@openpkg-ts/cli 0.5.1 → 0.6.1

package/README.md

@@ -10,11 +10,24 @@ npm install -g @openpkg-ts/cli
 npx @openpkg-ts/cli <command>
 ```
 
-## Commands
+## Command Structure
 
-### list
+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
+```
+
+---
 
-List exports from entry point.
+## Spec Commands
+
+### list
 
 ```bash
 openpkg list src/index.ts
@@ -24,31 +37,21 @@ Output: JSON array of `{ name, kind, file, line, description }`
 
 ### get
 
-Get detailed spec for single export.
-
 ```bash
 openpkg get src/index.ts createClient
 ```
 
 Output: JSON with `{ export, types }` - full spec for the export plus referenced types.
 
-### snapshot
-
-Generate full OpenPkg spec from TypeScript.
+### spec snapshot
 
 ```bash
-# Write to file
-openpkg snapshot src/index.ts -o openpkg.json
-
-# Stdout (pipeable)
-openpkg snapshot src/index.ts -o -
-
-# With options
-openpkg snapshot src/index.ts --max-depth 4 --runtime --verify
-openpkg snapshot src/index.ts --only "use*,create*" --ignore "*Internal"
+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"
 ```
 
-Options:
 | Flag | Description |
 |------|-------------|
 | `-o, --output <file>` | Output file (default: openpkg.json, `-` for stdout) |
@@ -59,195 +62,161 @@ Options:
 | `--ignore <exports>` | Ignore exports (comma-separated, wildcards) |
 | `--verify` | Exit 1 if any exports fail |
 
-### docs
-
-Generate documentation from spec.
+### spec validate
 
 ```bash
-# Markdown (default)
-openpkg docs openpkg.json -o api.md
-
-# HTML
-openpkg docs openpkg.json -f html -o api.html
+openpkg spec validate openpkg.json
+openpkg spec validate openpkg.json --version 1.0
+```
 
-# JSON (simplified structure)
-openpkg docs openpkg.json -f json
+### spec diagnostics
 
-# Split: one file per export
-openpkg docs openpkg.json --split -o docs/api/
+```bash
+openpkg spec diagnostics openpkg.json
+```
 
-# Pipeline: stdin
-openpkg snapshot src/index.ts -o - | openpkg docs - -f md
+### spec filter
 
-# With adapter (generates framework-specific output)
-openpkg docs openpkg.json --adapter fumadocs -o docs/api/
+```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'
 ```
 
-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) |
-| `-a, --adapter <name>` | Use adapter: `fumadocs`, `raw` (default: raw) |
-
-### diff
+| `--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) |
 
-Compare two specs for breaking changes.
+### spec diff
 
 ```bash
-openpkg diff old.json new.json
-openpkg diff old.json new.json --summary
+openpkg spec diff old.json new.json
+openpkg spec diff old.json new.json --summary
 ```
 
-Output includes:
-- `breaking` - categorized breaking changes
-- `added` - new exports
-- `removed` - removed exports
-- `changed` - modified exports
-- `docsOnly` - documentation-only changes
-- `summary.semverBump` - recommended version bump
+### spec breaking
 
-### breaking
-
-Check for breaking changes. Exit 1 if any found.
+Exit 1 if breaking changes found.
 
 ```bash
-openpkg breaking old.json new.json
+openpkg spec breaking old.json new.json
 ```
 
-Output:
-```json
-{
-  "breaking": [
-    { "id": "createClient", "name": "createClient", "kind": "function", "severity": "high", "reason": "signature changed" }
-  ],
-  "count": 1
-}
-```
+### spec semver
 
-### semver
+```bash
+openpkg spec semver old.json new.json
+```
 
-Recommend version bump based on changes.
+### spec changelog
 
 ```bash
-openpkg semver old.json new.json
+openpkg spec changelog old.json new.json
+openpkg spec changelog old.json new.json --format json
 ```
 
-Output:
-```json
-{
-  "bump": "major",
-  "reason": "1 breaking change detected"
-}
-```
+---
 
-### validate
+## Docs Commands
 
-Validate spec against schema.
+### docs init
+
+Initialize docs configuration.
 
 ```bash
-openpkg validate openpkg.json
-openpkg validate openpkg.json --version 1.0
+openpkg docs init
 ```
 
-Output:
-```json
-{
-  "valid": true,
-  "errors": []
-}
-```
+Creates `openpkg.config.json` with default settings.
 
-### changelog
+### docs generate
 
-Generate changelog from diff.
+Generate documentation from spec.
 
 ```bash
-openpkg changelog old.json new.json
-openpkg changelog old.json new.json --format json
-```
+# Markdown (default)
+openpkg docs generate openpkg.json -o api.md
 
-Markdown output:
-```markdown
-## Breaking Changes
-- **Removed** `oldFunction` (function)
+# React layout (single layout + spec JSON, add components via registry)
+openpkg docs generate openpkg.json -f react -o ./app/api
 
-## Added
-- `newFunction`
-```
+# HTML
+openpkg docs generate openpkg.json -f html -o api.html
 
-### diagnostics
+# JSON (simplified structure)
+openpkg docs generate openpkg.json -f json
 
