@adhd/apigen-cli 0.1.0

package/lib/apigen-cli.d.ts

@@ -0,0 +1 @@
+export declare function apigenCli(): string;

package/lib/commands/generate-registry.d.ts

@@ -0,0 +1,4 @@
+import { OutputPlugin } from '@adhd/apigen-core';
+import { Command } from 'commander';
+
+export declare function registerGenerateRegistryCommand(program: Command, plugins: Record<string, OutputPlugin>): void;

package/lib/commands/generate.d.ts

@@ -0,0 +1,6 @@
+import { ExportMode, OutputPlugin } from '@adhd/apigen-core';
+import { Command } from 'commander';
+
+/** Resolve the --export flag value to an ExportMode. */
+export declare function resolveExportMode(exportFlag: string | undefined): ExportMode;
+export declare function registerGenerateCommand(program: Command, plugins: Record<string, OutputPlugin>): void;

package/lib/commands/run-registry.d.ts

@@ -0,0 +1,4 @@
+import { OutputPlugin } from '@adhd/apigen-core';
+import { Command } from 'commander';
+
+export declare function registerRunRegistryCommand(program: Command, plugins: Record<string, OutputPlugin>): void;

package/lib/commands/run.d.ts

@@ -0,0 +1,4 @@
+import { OutputPlugin } from '@adhd/apigen-core';
+import { Command } from 'commander';
+
+export declare function registerRunCommand(program: Command, plugins: Record<string, OutputPlugin>): void;

package/lib/import-source.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dynamically import a (possibly TypeScript) source module, registering the tsx
+ * ESM loader for the duration of the import so that `.ts` entry files resolve in
+ * a plain `node` process. The loader is unregistered afterward so no global hook
+ * leaks into the rest of the run.
+ *
+ * Under a transpiling test runner (vitest) tsx registration is a harmless no-op,
+ * so this same path works in-repo and standalone.
+ *
+ * @param absSource - Absolute path to the source file to import.
+ * @param tsconfig  - Optional tsconfig.json path to drive tsx's transpilation.
+ * @returns The imported module namespace.
+ */
+export declare function importSource(absSource: string, tsconfig?: string): Promise<Record<string, unknown>>;

package/lib/logging.d.ts

@@ -0,0 +1,16 @@
+import { Logger } from '@adhd/apigen-runtime';
+import { Command } from 'commander';
+
+export interface LoggingFlags {
+    logLevel?: string;
+    logFormat?: string;
+    logFile?: string;
+}
+/** Add program-level logging options. Env vars provide fallbacks at build time. */
+export declare function addLoggingOptions(program: Command): Command;
+/**
+ * Build the shared CLI logger from program-level flags, falling back to env
+ * vars (`APIGEN_LOG_LEVEL`, `APIGEN_LOG_FORMAT`, `APIGEN_LOG_FILE`). Flags win
+ * over env. Logs target stderr (or `--log-file`) — never stdout.
+ */
+export declare function buildCliLogger(program: Command): Logger;

package/lib/orchestrator.d.ts

