@openpkg-ts/cli 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# OpenPkg CLI
+
+[![npm version](https://img.shields.io/npm/v/@openpkg-ts%2Fcli.svg)](https://www.npmjs.com/package/@openpkg-ts/cli)
+
+Command-line interface for producing OpenPkg specs from TypeScript projects.
+
+## Installation
+
+```bash
+# npm
+npm install -g @openpkg-ts/cli
+
+# bun
+bun add -g @openpkg-ts/cli
+
+# yarn
+yarn global add @openpkg-ts/cli
+
+# pnpm
+pnpm add -g @openpkg-ts/cli
+```
+
+## Quick Start
+
+```bash
+# Generate openpkg.json for the current package
+openpkg generate
+
+# Target a specific entry file
+openpkg generate src/index.ts
+
+# Scaffold an OpenPkg config
+openpkg init
+```
+
+`openpkg generate` discovers the package manifest, figures out the correct entry point, resolves external .d.ts files when `node_modules` is present, and writes `openpkg.json` by default.
+
+## Commands
+
+### `openpkg init`
+
+Create a starter `openpkg.config` file in the current project. The CLI picks an extension automatically:
+
+- `openpkg.config.js` when the nearest `package.json` declares `{ "type": "module" }`
+- `openpkg.config.mjs` otherwise (compatible with both ESM and CommonJS projects)
+
+```bash
+openpkg init --cwd . --format auto
+```
+
+Options:
+
+- `--cwd <dir>` – Directory where the config should be created (defaults to current directory).
+- `--format <auto|mjs|js|cjs>` – Override the generated file extension.
+
+The command aborts when a config already exists anywhere up the directory tree.
+
+### `openpkg generate [entry]`
+
+Generate an OpenPkg spec from a file or package entry point.
+
+```bash
+openpkg generate src/index.ts --output lib/openpkg.json --include=createUser
+```
+
+Key behaviors:
+
+- Auto-detects the entry point when `[entry]` is omitted (using `exports`, `main`, or TypeScript config fields).
+- Honors `openpkg.config.*` defaults and then applies CLI flags on top.
+- Emits diagnostics from the TypeScript compiler and from OpenPkg's filtering passes.
+- Writes formatted JSON to `openpkg.json` (or the path supplied via `--output`).
+
+#### Options
+
+- `[entry]` – Entry file to analyze. Optional when the package exposes a single entry point.
+- `-o, --output <file>` – Output path (default: `openpkg.json`).
+- `-p, --package <name>` – Resolve and analyze a workspace package by name.
+- `--cwd <dir>` – Base directory for resolution (default: current directory).
+- `--no-external-types` – Skip pulling types from `node_modules`.
+- `--include <ids>` – Keep only the listed export identifiers (comma-separated or repeatable).
+- `--exclude <ids>` – Drop the listed export identifiers.
+- `-y, --yes` – Assume "yes" for prompts.
+
+## Configuration File
+
+Create an `openpkg.config.ts`, `.js`, or `.mjs` file anywhere above your working directory to keep reusable defaults. Prefer `.mjs`/`.cjs` if you are running the CLI under Node.js without a TypeScript loader.
+
+```ts
+// openpkg.config.mjs
+import { defineConfig } from '@openpkg-ts/cli/config';
+
+export default defineConfig({
+  include: ['createUser', 'deleteUser'],
+  exclude: ['internalHelper'],
+  resolveExternalTypes: true,
+});
+```
+
+The CLI searches the current directory and its parents for the first config file and merges those settings with flags provided on the command line. `defineConfig` helps with type-safety but is optional—you can export a plain object as well.
+
+### Supported Options
+
+- `include: string[]` – Export identifiers to keep.
+- `exclude: string[]` – Export identifiers to drop.
+- `resolveExternalTypes?: boolean` – Override automatic detection of external type resolution.
+
+CLI flags always win over config values. When both provide filters, the CLI prints a short summary of how the sets were combined.
+
+## Filtering Tips
+
+- `--include` narrows the spec to the identifiers you care about. Any referenced types that fall outside the allow-list are removed unless they are still referenced.
+- `--exclude` is useful for dropping experimental or internal APIs while keeping everything else.
+- Combine filters in configuration for defaults and override per run via CLI flags.
+
+## Monorepo Support
+
+Supply `--package <name>` from the workspace root to locate a child package automatically. The CLI understands npm, pnpm, yarn, and bun workspace layouts.
+
+```bash
+openpkg generate --package @myorg/transactions
+```
+
+## Output
+
+After a successful run the CLI prints:
+
+- The relative path to the written spec.
+- Counts for exports and types earned after filtering.
+- Any diagnostics collected during analysis.
+
+The JSON schema for the output lives at `schemas/v0.1.0/openpkg.schema.json` in this repository.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,454 @@
+#!/usr/bin/env node
+import {
+  OPENPKG_CONFIG_FILENAMES,
+  loadOpenPkgConfigInternal
+} from "./config/index.js";
+
+// src/cli.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import * as path4 from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+
+// src/commands/generate.ts
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import chalk2 from "chalk";
+import { OpenPkg } from "@openpkg-ts/sdk";
+import { normalize, validateSpec } from "@openpkg-ts/spec";
+import ora from "ora";
+
+// src/utils/filter-options.ts
+import chalk from "chalk";
+var unique = (values) => Array.from(new Set(values));
+var parseListFlag = (value) => {
+  if (!value) {
+    return;
+  }
+  const rawItems = Array.isArray(value) ? value : [value];
+  const normalized = rawItems.flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter(Boolean);
+  return normalized.length > 0 ? unique(normalized) : undefined;
+};
+var formatList = (label, values) => `${label}: ${values.map((value) => chalk.cyan(value)).join(", ")}`;
+var mergeFilterOptions = (config, cliOptions) => {
+  const messages = [];
+  const configInclude = config?.include;
+  const configExclude = config?.exclude;
+  const cliInclude = cliOptions.include;
+  const cliExclude = cliOptions.exclude;
+  let include = configInclude;
+  let exclude = configExclude;
+  let source = include || exclude ? "config" : undefined;
+  if (configInclude) {
+    messages.push(formatList("include filters from config", configInclude));
+  }
+  if (configExclude) {
+    messages.push(formatList("exclude filters from config", configExclude));
+  }
+  if (cliInclude) {
+    include = include ? include.filter((item) => cliInclude.includes(item)) : cliInclude;
+    source = include ? "combined" : "cli";
+    messages.push(formatList("apply include filters from CLI", cliInclude));
+  }
+  if (cliExclude) {
+    exclude = exclude ? unique([...exclude, ...cliExclude]) : cliExclude;
+    source = source ? "combined" : "cli";
+    messages.push(formatList("apply exclude filters from CLI", cliExclude));
+  }
+  include = include ? unique(include) : undefined;
+  exclude = exclude ? unique(exclude) : undefined;
+  if (!include && !exclude) {
+    return { messages };
+  }
+  return {
+    include,
+    exclude,
+    source,
+    messages
+  };
+};
+
+// src/utils/package-utils.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+async function findEntryPoint(packageDir, preferSource = false) {
+  const packageJsonPath = path.join(packageDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return findDefaultEntryPoint(packageDir);
+  }
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+  if (preferSource) {
+    const srcIndex = path.join(packageDir, "src/index.ts");
+    if (fs.existsSync(srcIndex)) {
+      return srcIndex;
+    }
+  }
+  if (!preferSource && (packageJson.types || packageJson.typings)) {
+    const typesPath = path.join(packageDir, packageJson.types || packageJson.typings);
+    if (fs.existsSync(typesPath)) {
+      return typesPath;
+    }
+  }
+  if (packageJson.exports) {
+    const exportPath = resolveExportsField(packageJson.exports, packageDir);
+    if (exportPath) {
+      return exportPath;
+    }
+  }
+  if (packageJson.main) {
+    const mainBase = packageJson.main.replace(/\.(js|mjs|cjs)$/, "");
+    const dtsPath = path.join(packageDir, `${mainBase}.d.ts`);
+    if (fs.existsSync(dtsPath)) {
+      return dtsPath;
+    }
+    const tsPath = path.join(packageDir, `${mainBase}.ts`);
+    if (fs.existsSync(tsPath)) {
+      return tsPath;
+    }
+    const mainPath = path.join(packageDir, packageJson.main);
+    if (fs.existsSync(mainPath) && fs.statSync(mainPath).isDirectory()) {
+      const indexDts = path.join(mainPath, "index.d.ts");
+      const indexTs = path.join(mainPath, "index.ts");
+      if (fs.existsSync(indexDts))
+        return indexDts;
+      if (fs.existsSync(indexTs))
+        return indexTs;
+    }
+  }
+  return findDefaultEntryPoint(packageDir);
+}
+function resolveExportsField(exports, packageDir) {
+  if (typeof exports === "string") {
+    return findTypeScriptFile(path.join(packageDir, exports));
+  }
+  if (typeof exports === "object" && exports !== null && "." in exports) {
+    const dotExport = exports["."];
+    if (typeof dotExport === "string") {
+      return findTypeScriptFile(path.join(packageDir, dotExport));
+    }
+    if (dotExport && typeof dotExport === "object") {
+      const dotRecord = dotExport;
+      const typesEntry = dotRecord.types;
+      if (typeof typesEntry === "string") {
+        const typesPath = path.join(packageDir, typesEntry);
+        if (fs.existsSync(typesPath)) {
+          return typesPath;
+        }
+      }
+      for (const condition of ["import", "require", "default"]) {
+        const target = dotRecord[condition];
+        if (typeof target === "string") {
+          const result = findTypeScriptFile(path.join(packageDir, target));
+          if (result)
+            return result;
+        }
+      }
+    }
+  }
+  return null;
+}
+function findTypeScriptFile(jsPath) {
+  if (!fs.existsSync(jsPath))
+    return null;
+  const dtsPath = jsPath.replace(/\.(js|mjs|cjs)$/, ".d.ts");
+  if (fs.existsSync(dtsPath)) {
+    return dtsPath;
+  }
+  const tsPath = jsPath.replace(/\.(js|mjs|cjs)$/, ".ts");
+  if (fs.existsSync(tsPath)) {
+    return tsPath;
+  }
+  return null;
+}
+async function findDefaultEntryPoint(packageDir) {
+  const candidates = [
+    "dist/index.d.ts",
+    "dist/index.ts",
+    "lib/index.d.ts",
+    "lib/index.ts",
+    "src/index.ts",
+    "index.d.ts",
+    "index.ts"
+  ];
+  for (const candidate of candidates) {
+    const fullPath = path.join(packageDir, candidate);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  throw new Error(`Could not find entry point in ${packageDir}`);
+}
+async function findPackageInMonorepo(rootDir, packageName) {
+  const rootPackageJsonPath = path.join(rootDir, "package.json");
+  if (!fs.existsSync(rootPackageJsonPath)) {
+    return null;
+  }
+  const rootPackageJson = JSON.parse(fs.readFileSync(rootPackageJsonPath, "utf-8"));
+  const workspacePatterns = Array.isArray(rootPackageJson.workspaces) ? rootPackageJson.workspaces : rootPackageJson.workspaces?.packages || [];
+  for (const pattern of workspacePatterns) {
+    const searchPath = path.join(rootDir, pattern.replace("/**", "").replace("/*", ""));
+    if (fs.existsSync(searchPath) && fs.statSync(searchPath).isDirectory()) {
+      const entries = fs.readdirSync(searchPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const packagePath = path.join(searchPath, entry.name);
+          const packageJsonPath = path.join(packagePath, "package.json");
+          if (fs.existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+            if (packageJson.name === packageName) {
+              return packagePath;
+            }
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// src/commands/generate.ts
+var defaultDependencies = {
+  createOpenPkg: (options) => new OpenPkg(options),
+  writeFileSync: fs2.writeFileSync,
+  spinner: (text) => ora(text),
+  log: console.log,
+  error: console.error
+};
+function getArrayLength(value) {
+  return Array.isArray(value) ? value.length : 0;
+}
+function registerGenerateCommand(program, dependencies = {}) {
+  const { createOpenPkg, writeFileSync: writeFileSync2, spinner, log, error } = {
+    ...defaultDependencies,
+    ...dependencies
+  };
+  program.command("generate [entry]").description("Generate OpenPkg specification").option("-o, --output <file>", "Output file", "openpkg.json").option("-p, --package <name>", "Target package name (for monorepos)").option("--cwd <dir>", "Working directory", process.cwd()).option("--no-external-types", "Skip external type resolution from node_modules").option("--include <ids>", "Filter exports by identifier (comma-separated or repeated)").option("--exclude <ids>", "Exclude exports by identifier (comma-separated or repeated)").option("-y, --yes", "Skip all prompts and use defaults").action(async (entry, options) => {
+    try {
+      let targetDir = options.cwd;
+      let entryFile = entry;
+      if (options.package) {
+        const packageDir = await findPackageInMonorepo(options.cwd, options.package);
+        if (!packageDir) {
+          throw new Error(`Package "${options.package}" not found in monorepo`);
+        }
+        targetDir = packageDir;
+        log(chalk2.gray(`Found package at ${path2.relative(options.cwd, packageDir)}`));
+      }
+      if (!entryFile) {
+        entryFile = await findEntryPoint(targetDir, true);
+        log(chalk2.gray(`Auto-detected entry point: ${path2.relative(targetDir, entryFile)}`));
+      } else {
+        entryFile = path2.resolve(targetDir, entryFile);
+      }
+      const resolveExternalTypes = options.externalTypes !== false;
+      const cliFilters = {
+        include: parseListFlag(options.include),
+        exclude: parseListFlag(options.exclude)
+      };
+      let config = null;
+      try {
+        config = await loadOpenPkgConfigInternal(targetDir);
+        if (config?.filePath) {
+          log(chalk2.gray(`Loaded configuration from ${path2.relative(targetDir, config.filePath)}`));
+        }
+      } catch (configError) {
+        error(chalk2.red("Failed to load OpenPkg config:"), configError instanceof Error ? configError.message : configError);
+        process.exit(1);
+      }
+      const resolvedFilters = mergeFilterOptions(config, cliFilters);
+      for (const message of resolvedFilters.messages) {
+        log(chalk2.gray(`• ${message}`));
+      }
+      const spinnerInstance = spinner("Generating OpenPkg spec...");
+      spinnerInstance.start();
+      let result;
+      try {
+        const openpkg = createOpenPkg({
+          resolveExternalTypes
+        });
+        const analyzeOptions = resolvedFilters.include || resolvedFilters.exclude ? {
+          filters: {
+            include: resolvedFilters.include,
+            exclude: resolvedFilters.exclude
+          }
+        } : {};
+        result = await openpkg.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
+        spinnerInstance.succeed("Generated OpenPkg spec");
+      } catch (generationError) {
+        spinnerInstance.fail("Failed to generate spec");
+        throw generationError;
+      }
+      if (!result) {
+        throw new Error("Failed to produce an OpenPkg spec.");
+      }
+      const outputPath = path2.resolve(targetDir, options.output);
+      const normalized = normalize(result.spec);
+      const validation = validateSpec(normalized);
+      if (!validation.ok) {
+        spinnerInstance.fail("Spec failed schema validation");
+        for (const err of validation.errors) {
+          error(chalk2.red(`schema: ${err.instancePath || "/"} ${err.message}`));
+        }
+        process.exit(1);
+      }
+      writeFileSync2(outputPath, JSON.stringify(normalized, null, 2));
+      log(chalk2.green(`✓ Generated ${path2.relative(process.cwd(), outputPath)}`));
+      log(chalk2.gray(`  ${getArrayLength(normalized.exports)} exports`));
+      log(chalk2.gray(`  ${getArrayLength(normalized.types)} types`));
+      if (result.diagnostics.length > 0) {
+        log("");
+        log(chalk2.bold("Diagnostics"));
+        for (const diagnostic of result.diagnostics) {
+          const prefix = diagnostic.severity === "error" ? chalk2.red("✖") : diagnostic.severity === "warning" ? chalk2.yellow("⚠") : chalk2.cyan("ℹ");
+          log(`${prefix} ${diagnostic.message}`);
+        }
+      }
+    } catch (commandError) {
+      error(chalk2.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/init.ts
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+import chalk3 from "chalk";
+var defaultDependencies2 = {
+  fileExists: fs3.existsSync,
+  writeFileSync: fs3.writeFileSync,
+  readFileSync: fs3.readFileSync,
+  log: console.log,
+  error: console.error
+};
+function registerInitCommand(program, dependencies = {}) {
+  const { fileExists, writeFileSync: writeFileSync3, readFileSync: readFileSync3, log, error } = {
+    ...defaultDependencies2,
+    ...dependencies
+  };
+  program.command("init").description("Create an OpenPkg configuration file").option("--cwd <dir>", "Working directory", process.cwd()).option("--format <format>", "Config format: auto, mjs, js, cjs", "auto").action((options) => {
+    const cwd = path3.resolve(options.cwd);
+    const formatOption = String(options.format ?? "auto").toLowerCase();
+    if (!isValidFormat(formatOption)) {
+      error(chalk3.red(`Invalid format "${formatOption}". Use auto, mjs, js, or cjs.`));
+      process.exitCode = 1;
+      return;
+    }
+    const existing = findExistingConfig(cwd, fileExists);
+    if (existing) {
+      error(chalk3.red(`An OpenPkg config already exists at ${path3.relative(cwd, existing) || "./openpkg.config.*"}.`));
+      process.exitCode = 1;
+      return;
+    }
+    const packageType = detectPackageType(cwd, fileExists, readFileSync3);
+    const targetFormat = resolveFormat(formatOption, packageType);
+    if (targetFormat === "js" && packageType !== "module") {
+      log(chalk3.yellow('Package is not marked as "type": "module"; creating openpkg.config.js may require enabling ESM.'));
+    }
+    const fileName = `openpkg.config.${targetFormat}`;
+    const outputPath = path3.join(cwd, fileName);
+    if (fileExists(outputPath)) {
+      error(chalk3.red(`Cannot create ${fileName}; file already exists.`));
+      process.exitCode = 1;
+      return;
+    }
+    const template = buildTemplate(targetFormat);
+    writeFileSync3(outputPath, template, { encoding: "utf8" });
+    log(chalk3.green(`✓ Created ${path3.relative(process.cwd(), outputPath)}`));
+  });
+}
+var isValidFormat = (value) => {
+  return value === "auto" || value === "mjs" || value === "js" || value === "cjs";
+};
+var findExistingConfig = (cwd, fileExists) => {
+  let current = path3.resolve(cwd);
+  const { root } = path3.parse(current);
+  while (true) {
+    for (const candidate of OPENPKG_CONFIG_FILENAMES) {
+      const candidatePath = path3.join(current, candidate);
+      if (fileExists(candidatePath)) {
+        return candidatePath;
+      }
+    }
+    if (current === root) {
+      break;
+    }
+    current = path3.dirname(current);
+  }
+  return null;
+};
+var detectPackageType = (cwd, fileExists, readFileSync3) => {
+  const packageJsonPath = findNearestPackageJson(cwd, fileExists);
+  if (!packageJsonPath) {
+    return;
+  }
+  try {
+    const raw = readFileSync3(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.type === "module") {
+      return "module";
+    }
+    if (parsed.type === "commonjs") {
+      return "commonjs";
+    }
+  } catch (_error) {}
+  return;
+};
+var findNearestPackageJson = (cwd, fileExists) => {
+  let current = path3.resolve(cwd);
+  const { root } = path3.parse(current);
+  while (true) {
+    const candidate = path3.join(current, "package.json");
+    if (fileExists(candidate)) {
+      return candidate;
+    }
+    if (current === root) {
+      break;
+    }
+    current = path3.dirname(current);
+  }
+  return null;
+};
+var resolveFormat = (format, packageType) => {
+  if (format === "auto") {
+    return packageType === "module" ? "js" : "mjs";
+  }
+  return format;
+};
+var buildTemplate = (format) => {
+  if (format === "cjs") {
+    return [
+      "const { defineConfig } = require('@openpkg-ts/cli/config');",
+      "",
+      "module.exports = defineConfig({",
+      "  include: [],",
+      "  exclude: [],",
+      "});",
+      ""
+    ].join(`
+`);
+  }
+  return [
+    "import { defineConfig } from '@openpkg-ts/cli/config';",
+    "",
+    "export default defineConfig({",
+    "  include: [],",
+    "  exclude: [],",
+    "});",
+    ""
+  ].join(`
+`);
+};
+
+// src/cli.ts
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path4.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync3(path4.join(__dirname2, "../package.json"), "utf-8"));
+var program = new Command;
+program.name("openpkg").description("Generate OpenPkg specification for TypeScript packages").version(packageJson.version);
+registerGenerateCommand(program);
+registerInitCommand(program);
+program.command("*", { hidden: true }).action(() => {
+  program.outputHelp();
+});
+program.parseAsync();

package/dist/config/index.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+declare const stringList: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+declare const openPkgConfigSchema: z.ZodObject<{
+	include: z.ZodOptional<typeof stringList>
+	exclude: z.ZodOptional<typeof stringList>
+	plugins: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>
+}>;
+type OpenPkgConfigInput = z.infer<typeof openPkgConfigSchema>;
+interface NormalizedOpenPkgConfig {
+	include?: string[];
+	exclude?: string[];
+	plugins?: unknown[];
+}
+interface LoadedOpenPkgConfig extends NormalizedOpenPkgConfig {
+	filePath: string;
+}
+declare const loadOpenPkgConfigInternal: (cwd: string) => Promise<LoadedOpenPkgConfig | null>;
+declare const define: (config: OpenPkgConfigInput) => OpenPkgConfigInput;
+export { loadOpenPkgConfigInternal as loadOpenPkgConfig, define as defineConfig, NormalizedOpenPkgConfig, LoadedOpenPkgConfig };

package/dist/config/index.js

@@ -0,0 +1,110 @@
+// src/config/openpkg-config.ts
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+// src/config/schema.ts
+import { z } from "zod";
+var stringList = z.union([
+  z.string(),
+  z.array(z.string())
+]);
+var openPkgConfigSchema = z.object({
+  include: stringList.optional(),
+  exclude: stringList.optional(),
+  plugins: z.array(z.unknown()).optional()
+});
+var normalizeList = (value) => {
+  if (!value) {
+    return;
+  }
+  const list = Array.isArray(value) ? value : [value];
+  const normalized = list.map((item) => item.trim()).filter(Boolean);
+  return normalized.length > 0 ? normalized : undefined;
+};
+var normalizeConfig = (input) => {
+  const include = normalizeList(input.include);
+  const exclude = normalizeList(input.exclude);
+  return {
+    include,
+    exclude,
+    plugins: input.plugins
+  };
+};
+
+// src/config/openpkg-config.ts
+var OPENPKG_CONFIG_FILENAMES = [
+  "openpkg.config.ts",
+  "openpkg.config.mts",
+  "openpkg.config.cts",
+  "openpkg.config.js",
+  "openpkg.config.mjs",
+  "openpkg.config.cjs"
+];
+var fileExists = async (filePath) => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var findConfigFile = async (cwd) => {
+  let current = path.resolve(cwd);
+  const { root } = path.parse(current);
+  while (true) {
+    for (const candidate of OPENPKG_CONFIG_FILENAMES) {
+      const candidatePath = path.join(current, candidate);
+      if (await fileExists(candidatePath)) {
+        return candidatePath;
+      }
+    }
+    if (current === root) {
+      return null;
+    }
+    current = path.dirname(current);
+  }
+};
+var importConfigModule = async (absolutePath) => {
+  const fileUrl = pathToFileURL(absolutePath);
+  fileUrl.searchParams.set("t", Date.now().toString());
+  const module = await import(fileUrl.href);
+  return module?.default ?? module?.config ?? module;
+};
+var formatIssues = (issues) => issues.map((issue) => `- ${issue}`).join(`
+`);
+var loadOpenPkgConfigInternal = async (cwd) => {
+  const configPath = await findConfigFile(cwd);
+  if (!configPath) {
+    return null;
+  }
+  let rawConfig;
+  try {
+    rawConfig = await importConfigModule(configPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to load OpenPkg config at ${configPath}: ${message}`);
+  }
+  const parsed = openPkgConfigSchema.safeParse(rawConfig);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => {
+      const pathLabel = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `${pathLabel}: ${issue.message}`;
+    });
+    throw new Error(`Invalid OpenPkg configuration at ${configPath}.
+${formatIssues(issues)}`);
+  }
+  const normalized = normalizeConfig(parsed.data);
+  return {
+    filePath: configPath,
+    ...normalized
+  };
+};
+
+// src/config/index.ts
+var define = (config) => config;
+export {
+  loadOpenPkgConfigInternal as loadOpenPkgConfig,
+  define as defineConfig
+};
+export { OPENPKG_CONFIG_FILENAMES, loadOpenPkgConfigInternal };

package/package.json

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