@n-dx/core 0.1.0

package/packages/llm-client/dist/help-format.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Help formatting utilities with semantic color coding.
+ *
+ * Provides consistent, accessible help output across all n-dx CLI packages.
+ * Colors respect NO_COLOR, FORCE_COLOR, and terminal capabilities.
+ *
+ * ## Color semantics
+ *
+ * | Element           | Color  | Purpose                          |
+ * |-------------------|--------|----------------------------------|
+ * | Commands          | Cyan   | Executable names and subcommands |
+ * | Flags / options   | Yellow | --flag=<value> style options      |
+ * | Section headers   | Bold   | DESCRIPTION, USAGE, OPTIONS, etc.|
+ * | Required params   | Bold   | <required>                        |
+ * | Optional params   | Dim    | [optional]                        |
+ * | Descriptions      | (none) | Plain text for readability        |
+ * | Dim / secondary   | Dim    | Hints, "See also", etc.          |
+ *
+ * @module @n-dx/llm-client/help-format
+ */
+/** Check if color is enabled (lazy, cached). */
+export declare function isColorEnabled(): boolean;
+/** Reset cached color detection (for testing). */
+export declare function resetColorCache(): void;
+/** Bold text (section headers, required params). */
+export declare function bold(text: string): string;
+/** Dim text (optional params, hints, secondary info). */
+export declare function dim(text: string): string;
+/** Cyan text (command names, executable names). */
+export declare function cyan(text: string): string;
+/** Yellow text (flags, options). */
+export declare function yellow(text: string): string;
+/** Format a command name (cyan). */
+export declare function cmd(text: string): string;
+/** Format a flag/option name (yellow). */
+export declare function flag(text: string): string;
+/** Format a section header (bold, uppercase). */
+export declare function sectionHeader(text: string): string;
+/** Format a required parameter (bold angle brackets). */
+export declare function requiredParam(text: string): string;
+/** Format an optional parameter (dim square brackets). */
+export declare function optionalParam(text: string): string;
+/**
+ * Option definition for help formatting.
+ */
+export interface HelpOption {
+    /** Flag name(s) including dashes, e.g. "--format=<value>" or "--quiet, -q" */
+    flag: string;
+    /** Description of the option */
+    description: string;
+    /** Whether this option is required (default: false) */
+    required?: boolean;
+}
+/**
+ * Example definition for help formatting.
+ */
+export interface HelpExample {
+    /** The command to run */
+    command: string;
+    /** Description of what the command does */
+    description: string;
+}
+/**
+ * Complete help definition for a command.
+ */
+export interface HelpDefinition {
+    /** Tool name (e.g. "rex", "hench", "ndx") */
+    tool: string;
+    /** Command name (e.g. "status", "run") */
+    command: string;
+    /** One-line summary after the em dash */
+    summary: string;
+    /** Multi-line description paragraph(s) */
+    description?: string;
+    /** Usage pattern(s) — each line is a separate usage form */
+    usage: string | string[];
+    /** Named sections (e.g. "Phases", "Subcommands", "Levels") — rendered as-is with header */
+    sections?: Array<{
+        title: string;
+        content: string;
+    }>;
+    /** Options/flags */
+    options?: HelpOption[];
+    /** Examples */
+    examples?: HelpExample[];
+    /** Related commands (shown as "See also") */
+    related?: string[];
+}
+/**
+ * Format a complete help page from a definition.
+ *
+ * Produces consistently formatted output:
+ * ```
+ * tool command — summary
+ *
+ * DESCRIPTION
+ *   Multi-line description text.
+ *
+ * USAGE
+ *   tool command [options] [dir]
+ *
+ * OPTIONS
+ *   --flag=<value>    Description
+ *   --other           Description
+ *
+ * EXAMPLES
+ *   tool command                  Description
+ *   tool command --flag           Description
+ *
+ * See also: tool cmd1, tool cmd2
+ * ```
+ */
+export declare function formatHelp(def: HelpDefinition): string;
+/**
+ * Format a top-level usage page (for the main help of a tool).
+ *
+ * Renders a structured overview with grouped commands and global options.
+ */
+export interface UsageSection {
+    /** Section title (e.g. "Commands", "Orchestration", "Tools") */
+    title: string;
+    /** Items in this section */
+    items: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export interface UsageDefinition {
+    /** Title line (e.g. "rex v0.1.0 — PRD management") */
+    title: string;
+    /** Usage pattern */
+    usage: string;
+    /** Grouped command sections */
+    sections: UsageSection[];
+    /** Global options */
+    options?: HelpOption[];
+    /** Footer lines (hints, tips) */
+    footer?: string[];
+}
+/**
+ * Format a top-level usage/help page.
+ */
+export declare function formatUsage(def: UsageDefinition): string;

package/packages/llm-client/dist/help-format.js

@@ -0,0 +1,280 @@
+/**
+ * Help formatting utilities with semantic color coding.
+ *
+ * Provides consistent, accessible help output across all n-dx CLI packages.
+ * Colors respect NO_COLOR, FORCE_COLOR, and terminal capabilities.
+ *
+ * ## Color semantics
+ *
+ * | Element           | Color  | Purpose                          |
+ * |-------------------|--------|----------------------------------|
+ * | Commands          | Cyan   | Executable names and subcommands |
+ * | Flags / options   | Yellow | --flag=<value> style options      |
+ * | Section headers   | Bold   | DESCRIPTION, USAGE, OPTIONS, etc.|
+ * | Required params   | Bold   | <required>                        |
+ * | Optional params   | Dim    | [optional]                        |
+ * | Descriptions      | (none) | Plain text for readability        |
+ * | Dim / secondary   | Dim    | Hints, "See also", etc.          |
+ *
+ * @module @n-dx/llm-client/help-format
+ */
+// ── ANSI color support ──────────────────────────────────────────────────
+/**
+ * Detect whether the terminal supports color output.
+ *
+ * Respects the de-facto standards:
+ * - NO_COLOR (https://no-color.org/) — disables color when set
+ * - FORCE_COLOR — forces color when set (overrides NO_COLOR)
+ * - CI environments typically have TERM=dumb or no TTY
+ */
+function supportsColor() {
+    // FORCE_COLOR takes precedence over everything
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0") {
+        return true;
+    }
+    // NO_COLOR disables color (https://no-color.org/)
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") {
+        return false;
+    }
+    // Check if stdout is a TTY
+    if (process.stdout && typeof process.stdout.isTTY === "boolean") {
+        return process.stdout.isTTY;
+    }
+    return false;
+}
+/** Cached color support result (computed once). */
+let _colorEnabled = null;
+/** Check if color is enabled (lazy, cached). */
+export function isColorEnabled() {
+    if (_colorEnabled === null) {
+        _colorEnabled = supportsColor();
+    }
+    return _colorEnabled;
+}
+/** Reset cached color detection (for testing). */
+export function resetColorCache() {
+    _colorEnabled = null;
+}
+// ── ANSI escape helpers ─────────────────────────────────────────────────
+/** Wrap text in an ANSI escape sequence, respecting color detection. */
+function ansi(code, text, reset) {
+    if (!isColorEnabled())
+        return text;
+    return `\x1b[${code}m${text}\x1b[${reset}m`;
+}
+/** Bold text (section headers, required params). */
+export function bold(text) {
+    return ansi("1", text, "22");
+}
+/** Dim text (optional params, hints, secondary info). */
+export function dim(text) {
+    return ansi("2", text, "22");
+}
+/** Cyan text (command names, executable names). */
+export function cyan(text) {
+    return ansi("36", text, "39");
+}
+/** Yellow text (flags, options). */
+export function yellow(text) {
+    return ansi("33", text, "39");
+}
+// ── Semantic formatters ─────────────────────────────────────────────────
+/** Format a command name (cyan). */
+export function cmd(text) {
+    return cyan(text);
+}
+/** Format a flag/option name (yellow). */
+export function flag(text) {
+    return yellow(text);
+}
+/** Format a section header (bold, uppercase). */
+export function sectionHeader(text) {
+    return bold(text);
+}
+/** Format a required parameter (bold angle brackets). */
+export function requiredParam(text) {
+    return bold(`<${text}>`);
+}
+/** Format an optional parameter (dim square brackets). */
+export function optionalParam(text) {
+    return dim(`[${text}]`);
+}
+/**
+ * Format a flag string with color highlighting.
+ * Highlights the flag name in yellow and value placeholders appropriately.
+ */
+function formatFlag(flagStr) {
+    // Handle compound flags like "--quiet, -q"
+    return flagStr.replace(/--[\w-]+(?:=<[^>]+>)?|-\w/g, (match) => {
+        return flag(match);
+    });
+}
+/**
+ * Format a complete help page from a definition.
+ *
+ * Produces consistently formatted output:
+ * ```
+ * tool command — summary
+ *
+ * DESCRIPTION
+ *   Multi-line description text.
+ *
+ * USAGE
+ *   tool command [options] [dir]
+ *
+ * OPTIONS
+ *   --flag=<value>    Description
+ *   --other           Description
+ *
+ * EXAMPLES
+ *   tool command                  Description
+ *   tool command --flag           Description
+ *
+ * See also: tool cmd1, tool cmd2
+ * ```
+ */
+export function formatHelp(def) {
+    const lines = [];
+    // ── Title line ──
+    lines.push(`${cmd(def.tool)} ${cmd(def.command)} ${dim("—")} ${def.summary}`);
+    lines.push("");
+    // ── Description ──
+    if (def.description) {
+        lines.push(sectionHeader("DESCRIPTION"));
+        for (const line of def.description.split("\n")) {
+            lines.push(line ? `  ${line}` : "");
+        }
+        lines.push("");
+    }
+    // ── Usage ──
+    const usageLines = Array.isArray(def.usage) ? def.usage : [def.usage];
+    lines.push(sectionHeader("USAGE"));
+    for (const u of usageLines) {
+        lines.push(`  ${highlightUsageLine(u)}`);
+    }
+    lines.push("");
+    // ── Custom sections (Phases, Subcommands, Levels, etc.) ──
+    if (def.sections) {
+        for (const section of def.sections) {
+            lines.push(sectionHeader(section.title.toUpperCase()));
+            for (const line of section.content.split("\n")) {
+                lines.push(line ? `  ${line}` : "");
+            }
+            lines.push("");
+        }
+    }
+    // ── Options ──
+    if (def.options && def.options.length > 0) {
+        lines.push(sectionHeader("OPTIONS"));
+        // Calculate padding for alignment
+        const maxFlagLen = Math.max(...def.options.map((o) => o.flag.length));
+        const pad = Math.max(maxFlagLen + 4, 24); // At least 24 chars
+        for (const opt of def.options) {
+            const marker = opt.required ? bold("*") + " " : "  ";
+            const flagText = formatFlag(opt.flag);
+            // We need raw flag length for padding (without ANSI escapes)
+            const rawFlagLen = opt.flag.length;
+            const spacing = " ".repeat(Math.max(pad - rawFlagLen - 2, 2));
+            lines.push(`${marker}${flagText}${spacing}${opt.description}`);
+        }
+        // Legend for required marker
+        const hasRequired = def.options.some((o) => o.required);
+        if (hasRequired) {
+            lines.push("");
+            lines.push(dim("  * = required"));
+        }
+        lines.push("");
+    }
+    // ── Examples ──
+    if (def.examples && def.examples.length > 0) {
+        lines.push(sectionHeader("EXAMPLES"));
+        // Calculate padding for alignment
+        const maxCmdLen = Math.max(...def.examples.map((e) => e.command.length));
+        const pad = Math.max(maxCmdLen + 4, 36); // At least 36 chars
+        for (const ex of def.examples) {
+            const cmdText = cmd(ex.command);
+            const rawCmdLen = ex.command.length;
+            const spacing = " ".repeat(Math.max(pad - rawCmdLen - 2, 2));
+            lines.push(`  ${cmdText}${spacing}${dim(ex.description)}`);
+        }
+        lines.push("");
+    }
+    // ── See also ──
+    if (def.related && def.related.length > 0) {
+        const relatedStr = def.related.map((r) => cmd(`${def.tool} ${r}`)).join(dim(", "));
+        lines.push(dim("See also: ") + relatedStr);
+    }
+    return lines.join("\n");
+}
+/**
+ * Highlight a usage line: commands in cyan, [optional] in dim, <required> in bold.
+ */
+function highlightUsageLine(line) {
+    let result = line;
+    // Highlight <required> params
+    result = result.replace(/<([^>]+)>/g, (_, inner) => {
+        return bold(`<${inner}>`);
+    });
+    // Highlight [optional] params
+    result = result.replace(/\[([^\]]+)\]/g, (_, inner) => {
+        return dim(`[${inner}]`);
+    });
+    // Highlight leading command (first 1-2 words that look like commands)
+    // This handles "rex status" or "ndx plan" at the start
+    result = result.replace(/^(\S+)(\s+)(\S+)/, (_, tool, space, command) => {
+        // Only colorize if the first word looks like a tool name
+        if (/^(ndx|n-dx|rex|hench|sourcevision|sv|echo|cat)$/.test(tool)) {
+            return cmd(tool) + space + cmd(command);
+        }
+        return _;
+    });
+    return result;
+}
+/**
+ * Format a top-level usage/help page.
+ */
+export function formatUsage(def) {
+    const lines = [];
+    // ── Title ──
+    lines.push(def.title);
+    lines.push("");
+    // ── Usage ──
+    lines.push(sectionHeader("USAGE"));
+    lines.push(`  ${highlightUsageLine(def.usage)}`);
+    lines.push("");
+    // ── Command sections ──
+    for (const section of def.sections) {
+        lines.push(sectionHeader(section.title.toUpperCase()));
+        // Calculate padding for alignment
+        const maxNameLen = Math.max(...section.items.map((i) => i.name.length));
+        const pad = Math.max(maxNameLen + 4, 24);
+        for (const item of section.items) {
+            const nameText = cmd(item.name);
+            const rawNameLen = item.name.length;
+            const spacing = " ".repeat(Math.max(pad - rawNameLen - 2, 2));
+            lines.push(`  ${nameText}${spacing}${item.description}`);
+        }
+        lines.push("");
+    }
+    // ── Global options ──
+    if (def.options && def.options.length > 0) {
+        lines.push(sectionHeader("OPTIONS"));
+        const maxFlagLen = Math.max(...def.options.map((o) => o.flag.length));
+        const pad = Math.max(maxFlagLen + 4, 24);
+        for (const opt of def.options) {
+            const flagText = formatFlag(opt.flag);
+            const rawFlagLen = opt.flag.length;
+            const spacing = " ".repeat(Math.max(pad - rawFlagLen - 2, 2));
+            lines.push(`  ${flagText}${spacing}${opt.description}`);
+        }
+        lines.push("");
+    }
+    // ── Footer ──
+    if (def.footer) {
+        for (const line of def.footer) {
+            lines.push(dim(line));
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=help-format.js.map

package/packages/llm-client/dist/help-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-format.js","sourceRoot":"","sources":["../src/help-format.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,15 @@
+/**
+ * Canonical JSON serialization shared across all packages.
+ *
+ * Produces deterministic, human-readable output with 2-space indent
+ * and a trailing newline — the standard format for all .json files
+ * in the n-dx project.
+ */
+/**
+ * Serialize data to pretty-printed JSON with a trailing newline.
+ *
+ * Used throughout the monorepo for writing config files, PRD documents,
+ * analysis output, and run records. The trailing newline ensures
+ * POSIX-compliant text files and clean git diffs.
+ */
+export declare function toCanonicalJSON(data: unknown): string;

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

@@ -0,0 +1,18 @@
+/**
+ * Canonical JSON serialization shared across all packages.
+ *
+ * Produces deterministic, human-readable output with 2-space indent
+ * and a trailing newline — the standard format for all .json files
+ * in the n-dx project.
+ */
+/**
+ * Serialize data to pretty-printed JSON with a trailing newline.
+ *
+ * Used throughout the monorepo for writing config files, PRD documents,
+ * analysis output, and run records. The trailing newline ensures
+ * POSIX-compliant text files and clean git diffs.
+ */
+export function toCanonicalJSON(data) {
+    return JSON.stringify(data, null, 2) + "\n";
+}
+//# sourceMappingURL=json.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAC9C,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * Vendor-neutral client factory.
+ *
+ * Current support:
+ * - Claude: dual provider stack (API + CLI)
+ * - Codex: CLI provider (`codex exec`)
+ */
+import { type CreateClientOptions } from "./create-client.js";
+import type { AuthMode, ClaudeClient, ClaudeConfig } from "./types.js";
+import type { LLMVendor, LLMConfig } from "./llm-types.js";
+/**
+ * Vendor-neutral client creation options.
+ *
+ * Extends {@link CreateClientOptions} (minus the required `claudeConfig`) with
+ * vendor selection and a unified LLM config bag. Lives here — alongside the
+ * factory it parameterises — rather than in `llm-types.ts`, keeping that
+ * module free of implementation-layer dependencies.
+ */
+export interface CreateLLMClientOptions extends Omit<CreateClientOptions, "claudeConfig"> {
+    /** Explicit vendor override. Defaults to `llmConfig.vendor` or `claude`. */
+    vendor?: LLMVendor;
+    /** Unified vendor config loaded from project config. */
+    llmConfig?: LLMConfig;
+    /**
+     * Legacy Claude config override.
+     * If provided, takes precedence over `llmConfig.claude`.
+     */
+    claudeConfig?: ClaudeConfig;
+}
+/**
+ * Detect auth mode for the resolved vendor.
+ *
+ * For now this delegates to Claude's auth-mode detection. Codex returns `cli`
+ * as a conservative default until its provider adapters are implemented.
+ */
+export declare function detectLLMAuthMode(options: CreateLLMClientOptions): AuthMode;
+/**
+ * Create a vendor-neutral LLM client.
+ *
+ * Claude uses the production-ready dual provider implementation.
+ * Codex currently uses a CLI provider adapter.
+ */
+export declare function createLLMClient(options: CreateLLMClientOptions): ClaudeClient;

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

@@ -0,0 +1,48 @@
+/**
+ * Vendor-neutral client factory.
+ *
+ * Current support:
+ * - Claude: dual provider stack (API + CLI)
+ * - Codex: CLI provider (`codex exec`)
+ */
+import { createClient, detectAuthMode } from "./create-client.js";
+import { createCodexCliClient } from "./codex-cli-provider.js";
+function resolveVendor(options) {
+    return options.vendor ?? options.llmConfig?.vendor ?? "claude";
+}
+/**
+ * Detect auth mode for the resolved vendor.
+ *
+ * For now this delegates to Claude's auth-mode detection. Codex returns `cli`
+ * as a conservative default until its provider adapters are implemented.
+ */
+export function detectLLMAuthMode(options) {
+    const vendor = resolveVendor(options);
+    if (vendor === "codex")
+        return "cli";
+    const claudeConfig = options.claudeConfig ?? options.llmConfig?.claude ?? {};
+    return detectAuthMode({
+        claudeConfig,
+        apiKeyEnv: options.apiKeyEnv,
+    });
+}
+/**
+ * Create a vendor-neutral LLM client.
+ *
+ * Claude uses the production-ready dual provider implementation.
+ * Codex currently uses a CLI provider adapter.
+ */
+export function createLLMClient(options) {
+    const vendor = resolveVendor(options);
+    if (vendor === "codex") {
+        return createCodexCliClient({
+            codexConfig: options.llmConfig?.codex,
+        });
+    }
+    const claudeConfig = options.claudeConfig ?? options.llmConfig?.claude ?? {};
+    return createClient({
+        ...options,
+        claudeConfig,
+    });
+}
+//# sourceMappingURL=llm-client.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm-client.js","sourceRoot":"","sources":["../src/llm-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAA4B,MAAM,oBAAoB,CAAC;AAG5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAsB/D,SAAS,aAAa,CAAC,OAA+B;IACpD,OAAO,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,MAAM,IAAI,QAAQ,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA+B;IAC/D,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAErC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,MAAM,IAAI,EAAE,CAAC;IAC7E,OAAO,cAAc,CAAC;QACpB,YAAY;QACZ,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,oBAAoB,CAAC;YAC1B,WAAW,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK;SACtC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,MAAM,IAAI,EAAE,CAAC;IAC7E,OAAO,YAAY,CAAC;QAClB,GAAG,OAAO;QACV,YAAY;KACb,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,16 @@
+/**
+ * Vendor-neutral configuration loader.
+ *
+ * Reads `.n-dx.json` and returns an `LLMConfig` object that supports both
+ * a new `llm` section and legacy `claude` settings.
+ */
+import type { LLMConfig } from "./llm-types.js";
+/**
+ * Load the vendor-neutral LLM config from `.n-dx.json`.
+ *
+ * Merge behavior:
+ * - Reads `llm.vendor` if present.
+ * - Reads `llm.claude`/`llm.codex` blocks when present.
+ * - Falls back to legacy top-level `claude` block for compatibility.
+ */
+export declare function loadLLMConfig(dir: string): Promise<LLMConfig>;

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

@@ -0,0 +1,81 @@
+/**
+ * Vendor-neutral configuration loader.
+ *
+ * Reads `.n-dx.json` and returns an `LLMConfig` object that supports both
+ * a new `llm` section and legacy `claude` settings.
+ */
+import { join } from "node:path";
+import { access, readFile } from "node:fs/promises";
+const PROJECT_CONFIG_FILE = ".n-dx.json";
+function asRecord(value) {
+    return value && typeof value === "object" ? value : undefined;
+}
+function extractVendor(value) {
+    return value === "claude" || value === "codex" ? value : undefined;
+}
+function extractClaudeConfig(value) {
+    const v = asRecord(value);
+    if (!v)
+        return undefined;
+    const cfg = {};
+    if (typeof v.cli_path === "string" && v.cli_path)
+        cfg.cli_path = v.cli_path;
+    if (typeof v.api_key === "string" && v.api_key)
+        cfg.api_key = v.api_key;
+    if (typeof v.api_endpoint === "string" && v.api_endpoint)
+        cfg.api_endpoint = v.api_endpoint;
+    if (typeof v.model === "string" && v.model)
+        cfg.model = v.model;
+    return Object.keys(cfg).length > 0 ? cfg : undefined;
+}
+function extractCodexConfig(value) {
+    const v = asRecord(value);
+    if (!v)
+        return undefined;
+    const cfg = {};
+    if (typeof v.cli_path === "string" && v.cli_path)
+        cfg.cli_path = v.cli_path;
+    if (typeof v.api_key === "string" && v.api_key)
+        cfg.api_key = v.api_key;
+    if (typeof v.api_endpoint === "string" && v.api_endpoint)
+        cfg.api_endpoint = v.api_endpoint;
+    if (typeof v.model === "string" && v.model)
+        cfg.model = v.model;
+    return Object.keys(cfg).length > 0 ? cfg : undefined;
+}
+/**
+ * Load the vendor-neutral LLM config from `.n-dx.json`.
+ *
+ * Merge behavior:
+ * - Reads `llm.vendor` if present.
+ * - Reads `llm.claude`/`llm.codex` blocks when present.
+ * - Falls back to legacy top-level `claude` block for compatibility.
+ */
+export async function loadLLMConfig(dir) {
+    const path = join(dir, PROJECT_CONFIG_FILE);
+    try {
+        await access(path);
+        const raw = await readFile(path, "utf-8");
+        const data = JSON.parse(raw);
+        const root = asRecord(data);
+        if (!root)
+            return {};
+        const llm = asRecord(root.llm);
+        const llmVendor = extractVendor(llm?.vendor);
+        const llmClaude = extractClaudeConfig(llm?.claude);
+        const llmCodex = extractCodexConfig(llm?.codex);
+        const legacyClaude = extractClaudeConfig(root.claude);
+        const config = {};
+        if (llmVendor)
+            config.vendor = llmVendor;
+        if (llmClaude || legacyClaude)
+            config.claude = llmClaude ?? legacyClaude;
+        if (llmCodex)
+            config.codex = llmCodex;
+        return config;
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=llm-config.js.map