@bli-cockpit/cli 0.2.94 → 0.2.95

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

package/dist/commands/sync-followups-autostart.js

@@ -0,0 +1,99 @@
+import { resolveAutostartRoots } from "./autostart-command.js";
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { runAutostartSelfHeal, } from "../autostart-self-heal.js";
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
+/**
+ * BLI-2721: after the tick's collection and self-update are done and
+ * reported, repair a broken/legacy autostart registration in place (Windows
+ * only — see autostart-self-heal.ts for why macOS is excluded). Every error
+ * path is swallowed like the self-update's: heal outcomes are their own
+ * receipts, never a sync failure.
+ */
+export async function runAutostartSelfHealAfterSync(command, io, dashboardUrl) {
+    let result;
+    try {
+        const rawExec = io.exec;
+        if (!rawExec) {
+            sayNoProcessRunner();
+            await reportAutostartSelfHealOutcome(command, io, dashboardUrl, runnerUnavailableOutcome());
+            return;
+        }
+        result = await repairAutostartRegistration(command, io, rawExec);
+    }
+    catch (error) {
+        result = {
+            status: "fail",
+            reason: "autostart_self_heal_threw",
+            detail: redactedSyncErrorDetail(error),
+        };
+    }
+    // Steady state (healthy, absent, non-Windows, no roots) and the daily
+    // throttle are silent; an actual repair attempt reports either way.
+    if (!result || result.reason === "repair_throttled_recent_attempt")
+        return;
+    await reportAutostartSelfHealOutcome(command, io, dashboardUrl, result);
+}
+/**
+ * Attempt the repair with a runner that can find node.
+ *
+ * Every spawn in the scheduled path carries the running node's bin dir on
+ * PATH (`envWithNodeRuntimeOnPath`); the scheduler's stripped environment
+ * needs it. Returns null when there was nothing to repair.
+ */
+async function repairAutostartRegistration(command, io, rawExec) {
+    const spawnEnv = envWithNodeRuntimeOnPath(io.env ?? process.env);
+    const exec = (cmd, args, options) => rawExec(cmd, args, { ...options, env: options?.env ?? spawnEnv });
+    return runAutostartSelfHeal(getCollectorRuntimePaths(command.homeDir), {
+        homeDir: command.homeDir,
+        repoRoots: await resolveAutostartRoots(command.homeDir, undefined),
+        dashboardUrl: command.dashboardUrl,
+        exec,
+    });
+}
+/**
+ * Say out loud that the repair was never attempted.
+ *
+ * BLI-3483: this was a bare `return`. On Windows the self-heal is the only
+ * thing that puts a broken scheduler back, so abandoning it here meant a
+ * machine could stop collecting forever and leave no receipt anywhere — the
+ * exact shape the fleet contract forbids. The packed CLI always supplies a
+ * runner (`commands/cli-io.ts`), so this fires only for an embedder that built
+ * its own `io`; it costs one line either way.
+ */
+function sayNoProcessRunner() {
+    console.error("[autostart-self-heal] no process runner on this io; the repair could not be attempted", JSON.stringify({
+        reason: "runner_unavailable",
+        platform: process.platform,
+        next_action: "reinstall the CLI (npm i -g @bli-cockpit/cli) and run `cockpit autostart install`",
+    }));
+}
+/** The same fact as a receipt, so the fleet table can see it too. */
+function runnerUnavailableOutcome() {
+    return {
+        status: "skipped",
+        reason: "runner_unavailable",
+        detail: "No process runner available to this CLI invocation; run `cockpit autostart install` by hand.",
+    };
+}
+/** One receipt for the repair, whichever branch above produced the outcome. */
+async function reportAutostartSelfHealOutcome(command, io, dashboardUrl, result) {
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [
+            {
+                // Windows repairs in place and keeps the name already in the receipts
+                // and the runbook; the macOS path only SCHEDULES a detached repair, so
+                // it reports under its own step (BLI-3553).
+                step: result.step ?? "autostart_repair",
+                status: result.status,
+                ...(result.status === "ok" ? {} : { error_code: result.reason }),
+                ...(result.detail ? { error_detail: result.detail } : {}),
+            },
+        ],
+        json: command.json,
+        io,
+    });
+}

package/dist/commands/sync-followups-memory.js

