@cruxy/cli 0.3.0 → 0.6.0

package/dist/approval/prompt.js

@@ -0,0 +1,212 @@
+import path from "node:path";
+import pc from "picocolors";
+/** Cap on rendered preview lines before collapsing the rest. */
+const PREVIEW_MAX_LINES = 40;
+/**
+ * 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 —
+ * is a reject.
+ */
+export async function promptForApproval(request, io) {
+    io.write(render(request, io.color));
+    const key = (await io.readKey()).toLowerCase();
+    io.write("\n");
+    switch (key) {
+        case "y":
+            return { kind: "once" };
+        case "a":
+            return { kind: "session" };
+        case "n": {
+            io.write("  reason (optional, sent to the agent): ");
+            const reason = (await io.readLine()).trim();
+            return reason ? { kind: "reject", reason } : { kind: "reject" };
+        }
+        case "t": {
+            io.write("  what should the agent do instead? ");
+            const instruction = (await io.readLine()).trim();
+            return instruction
+                ? { kind: "instruct", instruction }
+                : { kind: "reject" };
+        }
+        default:
+            // n/a key, empty, EOF, Ctrl-C → default-deny.
+            return { kind: "reject" };
+    }
+}
+/** Render the full prompt block: header, detail (diff or command+cwd), choices. */
+export function render(request, color) {
+    const c = pc.createColors(color);
+    const destructive = request.tier === "destructive";
+    const mark = destructive ? c.red(c.bold("!")) : c.yellow("?");
+    const label = destructive ? c.red(c.bold(" (destructive)")) : "";
+    const lines = [];
+    lines.push(`${mark} cruxy wants to ${c.bold(request.summary)}${label}`);
+    lines.push(detail(request, c));
+    lines.push(choices(request.scope, c));
+    return lines.filter((l) => l !== "").join("\n") + " ";
+}
+/** The action detail: a diff for file actions, the command + cwd for shell. */
+function detail(request, c) {
+    if (request.action.kind === "shell") {
+        return [
+            `  ${c.dim("$")} ${request.action.command ?? ""}`,
+            `  ${c.dim(`in ${request.cwd}`)}`,
+        ].join("\n");
+    }
+    return renderPreview(request.action.preview, c);
+}
+/** The choices line, including a short label of what an `a` grant would cover. */
+function choices(scope, c) {
+    const grant = scopeLabel(scope);
+    const a = grant === null
+        ? `${c.dim("[a] allow this kind (n/a here)")}`
+        : `[a] allow ${c.bold(grant)} this session`;
+    return `  ${c.dim("[y] approve once ·")} ${a} ${c.dim("· [n] reject · [t] reject & instruct:")}`;
+}
+/** Short human label for what a session grant would allow, or null if none. */
+function scopeLabel(scope) {
+    if (scope.kind === "shell-prefix")
+        return `${scope.token} commands`;
+    if (scope.kind === "file-subtree")
+        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) {
+    return {
+        write: (text) => void process.stderr.write(text),
+        readKey: readKeyFromStdin,
+        readLine: readLineFromStdin,
+        color,
+    };
+}
+/** Read a single keypress in raw mode; "" on EOF. Always 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();
+            resolve(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);
+    });
+}

package/dist/approval/service.d.ts

@@ -0,0 +1,36 @@
+import type { ApproveAction } from "../tools/types.js";
+import { type PromptIO } from "./prompt.js";
+import type { ApprovalDecision, ApprovalPolicy } from "./types.js";
+/**
+ * The approval gate, called by the tool layer **before any side effect**. It
+ * classifies the action, lets read-only actions through, **throws
+ * CRUXY_E_APPROVAL_REQUIRED when it can't ask** (non-interactive — default-deny,
+ * never auto-approve), and otherwise defers to the policy. It owns the
+ * per-session allowlist, so a new service ⇒ a fresh session.
+ */
+export interface ApprovalServiceOptions {
+    /** Resolved project root the actions run in. */
+    cwd: string;
+    /** Whether cruxy can actually prompt (stdin is a TTY). */
+    interactive: boolean;
+    /** Override the decision policy (the seam — tests / a future CI policy). */
+    policy?: ApprovalPolicy;
+    /** Override the prompt I/O (tests script keys/lines). */
+    io?: PromptIO;
+}
+export declare class ApprovalService {
+    private readonly cwd;
+    private readonly interactive;
+    private readonly allowlist;
+    private readonly policy;
+    constructor(opts: ApprovalServiceOptions);
+    /**
+     * Decide whether `action` may proceed. Read-only ⇒ allow. Non-interactive ⇒
+     * throw {@link approvalRequired} (the U.5 error system, exit 10). Otherwise the
+     * policy prompts. A returned `{allow:false}` is a clean rejection (fed back to
+     * the agent), not an error.
+     */
+    requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
+    /** Clear all session grants (a fresh session). */
+    resetSession(): void;
+}

