@bli-cockpit/cli 0.2.48 → 0.2.50

package/dist/commands/memory-install.js

@@ -0,0 +1,378 @@
+/**
+ * `cockpit memory install` / `cockpit memory status` (BLI-3580).
+ *
+ * BLI Memory replaces hosted Supermemory: our own table, our own doors, and an
+ * MCP server (`@bli-cockpit/memory-mcp`, bin `bli-memory-mcp`) that both agent
+ * hosts talk to. Nothing about that reaches an intern's machine unless
+ * something puts it there — the vendor plugin never had a fleet install path,
+ * which is why every machine was configured by hand. This is that path, and it
+ * does not ask: `do-everything` runs it, and the sync tick re-runs it at most
+ * once a day so a machine converges without anyone typing anything.
+ *
+ * What it writes, and where, is in the two halves:
+ *   memory-install-claude.ts   ~/.claude.json (user-scope MCP) + ~/.claude/settings.json (hooks, allow-list)
+ *   memory-install-codex.ts    ~/.codex/config.toml (one table) + ~/.codex/skills/bli-memory/
+ *
+ * What this module owns is the decisions around them:
+ *
+ * - **Where the server is.** `bli-memory-mcp` ships as a DEPENDENCY of
+ *   `@bli-cockpit/cli`, so the canonical lookup is the `node_modules/.bin` on
+ *   the way up from this CLI's own entry point; PATH is the fallback. Nobody
+ *   ever installs a second global package. See `resolveMemoryMcpBin`.
+ * - **No server, no write.** If the bin does not resolve, not one file is
+ *   opened and the outcome is `skipped bin_missing` — see `no_bin_no_write`
+ *   below for why a written-but-inert registration is the worse option.
+ * - **Which config shape.** `bli-memory-mcp --print-config --claude` wins when
+ *   the bin answers it; the built-in template of the same shape is the
+ *   fallback for an older server, and it is only ever used with a bin that
+ *   actually resolved.
+ * - **Never throw at the caller.** The sync tick calls this. A failure is a
+ *   named receipt, never an exception that could cost a machine its
+ *   collection tick.
+ * - **Never claim an install it did not read back** (BLI-2541). Both halves
+ *   re-read and re-parse; this module only aggregates what they proved.
+ */
+import os from "node:os";
+import path from "node:path";
+import { writeLine } from "./cli-io.js";
+import { builtinMemoryInstallConfig, isUnsafeBinPath, MEMORY_MCP_BIN, parsePrintedMemoryInstallConfig, } from "./memory-install-contract.js";
+import { defaultMemoryFileIo, } from "./memory-install-files.js";
+import { installClaudeMemoryIntegration, inspectClaudeMemoryIntegration, } from "./memory-install-claude.js";
+import { installCodexMemoryIntegration, inspectCodexMemoryIntegration, } from "./memory-install-codex.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
+export async function runMemoryInstall(command, io, deps = {}) {
+    const outcome = command.action === "status"
+        ? await inspectMemoryIntegration(command, io, deps)
+        : await installMemoryIntegration(command, io, deps);
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify(outcome, null, 2));
+    }
+    else {
+        for (const line of memoryOutcomeLines(outcome))
+            writeLine(io.stdout, line);
+    }
+    return outcome.status === "failed" ? 1 : 0;
+}
+export async function installMemoryIntegration(command, io, deps = {}) {
+    const homeDir = deps.homeDir ?? command.homeDir ?? os.homedir();
+    const platform = deps.platform ?? process.platform;
+    const fileIo = deps.io ?? defaultMemoryFileIo();
+    const resolved = await resolveMemoryConfig(command, io, platform, deps);
+    const targets = [resolved.binTarget];
+    // `no_bin_no_write`: with no resolved server there is nothing safe to
+    // register, so not one file is opened. The bin target carries the reason.
+    if (resolved.config) {
+        targets.push(...(await installClaudeMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            dryRun: command.dryRun,
+            io: fileIo,
+        })));
+        targets.push(...(await installCodexMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            dryRun: command.dryRun,
+            io: fileIo,
+        })));
+    }
+    const outcome = {
+        action: "install",
+        ...aggregate(targets),
+        config_source: resolved.source,
+        bin_found: resolved.config !== null,
+        ...(resolved.bin_source ? { bin_source: resolved.bin_source } : {}),
+        targets,
+    };
+    logMemoryOutcome(outcome, platform);
+    return outcome;
+}
+export async function inspectMemoryIntegration(command, io, deps = {}) {
+    const homeDir = deps.homeDir ?? command.homeDir ?? os.homedir();
+    const platform = deps.platform ?? process.platform;
+    const fileIo = deps.io ?? defaultMemoryFileIo();
+    const resolved = await resolveMemoryConfig(command, io, platform, deps);
+    const targets = [resolved.binTarget];
+    // Without a resolved server there is no shape to compare the stored config
+    // against, so `status` says the one true thing — the server is not here —
+    // rather than reporting four targets against a shape we invented.
+    if (resolved.config) {
+        targets.push(...(await inspectClaudeMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            io: fileIo,
+        })));
+        targets.push(...(await inspectCodexMemoryIntegration({
+            homeDir,
+            config: resolved.config,
+            io: fileIo,
+        })));
+    }
+    return {
+        action: "status",
+        ...aggregate(targets),
+        config_source: resolved.source,
+        bin_found: resolved.config !== null,
+        ...(resolved.bin_source ? { bin_source: resolved.bin_source } : {}),
+        targets,
+    };
+}
+/**
+ * **`no_bin_no_write`.** When `bli-memory-mcp` cannot be resolved, this command
+ * writes NOTHING — not the MCP entry, not the hooks, not the Codex table, not
+ * the skills.
+ *
+ * An earlier revision wrote the registration anyway, on the reasoning that a
+ * correct shape waiting for the package is better than nothing. It is not:
+ * Claude Code RUNS a registered hook. Three hooks pointing at a binary that
+ * does not exist would print a hook failure on every SessionStart, every
+ * prompt and every Stop, on every intern machine, until the package shipped —
+ * a self-inflicted outage in the one surface people look at all day.
+ *
+ * So an absent bin is `skipped bin_missing`: a receipt, not a write. The daily
+ * self-heal retries tomorrow, and the first tick after the package lands does
+ * the whole registration at once.
+ */
+async function resolveMemoryConfig(command, io, platform, deps) {
+    const dashboardUrl = await resolveDashboardUrl(command, deps);
+    const found = await resolveMemoryMcpBin({
+        env: envWithNodeRuntimeOnPath(io.env ?? process.env),
+        platform,
+        fileExists: deps.fileExists,
+        cliEntryPoint: deps.cliEntryPoint,
+    });
+    if (!found) {
+        return {
+            config: null,
+            source: "none",
+            binTarget: {
+                target: "bin",
+                status: "skipped",
+                reason: "bin_missing",
+                detail: `${MEMORY_MCP_BIN} is not installed beside this CLI or on PATH; nothing was written, and the next daily run will try again`,
+            },
+        };
+    }
+    if (isUnsafeBinPath(found.path)) {
+        // A hook command is a shell string by the platform's design. A path that
+        // cannot be quoted safely is not escaped cleverly, and it is not swapped
+        // for a bare name that may resolve to something else either — the install
+        // refuses and says why.
+        return {
+            config: null,
+            source: "none",
+            binTarget: {
+                target: "bin",
+                status: "failed",
+                reason: "bin_path_unsafe",
+                detail: "the resolved bin path contains characters that cannot appear in a hook command; nothing was written",
+            },
+            bin_source: found.source,
+        };
+    }
+    const printed = await printedMemoryConfig(io, found.path);
+    if (printed) {
+        return {
+            config: printed,
+            source: "bin",
+            binTarget: { target: "bin", status: "already", reason: "bin_printed_config" },
+            bin_source: found.source,
+        };
+    }
+    return {
+        config: builtinMemoryInstallConfig({
+            binPath: found.path,
+            platform,
+            dashboardUrl,
+        }),
+        source: "template",
+        binTarget: {
+            target: "bin",
+            status: "already",
+            reason: "bin_present_template_used",
+            detail: "the bin did not print a usable --print-config; the built-in shape was used",
+        },
+        bin_source: found.source,
+    };
+}
+/**
+ * Asks the server for its own shape. Arguments go as an ARRAY — nothing is
+ * interpolated into a command line — and on Windows the captured runner routes
+ * a `.cmd` shim through ComSpec with its own escaping (process-runner.ts).
+ */
+async function printedMemoryConfig(io, binPath) {
+    const exec = io.exec;
+    if (!exec)
+        return null;
+    try {
+        const result = await exec(binPath, ["--print-config", "--claude"]);
+        if (result.code !== 0)
+            return null;
+        return parsePrintedMemoryInstallConfig(result.stdout);
+    }
+    catch {
+        // Deliberately silent here: the caller reports
+        // `bin_present_template_used`, which is the same information with a name
+        // on it, and this path is reached on every machine that has an older bin.
+        return null;
+    }
+}
+/**
+ * Two steps, in this order, and the first is the canonical one.
+ *
+ * **1. Beside the CLI that is running.** `bli-memory-mcp` ships as a DEPENDENCY
+ * of `@bli-cockpit/cli`, so installing the CLI installs the server, and npm
+ * links its bin into a `node_modules/.bin` on the path from this entry point up
+ * to the install root — `…/@bli-cockpit/cli/node_modules/.bin` when it is
+ * nested, `…/lib/node_modules/.bin` when npm hoists it. Walking up from
+ * `process.argv[1]` finds it either way, and it is the ONLY lookup that cannot
+ * find somebody else's `bli-memory-mcp`. Nobody ever runs `npm i -g` for a
+ * second package.
+ *
+ * **2. PATH, as a fallback**, for a linked checkout or a hand-installed server.
+ * Done in this process rather than through `which`/`where`: it spawns nothing,
+ * behaves the same on both host families, and is testable without a fixture
+ * binary. The npm global bin sits beside the running node binary in the
+ * standard layouts, which is why the caller passes a PATH that already includes
+ * it (`envWithNodeRuntimeOnPath`) — the launchd tick's PATH is otherwise
+ * `/usr/bin:/bin:/usr/sbin:/sbin` and would find nothing.
+ */
+export async function resolveMemoryMcpBin(options) {
+    const exists = options.fileExists ?? defaultFileExists;
+    const beside = await resolveBesideCli(options, exists);
+    if (beside)
+        return { path: beside, source: "cli_dependency" };
+    const onPath = await resolveOnPath(options, exists);
+    return onPath ? { path: onPath, source: "path" } : null;
+}
+async function resolveBesideCli(options, exists) {
+    const entry = options.cliEntryPoint ?? process.argv[1];
+    if (!entry)
+        return null;
+    const platformPath = options.platform === "win32" ? path.win32 : path.posix;
+    const extensions = binExtensions(options.platform);
+    let directory = platformPath.dirname(platformPath.resolve(entry));
+    // Bounded walk: deep enough for `…/node_modules/@scope/pkg/dist/cli.js` plus
+    // a hoisted root above it, and it stops at the filesystem root anyway.
+    for (let depth = 0; depth < 12; depth += 1) {
+        for (const extension of extensions) {
+            const candidate = platformPath.join(directory, "node_modules", ".bin", `${MEMORY_MCP_BIN}${extension}`);
+            if (await exists(candidate))
+                return candidate;
+        }
+        const parent = platformPath.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return null;
+}
+async function resolveOnPath(options, exists) {
+    // The TARGET platform's path rules, not the running one's. On a real machine
+    // they are the same; asking for them explicitly is what lets the Windows
+    // lookup be tested from a Mac, which is the only Windows proof this repo
+    // gets before a release (AGENTS.md, supported fleet).
+    const platformPath = options.platform === "win32" ? path.win32 : path.posix;
+    const entries = (options.env["PATH"] ?? options.env["Path"] ?? "")
+        .split(platformPath.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const entry of entries) {
+        for (const extension of binExtensions(options.platform)) {
+            const candidate = platformPath.join(entry, `${MEMORY_MCP_BIN}${extension}`);
+            if (await exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** npm writes `.cmd` (and `.ps1`) shims on Windows; POSIX gets the bare name. */
+function binExtensions(platform) {
+    return platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+}
+async function defaultFileExists(file) {
+    const { stat } = await import("node:fs/promises");
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+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;
+}
+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" };
+    }
+    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.
+ */
+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}`),
+    };
+    // 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];
+    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;
+}

package/dist/commands/onboard-receipts.js

@@ -0,0 +1,66 @@
+/**
+ * What onboarding records about itself: one install-event step per thing it
+ * did, and the blocker label a failure earns.
+ *
+ * Split out of commands/onboard.ts (BLI-3578), moved verbatim. It is the same
+ * ledger `./install-receipts.ts` posts for every command — this module only
+ * decides which step a given onboarding outcome belongs to, so the runbook next
+ * door never has to.
+ */
+import { addInstallEvent } from "./install-receipts.js";
+import { COLLECTION_ROOT_REQUIRED } from "../onboarding-roots.js";
+export function addOnboardFailureEvent(events, blocker) {
+    const step = onboardFailureStep(blocker, events);
+    const existing = events.find((event) => event.step === step && event.status === "fail");
+    if (existing)
+        return;
+    addInstallEvent(events, step, "fail", blocker);
+}
+function onboardFailureStep(blocker, events) {
+    if (blocker === COLLECTION_ROOT_REQUIRED)
+        return "install";
+    if (blocker === "device_pairing")
+        return "pair";
+    if (blocker === "work_context" || blocker === "ticket_binding" || blocker === "ticket") {
+        return "work_context";
+    }
+    if (blocker === "network_or_ingest")
+        return "sync";
+    if (blocker === "install")
+        return "install";
+    const lastIncomplete = ["install", "auth", "pair", "work_context", "sync"].find((step) => !events.some((event) => event.step === step));
+    return lastIncomplete ?? "sync";
+}
+export function addAutostartInstallEvent(events, result) {
+    if (!result) {
+        addInstallEvent(events, "autostart", "skipped", "runner_unavailable");
+        return;
+    }
+    if (result.status === "unsupported") {
+        addInstallEvent(events, "autostart", "skipped", "unsupported", result.message);
+        return;
+    }
+    addInstallEvent(events, "autostart", result.loaded === false ? "fail" : "ok", result.loaded === false ? "autostart_load_failed" : undefined, result.loaded === false ? result.message : undefined);
+}
+export function onboardAutostartFailed(result) {
+    return (result !== null &&
+        result.status !== "unsupported" &&
+        result.loaded === false);
+}
+export function classifyOnboardBlocker(message) {
+    if (message.includes(COLLECTION_ROOT_REQUIRED))
+        return COLLECTION_ROOT_REQUIRED;
+    if (/ticket/i.test(message))
+        return "ticket";
+    if (/pair|paired|approval|expired|revoked/i.test(message))
+        return "device_pairing";
+    if (/fetch|network|ENOTFOUND|ECONNREFUSED|HTTP/i.test(message))
+        return "network_or_ingest";
+    if (/config|install/i.test(message))
+        return "install";
+    if (/context|start/i.test(message))
+        return "work_context";
+    if (/bound|binding/i.test(message))
+        return "ticket_binding";
+    return "unknown";
+}