@openpkg-ts/cli 0.6.4 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ryan Waits
+
+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,233 +1,48 @@
 # @openpkg-ts/cli
 
-CLI for TypeScript API extraction and documentation generation.
+CLI for [OpenPkg](https://github.com/ryanwaits/openpkg-ts) — extract TypeScript API specs and generate docs. Thin wrapper over [@openpkg-ts/sdk](https://www.npmjs.com/package/@openpkg-ts/sdk).
 
-## Install
+## Usage
 
 ```bash
-npm install -g @openpkg-ts/cli
-# or use directly
-npx @openpkg-ts/cli <command>
-```
-
-## Command Structure
-
-Commands organized under `openpkg spec` and `openpkg docs`. Legacy commands work as aliases.
-
-```bash
-openpkg spec snapshot ./src/index.ts -o spec.json
-openpkg spec validate spec.json
-
-openpkg docs init
-openpkg docs generate spec.json -o ./docs
-openpkg docs add function-section
-```
-
----
-
-## Spec Commands
-
-### list
-
-```bash
-openpkg list src/index.ts
-```
+# Extract an OpenPkg spec
+bunx @openpkg-ts/cli spec src/index.ts -o openpkg.json
 
-Output: JSON array of `{ name, kind, file, line, description }`
+# Generate markdown docs (from source or an existing spec)
+bunx @openpkg-ts/cli docs src/index.ts -o docs/api.md
+bunx @openpkg-ts/cli docs openpkg.json -f html -o docs/api.html
 
-### get
+# List exports
+bunx @openpkg-ts/cli list src/index.ts
 
-```bash
-openpkg get src/index.ts createClient
+# Diff two specs, get a semver recommendation
+bunx @openpkg-ts/cli diff old.json new.json
 ```
 
-Output: JSON with `{ export, types }` - full spec for the export plus referenced types.
+## Commands
 
-### spec snapshot
+| Command | Description |
+|---------|-------------|
+| `spec <entry.ts>` | Extract an OpenPkg spec from a TypeScript entry point |
+| `docs <entry.ts \| spec.json>` | Generate docs (`-f md\|html\|json`) |
+| `list <entry.ts>` | List exports with kind and location (`--json`) |
+| `diff <old.json> <new.json>` | Compare specs; exits 2 if breaking changes |
 
-```bash
-openpkg spec snapshot src/index.ts -o openpkg.json
-openpkg spec snapshot src/index.ts -o -  # stdout
-openpkg spec snapshot src/index.ts --max-depth 4 --runtime --verify
-openpkg spec snapshot src/index.ts --only "use*,create*" --ignore "*Internal"
-```
+`-o, --output` writes to a file instead of stdout.
 
-| 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 |
+For programmatic use, richer options, and framework integrations (search indexes, nav trees), use `@openpkg-ts/sdk` directly.
 
-### spec validate
+## Agent-assisted docs generation
 
-```bash
-openpkg spec validate openpkg.json
-openpkg spec validate openpkg.json --version 1.0
-```
-
-### spec diagnostics
+The package ships an agent skill that scaffolds framework-ready API reference pages (Fumadocs, Docusaurus, or plain Markdown) — framework detection, page-per-export MDX with navigation, search indexes, and output verification. Copy it into your project's skills directory:
 
 ```bash
-openpkg spec diagnostics openpkg.json
+cp -r node_modules/@openpkg-ts/cli/skills/generate-docs .claude/skills/
 ```
 
-### spec filter
-
-```bash
-openpkg spec filter openpkg.json --kind function,class
-openpkg spec filter openpkg.json --has-description -o documented.json
-openpkg spec filter openpkg.json --search "user" --summary
-openpkg spec filter openpkg.json --deprecated --quiet | jq '.exports[].name'
-```
-
-| 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) |
-
-### spec diff
-
-```bash
-openpkg spec diff old.json new.json
-openpkg spec diff old.json new.json --summary
-```
-
-### spec breaking
-
-Exit 1 if breaking changes found.
-
-```bash
-openpkg spec breaking old.json new.json
-```
-
-### spec semver
-
-```bash
-openpkg spec semver old.json new.json
-```
-
-### spec changelog
-
-```bash
-openpkg spec changelog old.json new.json
-openpkg spec changelog old.json new.json --format json
-```
-
----
-
-## Docs Commands
-
-### docs init
-
-Initialize docs configuration.
+Then ask your agent to "generate API docs" (or run `/generate-docs` in Claude Code).
 