package/dist/approval/service.js

@@ -0,0 +1,37 @@
+import { approvalRequired } from "../errors/index.js";
+import { shouldUseColor } from "../errors/index.js";
+import { classify } from "./classify.js";
+import { InteractivePolicy, SessionAllowlist } from "./policy.js";
+import { defaultPromptIO } from "./prompt.js";
+export class ApprovalService {
+    cwd;
+    interactive;
+    allowlist = new SessionAllowlist();
+    policy;
+    constructor(opts) {
+        this.cwd = opts.cwd;
+        this.interactive = opts.interactive;
+        this.policy =
+            opts.policy ??
+                new InteractivePolicy(this.allowlist, opts.io ?? defaultPromptIO(shouldUseColor()));
+    }
+    /**
+     * Decide whether `action` may proceed. Read-only ⇒ allow. Non-interactive ⇒
+     * throw {@link approvalRequired} (the U.5 error system, exit 10). Otherwise the
+     * policy prompts. A returned `{allow:false}` is a clean rejection (fed back to
+     * the agent), not an error.
+     */
+    async requestApproval(action) {
+        const request = classify(action, this.cwd);
+        if (request.tier === "read")
+            return { allow: true };
+        if (!this.interactive) {
+            throw approvalRequired(request.summary);
+        }
+        return this.policy.decide(request);
+    }
+    /** Clear all session grants (a fresh session). */
+    resetSession() {
+        this.allowlist.clear();
+    }
+}

package/dist/approval/types.d.ts

@@ -0,0 +1,64 @@
+import type { ApproveAction } from "../tools/types.js";
+/**
+ * Types for the approval gate (U.3) — the security boundary between the agent
+ * and side-effecting actions. The gate is **default-deny**: no response means
+ * reject, never auto-approve.
+ */
+/**
+ * Risk classification for a pending action. Friction is reserved for what's
+ * risky, so users don't rubber-stamp.
+ * - `read` — read-only, auto-allowed (read tools bypass the gate entirely).
+ * - `mutate` — reversible-ish mutation (file write/edit) → approve, normal style.
+ * - `destructive` — irreversible / high blast radius (shell, delete) → approve,
+ *   visually distinct. **Unknown actions classify here.**
+ */
+export type RiskTier = "read" | "mutate" | "destructive";
+/**
+ * The tight scope a session grant is keyed by. Never blanket.
+ * - `shell-prefix` — a command's leading program token (e.g. `git`); only ever
+ *   matches commands we can *positively* prove are simple (no shell features).
+ * - `file-subtree` — an absolute directory (or, under the root-cap, an exact
+ *   file path); matches targets that resolve inside it.
+ * - `none` — nothing safe to grant (e.g. a multi-file patch spanning the root).
+ */
+export type Scope = {
+    readonly kind: "shell-prefix";
+    readonly token: string;
+} | {
+    readonly kind: "file-subtree";
+    readonly root: string;
+} | {
+    readonly kind: "none";
+};
+/** A pending action, classified and ready to show / decide on. */
+export interface ApprovalRequest {
+    /** The raw tool action (kind, path/command, preview). */
+    readonly action: ApproveAction;
+    /** Risk classification. */
+    readonly tier: RiskTier;
+    /** The tight scope a session grant would use. */
+    readonly scope: Scope;
+    /** One plain line describing the action (e.g. "run: git status"). */
+    readonly summary: string;
+    /** Absolute resolved target paths for file actions; `[]` for shell. */
+    readonly targets: readonly string[];
+    /** Resolved project root the action runs in (shown as the shell cwd). */
+    readonly cwd: string;
+}
+/**
+ * The gate's verdict. On reject, `feedback` (if any) is fed back to the agent as
+ * the tool result so it can adapt — a rejection is data, not an error.
+ */
+export type ApprovalDecision = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    readonly feedback?: string;
+};
+/**
+ * Pluggable decision strategy — the seam. Only `InteractivePolicy` ships in U.3;
+ * a future non-interactive/CI policy slots in here without touching call sites.
+ */
+export interface ApprovalPolicy {
+    decide(request: ApprovalRequest): Promise<ApprovalDecision>;
+}

