@bli-cockpit/cli 0.2.224 → 0.2.237

package/dist/commands/local-args-docs-export.js

@@ -0,0 +1,23 @@
+/**
+ * `cockpit docs export` flag parsing (ticket 20694), split out of `local-args-tower-docs-msg.ts`,
+ * which sits at the file-size ratchet.
+ */
+import { optionalNonEmpty } from "./local-arg-values.js";
+const DOCS_EXPORT_FORMATS = ["md", "pdf", "docx", "txt"];
+/** Ticket 20694: `--format`/`--out` mean something on `export` alone, and an unknown format is refused by name. */
+export function parseDocsExportFlags(action, values) {
+    const format = optionalNonEmpty(values.flags.get("--format"))?.toLowerCase();
+    const outPath = optionalNonEmpty(values.flags.get("--out"));
+    if (action !== "export") {
+        if (format)
+            throw new Error("--format belongs to `cockpit docs export`.");
+        if (outPath)
+            throw new Error("--out belongs to `cockpit docs export`.");
+        return {};
+    }
+    const chosen = format === "markdown" ? "md" : format === "word" ? "docx" : format === "text" ? "txt" : (format ?? "md");
+    if (!DOCS_EXPORT_FORMATS.includes(chosen)) {
+        throw new Error(`docs export --format must be one of ${DOCS_EXPORT_FORMATS.join(", ")} (Word is docx), not "${format}".`);
+    }
+    return { exportFormat: chosen, ...(outPath ? { outPath } : {}) };
+}

package/dist/commands/local-args-tower-admin.js

@@ -301,6 +301,14 @@ export function parseTeamArgs(args) {
         }
         return { kind: "team", action: `github-login-${operation}`, personRef, githubLogin, ...common };
     }
+    if (verb === "timezone") {
+        const [operation, personRef, zone, ...extra] = rest;
+        if (!["set", "list"].includes(operation ?? "") || extra.length ||
+            (operation === "list" ? personRef !== undefined : !personRef || !zone)) {
+            throw new Error("team timezone takes set <person> <iana-zone> (or the word unknown), or list.");
+        }
+        return { kind: "team", action: operation === "set" ? "timezone-set" : "timezone-list", ...(personRef ? { personRef } : {}), ...(zone ? { zone } : {}), ...common };
+    }
     if (verb === "device") {
         return parseTeamDeviceArgs(rest, values.flags, common);
     }

package/dist/commands/local-args-tower-brain-ladder.js

