@bli-cockpit/cli 0.2.123 → 0.2.125

package/dist/commands/brief-done.js

@@ -0,0 +1,144 @@
+/**
+ * `cockpit brief done <item>` / `cockpit brief undone <item>` (BLI-3605).
+ *
+ * The website's board has a checkbox; this is that checkbox at a terminal,
+ * over the same `POST /api/jarvis/ticks` door with the same device token.
+ *
+ * The one judgement this file makes is REFUSING BEFORE WRITING. A tick is
+ * keyed on a board row — its ticket identifier, or its claim id for a row with
+ * no ticket — and a key that names nothing would sit in the table forever,
+ * ticked against an item nobody can find. So the page is read first, the item
+ * is looked for in it, and an item that is not on the board is named in the
+ * person's own words with nothing sent. That read costs one request and buys
+ * the only error message worth having.
+ *
+ * Whose page: your own. There is deliberately no `--for` here. Every other
+ * brief verb lets an admin work on somebody else's page; a tick is private
+ * working state, and the door has no way to accept one on another person's
+ * behalf even if this command asked.
+ */
+import { colorEnabled, dim, writeLine } from "./cli-io.js";
+import { loadPairedSession, towerJsonRequest } from "../tower-client.js";
+const REQUEST_DEADLINE_MS = 30_000;
+/** A ticket identifier as Linear writes it, and as a board row carries it. */
+const TICKET_IDENTIFIER = /^[A-Z][A-Z0-9]{1,9}-\d+$/;
+export async function runBriefDone(command, io) {
+    const done = command.action === "done";
+    const item = (command.item ?? "").trim();
+    const session = await loadPairedSession(`brief ${command.action}`, command.homeDir);
+    const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
+    const log = (line) => writeLine(io.stderr, line);
+    const page = await readThePage(dashboardUrl, session.device_token, io, log);
+    if (!page)
+        return 1;
+    const found = findTheItem(page, item);
+    if (!found) {
+        // Named rather than sent. See the module header.
+        writeFailure(command, io, "unknown_item", notOnTheBoard(item));
+        return 1;
+    }
+    const result = await towerJsonRequest({
+        dashboardUrl,
+        path: "/api/jarvis/ticks",
+        deviceToken: session.device_token,
+        fetch: io.fetch,
+        method: "POST",
+        label: `brief ${command.action}`,
+        timeoutMs: REQUEST_DEADLINE_MS,
+        log,
+        body: {
+            item_key: found.itemKey,
+            ticket_identifier: found.ticketIdentifier,
+            claim_id: found.claimId,
+            page_id: page.page?.pageId ?? null,
+            done,
+        },
+    });
+    if (!result.ok) {
+        writeFailure(command, io, result.reason, result.detail);
+        return 1;
+    }
+    const body = result.body;
+    if (!body.ok) {
+        writeFailure(command, io, body.error ?? "not_saved", body.reply ?? body.error ?? "It did not save.");
+        return 1;
+    }
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(body));
+    }
+    else {
+        const styled = colorEnabled(io);
+        const box = done ? "[x]" : "[ ]";
+        writeLine(io.stdout, `${box} ${found.itemKey} ${done ? "done" : "back on the board"}`);
+        writeLine(io.stdout, dim(found.text, styled));
+    }
+    writeLine(io.stderr, `[brief tick cli] ${done ? "ticked" : "unticked"} ${JSON.stringify({
+        item_key: found.itemKey,
+        has_ticket: found.ticketIdentifier != null,
+    })}`);
+    return 0;
+}
+/** The page, with its claim ids, so an item can be checked before anything is sent. */
+async function readThePage(dashboardUrl, deviceToken, io, log) {
+    const result = await towerJsonRequest({
+        dashboardUrl,
+        path: "/api/jarvis/brief?claims=1",
+        deviceToken,
+        fetch: io.fetch,
+        method: "GET",
+        label: "brief",
+        timeoutMs: REQUEST_DEADLINE_MS,
+        log,
+    });
+    if (!result.ok) {
+        writeLine(io.stderr, `[brief tick cli] page unread ${JSON.stringify({ reason: result.reason })}`);
+        writeLine(io.stdout, result.detail);
+        return undefined;
+    }
+    const body = result.body;
+    if (!body.ok) {
+        writeLine(io.stdout, body.reply ?? body.error ?? "There is no page here yet.");
+        return undefined;
+    }
+    return body;
+}
+/**
+ * The board row the person named, found in the page they can actually see.
+ *
+ * Two spellings, because those are the two keys a row can have: a ticket
+ * identifier (matched inside the rendered line, which is where the board puts
+ * it) and a claim id (matched exactly, as `cockpit brief --claims` prints it).
+ * A ticket identifier wins when both could match, because that is the key the
+ * tick is stored under and the one that survives tomorrow's compile.
+ */
+export function findTheItem(page, item) {
+    const claims = page.claims ?? [];
+    if (TICKET_IDENTIFIER.test(item)) {
+        const line = claims.find((claim) => (claim.text ?? "").includes(item));
+        if (!line)
+            return null;
+        return {
+            itemKey: item,
+            ticketIdentifier: item,
+            claimId: line.claimId ?? null,
+            text: line.text ?? "",
+        };
+    }
+    const line = claims.find((claim) => claim.claimId === item);
+    if (!line)
+        return null;
+    return { itemKey: item, ticketIdentifier: null, claimId: item, text: line.text ?? "" };
+}
+function notOnTheBoard(item) {
+    return (`Nothing on your page is called "${item}". Run \`cockpit brief --claims\` to see the ids, ` +
+        "or name the ticket exactly as the board writes it. Nothing was recorded.");
+}
+function writeFailure(command, io, reason, detail) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({ ok: false, error: reason, reply: detail }));
+    }
+    else {
+        writeLine(io.stdout, detail);
+    }
+    writeLine(io.stderr, `[brief tick cli] refused ${JSON.stringify({ reason })}`);
+}

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

