tumwater 0.4.2 → 0.4.3

package/dist/src/agent/image-input.js

@@ -1,12 +1,14 @@
 /** The seam's answer to "who in this team can read images" (plans/image-input.md
- * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives, so the
- * answer is never reached two ways. It lives at runtime level because it needs the backend
- * registry: a claude seam is always capable through the AgentBackend.imageInput hook, a pi
- * seam reads the model's `input` in models.json, and any other backend answers null unless it
- * declares a hook. */
-import { configForRole } from "../config/config-views.js";
-import { seamAgent } from "../config/model-selector.js";
-import { piModelImageInput, piModelsPath, readPiProviders } from "../pi/pi-models.js";
+ * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives; the reroute
+ * target (imageReroute) and the per-role surfaces (roleImageInfo) both read it, so the answer
+ * is never reached two ways. It lives at runtime level because it needs the backend registry:
+ * a claude seam is always capable through the AgentBackend.imageInput hook, a pi seam reads the
+ * model's `input` in models.json, and any other backend answers null unless it declares a hook. */
+import { configForRole, roleSeamTier, withModelOverrides } from "../config/config-views.js";
+import { BORROW_ORDER, resolveTierFallbacks } from "../config/config-fallbacks.js";
+import { seamAgent } from "../config/config-model-selector.js";
+import { modelLabel } from "./backend-traits.js";
+import { piModelImageInput, piPairFree, piModelsPath, readPiProviders } from "../pi/pi-models.js";
 import { piListedImageInput } from "../pi/pi-listed-models.js";
 import { backendById } from "./agent-backend.js";
 /** One seam's image-input capability (plans/image-input.md "Capability"): `true` when the
@@ -32,12 +34,67 @@ export function seamImageInput(seam, providers, listed = null) {
         return null;
     return piModelImageInput(providers, seam.provider, seam.model) ?? piListedImageInput(listed, seam.provider, seam.model);
 }
+/** The image-capable reroute target for `role`, or null when no peer tier can read images
+ * (plans/image-input.md "Reroute target"). Walks the role's seam tier through BORROW_ORDER,
+ * skipping the tier itself — small → default → strong, default → strong → small, strong →
+ * default (a strong-tier seam never drops to small, the same rule as the budget fallback) —
+ * and takes the first tier whose model reads images. `regime` picks the pair set (see
+ * RerouteRegime); `modelsPath` and `account` are injectable so tests need no real pi install
+ * or account. */
+export function imageReroute(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, providers = null, listed = null) {
+    const tier = roleSeamTier(config, role);
+    const candidates = BORROW_ORDER[tier].filter((t) => t !== tier);
+    if (candidates.length === 0)
+        return null;
+    const providerMap = providers ?? readPiProviders(modelsPath);
+    const capable = (rc) => seamImageInput(rc, providerMap, listed) === true;
+    if (regime === "primary") {
+        for (const t of candidates) {
+            const rc = withModelOverrides(config, t, {});
+            if (capable(rc))
+                return { tier: t, config: rc };
+        }
+        return null;
+    }
+    // Fallback regime: only the tiers' free fallback pairs qualify (resolveTierFallbacks over the
+    // price check), never a priced primary model — a reroute must not spend past the cap.
+    const resolved = resolveTierFallbacks(config, (p) => 
+    // The free-ness lookup reads the one claude account held here (part 2a/9).
+    piPairFree(providerMap, p, (b) => (b === "claude" ? account : null)));
+    for (const t of candidates) {
+        const pair = resolved[t].pair;
+        if (!pair)
+            continue;
+        const rc = withModelOverrides(config, t, {
+            provider: pair.provider,
+            model: pair.model,
+            thinking: pair.thinking,
+        });
+        if (capable(rc))
+            return { tier: t, config: rc };
+    }
+    return null;
+}
+/** The config of imageReroute, for callers that want only the target model. */
+export function imageRerouteTarget(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, providers = null, listed = null) {
+    return imageReroute(config, role, regime, modelsPath, account, providers, listed)?.config ?? null;
+}
+/** A seam's model as one readable token, the same label the doctor's `image input` check used
+ * (`claude/<id>` for a claude seam, `provider/model` for pi), delegated to backend-traits'
+ * modelLabel. Used by roleImageInfo alone. */
+function seamImageLabel(backend, provider, model) {
+    return modelLabel(backend, provider, model);
+}
 /** Compute RoleImageInfo for one role. `modelsPath` and `listed` are injectable; the providers
- * catalog is read (stat-cached) here. The reroute field is a literal null — the peer-tier image
- * reroute was subtracted (part 5g/6), so no role names a reroute target; 5h removes the field. */
+ * catalog is read (stat-cached) here and also handed to imageReroute so a poll that asks many
+ * roles still parses the catalog once. */
 export function roleImageInfo(config, role, modelsPath = piModelsPath(), listed = null) {
     const providers = readPiProviders(modelsPath);
     const rc = configForRole(config, role);
     const imageInput = seamImageInput(rc, providers, listed);
-    return { imageInput, imageReroute: null };
+    const rr = imageReroute(config, role, "primary", modelsPath, null, providers, listed);
+    const imageRerouteStr = rr
+        ? `${rr.tier} (${seamImageLabel(rr.config.agent, rr.config.provider, rr.config.model)})`
+        : null;
+    return { imageInput, imageReroute: imageRerouteStr };
 }

