cursor-template 0.1.0

package/dist/core/doctor.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from 'smol-toml';
+import { readManifest } from './manifest.js';
+import { readCodexConfig, readCursorMcp } from './mcp.js';
+import { componentDest } from './paths.js';
+import { errorMessage } from '../utils/errors.js';
+import { isWritableDir, listChildDirs, listChildFiles, pathExists } from '../utils/fs.js';
+export async function doctor({ target, roots }) {
+    const issues = [];
+    const notes = [];
+    for (const [label, dir] of [
+        ['skills', roots.skills],
+        ['commands', roots.commands],
+        ['agents', roots.agents],
+    ]) {
+        if (await isWritableDir(dir))
+            notes.push(`writable ${label}: ${dir}`);
+        else
+            issues.push(`not writable ${label}: ${dir}`);
+    }
+    const manifest = await readManifest(roots.manifest);
+    const skillNames = new Set();
+    for (const dir of await listChildDirs(roots.skills)) {
+        skillNames.add(path.basename(dir));
+        if (!(await pathExists(path.join(dir, 'SKILL.md'))))
+            issues.push(`missing SKILL.md: ${dir}`);
+    }
+    const agentExt = target === 'codex' ? '.toml' : '.md';
+    for (const file of await listChildFiles(roots.agents, agentExt)) {
+        const text = await fs.readFile(file, 'utf8');
+        if (!text.trim()) {
+            issues.push(`empty agent file: ${file}`);
+            continue;
+        }
+        if (target === 'codex') {
+            try {
+                const doc = parse(text);
+                for (const key of ['name', 'description', 'developer_instructions']) {
+                    if (!doc[key])
+                        issues.push(`agent missing ${key}: ${file}`);
+                }
+            }
+            catch (error) {
+                issues.push(`agent TOML parse error: ${file}: ${errorMessage(error)}`);
+            }
+        }
+    }
+    if (await pathExists(roots.mcpFile)) {
+        const text = await fs.readFile(roots.mcpFile, 'utf8');
+        try {
+            if (target === 'cursor')
+                readCursorMcp(text);
+            else
+                readCodexConfig(text);
+            notes.push(`mcp config ok: ${roots.mcpFile}`);
+        }
+        catch (error) {
+            issues.push(`mcp parse error: ${roots.mcpFile}: ${errorMessage(error)}`);
+        }
+    }
+    else {
+        notes.push(`mcp config absent: ${roots.mcpFile}`);
+    }
+    for (const entry of Object.values(manifest.components)) {
+        if (entry.type === 'skill' || (target === 'codex' && entry.type === 'command')) {
+            if (!skillNames.has(entry.name))
+                issues.push(`missing installed ${entry.type}: ${entry.id}`);
+        }
+        else if (entry.type !== 'mcp') {
+            const dest = componentDest({ target, roots, type: entry.type, name: entry.name });
+            if (!(await pathExists(dest.path)))
+                issues.push(`missing installed ${entry.type}: ${entry.id}`);
+        }
+    }
+    return { issues, notes };
+}

package/dist/core/install.d.ts

@@ -0,0 +1,29 @@
+import type { Catalog, ComponentRecord, ComponentType, InstallRoots, Target } from './types.js';
+export declare function installRecord({ target, roots, record, yes, dryRun, catalog, confirmImpl, }: {
+    target: Target;
+    roots: InstallRoots;
+    record: ComponentRecord;
+    yes?: boolean;
+    dryRun?: boolean;
+    catalog: Catalog;
+    confirmImpl?: (question: string) => Promise<boolean>;
+}): Promise<true | 'skipped' | false>;
+export declare function removeInstalled({ target, roots, type, id, yes, dryRun, confirmImpl, }: {
+    target: Target;
+    roots: InstallRoots;
+    type: ComponentType;
+    id: string;
+    yes?: boolean;
+    dryRun?: boolean;
+    confirmImpl?: (question: string) => Promise<boolean>;
+}): Promise<boolean>;
+export declare function sourceLine(record: ComponentRecord): string;
+export declare function installById(options: {
+    target: Target;
+    roots: InstallRoots;
+    type: ComponentType;
+    id: string;
+    yes?: boolean;
+    dryRun?: boolean;
+    catalog: Catalog;
+}): Promise<true | 'skipped' | false>;

package/dist/core/install.js

