cliguard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cliguard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# cliguard
+
+Snapshot testing for CLI contracts.
+
+## The problem
+
+REST and GraphQL APIs have contract testing (Pact, Specmatic, oasdiff) baked into every serious CI pipeline. CLIs don't. So a CLI's breaking changes ship silently: a flag quietly goes from optional to required, a subcommand gets renamed, a default value changes - and the first place anyone finds out is a Slack message from whoever's automation script just started failing in production.
+
+## The solution
+
+`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[--dry-run]] New optional option "--dry-run" was added.
+```
+
+The first line fails your CI. The second one doesn't - `--dry-run` is new and optional, so nothing that already calls your CLI can break because of it.
+
+## Quick start
+
+```sh
+npm install --save-dev cliguard
+```
+
+Your CLI's entry file needs to **export** its Commander `Command` instance instead of calling `.parse()` itself:
+
+```js
+// bin/cli.js
+const { Command } = require("commander");
+
+const program = new Command();
+program.command("build").requiredOption("-t, --target <target>", "build target");
+// ...
+
+module.exports = { program }; // <- cliguard reads this, never runs it
+```
+
+Then:
+
+```sh
+# Capture the current contract - commit .cliguard/contract.json
+npx cliguard init ./bin/cli.js
+
+# In CI: fail the build on any breaking change
+npx cliguard check ./bin/cli.js
+
+# You changed something on purpose? Accept the new contract.
+npx cliguard update ./bin/cli.js
+```
+
+`cliguard check` exits `1` if it finds even one `BREAKING` change, and `0` otherwise - safe to drop straight into any CI pipeline.
+
+## How changes get classified
+
+| | Removed | Added | Required flipped | Value type / default changed |
+|---|---|---|---|---|
+| **Command** | 🔴 BREAKING | 🟢 ADDITIVE | - | - |
+| **Option / argument** | 🔴 BREAKING | 🟢 ADDITIVE (optional) / 🔴 BREAKING (required) | 🔴 optional→required · 🟡 required→optional | 🔴 BREAKING |
+| **Alias** | 🔴 BREAKING | 🟡 PATCH | - | - |
+| **Description** | - | - | - | 🟡 PATCH |
+
+Full rules live in [`src/core/diff.engine.ts`](src/core/diff.engine.ts) - it's the one file worth reading if you want to know exactly why something was flagged.
+
+## CI integration
+
+```yaml
+# .github/workflows/cliguard.yml
+name: CLI contract
+on: [pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22.x }
+      - run: npm ci
+      - run: npx cliguard check ./bin/cli.js
+```
+
+## 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.
+
+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.
+
+## Roadmap
+
+The CLI and core diffing engine are, and will stay, free and open-source. Planned next: a hosted add-on for teams that want more than a CI exit code - a dashboard with the history of contract changes across releases, and Slack/webhook alerts the moment a breaking change lands. See [issue: Webhook reporter for SaaS integration](https://github.com/Bryandero98/cliguard/issues) for the first building block.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)

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

@@ -0,0 +1,13 @@
+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.
+ */
+export interface CliAdapter {
+    /** Adapter identifier stored in `Contract.adapter`, e.g. "commander". */
+    readonly id: string;
+    /** Loads `entryPath` and extracts its full command surface as a Contract. */
+    extract(entryPath: string): Promise<Contract>;
+}

package/dist/adapters/adapter.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,24 @@
+import type { Contract } from "../core/types";
+import type { CliAdapter } from "./adapter.interface";
+/**
+ * Extracts a Contract from a target file that exports a Commander.js
+ * `Command` instance. Never parses --help output - every field comes
+ * straight from Commander's own object graph (`.options`, `.commands`,
+ * `.registeredArguments`), so a change here can only ever be a mapping bug,
+ * never a text-format regression.
+ */
+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. */
+    private mapCommand;
+    private mapOption;
+    /** `<value>` = required value, `[value]` = optional value, neither = boolean flag. Read from Commander's own flag declaration, not rendered --help text. */
+    private inferValueType;
+    private mapArguments;
+}

