@n-dx/core 0.1.0

package/packages/llm-client/dist/llm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-config.js","sourceRoot":"","sources":["../src/llm-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAEzC,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzB,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;IACxE,IAAI,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,YAAY;QAAE,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IAC5F,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IAChE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1B,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzB,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;IACxE,IAAI,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,YAAY;QAAE,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IAC5F,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK;QAAE,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IAChE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QAErB,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,SAAS,GAAG,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChD,MAAM,YAAY,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEtD,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,IAAI,SAAS;YAAE,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;QACzC,IAAI,SAAS,IAAI,YAAY;YAAE,MAAM,CAAC,MAAM,GAAG,SAAS,IAAI,YAAY,CAAC;QACzE,IAAI,QAAQ;YAAE,MAAM,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtC,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/packages/llm-client/dist/llm-types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Vendor-neutral LLM client types.
+ *
+ * These types define the forward-looking contract for multi-vendor support
+ * while keeping the existing Claude-specific contract available for
+ * backward compatibility during migration.
+ *
+ * ## Dependency note
+ *
+ * This module imports only from foundational leaf modules (`types.ts`,
+ * `provider-interface.ts`). Factory-level types such as
+ * `CreateLLMClientOptions` live in `llm-client.ts` alongside the factory
+ * function they parameterise, keeping this file free of implementation
+ * dependencies.
+ */
+import type { ClaudeClient, ClaudeConfig } from "./types.js";
+import type { LLMVendor } from "./provider-interface.js";
+export type { LLMVendor };
+/** Optional Codex-specific config section in `.n-dx.json`. */
+export interface CodexConfig {
+    /** Path to Codex CLI binary. Defaults to `codex`. */
+    cli_path?: string;
+    /** API key used by future Codex API providers. */
+    api_key?: string;
+    /** Optional custom API endpoint. */
+    api_endpoint?: string;
+    /** Default model for Codex requests. */
+    model?: string;
+}
+/** Vendor-neutral config shape loaded from `.n-dx.json`. */
+export interface LLMConfig {
+    /** Default vendor selected by the project. */
+    vendor?: LLMVendor;
+    /** Claude-specific config (legacy + active). */
+    claude?: ClaudeConfig;
+    /** Codex-specific config (reserved for adapter integration). */
+    codex?: CodexConfig;
+}
+/** Alias that preserves migration ergonomics for downstream packages. */
+export type LLMClient = ClaudeClient;

package/packages/llm-client/dist/llm-types.js

@@ -0,0 +1,17 @@
+/**
+ * Vendor-neutral LLM client types.
+ *
+ * These types define the forward-looking contract for multi-vendor support
+ * while keeping the existing Claude-specific contract available for
+ * backward compatibility during migration.
+ *
+ * ## Dependency note
+ *
+ * This module imports only from foundational leaf modules (`types.ts`,
+ * `provider-interface.ts`). Factory-level types such as
+ * `CreateLLMClientOptions` live in `llm-client.ts` alongside the factory
+ * function they parameterise, keeping this file free of implementation
+ * dependencies.
+ */
+export {};
+//# sourceMappingURL=llm-types.js.map

package/packages/llm-client/dist/llm-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-types.js","sourceRoot":"","sources":["../src/llm-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/packages/llm-client/dist/output.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CLI output control — supports --quiet mode for scripting.
+ *
+ * Shared foundation for consistent output behavior across all packages.
+ * Each package may extend this with additional output functions (spinners,
+ * section headers, etc.) but the core quiet-mode primitives live here.
+ *
+ * In quiet mode, only essential output is emitted:
+ * - Error messages (always via console.error)
+ * - Final result identifiers (e.g. JSON, IDs, structured results)
+ *
+ * Informational messages (progress, hints, summaries) are suppressed.
+ */
+/** Enable or disable quiet mode. Call once at CLI entry. */
+export declare function setQuiet(quiet: boolean): void;
+/** Returns true when quiet mode is active. */
+export declare function isQuiet(): boolean;
+/**
+ * Print informational output. Suppressed in quiet mode.
+ * Use for progress messages, hints, decorative output.
+ */
+export declare function info(...args: unknown[]): void;
+/**
+ * Print result output. Always shown, even in quiet mode.
+ * Use for the primary data the user asked for: JSON, IDs, structured results.
+ */
+export declare function result(...args: unknown[]): void;

