proteum 2.1.3-1 → 2.1.7

package/cli/commands/diagnose.ts

@@ -0,0 +1,286 @@
+import fs from 'fs-extra';
+import got, { type Method } from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import { renderDoctorResponseHuman } from '../../common/dev/diagnostics';
+import type { TDevConsoleLogsResponse } from '../../common/dev/console';
+import type { TDiagnoseResponse, TExplainOwnerMatch } from '../../common/dev/inspection';
+import type { TProteumManifest } from '../../common/dev/proteumManifest';
+import type { TRequestTraceErrorResponse, TRequestTraceArmResponse } from '../../common/dev/requestTrace';
+import type { TDevSessionErrorResponse, TDevSessionStartResponse } from '../../common/dev/session';
+import { summarizeTraceForDiagnose } from '@common/dev/inspection';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+const truncate = (value: string, max = 160) => (value.length <= max ? value : `${value.slice(0, max)}...`);
+const dedupe = <TValue>(values: TValue[]) => [...new Set(values)];
+
+const buildBaseUrlCandidates = (value: string) => {
+    const normalized = normalizeBaseUrl(value);
+
+    try {
+        const parsed = new URL(normalized);
+        const port = parsed.port;
+        const pathname = parsed.pathname === '/' ? '' : parsed.pathname;
+        const search = parsed.search;
+        const hash = parsed.hash;
+        const buildUrl = (hostname: string) => `${parsed.protocol}//${hostname}${port ? `:${port}` : ''}${pathname}${search}${hash}`;
+
+        if (parsed.hostname === '127.0.0.1') return dedupe([normalized, buildUrl('localhost'), buildUrl('[::1]')]);
+        if (parsed.hostname === 'localhost') return dedupe([normalized, buildUrl('127.0.0.1'), buildUrl('[::1]')]);
+        if (parsed.hostname === '[::1]' || parsed.hostname === '::1') return dedupe([normalized, buildUrl('localhost'), buildUrl('127.0.0.1')]);
+    } catch (_error) {}
+
+    return [normalized];
+};
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.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 buildBaseUrlCandidates(explicitUrl);
+
+    const port = getRouterPort();
+    return dedupe([`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`]);
+};
+
+const getJsonErrorMessage = (body: TRequestTraceErrorResponse | TDevSessionErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Request failed with status ${statusCode}.`;
+};
+
+const requestJson = async <TResponse>(pathname: string, options?: { json?: object; method?: 'GET' | 'POST' }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                json: options?.json,
+                method: options?.method || 'GET',
+                responseType: 'json',
+                retry: { limit: 0 },
+                throwHttpErrors: false,
+            });
+
+            if (response.statusCode >= 400) {
+                throw new UsageError(getJsonErrorMessage(response.body as TRequestTraceErrorResponse | object | string | undefined, response.statusCode));
+            }
+
+            return { baseUrl, body: response.body as TResponse };
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+            attempts.push(`${baseUrl}${pathname}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum dev diagnostics server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or pass `--url http://host:port` if it is bound elsewhere.',
+        ].join('\n'),
+    );
+};
+
+const requestSession = async (email: string, role: string) =>
+    requestJson<TDevSessionStartResponse>('/__proteum/session/start', {
+        json: role ? { email, role } : { email },
+        method: 'POST',
+    });
+
+const hitRequest = async ({
+    baseUrl,
+    cookieHeader,
+    dataJson,
+    method,
+    requestPath,
+}: {
+    baseUrl: string;
+    cookieHeader?: string;
+    dataJson?: unknown;
+    method: Method;
+    requestPath: string;
+}) => {
+    const targetUrl = requestPath.startsWith('http://') || requestPath.startsWith('https://') ? requestPath : `${baseUrl}${requestPath}`;
+    const headers = {
+        ...(cookieHeader ? { Cookie: cookieHeader } : {}),
+        ...(dataJson !== undefined ? { 'Content-Type': 'application/json' } : {}),
+    };
+    const response = await got(targetUrl, {
+        body: dataJson !== undefined ? JSON.stringify(dataJson) : undefined,
+        followRedirect: false,
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        method,
+        retry: { limit: 0 },
+        throwHttpErrors: false,
+    });
+
+    return { statusCode: response.statusCode, url: targetUrl };
+};
+
+const formatSource = (match: TExplainOwnerMatch) =>
+    `${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`;
+
+const renderLogs = (logs: TDevConsoleLogsResponse) =>
+    logs.logs.length === 0
+        ? ['Server logs', '- none'].join('\n')
+        : ['Server logs', ...logs.logs.map((entry) => `- [${entry.level}] ${entry.time} ${truncate(entry.text)}`)].join('\n');
+
+const renderOwners = (matches: TExplainOwnerMatch[]) =>
+    matches.length === 0
+        ? ['Owner matches', '- none'].join('\n')
+        : [
+              'Owner matches',
+              ...matches.map((match) => `- [${match.kind}] ${match.label} score=${match.score} source=${formatSource(match)}`),
+          ].join('\n');
+
+const renderSuspects = (response: TDiagnoseResponse) =>
+    response.suspects.length === 0
+        ? ['Suspects', '- none'].join('\n')
+        : [
+              'Suspects',
+              ...response.suspects.map(
+                  (suspect) =>
+                      `- score=${suspect.score} ${suspect.filepath}${suspect.line ? `:${suspect.line}` : ''} ${suspect.label} reasons=${suspect.reasons.join(', ')}`,
+              ),
+          ].join('\n');
+
+const renderHuman = (manifest: ReturnType<typeof readProteumManifest>, response: TDiagnoseResponse) =>
+    [
+        'Proteum diagnose',
+        `- query=${response.query}`,
+        `- trace=${summarizeTraceForDiagnose(response.request)}`,
+        `- manifest=${manifest.app.identity.identifier}`,
+        '',
+        renderSuspects(response),
+        '',
+        renderOwners(response.owner.matches.slice(0, 6)),
+        '',
+        renderDoctorResponseHuman({
+            emptyMessage: 'No manifest diagnostics were found.',
+            manifest,
+            response: response.doctor,
+            title: 'Doctor',
+        }),
+        '',
+        renderDoctorResponseHuman({
+            emptyMessage: 'No contract diagnostics were found.',
+            manifest,
+            response: response.contracts,
+            title: 'Contracts',
+        }),
+        '',
+        renderLogs(response.serverLogs),
+    ].join('\n');
+
+const resolveManifest = async () => {
+    try {
+        return readProteumManifest(cli.paths.appRoot);
+    } catch (error) {
+        const explicitUrl = typeof cli.args.url === 'string' && cli.args.url.trim();
+        if (!explicitUrl) throw error;
+
+        const explain = await requestJson<TProteumManifest>('/__proteum/explain');
+        return explain.body;
+    }
+};
+
+export const run = async () => {
+    const target = typeof cli.args.target === 'string' ? cli.args.target.trim() : '';
+    const hit = typeof cli.args.hit === 'string' ? cli.args.hit.trim() : '';
+    const sessionEmail = typeof cli.args.sessionEmail === 'string' ? cli.args.sessionEmail.trim() : '';
+    const sessionRole = typeof cli.args.sessionRole === 'string' ? cli.args.sessionRole.trim() : '';
+    const capture = typeof cli.args.capture === 'string' && cli.args.capture ? cli.args.capture.trim() : 'deep';
+    const method = typeof cli.args.method === 'string' && cli.args.method ? cli.args.method.trim().toUpperCase() : 'GET';
+    const logsLevel = typeof cli.args.logsLevel === 'string' && cli.args.logsLevel ? cli.args.logsLevel.trim() : 'warn';
+    const logsLimit = typeof cli.args.logsLimit === 'string' && cli.args.logsLimit ? cli.args.logsLimit.trim() : '40';
+    const shouldPrintJson = cli.args.json === true;
+    const hitPath = hit || (target.startsWith('/') ? target : '');
+    const query = target || hitPath;
+    let parsedDataJson: unknown;
+    if (typeof cli.args.dataJson === 'string' && cli.args.dataJson.trim()) {
+        try {
+            parsedDataJson = JSON.parse(cli.args.dataJson);
+        } catch (error) {
+            throw new UsageError(`Invalid --data-json payload: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    const diagnoseRequest: Record<string, string> = {};
+    if (query) diagnoseRequest.query = query;
+    if (hitPath) diagnoseRequest.path = hitPath;
+    if (logsLevel) diagnoseRequest.logsLevel = logsLevel;
+    if (logsLimit) diagnoseRequest.logsLimit = logsLimit;
+
+    let baseUrl: string | undefined;
+
+    if (hitPath) {
+        const armed = await requestJson<TRequestTraceArmResponse>('/__proteum/trace/arm', {
+            json: { capture },
+            method: 'POST',
+        });
+        baseUrl = armed.baseUrl;
+
+        let cookieHeader: string | undefined;
+        if (sessionEmail) {
+            const session = await requestSession(sessionEmail, sessionRole);
+            baseUrl = session.baseUrl;
+            cookieHeader = `${session.body.session.cookieName}=${session.body.session.token}`;
+        }
+
+        const hitResponse = await hitRequest({
+            baseUrl,
+            cookieHeader,
+            dataJson: parsedDataJson,
+            method: method as Method,
+            requestPath: hitPath,
+        });
+
+        diagnoseRequest.path = hitPath;
+        if (!diagnoseRequest.query) diagnoseRequest.query = hitPath;
+        if (hitResponse.statusCode >= 300 && hitResponse.statusCode < 400 && !target) diagnoseRequest.query = hitPath;
+    }
+
+    const diagnose = await requestJson<TDiagnoseResponse>(
+        `/__proteum/diagnose?${new URLSearchParams(diagnoseRequest).toString()}`,
+    );
+    if (shouldPrintJson) {
+        console.log(JSON.stringify(diagnose.body, null, 2));
+        return;
+    }
+
+    const manifest = await resolveManifest();
+    console.log(renderHuman(manifest, diagnose.body));
+};

package/cli/commands/doctor.ts

@@ -1,9 +1,10 @@
 import cli from '..';
 import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
-import { buildDoctorResponse, renderDoctorHuman } from '@common/dev/diagnostics';
+import { buildContractsDoctorResponse } from '@common/dev/contractsDoctor';
+import { buildDoctorResponse, renderDoctorHuman, renderDoctorResponseHuman } from '@common/dev/diagnostics';
 
-const allowedDoctorArgs = new Set(['json', 'strict']);
+const allowedDoctorArgs = new Set(['contracts', 'json', 'strict']);
 
 const validateDoctorArgs = () => {
     const enabledArgs = Object.entries(cli.args)
@@ -26,15 +27,27 @@ export const run = async (): Promise<void> => {
     await compiler.refreshGeneratedTypings();
 
     const manifest = readProteumManifest(cli.paths.appRoot);
-    const response = buildDoctorResponse(manifest, cli.args.strict === true);
+    const response =
+        cli.args.contracts === true
+            ? buildContractsDoctorResponse(manifest, cli.args.strict === true)
+            : buildDoctorResponse(manifest, cli.args.strict === true);
 
     if (cli.args.json === true) {
         console.log(JSON.stringify(response, null, 2));
     } else {
-        console.log(renderDoctorHuman(manifest, cli.args.strict === true));
+        console.log(
+            cli.args.contracts === true
+                ? renderDoctorResponseHuman({
+                      emptyMessage: 'No contract diagnostics were found.',
+                      manifest,
+                      response,
+                      title: 'Proteum doctor contracts',
+                  })
+                : renderDoctorHuman(manifest, cli.args.strict === true),
+        );
     }
 
-    if (cli.args.strict === true && manifest.diagnostics.length > 0) {
+    if (cli.args.strict === true && response.diagnostics.length > 0) {
         throw new Error(
             `Proteum doctor failed in strict mode with ${response.summary.errors} errors and ${response.summary.warnings} warnings.`,
         );

package/cli/commands/explain.ts

@@ -7,6 +7,7 @@ import {
     renderExplainHuman,
     type TExplainSectionName,
 } from '@common/dev/diagnostics';
+import { explainOwner } from '@common/dev/inspection';
 
 const allowedExplainArgs = new Set(['json', 'all', ...explainSectionNames]);
 
@@ -37,6 +38,30 @@ export const run = async (): Promise<void> => {
     await compiler.refreshGeneratedTypings();
 
     const manifest = readProteumManifest(cli.paths.appRoot);
+    const ownerQuery = typeof cli.args.ownerQuery === 'string' ? cli.args.ownerQuery.trim() : '';
+
+    if (ownerQuery) {
+        const response = explainOwner(manifest, ownerQuery);
+        if (cli.args.json === true) {
+            console.log(JSON.stringify(response, null, 2));
+            return;
+        }
+
+        console.log(
+            [
+                'Proteum explain owner',
+                `- query=${ownerQuery}`,
+                ...(response.matches.length === 0
+                    ? ['- No matching manifest owners were found.']
+                    : response.matches.map(
+                          (match) =>
+                              `- [${match.kind}] ${match.label} score=${match.score} source=${match.source.filepath}${match.source.line ? `:${match.source.line}` : ''}${match.source.column ? `:${match.source.column}` : ''}`,
+                      )),
+            ].join('\n'),
+        );
+        return;
+    }
+
     const selectedSections = getSelectedSections();
 
     if (cli.args.json === true) {

package/cli/commands/perf.ts

@@ -0,0 +1,243 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import type {
+    TPerfCompareResponse,
+    TPerfMemoryResponse,
+    TPerfRequestResponse,
+    TPerfTopResponse,
+} from '../../common/dev/performance';
+
+type TPerfAction = 'compare' | 'memory' | 'request' | 'top';
+
+const allowedActions = new Set<TPerfAction>(['compare', 'memory', 'request', 'top']);
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+const truncate = (value: string, max = 160) => (value.length <= max ? value : `${value.slice(0, max)}...`);
+const formatDuration = (value?: number) => (value === undefined ? 'n/a' : `${Math.round(value)} ms`);
+const formatBytes = (value?: number) => (value === undefined ? 'n/a' : `${(value / 1024).toFixed(value >= 1024 ? 1 : 2)} KB`);
+const formatSignedBytes = (value?: number) =>
+    value === undefined ? 'n/a' : `${value >= 0 ? '+' : '-'}${formatBytes(Math.abs(value))}`;
+const formatPercent = (value?: number) => (value === undefined ? 'n/a' : `${value >= 0 ? '+' : ''}${value.toFixed(0)}%`);
+
+const getAction = () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'top';
+    if (!allowedActions.has(action as TPerfAction)) {
+        throw new UsageError(`Unsupported perf action "${action}". Expected one of: ${[...allowedActions].join(', ')}.`);
+    }
+
+    return action as TPerfAction;
+};
+
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.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 requestJson = async <TResponse>(pathname: string) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                responseType: 'json',
+                retry: { limit: 0 },
+                throwHttpErrors: false,
+            });
+
+            if (response.statusCode >= 400) {
+                const body = response.body as { error?: string } | undefined;
+                throw new UsageError(body?.error || `Perf request failed with status ${response.statusCode}.`);
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof UsageError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum perf server.',
+            ...attempts.map((attempt) => `- ${attempt}`),
+            'Make sure the app is running with `proteum dev`, or pass `--url http://host:port` if it is bound elsewhere.',
+        ].join('\n'),
+    );
+};
+
+const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+const renderWindow = (label: string, value: { startedAt: string; finishedAt: string; requestCount: number; availableRequestCount: number }) =>
+    `${label}=${value.requestCount}/${value.availableRequestCount} traces ${value.startedAt}..${value.finishedAt}`;
+
+const renderTop = (response: TPerfTopResponse) =>
+    [
+        `Proteum perf top groupBy=${response.groupBy} ${renderWindow('window', response.window)}`,
+        `- requests=${response.summary.requestCount} errors=${response.summary.errorCount} avg=${formatDuration(response.summary.avgDurationMs)} p95=${formatDuration(response.summary.p95DurationMs)} cpu=${formatDuration(response.summary.avgCpuMs)} sql=${formatDuration(response.summary.avgSqlDurationMs)}`,
+        ...(response.rows.length === 0
+            ? ['- no traced requests matched this window']
+            : response.rows.map(
+                  (row) =>
+                      `- ${row.label} | requests=${row.requestCount} avg=${formatDuration(row.avgDurationMs)} p95=${formatDuration(row.p95DurationMs)} max=${formatDuration(row.maxDurationMs)} cpu=${formatDuration(row.avgCpuMs)} sql=${formatDuration(row.avgSqlDurationMs)} render=${formatDuration(row.avgRenderDurationMs)} heap=${formatSignedBytes(row.avgHeapDeltaBytes)} slowest=${row.slowestRequestId || 'n/a'}`,
+              )),
+    ].join('\n');
+
+const renderCompare = (response: TPerfCompareResponse) =>
+    [
+        `Proteum perf compare groupBy=${response.groupBy}`,
+        `- baseline ${renderWindow('window', response.baseline)}`,
+        `- target ${renderWindow('window', response.target)}`,
+        ...(response.rows.length === 0
+            ? ['- no traced requests matched either window']
+            : response.rows.map(
+                  (row) =>
+                      `- [${row.change}] ${row.label} | p95 ${formatPercent(row.p95DurationMs.deltaPercent)} (${formatDuration(row.p95DurationMs.baseline)} -> ${formatDuration(row.p95DurationMs.target)}) | avg ${formatPercent(row.avgDurationMs.deltaPercent)} | cpu ${formatPercent(row.avgCpuMs.deltaPercent)} | heap ${formatSignedBytes(row.avgHeapDeltaBytes.delta)} | sql ${formatPercent(row.avgSqlDurationMs.deltaPercent)}`,
+              )),
+    ].join('\n');
+
+const renderMemory = (response: TPerfMemoryResponse) =>
+    [
+        `Proteum perf memory groupBy=${response.groupBy} ${renderWindow('window', response.window)}`,
+        ...(response.rows.length === 0
+            ? ['- no traced requests matched this window']
+            : response.rows.map(
+                  (row) =>
+                      `- [${row.trend}] ${row.label} | requests=${row.requestCount} heap avg=${formatSignedBytes(row.avgHeapDeltaBytes)} max=${formatSignedBytes(row.maxHeapDeltaBytes)} rss avg=${formatSignedBytes(row.avgRssDeltaBytes)} drift=${formatPercent(row.positiveHeapDriftRatio * 100)}`,
+              )),
+    ].join('\n');
+
+const renderRequest = (response: TPerfRequestResponse) =>
+    [
+        `Proteum perf request ${response.request.requestId}`,
+        `- ${response.request.method} ${response.request.path} status=${response.request.statusCode ?? 'pending'} route=${response.request.routeLabel} controller=${response.request.controllerLabel}`,
+        `- total=${formatDuration(response.request.totalDurationMs)} cpu=${formatDuration(response.request.cpuTotalMs)} sql=${formatDuration(response.request.sqlDurationMs)} calls=${formatDuration(response.request.callDurationMs)} render=${formatDuration(response.request.renderDurationMs)} self=${formatDuration(response.request.selfDurationMs)}`,
+        `- heap=${formatSignedBytes(response.request.heapDeltaBytes)} rss=${formatSignedBytes(response.request.rssDeltaBytes)} ssr=${formatBytes(response.request.ssrPayloadBytes)} html=${formatBytes(response.request.htmlBytes)} document=${formatBytes(response.request.documentBytes)}`,
+        'Stages',
+        ...(response.request.stages.length === 0
+            ? ['- none']
+            : response.request.stages.map(
+                  (stage) => `- ${stage.label} | start=+${Math.round(stage.startOffsetMs)}ms end=+${Math.round(stage.endOffsetMs)}ms duration=${formatDuration(stage.durationMs)}`,
+              )),
+        'Hot Calls',
+        ...(response.request.hottestCalls.length === 0
+            ? ['- none']
+            : response.request.hottestCalls.map(
+                  (call) =>
+                      `- ${call.label} | duration=${formatDuration(call.durationMs)} status=${call.statusCode ?? 'pending'} origin=${call.origin}${call.errorMessage ? ` error=${truncate(call.errorMessage, 96)}` : ''}`,
+              )),
+        'Hot SQL',
+        ...(response.request.hottestSqlQueries.length === 0
+            ? ['- none']
+            : response.request.hottestSqlQueries.map(
+                  (query) =>
+                      `- ${query.callerLabel} | ${query.operation}${query.model ? ` ${query.model}` : ''} | duration=${formatDuration(query.durationMs)} | ${truncate(query.query, 104)}`,
+              )),
+    ].join('\n');
+
+export const run = async () => {
+    const action = getAction();
+    const shouldPrintJson = cli.args.json === true;
+    const groupBy = typeof cli.args.groupBy === 'string' && cli.args.groupBy ? cli.args.groupBy : 'path';
+    const limit =
+        typeof cli.args.limit === 'string' && cli.args.limit ? Math.max(1, Number.parseInt(cli.args.limit, 10) || 12) : 12;
+
+    if (action === 'top') {
+        const since = typeof cli.args.since === 'string' && cli.args.since ? cli.args.since : 'today';
+        const response = await requestJson<TPerfTopResponse>(
+            `/__proteum/perf/top?${new URLSearchParams({ groupBy, limit: String(limit), since }).toString()}`,
+        );
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderTop(response));
+        return;
+    }
+
+    if (action === 'compare') {
+        const baseline = typeof cli.args.baseline === 'string' && cli.args.baseline ? cli.args.baseline : 'yesterday';
+        const targetWindow = typeof cli.args.targetWindow === 'string' && cli.args.targetWindow ? cli.args.targetWindow : 'today';
+        const response = await requestJson<TPerfCompareResponse>(
+            `/__proteum/perf/compare?${new URLSearchParams({
+                baseline,
+                groupBy,
+                limit: String(limit),
+                target: targetWindow,
+            }).toString()}`,
+        );
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderCompare(response));
+        return;
+    }
+
+    if (action === 'memory') {
+        const since = typeof cli.args.since === 'string' && cli.args.since ? cli.args.since : 'today';
+        const response = await requestJson<TPerfMemoryResponse>(
+            `/__proteum/perf/memory?${new URLSearchParams({ groupBy, limit: String(limit), since }).toString()}`,
+        );
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderMemory(response));
+        return;
+    }
+
+    const requestTarget = typeof cli.args.target === 'string' ? cli.args.target.trim() : '';
+    if (!requestTarget) throw new UsageError('`proteum perf request` requires a traced request id or path.');
+
+    const response = await requestJson<TPerfRequestResponse>(
+        `/__proteum/perf/request?${new URLSearchParams({ query: requestTarget }).toString()}`,
+    );
+    if (shouldPrintJson) {
+        printJson(response);
+        return;
+    }
+
+    console.log(renderRequest(response));
+};

package/cli/commands/trace.ts

@@ -127,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}` : '',
     ]
@@ -137,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',
@@ -147,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) =>