tumwater 0.2.0 → 0.3.0

package/dist/src/cli/cli-args.js

@@ -1,8 +1,8 @@
 import { fail } from "./cli-output.js";
-import { BRANCH_VALUE_ERROR, ROLE_VALUE_ERROR } from "./cli-flag-specs.js";
+import { BRANCH_VALUE_ERROR, ROLE_VALUE_ERROR, TOKEN_VALUE_ERROR } from "./cli-flag-specs.js";
 import { knownRoleIdsCached } from "../config/config.js";
 import { allRoleIds, unknownRoleMessage } from "../roles/roles.js";
-import { gotSuffix, parsePositiveInt } from "../text/text.js";
+import { gotSuffix, parsePositiveInt, splitCommaList } from "../text/text.js";
 import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 /** CLI argument parsing and validation, shared by every command in cli.ts. The execution
  * layer calls these before running a command, so a bad flag fails fast with an actionable
@@ -29,17 +29,68 @@ export function flagValue(args, flag) {
     const i = args.indexOf(flag);
     return i < 0 ? null : args[i + 1];
 }
+/** The one validation of a `--token <secret>` value, shared by `tumwater gui` (cmdGui) and
+ * `tumwater start --gui` (cmdStart) so the value checks and their wording cannot drift
+ * between the two callers. Returns null when the token is fine (or absent), the error text
+ * the caller `fail()`s otherwise: TOKEN_VALUE_ERROR for a valueless or empty `--token`, and a
+ * flag-looking-value message when the value starts with `--` (a valued flag claims the next
+ * token even when it is a known flag, so `--token --all-interfaces` would otherwise serve with
+ * the literal secret "--all-interfaces"). `example` names the command form the operator
+ * typed (e.g. "tumwater gui" or "tumwater start --gui") in the copyable fix, so the
+ * message names whichever command the secret was meant for. */
+export function tokenValueProblem(args, example) {
+    const raw = flagValue(args, "--token");
+    if (raw === null)
+        return null;
+    if (raw === undefined || raw === "")
+        return TOKEN_VALUE_ERROR;
+    if (raw.startsWith("--"))
+        return `--token got the flag-looking value "${raw}" instead of a secret — write the secret as its own argument (e.g. \`${example} --token s3cret --all-interfaces\`)`;
+    return null;
+}
 /** The "each flag at most once" rule at a flag fold: fail the occurrence after the first with
  * the shared wording (`<flag> may only be given once`), `seen` being the caller's accumulator
  * for that flag. One home for the wording the spec-driven gate (cli-flag-specs.ts), the
  * free-form parsers' pre-scan (cli-command-args.ts), and the bespoke command shells
- * (backlog-cli.ts, cli-query-commands.ts) all apply, so a repeat cannot be reported as a
- * different error on one surface. Called per occurrence rather than pre-scanned at every site,
+ * (backlog-cli.ts, backlog-cli-view.ts, cli-query-commands.ts) all apply, so a repeat cannot be
+ * reported as a different error on one surface. Called per occurrence rather than pre-scanned
+ * at every site,
  * so a malformed invocation still reports whichever error its token order reaches first. */
 export function rejectRepeatFlag(seen, flag) {
     if (seen)
         fail(`${flag} may only be given once`);
 }