package/packages/llm-client/dist/output.js

@@ -0,0 +1,38 @@
+/**
+ * CLI output control — supports --quiet mode for scripting.
+ *
+ * Shared foundation for consistent output behavior across all packages.
+ * Each package may extend this with additional output functions (spinners,
+ * section headers, etc.) but the core quiet-mode primitives live here.
+ *
+ * In quiet mode, only essential output is emitted:
+ * - Error messages (always via console.error)
+ * - Final result identifiers (e.g. JSON, IDs, structured results)
+ *
+ * Informational messages (progress, hints, summaries) are suppressed.
+ */
+let _quiet = false;
+/** Enable or disable quiet mode. Call once at CLI entry. */
+export function setQuiet(quiet) {
+    _quiet = quiet;
+}
+/** Returns true when quiet mode is active. */
+export function isQuiet() {
+    return _quiet;
+}
+/**
+ * Print informational output. Suppressed in quiet mode.
+ * Use for progress messages, hints, decorative output.
+ */
+export function info(...args) {
+    if (!_quiet)
+        console.log(...args);
+}
+/**
+ * Print result output. Always shown, even in quiet mode.
+ * Use for the primary data the user asked for: JSON, IDs, structured results.
+ */
+export function result(...args) {
+    console.log(...args);
+}
+//# sourceMappingURL=output.js.map

package/packages/llm-client/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,MAAM,GAAG,KAAK,CAAC;AACjB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,OAAO;IACrB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,GAAG,IAAe;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,GAAG,IAAe;IACvC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AACvB,CAAC"}

package/packages/llm-client/dist/project-config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Project-level configuration utilities shared across packages.
+ *
+ * Handles loading .n-dx.json overrides and deep-merging them into
+ * package-specific configs. Previously duplicated identically in
+ * both rex and hench.
+ */
+/**
+ * Deep merge source into target. Source values take precedence.
+ * Arrays are replaced (not concatenated). Objects are recursively merged.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Load project-level .n-dx.json overrides for a specific package.
+ * Returns the package-scoped section (e.g., the "rex" key) or an empty object.
+ *
+ * @param configDir The package config directory (e.g., /project/.rex)
+ * @param packageKey The key to extract (e.g., "rex")
+ */
+export declare function loadProjectOverrides(configDir: string, packageKey: string): Promise<Record<string, unknown>>;
+/**
+ * Merge project-level overrides into a package config.
+ * Project config (.n-dx.json) takes precedence over package config.
+ */
+export declare function mergeWithOverrides<T>(config: T, overrides: Record<string, unknown>): T;

package/packages/llm-client/dist/project-config.js

