tumwater 0.2.0 → 0.3.0

package/dist/src/cli/cli-flag-specs.js

@@ -1,6 +1,6 @@
 /** The declarative flag-vocabulary layer shared by every command's argument gate: the
  * FlagSpec shape, the per-flag specs (ROLE_FLAG, durationFlagSpec, REASON_FLAG, sinceFlagSpec,
- * N_FLAG, JSON_FLAG, grepFlagSpec, RUN_FLAG_SPECS), and the unknown-argument gate
+ * N_FLAG, JSON_FLAG, grepFlagSpec, START_FLAG_SPECS), and the unknown-argument gate
  * (rejectUnknownArgs, with rejectEqualsForm). Split from cli/cli-args.ts, whose imperative
  * single-flag parsers (flagValue, parseCountFlag, parseDurationFlag, parseRoleFlag, ...)
  * stay there — one module per layer, so the vocabulary a command accepts and the parsers
@@ -11,7 +11,8 @@
 import { fail } from "./cli-output.js";
 import { failOverDurationCap, parseCountFlag, parseDurationFlag, parsePortFlag, rejectRepeatFlag } from "./cli-args.js";
 import { PAUSE_FOR_MAX_MS } from "../operator/operator-intent.js";
-import { typoSuffix } from "../text/suggest.js";
+import { allRoleIds } from "../roles/roles.js";
+import { didYouMean, suggestClosest, typoSuffix } from "../text/suggest.js";
 import { gotSuffix } from "../text/text.js";
 /** One command's accepted flag list as error-message text (`--file <path>, --branch <name>, …`),
  * derived from the specs — the one home of the rendering, so the lists the error messages
@@ -42,10 +43,18 @@ export function rejectUnknownDoubleDash(command, args, specs) {
  * (rejectUnknownDoubleDash) print, so the message cannot drift between the two gates. The
  * valid-flags list is followed by text/suggest.ts's did-you-mean hint when the token is a near
  * miss of an accepted spelling (`--rol` → `--role`), the same annotation every other unknown-X
- * error carries; a token far from every flag gets only the list. */
+ * error carries; a token far from every flag gets only the list. A bare token that names (or
+ * nearly names) a role id, on a command taking ROLE_FLAG, instead gets `did you mean \`--role
+ * <id>\`?` (`tumwater wake feature`); `role` is exempt because it peels its own positional id,
+ * so a stray second token there is not a missing flag. Custom (config-defined) roles get no
+ * hint: this parse-time gate has no config, so only allRoleIds() are matched. */
 function failUnknownArgument(command, arg, specs) {
     const spellings = specs.flatMap((s) => s.names);
-    fail(`unknown argument: ${arg} (valid flags for tumwater ${command}: ${validFlagsList(specs)})${typoSuffix(arg, spellings)}`);
+    const roleId = specs.includes(ROLE_FLAG) && !arg.startsWith("-") && command !== "role"
+        ? suggestClosest(arg, allRoleIds())
+        : null;
+    const suffix = roleId !== null ? didYouMean(`--role ${roleId}`) : typoSuffix(arg, spellings);
+    fail(`unknown argument: ${arg} (valid flags for tumwater ${command}: ${validFlagsList(specs)})${suffix}`);
 }
 /** A `--flag=value` token's flag name ("--role" from "--role=feature"), or null when the
  * token is not in equals form. "--=x" and bare "--" carry no flag name and stay null. */