-Analyze spec for quality issues.
+# Split: one file per export
+openpkg docs generate openpkg.json --split -o docs/api/
 
-```bash
-openpkg diagnostics openpkg.json
+# 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
 ```
 
-Output:
-```json
-{
-  "summary": {
-    "total": 5,
-    "missingDescriptions": 3,
-    "deprecatedNoReason": 1,
-    "missingParamDocs": 1
-  },
-  "diagnostics": { ... }
-}
+| 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
 ```
 
-### filter
+### docs list
 
-Filter spec by various criteria.
+List available registry components.
 
 ```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'
+openpkg docs list
 ```
 
-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) |
+16 components available: layouts, sections, primitives.
+
+### docs view
 
-All criteria use AND logic when combined.
+View component details and dependencies.
 
-Output (default):
-```json
-{
-  "spec": { ... },
-  "matched": 12,
-  "total": 45
-}
+```bash
+openpkg docs view function-section
 ```
 
+---
+
 ## Pipelines
 
 Commands are composable via stdin/stdout:
 
 ```bash
 # Extract and generate docs
-openpkg snapshot src/index.ts -o - | openpkg docs - -f md > api.md
+openpkg spec snapshot src/index.ts -o - | openpkg docs generate - -f md > api.md
 
 # Extract, verify, then diff