@@ -0,0 +1,66 @@
+/**
+ * Project-level configuration utilities shared across packages.
+ *
+ * Handles loading .n-dx.json overrides and deep-merging them into
+ * package-specific configs. Previously duplicated identically in
+ * both rex and hench.
+ */
+import { dirname, join } from "node:path";
+import { readFile, access } from "node:fs/promises";
+const PROJECT_CONFIG_FILE = ".n-dx.json";
+/**
+ * Deep merge source into target. Source values take precedence.
+ * Arrays are replaced (not concatenated). Objects are recursively merged.
+ */
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const srcVal = source[key];
+        const tgtVal = result[key];
+        if (srcVal !== null &&
+            typeof srcVal === "object" &&
+            !Array.isArray(srcVal) &&
+            tgtVal !== null &&
+            typeof tgtVal === "object" &&
+            !Array.isArray(tgtVal)) {
+            result[key] = deepMerge(tgtVal, srcVal);
+        }
+        else {
+            result[key] = srcVal;
+        }
+    }
+    return result;
+}
+/**
+ * Load project-level .n-dx.json overrides for a specific package.
+ * Returns the package-scoped section (e.g., the "rex" key) or an empty object.
+ *
+ * @param configDir The package config directory (e.g., /project/.rex)
+ * @param packageKey The key to extract (e.g., "rex")
+ */
+export async function loadProjectOverrides(configDir, packageKey) {
+    const projectDir = dirname(configDir);
+    const configPath = join(projectDir, PROJECT_CONFIG_FILE);
+    try {
+        await access(configPath);
+        const raw = await readFile(configPath, "utf-8");
+        const data = JSON.parse(raw);
+        if (data && typeof data === "object" && data[packageKey]) {
+            return data[packageKey];
+        }
+    }
+    catch {
+        // File doesn't exist or is invalid — no overrides
+    }
+    return {};
+}
+/**
+ * Merge project-level overrides into a package config.
+ * Project config (.n-dx.json) takes precedence over package config.
+ */
+export function mergeWithOverrides(config, overrides) {
+    if (Object.keys(overrides).length === 0)
+        return config;
+    return deepMerge(config, overrides);
+}
+//# sourceMappingURL=project-config.js.map

package/packages/llm-client/dist/project-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../src/project-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,MAA+B,EAC/B,MAA+B;IAE/B,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,IACE,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACtB,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACtB,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CACrB,MAAiC,EACjC,MAAiC,CAClC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB,EACjB,UAAkB;IAElB,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC;IACzD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACzD,OAAO,IAAI,CAAC,UAAU,CAA4B,CAAC;QACrD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAS,EACT,SAAkC;IAElC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACvD,OAAO,SAAS,CACd,MAA4C,EAC5C,SAAS,CACM,CAAC;AACpB,CAAC"}

package/packages/llm-client/dist/project-dirs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared project directory constants for the n-dx monorepo.
+ *
+ * Each n-dx tool stores its data in a dot-directory under the project root:
+ * - `.rex/` — PRD tree, config, execution log
+ * - `.hench/` — agent config, run history
+ * - `.sourcevision/` — analysis output (inventory, imports, zones, components)
+ *
+ * These constants are the **single source of truth** for directory names.
+ * All packages import from here instead of defining their own literals,
+ * eliminating the risk of silent drift between CLI and MCP implementations.
+ *
+ * @example
+ * ```ts
+ * import { PROJECT_DIRS } from "@n-dx/llm-client";
+ *
+ * const rexDir = join(projectRoot, PROJECT_DIRS.REX);
+ * const henchDir = join(projectRoot, PROJECT_DIRS.HENCH);
+ * const svDir = join(projectRoot, PROJECT_DIRS.SOURCEVISION);
+ * ```
+ */
+/** Canonical dot-directory names for each n-dx tool. */
+export declare const PROJECT_DIRS: {
+    /** Rex PRD management directory (`.rex/`). */
+    readonly REX: ".rex";
+    /** Hench autonomous agent directory (`.hench/`). */
+    readonly HENCH: ".hench";
+    /** SourceVision analysis output directory (`.sourcevision/`). */
+    readonly SOURCEVISION: ".sourcevision";
+};
+/** Type of a single project directory name. */
+export type ProjectDir = (typeof PROJECT_DIRS)[keyof typeof PROJECT_DIRS];

package/packages/llm-client/dist/project-dirs.js

