proteum 2.1.0-5 → 2.1.1

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,91 @@
+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'
+    | '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

@@ -3,6 +3,10 @@ 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',
@@ -57,12 +61,34 @@ export type TTraceEvent = {
     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;
@@ -71,10 +97,11 @@ export type TRequestTrace = {
     droppedEvents: number;
     persistedFilepath?: string;
     errorMessage?: string;
+    calls: TTraceCall[];
     events: TTraceEvent[];
 };
 
-export type TRequestTraceListItem = Omit<TRequestTrace, 'events'> & { eventCount: number };
+export type TRequestTraceListItem = Omit<TRequestTrace, 'events' | 'calls'> & { eventCount: number; callCount: number };
 
 export type TRequestTraceListResponse = { requests: TRequestTraceListItem[] };
 export type TRequestTraceResponse = { request: TRequestTrace };

package/docs/dev-commands.md

@@ -0,0 +1,86 @@
+## Dev Commands
+
+Proteum supports a dev-only internal command surface for testing, debugging, and one-off server-side execution that should not be exposed as a normal controller or route.
+
+### Source Contract
+
+- command files live under `./commands/**/*.ts`
+- each file default-exports a class extending `Commands` from `@server/app/commands`
+- every method with a body becomes a runnable command
+- the command path is `file/path/methodName`
+- `export const commandPath = 'Custom/path'` can override the file-derived base path
+
+Example:
+
+```ts
+import { Commands } from '@server/app/commands';
+
+export default class DiagnosticsCommands extends Commands {
+  public async ping() {
+    return {
+      app: this.app.identity.identifier,
+      env: this.app.env.profile,
+    };
+  }
+}
+```
+
+The example above is available as `diagnostics/ping`.
+
+When `./commands` exists, Proteum also creates `./commands/tsconfig.json` plus a generated command typing surface under `.proteum/server/commands.d.ts`.
+
+- command files inherit the server alias project
+- `extends Commands` works without importing your app class
+- `@/server/index` remains available inside `/commands` as a generated command-only app type alias
+
+### CLI
+
+Run a command locally:
+
+```bash
+proteum command proteum/diagnostics/ping
+```
+
+Local mode does this:
+
+1. refreshes `.proteum` artifacts
+2. picks a temporary local port
+3. builds the dev server output
+4. starts a temporary local dev server
+5. runs the command through the dev-only command endpoint
+6. prints the result and exits
+
+Run a command against an existing dev instance:
+
+```bash
+proteum command proteum/diagnostics/ping --port 3101
+proteum command proteum/diagnostics/ping --url http://127.0.0.1:3101
+```
+
+Use `--port` or `--url` when you want to reuse an existing `proteum dev` instance instead of building and starting a temporary local one.
+
+### Profiler
+
+In `proteum dev`, the bottom profiler exposes a `Commands` tab.
+
+- it lists every generated command path
+- it shows the backing class, method, scope, and source location
+- clicking `Run now` executes the command through the running dev server
+- the last result or error stays attached to that command row in the panel
+
+### HTTP Endpoints
+
+The CLI remote mode and the profiler use the same dev-only endpoints:
+
+- `GET /__proteum/commands`
+- `POST /__proteum/commands/run`
+
+These endpoints exist only in dev mode and are not available in production.
+
+### Built-In Command
+
+Proteum ships one framework command by default:
+
+- `proteum/diagnostics/ping`
+
+It returns the current app identifier, active env profile, and discovered root services so every dev app has a real command surface available immediately.

package/docs/request-tracing.md

@@ -76,6 +76,8 @@ Notes:
 - `capture` defaults to `resolve`
 - `requestsLimit` defaults to `200`
 - `eventsLimit` defaults to `800`
+- `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
+- explicit `proteum trace export` files under `var/traces/exports/` are left in place
 
 ## Memory Model
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.0-5",
+	"version": "2.1.1",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -70,7 +70,6 @@
 		"preact-render-to-string": "^6.6.1",
 		"prompts": "^2.4.2",
 		"replace-once": "^1.0.0",
-		"request": "^2.88.2",
 		"responsive-loader": "^3.1.2",
 		"serialize-javascript": "^6.0.2",
 		"sharp": "^0.34.3",