@@ -0,0 +1,123 @@
+/**
+ * Follow-up three: keep BLI Memory registered with both agent hosts (BLI-3580).
+ *
+ * Nobody is going to be asked to install a hook. `do-everything` registers it
+ * on the way through, and this puts it back if a host config is edited,
+ * replaced, or restored from a machine that never had it — at most once a day,
+ * because the steady state is "already current" and re-proving that every
+ * fifteen minutes is four file reads a tick for no new information.
+ *
+ * Same rule as the other follow-ups: it runs only once collection's own
+ * outcome has been decided and reported, it never throws, and its outcome is
+ * its own named receipt rather than a sync failure.
+ *
+ * Split out of `sync-followups.ts` (BLI-3988). The registration itself, and
+ * every target it writes, are `./memory-install.ts`.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { installMemoryIntegration, } from "./memory-install.js";
+import { getCollectorRuntimePaths, } from "../local-state.js";
+export const MEMORY_INSTALL_THROTTLE_MARKER = ".last-memory-install";
+const MEMORY_INSTALL_MIN_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * BLI-3580: BLI Memory's registration converges on its own, once a day.
+ *
+ * The daily cadence and the swallowed error paths are the whole contract; see
+ * this module's header for why each of them is what it is.
+ */
+export async function runMemoryInstallAfterSync(command, io, dashboardUrl, options = {}) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const now = options.now ?? new Date();
+    if (await triedWithinTheLastDay(paths, now))
+        return;
+    await markInstallAttempted(paths, now);
+    const event = await installMemoryOrSayWhyNot(command, io, dashboardUrl);
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [event],
+        json: command.json,
+        io,
+    });
+}
+/** Has this machine already had its one attempt today? */
+async function triedWithinTheLastDay(paths, now) {
+    const marker = path.join(paths.state_dir, MEMORY_INSTALL_THROTTLE_MARKER);
+    const lastAttempt = await fs.stat(marker).catch(() => null);
+    if (!lastAttempt)
+        return false;
+    return now.getTime() - lastAttempt.mtimeMs < MEMORY_INSTALL_MIN_INTERVAL_MS;
+}
+/**
+ * Spend today's attempt before making it.
+ *
+ * Written for the ATTEMPT, not the outcome — the same idiom the self-update
+ * and autostart repair use, so a machine that cannot write a host config does
+ * not retry it every fifteen minutes.
+ */
+async function markInstallAttempted(paths, now) {
+    const marker = path.join(paths.state_dir, MEMORY_INSTALL_THROTTLE_MARKER);
+    await fs.mkdir(paths.state_dir, { recursive: true }).catch(() => undefined);
+    await fs.writeFile(marker, now.toISOString()).catch(() => undefined);
+}
+/** The registration attempt, as a receipt either way; it cannot throw. */
+async function installMemoryOrSayWhyNot(command, io, dashboardUrl) {
+    try {
+        const outcome = await installMemoryIntegration({
+            kind: "memory",
+            action: "install",
+            homeDir: command.homeDir,
+            dashboardUrl,
+            dryRun: false,
+            json: command.json,
+        }, io, 
+        // Undefined on the real CLI (no io literal sets it); a test io can
+        // override the bin lookup so `bin_missing` is a fixture rather than a
+        // property of the machine the suite runs on (BLI-3630).
+        io.memoryInstallDeps);
+        return memoryInstallEvent(outcome);
+    }
+    catch (error) {
+        return {
+            step: "memory_install",
+            status: "fail",
+            error_code: "memory_install_threw",
+            error_detail: redactedSyncErrorDetail(error),
+        };
+    }
+}
+/**
+ * Target names and reason labels only. A target's `path` names a person's home
+ * directory and a `write_failed` detail can carry one, so neither travels: the
+ * receipt says `claude_hooks:read_back_mismatch`, which is the part an operator
+ * can act on.
+ */
+function memoryInstallEvent(outcome) {
+    const detail = [
+        `source=${outcome.config_source}`,
+        ...outcome.targets.map((target) => `${target.target}:${target.status}/${target.reason}`),
+    ].join("; ");
+    if (outcome.status === "failed") {
+        return {
+            step: "memory_install",
+            status: "fail",
+            error_code: outcome.reason,
+            error_detail: detail,
+        };
+    }
+    if (outcome.status === "skipped") {
+        // Nothing was written, on purpose (`no_bin_no_write`). A fleet-wide
+        // `bin_missing` is the receipt that says the server package has not
+        // reached the machines yet — a fact, not a fault.
+        return {
+            step: "memory_install",
+            status: "skipped",
+            error_code: outcome.reason,
+            error_detail: detail,
+        };
+    }
+    return { step: "memory_install", status: "ok", error_detail: detail };
+}

package/dist/commands/sync-followups-self-update.js

