tumwater 0.1.2 → 0.2.0

package/dist/src/cli/completion.js

@@ -0,0 +1,207 @@
+// vocabulary: plain
+/** Shell completion derived from the help text. The spec is parsed from the same HELP stanzas
+ * `tumwater help <command>` and the unknown-command suggestion use, so a new command or flag
+ * completes the moment it gains a help stanza and can never drift from the listing. */
+import { customLoopNames, knownRoleIds, loadConfig } from "../config/config.js";
+import { AGENT_IDS, AGENT_KEYS, CLAUDE_AGENT_KEYS, MODEL_TIERS, ROLE_ENTRY_KEYS, TOP_LEVEL_KEYS } from "../config/config-schema.js";
+import { DOTTED_MAP_KEYS } from "../config/config-keys.js";
+import { HISTORY_RESULT_FLAG_NAMES } from "../history/history-data.js";
+import { templateIds } from "../init/init-templates.js";
+import { allRoleIds } from "../roles/roles.js";
+import { EVENT_TYPE_LABELS } from "../events/event-labels.js";
+import { HELP, helpStanzas } from "./help.js";
+export const SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
+/** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
+ * description column (two or more spaces). Bare lowercase words count inside `[...]` and as the
+ * leading run directly after the command; outside brackets the first other token ends the run, so
+ * a single-space description (`role <id> --clear-notes Clear that notebook`) adds nothing. */
+function usageWords(firstLine, command) {
+    const rest = firstLine.replace(new RegExp(`^ {2}tumwater ${command}`), "");
+    // Usage arguments follow the command after a single space; two or more spaces start the
+    // description.
+    const usage = /^ {2,}/.test(rest) ? "" : (rest.split(/ {2,}/)[0] ?? "");
+    const words = [];
+    let depth = 0;
+    let leading = true;
+    for (const token of usage.split(/\s+/).filter(Boolean)) {
+        // An angle-bracket alternation of plain words — `<bash|zsh|fish>`, the completion
+        // command's shell positional — expands to each alternative as a subcommand word, so
+        // `tumwater completion <TAB>` lists exactly the shells the command accepts. A bare
+        // placeholder like `<id>` or `<k>` carries no `|` and so stays a placeholder, skipped
+        // as before (its `<`/`>` never leave the token, so it never looked like a word).
+        const alternation = /^<([a-z][a-z-]*(?:\|[a-z][a-z-]*)+)>$/.exec(token);
+        if (alternation && leading) {
+            for (const alt of alternation[1].split("|"))
+                words.push(alt);
+            continue;
+        }
+        const bare = token.replace(/[[\]|]/g, "");
+        const isWord = /^[a-z][a-z-]*$/.test(bare);
+        if (isWord && (depth > 0 || token.startsWith("[") || leading))
+            words.push(bare);
+        else if (depth === 0 && !token.startsWith("[") && bare !== "")
+            leading = false;
+        for (const ch of token)
+            depth += ch === "[" ? 1 : ch === "]" ? -1 : 0;
+    }
+    return words;
+}
+export function completionSpec(help = HELP) {
+    const stanzas = helpStanzas(help);
+    const commands = [...new Set(stanzas.map((s) => s.command))];
+    const subcommands = {};
+    const flags = {};
+    for (const command of commands) {
+        const own = stanzas.filter((s) => s.command === command);
+        const flagSet = new Set(["--help"]);
+        const subs = new Set();
+        for (const stanza of own) {
+            for (const match of stanza.text.matchAll(/--[a-z][a-z-]*/g))
+                flagSet.add(match[0]);
+            for (const word of usageWords(stanza.text.split("\n")[0] ?? "", command))
+                subs.add(word);
+        }
+        flags[command] = [...flagSet].sort();
+        subcommands[command] = command === "help" ? commands : [...subs];
+    }
+    return { commands, subcommands, flags };
+}
+/** The ids `--role` completes: this repo's loop ids, or the built-in catalog when tumwater.json is
+ * unreadable (a broken config must not write errors into the operator's prompt). */
+export function completionRoleIds(root) {
+    try {
+        return knownRoleIds(loadConfig(root));
+    }
+    catch {
+        return allRoleIds();
+    }
+}
+/** The keys `config get|set|unset` complete: every form parseConfigKey accepts, with the
+ * role-scoped keys of this repo's base roles and custom loops (not instance ids like
+ * `feature-2`). A broken tumwater.json falls back to the built-in catalog rather than writing
+ * errors into the prompt. */
+export function completionConfigKeys(root) {
+    let roleIds;
+    try {
+        roleIds = [...allRoleIds(), ...customLoopNames(loadConfig(root))];
+    }
+    catch {
+        roleIds = allRoleIds();
+    }
+    const keys = [
+        ...TOP_LEVEL_KEYS,
+        ...MODEL_TIERS.map((tier) => `model.${tier}`),
+        ...AGENT_IDS.flatMap((id) => (id === "claude" ? CLAUDE_AGENT_KEYS : AGENT_KEYS).map((field) => `backends.${id}.${field}`)),
+        ...DOTTED_MAP_KEYS.flatMap((map) => roleIds.map((id) => `${map}.${id}`)),
+        ...roleIds.flatMap((id) => ROLE_ENTRY_KEYS.map((field) => `roles.${id}.${field}`)),
+    ];
+    return [...new Set(keys)];
+}
+/** Flags whose value is a file path: completion offers file names after them. */
+const PATH_FLAGS = ["--file", "--attach", "--notes-file", "--instructions-file"];
+/** The event-type codes `logs --type` filters by: the keys of the labels map, so a new event
+ * type completes the moment it gains a label. Sorted for a stable, alphabetical offer of a
+ * vocabulary too large to recall offhand — the same reason `--role`, `--template`, and
+ * `--result` complete their values. */
+const EVENT_TYPE_CODES = Object.keys(EVENT_TYPE_LABELS).sort();
+function bashScript(help) {
+    const spec = completionSpec(help);
+    const arms = spec.commands.map((command) => {
+        const subs = spec.subcommands[command] ?? [];
+        const flags = spec.flags[command] ?? [];
+        return [
+            `    ${command})`,
+            `      if [[ "$cur" == -* ]]; then`,
+            `        COMPREPLY=( $(compgen -W "${flags.join(" ")}" -- "$cur") )`,
+            ...(subs.length > 0
+                ? [
+                    `      elif [ "$COMP_CWORD" -eq 2 ]; then`,
+                    `        COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") )`,
+                ]
+                : []),
+            `      fi`,
+            `      ;;`,
+        ].join("\n");
+    });
+    return [
+        `# tumwater completion (generated from \`tumwater help\`)`,
+        `_tumwater() {`,
+        `  local cur="\${COMP_WORDS[COMP_CWORD]}"`,
+        `  local prev="\${COMP_WORDS[COMP_CWORD-1]}"`,
+        `  COMPREPLY=()`,
+        `  if [ "$prev" = "--role" ] || { [ "$COMP_CWORD" -eq 2 ] && [[ "\${COMP_WORDS[1]}" == role || "\${COMP_WORDS[1]}" == history ]] && [[ "$cur" != -* ]]; }; then`,
+        `    COMPREPLY=( $(compgen -W "$(tumwater completion --roles 2>/dev/null)" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  case "$prev" in ${PATH_FLAGS.join("|")})`,
+        `    COMPREPLY=( $(compgen -f -- "$cur") )`,
+        `    return 0`,
+        `    ;;`,
+        `  esac`,
+        `  if [ "$prev" = "--template" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${templateIds().join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--result" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--type" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${EVENT_TYPE_CODES.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$COMP_CWORD" -eq 3 ] && [ "\${COMP_WORDS[1]}" = config ] && [[ "\${COMP_WORDS[2]}" == get || "\${COMP_WORDS[2]}" == set || "\${COMP_WORDS[2]}" == unset ]] && [[ "$cur" != -* ]]; then`,
+        `    COMPREPLY=( $(compgen -W "$(tumwater completion --config-keys 2>/dev/null)" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$COMP_CWORD" -eq 1 ]; then`,
+        `    COMPREPLY=( $(compgen -W "${spec.commands.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  case "\${COMP_WORDS[1]}" in`,
+        ...arms,
+        `  esac`,
+        `  return 0`,
+        `}`,
+        `complete -F _tumwater tumwater`,
+        ``,
+    ].join("\n");
+}
+/** The value suffix a fish flag line carries: what completes after the flag. */
+function fishFlagValue(flag) {
+    if (flag === "--role")
+        return ` -x -a "(tumwater completion --roles 2>/dev/null)"`;
+    if (PATH_FLAGS.includes(flag))
+        return ` -r -F`;
+    if (flag === "--template")
+        return ` -x -a "${templateIds().join(" ")}"`;
+    if (flag === "--result")
+        return ` -x -a "${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")}"`;
+    if (flag === "--type")
+        return ` -x -a "${EVENT_TYPE_CODES.join(" ")}"`;
+    return "";
+}
+function fishScript(help) {
+    const spec = completionSpec(help);
+    const lines = [
+        `# tumwater completion (generated from \`tumwater help\`)`,
+        `complete -c tumwater -f`,
+        `function __tumwater_argc; count (commandline -opc); end`,
+        `complete -c tumwater -n __fish_use_subcommand -a "${spec.commands.join(" ")}"`,
+    ];
+    for (const command of spec.commands) {
+        const subs = spec.subcommands[command] ?? [];
+        if (subs.length > 0)
+            lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from ${command}; and test (__tumwater_argc) -eq 2" -a "${subs.join(" ")}"`);
+        for (const flag of spec.flags[command] ?? [])
+            lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from ${command}" -l ${flag.slice(2)}${fishFlagValue(flag)}`);
+    }
+    lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from role history; and test (__tumwater_argc) -eq 2" -a "(tumwater completion --roles 2>/dev/null)"`, `complete -c tumwater -n "__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get set unset; and test (__tumwater_argc) -eq 3" -a "(tumwater completion --config-keys 2>/dev/null)"`, ``);
+    return lines.join("\n");
+}
+export function completionScript(shell, help = HELP) {
+    if (shell === "fish")
+        return fishScript(help);
+    const bash = bashScript(help);
+    return shell === "zsh" ? `autoload -U +X bashcompinit && bashcompinit\n${bash}` : bash;
+}

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