@@ -77,7 +86,7 @@ export function rejectEqualsForm(arg, specs) {
  * gate below, so the three wordings cannot drift (the drift-guard test imports it). */
 export const ROLE_VALUE_ERROR = "--role needs a role id (e.g. `--role feature`)";
 /** The missing-or-flag-shaped-value error parseBranchFlag (cli/cli-args.ts) shares with
- * RUN_FLAG_SPECS' --branch entry, for the same no-drift reason. */
+ * START_FLAG_SPECS' --branch entry, for the same no-drift reason. */
 export const BRANCH_VALUE_ERROR = "--branch needs a branch name (e.g. `--branch release/2.0`)";
 /** The `--role <id>` flag spec, shared by every role-targeting command (logs, reset-counters,
  * wake, abort, pause, resume): one definition of the flag's spelling and value shape so the
@@ -89,6 +98,16 @@ export const ROLE_FLAG = {
     valueName: "<id>",
     missingValue: ROLE_VALUE_ERROR,
 };
+/** The missing-value error for `logs --transcript` (LOGS_TRANSCRIPT_FLAG's trailing gate). */
+export const LOGS_TRANSCRIPT_VALUE_ERROR = "--transcript needs a role id (e.g. `--transcript feature`)";
+/** The `--transcript <id>` flag spec of `logs`: the role whose agent transcript to print. A
+ * separate constant from ROLE_FLAG because its missing-value text names `--transcript`. */
+export const LOGS_TRANSCRIPT_FLAG = {
+    names: ["--transcript"],
+    value: true,
+    valueName: "<id>",
+    missingValue: LOGS_TRANSCRIPT_VALUE_ERROR,
+};
 /** The `--for <duration>` flag spec factory, accepted by `pause` (the timed pause) and
  * `run` (the windowed run): one definition of the flag's spelling and value shape, beside
  * ROLE_FLAG, so the gate's accepted vocabulary and parseDurationFlag's error messages cannot
@@ -183,6 +202,19 @@ export function sinceFlagSpec(label) {
         },
     };
 }
+/** The `--until <duration>` flag spec of `logs`, `history` and `report`: ends the `--since`
+ * window that long ago. `label` names the command with the flag (e.g. "logs --until"). */
+export function untilFlagSpec(label) {
+    return {
+        names: ["--until"],
+        value: true,
+        valueName: "<duration>",
+        missingValue: `${label} needs a value`,
+        validate: (value) => {
+            parseDurationFlag(label, value);
+        },
+    };
+}
 /** The `-n <count>` flag spec, shared by the two tail views that take a row count (logs,
  * history): one definition of the flag's spelling and value shape, beside sinceFlagSpec, so the
  * gate's accepted vocabulary and parseCountFlag's error messages cannot drift apart. validate
@@ -196,12 +228,27 @@ export const N_FLAG = {
     },
 };
 /** The `--json` flag spec, shared by every command with a machine-readable form (status,
- * doctor, logs, history, tick, diff, backlog, role, report, prompt --list): one definition of
+ * doctor, logs, history, diff, backlog, role, report, prompt --list): one definition of
  * the flag's spelling, beside ROLE_FLAG and sinceFlagSpec, so the gate's accepted vocabulary
  * cannot drift apart. It takes no value and carries no per-command wording — unlike its
  * siblings it needs neither a factory nor a missing-value error — so the constant is the
  * whole spec, and the render-vs-JSON switch stays in each command body beside its render. */
 export const JSON_FLAG = { names: ["--json"] };
+/** The `-f/--follow` flag spec, shared by every command with a follow view (logs, history,
+ * status, queue, report, backlog and diff — each snapshot command's `-f/--follow` twin): one
+ * definition of the flag's spelling, beside ROLE_FLAG and JSON_FLAG, so the gate's accepted
+ * vocabulary cannot drift apart. It takes no value, like JSON_FLAG; each body renders its
+ * own live view, and detects the flag through hasFollowFlag, so the spelling lives in exactly
+ * one place. */
+export const FOLLOW_FLAG = { names: ["-f", "--follow"] };
+/** Whether an arg array carries the `-f/--follow` flag — the detection every follow-capable
+ * command body spelled out as an `includes("-f") || includes("--follow")` one-liner over
+ * its own arg array (`args` for status, queue, report and diff; `rest` for logs, history and
+ * backlog). Now derived from FOLLOW_FLAG's own spelling, so the detection cannot drift from
+ * the gate's accepted vocabulary. */
+export function hasFollowFlag(args) {
+    return FOLLOW_FLAG.names.some((name) => args.includes(name));
+}
 /** The `--ready` flag spec, accepted by `backlog`: keep only the entries no hold keeps from
  * being picked. Value-less, like STAT_FLAG. */
 export const READY_FLAG = { names: ["--ready"] };
@@ -211,10 +258,35 @@ export const REPROBE_FLAG = { names: ["--reprobe"] };
 /** The `--problems` flag spec, accepted by `doctor`: print only the warn and fail rows. Value-less,
  * like REPROBE_FLAG. */
 export const PROBLEMS_FLAG = { names: ["--problems"] };
+/** The `--kill-orphans` flag spec, accepted by `doctor`: first kill the orphaned processes the
+ * orphans check lists, each with its descendants. Value-less, like PROBLEMS_FLAG. */
+export const KILL_ORPHANS_FLAG = { names: ["--kill-orphans"] };
 /** The `--stat` flag spec, accepted by `diff --role`: print each patch as its `git diff --stat`
  * summary. Value-less, like JSON_FLAG. */
 export const STAT_FLAG = { names: ["--stat"] };
-/** The `--summary` flag spec, accepted by `history`: tally each loop's tick outcomes instead of
+/** The `--overlaps` flag spec, accepted by `diff`: list the files two or more roles' pending
+ * changes touch. Value-less, like STAT_FLAG. */
+export const OVERLAPS_FLAG = { names: ["--overlaps"] };
+/** The missing-value wording for DIFF_PATH_FLAG. */
+const DIFF_PATH_VALUE_ERROR = "diff --path needs a path (e.g. `--path src/cli.ts`)";
+/** The `--path` flag spec, accepted by `diff --role`: keep only the part of each role's view
+ * under one repo-relative file or directory. Valued, unlike OVERLAPS_FLAG. */
+export const DIFF_PATH_FLAG = {
+    names: ["--path"],
+    value: true,
+    valueName: "<path>",
+    missingValue: DIFF_PATH_VALUE_ERROR,
+};
+/** The `--patch` flag spec, accepted by `history <role> <n>`: append the run's commit patch.
+ * Value-less, like STAT_FLAG. */
+export const PATCH_FLAG = { names: ["--patch"] };
+/** The `--transcript` flag spec, accepted by `history <role> <n>`: append that run's agent
+ * transcript to its trail. Value-less, like STAT_FLAG. */
+export const TRANSCRIPT_FLAG = { names: ["--transcript"] };
+/** The `--prompt` flag spec: value-less, used by `logs` (the transcript view) and by the
+ * `history <role>` trail (with `--transcript`). */
+export const PROMPT_FLAG = { names: ["--prompt"] };
+/** The `--summary` flag spec, accepted by `history`: tally each role's run outcomes instead of
  * printing the rows. Value-less, like STAT_FLAG. */
 export const SUMMARY_FLAG = { names: ["--summary"] };
 /** The `--count` flag spec, accepted by `logs`: tally the selected window's event types
@@ -227,10 +299,10 @@ export const FORCE_FLAG = { names: ["--force"] };
 /** The `--dry-run` flag spec: preview a reclaim pass or a retire without changing anything. Beside
  * FORCE_FLAG so its spelling lives with the other boolean flags the gate admits. */
 export const DRY_RUN_FLAG = { names: ["--dry-run"] };
-/** The `--last` flag spec for `tumwater tick <role> --last`: one definition of the flag's
- * spelling, beside JSON_FLAG, so tick's gate and cmdTick's arity guards cannot disagree on
+/** The `--last` flag spec for `tumwater history <role> --last`: one definition of the flag's
+ * spelling, beside JSON_FLAG, so history's gate and cmdRunDetail's arity guards cannot disagree on
  * what the command admits. Like --json it takes no value and needs no wording — the
- * command body owns the meaning (resolve the newest completed tick instead of numbering
+ * command body owns the meaning (resolve the newest completed run instead of numbering
  * one) and the arity rules it implies. */
 export const LAST_FLAG = { names: ["--last"] };
 /** The `--grep <text>` flag spec shared by the two filtering views (logs, history): one
@@ -256,61 +328,94 @@ export function typeFlagSpec(missingValue) {
 export function resultFlagSpec(missingValue) {
     return { names: ["--result"], value: true, valueName: "<class>", missingValue };
 }
-/** `tumwater run`'s flag vocabulary: `--branch <name>` (the target branch, parsed by
- * parseBranchFlag), `--once` (one full round of ticks, then exit), `--role <id>`
- * (scope a --once round to one loop, parsed by parseRoleFlag), and `--gui` (also serve the
- * browser dashboard on its defaults; port/token selection stays on `tumwater gui`). Exported
+/** `history --model <selector>[,...]`: keeps the runs that started on the listed models;
+ * `missingValue` is the same string the command body fails with. */
+export function modelFlagSpec(missingValue) {
+    return { names: ["--model"], value: true, valueName: "<selector>", missingValue };
+}
+/** `history --by <role|model>`: how `--summary` groups its lines; `missingValue` is the same
+ * string the command body fails with. */
+export function byFlagSpec(missingValue) {
+    return { names: ["--by"], value: true, valueName: "<role|model>", missingValue };
+}
+/** `tumwater gui`'s `--port <n>` flag: the dashboard port, shape-checked by parsePortFlag so
+ * `gui --port abc` and `start --gui --port abc` are named before the ready-repo gate can mask
+ * them. Shared by `gui` and `start --gui` (START_FLAG_SPECS) so the shape check and the
+ * valid-flags error rendering cannot drift between the two commands. */
+const PORT_FLAG = {
+    names: ["--port"],
+    value: true,
+    valueName: "<n>",
+    validate: (value) => {
+        parsePortFlag(value);
+    },
+};
+/** The one refusal for a trailing `gui --token` with no value, phrased for what the
+ * flag actually needs — the spec's missingValue (so the gate's early report says it)
+ * and cmdGui's own re-check share this one wording. Declared above START_FLAG_SPECS
+ * (whose TOKEN_FLAG references it at module load), not between the two spec arrays. */
+export const TOKEN_VALUE_ERROR = "--token requires a non-empty secret (e.g. `--token s3cret`)";
+/** `tumwater gui`'s `--all-interfaces` flag: serve the dashboard on every network
+ * interface instead of loopback, exposing it to the LAN. Value-less. Shared by `gui` and
+ * `start --gui` (START_FLAG_SPECS) so the accepted vocabulary cannot drift between the
+ * two commands. */
+const ALL_INTERFACES_FLAG = { names: ["--all-interfaces"] };
+/** `tumwater gui`'s `--token <secret>` flag: the dashboard auth token, the gate behind
+ * which the dashboard sits when the operator protects it. Shared by `gui` and
+ * `start --gui` (START_FLAG_SPECS); its missing-value wording is TOKEN_VALUE_ERROR, the
+ * same error cmdGui and cmdStart's tokenValueProblem re-check fail with. */
+const TOKEN_FLAG = {
+    names: ["--token"],
+    value: true,
+    valueName: "<secret>",
+    missingValue: TOKEN_VALUE_ERROR,
+};
+/** `tumwater start`'s flag vocabulary: `--branch <name>` (the target branch, parsed by
+ * parseBranchFlag), `--once` (one full round of runs, then exit), `--json` (with `--once`, print
+ * the round's outcomes as one JSON document), `--role <id>`
+ * (scope a --once round to one role, parsed by parseRoleFlag), `--gui` (also serve the browser
+ * dashboard), and `--port <n>`, `--all-interfaces` and `--token <secret>` (forwarded onto the
+ * dashboard child, shared with `tumwater gui`). Exported
  * so the caller's rejectUnknownArgs check and its tests share one definition of what `start`
  * (and its hidden alias `run`) accepts — before this vocabulary existed, run parsed --branch
  * and silently ignored every other flag, so a typo'd option ran the daemon with default
  * behavior. */
-export const RUN_FLAG_SPECS = [
+export const START_FLAG_SPECS = [
     { names: ["--branch"], value: true, valueName: "<name>", missingValue: BRANCH_VALUE_ERROR },
     { names: ["--once"] },
+    JSON_FLAG,
     // `run --gui` is the one-command form of the dashboard: it boots the team and serves the
-    // browser dashboard at its defaults, loopback on port 7180. The dashboard's own --port,
-    // --all-interfaces, and --token stay on `tumwater gui`; widening them here would mean two
-    // flag vocabularies to keep in step. `run --gui --once` is refused in cmdRun beside the
-    // timer it arms.
+    // browser dashboard on its defaults, loopback on port 7180. `--port <n>` (shared with `tumwater
+    // gui` via PORT_FLAG) picks another port, and `--all-interfaces`/`--token <secret>` (shared
+    // with `tumwater gui` via ALL_INTERFACES_FLAG/TOKEN_FLAG) forward onto the dashboard child
+    // exactly as a direct `tumwater gui` would serve them. `run --gui --once` and any of the
+    // three dashboard-only flags without `--gui` are refused in cmdStart beside the timer it arms.
     { names: ["--gui"] },
+    PORT_FLAG,
+    ALL_INTERFACES_FLAG,
+    TOKEN_FLAG,
     // `run --tui` is the one-command form of the observer TUI: it boots the team and hosts the
     // same in-terminal TUI `tumwater tui` attaches from another terminal. Its flag vocabulary
-    // stays at run's (`tumwater tui` takes no flags); `run --tui --once` is refused in cmdRun
+    // stays at run's (`tumwater tui` takes no flags); `run --tui --once` is refused in cmdStart
     // beside the `--gui` rival.
     { names: ["--tui"] },
     // `run --for <duration>` (the windowed run): the same spec `pause --for` passes, so the
     // gate's accepted vocabulary and parseDurationFlag's error wording cannot drift; the
     // 90-day cap is the spec's own validate (shared with pause), and the --once rival rule
-    // stays in cmdRun beside the timer it arms.
+    // stays in cmdStart beside the timer it arms.
     durationFlagSpec("start --for"),
     ROLE_FLAG,
 ];
-/** The one refusal for a trailing `gui --token` with no value, phrased for what the
- * flag actually needs — the spec's missingValue (so the gate's early report says it)
- * and cmdGui's own re-check share this one wording. */
-export const TOKEN_VALUE_ERROR = "--token requires a non-empty secret (e.g. `--token s3cret`)";
-/** `tumwater gui`'s flag vocabulary: `--port <n>` (the dashboard port, shape-checked by
- * parsePortFlag so `gui --port abc` is named before the ready-repo gate can mask it),
- * `--all-interfaces`, and `--token <secret>` (the dashboard auth token). Exported so
- * cli.ts's rejectUnknownArgs check and its tests share one definition of what `gui`
- * accepts, like every other command's spec in this module; cmdGui re-runs parsePortFlag
- * and the token emptiness check on the accepted args, so the gate and the body cannot
- * drift apart. */
-export const GUI_FLAG_SPECS = [
-    {
-        names: ["--port"],
-        value: true,
-        valueName: "<n>",
-        validate: (value) => {
-            parsePortFlag(value);
-        },
-    },
-    { names: ["--all-interfaces"] },
-    { names: ["--token"], value: true, valueName: "<secret>", missingValue: TOKEN_VALUE_ERROR },
-];
+/** `tumwater gui`'s flag vocabulary: `--port <n>` (the dashboard port), `--all-interfaces`,
+ * and `--token <secret>` (the dashboard auth token), each shared with `start --gui` via the
+ * same module const so the accepted vocabulary cannot drift between the two commands.
+ * Exported so cli.ts's rejectUnknownArgs check and its tests share one definition of what
+ * `gui` accepts, like every other command's spec in this module; cmdGui re-runs parsePortFlag
+ * and the token value check on the accepted args, so the gate and the body cannot drift apart. */
+export const GUI_FLAG_SPECS = [PORT_FLAG, ALL_INTERFACES_FLAG, TOKEN_FLAG];
 /** Fail when any argument was not consumed by this command's known flags — a misspelled flag
  * (e.g. `--rol` instead of `--role`) would otherwise be silently ignored and the command runs with
- * default behavior, which is worse than an error: `reset-counters --rol x` zeroed every loop
+ * default behavior, which is worse than an error: `reset-counters --rol x` zeroed every role
  * instead of one, and `gui --portt 8080` served on the default port. Valueless flags claim one
  * token; valued flags claim two — and a valued flag left without its value fails right here, with
  * the spec's missingValue wording: cli.ts runs this gate before the ready-repo gate and the command

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

@@ -0,0 +1,51 @@
+/** `tumwater init`'s implementation (src/init/init.ts does the work; this prints the report).
+ * Split out of cli/cli-start.ts, whose name is for start alone: every command it dispatches
+ * delegates to its own module (operator/operator-commands.ts, config-commands.ts, log-commands.ts,
+ * doctor.ts, …), and init is no exception. cli.ts stays the pure dispatcher. */
+import { say } from "./cli-output.js";
+import { parseInitArgs } from "./cli-command-args.js";
+import { initProject } from "../init/init.js";
+import { templateCatalog } from "../init/init-templates.js";
+/** `tumwater init`: seed a project directory from the operator's brief (src/init/init.ts does the
+ * work; this prints the report). --dry-run prints the would-be actions without writing
+ * anything; an already-initialized repo is reported as a no-op, never an error. */
+export async function cmdInit(root, args) {
+    const { prompt, branch, template, listTemplates, adopt, dryRun } = parseInitArgs(args);
+    if (listTemplates) {
+        for (const { id, description } of templateCatalog())
+            say(`${id} — ${description}`);
+        return;
+    }
+    const result = await initProject(root, prompt, branch ?? undefined, {
+        adopt,
+        dryRun,
+        template: template ?? undefined,
+    });
+    if (result.template !== "blank")
+        say(`template: ${result.template}`);
+    if (result.adopted) {
+        say(`${result.dryRun ? "would adopt" : "adopting"} an existing repo: the project brief goes in TUMWATER.md and README.md is left untouched`);
+    }
+    if (result.dryRun) {
+        if (result.repoInitialized && result.branch) {
+            say(`dry run — would initialize a new git repository on branch ${result.branch}`);
+        }
+        const list = (names) => (names.length > 0 ? names.join(", ") : "nothing");
+        say(`dry run — would create: ${list(result.created)}`);
+        say(`would leave alone: ${list(result.leftAlone)}`);
+        say("nothing written; re-run without --dry-run to apply");
+        return;
+    }
+    if (result.created.length === 0) {
+        say("already initialized; nothing to do");
+        return;
+    }
+    if (result.repoInitialized && result.branch) {
+        say(`initialized a new git repository on branch ${result.branch}`);
+    }
+    say(`created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`);
+    if (result.bootstrap !== null) {
+        say(`fresh project — maintenance roles wait until ${result.bootstrap} plans are done; remove "bootstrap" from tumwater.json to end that early`);
+    }
+    say("next: `tumwater start` in one terminal, `tumwater tui` in another");
+}

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

@@ -25,9 +25,9 @@ export async function runMarkerCommand(root, command, args) {
     // `pause` alone accepts `--for <duration>` (the timed pause) and `--reason <text>` (the
     // operator pause's why); `wake` alone accepts `--in <duration>` (the scheduled wake) and
     // `--cancel` (drop the pending scheduled wakes), `--list` (show them), and `--json`
-    // (with --list); `reclaim` alone accepts `--dry-run`; the other marker commands keep the
-    // plain --role vocabulary, so a stray --for, --reason, --in, --cancel, or --dry-run fails
-    // fast instead of being silently ignored.
+    // (with --list); `reclaim` alone accepts `--dry-run` (and `--json` with it); the other
+    // marker commands keep the plain --role vocabulary, so a stray --for, --reason, --in,
+    // --cancel, or --dry-run fails fast instead of being silently ignored.
     const perCommandFlags = {
         "reset-counters": [ROLE_FLAG],
         wake: [ROLE_FLAG, WAKE_IN_FLAG, WAKE_CANCEL_FLAG, WAKE_LIST_FLAG, JSON_FLAG],
@@ -38,7 +38,7 @@ export async function runMarkerCommand(root, command, args) {
             REASON_FLAG,
         ],
         resume: [ROLE_FLAG],
-        reclaim: [DRY_RUN_FLAG],
+        reclaim: [DRY_RUN_FLAG, JSON_FLAG],
         restart: [],
     };
     rejectUnknownArgs(command, args, perCommandFlags[command] ?? [ROLE_FLAG]);