@cruxy/cli 0.3.0 → 0.6.0

package/dist/errors/constructors.js

@@ -0,0 +1,329 @@
+import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { CruxyError, ErrorCode } from "./types.js";
+/**
+ * Helper constructors for {@link CruxyError}. Each encodes the title, the human
+ * cause, and the concrete next steps for one failure mode, so call sites stay a
+ * one-liner and the wording lives in one place. Lower-level errors are passed as
+ * `underlying` (preserved, shown only under `--verbose`).
+ */
+const ISSUE_URL = "https://github.com/cruxy-ai/cli/issues";
+/** Best-effort human message for an arbitrary thrown value. */
+export function messageOf(underlying) {
+    if (underlying instanceof Error)
+        return underlying.message;
+    if (underlying === undefined || underlying === null)
+        return undefined;
+    return String(underlying);
+}
+// ── usage (exit 2) ────────────────────────────────────────────────────────────
+export function usageError(title, nextSteps) {
+    return new CruxyError({
+        code: ErrorCode.Usage,
+        title,
+        nextSteps: nextSteps ?? ["run `cruxy --help` for usage"],
+    });
+}
+export function configKeyUnknown(key) {
+    return new CruxyError({
+        code: ErrorCode.ConfigKeyUnknown,
+        title: `no such config key: ${key}`,
+        nextSteps: ["run `cruxy config list` to see all available keys"],
+        meta: { key },
+    });
+}
+export function providerUnsupported(provider) {
+    return new CruxyError({
+        code: ErrorCode.ProviderUnsupported,
+        title: `provider "${provider}" does not support tool use`,
+        cause: "cruxy run drives an agent loop, which requires a tool-capable provider",
+        nextSteps: [
+            "switch to a tool-capable provider, e.g. `cruxy config set model.provider anthropic`",
+        ],
+        meta: { provider },
+    });
+}
+// ── config (exit 3) ───────────────────────────────────────────────────────────
+export function configParse(path, underlying) {
+    return new CruxyError({
+        code: ErrorCode.ConfigParse,
+        title: `could not parse config file: ${path}`,
+        cause: messageOf(underlying),
+        nextSteps: [
+            "fix the JSON syntax, or delete the file to fall back to defaults",
+        ],
+        underlying,
+        meta: { path },
+    });
+}
+export function configInvalid(issues, path) {
+    return new CruxyError({
+        code: ErrorCode.ConfigInvalid,
+        title: "the configuration is invalid",
+        cause: issues,
+        nextSteps: [
+            "correct the reported field(s)",
+            "see valid keys with `cruxy config list`",
+        ],
+        meta: path ? { path } : undefined,
+    });
+}
+// ── auth (exit 4) ─────────────────────────────────────────────────────────────
+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`,
+        nextSteps: [
+            `export ${envVar}=… in your shell (keys are read from the environment, never from config)`,
+        ],
+        meta: { provider, envVar },
+    });
+}
+export function authInvalid(underlying) {
+    return new CruxyError({
+        code: ErrorCode.AuthInvalid,
+        title: "the provider rejected your credentials",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "verify your API key is correct and active",
+            "re-export the key and try again",
+        ],
+        underlying,
+    });
+}
+// ── network (exit 5) ──────────────────────────────────────────────────────────
+export function gatewayUnreachable(underlying) {
+    return new CruxyError({
+        code: ErrorCode.GatewayUnreachable,
+        title: "could not reach the model gateway",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "check your internet connection",
+            "verify the gateway URL with `cruxy config get cruxy.gatewayUrl`",
+            "retry in a moment",
+        ],
+        underlying,
+    });
+}
+// ── api (exit 6) ──────────────────────────────────────────────────────────────
+export function apiError(underlying) {
+    const status = underlying instanceof ApiError ? underlying.status : undefined;
+    return new CruxyError({
+        code: ErrorCode.Api,
+        title: status
+            ? `the model provider returned an error (HTTP ${status})`
+            : "the model provider returned an error",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "retry in a moment; if it persists, check the provider's status",
+        ],
+        underlying,
+        meta: status ? { status } : undefined,
+    });
+}
+export function apiRateLimit(underlying) {
+    const retryAfterMs = underlying instanceof RateLimitError ? underlying.retryAfterMs : undefined;
+    return new CruxyError({
+        code: ErrorCode.ApiRateLimit,
+        title: "rate limited by the model provider",
+        cause: messageOf(underlying),
+        nextSteps: [
+            retryAfterMs
+                ? `wait ~${Math.ceil(retryAfterMs / 1000)}s and retry`
+                : "wait a moment and retry",
+        ],
+        underlying,
+        meta: retryAfterMs ? { retryAfterMs } : undefined,
+    });
+}
+export function apiOverloaded(underlying) {
+    return new CruxyError({
+        code: ErrorCode.ApiOverloaded,
+        title: "the model provider is overloaded",
+        cause: messageOf(underlying),
+        nextSteps: ["retry in a few moments"],
+        underlying,
+    });
+}
+export function budgetExhausted(underlying) {
+    return new CruxyError({
+        code: ErrorCode.BudgetExhausted,
+        title: "your Cruxy budget is exhausted",
+        cause: messageOf(underlying),
+        nextSteps: ["top up or raise your budget, then retry"],
+        underlying,
+    });
+}
+// ── filesystem (exit 7) ───────────────────────────────────────────────────────
+export function fileNotFound(path, underlying) {
+    return new CruxyError({
+        code: ErrorCode.FileNotFound,
+        title: `file not found: ${path}`,
+        cause: messageOf(underlying),
+        nextSteps: ["check the path and try again"],
+        underlying,
+        meta: { path },
+    });
+}
+export function permissionDenied(path, underlying) {
+    return new CruxyError({
+        code: ErrorCode.PermissionDenied,
+        title: `permission denied: ${path}`,
+        cause: messageOf(underlying),
+        nextSteps: ["check the file's permissions, or run with the right user"],
+        underlying,
+        meta: { path },
+    });
+}
+// ── index (exit 8) ────────────────────────────────────────────────────────────
+export function indexEmbedderUnavailable(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexEmbedderUnavailable,
+        title: "the local embedding model (fastembed) could not be loaded",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "reinstall dependencies with `pnpm install`",
+            "ensure the native onnxruntime-node addon built for your platform",
+        ],
+        underlying,
+    });
+}
+export function indexStoreUnavailable(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexStoreUnavailable,
+        title: "the codebase index store (SQLite) is unavailable",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "reinstall dependencies with `pnpm install` (better-sqlite3 must build), or set index.store = memory",
+        ],
+        underlying,
+    });
+}
+export function indexFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexFailed,
+        title: "building the codebase index failed",
+        cause: messageOf(underlying),
+        nextSteps: ["re-run with --verbose for details"],
+        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 },
+    });
+}
+// ── internal (exit 1) ─────────────────────────────────────────────────────────
+export function internal(underlying) {
+    return new CruxyError({
+        code: ErrorCode.Internal,
+        title: "an unexpected internal error occurred",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "re-run with --verbose (or --log-level debug) to see the underlying error",
+            `report it at ${ISSUE_URL} with the error code and details`,
+        ],
+        underlying,
+    });
+}
+/**
+ * Map a known provider/transport error (from `@cruxy/sdk`) to a typed
+ * {@link CruxyError}, or `null` if it isn't one. Order matters: specific
+ * subclasses before the `ApiError` base.
+ */
+export function classifyProviderError(underlying) {
+    if (underlying instanceof AuthError)
+        return authInvalid(underlying);
+    if (underlying instanceof RateLimitError)
+        return apiRateLimit(underlying);
+    if (underlying instanceof OverloadedError)
+        return apiOverloaded(underlying);
+    if (underlying instanceof NetworkError)
+        return gatewayUnreachable(underlying);
+    if (underlying instanceof ApiError) {
+        // BudgetExhaustedError isn't exported by the SDK; match by name.
+        if (underlying.name === "BudgetExhaustedError") {
+            return budgetExhausted(underlying);
+        }
+        return apiError(underlying);
+    }
+    return null;
+}

package/dist/errors/format.d.ts

@@ -0,0 +1,31 @@
+import { CruxyError } from "./types.js";
+/**
+ * Rendering for {@link CruxyError}, kept separate from the data so it's testable
+ * and swappable. {@link TerminalFormatter} renders the human, 4-part terminal
+ * form; a `JsonFormatter` for headless output can drop in behind the same
+ * {@link Formatter} interface later (out of scope here — this is the seam).
+ */
+export interface FormatOptions {
+    /** Append the underlying error's stack/message (hidden by default). */
+    verbose: boolean;
+    /** Emit ANSI color. Resolve with {@link shouldUseColor}. */
+    color: boolean;
+}
+export interface Formatter {
+    format(err: CruxyError, opts: FormatOptions): string;
+}
+/**
+ * Decide whether to colorize: honor `NO_COLOR` (disable) and `FORCE_COLOR`
+ * (enable), otherwise color only when writing to a TTY.
+ */
+export declare function shouldUseColor(stream?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
+/** The default terminal formatter: title, cause, next steps, code (+ verbose). */
+export declare class TerminalFormatter implements Formatter {
+    format(err: CruxyError, opts: FormatOptions): string;
+}
+/** The shared default instance. */
+export declare const terminalFormatter: TerminalFormatter;
+/** Convenience: render with the default terminal formatter. */
+export declare function formatError(err: CruxyError, opts: FormatOptions): string;

package/dist/errors/format.js

@@ -0,0 +1,60 @@
+import pc from "picocolors";
+/**
+ * Decide whether to colorize: honor `NO_COLOR` (disable) and `FORCE_COLOR`
+ * (enable), otherwise color only when writing to a TTY.
+ */
+export function shouldUseColor(stream = process.stderr, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "")
+        return true;
+    return Boolean(stream.isTTY);
+}
+/** The default terminal formatter: title, cause, next steps, code (+ verbose). */
+export class TerminalFormatter {
+    format(err, opts) {
+        const c = pc.createColors(opts.color);
+        const lines = [];
+        // 1. Title — one plain line, what failed.
+        lines.push(c.red(c.bold(err.title)));
+        // 2. Cause — the specific reason, when known.
+        if (err.cause)
+            lines.push(`${c.dim("Cause:")} ${err.cause}`);
+        // 3. Next step(s) — the concrete action(s) to take.
+        if (err.nextSteps.length > 0) {
+            lines.push("");
+            lines.push(c.bold("Next steps:"));
+            for (const step of err.nextSteps)
+                lines.push(`  ${c.cyan("→")} ${step}`);
+        }
+        // 4. Code — the stable, greppable id.
+        lines.push("");
+        lines.push(c.dim(`[${err.code}]`));
+        // Verbose-only: the preserved underlying error.
+        if (opts.verbose && err.underlying !== undefined) {
+            lines.push("");
+            lines.push(c.dim("Underlying error:"));
+            lines.push(indent(stackOf(err.underlying)));
+        }
+        return lines.join("\n");
+    }
+}
+/** The shared default instance. */
+export const terminalFormatter = new TerminalFormatter();
+/** Convenience: render with the default terminal formatter. */
+export function formatError(err, opts) {
+    return terminalFormatter.format(err, opts);
+}
+/** The stack (preferred) or message of an underlying error, as a string. */
+function stackOf(underlying) {
+    if (underlying instanceof Error) {
+        return underlying.stack ?? `${underlying.name}: ${underlying.message}`;
+    }
+    return String(underlying);
+}
+function indent(text, by = "  ") {
+    return text
+        .split("\n")
+        .map((line) => by + line)
+        .join("\n");
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./format.js";
+export * from "./constructors.js";
+export * from "./boundary.js";

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./format.js";
+export * from "./constructors.js";
+export * from "./boundary.js";

package/dist/errors/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The one error type for every user-facing failure (U.5). A {@link CruxyError}
+ * carries structured fields — title, optional human cause, next steps, a stable
+ * greppable {@link ErrorCode}, and a process exit code — while *formatting* lives
+ * separately (see `format.ts`). The raw underlying error is preserved but shown
+ * only under `--verbose`; no Node stack trace ever reaches the user by default.
+ */
+/**
+ * Stable, greppable error identifiers. The string value *is* the id that appears
+ * in output (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`) — grep for it in logs/issues.
+ * Grouped by category; each category maps to a distinct process exit code
+ * (see {@link exitCodeFor}).
+ */
+export declare const ErrorCode: {
+    readonly Internal: "CRUXY_E_INTERNAL";
+    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 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";
+    readonly IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE";
+    readonly IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE";
+    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";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** The process exit code for an error code (defaults to 1 for safety). */
+export declare function exitCodeFor(code: ErrorCode): number;
+export interface CruxyErrorInit {
+    /** Stable error id (drives the exit code and appears in output). */
+    code: ErrorCode;
+    /** One plain line: what failed. */
+    title: string;
+    /** The specific reason, when known. Always shown (part 2 of the standard). */
+    cause?: string;
+    /** Concrete actions the user can take. */
+    nextSteps?: string[];
+    /** Structured context (not rendered; for future JSON output / telemetry). */
+    meta?: Record<string, unknown>;
+    /** The original thrown error, preserved and shown only under `--verbose`. */
+    underlying?: unknown;
+    /** Override the exit code; defaults to {@link exitCodeFor}(code). */
+    exitCode?: number;
+}
+/**
+ * Every user-facing failure is (or becomes) one of these. Extends `Error` so it
+ * flows through normal throw/catch; `.message` mirrors `title` so logs and
+ * `instanceof Error` consumers stay useful.
+ */
+export declare class CruxyError extends Error {
+    readonly code: ErrorCode;
+    readonly title: string;
+    /** Human-readable reason (part 2). Narrows the inherited `Error.cause`. */
+    readonly cause?: string;
+    readonly nextSteps: string[];
+    readonly exitCode: number;
+    readonly meta?: Record<string, unknown>;
+    /** The wrapped lower-level error — rendered only under `--verbose`. */
+    readonly underlying?: unknown;
+    constructor(init: CruxyErrorInit);
+    /** Type guard — true for any CruxyError (across realms, via the brand). */
+    static is(err: unknown): err is CruxyError;
+}

package/dist/errors/types.js

@@ -0,0 +1,118 @@
+/**
+ * The one error type for every user-facing failure (U.5). A {@link CruxyError}
+ * carries structured fields — title, optional human cause, next steps, a stable
+ * greppable {@link ErrorCode}, and a process exit code — while *formatting* lives
+ * separately (see `format.ts`). The raw underlying error is preserved but shown
+ * only under `--verbose`; no Node stack trace ever reaches the user by default.
+ */
+/**
+ * Stable, greppable error identifiers. The string value *is* the id that appears
+ * in output (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`) — grep for it in logs/issues.
+ * Grouped by category; each category maps to a distinct process exit code
+ * (see {@link exitCodeFor}).
+ */
+export const ErrorCode = {
+    // internal (exit 1)
+    Internal: "CRUXY_E_INTERNAL",
+    // usage (exit 2)
+    Usage: "CRUXY_E_USAGE",
+    ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
+    ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
+    GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH",
+    // 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",
+    PathEscape: "CRUXY_E_PATH_ESCAPE",
+    // index (exit 8)
+    IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE",
+    IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE",
+    IndexFailed: "CRUXY_E_INDEX_FAILED",
+    // skill (exit 9)
+    SkillInvalid: "CRUXY_E_SKILL_INVALID",
+    SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND",
+    // approval (exit 10)
+    ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED",
+};
+/**
+ * Category exit codes. Distinct per category so a caller (CI, a script) can
+ * branch on *why* cruxy failed. Documented in the README error table.
+ */
+const EXIT_CODES = {
+    [ErrorCode.Internal]: 1,
+    [ErrorCode.Usage]: 2,
+    [ErrorCode.ConfigKeyUnknown]: 2,
+    [ErrorCode.ProviderUnsupported]: 2,
+    [ErrorCode.GitProtectedBranch]: 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,
+    [ErrorCode.IndexEmbedderUnavailable]: 8,
+    [ErrorCode.IndexStoreUnavailable]: 8,
+    [ErrorCode.IndexFailed]: 8,
+    [ErrorCode.SkillInvalid]: 9,
+    [ErrorCode.SkillNotFound]: 9,
+    [ErrorCode.ApprovalRequired]: 10,
+};
+/** The process exit code for an error code (defaults to 1 for safety). */
+export function exitCodeFor(code) {
+    return EXIT_CODES[code] ?? 1;
+}
+/**
+ * Every user-facing failure is (or becomes) one of these. Extends `Error` so it
+ * flows through normal throw/catch; `.message` mirrors `title` so logs and
+ * `instanceof Error` consumers stay useful.
+ */
+export class CruxyError extends Error {
+    code;
+    title;
+    /** Human-readable reason (part 2). Narrows the inherited `Error.cause`. */
+    cause;
+    nextSteps;
+    exitCode;
+    meta;
+    /** The wrapped lower-level error — rendered only under `--verbose`. */
+    underlying;
+    constructor(init) {
+        super(init.title);
+        this.name = "CruxyError";
+        this.code = init.code;
+        this.title = init.title;
+        this.cause = init.cause;
+        this.nextSteps = init.nextSteps ?? [];
+        this.meta = init.meta;
+        this.underlying = init.underlying;
+        this.exitCode = init.exitCode ?? exitCodeFor(init.code);
+    }
+    /** Type guard — true for any CruxyError (across realms, via the brand). */
+    static is(err) {
+        return err instanceof CruxyError;
+    }
+}

package/dist/index.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-import pc from "picocolors";
 import { buildProgram } from "./cli/program.js";
-import { logger } from "./utils/logger.js";
+import { handleFatal, isCommanderSuccess, isVerbose } from "./errors/index.js";
 async function main() {
     const program = buildProgram();
     await program.parseAsync(process.argv);
 }
 main().catch((err) => {
-    const message = err instanceof Error ? err.message : String(err);
-    logger.error(pc.red(message));
-    process.exit(1);
+    // Commander signals `--help` / `--version` by throwing with exit code 0 — that
+    // is success, not a failure. Everything else goes through the one boundary:
+    // CruxyError → formatted output + its exit code; unknown → CRUXY_E_INTERNAL,
+    // with the raw stack shown only under --verbose.
+    if (isCommanderSuccess(err))
+        process.exit(0);
+    handleFatal(err, { verbose: isVerbose() });
 });

package/dist/indexing/embedder.js

@@ -1,4 +1,5 @@
 import { promises as fs } from "node:fs";
+import { indexEmbedderUnavailable } from "../errors/index.js";
 import { l2normalize } from "./util.js";
 /**
  * Output dimensionality of bge-small-en-v1.5, and the default size of the
@@ -132,9 +133,8 @@ export async function createEmbedder(opts = {}) {
         await import("fastembed");
     }
     catch (err) {
-        throw new Error(`the local embedding model (fastembed) could not be loaded: ${err.message}. ` +
-            "It requires the onnxruntime-node native addon — reinstall with `pnpm install` and " +
-            "ensure the native build completed. The codebase index is unavailable until this is fixed.");
+        // Fail loud (the C.17 guarantee), now with a stable code + next steps.
+        throw indexEmbedderUnavailable(err);
     }
     return new FastEmbedEmbedder({ cacheDir: opts.cacheDir });
 }