cliguard 0.1.0 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@ REST and GraphQL APIs have contract testing (Pact, Specmatic, oasdiff) baked int
 `cliguard` captures your CLI's real contract - every command, flag, default, and required argument - straight from your CLI framework's own object graph, not by parsing `--help` text. Commit that contract like a snapshot test. From then on, `cliguard check` fails your build the moment a change would break an existing caller, and passes straight through anything additive or cosmetic.
 
 ```text
-🔴 [root -> build -> option[--target]] Required option "--target" was removed.
+🔴 [root -> build -> option[--target]] Option "--target" was removed.
 🟢 [root -> build -> option[--dry-run]] New optional option "--dry-run" was added.
 ```
 
@@ -36,6 +36,26 @@ program.command("build").requiredOption("-t, --target <target>", "build target")
 module.exports = { program }; // <- cliguard reads this, never runs it
 ```
 
+ESM entry files work the same way - `export default program` (or a named export) instead of `module.exports`. cliguard loads your entry through a real dynamic `import()`, so this works even for a target CLI with a top-level `await`.
+
+Built with [CAC](https://github.com/cacjs/cac) instead? Export the `CAC` instance the same way (`module.exports = { cli }` / `export default cli`) and pass `--adapter cac`:
+
+```js
+// bin/cli.js
+const { cac } = require("cac");
+
+const cli = cac("mycli");
+cli.command("build <entry>", "build target").option("-t, --target <target>", "build target");
+
+module.exports = { cli };
+```
+
+```sh
+npx cliguard init ./bin/cli.js --adapter cac
+```
+
+`cac` itself is an optional dependency of cliguard - only installed if you actually use `--adapter cac`.
+
 Then:
 
 ```sh
@@ -81,9 +101,15 @@ jobs:
 
 ## Supported frameworks
 
-[Commander.js](https://github.com/tj/commander.js) today - it's what Vue CLI, Prettier, and a large share of the npm CLI ecosystem is built on. The core (types + diff engine) is 100% framework-agnostic by design: every framework-specific detail lives behind the `CliAdapter` interface in [`src/adapters/`](src/adapters/), so adding a new adapter never touches the diffing logic. See the [good first issues](https://github.com/Bryandero98/cliguard/labels/good%20first%20issue) for exactly that.
+[Commander.js](https://github.com/tj/commander.js) (default) and [CAC](https://github.com/cacjs/cac) (`--adapter cac`) today. The core (types + diff engine) is 100% framework-agnostic by design: every framework-specific detail lives behind the `CliAdapter` interface in [`src/adapters/`](src/adapters/), so adding a new adapter never touches the diffing logic. Yargs is the next open gap - see the [good first issue](https://github.com/Bryandero98/cliguard/labels/good%20first%20issue).
+
+A couple of `OptionContract`/`ArgumentContract` fields carry real, framework-specific limitations rather than a mapping gap - see [`src/adapters/cac.adapter.ts`](src/adapters/cac.adapter.ts)'s own doc comment for exactly which ones and why (CAC has no declarative "this flag must be passed" concept, and no per-argument description).
+
+The current adapter mechanism loads the target CLI's entry file into the Node process (`import()`/`require()`) and reads its object graph directly, so the next targets are other Node frameworks. Cross-language support (Python's Click, Rust's Clap, Go's Cobra) is a real future direction, but needs a different extraction strategy first, since a compiled Clap/Cobra binary can't be `require()`'d into Node the way a JS CLI can - most likely each of those would introspect via a structured `--help` output (some frameworks support a JSON mode) rather than the same in-process approach.
+
+## Security
 
-The current adapter mechanism loads the target CLI's entry file into the Node process (`import()`/`require()`) and reads its object graph directly, so the next targets are other Node frameworks - Yargs and CAC are both open. Cross-language support (Python's Click, Rust's Clap, Go's Cobra) is a real future direction, but needs a different extraction strategy first, since a compiled Clap/Cobra binary can't be `require()`'d into Node the way a JS CLI can - most likely each of those would introspect via a structured `--help` output (some frameworks support a JSON mode) rather than the same in-process approach.
+Extracting a contract runs the target entry file's own top-level code, the same as `node ./bin/cli.js` would - see [SECURITY.md](./SECURITY.md) for what that means in practice.
 
 ## Roadmap
 

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

