proteum 2.1.0 → 2.1.2

package/common/dev/diagnostics.ts

@@ -0,0 +1,298 @@
+import type {
+    TProteumManifest,
+    TProteumManifestCommand,
+    TProteumManifestController,
+    TProteumManifestDiagnostic,
+    TProteumManifestLayout,
+    TProteumManifestRoute,
+    TProteumManifestService,
+} from './proteumManifest';
+
+export const explainSectionNames = ['app', 'conventions', 'env', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'] as const;
+
+export type TExplainSectionName = (typeof explainSectionNames)[number];
+export type THumanTextBlock = {
+    title: string;
+    items: string[];
+    empty?: string;
+};
+export type TDoctorResponse = {
+    summary: {
+        errors: number;
+        warnings: number;
+        strictFailed: boolean;
+    };
+    diagnostics: TProteumManifestDiagnostic[];
+};
+
+const normalizePath = (value: string) => value.replace(/\\/g, '/');
+const emptyBlock = 'none';
+
+export const formatManifestLocation = (line?: number, column?: number) =>
+    line && column ? `:${line}:${column}` : line ? `:${line}` : '';
+
+export const formatManifestFilepath = (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 normalizedFilepath.slice(normalizedAppRoot.length + 1) || '.';
+
+    if (normalizedFilepath === normalizedCoreRoot) return 'node_modules/proteum';
+    if (normalizedFilepath.startsWith(normalizedCoreRoot + '/'))
+        return `node_modules/proteum/${normalizedFilepath.slice(normalizedCoreRoot.length + 1)}`;
+
+    return normalizedFilepath;
+};
+
+const formatServiceItem = (manifest: TProteumManifest, service: TProteumManifestService) => {
+    if (service.kind === 'ref') {
+        return `${service.registeredName} -> ref ${service.refTo} [${service.parent}]`;
+    }
+
+    const source = service.metasFilepath ? formatManifestFilepath(manifest, service.metasFilepath) : 'unknown';
+    return `${service.registeredName} -> ${service.id} (${service.metaName}) [${service.scope}] priority=${service.priority} source=${source}`;
+};
+
+const formatControllerItem = (manifest: TProteumManifest, controller: TProteumManifestController) =>
+    `${controller.clientAccessor} -> POST ${controller.httpPath} [${controller.scope}] input=${controller.hasInput ? 'yes' : 'no'} source=${formatManifestFilepath(manifest, controller.filepath)}${formatManifestLocation(controller.sourceLocation.line, controller.sourceLocation.column)}#${controller.methodName}`;
+
+const formatCommandItem = (manifest: TProteumManifest, command: TProteumManifestCommand) =>
+    `${command.path} -> ${command.className}.${command.methodName} [${command.scope}] source=${formatManifestFilepath(manifest, command.filepath)}${formatManifestLocation(command.sourceLocation.line, command.sourceLocation.column)}`;
+
+const formatRouteTarget = (route: TProteumManifestRoute) => {
+    if (route.kind === 'client-error') return route.code !== undefined ? String(route.code) : route.codeRaw || '?';
+    return route.path || route.pathRaw || '?';
+};
+
+const formatRouteItem = (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=${formatManifestFilepath(manifest, route.filepath)}${formatManifestLocation(route.sourceLocation.line, route.sourceLocation.column)}`;
+};
+
+const formatLayoutItem = (manifest: TProteumManifest, layout: TProteumManifestLayout) =>
+    `${layout.chunkId || 'root'} depth=${layout.depth} [${layout.scope}] source=${formatManifestFilepath(manifest, layout.filepath)}`;
+
+const formatDiagnosticItem = (manifest: TProteumManifest, diagnostic: TProteumManifestDiagnostic) => {
+    const related =
+        diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
+            ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatManifestFilepath(manifest, filepath)).join(',')}`
+            : '';
+
+    return `[${diagnostic.level}] ${diagnostic.code} ${diagnostic.message} source=${formatManifestFilepath(manifest, diagnostic.filepath)}${formatManifestLocation(diagnostic.sourceLocation?.line, diagnostic.sourceLocation?.column)}${related}`;
+};
+
+export const pickExplainManifestSections = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
+    if (sectionNames.length === 0) return manifest;
+
+    const selected: Partial<TProteumManifest> = {};
+
+    for (const sectionName of sectionNames) {
+        selected[sectionName] = manifest[sectionName];
+    }
+
+    return selected;
+};
+
+export const buildExplainSummaryItems = (manifest: TProteumManifest) => {
+    const errorsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warningsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+    const providedRequiredEnvVariables = manifest.env.requiredVariables.filter((variable) => variable.provided).length;
+
+    return [
+        `Proteum manifest: ${formatManifestFilepath(manifest, `${normalizePath(manifest.app.root)}/.proteum/manifest.json`)}`,
+        `App: ${manifest.app.identity.name} (${manifest.app.identity.identifier})`,
+        `Env vars: ${providedRequiredEnvVariables}/${manifest.env.requiredVariables.length} required provided`,
+        `Services: ${manifest.services.app.length} app, ${manifest.services.routerPlugins.length} router plugins`,
+        `Controllers: ${manifest.controllers.length}`,
+        `Commands: ${manifest.commands.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`.',
+    ];
+};
+
+export const buildExplainBlocks = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]): THumanTextBlock[] => {
+    const blocks: THumanTextBlock[] = [];
+
+    for (const sectionName of sectionNames) {
+        if (sectionName === 'app') {
+            blocks.push({
+                title: 'App',
+                items: [
+                    `root=${formatManifestFilepath(manifest, manifest.app.root)}`,
+                    `coreRoot=${formatManifestFilepath(manifest, manifest.app.coreRoot)}`,
+                    `identity=${formatManifestFilepath(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') {
+            blocks.push({
+                title: 'Conventions',
+                items: [
+                    `routeSetupOptionKeys=${manifest.conventions.routeSetupOptionKeys.join(', ')}`,
+                    `reservedRouteSetupKeys=${manifest.conventions.reservedRouteSetupKeys.join(', ')}`,
+                ],
+            });
+            continue;
+        }
+
+        if (sectionName === 'env') {
+            blocks.push({
+                title: 'Env',
+                items: [
+                    `source=${manifest.env.source}`,
+                    `loadedVariableKeys=${manifest.env.loadedVariableKeys.join(', ') || 'none'}`,
+                    ...manifest.env.requiredVariables.map(
+                        (variable) =>
+                            `${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`,
+                    ),
+                    `resolved.name=${manifest.env.resolved.name}`,
+                    `resolved.profile=${manifest.env.resolved.profile}`,
+                    `resolved.routerPort=${manifest.env.resolved.routerPort}`,
+                    `resolved.routerCurrentDomain=${manifest.env.resolved.routerCurrentDomain}`,
+                ],
+            });
+            continue;
+        }
+
+        if (sectionName === 'services') {
+            blocks.push(
+                {
+                    title: 'App Services',
+                    items: manifest.services.app.map((service) => formatServiceItem(manifest, service)),
+                },
+                {
+                    title: 'Router Plugins',
+                    items: manifest.services.routerPlugins.map((service) => formatServiceItem(manifest, service)),
+                },
+            );
+            continue;
+        }
+
+        if (sectionName === 'controllers') {
+            blocks.push({
+                title: 'Controllers',
+                items: manifest.controllers.map((controller) => formatControllerItem(manifest, controller)),
+            });
+            continue;
+        }
+
+        if (sectionName === 'commands') {
+            blocks.push({
+                title: 'Commands',
+                items: manifest.commands.map((command) => formatCommandItem(manifest, command)),
+            });
+            continue;
+        }
+
+        if (sectionName === 'routes') {
+            blocks.push(
+                {
+                    title: 'Client Routes',
+                    items: manifest.routes.client.map((route) => formatRouteItem(manifest, route)),
+                },
+                {
+                    title: 'Server Routes',
+                    items: manifest.routes.server.map((route) => formatRouteItem(manifest, route)),
+                },
+            );
+            continue;
+        }
+
+        if (sectionName === 'layouts') {
+            blocks.push({
+                title: 'Layouts',
+                items: manifest.layouts.map((layout) => formatLayoutItem(manifest, layout)),
+            });
+            continue;
+        }
+
+        if (sectionName === 'diagnostics') {
+            blocks.push({
+                title: 'Diagnostics',
+                items: manifest.diagnostics.map((diagnostic) => formatDiagnosticItem(manifest, diagnostic)),
+            });
+        }
+    }
+
+    return blocks;
+};
+
+export const renderHumanBlock = (block: THumanTextBlock) => {
+    if (block.items.length === 0) return `${block.title}\n- ${block.empty || emptyBlock}`;
+    return `${block.title}\n${block.items.map((item) => `- ${item}`).join('\n')}`;
+};
+
+export const renderExplainHuman = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
+    if (sectionNames.length === 0) return buildExplainSummaryItems(manifest).join('\n');
+    return buildExplainBlocks(manifest, sectionNames).map(renderHumanBlock).join('\n\n');
+};
+
+export const buildDoctorResponse = (manifest: TProteumManifest, strict = false): TDoctorResponse => {
+    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error');
+    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+
+    return {
+        summary: {
+            errors: errors.length,
+            warnings: warnings.length,
+            strictFailed: strict === true && manifest.diagnostics.length > 0,
+        },
+        diagnostics: manifest.diagnostics,
+    };
+};
+
+export const buildDoctorBlocks = (manifest: TProteumManifest): THumanTextBlock[] => {
+    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error');
+    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+
+    return [
+        {
+            title: 'Errors',
+            items: errors.map((diagnostic) => {
+                const related =
+                    diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
+                        ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatManifestFilepath(manifest, filepath)).join(',')}`
+                        : '';
+
+                return `${diagnostic.code} ${diagnostic.message} source=${formatManifestFilepath(manifest, diagnostic.filepath)}${formatManifestLocation(diagnostic.sourceLocation?.line, diagnostic.sourceLocation?.column)}${related}`;
+            }),
+        },
+        {
+            title: 'Warnings',
+            items: warnings.map((diagnostic) => {
+                const related =
+                    diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
+                        ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatManifestFilepath(manifest, filepath)).join(',')}`
+                        : '';
+
+                return `${diagnostic.code} ${diagnostic.message} source=${formatManifestFilepath(manifest, diagnostic.filepath)}${formatManifestLocation(diagnostic.sourceLocation?.line, diagnostic.sourceLocation?.column)}${related}`;
+            }),
+        },
+    ];
+};
+
+export const renderDoctorHuman = (manifest: TProteumManifest, strict = false) => {
+    const response = buildDoctorResponse(manifest, strict);
+    if (response.diagnostics.length === 0) return 'Proteum doctor\n- No manifest diagnostics were found.';
+
+    return [
+        'Proteum doctor',
+        `- ${response.summary.errors} errors`,
+        `- ${response.summary.warnings} warnings`,
+        '',
+        ...buildDoctorBlocks(manifest).map(renderHumanBlock),
+    ].join('\n');
+};

package/common/dev/profiler.ts

@@ -0,0 +1,92 @@
+import type { TRequestTrace } from './requestTrace';
+
+export const profilerTraceRequestIdHeader = 'x-proteum-trace-request-id';
+export const profilerSessionIdHeader = 'x-proteum-profiler-session-id';
+export const profilerOriginHeader = 'x-proteum-profiler-origin';
+export const profilerParentRequestIdHeader = 'x-proteum-profiler-parent-request-id';
+
+export type TProfilerUiState = 'expanded' | 'minimized' | 'pinned-handle';
+export type TProfilerPanel =
+    | 'summary'
+    | 'timeline'
+    | 'auth'
+    | 'routing'
+    | 'controller'
+    | 'ssr'
+    | 'api'
+    | 'explain'
+    | 'doctor'
+    | 'commands'
+    | 'cron'
+    | 'errors';
+export type TProfilerNavigationSessionKind = 'initial-ssr' | 'client-navigation';
+export type TProfilerSessionTraceKind = 'initial-root' | 'navigation-data' | 'async';
+export type TProfilerNavigationStepStatus = 'pending' | 'completed' | 'error';
+export type TProfilerCronTaskTrigger = 'scheduler' | 'manual' | 'autoexec';
+export type TProfilerCronTaskRunStatus = 'completed' | 'error';
+
+export type TProfilerCronTaskFrequency =
+    | { kind: 'cron'; value: string }
+    | { kind: 'date'; value: string };
+
+export type TProfilerCronTask = {
+    name: string;
+    registeredAt: string;
+    frequency: TProfilerCronTaskFrequency;
+    autoexec: boolean;
+    automaticExecution: boolean;
+    nextInvocation?: string;
+    running: boolean;
+    lastTrigger?: TProfilerCronTaskTrigger;
+    lastRunStartedAt?: string;
+    lastRunFinishedAt?: string;
+    lastRunDurationMs?: number;
+    lastRunStatus?: TProfilerCronTaskRunStatus;
+    lastErrorMessage?: string;
+    runCount: number;
+};
+
+export type TProfilerNavigationStep = {
+    id: string;
+    label: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    status: TProfilerNavigationStepStatus;
+    details?: { [key: string]: string | number | boolean };
+    errorMessage?: string;
+};
+
+export type TProfilerSessionTrace = {
+    id: string;
+    kind: TProfilerSessionTraceKind;
+    label: string;
+    method: string;
+    path: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    status: 'pending' | 'completed' | 'error';
+    requestId?: string;
+    fetcherIds?: string[];
+    trace?: TRequestTrace;
+    errorMessage?: string;
+};
+
+export type TProfilerNavigationSession = {
+    id: string;
+    kind: TProfilerNavigationSessionKind;
+    label: string;
+    path: string;
+    url: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    status: 'active' | 'completed' | 'error';
+    requestId?: string;
+    routeLabel?: string;
+    routeChunkId?: string;
+    title?: string;
+    steps: TProfilerNavigationStep[];
+    traces: TProfilerSessionTrace[];
+};

package/common/dev/proteumManifest.ts

@@ -0,0 +1,135 @@
+export type TProteumManifestScope = 'app' | 'framework';
+export type TProteumManifestSourceLocation = { line: number; column: number };
+export type TProteumManifestRouteTargetResolution = 'literal' | 'static-expression' | 'dynamic-expression';
+export type TProteumManifestDiagnosticLevel = 'warning' | 'error';
+
+export type TProteumManifestDiagnostic = {
+    level: TProteumManifestDiagnosticLevel;
+    code: string;
+    message: string;
+    filepath: string;
+    sourceLocation?: TProteumManifestSourceLocation;
+    relatedFilepaths?: string[];
+};
+
+export type TProteumManifestService = {
+    kind: 'service' | 'ref';
+    id?: string;
+    registeredName: string;
+    metaName?: string;
+    parent: string;
+    priority: number;
+    importPath?: string;
+    sourceDir?: string;
+    metasFilepath?: string;
+    refTo?: string;
+    scope: TProteumManifestScope;
+};
+
+export type TProteumManifestController = {
+    className: string;
+    importPath: string;
+    filepath: string;
+    sourceLocation: TProteumManifestSourceLocation;
+    routeBasePath: string;
+    methodName: string;
+    inputCallsCount: number;
+    hasInput: boolean;
+    routePath: string;
+    httpPath: string;
+    clientAccessor: string;
+    scope: TProteumManifestScope;
+};
+
+export type TProteumManifestCommand = {
+    className: string;
+    importPath: string;
+    filepath: string;
+    sourceLocation: TProteumManifestSourceLocation;
+    commandBasePath: string;
+    methodName: string;
+    path: string;
+    scope: TProteumManifestScope;
+};
+
+export type TProteumManifestRoute = {
+    kind: 'client-page' | 'client-error' | 'server-route';
+    methodName: string;
+    serviceLocalName: string;
+    filepath: string;
+    sourceLocation: TProteumManifestSourceLocation;
+    targetResolution: TProteumManifestRouteTargetResolution;
+    path?: string;
+    pathRaw?: string;
+    code?: number;
+    codeRaw?: string;
+    optionKeys: string[];
+    normalizedOptionKeys: string[];
+    invalidOptionKeys: string[];
+    reservedOptionKeys: string[];
+    optionsRaw?: string;
+    hasSetup: boolean;
+    chunkId?: string;
+    chunkFilepath?: string;
+    scope: TProteumManifestScope;
+};
+
+export type TProteumManifestLayout = {
+    chunkId: string;
+    filepath: string;
+    importPath: string;
+    depth: number;
+    scope: TProteumManifestScope;
+};
+
+export type TProteumManifest = {
+    version: 2;
+    app: {
+        root: string;
+        coreRoot: string;
+        identityFilepath: string;
+        identity: {
+            name: string;
+            identifier: string;
+            description: string;
+            language?: string;
+            locale?: string;
+            title?: string;
+            titleSuffix?: string;
+            fullTitle?: string;
+            webDescription?: string;
+            version?: string;
+        };
+    };
+    conventions: {
+        routeSetupOptionKeys: string[];
+        reservedRouteSetupKeys: string[];
+    };
+    env: {
+        source: string;
+        loadedVariableKeys: string[];
+        requiredVariables: {
+            key: string;
+            possibleValues: string[];
+            provided: boolean;
+        }[];
+        resolved: {
+            name: string;
+            profile: string;
+            routerPort: number;
+            routerCurrentDomain: string;
+        };
+    };
+    services: {
+        app: TProteumManifestService[];
+        routerPlugins: TProteumManifestService[];
+    };
+    controllers: TProteumManifestController[];
+    commands: TProteumManifestCommand[];
+    routes: {
+        client: TProteumManifestRoute[];
+        server: TProteumManifestRoute[];
+    };
+    layouts: TProteumManifestLayout[];
+    diagnostics: TProteumManifestDiagnostic[];
+};

package/common/dev/requestTrace.ts

@@ -0,0 +1,115 @@
+export const traceCaptureModes = ['summary', 'resolve', 'deep'] as const;
+
+export type TTraceCaptureMode = (typeof traceCaptureModes)[number];
+type TTracePrimitive = string | number | boolean;
+
+export const traceCallOrigins = ['ssr-fetcher', 'api-batch-fetcher', 'client-async'] as const;
+
+export type TTraceCallOrigin = (typeof traceCallOrigins)[number];
+
+export const traceEventTypes = [
+    'request.start',
+    'request.user',
+    'auth.decode',
+    'auth.route',
+    'auth.check.start',
+    'auth.check.rule',
+    'auth.check.result',
+    'auth.session',
+    'resolve.start',
+    'resolve.controller-route',
+    'resolve.routes-evaluated',
+    'resolve.route-skip',
+    'resolve.route-match',
+    'resolve.not-found',
+    'controller.start',
+    'controller.result',
+    'setup.options',
+    'context.create',
+    'page.data',
+    'ssr.payload',
+    'render.start',
+    'render.end',
+    'response.send',
+    'request.finish',
+    'error',
+] as const;
+
+export type TTraceEventType = (typeof traceEventTypes)[number];
+
+export type TTraceSummaryValue =
+    | TTracePrimitive
+    | null
+    | { kind: 'undefined' }
+    | { kind: 'redacted'; reason: string }
+    | { kind: 'bigint'; value: string }
+    | { kind: 'symbol'; value: string }
+    | { kind: 'function'; name: string }
+    | { kind: 'date'; value: string }
+    | { kind: 'error'; name: string; message: string; stack?: string }
+    | { kind: 'buffer'; byteLength: number }
+    | { kind: 'array'; length: number; items: TTraceSummaryValue[]; truncated: boolean }
+    | {
+          kind: 'object';
+          constructorName: string;
+          keys: string[];
+          entries: { [key: string]: TTraceSummaryValue };
+          truncated: boolean;
+      }
+    | { kind: 'map'; size: number }
+    | { kind: 'set'; size: number };
+
+export type TTraceEvent = {
+    index: number;
+    at: string;
+    elapsedMs: number;
+    type: TTraceEventType;
+    details: { [key: string]: TTraceSummaryValue };
+};
+
+export type TTraceCall = {
+    id: string;
+    parentId?: string;
+    origin: TTraceCallOrigin;
+    label: string;
+    method: string;
+    path: string;
+    fetcherId?: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    errorMessage?: string;
+    requestDataKeys: string[];
+    requestData?: TTraceSummaryValue;
+    resultKeys: string[];
+    result?: TTraceSummaryValue;
+};
+
+export type TRequestTrace = {
+    id: string;
+    method: string;
+    path: string;
+    url: string;
+    capture: TTraceCaptureMode;
+    profilerSessionId?: string;
+    profilerOrigin?: string;
+    profilerParentRequestId?: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    user?: string;
+    droppedEvents: number;
+    persistedFilepath?: string;
+    errorMessage?: string;
+    calls: TTraceCall[];
+    events: TTraceEvent[];
+};
+
+export type TRequestTraceListItem = Omit<TRequestTrace, 'events' | 'calls'> & { eventCount: number; callCount: number };
+
+export type TRequestTraceListResponse = { requests: TRequestTraceListItem[] };
+export type TRequestTraceResponse = { request: TRequestTrace };
+export type TRequestTraceArmResponse = { armed: true; capture: TTraceCaptureMode };
+export type TRequestTraceErrorResponse = { error: string };