-openpkg snapshot src/index.ts --verify -o new.json
-openpkg diff baseline.json new.json --summary
+openpkg spec snapshot src/index.ts --verify -o new.json
+openpkg spec diff baseline.json new.json --summary
 ```
 
 ## Programmatic Use

package/dist/bin/openpkg.js

@@ -5,13 +5,11 @@ import {
 } from "../shared/chunk-1dqs11h6.js";
 
 // bin/openpkg.ts
-import * as path10 from "node:path";
-import { getExport, listExports } from "@openpkg-ts/sdk";
-import { Command as Command10 } from "commander";
+import { Command as Command12 } from "commander";
 // package.json
 var package_default = {
   name: "@openpkg-ts/cli",
-  version: "0.5.1",
+  version: "0.6.1",
   description: "CLI for OpenPkg TypeScript API extraction and documentation generation",
   homepage: "https://github.com/ryanwaits/openpkg-ts#readme",
   repository: {
@@ -34,14 +32,14 @@ var package_default = {
     test: "bun test"
   },
   dependencies: {
-    "@openpkg-ts/adapters": "^0.3.2",
-    "@openpkg-ts/sdk": "^0.33.1",
+    "@openpkg-ts/adapters": "^0.3.4",
+    "@openpkg-ts/sdk": "^0.34.1",
     commander: "^14.0.0"
   },
   devDependencies: {
     "@types/bun": "latest",
     "@types/node": "^20.0.0",
-    bunup: "latest"
+    bunup: "^0.16.20"
   },
   publishConfig: {
     access: "public"
@@ -253,78 +251,108 @@ function createChangelogCommand() {
   });
 }
 
-// src/commands/diagnostics.ts
+// src/commands/docs/index.ts
+import { Command as Command9 } from "commander";
+
+// src/commands/docs/add.ts
+import { spawn } from "node:child_process";
+import { Command as Command4 } from "commander";
+
+// src/commands/docs/utils.ts
 import * as fs4 from "node:fs";
 import * as path4 from "node:path";
-import { analyzeSpec } from "@openpkg-ts/sdk";
-import { Command as Command4 } from "commander";
-function loadJSON(filePath) {
-  const resolved = path4.resolve(filePath);
-  const content = fs4.readFileSync(resolved, "utf-8");
-  return JSON.parse(content);
-}
-function createDiagnosticsCommand() {
-  return new Command4("diagnostics").description("Analyze spec for quality issues (missing docs, deprecated without reason)").argument("<spec>", "Path to spec file (JSON)").option("--verbose", "Show detailed information including skipped export details").action(async (specPath, options) => {
+function detectPackageManager(cwd = process.cwd()) {
+  const pkgJsonPath = path4.join(cwd, "package.json");
+  if (fs4.existsSync(pkgJsonPath)) {
     try {
-      const spec = loadJSON(specPath);
-      const diagnostics = analyzeSpec(spec);
-      const generation = spec.generation;
-      const skipped = generation?.skipped ?? [];
-      const externalExports = spec.exports.filter((e) => e.kind === "external");
-      const byReason = {};
-      for (const skip of skipped) {
-        byReason[skip.reason] = (byReason[skip.reason] ?? 0) + 1;
+      const pkg = JSON.parse(fs4.readFileSync(pkgJsonPath, "utf-8"));
+      if (pkg.packageManager) {
+        if (pkg.packageManager.startsWith("bun"))
+          return "bun";
+        if (pkg.packageManager.startsWith("pnpm"))
+          return "pnpm";
+        if (pkg.packageManager.startsWith("yarn"))
+          return "yarn";
+        if (pkg.packageManager.startsWith("npm"))
+          return "npm";
       }
-      const result = {
-        summary: {
-          total: diagnostics.missingDescriptions.length + diagnostics.deprecatedNoReason.length + diagnostics.missingParamDocs.length,
-          missingDescriptions: diagnostics.missingDescriptions.length,
-          deprecatedNoReason: diagnostics.deprecatedNoReason.length,
-          missingParamDocs: diagnostics.missingParamDocs.length,
-          ...skipped.length > 0 && { skippedExports: skipped.length },
-          ...externalExports.length > 0 && { externalExports: externalExports.length }
-        },
-        diagnostics,
-        ...skipped.length > 0 && {
-          skippedExports: {
-            total: skipped.length,
-            byReason,
-            ...options.verbose && { details: skipped }
-          }
-        },
-        ...externalExports.length > 0 && {
-          externalExports: {
-            count: externalExports.length,
-            ...options.verbose && {
-              details: externalExports.map((e) => ({
-                name: e.name,
-                package: e.source?.package
-              }))
-            }
-          }
-        }
-      };
-      console.log(JSON.stringify(result, null, 2));
-      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);
+    } catch {}
+  }
+  if (fs4.existsSync(path4.join(cwd, "bun.lockb")) || fs4.existsSync(path4.join(cwd, "bun.lock"))) {
+    return "bun";
+  }
+  if (fs4.existsSync(path4.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fs4.existsSync(path4.join(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  return "npm";
+}
+function getDlxCommand(pkg, pm) {
+  const packageManager = pm || detectPackageManager();
+  switch (packageManager) {
+    case "bun":
+      return { cmd: "bunx", args: [pkg] };
+    case "pnpm":
+      return { cmd: "pnpm", args: ["dlx", pkg] };
+    case "yarn":
+      return { cmd: "yarn", args: ["dlx", pkg] };
+    default:
+      return { cmd: "npx", args: [pkg] };
+  }
+}
+function getShadcnCommand(subcommand, args = []) {
+  const dlx = getDlxCommand("shadcn@latest");
+  return {
+    cmd: dlx.cmd,
+    args: [...dlx.args, subcommand, ...args]
+  };
+}
+
+// src/commands/docs/add.ts
+function createAddCommand() {
+  return new Command4("add").description("Install @openpkg components (wrapper for shadcn add)").argument("<components...>", "Components to install").option("-o, --overwrite", "Overwrite existing files").option("-c, --cwd <path>", "Working directory").option("-y, --yes", "Skip confirmation prompt").option("-s, --silent", "Mute output").action(async (components, options) => {
+    const prefixedComponents = components.map((c) => c.startsWith("@") ? c : `@openpkg/${c}`);
+    const extraArgs = [];
+    if (options.overwrite)
+      extraArgs.push("--overwrite");
+    if (options.cwd)
+      extraArgs.push("--cwd", options.cwd);
+    if (options.yes)
+      extraArgs.push("--yes");
+    if (options.silent)
+      extraArgs.push("--silent");
+    const { cmd, args } = getShadcnCommand("add", [...prefixedComponents, ...extraArgs]);
+    if (!options.silent) {
+      console.log(`Running: ${cmd} ${args.join(" ")}`);
+      console.log("");
     }
+    const child = spawn(cmd, args, {
+      stdio: "inherit",
+      shell: true
+    });
+    child.on("close", (code) => {
+      process.exit(code || 0);
+    });
   });
 }
 
-// src/commands/docs.ts
+// src/commands/docs/generate.ts
 import * as fs5 from "node:fs";
 import * as path5 from "node:path";
-import { createDocs, loadSpec as loadSpec4 } from "@openpkg-ts/sdk";
+import { loadSpec as loadSpec4, query, toReact } from "@openpkg-ts/sdk";
 import { Command as Command5 } from "commander";
 async function readStdin() {
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(chunk);
+  try {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+  } catch (err) {
+    throw new Error(`stdin read failed: ${err instanceof Error ? err.message : String(err)}`);
   }
-  return Buffer.concat(chunks).toString("utf-8");
 }
 function getExtension(format) {
   switch (format) {
@@ -332,10 +360,32 @@ function getExtension(format) {
       return ".json";
     case "html":
       return ".html";
+    case "react":
+      return ".tsx";
     default:
       return ".md";
   }
 }
+function applyFilters(spec, options) {
+  let qb = query(spec);
+  if (options.kind) {
+    const kinds = options.kind.split(",").map((k) => k.trim());
+    qb = qb.byKind(...kinds);
+  }
+  if (options.tag) {
+    const tags = options.tag.split(",").map((t) => t.trim());
+    qb = qb.byTag(...tags);
+  }
+  if (options.search) {
+    qb = qb.search(options.search);
+  }
+  if (options.deprecated === true) {
+    qb = qb.deprecated(true);
+  } else if (options.deprecated === false) {
+    qb = qb.deprecated(false);
+  }
+  return qb.toSpec();
+}
 function renderExport(docs, exportId, format, collapseUnionThreshold) {
   const exp = docs.getExport(exportId);
   if (!exp)
@@ -364,8 +414,8 @@ function renderFull(docs, format, collapseUnionThreshold) {
       return docs.toMarkdown({ frontmatter: true, codeSignatures: true, collapseUnionThreshold });
   }
 }
-function createDocsCommand() {
-  return new Command5("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)").option("-e, --export <name>", "Generate docs for a single export by name").option("-a, --adapter <name>", "Use adapter for generation (default: raw)").option("--collapse-unions <n>", "Collapse unions with more than N members (default: no collapse)").action(async (specPath, options) => {
+function createGenerateCommand() {
+  return new Command5("generate").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, react (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)").option("--collapse-unions <n>", "Collapse unions with more than N members").option("-k, --kind <kinds>", "Filter by kind(s), comma-separated").option("-t, --tag <tags>", "Filter by tag(s), comma-separated").option("-s, --search <term>", "Search name and description").option("--deprecated", "Only include deprecated exports").option("--no-deprecated", "Exclude deprecated exports").option("--variant <variant>", "React layout variant: full (single page) or index (links)", "full").option("--components-path <path>", "React components import path", "@/components/api").action(async (specPath, options) => {
     const format = options.format || "md";
     try {
       if (options.adapter && options.adapter !== "raw") {
@@ -387,36 +437,56 @@ function createDocsCommand() {
           console.error(JSON.stringify({ error: "--adapter requires --output <directory>" }));
           process.exit(1);
         }
-        let spec;
+        let spec2;
         if (specPath === "-") {
           const input = await readStdin();
-          spec = JSON.parse(input);
+          spec2 = JSON.parse(input);
         } else {
           const specFile = path5.resolve(specPath);
           if (!fs5.existsSync(specFile)) {
             console.error(JSON.stringify({ error: `Spec file not found: ${specFile}` }));
             process.exit(1);
           }
-          spec = JSON.parse(fs5.readFileSync(specFile, "utf-8"));
+          spec2 = JSON.parse(fs5.readFileSync(specFile, "utf-8"));
         }
-        await adapter.generate(spec, path5.resolve(options.output));
+        spec2 = applyFilters(spec2, options);
+        await adapter.generate(spec2, path5.resolve(options.output));
         console.error(`Generated docs with ${options.adapter} adapter to ${options.output}`);
         return;
       }
-      let docs;
+      let spec;
       if (specPath === "-") {
         const input = await readStdin();
-        const spec = JSON.parse(input);
-        docs = loadSpec4(spec);
+        spec = JSON.parse(input);
       } else {
         const specFile = path5.resolve(specPath);
         if (!fs5.existsSync(specFile)) {
           console.error(JSON.stringify({ error: `Spec file not found: ${specFile}` }));
           process.exit(1);
         }
-        docs = createDocs(specFile);
+        spec = JSON.parse(fs5.readFileSync(specFile, "utf-8"));
       }
+      spec = applyFilters(spec, options);
+      const docs = loadSpec4(spec);
       const collapseUnionThreshold = options.collapseUnions ? parseInt(options.collapseUnions, 10) : undefined;
+      if (format === "react") {
+        if (!options.output) {
+          console.error(JSON.stringify({ error: "--format react requires --output <directory>" }));
+          process.exit(1);
+        }
+        const variant = options.variant === "index" ? "index" : "full";
+        await toReact(spec, {
+          outDir: path5.resolve(options.output),
+          variant,
+          componentsPath: options.componentsPath ?? "@/components/api"
+        });
+        console.error(`Generated React layout to ${options.output}`);
+        console.error(`  - page.tsx: Layout file`);
+        console.error(`  - openpkg.json: Spec data`);
+        console.error(`
+Next: Add components with 'openpkg docs add function-section'`);
+        return;
+      }
       if (options.export) {
         const exports = docs.getAllExports();
         const exp = exports.find((e) => e.name === options.export);
@@ -445,8 +515,14 @@ function createDocsCommand() {
         }
         const exports = docs.getAllExports();
         for (const exp of exports) {
-          const filename = `${exp.name}${getExtension(format)}`;
+          const filename = path5.basename(`${exp.name}${getExtension(format)}`);
           const filePath = path5.join(outDir, filename);
+          const resolvedPath = path5.resolve(filePath);
+          const resolvedOutDir = path5.resolve(outDir);
+          if (!resolvedPath.startsWith(resolvedOutDir + path5.sep)) {
+            console.error(JSON.stringify({ error: `Path traversal detected: ${exp.name}` }));
+            process.exit(1);
+          }
           const content = renderExport(docs, exp.id, format, collapseUnionThreshold);
           fs5.writeFileSync(filePath, content);
         }
@@ -469,108 +545,115 @@ function createDocsCommand() {
   });
 }
 
-// src/commands/filter.ts
+// src/commands/docs/init.ts
 import * as fs6 from "node:fs";
 import * as path6 from "node:path";
-import { filterSpec } from "@openpkg-ts/sdk";
 import { Command as Command6 } from "commander";
-var VALID_KINDS = [
-  "function",
-  "class",
-  "variable",
-  "interface",
-  "type",
-  "enum",
-  "module",
-  "namespace",
-  "reference",
-  "external"
-];
-function loadSpec5(filePath) {
-  const resolved = path6.resolve(filePath);
-  const content = fs6.readFileSync(resolved, "utf-8");
-  return JSON.parse(content);
-}
-function parseList(val) {
-  if (!val)
-    return;
-  return val.split(",").map((s) => s.trim()).filter(Boolean);
-}
-function validateKinds(kinds) {
-  const invalid = kinds.filter((k) => !VALID_KINDS.includes(k));
-  if (invalid.length > 0) {
-    throw new Error(`Invalid kind(s): ${invalid.join(", ")}. Valid kinds: ${VALID_KINDS.join(", ")}`);
-  }
-  return kinds;
+var COMPONENTS_JSON = "components.json";
+var REGISTRY_URL = "https://raw.githubusercontent.com/anthropics/openpkg-ts/main/registry/r/{name}.json";
+function loadComponentsJson() {
+  const configPath = path6.resolve(COMPONENTS_JSON);
+  if (!fs6.existsSync(configPath))
+    return null;
+  return JSON.parse(fs6.readFileSync(configPath, "utf-8"));
 }
-function createFilterCommand() {
-  return new Command6("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("--search-members", "Also search member names/descriptions").option("--search-docs", "Also search param/return descriptions and examples").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, options) => {
-    try {
-      const spec = loadSpec5(specPath);
-      const criteria = {};
-      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.searchMembers)
-        criteria.searchMembers = true;
-      if (options.searchDocs)
-        criteria.searchDocs = true;
-      if (options.module)
-        criteria.module = options.module;
-      const result = filterSpec(spec, criteria);
-      let output;
-      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) {
-        fs6.writeFileSync(path6.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));
+function createInitCommand() {
+  return new Command6("init").description("Add @openpkg registry to components.json for shadcn CLI").option("--registry <url>", "Custom registry URL", REGISTRY_URL).action(async (options) => {
+    const configPath = path6.resolve(COMPONENTS_JSON);
+    const registryUrl = options.registry || REGISTRY_URL;
+    if (!fs6.existsSync(configPath)) {
+      console.error(`${COMPONENTS_JSON} not found.`);
+      console.error('Run "npx shadcn@latest init" first to initialize shadcn.');
+      process.exit(1);
+    }
+    const config = loadComponentsJson();
+    if (!config) {
+      console.error(`Failed to parse ${COMPONENTS_JSON}`);
       process.exit(1);
     }
+    config.registries = config.registries || {};
+    config.registries["@openpkg"] = registryUrl;
+    fs6.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log(`Added @openpkg registry to ${COMPONENTS_JSON}`);
+    console.log("");
+    console.log("Usage:");
+    console.log("  npx shadcn@latest add @openpkg/function-section");
+    console.log("  npx shadcn@latest add @openpkg/export-card");
+    console.log("");
+    console.log("List components:");
+    console.log("  openpkg docs list");
+  });
+}
+
+// src/commands/docs/list.ts
+import { spawn as spawn2 } from "node:child_process";
+import { Command as Command7 } from "commander";
+function createListCommand() {
+  return new Command7("list").description("List @openpkg components (wrapper for shadcn list)").option("-q, --query <query>", "Search query").option("-l, --limit <number>", "Max items to display").option("-c, --cwd <cwd>", "Working directory").action(async (options) => {
+    const extraArgs = ["@openpkg"];
+    if (options.query)
+      extraArgs.push("-q", options.query);
+    if (options.limit)
+      extraArgs.push("-l", options.limit);
+    if (options.cwd)
+      extraArgs.push("-c", options.cwd);
+    const { cmd, args } = getShadcnCommand("list", extraArgs);
+    const child = spawn2(cmd, args, {
+      stdio: "inherit",
+      shell: true
+    });
+    child.on("close", (code) => {
+      process.exit(code || 0);
+    });
   });
 }
 
+// src/commands/docs/view.ts
+import { spawn as spawn3 } from "node:child_process";
+import { Command as Command8 } from "commander";
+function createViewCommand() {
+  return new Command8("view").description("View @openpkg component before installing (wrapper for shadcn view)").argument("<components...>", "Components to view").option("-c, --cwd <cwd>", "Working directory").action(async (components, options) => {
+    const prefixedComponents = components.map((c) => c.startsWith("@") ? c : `@openpkg/${c}`);
+    const extraArgs = [...prefixedComponents];
+    if (options.cwd)
+      extraArgs.push("-c", options.cwd);
+    const { cmd, args } = getShadcnCommand("view", extraArgs);
+    const child = spawn3(cmd, args, {
+      stdio: "inherit",
+      shell: true
+    });
+    child.on("close", (code) => {
+      process.exit(code || 0);
+    });
+  });
+}
+
+// src/commands/docs/index.ts
+function createDocsCommand() {
+  const docs = new Command9("docs").description("Documentation generation and component registry");
+  docs.addCommand(createGenerateCommand());
+  docs.addCommand(createInitCommand());
+  docs.addCommand(createListCommand());
+  docs.addCommand(createViewCommand());
+  docs.addCommand(createAddCommand());
+  return docs;
+}
+
 // src/commands/semver.ts
 import * as fs7 from "node:fs";
 import * as path7 from "node:path";
 import { diffSpec as diffSpec3, recommendSemverBump as recommendSemverBump2 } from "@openpkg-ts/spec";
-import { Command as Command7 } from "commander";
-function loadSpec6(filePath) {
+import { Command as Command10 } from "commander";
+function loadSpec5(filePath) {
   const resolved = path7.resolve(filePath);
   const content = fs7.readFileSync(resolved, "utf-8");
   return JSON.parse(content);
 }
 function createSemverCommand() {
-  return new Command7("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, newPath) => {
+  return new Command10("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, newPath) => {
     try {
-      const oldSpec = loadSpec6(oldPath);
-      const newSpec = loadSpec6(newPath);
+      const oldSpec = loadSpec5(oldPath);
+      const newSpec = loadSpec5(newPath);
       const diff = diffSpec3(oldSpec, newSpec);
       const recommendation = recommendSemverBump2(diff);
       const result = {
@@ -586,19 +669,64 @@ function createSemverCommand() {
   });
 }
 
-// src/commands/snapshot.ts
+// src/commands/spec.ts
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
 import {
+  analyzeSpec,
   extractSpec,
+  filterSpec,
+  getExport,
+  listExports,
   loadConfig,
   mergeConfig
 } from "@openpkg-ts/sdk";
-import { Command as Command8 } from "commander";
-function parseFilter(value) {
-  if (!value)
+import { getValidationErrors } from "@openpkg-ts/spec";
+import { Command as Command11 } from "commander";
+var VALID_KINDS = [
+  "function",
+  "class",
+  "variable",
+  "interface",
+  "type",
+  "enum",
+  "module",
+  "namespace",
+  "reference",
+  "external"
+];
+function loadSpec6(filePath) {
+  const resolved = path8.resolve(filePath);
+  let content;
+  let spec;
+  try {
+    content = fs8.readFileSync(resolved, "utf-8");
+  } catch (err) {
+    throw new Error(`Failed to read spec file: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  try {
+    spec = JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Invalid JSON in spec file: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const errors = getValidationErrors(spec);
+  if (errors.length > 0) {
+    const details = errors.slice(0, 5).map((e) => `${e.instancePath || "/"}: ${e.message}`).join("; ");
+    throw new Error(`Invalid OpenPkg spec: ${details}`);
+  }
+  return spec;
+}
+function parseList(val) {
+  if (!val)
     return;
-  return value.split(",").map((s) => s.trim()).filter(Boolean);
+  return val.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function validateKinds(kinds) {
+  const invalid = kinds.filter((k) => !VALID_KINDS.includes(k));
+  if (invalid.length > 0) {
+    throw new Error(`Invalid kind(s): ${invalid.join(", ")}. Valid kinds: ${VALID_KINDS.join(", ")}`);
+  }
+  return kinds;
 }
 function formatDiagnostics(diagnostics) {
   return diagnostics.map((d) => ({
@@ -609,11 +737,8 @@ function formatDiagnostics(diagnostics) {
     ...d.location && { location: d.location }
   }));
 }
-function createSnapshotCommand() {
-  return new Command8("snapshot").description(`Generate full OpenPkg spec from TypeScript entry point
-
-` + `Config: Reads from openpkg.config.json or package.json "openpkg" field.
-` + "CLI flags override config file settings.").argument("<entry>", "Entry point file path").option("-o, --output <file>", "Output file (default: openpkg.json, use - for stdout)", "openpkg.json").option("--max-depth <n>", "Max type depth (default: 4)", "4").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").option("--only <exports>", "Filter exports (comma-separated, wildcards supported)").option("--ignore <exports>", "Ignore exports (comma-separated, wildcards supported)").option("--verify", "Exit 1 if any exports fail").option("--verbose", "Show detailed output including skipped exports").option("--include-private", "Include private/protected class members").option("--external-include <patterns...>", "Resolve re-exports from these packages (globs supported)").option("--external-exclude <patterns...>", "Never resolve from these packages").option("--external-depth <n>", "Max transitive depth for external resolution (default: 1)", "1").action(async (entry, options) => {
+function createSnapshotSubcommand() {
+  return new Command11("snapshot").description("Generate full OpenPkg spec from TypeScript entry point").argument("<entry>", "Entry point file path").option("-o, --output <file>", "Output file (default: openpkg.json)", "openpkg.json").option("--max-depth <n>", "Max type depth (default: 4)", "4").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").option("--only <exports>", "Filter exports (comma-separated)").option("--ignore <exports>", "Ignore exports (comma-separated)").option("--verify", "Exit 1 if any exports fail").option("--verbose", "Show detailed output").option("--include-private", "Include private/protected class members").option("--external-include <patterns...>", "Resolve re-exports from these packages").option("--external-exclude <patterns...>", "Never resolve from these packages").option("--external-depth <n>", "Max transitive depth for external resolution", "1").action(async (entry, options) => {
     const entryFile = path8.resolve(entry);
     const entryDir = path8.dirname(entryFile);
     const fileConfig = loadConfig(entryDir);
@@ -630,8 +755,8 @@ function createSnapshotCommand() {
       maxTypeDepth: parseInt(options.maxDepth ?? "4", 10),
       resolveExternalTypes: !options.skipResolve,
       schemaExtraction: options.runtime ? "hybrid" : "static",
-      only: parseFilter(options.only),
-      ignore: parseFilter(options.ignore),
+      only: parseList(options.only),
+      ignore: parseList(options.ignore),
       includePrivate: options.includePrivate,
       ...mergedConfig.externals && { externals: mergedConfig.externals }
     };
@@ -653,58 +778,15 @@ function createSnapshotCommand() {
             }
           }
         },
-        ...externalExports.length > 0 && {
-          external: {
-            count: externalExports.length,
-            ...options.verbose && {
-              exports: externalExports.map((e) => ({
-                name: e.name,
-                package: e.source?.package
-              }))
-            }
-          }
-        },
-        ...result.runtimeSchemas && {
-          runtime: {
-            extracted: result.runtimeSchemas.extracted,
-            merged: result.runtimeSchemas.merged,
-            vendors: result.runtimeSchemas.vendors
-          }
-        }
+        ...externalExports.length > 0 && { external: { count: externalExports.length } }
       };
       console.error(JSON.stringify(summary, null, 2));
-      if (externalExports.length > 0 || (result.verification?.skipped ?? 0) > 0) {
-        console.error("");
-        if (externalExports.length > 0) {
-          if (options.verbose) {
-            console.error(`⚠ ${externalExports.length} external re-export(s) (install dependencies for full type info):`);
-            for (const exp of externalExports) {
-              console.error(`  - ${exp.name} from "${exp.source?.package}"`);
-            }
-          } else {
-            console.error(`⚠ ${externalExports.length} external re-export(s) (install dependencies for full type info)`);
-          }
-        }
-        const skipped = result.verification?.details.skipped ?? [];
-        if (skipped.length > 0) {
-          if (options.verbose) {
-            console.error(`⚠ ${skipped.length} export(s) skipped:`);
-            for (const skip of skipped) {
-              const pkgInfo = skip.package ? ` from "${skip.package}"` : "";
-              console.error(`  - ${skip.name} (${skip.reason})${pkgInfo}`);
-            }
-          } else {
-            console.error(`⚠ ${skipped.length} export(s) skipped (use --verbose for details)`);
-          }
-        }
-      }
       if (options.verify && result.verification && result.verification.failed > 0) {
-        const errorOutput = {
+        console.error(JSON.stringify({
           error: "Export verification failed",
           failed: result.verification.details.failed,
           diagnostics: formatDiagnostics(result.diagnostics)
-        };
-        console.error(JSON.stringify(errorOutput, null, 2));
+        }, null, 2));
         process.exit(1);
       }
       const specJson = JSON.stringify(result.spec, null, 2);
@@ -717,40 +799,118 @@ function createSnapshotCommand() {
       }
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
-      const errorOutput = {
-        error: error.message,
-        ...error.stack && { stack: error.stack }
-      };
-      console.error(JSON.stringify(errorOutput, null, 2));
+      console.error(JSON.stringify({ error: error.message }, null, 2));
       process.exit(1);
     }
   });
 }
