gigarag-claude-code 0.1.0

package/cli/clients/commands.js

@@ -0,0 +1,160 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { PROMPTS } from '../prompts.js';
+import { expandPath } from '../paths.js';
+/** Every file we write carries this, so we only ever replace or delete our own. */
+export const MARKER = 'gigarag:managed';
+const FALLBACK_ARGS = 'the text the user typed after the command';
+function body(prompt, target) {
+    return prompt.text.replaceAll('$ARGUMENTS', () => target.argToken ?? FALLBACK_ARGS);
+}
+function yamlValue(v) {
+    if (typeof v === 'boolean')
+        return String(v);
+    return /^[\w .,()/'-]+$/.test(v) && !/^\s|\s$|^(true|false|null|yes|no)$/i.test(v) ? v : JSON.stringify(v);
+}
+function tomlString(text) {
+    return `"""\n${text.replace(/\\/g, '\\\\').replace(/"""/g, '""\\"')}"""`;
+}
+/** The file for one prompt: where it goes under the target directory, and what it says. */
+export function renderCommand(target, prompt) {
+    const text = body(prompt, target);
+    if (target.kind === 'skill') {
+        const extra = Object.entries(target.frontmatter ?? {}).map(([k, v]) => `${k}: ${yamlValue(v)}`);
+        const fm = [`name: ${prompt.name}`, `description: ${yamlValue(prompt.description)}`, ...extra];
+        return {
+            rel: join(prompt.name, 'SKILL.md'),
+            text: `---\n${fm.join('\n')}\n---\n\n${text}\n\n<!-- ${MARKER} -->\n`,
+        };
+    }
+    if (target.kind === 'toml') {
+        return {
+            rel: `${prompt.name}.toml`,
+            text: `# ${MARKER}\ndescription = ${JSON.stringify(prompt.description)}\nprompt = ${tomlString(text)}\n`,
+        };
+    }
+    const fm = [];
+    if (target.nameKey)
+        fm.push(`name: ${prompt.name}`);
+    fm.push(`description: ${yamlValue(prompt.description)}`);
+    if (target.argumentHint && prompt.argumentHint)
+        fm.push(`argument-hint: ${yamlValue(prompt.argumentHint)}`);
+    for (const [k, v] of Object.entries(target.frontmatter ?? {}))
+        fm.push(`${k}: ${yamlValue(v)}`);
+    return {
+        rel: `${prompt.name}.md`,
+        text: `---\n${fm.join('\n')}\n---\n\n${text}\n\n<!-- ${MARKER} -->\n`,
+    };
+}
+export function targetDir(target, where) {
+    const raw = target.path[where.platform] ?? target.path['*'];
+    return raw ? expandPath(raw, where.platform, where.env, where.home) : undefined;
+}
+const isOurs = (text) => text.includes(MARKER);
+function writeFile(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+}
+/**
+ * Writes every command into one target directory. It never touches a file that
+ * lacks the marker: a person's own `gigasave.md` is theirs, and the result says
+ * so and leaves it.
+ */
+export function installCommands(targetId, target, where, prompts = PROMPTS) {
+    const dir = targetDir(target, where);
+    if (!dir)
+        return [];
+    const results = [];
+    for (const prompt of prompts) {
+        const { rel, text } = renderCommand(target, prompt);
+        const path = join(dir, rel);
+        const base = { target: targetId, name: prompt.name, path };
+        try {
+            if (!existsSync(path)) {
+                writeFile(path, text);
+                results.push({ ...base, status: 'written' });
+                continue;
+            }
+            const current = readFileSync(path, 'utf8');
+            if (!isOurs(current)) {
+                results.push({ ...base, status: 'skipped', reason: 'a file of yours with that name is already there' });
+            }
+            else if (current.replace(/\r\n/g, '\n') === text) {
+                results.push({ ...base, status: 'unchanged' });
+            }
+            else {
+                writeFile(path, text);
+                results.push({ ...base, status: 'replaced' });
+            }
+        }
+        catch (err) {
+            results.push({ ...base, status: 'skipped', reason: err.message });
+        }
+    }
+    return results;
+}
+/** Deletes our files from a target, and a skill folder once it is empty. Anything without the marker stays. */
+export function removeCommands(targetId, target, where, prompts = PROMPTS) {
+    const dir = targetDir(target, where);
+    if (!dir)
+        return [];
+    const results = [];
+    for (const prompt of prompts) {
+        const { rel } = renderCommand(target, prompt);
+        const path = join(dir, rel);
+        const base = { target: targetId, name: prompt.name, path };
+        if (!existsSync(path))
+            continue;
+        try {
+            if (!isOurs(readFileSync(path, 'utf8'))) {
+                results.push({ ...base, status: 'skipped', reason: 'not written by gigarag' });
+                continue;
+            }
+            unlinkSync(path);
+            if (target.kind === 'skill') {
+                const folder = dirname(path);
+                if (readdirSync(folder).length === 0)
+                    rmdirSync(folder);
+            }
+            results.push({ ...base, status: 'removed' });
+        }
+        catch (err) {
+            results.push({ ...base, status: 'skipped', reason: err.message });
+        }
+    }
+    return results;
+}
+/** How many of our commands are installed in a target right now, for `status`. */
+export function installedCount(target, where, prompts = PROMPTS) {
+    const dir = targetDir(target, where);
+    if (!dir)
+        return 0;
+    return prompts.filter(p => {
+        const path = join(dir, renderCommand(target, p).rel);
+        try {
+            return existsSync(path) && isOurs(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return false;
+        }
+    }).length;
+}
+/**
+ * Which command targets a set of clients needs. A target several clients read,
+ * such as the shared skills folder, appears once with all of them attached, so
+ * it is written once and removed only when the last of them goes.
+ */
+export function planTargets(registry, clients) {
+    const plan = new Map();
+    for (const client of clients) {
+        for (const id of client.commands ?? []) {
+            const target = registry.commandTargets[id];
+            if (!target)
+                continue;
+            const entry = plan.get(id) ?? { target, clients: [] };
+            entry.clients.push(client);
+            plan.set(id, entry);
+        }
+    }
+    return plan;
+}

package/cli/clients/connect.js

@@ -0,0 +1,217 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { SERVER_NAME } from '../constants.js';
+import { fillEntry } from './launcher.js';
+import { configPathFor } from './registry.js';
+import { parseJsonConfig, removeEntry, serializeJson, upsertEntry } from './json.js';
+import { removeTable, setTable } from './toml.js';
+import { removeArrayEntry, setArrayEntry } from './tomlarray.js';
+import { removeYamlEntry, setYamlEntry } from './yaml.js';
+/** Every whole file we write carries this, so we only ever replace or delete our own. */
+export const FILE_MARKER = 'gigarag:managed';
+const backupPath = (path) => `${path}.gigarag.bak`;
+/**
+ * Written next to the target and renamed over it, so a crash never leaves half a config.
+ *
+ * Two things a plain temp file and rename would lose. The file's permissions: a config that holds
+ * other tools' secrets is often 0600, and a new file would come out 0644. And a symlink: a dotfiles
+ * manager links `~/.cursor/mcp.json` elsewhere, and renaming over the link replaces it with a regular
+ * file. So the write goes to the link's target and takes the original's mode.
+ */
+function writeAtomic(path, text) {
+    let target = path;
+    let mode;
+    if (existsSync(path)) {
+        if (lstatSync(path).isSymbolicLink())
+            target = realpathSync(path);
+        mode = statSync(target).mode & 0o777;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    const tmp = `${target}.gigarag-${process.pid}.tmp`;
+    writeFileSync(tmp, text, mode === undefined ? undefined : { mode });
+    try {
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* nothing to clean */
+        }
+        throw err;
+    }
+}
+/**
+ * Copies the file once. A second backup would overwrite the first, which is the
+ * copy that holds the person's config from before we ever touched it.
+ */
+function backupOnce(path) {
+    const target = backupPath(path);
+    if (!existsSync(path) || existsSync(target))
+        return undefined;
+    copyFileSync(path, target);
+    return target;
+}
+export function yamlFile(launcher) {
+    const q = (s) => JSON.stringify(s);
+    return [
+        `# ${FILE_MARKER}`,
+        'name: GigaRAG',
+        'version: 0.0.1',
+        'schema: v1',
+        'mcpServers:',
+        `  - name: ${SERVER_NAME}`,
+        `    command: ${q(launcher.command)}`,
+        '    args:',
+        ...launcher.args.map(a => `      - ${q(a)}`),
+        '',
+    ].join('\n');
+}
+function tomlValues(entry) {
+    const out = {};
+    for (const [k, v] of Object.entries(entry)) {
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+            out[k] = v;
+        else if (Array.isArray(v) && v.every(x => typeof x === 'string'))
+            out[k] = v;
+    }
+    return out;
+}
+const textOf = (edit) => (edit.ok && 'text' in edit && edit.text !== undefined ? edit.text : '');
+/** The block for `connect --print`: what would be written, in the client's own format. */
+export function renderConfig(client, launcher, url) {
+    const cfg = client.config;
+    if (!cfg) {
+        return JSON.stringify({ mcpServers: { [SERVER_NAME]: { command: launcher.command, args: launcher.args } } }, null, 2);
+    }
+    const entry = fillEntry(cfg.entry, launcher, url);
+    switch (cfg.format) {
+        case 'yamlfile':
+            return yamlFile(launcher);
+        case 'toml':
+            return textOf(setTable('', [...cfg.at, SERVER_NAME], tomlValues(entry)));
+        case 'toml-array':
+            return textOf(setArrayEntry('', cfg.at, SERVER_NAME, tomlValues(entry)));
+        case 'yamlmap':
+            return textOf(setYamlEntry('', cfg.at[0], SERVER_NAME, entry));
+        default: {
+            let wrapped = { [SERVER_NAME]: entry };
+            for (const key of [...cfg.at].reverse())
+                wrapped = { [key]: wrapped };
+            return JSON.stringify(wrapped, null, 2);
+        }
+    }
+}
+/** Adds or replaces the gigarag entry in one client's config. Never throws: the result says what happened. */
+export function connectClient(client, where, launcher, url) {
+    const base = { slug: client.slug, name: client.name };
+    const cfg = client.config;
+    const path = configPathFor(client, where);
+    if (client.mode !== 'auto' || !cfg || !path) {
+        return { ...base, status: 'skipped', reason: client.hint ?? 'set up by hand; use --print' };
+    }
+    const refuse = (reason) => ({
+        ...base,
+        status: 'failed',
+        path,
+        reason: `${path} was left alone: ${reason}. Run: gigarag connect --print ${client.slug}`,
+    });
+    try {
+        const exists = existsSync(path);
+        const original = exists ? readFileSync(path, 'utf8') : '';
+        const entry = fillEntry(cfg.entry, launcher, url);
+        let edit;
+        if (cfg.format === 'yamlfile') {
+            // The whole file is ours or it is not. A file of the person's with the same name is theirs.
+            if (exists && !original.includes(FILE_MARKER))
+                return refuse('a file of yours is already there and it is not one gigarag wrote');
+            const next = yamlFile(launcher);
+            edit = { ok: true, text: next, existed: exists, changed: !exists || original.replace(/\r\n/g, '\n') !== next };
+        }
+        else if (cfg.format === 'toml') {
+            edit = setTable(original, [...cfg.at, SERVER_NAME], tomlValues(entry));
+        }
+        else if (cfg.format === 'toml-array') {
+            edit = setArrayEntry(original, cfg.at, SERVER_NAME, tomlValues(entry));
+        }
+        else if (cfg.format === 'yamlmap') {
+            edit = setYamlEntry(original, cfg.at[0], SERVER_NAME, entry);
+        }
+        if (edit) {
+            if (!edit.ok)
+                return refuse(edit.reason);
+            if (!edit.changed)
+                return { ...base, status: 'unchanged', path };
+            const backup = backupOnce(path);
+            writeAtomic(path, edit.text);
+            return { ...base, status: edit.existed ? 'replaced' : 'written', path, backup };
+        }
+        const parsed = parseJsonConfig(original);
+        if (!parsed.ok)
+            return refuse(parsed.reason);
+        const outcome = upsertEntry(parsed.value, cfg.at, SERVER_NAME, entry);
+        if (typeof outcome === 'object')
+            return refuse(outcome.error);
+        if (outcome === 'unchanged')
+            return { ...base, status: 'unchanged', path };
+        const backup = backupOnce(path);
+        writeAtomic(path, serializeJson(parsed));
+        return { ...base, status: outcome === 'added' ? 'written' : 'replaced', path, backup };
+    }
+    catch (err) {
+        return { ...base, status: 'failed', path, reason: err.message };
+    }
+}
+/** Deletes our entry and nothing else. */
+export function removeClientEntry(client, where) {
+    const base = { slug: client.slug, name: client.name };
+    const cfg = client.config;
+    const path = configPathFor(client, where);
+    if (!cfg || !path || !existsSync(path))
+        return { ...base, status: 'skipped', reason: 'no config file' };
+    try {
+        const original = readFileSync(path, 'utf8');
+        if (cfg.format === 'yamlfile') {
+            // Only a file we wrote. One the person edited or replaced is theirs, and stays.
+            if (!original.includes(FILE_MARKER))
+                return { ...base, status: 'skipped', path, reason: 'not written by gigarag' };
+            unlinkSync(path);
+            return { ...base, status: 'written', path, reason: 'file deleted' };
+        }
+        let next;
+        if (cfg.format === 'toml') {
+            const r = removeTable(original, [...cfg.at, SERVER_NAME]);
+            next = r.ok ? { ok: true, text: r.text, removed: r.existed } : r;
+        }
+        else if (cfg.format === 'toml-array') {
+            const r = removeArrayEntry(original, cfg.at, SERVER_NAME);
+            next = r.ok ? { ok: true, text: r.text, removed: r.existed } : r;
+        }
+        else if (cfg.format === 'yamlmap') {
+            const r = removeYamlEntry(original, cfg.at[0], SERVER_NAME);
+            next = r.ok ? { ok: true, text: r.text, removed: r.existed } : r;
+        }
+        if (next) {
+            if (!next.ok)
+                return { ...base, status: 'failed', path, reason: `${path} was left alone: ${next.reason}` };
+            if (!next.removed)
+                return { ...base, status: 'skipped', path, reason: 'no gigarag entry' };
+            backupOnce(path);
+            writeAtomic(path, next.text);
+            return { ...base, status: 'written', path };
+        }
+        const parsed = parseJsonConfig(original);
+        if (!parsed.ok)
+            return { ...base, status: 'failed', path, reason: `${path} was left alone: ${parsed.reason}` };
+        if (!removeEntry(parsed.value, cfg.at, SERVER_NAME)) {
+            return { ...base, status: 'skipped', path, reason: 'no gigarag entry' };
+        }
+        backupOnce(path);
+        writeAtomic(path, serializeJson(parsed));
+        return { ...base, status: 'written', path };
+    }
+    catch (err) {
+        return { ...base, status: 'failed', path, reason: err.message };
+    }
+}

package/cli/clients/inspect.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { SERVER_NAME } from '../constants.js';
+import { configPathFor } from './registry.js';
+import { parseJsonConfig } from './json.js';
+import { headerParts } from './toml.js';
+import { arrayEntryCommand } from './tomlarray.js';
+const QUOTED_COMMAND = /^\s*(?:command|cmd)\s*[:=]\s*("(?:[^"\\]|\\.)*")/;
+const indentOf = (line) => /^ */.exec(line)[0].length;
+/** The command our entry launches, read back from the file. Undefined when there is no entry. */
+export function installedCommand(client, where) {
+    const cfg = client.config;
+    const path = configPathFor(client, where);
+    if (!cfg || !path || !existsSync(path))
+        return undefined;
+    try {
+        const text = readFileSync(path, 'utf8');
+        const lines = text.split(/\r?\n/);
+        if (cfg.format === 'yamlfile') {
+            const line = lines.map(l => QUOTED_COMMAND.exec(l)).find(Boolean);
+            return line ? JSON.parse(line[1]) : undefined;
+        }
+        if (cfg.format === 'toml-array')
+            return arrayEntryCommand(text, cfg.at, SERVER_NAME);
+        if (cfg.format === 'yamlmap') {
+            const at = lines.findIndex(l => l.trim() === `${SERVER_NAME}:` && indentOf(l) > 0);
+            if (at < 0)
+                return undefined;
+            const indent = indentOf(lines[at]);
+            for (const line of lines.slice(at + 1)) {
+                if (line.trim() !== '' && indentOf(line) <= indent)
+                    break;
+                const m = QUOTED_COMMAND.exec(line);
+                if (m)
+                    return JSON.parse(m[1]);
+            }
+            return undefined;
+        }
+        if (cfg.format === 'toml') {
+            const want = [...cfg.at, SERVER_NAME].join('.');
+            const start = lines.findIndex(l => headerParts(l)?.join('.') === want);
+            if (start < 0)
+                return undefined;
+            for (const line of lines.slice(start + 1)) {
+                if (/^\s*\[/.test(line))
+                    break;
+                const m = QUOTED_COMMAND.exec(line);
+                if (m)
+                    return JSON.parse(m[1]);
+            }
+            return undefined;
+        }
+        const parsed = parseJsonConfig(text);
+        if (!parsed.ok)
+            return undefined;
+        let node = parsed.value;
+        for (const key of cfg.at)
+            node = node?.[key];
+        const command = node?.[SERVER_NAME]?.['command'];
+        if (typeof command === 'string')
+            return command;
+        if (Array.isArray(command) && typeof command[0] === 'string')
+            return command[0];
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The command we wrote, when it points at a file that is gone. */
+export function launcherIsStale(client, where) {
+    // A command written for a shell-splitting client comes back with its quotes on.
+    const command = installedCommand(client, where)?.replace(/^"(.*)"$/, '$1');
+    return command && /[\\/]/.test(command) && !existsSync(command) ? command : undefined;
+}

package/cli/clients/json.js

@@ -0,0 +1,135 @@
+/** True when stripping comments and trailing commas is what makes the text parse. */
+function isJsonc(text) {
+    let out = '';
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out += ch;
+            if (ch === '\\')
+                out += text[++i] ?? '';
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+        }
+        else if (ch === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+        }
+        else if (ch === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+        }
+        else {
+            out += ch;
+        }
+    }
+    try {
+        JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when a number in the text would come out different after a parse and a write: an integer past
+ * 2^53, or one too large to represent. Rewriting the file would quietly change somebody's data.
+ */
+function hasLossyNumber(text) {
+    const outsideStrings = text.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+    for (const token of outsideStrings.match(/-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g) ?? []) {
+        const n = Number(token);
+        if (!Number.isFinite(n))
+            return true;
+        if (/^-?\d+$/.test(token) && String(n) !== token.replace(/^(-?)0+(?=\d)/, '$1'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Parses a config file for editing. An empty file is an empty object. A file
+ * with comments is refused rather than rewritten, because rewriting it as plain
+ * JSON would delete every comment the person wrote.
+ */
+export function parseJsonConfig(text) {
+    const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const eol = body.includes('\r\n') ? '\r\n' : '\n';
+    const endsWithNewline = body.endsWith('\n') || body.trim() === '';
+    if (body.trim() === '')
+        return { ok: true, value: {}, indent: '  ', eol, endsWithNewline: true };
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: isJsonc(body)
+                ? 'it contains comments or trailing commas, and rewriting it would remove them'
+                : `it is not valid JSON (${err.message})`,
+        };
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, reason: 'its top level is not an object' };
+    }
+    if (hasLossyNumber(body))
+        return { ok: false, reason: 'it holds a number too large to write back without changing it' };
+    const indentMatch = /\n([ \t]+)"/.exec(body);
+    return { ok: true, value: value, indent: indentMatch?.[1] ?? '  ', eol, endsWithNewline };
+}
+export function serializeJson(parsed) {
+    let out = JSON.stringify(parsed.value, null, parsed.indent);
+    if (parsed.eol === '\r\n')
+        out = out.replace(/\n/g, '\r\n');
+    return parsed.endsWithNewline ? `${out}${parsed.eol}` : out;
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** Sets `root[...at][name] = entry`, creating the containers on the way. */
+export function upsertEntry(root, at, name, entry) {
+    let node = root;
+    for (const key of at) {
+        const next = node[key];
+        if (next === undefined) {
+            const created = {};
+            node[key] = created;
+            node = created;
+        }
+        else if (next !== null && typeof next === 'object' && !Array.isArray(next)) {
+            node = next;
+        }
+        else {
+            return { error: `"${key}" is not an object in that file` };
+        }
+    }
+    const existing = node[name];
+    if (existing === undefined) {
+        node[name] = entry;
+        return 'added';
+    }
+    if (same(existing, entry))
+        return 'unchanged';
+    node[name] = entry;
+    return 'replaced';
+}
+/** Deletes `root[...at][name]`. Returns whether anything was there. */
+export function removeEntry(root, at, name) {
+    let node = root;
+    for (const key of at) {
+        const next = node[key];
+        if (next === null || typeof next !== 'object' || Array.isArray(next))
+            return false;
+        node = next;
+    }
+    if (!(name in node))
+        return false;
+    delete node[name];
+    return true;
+}

package/cli/clients/launcher.js

@@ -0,0 +1,71 @@
+import { sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isSea } from 'node:sea';
+import { version } from '../constants.js';
+/**
+ * Picks the command a client will run.
+ *
+ * Absolute paths, not `gigarag` or `npx`: an editor launched from a dock or a
+ * start menu does not inherit the shell PATH, so a bare command name works in
+ * a terminal test and fails inside the app. The cost is that moving Node
+ * invalidates the entry, which `gigarag status` reports and re-running
+ * `gigarag connect` fixes.
+ *
+ * Running through npx is the exception. Its cache path is not stable, so there
+ * the entry itself calls npx, wrapped in cmd on Windows where npx is a script.
+ */
+export function resolveLauncher(force, binScript = fileURLToPath(new URL('../bin.js', import.meta.url)), platform = process.platform, execPath = process.execPath, sea = isSea()) {
+    const inNpxCache = binScript.split(sep).includes('_npx');
+    const kind = force ?? (sea ? 'binary' : inNpxCache ? 'npx' : 'node');
+    // Only the standalone build is a binary that takes `mcp` directly. Anywhere else execPath is node itself,
+    // and `node mcp` would look for a script called mcp.
+    if (kind === 'binary' && sea)
+        return { command: execPath, args: ['mcp'], kind };
+    if (kind === 'npx') {
+        // The version this was configured by, so a client keeps running the CLI it was set up with until
+        // `gigarag connect` is run again, and a release cannot change a running setup unannounced.
+        const v = version();
+        const spec = v === '0.0.0' ? 'gigarag' : `gigarag@${v}`;
+        return platform === 'win32'
+            ? { command: 'cmd', args: ['/c', 'npx', '-y', spec, 'mcp'], kind }
+            : { command: 'npx', args: ['-y', spec, 'mcp'], kind };
+    }
+    return { command: execPath, args: [binScript, 'mcp'], kind: 'node' };
+}
+const quote = (part) => (/[\s"]/.test(part) ? `"${part.replaceAll('"', '\\"')}"` : part);
+/** The shell command a `headersHelper` runs: the launcher with `auth-header` in place of `mcp`. */
+export function helperCommand(launcher) {
+    const args = launcher.args.map(a => (a === 'mcp' ? 'auth-header' : a));
+    return [launcher.command, ...args].map(quote).join(' ');
+}
+/**
+ * A command for a client that splits it like a POSIX shell. Mistral Vibe does: given
+ * `C:\Program Files\nodejs\node.exe` it started `C:Program` and `Filesnodejsnode.exe`, so
+ * the backslashes were eaten and the space cut the path in two. Forward slashes survive that,
+ * Windows accepts them, and quotes keep a path with spaces in one piece.
+ */
+export function posixCommand(command) {
+    const slashed = command.replace(/\\/g, '/');
+    return /\s/.test(slashed) ? `"${slashed}"` : slashed;
+}
+/** Fills `$command`, `$commandPosix`, `$args`, `$argv`, `$helper` and `$url` in a registry entry. */
+export function fillEntry(entry, launcher, url = 'https://mcp.gigarag.com/mcp') {
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (value === '$command')
+            out[key] = launcher.command;
+        else if (value === '$args')
+            out[key] = [...launcher.args];
+        else if (value === '$argv')
+            out[key] = [launcher.command, ...launcher.args];
+        else if (value === '$commandPosix')
+            out[key] = posixCommand(launcher.command);
+        else if (value === '$helper')
+            out[key] = helperCommand(launcher);
+        else if (value === '$url')
+            out[key] = url;
+        else
+            out[key] = value;
+    }
+    return out;
+}