proteum 2.4.3 → 2.5.0

package/tests/mcp.test.cjs

@@ -186,6 +186,14 @@ test('instruction routing promotes triggered full instruction files', () => {
     );
     assert.equal(payload.data.fullReadPolicy.default.includes('read-only'), true);
     assert.equal(payload.data.selected.some((entry) => entry.fullRead === 'full-before-action'), true);
+
+    const bugFixPayload = resolveInstructionRouting({ appRoot, query: 'fix OAuth redirect bug' });
+    assert.equal(
+        bugFixPayload.data.selected.some(
+            (entry) => entry.file === path.join(appRoot, 'DOCUMENTATION.md') && /Bug fix/.test(entry.reason),
+        ),
+        true,
+    );
 });
 
 test('workflow start payload combines compact runtime, instructions, owner, and duplicate guidance', () => {
@@ -777,6 +785,88 @@ test('machine MCP router resolves offline monorepo app candidates before dev is
     await server.close();
 });
 
+test('machine MCP workflow_start blocks offline unbootstrapped Codex worktrees', async (t) => {
+    const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-worktree-offline-'));
+    process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = registryDir;
+    t.onTestFinished(() => {
+        if (previousRegistryDir === undefined) delete process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+        else process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = previousRegistryDir;
+    });
+
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-worktree-repo-'));
+    const appRoot = path.join(repoRoot, '.codex', 'worktrees', 'product');
+    writeProteumAppFixture(appRoot, { identifier: 'ProductApp', name: 'Product', routerPort: 3020 });
+
+    const server = createProteumMachineMcpServer({ version: 'test' });
+    const client = new Client({ name: 'machine-mcp-test', version: '1.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    const workflow = await client.callTool({ name: 'workflow_start', arguments: { cwd: appRoot, task: 'runtime health' } });
+    const payload = JSON.parse(workflow.content[0].text);
+
+    assert.equal(payload.ok, false);
+    assert.match(payload.summary, /has not completed Proteum worktree bootstrap/);
+    assert.equal(payload.nextActions.length, 1);
+    assert.match(payload.nextActions[0].command, /proteum worktree init --source <source-app-root>/);
+
+    await client.close();
+    await server.close();
+});
+
+test('machine MCP workflow_start blocks live unbootstrapped Codex worktrees before forwarding', async (t) => {
+    const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-worktree-live-'));
+    process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = registryDir;
+    t.onTestFinished(() => {
+        if (previousRegistryDir === undefined) delete process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+        else process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = previousRegistryDir;
+    });
+
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-worktree-live-repo-'));
+    const appRoot = path.join(repoRoot, '.codex', 'worktrees', 'product');
+    writeProteumAppFixture(appRoot, { identifier: 'ProductApp', name: 'Product', routerPort: 3020 });
+    await writeMachineDevSessionRecord({
+        ...createDevSessionRecord({
+            appRoot,
+            port: 3020,
+            sessionFilePath: path.join(appRoot, 'var/run/proteum/dev/3020.json'),
+        }),
+        publicUrl: 'http://localhost:3020',
+        state: 'ready',
+    });
+
+    let forwarded = false;
+    const server = createProteumMachineMcpServer({
+        createDevMcpClient: async () => ({
+            callTool: async () => {
+                forwarded = true;
+                throw new Error('should not forward');
+            },
+            close: async () => {},
+        }),
+        version: 'test',
+    });
+    const client = new Client({ name: 'machine-mcp-test', version: '1.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    const workflow = await client.callTool({ name: 'workflow_start', arguments: { cwd: appRoot, task: 'runtime health' } });
+    const payload = JSON.parse(workflow.content[0].text);
+
+    assert.equal(payload.ok, false);
+    assert.equal(forwarded, false);
+    assert.match(payload.nextActions[0].command, /proteum worktree init --source <source-app-root>/);
+
+    await client.close();
+    await server.close();
+});
+
 test('machine MCP offline resolution inspects occupied ports before suggesting dev start', async (t) => {
     const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
     const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-offline-port-registry-'));

package/tests/worktree-bootstrap.test.cjs

@@ -0,0 +1,206 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const {
+    createWorktreeBootstrapDiagnostics,
+    getWorktreeBootstrapStatus,
+    runWorktreeBootstrapInit,
+    worktreeBootstrapMarkerRelativePath,
+} = require('../cli/runtime/worktreeBootstrap.ts');
+
+const writeFile = (filepath, content) => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+const createCodexAppRoot = () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-bootstrap-'));
+    const appRoot = path.join(root, '.codex', 'worktrees', 'fixture-app');
+
+    fs.mkdirSync(appRoot, { recursive: true });
+    return appRoot;
+};
+
+const writeBootstrapFixture = (appRoot, { env = true, manifest = true, nodeModules = true } = {}) => {
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Agents\n');
+    if (env) writeFile(path.join(appRoot, '.env'), 'PORT=3020\n');
+    if (manifest) writeFile(path.join(appRoot, '.proteum', 'manifest.json'), '{"version":10}\n');
+    if (nodeModules) fs.mkdirSync(path.join(appRoot, 'node_modules'), { recursive: true });
+};
+
+const noOpRefresh = async () => ({ stdout: '', stderr: '', summary: 'refresh ok' });
+const noOpRuntime = async () => ({ stdout: '', stderr: '', summary: 'runtime ok' });
+const noOpDeps = async () => {};
+
+test('worktree bootstrap status blocks Codex worktrees without a marker', () => {
+    const appRoot = createCodexAppRoot();
+    writeBootstrapFixture(appRoot);
+
+    const status = getWorktreeBootstrapStatus({ appRoot, proteumVersion: 'test' });
+
+    assert.equal(status.guarded, true);
+    assert.equal(status.blocking, true);
+    assert.equal(status.state, 'missing');
+    assert.equal(status.staleReasons[0].code, 'worktree-bootstrap/missing-marker');
+});
+
+test('worktree bootstrap init writes a fresh marker with hashes and runtime status', async () => {
+    const appRoot = createCodexAppRoot();
+    writeBootstrapFixture(appRoot);
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+    });
+
+    assert.equal(fs.existsSync(path.join(appRoot, worktreeBootstrapMarkerRelativePath)), true);
+    assert.equal(result.status.blocking, false);
+    assert.equal(result.marker.proteumVersion, 'test');
+    assert.equal(result.marker.refresh.status, 'ok');
+    assert.equal(result.marker.runtimeStatus.summary, 'runtime ok');
+});
+
+test('worktree bootstrap becomes stale when tracked inputs change', async () => {
+    const appRoot = createCodexAppRoot();
+    writeBootstrapFixture(appRoot);
+
+    await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+    });
+
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3,"changed":true}\n');
+
+    const status = getWorktreeBootstrapStatus({ appRoot, proteumVersion: 'test' });
+
+    assert.equal(status.blocking, true);
+    assert.equal(
+        status.staleReasons.some((reason) => reason.code === 'worktree-bootstrap/package-lock-changed'),
+        true,
+    );
+});
+
+test('worktree bootstrap accepts intentional dependency skips with a reason', async () => {
+    const appRoot = createCodexAppRoot();
+    writeBootstrapFixture(appRoot, { nodeModules: false });
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        reason: 'dependencies are shared by the parent workspace',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+        skipDeps: true,
+    });
+
+    assert.equal(result.status.blocking, false);
+    assert.equal(result.marker.dependencies.status, 'skipped');
+    assert.equal(result.marker.skips.dependencies.reason, 'dependencies are shared by the parent workspace');
+});
+
+test('worktree bootstrap requires a source env only when .env is missing', async () => {
+    const appRoot = createCodexAppRoot();
+    writeBootstrapFixture(appRoot, { env: false });
+
+    await assert.rejects(
+        () =>
+            runWorktreeBootstrapInit({
+                appRoot,
+                coreRoot,
+                proteumVersion: 'test',
+                runDependencies: noOpDeps,
+                runRefresh: noOpRefresh,
+                runRuntimeStatus: noOpRuntime,
+            }),
+        /missing \.env/,
+    );
+
+    const sourceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-source-'));
+    writeFile(path.join(sourceRoot, '.env'), 'PORT=3021\n');
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+        source: sourceRoot,
+    });
+
+    assert.equal(fs.readFileSync(path.join(appRoot, '.env'), 'utf8'), 'PORT=3021\n');
+    assert.equal(result.marker.env.copied, true);
+    assert.equal(result.status.blocking, false);
+});
+
+test('worktree bootstrap detects missing env manifest node_modules and version changes', async () => {
+    const appRoot = createCodexAppRoot();
+    writeBootstrapFixture(appRoot);
+
+    await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+    });
+
+    fs.rmSync(path.join(appRoot, '.env'));
+    fs.rmSync(path.join(appRoot, '.proteum', 'manifest.json'));
+    fs.rmSync(path.join(appRoot, 'node_modules'), { force: true, recursive: true });
+
+    const status = getWorktreeBootstrapStatus({ appRoot, proteumVersion: 'next' });
+    const codes = status.staleReasons.map((reason) => reason.code);
+
+    assert.equal(status.blocking, true);
+    assert.equal(codes.includes('worktree-bootstrap/env-missing'), true);
+    assert.equal(codes.includes('worktree-bootstrap/manifest-missing'), true);
+    assert.equal(codes.includes('worktree-bootstrap/node-modules-missing'), true);
+    assert.equal(codes.includes('worktree-bootstrap/proteum-version-changed'), true);
+});
+
+test('worktree bootstrap bypass keeps status visible without blocking', () => {
+    const appRoot = createCodexAppRoot();
+    const previous = process.env.PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE;
+    process.env.PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE = '1';
+
+    try {
+        writeBootstrapFixture(appRoot);
+        const status = getWorktreeBootstrapStatus({ appRoot, proteumVersion: 'test' });
+
+        assert.equal(status.bypassed, true);
+        assert.equal(status.blocking, false);
+        assert.equal(status.state, 'bypassed');
+        assert.equal(status.staleReasons.length > 0, true);
+        assert.equal(
+            createWorktreeBootstrapDiagnostics({ appRoot, status }).some(
+                (diagnostic) => diagnostic.code === 'worktree-bootstrap/bypassed',
+            ),
+            true,
+        );
+    } finally {
+        if (previous === undefined) delete process.env.PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE;
+        else process.env.PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE = previous;
+    }
+});