@@ -0,0 +1,153 @@
+import { ProjectionConfig } from '@adhd/apigen-naming';
+import { Operation, Descriptor, ComposedSchemas, ExportMode, Logger, OutputPlugin } from '@adhd/apigen-core';
+
+/**
+ * A single source entry passed to the orchestrator.
+ *
+ * `file` is an absolute path.  Language detection is performed here — for now
+ * `.ts` / `.tsx` / `.mts` / `.cts` → `'ts'`; everything else is unsupported
+ * and will throw.
+ */
+export interface SourceEntry {
+    /** Absolute path to the source file. */
+    file: string;
+    /**
+     * Export mode for this source. Defaults to `{ type: 'named' }` when omitted.
+     * Per-source because a single `run` may compose multiple differently-shaped
+     * sources.
+     */
+    exportMode?: ExportMode;
+    /**
+     * Namespace override for this source.  When omitted, namespace is resolved
+     * from the nearest tsconfig folder (same logic as v1).
+     */
+    namespace?: string;
+    /** Explicit tsconfig.json path.  Resolved per source file when omitted. */
+    tsconfig?: string;
+}
+/**
+ * Projection-override config (Tenet 1).
+ *
+ * Accepted from `--opt http.verb.<id>=GET` pairs or an `apigen.config` file.
+ * Overrides are NEVER written to source.
+ */
+export interface OverrideConfig extends ProjectionConfig {
+}
+/** Options passed to the v2 orchestrator. */
+export interface OrchestratorOptions {
+    /** Source files to extract and merge.  Must be non-empty. */
+    sources: SourceEntry[];
+    /**
+     * Plugin ids supplied via `--use <plugin>` (layer / mount / envelope
+     * plugins).  Validated but not dispatched in v1 — wired through for v2.x.
+     */
+    usePlugins?: string[];
+    /** Projection-override config (Tenet 1). */
+    overrides?: OverrideConfig;
+    /** Shared logger. */
+    logger?: Logger;
+}
+/** The unified canonical descriptor built by the orchestrator. */
+export interface OrchestratorDescriptor {
+    /** All extracted + merged operations (tagged by `host`). */
+    operations: Operation[];
+    /**
+     * Per-source composed schemas, keyed by the source's resolved namespace.
+     * The v1 `PluginInput.packages` is built from these.
+     */
+    packageSchemas: Map<string, {
+        id: string;
+        schemas: ComposedSchemas;
+        importPath: string;
+    }>;
+}
+/** Result returned by `orchestrateGenerate`. */
+export interface GenerateResult {
+    descriptor: OrchestratorDescriptor;
+    pluginOutput: Awaited<ReturnType<OutputPlugin['generate']>>;
+}
+/** Supported host languages (only 'ts' in v1). */
+export type HostLang = 'ts';
+/**
+ * Detects the host language from a file path extension.
+ *
+ * @throws if the extension is not a recognised TypeScript extension.
+ */
+export declare function detectLang(filePath: string): HostLang;
+/**
+ * Parses `--opt` key=value pairs into an {@link OverrideConfig}.
+ *
+ * Recognises:
+ *   `http.verb.<operationId>=GET`  → config.http.verb[operationId] = 'GET'
+ *
+ * Unknown keys are silently ignored (forward-compatible).
+ *
+ * @param pairs - Raw `key=value` strings from `--opt`.
+ */
+export declare function parseOverrides(pairs: string[]): OverrideConfig;
+/**
+ * Loads an `apigen.config` JSON file and merges it with CLI overrides.
+ *
+ * CLI overrides win over the file.  The file is optional; when absent this is
+ * a no-op.
+ *
+ * @param configPath - Optional explicit path.  When omitted, looks for
+ *   `apigen.config.json` in the current working directory.
+ * @param cliOverrides - Already-parsed CLI overrides (win over file).
+ */
+export declare function loadOverrideConfig(configPath: string | undefined, cliOverrides: OverrideConfig): OverrideConfig;
+/**
+ * Merge multiple per-source `Operation[]` arrays into one unified list.
+ *
+ * Operations are tagged by `host` from the extractor.  No deduplication — two
+ * distinct sources may export the same name in different namespaces; the
+ * collision check enforces uniqueness across transports.
+ *
+ * @param perSourceOps - Arrays produced by {@link extractSource} per file.
+ */
+export declare function mergeOperations(perSourceOps: Operation[][]): Operation[];
+/**
+ * Build the unified `OrchestratorDescriptor` from a set of source entries.
+ *
+ * Steps:
+ *   1. Detect language per source.
+ *   2. Extract canonical `Operation[]` per source (v2 extract).
+ *   3. Merge into one list.
+ *   4. Run the collision check (SPEC §5 uniqueness invariant).
+ *   5. Build per-source `ComposedSchemas` for the v1 plugin surface.
+ *
+ * @param opts - Orchestrator options.
+ */
+export declare function buildDescriptor(opts: OrchestratorOptions): Promise<OrchestratorDescriptor>;
+/**
+ * Run the v2 orchestrator in **generate** mode.
+ *
+ * Builds the unified descriptor, then invokes the selected plugin's `generate`
+ * method with the merged package set.
+ *
+ * @param opts      - Orchestrator options.
+ * @param plugin    - The selected output plugin (`--type`).
+ * @param outputDir - Absolute path to the output directory.
+ * @param pluginOpts - Plugin-level options (`--opt` key=value pairs, already parsed).
+ */
+export declare function orchestrateGenerate(opts: OrchestratorOptions, plugin: OutputPlugin, outputDir: string, pluginOpts?: Record<string, unknown>): Promise<GenerateResult>;
+/**
+ * Run the v2 orchestrator in **run** (server) mode.
+ *
+ * Builds the unified descriptor, then invokes the selected plugin's `run`
+ * method with the merged package set + live function tables.
+ *
+ * @param opts          - Orchestrator options.
+ * @param plugin        - The selected output plugin (`--type`).
+ * @param buildFnTables - Async function that imports each source and returns
+ *                        `(fns, createClient)` for that source.  Injected by
+ *                        the command layer so the orchestrator stays testable
+ *                        without live imports.
+ * @param signal        - Abort signal forwarded from the process SIGINT handler.
+ * @param pluginOpts    - Plugin-level options.
+ */
+export declare function orchestrateRun(opts: OrchestratorOptions, plugin: OutputPlugin, buildFnTables: (entry: SourceEntry) => Promise<{
+    fns: Record<string, (...args: unknown[]) => unknown>;
+    createClient: (envelope: Record<string, unknown>) => Promise<object>;
+}>, signal: AbortSignal, pluginOpts?: Record<string, unknown>): Promise<void>;
+export type { Descriptor };

