proteum 2.5.0 → 2.5.1

package/README.md

@@ -140,7 +140,7 @@ Use this for linked or workspace-local TypeScript packages that ship source file
 
 ## Example: Server Bootstrap
 
-Proteum app services are declared explicitly through typed config exports plus a concrete `Application` subclass.
+Proteum app services and router plugins are declared explicitly through typed config exports plus a default-exported `defineApplication(...)` definition object.
 
 ```ts
 // server/config/user.ts
@@ -167,27 +167,45 @@ export const routerBaseConfig = {
 
 ```ts
 // server/index.ts
-import { defineApplication } from '@server/app';
+import { defineApplication, type Application } from '@server/app';
 import Router from '@server/services/router';
 import SchemaRouter from '@server/services/schema/router';
 import Users from '@/server/services/Users';
 import * as userConfig from '@/server/config/user';
 
-export default defineApplication({
+type MyAppServices = {
+  Users: Users;
+};
+
+type MyRouterPlugins = {
+  schema: SchemaRouter;
+};
+
+export type MyRouter = Router<MyApp, MyRouterPlugins>;
+export interface MyApp extends Application, MyAppServices {
+  Router: MyRouter;
+}
+
+const createRouter = (app: MyApp): MyRouter =>
+  new Router<MyApp, MyRouterPlugins>(
+    app,
+    {
+      ...userConfig.routerBaseConfig,
+      plugins: {
+        schema: new SchemaRouter({}, app),
+      },
+    },
+    app
+  );
+
+const MyApplication = defineApplication<MyAppServices, MyRouter>({
   services: (app) => ({
     Users: new Users(app, userConfig.usersConfig, app),
-    Router: new Router(
-      app,
-      {
-        ...userConfig.routerBaseConfig,
-        plugins: {
-          schema: new SchemaRouter({}, app),
-        },
-      },
-      app
-    ),
   }),
+  router: createRouter,
 });
+
+export default MyApplication;
 ```
 
 Proteum reads `server/index.ts` as the source of truth for installed root services and router plugins, and reads `server/config/*.ts` `Services.config(...)` exports for typed config such as service priority overrides.
@@ -233,7 +251,7 @@ Default public asset validators depend on the environment: dev disables `ETag` a
 Proteum pages are explicit SSR entrypoints.
 
 ```tsx
-import { definePageRoute } from '@common/router';
+import { definePageRoute } from '@common/router/definitions';
 
 export default definePageRoute({
   path: '/',
@@ -653,6 +671,12 @@ npx proteum check
 npx proteum build --prod
 ```
 
+## Migrating To 2.5
+
+Proteum 2.5 removes the old contextual route/controller magic. Apps migrate by replacing ambient `@app` imports, top-level `Router.*(...)` route calls, controller classes, and `Application` subclasses with explicit definition objects and typed runtime callback parameters.
+
+Use [the 2.5 migration guide](docs/migration-2.5.md) for the full checklist.
+
 ## Repository Structure
 
 This repository is organized around the same explicit framework surface it exposes:
@@ -661,7 +685,7 @@ This repository is organized around the same explicit framework surface it expos
 - `client/`: client runtime, page registration, islands, and router behavior
 - `server/`: controller base classes, services, runtime, and SSR server behavior
 - `common/`: shared router contracts, models, request/response types, and utilities
-- `doc/`: focused design notes and internal documentation
+- `docs/`: focused design notes and internal documentation
 - `agents/`: agent-specific conventions and scaffolding used in Proteum-based projects
 
 ## Status

package/agents/project/client/AGENTS.md

@@ -25,7 +25,11 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Never depend on legacy `@app` imports on the client.
 - Errors from controller calls should never be silently swallowed. Rethrow or surface them clearly.
 - Caught frontend errors must always preserve the original failure. Never write `catch {}`, `.catch(() => ...)`, or a catch handler that only shows a generic toast/state without using the caught error.
-- Valid frontend error handling includes rethrowing the error, passing it to `useContext().app.handleError(error)` or `context.app.handleError(error)`, logging/reporting it with the original error, or surfacing original detail such as `error.message` in user-visible feedback.
+- Valid terminal frontend error handling is `throw error`, `useContext().app.handleError(error)`, or `context.app.handleError(error)`.
+- Do not normalize caught values in app code before calling `handleError`; the app handles `unknown` values and returns a displayable message.
+- If the app customizes `handleError`, keep the signature `handleError(error: unknown, fallbackMessage?: string): string`.
+- Toasts and form errors are local feedback only; use `setError(context.app.handleError(error, fallbackMessage))` or rethrow the caught error.
+- `console.*(error)` is not error handling and must not be the last stop for a caught error.
 
 ## Design
 

package/agents/project/server/services/AGENTS.md

@@ -38,3 +38,7 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 
 - Never silence caught errors.
 - If you need to wrap a failure, preserve enough detail and the original error.
+- Prefer `throw error` when the current request or job should fail.
+- For catch-and-continue server work, detached promises, custom Express responses, or background jobs, call `await this.app.reportError(error, request)` when a request is available, or `await this.app.reportError(error)` without one.
+- Do not call `app.runHook('error', ...)` directly from app code; route caught errors through `app.reportError(...)` so HTTP-specific error hooks stay centralized.
+- `console.*(error)` is not error handling and must not be the last stop for a caught error.

package/cli/scaffold/templates.ts

@@ -172,8 +172,9 @@ import SchemaRouter from '@server/services/schema/router';
 import * as appConfig from '@/server/config/app';
 
 export default defineApplication({
-    services: (app) => ({
-        Router: new Router(
+    services: () => ({}),
+    router: (app) =>
+        new Router(
             app,
             {
                 ...appConfig.routerBaseConfig,
@@ -183,7 +184,6 @@ export default defineApplication({
             },
             app,
         ),
-    }),
 });
 `;
 

package/client/app/index.ts

@@ -7,8 +7,6 @@ if (typeof window === 'undefined') throw new Error(`This file shouldn't be loade
 
 window.dev && require('preact/debug');
 
-// Core
-import { CoreError } from '@common/errors';
 import type { Layout } from '@common/router';
 import { createDialog } from '@client/components/Dialog/Manager';
 
@@ -53,6 +51,21 @@ const isIgnorableBrowserErrorMessage = (message: string) =>
     message === 'ResizeObserver loop completed with undelivered notifications.' ||
     message === 'ResizeObserver loop limit exceeded';
 
+export const getClientErrorMessage = (error: unknown, fallbackMessage = 'Unknown client error'): string => {
+    if (error instanceof Error && error.message) return error.message;
+    if (typeof error === 'string' && error.trim()) return error;
+    if (error && typeof error === 'object' && 'message' in error && typeof error.message === 'string' && error.message)
+        return error.message;
+
+    return fallbackMessage;
+};
+
+export const normalizeClientError = (error: unknown, fallbackMessage?: string): Error => {
+    if (error instanceof Error) return error;
+
+    return new Error(getClientErrorMessage(error, fallbackMessage));
+};
+
 /*----------------------------------
 - CLASS
 ----------------------------------*/
@@ -88,8 +101,7 @@ export default abstract class Application {
     public bindErrorHandlers() {
         // Impossible de recup le stacktrace ...
         window.addEventListener('unhandledrejection', (e) => {
-            const error = new Error(e.reason); // How to get stacktrace ?
-            this.handleError(error);
+            this.handleError(e.reason);
         });
 
         window.onerror = (message, file, line, col, stacktrace) => {
@@ -109,7 +121,12 @@ export default abstract class Application {
         };
     }
 
-    public abstract handleError(error: CoreError | Error): void;
+    public handleError(error: unknown, fallbackMessage?: string): string {
+        const normalizedError = normalizeClientError(error, fallbackMessage);
+        console.error(normalizedError);
+
+        return getClientErrorMessage(error, fallbackMessage);
+    }
 
     public abstract handleUpdate(): void;
 

package/client/services/router/request/api.ts

@@ -109,7 +109,7 @@ export default class ApiClient implements ApiClientService {
             .then((data: TObjetDonnees) => {
                 this.set(data);
             })
-            .catch((error: Error) => {
+            .catch((error: unknown) => {
                 this.app.handleError(error);
             });
     }
@@ -270,7 +270,7 @@ export default class ApiClient implements ApiClientService {
                           );
 
                           // API Error hook
-                          this.app.handleError(e as Error);
+                          this.app.handleError(e);
 
                           throw e;
                       }

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,77 +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;
-    if (callExpression.callee.type === 'MemberExpression' && callExpression.callee.object?.name === 'console')
-        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 false;
+    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) {
@@ -205,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 } });
             }
         };

