proteum 2.1.0 → 2.1.1

package/cli/commands/doctor.ts

@@ -1,12 +1,7 @@
-import path from 'path';
-
 import cli from '..';
 import Compiler from '../compiler';
-import {
-    readProteumManifest,
-    type TProteumManifest,
-    type TProteumManifestDiagnostic,
-} from '../compiler/common/proteumManifest';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { buildDoctorResponse, renderDoctorHuman } from '@common/dev/diagnostics';
 
 const allowedDoctorArgs = new Set(['json', 'strict']);
 
@@ -24,43 +19,6 @@ const validateDoctorArgs = () => {
     }
 };
 
-const normalizePath = (value: string) => value.replace(/\\/g, '/');
-
-const formatFilepath = (manifest: TProteumManifest, filepath: string) => {
-    const normalizedFilepath = normalizePath(filepath);
-    const normalizedAppRoot = normalizePath(manifest.app.root);
-    const normalizedCoreRoot = normalizePath(manifest.app.coreRoot);
-
-    if (normalizedFilepath === normalizedAppRoot) return '.';
-    if (normalizedFilepath.startsWith(normalizedAppRoot + '/'))
-        return normalizePath(path.relative(normalizedAppRoot, normalizedFilepath)) || '.';
-
-    if (normalizedFilepath === normalizedCoreRoot) return 'node_modules/proteum';
-    if (normalizedFilepath.startsWith(normalizedCoreRoot + '/'))
-        return normalizePath(path.join('node_modules/proteum', path.relative(normalizedCoreRoot, normalizedFilepath)));
-
-    return normalizedFilepath;
-};
-
-const formatLocation = (diagnostic: TProteumManifestDiagnostic) =>
-    diagnostic.sourceLocation ? `:${diagnostic.sourceLocation.line}:${diagnostic.sourceLocation.column}` : '';
-
-const renderGroup = (manifest: TProteumManifest, diagnostics: TProteumManifestDiagnostic[], title: string) => {
-    if (diagnostics.length === 0) return `${title}\n- none`;
-
-    return [
-        title,
-        ...diagnostics.map((diagnostic) => {
-            const related =
-                diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
-                    ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatFilepath(manifest, filepath)).join(',')}`
-                    : '';
-
-            return `- ${diagnostic.code} ${diagnostic.message} source=${formatFilepath(manifest, diagnostic.filepath)}${formatLocation(diagnostic)}${related}`;
-        }),
-    ].join('\n');
-};
-
 export const run = async (): Promise<void> => {
     validateDoctorArgs();
 
@@ -68,41 +26,17 @@ export const run = async (): Promise<void> => {
     await compiler.refreshGeneratedTypings();
 
     const manifest = readProteumManifest(cli.paths.appRoot);
-    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error');
-    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+    const response = buildDoctorResponse(manifest, cli.args.strict === true);
 
     if (cli.args.json === true) {
-        console.log(
-            JSON.stringify(
-                {
-                    summary: {
-                        errors: errors.length,
-                        warnings: warnings.length,
-                        strictFailed: cli.args.strict === true && manifest.diagnostics.length > 0,
-                    },
-                    diagnostics: manifest.diagnostics,
-                },
-                null,
-                2,
-            ),
-        );
-    } else if (manifest.diagnostics.length === 0) {
-        console.log('Proteum doctor\n- No manifest diagnostics were found.');
+        console.log(JSON.stringify(response, null, 2));
     } else {
-        console.log(
-            [
-                'Proteum doctor',
-                `- ${errors.length} errors`,
-                `- ${warnings.length} warnings`,
-                '',
-                renderGroup(manifest, errors, 'Errors'),
-                '',
-                renderGroup(manifest, warnings, 'Warnings'),
-            ].join('\n'),
-        );
+        console.log(renderDoctorHuman(manifest, cli.args.strict === true));
     }
 
     if (cli.args.strict === true && manifest.diagnostics.length > 0) {
-        throw new Error(`Proteum doctor failed in strict mode with ${errors.length} errors and ${warnings.length} warnings.`);
+        throw new Error(
+            `Proteum doctor failed in strict mode with ${response.summary.errors} errors and ${response.summary.warnings} warnings.`,
+        );
     }
 };

package/cli/commands/explain.ts

@@ -1,22 +1,15 @@
-import path from 'path';
-
 import cli from '..';
 import Compiler from '../compiler';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
 import {
-    readProteumManifest,
-    type TProteumManifestDiagnostic,
-    type TProteumManifest,
-    type TProteumManifestController,
-    type TProteumManifestLayout,
-    type TProteumManifestRoute,
-    type TProteumManifestService,
-} from '../compiler/common/proteumManifest';
+    explainSectionNames,
+    pickExplainManifestSections,
+    renderExplainHuman,
+    type TExplainSectionName,
+} from '@common/dev/diagnostics';
 
-const explainSectionNames = ['app', 'conventions', 'env', 'services', 'controllers', 'routes', 'layouts', 'diagnostics'] as const;
 const allowedExplainArgs = new Set(['json', 'all', ...explainSectionNames]);
 
-type TExplainSectionName = (typeof explainSectionNames)[number];
-
 const validateExplainArgs = () => {
     const enabledArgs = Object.entries(cli.args)
         .filter(([name, value]) => name !== 'workdir' && name !== 'verbose' && value === true)
@@ -37,177 +30,6 @@ const getSelectedSections = (): TExplainSectionName[] => {
     return explainSectionNames.filter((sectionName) => cli.args[sectionName] === true);
 };
 
-const pickManifestSections = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
-    if (sectionNames.length === 0) return manifest;
-
-    const selected: Record<string, unknown> = {};
-
-    for (const sectionName of sectionNames) {
-        selected[sectionName] = manifest[sectionName];
-    }
-
-    return selected;
-};
-
-const normalizePath = (value: string) => value.replace(/\\/g, '/');
-const formatLocation = (line?: number, column?: number) =>
-    line && column ? `:${line}:${column}` : line ? `:${line}` : '';
-
-const formatFilepath = (manifest: TProteumManifest, filepath: string) => {
-    const normalizedFilepath = normalizePath(filepath);
-    const normalizedAppRoot = normalizePath(manifest.app.root);
-    const normalizedCoreRoot = normalizePath(manifest.app.coreRoot);
-
-    if (normalizedFilepath === normalizedAppRoot) return '.';
-    if (normalizedFilepath.startsWith(normalizedAppRoot + '/'))
-        return normalizePath(path.relative(normalizedAppRoot, normalizedFilepath)) || '.';
-
-    if (normalizedFilepath === normalizedCoreRoot) return 'node_modules/proteum';
-    if (normalizedFilepath.startsWith(normalizedCoreRoot + '/'))
-        return normalizePath(path.join('node_modules/proteum', path.relative(normalizedCoreRoot, normalizedFilepath)));
-
-    return normalizedFilepath;
-};
-
-const formatService = (manifest: TProteumManifest, service: TProteumManifestService) => {
-    if (service.kind === 'ref') {
-        return `- ${service.registeredName} -> ref ${service.refTo} [${service.parent}]`;
-    }
-
-    const source = service.metasFilepath ? formatFilepath(manifest, service.metasFilepath) : 'unknown';
-    return `- ${service.registeredName} -> ${service.id} (${service.metaName}) [${service.scope}] priority=${service.priority} source=${source}`;
-};
-
-const formatController = (manifest: TProteumManifest, controller: TProteumManifestController) =>
-    `- ${controller.clientAccessor} -> POST ${controller.httpPath} [${controller.scope}] input=${controller.hasInput ? 'yes' : 'no'} source=${formatFilepath(manifest, controller.filepath)}${formatLocation(controller.sourceLocation.line, controller.sourceLocation.column)}#${controller.methodName}`;
-
-const formatRouteTarget = (route: TProteumManifestRoute) => {
-    if (route.kind === 'client-error') return route.code !== undefined ? String(route.code) : route.codeRaw || '?';
-    return route.path || route.pathRaw || '?';
-};
-
-const formatRoute = (manifest: TProteumManifest, route: TProteumManifestRoute) => {
-    const chunk = route.chunkId ? ` chunk=${route.chunkId}` : '';
-    const setup = route.hasSetup ? ' setup=yes' : ' setup=no';
-    const options = route.normalizedOptionKeys.length > 0 ? ` options=${route.normalizedOptionKeys.join(',')}` : '';
-    const resolution = route.targetResolution !== 'literal' ? ` resolution=${route.targetResolution}` : '';
-
-    return `- ${route.kind} ${route.methodName} ${formatRouteTarget(route)} [${route.scope}]${chunk}${setup}${options}${resolution} source=${formatFilepath(manifest, route.filepath)}${formatLocation(route.sourceLocation.line, route.sourceLocation.column)}`;
-};
-
-const formatLayout = (manifest: TProteumManifest, layout: TProteumManifestLayout) =>
-    `- ${layout.chunkId || 'root'} depth=${layout.depth} [${layout.scope}] source=${formatFilepath(manifest, layout.filepath)}`;
-
-const formatDiagnostic = (manifest: TProteumManifest, diagnostic: TProteumManifestDiagnostic) => {
-    const related =
-        diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
-            ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatFilepath(manifest, filepath)).join(',')}`
-            : '';
-
-    return `- [${diagnostic.level}] ${diagnostic.code} ${diagnostic.message} source=${formatFilepath(manifest, diagnostic.filepath)}${formatLocation(diagnostic.sourceLocation?.line, diagnostic.sourceLocation?.column)}${related}`;
-};
-
-const printSection = (title: string, lines: string[]) => {
-    if (lines.length === 0) return `${title}\n- none`;
-    return `${title}\n${lines.join('\n')}`;
-};
-
-const renderSummary = (manifest: TProteumManifest) => {
-    const errorsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
-    const warningsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
-    const lines = [
-        `Proteum manifest: ${formatFilepath(manifest, path.join(manifest.app.root, '.proteum', 'manifest.json'))}`,
-        `App: ${manifest.app.identity.name} (${manifest.app.identity.identifier})`,
-        `Env keys: ${manifest.env.loadedTopLevelKeys.join(', ') || 'none'}`,
-        `Services: ${manifest.services.app.length} app, ${manifest.services.routerPlugins.length} router plugins`,
-        `Controllers: ${manifest.controllers.length}`,
-        `Routes: ${manifest.routes.client.length} client, ${manifest.routes.server.length} server`,
-        `Layouts: ${manifest.layouts.length}`,
-        `Diagnostics: ${errorsCount} errors, ${warningsCount} warnings`,
-        'Use `proteum explain --json` for the full machine-readable manifest or pass section flags like `routes` and `services`.',
-    ];
-
-    return lines.join('\n');
-};
-
-const renderHuman = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
-    if (sectionNames.length === 0) return renderSummary(manifest);
-
-    const sections: string[] = [];
-
-    for (const sectionName of sectionNames) {
-        if (sectionName === 'app') {
-            sections.push(
-                printSection('App', [
-                    `- root=${formatFilepath(manifest, manifest.app.root)}`,
-                    `- coreRoot=${formatFilepath(manifest, manifest.app.coreRoot)}`,
-                    `- identity=${formatFilepath(manifest, manifest.app.identityFilepath)}`,
-                    `- name=${manifest.app.identity.name}`,
-                    `- identifier=${manifest.app.identity.identifier}`,
-                    `- title=${manifest.app.identity.fullTitle || manifest.app.identity.title || manifest.app.identity.name}`,
-                ]),
-            );
-            continue;
-        }
-
-        if (sectionName === 'conventions') {
-            sections.push(
-                printSection('Conventions', [
-                    `- routeSetupOptionKeys=${manifest.conventions.routeSetupOptionKeys.join(', ')}`,
-                    `- reservedRouteSetupKeys=${manifest.conventions.reservedRouteSetupKeys.join(', ')}`,
-                ]),
-            );
-            continue;
-        }
-
-        if (sectionName === 'env') {
-            sections.push(
-                printSection('Env', [
-                    `- source=${formatFilepath(manifest, manifest.env.sourceFilepath)}`,
-                    `- loadedTopLevelKeys=${manifest.env.loadedTopLevelKeys.join(', ') || 'none'}`,
-                    `- requiredTopLevelKeys=${manifest.env.requiredTopLevelKeys.join(', ')}`,
-                ]),
-            );
-            continue;
-        }
-
-        if (sectionName === 'services') {
-            sections.push(
-                printSection('App Services', manifest.services.app.map((service) => formatService(manifest, service))),
-                printSection(
-                    'Router Plugins',
-                    manifest.services.routerPlugins.map((service) => formatService(manifest, service)),
-                ),
-            );
-            continue;
-        }
-
-        if (sectionName === 'controllers') {
-            sections.push(printSection('Controllers', manifest.controllers.map((controller) => formatController(manifest, controller))));
-            continue;
-        }
-
-        if (sectionName === 'routes') {
-            sections.push(
-                printSection('Client Routes', manifest.routes.client.map((route) => formatRoute(manifest, route))),
-                printSection('Server Routes', manifest.routes.server.map((route) => formatRoute(manifest, route))),
-            );
-            continue;
-        }
-
-        if (sectionName === 'layouts') {
-            sections.push(printSection('Layouts', manifest.layouts.map((layout) => formatLayout(manifest, layout))));
-            continue;
-        }
-
-        if (sectionName === 'diagnostics') {
-            sections.push(printSection('Diagnostics', manifest.diagnostics.map((diagnostic) => formatDiagnostic(manifest, diagnostic))));
-        }
-    }
-
-    return sections.join('\n\n');
-};
-
 export const run = async (): Promise<void> => {
     validateExplainArgs();
 
@@ -218,9 +40,9 @@ export const run = async (): Promise<void> => {
     const selectedSections = getSelectedSections();
 
     if (cli.args.json === true) {
-        console.log(JSON.stringify(pickManifestSections(manifest, selectedSections), null, 2));
+        console.log(JSON.stringify(pickExplainManifestSections(manifest, selectedSections), null, 2));
         return;
     }
 
-    console.log(renderHuman(manifest, selectedSections));
+    console.log(renderExplainHuman(manifest, selectedSections));
 };

package/cli/commands/trace.ts

@@ -0,0 +1,228 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import type {
+    TRequestTrace,
+    TRequestTraceArmResponse,
+    TRequestTraceErrorResponse,
+    TRequestTraceListItem,
+    TRequestTraceListResponse,
+    TRequestTraceResponse,
+} from '../../common/dev/requestTrace';
+
+type TTraceAction = 'latest' | 'show' | 'requests' | 'arm' | 'export';
+
+const allowedActions = new Set<TTraceAction>(['latest', 'show', 'requests', 'arm', 'export']);
+
+class TraceResponseError extends UsageError {}
+
+const getAction = () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'latest';
+    if (!allowedActions.has(action as TTraceAction)) {
+        throw new UsageError(`Unsupported trace action "${action}". Expected one of: ${[...allowedActions].join(', ')}.`);
+    }
+
+    return action as TTraceAction;
+};
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
+
+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 getTraceErrorMessage = (body: TRequestTraceErrorResponse | object | string | undefined, statusCode: number) => {
+    if (typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string') {
+        return body.error;
+    }
+
+    return `Trace request failed with status ${statusCode}.`;
+};
+
+const requestJson = async <TResponse>(pathname: string, options?: { method?: 'GET' | 'POST'; json?: object }) => {
+    const attempts: string[] = [];
+
+    for (const baseUrl of getRouterBaseUrls()) {
+        try {
+            const response = await got(`${baseUrl}${pathname}`, {
+                method: options?.method || 'GET',
+                json: options?.json,
+                responseType: 'json',
+                throwHttpErrors: false,
+                retry: { limit: 0 },
+            });
+
+            if (response.statusCode >= 400) {
+                throw new TraceResponseError(
+                    getTraceErrorMessage(response.body as TRequestTraceErrorResponse | object | string | undefined, response.statusCode),
+                );
+            }
+
+            return response.body as TResponse;
+        } catch (error) {
+            if (error instanceof TraceResponseError) throw error;
+
+            const message = error instanceof Error ? error.message : String(error);
+            attempts.push(`${baseUrl}${pathname}: ${message}`);
+        }
+    }
+
+    throw new UsageError(
+        [
+            'Could not reach the Proteum trace 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 renderTraceSummary = (request: TRequestTraceListItem) =>
+    [
+        `${request.id} ${request.method} ${request.path}`,
+        `status=${request.statusCode ?? 'pending'}`,
+        `capture=${request.capture}`,
+        `events=${request.eventCount}`,
+        `calls=${request.callCount}`,
+        request.user ? `user=${request.user}` : '',
+        request.errorMessage ? `error=${request.errorMessage}` : '',
+    ]
+        .filter(Boolean)
+        .join(' | ');
+
+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}`,
+        ...(request.user ? [`- user=${request.user}`] : []),
+        ...(request.persistedFilepath ? [`- persisted=${request.persistedFilepath}`] : []),
+        'Calls',
+        ...(request.calls.length === 0
+            ? ['- none']
+            : request.calls.map(
+                  (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(',')}`,
+              )),
+        'Events',
+        ...request.events.map(
+            (event) =>
+                `- [${event.elapsedMs}ms] ${event.type} ${Object.entries(event.details)
+                    .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+                    .join(' ')}`,
+        ),
+    ].join('\n');
+
+const printJson = (value: object) => {
+    console.log(JSON.stringify(value, null, 2));
+};
+
+export const run = async () => {
+    const action = getAction();
+    const requestId = typeof cli.args.id === 'string' ? cli.args.id : '';
+    const shouldPrintJson = cli.args.json === 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'));
+        return;
+    }
+
+    if (action === 'arm') {
+        const capture = typeof cli.args.capture === 'string' && cli.args.capture ? cli.args.capture : 'deep';
+        const response = await requestJson<TRequestTraceArmResponse>('/__proteum/trace/arm', {
+            method: 'POST',
+            json: { capture },
+        });
+
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(`Armed next request trace with capture=${response.capture}.`);
+        return;
+    }
+
+    if (action === 'latest') {
+        const response = await requestJson<TRequestTraceResponse>('/__proteum/trace/latest');
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderTrace(response.request));
+        return;
+    }
+
+    if (!requestId) {
+        throw new UsageError(`Trace action "${action}" requires a request id.`);
+    }
+
+    const response = await requestJson<TRequestTraceResponse>(`/__proteum/trace/requests/${requestId}`);
+
+    if (action === 'show') {
+        if (shouldPrintJson) {
+            printJson(response);
+            return;
+        }
+
+        console.log(renderTrace(response.request));
+        return;
+    }
+
+    const output =
+        typeof cli.args.output === 'string' && cli.args.output
+            ? cli.args.output
+            : path.join(cli.args.workdir as string, 'var', 'traces', 'exports', `${response.request.id}.json`);
+
+    fs.ensureDirSync(path.dirname(output));
+    fs.writeJSONSync(output, response.request, { spaces: 2 });
+
+    if (shouldPrintJson) {
+        printJson({ output, request: response.request });
+        return;
+    }
+
+    console.log(`Exported trace ${response.request.id} to ${output}`);
+};