delimit-cli 2.1.0 → 2.2.0

package/.github/workflows/api-governance.yml

@@ -3,22 +3,41 @@ name: API Governance
 on:
   pull_request:
     paths:
-      - '**.json'
-      - '**.yaml'
-      - '**.yml'
-      - 'openapi/**'
-      - 'api/**'
-      - 'swagger/**'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.json'
+      - 'lib/**'
 
 jobs:
   api-check:
+    name: Delimit API Check
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - uses: actions/checkout@v4
         with:
-          fetch-depth: 0
-          
-      - name: Detect API breaking changes
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+
+      - name: Check for spec changes
+        id: spec-check
+        run: |
+          # Find any OpenAPI/Swagger specs in the repo
+          SPECS=$(find . -path ./base -prune -o \( -name "openapi*.yaml" -o -name "openapi*.yml" -o -name "openapi*.json" -o -name "swagger*.yaml" -o -name "swagger*.json" \) -print | head -1)
+          if [ -n "$SPECS" ]; then
+            echo "spec_found=true" >> $GITHUB_OUTPUT
+            echo "spec_path=$SPECS" >> $GITHUB_OUTPUT
+          else
+            echo "spec_found=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Delimit
+        if: steps.spec-check.outputs.spec_found == 'true'
         uses: delimit-ai/delimit-action@v1
         with:
-          advisory_mode: true
+          old_spec: base/${{ steps.spec-check.outputs.spec_path }}
+          new_spec: ${{ steps.spec-check.outputs.spec_path }}
+          mode: advisory

package/README.md

@@ -1,97 +1,112 @@
-# Delimit
+# delimit-cli
 
-**API governance CLI for development teams.** Detect breaking API changes, enforce policies, and maintain audit trails across your services.
+**ESLint for API contracts** — detect breaking changes, enforce semver, and generate migration guides for OpenAPI specs.
 
