@bli-cockpit/cli 0.2.240 → 0.2.241

package/dist/commands/manager.js

@@ -5,7 +5,7 @@
  * them, adds and edits them, ticks them off, links an action to the meeting it came from, and
  * decides the AI's suggestions, the same things the manager page does.
  *
- * Eighteen verbs (`home` and `summary`, BLI-5698: a client's Home and its "Where we are" card), each one `/api/manager` door on this machine's device token, the same door the MCP
+ * Nineteen verbs (`home` and `summary`, BLI-5698: a client's Home and its "Where we are" card), each one `/api/manager` door on this machine's device token, the same door the MCP
  * twins (`manager_*`) use; the door passes Railway's answer through unchanged. Every write on an
  * existing item carries `--version`, the item's `updatedAt` as `list`/`show` print it: a stale one is
  * refused with the door's own sentence and nothing is written. `approve`, `dismiss` and `proposal`
@@ -16,8 +16,11 @@ import { randomUUID } from "node:crypto";
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
 import { colorEnabled, writeLine } from "./cli-io.js";
 import { localCommandHelp } from "./local-help.js";
-import { clientDetailLines, clientLines, itemDetailLines, itemRowLines, runLines, listLines, queueLines, } from "./manager-render.js";
+import { savedTextLines, clientDetailLines, clientLines, itemDetailLines, itemRowLines, runLines, listLines, queueLines, } from "./manager-render.js";
 import { homeLines, summaryWrittenLines } from "./manager-render-home.js";
+import { parseManagerArgs } from "./local-args-tower-manager.js";
+import { READ_ONLY_HINTS, RESEEN_REFUSALS, itemHints, summaryHints } from "./manager-hints.js";
+import { readFieldsText } from "./manager-fields-file.js";
 import { planManagerRequest } from "./manager-requests.js";
 const TAG = "[manager cli]";
 /**
@@ -26,12 +29,38 @@ const TAG = "[manager cli]";
  * giving up first while the write may still land.
  */
 export const MANAGER_DEADLINE_MS = 65_000;
-const staleHint = (id, timeline) => `Run \`cockpit manager show ${id}${timeline ? " --timeline" : ""}\` for the current version and try again.`;
-/** Refusals that mean "the item is not as you last saw it": reading it again is the way forward. */
 /** The verbs that change an existing item. */
-const WRITES = new Set(["summary", "edit", "done", "reopen", "link", "approve", "dismiss", "proposal", "archive", "unarchive"]);
-const RESEEN_REFUSALS = new Set(["item_changed", "item_busy", "proposal_decided", "no_proposal"]);
-export async function runManager(command, io) {
+const WRITES = new Set(["summary", "edit", "done", "drop", "reopen", "link", "approve", "dismiss", "proposal", "archive", "unarchive"]);
+/**
+ * `--fields-file`: the parser left the fields unread. Read the file (or stdin), and parse the same args again with its text,
+ * so the file's values get exactly the flags' checks. Nothing has touched the network yet, so a bad file costs nothing.
+ */
+async function withFieldsFile(command, io) {
+    if (command.fieldsFile === undefined || command.rawArgs === undefined)
+        return command;
+    const source = command.fieldsFile === "-" ? "stdin" : "file";
+    try {
+        const text = await readFieldsText(command.fieldsFile, io);
+        const parsed = parseManagerArgs(command.rawArgs, { fieldsText: text });
+        writeLine(io.stderr, `${TAG} fields read ${JSON.stringify({ source, bytes: Buffer.byteLength(text, "utf8"), verb: command.action })}`);
+        const { fieldsFile: _file, rawArgs: _args, ...rest } = parsed;
+        return { ...rest, homeDir: command.homeDir, dashboardUrl: command.dashboardUrl, json: command.json };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "the fields file could not be read";
+        writeLine(io.stderr, `${TAG} refused ${JSON.stringify({ reason: "fields_file_invalid", source, verb: command.action })}`);
+        if (command.json)
+            writeLine(io.stdout, JSON.stringify({ ok: false, error: "fields_file_invalid", detail }));
+        else
+            writeLine(io.stderr, detail);
+        return 1;
+    }
+}
+export async function runManager(given, io) {
+    const loaded = await withFieldsFile(given, io);
+    if (typeof loaded === "number")
+        return loaded;
+    const command = loaded;
     if (command.help) {
         writeLine(io.stderr, `${TAG} help printed ${JSON.stringify({ reason: "no_verb_or_help_asked" })}`);
         writeLine(io.stdout, localCommandHelp("manager"));
@@ -107,12 +136,14 @@ function renderAnswer(command, body, color) {
         case "home": return homeLines(body, command.client ?? "<client>", color);
         case "summary": return summaryWrittenLines(body, color);
         case "run": return runLines(body);
-        case "list": return listLines(body, timeline, color);
+        case "list": return listLines(body, timeline, color, new Date(), command.archived !== true && command.review !== "rejected", command.ownerFilter !== undefined || command.noOwner === true);
         case "queue": return queueLines(body, color);
         case "show": return itemDetailLines(body, timeline, color);
-        default: return [...writeSentence(command, body), ...itemRowLines(body.item, timeline, color)];
+        default: return [...writeSentence(command, body), ...itemRowLines(body.item, timeline, color), ...(command.action === "add" ? savedTextLines(body) : [])];
     }
 }
+/** An add answered `created: false`: the same request id came back, so the item that already existed is returned. */
+const ALREADY_ADDED = "Already added earlier under this request id; nothing new was written.";
 /** What a write did, in one sentence a person reads; the item's new version follows on its row. */
 function writeSentence(command, body) {
     const as = "as you";
@@ -120,10 +151,14 @@ function writeSentence(command, body) {
     const waiting = body.item?.proposedChanges?.length ?? 0;
     const queue = waiting === 0 ? "It leaves the review queue." : `${waiting === 1 ? "Its other suggested change still waits" : `Its ${waiting} other suggested changes still wait`} in the review queue.`;
     switch (command.action) {
-        case "add": return [command.timeline && !command.occurredAt ? "Added. It has no date, so it sits in \"Needs a date\"." : "Added."];
-        case "edit": return ["Saved your changes."];
+        // Only an explicit `created: false` is "not created": an older server sends no field, and that add did write.
+        case "add": return body.created === false ? [ALREADY_ADDED] : [command.timeline && !command.occurredAt ? "Added. It has no date, so it sits in \"Needs a date\"." : "Added."];
+        // Railway writes nothing when every field already equals the stored one: no new version, no reviewed mark.
+        case "edit": return [body.unchanged === true ? "No change; nothing was written." : "Saved your changes."];
         // Railway writes nothing when the action already has that status, so its version comes back unchanged.
         case "done": return [body.item?.updatedAt === command.version ? "Already done; nothing changed." : "Marked done."];
+        // A dropped action was not done. Railway writes nothing when it is already dropped (`unchanged: true`).
+        case "drop": return [body.unchanged === true || body.item?.updatedAt === command.version ? "No change; nothing was written." : `Dropped: ${body.item?.title ?? "that action"}.`];
         case "reopen": return [body.item?.updatedAt === command.version ? "Already open; nothing changed." : "Reopened."];
         case "link": return [command.timelineItemId ? `Linked to ${body.timelineItem?.title ?? "that meeting"}.` : "Unlinked from its meeting."];
         case "approve": return [command.restore ? `Restored: ${body.item?.title ?? "that item"}, back in the lists and marked reviewed by you.` : `Approved ${as}. ${queue.replace("other ", "")}`];
@@ -170,7 +205,7 @@ function nextStep(reason, refusal, command) {
     if (reason === "not_found" && command?.id) {
         return command.timeline
             ? " Check the id with `cockpit manager list <client> --timeline`; for an action, drop --timeline."
-            : ` Check the id with \`cockpit manager list <client>\`; for a timeline item, add --timeline${command.action === "done" || command.action === "reopen" || command.action === "link" ? " (done, reopen and link are for actions only)" : ""}.`;
+            : ` Check the id with \`cockpit manager list <client>\`; for a timeline item, add --timeline${command.action === "done" || command.action === "drop" || command.action === "reopen" || command.action === "link" ? " (done, drop, reopen and link are for actions only)" : ""}.`;
     }
     // A client-level command (home, summary, client, list, queue, add) the door cannot find the client of: "That client does not exist".
     if (reason === "not_found" && !command?.id && command?.action !== "run")
@@ -183,26 +218,30 @@ function nextStep(reason, refusal, command) {
     if ((reason === "manager_unreachable" || reason === "manager_timeout") && (command === undefined || !WRITES.has(command.action) && command.action !== "add")) {
         return " Try again in a minute; if it keeps failing, Tower's manager server may be down.";
     }
-    switch (refusal) {
-        // Another person's or another client's add already used this id: a fresh one makes the item.
-        case "request_reused": return " Run the add again without --request-id to make a new item.";
-        case "proposal_replaced": return ` Run \`cockpit manager show ${id}${flag}\` to see the suggested changes waiting and their ids.`;
-        case "item_archived": return ` Bring it back first: \`cockpit manager unarchive ${id}${flag} --version <v>\` (\`list <client>${flag} --archived\` prints its version).`;
-        case "item_dismissed": return ` Restore it first: \`cockpit manager approve ${id}${flag} --version <v> --restore\` (\`list <client>${flag} --review dismissed\` prints its version).`;
-        case "person_item_not_dismissable": return ` To delete an item a person added, use \`cockpit manager archive ${id}${flag} --version <v>\`.`;
-        case "timeline_not_live": return " Link to a live timeline item of the same client: `cockpit manager list <client> --timeline` lists them.";
-        case "item_not_archived": return " It is already in the lists; nothing to bring back.";
-        default: return "";
-    }
+    // The door's own 403 for a read-only key names itself as the reason.
+    const readOnly = READ_ONLY_HINTS[reason];
+    if (readOnly)
+        return readOnly;
+    const hint = refusal ? itemHints(id, flag)[refusal] : undefined;
+    return hint ? ` ${hint}` : "";
 }
 function refuse(door, answer, command, requestId) {
     const body = answer.body && typeof answer.body === "object" ? answer.body : {};
     const text = (value) => (typeof value === "string" && value.trim() !== "" ? value : undefined);
-    const sentence = text(body["message"]) ?? (text(body["reason"]) ? text(body["error"]) : undefined) ?? answer.detail;
     const refusal = text(body["refusal"]);
+    // `--version none` says "this client has no card yet": a card that exists is the only way the version check can refuse it, and
+    // the server's own sentence ("Someone changed this card after you opened it") would send the person looking for a change nobody made.
+    const cardExists = refusal === "summary_changed" && command?.action === "summary" && command.version === null;
+    // An older Tower server's status door takes only done and open: its 400 for "dropped" is a schema message, not a way forward.
+    const noDrop = command?.action === "drop" && answer.httpStatus === 400 && refusal === undefined;
+    const sentence = noDrop
+        ? "This Tower server can't drop actions yet; mark it done with a dated line saying why, or ask for a server update."
+        : cardExists
+            ? `This client already has a card: pass its version (\`cockpit manager home ${clientWord(command)}\` shows it).`
+            : text(body["message"]) ?? (text(body["reason"]) ? text(body["error"]) : undefined) ?? answer.detail;
     const reseen = answer.reason === "invalid_state" && (refusal === undefined || RESEEN_REFUSALS.has(refusal));
-    const hint = reseen && command?.id
-        ? ` ${staleHint(command.id, command.timeline)}`
+    const hint = cardExists || noDrop ? "" : reseen && command?.id
+        ? ` ${itemHints(command.id, command.timeline ? " --timeline" : "").item_changed}`
         : nextStep(answer.reason, refusal, command);
     // An add with no answer from Tower (or a server error) may or may not have been made: the same request id makes the retry safe.
     const unconfirmed = requestId !== undefined && (answer.httpStatus === undefined || answer.httpStatus >= 500);
@@ -222,24 +261,9 @@ function refuse(door, answer, command, requestId) {
     return failAgentDoor(door, TAG, answer.reason, `${sentence}${stop}${hint}${retry}`, { ...(refusal ? { refusal } : {}), ...(unconfirmed ? { requestId } : {}) });
 }
 const clientWord = (command) => (command.client && /\s/.test(command.client) ? `"${command.client}"` : command.client ?? "<client>");
-/** The way forward after each named refusal of a "Where we are" edit (`TOWER_MANAGER_SUMMARY_REFUSALS`). */
+/** The way forward after each named refusal of a "Where we are" edit (`TOWER_MANAGER_SUMMARY_REFUSALS`, `manager-hints.ts`). */
 function summaryHint(refusal, command) {
     const home = `\`cockpit manager home ${clientWord(command)} --json\``;
-    const hints = {
-        summary_changed: `Someone or the check wrote the card since: read it again with ${home} and retry with its summary.updatedAt as --version (none only when it has no card).`,
-        summary_empty: "Give at least one of --health, --headline, --bullet, --next, --blocker.",
-        summary_incomplete: "This client has no card yet: give --health, --headline and at least one --bullet together (with --version none).",
-        summary_health_invalid: "--health is on_track, at_risk or blocked.",
-        summary_headline_empty: "Give the headline some words.",
-        summary_headline_too_long: "Keep --headline to 140 characters.",
-        summary_bullets_count: "Give 1 to 5 --bullet flags; together they replace the whole list.",
-        summary_bullet_empty: "Every --bullet needs words (after its date, when it has one).",
-        summary_bullet_too_long: "Keep each --bullet to 160 characters.",
-        summary_bullet_date_invalid: "Start a dated bullet with a real day, \"YYYY-MM-DD: \", or leave the date out.",
-        summary_next_too_long: "Keep --next to 200 characters.",
-        summary_blocker_too_long: "Keep --blocker to 200 characters.",
-        summary_blocked_needs_blocker: "blocked needs a blocker: add --blocker <what blocks it>, or pick another --health.",
-    };
-    const hint = hints[refusal];
+    const hint = summaryHints(home)[refusal];
     return hint ? ` ${hint}` : ` Read the card with ${home} and try again.`;
 }

package/dist/commands/public-root.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.240",
+  "version": "0.2.241",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.70",
-    "@bli-cockpit/mcp": "0.1.145",
+    "@bli-cockpit/mcp": "0.1.146",
     "@bli-cockpit/telemetry-core": "0.1.77"
   },
   "repository": {