@bli-cockpit/cli 0.2.57 → 0.2.59

package/dist/commands/ops-render-memory.js

@@ -0,0 +1,76 @@
+/**
+ * How the BLI Memory adoption gauge reads in a terminal (BLI-3729). Pure
+ * layout: no io, no network, no clock of its own — the sibling of
+ * `ops-render.ts`, split out to keep both under the repo's readability band
+ * (`repo-shape/file-size-ratchet.test.ts`).
+ *
+ * Same rule as the fleet and coverage sections next door: every SENTENCE was
+ * written on the server (`lib/ops/memory-usage.ts`) and is printed verbatim;
+ * this file decides column widths and order and nothing else.
+ *
+ * Both public names are re-exported from `./ops-render.js`, so a caller of that
+ * module never has to know the split happened.
+ */
+/**
+ * Is the org using BLI Memory? One row per person, one column per day, and the
+ * two agent sources counted apart from the import — an imported row is a
+ * backfill and must never be read as somebody using the thing.
+ */
+export function renderMemoryUsage(memory, dim) {
+    const lines = ["", `MEMORY  ${memory.summary ?? "(no summary)"}`];
+    if (memory.readError) {
+        lines.push(`  usage could not be read (${memory.readError}); nothing is known about whether anybody is using BLI Memory`);
+        return lines;
+    }
+    const days = memory.days ?? [];
+    const people = memory.people ?? [];
+    if (people.length === 0) {
+        lines.push(dim("  nobody on the roster has any memory activity to show"));
+        return lines;
+    }
+    const nameWidth = Math.max(6, ...people.map((person) => (person.displayName ?? "").length));
+    // `MM-DD` per column: the year is the same on every one of seven days and
+    // spending four characters on it costs the terminal a column per day.
+    const header = `  ${"person".padEnd(nameWidth)}  ` +
+        days.map((day) => day.slice(5).padStart(5)).join(" ") +
+        `  ${"mcp".padStart(5)} ${"hook".padStart(5)} ${"impt".padStart(5)}`;
+    lines.push(dim(header));
+    // Most active first, so the answer to "who is using it" is the top of the
+    // list; the unattributed bucket sinks to the bottom whatever its total,
+    // because it is not a person and its number is mostly the import.
+    const ranked = [...people].sort((left, right) => {
+        const leftOrphan = left.personId === null || left.personId === undefined ? 1 : 0;
+        const rightOrphan = right.personId === null || right.personId === undefined ? 1 : 0;
+        if (leftOrphan !== rightOrphan)
+            return leftOrphan - rightOrphan;
+        return agentSaves(right.counts) - agentSaves(left.counts);
+    });
+    for (const person of ranked) {
+        const byDay = new Map((person.days ?? []).map((entry) => [entry.day ?? "", entry]));
+        const cells = days
+            .map((day) => {
+            const entry = byDay.get(day);
+            const saved = agentSaves(entry?.counts);
+            // A zero prints as `·`, not `0`: seven zeroes in a row is the shape a
+            // reader is scanning for, and seven `0`s hide it in the noise.
+            return (saved === 0 ? "·" : String(saved)).padStart(5);
+        })
+            .join(" ");
+        const counts = person.counts ?? {};
+        const row = `  ${(person.displayName ?? "?").padEnd(nameWidth)}  ${cells}  ` +
+            `${String(counts.mcp ?? 0).padStart(5)} ${String(counts.stop_hook ?? 0).padStart(5)} ` +
+            `${String(counts.import ?? 0).padStart(5)}`;
+        lines.push(agentSaves(counts) > 0 ? row : dim(row));
+    }
+    if (memory.truncated) {
+        lines.push(dim("  this read stopped at its page cap, so every number above is a FLOOR — it can understate use and never invent it"));
+    }
+    if (memory.searches?.counted === false) {
+        lines.push(dim(`  searches are not counted (${memory.searches.reason ?? "no ledger"}): nothing in Tower records one, so this is saves only`));
+    }
+    return lines;
+}
+/** The two sources that mean a PERSON's agent used memory. Never the import. */
+function agentSaves(counts) {
+    return (counts?.mcp ?? 0) + (counts?.stop_hook ?? 0);
+}

package/dist/commands/ops-render.js

@@ -12,6 +12,7 @@
  * artifact does and does not prove — because that is exactly the moment
  * somebody is about to conclude something from it.
  */