@@ -1,12 +1,15 @@
+// vocabulary: plain
 import { loadConfigSafe, knownRoleIds } from "../config/config.js";
 import { fail, say, sayJson, sayJsonLine } from "./cli-output.js";
-import { setConfigKey, unsetConfigKey, parseConfigKey, unknownConfigKeyError, unknownRoleFieldError, } from "../config/config-write.js";
+import { setConfigKey, unsetConfigKey, } from "../config/config-write.js";
+import { canonicalConfigKey } from "../config/config-aliases.js";
+import { parseConfigKey, unknownConfigKeyError, unknownRoleFieldError } from "../config/config-keys.js";
 import { modelTierMap } from "../config/config-schema.js";
 import { unknownRoleMessage } from "../roles/roles.js";
 /** The `tumwater config` command's CLI layer (split out of operator/operator-commands.ts, which
  * keeps the other operator-command bodies): with no arguments, print the effective merged
  * config — exactly what `loadConfig(root)` returns — as pretty JSON, so an operator
- * debugging scheduling or custom-loop wiring sees what the fleet would actually load instead
+ * debugging scheduling or custom-loop wiring sees what the team would actually load instead
  * of overlaying defaults onto tumwater.json by hand. A query, not a writer: no redaction (the
  * config holds no secrets — provider keys belong to pi's own env) and no transformation,
  * including the per-role entries custom loops merge into. `get <key>` prints that one key's
@@ -17,7 +20,7 @@ import { unknownRoleMessage } from "../roles/roles.js";
  * not parseable JSON for a script and indistinguishable from a crash for a human. `set <key>
  * <value>` writes one top-level key through setConfigKey and prints one confirmation line
  * naming the key and its new value; `unset <key>` removes one value through unsetConfigKey
- * (the inverse of set) and confirms what, if anything, was removed. A running fleet picks the
+ * (the inverse of set) and confirms what, if anything, was removed. A running team picks the
  * change up on its next ~2 s config poll (newLiveConfigReload). A malformed or invalid
  * tumwater.json fails with validateConfig's actionable message and prints no JSON — the same
  * surfacing doctor's config check produces. The reading/writing halves live beside it in
@@ -30,12 +33,13 @@ export const CONFIG_USAGE = "usage: tumwater config [get <key> | set <key> <valu
 /** The key screens `config get` and `config unset` run before resolving or removing a value:
  * the shape parser's own error; the shared unknown-top-level-key message; then, for a dotted
  * key, the catalog's known-role check and the shared unknown-role-field message. A dotted key
- * naming a role the catalog (plus customLoops) does not know can never resolve, and a silent
+ * naming a role the catalog (plus customRoles) does not know can never resolve, and a silent
  * `null`/removal for it would read as a real unset when the operator misspelled the id. Fails
  * the process with whichever message applies; returns the parsed key and the freshly loaded
  * config for the caller's own read/mutation. (An unknown role id in the FILE is already a
  * validation error — this is the same rule at the CLI boundary.) */