@@ -0,0 +1,127 @@
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { runSelfUpdate, SelfUpdateError } from "./install-update.js";
+import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { envWithNodeRuntimeOnPath, runScheduledSelfUpdate, } from "../scheduled-self-update.js";
+/**
+ * BLI-2601: the fleet keeps itself current on npm `latest` without anyone
+ * re-running `npm i -g @bli-cockpit/cli` by hand after day 0. This always
+ * runs AFTER `runSync` has already decided and reported collection's own
+ * outcome above — a stuck or failing self-update can never block or delay
+ * collection, and a collection failure never blocks the chance to
+ * self-update. Every error path here is swallowed on purpose: a failure is
+ * reported as its own named `update` receipt, never surfaced as a `sync`
+ * failure or thrown from this function.
+ */
+export async function runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion) {
+    let event;
+    try {
+        event = await runScheduledSelfUpdateForSync(command, io, minCliVersion);
+    }
+    catch (error) {
+        // The throttle/probe/install machinery below is defensive already; this
+        // is the last-resort net so an update crash truly cannot touch the sync
+        // result above.
+        event = {
+            step: "update",
+            status: "fail",
+            error_code: "self_update_threw",
+            error_detail: redactedSyncErrorDetail(error),
+        };
+    }
+    if (!event)
+        return;
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "update",
+        events: [event],
+        json: command.json,
+        io,
+    });
+}
+async function runScheduledSelfUpdateForSync(command, io, minCliVersion) {
+    const rawExec = io.exec;
+    if (!rawExec) {
+        // Only the real production `defaultIo()` supplies a process runner. A
+        // caller that omitted one gets a silent no-op rather than this reaching
+        // for a real npm binary it was never given — never observed in
+        // production, where `defaultIo()` always sets `exec`.
+        return null;
+    }
+    // Every spawn in the scheduled path carries the running node's bin dir on
+    // PATH — see envWithNodeRuntimeOnPath. Interactive doctor never needed
+    // this; the scheduler's stripped environment does.
+    const spawnEnv = envWithNodeRuntimeOnPath(io.env ?? process.env);
+    const exec = (cmd, args, options) => rawExec(cmd, args, { ...options, env: options?.env ?? spawnEnv });
+    const scheduledIo = { ...io, exec };
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const result = await runScheduledSelfUpdate(paths, {
+        exec,
+        currentVersion: LOCAL_COLLECTOR_VERSION,
+        install: (tag) => attemptScheduledSelfUpdateInstall(scheduledIo, tag),
+    }, { env: io.env, minVersion: minCliVersion });
+    return scheduledSelfUpdateInstallEvent(result);
+}
+async function attemptScheduledSelfUpdateInstall(io, tag) {
+    try {
+        // Reuses the exact npm-install machinery `cockpit doctor`'s
+        // `fixCliLatest` uses (see doctor.ts:243-280) so there is one place that
+        // knows how to invoke `npm i -g` and classify EACCES. Unlike doctor,
+        // this call never re-execs — see runScheduledSelfUpdate's doc comment.
+        await runSelfUpdate(io, { json: true, tag });
+        return { ok: true };
+    }
+    catch (error) {
+        if (!(error instanceof SelfUpdateError))
+            throw error;
+        return { ok: false, eacces: error.eacces };
+    }
+}
+function scheduledSelfUpdateInstallEvent(result) {
+    // The steady-state "already checked today" case is a pure no-op; reporting
+    // it would post a receipt on ~95 of every 96 sync ticks for no new
+    // information. Only a real attempt (ok, fail, or an explicit disable)
+    // produces a receipt.
+    if (result.reason === "throttled_recent_attempt")
+        return null;
+    // A forced attempt names its trigger in the receipt either way, so the
+    // ledger can tell "converged on the daily cadence" from "the floor pulled
+    // this machine forward" (BLI-2678).
+    const forcedDetail = result.forced && result.min_version
+        ? `forced_min_version ${result.min_version}`
+        : null;
+    if (result.status === "ok") {
+        // BLI-3551: this used to be `update ok` with an empty detail unless the
+        // floor forced it. One machine posted that receipt daily for nine releases
+        // while sitting on 0.2.37, and nobody could tell "already current" from
+        // "installed something" from "npm answered nothing" — three different
+        // situations wearing one word. The success branch names itself now.
+        const okDetail = [
+            forcedDetail,
+            result.reason === "updated" && result.previous_version && result.installed_version
+                ? `installed ${result.previous_version}→${result.installed_version}`
+                : result.reason,
+            result.target_version ? `target ${result.target_version}` : null,
+        ]
+            .filter((part) => Boolean(part))
+            .join("; ");
+        return {
+            step: "update",
+            status: "ok",
+            ...(okDetail ? { error_detail: okDetail } : {}),
+        };
+    }
+    const detail = [
+        forcedDetail,
+        result.target_version ? `target ${result.target_version}` : null,
+        result.installed_version ? `installed ${result.installed_version}` : null,
+    ]
+        .filter((part) => Boolean(part))
+        .join("; ");
+    return {
+        step: "update",
+        status: result.status,
+        error_code: result.reason,
+        ...(detail ? { error_detail: detail } : {}),
+    };
+}

