proteum 2.2.0 → 2.2.2-1

package/cli/compiler/common/index.ts

@@ -45,6 +45,15 @@ export default function createCommonConfig(
 ): Configuration {
     const dev = mode === 'dev';
     const enableFilesystemCache = dev ? cli.args.cache !== false : cli.args.cache === true;
+    const transpileModuleDirectories = app.transpileModuleDirectories;
+    const transpileModuleSnapshot =
+        dev && transpileModuleDirectories.length > 0
+            ? {
+                  // Transpiled local packages can resolve through node_modules symlinks,
+                  // but they still need live invalidation like mutable app sources in dev.
+                  unmanagedPaths: transpileModuleDirectories,
+              }
+            : undefined;
     const frameworkPackageRoots = [cli.paths.framework.installedRoot, cli.paths.framework.activeRoot].filter(
         (rootPath, index, list): rootPath is string => typeof rootPath === 'string' && list.indexOf(rootPath) === index,
     );
@@ -109,6 +118,8 @@ export default function createCommonConfig(
             ]*/
         },
 
+        ...(transpileModuleSnapshot ? { snapshot: transpileModuleSnapshot } : {}),
+
         // Turn off performance processing because we utilize
         // our own hints via the FileSizeReporter
         performance: false,
@@ -123,6 +134,11 @@ export default function createCommonConfig(
                   cacheDirectory: path.join(app.paths.cache, 'rspack', side, mode),
                   compression: false,
                   buildDependencies: { config: [__filename] },
+                  ...(transpileModuleSnapshot
+                      ? {
+                            snapshot: transpileModuleSnapshot,
+                        }
+                      : {}),
               }
             : false,
 

package/cli/presentation/commands.ts

@@ -190,6 +190,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'Use `--cwd` when the target Proteum app lives in another worktree or checkout and you do not want to `cd` first.',
             'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
+            'Before the interactive dev loop starts, Proteum offers to launch `proteum configure agents` when the app root is missing `AGENTS.md`.',
             'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
             '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
             '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',

package/cli/presentation/help.ts

