cliguard 0.7.3 → 0.8.0

package/README.md

@@ -103,6 +103,14 @@ npx cliguard init ./cli.py --adapter click
 
 Unlike the JS adapters, `click` needs a real Python interpreter: cliguard shells out to `python3` (falling back to `python`) with `click` installed in that same environment - there's no in-process way to introspect a Python object from Node. `pip install click` in whichever Python cliguard's shell can already reach is all that's required; nothing npm-installable covers this one.
 
+Built with [oclif](https://oclif.io/) instead? Point cliguard at the plugin's own root directory (wherever its `package.json` lives) and pass `--adapter oclif`:
+
+```sh
+npx cliguard init ./ --adapter oclif
+```
+
+Unlike every other adapter, this one doesn't need to load your CLI's code at all - oclif already ships a first-class `oclif manifest` command that dumps a complete, structured description of every command's flags and arguments as `oclif.manifest.json`. cliguard reads that file directly if your project already has one (some oclif projects commit it, or produce it as part of their own build), or runs `oclif manifest` itself and cleans up afterward if it doesn't. Either way, `oclif` needs to be a devDependency of the target project - the same one your own `npm run prepack` (or similar) would already need.
+
 ### 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.
@@ -319,6 +327,18 @@ Off by default so it never changes behavior for an existing CI config - opt in p
 
 A `--strict`-only change is real BREAKING output, so `cliguard accept` needs the same flag to find it - `cliguard accept ./bin/cli.js "root -> copy" --strict --reason "..."` - without it, `accept` compares in default (non-strict) mode and won't see the change at all.
 
+## Architecture
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/architecture-dark.svg">
+  <img src="docs/architecture-light.svg" alt="Diagram: cliguard check loads the target CLI through a framework adapter to extract a fresh Contract, compares it against the committed contract.json using DiffEngine, classifies every change as BREAKING, PATCH or ADDITIVE, and exits 1 only if an unacknowledged BREAKING change remains.">
+</picture>
+
+The interesting part isn't the diff - it's getting the CLI's true shape out
+of code that may never export it. See "Entry files that build the CLI
+lazily" below for how the adapter reaches a Commander/CAC/Yargs instance
+that's never assigned to anything exported.
+
 ## Programmatic API
 
 Everything above is the CLI. The same extraction and diff logic is also available as a library, for a custom build script, monorepo tool, or bot that wants to embed a contract check without spawning `npx cliguard` as a subprocess:
@@ -333,7 +353,7 @@ const diff = compareContracts(oldContract, newContract, { strict: true });
 const breaking = diff.filter((change) => change.type === ChangeType.BREAKING);
 ```
 
-`listAdapters()` returns every name `extractContract`'s second argument accepts. `DiffEngine`, every adapter class (`CommanderAdapter`/`CacAdapter`/`YargsAdapter`), and the `toJUnitXml`/`toGitLabCodeQuality`/`toRdjsonl` formatters are all exported too, for anything more custom than the two convenience functions cover.
+`listAdapters()` returns every name `extractContract`'s second argument accepts. `DiffEngine`, every adapter class (`CommanderAdapter`/`CacAdapter`/`YargsAdapter`/`ClickAdapter`/`CobraAdapter`/`OclifAdapter`), and the `toJUnitXml`/`toGitLabCodeQuality`/`toRdjsonl` formatters are all exported too, for anything more custom than the two convenience functions cover.
 
 ## How changes get classified
 
@@ -344,7 +364,7 @@ const breaking = diff.filter((change) => change.type === ChangeType.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.
+Every rule cliguard enforces - including how environment variable bindings and each escape hatch (`accept`/`deprecate`/`[unstable]`) factor in - is documented in full in [`RULES.md`](RULES.md), the same spirit as [oasdiff documenting its own ~755 OpenAPI checks](https://github.com/oasdiff/oasdiff) separately from its source. The underlying implementation and its own tests are [`src/core/diff.engine.ts`](src/core/diff.engine.ts) and [`src/__tests__/diff-engine.test.ts`](src/__tests__/diff-engine.test.ts), if `RULES.md` and the code ever disagree.
 
 ### Reports for non-GitHub CI
 
@@ -366,11 +386,42 @@ npx cliguard check ./bin/cli.js --format rdjsonl | reviewdog -f=rdjsonl -reporte
 
 Same exit code either way - `1` on an unacknowledged BREAKING change, `0` otherwise - so any of the three drops straight into a CI job that already fails the build on a non-zero exit.
 
+### Webhook reporter for SaaS integrations
+
+`--webhook <url>` (or a `CLIGUARD_WEBHOOK_URL` environment variable) POSTs the same diff `check` just computed as JSON to a URL of your choice - the first building block toward the hosted dashboard/Slack-alert roadmap below, v1 scoped to just the POST itself:
+
+```sh
+npx cliguard check ./bin/cli.js --webhook https://example.com/cliguard-hook
+```
+
+```json
+{
+  "entry": "./bin/cli.js",
+  "repo": "git@github.com:you/your-cli.git",
+  "commit": "a1b2c3d4e5f6...",
+  "changes": [
+    { "type": "BREAKING", "path": "root -> option[--target]", "message": "Option \"--target\" was removed." }
+  ]
+}
+```
+
+`repo`/`commit` are best-effort (`git config --get remote.origin.url` / `git rev-parse HEAD`) - `null` outside a git repository. A webhook that's unreachable or slow to respond never fails `check` or changes its exit code - it just prints a warning and moves on.
+
+### `--open-diff`: opening a real difference in your editor
+
+Inspired by how [ApprovalTests](https://approvaltests.com/)' reporters open an external diff tool the moment a test fails - `--open-diff` does the same the moment `check` finds a real difference: it writes the expected and actual contracts to temp files and, if [VS Code](https://code.visualstudio.com/)'s own `code` CLI is on PATH, opens its built-in two-pane diff view on them.
+
+```sh
+npx cliguard check ./bin/cli.js --open-diff
+```
+
+No supported editor found on PATH? cliguard never fails hard over it - it just prints both files' paths instead, so you can open them with whatever you have. Either way, `--open-diff` never changes `check`'s own exit code, and the editor (when one opens) is launched detached from cliguard's own process, so `check` still exits immediately rather than waiting on you to close it.
+
 ## CI integration
 
 `cliguard init --with-ci` scaffolds the workflow below for you - `git add .github/workflows/cliguard.yml` and you're done. Prefer to see it first, or wire it up by hand? Read on.
 
-The bundled GitHub Action (`Bryandero98/cliguard@v1`) is the recommended way to run this in CI: on top of the same exit-code gate as `npx cliguard check`, it posts the diff as a PR comment - updated in place on every push, not a new one each time - so a reviewer sees exactly what changed without opening the CI log:
+The bundled GitHub Action (`Bryandero98/cliguard@v0`) is the recommended way to run this in CI: on top of the same exit-code gate as `npx cliguard check`, it posts the diff as a PR comment - updated in place on every push, not a new one each time - so a reviewer sees exactly what changed without opening the CI log:
 
 ```yaml
 # .github/workflows/cliguard.yml
@@ -386,7 +437,7 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22.x }
       - run: npm ci
-      - uses: Bryandero98/cliguard@v1
+      - uses: Bryandero98/cliguard@v0
         with:
           entry: ./bin/cli.js
           # adapter: yargs        # default: commander
@@ -402,11 +453,15 @@ Set `comment-on-pr: false` to keep the exit-code gate without the comment, or us
 
 ## Supported frameworks
 
