proteum 2.1.2 → 2.1.3-1

package/README.md

@@ -289,6 +289,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum explain` | Explain routes, controllers, services, layouts, conventions, and env |
 | `proteum trace` | Inspect live dev-only request traces from the running SSR server |
 | `proteum command` | Run a dev-only internal command locally or against a running dev server |
+| `proteum session` | Mint a dev-only auth session token and Playwright-ready cookie payload |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
@@ -311,6 +312,8 @@ proteum explain --routes --controllers --commands
 proteum explain --all --json
 proteum command proteum/diagnostics/ping
 proteum command proteum/diagnostics/ping --port 3101
+proteum session admin@example.com --role ADMIN --port 3101
+proteum session god@example.com --role GOD --json
 proteum trace requests
 proteum trace arm --capture deep
 proteum trace latest

package/cli/commands/command.ts

@@ -61,6 +61,9 @@ const getCommandErrorMessage = (body: TDevCommandErrorResponse | object | string
     return `Command request failed with status ${statusCode}.`;
 };
 
+const hasStructuredCommandError = (body: TDevCommandErrorResponse | object | string | undefined): body is TDevCommandErrorResponse =>
+    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[] = [];
 
@@ -75,6 +78,11 @@ const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GE
             });
 
             if (response.statusCode >= 400) {
+                if (response.statusCode === 404 && !hasStructuredCommandError(response.body as TDevCommandErrorResponse | object | string | undefined)) {
+                    attempts.push(`${baseUrl}${pathname}: returned 404`);
+                    continue;
+                }
+
                 throw new UsageError(
                     getCommandErrorMessage(response.body as TDevCommandErrorResponse | object | string | undefined, response.statusCode),
                 );

package/cli/commands/session.ts

@@ -0,0 +1,254 @@
+import got from 'got';
+import path from 'path';
+import { spawn } from 'child_process';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
+
+const localSessionResultMarker = '__PROTEUM_SESSION_RESULT__';
+
+type TResolvedSessionOutput = {
+    baseUrl: string;
+    user: TDevSessionStartResponse['user'];
+    session: TDevSessionStartResponse['session'];
+    browserCookie: string;
+    curlCookieHeader: string;
+    playwright: {
+        cookies: Array<{
+            name: string;
+            value: string;
+            url: string;
+            expires: number;
+            httpOnly: boolean;
+            secure: boolean;
+            sameSite: 'Lax';
+        }>;
+    };
+};
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!require('fs-extra').existsSync(manifestFilepath)) return undefined;
+
+    const manifest = require('fs-extra').readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
+const getRouterPort = () => {
+    const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
+    if (overridePort) return overridePort;
+
+    const envPort = process.env.PORT?.trim();
+    if (envPort) return envPort;
+
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
+
+    throw new UsageError(
+        `Could not determine the router port from PORT or .proteum/manifest.json in ${cli.args.workdir as string}. Pass --port or --url explicitly.`,
+    );
+};
+
+const getRouterBaseUrls = () => {
+    const explicitUrl = typeof cli.args.url === 'string' && cli.args.url ? cli.args.url.trim() : '';
+    if (explicitUrl) return [normalizeBaseUrl(explicitUrl)];
+
+    const port = getRouterPort();
+    return [...new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`])];
+};
+
+const getSessionErrorMessage = (body: TDevSessionErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Session request failed with status ${statusCode}.`;
+};
+
+const hasStructuredSessionError = (body: TDevSessionErrorResponse | object | string | undefined): body is TDevSessionErrorResponse =>
+    typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string';
+
+const requestSession = async (email: string, role: string) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}/__proteum/session/start`, {
+                method: 'POST',
+                json: role ? { email, role } : { email },
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                if (response.statusCode === 404 && !hasStructuredSessionError(response.body as TDevSessionErrorResponse | object | string | undefined)) {
+                    attempts.push(`${baseUrl}/__proteum/session/start: returned 404`);
+                    continue;
+                }
+
+                throw new UsageError(
+                    getSessionErrorMessage(response.body as TDevSessionErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return {
+                baseUrl,
+                response: response.body as TDevSessionStartResponse,
+            };
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}/__proteum/session/start: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum session server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or omit --port/--url to run the session request locally.',
+        ].join('\n'),
+    );
+};
+
+const buildSessionOutput = ({
+    baseUrl,
+    response,
+}: {
+    baseUrl: string;
+    response: TDevSessionStartResponse;
+}): TResolvedSessionOutput => {
+    const expires = Math.floor(Date.parse(response.session.expiresAt) / 1000);
+    const secure = new URL(baseUrl).protocol === 'https:';
+
+    return {
+        baseUrl,
+        user: response.user,
+        session: response.session,
+        browserCookie: `${response.session.cookieName}=${response.session.token}; Path=/`,
+        curlCookieHeader: `Cookie: ${response.session.cookieName}=${response.session.token}`,
+        playwright: {
+            cookies: [
+                {
+                    name: response.session.cookieName,
+                    value: response.session.token,
+                    url: baseUrl,
+                    expires,
+                    httpOnly: false,
+                    secure,
+                    sameSite: 'Lax',
+                },
+            ],
+        },
+    };
+};
+
+const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+const renderSession = (value: TResolvedSessionOutput) =>
+    [
+        `Session ${value.user.email}`,
+        `- baseUrl=${value.baseUrl}`,
+        `- roles=${value.user.roles.join(',')}`,
+        `- expiresAt=${value.session.expiresAt}`,
+        'Token',
+        value.session.token,
+        'Playwright',
+        JSON.stringify(value.playwright, null, 2),
+        'Browser Cookie',
+        value.browserCookie,
+    ].join('\n');
+
+const runLocalSession = async (email: string, role: string) => {
+    const runnerFilepath = path.join(cli.paths.core.root, 'cli', 'commands', 'sessionLocalRunner.js');
+
+    return await new Promise<{ baseUrl: string; response: TDevSessionStartResponse }>((resolve, reject) => {
+        const stdoutChunks: Buffer[] = [];
+        const stderrChunks: Buffer[] = [];
+        const child = spawn(process.execPath, [runnerFilepath, cli.args.workdir as string, email, role], {
+            cwd: cli.args.workdir as string,
+            env: { ...process.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        child.stdout.on('data', (chunk: Buffer | string) => {
+            stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+
+        child.stderr.on('data', (chunk: Buffer | string) => {
+            stderrChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+
+        child.on('error', (error) => reject(error));
+        child.on('close', () => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            const markerLine = stdout
+                .split(/\r?\n/)
+                .find((line) => line.startsWith(localSessionResultMarker));
+
+            if (stderr.trim()) {
+                process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
+            }
+
+            if (!markerLine) {
+                reject(
+                    new Error(
+                        ['Local session runner exited without returning a structured result.', stdout.trim() ? `stdout:\n${stdout.trim()}` : undefined]
+                            .filter(Boolean)
+                            .join('\n\n'),
+                    ),
+                );
+                return;
+            }
+
+            const payload = JSON.parse(markerLine.slice(localSessionResultMarker.length)) as
+                | { session: { baseUrl: string; response: TDevSessionStartResponse } }
+                | { error: string };
+
+            if ('session' in payload) {
+                resolve(payload.session);
+                return;
+            }
+
+            reject(new Error(payload.error || 'Session runner failed.'));
+        });
+    });
+};
+
+export const run = async () => {
+    const email = typeof cli.args.email === 'string' ? cli.args.email.trim() : '';
+    const role = typeof cli.args.role === 'string' ? cli.args.role.trim() : '';
+    const shouldPrintJson = cli.args.json === true;
+    const shouldUseRemoteServer =
+        (typeof cli.args.port === 'string' && cli.args.port.length > 0) ||
+        (typeof cli.args.url === 'string' && cli.args.url.length > 0);
+
+    if (!email) {
+        throw new UsageError('An email is required. Example: proteum session admin@example.com --role ADMIN');
+    }
+
+    const resolved = buildSessionOutput(
+        shouldUseRemoteServer ? await requestSession(email, role) : await runLocalSession(email, role),
+    );
+
+    if (shouldPrintJson) {
+        printJson(resolved);
+        return;
+    }
+
+    console.log(renderSession(resolved));
+};

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/presentation/commands.ts

@@ -16,6 +16,7 @@ export const proteumCommandNames = [
     'explain',
     'trace',
     'command',
+    'session',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -48,7 +49,7 @@ 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: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command', 'session'] },
     { title: 'Project scaffolding', names: ['init', 'create'] },
 ];
 
@@ -274,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) =>

package/cli/runtime/commands.ts

@@ -296,6 +296,32 @@ class CommandCommand extends ProteumCommand {
     }
 }
 
+class SessionCommand extends ProteumCommand {
+    public static paths = [['session']];
+
+    public static usage = buildUsage('session');
+
+    public role = Option.String('--role', { description: 'Require the resolved user to have the given role.' });
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [email = ''] = this.args;
+
+        this.setCliArgs({
+            email,
+            role: this.role ?? '',
+            port: this.port ?? '',
+            url: this.url ?? '',
+            json: this.json,
+        });
+
+        await runCommandModule(() => import('../commands/session'));
+    }
+}
+
 export const registeredCommands = {
     init: InitCommand,
     create: CreateCommand,
@@ -309,6 +335,7 @@ export const registeredCommands = {
     explain: ExplainCommand,
     trace: TraceCommand,
     command: CommandCommand,
+    session: SessionCommand,
 } as const;
 
 export const createCli = (version: string) => {
@@ -333,6 +360,7 @@ export const createCli = (version: string) => {
     clipanion.register(ExplainCommand);
     clipanion.register(TraceCommand);
     clipanion.register(CommandCommand);
+    clipanion.register(SessionCommand);
 
     return clipanion;
 };