proteum 2.1.7 → 2.1.9-1

package/cli/compiler/server/index.ts

@@ -3,6 +3,7 @@
 ----------------------------------*/
 
 // Npm
+import path from 'path';
 import { type Configuration } from '@rspack/core';
 
 // Core
@@ -50,16 +51,38 @@ const getDevGeneratedRuntimeEntries = (app: App) => ({
     __proteum_dev_controllers: [app.paths.server.generated + '/controllers.ts'],
 });
 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 getFrameworkSourceRoot = () => {
+    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 && activeCoreRoot.includes('/node_modules/')) {
+        return installedCoreRoot;
+    }
+
+    return activeCoreRoot;
+};
+
+const rewriteFrameworkAliasTargets = (aliases: Record<string, string | string[]>) => {
+    const visibleFrameworkRoots = [
+        ...cli.paths.getVisiblePackageInstallRoots('proteum'),
+        cli.paths.framework.installedRoot,
+        cli.paths.framework.activeRoot,
+    ]
+        .filter((rootPath): rootPath is string => typeof rootPath === 'string' && rootPath !== '')
+        .map((rootPath) => normalizeModulePath(rootPath))
+        .filter((rootPath, index, list) => list.indexOf(rootPath) === index);
+    const frameworkSourceRoot = getFrameworkSourceRoot();
 
     const rewriteCandidate = (candidate: string) =>
-        normalizeModulePath(candidate).startsWith(installedCoreRoot + '/')
-            ? activeCoreRoot + normalizeModulePath(candidate).substring(installedCoreRoot.length)
-            : candidate;
+        visibleFrameworkRoots.reduce((nextCandidate, rootPath) => {
+                const normalizedCandidate = normalizeModulePath(nextCandidate);
+
+                return normalizedCandidate.startsWith(rootPath + '/')
+                    ? frameworkSourceRoot + normalizedCandidate.substring(rootPath.length)
+                    : nextCandidate;
+            }, candidate);
 
     return Object.fromEntries(
         Object.entries(aliases).map(([alias, value]) => [
@@ -80,19 +103,22 @@ 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 frameworkSourceRoot = getFrameworkSourceRoot();
+    const frameworkRoots = [frameworkSourceRoot, ...cli.paths.getFrameworkRoots()].filter(
+        (rootPath, index, list) => list.indexOf(rootPath) === index,
+    );
     const transpileModuleDirectories = app.transpileModuleDirectories;
 
     const commonConfig = createCommonConfig(app, 'server', mode, outputTarget);
-    const { aliases } = app.aliases.server.forWebpack({ modulesPath: app.paths.root + '/node_modules' });
-    const resolvedAliases = rewriteFrameworkAliasTargets(app, aliases);
+    const { aliases } = app.aliases.server.forWebpack({ modulesPath: cli.paths.framework.appNodeModulesRoot });
+    const resolvedAliases = rewriteFrameworkAliasTargets(aliases);
 
     // We're not supposed in any case to import client services from server
     delete resolvedAliases['@client/services'];
     delete resolvedAliases['@/client/services'];
     const rspackAliases = toRspackAliases(resolvedAliases);
-    rspackAliases['@/client/router$'] = cli.paths.core.root + '/client/router.ts';
+    rspackAliases['proteum'] = frameworkSourceRoot;
+    rspackAliases['@/client/router$'] = frameworkSourceRoot + '/client/router.ts';
 
     debug &&
         console.log(
@@ -107,7 +133,7 @@ export default function createCompiler(
         name: 'server',
         target: 'node',
         entry: {
-            server: [cli.paths.coreRoot + '/server/index.ts'],
+            server: [path.join(frameworkSourceRoot, 'server', 'index.ts')],
             ...(dev ? getDevGeneratedRuntimeEntries(app) : {}),
         },
 

package/cli/index.ts

@@ -3,21 +3,62 @@ 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';
 import { normalizeHelpArgv, normalizeLegacyArgv } from './runtime/argv';
 import { createCli, registeredCommands } from './runtime/commands';
 
+const formatInvocation = (argv: string[]) => ['proteum', ...argv].join(' ').trim();
+
+const shouldRenderSharedWelcomeBanner = ({
+    argv,
+    helpRequestKind,
+}: {
+    argv: string[];
+    helpRequestKind: 'none' | 'overview' | 'command';
+}) => {
+    if (helpRequestKind !== 'none') return true;
+    if (argv[0] !== 'dev') return true;
+
+    if (argv.length === 1) return false;
+
+    const action = argv[1];
+    if (action.startsWith('-')) return false;
+
+    return action === 'list' || action === 'stop';
+};
+
 export const runCli = async (argv: string[] = process.argv.slice(2)) => {
     const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
-    const clipanion = createCli(String(cli.packageJson.version || ''));
+    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);
+    const shouldRenderWelcomeBanner = shouldRenderSharedWelcomeBanner({
+        argv: normalizedArgv,
+        helpRequestKind: helpRequest.kind,
+    });
+
+    if (shouldRenderWelcomeBanner) {
+        process.stderr.write(
+            `${await renderCliWelcomeBanner({
+                command: formatInvocation(normalizedArgv),
+                installSummary: proteumInstall.summary,
+                version,
+            })}\n\n`,
+        );
+    }
 
     if (helpRequest.kind === 'overview') {
         process.stdout.write(
             await renderCliOverview({
-                version: String(cli.packageJson.version || ''),
+                version,
                 workdir: process.cwd(),
                 initAvailable,
             }),

package/cli/paths.ts

@@ -35,6 +35,29 @@ export type TPathInfos = {
     isIndex: boolean;
 };
 
+export type TResolvedPackageBinary = {
+    packageName: string;
+    packageRoot: string;
+    binPath: string;
+    command: string;
+    args: string[];
+};
+
+export type TFrameworkInstallGraph = {
+    activeRoot: string;
+    installedRoot?: string;
+    appNodeModulesRoot: string;
+    frameworkNodeModulesRoot: string;
+};
+
+export type TFrameworkInstallMode = 'npm' | 'npm-link' | 'path' | 'workspace' | 'global' | 'checkout';
+
+export type TFrameworkInstallInfo = {
+    mode: TFrameworkInstallMode;
+    summary: string;
+    dependencySpec?: string;
+};
+
 /*----------------------------------
 - CONFIG
 ----------------------------------*/
@@ -51,7 +74,88 @@ const safeRealpath = (filepath: string) => {
     }
 };
 
-const resolveCoreRoot = (appRoot: string) => {
+const readPackageJson = (filepath: string) => {
+    try {
+        return JSON.parse(fs.readFileSync(filepath, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return undefined;
+    }
+};
+
+const readPackageDependencySpec = (appRoot: string, packageName: string) => {
+    const packageJson = readPackageJson(path.join(appRoot, 'package.json'));
+    if (!packageJson) return undefined;
+
+    const dependencySections = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const;
+
+    for (const section of dependencySections) {
+        const dependencies = packageJson[section];
+        if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) continue;
+
+        const dependencySpec = (dependencies as Record<string, unknown>)[packageName];
+        if (typeof dependencySpec !== 'string' || dependencySpec.trim() === '') continue;
+
+        return dependencySpec.trim();
+    }
+
+    return undefined;
+};
+
+const findVisibleNodeModulesRoot = (startPath: string): string | undefined => {
+    let currentPath = path.resolve(startPath);
+
+    while (true) {
+        const candidate = path.join(currentPath, 'node_modules');
+        if (fs.existsSync(candidate)) return candidate;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+};
+
+const findVisibleNodeModulesRoots = (startPath: string): string[] => {
+    const roots: string[] = [];
+    let currentPath = path.resolve(startPath);
+
+    while (true) {
+        const candidate = path.join(currentPath, 'node_modules');
+        if (fs.existsSync(candidate) && !roots.includes(candidate)) roots.push(candidate);
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return roots;
+        currentPath = parentPath;
+    }
+};
+
+const findVisiblePackageInstall = (startPath: string, packageName: string): string | undefined => {
+    let currentPath = path.resolve(startPath);
+
+    while (true) {
+        const candidate = path.join(currentPath, 'node_modules', packageName);
+        if (fs.existsSync(candidate)) return candidate;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+};
+
+const findVisiblePackageInstalls = (startPath: string, packageName: string): string[] => {
+    const installs: string[] = [];
+    let currentPath = path.resolve(startPath);
+
+    while (true) {
+        const candidate = path.join(currentPath, 'node_modules', packageName);
+        if (fs.existsSync(candidate) && !installs.includes(candidate)) installs.push(candidate);
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return installs;
+        currentPath = parentPath;
+    }
+};
+
+const resolveCoreRoot = (appRoot: string): string => {
     const currentPackageRoot = path.resolve(__dirname, '..');
     const currentBin = path.join(currentPackageRoot, 'cli', 'bin.js');
     const invokedScript = process.argv[1] ? safeRealpath(process.argv[1]) : '';
@@ -59,8 +163,8 @@ const resolveCoreRoot = (appRoot: string) => {
 
     if (invokedCurrentPackage) return currentPackageRoot;
 
-    const localInstall = path.join(appRoot, 'node_modules', 'proteum');
-    if (fs.existsSync(localInstall)) return localInstall;
+    const installedFrameworkRoot = findVisiblePackageInstall(appRoot, 'proteum');
+    if (installedFrameworkRoot) return installedFrameworkRoot;
 
     // When running `npx`/global installs, there may be no local `node_modules/proteum` yet.
     // Fall back to the installed package root (this file lives in `<root>/cli`).
@@ -69,9 +173,101 @@ const resolveCoreRoot = (appRoot: string) => {
 
 const normalizeImportPath = (value: string) => value.replace(/\\/g, '/');
 
+const resolveAppNodeModulesRoot = (appRoot: string): string => {
+    const installedRoot = findVisiblePackageInstall(appRoot, 'proteum');
+
+    return (
+        (installedRoot ? path.dirname(installedRoot) : undefined) ||
+        findVisibleNodeModulesRoot(appRoot) ||
+        path.join(appRoot, 'node_modules')
+    );
+};
+
+const resolveFrameworkInstallRoot = (appRoot: string): string =>
+    findVisiblePackageInstall(appRoot, 'proteum') || path.join(resolveAppNodeModulesRoot(appRoot), 'proteum');
+
+const resolveFrameworkInstallGraph = (appRoot: string, activeRoot: string): TFrameworkInstallGraph => {
+    const installedRoot = findVisiblePackageInstall(appRoot, 'proteum');
+
+    return {
+        activeRoot,
+        installedRoot,
+        appNodeModulesRoot: resolveAppNodeModulesRoot(appRoot),
+        frameworkNodeModulesRoot: findVisibleNodeModulesRoot(activeRoot) || path.join(activeRoot, 'node_modules'),
+    };
+};
+
+const resolvePackageJsonPath = (packageName: string, searchPaths: string[]): string =>
+    require.resolve(`${packageName}/package.json`, { paths: searchPaths });
+
 const filenameToImportName = (value: string) =>
     normalizeImportPath(value).replace(/[^A-Za-z0-9_]+/g, '_');
 
+export const resolveFrameworkInstallInfo = ({
+    appRoot,
+    framework,
+}: {
+    appRoot: string;
+    framework: TFrameworkInstallGraph;
+}): TFrameworkInstallInfo => {
+    const dependencySpec = readPackageDependencySpec(appRoot, 'proteum');
+    const installedRoot = framework.installedRoot ? path.resolve(framework.installedRoot) : undefined;
+    const normalizedActiveRoot = normalizeImportPath(safeRealpath(framework.activeRoot));
+    const installedRootIsSymlink =
+        installedRoot !== undefined &&
+        (() => {
+            try {
+                return fs.lstatSync(installedRoot).isSymbolicLink();
+            } catch {
+                return false;
+            }
+        })();
+
+    if (dependencySpec?.startsWith('file:') || dependencySpec?.startsWith('link:')) {
+        return {
+            mode: 'path',
+            summary: `path (${dependencySpec})`,
+            dependencySpec,
+        };
+    }
+
+    if (dependencySpec?.startsWith('workspace:')) {
+        return {
+            mode: 'workspace',
+            summary: `workspace (${dependencySpec})`,
+            dependencySpec,
+        };
+    }
+
+    if (installedRootIsSymlink) {
+        return {
+            mode: 'npm-link',
+            summary: 'npm link',
+            dependencySpec,
+        };
+    }
+
+    if (dependencySpec) {
+        return {
+            mode: 'npm',
+            summary: `npm (${dependencySpec})`,
+            dependencySpec,
+        };
+    }
+
+    if (!normalizedActiveRoot.includes('/node_modules/')) {
+        return {
+            mode: 'checkout',
+            summary: 'local checkout',
+        };
+    }
+
+    return {
+        mode: 'global',
+        summary: 'global install',
+    };
+};
+
 /*----------------------------------
 - LIB
 ----------------------------------*/
@@ -79,13 +275,15 @@ export default class Paths {
     /*----------------------------------
     - LISTE
     ----------------------------------*/
-
-    public constructor(
-        public appRoot: string,
-        public coreRoot = resolveCoreRoot(appRoot),
-    ) {}
-
-    public core = { cli: path.resolve(__dirname, '.'), root: this.coreRoot, pages: this.coreRoot + '/client/pages' };
+    public coreRoot: string;
+    public framework: TFrameworkInstallGraph;
+    public core: { cli: string; root: string; pages: string };
+
+    public constructor(public appRoot: string, coreRoot = resolveCoreRoot(appRoot)) {
+        this.coreRoot = coreRoot;
+        this.framework = resolveFrameworkInstallGraph(appRoot, coreRoot);
+        this.core = { cli: path.resolve(__dirname, '.'), root: this.coreRoot, pages: this.coreRoot + '/client/pages' };
+    }
 
     /*----------------------------------
     - EXTRACTION
@@ -171,4 +369,137 @@ export default class Paths {
         //console.log('Applying Aliases ...', aliases.forModuleAlias());
         moduleAlias.addAliases(aliases.forModuleAlias());
     }
+
+    public getFrameworkRoots(): string[] {
+        return [
+            this.framework.activeRoot,
+            ...(this.framework.installedRoot ? [this.framework.installedRoot] : []),
+            ...this.getVisiblePackageInstallRoots('proteum'),
+        ].filter((rootPath, index, list) => list.indexOf(rootPath) === index && fs.existsSync(rootPath));
+    }
+
+    public getVisibleNodeModulesRootsForPath(startPath: string): string[] {
+        return findVisibleNodeModulesRoots(startPath);
+    }
+
+    public getVisiblePackageInstallRoots(packageName: string, startPath = this.appRoot): string[] {
+        return findVisiblePackageInstalls(startPath, packageName);
+    }
+
+    public getFrameworkInstallRoot(): string {
+        return this.getFrameworkInstallRootForAppRoot(this.appRoot);
+    }
+
+    public getFrameworkInstallRootForAppRoot(appRoot: string): string {
+        return resolveFrameworkInstallRoot(appRoot);
+    }
+
+    public getAppNodeModulesRootForAppRoot(appRoot: string): string {
+        return resolveAppNodeModulesRoot(appRoot);
+    }
+
+    public relativePathFromFile(targetFile: string, absolutePath: string): string {
+        return this.relativePathFromDirectory(path.dirname(targetFile), absolutePath);
+    }
+
+    public relativePathFromDirectory(targetDirectory: string, absolutePath: string): string {
+        const relativePath = normalizeImportPath(path.relative(targetDirectory, absolutePath));
+        if (relativePath === '') return '.';
+        if (!relativePath.startsWith('.')) return `./${relativePath}`;
+        return relativePath;
+    }
+
+    public relativeFrameworkPathFrom(targetFile: string, ...segments: string[]): string {
+        return this.relativePathFromFile(targetFile, path.join(this.getFrameworkInstallRoot(), ...segments));
+    }
+
+    public relativeAppNodeModulesPathFrom(targetFile: string, ...segments: string[]): string {
+        return this.relativePathFromFile(targetFile, path.join(this.framework.appNodeModulesRoot, ...segments));
+    }
+
+    public relativeFrameworkPathFromDirectory(targetDirectory: string, ...segments: string[]): string {
+        return this.relativePathFromDirectory(targetDirectory, path.join(this.getFrameworkInstallRoot(), ...segments));
+    }
+
+    public relativeAppNodeModulesPathFromDirectory(targetDirectory: string, ...segments: string[]): string {
+        return this.relativePathFromDirectory(targetDirectory, path.join(this.framework.appNodeModulesRoot, ...segments));
+    }
+
+    public relativeFrameworkTsconfigPathFrom(targetFile: string): string {
+        return this.relativeFrameworkPathFrom(targetFile, 'tsconfig.common.json');
+    }
+
+    public relativeFrameworkPathForAppRoot(appRoot: string, targetFile: string, ...segments: string[]): string {
+        return this.relativePathFromFile(targetFile, path.join(this.getFrameworkInstallRootForAppRoot(appRoot), ...segments));
+    }
+
+    public relativeFrameworkPathFromDirectoryForAppRoot(
+        appRoot: string,
+        targetDirectory: string,
+        ...segments: string[]
+    ): string {
+        return this.relativePathFromDirectory(
+            targetDirectory,
+            path.join(this.getFrameworkInstallRootForAppRoot(appRoot), ...segments),
+        );
+    }
+
+    public relativeAppNodeModulesPathFromDirectoryForAppRoot(
+        appRoot: string,
+        targetDirectory: string,
+        ...segments: string[]
+    ): string {
+        return this.relativePathFromDirectory(
+            targetDirectory,
+            path.join(this.getAppNodeModulesRootForAppRoot(appRoot), ...segments),
+        );
+    }
+
+    public resolvePackageRoot(packageName: string, { preferApp = true }: { preferApp?: boolean } = {}): string {
+        const installedRoot = this.framework.installedRoot;
+        const searchPaths = (preferApp
+            ? [this.appRoot, ...(installedRoot ? [installedRoot] : []), this.framework.activeRoot]
+            : [this.framework.activeRoot, ...(installedRoot ? [installedRoot] : []), this.appRoot]
+        ).filter((searchPath, index, list) => list.indexOf(searchPath) === index);
+        return path.dirname(resolvePackageJsonPath(packageName, searchPaths));
+    }
+
+    public resolveRequest(request: string, { preferApp = true }: { preferApp?: boolean } = {}): string {
+        const installedRoot = this.framework.installedRoot;
+        const searchPaths = (preferApp
+            ? [this.appRoot, ...(installedRoot ? [installedRoot] : []), this.framework.activeRoot]
+            : [this.framework.activeRoot, ...(installedRoot ? [installedRoot] : []), this.appRoot]
+        ).filter((searchPath, index, list) => list.indexOf(searchPath) === index);
+        return require.resolve(request, { paths: searchPaths });
+    }
+
+    public resolveBinary(
+        packageName: string,
+        binName = packageName,
+        { preferApp = true }: { preferApp?: boolean } = {},
+    ): TResolvedPackageBinary {
+        const packageRoot = this.resolvePackageRoot(packageName, { preferApp });
+        const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as {
+            bin?: string | Record<string, string>;
+        };
+        const binField = packageJson.bin;
+        const relativeBinPath =
+            typeof binField === 'string'
+                ? binField
+                : binField?.[binName] || binField?.[packageName];
+
+        if (!relativeBinPath) {
+            throw new Error(`Unable to resolve binary "${binName}" from package "${packageName}".`);
+        }
+
+        const binPath = path.resolve(packageRoot, relativeBinPath);
+
+        return {
+            packageName,
+            packageRoot,
+            binPath,
+            command: process.execPath,
+            args: [binPath],
+        };
+    }
 }

package/cli/presentation/commands.ts

@@ -110,18 +110,37 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'dev',
         category: 'Daily workflow',
         summary: 'Start the local compiler, SSR server, and hot reload loop.',
-        usage: 'proteum dev [--port <port>] [--cache|--no-cache]',
+        usage: 'proteum dev [list|stop] [--port <port>] [--session-file <path>] [--replace-existing] [--all] [--stale] [--json] [--cache|--no-cache]',
         bestFor:
             'Day-to-day app work. This is the main entrypoint used by the current reference apps during local development.',
         examples: [
             { description: 'Start the app on its configured router port', command: 'proteum dev' },
-            { description: 'Run a second Proteum app on another port', command: 'proteum dev --port 3101' },
+            { description: 'Replace the tracked dev session on another port', command: 'proteum dev --port 3101 --replace-existing' },
+            {
+                description: 'Start a tracked dev session with an explicit session file for an agent task',
+                command: 'proteum dev --port 3101 --session-file var/run/proteum/dev/agents/task.json --replace-existing',
+            },
+            {
+                description: 'List tracked Proteum dev sessions as JSON',
+                command: 'proteum dev list --json',
+            },
+            {
+                description: 'Stop every stale tracked dev session for the current app',
+                command: 'proteum dev stop --all --stale',
+            },
             {
                 description: 'Disable the filesystem cache while debugging compiler state',
                 command: 'proteum dev --no-cache',
             },
         ],
-        notes: ['Legacy single-dash long options remain supported, for example `proteum dev -port 3001`.'],
+        notes: [
+            'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
+            'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
+            '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
+            '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',
+            '`proteum dev` clears the interactive terminal once at startup, then shows `CTRL+R` reload and `CTRL+C` shutdown hotkeys in the session banner.',
+            'Legacy single-dash long options remain supported, for example `proteum dev -port 3001`.',
+        ],
         status: 'stable',
     },
     refresh: {
@@ -141,7 +160,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'build',
         category: 'Daily workflow',
         summary: 'Build the application.',
-        usage: 'proteum build [--prod] [--strict] [--cache] [--analyze] [--port <port>]',
+        usage: 'proteum build [--prod] [--strict] [--cache] [--analyze] [--analyze-serve] [--analyze-host <host>] [--analyze-port <port|auto>] [--port <port>]',
         bestFor: 'CI, release builds, and local verification of the production server and client output.',
         examples: [
             { description: 'Run the normal production build', command: 'proteum build --prod' },
@@ -150,10 +169,17 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
                 command: 'proteum build --prod --strict',
             },
             { description: 'Generate bundle analysis artifacts', command: 'proteum build --prod --analyze' },
+            {
+                description: 'Serve the bundle analysis at a local URL and let the OS choose the port',
+                command: 'proteum build --prod --analyze --analyze-serve --analyze-port auto',
+            },
             { description: 'Reuse the filesystem cache during builds', command: 'proteum build --prod --cache' },
         ],
         notes: [
             'Legacy positional booleans remain supported, for example `proteum build prod strict analyze`.',
+            '`--analyze` alone emits `bin/bundle-analysis/client.html` and `client-stats.json`.',
+            '`--analyze-serve` switches the analyzer to HTTP server mode and keeps the process open until you stop it.',
+            '`--analyze-host` and `--analyze-port` require `--analyze-serve`; use `auto` to let the OS assign a free port.',
             'Use `--strict` when the build must refresh generated typings and fail on any TypeScript error before compilation starts.',
             'The production output is emitted under `bin/`.',
         ],