@cruxy/cli 0.6.0 → 0.8.0

package/dist/cli/commands/run.js

@@ -1,20 +1,18 @@
 import { Command } from "commander";
 import pc from "picocolors";
-import { createProvider } from "@cruxy/sdk";
 import { logger } from "../../utils/logger.js";
-import { loadConfig, resolveApiKey, loadProjectInstructions, } from "../../config/index.js";
+import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, usageError } from "../../errors/index.js";
-import { ApprovalService } from "../../approval/index.js";
-import { buildDefaultRegistry } from "../../tools/index.js";
-import { Session } from "../../agent/index.js";
+import { createRenderer } from "../../render/index.js";
 import { runInteractive } from "../repl.js";
-import { createStreamPrinter } from "../stream-print.js";
-import { getGitInfo } from "../../utils/git.js";
+import { buildAgentSession } from "../session-factory.js";
+import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
     return new Command("run")
         .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
-        .action(async (promptParts) => {
+        .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
+        .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const interactive = prompt === "";
         // No prompt and stdin isn't a terminal: there's no way to read input and
@@ -23,71 +21,57 @@ export function runCommand() {
             throw usageError("cruxy run needs a prompt when stdin is not a terminal", ['provide a task, e.g. cruxy run "fix the failing test"']);
         }
         const { config, sources } = loadConfig();
-        const apiKey = resolveApiKey(config.model.provider);
+        let apiKey = resolveApiKey(config.model.provider);
         logger.info(pc.dim(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(pc.dim(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+        // First-run with no key (and a TTY) → guided onboarding instead of the
+        // dead-end auth error. The first-win demo is offered only in the no-prompt
+        // (REPL) path; with a real prompt, that prompt IS the first win.
         if (!apiKey) {
-            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            const onboarding = maybeRunOnboarding(config, {
+                ttyInteractive: Boolean(process.stdin.isTTY),
+                offerFirstWin: interactive,
+                cwd: process.cwd(),
+            });
+            if (onboarding === null) {
+                // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
+                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            }
+            const result = await onboarding;
+            if (!result.completed) {
+                // Aborted/failed mid-setup — guidance already shown; exit cleanly.
+                logger.print(pc.dim("run `cruxy login` to finish setup."));
+                return;
+            }
+            apiKey = result.apiKey ?? resolveApiKey(config.model.provider);
+            if (!apiKey) {
+                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            }
         }
-        const provider = createProvider({
-            provider: config.model.provider,
-            apiKey,
-            model: config.model.model,
-            maxTokens: config.model.maxTokens,
-            temperature: config.model.temperature,
-            gatewayUrl: config.cruxy.gatewayUrl,
-        });
-        const registry = buildDefaultRegistry();
-        // The approval gate. Default-deny, risk-tiered, scoped session allowlist;
-        // no global skip flag (the policy seam lives in src/approval). When stdin
-        // isn't a TTY, a side-effecting action fails with CRUXY_E_APPROVAL_REQUIRED
-        // rather than being auto-approved.
-        const approval = new ApprovalService({
-            cwd: process.cwd(),
-            interactive: Boolean(process.stdin.isTTY),
-        });
-        const ctx = {
-            cwd: process.cwd(),
-            config,
-            logger,
-            requestApproval: (action) => approval.requestApproval(action),
-        };
-        const projectInstructions = loadProjectInstructions(process.cwd());
-        const git = getGitInfo(process.cwd());
-        const session = new Session({
-            provider,
-            registry,
-            config,
-            ctx,
-            git,
-            projectInstructions,
-        });
+        // Plan mode is opt-in: --plan flag overrides the config default.
+        const planMode = opts.plan ?? config.agent.planMode;
+        // One renderer for the whole run (U.2): the streaming path and the
+        // approval prompt's status-suspend hook must share the same live region.
+        const renderer = createRenderer();
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer);
         if (interactive) {
-            await runInteractive(session);
+            await runInteractive(session, undefined, renderer);
             return;
         }
         // One-shot: a single turn, then exit. Preserves scripting/pipe use.
-        // Assistant text streams to stdout delta by delta (same as the REPL),
-        // through a printer that trims the model's leading blank lines; the agent
-        // loop terminates the line.
+        // Assistant text streams to stdout delta by delta (same as the REPL);
+        // piped output degrades to the plain renderer (no ANSI, chrome on stderr).
         logger.print(`${pc.cyan("cruxy")} ${pc.dim("›")} ${prompt}\n`);
         // Provider/network/auth failures propagate to the top-level boundary,
         // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
         // the matching code — a one-shot run must fail non-zero on error.
-        const print = createStreamPrinter((text) => process.stdout.write(text));
-        const result = await session.send(prompt, print);
-        logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
-            `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        try {
+            const result = await session.send(prompt, renderer);
+            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        }
+        finally {
+            renderer.close();
+        }
     });
 }
-/** Environment variable that holds the API key for a provider. */
-function apiKeyEnvVar(provider) {
-    switch (provider) {
-        case "anthropic":
-            return "ANTHROPIC_API_KEY";
-        case "openai":
-            return "OPENAI_API_KEY";
-        default:
-            return "CRUXY_API_KEY";
-    }
-}

package/dist/cli/onboard.d.ts

@@ -0,0 +1,25 @@
+import type { CruxyConfig } from "../config/index.js";
+import { type OnboardingResult } from "../onboarding/index.js";
+/**
+ * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
+ * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
+ * the production wiring (live validation, credential persistence, first-win run).
+ */
+/** The env var that holds the key for a provider (for the fail-loud message). */
+export declare function apiKeyEnvVar(provider: string): string;
+/** Run one first-win task end-to-end against the just-saved key. */
+export declare function runFirstWinTask(config: CruxyConfig, cwd: string, prompt: string): Promise<void>;
+export interface MaybeOnboardOptions {
+    /** Whether stdin is a TTY (the gate). */
+    ttyInteractive: boolean;
+    /** Offer the first-win demo run (no real task queued). */
+    offerFirstWin: boolean;
+    cwd: string;
+}
+/**
+ * Run the guided first-run flow **iff** this is a first run; otherwise return
+ * `null` so the caller can fall back (fail loud, or show a banner). Never throws
+ * for an aborted setup — `result.completed` is `false` and the caller exits
+ * cleanly.
+ */
+export declare function maybeRunOnboarding(config: CruxyConfig, opts: MaybeOnboardOptions): Promise<OnboardingResult> | null;

package/dist/cli/onboard.js

@@ -0,0 +1,59 @@
+import { resolveApiKey } from "../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
+import { createRenderer } from "../render/index.js";
+import { buildAgentSession } from "./session-factory.js";
+/**
+ * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
+ * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
+ * the production wiring (live validation, credential persistence, first-win run).
+ */
+/** The env var that holds the key for a provider (for the fail-loud message). */
+export function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}
+/** Run one first-win task end-to-end against the just-saved key. */
+export async function runFirstWinTask(config, cwd, prompt) {
+    const apiKey = resolveApiKey(config.model.provider);
+    if (!apiKey)
+        return; // defensive — the key was just persisted
+    const renderer = createRenderer();
+    const session = buildAgentSession(config, apiKey, cwd, true, false, renderer);
+    try {
+        await session.send(prompt, renderer);
+    }
+    finally {
+        renderer.close();
+    }
+}
+/**
+ * Run the guided first-run flow **iff** this is a first run; otherwise return
+ * `null` so the caller can fall back (fail loud, or show a banner). Never throws
+ * for an aborted setup — `result.completed` is `false` and the caller exits
+ * cleanly.
+ */
+export function maybeRunOnboarding(config, opts) {
+    const provider = config.model.provider;
+    if (!isFirstRun({ provider, interactive: opts.ttyInteractive }))
+        return null;
+    const deps = createDefaultDeps({
+        config,
+        cwd: opts.cwd,
+        runTask: opts.offerFirstWin
+            ? (prompt) => runFirstWinTask(config, opts.cwd, prompt)
+            : undefined,
+    });
+    return runOnboarding({
+        provider,
+        mode: "first-run",
+        offerFirstWin: opts.offerFirstWin,
+        io: defaultOnboardingIO(),
+        deps,
+    });
+}

package/dist/cli/program.js

@@ -8,6 +8,10 @@ import { configCommand } from "./commands/config.js";
 import { indexCommand } from "./commands/index.js";
 import { skillsCommand } from "./commands/skills.js";
 import { prCommand } from "./commands/pr.js";
+import { loginCommand } from "./commands/login.js";
+import { initCommand } from "./commands/init.js";
+import { loadConfig } from "../config/index.js";
+import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -30,15 +34,29 @@ export function buildProgram() {
     program.addCommand(indexCommand());
     program.addCommand(skillsCommand());
     program.addCommand(prCommand());
+    program.addCommand(loginCommand());
+    program.addCommand(initCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.
-    program.action((_opts, command) => {
+    program.action(async (_opts, command) => {
         if (command.args.length > 0) {
             throw usageError(`unknown command: ${command.args[0]}`, [
                 "run `cruxy --help` to see available commands",
             ]);
         }
+        // First-run with no key (and a TTY) → guided setup, with the first-win demo.
+        // Otherwise fall through to the banner (an already-set-up user, or non-TTY).
+        const { config } = loadConfig();
+        const onboarding = maybeRunOnboarding(config, {
+            ttyInteractive: Boolean(process.stdin.isTTY),
+            offerFirstWin: true,
+            cwd: process.cwd(),
+        });
+        if (onboarding) {
+            await onboarding;
+            return;
+        }
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));
         logger.print(pc.dim("an agentic coding CLI\n"));
         logger.print("The interactive REPL lands in C.3 (terminal UI).");

package/dist/cli/repl.d.ts

@@ -1,5 +1,6 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
+import { type StreamRenderer } from "../render/index.js";
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;
@@ -7,9 +8,13 @@ export interface ReplIO {
 }
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
- * commands or run a turn, repeat. Assistant text streams to stdout from within
- * `session.send` (via the logger); this loop only owns input and control.
+ * commands or run a turn, repeat. Assistant text and tool-call progress stream
+ * through the `renderer` from within `session.send`; this loop only owns input
+ * and control.
  *
- * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair. The
+ * renderer defaults to whatever `io.output` supports (a TTY gets the managed
+ * live region, anything else the plain append-only renderer); `cruxy run`
+ * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export declare function runInteractive(session: Session, io?: ReplIO): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer): Promise<void>;

package/dist/cli/repl.js

@@ -1,14 +1,15 @@
 import readline from "node:readline";
 import pc from "picocolors";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
+import { createRenderer } from "../render/index.js";
 import { logger } from "../utils/logger.js";
-import { createStreamPrinter } from "./stream-print.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
 const HELP = `Commands:
   /help          show this help
   /clear         clear the conversation history (keep the session)
   /compact       summarize older history to free up context now
   /reload        re-read project instructions (CRUXY.md)
+  /plan          toggle plan mode (propose a plan before executing)
   /exit, /quit   leave cruxy
   Ctrl+D         leave cruxy`;
 const defaultIO = () => ({
@@ -64,13 +65,25 @@ function printReplError(err) {
 }
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
- * commands or run a turn, repeat. Assistant text streams to stdout from within
- * `session.send` (via the logger); this loop only owns input and control.
+ * commands or run a turn, repeat. Assistant text and tool-call progress stream
+ * through the `renderer` from within `session.send`; this loop only owns input
+ * and control.
  *
- * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair. The
+ * renderer defaults to whatever `io.output` supports (a TTY gets the managed
+ * live region, anything else the plain append-only renderer); `cruxy run`
+ * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export async function runInteractive(session, io = defaultIO()) {
+export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr)) {
     logger.print(pc.dim("interactive session — /help for commands, /exit or Ctrl+D to quit"));
+    try {
+        await replLoop(session, io, renderer);
+    }
+    finally {
+        renderer.close();
+    }
+}
+async function replLoop(session, io, renderer) {
     for (;;) {
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
@@ -107,18 +120,25 @@ export async function runInteractive(session, io = defaultIO()) {
                 : "no project instructions found"));
             continue;
         }
+        if (trimmed === "/plan") {
+            session.setPlanMode(!session.getPlanMode());
+            const on = session.getPlanMode();
+            logger.print(pc.dim(on
+                ? "plan mode on — the next prompt proposes a plan for approval"
+                : "plan mode off"));
+            continue;
+        }
         if (trimmed === "/help") {
             logger.print(HELP);
             continue;
         }
-        // A real turn. Assistant text streams to the output delta by delta through a
-        // single printer (which trims the model's leading blank lines); the agent
-        // loop closes the segment with one newline, so the next prompt lands on its
-        // own line. Errors (provider/API failures) log and return to the prompt
-        // rather than killing the REPL.
+        // A real turn. Assistant text streams through the renderer delta by delta
+        // (leading blank lines trimmed, code fences highlighted); the agent loop
+        // closes each segment with one newline, so the next prompt lands on its own
+        // line. Errors (provider/API failures) log and return to the prompt rather
+        // than killing the REPL.
         try {
-            const print = createStreamPrinter((text) => io.output.write(text));
-            await session.send(line, print);
+            await session.send(line, renderer);
         }
         catch (err) {
             logger.error(err.message);

package/dist/cli/session-factory.d.ts

@@ -0,0 +1,13 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
+import { Session } from "../agent/index.js";
+/**
+ * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
+ * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
+ * The approval gate's interactivity tracks the TTY, exactly as in `run`.
+ *
+ * When `planMode` is on (C.31), it additionally wires a {@link PlanExecutionPolicy}
+ * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
+ * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
+ */
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer): Session;

package/dist/cli/session-factory.js

@@ -0,0 +1,109 @@
+import { createProvider } from "@cruxy/sdk";
+import { loadProjectInstructions } from "../config/index.js";
+import { logger } from "../utils/logger.js";
+import { getGitInfo } from "../utils/git.js";
+import { ApprovalService, InteractivePolicy, SessionAllowlist, defaultPromptIO, } from "../approval/index.js";
+import { shouldUseColor } from "../errors/index.js";
+import { buildDefaultRegistry } from "../tools/index.js";
+import { Session } from "../agent/index.js";
+import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
+/**
+ * Wrap a PromptIO so the renderer's transient status line is erased before any
+ * prompt text lands (U.2): the approval prompt writes to stderr while the
+ * spinner owns the last stdout row of the same terminal — clearing first keeps
+ * the prompt from tearing through the live region.
+ */
+function suspendStatusOnPrompt(io, renderer) {
+    if (!renderer)
+        return io;
+    return {
+        ...io,
+        write: (text) => {
+            renderer.status(null);
+            io.write(text);
+        },
+    };
+}
+/**
+ * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
+ * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
+ * The approval gate's interactivity tracks the TTY, exactly as in `run`.
+ *
+ * When `planMode` is on (C.31), it additionally wires a {@link PlanExecutionPolicy}
+ * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
+ * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
+ */
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer) {
+    const provider = createProvider({
+        provider: config.model.provider,
+        apiKey,
+        model: config.model.model,
+        maxTokens: config.model.maxTokens,
+        temperature: config.model.temperature,
+        gatewayUrl: config.cruxy.gatewayUrl,
+    });
+    const execRegistry = buildDefaultRegistry();
+    const git = getGitInfo(cwd);
+    const projectInstructions = loadProjectInstructions(cwd);
+    if (planMode) {
+        // One io + allowlist shared by the plan-approval prompt and the per-action
+        // gate, so a grant recorded during execution is honored by U.3's own check.
+        const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
+        const allowlist = new SessionAllowlist();
+        const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io));
+        const approval = new ApprovalService({
+            cwd,
+            interactive: ttyInteractive,
+            policy: planPolicy,
+            io,
+        });
+        const ctx = {
+            cwd,
+            config,
+            logger,
+            requestApproval: (action) => approval.requestApproval(action),
+        };
+        const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
+            provider,
+            config,
+            ctx,
+            execRegistry,
+            planPolicy,
+            io,
+            interactive: ttyInteractive,
+            messages,
+            git,
+            projectInstructions,
+            renderer: turnRenderer,
+        });
+        return new Session({
+            provider,
+            registry: execRegistry,
+            config,
+            ctx,
+            git,
+            projectInstructions,
+            planMode: true,
+            planRunner,
+        });
+    }
+    const approval = new ApprovalService({
+        cwd,
+        interactive: ttyInteractive,
+        io: suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer),
+    });
+    const ctx = {
+        cwd,
+        config,
+        logger,
+        requestApproval: (action) => approval.requestApproval(action),
+    };
+    return new Session({
+        provider,
+        registry: execRegistry,
+        config,
+        ctx,
+        git,
+        projectInstructions,
+    });
+}

package/dist/config/credentials.d.ts

@@ -0,0 +1,10 @@
+/** `~/.cruxy/credentials.json` */
+export declare function credentialsPath(): string;
+/** The stored key for `provider`, or `undefined`. Never throws. */
+export declare function readCredential(provider: string, file?: string): string | undefined;
+/**
+ * Persist `key` for `provider`, merging into any existing store. The file is
+ * written `0600` and its directory `0700` so the secret is owner-only — enforced
+ * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ */
+export declare function writeCredential(provider: string, key: string, file?: string): void;

package/dist/config/credentials.js

@@ -0,0 +1,69 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { CREDENTIALS_FILE_NAME } from "../constants.js";
+import { globalDir } from "./paths.js";
+/**
+ * The credentials store (U.6) — the one place a provider API key is persisted.
+ * It lives **outside** `config.json` on purpose: config is secret-free by design
+ * ("the API key comes from env"), so secrets get their own file with restrictive
+ * permissions (`0600`, dir `0700`), the same shape as gh/aws/npm. `resolveApiKey`
+ * reads it as a fallback after the environment.
+ */
+/** Bumped if the on-disk shape ever changes. */
+const CREDENTIALS_VERSION = 1;
+/** `~/.cruxy/credentials.json` */
+export function credentialsPath() {
+    return join(globalDir(), CREDENTIALS_FILE_NAME);
+}
+/** Parse the store at `file`, or `null` if absent/unreadable/malformed. */
+function readStore(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed &&
+            typeof parsed === "object" &&
+            "keys" in parsed &&
+            typeof parsed.keys === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // A corrupt store is treated as absent — onboarding can rewrite it.
+    }
+    return null;
+}
+/** The stored key for `provider`, or `undefined`. Never throws. */
+export function readCredential(provider, file = credentialsPath()) {
+    const store = readStore(file);
+    const key = store?.keys[provider];
+    return typeof key === "string" && key !== "" ? key : undefined;
+}
+/**
+ * Persist `key` for `provider`, merging into any existing store. The file is
+ * written `0600` and its directory `0700` so the secret is owner-only — enforced
+ * with an explicit `chmod` after write (mkdir/write modes are umask-masked).
+ */
+export function writeCredential(provider, key, file = credentialsPath()) {
+    const dir = dirname(file);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best-effort on platforms without POSIX modes (e.g. Windows).
+    }
+    const store = readStore(file) ?? { version: CREDENTIALS_VERSION, keys: {} };
+    store.version = CREDENTIALS_VERSION;
+    store.keys[provider] = key;
+    writeFileSync(file, JSON.stringify(store, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Best-effort (see above).
+    }
+}

package/dist/config/index.d.ts

@@ -2,3 +2,4 @@ export * from "./schema.js";
 export * from "./paths.js";
 export * from "./manager.js";
 export * from "./project.js";
+export * from "./credentials.js";

package/dist/config/index.js

@@ -2,3 +2,4 @@ export * from "./schema.js";
 export * from "./paths.js";
 export * from "./manager.js";
 export * from "./project.js";
+export * from "./credentials.js";

package/dist/config/manager.d.ts

@@ -30,5 +30,10 @@ export declare function initConfig(file: string): {
     path: string;
     created: boolean;
 };
-/** Provider API key, read from the environment only (never persisted). */
+/**
+ * Provider API key, resolved **env → credentials store → undefined**. The
+ * environment always wins (CI / one-off overrides); the credentials store
+ * (`~/.cruxy/credentials.json`, written by onboarding / `cruxy login`) is the
+ * persistent fallback. The key is never read from `config.json`.
+ */
 export declare function resolveApiKey(provider: string): string | undefined;

package/dist/config/manager.js

@@ -3,6 +3,7 @@ import { dirname } from "node:path";
 import { configInvalid, configParse } from "../errors/index.js";
 import { CruxyConfigSchema } from "./schema.js";
 import { globalConfigPath, findProjectConfig } from "./paths.js";
+import { readCredential } from "./credentials.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -137,8 +138,17 @@ export function initConfig(file) {
     writeFileSync(file, JSON.stringify(defaults, null, 2) + "\n", "utf8");
     return { path: file, created: true };
 }
-/** Provider API key, read from the environment only (never persisted). */
+/**
+ * Provider API key, resolved **env → credentials store → undefined**. The
+ * environment always wins (CI / one-off overrides); the credentials store
+ * (`~/.cruxy/credentials.json`, written by onboarding / `cruxy login`) is the
+ * persistent fallback. The key is never read from `config.json`.
+ */
 export function resolveApiKey(provider) {
+    return envApiKey(provider) ?? readCredential(provider);
+}
+/** The API key from the environment for `provider`, or `undefined`. */
+function envApiKey(provider) {
     switch (provider) {
         case "cruxy":
             return process.env.CRUXY_API_KEY;