@openpkg-ts/cli 0.11.3 → 0.12.1

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

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import fs from "node:fs";
-import path from "node:path";
+import fs2 from "node:fs";
+import path2 from "node:path";
+import readline from "node:readline/promises";
 import { parseArgs } from "node:util";
 import {
   calculateNextVersion,
@@ -12,23 +13,99 @@ import {
   extractSpec,
   getAvailableVersions,
   getValidationErrors,
+  isPathLikeInput,
+  isRemoteInput,
   listExports,
   loadConfig,
   mergeConfig,
-  recommendSemverBump
+  pickEntry,
+  recommendSemverBump,
+  resolveTarget
 } from "@openpkg-ts/sdk";
+
+// src/env.ts
+import fs from "node:fs";
+import path from "node:path";
+function parseEnvText(content) {
+  const out = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    if (line.startsWith("export "))
+      line = line.slice(7).trimStart();
+    const eq = line.indexOf("=");
+    if (eq <= 0)
+      continue;
+    const key = line.slice(0, eq).trim();
+    if (!key || /\s/.test(key))
+      continue;
+    let value = line.slice(eq + 1);
+    if (value.startsWith(" ") || value.startsWith("\t"))
+      value = value.trimStart();
+    if (value.startsWith('"')) {
+      let i = 1;
+      let parsed = "";
+      while (i < value.length) {
+        const ch = value[i];
+        if (ch === "\\" && i + 1 < value.length) {
+          const next = value[i + 1];
+          parsed += next === "n" ? `
+` : next === "r" ? "\r" : next === "t" ? "\t" : next;
+          i += 2;
+          continue;
+        }
+        if (ch === '"')
+          break;
+        parsed += ch;
+        i++;
+      }
+      out[key] = parsed;
+      continue;
+    }
+    if (value.startsWith("'")) {
+      const end = value.indexOf("'", 1);
+      out[key] = end === -1 ? value.slice(1) : value.slice(1, end);
+      continue;
+    }
+    const hash = value.search(/\s+#/);
+    out[key] = (hash === -1 ? value : value.slice(0, hash)).trim();
+  }
+  return out;
+}
+function parseIfExists(file) {
+  try {
+    if (!fs.existsSync(file))
+      return {};
+    return parseEnvText(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function loadCwdEnv(cwd = process.cwd()) {
+  const parsed = {
+    ...parseIfExists(path.join(cwd, ".env")),
+    ...parseIfExists(path.join(cwd, ".env.local"))
+  };
+  for (const [k, v] of Object.entries(parsed)) {
+    if (process.env[k] === undefined)
+      process.env[k] = v;
+  }
+}
+
+// src/index.ts
 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,32 +115,45 @@ 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}`);
-  process.exit(1);
+
+class CliError extends Error {
+  exitCode;
+  printed;
+  constructor(message, exitCode = 1, printed = false) {
+    super(message);
+    this.exitCode = exitCode;
+    this.printed = printed;
+    this.name = "CliError";
+  }
+}
+function fail(message, exitCode = 1) {
+  throw new CliError(message, exitCode);
 }
 function write(content, output) {
   if (output) {
-    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
-    fs.writeFileSync(output, content);
+    fs2.mkdirSync(path2.dirname(path2.resolve(output)), { recursive: true });
+    fs2.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"));
+  const pkg = JSON.parse(fs2.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
   return pkg.version;
 }
 function reportDiagnostics(diagnostics) {
@@ -73,7 +163,87 @@ function reportDiagnostics(diagnostics) {
     }
   }
   if (diagnostics.some((d) => d.severity === "error")) {
-    process.exit(1);
+    throw new CliError("", 1, true);
+  }
+}
+function parseTargetArgs(positionals, cwd) {
+  if (!positionals.length)
+    return { input: cwd };
+  const first = positionals[0];
+  const rest = positionals.slice(1).join(" ").trim();
+  if (isRemoteInput(first)) {
+    return { input: first, ...rest ? { intent: rest } : {} };
+  }
+  const abs = path2.resolve(cwd, first);
+  if (fs2.existsSync(abs) || isPathLikeInput(first)) {
+    return { input: abs, ...rest ? { intent: rest } : {} };
+  }
+  return { input: cwd, intent: positionals.join(" ") };
+}
+function formatPackages(candidates, cwd) {
+  return candidates.map((c, i) => {
+    const rel = path2.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();
+  }
+}
+async function resolveCliTarget(positionals, decisions) {
+  loadCwdEnv();
+  const cwd = process.cwd();
+  const { input, intent } = parseTargetArgs(positionals, cwd);
+  const resolved = await resolveTarget({ input, intent, cwd, decisions });
+  const cleanup = resolved.cleanup;
+  try {
+    if (resolved.kind === "unavailable")
+      fail(resolved.reason);
+    if (resolved.kind === "empty")
+      fail(resolved.reason);
+    if (resolved.kind === "needs-build") {
+      fail(resolved.command ? `${resolved.reason}
+  → ${resolved.command}` : resolved.reason, 2);
+    }
+    if (resolved.kind === "explicit") {
+      return {
+        entryFile: resolved.entryFile,
+        entryPointSource: resolved.entryPointSource,
+        cleanup
+      };
+    }
+    if (resolved.kind === "ok") {
+      return {
+        entryFile: resolved.entryFile,
+        entryPointSource: resolved.entryPointSource,
+        cleanup
+      };
+    }
+    const chosen = await choosePackage(resolved.candidates, cwd);
+    const picked = pickEntry(chosen.dir);
+    if (!picked)
+      fail(`no TypeScript entry found in ${chosen.name}`);
+    return { ...picked, cleanup };
+  } catch (err) {
+    cleanup?.();
+    throw err;
   }
 }
 function toList(value) {
@@ -82,6 +252,15 @@ function toList(value) {
   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,86 +284,112 @@ 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 config = mergeConfig(fileConfig, cliConfig);
-  const { spec, diagnostics } = await extractSpec({
-    entryFile,
-    followExternal: config.followExternal,
-    only: config.only,
-    ignore: config.ignore,
-    externals: config.externals
-  });
-  reportDiagnostics(diagnostics);
-  if (!config.followExternal)
-    reportStubbedExternals(spec);
-  write(JSON.stringify(spec, null, 2), values.output);
+  let cleanup;
+  try {
+    const resolved = await resolveCliTarget(positionals, cliConfig.decisions ?? fileConfig?.decisions);
+    cleanup = resolved.cleanup;
+    const { entryFile, entryPointSource } = resolved;
+    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,
+      decisions: config.decisions
+    });
+    reportDiagnostics(diagnostics);
+    if (!config.followExternal)
+      reportStubbedExternals(spec);
+    write(JSON.stringify(spec, null, 2), values.output);
+  } finally {
+    cleanup?.();
+  }
 }
 async function docsCommand(args) {
   const { values, positionals } = parseArgs({
     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);
-  } else {
-    const { spec, diagnostics } = await extractSpec({ entryFile: input });
-    reportDiagnostics(diagnostics);
-    docs = createDocs(spec);
+  let cleanup;
+  try {
+    if (positionals[0]?.endsWith(".json")) {
+      docs = createDocs(positionals[0]);
+    } else {
+      const decisions = values.jev ? "jev" : loadConfig(process.cwd())?.decisions;
+      const resolved = await resolveCliTarget(positionals, decisions);
+      cleanup = resolved.cleanup;
+      const { spec, diagnostics } = await extractSpec({
+        entryFile: resolved.entryFile,
+        entryPointSource: resolved.entryPointSource
+      });
+      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);
+  } finally {
+    cleanup?.();
   }
-  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" } },
+    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 { exports, errors } = await listExports({ entryFile });
-  for (const err of errors) {
-    console.error(`error: ${err}`);
-  }
-  if (errors.length > 0 && exports.length === 0) {
-    process.exit(1);
-  }
-  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}`);
+  const decisions = values.jev ? "jev" : loadConfig(process.cwd())?.decisions;
+  let cleanup;
+  try {
+    const resolved = await resolveCliTarget(positionals, decisions);
+    cleanup = resolved.cleanup;
+    const { exports, errors } = await listExports({ entryFile: resolved.entryFile });
+    for (const err of errors) {
+      console.error(`error: ${err}`);
+    }
+    if (errors.length > 0 && exports.length === 0) {
+      throw new CliError("", 1, true);
+    }
+    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}`);
+    }
+  } finally {
+    cleanup?.();
   }
 }
 function readSpecFile(file) {
   try {
-    return JSON.parse(fs.readFileSync(file, "utf-8"));
+    return JSON.parse(fs2.readFileSync(file, "utf-8"));
   } catch (err) {
     fail(`failed to read spec file ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -220,7 +425,7 @@ function validateCommand(args) {
   for (const e of errors) {
     console.error(`${e.instancePath || "/"} ${e.message}`);
   }
-  process.exit(1);
+  throw new CliError("", 1, true);
 }
 function diffCommand(args) {
   const { values, positionals } = parseArgs({
@@ -302,5 +507,11 @@ async function main() {
   }
 }
 main().catch((err) => {
-  fail(err instanceof Error ? err.message : String(err));
+  if (err instanceof CliError) {
+    if (!err.printed && err.message)
+      console.error(`error: ${err.message}`);
+    process.exit(err.exitCode);
+  }
+  console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/cli",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "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.2"
   },
   "devDependencies": {
     "@types/bun": "latest",