@cruxy/cli 0.4.0 → 0.7.0

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 },
     });
@@ -208,6 +209,132 @@ export function indexFailed(underlying) {
         underlying,
     });
 }
+// ── approval (exit 10) ────────────────────────────────────────────────────────
+/**
+ * A side-effecting action needs approval but cruxy can't ask (non-interactive,
+ * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI
+ * can tell "needed approval" apart from a usage error.
+ */
+export function approvalRequired(summary) {
+    return new CruxyError({
+        code: ErrorCode.ApprovalRequired,
+        title: "this action needs your approval, but cruxy is running non-interactively",
+        cause: `pending action — ${summary}`,
+        nextSteps: [
+            "run cruxy in an interactive terminal so you can approve actions",
+            "or scope the task to read-only actions (no file writes or shell commands)",
+        ],
+        meta: { summary },
+    });
+}
+// ── vcs: forge + git (exit 4 / 2 / 6 / 5) ─────────────────────────────────────
+/**
+ * No forge token could be resolved (PR generation, C.15). The chain is env →
+ * `gh auth token` → fail. We never prompt for, store, or persist a token, so the
+ * fix is always to provide one in the environment.
+ */
+export function forgeAuth(host = "github.com") {
+    return new CruxyError({
+        code: ErrorCode.ForgeAuth,
+        title: `no ${host} token available to open a pull request`,
+        cause: "checked GITHUB_TOKEN, GH_TOKEN, and `gh auth token` — none provided a token",
+        nextSteps: [
+            "export GITHUB_TOKEN=… (a personal access token with `repo` scope)",
+            "or install the GitHub CLI and run `gh auth login`",
+        ],
+        meta: { host },
+    });
+}
+/**
+ * A commit/push was attempted on a protected branch (`main`/`master`/configured).
+ * The PR flow must branch off first; this is the last-line guard.
+ */
+export function gitProtectedBranch(branch) {
+    return new CruxyError({
+        code: ErrorCode.GitProtectedBranch,
+        title: `refusing to commit or push on the protected branch "${branch}"`,
+        cause: "cruxy never writes directly to a protected branch",
+        nextSteps: [
+            "switch to a feature branch first, e.g. `git switch -c feat/my-change`",
+            "adjust the protected list with `git.protectedBranches` in your config",
+        ],
+        meta: { branch },
+    });
+}
+/** The forge REST API returned an error (non-auth) while opening a PR. */
+export function forgeApi(title, underlying, meta) {
+    return new CruxyError({
+        code: ErrorCode.ForgeApi,
+        title,
+        cause: messageOf(underlying),
+        nextSteps: [
+            "retry in a moment; if it persists, check the forge's status",
+            "re-run with --verbose to see the API response",
+        ],
+        underlying,
+        meta,
+    });
+}
+/**
+ * `git push` failed — most often the husky `pre-push` verify hook (build ·
+ * typecheck · lint · test) or a rejected non-fast-forward. We never `--force` or
+ * `--no-verify`, so the underlying reason is surfaced verbatim.
+ */
+export function gitPushFailed(branch, stderr) {
+    return new CruxyError({
+        code: ErrorCode.GitPushFailed,
+        title: `failed to push branch "${branch}"`,
+        cause: stderr?.trim() || undefined,
+        nextSteps: [
+            "check the error above (the pre-push hook runs build · typecheck · lint · test)",
+            "fix the reported issue and try again — cruxy never force-pushes or skips hooks",
+        ],
+        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

@@ -16,15 +16,21 @@ export declare const ErrorCode: {
     readonly Usage: "CRUXY_E_USAGE";
     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";
     readonly AuthInvalid: "CRUXY_E_AUTH_INVALID";
+    readonly ForgeAuth: "CRUXY_E_FORGE_AUTH";
     readonly GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE";
+    readonly GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED";
     readonly Api: "CRUXY_E_API";
     readonly ApiRateLimit: "CRUXY_E_API_RATE_LIMIT";
     readonly ApiOverloaded: "CRUXY_E_API_OVERLOADED";
     readonly BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED";
+    readonly ForgeApi: "CRUXY_E_FORGE_API";
     readonly FileNotFound: "CRUXY_E_FILE_NOT_FOUND";
     readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
     readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
@@ -33,6 +39,8 @@ export declare const ErrorCode: {
     readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
     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

@@ -18,19 +18,25 @@ export const ErrorCode = {
     Usage: "CRUXY_E_USAGE",
     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",
     // auth (exit 4)
     AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
     AuthInvalid: "CRUXY_E_AUTH_INVALID",
+    ForgeAuth: "CRUXY_E_FORGE_AUTH",
     // network (exit 5)
     GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE",
+    GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED",
     // api (exit 6)
     Api: "CRUXY_E_API",
     ApiRateLimit: "CRUXY_E_API_RATE_LIMIT",
     ApiOverloaded: "CRUXY_E_API_OVERLOADED",
     BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED",
+    ForgeApi: "CRUXY_E_FORGE_API",
     // filesystem (exit 7)
     FileNotFound: "CRUXY_E_FILE_NOT_FOUND",
     PermissionDenied: "CRUXY_E_PERMISSION_DENIED",
@@ -42,6 +48,9 @@ export const ErrorCode = {
     // skill (exit 9)
     SkillInvalid: "CRUXY_E_SKILL_INVALID",
     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
@@ -52,15 +61,21 @@ const EXIT_CODES = {
     [ErrorCode.Usage]: 2,
     [ErrorCode.ConfigKeyUnknown]: 2,
     [ErrorCode.ProviderUnsupported]: 2,
+    [ErrorCode.GitProtectedBranch]: 2,
+    [ErrorCode.PlanInvalid]: 2,
+    [ErrorCode.PlanRevisionLimit]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
     [ErrorCode.AuthInvalid]: 4,
+    [ErrorCode.ForgeAuth]: 4,
     [ErrorCode.GatewayUnreachable]: 5,
+    [ErrorCode.GitPushFailed]: 5,
     [ErrorCode.Api]: 6,
     [ErrorCode.ApiRateLimit]: 6,
     [ErrorCode.ApiOverloaded]: 6,
     [ErrorCode.BudgetExhausted]: 6,
+    [ErrorCode.ForgeApi]: 6,
     [ErrorCode.FileNotFound]: 7,
     [ErrorCode.PermissionDenied]: 7,
     [ErrorCode.PathEscape]: 7,
@@ -69,6 +84,8 @@ const EXIT_CODES = {
     [ErrorCode.IndexFailed]: 8,
     [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>;