fix(cli): preserve usage code for lifecycle json

Author: roodboi

src/commands/project.ts

@@ -711,6 +711,13 @@ function emitLifecycleResult(opts: {
   return opts.exitCode;
 }
 
+function buildLifecycleJsonErrorResult(opts: { readonly error: unknown }) {
+  if (opts.error instanceof CliUsageError) {
+    return errorResult({ code: "E_USAGE", message: opts.error.message });
+  }
+  return errorResultFromUnknown({ error: opts.error });
+}
+
 /**
  * Envelope for lifecycle actions that were routed to a remote node — the
  * remote runner owns per-service detail, so the payload reports the routing
@@ -5303,7 +5310,7 @@ async function handleUp({
     return await runUpCommand({ ctx, args, json: true, startedAtMs });
   } catch (error: unknown) {
     return emitLifecycleResult({
-      result: errorResultFromUnknown({ error }),
+      result: buildLifecycleJsonErrorResult({ error }),
       exitCode: 1,
     });
   }
@@ -5628,7 +5635,7 @@ async function handleDown({
       });
     }
     return emitLifecycleResult({
-      result: errorResultFromUnknown({ error }),
+      result: buildLifecycleJsonErrorResult({ error }),
       exitCode: 1,
     });
   }
@@ -6026,7 +6033,7 @@ async function handleRestart({
       });
     }
     return emitLifecycleResult({
-      result: errorResultFromUnknown({ error }),
+      result: buildLifecycleJsonErrorResult({ error }),
       exitCode: 1,
     });
   }

tests/lifecycle-json.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -116,6 +116,78 @@ test("usage errors under --json emit an E_USAGE envelope instead of help text",
   expect(result.stdout).not.toContain("Usage:");
 });
 
+for (const action of ["up", "down", "restart"] as const) {
+  test(`${action} --json preserves E_USAGE for a detached linked worktree`, async () => {
+    const worktreeRoot = await createDetachedWorktreeFixture();
+    const result = await runCliWithCapturedOutput([
+      action,
+      "--json",
+      "--path",
+      worktreeRoot,
+    ]);
+
+    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(parsed.error?.message).toContain("Detached linked worktree");
+    expect(parsed.error?.message).toContain("--branch <name>");
+  });
+}
+
+async function createDetachedWorktreeFixture(): Promise<string> {
+  if (!tempDir) {
+    throw new Error("Missing temp directory");
+  }
+
+  const primaryRoot = join(tempDir, "repo-primary");
+  const hackDir = join(primaryRoot, ".hack");
+  await mkdir(hackDir, { recursive: true });
+  await writeFile(
+    join(hackDir, "hack.config.json"),
+    `${JSON.stringify({ name: "json-worktree", dev_host: "json-worktree.hack" }, null, 2)}\n`
+  );
+  await writeFile(
+    join(hackDir, "docker-compose.yml"),
+    ["services:", "  api:", "    image: alpine:3.20", ""].join("\n")
+  );
+  await writeFile(join(primaryRoot, "README.md"), "# fixture\n");
+
+  runGit({ cwd: primaryRoot, args: ["init", "-b", "main"] });
+  runGit({
+    cwd: primaryRoot,
+    args: ["config", "user.email", "test@example.com"],
+  });
+  runGit({ cwd: primaryRoot, args: ["config", "user.name", "Test User"] });
+  runGit({ cwd: primaryRoot, args: ["add", "."] });
+  runGit({ cwd: primaryRoot, args: ["commit", "-m", "init"] });
+
+  const worktreeRoot = join(tempDir, "repo-worktree");
+  runGit({
+    cwd: primaryRoot,
+    args: ["worktree", "add", "-b", "feature/json", worktreeRoot],
+  });
+  runGit({ cwd: worktreeRoot, args: ["checkout", "--detach"] });
+  return worktreeRoot;
+}
+
+function runGit(opts: {
+  readonly cwd: string;
+  readonly args: readonly string[];
+}): void {
+  const result = Bun.spawnSync(["git", "-C", opts.cwd, ...opts.args], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(Buffer.from(result.stderr).toString("utf8"));
+  }
+}
+
 async function runCliWithCapturedOutput(
   args: readonly string[]
 ): Promise<CapturedRunResult> {