@cruxy/cli 0.6.0 → 0.8.0

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";

package/dist/onboarding/index.js

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

package/dist/onboarding/io.d.ts

@@ -0,0 +1,8 @@
+import type { OnboardingIO } from "./types.js";
+/**
+ * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
+ * stays clean for piping); the secret reader echoes `*` per keystroke and never
+ * the real character. All readers restore cooked mode on the way out, even on
+ * Ctrl-C / EOF — the terminal is never left in raw mode.
+ */
+export declare function defaultOnboardingIO(color?: boolean): OnboardingIO;

package/dist/onboarding/io.js

@@ -0,0 +1,133 @@
+import { shouldUseColor } from "../errors/index.js";
+/**
+ * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
+ * stays clean for piping); the secret reader echoes `*` per keystroke and never
+ * the real character. All readers restore cooked mode on the way out, even on
+ * Ctrl-C / EOF — the terminal is never left in raw mode.
+ */
+export function defaultOnboardingIO(color = shouldUseColor()) {
+    return {
+        write: (text) => void process.stderr.write(text),
+        readLine: readLineFromStdin,
+        readKey: readKeyFromStdin,
+        readSecret: readSecretFromStdin,
+        color,
+    };
+}
+const CTRL_C = 0x03;
+const CTRL_D = 0x04;
+const BACKSPACE = 0x08;
+const DELETE = 0x7f;
+const LF = 0x0a;
+const CR = 0x0d;
+/** Read one keypress in raw mode; "" on EOF / Ctrl-C / Ctrl-D. Restores cooked mode. */
+function readKeyFromStdin() {
+    const stdin = process.stdin;
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+        };
+        const onData = (buf) => {
+            cleanup();
+            const code = buf[0];
+            resolve(code === CTRL_C || code === CTRL_D
+                ? ""
+                : buf.toString("utf8").slice(0, 1));
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve("");
+        };
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.once("data", onData);
+        stdin.once("end", onEnd);
+    });
+}
+/** Read one line in cooked mode; "" on EOF. */
+function readLineFromStdin() {
+    const stdin = process.stdin;
+    return new Promise((resolve) => {
+        let buf = "";
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            stdin.pause();
+        };
+        const onData = (chunk) => {
+            buf += chunk.toString("utf8");
+            const nl = buf.indexOf("\n");
+            if (nl !== -1) {
+                cleanup();
+                resolve(buf.slice(0, nl).replace(/\r$/, ""));
+            }
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(buf.replace(/\r$/, ""));
+        };
+        if (stdin.isTTY)
+            stdin.setRawMode(false);
+        stdin.resume();
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+    });
+}
+/**
+ * Read a secret with no echo: each printable keystroke shows a `*`, backspace
+ * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The real
+ * characters are never written anywhere.
+ */
+function readSecretFromStdin() {
+    const stdin = process.stdin;
+    const out = process.stderr;
+    return new Promise((resolve) => {
+        let buf = "";
+        let done = false;
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+        };
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            cleanup();
+            out.write("\n");
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const byte of chunk) {
+                if (byte === CR || byte === LF)
+                    return finish(buf); // Enter → submit
+                if (byte === CTRL_C || byte === CTRL_D)
+                    return finish(""); // abort
+                if (byte === DELETE || byte === BACKSPACE) {
+                    if (buf.length > 0) {
+                        buf = buf.slice(0, -1);
+                        out.write("\b \b"); // erase one star
+                    }
+                    continue;
+                }
+                if (byte < 0x20)
+                    continue; // ignore other control chars
+                buf += String.fromCharCode(byte);
+                out.write("*");
+            }
+        };
+        const onEnd = () => finish("");
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+    });
+}

package/dist/onboarding/steps.d.ts

@@ -0,0 +1,17 @@
+import type { OnboardingDeps, OnboardingIO, StepResult } from "./types.js";
+/**
+ * Acquire and persist a provider key: print the create-key URL, read it masked,
+ * validate it live, and **only then** write it to the credentials store. Loops on
+ * a rejected key (up to 3 tries); a network failure or an empty entry stops.
+ */
+export declare function acquireKeyStep(io: OnboardingIO, deps: OnboardingDeps, provider: string): Promise<StepResult>;
+/**
+ * Offer to scaffold a project `CRUXY.md`. Skipped silently when one already
+ * exists (or `AGENTS.md`); otherwise a `y` confirmation writes the template.
+ */
+export declare function scaffoldStep(io: OnboardingIO, cwd: string): Promise<StepResult>;
+/**
+ * Offer the first-win demo run. Skipped when no runner is wired or the user
+ * declines; otherwise runs one real task so they see value immediately.
+ */
+export declare function firstWinStep(io: OnboardingIO, deps: OnboardingDeps): Promise<StepResult>;