+export { renderMemoryUsage } from "./ops-render-memory.js";
 /** The word a person reads. Short, fixed width, and never a bare colour. */
 export function verdictWord(verdict) {
     switch (verdict) {
@@ -19,6 +20,11 @@ export function verdictWord(verdict) {
             return "ok";
         case "stale":
             return "STALE";
+        // BLI-3723. Its own word, not a shade of STALE: a `failing` reader's input
+        // is CURRENT and its answer is bad, which sends a person to a laptop
+        // rather than to a cron config.
+        case "failing":
+            return "BAD";
         case "never_produced":
             return "EMPTY";
         case "unreadable":
@@ -69,7 +75,9 @@ export function renderOpsStatus(payload, dim) {
     for (const row of rows) {
         const verdict = verdictWord(row.verdict).padEnd(6);
         const id = (row.id ?? "?").padEnd(idWidth);
-        const age = ageWord(row.ageHours).padStart(7);
+        // BLI-3723: a row that has no age BY DESIGN says `n/a`, never `—`. The two
+        // look alike and mean opposite things — `—` is "the table is empty".
+        const age = (row.ageAbsence ? "n/a" : ageWord(row.ageHours)).padStart(7);
         // BLI-3722: name the device this age belongs to right in the row — a bare
         // `STALE collector-fleet 11h` was already misread once (BLI-3699) as "the
         // fleet", not "one machine in it", and the name is otherwise buried in
@@ -77,6 +85,10 @@ export function renderOpsStatus(payload, dim) {
         const staleName = row.verdict === "stale" && row.staleDeviceName ? ` ${dim(`(${row.staleDeviceName})`)}` : "";
         lines.push(`${verdict} ${id}  ${age}${staleName}  ${dim(intervalWord(row))}`);
         if (row.verdict !== "healthy") {
+            // The absence of an age is explained BEFORE the detail, because it is
+            // the first thing a reader's eye stopped on.
+            if (row.ageAbsence)
+                lines.push(dim(`       no age: ${row.ageAbsence}`));
             if (row.detail)
                 lines.push(dim(`       ${row.detail}`));
             if (row.caveat)

package/dist/commands/ops.js

@@ -12,7 +12,7 @@
  *
  * **Exit codes are the whole point of running this in a script.** Zero when
  * every job that CAN be answered for is healthy; 1 when anything is stale,
- * empty or unreadable. `no_artifact` — a job that writes no row — does not fail
+ * failing, empty or unreadable. `no_artifact` — a job that writes no row — does not fail
  * the command, and it does not pass silently either: it prints as `n/a` with
  * the reason there is nothing to read.
  *
@@ -25,6 +25,7 @@
  */
 import { colorEnabled, dim, writeLine } from "./cli-io.js";
 import { renderOpsStatus } from "./ops-render.js";
+import { renderMemoryUsage, } from "./ops-render-memory.js";
 import { asRecord, callTower, openTower, writeCommandFailure } from "./tower-command.js";
 /**
  * A whole compile, plus a little. `maxDuration` on `/api/ops/recompile` is 800
@@ -60,15 +61,40 @@ async function runOpsStatus(command, io, tower) {
     }
     const payload = asRecord(result.body);
     const rows = payload.pipelines ?? [];
-    const unhealthy = rows.filter((row) => row.verdict === "stale" || row.verdict === "never_produced" || row.verdict === "unreadable");
+    // BLI-3729. A SECOND door, asked for only when `--memory` was: the adoption
+    // gauge is a different question from pipeline health and a different read,
+    // and putting it on every `cockpit ops` would make the common run slower for
+    // a number most runs do not want. Its failure is its own line and never the
+    // status board's exit code — "is the org using memory" going unread is not a
+    // pipeline outage.
+    const memory = command.memory ? await readMemoryUsage(command, io, tower) : null;
+    // BLI-3723: `failing` joins the list. An older CLI that has never heard of it
+    // simply does not count it — which is why the server keeps the sentence in
+    // `detail`, so an un-upgraded terminal still PRINTS the outage even when it
+    // exits 0 over it.
+    const unhealthy = rows.filter((row) => row.verdict === "stale" ||
+        row.verdict === "never_produced" ||
+        row.verdict === "unreadable" ||
+        row.verdict === "failing");
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify(payload));
+        writeLine(io.stdout, JSON.stringify(memory ? { ...payload, memory: memory.section } : payload));
     }
     else {
         const styled = colorEnabled(io);
         for (const line of renderOpsStatus(payload, (text) => dim(text, styled))) {
             writeLine(io.stdout, line);
         }
+        if (memory?.section) {
+            for (const line of renderMemoryUsage(memory.section, (text) => dim(text, styled))) {
+                writeLine(io.stdout, line);
+            }
+        }
+        else if (memory) {
+            // Never a silent gap where a section was asked for: the reason the gauge
+            // could not be read is printed where the gauge would have been.
+            writeLine(io.stdout, "");
+            writeLine(io.stdout, `MEMORY  not read (${memory.reason})`);
+        }
     }
     // Both branches log — an all-green board that says nothing cannot answer
     // "did anybody look today?".
@@ -84,9 +110,45 @@ async function runOpsStatus(command, io, tower) {
         fleet_devices: payload.fleet?.counts?.devices ?? null,
         fleet_red: payload.fleet?.counts?.red ?? null,
         fleet_amber: payload.fleet?.counts?.amber ?? null,
+        // BLI-3729: whether the adoption gauge was asked for, and what it said.
+        // Both branches, as everywhere else here.
+        memory_asked: Boolean(command.memory),
+        memory_reason: memory?.reason ?? null,
+        memory_agent_saves: memory?.section
+            ? (memory.section.counts?.mcp ?? 0) + (memory.section.counts?.stop_hook ?? 0)
+            : null,
     })}`);
     return unhealthy.length > 0 ? 1 : 0;
 }
+/**
+ * The adoption gauge, read through its own door.
+ *
+ * Never fails the board: a `cockpit ops --memory` whose memory half is
+ * unreadable still prints the pipelines, the fleet and the coverage, and says
+ * in one line which half is missing and why. The status board's exit code is
+ * about collection health, and adoption is not that.
+ */
+async function readMemoryUsage(command, io, tower) {
+    const params = new URLSearchParams();
+    if (command.memoryDays !== undefined)
+        params.set("days", String(command.memoryDays));
+    const query = params.toString();
+    const result = await callTower(tower, {
+        path: `/api/ops/memory-usage${query ? `?${query}` : ""}`,
+        label: "ops-memory-usage",
+    });
+    if (!result.ok) {
+        writeLine(io.stderr, `[ops cli] memory usage not read ${JSON.stringify({
+            reason: result.reason,
+            http_status: result.httpStatus ?? null,
+        })}`);
+        return { section: null, reason: result.reason };
+    }
+    const body = asRecord(result.body);
+    if (!body.memory)
+        return { section: null, reason: "memory_section_absent" };
+    return { section: body.memory, reason: "ok" };
+}
 async function runOpsRecompile(command, io, tower) {
     const person = command.person ?? "";
     if (!command.json) {

package/dist/commands/project.js

@@ -0,0 +1,38 @@
+/**
+ * `cockpit project list` — the projects issues are filed under (BLI-3716).
+ *
+ * One verb, because `GET /api/work/projects` is the whole of the Work
+ * surface's project door today (BLI-3703 scoped projects to list-only; there
+ * is no create/update/delete route to put a terminal in front of). Its own
+ * command rather than `cockpit issue projects` because a person says
+ * "projects", and `cockpit issue list --project <name>` resolves a name
+ * against exactly this list.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[project cli]";
+const READ_DEADLINE_MS = 30_000;
+export async function runProject(command, io) {
+    const door = await openAgentDoor("project", command, io);
+    const answer = await askAgentDoor(door, {
+        path: `/api/work/projects${command.includeArchived ? "?include_archived=true" : ""}`,
+        method: "GET",
+        label: "project list",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const projects = answer.body.projects ?? [];
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, projects });
+    if (projects.length === 0) {
+        writeLine(door.io.stdout, "No projects.");
+        return 0;
+    }
+    for (const project of projects) {
+        writeLine(door.io.stdout, `${project.id}  ${project.archived_at ? "archived" : "active  "}  ${project.name}`);
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${projects.length} project(s).`);
+    return 0;
+}

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

package/dist/commands/search.js

@@ -0,0 +1,122 @@
+/**
+ * `cockpit search` — one bar over five corpora, in a terminal (BLI-3728).
+ *
+ * The SAME door the browser's search bar presses: `GET /api/search`, opted
+ * into the collector device token in `route-caller-census.test.ts`. So a
+ * result a person reads in the rail is the same row, the same ranking and the
+ * same snippet an agent gets here. That is the whole point of the ticket's
+ * "agent-friendly is the definition of done" clause; nothing about search is
+ * computed on this side.
+ *
+ * WHAT THIS PRINTS THAT THE BROWSER ALSO SHOWS
+ * --------------------------------------------
+ * A corpus that could not answer gets its own line. "Messages did not answer"
+ * and "no messages matched" are different facts, and a terminal that folds
+ * them together lets a person conclude the record is silent when the search
+ * was simply broken. Same rule, same words, as the overlay.
+ *
+ * `[[` / `]]` are `ts_headline`'s markers, chosen server-side precisely
+ * BECAUSE they are inert in a terminal (`src/lib/search/snippet.ts`). Without
+ * a TTY they are stripped; with one they become reverse video, and nothing
+ * here parses HTML.
+ *
+ * A refusal keeps the door's own `reason` label verbatim (`agent-door.ts`):
+ * `needs_rls_client`, `query_too_short`, `query_too_long`, `unknown_kind`,
+ * `read_failed` — never rephrased here.
+ */
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
+import { writeLine } from "./cli-io.js";
+const TAG = "[search cli]";
+const READ_DEADLINE_MS = 30_000;
+/** Group headings, in the order a person reads them. Mirrors the overlay. */
+const KIND_LABELS = {
+    doc: "DOCUMENTS",
+    msg: "MESSAGES",
+    issue: "ISSUES",
+    note: "MEETING NOTES",
+    memory: "MEMORY",
+};
+const KIND_ORDER = ["doc", "msg", "issue", "note", "memory"];
+export async function runSearch(command, io) {
+    const door = await openAgentDoor("search", command, io);
+    const params = new URLSearchParams({ q: command.query });
+    if (command.kinds && command.kinds.length > 0)
+        params.set("kinds", command.kinds.join(","));
+    if (command.limit !== undefined)
+        params.set("limit", String(command.limit));
+    const answer = await askAgentDoor(door, {
+        path: `/api/search?${params.toString()}`,
+        method: "GET",
+        label: "search",
+        timeoutMs: READ_DEADLINE_MS,
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emitAgentDoor(door, body);
+    return render(door, body);
+}
+function render(door, body) {
+    const hits = body.hits ?? [];
+    const failures = body.failures ?? {};
+    const colour = Boolean(door.io.stdout.isTTY);
+    if (hits.length === 0) {
+        if (Object.keys(failures).length === 0) {
+            writeLine(door.io.stdout, "Nothing matched. Every corpus answered — this is silence, not a failure.");
+        }
+        else {
+            writeLine(door.io.stdout, "Nothing matched in the corpora that answered.");
+        }
+    }
+    for (const kind of KIND_ORDER) {
+        const group = hits.filter((hit) => hit.kind === kind);
+        if (group.length === 0)
+            continue;
+        writeLine(door.io.stdout, "");
+        writeLine(door.io.stdout, KIND_LABELS[kind] ?? kind.toUpperCase());
+        for (const hit of group) {
+            writeLine(door.io.stdout, `  ${hit.title}`);
+            const snippet = paintSnippet(hit.snippet, colour);
+            if (snippet.length > 0)
+                writeLine(door.io.stdout, `    ${snippet}`);
+            const meta = [
+                hit.author,
+                hit.date ? hit.date.slice(0, 10) : null,
+                (hit.channels ?? []).join("+"),
+                `score ${hit.score}`,
+                // A memory has no address, and saying so is better than printing a
+                // blank column somebody reads as a missing link.
+                hit.href ?? "(no page — the text above is the whole record)",
+            ]
+                .filter(Boolean)
+                .join("  ·  ");
+            writeLine(door.io.stdout, `    ${meta}`);
+        }
+    }
+    // Never folded into "nothing matched". Same rule as the overlay.
+    const failed = Object.entries(failures);
+    if (failed.length > 0) {
+        writeLine(door.io.stdout, "");
+        for (const [kind, reason] of failed) {
+            writeLine(door.io.stdout, `${KIND_LABELS[kind] ?? kind.toUpperCase()} did not answer (${reason}). Nothing from there is in this list.`);
+        }
+    }
+    writeLine(door.io.stdout, "");
+    writeLine(door.io.stdout, `${hits.length} result(s) in ${body.elapsedMs ?? 0} ms.`);
+    return 0;
+}
+const REVERSE_ON = "\u001B[7m";
+const REVERSE_OFF = "\u001B[27m";
+/**
+ * `[[match]]` into reverse video, or into plain text without a TTY.
+ *
+ * A pipe gets clean text — `cockpit search x | grep` must not have to know
+ * about escape codes — and a terminal gets the highlight the browser shows.
+ */
+export function paintSnippet(snippet, colour) {
+    const collapsed = snippet.replace(/\s+/g, " ").trim();
+    if (!colour)
+        return collapsed.split("[[").join("").split("]]").join("");
+    return collapsed.split("[[").join(REVERSE_ON).split("]]").join(REVERSE_OFF);
+}

package/dist/commands/setup-receipt-lines.js

@@ -0,0 +1,71 @@
+/**
+ * What the setup receipt SAYS (BLI-3731). One line, then one fix per gap.
+ *
+ * Split from `setup-receipt.ts` for the reason the repo splits everything:
+ * computing a state and wording it are different jobs, and only one of them
+ * touches the machine. This file touches nothing.
+ *
+ * The rule for the fix lines is the one the message standard already sets — a
+ * refusal that does not say what to do next is half a message. Every gap here
+ * gets ONE command or ONE click, never a paragraph and never "see the docs".
+ */
+import { setupPieceMark, setupReceiptLine, setupReceiptPieces, } from "@bli-cockpit/telemetry-core";
+/** The one fix for each piece, by key. Present for every key the block prints. */
+const FIXES = {
+    browser: "Run `cockpit login` and open the link it prints.",
+    device: "Run `cockpit login` — this machine's session has lapsed.",
+    "claude.mcp": "Run `cockpit memory install`.",
+    "claude.hooks": "Run `cockpit memory install`.",
+    "codex.mcp": "Run `cockpit memory install`.",
+    "codex.skill": "Run `cockpit memory install`.",
+    "codex.hooks": "Run `cockpit memory install`.",
+    "collector.autostart": "Run `cockpit autostart install`.",
+};
+/** Codex hooks a person switched OFF is a decision, not a fault. */
+const UNSUPPORTED_FIX = "Switched off in your own config; nothing to do.";
+/**
+ * The one exception to "a gap gets a command": Codex hooks that are installed
+ * and waiting to be trusted are finished by a PERSON, in the Codex UI, and no
+ * command we could print would do it.
+ */
+const NEEDS_TRUST_FIX = "Open Codex and press `/hooks` to trust them (once, ~15s).";
+/**
+ * The block a terminal prints: the one line, then one fix per gap, then
+ * nothing. A fully connected machine gets one line and no advice — a receipt
+ * that keeps talking after saying yes trains people to stop reading it.
+ */
+export function setupReceiptBlock(reading, options = {}) {
+    const { receipt, memory } = reading;
+    const indent = options.indent ?? "";
+    const lines = [`${indent}${setupReceiptLine(receipt, memory)}`];
+    for (const { key, label, piece } of setupReceiptPieces(receipt, memory)) {
+        if (piece.status === "ok")
+            continue;
+        lines.push(`${indent}  ${label} ${setupPieceMark(piece.status)}${reasonSuffix(piece)} — ${fixFor(key, piece)}`);
+    }
+    if (options.showCheckedAt) {
+        lines.push(`${indent}Last read: ${receipt.checked_at}`);
+    }
+    return lines;
+}
+/** The whole receipt in one string, for a single `writeLine`. */
+export function setupReceiptText(reading, options = {}) {
+    return setupReceiptBlock(reading, options).join("\n");
+}
+function fixFor(key, piece) {
+    if (piece.status === "needs_trust")
+        return NEEDS_TRUST_FIX;
+    if (piece.status === "unsupported")
+        return UNSUPPORTED_FIX;
+    if (piece.status === "unknown") {
+        // "We did not look" is not somebody's chore. Say what would look.
+        return "Not read this run. Run `cockpit doctor` to check it.";
+    }
+    if (piece.status === "skipped") {
+        return "Skipped on purpose; nothing to do.";
+    }
+    return FIXES[key] ?? "Run `cockpit doctor`.";
+}
+function reasonSuffix(piece) {
+    return piece.reason ? ` (${piece.reason})` : "";
+}