-
-// src/commands/validate.ts
-import * as fs9 from "node:fs";
-import * as path9 from "node:path";
-import { getValidationErrors } from "@openpkg-ts/spec";
-import { Command as Command9 } from "commander";
-function loadJSON2(filePath) {
-  const resolved = path9.resolve(filePath);
-  const content = fs9.readFileSync(resolved, "utf-8");
-  return JSON.parse(content);
-}
-function createValidateCommand() {
-  return new Command9("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, options) => {
+function createValidateSubcommand() {
+  return new Command11("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, options) => {
     try {
-      const spec = loadJSON2(specPath);
+      const spec = loadSpec6(specPath);
       const version = options.version ?? "latest";
       const errors = getValidationErrors(spec, version);
+      console.log(JSON.stringify({ valid: errors.length === 0, errors }, 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);
+    }
+  });
+}
+function createFilterSubcommand() {
+  return new Command11("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").option("--search-members", "Also search member names/descriptions").option("--search-docs", "Also search param/return descriptions").option("--module <path>", "Filter by source file path").option("-o, --output <file>", "Output file (default: stdout)").option("--summary", "Only output matched/total counts").option("--quiet", "Output raw spec only").action(async (specPath, options) => {
+    try {
+      const spec = loadSpec6(specPath);
+      const criteria = {};
+      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.searchMembers)
+        criteria.searchMembers = true;
+      if (options.searchDocs)
+        criteria.searchDocs = true;
+      if (options.module)
+        criteria.module = options.module;
+      const result = filterSpec(spec, criteria);
+      let output;
+      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) {
+        fs8.writeFileSync(path8.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);
+    }
+  });
+}
+function createLintSubcommand() {
+  return new Command11("lint").description("Analyze spec for quality issues (missing docs, deprecated without reason)").argument("<spec>", "Path to spec file (JSON)").option("--verbose", "Show detailed information").action(async (specPath, options) => {
+    try {
+      const spec = loadSpec6(specPath);
+      const diagnostics = analyzeSpec(spec);
+      const generation = spec.generation;
+      const skipped = generation?.skipped ?? [];
+      const externalExports = spec.exports.filter((e) => e.kind === "external");
+      const byReason = {};
+      for (const skip of skipped) {
+        byReason[skip.reason] = (byReason[skip.reason] ?? 0) + 1;
+      }
       const result = {
-        valid: errors.length === 0,
-        errors
+        summary: {
+          total: diagnostics.missingDescriptions.length + diagnostics.deprecatedNoReason.length + diagnostics.missingParamDocs.length,
+          missingDescriptions: diagnostics.missingDescriptions.length,
+          deprecatedNoReason: diagnostics.deprecatedNoReason.length,
+          missingParamDocs: diagnostics.missingParamDocs.length,
+          ...skipped.length > 0 && { skippedExports: skipped.length },
+          ...externalExports.length > 0 && { externalExports: externalExports.length }
+        },
+        diagnostics,
+        ...skipped.length > 0 && {
+          skippedExports: {
+            total: skipped.length,
+            byReason,
+            ...options.verbose && { details: skipped }
+          }
+        },
+        ...externalExports.length > 0 && {
+          externalExports: {
+            count: externalExports.length,
+            ...options.verbose && {
+              details: externalExports.map((e) => ({ name: e.name, package: e.source?.package }))
+            }
+          }
+        }
       };
       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));
@@ -758,40 +918,74 @@ function createValidateCommand() {
     }
   });
 }
