@prodero/curator 0.0.0-stage → 0.1.0

package/dist/hosts/adapters.js

@@ -0,0 +1,119 @@
+import { PRESENTATION_LAUNCHER } from "../presentation.js";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { parseTree, modify, applyEdits } from 'jsonc-parser';
+import { fail } from './files.js';
+export const MCP_START = '# prodero:mcp-start', MCP_END = '# prodero:mcp-end';
+export const GLOBAL_START = '<!-- prodero:global-start -->', GLOBAL_END = '<!-- prodero:global-end -->';
+export const LAUNCHER = `${GLOBAL_START}\n## Prodero launcher\n\n${PRESENTATION_LAUNCHER} The connected server resolves the current workspace from the host. Omit \`projectRoot\` normally; use it only to select among host-authorized roots. New projects initialize through Prodero MCP without shell setup.\n${GLOBAL_END}`;
+export function block(text, start, end) {
+    const a = text.indexOf(start), b = text.indexOf(end);
+    if (a < 0 && b < 0)
+        return null;
+    if (a < 0 || b < a || text.indexOf(start, a + start.length) >= 0 || text.indexOf(end, b + end.length) >= 0)
+        fail('HOST_CONFLICT', 'Managed boundaries are missing, duplicated or ambiguous. Review them manually.');
+    return { text: text.slice(a, b + end.length), start: a, end: b + end.length };
+}
+export function replaceBlock(text, start, end, value) {
+    const found = block(text, start, end);
+    if (found)
+        return text.slice(0, found.start) + (value ?? '') + text.slice(found.end);
+    return value === undefined ? text : text + (text && !text.endsWith('\n') ? '\n' : '') + (text ? '\n' : '') + value + '\n';
+}
+export function strictJson(text) {
+    if (!text.trim())
+        fail('HOST_INVALID_CONFIG', 'Empty JSON host configuration. Restore valid JSON before retrying.');
+    const errors = [];
+    const tree = parseTree(text, errors, { allowTrailingComma: false, disallowComments: true });
+    const check = (node) => { if (node.type === 'object') {
+        const keys = node.children?.map(c => c.children[0].value) ?? [];
+        if (new Set(keys).size !== keys.length)
+            fail('HOST_INVALID_CONFIG', 'Duplicate keys in host JSON. Resolve ambiguity before retrying.');
+    } node.children?.forEach(check); };
+    if (errors.length || !tree || tree.type !== 'object')
+        fail('HOST_INVALID_CONFIG', 'Malformed JSON host configuration. Restore valid JSON before retrying.');
+    check(tree);
+    return JSON.parse(text);
+}
+function toml(text) { try {
+    return parseToml(text);
+}
+catch {
+    fail('HOST_INVALID_CONFIG', 'Malformed or ambiguous Codex TOML. Restore valid configuration before retrying.');
+} }
+function map(value) { if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value)))
+    fail('HOST_UNSUPPORTED_CONFIG', 'MCP settings must be an object/table. No files changed.'); return value; }
+export async function adapters(home, env, selection) {
+    // Relative overrides would make machine installation depend on the current project.
+    for (const key of (selection === 'codex' ? ['CODEX_HOME'] : selection === 'claude' ? ['CLAUDE_CONFIG_DIR'] : ['CODEX_HOME', 'CLAUDE_CONFIG_DIR']))
+        if (env[key] && !path.isAbsolute(env[key]))
+            fail('HOST_UNSUPPORTED_PATH', 'Host configuration overrides must be absolute paths inside the user home. No files changed.');
+    const codex = env.CODEX_HOME ? path.resolve(env.CODEX_HOME) : path.join(home, '.codex');
+    const claude = env.CLAUDE_CONFIG_DIR ? path.resolve(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
+    const launchers = [path.join(codex, 'AGENTS.md'), path.join(codex, 'AGENTS.override.md')];
+    const override = selection === 'claude' ? null : await fs.lstat(launchers[1]).catch(() => null);
+    const result = [{ id: 'codex', name: 'Codex', support: 'supported', config: path.join(codex, 'config.toml'), launchers, launcher: override && override.size > 0 ? launchers[1] : launchers[0],
+            async detect() { return await executable('codex', env) || Boolean(await fs.lstat(this.config).catch(() => null)); },
+            inspectConfig: toml, entry(text) { return map(toml(text).mcp_servers)?.prodero; },
+            alternateEntry(text) { return map(toml(text).mcp_servers)?.['prodero-dev']; },
+            removeAlternate: removeCodexDev,
+            edit(text, value) {
+                const stanza = value ? `${MCP_START}\n[mcp_servers.prodero]\ncommand = ${JSON.stringify(value.command)}\nargs = ${JSON.stringify(value.args)}\n${value.env ? `env = { ${Object.entries(value.env).map(([k, v]) => `${JSON.stringify(k)} = ${JSON.stringify(v)}`).join(", ")} }\n` : ""}${MCP_END}` : undefined;
+                const next = replaceBlock(text, MCP_START, MCP_END, stanza);
+                toml(next);
+                return next;
+            } },
+        { id: 'claude', name: 'Claude Code', support: 'experimental', config: env.CLAUDE_CONFIG_DIR ? path.join(claude, '.claude.json') : path.join(home, '.claude.json'), launchers: [path.join(claude, 'CLAUDE.md')], launcher: path.join(claude, 'CLAUDE.md'),
+            async detect() { return await executable('claude', env) || Boolean(await fs.lstat(this.config).catch(() => null)); },
+            inspectConfig: strictJson, entry(text) { return map(strictJson(text).mcpServers)?.prodero; },
+            alternateEntry(text) { return map(strictJson(text).mcpServers)?.['prodero-dev']; },
+            removeAlternate(text) { return applyEdits(text, modify(text, ['mcpServers', 'prodero-dev'], undefined, { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } })); },
+            edit(text, value) { const next = applyEdits(text, modify(text, ['mcpServers', 'prodero'], value, { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } })); strictJson(next); return next; }
+        }];
+    return selection && selection !== 'all' ? result.filter(host => host.id === selection) : result;
+}
+export async function executable(name, env) {
+    for (const dir of (env.PATH ?? '').split(path.delimiter).filter(d => path.isAbsolute(d))) {
+        try {
+            const p = path.join(dir, name);
+            await fs.access(p, fs.constants.X_OK);
+            if ((await fs.stat(p)).isFile())
+                return true;
+        }
+        catch { }
+    }
+    return false;
+}
+/** Migrate an unambiguous dev table and optional adjacent env table; preserve unrelated bytes. */
+function removeCodexDev(text) {
+    const before = toml(text);
+    const headers = [...text.matchAll(/^\s*\[mcp_servers\.prodero-dev\][ \t]*(?:#[^\r\n]*)?\r?$/gm)];
+    if (headers.length !== 1)
+        fail('HOST_UNSUPPORTED_CONFIG', 'Migration requires one standalone [mcp_servers.prodero-dev] table. Review other TOML forms manually.');
+    const start = headers[0].index, bodyStart = start + headers[0][0].length;
+    const rest = text.slice(bodyStart);
+    let next = /^\s*\[/m.exec(rest), end = next ? bodyStart + next.index : text.length;
+    // Native Codex configurations commonly serialize env as a separate child table.
+    // Remove only this exact adjacent child; the semantic check below rejects any
+    // remaining descendants or other structure we cannot preserve unambiguously.
+    const envHeader = /^\s*\[mcp_servers\.prodero-dev\.env\][ \t]*(?:#[^\r\n]*)?\r?$/m.exec(text.slice(end));
+    if (envHeader?.index === 0) {
+        const afterEnv = end + envHeader[0].length;
+        next = /^\s*\[/m.exec(text.slice(afterEnv));
+        end = next ? afterEnv + next.index : text.length;
+    }
+    const result = text.slice(0, start) + text.slice(end);
+    delete before.mcp_servers['prodero-dev'];
+    const after = toml(result);
+    // Empty parent maps can disappear when their last child table is removed.
+    if (before.mcp_servers && Object.keys(before.mcp_servers).length === 0)
+        delete before.mcp_servers;
+    if (after.mcp_servers && Object.keys(after.mcp_servers).length === 0)
+        delete after.mcp_servers;
+    const stable = (v) => JSON.stringify(v, (_k, value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value);
+    if (stable(before) !== stable(after))
+        fail('HOST_UNSUPPORTED_CONFIG', 'Cannot remove the dev table without changing other TOML settings. Review the registration manually.');
+    return result;
+}
+//# sourceMappingURL=adapters.js.map

package/dist/hosts/files.js

@@ -0,0 +1,133 @@
+import { PRIVATE_DIRECTORY_MODE, PRIVATE_FILE_MODE } from "../filesystem/permissions.js";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+export class IntegrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+export function fail(code, message) { throw new IntegrationError(code, message); }
+/** Resolve only OS aliases above HOME; never follow links in user configuration. */
+export async function safePath(home, target) {
+    const relative = path.relative(home, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        fail('HOST_UNSUPPORTED_PATH', 'Host configuration must be inside the user home. No files changed.');
+    let cursor = home;
+    for (const part of ['', ...relative.split(path.sep).filter(Boolean)]) {
+        if (part)
+            cursor = path.join(cursor, part);
+        try {
+            const stat = await fs.lstat(cursor);
+            if (stat.isSymbolicLink() || (!stat.isDirectory() && cursor !== target) || (stat.isFile() && stat.nlink > 1))
+                fail('HOST_UNSAFE_PATH', 'Symlink, hard link or invalid configuration path. Review the host settings manually.');
+            if (cursor === target && !stat.isDirectory() && !stat.isFile())
+                fail('HOST_UNSAFE_PATH', 'Unsupported configuration file type.');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+}
+export async function read(home, target) {
+    await safePath(home, target);
+    try {
+        const s = await fs.stat(target);
+        if (!s.isFile() || s.size > 8_000_000)
+            fail('HOST_UNSUPPORTED_CONFIG', 'Host configuration is not a supported regular text file.');
+        return await fs.readFile(target, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+}
+export async function directory(home, target) {
+    await safePath(home, target);
+    await fs.mkdir(target, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+    await safePath(home, target);
+}
+async function atomic(home, target, content) {
+    await safePath(home, target);
+    if (content === null) {
+        await fs.rm(target, { force: true });
+        return;
+    }
+    await directory(home, path.dirname(target));
+    const mode = (await fs.stat(target).catch(() => null))?.mode ?? PRIVATE_FILE_MODE;
+    const temporary = target + '.prodero-' + crypto.randomUUID();
+    try {
+        await fs.writeFile(temporary, content, { flag: 'wx', mode: mode & 0o777 });
+        await safePath(home, target);
+        await fs.rename(temporary, target);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}
+/** One per-host lock and private before/after journal. Never roll back over concurrent edits. */
+export async function transact(home, state, changes) {
+    const writes = changes.filter(c => c.before !== c.after);
+    if (!writes.length)
+        return;
+    await directory(home, state);
+    const lock = path.join(state, 'lock'), pending = path.join(state, 'pending.json');
+    await safePath(home, lock);
+    try {
+        await fs.mkdir(lock, { mode: PRIVATE_DIRECTORY_MODE });
+    }
+    catch {
+        fail('HOST_BUSY', 'Another integration operation or interrupted lock exists. Close host processes and inspect the private integration state before retrying.');
+    }
+    let journalWritten = false;
+    try {
+        if (await read(home, pending) !== null)
+            fail('HOST_RECOVERY_REQUIRED', 'A preserved integration journal requires review before retrying.');
+        for (const c of changes)
+            if (await read(home, c.path) !== c.before)
+                fail('HOST_CONCURRENT_CHANGE', 'Host settings changed during inspection. Retry after closing the host.');
+        const journal = JSON.stringify({ format: 1, changes: writes }, null, 2) + '\n';
+        await atomic(home, pending, journal);
+        journalWritten = true;
+        // Backups can contain host credentials; keep them private and never print their contents.
+        await fs.writeFile(path.join(state, 'backup-' + crypto.randomUUID() + '.json'), journal, { flag: 'wx', mode: PRIVATE_FILE_MODE });
+        for (const c of writes) {
+            if (await read(home, c.path) !== c.before)
+                fail('HOST_CONCURRENT_CHANGE', 'Host settings changed while applying integration.');
+            await atomic(home, c.path, c.after);
+        }
+        for (const c of changes)
+            if (await read(home, c.path) !== c.after)
+                fail('HOST_CONCURRENT_CHANGE', 'Host settings changed during verification.');
+        await fs.rm(pending);
+    }
+    catch (e) {
+        if (journalWritten) {
+            let restored = true;
+            for (const c of [...writes].reverse())
+                try {
+                    const now = await read(home, c.path);
+                    if (now === c.after)
+                        await atomic(home, c.path, c.before);
+                    else if (now !== c.before)
+                        restored = false;
+                }
+                catch {
+                    restored = false;
+                }
+            if (restored)
+                await fs.rm(pending, { force: true });
+            else
+                fail('HOST_RECOVERY_REQUIRED', 'Integration interrupted with concurrent changes. Preserve the private pending.json and backups; review before retrying.');
+        }
+        throw e;
+    }
+    finally {
+        await fs.rmdir(lock).catch(() => { });
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/hosts/manager.js

@@ -0,0 +1,150 @@
+import { publicEntry, verifyPublicEntry } from './public-entry.js';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { PRODERO_VERSION } from '../core/constants.js';
+import { adapters, executable, block, replaceBlock, LAUNCHER, GLOBAL_START, GLOBAL_END, MCP_START, MCP_END } from './adapters.js';
+import { IntegrationError, fail, read, transact } from './files.js';
+const legacyReceiptSchema = z.object({ format: z.literal(1), host: z.enum(['codex', 'claude']), config: z.string(), launcherPath: z.string(), entry: z.object({ command: z.string(), args: z.array(z.string()), type: z.string().optional(), env: z.record(z.string()).optional() }).strict(), launcher: z.string(), mcpBlock: z.string().nullable(), originalConfig: z.string().nullable(), originalLauncher: z.string().nullable(), installedConfig: z.string(), installedLauncher: z.string() }).strict();
+const runtimeEntrySchema = legacyReceiptSchema.shape.entry;
+export const receiptSchema = z.union([
+    legacyReceiptSchema,
+    legacyReceiptSchema.extend({ format: z.literal(2), runtime: z.object({ mode: z.enum(['package', 'dev']), packageEntry: runtimeEntrySchema, devRoot: z.string().nullable(), devEntry: runtimeEntrySchema.nullable() }).strict() }).strict(),
+]);
+const stable = (v) => JSON.stringify(v, (_k, value) => value && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value);
+const errorStatus = (base, e) => ({ ...base, mcpConfigured: null, launcherInstalled: null, state: e instanceof IntegrationError ? e.code === 'HOST_CONFLICT' ? 'conflicted' : e.code === 'HOST_RECOVERY_REQUIRED' ? 'recovery-required' : 'unsupported-configuration' : 'unsupported-configuration', message: e instanceof IntegrationError ? e.message : 'HOST_CONFIGURATION_ERROR: Cannot safely read or update host settings. Check file access and restore valid configuration; no configuration contents are shown.' });
+export function environment(options) {
+    const env = options.env ?? process.env, home = options.home ?? env.HOME ?? os.homedir();
+    if (!path.isAbsolute(home) || (env.XDG_STATE_HOME && !path.isAbsolute(env.XDG_STATE_HOME)))
+        fail('HOST_UNSUPPORTED_PATH', 'HOME and integration state overrides must be absolute paths. No files changed.');
+    return { env, home: path.resolve(home), state: path.join(env.XDG_STATE_HOME || path.join(home, '.local/state'), 'prodero/host-integrations'), entryPoint: options.entryPoint ?? fileURLToPath(new URL('../cli.js', import.meta.url)) };
+}
+export function expectedEntry(host, entryPoint, env = process.env) { return publicEntry(host.id, entryPoint, env); }
+export async function inspect(host, options, remove = false, adoptDev = false) {
+    const { home, env, state, entryPoint } = options, dir = path.join(state, host.id), receiptPath = path.join(dir, 'receipt.json');
+    const detected = await host.detect();
+    const base = { id: host.id, name: host.name, support: host.support, detected, mcpConfigured: false, launcherInstalled: false, state: 'not-detected', message: 'Agent not detected.' };
+    let receipt;
+    const saved = await read(home, receiptPath);
+    if (saved !== null) {
+        const parsed = receiptSchema.safeParse(JSON.parse(saved));
+        if (!parsed.success)
+            fail('HOST_UNSUPPORTED_CONFIG', 'Invalid integration receipt. Restore the private receipt or review integration manually.');
+        receipt = parsed.data;
+        if (receipt.host !== host.id || receipt.config !== host.config || !host.launchers.includes(receipt.launcherPath))
+            fail('HOST_CONFLICT', 'Host configuration location changed. Review the original managed integration before reinstalling.');
+    }
+    if (await read(home, path.join(dir, 'pending.json')) !== null)
+        fail('HOST_RECOVERY_REQUIRED', 'Preserved private integration journal requires manual recovery before another write.');
+    if (await fs.lstat(path.join(dir, 'lock')).catch(() => null))
+        fail('HOST_RECOVERY_REQUIRED', 'An integration lock exists. Close other installers; inspect private state if an operation was interrupted.');
+    const launcherPath = receipt?.launcherPath ?? host.launcher;
+    if (!remove && receipt && launcherPath !== host.launcher)
+        fail('HOST_CONFLICT', 'A global instruction override now shadows the installed launcher. Uninstall first, then reinstall for the active global file.');
+    const config = await read(home, host.config), launcher = await read(home, launcherPath);
+    // Do not install a second block hidden in Codex's inactive global instruction file.
+    // Removal can still clean up the receipt-owned file without touching the other one.
+    if (!remove)
+        for (const other of host.launchers.filter(p => p !== launcherPath)) {
+            if (block(await read(home, other) ?? '', GLOBAL_START, GLOBAL_END))
+                fail('HOST_CONFLICT', 'Another global instruction file contains a Prodero launcher. Reconcile the existing launcher before installing.');
+        }
+    const text = config ?? (host.id === 'claude' ? '{}\n' : '');
+    host.inspectConfig(text);
+    if (receipt?.originalConfig !== null && receipt?.originalConfig !== undefined)
+        host.inspectConfig(receipt.originalConfig);
+    const current = host.entry(text), owned = block(launcher ?? '', GLOBAL_START, GLOBAL_END), mcp = host.id === 'codex' ? block(text, MCP_START, MCP_END) : null;
+    base.mcpConfigured = current !== undefined;
+    base.launcherInstalled = Boolean(owned);
+    const alternate = host.alternateEntry?.(text);
+    if (!remove && alternate !== undefined && (host.id === 'claude' || alternate?.enabled !== false || (adoptDev && !receipt && current === undefined && !mcp))) {
+        const valid = alternate && typeof alternate === 'object' && ((typeof alternate.command === 'string' && alternate.command.trim() && (alternate.args === undefined || (Array.isArray(alternate.args) && alternate.args.every(a => typeof a === 'string')))) || (typeof alternate.url === 'string' && /^https?:\/\//.test(alternate.url)));
+        if (!valid)
+            fail('HOST_UNSUPPORTED_CONFIG', `Invalid prodero-dev connection in ${host.config}. Review its command or URL before installing.`);
+        if (current !== undefined || receipt || mcp)
+            fail('HOST_CONFLICT', `Both prodero-dev and a prodero installation are present in ${host.config}. Disable one connection before continuing.`);
+        base.mcpConfigured = true;
+        base.state = owned ? 'externally-configured' : 'external-incomplete';
+        base.message = owned ? `Already configured through prodero-dev (managed manually). Settings: ${host.config}. No second server will be installed.` : `prodero-dev is configured in ${host.config}, but the global launcher is missing in ${launcherPath}. Review this manual setup before installing; no second server will be added.`;
+        return { base, receipt, receiptPath, saved, dir, config, text, launcher, launcherPath, desired: expectedEntry(host, entryPoint, env) };
+    }
+    if (!receipt && (current !== undefined || owned || mcp))
+        fail('HOST_CONFLICT', `Existing Prodero configuration has no ownership receipt. Review ${current !== undefined || mcp ? host.config : launcherPath}; back up and reconcile only the Prodero entry/block before installing.`);
+    if (receipt) {
+        if (current !== undefined && stable(current) !== stable(receipt.entry))
+            fail('HOST_CONFLICT', 'The managed Prodero MCP entry was modified. Preserve your changes and review before reinstalling/uninstalling.');
+        if (owned && owned.text !== receipt.launcher)
+            fail('HOST_CONFLICT', 'The managed launcher was modified. Preserve your changes and review its block before reinstalling/uninstalling.');
+        if (host.id === 'codex' && ((mcp && mcp.text !== receipt.mcpBlock) || (current !== undefined && !mcp)))
+            fail('HOST_CONFLICT', 'The managed Codex MCP block was modified or lost its boundaries.');
+    }
+    if (receipt?.format === 2) {
+        const runtime = receipt.runtime;
+        if ((runtime.mode === 'dev' && (!runtime.devRoot || !path.isAbsolute(runtime.devRoot) || !runtime.devEntry)) || stable(receipt.entry) !== stable(runtime.mode === 'dev' ? runtime.devEntry : runtime.packageEntry))
+            fail('HOST_UNSUPPORTED_CONFIG', 'Runtime receipt is inconsistent. Restore the private receipt before switching.');
+    }
+    base.runtimeMode = receipt?.format === 2 ? receipt.runtime.mode : receipt ? 'package' : undefined;
+    const desired = receipt?.format === 2 && receipt.runtime.mode === 'dev' ? { ...expectedEntry(host, entryPoint, env), args: receipt.runtime.devEntry.args[0] === 'mcp' ? receipt.runtime.devEntry.args : ['mcp', '--dev'] } : expectedEntry(host, entryPoint, env);
+    base.state = receipt ? (current !== undefined && owned && stable(current) === stable(desired) && owned.text === LAUNCHER ? 'installed' : 'outdated') : detected ? 'not-configured' : 'not-detected';
+    base.message = base.state === 'installed' ? 'MCP configured; launcher installed. Restart the host after package updates.' : base.state === 'outdated' ? 'Managed integration is missing or outdated. Run prodero install to update it.' : detected ? 'Agent detected; Prodero not configured.' : 'Agent not detected.';
+    return { base, receipt, receiptPath, saved, dir, config, text, launcher, launcherPath, desired };
+}
+export async function machineIntegrations(action, selection, options = {}) {
+    if (selection && !['all', 'codex', 'claude', 'cursor'].includes(selection))
+        fail('HOST_UNKNOWN', 'Unknown host. Choose codex or claude, or use --all.');
+    const ctx = environment(options);
+    if (action === 'install' && !options.entryPoint && await fs.stat(path.resolve(path.dirname(ctx.entryPoint), '../src/cli.ts')).catch(() => null))
+        fail('HOST_UNPACKAGED_RUNTIME', 'Install @prodero/curator from npm or a release tarball before configuring hosts. Development checkout launchers are not registered.');
+    const hosts = await adapters(ctx.home, ctx.env, selection);
+    const results = [];
+    for (const host of hosts) {
+        if (selection && selection !== 'all' && selection !== host.id)
+            continue;
+        let base = { id: host.id, name: host.name, support: host.support, detected: await host.detect(), mcpConfigured: false, launcherInstalled: false, state: 'not-configured', message: '' };
+        try {
+            const view = await inspect(host, ctx, action === 'uninstall');
+            base = view.base;
+            if (action === 'status' || (action === 'install' && (base.state === 'externally-configured' || base.state === 'external-incomplete' || (!base.detected && !view.receipt)))) {
+                results.push(base);
+                continue;
+            }
+            const { receipt, receiptPath, saved, dir, config, text, launcher, launcherPath, desired } = view;
+            if (action === 'uninstall' && !receipt) {
+                results.push({ ...base, message: 'No managed integration to remove. Existing project knowledge remains intact.' });
+                continue;
+            }
+            let nextConfig, nextLauncher, nextReceipt;
+            if (action === 'install') {
+                // All parsing and ownership checks happen before the first write.
+                await verifyPublicEntry(desired);
+                nextConfig = host.edit(text, desired);
+                nextLauncher = replaceBlock(launcher ?? '', GLOBAL_START, GLOBAL_END, LAUNCHER);
+                const next = { ...(receipt?.format === 2 ? { format: 2, runtime: { ...receipt.runtime, packageEntry: expectedEntry(host, ctx.entryPoint, ctx.env), ...(receipt.runtime.mode === 'dev' ? { devEntry: desired } : {}) } } : { format: 1 }), host: host.id, config: host.config, launcherPath, entry: desired, launcher: LAUNCHER, mcpBlock: host.id === 'codex' ? block(nextConfig, MCP_START, MCP_END).text : null, originalConfig: receipt ? receipt.originalConfig : config, originalLauncher: receipt ? receipt.originalLauncher : launcher, installedConfig: nextConfig, installedLauncher: nextLauncher };
+                // An unchanged installation must not rewrite JSON formatting or the ownership receipt.
+                if (base.state === 'installed') {
+                    results.push(base);
+                    continue;
+                }
+                nextReceipt = JSON.stringify(next, null, 2) + '\n';
+            }
+            else {
+                nextConfig = config === receipt.installedConfig ? receipt.originalConfig : config === null ? null : host.edit(text, undefined);
+                nextLauncher = launcher === receipt.installedLauncher ? receipt.originalLauncher : launcher === null ? null : replaceBlock(launcher, GLOBAL_START, GLOBAL_END, undefined);
+                nextReceipt = null;
+            }
+            const changes = [{ path: host.config, before: config, after: nextConfig }, { path: launcherPath, before: launcher, after: nextLauncher }, { path: receiptPath, before: saved, after: nextReceipt }];
+            await transact(ctx.home, dir, changes);
+            results.push({ ...base, mcpConfigured: action === 'install', launcherInstalled: action === 'install', state: action === 'install' ? 'installed' : 'not-configured', message: action === 'install' ? 'Managed MCP and minimal launcher installed. Restart the host; open a repository and type prodero.' : 'Managed MCP and launcher removed. Existing project knowledge and project instructions remain intact.' });
+        }
+        catch (e) {
+            results.push(errorStatus(base, e));
+        }
+    }
+    if (!selection || selection === 'all' || selection === 'cursor')
+        results.push({ id: 'cursor', name: 'Cursor', support: 'unimplemented', detected: await executable('cursor', ctx.env) || Boolean(await fs.lstat(path.join(ctx.home, '.cursor')).catch(() => null)), mcpConfigured: false, launcherInstalled: false, state: 'unsupported', message: 'Detection only; Cursor configuration is not modified.' });
+    const failed = results.some(r => ['conflicted', 'unsupported-configuration', 'recovery-required', 'external-incomplete'].includes(r.state)) || (action === 'install' && selection !== undefined && selection !== 'all' && results.every(r => !r.detected || r.support === 'unimplemented'));
+    return { ok: !failed, version: PRODERO_VERSION, scope: 'machine', action, hosts: results, ...(action === 'uninstall' ? { message: 'Existing project knowledge and project instructions remain intact.' } : {}) };
+}
+//# sourceMappingURL=manager.js.map

package/dist/hosts/public-entry.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fail } from './files.js';
+/** Public package executable, never resolved through the current workspace/PATH. */
+export function publicEntry(host, cli, env = process.env) {
+    const command = path.resolve(path.dirname(cli), '../bin/prodero');
+    const paths = [path.dirname(process.execPath), ...(env.PATH ?? '').split(path.delimiter), '/usr/bin', '/bin'];
+    const PATH = [...new Set(paths.filter(p => path.isAbsolute(p)))].join(path.delimiter);
+    return { ...(host === 'claude' ? { type: 'stdio' } : {}), command, args: ['mcp'], env: { PATH } };
+}
+export async function verifyPublicEntry(entry) {
+    if (!path.isAbsolute(entry.command) || path.basename(entry.command) !== 'prodero')
+        fail('HOST_RUNTIME_MISSING', 'Expected an absolute public Prodero executable.');
+    const executable = await fs.realpath(entry.command).catch(() => fail('HOST_RUNTIME_MISSING', 'Public Prodero executable is missing. Install the updated package.'));
+    const root = path.resolve(path.dirname(executable), '..');
+    let metadata;
+    try {
+        metadata = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        fail('HOST_RUNTIME_MISSING', 'Cannot read the installed Prodero package.');
+    }
+    if (!['@prodero/curator', '@prodero/cli'].includes(metadata.name ?? '') || metadata.bin?.prodero !== './bin/prodero' || executable !== path.join(root, 'bin/prodero'))
+        fail('HOST_RUNTIME_UNSUPPORTED', 'The package does not expose the supported public Prodero executable.');
+    if (await fs.stat(path.join(root, 'src/cli.ts')).catch(() => null))
+        fail('HOST_UNPACKAGED_RUNTIME', 'Use an installed Prodero package for the public executable, not a source checkout.');
+    await fs.access(executable, fs.constants.X_OK).catch(() => fail('HOST_RUNTIME_MISSING', 'Public Prodero executable is not executable.'));
+    if (!(await fs.stat(executable)).isFile() || !(await fs.readFile(executable, 'utf8')).startsWith('#!/usr/bin/env node\n'))
+        fail('HOST_RUNTIME_UNSUPPORTED', 'Unsupported public Prodero executable.');
+    for (const relative of ['dist/cli.js', 'dist/hosts/runtime.js'])
+        if (!(await fs.stat(path.join(root, relative)).catch(() => null))?.isFile())
+            fail('HOST_RUNTIME_UNSUPPORTED', 'The installed package is missing runtime switching support.');
+    // The saved PATH must resolve the shebang to this installation's Node, even in GUI hosts.
+    const first = entry.env?.PATH?.split(path.delimiter)[0];
+    if (!first || !path.isAbsolute(first) || await fs.realpath(path.join(first, 'node')).catch(() => null) !== await fs.realpath(process.execPath))
+        fail('HOST_RUNTIME_MISSING', 'The public launcher requires the current Node executable on its managed PATH.');
+    return root;
+}
+export async function resolveNpmCli(env) {
+    for (const dir of (env.PATH ?? '').split(path.delimiter).filter(p => path.isAbsolute(p))) {
+        const candidate = await fs.realpath(path.join(dir, 'npm')).catch(() => null);
+        if (candidate && /\.(?:c?js|mjs)$/.test(candidate) && (await fs.stat(candidate)).isFile())
+            return candidate;
+    }
+    return fail('HOST_RUNTIME_MISSING', 'Cannot resolve an npm JavaScript executable for development builds.');
+}
+//# sourceMappingURL=public-entry.js.map

package/dist/hosts/runtime-command.js

@@ -0,0 +1,66 @@
+import { switchRuntime } from './runtime.js';
+const help = `Usage: prodero runtime <dev|package> --host <codex|claude> [options]
+
+  --checkout PATH      Absolute Prodero checkout path (required for first dev switch)
+  --package-root PATH  Absolute installed package directory (if not already recorded)
+  --workspace PATH     Workspace to check for overrides (defaults to current directory)
+  --dry-run            Show the plan without changing any files
+  --adopt-dev          Explicitly migrate a manual prodero-dev registration
+
+Only the named host is changed. Restart that host after switching.
+Use prodero install for initial setup; runtime switching never installs packages.`;
+export async function runtimeCommand(args) {
+    if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+        console.log(help);
+        return;
+    }
+    const mode = args[0];
+    if (!['dev', 'package'].includes(mode))
+        throw new Error(help);
+    let host;
+    const options = {};
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        if (seen.has(flag))
+            throw new Error(`Specify ${flag} only once.`);
+        seen.add(flag);
+        if (flag === '--dry-run') {
+            options.dryRun = true;
+            continue;
+        }
+        if (flag === '--adopt-dev') {
+            options.adoptDev = true;
+            continue;
+        }
+        if (!['--host', '--checkout', '--package-root', '--workspace'].includes(flag))
+            throw new Error(help);
+        const value = args[++i];
+        if (!value || value.startsWith('-'))
+            throw new Error(`${flag} requires a value.`);
+        if (flag === '--host')
+            host = value;
+        else if (flag === '--checkout')
+            options.checkout = value;
+        else if (flag === '--package-root')
+            options.packageRoot = value;
+        else
+            options.workspace = value;
+    }
+    if (!host || !['codex', 'claude'].includes(host))
+        throw new Error('Specify exactly one --host: codex or claude.');
+    if (mode === 'package' && options.checkout)
+        throw new Error('--checkout is only used with runtime dev.');
+    const result = await switchRuntime(host, mode, options);
+    const safe = (value) => value.replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
+    console.log(`\nProdero · ${host === 'codex' ? 'Codex' : 'Claude Code'} runtime\n`);
+    console.log(`${result.dryRun ? 'Preview' : result.changed ? 'Configured' : 'Already configured'}: ${result.previousMode} → ${result.mode}`);
+    console.log(`Runtime: ${safe(result.runtimePath)}\nSettings: ${safe(result.config)}`);
+    if (result.migration)
+        console.log('Migration: replace the manual prodero-dev registration with managed prodero; retain private originals for uninstall.');
+    if (result.dryRun)
+        console.log(`No files changed.${result.migration ? ' Apply with --adopt-dev after reviewing this migration.' : ''}`);
+    else
+        console.log('Restart or reconnect this agent to load the selected runtime. The running server has not been restarted.');
+}
+//# sourceMappingURL=runtime-command.js.map