@bli-cockpit/cli 0.2.48 → 0.2.50

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

@@ -0,0 +1,231 @@
+/**
+ * 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://…" }
+ * ```
+ *
+ * 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],
+    };
+}
+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.
+`;

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

@@ -0,0 +1,265 @@
+/**
+ * The smallest TOML surface that can put ONE table into `~/.codex/config.toml`
+ * and read it back — and nothing else.
+ *
+ * This is deliberately not a TOML parser. That file is a person's own Codex
+ * configuration: model, approval policy, sandbox, their other MCP servers. The
+ * rule is that everything outside `[mcp_servers.bli-memory]` comes out of an
+ * install byte-identical, which a parse-and-reserialise round trip cannot
+ * promise (it would reorder keys, drop comments and normalise strings). So the
+ * writer works on LINE SPANS: find our table's header, find where it ends, swap
+ * those lines, leave every other byte alone.
+ *
+ * The reader is the other half of BLI-2541's rule — verify against what the
+ * platform stored, not against what you wrote. It understands exactly the three
+ * value forms we emit (a quoted string, a single-line array of strings, a
+ * single-line inline table of strings). Anything else in our table reads back as
+ * unparsed, which surfaces as `read_back_mismatch` rather than as a shrug.
+ */
+/**
+ * Finds `[a.b]` (or `["a"."b"]`, or any mix) and the span it owns: everything up
+ * to the next table header of any kind, or end of file.
+ */
+export function findTomlTableSpan(text, tablePath) {
+    const lines = text.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const header = parseTableHeader(lines[index] ?? "");
+        if (!header || !samePath(header, tablePath))
+            continue;
+        let end = lines.length;
+        for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+            if (parseTableHeader(lines[cursor] ?? "") || isArrayTableHeader(lines[cursor] ?? "")) {
+                end = cursor;
+                break;
+            }
+        }
+        return { start_line: index, end_line: end };
+    }
+    return null;
+}
+/** Reads our table's simple key/values back off stored text. Null = no such table. */
+export function readTomlTable(text, tablePath) {
+    const span = findTomlTableSpan(text, tablePath);
+    if (!span)
+        return null;
+    const lines = text.split("\n").slice(span.start_line + 1, span.end_line);
+    const out = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const equals = trimmed.indexOf("=");
+        if (equals <= 0)
+            continue;
+        const key = unquoteKey(trimmed.slice(0, equals).trim());
+        if (!key)
+            continue;
+        // `null` means "present but in a form this reader does not model" — the
+        // caller reports a mismatch instead of pretending the field matched.
+        out[key] = parseTomlValue(trimmed.slice(equals + 1).trim());
+    }
+    return out;
+}
+/**
+ * Replaces our table's lines, or appends the table at the end when it is
+ * absent. Everything outside the span is untouched, including trailing
+ * whitespace and comments.
+ */
+export function upsertTomlTable(text, tablePath, renderedTable) {
+    const block = renderedTable.replace(/\n+$/u, "");
+    const span = findTomlTableSpan(text, tablePath);
+    if (!span) {
+        if (!text.trim())
+            return `${block}\n`;
+        const separator = text.endsWith("\n") ? "\n" : "\n\n";
+        return `${text}${separator}${block}\n`;
+    }
+    const lines = text.split("\n");
+    const before = lines.slice(0, span.start_line);
+    const after = lines.slice(span.end_line);
+    return [...before, ...block.split("\n"), ...after].join("\n");
+}
+/** Removes our table's lines. Used by `--uninstall`-shaped callers and tests. */
+export function removeTomlTable(text, tablePath) {
+    const span = findTomlTableSpan(text, tablePath);
+    if (!span)
+        return text;
+    const lines = text.split("\n");
+    return [...lines.slice(0, span.start_line), ...lines.slice(span.end_line)].join("\n");
+}
+export function renderTomlTable(tablePath, entries) {
+    const header = `[${tablePath.map(renderKey).join(".")}]`;
+    const body = entries.map(([key, value]) => `${renderKey(key)} = ${renderValue(value)}`);
+    return [header, ...body].join("\n");
+}
+function renderKey(key) {
+    return /^[A-Za-z0-9_-]+$/u.test(key) ? key : `"${key.replace(/"/gu, '\\"')}"`;
+}
+function renderValue(value) {
+    if (typeof value === "string")
+        return renderString(value);
+    if (Array.isArray(value))
+        return `[${value.map(renderString).join(", ")}]`;
+    const pairs = Object.entries(value).map(([key, entry]) => `${renderKey(key)} = ${renderString(entry)}`);
+    return pairs.length === 0 ? "{}" : `{ ${pairs.join(", ")} }`;
+}
+function renderString(value) {
+    return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"')}"`;
+}
+function parseTableHeader(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("[") || trimmed.startsWith("[["))
+        return null;
+    const close = trimmed.indexOf("]");
+    if (close < 0)
+        return null;
+    // Anything after the closing bracket other than a comment is not a header.
+    const rest = trimmed.slice(close + 1).trim();
+    if (rest && !rest.startsWith("#"))
+        return null;
+    return splitKeyPath(trimmed.slice(1, close));
+}
+function isArrayTableHeader(line) {
+    return line.trim().startsWith("[[");
+}
+function splitKeyPath(raw) {
+    const parts = [];
+    let current = "";
+    let quote = null;
+    for (const character of raw) {
+        if (quote) {
+            if (character === quote)
+                quote = null;
+            else
+                current += character;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (character === ".") {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    parts.push(current.trim());
+    return parts.filter((part) => part.length > 0);
+}
+function samePath(left, right) {
+    return left.length === right.length && left.every((part, index) => part === right[index]);
+}
+function unquoteKey(raw) {
+    const trimmed = raw.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.length >= 2) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2)) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function parseTomlValue(raw) {
+    const value = stripTrailingComment(raw).trim();
+    if (!value)
+        return null;
+    if (value.startsWith('"') || value.startsWith("'")) {
+        return parseTomlString(value);
+    }
+    if (value.startsWith("[")) {
+        if (!value.endsWith("]"))
+            return null;
+        const inner = value.slice(1, -1).trim();
+        if (!inner)
+            return [];
+        const items = splitTopLevel(inner);
+        const parsed = items.map(parseTomlString);
+        return parsed.every((item) => item !== null) ? parsed : null;
+    }
+    if (value.startsWith("{")) {
+        if (!value.endsWith("}"))
+            return null;
+        const inner = value.slice(1, -1).trim();
+        const out = {};
+        if (!inner)
+            return out;
+        for (const pair of splitTopLevel(inner)) {
+            const equals = pair.indexOf("=");
+            if (equals <= 0)
+                return null;
+            const key = unquoteKey(pair.slice(0, equals).trim());
+            const parsed = parseTomlString(pair.slice(equals + 1).trim());
+            if (!key || parsed === null)
+                return null;
+            out[key] = parsed;
+        }
+        return out;
+    }
+    return null;
+}
+function parseTomlString(raw) {
+    const value = raw.trim();
+    if (value.length < 2)
+        return null;
+    const quote = value[0];
+    if ((quote !== '"' && quote !== "'") || value[value.length - 1] !== quote)
+        return null;
+    const inner = value.slice(1, -1);
+    if (quote === "'")
+        return inner;
+    return inner.replace(/\\(["\\nrt])/gu, (_match, escaped) => {
+        if (escaped === "n")
+            return "\n";
+        if (escaped === "r")
+            return "\r";
+        if (escaped === "t")
+            return "\t";
+        return escaped;
+    });
+}
+/** Splits on commas that are not inside a quoted string. */
+function splitTopLevel(raw) {
+    const parts = [];
+    let current = "";
+    let quote = null;
+    for (const character of raw) {
+        if (quote) {
+            current += character;
+            if (character === quote)
+                quote = null;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            current += character;
+            continue;
+        }
+        if (character === ",") {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+function stripTrailingComment(raw) {
+    let quote = null;
+    for (let index = 0; index < raw.length; index += 1) {
+        const character = raw[index];
+        if (quote) {
+            if (character === quote)
+                quote = null;
+            continue;
+        }
+        if (character === '"' || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (character === "#")
+            return raw.slice(0, index);
+    }
+    return raw;
+}