proteum 2.4.3 → 2.5.0

package/cli/mcp/router.ts

@@ -37,6 +37,11 @@ import {
     type TProteumAppRootSummary,
 } from '../utils/appRoots';
 import { inspectDevPort, type TDevPortInspection } from '../runtime/ports';
+import {
+    compactWorktreeBootstrapStatus,
+    createWorktreeBootstrapMcpBlockResponse,
+    getWorktreeBootstrapStatus,
+} from '../runtime/worktreeBootstrap';
 
 type TDevMcpClient = {
     callTool: (input: { arguments?: Record<string, unknown>; name: string }) => Promise<CallToolResult>;
@@ -134,12 +139,17 @@ const createOfflineNextAction = async ({
     baseRoot,
     portInspection,
     summary,
+    version,
 }: {
     appRoot: string;
     baseRoot?: string;
     portInspection?: TDevPortInspection;
     summary: TProteumAppRootSummary;
+    version: string;
 }) => {
+    const bootstrapStatus = getWorktreeBootstrapStatus({ appRoot, proteumVersion: version });
+    if (bootstrapStatus.blocking) return bootstrapStatus.nextAction;
+
     if (!summary.manifest) {
         return {
             label: 'Check Runtime Status',
@@ -178,10 +188,12 @@ const compactOfflineProject = async ({
     appRoot,
     baseRoot,
     matchReason,
+    version,
 }: {
     appRoot: string;
     baseRoot?: string;
     matchReason: string;
+    version: string;
 }): Promise<TOfflineProject> => {
     const summary = readProteumAppRootSummary(appRoot, baseRoot);
     const portInspection = summary.manifest
@@ -196,7 +208,7 @@ const compactOfflineProject = async ({
         devPort: portInspection,
         live: false,
         matchReason,
-        nextAction: await createOfflineNextAction({ appRoot: summary.appRoot, baseRoot, portInspection, summary }),
+        nextAction: await createOfflineNextAction({ appRoot: summary.appRoot, baseRoot, portInspection, summary, version }),
         projectId: await resolveProteumProjectId(summary.appRoot),
         state: 'offline',
     };
@@ -297,7 +309,7 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
             if (!matches.has(record.projectId)) matches.set(record.projectId, { project: compactProjectMatch(record, reason), record });
         };
         const addOfflineMatch = async (appRoot: string, reason: string, baseRoot?: string) => {
-            const offline = await compactOfflineProject({ appRoot, baseRoot, matchReason: reason });
+            const offline = await compactOfflineProject({ appRoot, baseRoot, matchReason: reason, version });
             if (!matches.has(offline.projectId)) matches.set(offline.projectId, { offline, project: offline });
         };
         const normalizedProjectId = typeof projectId === 'string' ? projectId.trim() : '';
@@ -386,16 +398,38 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         return { error: null, record: inspection.record };
     };
 
+    const augmentForwardedPayload = (result: CallToolResult, record: TMachineDevSessionRecord) => {
+        if (result.content[0]?.type !== 'text') return result;
+
+        try {
+            const payload = JSON.parse(result.content[0].text);
+            const bootstrapStatus = getWorktreeBootstrapStatus({ appRoot: record.appRoot, proteumVersion: version });
+
+            return jsonToolResult({
+                ...payload,
+                data: {
+                    ...(payload.data || {}),
+                    worktreeBootstrap: compactWorktreeBootstrapStatus(bootstrapStatus),
+                },
+            });
+        } catch {
+            return result;
+        }
+    };
+
     const forwardTool = async (name: string, input: Record<string, unknown>) => {
         const resolution = await resolveProject(input.projectId);
         if (!resolution.record) return resolution.error;
 
         try {
             const client = await getClient(resolution.record);
-            return await client.callTool({
+            const result = await client.callTool({
                 arguments: stripProjectRouting(input),
                 name,
             });
+
+            if (name === 'runtime_status' || name === 'doctor') return augmentForwardedPayload(result, resolution.record);
+            return result;
         } catch (error) {
             await closeClient(resolution.record);
             return errorToolResult(`Could not reach Proteum dev MCP for ${resolution.record.projectId}.`, {
@@ -407,6 +441,9 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
     };
 
     const createOfflineWorkflowStartResult = (offline: TOfflineProject, input: Record<string, unknown>) => {
+        const bootstrapStatus = getWorktreeBootstrapStatus({ appRoot: offline.appRoot, proteumVersion: version });
+        if (bootstrapStatus.blocking) return jsonToolResult(createWorktreeBootstrapMcpBlockResponse(bootstrapStatus, offline), true);
+
         let manifest: ReturnType<typeof readProteumManifest>;
         try {
             manifest = readProteumManifest(offline.appRoot);
@@ -458,6 +495,7 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
             ...payload,
             data: {
                 project: offline,
+                worktreeBootstrap: compactWorktreeBootstrapStatus(bootstrapStatus),
                 ...payload.data,
             },
             nextActions: [
@@ -497,6 +535,11 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
             });
         }
 
+        const bootstrapStatus = getWorktreeBootstrapStatus({ appRoot: record.appRoot, proteumVersion: version });
+        if (bootstrapStatus.blocking) {
+            return jsonToolResult(createWorktreeBootstrapMcpBlockResponse(bootstrapStatus, compactProject(record)), true);
+        }
+
         try {
             const client = await getClient(record);
             const result = await client.callTool({
@@ -525,6 +568,7 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
                 ...payload,
                 data: {
                     project: compactProject(record),
+                    worktreeBootstrap: compactWorktreeBootstrapStatus(bootstrapStatus),
                     ...payload.data,
                 },
                 ...(routedNextActions && routedNextActions.length > 0 ? { nextActions: routedNextActions } : {}),

package/cli/presentation/commands.ts

@@ -7,7 +7,7 @@ export const proteumCommandNames = [
     'init',
     'create',
     'configure',
-    'migrate',
+    'worktree',
     'dev',
     'refresh',
     'build',
@@ -61,7 +61,7 @@ export const proteumCommandGroups: Array<{ title: string; names: TProteumCommand
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check', 'e2e'] },
     { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'db', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
-    { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
+    { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'worktree'] },
 ];
 
 export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> = {
@@ -135,28 +135,38 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
-    migrate: {
-        name: 'migrate',
+    worktree: {
+        name: 'worktree',
         category: 'Project scaffolding',
-        summary: 'Rewrite legacy page registrations to the explicit Router.page(path, options, data, render) contract.',
-        usage: 'proteum migrate page-contract [--cwd <path>] [--dry-run] [--json]',
+        summary: 'Initialize or create Codex worktrees with a Proteum bootstrap marker.',
+        usage:
+            'proteum worktree <init|create> [target-repo-root] --source <app-root> [--branch <branch>] [--base <ref>] [--refresh] [--skip-deps --reason <text>] [--json]',
         bestFor:
-            'Upgrading existing Proteum apps to the single explicit page contract without hand-editing every `client/pages/**` file.',
+            'Making newly created Codex worktrees explicit and machine-checkable before agents run refresh, runtime, dev, verify, or MCP workflow reads.',
         examples: [
-            { description: 'Rewrite the current app in place', command: 'proteum migrate page-contract' },
             {
-                description: 'Preview the migration without writing files',
-                command: 'proteum migrate page-contract --dry-run --json',
+                description: 'Initialize the current Codex worktree from a source app root',
+                command: 'proteum worktree init --source /path/to/main-app',
+            },
+            {
+                description: 'Refresh a stale bootstrap marker',
+                command: 'proteum worktree init --source /path/to/main-app --refresh',
+            },
+            {
+                description: 'Create a new Git worktree and bootstrap the matching Proteum app root',
+                command:
+                    'proteum worktree create /path/to/.codex/worktrees/feature --source /path/to/main-app --branch feature/worktree-bootstrap',
             },
             {
-                description: 'Migrate another app root from the current shell',
-                command: 'proteum migrate page-contract --cwd /path/to/app',
+                description: 'Record an intentional dependency-install skip',
+                command: 'proteum worktree init --source /path/to/main-app --skip-deps --reason "dependencies are shared by the parent workspace"',
             },
         ],
         notes: [
-            'This migration rewrites supported legacy Router.page signatures to the explicit 4-argument form.',
-            'If a page data function cannot be analyzed safely, Proteum leaves the file unchanged and reports a manual-fix location.',
-            'Run `proteum typecheck` and `proteum build --strict` after the rewrite.',
+            'Bootstrap writes `.proteum/worktree-bootstrap.json` with hashes, step timestamps, dependency status, runtime status, and Proteum version.',
+            'When `.env` is missing, `--source` is required and must point to an app root with a readable `.env`.',
+            'Guarded commands block inside `/.codex/worktrees/` until bootstrap is complete or explicitly bypassed with `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1`.',
+            '`worktree create` preserves the source app root path relative to the source repository root, so monorepo app roots are bootstrapped in the matching target location.',
         ],
         status: 'experimental',
     },

package/cli/runtime/commands.ts

@@ -4,6 +4,7 @@ import path from 'path';
 import cli, { type TArgsObject } from '../context';
 import { applyLegacyBooleanArgs, assertNoLegacyArgs } from './argv';
 import { buildUsage, ProteumCommand, runCommandModule } from './command';
+import { createWorktreeBootstrapBlockResponse, getWorktreeBootstrapStatus } from './worktreeBootstrap';
 import { createStartDevCommand, quoteShellPath, resolveProteumAppRootContext } from '../utils/appRoots';
 import { printJson } from '../utils/agentOutput';
 
@@ -68,6 +69,19 @@ const printNonAppRootResponse = ({
 
 const isCurrentWorkdirProteumAppRoot = () => resolveProteumAppRootContext(String(cli.args.workdir || process.cwd())).isAppRoot;
 
+const blockIfWorktreeBootstrapRequired = () => {
+    const status = getWorktreeBootstrapStatus({
+        appRoot: cli.paths.appRoot,
+        proteumVersion: String(cli.packageJson.version || ''),
+    });
+
+    if (!status.blocking) return false;
+
+    printJson(createWorktreeBootstrapBlockResponse(status));
+    process.exitCode = 1;
+    return true;
+};
+
 class InitCommand extends ProteumCommand {
     public static paths = [['init']];
 
@@ -156,26 +170,35 @@ class ConfigureCommand extends ProteumCommand {
     }
 }
 
-class MigrateCommand extends ProteumCommand {
-    public static paths = [['migrate']];
+class WorktreeCommand extends ProteumCommand {
+    public static paths = [['worktree']];
 
-    public static usage = buildUsage('migrate');
+    public static usage = buildUsage('worktree');
 
-    public cwd = Option.String('--cwd', { description: 'Run the migration against another Proteum app root.' });
-    public dryRun = Option.Boolean('--dry-run', false, { description: 'Print the rewrite plan without writing files.' });
-    public json = Option.Boolean('--json', false, { description: 'Print machine-readable migration output.' });
+    public source = Option.String('--source', { description: 'Source Proteum app root used for .env copy and worktree creation.' });
+    public branch = Option.String('--branch', { description: 'Branch name created by `worktree create`.' });
+    public base = Option.String('--base', { description: 'Base ref used by `worktree create`.' });
+    public refresh = Option.Boolean('--refresh', false, { description: 'Refresh an existing stale bootstrap marker.' });
+    public skipDeps = Option.Boolean('--skip-deps', false, { description: 'Skip dependency install while recording an explicit reason.' });
+    public reason = Option.String('--reason', { description: 'Reason required when --skip-deps is used.' });
+    public json = Option.Boolean('--json', false, { description: 'Print machine-readable worktree bootstrap output.' });
     public args = Option.Rest();
 
     public async execute() {
-        const [action = ''] = this.args;
+        const [action = '', target = ''] = this.args;
 
         this.setCliArgs({
             action,
-            workdir: this.cwd ?? '',
-            dryRun: this.dryRun,
+            base: this.base ?? '',
+            branch: this.branch ?? '',
             json: this.json,
+            reason: this.reason ?? '',
+            refresh: this.refresh,
+            skipDeps: this.skipDeps,
+            source: this.source ?? '',
+            target,
         });
-        await runCommandModule(() => import('../commands/migrate'));
+        await runCommandModule(() => import('../commands/worktree'));
     }
 }
 
@@ -222,6 +245,7 @@ class DevCommand extends ProteumCommand {
             printNonAppRootResponse({ commandName: 'dev', cwd: String(cli.args.workdir || process.cwd()) });
             return 1;
         }
+        if (action !== 'stop' && blockIfWorktreeBootstrapRequired()) return 1;
         await runCommandModule(() => import('../commands/dev'));
     }
 }
@@ -236,6 +260,7 @@ class RefreshCommand extends ProteumCommand {
     public async execute() {
         assertNoLegacyArgs('refresh', this.legacyArgs);
         this.setCliArgs();
+        if (blockIfWorktreeBootstrapRequired()) return 1;
         await runCommandModule(() => import('../commands/refresh'));
     }
 }
@@ -776,6 +801,7 @@ class RuntimeCommand extends ProteumCommand {
             return 1;
         }
 
+        if (blockIfWorktreeBootstrapRequired()) return 1;
         await runCommandModule(() => import('../commands/runtime'));
     }
 }
@@ -869,6 +895,7 @@ class VerifyCommand extends ProteumCommand {
             websitePort: this.websitePort ?? '',
         });
 
+        if (blockIfWorktreeBootstrapRequired()) return 1;
         await runCommandModule(() => import('../commands/verify'));
     }
 }
@@ -877,7 +904,7 @@ export const registeredCommands = {
     init: InitCommand,
     create: CreateCommand,
     configure: ConfigureCommand,
-    migrate: MigrateCommand,
+    worktree: WorktreeCommand,
     dev: DevCommand,
     refresh: RefreshCommand,
     build: BuildCommand,
@@ -913,7 +940,7 @@ export const createCli = (version: string) => {
     clipanion.register(InitCommand);
     clipanion.register(CreateCommand);
     clipanion.register(ConfigureCommand);
-    clipanion.register(MigrateCommand);
+    clipanion.register(WorktreeCommand);
     clipanion.register(DevCommand);
     clipanion.register(RefreshCommand);
     clipanion.register(BuildCommand);