@n-dx/core 0.1.0

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

@@ -0,0 +1,165 @@
+/**
+ * Authentication detection and validation.
+ *
+ * Provides utilities to detect available authentication methods (CLI / API key),
+ * validate credentials before use, and produce human-readable diagnostics when
+ * authentication is misconfigured.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { ClaudeClientError } from "./types.js";
+import { resolveApiKey, resolveCliPath } from "./config.js";
+import { exec } from "./exec.js";
+// ── CLI availability ─────────────────────────────────────────────────────────
+/**
+ * Check whether the Claude Code CLI binary is reachable.
+ *
+ * Runs `<binary> --version` and resolves `true` if the command exits
+ * successfully (exit code 0), `false` otherwise (not found, permission
+ * error, crash, etc.).
+ */
+export async function detectCliAvailability(options) {
+    const binary = resolveCliPath(options.claudeConfig);
+    const result = await exec(binary, ["--version"], { cwd: process.cwd(), timeout: 5000 });
+    return result.exitCode === 0;
+}
+// ── API key validation ───────────────────────────────────────────────────────
+/**
+ * Validate that the resolved API key is accepted by the Anthropic API.
+ *
+ * Makes a minimal `messages.create` call with 1 max_tokens. The call is
+ * expected to succeed (or fail with a non-auth error such as rate-limit),
+ * confirming the key is valid.
+ *
+ * @returns `true` if the key is valid, `false` if authentication fails
+ *   (401/403).
+ * @throws {ClaudeClientError} with reason "auth" when no API key is
+ *   available at all (not configured and not in env).
+ */
+export async function validateApiKey(options) {
+    const apiKeyEnv = options.apiKeyEnv ?? "ANTHROPIC_API_KEY";
+    const apiKey = resolveApiKey(options.claudeConfig, apiKeyEnv);
+    if (!apiKey) {
+        throw new ClaudeClientError(`API key not found. Set it via 'n-dx config claude.api_key <key>' or the ${apiKeyEnv} environment variable.`, "auth", false);
+    }
+    const clientOpts = { apiKey };
+    if (options.claudeConfig.api_endpoint) {
+        clientOpts.baseURL = options.claudeConfig.api_endpoint;
+    }
+    const client = new Anthropic(clientOpts);
+    try {
+        await client.messages.create({
+            model: "claude-sonnet-4-6",
+            max_tokens: 1,
+            messages: [{ role: "user", content: "hi" }],
+        });
+        return true;
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === 401 || status === 403) {
+            return false;
+        }
+        // Any other error (rate-limit, network, etc.) means the key itself is
+        // structurally valid — the failure is unrelated to authentication.
+        return true;
+    }
+}
+/**
+ * Detect the best available authentication method by actually probing the
+ * environment (checking the CLI binary and API key availability).
+ *
+ * Unlike the synchronous `detectAuthMode()` in create-client.ts which only
+ * checks for an API key, this function also verifies CLI availability so the
+ * caller gets a complete picture.
+ *
+ * Priority:
+ * 1. API key present (from config or env) → "api"
+ * 2. CLI binary reachable → "cli"
+ * 3. Neither available → throws with a helpful error message
+ *
+ * @throws {ClaudeClientError} with reason "auth" when neither method is
+ *   available.
+ */
+export async function detectAvailableAuth(options) {
+    const apiKeyEnv = options.apiKeyEnv ?? "ANTHROPIC_API_KEY";
+    const apiKey = resolveApiKey(options.claudeConfig, apiKeyEnv);
+    const apiKeyAvailable = !!apiKey;
+    if (apiKeyAvailable) {
+        // API key takes priority — don't even check CLI
+        return { mode: "api", apiKeyAvailable: true, cliAvailable: false };
+    }
+    // No API key → check if CLI is available as fallback
+    const cliAvailable = await detectCliAvailability(options);
+    if (cliAvailable) {
+        return { mode: "cli", apiKeyAvailable: false, cliAvailable: true };
+    }
+    // Neither method is available
+    throw new ClaudeClientError("No authentication method available. Either:\n" +
+        `  - Set an API key: n-dx config claude.api_key <key> (or export ${apiKeyEnv}=<key>)\n` +
+        "  - Install the Claude Code CLI: npm install -g @anthropic-ai/claude-code", "auth", false);
+}
+/**
+ * Run a full diagnostic check on authentication configuration.
+ *
+ * This is useful for `ndx config` / status commands to tell the user
+ * exactly what is and isn't working.
+ *
+ * When `validateKey` is true (default: false), the function makes a real
+ * API call to verify the key is accepted. This costs a tiny number of
+ * tokens but confirms end-to-end auth.
+ */
+export async function diagnoseAuth(options) {
+    const apiKeyEnv = options.apiKeyEnv ?? "ANTHROPIC_API_KEY";
+    const messages = [];
+    // ── API key ──
+    const configKey = options.claudeConfig.api_key;
+    const envKey = process.env[apiKeyEnv];
+    let apiKeySource = "none";
+    let apiKeyValid;
+    if (configKey) {
+        apiKeySource = "config";
+        messages.push(`API key: found in .n-dx.json (claude.api_key)`);
+    }
+    else if (envKey) {
+        apiKeySource = "env";
+        messages.push(`API key: found in environment (${apiKeyEnv})`);
+    }
+    else {
+        messages.push("API key: not configured");
+    }
+    if (apiKeySource !== "none" && options.validateKey) {
+        try {
+            apiKeyValid = await validateApiKey(options);
+            messages.push(apiKeyValid ? "API key: validated successfully" : "API key: rejected by API (invalid or expired)");
+        }
+        catch {
+            apiKeyValid = false;
+            messages.push("API key: validation failed");
+        }
+    }
+    // ── CLI ──
+    const cliAvailable = await detectCliAvailability(options);
+    const cliPath = resolveCliPath(options.claudeConfig);
+    if (cliAvailable) {
+        messages.push(`CLI: available (${cliPath})`);
+    }
+    else {
+        messages.push(`CLI: not found (looked for: ${cliPath})`);
+    }
+    // ── Recommendation ──
+    let recommendedMode = "none";
+    if (apiKeySource !== "none" && apiKeyValid !== false) {
+        recommendedMode = "api";
+    }
+    else if (cliAvailable) {
+        recommendedMode = "cli";
+    }
+    if (recommendedMode === "none") {
+        messages.push("No authentication method available. Set an API key or install the Claude Code CLI.");
+    }
+    else {
+        messages.push(`Recommended mode: ${recommendedMode}`);
+    }
+    return { apiKeySource, apiKeyValid, cliAvailable, recommendedMode, messages };
+}
+//# sourceMappingURL=auth.js.map

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

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

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

