@bli-cockpit/cli 0.2.57 → 0.2.59

package/dist/commands/memory-install-receipt.js

@@ -0,0 +1,222 @@
+/**
+ * THE MEMORY RECEIPT (BLI-3729) — six words this machine can prove.
+ *
+ * `cockpit memory install` already knew, per target, what it had just done.
+ * What nobody could ask was the fleet question: "does Savina's machine have
+ * memory hooks?" This module turns the install's own per-target results into
+ * the small fixed shape that rides the heartbeat
+ * (`@bli-cockpit/telemetry-core`'s `MemoryInstallReceipt`) and that
+ * `lib/ops/fleet-liveness.ts` reads back on the board.
+ *
+ * **It is built from targets that were READ BACK, never from what was sent**
+ * (BLI-2541). Every target it consumes has already re-read and re-parsed the
+ * stored file the way the host will: `installed` means the bytes on disk parse
+ * back to what we wrote, `already` means they already did. This module adds no
+ * new claim; it names the six pieces and carries the reason each one is not
+ * `ok`.
+ *
+ * **One module, on purpose.** BLI-3731 folds this receipt into a one-login
+ * ceremony, so the shape has exactly one producer here and exactly one reader
+ * on the server. Anything that wants to know whether a machine has memory on
+ * calls `buildMemoryInstallReceipt` — it does not re-derive six words from a
+ * target list of its own.
+ *
+ * ## The one word that is not about a file
+ *
+ * `codex.hooks` can be `needs_trust`: installed correctly, and not running,
+ * because Codex requires a person to review and trust a non-managed command
+ * hook before it fires (`/hooks`; see `memory-install-codex-hooks.ts` for the
+ * citation). That state exists in no other piece and is the reason this is six
+ * words rather than a boolean.
+ */
+import { MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION, } from "@bli-cockpit/telemetry-core";
+/**
+ * The one place the six words are decided.
+ *
+ * A target this run never produced (an older CLI, a half-run that threw) is
+ * `unknown`, never `missing`: "we did not look" and "it is not there" are
+ * different facts and the board acts on them differently.
+ */
+export function buildMemoryInstallReceipt(input) {
+    const reasons = {};
+    const piece = (id, key) => {
+        const target = input.targets.find((entry) => entry.target === id);
+        if (!target) {
+            reasons[key] = input.binFound ? "target_not_checked" : "bin_missing";
+            return "unknown";
+        }
+        const word = pieceFor(target.status);
+        if (word !== "ok")
+            reasons[key] = reasonLabel(target.reason);
+        return word;
+    };
+    const codexHooks = judgeCodexHooks(input, reasons);
+    const receipt = {
+        schema_version: MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION,
+        checked_at: (input.now ?? new Date()).toISOString(),
+        claude: {
+            mcp: piece("claude_mcp", "claude.mcp"),
+            hooks: piece("claude_hooks", "claude.hooks"),
+        },
+        codex: {
+            mcp: piece("codex_mcp", "codex.mcp"),
+            skill: piece("codex_skills", "codex.skill"),
+            hooks: codexHooks,
+        },
+        bin_found: input.binFound,
+        ...(Object.keys(reasons).length > 0 ? { reasons } : {}),
+    };
+    return receipt;
+}
+/**
+ * `codex.hooks` is judged in three steps, in this order, and the order is the
+ * point:
+ *
+ *  1. A person who turned hooks OFF is `unsupported`. That is a decision, and
+ *     reporting it as a missing install would put a machine on somebody's
+ *     morning board for doing what its owner asked.
+ *  2. A file target that is not installed loses; there is nothing to trust.
+ *  3. Only then does trust decide, and it can only demote: a correctly written
+ *     hooks file with no trust rows is `needs_trust`, which is INSTALLED and
+ *     NOT RUNNING.
+ */
+function judgeCodexHooks(input, reasons) {
+    const key = "codex.hooks";
+    if (input.codexTrust.feature === "disabled") {
+        reasons[key] = "hooks_disabled_in_config";
+        return "unsupported";
+    }
+    const target = input.targets.find((entry) => entry.target === "codex_hooks");
+    if (!target) {
+        reasons[key] = input.binFound ? "target_not_checked" : "bin_missing";
+        return "unknown";
+    }
+    const word = pieceFor(target.status);
+    if (word !== "ok") {
+        reasons[key] = reasonLabel(target.reason);
+        return word;
+    }
+    if (input.codexTrust.feature === "config_unreadable") {
+        // The hooks are written and correct; whether Codex will run them could not
+        // be read. Say which half is unknown rather than claiming either.
+        reasons[key] = "trust_unreadable";
+        return "unknown";
+    }
+    if (input.codexTrust.trustedRows >= input.expectedTrustRows)
+        return "ok";
+    reasons[key] =
+        input.codexTrust.disabledRows > 0 ? "trust_rows_disabled" : "no_trust_rows";
+    return "needs_trust";
+}
+/**
+ * A target's status collapsed to one of the receipt's words.
+ *
+ * `would_install` (a dry run) is `unknown` on purpose: a dry run proves what
+ * WOULD happen and nothing about what is on disk, and a receipt that treated
+ * it as a reading would let `--dry-run` publish a state nobody wrote.
+ */
+function pieceFor(status) {
+    switch (status) {
+        case "installed":
+        case "already":
+            return "ok";
+        case "mismatch":
+            return "stale";
+        case "missing":
+            return "missing";
+        case "skipped":
+            // Nothing was written, on purpose — today only `bin_missing`. The config
+            // is untouched, so "missing" is the true reading of the file.
+            return "missing";
+        case "would_install":
+        case "failed":
+        default:
+            return "unknown";
+    }
+}
+/** The receipt's reason labels are charset-bounded; a stray reason is clipped. */
+function reasonLabel(reason) {
+    const cleaned = reason.trim().replace(/[^A-Za-z0-9_:.-]/gu, "_");
+    if (cleaned.length === 0)
+        return "unlabelled";
+    return cleaned.slice(0, 60);
+}
+/** `claude ✓ hooks ✓ · codex mcp ✓ skill ✓ hooks needs_trust` — one line. */
+export function memoryReceiptLine(receipt) {
+    const mark = (word) => (word === "ok" ? "✓" : word);
+    return (`claude mcp ${mark(receipt.claude.mcp)} hooks ${mark(receipt.claude.hooks)} · ` +
+        `codex mcp ${mark(receipt.codex.mcp)} skill ${mark(receipt.codex.skill)} ` +
+        `hooks ${mark(receipt.codex.hooks)}`);
+}
+// ---------------------------------------------------------------------------
+// Where the receipt lives between runs
+// ---------------------------------------------------------------------------
+/**
+ * The receipt is CACHED on disk, and the heartbeat reads the cache.
+ *
+ * The alternative — recomputing it inside the heartbeat — costs five file
+ * reads AND a `bli-memory-mcp --print-config` spawn every fifteen minutes on
+ * every machine, to re-prove a state that changes about once a month. The
+ * install and status paths already do that work; this is where they leave the
+ * answer. `checked_at` travels with it, so a stale reading says how stale it
+ * is rather than pretending to be now.
+ *
+ * A cache that cannot be written is logged and dropped: the install still
+ * happened, and a heartbeat with no receipt reads as "not reported", never as
+ * "not installed".
+ */
+export const MEMORY_RECEIPT_FILE = "memory-install-receipt.json";
+/** How old a cached receipt may be before the heartbeat stops sending it. */
+export const MEMORY_RECEIPT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export async function writeMemoryReceiptFile(options) {
+    const file = joinState(options.stateDir, MEMORY_RECEIPT_FILE);
+    try {
+        await options.io.mkdir(options.stateDir);
+        await options.io.writeFile(file, `${JSON.stringify(options.receipt, null, 2)}\n`);
+        return true;
+    }
+    catch (error) {
+        console.error("[memory-install] the memory receipt could not be cached for the heartbeat", JSON.stringify({
+            reason: "receipt_cache_write_failed",
+            error_name: error instanceof Error ? error.name : "unknown",
+        }));
+        return false;
+    }
+}
+/**
+ * The cached receipt, or a named reason there is none. Never throws: a
+ * heartbeat must not fail over a cache file.
+ */
+export async function readMemoryReceiptFile(options) {
+    let raw;
+    try {
+        raw = await options.readText(joinState(options.stateDir, MEMORY_RECEIPT_FILE));
+    }
+    catch {
+        return { receipt: null, reason: "receipt_absent" };
+    }
+    if (raw === null || !raw.trim())
+        return { receipt: null, reason: "receipt_absent" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { receipt: null, reason: "receipt_unparseable" };
+    }
+    const receipt = options.parse(parsed);
+    if (!receipt)
+        return { receipt: null, reason: "receipt_unparseable" };
+    const age = (options.now ?? new Date()).getTime() - Date.parse(receipt.checked_at);
+    // A reading a week old is not a reading. Better to send nothing and let the
+    // board say "not reported" than to publish a claim about a machine that has
+    // not been looked at since.
+    if (Number.isFinite(age) && age > MEMORY_RECEIPT_MAX_AGE_MS) {
+        return { receipt: null, reason: "receipt_expired" };
+    }
+    return { receipt, reason: "receipt_read" };
+}
+function joinState(stateDir, name) {
+    const separator = stateDir.includes("\\") && !stateDir.includes("/") ? "\\" : "/";
+    return stateDir.endsWith(separator) ? `${stateDir}${name}` : `${stateDir}${separator}${name}`;
+}