-[![npm](https://img.shields.io/npm/v/delimit)](https://www.npmjs.com/package/delimit)
+[![npm](https://img.shields.io/npm/v/delimit-cli)](https://www.npmjs.com/package/delimit-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ## Install
 
 ```bash
-npm install -g delimit
+npm install -g delimit-cli
 ```
 
+This installs the `delimit` command globally.
+
 ## Quick Start
 
 ```bash
-# Check current governance status
-delimit status
+# Initialize a policy file in your repo
+delimit init
+
+# Detect breaking changes between two specs
+delimit lint api/openapi-old.yaml api/openapi-new.yaml
 
-# Set up governance for this repo (advisory mode by default)
-delimit install --mode advisory
+# See raw diff output
+delimit diff api/openapi-old.yaml api/openapi-new.yaml
 
-# Validate an API spec
-delimit validate api/openapi.yaml
+# Generate a human-readable explanation
+delimit explain api/openapi-old.yaml api/openapi-new.yaml
 ```
 
-## Governance Modes
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `delimit init` | Create `.delimit/policies.yml` with default rules |
+| `delimit lint <old> <new>` | Diff + policy check with semver badge and violations |
+| `delimit diff <old> <new>` | Raw diff with `[BREAKING]`/`[safe]` tags |
+| `delimit explain <old> <new>` | Human-readable change explanation |
 
-Delimit supports three enforcement levels. You choose:
+### Options
 
 ```bash
-delimit install --mode advisory   # Warnings only, no blocking
-delimit install --mode guarded    # Soft enforcement with overrides
-delimit install --mode enforce    # Strict policy enforcement
-```
+# Specify explainer template (default: developer)
+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
 
-### Scope Control
+# Include semver classification
+delimit lint old.yaml new.yaml --current-version 1.0.0
 
-```bash
-delimit install --scope repo      # Current repository only
-delimit install --scope global    # All repositories on this machine
+# Use custom policy file
+delimit lint old.yaml new.yaml -p .delimit/policies.yml
 ```
 
-## What It Does
+### Explainer Templates
 
-- **API Change Detection** — Identifies breaking changes in OpenAPI/Swagger specs
-- **Policy Enforcement** — Applies configurable governance rules to API changes
-- **Evidence Collection** — Records audit trail of all governance decisions
-- **MCP Integration** — Works with Claude, Gemini, and other AI coding tools via Model Context Protocol
+| 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 |
 
-## Usage with CI
+## CI/CD Integration
 
-For CI/CD integration, use the GitHub Action instead:
+For automated PR checks, use the GitHub Action:
 
 ```yaml
 - uses: delimit-ai/delimit-action@v1
+  with:
+    old_spec: base/api/openapi.yaml
+    new_spec: api/openapi.yaml
 ```
 
-See [delimit-action](https://github.com/delimit-ai/delimit-action) for full CI setup.
+See [Delimit API Governance](https://github.com/marketplace/actions/delimit-api-governance) on the GitHub Marketplace.
 
-## Commands
+## Custom Policies
 
-| Command | Description |
-|---------|-------------|
-| `delimit status` | Show current governance state |
-| `delimit install` | Set up governance hooks and config |
-| `delimit validate <spec>` | Validate an API specification |
-| `delimit doctor` | Diagnose configuration issues |
-| `delimit uninstall` | Clean removal of all hooks and config |
-
-## Uninstall
-
-```bash
-delimit uninstall
-```
-
-Cleanly removes all hooks, PATH modifications, and configuration files.
-
-## Configuration
-
-Create `.delimit/policies.yml` in your repository:
+Create `.delimit/policies.yml`:
 
 ```yaml
 rules:
   - id: no_endpoint_removal
     change_types: [endpoint_removed]
     severity: error
+    action: forbid
     message: "Endpoints cannot be removed without deprecation"
+
+  - id: warn_type_change
+    change_types: [type_changed]
+    severity: warning
+    action: warn
+    message: "Type change may break clients"
 ```
 
+## Supported Specs
+
+- OpenAPI 3.0.x and 3.1.x
+- Swagger 2.0
+- YAML and JSON formats
+
 ## Links
 
-- [GitHub Action](https://github.com/delimit-ai/delimit-action) — CI/CD integration
-- [Website](https://delimit.ai) — Documentation and platform
+- [GitHub Action](https://github.com/marketplace/actions/delimit-api-governance) — CI/CD integration
+- [GitHub](https://github.com/delimit-ai/delimit) — Source code
 - [Issues](https://github.com/delimit-ai/delimit/issues) — Bug reports and feature requests
 
 ## License

package/bin/delimit-cli.js

@@ -783,20 +783,66 @@ rules: []
     });
 
 // Lint command — diff + policy (primary command)
+// Supports zero-spec mode: `delimit lint` (no args) auto-extracts from FastAPI
 program
-    .command('lint <old_spec> <new_spec>')
+    .command('lint [old_spec] [new_spec]')
     .description('Lint API specs for breaking changes and policy violations')
     .option('-p, --policy <file>', 'Custom policy file')
     .option('--current-version <ver>', 'Current API version for semver bump')
     .option('-n, --name <name>', 'API name for context')
     .option('--json', 'Output raw JSON')
+    .option('-d, --dir <path>', 'Project directory for zero-spec mode', '.')
     .action(async (oldSpec, newSpec, options) => {
         try {
-            const result = apiEngine.lint(
-                path.resolve(oldSpec),
-                path.resolve(newSpec),
-                { policy: options.policy, version: options.currentVersion, name: options.name }
-            );
+            let result;
+
+            if (!oldSpec || !newSpec) {
+                // Zero-spec mode: extract from framework source
+                console.log(chalk.gray('No spec files provided — detecting framework...'));
+                const zeroResult = apiEngine.zeroSpec(path.resolve(options.dir));
+
+                if (!zeroResult.success) {
+                    console.error(chalk.red(`\n  ${zeroResult.error}\n`));
+                    if (zeroResult.error_type === 'no_framework') {
+                        console.log('  Usage: delimit lint <old_spec> <new_spec>');
+                        console.log('  Or run from a FastAPI project directory.\n');
+                    }
+                    process.exit(1);
+                    return;
+                }
+
+                console.log(chalk.green(`  ${zeroResult.message}`));
+                console.log(`  Extracted: ${zeroResult.paths_count} paths, ${zeroResult.schemas_count} schemas`);
+                console.log(`  Spec: ${zeroResult.spec_path}\n`);
+
+                // Check for baseline
+                const baselineDir = path.join(path.resolve(options.dir), '.delimit');
+                const baselinePath = path.join(baselineDir, 'baseline.yaml');
+
+                if (!fs.existsSync(baselinePath)) {
+                    // First run: save baseline
+                    fs.mkdirSync(baselineDir, { recursive: true });
+                    const yaml = require('js-yaml');
+                    fs.writeFileSync(baselinePath, yaml.dump(zeroResult.spec));
+                    console.log(chalk.green('  Saved baseline to .delimit/baseline.yaml'));
+                    console.log('  Run again after making changes to see the diff.\n');
+                    process.exit(0);
+                    return;
+                }
+
+                // Compare against baseline
+                result = apiEngine.lint(
+                    baselinePath,
+                    zeroResult.spec_path,
+                    { policy: options.policy, version: options.currentVersion, name: options.name }
+                );
+            } else {
+                result = apiEngine.lint(
+                    path.resolve(oldSpec),
+                    path.resolve(newSpec),
+                    { policy: options.policy, version: options.currentVersion, name: options.name }
+                );
+            }
 
             if (options.json) {
                 console.log(JSON.stringify(result, null, 2));

package/lib/api-engine.js

@@ -153,4 +153,42 @@ function semver(oldSpec, newSpec, currentVersion) {
     ].join('\n'));
 }
 
-module.exports = { lint, diff, explain, semver, GATEWAY_ROOT };
+/**
+ * delimit zero-spec — extract OpenAPI from framework source code
+ */
+function zeroSpec(projectDir, opts = {}) {
+    const args = [];
+    if (opts.pythonBin) args.push(`python_bin=${pyStr(opts.pythonBin)}`);
+
+    return runGateway([
+        'import json, sys',
+        'sys.path.insert(0, ".")',
+        'from core.zero_spec.detector import detect_framework, Framework',
+        'from core.zero_spec.fastapi_extractor import extract_fastapi_spec',
+        'from core.zero_spec.nestjs_extractor import extract_nestjs_spec',
+        'from core.zero_spec.express_extractor import extract_express_spec',
+        `info = detect_framework(${pyStr(projectDir)})`,
+        'r = {"framework": info.framework.value, "confidence": info.confidence, "message": info.message}',
+        'if info.framework == Framework.FASTAPI:',
+        `    ext = extract_fastapi_spec(info, ${pyStr(projectDir)}${opts.pythonBin ? `, python_bin=${pyStr(opts.pythonBin)}` : ''})`,
+        '    r.update(ext)',
+        '    if ext.get("success") and info.app_locations:',
+        '        r["app_file"] = info.app_locations[0].file',
+        'elif info.framework == Framework.NESTJS:',
+        `    ext = extract_nestjs_spec(info, ${pyStr(projectDir)})`,
+        '    r.update(ext)',
+        '    if ext.get("success") and info.app_locations:',
+        '        r["app_file"] = info.app_locations[0].file',
+        'elif info.framework == Framework.EXPRESS:',
+        `    ext = extract_express_spec(info, ${pyStr(projectDir)})`,
+        '    r.update(ext)',
+        '    if ext.get("success") and info.app_locations:',
+        '        r["app_file"] = info.app_locations[0].file',
+        'else:',
+        '    r["success"] = False',
+        '    r["error"] = "No supported API framework detected"',
+        'print(json.dumps(r, default=str))',
+    ].join('\n'));
+}
+
+module.exports = { lint, diff, explain, semver, zeroSpec, GATEWAY_ROOT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delimit-cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "ESLint for API contracts — detect breaking changes, enforce semver, and generate migration guides for OpenAPI specs",
   "main": "index.js",
   "bin": {