@cruxy/cli 0.2.0 → 0.4.0

package/README.md

@@ -25,12 +25,18 @@ cruxy run                           # interactive session
 ## Features
 
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
-  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`.
+  `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
+  `list_skills`, `load_skill`.
 - **Codebase index** — a local, incremental semantic index (`cruxy index`)
   behind the `search_codebase` tool. Embeddings run on-device via fastembed
   (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at
   `.cruxy/index.db`. Only changed files are re-embedded; `.gitignore` /
   `.cruxyignore` are respected and secrets (`.env*`, keys) are never indexed.
+- **Skills** — reusable, task-specific instructions in a `SKILL.md`
+  (frontmatter + markdown), discovered via `list_skills` and pulled on demand
+  with `load_skill` (progressive disclosure: only name + description are in
+  context until a skill is loaded). Layered project > user > builtin, strictly
+  validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
 - **Safety** — a single approval gate with diff previews that fails closed;
@@ -53,6 +59,38 @@ The index refreshes itself lazily the first time the agent calls
 `search_codebase`, so it works even without running `cruxy index` first. The
 bge-small embedding model (~130 MB) downloads and caches on first use.
 
+### Skills
+
+```bash
+cruxy skills            # list the resolved skill catalog
+cruxy skills --status   # show source directories and validation errors
+```
+
+Add a skill by creating `<name>/SKILL.md` under `.cruxy/skills/` (project) or
+`~/.cruxy/skills/` (user); shipped builtins are the lowest layer. See the
+built-in `using-skills` skill for the authoring rules.
+
+## Errors & exit codes
+
+Every user-facing error prints a title, the cause (when known), concrete next
+steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
+(or `--log-level debug` / `DEBUG=1`) to see the underlying error and stack;
+`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`                   |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`                                              |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`                                                                   |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`   |
+| `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`                                              |
+
 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.js

@@ -1,3 +1,4 @@
+import { providerUnsupported } from "../errors/index.js";
 import { buildSystemPrompt } from "./prompts.js";
 /**
  * Drive the model/tool loop over an existing conversation. Streams each turn,
@@ -11,7 +12,7 @@ import { buildSystemPrompt } from "./prompts.js";
 export async function runAgent(args) {
     const { provider, registry, config, ctx } = args;
     if (!provider.supportsTools) {
-        throw new Error(`provider ${config.model.provider} does not support tool use; cruxy run requires a tool-capable provider`);
+        throw providerUnsupported(config.model.provider);
     }
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the

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/run.js

@@ -3,6 +3,7 @@ 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 { buildDefaultRegistry } from "../../tools/index.js";
 import { Session, createApprover } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
@@ -20,16 +21,14 @@ export function runCommand() {
         // 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,
@@ -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/commands/skills.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy skills` — list the skills available to the agent (the same catalog the
+ * `list_skills` tool sees). `--status` additionally shows the three source
+ * directories in precedence order and any validation errors (skills that were
+ * excluded for being malformed).
+ */
+export declare function skillsCommand(): Command;

package/dist/cli/commands/skills.js

@@ -0,0 +1,51 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { getSkillService, resetSkillServices } from "../../skills/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy skills` — list the skills available to the agent (the same catalog the
+ * `list_skills` tool sees). `--status` additionally shows the three source
+ * directories in precedence order and any validation errors (skills that were
+ * excluded for being malformed).
+ */
+export function skillsCommand() {
+    return new Command("skills")
+        .description("list the skills available to the agent")
+        .option("--status", "show source directories and validation errors")
+        .action(async (opts) => {
+        const service = getSkillService(process.cwd(), logger);
+        const status = await service.status();
+        if (status.entries.length === 0) {
+            logger.print(pc.dim("no skills found"));
+        }
+        else {
+            for (const entry of status.entries) {
+                logger.print(`${pc.bold(entry.name)}  ${pc.dim(`[${entry.source}]`)}`);
+                logger.print(`  ${entry.description}`);
+            }
+        }
+        if (!opts.status) {
+            if (status.errors.length > 0) {
+                logger.print(pc.yellow(`\n${status.errors.length} skill(s) failed validation — run ${pc.bold("cruxy skills --status")} for details`));
+            }
+            resetSkillServices();
+            return;
+        }
+        logger.print(`\n${pc.bold("sources")} ${pc.dim("(precedence high → low):")}`);
+        for (const { source, dir } of status.sources) {
+            logger.print(`  ${source.padEnd(8)} ${pc.dim(dir)}`);
+        }
+        logger.print("");
+        if (status.errors.length === 0) {
+            logger.print(pc.green("no validation errors"));
+        }
+        else {
+            logger.print(pc.yellow(`validation errors (${status.errors.length}):`));
+            for (const err of status.errors) {
+                logger.print(`  ${pc.red("✗")} ${pc.bold(err.name)} ${pc.dim(`[${err.source}]`)}: ${err.message}`);
+                logger.print(`    ${pc.dim(err.dir)}`);
+            }
+        }
+        resetSkillServices();
+    });
+}