package/dist/commands/memory-install-report.js

@@ -0,0 +1,113 @@
+/**
+ * The dashboard URL to register against, aggregating per-target results into
+ * one outcome, and rendering that outcome for a log line or a terminal.
+ * Sibling of `memory-install.ts`, named in its header.
+ */
+import { memoryInstallGaps } from "@bli-cockpit/telemetry-core";
+import { memoryReceiptLine } from "./memory-install-receipt.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+export async function resolveDashboardUrl(command, deps) {
+    if (command.dashboardUrl)
+        return command.dashboardUrl;
+    const paths = getCollectorRuntimePaths(deps.homeDir ?? command.homeDir);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    return config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
+}
+export function aggregate(targets) {
+    const failed = targets.filter((target) => target.status === "failed");
+    if (failed.length > 0) {
+        return {
+            status: "failed",
+            // The first named reason, not a count: an operator needs the reason, and
+            // the per-target list beside it carries the rest.
+            reason: failed[0]?.reason ?? "unknown_failure",
+        };
+    }
+    if (targets.some((target) => target.status === "would_install")) {
+        return { status: "would_install", reason: "dry_run" };
+    }
+    if (targets.some((target) => target.status === "installed")) {
+        return { status: "installed", reason: "wrote_entry" };
+    }
+    if (targets.some((target) => target.status === "mismatch" || target.status === "missing")) {
+        return { status: "missing", reason: "entry_absent" };
+    }
+    // BLI-3706: checked BEFORE `skipped`, not after. `bli-tower` registering
+    // beside `bli-memory` on this same command means a machine can be fully
+    // "already" registered for one server while the other's bin is not here
+    // yet — that machine's OWN state must not read as "skipped" (nothing is
+    // happening) when something plainly already is. `skipped` only wins the
+    // whole outcome when NOTHING on this machine has ever reached "already"
+    // either — the original one-server case (a fresh machine, bin missing,
+    // nothing written at all) still returns "skipped" via the fallback below.
+    if (targets.some((target) => target.status === "already")) {
+        return { status: "already", reason: "already_current" };
+    }
+    const skipped = targets.find((target) => target.status === "skipped");
+    if (skipped) {
+        // Not a failure and not a success: nothing was written, on purpose, and
+        // the next daily run will try again. `bin_missing` is the only one today.
+        return { status: "skipped", reason: skipped.reason };
+    }
+    return { status: "already", reason: "already_current" };
+}
+/**
+ * Both branches log, and neither carries a path — a home directory names a
+ * person, and this line ends up in `sync.err.log` on every machine.
+ */
+export function logMemoryOutcome(outcome, platform) {
+    const fields = {
+        status: outcome.status,
+        reason: outcome.reason,
+        config_source: outcome.config_source,
+        bin_found: outcome.bin_found,
+        platform,
+        installed_count: outcome.targets.filter((target) => target.status === "installed").length,
+        already_count: outcome.targets.filter((target) => target.status === "already").length,
+        failed: outcome.targets
+            .filter((target) => target.status === "failed")
+            .map((target) => `${target.target}:${target.reason}`),
+        // BLI-3729: the six words, on the same line. `sync.err.log` is where a
+        // person looks when the board says their machine is missing a piece, and
+        // the log that only named per-target statuses could not answer "is memory
+        // ON here?" without the reader collapsing five rows in their head.
+        memory_on: memoryInstallGaps(outcome.receipt).length === 0,
+        memory_gaps: memoryInstallGaps(outcome.receipt),
+        codex_hooks: outcome.receipt.codex.hooks,
+    };
+    // stderr on both branches: launchd captures it to sync.err.log, and stdout is
+    // reserved for `--json`.
+    console.error(outcome.status === "failed"
+        ? "[memory-install] BLI Memory is not fully registered on this machine"
+        : "[memory-install] BLI Memory registration converged", JSON.stringify(fields));
+}
+export function memoryOutcomeLines(outcome) {
+    const headline = outcome.status === "installed"
+        ? "BLI Memory registered on this machine."
+        : outcome.status === "already"
+            ? "BLI Memory is already registered on this machine."
+            : outcome.status === "would_install"
+                ? "BLI Memory would be registered (dry run; nothing was written)."
+                : outcome.status === "missing"
+                    ? "BLI Memory is not registered on this machine."
+                    : outcome.status === "skipped"
+                        ? "BLI Memory was not registered and nothing was written: the bli-memory-mcp server is not on this machine yet."
+                        : `BLI Memory is not fully registered: ${outcome.reason}.`;
+    const lines = [headline, `  ${memoryReceiptLine(outcome.receipt)}`];
+    // The trust step is the one thing a person has to do by hand, so it is said
+    // here in words rather than left as a status word they have to look up.
+    if (outcome.receipt.codex.hooks === "needs_trust") {
+        lines.push("  Codex will NOT run these hooks until you trust them: open Codex in any folder, " +
+            "run /hooks, and trust the three bli-memory entries. One time, per machine.");
+    }
+    if (outcome.receipt.codex.hooks === "unsupported") {
+        lines.push("  Codex hooks are turned off in your ~/.codex/config.toml ([features] hooks = false), " +
+            "so the hooks were written and will not run. That is your setting; nothing here changes it.");
+    }
+    for (const target of outcome.targets) {
+        const where = target.path ? ` ${target.path}` : "";
+        const detail = target.detail ? ` — ${target.detail}` : "";
+        lines.push(`  ${target.target}: ${target.status} (${target.reason})${where}${detail}`);
+    }
+    return lines;
+}