proteum 2.2.9 → 2.3.0

package/cli/commands/runtime.ts

@@ -0,0 +1,151 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { listDevSessionInspections, type TDevSessionInspection } from '../runtime/devSessions';
+import { printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
+import type { TDoctorResponse } from '@common/dev/diagnostics';
+import type { TProteumManifest } from '@common/dev/proteumManifest';
+
+type TRuntimeAction = 'status';
+
+const allowedActions = new Set<TRuntimeAction>(['status']);
+
+const getAction = () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'status';
+    if (!allowedActions.has(action as TRuntimeAction)) {
+        throw new UsageError(`Unsupported runtime action "${action}". Expected one of: ${[...allowedActions].join(', ')}.`);
+    }
+
+    return action as TRuntimeAction;
+};
+
+const readManifestIfAvailable = (): TProteumManifest | undefined => {
+    const manifestFilepath = path.join(cli.paths.appRoot, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    try {
+        return readProteumManifest(cli.paths.appRoot);
+    } catch {
+        return undefined;
+    }
+};
+
+const getSessionUrl = (inspection: TDevSessionInspection) => {
+    if (!inspection.record) return '';
+    if (inspection.record.publicUrl) return inspection.record.publicUrl.replace(/\/+$/, '');
+    return `http://localhost:${inspection.record.routerPort}`;
+};
+
+const probeDoctor = async (baseUrl: string) => {
+    if (!baseUrl) return { reachable: false, error: 'No dev URL is registered.' };
+
+    try {
+        const response = await got(`${baseUrl}/__proteum/doctor`, {
+            responseType: 'json',
+            retry: { limit: 0 },
+            throwHttpErrors: false,
+            timeout: { request: 1200 },
+        });
+
+        if (response.statusCode >= 400) {
+            return { reachable: false, statusCode: response.statusCode, error: `Doctor returned HTTP ${response.statusCode}.` };
+        }
+
+        const doctor = response.body as TDoctorResponse;
+        return {
+            reachable: true,
+            statusCode: response.statusCode,
+            doctor: doctor.summary,
+        };
+    } catch (error) {
+        return {
+            reachable: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+
+const compactSession = (inspection: TDevSessionInspection) => ({
+    sessionFilePath: inspection.sessionFilePath,
+    live: inspection.live,
+    stale: inspection.stale,
+    invalid: inspection.invalid,
+    parseError: inspection.parseError,
+    pid: inspection.record?.pid,
+    routerPort: inspection.record?.routerPort,
+    publicUrl: inspection.record?.publicUrl,
+    state: inspection.record?.state,
+    startedAt: inspection.record?.startedAt,
+    updatedAt: inspection.record?.updatedAt,
+});
+
+export const run = async () => {
+    const action = getAction();
+    if (action !== 'status') return;
+
+    const manifest = readManifestIfAvailable();
+    const sessions = await listDevSessionInspections({
+        appRoot: cli.paths.appRoot,
+        sessionFilePath: typeof cli.args.sessionFile === 'string' && cli.args.sessionFile ? cli.args.sessionFile : undefined,
+    });
+    const liveSessions = sessions.filter((inspection) => inspection.live && inspection.record);
+    const selectedSession =
+        liveSessions.find((inspection) => inspection.record?.state === 'ready') || liveSessions[0] || sessions.find((inspection) => inspection.record);
+    const selectedBaseUrl = selectedSession ? getSessionUrl(selectedSession) : '';
+    const health = selectedSession && selectedSession.live ? await probeDoctor(selectedBaseUrl) : { reachable: false, error: 'No live tracked dev session.' };
+
+    const payload = {
+        appRoot: cli.paths.appRoot,
+        manifest: manifest
+            ? {
+                  identifier: manifest.app.identity.identifier,
+                  name: manifest.app.identity.name,
+                  routerPort: manifest.env.resolved.routerPort,
+                  diagnostics: {
+                      errors: manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length,
+                      warnings: manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length,
+                  },
+                  counts: {
+                      connectedProjects: manifest.connectedProjects.length,
+                      controllers: manifest.controllers.length,
+                      routes: manifest.routes.client.length + manifest.routes.server.length,
+                  },
+              }
+            : undefined,
+        selected: selectedSession ? compactSession(selectedSession) : undefined,
+        sessions: sessions.map(compactSession),
+        health,
+    };
+
+    if (cli.args.full === true) {
+        printJson(payload);
+        return;
+    }
+
+    printAgentResponse({
+        summary: selectedSession
+            ? `${selectedSession.live ? 'live' : 'stale'} dev session on ${selectedSession.record?.routerPort || 'unknown port'}; health=${health.reachable ? 'reachable' : 'unreachable'}`
+            : 'No tracked Proteum dev session found.',
+        data: payload,
+        nextActions: selectedSession?.record
+            ? [
+                  {
+                      label: 'Diagnose Root',
+                      command: `proteum diagnose ${quoteCommandArgument('/')} --port ${selectedSession.record.routerPort}`,
+                      reason: 'Use the selected runtime for the smallest request-level diagnostic pass.',
+                  },
+              ]
+            : [
+                  {
+                      label: 'Start Dev',
+                      command: 'proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port <free-port>',
+                      reason: 'Create a tracked dev session before request-time diagnostics.',
+                  },
+              ],
+        fullDetailCommand: 'proteum runtime status --full',
+    });
+};

package/cli/commands/trace.ts

@@ -4,6 +4,7 @@ import path from 'path';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument, truncateForAgent } from '../utils/agentOutput';
 import type {
     TRequestTrace,
     TRequestTraceArmResponse,
@@ -164,23 +165,114 @@ const renderTrace = (request: TRequestTrace) =>
         ),
     ].join('\n');
 
-const printJson = (value: object) => {
-    console.log(JSON.stringify(value, null, 2));
+const compactCall = (call: TRequestTrace['calls'][number]) => ({
+    id: call.id,
+    origin: call.origin,
+    label: call.label,
+    method: call.method,
+    path: call.path,
+    statusCode: call.statusCode,
+    durationMs: call.durationMs,
+    errorMessage: call.errorMessage ? truncateForAgent(call.errorMessage) : undefined,
+});
+
+const compactSql = (query: TRequestTrace['sqlQueries'][number]) => ({
+    id: query.id,
+    caller: query.callerLabel || `${query.callerMethod} ${query.callerPath}`,
+    kind: query.kind,
+    operation: query.operation,
+    model: query.model,
+    durationMs: query.durationMs,
+    fingerprint: query.fingerprint,
+});
+
+const compactEvent = (event: TRequestTrace['events'][number]) => ({
+    index: event.index,
+    elapsedMs: event.elapsedMs,
+    type: event.type,
+    detailKeys: Object.keys(event.details),
+});
+
+const buildTraceFullDetailCommand = (request: TRequestTrace) =>
+    [
+        'proteum trace show',
+        quoteCommandArgument(request.id),
+        typeof cli.args.port === 'string' && cli.args.port ? `--port ${cli.args.port}` : '',
+        typeof cli.args.url === 'string' && cli.args.url ? `--url ${quoteCommandArgument(cli.args.url)}` : '',
+        '--events',
+    ]
+        .filter(Boolean)
+        .join(' ');
+
+const printCompactTrace = (request: TRequestTrace) => {
+    const failedCalls = request.calls.filter((call) => call.errorMessage || (call.statusCode !== undefined && call.statusCode >= 400));
+    const errorEvents = request.events.filter((event) => event.type === 'error');
+    const hotCalls = [...request.calls].sort((left, right) => (right.durationMs || 0) - (left.durationMs || 0));
+    const hotSql = [...request.sqlQueries].sort((left, right) => right.durationMs - left.durationMs);
+
+    printAgentResponse({
+        summary: `${request.id}: ${request.method} ${request.path} status=${request.statusCode ?? 'pending'} durationMs=${request.durationMs ?? 'pending'} events=${request.events.length} calls=${request.calls.length} sql=${request.sqlQueries.length}`,
+        data: {
+            request: {
+                id: request.id,
+                method: request.method,
+                path: request.path,
+                statusCode: request.statusCode,
+                durationMs: request.durationMs,
+                capture: request.capture,
+                user: request.user,
+                errorMessage: request.errorMessage,
+                droppedEvents: request.droppedEvents,
+                persistedFilepath: request.persistedFilepath,
+            },
+            counts: {
+                calls: request.calls.length,
+                events: request.events.length,
+                sqlQueries: request.sqlQueries.length,
+            },
+            failedCalls: compactList(failedCalls, 5).map(compactCall),
+            errorEvents: compactList(errorEvents, 5).map(compactEvent),
+            hotCalls: compactList(hotCalls, 5).map(compactCall),
+            hotSql: compactList(hotSql, 5).map(compactSql),
+        },
+        nextActions: [
+            {
+                label: 'Diagnose Request',
+                command: `proteum diagnose ${quoteCommandArgument(request.path)}`,
+                reason: 'Collapse this trace with owner lookup, diagnostics, suspects, and server logs.',
+            },
+            {
+                label: 'Perf Request',
+                command: `proteum perf request ${quoteCommandArgument(request.id)}`,
+                reason: 'Inspect request timing, SQL, render, and memory rollups without full events.',
+            },
+        ],
+        fullDetailCommand: buildTraceFullDetailCommand(request),
+        omitted: [
+            {
+                reason: 'Full event details, payload summaries, raw SQL, and call bodies are omitted by default.',
+                command: buildTraceFullDetailCommand(request),
+            },
+        ],
+    });
 };
 
 export const run = async () => {
     const action = getAction();
     const requestId = typeof cli.args.id === 'string' ? cli.args.id : '';
-    const shouldPrintJson = cli.args.json === true;
+    const shouldPrintFull = cli.args.full === true || cli.args.events === true;
+    const shouldPrintHuman = cli.args.human === true;
 
     if (action === 'requests') {
         const response = await requestJson<TRequestTraceListResponse>('/__proteum/trace/requests');
-        if (shouldPrintJson) {
-            printJson(response);
-            return;
-        }
-
-        console.log(['Proteum trace', ...response.requests.map(renderTraceSummary)].join('\n'));
+        if (shouldPrintFull) printJson(response);
+        else if (shouldPrintHuman) console.log(['Proteum trace', ...response.requests.map(renderTraceSummary)].join('\n'));
+        else
+            printAgentResponse({
+                summary: `${response.requests.length} request traces`,
+                data: { requests: compactList(response.requests, 20), totalReturned: response.requests.length },
+                fullDetailCommand: 'proteum trace requests --full',
+            });
         return;
     }
 
@@ -191,23 +283,20 @@ export const run = async () => {
             json: { capture },
         });
 
-        if (shouldPrintJson) {
-            printJson(response);
-            return;
-        }
-
-        console.log(`Armed next request trace with capture=${response.capture}.`);
+        if (shouldPrintHuman) console.log(`Armed next request trace with capture=${response.capture}.`);
+        else printAgentResponse({ summary: `Armed next request trace with capture=${response.capture}.`, data: response });
         return;
     }
 
     if (action === 'latest') {
         const response = await requestJson<TRequestTraceResponse>('/__proteum/trace/latest');
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderTrace(response.request));
+        if (shouldPrintHuman) console.log(renderTrace(response.request));
+        else printCompactTrace(response.request);
         return;
     }
 
@@ -218,12 +307,13 @@ export const run = async () => {
     const response = await requestJson<TRequestTraceResponse>(`/__proteum/trace/requests/${requestId}`);
 
     if (action === 'show') {
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderTrace(response.request));
+        if (shouldPrintHuman) console.log(renderTrace(response.request));
+        else printCompactTrace(response.request);
         return;
     }
 
@@ -235,10 +325,15 @@ export const run = async () => {
     fs.ensureDirSync(path.dirname(output));
     fs.writeJSONSync(output, response.request, { spaces: 2 });
 
-    if (shouldPrintJson) {
+    if (shouldPrintFull) {
         printJson({ output, request: response.request });
         return;
     }
 
-    console.log(`Exported trace ${response.request.id} to ${output}`);
+    if (shouldPrintHuman) console.log(`Exported trace ${response.request.id} to ${output}`);
+    else
+        printAgentResponse({
+            summary: `Exported trace ${response.request.id}.`,
+            data: { output, requestId: response.request.id },
+        });
 };