proteum 2.4.3 → 2.5.0

package/server/services/router/index.ts

@@ -14,12 +14,12 @@ const { v4: uuid } = require('uuid') as { v4: () => string };
 import got from 'got';
 import hInterval from 'human-interval';
 import type express from 'express';
-import type { Request, Response, NextFunction } from 'express';
 import zod, { ZodError } from 'zod';
 export { default as schema } from 'zod';
 
 // Core
 import type { Application } from '@server/app/index';
+import { runControllerAction, type TControllerActionDefinition } from '@server/app/controller';
 import Service, { TServiceArgs } from '@server/app/service';
 import context from '@server/context';
 import type DisksManager from '@server/services/disks';
@@ -30,9 +30,12 @@ import BaseRouter, {
     TErrorRoute,
     TRouteModule,
     TRouteOptions,
+    type TRouteDefinition,
+    type TRouteMetadata,
     defaultOptions,
     matchRoute,
     buildUrl,
+    withRouteMetadata,
 } from '@common/router';
 import type { TSsrUnresolvedRoute, TRegisterPageArgs } from '@common/router/contracts';
 import { buildRegex, getRegisterPageArgs } from '@common/router/register';
@@ -76,7 +79,7 @@ type TGeneratedControllerDefinition = {
     path: string;
     filepath: string;
     sourceLocation: { line: number; column: number };
-    Controller: new (request: TRouterContext<TServerRouter>) => { [method: string]: () => any };
+    action: TControllerActionDefinition<any, any, any, any>;
     method: string;
 };
 
@@ -385,7 +388,7 @@ export default class ServerRouter<
             }
         }
 
-        this.afterRegister();
+        this.refreshRouteRegistration();
     }
 
     private registerControllers(definitions: TGeneratedControllerDefinition[]) {
@@ -393,10 +396,8 @@ export default class ServerRouter<
             const route: TRoute<TRouterContext<this>> = {
                 method: 'POST',
                 path: definition.path,
-                controller: (requestContext: TRouterContext<this>) => {
-                    const controller = new definition.Controller(requestContext);
-                    return controller[definition.method]();
-                },
+                controller: (requestContext: TRouterContext<this>) =>
+                    runControllerAction(definition.action, requestContext as any),
                 options: { ...defaultOptions, filepath: definition.filepath, sourceLocation: definition.sourceLocation },
             };
 
@@ -419,7 +420,31 @@ export default class ServerRouter<
     - REGISTER
     ----------------------------------*/
 
-    public page(...args: TRegisterPageArgs<any, TRouteOptions>) {
+    public registerRouteDefinition(definition: TRouteDefinition, metadata: TRouteMetadata = {}) {
+        if (definition.kind === 'page') {
+            return this.page(
+                definition.path,
+                withRouteMetadata(definition.options, metadata),
+                definition.data,
+                definition.render,
+            );
+        }
+
+        if (definition.kind === 'error') {
+            return this.error(definition.code, withRouteMetadata(definition.options, metadata), definition.render);
+        }
+
+        const method = definition.method === '*' ? '*' : (definition.method.toUpperCase() as TRouteHttpMethod);
+
+        return this.registerApi(
+            method,
+            definition.path,
+            withRouteMetadata(definition.options, metadata),
+            definition.handler as TServerController<this>,
+        );
+    }
+
+    protected page(...args: TRegisterPageArgs<any, TRouteOptions>) {
         const { path, options, data, renderer, layout } = getRegisterPageArgs(...args);
 
         const { regex, keys } = buildRegex(path);
@@ -442,7 +467,7 @@ export default class ServerRouter<
         return this;
     }
 
-    public error(
+    protected error(
         code: number,
         options: Partial<TRouteOptions>,
         renderer: TFrontRenderer<{}, { message: string }>,
@@ -461,34 +486,13 @@ export default class ServerRouter<
         this.errors[code] = route;
     }
 
-    public all = (...args: TApiRegisterArgs<this>) => this.registerApi('*', ...args);
-    public options = (...args: TApiRegisterArgs<this>) => this.registerApi('OPTIONS', ...args);
-    public get = (...args: TApiRegisterArgs<this>) => this.registerApi('GET', ...args);
-    public post = (...args: TApiRegisterArgs<this>) => this.registerApi('POST', ...args);
-    public put = (...args: TApiRegisterArgs<this>) => this.registerApi('PUT', ...args);
-    public patch = (...args: TApiRegisterArgs<this>) => this.registerApi('PATCH', ...args);
-    public delete = (...args: TApiRegisterArgs<this>) => this.registerApi('DELETE', ...args);
-
-    public express(
-        middleware: (req: Request, res: Response, next: NextFunction, requestContext: TRouterContext<this>) => void,
-    ) {
-        return (context: TRouterContext<this>) =>
-            new Promise((resolve) => {
-                context.request.res.on('finish', function () {
-                    //console.log('the response has been sent', request.res.statusCode);
-                    resolve(true);
-                });
-
-                middleware(
-                    context.request.req,
-                    context.request.res,
-                    () => {
-                        resolve(true);
-                    },
-                    context,
-                );
-            });
-    }
+    protected all = (...args: TApiRegisterArgs<this>) => this.registerApi('*', ...args);
+    protected options = (...args: TApiRegisterArgs<this>) => this.registerApi('OPTIONS', ...args);
+    protected get = (...args: TApiRegisterArgs<this>) => this.registerApi('GET', ...args);
+    protected post = (...args: TApiRegisterArgs<this>) => this.registerApi('POST', ...args);
+    protected put = (...args: TApiRegisterArgs<this>) => this.registerApi('PUT', ...args);
+    protected patch = (...args: TApiRegisterArgs<this>) => this.registerApi('PATCH', ...args);
+    protected delete = (...args: TApiRegisterArgs<this>) => this.registerApi('DELETE', ...args);
 
     protected registerApi(method: TRouteHttpMethod, ...args: TApiRegisterArgs<this>): this {
         let path: string;
@@ -565,7 +569,11 @@ export default class ServerRouter<
         );
     }
 
-    private async afterRegister() {
+    public refreshRouteRegistration() {
+        this.afterRegister();
+    }
+
+    private afterRegister() {
         // Ordonne par ordre de priorité
         this.config.debug && console.info('Loading routes ...');
         this.routes.sort((r1, r2) => {
@@ -579,6 +587,7 @@ export default class ServerRouter<
             return 0;
         });
         // - Génère les définitions de route pour le client
+        this.ssrRoutes = [];
         this.config.debug && console.info(`Registered routes:`);
         for (const route of this.routes) {
             const chunkId = route.options.id;

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');