@openpkg-ts/cli 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @openpkg-ts/cli
 
+## 0.3.0
+
+### Minor Changes
+
+- bd70dc7: add diagnostics, filter primitives, new CLI commands (breaking, changelog, diagnostics, filter, semver, validate), registry system, render enhancements
+
+### Patch Changes
+
+- Updated dependencies [bd70dc7]
+  - @openpkg-ts/sdk@0.31.0
+  - @openpkg-ts/adapters@0.3.0
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -78,6 +78,9 @@ openpkg docs openpkg.json --split -o docs/api/
 
 # Pipeline: stdin
 openpkg snapshot src/index.ts -o - | openpkg docs - -f md
+
+# With adapter (generates framework-specific output)
+openpkg docs openpkg.json --adapter fumadocs -o docs/api/
 ```
 
 Options:
@@ -86,6 +89,7 @@ Options:
 | `-o, --output <path>` | Output file or directory (default: stdout) |
 | `-f, --format <fmt>` | Format: `md`, `json`, `html` (default: md) |
 | `--split` | One file per export (requires `-o` as directory) |
+| `-a, --adapter <name>` | Use adapter: `fumadocs`, `raw` (default: raw) |
 
 ### diff
 
@@ -104,6 +108,135 @@ Output includes:
 - `docsOnly` - documentation-only changes
 - `summary.semverBump` - recommended version bump
 
+### breaking
+
+Check for breaking changes. Exit 1 if any found.
+
+```bash
+openpkg breaking old.json new.json
+```
+
+Output:
+```json
+{
+  "breaking": [
+    { "id": "createClient", "name": "createClient", "kind": "function", "severity": "high", "reason": "signature changed" }
+  ],
+  "count": 1
+}
+```
+
+### semver
+
+Recommend version bump based on changes.
+
+```bash
+openpkg semver old.json new.json
+```
+
+Output:
+```json
+{
+  "bump": "major",
+  "reason": "1 breaking change detected"
+}
+```
+
+### validate
+
+Validate spec against schema.
+
+```bash
+openpkg validate openpkg.json
+openpkg validate openpkg.json --version 1.0
+```
+
+Output:
+```json
+{
+  "valid": true,
+  "errors": []
+}
+```
+
+### changelog
+
+Generate changelog from diff.
+
+```bash
+openpkg changelog old.json new.json
+openpkg changelog old.json new.json --format json
+```
+
+Markdown output:
+```markdown
+## Breaking Changes
+- **Removed** `oldFunction` (function)
+
+## Added
+- `newFunction`
+```
+
+### diagnostics
+
+Analyze spec for quality issues.
+
+```bash
+openpkg diagnostics openpkg.json
+```
+
+Output:
+```json
+{
+  "summary": {
+    "total": 5,
+    "missingDescriptions": 3,
+    "deprecatedNoReason": 1,
+    "missingParamDocs": 1
+  },
+  "diagnostics": { ... }
+}
+```
+
+### filter
+
+Filter spec by various criteria.
+
+```bash
+openpkg filter openpkg.json --kind function,class
+openpkg filter openpkg.json --has-description -o documented.json
+openpkg filter openpkg.json --search "user" --summary
+openpkg filter openpkg.json --deprecated --quiet | jq '.exports[].name'
+```
+
+Options:
+| Flag | Description |
+|------|-------------|
+| `--kind <kinds>` | Filter by kinds (comma-separated) |
+| `--name <names>` | Filter by exact names (comma-separated) |
+| `--id <ids>` | Filter by export IDs (comma-separated) |
+| `--tag <tags>` | Filter by tags (comma-separated) |
+| `--deprecated` | Only deprecated exports |
+| `--no-deprecated` | Exclude deprecated exports |
+| `--has-description` | Only exports with descriptions |
+| `--missing-description` | Only exports without descriptions |
+| `--search <term>` | Search name/description (case-insensitive) |
+| `--module <path>` | Filter by source file path (contains) |
+| `-o, --output <file>` | Output file (default: stdout) |
+| `--summary` | Only output matched/total counts |
+| `--quiet` | Output raw spec only (no wrapper) |
+
+All criteria use AND logic when combined.
+
+Output (default):
+```json
+{
+  "spec": { ... },
+  "matched": 12,
+  "total": 45
+}
+```
+
 ## Pipelines
 
 Commands are composable via stdin/stdout:

package/bin/openpkg.ts

@@ -2,10 +2,16 @@
 import * as path from 'node:path';
 import { getExport, listExports } from '@openpkg-ts/sdk';
 import { Command } from 'commander';
+import pkg from '../package.json';
+import { createBreakingCommand } from '../src/commands/breaking';
+import { createChangelogCommand } from '../src/commands/changelog';
+import { createDiagnosticsCommand } from '../src/commands/diagnostics';
 import { createDiffCommand } from '../src/commands/diff';
+import { createFilterCommand } from '../src/commands/filter';
 import { createDocsCommand } from '../src/commands/docs';
+import { createSemverCommand } from '../src/commands/semver';
 import { createSnapshotCommand } from '../src/commands/snapshot';
-import pkg from '../package.json';
+import { createValidateCommand } from '../src/commands/validate';
 
 const program = new Command();
 
@@ -57,5 +63,11 @@ program
 program.addCommand(createSnapshotCommand());
 program.addCommand(createDiffCommand());
 program.addCommand(createDocsCommand());
+program.addCommand(createBreakingCommand());
+program.addCommand(createChangelogCommand());
+program.addCommand(createSemverCommand());
+program.addCommand(createValidateCommand());
+program.addCommand(createDiagnosticsCommand());
+program.addCommand(createFilterCommand());
 
 program.parse();

package/dist/index.d.ts

@@ -1,2 +1,12 @@
 import { getExport, listExports } from "@openpkg-ts/sdk";
-export { listExports, getExport };
+import { OpenPkg } from "@openpkg-ts/spec";
+type FilterResult = {
+	spec: OpenPkg;
+	matched: number;
+	total: number;
+};
+type FilterSummaryResult = {
+	matched: number;
+	total: number;
+};
+export { listExports, getExport, FilterSummaryResult, FilterResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "CLI for OpenPkg TypeScript API extraction and documentation generation",
   "homepage": "https://github.com/ryanwaits/openpkg-ts#readme",
   "repository": {
@@ -18,7 +18,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/sdk": "^0.30.2",
+    "@openpkg-ts/adapters": "^0.3.0",
+    "@openpkg-ts/sdk": "^0.31.0",
     "commander": "^14.0.0"
   },
   "devDependencies": {

package/src/commands/breaking.ts

@@ -0,0 +1,46 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { type CategorizedBreaking, categorizeBreakingChanges, diffSpec, type OpenPkg } from '@openpkg-ts/spec';
+import { Command } from 'commander';
+
+export type BreakingResult = {
+  breaking: CategorizedBreaking[];
+  count: number;
+};
+
+function loadSpec(filePath: string): OpenPkg {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content) as OpenPkg;
+}
+
+export function createBreakingCommand(): Command {
+  return new Command('breaking')
+    .description('Check for breaking changes between two specs')
+    .argument('<old>', 'Path to old spec file (JSON)')
+    .argument('<new>', 'Path to new spec file (JSON)')
+    .action(async (oldPath: string, newPath: string) => {
+      try {
+        const oldSpec = loadSpec(oldPath);
+        const newSpec = loadSpec(newPath);
+
+        const diff = diffSpec(oldSpec, newSpec);
+        const categorized = categorizeBreakingChanges(diff.breaking, oldSpec, newSpec);
+
+        const result: BreakingResult = {
+          breaking: categorized,
+          count: categorized.length,
+        };
+
+        console.log(JSON.stringify(result, null, 2));
+
+        if (categorized.length > 0) {
+          process.exit(1);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error(JSON.stringify({ error: error.message }, null, 2));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/changelog.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { OpenPkg } from '@openpkg-ts/spec';
+import { $ } from 'bun';
+
+const oldSpec: OpenPkg = {
+  meta: { name: 'test-pkg', version: '1.0.0' },
+  exports: [
+    { id: 'fn-greet', name: 'greet', kind: 'function', signatures: [] },
+    { id: 'fn-removed', name: 'removed', kind: 'function', signatures: [] },
+  ],
+  types: [],
+};
+
+const newSpec: OpenPkg = {
+  meta: { name: 'test-pkg', version: '2.0.0' },
+  exports: [
+    { id: 'fn-greet', name: 'greet', kind: 'function', signatures: [] },
+    { id: 'fn-added', name: 'added', kind: 'function', signatures: [] },
+  ],
+  types: [],
+};
+
+describe('changelog command', () => {
+  test('outputs JSON format', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'changelog-test-'));
+    const oldPath = path.join(tmpDir, 'old.json');
+    const newPath = path.join(tmpDir, 'new.json');
+
+    fs.writeFileSync(oldPath, JSON.stringify(oldSpec));
+    fs.writeFileSync(newPath, JSON.stringify(newSpec));
+
+    const result = await $`bun packages/cli/bin/openpkg.ts changelog ${oldPath} ${newPath} --format json`.text();
+    const parsed = JSON.parse(result);
+
+    expect(parsed).toHaveProperty('breaking');
+    expect(parsed).toHaveProperty('added');
+    expect(parsed).toHaveProperty('removed');
+    expect(parsed).toHaveProperty('summary');
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('outputs markdown format', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'changelog-test-'));
+    const oldPath = path.join(tmpDir, 'old.json');
+    const newPath = path.join(tmpDir, 'new.json');
+
+    fs.writeFileSync(oldPath, JSON.stringify(oldSpec));
+    fs.writeFileSync(newPath, JSON.stringify(newSpec));
+
+    const result = await $`bun packages/cli/bin/openpkg.ts changelog ${oldPath} ${newPath}`.text();
+
+    expect(result).toContain('## Breaking Changes');
+    expect(result).toContain('removed');
+    expect(result).toContain('## Added');
+    expect(result).toContain('added');
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('empty diff shows no changes', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'changelog-test-'));
+    const oldPath = path.join(tmpDir, 'old.json');
+    const newPath = path.join(tmpDir, 'new.json');
+
+    fs.writeFileSync(oldPath, JSON.stringify(oldSpec));
+    fs.writeFileSync(newPath, JSON.stringify(oldSpec));
+
+    const result = await $`bun packages/cli/bin/openpkg.ts changelog ${oldPath} ${newPath}`.text();
+
+    expect(result.trim()).toBe('No changes detected.');
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+});

package/src/commands/changelog.ts

@@ -0,0 +1,79 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { OpenPkg } from '@openpkg-ts/spec';
+import { Command } from 'commander';
+import { type DiffResult, enrichDiff } from './diff.js';
+
+function loadSpec(filePath: string): OpenPkg {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content) as OpenPkg;
+}
+
+/**
+ * Format diff result as markdown changelog
+ */
+function formatMarkdown(diff: DiffResult): string {
+  const lines: string[] = [];
+
+  // Breaking Changes
+  if (diff.removed.length > 0 || diff.changed.length > 0) {
+    lines.push('## Breaking Changes');
+    lines.push('');
+    for (const r of diff.removed) {
+      lines.push(`- **Removed** \`${r.name}\` (${r.kind})`);
+    }
+    for (const c of diff.changed) {
+      lines.push(`- **${c.name}** (${c.kind}): ${c.description}`);
+    }
+    lines.push('');
+  }
+
+  // Added
+  if (diff.added.length > 0) {
+    lines.push('## Added');
+    lines.push('');
+    for (const id of diff.added) {
+      lines.push(`- \`${id}\``);
+    }
+    lines.push('');
+  }
+
+  // Changed (docs only)
+  if (diff.docsOnly.length > 0) {
+    lines.push('## Changed');
+    lines.push('');
+    for (const id of diff.docsOnly) {
+      lines.push(`- \`${id}\` (docs)`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trim() || 'No changes detected.';
+}
+
+export function createChangelogCommand(): Command {
+  return new Command('changelog')
+    .description('Generate changelog from diff between two specs')
+    .argument('<old>', 'Path to old spec file (JSON)')
+    .argument('<new>', 'Path to new spec file (JSON)')
+    .option('--format <format>', 'Output format: md or json', 'md')
+    .action(async (oldPath: string, newPath: string, options: { format?: string }) => {
+      try {
+        const oldSpec = loadSpec(oldPath);
+        const newSpec = loadSpec(newPath);
+
+        const diff = enrichDiff(oldSpec, newSpec);
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify(diff, null, 2));
+        } else {
+          console.log(formatMarkdown(diff));
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error(JSON.stringify({ error: error.message }, null, 2));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/diagnostics.test.ts

@@ -0,0 +1,55 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { $ } from 'bun';
+
+describe('openpkg diagnostics', () => {
+  let tmpDir: string;
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'diagnostics-test-'));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it('outputs JSON with diagnostics', async () => {
+    const specPath = path.join(tmpDir, 'spec.json');
+    const spec = {
+      openpkg: '0.4.0',
+      meta: { name: 'test-pkg' },
+      exports: [
+        { id: 'a', name: 'noDesc', kind: 'function' },
+        { id: 'b', name: 'withDesc', kind: 'function', description: 'Has desc' },
+        {
+          id: 'c',
+          name: 'depNoReason',
+          kind: 'function',
+          description: 'Something',
+          deprecated: true,
+        },
+      ],
+    };
+    fs.writeFileSync(specPath, JSON.stringify(spec));
+
+    const output = await $`bun packages/cli/bin/openpkg.ts diagnostics ${specPath}`.text();
+    const result = JSON.parse(output);
+
+    expect(result.summary.total).toBe(2);
+    expect(result.summary.missingDescriptions).toBe(1);
+    expect(result.summary.deprecatedNoReason).toBe(1);
+    expect(result.diagnostics.missingDescriptions[0].exportName).toBe('noDesc');
+  });
+
+  it('handles malformed spec gracefully', async () => {
+    const specPath = path.join(tmpDir, 'bad.json');
+    fs.writeFileSync(specPath, '{ invalid json');
+
+    const output = await $`bun packages/cli/bin/openpkg.ts diagnostics ${specPath}`.text();
+    const result = JSON.parse(output);
+
+    expect(result.error).toBeDefined();
+  });
+});

package/src/commands/diagnostics.ts

@@ -0,0 +1,55 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { analyzeSpec, type SpecDiagnostics } from '@openpkg-ts/sdk';
+import type { OpenPkg } from '@openpkg-ts/spec';
+import { Command } from 'commander';
+
+export interface DiagnosticsResult {
+  summary: {
+    total: number;
+    missingDescriptions: number;
+    deprecatedNoReason: number;
+    missingParamDocs: number;
+  };
+  diagnostics: SpecDiagnostics;
+}
+
+function loadJSON(filePath: string): unknown {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content);
+}
+
+export function createDiagnosticsCommand(): Command {
+  return new Command('diagnostics')
+    .description('Analyze spec for quality issues (missing docs, deprecated without reason)')
+    .argument('<spec>', 'Path to spec file (JSON)')
+    .action(async (specPath: string) => {
+      try {
+        const spec = loadJSON(specPath) as OpenPkg;
+
+        const diagnostics = analyzeSpec(spec);
+
+        const result: DiagnosticsResult = {
+          summary: {
+            total:
+              diagnostics.missingDescriptions.length +
+              diagnostics.deprecatedNoReason.length +
+              diagnostics.missingParamDocs.length,
+            missingDescriptions: diagnostics.missingDescriptions.length,
+            deprecatedNoReason: diagnostics.deprecatedNoReason.length,
+            missingParamDocs: diagnostics.missingParamDocs.length,
+          },
+          diagnostics,
+        };
+
+        console.log(JSON.stringify(result, null, 2));
+        // Always exit 0 - informational only
+        process.exit(0);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.log(JSON.stringify({ error: error.message }, null, 2));
+        process.exit(0);
+      }
+    });
+}

package/src/commands/diff.ts

@@ -75,7 +75,6 @@ export function enrichDiff(oldSpec: OpenPkg, newSpec: OpenPkg): DiffResult {
   const semver = recommendSemverBump(rawDiff);
 
   const oldExports = toExportMap(oldSpec);
-  const _newExports = toExportMap(newSpec);
 
   // Separate removed from changed
   const removed: RemovedExport[] = [];

package/src/commands/docs.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { OpenPkg } from '@openpkg-ts/spec';
+import { $ } from 'bun';
+
+const testSpec: OpenPkg = {
+  meta: { name: 'test-pkg', version: '1.0.0' },
+  exports: [
+    { id: 'fn-hello', name: 'hello', kind: 'function', signatures: [] },
+    { id: 'fn-world', name: 'world', kind: 'function', signatures: [] },
+  ],
+  types: [],
+};
+
+describe('docs command --adapter', () => {
+  test('--adapter fumadocs generates docs', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'docs-adapter-test-'));
+    const specPath = path.join(tmpDir, 'spec.json');
+    const outDir = path.join(tmpDir, 'out');
+
+    fs.writeFileSync(specPath, JSON.stringify(testSpec));
+
+    await $`bun packages/cli/bin/openpkg.ts docs ${specPath} --adapter fumadocs --output ${outDir}`.text();
+
+    expect(fs.existsSync(outDir)).toBe(true);
+    expect(fs.existsSync(path.join(outDir, 'hello.md'))).toBe(true);
+    expect(fs.existsSync(path.join(outDir, 'world.md'))).toBe(true);
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('--adapter raw falls through to default', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'docs-adapter-test-'));
+    const specPath = path.join(tmpDir, 'spec.json');
+
+    fs.writeFileSync(specPath, JSON.stringify(testSpec));
+
+    const result = await $`bun packages/cli/bin/openpkg.ts docs ${specPath} --adapter raw`.text();
+
+    expect(result).toContain('hello');
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('--adapter unknown exits with error', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'docs-adapter-test-'));
+    const specPath = path.join(tmpDir, 'spec.json');
+    const outDir = path.join(tmpDir, 'out');
+
+    fs.writeFileSync(specPath, JSON.stringify(testSpec));
+
+    const result = await $`bun packages/cli/bin/openpkg.ts docs ${specPath} --adapter unknown --output ${outDir}`.nothrow();
+
+    expect(result.exitCode).toBe(1);
+    // Error is written to stderr as JSON
+    const stderr = result.stderr.toString();
+    expect(stderr).toContain('Failed to load adapter');
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+});

