proteum 2.4.4 → 2.5.1

package/common/router/pageData.ts

@@ -46,7 +46,7 @@ const formatRouteSource = (route: TAnyRoute) => {
 };
 
 export const getRouteOptionKey = (key: string) => {
-    if (reservedRouteOptionKeysSet.has(key)) throw new Error(`"${key}" is a reserved Router.page option key.`);
+    if (reservedRouteOptionKeysSet.has(key)) throw new Error(`"${key}" is a reserved route option key.`);
 
     return routeOptionKeysSet.has(key) ? (key as keyof TRouteOptions) : null;
 };
@@ -54,8 +54,8 @@ export const getRouteOptionKey = (key: string) => {
 export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
     if (!result || typeof result !== 'object' || Array.isArray(result)) {
         throw new Error(
-            `Router.page data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} must return an object. ` +
-                `If the page has no data loader, pass null as the third argument.`,
+            `definePageRoute data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} must return an object. ` +
+                `If the page has no data loader, set data to null.`,
         );
     }
 
@@ -63,8 +63,8 @@ export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
         if (!reservedPageDataKeys.has(key)) continue;
 
         throw new Error(
-            `Router.page data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} cannot return reserved key "${key}". ` +
-                `Move route behavior into the explicit Router.page(path, options, data, render) options argument.`,
+            `definePageRoute data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} cannot return reserved key "${key}". ` +
+                `Move route behavior into definePageRoute({ path, options, data, render }).options.`,
         );
     }
 

package/common/router/register.ts

@@ -21,12 +21,12 @@ export const getRegisterPageArgs = (...args: TRegisterPageArgs<any, TRouteOption
     const [path, options, data, renderer] = args;
 
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
-        throw new Error(`Router.page(${JSON.stringify(path)}) requires an explicit options object as its second argument.`);
+        throw new Error(`definePageRoute(${JSON.stringify(path)}) requires an explicit options object.`);
     }
 
     if (data !== null && typeof data !== 'function') {
         throw new Error(
-            `Router.page(${JSON.stringify(path)}) requires a data function or null as its third argument.`,
+            `definePageRoute(${JSON.stringify(path)}) requires a data function or null.`,
         );
     }
 

package/common/router/request/api.ts

