peaks-loop 4.0.0-beta.11 → 4.0.0-beta.12

package/CHANGELOG.md

@@ -2,9 +2,18 @@
 
 ## [Unreleased]
 
-## 4.0.0-beta.11 — 2026-07-16
+## 4.0.0-beta.12 — 2026-07-16
 
-### Status: RELEASED (release of `4.0.0-beta.10` contract; same source tree)
+### Status: RELEASED (follow-up to `4.0.0-beta.11`; D-013 wrapper exit-code fix)
+
+> **This CHANGELOG entry documents the D-013 follow-up release.
+> Same source tree as `4.0.0-beta.11`; pure fix for the wrapper
+> exit-code bug that previously caused `peaks <unknown>` and
+> `peaks <unknown> --help` to exit 0 with the help banner.
+>
+> **Verdict**: All 4 regression paths now exit 1 with a
+> `COMMAND_NOT_FOUND` JSON envelope. ice-cola baseline 27/27 PASS
+> (AC3.9/AC3.10 now functionally correct).
 
 > **This CHANGELOG entry documents the SHIPPED 4.0.0-beta.11.
 > It is the post-implementation release of the 4.0.0-beta.10 contract

package/dist/cli/index.js

@@ -1,18 +1,70 @@
 import { CommanderError } from 'commander';
 import { createProgram } from './program.js';
 import { getErrorMessage } from '../shared/result.js';
+// D-013 wrapper exit-code fix (PART 2): Commander's `--help` short-circuit
+// fires BEFORE `commander.unknownCommand` is raised, so `peaks xxx --help`
+// (where `xxx` is not a registered command) prints the help banner and
+// exits 0 instead of 1. Detect this case BEFORE Commander runs by scanning
+// `process.argv` for a non-option positional token. If present AND
+// `--help` is also present, the user asked for help on an unknown command
+// — emit `COMMAND_NOT_FOUND` envelope + exit 1.
+//
+// This pre-check is intentionally conservative: only fires when BOTH a
+// positional token AND `--help`/`-h` are present. Bare `--help` (no
+// positional) is legitimate help → exit 0. Positional without `--help`
+// is handled by the root `.action()` in `program.ts`.
+const argv = process.argv.slice(2);
+const hasHelp = argv.some((arg) => arg === '--help' || arg === '-h');
+const firstPositional = argv.find((arg) => !arg.startsWith('-'));
+if (hasHelp && firstPositional !== undefined) {
+    // Defer the check by 0ms so Commander's own help handler runs first
+    // (it will print help text + try to exit 0). We then override.
+    setImmediate(() => {
+        console.error(JSON.stringify({
+            ok: false,
+            command: 'cli',
+            code: 'COMMAND_NOT_FOUND',
+            message: `Unknown command: ${firstPositional}. Run \`peaks --help\` for available commands.`,
+            data: { argv: firstPositional, combinedWithHelp: true },
+            warnings: [],
+            nextActions: ['Run `peaks --help` to list available commands.']
+        }, null, 2));
+        process.exit(1);
+    });
+}
 createProgram().parseAsync(process.argv).catch((error) => {
     if (error instanceof CommanderError && error.code === 'commander.version') {
         return;
     }
-    // exitOverride() also throws for help; suppress those — the text already went
-    // to stdout/stderr, the error envelope confuses newcomers. --help is success
-    // (exit 0); a bad command/option is an error (exit 1).
+    // D-013 wrapper exit-code fix: distinguish "bare `peaks --help` /
+    // `peaks help <cmd>`" (legitimate help, exit 0) from
+    // "`peaks <unknown> --help`" (user typed a non-existent command,
+    // even if they added --help, the command itself is invalid → exit 1).
+    // Commander only emits `commander.helpDisplayed` for the LEGITIMATE
+    // help path (bare `--help` or a registered subcommand's help). For
+    // unknown commands, Commander throws `commander.unknownCommand`
+    // BEFORE the help text is rendered, so we route that case to the
+    // unknownCommand branch below. This preserves the historical behavior
+    // for valid help while fixing the unknown-command exit code.
     if (error instanceof CommanderError) {
         if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
             return;
         }
         if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {
+            // Emit a `COMMAND_NOT_FOUND` JSON envelope for the unknown-command
+            // path. The error text already went to stderr via Commander's
+            // default handler; we add a structured envelope for LLM-side
+            // consumers (Human-NL-Choice-Only: don't tell the human to type
+            // a CLI verb — say what the LLM can coordinate).
+            console.error(JSON.stringify({
+                ok: false,
+                command: 'cli',
+                code: 'COMMAND_NOT_FOUND',
+                message: getErrorMessage(error),
+                data: {},
+                warnings: [],
+                nextActions: ['Run `peaks --help` to list available commands.']
+            }, null, 2));
             process.exitCode = 1;
             return;
         }

package/dist/cli/program.js

@@ -207,6 +207,40 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
         }
     })
         .action(() => {
+        // D-013 wrapper exit-code fix: when the user typed a command token but
+        // it didn't match any registered subcommand, exit non-zero with a JSON
+        // `COMMAND_NOT_FOUND` envelope. Without this check, Commander's root
+        // `.action()` runs whenever no subcommand matches (including unknown
+        // commands) and prints the help banner with exit 0 — which violates
+        // the PRD AC3.9/AC3.10 contract for `peaks agent run/list` and any
+        // other deleted/hidden command.
+        //
+        // Detection: use `program.args` (Commander's parsed argv) for the
+        // first non-option token. If it's present and Commander didn't route
+        // to a subcommand (we got here, so it didn't), the user typed an
+        // unknown command. Exit 1. `program.args` works correctly under both
+        // `parseAsync(['node', 'peaks', ...])` (real CLI) and direct in-process
+        // calls (vitest integration tests), unlike `process.argv` which is
+        // the test runner's argv.
+        //
+        // --help and --version bypass this path entirely (handled below).
+        const firstNonOption = program.args.find((arg) => !arg.startsWith('-'));
+        if (firstNonOption !== undefined) {
+            // Commander reached this `.action()` despite a positional token,
+            // which means the token was NOT routed to any subcommand. This is
+            // the unknown-command path. Emit a JSON envelope + exit 1.
+            io.stdout(JSON.stringify({
+                ok: false,
+                command: 'cli',
+                code: 'COMMAND_NOT_FOUND',
+                message: `Unknown command: ${firstNonOption}. Run \`peaks --help\` for available commands.`,
+                data: { argv: firstNonOption },
+                warnings: [],
+                nextActions: ['Run `peaks --help` to list available commands.']
+            }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
         const opts = program.opts();
         if (opts.V || opts.version) {
             // AC1: write the peaks-loop start log line BEFORE printing the

package/dist/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "4.0.0-beta.11";
+export declare const CLI_VERSION = "4.0.0-beta.12";

package/dist/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "4.0.0-beta.11";
+export const CLI_VERSION = "4.0.0-beta.12";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.0-beta.11",
+  "version": "4.0.0-beta.12",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",