@bli-cockpit/cli 0.2.237 → 0.2.239

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

@@ -9,11 +9,56 @@ const NEEDS_ROLE = ['takehome-show', 'takehome-set'];
 export function parseCareersArgs(args) {
     const valueFlags = ['--role', '--min-score', '--since', '--home', '--dashboard-url', '--decision', '--stage', '--subject', '--body-file', '--link', '--pass-score', '--account', '--auto-invite-min-score', '--attention-min-score', '--enabled', '--booking-link', '--grader-model', '--out', '--record-sent-at', '--at', '--followup-enabled', '--followup-after-days', '--takehome-window-hours'];
     const values = parseNamedArgs(args, { allowedFlags: [...valueFlags, '--json', '--now', '--force', '--clear'], valueFlags });
-    const positionals = [...values.positionals];
-    // `takehome show` and `settings set` are two words a person types and one
-    // action everything downstream reads.
-    // A bare `careers takehome` or `careers settings` reads as its `show`, the way
-    // `team device` reads as `team device list`: the noun alone is a question.
+    const { verb, target } = readCareersVerb([...values.positionals]);
+    const rawScore = values.flags.get('--min-score');
+    const minScore = rawScore === undefined ? undefined : Number(rawScore);
+    if (minScore !== undefined && (!Number.isFinite(minScore) || minScore < 0 || minScore > 100))
+        throw new Error('--min-score must be 0 to 100.');
+    const since = optionalNonEmpty(values.flags.get('--since'));
+    if (since && !Number.isFinite(Date.parse(since)))
+        throw new Error('--since must be a date.');
+    const decision = optionalNonEmpty(values.flags.get('--decision'));
+    if (verb === 'decide' && (!decision || !DECISIONS.includes(decision)))
+        throw new Error(`careers decide needs --decision ${DECISIONS.join('|')}.`);
+    const passScore = numberFlag(values.flags.get('--pass-score'), '--pass-score', 0, 10);
+    const autoInviteMinScore = numberFlag(values.flags.get('--auto-invite-min-score'), '--auto-invite-min-score', 0, 100);
+    const attentionMinScore = numberFlag(values.flags.get('--attention-min-score'), '--attention-min-score', 0, 100);
+    const enabledRaw = trueOrFalseFlag(values.flags.get('--enabled'), '--enabled');
+    const recordSentAt = readRecordSentAt(values, verb);
+    const { interviewAt, clear } = readInterviewFlags(values, verb);
+    const followupEnabledRaw = trueOrFalseFlag(values.flags.get('--followup-enabled'), '--followup-enabled');
+    const followupAfterDays = wholeFlag(values.flags.get('--followup-after-days'), '--followup-after-days', 1, 60);
+    const takehomeWindowHours = wholeFlag(values.flags.get('--takehome-window-hours'), '--takehome-window-hours', 1, 720);
+    const { outPath, force } = readResumeFileFlags(values, verb);
+    return {
+        kind: 'careers', action: verb,
+        id: NEEDS_ID.includes(verb) ? target : undefined,
+        takehomeRole: NEEDS_ROLE.includes(verb) ? target : undefined,
+        role: optionalNonEmpty(values.flags.get('--role')), minScore, since: since ? new Date(since).toISOString() : undefined,
+        stage: optionalNonEmpty(values.flags.get('--stage')), decision,
+        subject: optionalNonEmpty(values.flags.get('--subject')), bodyFile: optionalNonEmpty(values.flags.get('--body-file')),
+        link: optionalNonEmpty(values.flags.get('--link')), passScore,
+        inviteAccountId: optionalNonEmpty(values.flags.get('--account')),
+        bookingLink: httpsFlag(values.flags.get('--booking-link')),
+        graderModel: optionalNonEmpty(values.flags.get('--grader-model')),
+        now: values.booleans.has('--now'),
+        outPath, force,
+        interviewAt: interviewAt ? new Date(interviewAt).toISOString() : undefined, clear: clear || undefined,
+        recordSentAt: recordSentAt ? new Date(recordSentAt).toISOString() : undefined,
+        followupEnabled: followupEnabledRaw === undefined ? undefined : followupEnabledRaw === 'true',
+        followupAfterDays, takehomeWindowHours,
+        autoInviteMinScore, attentionMinScore,
+        autoInviteEnabled: enabledRaw === undefined ? undefined : enabledRaw === 'true',
+        homeDir: optionalNonEmpty(values.flags.get('--home')), dashboardUrl: optionalUrl(values.flags.get('--dashboard-url')), json: values.booleans.has('--json'),
+    };
+}
+/**
+ * `takehome show` and `settings set` are two words a person types and one
+ * action everything downstream reads.
+ * A bare `careers takehome` or `careers settings` reads as its `show`, the way
+ * `team device` reads as `team device list`: the noun alone is a question.
+ */
+function readCareersVerb(positionals) {
     const first = positionals[0] ?? 'list';
     const paired = first === 'takehome' || first === 'settings';
     const typed = paired
@@ -32,32 +77,28 @@ export function parseCareersArgs(args) {
         throw new Error(`careers ${verb.replace('-', ' ')} needs a role slug.`);
     if (positionals.length > 0)
         throw new Error('Unexpected careers argument.');
-    const rawScore = values.flags.get('--min-score');
-    const minScore = rawScore === undefined ? undefined : Number(rawScore);
-    if (minScore !== undefined && (!Number.isFinite(minScore) || minScore < 0 || minScore > 100))
-        throw new Error('--min-score must be 0 to 100.');
-    const since = optionalNonEmpty(values.flags.get('--since'));
-    if (since && !Number.isFinite(Date.parse(since)))
-        throw new Error('--since must be a date.');
-    const decision = optionalNonEmpty(values.flags.get('--decision'));
-    if (verb === 'decide' && (!decision || !DECISIONS.includes(decision)))
-        throw new Error(`careers decide needs --decision ${DECISIONS.join('|')}.`);
-    const passScore = numberFlag(values.flags.get('--pass-score'), '--pass-score', 0, 10);
-    const autoInviteMinScore = numberFlag(values.flags.get('--auto-invite-min-score'), '--auto-invite-min-score', 0, 100);
-    const attentionMinScore = numberFlag(values.flags.get('--attention-min-score'), '--attention-min-score', 0, 100);
-    const enabledRaw = optionalNonEmpty(values.flags.get('--enabled'));
-    if (enabledRaw !== undefined && enabledRaw !== 'true' && enabledRaw !== 'false')
-        throw new Error('--enabled must be true or false.');
-    // BLI-12183: the second-chance follow-up. `--record-sent-at` records one sent
-    // outside Tower and sends nothing; the three settings flags are whole numbers
-    // and a boolean, refused here as well as on the door.
+    return { typed, verb, target };
+}
+function trueOrFalseFlag(raw, flag) {
+    const value = optionalNonEmpty(raw);
+    if (value !== undefined && value !== 'true' && value !== 'false')
+        throw new Error(`${flag} must be true or false.`);
+    return value;
+}
+// BLI-12183: the second-chance follow-up. `--record-sent-at` records one sent
+// outside Tower and sends nothing; the three settings flags are whole numbers
+// and a boolean, refused here as well as on the door.
+function readRecordSentAt(values, verb) {
     const recordSentAt = optionalNonEmpty(values.flags.get('--record-sent-at'));
     if (recordSentAt !== undefined && verb !== 'followup')
         throw new Error('--record-sent-at belongs to `cockpit careers followup <id>`.');
     if (recordSentAt !== undefined && !Number.isFinite(Date.parse(recordSentAt)))
         throw new Error('--record-sent-at must be an ISO date-time, e.g. 2026-10-03T08:00:00Z.');
-    // BLI-12198: an interview Edward booked himself. Exactly one of `--at <iso>`
-    // (book or reschedule) or `--clear`, refused here as well as on the door.
+    return recordSentAt;
+}
+// BLI-12198: an interview Edward booked himself. Exactly one of `--at <iso>`
+// (book or reschedule) or `--clear`, refused here as well as on the door.
+function readInterviewFlags(values, verb) {
     const interviewAt = optionalNonEmpty(values.flags.get('--at'));
     const clear = values.booleans.has('--clear');
     if (interviewAt !== undefined && verb !== 'interview')
@@ -71,13 +112,11 @@ export function parseCareersArgs(args) {
             throw new Error('--at must be an ISO date-time with an offset, e.g. 2026-10-05T10:00:00-07:00.');
         }
     }
-    const followupEnabledRaw = optionalNonEmpty(values.flags.get('--followup-enabled'));
-    if (followupEnabledRaw !== undefined && followupEnabledRaw !== 'true' && followupEnabledRaw !== 'false')
-        throw new Error('--followup-enabled must be true or false.');
-    const followupAfterDays = wholeFlag(values.flags.get('--followup-after-days'), '--followup-after-days', 1, 60);
-    const takehomeWindowHours = wholeFlag(values.flags.get('--takehome-window-hours'), '--takehome-window-hours', 1, 720);
-    // The resume is the only thing this noun writes to disk, so both file flags
-    // belong to it alone and say so rather than being accepted and ignored.
+    return { interviewAt, clear };
+}
+// The resume is the only thing this noun writes to disk, so both file flags
+// belong to it alone and say so rather than being accepted and ignored.
+function readResumeFileFlags(values, verb) {
     const outPath = optionalNonEmpty(values.flags.get('--out'));
     const force = values.booleans.has('--force');
     if (outPath !== undefined && verb !== 'resume')
@@ -86,27 +125,7 @@ export function parseCareersArgs(args) {
         throw new Error('--force belongs to `cockpit careers resume <id> --out <path>`.');
     if (force && outPath === undefined)
         throw new Error('--force only means something beside --out <path>: with no file to write there is nothing to overwrite.');
-    return {
-        kind: 'careers', action: verb,
-        id: NEEDS_ID.includes(verb) ? target : undefined,
-        takehomeRole: NEEDS_ROLE.includes(verb) ? target : undefined,
-        role: optionalNonEmpty(values.flags.get('--role')), minScore, since: since ? new Date(since).toISOString() : undefined,
-        stage: optionalNonEmpty(values.flags.get('--stage')), decision,
-        subject: optionalNonEmpty(values.flags.get('--subject')), bodyFile: optionalNonEmpty(values.flags.get('--body-file')),
-        link: optionalNonEmpty(values.flags.get('--link')), passScore,
-        inviteAccountId: optionalNonEmpty(values.flags.get('--account')),
-        bookingLink: httpsFlag(values.flags.get('--booking-link')),
-        graderModel: optionalNonEmpty(values.flags.get('--grader-model')),
-        now: values.booleans.has('--now'),
-        outPath, force,
-        interviewAt: interviewAt ? new Date(interviewAt).toISOString() : undefined, clear: clear || undefined,
-        recordSentAt: recordSentAt ? new Date(recordSentAt).toISOString() : undefined,
-        followupEnabled: followupEnabledRaw === undefined ? undefined : followupEnabledRaw === 'true',
-        followupAfterDays, takehomeWindowHours,
-        autoInviteMinScore, attentionMinScore,
-        autoInviteEnabled: enabledRaw === undefined ? undefined : enabledRaw === 'true',
-        homeDir: optionalNonEmpty(values.flags.get('--home')), dashboardUrl: optionalUrl(values.flags.get('--dashboard-url')), json: values.booleans.has('--json'),
-    };
+    return { outPath, force };
 }
 /**
  * BLI-4461: a booking link goes into an email a stranger clicks, so the

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

@@ -8,63 +8,70 @@
  */
 import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs, } from "./local-arg-values.js";
 import { parseDocsExportFlags } from "./local-args-docs-export.js";