package/dist/cli/program.js

@@ -2,9 +2,11 @@ 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";
 export function buildProgram() {
     const program = new Command();
     program
@@ -13,8 +15,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();
@@ -26,13 +27,34 @@ export function buildProgram() {
     program.addCommand(runCommand());
     program.addCommand(configCommand());
     program.addCommand(indexCommand());
-    // Default action: no subcommand -> interactive entrypoint (stub for now).
-    program.action(() => {
+    program.addCommand(skillsCommand());
+    // 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);
+}

package/dist/cli/repl.js

@@ -1,5 +1,6 @@
 import readline from "node:readline";
 import pc from "picocolors";
+import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
 import { createStreamPrinter } from "./stream-print.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
@@ -49,6 +50,18 @@ function readLine(io, prompt) {
         });
     });
 }
+/**
+ * Render a non-fatal error inline (classified + formatted, the same 4-part
+ * shape as the fatal boundary) and return to the prompt — the REPL must survive
+ * a failed turn rather than exit.
+ */
+function printReplError(err) {
+    const cruxy = fromUnknown(err);
+    logger.print(formatError(cruxy, {
+        verbose: isVerbose(),
+        color: shouldUseColor(process.stdout),
+    }));
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text streams to stdout from within
@@ -83,7 +96,7 @@ export async function runInteractive(session, io = defaultIO()) {
                 logger.print(pc.dim(n ? `compacted ${n} older messages` : "nothing to compact yet"));
             }
             catch (err) {
-                logger.error(err.message);
+                printReplError(err);
             }
             continue;
         }

package/dist/config/manager.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { configInvalid, configParse } from "../errors/index.js";
 import { CruxyConfigSchema } from "./schema.js";
 import { globalConfigPath, findProjectConfig } from "./paths.js";
 function isPlainObject(v) {
@@ -23,13 +24,13 @@ function readJsonFile(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
         if (!isPlainObject(parsed)) {
-            throw new Error(`config at ${path} must be a JSON object`);
+            throw configParse(path, new Error("top-level value is not a JSON object"));
         }
         return parsed;
     }
     catch (err) {
         if (err instanceof SyntaxError) {
-            throw new Error(`config at ${path} is not valid JSON: ${err.message}`);
+            throw configParse(path, err);
         }
         throw err;
     }
@@ -81,7 +82,7 @@ export function loadConfig(opts = {}) {
         const issues = result.error.issues
             .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
             .join("\n");
-        throw new Error(`invalid configuration:\n${issues}`);
+        throw configInvalid(issues, sources.project ?? sources.global ?? undefined);
     }
     return { config: result.data, sources };
 }
@@ -121,7 +122,7 @@ export function setValue(path, rawValue, file) {
         const issues = check.error.issues
             .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
             .join("\n");
-        throw new Error(`refusing to write invalid config:\n${issues}`);
+        throw configInvalid(issues, file);
     }
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(current, null, 2) + "\n", "utf8");

package/dist/constants.d.ts

@@ -9,3 +9,16 @@ export declare const CONFIG_FILE_NAME = "config.json";
 export declare const PROJECT_CONFIG_FILENAMES: string[];
 /** Project-instruction filenames, checked in order (first match wins). */
 export declare const PROJECT_INSTRUCTION_FILENAMES: string[];
