proteum 2.4.4 → 2.5.0

package/docs/agent-routing.md

@@ -68,7 +68,7 @@ proteum mcp
 
 The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
 
-If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's next action from the app root, not from the monorepo wrapper. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
+If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's next action from the app root, not from the monorepo wrapper. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
 
 Prefer CLI over MCP when the result must be reproducible as a shell command, part of verification, or copied into CI/debug instructions.
 
@@ -93,9 +93,12 @@ The router standard is trigger -> canonical instruction file, not trigger -> cop
 
 Standard triggered reads:
 
+- Worktree Preflight (`cwd` inside `/.codex/worktrees/`, newly created Proteum worktree, or before editing in a Codex worktree): root contract fallback, then `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command, `npx proteum runtime status`, and tracked `npx proteum dev` for runtime-visible work.
 - Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): root contract fallback.
-- Before finishing production code changes: root contract fallback, `CODING_STYLE.md`, and touched area `AGENTS.md`.
+- Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change: `DOCUMENTATION.md`.
+- Before finishing production code changes: root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, and touched area `AGENTS.md`.
 - Runtime-visible, request-time, router, SSR, browser, or controller behavior: root contract fallback plus `diagnostics.md`.
+- Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: `DOCUMENTATION.md`.
 - Non-trivial feature, product, business-rule, UX, copy, or docs changes: `DOCUMENTATION.md`.
 - Implementation edits: `CODING_STYLE.md` plus the matching area file from the routing table.
 

package/docs/diagnostics.md

@@ -112,6 +112,8 @@ Default compact command output follows this shape:
 
 `proteum runtime status` emits the current app manifest summary, tracked dev sessions, selected live session, MCP URL, health status, configured router/HMR port inspection, and a suggested next command. Use it before starting another dev server, and use its Start Dev command instead of probing page bodies when the default port is occupied. If it reports that the same app already responds on the configured port without a live tracked session, use or repair that runtime instead of starting a second server.
 
+Inside `/.codex/worktrees/`, `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` require a fresh `.proteum/worktree-bootstrap.json`. If the marker is missing, run `npx proteum worktree init --source <source-app-root>`. If hashes, `.env`, `.proteum/manifest.json`, `node_modules`, or the Proteum version are stale, run the returned `npx proteum worktree init --source <source-app-root> --refresh` command. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor diagnostics, and MCP output.
+
 During `proteum dev`, `/__proteum/mcp` exposes compact `workflow_start`, `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each repeated read. `proteum dev` also ensures one managed machine `proteum mcp` daemon is running. Through the machine router, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, follow the selected app root's port-inspected next action when needed, then pass the selected live `projectId` to follow-up app-bound tools.
 
 MCP tool/resource output follows compact single-line `proteum-mcp-v1` JSON:

package/docs/mcp.md

