fix: --help shows usage instead of validation error

src/cli/commands/audit.ts

@@ -2,8 +2,14 @@ import * as path from "path";
 import { ContractLoader } from "../../infrastructure/filesystem/ContractLoader";
 import { CForgePromptGenerator } from "../../infrastructure/cforge/CForgePromptGenerator";
 import { GovernanceAuditor } from "../../application/use-cases/GovernanceAuditor";
+import { USAGE_AUDIT } from "../validation";
+
+export async function auditCommand(flags: string[] = []): Promise<void> {
+  if (flags.includes("--help")) {
+    console.log(USAGE_AUDIT);
+    process.exit(0);
+  }
 
-export async function auditCommand(): Promise<void> {
   const workingDir = process.cwd();
   const contractsDir = path.join(workingDir, "contracts");
 

src/cli/commands/plan.ts

@@ -17,6 +17,11 @@ function prompt(question: string): Promise<string> {
 }
 
 export async function planCommand(prdFile: string): Promise<void> {
+  if (prdFile === "--help") {
+    console.log(USAGE_PLAN);
+    process.exit(0);
+  }
+
   const presenceErr = validatePresence(prdFile, USAGE_PLAN);
   if (presenceErr) {
     console.error(presenceErr);

src/cli/commands/release.ts

@@ -4,6 +4,11 @@ import { loadContext } from "../utils/loadContext";
 import { validatePresence, USAGE_RELEASE } from "../validation";
 
 export async function releaseCommand(milestoneIdStr: string, version: string): Promise<void> {
+  if (milestoneIdStr === "--help" || version === "--help") {
+    console.log(USAGE_RELEASE);
+    process.exit(0);
+  }
+
   const presenceErr = validatePresence(milestoneIdStr, USAGE_RELEASE) || validatePresence(version, USAGE_RELEASE);
   if (presenceErr) {
     console.error(presenceErr);

src/cli/commands/verify.ts

@@ -5,6 +5,11 @@ import { loadContext } from "../utils/loadContext";
 import { validatePresence, validateNumericIssueNumber, USAGE_VERIFY } from "../validation";
 
 export async function verifyCommand(issueNumberStr: string): Promise<void> {
+  if (issueNumberStr === "--help") {
+    console.log(USAGE_VERIFY);
+    process.exit(0);
+  }
+
   const presenceErr = validatePresence(issueNumberStr, USAGE_VERIFY);
   if (presenceErr) {
     console.error(presenceErr);

src/cli/index.ts

@@ -30,6 +30,11 @@ export async function main(): Promise<void> {
     process.exit(0);
   }
 
+  if (command === "--help" || command === "-h") {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
   if (command === "--version" || command === "-v") {
     console.log(getVersion());
     process.exit(0);
@@ -52,7 +57,7 @@ export async function main(): Promise<void> {
       await chatCommand();
       break;
     case "audit":
-      await auditCommand();
+      await auditCommand(args);
       break;
     default:
       console.error(`Unknown command: ${command}\n`);

tests/cli/commands/help.test.ts

@@ -0,0 +1,112 @@
+// Mock @octokit/rest which uses ESM and cannot be loaded by ts-jest directly
+jest.mock("@octokit/rest", () => ({ Octokit: jest.fn() }));
+
+import { implementCommand } from "../../../src/cli/commands/implement";
+import { planCommand } from "../../../src/cli/commands/plan";
+import { verifyCommand } from "../../../src/cli/commands/verify";
+import { releaseCommand } from "../../../src/cli/commands/release";
+import { auditCommand } from "../../../src/cli/commands/audit";
+import {
+  USAGE_IMPLEMENT,
+  USAGE_VERIFY,
+  USAGE_RELEASE,
+  USAGE_PLAN,
+  USAGE_AUDIT,
+} from "../../../src/cli/validation";
+
+describe("--help flag handling", () => {
+  let mockExit: jest.SpyInstance;
+  let mockLog: jest.SpyInstance;
+  let mockError: jest.SpyInstance;
+
+  beforeEach(() => {
+    mockExit = jest.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as never);
+    mockLog = jest.spyOn(console, "log").mockImplementation(() => {});
+    mockError = jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    mockExit.mockRestore();
+    mockLog.mockRestore();
+    mockError.mockRestore();
+  });
+
+  describe("implement --help", () => {
+    it("prints usage and exits with code 0 when --help is the first argument", async () => {
+      await expect(implementCommand("--help", [])).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_IMPLEMENT);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("prints usage and exits with code 0 when --help is in flags", async () => {
+      await expect(implementCommand(undefined as unknown as string, ["--help"])).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_IMPLEMENT);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("does not exit with error code when --help is used", async () => {
+      await expect(implementCommand("--help", [])).rejects.toThrow("process.exit:0");
+      expect(mockExit).not.toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe("plan --help", () => {
+    it("prints usage and exits with code 0 when --help is passed", async () => {
+      await expect(planCommand("--help")).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_PLAN);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("does not exit with error code when --help is used", async () => {
+      await expect(planCommand("--help")).rejects.toThrow("process.exit:0");
+      expect(mockExit).not.toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe("verify --help", () => {
+    it("prints usage and exits with code 0 when --help is passed", async () => {
+      await expect(verifyCommand("--help")).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_VERIFY);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("does not exit with error code when --help is used", async () => {
+      await expect(verifyCommand("--help")).rejects.toThrow("process.exit:0");
+      expect(mockExit).not.toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe("release --help", () => {
+    it("prints usage and exits with code 0 when --help is passed as milestone", async () => {
+      await expect(releaseCommand("--help", "1.0.0")).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_RELEASE);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("prints usage and exits with code 0 when --help is passed as version", async () => {
+      await expect(releaseCommand("1", "--help")).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_RELEASE);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("does not exit with error code when --help is used", async () => {
+      await expect(releaseCommand("--help", "1.0.0")).rejects.toThrow("process.exit:0");
+      expect(mockExit).not.toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe("audit --help", () => {
+    it("prints usage and exits with code 0 when --help is passed", async () => {
+      await expect(auditCommand(["--help"])).rejects.toThrow("process.exit:0");
+      expect(mockLog).toHaveBeenCalledWith(USAGE_AUDIT);
+      expect(mockExit).toHaveBeenCalledWith(0);
+    });
+
+    it("does not exit with error code when --help is used", async () => {
+      await expect(auditCommand(["--help"])).rejects.toThrow("process.exit:0");
+      expect(mockExit).not.toHaveBeenCalledWith(1);
+    });
+  });
+});

tests/cli/index.test.ts

@@ -0,0 +1,55 @@
+// Mock @octokit/rest which uses ESM and cannot be loaded by ts-jest directly
+jest.mock("@octokit/rest", () => ({ Octokit: jest.fn() }));
+jest.mock("../../src/infrastructure/github/OctokitGitHubClient");
+jest.mock("../../src/infrastructure/cforge/CForgePromptGenerator");
+jest.mock("../../src/infrastructure/claude/ClaudeCodeRunner");
+jest.mock("../../src/infrastructure/filesystem/ContractLoader");
+
+import { main, USAGE } from "../../src/cli/index";
+
+describe("global --help", () => {
+  let originalArgv: string[];
+  let mockExit: jest.SpyInstance;
+  let mockLog: jest.SpyInstance;
+  let mockError: jest.SpyInstance;
+
+  beforeEach(() => {
+    originalArgv = process.argv;
+    mockExit = jest.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as never);
+    mockLog = jest.spyOn(console, "log").mockImplementation(() => {});
+    mockError = jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    mockExit.mockRestore();
+    mockLog.mockRestore();
+    mockError.mockRestore();
+  });
+
+  it("displays global usage and exits with code 0 when --help flag is provided", async () => {
+    process.argv = ["node", "cforge-dev", "--help"];
+    await expect(main()).rejects.toThrow("process.exit:0");
+    expect(mockLog).toHaveBeenCalledWith(USAGE);
+    expect(mockExit).toHaveBeenCalledWith(0);
+  });
+
+  it("lists all available commands in global help output", async () => {
+    process.argv = ["node", "cforge-dev", "--help"];
+    await expect(main()).rejects.toThrow("process.exit:0");
+    const logOutput = mockLog.mock.calls.map((call: unknown[]) => call[0]).join("");
+    expect(logOutput).toContain("plan");
+    expect(logOutput).toContain("implement");
+    expect(logOutput).toContain("verify");
+    expect(logOutput).toContain("release");
+    expect(logOutput).toContain("audit");
+  });
+
+  it("does not exit with error code when --help is used", async () => {
+    process.argv = ["node", "cforge-dev", "--help"];
+    await expect(main()).rejects.toThrow("process.exit:0");
+    expect(mockExit).not.toHaveBeenCalledWith(1);
+  });
+});