@cruxy/cli 0.3.0 → 0.6.0

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("›")} `;
@@ -17,7 +18,7 @@ const defaultIO = () => ({
 /**
  * Read one line using a readline interface that is created and then **closed
  * before this resolves**. This is the crux of the stdin coordination: while a
- * turn runs (`session.send`), approvals grab stdin in raw mode via the Approver
+ * turn runs (`session.send`), approvals grab stdin in raw mode via the approval prompt
  * — so no readline interface may be live at that moment. Creating a fresh
  * interface per line, and closing it the instant we have input, guarantees the
  * two never contend.
@@ -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/config/schema.d.ts

@@ -52,10 +52,20 @@ export declare const ToolsConfigSchema: z.ZodObject<{
 }>;
 export declare const GitConfigSchema: z.ZodObject<{
     autoCommit: z.ZodDefault<z.ZodBoolean>;
+    /** Branches cruxy never commits/pushes to directly (PR flow branches off
+     * first). `main` and `master` are always protected; these add to them. */
+    protectedBranches: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Default base branch for generated pull requests; falls back to the
+     * repo's default branch, then `main`, when unset. */
+    defaultBase: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     autoCommit: boolean;
+    protectedBranches: string[];
+    defaultBase?: string | undefined;
 }, {
     autoCommit?: boolean | undefined;
+    protectedBranches?: string[] | undefined;
+    defaultBase?: string | undefined;
 }>;
 /** Execution bounds for the `run_command` shell tool (distinct from the
  * `tools.shell` enable flag above). */
@@ -89,13 +99,18 @@ export declare const ContextConfigSchema: z.ZodObject<{
     compactThreshold?: number | undefined;
     keepRecentMessages?: number | undefined;
 }>;
-/** How tool-action approval is resolved. */
+/**
+ * How tool-action approval is resolved. Only `prompt` exists: ask interactively
+ * and **deny by default** when non-interactive. There is deliberately no
+ * auto-approve / skip mode — the policy seam for a future CI mode lives in
+ * `src/approval` (see U.3), not behind a footgun flag.
+ */
 export declare const ApprovalConfigSchema: z.ZodObject<{
-    mode: z.ZodDefault<z.ZodEnum<["prompt", "auto"]>>;
+    mode: z.ZodDefault<z.ZodEnum<["prompt"]>>;
 }, "strict", z.ZodTypeAny, {
-    mode: "auto" | "prompt";
+    mode: "prompt";
 }, {
-    mode?: "auto" | "prompt" | undefined;
+    mode?: "prompt" | undefined;
 }>;
 /**
  * Codebase semantic index (C.17): the local embedding index that backs the
@@ -249,10 +264,20 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }>>;
     git: z.ZodDefault<z.ZodObject<{
         autoCommit: z.ZodDefault<z.ZodBoolean>;
+        /** Branches cruxy never commits/pushes to directly (PR flow branches off
+         * first). `main` and `master` are always protected; these add to them. */
+        protectedBranches: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Default base branch for generated pull requests; falls back to the
+         * repo's default branch, then `main`, when unset. */
+        defaultBase: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         autoCommit: boolean;
+        protectedBranches: string[];
+        defaultBase?: string | undefined;
     }, {
         autoCommit?: boolean | undefined;
+        protectedBranches?: string[] | undefined;
+        defaultBase?: string | undefined;
     }>>;
     shell: z.ZodDefault<z.ZodObject<{
         /** Kill the command (and its process tree) after this many ms. */
@@ -284,11 +309,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         keepRecentMessages?: number | undefined;
     }>>;
     approval: z.ZodDefault<z.ZodObject<{
-        mode: z.ZodDefault<z.ZodEnum<["prompt", "auto"]>>;
+        mode: z.ZodDefault<z.ZodEnum<["prompt"]>>;
     }, "strict", z.ZodTypeAny, {
-        mode: "auto" | "prompt";
+        mode: "prompt";
     }, {
-        mode?: "auto" | "prompt" | undefined;
+        mode?: "prompt" | undefined;
     }>>;
     index: z.ZodDefault<z.ZodObject<{
         /** Master switch for `search_codebase` and `cruxy index`. */
@@ -411,6 +436,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     };
     git: {
         autoCommit: boolean;
+        protectedBranches: string[];
+        defaultBase?: string | undefined;
     };
     context: {
         maxTokens: number;
@@ -418,7 +445,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         keepRecentMessages: number;
     };
     approval: {
-        mode: "auto" | "prompt";
+        mode: "prompt";
     };
     index: {
         search: {
@@ -466,6 +493,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     } | undefined;
     git?: {
         autoCommit?: boolean | undefined;
+        protectedBranches?: string[] | undefined;
+        defaultBase?: string | undefined;
     } | undefined;
     context?: {
         maxTokens?: number | undefined;
@@ -473,7 +502,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         keepRecentMessages?: number | undefined;
     } | undefined;
     approval?: {
-        mode?: "auto" | "prompt" | undefined;
+        mode?: "prompt" | undefined;
     } | undefined;
     index?: {
         search?: {

package/dist/config/schema.js

@@ -40,6 +40,12 @@ export const ToolsConfigSchema = z
 export const GitConfigSchema = z
     .object({
     autoCommit: z.boolean().default(false),
+    /** Branches cruxy never commits/pushes to directly (PR flow branches off
+     * first). `main` and `master` are always protected; these add to them. */
+    protectedBranches: z.array(z.string()).default([]),
+    /** Default base branch for generated pull requests; falls back to the
+     * repo's default branch, then `main`, when unset. */
+    defaultBase: z.string().optional(),
 })
     .strict();
 /** Execution bounds for the `run_command` shell tool (distinct from the
@@ -64,12 +70,15 @@ export const ContextConfigSchema = z
     keepRecentMessages: z.number().int().positive().default(6),
 })
     .strict();
-/** How tool-action approval is resolved. */
+/**
+ * How tool-action approval is resolved. Only `prompt` exists: ask interactively
+ * and **deny by default** when non-interactive. There is deliberately no
+ * auto-approve / skip mode — the policy seam for a future CI mode lives in
+ * `src/approval` (see U.3), not behind a footgun flag.
+ */
 export const ApprovalConfigSchema = z
     .object({
-    // "prompt": ask interactively (deny when non-interactive). "auto": approve
-    // every action unattended (CI / explicit opt-in).
-    mode: z.enum(["prompt", "auto"]).default("prompt"),
+    mode: z.enum(["prompt"]).default("prompt"),
 })
     .strict();
 /**

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,52 @@
+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;
+/**
+ * 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 declare function approvalRequired(summary: string): CruxyError;
+/**
+ * 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 declare function forgeAuth(host?: string): CruxyError;
+/**
+ * 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 declare function gitProtectedBranch(branch: string): CruxyError;
+/** The forge REST API returned an error (non-auth) while opening a PR. */
+export declare function forgeApi(title: string, underlying?: unknown, meta?: Record<string, unknown>): CruxyError;
+/**
+ * `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 declare function gitPushFailed(branch: string, stderr?: string): 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;