-function screenOperableKey(root, k) {
+function screenOperableKey(root, key) {
+    const k = canonicalConfigKey(key);
     const parsed = parseConfigKey(k); // shape only — the verbs below own the unknown-key wording
     if (parsed.kind === "error")
         fail(parsed.error);
@@ -65,18 +69,17 @@ function screenOperableKey(root, k) {
 export async function cmdConfig(root, args = []) {
     const [sub, key, ...rest] = args;
     if (sub === "get") {
-        const k = key ?? "";
-        const { parsed, config } = screenOperableKey(root, k);
+        const { parsed, config } = screenOperableKey(root, key ?? "");
         const record = config;
         const value = parsed.kind === "map"
             ? record[parsed.map]?.[parsed.role]
             : parsed.kind === "tier"
                 ? modelTierMap(record.model)[parsed.tier] // a string is shorthand for { default }
                 : parsed.kind === "agent"
-                    ? record.agents?.[parsed.id]?.[parsed.field]
+                    ? record.backends?.[parsed.id]?.[parsed.field]
                     : parsed.kind === "role"
                         ? record.roles?.[parsed.id]?.[parsed.field]
-                        : record[k];
+                        : record[canonicalConfigKey(key ?? "")];
         sayJsonLine(value === undefined ? null : value); // Absent optional key → JSON null.
         return;
     }
@@ -85,7 +88,7 @@ export async function cmdConfig(root, args = []) {
         // this is the defensive tail for a direct caller, matching the bare-config tail below.
         if (key === undefined)
             fail(CONFIG_USAGE);
-        const k = key;
+        const k = canonicalConfigKey(key);
         // The same screens get runs first, so a typo'd top-level key, role id, or role field
         // fails identically — unsetConfigKey's own parse/field checks are the mutation-side
         // backstop, not the wording the operator sees.
@@ -112,7 +115,7 @@ export async function cmdConfig(root, args = []) {
         const result = setConfigKey(root, key ?? "", raw);
         if (!result.ok)
             fail(result.error);
-        say(`set ${key} to ${JSON.stringify(result.value)}`);
+        say(`set ${canonicalConfigKey(key ?? "")} to ${JSON.stringify(result.value)}`);
         // A bare `roles` set replaces the FILE's section, but the built-in catalog always merges
         // per entry at load, so the replacement cannot disable a role by omission. Say so here
         // rather than let the confirmation imply the role is gone.