@bli-cockpit/cli 0.2.240 → 0.2.242

package/dist/commands/manager-hints.js

@@ -0,0 +1,88 @@
+/**
+ * What `cockpit manager` tells a person after a refusal, and the limits it tells them (BLI-5777).
+ *
+ * A leaf module (it imports nothing) so the repo-shape tests can read it without pulling in the collector. Everything here
+ * is a COPY of something the manager server owns, and the CLI cannot import the server:
+ *
+ *   - `MANAGER_LIMITS_COPY` and `LONG_OVERDUE_DAYS_COPY`: the server's `TOWER_MANAGER_SUMMARY_LIMITS` and `SUMMARY_LONG_OVERDUE_DAYS`;
+ *   - `SUMMARY_REFUSAL_NAMES`: the server's `TOWER_MANAGER_SUMMARY_REFUSALS`, same names in the same order;
+ *   - `ITEM_REFUSAL_NAMES`: the server's `ReviewRefusal` (`db/review.ts`) and `item_busy`, less `not_found` (the `not_found` reason answers it);
+ *   - `READ_ONLY_REFUSAL_NAMES`: the door's `ReadOnlyRefusalReason`.
+ *
+ * `apps/dashboard/src/repo-shape/manager-copies.test.ts` fails the moment a copy differs from the server's, and each hint map
+ * is typed against its own name list (`satisfies Record<…>`), so a name added to the list without a hint fails `tsc`.
+ * A new module like this one joins `scripts/build-public-cli.mjs` `runtimeFiles` or the packed CLI breaks while the tests stay green.
+ */
+export const MANAGER_LIMITS_COPY = { headlineMax: 140, bulletsMinPerson: 1, bulletsMax: 5, bulletMax: 160, nextMax: 200, blockerMax: 200 };
+/** More than this many days past due, an open action makes the card at risk: a copy of the server's `SUMMARY_LONG_OVERDUE_DAYS`. */
+export const LONG_OVERDUE_DAYS_COPY = 14;
+const L = MANAGER_LIMITS_COPY;
+export const SUMMARY_REFUSAL_NAMES = [
+    "summary_changed", "summary_empty", "summary_incomplete", "summary_health_invalid", "summary_headline_empty", "summary_headline_too_long",
+    "summary_bullets_count", "summary_bullet_empty", "summary_bullet_too_long", "summary_bullet_date_invalid", "summary_next_too_long",
+    "summary_blocker_too_long", "summary_blocked_needs_blocker", "summary_blocker_needs_blocked",
+];
+/** The way forward after each named refusal of a "Where we are" edit; `home` is the ready-to-run `cockpit manager home <client> --json`. */
+export function summaryHints(home) {
+    // A hint is the next step in this terminal's own words (the flag to pass, the command to run). It never says the server's sentence again.
+    return {
+        summary_changed: `Read the card again with ${home} and retry with its summary.updatedAt as --version (none only when it has no card).`,
+        summary_empty: "Pass at least one of --health, --headline, --bullet, --next, --blocker.",
+        summary_incomplete: "Pass --health, --headline and --bullet together, with --version none.",
+        summary_health_invalid: "Pass --health with one of those words, in lower case with underscores.",
+        summary_headline_empty: "A blank or invisible-only --headline counts as empty.",
+        summary_headline_too_long: `Shorten --headline: the limit (${L.headlineMax}) counts characters, not bytes.`,
+        summary_bullets_count: "Each --bullet is one bullet, and together they replace the whole list.",
+        summary_bullet_empty: "Put words after a --bullet's date, when it has one.",
+        summary_bullet_too_long: `Shorten the long --bullet (the limit is ${L.bulletMax}).`,
+        summary_bullet_date_invalid: "Start a dated --bullet with \"YYYY-MM-DD: \" and a real day.",
+        summary_next_too_long: `Shorten --next (the limit is ${L.nextMax}).`,
+        summary_blocker_too_long: `Shorten --blocker (the limit is ${L.blockerMax}).`,
+        summary_blocked_needs_blocker: "Add --blocker <what blocks it>, or pass another --health.",
+        summary_blocker_needs_blocked: "Add --health blocked, or leave --blocker out (`--blocker none` clears the stored one).",
+    };
+}
+export const ITEM_REFUSAL_NAMES = [
+    "item_changed", "item_busy", "item_archived", "item_not_archived", "item_dismissed", "person_item_not_dismissable",
+    "no_proposal", "proposal_replaced", "timeline_not_live", "request_reused", "proposal_decided", "proposal_not_addable",
+];
+/** Refusals that mean "the item is not as you last saw it": reading it again is the way forward. */
+export const RESEEN_REFUSALS = new Set(["item_changed", "item_busy", "proposal_decided", "no_proposal"]);
+/** The way forward after each named refusal of an item write. `flag` is " --timeline" for a timeline item, else "". */
+export function itemHints(id, flag) {
+    const reread = `Run \`cockpit manager show ${id}${flag}\` for the current version.`;
+    return {
+        item_changed: reread,
+        item_busy: reread,
+        no_proposal: reread,
+        proposal_decided: reread,
+        // The request id IS the item's id (an add made it): show it; a retry already made it, and a different item needs no request id.
+        request_reused: "The request id is that item's id: `cockpit manager show <request-id>` shows it. If you were retrying an add, it is already there: don't add it again. To add a different item, run the add without --request-id.",
+        proposal_replaced: `Run \`cockpit manager show ${id}${flag}\` to see the suggested changes waiting and their ids.`,
+        proposal_not_addable: `Run \`cockpit manager proposal ${id} <proposal-id> accept --version <v>\` (or dismiss).`,
+        item_archived: `Bring it back with \`cockpit manager unarchive ${id}${flag} --version <v>\` (\`list <client>${flag} --archived\` prints its version).`,
+        item_dismissed: `Run \`cockpit manager approve ${id}${flag} --version <v> --restore\` (\`list <client>${flag} --review dismissed\` prints its version).`,
+        person_item_not_dismissable: `Run \`cockpit manager archive ${id}${flag} --version <v>\`.`,
+        timeline_not_live: "`cockpit manager list <client> --timeline` lists the client's live timeline items.",
+        item_not_archived: "Nothing to bring back: it is in the lists already.",
+    };
+}
+/**
+ * The door's own refusals of a read-only device token (`ReadOnlyRefusalReason`): they reach the terminal as the `reason`
+ * (BLI-5777; before, the 403 carried no name and the CLI printed `http_403`).
+ */
+export const READ_ONLY_REFUSAL_NAMES = ["read_only_device_cannot_write", "read_only_device_door_not_listed", "read_only_device_on_admin"];
+export const READ_ONLY_HINTS = {
+    read_only_device_cannot_write: " Sign in as the person who is asking with `cockpit login`.",
+    read_only_device_door_not_listed: " A brain session's key may not read Tower Manager: sign in as the person who is asking with `cockpit login`.",
+    read_only_device_on_admin: " Mint the read-only key for a member instead.",
+};
+/** A read's workflow id (`sched_wf_…`, `wf-…`): what `lastRead.workflowRunId` holds in `client --json` and `home --json`. It is not a run's receipt id. */
+export const looksLikeWorkflowId = (value) => /^(?:[a-z]+_)?wf[-_]/i.test(value);
+/** Where a run's receipt id really comes from, for the refusal of anything else (`run <run-id>`). */
+export function runIdRefusal(value) {
+    const where = "A run id looks like 8f14e45f-ceea-467a-9575-1d3a4e7b2c10. It comes from `cockpit manager queue <client> --json` (a row's changedByRunId), `cockpit manager show <id>` (a suggested change's runId) or `cockpit manager client <client> --json` (lastBriefRebuild.runId); `list` does not print run ids.";
+    return looksLikeWorkflowId(value)
+        ? `That is a read's workflow id (the lastRead.workflowRunId that \`client --json\` and \`home --json\` print), not a run's receipt id. ${where}`
+        : where;
+}