-```bash
-openpkg docs init
-```
-
-Creates `openpkg.config.json` with default settings.
-
-### docs generate
-
-Generate documentation from spec.
-
-```bash
-# Markdown (default)
-openpkg docs generate openpkg.json -o api.md
-
-# React layout (single layout + spec JSON, add components via registry)
-openpkg docs generate openpkg.json -f react -o ./app/api
-
-# HTML
-openpkg docs generate openpkg.json -f html -o api.html
-
-# JSON (simplified structure)
-openpkg docs generate openpkg.json -f json
-
-# Split: one file per export
-openpkg docs generate openpkg.json --split -o docs/api/
-
-# With adapter
-openpkg docs generate openpkg.json -a fumadocs -o docs/api/
-
-# From stdin
-openpkg spec snapshot src/index.ts -o - | openpkg docs generate - -f md
-```
-
-| Flag | Description |
-|------|-------------|
-| `-o, --output <path>` | Output file or directory (default: stdout) |
-| `-f, --format <fmt>` | Format: `md`, `json`, `html`, `react` (default: md) |
-| `--split` | One file per export (requires `-o` as directory) |
-| `-a, --adapter <name>` | Use adapter: `fumadocs`, `raw` (default: raw) |
-
-### docs add
-
-Add components from shadcn-compatible registry.
-
-```bash
-openpkg docs add function-section
-openpkg docs add class-section interface-section
-openpkg docs add export-card param-table signature
-```
-
-### docs list
-
-List available registry components.
-
-```bash
-openpkg docs list
-```
-
-16 components available: layouts, sections, primitives.
-
-### docs view
-
-View component details and dependencies.
-
-```bash
-openpkg docs view function-section
-```
-
----
-
-## Pipelines
-
-Commands are composable via stdin/stdout:
-
-```bash
-# Extract and generate docs
-openpkg spec snapshot src/index.ts -o - | openpkg docs generate - -f md > api.md
-
-# Extract, verify, then diff
-openpkg spec snapshot src/index.ts --verify -o new.json
-openpkg spec diff baseline.json new.json --summary
-```
-
-## Programmatic Use
-
-```typescript
-import { getExport, listExports } from '@openpkg-ts/sdk';
-
-// Same primitives as CLI
-const { exports } = await listExports({ entryFile: './src/index.ts' });
-const { export: spec } = await getExport({ entryFile: './src/index.ts', exportName: 'myFunc' });
-```
+> Versions ≤ 0.6.4 are broken (unresolvable dependency) and deprecated. Use 0.7.0+.
 
 ## License
 

