proteum 2.1.1 → 2.1.3-1

package/cli/commands/sessionLocalRunner.js

@@ -0,0 +1,188 @@
+const path = require('path');
+const net = require('net');
+const { spawn } = require('child_process');
+const tsNode = require('ts-node');
+
+const resultMarker = '__PROTEUM_SESSION_RESULT__';
+
+const printPayload = (payload) => {
+    process.stdout.write(`${resultMarker}${JSON.stringify(payload)}\n`);
+};
+
+const fail = (error) => {
+    printPayload({ error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+};
+
+const getAvailablePort = async () =>
+    await new Promise((resolve, reject) => {
+        const server = net.createServer();
+
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+
+            if (!address || typeof address === 'string') {
+                server.close(() => reject(new Error('Could not determine a local port for the session runner.')));
+                return;
+            }
+
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                resolve(address.port);
+            });
+        });
+    });
+
+const closeMultiCompiler = async (multiCompiler) =>
+    await new Promise((resolve, reject) => {
+        multiCompiler.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+
+            resolve();
+        });
+    });
+
+const runCompiler = async (compiler) => {
+    const multiCompiler = await compiler.create();
+
+    try {
+        await new Promise((resolve, reject) => {
+            multiCompiler.run((error, stats) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                if (stats && stats.hasErrors()) {
+                    reject(new Error('Compilation failed for the local dev session runner.'));
+                    return;
+                }
+
+                resolve();
+            });
+        });
+    } finally {
+        compiler.dispose();
+        await closeMultiCompiler(multiCompiler);
+    }
+};
+
+const waitForServerReady = async (child) =>
+    await new Promise((resolve, reject) => {
+        let settled = false;
+
+        const finish = (callback, value) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeout);
+            child.off('message', onMessage);
+            child.off('error', onError);
+            child.off('exit', onExit);
+            callback(value);
+        };
+
+        const onMessage = (message) => {
+            if (!message || message.type !== 'proteum:server-ready' || typeof message.publicUrl !== 'string') return;
+            finish(resolve, message.publicUrl);
+        };
+
+        const onError = (error) => finish(reject, error);
+        const onExit = (code, signal) =>
+            finish(reject, new Error(`Local session server exited before becoming ready (code=${code}, signal=${signal}).`));
+        const timeout = setTimeout(
+            () => finish(reject, new Error('Timed out while waiting for the local session server to become ready.')),
+            30000,
+        );
+
+        child.on('message', onMessage);
+        child.once('error', onError);
+        child.once('exit', onExit);
+    });
+
+const stopServerProcess = async (child) => {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+
+    child.kill('SIGTERM');
+
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+        }, 5000);
+
+        child.once('exit', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+};
+
+const requestSession = async (baseUrl, email, role) => {
+    const response = await fetch(`${baseUrl}/__proteum/session/start`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(role ? { email, role } : { email }),
+    });
+    const body = await response.json();
+
+    if (response.status >= 400) {
+        throw new Error((body && body.error) || `Session request failed with status ${response.status}.`);
+    }
+
+    return { baseUrl, response: body };
+};
+
+(async () => {
+    const [, , appRootArg = '', email = '', role = ''] = process.argv;
+    const appRoot = path.resolve(appRootArg);
+
+    if (!appRootArg || !email) {
+        fail(new Error('sessionLocalRunner requires <appRoot> and <email>.'));
+        return;
+    }
+
+    process.chdir(appRoot);
+
+    tsNode.register({
+        transpileOnly: true,
+        project: path.join(__dirname, '..', 'tsconfig.json'),
+        files: true,
+    });
+
+    const port = await getAvailablePort();
+    const cli = require('../context.ts').default;
+    cli.setArgs({ workdir: appRoot, port: String(port), url: '', json: true });
+
+    const app = require('../app/index.ts').default;
+    const Compiler = require('../compiler/index.ts').default;
+
+    if (app.env.profile !== 'dev') {
+        fail(new Error(`Proteum sessions are only available when ENV_PROFILE=dev. Current profile: ${app.env.profile}.`));
+        return;
+    }
+
+    const compiler = new Compiler('dev');
+    await runCompiler(compiler);
+
+    const serverProcess = spawn(process.execPath, ['--preserve-symlinks', path.join(app.outputPath('dev'), 'server.js')], {
+        cwd: app.paths.root,
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+    });
+
+    try {
+        const baseUrl = await waitForServerReady(serverProcess);
+        const session = await requestSession(baseUrl, email, role);
+        printPayload({ session });
+    } finally {
+        await stopServerProcess(serverProcess);
+    }
+})().catch((error) => {
+    fail(error);
+});