+/** Refuse a `--`-token in a valued flag's position — `--result --last` must not treat `--last`
+ * as its value. Both `history` forms used to swallow the following `--` token in the value
+ * slot: the trail's `--result`/`--model` then failed downstream with a misleading "--result
+ * needs --last" wording — the operator DID write `--last` — and the listing's `--model`
+ * silently treated `--last` as a model filter and matched no rows. Returns the value
+ * unchanged when it is not a `--` token; only a `--` token reads as a flag, so a single-dash
+ * token and the intentional-text filters (grep, type) are not refused. `flag` names the
+ * valued flag the way its missing-value error names the command (e.g. `history --model`). */
+export function rejectFlagLookingValue(flag, value) {
+    if (typeof value === "string" && value.startsWith("--"))
+        fail(`${flag} needs a value (the next token ${JSON.stringify(value)} is a flag, not a value)`);
+    return value;
+}
+/** The shared body of the `parse*Flag` helpers (grep, type, result, model): the flag's
+ * value (null when absent) alongside `rest`, the args with the value token removed, failing
+ * with `missingValueError` when the flag is valueless or its value is empty.
+ * `guardFlagValue` opts the flag into rejectFlagLookingValue, the same refusal the history
+ * listing (cmdHistory) applies to its own `--result`/`--model` and `role <id>`'s write flags
+ * and `config set` make. The value-scored filters (grep, type) deliberately keep a
+ * flag-shaped token as filter text and so stay off this guard. */
+function takeValuedFlag(args, flag, missingValueError, guardFlagValue = false) {
+    const i = args.indexOf(flag);
+    const rest = i >= 0 ? args.filter((_, j) => j !== i + 1) : args;
+    const raw = flagValue(args, flag);
+    if (raw === null)
+        return { rest, value: null };
+    const checked = guardFlagValue ? rejectFlagLookingValue(flag, raw) : raw;
+    if (checked === undefined || checked === "")
+        fail(missingValueError);
+    return { rest, value: checked };
+}
 /** Parse an optional `--grep <text>` filter flag for the filtering views (logs, history): the
  * substring pattern, or null when absent, returned alongside `rest` — the args with the
  * flag's value token removed. The value token leaves the list because a flag-shaped token
@@ -51,14 +102,8 @@ export function rejectRepeatFlag(seen, flag) {
  * case. Lives beside flagValue, whose indexOf/value pairing it builds on, so the views'
  * scans cannot drift apart. */
 export function parseGrepFlag(args, missingValueError) {
-    const i = args.indexOf("--grep");
-    const rest = i >= 0 ? args.filter((_, j) => j !== i + 1) : args;
-    const raw = flagValue(args, "--grep");
-    if (raw === null)
-        return { rest, pattern: null };
-    if (raw === undefined || raw === "")
-        fail(missingValueError);
-    return { rest, pattern: raw };
+    const { rest, value } = takeValuedFlag(args, "--grep", missingValueError);
+    return { rest, pattern: value };
 }
 /** Parse an optional `--type <eventType>` exact-type filter flag for the event feed view
  * (logs): the exact type id, or null when absent, returned alongside `rest` — the args with
@@ -69,14 +114,24 @@ export function parseGrepFlag(args, missingValueError) {
  * caller's wording (each view names its own command) — the same error the `--type` gate spec
  * (typeFlagSpec) reports earlier for the trailing-no-value case. */
 export function parseTypeFlag(args, missingValueError) {
-    const i = args.indexOf("--type");
-    const rest = i >= 0 ? args.filter((_, j) => j !== i + 1) : args;
-    const raw = flagValue(args, "--type");
-    if (raw === null)
-        return { rest, type: null };
-    if (raw === undefined || raw === "")
-        fail(missingValueError);
-    return { rest, type: raw };
+    const { rest, value } = takeValuedFlag(args, "--type", missingValueError);
+    return { rest, type: value };
+}
+/** Parse an optional `--result <class>[,...]` flag for the history trail form: the raw value
+ * (null when absent) alongside `rest`, the args with the value token removed so a class name
+ * cannot be read as a positional. Validation of the classes belongs to the caller
+ * (parseHistoryResultList); a valueless or empty value fails with `missingValueError`. */
+export function parseResultFlag(args, missingValueError) {
+    const { rest, value } = takeValuedFlag(args, "--result", missingValueError, true);
+    return { rest, raw: value };
+}
+/** Parse an optional `--model <selector>[,...]` flag for the history trail form: the raw value
+ * (null when absent) alongside `rest`, the args with the value token removed so a selector
+ * cannot be read as a positional. Validation belongs to the caller (parseHistoryModelList); a
+ * valueless or empty value fails with `missingValueError`. */
+export function parseModelFlag(args, missingValueError) {
+    const { rest, value } = takeValuedFlag(args, "--model", missingValueError, true);
+    return { rest, raw: value };
 }
 /** Parse a `-n`-style count flag value: a positive integer, or fail with a clear message.
  * Unvalidated, NaN/0/negative limits make readEvents' `slice(-limit)` dump the whole log
@@ -111,18 +166,47 @@ export function parsePositionFlag(flag, raw, example) {
     return n;
 }
 /** Resolve a read-only command's `--role <id>` scope: the role id, or null when the flag is
- * absent. The id is validated against built-ins PLUS user-defined loops, read through
+ * absent. The id is validated against built-ins PLUS user-defined roles, read through
  * loadConfigCached (which never throws) so a transiently broken tumwater.json cannot take a
  * read-only view down — a broken file falls back to the built-in catalog rather than refusing
  * every id. Without --role no config is read. (State-changing commands instead resolve --role
  * against loadConfig and fail loudly on a broken file, as operator/operator-commands.ts and
  * prompt-commands.ts do.) The id
  * set comes from config.knownRoleIdsCached, the one home of the cached-with-built-in-fallback
- * rule. Shared by the tail views that scope their output to one loop (cmdLogs, cmdHistory). */
-export function parseRoleScope(root, args) {
-    if (!args.includes("--role"))
+ * rule. Shared by the tail views that scope their output to one role (cmdLogs, cmdHistory). */
+export function parseRoleScope(root, args, flag = "--role", missingValue = ROLE_VALUE_ERROR) {
+    if (!args.includes(flag))
         return null;
-    return parseRoleFlag(args, knownRoleIdsCached(root));
+    return parseRoleFlag(args, knownRoleIdsCached(root), flag, missingValue);
+}
+/** Resolve `history --role <id>[,<id>...]`: the listed role ids (canonical, deduplicated,
+ * first-seen order), or null when the flag is absent (no config read then, as parseRoleScope).
+ * Each piece is validated like parseRoleScope's id; empty pieces are dropped, and a value with
+ * no piece left fails with ROLE_VALUE_ERROR. */
+export function parseRoleListScope(root, args) {
+    return args.includes("--role") ? parseRoleListFlag(args, knownRoleIdsCached(root)) : null;
+}
+/** Parse `--role <id>[,<id>...]`: the listed role ids (canonical, deduplicated, first-seen
+ * order), or null when the flag is absent. Empty pieces are dropped, and a value with no piece
+ * left fails with ROLE_VALUE_ERROR. `validIds` defaults to the built-in catalog, as
+ * parseRoleFlag. */
+export function parseRoleListFlag(args, validIds) {
+    const typed = flagValue(args, "--role");
+    if (typed === null)
+        return null;
+    const pieces = splitCommaList(typed ?? "");
+    if (pieces.length === 0)
+        fail(ROLE_VALUE_ERROR);
+    const ids = validIds ?? allRoleIds();
+    const out = [];
+    for (const piece of pieces) {
+        const role = canonicalRoleId(piece);
+        if (!ids.includes(role))
+            fail(unknownRoleMessage(role, ids));
+        if (!out.includes(role))
+            out.push(role);
+    }
+    return out;
 }
 /** Parse the `--port` flag value: an integer in 1..65535, or fail with a clear message.
  * Port 0 would make Node pick an ephemeral port while the CLI prints :0 — a URL that
@@ -241,9 +325,10 @@ export function failRivalShapes(subject, rival, why) {
  * "logs --since …" instead of the malformed and missing-value forms naming a bare "--since".
  * Rival-flag rules stay in each command body, checked on the returned non-null value — so a
  * malformed or over-cap `--since` fails on its own wording before a rival-flag check fires,
- * the same precedence a command with only --since shows. */
-export function parseSinceFlag(args, label, maxMs) {
-    const raw = flagValue(args, "--since");
+ * the same precedence a command with only --since shows. `flag` defaults to `--since`; logs,
+ * history and report read their `--until` bound through the same idiom. */
+export function parseSinceFlag(args, label, maxMs, flag = "--since") {
+    const raw = flagValue(args, flag);
     if (raw === null)
         return null;
     const ms = parseDurationFlag(label, raw);
@@ -251,17 +336,17 @@ export function parseSinceFlag(args, label, maxMs) {
     return ms;
 }
 /** Parse an optional `--role <id>` flag: the validated role id, or null when absent.
- * Shared by every command that scopes to one loop so their validation and error messages
+ * Shared by every command that scopes to one role so their validation and error messages
  * cannot drift. `validIds` is the set of ids this command accepts — callers pass
- * knownRoleIds(config) so user-defined loops are accepted like built-ins; it defaults to the
+ * knownRoleIds(config) so user-defined roles are accepted like built-ins; it defaults to the
  * catalog alone, which keeps in-process callers (and tests) that have no config working.
  */
-export function parseRoleFlag(args, validIds) {
-    const typed = flagValue(args, "--role");
+export function parseRoleFlag(args, validIds, flag = "--role", missingValue = ROLE_VALUE_ERROR) {
+    const typed = flagValue(args, flag);
     if (typed === null)
         return null;
     if (!typed)
-        fail(ROLE_VALUE_ERROR);
+        fail(missingValue);
     const role = canonicalRoleId(typed);
     const ids = validIds ?? allRoleIds();
     if (!ids.includes(role))

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

@@ -1,9 +1,8 @@
-// vocabulary: plain
 /** The free-form-prompt commands' bespoke argument parsers: `tumwater init` and
  * `tumwater prompt`, whose positionals are prompt TEXT rather than a token list. Every
  * shared helper in cli/cli-args.ts assumes flags claim their tokens and rejects whatever is
  * left over — exactly wrong here, where a misspelled flag must fail instead of being
- * silently baked into the prompt that every loop then ticks from. Both parsers therefore
+ * silently baked into the prompt that every role then runs from. Both parsers therefore
  * hand-roll the same discipline (a double-dash token must be a known flag, given at most
  * once; single-dash tokens are content) and share failStrayArg, so they live together
  * apart from cli/cli-args.ts's generic machinery — which also keeps that module, minus these
@@ -13,14 +12,16 @@ import { failOverDurationCap, parseBranchFlag, parseDurationFlag, parsePositionF
 import { PAUSE_FOR_MAX_MS } from "../operator/operator-intent.js";
 import { JSON_FLAG, ROLE_FLAG, ROLE_VALUE_ERROR, rejectUnknownDoubleDash, } from "./cli-flag-specs.js";
 import { fail } from "./cli-output.js";
+import { DOCTOR_CHECK_NAMES } from "../doctor/doctor-check-names.js";
+import { typoSuffix } from "../text/suggest.js";
 import { templateIds, unknownTemplateError } from "../init/init-templates.js";
 import { errorMessage } from "../text/text.js";
 /** Peel a positional-first command's bare tokens off the argument list: every flag-shaped
  * token rides in rest for rejectUnknownArgs, every bare token is a positional. For commands
- * with no valued flags (tick: `--json` alone; bug/plan via fileAndAnnounce) the split is a
- * prefix test — a negative tick number (`tick bugfix -3`) arrives flag-shaped and fails the
+ * with no valued flags (history: `--json` alone; bug/plan via fileAndAnnounce) the split is a
+ * prefix test — a negative run number (`history bugfix -3`) arrives flag-shaped and fails the
  * unknown-arg gate, which is the right answer for a non-positive n anyway. Lives here with
- * the CLI's other argument helpers, shared by cli.ts's tick case and
+ * the CLI's other argument helpers, shared by cli.ts's history case and
  * backlog-cli.ts's fileAndAnnounce. */
 export function peelPositionals(args) {
     const positionals = [];
@@ -29,17 +30,34 @@ export function peelPositionals(args) {
         (arg.startsWith("-") ? rest : positionals).push(arg);
     return { positionals, rest };
 }
+/** Map `tumwater doctor`'s bare tokens to check names (case-insensitive, deduplicated, in the
+ * order named); undefined for none, which runs every check. An unknown name fails with the
+ * closest check as a hint. */
+export function parseDoctorChecks(positionals) {
+    if (positionals.length === 0)
+        return undefined;
+    const names = new Set();
+    for (const token of positionals) {
+        const name = DOCTOR_CHECK_NAMES.find((n) => n.toLowerCase() === token.toLowerCase());
+        if (name === undefined)
+            fail(`tumwater doctor: unknown check "${token}"${typoSuffix(token, DOCTOR_CHECK_NAMES)} (\`tumwater doctor\` lists every check by name)`);
+        else
+            names.add(name);
+    }
+    return [...names];
+}
 /** The `history` listing flags that take a separate value token. */
-const HISTORY_LISTING_VALUED_FLAGS = ["-n", "--since", "--grep", "--result", "--role"];
+const HISTORY_LISTING_VALUED_FLAGS = ["-n", "--since", "--until", "--grep", "--result", "--role", "--model", "--by"];
 /** True when `history`'s args are the one-run trail form (`history <role> <n>`, `history
- * <role> --last`): a token that is neither a flag nor the value of a listing-form valued flag.
- * A valued flag's value is skipped by position, so `--grep -x` stays a listing. */
+ * <role> --last`, bare `history --last`): `--last`, or a token that is neither a flag nor the
+ * value of a listing-form valued flag. A valued flag's value is skipped by position, so
+ * `--grep -x` stays a listing. */
 export function historyTrailForm(args) {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (HISTORY_LISTING_VALUED_FLAGS.includes(arg))
             i++;
-        else if (!arg.startsWith("-"))
+        else if (!arg.startsWith("-") || arg === "--last")
             return true;
     }
     return false;
@@ -69,9 +87,10 @@ function readPromptFile(file) {
     }
 }
 /** A `--file <path>` value that must be present: the one home of the missing-value refusal
- * shared by the init and prompt parsers (two call sites — parseInitArgs' and parsePromptArgs'
- * --file branches), so the wording cannot drift between them. The flag token itself is
- * claimed by each parser's stray-argument accounting; this helper only owns the value. */
+ * shared by every `--file`-taking parser — init, prompt's edit and enqueue branches, plan/bug
+ * add and edit (fileAndAnnounce / editAndAnnounce), and the questions command — so the wording
+ * cannot drift between them. The flag token itself is claimed by each parser's stray-argument
+ * accounting; this helper only owns the value. */
 export function promptFileValue(file) {
     if (!file)
         fail("--file needs a path");
@@ -90,7 +109,7 @@ function readPromptFileChecked(file) {
 /** Fail when a read `--file` prompt holds no text: an empty (or whitespace-only) file reads
  * as an empty prompt, which the bare-init path would then treat as "re-seed from README.md"
  * (the operator's --file argument silently ignored on an initialized repo), and a generic
- * "an initial prompt is required" (which never names the file) on a fresh one; the prompt
+ * "a brief is required" (which never names the file) on a fresh one; the prompt
  * queue would enqueue nothing. Names the file, like every other bad --file shape. Shared by
  * the init and prompt parsers, so the message cannot drift between them. */
 function failEmptyPromptFile(file, contents) {
@@ -129,7 +148,7 @@ function rejectDuplicateFlags(args, flags) {
  * once; with `--file` present nothing but the other flags may accompany it; a `--branch
  * <name>` pair and the valueless flags are never prompt content; single-dash positionals are
  * prompt content, not flags. Without these checks a misspelled --file would be baked into the
- * initial prompt — injected into every tick of every loop until someone edits the project
+ * brief text — injected into every run of every role until someone edits the project
  * brief. */
 export function parseInitArgs(args) {
     const known = INIT_FLAG_SPECS.flatMap((s) => s.names);
@@ -226,11 +245,12 @@ const PROMPT_FLAG_SPECS = [
     { names: ["--file"], value: true, valueName: "<path>" },
     { names: ["--at"], value: true, valueName: "<duration>" },
     { names: ["--attach"], value: true, valueName: "<path>" },
+    { names: ["--grep"], value: true, valueName: "<text>" },
 ];
 /** `tumwater prompt` argument handling, following parseInitArgs' pattern. Like init's,
  * positionals are free-form prompt content — but a double-dash token must be a real flag
- * (`--role <id>`, `--list`, `--json`, `--cancel <n>`, `--edit <n>`, `--top <n>`, `--file <path>`,
- * `--at <duration>`), or
+ * (`--role <id>`, `--list`, `--json`, `--grep <text>`, `--cancel <n>`, `--edit <n>`,
+ * `--top <n>`, `--file <path>`, `--at <duration>`), or
  * it would be baked into the queued prompt (the same class of bug parseInitArgs fixed: today
  * `tumwater prompt --foo text` enqueues "--foo text"). Single-dash positionals remain prompt
  * content. `--list`, `--cancel`, `--edit` and `--top` are mutually exclusive and may
@@ -252,6 +272,7 @@ export function parsePromptArgs(args) {
     const topFlag = args.indexOf("--top");
     const fileFlag = args.indexOf("--file");
     const atFlag = args.indexOf("--at");
+    const grepFlag = args.indexOf("--grep");
     // --attach is repeatable: every occurrence claims itself and its value token, like --role's
     // single pair, so the pairs ride out of the prompt text in every mode.
     const attachFlags = args.flatMap((a, i) => (a === "--attach" ? [i] : []));
@@ -281,6 +302,13 @@ export function parsePromptArgs(args) {
     // prompt text (or beside a state change), so it is refused before either branch runs.
     if (jsonFlags.length > 0 && listFlag < 0)
         fail("--json only applies to --list");
+    if (grepFlag >= 0 && listFlag < 0)
+        fail("--grep only applies to --list");
+    const grepRaw = grepFlag >= 0 ? args[grepFlag + 1] : undefined;
+    if (grepFlag >= 0 && (!grepRaw || grepRaw.startsWith("--"))) {
+        fail("--grep needs text (usage: tumwater prompt --list --grep <text>)");
+    }
+    const grepClaim = grepFlag >= 0 ? [grepFlag, grepFlag + 1] : [];
     // The queue-only flags --file and --at have nothing to mean in the read-only and destructive
     // modes (--list and --cancel): --file is the file-shaped twin of free-form text (--edit
     // accepts it as its replacement text, so the editFlag test below exempts that one mode), and
@@ -317,8 +345,8 @@ export function parsePromptArgs(args) {
         failOverDurationCap("--at", atDelayMs, PAUSE_FOR_MAX_MS);
     }
     if (listFlag >= 0) {
-        failStrayArg(args, "with --list there is no prompt text", listFlag, ...jsonFlags, ...roleClaim);
-        return { mode: "list", role, json: jsonFlags.length > 0 };
+        failStrayArg(args, "with --list there is no prompt text", listFlag, ...jsonFlags, ...roleClaim, ...grepClaim);
+        return { mode: "list", role, json: jsonFlags.length > 0, grep: grepRaw ?? null };
     }
     if (cancelFlag >= 0) {
         const n = parsePositionFlag("--cancel", args[cancelFlag + 1], "--cancel 2");

package/dist/src/cli/cli-editor.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fail } from "./cli-output.js";
+import { removeTree } from "../files/files.js";
 /** Signal number → name, for the shell's 128+n convention: a shell that does not re-raise a
  * signal-killed child (dash on Linux) exits with 128+signo, so node sees an exit status where
  * bash on macOS lets it see the signal. Keyed by number, so a later alias (SIGABRT over SIGIOT)
@@ -55,7 +56,7 @@ export function editInEditor(initial, fileName, fallback = "pass the new text or
         }
     }
     finally {
-        fs.rmSync(dir, { recursive: true, force: true });
+        removeTree(dir);
     }
     // fail() exits the process, which would skip the finally above, so it runs after cleanup.
     if (failure !== undefined)