proteum 2.1.6 → 2.1.8

package/cli/compiler/common/bundleAnalysis.ts

@@ -1,6 +1,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import type { RspackPluginInstance } from '@rspack/core';
+import { UsageError } from 'clipanion';
 
 import cli from '../..';
 import type { App } from '../../app';
@@ -8,8 +9,56 @@ import type { App } from '../../app';
 const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
 
 export type TBundleAnalysisReportPaths = { reportPath: string; statsPath: string };
+export type TBundleAnalysisMode = 'server' | 'static';
+type TBundleAnalysisServerUrlArgs = {
+    listenHost: string;
+    listenPort: number | 'auto';
+    boundAddress?: string | { address?: string; port?: number } | null;
+};
+
+const defaultAnalyzerHost = '127.0.0.1';
+const defaultAnalyzerPort = 8888;
+let latestClientBundleAnalysisServerUrl: string | undefined;
 
 export const isBundleAnalysisEnabled = () => cli.args.analyze === true;
+export const isBundleAnalysisServerEnabled = () => cli.args.analyzeServe === true;
+export const getBundleAnalysisMode = (): TBundleAnalysisMode => (isBundleAnalysisServerEnabled() ? 'server' : 'static');
+
+const hasCliStringArg = (name: string) => typeof cli.args[name] === 'string' && (cli.args[name] as string).trim().length > 0;
+
+export const hasBundleAnalysisServerOverrides = () => hasCliStringArg('analyzeHost') || hasCliStringArg('analyzePort');
+
+export const getBundleAnalysisServerHost = () =>
+    hasCliStringArg('analyzeHost') ? String(cli.args.analyzeHost).trim() : defaultAnalyzerHost;
+
+export const getBundleAnalysisServerPort = (): number | 'auto' => {
+    const rawPort = hasCliStringArg('analyzePort') ? String(cli.args.analyzePort).trim() : '';
+    if (!rawPort) return defaultAnalyzerPort;
+    if (rawPort === 'auto') return 'auto';
+
+    const parsedPort = Number.parseInt(rawPort, 10);
+    if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+        throw new UsageError(`Invalid analyzer port "${rawPort}". Use a number between 1 and 65535, or \`auto\`.`);
+    }
+
+    return parsedPort;
+};
+
+const createBundleAnalysisServerUrl = ({ listenHost, listenPort, boundAddress }: TBundleAnalysisServerUrlArgs) => {
+    const port =
+        typeof boundAddress === 'object' && boundAddress !== null && typeof boundAddress.port === 'number'
+            ? boundAddress.port
+            : listenPort;
+    const url = `http://${listenHost}:${port}`;
+    latestClientBundleAnalysisServerUrl = url;
+    return url;
+};
+
+export const consumeClientBundleAnalysisServerUrl = () => {
+    const url = latestClientBundleAnalysisServerUrl;
+    latestClientBundleAnalysisServerUrl = undefined;
+    return url;
+};
 
 export const getClientBundleAnalysisReportPaths = (
     app: App,
@@ -23,19 +72,25 @@ export const getClientBundleAnalysisReportPaths = (
 export const createClientBundleAnalysisPlugins = (app: App, outputTarget: 'dev' | 'bin'): RspackPluginInstance[] => {
     if (!isBundleAnalysisEnabled()) return [];
 
+    latestClientBundleAnalysisServerUrl = undefined;
+
     const { reportPath, statsPath } = getClientBundleAnalysisReportPaths(app, outputTarget);
+    const analyzerMode = getBundleAnalysisMode();
 
     fs.ensureDirSync(path.dirname(reportPath));
 
     return [
         new BundleAnalyzerPlugin({
-            analyzerMode: 'static',
+            analyzerMode,
+            analyzerHost: getBundleAnalysisServerHost(),
+            analyzerPort: getBundleAnalysisServerPort(),
             openAnalyzer: false,
             defaultSizes: 'parsed',
             reportFilename: reportPath,
             generateStatsFile: true,
             statsFilename: statsPath,
             logLevel: 'info',
+            analyzerUrl: createBundleAnalysisServerUrl,
         }),
     ];
 };

package/cli/index.ts

@@ -5,19 +5,54 @@ import { Cli } from 'clipanion';
 import cli from './context';
 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 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),
+                version,
+            })}\n\n`,
+        );
+    }
 
     if (helpRequest.kind === 'overview') {
         process.stdout.write(
             await renderCliOverview({
-                version: String(cli.packageJson.version || ''),
+                version,
                 workdir: process.cwd(),
                 initAvailable,
             }),

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/`.',
         ],