@@ -0,0 +1,206 @@
+import fs from 'node:fs/promises';
+import { agentMarkdownToToml, cursorAgentMarkdown, wrapCommandAsSkill } from './adapters.js';
+import { findComponent, readManifest, removeComponent, upsertComponent, writeManifest } from './manifest.js';
+import { applyCodexMcp, applyCursorMcp, codexMcpConflicts, cursorMcpConflicts, envKeysFromServers, extractMcpServers, readCodexConfig, readCursorMcp, removeCodexServers, removeCursorServers, } from './mcp.js';
+import { componentDest } from './paths.js';
+import { githubBlobUrl } from '../services/github.js';
+import { assertSafeId } from '../utils/ids.js';
+import { backupOnce, confirm, isExecutableRel, pathExists, safeJoin, writeBytes } from '../utils/fs.js';
+async function readTextIfExists(file) {
+    try {
+        return await fs.readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+async function shouldReplace(dest, confirmImpl, dryRun) {
+    if (!(await pathExists(dest.path)))
+        return true;
+    const ok = await confirmImpl(`Overwrite ${dest.path}? (y/N) `);
+    if (!ok) {
+        console.log(`skipped ${dest.path}`);
+        return false;
+    }
+    if (!dryRun && dest.kind === 'dir')
+        await fs.rm(dest.path, { recursive: true, force: true });
+    return true;
+}
+export async function installRecord({ target, roots, record, yes = false, dryRun = false, catalog, confirmImpl = (question) => confirm(question, { yes, dryRun }), }) {
+    const dest = componentDest({ target, roots, type: record.type, name: record.name });
+    if (record.type === 'skill') {
+        if (!record.files.some((file) => file.rel === 'SKILL.md'))
+            throw new Error(`SKILL.md not found in skill "${record.id}"`);
+        if (!(await shouldReplace(dest, confirmImpl, dryRun)))
+            return 'skipped';
+        for (const file of record.files) {
+            const buf = await catalog.readFile(file.repoPath);
+            if (!buf)
+                throw new Error(`Missing skill file ${file.repoPath}`);
+            await writeBytes(safeJoin(dest.path, file.rel), buf, { executable: isExecutableRel(file.rel), dryRun });
+        }
+        console.log(`${dryRun ? 'would install' : 'installed'} skill ${record.id}`);
+        console.log(`  ${dest.path}`);
+        if (!dryRun)
+            await remember(roots, { type: 'skill', id: record.id, name: record.name });
+        return true;
+    }
+    if (record.type === 'command') {
+        if (!record.repoPath)
+            throw new Error(`Command "${record.id}" has no source file`);
+        const buf = await catalog.readFile(record.repoPath);
+        if (!buf)
+            throw new Error(`Command "${record.id}" not found`);
+        const markdown = buf.toString('utf8');
+        if (!(await shouldReplace(dest, confirmImpl, dryRun)))
+            return 'skipped';
+        if (target === 'cursor') {
+            await writeBytes(dest.path, markdown.endsWith('\n') ? markdown : `${markdown}\n`, { dryRun });
+        }
+        else {
+            const wrapped = wrapCommandAsSkill(markdown, record.name);
+            await writeBytes(safeJoin(dest.path, 'SKILL.md'), wrapped.skill, { dryRun });
+            await writeBytes(safeJoin(dest.path, 'agents/openai.yaml'), wrapped.openaiYaml, { dryRun });
+        }
+        console.log(`${dryRun ? 'would install' : 'installed'} command ${record.id}`);
+        console.log(`  ${dest.path}`);
+        if (!dryRun)
+            await remember(roots, { type: 'command', id: record.id, name: record.name });
+        return true;
+    }
+    if (record.type === 'agent') {
+        if (!record.repoPath)
+            throw new Error(`Agent "${record.id}" has no source file`);
+        const buf = await catalog.readFile(record.repoPath);
+        if (!buf)
+            throw new Error(`Agent "${record.id}" not found`);
+        const markdown = buf.toString('utf8');
+        if (!(await shouldReplace(dest, confirmImpl, dryRun)))
+            return 'skipped';
+        const output = target === 'cursor' ? cursorAgentMarkdown(markdown) : agentMarkdownToToml(markdown, record.name);
+        await writeBytes(dest.path, output, { dryRun });
+        console.log(`${dryRun ? 'would install' : 'installed'} agent ${record.id}`);
+        console.log(`  ${dest.path}`);
+        if (!dryRun)
+            await remember(roots, { type: 'agent', id: record.id, name: record.name });
+        return true;
+    }
+    if (record.type === 'mcp') {
+        if (!record.repoPath)
+            throw new Error(`MCP "${record.id}" has no source file`);
+        const buf = await catalog.readFile(record.repoPath);
+        if (!buf)
+            throw new Error(`MCP "${record.id}" not found`);
+        const servers = extractMcpServers(JSON.parse(buf.toString('utf8')));
+        const existing = await readTextIfExists(dest.path);
+        if (!(await mergeMcp({ target, dest: dest.path, existing, servers, dryRun, confirmImpl })))
+            return false;
+        const keys = envKeysFromServers(servers);
+        console.log(`${dryRun ? 'would install' : 'installed'} mcp ${record.id}`);
+        console.log(`  ${dest.path} (${Object.keys(servers).join(', ')})`);
+        if (keys.length)
+            console.log(`  env: ${keys.join(', ')}`);
+        if (!dryRun)
+            await remember(roots, { type: 'mcp', id: record.id, name: record.name, mcpServers: Object.keys(servers) });
+        return true;
+    }
+    throw new Error(`Unknown component type "${record.type}"`);
+}
+async function mergeMcp({ target, dest, existing, servers, dryRun, confirmImpl, }) {
+    if (target === 'cursor') {
+        const doc = readCursorMcp(existing);
+        const conflicts = cursorMcpConflicts(doc, servers);
+        const overwrite = new Set();
+        for (const id of conflicts) {
+            if (await confirmImpl(`Overwrite MCP server "${id}" in ${dest}? (y/N) `))
+                overwrite.add(id);
+            else
+                console.log(`kept existing MCP server ${id}`);
+        }
+        if (dryRun) {
+            for (const id of Object.keys(servers)) {
+                if (conflicts.includes(id) && !overwrite.has(id))
+                    continue;
+                console.log(`would merge MCP server ${id} into ${dest}`);
+            }
+            return true;
+        }
+        await writeBytes(dest, applyCursorMcp(doc, servers, overwrite));
+        return true;
+    }
+    const doc = readCodexConfig(existing);
+    const conflicts = codexMcpConflicts(doc, servers);
+    const overwrite = new Set();
+    for (const id of conflicts) {
+        if (await confirmImpl(`Overwrite MCP server "${id}" in ${dest}? (y/N) `))
+            overwrite.add(id);
+        else
+            console.log(`kept existing MCP server ${id}`);
+    }
+    if (dryRun) {
+        for (const id of Object.keys(servers)) {
+            if (conflicts.includes(id) && !overwrite.has(id))
+                continue;
+            console.log(`would merge MCP server ${id} into ${dest}`);
+        }
+        return true;
+    }
+    if (existing.trim())
+        await backupOnce(dest);
+    const next = applyCodexMcp(doc, servers, overwrite);
+    await writeBytes(dest, next.endsWith('\n') ? next : `${next}\n`);
+    return true;
+}
+async function remember(roots, entry) {
+    const manifest = await readManifest(roots.manifest);
+    upsertComponent(manifest, entry);
+    await writeManifest(roots.manifest, manifest);
+}
+export async function removeInstalled({ target, roots, type, id, yes = false, dryRun = false, confirmImpl = (question) => confirm(question, { yes, dryRun }), }) {
+    const manifest = await readManifest(roots.manifest);
+    const entry = findComponent(manifest, type, id);
+    if (!entry) {
+        console.log(`${type} "${id}" is not installed`);
+        return false;
+    }
+    const dest = componentDest({ target, roots, type: entry.type, name: entry.name });
+    const ok = await confirmImpl(`Remove ${entry.id} from ${dest.path}? (y/N) `);
+    if (!ok && !yes && !dryRun) {
+        console.log(`skipped ${entry.id}`);
+        return false;
+    }
+    if (dryRun) {
+        console.log(`would remove ${entry.type} ${entry.id}`);
+        console.log(`  ${dest.path}`);
+        return true;
+    }
+    if (entry.type === 'mcp') {
+        const existing = await readTextIfExists(dest.path);
+        if (existing.trim()) {
+            if (target === 'cursor')
+                await writeBytes(dest.path, removeCursorServers(readCursorMcp(existing), entry.mcpServers || []));
+            else {
+                const next = removeCodexServers(readCodexConfig(existing), entry.mcpServers || []);
+                await writeBytes(dest.path, next.endsWith('\n') ? next : `${next}\n`);
+            }
+        }
+    }
+    else if (dest.kind === 'dir')
+        await fs.rm(dest.path, { recursive: true, force: true });
+    else
+        await fs.rm(dest.path, { force: true });
+    removeComponent(manifest, entry);
+    await writeManifest(roots.manifest, manifest);
+    console.log(`removed ${entry.type} ${entry.id}`);
+    return true;
+}
+export function sourceLine(record) {
+    return githubBlobUrl(record.primaryPath);
+}
+export async function installById(options) {
+    assertSafeId(options.id);
+    const record = await options.catalog.resolve(options.type, options.id);
+    return installRecord({ ...options, record });
+}

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentType, InstallRoots, Target } from './types.js';
+export interface InstalledItem {
+    type: ComponentType;
+    id: string;
+    name: string;
+    path: string;
+    mcpServers: string[];
+    present: boolean;
+    tracked: boolean;
+}
+export declare function collectInstalled({ target, roots }: {
+    target: Target;
+    roots: InstallRoots;
+}): Promise<InstalledItem[]>;

package/dist/core/lifecycle.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readManifest } from './manifest.js';
+import { readCodexConfig, readCursorMcp } from './mcp.js';
+import { componentDest } from './paths.js';
+import { listChildDirs, listChildFiles, pathExists } from '../utils/fs.js';
+export async function collectInstalled({ target, roots }) {
+    const manifest = await readManifest(roots.manifest);
+    const items = [];
+    const seen = new Set();
+    for (const entry of Object.values(manifest.components)) {
+        const dest = componentDest({ target, roots, type: entry.type, name: entry.name });
+        items.push({
+            type: entry.type,
+            id: entry.id,
+            name: entry.name,
+            path: dest.path,
+            mcpServers: entry.mcpServers || [],
+            present: await pathExists(dest.path),
+            tracked: true,
+        });
+        seen.add(`${entry.type}:${entry.name}`);
+    }
+    for (const dir of await listChildDirs(roots.skills)) {
+        const name = path.basename(dir);
+        if (seen.has(`skill:${name}`) || seen.has(`command:${name}`))
+            continue;
+        items.push({ type: 'skill', id: name, name, path: dir, mcpServers: [], present: true, tracked: false });
+    }
+    if (target === 'cursor') {
+        for (const file of await listChildFiles(roots.commands, '.md')) {
+            const name = path.basename(file, '.md');
+            if (seen.has(`command:${name}`))
+                continue;
+            items.push({ type: 'command', id: name, name, path: file, mcpServers: [], present: true, tracked: false });
+        }
+    }
+    const agentExt = target === 'codex' ? '.toml' : '.md';
+    for (const file of await listChildFiles(roots.agents, agentExt)) {
+        const name = path.basename(file, agentExt);
+        if (seen.has(`agent:${name}`))
+            continue;
+        items.push({ type: 'agent', id: name, name, path: file, mcpServers: [], present: true, tracked: false });
+    }
+    const knownServers = new Set(items.flatMap((item) => item.mcpServers));
+    if (await pathExists(roots.mcpFile)) {
+        const text = await fs.readFile(roots.mcpFile, 'utf8');
+        const servers = target === 'cursor'
+            ? Object.keys(readCursorMcp(text).mcpServers || {})
+            : Object.keys(readCodexConfig(text).mcp_servers || {});
+        for (const name of servers) {
+            if (knownServers.has(name))
+                continue;
+            items.push({ type: 'mcp', id: name, name, path: roots.mcpFile, mcpServers: [name], present: true, tracked: false });
+        }
+    }
+    return items.sort((a, b) => `${a.type}:${a.id}`.localeCompare(`${b.type}:${b.id}`));
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentType, Manifest, ManifestEntry } from './types.js';
+export declare function emptyManifest(): Manifest;
+export declare function manifestKey(type: ComponentType, id: string): string;
+export declare function readManifest(file: string): Promise<Manifest>;
+export declare function writeManifest(file: string, manifest: Manifest): Promise<void>;
+export declare function upsertComponent(manifest: Manifest, entry: Omit<ManifestEntry, 'mcpServers'> & {
+    mcpServers?: string[];
+}): Manifest;
+export declare function findComponent(manifest: Manifest, type: ComponentType, idOrName: string): ManifestEntry | null;
+export declare function removeComponent(manifest: Manifest, entry: ManifestEntry): Manifest;

