@bli-cockpit/cli 0.2.224 → 0.2.236

package/dist/commands/agent-door.js

@@ -57,6 +57,41 @@ export async function askAgentDoor(door, options) {
     }
     return { ok: true, httpStatus: result.response.status, body };
 }
+/**
+ * A GET whose answer is a FILE (ticket 20694, `cockpit docs export`): the bytes
+ * come back untouched, never through a JSON or text decode. A refusal keeps the
+ * door's own `reason` and `message`, exactly as `askAgentDoor` does.
+ */
+export async function fetchAgentDoorFile(door, options) {
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: options.path,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: "GET",
+        label: options.label,
+        timeoutMs: options.timeoutMs,
+        ...(door.homeDir === undefined ? {} : { homeDir: door.homeDir }),
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        const failure = result;
+        return { ok: false, reason: failure.reason, detail: towerFailureDetail(failure.reason, failure.detail) };
+    }
+    if (!result.response.ok) {
+        const status = result.response.status;
+        const body = await readResponseJson(result.response);
+        return {
+            ok: false,
+            reason: doorReason(body) ?? `http_${status}`,
+            detail: doorMessage(body) ?? `Tower answered ${status} and said nothing about why.`,
+        };
+    }
+    const bytes = Buffer.from(await result.response.arrayBuffer());
+    const disposition = result.response.headers.get("content-disposition") ?? "";
+    const filename = /filename="([^"]+)"/.exec(disposition)?.[1] ?? null;
+    return { ok: true, bytes, filename, contentType: result.response.headers.get("content-type") ?? "" };
+}
 /** The door's own `reason` label (`document_not_found_or_unreadable`, `needs_rls_client`, …), verbatim. */
 function doorReason(body) {
     if (!body || typeof body !== "object")

package/dist/commands/approvals.js

@@ -232,4 +232,6 @@ async function readJsonObject(door, verb) {
         return { ok: false, reason: "invalid_json_body", detail: "stdin must be one JSON object, like {\"text\":\"...\"}. Nothing was sent." };
     }
     return { ok: true, value: parsed };
-}
+}
+// BLI-19259: `cockpit drills` is re-exported here so `local.ts` (at the readability ceiling) imports both on one line.
+export { runDrills } from "./drills.js";

package/dist/commands/brain.js

@@ -2,6 +2,27 @@ import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./age
 import { writeLine } from "./cli-io.js";
 const TAG = "[brain cli]";
 const READ_DEADLINE_MS = 55_000;
