proteum 2.1.7 → 2.1.9-1

package/AGENTS.md

@@ -26,16 +26,26 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise the affected flow with Playwright or the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations 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 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. 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 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.
@@ -54,9 +64,10 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 
 Do not stop at static analysis for routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
 
-- Run `npx proteum dev --no-cache --port 3xxx` in both reference apps on explicit ports.
+- Run `npx proteum dev --no-cache --replace-existing --session-file var/run/proteum/dev/framework-<app>.json --port 3xxx` in both reference apps on explicit ports.
 - When validating a concrete route, controller path, or failing page on a running dev server, prefer `proteum diagnose <path> --port <port>` first. Use raw `proteum trace ...` output when you need lower-level event detail beyond the diagnose summary.
 - When the issue is latency, CPU, SQL cost, render cost, or memory drift, inspect `proteum perf top`, `proteum perf request`, `proteum perf compare`, or `proteum perf memory` against the running dev server before adding custom instrumentation.
+- When a framework change can affect shipped client code size, run `proteum build --prod --analyze` for static bundle artifacts or `proteum build --prod --analyze --analyze-serve --analyze-port auto` when you need a local analyzer URL.
 - For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` to mint a dev auth cookie instead of automating the login UI. Use the login UI only when login itself is the feature under test.
 - For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
 - When the framework-facing workflow itself changed, verify the CLI surface too with `proteum verify framework-change --crosspath-port <port> --product-port <port> --website-port <port>`.

package/README.md

@@ -323,7 +323,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum typecheck` | Refresh generated typings, then run TypeScript |
 | `proteum lint` | Run ESLint for the current app |
 | `proteum check` | Refresh, typecheck, and lint in one command |
-| `proteum build --prod` | Produce the production server and client bundles into `bin/` |
+| `proteum build --prod` | Produce the production server and client bundles into `bin/`, with optional static or served bundle analysis |
 | `proteum connect` | Inspect connected-project sources, env, cached contracts, and imported controllers |
 | `proteum doctor` | Inspect manifest diagnostics |
 | `proteum explain` | Explain routes, controllers, services, layouts, conventions, env, and connected projects |
@@ -343,8 +343,12 @@ proteum dev
 proteum refresh
 proteum check
 proteum build --prod
+proteum build --prod --analyze
+proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
+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:
 
 ```bash

package/agents/project/AGENTS.md

@@ -16,10 +16,19 @@ Coding style source of truth: project-root `CODING_STYLE.md`.
 - Follow project-root `diagnostics.md` for diagnosis, runtime reproduction, temporary instrumentation, error-solving workflow, and verification method selection.
 - For new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- 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 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.
-- 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".
+- 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 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
 
@@ -98,6 +107,8 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - `npx proteum command ...`
 - `npx proteum session ...`
 - `npx proteum create ... --dry-run --json`
+- `npx proteum dev list --json`
+- `npx proteum dev stop --session-file <path>`
 
 Prefer scaffold commands before hand-writing boilerplate:
 
@@ -224,7 +235,7 @@ Verify at the correct layer:
 - router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
 - For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow project-root `diagnostics.md`.
 
-Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum perf top`, `npx proteum perf request <requestId|path>`, `npx proteum perf compare --baseline yesterday --target today`, `npx proteum command <path>`, `npx proteum session <email> --role <role>`.
+Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `proteum dev list --json`, `proteum dev stop --session-file <path>`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum build --prod --analyze`, `npx proteum build --prod --analyze --analyze-serve --analyze-port auto`, `npx proteum perf top`, `npx proteum perf request <requestId|path>`, `npx proteum perf compare --baseline yesterday --target today`, `npx proteum command <path>`, `npx proteum session <email> --role <role>`.
 
 ## High-Impact Files
 

package/agents/project/diagnostics.md

@@ -12,10 +12,13 @@ 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 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.
 - For performance issues or regressions in dev, use `npx proteum perf top --since <window>` to rank hot paths, `npx proteum perf request <requestId|path>` for one request waterfall, `npx proteum perf compare --baseline <window> --target <window>` for regressions, and `npx proteum perf memory --since <window>` for heap or RSS drift.
+- For bundle-size inspection, use `npx proteum build --prod --analyze` to emit `bin/bundle-analysis/client.html` and `client-stats.json`, or add `--analyze-serve --analyze-port auto` when you want a local analyzer URL instead of a static HTML file.
 - For request-time issues in dev, inspect traces before adding logs when the diagnose surface is still too coarse.
 - If a server is already running on the default port from `PORT` or `./.proteum/manifest.json`, inspect existing traces before reproducing the issue.
 - If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request with `npx proteum trace latest` or `npx proteum trace show <requestId>`.
@@ -47,6 +50,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - For browser regressions, prefer targeted Playwright coverage and inspect failure artifacts such as screenshots, videos, `error-context.md`, and Playwright traces.
 - Treat server startup failures, runtime errors, browser console errors or warnings, and Playwright failures as blocking unless they are clearly unrelated to the change.
 - When the touched surface can affect coding-style enforcement, run the smallest relevant project check such as `npx proteum lint` or `npx proteum check` before finishing.
+- If the task started any long-lived `proteum dev` server, stop it explicitly with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`, then confirm the remaining tracked sessions with `npx proteum dev list --json`.
 - Add `data-testid` when stable selectors are missing instead of relying on brittle text or DOM-shape selectors.
 - If an isolated test misses prerequisite state, run the smallest broader scope that reproduces the real setup.
 - After a fix, re-check traces, rendered HTML, browser console, and server output when those surfaces were part of the original failure.

