@cruxy/cli 1.10.0 → 1.11.1

package/dist/components/keys.js

@@ -26,6 +26,22 @@ const CBT = 0x5a;
  * not rejected, so these are matched on the leading number instead.
  */
 const TILDE = 0x7e;
+/**
+ * The two mouse encodings a terminal can answer `?1000h` with.
+ *
+ * SGR (`?1006h`, the one the TUI asks for) sends `ESC [ < Cb ; Cx ; Cy M` for
+ * a press and `… m` for a release, all in printable ASCII. A terminal that does
+ * not know SGR falls back to X10: `ESC [ M` followed by THREE RAW BYTES
+ * (button+32, column+32, row+32). The X10 form has to be recognised even though
+ * it is never requested, because the alternative is worse than an unmapped key:
+ * the generic CSI rule below would stop at the `M`, and the three bytes after
+ * it — printable, by construction — would land in the input line as text.
+ */
+const SGR_MOUSE_INTRO = 0x3c; // <
+const X10_MOUSE_FINAL = 0x4d; // M
+/** Bit 6 of the button code marks a wheel event; bit 0 says which way. */
+const MOUSE_WHEEL_FLAG = 64;
+const X10_MOUSE_PAYLOAD = 3;
 /** Leading `~`-sequence parameter → key. `ESC [ 5 ~` / `ESC [ 6 ~`. */
 const TILDES = {
     5: "page-up",
@@ -43,9 +59,10 @@ const ARROWS = {
  * keys per chunk; all are returned in order.
  *
  * Escape handling is deliberately simple: `ESC [ A..D` decodes to an arrow,
- * `ESC [ … Z` decodes to Shift+Tab, any other CSI sequence (`ESC [ …final`) is
- * swallowed whole (unmapped keys must not leak garbage chars into a query), and
- * a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
+ * `ESC [ … Z` decodes to Shift+Tab, a mouse report (SGR `ESC [ < … M`, or X10
+ * `ESC [ M` + 3 bytes) decodes to a wheel notch or to nothing, any other CSI
+ * sequence (`ESC [ …final`) is swallowed whole (unmapped keys must not leak
+ * garbage chars into a query), and a lone ESC decodes to `escape`. Terminals send arrow sequences atomically in practice; a sequence
  * split across chunks degrades to `escape` + literal chars, which is safe
  * (escape cancels).
  */
@@ -56,12 +73,44 @@ export function decodeKeys(chunk) {
         const byte = buf[i];
         if (byte === ESC) {
             if (buf[i + 1] === 0x5b /* [ */) {
+                // X10 mouse: `ESC [ M` plus three raw payload bytes. Consumed as one
+                // unit BEFORE the generic CSI walk, which would otherwise treat `M` as
+                // the final byte and hand the payload to the printable branch.
+                if (buf[i + 2] === X10_MOUSE_FINAL) {
+                    const end = i + 3 + X10_MOUSE_PAYLOAD;
+                    if (end <= buf.length) {
+                        const wheel = mouseWheel(buf[i + 3] - 32);
+                        if (wheel)
+                            keys.push({ kind: wheel });
+                        i = end;
+                        continue;
+                    }
+                    // Truncated at the chunk boundary: the same degradation as any other
+                    // partial CSI — escape, and drop the tail.
+                    keys.push({ kind: "escape" });
+                    i = buf.length;
+                    continue;
+                }
                 // CSI: consume parameter/intermediate bytes (0x20–0x3f) up to the
                 // final byte (0x40–0x7e); map arrows, swallow everything else.
                 let j = i + 2;
                 while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x3f)
                     j++;
                 if (j < buf.length) {
+                    if (buf[i + 2] === SGR_MOUSE_INTRO) {
+                        // SGR mouse: `ESC [ < Cb ; Cx ; Cy M|m`. Only the button code is
+                        // read — the wheel has no position — and a press is the only edge
+                        // a wheel has, so `m` (release) never maps to anything.
+                        let cb = 0;
+                        for (let k = i + 3; k < j && buf[k] >= 0x30 && buf[k] <= 0x39; k++) {
+                            cb = cb * 10 + (buf[k] - 0x30);
+                        }
+                        const wheel = buf[j] === X10_MOUSE_FINAL ? mouseWheel(cb) : null;
+                        if (wheel)
+                            keys.push({ kind: wheel });
+                        i = j + 1;
+                        continue;
+                    }
                     if (buf[j] === CBT) {
                         // Shift+Tab, in BOTH its forms: bare `ESC [ Z`, and the
                         // parameterized `ESC [ 1 ; 2 Z` some terminals send when a modifier
@@ -165,3 +214,17 @@ export function decodeKeys(chunk) {
     }
     return keys;
 }
+/**
+ * A mouse button code → the wheel direction it encodes, or null for any other
+ * mouse event. Modifier bits (shift 4, meta 8, ctrl 16) are masked off so a
+ * wheel with a modifier held still scrolls; the low two bits pick the direction.
+ */
+function mouseWheel(button) {
+    if ((button & MOUSE_WHEEL_FLAG) === 0)
+        return null;
+    return (button & 3) === 0
+        ? "wheel-up"
+        : (button & 3) === 1
+            ? "wheel-down"
+            : null;
+}

package/dist/config/manager.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { configInvalid, configParse, mcpProjectHeaders, } from "../errors/index.js";
-import { CruxyConfigSchema } from "./schema.js";
+import { configInvalid, configNotFound, configParse, mcpProjectHeaders, } from "../errors/index.js";
+import { CruxyConfigSchema, } from "./schema.js";
 import { globalConfigPath, findProjectConfig } from "./paths.js";
 import { readCredential } from "./credentials.js";
 function isPlainObject(v) {
@@ -90,6 +90,39 @@ function envOverrides() {
     }
     return out;
 }
+/**
+ * The `--config <path>` this process was invoked with, or null.
+ *
+ * PROCESS-WIDE RATHER THAN THREADED, because the flag is a property of the
+ * INVOCATION: every read of the config in one run must resolve the same file,
+ * and there are ~20 `loadConfig()` call sites. Two of them cannot take an
+ * argument at all — the credential-expiry probe in `src/index.ts` runs from the
+ * error boundary, after the command that would have carried the path has
+ * already thrown, and the Settings view's `reload` is a zero-argument callback
+ * held for a whole session. Threading would wire the sites that are easy to
+ * reach and leave those two reading a *different* config than the command they
+ * belong to, which is the same silent divergence this flag was filed for
+ * (#289).
+ *
+ * Set once from the `preAction` hook that already applies the other global
+ * options (`cli/program.ts`), alongside `logger.setLevel`. An explicit
+ * {@link LoadOptions.configPath} still wins, so a caller that names a file is
+ * unaffected.
+ */
+let cliConfigPath = null;
+/**
+ * Record the `--config <path>` for this process. Returns the previous value so
+ * a test can restore it; pass null to clear.
+ */
+export function setCliConfigPath(path) {
+    const previous = cliConfigPath;
+    cliConfigPath = path;
+    return previous;
+}
+/** The `--config <path>` in effect for this process, or null. */
+export function cliConfigPathInEffect() {
+    return cliConfigPath;
+}
 /**
  * Resolution order (later wins):
  *   schema defaults -> global file -> project file (or explicit) -> env vars
@@ -113,12 +146,21 @@ export function loadConfig(opts = {}) {
         merged = deepMerge(merged, layers.global);
         sources.global = gPath;
     }
-    if (opts.configPath) {
-        const obj = readJsonFile(opts.configPath);
-        rejectProjectScopeHeaders(obj, opts.configPath);
+    // `--config` (recorded process-wide) unless this caller named a file itself.
+    const configPath = opts.configPath ?? cliConfigPath ?? undefined;
+    if (configPath) {
+        // A named file that is not there is a MISTAKE, never a fall-through to
+        // discovery or defaults: silently running the default config for a path
+        // someone typed is precisely the failure #289 is about, wearing the other
+        // hat. The global and project layers are `existsSync`-guarded above because
+        // absence there is the normal case; here absence is the error.
+        if (!existsSync(configPath))
+            throw configNotFound(configPath);
+        const obj = readJsonFile(configPath);
+        rejectProjectScopeHeaders(obj, configPath);
         layers.explicit = obj;
         merged = deepMerge(merged, obj);
-        sources.explicit = opts.configPath;
+        sources.explicit = configPath;
     }
     else {
         const pPath = findProjectConfig(opts.cwd);
@@ -137,10 +179,28 @@ export function loadConfig(opts = {}) {
         const issues = result.error.issues
             .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
             .join("\n");
-        throw configInvalid(issues, sources.project ?? sources.global ?? undefined);
+        throw configInvalid(issues, configSourceFile(sources) ?? undefined);
     }
     return { config: result.data, sources, layers };
 }
+/**
+ * The file to NAME for the config as a whole — the nearest winning source, in
+ * the precedence order the merge itself used.
+ *
+ * `explicit` COMES FIRST, and that is the whole point: an explicit file
+ * REPLACES project discovery, so when `--config` is in play `sources.project`
+ * is null and a `project ?? global` fallback silently names the *global* file.
+ * A user fixing the field an error reports would then be editing a file that
+ * contributed nothing to it (#289).
+ *
+ * This is the whole-config counterpart to `originFile` in `effective.ts`, which
+ * answers the same question per key. It lives here, next to the `sources` it
+ * reads, so `loadConfig`'s own error path can use it without importing
+ * `effective.ts` (which imports this module).
+ */
+export function configSourceFile(sources) {
+    return sources.explicit ?? sources.project ?? sources.global ?? null;
+}
 /** Resolve a dot-path (e.g. "model.temperature") against a config object. */
 export function getPath(obj, path) {
     return path
@@ -205,13 +265,33 @@ export function resolveApiKey(provider) {
 function envApiKey(provider) {
     return process.env[apiKeyEnvVar(provider)];
 }
+/**
+ * Provider id → the environment variable its API key is read from.
+ *
+ * A TOTAL RECORD OVER `Provider`, not a switch with a default, because that is
+ * what makes the mapping self-maintaining: adding a provider to
+ * {@link ProviderSchema} makes this object a compile error until its env var is
+ * named. A `default:` arm silently answers `CRUXY_API_KEY` for a provider
+ * nobody has thought about yet, which is the failure mode #285 is named for —
+ * the copy that drifts is always the one telling the user where to put their
+ * key.
+ */
+const API_KEY_ENV_VAR = {
+    cruxy: "CRUXY_API_KEY",
+};
 /**
  * The environment variable a provider's API key is read from — the NAME only,
  * never the value, so a surface can say where a key would come from without
- * ever holding one. Exported so nothing has to restate this mapping: a second
- * copy would drift the moment a provider is added, and the copy that drifts is
- * always the one telling the user where to put their key.
+ * ever holding one.
+ *
+ * THE one definition. It was exported to prevent restatement and said so at the
+ * site, and two copies were written anyway (`cli/onboard.ts`,
+ * `cli/commands/pr.ts`), both carrying an `"openai"` branch that #284 had made
+ * unreachable — invisible because all three took `string`. The parameter is
+ * {@link Provider} now: an id the config layer would refuse no longer type-checks
+ * here, so the next such branch is a build failure rather than dead code that
+ * reads as live (#285).
  */
 export function apiKeyEnvVar(provider) {
-    return provider === "openai" ? "OPENAI_API_KEY" : "CRUXY_API_KEY";
+    return API_KEY_ENV_VAR[provider];
 }

package/dist/config/schema.js

@@ -133,7 +133,14 @@ export const ContextConfigSchema = z
      * sees — the system prompt and every tool's JSON schema — added to the
      * measured history before the threshold test so the trigger reflects the
      * real request size, not just the visible messages. Roughly the size of
-     * the built system prompt plus the default tool catalogue today.
+     * the built system prompt plus the default tool catalogue today (about
+     * 3.7k measured for the prompt and 14 tool schemas).
+     *
+     * An ALLOWANCE, not a measurement — the context panel and `/context` say
+     * so. It is the same number on every turn, so it does not track the parts
+     * of a request that vary: CRUXY.md, recalled memory, LSP context, web
+     * results and MCP tool schemas all make the real request larger without
+     * moving it. Raise it if a project carries a lot of those.
      */
     reserveTokens: z.number().int().nonnegative().default(4500),
     /** Most-recent messages always kept verbatim (a floor; the cut rounds up to
@@ -391,13 +398,47 @@ export const JobsConfigSchema = z
      */
     maxJobs: z.number().int().positive().default(5),
     /**
-     * How many of a job's most-recent log lines are retained in its ring buffer
-     * for `cruxy logs <id>`. Bounded so a chatty job can't grow memory without
-     * limit; older lines roll off oldest-first. Default 1000.
+     * How many of a job's most-recent log lines are retained in its IN-MEMORY
+     * ring buffer, which is what `/logs <id>` and the Tasks view read while the
+     * session is alive. Bounded so a chatty job can't grow memory without
+     * limit; older lines roll off oldest-first and `/logs` says how many.
+     * Default 1000.
+     *
+     * This is no longer the only copy: {@link logFileLines} bounds the
+     * persisted one, which `cruxy logs <id>` reads back after the fact.
      */
     logBufferLines: z.number().int().positive().default(1000),
+    /**
+     * How many lines of a job's output are written to its file under
+     * `~/.cruxy/projects/<project>/subagents/` (#172 item 1). Past this the log
+     * records one honest `truncated` marker and stops; the job runs on.
+     *
+     * WHY A SECOND, LARGER BOUND rather than reusing {@link logBufferLines}.
+     * The file exists precisely to remove the ring buffer's drop-on-overflow,
+     * so a file bounded at the buffer's size would persist the same truncated
+     * tail and buy nothing — which is why this is FLOORED at `logBufferLines`
+     * rather than allowed to sink below it (see the refinement below).
+     *
+     * WHY IT IS BOUNDED AT ALL. `sessions.retention` bounds how many session-
+     * shaped things the tree keeps; nothing bounds how big ONE of them gets,
+     * and a background job is the first writer here that can produce unbounded
+     * output unattended — it runs a full agent loop off screen, and a job stuck
+     * in a tool-call loop emits lines for as long as its budget lasts with
+     * nobody watching. Streaming that to disk uncapped is the second unbounded
+     * writer under `~/.cruxy` that #257 exists to prevent.
+     *
+     * 20000 is 20x the in-memory buffer: roughly 2 MB for a worst-case job, and
+     * the sweep drops a `done` job's log at the next start, so the steady-state
+     * cost of the default is near zero.
+     */
+    logFileLines: z.number().int().positive().default(20000),
 })
-    .strict();
+    .strict()
+    .refine((j) => j.logFileLines >= j.logBufferLines, {
+    message: "jobs.logFileLines must be at least jobs.logBufferLines — the persisted log " +
+        "exists to remove the ring buffer's drop-on-overflow, and a file that kept " +
+        "fewer lines than memory would make persisting strictly worse than not persisting",
+});
 /**
  * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
  * When enabled, `run_command` and `run_tests` execute inside an isolated,
@@ -461,17 +502,25 @@ export const HooksConfigSchema = z
 /**
  * Multi-model routing (C.30): map declared task classes to tiers so mechanical
  * work runs on a cheap tier and hard reasoning on a strong one. Fully opt-in —
- * with an empty `map` and no `default`, every task class routes to the session's
- * single tier and behavior is unchanged (routing stays inert until configured).
- * Only tier names appear here; upstream model names never do (U.8). Keys are the
- * fixed {@link TASK_CLASSES}, so a mistyped class is rejected at config load.
+ * with an empty `map` and no `default` the whole table is inert and nothing
+ * about a session changes. Only tier names appear here; upstream model names
+ * never do (U.8). Keys are the fixed {@link TASK_CLASSES}, so a mistyped class
+ * is rejected at config load.
+ *
+ * A PARTIAL TABLE STAYS PARTIAL. Writing `map` without `default` routes exactly
+ * the classes named and leaves every other one to the gateway (`auto`) — it does
+ * not pin them to some tier chosen on your behalf. The exception is a
+ * `model.model` that names a tier: that is a session-wide model choice, and the
+ * unnamed classes inherit it rather than being handed back to the gateway.
  */
 export const RoutingConfigSchema = z
     .object({
-    /** Tier for any task class not in `map`. Unset → the tier implied by
-     * `model.model` (a real tier, or the auto-fallback tier). */
+    /** Tier for any task class not in `map`. Unset → the tier `model.model`
+     * names, if it names one; otherwise the class is not routed here at all and
+     * goes out as `auto` for the gateway to route. */
     default: z.enum(MODEL_TIERS).optional(),
-    /** Per-task-class tier overrides; anything omitted takes `default`. */
+    /** Per-task-class tier overrides; anything omitted takes `default`, or
+     * `auto` when there is no `default` to take. */
     map: z.record(z.enum(TASK_CLASSES), z.enum(MODEL_TIERS)).default({}),
 })
     .strict();

package/dist/errors/constructors.js

@@ -109,14 +109,47 @@ export function configParse(path, underlying) {
         meta: { path },
     });
 }
+/**
+ * `--config <path>` named a file that does not exist.
+ *
+ * Loud by construction: the alternative is falling back to discovery or to
+ * defaults, which produces exactly the behaviour the user would have got
+ * without the flag, and so is indistinguishable from success (#289). Raised
+ * only for an EXPLICIT path — a missing global or project config is ordinary.
+ */
+export function configNotFound(path) {
+    return new CruxyError({
+        code: ErrorCode.ConfigNotFound,
+        title: `config file not found: ${path}`,
+        cause: "`--config` named a file that does not exist",
+        nextSteps: [
+            "check the path (it is resolved as given, relative to the current directory)",
+            "omit `--config` to use the discovered project config, or `~/.cruxy/config.json`",
+        ],
+        meta: { path },
+    });
+}
 export function configInvalid(issues, path) {
     return new CruxyError({
         code: ErrorCode.ConfigInvalid,
-        title: "the configuration is invalid",
+        // NAME THE FILE, as `configParse` above already does. The path was carried
+        // in `meta` alone, and the terminal formatter renders title/cause/steps/code
+        // — not meta — so the caller's choice of which file to blame reached nobody
+        // and "correct the reported field(s)" left the user to guess between the
+        // global, project and explicit configs (#289).
+        //
+        // It is the HIGHEST-PRECEDENCE file in effect, not necessarily the one
+        // holding the bad key: the config is a merge, and a resolved value cannot
+        // be traced to a layer from here. Hence "start with" and the pointer to
+        // `config path` — an honest lead, not a claim about which line to edit.
+        title: path
+            ? `the configuration is invalid (${path})`
+            : "the configuration is invalid",
         cause: issues,
         nextSteps: [
             "correct the reported field(s)",
-            "see valid keys with `cruxy config list`",
+            ...(path ? [`start with ${path}, the last file merged`] : []),
+            "see valid keys with `cruxy config list`, or the files in effect with `cruxy config path`",
         ],
         meta: path ? { path } : undefined,
     });

package/dist/errors/types.js

@@ -29,6 +29,11 @@ export const ErrorCode = {
     // config (exit 3)
     ConfigParse: "CRUXY_E_CONFIG_PARSE",
     ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
+    /** A config file named with `--config` does not exist. DISTINCT from
+     * {@link ConfigParse}: nothing was malformed, the file simply is not there,
+     * and the advice is to check the path rather than the JSON. Only an EXPLICIT
+     * path can raise it — a missing global or project file is the normal case. */
+    ConfigNotFound: "CRUXY_E_CONFIG_NOT_FOUND",
     // auth (exit 4)
     AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
     AuthInvalid: "CRUXY_E_AUTH_INVALID",
@@ -311,6 +316,7 @@ const EXIT_CODES = {
     [ErrorCode.RoutingTierUnavailable]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
+    [ErrorCode.ConfigNotFound]: 3,
     [ErrorCode.AuthMissingKey]: 4,
     [ErrorCode.AuthInvalid]: 4,
     [ErrorCode.AuthExpired]: 4,

package/dist/jobs/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./log-buffer.js";
+export * from "./log-store.js";
 export * from "./log-renderer.js";
 export * from "./approval-queue.js";
 export * from "./manager.js";

package/dist/jobs/log-renderer.js

@@ -18,9 +18,14 @@ const OFFSCREEN_CAPS = {
 };
 /**
  * A {@link StreamRenderer} for a background job (C.28) that captures activity into
- * the job's log buffer and writes NOTHING to any terminal — a job runs
+ * the job's log sink and writes NOTHING to any terminal — a job runs
  * non-interactively, off screen, and its foreground session owns the terminal.
- * `cruxy logs <id>` (a REPL `/logs`) reads back what was captured here.
+ *
+ * What was captured here is read back from two different copies: the in-session
+ * `/logs <id>` and the Tasks view read the ring buffer while the session lives,
+ * and `cruxy logs <id>` reads the persisted file afterwards (#172 item 1).
+ * Everything this renderer emits goes through the one `JobManager.log` sink, so
+ * both copies see exactly the same lines.
  *
  * Assistant text is accumulated and flushed a line at a time on `endSegment`;
  * committed chrome notes and tool-call completions are captured verbatim. The
@@ -94,9 +99,9 @@ export class JobLogRenderer {
         this.planSteps = steps.map((s) => ({ ...s }));
     }
     /**
-     * A job's test run is exactly the kind of outcome `cruxy logs` exists to
-     * show. Plain text, no theme glyphs, matching this log's `[ok]`/`[fail]`
-     * style — and no count this renderer was not given.
+     * A job's test run is exactly the kind of outcome a job log exists to show.
+     * Plain text, no theme glyphs, matching this log's `[ok]`/`[fail]` style —
+     * and no count this renderer was not given.
      */
     testResult(report) {
         const counted = report.total !== undefined