@bli-cockpit/cli 0.2.49 → 0.2.51

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

@@ -0,0 +1,294 @@
+/**
+ * The Claude Code half of `cockpit memory install` (BLI-3580).
+ *
+ * TWO files, because Claude Code reads two:
+ *
+ *   ~/.claude.json            user-scope MCP servers, under top-level
+ *                             `mcpServers`. This is where `claude mcp add
+ *                             --scope user` puts a server, and — per the
+ *                             BLI-3580 touchpoint survey — the ONLY place a
+ *                             non-plugin server can be registered for every
+ *                             project on the machine. The Supermemory plugin
+ *                             reached Claude Code through its own marketplace
+ *                             `.mcp.json`; we are not a plugin, so we write a
+ *                             direct user-scope entry instead.
+ *   ~/.claude/settings.json   `hooks` (the three recall/save hooks) and
+ *                             `permissions.allow` (auto-approve for the
+ *                             read-only tool, the documented equivalent of the
+ *                             vendor's PreToolUse regex trick).
+ *
+ * Three rules govern every write here:
+ *
+ * 1. **Merge, never clobber.** Both files belong to the person. Every other
+ *    key, every other MCP server and every other hook comes out untouched, and
+ *    a file that will not parse is a REFUSAL (`config_unreadable`), never an
+ *    overwrite — the opposite of what `agent-rules.ts` may do to a markdown
+ *    file, because losing a person's whole Claude configuration is a different
+ *    order of damage from losing a rules block.
+ * 2. **Idempotent by identity.** Our hook entries are recognised by the bin
+ *    name (`isMemoryHookCommand`), so a re-run replaces exactly our three and
+ *    appends nothing.
+ * 3. **Read back what the platform stored** (BLI-2541). A write that returned
+ *    without throwing is not proof. The file is re-read, re-parsed and compared
+ *    field by field; a difference is `read_back_mismatch` and the target is
+ *    reported failed.
+ */
+import path from "node:path";
+import { isMemoryHookCommand, } from "./memory-install-contract.js";
+export function claudeMcpConfigFile(homeDir) {
+    return path.join(homeDir, ".claude.json");
+}
+export function claudeSettingsFile(homeDir) {
+    return path.join(homeDir, ".claude", "settings.json");
+}
+export async function installClaudeMemoryIntegration(options) {
+    return [
+        await applyJsonTarget({
+            target: "claude_mcp",
+            file: claudeMcpConfigFile(options.homeDir),
+            options,
+            apply: (root) => applyMcpServer(root, options.config),
+            matches: (root) => mcpServerMatches(root, options.config),
+        }),
+        await applyJsonTarget({
+            target: "claude_hooks",
+            file: claudeSettingsFile(options.homeDir),
+            options,
+            apply: (root) => applyHooksAndPermissions(root, options.config),
+            matches: (root) => hooksAndPermissionsMatch(root, options.config),
+        }),
+    ];
+}
+export async function inspectClaudeMemoryIntegration(options) {
+    return [
+        await inspectJsonTarget({
+            target: "claude_mcp",
+            file: claudeMcpConfigFile(options.homeDir),
+            io: options.io,
+            present: (root) => readMcpServer(root, options.config.server_id) !== null,
+            matches: (root) => mcpServerMatches(root, options.config),
+        }),
+        await inspectJsonTarget({
+            target: "claude_hooks",
+            file: claudeSettingsFile(options.homeDir),
+            io: options.io,
+            present: (root) => ourHookCount(root) > 0,
+            matches: (root) => hooksAndPermissionsMatch(root, options.config),
+        }),
+    ];
+}
+async function applyJsonTarget(input) {
+    const { file, options } = input;
+    const raw = await input.options.io.readText(file);
+    let root;
+    if (raw === null || !raw.trim()) {
+        root = {};
+    }
+    else {
+        const parsed = parseJsonRecord(raw);
+        if (!parsed) {
+            // Refuse rather than replace. A `~/.claude.json` that will not parse
+            // still holds the person's project history and their other servers.
+            return failure(input.target, file, "config_unreadable", "the file is not valid JSON; fix it and re-run");
+        }
+        root = parsed;
+    }
+    if (input.matches(root)) {
+        return { target: input.target, status: "already", reason: "already_current", path: file };
+    }
+    const next = input.apply(structuredClone(root));
+    const serialized = serializeJson(next, raw ?? "");
+    if (options.dryRun) {
+        return {
+            target: input.target,
+            status: "would_install",
+            reason: "dry_run",
+            path: file,
+        };
+    }
+    try {
+        await options.io.writeText(file, serialized);
+    }
+    catch (error) {
+        return failure(input.target, file, "write_failed", error instanceof Error ? error.message : String(error));
+    }
+    // BLI-2541: what the platform stored, not what we sent it.
+    const storedRaw = await options.io.readText(file);
+    const stored = storedRaw === null ? null : parseJsonRecord(storedRaw);
+    if (!stored || !input.matches(stored)) {
+        return failure(input.target, file, "read_back_mismatch", "the file on disk does not contain the entry that was just written");
+    }
+    return { target: input.target, status: "installed", reason: "wrote_entry", path: file };
+}
+async function inspectJsonTarget(input) {
+    const raw = await input.io.readText(input.file);
+    if (raw === null || !raw.trim()) {
+        return { target: input.target, status: "missing", reason: "file_absent", path: input.file };
+    }
+    const root = parseJsonRecord(raw);
+    if (!root) {
+        return failure(input.target, input.file, "config_unreadable", "the file is not valid JSON");
+    }
+    if (input.matches(root)) {
+        return { target: input.target, status: "installed", reason: "already_current", path: input.file };
+    }
+    const status = input.present(root) ? "mismatch" : "missing";
+    return {
+        target: input.target,
+        status,
+        reason: status === "mismatch" ? "entry_differs" : "entry_absent",
+        path: input.file,
+    };
+}
+function applyMcpServer(root, config) {
+    const servers = asRecord(root["mcpServers"]) ?? {};
+    servers[config.server_id] = {
+        command: config.mcp_server.command,
+        args: config.mcp_server.args,
+        ...(Object.keys(config.mcp_server.env).length > 0
+            ? { env: config.mcp_server.env }
+            : {}),
+    };
+    root["mcpServers"] = servers;
+    return root;
+}
+function readMcpServer(root, serverId) {
+    const servers = asRecord(root["mcpServers"]);
+    if (!servers)
+        return null;
+    return asRecord(servers[serverId]);
+}
+function mcpServerMatches(root, config) {
+    const entry = readMcpServer(root, config.server_id);
+    if (!entry)
+        return false;
+    if (entry["command"] !== config.mcp_server.command)
+        return false;
+    if (!sameStringArray(entry["args"], config.mcp_server.args))
+        return false;
+    const env = asRecord(entry["env"]) ?? {};
+    for (const [key, value] of Object.entries(config.mcp_server.env)) {
+        if (env[key] !== value)
+            return false;
+    }
+    return true;
+}
+/**
+ * Claude Code's hook shape, verbatim: `hooks.<Event>` is an ARRAY of matcher
+ * groups, each `{ matcher?, hooks: [{ type: "command", command, timeout? }] }`.
+ * The matcher is omitted on purpose — all three events want every source.
+ */
+function applyHooksAndPermissions(root, config) {
+    const hooks = asRecord(root["hooks"]) ?? {};
+    for (const spec of config.hooks) {
+        const groups = Array.isArray(hooks[spec.event])
+            ? hooks[spec.event].slice()
+            : [];
+        const survivors = groups.filter((group) => !groupIsOurs(group));
+        survivors.push({
+            hooks: [
+                {
+                    type: "command",
+                    command: spec.command,
+                    timeout: spec.timeout_seconds,
+                },
+            ],
+        });
+        hooks[spec.event] = survivors;
+    }
+    root["hooks"] = hooks;
+    if (config.permissions_allow.length > 0) {
+        const permissions = asRecord(root["permissions"]) ?? {};
+        const allow = Array.isArray(permissions["allow"])
+            ? permissions["allow"].filter((entry) => typeof entry === "string")
+            : [];
+        for (const rule of config.permissions_allow) {
+            if (!allow.includes(rule))
+                allow.push(rule);
+        }
+        permissions["allow"] = allow;
+        root["permissions"] = permissions;
+    }
+    return root;
+}
+function hooksAndPermissionsMatch(root, config) {
+    const hooks = asRecord(root["hooks"]);
+    if (!hooks)
+        return false;
+    for (const spec of config.hooks) {
+        const groups = Array.isArray(hooks[spec.event]) ? hooks[spec.event] : [];
+        const ours = groups.filter(groupIsOurs);
+        if (ours.length !== 1)
+            return false;
+        const commands = hookCommands(ours[0]);
+        if (commands.length !== 1 || commands[0] !== spec.command)
+            return false;
+    }
+    const allow = asRecord(root["permissions"])?.["allow"];
+    const allowed = Array.isArray(allow) ? allow : [];
+    return config.permissions_allow.every((rule) => allowed.includes(rule));
+}
+function ourHookCount(root) {
+    const hooks = asRecord(root["hooks"]);
+    if (!hooks)
+        return 0;
+    let count = 0;
+    for (const value of Object.values(hooks)) {
+        if (!Array.isArray(value))
+            continue;
+        count += value.filter(groupIsOurs).length;
+    }
+    return count;
+}
+function groupIsOurs(group) {
+    return hookCommands(group).some(isMemoryHookCommand);
+}
+function hookCommands(group) {
+    const record = asRecord(group);
+    if (!record || !Array.isArray(record["hooks"]))
+        return [];
+    return record["hooks"]
+        .map((entry) => asRecord(entry)?.["command"])
+        .filter((command) => typeof command === "string");
+}
+function failure(target, file, reason, detail) {
+    return { target, status: "failed", reason, path: file, detail };
+}
+function parseJsonRecord(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function sameStringArray(value, expected) {
+    if (!Array.isArray(value))
+        return expected.length === 0;
+    return (value.length === expected.length &&
+        value.every((entry, index) => entry === expected[index]));
+}
+/**
+ * Keeps the file's own indentation. Claude Code rewrites `~/.claude.json`
+ * itself, so this is cosmetic — but a diff that reindents a person's whole
+ * configuration reads like damage even when it is not.
+ */
+function serializeJson(root, previous) {
+    const indent = detectIndent(previous);
+    return `${JSON.stringify(root, null, indent)}\n`;
+}
+function detectIndent(previous) {
+    const match = previous.match(/\n([ \t]+)"/u);
+    if (!match)
+        return 2;
+    const whitespace = match[1] ?? "  ";
+    return whitespace.startsWith("\t") ? "\t" : whitespace.length;
+}

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

@@ -0,0 +1,205 @@
+/**
+ * The Codex half of `cockpit memory install` (BLI-3580).
+ *
+ * TWO targets:
+ *
+ *   ~/.codex/config.toml            one table, `[mcp_servers.bli-memory]`.
+ *   ~/.codex/skills/bli-memory/     the skill that teaches Codex when to
+ *                                   recall, save, update and forget — taking
+ *                                   over the job the four `supermemory-*`
+ *                                   skills did on Edward's machine.
+ *
+ * **`config.toml` is somebody's own configuration and is treated that way.**
+ * The standing rule for that file is "never change HIS settings"; this respects
+ * it literally by touching one table and nothing else. The write is a line-span
+ * swap (see `memory-install-toml.ts`), not a parse-and-reserialise, so model,
+ * approval policy, sandbox settings, comments and every other MCP server come
+ * out byte-identical — which a test asserts by comparing the bytes outside our
+ * span before and after.
+ *
+ * The skill files are ours end to end, so they are written whole and compared
+ * whole: a person who edited one gets it replaced on the next install, which is
+ * the same deal `cockpit agent-rules` offers for its managed block.
+ */
+import path from "node:path";
+import { MEMORY_MCP_SERVER_ID, } from "./memory-install-contract.js";
+import { findTomlTableSpan, readTomlTable, renderTomlTable, upsertTomlTable, } from "./memory-install-toml.js";
+import { memoryCodexSkillFiles } from "./memory-install-skills.js";
+const MEMORY_TOML_PATH = ["mcp_servers", MEMORY_MCP_SERVER_ID];
+export function codexConfigFile(homeDir) {
+    return path.join(homeDir, ".codex", "config.toml");
+}
+export function codexSkillDirectory(homeDir) {
+    return path.join(homeDir, ".codex", "skills", MEMORY_MCP_SERVER_ID);
+}
+export async function installCodexMemoryIntegration(options) {
+    return [
+        await applyCodexMcpTable(options),
+        await applyCodexSkills(options),
+    ];
+}
+export async function inspectCodexMemoryIntegration(options) {
+    const file = codexConfigFile(options.homeDir);
+    const raw = await options.io.readText(file);
+    const mcp = raw === null
+        ? { target: "codex_mcp", status: "missing", reason: "file_absent", path: file }
+        : tableMatches(raw, options.config)
+            ? { target: "codex_mcp", status: "installed", reason: "already_current", path: file }
+            : findTomlTableSpan(raw, MEMORY_TOML_PATH)
+                ? { target: "codex_mcp", status: "mismatch", reason: "entry_differs", path: file }
+                : { target: "codex_mcp", status: "missing", reason: "entry_absent", path: file };
+    const directory = codexSkillDirectory(options.homeDir);
+    const files = memoryCodexSkillFiles();
+    let present = 0;
+    let current = 0;
+    for (const [relative, contents] of Object.entries(files)) {
+        const stored = await options.io.readText(path.join(directory, relative));
+        if (stored === null)
+            continue;
+        present += 1;
+        if (stored === contents)
+            current += 1;
+    }
+    const total = Object.keys(files).length;
+    const skills = current === total
+        ? { target: "codex_skills", status: "installed", reason: "already_current", path: directory }
+        : present === 0
+            ? { target: "codex_skills", status: "missing", reason: "entry_absent", path: directory }
+            : {
+                target: "codex_skills",
+                status: "mismatch",
+                reason: "entry_differs",
+                path: directory,
+                detail: `${current} of ${total} skill files current`,
+            };
+    return [mcp, skills];
+}
+async function applyCodexMcpTable(options) {
+    const file = codexConfigFile(options.homeDir);
+    const raw = (await options.io.readText(file)) ?? "";
+    if (tableMatches(raw, options.config)) {
+        return { target: "codex_mcp", status: "already", reason: "already_current", path: file };
+    }
+    const next = upsertTomlTable(raw, MEMORY_TOML_PATH, renderMemoryTable(options.config));
+    if (options.dryRun) {
+        return { target: "codex_mcp", status: "would_install", reason: "dry_run", path: file };
+    }
+    try {
+        await options.io.writeText(file, next);
+    }
+    catch (error) {
+        return {
+            target: "codex_mcp",
+            status: "failed",
+            reason: "write_failed",
+            path: file,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // BLI-2541: parse the table back out of the stored bytes the way Codex will
+    // read it. A successful write is not a correct registration.
+    const stored = await options.io.readText(file);
+    if (stored === null || !tableMatches(stored, options.config)) {
+        return {
+            target: "codex_mcp",
+            status: "failed",
+            reason: "read_back_mismatch",
+            path: file,
+            detail: "the table on disk does not parse back to the entry that was written",
+        };
+    }
+    return { target: "codex_mcp", status: "installed", reason: "wrote_entry", path: file };
+}
+async function applyCodexSkills(options) {
+    const directory = codexSkillDirectory(options.homeDir);
+    const files = memoryCodexSkillFiles();
+    const stale = [];
+    for (const [relative, contents] of Object.entries(files)) {
+        const stored = await options.io.readText(path.join(directory, relative));
+        if (stored !== contents)
+            stale.push(relative);
+    }
+    if (stale.length === 0) {
+        return {
+            target: "codex_skills",
+            status: "already",
+            reason: "already_current",
+            path: directory,
+        };
+    }
+    if (options.dryRun) {
+        return {
+            target: "codex_skills",
+            status: "would_install",
+            reason: "dry_run",
+            path: directory,
+            detail: `${stale.length} of ${Object.keys(files).length} skill files would be written`,
+        };
+    }
+    for (const relative of stale) {
+        const target = path.join(directory, relative);
+        try {
+            await options.io.writeText(target, files[relative]);
+        }
+        catch (error) {
+            return {
+                target: "codex_skills",
+                status: "failed",
+                reason: "write_failed",
+                path: directory,
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    for (const relative of stale) {
+        const stored = await options.io.readText(path.join(directory, relative));
+        if (stored !== files[relative]) {
+            return {
+                target: "codex_skills",
+                status: "failed",
+                reason: "read_back_mismatch",
+                path: directory,
+                detail: `${relative} does not read back as written`,
+            };
+        }
+    }
+    return {
+        target: "codex_skills",
+        status: "installed",
+        reason: "wrote_entry",
+        path: directory,
+        detail: `${stale.length} skill file(s) written`,
+    };
+}
+export function renderMemoryTable(config) {
+    const entries = [
+        ["command", config.mcp_server.command],
+        ["args", config.mcp_server.args],
+    ];
+    if (Object.keys(config.mcp_server.env).length > 0) {
+        entries.push(["env", config.mcp_server.env]);
+    }
+    return renderTomlTable(MEMORY_TOML_PATH, entries);
+}
+function tableMatches(raw, config) {
+    const table = readTomlTable(raw, MEMORY_TOML_PATH);
+    if (!table)
+        return false;
+    if (table["command"] !== config.mcp_server.command)
+        return false;
+    const args = table["args"];
+    if (!Array.isArray(args))
+        return config.mcp_server.args.length === 0;
+    if (args.length !== config.mcp_server.args.length)
+        return false;
+    if (!args.every((entry, index) => entry === config.mcp_server.args[index]))
+        return false;
+    const env = table["env"];
+    for (const [key, value] of Object.entries(config.mcp_server.env)) {
+        if (!env || Array.isArray(env) || typeof env === "string")
+            return false;
+        if (env[key] !== value)
+            return false;
+    }
+    return true;
+}