package/dist/index.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import {
+  createDocs,
+  diffSpecs,
+  extractSpec,
+  listExports,
+  recommendSemverBump
+} from "@openpkg-ts/sdk";
+var HELP = `openpkg - extract TypeScript API specs and generate docs
+
+Usage:
+  openpkg spec <entry.ts> [-o spec.json]
+  openpkg docs <entry.ts | spec.json> [-f md|html|json] [-o out]
+  openpkg list <entry.ts> [--json]
+  openpkg diff <old.json> <new.json>
+
+Commands:
+  spec    Extract an OpenPkg spec from a TypeScript entry point
+  docs    Generate docs from an entry point or an existing spec file
+  list    List exports (name, kind, location)
+  diff    Compare two spec files and recommend a semver bump
+
+Options:
+  -o, --output   Write to file instead of stdout
+  -f, --format   docs output format: md (default), html, json
+      --json     list output as JSON
+  -h, --help     Show this help
+  -v, --version  Show version
+`;
+function fail(message) {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+function write(content, output) {
+  if (output) {
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(output, content);
+    console.error(`wrote ${output}`);
+  } else {
+    console.log(content);
+  }
+}
+function version() {
+  const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+  return pkg.version;
+}
+function reportDiagnostics(diagnostics) {
+  for (const d of diagnostics) {
+    if (d.severity === "error" || d.severity === "warning") {
+      console.error(`${d.severity}: ${d.message}`);
+    }
+  }
+}
+async function specCommand(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: { output: { type: "string", short: "o" } },
+    allowPositionals: true
+  });
+  const entryFile = positionals[0];
+  if (!entryFile)
+    fail("spec requires an entry file (openpkg spec src/index.ts)");
+  const { spec, diagnostics } = await extractSpec({ entryFile });
+  reportDiagnostics(diagnostics);
+  write(JSON.stringify(spec, null, 2), values.output);
+}
+async function docsCommand(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      output: { type: "string", short: "o" },
+      format: { type: "string", short: "f" }
+    },
+    allowPositionals: true
+  });
+  const input = positionals[0];
+  if (!input)
+    fail("docs requires an entry file or spec file (openpkg docs src/index.ts)");
+  const format = values.format ?? "md";
+  if (!["md", "html", "json"].includes(format))
+    fail(`unknown format "${format}" (md|html|json)`);
+  let docs;
+  if (input.endsWith(".json")) {
+    docs = createDocs(input);
+  } else {
+    const { spec, diagnostics } = await extractSpec({ entryFile: input });
+    reportDiagnostics(diagnostics);
+    docs = createDocs(spec);
+  }
+  const content = format === "md" ? docs.toMarkdown() : format === "html" ? docs.toHTML() : JSON.stringify(docs.toJSON(), null, 2);
+  write(content, values.output);
+}
+async function listCommand(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: { json: { type: "boolean" } },
+    allowPositionals: true
+  });
+  const entryFile = positionals[0];
+  if (!entryFile)
+    fail("list requires an entry file (openpkg list src/index.ts)");
+  const { exports } = await listExports({ entryFile });
+  if (values.json) {
+    console.log(JSON.stringify(exports, null, 2));
+    return;
+  }
+  for (const exp of exports) {
+    const location = exp.file ? ` (${exp.file}:${exp.line})` : "";
+    console.log(`${exp.kind.padEnd(10)}${exp.name}${location}`);
+  }
+}
+function readSpecFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch (err) {
+    fail(`failed to read spec file ${file}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function diffCommand(args) {
+  const [oldFile, newFile] = args;
+  if (!oldFile || !newFile)
+    fail("diff requires two spec files (openpkg diff old.json new.json)");
+  const diff = diffSpecs(readSpecFile(oldFile), readSpecFile(newFile));
+  const recommendation = recommendSemverBump(diff);
+  const section = (title, items) => {
+    if (!items.length)
+      return;
+    console.log(`${title}:`);
+    for (const item of items)
+      console.log(`  - ${item}`);
+  };
+  section("Breaking", diff.breaking);
+  section("Non-breaking", diff.nonBreaking);
+  section("Docs-only", diff.docsOnly);
+  if (!diff.breaking.length && !diff.nonBreaking.length && !diff.docsOnly.length) {
+    console.log("No changes.");
+  }
+  console.log(`
+Recommended bump: ${recommendation.bump} (${recommendation.reason})`);
+  if (diff.breaking.length)
+    process.exitCode = 2;
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "spec":
+      await specCommand(rest);
+      break;
+    case "docs":
+      await docsCommand(rest);
+      break;
+    case "list":
+      await listCommand(rest);
+      break;
+    case "diff":
+      diffCommand(rest);
+      break;
+    case "-v":
+    case "--version":
+      console.log(version());
+      break;
+    case undefined:
+    case "-h":
+    case "--help":
+      console.log(HELP);
+      break;
+    default:
+      fail(`unknown command "${command}" - run openpkg --help`);
+  }
+}
+main().catch((err) => {
+  fail(err instanceof Error ? err.message : String(err));
+});

package/package.json

@@ -1,31 +1,41 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.6.4",
-  "description": "CLI for OpenPkg TypeScript API extraction and documentation generation",
+  "version": "0.8.0",
+  "description": "CLI for OpenPkg - extract TypeScript API specs and generate docs",
+  "keywords": [
+    "openpkg",
+    "typescript",
+    "api-extractor",
+    "cli",
+    "docs"
+  ],
   "homepage": "https://github.com/ryanwaits/openpkg-ts#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ryanwaits/openpkg-ts.git",
     "directory": "packages/cli"
   },
+  "license": "MIT",
+  "author": "Ryan Waits",
   "type": "module",
-  "main": "./dist/src/index.js",
-  "types": "./dist/src/index.d.ts",
   "bin": {
-    "openpkg": "./dist/bin/openpkg.js"
+    "openpkg": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "bunup",
     "dev": "bunup --watch",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
+    "typecheck": "tsc --noEmit -p .",
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/adapters": "^0.3.15",
-    "@openpkg-ts/sdk": "^0.36.0",
-    "commander": "^14.0.0"
+    "@openpkg-ts/sdk": "^0.38.0"
   },
   "devDependencies": {
     "@types/bun": "latest",