@@ -0,0 +1,31 @@
+/**
+ * Shared project directory constants for the n-dx monorepo.
+ *
+ * Each n-dx tool stores its data in a dot-directory under the project root:
+ * - `.rex/` — PRD tree, config, execution log
+ * - `.hench/` — agent config, run history
+ * - `.sourcevision/` — analysis output (inventory, imports, zones, components)
+ *
+ * These constants are the **single source of truth** for directory names.
+ * All packages import from here instead of defining their own literals,
+ * eliminating the risk of silent drift between CLI and MCP implementations.
+ *
+ * @example
+ * ```ts
+ * import { PROJECT_DIRS } from "@n-dx/llm-client";
+ *
+ * const rexDir = join(projectRoot, PROJECT_DIRS.REX);
+ * const henchDir = join(projectRoot, PROJECT_DIRS.HENCH);
+ * const svDir = join(projectRoot, PROJECT_DIRS.SOURCEVISION);
+ * ```
+ */
+/** Canonical dot-directory names for each n-dx tool. */
+export const PROJECT_DIRS = {
+    /** Rex PRD management directory (`.rex/`). */
+    REX: ".rex",
+    /** Hench autonomous agent directory (`.hench/`). */
+    HENCH: ".hench",
+    /** SourceVision analysis output directory (`.sourcevision/`). */
+    SOURCEVISION: ".sourcevision",
+};
+//# sourceMappingURL=project-dirs.js.map

package/packages/llm-client/dist/project-dirs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-dirs.js","sourceRoot":"","sources":["../src/project-dirs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wDAAwD;AACxD,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,8CAA8C;IAC9C,GAAG,EAAE,MAAM;IAEX,oDAAoD;IACpD,KAAK,EAAE,QAAQ;IAEf,iEAAiE;IACjE,YAAY,EAAE,eAAe;CACrB,CAAC"}

