proteum 2.2.8 → 2.3.0

package/cli/commands/explain.ts

@@ -2,14 +2,16 @@ import cli from '..';
 import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import {
+    buildExplainSummaryItems,
     explainSectionNames,
     pickExplainManifestSections,
     renderExplainHuman,
     type TExplainSectionName,
 } from '@common/dev/diagnostics';
 import { explainOwner } from '@common/dev/inspection';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 
-const allowedExplainArgs = new Set(['json', 'all', ...explainSectionNames]);
+const allowedExplainArgs = new Set(['json', 'all', 'full', 'human', 'manifest', ...explainSectionNames]);
 
 const validateExplainArgs = () => {
     const enabledArgs = Object.entries(cli.args)
@@ -31,6 +33,93 @@ const getSelectedSections = (): TExplainSectionName[] => {
     return explainSectionNames.filter((sectionName) => cli.args[sectionName] === true);
 };
 
+const compactOwnerMatch = (match: ReturnType<typeof explainOwner>['matches'][number]) => ({
+    kind: match.kind,
+    label: match.label,
+    score: match.score,
+    scope: match.scopeLabel,
+    origin: match.originHint,
+    source: match.source,
+});
+
+const hasExplicitDetailSelection = (selectedSections: TExplainSectionName[]) =>
+    cli.args.full === true || cli.args.manifest === true || cli.args.all === true || selectedSections.length > 0;
+
+const printCompactOwner = (ownerQuery: string, response: ReturnType<typeof explainOwner>) => {
+    const topOwner = response.matches[0];
+
+    printAgentResponse({
+        summary: topOwner
+            ? `${ownerQuery} -> ${topOwner.kind} ${topOwner.label} (${topOwner.scopeLabel})`
+            : `${ownerQuery} -> no manifest owner matched`,
+        data: {
+            query: ownerQuery,
+            normalizedQuery: response.normalizedQuery,
+            top: topOwner ? compactOwnerMatch(topOwner) : undefined,
+            matches: compactList(response.matches, 6).map(compactOwnerMatch),
+            totalReturned: response.matches.length,
+        },
+        nextActions: [
+            {
+                label: 'Orient',
+                command: `proteum orient ${quoteCommandArgument(ownerQuery)}`,
+                reason: 'Resolve the owner together with the relevant instruction files and next command.',
+            },
+        ],
+        fullDetailCommand: `proteum explain owner ${quoteCommandArgument(ownerQuery)} --full`,
+    });
+};
+
+const printCompactExplain = (manifest: ReturnType<typeof readProteumManifest>) => {
+    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+    const requiredEnvProvided = manifest.env.requiredVariables.filter((variable) => variable.provided).length;
+
+    printAgentResponse({
+        summary: `${manifest.app.identity.identifier}: ${manifest.controllers.length} controllers, ${manifest.routes.client.length + manifest.routes.server.length} routes, ${errors} errors, ${warnings} warnings`,
+        data: {
+            app: {
+                root: manifest.app.root,
+                coreRoot: manifest.app.coreRoot,
+                identifier: manifest.app.identity.identifier,
+                name: manifest.app.identity.name,
+            },
+            counts: {
+                commands: manifest.commands.length,
+                connectedProjects: manifest.connectedProjects.length,
+                controllers: manifest.controllers.length,
+                diagnostics: manifest.diagnostics.length,
+                layouts: manifest.layouts.length,
+                routesClient: manifest.routes.client.length,
+                routesServer: manifest.routes.server.length,
+                servicesApp: manifest.services.app.length,
+                servicesRouterPlugins: manifest.services.routerPlugins.length,
+            },
+            diagnostics: { errors, warnings },
+            env: {
+                requiredProvided: requiredEnvProvided,
+                requiredTotal: manifest.env.requiredVariables.length,
+                routerPort: manifest.env.resolved.routerPort,
+            },
+            summaryItems: buildExplainSummaryItems(manifest),
+        },
+        nextActions: [
+            {
+                label: 'Orient Target',
+                command: 'proteum orient <route|file|controller|error>',
+                reason: 'Use orient for task-specific owner, instruction, and next-command routing.',
+            },
+        ],
+        fullDetailCommand: 'proteum explain --manifest',
+        omitted: [
+            {
+                reason: 'Full manifest sections are omitted from the default agent summary.',
+                command: 'proteum explain --manifest',
+            },
+        ],
+    });
+};
+
 export const run = async (): Promise<void> => {
     validateExplainArgs();
 
@@ -42,8 +131,13 @@ export const run = async (): Promise<void> => {
 
     if (ownerQuery) {
         const response = explainOwner(manifest, ownerQuery);
-        if (cli.args.json === true) {
-            console.log(JSON.stringify(response, null, 2));
+        if (cli.args.full === true || cli.args.manifest === true) {
+            printJson(response);
+            return;
+        }
+
+        if (cli.args.human !== true) {
+            printCompactOwner(ownerQuery, response);
             return;
         }
 
@@ -64,10 +158,15 @@ export const run = async (): Promise<void> => {
 
     const selectedSections = getSelectedSections();
 
-    if (cli.args.json === true) {
-        console.log(JSON.stringify(pickExplainManifestSections(manifest, selectedSections), null, 2));
+    if (hasExplicitDetailSelection(selectedSections)) {
+        printJson(pickExplainManifestSections(manifest, cli.args.manifest === true ? [...explainSectionNames] : selectedSections));
+        return;
+    }
+
+    if (cli.args.human === true) {
+        console.log(renderExplainHuman(manifest, selectedSections));
         return;
     }
 
-    console.log(renderExplainHuman(manifest, selectedSections));
+    printCompactExplain(manifest);
 };

package/cli/commands/mcp.ts

@@ -0,0 +1,16 @@
+import cli from '..';
+import { CliProteumMcpProvider } from '../mcp/provider';
+import { startProteumMcpStdioServer } from '../mcp/stdio';
+
+export const run = async () => {
+    const provider = new CliProteumMcpProvider({
+        appRoot: cli.paths.appRoot,
+        sessionFilePath: typeof cli.args.sessionFile === 'string' && cli.args.sessionFile ? cli.args.sessionFile : undefined,
+        url: typeof cli.args.url === 'string' && cli.args.url ? cli.args.url : undefined,
+    });
+
+    await startProteumMcpStdioServer({
+        provider,
+        version: String(cli.packageJson.version || ''),
+    });
+};

package/cli/commands/orient.ts

@@ -8,6 +8,7 @@ import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import { buildOrientationResponse, type TOrientResponse } from '@common/dev/inspection';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 
 const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
 const dedupe = <TValue>(values: TValue[]) => [...new Set(values)];
@@ -153,6 +154,63 @@ const renderHuman = (response: TOrientResponse) =>
         ...(response.warnings.length === 0 ? ['- none'] : response.warnings.map((warning) => `- ${warning}`)),
     ].join('\n');
 
+const compactOwnerMatch = (match: TOrientResponse['owner']['matches'][number]) => ({
+    kind: match.kind,
+    label: match.label,
+    score: match.score,
+    scope: match.scopeLabel,
+    origin: match.originHint,
+    source: match.source,
+});
+
+const buildInstructionPlan = (response: TOrientResponse) => ({
+    mustRead: [...new Set([response.guidance.agents, ...response.guidance.areaAgents])],
+    readWhen: [
+        {
+            file: response.guidance.diagnostics,
+            when: 'Read only for raw errors, failing requests, traces, perf regressions, or reproduction work.',
+        },
+        {
+            file: response.guidance.codingStyle,
+            when: 'Read before editing implementation files.',
+        },
+        {
+            file: response.guidance.optimizations,
+            when: 'Read after client-side implementation or when the task explicitly concerns packages, build, runtime, or performance.',
+        },
+    ],
+});
+
+const printCompactOrient = (response: TOrientResponse) => {
+    const topOwner = response.owner.matches[0];
+    const summary = topOwner
+        ? `${response.query} -> ${topOwner.kind} ${topOwner.label} (${topOwner.scopeLabel})`
+        : `${response.query} -> no manifest owner matched`;
+
+    printAgentResponse({
+        summary,
+        data: {
+            query: response.query,
+            app: response.app,
+            owner: {
+                top: topOwner ? compactOwnerMatch(topOwner) : undefined,
+                matches: compactList(response.owner.matches, 4).map(compactOwnerMatch),
+                totalReturned: response.owner.matches.length,
+            },
+            instructions: buildInstructionPlan(response),
+            connected: {
+                imports: compactList(response.connected.imports, 4),
+                producers: compactList(response.connected.producers, 3),
+                totalImports: response.connected.imports.length,
+                totalProducers: response.connected.producers.length,
+            },
+            warnings: response.warnings,
+        },
+        nextActions: response.nextSteps,
+        fullDetailCommand: `proteum orient ${quoteCommandArgument(response.query)} --full`,
+    });
+};
+
 export const run = async () => {
     const query = typeof cli.args.query === 'string' ? cli.args.query.trim() : '';
     if (!query) throw new UsageError('A query is required. Example: proteum orient /api/Auth/CurrentUser');
@@ -160,10 +218,15 @@ export const run = async () => {
     const manifest = await resolveManifest();
     const response = buildOrientationResponse(manifest, query);
 
-    if (cli.args.json === true) {
-        console.log(JSON.stringify(response, null, 2));
+    if (cli.args.full === true) {
+        printJson(response);
+        return;
+    }
+
+    if (cli.args.human === true) {
+        console.log(renderHuman(response));
         return;
     }
 
-    console.log(renderHuman(response));
+    printCompactOrient(response);
 };

package/cli/commands/perf.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 {
     TPerfCompareResponse,
     TPerfMemoryResponse,
@@ -102,10 +103,6 @@ const requestJson = async <TResponse>(pathname: string) => {
     );
 };
 
-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}`;
 
@@ -180,9 +177,113 @@ const renderRequest = (response: TPerfRequestResponse) =>
               )),
     ].join('\n');
 
+const compactTopLikeRow = (row: TPerfTopResponse['rows'][number]) => ({
+    label: row.label,
+    requestCount: row.requestCount,
+    avgDurationMs: row.avgDurationMs,
+    p95DurationMs: row.p95DurationMs,
+    maxDurationMs: row.maxDurationMs,
+    avgCpuMs: row.avgCpuMs,
+    avgSqlDurationMs: row.avgSqlDurationMs,
+    avgRenderDurationMs: row.avgRenderDurationMs,
+    avgHeapDeltaBytes: row.avgHeapDeltaBytes,
+    slowestRequestId: row.slowestRequestId,
+});
+
+const compactSql = (query: TPerfRequestResponse['request']['hottestSqlQueries'][number]) => ({
+    callerLabel: query.callerLabel,
+    operation: query.operation,
+    model: query.model,
+    fingerprint: query.fingerprint,
+    durationMs: query.durationMs,
+    query: truncateForAgent(query.query, 140),
+});
+
+const printCompactTop = (response: TPerfTopResponse) => {
+    printAgentResponse({
+        summary: `Perf top ${response.groupBy}: ${response.summary.requestCount} requests, ${response.summary.errorCount} errors, p95=${formatDuration(response.summary.p95DurationMs)}`,
+        data: {
+            groupBy: response.groupBy,
+            window: response.window,
+            summary: response.summary,
+            rows: compactList(response.rows, 8).map(compactTopLikeRow),
+            totalRows: response.rows.length,
+        },
+        fullDetailCommand: 'proteum perf top --full',
+    });
+};
+
+const printCompactCompare = (response: TPerfCompareResponse) => {
+    printAgentResponse({
+        summary: `Perf compare ${response.groupBy}: ${response.rows.length} rows`,
+        data: {
+            groupBy: response.groupBy,
+            baseline: response.baseline,
+            target: response.target,
+            rows: compactList(response.rows, 8),
+            totalRows: response.rows.length,
+        },
+        fullDetailCommand: 'proteum perf compare --full',
+    });
+};
+
+const printCompactMemory = (response: TPerfMemoryResponse) => {
+    printAgentResponse({
+        summary: `Perf memory ${response.groupBy}: ${response.rows.length} rows`,
+        data: {
+            groupBy: response.groupBy,
+            window: response.window,
+            rows: compactList(response.rows, 8),
+            totalRows: response.rows.length,
+        },
+        fullDetailCommand: 'proteum perf memory --full',
+    });
+};
+
+const printCompactRequest = (response: TPerfRequestResponse) => {
+    printAgentResponse({
+        summary: `${response.request.requestId}: ${response.request.method} ${response.request.path} total=${formatDuration(response.request.totalDurationMs)} cpu=${formatDuration(response.request.cpuTotalMs)} sql=${formatDuration(response.request.sqlDurationMs)}`,
+        data: {
+            request: {
+                requestId: response.request.requestId,
+                method: response.request.method,
+                path: response.request.path,
+                statusCode: response.request.statusCode,
+                routeLabel: response.request.routeLabel,
+                controllerLabel: response.request.controllerLabel,
+                totalDurationMs: response.request.totalDurationMs,
+                cpuTotalMs: response.request.cpuTotalMs,
+                sqlDurationMs: response.request.sqlDurationMs,
+                callDurationMs: response.request.callDurationMs,
+                renderDurationMs: response.request.renderDurationMs,
+                selfDurationMs: response.request.selfDurationMs,
+                heapDeltaBytes: response.request.heapDeltaBytes,
+            },
+            stages: compactList(response.request.stages, 8),
+            hotCalls: compactList(response.request.hottestCalls, 6),
+            chain: compactList(response.request.chain || [], 8),
+            hotSql: compactList(response.request.hottestSqlQueries, 6).map(compactSql),
+        },
+        nextActions: [
+            {
+                label: 'Diagnose Request',
+                command: `proteum diagnose ${quoteCommandArgument(response.request.path)}`,
+                reason: 'Combine this request with owner, diagnostics, suspects, and logs.',
+            },
+            {
+                label: 'Trace Events',
+                command: `proteum trace show ${quoteCommandArgument(response.request.requestId)} --events`,
+                reason: 'Open raw event detail only if the compact waterfall is insufficient.',
+            },
+        ],
+        fullDetailCommand: `proteum perf request ${quoteCommandArgument(response.request.requestId)} --full`,
+    });
+};
+
 export const run = async () => {
     const action = getAction();
-    const shouldPrintJson = cli.args.json === true;
+    const shouldPrintFull = cli.args.full === true;
+    const shouldPrintHuman = cli.args.human === 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;
@@ -192,12 +293,13 @@ export const run = async () => {
         const response = await requestJson<TPerfTopResponse>(
             `/__proteum/perf/top?${new URLSearchParams({ groupBy, limit: String(limit), since }).toString()}`,
         );
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderTop(response));
+        if (shouldPrintHuman) console.log(renderTop(response));
+        else printCompactTop(response);
         return;
     }
 
@@ -212,12 +314,13 @@ export const run = async () => {
                 target: targetWindow,
             }).toString()}`,
         );
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderCompare(response));
+        if (shouldPrintHuman) console.log(renderCompare(response));
+        else printCompactCompare(response);
         return;
     }
 
@@ -226,12 +329,13 @@ export const run = async () => {
         const response = await requestJson<TPerfMemoryResponse>(
             `/__proteum/perf/memory?${new URLSearchParams({ groupBy, limit: String(limit), since }).toString()}`,
         );
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderMemory(response));
+        if (shouldPrintHuman) console.log(renderMemory(response));
+        else printCompactMemory(response);
         return;
     }
 
@@ -241,10 +345,11 @@ export const run = async () => {
     const response = await requestJson<TPerfRequestResponse>(
         `/__proteum/perf/request?${new URLSearchParams({ query: requestTarget }).toString()}`,
     );
-    if (shouldPrintJson) {
+    if (shouldPrintFull) {
         printJson(response);
         return;
     }
 
-    console.log(renderRequest(response));
+    if (shouldPrintHuman) console.log(renderRequest(response));
+    else printCompactRequest(response);
 };

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',
+    });
+};