@cruxy/cli 0.6.0 → 0.8.0

package/README.md

@@ -16,14 +16,26 @@ an approval gate before anything touches disk.
 ```bash
 npm install -g @cruxy/cli
 
-export CRUXY_API_KEY=cxy_live_...   # from app.cruxy.in
+cruxy run "explain this codebase"   # first run guides you through setup
+```
+
+On your first interactive run with no key, cruxy walks you through getting one,
+validates it, and saves it to `~/.cruxy` (owner-only) — no env var needed. You
+can also run setup on demand:
 
-cruxy run "explain this codebase"   # one-shot
-cruxy run                           # interactive session
+```bash
+cruxy login                         # set or replace your API key
+cruxy init                          # key + a project CRUXY.md + a first run
+export CRUXY_API_KEY=cxy_live_...   # …or just use an env var (always wins)
 ```
 
 ## Features
 
+- **Onboarding** — a guided first run (`cruxy login` / `cruxy init` on demand):
+  get a key, validate it live, and save it to `~/.cruxy/credentials.json`
+  (`0600`) — never to `config.json`, the project, or env files. Keys resolve
+  env → credentials store. Non-interactive runs stay fail-loud
+  (`CRUXY_E_AUTH_MISSING_KEY`), never blocking on input.
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
   `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
   `list_skills`, `load_skill`, `create_pull_request`.
@@ -46,6 +58,17 @@ cruxy run                           # interactive session
   validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
+- **Streaming render** — flicker-free live output: a single in-place status line
+  (spinner while the model thinks / tools run), append-only committed text,
+  syntax-highlighted code fences, tool-call notes, and diffs drawn by the same
+  renderer as the approval prompt. Degrades cleanly: piped/CI output is plain
+  append-only text with zero ANSI (chrome on stderr), `NO_COLOR` drops color,
+  and `CRUXY_NO_SPINNER=1` stills the animation.
+- **Plan mode** (opt-in: `cruxy run --plan`, `/plan`, or `agent.planMode`) — the
+  agent proposes a structured, step-by-step plan; you approve it once, then it
+  executes with live per-step status. Approving consents to the _shape_ of the
+  work — every action still passes the approval gate, and destructive/ungrantable
+  actions always re-confirm even after approval.
 - **Safety** — a single approval gate with diff previews that fails closed;
   read-only tools never prompt; file access is confined to the project root;
   shell commands run bounded.
@@ -101,19 +124,19 @@ steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
 `NO_COLOR` disables color. Exit codes are stable per category, so scripts can
 branch on them:
 
-| Exit | Category   | Example codes                                                                                                      |
-| ---- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
-| `0`  | success    | —                                                                                                                  |
-| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                 |
-| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`      |
-| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                   |
-| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                           |
-| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                           |
-| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API` |
-| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                       |
-| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                    |
-| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                 |
-| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`                                                                                        |
+| Exit | Category   | Example codes                                                                                                                                                        |
+| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success    | —                                                                                                                                                                    |
+| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                                                                   |
+| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`, `CRUXY_E_PLAN_INVALID`, `CRUXY_E_PLAN_REVISION_LIMIT` |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                     |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                             |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                             |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                   |
+| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                                                                         |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                      |
+| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                   |
+| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`                                                                                                        |
 
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.

package/dist/agent/loop.d.ts

