proteum 2.1.8 → 2.1.9

package/AGENTS.md

@@ -29,17 +29,23 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 - When starting a long-lived reference app dev server for framework work, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
 - Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
 - If the task changed the dev workflow itself, verify the final cleanup path with `npx proteum dev list --json` before finishing.
-- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Output as "Commit message".
+- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Strictly use the Conventional Commits specification:
+```
+Commit message: <type>[optional scope]: <description>
+
+[optional body]
+```
 
 ## Core Changes
 
 - Validate framework changes against the reference apps:
-  - `/Users/gaetan/Desktop/Projets/crosspath/platform`
-  - `/Users/gaetan/Desktop/Projets/unique.domains/product`
-  - `/Users/gaetan/Desktop/Projets/unique.domains/website`
+  - `/Users/gaetan/Desktop/Projets/crosspath/platform`: Standalone app
+  - `/Users/gaetan/Desktop/Projets/unique.domains/platform`: Monorepo including the following apps:
+    - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/product`
+    - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
-- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner, while only `proteum dev` clears the interactive terminal before rendering and exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI.
+- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method, while only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.

package/README.md

@@ -347,7 +347,7 @@ proteum build --prod --analyze
 proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
-Every human-facing Proteum CLI run prints the welcome banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, and its banner exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys.
+Every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys, and prints connected app names plus successful connected `/ping` checks in the server-ready banner.
 
 Useful inspection commands:
 

package/agents/project/AGENTS.md

@@ -19,11 +19,16 @@ Coding style source of truth: project-root `CODING_STYLE.md`.
 - When starting a long-lived dev server for an agent task, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
 - Do not start a second `proteum dev` server for the same app and port until the earlier tracked session has been stopped or replaced.
 - When framework work changes Proteum CLI commands, profiler panels/features, or the `proteum dev` banners, keep this file, project-root `diagnostics.md`, and any narrower area `AGENTS.md` that mentions the same workflow aligned with the live framework behavior in the same pass.
-- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner, while only `proteum dev` clears the interactive terminal before rendering and exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI.
+- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner and includes the active Proteum installation method, while only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
 - Before finishing, double-check the touched files and generated output against the applicable optimization, diagnostics, and coding-style sources: project-root `optimizations.md`, project-root `diagnostics.md`, project-root `CODING_STYLE.md`, and any narrower area `AGENTS.md`.
 - After implementing any feature or behavior change, always verify it on a running app before finishing: start the server, exercise the affected flow with Playwright or the smallest real runtime or `npx proteum` surface, run the relevant diagnostics or perf commands, and confirm there is no meaningful regression in behavior, performance, bundle/load size, SEO output, or coding style.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
-- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence ALL the changes you made since the beginning of the WHOLE conversation. Output as "Commit message".
+- When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Strictly use the Conventional Commits specification:
+```
+Commit message: <type>[optional scope]: <description>
+
+[optional body]
+```
 
 ## Project Shape
 

package/agents/project/diagnostics.md

@@ -13,7 +13,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 ## Runtime Diagnostics
 
 - For long-lived dev reproductions, start the app with `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically after the repro.
-- Human-facing Proteum CLI runs now print the welcome banner, but only `npx proteum dev` clears the interactive terminal before rendering; keep that in mind when capturing or comparing command logs during diagnosis.
+- Human-facing Proteum CLI runs now print the welcome banner and include the active Proteum installation method, but only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis.
 - For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
 - For connected-project failures, confirm the consumer app resolves the expected `connect.<Namespace>.source` and `connect.<Namespace>.urlInternal` values, the producer app exposes `GET /api/__proteum/connected/ping`, and the imported controller entries show `scope=connected` in `proteum explain`.
 - Use `npx proteum explain owner <query>` when you need a fast ownership graph for a route, controller path, source file, or generated artifact before reading code.

package/cli/app/index.ts

