proteum 2.0.0 → 2.1.0

package/cli/presentation/devSession.ts

@@ -0,0 +1,70 @@
+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 renderDevSession = async ({
+    appName,
+    appRoot,
+    routerPort,
+    devEventPort,
+}: {
+    appName: string;
+    appRoot: string;
+    routerPort: number;
+    devEventPort: number;
+}) =>
+    [
+        await renderInk(({ Box, Text }) => {
+            const createElement = React.createElement;
+            const wordmark = ProteumWordmark.map((line) =>
+                createElement(Text, { key: line, bold: true, color: 'cyan' }, line),
+            );
+
+            return createElement(
+                Box,
+                { borderStyle: 'round', borderColor: 'cyan', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+                createElement(Text, { bold: true, color: 'green' }, 'PROTEUM DEV'),
+                createElement(Text, { dimColor: true }, 'Agent-first SSR compiler and server loop.'),
+                createElement(Box, { flexDirection: 'column', marginTop: 1 }, ...wordmark),
+            );
+        }),
+        renderRows(
+            [
+                { label: 'app', value: appName },
+                { label: 'root', value: appRoot },
+                { label: 'router', value: `http://localhost:${routerPort}` },
+                { label: 'hmr', value: `http://localhost:${devEventPort}/__proteum_hmr` },
+                { label: 'hotkeys', value: 'Ctrl+R reload, Ctrl+C stop' },
+            ],
+            { minLabelWidth: 12, maxLabelWidth: 12 },
+        ),
+    ].join('\n\n');
+
+export const renderServerReadyBanner = async ({
+    appName,
+    publicUrl,
+}: {
+    appName: string;
+    publicUrl: string;
+}) =>
+    renderInk(({ Box, Text }) => {
+        const createElement = React.createElement;
+
+        return createElement(
+            Box,
+            { borderStyle: 'round', borderColor: 'green', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+            createElement(Text, { bold: true, backgroundColor: 'green', color: 'black' }, ' SERVER READY '),
+            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.'),
+        );
+    });

package/cli/presentation/help.ts

@@ -0,0 +1,193 @@
+import { renderRows, wrapText } from './layout';
+import {
+    getInitAvailabilityNote,
+    isLikelyProteumAppRoot,
+    proteumCommandGroups,
+    proteumCommandNames,
+    proteumCommands,
+    proteumRecommendedFlow,
+    type TProteumCommandName,
+} from './commands';
+import { renderSection, renderTitle } from './ink';
+
+type TCommandDefinition = {
+    options: Array<{
+        preferredName: string;
+        definition: string;
+        description?: string;
+        required: boolean;
+    }>;
+} | null;
+
+type THelpRequest =
+    | { kind: 'none' }
+    | { kind: 'overview' }
+    | { kind: 'command'; commandName: TProteumCommandName };
+
+const commandNameSet = new Set<TProteumCommandName>(proteumCommandNames);
+
+const renderExamples = (examples: Array<{ description: string; command: string }>) =>
+    examples
+        .map((example) =>
+            [
+                `  ${example.command}`,
+                wrapText(example.description, { indent: '      ', nextIndent: '      ' }),
+            ].join('\n'),
+        )
+        .join('\n');
+
+const renderNotes = (notes: string[]) =>
+    notes.map((note) => wrapText(note, { indent: '  - ', nextIndent: '    ' })).join('\n');
+
+const renderOptions = (definition: TCommandDefinition) => {
+    if (!definition || definition.options.length === 0) return '  This command has no options.';
+
+    return renderRows(
+        definition.options.map((option) => ({
+            label: option.definition,
+            value: option.description || 'No description.',
+        })),
+        { minLabelWidth: 18, maxLabelWidth: 34 },
+    );
+};
+
+export const resolveCustomHelpRequest = (argv: string[]): THelpRequest => {
+    if (argv.length === 0) return { kind: 'overview' };
+    if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help')) return { kind: 'overview' };
+
+    if (argv[0] === 'help' && commandNameSet.has(argv[1] as TProteumCommandName))
+        return { kind: 'command', commandName: argv[1] as TProteumCommandName };
+
+    if (commandNameSet.has(argv[0] as TProteumCommandName) && argv.some((arg) => arg === '--help' || arg === '-h'))
+        return { kind: 'command', commandName: argv[0] as TProteumCommandName };
+
+    return { kind: 'none' };
+};
+
+export const renderCliOverview = async ({
+    version,
+    workdir,
+    initAvailable,
+}: {
+    version: string;
+    workdir: string;
+    initAvailable: boolean;
+}) => {
+    const sections: string[] = [];
+
+    sections.push(
+        await renderTitle(
+            `PROTEUM ${version}`,
+            'Explicit SSR / SEO / TypeScript framework for agent-friendly apps.',
+        ),
+    );
+
+    sections.push(
+        await renderSection(
+            'Recommended flow',
+            renderRows(proteumRecommendedFlow, { minLabelWidth: 24, maxLabelWidth: 24 }),
+        ),
+    );
+
+    const groupedCommands = await Promise.all(
+        proteumCommandGroups.map(async (group) =>
+            renderSection(
+                group.title,
+                renderRows(
+                    group.names.map((name) => {
+                        const command = proteumCommands[name];
+                        const initNote = name === 'init' ? ` ${getInitAvailabilityNote(initAvailable)}` : '';
+                        const status = command.status === 'experimental' ? ' Experimental.' : '';
+
+                        return {
+                            label: command.name === 'init' ? command.usage : `proteum ${command.name}`,
+                            value: `${command.summary}${status}${initNote}`,
+                        };
+                    }),
+                    { minLabelWidth: 18, maxLabelWidth: 24 },
+                ),
+            ),
+        ),
+    );
+
+    sections.push(groupedCommands.join('\n\n'));
+
+    if (!isLikelyProteumAppRoot(workdir)) {
+        sections.push(
+            await renderSection(
+                'Context',
+                renderRows([
+                    { label: 'current directory', value: workdir },
+                    {
+                        label: 'note',
+                        value: 'This directory does not look like a Proteum app root. Run dev, refresh, build, check, doctor, and explain inside an app where `client/` and `server/` exist.',
+                    },
+                ]),
+            ),
+        );
+    }
+
+    sections.push(
+        await renderSection(
+            'Next',
+            [
+                wrapText('Run `proteum <command> --help` or `proteum help <command>` for full options and examples.', {
+                    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: '  ',
+                }),
+                wrapText('Add `--verbose` when you want compiler internals, watch-cycle chatter, and framework setup logs.', {
+                    indent: '  ',
+                    nextIndent: '  ',
+                }),
+            ].join('\n'),
+        ),
+    );
+
+    return `${sections.join('\n\n')}\n`;
+};
+
+export const renderCommandHelp = async ({
+    commandName,
+    definition,
+    workdir,
+    initAvailable,
+}: {
+    commandName: TProteumCommandName;
+    definition: TCommandDefinition;
+    workdir: string;
+    initAvailable: boolean;
+}) => {
+    const command = proteumCommands[commandName];
+    const sections: string[] = [];
+    const notes = [...(command.notes ?? [])];
+
+    if (commandName === 'init') notes.push(getInitAvailabilityNote(initAvailable));
+    if (commandName !== 'init' && !isLikelyProteumAppRoot(workdir)) {
+        notes.push(
+            'This command expects to run inside a Proteum app root. The current directory does not contain the usual `client/` and `server/` folders.',
+        );
+    }
+
+    sections.push(await renderTitle(`PROTEUM ${command.name.toUpperCase()}`, command.summary));
+    sections.push(await renderSection('Usage', `  ${command.usage}`));
+    sections.push(
+        await renderSection(
+            'Category',
+            wrapText(`${command.category}${command.status === 'experimental' ? ' · experimental' : ''}`, {
+                indent: '  ',
+                nextIndent: '  ',
+            }),
+        ),
+    );
+    sections.push(await renderSection('Best for', wrapText(command.bestFor, { indent: '  ', nextIndent: '  ' })));
+    sections.push(await renderSection('Options', renderOptions(definition)));
+    sections.push(await renderSection('Examples', renderExamples(command.examples)));
+
+    if (notes.length > 0) sections.push(await renderSection('Notes', renderNotes(notes)));
+
+    return `${sections.join('\n\n')}\n`;
+};

package/cli/presentation/ink.ts

@@ -0,0 +1,69 @@
+const React = require('react') as typeof import('react');
+
+import { importEsm } from '../runtime/importEsm';
+import { getTerminalWidth } from './layout';
+
+type TInkModule = typeof import('ink');
+type TInkUiModule = typeof import('@inkjs/ui');
+
+type TInkRuntime = {
+    Box: TInkModule['Box'];
+    Text: TInkModule['Text'];
+    renderToString: TInkModule['renderToString'];
+    StatusMessage: TInkUiModule['StatusMessage'];
+};
+
+let inkRuntimePromise: Promise<TInkRuntime> | undefined;
+
+const loadInkRuntime = () => {
+    if (inkRuntimePromise) return inkRuntimePromise;
+
+    inkRuntimePromise = Promise.all([
+        importEsm<TInkModule>('ink'),
+        importEsm<TInkUiModule>('@inkjs/ui'),
+    ]).then(([ink, inkUi]) => ({
+        Box: ink.Box,
+        Text: ink.Text,
+        renderToString: ink.renderToString,
+        StatusMessage: inkUi.StatusMessage,
+    }));
+
+    return inkRuntimePromise;
+};
+
+export const renderInk = async (
+    buildNode: (runtime: TInkRuntime) => import('react').ReactElement | null,
+    columns = getTerminalWidth(),
+) => {
+    const runtime = await loadInkRuntime();
+    return runtime.renderToString(buildNode(runtime), { columns });
+};
+
+export const renderTitle = async (title: string, subtitle?: string) =>
+    renderInk(({ Box, Text }) => {
+        const createElement = React.createElement;
+
+        return createElement(
+            Box,
+            { flexDirection: 'column' },
+            createElement(Text, { bold: true, color: 'cyan' }, title),
+            subtitle ? createElement(Text, { dimColor: true }, subtitle) : null,
+        );
+    });
+
+export const renderSection = async (title: string, body: string) => {
+    const heading = await renderInk(({ Text }) => React.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}`));
+
+const renderStatusMessage = async (variant: 'success' | 'warning' | 'error', message: string) =>
+    renderInk(({ StatusMessage }) => React.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);

package/cli/presentation/layout.ts

@@ -0,0 +1,83 @@
+const ansiPattern = /\u001b\[[0-9;]*m/g;
+
+export type TRow = {
+    label: string;
+    value: string;
+};
+
+export const stripAnsi = (value: string) => value.replace(ansiPattern, '');
+
+const visibleLength = (value: string) => stripAnsi(value).length;
+
+export const getTerminalWidth = () => {
+    const width = process.stdout.columns ?? 100;
+    return Math.max(72, Math.min(width, 110));
+};
+
+export const wrapText = (
+    value: string,
+    {
+        width = getTerminalWidth(),
+        indent = '',
+        nextIndent = indent,
+    }: {
+        width?: number;
+        indent?: string;
+        nextIndent?: string;
+    } = {},
+) => {
+    const words = value.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0) return indent.trimEnd();
+
+    const lines: string[] = [];
+    let currentLine = indent;
+
+    for (const word of words) {
+        const separator = currentLine.trim().length === 0 ? '' : ' ';
+        const nextLine = `${currentLine}${separator}${word}`;
+
+        if (visibleLength(nextLine) > width && currentLine.trim().length > 0) {
+            lines.push(currentLine);
+            currentLine = `${nextIndent}${word}`;
+            continue;
+        }
+
+        currentLine = nextLine;
+    }
+
+    lines.push(currentLine);
+    return lines.join('\n');
+};
+
+export const renderRows = (
+    rows: TRow[],
+    {
+        indent = '  ',
+        minLabelWidth = 14,
+        maxLabelWidth = 28,
+    }: {
+        indent?: string;
+        minLabelWidth?: number;
+        maxLabelWidth?: number;
+    } = {},
+) => {
+    if (rows.length === 0) return `${indent}none`;
+
+    const width = getTerminalWidth();
+    const labelWidth = Math.min(
+        maxLabelWidth,
+        Math.max(
+            minLabelWidth,
+            ...rows.map((row) => visibleLength(row.label)),
+        ),
+    );
+
+    return rows
+        .map((row) => {
+            const paddedLabel = `${row.label}${' '.repeat(Math.max(labelWidth - visibleLength(row.label), 0))}`;
+            const prefix = `${indent}${paddedLabel}  `;
+            const continuation = `${indent}${' '.repeat(labelWidth)}  `;
+            return wrapText(row.value, { width, indent: prefix, nextIndent: continuation });
+        })
+        .join('\n');
+};

package/cli/runtime/argv.ts

@@ -0,0 +1,49 @@
+import { UsageError } from 'clipanion';
+
+import type { TArgsObject } from '../context';
+
+export const normalizeLegacyArgv = (argv: string[]) =>
+    argv.map((arg) => {
+        if (!/^-[-A-Za-z0-9]+$/.test(arg)) return arg;
+        if (arg.startsWith('--')) return arg;
+        if (arg.length <= 2) return arg;
+
+        return `--${arg.substring(1)}`;
+    });
+
+export const normalizeHelpArgv = (argv: string[], commandNames: readonly string[]) => {
+    if (argv.length === 0) return argv;
+    if (!commandNames.includes(argv[0])) return argv;
+    if (!argv.includes('--help') && !argv.includes('-h')) return argv;
+
+    return [argv[0], '--help'];
+};
+
+export const createArgs = (args: TArgsObject = {}) => ({ workdir: process.cwd(), ...args });
+
+export const applyLegacyBooleanArgs = (
+    commandName: string,
+    legacyArgs: readonly string[],
+    allowedArgs: readonly string[],
+    args: TArgsObject,
+) => {
+    const allowedArgsSet = new Set(allowedArgs);
+
+    for (const legacyArg of legacyArgs) {
+        if (!allowedArgsSet.has(legacyArg)) {
+            throw new UsageError(
+                `Unknown ${commandName} argument: ${legacyArg}. Allowed values: ${allowedArgs.join(', ') || 'none'}.`,
+            );
+        }
+
+        args[legacyArg] = true;
+    }
+};
+
+export const assertNoLegacyArgs = (commandName: string, legacyArgs: readonly string[]) => {
+    if (legacyArgs.length === 0) return;
+
+    throw new UsageError(
+        `${commandName} does not accept positional arguments. Received: ${legacyArgs.join(', ')}.`,
+    );
+};

package/cli/runtime/command.ts

@@ -0,0 +1,25 @@
+import { Command, Option } from 'clipanion';
+
+import cli, { type TArgsObject } from '../context';
+import { createClipanionUsage, proteumCommands, type TProteumCommandName } from '../presentation/commands';
+import { createArgs } from './argv';
+
+type TRunModule = { run: () => Promise<void> };
+
+export const runCommandModule = async (loader: () => Promise<TRunModule>) => {
+    const module = await loader();
+    await module.run();
+};
+
+export abstract class ProteumCommand extends Command {
+    public verbose = Option.Boolean('-v,--verbose', false, {
+        description: 'Show verbose compiler, watcher, and framework setup logs.',
+    });
+
+    protected setCliArgs(args: TArgsObject = {}) {
+        cli.setArgs(createArgs({ ...args, verbose: this.verbose }));
+    }
+}
+
+export const buildUsage = (commandName: TProteumCommandName) =>
+    Command.Usage(createClipanionUsage(proteumCommands[commandName]));