feat: add structured error formatting with codes and hints (#18)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: gnapse

src/__tests__/output.test.ts

@@ -1,5 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { getOutputOptions, outputItem, outputList } from "../lib/output.js";
+import {
+	formatError,
+	getOutputOptions,
+	outputItem,
+	outputList,
+} from "../lib/output.js";
 
 describe("output", () => {
 	let logs: string[];
@@ -52,4 +57,37 @@ describe("output", () => {
 			},
 		);
 	});
+
+	describe("formatError", () => {
+		it("formats error with code and message", () => {
+			const result = formatError("TEST_ERROR", "Something went wrong");
+			expect(result).toContain("Error: TEST_ERROR");
+			expect(result).toContain("Something went wrong");
+		});
+
+		it("formats error with hints", () => {
+			const result = formatError("TEST_ERROR", "Something went wrong", [
+				"Try this",
+				"Or try that",
+			]);
+			expect(result).toContain("Error: TEST_ERROR");
+			expect(result).toContain("Something went wrong");
+			expect(result).toContain("  - Try this");
+			expect(result).toContain("  - Or try that");
+		});
+
+		it("formats error with empty hints array", () => {
+			const result = formatError("TEST_ERROR", "Something went wrong", []);
+			expect(result).toContain("Error: TEST_ERROR");
+			expect(result).toContain("Something went wrong");
+			expect(result).not.toContain("  - ");
+		});
+
+		it("formats error without hints", () => {
+			const result = formatError("NO_HINTS", "No hints provided");
+			expect(result).toContain("Error: NO_HINTS");
+			expect(result).toContain("No hints provided");
+			expect(result).not.toContain("  - ");
+		});
+	});
 });

src/commands/auth.ts

@@ -9,6 +9,7 @@ import {
 	getTokenSource,
 	saveConfig,
 } from "../lib/auth.js";
+import { formatError } from "../lib/output.js";
 
 interface TeamInfo {
 	name: string;
@@ -59,7 +60,12 @@ export function registerAuthCommand(program: Command): void {
 		.action(async () => {
 			const token = await promptSecret("API token: ");
 			if (!token.trim()) {
-				console.error(chalk.red("Token is required."));
+				console.error(
+					formatError("AUTH_TOKEN_REQUIRED", "API token is required.", [
+						"Enter your API token from Outline settings",
+						"Find it at Settings → API Tokens",
+					]),
+				);
 				process.exit(1);
 			}
 
@@ -104,8 +110,15 @@ export function registerAuthCommand(program: Command): void {
 				console.log(`User: ${data.user.name} (${data.user.email})`);
 			} catch (err) {
 				console.error(
-					chalk.red("Could not fetch auth info:"),
-					(err as Error).message,
+					formatError(
+						"AUTH_VERIFICATION_FAILED",
+						`Could not fetch auth info: ${(err as Error).message}`,
+						[
+							"Check that your API token is valid",
+							"Verify the base URL is correct",
+							"Run 'ol auth login' to re-authenticate",
+						],
+					),
 				);
 				process.exit(1);
 			}

src/commands/collection.ts

@@ -1,7 +1,12 @@
 import chalk from "chalk";
 import type { Command } from "commander";
 import { apiRequest } from "../lib/api.js";
-import { getOutputOptions, outputItem, outputList } from "../lib/output.js";
+import {
+	formatError,
+	getOutputOptions,
+	outputItem,
+	outputList,
+} from "../lib/output.js";
 
 interface Collection {
 	id: string;
@@ -122,7 +127,13 @@ export function registerCollectionCommand(program: Command): void {
 		.option("--confirm", "Skip confirmation")
 		.action(async (id: string, opts) => {
 			if (!opts.confirm) {
-				console.error(chalk.red("Use --confirm to delete."));
+				console.error(
+					formatError(
+						"CONFIRMATION_REQUIRED",
+						"Delete operation requires confirmation.",
+						["Use --confirm flag to proceed with deletion"],
+					),
+				);
 				process.exit(1);
 			}
 			await apiRequest("collections.delete", { id });

src/commands/document.ts

@@ -5,7 +5,12 @@ import type { Command } from "commander";
 import { apiRequest } from "../lib/api.js";
 import { getBaseUrl } from "../lib/auth.js";
 import { renderMarkdown } from "../lib/markdown.js";
-import { getOutputOptions, outputItem, outputList } from "../lib/output.js";
+import {
+	formatError,
+	getOutputOptions,
+	outputItem,
+	outputList,
+} from "../lib/output.js";
 
 interface Document {
 	id: string;
@@ -226,7 +231,13 @@ export function registerDocumentCommand(program: Command): void {
 		.option("--confirm", "Skip confirmation")
 		.action(async (id: string, opts) => {
 			if (!opts.confirm) {
-				console.error(chalk.red("Use --confirm to delete."));
+				console.error(
+					formatError(
+						"CONFIRMATION_REQUIRED",
+						"Delete operation requires confirmation.",
+						["Use --confirm flag to proceed with deletion"],
+					),
+				);
 				process.exit(1);
 			}
 			await apiRequest("documents.delete", { id: resolveId(id) });

src/commands/skill.ts

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import type { Command } from "commander";
+import { formatError } from "../lib/output.js";
 import {
 	getInstaller,
 	listAgents,
@@ -26,8 +27,10 @@ export function registerSkillCommand(program: Command): void {
 			if (!installer) {
 				const available = listAgents().join(", ");
 				console.error(
-					chalk.red(`Unknown agent: ${agent}`),
-					chalk.dim(`\nAvailable: ${available}`),
+					formatError("UNKNOWN_AGENT", `Unknown agent: ${agent}`, [
+						`Available agents: ${available}`,
+						"Run 'ol skill list' to see all agents",
+					]),
 				);
 				process.exit(1);
 			}
@@ -56,8 +59,10 @@ export function registerSkillCommand(program: Command): void {
 			if (!installer) {
 				const available = listAgents().join(", ");
 				console.error(
-					chalk.red(`Unknown agent: ${agent}`),
-					chalk.dim(`\nAvailable: ${available}`),
+					formatError("UNKNOWN_AGENT", `Unknown agent: ${agent}`, [
+						`Available agents: ${available}`,
+						"Run 'ol skill list' to see all agents",
+					]),
 				);
 				process.exit(1);
 			}

src/lib/output.ts

@@ -74,3 +74,18 @@ function pick<T extends object>(obj: T, keys: (keyof T)[]): Partial<T> {
 	}
 	return result;
 }
+
+export function formatError(
+	code: string,
+	message: string,
+	hints?: string[],
+): string {
+	const lines = [`Error: ${code}`, message];
+	if (hints && hints.length > 0) {
+		lines.push("");
+		for (const hint of hints) {
+			lines.push(`  - ${hint}`);
+		}
+	}
+	return chalk.red(lines.join("\n"));
+}