package/packages/llm-client/dist/provider-interface.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Generic LLM provider interface for multi-vendor support.
+ *
+ * ## Design goals
+ *
+ * - **Vendor-agnostic core** — The `LLMProvider` interface uses no
+ *   vendor-specific terminology. Adding a new vendor (e.g. Gemini, Bedrock)
+ *   requires only a new factory function, not changes to this file.
+ *
+ * - **Capability-driven** — Providers declare optional features (streaming,
+ *   function-calling, vision) in `ProviderInfo.capabilities`. Callers check
+ *   capabilities before invoking optional methods, enabling graceful
+ *   degradation across provider tiers.
+ *
+ * - **Extensible auth** — `ProviderAuthMode` covers known modes ("api",
+ *   "cli", "oauth") and accepts any string, so future providers can declare
+ *   their authentication strategy without changing this file.
+ *
+ * - **Backward-compatible** — The existing `ClaudeClient` interface remains
+ *   in `types.ts` for the duration of the migration. Providers may implement
+ *   both `ClaudeClient` and `LLMProvider` during the transition.
+ *
+ * ## Implementing a new provider
+ *
+ * 1. Create `createXyzProvider(options: XyzProviderOptions): LLMProvider`.
+ * 2. Populate `info` with accurate vendor, mode, model, and capabilities.
+ * 3. Implement `complete()` — all providers must support this.
+ * 4. Implement `stream()` and declare `"streaming"` in capabilities if supported.
+ * 5. Implement `validateAuth()` if the provider's credentials can be probed.
+ * 6. Register the factory with `defaultRegistry` in `provider-registry.ts`.
+ *
+ * @example
+ * ```ts
+ * import type { LLMProvider } from "@n-dx/llm-client";
+ *
+ * async function run(provider: LLMProvider) {
+ *   // Capability check before calling optional method
+ *   if (provider.info.capabilities.includes("streaming")) {
+ *     for await (const chunk of provider.stream!({ prompt: "Hi", model: "..." })) {
+ *       process.stdout.write(chunk.text ?? "");
+ *     }
+ *   } else {
+ *     const result = await provider.complete({ prompt: "Hi", model: "..." });
+ *     console.log(result.text);
+ *   }
+ * }
+ * ```
+ */
+import type { CompletionRequest, CompletionResult, TokenUsage } from "./types.js";
+/**
+ * Supported LLM vendors.
+ *
+ * Defined here (rather than `llm-types.ts`) so that `provider-interface.ts`
+ * has no upstream dependency on `llm-types.ts`, breaking a circular chain:
+ *   provider-interface → llm-types → create-client → api/cli-provider → provider-interface
+ *
+ * `llm-types.ts` re-exports this type so all existing consumers are unaffected.
+ */
+export type LLMVendor = "claude" | "codex";
+/**
+ * How a provider instance authenticates with the LLM service.
+ *
+ * Known modes:
+ * - `"api"` — Direct HTTP calls authenticated with an API key.
+ * - `"cli"` — Delegates to a local CLI binary (e.g. `claude`, `codex`).
+ * - `"oauth"` — OAuth 2.0 token flow (e.g. cloud provider integrations).
+ *
+ * The type is open (`string & {}`) so future providers can declare their own
+ * auth modes (e.g. `"iam"`, `"service-account"`) without changing this file.
+ */
+export type ProviderAuthMode = "api" | "cli" | "oauth" | (string & {});
+/**
+ * Optional feature flags a provider may declare.
+ *
+ * Callers use these to decide which `LLMProvider` methods are safe to invoke:
+ * - `"streaming"` — `provider.stream()` is defined and functional.
+ * - `"function-calling"` — Provider supports tool/function call responses.
+ * - `"vision"` — Provider can accept image inputs alongside text prompts.
+ * - `"embeddings"` — Provider can produce dense vector embeddings.
+ */
+export type ProviderCapability = "streaming" | "function-calling" | "vision" | "embeddings";
+/**
+ * Metadata about a provider instance.
+ *
+ * Aggregated into a single `info` property on `LLMProvider` so that callers
+ * inspect provider characteristics through one well-defined shape. Future
+ * fields (e.g. `region`, `tier`, `rateLimit`) can be added here without
+ * changing the top-level `LLMProvider` interface.
+ */
+export interface ProviderInfo {
+    /** Which LLM vendor this provider connects to. */
+    readonly vendor: LLMVendor;
+    /** Authentication strategy in use for this instance. */
+    readonly mode: ProviderAuthMode;
+    /**
+     * Active model identifier (e.g. `"claude-sonnet-4-6"`).
+     * Absent when the provider delegates model selection to the CLI.
+     */
+    readonly model?: string;
+    /**
+     * Feature flags this provider instance supports.
+     * Check before calling optional methods like `stream()`.
+     */
+    readonly capabilities: ReadonlyArray<ProviderCapability>;
+}
+/**
+ * A single chunk emitted by a streaming completion.
+ *
+ * Providers that support streaming yield these chunks incrementally.
+ * Typically `text` chunks arrive first, followed by a final chunk that
+ * carries `usage` and/or `done: true`.
+ */
+export interface StreamChunk {
+    /**
+     * Incremental text fragment from the model.
+     * May be absent in non-text events (e.g. the final usage chunk).
+     */
+    text?: string;
+    /**
+     * Token usage for the full request.
+     * Typically present only on the terminal chunk.
+     */
+    usage?: TokenUsage;
+    /**
+     * True when this is the terminal chunk and no more chunks follow.
+     * Consumers should stop iterating after receiving a chunk with `done: true`.
+     */
+    done?: boolean;
+}
+/**
+ * Generic interface all LLM provider implementations must satisfy.
+ *
+ * Providers are instantiated by vendor-specific factories and consumed
+ * uniformly by domain packages (rex, hench, sourcevision) through this
+ * interface. This decoupling means:
+ *
+ * - Domain packages depend on this interface, not on vendor SDKs.
+ * - Swapping or adding a vendor requires only a new factory function.
+ * - Providers declare their capabilities so callers can adapt gracefully.
+ *
+ * ## Required vs optional methods
+ *
+ * | Method           | Required | Guard before calling          |
+ * |------------------|----------|-------------------------------|
+ * | `complete()`     | ✓        | None — always available        |
+ * | `stream()`       | ✗        | `capabilities.includes("streaming")` |
+ * | `validateAuth()` | ✗        | Check for `undefined`          |
+ */
+export interface LLMProvider {
+    /**
+     * Metadata about this provider instance.
+     *
+     * Inspect `info.capabilities` before calling optional methods.
+     * Inspect `info.vendor` and `info.mode` for observability and fallback.
+     */
+    readonly info: ProviderInfo;
+    /**
+     * Perform a blocking completion and return the full response.
+     *
+     * All providers must implement this method. It is the lowest common
+     * denominator across all vendor integrations.
+     *
+     * @throws {ClaudeClientError} on classified failures (auth, timeout, rate-limit, etc.)
+     */
+    complete(request: CompletionRequest): Promise<CompletionResult>;
+    /**
+     * Stream a completion as an async iterable of incremental chunks.
+     *
+     * Only defined when `"streaming"` appears in `info.capabilities`.
+     * Always guard with a capability check before calling:
+     *
+     * ```ts
+     * if (provider.info.capabilities.includes("streaming")) {
+     *   for await (const chunk of provider.stream!(request)) {
+     *     process.stdout.write(chunk.text ?? "");
+     *   }
+     * }
+     * ```
+     *
+     * @throws {ClaudeClientError} on classified failures before the stream begins.
+     */
+    stream?(request: CompletionRequest): AsyncIterable<StreamChunk>;
+    /**
+     * Probe whether this provider's credentials are currently valid.
+     *
+     * Returns `true` if the provider can authenticate successfully.
+     * Returns `false` if credentials are invalid (wrong key, expired token).
+     * May throw `ClaudeClientError` for infrastructure failures (network, timeout).
+     *
+     * Optional: providers whose auth cannot be probed (e.g. CLI tools that
+     * authenticate through a browser session) may omit this method entirely.
+     */
+    validateAuth?(): Promise<boolean>;
+}