+async function runLadder(door, ladder, json) {
+    const base = "/api/brain/ladder";
+    const request = (() => {
+        switch (ladder.verb) {
+            case "show": return { path: base, method: "GET", label: "brain ladder show" };
+            case "promote": return { path: `${base}/promote`, method: "POST", label: "brain ladder promote", body: { class: ladder.className, anyway: ladder.anyway, note: ladder.note, via: "cli" } };
+            case "demote": return { path: `${base}/demote`, method: "POST", label: "brain ladder demote", body: { class: ladder.className, note: ladder.note, via: "cli" } };
+            case "predict": return { path: `${base}/predictions`, method: "POST", label: "brain ladder predict", body: { question: ladder.text, context: ladder.context, asker: ladder.asker, source_kind: ladder.sourceKind, source_ref: ladder.sourceRef } };
+            case "answer": return { path: `${base}/answers`, method: "POST", label: "brain ladder answer", body: { answer: ladder.text, prediction_id: ladder.predictionId, source_kind: ladder.sourceKind, source_ref: ladder.sourceRef } };
+        }
+    })();
+    const answer = await askAgentDoor(door, { path: request.path, method: request.method, label: request.label, timeoutMs: READ_DEADLINE_MS, ...(request.body ? { body: request.body } : {}) });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(door.io.stderr, `${TAG} ladder ${ladder.verb} answered ${JSON.stringify({ ok: body.ok !== false, reason: body.reason ?? "ok" })}`);
+    if (json)
+        return emitAgentDoor(door, body, body.ok === false ? 1 : 0);
+    writeLine(door.io.stdout, body.text ?? body.message ?? "");
+    return body.ok === false ? 1 : 0;
+}
 export async function runBrain(command, io) {
     let door;
     try {
@@ -16,6 +37,8 @@ export async function runBrain(command, io) {
             writeLine(io.stderr, detail);
         return 1;
     }
+    if (command.ladder)
+        return runLadder(door, command.ladder, command.json);
     if (command.action === "retry") {
         const answer = await askAgentDoor(door, { path: "/api/brain/incidents/retry", method: "POST", label: "brain retry", timeoutMs: READ_DEADLINE_MS,
             body: { ids: command.ids, all_needs_human: command.allNeedsHuman, project: command.project, reason: command.reason } });

package/dist/commands/ci.js

@@ -0,0 +1,23 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { parseNamedArgs, optionalNonEmpty, optionalUrl } from "./local-arg-values.js";
+export function parseCiArgs(args) {
+    const values = parseNamedArgs(args, { allowedFlags: ["--repo", "--json", "--home", "--dashboard-url"], valueFlags: ["--repo", "--home", "--dashboard-url"] });
+    const repo = values.flags.get("--repo");
+    if (values.positionals.length !== 1 || values.positionals[0] !== "report" || (repo !== undefined && !/^BLI-INC\/[A-Za-z0-9_.-]+$/.test(repo)))
+        throw new Error("Usage: cockpit ci report [--repo BLI-INC/name] [--json]");
+    return { kind: "ci", action: "report", repo, json: values.booleans.has("--json"), homeDir: optionalNonEmpty(values.flags.get("--home")), dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")) };
+}
+export async function runCi(command, io) {
+    const door = await openAgentDoor("ci", command, io);
+    const query = command.repo ? `?${new URLSearchParams({ repo: command.repo })}` : "";
+    const answer = await askAgentDoor(door, { path: `/api/ops/ci/report${query}`, method: "GET", label: "ci report", timeoutMs: 30_000 });
+    if (!answer.ok)
+        return failAgentDoor(door, "[ci cli]", answer.reason, answer.detail);
+    if (command.json)
+        return emitAgentDoor(door, answer.body);
+    const body = answer.body;
+    for (const line of body.lines)
+        writeLine(io.stdout, line);
+    return 0;
+}

package/dist/commands/docs-export.js

@@ -0,0 +1,62 @@
+/**
+ * `cockpit docs export <id|slug> [--format md|pdf|docx|txt] [--out <path>]`
+ * (ticket 20694). A sibling of `docs.ts`: one verb, one door.
+ *
+ * `GET /api/docs/documents/[id]/export?format=` is the same door the browser's
+ * Export menu calls. The bytes are written untouched; the filename is the one
+ * the door chose (a slug of the title plus the extension) unless `--out` names
+ * another. `cockpit docs read` already covers "copy": it prints the Markdown.
+ */
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { emitAgentDoor, failAgentDoor, fetchAgentDoorFile } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+import { resolveDocId } from "./docs.js";
+const TAG = "[docs cli]";
+const EXPORT_DEADLINE_MS = 90_000;
+async function isDirectory(target) {
+    try {
+        return (await stat(target)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function exportDoc(command, door) {
+    const ref = command.docRef ?? "";
+    const format = command.exportFormat ?? "md";
+    const resolved = await resolveDocId(door, ref);
+    if (resolved.status === "list_failed")
+        return failAgentDoor(door, TAG, resolved.reason, resolved.detail);
+    if (resolved.status === "not_found") {
+        return failAgentDoor(door, TAG, "document_not_found_or_unreadable", `That document does not exist, or you cannot read it: ${ref}`);
+    }
+    const started = Date.now();
+    const answer = await fetchAgentDoorFile(door, {
+        path: `/api/docs/documents/${encodeURIComponent(resolved.id)}/export?format=${encodeURIComponent(format)}`,
+        label: "docs export",
+        timeoutMs: EXPORT_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const filename = path.basename(answer.filename ?? `${ref}.${format}`);
+    let target = path.resolve(process.cwd(), filename);
+    if (command.outPath) {
+        const asked = path.resolve(command.outPath);
+        const wantsDirectory = /[\\/]$/.test(command.outPath) || (await isDirectory(asked));
+        target = wantsDirectory ? path.join(asked, filename) : asked;
+    }
+    try {
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, answer.bytes);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return failAgentDoor(door, TAG, "export_write_failed", `Could not write ${target}: ${detail}`);
+    }
+    writeLine(door.io.stderr, `${TAG} export ${JSON.stringify({ document_id: resolved.id, format, bytes: answer.bytes.length, duration_ms: Date.now() - started })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, path: target, bytes: answer.bytes.length, format });
+    writeLine(door.io.stdout, target);
+    return 0;
+}

package/dist/commands/docs.js

@@ -30,6 +30,7 @@
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
 import { readDoc } from "./docs-read.js";
+import { exportDoc } from "./docs-export.js";
 import { linkDoc, syncStatusDocs } from "./docs-notion.js";
 import { readNoteFile } from "./notes-file.js";
 import { cacheAgeLabel, cacheCoverage, readThroughCache } from "./read-cache.js";
@@ -56,6 +57,8 @@ export async function runDocs(command, io) {
             return linkDoc(command, door);
         case "sync-status":
             return syncStatusDocs(command, door);
+        case "export":
+            return exportDoc(command, door);
     }
 }
 /** `--parent`, `--query`, `--word`, `--limit`, `--bodies` (BLI-10450) as the door's own query parameters (BLI-3737). */

package/dist/commands/drills-render.js

@@ -0,0 +1,63 @@
+/** Plain-words rendering of the drills doors for the terminal (BLI-19259). No system nouns, no dashes used as punctuation. */
+const indent = (text, prefix = "    ") => text.split("\n").map((line) => `${prefix}${line}`);
+export function drillLines(current) {
+    const lines = [`${current.framing.bossName}: ${current.framing.roundLine}${current.redrillDay ? ` (back after ${current.redrillDay} day${current.redrillDay === 1 ? "" : "s"})` : ""}`, "", current.scenario.title, current.scenario.context, ""];
+    lines.push(`The ${current.scenario.artifactKind}:`, ...indent(current.scenario.artifact));
+    if (current.scenario.logExcerpt)
+        lines.push("", "What it printed, up to the moment before it broke:", ...indent(current.scenario.logExcerpt));
+    lines.push("", current.scenario.question);
+    if (current.scenario.reconstructed)
+        lines.push("(Rebuilt from the incident write-up, so the details are close, not word for word.)");
+    return lines;
+}
+const minutes = (value) => (value === null ? "none yet" : value >= 120 ? `${(value / 60).toFixed(1)} hours` : `${Math.round(value)} minutes`);
+export function overviewLines(body) {
+    const lines = [];
+    if (body.current)
+        lines.push("You have a drill open. Answer it before you see the cause:", "", ...drillLines(body.current), "", "Answer with: echo \"what you think\" | cockpit drills answer --confidence <1-5>", "");
+    else if (body.queue.redrillsDue > 0)
+        lines.push(`${body.queue.redrillsDue} drill${body.queue.redrillsDue === 1 ? "" : "s"} you were sure about ${body.queue.redrillsDue === 1 ? "is" : "are"} due for another look. Run: cockpit drills start`, "");
+    else if (body.queue.newLeft > 0)
+        lines.push(`${body.queue.newLeft} new drill${body.queue.newLeft === 1 ? "" : "s"} waiting. Run: cockpit drills start`, "");
+    else
+        lines.push("You are all caught up. Nothing new is waiting.", "");
+    lines.push(`Theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default; change it with `cockpit drills theme set <theme>`)"}`, "");
+    if (body.bosses.length > 0) {
+        lines.push("Bosses");
+        for (const boss of body.bosses)
+            lines.push(`  ${boss.bossName}: ${boss.progressLine}`);
+        lines.push("");
+    }
+    const { stats } = body;
+    lines.push(`You have answered ${stats.answered} and passed ${stats.passed}. ${stats.confidentMisses} wrong answer${stats.confidentMisses === 1 ? "" : "s"} you were sure about.`);
+    lines.push(stats.firstRunGreenStreak.known ? `PRs green on the first CI run, in a row: at least ${stats.firstRunGreenStreak.value}.` : (stats.firstRunGreenStreak.note ?? ""));
+    if (stats.recovery.known && stats.recovery.value)
+        lines.push(`Recovering from a hit: last ${minutes(stats.recovery.value.lastMinutes)}, your best ${minutes(stats.recovery.value.bestMinutes)}.`);
+    if (stats.teamBeaten.known && stats.teamBeaten.value)
+        lines.push(`Across the team, ${stats.teamBeaten.value.fightsBeaten} boss fight${stats.teamBeaten.value.fightsBeaten === 1 ? "" : "s"} won, ${stats.teamBeaten.value.patternsBeaten} pattern${stats.teamBeaten.value.patternsBeaten === 1 ? "" : "s"} beaten at least once.`);
+    if (body.history.length > 0) {
+        lines.push("", "Recently");
+        for (const item of body.history.slice(0, 5))
+            lines.push(`  ${item.verdict === "pass" ? "passed" : item.verdict === "miss" ? "missed" : "unmarked"}  ${item.title}  (sure: ${item.confidence} of 5${item.hypercorrection ? ", comes back" : ""})`);
+    }
+    for (const note of body.notes)
+        lines.push("", note);
+    return lines.filter((line, index, all) => !(line === "" && all[index - 1] === ""));
+}
+export function reviewLines(body) {
+    const lines = [body.headline];
+    const section = (title, items) => {
+        if (items.length > 0)
+            lines.push("", title, ...items.map((item) => `  ${item}`));
+    };
+    if (body.hits.known && body.hits.value)
+        section("Your hits this week", body.hits.value.length === 0 ? ["None."] : body.hits.value.map((hit) => `A ${hit.weight} one: ${hit.patternLabel.toLowerCase()}${hit.recoveredMinutes === null ? "" : `, back to green in ${minutes(hit.recoveredMinutes)}`}.`));
+    section("Wins", body.wins);
+    section("Highs", body.highs);
+    section("Lows", body.lows);
+    section("Where you have stopped improving", body.plateaus);
+    section("What to practise", body.practise.map((item) => `${item.patternLabel}: ${item.why}`));
+    for (const note of body.notes)
+        lines.push("", note);
+    return lines;
+}

package/dist/commands/drills.js

@@ -0,0 +1,152 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { drillLines, overviewLines, reviewLines } from "./drills-render.js";
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+const TAG = "[drills cli]";
+const READ_DEADLINE_MS = 30_000;
+const WRITE_DEADLINE_MS = 55_000;
+const ANSWER_MAX_CHARS = 4_000;
+export async function runDrills(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("drills", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    switch (command.action) {
+        case "list": return list(door);
+        case "start": return start(door);
+        case "answer": return answer(command, door);
+        case "theme": return themeShow(door);
+        case "theme-set": return themeSet(command, door);
+        case "review": return review(door);
+    }
+}
+async function list(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills", method: "GET", label: "drills list", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} list answered ${JSON.stringify({ open: body.current !== null, bosses: body.bosses.length, history: body.history.length, new_left: body.queue.newLeft })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    for (const line of overviewLines(body))
+        writeLine(door.io.stdout, line);
+    return 0;
+}
+async function start(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills/start", method: "POST", label: "drills start", timeoutMs: READ_DEADLINE_MS, body: {} });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} start answered ${JSON.stringify({ started: body.started, reason: body.reason })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    if (!body.started || !body.current) {
+        writeLine(door.io.stdout, body.message ?? "Nothing new is waiting for you right now.");
+        return 0;
+    }
+    for (const line of drillLines(body.current))
+        writeLine(door.io.stdout, line);
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, "Answer first, then see the cause:  echo \"what you think\" | cockpit drills answer --confidence <1-5>");
+    return 0;
+}
+async function openAttemptId(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills", method: "GET", label: "drills list", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return { ok: false, reason: response.reason, detail: response.detail };
+    const current = response.body.current;
+    if (!current)
+        return { ok: false, reason: "no_open_drill", detail: "No drill is open. Run `cockpit drills start` first." };
+    return { ok: true, id: current.attemptId };
+}
+async function answer(command, door) {
+    let text = command.text;
+    if (!text) {
+        if (isInteractiveStdin(door.io))
+            return failAgentDoor(door, TAG, "nothing_piped", "Pipe your answer in, e.g. `echo \"it will stop at 1,000 rows\" | cockpit drills answer --confidence 4`, or use --text. Nothing was sent.");
+        try {
+            text = (await readPipedText(door.io.stdin, { maxChars: ANSWER_MAX_CHARS, overflowMessage: `Keep your answer under ${ANSWER_MAX_CHARS} characters.` })).trim();
+        }
+        catch (error) {
+            return failAgentDoor(door, TAG, "answer_too_long", error instanceof Error ? error.message : String(error));
+        }
+    }
+    let id = command.attemptId;
+    if (!id) {
+        const open = await openAttemptId(door);
+        if (!open.ok)
+            return failAgentDoor(door, TAG, open.reason, open.detail);
+        id = open.id;
+    }
+    const response = await askAgentDoor(door, { path: "/api/drills/answer", method: "POST", label: "drills answer", timeoutMs: WRITE_DEADLINE_MS, body: { attemptId: id, answer: text, confidence: command.confidence } });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} answered ${JSON.stringify({ verdict: body.verdict, hypercorrection: body.hypercorrection, redrills: body.redrills.length, new_win: body.newWin })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    const out = door.io.stdout;
+    writeLine(out, body.message);
+    writeLine(out, "");
+    writeLine(out, "The real cause:");
+    writeLine(out, `  ${body.reveal.realCause}`);
+    writeLine(out, "The guard that would have caught it:");
+    writeLine(out, `  ${body.reveal.guard}`);
+    if (body.reveal.aftermath)
+        writeLine(out, `What it cost: ${body.reveal.aftermath}`);
+    if (body.redrills.length > 0)
+        writeLine(out, `It comes back in ${body.redrills.map((plan) => plan.day).join(", ")} days.`);
+    return 0;
+}
+async function themeShow(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills/theme", method: "GET", label: "drills theme", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} theme answered ${JSON.stringify({ key: body.theme.key, chosen: body.theme.chosen, ready: body.ready })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    writeLine(door.io.stdout, `Your theme: ${body.theme.label}${body.theme.chosen ? "" : " (the default)"}`);
+    writeLine(door.io.stdout, "Choices:");
+    for (const choice of body.themes)
+        writeLine(door.io.stdout, `  ${choice.key}: ${choice.blurb}${choice.key === body.suggestedTheme && !body.theme.chosen ? "  (suggested)" : ""}`);
+    writeLine(door.io.stdout, "Or use your own words. Change it with: cockpit drills theme set <theme> [--play <what you play>] [--watch <what you watch>] [--train <what you train>]");
+    return 0;
+}
+async function themeSet(command, door) {
+    const response = await askAgentDoor(door, {
+        path: "/api/drills/theme",
+        method: "POST",
+        label: "drills theme set",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { theme: command.theme, ...(command.play ? { play: command.play } : {}), ...(command.watch ? { watch: command.watch } : {}), ...(command.train ? { train: command.train } : {}) },
+    });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} theme saved ${JSON.stringify({ key: body.theme.key, closed: body.theme.closed, preparing: body.preparing ?? false })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    writeLine(door.io.stdout, body.message ?? "Theme saved.");
+    return 0;
+}
+async function review(door) {
+    const response = await askAgentDoor(door, { path: "/api/drills/review", method: "GET", label: "drills review", timeoutMs: READ_DEADLINE_MS });
+    if (!response.ok)
+        return failAgentDoor(door, TAG, response.reason, response.detail);
+    const body = response.body;
+    writeLine(door.io.stderr, `${TAG} review answered ${JSON.stringify({ practise: body.practise.length, plateaus: body.plateaus.length })}`);
+    if (door.json)
+        return emitAgentDoor(door, response.body);
+    for (const line of reviewLines(body))
+        writeLine(door.io.stdout, line);
+    return 0;
+}

package/dist/commands/hits.js

@@ -0,0 +1,83 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[hits cli]";
+const READ_DEADLINE_MS = 55_000;
+/** The door's own query for a read: only what the person asked for, so the door's defaults stay the door's. */
+export function hitsReadQuery(command) {
+    const query = new URLSearchParams();
+    if (command.who)
+        query.set("who", command.who);
+    if (command.person)
+        query.set("person", command.person);
+    if (command.project)
+        query.set("project", command.project);
+    if (command.days !== undefined)
+        query.set("days", String(command.days));
+    if (command.top !== undefined)
+        query.set("top", String(command.top));
+    if (command.learning)
+        query.set("learning", "1");
+    if (command.patterns)
+        query.set("view", "patterns");
+    return query.toString();
+}
+export async function runHits(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("hits", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    if (command.action === "approve") {
+        const answer = await askAgentDoor(door, { path: "/api/hits/patterns/approve", method: "POST", label: "hits approve", timeoutMs: READ_DEADLINE_MS,
+            body: { scope: command.scope, ...(command.version !== undefined ? { version: command.version } : {}) } });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const body = answer.body;
+        writeLine(io.stderr, `${TAG} approve answered ${JSON.stringify({ reason: body.reason, approved: body.approved ?? 0, version: body.version ?? null })}`);
+        if (command.json)
+            return emitAgentDoor(door, body, body.ok ? 0 : 1);
+        writeLine(io.stdout, body.text);
+        return body.ok ? 0 : 1;
+    }
+    if (command.action === "timeline") {
+        const path = command.weeks !== undefined ? `/api/hits/timeline?weeks=${command.weeks}` : "/api/hits/timeline";
+        const answer = await askAgentDoor(door, { path, method: "GET", label: "hits timeline", timeoutMs: READ_DEADLINE_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const body = answer.body;
+        writeLine(io.stderr, `${TAG} timeline read ${JSON.stringify({ weeks: body.weeks.length, hits: body.coverage.hits, labels: body.coverage.labels, end: body.coverage.end })}`);
+        if (command.json)
+            return emitAgentDoor(door, body);
+        writeLine(io.stdout, body.text);
+        return 0;
+    }
+    if (command.action === "coach") {
+        const answer = await askAgentDoor(door, { path: "/api/hits/coach", method: "GET", label: "hits coach", timeoutMs: READ_DEADLINE_MS });
+        if (!answer.ok)
+            return failAgentDoor(door, TAG, answer.reason, answer.detail);
+        const body = answer.body;
+        writeLine(io.stderr, `${TAG} coach read ${JSON.stringify({ alerts: body.alerts.length, rows: body.coverage.rows, pages: body.coverage.pages, end: body.coverage.end })}`);
+        if (command.json)
+            return emitAgentDoor(door, body);
+        writeLine(io.stdout, body.text);
+        return 0;
+    }
+    const asked = hitsReadQuery(command);
+    const answer = await askAgentDoor(door, { path: asked ? `/api/hits?${asked}` : "/api/hits", method: "GET", label: "hits read", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(io.stderr, `${TAG} read answered ${JSON.stringify({ who: body.who, hits: body.totals.hits, rows: body.coverage.rows, pages: body.coverage.pages, end: body.coverage.end })}`);
+    if (command.json)
+        return emitAgentDoor(door, body);
+    writeLine(io.stdout, body.text);
+    return 0;
+}

package/dist/commands/intentions.js

@@ -0,0 +1,49 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[intentions cli]";
+const DEADLINE_MS = 55_000;
+export async function runIntentions(command, io) {
+    let door;
+    try {
+        door = await openAgentDoor("intentions", command, io);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "this machine is not paired with Tower";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "not_paired" })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "not_paired", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+    let request;
+    if (command.action === "list") {
+        const query = new URLSearchParams();
+        if (command.status)
+            query.set("status", command.status);
+        if (command.project)
+            query.set("project", command.project);
+        if (command.limit !== undefined)
+            query.set("limit", String(command.limit));
+        const asked = query.toString();
+        request = { path: asked ? `/api/intentions?${asked}` : "/api/intentions", method: "GET", label: "intentions list" };
+    }
+    else if (command.action === "show") {
+        request = { path: `/api/intentions/${encodeURIComponent(command.id)}`, method: "GET", label: "intentions show" };
+    }
+    else {
+        request = {
+            path: `/api/intentions/${encodeURIComponent(command.id)}`, method: "POST", label: `intentions ${command.action}`,
+            body: { action: command.action, ...(command.evidence ? { evidence: command.evidence } : {}), ...(command.by ? { by: command.by } : {}) },
+        };
+    }
+    const answer = await askAgentDoor(door, { ...request, timeoutMs: DEADLINE_MS });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    writeLine(io.stderr, `${TAG} ${command.action} answered ${JSON.stringify({ rows: body.intentions?.length ?? 1, ...(body.coverage ? { requested: body.coverage.requested, returned: body.coverage.returned, unique: body.coverage.unique, end: body.coverage.end } : {}) })}`);
+    if (command.json)
+        return emitAgentDoor(door, body);
+    writeLine(io.stdout, body.text ?? "");
+    return 0;
+}

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);
     }