delimit-cli 2.3.1 → 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());
+}