package/dist/adapters/commander.adapter.js

@@ -0,0 +1,144 @@
+"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");
+/**
+ * Extracts a Contract from a target file that exports a Commander.js
+ * `Command` instance. Never parses --help output - every field comes
+ * straight from Commander's own object graph (`.options`, `.commands`,
+ * `.registeredArguments`), so a change here can only ever be a mapping bug,
+ * never a text-format regression.
+ */
+class CommanderAdapter {
+    constructor() {
+        this.id = "commander";
+    }
+    async extract(entryPath) {
+        const program = await this.loadCommand(entryPath);
+        return {
+            contractVersion: 1,
+            adapter: this.id,
+            capturedAt: new Date().toISOString(),
+            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;
+        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);
+    }
+    /** Handles `export default`, `module.exports = program`, and named exports. */
+    findCommand(moduleExports) {
+        if (moduleExports instanceof commander_1.Command) {
+            return moduleExports;
+        }
+        if (moduleExports && typeof moduleExports === "object") {
+            const exportsObject = moduleExports;
+            if (exportsObject.default instanceof commander_1.Command) {
+                return exportsObject.default;
+            }
+            for (const value of Object.values(exportsObject)) {
+                if (value instanceof commander_1.Command)
+                    return value;
+            }
+        }
+        return undefined;
+    }
+    /** Recurses into `command.commands` so root and every subcommand at any depth go through the same mapping. */
+    mapCommand(command) {
+        return {
+            name: command.name(),
+            description: command.description() ?? "",
+            aliases: command.aliases(),
+            options: command.options.map((option) => this.mapOption(option)),
+            arguments: this.mapArguments(command),
+            subcommands: command.commands.map((subcommand) => this.mapCommand(subcommand)),
+        };
+    }
+    mapOption(option) {
+        return {
+            flags: option.flags,
+            name: option.name(),
+            aliases: option.short ? [option.short] : [],
+            description: option.description ?? "",
+            required: option.mandatory ?? false,
+            valueType: this.inferValueType(option.flags),
+            variadic: option.variadic ?? false,
+            defaultValue: option.defaultValue ?? null,
+        };
+    }
+    /** `<value>` = required value, `[value]` = optional value, neither = boolean flag. Read from Commander's own flag declaration, not rendered --help text. */
+    inferValueType(flags) {
+        return flags.includes("<") || flags.includes("[") ? "string" : "boolean";
+    }
+    mapArguments(command) {
+        const modern = command
+            .registeredArguments;
+        const legacy = command._args;
+        const args = modern ?? legacy ?? [];
+        return args.map((arg) => ({
+            name: arg.name(),
+            required: arg.required,
+            variadic: arg.variadic,
+            description: arg.description ?? "",
+        }));
+    }
+}
+exports.CommanderAdapter = CommanderAdapter;

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+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();
+const diffEngine = new diff_engine_1.DiffEngine();
+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.");
+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) => {
+    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);
+    (0, storage_1.writeContract)(contract);
+    console.log(`✅ Contrato de CLI inicializado con éxito en ${(0, storage_1.getContractDisplayPath)()}.`);
+});
+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) => {
+    const oldContract = (0, storage_1.readContract)();
+    const newContract = await adapter.extract(entry);
+    const diff = diffEngine.compare(oldContract, newContract);
+    if (diff.length === 0) {
+        console.log("✅ El contrato de la CLI está intacto.");
+        process.exit(0);
+    }
+    printDiff(diff);
+    const hasBreaking = diff.some((entry) => entry.type === types_1.ChangeType.BREAKING);
+    process.exit(hasBreaking ? 1 : 0);
+});
+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);
+    (0, storage_1.writeContract)(contract);
+    console.log("🔄 Contrato de CLI actualizado con éxito.");
+});
+function printDiff(diff) {
+    for (const entry of diff) {
+        console.log(`${emojiFor(entry.type)} [${entry.path}] ${entry.message}`);
+    }
+}
+function emojiFor(type) {
+    switch (type) {
+        case types_1.ChangeType.BREAKING:
+            return "🔴";
+        case types_1.ChangeType.PATCH:
+            return "🟡";
+        case types_1.ChangeType.ADDITIVE:
+            return "🟢";
+        default:
+            return "⚪";
+    }
+}
+program.parseAsync(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

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

@@ -0,0 +1,29 @@
+import { ChangeType, type Contract } from "./types";
+export interface DiffResult {
+    readonly type: ChangeType;
+    /** Where in the command tree the change happened, e.g. "root -> build -> option[--target]". */
+    readonly path: string;
+    /** Human-readable description of exactly what changed. */
+    readonly message: string;
+}
+/**
+ * Compares two Contracts and returns every difference between them,
+ * classified as BREAKING, ADDITIVE, or PATCH. Purely structural: it only
+ * ever reads the Contract shape from `core/types.ts`, never a specific
+ * adapter, so it works identically regardless of which framework produced
+ * either contract. `capturedAt` is intentionally never read.
+ */
+export declare class DiffEngine {
+    compare(oldContract: Contract, newContract: Contract): DiffResult[];
+    private compareCommands;
+    private compareSubcommands;
+    private compareOptions;
+    private compareOption;
+    private compareArguments;
+    private compareArgument;
+    /** Shared by command aliases and option aliases - the rules are identical for both. */
+    private compareAliases;
+    private indexByName;
+    /** Deliberately simple: option/argument defaults are JSON-serializable primitives or arrays, never objects where key order would matter. */
+    private deepEqual;
+}

package/dist/core/diff.engine.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiffEngine = void 0;
+const types_1 = require("./types");
+/**
+ * Compares two Contracts and returns every difference between them,
+ * classified as BREAKING, ADDITIVE, or PATCH. Purely structural: it only
+ * ever reads the Contract shape from `core/types.ts`, never a specific
+ * adapter, so it works identically regardless of which framework produced
+ * either contract. `capturedAt` is intentionally never read.
+ */
+class DiffEngine {
+    compare(oldContract, newContract) {
+        const results = [];
+        if (oldContract.adapter !== newContract.adapter) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path: "contract",
+                message: `Contract adapter changed from "${oldContract.adapter}" to "${newContract.adapter}" - the two snapshots are not comparable.`,
+            });
+        }
+        if (oldContract.contractVersion !== newContract.contractVersion) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path: "contract",
+                message: `Contract format version changed from ${oldContract.contractVersion} to ${newContract.contractVersion}.`,
+            });
+        }
+        results.push(...this.compareCommands(oldContract.root, newContract.root, "root"));
+        return results;
+    }
+    compareCommands(oldCmd, newCmd, path) {
+        const results = [];
+        if (oldCmd.description !== newCmd.description) {
+            results.push({
+                type: types_1.ChangeType.PATCH,
+                path,
+                message: `Description changed for command "${oldCmd.name}".`,
+            });
+        }
+        results.push(...this.compareAliases(oldCmd.aliases, newCmd.aliases, path, `command "${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));
+        return results;
+    }
+    compareSubcommands(oldSubs, newSubs, path) {
+        const results = [];
+        const oldByName = this.indexByName(oldSubs);
+        const newByName = this.indexByName(newSubs);
+        for (const [name, oldSub] of oldByName) {
+            const childPath = `${path} -> ${name}`;
+            const newSub = newByName.get(name);
+            if (!newSub) {
+                results.push({
+                    type: types_1.ChangeType.BREAKING,
+                    path: childPath,
+                    message: `Command "${name}" was removed.`,
+                });
+                continue;
+            }
+            results.push(...this.compareCommands(oldSub, newSub, childPath));
+        }
+        for (const name of newByName.keys()) {
+            if (oldByName.has(name))
+                continue;
+            results.push({
+                type: types_1.ChangeType.ADDITIVE,
+                path: `${path} -> ${name}`,
+                message: `Command "${name}" was added.`,
+            });
+        }
+        return results;
+    }
+    compareOptions(oldOptions, newOptions, path) {
+        const results = [];
+        const oldByName = this.indexByName(oldOptions);
+        const newByName = this.indexByName(newOptions);
+        for (const [name, oldOption] of oldByName) {
+            const optionPath = `${path} -> option[--${name}]`;
+            const newOption = newByName.get(name);
+            if (!newOption) {
+                results.push({
+                    type: types_1.ChangeType.BREAKING,
+                    path: optionPath,
+                    message: `Required option "--${name}" was removed.`,
+                });
+                continue;
+            }
+            results.push(...this.compareOption(oldOption, newOption, optionPath));
+        }
+        for (const [name, newOption] of newByName) {
+            if (oldByName.has(name))
+                continue;
+            const optionPath = `${path} -> option[--${name}]`;
+            if (newOption.required) {
+                results.push({
+                    type: types_1.ChangeType.BREAKING,
+                    path: optionPath,
+                    message: `New required option "--${name}" was added - existing invocations that don't pass it will now fail.`,
+                });
+            }
+            else {
+                results.push({
+                    type: types_1.ChangeType.ADDITIVE,
+                    path: optionPath,
+                    message: `New optional option "--${name}" was added.`,
+                });
+            }
+        }
+        return results;
+    }
+    compareOption(oldOption, newOption, path) {
+        const results = [];
+        const label = `Option "--${oldOption.name}"`;
+        if (!oldOption.required && newOption.required) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} became required - existing invocations that don't pass it will now fail.`,
+            });
+        }
+        else if (oldOption.required && !newOption.required) {
+            results.push({
+                type: types_1.ChangeType.PATCH,
+                path,
+                message: `${label} became optional - backward compatible.`,
+            });
+        }
+        if (oldOption.valueType !== newOption.valueType) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} changed value type from "${oldOption.valueType}" to "${newOption.valueType}".`,
+            });
+        }
+        if (oldOption.variadic !== newOption.variadic) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} ${newOption.variadic ? "became variadic" : "stopped being variadic"} - the number of values it accepts changed.`,
+            });
+        }
+        if (!this.deepEqual(oldOption.defaultValue, newOption.defaultValue)) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} default value changed from ${JSON.stringify(oldOption.defaultValue)} to ${JSON.stringify(newOption.defaultValue)}.`,
+            });
+        }
+        results.push(...this.compareAliases(oldOption.aliases, newOption.aliases, path, label));
+        if (oldOption.description !== newOption.description) {
+            results.push({
+                type: types_1.ChangeType.PATCH,
+                path,
+                message: `${label} description changed.`,
+            });
+        }
+        return results;
+    }
+    compareArguments(oldArgs, newArgs, path) {
+        const results = [];
+        const oldByName = this.indexByName(oldArgs);
+        const newByName = this.indexByName(newArgs);
+        for (const [name, oldArg] of oldByName) {
+            const argPath = `${path} -> argument[<${name}>]`;
+            const newArg = newByName.get(name);
+            if (!newArg) {
+                results.push({
+                    type: types_1.ChangeType.BREAKING,
+                    path: argPath,
+                    message: `Argument "<${name}>" was removed.`,
+                });
+                continue;
+            }
+            results.push(...this.compareArgument(oldArg, newArg, argPath));
+        }
+        for (const [name, newArg] of newByName) {
+            if (oldByName.has(name))
+                continue;
+            const argPath = `${path} -> argument[<${name}>]`;
+            if (newArg.required) {
+                results.push({
+                    type: types_1.ChangeType.BREAKING,
+                    path: argPath,
+                    message: `New required argument "<${name}>" was added - existing invocations that don't pass it will now fail.`,
+                });
+            }
+            else {
+                results.push({
+                    type: types_1.ChangeType.ADDITIVE,
+                    path: argPath,
+                    message: `New optional argument "<${name}>" was added.`,
+                });
+            }
+        }
+        return results;
+    }
+    compareArgument(oldArg, newArg, path) {
+        const results = [];
+        const label = `Argument "<${oldArg.name}>"`;
+        if (!oldArg.required && newArg.required) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} became required - existing invocations that don't pass it will now fail.`,
+            });
+        }
+        else if (oldArg.required && !newArg.required) {
+            results.push({
+                type: types_1.ChangeType.PATCH,
+                path,
+                message: `${label} became optional - backward compatible.`,
+            });
+        }
+        if (oldArg.variadic !== newArg.variadic) {
+            results.push({
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} ${newArg.variadic ? "became variadic" : "stopped being variadic"} - the number of values it accepts changed.`,
+            });
+        }
+        if (oldArg.description !== newArg.description) {
+            results.push({
+                type: types_1.ChangeType.PATCH,
+                path,
+                message: `${label} description changed.`,
+            });
+        }
+        return results;
+    }
+    /** Shared by command aliases and option aliases - the rules are identical for both. */
+    compareAliases(oldAliases, newAliases, path, label) {
+        const results = [];
+        const oldSet = new Set(oldAliases);
+        const newSet = new Set(newAliases);
+        for (const alias of oldSet) {
+            if (!newSet.has(alias)) {
+                results.push({
+                    type: types_1.ChangeType.BREAKING,
+                    path,
+                    message: `Alias "${alias}" was removed from ${label}.`,
+                });
+            }
+        }
+        for (const alias of newSet) {
+            if (!oldSet.has(alias)) {
+                results.push({
+                    type: types_1.ChangeType.PATCH,
+                    path,
+                    message: `Alias "${alias}" was added to ${label}.`,
+                });
+            }
+        }
+        return results;
+    }
+    indexByName(items) {
+        return new Map(items.map((item) => [item.name, item]));
+    }
+    /** Deliberately simple: option/argument defaults are JSON-serializable primitives or arrays, never objects where key order would matter. */
+    deepEqual(a, b) {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+}
+exports.DiffEngine = DiffEngine;

package/dist/core/storage.d.ts

@@ -0,0 +1,6 @@
+import type { Contract } from "./types";
+/** Contract path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+export declare function getContractDisplayPath(): string;
+export declare function contractExists(): boolean;
+export declare function readContract(): Contract;
+export declare function writeContract(contract: Contract): void;

package/dist/core/storage.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContractDisplayPath = getContractDisplayPath;
+exports.contractExists = contractExists;
+exports.readContract = readContract;
+exports.writeContract = writeContract;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const CONTRACT_PATH = (0, path_1.join)(process.cwd(), ".cliguard", "contract.json");
+/** Contract path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+function getContractDisplayPath() {
+    return (0, path_1.relative)(process.cwd(), CONTRACT_PATH).split("\\").join("/");
+}
+function contractExists() {
+    return (0, fs_1.existsSync)(CONTRACT_PATH);
+}
+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"));
+}
+function writeContract(contract) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(CONTRACT_PATH), { recursive: true });
+    (0, fs_1.writeFileSync)(CONTRACT_PATH, JSON.stringify(contract, null, 2) + "\n", "utf-8");
+}

package/dist/core/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Framework-agnostic representation of a CLI's public surface. Every
+ * adapter (Commander today, Yargs/Clap/Cobra later) normalizes whatever
+ * that framework exposes internally into exactly these shapes - the
+ * diff engine and the `.cliguard/contract.json` file on disk never know
+ * which framework produced a Contract.
+ */
+/** How a captured option carries its value, as declared by the framework - never guessed from parsing text. */
+export type OptionValueType = "boolean" | "string";
+export interface OptionContract {
+    /** Raw flag declaration as the framework received it, e.g. "-o, --output <path>". Informational only - never diffed directly. */
+    readonly flags: string;
+    /** Normalized long-form name with no leading dashes, e.g. "output". This is the diff key. */
+    readonly name: string;
+    /** Short forms / synonyms, e.g. ["-o"]. Order is not significant. */
+    readonly aliases: readonly string[];
+    readonly description: string;
+    /** True for a mandatory option (e.g. Commander's requiredOption). */
+    readonly required: boolean;
+    readonly valueType: OptionValueType;
+    /** True if the option can be passed more than once / collects multiple values. */
+    readonly variadic: boolean;
+    /** JSON-serializable default, or null if the framework declared none. */
+    readonly defaultValue: unknown;
+}
+export interface ArgumentContract {
+    /** Positional argument name, e.g. "file" from "<file>" or "[file]". */
+    readonly name: string;
+    readonly required: boolean;
+    readonly variadic: boolean;
+    readonly description: string;
+}
+export interface CommandContract {
+    readonly name: string;
+    readonly description: string;
+    readonly aliases: readonly string[];
+    readonly options: readonly OptionContract[];
+    readonly arguments: readonly ArgumentContract[];
+    readonly subcommands: readonly CommandContract[];
+}
+/**
+ * The full committed shape of `.cliguard/contract.json`. `contractVersion`
+ * is this *format's* own schema version (bumped only if we change what a
+ * Contract can express), never the target CLI's version.
+ */
+export interface Contract {
+    readonly contractVersion: 1;
+    /** Identifier of the adapter that produced this contract, e.g. "commander". */
+    readonly adapter: string;
+    /** ISO-8601 capture timestamp. Informational only - excluded from diffing. */
+    readonly capturedAt: string;
+    readonly root: CommandContract;
+}
+/** Severity of a single detected difference between two contracts. */
+export declare enum ChangeType {
+    /** Removes or narrows something a caller may already depend on. */
+    BREAKING = "BREAKING",
+    /** Purely additive - existing callers are unaffected. */
+    ADDITIVE = "ADDITIVE",
+    /** Cosmetic only (help text, alias reordering with no collision). */
+    PATCH = "PATCH",
+    /** No difference at all. Not expected to appear in a diff result list. */
+    NONE = "NONE"
+}

package/dist/core/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Framework-agnostic representation of a CLI's public surface. Every
+ * adapter (Commander today, Yargs/Clap/Cobra later) normalizes whatever
+ * that framework exposes internally into exactly these shapes - the
+ * diff engine and the `.cliguard/contract.json` file on disk never know
+ * which framework produced a Contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChangeType = void 0;
+/** Severity of a single detected difference between two contracts. */
+var ChangeType;
+(function (ChangeType) {
+    /** Removes or narrows something a caller may already depend on. */
+    ChangeType["BREAKING"] = "BREAKING";
+    /** Purely additive - existing callers are unaffected. */
+    ChangeType["ADDITIVE"] = "ADDITIVE";
+    /** Cosmetic only (help text, alias reordering with no collision). */
+    ChangeType["PATCH"] = "PATCH";
+    /** No difference at all. Not expected to appear in a diff result list. */
+    ChangeType["NONE"] = "NONE";
+})(ChangeType || (exports.ChangeType = ChangeType = {}));

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "cliguard",
+  "version": "0.1.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",
+  "license": "MIT",
+  "homepage": "https://github.com/Bryandero98/cliguard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bryandero98/cliguard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Bryandero98/cliguard/issues"
+  },
+  "bin": {
+    "cliguard": "dist/bin.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.13",
+    "@types/node": "^22.7.4",
+    "@typescript-eslint/eslint-plugin": "^8.8.0",
+    "@typescript-eslint/parser": "^8.8.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.3.3",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}