@@ -1,5 +1,7 @@
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from './local-arg-values.js';
 const ACTIONS = ['list', 'show', 'rescreen', 'invite', 'decide', 'grade', 'takehome-show', 'takehome-set', 'settings-show', 'settings-set'];
+/** Typed word → the one action it means. The left side is what a person reads on the button. */
+const ALSO_SPELLED = { 'send-takehome': 'invite' };
 const DECISIONS = ['passed_on', 'archived', 'reopen'];
 /** Verbs that name an application id, a role slug, or nothing at all. */
 const NEEDS_ID = ['show', 'rescreen', 'invite', 'decide', 'grade'];
@@ -14,15 +16,18 @@ export function parseCareersArgs(args) {
     // `team device` reads as `team device list`: the noun alone is a question.
     const first = positionals[0] ?? 'list';
     const paired = first === 'takehome' || first === 'settings';
-    const action = paired
+    const typed = paired
         ? `${first}-${positionals.splice(0, positionals[1] === undefined ? 1 : 2)[1] ?? 'show'}`
         : (positionals.shift() ?? 'list');
+    // `send-takehome` is the button's own words; `invite` is the older spelling
+    // of the same act. One action from here on, the typed word only for errors.
+    const action = ALSO_SPELLED[typed] ?? typed;
     if (!ACTIONS.includes(action))
-        throw new Error(`careers takes ${ACTIONS.join(', ')}.`);
+        throw new Error(`careers takes ${[...ACTIONS, ...Object.keys(ALSO_SPELLED)].join(', ')}.`);
     const verb = action;
     const target = positionals.shift();
     if (NEEDS_ID.includes(verb) && !target)
-        throw new Error(`careers ${verb} needs an application id.`);
+        throw new Error(`careers ${typed} needs an application id.`);
     if (NEEDS_ROLE.includes(verb) && !target)
         throw new Error(`careers ${verb.replace('-', ' ')} needs a role slug.`);
     if (positionals.length > 0)

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

@@ -64,11 +64,21 @@ export function parseBriefArgs(args) {
     // `status` (BLI-3462) answers why a brief was or was not delivered.
     const first = values.positionals[0];
     const action = (first === undefined ? "read" : first);
-    if (!["read", "edit", "rewrite", "history", "status"].includes(action)) {
-        throw new Error(`Unknown brief command: ${first}. Try edit, rewrite, history or status, or nothing to read it.`);
+    if (!["read", "edit", "rewrite", "history", "status", "done", "undone"].includes(action)) {
+        throw new Error(`Unknown brief command: ${first}. Try done, undone, edit, rewrite, history or status, or nothing to read it.`);
     }
-    if (values.positionals.length > (first === undefined ? 0 : 1)) {
-        throw new Error(`brief ${action} does not take "${values.positionals[1]}".`);
+    // BLI-3605: `done` and `undone` are the only brief verbs that take a
+    // positional, and they REQUIRE one, "which item" is the whole command, and
+    // a bare `cockpit brief done` that guessed at the top row would tick off
+    // somebody's work for them.
+    const ticksAnItem = action === "done" || action === "undone";
+    const item = ticksAnItem ? values.positionals[1] : undefined;
+    if (ticksAnItem && !item) {
+        throw new Error(`brief ${action} needs the item: a ticket like BLI-3511, or a claim id from \`cockpit brief --claims\`.`);
+    }
+    const positionalsAllowed = first === undefined ? 0 : ticksAnItem ? 2 : 1;
+    if (values.positionals.length > positionalsAllowed) {
+        throw new Error(`brief ${action} does not take "${values.positionals[positionalsAllowed]}".`);
     }
     const tldr = values.booleans.has("--tldr");
     const full = values.booleans.has("--full");
@@ -133,6 +143,7 @@ export function parseBriefArgs(args) {
     return {
         kind: "brief",
         action,
+        ...(item ? { item } : {}),
         render,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),

package/dist/commands/local-help-commands-tower.js

@@ -25,11 +25,11 @@ export const TOWER_COMMAND_HELP = [
     [
         "careers",
         [
-            "Usage: cockpit careers [list|show <id>|rescreen <id>|invite <id>|decide <id> --decision <d>|grade <id>|takehome show <role>|takehome set <role>|settings show|settings set] [flags]",
+            "Usage: cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <d>|grade <id>|takehome show <role>|takehome set <role>|settings show|settings set] [flags]",
             "",
             "Super-admin application review and pipeline. Lists at most 100 matches with total and has_more; use filters to narrow.",
             "list [--role <slug>] [--min-score <n>] [--since <date>] [--stage <screened|invited|submitted|graded|booking_sent|passed_on|archived>] — the board, newest first, with the two thresholds in force.",
-            "invite <id> — sends that role's take-home from the configured mailbox, whatever the screening scored. Only a row still at `screened`.",
+            "send-takehome <id> (also `invite <id>`): sends that role's take-home from the configured mailbox, whatever the screening scored. The same act as Tower's Send take-home button, and only a row still at `screened`.",
             "decide <id> --decision <passed_on|archived|reopen> — your own call on a row; `reopen` puts it back to `screened`.",
             "grade <id> [--now]: puts one submission back in the take-home grader's queue. The grader runs on Railway every 15 minutes; --now says so rather than pretending the run happened here.",
             "takehome show <role> — the subject, body, link and the reviewer's rubric for that role.",

package/dist/commands/local-help-commands.js

@@ -410,7 +410,7 @@ export function localSubcommandHelp(command) {
         [
             "brief",
             [
-                "Usage: cockpit brief [edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit brief [done <item>|undone <item>|edit|rewrite|history] [--for <person>] [--date <YYYY-MM-DD>] [--delta [--against <YYYY-MM-DD>]] [--version <pageId>] [--tldr|--full] [--versions] [--claims] [--days <n>] [--reason \"<why>\"] [--wait|--no-wait] [--dashboard-url <url>] [--json]",
                 "",
                 "Prints the TODAY page — the same page the Tower website shows, rendered for a terminal.",
                 "--for opens somebody else's page; the website's own rule decides whether you may, and it refuses in plain words when you may not.",
@@ -442,6 +442,12 @@ export function localSubcommandHelp(command) {
                 "  With no editor, or with something piped in, the edited document is read from stdin instead — `cockpit brief edit < page.md`.",
                 "  The edit IS the correction: each changed line is filed in the ledger before the page is republished, so a publish that falls over never costs you the edit.",
                 "",
+                "done <item> / undone <item>, tick one DO THIS FIRST row off, or put it back. The same checkbox the website's board has, on the same record.",
+                "  <item> is the ticket exactly as the board writes it (BLI-3511), or a claim id from `cockpit brief --claims` for a row with no ticket behind it.",
+                "  A ticked row prints as [x] and says `done`; everything still open prints as [ ]. A ticket keeps its tick across every recompile, so what you finished stays finished.",
+                "  An item that is not on your page is named before anything is sent, and nothing is recorded.",
+                "  Your own board only: a tick is your working state, so there is no --for here.",
+                "",
                 "rewrite — asks Tower to compile the page again and waits for the new version. Writing a page takes minutes, so this queues the work and watches your page rather than holding one long request open.",
                 "  --no-wait returns as soon as the ask is on the record. Waiting is the default.",
                 "  Running out of patience is not a failure and says so: the work is still going, and `cockpit brief` will show it when it lands.",

package/dist/commands/local-help.js

@@ -104,7 +104,7 @@ export function localCommandHelp(command) {
         "  cockpit project [list] [--archived] [--dashboard-url <url>] [--json]",
         `  cockpit search "<words>" [--kind ${SEARCH_KINDS.join(",")}] [--limit <n>] [--dashboard-url <url>] [--json]`,
         "  cockpit release [--dry-run] [--skip-checks] [--no-floor] [--tag <tag>] [--access <public|restricted>] [--otp <code>]",
-        "  cockpit careers [list|show <id>|rescreen <id>|invite <id>|decide <id> --decision <passed_on|archived|reopen>|grade <id> [--now]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--json]",
+        "  cockpit careers [list|show <id>|rescreen <id>|send-takehome <id>|decide <id> --decision <passed_on|archived|reopen>|grade <id> [--now]|takehome show <role>|takehome set <role> --body-file <path>|settings show|settings set --enabled <true|false>] [--role <slug>] [--min-score <n>] [--since <date>] [--stage <s>] [--json]",
         "  cockpit usage sessions [--task <BLI-NNNN> | --subject <name>] [--repo <label>] [--since <window>] [--json]",
         "  cockpit usage sessions --session <id> [--from-window <n>] [--json]",
         "  --by-topic groups work types; --by-subject groups open subjects from session summaries.",

package/dist/commands/local.js

@@ -27,6 +27,7 @@ import { runWorkbook } from "./workbook.js";
 import { runBrief } from "./brief.js";
 import { runBriefEdit } from "./brief-edit.js";
 import { runBriefRewrite } from "./brief-rewrite.js";
+import { runBriefDone } from "./brief-done.js";
 import { runCorrect } from "./correct.js";
 import { runNotes } from "./notes.js";
 import { runServe } from "./serve.js";
@@ -137,6 +138,10 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                     return await runBriefEdit(command, io);
                 if (command.action === "rewrite")
                     return await runBriefRewrite(command, io);
+                // BLI-3605: the board's done checkbox, at a terminal.
+                if (command.action === "done" || command.action === "undone") {
+                    return await runBriefDone(command, io);
+                }
                 return await runBrief(command, io);
             case "correct":
                 return await runCorrect(command, io);

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.123");
+    writeLine(io?.stdout ?? process.stdout, "0.2.125");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.123",
+  "version": "0.2.125",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.32",
-    "@bli-cockpit/mcp": "0.1.50",
+    "@bli-cockpit/mcp": "0.1.52",
     "@bli-cockpit/telemetry-core": "0.1.48"
   }
 }