package/dist/commands/sync-followups-staging.js

@@ -0,0 +1,202 @@
+import { redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { runStagingPrune } from "../disk-prune.js";
+import { runEvidenceReconcile, } from "../evidence-reconcile-client.js";
+import { runEvidenceRedelivery, } from "../evidence-redelivery.js";
+/** How many reconcile batches (of up to 500 hashes each) one sync tick may spend. */
+const RECONCILE_BATCHES_PER_TICK = 1;
+/**
+ * BLI-3619: staged raw evidence Tower has already accepted stops living on the
+ * laptop forever.
+ *
+ * Same shape as the memory install beside it and for the same reasons: it runs
+ * only once collection's own outcome is decided and reported, at most once a
+ * day, it cannot throw, and its outcome is its own named receipt rather than a
+ * sync failure. A machine that cannot prune is a machine short of disk, and
+ * that must never also be a machine that stops collecting.
+ *
+ * The rule itself is `disk-retention.ts`: only objects the upload ledger
+ * vouches for are ever deleted, and anything undelivered is counted, aged and
+ * named instead.
+ *
+ * BLI-3619's second half runs FIRST, every tick, bounded to
+ * `RECONCILE_BATCHES_PER_TICK` (one batch of up to 500 hashes): the local
+ * ledger's own memory is capped, so a laptop that keeps accumulating
+ * `unknown` state needs SOMETHING asking the server on a schedule, not only
+ * when a person happens to type `cockpit clean --reconcile`. One batch a tick
+ * is not throttled to once a day like the prune below — an `unknown` backlog
+ * drains at up to 500 hashes/15 min, and the ordinary case (nothing unknown)
+ * costs one cheap local read and no network call at all, so it never competes
+ * with collection for the tick's time. A reconcile failure never blocks the
+ * prune that follows it.
+ *
+ * BLI-3797 sits between them: the reconcile has just established which staged
+ * objects the SERVER says it never received, so the redelivery drain re-offers
+ * exactly those, bounded, before the prune runs and can delete whatever landed.
+ * Neither of the two can block the prune, and none of the three can fail a tick.
+ */
+export async function runStagingPruneAfterSync(command, io, dashboardUrl, options = {}) {
+    const events = [];
+    const reconciled = await runReconcileFollowUp(command, io, dashboardUrl, options);
+    if (reconciled)
+        events.push(reconcileEvent(reconciled));
+    const redelivered = await runRedeliveryFollowUp(command, io, dashboardUrl, options);
+    if (redelivered)
+        events.push(redeliveryEvent(redelivered));
+    let result;
+    try {
+        result = await runStagingPrune(getCollectorRuntimePaths(command.homeDir), {
+            env: io.env,
+            ...(options.now ? { now: options.now } : {}),
+        });
+    }
+    catch (error) {
+        // runStagingPrune already catches everything it can reach; this is the
+        // last-resort net so a prune crash truly cannot touch the sync result.
+        result = { ...prunedNothing(), reason: "prune_threw", status: "fail" };
+        console.error("[collector prune] the prune follow-up threw", JSON.stringify({
+            reason: "prune_followup_threw",
+            detail: redactedSyncErrorDetail(error),
+        }));
+    }
+    // The daily throttle is the steady state — reporting it would post a receipt
+    // on 95 of every 96 ticks for no new information.
+    if (result.reason !== "throttled_recent_run") {
+        events.push(stagingPruneEvent(result));
+    }
+    if (events.length === 0)
+        return;
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events,
+        json: command.json,
+        io,
+    });
+}
+/**
+ * Never throws (`runEvidenceReconcile` already never does); returns `null`
+ * for the boring, common case — nothing this tick was `unknown` — so that
+ * case costs no receipt either, the same rule the prune's own daily throttle
+ * follows above.
+ */
+async function runReconcileFollowUp(command, io, dashboardUrl, options) {
+    const result = await runEvidenceReconcile({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        maxBatches: RECONCILE_BATCHES_PER_TICK,
+        fetch: io.fetch,
+        ...(options.now ? { now: options.now } : {}),
+    });
+    return result.reason === "nothing_unknown" ? null : result;
+}
+/**
+ * BLI-3797, between the reconcile above and the prune below, and in that order
+ * for a reason: reconcile turns `unknown` into a server-backed answer, this
+ * re-offers what that answer says never landed, and the prune then deletes
+ * whatever this just made durable. Running the drain first would ask the server
+ * about hashes it is about to be told the truth about; running it after the
+ * prune would leave a tick's worth of freed cap unused.
+ *
+ * Never throws (`runEvidenceRedelivery` already never does); returns `null` for
+ * the boring, common case — nothing on this disk is undelivered — so the steady
+ * state costs no receipt, the same rule the reconcile follow-up above and the
+ * prune's daily throttle below both follow.
+ */
+async function runRedeliveryFollowUp(command, io, dashboardUrl, options) {
+    const result = await runEvidenceRedelivery({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        env: io.env,
+        fetch: io.fetch,
+        ...(options.now ? { now: options.now } : {}),
+    });
+    return result.reason === "nothing_uncommitted" ? null : result;
+}
+/** Counts and byte totals only; no pack id and no hash travels in a receipt. */
+function redeliveryEvent(result) {
+    const detail = [
+        `offered ${result.offered} object(s), ${result.offered_bytes}B, across ${result.packs} pack(s)`,
+        `uploaded ${result.uploaded} (${result.uploaded_bytes}B), reused ${result.reused}, failed ${result.failed}`,
+        `held ${result.held}, deferred ${result.deferred} (${result.deferred_bytes}B)`,
+        result.failure_reasons.length > 0
+            ? `failure_reasons ${result.failure_reasons.join(",")}`
+            : null,
+    ]
+        .filter((part) => Boolean(part))
+        .join("; ");
+    if (result.status === "fail") {
+        return {
+            step: "evidence_redelivery",
+            status: "fail",
+            error_code: result.reason,
+            error_detail: detail,
+        };
+    }
+    if (result.status === "skipped") {
+        return {
+            step: "evidence_redelivery",
+            status: "skipped",
+            error_code: result.reason,
+            error_detail: detail,
+        };
+    }
+    return { step: "evidence_redelivery", status: "ok", error_detail: detail };
+}
+function prunedNothing() {
+    return {
+        status: "skipped",
+        reason: "prune_threw",
+        deleted_files: 0,
+        deleted_bytes: 0,
+        removed_packs: 0,
+        kept_uncommitted: 0,
+        kept_uncommitted_bytes: 0,
+        oldest_uncommitted_age_ms: 0,
+        kept_unknown: 0,
+        kept_unknown_bytes: 0,
+        kept_in_window: 0,
+        cap_bytes: 0,
+        bytes_before: 0,
+        bytes_after: 0,
+        cap_blocked_by_uncommitted: false,
+        cap_blocked_count: 0,
+        failed_deletions: 0,
+    };
+}
+/** Counts and byte totals only; no pack id and no path travels in a receipt. */
+function stagingPruneEvent(result) {
+    const detail = [
+        `freed ${result.deleted_bytes}B in ${result.deleted_files} file(s)`,
+        `held ${result.kept_uncommitted_bytes}B uncommitted`,
+        result.cap_blocked_by_uncommitted
+            ? `staging_cap_blocked_by_uncommitted ${result.cap_blocked_count}`
+            : null,
+        result.failed_deletions > 0
+            ? `failed_deletions ${result.failed_deletions}`
+            : null,
+    ]
+        .filter((part) => Boolean(part))
+        .join("; ");
+    if (result.status === "fail") {
+        return {
+            step: "staging_prune",
+            status: "fail",
+            error_code: result.reason,
+            error_detail: detail,
+        };
+    }
+    if (result.status === "skipped") {
+        return { step: "staging_prune", status: "skipped", error_code: result.reason };
+    }
+    return { step: "staging_prune", status: "ok", error_detail: detail };
+}
+/** Counts only; no hash and no pack id travels in a receipt. */
+function reconcileEvent(result) {
+    const detail = `asked ${result.asked} hash(es) across ${result.batches}/${result.total_batches} batch(es); committed ${result.committed}, not_committed ${result.not_committed}, unknown_to_server ${result.unknown_to_server}, failed_batches ${result.failed_batches}`;
+    if (result.status === "fail") {
+        return { step: "evidence_reconcile", status: "fail", error_code: result.reason, error_detail: detail };
+    }
+    return { step: "evidence_reconcile", status: "ok", error_detail: detail };
+}