proteum 2.1.7 → 2.1.9-1

package/cli/presentation/devSession.ts

@@ -1,17 +1,10 @@
-const React = require('react') as typeof import('react');
-
+import type { TServerReadyConnectedProject } from '../../common/dev/serverHotReload';
 import { renderRows } from './layout';
-import { renderInk } from './ink';
-
-const ProteumWordmark = [
-    String.raw` ____  ____   ___ _____ _____ _   _ __  __`,
-    String.raw`|  _ \|  _ \ / _ \_   _| ____| | | |  \/  |`,
-    String.raw`| |_) | |_) | | | || | |  _| | | | | |\/| |`,
-    String.raw`|  __/|  _ <| |_| || | | |___| |_| | |  | |`,
-    String.raw`|_|   |_| \_\\___/ |_| |_____|\___/|_|  |_|`,
-];
+import { CliReact, renderInk } from './ink';
+import { renderWelcomePanel } from './welcome';
 
-const ProteumTagline = 'Agent-first SSR compiler and server loop.';
+const formatConnectedProjectLabel = (connectedProject: TServerReadyConnectedProject) =>
+    `${connectedProject.namespace} -> ${connectedProject.name}`;
 
 export const renderDevSession = async ({
     appName,
@@ -19,6 +12,7 @@ export const renderDevSession = async ({
     routerPort,
     devEventPort,
     connectedProjects,
+    proteumInstallSummary,
     proteumVersion,
 }: {
     appName: string;
@@ -26,24 +20,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 +45,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 +56,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 createElement = CliReact.createElement;
+        const verifiedConnectedProjects = connectedProjects || [];
 
         return createElement(
             Box,
@@ -88,13 +74,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 (/ping): ${formatConnectedProjectLabel(connectedProject)}`,
+                ),
+            ),
             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}`),
@@ -103,7 +96,7 @@ export const renderServerReadyBanner = async ({
 
 export const renderDevShutdownBanner = async () =>
     renderInk(({ Box, Text }) => {
-        const createElement = React.createElement;
+        const createElement = CliReact.createElement;
 
         return createElement(
             Box,

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/ink.ts

@@ -1,4 +1,4 @@
-const React = require('react') as typeof import('react');
+import { createRequire } from 'module';
 
 import { importEsm } from '../runtime/importEsm';
 import { getTerminalWidth } from './layout';
@@ -13,6 +13,9 @@ type TInkRuntime = {
     StatusMessage: TInkUiModule['StatusMessage'];
 };
 
+// Keep the CLI renderer on the exact React instance Ink resolved for this install shape.
+const CliReact = createRequire(require.resolve('ink'))('react') as typeof import('react');
+
 let inkRuntimePromise: Promise<TInkRuntime> | undefined;
 
 const loadInkRuntime = () => {
@@ -41,7 +44,7 @@ export const renderInk = async (
 
 export const renderTitle = async (title: string, subtitle?: string) =>
     renderInk(({ Box, Text }) => {
-        const createElement = React.createElement;
+        const createElement = CliReact.createElement;
 
         return createElement(
             Box,
@@ -52,18 +55,20 @@ export const renderTitle = async (title: string, subtitle?: string) =>
     });
 
 export const renderSection = async (title: string, body: string) => {
-    const heading = await renderInk(({ Text }) => React.createElement(Text, { bold: true }, title));
+    const heading = await renderInk(({ Text }) => CliReact.createElement(Text, { bold: true }, title));
     return `${heading}\n${body}`;
 };
 
 export const renderStep = async (label: string, message: string) =>
-    renderInk(({ Text }) => React.createElement(Text, { color: 'cyan' }, `${label} ${message}`));
+    renderInk(({ Text }) => CliReact.createElement(Text, { color: 'cyan' }, `${label} ${message}`));
 
 const renderStatusMessage = async (variant: 'success' | 'warning' | 'error', message: string) =>
-    renderInk(({ StatusMessage }) => React.createElement(StatusMessage, { variant }, message));
+    renderInk(({ StatusMessage }) => CliReact.createElement(StatusMessage, { variant }, message));
 
 export const renderSuccess = (message: string) => renderStatusMessage('success', message);
 
 export const renderWarning = (message: string) => renderStatusMessage('warning', message);
 
 export const renderDanger = (message: string) => renderStatusMessage('error', message);
+
+export { CliReact };

package/cli/presentation/welcome.ts

@@ -0,0 +1,67 @@
+import { renderRows } from './layout';
+import { CliReact, 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 = CliReact.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;
 

package/cli/runtime/devSessions.ts

@@ -0,0 +1,337 @@
+import path from 'path';
+
+import fs from 'fs-extra';
+
+export const devSessionRegistryVersion = 1 as const;
+
+export type TDevSessionState = 'starting' | 'ready';
+
+export type TDevSessionRecord = {
+    version: typeof devSessionRegistryVersion;
+    pid: number;
+    appRoot: string;
+    routerPort: number;
+    publicUrl: string;
+    startedAt: string;
+    updatedAt: string;
+    sessionFilePath: string;
+    state: TDevSessionState;
+};
+
+export type TDevSessionInspection = {
+    sessionFilePath: string;
+    record: TDevSessionRecord | null;
+    live: boolean;
+    stale: boolean;
+    invalid: boolean;
+    parseError: string;
+};
+
+export type TStopDevSessionResult = {
+    sessionFilePath: string;
+    pid: number | null;
+    routerPort: number | null;
+    publicUrl: string;
+    state: TDevSessionState | '';
+    matched: boolean;
+    stopped: boolean;
+    removed: boolean;
+    stale: boolean;
+    live: boolean;
+    invalid: boolean;
+    parseError: string;
+};
+
+const defaultRegistryDirectoryParts = ['var', 'run', 'proteum', 'dev'];
+
+const sleep = async (durationMs: number) => await new Promise((resolve) => setTimeout(resolve, durationMs));
+
+const isRecordShape = (value: unknown): value is TDevSessionRecord => {
+    if (!value || typeof value !== 'object') return false;
+
+    const candidate = value as Partial<TDevSessionRecord>;
+
+    return (
+        candidate.version === devSessionRegistryVersion &&
+        typeof candidate.pid === 'number' &&
+        Number.isInteger(candidate.pid) &&
+        candidate.pid > 0 &&
+        typeof candidate.appRoot === 'string' &&
+        candidate.appRoot.length > 0 &&
+        typeof candidate.routerPort === 'number' &&
+        Number.isInteger(candidate.routerPort) &&
+        candidate.routerPort > 0 &&
+        typeof candidate.publicUrl === 'string' &&
+        typeof candidate.startedAt === 'string' &&
+        typeof candidate.updatedAt === 'string' &&
+        typeof candidate.sessionFilePath === 'string' &&
+        candidate.sessionFilePath.length > 0 &&
+        (candidate.state === 'starting' || candidate.state === 'ready')
+    );
+};
+
+const canSignalProcess = (pid: number, signal: NodeJS.Signals | 0) => {
+    try {
+        process.kill(pid, signal);
+        return true;
+    } catch (error) {
+        const errno = error as NodeJS.ErrnoException;
+
+        if (errno.code === 'ESRCH') return false;
+        if (errno.code === 'EPERM') return true;
+
+        throw error;
+    }
+};
+
+export const isProcessAlive = (pid: number) => canSignalProcess(pid, 0);
+
+const waitForProcessExit = async (pid: number, timeoutMs: number) => {
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) return true;
+        await sleep(100);
+    }
+
+    return !isProcessAlive(pid);
+};
+
+export const getDevSessionRegistryDirectory = (appRoot: string) => path.join(appRoot, ...defaultRegistryDirectoryParts);
+
+export const resolveDevSessionFilePath = ({
+    appRoot,
+    port,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    port: number;
+    sessionFilePath?: string;
+}) => {
+    if (sessionFilePath && sessionFilePath.trim()) {
+        return path.isAbsolute(sessionFilePath)
+            ? path.normalize(sessionFilePath)
+            : path.resolve(appRoot, sessionFilePath);
+    }
+
+    return path.join(getDevSessionRegistryDirectory(appRoot), `${port}.json`);
+};
+
+export const createDevSessionRecord = ({
+    appRoot,
+    port,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    port: number;
+    sessionFilePath: string;
+}): TDevSessionRecord => {
+    const timestamp = new Date().toISOString();
+
+    return {
+        version: devSessionRegistryVersion,
+        pid: process.pid,
+        appRoot,
+        routerPort: port,
+        publicUrl: '',
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        sessionFilePath,
+        state: 'starting',
+    };
+};
+
+export const writeDevSessionRecord = async (record: TDevSessionRecord) => {
+    await fs.ensureDir(path.dirname(record.sessionFilePath));
+    await fs.writeJson(record.sessionFilePath, record, { spaces: 2 });
+};
+
+export const updateDevSessionRecord = async ({
+    sessionFilePath,
+    patch,
+}: {
+    sessionFilePath: string;
+    patch: Partial<Omit<TDevSessionRecord, 'version' | 'pid' | 'appRoot' | 'routerPort' | 'startedAt' | 'sessionFilePath'>>;
+}) => {
+    const inspection = await inspectDevSessionFile(sessionFilePath);
+    if (!inspection || !inspection.record) return;
+
+    await writeDevSessionRecord({
+        ...inspection.record,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    });
+};
+
+export const removeDevSessionRecord = async (sessionFilePath: string) => {
+    await fs.remove(sessionFilePath);
+};
+
+export const removeDevSessionRecordSync = (sessionFilePath: string) => {
+    try {
+        fs.removeSync(sessionFilePath);
+    } catch {
+        // Best-effort cleanup during process exit.
+    }
+};
+
+export const inspectDevSessionFile = async (sessionFilePath: string): Promise<TDevSessionInspection | null> => {
+    if (!(await fs.pathExists(sessionFilePath))) return null;
+
+    try {
+        const rawValue = await fs.readJson(sessionFilePath);
+        if (!isRecordShape(rawValue)) {
+            return {
+                sessionFilePath,
+                record: null,
+                live: false,
+                stale: true,
+                invalid: true,
+                parseError: 'Session file contents do not match the Proteum dev session schema.',
+            };
+        }
+
+        const record = rawValue;
+        const live = isProcessAlive(record.pid);
+
+        return {
+            sessionFilePath,
+            record,
+            live,
+            stale: !live,
+            invalid: false,
+            parseError: '',
+        };
+    } catch (error) {
+        return {
+            sessionFilePath,
+            record: null,
+            live: false,
+            stale: true,
+            invalid: true,
+            parseError: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+
+export const listDevSessionFiles = async ({
+    appRoot,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    sessionFilePath?: string;
+}) => {
+    if (sessionFilePath && sessionFilePath.trim())
+        return [resolveDevSessionFilePath({ appRoot, port: 1, sessionFilePath })];
+
+    const registryDirectory = getDevSessionRegistryDirectory(appRoot);
+    if (!(await fs.pathExists(registryDirectory))) return [];
+
+    const entries = await fs.readdir(registryDirectory);
+
+    return entries
+        .filter((entry) => entry.endsWith('.json'))
+        .sort((left, right) => left.localeCompare(right))
+        .map((entry) => path.join(registryDirectory, entry));
+};
+
+export const listDevSessionInspections = async ({
+    appRoot,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    sessionFilePath?: string;
+}) => {
+    const sessionFilePaths = await listDevSessionFiles({ appRoot, sessionFilePath });
+    const inspections = await Promise.all(sessionFilePaths.map((entryPath) => inspectDevSessionFile(entryPath)));
+
+    return inspections.filter((inspection): inspection is TDevSessionInspection => inspection !== null);
+};
+
+export const stopDevSessionFile = async (sessionFilePath: string): Promise<TStopDevSessionResult> => {
+    const inspection = await inspectDevSessionFile(sessionFilePath);
+
+    if (!inspection) {
+        return {
+            sessionFilePath,
+            pid: null,
+            routerPort: null,
+            publicUrl: '',
+            state: '',
+            matched: false,
+            stopped: false,
+            removed: false,
+            stale: false,
+            live: false,
+            invalid: false,
+            parseError: '',
+        };
+    }
+
+    if (!inspection.record) {
+        await removeDevSessionRecord(sessionFilePath);
+
+        return {
+            sessionFilePath,
+            pid: null,
+            routerPort: null,
+            publicUrl: '',
+            state: '',
+            matched: true,
+            stopped: true,
+            removed: true,
+            stale: true,
+            live: false,
+            invalid: true,
+            parseError: inspection.parseError,
+        };
+    }
+
+    const { record } = inspection;
+
+    if (!inspection.live) {
+        await removeDevSessionRecord(sessionFilePath);
+
+        return {
+            sessionFilePath,
+            pid: record.pid,
+            routerPort: record.routerPort,
+            publicUrl: record.publicUrl,
+            state: record.state,
+            matched: true,
+            stopped: true,
+            removed: true,
+            stale: true,
+            live: false,
+            invalid: false,
+            parseError: '',
+        };
+    }
+
+    if (canSignalProcess(record.pid, 'SIGTERM')) {
+        const exitedAfterTerm = await waitForProcessExit(record.pid, 5000);
+        if (!exitedAfterTerm && canSignalProcess(record.pid, 'SIGKILL')) {
+            await waitForProcessExit(record.pid, 2000);
+        }
+    }
+
+    const live = isProcessAlive(record.pid);
+    if (!live) {
+        await removeDevSessionRecord(sessionFilePath);
+    }
+
+    return {
+        sessionFilePath,
+        pid: record.pid,
+        routerPort: record.routerPort,
+        publicUrl: record.publicUrl,
+        state: record.state,
+        matched: true,
+        stopped: !live,
+        removed: !live,
+        stale: !live,
+        live,
+        invalid: false,
+        parseError: '',
+    };
+};