@openpkg-ts/cli 0.11.3 → 0.12.0

package/README.md

@@ -5,9 +5,15 @@ Extract [OpenPkg](https://openpkg.dev) documents and generate docs from the comm
 ## Usage
 
 ```bash
-# Extract an OpenPkg spec
+# Extract from an entry file
 bunx @openpkg-ts/cli spec src/index.ts -o openpkg.json
 
+# Or resolve the package/entry from a dir, cwd, intent, or git URL
+bunx @openpkg-ts/cli spec
+bunx @openpkg-ts/cli spec .
+bunx @openpkg-ts/cli spec . sdk
+bunx @openpkg-ts/cli spec https://github.com/org/repo
+
 # 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
@@ -19,16 +25,31 @@ bunx @openpkg-ts/cli list src/index.ts
 bunx @openpkg-ts/cli diff old.json new.json
 ```
 
+Prefers TypeScript source (`src/index.ts`) over `dist/*.d.ts`. Several packages and no intent → prompt (or a list if not a TTY).
+
+Opt-in Jev routing (needs `AI_GATEWAY_API_KEY` and the `ai` package). Sends package.json + file heads to Vercel AI Gateway with zero data retention:
+
+```bash
+bunx @openpkg-ts/cli spec . --jev
+bunx @openpkg-ts/cli spec . --jev --follow-external auto
+```
+
+`followExternal: "auto"` (config or flag) requires `--jev`. Config: `openpkg.config.json` or `package.json#openpkg`.
+
+```json
+{ "followExternal": "auto", "decisions": "jev" }
+```
+
 ## Commands
 
 | 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`) |
+| `spec [path \| entry.ts] [intent...]` | Extract a spec from a file, package dir, cwd, or git URL |
+| `docs [path \| entry.ts \| spec.json] [intent...]` | Generate docs (`-f md\|html\|json`) |
+| `list [path \| entry.ts] [intent...]` | List exports with kind and location (`--json`) |
 | `diff <old.json> <new.json>` | Compare specs; exits 2 if breaking changes |
 
-`-o, --output` writes to a file instead of stdout.
+`-o, --output` writes to a file instead of stdout. `--jev` routes package/entry with Jev. `--follow-external auto` expands load-bearing externals (requires `--jev`).
 
 For programmatic use, richer options, and framework integrations (search indexes, nav trees), use `@openpkg-ts/sdk` directly.
 

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/index.ts
 import fs from "node:fs";
 import path from "node:path";
+import readline from "node:readline/promises";
 import { parseArgs } from "node:util";
 import {
   calculateNextVersion,
@@ -12,23 +13,26 @@ import {
   extractSpec,
   getAvailableVersions,
   getValidationErrors,
+  isRemoteInput,
   listExports,
   loadConfig,
   mergeConfig,
-  recommendSemverBump
+  pickEntry,
+  recommendSemverBump,
+  resolveTarget
 } from "@openpkg-ts/sdk";
 var HELP = `openpkg - extract TypeScript API specs and generate docs
 
 Usage:
-  openpkg spec <entry.ts> [-o spec.json] [--follow-external <pkg,...>]
-  openpkg docs <entry.ts | spec.json> [-f md|html|json] [-o out]
-  openpkg list <entry.ts> [--json]
+  openpkg spec [path | entry.ts] [intent...] [-o spec.json] [--follow-external <pkg,...>]
+  openpkg docs [path | entry.ts | spec.json] [intent...] [-f md|html|json] [-o out]
+  openpkg list [path | entry.ts] [intent...] [--json]
   openpkg validate <spec.json>
   openpkg diff <old.json> <new.json> [--json]
 
 Commands:
-  spec      Extract an OpenPkg spec from a TypeScript entry point
-  docs      Generate docs from an entry point or an existing spec file
+  spec      Extract an OpenPkg spec (dir, cwd, or entry file)
+  docs      Generate docs from a package, entry point, or spec file
   list      List exports (name, kind, location)
   validate  Validate a spec file against the OpenPkg meta-schema
   diff      Compare two spec files and recommend a semver bump
@@ -38,16 +42,19 @@ Options:
   -f, --format            docs output format: md (default), html, json
       --json              list/diff output as JSON
       --follow-external   Expand types from these packages (comma-separated,
-                          globs ok: "@ai-sdk/*"). Default: stub externals.
+                          globs ok: "@ai-sdk/*", or "auto" with --jev).
+                          Default: stub externals.
       --follow-external-all   Expand every external package (use with care)
       --only              Only extract these exports (comma-separated, * ok)
       --ignore            Ignore these exports (comma-separated, * ok)