package/cli/presentation/devSession.ts

@@ -2,16 +2,7 @@ const React = require('react') as typeof import('react');
 
 import { renderRows } from './layout';
 import { renderInk } from './ink';
-
-const ProteumWordmark = [
-    String.raw` ____  ____   ___ _____ _____ _   _ __  __`,
-    String.raw`|  _ \|  _ \ / _ \_   _| ____| | | |  \/  |`,
-    String.raw`| |_) | |_) | | | || | |  _| | | | | |\/| |`,
-    String.raw`|  __/|  _ <| |_| || | | |___| |_| | |  | |`,
-    String.raw`|_|   |_| \_\\___/ |_| |_____|\___/|_|  |_|`,
-];
-
-const ProteumTagline = 'Agent-first SSR compiler and server loop.';
+import { renderWelcomePanel } from './welcome';
 
 export const renderDevSession = async ({
     appName,
@@ -29,21 +20,9 @@ export const renderDevSession = async ({
     proteumVersion: string;
 }) =>
     [
-        await renderInk(({ Box, Text }) => {
-            const createElement = React.createElement;
-            const wordmark = ProteumWordmark.map((line) =>
-                createElement(Text, { key: line, bold: true, color: 'blue' }, line),
-            );
-            const versionLabel = proteumVersion ? `v${proteumVersion}` : '';
-
-            return createElement(
-                Box,
-                { 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),
-            );
+        await renderWelcomePanel({
+            version: proteumVersion,
+            tagline: 'Agent-first SSR compiler and server loop.',
         }),
         renderRows(
             [
@@ -61,7 +40,8 @@ export const renderDevSession = async ({
                 { 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' },
+                { label: 'reload', value: 'CTRL+R' },
+                { label: 'shutdown', value: 'CTRL+C' },
             ],
             { minLabelWidth: 12, maxLabelWidth: 12 },
         ),

package/cli/presentation/help.ts

@@ -135,6 +135,10 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
+                wrapText('Every Proteum CLI invocation prints the welcome banner. `proteum dev` is the only command that clears the interactive terminal before rendering its session UI.', {
+                    indent: '  ',
+                    nextIndent: '  ',
+                }),
                 wrapText('Legacy single-dash flags and positional booleans remain accepted for older app scripts, but new docs should prefer modern long flags.', {
                     indent: '  ',
                     nextIndent: '  ',

package/cli/presentation/welcome.ts

@@ -0,0 +1,63 @@
+const React = require('react') as typeof import('react');
+
+import { renderRows } from './layout';
+import { renderInk } from './ink';
+
+const ProteumWordmark = [
+    String.raw` ____  ____   ___ _____ _____ _   _ __  __`,
+    String.raw`|  _ \|  _ \ / _ \_   _| ____| | | |  \/  |`,
+    String.raw`| |_) | |_) | | | || | |  _| | | | | |\/| |`,
+    String.raw`|  __/|  _ <| |_| || | | |___| |_| | |  | |`,
+    String.raw`|_|   |_| \_\\___/ |_| |_____|\___/|_|  |_|`,
+];
+
+export const clearInteractiveConsole = () => {
+    if (process.stdout.isTTY !== true || process.env.TERM === 'dumb') return;
+
+    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
+};
+
+export const renderWelcomePanel = async ({
+    version,
+    tagline,
+}: {
+    version: string;
+    tagline: string;
+}) =>
+    renderInk(({ Box, Text }) => {
+        const createElement = React.createElement;
+        const wordmark = ProteumWordmark.map((line) =>
+            createElement(Text, { key: line, bold: true, color: 'blue' }, line),
+        );
+        const versionLabel = version ? `v${version}` : '';
+
+        return createElement(
+            Box,
+            { 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 }, tagline),
+        );
+    });
+
+export const renderCliWelcomeBanner = async ({
+    command,
+    version,
+}: {
+    command: string;
+    version: string;
+}) =>
+    [
+        await renderWelcomePanel({
+            version,
+            tagline: 'Explicit SSR / SEO / TypeScript framework for agent-friendly apps.',
+        }),
+        renderRows(
+            [
+                { label: 'command', value: command },
+                { label: 'shutdown', value: 'CTRL+C' },
+            ],
+            { minLabelWidth: 10, maxLabelWidth: 10 },
+        ),
+    ].join('\n\n');

package/cli/runtime/commands.ts

@@ -79,13 +79,38 @@ class DevCommand extends ProteumCommand {
 
     public static usage = buildUsage('dev');
 
+    public json = Option.Boolean('--json', false, { description: 'Print machine-readable dev session output.' });
     public port = Option.String('--port', { description: 'Override the router port.' });
     public cache = Option.Boolean('--cache', true, { description: 'Enable filesystem caching.' });
-    public legacyArgs = Option.Rest();
+    public sessionFile = Option.String('--session-file', {
+        description: 'Override the dev session file path used for list, stop, or the active dev server.',
+    });
+    public replaceExisting = Option.Boolean('--replace-existing', false, {
+        description: 'Stop the existing matching dev session before starting a new one.',
+    });
+    public all = Option.Boolean('--all', false, {
+        description: 'When used with `dev stop`, stop every tracked dev session for the current app root.',
+    });
+    public stale = Option.Boolean('--stale', false, {
+        description: 'Filter `dev list` or `dev stop --all` to stale tracked sessions only.',
+    });
+    public args = Option.Rest();
 
     public async execute() {
-        assertNoLegacyArgs('dev', this.legacyArgs);
-        this.setCliArgs({ port: this.port ?? '', cache: this.cache });
+        const [maybeAction = '', ...restArgs] = this.args;
+        const action = maybeAction === 'list' || maybeAction === 'stop' ? maybeAction : '';
+
+        assertNoLegacyArgs('dev', action ? restArgs : this.args);
+        this.setCliArgs({
+            action: action || 'start',
+            port: this.port ?? '',
+            cache: this.cache,
+            json: this.json,
+            sessionFile: this.sessionFile ?? '',
+            replaceExisting: this.replaceExisting,
+            all: this.all,
+            stale: this.stale,
+        });
         await runCommandModule(() => import('../commands/dev'));
     }
 }
@@ -113,6 +138,15 @@ class BuildCommand extends ProteumCommand {
     public prod = Option.Boolean('--prod', false, { description: 'Build in production mode.' });
     public cache = Option.Boolean('--cache', false, { description: 'Enable filesystem caching during the build.' });
     public analyze = Option.Boolean('--analyze', false, { description: 'Emit the client bundle analysis report.' });
+    public analyzeServe = Option.Boolean('--analyze-serve', false, {
+        description: 'Serve the bundle analysis over HTTP instead of only writing a static report.',
+    });
+    public analyzeHost = Option.String('--analyze-host', {
+        description: 'Host used by the analyzer HTTP server when `--analyze-serve` is enabled.',
+    });
+    public analyzePort = Option.String('--analyze-port', {
+        description: 'Port used by the analyzer HTTP server when `--analyze-serve` is enabled. Use `auto` for an ephemeral port.',
+    });
     public strict = Option.Boolean('--strict', false, {
         description: 'Refresh generated typings and fail the build if TypeScript reports any error.',
     });
@@ -125,6 +159,9 @@ class BuildCommand extends ProteumCommand {
             prod: this.prod,
             cache: this.cache,
             analyze: this.analyze,
+            analyzeServe: this.analyzeServe,
+            analyzeHost: this.analyzeHost ?? '',
+            analyzePort: this.analyzePort ?? '',
             strict: this.strict,
         } satisfies TArgsObject;