tumwater 0.4.2 → 0.4.3

package/dist/src/cli/log-commands.js

@@ -103,6 +103,11 @@ export function followUntilParentGone(file, offset, onLines, seams) {
         });
     });
 }
+/** The `-n` ceiling for the event-log dump (`tumwater logs -n <count>`): a terminal tail has
+ * no use for more than this many scanned events, and bounding it keeps an accidental
+ * `-n 999999999` from traversing the whole event file. Sister counts are bounded the same way
+ * (history's HISTORY_MAX_RUNS, report's REPORT_MAX_DAYS); the GUI clamps its logs counts too. */
+const LOGS_MAX_EVENTS = 100_000;
 /** `tumwater logs [-f] [-n <count>] [--since <duration>] [--until <duration>]
  * [--role <id>[,<id>...]] [--transcript <id>] [--prompt]
  * [--grep <text>]`: follow or dump the harness event log, with `--since` a bounded
@@ -126,7 +131,7 @@ export async function cmdLogs(root, args, seams = {}) {
         return;
     }
     const nRaw = flagValue(feed.rest, "-n");
-    const limit = nRaw !== null ? parseCountFlag("-n", nRaw) : 50;
+    const limit = nRaw !== null ? parseCountFlag("-n", nRaw, LOGS_MAX_EVENTS) : 50;
     // The event feed (no --transcript) never needs the config at all: parseRoleScope reads it only
     // when the flag is present.
     const role = parseRoleScope(root, feed.rest, "--transcript", LOGS_TRANSCRIPT_VALUE_ERROR);
@@ -278,39 +283,54 @@ function sayLogsWindowNoMatch(feed, windowPhrase) {
     else
         say(feed.roles !== null ? `${feed.roleEmpty} ${windowPhrase}` : `no events ${windowPhrase}`);
 }
-/** The `-n` tail view and its follow: `readEventsTailWithEnd`, the `shown` filter, the
- * `--count` branch and its empty-match prose, the per-event print, the `!follow` return, and
- * `followUntilParentGone` seeded from `tail.coveredEnd`. It owns the follow-loop locals. */
+/** The `-n` tail view and its `-f` follow: read the filtered tail, print the `--count`
+ * tally or the per-event rows, and seed the follow; each job lives in a named helper. */
 async function sayLogsTail(root, feed, limit, seams) {
-    // -n bounds the scan, not the print: the matched subset of the last `limit` events is what
-    // appears, so `-n 200 --grep merge_failed` may print 3 rows from 200 scanned. The read is
-    // the tail-with-end shape (not the per-poll cached readEvents) so the follow below can seed
-    // from the byte end this very read covered instead of a later stat of the file.
-    const tail = readEventsTailWithEnd(root, limit);
-    const shown = feed.grepLower !== null || feed.type !== null || feed.roles !== null || feed.notable ? tail.events.filter(feed.filter) : tail.events;
-    // `--count` over the -n view answers with the tally of exactly the filtered rows the plain
-    // view would print, and carries over the plain view's empty-match prose below (a `--type`
-    // or `--grep` that matches nothing names its value; an empty unfiltered -n view prints
-    // nothing, as the plain view does). In JSON mode the empty output is the answer.
+    const { shown, coveredEnd } = readTailShown(root, feed, limit);
     if (feed.count) {
+        // `--count` over the -n view answers with the tally of exactly the filtered rows the plain
+        // view would print, and carries over the plain view's empty-match prose (a `--type` or
+        // `--grep` that matches nothing names its value; an empty unfiltered -n view prints
+        // nothing, as the plain view does). In JSON mode the empty output is the answer.
         if (shown.length !== 0)
             sayTally(shown, feed.json);
-        else if (!feed.json && (feed.filtersGrepOrType || feed.roles !== null || feed.notable))
-            sayLogsTailNoMatch(feed);
+        else
+            sayTailEmptyNote(shown, feed);
         return;
     }
     for (const e of shown)
         sayEventLine(e, feed.json);
     if (!feed.follow) {
-        // The empty-match line is prose: in JSON mode the empty output is the answer. It fires
-        // for either filter, naming the flag's value(s) whose match came up empty so the operator
-        // knows what to loosen.
-        if (shown.length === 0 && !feed.json && (feed.filtersGrepOrType || feed.roles !== null || feed.notable))
-            sayLogsTailNoMatch(feed);
+        sayTailEmptyNote(shown, feed);
         return;
     }
+    await followLogsTail(root, feed, coveredEnd, seams);
+}
+/** How `-n` scans versus prints: `limit` bounds the scan, not the print — the matched
+ * subset of the last `limit` events is what appears, so `-n 200 --grep merge_failed` may
+ * print 3 rows from 200 scanned. The read is the tail-with-end shape (not the per-poll
+ * cached readEvents) so the follow can seed from the byte end this very read covered
+ * instead of a later stat of the file. It also owns the share of output to print: the
+ * `shown` rows in read order. */
+function readTailShown(root, feed, limit) {
+    const tail = readEventsTailWithEnd(root, limit);
+    const shown = feed.grepLower !== null || feed.type !== null || feed.roles !== null || feed.notable ? tail.events.filter(feed.filter) : tail.events;
+    return { shown, coveredEnd: tail.coveredEnd };
+}
+/** The empty-match guard shared by the `--count` branch and the no-follow plain branch: the
+ * empty-match line is prose (in JSON mode the empty output is the answer) and fires for
+ * either filter, naming the flag's value(s) whose match came up empty so the operator knows
+ * what to loosen. */
+function sayTailEmptyNote(shown, feed) {
+    if (shown.length === 0 && !feed.json && (feed.filtersGrepOrType || feed.roles !== null || feed.notable))
+        sayLogsTailNoMatch(feed);
+}
+/** The `-f` follow: resolve the event-log path and stream every newly landed event through
+ * the same `feed.filter` as the seeded window, seeded from `coveredEnd` (the byte end the
+ * initial read covered) and holding the filter across rotation. */
+async function followLogsTail(root, feed, coveredEnd, seams) {
     const file = eventsLogPath(root);
-    // Seed the follow from the byte end the initial read covered (tail.coveredEnd), mirroring
+    // Seed the follow from the byte end the initial read covered (coveredEnd), mirroring
     // cmdLogsTranscript's tail.end seed: an event appended between the read and the follow's
     // start lies past the printed window but at or above this offset, so the follow's first
     // poll delivers it — seeding from a fresh statOrNull(file).size instead would start past
@@ -318,7 +338,7 @@ async function sayLogsTail(root, feed, limit, seams) {
     // log scans to coveredEnd 0, and followFile tolerates a missing file (its poll re-stats
     // every interval), so a read-only command never leaves a harness state file behind — the
     // module contract above promises writes to stdout only.
-    await followUntilParentGone(file, tail.coveredEnd, (lines) => {
+    await followUntilParentGone(file, coveredEnd, (lines) => {
         for (const line of lines.filter(Boolean)) {
             const e = parseEventLine(line);
             // The filter holds across rotation: every event the follow callback sees goes through

package/dist/src/cli/notify-command.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { fail, say } from "./cli-output.js";
 import { loadConfig } from "../config/config.js";
 import { TUMWATER_SOURCE } from "../events/events.js";
-import { notifyCommandEnv, notifyExitGloss } from "../events/notify.js";
+import { notifyCommandEnv, notifyExitGloss } from "../events/event-notify.js";
 /** The one representative allowlisted event `tumwater notify --test` fires: a failed merge
  * with source `tumwater`. Fixed and opinionated — the goal is to prove the hook runs, not to
  * replay a specific page, so there are no per-type or per-message flags. */
@@ -16,7 +16,7 @@ const NOTIFY_TEST_MESSAGE = "tumwater notify --test";
  * Generous enough not to misclassify a hook that is merely slow. */
 export const NOTIFY_TEST_TIMEOUT_MS = 10_000;
 /** Run one notify hook to completion, returning its exit code. Unlike the notifier's detached
- * fire-and-forget spawn (src/events/notify.ts), this waits with inherited stdio by
+ * fire-and-forget spawn (src/events/event-notify.ts), this waits with inherited stdio by
  * default (the dashboard passes "ignore"), so the
  * operator sees the hook's own output and its exit. A shell that cannot start resolves 127 —
  * the conventional "command not found" code. A hook that does not finish within `timeoutMs`

package/dist/src/cli/question-commands.js

@@ -1,8 +1,9 @@
 /** The CLI layer of `tumwater questions` — the `tumwater questions` command body: list the open
  * questions in QUESTIONS.md numbered, or `answer <n> <decision>` one, which moves its entry from
  * `## Open` to `## Answered` with a dated operator answer. The markdown surgery itself — the
- * fence-aware `### ` block cut and the `## Answered` skeleton — lives in src/backlog/
- * question-answer.ts (the shared QUESTIONS.md core the TUI and dashboard also call); this module
+ * fence-aware `### ` block cut and the `## Answered` skeleton — lives in
+ * src/backlog/backlog-question-answer.ts (the shared QUESTIONS.md core the TUI and dashboard also
+ * call); this module
  * is the command's argument scan, say/fail/editor jacket and commit-and-wake tail over that core,
  * routed to by src/cli.ts.
  */
@@ -17,8 +18,14 @@ import { typoSuffix } from "../text/suggest.js";
 import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { stampedSubject } from "../git/commit-message.js";
 import { wakeQuestionAsker } from "../operator/operator-intent.js";
-import { answeredQuestionAt, answeredQuestionCount, answeredQuestionList, answeredQuestionPayload, openQuestionAt, openQuestionList, questionListPayload, renderShownQuestion, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/question-answer.js";
+import { answeredQuestionAt, answeredQuestionCount, answeredQuestionList, answeredQuestionPayload, openQuestionAt, openQuestionList, questionListPayload, renderShownQuestion, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/backlog-question-answer.js";
 import { bodyStructureProblem, normalizeEntryBody } from "../backlog/backlog-write.js";
+/** `questions --answered -n`'s ceiling: bounds how many answered questions 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 list data
+ * is small (QUESTIONS.md), so the cap never meaningfully binds — it exists for the uniform
+ * count-flag contract and the clear over-range rebuke, not for memory. */
+const QUESTIONS_MAX_LISTED = 100_000;
 /** The `tumwater questions answer` entry point: `tryAnswerQuestion` without a title check, its
  * refusals mapped to `fail` (exit 1) with the CLI's wording. Returns the answered question's
  * title plus the collapsed decision that landed in the file. */
@@ -84,6 +91,72 @@ function sayQuestionList(root, json, pattern) {
 }
 /** `questions answer`'s `--file <path>` flag: the decision comes from the file, lines kept. */
 const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
+/** The `--show`/`--answered`/`-n`/`--grep` arms — the flags only valid before the question's
+ * number positional. Each performs its read and writes its `scan.<field>` exactly as the
+ * inline scan did; returns `i` (the index of the last token consumed, after any `args[++i]`);
+ * every other token returns `undefined`. */
+function readPreNumberFlag(scan, args, i) {
+    if (scan.numbered)
+        return undefined;
+    const arg = args[i];
+    if (arg === "--show") {
+        rejectRepeatFlag(scan.show !== undefined, "--show");
+        scan.show = parsePositionFlag("--show", args[++i], "--show 2");
+        return i;
+    }
+    if (arg === "--answered") {
+        rejectRepeatFlag(scan.answeredFlag, "--answered");
+        scan.answeredFlag = true;
+        return i;
+    }
+    if (arg === "-n") {
+        rejectRepeatFlag(scan.limit !== undefined, "-n");
+        scan.limit = parseCountFlag("-n", args[++i], QUESTIONS_MAX_LISTED);
+        return i;
+    }
+    if (arg === "--grep") {
+        rejectRepeatFlag(scan.grep !== undefined, "--grep");
+        const text = args[++i];
+        if (text === undefined || text === "")
+            fail("--grep needs text (usage: tumwater questions [--answered] --grep <text>)");
+        scan.grep = text;
+        return i;
+    }
+    return undefined;
+}
+/** The `--file` arm (valid anywhere), the `!numbered && --json` arm, and the unknown
+ * `--`-flag gate — in that order. Returns `i` when `--file`/`--json` consumed the token; the
+ * unknown-flag arm never returns (it `fail`s). */
+function readAnywhereFlag(scan, args, i) {
+    const arg = args[i];
+    if (arg === "--file") {
+        rejectRepeatFlag(scan.file !== undefined, "--file");
+        scan.file = promptFileValue(args[++i]);
+        return i;
+    }
+    if (!scan.numbered && arg === "--json") {
+        rejectRepeatFlag(scan.jsonFlag, "--json");
+        scan.jsonFlag = true;
+        return i;
+    }
+    if (arg.startsWith("--") && arg !== "--json") {
+        rejectEqualsForm(arg, [JSON_FLAG, FILE_SPEC, { names: ["--show"], value: true, valueName: "<n>" }, { names: ["--grep"], value: true, valueName: "<text>" }]);
+        // The complete flag set (this gate only sees `--`-flags, but `-n` is a real flag the
+        // list should not omit) plus the same did-you-mean hint the sibling commands'
+        // unknown-argument gate (cli-flag-specs's failUnknownArgument) attaches, so a mistyped
+        // `--ansered` names `--answered` instead of only printing the valid list — the missing
+        // treatment the questions gate was the one unknown-argument caller without.
+        const spellings = ["--json", "--file", "--answered", "--show", "--grep", "-n"];
+        fail(`unknown argument: ${arg} (valid flags for tumwater questions: ${spellings.join(", ")})${typoSuffix(arg, spellings)}`);
+    }
+    return undefined;
+}
+/** The trailing `-n needs --answered` guard: `-n` limits the answered list, so without
+ * `--answered` it means nothing. */
+function assertQuestionsFlags(scan) {
+    if (scan.limit !== undefined && !scan.answeredFlag)
+        fail("-n needs --answered (it limits the answered questions listed)");
+}
 /** No requireReadyRepo gate, like backlog: the reader degrades to an empty list on a
  * missing QUESTIONS.md, so the command inspects any directory instead of refusing (a team
  * workspace still refuses).
@@ -102,72 +175,25 @@ const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
  * into JSON mode. Unknown `--`-prefixed tokens stay refused even there, so a misspelled
  * flag is still an error rather than silent decision text. */
 function parseQuestionsInvocation(args) {
-    const words = [];
-    let jsonFlag = false;
-    let numbered = false;
-    let file;
-    let answeredFlag = false;
-    let limit;
-    let grep;
-    let show;
+    const scan = { words: [], jsonFlag: false, numbered: false, file: undefined, answeredFlag: false, limit: undefined, grep: undefined, show: undefined };
     for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (!numbered && arg === "--show") {
-            rejectRepeatFlag(show !== undefined, "--show");
-            show = parsePositionFlag("--show", args[++i], "--show 2");
+        const consumed = readPreNumberFlag(scan, args, i) ?? readAnywhereFlag(scan, args, i);
+        if (consumed !== undefined) {
+            i = consumed;
             continue;
         }
-        if (!numbered && arg === "--answered") {
-            rejectRepeatFlag(answeredFlag, "--answered");
-            answeredFlag = true;
-            continue;
-        }
-        if (!numbered && arg === "-n") {
-            rejectRepeatFlag(limit !== undefined, "-n");
-            limit = parseCountFlag("-n", args[++i]);
-            continue;
-        }
-        if (!numbered && arg === "--grep") {
-            rejectRepeatFlag(grep !== undefined, "--grep");
-            const text = args[++i];
-            if (text === undefined || text === "")
-                fail("--grep needs text (usage: tumwater questions [--answered] --grep <text>)");
-            grep = text;
-            continue;
-        }
-        if (arg === "--file") {
-            rejectRepeatFlag(file !== undefined, "--file");
-            file = promptFileValue(args[++i]);
-            continue;
-        }
-        if (!numbered && arg === "--json") {
-            rejectRepeatFlag(jsonFlag, "--json");
-            jsonFlag = true;
-            continue;
-        }
-        if (arg.startsWith("--") && arg !== "--json") {
-            rejectEqualsForm(arg, [JSON_FLAG, FILE_SPEC, { names: ["--show"], value: true, valueName: "<n>" }, { names: ["--grep"], value: true, valueName: "<text>" }]);
-            // The complete flag set (this gate only sees `--`-flags, but `-n` is a real flag the
-            // list should not omit) plus the same did-you-mean hint the sibling commands'
-            // unknown-argument gate (cli-flag-specs's failUnknownArgument) attaches, so a mistyped
-            // `--ansered` names `--answered` instead of only printing the valid list — the missing
-            // treatment the questions gate was the one unknown-argument caller without.
-            const spellings = ["--json", "--file", "--answered", "--show", "--grep", "-n"];
-            fail(`unknown argument: ${arg} (valid flags for tumwater questions: ${spellings.join(", ")})${typoSuffix(arg, spellings)}`);
-        }
-        if (!numbered) {
+        if (!scan.numbered) {
             // The position is a plain-decimal positive integer (parsePositiveInt's rule, the same
             // one --cancel's position honors): bare Number() admitted hex ("0x2"), exponent
             // ("1e2"), and whitespace-padded spellings as a valid question number, answering a
             // question the operator never named.
-            if (parsePositiveInt(arg) !== null)
-                numbered = true;
+            if (parsePositiveInt(args[i]) !== null)
+                scan.numbered = true;
         }
-        words.push(arg);
+        scan.words.push(args[i]);
     }
-    if (limit !== undefined && !answeredFlag)
-        fail("-n needs --answered (it limits the answered questions listed)");
-    return { words, jsonFlag, file, answeredFlag, limit, grep, show };
+    assertQuestionsFlags(scan);
+    return { words: scan.words, jsonFlag: scan.jsonFlag, file: scan.file, answeredFlag: scan.answeredFlag, limit: scan.limit, grep: scan.grep, show: scan.show };
 }
 /** The `--show` output branch: one open (or, with `--answered`, answered) question in full. */
 function sayShownQuestion(root, inv) {