@@ -1,5 +1,6 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
 export interface RunAgentArgs {
@@ -17,12 +18,13 @@ export interface RunAgentArgs {
     /** Ambient capabilities handed to each tool. */
     ctx: ToolContext;
     /**
-     * Optional sink for assistant text as it streams: called per text delta, then
-     * once with a lone "\n" to close each non-empty text segment on its own line.
-     * When set, `runAgent` streams live and does not buffer-print the turn (the
-     * caller renders); when omitted, behavior is unchanged (one buffered print).
+     * The render seam (U.2): assistant text streams through `renderer.write`
+     * delta by delta (each non-empty segment closed via `endSegment`), and
+     * tool-call progress is surfaced as transient `status` + committed `note`
+     * lines. When omitted, behavior is unchanged (one buffered print per turn,
+     * no tool-call chrome). The loop never touches stdout directly.
      */
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
     /** Git context (branch + dirty) for the system prompt's Environment section. */
     git?: {
         branch: string;
@@ -30,6 +32,8 @@ export interface RunAgentArgs {
     } | null;
     /** Project instructions (e.g. from CRUXY.md) folded into the system prompt. */
     projectInstructions?: string | null;
+    /** Plan mode's propose phase (C.31): inject the plan-first system directive. */
+    planMode?: boolean;
 }
 export interface AgentResult {
     /** The full conversation, including assistant tool calls and tool results. */

package/dist/agent/loop.js

@@ -10,10 +10,23 @@ import { buildSystemPrompt } from "./prompts.js";
  * silently running tool-less.
  */
 export async function runAgent(args) {
-    const { provider, registry, config, ctx } = args;
+    const { provider, config, renderer } = args;
     if (!provider.supportsTools) {
         throw providerUnsupported(config.model.provider);
     }
+    renderer?.beginTurn();
+    try {
+        return await driveLoop(args, renderer);
+    }
+    finally {
+        // Always leave the terminal clean: no orphaned status line, no held text —
+        // even when a provider error aborts the turn mid-stream.
+        renderer?.endTurn();
+    }
+}
+/** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
+async function driveLoop(args, renderer) {
+    const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
     // extended history is returned for the caller to adopt.
@@ -32,6 +45,7 @@ export async function runAgent(args) {
             .map((tool) => ({ name: tool.name, description: tool.description })),
         git: args.git ?? null,
         projectInstructions: args.projectInstructions ?? null,
+        planMode: args.planMode ?? false,
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {
@@ -41,6 +55,8 @@ export async function runAgent(args) {
         let turnText = "";
         const pending = new Map();
         const toolUses = [];
+        // Live progress while waiting on the model; dismissed by the first delta.
+        renderer?.status("thinking…");
         for await (const ev of provider.stream({
             system,
             messages,
@@ -49,7 +65,7 @@ export async function runAgent(args) {
             switch (ev.type) {
                 case "text_delta":
                     turnText += ev.text;
-                    args.onText?.(ev.text);
+                    renderer?.write(ev.text);
                     break;
                 case "tool_use_start":
                     pending.set(ev.index, { id: ev.id, name: ev.name });
@@ -82,13 +98,13 @@ export async function runAgent(args) {
         }
         // ── Record the assistant turn ───────────────────────────────────────────
         if (turnText) {
-            // Streaming (onText set): the text already reached the user delta by delta,
-            // so close the segment with a single newline through the *same* sink — no
-            // separate buffered print racing the stream — so tool output, the next
-            // turn, or an approval prompt starts on its own line. Otherwise render the
-            // whole buffered block (no-callback path, unchanged).
-            if (args.onText)
-                args.onText("\n");
+            // Streaming (renderer set): the text already reached the user delta by
+            // delta, so close the segment through the *same* renderer — it flushes any
+            // held partial line and terminates with one newline, so tool output, the
+            // next turn, or an approval prompt starts on its own line. Otherwise
+            // render the whole buffered block (no-renderer path, unchanged).
+            if (renderer)
+                renderer.endSegment();
             else
                 logger.print(turnText);
         }
@@ -104,13 +120,40 @@ export async function runAgent(args) {
         // ── Execute each tool call, collecting one tool_result per call ──────────
         const toolResults = [];
         for (const call of toolUses) {
-            toolResults.push(await runToolCall(call, registry, ctx));
+            const label = describeToolCall(call);
+            renderer?.status(`${label}…`);
+            const result = await runToolCall(call, registry, ctx);
+            renderer?.note(`${result.is_error ? "✗" : "✓"} ${label}`);
+            toolResults.push(result);
         }
         messages.push({ role: "user", content: toolResults });
     }
     logger.warn(`reached maxIterations (${maxIterations}) without completing`);
     return { messages, iterations, stop: "max_iterations", usage };
 }
+/** Input keys worth surfacing in tool-call chrome, in preference order. */
+const HINT_KEYS = ["path", "file_path", "command", "pattern", "query", "url"];
+/** Longest hint shown before truncation — chrome, not information of record. */
+const HINT_MAX = 60;
+/**
+ * A short human label for a tool call ("read_file src/x.ts"): the tool name
+ * plus the first recognizable scalar argument, if any. Best-effort — unknown
+ * shapes fall back to the bare name.
+ */
+function describeToolCall(call) {
+    const input = call.input;
+    if (typeof input === "object" && input !== null) {
+        for (const key of HINT_KEYS) {
+            const value = input[key];
+            if (typeof value === "string" && value !== "") {
+                const flat = value.replace(/\s+/g, " ").trim();
+                const hint = flat.length > HINT_MAX ? flat.slice(0, HINT_MAX - 1) + "…" : flat;
+                return `${call.name} ${hint}`;
+            }
+        }
+    }
+    return call.name;
+}
 /**
  * Dispatch a single reassembled tool call to its tool and shape the outcome as
  * a `tool_result` block. Unknown tools and invalid arguments become `is_error`

package/dist/agent/prompts.d.ts

@@ -28,6 +28,8 @@ export interface PromptContext {
     } | null;
     /** Optional extra instructions (e.g. from a project CRUXY.md). */
     projectInstructions?: string | null;
+    /** Plan mode's propose phase (C.31): inject the plan-first directive. */
+    planMode?: boolean;
 }
 /** Assemble the full system prompt for a session. */
 export declare function buildSystemPrompt(ctx: PromptContext): string;

package/dist/agent/prompts.js

@@ -6,6 +6,10 @@
  * dynamic environment block, so the model always knows where it is, what it
  * can do, and how it's expected to behave.
  */
+/** The plan-mode directive, injected during the propose phase only. */
+const PLAN_MODE_SECTION = `## Plan mode
+You are in plan mode. Do NOT edit files, run commands, or take any side-effecting action yet.
+First investigate with the read-only tools if you need to, then call \`submit_plan\` with an ordered list of steps — each with a title, a one-line rationale, and a kind (read | mutate | destructive). Cover the whole task; keep steps concrete and minimal. After you call \`submit_plan\`, stop and end your turn — the user reviews and approves the plan before you execute it.`;
 /**
  * The static core of cruxy's behaviour. Phrased as direct instruction to the
  * model. Keep this tight — every line earns its place; vague prose dilutes the
@@ -74,6 +78,8 @@ export function buildSystemPrompt(ctx) {
     const approval = "Side-effecting actions (file writes, shell commands) require the user's approval; destructive or irreversible actions are flagged distinctly.";
     const core = CORE.replace("${APPROVAL_CLAUSE}", approval);
     const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
+    if (ctx.planMode)
+        sections.push(PLAN_MODE_SECTION);
     if (ctx.projectInstructions?.trim()) {
         sections.push(`## Project instructions\nThe following came from this project's configuration; honor it unless it conflicts with the rules above:\n\n${ctx.projectInstructions.trim()}`);
     }

package/dist/agent/session.d.ts

@@ -1,8 +1,20 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
 import { type AgentResult } from "./loop.js";
+/**
+ * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
+ * the plan package. When plan mode is on, `send` delegates the whole turn to
+ * this instead of a single `runAgent` call. Receives the running history (with
+ * the user turn already appended) and returns the extended history to adopt.
+ */
+export type PlanRunner = (args: {
+    messages: Message[];
+    projectInstructions: string | null;
+    renderer?: StreamRenderer;
+}) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
     provider: Provider;
@@ -19,6 +31,10 @@ export interface SessionArgs {
     } | null;
     /** Project instructions (e.g. CRUXY.md) folded into every turn's system prompt. */
     projectInstructions?: string | null;
+    /** Start in plan mode (C.31). Toggleable at runtime via `setPlanMode`. */
+    planMode?: boolean;
+    /** The plan-mode turn runner; required for plan mode to actually engage. */
+    planRunner?: PlanRunner;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -46,16 +62,26 @@ export declare class Session {
     private readonly args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     private projectInstructions;
+    /** Mutable so `/plan` can toggle plan mode mid-session. */
+    private planMode;
     constructor(args: SessionArgs);
+    /** Whether plan mode is currently on. */
+    getPlanMode(): boolean;
+    /**
+     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
+     * the session factory); without one, plan mode stays off.
+     */
+    setPlanMode(enabled: boolean): void;
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
      * the threshold, drive the agent loop over the full history, adopt the
      * extended history, and accumulate usage. Returns the turn's `AgentResult`.
      *
-     * `onText`, when supplied, receives assistant text deltas as they stream so the
-     * caller can render them live (see the REPL); history is unaffected.
+     * `renderer`, when supplied, receives assistant text deltas and tool-call
+     * progress as they stream so the caller sees the turn live (see the REPL);
+     * history is unaffected.
      */
-    send(userPrompt: string, onText?: (delta: string) => void): Promise<AgentResult>;
+    send(userPrompt: string, renderer?: StreamRenderer): Promise<AgentResult>;
     /**
      * Re-read project instructions (CRUXY.md / AGENTS.md) from the working
      * directory so edits take effect without restarting. Returns the new text, or

package/dist/agent/session.js

@@ -49,29 +49,56 @@ export class Session {
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
+    /** Mutable so `/plan` can toggle plan mode mid-session. */
+    planMode;
     constructor(args) {
         this.args = args;
         this.projectInstructions = args.projectInstructions ?? null;
+        // Plan mode requires a wired runner; without one it stays off (no half-on
+        // state where the plan directive is injected but nothing orchestrates it).
+        this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
+    }
+    /** Whether plan mode is currently on. */
+    getPlanMode() {
+        return this.planMode;
+    }
+    /**
+     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
+     * the session factory); without one, plan mode stays off.
+     */
+    setPlanMode(enabled) {
+        this.planMode = enabled && this.args.planRunner !== undefined;
     }
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
      * the threshold, drive the agent loop over the full history, adopt the
      * extended history, and accumulate usage. Returns the turn's `AgentResult`.
      *
-     * `onText`, when supplied, receives assistant text deltas as they stream so the
-     * caller can render them live (see the REPL); history is unaffected.
+     * `renderer`, when supplied, receives assistant text deltas and tool-call
+     * progress as they stream so the caller sees the turn live (see the REPL);
+     * history is unaffected.
      */
-    async send(userPrompt, onText) {
+    async send(userPrompt, renderer) {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
-        const result = await runAgent({
-            messages: this.messages,
-            ...this.args,
-            // After the spread so a mid-session `/reload` wins over the initial value.
-            projectInstructions: this.projectInstructions,
-            onText,
-        });
+        // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
+        // plan, approve/revise, then execute step-by-step. Falls back to the normal
+        // single-shot loop when off or unwired, so existing behavior is untouched.
+        const result = this.planMode && this.args.planRunner
+            ? await this.args.planRunner({
+                messages: this.messages,
+                projectInstructions: this.projectInstructions,
+                renderer,
+            })
+            : await runAgent({
+                messages: this.messages,
+                ...this.args,
+                // After the spread so a mid-session `/reload` wins over the initial value.
+                projectInstructions: this.projectInstructions,
+                planMode: false, // the plan directive belongs only to the runner's propose phase
+                renderer,
+            });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;

package/dist/approval/prompt.d.ts

@@ -1,4 +1,13 @@
 import type { ApprovalRequest } from "./types.js";
+/**
+ * The interactive prompt: render a pending action (a real diff for file edits,
+ * the exact command + cwd for shell) and read a 4-way choice. Rendering is data
+ * → string so it's testable; color is gated on `io.color` (NO_COLOR / non-TTY
+ * aware). **Default-deny**: EOF / Ctrl-C / any unrecognized key → reject.
+ *
+ * Diff/preview rendering is the shared implementation in `render/diff.ts` —
+ * the streaming path and this prompt draw the same bytes for the same change.
+ */
 /** The four user choices (plus the implicit default-deny). */
 export type PromptChoice = {
     kind: "once";

package/dist/approval/prompt.js

@@ -1,7 +1,6 @@
 import path from "node:path";
 import pc from "picocolors";
-/** Cap on rendered preview lines before collapsing the rest. */
-const PREVIEW_MAX_LINES = 40;
+import { renderActionPreview } from "../render/diff.js";
 /**
  * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
  * read a follow-up line (reason / instruction). Anything else — including EOF —
@@ -53,7 +52,7 @@ function detail(request, c) {
             `  ${c.dim(`in ${request.cwd}`)}`,
         ].join("\n");
     }
-    return renderPreview(request.action.preview, c);
+    return renderActionPreview(request.action.preview, c);
 }
 /** The choices line, including a short label of what an `a` grant would cover. */
 function choices(scope, c) {
@@ -71,80 +70,6 @@ function scopeLabel(scope) {
         return `changes under ${path.basename(scope.root)}/`;
     return null;
 }
-// ── diff rendering (shared with the old C.6 renderer) ──────────────────────────
-function diffLines(oldStr, newStr, c) {
-    const removed = oldStr.split("\n").map((l) => c.red(`- ${l}`));
-    const added = newStr.split("\n").map((l) => c.green(`+ ${l}`));
-    return [...removed, ...added];
-}
-function renderPatchFiles(files, c) {
-    const out = [];
-    for (const file of files) {
-        if (file.op === "delete") {
-            out.push(c.red(`delete ${file.path}`));
-        }
-        else if (file.op === "create") {
-            out.push(c.green(`create ${file.path}`));
-            out.push(...file.lines.map((l) => c.green(`+ ${l}`)));
-            if (file.omittedLines > 0)
-                out.push(c.dim(`  ...${file.omittedLines} more lines`));
-        }
-        else {
-            out.push(c.yellow(`update ${file.path}`));
-            for (const hunk of file.hunks)
-                out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
-        }
-    }
-    return out;
-}
-/** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
-function renderPrPreview(preview, c) {
-    const out = [];
-    out.push(`${c.bold("branch")}  ${c.green(preview.branch)} → ${preview.base}`);
-    out.push("");
-    out.push(c.bold("commit"));
-    out.push(`  ${preview.commitSubject}`);
-    for (const line of bodyLines(preview.commitBody))
-        out.push(c.dim(`  ${line}`));
-    out.push("");
-    out.push(`${c.bold("pull request")}  ${preview.prTitle}`);
-    for (const line of bodyLines(preview.prBody))
-        out.push(c.dim(`  ${line}`));
-    return out;
-}
-/** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
-function bodyLines(body) {
-    const lines = body.replace(/\s+$/, "").split("\n");
-    return lines.length === 1 && lines[0] === "" ? [] : lines;
-}
-function renderPreview(preview, c) {
-    if (!preview)
-        return "";
-    let lines;
-    if (preview.type === "edit") {
-        lines = diffLines(preview.oldStr, preview.newStr, c);
-    }
-    else if (preview.type === "patch") {
-        lines = renderPatchFiles(preview.files, c);
-    }
-    else if (preview.type === "pr") {
-        lines = renderPrPreview(preview, c);
-    }
-    else {
-        const header = preview.exists
-            ? c.yellow("OVERWRITE existing")
-            : c.green("create");
-        const body = preview.lines.map((l) => `  ${l}`);
-        if (preview.omittedLines > 0)
-            body.push(c.dim(`  ...${preview.omittedLines} more lines`));
-        lines = [header, ...body];
-    }
-    if (lines.length > PREVIEW_MAX_LINES) {
-        const hidden = lines.length - PREVIEW_MAX_LINES;
-        lines = [...lines.slice(0, PREVIEW_MAX_LINES), c.dim(`...${hidden} more`)];
-    }
-    return lines.map((l) => `  ${l}`).join("\n");
-}
 // ── default stdin-backed PromptIO ──────────────────────────────────────────────
 /** Build the real PromptIO: prompt to stderr, read keys/lines from stdin. */
 export function defaultPromptIO(color) {

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy init` — set up a project (U.6): ensure a key (acquired only if missing),
+ * offer to scaffold a project `CRUXY.md`, and offer a first-win demo run. Like
+ * `login`, it's interactive-only.
+ */
+export declare function initCommand(): Command;

package/dist/cli/commands/init.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig } from "../../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
+import { runFirstWinTask } from "../onboard.js";
+/**
+ * `cruxy init` — set up a project (U.6): ensure a key (acquired only if missing),
+ * offer to scaffold a project `CRUXY.md`, and offer a first-win demo run. Like
+ * `login`, it's interactive-only.
+ */
+export function initCommand() {
+    return new Command("init")
+        .description("set up cruxy in this project (key + CRUXY.md + a first run)")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            logger.print(pc.dim("cruxy init is interactive — run it in a terminal, or export your key as an environment variable."));
+            process.exitCode = 1;
+            return;
+        }
+        const cwd = process.cwd();
+        const { config } = loadConfig();
+        const result = await runOnboarding({
+            provider: config.model.provider,
+            mode: "init",
+            offerScaffold: true,
+            offerFirstWin: true,
+            io: defaultOnboardingIO(),
+            deps: createDefaultDeps({
+                config,
+                cwd,
+                runTask: (prompt) => runFirstWinTask(config, cwd, prompt),
+            }),
+        });
+        if (!result.completed) {
+            logger.print(pc.dim("setup not completed — run `cruxy init` again to resume."));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/login.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
+ * of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch), validates it live, and persists it to the credentials store.
+ * Non-interactive invocations fail loud rather than hang.
+ */
+export declare function loginCommand(): Command;

package/dist/cli/commands/login.js

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig } from "../../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
+/**
+ * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
+ * of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch), validates it live, and persists it to the credentials store.
+ * Non-interactive invocations fail loud rather than hang.
+ */
+export function loginCommand() {
+    return new Command("login")
+        .description("set or replace your API key (validated, saved to ~/.cruxy)")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            logger.print(pc.dim("cruxy login is interactive — run it in a terminal, or export your key as an environment variable."));
+            process.exitCode = 1;
+            return;
+        }
+        const { config } = loadConfig();
+        const result = await runOnboarding({
+            provider: config.model.provider,
+            mode: "login",
+            forceKey: true,
+            offerFirstWin: false,
+            offerScaffold: false,
+            io: defaultOnboardingIO(),
+            deps: createDefaultDeps({ config, cwd: process.cwd() }),
+        });
+        if (!result.completed) {
+            logger.print(pc.dim("login not completed."));
+            process.exitCode = 1;
+        }
+    });
+}