@@ -139,6 +139,10 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
+                wrapText('When the app root is missing `AGENTS.md`, the interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.', {
+                    indent: '  ',
+                    nextIndent: '  ',
+                }),
                 wrapText('Legacy single-dash flags and positional booleans remain accepted for older app scripts, but new docs should prefer modern long flags.', {
                     indent: '  ',
                     nextIndent: '  ',

package/cli/utils/agents.ts

@@ -42,6 +42,11 @@ export type TConfigureProjectAgentSymlinksResult = {
     updatedGitignores: string[];
 };
 
+export type TProjectAgentFileInspection = {
+    existing: string[];
+    missing: string[];
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -147,6 +152,37 @@ export function renderProjectInstructionGitignoreBlock({ coreRoot }: TProjectIns
     return renderInstructionGitignoreBlock({ linkDefinitions: getAppAgentLinkDefinitions({ coreRoot, mode: 'standalone' }) });
 }
 
+export function inspectProjectAgentFiles({ appRoot }: { appRoot: string }): TProjectAgentFileInspection {
+    const normalizedAppRoot = path.resolve(appRoot);
+    const expectedAgentPaths = Array.from(
+        new Set(
+            standaloneAppAgentLinkDefinitions
+                .map((linkDefinition) => linkDefinition.projectPath)
+                .filter((projectPath) => projectPath.endsWith('AGENTS.md')),
+        ),
+    );
+    const result: TProjectAgentFileInspection = {
+        existing: [],
+        missing: [],
+    };
+
+    for (const projectPath of expectedAgentPaths) {
+        const absolutePath = path.join(normalizedAppRoot, projectPath);
+        const parentPath = path.dirname(absolutePath);
+
+        if (projectPath !== 'AGENTS.md' && !fs.existsSync(parentPath)) continue;
+
+        if (fs.existsSync(absolutePath)) {
+            result.existing.push(projectPath);
+            continue;
+        }
+
+        result.missing.push(projectPath);
+    }
+
+    return result;
+}
+
 /*----------------------------------
 - HELPERS
 ----------------------------------*/

package/common/dev/requestTrace.ts

@@ -114,6 +114,7 @@ export type TTraceSqlQuery = {
     model?: string;
     operation: string;
     fingerprint?: string;
+    normalizedQuery?: string;
     ownerLabel?: string;
     ownerFilepath?: string;
     serviceLabel?: string;
@@ -169,6 +170,71 @@ export type TRequestTrace = {
     events: TTraceEvent[];
 };
 
+export type TRequestProfilingApiCall = {
+    id: string;
+    origin: TTraceCallOrigin;
+    label: string;
+    method: string;
+    path: string;
+    fetcherId?: string;
+    connectedProjectNamespace?: string;
+    connectedControllerAccessor?: string;
+    ownerLabel?: string;
+    ownerFilepath?: string;
+    serviceLabel?: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    errorMessage?: string;
+    requestBodyJson?: unknown;
+    responseBodyJson?: unknown;
+};
+
+export type TRequestProfilingSqlQuery = {
+    id: string;
+    callerCallId?: string;
+    callerFetcherId?: string;
+    callerLabel?: string;
+    callerMethod: string;
+    callerOrigin: TTraceSqlQueryCallerOrigin;
+    callerPath: string;
+    durationMs: number;
+    finishedAt: string;
+    kind: TTraceSqlQueryKind;
+    model?: string;
+    operation: string;
+    fingerprint?: string;
+    normalizedQuery?: string;
+    ownerLabel?: string;
+    ownerFilepath?: string;
+    serviceLabel?: string;
+    connectedNamespace?: string;
+    paramsJson?: unknown;
+    paramsText?: string;
+    query: string;
+    startedAt: string;
+    target?: string;
+};
+
+export type TRequestProfiling = {
+    enabled: boolean;
+    requestId: string;
+    method: string;
+    path: string;
+    url: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    user?: string;
+    errorMessage?: string;
+    profilerOrigin?: string;
+    profilerParentRequestId?: string;
+    apiCalls: TRequestProfilingApiCall[];
+    sqlQueries: TRequestProfilingSqlQuery[];
+};
+
 export type TRequestTraceListItem = Omit<TRequestTrace, 'events' | 'calls' | 'sqlQueries'> & {
     eventCount: number;
     callCount: number;

package/common/env/proteumEnv.ts

@@ -36,6 +36,7 @@ export type TProteumEnvConfig = {
     connectedProjects: Record<string, TProteumConnectedProjectEnvConfig>;
     trace: {
         enable: boolean;
+        profilerEnable: boolean;
         requestsLimit: number;
         eventsLimit: number;
         capture: TProteumTraceCapture;
@@ -65,7 +66,7 @@ const isProvidedEnvValue = (value: string | undefined) => typeof value === 'stri
 
 const buildRequiredEnvVariableDefinitions = (_connectedProjects: TConnectedProjectsConfig) => [...baseRequiredProteumEnvVariableDefinitions];
 
-const buildOptionalEnvKeys = (_connectedProjects: TConnectedProjectsConfig) => [] as string[];
+const buildOptionalEnvKeys = (_connectedProjects: TConnectedProjectsConfig) => ['ENABLE_PROFILER'] as string[];
 
 const formatRequiredEnvVariableStatus = (variable: TProteumRequiredEnvVariable) =>
     `- ${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`;
@@ -269,8 +270,8 @@ export const loadOptionalProteumDotenv = (appDir: string) => {
 };
 
 export const getLoadedProteumEnvVariableKeys = (connectedProjects: TConnectedProjectsConfig = {}) => {
-    const requiredKeys = new Set(buildRequiredEnvVariableDefinitions(connectedProjects).map((definition) => definition.key));
-    const optionalKeys = new Set(buildOptionalEnvKeys(connectedProjects));
+    const requiredKeys = new Set<string>(buildRequiredEnvVariableDefinitions(connectedProjects).map((definition) => definition.key));
+    const optionalKeys = new Set<string>(buildOptionalEnvKeys(connectedProjects));
 
     return Object.keys(process.env)
         .filter(
@@ -338,6 +339,11 @@ export const parseProteumEnvConfig = ({
         value: process.env.TRACE_ENABLE,
         context,
     });
+    const profilerEnable = parseBooleanEnvValue({
+        key: 'ENABLE_PROFILER',
+        value: process.env.ENABLE_PROFILER,
+        context,
+    });
     const tracePersistOnError = parseBooleanEnvValue({
         key: 'TRACE_PERSIST_ON_ERROR',
         value: process.env.TRACE_PERSIST_ON_ERROR,
@@ -387,6 +393,7 @@ export const parseProteumEnvConfig = ({
         connectedProjects: resolvedConnectedProjects,
         trace: {
             enable: traceEnable ?? profile === 'dev',
+            profilerEnable: profilerEnable ?? false,
             requestsLimit:
                 traceRequestsLimit === undefined || traceRequestsLimit === ''
                     ? 200

package/docs/request-tracing.md

@@ -1,13 +1,18 @@
 # Request Tracing
 
-Proteum ships with a dev-only in-memory request trace buffer so routing, controller execution, SSR, API, Prisma SQL, render behavior, and request-time performance can be inspected without attaching a debugger or scattering temporary logs through the runtime.
+Proteum ships with one request-instrumentation system with two runtime shapes:
+
+- retained dev traces for `proteum trace`, `proteum perf`, the dev-only HTTP endpoints, and the bottom profiler
+- reduced request-local profiling for `request.profiling` and the router `request.finished` hook
+
+The same API and SQL instrumentation feeds both shapes. Dev trace keeps the in-memory buffer and event timeline. Reduced profiling keeps only the finalized request/API/SQL snapshot and releases it after the `request.finished` hook runs.
 
 ## Scope
 
-- tracing is available only when the app runs with `profile: dev`
+- retained dev tracing is available only when the app runs with `profile: dev`
 - traces are exposed through `proteum trace`, `proteum perf`, and the dev-only `__proteum/trace` and `__proteum/perf` HTTP endpoints
 - `proteum diagnose` is a separate composite surface that reads the same framework diagnostics plus one matching request trace and buffered server logs; see [diagnostics.md](diagnostics.md)
-- production requests are not traced by this feature
+- `ENABLE_PROFILER=true` enables reduced request-local profiling in any environment, including production
 
 ## Main Commands
 
@@ -77,6 +82,13 @@ Depending on capture mode, traces can include:
 - normalized request errors
 - additive owner, service, cache, and connected-boundary metadata propagated from route/controller resolution into downstream calls and SQL
 
+Reduced request-local profiling keeps the finalized request summary plus API and SQL rows only:
+
+- `request.profiling` exists before the router `request` hook runs
+- `request.profiling.apiCalls` and `request.profiling.sqlQueries` start empty and are populated during request handling
+- the router `request.finished` hook receives that same object after status, duration, API calls, and SQL queries are finalized
+- when only reduced profiling is enabled, finished requests are released immediately after `request.finished` instead of being retained in the global trace buffer
+
 ## SQL Tracing
 
 Prisma query tracing covers both ORM operations and raw queries.
@@ -140,6 +152,7 @@ export TRACE_REQUESTS_LIMIT=200
 export TRACE_EVENTS_LIMIT=800
 export TRACE_CAPTURE=resolve
 export TRACE_PERSIST_ON_ERROR=true
+export ENABLE_PROFILER=true
 ```
 
 Notes:
@@ -150,6 +163,7 @@ Notes:
 - `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
+- `ENABLE_PROFILER` reuses the same request instrumentation path but skips the retained global buffer and event timeline when dev trace is otherwise off
 
 ## Memory Model
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.2.0",
+	"version": "2.2.2-1",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",