delimit-cli 2.3.2 → 3.0.0

package/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+.git
+tests
+junit.xml
+playwright-report
+test-results
+test-results.json

package/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['18', '20', '22']
+
+    name: Test Node ${{ matrix.node-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - run: npm install
+
+      - run: npm test

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/CODE_OF_CONDUCT.md

@@ -0,0 +1,48 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery
+* Trolling, insulting or derogatory comments, and personal attacks
+* Public or private harassment
+* Publishing others' private information without permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+opensource@delimit.ai.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Delimit
+
+Thank you for your interest in contributing to Delimit. We welcome contributions from the community.
+
+## How to Contribute
+
+### Reporting Issues
+
+1. Check if the issue already exists
+2. Create a new issue with:
+   - Clear title and description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment details (OS, Node version, etc.)
+
+### Submitting Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes
+4. Run the test suite
+5. Commit with clear messages
+6. Push to your fork
+7. Open a PR with:
+   - Description of changes
+   - Related issue numbers
+   - Test results
+
+## Development Setup
+
+### CLI (npm)
+
+```bash
+npm install -g delimit-cli
+delimit doctor
+```
+
+### GitHub Action
+
+See [delimit-action](https://github.com/delimit-ai/delimit-action) for CI integration.
+
+## Code Style
+
+- Follow existing conventions in the codebase
+- Use type hints where appropriate
+- Document functions and classes
+- Keep functions focused and small
+
+## Testing
+
+All PRs must:
+- Pass existing tests
+- Include tests for new features
+- Not introduce regressions
+
+## Areas for Contribution
+
+- Documentation improvements
+- Bug fixes
+- New governance rules and policy presets
+- Performance improvements
+- Framework integrations (Zero-Spec extractors)
+
+## Questions?
+
+- Open a [Discussion](https://github.com/delimit-ai/delimit/discussions) on GitHub
+- Email opensource@delimit.ai

package/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:20-slim
+RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip && rm -rf /var/lib/apt/lists/*
+RUN pip3 install --break-system-packages pyyaml pydantic packaging
+WORKDIR /app
+COPY package*.json ./
+RUN npm install --production --ignore-scripts
+COPY . .
+ENV DELIMIT_GATEWAY_ROOT=/app/gateway
+ENTRYPOINT ["node", "bin/delimit-cli.js"]

package/LICENSE

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

package/README.md

@@ -1,167 +1,88 @@
-# 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)
 
-## 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
-
-# 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: delimit-ai/delimit-action@v1
+        with:
+          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 |
-
-## Policy Presets
-
-Choose a preset that fits your team:
+One input. Delimit fetches the base branch version automatically. Runs in **advisory mode** by default -- posts a PR comment but does not fail your build. Set `mode: enforce` to block merges on breaking changes.
 
-```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
-```
-
-| 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:
+## CLI
 
 ```bash
-delimit lint --policy strict old.yaml new.yaml
+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
 ```
 
-## Options
+Or install globally:
 
 ```bash
-# Semver classification with version bump
-delimit lint old.yaml new.yaml --current-version 1.0.0
-
-# 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
+npm install -g delimit-cli
+delimit init --preset default
+delimit lint api/openapi.yaml
 ```
 
-### Explainer Templates
-
-| 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 |
+### Commands
 
-## CI/CD Integration
+| Command | What it does |
+|---------|-------------|
+| `delimit init [--preset]` | Create `.delimit/policies.yml` with a policy preset |
+| `delimit lint <spec>` | Diff + policy check. Exit 1 on violations. |
+| `delimit diff <old> <new>` | Raw diff with `[BREAKING]` / `[safe]` tags |
+| `delimit explain <old> <new>` | Human-readable summary (7 templates) |
 
-Add this workflow to `.github/workflows/api-governance.yml`:
+### Policy presets
 
-```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
+```bash
+delimit init --preset strict    # All breaking changes are errors
+delimit init --preset default   # Breaking = error, type changes = warn
+delimit init --preset relaxed   # Everything is a warning
 ```
 
-The action posts a PR comment with:
-- Semver badge (`MAJOR` / `MINOR` / `PATCH`)
-- Violation table with severity
-- Expandable migration guide for breaking changes
-
-See [Delimit API Governance](https://github.com/marketplace/actions/delimit-api-governance) on the GitHub Marketplace.
+Or inline: `delimit lint --policy strict api/openapi.yaml`
 
-## Custom Policies
+---
 
-Create `.delimit/policies.yml` or start from a preset:
+## What it catches
 
-```yaml
-override_defaults: false
-
-rules:
-  - id: protect_v1
-    name: Protect V1 API
-    change_types: [endpoint_removed, method_removed, field_removed]
-    severity: error
-    action: forbid
-    conditions:
-      path_pattern: "^/v1/.*"
-    message: "V1 API is frozen. Make changes in V2."
-```
+10 breaking change types (endpoint removed, method removed, required param added, param removed, response removed, required field added, response field removed, type changed, format changed, enum value removed) plus 7 non-breaking types for full visibility. Every change classified as `MAJOR`, `MINOR`, `PATCH`, or `NONE`.
 
-## Supported Specs
+Supports OpenAPI 3.0, 3.1, and Swagger 2.0 in YAML or JSON.
 
-- OpenAPI 3.0.x and 3.1.x
-- Swagger 2.0
-- YAML and JSON formats
+---
 
 ## 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)
+- [GitHub Action](https://github.com/marketplace/actions/delimit-api-governance)
+- [delimit-cli on npm](https://www.npmjs.com/package/delimit-cli)
+- [Quickstart repo](https://github.com/delimit-ai/delimit-quickstart)
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 2.x     | Yes       |
+| 1.x     | No        |
+
+## Reporting a Vulnerability
+
+We take security seriously at Delimit. If you discover a security vulnerability, please follow these steps:
+
+1. **Do NOT** create a public GitHub issue
+2. Email security@delimit.ai with:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Your suggested fix (if any)
+
+## Response Timeline
+
+- **Acknowledgment**: Within 24 hours
+- **Initial Assessment**: Within 72 hours
+- **Fix Timeline**: Based on severity
+  - Critical: Within 7 days
+  - High: Within 14 days
+  - Medium: Within 30 days
+  - Low: Next release
+
+## Security Best Practices
+
+When using Delimit:
+
+1. **Never commit API keys or tokens** to your repository
+2. **Use environment variables** for sensitive configuration
+3. **Keep Delimit updated** to the latest version
+4. **Review PR annotations** before merging
+
+## Data Privacy
+
+Delimit processes your API specifications locally. The CLI and GitHub Action do not send your specs to external servers.

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());
+}