+      --jev               Route package/entry with Jev (needs AI_GATEWAY_API_KEY)
   -h, --help              Show this help
   -v, --version           Show version
 
 Config: reads openpkg.config.json (or package.json "openpkg" field) from the
-cwd. Flags override the file. Example openpkg.config.json:
-  { "followExternal": ["@acme/payment-kit", "@ai-sdk/*"] }
+cwd. Flags override the file. Example:
+  { "followExternal": ["@ai-sdk/*"] }
+  { "followExternal": "auto", "decisions": "jev" }
 `;
 function fail(message) {
   console.error(`error: ${message}`);
@@ -76,12 +83,111 @@ function reportDiagnostics(diagnostics) {
     process.exit(1);
   }
 }
+function parseTargetArgs(positionals, cwd) {
+  if (!positionals.length)
+    return { input: cwd };
+  const first = positionals[0];
+  const rest = positionals.slice(1).join(" ").trim();
+  const abs = path.resolve(cwd, first);
+  if (isRemoteInput(first)) {
+    return { input: first, ...rest ? { intent: rest } : {} };
+  }
+  if (fs.existsSync(abs)) {
+    return { input: abs, ...rest ? { intent: rest } : {} };
+  }
+  return { input: cwd, intent: positionals.join(" ") };
+}
+function formatPackages(candidates, cwd) {
+  return candidates.map((c, i) => {
+    const rel = path.relative(cwd, c.dir) || ".";
+    return `  ${i + 1}. ${c.name}  ${rel}`;
+  }).join(`
+`);
+}
+async function choosePackage(candidates, cwd) {
+  const body = `multiple packages — pick one:
+${formatPackages(candidates, cwd)}`;
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    const hint = candidates[0]?.name.split("/").pop() ?? "sdk";
+    fail(`${body}
+re-run with a path or intent, e.g. openpkg spec . ${hint}`);
+  }
+  console.error(body);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await rl.question(`Package [1-${candidates.length}]: `);
+    const i = Number(answer.trim());
+    if (!Number.isInteger(i) || i < 1 || i > candidates.length)
+      fail("invalid selection");
+    return candidates[i - 1];
+  } finally {
+    rl.close();
+  }
+}
+function loadCwdEnv() {
+  for (const name of [".env.local", ".env"]) {
+    const file = path.join(process.cwd(), name);
+    if (!fs.existsSync(file))
+      continue;
+    for (const line of fs.readFileSync(file, "utf8").split(`
+`)) {
+      const t = line.trim();
+      if (!t || t.startsWith("#"))
+        continue;
+      const i = t.indexOf("=");
+      if (i === -1)
+        continue;
+      const k = t.slice(0, i).trim();
+      const v = t.slice(i + 1).trim();
+      if (k && process.env[k] === undefined)
+        process.env[k] = v;
+    }
+  }
+}
+async function resolveCliTarget(positionals, decisions) {
+  loadCwdEnv();
+  const cwd = process.cwd();
+  const { input, intent } = parseTargetArgs(positionals, cwd);
+  const resolved = await resolveTarget({ input, intent, cwd, decisions });
+  if (resolved.kind === "unavailable")
+    fail(resolved.reason);
+  if (resolved.kind === "remote")
+    fail("failed to clone remote repo");
+  if (resolved.kind === "empty")
+    fail(resolved.reason);
+  if (resolved.kind === "needs-build") {
+    console.error(`error: ${resolved.reason}`);
+    if (resolved.command)
+      console.error(`  → ${resolved.command}`);
+    process.exit(2);
+  }
+  if (resolved.kind === "explicit") {
+    return { entryFile: resolved.entryFile, entryPointSource: resolved.entryPointSource };
+  }
+  if (resolved.kind === "ok") {
+    return { entryFile: resolved.entryFile, entryPointSource: resolved.entryPointSource };
+  }
+  const chosen = await choosePackage(resolved.candidates, cwd);
+  const picked = pickEntry(chosen.dir);
+  if (!picked)
+    fail(`no TypeScript entry found in ${chosen.name}`);
+  return picked;
+}
 function toList(value) {
   if (!value)
     return;
   const items = value.split(",").map((s) => s.trim()).filter(Boolean);
   return items.length > 0 ? items : undefined;
 }
+function parseFollowExternal(value, all) {
+  if (all)
+    return true;
+  if (!value)
+    return;
+  if (value.trim() === "auto")
+    return "auto";
+  return toList(value);
+}
 function reportStubbedExternals(spec) {
   const counts = new Map;
   for (const t of spec.types ?? []) {
@@ -105,26 +211,31 @@ async function specCommand(args) {
       "follow-external": { type: "string" },
       "follow-external-all": { type: "boolean" },
       only: { type: "string" },
-      ignore: { type: "string" }
+      ignore: { type: "string" },
+      jev: { type: "boolean" }
     },
     allowPositionals: true
   });
-  const entryFile = positionals[0];
-  if (!entryFile)
-    fail("spec requires an entry file (openpkg spec src/index.ts)");
   const fileConfig = loadConfig(process.cwd());
   const cliConfig = {
-    followExternal: values["follow-external-all"] ? true : toList(values["follow-external"]),
+    followExternal: parseFollowExternal(values["follow-external"], values["follow-external-all"]),
     only: toList(values.only),
-    ignore: toList(values.ignore)
+    ignore: toList(values.ignore),
+    ...values.jev ? { decisions: "jev" } : {}
   };
+  const { entryFile, entryPointSource } = await resolveCliTarget(positionals, cliConfig.decisions ?? fileConfig?.decisions);
   const config = mergeConfig(fileConfig, cliConfig);
+  if (config.followExternal === "auto" && config.decisions !== "jev") {
+    fail("followExternal auto requires --jev");
+  }
   const { spec, diagnostics } = await extractSpec({
     entryFile,
+    entryPointSource,
     followExternal: config.followExternal,
     only: config.only,
     ignore: config.ignore,
-    externals: config.externals
+    externals: config.externals,
+    decisions: config.decisions
   });
   reportDiagnostics(diagnostics);
   if (!config.followExternal)
@@ -136,21 +247,21 @@ async function docsCommand(args) {
     args,
     options: {
       output: { type: "string", short: "o" },
-      format: { type: "string", short: "f" }
+      format: { type: "string", short: "f" },
+      jev: { type: "boolean" }
     },
     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);
+  if (positionals[0]?.endsWith(".json")) {
+    docs = createDocs(positionals[0]);
   } else {
-    const { spec, diagnostics } = await extractSpec({ entryFile: input });
+    const decisions = values.jev ? "jev" : loadConfig(process.cwd())?.decisions;
+    const { entryFile, entryPointSource } = await resolveCliTarget(positionals, decisions);
+    const { spec, diagnostics } = await extractSpec({ entryFile, entryPointSource });
     reportDiagnostics(diagnostics);
     docs = createDocs(spec);
   }
@@ -160,12 +271,11 @@ async function docsCommand(args) {
 async function listCommand(args) {
   const { values, positionals } = parseArgs({
     args,
-    options: { json: { type: "boolean" } },
+    options: { json: { type: "boolean" }, jev: { type: "boolean" } },
     allowPositionals: true
   });
-  const entryFile = positionals[0];
-  if (!entryFile)
-    fail("list requires an entry file (openpkg list src/index.ts)");
+  const decisions = values.jev ? "jev" : loadConfig(process.cwd())?.decisions;
+  const { entryFile } = await resolveCliTarget(positionals, decisions);
   const { exports, errors } = await listExports({ entryFile });
   for (const err of errors) {
     console.error(`error: ${err}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "CLI for OpenPkg - extract TypeScript API specs and generate docs",
   "keywords": [
     "openpkg",
@@ -31,11 +31,11 @@
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
-    "typecheck": "tsc --noEmit -p .",
+    "typecheck": "tsc --noEmit --types bun -p .",
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/sdk": "^0.51.0"
+    "@openpkg-ts/sdk": "^0.52.0"
   },
   "devDependencies": {
     "@types/bun": "latest",