proteum 2.4.4 → 2.5.1

package/tests/dev-transpile-watch.test.cjs

@@ -370,24 +370,26 @@ ${cacheConfigSource}
     );
     writeFile(
         path.join(appRoot, 'server', 'index.ts'),
-        `import { Application } from '@server/app';
+        `import { defineApplication } from '@server/app';
 import Router from '@server/services/router';
 import SchemaRouter from '@server/services/schema/router';
 
 import * as appConfig from '@/server/config/app';
 
-export default class TranspileWatchFixture extends Application {
-    public Router = new Router(
-        this,
-        {
-            ...appConfig.routerBaseConfig,
-            plugins: {
-                schema: new SchemaRouter({}, this),
+export default defineApplication({
+    services: () => ({}),
+    router: (app) =>
+        new Router(
+            app,
+            {
+                ...appConfig.routerBaseConfig,
+                plugins: {
+                    schema: new SchemaRouter({}, app),
+                },
             },
-        },
-        this,
-    );
-}
+            app,
+        ),
+});
 `,
     );
     writeFile(
@@ -403,56 +405,53 @@ export default class TranspileWatchClient extends ClientApplication {
 
     public boot() {}
     public handleUpdate() {}
-    public handleError(error: Error) {
-        throw error;
-    }
 }
 `,
     );
     writeFile(
         path.join(appRoot, 'client', 'pages', 'index.tsx'),
-        `import Router from '@/client/router';
+        `import { definePageRoute } from '@common/router/definitions';
 import { SharedMarker } from '@test/shared';
 
-Router.page(
-    '/',
-    {
+export default definePageRoute({
+    path: '/',
+    options: {
         auth: false,
         layout: false,
     },
-    null,
-    () => {
+    data: null,
+    render: () => {
         return (
             <main>
                 <SharedMarker />
             </main>
         );
     },
-);
+});
 `,
     );
     if (options.staticPage) {
         writeFile(
             path.join(appRoot, 'client', 'pages', 'static-cache.tsx'),
-            `import Router from '@/client/router';
+            `import { definePageRoute } from '@common/router/definitions';
 import { SharedMarker } from '@test/shared';
 
-Router.page(
-    '/static-cache',
-    {
+export default definePageRoute({
+    path: '/static-cache',
+    options: {
         auth: false,
         layout: false,
         static: { urls: ['/static-cache'] },
     },
-    null,
-    () => {
+    data: null,
+    render: () => {
         return (
             <main>
                 <SharedMarker />
             </main>
         );
     },
-);
+});
 `,
         );
     }
@@ -539,8 +538,13 @@ test('proteum dev invalidates client assets and reloads for transpiled package s
 
     try {
         await waitForSessionReady(sessionFile, child, getOutput);
+        await request(port, '/', { Accept: 'text/html' });
 
-        const initialScriptAsset = await waitForAssetContaining(appRoot, '.js', 'SCRIPT_MARKER_INITIAL');
+        const initialScriptAsset = await waitForAssetContaining(appRoot, '.js', 'SCRIPT_MARKER_INITIAL').catch(
+            (error) => {
+                throw new Error(`${error.message}\n${getOutput()}`);
+            },
+        );
         const initialScriptContent = fs.readFileSync(initialScriptAsset, 'utf8');
         const scriptReloadStream = await connectToReloadStream(port + 1);
 
@@ -608,7 +612,9 @@ test('proteum dev applies router HTTP cache config to HTML and public assets', {
         const staticResponse = await waitForHeader(port, '/static-cache', 'cache-control', staticHtmlCacheControl);
         assert.equal(staticResponse.headers.get('surrogate-control'), 'static-surrogate');
 
-        const asset = await waitForAssetContaining(appRoot, '.js', 'SCRIPT_MARKER_INITIAL');
+        const asset = await waitForAssetContaining(appRoot, '.js', 'SCRIPT_MARKER_INITIAL').catch((error) => {
+            throw new Error(`${error.message}\n${getOutput()}`);
+        });
         const { response: assetResponse } = await request(port, toPublicAssetUrl(appRoot, asset));
 
         assert.equal(assetResponse.headers.get('cache-control'), publicAssetCacheControl);

package/tests/eslint-rules.test.cjs

@@ -3,14 +3,25 @@ const { Linter } = require('eslint');
 
 const { createProteumEslintConfig } = require('../eslint.js');
 
-const lint = (code) => {
+const lint = (code, filename = 'client/example.tsx') => {
     const linter = new Linter({ configType: 'flat' });
     return linter.verify(code, createProteumEslintConfig(), {
-        filename: 'client/example.tsx',
+        filename,
     });
 };
 
 const swallowedErrorRuleId = 'proteum/no-swallowed-caught-error';
+const noAppImportRuleId = 'proteum/no-app-import';
+
+test('proteum lint rejects contextual @app imports', () => {
+    const messages = lint(`
+        import { Router } from '@app';
+
+        export const route = Router;
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === noAppImportRuleId), true);
+});
 
 test('proteum lint rejects empty catch blocks', () => {
     const messages = lint(`
@@ -50,6 +61,32 @@ test('proteum lint rejects generic catch feedback that drops original error deta
     assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
+test('proteum lint rejects console calls as caught error preservation', () => {
+    for (const method of ['error', 'warn']) {
+        const messages = lint(`
+            export const run = async () => {
+                try {
+                    await Investor.api.getDashboard();
+                } catch (error) {
+                    console.${method}(error);
+                }
+            };
+        `);
+
+        assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+    }
+});
+
+test('proteum lint rejects direct console promise catch handlers', () => {
+    const messages = lint(`
+        export const run = () => {
+            Investor.api.ensureApiKey().catch(console.log);
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
 test('proteum lint allows rethrowing the caught error', () => {
     const messages = lint(`
         export const run = async () => {
@@ -65,7 +102,7 @@ test('proteum lint allows rethrowing the caught error', () => {
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
 
-test('proteum lint allows surfacing original error details', () => {
+test('proteum lint rejects user feedback that does not route the caught error', () => {
     const messages = lint(`
         export const run = async () => {
             try {
@@ -78,10 +115,10 @@ test('proteum lint allows surfacing original error details', () => {
         };
     `);
 
-    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
-test('proteum lint allows surfacing a message derived from the caught error', () => {
+test('proteum lint rejects derived message state that does not route the caught error', () => {
     const messages = lint(`
         export const run = async () => {
             try {
@@ -93,17 +130,157 @@ test('proteum lint allows surfacing a message derived from the caught error', ()
         };
     `);
 
-    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
-test('proteum lint allows routing promise failures to app error handling', () => {
+test('proteum lint allows client catches routed to context app error handling', () => {
     const messages = lint(`
         export const run = () => {
+            const context = useContext();
             Investor.api.ensureApiKey().catch((error) => {
-                Router.app.handleError(error);
+                context.app.handleError(error);
             });
         };
     `);
 
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
+
+test('proteum lint allows client catches using app error messages for UI feedback', () => {
+    const messages = lint(`
+        export const run = async () => {
+            const context = useContext();
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                setError(context.app.handleError(error, 'Unable to finish this action.'));
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows client catches routed to local app error handling', () => {
+    const messages = lint(`
+        export const run = async () => {
+            const app = useContext();
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                app.handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows client catches routed to useContext app error handling', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                useContext().app.handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint rejects bare client error handlers', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows server catches routed to app error reporting', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    await context.app.reportError(error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint rejects server catches routed to client app error handling', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    context.app.handleError(error);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint rejects raw server error hooks as caught error handling', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    await context.app.runHook('error', error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows manual promise rejection', () => {
+    const messages = lint(
+        `
+            export const run = (input) =>
+                new Promise((resolve, reject) => {
+                    input.load().catch((error) => {
+                        reject(error);
+                    });
+                });
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows direct reject promise catch handlers', () => {
+    const messages = lint(
+        `
+            export const run = (input) =>
+                new Promise((resolve, reject) => {
+                    input.load().catch(reject);
+                });
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 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/scaffold-templates.test.cjs

@@ -0,0 +1,18 @@
+const assert = require('node:assert/strict');
+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 { createServerIndexTemplate } = require('../cli/scaffold/templates.ts');
+
+test('server index scaffold uses explicit defineApplication router property', () => {
+    const content = createServerIndexTemplate({ appIdentifier: 'ExampleApp' });
+
+    assert.match(content, /export default defineApplication\(\{/);
+    assert.match(content, /services: \(\) => \(\{\}\),/);
+    assert.match(content, /router: \(app\) =>\s+new Router\(/);
+    assert.doesNotMatch(content, /services: \(app\) => \(\{\s+Router: new Router\(/);
+});

package/tests/server-app-report-error.test.cjs

@@ -0,0 +1,135 @@
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+const path = require('node:path');
+
+const coreRoot = path.join(__dirname, '..');
+require('module-alias').addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+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 appContainerStub = {
+    Environment: {
+        profile: 'test',
+        connectedProjects: [],
+    },
+    Identity: {},
+    Setup: {},
+    Console: {
+        createBugReport: () => {},
+    },
+    Trace: {
+        finishRequest: () => {},
+        record: () => {},
+        releaseRequest: () => {},
+    },
+    handleBug: () => {},
+};
+
+const applicationModulePath = path.join(coreRoot, 'server/app/index.ts');
+const originalLoad = Module._load;
+Module._load = function patchedLoad(request, parent, isMain) {
+    if (parent?.filename === applicationModulePath && request === './container') {
+        return { __esModule: true, default: appContainerStub };
+    }
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+let Application;
+try {
+    Application = require('../server/app/index.ts').Application;
+} finally {
+    Module._load = originalLoad;
+}
+
+class TestApplication extends Application {}
+
+const createAppWithHooks = (hooks) => {
+    const app = new TestApplication();
+    app.hooks = hooks;
+
+    return app;
+};
+
+test('server application reports plain errors through the default error hook', async () => {
+    const events = [];
+    const request = { id: 'request-1' };
+    const app = createAppWithHooks({
+        error: [
+            async (error, hookRequest) => {
+                events.push({
+                    hook: 'error',
+                    message: error.message,
+                    requestId: hookRequest.id,
+                });
+            },
+        ],
+    });
+
+    await app.reportError(new Error('boom'), request);
+
+    assert.deepEqual(events, [{ hook: 'error', message: 'boom', requestId: 'request-1' }]);
+});
+
+test('server application reports HTTP errors through code-specific hooks', async () => {
+    const events = [];
+    const error = new Error('missing');
+    error.http = 404;
+    const request = { id: 'request-404' };
+    const app = createAppWithHooks({
+        'error.404': [
+            async (hookError, hookRequest) => {
+                events.push({
+                    hook: 'error.404',
+                    message: hookError.message,
+                    requestId: hookRequest.id,
+                });
+            },
+        ],
+    });
+
+    await app.reportError(error, request);
+
+    assert.deepEqual(events, [{ hook: 'error.404', message: 'missing', requestId: 'request-404' }]);
+});
+
+test('server application reports status errors through code-specific hooks', async () => {
+    const events = [];
+    const error = new Error('forbidden');
+    error.status = 403;
+    const app = createAppWithHooks({
+        'error.403': [
+            async (hookError) => {
+                events.push({
+                    hook: 'error.403',
+                    message: hookError.message,
+                });
+            },
+        ],
+    });
+
+    await app.reportError(error);
+
+    assert.deepEqual(events, [{ hook: 'error.403', message: 'forbidden' }]);
+});
+
+test('server application normalizes non-error rejections before reporting', async () => {
+    const messages = [];
+    const app = createAppWithHooks({
+        error: [
+            async (error) => {
+                messages.push(error.message);
+            },
+        ],
+    });
+
+    await app.reportError('string failure');
+    await app.reportError({ reason: 'unknown failure' });
+
+    assert.deepEqual(messages, ['string failure', 'Unknown application error']);
+});