@@ -49,6 +49,8 @@ Example tool calls:
 
 `workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
 
+When the selected app root is inside `/.codex/worktrees/`, `workflow_start` first checks `.proteum/worktree-bootstrap.json`. If the marker is missing or stale, it returns `ok: false` with a single next action such as `npx proteum worktree init --source <source-app-root>` or the same command with `--refresh`. The router does not forward to the app MCP endpoint until bootstrap is complete, unless `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` is set; bypasses remain visible in MCP, `runtime status`, and `doctor`.
+
 ## Dev Runtime Endpoint
 
 During `proteum dev`, the app exposes the same app-level MCP contract through the official streamable HTTP transport:
@@ -76,9 +78,10 @@ If machine MCP routing fails:
 
 1. Run `proteum mcp status`.
 2. Run `proteum runtime status` from the intended app root. If you are in a monorepo wrapper, use the returned app candidates and exact next action instead of starting dev from the wrapper.
-3. If no live app session exists, use the exact Start Dev next action returned by runtime status. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
-4. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
-5. Retry MCP `workflow_start` and use the returned `projectId`.
+3. If the app root is inside `/.codex/worktrees/` and runtime status or workflow start reports missing/stale bootstrap, run `proteum worktree init --source <source-app-root>` or the returned `--refresh` command first.
+4. If no live app session exists, use the exact Start Dev next action returned by runtime status. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
+5. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
+6. Retry MCP `workflow_start` and use the returned `projectId`.
 
 Offline `project_resolve` and `workflow_start` candidates also inspect configured router/HMR ports before returning `nextAction`. If the configured port already serves the same app but no live machine project is registered, the next action is runtime tracking repair, not starting a second dev server.
 

package/eslint.js

@@ -139,6 +139,8 @@ const preservingMemberNames = new Set(['captureException', 'error', 'handleError
 const isPreservingCall = (callExpression, names) => {
     const propertyName = getCalleePropertyName(callExpression.callee);
     if (!propertyName) return false;
+    if (callExpression.callee.type === 'MemberExpression' && callExpression.callee.object?.name === 'console')
+        return false;
 
     const isKnownPreserver =
         preservingCallNames.has(propertyName) ||
@@ -170,7 +172,7 @@ const directPromiseCatchHandlers = new Set([
 const isDirectPromiseCatchHandler = (node) => {
     const name = getCalleePropertyName(node);
     if (name && directPromiseCatchHandlers.has(name)) return true;
-    return node?.type === 'MemberExpression' && node.object?.type === 'Identifier' && node.object.name === 'console';
+    return false;
 };
 
 const createSwallowedErrorRule = () => ({
@@ -228,6 +230,37 @@ const createSwallowedErrorRule = () => ({
     },
 });
 
+const createNoAppImportRule = () => ({
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow Proteum contextual @app imports in user code.',
+        },
+        messages: {
+            noAppImport:
+                '`@app` is not a real runtime module. Receive app services through typed route/controller callback context instead.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            ImportDeclaration(node) {
+                if (node.source?.value === '@app') context.report({ node, messageId: 'noAppImport' });
+            },
+            CallExpression(node) {
+                if (
+                    node.callee?.type === 'Identifier' &&
+                    node.callee.name === 'require' &&
+                    node.arguments?.[0]?.type === 'Literal' &&
+                    node.arguments[0].value === '@app'
+                ) {
+                    context.report({ node, messageId: 'noAppImport' });
+                }
+            },
+        };
+    },
+});
+
 const createProteumEslintConfig = ({ ignores = [] } = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
@@ -253,6 +286,7 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
             '@typescript-eslint': tseslint.plugin,
             proteum: {
                 rules: {
+                    'no-app-import': createNoAppImportRule(),
                     'no-swallowed-caught-error': createSwallowedErrorRule(),
                 },
             },
@@ -262,6 +296,7 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
         },
         rules: {
             '@typescript-eslint/no-explicit-any': 'error',
+            'proteum/no-app-import': 'error',
             'proteum/no-swallowed-caught-error': 'error',
             'no-restricted-syntax': [
                 'error',

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.4.4",
+	"version": "2.5.0",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/app/commands.ts

@@ -44,7 +44,11 @@ export abstract class Commands<TApplication extends TCommandApplication = TComma
     }
 
     public get models(): object {
-        const models = this.app.models?.client ?? this.app.Models?.client;
+        const appRecord = this.app as unknown as Record<string, unknown>;
+        const explicitModels = Object.prototype.hasOwnProperty.call(appRecord, 'models')
+            ? (appRecord.models as { client?: object } | undefined)
+            : undefined;
+        const models = explicitModels?.client ?? this.app.Models?.client;
 
         if (!models)
             throw new Error(`${this.constructor.name} tried to access models but no Models service is registered.`);

package/server/app/container/console/index.ts

@@ -539,7 +539,7 @@ Logs: ${
     public jsonToHTML(json: unknown): string {
         if (!json) return 'No data';
 
-        const coloredJson = highlight(stringify(json, null, 4), { language: 'json', ignoreIllegals: true });
+        const coloredJson = highlight(stringify(json, undefined, 4), { language: 'json', ignoreIllegals: true });
 
         const html = ansi2Html.toHtml(coloredJson);
 

package/server/app/controller/index.ts

@@ -5,8 +5,6 @@
 // Npm
 import zod from 'zod';
 
-// Core
-import context from '@server/context';
 import {
     toValidationSchema,
     type TValidationSchema,
@@ -63,11 +61,6 @@ export type TControllerRequestContext<
 } & (TRouter extends TAnyRouter ? TRouterContextServices<TControllerRouter<TRouter>> : {}) &
     TRequestServices;
 
-type TControllerBaseContext<TApplication extends object> = {
-    app: TApplication;
-    request: { data: TObjetDonnees };
-};
-
 type TControllerDefaultContext<TApplication extends object, TRequestServices extends object> = {
     app: TApplication;
     context: object;
@@ -80,43 +73,108 @@ type TControllerDefaultContext<TApplication extends object, TRequestServices ext
 } & TRouterContextServices<TControllerApplicationRouter<TApplication>> &
     TRequestServices;
 
-/*----------------------------------
-- CLASS
-----------------------------------*/
-
-export default abstract class Controller<
+export type TControllerActionContext<
+    TInput = undefined,
     TApplication extends object = object,
-    TRouter extends object = object,
     TRequestServices extends object = {},
-    TContext extends TControllerBaseContext<TApplication> = TControllerDefaultContext<TApplication, TRequestServices>,
-> {
-    public constructor(public request: TContext) {}
-
-    public get app(): TApplication {
-        return this.request.app as TApplication;
-    }
-
-    public get services(): TApplication {
-        return this.app;
-    }
-
-    public get models(): TControllerModelsClient<TApplication> {
-        const app = this.app as {
-            models?: { client?: TControllerModelsClient<TApplication> };
-            Models?: { client?: TControllerModelsClient<TApplication> };
-        };
-        return (app.models?.client ?? app.Models?.client) as TControllerModelsClient<TApplication>;
-    }
+> = TControllerDefaultContext<TApplication, TRequestServices> & {
+    input: TInput;
+    models: TControllerModelsClient<TApplication>;
+    services: TApplication;
+};
 
-    public input<TSchema extends TValidationSchema>(schema: TSchema): zod.output<TSchema>;
-    public input<TShape extends TValidationShape>(schema: TShape): zod.output<zod.ZodObject<TShape>>;
-    public input(schema: TValidationSchema | TValidationShape) {
-        const store = context.getStore() as { inputSchemaUsed?: boolean } | undefined;
+export type TControllerActionDefinition<
+    TInput = undefined,
+    TResult = unknown,
+    TApplication extends object = object,
+    TRequestServices extends object = {},
+> = {
+    input?: TValidationSchema | TValidationShape;
+    handler: (context: TControllerActionContext<TInput, TApplication, TRequestServices>) => TResult;
+};
 
-        if (store?.inputSchemaUsed) throw new Error('Controller.input() can only be called once per request handler.');
+export type TControllerDefinition<
+    TActions extends Record<string, TControllerActionDefinition<any, any, any, any>>,
+> = {
+    kind: 'controller';
+    path?: string;
+    actions: TActions;
+};
 
-        if (store) store.inputSchemaUsed = true;
+export type TControllerActionInput<TController, TMethod extends keyof any> = TController extends { actions: infer TActions }
+    ? TMethod extends keyof TActions
+        ? TActions[TMethod] extends TControllerActionDefinition<infer TInput, any, any, any>
+            ? TInput
+            : never
+        : never
+    : never;
 
-        return toValidationSchema(schema).parse(this.request.request.data);
-    }
+export type TControllerActionResult<TController, TMethod extends keyof any> = TController extends {
+    actions: infer TActions;
+}
+    ? TMethod extends keyof TActions
+        ? TActions[TMethod] extends TControllerActionDefinition<any, infer TResult, any, any>
+            ? Awaited<TResult>
+            : never
+        : never
+    : never;
+
+export function defineAction<TSchema extends TValidationSchema, TResult>(
+    definition: {
+        input: TSchema;
+        handler: (context: TControllerActionContext<zod.output<TSchema>>) => TResult;
+    },
+): TControllerActionDefinition<zod.output<TSchema>, TResult>;
+export function defineAction<TShape extends TValidationShape, TResult>(
+    definition: {
+        input: TShape;
+        handler: (context: TControllerActionContext<zod.output<zod.ZodObject<TShape>>>) => TResult;
+    },
+): TControllerActionDefinition<zod.output<zod.ZodObject<TShape>>, TResult>;
+export function defineAction<TResult>(
+    definition: {
+        handler: (context: TControllerActionContext<undefined>) => TResult;
+    },
+): TControllerActionDefinition<undefined, TResult>;
+export function defineAction(definition: {
+    input?: TValidationSchema | TValidationShape;
+    handler: (context: TControllerActionContext<any>) => unknown;
+}) {
+    return definition;
 }
+
+export const defineController = <
+    TActions extends Record<string, TControllerActionDefinition<any, any, any, any>>,
+>({
+    path,
+    actions,
+}: {
+    path?: string;
+    actions: TActions;
+}): TControllerDefinition<TActions> => ({
+    kind: 'controller',
+    path,
+    actions,
+});
+
+export const runControllerAction = (
+    action: TControllerActionDefinition<any, any, any, any>,
+    requestContext: TControllerDefaultContext<any, any>,
+) => {
+    const input = action.input === undefined ? undefined : toValidationSchema(action.input).parse(requestContext.request.data);
+    const app = requestContext.app as {
+        models?: { client?: object };
+        Models?: { client?: object };
+    };
+    const appRecord = app as Record<string, unknown>;
+    const explicitModels = Object.prototype.hasOwnProperty.call(appRecord, 'models')
+        ? (appRecord.models as { client?: object } | undefined)
+        : undefined;
+
+    return action.handler({
+        ...requestContext,
+        input,
+        models: explicitModels?.client ?? app.Models?.client ?? {},
+        services: requestContext.app,
+    });
+};

package/server/app/index.ts

@@ -40,6 +40,33 @@ export type TApplicationStartOptions = {
 
 export const Service = ServicesContainer;
 
+type TApplicationDefinitionValue<TValue, TApplication extends object> =
+    | TValue
+    | ((app: TApplication) => TValue);
+
+type TDefinedApplicationContext<
+    TServices extends Record<string, unknown>,
+    TRouter,
+    TModels = unknown,
+> = Application &
+    TServices & {
+        Router: TRouter;
+        models?: TModels;
+        Models?: TModels;
+    };
+
+export type TApplicationDefinition<
+    TServices extends Record<string, unknown> = {},
+    TRouter = unknown,
+    TModels = unknown,
+    TCommands = unknown,
+> = {
+    services?: TApplicationDefinitionValue<TServices, TDefinedApplicationContext<TServices, TRouter>>;
+    router?: TApplicationDefinitionValue<TRouter, TDefinedApplicationContext<TServices, TRouter>>;
+    models?: TApplicationDefinitionValue<TModels, TDefinedApplicationContext<TServices, TRouter>>;
+    commands?: TApplicationDefinitionValue<TCommands, TDefinedApplicationContext<TServices, TRouter, TModels>>;
+};
+
 // Without prettify, we don't get a clear list of the class properties
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
@@ -78,7 +105,7 @@ export abstract class Application<
     public app!: this;
     public servicesContainer!: TServicesContainer;
     public userType!: TUser;
-    public declare Router: object;
+    public declare Router: unknown;
 
     /*----------------------------------
     - PROPERTIES
@@ -268,4 +295,68 @@ export abstract class Application<
     }
 }
 
+const resolveApplicationDefinitionValue = <TValue, TApplication extends object>(
+    value: TApplicationDefinitionValue<TValue, TApplication> | undefined,
+    app: TApplication,
+): TValue | undefined => (typeof value === 'function' ? (value as (app: TApplication) => TValue)(app) : value);
+
+const assignApplicationRecord = (target: object, value: unknown) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return;
+
+    Object.assign(target, value);
+};
+
+export const defineApplication = <
+    TServices extends Record<string, unknown> = {},
+    TRouter = unknown,
+    TModels = unknown,
+    TCommands = unknown,
+>(
+    definition: TApplicationDefinition<TServices, TRouter, TModels, TCommands>,
+) => {
+    type TDefinedApplication = Application &
+        TServices & {
+            Router: TRouter;
+            models?: TModels;
+            Models?: TModels;
+            commands?: TCommands;
+        };
+
+    class DefinedApplication extends Application {
+        public constructor() {
+            super();
+
+            const self = this as unknown as TDefinedApplication & Record<string, unknown>;
+            const services = resolveApplicationDefinitionValue(
+                definition.services,
+                self as TDefinedApplicationContext<TServices, TRouter>,
+            );
+            assignApplicationRecord(self, services);
+
+            const router = resolveApplicationDefinitionValue(
+                definition.router,
+                self as TDefinedApplicationContext<TServices, TRouter>,
+            );
+            if (router !== undefined) (self as Record<string, unknown>).Router = router;
+
+            const models = resolveApplicationDefinitionValue(
+                definition.models,
+                self as TDefinedApplicationContext<TServices, TRouter>,
+            );
+            if (models !== undefined) {
+                (self as Record<string, unknown>).models = models;
+                (self as Record<string, unknown>).Models = models;
+            }
+
+            const commands = resolveApplicationDefinitionValue(
+                definition.commands,
+                self as TDefinedApplicationContext<TServices, TRouter, TModels>,
+            );
+            if (commands !== undefined) (self as Record<string, unknown>).commands = commands;
+        }
+    }
+
+    return DefinedApplication as unknown as new () => TDefinedApplication;
+};
+
 export default Application;

package/server/app/service/index.ts

@@ -145,7 +145,11 @@ export default abstract class Service<
             models?: { client?: TServiceModelsClient<TApplication> };
             Models?: { client?: TServiceModelsClient<TApplication> };
         };
-        const models = app.models?.client ?? app.Models?.client;
+        const appRecord = app as Record<string, unknown>;
+        const explicitModels = Object.prototype.hasOwnProperty.call(appRecord, 'models')
+            ? (appRecord.models as { client?: TServiceModelsClient<TApplication> } | undefined)
+            : undefined;
+        const models = explicitModels?.client ?? app.Models?.client;
 
         if (!models)
             throw new Error(`${this.constructor.name} tried to access models but no Models service is registered.`);

package/server/index.ts

@@ -3,6 +3,10 @@ import Application from '@/server/index';
 import { isServerHotReloadRequest, serverHotReloadMessageType } from '@common/dev/serverHotReload';
 
 const application = AppContainer.start(Application);
+const router = application.Router as {
+    started?: Promise<unknown>;
+    reloadGeneratedDefinitions?: (changedFiles: string[]) => Promise<unknown>;
+};
 let shutdownPromise: Promise<void> | undefined;
 
 const shutdownApplication = async (reason: string) => {
@@ -36,8 +40,8 @@ if (__DEV__ && typeof process.send === 'function') {
 
         void (async () => {
             try {
-                await application.Router?.started;
-                await application.Router.reloadGeneratedDefinitions(message.changedFiles);
+                await router.started;
+                await router.reloadGeneratedDefinitions?.(message.changedFiles);
 
                 process.send?.({ type: serverHotReloadMessageType.succeeded, changedFiles: message.changedFiles });
             } catch (error) {

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;