@@ -3,7 +3,7 @@ import type { Contract } from "../core/types";
  * Everything the diff engine and the `cliguard` CLI commands need from a
  * framework adapter. Each adapter owns exactly one framework's introspection
  * details; nothing outside `src/adapters/` should ever import a framework
- * package (`commander`, eventually `yargs`, etc.) directly.
+ * package (`commander`, `cac`, eventually `yargs`) directly.
  */
 export interface CliAdapter {
     /** Adapter identifier stored in `Contract.adapter`, e.g. "commander". */

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

@@ -0,0 +1,37 @@
+import type { Contract } from "../core/types";
+import type { CliAdapter } from "./adapter.interface";
+/**
+ * Extracts a Contract from a target file that exports a `cac()` `CAC`
+ * instance. Never parses --help output - every field comes straight from
+ * CAC's own object graph (`.commands`, `.globalCommand`, `.options`,
+ * `.args`), matching CommanderAdapter's approach.
+ *
+ * Two real shape differences from Commander, not bugs:
+ * - CAC has no declarative "this option must be passed" concept (unlike
+ *   Commander's `requiredOption`) - `checkOptionValue` (cac's own source)
+ *   only validates the *value* of an option that was actually passed, so
+ *   `OptionContract.required` is always `false` here.
+ * - CAC's commands are a flat list off the root `CAC` instance, not a
+ *   tree - there's no nested sub-subcommand concept to recurse into, so
+ *   every mapped command's own `subcommands` is always `[]`.
+ */
+export declare class CacAdapter implements CliAdapter {
+    readonly id = "cac";
+    extract(entryPath: string): Promise<Contract>;
+    private loadCac;
+    /** Handles `export default`, `module.exports = cli`, and named exports. */
+    private findCac;
+    /**
+     * CAC's root instance carries global options (`cli.option(...)`,
+     * exposed via `globalCommand`) but no description of its own and no
+     * positional arguments - those only exist on individual commands.
+     */
+    private mapRoot;
+    /** subcommands is always [] - CAC has no nested sub-subcommand concept to recurse into. */
+    private mapCommand;
+    private mapOption;
+    /** `-x` for a single-character name, `--xray` otherwise - CAC's own `.names` carries neither dash. */
+    private dashPrefix;
+    /** `isBoolean` is CAC's own flag for a valueless option; anything else declared a value (`<x>` required or `[x]` optional). */
+    private inferValueType;
+}

package/dist/adapters/cac.adapter.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacAdapter = void 0;
+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
+ * CAC's own object graph (`.commands`, `.globalCommand`, `.options`,
+ * `.args`), matching CommanderAdapter's approach.
+ *
+ * Two real shape differences from Commander, not bugs:
+ * - CAC has no declarative "this option must be passed" concept (unlike
+ *   Commander's `requiredOption`) - `checkOptionValue` (cac's own source)
+ *   only validates the *value* of an option that was actually passed, so
+ *   `OptionContract.required` is always `false` here.
+ * - CAC's commands are a flat list off the root `CAC` instance, not a
+ *   tree - there's no nested sub-subcommand concept to recurse into, so
+ *   every mapped command's own `subcommands` is always `[]`.
+ */
+class CacAdapter {
+    constructor() {
+        this.id = "cac";
+    }
+    async extract(entryPath) {
+        const cli = await this.loadCac(entryPath);
+        return {
+            contractVersion: 1,
+            adapter: this.id,
+            capturedAt: new Date().toISOString(),
+            root: this.mapRoot(cli),
+        };
+    }
+    async loadCac(entryPath) {
+        const CacClass = loadCacClass();
+        const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
+        const cli = this.findCac(viaImport.moduleExports, CacClass) ??
+            this.findCac(viaRequire.moduleExports, CacClass);
+        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" +
+            `  import() failed: ${viaImport.error ?? "module loaded, but exported no CAC instance"}\n` +
+            `  require() failed: ${viaRequire.error ?? "module loaded, but exported no CAC instance"}`);
+    }
+    /** Handles `export default`, `module.exports = cli`, and named exports. */
+    findCac(moduleExports, CacClass) {
+        if (moduleExports instanceof CacClass) {
+            return moduleExports;
+        }
+        if (moduleExports && typeof moduleExports === "object") {
+            const exportsObject = moduleExports;
+            if (exportsObject.default instanceof CacClass) {
+                return exportsObject.default;
+            }
+            for (const value of Object.values(exportsObject)) {
+                if (value instanceof CacClass)
+                    return value;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * CAC's root instance carries global options (`cli.option(...)`,
+     * exposed via `globalCommand`) but no description of its own and no
+     * positional arguments - those only exist on individual commands.
+     */
+    mapRoot(cli) {
+        return {
+            name: cli.name,
+            description: "",
+            aliases: [],
+            options: cli.globalCommand.options.map((option) => this.mapOption(option)),
+            arguments: [],
+            subcommands: cli.commands.map((command) => this.mapCommand(command)),
+        };
+    }
+    /** subcommands is always [] - CAC has no nested sub-subcommand concept to recurse into. */
+    mapCommand(command) {
+        return {
+            name: command.name,
+            description: command.description,
+            aliases: command.aliasNames,
+            options: command.options.map((option) => this.mapOption(option)),
+            arguments: command.args.map((arg) => ({
+                name: arg.value,
+                required: arg.required,
+                variadic: arg.variadic,
+                // CAC's CommandArg carries no description field - a real
+                // framework limitation (positional args are undocumented in
+                // CAC's own model), not a mapping gap.
+                description: "",
+            })),
+            subcommands: [],
+        };
+    }
+    mapOption(option) {
+        return {
+            flags: option.rawName,
+            name: option.name,
+            aliases: option.names
+                .filter((name) => name !== option.name)
+                .map((name) => this.dashPrefix(name)),
+            description: option.description,
+            // CAC has no declarative "must be passed" concept - see class doc.
+            required: false,
+            valueType: this.inferValueType(option),
+            // CAC has no per-option variadic declaration (unlike positional
+            // args, which do) - a repeated flag collects into an array at
+            // parse time regardless of anything declared statically here.
+            variadic: false,
+            defaultValue: option.config.default ?? null,
+        };
+    }
+    /** `-x` for a single-character name, `--xray` otherwise - CAC's own `.names` carries neither dash. */
+    dashPrefix(name) {
+        return name.length === 1 ? `-${name}` : `--${name}`;
+    }
+    /** `isBoolean` is CAC's own flag for a valueless option; anything else declared a value (`<x>` required or `[x]` optional). */
+    inferValueType(option) {
+        return option.isBoolean ? "boolean" : "string";
+    }
+}
+exports.CacAdapter = CacAdapter;

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

@@ -10,9 +10,7 @@ import type { CliAdapter } from "./adapter.interface";
 export declare class CommanderAdapter implements CliAdapter {
     readonly id = "commander";
     extract(entryPath: string): Promise<Contract>;
-    /** Tries `import()` first, then falls back to `require()` for entry points that don't support ESM dynamic import. */
     private loadCommand;
-    private tryLoad;
     /** Handles `export default`, `module.exports = program`, and named exports. */
     private findCommand;
     /** Recurses into `command.commands` so root and every subcommand at any depth go through the same mapping. */

package/dist/adapters/commander.adapter.js

@@ -1,41 +1,8 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommanderAdapter = void 0;
-const path_1 = require("path");
 const commander_1 = require("commander");
+const load_module_1 = require("./load-module");
 /**
  * Extracts a Contract from a target file that exports a Commander.js
  * `Command` instance. Never parses --help output - every field comes
@@ -56,33 +23,25 @@ class CommanderAdapter {
             root: this.mapCommand(program),
         };
     }
-    /** Tries `import()` first, then falls back to `require()` for entry points that don't support ESM dynamic import. */
     async loadCommand(entryPath) {
-        // A relative entryPath (as typed on the command line) must resolve
-        // against the caller's cwd, not against this file's own location -
-        // both import() and require() would otherwise resolve it relative to
-        // dist/, silently loading the wrong (or no) file.
-        const absolutePath = (0, path_1.resolve)(process.cwd(), entryPath);
-        const viaImport = await this.tryLoad(() => Promise.resolve(`${absolutePath}`).then(s => __importStar(require(s))));
-        if (viaImport)
-            return viaImport;
-        // eslint-disable-next-line @typescript-eslint/no-require-imports -- deliberate fallback for target CLIs that aren't import()-able
-        const viaRequire = await this.tryLoad(() => Promise.resolve(require(absolutePath)));
-        if (viaRequire)
-            return viaRequire;
+        const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
+        const command = this.findCommand(viaImport.moduleExports) ?? this.findCommand(viaRequire.moduleExports);
+        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
+        // 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()`).");
-    }
-    async tryLoad(load) {
-        let moduleExports;
-        try {
-            moduleExports = await load();
-        }
-        catch {
-            return undefined;
-        }
-        return this.findCommand(moduleExports);
+            "or a named export (e.g. `export const program = new Command()`).\n" +
+            `  import() failed: ${viaImport.error ?? "module loaded, but exported no Command instance"}\n` +
+            `  require() failed: ${viaRequire.error ?? "module loaded, but exported no Command instance"}`);
     }
     /** Handles `export default`, `module.exports = program`, and named exports. */
     findCommand(moduleExports) {

package/dist/adapters/load-module.d.ts

@@ -0,0 +1,22 @@
+export interface LoadAttempt {
+    /** `undefined` when this attempt threw - see `error` instead. */
+    readonly moduleExports: unknown;
+    /** Set only when this particular attempt threw. */
+    readonly error: unknown;
+}
+export interface LoadResult {
+    readonly viaImport: LoadAttempt;
+    readonly viaRequire: LoadAttempt;
+}
+/**
+ * Loads `entryPath` (resolved against the caller's cwd, not this file's
+ * own location) via a real dynamic import() AND require(), always both -
+ * never short-circuiting on the first one that merely doesn't throw.
+ * A framework instance can end up reachable through only one of the two
+ * (e.g. an interop wrapper shifting where a named export lands), so an
+ * adapter needs both attempts' exports to search, not just whichever
+ * loaded first. Shared by every adapter - none of this is
+ * framework-specific; finding the actual Command/CAC/etc. instance
+ * inside either attempt's exports is each adapter's own job.
+ */
+export declare function loadModule(entryPath: string): Promise<LoadResult>;

package/dist/adapters/load-module.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadModule = loadModule;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const url_1 = require("url");
+/**
+ * A genuine dynamic `import()`, immune to TypeScript's own rewriting.
+ * This project builds with `module: "commonjs"` (required for the CLI's
+ * own require()-based entrypoint), and under that setting tsc rewrites a
+ * literal `import()` expression into `Promise.resolve().then(() =>
+ * require(...))` - so a plain `import(absolutePath)` would compile to
+ * `require()` in disguise, never a real ESM load, no matter how the
+ * source reads. That silently breaks on any target file that's genuine
+ * ESM with no synchronous CommonJS-compatible form (e.g. one with a
+ * top-level `await`) on any Node version that doesn't support requiring
+ * an ESM graph. Constructing the function from a string hides the
+ * `import()` call from tsc's static analysis, so this is Node's actual
+ * dynamic import at runtime.
+ */
+const dynamicImport = new Function("specifier", "return import(specifier)");
+/**
+ * Loads `entryPath` (resolved against the caller's cwd, not this file's
+ * own location) via a real dynamic import() AND require(), always both -
+ * never short-circuiting on the first one that merely doesn't throw.
+ * A framework instance can end up reachable through only one of the two
+ * (e.g. an interop wrapper shifting where a named export lands), so an
+ * adapter needs both attempts' exports to search, not just whichever
+ * loaded first. Shared by every adapter - none of this is
+ * framework-specific; finding the actual Command/CAC/etc. instance
+ * inside either attempt's exports is each adapter's own job.
+ */
+async function loadModule(entryPath) {
+    const absolutePath = (0, path_1.resolve)(process.cwd(), entryPath);
+    // Checked up front so a caller can tell "the file doesn't exist" apart
+    // from "it exists but doesn't export what we're looking for" - both
+    // import() and require() otherwise fail the same opaque way for a
+    // missing file. Exact-path only, by design: entryPath is documented as
+    // a path to a specific entry file, not a resolvable module specifier,
+    // so this never has to account for extension-less or directory-index
+    // resolution.
+    if (!(0, fs_1.existsSync)(absolutePath)) {
+        throw new Error(`cliguard: no such file: "${absolutePath}".`);
+    }
+    // Dynamic import() requires a file:// URL for an absolute filesystem
+    // path on Windows - a raw "C:\foo\bar.js" parses as a URL with scheme
+    // "c:" and throws ERR_UNSUPPORTED_ESM_URL_SCHEME. pathToFileURL is a
+    // no-op in effect on POSIX (still produces a valid file:// URL there).
+    const fileUrl = (0, url_1.pathToFileURL)(absolutePath).href;
+    const viaImport = await attempt(() => dynamicImport(fileUrl));
+    const viaRequire = await attempt(
+    // eslint-disable-next-line @typescript-eslint/no-require-imports -- deliberate second attempt for entry points that aren't import()-able
+    () => Promise.resolve(require(absolutePath)));
+    return { viaImport, viaRequire };
+}
+async function attempt(load) {
+    try {
+        return { moduleExports: await load(), error: undefined };
+    }
+    catch (error) {
+        return { moduleExports: undefined, error };
+    }
+}

package/dist/bin.js

@@ -2,26 +2,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
+const cac_adapter_1 = require("./adapters/cac.adapter");
 const commander_adapter_1 = require("./adapters/commander.adapter");
 const diff_engine_1 = require("./core/diff.engine");
 const storage_1 = require("./core/storage");
 const types_1 = require("./core/types");
-const adapter = new commander_adapter_1.CommanderAdapter();
+// Constructing an adapter here is cheap (no eager require of its
+// framework - CacAdapter only loads `cac` lazily, inside extract()), so
+// every adapter is always registered regardless of which one a given
+// invocation actually uses.
+const adapters = {
+    commander: new commander_adapter_1.CommanderAdapter(),
+    cac: new cac_adapter_1.CacAdapter(),
+};
+function resolveAdapter(name) {
+    const adapter = adapters[name];
+    if (!adapter) {
+        throw new Error(`cliguard: unknown adapter "${name}". Available: ${Object.keys(adapters).join(", ")}.`);
+    }
+    return adapter;
+}
 const diffEngine = new diff_engine_1.DiffEngine();
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- package.json has no type declarations to import against; require() is the simplest correct read here
+const packageJson = require("../package.json");
 const program = new commander_1.Command();
 program
     .name("cliguard")
-    .description("Snapshot-tests your CLI's contract so you never ship a breaking change by accident.");
+    .description("Snapshot-tests your CLI's contract so you never ship a breaking change by accident.")
+    .version(packageJson.version);
+const adapterOption = [
+    "-a, --adapter <name>",
+    "CLI framework adapter to use",
+    "commander",
+];
 program
     .command("init")
     .description("Capture the current CLI surface as the committed contract")
     .argument("<entry>", "path to the target CLI's entry file")
-    .action(async (entry) => {
+    .option(...adapterOption)
+    .action(async (entry, options) => {
     if ((0, storage_1.contractExists)()) {
         console.warn(`El contrato ya existe. Usa "cliguard update" para sobrescribirlo.`);
         process.exit(1);
     }
-    const contract = await adapter.extract(entry);
+    const contract = await resolveAdapter(options.adapter).extract(entry);
     (0, storage_1.writeContract)(contract);
     console.log(`✅ Contrato de CLI inicializado con éxito en ${(0, storage_1.getContractDisplayPath)()}.`);
 });
@@ -29,9 +53,10 @@ program
     .command("check")
     .description("Compare the current CLI surface against the committed contract")
     .argument("<entry>", "path to the target CLI's entry file")
-    .action(async (entry) => {
+    .option(...adapterOption)
+    .action(async (entry, options) => {
     const oldContract = (0, storage_1.readContract)();
-    const newContract = await adapter.extract(entry);
+    const newContract = await resolveAdapter(options.adapter).extract(entry);
     const diff = diffEngine.compare(oldContract, newContract);
     if (diff.length === 0) {
         console.log("✅ El contrato de la CLI está intacto.");
@@ -45,8 +70,9 @@ program
     .command("update")
     .description("Overwrite the committed contract with the CLI's current surface")
     .argument("<entry>", "path to the target CLI's entry file")
-    .action(async (entry) => {
-    const contract = await adapter.extract(entry);
+    .option(...adapterOption)
+    .action(async (entry, options) => {
+    const contract = await resolveAdapter(options.adapter).extract(entry);
     (0, storage_1.writeContract)(contract);
     console.log("🔄 Contrato de CLI actualizado con éxito.");
 });

package/dist/core/diff.engine.js

@@ -83,7 +83,7 @@ class DiffEngine {
                 results.push({
                     type: types_1.ChangeType.BREAKING,
                     path: optionPath,
-                    message: `Required option "--${name}" was removed.`,
+                    message: `Option "--${name}" was removed.`,
                 });
                 continue;
             }

package/dist/core/storage.js

@@ -18,7 +18,22 @@ function readContract() {
     if (!(0, fs_1.existsSync)(CONTRACT_PATH)) {
         throw new Error(`cliguard: no contract found at "${getContractDisplayPath()}". Run \`cliguard init <entry.js>\` first.`);
     }
-    return JSON.parse((0, fs_1.readFileSync)(CONTRACT_PATH, "utf-8"));
+    const raw = (0, fs_1.readFileSync)(CONTRACT_PATH, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        // A bare JSON.parse error ("Unexpected token..." with no file
+        // context) reads as an internal cliguard bug, not "your committed
+        // contract file is corrupted" - which is the actual, fixable cause
+        // (a bad manual edit, a botched merge). Naming the file and the
+        // fix (re-run init/update) turns a confusing crash into an
+        // actionable message.
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`cliguard: "${getContractDisplayPath()}" is not valid JSON (${reason}). ` +
+            "If this file was hand-edited or came out of a bad merge, re-run " +
+            "`cliguard update <entry.js>` to regenerate it.");
+    }
 }
 function writeContract(contract) {
     (0, fs_1.mkdirSync)((0, path_1.dirname)(CONTRACT_PATH), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": ["cli", "contract-testing", "snapshot-testing", "commander", "ci"],
   "author": "Bryandero98",
@@ -22,17 +22,27 @@
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint src --ext .ts --fix",
     "format": "prettier --write \"src/**/*.ts\"",
+    "pretest": "npm run build",
     "test": "jest",
     "test:watch": "jest --watch"
   },
   "dependencies": {
     "commander": "^12.1.0"
   },
+  "peerDependencies": {
+    "cac": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "cac": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/jest": "^29.5.13",
     "@types/node": "^22.7.4",
     "@typescript-eslint/eslint-plugin": "^8.8.0",
     "@typescript-eslint/parser": "^8.8.0",
+    "cac": "^6.7.14",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^9.1.0",
     "jest": "^29.7.0",