@prodero/curator 0.0.0-stage → 0.2.0

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

package/dist/hosts/runtime.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { adapters, block, replaceBlock, LAUNCHER, GLOBAL_START, GLOBAL_END, MCP_START, MCP_END } from './adapters.js';
+import { environment, expectedEntry, inspect, receiptSchema } from './manager.js';
+import { verifyPublicEntry, resolveNpmCli } from './public-entry.js';
+import { read, fail, transact } from './files.js';
+const stable = (value) => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+async function packageEntry(host, entry, env) {
+    // Accept historical receipt targets only to migrate them to the public executable.
+    const cli = entry.args.length === 2 && entry.args[1] === 'mcp' && path.isAbsolute(entry.args[0])
+        ? entry.args[0] : path.resolve(path.dirname(entry.command), '../dist/cli.js');
+    const adapter = { id: host };
+    const result = expectedEntry(adapter, cli, env);
+    await verifyPublicEntry(result);
+    return result;
+}
+async function readPackage(root) {
+    try {
+        return JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return fail('HOST_RUNTIME_MISSING', 'Cannot read the selected runtime package.json. No settings changed.');
+    }
+}
+async function developmentEntry(host, checkout, env) {
+    if (!path.isAbsolute(checkout))
+        fail('HOST_UNSUPPORTED_PATH', '--checkout must be an absolute Prodero repository path.');
+    const root = await fs.realpath(checkout).catch(() => fail('HOST_RUNTIME_MISSING', 'Development checkout does not exist.'));
+    const metadata = await readPackage(root);
+    if (!['@prodero/curator', '@prodero/cli'].includes(metadata.name ?? '') || !metadata.scripts?.['mcp:dev'])
+        fail('HOST_RUNTIME_MISSING', 'Select a Prodero checkout with an mcp:dev script.');
+    for (const relative of ['src/cli.ts', 'scripts/mcp-dev.ts', 'scripts/mcp-dev-launcher.mjs', 'node_modules/tsx/package.json']) {
+        if (!(await fs.stat(path.join(root, relative)).catch(() => null))?.isFile())
+            fail('HOST_RUNTIME_MISSING', 'Development source or dependencies are missing. Install checkout dependencies first.');
+    }
+    await resolveNpmCli(env);
+    return { root };
+}
+/** Refuse to silently switch a global registration shadowed by workspace policy. */
+async function checkWorkspace(host, workspace, globalConfig, nativeConfig) {
+    if (!path.isAbsolute(workspace))
+        fail('HOST_UNSUPPORTED_PATH', '--workspace must be absolute.');
+    workspace = await fs.realpath(workspace).catch(() => fail('HOST_SCOPE_CONFLICT', 'The selected workspace does not exist.'));
+    if (!(await fs.stat(workspace)).isDirectory())
+        fail('HOST_SCOPE_CONFLICT', 'The selected workspace is not a directory.');
+    const globalReal = await fs.realpath(globalConfig).catch(() => globalConfig);
+    for (let dir = path.resolve(workspace);; dir = path.dirname(dir)) {
+        const relatives = host === 'codex' ? ['.codex/config.toml'] : ['.mcp.json', '.claude/settings.json', '.claude/settings.local.json'];
+        for (const relative of relatives) {
+            const file = path.join(dir, relative);
+            if (file === globalConfig || await fs.realpath(file).catch(() => null) === globalReal)
+                continue;
+            const text = await fs.readFile(file, 'utf8').catch((error) => {
+                if (error.code === 'ENOENT')
+                    return '';
+                return fail('HOST_SCOPE_CONFLICT', 'Cannot inspect workspace MCP overrides. No settings changed.');
+            });
+            if (/prodero/i.test(text))
+                fail('HOST_SCOPE_CONFLICT', `Workspace Prodero settings in ${file} require review before switching the user-level connection.`);
+        }
+        if (dir === path.dirname(dir))
+            break;
+    }
+    if (host === 'claude') {
+        const projects = JSON.parse(nativeConfig).projects ?? {};
+        for (const [project, settings] of Object.entries(projects)) {
+            const relative = path.relative(project, workspace);
+            if ((relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) && /prodero/i.test(JSON.stringify(settings))) {
+                fail('HOST_SCOPE_CONFLICT', 'Claude project-specific Prodero settings require review before switching the user-level connection.');
+            }
+        }
+    }
+}
+/** Explicit single-host operation. Never discovers a target host or updates the running process. */
+export async function switchRuntime(hostId, mode, options = {}) {
+    if (hostId !== 'codex' && hostId !== 'claude')
+        fail('HOST_UNKNOWN', 'Choose exactly one host: codex or claude.');
+    if (mode !== 'package' && mode !== 'dev')
+        fail('HOST_RUNTIME_MODE', 'Choose package or dev.');
+    if (options.packageRoot && !path.isAbsolute(options.packageRoot))
+        fail('HOST_UNSUPPORTED_PATH', '--package-root must be absolute.');
+    const ctx = environment(options);
+    const host = (await adapters(ctx.home, ctx.env, hostId))[0];
+    const view = await inspect(host, ctx, false, true);
+    await checkWorkspace(hostId, options.workspace ?? process.cwd(), host.config, view.text);
+    const { receipt } = view;
+    const migrating = !receipt && ['externally-configured', 'external-incomplete'].includes(view.base.state);
+    if (!receipt && !migrating)
+        fail('HOST_NOT_INSTALLED', 'Configure this agent with prodero install before switching runtimes.');
+    if (migrating && !options.adoptDev && !options.dryRun)
+        fail('HOST_ADOPTION_REQUIRED', 'Preview with --dry-run, then use --adopt-dev to migrate this manual prodero-dev registration.');
+    const stored = receipt?.format === 2 ? receipt.runtime : undefined;
+    const selectedPackage = options.packageRoot
+        ? expectedEntry(host, path.join(options.packageRoot, 'dist/cli.js'))
+        : stored?.packageEntry ?? receipt?.entry ?? expectedEntry(host, fileURLToPath(new URL('../cli.js', import.meta.url)));
+    const packaged = await packageEntry(hostId, selectedPackage, ctx.env);
+    let devRoot = stored?.devRoot ?? null, devEntry = stored?.devEntry ?? null;
+    if (mode === 'dev') {
+        const checkout = options.checkout ?? devRoot;
+        if (!checkout)
+            fail('HOST_RUNTIME_MISSING', 'Supply --checkout with the absolute Prodero repository path.');
+        const development = await developmentEntry(hostId, checkout, ctx.env);
+        devRoot = development.root;
+        let explicit = false;
+        const other = hostId === 'codex' ? 'claude' : 'codex';
+        const saved = await read(ctx.home, path.join(ctx.state, other, 'receipt.json'));
+        if (saved !== null) {
+            const otherReceipt = receiptSchema.parse(JSON.parse(saved));
+            explicit = otherReceipt.format === 2 && Boolean(otherReceipt.runtime.devRoot) && otherReceipt.runtime.devRoot !== devRoot;
+        }
+        devEntry = { ...packaged, args: ['mcp', '--dev', ...(explicit ? ['--checkout', devRoot] : [])] };
+    }
+    const entry = mode === 'dev' ? devEntry : packaged;
+    const config = host.edit(migrating ? host.removeAlternate(view.text) : view.text, entry);
+    const launcher = replaceBlock(view.launcher ?? '', GLOBAL_START, GLOBAL_END, LAUNCHER);
+    const next = {
+        format: 2, host: hostId, config: host.config, launcherPath: view.launcherPath,
+        entry, launcher: LAUNCHER, mcpBlock: hostId === 'codex' ? block(config, MCP_START, MCP_END).text : null,
+        originalConfig: receipt ? receipt.originalConfig : view.config,
+        originalLauncher: receipt ? receipt.originalLauncher : view.launcher,
+        installedConfig: config, installedLauncher: launcher,
+        runtime: { mode, packageEntry: packaged, devRoot, devEntry },
+    };
+    receiptSchema.parse(next);
+    host.inspectConfig(config);
+    const unchanged = receipt?.format === 2 && stable(receipt.runtime) === stable(next.runtime) && stable(host.entry(view.text)) === stable(entry) && launcher === view.launcher;
+    const plan = { host: hostId, mode, previousMode: stored?.mode ?? (migrating ? 'manual-dev' : 'package'), changed: !unchanged, migration: migrating,
+        config: host.config, launcher: view.launcherPath, runtimePath: mode === 'dev' ? devRoot : packaged.command, restartRequired: true };
+    if (options.dryRun || unchanged)
+        return { ...plan, dryRun: Boolean(options.dryRun) };
+    await transact(ctx.home, view.dir, [
+        { path: host.config, before: view.config, after: config },
+        { path: view.launcherPath, before: view.launcher, after: launcher },
+        { path: view.receiptPath, before: view.saved, after: JSON.stringify(next, null, 2) + '\n' },
+    ]);
+    return { ...plan, dryRun: false };
+}
+//# sourceMappingURL=runtime.js.map