@@ -38,16 +38,16 @@ const normalizeModulePath = (value: string) => value.replace(/\\/g, '/').replace
 
 const resolveTranspileModuleDirectories = ({
     moduleNames,
-    searchRoots,
+    nodeModulesRoots,
 }: {
     moduleNames: string[];
-    searchRoots: string[];
+    nodeModulesRoots: string[];
 }) => {
     const directories = new Set<string>();
 
     for (const moduleName of moduleNames) {
-        for (const searchRoot of searchRoots) {
-            const candidate = normalizeModulePath(path.join(searchRoot, 'node_modules', moduleName));
+        for (const nodeModulesRoot of nodeModulesRoots) {
+            const candidate = normalizeModulePath(path.join(nodeModulesRoot, moduleName));
             if (!fs.existsSync(candidate)) continue;
 
             directories.add(candidate);
@@ -136,7 +136,7 @@ export class App {
     public get transpileModuleDirectories() {
         return resolveTranspileModuleDirectories({
             moduleNames: this.transpile,
-            searchRoots: [this.paths.root, cli.paths.core.root],
+            nodeModulesRoots: [cli.paths.framework.appNodeModulesRoot, cli.paths.framework.frameworkNodeModulesRoot],
         });
     }
 
@@ -161,12 +161,12 @@ export class App {
     public aliases = {
         client: new TsAlias({
             rootDir: this.paths.root + '/client',
-            modulesDir: [cli.paths.appRoot + '/node_modules', cli.paths.coreRoot + '/node_modules'],
+            modulesDir: [cli.paths.framework.appNodeModulesRoot, cli.paths.framework.frameworkNodeModulesRoot],
             debug: false,
         }),
         server: new TsAlias({
             rootDir: this.paths.root + '/server',
-            modulesDir: [cli.paths.appRoot + '/node_modules', cli.paths.coreRoot + '/node_modules'],
+            modulesDir: [cli.paths.framework.appNodeModulesRoot, cli.paths.framework.frameworkNodeModulesRoot],
             debug: false,
         }),
     };

package/cli/commands/dev.ts

@@ -36,6 +36,7 @@ import {
     type TDevSessionInspection,
     type TStopDevSessionResult,
 } from '../runtime/devSessions';
+import { resolveFrameworkInstallInfo } from '../paths';
 import { logVerbose } from '../runtime/verbose';
 
 // Core
@@ -396,7 +397,7 @@ async function startApp(app: App) {
                     console.info(
                         await renderServerReadyBanner({
                             appName: getDevAppName(app),
-                            connectedProjectsCount: Object.keys(app.env.connectedProjects).length,
+                            connectedProjects: message.connectedProjects,
                             publicUrl: message.publicUrl,
                             routerPort: app.env.router.port,
                         }),
@@ -558,6 +559,10 @@ const runDevLoop = async () => {
     clearInteractiveConsole();
     ensureProjectAgentSymlinks({ appRoot: app.paths.root, coreRoot: cli.paths.core.root });
     await ensureDevSessionSlot();
+    const proteumInstall = resolveFrameworkInstallInfo({
+        appRoot: app.paths.root,
+        framework: cli.paths.framework,
+    });
 
     const devEventServer = await createDevEventServer(app.env.router.port + 1);
     app.devEventPort = devEventServer.port;
@@ -568,6 +573,7 @@ const runDevLoop = async () => {
             connectedProjects: Object.values(app.env.connectedProjects),
             routerPort: app.env.router.port,
             devEventPort: devEventServer.port,
+            proteumInstallSummary: proteumInstall.summary,
             proteumVersion: String(cli.packageJson.version || ''),
         }),
     );

package/cli/compiler/artifacts/commands.ts

@@ -22,8 +22,15 @@ const readServerTsconfigPaths = () => {
     return compilerOptions.paths || {};
 };
 
-const createCommandsTsconfigContent = () =>
-    `${JSON.stringify(
+const getCommandsTsconfigFilepath = () => path.join(app.paths.root, 'commands', 'tsconfig.json');
+
+const getCommandsGlobalTypesPath = (commandsTsconfigFilepath: string) =>
+    cli.paths.relativeFrameworkPathFrom(commandsTsconfigFilepath, 'types', 'global');
+
+const createCommandsTsconfigContent = () => {
+    const commandsTsconfigFilepath = getCommandsTsconfigFilepath();
+
+    return `${JSON.stringify(
         {
             extends: '../server/tsconfig.json',
             compilerOptions: {
@@ -35,12 +42,13 @@ const createCommandsTsconfigContent = () =>
                     '@models/types': ['./.proteum/server/models.ts'],
                 },
             },
-            include: ['.', '../var/typings', '../node_modules/proteum/types/global', '../.proteum/server/commands.d.ts'],
+            include: ['.', '../var/typings', getCommandsGlobalTypesPath(commandsTsconfigFilepath), '../.proteum/server/commands.d.ts'],
         },
         null,
         4,
     )}
 `;
+};
 
 const legacyCommandsTsconfigContent = `{
     "extends": "../server/tsconfig.json",
@@ -105,8 +113,15 @@ const isManagedCommandsTsconfig = (content: string) => {
         };
 
         if (parsed.extends !== '../server/tsconfig.json') return false;
-        if (JSON.stringify(parsed.include || []) !== JSON.stringify(['.', '../var/typings', '../node_modules/proteum/types/global', '../.proteum/server/commands.d.ts']))
+        if (!Array.isArray(parsed.include) || parsed.include.length !== 4) return false;
+        if (parsed.include[0] !== '.' || parsed.include[1] !== '../var/typings') return false;
+        if (parsed.include[3] !== '../.proteum/server/commands.d.ts') return false;
+        if (
+            parsed.include[2] !== getCommandsGlobalTypesPath(getCommandsTsconfigFilepath()) &&
+            !parsed.include[2].includes('node_modules/proteum/types/global')
+        ) {
             return false;
+        }
 
         if (parsed.compilerOptions?.baseUrl !== undefined && parsed.compilerOptions.baseUrl !== '..') return false;
         if (parsed.compilerOptions?.rootDir !== undefined && parsed.compilerOptions.rootDir !== '..') return false;
@@ -119,7 +134,7 @@ const isManagedCommandsTsconfig = (content: string) => {
 
 const ensureCommandsTsconfig = () => {
     const commandsRoot = path.join(app.paths.root, 'commands');
-    const commandsTsconfigFilepath = path.join(commandsRoot, 'tsconfig.json');
+    const commandsTsconfigFilepath = getCommandsTsconfigFilepath();
     const nextContent = createCommandsTsconfigContent();
 
     if (!fs.existsSync(commandsRoot)) return;

package/cli/compiler/client/index.ts

@@ -21,17 +21,18 @@ import type { App } from '../../app';
 
 const debug = false;
 const ssrScriptPattern = /\.ssr\.(ts|tsx)$/;
-const normalizedCoreRoot = cli.paths.core.root.replace(/\\/g, '/');
+const normalizedCoreRoot = cli.paths.framework.activeRoot.replace(/\\/g, '/');
 const hmrClientEntry = path.join(cli.paths.core.root, 'client', 'dev', 'hmr.ts');
 
 const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
-const resolveFromAppOrCore = (app: App, request: string) =>
-    require.resolve(request, { paths: [app.paths.root, cli.paths.core.root] });
+const resolveFromAppOrCore = (_app: App, request: string) => cli.paths.resolveRequest(request);
 const rewriteFrameworkAliasTargets = (app: App, aliases: Record<string, string | string[]>) => {
-    const installedCoreRoot = normalizeModulePath(path.join(app.paths.root, 'node_modules', 'proteum'));
-    const activeCoreRoot = normalizeModulePath(cli.paths.core.root);
+    const installedCoreRoot = cli.paths.framework.installedRoot
+        ? normalizeModulePath(cli.paths.framework.installedRoot)
+        : undefined;
+    const activeCoreRoot = normalizeModulePath(cli.paths.framework.activeRoot);
 
-    if (installedCoreRoot === activeCoreRoot) return aliases;
+    if (!installedCoreRoot || installedCoreRoot === activeCoreRoot) return aliases;
 
     const rewriteCandidate = (candidate: string) =>
         normalizeModulePath(candidate).startsWith(installedCoreRoot + '/')
@@ -76,8 +77,7 @@ export default function createCompiler(
     logVerbose(`Creating compiler for client (${mode}).`);
     const dev = mode === 'dev';
     const outputPath = app.outputPath(outputTarget);
-    const installedCoreRoot = path.join(app.paths.root, 'node_modules', 'proteum');
-    const frameworkRoots = [cli.paths.core.root, installedCoreRoot];
+    const frameworkRoots = cli.paths.getFrameworkRoots();
     const transpileModuleDirectories = app.transpileModuleDirectories;
 
     const commonConfig = createCommonConfig(app, 'client', mode, outputTarget);
@@ -93,7 +93,7 @@ export default function createCompiler(
         );*/
 
     // Convert tsconfig paths into bundler aliases.
-    const { aliases } = app.aliases.client.forWebpack({ modulesPath: app.paths.root + '/node_modules' });
+    const { aliases } = app.aliases.client.forWebpack({ modulesPath: cli.paths.framework.appNodeModulesRoot });
     const resolvedAliases = rewriteFrameworkAliasTargets(app, aliases);
 
     // We're not supposed in any case to import server libs from client

package/cli/compiler/common/index.ts

@@ -45,6 +45,11 @@ export default function createCommonConfig(
 ): Configuration {
     const dev = mode === 'dev';
     const enableFilesystemCache = dev ? cli.args.cache !== false : cli.args.cache === true;
+    const loaderModuleRoots = [
+        cli.paths.framework.appNodeModulesRoot,
+        cli.paths.framework.frameworkNodeModulesRoot,
+        path.join(cli.paths.core.cli, 'node_modules'),
+    ].filter((moduleRoot, index, list) => list.indexOf(moduleRoot) === index);
     const config: Configuration = {
         // Project root
         context: app.paths.root,
@@ -55,11 +60,7 @@ export default function createCommonConfig(
             // Support both install modes:
             // - npm i: loaders are often hoisted in app/node_modules
             // - npm link: loaders often live in framework/node_modules
-            modules: [
-                app.paths.root + '/node_modules',
-                cli.paths.core.root + '/node_modules',
-                cli.paths.core.cli + '/node_modules',
-            ],
+            modules: loaderModuleRoots,
             mainFields: ['loader', 'main'],
         },
 

package/cli/compiler/index.ts

@@ -9,6 +9,7 @@ import { rspack, type Compiler as RspackCompiler } from '@rspack/core';
 
 // Core
 import app from '../app';
+import cli from '..';
 import createServerConfig from './server';
 import createClientConfig from './client';
 import { TCompileMode, TCompileOutputTarget } from './common';
@@ -62,15 +63,21 @@ export default class Compiler {
         - Including React, so VSCode shows that JSX is missing
     */
     public fixNpmLinkIssues() {
-        const corePath = path.join(app.paths.root, '/node_modules/proteum');
-        if (!fs.lstatSync(corePath).isSymbolicLink())
-            return logVerbose("Not fixing npm issue because proteum wasn't installed with npm link.");
+        const installedFrameworkRoot = cli.paths.framework.installedRoot;
+
+        if (!installedFrameworkRoot || !fs.existsSync(installedFrameworkRoot)) {
+            return logVerbose("Not fixing npm link issues because the app can't see an installed Proteum package.");
+        }
+
+        if (!fs.lstatSync(installedFrameworkRoot).isSymbolicLink()) {
+            return logVerbose("Not fixing npm link issues because Proteum wasn't installed with npm link.");
+        }
 
         this.debug && logVerbose(`Fix NPM link issues ...`);
         const outputPath = app.outputPath(this.outputTarget);
 
-        const appModules = path.join(app.paths.root, 'node_modules');
-        const coreModules = path.join(corePath, 'node_modules');
+        const appModules = cli.paths.framework.appNodeModulesRoot;
+        const coreModules = cli.paths.framework.frameworkNodeModulesRoot;
 
         // When the 5htp package is installed from npm link,
         // Modules are installed locally and not glbally as with with the 5htp package from NPM.

package/cli/compiler/server/index.ts

@@ -51,10 +51,12 @@ const getDevGeneratedRuntimeEntries = (app: App) => ({
 });
 const normalizeModulePath = (value?: string) => (value || '').replace(/\\/g, '/');
 const rewriteFrameworkAliasTargets = (app: App, aliases: Record<string, string | string[]>) => {
-    const installedCoreRoot = normalizeModulePath(app.paths.root + '/node_modules/proteum');
-    const activeCoreRoot = normalizeModulePath(cli.paths.core.root);
+    const installedCoreRoot = cli.paths.framework.installedRoot
+        ? normalizeModulePath(cli.paths.framework.installedRoot)
+        : undefined;
+    const activeCoreRoot = normalizeModulePath(cli.paths.framework.activeRoot);
 
-    if (installedCoreRoot === activeCoreRoot) return aliases;
+    if (!installedCoreRoot || installedCoreRoot === activeCoreRoot) return aliases;
 
     const rewriteCandidate = (candidate: string) =>
         normalizeModulePath(candidate).startsWith(installedCoreRoot + '/')
@@ -80,12 +82,11 @@ export default function createCompiler(
     debug && console.info(`Creating compiler for server (${mode}).`);
     const dev = mode === 'dev';
     const outputPath = app.outputPath(outputTarget);
-    const installedCoreRoot = app.paths.root + '/node_modules/proteum';
-    const frameworkRoots = [cli.paths.core.root, installedCoreRoot];
+    const frameworkRoots = cli.paths.getFrameworkRoots();
     const transpileModuleDirectories = app.transpileModuleDirectories;
 
     const commonConfig = createCommonConfig(app, 'server', mode, outputTarget);
-    const { aliases } = app.aliases.server.forWebpack({ modulesPath: app.paths.root + '/node_modules' });
+    const { aliases } = app.aliases.server.forWebpack({ modulesPath: cli.paths.framework.appNodeModulesRoot });
     const resolvedAliases = rewriteFrameworkAliasTargets(app, aliases);
 
     // We're not supposed in any case to import client services from server

package/cli/index.ts

@@ -3,6 +3,7 @@ process.traceDeprecation = true;
 import { Cli } from 'clipanion';
 
 import cli from './context';
+import { resolveFrameworkInstallInfo } from './paths';
 import { proteumCommandNames } from './presentation/commands';
 import { renderCliOverview, renderCommandHelp, resolveCustomHelpRequest } from './presentation/help';
 import { renderCliWelcomeBanner } from './presentation/welcome';
@@ -32,6 +33,10 @@ const shouldRenderSharedWelcomeBanner = ({
 export const runCli = async (argv: string[] = process.argv.slice(2)) => {
     const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
     const version = String(cli.packageJson.version || '');
+    const proteumInstall = resolveFrameworkInstallInfo({
+        appRoot: cli.paths.appRoot,
+        framework: cli.paths.framework,
+    });
     const clipanion = createCli(version);
     const initAvailable = true;
     const helpRequest = resolveCustomHelpRequest(normalizedArgv);
@@ -44,6 +49,7 @@ export const runCli = async (argv: string[] = process.argv.slice(2)) => {
         process.stderr.write(
             `${await renderCliWelcomeBanner({
                 command: formatInvocation(normalizedArgv),
+                installSummary: proteumInstall.summary,
                 version,
             })}\n\n`,
         );