package/packages/llm-client/dist/provider-interface.js

@@ -0,0 +1,50 @@
+/**
+ * Generic LLM provider interface for multi-vendor support.
+ *
+ * ## Design goals
+ *
+ * - **Vendor-agnostic core** — The `LLMProvider` interface uses no
+ *   vendor-specific terminology. Adding a new vendor (e.g. Gemini, Bedrock)
+ *   requires only a new factory function, not changes to this file.
+ *
+ * - **Capability-driven** — Providers declare optional features (streaming,
+ *   function-calling, vision) in `ProviderInfo.capabilities`. Callers check
+ *   capabilities before invoking optional methods, enabling graceful
+ *   degradation across provider tiers.
+ *
+ * - **Extensible auth** — `ProviderAuthMode` covers known modes ("api",
+ *   "cli", "oauth") and accepts any string, so future providers can declare
+ *   their authentication strategy without changing this file.
+ *
+ * - **Backward-compatible** — The existing `ClaudeClient` interface remains
+ *   in `types.ts` for the duration of the migration. Providers may implement
+ *   both `ClaudeClient` and `LLMProvider` during the transition.
+ *
+ * ## Implementing a new provider
+ *
+ * 1. Create `createXyzProvider(options: XyzProviderOptions): LLMProvider`.
+ * 2. Populate `info` with accurate vendor, mode, model, and capabilities.
+ * 3. Implement `complete()` — all providers must support this.
+ * 4. Implement `stream()` and declare `"streaming"` in capabilities if supported.
+ * 5. Implement `validateAuth()` if the provider's credentials can be probed.
+ * 6. Register the factory with `defaultRegistry` in `provider-registry.ts`.
+ *
+ * @example
+ * ```ts
+ * import type { LLMProvider } from "@n-dx/llm-client";
+ *
+ * async function run(provider: LLMProvider) {
+ *   // Capability check before calling optional method
+ *   if (provider.info.capabilities.includes("streaming")) {
+ *     for await (const chunk of provider.stream!({ prompt: "Hi", model: "..." })) {
+ *       process.stdout.write(chunk.text ?? "");
+ *     }
+ *   } else {
+ *     const result = await provider.complete({ prompt: "Hi", model: "..." });
+ *     console.log(result.text);
+ *   }
+ * }
+ * ```
+ */
+export {};
+//# sourceMappingURL=provider-interface.js.map

package/packages/llm-client/dist/provider-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-interface.js","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG"}