+function createListSubcommand() {
+  return new Command11("list").description("List exports from a TypeScript entry point").argument("<entry>", "Entry point file path").action(async (entry) => {
+    const entryFile = path8.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));
+  });
+}
+function createGetSubcommand() {
+  return new Command11("get").description("Get detailed spec for a single export").argument("<entry>", "Entry point file path").argument("<name>", "Export name").action(async (entry, name) => {
+    const entryFile = path8.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);
+    }
+    const output = { export: result.export };
+    if (result.types.length > 0) {
+      output.types = result.types;
+    }
+    console.log(JSON.stringify(output, null, 2));
+  });
+}
+function createSpecCommand() {
+  const spec = new Command11("spec").description("Spec extraction and manipulation commands");
+  spec.addCommand(createSnapshotSubcommand());
+  spec.addCommand(createValidateSubcommand());
+  spec.addCommand(createFilterSubcommand());
+  spec.addCommand(createLintSubcommand());
+  spec.addCommand(createListSubcommand());
+  spec.addCommand(createGetSubcommand());
+  return spec;
+}
 
 // bin/openpkg.ts
-var program = new Command10;
+var program = new Command12;
 program.name("openpkg").description("OpenPkg CLI - TypeScript API extraction primitives").version(package_default.version);
-program.command("list").description("List exports from a TypeScript entry point").argument("<entry>", "Entry point file path").action(async (entry) => {
-  const entryFile = path10.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, name) => {
-  const entryFile = path10.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);
-  }
-  const output = { 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(createSpecCommand());
 program.addCommand(createDocsCommand());
+program.addCommand(createDiffCommand());
 program.addCommand(createBreakingCommand());
 program.addCommand(createChangelogCommand());
 program.addCommand(createSemverCommand());
-program.addCommand(createValidateCommand());
-program.addCommand(createDiagnosticsCommand());
-program.addCommand(createFilterCommand());
+var specCmd = program.commands.find((c) => c.name() === "spec");
+if (!specCmd) {
+  throw new Error("Internal error: spec command not found");
+}
+function getSubcommand(parent, name) {
+  const cmd = parent.commands.find((c) => c.name() === name);
+  if (!cmd) {
+    throw new Error(`Internal error: ${name} subcommand not found`);
+  }
+  return cmd;
+}
+function createAlias(aliasName, targetName, description) {
+  return new Command12(aliasName).description(description).allowUnknownOption().allowExcessArguments().action(async () => {
+    const args = process.argv.slice(3);
+    await getSubcommand(specCmd, targetName).parseAsync(args, { from: "user" });
+  });
+}
+program.addCommand(createAlias("snapshot", "snapshot", "(alias) → openpkg spec snapshot"));
+program.addCommand(createAlias("list", "list", "(alias) → openpkg spec list"));
+program.addCommand(createAlias("get", "get", "(alias) → openpkg spec get"));
+program.addCommand(createAlias("validate", "validate", "(alias) → openpkg spec validate"));
+program.addCommand(createAlias("filter", "filter", "(alias) → openpkg spec filter"));
+program.addCommand(createAlias("diagnostics", "lint", "(alias) → openpkg spec lint"));
 program.parse();

package/dist/src/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "CLI for OpenPkg TypeScript API extraction and documentation generation",
   "homepage": "https://github.com/ryanwaits/openpkg-ts#readme",
   "repository": {
@@ -23,14 +23,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/adapters": "^0.3.2",
-    "@openpkg-ts/sdk": "^0.33.1",
+    "@openpkg-ts/adapters": "^0.3.4",
+    "@openpkg-ts/sdk": "^0.34.1",
     "commander": "^14.0.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "^20.0.0",
-    "bunup": "latest"
+    "bunup": "^0.16.20"
   },
   "publishConfig": {
     "access": "public"