-const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export"]);
+const DOCS_ACTIONS = new Set(["list", "tree", "read", "create", "update", "delete", "link", "sync-status", "export", "mutation-status"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 // 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", "export"]);
+const DOCS_ACTIONS_NEEDING_A_DOC = new Set(["update", "link", "export", "mutation-status"]);
+const DOCS_ALLOWED_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--title",
+    "--parent",
+    "--clear-parent",
+    "--allow-empty",
+    "--expected-revision",
+    "--request-id",
+    "--visibility",
+    "--file",
+    "--body-stdin",
+    "--query",
+    "--word",
+    "--limit",
+    "--clear",
+    "--bodies",
+    "--section",
+    "--offset",
+    "--format",
+    "--out",
+    "--json",
+];
+const DOCS_VALUE_FLAGS = [
+    "--home",
+    "--dashboard-url",
+    "--title",
+    "--parent",
+    "--expected-revision",
+    "--request-id",
+    "--visibility",
+    "--file",
+    "--query",
+    "--limit",
+    "--section",
+    "--offset",
+    "--format",
+    "--out",
+];
 export function parseDocsArgs(args) {
-    const values = parseNamedArgs(args, {
-        allowedFlags: [
-            "--home",
-            "--dashboard-url",
-            "--title",
-            "--parent",
-            "--clear-parent",
-            "--allow-empty",
-            "--visibility",
-            "--file",
-            "--body-stdin",
-            "--query",
-            "--word",
-            "--limit",
-            "--clear",
-            "--bodies",
-            "--section",
-            "--offset",
-            "--format",
-            "--out",
-            "--json",
-        ],
-        valueFlags: [
-            "--home",
-            "--dashboard-url",
-            "--title",
-            "--parent",
-            "--visibility",
-            "--file",
-            "--query",
-            "--limit",
-            "--section",
-            "--offset",
-            "--format",
-            "--out",
-        ],
-    });
+    const values = parseNamedArgs(args, { allowedFlags: DOCS_ALLOWED_FLAGS, valueFlags: DOCS_VALUE_FLAGS });
     const { action, rest } = parseDocsAction(values.positionals);
     const link = parseDocsLink(action, rest, values.booleans.has("--clear"));
     const { docRef, docRefs } = parseDocsDocumentReference(action, link.rest);
-    const { visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset } = parseDocsFlags(action, values);
+    const { visibility, clearParent, parentId, allowEmpty, title, requestId, expectedRevision, query, wholeWord, limit, bodies, section, offset } = parseDocsFlags(action, values);
     if (action === "read")
         validateDocsReadTargets(docRefs, parentId, bodies);
+    if (action === "mutation-status" && !UUID_PATTERN.test(docRef ?? "")) {
+        throw new Error("docs mutation-status needs a request UUID (the --request-id you sent, or the one `docs update` printed).");
+    }
     // BLI‑10555: `delete` needs no `--parent`/`--bodies` shape, only at least
     // one reference — `read`'s emptier validation does not apply.
     if (action === "delete" && (!docRefs || docRefs.length === 0)) {
         throw new Error("docs delete needs one or more document ids/slugs.");
     }
-    return buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link);
+    return buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link, { requestId, expectedRevision });
 }
 /**
  * BLI-10450: `read` takes either several document references OR
@@ -116,7 +123,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, sync-status, or export.`);
+        throw new Error(`Unknown docs command: ${first}. Try list, tree, read, create, update, delete, link, sync-status, export, or mutation-status.`);
     }
     return { action, rest: positionals.slice(first === undefined ? 0 : 1) };
 }
@@ -150,6 +157,10 @@ function parseDocsDocumentReference(action, rest) {
     return { docRef: undefined, docRefs: undefined };
 }
 function parseDocsFlags(action, values) {
+    return { ...parseDocsWriteFlags(action, values), ...parseDocsReadFlags(action, values) };
+}
+/** The flags that decide where a document lives and what it is called. */
+function parseDocsWriteFlags(action, values) {
     const visibility = optionalNonEmpty(values.flags.get("--visibility"));
     if (visibility && visibility !== "org" && visibility !== "private") {
         throw new Error('docs --visibility must be "org" or "private".');
@@ -170,10 +181,22 @@ function parseDocsFlags(action, values) {
     if (allowEmpty && action !== "update") {
         throw new Error("--allow-empty belongs to `cockpit docs update`.");
     }
+    // BLI-21298: the write-safety pair belongs to `update`, like the other save-shaping flags.
+    if ((values.flags.has("--request-id") || values.flags.has("--expected-revision")) && action !== "update") {
+        throw new Error("--request-id and --expected-revision belong to `cockpit docs update`.");
+    }
+    const requestId = optionalNonEmpty(values.flags.get("--request-id"));
+    if (requestId && !UUID_PATTERN.test(requestId))
+        throw new Error("--request-id must be a UUID.");
+    const expectedRevision = optionalPositiveInteger(values.flags.get("--expected-revision"), "--expected-revision");
     const title = optionalNonEmpty(values.flags.get("--title"));
     if (action === "create" && !title) {
         throw new Error("docs create needs --title.");
     }
+    return { visibility, clearParent, parentId, allowEmpty, title, requestId, expectedRevision };
+}
+/** The flags that narrow or slice what a list or read returns. */
+function parseDocsReadFlags(action, values) {
     // BLI-3737: narrowing belongs to `list` only. `--parent` keeps its create/
     // update meaning elsewhere (which parent to file the document under); on
     // `list` the same word names which parent to list UNDER, plus the literal
@@ -205,18 +228,21 @@ function parseDocsFlags(action, values) {
     const section = optionalNonEmpty(values.flags.get("--section"));
     if (section && action !== "read")
         throw new Error("--section belongs to `cockpit docs read`.");
-    const offsetRaw = optionalNonEmpty(values.flags.get("--offset"));
-    let offset;
-    if (offsetRaw !== undefined) {
-        offset = Number(offsetRaw);
-        if (!Number.isInteger(offset) || offset < 0)
-            throw new Error("--offset must be a whole number 0 or greater.");
-    }
+    const offset = parseDocsOffset(values.flags.get("--offset"));
     if (offset !== undefined && action !== "read")
         throw new Error("--offset belongs to `cockpit docs read`.");
-    return { visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset };
+    return { query, wholeWord, limit, bodies, section, offset };
+}
+function parseDocsOffset(raw) {
+    const offsetRaw = optionalNonEmpty(raw);
+    if (offsetRaw === undefined)
+        return undefined;
+    const offset = Number(offsetRaw);
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new Error("--offset must be a whole number 0 or greater.");
+    return offset;
 }
-function buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link) {
+function buildDocsCommand(values, action, docRef, docRefs, visibility, clearParent, parentId, allowEmpty, title, query, wholeWord, limit, bodies, section, offset, link, safety) {
     return {
         kind: "docs",
         action,
@@ -228,6 +254,8 @@ function buildDocsCommand(values, action, docRef, docRefs, visibility, clearPare
         ...(parentId ? { parentId } : {}),
         clearParent,
         ...(allowEmpty ? { allowEmpty } : {}),
+        ...(safety.requestId ? { requestId: safety.requestId } : {}),
+        ...(safety.expectedRevision === undefined ? {} : { expectedRevision: safety.expectedRevision }),
         visibility: visibility,
         filePath: optionalNonEmpty(values.flags.get("--file")),
         bodyStdin: values.booleans.has("--body-stdin"),

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

@@ -33,26 +33,8 @@ export function parseGithubArgs(args) {
         throw new Error(`github ${action} takes a repo and a pull request number only.`);
     const pullNumber = numberText === undefined ? undefined : optionalPositiveInteger(numberText, "pull request number");
     const runId = optionalPositiveInteger(values.flags.get("--run"), "--run");
-    if (action === "rerun") {
-        if ((pullNumber === undefined) === (runId === undefined)) {
-            throw new Error("github rerun needs exactly one of a pull request number or --run <id>.");
-        }
-    }
-    else if (pullNumber === undefined) {
-        throw new Error(`github ${action} needs a pull request number.`);
-    }
-    const only = (flag, allowed) => {
-        if (values.flags.has(flag) && !allowed.includes(action)) {
-            throw new Error(`${flag} belongs to \`cockpit github ${allowed.join("|")}\`.`);
-        }
-    };
-    only("--claim", ["pr"]);
-    only("--method", ["merge"]);
-    only("--title", ["retitle"]);
-    only("--run", ["rerun"]);
-    if (values.flags.has("--confirm") && action === "pr") {
-        throw new Error("--confirm belongs to merge, retitle and rerun; pr only reads.");
-    }
+    requireTargetFor(action, pullNumber, runId);
+    refuseFlagsFromOtherActions(values, action);
     const title = optionalNonEmpty(values.flags.get("--title"));
     if (action === "retitle" && !title)
         throw new Error("github retitle needs --title \"<new title>\".");
@@ -78,4 +60,28 @@ export function parseGithubArgs(args) {
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         json: values.booleans.has("--json"),
     };
+}
+function requireTargetFor(action, pullNumber, runId) {
+    if (action === "rerun") {
+        if ((pullNumber === undefined) === (runId === undefined)) {
+            throw new Error("github rerun needs exactly one of a pull request number or --run <id>.");
+        }
+    }
+    else if (pullNumber === undefined) {
+        throw new Error(`github ${action} needs a pull request number.`);
+    }
+}
+function refuseFlagsFromOtherActions(values, action) {
+    const only = (flag, allowed) => {
+        if (values.flags.has(flag) && !allowed.includes(action)) {
+            throw new Error(`${flag} belongs to \`cockpit github ${allowed.join("|")}\`.`);
+        }
+    };
+    only("--claim", ["pr"]);
+    only("--method", ["merge"]);
+    only("--title", ["retitle"]);
+    only("--run", ["rerun"]);
+    if (values.flags.has("--confirm") && action === "pr") {
+        throw new Error("--confirm belongs to merge, retitle and rerun; pr only reads.");
+    }
 }

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

@@ -37,27 +37,39 @@ export function parseHitsArgs(args) {
     }
     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")) };
-    }
+    const parsed = { values, given, common };
+    if (action === "timeline")
+        return parseHitsTimeline(parsed);
+    if (action === "coach")
+        return parseHitsCoach(parsed);
+    if (action === "approve")
+        return parseHitsApprove(parsed);
+    return parseHitsRead(parsed);
+}
+function refuseApproveFlags({ given }) {
     if (given("--scope") || given("--version"))
         throw new Error("--scope and --version belong to hits approve.");
+}
+function parseHitsTimeline(parsed) {
+    refuseApproveFlags(parsed);
+    const weeks = optionalPositiveInteger(parsed.values.flags.get("--weeks"), "--weeks");
+    if (weeks !== undefined && weeks > 26)
+        throw new Error("--weeks must be 26 or fewer.");
+    return { ...parsed.common, action: "timeline", ...(weeks !== undefined ? { weeks } : {}) };
+}
+function parseHitsCoach(parsed) {
+    refuseApproveFlags(parsed);
+    return { ...parsed.common, action: "coach" };
+}
+function parseHitsApprove({ values, common }) {
+    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: "approve", scope, ...versionOf(values.flags.get("--version")) };
+}
+function parseHitsRead(parsed) {
+    const { values, given, common } = parsed;
+    refuseApproveFlags(parsed);
     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 ")}).`);
@@ -77,7 +89,7 @@ export function parseHitsArgs(args) {
         throw new Error("--learning is read for one person: use --mine or --person <name>.");
     return {
         ...common,
-        action,
+        action: "read",
         ...(who ? { who } : {}),
         ...(person ? { person } : {}),
         ...(project ? { project } : {}),

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

@@ -3,6 +3,8 @@
  *
  *   cockpit manager clients
  *   cockpit manager client <client>
+ *   cockpit manager home <client>
+ *   cockpit manager summary <client> --version <v>|none [--health on_track|at_risk|blocked] [--headline <t>] [--bullet "YYYY-MM-DD: t"|"t"]... [--next <t>|none] [--blocker <t>|none]
  *   cockpit manager run <run-id>
  *   cockpit manager list <client> [--timeline] [--needs-review] [--status open|done|dropped|closed|all] [--owner <name> | --no-owner] [--overdue] [--kind <kind>] [--search <text>] [--archived] [--review dismissed|all]
  *   cockpit manager queue <client>
@@ -22,27 +24,36 @@
  */
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
 export const MANAGER_VERBS = [
-    "clients", "client", "run", "list", "queue", "show", "add", "edit", "done", "reopen", "link",
+    "clients", "client", "home", "summary", "run", "list", "queue", "show", "add", "edit", "done", "reopen", "link",
     "approve", "dismiss", "proposal", "archive", "unarchive",
 ];
 export const MANAGER_ACTION_STATUSES = ["open", "done", "dropped", "closed", "all"];
 export const MANAGER_TIMELINE_KINDS = ["meeting", "document", "milestone", "internal"];
+export const MANAGER_SUMMARY_HEALTHS = ["on_track", "at_risk", "blocked"];
+/** The verbs whose one positional word is a client (its id or its exact name). */
+const CLIENT_VERBS = new Set(["client", "home", "summary", "list", "queue", "add"]);
 const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const VERSION = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
 const ONE_VERB = `manager takes one verb: ${MANAGER_VERBS.join(", ")}. Example: \`cockpit manager clients\` or \`cockpit manager list <client>\`.`;
 const OWN_FLAGS = [
     "--timeline", "--needs-review", "--status", "--owner", "--owners", "--no-owner", "--kind", "--search", "--archived", "--review",
     "--title", "--detail", "--due", "--date", "--meeting", "--none", "--version", "--request-id", "--restore", "--overdue", "--source-url", "--source-note",
+    "--health", "--headline", "--bullet", "--next", "--blocker",
 ];
 const COMMON_FLAGS = ["--home", "--dashboard-url", "--json", "--help"];
 const VALUE_FLAGS = [
     "--status", "--owner", "--owners", "--kind", "--search", "--review", "--title", "--detail", "--due", "--date", "--meeting",
     "--version", "--request-id", "--source-url", "--source-note", "--home", "--dashboard-url",
+    "--health", "--headline", "--bullet", "--next", "--blocker",
 ];
+/** `summary --bullet` is given once per bullet: the one value flag that may repeat. */
+const REPEATABLE_FLAGS = new Set(["--bullet"]);
 /** Which flags each verb owns, so a flag on the wrong verb is refused by name rather than ignored. */
 export const FLAGS_BY_VERB = {
     clients: [],
     client: [],
+    home: [],
+    summary: ["--version", "--health", "--headline", "--bullet", "--next", "--blocker"],
     run: [],
     list: ["--timeline", "--needs-review", "--status", "--owner", "--no-owner", "--overdue", "--kind", "--search", "--archived", "--review"],
     queue: [],
@@ -62,6 +73,8 @@ export const FLAGS_BY_VERB = {
 const POSITIONALS = {
     clients: [],
     client: ["client"],
+    home: ["client"],
+    summary: ["client"],
     run: ["run id"],
     list: ["client"],
     queue: ["client"],
@@ -80,6 +93,8 @@ const POSITIONALS = {
 /** A value flag given twice would silently keep only the last; say so instead. */
 function refuseRepeatedFlags(args) {
     for (const flag of VALUE_FLAGS) {
+        if (REPEATABLE_FLAGS.has(flag))
+            continue;
         const times = args.filter((arg) => arg === flag || arg.startsWith(`${flag}=`)).length;
         if (times > 1) {
             throw new Error(flag === "--owners"
@@ -113,12 +128,12 @@ export function parseManagerArgs(args) {
     if (rest.length !== wanted.length) {
         throw new Error(wanted.length === 0
             ? `\`cockpit manager ${verb}\` takes no positional arguments.`
-            : `\`cockpit manager ${verb}\` takes exactly: ${wanted.map((word) => `<${word}>`).join(" ")}${verb === "list" || verb === "queue" || verb === "add" || verb === "client" ? " (quote a client's name that has spaces)" : ""}.`);
+            : `\`cockpit manager ${verb}\` takes exactly: ${wanted.map((word) => `<${word}>`).join(" ")}${CLIENT_VERBS.has(verb) ? " (quote a client's name that has spaces)" : ""}.`);
     }
     const timeline = values.booleans.has("--timeline");
     const shape = { ...base, action: verb, timeline };
     const flag = (name) => values.flags.get(name);
-    if (verb === "list" || verb === "queue" || verb === "add" || verb === "client")
+    if (CLIENT_VERBS.has(verb))
         shape.client = rest[0];
     else if (verb === "run")
         shape.runId = readId(rest[0], "A run");
@@ -128,9 +143,11 @@ export function parseManagerArgs(args) {
         shape.proposalId = rest[1];
         shape.decision = readDecision(rest[2]);
     }
-    const needsVersion = !["clients", "client", "run", "list", "queue", "show", "add"].includes(verb);
+    const needsVersion = !["clients", "client", "home", "summary", "run", "list", "queue", "show", "add"].includes(verb);
     if (needsVersion)
         shape.version = readVersion(flag("--version"), verb);
+    if (verb === "summary")
+        readSummaryFields(values, shape);
     if (verb === "list")
         readListFilters(values, shape);
     if (verb === "add")
@@ -368,4 +385,68 @@ function readLink(values, shape) {
     if (!meeting && !none)
         throw new Error("`cockpit manager link` needs --meeting <timeline-id> to link, or --none to unlink.");
     shape.timelineItemId = meeting ? readId(meeting, "A timeline item") : null;
+}
+/** `summary`'s version: the card's `summary.updatedAt` as `home --json` gives it, or `none` when the client has no card yet. */
+function readSummaryVersion(raw) {
+    if (raw === undefined) {
+        throw new Error("`cockpit manager summary` needs --version: the card's summary.updatedAt from `cockpit manager home <client> --json`, or none when the client has no card yet. It keeps you from writing over a newer card.");
+    }
+    if (isNone(raw))
+        return null;
+    if (!VERSION.test(raw))
+        throw new Error("--version is the card's summary.updatedAt exactly as `cockpit manager home <client> --json` gives it, like 2026-10-09T17:03:11.123456+00:00, or none.");
+    return raw;
+}
+/** `--bullet "2026-10-14: Signed the SOW"` is a dated bullet; without a leading `YYYY-MM-DD: ` it is undated. */
+export function readBullet(raw) {
+    // A bullet pasted from a list keeps no "- " or "* " of its own.
+    const value = raw.trim().replace(/^[-*•]\s+/u, "");
+    const dated = /^(\d{4}-\d{2}-\d{2}):\s*(.*)$/s.exec(value);
+    const dateLike = dated ? null : /^(\d{1,4}[-/.]\d{1,2}[-/.]\d{1,4})\s*:/.exec(value);
+    if (dateLike)
+        throw new Error(`--bullet "${raw}" starts with ${dateLike[1]}, which is not a YYYY-MM-DD day. Write it like 2026-10-14, or leave the date out for an undated bullet.`);
+    const date = dated ? dated[1] : null;
+    const text = (dated ? dated[2] : value).trim();
+    if (date !== null && !isCalendarDate(date))
+        throw new Error(`--bullet "${raw}" starts with ${date}, which is not a real day. Write the date YYYY-MM-DD, like 2026-10-14, or leave it out for an undated bullet.`);
+    if (text === "")
+        throw new Error("--bullet needs words after its date. Example: --bullet \"2026-10-14: Signed the SOW\".");
+    return { date, text };
+}
+/** The card's fields. Counts, lengths and "blocked needs a blocker" are the server's rules, refused there by name. */
+function readSummaryFields(values, shape) {
+    shape.version = readSummaryVersion(values.flags.get("--version"));
+    let changes = 0;
+    const health = values.flags.get("--health");
+    if (health !== undefined) {
+        if (!MANAGER_SUMMARY_HEALTHS.includes(health))
+            throw new Error(`--health wants one of ${MANAGER_SUMMARY_HEALTHS.join(", ")}.`);
+        shape.health = health;
+        changes += 1;
+    }
+    const headline = values.flags.get("--headline");
+    if (headline !== undefined) {
+        if (headline.trim() === "")
+            throw new Error("--headline cannot be blank.");
+        shape.headline = headline.trim();
+        changes += 1;
+    }
+    const bullets = values.flagValues.get("--bullet");
+    if (bullets !== undefined && bullets.length > 0) {
+        shape.bullets = bullets.map(readBullet);
+        changes += 1;
+    }
+    const next = values.flags.get("--next");
+    if (next !== undefined) {
+        shape.next = isNone(next) ? null : next.trim();
+        changes += 1;
+    }
+    const blocker = values.flags.get("--blocker");
+    if (blocker !== undefined) {
+        shape.blocker = isNone(blocker) ? null : blocker.trim();
+        changes += 1;
+    }
+    if (changes === 0) {
+        throw new Error("`cockpit manager summary` has nothing to change. Give at least one of --health, --headline, --bullet (1 to 5 of them, replacing the list), --next, --blocker. A flag you leave out keeps its value; none clears --next or --blocker.");
+    }
 }