cliguard 0.3.0 → 0.4.0

package/README.md

@@ -23,7 +23,7 @@ The first line fails your CI. The second one doesn't - `--dry-run` is new and op
 npm install --save-dev cliguard
 ```
 
-Your CLI's entry file needs to **export** its Commander `Command` instance instead of calling `.parse()` itself:
+Your CLI's entry file should **export** its Commander `Command` instance instead of calling `.parse()` itself - the cleanest way to adopt cliguard, since it never risks running any of your CLI's real logic:
 
 ```js
 // bin/cli.js
@@ -56,6 +56,16 @@ npx cliguard init ./bin/cli.js --adapter cac
 
 `cac` itself is an optional dependency of cliguard - only installed if you actually use `--adapter cac`.
 
+### Entry files that build the CLI lazily
+
+Not every real CLI exports its instance - plenty build it inside a function that only runs when something actually calls it, or just never had a reason to export it. Pointing cliguard straight at a file like that would fail with "no instance found" under the rule above alone.
+
+So when the direct export lookup finds nothing, cliguard tries one more thing automatically, no flag needed: it patches the exact copy of `commander`/`cac` your entry file will itself `require()`, so any `new Command()` (or CAC's `cac()`) call anywhere in your file's own top-level code is captured - even though nothing was ever exported. This covers most real CLIs, since even ones that never bother exporting still build (and often `.parse()`) at the top of their own file as a matter of course.
+
+It can't reach an instance built strictly *inside* a function that's only invoked later, never automatically at load time (a `main()` some other file calls, not the file cliguard is pointed at) - there's no safe, generic way for cliguard to know which function to call or with what arguments. For that shape, write a small wrapper file that reaches into the target's own internals to get (or construct) the instance, and point cliguard at the wrapper instead of the original entry file. The exact shape of that wrapper is inherently project-specific - it's standing in for whatever that project's own entry point would otherwise do - but the command stays the same either way: `cliguard init ./your-wrapper.mjs`.
+
+Either way, if the target's top-level code has its own real side effects when loaded - a `.parse()` call that matches a real command and runs it, a network request, spawning a process - running cliguard against it (directly or through a wrapper) triggers those too, exactly as `node ./bin/cli.js` would. cliguard neutralizes one specific danger this creates (a target calling `process.exit()` can't kill cliguard's own process or override its exit code), but doesn't sandbox anything else - see [SECURITY.md](./SECURITY.md).
+
 Then:
 
 ```sh

package/dist/adapters/cac.adapter.d.ts

@@ -19,8 +19,27 @@ export declare class CacAdapter implements CliAdapter {
     readonly id = "cac";
     extract(entryPath: string): Promise<Contract>;
     private loadCac;
+    /** Among every CAC instance captured during construction, the one that looks most like the real, fully-built root CLI. */
+    private pickBestCandidate;
     /** Handles `export default`, `module.exports = cli`, and named exports. */
     private findCac;
+    /**
+     * Structural check, not `instanceof CAC` - see CommanderAdapter's
+     * identical-purpose `looksLikeCommand` for why: the target project's
+     * own `cac` install is almost always a separate copy from any `cac`
+     * cliguard itself could resolve, even at the identical version, so
+     * `instanceof` fails by construction. This also removes the only
+     * reason this adapter ever needed `cac` installed in cliguard's own
+     * environment - `require("cac")` from cliguard's own (often
+     * `npx`-isolated) location previously gated every use of this adapter
+     * behind a package cliguard could rarely actually see, even when the
+     * target project had it. The target file's own `require("cac")` /
+     * `import("cac")`, resolved from *its* location by `loadModule`, is
+     * the only place `cac` needs to be installed now - and if it isn't,
+     * that failure surfaces below via the real load error, same as any
+     * other missing dependency.
+     */
+    private looksLikeCac;
     /**
      * CAC's root instance carries global options (`cli.option(...)`,
      * exposed via `globalCommand`) but no description of its own and no

package/dist/adapters/cac.adapter.js

@@ -1,24 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacAdapter = void 0;
+const construction_capture_1 = require("./construction-capture");
 const load_module_1 = require("./load-module");
-/**
- * `cac` is an optional peer dependency (see package.json) - a project
- * whose target CLI is built with Commander has no reason to install it.
- * Loaded lazily, only when this adapter actually runs, so importing this
- * file (which `bin.ts` does unconditionally, to register every adapter)
- * never requires `cac` to be present.
- */
-function loadCacClass() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports -- deliberate lazy load of an optional peer dependency
-        const cacModule = require("cac");
-        return cacModule.CAC;
-    }
-    catch {
-        throw new Error("cliguard: the CAC adapter needs the `cac` package. Run `npm install --save-dev cac`.");
-    }
-}
 /**
  * Extracts a Contract from a target file that exports a `cac()` `CAC`
  * instance. Never parses --help output - every field comes straight from
@@ -48,37 +32,82 @@ class CacAdapter {
         };
     }
     async loadCac(entryPath) {
-        const CacClass = loadCacClass();
+        // See CommanderAdapter.loadCommand's identical block: patched before
+        // the target loads, so a `new CAC()` or `cac()` call anywhere in its
+        // own top-level code gets captured even if the target never exports
+        // the result.
+        const captured = (0, construction_capture_1.captureConstructions)("cac", entryPath, "CAC", ["cac"]);
         const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
-        const cli = this.findCac(viaImport.moduleExports, CacClass) ??
-            this.findCac(viaRequire.moduleExports, CacClass);
+        const cli = this.findCac(viaImport.moduleExports) ??
+            this.findCac(viaRequire.moduleExports) ??
+            this.pickBestCandidate(captured);
         if (cli)
             return cli;
         // See CommanderAdapter's identical block for why both real errors -
         // not a swallowed, generic guess - matter here.
         throw new Error(`cliguard: no CAC instance found in "${entryPath}". ` +
             "Export it as `export default cli`, `module.exports = cli`, " +
-            "or a named export (e.g. `export const cli = cac()`).\n" +
+            "or a named export (e.g. `export const cli = cac()`). If the file builds its " +
+            "CAC instance inside a function that only runs when something calls it (never " +
+            "at the top level), point cliguard at a small wrapper file that calls that " +
+            "function and exports the result instead - see the README's \"Entry files that " +
+            'build the CLI lazily" section.\n' +
             `  import() failed: ${viaImport.error ?? "module loaded, but exported no CAC instance"}\n` +
             `  require() failed: ${viaRequire.error ?? "module loaded, but exported no CAC instance"}`);
     }
+    /** Among every CAC instance captured during construction, the one that looks most like the real, fully-built root CLI. */
+    pickBestCandidate(candidates) {
+        const valid = candidates.filter((candidate) => this.looksLikeCac(candidate));
+        if (valid.length === 0)
+            return undefined;
+        return valid.reduce((best, candidate) => candidate.commands.length + candidate.globalCommand.options.length >
+            best.commands.length + best.globalCommand.options.length
+            ? candidate
+            : best);
+    }
     /** Handles `export default`, `module.exports = cli`, and named exports. */
-    findCac(moduleExports, CacClass) {
-        if (moduleExports instanceof CacClass) {
+    findCac(moduleExports) {
+        if (this.looksLikeCac(moduleExports)) {
             return moduleExports;
         }
         if (moduleExports && typeof moduleExports === "object") {
             const exportsObject = moduleExports;
-            if (exportsObject.default instanceof CacClass) {
+            if (this.looksLikeCac(exportsObject.default)) {
                 return exportsObject.default;
             }
             for (const value of Object.values(exportsObject)) {
-                if (value instanceof CacClass)
+                if (this.looksLikeCac(value))
                     return value;
             }
         }
         return undefined;
     }
+    /**
+     * Structural check, not `instanceof CAC` - see CommanderAdapter's
+     * identical-purpose `looksLikeCommand` for why: the target project's
+     * own `cac` install is almost always a separate copy from any `cac`
+     * cliguard itself could resolve, even at the identical version, so
+     * `instanceof` fails by construction. This also removes the only
+     * reason this adapter ever needed `cac` installed in cliguard's own
+     * environment - `require("cac")` from cliguard's own (often
+     * `npx`-isolated) location previously gated every use of this adapter
+     * behind a package cliguard could rarely actually see, even when the
+     * target project had it. The target file's own `require("cac")` /
+     * `import("cac")`, resolved from *its* location by `loadModule`, is
+     * the only place `cac` needs to be installed now - and if it isn't,
+     * that failure surfaces below via the real load error, same as any
+     * other missing dependency.
+     */
+    looksLikeCac(value) {
+        if (!value || typeof value !== "object")
+            return false;
+        const candidate = value;
+        return (Array.isArray(candidate.commands) &&
+            typeof candidate.globalCommand === "object" &&
+            candidate.globalCommand !== null &&
+            typeof candidate.command === "function" &&
+            typeof candidate.parse === "function");
+    }
     /**
      * CAC's root instance carries global options (`cli.option(...)`,
      * exposed via `globalCommand`) but no description of its own and no

package/dist/adapters/commander.adapter.d.ts

@@ -11,8 +11,25 @@ export declare class CommanderAdapter implements CliAdapter {
     readonly id = "commander";
     extract(entryPath: string): Promise<Contract>;
     private loadCommand;
+    /** Among every Command captured during construction, the one that looks most like the real, fully-built root program - flags on this file's own top-level code sometimes constructing more than one incidentally. */
+    private pickBestCandidate;
     /** Handles `export default`, `module.exports = program`, and named exports. */
     private findCommand;
+    /**
+     * Structural check, not `instanceof Command`. The target CLI almost
+     * always has its own separate install of `commander` - a different
+     * copy than the one this adapter imports, even at the identical
+     * version - because `npx cliguard` installs cliguard (and its pinned
+     * `commander`) into its own isolated location, unrelated to the target
+     * project's `node_modules`. Node gives every resolved copy of a
+     * package its own class identity ("dual package hazard"), so
+     * `instanceof` fails by construction in that - extremely common - case.
+     * Verified against a real external consumer project via `npx cliguard`
+     * with its own separate `commander` install, both at a different major
+     * version and at the identical version to this package's own
+     * `^12.1.0` - `instanceof` failed in both; this doesn't.
+     */
+    private looksLikeCommand;
     /** Recurses into `command.commands` so root and every subcommand at any depth go through the same mapping. */
     private mapCommand;
     private mapOption;

package/dist/adapters/commander.adapter.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommanderAdapter = void 0;
-const commander_1 = require("commander");
+const construction_capture_1 = require("./construction-capture");
 const load_module_1 = require("./load-module");
 /**
  * Extracts a Contract from a target file that exports a Commander.js
@@ -24,42 +24,90 @@ class CommanderAdapter {
         };
     }
     async loadCommand(entryPath) {
+        // Patched *before* the target loads, so a `new Command()` or
+        // `createCommand()` call anywhere in its own top-level code gets
+        // captured as a side effect of loadModule() below - even if the
+        // target never exports the result anywhere. See
+        // construction-capture.ts for why this is safe and what it can't
+        // reach.
+        const captured = (0, construction_capture_1.captureConstructions)("commander", entryPath, "Command", ["createCommand"]);
         const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
-        const command = this.findCommand(viaImport.moduleExports) ?? this.findCommand(viaRequire.moduleExports);
+        const command = this.findCommand(viaImport.moduleExports) ??
+            this.findCommand(viaRequire.moduleExports) ??
+            this.pickBestCandidate(captured);
         if (command)
             return command;
-        // Neither attempt's exports contained a Command. One load attempt
-        // failing on its own is normal and expected (an ESM-only file can't
-        // require(), a CJS one may reject a bare import() on an older Node)
-        // - the interesting case is when the file simply never loaded at all
-        // (a syntax error, a missing dependency inside it), which the
-        // generic "no Command instance found" message below would otherwise
+        // Neither attempt's exports contained a Command, and nothing was
+        // captured during construction either. One load attempt failing on
+        // its own is normal and expected (an ESM-only file can't require(),
+        // a CJS one may reject a bare import() on an older Node) - the
+        // interesting case is when the file simply never loaded at all (a
+        // syntax error, a missing dependency inside it), which the generic
+        // "no Command instance found" message below would otherwise
         // misrepresent as "loaded fine, wrong export shape." Surface both
         // real reasons so the actual cause - a broken file vs. a genuinely
         // missing export - is never a guess.
         throw new Error(`cliguard: no Commander.js Command instance found in "${entryPath}". ` +
             "Export it as `export default program`, `module.exports = program`, " +
-            "or a named export (e.g. `export const program = new Command()`).\n" +
+            "or a named export (e.g. `export const program = new Command()`). If the file " +
+            "builds its Command inside a function that only runs when something calls it " +
+            "(never at the top level), point cliguard at a small wrapper file that calls " +
+            "that function and exports the result instead - see the README's " +
+            '"Entry files that build the CLI lazily" section.\n' +
             `  import() failed: ${viaImport.error ?? "module loaded, but exported no Command instance"}\n` +
             `  require() failed: ${viaRequire.error ?? "module loaded, but exported no Command instance"}`);
     }
+    /** Among every Command captured during construction, the one that looks most like the real, fully-built root program - flags on this file's own top-level code sometimes constructing more than one incidentally. */
+    pickBestCandidate(candidates) {
+        const valid = candidates.filter((candidate) => this.looksLikeCommand(candidate));
+        if (valid.length === 0)
+            return undefined;
+        return valid.reduce((best, candidate) => candidate.options.length + candidate.commands.length >
+            best.options.length + best.commands.length
+            ? candidate
+            : best);
+    }
     /** Handles `export default`, `module.exports = program`, and named exports. */
     findCommand(moduleExports) {
-        if (moduleExports instanceof commander_1.Command) {
+        if (this.looksLikeCommand(moduleExports)) {
             return moduleExports;
         }
         if (moduleExports && typeof moduleExports === "object") {
             const exportsObject = moduleExports;
-            if (exportsObject.default instanceof commander_1.Command) {
+            if (this.looksLikeCommand(exportsObject.default)) {
                 return exportsObject.default;
             }
             for (const value of Object.values(exportsObject)) {
-                if (value instanceof commander_1.Command)
+                if (this.looksLikeCommand(value))
                     return value;
             }
         }
         return undefined;
     }
+    /**
+     * Structural check, not `instanceof Command`. The target CLI almost
+     * always has its own separate install of `commander` - a different
+     * copy than the one this adapter imports, even at the identical
+     * version - because `npx cliguard` installs cliguard (and its pinned
+     * `commander`) into its own isolated location, unrelated to the target
+     * project's `node_modules`. Node gives every resolved copy of a
+     * package its own class identity ("dual package hazard"), so
+     * `instanceof` fails by construction in that - extremely common - case.
+     * Verified against a real external consumer project via `npx cliguard`
+     * with its own separate `commander` install, both at a different major
+     * version and at the identical version to this package's own
+     * `^12.1.0` - `instanceof` failed in both; this doesn't.
+     */
+    looksLikeCommand(value) {
+        if (!value || typeof value !== "object")
+            return false;
+        const candidate = value;
+        return (Array.isArray(candidate.options) &&
+            Array.isArray(candidate.commands) &&
+            typeof candidate.name === "function" &&
+            typeof candidate.action === "function" &&
+            typeof candidate.opts === "function");
+    }
     /** Recurses into `command.commands` so root and every subcommand at any depth go through the same mapping. */
     mapCommand(command) {
         return {

package/dist/adapters/construction-capture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Captures whatever instance a target file's own top-level code
+ * constructs from `packageName` - even when the target never exports
+ * that instance anywhere `module.exports` reaches. Many real CLIs build
+ * their Commander/CAC instance inside a function that only runs when
+ * something actually calls it (or just never bother exporting it, since
+ * they have no reason to) - `findCommand`/`findCac` alone only ever
+ * catch the minority that do.
+ *
+ * How: Node caches a CommonJS module by its resolved absolute path.
+ * Resolving `packageName` from the *target file's own directory* (not
+ * this package's - a different copy, per commander.adapter.ts's
+ * `looksLikeCommand` doc) and mutating the exact object at that cached
+ * path means the target's own later `require(packageName)` - resolving
+ * to the same path - returns this already-patched object. There's no
+ * way for the target to tell the difference: `new Command()` still
+ * returns a real `Command` (the patch is a construct-trapping `Proxy`
+ * around the real class, transparent to `instanceof` and to every
+ * static/instance member), it's just also recorded here as a side
+ * effect.
+ *
+ * Only reaches CommonJS construction - a direct `new ClassExport()`, or
+ * a named factory function that closes over the real class and returns
+ * `new ClassExport()` internally (commander's `createCommand`, cac's
+ * `cac()` - patching only the class export wouldn't catch these, since
+ * the factory's own closure still points at the *original* class, not
+ * whatever we later put in `moduleExports[classExportName]`). A target
+ * that's genuine ESM, reaching the framework via a static `import`
+ * rather than `require`, isn't reachable this way - Node's ESM module
+ * cache is separate and not patchable from CommonJS. That's a real,
+ * documented limit, not a bug: commander and cac both ship CJS-only, so
+ * even an ESM target almost always reaches them through interop's own
+ * require() underneath - the case this can't reach is the rare one.
+ */
+export declare function captureConstructions(packageName: string, entryPath: string, classExportName: string, factoryExportNames: readonly string[]): unknown[];

package/dist/adapters/construction-capture.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureConstructions = captureConstructions;
+const path_1 = require("path");
+/**
+ * Captures whatever instance a target file's own top-level code
+ * constructs from `packageName` - even when the target never exports
+ * that instance anywhere `module.exports` reaches. Many real CLIs build
+ * their Commander/CAC instance inside a function that only runs when
+ * something actually calls it (or just never bother exporting it, since
+ * they have no reason to) - `findCommand`/`findCac` alone only ever
+ * catch the minority that do.
+ *
+ * How: Node caches a CommonJS module by its resolved absolute path.
+ * Resolving `packageName` from the *target file's own directory* (not
+ * this package's - a different copy, per commander.adapter.ts's
+ * `looksLikeCommand` doc) and mutating the exact object at that cached
+ * path means the target's own later `require(packageName)` - resolving
+ * to the same path - returns this already-patched object. There's no
+ * way for the target to tell the difference: `new Command()` still
+ * returns a real `Command` (the patch is a construct-trapping `Proxy`
+ * around the real class, transparent to `instanceof` and to every
+ * static/instance member), it's just also recorded here as a side
+ * effect.
+ *
+ * Only reaches CommonJS construction - a direct `new ClassExport()`, or
+ * a named factory function that closes over the real class and returns
+ * `new ClassExport()` internally (commander's `createCommand`, cac's
+ * `cac()` - patching only the class export wouldn't catch these, since
+ * the factory's own closure still points at the *original* class, not
+ * whatever we later put in `moduleExports[classExportName]`). A target
+ * that's genuine ESM, reaching the framework via a static `import`
+ * rather than `require`, isn't reachable this way - Node's ESM module
+ * cache is separate and not patchable from CommonJS. That's a real,
+ * documented limit, not a bug: commander and cac both ship CJS-only, so
+ * even an ESM target almost always reaches them through interop's own
+ * require() underneath - the case this can't reach is the rare one.
+ */
+function captureConstructions(packageName, entryPath, classExportName, factoryExportNames) {
+    const captured = [];
+    let moduleExports;
+    try {
+        const targetDir = (0, path_1.dirname)((0, path_1.resolve)(process.cwd(), entryPath));
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- resolving/patching the target's own copy of a CJS package, not a static dependency of this file
+        const resolvedPath = require.resolve(packageName, { paths: [targetDir] });
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
+        moduleExports = require(resolvedPath);
+    }
+    catch {
+        // The target doesn't have this package resolvable from its own
+        // location at all - nothing to patch, nothing to capture. The
+        // caller's existing "no instance found" error already covers this.
+        return captured;
+    }
+    const record = (instance) => {
+        if (instance && typeof instance === "object")
+            captured.push(instance);
+    };
+    const RealClass = moduleExports[classExportName];
+    if (typeof RealClass === "function") {
+        moduleExports[classExportName] = new Proxy(RealClass, {
+            construct(target, args, newTarget) {
+                const instance = Reflect.construct(target, args, newTarget);
+                record(instance);
+                return instance;
+            },
+        });
+    }
+    for (const factoryName of factoryExportNames) {
+        const realFactory = moduleExports[factoryName];
+        if (typeof realFactory === "function") {
+            moduleExports[factoryName] = (...args) => {
+                const instance = realFactory(...args);
+                record(instance);
+                return instance;
+            };
+        }
+    }
+    return captured;
+}

package/dist/bin.js

@@ -45,9 +45,13 @@ program
         console.warn(`A contract already exists. Run "cliguard update" to overwrite it.`);
         process.exit(1);
     }
-    const contract = await resolveAdapter(options.adapter).extract(entry);
-    (0, storage_1.writeContract)(contract);
-    console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)()}.`);
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await resolveAdapter(options.adapter).extract(entry);
+        (0, storage_1.writeContract)(contract);
+        console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)()}.`);
+        return 0;
+    });
+    process.exit(exitCode);
 });
 program
     .command("check")
@@ -56,20 +60,23 @@ program
     .option(...adapterOption)
     .option("--json", "print a machine-readable JSON result instead of text", false)
     .action(async (entry, options) => {
-    const oldContract = (0, storage_1.readContract)();
-    const newContract = await resolveAdapter(options.adapter).extract(entry);
-    const diff = diffEngine.compare(oldContract, newContract);
-    const hasBreaking = diff.some((entry) => entry.type === types_1.ChangeType.BREAKING);
-    if (options.json) {
-        console.log(JSON.stringify(toJsonResult(diff), null, 2));
-        process.exit(hasBreaking ? 1 : 0);
-    }
-    if (diff.length === 0) {
-        console.log("✅ CLI contract is intact.");
-        process.exit(0);
-    }
-    printDiff(diff);
-    process.exit(hasBreaking ? 1 : 0);
+    const exitCode = await withSuppressedExit(async () => {
+        const oldContract = (0, storage_1.readContract)();
+        const newContract = await resolveAdapter(options.adapter).extract(entry);
+        const diff = diffEngine.compare(oldContract, newContract);
+        const hasBreaking = diff.some((entry) => entry.type === types_1.ChangeType.BREAKING);
+        if (options.json) {
+            console.log(JSON.stringify(toJsonResult(diff), null, 2));
+            return hasBreaking ? 1 : 0;
+        }
+        if (diff.length === 0) {
+            console.log("✅ CLI contract is intact.");
+            return 0;
+        }
+        printDiff(diff);
+        return hasBreaking ? 1 : 0;
+    });
+    process.exit(exitCode);
 });
 program
     .command("update")
@@ -77,10 +84,45 @@ program
     .argument("<entry>", "path to the target CLI's entry file")
     .option(...adapterOption)
     .action(async (entry, options) => {
-    const contract = await resolveAdapter(options.adapter).extract(entry);
-    (0, storage_1.writeContract)(contract);
-    console.log("🔄 CLI contract updated successfully.");
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await resolveAdapter(options.adapter).extract(entry);
+        (0, storage_1.writeContract)(contract);
+        console.log("🔄 CLI contract updated successfully.");
+        return 0;
+    });
+    process.exit(exitCode);
 });
+/**
+ * Runs `action` with `process.exit` neutralized, restoring the real one
+ * the instant `action` settles - then the caller calls the *real*
+ * `process.exit` immediately with cliguard's own, correct code.
+ *
+ * Why this exists: the fallback in commander.adapter.ts /
+ * cac.adapter.ts's construction-capture lets a target CLI's own
+ * top-level code run further than a plain export lookup ever did - real
+ * targets often call `.parse()`/`.run()` for real as a side effect of
+ * being loaded, sometimes asynchronously (an `await` inside their own
+ * main function, a dangling `.catch()` continuation still in flight).
+ * Node's `process.exit()` is immediate and unconditional - if that
+ * dangling target code calls it (even with an unrelated code, even
+ * *after* cliguard already computed the right answer), it kills this
+ * process with the target's exit code, not cliguard's. Restoring the
+ * real `process.exit` and calling it ourselves right away, synchronously,
+ * the moment `action` resolves closes the race: Node's exit is immediate
+ * and single-threaded, so nothing queued after that point - including
+ * whatever the target's own code was about to do - ever runs.
+ */
+async function withSuppressedExit(action) {
+    const realExit = process.exit.bind(process);
+    // eslint-disable-next-line @typescript-eslint/no-empty-function -- deliberately a no-op: see doc comment above
+    process.exit = (() => undefined);
+    try {
+        return await action();
+    }
+    finally {
+        process.exit = realExit;
+    }
+}
 function toJsonResult(diff) {
     const summary = {
         breaking: diff.filter((entry) => entry.type === types_1.ChangeType.BREAKING).length,

package/dist/core/diff.engine.d.ts

@@ -17,6 +17,8 @@ export declare class DiffEngine {
     compare(oldContract: Contract, newContract: Contract): DiffResult[];
     private compareCommands;
     private compareSubcommands;
+    /** CAC's default command (declared with no leading name, e.g. `cli.command("[...files]", ...)`) has name === "" - a blank path segment reads as a typo, not a real command. */
+    private commandLabel;
     private compareOptions;
     private compareOption;
     private compareArguments;

package/dist/core/diff.engine.js

@@ -35,10 +35,10 @@ class DiffEngine {
             results.push({
                 type: types_1.ChangeType.PATCH,
                 path,
-                message: `Description changed for command "${oldCmd.name}".`,
+                message: `Description changed for command "${this.commandLabel(oldCmd.name)}".`,
             });
         }
-        results.push(...this.compareAliases(oldCmd.aliases, newCmd.aliases, path, `command "${oldCmd.name}"`));
+        results.push(...this.compareAliases(oldCmd.aliases, newCmd.aliases, path, `command "${this.commandLabel(oldCmd.name)}"`));
         results.push(...this.compareOptions(oldCmd.options, newCmd.options, path));
         results.push(...this.compareArguments(oldCmd.arguments, newCmd.arguments, path));
         results.push(...this.compareSubcommands(oldCmd.subcommands, newCmd.subcommands, path));
@@ -49,13 +49,13 @@ class DiffEngine {
         const oldByName = this.indexByName(oldSubs);
         const newByName = this.indexByName(newSubs);
         for (const [name, oldSub] of oldByName) {
-            const childPath = `${path} -> ${name}`;
+            const childPath = `${path} -> ${this.commandLabel(name)}`;
             const newSub = newByName.get(name);
             if (!newSub) {
                 results.push({
                     type: types_1.ChangeType.BREAKING,
                     path: childPath,
-                    message: `Command "${name}" was removed.`,
+                    message: `Command "${this.commandLabel(name)}" was removed.`,
                 });
                 continue;
             }
@@ -66,12 +66,16 @@ class DiffEngine {
                 continue;
             results.push({
                 type: types_1.ChangeType.ADDITIVE,
-                path: `${path} -> ${name}`,
-                message: `Command "${name}" was added.`,
+                path: `${path} -> ${this.commandLabel(name)}`,
+                message: `Command "${this.commandLabel(name)}" was added.`,
             });
         }
         return results;
     }
+    /** CAC's default command (declared with no leading name, e.g. `cli.command("[...files]", ...)`) has name === "" - a blank path segment reads as a typo, not a real command. */
+    commandLabel(name) {
+        return name === "" ? "<default>" : name;
+    }
     compareOptions(oldOptions, newOptions, path) {
         const results = [];
         const oldByName = this.indexByName(oldOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",