package/package.json

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

package/server/app/index.ts

@@ -92,6 +92,24 @@ const createCommandsManager = (app: Application) => new CommandsManager(app, { d
 const createDevCommandsRegistry = (app: Application) => new DevCommandsRegistry(app);
 const createDevDiagnosticsRegistry = (app: Application) => new DevDiagnosticsRegistry(app);
 
+const normalizeReportedError = (rejection: unknown, fallbackMessage: string): Error => {
+    if (rejection instanceof Error) return rejection;
+    if (typeof rejection === 'string') return new Error(rejection);
+
+    return new Error(fallbackMessage);
+};
+
+const getNumericErrorProperty = (error: Error, property: 'http' | 'status' | 'statusCode') => {
+    const value = (error as Error & Partial<Record<typeof property, unknown>>)[property];
+    return typeof value === 'number' ? value : undefined;
+};
+
+const getErrorHttpCode = (error: Error) =>
+    getNumericErrorProperty(error, 'http') ??
+    getNumericErrorProperty(error, 'status') ??
+    getNumericErrorProperty(error, 'statusCode') ??
+    500;
+
 /*----------------------------------
 - FUNCTIONS
 ----------------------------------*/
@@ -138,12 +156,12 @@ export abstract class Application<
         // Handle unhandled crash
         this.on('error', (e, request) => this.container.handleBug(e, 'An error occured in the application', request));
 
-        process.on('unhandledRejection', (error: any, _promise: any) => {
+        process.on('unhandledRejection', (error: unknown) => {
             // Log so we know it's coming from unhandledRejection
             console.error('unhandledRejection', error);
 
             // We don't log the error here because it's the role of the app to decidehiw to log errors
-            this.runHook('error', error);
+            void this.reportError(error);
         });
 
         // We can't pass this in super so we assign here
@@ -155,6 +173,14 @@ export abstract class Application<
         return this.container.Console.createBugReport(new Anomaly(...anomalyArgs));
     }
 
+    public async reportError(rejection: unknown, request?: ServerRequest<TServerRouter>) {
+        const error = normalizeReportedError(rejection, 'Unknown application error');
+        const code = getErrorHttpCode(error);
+
+        if (code === 500) await this.runHook('error', error, request);
+        else await this.runHook('error.' + code, error, request);
+    }
+
     /*----------------------------------
     - COMMANDS
     ----------------------------------*/

package/server/services/router/index.ts

@@ -637,7 +637,7 @@ export default class ServerRouter<
                 error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown request.finished hook error');
 
             try {
-                await this.app.runHook('error', typedError, request);
+                await this.app.reportError(typedError, request);
             } catch (hookError) {
                 console.error('request.finished hook error', typedError, 'Error hook failure', hookError);
             }
@@ -1111,7 +1111,7 @@ export default class ServerRouter<
             console.log(LogPrefix, 'Error catched from the router:', error);
 
             // Report error
-            await this.app.runHook('error', error, request);
+            await this.app.reportError(error, request);
 
             // Don't exose technical errors to users
             if (this.app.env.profile === 'prod')
@@ -1123,7 +1123,7 @@ export default class ServerRouter<
             /*if (this.app.env.profile === "dev")
                 console.warn(e);*/
 
-            await this.app.runHook('error.' + code, error, request);
+            await this.app.reportError(error, request);
         }
 
         // Return error based on the request format

package/tests/client-app-error-handling.test.cjs

@@ -0,0 +1,100 @@
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+const path = require('node:path');
+
+const coreRoot = path.join(__dirname, '..');
+require('module-alias').addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+const previousLessExtension = require.extensions['.less'];
+require.extensions['.less'] = () => {};
+
+const clientContextStub = () => ({ side: 'client' });
+clientContextStub.default = clientContextStub;
+const originalLoad = Module._load;
+Module._load = function load(request, parent, isMain) {
+    if (request === '@/client/context') return clientContextStub;
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+const previousWindow = global.window;
+const previousDocument = global.document;
+global.window = {
+    dev: false,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    history: {
+        state: {},
+        pushState: () => {},
+        replaceState: () => {},
+    },
+    location: {
+        hash: '',
+        pathname: '/',
+        search: '',
+        assign: () => {},
+    },
+};
+global.document = { defaultView: global.window };
+
+const {
+    default: Application,
+    getClientErrorMessage,
+    normalizeClientError,
+} = require('../client/app/index.ts');
+
+class TestApplication extends Application {
+    boot() {}
+    handleUpdate() {}
+}
+
+test('client error message normalization accepts unknown caught values', () => {
+    assert.equal(getClientErrorMessage(new Error('boom'), 'fallback'), 'boom');
+    assert.equal(getClientErrorMessage('string failure', 'fallback'), 'string failure');
+    assert.equal(getClientErrorMessage({ message: 'object failure' }, 'fallback'), 'object failure');
+    assert.equal(getClientErrorMessage({ code: 'UNKNOWN' }, 'fallback'), 'fallback');
+});
+
+test('client error normalization returns an Error instance', () => {
+    const existing = new Error('existing');
+
+    assert.equal(normalizeClientError(existing), existing);
+    assert.equal(normalizeClientError('string failure').message, 'string failure');
+    assert.equal(normalizeClientError({ code: 'UNKNOWN' }, 'fallback').message, 'fallback');
+});
+
+test('client app handleError logs and returns displayable message', () => {
+    const app = new TestApplication();
+    const logged = [];
+    const originalConsoleError = console.error;
+    console.error = (error) => {
+        logged.push(error);
+    };
+
+    try {
+        const message = app.handleError({ code: 'UNKNOWN' }, 'Unable to finish action.');
+
+        assert.equal(message, 'Unable to finish action.');
+        assert.equal(logged.length, 1);
+        assert.equal(logged[0] instanceof Error, true);
+        assert.equal(logged[0].message, 'Unable to finish action.');
+    } finally {
+        console.error = originalConsoleError;
+    }
+});
+
+afterAll(() => {
+    Module._load = originalLoad;
+    if (previousLessExtension === undefined) delete require.extensions['.less'];
+    else require.extensions['.less'] = previousLessExtension;
+    if (previousWindow === undefined) delete global.window;
+    else global.window = previousWindow;
+    if (previousDocument === undefined) delete global.document;
+    else global.document = previousDocument;
+});

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

@@ -377,8 +377,9 @@ import SchemaRouter from '@server/services/schema/router';
 import * as appConfig from '@/server/config/app';
 
 export default defineApplication({
-    services: (app) => ({
-        Router: new Router(
+    services: () => ({}),
+    router: (app) =>
+        new Router(
             app,
             {
                 ...appConfig.routerBaseConfig,
@@ -388,7 +389,6 @@ export default defineApplication({
             },
             app,
         ),
-    }),
 });
 `,
     );
@@ -405,9 +405,6 @@ export default class TranspileWatchClient extends ClientApplication {
 
     public boot() {}
     public handleUpdate() {}
-    public handleError(error: Error) {
-        throw error;
-    }
 }
 `,
     );

package/tests/eslint-rules.test.cjs

@@ -3,10 +3,10 @@ const { Linter } = require('eslint');
 
 const { createProteumEslintConfig } = require('../eslint.js');
 
-const lint = (code) => {
+const lint = (code, filename = 'client/example.tsx') => {
     const linter = new Linter({ configType: 'flat' });
     return linter.verify(code, createProteumEslintConfig(), {
-        filename: 'client/example.tsx',
+        filename,
     });
 };
 
@@ -102,7 +102,7 @@ test('proteum lint allows rethrowing the caught error', () => {
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
 
-test('proteum lint allows surfacing original error details', () => {
+test('proteum lint rejects user feedback that does not route the caught error', () => {
     const messages = lint(`
         export const run = async () => {
             try {
@@ -115,10 +115,10 @@ test('proteum lint allows surfacing original error details', () => {
         };
     `);
 
-    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
-test('proteum lint allows surfacing a message derived from the caught error', () => {
+test('proteum lint rejects derived message state that does not route the caught error', () => {
     const messages = lint(`
         export const run = async () => {
             try {
@@ -130,10 +130,10 @@ test('proteum lint allows surfacing a message derived from the caught error', ()
         };
     `);
 
-    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
 });
 
-test('proteum lint allows routing promise failures to app error handling', () => {
+test('proteum lint allows client catches routed to context app error handling', () => {
     const messages = lint(`
         export const run = () => {
             const context = useContext();
@@ -145,3 +145,142 @@ test('proteum lint allows routing promise failures to app error handling', () =>
 
     assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
 });
+
+test('proteum lint allows client catches using app error messages for UI feedback', () => {
+    const messages = lint(`
+        export const run = async () => {
+            const context = useContext();
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                setError(context.app.handleError(error, 'Unable to finish this action.'));
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows client catches routed to local app error handling', () => {
+    const messages = lint(`
+        export const run = async () => {
+            const app = useContext();
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                app.handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows client catches routed to useContext app error handling', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                useContext().app.handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint rejects bare client error handlers', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.ensureApiKey();
+            } catch (error) {
+                handleError(error);
+            }
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows server catches routed to app error reporting', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    await context.app.reportError(error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint rejects server catches routed to client app error handling', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    context.app.handleError(error);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint rejects raw server error hooks as caught error handling', () => {
+    const messages = lint(
+        `
+            export const run = async (context) => {
+                try {
+                    await context.services.Worker.run();
+                } catch (error) {
+                    await context.app.runHook('error', error, context.request);
+                }
+            };
+        `,
+        'server/example.ts',
+    );
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows manual promise rejection', () => {
+    const messages = lint(
+        `
+            export const run = (input) =>
+                new Promise((resolve, reject) => {
+                    input.load().catch((error) => {
+                        reject(error);
+                    });
+                });
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows direct reject promise catch handlers', () => {
+    const messages = lint(
+        `
+            export const run = (input) =>
+                new Promise((resolve, reject) => {
+                    input.load().catch(reject);
+                });
+        `,
+        'common/example.ts',
+    );
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});

package/tests/scaffold-templates.test.cjs

@@ -0,0 +1,18 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const { createServerIndexTemplate } = require('../cli/scaffold/templates.ts');
+
+test('server index scaffold uses explicit defineApplication router property', () => {
+    const content = createServerIndexTemplate({ appIdentifier: 'ExampleApp' });
+
+    assert.match(content, /export default defineApplication\(\{/);
+    assert.match(content, /services: \(\) => \(\{\}\),/);
+    assert.match(content, /router: \(app\) =>\s+new Router\(/);
+    assert.doesNotMatch(content, /services: \(app\) => \(\{\s+Router: new Router\(/);
+});

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

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