@@ -0,0 +1,90 @@
+/**
+ * `cockpit brain ladder` argument parsing (BLI-19250): Edward's call ladder.
+ *
+ *   cockpit brain ladder show [--json]
+ *   cockpit brain ladder promote <class> [--anyway] [--note <text>] [--json]
+ *   cockpit brain ladder demote <class> [--note <text>] [--json]
+ *   cockpit brain ladder predict "<question>" [--context <text>] [--asker <label>] [--source-kind <k>] [--source-ref <ref>] [--json]
+ *   cockpit brain ladder answer "<what he answered>" (--prediction <uuid> | --source-kind <k> --source-ref <ref>) [--json]
+ *
+ * The class names are checked by the door against the closed list (`lib/edward-predictor/classes.ts`), not copied here.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const VERBS = ["show", "promote", "demote", "predict", "answer"];
+const SOURCE_KIND = /^[a-z][a-z0-9_]{0,31}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function parseBrainLadderArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--home", "--dashboard-url", "--json", "--anyway", "--note", "--context", "--asker", "--source-kind", "--source-ref", "--prediction"],
+        valueFlags: ["--home", "--dashboard-url", "--note", "--context", "--asker", "--source-kind", "--source-ref", "--prediction"],
+    });
+    const [ladderWord, verb, ...rest] = values.positionals;
+    if (ladderWord !== "ladder" || !VERBS.includes(verb ?? "")) {
+        throw new Error(`brain ladder takes one verb: ${VERBS.join(", ")}. Example: \`cockpit brain ladder show\`.`);
+    }
+    const shape = { verb: verb };
+    const flag = (name) => optionalNonEmpty(values.flags.get(name))?.trim();
+    const note = flag("--note");
+    if (note && note.length > 300)
+        throw new Error("--note is at most 300 characters.");
+    const sourceKind = flag("--source-kind");
+    if (sourceKind && !SOURCE_KIND.test(sourceKind))
+        throw new Error("--source-kind wants a lowercase label like approval_card.");
+    const prediction = flag("--prediction");
+    if (prediction && !UUID.test(prediction))
+        throw new Error("--prediction wants a prediction id (a UUID).");
+    const only = (allowed) => {
+        for (const name of ["--anyway", "--note", "--context", "--asker", "--source-kind", "--source-ref", "--prediction"]) {
+            const given = values.booleans.has(name) || values.flags.has(name);
+            if (given && !allowed.includes(name))
+                throw new Error(`${name} does not belong to brain ladder ${shape.verb}.`);
+        }
+    };
+    switch (shape.verb) {
+        case "show":
+            if (rest.length)
+                throw new Error("brain ladder show takes no arguments.");
+            only([]);
+            break;
+        case "promote":
+        case "demote":
+            if (rest.length !== 1)
+                throw new Error(`brain ladder ${shape.verb} takes one class name. Example: \`cockpit brain ladder ${shape.verb} merge\`.`);
+            only(shape.verb === "promote" ? ["--anyway", "--note"] : ["--note"]);
+            shape.className = rest[0];
+            if (values.booleans.has("--anyway"))
+                shape.anyway = true;
+            if (note)
+                shape.note = note;
+            break;
+        case "predict":
+            if (rest.length !== 1)
+                throw new Error('brain ladder predict takes the question in quotes. Example: `cockpit brain ladder predict "Merge #1820 now?"`.');
+            only(["--context", "--asker", "--source-kind", "--source-ref"]);
+            shape.text = rest[0];
+            if (flag("--context"))
+                shape.context = flag("--context");
+            if (flag("--asker"))
+                shape.asker = flag("--asker");
+            if (sourceKind)
+                shape.sourceKind = sourceKind;
+            if (flag("--source-ref"))
+                shape.sourceRef = flag("--source-ref");
+            break;
+        case "answer":
+            if (rest.length !== 1)
+                throw new Error('brain ladder answer takes what he answered, in quotes. Example: `cockpit brain ladder answer "Yes, merge it" --prediction <id>`.');
+            only(["--prediction", "--source-kind", "--source-ref"]);
+            shape.text = rest[0];
+            if (prediction)
+                shape.predictionId = prediction;
+            if (sourceKind)
+                shape.sourceKind = sourceKind;
+            if (flag("--source-ref"))
+                shape.sourceRef = flag("--source-ref");
+            if (!shape.predictionId && !(shape.sourceKind && shape.sourceRef))
+                throw new Error("brain ladder answer needs --prediction <id>, or --source-kind and --source-ref.");
+            break;
+    }
+    return { ladder: shape, dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")), homeDir: flag("--home"), json: values.booleans.has("--json") };
+}

package/dist/commands/local-args-tower-brain.js

@@ -9,16 +9,26 @@
  */
 import { LOG_PROJECT_PATTERN } from "@bli-cockpit/telemetry-core/log-digest";
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+import { parseBrainLadderArgs } from "./local-args-tower-brain-ladder.js";
 /** The statuses the queue's door accepts for `--show`; the migration's CHECK constraint is the other copy. */
 export const BRAIN_SHOW_STATUSES = ["open", "running", "needs_human", "fixed", "not_actionable", "cleared"];
 export function parseBrainArgs(args) {
+    // BLI-19250: `brain ladder ...` is Edward's call ladder; it has its own verbs and flags.
+    // The census spells these `brain ladder-show` (one action word), so that spelling is accepted beside `brain ladder show`.
+    const first = args.find((arg) => !arg.startsWith("--"));
+    if (first === "ladder" || /^ladder-[a-z]+$/.test(first ?? "")) {
+        const hyphen = first !== "ladder";
+        const split = hyphen ? args.flatMap((arg) => (arg === first ? ["ladder", first.slice("ladder-".length)] : [arg])) : args;
+        const parsed = parseBrainLadderArgs(split);
+        return { kind: "brain", action: `ladder-${parsed.ladder.verb}`, ladder: parsed.ladder, dashboardUrl: parsed.dashboardUrl, homeDir: parsed.homeDir, json: parsed.json };
+    }
     const values = parseNamedArgs(args, {
         allowedFlags: ["--project", "--show", "--home", "--dashboard-url", "--json", "--all-needs-human", "--reason"],
         valueFlags: ["--project", "--show", "--home", "--dashboard-url", "--reason"],
     });
     const action = values.positionals[0];
     if ((action !== "status" && action !== "retry") || (action === "status" && values.positionals.length > 1)) {
-        throw new Error("brain takes one verb: `status` or `retry`. Example: `cockpit brain status` or `cockpit brain status --project pearl-portal`.");
+        throw new Error("brain takes one verb: `status`, `retry` or `ladder`. Example: `cockpit brain status` or `cockpit brain status --project pearl-portal`.");
     }
     const project = optionalNonEmpty(values.flags.get("--project"));
     if (project && !LOG_PROJECT_PATTERN.test(project))

package/dist/commands/local-args-tower-cal.js

@@ -20,6 +20,7 @@
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 const CAL_ACTIONS = new Set([
+    "conflicts", "calendar-change",
     "today",
     "week",
     "next",
@@ -35,7 +36,7 @@ const CAL_ACTIONS = new Set([
     "delete",
 ]);
 /** Every verb that names ONE thing first — a calendar id, or (delete) an event id. */
-const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set(["sync", "detach", "share", "delete", "change", "cancel"]);
+const CAL_ACTIONS_NEEDING_A_SUBJECT = new Set(["calendar-change", "sync", "detach", "share", "delete", "change", "cancel"]);
 /** `sync-status [<calendar id>]` — every calendar, or one's. Ticket 10730. */
 const CAL_ACTIONS_WITH_OPTIONAL_SUBJECT = new Set(["sync-status"]);
 export function parseCalArgs(args) {
@@ -43,6 +44,7 @@ export function parseCalArgs(args) {
         allowedFlags: [
             "--home",
             "--dashboard-url",
+            "--color",
             "--calendar",
             "--account",
             "--tz",
@@ -69,6 +71,7 @@ export function parseCalArgs(args) {
         valueFlags: [
             "--home",
             "--dashboard-url",
+            "--color",
             "--calendar",
             "--account",
             "--tz",
@@ -100,7 +103,7 @@ function readCalAction(values) {
     const first = values.positionals[0];
     const action = (first === undefined ? "today" : first);
     if (!CAL_ACTIONS.has(action)) {
-        throw new Error(`Unknown cal command: ${first}. Try today, week, next, find, calendars, add-ical, create, share, detach, sync, sync-status, or delete.`);
+        throw new Error(`Unknown cal command: ${first}. Try today, week, conflicts, calendar-change, next, find, calendars, add-ical, create, share, detach, sync, sync-status, or delete.`);
     }
     return { action, rest: values.positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -170,6 +173,7 @@ function readCalOffset(values) {
 function buildCalCommand(values, action, subject, query, title, startsAt, endsAt, offset, limit) {
     return {
         kind: "cal",
+        color: optionalNonEmpty(values.flags.get("--color")),
         action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),

package/dist/commands/local-args-tower-docs-msg.js

@@ -7,13 +7,14 @@
  * added both without stretching either existing family's own doc comment.
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status"]);
+import { parseDocsExportFlags } from "./local-args-docs-export.js";
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export"]);
 // BLI-10450: `read` moved to its own branch in `parseDocsDocumentReference` —
 // it takes SEVERAL references now, so it no longer shares the "exactly one"
 // rule `update`/`link` still enforce. BLI‑10555: `delete` takes several too
 // (the same door, called once per ref), so it joined `read`'s branch rather
 // than this set.
-const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export"]);
 export function parseDocsArgs(args) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
@@ -33,6 +34,8 @@ export function parseDocsArgs(args) {
             "--bodies",
             "--section",
             "--offset",
+            "--format",
+            "--out",
             "--json",
         ],
         valueFlags: [
@@ -46,6 +49,8 @@ export function parseDocsArgs(args) {
             "--limit",
             "--section",
             "--offset",
+            "--format",
+            "--out",
         ],
     });
     const { action, rest } = parseDocsAction(values.positionals);
@@ -111,7 +116,7 @@ function parseDocsAction(positionals) {
     const first = positionals[0];
     const action = (first === undefined ? "list" : first);
     if (!DOCS_ACTIONS.has(action)) {
-        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, or sync-status.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, or export.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -234,149 +239,8 @@ function buildDocsCommand(values, action, docRef, docRefs, visibility, clearPare
         ...(offset === undefined ? {} : { offset }),
         ...(link.notionPage ? { notionPage: link.notionPage } : {}),
         ...(link.clearLink ? { clearLink: true } : {}),
+        ...parseDocsExportFlags(action, values),
         json: values.booleans.has("--json"),
     };
 }
-const MSG_ACTIONS = new Set(["channels", "read", "send", "thread", "create", "dm"]);
-const MSG_ACTIONS_NEEDING_A_CHANNEL = new Set(["read", "send"]);
-/**
- * `--members a@x.test,b@y.test` — addresses only, split on commas, never
- * fuzzy (BLI-3749). The door resolves each one exactly, so a typo comes back
- * as `person_not_found` naming the address rather than as a stranger added
- * to a private channel.
- */
-function parseMemberEmails(raw) {
-    const value = optionalNonEmpty(raw);
-    if (!value)
-        return undefined;
-    const emails = value
-        .split(",")
-        .map((part) => part.trim())
-        .filter((part) => part !== "");
-    if (emails.length === 0)
-        throw new Error("msg create --members needs at least one email address.");
-    const notAnAddress = emails.find((email) => !email.includes("@"));
-    if (notAnAddress) {
-        throw new Error(`msg create --members takes email addresses; "${notAnAddress}" is not one.`);
-    }
-    return emails;
-}
-export function parseMsgArgs(args) {
-    const values = parseNamedArgs(args, {
-        allowedFlags: [
-            "--home",
-            "--dashboard-url",
-            "--channel",
-            "--thread",
-            "--limit",
-            "--private",
-            "--members",
-            "--description",
-            "--json",
-        ],
-        valueFlags: ["--home", "--dashboard-url", "--channel", "--thread", "--limit", "--members", "--description"],
-    });
-    const { action, rest } = parseMsgAction(values.positionals);
-    const { channelName, dmEmail } = parseMsgCreateTarget(action, rest);
-    const { isPrivate, memberEmails, description } = parseMsgCreateFlags(action, values);
-    const { channelRef, threadId, limit } = parseMsgReadTarget(action, rest, values);
-    return buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit);
-}
-function parseMsgAction(positionals) {
-    const first = positionals[0];
-    const action = (first === undefined ? "channels" : first);
-    if (!MSG_ACTIONS.has(action)) {
-        throw new Error(`Unknown msg command: ${first}. Try channels, read, send, thread, create, or dm.`);
-    }
-    return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
-}
-function parseMsgCreateTarget(action, rest) {
-    let channelName;
-    let dmEmail;
-    if (action === "create") {
-        channelName = optionalNonEmpty(rest[0]);
-        if (!channelName)
-            throw new Error("msg create needs a channel name, e.g. `cockpit msg create general`.");
-        if (rest.length > 1)
-            throw new Error(`msg create takes one channel name, not ${rest.length}.`);
-        // `#general` is how a person says it and how `read`/`send` accept it, so
-        // the leading # is dropped here rather than becoming part of the name.
-        if (channelName.startsWith("#"))
-            channelName = channelName.slice(1);
-        if (channelName === "")
-            throw new Error("msg create needs a channel name, e.g. `cockpit msg create general`.");
-    }
-    else if (action === "dm") {
-        dmEmail = optionalNonEmpty(rest[0]);
-        if (!dmEmail)
-            throw new Error("msg dm needs the person's email address, e.g. `cockpit msg dm ada@example.com`.");
-        if (rest.length > 1)
-            throw new Error(`msg dm takes one email address, not ${rest.length}.`);
-        if (!dmEmail.includes("@"))
-            throw new Error(`msg dm takes an email address; "${dmEmail}" is not one.`);
-    }
-    return { channelName, dmEmail };
-}
-function parseMsgCreateFlags(action, values) {
-    const isPrivate = values.booleans.has("--private");
-    if (isPrivate && action !== "create") {
-        throw new Error("--private belongs to `cockpit msg create`.");
-    }
-    const memberEmails = parseMemberEmails(values.flags.get("--members"));
-    if (memberEmails && action !== "create") {
-        throw new Error("--members belongs to `cockpit msg create`.");
-    }
-    const description = optionalNonEmpty(values.flags.get("--description"));
-    if (description && action !== "create") {
-        throw new Error("--description belongs to `cockpit msg create`.");
-    }
-    return { isPrivate, memberEmails, description };
-}
-function parseMsgReadTarget(action, rest, values) {
-    let channelRef;
-    if (MSG_ACTIONS_NEEDING_A_CHANNEL.has(action)) {
-        channelRef = optionalNonEmpty(rest[0]);
-        if (!channelRef)
-            throw new Error(`msg ${action} needs a channel id or name.`);
-        if (rest.length > 1)
-            throw new Error(`msg ${action} takes one channel, not ${rest.length}.`);
-    }
-    else if (action === "thread") {
-        // `thread <id> --channel <channel>` — the channel is a flag here because
-        // the positional names the THREAD, not the channel (`--channel` below).
-        if (rest.length > 1)
-            throw new Error(`msg thread takes one thread id, not ${rest.length}.`);
-    }
-    else if (action !== "create" && action !== "dm" && rest.length > 0) {
-        throw new Error(`msg ${action} does not take "${rest[0]}".`);
-    }
-    const threadFlag = optionalNonEmpty(values.flags.get("--thread"));
-    const threadId = action === "thread" ? optionalNonEmpty(rest[0]) : threadFlag;
-    if (action === "thread" && !threadId)
-        throw new Error("msg thread needs a thread id.");
-    const channelFlag = optionalNonEmpty(values.flags.get("--channel"));
-    if (action === "thread")
-        channelRef = channelFlag;
-    const limit = optionalPositiveInteger(values.flags.get("--limit"), "--limit");
-    if (limit !== undefined && action !== "read" && action !== "thread") {
-        throw new Error("--limit belongs to `cockpit msg read` or `cockpit msg thread`.");
-    }
-    return { channelRef, threadId, limit };
-}
-function buildMsgCommand(values, action, channelRef, channelName, dmEmail, memberEmails, description, isPrivate, threadId, limit) {
-    return {
-        kind: "msg",
-        action,
-        homeDir: optionalNonEmpty(values.flags.get("--home")),
-        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
-        ...(channelRef ? { channelRef } : {}),
-        ...(channelName ? { channelName } : {}),
-        ...(dmEmail ? { dmEmail } : {}),
-        ...(memberEmails ? { memberEmails } : {}),
-        ...(description ? { description } : {}),
-        isPrivate,
-        ...(threadId ? { threadId } : {}),
-        ...(limit === undefined ? {} : { limit }),
-        json: values.booleans.has("--json"),
-    };
-}
+export { parseMsgArgs } from "./local-args-tower-msg.js";

package/dist/commands/local-args-tower-drills.js

@@ -0,0 +1,87 @@
+/**
+ * `cockpit drills` argument parsing (BLI-19259).
+ *
+ *   cockpit drills [list]                                     your open drill, queue, bosses, streak, history
+ *   cockpit drills start                                      open the next drill (answer first: the cause is not shown)
+ *   cockpit drills answer --confidence <1-5> [--text <words>] [--attempt <id>]    (the answer on stdin when --text is absent)
+ *   cockpit drills theme                                      your theme and the choices
+ *   cockpit drills theme set <theme> [--play <t>] [--watch <t>] [--train <t>]
+ *   cockpit drills review                                     your own week: hits, wins, highs, lows, plateaus, what to practise
+ *
+ * Every verb is one `/api/drills` door on this machine's device token, the same doors the web page, the MCP twins and JARVIS use.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ONE_VERB = "drills takes one verb: list, start, answer, theme, theme set or review. Example: `cockpit drills` or `cockpit drills start`.";
+const FLAGS_BY_ACTION = {
+    list: [],
+    start: [],
+    answer: ["--confidence", "--text", "--attempt"],
+    theme: [],
+    "theme-set": ["--play", "--watch", "--train"],
+    review: [],
+};
+const OWN_FLAGS = ["--confidence", "--text", "--attempt", "--play", "--watch", "--train"];
+const COMMON_FLAGS = ["--home", "--dashboard-url", "--json"];
+export function parseDrillsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [...OWN_FLAGS, ...COMMON_FLAGS],
+        valueFlags: [...OWN_FLAGS, "--home", "--dashboard-url"],
+    });
+    const first = values.positionals[0];
+    let action;
+    let consumed = 1;
+    if (first === undefined) {
+        action = "list";
+        consumed = 0;
+    }
+    else if (first === "theme" && values.positionals[1] === "set") {
+        action = "theme-set";
+        consumed = 2;
+    }
+    else if (first === "list" || first === "start" || first === "answer" || first === "theme" || first === "review") {
+        action = first;
+    }
+    else
+        throw new Error(ONE_VERB);
+    const given = [...values.flags.keys()].filter((flag) => OWN_FLAGS.includes(flag));
+    const owned = FLAGS_BY_ACTION[action];
+    const stray = given.find((flag) => !owned.includes(flag));
+    if (stray)
+        throw new Error(`${stray} does not belong to \`cockpit drills ${action === "theme-set" ? "theme set" : action}\`.`);
+    const rest = values.positionals.slice(consumed);
+    let theme;
+    if (action === "theme-set") {
+        theme = rest.join(" ").trim();
+        if (!theme)
+            throw new Error("`cockpit drills theme set` takes a theme: video-game, boxing, muay-thai, crime-drama, anime, sports, or your own words.");
+    }
+    else if (rest.length > 0)
+        throw new Error(`\`cockpit drills ${action}\` takes no positional arguments.`);
+    let confidence;
+    const rawConfidence = values.flags.get("--confidence");
+    if (action === "answer") {
+        if (rawConfidence === undefined)
+            throw new Error("`cockpit drills answer` needs --confidence 1 to 5: how sure you are, from a guess to certain.");
+        confidence = Number(rawConfidence);
+        if (!Number.isInteger(confidence) || confidence < 1 || confidence > 5)
+            throw new Error("--confidence wants a whole number from 1 (a guess) to 5 (certain).");
+    }
+    const attempt = optionalNonEmpty(values.flags.get("--attempt"));
+    if (attempt && !ID.test(attempt))
+        throw new Error("--attempt looks like 8f14e45f-ceea-467a-9575-1d3a4e7b2c10 (`cockpit drills` shows the open one).");
+    return {
+        kind: "drills",
+        action,
+        ...(attempt ? { attemptId: attempt } : {}),
+        ...(confidence !== undefined ? { confidence } : {}),
+        ...(optionalNonEmpty(values.flags.get("--text")) ? { text: optionalNonEmpty(values.flags.get("--text")) } : {}),
+        ...(theme ? { theme } : {}),
+        ...(optionalNonEmpty(values.flags.get("--play")) ? { play: optionalNonEmpty(values.flags.get("--play")) } : {}),
+        ...(optionalNonEmpty(values.flags.get("--watch")) ? { watch: optionalNonEmpty(values.flags.get("--watch")) } : {}),
+        ...(optionalNonEmpty(values.flags.get("--train")) ? { train: optionalNonEmpty(values.flags.get("--train")) } : {}),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}

package/dist/commands/local-args-tower-hits.js

@@ -0,0 +1,93 @@
+/**
+ * `cockpit hits` argument parsing (BLI-19257).
+ *
+ *   cockpit hits [--mine | --person <email|github-login|name> | --agent | --project <id>] [--days <n>] [--patterns] [--learning] [--top <n>] [--json]
+ *   cockpit hits coach [--json]
+ *   cockpit hits timeline [--weeks <n>] [--json]
+ *   cockpit hits approve --scope <team|agents|project:<id>> [--version <n>] [--json]
+ *
+ * The hit ledger over `GET /api/hits`, `GET /api/hits/coach` and `POST /api/hits/patterns/approve` with this machine's
+ * device token. Who may see what is the database's rule and the door's refusal, not this parser's.
+ */
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+const PROJECT_ID = /^[a-z0-9][a-z0-9-]{0,40}$/;
+const SCOPE = /^(?:team|agents|project:[a-z0-9][a-z0-9-]{0,40})$/;
+const READ_ONLY_FLAGS = ["--mine", "--person", "--agent", "--project", "--days", "--top", "--patterns", "--learning"];
+export function parseHitsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: [...READ_ONLY_FLAGS, "--scope", "--version", "--weeks", "--home", "--dashboard-url", "--json"],
+        valueFlags: ["--person", "--project", "--days", "--top", "--scope", "--version", "--weeks", "--home", "--dashboard-url"],
+    });
+    const verb = values.positionals[0];
+    if (values.positionals.length > 1 || (verb !== undefined && verb !== "read" && verb !== "coach" && verb !== "approve" && verb !== "timeline")) {
+        throw new Error("hits takes no verb (read the ledger), `timeline`, `coach` or `approve`. Example: `cockpit hits --mine` or `cockpit hits timeline`.");
+    }
+    const action = verb === "coach" || verb === "approve" || verb === "timeline" ? verb : "read";
+    const given = (flag) => values.flags.has(flag) || values.booleans.has(flag);
+    const common = {
+        kind: "hits",
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+    if (action !== "read") {
+        const stray = READ_ONLY_FLAGS.find(given);
+        if (stray)
+            throw new Error(`${stray} belongs to \`cockpit hits\` (reading the ledger), not to hits ${action}.`);
+    }
+    if (given("--weeks") && action !== "timeline")
+        throw new Error("--weeks belongs to hits timeline.");
+    if (action === "timeline") {
+        if (given("--scope") || given("--version"))
+            throw new Error("--scope and --version belong to hits approve.");
+        const weeks = optionalPositiveInteger(values.flags.get("--weeks"), "--weeks");
+        if (weeks !== undefined && weeks > 26)
+            throw new Error("--weeks must be 26 or fewer.");
+        return { ...common, action, ...(weeks !== undefined ? { weeks } : {}) };
+    }
+    if (action === "coach") {
+        if (given("--scope") || given("--version"))
+            throw new Error("--scope and --version belong to hits approve.");
+        return { ...common, action };
+    }
+    if (action === "approve") {
+        const scope = optionalNonEmpty(values.flags.get("--scope"));
+        if (!scope || !SCOPE.test(scope))
+            throw new Error("hits approve wants --scope team, agents or project:<id> (for example project:pearl-portal).");
+        return { ...common, action, scope, ...versionOf(values.flags.get("--version")) };
+    }
+    if (given("--scope") || given("--version"))
+        throw new Error("--scope and --version belong to hits approve.");
+    const whoFlags = ["--mine", "--person", "--agent", "--project"].filter(given);
+    if (whoFlags.length > 1)
+        throw new Error(`Pick one of --mine, --person, --agent or --project (got ${whoFlags.join(" and ")}).`);
+    const person = optionalNonEmpty(values.flags.get("--person"))?.trim();
+    const project = optionalNonEmpty(values.flags.get("--project"));
+    if (project && !PROJECT_ID.test(project))
+        throw new Error("--project wants a registry project id like pearl-portal.");
+    const days = optionalPositiveInteger(values.flags.get("--days"), "--days");
+    if (days !== undefined && days > 365)
+        throw new Error("--days must be 365 or fewer.");
+    const top = optionalPositiveInteger(values.flags.get("--top"), "--top");
+    if (top !== undefined && top > 50)
+        throw new Error("--top must be 50 or fewer.");
+    const learning = values.booleans.has("--learning");
+    const who = values.booleans.has("--mine") ? "mine" : person ? "person" : values.booleans.has("--agent") ? "agents" : project ? "project" : undefined;
+    if (learning && who !== "mine" && who !== "person")
+        throw new Error("--learning is read for one person: use --mine or --person <name>.");
+    return {
+        ...common,
+        action,
+        ...(who ? { who } : {}),
+        ...(person ? { person } : {}),
+        ...(project ? { project } : {}),
+        ...(days !== undefined ? { days } : {}),
+        ...(top !== undefined ? { top } : {}),
+        ...(values.booleans.has("--patterns") ? { patterns: true } : {}),
+        ...(learning ? { learning: true } : {}),
+    };
+}
+function versionOf(raw) {
+    const version = optionalPositiveInteger(raw, "--version");
+    return version === undefined ? {} : { version };
+}

package/dist/commands/local-args-tower-intentions.js

@@ -0,0 +1,70 @@
+/**
+ * `cockpit intentions` argument parsing (BLI-19248).
+ *
+ *   cockpit intentions [list] [--status open|overdue|done|dropped|all] [--project <name>] [--limit <n>] [--json]
+ *   cockpit intentions show <id> [--json]
+ *   cockpit intentions done <id> --evidence "<what settled it>" [--by person|agent] [--json]
+ *   cockpit intentions drop <id> --evidence "<why>" [--by person|agent] [--json]
+ *   cockpit intentions reopen <id> [--json]
+ *
+ * Prospective memory: what a person or an agent said they would do later, tied to a trigger. Reads and writes
+ * `/api/intentions` with this machine's device token.
+ */
+import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+export const INTENTION_LIST_STATUSES = ["open", "overdue", "done", "dropped", "all"];
+const ACTIONS = ["list", "show", "done", "drop", "reopen"];
+export function parseIntentionsArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--status", "--project", "--limit", "--evidence", "--by", "--home", "--dashboard-url", "--json"],
+        valueFlags: ["--status", "--project", "--limit", "--evidence", "--by", "--home", "--dashboard-url"],
+    });
+    const first = values.positionals[0];
+    const action = (first ?? "list");
+    if (!ACTIONS.includes(action)) {
+        throw new Error("intentions takes one verb: list, show, done, drop or reopen. Example: `cockpit intentions list --status overdue`.");
+    }
+    const rest = values.positionals.slice(first ? 1 : 0);
+    const status = optionalNonEmpty(values.flags.get("--status"));
+    const project = optionalNonEmpty(values.flags.get("--project"));
+    const evidence = optionalNonEmpty(values.flags.get("--evidence"))?.trim();
+    const by = optionalNonEmpty(values.flags.get("--by"));
+    const rawLimit = optionalNonEmpty(values.flags.get("--limit"));
+    if (status && !INTENTION_LIST_STATUSES.includes(status))
+        throw new Error(`--status wants one of ${INTENTION_LIST_STATUSES.join(", ")}.`);
+    if (by && by !== "person" && by !== "agent")
+        throw new Error("--by wants person or agent.");
+    const limit = rawLimit ? Number(rawLimit) : undefined;
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 200))
+        throw new Error("--limit wants a whole number from 1 to 200.");
+    if (action === "list") {
+        if (rest.length)
+            throw new Error("intentions list takes no id; use `cockpit intentions show <id>`.");
+        if (evidence || by)
+            throw new Error("--evidence and --by belong to intentions done and drop.");
+    }
+    else {
+        if (rest.length !== 1)
+            throw new Error(`intentions ${action} takes exactly one id (the uuid or the 8-character prefix list prints).`);
+        if (status || project || limit !== undefined)
+            throw new Error("--status, --project and --limit belong to intentions list.");
+        if (action === "done" || action === "drop") {
+            if (!evidence || evidence.length < 3 || evidence.length > 300)
+                throw new Error(`intentions ${action} needs --evidence "<what settled it>" of 3 to 300 characters.`);
+        }
+        else if (evidence || by)
+            throw new Error("--evidence and --by belong to intentions done and drop.");
+    }
+    return {
+        kind: "intentions",
+        action,
+        ...(rest[0] ? { id: rest[0] } : {}),
+        ...(status ? { status } : {}),
+        ...(project ? { project } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(evidence ? { evidence } : {}),
+        ...(by ? { by: by } : {}),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        json: values.booleans.has("--json"),
+    };
+}