+/**
+ * Name of the skills subdirectory, used under the project dir
+ * (`<cwd>/.cruxy/skills`), the global dir (`~/.cruxy/skills`), and the package
+ * root for shipped builtins.
+ */
+export declare const SKILLS_DIR_NAME = "skills";
+/**
+ * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
+ * Anchored the same way as the package.json lookup above: both `dist/` and
+ * `src/` sit one level below the package root, so `../skills` resolves to the
+ * shipped `skills/` directory in dev, in `dist`, and when published.
+ */
+export declare const BUILTIN_SKILLS_DIR: string;

package/dist/constants.js

@@ -29,3 +29,16 @@ export const PROJECT_CONFIG_FILENAMES = [
 ];
 /** Project-instruction filenames, checked in order (first match wins). */
 export const PROJECT_INSTRUCTION_FILENAMES = ["CRUXY.md", "AGENTS.md"];
+/**
+ * Name of the skills subdirectory, used under the project dir
+ * (`<cwd>/.cruxy/skills`), the global dir (`~/.cruxy/skills`), and the package
+ * root for shipped builtins.
+ */
+export const SKILLS_DIR_NAME = "skills";
+/**
+ * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
+ * Anchored the same way as the package.json lookup above: both `dist/` and
+ * `src/` sit one level below the package root, so `../skills` resolves to the
+ * shipped `skills/` directory in dev, in `dist`, and when published.
+ */
+export const BUILTIN_SKILLS_DIR = join(__dirname, "..", SKILLS_DIR_NAME);

package/dist/errors/boundary.d.ts

@@ -0,0 +1,43 @@
+import { type Formatter } from "./format.js";
+import { CruxyError } from "./types.js";
+/**
+ * The single top-level error boundary. {@link handleFatal} classifies any thrown
+ * value into a {@link CruxyError}, formats it, writes it to stderr, and exits
+ * with the error's stable exit code. Nothing escapes to a raw Node stack trace:
+ * an unknown error becomes {@link internal} (CRUXY_E_INTERNAL) with a
+ * bug-report hint, and the underlying stack is shown only under `--verbose`.
+ */
+/**
+ * Normalize any thrown value into a {@link CruxyError}:
+ * - already a CruxyError → returned as-is;
+ * - a Commander parse error → a usage error (CRUXY_E_USAGE);
+ * - a known provider/transport error → its mapped code;
+ * - anything else → CRUXY_E_INTERNAL, preserving the original as `underlying`.
+ */
+export declare function fromUnknown(err: unknown): CruxyError;
+/** A Commander "error" that's actually success (`--help`, `--version`). */
+export declare function isCommanderSuccess(err: unknown): boolean;
+export interface HandleFatalOptions {
+    /** Show the underlying error/stack. Defaults to {@link isVerbose}(). */
+    verbose?: boolean;
+    /** Override the formatter (e.g. a future JSON formatter). */
+    formatter?: Formatter;
+    /** Force color on/off. Defaults to {@link shouldUseColor}(). */
+    color?: boolean;
+    /** Sink for the formatted output (default: stderr). For tests. */
+    write?: (text: string) => void;
+    /** Process exit (default: process.exit). For tests. */
+    exit?: (code: number) => never;
+}
+/**
+ * Classify → format → print → exit. Install this as the *only* catch at the CLI
+ * entry. `write`/`exit` are injectable so the boundary is testable without
+ * touching the real process.
+ */
+export declare function handleFatal(err: unknown, opts?: HandleFatalOptions): never;
+/**
+ * Whether the invocation requested verbose output: `--verbose`,
+ * `--log-level debug`, `DEBUG`, or `CRUXY_LOG_LEVEL=debug`. Read from argv/env so
+ * it works even when a failure happens before the CLI finishes parsing flags.
+ */
+export declare function isVerbose(argv?: string[], env?: NodeJS.ProcessEnv): boolean;

package/dist/errors/boundary.js