package/types/aliases.d.ts

@@ -49,8 +49,3 @@ declare module '@/client/context' {
 
     export default useContext;
 }
-
-declare module '@app' {
-    const ServerApplicationClass: import('../server/app').default;
-    export = ServerApplicationClass;
-}

package/types/controller-input.test.ts

@@ -1,4 +1,9 @@
-import Controller, { schema } from '@server/app/controller';
+import {
+    defineAction,
+    defineController,
+    schema,
+    type TControllerActionInput,
+} from '@server/app/controller';
 
 type Assert<T extends true> = T;
 
@@ -8,25 +13,26 @@ type Equals<TLeft, TRight> = (<T>() => T extends TLeft ? 1 : 2) extends <T>() =>
         : false
     : false;
 
-class InputInferenceController extends Controller {
-    public fromShape() {
-        return this.input({
-            name: schema.string(),
-            age: schema.number().optional(),
-        });
-    }
-
-    public fromSchema() {
-        return this.input(
-            schema.object({
+const controller = defineController({
+    actions: {
+        fromShape: defineAction({
+            input: {
+                name: schema.string(),
+                age: schema.number().optional(),
+            },
+            handler: ({ input }) => input,
+        }),
+        fromSchema: defineAction({
+            input: schema.object({
                 slug: schema.string(),
             }),
-        );
-    }
-}
+            handler: ({ input }) => input,
+        }),
+    },
+});
 
-type TFromShape = ReturnType<InputInferenceController['fromShape']>;
-type TFromSchema = ReturnType<InputInferenceController['fromSchema']>;
+type TFromShape = TControllerActionInput<typeof controller, 'fromShape'>;
+type TFromSchema = TControllerActionInput<typeof controller, 'fromSchema'>;
 
 type _AssertShapeInference = Assert<
     Equals<

package/types/controller-request-context.test.ts

@@ -1,5 +1,5 @@
 import type { Application } from '@server/app';
-import Controller from '@server/app/controller';
+import type { TControllerActionContext } from '@server/app/controller';
 import type { TServerRouter } from '@server/services/router';
 import type { TServiceModelsClient, TServiceRequestContext } from '@server/app/service';
 
@@ -38,18 +38,17 @@ interface TTestApp extends Application {
     };
 }
 
-class TypedRequestController extends Controller<TTestApp> {
-    public useAuth() {
-        return this.request.auth.check();
-    }
-}
-
-type TRequestAuth = TypedRequestController['request']['auth'];
-type TAuthCheckResult = ReturnType<TypedRequestController['useAuth']>;
+type TControllerContext = TControllerActionContext<undefined, TTestApp>;
+type TControllerContextAuth = TControllerContext['auth'];
+type TControllerModelsClient = TControllerContext['models'];
 type TServiceContextAuth = TServiceRequestContext<TTestApp>['auth'];
 type TModelsClient = TServiceModelsClient<TTestApp>;
 
-type _AssertTypedRequestService = Assert<Equals<TRequestAuth['check'], TTypedAuthRequestService['check']>>;
-type _AssertTypedAuthCheckResult = Assert<Equals<TAuthCheckResult, 'typed-user'>>;
+type _AssertTypedControllerRequestService = Assert<
+    Equals<TControllerContextAuth['check'], TTypedAuthRequestService['check']>
+>;
 type _AssertTypedServiceRequestContext = Assert<Equals<TServiceContextAuth['check'], TTypedAuthRequestService['check']>>;
+type _AssertTypedControllerModelsClient = Assert<
+    Equals<ReturnType<TControllerModelsClient['post']['findMany']>, 'posts'>
+>;
 type _AssertTypedModelsClient = Assert<Equals<ReturnType<TModelsClient['post']['findMany']>, 'posts'>>;

package/cli/commands/migrate.ts

@@ -1,51 +0,0 @@
-import path from 'path';
-
-import cli from '..';
-import { runPageContractMigration } from '../migrate/pageContract';
-
-const printHuman = (summary: ReturnType<typeof runPageContractMigration>) => {
-    console.log(`Proteum migrate page-contract`);
-    console.log(`App root: ${summary.appRoot}`);
-    console.log(`Scanned files: ${summary.scannedFiles}`);
-    console.log(`Changed files: ${summary.changedFiles.length}${summary.dryRun ? ' (dry run)' : ''}`);
-
-    if (summary.changedFiles.length > 0) {
-        console.log('');
-        console.log('Rewritten files:');
-        for (const filepath of summary.changedFiles) {
-            console.log(`- ${path.relative(summary.appRoot, filepath)}`);
-        }
-    }
-
-    if (summary.manualFixes.length > 0) {
-        console.log('');
-        console.log('Manual fixes required:');
-        for (const fix of summary.manualFixes) {
-            console.log(
-                `- ${path.relative(summary.appRoot, fix.filepath)}:${fix.line}:${fix.column} ${fix.routeLabel} :: ${fix.reason}`,
-            );
-        }
-    }
-};
-
-export const run = async (): Promise<void> => {
-    const action = String(cli.args.action || '').trim();
-    if (action !== 'page-contract') {
-        throw new Error(`Unsupported migrate action "${action}". Expected "page-contract".`);
-    }
-
-    const summary = runPageContractMigration({
-        appRoot: String(cli.args.workdir || process.cwd()),
-        dryRun: cli.args.dryRun === true,
-    });
-
-    if (cli.args.json === true) {
-        console.log(JSON.stringify(summary, null, 2));
-    } else {
-        printHuman(summary);
-    }
-
-    if (summary.manualFixes.length > 0) {
-        throw new Error(`Page-contract migration requires manual fixes in ${summary.manualFixes.length} location(s).`);
-    }
-};