package/dist/approval/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/config.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import pc from "picocolors";
+import { configKeyUnknown } from "../../errors/index.js";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, getPath, setValue, initConfig, globalConfigPath, findProjectConfig, } from "../../config/index.js";
 export function configCommand() {
@@ -19,9 +20,7 @@ export function configCommand() {
         const { config } = loadConfig();
         const value = getPath(config, key);
         if (value === undefined) {
-            logger.error(`no such config key: ${pc.bold(key)}`);
-            process.exitCode = 1;
-            return;
+            throw configKeyUnknown(key);
         }
         logger.print(typeof value === "object"
             ? JSON.stringify(value, null, 2)

package/dist/cli/commands/index.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { Command } from "commander";
 import pc from "picocolors";
 import { loadConfig } from "../../config/index.js";
+import { CruxyError, indexFailed } from "../../errors/index.js";
 import { getIndexService, indexDbPath, resetIndexServices, } from "../../indexing/index.js";
 import { logger } from "../../utils/logger.js";
 /**
@@ -41,8 +42,10 @@ export function indexCommand() {
                 pc.dim(`(${stats.filesSkipped} unchanged, ${stats.filesPurged} purged, ${stats.durationMs}ms)`));
         }
         catch (err) {
-            logger.error(`indexing failed: ${err.message}`);
-            process.exitCode = 1;
+            // Typed index failures (embedder/store unavailable) already carry a
+            // code; anything else becomes CRUXY_E_INDEX_FAILED. The boundary formats
+            // and sets the exit code.
+            throw err instanceof CruxyError ? err : indexFailed(err);
         }
         finally {
             await resetIndexServices();

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

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy pr` — turn the current changes into a pull request (C.15). Generates the
+ * branch name, conventional commit, and PR title/body from the diff with the
+ * model, then runs branch → commit → push → open-PR behind the one U.3 approval.
+ * The forge token comes from the environment / `gh`; it's never prompted or stored.
+ */
+export declare function prCommand(): Command;

package/dist/cli/commands/pr.js

@@ -0,0 +1,87 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { createProvider } from "@cruxy/sdk";
+import { logger } from "../../utils/logger.js";
+import { loadConfig, resolveApiKey } from "../../config/index.js";
+import { authMissingKey } from "../../errors/index.js";
+import { ApprovalService } from "../../approval/index.js";
+import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidance, resolveForgeToken, } from "../../vcs/index.js";
+/**
+ * `cruxy pr` — turn the current changes into a pull request (C.15). Generates the
+ * branch name, conventional commit, and PR title/body from the diff with the
+ * model, then runs branch → commit → push → open-PR behind the one U.3 approval.
+ * The forge token comes from the environment / `gh`; it's never prompted or stored.
+ */
+export function prCommand() {
+    return new Command("pr")
+        .description("open a pull request from the current changes (generated + gated)")
+        .option("-b, --base <branch>", "base branch to merge into")
+        .option("-t, --title <title>", "PR title (conventional-commit subject)")
+        .option("--body <body>", "PR body")
+        .option("--draft", "open the pull request as a draft")
+        .action(async (opts) => {
+        const cwd = process.cwd();
+        const { config } = loadConfig();
+        // The model writes the PR content, so we need a provider key just like
+        // `cruxy run`. The forge token is resolved separately (env / gh).
+        const apiKey = resolveApiKey(config.model.provider);
+        if (!apiKey) {
+            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+        }
+        const provider = createProvider({
+            provider: config.model.provider,
+            apiKey,
+            model: config.model.model,
+            maxTokens: config.model.maxTokens,
+            temperature: config.model.temperature,
+            gatewayUrl: config.cruxy.gatewayUrl,
+        });
+        // resolveForgeToken throws CRUXY_E_FORGE_AUTH (exit 4) if none is found.
+        const forge = createForgeProvider(resolveForgeToken());
+        const guidance = await loadCommitGuidance(cwd);
+        const approval = new ApprovalService({
+            cwd,
+            interactive: Boolean(process.stdin.isTTY),
+        });
+        const service = createPrService({
+            cwd,
+            config,
+            forge,
+            requestApproval: (action) => approval.requestApproval(action),
+            generate: (i) => generateWithLlm(provider, {
+                ...i,
+                scopes: guidance.scopes,
+                skillBody: guidance.skillBody,
+            }),
+        });
+        logger.info(pc.dim("generating pull request content…"));
+        const outcome = await service.openPullRequest({
+            base: opts.base,
+            title: opts.title,
+            body: opts.body,
+            draft: opts.draft,
+        });
+        if (!outcome.approved) {
+            logger.print(pc.yellow("pull request not opened — approval declined."));
+            if (outcome.feedback)
+                logger.print(pc.dim(outcome.feedback));
+            return;
+        }
+        const label = outcome.alreadyExists
+            ? "a pull request already exists"
+            : "opened pull request";
+        logger.print(`${pc.green("✓")} ${label} (${outcome.branch} → ${outcome.base})`);
+        logger.print(pc.cyan(outcome.url));
+    });
+}
+/** Environment variable that holds the API key for a provider. */
+function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}

package/dist/cli/commands/run.js

@@ -3,8 +3,10 @@ import pc from "picocolors";
 import { createProvider } from "@cruxy/sdk";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey, loadProjectInstructions, } from "../../config/index.js";
