@bli-cockpit/cli 0.2.49 → 0.2.51

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

@@ -0,0 +1,286 @@
+/**
+ * The interface this installer consumes from `@bli-cockpit/memory-mcp`
+ * (BLI-3580, core slice on branch `edward/bli-3580-agent-memory-core`).
+ *
+ * That package does not exist on `main` yet, and the two pull requests must be
+ * able to land in either order — so the contract lives HERE, in one small
+ * module, and is stated twice on purpose:
+ *
+ *   1. `bli-memory-mcp --print-config --claude` prints the JSON below, and
+ *      `--print-config --codex` prints the TOML table below. When the bin
+ *      resolves, what it prints WINS: the server knows its own shape.
+ *   2. `builtinMemoryInstallConfig()` is the same shape, built locally, for a
+ *      server that resolved but does not answer `--print-config` yet.
+ *
+ * Both require a RESOLVED bin. A machine that does not have the server gets
+ * nothing written at all and a `skipped bin_missing` receipt — the template is
+ * a fallback for an older server, never a substitute for an absent one
+ * (`no_bin_no_write`, memory-install.ts).
+ *
+ * The printed JSON contract (`--print-config --claude`):
+ *
+ * ```json
+ * {
+ *   "schema": "bli-memory-install-config.v1",
+ *   "server_id": "bli-memory",
+ *   "mcp_server": { "command": "bli-memory-mcp", "args": [], "env": {} },
+ *   "hooks": [
+ *     { "event": "SessionStart",     "command": "bli-memory-mcp hook session-start", "timeout_seconds": 30 },
+ *     { "event": "UserPromptSubmit", "command": "bli-memory-mcp hook prompt",        "timeout_seconds": 5 },
+ *     { "event": "Stop",             "command": "bli-memory-mcp hook stop",          "timeout_seconds": 30 }
+ *   ],
+ *   "permissions_allow": ["mcp__bli-memory__search_memory"]
+ * }
+ * ```
+ *
+ * The printed TOML contract (`--print-config --codex`) is exactly one table:
+ *
+ * ```toml
+ * [mcp_servers.bli-memory]
+ * command = "bli-memory-mcp"
+ * args = []
+ * env = { COCKPIT_DASHBOARD_URL = "https://…" }
+ * ```
+ *
+ * **The printed `command` is a bare name and is never written as-is.** The bin
+ * cannot know where it was installed, and it lives nested inside
+ * `@bli-cockpit/cli`'s `node_modules` rather than on PATH — so
+ * `withResolvedBinPath` re-points every command at the absolute path this
+ * machine resolved before anything is written. Skipping that step registered
+ * three hooks that answered `command not found` on every turn.
+ *
+ * Nothing here touches the filesystem. The halves that do are
+ * `memory-install-claude.ts` and `memory-install-codex.ts`.
+ */
+/** The published bin name. Both hosts spawn this. */
+export const MEMORY_MCP_BIN = "bli-memory-mcp";
+/** The MCP server id, as it appears in `mcp__<server>__<tool>`. */
+export const MEMORY_MCP_SERVER_ID = "bli-memory";
+/** The one env var the server is handed. A URL, never a token. */
+export const MEMORY_DASHBOARD_URL_ENV = "COCKPIT_DASHBOARD_URL";
+/** Claude Code hook events this installer registers, in the order it writes them. */
+export const MEMORY_HOOK_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "Stop",
+];
+/**
+ * The bin's own hook subcommands. `session-start` recalls at session open,
+ * `prompt` recalls per turn, `stop` saves the turn — the same three jobs the
+ * Supermemory plugin's `session-start.js` / `recall-directive.js` / `capture.js`
+ * did, collapsed onto one bin.
+ */
+export const MEMORY_HOOK_SUBCOMMAND = {
+    SessionStart: "hook session-start",
+    UserPromptSubmit: "hook prompt",
+    Stop: "hook stop",
+};
+/**
+ * Injection hooks must stay fast — Claude Code discards a hook that outlives
+ * its timeout, and a recall that arrives late is a recall that did not happen.
+ * These mirror the vendor plugin's own budgets (30 s / 5 s / 30 s).
+ */
+export const MEMORY_HOOK_TIMEOUT_SECONDS = {
+    SessionStart: 30,
+    UserPromptSubmit: 5,
+    Stop: 30,
+};
+/**
+ * Auto-approved tools. READ ONLY, deliberately: the vendor's
+ * `recall-approve.js` allowed its read set and left every write prompting, and
+ * a memory the agent can silently overwrite is worse than one it has to ask
+ * about. `save_memory` / `update_memory` / `forget_memory` are absent on purpose.
+ */
+export const MEMORY_AUTO_APPROVE_TOOLS = [
+    `mcp__${MEMORY_MCP_SERVER_ID}__search_memory`,
+];
+/** Characters that would let a resolved path change the meaning of a hook command string. */
+const UNSAFE_PATH_CHARACTERS = /["'`$;&|<>\r\n]/u;
+export function isUnsafeBinPath(binPath) {
+    return UNSAFE_PATH_CHARACTERS.test(binPath);
+}
+/**
+ * A Claude Code hook `command` is a shell string by the platform's design, so
+ * the only defence is quoting — and a path that could not be quoted safely is
+ * refused upstream (see `resolveMemoryMcpBin`) rather than escaped cleverly.
+ */
+export function shellQuoteBinPath(binPath) {
+    return /\s/u.test(binPath) ? `"${binPath}"` : binPath;
+}
+/**
+ * Windows cannot spawn an npm `.cmd` shim directly — Node refuses it without a
+ * shell, which is why `commands/editor.ts` REFUSES a `.cmd` editor rather than
+ * running it through cmd.exe with a person's path interpolated in. Here the
+ * path is ours, not a person's, and both hosts spawn the MCP server themselves
+ * with an argument array, so `cmd /c <shim>` is the correct and safe shape: the
+ * arguments never become one string we built.
+ */
+export function memoryMcpServerEntry(options) {
+    const env = options.dashboardUrl
+        ? { [MEMORY_DASHBOARD_URL_ENV]: options.dashboardUrl }
+        : {};
+    if (options.platform === "win32") {
+        return { command: "cmd", args: ["/c", options.binPath], env };
+    }
+    return { command: options.binPath, args: [], env };
+}
+export function builtinMemoryInstallConfig(options) {
+    const quoted = shellQuoteBinPath(options.binPath);
+    return {
+        server_id: MEMORY_MCP_SERVER_ID,
+        mcp_server: memoryMcpServerEntry(options),
+        hooks: MEMORY_HOOK_EVENTS.map((event) => ({
+            event,
+            command: `${quoted} ${MEMORY_HOOK_SUBCOMMAND[event]}`,
+            timeout_seconds: MEMORY_HOOK_TIMEOUT_SECONDS[event],
+        })),
+        permissions_allow: [...MEMORY_AUTO_APPROVE_TOOLS],
+    };
+}
+/**
+ * Recognises a hook entry as OURS, wherever the bin ended up and however it was
+ * quoted. Identity is the bin name followed by `hook`, so an absolute path, a
+ * `.cmd` shim and a bare name all match — and somebody else's hook never does.
+ * This is what makes a re-run replace our three entries instead of appending a
+ * fourth copy.
+ */
+export function isMemoryHookCommand(command) {
+    return new RegExp(`${escapeRegExp(MEMORY_MCP_BIN)}(?:\\.cmd|\\.exe|\\.bat)?["']?\\s+hook\\b`, "u").test(command);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+/**
+ * Parses what `bli-memory-mcp --print-config --claude` printed. Anything that
+ * is not the documented shape returns null and the caller falls back to the
+ * built-in template with a named reason — a half-understood config is worse
+ * than the one we can write ourselves.
+ */
+export function parsePrintedMemoryInstallConfig(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const record = parsed;
+    const server = record["mcp_server"];
+    if (!server || typeof server !== "object")
+        return null;
+    const serverRecord = server;
+    const command = serverRecord["command"];
+    if (typeof command !== "string" || !command.trim())
+        return null;
+    const args = normalizeStringArray(serverRecord["args"]);
+    const env = normalizeStringRecord(serverRecord["env"]);
+    if (args === null || env === null)
+        return null;
+    const rawHooks = record["hooks"];
+    if (!Array.isArray(rawHooks))
+        return null;
+    const hooks = [];
+    for (const rawHook of rawHooks) {
+        if (!rawHook || typeof rawHook !== "object")
+            return null;
+        const hookRecord = rawHook;
+        const event = hookRecord["event"];
+        const hookCommand = hookRecord["command"];
+        if (typeof event !== "string" || typeof hookCommand !== "string")
+            return null;
+        if (!MEMORY_HOOK_EVENTS.includes(event))
+            return null;
+        const timeout = hookRecord["timeout_seconds"];
+        hooks.push({
+            event: event,
+            command: hookCommand,
+            timeout_seconds: typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
+                ? timeout
+                : MEMORY_HOOK_TIMEOUT_SECONDS[event],
+        });
+    }
+    if (hooks.length === 0)
+        return null;
+    const allow = normalizeStringArray(record["permissions_allow"]);
+    const serverId = record["server_id"];
+    return {
+        server_id: typeof serverId === "string" && serverId.trim()
+            ? serverId.trim()
+            : MEMORY_MCP_SERVER_ID,
+        mcp_server: { command, args, env },
+        hooks,
+        permissions_allow: allow ?? [...MEMORY_AUTO_APPROVE_TOOLS],
+    };
+}
+/**
+ * Put THIS machine's resolved bin path into a config the bin printed.
+ *
+ * The printed contract says `command: "bli-memory-mcp"` — a bare name, because
+ * the bin has no idea where it was installed. `bli-memory-mcp` is a DEPENDENCY
+ * of `@bli-cockpit/cli`, nested inside its `node_modules`, and therefore **not
+ * on anybody's PATH**: a host handed the bare name answers `command not found`
+ * on every SessionStart, every prompt and every Stop. The installer is the only
+ * thing that knows the absolute path, so path qualification happens here and
+ * the printed strings are never written verbatim (BLI-3580; found by running
+ * the registered hook command in a simulated global install, not by reading
+ * the code).
+ *
+ * What the printed config still owns: which hook EVENTS exist, their
+ * subcommands, their timeouts, the server id and the allow-list. What this
+ * function owns: where the program is, and the per-platform launch shape.
+ *
+ * Returns null when a printed hook command cannot be understood well enough to
+ * re-point — the caller then falls back to the built-in template, which is
+ * always path-qualified. Guessing at a command we cannot parse would write a
+ * hook that runs something else.
+ */
+export function withResolvedBinPath(config, options) {
+    const quoted = shellQuoteBinPath(options.binPath);
+    const hooks = [];
+    for (const hook of config.hooks) {
+        const tail = hookSubcommandTail(hook.command);
+        if (!tail)
+            return null;
+        hooks.push({ ...hook, command: `${quoted} ${tail}` });
+    }
+    const entry = memoryMcpServerEntry(options);
+    return {
+        ...config,
+        // The bin's own env wins nothing and loses nothing: it prints `{}`, and the
+        // dashboard URL is a machine fact the installer holds.
+        mcp_server: { ...entry, env: { ...config.mcp_server.env, ...entry.env } },
+        hooks,
+    };
+}
+/**
+ * `…/bli-memory-mcp hook prompt` → `hook prompt`. The subcommand is the part we
+ * keep; everything before it is a path that may be wrong for this machine.
+ */
+function hookSubcommandTail(command) {
+    const match = /(^|\s)(hook\s+\S+.*)$/u.exec(command.trim());
+    return match?.[2]?.trim() ?? null;
+}
+function normalizeStringArray(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return null;
+    if (!value.every((entry) => typeof entry === "string"))
+        return null;
+    return value;
+}
+function normalizeStringRecord(value) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== "string")
+            return null;
+        out[key] = entry;
+    }
+    return out;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * The one filesystem seam `cockpit memory install` writes through.
+ *
+ * It exists for two reasons. The first is production: every file this installer
+ * touches belongs to a host that may be RUNNING while we write — Claude Code
+ * rewrites `~/.claude.json` on its own schedule — so the write is staged beside
+ * the target and renamed over it, which is the closest thing to atomic either
+ * host family offers. A reader never sees a half-written config.
+ *
+ * The second is proof. The read-back check (BLI-2541) is only worth something if
+ * a test can make the stored bytes differ from the written ones; injecting this
+ * interface is how `memory-install.test.ts` proves `read_back_mismatch` fires
+ * instead of asserting that it would.
+ */
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { describeError, isMissingFileFailure } from "../health-detail.js";
+export function defaultMemoryFileIo() {
+    return {
+        async readText(file) {
+            try {
+                return await readFile(file, "utf8");
+            }
+            catch (error) {
+                if (isMissingFileFailure(error))
+                    return null;
+                throw error;
+            }
+        },
+        async writeText(file, contents) {
+            await mkdir(path.dirname(file), { recursive: true });
+            const staged = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+            // A staged file is created with the process umask and the rename carries
+            // that mode onto the target — so a `~/.claude.json` or `~/.codex/config.toml`
+            // the person keeps at 0600 would come out 0644, quietly widened by an
+            // installer that was only meant to add one key. Carry the existing mode
+            // across; a file that does not exist yet keeps the umask default.
+            const existingMode = await stat(file)
+                .then((info) => info.mode & 0o777)
+                .catch(() => null);
+            try {
+                await writeFile(staged, contents, "utf8");
+                if (existingMode !== null)
+                    await chmod(staged, existingMode);
+                await rename(staged, file);
+            }
+            catch (error) {
+                // A rename that will not land (a locked destination on Windows, a
+                // cross-device staging directory) must not lose the write — and it must
+                // say which of the two happened, because "install failed" on a config
+                // file is exactly the silent failure the fleet contract forbids.
+                console.error("[memory-install] staged write could not be renamed; writing in place", JSON.stringify({
+                    reason: "staged_rename_failed",
+                    byte_size: contents.length,
+                    ...describeError(error),
+                }));
+                await unlink(staged).catch(() => undefined);
+                await writeFile(file, contents, "utf8");
+            }
+        },
+    };
+}

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