package/dist/commands/manager-limits.json

@@ -0,0 +1,269 @@
+{
+  "schema": 1,
+  "about": "Tower Manager's limits, rules and refusal names, generated from the manager server's constants (apps/dashboard/src/repo-shape/manager-limits-lib.ts). A skill or doc that quotes a number or a refusal name checks it against this list.",
+  "limits": [
+    {
+      "id": "addDetailCut",
+      "value": 200,
+      "unit": "characters",
+      "source": "the CLI's manager-render.ts savedTextLines: an add prints its detail cut to 200 characters (a display cut, not a server limit)"
+    },
+    {
+      "id": "attentionPart",
+      "value": 25,
+      "unit": "items",
+      "source": "TOWER_MANAGER_ATTENTION_PART_LIMIT"
+    },
+    {
+      "id": "blockerMax",
+      "value": 200,
+      "unit": "characters",
+      "source": "TOWER_MANAGER_SUMMARY_LIMITS.blockerMax"
+    },
+    {
+      "id": "bulletMax",
+      "value": 160,
+      "unit": "characters",
+      "source": "TOWER_MANAGER_SUMMARY_LIMITS.bulletMax"
+    },
+    {
+      "id": "bulletsMax",
+      "value": 5,
+      "unit": "bullets",
+      "source": "TOWER_MANAGER_SUMMARY_LIMITS.bulletsMax"
+    },
+    {
+      "id": "bulletsMin",
+      "value": 1,
+      "unit": "bullets",
+      "source": "TOWER_MANAGER_SUMMARY_LIMITS.bulletsMinPerson"
+    },
+    {
+      "id": "comingUp",
+      "value": 20,
+      "unit": "items",
+      "source": "TOWER_MANAGER_HOME_LIMITS.comingUp"
+    },
+    {
+      "id": "headlineMax",
+      "value": 140,
+      "unit": "characters",
+      "source": "TOWER_MANAGER_SUMMARY_LIMITS.headlineMax"
+    },
+    {
+      "id": "inTowerDays",
+      "value": 7,
+      "unit": "days",
+      "source": "TOWER_MANAGER_IN_TOWER_DAYS"
+    },
+    {
+      "id": "inTowerItems",
+      "value": 50,
+      "unit": "items",
+      "source": "TOWER_MANAGER_IN_TOWER_LIMIT"
+    },
+    {
+      "id": "listRows",
+      "value": 500,
+      "unit": "rows",
+      "source": "db/items.ts LIST_LIMIT"
+    },
+    {
+      "id": "longOverdueDays",
+      "value": 14,
+      "unit": "days",
+      "source": "SUMMARY_LONG_OVERDUE_DAYS"
+    },
+    {
+      "id": "needsAttention",
+      "value": 50,
+      "unit": "items",
+      "source": "TOWER_MANAGER_HOME_LIMITS.needsAttention"
+    },
+    {
+      "id": "needsAttentionDays",
+      "value": 7,
+      "unit": "days",
+      "source": "db/home.ts: due_at <= today + 6, so today and six days ahead (a window of 7 days)"
+    },
+    {
+      "id": "nextMax",
+      "value": 200,
+      "unit": "characters",
+      "source": "TOWER_MANAGER_SUMMARY_LIMITS.nextMax"
+    },
+    {
+      "id": "pageDefault",
+      "value": 50,
+      "unit": "rows",
+      "source": "MANAGER_LIST_PAGE.default (the MCP list tools' own default)"
+    },
+    {
+      "id": "pageMax",
+      "value": 200,
+      "unit": "rows",
+      "source": "MANAGER_LIST_PAGE.max (the MCP list tools' own cap)"
+    },
+    {
+      "id": "sourceNoteMax",
+      "value": 1000,
+      "unit": "characters",
+      "source": "routes/validation.ts: sourceNote .max(1000, ...)"
+    },
+    {
+      "id": "whatChanged",
+      "value": 100,
+      "unit": "items",
+      "source": "TOWER_MANAGER_HOME_LIMITS.whatChanged"
+    }
+  ],
+  "rules": [
+    {
+      "id": "long_overdue_makes_card_at_risk",
+      "text": "An open action more than 14 days past its due date (Tower's today, America/Vancouver) makes the card at_risk, or blocked with a named blocker; never on_track."
+    },
+    {
+      "id": "blocker_only_on_blocked",
+      "text": "A blocker goes only on a Blocked card: a blocker sent with any other health is refused (summary_blocker_needs_blocked), and sending only a new health drops the stored one; blocked always has a blocker."
+    },
+    {
+      "id": "every_item_write_names_its_version",
+      "text": "Every write on an existing item names the version (updatedAt) it last read; a stale one is refused by name and nothing is written."
+    }
+  ],
+  "refusals": {
+    "summary": [
+      "summary_changed",
+      "summary_empty",
+      "summary_incomplete",
+      "summary_health_invalid",
+      "summary_headline_empty",
+      "summary_headline_too_long",
+      "summary_bullets_count",
+      "summary_bullet_empty",
+      "summary_bullet_too_long",
+      "summary_bullet_date_invalid",
+      "summary_next_too_long",
+      "summary_blocker_too_long",
+      "summary_blocked_needs_blocker",
+      "summary_blocker_needs_blocked"
+    ],
+    "item": [
+      "item_archived",
+      "item_busy",
+      "item_changed",
+      "item_dismissed",
+      "item_not_archived",
+      "no_proposal",
+      "person_item_not_dismissable",
+      "proposal_decided",
+      "proposal_not_addable",
+      "proposal_replaced",
+      "request_reused",
+      "timeline_not_live"
+    ],
+    "owner": [
+      "owner_already_merged",
+      "owner_changed",
+      "owner_has_aliases",
+      "owner_not_merged",
+      "owner_same",
+      "owner_target_merged",
+      "owner_unknown"
+    ],
+    "read_only_door": [
+      "read_only_device_cannot_write",
+      "read_only_device_door_not_listed",
+      "read_only_device_on_admin"
+    ],
+    "door": [
+      "inference_not_configured",
+      "manager_body_too_large",
+      "manager_body_unreadable",
+      "manager_operation_not_on_this_door",
+      "manager_path_malformed",
+      "manager_role_denied",
+      "manager_route_not_found",
+      "manager_timeout",
+      "manager_unreachable",
+      "team_lookup_failed",
+      "team_membership_required"
+    ]
+  },
+  "refusalPrefixes": [
+    "summary_",
+    "item_",
+    "proposal_",
+    "owner_",
+    "read_only_device_",
+    "request_",
+    "manager_",
+    "team_",
+    "timeline_not_",
+    "person_item_",
+    "no_proposal"
+  ],
+  "tools": [
+    "archived",
+    "blocker",
+    "bullets",
+    "client_id",
+    "date",
+    "decision",
+    "detail",
+    "due",
+    "expected_updated_at",
+    "headline",
+    "health",
+    "item_id",
+    "kind",
+    "limit",
+    "manager_add",
+    "manager_approve",
+    "manager_archive",
+    "manager_client",
+    "manager_clients",
+    "manager_dismiss",
+    "manager_done",
+    "manager_drop",
+    "manager_edit",
+    "manager_home",
+    "manager_link",
+    "manager_list",
+    "manager_proposal",
+    "manager_queue",
+    "manager_reopen",
+    "manager_run",
+    "manager_set_summary",
+    "manager_show",
+    "manager_unarchive",
+    "meeting_id",
+    "needs_review",
+    "next",
+    "no_owner",
+    "overdue",
+    "owner",
+    "owner_name",
+    "owners",
+    "proposal_id",
+    "request_id",
+    "restore",
+    "review",
+    "run_id",
+    "search",
+    "source_note",
+    "source_url",
+    "status",
+    "timeline",
+    "title",
+    "version"
+  ],
+  "doorRefusedOperations": [
+    "create_client",
+    "merge_owner",
+    "rebuild_brief",
+    "sync_all",
+    "sync_client",
+    "unmerge_owner"
+  ]
+}