package/dist/core/manifest.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { errorMessage } from '../utils/errors.js';
+function isEnoent(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+export function emptyManifest() {
+    return { version: 1, components: {} };
+}
+export function manifestKey(type, id) {
+    return `${type}:${id}`;
+}
+export async function readManifest(file) {
+    try {
+        const text = await fs.readFile(file, 'utf8');
+        const data = JSON.parse(text);
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            return emptyManifest();
+        if (!data.components || typeof data.components !== 'object')
+            data.components = {};
+        return data;
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return emptyManifest();
+        throw new Error(`Cannot read install manifest ${file}: ${errorMessage(error)}`, { cause: error });
+    }
+}
+export async function writeManifest(file, manifest) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+export function upsertComponent(manifest, entry) {
+    manifest.components[manifestKey(entry.type, entry.id)] = {
+        type: entry.type,
+        id: entry.id,
+        name: entry.name,
+        mcpServers: entry.mcpServers || [],
+    };
+    return manifest;
+}
+export function findComponent(manifest, type, idOrName) {
+    const direct = manifest.components[manifestKey(type, idOrName)];
+    if (direct)
+        return direct;
+    const matches = Object.values(manifest.components).filter((entry) => {
+        if (entry.type !== type)
+            return false;
+        if (entry.id === idOrName || entry.name === idOrName)
+            return true;
+        return Array.isArray(entry.mcpServers) && entry.mcpServers.includes(idOrName);
+    });
+    if (matches.length === 1)
+        return matches[0] ?? null;
+    if (matches.length > 1) {
+        throw new Error(`${type} "${idOrName}" matches multiple installs: ${matches.map((item) => item.id).join(', ')}`);
+    }
+    return null;
+}
+export function removeComponent(manifest, entry) {
+    delete manifest.components[manifestKey(entry.type, entry.id)];
+    return manifest;
+}

package/dist/core/mcp.d.ts

@@ -0,0 +1,22 @@
+export type McpServers = Record<string, Record<string, unknown>>;
+type CursorDoc = {
+    mcpServers: McpServers;
+    [key: string]: unknown;
+};
+type CodexDoc = {
+    mcp_servers?: McpServers;
+    [key: string]: unknown;
+};
+export declare function stable(value: unknown): string;
+export declare function extractMcpServers(json: unknown): McpServers;
+export declare function envKeysFromServers(servers: McpServers): string[];
+export declare function toCodexServer(cfg: Record<string, unknown>): Record<string, unknown>;
+export declare function readCursorMcp(existingText: string): CursorDoc;
+export declare function cursorMcpConflicts(doc: CursorDoc, incoming: McpServers): string[];
+export declare function applyCursorMcp(doc: CursorDoc, incoming: McpServers, overwriteIds: Set<string> | string[]): string;
+export declare function removeCursorServers(doc: CursorDoc, ids: string[]): string;
+export declare function readCodexConfig(existingText: string): CodexDoc;
+export declare function codexMcpConflicts(doc: CodexDoc, incoming: McpServers): string[];
+export declare function applyCodexMcp(doc: CodexDoc, incoming: McpServers, overwriteIds: Set<string> | string[]): string;
+export declare function removeCodexServers(doc: CodexDoc, ids: string[]): string;
+export {};

package/dist/core/mcp.js

@@ -0,0 +1,130 @@
+import { parse, stringify } from 'smol-toml';
+const CODEX_KEYS = ['command', 'args', 'url', 'env', 'headers', 'bearer_token_env_var'];
+export function stable(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value && typeof value === 'object') {
+        return Object.keys(value)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = sortValue(value[key]);
+            return acc;
+        }, {});
+    }
+    return value;
+}
+export function extractMcpServers(json) {
+    const record = json && typeof json === 'object' && !Array.isArray(json) ? json : null;
+    const nested = record?.mcpServers;
+    const source = nested && typeof nested === 'object' && !Array.isArray(nested) ? nested : record;
+    if (!source || typeof source !== 'object' || Array.isArray(source)) {
+        throw new Error('MCP catalog file has no mcpServers object');
+    }
+    const servers = {};
+    for (const [id, cfg] of Object.entries(source)) {
+        if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
+            continue;
+        const next = { ...cfg };
+        delete next.description;
+        servers[id] = next;
+    }
+    if (!Object.keys(servers).length)
+        throw new Error('MCP catalog file did not contain any servers');
+    return servers;
+}
+export function envKeysFromServers(servers) {
+    const keys = [];
+    for (const cfg of Object.values(servers)) {
+        const env = cfg.env;
+        if (env && typeof env === 'object' && !Array.isArray(env))
+            keys.push(...Object.keys(env));
+    }
+    return [...new Set(keys)];
+}
+export function toCodexServer(cfg) {
+    const out = {};
+    for (const key of CODEX_KEYS) {
+        if (cfg[key] !== undefined)
+            out[key] = cfg[key];
+    }
+    return out;
+}
+export function readCursorMcp(existingText) {
+    if (!existingText || !existingText.trim())
+        return { mcpServers: {} };
+    const doc = JSON.parse(existingText);
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        throw new Error('mcp.json must be a JSON object');
+    const record = doc;
+    if (!record.mcpServers || typeof record.mcpServers !== 'object' || Array.isArray(record.mcpServers)) {
+        record.mcpServers = {};
+    }
+    return record;
+}
+export function cursorMcpConflicts(doc, incoming) {
+    const conflicts = [];
+    for (const [id, cfg] of Object.entries(incoming)) {
+        const prev = doc.mcpServers[id];
+        if (prev && stable(prev) !== stable(cfg))
+            conflicts.push(id);
+    }
+    return conflicts;
+}
+export function applyCursorMcp(doc, incoming, overwriteIds) {
+    const allow = overwriteIds instanceof Set ? overwriteIds : new Set(overwriteIds);
+    for (const [id, cfg] of Object.entries(incoming)) {
+        if (doc.mcpServers[id] && stable(doc.mcpServers[id]) !== stable(cfg) && !allow.has(id))
+            continue;
+        doc.mcpServers[id] = cfg;
+    }
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+export function removeCursorServers(doc, ids) {
+    for (const id of ids)
+        delete doc.mcpServers[id];
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+export function readCodexConfig(existingText) {
+    if (!existingText || !existingText.trim())
+        return { mcp_servers: {} };
+    const doc = parse(existingText);
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        return {};
+    if (!doc.mcp_servers || typeof doc.mcp_servers !== 'object' || Array.isArray(doc.mcp_servers)) {
+        doc.mcp_servers = {};
+    }
+    return doc;
+}
+export function codexMcpConflicts(doc, incoming) {
+    const conflicts = [];
+    const servers = doc.mcp_servers ?? {};
+    for (const [id, cfg] of Object.entries(incoming)) {
+        const prev = servers[id];
+        if (prev && stable(prev) !== stable(toCodexServer(cfg)))
+            conflicts.push(id);
+    }
+    return conflicts;
+}
+export function applyCodexMcp(doc, incoming, overwriteIds) {
+    const allow = overwriteIds instanceof Set ? overwriteIds : new Set(overwriteIds);
+    if (!doc.mcp_servers)
+        doc.mcp_servers = {};
+    for (const [id, cfg] of Object.entries(incoming)) {
+        const mapped = toCodexServer(cfg);
+        const prev = doc.mcp_servers[id];
+        if (prev && stable(prev) !== stable(mapped) && !allow.has(id))
+            continue;
+        doc.mcp_servers[id] = mapped;
+    }
+    return stringify(doc);
+}
+export function removeCodexServers(doc, ids) {
+    if (!doc.mcp_servers)
+        doc.mcp_servers = {};
+    for (const id of ids)
+        delete doc.mcp_servers[id];
+    return stringify(doc);
+}

package/dist/core/paths.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType, Dest, InstallRoots, Scope, Target } from './types.js';
+export declare function destRoots({ target, scope, directory, home, }: {
+    target: Target;
+    scope?: Scope;
+    directory?: string;
+    home?: string;
+}): InstallRoots;
+export declare function componentDest({ target, roots, type, name, }: {
+    target: Target;
+    roots: InstallRoots;
+    type: ComponentType;
+    name: string;
+}): Dest;