package/src/commands/docs.ts

@@ -10,6 +10,8 @@ interface DocsCommandOptions {
   output?: string;
   format?: OutputFormat;
   split?: boolean;
+  export?: string;
+  adapter?: string;
 }
 
 async function readStdin(): Promise<string> {
@@ -37,11 +39,11 @@ function renderExport(docs: DocsInstance, exportId: string, format: OutputFormat
 
   switch (format) {
     case 'json':
-      return JSON.stringify(docs.toJSON({ exportId }), null, 2);
+      return JSON.stringify(docs.toJSON({ export: exportId }), null, 2);
     case 'html':
-      return docs.toHTML({ exportId });
+      return docs.toHTML({ export: exportId });
     default:
-      return docs.toMarkdown({ exportId, frontmatter: true, codeSignatures: true });
+      return docs.toMarkdown({ export: exportId, frontmatter: true, codeSignatures: true });
   }
 }
 
@@ -63,10 +65,55 @@ export function createDocsCommand(): Command {
     .option('-o, --output <path>', 'Output file or directory (default: stdout)')
     .option('-f, --format <format>', 'Output format: md, json, html (default: md)', 'md')
     .option('--split', 'Output one file per export (requires --output as directory)')
+    .option('-e, --export <name>', 'Generate docs for a single export by name')
+    .option('-a, --adapter <name>', 'Use adapter for generation (default: raw)')
     .action(async (specPath: string, options: DocsCommandOptions) => {
       const format = (options.format || 'md') as OutputFormat;
 
       try {
+        // Handle adapter mode
+        if (options.adapter && options.adapter !== 'raw') {
+          // Dynamic import adapter to trigger self-registration
+          let getAdapter: typeof import('@openpkg-ts/adapters').getAdapter;
+          try {
+            const adapterModule = await import(`@openpkg-ts/adapters/${options.adapter}`);
+            const registryModule = await import('@openpkg-ts/adapters');
+            getAdapter = registryModule.getAdapter;
+          } catch {
+            console.error(JSON.stringify({ error: `Failed to load adapter: ${options.adapter}` }));
+            process.exit(1);
+          }
+
+          const adapter = getAdapter(options.adapter);
+          if (!adapter) {
+            console.error(JSON.stringify({ error: `Unknown adapter: ${options.adapter}` }));
+            process.exit(1);
+          }
+
+          if (!options.output) {
+            console.error(JSON.stringify({ error: '--adapter requires --output <directory>' }));
+            process.exit(1);
+          }
+
+          // Load spec
+          let spec: OpenPkg;
+          if (specPath === '-') {
+            const input = await readStdin();
+            spec = JSON.parse(input);
+          } else {
+            const specFile = path.resolve(specPath);
+            if (!fs.existsSync(specFile)) {
+              console.error(JSON.stringify({ error: `Spec file not found: ${specFile}` }));
+              process.exit(1);
+            }
+            spec = JSON.parse(fs.readFileSync(specFile, 'utf-8'));
+          }
+
+          await adapter.generate(spec, path.resolve(options.output));
+          console.error(`Generated docs with ${options.adapter} adapter to ${options.output}`);
+          return;
+        }
+
         let docs: DocsInstance;
 
         // Handle stdin
@@ -83,6 +130,25 @@ export function createDocsCommand(): Command {
           docs = createDocs(specFile);
         }
 
+        // Single export mode
+        if (options.export) {
+          const exports = docs.getAllExports();
+          const exp = exports.find(e => e.name === options.export);
+          if (!exp) {
+            console.error(JSON.stringify({ error: `Export not found: ${options.export}` }));
+            process.exit(1);
+          }
+          const output = renderExport(docs, exp.id, format);
+          if (options.output && options.output !== '-') {
+            const outputPath = path.resolve(options.output);
+            fs.writeFileSync(outputPath, output);
+            console.error(`Wrote ${outputPath}`);
+          } else {
+            console.log(output);
+          }
+          return;
+        }
+
         // Split mode: one file per export
         if (options.split) {
           if (!options.output) {

package/src/commands/filter.test.ts

@@ -0,0 +1,210 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { $ } from 'bun';
+
+describe('openpkg filter', () => {
+  let tmpDir: string;
+  let specPath: string;
+
+  const spec = {
+    openpkg: '0.4.0',
+    meta: { name: 'test-pkg' },
+    exports: [
+      { id: 'a', name: 'myFunction', kind: 'function', description: 'A function' },
+      { id: 'b', name: 'MyClass', kind: 'class', description: 'A class' },
+      { id: 'c', name: 'myVar', kind: 'variable' },
+      { id: 'd', name: 'deprecatedFn', kind: 'function', deprecated: true, description: 'Old' },
+      {
+        id: 'e',
+        name: 'taggedFn',
+        kind: 'function',
+        tags: [{ name: 'beta' }],
+        description: 'Beta feature',
+      },
+      {
+        id: 'f',
+        name: 'anotherClass',
+        kind: 'class',
+        source: { file: 'src/utils/helpers.ts' },
+      },
+    ],
+  };
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'filter-test-'));
+    specPath = path.join(tmpDir, 'spec.json');
+    fs.writeFileSync(specPath, JSON.stringify(spec));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it('filters by kind', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind function`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(3);
+    expect(result.total).toBe(6);
+    expect(result.spec.exports.every((e: { kind: string }) => e.kind === 'function')).toBe(true);
+  });
+
+  it('filters by multiple kinds', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind function,class`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(5);
+  });
+
+  it('filters by name', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --name myFunction,MyClass`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(2);
+  });
+
+  it('filters by deprecated flag', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --deprecated`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(1);
+    expect(result.spec.exports[0].name).toBe('deprecatedFn');
+  });
+
+  it('filters by non-deprecated', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --no-deprecated`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(5);
+  });
+
+  it('filters by has-description', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --has-description`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(4);
+  });
+
+  it('filters by missing-description', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --missing-description`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(2);
+  });
+
+  it('filters by search term', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --search beta`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(1);
+    expect(result.spec.exports[0].name).toBe('taggedFn');
+  });
+
+  it('filters by tag', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --tag beta`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(1);
+    expect(result.spec.exports[0].name).toBe('taggedFn');
+  });
+
+  it('filters by module path', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --module src/utils`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(1);
+    expect(result.spec.exports[0].name).toBe('anotherClass');
+  });
+
+  it('combines filters with AND logic', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind function --has-description`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(3);
+  });
+
+  it('outputs summary only with --summary', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind function --summary`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(3);
+    expect(result.total).toBe(6);
+    expect(result.spec).toBeUndefined();
+  });
+
+  it('outputs raw spec with --quiet', async () => {
+    const output =
+      await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind function --quiet`.text();
+    const result = JSON.parse(output);
+
+    expect(result.openpkg).toBe('0.4.0');
+    expect(result.exports.length).toBe(3);
+    expect(result.matched).toBeUndefined();
+  });
+
+  it('writes to file with --output', async () => {
+    const outPath = path.join(tmpDir, 'filtered.json');
+    await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind class -o ${outPath}`.text();
+
+    const content = JSON.parse(fs.readFileSync(outPath, 'utf-8'));
+    expect(content.matched).toBe(2);
+  });
+
+  it('errors on invalid kind', async () => {
+    const proc = await $`bun packages/cli/bin/openpkg.ts filter ${specPath} --kind invalid`
+      .nothrow()
+      .quiet();
+    const result = JSON.parse(proc.stderr.toString());
+
+    expect(result.error).toContain('Invalid kind(s): invalid');
+    expect(result.error).toContain('Valid kinds:');
+  });
+
+  it('returns all exports with no criteria', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts filter ${specPath}`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(6);
+    expect(result.total).toBe(6);
+  });
+
+  it('handles empty spec', async () => {
+    const emptyPath = path.join(tmpDir, 'empty.json');
+    fs.writeFileSync(emptyPath, JSON.stringify({ openpkg: '0.4.0', meta: {}, exports: [] }));
+
+    const output = await $`bun packages/cli/bin/openpkg.ts filter ${emptyPath} --kind function`.text();
+    const result = JSON.parse(output);
+
+    expect(result.matched).toBe(0);
+    expect(result.total).toBe(0);
+  });
+
+  it('errors on malformed JSON', async () => {
+    const badPath = path.join(tmpDir, 'bad.json');
+    fs.writeFileSync(badPath, '{ invalid json }');
+
+    const proc = await $`bun packages/cli/bin/openpkg.ts filter ${badPath}`.nothrow().quiet();
+    const result = JSON.parse(proc.stderr.toString());
+
+    expect(result.error).toBeDefined();
+  });
+
+  it('errors on missing file', async () => {
+    const proc = await $`bun packages/cli/bin/openpkg.ts filter /nonexistent/path.json`
+      .nothrow()
+      .quiet();
+    const result = JSON.parse(proc.stderr.toString());
+
+    expect(result.error).toBeDefined();
+  });
+});

package/src/commands/filter.ts

@@ -0,0 +1,131 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { filterSpec, type FilterCriteria } from '@openpkg-ts/sdk';
+import type { OpenPkg, SpecExportKind } from '@openpkg-ts/spec';
+import { Command } from 'commander';
+
+const VALID_KINDS: SpecExportKind[] = [
+  'function',
+  'class',
+  'variable',
+  'interface',
+  'type',
+  'enum',
+  'module',
+  'namespace',
+  'reference',
+  'external',
+];
+
+export type FilterResult = {
+  spec: OpenPkg;
+  matched: number;
+  total: number;
+};
+
+export type FilterSummaryResult = {
+  matched: number;
+  total: number;
+};
+
+function loadSpec(filePath: string): OpenPkg {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content) as OpenPkg;
+}
+
+function parseList(val?: string): string[] | undefined {
+  if (!val) return undefined;
+  return val
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function validateKinds(kinds: string[]): SpecExportKind[] {
+  const invalid = kinds.filter((k) => !VALID_KINDS.includes(k as SpecExportKind));
+  if (invalid.length > 0) {
+    throw new Error(`Invalid kind(s): ${invalid.join(', ')}. Valid kinds: ${VALID_KINDS.join(', ')}`);
+  }
+  return kinds as SpecExportKind[];
+}
+
+export function createFilterCommand(): Command {
+  return new Command('filter')
+    .description('Filter an OpenPkg spec by various criteria')
+    .argument('<spec>', 'Path to spec file (JSON)')
+    .option('--kind <kinds>', 'Filter by kinds (comma-separated)')
+    .option('--name <names>', 'Filter by exact names (comma-separated)')
+    .option('--id <ids>', 'Filter by IDs (comma-separated)')
+    .option('--tag <tags>', 'Filter by tags (comma-separated)')
+    .option('--deprecated', 'Only deprecated exports')
+    .option('--no-deprecated', 'Exclude deprecated exports')
+    .option('--has-description', 'Only exports with descriptions')
+    .option('--missing-description', 'Only exports without descriptions')
+    .option('--search <term>', 'Search name/description (case-insensitive)')
+    .option('--module <path>', 'Filter by source file path (contains)')
+    .option('-o, --output <file>', 'Output file (default: stdout)')
+    .option('--summary', 'Only output matched/total counts')
+    .option('--quiet', 'Output raw spec only (no wrapper)')
+    .action(
+      async (
+        specPath: string,
+        options: {
+          kind?: string;
+          name?: string;
+          id?: string;
+          tag?: string;
+          deprecated?: boolean;
+          hasDescription?: boolean;
+          missingDescription?: boolean;
+          search?: string;
+          module?: string;
+          output?: string;
+          summary?: boolean;
+          quiet?: boolean;
+        }
+      ) => {
+        try {
+          const spec = loadSpec(specPath);
+
+          const criteria: FilterCriteria = {};
+
+          if (options.kind) {
+            const kinds = parseList(options.kind);
+            if (kinds) criteria.kinds = validateKinds(kinds);
+          }
+          if (options.name) criteria.names = parseList(options.name);
+          if (options.id) criteria.ids = parseList(options.id);
+          if (options.tag) criteria.tags = parseList(options.tag);
+          if (options.deprecated !== undefined) criteria.deprecated = options.deprecated;
+          if (options.hasDescription) criteria.hasDescription = true;
+          if (options.missingDescription) criteria.hasDescription = false;
+          if (options.search) criteria.search = options.search;
+          if (options.module) criteria.module = options.module;
+
+          const result = filterSpec(spec, criteria);
+
+          let output: OpenPkg | FilterResult | FilterSummaryResult;
+          if (options.summary) {
+            output = { matched: result.matched, total: result.total };
+          } else if (options.quiet) {
+            output = result.spec;
+          } else {
+            output = { spec: result.spec, matched: result.matched, total: result.total };
+          }
+
+          const json = JSON.stringify(output, null, 2);
+
+          if (options.output) {
+            fs.writeFileSync(path.resolve(options.output), json);
+          } else {
+            console.log(json);
+          }
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          console.error(JSON.stringify({ error: error.message }, null, 2));
+          process.exit(1);
+        }
+      }
+    );
+}

package/src/commands/semver.ts

@@ -0,0 +1,43 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { diffSpec, type OpenPkg, recommendSemverBump, type SemverBump } from '@openpkg-ts/spec';
+import { Command } from 'commander';
+
+export type SemverResult = {
+  bump: SemverBump;
+  reason: string;
+};
+
+function loadSpec(filePath: string): OpenPkg {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content) as OpenPkg;
+}
+
+export function createSemverCommand(): Command {
+  return new Command('semver')
+    .description('Recommend semver bump based on spec changes')
+    .argument('<old>', 'Path to old spec file (JSON)')
+    .argument('<new>', 'Path to new spec file (JSON)')
+    .action(async (oldPath: string, newPath: string) => {
+      try {
+        const oldSpec = loadSpec(oldPath);
+        const newSpec = loadSpec(newPath);
+
+        const diff = diffSpec(oldSpec, newSpec);
+        const recommendation = recommendSemverBump(diff);
+
+        const result: SemverResult = {
+          bump: recommendation.bump,
+          reason: recommendation.reason,
+        };
+
+        console.log(JSON.stringify(result, null, 2));
+        // Always exit 0 - this is a recommendation only
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error(JSON.stringify({ error: error.message }, null, 2));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/validate.ts

@@ -0,0 +1,45 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getValidationErrors, type SchemaVersion, type SpecError } from '@openpkg-ts/spec';
+import { Command } from 'commander';
+
+export type ValidateResult = {
+  valid: boolean;
+  errors: SpecError[];
+};
+
+function loadJSON(filePath: string): unknown {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content);
+}
+
+export function createValidateCommand(): Command {
+  return new Command('validate')
+    .description('Validate an OpenPkg spec against the schema')
+    .argument('<spec>', 'Path to spec file (JSON)')
+    .option('--version <version>', 'Schema version to validate against (default: latest)')
+    .action(async (specPath: string, options: { version?: string }) => {
+      try {
+        const spec = loadJSON(specPath);
+        const version = (options.version ?? 'latest') as SchemaVersion;
+
+        const errors = getValidationErrors(spec, version);
+
+        const result: ValidateResult = {
+          valid: errors.length === 0,
+          errors,
+        };
+
+        console.log(JSON.stringify(result, null, 2));
+
+        if (errors.length > 0) {
+          process.exit(1);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error(JSON.stringify({ error: error.message }, null, 2));
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -1,2 +1,3 @@
 // CLI package - entry point for programmatic use if needed
 export { getExport, listExports } from '@openpkg-ts/sdk';
+export { type FilterResult, type FilterSummaryResult } from './commands/filter';

package/test/e2e/release-workflow.test.ts

@@ -0,0 +1,189 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { OpenPkg } from '@openpkg-ts/spec';
+import { $ } from 'bun';
+
+/**
+ * E2E test for full release workflow:
+ * old.json → new.json → breaking check → semver → changelog → docs (fumadocs)
+ */
+describe('release workflow e2e', () => {
+  let tmpDir: string;
+  let oldPath: string;
+  let newPath: string;
+
+  const oldSpec: OpenPkg = {
+    openpkg: '0.4.0',
+    meta: { name: 'test-pkg', version: '1.0.0' },
+    exports: [
+      {
+        id: 'fn-greet',
+        name: 'greet',
+        kind: 'function',
+        description: 'Greets a person',
+        signatures: [
+          {
+            parameters: [
+              { name: 'name', schema: { type: 'string' }, description: 'Person name' },
+            ],
+            returns: { schema: { type: 'string' }, description: 'Greeting message' },
+          },
+        ],
+      },
+      {
+        id: 'fn-goodbye',
+        name: 'goodbye',
+        kind: 'function',
+        description: 'Says goodbye',
+        signatures: [],
+      },
+    ],
+    types: [],
+  };
+
+  const newSpec: OpenPkg = {
+    openpkg: '0.4.0',
+    meta: { name: 'test-pkg', version: '2.0.0' },
+    exports: [
+      {
+        id: 'fn-greet',
+        name: 'greet',
+        kind: 'function',
+        description: 'Greets a person with optional message',
+        signatures: [
+          {
+            parameters: [
+              { name: 'name', schema: { type: 'string' }, description: 'Person name' },
+              { name: 'message', schema: { type: 'string' }, description: 'Optional message' },
+            ],
+            returns: { schema: { type: 'string' }, description: 'Greeting message' },
+          },
+        ],
+      },
+      {
+        id: 'fn-hello',
+        name: 'hello',
+        kind: 'function',
+        description: 'New hello function',
+        signatures: [],
+      },
+    ],
+    types: [],
+  };
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'release-workflow-test-'));
+    oldPath = path.join(tmpDir, 'old.json');
+    newPath = path.join(tmpDir, 'new.json');
+
+    fs.writeFileSync(oldPath, JSON.stringify(oldSpec));
+    fs.writeFileSync(newPath, JSON.stringify(newSpec));
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it('detects breaking changes', async () => {
+    const proc = Bun.spawn(['bun', 'packages/cli/bin/openpkg.ts', 'breaking', oldPath, newPath]);
+    const stdout = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    const result = JSON.parse(stdout);
+
+    // Should find breaking change: goodbye removed
+    expect(result.count).toBeGreaterThan(0);
+    expect(exitCode).toBe(1); // exits 1 when breaking changes found
+  });
+
+  it('recommends semver bump', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts semver ${oldPath} ${newPath}`.text();
+    const result = JSON.parse(output);
+
+    expect(result.bump).toBe('major'); // breaking change = major
+    expect(result.reason).toBeDefined();
+  });
+
+  it('generates changelog', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts changelog ${oldPath} ${newPath} --format json`.text();
+    const result = JSON.parse(output);
+
+    expect(result.breaking).toBeDefined();
+    expect(result.added).toBeDefined();
+    expect(result.removed).toBeDefined();
+    expect(result.summary).toBeDefined();
+
+    // Verify removed function detected (removed has full objects)
+    const removed = result.removed.find((r: { name: string }) => r.name === 'goodbye');
+    expect(removed).toBeDefined();
+
+    // Verify added function detected (added is array of IDs)
+    expect(result.added).toContain('fn-hello');
+  });
+
+  it('generates markdown docs', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts docs ${newPath}`.text();
+
+    expect(output).toContain('greet');
+    expect(output).toContain('hello');
+    expect(output).toContain('Greets a person');
+  });
+
+  it('generates json docs', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts docs ${newPath} --format json`.text();
+    const result = JSON.parse(output);
+
+    expect(result.name).toBe('test-pkg');
+    expect(result.exports).toBeDefined();
+    expect(result.exports.length).toBe(2);
+  });
+
+  it('generates fumadocs output', async () => {
+    const docsDir = path.join(tmpDir, 'fumadocs-output');
+
+    await $`bun packages/cli/bin/openpkg.ts docs ${newPath} --adapter fumadocs --output ${docsDir}`;
+
+    // Verify directory created
+    expect(fs.existsSync(docsDir)).toBe(true);
+
+    // Verify markdown files created (one per export)
+    const files = fs.readdirSync(docsDir);
+    const mdFiles = files.filter((f) => f.endsWith('.md'));
+    expect(mdFiles.length).toBe(2); // greet.md, hello.md
+  });
+
+  it('validates new spec', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts validate ${newPath}`.text();
+    const result = JSON.parse(output);
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('runs diagnostics on new spec', async () => {
+    const output = await $`bun packages/cli/bin/openpkg.ts diagnostics ${newPath}`.text();
+    const result = JSON.parse(output);
+
+    expect(result.summary).toBeDefined();
+    expect(result.diagnostics).toBeDefined();
+  });
+
+  it('full workflow runs without error', async () => {
+    // Simulate complete release workflow sequence
+    const steps = [
+      $`bun packages/cli/bin/openpkg.ts validate ${oldPath}`,
+      $`bun packages/cli/bin/openpkg.ts validate ${newPath}`,
+      $`bun packages/cli/bin/openpkg.ts semver ${oldPath} ${newPath}`,
+      $`bun packages/cli/bin/openpkg.ts changelog ${oldPath} ${newPath} --format json`,
+      $`bun packages/cli/bin/openpkg.ts diagnostics ${newPath}`,
+      $`bun packages/cli/bin/openpkg.ts docs ${newPath} --format json`,
+    ];
+
+    for (const step of steps) {
+      const output = await step.text();
+      expect(() => JSON.parse(output)).not.toThrow();
+    }
+  });
+});