proteum 2.1.3-1 → 2.1.7

package/common/dev/profiler.ts

@@ -9,11 +9,14 @@ export type TProfilerUiState = 'expanded' | 'minimized' | 'pinned-handle';
 export type TProfilerPanel =
     | 'summary'
     | 'timeline'
+    | 'perf'
     | 'auth'
     | 'routing'
     | 'controller'
     | 'ssr'
     | 'api'
+    | 'sql'
+    | 'diagnose'
     | 'explain'
     | 'doctor'
     | 'commands'

package/common/dev/proteumManifest.ts

@@ -1,4 +1,9 @@
-export type TProteumManifestScope = 'app' | 'framework';
+import type {
+    TConnectedProjectSourceKind,
+    TConnectedProjectTypingMode,
+} from '../connectedProjects';
+
+export type TProteumManifestScope = 'app' | 'framework' | 'connected';
 export type TProteumManifestSourceLocation = { line: number; column: number };
 export type TProteumManifestRouteTargetResolution = 'literal' | 'static-expression' | 'dynamic-expression';
 export type TProteumManifestDiagnosticLevel = 'warning' | 'error';
@@ -14,14 +19,12 @@ export type TProteumManifestDiagnostic = {
 
 export type TProteumManifestService = {
     kind: 'service' | 'ref';
-    id?: string;
     registeredName: string;
-    metaName?: string;
+    className?: string;
     parent: string;
     priority: number;
     importPath?: string;
-    sourceDir?: string;
-    metasFilepath?: string;
+    sourceFilepath?: string;
     refTo?: string;
     scope: TProteumManifestScope;
 };
@@ -39,6 +42,21 @@ export type TProteumManifestController = {
     httpPath: string;
     clientAccessor: string;
     scope: TProteumManifestScope;
+    connectedProjectNamespace?: string;
+    connectedProjectIdentifier?: string;
+};
+
+export type TProteumManifestConnectedProject = {
+    namespace: string;
+    packageName?: string;
+    identityIdentifier?: string;
+    identityName?: string;
+    sourceKind?: TConnectedProjectSourceKind;
+    sourceValue?: string;
+    cachedContractFilepath?: string;
+    typingMode?: TConnectedProjectTypingMode;
+    urlInternal?: string;
+    controllerCount: number;
 };
 
 export type TProteumManifestCommand = {
@@ -83,11 +101,12 @@ export type TProteumManifestLayout = {
 };
 
 export type TProteumManifest = {
-    version: 2;
+    version: 9;
     app: {
         root: string;
         coreRoot: string;
         identityFilepath: string;
+        setupFilepath: string;
         identity: {
             name: string;
             identifier: string;
@@ -100,6 +119,10 @@ export type TProteumManifest = {
             webDescription?: string;
             version?: string;
         };
+        setup: {
+            transpile?: string[];
+            connect?: Record<string, { source?: string; urlInternal?: string }>;
+        };
     };
     conventions: {
         routeSetupOptionKeys: string[];
@@ -118,8 +141,10 @@ export type TProteumManifest = {
             profile: string;
             routerPort: number;
             routerCurrentDomain: string;
+            routerInternalUrl: string;
         };
     };
+    connectedProjects: TProteumManifestConnectedProject[];
     services: {
         app: TProteumManifestService[];
         routerPlugins: TProteumManifestService[];

package/common/dev/requestTrace.ts

@@ -6,6 +6,10 @@ 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 traceSqlQueryKinds = ['orm', 'raw'] as const;
+
+export type TTraceSqlQueryKind = (typeof traceSqlQueryKinds)[number];
+export type TTraceSqlQueryCallerOrigin = TTraceCallOrigin | 'request';
 
 export const traceEventTypes = [
     'request.start',
@@ -75,6 +79,8 @@ export type TTraceCall = {
     method: string;
     path: string;
     fetcherId?: string;
+    connectedProjectNamespace?: string;
+    connectedControllerAccessor?: string;
     startedAt: string;
     finishedAt?: string;
     durationMs?: number;
@@ -88,6 +94,45 @@ export type TTraceCall = {
     resultJson?: unknown;
 };
 
+export type TTraceSqlQuery = {
+    id: string;
+    callerCallId?: string;
+    callerFetcherId?: string;
+    callerLabel?: string;
+    callerMethod: string;
+    callerOrigin: TTraceSqlQueryCallerOrigin;
+    callerPath: string;
+    durationMs: number;
+    finishedAt: string;
+    kind: TTraceSqlQueryKind;
+    model?: string;
+    operation: string;
+    paramsJson?: unknown;
+    paramsText?: string;
+    query: string;
+    startedAt: string;
+    target?: string;
+};
+
+export type TTraceMemorySnapshot = {
+    arrayBuffers: number;
+    external: number;
+    heapTotal: number;
+    heapUsed: number;
+    rss: number;
+};
+
+export type TRequestTracePerformance = {
+    cpu: {
+        systemMicros: number;
+        userMicros: number;
+    };
+    memory: {
+        after: TTraceMemorySnapshot;
+        before: TTraceMemorySnapshot;
+    };
+};
+
 export type TRequestTrace = {
     id: string;
     method: string;
@@ -107,11 +152,17 @@ export type TRequestTrace = {
     errorMessage?: string;
     requestDataJson?: unknown;
     resultJson?: unknown;
+    performance?: TRequestTracePerformance;
     calls: TTraceCall[];
+    sqlQueries: TTraceSqlQuery[];
     events: TTraceEvent[];
 };
 
-export type TRequestTraceListItem = Omit<TRequestTrace, 'events' | 'calls'> & { eventCount: number; callCount: number };
+export type TRequestTraceListItem = Omit<TRequestTrace, 'events' | 'calls' | 'sqlQueries'> & {
+    eventCount: number;
+    callCount: number;
+    sqlQueryCount: number;
+};
 
 export type TRequestTraceListResponse = { requests: TRequestTraceListItem[] };
 export type TRequestTraceResponse = { request: TRequestTrace };

package/common/env/proteumEnv.ts

@@ -2,11 +2,16 @@ import fs from 'fs';
 import path from 'path';
 import dotenv from 'dotenv';
 
+import {
+    normalizeConnectedProjectsConfig,
+    type TConnectedProjectsConfig,
+} from '../connectedProjects';
+
 export type TProteumEnvName = 'local' | 'server';
 export type TProteumEnvProfile = 'dev' | 'testing' | 'prod';
 export type TProteumTraceCapture = 'summary' | 'resolve' | 'deep';
 export type TProteumRequiredEnvVariable = {
-    key: TProteumRequiredEnvVariableKey;
+    key: string;
     possibleValues: string[];
     provided: boolean;
 };
@@ -15,13 +20,20 @@ export type TProteumEnvInspection = {
     requiredVariables: TProteumRequiredEnvVariable[];
 };
 
+export type TProteumConnectedProjectEnvConfig = {
+    namespace: string;
+    urlInternal: string;
+};
+
 export type TProteumEnvConfig = {
     name: TProteumEnvName;
     profile: TProteumEnvProfile;
     router: {
         port: number;
         currentDomain: string;
+        internalUrl: string;
     };
+    connectedProjects: Record<string, TProteumConnectedProjectEnvConfig>;
     trace: {
         enable: boolean;
         requestsLimit: number;
@@ -34,32 +46,40 @@ export type TProteumEnvConfig = {
 export type TProteumLoadedEnvConfig = TProteumEnvConfig & { version: string };
 
 const dotenvFileNames = ['.env'];
-const requiredProteumEnvVariableKeys = ['ENV_NAME', 'ENV_PROFILE', 'PORT', 'URL'] as const;
+const baseRequiredProteumEnvVariableDefinitions = [
+    { key: 'ENV_NAME', possibleValues: ['local', 'server'] },
+    { key: 'ENV_PROFILE', possibleValues: ['dev', 'testing', 'prod'] },
+    { key: 'PORT', possibleValues: ['integer between 1 and 65535'] },
+    { key: 'URL', possibleValues: ['absolute URL'] },
+    { key: 'URL_INTERNAL', possibleValues: ['absolute URL'] },
+] as const;
 const optionalProteumEnvVariablePrefixes = ['TRACE_'] as const;
 
-export type TProteumRequiredEnvVariableKey = (typeof requiredProteumEnvVariableKeys)[number];
-
-const requiredProteumEnvVariablePossibleValues: Record<TProteumRequiredEnvVariableKey, string[]> = {
-    ENV_NAME: ['local', 'server'],
-    ENV_PROFILE: ['dev', 'testing', 'prod'],
-    PORT: ['integer between 1 and 65535'],
-    URL: ['absolute URL'],
+type TEnvContext = {
+    appDir: string;
+    connectedProjects: TConnectedProjectsConfig;
 };
 
 const envDefinitionHint = (appDir: string) => `Define it in process.env or ${appDir}/.env.`;
 const isProvidedEnvValue = (value: string | undefined) => typeof value === 'string' && value.trim() !== '';
 
+const buildRequiredEnvVariableDefinitions = (_connectedProjects: TConnectedProjectsConfig) => [...baseRequiredProteumEnvVariableDefinitions];
+
+const buildOptionalEnvKeys = (_connectedProjects: TConnectedProjectsConfig) => [] as string[];
+
 const formatRequiredEnvVariableStatus = (variable: TProteumRequiredEnvVariable) =>
     `- ${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`;
 
 const createProteumEnvError = ({
     appDir,
+    connectedProjects,
     message,
 }: {
     appDir: string;
+    connectedProjects: TConnectedProjectsConfig;
     message: string;
 }) => {
-    const inspection = inspectProteumEnv(appDir);
+    const inspection = inspectProteumEnv(appDir, connectedProjects);
 
     return new Error(
         [message, envDefinitionHint(appDir), '', 'Required env variables:', ...inspection.requiredVariables.map(formatRequiredEnvVariableStatus)].join(
@@ -71,11 +91,11 @@ const createProteumEnvError = ({
 const parseBooleanEnvValue = ({
     key,
     value,
-    appDir,
+    context,
 }: {
     key: string;
     value: string | undefined;
-    appDir: string;
+    context: TEnvContext;
 }) => {
     if (value === undefined || value === '') return undefined;
 
@@ -84,7 +104,7 @@ const parseBooleanEnvValue = ({
     if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
 
     throw createProteumEnvError({
-        appDir,
+        ...context,
         message: `Invalid boolean value for ${key}: "${value}". Expected one of: 1, 0, true, false, yes, no, on, off.`,
     });
 };
@@ -92,18 +112,18 @@ const parseBooleanEnvValue = ({
 const parseIntegerEnvValue = ({
     key,
     value,
-    appDir,
+    context,
     min = 1,
 }: {
     key: string;
     value: string;
-    appDir: string;
+    context: TEnvContext;
     min?: number;
 }) => {
     const parsed = Number.parseInt(value, 10);
     if (Number.isNaN(parsed) || parsed < min) {
         throw createProteumEnvError({
-            appDir,
+            ...context,
             message: `Invalid integer value for ${key}: "${value}". Expected an integer greater than or equal to ${min}.`,
         });
     }
@@ -111,44 +131,78 @@ const parseIntegerEnvValue = ({
     return parsed;
 };
 
-const getRequiredEnvValue = ({ key, appDir }: { key: TProteumRequiredEnvVariableKey; appDir: string }) => {
+const getRequiredEnvValue = ({
+    key,
+    context,
+}: {
+    key: string;
+    context: TEnvContext;
+}) => {
     const value = process.env[key]?.trim();
     if (value) return value;
 
     throw createProteumEnvError({
-        appDir,
+        ...context,
         message: `Missing required Proteum env variable "${key}".`,
     });
 };
 
-const parseEnvName = (value: string, appDir: string): TProteumEnvName => {
+const createConnectedProjectConfigError = ({
+    appDir,
+    message,
+}: {
+    appDir: string;
+    message: string;
+}) => new Error(`${message} Define it explicitly in ${path.join(appDir, 'proteum.config.ts')}.`);
+
+const getRequiredConnectedConfigValue = ({
+    appDir,
+    namespace,
+    field,
+    value,
+}: {
+    appDir: string;
+    namespace: string;
+    field: 'source' | 'urlInternal';
+    value: string | undefined;
+}) => {
+    const normalized = value?.trim();
+    if (normalized) return normalized;
+
+    throw createConnectedProjectConfigError({
+        appDir,
+        message: `Connected project "${namespace}" requires connect.${namespace}.${field}.`,
+    });
+};
+
+const parseEnvName = (value: string, context: TEnvContext): TProteumEnvName => {
     if (value === 'local' || value === 'server') return value;
     throw createProteumEnvError({
-        appDir,
+        ...context,
         message: `Invalid ENV_NAME "${value}". Expected "local" or "server".`,
     });
 };
 
-const parseEnvProfile = (value: string, appDir: string): TProteumEnvProfile => {
+const parseEnvProfile = (value: string, context: TEnvContext): TProteumEnvProfile => {
     if (value === 'dev' || value === 'testing' || value === 'prod') return value;
     throw createProteumEnvError({
-        appDir,
+        ...context,
         message: `Invalid ENV_PROFILE "${value}". Expected "dev", "testing", or "prod".`,
     });
 };
 
 const parseTraceCapture = ({
     value,
-    appDir,
+    context,
 }: {
     value: string | undefined;
-    appDir: string;
+    context: TEnvContext;
 }): TProteumTraceCapture | undefined => {
     if (value === undefined || value === '') return undefined;
     if (value === 'summary' || value === 'resolve' || value === 'deep') return value;
 
     throw createProteumEnvError({
-        appDir,
+        ...context,
         message: `Invalid TRACE_CAPTURE "${value}". Expected "summary", "resolve", or "deep".`,
     });
 };
@@ -156,11 +210,11 @@ const parseTraceCapture = ({
 const parseAbsoluteUrl = ({
     key,
     value,
-    appDir,
+    context,
 }: {
     key: string;
     value: string;
-    appDir: string;
+    context: TEnvContext;
 }) => {
     let url: URL;
 
@@ -168,14 +222,14 @@ const parseAbsoluteUrl = ({
         url = new URL(value);
     } catch {
         throw createProteumEnvError({
-            appDir,
+            ...context,
             message: `Invalid absolute URL for ${key}: "${value}". Expected an absolute http:// or https:// URL.`,
         });
     }
 
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
         throw createProteumEnvError({
-            appDir,
+            ...context,
             message: `Invalid absolute URL for ${key}: "${value}". Expected an absolute http:// or https:// URL.`,
         });
     }
@@ -183,6 +237,29 @@ const parseAbsoluteUrl = ({
     return value;
 };
 
+const parseConnectedProjectAbsoluteUrl = ({
+    appDir,
+    namespace,
+    field,
+    value,
+}: {
+    appDir: string;
+    namespace: string;
+    field: 'urlInternal';
+    value: string;
+}) => {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error();
+        return value;
+    } catch {
+        throw createConnectedProjectConfigError({
+            appDir,
+            message: `Invalid connect.${namespace}.${field} "${value}". Expected an absolute http:// or https:// URL.`,
+        });
+    }
+};
+
 export const loadOptionalProteumDotenv = (appDir: string) => {
     for (const filename of dotenvFileNames) {
         const filepath = path.join(appDir, filename);
@@ -191,74 +268,123 @@ export const loadOptionalProteumDotenv = (appDir: string) => {
     }
 };
 
-export const getLoadedProteumEnvVariableKeys = () =>
-    Object.keys(process.env)
+export const getLoadedProteumEnvVariableKeys = (connectedProjects: TConnectedProjectsConfig = {}) => {
+    const requiredKeys = new Set(buildRequiredEnvVariableDefinitions(connectedProjects).map((definition) => definition.key));
+    const optionalKeys = new Set(buildOptionalEnvKeys(connectedProjects));
+
+    return Object.keys(process.env)
         .filter(
             (key) =>
-                requiredProteumEnvVariableKeys.includes(key as TProteumRequiredEnvVariableKey) ||
+                requiredKeys.has(key) ||
+                optionalKeys.has(key) ||
                 optionalProteumEnvVariablePrefixes.some((prefix) => key.startsWith(prefix)),
         )
-        .sort((a, b) => a.localeCompare(b));
+        .sort((left, right) => left.localeCompare(right));
+};
 
-export const inspectProteumEnv = (appDir: string): TProteumEnvInspection => {
+export const inspectProteumEnv = (
+    appDir: string,
+    rawConnectedProjects: TConnectedProjectsConfig = {},
+): TProteumEnvInspection => {
     loadOptionalProteumDotenv(appDir);
 
+    const connectedProjects = normalizeConnectedProjectsConfig(rawConnectedProjects);
+    const requiredVariables = buildRequiredEnvVariableDefinitions(connectedProjects);
+
     return {
-        loadedVariableKeys: getLoadedProteumEnvVariableKeys(),
-        requiredVariables: requiredProteumEnvVariableKeys.map((key) => ({
-            key,
-            possibleValues: [...requiredProteumEnvVariablePossibleValues[key]],
-            provided: isProvidedEnvValue(process.env[key]),
+        loadedVariableKeys: getLoadedProteumEnvVariableKeys(connectedProjects),
+        requiredVariables: requiredVariables.map((definition) => ({
+            key: definition.key,
+            possibleValues: [...definition.possibleValues],
+            provided: isProvidedEnvValue(process.env[definition.key]),
         })),
     };
 };
 
 export const parseProteumEnvConfig = ({
     appDir,
+    connectedProjects: rawConnectedProjects = {},
     routerPortOverride,
 }: {
     appDir: string;
+    connectedProjects?: TConnectedProjectsConfig;
     routerPortOverride?: number;
 }): TProteumEnvConfig => {
     loadOptionalProteumDotenv(appDir);
 
-    const name = parseEnvName(getRequiredEnvValue({ key: 'ENV_NAME', appDir }), appDir);
-    const profile = parseEnvProfile(getRequiredEnvValue({ key: 'ENV_PROFILE', appDir }), appDir);
+    const connectedProjects = normalizeConnectedProjectsConfig(rawConnectedProjects);
+    const context = { appDir, connectedProjects } satisfies TEnvContext;
+
+    const name = parseEnvName(getRequiredEnvValue({ key: 'ENV_NAME', context }), context);
+    const profile = parseEnvProfile(getRequiredEnvValue({ key: 'ENV_PROFILE', context }), context);
     const configuredRouterPort = parseIntegerEnvValue({
         key: 'PORT',
-        value: getRequiredEnvValue({ key: 'PORT', appDir }),
-        appDir,
+        value: getRequiredEnvValue({ key: 'PORT', context }),
+        context,
     });
     const currentDomain = parseAbsoluteUrl({
         key: 'URL',
-        value: getRequiredEnvValue({ key: 'URL', appDir }),
-        appDir,
+        value: getRequiredEnvValue({ key: 'URL', context }),
+        context,
+    });
+    const internalUrl = parseAbsoluteUrl({
+        key: 'URL_INTERNAL',
+        value: getRequiredEnvValue({ key: 'URL_INTERNAL', context }),
+        context,
     });
 
     const traceEnable = parseBooleanEnvValue({
         key: 'TRACE_ENABLE',
         value: process.env.TRACE_ENABLE,
-        appDir,
+        context,
     });
     const tracePersistOnError = parseBooleanEnvValue({
         key: 'TRACE_PERSIST_ON_ERROR',
         value: process.env.TRACE_PERSIST_ON_ERROR,
-        appDir,
+        context,
     });
     const traceRequestsLimit = process.env.TRACE_REQUESTS_LIMIT?.trim();
     const traceEventsLimit = process.env.TRACE_EVENTS_LIMIT?.trim();
     const traceCapture = parseTraceCapture({
         value: process.env.TRACE_CAPTURE?.trim(),
-        appDir,
+        context,
     });
 
+    const resolvedConnectedProjects = Object.fromEntries(
+        Object.entries(connectedProjects)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([namespace, config]) => {
+                const urlInternal = parseConnectedProjectAbsoluteUrl({
+                    appDir,
+                    namespace,
+                    field: 'urlInternal',
+                    value: getRequiredConnectedConfigValue({
+                        appDir,
+                        namespace,
+                        field: 'urlInternal',
+                        value: config.urlInternal,
+                    }),
+                });
+
+                return [
+                    namespace,
+                    {
+                        namespace,
+                        urlInternal,
+                    } satisfies TProteumConnectedProjectEnvConfig,
+                ];
+            }),
+    );
+
     return {
         name,
         profile,
         router: {
             port: routerPortOverride === undefined ? configuredRouterPort : routerPortOverride,
             currentDomain,
+            internalUrl,
         },
+        connectedProjects: resolvedConnectedProjects,
         trace: {
             enable: traceEnable ?? profile === 'dev',
             requestsLimit:
@@ -267,7 +393,7 @@ export const parseProteumEnvConfig = ({
                     : parseIntegerEnvValue({
                           key: 'TRACE_REQUESTS_LIMIT',
                           value: traceRequestsLimit,
-                          appDir,
+                          context,
                       }),
             eventsLimit:
                 traceEventsLimit === undefined || traceEventsLimit === ''
@@ -275,7 +401,7 @@ export const parseProteumEnvConfig = ({
                     : parseIntegerEnvValue({
                           key: 'TRACE_EVENTS_LIMIT',
                           value: traceEventsLimit,
-                          appDir,
+                          context,
                       }),
             capture: traceCapture ?? 'resolve',
             persistOnError: tracePersistOnError ?? profile === 'dev',

package/common/router/index.ts

@@ -75,6 +75,7 @@ export type TRouteOptions = {
     // Injected by the page plugin
     id?: string;
     filepath?: string;
+    sourceLocation?: { line: number; column: number };
     setup?: TPageSetup;
 
     // Indexing

package/common/router/request/api.ts

@@ -2,6 +2,7 @@
 - DEPENDANCES
 ----------------------------------*/
 
+import type { TConnectedFetcherTarget } from '@common/connectedProjects';
 import type { HttpMethod } from '@server/services/router';
 
 /*----------------------------------
@@ -37,6 +38,7 @@ export type TApiFetchOptions = {
     onProgress?: (percent: number) => void;
     // Default: json
     encoding?: 'json' | 'multipart';
+    connected?: TConnectedFetcherTarget;
 };
 
 export type TPostData = TPostDataWithFile;

package/config.ts

@@ -0,0 +1,5 @@
+export { Application } from './common/applicationConfig';
+export type {
+    TApplicationIdentityConfig as ApplicationIdentityConfig,
+    TApplicationSetupConfig as ApplicationSetupConfig,
+} from './common/applicationConfig';

package/docs/dev-commands.md

@@ -67,13 +67,17 @@ In `proteum dev`, the bottom profiler exposes a `Commands` tab.
 - 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
+- it now adds scope, execution-duration, and status charts over the same command definitions and latest execution snapshots
 
 The profiler also exposes the shared diagnostics surfaces for humans:
 
 - `Explain` renders the same manifest-backed data as `proteum explain`
 - `Doctor` renders the same manifest diagnostics as `proteum doctor`
+- `Diagnose` renders the same owner, suspect, contract, trace-summary, and buffered-log view as `proteum diagnose`
+- `Perf` renders the same hot-path, request-waterfall, compare, and memory views as `proteum perf`
+- the other profiler tabs now add focused visual charts over the same trace, manifest, and dev-runtime contracts instead of only row lists
 
-For the shared diagnostics contract and the corresponding dev HTTP endpoints, see [diagnostics.md](diagnostics.md).
+For the shared diagnostics contract, trace-derived perf contract, and the corresponding dev HTTP endpoints, see [diagnostics.md](diagnostics.md) and [request-tracing.md](request-tracing.md).
 
 ### HTTP Endpoints