fix(cli): usage errors emit the JSON envelope under --json

CliUsageError returned before the jsonRequested check, printing styled
help to stdout. Usage errors now emit {ok:false, error:{code:E_USAGE}}
with the message on stderr; error handling extracted to a helper.
From PR review.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: roodboi

src/cli/run.ts

@@ -1,6 +1,7 @@
 import { cancel } from "@clack/prompts";
 import {
   emitCliResult,
+  errorResult,
   errorResultFromUnknown,
   HackCliError,
 } from "../lib/cli-result.ts";
@@ -104,29 +105,50 @@ export async function runCli(argv: readonly string[]): Promise<number> {
       },
     });
   } catch (error: unknown) {
-    if (error instanceof CliUsageError) {
-      logger.error({ message: error.message });
-      await printHelpForPath(CLI_SPEC, []);
-      return 1;
-    }
+    return await handleRunCliError({ error, jsonRequested });
+  }
+}
 
+/**
+ * Maps a top-level CLI failure to its exit path. Under `--json`, stdout
+ * stays a single parseable envelope for every error class (usage errors
+ * included — they emit E_USAGE and skip the printed help); the human-readable
+ * message still reaches stderr.
+ */
+async function handleRunCliError(opts: {
+  readonly error: unknown;
+  readonly jsonRequested: boolean;
+}): Promise<number> {
+  const { error, jsonRequested } = opts;
+  if (error instanceof CliUsageError) {
     if (jsonRequested) {
-      emitCliResult({ result: errorResultFromUnknown({ error }) });
+      emitCliResult({
+        result: errorResult({ code: "E_USAGE", message: error.message }),
+      });
+      logger.error({ message: error.message });
       return 1;
     }
+    logger.error({ message: error.message });
+    await printHelpForPath(CLI_SPEC, []);
+    return 1;
+  }
 
-    if (error instanceof HackCliError) {
-      logger.error({ message: `${error.code}: ${error.message}` });
-      return 1;
-    }
+  if (jsonRequested) {
+    emitCliResult({ result: errorResultFromUnknown({ error }) });
+    return 1;
+  }
 
-    const message = error instanceof Error ? error.message : "Unknown error";
-    cancel(message);
-    if (error instanceof Error && error.stack) {
-      logger.error({ message: error.stack });
-    }
+  if (error instanceof HackCliError) {
+    logger.error({ message: `${error.code}: ${error.message}` });
     return 1;
   }
+
+  const message = error instanceof Error ? error.message : "Unknown error";
+  cancel(message);
+  if (error instanceof Error && error.stack) {
+    logger.error({ message: error.stack });
+  }
+  return 1;
 }
 
 /**

src/lib/cli-result.ts

@@ -25,6 +25,7 @@ export type HackErrorCode =
   | "E_ENV_KEY_MISSING"
   | "E_PERMISSION"
   | "E_INTERACTIVE_REQUIRED"
+  | "E_USAGE"
   | "E_UNEXPECTED";
 
 export type CliResultError = {

tests/lifecycle-json.test.ts

@@ -99,6 +99,23 @@ for (const action of ["up", "down", "restart"] as const) {
   });
 }
 
+test("usage errors under --json emit an E_USAGE envelope instead of help text", async () => {
+  const result = await runCliWithCapturedOutput([
+    "up",
+    "--json",
+    "--definitely-not-a-flag",
+  ]);
+
+  expect(result.exitCode).toBe(1);
+  const parsed = JSON.parse(result.stdout) as {
+    ok: boolean;
+    error?: { code: string; message: string };
+  };
+  expect(parsed.ok).toBe(false);
+  expect(parsed.error?.code).toBe("E_USAGE");
+  expect(result.stdout).not.toContain("Usage:");
+});
+
 async function runCliWithCapturedOutput(
   args: readonly string[]
 ): Promise<CapturedRunResult> {