@@ -43,9 +43,19 @@ export type TApiFetchOptions = {
 
 export type TPostData = TPostDataWithFile;
 
-export type TPostDataWithFile = { [key: string]: PrimitiveValue };
+export type TPostDataJsonValue =
+    | PrimitiveValue
+    | null
+    | undefined
+    | Date
+    | TPostDataJsonValue[]
+    | { [key: string]: TPostDataJsonValue };
 
-export type TPostDataWithoutFile = { [key: string]: PrimitiveValue };
+export type TPostDataValue = TPostDataJsonValue | Blob | FileList;
+
+export type TPostDataWithFile = { [key: string]: TPostDataValue };
+
+export type TPostDataWithoutFile = { [key: string]: TPostDataJsonValue };
 
 export type TDataReturnedByFetchers<TProvidedData extends TFetcherList = {}> = {
     [Property in keyof TProvidedData]: ThenArg<TProvidedData[Property]>;

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/docs/migration-2.5.md

@@ -0,0 +1,226 @@
+# Migrating To Proteum 2.5
+
+Proteum 2.5 is a breaking cleanup release. It removes contextual app/router magic from user source and makes routes, controllers, pages, services, and app bootstrap machine-readable through explicit definition objects.
+
+## What Changed
+
+- App roots default-export `defineApplication({ services, router, models, commands })`.
+- Page files default-export `definePageRoute({ path, options, data, render })` or `defineErrorRoute({ code, options, render })`.
+- Manual HTTP route files default-export `defineServerRoute({ method, path, options, handler })` or `defineServerRoutes(...)`.
+- Raw Express handlers are wrapped with `expressHandler(...)`.
+- Controller files default-export `defineController({ path, actions })`; actions use `defineAction({ input, handler })`.
+- Runtime app, service, router, request, response, auth, and router-plugin access comes from typed callback context.
+- `@app` imports, top-level `Router.page(...)`, top-level server `Router.*(...)`, controller classes, and `this.input(...)` are no longer supported.
+
+## 1. Install The Published Package
+
+Update every Proteum app package in the repo to `proteum@^2.5.0`, then reinstall from npm.
+
+```bash
+npm install
+npm ls proteum
+node -p "require('./node_modules/proteum/package.json').version + ' ' + require.resolve('proteum/package.json')"
+```
+
+The resolved path must point inside the app repo `node_modules/proteum`, not to a local framework checkout. If a project was using `npm link`, the reinstall should replace the symlink.
+
+## 2. Refresh Agent Instructions
+
+Regenerate project instructions so LLMs receive the explicit 2.5 contracts.
+
+```bash
+npx proteum configure agents
+```
+
+Generated instructions should mention `defineApplication`, `definePageRoute`, `defineServerRoute`, `defineController`, and the ban on `@app` imports in route, page, and controller files.
+
+## 3. Migrate `server/index.ts`
+
+Move from an `Application` subclass or service-returned `Router` to an explicit app definition. Keep `server/index.ts` as the canonical type root for services, router plugins, models, and request context.
+
+```ts
+import { defineApplication, type Application } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+import BillingService from '@/server/services/Billing';
+
+import * as appConfig from '@/server/config/app';
+
+type ProjectServices = {
+    Billing: BillingService;
+};
+
+type ProjectRouterPlugins = {
+    schema: SchemaRouter;
+};
+
+export type ProjectRouter = Router<ProjectApp, ProjectRouterPlugins>;
+export interface ProjectApp extends Application, ProjectServices {
+    Router: ProjectRouter;
+}
+
+const createProjectRouter = (app: ProjectApp): ProjectRouter =>
+    new Router<ProjectApp, ProjectRouterPlugins>(
+        app,
+        {
+            ...appConfig.routerBaseConfig,
+            plugins: {
+                schema: new SchemaRouter({}, app),
+            },
+        },
+        app,
+    );
+
+const ProjectApplication = defineApplication<ProjectServices, ProjectRouter>({
+    services: (app) => ({
+        Billing: new BillingService(app, {}, app),
+    }),
+    router: createProjectRouter,
+});
+
+export default ProjectApplication;
+```
+
+## 4. Migrate Pages
+
+Replace legacy page registration with a default-exported page definition.
+
+```tsx
+import { definePageRoute } from '@common/router/definitions';
+
+export default definePageRoute({
+    path: '/dashboard',
+    options: { auth: true },
+    data: ({ AccountController }) => ({
+        account: AccountController.accountPage(),
+    }),
+    render: ({ account }) => <Dashboard account={account} />,
+});
+```
+
+Rules:
+
+- `path`, `options`, and error `code` must be static and compiler-readable.
+- Route behavior belongs in `options`, not in data.
+- Use `data: null` when no SSR data is needed.
+- Runtime references are allowed only inside `data` and `render`.
+
+## 5. Migrate Manual Server Routes
+
+Replace top-level `Router.get(...)`, `Router.post(...)`, `Router.express(...)`, and similar calls with definition exports.
+
+```ts
+import { defineServerRoute, defineServerRoutes, expressHandler } from '@common/router/definitions';
+import type { ProjectApp } from '@/server/index';
+
+export default defineServerRoutes((app: ProjectApp) => [
+    defineServerRoute({
+        method: 'GET',
+        path: '/health',
+        options: {},
+        handler: ({ response }) => response.json({ ok: true }),
+    }),
+    defineServerRoute({
+        method: 'POST',
+        path: '/webhook',
+        options: {},
+        handler: expressHandler((request, response) => {
+            app.Billing.recordWebhook(request.body);
+            response.status(204).send('');
+        }),
+    }),
+]);
+```
+
+Use `defineServerRoutes((app) => [...])` only when the route definitions need app services at registration time. Otherwise export one `defineServerRoute(...)`.
+
+## 6. Migrate Controllers
+
+Replace controller classes and `this.input(schema)` with explicit actions.
+
+```ts
+import { defineAction, defineController, schema } from '@server/app/controller';
+
+export default defineController({
+    path: 'Billing',
+    actions: {
+        read: defineAction({
+            input: schema.object({ accountId: schema.string() }),
+            handler: ({ input, services }) => services.Billing.read(input.accountId),
+        }),
+    },
+});
+```
+
+Rules:
+
+- `input` is parsed before the handler runs.
+- Read parsed input from `context.input`.
+- Read request state from `request`, `response`, `api`, `auth`, and router-plugin context.
+- Call business logic through `services`, `models`, or `app`.
+
+## 7. Remove Legacy Magic
+
+Search user source for old contracts and remove every match.
+
+```bash
+rg -n "from ['\"]@app['\"]|Router\\.(page|error|get|post|put|patch|delete|express)\\(|this\\.input\\(" client server common commands
+```
+
+Expected result: no user-source matches.
+
+Allowed replacements:
+
+- `ctx.app`, `ctx.services`, `ctx.Router`, `ctx.request`, `ctx.response`, `ctx.auth`, and custom router-plugin context inside handlers.
+- `this.app`, `this.services`, and `this.models` inside typed services.
+- `defineServerRoutes((app) => [...])` when server route definitions need app services.
+
+## 8. Standardize Caught Error Handling
+
+Every caught error must end at the same framework error surface. Local UI feedback or protocol responses can still happen, but they are not the terminal error handling step by themselves.
+
+Server rules:
+
+- Use `throw error` when the request/router/controller should fail and let Proteum render the HTTP error response.
+- Use `await app.reportError(error, request)` when a Proteum request is available, or `await app.reportError(error)` for detached/custom Express paths, catch-and-continue server work, and jobs that intentionally keep running.
+- Do not use raw `app.runHook('error', error, request)` in app code. `app.reportError(...)` keeps the `error` versus `error.<code>` routing centralized.
+
+Client rules:
+
+- Use `throw error` when the action should fail and reach the app-level unhandled rejection path.
+- Use `useContext().app.handleError(error)` or `context.app.handleError(error)` when the UI catches and continues.
+- `handleError` accepts unknown caught values and returns a displayable message. Prefer `setError(context.app.handleError(error, 'Unable to finish this action.'))` over local `instanceof Error` filtering.
+- If an app overrides `handleError`, update it to `handleError(error: unknown, fallbackMessage?: string): string` and return the display message.
+- Toasts, form errors, or `setError(...)` are local feedback only. Route the original caught value through `app.handleError(error)` or `throw error`.
+
+Do not treat `console.error(error)`, `console.warn(error)`, or any other `console.*(error)` call as error handling. Console calls can be temporary diagnostics, but they must not be the last stop for a caught error.
+
+## 9. Refresh Generated Artifacts
+
+Do not edit `.proteum/**` manually. Regenerate it from source.
+
+```bash
+npx proteum refresh
+npx proteum typecheck
+```
+
+If connected local projects are used through `file:` sources, start or validate producer apps before validating the consumer.
+
+## 10. Validate Runtime Behavior
+
+Run the smallest trustworthy checks first, then broaden when the touched surface requires it.
+
+```bash
+npx proteum diagnose /
+npx proteum build --prod
+npx proteum e2e
+```
+
+For protected flows, prefer Proteum session helpers over automating login unless login is the feature under test.
+
+## Common Fixes
+
+- Production route-generation errors where top-level `Router.express(...)` was lifted outside registration are fixed by moving the route into `defineServerRoute({ handler: expressHandler(...) })`.
+- `@app` import errors are fixed by moving runtime access into `data`, `render`, route handlers, controller action handlers, or typed services.
+- Missing `this.app.Router` typings are fixed by exporting the concrete app and router types from `server/index.ts`.
+- Static metadata errors are fixed by moving runtime-dependent values out of `path`, `method`, `options`, and error `code`.

package/eslint.js

@@ -121,75 +121,89 @@ const getCalleePropertyName = (callee) => {
     return null;
 };
 
-const preservingCallNames = new Set([
-    'captureError',
-    'captureException',
-    'consoleError',
-    'handleError',
-    'logError',
-    'onError',
-    'reject',
-    'reportError',
-    'setError',
-    'setErrorMessage',
-]);
-
-const preservingMemberNames = new Set(['captureException', 'error', 'handleError', 'reject', 'warn']);
-
-const isPreservingCall = (callExpression, names) => {
-    const propertyName = getCalleePropertyName(callExpression.callee);
-    if (!propertyName) return false;
-
-    const isKnownPreserver =
-        preservingCallNames.has(propertyName) ||
-        (callExpression.callee.type === 'MemberExpression' && preservingMemberNames.has(propertyName));
-
-    return isKnownPreserver && nodeReferencesName(callExpression, names);
+const getErrorHandlingSide = (filename) => {
+    const normalized = filename.replace(/\\/g, '/');
+    if (/(^|\/)client\//.test(normalized)) return 'client';
+    if (/(^|\/)(server|commands)\//.test(normalized)) return 'server';
+
+    return 'shared';
+};
+
+const getMemberPropertyName = (node) => {
+    if (node?.type !== 'MemberExpression') return null;
+    if (node.property.type === 'Identifier') return node.property.name;
+    if (node.property.type === 'Literal') return String(node.property.value);
+
+    return null;
+};
+
+const isConsoleMember = (node) =>
+    node?.type === 'MemberExpression' && node.object?.type === 'Identifier' && node.object.name === 'console';
+
+const isAppReceiver = (node) => {
+    if (!node) return false;
+    if (node.type === 'Identifier' && node.name === 'app') return true;
+    if (node.type === 'MemberExpression' && getMemberPropertyName(node) === 'app') return true;
+
+    return false;
 };
 
-const handlerPreservesCaughtError = (node, names) => {
+const isClientErrorHandlerCall = (callExpression) =>
+    callExpression.callee.type === 'MemberExpression' &&
+    getMemberPropertyName(callExpression.callee) === 'handleError' &&
+    isAppReceiver(callExpression.callee.object);
+
+const isServerErrorReporterCall = (callExpression) =>
+    callExpression.callee.type === 'MemberExpression' &&
+    getMemberPropertyName(callExpression.callee) === 'reportError' &&
+    isAppReceiver(callExpression.callee.object);
+
+const isPromiseRejectCall = (callExpression) => getCalleePropertyName(callExpression.callee) === 'reject';
+
+const isPreservingCall = (callExpression, names, side) => {
+    if (!nodeReferencesName(callExpression, names)) return false;
+    if (isConsoleMember(callExpression.callee)) return false;
+    if (isPromiseRejectCall(callExpression)) return true;
+    if (side === 'client') return isClientErrorHandlerCall(callExpression);
+    if (side === 'server') return isServerErrorReporterCall(callExpression);
+
+    return isClientErrorHandlerCall(callExpression) || isServerErrorReporterCall(callExpression);
+};
+
+const handlerPreservesCaughtError = (node, names, side) => {
     let preserves = false;
 
     traverseNode(node, (child) => {
         if (child.type === 'ThrowStatement' && nodeReferencesName(child.argument, names)) preserves = true;
-        if (child.type === 'CallExpression' && isPreservingCall(child, names)) preserves = true;
+        if (child.type === 'CallExpression' && isPreservingCall(child, names, side)) preserves = true;
     });
 
     return preserves;
 };
 
-const directPromiseCatchHandlers = new Set([
-    'captureError',
-    'captureException',
-    'consoleError',
-    'handleError',
-    'logError',
-    'reportError',
-]);
-
 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 name === 'reject';
 };
 
 const createSwallowedErrorRule = () => ({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Require caught errors to be preserved, reported, rethrown, or surfaced with original detail.',
+            description: 'Require caught errors to reach the standard app error path or be rethrown.',
         },
         messages: {
             missingParam:
-                'Caught errors must be bound and preserved. Use `catch (error)` and rethrow, report, route, or surface original details.',
+                'Caught errors must be bound and routed through the standard error path. Use `catch (error)` and rethrow, call app.reportError on the server, or call app.handleError on the client.',
             unusedParam:
-                'Caught error `{{name}}` is discarded. Rethrow it, report it, route it to app error handling, or surface its original details.',
+                'Caught error `{{name}}` is discarded. Rethrow it, call app.reportError on the server, or call app.handleError on the client.',
             unpreserved:
-                'Caught error `{{name}}` is used but not preserved. Rethrow it, report it, route it, or surface original error details.',
+                'Caught error `{{name}}` is used but not routed through the standard error path. Rethrow it, call app.reportError on the server, or call app.handleError on the client.',
         },
         schema: [],
     },
     create(context) {
+        const side = getErrorHandlingSide(context.filename || context.getFilename?.() || '');
         const reportHandler = (node, params, body) => {
             const names = params.flatMap((param) => collectPatternNames(param));
             if (names.length === 0) {
@@ -203,7 +217,7 @@ const createSwallowedErrorRule = () => ({
                 return;
             }
 
-            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names))) {
+            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side)) {
                 context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
             }
         };
@@ -228,6 +242,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 +298,7 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
             '@typescript-eslint': tseslint.plugin,
             proteum: {
                 rules: {
+                    'no-app-import': createNoAppImportRule(),
                     'no-swallowed-caught-error': createSwallowedErrorRule(),
                 },
             },
@@ -262,6 +308,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.1",
 	"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);