package/agents/project/optimizations.md

@@ -13,6 +13,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 ## Bundle Size And Runtime Cost
 
 - Reduce shipped client bundle size and unnecessary runtime code.
+- When you need evidence for a bundle-size regression, run `npx proteum build --prod --analyze` for static artifacts or `npx proteum build --prod --analyze --analyze-serve --analyze-port auto` for a local analyzer URL.
 - Before inventing a new helper, runtime, plugin, abstraction, primitive, parser, formatter, SDK wrapper, or build-time tool, first check whether the repo already depends on a suitable package.
 - If the repo does not already depend on one, search npm before writing a custom implementation.
 - Prefer established, flexible, well-typed, widely adopted, actively maintained packages.

package/cli/app/index.ts

@@ -38,20 +38,34 @@ const normalizeModulePath = (value: string) => value.replace(/\\/g, '/').replace
 
 const resolveTranspileModuleDirectories = ({
     moduleNames,
-    searchRoots,
+    resolvePackageRoot,
+    getVisiblePackageInstallRoots,
 }: {
     moduleNames: string[];
-    searchRoots: string[];
+    resolvePackageRoot: (moduleName: string) => string;
+    getVisiblePackageInstallRoots: (moduleName: string) => 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));
+        const candidates = new Set<string>();
+
+        try {
+            candidates.add(normalizeModulePath(resolvePackageRoot(moduleName)));
+        } catch {}
+
+        for (const visibleInstallRoot of getVisiblePackageInstallRoots(moduleName)) {
+            candidates.add(normalizeModulePath(visibleInstallRoot));
+        }
+
+        for (const candidate of candidates) {
             if (!fs.existsSync(candidate)) continue;
 
             directories.add(candidate);
-            directories.add(normalizeModulePath(fs.realpathSync(candidate)));
+
+            try {
+                directories.add(normalizeModulePath(fs.realpathSync(candidate)));
+            } catch {}
         }
     }
 
