fix: preserve toolcraft error output format

Author: kamilio

packages/terminal-pilot/src/testing/testing.test.ts

@@ -106,8 +106,11 @@ describe("terminal-pilot CLI REPL runner", () => {
 
     const missing = await repl.run(["get-session", "-s", "S1", "--output", "json"]);
     expect(missing.exitCode).toBe(1);
-    expect(missing.stdout).toBe("");
-    expect(missing.stderr).toContain('Session "S1" was not found.');
+    expect(JSON.parse(missing.stdout)).toEqual({
+      level: "error",
+      message: 'Session "S1" was not found. No active sessions are available.'
+    });
+    expect(missing.stderr).toBe("");
   });
 });
 

packages/toolcraft/src/cli.test.ts

@@ -16,6 +16,7 @@ const loggerState = {
   success: [] as string[],
   warn: [] as string[],
   error: [] as string[],
+  errorOutputFormats: [] as Array<string | undefined>,
   resolved: [] as Array<{ label: string; value: string }>,
   errorResolved: [] as Array<{ label: string; value: string }>,
   message: [] as string[]
@@ -68,7 +69,10 @@ vi.mock("toolcraft-design", () => ({
     info: (message: string) => loggerState.info.push(message),
     success: (message: string) => loggerState.success.push(message),
     warn: (message: string) => loggerState.warn.push(message),
-    error: (message: string) => loggerState.error.push(message),
+    error: (message: string) => {
+      loggerState.errorOutputFormats.push(process.env.OUTPUT_FORMAT);
+      loggerState.error.push(message);
+    },
     resolved: (label: string, value: string) => loggerState.resolved.push({ label, value }),
     errorResolved: (label: string, value: string) =>
       loggerState.errorResolved.push({ label, value }),
@@ -249,6 +253,7 @@ function resetLoggerState(): void {
   loggerState.success.length = 0;
   loggerState.warn.length = 0;
   loggerState.error.length = 0;
+  loggerState.errorOutputFormats.length = 0;
   loggerState.resolved.length = 0;
   loggerState.errorResolved.length = 0;
   loggerState.message.length = 0;
@@ -2137,6 +2142,29 @@ describe("runCLI", () => {
     expect(process.exitCode).toBe(1);
   });
 
+  it("renders handler UserError messages inside the requested output format", async () => {
+    const deploy = defineCommand({
+      name: "deploy",
+      params: S.Object({}),
+      handler: async () => {
+        throw new UserError("Invalid input.");
+      }
+    });
+
+    const root = defineGroup({
+      name: "toolcraft",
+      children: [deploy]
+    });
+
+    process.argv = ["node", "toolcraft", "deploy", "--output", "json", "--yes"];
+
+    await runCLI(root);
+
+    expect(loggerState.error).toEqual(["Invalid input."]);
+    expect(loggerState.errorOutputFormats).toEqual(["json"]);
+    expect(process.exitCode).toBe(1);
+  });
+
   it("reports missing required secrets before running the handler", async () => {
     const handler = vi.fn(async () => null);
 

packages/toolcraft/src/cli.ts

@@ -2461,6 +2461,40 @@ function resolveOutput(resolvedFlags: ResolvedFlags): OutputMode {
   return "rich";
 }
 
+function resolveOutputFromArgv(argv: readonly string[]): OutputMode {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] ?? "";
+
+    if (token === "--json") {
+      return "json";
+    }
+    if (token === "--md" || token === "--markdown") {
+      return "md";
+    }
+    if (token === "--output") {
+      const value = argv[index + 1];
+      if (value === "rich" || value === "md" || value === "json") {
+        return value;
+      }
+      if (value === "markdown") {
+        return "md";
+      }
+      continue;
+    }
+    if (token.startsWith("--output=")) {
+      const value = token.slice("--output=".length);
+      if (value === "rich" || value === "md" || value === "json") {
+        return value;
+      }
+      if (value === "markdown") {
+        return "md";
+      }
+    }
+  }
+
+  return "rich";
+}
+
 const DESIGN_SYSTEM_OUTPUT_BY_MODE = {
   rich: "terminal",
   md: "markdown",
@@ -4545,100 +4579,103 @@ function renderHttpError(
   }
 }
 
-function handleRunError(
+async function handleRunError(
   error: unknown,
   options: {
     debugStackMode: DebugStackMode | undefined;
+    output: OutputMode;
     verbose: boolean;
     program?: CommanderCommand;
     argv?: readonly string[];
     rootUsageName: string;
     commandPath: string;
     userErrorPattern: "runtime-user" | "usage";
   }
-): void {
+): Promise<void> {
   const logger = createLogger();
 
-  if (error instanceof UserError) {
-    renderCliErrorPattern(
-      options.userErrorPattern === "usage"
-        ? {
-            kind: "usage",
-            message: error.message,
-            rootUsageName: options.rootUsageName,
-            commandPath: options.commandPath
-          }
-        : {
-            kind: "runtime-user",
-            message: error.message
-          }
-    );
-    return;
-  }
-
-  if (error instanceof Error && error.name === "ToolcraftBugError") {
-    renderCliErrorPattern({
-      kind: "toolcraft-bug",
-      error,
-      debugStackMode: options.debugStackMode
-    });
-    return;
-  }
-
-  if (error instanceof CommanderError) {
-    process.exitCode = error.exitCode;
-    if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
+  await withOutputFormat(options.output, async () => {
+    if (error instanceof UserError) {
+      renderCliErrorPattern(
+        options.userErrorPattern === "usage"
+          ? {
+              kind: "usage",
+              message: error.message,
+              rootUsageName: options.rootUsageName,
+              commandPath: options.commandPath
+            }
+          : {
+              kind: "runtime-user",
+              message: error.message
+            }
+      );
       return;
     }
-    if (error.code === "commander.unknownCommand") {
-      logger.error(
-        appendUsagePointer(
-          formatUnknownCommandError(error, options.program, options.argv ?? process.argv),
-          {
-            rootUsageName: options.rootUsageName,
-            commandPath: options.commandPath
-          }
-        )
-      );
+
+    if (error instanceof Error && error.name === "ToolcraftBugError") {
+      renderCliErrorPattern({
+        kind: "toolcraft-bug",
+        error,
+        debugStackMode: options.debugStackMode
+      });
       return;
     }
-    if (error.code === "commander.unknownOption") {
-      const argv = options.argv ?? process.argv;
+
+    if (error instanceof CommanderError) {
+      process.exitCode = error.exitCode;
+      if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
+        return;
+      }
+      if (error.code === "commander.unknownCommand") {
+        logger.error(
+          appendUsagePointer(
+            formatUnknownCommandError(error, options.program, options.argv ?? process.argv),
+            {
+              rootUsageName: options.rootUsageName,
+              commandPath: options.commandPath
+            }
+          )
+        );
+        return;
+      }
+      if (error.code === "commander.unknownOption") {
+        const argv = options.argv ?? process.argv;
+        logger.error(
+          appendUsagePointer(formatUnknownOptionError(error, options.program, argv), {
+            rootUsageName: options.rootUsageName,
+            commandPath:
+              options.commandPath.length > 0
+                ? options.commandPath
+                : findCurrentCommanderCommandPath(options.program, argv)
+          })
+        );
+        return;
+      }
       logger.error(
-        appendUsagePointer(formatUnknownOptionError(error, options.program, argv), {
+        appendUsagePointer(formatCommanderErrorMessage(error), {
           rootUsageName: options.rootUsageName,
           commandPath:
             options.commandPath.length > 0
               ? options.commandPath
-              : findCurrentCommanderCommandPath(options.program, argv)
+              : findCurrentCommanderCommandPath(options.program, options.argv ?? process.argv)
         })
       );
       return;
     }
-    logger.error(
-      appendUsagePointer(formatCommanderErrorMessage(error), {
-        rootUsageName: options.rootUsageName,
-        commandPath:
-          options.commandPath.length > 0
-            ? options.commandPath
-            : findCurrentCommanderCommandPath(options.program, options.argv ?? process.argv)
-      })
-    );
-    return;
-  }
 
-  if (isHttpErrorLike(error)) {
-    renderHttpError(error, options);
-    process.exitCode = 1;
-    return;
-  }
+    if (isHttpErrorLike(error)) {
+      renderHttpError(error, options);
+      process.exitCode = 1;
+      return;
+    }
 
-  const message = error instanceof Error ? error.message : String(error);
-  renderCliErrorPattern({
-    kind: "unexpected",
-    message,
-    stack: error instanceof Error ? error.stack : undefined,
-    debugStackMode: options.debugStackMode
+    const message = error instanceof Error ? error.message : String(error);
+    renderCliErrorPattern({
+      kind: "unexpected",
+      message,
+      stack: error instanceof Error ? error.stack : undefined,
+      debugStackMode: options.debugStackMode
+    });
   });
 }
 
@@ -5087,11 +5124,15 @@ export async function runCLI<TServices extends object = Record<string, unknown>>
       process.stderr.write(`Saved error report to ${report.displayPath}\n`);
     }
 
-    handleRunError(error, {
+    await handleRunError(error, {
       debugStackMode:
         resolvedFlags !== undefined
           ? resolveDebugStackMode(resolvedFlags.debug)
           : getDebugStackModeFromArgv(process.argv),
+      output:
+        resolvedFlags !== undefined
+          ? resolveOutput(resolvedFlags)
+          : resolveOutputFromArgv(process.argv),
       verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : process.argv.includes("--verbose"),
       program,
       argv: process.argv,