proteum 2.4.4 → 2.5.0

package/server/services/router/response/index.ts

@@ -60,6 +60,7 @@ export type TRouterContext<TRouter extends TServerRouter> =
     // Request context
     {
         app: TServerRouterApplication<TRouter>;
+        services: TServerRouterApplication<TRouter>;
         context: TRouterContext<TRouter>; // = this
         request: ServerRequest<TRouter>;
         api: ServerRequest<TRouter>['api'];
@@ -155,14 +156,12 @@ export default class ServerResponse<
         const contextStore = context.getStore() as
             | {
                   requestContext?: TRouterContext<TAnyRouter>;
-                  inputSchemaUsed?: boolean;
                   ownerLabel?: string;
                   ownerFilepath?: string;
               }
             | undefined;
         if (contextStore) {
             contextStore.requestContext = requestContext;
-            contextStore.inputSchemaUsed = false;
             contextStore.ownerLabel = getRouteTraceTarget(route as TAnyRoute<TRouterContext<TServerRouter>>);
             contextStore.ownerFilepath = route.options.filepath || undefined;
         }
@@ -229,6 +228,7 @@ export default class ServerResponse<
         const requestContext: TRouterContext<TRouter> = {
             // Router context
             app: this.app,
+            services: this.app,
             context: undefined!,
             request: this.request,
             response: this,

package/tests/agents-utils.test.cjs

@@ -104,11 +104,23 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.match(agentsContent, /\/__proteum\/mcp/);
     assert.match(agentsContent, /central MCP ready banner/);
     assert.match(agentsContent, /proteum-mcp-v1/);
+    assert.match(agentsContent, /## Explicit App-Building Contract/);
+    assert.match(agentsContent, /defineApplication\(\{ services, router, models, commands \}\)/);
+    assert.match(agentsContent, /definePageRoute\(\{ path, options, data, render \}\)/);
+    assert.match(agentsContent, /defineController\(\{ path, actions \}\)/);
+    assert.match(agentsContent, /Never import `@app` in page, route, or controller files/);
+    assert.match(agentsContent, /Never call top-level `Router\.page\(\.\.\.\)`/);
     assert.match(agentsContent, /## Triggered Instruction Reads/);
+    assert.match(agentsContent, /Worktree Preflight/);
+    assert.match(agentsContent, /npx proteum worktree init --source <source-app-root>/);
+    assert.match(agentsContent, /--skip-deps --reason/);
     assert.match(agentsContent, /Git lifecycle/);
     assert.match(agentsContent, /read Root contract fallback before any git write/);
+    assert.match(agentsContent, /Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change/);
     assert.match(agentsContent, /add or update focused unit tests/);
-    assert.match(agentsContent, /read Root contract fallback, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /read Root contract fallback, `DOCUMENTATION\.md`, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /Bug fixes, regressions, incidents, broken public routes, auth\/OAuth failures/);
+    assert.match(agentsContent, /docs\/fixes\/YYYY-MM-DD-short-bug-name\.md/);
     assert.match(agentsContent, /GEO\/SEO\/crawler\/structured-data\/AI-source changes/);
     assert.match(agentsContent, /MCP-selected previews are enough/);
     assert.doesNotMatch(agentsContent, /Conventional Commits/);
@@ -234,6 +246,7 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Known Proteum Apps/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /apps\/product/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Do not start `npx proteum dev` from this root/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Worktree Preflight/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'CODING_STYLE.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'DOCUMENTATION.md'), 'utf8'), /## Source: DOCUMENTATION\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'diagnostics.md'), 'utf8'), /## Source: diagnostics\.md/);

package/tests/cli-mcp-command.test.cjs

@@ -1,4 +1,5 @@
 const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
 const { spawn, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const http = require('node:http');
@@ -55,6 +56,42 @@ const createProteumApp = (appRoot, { routerPort = 3020 } = {}) => {
     );
 };
 
+const hashFile = (filepath) => crypto.createHash('sha256').update(fs.readFileSync(filepath)).digest('hex');
+
+const writeFreshWorktreeBootstrapMarker = (appRoot) => {
+    const timestamp = new Date().toISOString();
+    fs.mkdirSync(path.join(appRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, '.env'), 'PORT=3020\n');
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Agents\n');
+
+    writeFile(
+        path.join(appRoot, '.proteum', 'worktree-bootstrap.json'),
+        JSON.stringify(
+            {
+                version: 1,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+                proteumVersion: require('../package.json').version,
+                packageLockHash: hashFile(path.join(appRoot, 'package-lock.json')),
+                proteumConfigHash: hashFile(path.join(appRoot, 'proteum.config.ts')),
+                agentsHash: hashFile(path.join(appRoot, 'AGENTS.md')),
+                env: { present: true, copied: false },
+                refresh: { status: 'ok', ranAt: timestamp },
+                dependencies: {
+                    status: 'up-to-date',
+                    ranAt: timestamp,
+                    nodeModulesPresent: true,
+                    packageLockHash: hashFile(path.join(appRoot, 'package-lock.json')),
+                },
+                runtimeStatus: { status: 'ok', checkedAt: timestamp, summary: 'runtime ok' },
+            },
+            null,
+            2,
+        ),
+    );
+};
+
 const listen = async (server, port = 0) =>
     await new Promise((resolve, reject) => {
         server.once('error', reject);
@@ -150,6 +187,7 @@ test('top-level help lists the machine-scope mcp router', () => {
 
     assert.equal(result.status, 0);
     assert.match(result.stdout, /proteum mcp\b/);
+    assert.match(result.stdout, /proteum worktree\b/);
     assert.match(result.stdout, /machine-scope MCP router/);
 });
 
@@ -287,6 +325,52 @@ test('runtime status manifest guard points to explain manifest', () => {
     assert.match(payload.nextActions[0].command, /proteum explain --manifest/);
 });
 
+test('runtime status blocks unbootstrapped Codex worktrees', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-worktree-block-'));
+    const appRoot = path.join(root, '.codex', 'worktrees', 'product');
+    createProteumApp(appRoot);
+
+    const result = spawnSync(process.execPath, [cliBin, 'runtime', 'status'], {
+        cwd: appRoot,
+        encoding: 'utf8',
+    });
+    const payload = JSON.parse(result.stdout);
+
+    assert.equal(result.status, 1);
+    assert.equal(payload.ok, false);
+    assert.match(payload.summary, /has not completed Proteum worktree bootstrap/);
+    assert.match(payload.nextActions[0].command, /proteum worktree init --source <source-app-root>/);
+});
+
+test('runtime status allows fresh Codex worktree bootstrap markers and reports stale refresh action', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-worktree-fresh-'));
+    const appRoot = path.join(root, '.codex', 'worktrees', 'product');
+    createProteumApp(appRoot);
+    writeFreshWorktreeBootstrapMarker(appRoot);
+
+    const fresh = spawnSync(process.execPath, [cliBin, 'runtime', 'status'], {
+        cwd: appRoot,
+        encoding: 'utf8',
+    });
+    const freshPayload = JSON.parse(fresh.stdout);
+
+    assert.equal(fresh.status, 0);
+    assert.equal(freshPayload.ok, true);
+    assert.equal(freshPayload.data.worktreeBootstrap.state, 'fresh');
+
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3,"changed":true}\n');
+
+    const stale = spawnSync(process.execPath, [cliBin, 'runtime', 'status'], {
+        cwd: appRoot,
+        encoding: 'utf8',
+    });
+    const stalePayload = JSON.parse(stale.stdout);
+
+    assert.equal(stale.status, 1);
+    assert.equal(stalePayload.ok, false);
+    assert.match(stalePayload.nextActions[0].command, /--refresh/);
+});
+
 test('runtime status reports occupied configured port without probing page bodies', async () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-port-'));
     const otherRoot = path.join(repoRoot, 'apps', 'other');

package/tests/definition-contracts.test.cjs

@@ -0,0 +1,453 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { EventEmitter } = require('node:events');
+
+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 {
+    indexRouteDefinitions,
+    writeGeneratedRouteModule,
+} = require('../cli/compiler/common/generatedRouteModules.ts');
+const { findClientRouteFiles } = require('../cli/compiler/artifacts/discovery.ts');
+const { indexControllers } = require('../cli/compiler/common/controllers.ts');
+const {
+    defineAction,
+    defineController,
+    runControllerAction,
+    schema,
+} = require('../server/app/controller/index.ts');
+const Service = require('../server/app/service/index.ts').default;
+const { expressHandler, registerRouteDefinition } = require('../common/router/definitions.ts');
+const { parseProteumEnvConfig } = require('../common/env/proteumEnv.ts');
+
+const createTempDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-definition-contracts-'));
+
+const writeFile = (filepath, content) => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+const loadServiceArtifactsForAppRoot = (appRoot) => {
+    const Module = require('node:module');
+    const modulePath = require.resolve('../cli/compiler/artifacts/services.ts');
+    const originalLoad = Module._load;
+    const appStub = { paths: { root: appRoot }, identity: { identifier: 'TestApp' }, containerServices: [] };
+    const cliStub = { paths: { core: { root: coreRoot } } };
+
+    delete require.cache[modulePath];
+    Module._load = function patchedLoad(request, parent, isMain) {
+        if (parent?.filename === modulePath && request === '../../app') {
+            return { __esModule: true, default: appStub };
+        }
+        if (parent?.filename === modulePath && request === '../..') {
+            return { __esModule: true, default: cliStub };
+        }
+
+        return originalLoad.call(this, request, parent, isMain);
+    };
+
+    try {
+        return require(modulePath);
+    } finally {
+        Module._load = originalLoad;
+    }
+};
+
+const withProteumEnv = (env, run) => {
+    const previous = {};
+    for (const key of Object.keys(env)) previous[key] = process.env[key];
+
+    Object.assign(process.env, env);
+
+    try {
+        return run();
+    } finally {
+        for (const key of Object.keys(env)) {
+            if (previous[key] === undefined) delete process.env[key];
+            else process.env[key] = previous[key];
+        }
+    }
+};
+
+test('route indexer reads explicit page definitions with static metadata', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'client/pages/index.tsx');
+
+    writeFile(
+        filepath,
+        `import { definePageRoute } from '@common/router/definitions';
+
+const routePath = '/demo';
+
+export default definePageRoute({
+    path: routePath,
+    options: { auth: false },
+    data: null,
+    render: () => null,
+});
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'client', sourceFilepath: filepath });
+
+    assert.equal(definition.methodName, 'page');
+    assert.equal(definition.path, '/demo');
+    assert.equal(definition.targetResolution, 'static-expression');
+    assert.equal(definition.hasData, false);
+    assert.deepEqual(definition.normalizedOptionKeys, ['auth']);
+});
+
+test('router port override updates absolute runtime URLs', () => {
+    const root = createTempDir();
+
+    const config = withProteumEnv(
+        {
+            ENV_NAME: 'local',
+            ENV_PROFILE: 'dev',
+            PORT: '3010',
+            URL: 'http://localhost:3010',
+            URL_INTERNAL: 'http://localhost:3010',
+        },
+        () =>
+            parseProteumEnvConfig({
+                appDir: root,
+                routerPortOverride: 3100,
+            }),
+    );
+
+    assert.equal(config.router.port, 3100);
+    assert.equal(config.router.currentDomain, 'http://localhost:3100');
+    assert.equal(config.router.internalUrl, 'http://localhost:3100');
+});
+
+test('route wrapper imports explicit definitions without lifting source helpers', () => {
+    const root = createTempDir();
+    const sourceFilepath = path.join(root, 'client/pages/index.tsx');
+    const outputFilepath = path.join(root, '.proteum/client/route-modules/client/pages/index.tsx');
+
+    writeFile(
+        sourceFilepath,
+        `import { definePageRoute } from '@common/router/definitions';
+
+const helper = 'must stay in the source module';
+
+export default definePageRoute({
+    path: '/wrapped',
+    options: {},
+    data: null,
+    render: () => helper,
+});
+`,
+    );
+
+    writeGeneratedRouteModule({
+        outputFilepath,
+        runtime: 'client',
+        side: 'client',
+        sourceFilepath,
+        clientRoute: { chunkId: 'client_pages_index' },
+    });
+
+    const generated = fs.readFileSync(outputFilepath, 'utf8');
+
+    assert.match(generated, /import __routeDefinition/);
+    assert.match(generated, /registerRouteDefinition/);
+    assert.doesNotMatch(generated, /must stay in the source module/);
+    assert.doesNotMatch(generated, /const \{ Router/);
+});
+
+test('route discovery includes explicit route definitions', () => {
+    const root = createTempDir();
+    const routeFilepath = path.join(root, 'client/pages/index.tsx');
+    const helperFilepath = path.join(root, 'client/pages/helpers.tsx');
+
+    writeFile(
+        routeFilepath,
+        `import { definePageRoute } from '@common/router/definitions';
+
+export default definePageRoute({
+    path: '/',
+    options: {},
+    data: null,
+    render: () => null,
+});
+`,
+    );
+    writeFile(
+        helperFilepath,
+        `export const helper = true;
+`,
+    );
+
+    assert.deepEqual(findClientRouteFiles(path.join(root, 'client/pages')), [routeFilepath]);
+});
+
+test('route indexer rejects legacy contextual route imports and top-level router calls', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/routes/legacy.ts');
+
+    writeFile(
+        filepath,
+        `import { Router } from '@app';
+
+Router.get('/legacy', {}, async () => ({ ok: true }));
+`,
+    );
+
+    assert.throws(
+        () => indexRouteDefinitions({ side: 'server', sourceFilepath: filepath }),
+        /imports @app/,
+    );
+});
+
+test('route indexer rejects runtime metadata expressions', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'client/pages/dynamic.tsx');
+
+    writeFile(
+        filepath,
+        `import { definePageRoute } from '@common/router/definitions';
+import runtimeConfig from '../runtimeConfig';
+
+export default definePageRoute({
+    path: runtimeConfig.path,
+    options: {},
+    data: null,
+    render: () => null,
+});
+`,
+    );
+
+    assert.throws(
+        () => indexRouteDefinitions({ side: 'client', sourceFilepath: filepath }),
+        /definePageRoute path must be a serializable static literal or const-only expression/,
+    );
+});
+
+test('server route factories keep app references inside runtime registration', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/routes/api.ts');
+
+    writeFile(
+        filepath,
+        `import { defineServerRoute, defineServerRoutes } from '@common/router/definitions';
+
+const base = '/api';
+
+export default defineServerRoutes(({ Users }) => [
+    defineServerRoute({
+        method: 'GET',
+        path: base + '/users',
+        options: {},
+        handler: async () => Users.list(),
+    }),
+]);
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'server', sourceFilepath: filepath });
+
+    assert.equal(definition.methodName, 'get');
+    assert.equal(definition.path, '/api/users');
+    assert.equal(definition.targetResolution, 'static-expression');
+});
+
+test('route definitions register through explicit router registrar', () => {
+    const calls = [];
+
+    registerRouteDefinition(
+        {
+            registerRouteDefinition: (definition, metadata) => {
+                calls.push({ definition, metadata });
+            },
+        },
+        { kind: 'server', method: 'GET', path: '/ready', options: {}, handler: () => true },
+        { id: 'route-ready' },
+    );
+
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].definition.path, '/ready');
+    assert.equal(calls[0].metadata.id, 'route-ready');
+    assert.throws(
+        () =>
+            registerRouteDefinition(
+                { get: () => true },
+                { kind: 'server', method: 'GET', path: '/ready', options: {}, handler: () => true },
+            ),
+        /registerRouteDefinition/,
+    );
+});
+
+test('expressHandler preserves next-based middleware behavior', async () => {
+    const response = new EventEmitter();
+    let called = false;
+
+    const handler = expressHandler((request, _response, next, context) => {
+        assert.equal(request.url, '/health');
+        assert.equal(context.marker, 'ctx');
+        called = true;
+        next();
+    });
+
+    await handler({
+        marker: 'ctx',
+        request: {
+            req: { url: '/health' },
+            res: response,
+        },
+    });
+
+    assert.equal(called, true);
+});
+
+test('controller definitions parse input through explicit actions', () => {
+    const controller = defineController({
+        path: 'Example',
+        actions: {
+            Save: defineAction({
+                input: schema.object({ name: schema.string() }),
+                handler: ({ input }) => ({ greeting: `Hello ${input.name}` }),
+            }),
+        },
+    });
+
+    const result = runControllerAction(controller.actions.Save, {
+        app: {},
+        request: { data: { name: 'Proteum' } },
+    });
+
+    assert.deepEqual(result, { greeting: 'Hello Proteum' });
+});
+
+test('service model accessor prefers explicit Models service without recursing through inherited app getter', () => {
+    class ModelConsumer extends Service {}
+
+    const app = Object.create(Service.prototype);
+    app.app = app;
+    app.Models = { client: { model: true } };
+
+    const service = new ModelConsumer(app, {}, app);
+
+    assert.deepEqual(service.models, { model: true });
+});
+
+test('controller action context reads Models service without recursing through inherited app getter', () => {
+    const app = Object.create(Service.prototype);
+    app.app = app;
+    app.Models = { client: { model: true } };
+
+    const controller = defineController({
+        path: 'Example',
+        actions: {
+            ReadModels: defineAction({
+                handler: ({ models }) => models,
+            }),
+        },
+    });
+
+    const result = runControllerAction(controller.actions.ReadModels, {
+        app,
+        request: { data: {} },
+    });
+
+    assert.deepEqual(result, { model: true });
+});
+
+test('controller indexer rejects legacy controller classes', () => {
+    const root = createTempDir();
+    const controllersRoot = path.join(root, 'server/controllers');
+    const filepath = path.join(controllersRoot, 'Legacy.ts');
+
+    writeFile(
+        filepath,
+        `import Controller from '@server/app/controller';
+
+export default class Legacy extends Controller {
+    public Test() {
+        return true;
+    }
+}
+`,
+    );
+
+    assert.throws(
+        () => indexControllers([{ importPrefix: '@/server/controllers/', root: controllersRoot }]),
+        /legacy controller class/,
+    );
+});
+
+test('service artifact parser reads defineApplication router factories', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/index.ts');
+    const { parseAppBootstrapSource } = loadServiceArtifactsForAppRoot(root);
+
+    writeFile(
+        filepath,
+        `import { defineApplication } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+
+export default defineApplication({
+    router: (app) => new Router(
+        app,
+        {
+            plugins: {
+                schema: new SchemaRouter({}, app),
+            },
+        },
+        app,
+    ),
+});
+`,
+    );
+
+    const bootstrap = parseAppBootstrapSource(filepath);
+
+    assert.deepEqual(bootstrap.rootServices.map((service) => service.registeredName), ['Router']);
+    assert.deepEqual(bootstrap.routerPlugins.map((service) => service.registeredName), ['schema']);
+});
+
+test('service artifact parser reads named defineApplication router factories', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/index.ts');
+    const { parseAppBootstrapSource } = loadServiceArtifactsForAppRoot(root);
+
+    writeFile(
+        filepath,
+        `import { defineApplication } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+
+const createRouter = (app) => new Router(
+    app,
+    {
+        plugins: {
+            schema: new SchemaRouter({}, app),
+        },
+    },
+    app,
+);
+
+const App = defineApplication({
+    router: createRouter,
+});
+
+export default App;
+`,
+    );
+
+    const bootstrap = parseAppBootstrapSource(filepath);
+
+    assert.deepEqual(bootstrap.rootServices.map((service) => service.registeredName), ['Router']);
+    assert.deepEqual(bootstrap.routerPlugins.map((service) => service.registeredName), ['schema']);
+});