@@ -0,0 +1,121 @@
+/**
+ * The Codex skill `cockpit memory install` writes to
+ * `~/.codex/skills/bli-memory/` (BLI-3580).
+ *
+ * It replaces the role of the four vendor skills a Codex machine carries today
+ * (`supermemory-search`, `-save`, `-forget`, `-login`): one discoverable skill
+ * directory with `SKILL.md` as the index and one reference per operation —
+ * search, save, update, forget. There is no login reference because there is no
+ * fourth credential: the MCP server authenticates with the collector's own
+ * device token, the one `cockpit login` already put on the machine.
+ *
+ * Content is static prose. It is written whole and compared whole, so an
+ * install is idempotent to the byte and a drifted copy is replaced rather than
+ * merged — the same deal `cockpit agent-rules` offers for its managed block.
+ */
+/** Relative path → exact file contents. The map IS the install. */
+export function memoryCodexSkillFiles() {
+    return {
+        "SKILL.md": SKILL_MD,
+        "references/search.md": SEARCH_MD,
+        "references/save.md": SAVE_MD,
+        "references/update.md": UPDATE_MD,
+        "references/forget.md": FORGET_MD,
+    };
+}
+const SKILL_MD = `---
+name: bli-memory
+description: BLI Memory — durable memory for this machine. Use when you need to recall what was decided before, or when a session produced a durable decision, preference or correction worth keeping.
+---
+
+# BLI Memory
+
+Durable memory lives in BLI's own store, reached through the \`bli-memory\` MCP
+server. Four tools, and nothing else:
+
+| Tool | When |
+|---|---|
+| \`search_memory\` | before answering anything that depends on earlier work |
+| \`save_memory\` | a durable decision, preference, correction or constraint appeared |
+| \`update_memory\` | a saved memory is now wrong and has a successor |
+| \`forget_memory\` | a saved memory should never surface again |
+
+Rules that do not bend:
+
+- **Recall before you assert.** An empty result means the record is silent, not
+  that nothing happened. Say which one you are looking at.
+- **Save the decision, not the transcript.** The nightly rollups already
+  distil sessions; this store is for the durable line a person would repeat.
+- **Never fuzzy-match when forgetting.** Exact id, or exact text inside one
+  container. Deleting the wrong memory is worse than keeping a stale one.
+- **Say what you did.** A save that produced an id says so; a search that
+  answered from memory credits it.
+
+References: \`references/search.md\`, \`references/save.md\`,
+\`references/update.md\`, \`references/forget.md\`.
+
+Installed and kept current by \`cockpit memory install\`. Do not edit by hand —
+the next sync tick replaces it.
+`;
+const SEARCH_MD = `# search_memory
+
+\`\`\`
+in : { query: string (1-1000, required),
+       containerTag?: string,   // omitted -> this machine's default container
+       limit?: 1-20 = 5,
+       includeProfile?: boolean = true }
+\`\`\`
+
+Returns relevance-ranked memories plus, when \`includeProfile\`, the container's
+most recent context. Rows that were forgotten or superseded are unreachable by
+construction and never come back.
+
+An empty answer is a finding: report "the record is silent on this", never
+"there is nothing".
+`;
+const SAVE_MD = `# save_memory
+
+\`\`\`
+in : { content: string (1-200000, required),
+       containerTag?: string,
+       customId?: string,       // e.g. the session id — the upsert key
+       metadata?: object }
+out: { id, containerTag, created|updated, chars }
+\`\`\`
+
+Stores what it is given; it does not summarise. Pass \`customId\` when a session
+may save more than once, so the second save updates the first row instead of
+adding a duplicate.
+
+Save the durable thing: a decision and its reason, a preference, a correction, a
+constraint discovered the hard way. Do not save the whole transcript.
+`;
+const UPDATE_MD = `# update_memory
+
+\`\`\`
+in : { id: uuid (required), content: string (required), metadata?: object }
+out: { newId, supersededId, containerTag, reEmbedded: true }
+\`\`\`
+
+An update is an insert plus a link: the new text becomes a new row, the old one
+is marked superseded and stops being reachable from recall while staying
+readable for audit.
+
+It refuses — loudly, never silently — when the id is unknown, already forgotten,
+or already superseded. The last case names the successor so you can retry
+against it.
+`;
+const FORGET_MD = `# forget_memory
+
+\`\`\`
+in : { id?: uuid, content?: string, containerTag?: string, reason?: string }
+     exactly one of id | content; containerTag is REQUIRED with content
+out: { forgotten: [{ id, containerTag, textPreview, created_at }], count }
+\`\`\`
+
+Soft delete: the row is marked forgotten and never surfaces through recall
+again. Matching by content is exact after whitespace normalisation — never
+fuzzy, and never widened to every container.
+
+It returns what it removed. A bare "done" is not an answer.
+`;