proteum 2.1.3-1 → 2.1.6

package/cli/compiler/common/generatedRouteModules.ts

@@ -36,7 +36,7 @@ export type TIndexedRouteDefinition = {
     hasSetup: boolean;
 };
 
-type TGeneratedClientRouteModuleOptions = { chunkId: string; filepath: string };
+type TGeneratedClientRouteModuleOptions = { chunkId: string };
 
 type TWriteGeneratedRouteModuleOptions = {
     outputFilepath: string;
@@ -222,6 +222,9 @@ const getRouteOptionMetadata = (node: ts.ObjectLiteralExpression | undefined) =>
     return { optionKeys, normalizedOptionKeys, invalidOptionKeys, reservedOptionKeys };
 };
 
+const buildInjectedRouteMetadata = (sourceFilepath: string, sourceLocation: TIndexedSourceLocation, extra: string[] = []) =>
+    `{ filepath: ${JSON.stringify(normalizeFilepath(sourceFilepath))}, sourceLocation: { line: ${sourceLocation.line}, column: ${sourceLocation.column} }${extra.length > 0 ? `, ${extra.join(', ')}` : ''} }`;
+
 const routeModuleExtensions = ['.ts', '.tsx', '.js', '.jsx'];
 
 const resolveRouteImport = (sourceFilepath: string, moduleSpecifier: string, routeSourceFilepaths?: Set<string>) => {
@@ -467,7 +470,10 @@ const buildClientRegisterArgs = (
     clientRoute: TGeneratedClientRouteModuleOptions,
 ) => {
     const { optionsArg, setupArg, renderArg } = getClientRouteSignature(sourceFile, definition);
-    const injectedOptions = `{ id: ${JSON.stringify(clientRoute.chunkId)}, filepath: ${JSON.stringify(clientRoute.filepath)} }`;
+    const sourceLocation = getNodeLocation(sourceFile, definition.callExpression);
+    const injectedOptions = buildInjectedRouteMetadata(sourceFile.fileName, sourceLocation, [
+        `id: ${JSON.stringify(clientRoute.chunkId)}`,
+    ]);
 
     if (!optionsArg && !setupArg) {
         return [injectedOptions, getNodeText(sourceFile, renderArg)];
@@ -475,7 +481,7 @@ const buildClientRegisterArgs = (
 
     if (optionsArg && !setupArg) {
         return [
-            `{ ...(${getNodeText(sourceFile, optionsArg)}), id: ${JSON.stringify(clientRoute.chunkId)}, filepath: ${JSON.stringify(clientRoute.filepath)} }`,
+            `{ ...(${getNodeText(sourceFile, optionsArg)}), ...${injectedOptions} }`,
             getNodeText(sourceFile, renderArg),
         ];
     }
@@ -485,12 +491,35 @@ const buildClientRegisterArgs = (
     }
 
     return [
-        `{ ...(${getNodeText(sourceFile, optionsArg!)}), id: ${JSON.stringify(clientRoute.chunkId)}, filepath: ${JSON.stringify(clientRoute.filepath)} }`,
+        `{ ...(${getNodeText(sourceFile, optionsArg!)}), ...${injectedOptions} }`,
         getNodeText(sourceFile, setupArg!),
         getNodeText(sourceFile, renderArg),
     ];
 };
 
+const buildServerRegisterArgs = (sourceFile: ts.SourceFile, definition: TRouteDefinition) => {
+    const sourceLocation = getNodeLocation(sourceFile, definition.callExpression);
+    const [targetArg, ...routeArgs] = [...definition.args];
+    const controllerArg = routeArgs[routeArgs.length - 1];
+    const optionsArg =
+        routeArgs.length >= 2 && ts.isObjectLiteralExpression(routeArgs[0]) ? routeArgs[0] : undefined;
+    const injectedOptions = buildInjectedRouteMetadata(sourceFile.fileName, sourceLocation);
+
+    if (routeArgs.length === 1) {
+        return [getNodeText(sourceFile, targetArg), injectedOptions, getNodeText(sourceFile, controllerArg)];
+    }
+
+    if (optionsArg) {
+        return [
+            getNodeText(sourceFile, targetArg),
+            `{ ...(${getNodeText(sourceFile, optionsArg)}), ...${injectedOptions} }`,
+            getNodeText(sourceFile, controllerArg),
+        ];
+    }
+
+    return [getNodeText(sourceFile, targetArg), ...routeArgs.map((arg) => getNodeText(sourceFile, arg))];
+};
+
 const buildRegisterStatements = (
     sourceFile: ts.SourceFile,
     side: TRouteSide,
@@ -519,7 +548,7 @@ const buildRegisterStatements = (
     }
 
     return definitions.map((definition) => {
-        const args = [...definition.args].map((arg) => getNodeText(sourceFile, arg));
+        const args = buildServerRegisterArgs(sourceFile, definition);
 
         return `${definition.serviceLocalName}.${definition.methodName}(${args.join(', ')});`;
     });

package/cli/compiler/common/scripts.ts

@@ -3,24 +3,30 @@ import type { RuleSetRule } from '@rspack/core';
 
 type TScriptRuleOptions = { app: App; side: TAppSide; dev: boolean };
 
-const shouldExcludeNodeModule = (filePath: string) => {
-    if (!filePath.includes('node_modules')) return false;
+const shouldExcludeNodeModule = (app: App, filePath: string) => {
+    const normalizedFilePath = filePath.replace(/\\/g, '/');
+    if (!normalizedFilePath.includes('/node_modules/')) return false;
 
-    if (filePath.includes('node_modules/proteum') && !filePath.includes('node_modules/proteum/node_modules')) {
+    if (
+        normalizedFilePath.includes('/node_modules/proteum/') &&
+        !normalizedFilePath.includes('/node_modules/proteum/node_modules/')
+    ) {
         return false;
     }
 
+    if (app.isTranspileModuleFile(normalizedFilePath)) return false;
+
     return true;
 };
 
 const getSwcTarget = (side: TAppSide) => (side === 'client' ? 'es2022' : 'es2021');
 
-module.exports = ({ side, dev }: TScriptRuleOptions): RuleSetRule[] => {
+module.exports = ({ app, side, dev }: TScriptRuleOptions): RuleSetRule[] => {
     return [
         {
             loader: 'builtin:swc-loader',
             type: 'javascript/auto',
-            exclude: shouldExcludeNodeModule,
+            exclude: (filePath: string) => shouldExcludeNodeModule(app, filePath),
             options: {
                 sourceMaps: true,
                 jsc: {

package/cli/compiler/index.ts

@@ -141,12 +141,13 @@ export default class Compiler {
         if (!this.refreshingGeneratedArtifacts) {
             this.refreshingGeneratedArtifacts = (async () => {
                 const services = generateServiceArtifacts();
-                const controllers = generateControllerArtifacts();
+                const { connectedProjects, controllers } = await generateControllerArtifacts();
                 const commands = generateCommandArtifacts();
                 const { clientRoutes, serverRoutes, layouts } = generateRoutingArtifacts();
 
                 writeCurrentProteumManifest({
                     services,
+                    connectedProjects,
                     controllers,
                     commands,
                     routes: { client: clientRoutes, server: serverRoutes },

package/cli/compiler/server/index.ts

@@ -82,6 +82,7 @@ export default function createCompiler(
     const outputPath = app.outputPath(outputTarget);
     const installedCoreRoot = app.paths.root + '/node_modules/proteum';
     const frameworkRoots = [cli.paths.core.root, installedCoreRoot];
+    const transpileModuleDirectories = app.transpileModuleDirectories;
 
     const commonConfig = createCommonConfig(app, 'server', mode, outputTarget);
     const { aliases } = app.aliases.server.forWebpack({ modulesPath: app.paths.root + '/node_modules' });
@@ -140,6 +141,7 @@ export default function createCompiler(
                         // Aliased modules
                         app.aliases.server.containsAlias(request) ||
                         // TODO: proteum.conf: compile: include
+                        app.isTranspileModuleRequest(request) ||
                         // Compile proteum modules
                         request.startsWith('proteum') ||
                         // React-based UI packages must pass through the alias layer on the server,
@@ -193,6 +195,7 @@ export default function createCompiler(
                         ...frameworkRoots.map((rootPath) => rootPath + '/client'),
                         ...frameworkRoots.map((rootPath) => rootPath + '/common'),
                         ...frameworkRoots.map((rootPath) => rootPath + '/server'),
+                        ...transpileModuleDirectories,
 
                         // Complle 5HTP modules so they can refer to the framework instance and aliases
                         // Temp disabled because compile issue on vercel

package/cli/presentation/commands.ts

@@ -12,11 +12,15 @@ export const proteumCommandNames = [
     'typecheck',
     'lint',
     'check',
+    'connect',
     'doctor',
     'explain',
+    'diagnose',
+    'perf',
     'trace',
     'command',
     'session',
+    'verify',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -49,7 +53,7 @@ export const proteumRecommendedFlow: TRow[] = [
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
-    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command', 'session'] },
+    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'diagnose', 'perf', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'create'] },
 ];
 
@@ -97,7 +101,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'Page scaffolds write `client/pages/**/index.tsx` and default the route path from the logical target path unless `--route` is provided.',
-            'Service scaffolds create `server/services/**/index.ts`, `service.json`, a config export under `server/config/*.ts`, and then try to register the new root service in `server/index.ts`.',
+            'Service scaffolds create `server/services/**/index.ts`, a typed config export under `server/config/*.ts`, and then try to register the new root service in `server/index.ts`.',
             'Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.',
         ],
         status: 'experimental',
@@ -190,26 +194,47 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: ['This command executes refresh, typecheck, then lint in that order.'],
         status: 'stable',
     },
+    connect: {
+        name: 'connect',
+        category: 'Manifest and contracts',
+        summary: 'Inspect connected-project config, cached contracts, and imported controllers.',
+        usage: 'proteum connect [--controllers] [--json] [--strict]',
+        bestFor:
+            'Auditing the current app connect setup without manually stitching together refresh, explain, env inspection, and contract checks.',
+        examples: [
+            { description: 'Print a human-readable connected-project summary', command: 'proteum connect' },
+            { description: 'Include imported connected controllers', command: 'proteum connect --controllers' },
+            { description: 'Emit machine-readable connect output', command: 'proteum connect --json' },
+            { description: 'Fail when connect diagnostics exist', command: 'proteum connect --strict' },
+        ],
+        notes: [
+            'Proteum refreshes generated typings before reading the connect manifest state.',
+            'This command inspects explicit `proteum.config.ts` connected sources and URLs, cached `.proteum/connected/*.json` files, and imported connected controllers.',
+            '`--strict` is intended for CI or framework validation when connected contracts must be present and usable.',
+        ],
+        status: 'stable',
+    },
     doctor: {
         name: 'doctor',
         category: 'Manifest and contracts',
         summary: 'Inspect the generated Proteum manifest diagnostics.',
-        usage: 'proteum doctor [--json] [--strict]',
+        usage: 'proteum doctor [--contracts] [--json] [--strict]',
         bestFor:
             'Auditing manifest warnings and errors, especially in CI or when route/controller generation behaves unexpectedly.',
         examples: [
             { description: 'Print a human-readable diagnostic summary', command: 'proteum doctor' },
+            { description: 'Inspect missing generated contracts and source files', command: 'proteum doctor --contracts' },
             { description: 'Fail if any diagnostics exist', command: 'proteum doctor --strict' },
             { description: 'Emit machine-readable diagnostics', command: 'proteum doctor --json' },
         ],
-        notes: ['`--strict` is intended for CI and pre-release verification.'],
+        notes: ['`--strict` is intended for CI and pre-release verification.', '`--contracts` checks manifest-owned source files and expected generated artifacts on disk.'],
         status: 'stable',
     },
     explain: {
         name: 'explain',
         category: 'Manifest and contracts',
         summary: 'Explain the generated Proteum manifest.',
-        usage: 'proteum explain [--all|--app|--conventions|--env|--services|--controllers|--commands|--routes|--layouts|--diagnostics] [--json]',
+        usage: 'proteum explain [owner <query>] [--all|--app|--conventions|--env|--connected|--services|--controllers|--commands|--routes|--layouts|--diagnostics] [--json]',
         bestFor:
             'Inspecting how source files became generated routes, controllers, commands, layouts, services, and diagnostics without reading compiler internals.',
         examples: [
@@ -218,11 +243,64 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 description: 'Inspect generated routes, controllers, and commands together',
                 command: 'proteum explain --routes --controllers --commands',
             },
+            {
+                description: 'Inspect configured connected projects and imported controllers',
+                command: 'proteum explain --connected --controllers',
+            },
+            { description: 'Resolve the most likely manifest owner for a path or file', command: 'proteum explain owner /api/Auth/CurrentUser' },
             { description: 'Emit the selected manifest sections as JSON', command: 'proteum explain --routes --json' },
         ],
-        notes: ['Legacy positional section selection remains supported, for example `proteum explain routes services`.'],
+        notes: [
+            'Legacy positional section selection remains supported, for example `proteum explain routes services`.',
+            '`proteum explain owner <query>` ranks matching routes, controllers, services, commands, layouts, and diagnostics from the manifest.',
+            'Connected projects are emitted from explicit `proteum.config.ts` `connect.<Namespace>.*` values plus the resolved connected contract.',
+        ],
         status: 'stable',
     },
+    diagnose: {
+        name: 'diagnose',
+        category: 'Manifest and contracts',
+        summary: 'Combine owner lookup, doctor output, contract checks, traces, and server logs into one report.',
+        usage: 'proteum diagnose [<query>] [--hit <path>] [--method <verb>] [--data-json <json>] [--session-email <email>] [--session-role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Collapsing the usual explain + doctor + trace + session + server log loop into one structured debugging pass.',
+        examples: [
+            { description: 'Diagnose the latest matching route trace on the running dev server', command: 'proteum diagnose /domains' },
+            { description: 'Arm a deep trace, mint an admin session, hit a protected page once, then diagnose it', command: 'proteum diagnose /godmode/users --hit /godmode/users --session-email god@example.com --session-role GOD' },
+            { description: 'Diagnose an API call with a JSON payload', command: 'proteum diagnose /api/Auth/CurrentUser --hit /api/Auth/CurrentUser --method POST --data-json "{}"' },
+        ],
+        notes: [
+            'This command talks to the running app over the dev-only diagnostics, trace, and session endpoints.',
+            'When `--hit` is omitted, Proteum diagnoses the latest matching request trace if one already exists.',
+        ],
+        status: 'experimental',
+    },
+    perf: {
+        name: 'perf',
+        category: 'Manifest and contracts',
+        summary: 'Inspect shared performance rollups built from live request traces on a running Proteum dev server.',
+        usage: 'proteum perf [top|request <requestId|path>|compare|memory] [--since <window>] [--baseline <window>] [--target <window>] [--group-by <path|route|controller>] [--limit <n>] [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Finding the routes or controllers with the biggest response-time, CPU, SQL, render, and memory impact without manually stitching traces together.',
+        examples: [
+            { description: 'Show the hottest paths for the current day', command: 'proteum perf top --since today' },
+            { description: 'Inspect one traced request or the latest request for a path', command: 'proteum perf request /domains' },
+            {
+                description: 'Compare today against yesterday by route',
+                command: 'proteum perf compare --baseline yesterday --target today --group-by route',
+            },
+            {
+                description: 'Rank memory growth by controller over the last hour',
+                command: 'proteum perf memory --since 1h --group-by controller',
+            },
+        ],
+        notes: [
+            'Perf data is derived from the same dev-only request trace buffer used by `proteum trace` and the profiler.',
+            'Window values accept `1h`, `6h`, `24h`, `today`, `yesterday`, or an ISO timestamp.',
+            'Older traces captured before the perf runtime metrics were added may not include CPU or memory deltas.',
+        ],
+        status: 'experimental',
+    },
     trace: {
         name: 'trace',
         category: 'Manifest and contracts',
@@ -300,11 +378,36 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
+    verify: {
+        name: 'verify',
+        category: 'Manifest and contracts',
+        summary: 'Validate framework changes against CrossPath, Unique Domains Product, and Unique Domains Website.',
+        usage: 'proteum verify [framework-change] [--crosspath <path>] [--product <path>] [--website <path>] [--crosspath-port <port>] [--product-port <port>] [--website-port <port>] [--route <path>] [--json]',
+        bestFor:
+            'Framework-repo smoke validation when Proteum changes must be exercised against CrossPath and the website -> product connected-project flow before review.',
+        examples: [
+            {
+                description: 'Run the default framework smoke verification against the reference apps',
+                command: 'proteum verify framework-change',
+            },
+            {
+                description: 'Load a specific route in the website validation pass',
+                command: 'proteum verify framework-change --route /domains',
+            },
+        ],
+        notes: [
+            'When a reference app is already running on the requested port, Proteum reuses it instead of spawning a new `proteum dev` process.',
+            'When Proteum spawns the website reference app, it sets the env values consumed by the website `proteum.config.ts` for the product internal and public URLs.',
+            'This command is intended for the framework repo and will be most useful where the reference app paths exist locally.',
+        ],
+        status: 'experimental',
+    },
 };
 
 export const isLikelyProteumAppRoot = (workdir: string) =>
     fs.existsSync(path.join(workdir, 'package.json')) &&
-    fs.existsSync(path.join(workdir, 'identity.yaml')) &&
+    fs.existsSync(path.join(workdir, 'identity.config.ts')) &&
+    fs.existsSync(path.join(workdir, 'proteum.config.ts')) &&
     fs.existsSync(path.join(workdir, 'client')) &&
     fs.existsSync(path.join(workdir, 'server'));
 

package/cli/presentation/devSession.ts

@@ -18,24 +18,30 @@ export const renderDevSession = async ({
     appRoot,
     routerPort,
     devEventPort,
+    connectedProjects,
+    proteumVersion,
 }: {
     appName: string;
     appRoot: string;
     routerPort: number;
     devEventPort: number;
+    connectedProjects?: Array<{ namespace: string; urlInternal: string }>;
+    proteumVersion: string;
 }) =>
     [
         await renderInk(({ Box, Text }) => {
             const createElement = React.createElement;
             const wordmark = ProteumWordmark.map((line) =>
-                createElement(Text, { key: line, bold: true, color: 'cyan' }, line),
+                createElement(Text, { key: line, bold: true, color: 'blue' }, line),
             );
+            const versionLabel = proteumVersion ? `v${proteumVersion}` : '';
 
             return createElement(
                 Box,
-                { borderStyle: 'round', borderColor: 'cyan', paddingX: 2, paddingY: 0, flexDirection: 'column' },
-                createElement(Text, { bold: true, backgroundColor: 'cyan', color: 'black' }, ' WELCOME TO '),
+                { borderStyle: 'round', borderColor: 'blue', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+                createElement(Text, { bold: true, backgroundColor: 'blue', color: 'white' }, ' WELCOME TO '),
                 createElement(Box, { flexDirection: 'column' }, ...wordmark),
+                versionLabel ? createElement(Text, { bold: true, color: 'blue' }, versionLabel) : null,
                 createElement(Text, { dimColor: true }, ProteumTagline),
             );
         }),
@@ -45,6 +51,14 @@ export const renderDevSession = async ({
                 { label: 'root', value: appRoot },
                 { label: 'router', value: `http://localhost:${routerPort}` },
                 { label: 'hmr', value: `http://localhost:${devEventPort}/__proteum_hmr` },
+                ...(connectedProjects && connectedProjects.length > 0
+                    ? connectedProjects.map((connectedProject) => ({
+                          label: `connect ${connectedProject.namespace}`,
+                          value: connectedProject.urlInternal,
+                      }))
+                    : []),
+                { label: 'diagnose', value: `proteum diagnose / --port ${routerPort}` },
+                { label: 'perf', value: `proteum perf top --port ${routerPort}` },
                 { label: 'trace', value: `proteum trace latest --port ${routerPort}` },
                 { label: 'trace deep', value: `proteum trace arm --capture deep --port ${routerPort}` },
                 { label: 'hotkeys', value: 'Ctrl+R reload, Ctrl+C stop' },
@@ -57,10 +71,12 @@ export const renderServerReadyBanner = async ({
     appName,
     publicUrl,
     routerPort,
+    connectedProjectsCount,
 }: {
     appName: string;
     publicUrl: string;
     routerPort: number;
+    connectedProjectsCount?: number;
 }) =>
     renderInk(({ Box, Text }) => {
         const createElement = React.createElement;
@@ -68,10 +84,19 @@ export const renderServerReadyBanner = async ({
         return createElement(
             Box,
             { borderStyle: 'round', borderColor: 'green', paddingX: 2, paddingY: 0, flexDirection: 'column' },
-            createElement(Text, { bold: true, backgroundColor: 'green', color: 'black' }, ' SERVER READY '),
+            createElement(Text, { bold: true, backgroundColor: 'green', color: 'white' }, ' SERVER READY '),
             createElement(Text, { bold: true, color: 'green' }, appName),
             createElement(Text, { bold: true }, publicUrl),
             createElement(Text, { dimColor: true }, 'SSR server is listening for requests and hot reloads.'),
+            connectedProjectsCount
+                ? createElement(
+                      Text,
+                      { dimColor: true },
+                      `Connected projects: ${connectedProjectsCount}`,
+                  )
+                : null,
+            createElement(Text, { dimColor: true }, `Diagnose /: proteum diagnose / --port ${routerPort}`),
+            createElement(Text, { dimColor: true }, `Perf top: proteum perf top --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),
         );
     });
@@ -82,8 +107,8 @@ export const renderDevShutdownBanner = async () =>
 
         return createElement(
             Box,
-            { borderStyle: 'round', borderColor: 'yellow', paddingX: 2, paddingY: 0, flexDirection: 'column' },
-            createElement(Text, { bold: true, backgroundColor: 'yellow', color: 'black' }, ' SHUTTING DOWN '),
-            createElement(Text, { bold: true, color: 'yellow' }, 'Thank you for developping with Proteum'),
+            { borderStyle: 'round', borderColor: 'blue', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+            createElement(Text, { bold: true, backgroundColor: 'blue', color: 'white' }, ' SHUTTING DOWN '),
+            createElement(Text, { bold: true, color: 'blue' }, 'Thank you for developping with Proteum'),
         );
     });