package/dist/commands/manager-read-reasons.js

@@ -0,0 +1,78 @@
+/**
+ * Why a read or a summary check stopped, in the words the manager page uses (`REASON_SENTENCES` in
+ * `apps/dashboard/src/app/(cockpit)/manager/manager-client-bar.tsx`, BLI-5777 batch 4). The CLI used to print the raw
+ * label ("notion_root_unreadable"). `manager-reason-words.test.ts` (dashboard repo-shape) fails when a reason the
+ * server can write has no sentence here, or when a sentence here is not the page's.
+ */
+export const READ_REASON_SENTENCES = {
+    running: "Still running.",
+    ok: "Finished.",
+    client_locked: "Another run was already reading this client, so this one stood aside.",
+    client_not_found: "This client no longer exists.",
+    client_disabled: "This client is disabled.",
+    notion_not_configured: "Notion is not connected on this Tower deployment.",
+    notion_root_unreadable: "Tower cannot read this client's Notion page. Share it with the Tower Manager Dashboard integration again, then sync.",
+    notion_unavailable: "Notion did not answer. The next sync will try again.",
+    model_failed: "The model did not answer. Nothing was lost; the next sync reads the same pages again.",
+    model_timeout: "The model took too long to answer. Nothing was lost; the next sync reads the same pages again, fewer at a time.",
+    model_output_rejected: "The model's answer was not usable. Nothing was lost; the next sync reads the same pages again.",
+    root_owned_by_other_client: "This client's Notion page sits inside another client's tree, which holds it. Nothing was read.",
+    interrupted: "Interrupted when Tower restarted; will retry. The daily sync carries it on, or Sync now.",
+    batch_too_dense: "Those pages held more than one answer can carry, so they are being read again in smaller batches.",
+    database_error: "Tower could not save the result. The next sync will try again.",
+    unexpected_error: "The run stopped on an unexpected error. The next sync will try again.",
+};
+/** The page's sentence for a reason, with the label beside it so an agent can name it; an unknown label is printed as it is. */
+export function readReasonText(reason) {
+    const sentence = READ_REASON_SENTENCES[reason];
+    return sentence ? `${sentence} (${reason})` : reason;
+}
+/**
+ * Why the AI's answer for a "Where we are" card was not used, in words (BLI-5777): every refusal name a summary check can record (the
+ * answer reader's `SummaryAnswerRefusal`, and the card's own `TOWER_MANAGER_SUMMARY_REFUSALS`). `manager-cli-mcp-rules.test.ts` fails
+ * when a name the server has no words here, so a new refusal cannot ship as a bare code.
+ */
+export const SUMMARY_REFUSAL_WORDS = {
+    not_an_answer: "it was not a card at all",
+    health_invalid: "its health was none of on_track, at_risk, blocked",
+    headline_empty: "it had no headline",
+    bullets_empty: "it had no bullets",
+    summary_changed: "the card was changed after the version the edit named",
+    summary_empty: "there was nothing to change",
+    summary_incomplete: "a first card needs health, headline and a bullet",
+    summary_health_invalid: "its health was none of on_track, at_risk, blocked",
+    summary_headline_empty: "the headline was empty",
+    summary_headline_too_long: "the headline was over 140 characters",
+    summary_bullets_count: "too many or too few bullets",
+    summary_bullet_empty: "a bullet had no words",
+    summary_bullet_too_long: "a bullet was over 160 characters",
+    summary_bullet_date_invalid: "a bullet's date was not a real day",
+    summary_next_too_long: "next was over 200 characters",
+    summary_blocker_too_long: "the blocker was over 200 characters",
+    summary_blocked_needs_blocker: "blocked with no blocker",
+    summary_blocker_needs_blocked: "a blocker on a card that is not blocked",
+};
+/** Why a summary check kept the card that was there instead of writing one (the receipt's `kept_reason`), in words. */
+export const SUMMARY_KEPT_WORDS = {
+    model_call_failed: "the model call failed, so the card that was there stays",
+    model_answer_refused: "the AI's answer was refused, so the card that was there stays",
+    card_changed_meanwhile: "someone wrote the card while the check ran, so theirs stays; it is newer",
+};
+/** "The AI's answer broke a card rule (too many or too few bullets: summary_bullets_count), so it was not used." The name stays after the words. */
+export function summaryRefusalText(refusal) {
+    const words = SUMMARY_REFUSAL_WORDS[refusal];
+    return words ? `The AI's answer broke a card rule (${words}: ${refusal}), so it was not used.` : `The AI's answer was refused (${refusal}), so it was not used.`;
+}
+/** "the model call failed, so the card that was there stays (model_call_failed)"; an unknown reason is said as it is. */
+export function keptReasonText(reason) {
+    const words = SUMMARY_KEPT_WORDS[reason];
+    return words ? `${words} (${reason})` : reason;
+}
+/** What started a summary check (the receipt's `trigger`), in words; an unknown one is said as it is. */
+export const SUMMARY_TRIGGER_WORDS = {
+    read: "a read",
+    brief_rebuild: "Rebuild brief",
+};
+export function summaryTriggerText(trigger) {
+    return SUMMARY_TRIGGER_WORDS[trigger] ?? trigger;
+}