proteum 2.5.0 → 2.5.2

package/common/applicationConfig.ts

@@ -32,6 +32,38 @@ export type TApplicationSetupConfig = {
     connect?: TConnectedProjectsConfig;
 };
 
+export type TVerificationCheckScope = 'targeted' | 'area' | 'full' | 'static';
+
+export type TVerificationSuiteConfig =
+    | string
+    | {
+          command: string;
+          cwd?: string;
+          description?: string;
+          scope?: TVerificationCheckScope;
+      };
+
+export type TVerificationRuleConfig = {
+    id: string;
+    match: readonly string[];
+    reason: string;
+    run: readonly string[];
+    scope?: TVerificationCheckScope;
+};
+
+export type TVerificationDocsOnlyConfig =
+    | boolean
+    | {
+          reason?: string;
+      };
+
+export type TVerificationConfig = {
+    always?: readonly string[];
+    docsOnly?: TVerificationDocsOnlyConfig;
+    rules?: readonly TVerificationRuleConfig[];
+    suites?: Record<string, TVerificationSuiteConfig>;
+};
+
 const isRecord = (value: unknown): value is TObjectRecord =>
     value !== null && typeof value === 'object' && !Array.isArray(value);
 
@@ -87,6 +119,137 @@ const readStringRecord = ({
     return output;
 };
 
+const readStringArray = ({
+    filepath,
+    path,
+    value,
+}: {
+    filepath: string;
+    path: string;
+    value: unknown;
+}) => {
+    if (!Array.isArray(value)) throw new Error(`Invalid ${path} in ${filepath}. Expected an array of strings.`);
+
+    const output = value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim() === '')
+            throw new Error(`Invalid ${path}.${index} in ${filepath}. Expected a non-empty string.`);
+
+        return entry.trim();
+    });
+
+    return [...new Set(output)];
+};
+
+const verificationScopes = new Set<TVerificationCheckScope>(['targeted', 'area', 'full', 'static']);
+
+const readVerificationScope = ({
+    filepath,
+    path,
+    value,
+}: {
+    filepath: string;
+    path: string;
+    value: unknown;
+}) => {
+    if (value === undefined) return undefined;
+    if (typeof value !== 'string' || !verificationScopes.has(value as TVerificationCheckScope)) {
+        throw new Error(
+            `Invalid ${path} in ${filepath}. Expected one of ${Array.from(verificationScopes).join(', ')}.`,
+        );
+    }
+
+    return value as TVerificationCheckScope;
+};
+
+const normalizeVerificationSuiteConfig = ({
+    filepath,
+    key,
+    value,
+}: {
+    filepath: string;
+    key: string;
+    value: unknown;
+}): TVerificationSuiteConfig => {
+    if (typeof value === 'string') return readRequiredString({ filepath, path: `suites.${key}`, value });
+    if (!isRecord(value)) throw new Error(`Invalid suites.${key} in ${filepath}. Expected a command string or object.`);
+
+    return {
+        command: readRequiredString({ filepath, path: `suites.${key}.command`, value: value.command }),
+        cwd: readOptionalString({ filepath, path: `suites.${key}.cwd`, value: value.cwd }),
+        description: readOptionalString({ filepath, path: `suites.${key}.description`, value: value.description }),
+        scope: readVerificationScope({ filepath, path: `suites.${key}.scope`, value: value.scope }),
+    };
+};
+
+const normalizeVerificationSuitesConfig = ({
+    filepath,
+    value,
+}: {
+    filepath: string;
+    value: unknown;
+}): Record<string, TVerificationSuiteConfig> => {
+    if (value === undefined) return {};
+    if (!isRecord(value)) throw new Error(`Invalid suites in ${filepath}. Expected an object.`);
+
+    const output: Record<string, TVerificationSuiteConfig> = {};
+
+    for (const [key, entry] of Object.entries(value)) {
+        if (!key.trim()) throw new Error(`Invalid suites key in ${filepath}. Expected a non-empty string.`);
+        output[key] = normalizeVerificationSuiteConfig({ filepath, key, value: entry });
+    }
+
+    return output;
+};
+
+const normalizeVerificationRuleConfig = ({
+    filepath,
+    index,
+    value,
+}: {
+    filepath: string;
+    index: number;
+    value: unknown;
+}): TVerificationRuleConfig => {
+    if (!isRecord(value)) throw new Error(`Invalid rules.${index} in ${filepath}. Expected an object.`);
+
+    return {
+        id: readRequiredString({ filepath, path: `rules.${index}.id`, value: value.id }),
+        match: readStringArray({ filepath, path: `rules.${index}.match`, value: value.match }),
+        reason: readRequiredString({ filepath, path: `rules.${index}.reason`, value: value.reason }),
+        run: readStringArray({ filepath, path: `rules.${index}.run`, value: value.run }),
+        scope: readVerificationScope({ filepath, path: `rules.${index}.scope`, value: value.scope }),
+    };
+};
+
+const normalizeVerificationRulesConfig = ({
+    filepath,
+    value,
+}: {
+    filepath: string;
+    value: unknown;
+}): TVerificationRuleConfig[] => {
+    if (value === undefined) return [];
+    if (!Array.isArray(value)) throw new Error(`Invalid rules in ${filepath}. Expected an array.`);
+
+    return value.map((entry, index) => normalizeVerificationRuleConfig({ filepath, index, value: entry }));
+};
+
+const normalizeVerificationDocsOnlyConfig = ({
+    filepath,
+    value,
+}: {
+    filepath: string;
+    value: unknown;
+}): TVerificationDocsOnlyConfig => {
+    if (value === undefined) return true;
+    if (typeof value === 'boolean') return value;
+    if (!isRecord(value)) throw new Error(`Invalid docsOnly in ${filepath}. Expected a boolean or object.`);
+
+    return {
+        reason: readOptionalString({ filepath, path: 'docsOnly.reason', value: value.reason }),
+    };
+};
+
 const readSocialConfig = ({
     filepath,
     value,
@@ -160,6 +323,18 @@ export const normalizeApplicationSetupConfig = (
     };
 };
 
+export const normalizeVerificationConfig = (value: unknown, filepath = 'proteum.verify.config.ts'): TVerificationConfig => {
+    if (value === undefined) return { always: [], docsOnly: true, rules: [], suites: {} };
+    if (!isRecord(value)) throw new Error(`Invalid verification config in ${filepath}. Expected an object export.`);
+
+    return {
+        always: value.always === undefined ? [] : readStringArray({ filepath, path: 'always', value: value.always }),
+        docsOnly: normalizeVerificationDocsOnlyConfig({ filepath, value: value.docsOnly }),
+        rules: normalizeVerificationRulesConfig({ filepath, value: value.rules }),
+        suites: normalizeVerificationSuitesConfig({ filepath, value: value.suites }),
+    };
+};
+
 class ApplicationConfigHelpers {
     public static identity<const TIdentity extends TApplicationIdentityConfig>(config: TIdentity) {
         return config;
@@ -170,4 +345,6 @@ class ApplicationConfigHelpers {
     }
 }
 
+export const defineVerificationConfig = <const TVerification extends TVerificationConfig>(config: TVerification) => config;
+
 export const Application = ApplicationConfigHelpers;

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

@@ -0,0 +1,269 @@
+# 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.1`, 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 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.
+
+```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 '@generated/server/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`.
+- 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();
+    }
+}
+```
+
+## 8. 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.
+
+## 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.
+
+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.
+
+## 10. 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.
+
+## 11. 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`, 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.