@@ -0,0 +1,49 @@
+/**
+ * CLI provider — calls Claude via the `claude` CLI binary.
+ *
+ * One half of the dual provider architecture. The CLI provider spawns the
+ * Claude Code CLI binary and parses its output (JSON or stream-json format).
+ *
+ * ## When this provider is selected
+ *
+ * - Explicitly via `createClient({ mode: "cli" })`
+ * - As the automatic fallback when no API key is available
+ *
+ * ## Use cases
+ *
+ * - Local development where Claude Code is already installed
+ * - Environments where the CLI handles authentication (OAuth, session tokens)
+ * - When leveraging CLI-specific features (output formats, CLI flags)
+ *
+ * ## Error handling
+ *
+ * Stderr output is classified into error categories (auth, rate-limit, unknown)
+ * with automatic retry on transient failures using exponential backoff with
+ * a configurable maximum delay cap.
+ *
+ * @see {@link createClient} in `create-client.ts` for provider selection logic
+ * @see {@link createApiClient} in `api-provider.ts` for the alternative provider
+ */
+import type { ClaudeClient, ClaudeClientOptions } from "./types.js";
+import type { LLMProvider } from "./provider-interface.js";
+/** Options specific to the CLI provider. */
+export interface CliProviderOptions extends ClaudeClientOptions {
+    /** Maximum number of retries for transient failures (default: 2). */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000). */
+    baseDelayMs?: number;
+    /** Maximum delay in ms for backoff (default: 10000). */
+    maxDelayMs?: number;
+}
+/**
+ * Create a CLI-based Claude client that implements both the legacy
+ * {@link ClaudeClient} interface and the generic {@link LLMProvider} interface.
+ *
+ * Spawns the `claude` binary for each completion request, with automatic
+ * retry on transient failures and exponential backoff.
+ *
+ * Note: The CLI provider does not implement `validateAuth()` because the
+ * Claude CLI authenticates through a browser session that cannot be probed
+ * programmatically without making a real completion request.
+ */
+export declare function createCliClient(options: CliProviderOptions): ClaudeClient & LLMProvider;

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

