@openpkg-ts/cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @openpkg-ts/cli
+
+## 0.2.0
+
+### Minor Changes
+
+- Major monorepo restructure: extract → sdk, doc-generator split into sdk/react/adapters, fumadocs-adapter deleted (use @openpkg-ts/adapters/fumadocs)
+
+### Patch Changes
+
+- Updated dependencies
+  - @openpkg-ts/sdk@0.30.0

package/README.md

@@ -1,134 +1,131 @@
-# OpenPkg CLI
+# @openpkg-ts/cli
 
-[![npm version](https://img.shields.io/npm/v/@openpkg-ts%2Fcli.svg)](https://www.npmjs.com/package/@openpkg-ts/cli)
+CLI for TypeScript API extraction and documentation generation.
 
-Command-line interface for producing OpenPkg specs from TypeScript projects.
-
-## Installation
+## Install
 
 ```bash
-# npm
 npm install -g @openpkg-ts/cli
-
-# bun
-bun add -g @openpkg-ts/cli
-
-# yarn
-yarn global add @openpkg-ts/cli
-
-# pnpm
-pnpm add -g @openpkg-ts/cli
+# or use directly
+npx @openpkg-ts/cli <command>
 ```
 
-## Quick Start
+## Commands
 
-```bash
-# Generate openpkg.json for the current package
-openpkg generate
+### list
 
-# Target a specific entry file
-openpkg generate src/index.ts
+List exports from entry point.
 
-# Scaffold an OpenPkg config
-openpkg init
+```bash
+openpkg list src/index.ts
 ```
 
-`openpkg generate` discovers the package manifest, figures out the correct entry point, resolves external .d.ts files when `node_modules` is present, and writes `openpkg.json` by default.
-
-## Commands
+Output: JSON array of `{ name, kind, file, line, description }`
 
-### `openpkg init`
+### get
 
-Create a starter `openpkg.config` file in the current project. The CLI picks an extension automatically:
-
-- `openpkg.config.js` when the nearest `package.json` declares `{ "type": "module" }`
-- `openpkg.config.mjs` otherwise (compatible with both ESM and CommonJS projects)
+Get detailed spec for single export.
 
 ```bash
-openpkg init --cwd . --format auto
+openpkg get src/index.ts createClient
 ```
 
-Options:
+Output: JSON with `{ export, types }` - full spec for the export plus referenced types.
 
-- `--cwd <dir>` – Directory where the config should be created (defaults to current directory).
-- `--format <auto|mjs|js|cjs>` – Override the generated file extension.
+### snapshot
 
-The command aborts when a config already exists anywhere up the directory tree.
+Generate full OpenPkg spec from TypeScript.
 
-### `openpkg generate [entry]`
+```bash
+# Write to file
+openpkg snapshot src/index.ts -o openpkg.json
 
-Generate an OpenPkg spec from a file or package entry point.
+# Stdout (pipeable)
+openpkg snapshot src/index.ts -o -
 
-```bash
-openpkg generate src/index.ts --output lib/openpkg.json --include=createUser
+# With options
+openpkg snapshot src/index.ts --max-depth 4 --runtime --verify
+openpkg snapshot src/index.ts --only "use*,create*" --ignore "*Internal"
 ```
 
-Key behaviors:
+Options:
+| Flag | Description |
+|------|-------------|
+| `-o, --output <file>` | Output file (default: openpkg.json, `-` for stdout) |
+| `--max-depth <n>` | Max type depth (default: 4) |
+| `--skip-resolve` | Skip external type resolution |
+| `--runtime` | Enable Standard Schema runtime extraction (Zod, Valibot) |
+| `--only <exports>` | Filter exports (comma-separated, wildcards) |
+| `--ignore <exports>` | Ignore exports (comma-separated, wildcards) |
+| `--verify` | Exit 1 if any exports fail |
 
-- Auto-detects the entry point when `[entry]` is omitted (using `exports`, `main`, or TypeScript config fields).
-- Honors `openpkg.config.*` defaults and then applies CLI flags on top.
-- Emits diagnostics from the TypeScript compiler and from OpenPkg's filtering passes.
-- Writes formatted JSON to `openpkg.json` (or the path supplied via `--output`).
+### docs
 
-#### Options
+Generate documentation from spec.
 
-- `[entry]` – Entry file to analyze. Optional when the package exposes a single entry point.
-- `-o, --output <file>` – Output path (default: `openpkg.json`).
-- `-p, --package <name>` – Resolve and analyze a workspace package by name.
-- `--cwd <dir>` – Base directory for resolution (default: current directory).
-- `--no-external-types` – Skip pulling types from `node_modules`.
-- `--include <ids>` – Keep only the listed export identifiers (comma-separated or repeatable).
-- `--exclude <ids>` – Drop the listed export identifiers.
-- `-y, --yes` – Assume "yes" for prompts.
+```bash
+# Markdown (default)
+openpkg docs openpkg.json -o api.md
 
-## Configuration File
+# HTML
+openpkg docs openpkg.json -f html -o api.html
 
-Create an `openpkg.config.ts`, `.js`, or `.mjs` file anywhere above your working directory to keep reusable defaults. Prefer `.mjs`/`.cjs` if you are running the CLI under Node.js without a TypeScript loader.
+# JSON (simplified structure)
+openpkg docs openpkg.json -f json
 
-```ts
-// openpkg.config.mjs
-import { defineConfig } from '@openpkg-ts/cli/config';
+# Split: one file per export
+openpkg docs openpkg.json --split -o docs/api/
 
-export default defineConfig({
-  include: ['createUser', 'deleteUser'],
-  exclude: ['internalHelper'],
-  resolveExternalTypes: true,
-});
+# Pipeline: stdin
+openpkg snapshot src/index.ts -o - | openpkg docs - -f md
 ```
 
-The CLI searches the current directory and its parents for the first config file and merges those settings with flags provided on the command line. `defineConfig` helps with type-safety but is optional—you can export a plain object as well.
-
-### Supported Options
+Options:
+| Flag | Description |
+|------|-------------|
+| `-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) |
 
-- `include: string[]` – Export identifiers to keep.
-- `exclude: string[]` – Export identifiers to drop.
-- `resolveExternalTypes?: boolean` – Override automatic detection of external type resolution.
+### diff
 
-CLI flags always win over config values. When both provide filters, the CLI prints a short summary of how the sets were combined.
+Compare two specs for breaking changes.
 
-## Filtering Tips
+```bash
+openpkg diff old.json new.json
+openpkg diff old.json new.json --summary
+```
 
-- `--include` narrows the spec to the identifiers you care about. Any referenced types that fall outside the allow-list are removed unless they are still referenced.
-- `--exclude` is useful for dropping experimental or internal APIs while keeping everything else.
-- Combine filters in configuration for defaults and override per run via CLI flags.
+Output includes:
+- `breaking` - categorized breaking changes
+- `added` - new exports
+- `removed` - removed exports
+- `changed` - modified exports
+- `docsOnly` - documentation-only changes
+- `summary.semverBump` - recommended version bump
 
-## Monorepo Support
+## Pipelines
 
-Supply `--package <name>` from the workspace root to locate a child package automatically. The CLI understands npm, pnpm, yarn, and bun workspace layouts.
+Commands are composable via stdin/stdout:
 
 ```bash
-openpkg generate --package @myorg/transactions
-```
+# Extract and generate docs
+openpkg snapshot src/index.ts -o - | openpkg docs - -f md > api.md
 
-## Output
+# Extract, verify, then diff
+openpkg snapshot src/index.ts --verify -o new.json
+openpkg diff baseline.json new.json --summary
+```
 
-After a successful run the CLI prints:
+## Programmatic Use
 
-- The relative path to the written spec.
-- Counts for exports and types earned after filtering.
-- Any diagnostics collected during analysis.
+```typescript
+import { getExport, listExports } from '@openpkg-ts/cli';
 
-The JSON schema for the output lives at `schemas/v0.1.0/openpkg.schema.json` in this repository.
+// Same primitives as CLI
+const { exports } = await listExports({ entryFile: './src/index.ts' });
+const { export: spec } = await getExport({ entryFile: './src/index.ts', exportName: 'myFunc' });
+```
 
 ## License
 

package/bin/openpkg.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+import { Command } from 'commander';
+import { getExport, listExports } from '@openpkg-ts/sdk';
+import { createSnapshotCommand } from '../src/commands/snapshot';
+import { createDiffCommand } from '../src/commands/diff';
+import { createDocsCommand } from '../src/commands/docs';
+import * as path from 'node:path';
+
+const program = new Command();
+
+program
+  .name('openpkg')
+  .description('OpenPkg CLI - TypeScript API extraction primitives')
+  .version('0.1.0');
+
+program
+  .command('list')
+  .description('List exports from a TypeScript entry point')
+  .argument('<entry>', 'Entry point file path')
+  .action(async (entry: string) => {
+    const entryFile = path.resolve(entry);
+    const result = await listExports({ entryFile });
+
+    if (result.errors.length > 0) {
+      console.error(JSON.stringify({ errors: result.errors }, null, 2));
+      process.exit(1);
+    }
+
+    console.log(JSON.stringify(result.exports, null, 2));
+  });
+
+program
+  .command('get')
+  .description('Get detailed spec for a single export')
+  .argument('<entry>', 'Entry point file path')
+  .argument('<name>', 'Export name')
+  .action(async (entry: string, name: string) => {
+    const entryFile = path.resolve(entry);
+    const result = await getExport({ entryFile, exportName: name });
+
+    if (!result.export) {
+      const errorMsg = result.errors.length > 0
+        ? result.errors.join('; ')
+        : `Export '${name}' not found`;
+      console.error(JSON.stringify({ error: errorMsg }, null, 2));
+      process.exit(1);
+    }
+
+    // Output export with related types if any
+    const output: Record<string, unknown> = { export: result.export };
+    if (result.types.length > 0) {
+      output.types = result.types;
+    }
+    console.log(JSON.stringify(output, null, 2));
+  });
+
+program.addCommand(createSnapshotCommand());
+program.addCommand(createDiffCommand());
+program.addCommand(createDocsCommand());
+
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { getExport, listExports } from "@openpkg-ts/sdk";
+export { listExports, getExport };

package/dist/index.js

@@ -0,0 +1,6 @@
+// src/index.ts
+import { getExport, listExports } from "@openpkg-ts/sdk";
+export {
+  listExports,
+  getExport
+};

package/package.json

@@ -1,58 +1,19 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.1.0",
-  "description": "OpenAPI-like specification generator for TypeScript packages",
-  "keywords": [
-    "typescript",
-    "cli",
-    "documentation",
-    "openpkg",
-    "package-analysis",
-    "openapi"
-  ],
-  "homepage": "https://github.com/openpkg/openpkg#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/openpkg/openpkg.git",
-    "directory": "packages/cli"
-  },
-  "license": "MIT",
-  "author": "Ryan Waits",
+  "version": "0.2.0",
+  "description": "CLI for OpenPkg TypeScript API extraction",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "bin": {
-    "openpkg": "./dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./config": {
-      "import": "./dist/config/index.js",
-      "types": "./dist/config/index.d.ts"
-    }
+    "openpkg": "./bin/openpkg.ts"
   },
   "scripts": {
     "build": "bunup",
     "dev": "bunup --watch",
-    "cli": "bun run src/cli.ts",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "format": "biome format --write src/"
+    "test": "bun test"
   },
-  "files": [
-    "dist"
-  ],
   "dependencies": {
-    "@inquirer/prompts": "^7.8.0",
-    "@openpkg-ts/sdk": "^0.1.0",
-    "@openpkg-ts/spec": "^0.1.0",
-    "chalk": "^5.4.1",
-    "commander": "^14.0.0",
-    "ora": "^8.2.0",
-    "zod": "^4.0.5"
+    "@openpkg-ts/sdk": "workspace:*",
+    "commander": "^14.0.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/commands/diff.ts

@@ -0,0 +1,173 @@
+import { Command } from 'commander';
+import {
+  diffSpec,
+  categorizeBreakingChanges,
+  recommendSemverBump,
+  type OpenPkg,
+  type CategorizedBreaking,
+  type SemverBump,
+  type SpecExportKind,
+} from '@openpkg-ts/spec';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * A changed export with details about what changed
+ */
+export interface ChangedExport {
+  id: string;
+  name: string;
+  kind: SpecExportKind;
+  description: string;
+}
+
+/**
+ * Enriched diff result with categorized changes
+ */
+export interface DiffResult {
+  breaking: CategorizedBreaking[];
+  added: string[];
+  removed: RemovedExport[];
+  changed: ChangedExport[];
+  docsOnly: string[];
+  summary: {
+    breakingCount: number;
+    addedCount: number;
+    removedCount: number;
+    changedCount: number;
+    docsOnlyCount: number;
+    semverBump: SemverBump;
+    semverReason: string;
+  };
+}
+
+export interface RemovedExport {
+  id: string;
+  name: string;
+  kind: SpecExportKind;
+}
+
+function loadSpec(filePath: string): OpenPkg {
+  const resolved = path.resolve(filePath);
+  const content = fs.readFileSync(resolved, 'utf-8');
+  return JSON.parse(content) as OpenPkg;
+}
+
+function toExportMap(spec: OpenPkg): Map<string, { name: string; kind: SpecExportKind }> {
+  const map = new Map<string, { name: string; kind: SpecExportKind }>();
+  for (const exp of spec.exports) {
+    map.set(exp.id, { name: exp.name, kind: exp.kind });
+  }
+  if (spec.types) {
+    for (const t of spec.types) {
+      map.set(t.id, { name: t.name, kind: t.kind as SpecExportKind });
+    }
+  }
+  return map;
+}
+
+/**
+ * Enriches basic diffSpec output with categorization
+ */
+export function enrichDiff(oldSpec: OpenPkg, newSpec: OpenPkg): DiffResult {
+  const rawDiff = diffSpec(oldSpec, newSpec);
+  const categorized = categorizeBreakingChanges(rawDiff.breaking, oldSpec, newSpec);
+  const semver = recommendSemverBump(rawDiff);
+
+  const oldExports = toExportMap(oldSpec);
+  const newExports = toExportMap(newSpec);
+
+  // Separate removed from changed
+  const removed: RemovedExport[] = [];
+  const changed: ChangedExport[] = [];
+  const breaking: CategorizedBreaking[] = [];
+
+  for (const cat of categorized) {
+    if (cat.reason === 'removed') {
+      const info = oldExports.get(cat.id);
+      removed.push({
+        id: cat.id,
+        name: cat.name,
+        kind: info?.kind ?? cat.kind,
+      });
+    } else {
+      // It's a change, not a removal
+      changed.push({
+        id: cat.id,
+        name: cat.name,
+        kind: cat.kind,
+        description: describeChange(cat),
+      });
+      breaking.push(cat);
+    }
+  }
+
+  // Added exports
+  const added = rawDiff.nonBreaking;
+
+  return {
+    breaking,
+    added,
+    removed,
+    changed,
+    docsOnly: rawDiff.docsOnly,
+    summary: {
+      breakingCount: breaking.length,
+      addedCount: added.length,
+      removedCount: removed.length,
+      changedCount: changed.length,
+      docsOnlyCount: rawDiff.docsOnly.length,
+      semverBump: semver.bump,
+      semverReason: semver.reason,
+    },
+  };
+}
+
+/**
+ * Generate human-readable description for a change
+ */
+function describeChange(cat: CategorizedBreaking): string {
+  switch (cat.reason) {
+    case 'signature changed':
+      return `Function signature changed`;
+    case 'type definition changed':
+      return `Type definition changed`;
+    case 'constructor changed':
+      return `Class constructor signature changed`;
+    case 'methods removed':
+      return `Class methods removed`;
+    case 'methods changed':
+      return `Class methods changed`;
+    case 'changed':
+      return `${cat.kind} changed`;
+    default:
+      return cat.reason;
+  }
+}
+
+export function createDiffCommand(): Command {
+  return new Command('diff')
+    .description('Compare two OpenPkg specs and show differences')
+    .argument('<old>', 'Path to old spec file (JSON)')
+    .argument('<new>', 'Path to new spec file (JSON)')
+    .option('--json', 'Output as JSON (default)')
+    .option('--summary', 'Only show summary')
+    .action(async (oldPath: string, newPath: string, options: { json?: boolean; summary?: boolean }) => {
+      try {
+        const oldSpec = loadSpec(oldPath);
+        const newSpec = loadSpec(newPath);
+
+        const result = enrichDiff(oldSpec, newSpec);
+
+        if (options.summary) {
+          console.log(JSON.stringify(result.summary, null, 2));
+        } else {
+          console.log(JSON.stringify(result, null, 2));
+        }
+      } 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/docs.ts

@@ -0,0 +1,122 @@
+import { Command } from 'commander';
+import { createDocs, loadSpec, type DocsInstance } from '@openpkg-ts/sdk';
+import type { OpenPkg } from '@openpkg-ts/spec';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+type OutputFormat = 'md' | 'json' | 'html';
+
+interface DocsCommandOptions {
+  output?: string;
+  format?: OutputFormat;
+  split?: boolean;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+function getExtension(format: OutputFormat): string {
+  switch (format) {
+    case 'json': return '.json';
+    case 'html': return '.html';
+    default: return '.md';
+  }
+}
+
+function renderExport(docs: DocsInstance, exportId: string, format: OutputFormat): string {
+  const exp = docs.getExport(exportId);
+  if (!exp) throw new Error(`Export not found: ${exportId}`);
+
+  switch (format) {
+    case 'json':
+      return JSON.stringify(docs.toJSON({ exportId }), null, 2);
+    case 'html':
+      return docs.toHTML({ exportId });
+    default:
+      return docs.toMarkdown({ exportId, frontmatter: true, codeSignatures: true });
+  }
+}
+
+function renderFull(docs: DocsInstance, format: OutputFormat): string {
+  switch (format) {
+    case 'json':
+      return JSON.stringify(docs.toJSON(), null, 2);
+    case 'html':
+      return docs.toHTML();
+    default:
+      return docs.toMarkdown({ frontmatter: true, codeSignatures: true });
+  }
+}
+
+export function createDocsCommand(): Command {
+  return new Command('docs')
+    .description('Generate documentation from OpenPkg spec')
+    .argument('<spec>', 'Path to openpkg.json spec file (use - for stdin)')
+    .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)')
+    .action(async (specPath: string, options: DocsCommandOptions) => {
+      const format = (options.format || 'md') as OutputFormat;
+
+      try {
+        let docs: DocsInstance;
+
+        // Handle stdin
+        if (specPath === '-') {
+          const input = await readStdin();
+          const spec: OpenPkg = JSON.parse(input);
+          docs = loadSpec(spec);
+        } else {
+          const specFile = path.resolve(specPath);
+          if (!fs.existsSync(specFile)) {
+            console.error(JSON.stringify({ error: `Spec file not found: ${specFile}` }));
+            process.exit(1);
+          }
+          docs = createDocs(specFile);
+        }
+
+        // Split mode: one file per export
+        if (options.split) {
+          if (!options.output) {
+            console.error(JSON.stringify({ error: '--split requires --output <directory>' }));
+            process.exit(1);
+          }
+
+          const outDir = path.resolve(options.output);
+          if (!fs.existsSync(outDir)) {
+            fs.mkdirSync(outDir, { recursive: true });
+          }
+
+          const exports = docs.getAllExports();
+          for (const exp of exports) {
+            const filename = `${exp.name}${getExtension(format)}`;
+            const filePath = path.join(outDir, filename);
+            const content = renderExport(docs, exp.id, format);
+            fs.writeFileSync(filePath, content);
+          }
+          console.error(`Wrote ${exports.length} files to ${outDir}`);
+          return;
+        }
+
+        // Single output mode
+        const output = renderFull(docs, format);
+
+        if (options.output && options.output !== '-') {
+          const outputPath = path.resolve(options.output);
+          fs.writeFileSync(outputPath, output);
+          console.error(`Wrote ${outputPath}`);
+        } else {
+          console.log(output);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error(JSON.stringify({ error: error.message }));
+        process.exit(1);
+      }
+    });
+}