proteum 2.1.2 → 2.1.6

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),
                 );
@@ -119,6 +127,7 @@ const renderTraceSummary = (request: TRequestTraceListItem) =>
         `capture=${request.capture}`,
         `events=${request.eventCount}`,
         `calls=${request.callCount}`,
+        `sql=${request.sqlQueryCount}`,
         request.user ? `user=${request.user}` : '',
         request.errorMessage ? `error=${request.errorMessage}` : '',
     ]
@@ -129,7 +138,7 @@ const renderTrace = (request: TRequestTrace) =>
     [
         `Request ${request.id}`,
         `- ${request.method} ${request.path} status=${request.statusCode ?? 'pending'} capture=${request.capture}`,
-        `- started=${request.startedAt} durationMs=${request.durationMs ?? 'pending'} events=${request.events.length} dropped=${request.droppedEvents}`,
+        `- started=${request.startedAt} durationMs=${request.durationMs ?? 'pending'} events=${request.events.length} calls=${request.calls.length} sql=${request.sqlQueries.length} dropped=${request.droppedEvents}`,
         ...(request.user ? [`- user=${request.user}`] : []),
         ...(request.persistedFilepath ? [`- persisted=${request.persistedFilepath}`] : []),
         'Calls',
@@ -139,6 +148,13 @@ const renderTrace = (request: TRequestTrace) =>
                   (call) =>
                       `- ${call.origin} ${call.label} ${call.method} ${call.path} status=${call.statusCode ?? 'pending'} durationMs=${call.durationMs ?? 'pending'} req=${call.requestDataKeys.join(',')} res=${call.resultKeys.join(',')}`,
               )),
+        'SQL',
+        ...(request.sqlQueries.length === 0
+            ? ['- none']
+            : request.sqlQueries.map(
+                  (query) =>
+                      `- [${query.durationMs}ms] ${query.kind} ${query.operation} ${query.callerMethod} ${query.callerPath} ${query.query}${query.paramsText ? ` params=${query.paramsText}` : ''}`,
+              )),
         'Events',
         ...request.events.map(
             (event) =>