delimit-cli 2.3.2 → 2.4.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [2.4.0] - 2026-03-15
+
+### Added
+- 29 real CLI tests covering init, lint, diff, explain, doctor, presets, and error handling
+- Auto-write GitHub Actions workflow file on `delimit init`
+
+### Improved
+- Version now read from package.json instead of hardcoded
+- Error handling across all commands
+
+## [2.3.2] - 2026-03-09
+
+### Fixed
+- Clean --help output (legacy commands hidden)
+- File existence checks before lint/diff operations
+- --policy flag accepts preset names (strict, default, relaxed)
+
+## [2.3.0] - 2026-03-07
+
+### Added
+- Policy presets: strict (all errors), default (balanced), relaxed (warnings only)
+- `delimit doctor` command for environment diagnostics
+- `delimit explain` command with 7 output templates
+
+## [2.0.0] - 2026-02-28
+
+### Added
+- Deterministic diff engine (23 change types, 10 breaking)
+- Policy enforcement with exit code 1 on violations
+- Semver classification (MAJOR/MINOR/PATCH/NONE)
+- Zero-Spec extraction for FastAPI, NestJS, Express

package/README.md

@@ -1,141 +1,108 @@
-# delimit-cli
+# delimit
 
-**Prevent breaking API changes before they reach production.**
-
-Deterministic diff engine + policy enforcement + semver classification for OpenAPI specs. The independent successor to Optic.
+Catch breaking API changes before they ship.
 
 [![npm](https://img.shields.io/npm/v/delimit-cli)](https://www.npmjs.com/package/delimit-cli)
+[![GitHub Action](https://img.shields.io/badge/Marketplace-Delimit-blue)](https://github.com/marketplace/actions/delimit-api-governance)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-299%20passing-brightgreen)](#)
 
-## Install
+Deterministic diff engine for OpenAPI specs. Detects breaking changes, classifies semver, enforces policy, and posts PR comments with migration guides. No API keys, no external services.
 
-```bash
-npm install -g delimit-cli
-```
+---
 
-## Quick Start (Under 5 Minutes)
+## GitHub Action (recommended)
 
-```bash
-# 1. Initialize with a policy preset
-delimit init --preset default
+Add `.github/workflows/api-check.yml`:
 
-# 2. Detect breaking changes
-delimit lint api/openapi-old.yaml api/openapi-new.yaml
+```yaml
+name: API Contract Check
+on: pull_request
 
-# 3. Add the GitHub Action for automated PR checks
-#    Copy .github/workflows/api-governance.yml (see CI section below)
+jobs:
+  delimit:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+      - uses: delimit-ai/delimit-action@v1
+        with:
+          old_spec: base/api/openapi.yaml
+          new_spec: api/openapi.yaml
 ```
 
-## What It Catches
-
-Delimit deterministically detects 23 types of API changes, including 10 breaking patterns:
-
-- Endpoint or method removal
-- Required parameter addition
-- Response field removal
-- Type changes
-- Enum value removal
-- And more
-
-Every change is classified as `MAJOR`, `MINOR`, `PATCH`, or `NONE` per semver.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `delimit init` | Create `.delimit/policies.yml` with a policy preset |
-| `delimit lint <old> <new>` | Diff + policy check — returns exit code 1 on violations |
-| `delimit diff <old> <new>` | Raw diff with `[BREAKING]`/`[safe]` tags |
-| `delimit explain <old> <new>` | Human-readable change explanation |
+Runs in **advisory mode** by default -- posts a PR comment but never fails your build. Set `mode: enforce` when you are ready to block merges on breaking changes.
 
-## Policy Presets
+---
 
-Choose a preset that fits your team:
+## CLI
 
 ```bash
-delimit init --preset strict    # Public APIs, payments — zero tolerance
-delimit init --preset default   # Most teams — balanced rules
-delimit init --preset relaxed   # Internal APIs, startups — warnings only
+npx delimit-cli lint api/openapi.yaml
+npx delimit-cli diff old.yaml new.yaml
+npx delimit-cli explain old.yaml new.yaml --template migration
 ```
 
-| Preset | Breaking changes | Type changes | Field removal |
-|--------|-----------------|--------------|---------------|
-| `strict` | Error (blocks) | Error (blocks) | Error (blocks) |
-| `default` | Error (blocks) | Warning | Error (blocks) |
-| `relaxed` | Warning | Warning | Info |
-
-Pass a preset directly to lint:
+Or install globally:
 
 ```bash
-delimit lint --policy strict old.yaml new.yaml
+npm install -g delimit-cli
+delimit init --preset default
+delimit lint old.yaml new.yaml
 ```
 
-## Options
+### Commands
 
-```bash
-# Semver classification with version bump
-delimit lint old.yaml new.yaml --current-version 1.0.0
+| Command | What it does |
+|---------|-------------|
+| `delimit init [--preset]` | Create `.delimit/policies.yml` |
+| `delimit lint <old> <new>` | Diff + policy check. Exit 1 on violations. |
+| `delimit diff <old> <new>` | Raw diff with `[BREAKING]` / `[safe]` tags |
+| `delimit explain <old> <new>` | Human-readable explanation (7 templates) |
 
-# Explainer templates
-delimit explain old.yaml new.yaml -t migration
-delimit explain old.yaml new.yaml -t pr_comment
-delimit explain old.yaml new.yaml -t changelog
+---
 
-# JSON output for scripting
-delimit lint old.yaml new.yaml --json
-```
+## What it catches
 
-### Explainer Templates
+10 breaking change types, detected deterministically:
 
-| Template | Audience |
-|----------|----------|
-| `developer` | Technical details for engineers |
-| `team_lead` | Summary for engineering managers |
-| `product` | Non-technical overview for PMs |
-| `migration` | Step-by-step migration guide |
-| `changelog` | Ready-to-paste changelog entry |
-| `pr_comment` | GitHub PR comment format |
-| `slack` | Slack message format |
+| Breaking change | Example |
+|----------------|---------|
+| Endpoint removed | `DELETE /users/{id}` path deleted |
+| Method removed | `PATCH` dropped from `/orders` |
+| Required parameter added | New required query param on existing endpoint |
+| Parameter removed | `?filter` param deleted |
+| Response removed | `200` response code dropped |
+| Required field added | New required field in request body |
+| Response field removed | `email` field removed from response |
+| Type changed | `age` changed from `string` to `integer` |
+| Format changed | `date` changed to `date-time` |
+| Enum value removed | `status: "pending"` no longer allowed |
 
-## CI/CD Integration
+Plus 7 non-breaking types (endpoint added, optional field added, etc.) for full change visibility. Every change is classified as `MAJOR`, `MINOR`, `PATCH`, or `NONE`.
 
-Add this workflow to `.github/workflows/api-governance.yml`:
+---
 
-```yaml
-name: API Governance
-on:
-  pull_request:
-    paths:
-      - 'path/to/openapi.yaml'  # adjust to your spec path
-permissions:
-  contents: read
-  pull-requests: write
-jobs:
-  api-governance:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.base.sha }}
-          path: _base
-      - uses: delimit-ai/delimit@v1
-        with:
-          old_spec: _base/path/to/openapi.yaml
-          new_spec: path/to/openapi.yaml
-          mode: advisory  # or 'enforce' to block PRs
+## Policy presets
+
+```bash
+delimit init --preset strict    # All breaking changes are errors. For public/payment APIs.
+delimit init --preset default   # Breaking changes error, type changes warn. For most teams.
+delimit init --preset relaxed   # Everything is a warning. For internal APIs and prototyping.
 ```
 
-The action posts a PR comment with:
-- Semver badge (`MAJOR` / `MINOR` / `PATCH`)
-- Violation table with severity
-- Expandable migration guide for breaking changes
+Or pass inline: `delimit lint --policy strict old.yaml new.yaml`
 
-See [Delimit API Governance](https://github.com/marketplace/actions/delimit-api-governance) on the GitHub Marketplace.
+---
 
-## Custom Policies
+## Custom policies
 
-Create `.delimit/policies.yml` or start from a preset:
+Create `.delimit/policies.yml`:
 
 ```yaml
 override_defaults: false
@@ -151,17 +118,22 @@ rules:
     message: "V1 API is frozen. Make changes in V2."
 ```
 
-## Supported Specs
+---
 
-- OpenAPI 3.0.x and 3.1.x
+## Supported formats
+
+- OpenAPI 3.0 and 3.1
 - Swagger 2.0
-- YAML and JSON formats
+- YAML and JSON
+
+---
 
 ## Links
 
-- [GitHub Action](https://github.com/marketplace/actions/delimit-api-governance) — Automated PR checks
-- [GitHub](https://github.com/delimit-ai/delimit) — Source code
-- [Issues](https://github.com/delimit-ai/delimit/issues) — Bug reports and feature requests
+- [delimit.ai](https://delimit.ai) -- Project home
+- [GitHub Action on Marketplace](https://github.com/marketplace/actions/delimit-api-governance) -- Install in one click
+- [delimit-cli on npm](https://www.npmjs.com/package/delimit-cli) -- CLI package
+- [Quickstart repo](https://github.com/delimit-ai/delimit-quickstart) -- Try it in 2 minutes
 
 ## License
 

package/adapters/codex-forge.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Delimit™ Codex Forge Adapter
+ * Layer: Forge (execution governance)
+ * Surfaces test failures, deploy state, and release gates before accepting code.
+ */
+
+'use strict';
+
+const axios = require('axios');
+const AGENT_URL = `http://127.0.0.1:${process.env.DELIMIT_AGENT_PORT || 7823}`;
+
+class DelimitCodexForge {
+    constructor() {
+        this.name = 'delimit-forge';
+        this.version = '1.0.0';
+    }
+
+    /**
+     * Before accepting code: check test gate and deploy state.
+     */
+    async onBeforeSuggestion(context) {
+        const [testState, deployState] = await Promise.allSettled([
+            this._getTestGate(),
+            this._getDeployState(),
+        ]);
+
+        const warnings = [];
+
+        if (testState.status === 'fulfilled' && testState.value.failing > 0) {
+            warnings.push(`[FORGE] ${testState.value.failing} test(s) failing — fix before accepting`);
+        }
+
+        if (deployState.status === 'fulfilled' && deployState.value.locked) {
+            warnings.push(`[FORGE] Deploy locked: ${deployState.value.reason || 'release in progress'}`);
+        }
+
+        if (warnings.length > 0) {
+            return { allow: true, warning: warnings.join(' | ') };
+        }
+
+        return { allow: true };
+    }
+
+    async onAfterAccept(context) {
+        try {
+            await axios.post(`${AGENT_URL}/audit`, {
+                action: 'forge_accept',
+                context,
+                timestamp: new Date().toISOString(),
+            }, { timeout: 2000 });
+        } catch (_) { /* silent */ }
+    }
+
+    async _getTestGate() {
+        const r = await axios.get(`${AGENT_URL}/test/status`, { timeout: 3000 });
+        return r.data;
+    }
+
+    async _getDeployState() {
+        const r = await axios.get(`${AGENT_URL}/deploy/status`, { timeout: 3000 });
+        return r.data;
+    }
+
+    async handleCommand(command, _args) {
+        const { execSync } = require('child_process');
+        const cmds = {
+            'forge': 'delimit status --layer=forge',
+            'tests': 'delimit test --summary',
+            'deploy': 'delimit deploy --status',
+            'release': 'delimit release --status',
+        };
+        if (cmds[command]) {
+            try {
+                return execSync(cmds[command], { timeout: 10000 }).toString();
+            } catch (e) {
+                return `[FORGE] Command failed: ${e.message}`;
+            }
+        }
+    }
+
+    /**
+     * Returns structured Forge context for consensus use.
+     */
+    async getContext() {
+        const [tests, deploy, release] = await Promise.allSettled([
+            axios.get(`${AGENT_URL}/test/status`, { timeout: 3000 }),
+            axios.get(`${AGENT_URL}/deploy/status`, { timeout: 3000 }),
+            axios.get(`${AGENT_URL}/release/status`, { timeout: 3000 }),
+        ]);
+
+        return {
+            layer: 'forge',
+            tests: tests.status === 'fulfilled' ? tests.value.data : null,
+            deploy: deploy.status === 'fulfilled' ? deploy.value.data : null,
+            release: release.status === 'fulfilled' ? release.value.data : null,
+        };
+    }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = new DelimitCodexForge();
+}
+
+if (typeof registerSkill === 'function') {
+    registerSkill(new DelimitCodexForge());
+}

package/adapters/codex-jamsons.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * Delimit™ Codex Jamsons Adapter
+ * Layer: Jamsons OS (strategy + operational governance)
+ * Injects portfolio context, logs decisions, surfaces venture/priority state.
+ */
+
+'use strict';
+
+const axios = require('axios');
+const AGENT_URL   = `http://127.0.0.1:${process.env.DELIMIT_AGENT_PORT || 7823}`;
+const JAMSONS_URL = `http://localhost:${process.env.JAMSONS_PORT || 8091}`;
+
+const VENTURES = {
+    delimit:      { priority: 'P0', status: 'active' },
+    domainvested: { priority: 'P2', status: 'maintenance' },
+    'wire.report': { priority: 'held', status: 'held' },
+    'livetube.ai': { priority: 'held', status: 'held' },
+};
+
+class DelimitCodexJamsons {
+    constructor() {
+        this.name = 'delimit-jamsons';
+        this.version = '1.0.0';
+    }
+
+    /**
+     * Before suggestion: inject portfolio context so the model has strategic awareness.
+     */
+    async onBeforeSuggestion(context) {
+        try {
+            const portfolioCtx = await this._getPortfolioContext(context);
+            // Attach context metadata — Codex passes this through to the model
+            context._jamsons = portfolioCtx;
+        } catch (_) { /* fail open */ }
+        return { allow: true };
+    }
+
+    async onAfterAccept(context) {
+        // Log accepted suggestion to Jamsons decision ledger
+        try {
+            await axios.post(`${JAMSONS_URL}/api/chatops/decisions`, {
+                type: 'task',
+                title: `Codex: accepted suggestion in ${context.file || 'unknown file'}`,
+                detail: `Language: ${context.language || 'unknown'} | Tool: codex`,
+                user_id: 'codex-adapter',
+                tags: ['delimit', 'chatops'],
+            }, {
+                headers: { Authorization: `Bearer ${process.env.CHATOPS_AUTH_TOKEN}` },
+                timeout: 2000,
+            });
+        } catch (_) { /* silent */ }
+    }
+
+    async _getPortfolioContext(context) {
+        const [memory, decisions] = await Promise.allSettled([
+            this._searchMemory(context.file || context.language || 'delimit'),
+            this._getPendingDecisions(),
+        ]);
+
+        return {
+            ventures: VENTURES,
+            activeVenture: this._detectVenture(context),
+            memory: memory.status === 'fulfilled' ? memory.value : [],
+            pendingDecisions: decisions.status === 'fulfilled' ? decisions.value : [],
+            timestamp: new Date().toISOString(),
+        };
+    }
+
+    _detectVenture(context) {
+        const path = (context.file || '').toLowerCase();
+        if (path.includes('delimit')) return 'delimit';
+        if (path.includes('domainvested')) return 'domainvested';
+        return 'delimit'; // default active venture
+    }
+
+    async _searchMemory(query) {
+        const r = await axios.get(`${JAMSONS_URL}/api/memory/search`, {
+            params: { q: query, limit: 5 },
+            timeout: 2000,
+        });
+        return r.data?.results || [];
+    }
+
+    async _getPendingDecisions() {
+        const r = await axios.get(`${JAMSONS_URL}/api/chatops/decisions`, {
+            params: { status: 'pending', limit: 5 },
+            headers: { Authorization: `Bearer ${process.env.CHATOPS_AUTH_TOKEN}` },
+            timeout: 2000,
+        });
+        return r.data?.decisions || r.data || [];
+    }
+
+    async handleCommand(command, _args) {
+        const { execSync } = require('child_process');
+        const cmds = {
+            'jamsons': 'delimit status --layer=jamsons',
+            'portfolio': 'delimit portfolio --summary',
+            'decisions': 'delimit decisions --pending',
+            'memory': 'delimit memory --recent',
+        };
+        if (cmds[command]) {
+            try {
+                return execSync(cmds[command], { timeout: 10000 }).toString();
+            } catch (e) {
+                return `[JAMSONS] Command failed: ${e.message}`;
+            }
+        }
+    }
+
+    /**
+     * Returns structured Jamsons context for consensus use.
+     */
+    async getContext() {
+        const [memory, decisions] = await Promise.allSettled([
+            axios.get(`${JAMSONS_URL}/api/memory/search`, {
+                params: { q: 'delimit strategy', limit: 5 },
+                timeout: 3000,
+            }),
+            axios.get(`${JAMSONS_URL}/api/chatops/decisions`, {
+                params: { status: 'pending' },
+                headers: { Authorization: `Bearer ${process.env.CHATOPS_AUTH_TOKEN}` },
+                timeout: 3000,
+            }),
+        ]);
+
+        return {
+            layer: 'jamsons',
+            ventures: VENTURES,
+            memory: memory.status === 'fulfilled' ? (memory.value.data?.results || []) : null,
+            pendingDecisions: decisions.status === 'fulfilled' ? (decisions.value.data || []) : null,
+        };
+    }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = new DelimitCodexJamsons();
+}
+
+if (typeof registerSkill === 'function') {
+    registerSkill(new DelimitCodexJamsons());
+}

package/adapters/codex-security.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Delimit™ Codex Security Skill Adapter
+ * Layer: Delimit (code governance) — Security surface
+ * Triggered on pre-code-generation and pre-suggestion events
+ */
+
+'use strict';
+
+const axios = require('axios');
+const AGENT_URL = `http://127.0.0.1:${process.env.DELIMIT_AGENT_PORT || 7823}`;
+
+class DelimitCodexSecurity {
+    constructor() {
+        this.name = 'delimit-security';
+        this.version = '1.0.0';
+    }
+
+    async onBeforeSuggestion(context) {
+        try {
+            const { code, language, file } = context;
+            const response = await axios.post(`${AGENT_URL}/security`, {
+                action: 'codex_suggestion',
+                code,
+                language,
+                file,
+                tool: 'codex',
+            }, { timeout: 3000 });
+
+            const { severity, findings } = response.data;
+
+            if (severity === 'critical') {
+                return {
+                    allow: false,
+                    message: `[DELIMIT SECURITY] Blocked — critical finding: ${findings?.[0]?.message || 'see audit log'}`,
+                };
+            }
+
+            if (severity === 'high') {
+                return {
+                    allow: true,
+                    warning: `[DELIMIT SECURITY] High-severity finding: ${findings?.[0]?.message || 'review before accepting'}`,
+                };
+            }
+
+            return { allow: true };
+        } catch (err) {
+            if (err.response?.data?.action === 'block') {
+                return { allow: false, message: `[DELIMIT SECURITY] ${err.response.data.reason}` };
+            }
+            // Fail open — security service unavailable
+            console.warn('[DELIMIT SECURITY] Scan unavailable:', err.message);
+            return { allow: true };
+        }
+    }
+
+    async onAfterAccept(context) {
+        try {
+            await axios.post(`${AGENT_URL}/audit`, {
+                action: 'codex_security_accept',
+                context,
+                timestamp: new Date().toISOString(),
+            }, { timeout: 2000 });
+        } catch (_) { /* silent */ }
+    }
+
+    async handleCommand(command, _args) {
+        if (command === 'security') {
+            const { execSync } = require('child_process');
+            try {
+                return execSync('delimit security --verbose', { timeout: 10000 }).toString();
+            } catch (e) {
+                return `[DELIMIT SECURITY] Command failed: ${e.message}`;
+            }
+        }
+    }
+
+    async getContext() {
+        try {
+            const r = await axios.get(`${AGENT_URL}/security/status`, { timeout: 3000 });
+            return { layer: 'delimit-security', status: 'ok', data: r.data };
+        } catch (_) {
+            return { layer: 'delimit-security', status: 'unavailable' };
+        }
+    }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = new DelimitCodexSecurity();
+}
+
+if (typeof registerSkill === 'function') {
+    registerSkill(new DelimitCodexSecurity());
+}

package/adapters/gemini-forge.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Delimit™ Gemini CLI Forge Adapter
+ * Layer: Forge (execution governance)
+ * Used as: command handler called from Gemini CLI hooks and @commands
+ */
+
+'use strict';
+
+const axios = require('axios');
+const AGENT_URL = `http://127.0.0.1:${process.env.DELIMIT_AGENT_PORT || 7823}`;
+
+class DelimitGeminiForge {
+    constructor() {
+        this.id = 'delimit-forge';
+        this.version = '1.0.0';
+    }
+
+    /**
+     * Pre-generation: surface test failures and deploy locks to Gemini before it generates code.
+     */
+    async beforeCodeGeneration(request) {
+        const [testState, deployState, releaseState] = await Promise.allSettled([
+            axios.get(`${AGENT_URL}/test/status`, { timeout: 3000 }),
+            axios.get(`${AGENT_URL}/deploy/status`, { timeout: 3000 }),
+            axios.get(`${AGENT_URL}/release/status`, { timeout: 3000 }),
+        ]);
+
+        const warnings = [];
+
+        if (testState.status === 'fulfilled') {
+            const t = testState.value.data;
+            if (t?.failing > 0) warnings.push(`[FORGE] ${t.failing} test(s) failing`);
+        }
+
+        if (deployState.status === 'fulfilled') {
+            const d = deployState.value.data;
+            if (d?.locked) warnings.push(`[FORGE] Deploy locked: ${d.reason || 'release in progress'}`);
+        }
+
+        if (releaseState.status === 'fulfilled') {
+            const rel = releaseState.value.data;
+            if (rel?.in_progress) warnings.push(`[FORGE] Release in progress: ${rel.version || 'unknown'}`);
+        }
+
+        if (warnings.length > 0) {
+            console.warn(warnings.join('\n'));
+            // Inject warnings into system prompt context
+            request._forgeWarnings = warnings;
+        }
+
+        return request;
+    }
+
+    async afterResponse(response) {
+        try {
+            await axios.post(`${AGENT_URL}/audit`, {
+                action: 'gemini_forge_response',
+                response: {
+                    model: response.model,
+                    tokens: response.usage,
+                    timestamp: new Date().toISOString(),
+                },
+            }, { timeout: 2000 });
+        } catch (_) { /* silent */ }
+        return response;
+    }
+
+    async handleCommand(command, _args) {
+        const { execSync } = require('child_process');
+        const commands = {
+            '@forge':   'delimit status --layer=forge',
+            '@tests':   'delimit test --summary',
+            '@deploy':  'delimit deploy --status',
+            '@release': 'delimit release --status',
+        };
+        if (commands[command]) {
+            try {
+                return execSync(commands[command], { timeout: 10000 }).toString();
+            } catch (e) {
+                return `[FORGE] Command failed: ${e.message}`;
+            }
+        }
+    }
+
+    /**
+     * Structured context for consensus — call this from hooks or consensus runners.
+     */
+    async getContext() {
+        const [tests, deploy, release] = await Promise.allSettled([
+            axios.get(`${AGENT_URL}/test/status`, { timeout: 3000 }),
+            axios.get(`${AGENT_URL}/deploy/status`, { timeout: 3000 }),
+            axios.get(`${AGENT_URL}/release/status`, { timeout: 3000 }),
+        ]);
+        return {
+            layer: 'forge',
+            tool: 'gemini',
+            tests: tests.status === 'fulfilled' ? tests.value.data : null,
+            deploy: deploy.status === 'fulfilled' ? deploy.value.data : null,
+            release: release.status === 'fulfilled' ? release.value.data : null,
+        };
+    }
+}
+
+module.exports = new DelimitGeminiForge();
+
+if (typeof registerExtension === 'function') {
+    registerExtension(new DelimitGeminiForge());
+}

package/bin/delimit-cli.js

@@ -50,7 +50,7 @@ async function ensureAgent() {
 program
     .name('delimit')
     .description('Prevent breaking API changes before they reach production')
-    .version('2.3.0');
+    .version(require('../package.json').version);
 
 // Install command with modes
 program
@@ -803,7 +803,7 @@ program
             const specPath = foundSpecs[0];
             console.log(`  Detected spec: ${chalk.bold(specPath)}`);
             console.log('');
-            console.log(chalk.bold('  Add this to .github/workflows/api-governance.yml:\n'));
+            console.log(chalk.bold('  Workflow template:\n'));
             console.log(chalk.gray(`  name: API Governance
   on:
     pull_request:
@@ -827,6 +827,48 @@ program
             new_spec: ${specPath}
             mode: advisory`));
             console.log('');
+
+            // Auto-write the workflow file
+            const workflowDir = path.join(process.cwd(), '.github', 'workflows');
+            const workflowFile = path.join(workflowDir, 'api-governance.yml');
+
+            if (!fs.existsSync(workflowFile)) {
+                try {
+                    fs.mkdirSync(workflowDir, { recursive: true });
+                    const workflowContent = `name: API Governance
+on:
+  pull_request:
+    paths:
+      - '${specPath}'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  api-governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.pull_request.base.sha }}
+          path: _base
+      - uses: delimit-ai/delimit@v1
+        with:
+          old_spec: _base/${specPath}
+          new_spec: ${specPath}
+          mode: advisory
+`;
+                    fs.writeFileSync(workflowFile, workflowContent);
+                    console.log(chalk.green(`  Created .github/workflows/api-governance.yml\n`));
+                } catch (err) {
+                    console.log(chalk.yellow(`  Could not write workflow file: ${err.message}`));
+                    console.log(chalk.bold('  Add this to .github/workflows/api-governance.yml manually (shown above)\n'));
+                }
+            } else {
+                console.log(chalk.yellow('  .github/workflows/api-governance.yml already exists — skipped\n'));
+            }
         } else {
             console.log('  No OpenAPI spec file detected.');
             console.log(`  Delimit also supports ${chalk.bold('Zero-Spec Mode')} — run ${chalk.bold('delimit lint')} in a FastAPI/NestJS/Express project.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delimit-cli",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Prevent breaking API changes before they reach production. Deterministic diff engine + policy enforcement + semver classification.",
   "main": "index.js",
   "bin": {
@@ -12,7 +12,7 @@
     "install-mcp": "bash ./hooks/install-hooks.sh mcp-only",
     "test-mcp": "bash ./hooks/install-hooks.sh troubleshoot",
     "fix-mcp": "bash ./hooks/install-hooks.sh fix-mcp",
-    "test": "echo 'Governance is context-aware' && exit 0"
+    "test": "node --test tests/cli.test.js"
   },
   "keywords": [
     "openapi",

package/tests/cli.test.js

@@ -0,0 +1,359 @@
+/**
+ * Delimit CLI Tests
+ *
+ * Uses Node.js built-in test runner (node:test).
+ * Run with: node --test tests/cli.test.js
+ */
+
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+
+const CLI = path.join(__dirname, '..', 'bin', 'delimit-cli.js');
+const FIXTURES = path.join(__dirname, 'fixtures');
+const SPEC_CLEAN = path.join(FIXTURES, 'openapi.yaml');
+const SPEC_BREAKING = path.join(FIXTURES, 'openapi-changed.yaml');
+
+/**
+ * Run the CLI and return { stdout, stderr, exitCode }.
+ * Does not throw on non-zero exit.
+ */
+function run(args, opts = {}) {
+    const cwd = opts.cwd || os.tmpdir();
+    try {
+        const stdout = execSync(`node "${CLI}" ${args}`, {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 30000,
+            env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+        });
+        return { stdout, stderr: '', exitCode: 0 };
+    } catch (err) {
+        return {
+            stdout: err.stdout || '',
+            stderr: err.stderr || '',
+            exitCode: err.status ?? 1,
+        };
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 1. CLI entry point loads without error
+// ---------------------------------------------------------------------------
+describe('CLI entry point', () => {
+    it('loads the module without throwing', () => {
+        assert.doesNotThrow(() => {
+            execSync(`node --check "${CLI}"`, { encoding: 'utf-8' });
+        });
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 2. --version returns the version from package.json
+// ---------------------------------------------------------------------------
+describe('--version', () => {
+    it('prints the version from package.json', () => {
+        const pkg = require(path.join(__dirname, '..', 'package.json'));
+        const { stdout } = run('--version');
+        assert.equal(stdout.trim(), pkg.version);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 3. --help works at top level
+// ---------------------------------------------------------------------------
+describe('--help (top level)', () => {
+    it('shows usage and lists commands', () => {
+        const { stdout } = run('--help');
+        assert.match(stdout, /Usage:/);
+        assert.match(stdout, /init/);
+        assert.match(stdout, /lint/);
+        assert.match(stdout, /diff/);
+        assert.match(stdout, /explain/);
+        assert.match(stdout, /doctor/);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Each command has help text
+// ---------------------------------------------------------------------------
+describe('subcommand --help', () => {
+    for (const cmd of ['init', 'lint', 'diff', 'explain', 'doctor']) {
+        it(`"help ${cmd}" shows description`, () => {
+            const { stdout } = run(`help ${cmd}`);
+            assert.match(stdout, /Usage:/);
+            assert.match(stdout, new RegExp(cmd));
+        });
+    }
+});
+
+// ---------------------------------------------------------------------------
+// 5. init creates .delimit/policies.yml with default preset
+// ---------------------------------------------------------------------------
+describe('init command', () => {
+    let tmpDir;
+
+    before(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'delimit-test-init-'));
+    });
+
+    after(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('creates .delimit/policies.yml with default preset', () => {
+        const { stdout, exitCode } = run('init', { cwd: tmpDir });
+        assert.equal(exitCode, 0);
+        const policyPath = path.join(tmpDir, '.delimit', 'policies.yml');
+        assert.ok(fs.existsSync(policyPath), 'policies.yml should exist');
+        const content = fs.readFileSync(policyPath, 'utf-8');
+        assert.match(content, /Delimit Policy Preset: default/);
+        assert.match(content, /override_defaults: false/);
+    });
+
+    it('reports already initialized on second run', () => {
+        const { stdout, exitCode } = run('init', { cwd: tmpDir });
+        assert.equal(exitCode, 0);
+        assert.match(stdout, /Already initialized/);
+    });
+});
+
+describe('init --preset strict', () => {
+    let tmpDir;
+
+    before(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'delimit-test-init-strict-'));
+    });
+
+    after(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('creates policies.yml with strict preset', () => {
+        const { stdout, exitCode } = run('init --preset strict', { cwd: tmpDir });
+        assert.equal(exitCode, 0);
+        const content = fs.readFileSync(
+            path.join(tmpDir, '.delimit', 'policies.yml'),
+            'utf-8'
+        );
+        assert.match(content, /Delimit Policy Preset: strict/);
+        assert.match(content, /no_endpoint_removal/);
+    });
+});
+
+describe('init --preset relaxed', () => {
+    let tmpDir;
+
+    before(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'delimit-test-init-relaxed-'));
+    });
+
+    after(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('creates policies.yml with relaxed preset', () => {
+        const { stdout, exitCode } = run('init --preset relaxed', { cwd: tmpDir });
+        assert.equal(exitCode, 0);
+        const content = fs.readFileSync(
+            path.join(tmpDir, '.delimit', 'policies.yml'),
+            'utf-8'
+        );
+        assert.match(content, /Delimit Policy Preset: relaxed/);
+        assert.match(content, /warn_endpoint_removal/);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 6. lint with identical specs returns clean (exit 0)
+// ---------------------------------------------------------------------------
+describe('lint (clean)', () => {
+    it('returns exit 0 with no violations for identical specs', () => {
+        const { stdout, exitCode } = run(
+            `lint "${SPEC_CLEAN}" "${SPEC_CLEAN}" --json`
+        );
+        assert.equal(exitCode, 0);
+        const result = JSON.parse(stdout);
+        assert.equal(result.decision, 'pass');
+        assert.equal(result.exit_code, 0);
+        assert.equal(result.summary.breaking_changes, 0);
+        assert.equal(result.violations.length, 0);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 7. lint with breaking change returns exit 1
+// ---------------------------------------------------------------------------
+describe('lint (breaking)', () => {
+    it('returns exit 1 when breaking changes are detected', () => {
+        const { stdout, exitCode } = run(
+            `lint "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        assert.equal(exitCode, 1);
+        const result = JSON.parse(stdout);
+        assert.equal(result.decision, 'fail');
+        assert.equal(result.exit_code, 1);
+        assert.ok(result.summary.breaking_changes > 0, 'should have breaking changes');
+        assert.ok(result.violations.length > 0, 'should have violations');
+    });
+
+    it('includes endpoint_removed in changes', () => {
+        const { stdout } = run(
+            `lint "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        const result = JSON.parse(stdout);
+        const types = result.all_changes.map(c => c.type);
+        assert.ok(types.includes('endpoint_removed'), 'should detect endpoint removal');
+    });
+
+    it('includes semver bump classification', () => {
+        const { stdout } = run(
+            `lint "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        const result = JSON.parse(stdout);
+        assert.ok(result.semver, 'should have semver field');
+        assert.equal(result.semver.bump, 'major');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 8. diff outputs change types
+// ---------------------------------------------------------------------------
+describe('diff command', () => {
+    it('outputs changes between two specs', () => {
+        const { stdout, exitCode } = run(
+            `diff "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        assert.equal(exitCode, 0);
+        const result = JSON.parse(stdout);
+        assert.ok(result.total_changes > 0, 'should have changes');
+        assert.ok(result.breaking_changes > 0, 'should have breaking changes');
+        assert.ok(Array.isArray(result.changes), 'changes should be an array');
+    });
+
+    it('reports change types correctly', () => {
+        const { stdout } = run(
+            `diff "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        const result = JSON.parse(stdout);
+        const types = result.changes.map(c => c.type);
+        assert.ok(types.includes('endpoint_removed'));
+        assert.ok(types.includes('type_changed'));
+        assert.ok(types.includes('enum_value_removed'));
+    });
+
+    it('marks breaking changes with is_breaking flag', () => {
+        const { stdout } = run(
+            `diff "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        const result = JSON.parse(stdout);
+        const breakingChanges = result.changes.filter(c => c.is_breaking);
+        assert.equal(breakingChanges.length, result.breaking_changes);
+    });
+
+    it('returns no changes for identical specs', () => {
+        const { stdout, exitCode } = run(
+            `diff "${SPEC_CLEAN}" "${SPEC_CLEAN}" --json`
+        );
+        assert.equal(exitCode, 0);
+        const result = JSON.parse(stdout);
+        assert.equal(result.total_changes, 0);
+        assert.equal(result.breaking_changes, 0);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 9. explain command
+// ---------------------------------------------------------------------------
+describe('explain command', () => {
+    it('generates human-readable explanation', () => {
+        const { stdout, exitCode } = run(
+            `explain "${SPEC_CLEAN}" "${SPEC_BREAKING}" --json`
+        );
+        assert.equal(exitCode, 0);
+        const result = JSON.parse(stdout);
+        assert.ok(result.output, 'should have output text');
+        assert.ok(result.output.length > 0, 'output should not be empty');
+        assert.ok(result.template, 'should report template used');
+    });
+
+    it('supports --template flag', () => {
+        const { stdout, exitCode } = run(
+            `explain "${SPEC_CLEAN}" "${SPEC_BREAKING}" --template migration --json`
+        );
+        assert.equal(exitCode, 0);
+        const result = JSON.parse(stdout);
+        assert.equal(result.template, 'migration');
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 10. lint with --policy preset
+// ---------------------------------------------------------------------------
+describe('lint --policy', () => {
+    it('accepts relaxed preset and does not fail on breaking changes', () => {
+        // relaxed preset uses action:warn, so decision is "warn" not "fail"
+        const { stdout, exitCode } = run(
+            `lint "${SPEC_CLEAN}" "${SPEC_BREAKING}" --policy relaxed --json`
+        );
+        assert.equal(exitCode, 0, 'relaxed preset should exit 0');
+        const result = JSON.parse(stdout);
+        assert.notEqual(result.decision, 'fail', 'relaxed should not produce fail decision');
+    });
+
+    it('accepts strict preset and fails on breaking changes', () => {
+        const { stdout, exitCode } = run(
+            `lint "${SPEC_CLEAN}" "${SPEC_BREAKING}" --policy strict --json`
+        );
+        assert.equal(exitCode, 1);
+        const result = JSON.parse(stdout);
+        assert.equal(result.decision, 'fail');
+        assert.ok(result.violations.length > 0);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 11. Error handling -- missing files
+// ---------------------------------------------------------------------------
+describe('error handling', () => {
+    it('lint with nonexistent spec file reports error', () => {
+        const { exitCode } = run('lint /nonexistent/old.yaml /nonexistent/new.yaml --json');
+        assert.notEqual(exitCode, 0);
+    });
+
+    it('diff with nonexistent spec file reports error', () => {
+        const { exitCode } = run('diff /nonexistent/old.yaml /nonexistent/new.yaml --json');
+        assert.notEqual(exitCode, 0);
+    });
+});
+
+// ---------------------------------------------------------------------------
+// 12. api-engine module exports
+// ---------------------------------------------------------------------------
+describe('api-engine module', () => {
+    it('exports lint, diff, explain, semver, zeroSpec functions', () => {
+        const engine = require(path.join(__dirname, '..', 'lib', 'api-engine.js'));
+        assert.equal(typeof engine.lint, 'function');
+        assert.equal(typeof engine.diff, 'function');
+        assert.equal(typeof engine.explain, 'function');
+        assert.equal(typeof engine.semver, 'function');
+        assert.equal(typeof engine.zeroSpec, 'function');
+    });
+
+    it('lint returns parsed JSON with decision field', () => {
+        const engine = require(path.join(__dirname, '..', 'lib', 'api-engine.js'));
+        const result = engine.lint(SPEC_CLEAN, SPEC_CLEAN);
+        assert.ok(result.decision, 'should have decision field');
+        assert.equal(result.decision, 'pass');
+    });
+
+    it('diff returns parsed JSON with changes array', () => {
+        const engine = require(path.join(__dirname, '..', 'lib', 'api-engine.js'));
+        const result = engine.diff(SPEC_CLEAN, SPEC_BREAKING);
+        assert.ok(Array.isArray(result.changes), 'should have changes array');
+        assert.ok(result.total_changes > 0);
+    });
+});

package/tests/fixtures/openapi-changed.yaml

@@ -0,0 +1,56 @@
+openapi: "3.0.3"
+info:
+  title: Pet Store API
+  version: "2.0.0"
+  description: Sample API for Delimit quickstart
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        "200":
+          description: A list of pets
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Pet"
+    post:
+      summary: Create a pet
+      operationId: createPet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        "201":
+          description: Pet created
+  # /pets/{petId} removed -- this is the breaking change
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        status:
+          type: string
+          enum:
+            - available
+            - adopted

package/tests/fixtures/openapi.yaml

@@ -0,0 +1,87 @@
+openapi: "3.0.3"
+info:
+  title: Pet Store API
+  version: "1.0.0"
+  description: Sample API for Delimit quickstart
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        "200":
+          description: A list of pets
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Pet"
+    post:
+      summary: Create a pet
+      operationId: createPet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        "201":
+          description: Pet created
+  /pets/{petId}:
+    get:
+      summary: Get a pet by ID
+      operationId: getPetById
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A single pet
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pet"
+    delete:
+      summary: Delete a pet
+      operationId: deletePet
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Pet deleted
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        tag:
+          type: string
+        status:
+          type: string
+          enum:
+            - available
+            - pending
+            - adopted