@@ -136,15 +150,25 @@ export class App {
     public get transpileModuleDirectories() {
         return resolveTranspileModuleDirectories({
             moduleNames: this.transpile,
-            searchRoots: [this.paths.root, cli.paths.core.root],
+            resolvePackageRoot: (moduleName) => cli.paths.resolvePackageRoot(moduleName),
+            getVisiblePackageInstallRoots: (moduleName) => cli.paths.getVisiblePackageInstallRoots(moduleName),
         });
     }
 
     public isTranspileModuleFile(filepath: string) {
         const normalizedFilepath = normalizeModulePath(path.resolve(filepath));
+        let normalizedRealFilepath: string | undefined;
+
+        try {
+            normalizedRealFilepath = normalizeModulePath(fs.realpathSync(filepath));
+        } catch {}
 
         return this.transpileModuleDirectories.some(
-            (directory) => normalizedFilepath === directory || normalizedFilepath.startsWith(directory + '/'),
+            (directory) =>
+                normalizedFilepath === directory ||
+                normalizedFilepath.startsWith(directory + '/') ||
+                normalizedRealFilepath === directory ||
+                normalizedRealFilepath?.startsWith(directory + '/') === true,
         );
     }
 
@@ -161,12 +185,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/bin.js

@@ -2,12 +2,6 @@
 
 const path = require('path');
 
-const clearInteractiveConsole = () => {
-    if (process.stdout.isTTY !== true || process.env.TERM === 'dumb') return;
-
-    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
-};
-
 /*
     Why this exists (npm i vs npm link difference)
 
@@ -36,8 +30,6 @@ if (!process.env.TS_NODE_IGNORE) {
 process.env.TS_NODE_PROJECT = path.join(__dirname, 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 
-clearInteractiveConsole();
-
 require('ts-node/register/transpile-only');
 
 const { runCli } = require('./index.ts');

package/cli/commands/build.ts

@@ -2,6 +2,8 @@
 - DEPENDANCES
 ----------------------------------*/
 
+import { UsageError } from 'clipanion';
+
 // Core
 import cli from '..';
 import { app } from '../app';
@@ -10,15 +12,23 @@ import { app } from '../app';
 import Compiler from '../compiler';
 import type { TCompileMode } from '../compiler/common';
 import {
+    consumeClientBundleAnalysisServerUrl,
+    getBundleAnalysisMode,
+    getBundleAnalysisServerHost,
+    getBundleAnalysisServerPort,
     getClientBundleAnalysisReportPaths,
+    hasBundleAnalysisServerOverrides,
     waitForClientBundleAnalysisArtifacts,
 } from '../compiler/common/bundleAnalysis';
 import { refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
 import { renderRows } from '../presentation/layout';
 import { renderStep, renderSuccess, renderTitle } from '../presentation/ink';
 
-const allowedBuildArgs = new Set(['prod', 'cache', 'analyze', 'strict']);
+const allowedBuildArgs = new Set(['prod', 'cache', 'analyze', 'analyzeServe', 'strict']);
 type TBuildMultiCompiler = Awaited<ReturnType<Compiler['create']>>;
+type TBuildAnalysisResult =
+    | { mode: 'static'; reportPath: string; statsPath: string }
+    | { mode: 'server'; statsPath: string; url?: string };
 
 /*----------------------------------
 - COMMAND
@@ -30,7 +40,9 @@ function resolveBuildMode(): TCompileMode {
 
     const invalidArgs = enabledArgs.filter((arg) => !allowedBuildArgs.has(arg));
     if (invalidArgs.length > 0)
-        throw new Error(`Unknown build argument(s): ${invalidArgs.join(', ')}. Allowed values: prod, cache, analyze, strict.`);
+        throw new Error(
+            `Unknown build argument(s): ${invalidArgs.join(', ')}. Allowed values: prod, cache, analyze, analyzeServe, strict.`,
+        );
 
     const requestedModes = enabledArgs.filter((arg): arg is TCompileMode => arg === 'prod');
     if (requestedModes.length > 1)
@@ -39,6 +51,19 @@ function resolveBuildMode(): TCompileMode {
     return requestedModes[0] ?? 'prod';
 }
 
+function assertValidBuildAnalyzerArgs() {
+    const analyzeEnabled = cli.args.analyze === true;
+    const analyzeServeEnabled = cli.args.analyzeServe === true;
+
+    if (!analyzeEnabled && (analyzeServeEnabled || hasBundleAnalysisServerOverrides())) {
+        throw new UsageError('Analyzer server flags require `--analyze`.');
+    }
+
+    if (!analyzeServeEnabled && hasBundleAnalysisServerOverrides()) {
+        throw new UsageError('`--analyze-host` and `--analyze-port` require `--analyze-serve`.');
+    }
+}
+
 const closeMultiCompiler = async (multiCompiler: TBuildMultiCompiler) =>
     await new Promise<void>((resolve, reject) => {
         multiCompiler.close((error) => {
@@ -54,7 +79,11 @@ const closeMultiCompiler = async (multiCompiler: TBuildMultiCompiler) =>
 export const run = async (): Promise<void> => {
     const mode = resolveBuildMode();
     const strict = cli.args.strict === true;
-    let analysisArtifacts: { reportPath: string; statsPath: string } | undefined;
+    assertValidBuildAnalyzerArgs();
+
+    const analyze = cli.args.analyze === true;
+    const analysisMode = analyze ? getBundleAnalysisMode() : undefined;
+    let analysisResult: TBuildAnalysisResult | undefined;
 
     console.info(
         [
@@ -69,7 +98,14 @@ export const run = async (): Promise<void> => {
                 { label: 'mode', value: mode },
                 { label: 'strict', value: strict ? 'enabled' : 'disabled' },
                 { label: 'cache', value: cli.args.cache === true ? 'enabled' : 'disabled' },
-                { label: 'analyze', value: cli.args.analyze === true ? 'enabled' : 'disabled' },
+                { label: 'analyze', value: analyze ? 'enabled' : 'disabled' },
+                ...(analyze ? [{ label: 'analyze mode', value: analysisMode || 'static' }] : []),
+                ...(analysisMode === 'server'
+                    ? [
+                          { label: 'analyze host', value: getBundleAnalysisServerHost() },
+                          { label: 'analyze port', value: String(getBundleAnalysisServerPort()) },
+                      ]
+                    : []),
                 { label: 'output', value: 'bin/' },
             ]),
         ].join('\n\n'),
@@ -103,10 +139,11 @@ export const run = async (): Promise<void> => {
                     return;
                 }
 
-                if (cli.args.analyze === true) {
+                if (analysisMode === 'static') {
                     waitForClientBundleAnalysisArtifacts(app, 'bin')
                         .then(() => {
-                            analysisArtifacts = getClientBundleAnalysisReportPaths(app, 'bin');
+                            const { reportPath, statsPath } = getClientBundleAnalysisReportPaths(app, 'bin');
+                            analysisResult = { mode: 'static', reportPath, statsPath };
                             resolve();
                         })
                         .catch(reject);
@@ -125,11 +162,25 @@ export const run = async (): Promise<void> => {
 
     if (buildError) throw buildError;
 
-    if (analysisArtifacts !== undefined) {
+    if (analysisMode === 'server') {
+        const { statsPath } = getClientBundleAnalysisReportPaths(app, 'bin');
+        analysisResult = {
+            mode: 'server',
+            statsPath,
+            url: consumeClientBundleAnalysisServerUrl(),
+        };
+    }
+
+    if (analysisResult !== undefined) {
         console.info(
             renderRows([
-                { label: 'report', value: analysisArtifacts.reportPath },
-                { label: 'stats', value: analysisArtifacts.statsPath },
+                ...(analysisResult.mode === 'static' ? [{ label: 'report', value: analysisResult.reportPath }] : []),
+                ...(analysisResult.mode === 'server'
+                    ? [
+                          { label: 'server', value: analysisResult.url || 'Analyzer server started. See the analyzer log for the URL.' },
+                      ]
+                    : []),
+                { label: 'stats', value: analysisResult.statsPath },
             ]),
         );
     }