-[Commander.js](https://github.com/tj/commander.js) (default), [CAC](https://github.com/cacjs/cac) (`--adapter cac`), and [Yargs](https://github.com/yargs/yargs) (`--adapter yargs`) 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. Click, Clap, and Cobra are the next open gaps - see the [good first issue](https://github.com/Bryandero98/cliguard/labels/good%20first%20issue).
+[Commander.js](https://github.com/tj/commander.js) (default), [CAC](https://github.com/cacjs/cac) (`--adapter cac`), [Yargs](https://github.com/yargs/yargs) (`--adapter yargs`), Python's [Click](https://click.palletsprojects.com/) (`--adapter click`), and [oclif](https://oclif.io/) (`--adapter oclif`, via its own `oclif manifest` command) today, all requiring zero changes to the target CLI itself.
+
+Go's [Cobra](https://github.com/spf13/cobra) (`--adapter cobra`) also exists, but as a **proof of concept only** (see [issue #9](https://github.com/Bryandero98/cliguard/issues/9)) - unlike every adapter above, it needs the target CLI's own author to wire in a hidden dump subcommand (there's no published `cliguard-go` package yet to do that for them). See [`examples/cobra-dump/`](examples/cobra-dump/) for the full example and [`src/adapters/cobra.adapter.ts`](src/adapters/cobra.adapter.ts) for exactly what it does and doesn't cover. Rust's [Clap](https://github.com/clap-rs/clap) (`--adapter clap`) would follow the same pattern (`clap::Command` is introspectable before parsing, same as `clap_complete`/`clap_mangen` already rely on) but isn't built yet - see [issue #10](https://github.com/Bryandero98/cliguard/issues/10).
+
+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.
 
 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). Yargs's own real limitation is the opposite kind - see [`src/adapters/yargs.adapter.ts`](src/adapters/yargs.adapter.ts)'s doc comment for why each command's options are read from a fresh, isolated instance rather than the shared one the target CLI actually built.
 
-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.
+The Commander/CAC/Yargs adapters load the target CLI's entry file into the Node process (`import()`/`require()`) and read its object graph directly - that only works for other Node frameworks. Click and Cobra instead run a small extractor as a subprocess and parse JSON off its stdout, since a Python object graph or a compiled Go binary can't be `require()`'d into Node the way a JS CLI can.
 
 ## Security
 

package/dist/adapters/cac.adapter.js

@@ -25,6 +25,7 @@ class CacAdapter {
             'OptionContract.required is always false - CAC has no declarative "this option must be passed" concept.',
             "CommandContract.subcommands is always [] - CAC's commands are a flat list, not a tree.",
             'ArgumentContract.description is always "" - CAC\'s positional args carry no description field.',
+            "OptionContract.envVar is always undefined - CAC has no built-in concept of satisfying a flag from an environment variable.",
         ];
     }
     async extract(entryPath) {

package/dist/adapters/click.adapter.js

@@ -112,6 +112,17 @@ def main():
                 "required": bool(p.required),
                 "nargs": p.nargs,
             }
+        def resolve_envvar(p):
+            # click.Option.envvar can be a single name, a list of names
+            # (first-match-wins at parse time), or None when envvar= was
+            # never passed - normalized here to "first name or None" so
+            # the TS side only ever deals with a single string or absent,
+            # matching every other adapter's OptionContract.envVar shape.
+            envvar = getattr(p, "envvar", None)
+            if isinstance(envvar, (list, tuple)):
+                return envvar[0] if envvar else None
+            return envvar
+
         return {
             "type": "Option",
             "name": p.name,
@@ -122,6 +133,7 @@ def main():
             "multiple": bool(p.multiple),
             "default": resolve_default(p),
             "help": p.help,
+            "envvar": resolve_envvar(p),
         }
 
     def dump_command(cmd, name):
@@ -173,6 +185,7 @@ class ClickAdapter {
             'OptionContract.valueType collapses every non-flag Click option (string, int, float, choice, path, ...) to "string" - Contract only distinguishes boolean vs. everything else, matching how CacAdapter/YargsAdapter already collapse their own richer type systems.',
             "A --flag/--no-flag paired boolean toggle surfaces as one OptionContract, same as a plain is_flag option - the negative form is only visible informationally inside `flags`, not as a separate field.",
             "Requires a `python3` or `python` on PATH with `click` installed in that same environment - unlike the JS adapters, which only need the target's own node_modules.",
+            "OptionContract.envVar only reflects an explicit `envvar=` on the option - Click's CLI-wide `auto_envvar_prefix` (which derives every option's env var implicitly from its name at parse time, never declared per-option) isn't read. When `envvar=` is a list of names, only the first is surfaced.",
         ];
     }
     async extract(entryPath) {
@@ -242,6 +255,7 @@ class ClickAdapter {
             valueType: param.is_flag ? "boolean" : "string",
             variadic: param.multiple ?? false,
             defaultValue: param.default ?? null,
+            envVar: param.envvar ?? undefined,
         };
     }
     mapArgument(param) {

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

@@ -0,0 +1,35 @@
+import type { Contract } from "../core/types";
+import type { CliAdapter } from "./adapter.interface";
+/**
+ * **Proof of concept, not a shipped integration** - see issue #9. Unlike
+ * every other adapter, cliguard can't `require()`/`import()` a compiled Go
+ * binary into Node, so a Cobra CLI has to expose its own command tree
+ * itself: a hidden `__cliguard_dump__` subcommand
+ * (examples/cobra-dump/clidump/dump.go's `NewDumpCommand`) prints it as
+ * JSON on stdout, and this adapter runs that subcommand as a subprocess
+ * and parses the output - no different in spirit from how ClickAdapter
+ * already shells out to a real Python interpreter instead of introspecting
+ * in-process.
+ *
+ * A real `cliguard-go` package doesn't exist yet (see the issue) - the
+ * target CLI's own author would today have to vendor a copy of
+ * examples/cobra-dump/clidump/dump.go directly and wire in
+ * `rootCmd.AddCommand(clidump.NewDumpCommand(rootCmd))` themselves. This
+ * adapter only proves the rest of the pattern (subprocess -> JSON ->
+ * Contract) actually works end to end against a real Cobra CLI.
+ *
+ * `entryPath` is either:
+ * - a compiled Cobra binary - run directly as `<entryPath> __cliguard_dump__`.
+ * - a `.go` file or a directory - run via `go run . __cliguard_dump__`
+ *   (requires a `go` toolchain on PATH), which is how the example CLI
+ *   under examples/cobra-dump is exercised without a separate build step.
+ */
+export declare class CobraAdapter implements CliAdapter {
+    readonly id = "cobra";
+    readonly limitations: readonly string[];
+    extract(entryPath: string): Promise<Contract>;
+    private runDump;
+    private mapCommand;
+    private mapOption;
+    private parseDefault;
+}

package/dist/adapters/cobra.adapter.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CobraAdapter = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** The dump subcommand every Cobra target CLI must expose - see examples/cobra-dump/clidump/dump.go. */
+const DUMP_SUBCOMMAND = "__cliguard_dump__";
+/**
+ * **Proof of concept, not a shipped integration** - see issue #9. Unlike
+ * every other adapter, cliguard can't `require()`/`import()` a compiled Go
+ * binary into Node, so a Cobra CLI has to expose its own command tree
+ * itself: a hidden `__cliguard_dump__` subcommand
+ * (examples/cobra-dump/clidump/dump.go's `NewDumpCommand`) prints it as
+ * JSON on stdout, and this adapter runs that subcommand as a subprocess
+ * and parses the output - no different in spirit from how ClickAdapter
+ * already shells out to a real Python interpreter instead of introspecting
+ * in-process.
+ *
+ * A real `cliguard-go` package doesn't exist yet (see the issue) - the
+ * target CLI's own author would today have to vendor a copy of
+ * examples/cobra-dump/clidump/dump.go directly and wire in
+ * `rootCmd.AddCommand(clidump.NewDumpCommand(rootCmd))` themselves. This
+ * adapter only proves the rest of the pattern (subprocess -> JSON ->
+ * Contract) actually works end to end against a real Cobra CLI.
+ *
+ * `entryPath` is either:
+ * - a compiled Cobra binary - run directly as `<entryPath> __cliguard_dump__`.
+ * - a `.go` file or a directory - run via `go run . __cliguard_dump__`
+ *   (requires a `go` toolchain on PATH), which is how the example CLI
+ *   under examples/cobra-dump is exercised without a separate build step.
+ */
+class CobraAdapter {
+    constructor() {
+        this.id = "cobra";
+        this.limitations = [
+            "Proof of concept (see issue #9): there is no published `cliguard-go` package yet - the target CLI's own author must vendor an equivalent of examples/cobra-dump/clidump/dump.go and wire in `rootCmd.AddCommand(clidump.NewDumpCommand(rootCmd))` themselves, unlike every other adapter which needs zero changes to the target (Click included).",
+            "ArgumentContract is always [] - Cobra's Args validators (cobra.ExactArgs(1), cobra.MinimumNArgs(1), ...) carry no per-argument name or description, unlike Commander's .argument('<file>', ...).",
+            "CommandContract.description comes from Cobra's Short text only - Long is never read.",
+            'OptionContract.valueType collapses every pflag type (string, int, stringSlice, ...) to "boolean" vs "string", the same simplification CacAdapter/YargsAdapter/ClickAdapter already make.',
+            "defaultValue is parsed from pflag's own DefValue string representation - correct for primitives and slices, but a flag whose default is itself a JSON-looking string could round-trip wrong.",
+            "A .go entry is run via `go run . <dump-subcommand>`, requiring a `go` toolchain on PATH - a compiled binary entry has no such requirement, matching how a real published cliguard-go integration would be used.",
+            "OptionContract.envVar is always undefined - Cobra/pflag itself has no built-in env var binding (that's normally layered on via viper, which this PoC's dump command doesn't wire in).",
+        ];
+    }
+    async extract(entryPath) {
+        const absolutePath = (0, path_1.resolve)(process.cwd(), entryPath);
+        if (!(0, fs_1.existsSync)(absolutePath)) {
+            throw new Error(`cliguard: no such file or directory: "${absolutePath}".`);
+        }
+        const json = this.runDump(absolutePath);
+        return {
+            contractVersion: 1,
+            adapter: this.id,
+            capturedAt: new Date().toISOString(),
+            root: this.mapCommand(json),
+        };
+    }
+    runDump(absolutePath) {
+        const isDirectory = (0, fs_1.statSync)(absolutePath).isDirectory();
+        const isGoSource = isDirectory || (0, path_1.extname)(absolutePath) === ".go";
+        const result = isGoSource
+            ? (0, child_process_1.spawnSync)("go", ["run", ".", DUMP_SUBCOMMAND], {
+                cwd: isDirectory ? absolutePath : (0, path_1.dirname)(absolutePath),
+                encoding: "utf8",
+            })
+            : (0, child_process_1.spawnSync)(absolutePath, [DUMP_SUBCOMMAND], { encoding: "utf8" });
+        if (result.error) {
+            throw new Error(`cliguard: failed to run the Cobra target at "${absolutePath}": ${result.error.message}` +
+                (isGoSource ? ' - is a Go toolchain ("go") installed and on PATH?' : ""));
+        }
+        if (result.status !== 0) {
+            throw new Error(`cliguard: the Cobra target at "${absolutePath}" exited with code ${result.status} ` +
+                `running "${DUMP_SUBCOMMAND}" - does it call rootCmd.AddCommand(clidump.NewDumpCommand(rootCmd))? ` +
+                `(see examples/cobra-dump)\n${result.stderr.trim()}`);
+        }
+        try {
+            return JSON.parse(result.stdout);
+        }
+        catch {
+            throw new Error(`cliguard: internal error - the Cobra dump command's output wasn't valid JSON:\n${result.stdout}`);
+        }
+    }
+    mapCommand(json) {
+        return {
+            name: json.name,
+            description: json.short,
+            aliases: json.aliases,
+            options: json.flags.map((flag) => this.mapOption(flag)),
+            // See class limitations: Cobra's Args validators carry no per-argument metadata.
+            arguments: [],
+            subcommands: json.subcommands.map((sub) => this.mapCommand(sub)),
+        };
+    }
+    mapOption(flag) {
+        const valueType = flag.valueType === "bool" ? "boolean" : "string";
+        const isBoolean = valueType === "boolean";
+        const flags = (flag.shorthand ? `-${flag.shorthand}, ` : "") +
+            `--${flag.name}` +
+            (isBoolean ? "" : ` <${flag.name}>`);
+        return {
+            flags,
+            name: flag.name,
+            aliases: flag.shorthand ? [`-${flag.shorthand}`] : [],
+            description: flag.usage,
+            required: flag.required,
+            valueType,
+            variadic: /slice|array/i.test(flag.valueType),
+            defaultValue: this.parseDefault(flag.defValue, valueType),
+        };
+    }
+    parseDefault(raw, valueType) {
+        if (raw === "")
+            return null;
+        if (valueType === "boolean")
+            return raw === "true";
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+}
+exports.CobraAdapter = CobraAdapter;

package/dist/adapters/commander.adapter.js

@@ -131,6 +131,10 @@ class CommanderAdapter {
             valueType: this.inferValueType(option.flags),
             variadic: option.variadic ?? false,
             defaultValue: option.defaultValue ?? null,
+            // Commander's own Option.envVar, set via `.env("NAME")` - undefined
+            // (not stored at all) when never called, matching OptionContract's
+            // own `envVar?:` shape.
+            envVar: option.envVar,
         };
     }
     /** `<value>` = required value, `[value]` = optional value, neither = boolean flag. Read from Commander's own flag declaration, not rendered --help text. */

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

@@ -0,0 +1,47 @@
+import type { Contract } from "../core/types";
+import type { CliAdapter } from "./adapter.interface";
+/**
+ * Extracts a Contract from an oclif CLI project by reading its manifest -
+ * `oclif.manifest.json`, the same structured JSON oclif's own `oclif
+ * manifest` command produces (and which some oclif projects already commit,
+ * e.g. to speed up their own startup/README generation). Unlike Cobra or
+ * Click, no subprocess-based introspection script had to be written for
+ * this adapter: oclif already ships a first-class command that dumps a
+ * complete, versioned description of every command's flags and positional
+ * arguments as JSON - this adapter only has to run it (when needed) and map
+ * its shape onto `Contract`.
+ *
+ * `entryPath` is either:
+ * - a path to an already-generated `oclif.manifest.json` file - read directly, no subprocess.
+ * - a path to the oclif project's root directory (containing `package.json`)
+ *   - if that directory already has its own `oclif.manifest.json` (common:
+ *     some projects commit it, or a build step already produced it), that
+ *     file is read as-is; otherwise this runs `npx oclif manifest .` there
+ *     (requiring `oclif` installed as a devDependency) and removes the
+ *     file it generated once done, leaving the project tree untouched.
+ *
+ * oclif's own command tree is flat, not nested the way Commander's is -
+ * every command has one `id` with `:` separating topic levels (e.g.
+ * `"config:get"`) rather than a real parent/child object graph. This
+ * adapter rebuilds the nested `CommandContract` tree `Contract` expects by
+ * splitting each id on `:`, synthesizing an empty topic node for any
+ * intermediate segment that isn't itself a real command (e.g. `"config"`
+ * when only `"config:get"` exists), matching how a real oclif CLI's own
+ * `--help` groups things.
+ */
+export declare class OclifAdapter implements CliAdapter {
+    readonly id = "oclif";
+    readonly limitations: readonly string[];
+    extract(entryPath: string): Promise<Contract>;
+    private loadManifest;
+    private generateManifest;
+    private parseManifestFile;
+    /** Prefers the target's own package.json "name" (the CLI's real identity); falls back to a command's own `pluginName`, then a generic default - a manifest with zero commands has neither. */
+    private inferRootName;
+    private buildTree;
+    private makeNode;
+    private toCommandContract;
+    private mapFlags;
+    private mapFlag;
+    private mapArgs;
+}

package/dist/adapters/oclif.adapter.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OclifAdapter = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/** The file `oclif manifest` writes - see https://oclif.io, the CLI's own "manifest" plugin command. */
+const MANIFEST_FILENAME = "oclif.manifest.json";
+/**
+ * Extracts a Contract from an oclif CLI project by reading its manifest -
+ * `oclif.manifest.json`, the same structured JSON oclif's own `oclif
+ * manifest` command produces (and which some oclif projects already commit,
+ * e.g. to speed up their own startup/README generation). Unlike Cobra or
+ * Click, no subprocess-based introspection script had to be written for
+ * this adapter: oclif already ships a first-class command that dumps a
+ * complete, versioned description of every command's flags and positional
+ * arguments as JSON - this adapter only has to run it (when needed) and map
+ * its shape onto `Contract`.
+ *
+ * `entryPath` is either:
+ * - a path to an already-generated `oclif.manifest.json` file - read directly, no subprocess.
+ * - a path to the oclif project's root directory (containing `package.json`)
+ *   - if that directory already has its own `oclif.manifest.json` (common:
+ *     some projects commit it, or a build step already produced it), that
+ *     file is read as-is; otherwise this runs `npx oclif manifest .` there
+ *     (requiring `oclif` installed as a devDependency) and removes the
+ *     file it generated once done, leaving the project tree untouched.
+ *
+ * oclif's own command tree is flat, not nested the way Commander's is -
+ * every command has one `id` with `:` separating topic levels (e.g.
+ * `"config:get"`) rather than a real parent/child object graph. This
+ * adapter rebuilds the nested `CommandContract` tree `Contract` expects by
+ * splitting each id on `:`, synthesizing an empty topic node for any
+ * intermediate segment that isn't itself a real command (e.g. `"config"`
+ * when only `"config:get"` exists), matching how a real oclif CLI's own
+ * `--help` groups things.
+ */
+class OclifAdapter {
+    constructor() {
+        this.id = "oclif";
+        this.limitations = [
+            'CommandContract tree is rebuilt from oclif\'s flat, colon-separated command ids (e.g. "config:get") - an intermediate topic with no command of its own (e.g. "config" when only "config:get" exists) appears as an empty synthetic node purely to hold its children.',
+            "ArgumentContract.variadic is always false - oclif's manifest carries no per-argument multiple-values concept; a command declaring `static strict = false` to accept unlimited extra positional args doesn't surface those extra args as a named argument at all.",
+            'OptionContract.valueType collapses every oclif flag kind (string, integer, url, ...) to "boolean" vs "string", the same simplification every adapter besides Commander already makes.',
+            "Requires generating (or reading an already-committed) oclif.manifest.json in the target project - when one doesn't already exist, this shells out to `npx oclif manifest .` (requiring `oclif` installed as a devDependency there) and removes the file it generated once done.",
+            "A single-command oclif CLI (package.json's `oclif.default`) may not appear as a distinct entry in the manifest at all, depending on the oclif version - verify with `cliguard doctor` before relying on it for that shape of CLI.",
+        ];
+    }
+    async extract(entryPath) {
+        const absolutePath = (0, path_1.resolve)(process.cwd(), entryPath);
+        if (!(0, fs_1.existsSync)(absolutePath)) {
+            throw new Error(`cliguard: no such file or directory: "${absolutePath}".`);
+        }
+        const manifest = this.loadManifest(absolutePath);
+        const rootName = this.inferRootName(absolutePath, manifest);
+        return {
+            contractVersion: 1,
+            adapter: this.id,
+            capturedAt: new Date().toISOString(),
+            root: this.buildTree(rootName, manifest),
+        };
+    }
+    loadManifest(absolutePath) {
+        if ((0, path_1.extname)(absolutePath) === ".json") {
+            return this.parseManifestFile(absolutePath);
+        }
+        const manifestPath = (0, path_1.join)(absolutePath, MANIFEST_FILENAME);
+        const alreadyExisted = (0, fs_1.existsSync)(manifestPath);
+        if (!alreadyExisted) {
+            this.generateManifest(absolutePath);
+        }
+        try {
+            return this.parseManifestFile(manifestPath);
+        }
+        finally {
+            // Only clean up a manifest this adapter itself produced as a
+            // side effect - one the target project already committed is left
+            // exactly as it was found.
+            if (!alreadyExisted) {
+                try {
+                    (0, fs_1.rmSync)(manifestPath, { force: true });
+                }
+                catch {
+                    // Best-effort cleanup - a stray oclif.manifest.json left behind
+                    // is a minor annoyance, never worth failing extraction over.
+                }
+            }
+        }
+    }
+    generateManifest(projectDir) {
+        // `shell: true` only on win32, where `npx` itself is a `.cmd` shim
+        // that Node's spawnSync can't invoke directly (a well-known Windows
+        // gotcha - verified live: without it this fails with EINVAL/ENOENT
+        // regardless of PATH). Every argument here is a fixed literal, never
+        // interpolated from `projectDir` or any other dynamic value - it's
+        // passed via `cwd` instead - so shell mode carries no injection risk
+        // despite Node's own generic deprecation warning about it.
+        const result = (0, child_process_1.spawnSync)("npx", ["--no-install", "oclif", "manifest", "."], {
+            cwd: projectDir,
+            encoding: "utf8",
+            shell: process.platform === "win32",
+        });
+        if (result.error) {
+            throw new Error(`cliguard: failed to run \`oclif manifest\` in "${projectDir}": ${result.error.message} - ` +
+                'is "oclif" installed as a devDependency there?');
+        }
+        if (result.status !== 0) {
+            throw new Error(`cliguard: \`oclif manifest\` exited with code ${result.status} in "${projectDir}" - ` +
+                'is "oclif" installed as a devDependency, and does its package.json have a valid "oclif" field?\n' +
+                (result.stderr.trim() || result.stdout.trim()));
+        }
+    }
+    parseManifestFile(manifestPath) {
+        if (!(0, fs_1.existsSync)(manifestPath)) {
+            throw new Error(`cliguard: no such file: "${manifestPath}" - expected an oclif manifest. Run ` +
+                "`oclif manifest` in the plugin's root first, or point cliguard directly at that project directory.");
+        }
+        let raw;
+        try {
+            raw = (0, fs_1.readFileSync)(manifestPath, "utf8");
+        }
+        catch (error) {
+            throw new Error(`cliguard: could not read "${manifestPath}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`cliguard: internal error - "${manifestPath}" wasn't valid JSON.`);
+        }
+    }
+    /** Prefers the target's own package.json "name" (the CLI's real identity); falls back to a command's own `pluginName`, then a generic default - a manifest with zero commands has neither. */
+    inferRootName(absolutePath, manifest) {
+        const projectDir = (0, path_1.extname)(absolutePath) === ".json" ? (0, path_1.dirname)(absolutePath) : absolutePath;
+        const packageJsonPath = (0, path_1.join)(projectDir, "package.json");
+        if ((0, fs_1.existsSync)(packageJsonPath)) {
+            try {
+                const pkg = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, "utf8"));
+                if (typeof pkg.name === "string" && pkg.name)
+                    return pkg.name;
+            }
+            catch {
+                // Falls through to the manifest-derived name below - an unreadable
+                // or malformed package.json alongside a perfectly good manifest
+                // shouldn't block extraction entirely.
+            }
+        }
+        const firstCommand = Object.values(manifest.commands)[0];
+        return firstCommand?.pluginName ?? "cli";
+    }
+    buildTree(rootName, manifest) {
+        const root = this.makeNode(rootName);
+        for (const [id, command] of Object.entries(manifest.commands)) {
+            const segments = id.split(":").filter((segment) => segment.length > 0);
+            let node = root;
+            for (const segment of segments) {
+                let child = node.children.get(segment);
+                if (!child) {
+                    child = this.makeNode(segment);
+                    node.children.set(segment, child);
+                }
+                node = child;
+            }
+            // `segments` is empty for a single-command CLI's own id (`""`) -
+            // its properties land directly on `root` in that case, same as any
+            // other command lands on the node its own path resolves to.
+            node.description = command.description ?? "";
+            node.aliases = [...(command.aliases ?? [])];
+            node.options = this.mapFlags(command.flags);
+            node.arguments = this.mapArgs(command.args);
+        }
+        return this.toCommandContract(root);
+    }
+    makeNode(name) {
+        return { name, description: "", aliases: [], options: [], arguments: [], children: new Map() };
+    }
+    toCommandContract(node) {
+        return {
+            name: node.name,
+            description: node.description,
+            aliases: node.aliases,
+            options: node.options,
+            arguments: node.arguments,
+            subcommands: [...node.children.values()].map((child) => this.toCommandContract(child)),
+        };
+    }
+    mapFlags(flags) {
+        return Object.entries(flags ?? {}).map(([name, flag]) => this.mapFlag(name, flag));
+    }
+    mapFlag(name, flag) {
+        const valueType = flag.type === "boolean" ? "boolean" : "string";
+        const long = `--${name}` + (valueType === "boolean" ? "" : ` <${name}>`);
+        return {
+            flags: flag.char ? `-${flag.char}, ${long}` : long,
+            name,
+            aliases: flag.char ? [`-${flag.char}`] : [],
+            description: flag.description ?? "",
+            required: flag.required ?? false,
+            valueType,
+            variadic: flag.multiple ?? false,
+            defaultValue: flag.default ?? null,
+            envVar: flag.env,
+        };
+    }
+    mapArgs(args) {
+        return Object.entries(args ?? {}).map(([name, arg]) => ({
+            name,
+            required: arg.required ?? false,
+            // See class limitations: oclif's manifest has no per-argument
+            // multiple-values concept.
+            variadic: false,
+            description: arg.description ?? "",
+        }));
+    }
+}
+exports.OclifAdapter = OclifAdapter;

package/dist/adapters/registry.js

@@ -4,7 +4,9 @@ exports.adapters = void 0;
 exports.resolveAdapter = resolveAdapter;
 const cac_adapter_1 = require("./cac.adapter");
 const click_adapter_1 = require("./click.adapter");
+const cobra_adapter_1 = require("./cobra.adapter");
 const commander_adapter_1 = require("./commander.adapter");
+const oclif_adapter_1 = require("./oclif.adapter");
 const yargs_adapter_1 = require("./yargs.adapter");
 // Constructing an adapter here is cheap (no eager require of its
 // framework - CacAdapter/YargsAdapter only load their framework lazily,
@@ -18,6 +20,8 @@ exports.adapters = {
     cac: new cac_adapter_1.CacAdapter(),
     yargs: new yargs_adapter_1.YargsAdapter(),
     click: new click_adapter_1.ClickAdapter(),
+    cobra: new cobra_adapter_1.CobraAdapter(),
+    oclif: new oclif_adapter_1.OclifAdapter(),
 };
 function resolveAdapter(name) {
     const adapter = exports.adapters[name];

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

@@ -89,6 +89,20 @@ export declare class YargsAdapter implements CliAdapter {
      * `arguments`, never duplicated into `options`.
      */
     private mapOptions;
+    /**
+     * Yargs has no *per-option* declared env var name (unlike Commander's
+     * `.env("NAME")`) - `.env(prefix)` instead turns on a blanket naming
+     * convention for every option at once, applied at real parse time by
+     * yargs-parser's own `applyEnvVars` (see yargs-parser's
+     * `yargs-parser.js`): an env var matching `<PREFIX_><NAME>` (uppercased,
+     * `-`/camelCase boundaries as `_`) satisfies the option named `<name>`
+     * unless the value was already supplied another way. This reconstructs
+     * that same name from the option side - the exact inverse of
+     * yargs-parser's own camelCase decoding - so it's a real, verified
+     * convention, not a guess. Returns `undefined` when `.env()` was never
+     * called, matching every other adapter's "no binding" shape.
+     */
+    private deriveEnvVar;
     private describe;
     /** `-x` for a single-character name, `--xray` otherwise - yargs's own alias lists carry neither dash. */
     private dashPrefix;

package/dist/adapters/yargs.adapter.js

@@ -26,6 +26,7 @@ class YargsAdapter {
         this.id = "yargs";
         this.limitations = [
             "Each command's options are read from a fresh, isolated yargs instance built by re-running that command's builder, not the shared instance the target CLI actually built - see this class's own doc comment for why.",
+            "OptionContract.envVar is reconstructed from yargs's own `.env(prefix)` naming convention (PREFIX_OPTION_NAME), not read from a per-option declaration the way Commander's `.env(\"NAME\")` is - a name using yargs-parser's `__` nested-key separator won't round-trip correctly.",
         ];
     }
     async extract(entryPath) {
@@ -175,13 +176,18 @@ class YargsAdapter {
         const commandInstance = cli.getInternalMethods().getCommandInstance();
         const options = cli.getOptions();
         const descriptions = cli.getInternalMethods().getUsageInstance().getDescriptions();
+        // `.env()` is only ever set on the real, shared top-level instance -
+        // every subcommand's own options are read from a fresh, isolated
+        // instance further down (see mapCommand) that never had it called, so
+        // this is captured here once and threaded down explicitly instead.
+        const envPrefix = options.envPrefix;
         return {
             name: cli.$0,
             description: "",
             aliases: [],
-            options: this.mapOptions(options, descriptions, new Set()),
+            options: this.mapOptions(options, descriptions, new Set(), envPrefix),
             arguments: [],
-            subcommands: Object.entries(commandInstance.handlers).map(([name, handler]) => this.mapCommand(name, handler, commandInstance.aliasMap)),
+            subcommands: Object.entries(commandInstance.handlers).map(([name, handler]) => this.mapCommand(name, handler, commandInstance.aliasMap, envPrefix)),
         };
     }
     /**
@@ -194,7 +200,7 @@ class YargsAdapter {
      * CommanderAdapter/CacAdapter, neither of which surfaces their
      * framework's built-in help/version as a regular option either.
      */
-    mapCommand(name, handler, parentAliasMap) {
+    mapCommand(name, handler, parentAliasMap, envPrefix) {
         const scoped = this.freshInstance();
         if (typeof handler.builder === "function") {
             handler.builder(scoped, false);
@@ -213,9 +219,9 @@ class YargsAdapter {
             aliases: Object.entries(parentAliasMap)
                 .filter(([, canonical]) => canonical === name)
                 .map(([alias]) => alias),
-            options: this.mapOptions(options, descriptions, positionalNames),
+            options: this.mapOptions(options, descriptions, positionalNames, envPrefix),
             arguments: this.mapArguments(handler, descriptions),
-            subcommands: Object.entries(commandInstance.handlers).map(([subName, subHandler]) => this.mapCommand(subName, subHandler, commandInstance.aliasMap)),
+            subcommands: Object.entries(commandInstance.handlers).map(([subName, subHandler]) => this.mapCommand(subName, subHandler, commandInstance.aliasMap, envPrefix)),
         };
     }
     freshInstance() {
@@ -247,7 +253,7 @@ class YargsAdapter {
      * internally) - excluded via `positionalNames` so they surface only in
      * `arguments`, never duplicated into `options`.
      */
-    mapOptions(options, descriptions, positionalNames) {
+    mapOptions(options, descriptions, positionalNames, envPrefix) {
         const aliasTargets = new Set(Object.values(options.alias).flat());
         const allNames = new Set([
             ...options.boolean,
@@ -271,8 +277,32 @@ class YargsAdapter {
             valueType: this.inferValueType(options, name),
             variadic: options.array.includes(name),
             defaultValue: name in options.default ? options.default[name] : null,
+            envVar: this.deriveEnvVar(envPrefix, name),
         }));
     }
+    /**
+     * Yargs has no *per-option* declared env var name (unlike Commander's
+     * `.env("NAME")`) - `.env(prefix)` instead turns on a blanket naming
+     * convention for every option at once, applied at real parse time by
+     * yargs-parser's own `applyEnvVars` (see yargs-parser's
+     * `yargs-parser.js`): an env var matching `<PREFIX_><NAME>` (uppercased,
+     * `-`/camelCase boundaries as `_`) satisfies the option named `<name>`
+     * unless the value was already supplied another way. This reconstructs
+     * that same name from the option side - the exact inverse of
+     * yargs-parser's own camelCase decoding - so it's a real, verified
+     * convention, not a guess. Returns `undefined` when `.env()` was never
+     * called, matching every other adapter's "no binding" shape.
+     */
+    deriveEnvVar(envPrefix, name) {
+        if (envPrefix === undefined || envPrefix === false)
+            return undefined;
+        const prefix = typeof envPrefix === "string" ? envPrefix : "";
+        const decamelized = name
+            .replace(/-/g, "_")
+            .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+            .toUpperCase();
+        return prefix ? `${prefix}_${decamelized}` : decamelized;
+    }
     describe(descriptions, name) {
         const raw = descriptions[name] ?? "";
         return raw.startsWith(YARGS_STRING_MARKER) ? raw.slice(YARGS_STRING_MARKER.length) : raw;

package/dist/bin.js

@@ -7,7 +7,9 @@ const registry_1 = require("./adapters/registry");
 const config_1 = require("./core/config");
 const diff_engine_1 = require("./core/diff.engine");
 const docs_1 = require("./core/docs");
+const open_diff_1 = require("./core/open-diff");
 const report_formats_1 = require("./core/report-formats");
+const webhook_1 = require("./core/webhook");
 const storage_1 = require("./core/storage");
 const types_1 = require("./core/types");
 const diffEngine = new diff_engine_1.DiffEngine();
@@ -122,8 +124,11 @@ program
     .option("--format <format>", `output format: ${REPORT_FORMATS.join(", ")}`)
     .option("--against <ref>", "compare against a git ref's committed contract (e.g. origin/main, a tag, a commit sha) instead of the .cliguard/contract.json on disk")
     .option("--strict", "enable extra rules for currently-silent risky changes (e.g. a positional argument reorder)", false)
+    .option("--webhook <url>", "POST the diff result as JSON to this URL after check runs (or set CLIGUARD_WEBHOOK_URL)")
+    .option("--open-diff", "on a real difference, write the expected/actual contracts to temp files and open them in your editor's diff view (falls back to printing the file paths if no supported editor is found)", false)
     .action(async (entry, options) => {
     const targets = resolveTargetsOrExit(entry, options.adapter);
+    const webhookUrl = options.webhook ?? process.env.CLIGUARD_WEBHOOK_URL;
     const exitCode = await runAcrossTargets(targets, (target) => withSuppressedExit(async () => {
         const format = resolveFormat(options.format, options.json);
         if (!format) {
@@ -137,6 +142,22 @@ program
         const diff = applyDeprecations(diffEngine.applyUnstableMarkers((0, config_1.applyConfig)(diffEngine.compare(oldContract, newContract, { strict: options.strict }), (0, config_1.loadConfig)()), oldContract, newContract), indexDeprecations((0, storage_1.readDeprecations)(target.namespace)));
         const acceptedPaths = indexAcceptedBreaks((0, storage_1.readAcceptedBreaks)(target.namespace));
         const hasBreaking = diff.some((change) => change.type === types_1.ChangeType.BREAKING && !acceptedPaths.has(change.path));
+        if (options.openDiff && diff.length > 0) {
+            const opened = (0, open_diff_1.openDiffInEditor)(oldContract, newContract, (0, open_diff_1.detectDiffTool)());
+            console.log(opened.openedWith
+                ? `🔍 --open-diff: opened ${opened.openedWith} --diff on the expected vs. actual contract.`
+                : "ℹ️  --open-diff: no supported editor found on PATH - contracts written to:\n" +
+                    `   expected: ${opened.oldPath}\n` +
+                    `   actual:   ${opened.newPath}`);
+        }
+        if (webhookUrl) {
+            try {
+                await (0, webhook_1.postWebhook)(webhookUrl, (0, webhook_1.buildWebhookPayload)(target.entry, diff));
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+            }
+        }
         if (format !== "text") {
             console.log(formatReport(diff, acceptedPaths, format, (0, storage_1.getContractDisplayPath)(target.namespace)));
             return hasBreaking ? 1 : 0;

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

@@ -66,6 +66,17 @@ export declare class DiffEngine {
     private commandLabel;
     private compareOptions;
     private compareOption;
+    /**
+     * `envVar` is a single optional binding (unlike `aliases`, a set), so it
+     * gets its own three-way comparison rather than reusing `compareAliases`:
+     * losing the *only* way an env var could satisfy this flag is BREAKING
+     * (an existing invocation that only ever set the env var, never the flag
+     * itself, silently stops working), gaining one is purely ADDITIVE (every
+     * existing invocation keeps working exactly as before), and renaming it
+     * is BREAKING too - from a caller's perspective that's the same as
+     * losing the old binding, even though a new one appears in its place.
+     */
+    private compareEnvVar;
     private compareArguments;
     /**
      * `--strict`-only: positional arguments are matched by name everywhere

package/dist/core/diff.engine.js

@@ -235,6 +235,7 @@ class DiffEngine {
             });
         }
         results.push(...this.compareAliases(oldOption.aliases, newOption.aliases, path, label));
+        results.push(...this.compareEnvVar(oldOption.envVar, newOption.envVar, path, label));
         if (oldOption.description !== newOption.description) {
             results.push({
                 type: types_1.ChangeType.PATCH,
@@ -244,6 +245,45 @@ class DiffEngine {
         }
         return results;
     }
+    /**
+     * `envVar` is a single optional binding (unlike `aliases`, a set), so it
+     * gets its own three-way comparison rather than reusing `compareAliases`:
+     * losing the *only* way an env var could satisfy this flag is BREAKING
+     * (an existing invocation that only ever set the env var, never the flag
+     * itself, silently stops working), gaining one is purely ADDITIVE (every
+     * existing invocation keeps working exactly as before), and renaming it
+     * is BREAKING too - from a caller's perspective that's the same as
+     * losing the old binding, even though a new one appears in its place.
+     */
+    compareEnvVar(oldEnvVar, newEnvVar, path, label) {
+        if (oldEnvVar === newEnvVar)
+            return [];
+        if (oldEnvVar && !newEnvVar) {
+            return [
+                {
+                    type: types_1.ChangeType.BREAKING,
+                    path,
+                    message: `${label} no longer reads from environment variable "${oldEnvVar}" - an invocation relying on that env var instead of the flag itself will silently stop working.`,
+                },
+            ];
+        }
+        if (!oldEnvVar && newEnvVar) {
+            return [
+                {
+                    type: types_1.ChangeType.ADDITIVE,
+                    path,
+                    message: `${label} can now also be set via environment variable "${newEnvVar}".`,
+                },
+            ];
+        }
+        return [
+            {
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `${label} environment variable binding changed from "${oldEnvVar}" to "${newEnvVar}" - an invocation relying on "${oldEnvVar}" will silently stop working.`,
+            },
+        ];
+    }
     compareArguments(oldArgs, newArgs, path, options) {
         const results = [];
         const oldByName = this.indexByName(oldArgs);

package/dist/core/open-diff.d.ts

@@ -0,0 +1,39 @@
+import type { Contract } from "./types";
+/**
+ * `cliguard check --open-diff`'s local equivalent of ApprovalTests'
+ * reporters, which open an external diff tool the moment a test fails -
+ * here, the moment a real contract difference is found. Deliberately
+ * simple: one known editor (VS Code's own `code` CLI, which ships a
+ * built-in two-pane `--diff` view) probed for on PATH, with a plain
+ * "here are the file paths" fallback when it isn't there - never a hard
+ * failure, and never anything that changes `check`'s own exit code.
+ */
+export interface DiffTool {
+    readonly command: string;
+    readonly buildArgs: (oldPath: string, newPath: string) => string[];
+}
+/**
+ * True if `command --version` runs successfully - the simplest portable
+ * "is this on PATH" probe, without depending on `which`/`where` (neither
+ * of which exists on every platform cliguard runs on).
+ */
+export declare function isCommandAvailable(command: string): boolean;
+/** `isAvailable` is injectable purely so tests can exercise both branches without depending on whether a real editor happens to be on the test runner's own PATH. */
+export declare function detectDiffTool(tools?: readonly DiffTool[], isAvailable?: (command: string) => boolean): DiffTool | undefined;
+export interface OpenDiffResult {
+    readonly oldPath: string;
+    readonly newPath: string;
+    /** The diff tool's own command name, present only if one was actually found and launched. */
+    readonly openedWith?: string;
+}
+/**
+ * Writes both contracts to a fresh temp directory as pretty-printed JSON,
+ * then - if `tool` is given (the caller's own `detectDiffTool()` result,
+ * not defaulted here so a test can pass `undefined` and mean it) - opens
+ * them there, detached from cliguard's own process so `check` still exits
+ * immediately with its normal code instead of waiting on the editor
+ * window to close. Never throws: a tool that fails to actually launch
+ * still leaves both files on disk, which is all the caller falls back to
+ * printing anyway.
+ */
+export declare function openDiffInEditor(oldContract: Contract, newContract: Contract, tool: DiffTool | undefined): OpenDiffResult;

package/dist/core/open-diff.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCommandAvailable = isCommandAvailable;
+exports.detectDiffTool = detectDiffTool;
+exports.openDiffInEditor = openDiffInEditor;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const DIFF_TOOLS = [
+    { command: "code", buildArgs: (a, b) => ["--diff", a, b] },
+];
+/**
+ * True if `command --version` runs successfully - the simplest portable
+ * "is this on PATH" probe, without depending on `which`/`where` (neither
+ * of which exists on every platform cliguard runs on).
+ */
+function isCommandAvailable(command) {
+    const result = (0, child_process_1.spawnSync)(command, ["--version"], {
+        encoding: "utf8",
+        shell: process.platform === "win32",
+    });
+    return !result.error && result.status === 0;
+}
+/** `isAvailable` is injectable purely so tests can exercise both branches without depending on whether a real editor happens to be on the test runner's own PATH. */
+function detectDiffTool(tools = DIFF_TOOLS, isAvailable = isCommandAvailable) {
+    return tools.find((tool) => isAvailable(tool.command));
+}
+/**
+ * Writes both contracts to a fresh temp directory as pretty-printed JSON,
+ * then - if `tool` is given (the caller's own `detectDiffTool()` result,
+ * not defaulted here so a test can pass `undefined` and mean it) - opens
+ * them there, detached from cliguard's own process so `check` still exits
+ * immediately with its normal code instead of waiting on the editor
+ * window to close. Never throws: a tool that fails to actually launch
+ * still leaves both files on disk, which is all the caller falls back to
+ * printing anyway.
+ */
+function openDiffInEditor(oldContract, newContract, tool) {
+    const dir = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "cliguard-diff-"));
+    const oldPath = (0, path_1.join)(dir, "expected.contract.json");
+    const newPath = (0, path_1.join)(dir, "actual.contract.json");
+    (0, fs_1.writeFileSync)(oldPath, JSON.stringify(oldContract, null, 2) + "\n");
+    (0, fs_1.writeFileSync)(newPath, JSON.stringify(newContract, null, 2) + "\n");
+    if (!tool)
+        return { oldPath, newPath };
+    try {
+        const child = (0, child_process_1.spawn)(tool.command, tool.buildArgs(oldPath, newPath), {
+            detached: true,
+            stdio: "ignore",
+            shell: process.platform === "win32",
+        });
+        // A launch failure surfacing asynchronously (after this function has
+        // already returned "openedWith") is still not fatal - both files are
+        // already safely on disk regardless - so this only exists to stop
+        // Node from ever treating an unhandled 'error' event as a crash.
+        child.on("error", () => undefined);
+        child.unref();
+        return { oldPath, newPath, openedWith: tool.command };
+    }
+    catch {
+        return { oldPath, newPath };
+    }
+}

package/dist/core/types.d.ts

@@ -22,6 +22,21 @@ export interface OptionContract {
     readonly variadic: boolean;
     /** JSON-serializable default, or null if the framework declared none. */
     readonly defaultValue: unknown;
+    /**
+     * Name of the environment variable that can also satisfy this flag (e.g.
+     * Commander's `.env("BUILD_TARGET")`, Click's `envvar="BUILD_TARGET"`,
+     * yargs's `.env(prefix)` convention), or `undefined` if the framework
+     * declared none - never guessed from a description or naming convention
+     * the framework itself doesn't actually apply. A maintainer renaming or
+     * removing this binding is a real, otherwise-invisible breaking change:
+     * existing invocations that rely on the env var (and never pass the
+     * flag directly) silently stop working. Omitted entirely (rather than
+     * `null`) for a framework/option that has no such binding, matching how
+     * TypeScript's own `?:` already distinguishes "never applicable" from
+     * "explicitly none" - unlike `defaultValue`, which every option always
+     * has an answer for (even if that answer is "none").
+     */
+    readonly envVar?: string;
 }
 export interface ArgumentContract {
     /** Positional argument name, e.g. "file" from "<file>" or "[file]". */

package/dist/core/webhook.d.ts

@@ -0,0 +1,27 @@
+import type { DiffResult } from "./diff.engine";
+/** The same three fields DiffResult carries on the wire - `removal` is an internal detail (used by `cliguard deprecate`), not part of the v1 webhook payload. */
+export interface WebhookChange {
+    readonly type: string;
+    readonly path: string;
+    readonly message: string;
+}
+export interface WebhookPayload {
+    /** The entry file (or config target name) `check` ran against. */
+    readonly entry: string;
+    /** `git config --get remote.origin.url`, or null outside a git repo / with no origin configured. */
+    readonly repo: string | null;
+    /** `git rev-parse HEAD`, or null outside a git repository. */
+    readonly commit: string | null;
+    readonly changes: readonly WebhookChange[];
+}
+export declare function buildWebhookPayload(entry: string, changes: readonly DiffResult[]): WebhookPayload;
+/**
+ * POSTs a check result to a configurable webhook URL - v1 of the "SaaS
+ * integration" building block from the README's roadmap (issue #3): just
+ * the POST itself, no receiving service or dashboard. Uses Node's native
+ * `fetch` (18+) - no new dependency. Throws on a network error or a non-2xx
+ * response so the caller (bin.ts) decides how to surface that; it never
+ * affects `check`'s own exit code, which reflects the CLI contract diff,
+ * not whether a webhook happened to be reachable.
+ */
+export declare function postWebhook(url: string, payload: WebhookPayload): Promise<void>;

package/dist/core/webhook.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWebhookPayload = buildWebhookPayload;
+exports.postWebhook = postWebhook;
+const child_process_1 = require("child_process");
+/** Best-effort: a plain temp dir, a shallow clone with no origin, or no git at all should never fail the payload - just leaves the field null. */
+function gitValue(args) {
+    try {
+        const out = (0, child_process_1.execFileSync)("git", args, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildWebhookPayload(entry, changes) {
+    return {
+        entry,
+        repo: gitValue(["config", "--get", "remote.origin.url"]),
+        commit: gitValue(["rev-parse", "HEAD"]),
+        changes: changes.map(({ type, path, message }) => ({ type, path, message })),
+    };
+}
+/**
+ * POSTs a check result to a configurable webhook URL - v1 of the "SaaS
+ * integration" building block from the README's roadmap (issue #3): just
+ * the POST itself, no receiving service or dashboard. Uses Node's native
+ * `fetch` (18+) - no new dependency. Throws on a network error or a non-2xx
+ * response so the caller (bin.ts) decides how to surface that; it never
+ * affects `check`'s own exit code, which reflects the CLI contract diff,
+ * not whether a webhook happened to be reachable.
+ */
+async function postWebhook(url, payload) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(payload),
+            // Never lets an unreachable/slow webhook host hang `check` - 5s is
+            // generous for a same-request JSON POST, and a timeout is reported
+            // through the same catch below as any other network failure.
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+    catch (error) {
+        throw new Error(`cliguard: webhook POST to "${url}" failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+        throw new Error(`cliguard: webhook POST to "${url}" failed with status ${response.status}.`);
+    }
+}

package/dist/index.d.ts

@@ -3,7 +3,9 @@ import type { Contract } from "./core/types";
 export type { CliAdapter } from "./adapters/adapter.interface";
 export { CacAdapter } from "./adapters/cac.adapter";
 export { ClickAdapter } from "./adapters/click.adapter";
+export { CobraAdapter } from "./adapters/cobra.adapter";
 export { CommanderAdapter } from "./adapters/commander.adapter";
+export { OclifAdapter } from "./adapters/oclif.adapter";
 export { YargsAdapter } from "./adapters/yargs.adapter";
 export { adapters, resolveAdapter } from "./adapters/registry";
 export { applyConfig, configExists, loadConfig } from "./core/config";
@@ -29,5 +31,5 @@ export declare function extractContract(entryPath: string, adapterName?: string)
  * or a git ref by the caller's own code.
  */
 export declare function compareContracts(oldContract: Contract, newContract: Contract, options?: CompareOptions): DiffResult[];
-/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs", "click"]. */
+/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs", "click", "cobra", "oclif"] - "cobra" is a proof of concept, see src/adapters/cobra.adapter.ts. */
 export declare function listAdapters(): string[];

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChangeType = exports.toRdjsonl = exports.toJUnitXml = exports.toGitLabCodeQuality = exports.renderMarkdownDocs = exports.DiffEngine = exports.loadConfig = exports.configExists = exports.applyConfig = exports.resolveAdapter = exports.adapters = exports.YargsAdapter = exports.CommanderAdapter = exports.ClickAdapter = exports.CacAdapter = void 0;
+exports.ChangeType = exports.toRdjsonl = exports.toJUnitXml = exports.toGitLabCodeQuality = exports.renderMarkdownDocs = exports.DiffEngine = exports.loadConfig = exports.configExists = exports.applyConfig = exports.resolveAdapter = exports.adapters = exports.YargsAdapter = exports.OclifAdapter = exports.CommanderAdapter = exports.CobraAdapter = exports.ClickAdapter = exports.CacAdapter = void 0;
 exports.extractContract = extractContract;
 exports.compareContracts = compareContracts;
 exports.listAdapters = listAdapters;
@@ -18,8 +18,12 @@ var cac_adapter_1 = require("./adapters/cac.adapter");
 Object.defineProperty(exports, "CacAdapter", { enumerable: true, get: function () { return cac_adapter_1.CacAdapter; } });
 var click_adapter_1 = require("./adapters/click.adapter");
 Object.defineProperty(exports, "ClickAdapter", { enumerable: true, get: function () { return click_adapter_1.ClickAdapter; } });
+var cobra_adapter_1 = require("./adapters/cobra.adapter");
+Object.defineProperty(exports, "CobraAdapter", { enumerable: true, get: function () { return cobra_adapter_1.CobraAdapter; } });
 var commander_adapter_1 = require("./adapters/commander.adapter");
 Object.defineProperty(exports, "CommanderAdapter", { enumerable: true, get: function () { return commander_adapter_1.CommanderAdapter; } });
+var oclif_adapter_1 = require("./adapters/oclif.adapter");
+Object.defineProperty(exports, "OclifAdapter", { enumerable: true, get: function () { return oclif_adapter_1.OclifAdapter; } });
 var yargs_adapter_1 = require("./adapters/yargs.adapter");
 Object.defineProperty(exports, "YargsAdapter", { enumerable: true, get: function () { return yargs_adapter_1.YargsAdapter; } });
 var registry_2 = require("./adapters/registry");
@@ -64,7 +68,7 @@ async function extractContract(entryPath, adapterName = "commander") {
 function compareContracts(oldContract, newContract, options) {
     return diffEngine.compare(oldContract, newContract, options);
 }
-/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs", "click"]. */
+/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs", "click", "cobra", "oclif"] - "cobra" is a proof of concept, see src/adapters/cobra.adapter.ts. */
 function listAdapters() {
     return Object.keys(registry_1.adapters);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",
@@ -9,6 +9,7 @@
     "commander",
     "yargs",
     "click",
+    "oclif",
     "ci"
   ],
   "author": "Bryandero98",