package/dist/src/agent/notes-shim.js

@@ -1,5 +1,5 @@
 /** Installing the per-team `tumwater-notes` shim every backend's run finds on its PATH
- * (plans/notes-command.md "Reaching it from a run"): run-spawn calls `ensureNotesShim(root)`
+ * (plans/notes-command.md "Reaching it from a run"): agent-spawn calls `ensureNotesShim(root)`
  * before building each invocation, and the backend prepends the returned dir to the run's
  * PATH (backendBaseEnv's `binDir`, src/process/run-marker.ts). The shim is a two-line `sh`
  * script that execs the compiled notes CLI, so a model's shell — pi's, Claude Code's or
@@ -20,7 +20,7 @@ export const NOTES_SHIM_NAME = "tumwater-notes";
 /** Install the `tumwater-notes` shim under `<root>/.tumwater/bin` and return that directory.
  * The shim is written atomically with mode 0755, only when its content differs from what is
  * already there (a redeploy that changes `<dist>` rewrites it). Never throws: a failure to
- * write is the caller's to absorb — run-spawn logs one warning and runs without the shim. */
+ * write is the caller's to absorb — agent-spawn logs one warning and runs without the shim. */
 export function ensureNotesShim(root, execPath = process.execPath) {
     const dir = notesShimDir(root);
     const target = path.join(dir, NOTES_SHIM_NAME);

package/dist/src/agent/opencode/opencode-backend.js

@@ -1,7 +1,7 @@
 /** The opencode adapter for the agent seam (plans/opencode-backend.md "The invocation",
  * "Sessions", §6). It shapes one run's argv/stdin/env, translates opencode's `run --format
  * json` into the canonical stream, runs the authoritative session export after the process
- * exits, and classifies the exit's stderr — everything backend-specific. src/agent/run-spawn.ts
+ * exits, and classifies the exit's stderr — everything backend-specific. src/agent/agent-spawn.ts
  * spawns the run and records this run in the session ledger; opencode mints its own session id
  * (a `ses_…` id, or the resumed record's id), which `invocation` returns so the ledger can
  * carry it.
@@ -13,7 +13,7 @@
  * the only thing that stops a follow-up running against an empty session. Anything else mints a
  * fresh id (design §4).
  *
- * Registration lives in src/agent/run-agent.ts beside the pi and claude adapters; a test selects
+ * Registration lives in src/agent/agent-run.ts beside the pi and claude adapters; a test selects
  * opencode by setting `config.agent = "opencode"` on a run. A run carrying a note gets the
  * notes path in its environment (the `tumwater-notes` command on PATH reads it), as the pi and
  * claude adapters do. */

package/dist/src/agent/opencode/opencode-catalog.js

@@ -33,6 +33,53 @@ const defaultFetch = async (url, timeoutMs) => {
 export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
     return fetchFn(CATALOG_URL, CATALOG_FETCH_TIMEOUT_MS);
 }
+/** The catalog root `parseOpencodeCatalog` iterates: models.dev's live api.json puts the provider
+ * map at the top level, OpenCode's cached copy wraps that same map under a `body` key. */
+function catalogRoot(body) {
+    const root = isJsonObject(body) ? body : {};
+    // models.dev's api.json IS the provider map; OpenCode's cached copy wraps that map under `body`.
+    const wrapped = root.body;
+    return isJsonObject(wrapped) ? wrapped : root;
+}
+/** The free/priced reads from a per-model cost block: whether it is present and yields two zero
+ * per-M prices. A missing cost block is unknown price data, and treating it as $0 is the unsafe
+ * direction for a budget gate. */
+function modelPricing(m) {
+    const cost = isJsonObject(m.cost) ? m.cost : undefined;
+    const input = cost?.input ?? 0;
+    const output = cost?.output ?? 0;
+    return {
+        costed: cost !== undefined,
+        free: cost !== undefined && input === 0 && output === 0,
+        inputPerM: input,
+        outputPerM: output,
+    };
+}
+/** The effort levels from a per-model object: the `values` of the `reasoning_options` entries
+ * whose `type` is `"effort"`. */
+function modelEfforts(m) {
+    if (!Array.isArray(m.reasoning_options))
+        return [];
+    return m.reasoning_options.flatMap((r) => isJsonObject(r) && r.type === "effort" && Array.isArray(r.values) ? r.values : []);
+}
+/** Build one catalog model from an untrusted per-model object, null when it is malformed. */
+function catalogModelFrom(m) {
+    const pricing = modelPricing(m);
+    const model = { free: pricing.free };
+    if (pricing.costed) {
+        model.inputPerM = pricing.inputPerM;
+        model.outputPerM = pricing.outputPerM;
+    }
+    if (isJsonObject(m.limit) && m.limit.context !== undefined)
+        model.context = m.limit.context;
+    if (isJsonObject(m.modalities) && Array.isArray(m.modalities.input)) {
+        model.images = m.modalities.input.includes("image");
+    }
+    const efforts = modelEfforts(m);
+    if (efforts.length > 0)
+        model.efforts = efforts;
+    return isOpencodeCatalogModel(model) ? model : null;
+}
 /** Parse models.dev's `api.json` into the models the config routes through OpenCode: always the
  * `opencode` provider, plus every provider named in `providers` (the config's
  * `opencode/<provider>/…` routes — `opencode-go` and so on). The live `GET /api.json` returns
@@ -43,11 +90,7 @@ export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
  * provider or model is skipped, never thrown on. */
 export function parseOpencodeCatalog(body, providers) {
     const out = {};
-    const root = isJsonObject(body) ? body : {};
-    // models.dev's api.json IS the provider map; OpenCode's cached copy wraps that map under `body`.
-    const wrapped = root.body;
-    const catalog = isJsonObject(wrapped) ? wrapped : root;
-    for (const [provider, providerInfo] of Object.entries(catalog)) {
+    for (const [provider, providerInfo] of Object.entries(catalogRoot(body))) {
         if (provider !== "opencode" && !providers.includes(provider))
             continue;
         if (!isJsonObject(providerInfo) || !isJsonObject(providerInfo.models))
@@ -55,28 +98,8 @@ export function parseOpencodeCatalog(body, providers) {
         for (const [id, m] of Object.entries(providerInfo.models)) {
             if (!isJsonObject(m))
                 continue;
-            // Only a present cost block marks a model free: a missing cost block is unknown price data,
-            // and treating it as $0 is the unsafe direction for a budget gate.
-            const cost = isJsonObject(m.cost) ? m.cost : undefined;
-            const input = cost?.input ?? 0;
-            const output = cost?.output ?? 0;
-            const model = { free: cost !== undefined && input === 0 && output === 0 };
-            if (cost !== undefined) {
-                model.inputPerM = input;
-                model.outputPerM = output;
-            }
-            if (isJsonObject(m.limit) && m.limit.context !== undefined)
-                model.context = m.limit.context;
-            if (isJsonObject(m.modalities) && Array.isArray(m.modalities.input)) {
-                model.images = m.modalities.input.includes("image");
-            }
-            if (Array.isArray(m.reasoning_options)) {
-                const efforts = m.reasoning_options
-                    .flatMap((r) => isJsonObject(r) && r.type === "effort" && Array.isArray(r.values) ? r.values : []);
-                if (efforts.length > 0)
-                    model.efforts = efforts;
-            }
-            if (isOpencodeCatalogModel(model))
+            const model = catalogModelFrom(m);
+            if (model !== null)
                 out[`${provider}/${id}`] = model;
         }
     }

package/dist/src/agent/opencode/opencode-config.js

@@ -38,29 +38,47 @@ const DENIED_PERMISSIONS = [
 function isCommentStart(src, i) {
     return src[i] === "/" && (src[i + 1] === "/" || src[i + 1] === "*");
 }
+/** True when `c` is a JSONC whitespace character. */
+function isWhitespace(c) {
+    return c === " " || c === "\t" || c === "\n" || c === "\r";
+}
+/** Advance `j` past a `//` line comment (a caller-supplied position where `src[j] === "/"`
+ * and `src[j + 1] === "/"`), not past the terminating newline. */
+function skipLineComment(src, j) {
+    while (j < src.length && src[j] !== "\n")
+        j += 1;
+    return j;
+}
+/** Advance `j` past a `/*`-style block comment (a caller-supplied position where `src[j] ===
+ * "/"` and `src[j + 1] === "*"`), ending after its closing two characters. An unterminated
+ * comment leaves `j` at `src.length + 2`, overshooting past the end — today's behaviour, kept. */
+function skipBlockComment(src, j) {
+    j += 2;
+    while (j < src.length && !(src[j] === "*" && src[j + 1] === "/"))
+        j += 1;
+    j += 2;
+    return j;
+}
+/** Advance `j` past one comment, dispatching on the second character: `//` to the line-comment
+ * scan, `/*` to the block-comment scan (a caller-supplied position where `isCommentStart`
+ * holds). */
+function skipComment(src, j) {
+    return src[j + 1] === "/" ? skipLineComment(src, j) : skipBlockComment(src, j);
+}
 /** Advance `j` past any whitespace and comments, for a position that is never inside a string.
  * Returns the index of the next significant (non-comment, non-whitespace) character, or
  * `src.length` when the input ends in comments/whitespace. */
 function skipWhitespaceAndComments(src, j) {
     while (j < src.length) {
-        const c = src[j];
-        if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+        if (isWhitespace(src[j])) {
             j += 1;
-            continue;
         }
-        if (c === "/" && src[j + 1] === "/") {
-            while (j < src.length && src[j] !== "\n")
-                j += 1;
-            continue;
+        else if (isCommentStart(src, j)) {
+            j = skipComment(src, j);
         }
-        if (c === "/" && src[j + 1] === "*") {
-            j += 2;
-            while (j < src.length && !(src[j] === "*" && src[j + 1] === "/"))
-                j += 1;
-            j += 2;
-            continue;
+        else {
+            break;
         }
-        break;
     }
     return j;
 }

package/dist/src/agent/opencode/opencode-env.js

@@ -14,22 +14,21 @@
  * the model to pass `timeout` for the check (§5). `XDG_CONFIG_HOME` and its siblings are NOT
  * set: OpenCode's shell-tool children inherit the environment, and pointing XDG at a private
  * dir would stop `git` reading `~/.config/git/config`, losing commits' author identity (§3). */
+import { scrubEnv } from "../env-scrub.js";
 /** Build the opencode process environment from `base`. Never mutates `base`. */
 export function opencodeEnv(base, opts) {
-    const env = {};
-    for (const [key, value] of Object.entries(base)) {
+    return scrubEnv(base, {
         // Everything an inherited OpenCode session set is scrubbed — server, config, database,
         // client and session id — except the operator's API key, which is operator intent and must
         // survive. `AI_AGENT` goes too, so the shell tool sets its own (finding 16).
-        if (key === "OPENCODE" || (key.startsWith("OPENCODE_") && key !== "OPENCODE_API_KEY") || key === "AI_AGENT")
-            continue;
-        env[key] = value;
-    }
-    env.OPENCODE_DISABLE_CLAUDE_CODE = "1";
-    env.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = "1";
-    env.OPENCODE_DISABLE_AUTOUPDATE = "1";
-    env.OPENCODE_DISABLE_FILEWATCHER = "1";
-    env.OPENCODE_DB = opts.dbPath;
-    env.OPENCODE_CONFIG_CONTENT = opts.configContent;
-    return env;
+        keep: (key) => !(key === "OPENCODE" || (key.startsWith("OPENCODE_") && key !== "OPENCODE_API_KEY") || key === "AI_AGENT"),
+        then: (env) => {
+            env.OPENCODE_DISABLE_CLAUDE_CODE = "1";
+            env.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = "1";
+            env.OPENCODE_DISABLE_AUTOUPDATE = "1";
+            env.OPENCODE_DISABLE_FILEWATCHER = "1";
+            env.OPENCODE_DB = opts.dbPath;
+            env.OPENCODE_CONFIG_CONTENT = opts.configContent;
+        },
+    });
 }

package/dist/src/agent/opencode/opencode-stream.js

@@ -28,49 +28,71 @@ const TOOL_NAMES = {
 /** A Retry-After hint spelled out in a rate-limit error's message text ("retry after 30s" /
  * "retry in 30 seconds"). */
 const RETRY_AFTER = /retry (?:after|in) (\d+)\s*s(?:econds?)?\b/i;
-/** How an `error` line classifies into the canonical `tumwaterKind` (and, for a transient
- * backend, its kind), trusted by `PiStreamParser` before its text regexes. The error's
- * `type` — the provider signal the plan's table maps (provider.auth, provider.no-route,
- * unknown) — is consulted FIRST, the message text second (plans/opencode-backend.md §8 and
- * its classification table). */
-function classifyError(err) {
-    const message = typeof err.message === "string" ? err.message : "";
-    const type = typeof err.type === "string" ? err.type : "";
-    const status = err.status;
-    // The free tier refuses intermittently (a provider failure, not a config error): three
-    // refusals in a row move the tier to its fallback through the existing model-failure
-    // episode. Typed `provider.auth` WITH status 403 — the free tier's own refusal — or the
-    // text naming the free tier. A `provider.auth` with any other status (a 401 bad
-    // credential) is not a refusal and falls through to the config-error row below.
+;
+/** Is this the free tier's intermittent refusal (a provider failure, not a config error)?
+ * Three refusals in a row move the tier to its fallback through the existing model-failure
+ * episode. Typed `provider.auth` WITH status 403 — the free tier's own refusal — or the
+ * text naming the free tier. A `provider.auth` with any other status (a 401 bad
+ * credential) is not a refusal and falls through to the config-error row. */
+function freeTierClassification(type, status, message) {
     if ((type === "provider.auth" && status === 403) || /free\s?tier|FreeTierError/i.test(message))
         return { kind: "transientBackend", backendKind: "server", freeTier: true };
-    // Rate limiting — 429 or rate-limit text — is the world saying "later", inherently
-    // retryable; carry the echoed Retry-After hint when the message spells it.
+    return undefined;
+}
+/** Is this a rate limit (429 or rate-limit text) — the world saying "later", inherently
+ * retryable? Carry the echoed Retry-After hint when the message spells it. */
+function rateLimitClassification(status, message) {
     if (status === 429 || /\b429\b|rate limit|too many requests/i.test(message)) {
         const retry = RETRY_AFTER.exec(message);
         return { kind: "transientRateLimit", ...(retry ? { retryAfterSeconds: Number(retry[1]) } : {}) };
     }
-    // An unknown model or variant, and the malformed `ses_` id, are permanent config errors
-    // (a misconfiguration, not a transient outage): typed `provider.no-route` / `unknown`, or
-    // the model-not-found / 401 text.
+    return undefined;
+}
+/** Is this a permanent config error — an unknown model or variant, or the malformed `ses_`
+ * id (a misconfiguration, not a transient outage): typed `provider.no-route` / `unknown`,
+ * or the model-not-found / 401 text? */
+function configErrorClassification(type, status, message) {
     if (type === "provider.no-route" ||
         type === "unknown" ||
         status === 401 ||
         /unknown model|unknown provider|model not found|provider not found|unauthorized|status\s*401|\b401\b/i.test(message))
         return { kind: "configError" };
-    // Context overflow that compaction could not fix. Matched STRICTLY (the same shape pi's
-    // own CONTEXT_ERROR matches), so a message that merely mentions "context" or "too long"
-    // in passing — a plugin error, say — is never misread as an overflow that would then be
-    // trusted by PiStreamParser over its own tighter regex.
+    return undefined;
+}
+/** Did context overflow in a way compaction could not fix? Matched STRICTLY (the same shape
+ * pi's own CONTEXT_ERROR matches), so a message that merely mentions "context" or "too long"
+ * in passing — a plugin error, say — is never misread as an overflow that would then be
+ * trusted by PiStreamParser over its own tighter regex. */
+function contextOverflowClassification(message) {
     if (/context (size|length|window)?\s*(has been |was )?exceeded|exceeds? (the )?context|too (long|large) for .*context/i.test(message))
         return { kind: "contextExceeded" };
-    // Transient server, connection and timeout failures.
+    return undefined;
+}
+/** Is this a transient server, connection or timeout failure? The server statuses and text
+ * first, then the shared connection/timeout prose vocabulary (see `transientProseKind`). */
+function transientClassification(message) {
     if (/\b(500|501|502|503|504|529)\b|internal server error|bad gateway|service unavailable|gateway timeout|overloaded/i.test(message))
         return { kind: "transientBackend", backendKind: "server" };
     const prose = transientProseKind(message);
     if (prose)
         return prose;
-    return {};
+    return undefined;
+}
+/** How an `error` line classifies into the canonical `tumwaterKind` (and, for a transient
+ * backend, its kind), trusted by `PiStreamParser` before its text regexes. The error's
+ * `type` — the provider signal the plan's table maps (provider.auth, provider.no-route,
+ * unknown) — is consulted FIRST, the message text second (plans/opencode-backend.md §8 and
+ * its classification table). */
+function classifyError(err) {
+    const message = typeof err.message === "string" ? err.message : "";
+    const type = typeof err.type === "string" ? err.type : "";
+    const status = err.status;
+    return (freeTierClassification(type, status, message) ??
+        rateLimitClassification(status, message) ??
+        configErrorClassification(type, status, message) ??
+        contextOverflowClassification(message) ??
+        transientClassification(message) ??
+        {});
 }
 /** The step's token counts and cost → pi's canonical usage block: the four counts, their sum
  * as `totalTokens`, and `cost.total` = the step's USD cost (plans/opencode-backend.md §6).

package/dist/src/agent/session-ledger.js

@@ -39,7 +39,7 @@ export function recordSession(dir, record) {
     }
 }
 /** The one run's ledger record, minus the id the two recording sites mint differently — the
- * pre-spawn id in run-spawn.ts, or the stream-minted session id in run-stream.ts. One place
+ * pre-spawn id in agent-spawn.ts, or the stream-minted session id in agent-stream.ts. One place
  * for the record's non-id shape (agent, kind, name, cwd, the optional model and the stamp), so
  * the two appends cannot drift on the model spread or the required fields. `agent` is the
  * owning backend's id; the run options supply the rest. */

package/dist/src/agent/subscription-account.js

@@ -31,9 +31,9 @@ export function subscriptionWindowRejected(run) {
 /** The subscription account's used-up usage window, or null: a window reading `rejected` with
  * no overage, or (with `includeOverage`, the default) a window whose current reading shows
  * `isUsingOverage`, and a `resetsAt` still ahead of `now`; among several, the one that resets
- * last. With a `reserve` (config `backends.<id>.windowReserve`), a window whose utilization
- * has reached its type's fraction counts too, and comes back with `reserve: true`; a rejected
- * or overage window outranks a reserve one, so the flag is set only when no window is used up
+ * last. With a `reserve` (the subscription-window reserve), a window whose utilization has
+ * reached its type's fraction counts too and comes back with `reserve: true`; a rejected or
+ * overage window outranks a reserve one, so the flag is set only when no window is used up
  * for real. The budget gate's window move (pollBudgetGate) reads the default; the team hold
  * (windowObservation) passes `includeOverage: false`, because overage never holds a
  * seam. Only subscription billing produces one; a missing account reads null. */

package/dist/src/backlog/backlog-cli-view.js

@@ -10,6 +10,12 @@ import { groupBlockedSeries, partsLabel } from "./backlog-index-data.js";
 import { rejectUnknownArgs } from "../cli/cli-flag-specs.js";
 import { refuseTeamWorkspace } from "../cli/cli-repo-gate.js";
 import { sectionNoun, showEntry } from "./backlog-write.js";
+/** `bug --list --done -n` / `plan --list --done -n` ceiling: bounds how many finished
+ * entries one list shows, so a typo'd huge count fails fast with the shared `must be between
+ * 1 and <max>` wording (the logs/history/report pattern) instead of silently meaning
+ * "everything". The finished lists are small (PLANS.md/BUGS.md), so the cap never meaningfully
+ * binds — it exists for the uniform count-flag contract and the clear over-range rebuke. */
+const BACKLOG_MAX_LISTED = 100_000;
 /** Ascending positions as runs: consecutive ones join with an en dash (`13–17`), runs separate
  * with commas (`13–15, 18`). */
 function positionRuns(positions) {
@@ -59,7 +65,7 @@ function parseListArgs(args, command) {
         }
         if (arg === "-n") {
             rejectRepeatFlag(count !== null, "-n");
-            count = parseCountFlag("-n", args[++i]);
+            count = parseCountFlag("-n", args[++i], BACKLOG_MAX_LISTED);
             continue;
         }
         if (arg === "--list") {
@@ -114,10 +120,10 @@ function announceFinishedList(root, fileName, bugSection, grep, count, json) {
     const header = pattern === null ? `${what} in ${fileName}, newest first:` : `${what} in ${fileName} matching "${pattern}", newest first:`;
     say(`${header}\n${lines.join("\n")}`);
 }
-/** The active half of the list shell: the open entries with their holds, in-progress claim
- * marks and age suffixes, optionally reduced to the ready ones, as `--json` or prose, grouping
- * a plan's blocked parts into one line (groupBlockedSeries). */
-function announceActiveList(root, fileName, command, bugSection, sectionTitle, grep, ready, json) {
+/** The active list's read-and-filter phase: reads the section's entries and each position's
+ * hold and live claimer, numbers them unfiltered, keeps the `--grep` matches under those
+ * positions, drops to the `--ready` survivors, counts what `--ready` hid, and names the noun. */
+function activeListView(root, bugSection, sectionTitle, grep, ready) {
     const entries = bugSection ? openBugEntries(root) : plannedPlanEntries(root);
     const holds = backlogHolds(root);
     const entryHolds = bugSection ? holds.bugs : holds.plans;
@@ -128,47 +134,62 @@ function announceActiveList(root, fileName, command, bugSection, sectionTitle, g
     const numbered = entries.map((entry, i) => ({ entry, position: i + 1 }));
     const matches = grep === null ? numbered : numbered.filter((m) => entryMatches(m.entry, grep));
     const kept = ready ? matches.filter((m) => (entryHolds[m.position - 1] ?? null) === null) : matches;
-    const hidden = matches.length - kept.length;
-    if (json) {
-        sayJson({
-            entries: kept.map(({ entry, position }) => {
-                const since = filingDate(entry.title);
-                return {
-                    position,
-                    title: entry.title,
-                    body: entry.body,
-                    hold: entryHolds[position - 1] ?? null,
-                    inProgress: entryRunners[position - 1] ?? null,
-                    // The filing stamp the entry's own heading carries, and how many days it has waited
-                    // since then (both present only when the heading names a stamp — an undated entry
-                    // keeps the pre-existing shape with neither key).
-                    ...(since === null ? {} : { since, ageDays: ageInDays(since) }),
-                };
-            }),
-        });
-        return;
-    }
-    const noun = sectionNoun(sectionTitle);
-    if (grep === null && entries.length === 0) {
-        say(`no ${noun}s`);
-        return;
-    }
-    if (matches.length === 0) {
-        say(`no ${noun}s match "${grep}"`);
-        return;
-    }
-    if (ready && kept.length === 0) {
-        say(`no ${noun}s ready (${hidden} held; run \`tumwater ${command} --list\` to see them)`);
-        return;
-    }
+    return {
+        entries,
+        entryHolds,
+        entryRunners,
+        matches,
+        kept,
+        hidden: matches.length - kept.length,
+        noun: sectionNoun(sectionTitle),
+        grep,
+        ready,
+    };
+}
+/** The `--json` body: each kept entry as its position, title, verbatim body, hold,
+ * in-progress claim and — only when the heading names a filing stamp — its `since`/`ageDays`. */
+function activeListJson(view) {
+    const { kept, entryHolds, entryRunners } = view;
+    return {
+        entries: kept.map(({ entry, position }) => {
+            const since = filingDate(entry.title);
+            return {
+                position,
+                title: entry.title,
+                body: entry.body,
+                hold: entryHolds[position - 1] ?? null,
+                inProgress: entryRunners[position - 1] ?? null,
+                // The filing stamp the entry's own heading carries, and how many days it has waited
+                // since then (both present only when the heading names a stamp — an undated entry
+                // keeps the pre-existing shape with neither key).
+                ...(since === null ? {} : { since, ageDays: ageInDays(since) }),
+            };
+        }),
+    };
+}
+/** The prose `no …` line for an empty list, a `--grep` with no match, or a `--ready` list
+ * whose every match is held; null when `view.kept` has rows to print. */
+function activeListEmptyLine(view, command) {
+    const { entries, matches, kept, hidden, noun, grep, ready } = view;
+    if (grep === null && entries.length === 0)
+        return `no ${noun}s`;
+    if (matches.length === 0)
+        return `no ${noun}s match "${grep}"`;
+    if (ready && kept.length === 0)
+        return `no ${noun}s ready (${hidden} held; run \`tumwater ${command} --list\` to see them)`;
+    return null;
+}
+/** The prose body of a non-empty active list: the bug list's numbered `line` rows, or the
+ * plan list's `groupBlockedSeries` rows, each with the hidden-held notice when `hidden > 0`. */
+function activeListProse(view, fileName, command, bugSection) {
+    const { kept, entryHolds, entryRunners, hidden, noun } = view;
     const hiddenNote = `(${hidden} held entries hidden; run \`tumwater ${command} --list\` to see them)`;
     const line = (entry, i) => `${entry.title}${holdMark(entryHolds[i] ?? null)}${inProgressMark(entryRunners[i] ?? null)}${entryAgeSuffix(entry.title)}`;
     if (bugSection) {
         const bugLines = kept.map(({ entry, position }) => `${position}. ${line(entry, position - 1)}`);
         if (hidden > 0)
             bugLines.push(hiddenNote);
-        say(`${noun}s in ${fileName}:\n${bugLines.join("\n")}`);
-        return;
+        return `${noun}s in ${fileName}:\n${bugLines.join("\n")}`;
     }
     // Plans: a series' blocked parts show as one line naming their positions, as the prompt's
     // backlog index does; numbering is unchanged so --show/--edit/--cancel <n> reach every part.
@@ -189,7 +210,26 @@ function announceActiveList(root, fileName, command, bugSection, sectionTitle, g
         lines.push("(each blocked series is one line; --show <n> prints a part, --json lists every entry)");
     if (hidden > 0)
         lines.push(hiddenNote);
-    say(`${noun}s in ${fileName}:\n${lines.join("\n")}`);
+    return `${noun}s in ${fileName}:\n${lines.join("\n")}`;
+}
+/** The active half of the list shell: the open entries with their holds, in-progress claim
+ * marks and age suffixes, optionally reduced to the ready ones, as `--json` or prose, grouping
+ * a plan's blocked parts into one line (groupBlockedSeries). Orchestrates the four named
+ * phases below — the read-and-filter view (activeListView), the `--json` body (activeListJson),
+ * the empty-list prose line (activeListEmptyLine) and the bug/plan prose body
+ * (activeListProse). */
+function announceActiveList(root, fileName, command, bugSection, sectionTitle, grep, ready, json) {
+    const view = activeListView(root, bugSection, sectionTitle, grep, ready);
+    if (json) {
+        sayJson(activeListJson(view));
+        return;
+    }
+    const empty = activeListEmptyLine(view, command);
+    if (empty !== null) {
+        say(empty);
+        return;
+    }
+    say(activeListProse(view, fileName, command, bugSection));
 }
 /** The shared shell of the `bug --list` and `plan --list` CLI cases — the read half of the
  * operator queue whose `--edit`/`--cancel` flags address entries by position. Reads the same