package/cli/commands/trace.ts

@@ -75,6 +75,9 @@ const getTraceErrorMessage = (body: TRequestTraceErrorResponse | object | string
     return `Trace request failed with status ${statusCode}.`;
 };
 
+const hasStructuredTraceError = (body: TRequestTraceErrorResponse | object | string | undefined): body is TRequestTraceErrorResponse =>
+    typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string';
+
 const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GET' | 'POST'; json?: object }) => {
     const attempts: string[] = [];
 
@@ -89,6 +92,11 @@ const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GE
             });
 
             if (response.statusCode >= 400) {
+                if (response.statusCode === 404 && !hasStructuredTraceError(response.body as TRequestTraceErrorResponse | object | string | undefined)) {
+                    attempts.push(`${baseUrl}${pathname}: returned 404`);
+                    continue;
+                }
+
                 throw new TraceResponseError(
                     getTraceErrorMessage(response.body as TRequestTraceErrorResponse | object | string | undefined, response.statusCode),
                 );

package/cli/index.ts

@@ -1,6 +1,5 @@
 process.traceDeprecation = true;
 
-import fs from 'fs';
 import { Cli } from 'clipanion';
 
 import cli from './context';
@@ -9,12 +8,10 @@ import { renderCliOverview, renderCommandHelp, resolveCustomHelpRequest } from '
 import { normalizeHelpArgv, normalizeLegacyArgv } from './runtime/argv';
 import { createCli, registeredCommands } from './runtime/commands';
 
-const hasInitScaffold = () => fs.existsSync(`${cli.paths.core.cli}/skeleton`);
-
 export const runCli = async (argv: string[] = process.argv.slice(2)) => {
     const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
     const clipanion = createCli(String(cli.packageJson.version || ''));
-    const initAvailable = hasInitScaffold();
+    const initAvailable = true;
     const helpRequest = resolveCustomHelpRequest(normalizedArgv);
 
     if (helpRequest.kind === 'overview') {

package/cli/presentation/commands.ts

@@ -5,6 +5,7 @@ import type { TRow } from './layout';
 
 export const proteumCommandNames = [
     'init',
+    'create',
     'dev',
     'refresh',
     'build',
@@ -15,6 +16,7 @@ export const proteumCommandNames = [
     'explain',
     'trace',
     'command',
+    'session',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -47,21 +49,56 @@ export const proteumRecommendedFlow: TRow[] = [
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
-    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command'] },
-    { title: 'Project scaffolding', names: ['init'] },
+    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command', 'session'] },
+    { title: 'Project scaffolding', names: ['init', 'create'] },
 ];
 
 export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> = {
     init: {
         name: 'init',
         category: 'Project scaffolding',
-        summary: 'Scaffold a new Proteum project.',
-        usage: 'proteum init',
-        bestFor: 'Bootstrap a new app when the Proteum scaffold assets are installed in the current package.',
-        examples: [{ description: 'Create a new app interactively', command: 'proteum init' }],
+        summary: 'Scaffold a new Proteum app with deterministic built-in templates.',
+        usage: 'proteum init [directory] [--name <name>] [--identifier <identifier>] [--port <port>] [--install] [--dry-run] [--json]',
+        bestFor: 'Bootstrapping a new app in a way that is explicit, machine-readable, and safe for LLM coding agents.',
+        examples: [
+            { description: 'Create a new app in ./my-app', command: 'proteum init my-app --name "My App"' },
+            {
+                description: 'Scaffold an app and install dependencies immediately',
+                command: 'proteum init my-app --name "My App" --install',
+            },
+            {
+                description: 'Emit scaffold details as JSON for an agent',
+                command: 'proteum init my-app --name "My App" --json',
+            },
+            {
+                description: 'Preview the full app scaffold without writing files',
+                command: 'proteum init my-app --name "My App" --dry-run --json',
+            },
+        ],
         notes: [
-            'This command is still experimental.',
-            'In source checkouts it requires `cli/skeleton` to exist.',
+            'When Proteum is invoked from a local framework checkout, init writes a file: dependency to that checkout by default.',
+            'Use `--dry-run --json` when an agent needs a machine-readable app scaffold plan before writing files.',
+            'Without `--install`, init only writes files and does not touch the network.',
+        ],
+        status: 'experimental',
+    },
+    create: {
+        name: 'create',
+        category: 'Project scaffolding',
+        summary: 'Generate a page, controller, command, route, or root service inside a Proteum app.',
+        usage: 'proteum create <page|controller|command|route|service> <target> [--route <url>] [--method <name>] [--http-method <verb>] [--dry-run] [--json]',
+        bestFor: 'Fast deterministic scaffolding inside an existing Proteum app without inventing file layouts or boilerplate by hand.',
+        examples: [
+            { description: 'Create a new SSR page', command: 'proteum create page marketing/faq --route /faq' },
+            { description: 'Create a new controller', command: 'proteum create controller Founder/projects --method list' },
+            { description: 'Create a new command', command: 'proteum create command diagnostics --method ping' },
+            { description: 'Preview a new route without writing files', command: 'proteum create route webhooks/stripe --dry-run --json' },
+            { description: 'Create and register a new root service', command: 'proteum create service Conversion/Plans' },
+        ],
+        notes: [
+            'Page scaffolds write `client/pages/**/index.tsx` and default the route path from the logical target path unless `--route` is provided.',
+            'Service scaffolds create `server/services/**/index.ts`, `service.json`, a config export under `server/config/*.ts`, and then try to register the new root service in `server/index.ts`.',
+            'Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.',
         ],
         status: 'experimental',
     },
@@ -238,6 +275,31 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
+    session: {
+        name: 'session',
+        category: 'Manifest and contracts',
+        summary: 'Mint a dev-only auth session token and cookie payload for a known user.',
+        usage: 'proteum session <email> [--role <role>] [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Starting browser or API automation from an authenticated state without driving the login UI, while still using the app-configured auth service.',
+        examples: [
+            {
+                description: 'Mint an admin session for a running dev server',
+                command: 'proteum session admin@example.com --role ADMIN --port 3101',
+            },
+            {
+                description: 'Mint a GOD session for unique.domains and print machine-readable cookie data',
+                command: 'proteum session god@example.com --role GOD --json',
+            },
+        ],
+        notes: [
+            'Sessions are available only in dev mode and use the auth service registered on the current app router.',
+            'You must provide the target user email explicitly; Proteum does not guess your admin account universally across apps.',
+            'The command returns a token plus Playwright-ready cookie JSON so agents can inject the session into a browser context directly.',
+            'Without `--port` or `--url`, Proteum refreshes generated artifacts, builds the dev output, starts a temporary local dev server, creates the session, prints the payload, and exits.',
+        ],
+        status: 'experimental',
+    },
 };
 
 export const isLikelyProteumAppRoot = (workdir: string) =>
@@ -248,8 +310,8 @@ export const isLikelyProteumAppRoot = (workdir: string) =>
 
 export const getInitAvailabilityNote = (initAvailable: boolean) =>
     initAvailable
-        ? 'Scaffold assets are installed in this checkout.'
-        : 'This checkout does not include `cli/skeleton`, so `proteum init` is unavailable until the scaffold assets are restored.';
+        ? 'Init is built into the CLI and does not depend on external scaffold assets.'
+        : 'Init scaffolding is currently unavailable in this checkout.';
 
 export const createClipanionUsage = (command: TProteumCommandDoc) => ({
     category: command.category,

package/cli/presentation/devSession.ts

@@ -11,6 +11,8 @@ const ProteumWordmark = [
     String.raw`|_|   |_| \_\\___/ |_| |_____|\___/|_|  |_|`,
 ];
 
+const ProteumTagline = 'Agent-first SSR compiler and server loop.';
+
 export const renderDevSession = async ({
     appName,
     appRoot,
@@ -32,9 +34,9 @@ export const renderDevSession = async ({
             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),
+                createElement(Text, { bold: true, backgroundColor: 'cyan', color: 'black' }, ' WELCOME TO '),
+                createElement(Box, { flexDirection: 'column' }, ...wordmark),
+                createElement(Text, { dimColor: true }, ProteumTagline),
             );
         }),
         renderRows(
@@ -73,3 +75,15 @@ export const renderServerReadyBanner = async ({
             createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),
         );
     });
+
+export const renderDevShutdownBanner = async () =>
+    renderInk(({ Box, Text }) => {
+        const createElement = React.createElement;
+
+        return createElement(
+            Box,
+            { borderStyle: 'round', borderColor: 'yellow', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+            createElement(Text, { bold: true, backgroundColor: 'yellow', color: 'black' }, ' SHUTTING DOWN '),
+            createElement(Text, { bold: true, color: 'yellow' }, 'Thank you for developping with Proteum'),
+        );
+    });