+import { authMissingKey, usageError } from "../../errors/index.js";
+import { ApprovalService } from "../../approval/index.js";
 import { buildDefaultRegistry } from "../../tools/index.js";
-import { Session, createApprover } from "../../agent/index.js";
+import { Session } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
 import { createStreamPrinter } from "../stream-print.js";
 import { getGitInfo } from "../../utils/git.js";
@@ -12,24 +14,20 @@ export function runCommand() {
     return new Command("run")
         .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
-        .option("-y, --yes", "auto-approve all tool actions (run unattended)")
-        .option("--dangerously-approve", "alias for --yes: approve every action without prompting")
-        .action(async (promptParts, opts) => {
+        .action(async (promptParts) => {
         const prompt = promptParts.join(" ").trim();
         const interactive = prompt === "";
         // No prompt and stdin isn't a terminal: there's no way to read input and
         // nothing to do — fail fast instead of hanging on a line that never comes.
         if (interactive && !process.stdin.isTTY) {
-            logger.error('cruxy run needs a prompt when stdin is not a terminal — try: cruxy run "<task>"');
-            return;
+            throw usageError("cruxy run needs a prompt when stdin is not a terminal", ['provide a task, e.g. cruxy run "fix the failing test"']);
         }
         const { config, sources } = loadConfig();
         const apiKey = resolveApiKey(config.model.provider);
         logger.info(pc.dim(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(pc.dim(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
         if (!apiKey) {
-            logger.warn(`no API key for provider ${pc.bold(config.model.provider)} — set it in the environment before running.`);
-            return;
+            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
         }
         const provider = createProvider({
             provider: config.model.provider,
@@ -40,18 +38,19 @@ export function runCommand() {
             gatewayUrl: config.cruxy.gatewayUrl,
         });
         const registry = buildDefaultRegistry();
-        const approver = createApprover({
-            mode: config.approval.mode,
+        // The approval gate. Default-deny, risk-tiered, scoped session allowlist;
+        // no global skip flag (the policy seam lives in src/approval). When stdin
+        // isn't a TTY, a side-effecting action fails with CRUXY_E_APPROVAL_REQUIRED
+        // rather than being auto-approved.
+        const approval = new ApprovalService({
             cwd: process.cwd(),
-            isInteractive: Boolean(process.stdin.isTTY),
-            autoApprove: Boolean(opts.yes || opts.dangerouslyApprove),
-            logger,
+            interactive: Boolean(process.stdin.isTTY),
         });
         const ctx = {
             cwd: process.cwd(),
             config,
             logger,
-            approve: (action) => approver.approve(action),
+            requestApproval: (action) => approval.requestApproval(action),
         };
         const projectInstructions = loadProjectInstructions(process.cwd());
         const git = getGitInfo(process.cwd());
@@ -72,14 +71,23 @@ export function runCommand() {
         // through a printer that trims the model's leading blank lines; the agent
         // loop terminates the line.
         logger.print(`${pc.cyan("cruxy")} ${pc.dim("›")} ${prompt}\n`);
-        try {
-            const print = createStreamPrinter((text) => process.stdout.write(text));
-            const result = await session.send(prompt, print);
-            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
-                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
-        }
-        catch (err) {
-            logger.error(err.message);
-        }
+        // Provider/network/auth failures propagate to the top-level boundary,
+        // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
+        // the matching code — a one-shot run must fail non-zero on error.
+        const print = createStreamPrinter((text) => process.stdout.write(text));
+        const result = await session.send(prompt, print);
+        logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+            `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
     });
 }
+/** Environment variable that holds the API key for a provider. */
+function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}

package/dist/cli/program.js

@@ -2,10 +2,12 @@ import { Command } from "commander";
 import pc from "picocolors";
 import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
 import { logger } from "../utils/logger.js";
+import { usageError } from "../errors/index.js";
 import { runCommand } from "./commands/run.js";
 import { configCommand } from "./commands/config.js";
 import { indexCommand } from "./commands/index.js";
 import { skillsCommand } from "./commands/skills.js";
+import { prCommand } from "./commands/pr.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -14,8 +16,7 @@ export function buildProgram() {
         .version(APP_VERSION, "-v, --version", "print the cruxy version")
         .option("-c, --config <path>", "use a specific config file")
         .option("--log-level <level>", "debug | info | warn | error | silent")
-        .option("--verbose", "shorthand for --log-level debug")
-        .showHelpAfterError("(run `cruxy --help` for usage)");
+        .option("--verbose", "shorthand for --log-level debug");
     // Apply global options as early as possible.
     program.hook("preAction", (thisCommand) => {
         const opts = thisCommand.opts();
@@ -28,13 +29,34 @@ export function buildProgram() {
     program.addCommand(configCommand());
     program.addCommand(indexCommand());
     program.addCommand(skillsCommand());
-    // Default action: no subcommand -> interactive entrypoint (stub for now).
-    program.action(() => {
+    program.addCommand(prCommand());
+    // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
+    // means an unknown command (Commander runs the default action with it as an
+    // operand rather than erroring), so reject it as a usage error.
+    program.action((_opts, command) => {
+        if (command.args.length > 0) {
+            throw usageError(`unknown command: ${command.args[0]}`, [
+                "run `cruxy --help` to see available commands",
+            ]);
+        }
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));
         logger.print(pc.dim("an agentic coding CLI\n"));
         logger.print("The interactive REPL lands in C.3 (terminal UI).");
         logger.print(`For now try:  ${pc.bold('cruxy run "<task>"')}  or  ${pc.bold("cruxy config path")}`);
         logger.print(`See all commands:  ${pc.bold("cruxy --help")}`);
     });
+    // Throw CommanderError instead of calling process.exit, and suppress
+    // Commander's own "error:" line — so parse errors (unknown command/option,
+    // missing argument) at *any* level route through the single error boundary as
+    // CRUXY_E_USAGE, sharing one exit code (2) and format. Applied recursively
+    // because these settings are not inherited by subcommands.
+    routeErrorsToBoundary(program);
     return program;
 }
+/** Recursively make a command (and its subcommands) throw on error, silently. */
+function routeErrorsToBoundary(command) {
+    command.exitOverride();
+    command.configureOutput({ outputError: () => { } });
+    for (const sub of command.commands)
+        routeErrorsToBoundary(sub);
+}