@bli-cockpit/cli 0.2.122 → 0.2.124

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/careers.js

@@ -2,7 +2,8 @@ import { readFile } from 'node:fs/promises';
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from './agent-door.js';
 /**
  * `cockpit careers` — application review (BLI-3706) and, since BLI-4460, the
- * pipeline: invite, decide, the role's take-home and the four settings.
+ * pipeline: invite, decide, the role's take-home and the settings. BLI-4461
+ * added `grade`, which puts one submission back in the grader's queue.
  *
  * Every verb goes through the SAME Tower door its MCP twin calls; nothing here
  * decides policy. The take-home body arrives from a FILE rather than a flag,
@@ -41,6 +42,10 @@ async function planCareersRequest(command) {
         case 'show': return { path: application, method: 'GET' };
         case 'rescreen': return { path: `${application}/rescreen`, method: 'POST' };
         case 'invite': return { path: `${application}/invite`, method: 'POST' };
+        // The grader itself runs on Railway, because it needs a clone and yt-dlp.
+        // This door re-queues the row; `--now` is passed through and the answer
+        // names where the run actually happens rather than implying it ran here.
+        case 'grade': return { path: `${application}/grade`, method: 'POST', body: { now: command.now === true } };
         case 'decide': return { path: `${application}/decide`, method: 'POST', body: { decision: command.decision } };
         case 'takehome-show': return { path: takehomePath(command), method: 'GET' };
         case 'takehome-set': return { path: takehomePath(command), method: 'PUT', body: await takehomeBody(command) };
@@ -81,8 +86,12 @@ function settingsBody(command) {
         body.attention_min_score = command.attentionMinScore;
     if (command.inviteAccountId !== undefined)
         body.invite_account_id = command.inviteAccountId;
+    if (command.bookingLink !== undefined)
+        body.booking_link = command.bookingLink;
+    if (command.graderModel !== undefined)
+        body.grader_model = command.graderModel;
     if (Object.keys(body).length === 0) {
-        throw new Error('careers settings set needs at least one of --enabled, --auto-invite-min-score, --attention-min-score or --account.');
+        throw new Error('careers settings set needs at least one of --enabled, --auto-invite-min-score, --attention-min-score, --account, --booking-link or --grader-model.');
     }
     return body;
 }

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

@@ -1,12 +1,12 @@
 import { optionalNonEmpty, optionalUrl, parseNamedArgs } from './local-arg-values.js';
-const ACTIONS = ['list', 'show', 'rescreen', 'invite', 'decide', 'takehome-show', 'takehome-set', 'settings-show', 'settings-set'];
+const ACTIONS = ['list', 'show', 'rescreen', 'invite', 'decide', 'grade', 'takehome-show', 'takehome-set', 'settings-show', 'settings-set'];
 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'];
+const NEEDS_ID = ['show', 'rescreen', 'invite', 'decide', 'grade'];
 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'];
-    const values = parseNamedArgs(args, { allowedFlags: [...valueFlags, '--json'], valueFlags });
+    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'];
+    const values = parseNamedArgs(args, { allowedFlags: [...valueFlags, '--json', '--now'], valueFlags });
     const positionals = [...values.positionals];
     // `takehome show` and `settings set` are two words a person types and one
     // action everything downstream reads.
@@ -52,11 +52,34 @@ export function parseCareersArgs(args) {
         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'),
         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'),
     };
 }
+/**
+ * BLI-4461: a booking link goes into an email a stranger clicks, so the
+ * terminal refuses anything but https here as well as on the server. Two
+ * checks, one rule, and the local one costs no round trip.
+ */
+function httpsFlag(raw) {
+    const value = optionalUrl(raw);
+    if (value === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error('--booking-link must be an https URL.');
+    }
+    if (parsed.protocol !== 'https:')
+        throw new Error('--booking-link must be an https URL.');
+    return value;
+}
 function numberFlag(raw, flag, min, max) {
     if (raw === undefined)
         return undefined;

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,16 +25,17 @@ export const TOWER_COMMAND_HELP = [
     [
         "careers",
         [
-            "Usage: cockpit careers [list|show <id>|rescreen <id>|invite <id>|decide <id> --decision <d>|takehome show <role>|takehome set <role>|settings show|settings set] [flags]",
+            "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]",
             "",
             "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`.",
             "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.",
             "takehome set <role> [--subject <s>] [--body-file <path>] [--link <url>] [--pass-score <0-10>] — the body comes from a FILE and must keep {first_name} and {link}.",
             "settings show — the bar, the attention threshold, whether automatic sending is on, and which mailbox it goes out from.",
-            "settings set [--enabled true|false] [--auto-invite-min-score <0-100>] [--attention-min-score <0-100>] [--account <mailbox uuid>] — each takes effect on the next screening, no deploy.",
+            "settings set [--enabled true|false] [--auto-invite-min-score <0-100>] [--attention-min-score <0-100>] [--account <mailbox uuid>] [--booking-link <https url>] [--grader-model <provider:model>]: each takes effect on the next run, no deploy.",
         ],
     ],
     [

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>|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>|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 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.122");
+    writeLine(io?.stdout ?? process.stdout, "0.2.124");
     return 0;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.122",
+  "version": "0.2.124",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.32",
-    "@bli-cockpit/mcp": "0.1.49",
+    "@bli-cockpit/mcp": "0.1.51",
     "@bli-cockpit/telemetry-core": "0.1.48"
   }
 }