@@ -0,0 +1,73 @@
+import { CommanderError } from "commander";
+import { classifyProviderError, internal, usageError } from "./constructors.js";
+import { shouldUseColor, terminalFormatter } from "./format.js";
+import { CruxyError } from "./types.js";
+/**
+ * The single top-level error boundary. {@link handleFatal} classifies any thrown
+ * value into a {@link CruxyError}, formats it, writes it to stderr, and exits
+ * with the error's stable exit code. Nothing escapes to a raw Node stack trace:
+ * an unknown error becomes {@link internal} (CRUXY_E_INTERNAL) with a
+ * bug-report hint, and the underlying stack is shown only under `--verbose`.
+ */
+/**
+ * Normalize any thrown value into a {@link CruxyError}:
+ * - already a CruxyError → returned as-is;
+ * - a Commander parse error → a usage error (CRUXY_E_USAGE);
+ * - a known provider/transport error → its mapped code;
+ * - anything else → CRUXY_E_INTERNAL, preserving the original as `underlying`.
+ */
+export function fromUnknown(err) {
+    if (err instanceof CruxyError)
+        return err;
+    if (err instanceof CommanderError) {
+        return usageError(stripErrorPrefix(err.message));
+    }
+    return classifyProviderError(err) ?? internal(err);
+}
+/** A Commander "error" that's actually success (`--help`, `--version`). */
+export function isCommanderSuccess(err) {
+    return err instanceof CommanderError && err.exitCode === 0;
+}
+/**
+ * Classify → format → print → exit. Install this as the *only* catch at the CLI
+ * entry. `write`/`exit` are injectable so the boundary is testable without
+ * touching the real process.
+ */
+export function handleFatal(err, opts = {}) {
+    const cruxy = fromUnknown(err);
+    const verbose = opts.verbose ?? isVerbose();
+    const color = opts.color ?? shouldUseColor();
+    const formatter = opts.formatter ?? terminalFormatter;
+    const write = opts.write ?? ((text) => void process.stderr.write(text));
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    write(`${formatter.format(cruxy, { verbose, color })}\n`);
+    return exit(cruxy.exitCode);
+}
+/**
+ * Whether the invocation requested verbose output: `--verbose`,
+ * `--log-level debug`, `DEBUG`, or `CRUXY_LOG_LEVEL=debug`. Read from argv/env so
+ * it works even when a failure happens before the CLI finishes parsing flags.
+ */
+export function isVerbose(argv = process.argv, env = process.env) {
+    if (argv.includes("--verbose"))
+        return true;
+    if (argv.includes("--log-level=debug"))
+        return true;
+    const idx = argv.indexOf("--log-level");
+    if (idx !== -1 && argv[idx + 1] === "debug")
+        return true;
+    if (env.CRUXY_LOG_LEVEL === "debug")
+        return true;
+    const debug = env.DEBUG;
+    if (debug !== undefined &&
+        debug !== "" &&
+        debug !== "0" &&
+        debug !== "false") {
+        return true;
+    }
+    return false;
+}
+/** Strip Commander's leading "error: " so the title reads cleanly. */
+function stripErrorPrefix(message) {
+    return message.replace(/^error:\s*/i, "");
+}

package/dist/errors/constructors.d.ts

@@ -0,0 +1,27 @@
+import { CruxyError } from "./types.js";
+/** Best-effort human message for an arbitrary thrown value. */
+export declare function messageOf(underlying: unknown): string | undefined;
+export declare function usageError(title: string, nextSteps?: string[]): CruxyError;
+export declare function configKeyUnknown(key: string): CruxyError;
+export declare function providerUnsupported(provider: string): CruxyError;
+export declare function configParse(path: string, underlying?: unknown): CruxyError;
+export declare function configInvalid(issues: string, path?: string): CruxyError;
+export declare function authMissingKey(provider: string, envVar: string): CruxyError;
+export declare function authInvalid(underlying?: unknown): CruxyError;
+export declare function gatewayUnreachable(underlying?: unknown): CruxyError;
+export declare function apiError(underlying?: unknown): CruxyError;
+export declare function apiRateLimit(underlying?: unknown): CruxyError;
+export declare function apiOverloaded(underlying?: unknown): CruxyError;
+export declare function budgetExhausted(underlying?: unknown): CruxyError;
+export declare function fileNotFound(path: string, underlying?: unknown): CruxyError;
+export declare function permissionDenied(path: string, underlying?: unknown): CruxyError;
+export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
+export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
+export declare function indexFailed(underlying?: unknown): CruxyError;
+export declare function internal(underlying?: unknown): CruxyError;
+/**
+ * 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 declare function classifyProviderError(underlying: unknown): CruxyError | null;