proteum 2.5.1 → 2.5.3

package/cli/compiler/artifacts/services.ts

@@ -615,10 +615,14 @@ const parseDefineApplicationBootstrap = (
     if (!definitionArg) return undefined;
 
     const servicesProperty = getObjectLiteralProperty(definitionArg, 'services');
-    const servicesDetails =
+    const servicesInitializer =
         servicesProperty && ts.isPropertyAssignment(servicesProperty)
-            ? getObjectLiteralFactoryDetails(servicesProperty.initializer)
+            ? ts.isIdentifier(unwrapExpression(servicesProperty.initializer)) &&
+              topLevelInitializers.has((unwrapExpression(servicesProperty.initializer) as ts.Identifier).text)
+                ? topLevelInitializers.get((unwrapExpression(servicesProperty.initializer) as ts.Identifier).text)!
+                : servicesProperty.initializer
             : undefined;
+    const servicesDetails = servicesInitializer ? getObjectLiteralFactoryDetails(servicesInitializer) : undefined;
     const servicesObject = servicesDetails?.object;
     const localServiceInitializers = servicesDetails?.localInitializers || new Map<string, ts.Expression>();
     const rootServices = parseRootServiceObject(servicesObject, imports, sourceFile.fileName, localServiceInitializers);
@@ -826,6 +830,7 @@ const createCommandServiceStubDeclarations = (rootServices: TParsedService[]): T
     const typeNamesByAliasImportPath = new Map<string, string>();
     const pendingSources: TCommandServiceStubSource[] = [];
     const seenSources = new Set<string>();
+    const appTypeReference = `import("@server/app/index").Application & import("@/server/index").${app.identity.identifier}`;
     const getStubTypeName = (source: TCommandServiceStubSource) => {
         const existingTypeName = typeNamesByAliasImportPath.get(source.aliasImportPath);
         if (existingTypeName) return existingTypeName;
@@ -863,7 +868,7 @@ const createCommandServiceStubDeclarations = (rootServices: TParsedService[]): T
             stubs.set(
                 source.aliasImportPath,
                 `declare class ${getStubTypeName(source)} {
-    app: InstanceType<typeof import("@/server/index").default>;
+    app: ${appTypeReference};
     [key: string]: any;
 }`,
             );
@@ -871,7 +876,7 @@ const createCommandServiceStubDeclarations = (rootServices: TParsedService[]): T
         }
 
         const className = getStubTypeName(source);
-        const classMembers = [`    app: InstanceType<typeof import("@/server/index").default>;`];
+        const classMembers = [`    app: ${appTypeReference};`];
 
         for (const member of defaultClass.members) {
             if (isPrivateOrProtectedInstanceMember(member)) continue;
@@ -994,6 +999,7 @@ export const generateServiceArtifacts = () => {
     const appServices = rootServices.map((service) => resolveManifestService(service, 'app'));
     const routerPluginServices = routerPlugins.map((service) => resolveManifestService(service, 'Router.plugins'));
     const commandServiceStubs = createCommandServiceStubDeclarations(rootServices);
+    const appTypeReference = `import("@server/app/index").Application & import("@/server/index").${appIdentifier}`;
 
     writeIfChanged(
         path.join(app.paths.client.generated, 'server-index.d.ts'),
@@ -1002,7 +1008,7 @@ export const generateServiceArtifacts = () => {
 
     writeIfChanged(
         path.join(app.paths.client.generated, 'services.d.ts'),
-        `declare type ${appIdentifier} = InstanceType<typeof import("@/server/index").default>;
+        `declare type ${appIdentifier} = ${appTypeReference};
     
 declare module '@models/types' {
     export * from '@generated/client/models';
@@ -1066,7 +1072,7 @@ export default (): ClientContext => {
 
     writeIfChanged(
         path.join(app.paths.common.generated, 'services.d.ts'),
-        `declare type ${appIdentifier} = InstanceType<typeof import("@/server/index").default>;
+        `declare type ${appIdentifier} = ${appTypeReference};
 
 declare module '@models/types' {
     export * from '@generated/common/models';
@@ -1083,7 +1089,7 @@ declare module '@models/types' {
 
     writeIfChanged(
         path.join(app.paths.server.generated, 'commands.d.ts'),
-        `declare type ${appIdentifier} = InstanceType<typeof import("@/server/index").default>;
+        `declare type ${appIdentifier} = ${appTypeReference};
 
 declare module "@models/types" {
     const Models: any;
@@ -1127,7 +1133,7 @@ export default ${appIdentifier};
 
     writeIfChanged(
         path.join(app.paths.server.generated, 'services.d.ts'),
-        `declare type ${appIdentifier} = InstanceType<typeof import("@/server/index").default>;
+        `declare type ${appIdentifier} = ${appTypeReference};
 
 declare module '@common/errors' {
         

package/cli/compiler/common/generatedRouteModules.ts

@@ -64,8 +64,75 @@ const parseSourceFile = (filepath: string, code: string) =>
         filepath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
     );
 
+const parsedSourceFileCache = new Map<string, ts.SourceFile | null>();
+
 const normalizeFilepath = (value: string) => path.resolve(value).replace(/\\/g, '/');
 
+const resolveExistingModuleFilepath = (baseFilepath: string) => {
+    const candidates = [
+        baseFilepath,
+        `${baseFilepath}.ts`,
+        `${baseFilepath}.tsx`,
+        `${baseFilepath}.js`,
+        `${baseFilepath}.jsx`,
+        path.join(baseFilepath, 'index.ts'),
+        path.join(baseFilepath, 'index.tsx'),
+        path.join(baseFilepath, 'index.js'),
+        path.join(baseFilepath, 'index.jsx'),
+    ];
+
+    return candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+};
+
+const getAppRootFromSourceFile = (sourceFilepath: string) => {
+    const normalized = normalizeFilepath(sourceFilepath);
+    const markers = ['/client/', '/server/', '/common/', '/commands/'];
+    const markerIndex = markers
+        .map((marker) => ({ marker, index: normalized.indexOf(marker) }))
+        .filter(({ index }) => index >= 0)
+        .sort((left, right) => left.index - right.index)[0];
+
+    return markerIndex ? normalized.slice(0, markerIndex.index) : path.dirname(sourceFilepath);
+};
+
+const resolveStaticImportFilepath = (sourceFile: ts.SourceFile, moduleSpecifier: string) => {
+    if (moduleSpecifier.startsWith('.')) {
+        return resolveExistingModuleFilepath(path.resolve(path.dirname(sourceFile.fileName), moduleSpecifier));
+    }
+
+    const appRoot = getAppRootFromSourceFile(sourceFile.fileName);
+    const aliases: Array<[string, string]> = [
+        ['@/', appRoot],
+        ['@client/', path.join(appRoot, 'client')],
+        ['@server/', path.join(appRoot, 'server')],
+        ['@common/', path.join(appRoot, 'common')],
+    ];
+
+    for (const [prefix, root] of aliases) {
+        if (!moduleSpecifier.startsWith(prefix)) continue;
+
+        const relativeImport = moduleSpecifier.slice(prefix.length);
+        return resolveExistingModuleFilepath(path.join(root, relativeImport));
+    }
+
+    return undefined;
+};
+
+const readStaticImportSourceFile = (filepath: string) => {
+    const normalized = normalizeFilepath(filepath);
+    if (parsedSourceFileCache.has(normalized)) return parsedSourceFileCache.get(normalized) || undefined;
+
+    if (!fs.existsSync(normalized)) {
+        parsedSourceFileCache.set(normalized, null);
+        return undefined;
+    }
+
+    const sourceFile = parseSourceFile(normalized, fs.readFileSync(normalized, 'utf8'));
+    parsedSourceFileCache.set(normalized, sourceFile);
+
+    return sourceFile;
+};
+
 const getNodeText = (sourceFile: ts.SourceFile, node: ts.Node) =>
     sourceFile.text.slice(node.getStart(sourceFile), node.getEnd());
 
@@ -115,39 +182,46 @@ const tryEvaluateStaticExpression = (
     resolvedBindings: Map<string, string | number | undefined>,
     activeBindings = new Set<string>(),
 ): string | number | undefined => {
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    const expression = unwrapStaticExpression(node);
+    const resolvedExpression = resolveStaticExpressionNode(expression, bindingInitializers, activeBindings);
 
-    if (ts.isNumericLiteral(node)) {
-        const value = Number(node.text);
+    if (resolvedExpression !== expression) {
+        return tryEvaluateStaticExpression(resolvedExpression, bindingInitializers, resolvedBindings, activeBindings);
+    }
+
+    if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return expression.text;
+
+    if (ts.isNumericLiteral(expression)) {
+        const value = Number(expression.text);
         return Number.isFinite(value) ? value : undefined;
     }
 
-    if (ts.isParenthesizedExpression(node)) {
-        return tryEvaluateStaticExpression(node.expression, bindingInitializers, resolvedBindings, activeBindings);
+    if (ts.isParenthesizedExpression(expression)) {
+        return tryEvaluateStaticExpression(expression.expression, bindingInitializers, resolvedBindings, activeBindings);
     }
 
-    if (ts.isIdentifier(node)) {
-        if (resolvedBindings.has(node.text)) return resolvedBindings.get(node.text);
+    if (ts.isIdentifier(expression)) {
+        if (resolvedBindings.has(expression.text)) return resolvedBindings.get(expression.text);
 
-        const initializer = bindingInitializers.get(node.text);
-        if (!initializer || activeBindings.has(node.text)) return undefined;
+        const initializer = bindingInitializers.get(expression.text);
+        if (!initializer || activeBindings.has(expression.text)) return undefined;
 
-        activeBindings.add(node.text);
+        activeBindings.add(expression.text);
         const value = tryEvaluateStaticExpression(initializer, bindingInitializers, resolvedBindings, activeBindings);
-        activeBindings.delete(node.text);
-        resolvedBindings.set(node.text, value);
+        activeBindings.delete(expression.text);
+        resolvedBindings.set(expression.text, value);
 
         return value;
     }
 
-    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
-        const operand = tryEvaluateStaticExpression(node.operand, bindingInitializers, resolvedBindings, activeBindings);
+    if (ts.isPrefixUnaryExpression(expression) && expression.operator === ts.SyntaxKind.MinusToken) {
+        const operand = tryEvaluateStaticExpression(expression.operand, bindingInitializers, resolvedBindings, activeBindings);
         return typeof operand === 'number' ? -operand : undefined;
     }
 
-    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
-        const left = tryEvaluateStaticExpression(node.left, bindingInitializers, resolvedBindings, activeBindings);
-        const right = tryEvaluateStaticExpression(node.right, bindingInitializers, resolvedBindings, activeBindings);
+    if (ts.isBinaryExpression(expression) && expression.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const left = tryEvaluateStaticExpression(expression.left, bindingInitializers, resolvedBindings, activeBindings);
+        const right = tryEvaluateStaticExpression(expression.right, bindingInitializers, resolvedBindings, activeBindings);
 
         if (left === undefined || right === undefined) return undefined;
 
@@ -157,10 +231,10 @@ const tryEvaluateStaticExpression = (
         return undefined;
     }
 
-    if (ts.isTemplateExpression(node)) {
-        let output = node.head.text;
+    if (ts.isTemplateExpression(expression)) {
+        let output = expression.head.text;
 
-        for (const span of node.templateSpans) {
+        for (const span of expression.templateSpans) {
             const value = tryEvaluateStaticExpression(span.expression, bindingInitializers, resolvedBindings, activeBindings);
             if (value === undefined) return undefined;
 
@@ -183,6 +257,70 @@ const unwrapStaticExpression = (node: ts.Expression): ts.Expression => {
     return node;
 };
 
+const getStaticPropertyName = (node: ts.PropertyName | ts.Expression) => {
+    if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node)) return node.text;
+    return undefined;
+};
+
+const getStaticObjectPropertyInitializer = (node: ts.ObjectLiteralExpression, propertyName: string) => {
+    for (const property of node.properties) {
+        if (ts.isPropertyAssignment(property)) {
+            const key = getObjectLiteralPropertyKey(property.name);
+            if (key === propertyName) return property.initializer;
+            continue;
+        }
+
+        if (ts.isShorthandPropertyAssignment(property) && property.name.text === propertyName) {
+            return property.name;
+        }
+    }
+
+    return undefined;
+};
+
+const resolveStaticExpressionNode = (
+    node: ts.Expression,
+    bindingInitializers: Map<string, ts.Expression>,
+    activeBindings = new Set<string>(),
+): ts.Expression => {
+    const expression = unwrapStaticExpression(node);
+
+    if (ts.isIdentifier(expression)) {
+        const initializer = bindingInitializers.get(expression.text);
+        if (!initializer || activeBindings.has(expression.text)) return expression;
+
+        activeBindings.add(expression.text);
+        const resolved = resolveStaticExpressionNode(initializer, bindingInitializers, activeBindings);
+        activeBindings.delete(expression.text);
+
+        return resolved;
+    }
+
+    if (ts.isPropertyAccessExpression(expression)) {
+        const container = resolveStaticExpressionNode(expression.expression, bindingInitializers, activeBindings);
+        const unwrappedContainer = unwrapStaticExpression(container);
+        if (!ts.isObjectLiteralExpression(unwrappedContainer)) return expression;
+
+        const initializer = getStaticObjectPropertyInitializer(unwrappedContainer, expression.name.text);
+        return initializer ? resolveStaticExpressionNode(initializer, bindingInitializers, activeBindings) : expression;
+    }
+
+    if (ts.isElementAccessExpression(expression)) {
+        const argument = expression.argumentExpression && unwrapStaticExpression(expression.argumentExpression);
+        const propertyName = argument && getStaticPropertyName(argument);
+        if (!propertyName) return expression;
+
+        const container = resolveStaticExpressionNode(expression.expression, bindingInitializers, activeBindings);
+        const unwrappedContainer = unwrapStaticExpression(container);
+        if (!ts.isObjectLiteralExpression(unwrappedContainer)) return expression;
+
+        const initializer = getStaticObjectPropertyInitializer(unwrappedContainer, propertyName);
+        return initializer ? resolveStaticExpressionNode(initializer, bindingInitializers, activeBindings) : expression;
+    }
+
+    return expression;
+};
+
 const isStaticSerializableExpression = (
     node: ts.Expression,
     bindingInitializers: Map<string, ts.Expression>,
@@ -190,6 +328,11 @@ const isStaticSerializableExpression = (
     activeBindings = new Set<string>(),
 ): boolean => {
     const expression = unwrapStaticExpression(node);
+    const resolvedExpression = resolveStaticExpressionNode(expression, bindingInitializers, activeBindings);
+
+    if (resolvedExpression !== expression) {
+        return isStaticSerializableExpression(resolvedExpression, bindingInitializers, resolvedBindings, activeBindings);
+    }
 
     if (
         ts.isStringLiteral(expression) ||
@@ -275,21 +418,9 @@ const assertStaticSerializableMetadata = (
     );
 };
 
-const collectStaticBindings = (sourceFile: ts.SourceFile) => {
-    const bindingInitializers = new Map<string, ts.Expression>();
+const resolveStaticBindings = (bindingInitializers: Map<string, ts.Expression>) => {
     const resolvedBindings = new Map<string, string | number | undefined>();
 
-    for (const statement of sourceFile.statements) {
-        if (!ts.isVariableStatement(statement)) continue;
-        if (!(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
-
-        for (const declaration of statement.declarationList.declarations) {
-            if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
-
-            bindingInitializers.set(declaration.name.text, declaration.initializer);
-        }
-    }
-
     for (const bindingName of bindingInitializers.keys()) {
         if (resolvedBindings.has(bindingName)) continue;
 
@@ -305,11 +436,15 @@ const collectStaticBindings = (sourceFile: ts.SourceFile) => {
     return resolvedBindings;
 };
 
-const collectStaticBindingInitializers = (sourceFile: ts.SourceFile) => {
+const collectStaticBindings = (sourceFile: ts.SourceFile) =>
+    resolveStaticBindings(collectStaticBindingInitializers(sourceFile));
+
+const collectExportedStaticBindingInitializers = (sourceFile: ts.SourceFile) => {
     const bindingInitializers = new Map<string, ts.Expression>();
 
     for (const statement of sourceFile.statements) {
         if (!ts.isVariableStatement(statement)) continue;
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
         if (!(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
 
         for (const declaration of statement.declarationList.declarations) {
@@ -322,6 +457,61 @@ const collectStaticBindingInitializers = (sourceFile: ts.SourceFile) => {
     return bindingInitializers;
 };
 
+const collectImportedStaticBindingInitializers = (
+    sourceFile: ts.SourceFile,
+    visitedFiles = new Set<string>([normalizeFilepath(sourceFile.fileName)]),
+) => {
+    const bindingInitializers = new Map<string, ts.Expression>();
+
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+
+        const namedBindings = statement.importClause?.namedBindings;
+        if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
+
+        const importedFilepath = resolveStaticImportFilepath(sourceFile, statement.moduleSpecifier.text);
+        if (!importedFilepath) continue;
+
+        const normalizedImportFilepath = normalizeFilepath(importedFilepath);
+        if (visitedFiles.has(normalizedImportFilepath)) continue;
+
+        const importedSourceFile = readStaticImportSourceFile(normalizedImportFilepath);
+        if (!importedSourceFile) continue;
+
+        const exportedInitializers = collectExportedStaticBindingInitializers(importedSourceFile);
+        for (const element of namedBindings.elements) {
+            const importedName = element.propertyName?.text || element.name.text;
+            const initializer = exportedInitializers.get(importedName);
+            if (!initializer) continue;
+
+            bindingInitializers.set(element.name.text, initializer);
+        }
+    }
+
+    return bindingInitializers;
+};
+
+const collectStatementStaticBindingInitializers = (
+    statements: readonly ts.Statement[],
+    bindingInitializers = new Map<string, ts.Expression>(),
+) => {
+    for (const statement of statements) {
+        if (!ts.isVariableStatement(statement)) continue;
+        if (!(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
+
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
+
+            bindingInitializers.set(declaration.name.text, declaration.initializer);
+        }
+    }
+
+    return bindingInitializers;
+};
+
+const collectStaticBindingInitializers = (sourceFile: ts.SourceFile) =>
+    collectStatementStaticBindingInitializers(sourceFile.statements, collectImportedStaticBindingInitializers(sourceFile));
+
 const getPropertyAssignment = (node: ts.ObjectLiteralExpression, propertyName: string) => {
     for (const property of node.properties) {
         if (!ts.isPropertyAssignment(property)) continue;
@@ -339,15 +529,42 @@ const getCallExpressionName = (node: ts.Expression) => {
     return undefined;
 };
 
+const collectServerRouteDefinitionExpressions = (routesArg: ts.Expression | undefined) => {
+    if (!routesArg) return undefined;
+
+    if (ts.isArrayLiteralExpression(routesArg)) return [...routesArg.elements];
+
+    if (!(ts.isArrowFunction(routesArg) || ts.isFunctionExpression(routesArg))) return undefined;
+
+    if (ts.isArrayLiteralExpression(routesArg.body)) return [...routesArg.body.elements];
+    if (!ts.isBlock(routesArg.body)) return undefined;
+
+    const routeExpressions: ts.Expression[] = [];
+
+    for (const statement of routesArg.body.statements) {
+        if (!ts.isExpressionStatement(statement)) continue;
+        if (!ts.isCallExpression(statement.expression)) continue;
+        if (!ts.isPropertyAccessExpression(statement.expression.expression)) continue;
+        if (statement.expression.expression.name.text !== 'push') continue;
+
+        for (const argument of statement.expression.arguments) {
+            const unwrappedArgument = unwrapStaticExpression(argument);
+            if (!ts.isCallExpression(unwrappedArgument)) continue;
+
+            const helperName = getCallExpressionName(unwrappedArgument.expression);
+            if (helperName === 'defineServerRoute') routeExpressions.push(unwrappedArgument);
+        }
+    }
+
+    return routeExpressions.length > 0 ? routeExpressions : undefined;
+};
+
 const resolveIdentifierExpression = (
     expression: ts.Expression,
     sourceFile: ts.SourceFile,
 ): ts.Expression => {
-    const unwrapped = unwrapStaticExpression(expression);
-    if (!ts.isIdentifier(unwrapped)) return unwrapped;
-
     const bindingInitializers = collectStaticBindingInitializers(sourceFile);
-    return bindingInitializers.get(unwrapped.text) || unwrapped;
+    return resolveStaticExpressionNode(expression, bindingInitializers);
 };
 
 const getDefaultRouteDefinitionExpression = (sourceFile: ts.SourceFile) => {
@@ -402,10 +619,11 @@ const parseExplicitRouteCall = (
     sourceFile: ts.SourceFile,
     side: TRouteSide,
     node: ts.Expression,
+    scopedStaticBindingInitializers?: Map<string, ts.Expression>,
 ): TExplicitRouteDefinition[] => {
     const expression = unwrapStaticExpression(resolveIdentifierExpression(node, sourceFile));
-    const staticBindingInitializers = collectStaticBindingInitializers(sourceFile);
-    const staticBindings = collectStaticBindings(sourceFile);
+    const staticBindingInitializers = scopedStaticBindingInitializers || collectStaticBindingInitializers(sourceFile);
+    const staticBindings = resolveStaticBindings(staticBindingInitializers);
 
     if (!ts.isCallExpression(expression)) {
         throw new Error(`Route module ${sourceFile.fileName} must default-export a define*Route(...) call.`);
@@ -422,20 +640,19 @@ const parseExplicitRouteCall = (
         }
 
         const [routesArg] = [...expression.arguments];
-        const routeListExpression =
-            routesArg && ts.isArrayLiteralExpression(routesArg)
-                ? routesArg
-                : routesArg &&
-                    (ts.isArrowFunction(routesArg) || ts.isFunctionExpression(routesArg)) &&
-                    ts.isArrayLiteralExpression(routesArg.body)
-                  ? routesArg.body
-                  : undefined;
-
-        if (!routeListExpression) {
-            throw new Error(`defineServerRoutes(...) in ${sourceFile.fileName} must receive a static array literal or a factory returning one.`);
+        const routeExpressions = collectServerRouteDefinitionExpressions(routesArg);
+        const routeBindingInitializers =
+            routesArg && (ts.isArrowFunction(routesArg) || ts.isFunctionExpression(routesArg)) && ts.isBlock(routesArg.body)
+                ? collectStatementStaticBindingInitializers(routesArg.body.statements, new Map(staticBindingInitializers))
+                : staticBindingInitializers;
+
+        if (!routeExpressions) {
+            throw new Error(
+                `defineServerRoutes(...) in ${sourceFile.fileName} must receive a static array literal, a factory returning one, or a factory that pushes defineServerRoute(...) entries into a local routes array.`,
+            );
         }
 
-        return routeListExpression.elements.map((element) => parseExplicitRouteCall(sourceFile, side, element)).flat();
+        return routeExpressions.map((element) => parseExplicitRouteCall(sourceFile, side, element, routeBindingInitializers)).flat();
     }
 
     const [definitionArg] = [...expression.arguments];
@@ -446,7 +663,7 @@ const parseExplicitRouteCall = (
     const sourceLocation = getNodeLocation(sourceFile, expression);
     const optionsExpression = getPropertyAssignment(definitionArg, 'options');
     const resolvedOptionsExpression = optionsExpression
-        ? unwrapStaticExpression(resolveIdentifierExpression(optionsExpression, sourceFile))
+        ? unwrapStaticExpression(resolveStaticExpressionNode(optionsExpression, staticBindingInitializers))
         : undefined;
     const optionsArg =
         resolvedOptionsExpression && ts.isObjectLiteralExpression(resolvedOptionsExpression)

package/cli/presentation/commands.ts

@@ -116,7 +116,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure tracked Proteum instruction files for a standalone app or monorepo app root.',
+        summary: 'Interactively configure tracked Proteum instruction files and Claude aliases for an app.',
         usage: 'proteum configure agents',
         bestFor:
             'Creating or switching the tracked instruction layout intentionally while keeping Proteum-owned instructions embedded in managed sections.',
@@ -128,8 +128,9 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root instruction files.',
-            'Standalone mode writes tracked instruction files into the current Proteum app root.',
+            'Standalone mode writes tracked instruction files into the current Proteum app root and creates `CLAUDE.md` symlinks beside each `AGENTS.md`.',
             'Monorepo mode writes reusable root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
+            'Every generated `CLAUDE.md` is a sibling symlink pointing to `AGENTS.md`.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],
@@ -612,10 +613,18 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'verify',
         category: 'Manifest and contracts',
         summary: 'Run focused owner/request/browser verification or the full framework reference-app validation pass.',
-        usage: 'proteum verify [framework-change|owner <query>|request <path>|browser <path>] [--port <port>|--url <baseUrl>] [--session-email <email>] [--session-role <role>] [--method <verb>] [--data-json <json>] [--strict-global] [--crosspath <path>] [--product <path>] [--website <path>] [--crosspath-port <port>] [--product-port <port>] [--website-port <port>] [--route <path>] [--json]',
+        usage: 'proteum verify [changed|framework-change|owner <query>|request <path>|browser <path>] [--staged] [--base <ref>] [--dry-run] [--port <port>|--url <baseUrl>] [--session-email <email>] [--session-role <role>] [--method <verb>] [--data-json <json>] [--strict-global] [--crosspath <path>] [--product <path>] [--website <path>] [--crosspath-port <port>] [--product-port <port>] [--website-port <port>] [--route <path>] [--json]',
         bestFor:
             'Choosing the smallest trustworthy verification surface first, then separating introduced blocking findings from unrelated pre-existing diagnostics.',
         examples: [
+            {
+                description: 'Plan targeted checks for changed files without running them',
+                command: 'proteum verify changed --dry-run',
+            },
+            {
+                description: 'Run targeted checks for staged changes only',
+                command: 'proteum verify changed --staged',
+            },
             {
                 description: 'Run the default framework smoke verification against the reference apps',
                 command: 'proteum verify framework-change',
@@ -638,6 +647,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             },
         ],
         notes: [
+            '`proteum verify changed` reads optional `proteum.verify.config.ts`, combines changed-file detection with built-in Vitest defaults, prints the selected plan, then runs every selected check.',
+            '`proteum verify changed --dry-run --json` is the safest agent entrypoint when you need to inspect selected checks without changing cache or test artifacts.',
             '`proteum verify owner` starts from `proteum orient`, then chooses the smallest trustworthy verify path instead of defaulting to broad global checks.',
             '`proteum verify owner`, `request`, and `browser` emit `introducedFindings`, `preExistingFindings`, `verificationSteps`, and `result` in JSON.',
             'Focused verification fails on introduced blocking findings by default and only fails on unrelated pre-existing blockers when `--strict-global` is passed.',

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/runtime/commands.ts

@@ -846,6 +846,8 @@ class VerifyCommand extends ProteumCommand {
 
     public static usage = buildUsage('verify');
 
+    public base = Option.String('--base', { description: 'Base ref used by `proteum verify changed`.' });
+    public dryRun = Option.Boolean('--dry-run', false, { description: 'Print the changed-file verification plan without running checks.' });
     public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
     public port = Option.String('--port', { description: 'Target an existing dev server on the given port for focused verify actions.' });
     public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL for focused verify actions.' });
@@ -869,6 +871,7 @@ class VerifyCommand extends ProteumCommand {
         description: 'Port used for the Unique Domains Website validation server.',
     });
     public route = Option.String('--route', { description: 'Route loaded in both apps during validation.' });
+    public staged = Option.Boolean('--staged', false, { description: 'Verify staged changes only.' });
     public args = Option.Rest();
 
     public async execute() {
@@ -877,9 +880,11 @@ class VerifyCommand extends ProteumCommand {
 
         this.setCliArgs({
             action,
+            base: this.base ?? '',
             crosspath: this.crosspath ?? '',
             crosspathPort: this.crosspathPort ?? '',
             dataJson: this.dataJson ?? '',
+            dryRun: this.dryRun,
             json: this.json,
             method: this.method ?? '',
             port: this.port ?? '',
@@ -888,6 +893,7 @@ class VerifyCommand extends ProteumCommand {
             route: this.route ?? '',
             sessionEmail: this.sessionEmail ?? '',
             sessionRole: this.sessionRole ?? '',
+            staged: this.staged,
             strictGlobal: this.strictGlobal,
             target,
             url: this.url ?? '',

package/cli/scaffold/templates.ts

@@ -53,7 +53,7 @@ export const createControllerTemplate = ({
     appIdentifier: string;
     className: string;
     methodName: string;
-}) => `import { defineAction, defineController } from '@server/app/controller';
+}) => `import { defineAction, defineController } from '@generated/server/controller';
 
 export default defineController({
     actions: {
@@ -75,7 +75,9 @@ export const createCommandTemplate = ({
     className: string;
     methodName: string;
 }) => `import { Commands } from '@server/app/commands';
-import type App from '@/server/index';
+import type AppApplication from '@/server/index';
+
+type App = InstanceType<typeof AppApplication>;
 
 export default class ${className} extends Commands<App> {
     public async ${methodName}() {
@@ -171,7 +173,9 @@ import SchemaRouter from '@server/services/schema/router';
 
 import * as appConfig from '@/server/config/app';
 
-export default defineApplication({
+export type TControllerRequestServices = {};
+
+const ${_args.appIdentifier}Application = defineApplication({
     services: () => ({}),
     router: (app) =>
         new Router(
@@ -185,6 +189,10 @@ export default defineApplication({
             app,
         ),
 });
+
+export type ${_args.appIdentifier} = InstanceType<typeof ${_args.appIdentifier}Application>;
+
+export default ${_args.appIdentifier}Application;
 `;
 
 export const createClientTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `{