@cruxy/cli 0.6.0 → 0.7.0

package/dist/cli/session-factory.js

@@ -0,0 +1,88 @@
+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";
+/**
+ * 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) {
+    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 = defaultPromptIO(shouldUseColor());
+        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, onText, }) => runPlanSession({
+            provider,
+            config,
+            ctx,
+            execRegistry,
+            planPolicy,
+            io,
+            interactive: ttyInteractive,
+            messages,
+            git,
+            projectInstructions,
+            onText,
+        });
+        return new Session({
+            provider,
+            registry: execRegistry,
+            config,
+            ctx,
+            git,
+            projectInstructions,
+            planMode: true,
+            planRunner,
+        });
+    }
+    const approval = new ApprovalService({ cwd, interactive: ttyInteractive });
+    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;

package/dist/config/schema.d.ts

@@ -30,12 +30,16 @@ export declare const AgentConfigSchema: z.ZodObject<{
     maxIterations: z.ZodDefault<z.ZodNumber>;
     /** Skip per-action confirmation prompts. */
     autoApprove: z.ZodDefault<z.ZodBoolean>;
+    /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
+    planMode: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     maxIterations: number;
     autoApprove: boolean;
+    planMode: boolean;
 }, {
     maxIterations?: number | undefined;
     autoApprove?: boolean | undefined;
+    planMode?: boolean | undefined;
 }>;
 export declare const ToolsConfigSchema: z.ZodObject<{
     fileEdit: z.ZodDefault<z.ZodBoolean>;
@@ -242,12 +246,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         maxIterations: z.ZodDefault<z.ZodNumber>;
         /** Skip per-action confirmation prompts. */
         autoApprove: z.ZodDefault<z.ZodBoolean>;
+        /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
+        planMode: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         maxIterations: number;
         autoApprove: boolean;
+        planMode: boolean;
     }, {
         maxIterations?: number | undefined;
         autoApprove?: boolean | undefined;
+        planMode?: boolean | undefined;
     }>>;
     tools: z.ZodDefault<z.ZodObject<{
         fileEdit: z.ZodDefault<z.ZodBoolean>;
@@ -428,6 +436,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     agent: {
         maxIterations: number;
         autoApprove: boolean;
+        planMode: boolean;
     };
     tools: {
         fileEdit: boolean;
@@ -485,6 +494,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     agent?: {
         maxIterations?: number | undefined;
         autoApprove?: boolean | undefined;
+        planMode?: boolean | undefined;
     } | undefined;
     tools?: {
         fileEdit?: boolean | undefined;

package/dist/config/schema.js

@@ -28,6 +28,8 @@ export const AgentConfigSchema = z
     maxIterations: z.number().int().positive().default(25),
     /** Skip per-action confirmation prompts. */
     autoApprove: z.boolean().default(false),
+    /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
+    planMode: z.boolean().default(false),
 })
     .strict();
 export const ToolsConfigSchema = z

package/dist/constants.d.ts

@@ -5,6 +5,12 @@ export declare const APP_DESCRIPTION: string;
 /** Directory/file names cruxy looks for. */
 export declare const GLOBAL_DIR_NAME = ".cruxy";
 export declare const CONFIG_FILE_NAME = "config.json";
+/** Secret store under the global dir — `0600`, never holds non-secret config. */
+export declare const CREDENTIALS_FILE_NAME = "credentials.json";
+/** Onboarding state + completion marker under the global dir (U.6). */
+export declare const ONBOARDING_FILE_NAME = "onboarding.json";
+/** Where a user creates a Cruxy gateway key (printed during onboarding). */
+export declare const CREATE_KEY_URL = "https://app.cruxy.in";
 /** Project-level config filenames, checked in order. */
 export declare const PROJECT_CONFIG_FILENAMES: string[];
 /** Project-instruction filenames, checked in order (first match wins). */

package/dist/constants.js

@@ -22,6 +22,12 @@ export const APP_DESCRIPTION = pkg.description ?? "an agentic coding CLI";
 /** Directory/file names cruxy looks for. */
 export const GLOBAL_DIR_NAME = ".cruxy";
 export const CONFIG_FILE_NAME = "config.json";
+/** Secret store under the global dir — `0600`, never holds non-secret config. */
+export const CREDENTIALS_FILE_NAME = "credentials.json";
+/** Onboarding state + completion marker under the global dir (U.6). */
+export const ONBOARDING_FILE_NAME = "onboarding.json";
+/** Where a user creates a Cruxy gateway key (printed during onboarding). */
+export const CREATE_KEY_URL = "https://app.cruxy.in";
 /** Project-level config filenames, checked in order. */
 export const PROJECT_CONFIG_FILENAMES = [
     "cruxy.config.json",

package/dist/errors/constructors.d.ts

@@ -43,6 +43,16 @@ export declare function forgeApi(title: string, underlying?: unknown, meta?: Rec
  * `--no-verify`, so the underlying reason is surfaced verbatim.
  */
 export declare function gitPushFailed(branch: string, stderr?: string): CruxyError;
+/** The agent's proposed plan was missing or malformed (plan mode, C.31). */
+export declare function planInvalid(reason: string): CruxyError;
+/** The plan was rejected too many times without converging (plan mode, C.31). */
+export declare function planRevisionLimit(limit: number): CruxyError;
+/**
+ * Plan mode needs interactive approval but cruxy is running non-interactively.
+ * Default-deny — a plan is never auto-approved. Distinct code (exit 10) so CI can
+ * tell it apart from a per-action approval requirement.
+ */
+export declare function planApprovalRequired(): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -72,9 +72,10 @@ export function authMissingKey(provider, envVar) {
     return new CruxyError({
         code: ErrorCode.AuthMissingKey,
         title: `no API key for provider "${provider}"`,
-        cause: `the ${envVar} environment variable is not set`,
+        cause: `no key in the environment (${envVar}) or the credentials store`,
         nextSteps: [
-            `export ${envVar}=… in your shell (keys are read from the environment, never from config)`,
+            "run `cruxy login` to set a key interactively (saved to ~/.cruxy, owner-only)",
+            `or export ${envVar}=… in your shell (env always wins; never written to config)`,
         ],
         meta: { provider, envVar },
     });
@@ -291,6 +292,49 @@ export function gitPushFailed(branch, stderr) {
         meta: { branch },
     });
 }
+// ── plan mode (exit 2 / 10) ───────────────────────────────────────────────────
+/** The agent's proposed plan was missing or malformed (plan mode, C.31). */
+export function planInvalid(reason) {
+    return new CruxyError({
+        code: ErrorCode.PlanInvalid,
+        title: "the agent did not produce a valid plan",
+        cause: reason,
+        nextSteps: [
+            "retry the task — the model must call `submit_plan` with at least one step",
+            "or run without `--plan` to execute directly",
+        ],
+        meta: { reason },
+    });
+}
+/** The plan was rejected too many times without converging (plan mode, C.31). */
+export function planRevisionLimit(limit) {
+    return new CruxyError({
+        code: ErrorCode.PlanRevisionLimit,
+        title: `plan not approved after ${limit} revision${limit === 1 ? "" : "s"}`,
+        cause: "the revision limit was reached without an approved plan",
+        nextSteps: [
+            "restate the task more concretely, or split it into smaller tasks",
+            "run without `--plan` to execute directly",
+        ],
+        meta: { limit },
+    });
+}
+/**
+ * Plan mode needs interactive approval but cruxy is running non-interactively.
+ * Default-deny — a plan is never auto-approved. Distinct code (exit 10) so CI can
+ * tell it apart from a per-action approval requirement.
+ */
+export function planApprovalRequired() {
+    return new CruxyError({
+        code: ErrorCode.PlanApprovalRequired,
+        title: "plan mode needs your approval, but cruxy is running non-interactively",
+        cause: "a plan can only be approved in an interactive terminal",
+        nextSteps: [
+            "run cruxy in an interactive terminal to review and approve the plan",
+            "or drop `--plan` (and `agent.planMode`) to execute directly",
+        ],
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -17,6 +17,8 @@ export declare const ErrorCode: {
     readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
     readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
     readonly GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH";
+    readonly PlanInvalid: "CRUXY_E_PLAN_INVALID";
+    readonly PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT";
     readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
     readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
     readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
@@ -38,6 +40,7 @@ export declare const ErrorCode: {
     readonly SkillInvalid: "CRUXY_E_SKILL_INVALID";
     readonly SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND";
     readonly ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED";
+    readonly PlanApprovalRequired: "CRUXY_E_PLAN_APPROVAL_REQUIRED";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -19,6 +19,8 @@ export const ErrorCode = {
     ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
     ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
     GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH",
+    PlanInvalid: "CRUXY_E_PLAN_INVALID",
+    PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT",
     // config (exit 3)
     ConfigParse: "CRUXY_E_CONFIG_PARSE",
     ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
@@ -48,6 +50,7 @@ export const ErrorCode = {
     SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND",
     // approval (exit 10)
     ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED",
+    PlanApprovalRequired: "CRUXY_E_PLAN_APPROVAL_REQUIRED",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -59,6 +62,8 @@ const EXIT_CODES = {
     [ErrorCode.ConfigKeyUnknown]: 2,
     [ErrorCode.ProviderUnsupported]: 2,
     [ErrorCode.GitProtectedBranch]: 2,
+    [ErrorCode.PlanInvalid]: 2,
+    [ErrorCode.PlanRevisionLimit]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
@@ -80,6 +85,7 @@ const EXIT_CODES = {
     [ErrorCode.SkillInvalid]: 9,
     [ErrorCode.SkillNotFound]: 9,
     [ErrorCode.ApprovalRequired]: 10,
+    [ErrorCode.PlanApprovalRequired]: 10,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/onboarding/detect.d.ts

@@ -0,0 +1,26 @@
+import type { OnboardingState } from "./types.js";
+/** `~/.cruxy/onboarding.json` */
+export declare function onboardingStatePath(): string;
+/** Read persisted onboarding state, or `null` if absent/unreadable. */
+export declare function readOnboardingState(file?: string): OnboardingState | null;
+/** Persist onboarding state (creates `~/.cruxy` if needed). */
+export declare function writeOnboardingState(state: OnboardingState, file?: string): void;
+/** A fresh state object. */
+export declare function newOnboardingState(): OnboardingState;
+/** Whether onboarding has been completed (the marker exists). */
+export declare function onboardingCompleted(file?: string): boolean;
+export interface FirstRunInput {
+    readonly provider: string;
+    /** Whether stdin is a TTY (the gate — non-TTY is never first-run). */
+    readonly interactive: boolean;
+    /** Override key resolution (tests); defaults to {@link resolveApiKey}. */
+    readonly resolveKey?: (provider: string) => string | undefined;
+    /** Override completion check (tests); defaults to {@link onboardingCompleted}. */
+    readonly completed?: () => boolean;
+}
+/**
+ * True iff we should launch the guided first-run flow: interactive **and** no
+ * resolvable key **and** no completion marker. Any one being false means we do
+ * not onboard (non-TTY fails loud elsewhere; a marker means "don't nag again").
+ */
+export declare function isFirstRun(input: FirstRunInput): boolean;

package/dist/onboarding/detect.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ONBOARDING_FILE_NAME } from "../constants.js";
+import { globalDir, resolveApiKey } from "../config/index.js";
+/**
+ * First-run detection + onboarding-state persistence (U.6). "First run" is
+ * deliberately derived from observable facts (no key + no completion marker)
+ * rather than a flag, and is **TTY-gated** so a non-interactive run never
+ * branches into an interactive flow.
+ */
+const ONBOARDING_VERSION = 1;
+/** `~/.cruxy/onboarding.json` */
+export function onboardingStatePath() {
+    return join(globalDir(), ONBOARDING_FILE_NAME);
+}
+/** Read persisted onboarding state, or `null` if absent/unreadable. */
+export function readOnboardingState(file = onboardingStatePath()) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        // A corrupt marker is treated as absent — onboarding can rewrite it.
+    }
+    return null;
+}
+/** Persist onboarding state (creates `~/.cruxy` if needed). */
+export function writeOnboardingState(state, file = onboardingStatePath()) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+/** A fresh state object. */
+export function newOnboardingState() {
+    return { version: ONBOARDING_VERSION };
+}
+/** Whether onboarding has been completed (the marker exists). */
+export function onboardingCompleted(file = onboardingStatePath()) {
+    return Boolean(readOnboardingState(file)?.completedAt);
+}
+/**
+ * True iff we should launch the guided first-run flow: interactive **and** no
+ * resolvable key **and** no completion marker. Any one being false means we do
+ * not onboard (non-TTY fails loud elsewhere; a marker means "don't nag again").
+ */
+export function isFirstRun(input) {
+    if (!input.interactive)
+        return false;
+    const resolveKey = input.resolveKey ?? resolveApiKey;
+    if (resolveKey(input.provider))
+        return false;
+    const completed = input.completed ?? onboardingCompleted;
+    return !completed();
+}

package/dist/onboarding/flow.d.ts

@@ -0,0 +1,28 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { OnboardingDeps, OnboardingOptions, OnboardingResult, ValidationOutcome } from "./types.js";
+/**
+ * Orchestrate the onboarding steps (U.6) — resumable and idempotent. The key
+ * step is skipped when a key already resolves; the completion marker is written
+ * only once a key is in place. An abort during the (mandatory) key step returns
+ * `{ aborted: true }` and writes **no** marker, so it resumes next time.
+ */
+export declare function runOnboarding(opts: OnboardingOptions): Promise<OnboardingResult>;
+/** Dependencies for the default (production) wiring. */
+export interface DefaultDepsOptions {
+    config: CruxyConfig;
+    cwd: string;
+    /** Runs the first-win task; omit to disable that step. */
+    runTask?: (prompt: string) => Promise<void>;
+}
+/**
+ * Build the production {@link OnboardingDeps}: live gateway validation, the
+ * credentials store, real state persistence, and a wall-clock timestamp.
+ */
+export declare function createDefaultDeps(opts: DefaultDepsOptions): OnboardingDeps;
+/**
+ * Validate a key with one cheap live call: start a 1-token stream and look at the
+ * first event. `AuthError` ⇒ invalid (bad key), `NetworkError` ⇒ unreachable;
+ * anything else (a token, rate-limit, transient API error) means the key was
+ * accepted, so ⇒ valid.
+ */
+export declare function validateKeyLive(provider: string, apiKey: string, config: CruxyConfig): Promise<ValidationOutcome>;

package/dist/onboarding/flow.js

@@ -0,0 +1,100 @@
+import { AuthError, NetworkError, createProvider } from "@cruxy/sdk";
+import pc from "picocolors";
+import { resolveApiKey, writeCredential } from "../config/index.js";
+import { newOnboardingState, readOnboardingState, writeOnboardingState, } from "./detect.js";
+import { acquireKeyStep, firstWinStep, scaffoldStep } from "./steps.js";
+/**
+ * Orchestrate the onboarding steps (U.6) — resumable and idempotent. The key
+ * step is skipped when a key already resolves; the completion marker is written
+ * only once a key is in place. An abort during the (mandatory) key step returns
+ * `{ aborted: true }` and writes **no** marker, so it resumes next time.
+ */
+export async function runOnboarding(opts) {
+    const { io, deps, provider } = opts;
+    const col = pc.createColors(io.color);
+    io.write(`${col.cyan(col.bold("Welcome to cruxy"))} — let's get you set up.\n`);
+    let state = deps.readState() ?? newOnboardingState();
+    let apiKey = deps.resolveApiKey(provider);
+    // ── key (mandatory; skipped if already resolvable unless forceKey) ─────────
+    if (!apiKey || opts.forceKey) {
+        const result = await acquireKeyStep(io, deps, provider);
+        if (result.status === "aborted") {
+            return { completed: false, aborted: true };
+        }
+        if (result.status !== "ok") {
+            // Failed (unreachable / rejected) — surface guidance, no marker.
+            if (result.message)
+                io.write(`${col.dim(result.message)}\n`);
+            return { completed: false, aborted: false };
+        }
+        apiKey = result.apiKey;
+        state = { ...state, keyConfigured: true };
+        deps.writeState(state);
+    }
+    else {
+        io.write(`${col.green("✓")} using your existing API key.\n`);
+        state = { ...state, keyConfigured: true };
+    }
+    // ── optional steps (Ctrl-C here just skips them; the key is already safe) ───
+    if (opts.offerScaffold)
+        await scaffoldStep(io, deps.cwd);
+    if (opts.offerFirstWin)
+        await firstWinStep(io, deps);
+    // ── complete ───────────────────────────────────────────────────────────────
+    state = { ...state, completedAt: deps.now() };
+    deps.writeState(state);
+    io.write(`${col.green(col.bold("✓ all set"))} — happy hacking.\n`);
+    return { completed: true, aborted: false, apiKey };
+}
+/**
+ * Build the production {@link OnboardingDeps}: live gateway validation, the
+ * credentials store, real state persistence, and a wall-clock timestamp.
+ */
+export function createDefaultDeps(opts) {
+    return {
+        validateKey: (provider, apiKey) => validateKeyLive(provider, apiKey, opts.config),
+        writeCredential,
+        resolveApiKey,
+        readState: () => readOnboardingState(),
+        writeState: (state) => writeOnboardingState(state),
+        runTask: opts.runTask,
+        cwd: opts.cwd,
+        now: () => new Date().toISOString(),
+    };
+}
+/**
+ * Validate a key with one cheap live call: start a 1-token stream and look at the
+ * first event. `AuthError` ⇒ invalid (bad key), `NetworkError` ⇒ unreachable;
+ * anything else (a token, rate-limit, transient API error) means the key was
+ * accepted, so ⇒ valid.
+ */
+export async function validateKeyLive(provider, apiKey, config) {
+    try {
+        const client = createProvider({
+            provider,
+            apiKey,
+            model: config.model.model,
+            maxTokens: 1,
+            gatewayUrl: config.cruxy.gatewayUrl,
+        });
+        for await (const ev of client.stream({
+            messages: [{ role: "user", content: "hi" }],
+        })) {
+            if (ev.type === "error")
+                return classifyValidation(ev.error);
+            return "valid"; // any non-error event ⇒ the key was accepted
+        }
+        return "valid";
+    }
+    catch (err) {
+        return classifyValidation(err);
+    }
+}
+function classifyValidation(err) {
+    if (err instanceof AuthError)
+        return "invalid";
+    if (err instanceof NetworkError)
+        return "unreachable";
+    // Rate-limit / overloaded / other API errors mean the key authenticated.
+    return "valid";
+}

package/dist/onboarding/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./io.js";
+export * from "./steps.js";
+export * from "./flow.js";