@@ -0,0 +1,226 @@
+/**
+ * CLI provider — calls Claude via the `claude` CLI binary.
+ *
+ * One half of the dual provider architecture. The CLI provider spawns the
+ * Claude Code CLI binary and parses its output (JSON or stream-json format).
+ *
+ * ## When this provider is selected
+ *
+ * - Explicitly via `createClient({ mode: "cli" })`
+ * - As the automatic fallback when no API key is available
+ *
+ * ## Use cases
+ *
+ * - Local development where Claude Code is already installed
+ * - Environments where the CLI handles authentication (OAuth, session tokens)
+ * - When leveraging CLI-specific features (output formats, CLI flags)
+ *
+ * ## Error handling
+ *
+ * Stderr output is classified into error categories (auth, rate-limit, unknown)
+ * with automatic retry on transient failures using exponential backoff with
+ * a configurable maximum delay cap.
+ *
+ * @see {@link createClient} in `create-client.ts` for provider selection logic
+ * @see {@link createApiClient} in `api-provider.ts` for the alternative provider
+ */
+import { spawn } from "node:child_process";
+import { ClaudeClientError } from "./types.js";
+import { resolveCliPath } from "./config.js";
+import { parseCliTokenUsage, parseStreamTokenUsage } from "./token-usage.js";
+/** Regex patterns for stderr content indicating a missing binary (Windows shell). */
+const NOT_FOUND_PATTERNS = /is not recognized as an internal or external command|cannot find the path|The system cannot find the file specified/i;
+/** Regex patterns for stderr content indicating an auth error. */
+const AUTH_PATTERNS = /auth|unauthorized|api.key|credential|login|not logged in/i;
+/** Regex patterns for stderr content indicating a rate-limit error. */
+const RATE_LIMIT_PATTERNS = /rate.limit|429|too many requests|overloaded/i;
+/** Regex patterns in error messages that indicate a transient failure. */
+const TRANSIENT_PATTERNS = [
+    /\b500\b/,
+    /\b502\b/,
+    /\b503\b/,
+    /\b529\b/,
+    /\b429\b/,
+    /overloaded/i,
+    /ETIMEDOUT/,
+    /ECONNRESET/,
+    /ECONNREFUSED/,
+    /socket hang up/i,
+];
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 10000;
+/**
+ * Classify an error message as retryable or not.
+ */
+function isTransientError(message) {
+    return TRANSIENT_PATTERNS.some((p) => p.test(message));
+}
+/**
+ * Classify stderr content into a structured error reason.
+ */
+function classifyStderr(stderr) {
+    if (AUTH_PATTERNS.test(stderr)) {
+        return { reason: "auth", retryable: false };
+    }
+    if (RATE_LIMIT_PATTERNS.test(stderr)) {
+        return { reason: "rate-limit", retryable: true };
+    }
+    return { reason: "unknown", retryable: isTransientError(stderr) };
+}
+/**
+ * Spawn the Claude CLI once and collect the result.
+ */
+function spawnOnce(cliBinary, request) {
+    return new Promise((resolve, reject) => {
+        const format = request.outputFormat ?? "json";
+        const args = [
+            "-p", "-",
+            "--output-format", format,
+            "--model", request.model,
+            ...(request.cliFlags ?? []),
+        ];
+        // Strip CLAUDECODE so the spawned claude process doesn't think it's
+        // nested inside an interactive Claude Code session (e.g. when the web
+        // server is launched from within Claude Code).
+        const { CLAUDECODE: _, ...cleanEnv } = process.env;
+        const proc = spawn(cliBinary, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32",
+            env: cleanEnv,
+        });
+        proc.stdin.on("error", () => { });
+        proc.stdin.write(request.prompt);
+        proc.stdin.end();
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        proc.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                const pathNote = cliBinary !== "claude"
+                    ? `Claude CLI not found at configured path: ${cliBinary}. Check 'n-dx config claude.cli_path'.`
+                    : "Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-code, or set a custom path: n-dx config claude.cli_path /path/to/claude";
+                reject(new ClaudeClientError(pathNote, "not-found", false));
+            }
+            else {
+                reject(new ClaudeClientError(err.message, "unknown", isTransientError(err.message)));
+            }
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                if (format === "json") {
+                    resolve(parseJsonOutput(stdout));
+                }
+                else {
+                    resolve(parseStreamOutput(stdout));
+                }
+                return;
+            }
+            const detail = stderr.trim() || `claude exited with code ${code}`;
+            // On Windows with shell: true, a missing binary doesn't trigger ENOENT —
+            // cmd.exe spawns fine but exits non-zero with a "not recognized" message.
+            if (NOT_FOUND_PATTERNS.test(detail)) {
+                const pathNote = cliBinary !== "claude"
+                    ? `Claude CLI not found at configured path: ${cliBinary}. Check 'n-dx config claude.cli_path'.`
+                    : "Claude CLI not found. Install it with: npm install -g @anthropic-ai/claude-code, or set a custom path: n-dx config claude.cli_path /path/to/claude";
+                reject(new ClaudeClientError(pathNote, "not-found", false));
+                return;
+            }
+            const classified = classifyStderr(detail);
+            reject(new ClaudeClientError(detail, classified.reason, classified.retryable));
+        });
+    });
+}
+/**
+ * Parse --output-format json envelope: { result: "...", input_tokens, ... }
+ */
+function parseJsonOutput(stdout) {
+    try {
+        const envelope = JSON.parse(stdout);
+        const text = typeof envelope.result === "string" ? envelope.result : stdout;
+        const tokenUsage = parseCliTokenUsage(envelope);
+        return { text, tokenUsage };
+    }
+    catch {
+        return { text: stdout };
+    }
+}
+/**
+ * Parse --output-format stream-json: newline-delimited JSON events.
+ * Looks for a { type: "result" } event.
+ */
+function parseStreamOutput(stdout) {
+    let resultText = "";
+    let tokenUsage;
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            if (obj.type === "result") {
+                resultText = typeof obj.result === "string" ? obj.result : "";
+                tokenUsage = parseStreamTokenUsage(obj);
+            }
+        }
+        catch {
+            // Skip unparseable lines
+        }
+    }
+    return { text: resultText, tokenUsage };
+}
+/**
+ * Create a CLI-based Claude client that implements both the legacy
+ * {@link ClaudeClient} interface and the generic {@link LLMProvider} interface.
+ *
+ * Spawns the `claude` binary for each completion request, with automatic
+ * retry on transient failures and exponential backoff.
+ *
+ * Note: The CLI provider does not implement `validateAuth()` because the
+ * Claude CLI authenticates through a browser session that cannot be probed
+ * programmatically without making a real completion request.
+ */
+export function createCliClient(options) {
+    const cliBinary = resolveCliPath(options.claudeConfig);
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const info = {
+        vendor: "claude",
+        mode: "cli",
+        ...(options.claudeConfig.model ? { model: options.claudeConfig.model } : {}),
+        capabilities: [],
+    };
+    return {
+        // ── LLMProvider ──────────────────────────────────────────────────────
+        info,
+        // ── ClaudeClient (backward compat) ───────────────────────────────────
+        mode: "cli",
+        async complete(request) {
+            let lastError;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    return await spawnOnce(cliBinary, request);
+                }
+                catch (err) {
+                    lastError = err;
+                    // Don't retry non-retryable errors
+                    if (err instanceof ClaudeClientError && !err.retryable) {
+                        throw err;
+                    }
+                    // Don't retry on last attempt
+                    if (attempt < maxRetries) {
+                        const delay = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+                        await new Promise((r) => setTimeout(r, delay));
+                    }
+                }
+            }
+            throw lastError;
+        },
+    };
+}
+//# sourceMappingURL=cli-provider.js.map

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

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

package/packages/llm-client/dist/codex-cli-provider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Codex CLI provider — calls Codex via the `codex exec` command.
+ *
+ * This provider implements the same client contract used by Claude providers:
+ * a `complete()` method returning plain text and optional token usage.
+ */
+import type { ClaudeClient } from "./types.js";
+import type { CodexConfig } from "./llm-types.js";
+export interface CodexCliProviderOptions {
+    codexConfig?: CodexConfig;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export declare function createCodexCliClient(options: CodexCliProviderOptions): ClaudeClient;