package/lib/pipeline.d.ts

@@ -0,0 +1,22 @@
+import { ComposedSchemas, ExportMode, Logger } from '@adhd/apigen-core';
+
+export interface PipelineOptions {
+    sourceFile: string;
+    exportMode?: ExportMode;
+    middlewares?: Array<{
+        id: string;
+        envelope?: Record<string, unknown>;
+    }>;
+    overrides?: Record<string, Record<string, boolean>>;
+    namespace?: string;
+    /** Explicit --tsconfig flag; when omitted, the nearest/builtin config is resolved from sourceFile. */
+    tsconfig?: string;
+    /** Optional shared logger; when present the pipeline logs schema extraction. */
+    logger?: Logger;
+}
+export interface PipelineResult {
+    schemas: ComposedSchemas;
+    createClient: (envelope: Record<string, unknown>) => Promise<object>;
+}
+/** Run the generate + compose pipeline for a single source file. */
+export declare function runPipeline(opts: PipelineOptions): Promise<PipelineResult>;

package/lib/registry.d.ts

@@ -0,0 +1,12 @@
+export interface PackageMeta {
+    id: string;
+    dir: string;
+    importPath: string;
+    tags: string[];
+}
+/** Discover packages in a directory, filtered by tag. Reads package.json for tags/keywords. */
+export declare function discoverPackages(opts: {
+    packagesDir: string;
+    includeTags?: string[];
+    excludeTags?: string[];
+}): PackageMeta[];

package/lib/resolve-tsconfig.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolve the tsconfig that should drive schema generation for `sourceFile`.
+ *
+ * Precedence: explicit `--tsconfig` (absolute) → nearest `tsconfig.json` walking
+ * up from the source's directory → shipped builtin default.
+ *
+ * @param sourceFile - Absolute path to the TypeScript source file.
+ * @param explicit   - Optional `--tsconfig` flag value (resolved against cwd).
+ * @returns Absolute path to a real tsconfig.json file.
+ */
+export declare function resolveTsconfig(sourceFile: string, explicit?: string): string;
+/**
+ * Resolve the package namespace (id) for a source file.
+ *
+ * Precedence: explicit `--namespace` → the folder name CONTAINING the tsconfig
+ * (the `--tsconfig` dir if given, else the nearest `tsconfig.json` walking up) →
+ * the source file's parent folder name (when no project tsconfig is found).
+ *
+ * @param sourceFile - Path to the TypeScript source file.
+ * @param opts.namespace - Optional explicit `--namespace` override.
+ * @param opts.tsconfig  - Optional explicit `--tsconfig` value.
+ */
+export declare function resolveNamespace(sourceFile: string, opts?: {
+    namespace?: string;
+    tsconfig?: string;
+}): string;

package/lib/scaffold.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Emit resolution scaffolding (`package.json`, `tsconfig.json`, `node_modules`
+ * symlink) into `outputDir` for the given `pluginId`, so the generated entrypoint
+ * runs from an arbitrary directory. Idempotent: never clobbers existing files.
+ *
+ * @param outputDir - The `--out-dir` the generated files were written to.
+ * @param pluginId  - The plugin id (`mcp`, `cli`, …) — selects the dep set.
+ * @returns The names of the scaffolding files written (for logging).
+ */
+export declare function emitResolutionScaffolding(outputDir: string, pluginId: string, opts?: {
+    linkWorkspace?: boolean;
+}): string[];

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@adhd/apigen-cli",
+  "version": "0.1.0",
+  "bin": {
+    "apigen-cli": "./index.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "ts-morph": "^23.0.0",
+    "ts-json-schema-generator": "^2.3.0",
+    "tsx": "^4.22.4",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "fastify": "^4.0.0",
+    "express": "^5.2.1",
+    "pino": "10.3.1",
+    "pino-pretty": "13.1.3",
+    "pino-http": "11.0.0",
+    "@adhd/apigen-core": "^0.1.0",
+    "@adhd/apigen-runtime": "^0.1.0",
+    "@adhd/apigen-plugin-mcp": "^0.1.0",
+    "@adhd/apigen-plugin-jsonschema": "^0.1.0",
+    "@adhd/apigen-plugin-api-fastify": "^0.1.0",
+    "@adhd/apigen-plugin-api-express": "^0.1.0",
+    "@adhd/apigen-plugin-cli-output": "^0.1.0"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}