proteum 2.1.7 → 2.1.9

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,60 @@ 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 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 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 +135,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 +145,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 +247,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 +341,124 @@ 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] : []),
+        ].filter((rootPath, index, list) => list.indexOf(rootPath) === index && fs.existsSync(rootPath));
+    }
+
+    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 searchPaths = preferApp
+            ? [this.appRoot, this.framework.activeRoot]
+            : [this.framework.activeRoot, this.appRoot];
+        return path.dirname(resolvePackageJsonPath(packageName, searchPaths));
+    }
+
+    public resolveRequest(request: string, { preferApp = true }: { preferApp?: boolean } = {}): string {
+        const searchPaths = preferApp
+            ? [this.appRoot, this.framework.activeRoot]
+            : [this.framework.activeRoot, this.appRoot];
+        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/`.',
         ],

package/cli/presentation/devSession.ts

@@ -1,17 +1,12 @@
 const React = require('react') as typeof import('react');
 
+import type { TServerReadyConnectedProject } from '../../common/dev/serverHotReload';
 import { renderRows } from './layout';
 import { renderInk } from './ink';
+import { renderWelcomePanel } from './welcome';
 
-const ProteumWordmark = [
-    String.raw` ____  ____   ___ _____ _____ _   _ __  __`,
-    String.raw`|  _ \|  _ \ / _ \_   _| ____| | | |  \/  |`,
-    String.raw`| |_) | |_) | | | || | |  _| | | | | |\/| |`,
-    String.raw`|  __/|  _ <| |_| || | | |___| |_| | |  | |`,
-    String.raw`|_|   |_| \_\\___/ |_| |_____|\___/|_|  |_|`,
-];
-
-const ProteumTagline = 'Agent-first SSR compiler and server loop.';
+const formatConnectedProjectLabel = (connectedProject: TServerReadyConnectedProject) =>
+    `${connectedProject.namespace} -> ${connectedProject.name}`;
 
 export const renderDevSession = async ({
     appName,
@@ -19,6 +14,7 @@ export const renderDevSession = async ({
     routerPort,
     devEventPort,
     connectedProjects,
+    proteumInstallSummary,
     proteumVersion,
 }: {
     appName: string;
@@ -26,24 +22,14 @@ export const renderDevSession = async ({
     routerPort: number;
     devEventPort: number;
     connectedProjects?: Array<{ namespace: string; urlInternal: string }>;
+    proteumInstallSummary?: string;
     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({
+            installSummary: proteumInstallSummary,
+            version: proteumVersion,
+            tagline: 'Agent-first SSR compiler and server loop.',
         }),
         renderRows(
             [
@@ -61,7 +47,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 },
         ),
@@ -71,15 +58,16 @@ export const renderServerReadyBanner = async ({
     appName,
     publicUrl,
     routerPort,
-    connectedProjectsCount,
+    connectedProjects,
 }: {
     appName: string;
     publicUrl: string;
     routerPort: number;
-    connectedProjectsCount?: number;
+    connectedProjects?: TServerReadyConnectedProject[];
 }) =>
     renderInk(({ Box, Text }) => {
         const createElement = React.createElement;
+        const verifiedConnectedProjects = connectedProjects || [];
 
         return createElement(
             Box,
@@ -88,13 +76,20 @@ export const renderServerReadyBanner = async ({
             createElement(Text, { bold: true, color: 'green' }, appName),
             createElement(Text, { bold: true }, publicUrl),
             createElement(Text, { dimColor: true }, 'SSR server is listening for requests and hot reloads.'),
-            connectedProjectsCount
+            verifiedConnectedProjects.length > 0
                 ? createElement(
                       Text,
                       { dimColor: true },
-                      `Connected projects: ${connectedProjectsCount}`,
+                      `Connected apps: ${verifiedConnectedProjects.map((connectedProject) => formatConnectedProjectLabel(connectedProject)).join(', ')}`,
                   )
                 : null,
+            ...verifiedConnectedProjects.map((connectedProject) =>
+                createElement(
+                    Text,
+                    { key: `connected-ping-${connectedProject.namespace}`, dimColor: true },
+                    `Ping OK: ${formatConnectedProjectLabel(connectedProject)} responded to /api/__proteum/connected/ping`,
+                ),
+            ),
             createElement(Text, { dimColor: true }, `Diagnose /: proteum diagnose / --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Perf top: proteum perf top --port ${routerPort}`),
             createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),

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,69 @@
+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 ({
+    installSummary,
+    version,
+    tagline,
+}: {
+    installSummary?: string;
+    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,
+            installSummary ? createElement(Text, { dimColor: true }, `Installed via ${installSummary}`) : null,
+            createElement(Text, { dimColor: true }, tagline),
+        );
+    });
+
+export const renderCliWelcomeBanner = async ({
+    command,
+    installSummary,
+    version,
+}: {
+    command: string;
+    installSummary?: string;
+    version: string;
+}) =>
+    [
+        await renderWelcomePanel({
+            installSummary,
+            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;