proteum 2.5.1 → 2.5.2

package/common/applicationConfigLoader.ts

@@ -5,10 +5,13 @@ import * as ts from 'typescript';
 
 import {
     Application as ApplicationConfig,
+    defineVerificationConfig,
     normalizeApplicationIdentityConfig,
     normalizeApplicationSetupConfig,
+    normalizeVerificationConfig,
     type TApplicationIdentityConfig,
     type TApplicationSetupConfig,
+    type TVerificationConfig,
 } from './applicationConfig';
 import { loadOptionalProteumDotenv } from './env/proteumEnv';
 
@@ -51,7 +54,8 @@ const loadTsModule = (filepath: string): unknown => {
 
     const requireFromFile = createRequire(normalizedFilepath);
     const runtimeRequire = (specifier: string) => {
-        if (specifier === 'proteum/config' || specifier === 'proteum/config.ts') return { Application: ApplicationConfig };
+        if (specifier === 'proteum/config' || specifier === 'proteum/config.ts')
+            return { Application: ApplicationConfig, defineVerificationConfig };
 
         if (specifier.startsWith('.') || specifier.startsWith('/')) {
             const resolved = resolveLocalModulePath(specifier, normalizedFilepath);
@@ -81,9 +85,11 @@ const getDefaultExport = <T>(value: unknown): T => {
 
 export const identityConfigFilename = 'identity.config.ts';
 export const setupConfigFilename = 'proteum.config.ts';
+export const verificationConfigFilename = 'proteum.verify.config.ts';
 
 export const resolveIdentityConfigFilepath = (appDir: string) => path.join(appDir, identityConfigFilename);
 export const resolveSetupConfigFilepath = (appDir: string) => path.join(appDir, setupConfigFilename);
+export const resolveVerificationConfigFilepath = (rootDir: string) => path.join(rootDir, verificationConfigFilename);
 
 export const loadApplicationIdentityConfig = (appDir: string): TApplicationIdentityConfig => {
     const filepath = resolveIdentityConfigFilepath(appDir);
@@ -100,3 +106,29 @@ export const loadApplicationSetupConfig = (appDir: string): TApplicationSetupCon
 
     return normalizeApplicationSetupConfig(getDefaultExport(loadTsModule(filepath)), filepath);
 };
+
+export const findVerificationConfigFilepath = (startDir: string) => {
+    let currentDir = path.resolve(startDir);
+
+    while (true) {
+        const candidate = resolveVerificationConfigFilepath(currentDir);
+        if (fs.existsSync(candidate)) return candidate;
+
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) return undefined;
+        currentDir = parentDir;
+    }
+};
+
+export const loadVerificationConfig = (
+    startDir: string,
+): { config: TVerificationConfig; filepath?: string; root: string } => {
+    const filepath = findVerificationConfigFilepath(startDir);
+    if (!filepath) return { config: normalizeVerificationConfig(undefined), root: path.resolve(startDir) };
+
+    return {
+        config: normalizeVerificationConfig(getDefaultExport(loadTsModule(filepath)), filepath),
+        filepath,
+        root: path.dirname(filepath),
+    };
+};

package/common/dev/contractsDoctor.ts

@@ -152,8 +152,24 @@ const isRouterRenderCallback = (node: ts.FunctionLikeDeclaration) => {
     return lastFunctionArgument === unwrappedNode;
 };
 
+const isDefinitionRouteRenderCallback = (node: ts.FunctionLikeDeclaration) => {
+    const unwrappedNode = unwrapExpression(node);
+    const parent = unwrappedNode.parent;
+    if (!ts.isPropertyAssignment(parent)) return false;
+    if (!ts.isIdentifier(parent.name) || parent.name.text !== 'render') return false;
+    if (!ts.isObjectLiteralExpression(parent.parent)) return false;
+
+    const callExpression = parent.parent.parent;
+    if (!ts.isCallExpression(callExpression)) return false;
+    if (!ts.isIdentifier(callExpression.expression)) return false;
+
+    const helperName = callExpression.expression.text;
+    return helperName === 'definePageRoute' || helperName === 'defineErrorRoute';
+};
+
 const isValidHookContainer = (node: ts.FunctionLikeDeclaration) => {
     if (isRouterRenderCallback(node)) return true;
+    if (isDefinitionRouteRenderCallback(node)) return true;
 
     const functionName = getFunctionName(node);
     if (!functionName) return false;

package/config.ts

@@ -1,5 +1,9 @@
-export { Application } from './common/applicationConfig';
+export { Application, defineVerificationConfig } from './common/applicationConfig';
 export type {
     TApplicationIdentityConfig as ApplicationIdentityConfig,
     TApplicationSetupConfig as ApplicationSetupConfig,
+    TVerificationCheckScope as VerificationCheckScope,
+    TVerificationConfig as VerificationConfig,
+    TVerificationRuleConfig as VerificationRuleConfig,
+    TVerificationSuiteConfig as VerificationSuiteConfig,
 } from './common/applicationConfig';

package/docs/migration-2.5.md

@@ -14,7 +14,7 @@ Proteum 2.5 is a breaking cleanup release. It removes contextual app/router magi
 
 ## 1. Install The Published Package
 
-Update every Proteum app package in the repo to `proteum@^2.5.0`, then reinstall from npm.
+Update every Proteum app package in the repo to `proteum@^2.5.1`, then reinstall from npm.
 
 ```bash
 npm install
@@ -71,16 +71,39 @@ const createProjectRouter = (app: ProjectApp): ProjectRouter =>
         app,
     );
 
-const ProjectApplication = defineApplication<ProjectServices, ProjectRouter>({
-    services: (app) => ({
-        Billing: new BillingService(app, {}, app),
-    }),
+const createProjectServices = (app: ProjectApp): ProjectServices => ({
+    Billing: new BillingService(app, {}, app),
+});
+
+const ProjectApplication = defineApplication({
+    services: createProjectServices,
     router: createProjectRouter,
 });
 
 export default ProjectApplication;
 ```
 
+Generated app globals read the named app type exported by `server/index.ts`. Derive that named type from the default `defineApplication` export when the app does not need a more explicit bootstrap type:
+
+```ts
+import type ProjectApplication from '@/server/index';
+
+type ProjectApp = InstanceType<typeof ProjectApplication>;
+```
+
+In app roots with service constructors that need earlier services during boot, use an explicit exported app type plus a progressively assigned service factory:
+
+```ts
+export type ProjectServices = {
+    Models: ModelsService;
+    Domains: DomainsService;
+};
+
+export type ProjectApp = Application & ProjectServices & {
+    Router: ProjectRouter;
+};
+```
+
 ## 4. Migrate Pages
 
 Replace legacy page registration with a default-exported page definition.
@@ -139,7 +162,7 @@ Use `defineServerRoutes((app) => [...])` only when the route definitions need ap
 Replace controller classes and `this.input(schema)` with explicit actions.
 
 ```ts
-import { defineAction, defineController, schema } from '@server/app/controller';
+import { defineAction, defineController, schema } from '@generated/server/controller';
 
 export default defineController({
     path: 'Billing',
@@ -158,8 +181,27 @@ Rules:
 - 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`.
+- Import controller definition helpers from `@generated/server/controller` when app-specific services, models, router, or request plugins are needed. The generated helper binds context to the concrete app type exported by `server/index.ts`.
+- Keep action schemas aligned with existing typed service methods. If a service method accepts `{ domainIds?: string[]; entries?: Entry[] }`, the `defineAction({ input })` schema must mark those fields optional too. Proteum 2.5 generates strict client types from these schemas, so stale schemas that were previously hidden by loose clients become compile errors.
+
+## 7. Migrate Commands
+
+Commands should no longer import a default `App` type from `server/index.ts`. The default export is now the application constructor returned by `defineApplication`.
+
+```ts
+import { Commands } from '@server/app/commands';
+import type ProjectApplication from '@/server/index';
+
+type ProjectApp = InstanceType<typeof ProjectApplication>;
+
+export default class BillingCommands extends Commands<ProjectApp> {
+    public async sync() {
+        return this.app.Billing.sync();
+    }
+}
+```
 
-## 7. Remove Legacy Magic
+## 8. Remove Legacy Magic
 
 Search user source for old contracts and remove every match.
 
@@ -175,7 +217,7 @@ Allowed replacements:
 - `this.app`, `this.services`, and `this.models` inside typed services.
 - `defineServerRoutes((app) => [...])` when server route definitions need app services.
 
-## 8. Standardize Caught Error Handling
+## 9. 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.
 
@@ -195,7 +237,7 @@ Client rules:
 
 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
+## 10. Refresh Generated Artifacts
 
 Do not edit `.proteum/**` manually. Regenerate it from source.
 
@@ -206,7 +248,7 @@ 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
+## 11. Validate Runtime Behavior
 
 Run the smallest trustworthy checks first, then broaden when the touched surface requires it.
 
@@ -222,5 +264,6 @@ For protected flows, prefer Proteum session helpers over automating login unless
 
 - 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`.
+- Missing `this.app.Router`, service, or `env` typings are fixed by exporting the project app type from `server/index.ts`, letting `defineApplication({ services, router })` infer from typed factories, and refreshing generated artifacts.
 - Static metadata errors are fixed by moving runtime-dependent values out of `path`, `method`, `options`, and error `code`.
+- Shared package interfaces should match the server controller schemas they wrap. A shared client type that allows `null` or extra enum values while the server schema rejects them will now fail assignment against the generated controller client.

package/eslint.js

@@ -16,23 +16,24 @@ const createZodTypeFactorySelector = (factoryName) =>
 
 const skippedTraversalKeys = new Set(['parent', 'loc', 'range', 'tokens', 'comments']);
 
-const traverseNode = (node, visit, parent = null, parentKey = null) => {
+const traverseNode = (node, visit, parent = null, parentKey = null, ancestors = []) => {
     if (!node || typeof node !== 'object') return;
 
-    visit(node, parent, parentKey);
+    visit(node, parent, parentKey, ancestors);
 
     for (const key of Object.keys(node)) {
         if (skippedTraversalKeys.has(key)) continue;
 
         const value = node[key];
+        const nextAncestors = [...ancestors, { node, childKey: key }];
         if (Array.isArray(value)) {
             value.forEach((child) => {
-                if (child && typeof child.type === 'string') traverseNode(child, visit, node, key);
+                if (child && typeof child.type === 'string') traverseNode(child, visit, node, key, nextAncestors);
             });
             continue;
         }
 
-        if (value && typeof value.type === 'string') traverseNode(value, visit, node, key);
+        if (value && typeof value.type === 'string') traverseNode(value, visit, node, key, nextAncestors);
     }
 };
 
@@ -160,8 +161,35 @@ const isServerErrorReporterCall = (callExpression) =>
 
 const isPromiseRejectCall = (callExpression) => getCalleePropertyName(callExpression.callee) === 'reject';
 
-const isPreservingCall = (callExpression, names, side) => {
+const hasOptionalCallBoundary = (callExpression, ancestors = []) => {
+    if (callExpression.optional === true) return true;
+
+    let hasOptional = false;
+    traverseNode(callExpression.callee, (child) => {
+        if (child.type === 'ChainExpression' || child.optional === true) hasOptional = true;
+    });
+
+    return hasOptional || ancestors.some(({ node }) => node.type === 'ChainExpression');
+};
+
+const isUnderConditionalControlFlow = (ancestors = []) =>
+    ancestors.some(({ node, childKey }) => {
+        if (node.type === 'IfStatement') return childKey === 'consequent' || childKey === 'alternate';
+        if (node.type === 'ConditionalExpression') return childKey === 'consequent' || childKey === 'alternate';
+        if (node.type === 'LogicalExpression') return childKey === 'right';
+        if (node.type === 'SwitchCase') return childKey === 'consequent';
+
+        return (
+            ['ForInStatement', 'ForOfStatement', 'ForStatement', 'WhileStatement', 'DoWhileStatement'].includes(
+                node.type,
+            ) && childKey === 'body'
+        );
+    });
+
+const isPreservingCall = (callExpression, names, side, ancestors = []) => {
     if (!nodeReferencesName(callExpression, names)) return false;
+    if (hasOptionalCallBoundary(callExpression, ancestors)) return false;
+    if (isUnderConditionalControlFlow(ancestors)) return false;
     if (isConsoleMember(callExpression.callee)) return false;
     if (isPromiseRejectCall(callExpression)) return true;
     if (side === 'client') return isClientErrorHandlerCall(callExpression);
@@ -173,9 +201,15 @@ const isPreservingCall = (callExpression, names, side) => {
 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, side)) preserves = true;
+    traverseNode(node, (child, _parent, _parentKey, ancestors) => {
+        if (
+            child.type === 'ThrowStatement' &&
+            nodeReferencesName(child.argument, names) &&
+            !isUnderConditionalControlFlow(ancestors)
+        ) {
+            preserves = true;
+        }
+        if (child.type === 'CallExpression' && isPreservingCall(child, names, side, ancestors)) preserves = true;
     });
 
     return preserves;

package/package.json

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

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

@@ -205,6 +205,20 @@ test('mcp help describes projectId routing', () => {
     assert.match(output, /--stdio/);
 });
 
+test('verify help documents changed-file verification flags', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'verify', '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /changed/);
+    assert.match(output, /--staged/);
+    assert.match(output, /--base/);
+    assert.match(output, /--dry-run/);
+});
+
 test('mcp daemon launch prints a central MCP connection banner', async () => {
     const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-daemon-launch-'));
     const reserveServer = http.createServer((req, res) => res.end('reserved'));

package/tests/contracts-doctor.test.cjs

@@ -0,0 +1,98 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const { buildContractsDoctorResponse } = require('../common/dev/contractsDoctor.ts');
+
+const touch = (filepath, content = '') => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+const createManifest = (appRoot, pageFilepath) => ({
+    app: {
+        identityFilepath: path.join(appRoot, 'identity.config.ts'),
+        root: appRoot,
+        setupFilepath: path.join(appRoot, 'proteum.config.ts'),
+    },
+    connectedProjects: [],
+    commands: [],
+    controllers: [],
+    layouts: [],
+    routes: {
+        client: [
+            {
+                chunkFilepath: 'landing/index',
+                filepath: pageFilepath,
+            },
+        ],
+        server: [],
+    },
+    services: {
+        app: [],
+        routerPlugins: [],
+    },
+});
+
+test('contracts doctor allows hooks inside definePageRoute render callbacks', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-contracts-doctor-'));
+    const pageFilepath = path.join(appRoot, 'client/pages/landing/index.tsx');
+
+    touch(path.join(appRoot, 'proteum.config.ts'), 'export default {};');
+    touch(path.join(appRoot, 'identity.config.ts'), 'export default {};');
+    touch(path.join(appRoot, 'client/hooks/useToast.ts'), 'export default function useToast() { return () => undefined; }');
+    touch(
+        pageFilepath,
+        `import { definePageRoute } from '@common/router/definitions';
+import useToast from '@/client/hooks/useToast';
+
+export default definePageRoute({
+    path: '/',
+    options: {},
+    data: null,
+    render: () => {
+        const toast = useToast();
+        return toast ? null : null;
+    },
+});
+`,
+    );
+
+    for (const filepath of [
+        'proteum.connected.json',
+        '.proteum/manifest.json',
+        '.proteum/proteum.connected.d.ts',
+        '.proteum/client/context.ts',
+        '.proteum/client/controllers.ts',
+        '.proteum/client/layouts.ts',
+        '.proteum/client/models.ts',
+        '.proteum/client/routes.ts',
+        '.proteum/client/services.d.ts',
+        '.proteum/common/controllers.ts',
+        '.proteum/common/models.ts',
+        '.proteum/common/services.d.ts',
+        '.proteum/server/commands.app.d.ts',
+        '.proteum/server/commands.d.ts',
+        '.proteum/server/commands.ts',
+        '.proteum/server/controllers.ts',
+        '.proteum/server/models.ts',
+        '.proteum/server/routes.ts',
+        '.proteum/server/services.d.ts',
+        '.proteum/client/route-modules/landing/index.tsx',
+        '.proteum/server/route-modules/client/pages/landing/index.tsx',
+    ]) {
+        touch(path.join(appRoot, filepath));
+    }
+
+    const response = buildContractsDoctorResponse(createManifest(appRoot, pageFilepath));
+    assert.equal(
+        response.diagnostics.some((diagnostic) => diagnostic.code === 'runtime/provider-hook-outside-provider'),
+        false,
+    );
+});

package/tests/definition-contracts.test.cjs

@@ -18,6 +18,7 @@ const {
     indexRouteDefinitions,
     writeGeneratedRouteModule,
 } = require('../cli/compiler/common/generatedRouteModules.ts');
+const { createTypedControllerHelperContent } = require('../cli/compiler/artifacts/controllerHelper.ts');
 const { findClientRouteFiles } = require('../cli/compiler/artifacts/discovery.ts');
 const { indexControllers } = require('../cli/compiler/common/controllers.ts');
 const {
@@ -107,6 +108,51 @@ export default definePageRoute({
     assert.deepEqual(definition.normalizedOptionKeys, ['auth']);
 });
 
+test('route indexer accepts imported const-only option metadata', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'client/pages/feed.tsx');
+    const catalogFilepath = path.join(root, 'client/catalogs/routes.ts');
+
+    writeFile(
+        catalogFilepath,
+        `export const PAGE_AUTH = {
+    feed: {
+        auth: {
+            hasFeature: 'opportunitiesFreq',
+        },
+        authTracking: {
+            source: 'investor_feed',
+            feature: 'opportunitiesFreq',
+            action: 'open-feed',
+            triggerKind: 'open',
+        },
+    },
+} as const;
+`,
+    );
+    writeFile(
+        filepath,
+        `import { definePageRoute } from '@common/router/definitions';
+import { PAGE_AUTH } from '@/client/catalogs/routes';
+
+export default definePageRoute({
+    path: '/feed',
+    options: {
+        auth: PAGE_AUTH.feed.auth,
+        authTracking: PAGE_AUTH.feed.authTracking,
+    },
+    data: null,
+    render: () => null,
+});
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'client', sourceFilepath: filepath });
+
+    assert.equal(definition.path, '/feed');
+    assert.deepEqual(definition.normalizedOptionKeys, ['auth', 'authTracking']);
+});
+
 test('router port override updates absolute runtime URLs', () => {
     const root = createTempDir();
 
@@ -262,6 +308,37 @@ export default defineServerRoutes(({ Users }) => [
     assert.equal(definition.targetResolution, 'static-expression');
 });
 
+test('server route factories can push explicit route definitions from a block body', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/routes/api.ts');
+
+    writeFile(
+        filepath,
+        `import { defineServerRoute, defineServerRoutes } from '@common/router/definitions';
+
+export default defineServerRoutes((app) => {
+    const { Users } = app;
+    const routeOptions = {};
+    const routes = [];
+
+    routes.push(defineServerRoute({
+        method: 'GET',
+        path: '/api/users',
+        options: routeOptions,
+        handler: async () => Users.list(),
+    }));
+
+    return routes;
+});
+`,
+    );
+
+    const [definition] = indexRouteDefinitions({ side: 'server', sourceFilepath: filepath });
+
+    assert.equal(definition.methodName, 'get');
+    assert.equal(definition.path, '/api/users');
+});
+
 test('route definitions register through explicit router registrar', () => {
     const calls = [];
 
@@ -386,6 +463,17 @@ export default class Legacy extends Controller {
     );
 });
 
+test('generated typed controller helper binds action context to app root', () => {
+    const content = createTypedControllerHelperContent('TestApp');
+
+    assert.match(content, /@server\/app\/controller/);
+    assert.match(content, /@\/server\/index/);
+    assert.match(content, /export type TApplication = import\('@\/server\/index'\)\.TestApp/);
+    assert.match(content, /export type TControllerRequestServices = import\('@\/server\/index'\)\.TControllerRequestServices/);
+    assert.match(content, /TControllerActionContext<\n    TInput,\n    TApplication,\n    TControllerRequestServices\n>/);
+    assert.match(content, /handler: \(context: TTypedControllerActionContext<z\.output<TSchema>>\) => TResult/);
+});
+
 test('service artifact parser reads defineApplication router factories', () => {
     const root = createTempDir();
     const filepath = path.join(root, 'server/index.ts');
@@ -451,3 +539,44 @@ export default App;
     assert.deepEqual(bootstrap.rootServices.map((service) => service.registeredName), ['Router']);
     assert.deepEqual(bootstrap.routerPlugins.map((service) => service.registeredName), ['schema']);
 });
+
+test('service artifact parser reads named defineApplication service factories', () => {
+    const root = createTempDir();
+    const filepath = path.join(root, 'server/index.ts');
+    const serviceFilepath = path.join(root, 'server/services/Billing.ts');
+    const { parseAppBootstrapSource } = loadServiceArtifactsForAppRoot(root);
+
+    writeFile(serviceFilepath, 'export default class Billing {}');
+    writeFile(
+        filepath,
+        `import { defineApplication } from '@server/app';
+import Router from '@server/services/router';
+import SchemaRouter from '@server/services/schema/router';
+import Billing from '@/server/services/Billing';
+
+const createServices = (app) => ({
+    Billing: new Billing(app, {}, app),
+});
+
+const createRouter = (app) => new Router(
+    app,
+    {
+        plugins: {
+            schema: new SchemaRouter({}, app),
+        },
+    },
+    app,
+);
+
+export default defineApplication({
+    services: createServices,
+    router: createRouter,
+});
+`,
+    );
+
+    const bootstrap = parseAppBootstrapSource(filepath);
+
+    assert.deepEqual(bootstrap.rootServices.map((service) => service.registeredName), ['Billing', 'Router']);
+    assert.deepEqual(bootstrap.routerPlugins.map((service) => service.registeredName), ['schema']);
+});