proteum 2.1.0 → 2.1.1

package/AGENTS.md

@@ -1,113 +1,59 @@
-# Proteum Framework
+# Proteum Core
 
-## Vision
+This file governs work in the Proteum framework repository itself. For downstream app rules, use `agents/framework/AGENTS.md`.
 
-Proteum aims to become the first SSR / SEO / TypeScript framework built primarily for non-human developers and AI agents.
+## Priorities
 
-The framework should maximize LLM efficiency, correctness, determinism, and performance when building Proteum-based projects.
-
-When tradeoffs exist, prioritize framework decisions in this order:
+When tradeoffs exist, optimize in this order:
 
 1. Reduce shipped client bundle size and unnecessary runtime code.
-2. Increase build-time, server-time, and browser-time performance.
-3. Improve SEO output and LLM-friendly, crawlable, semantic HTML.
+2. Improve build-time, server-time, and browser-time performance.
+3. Improve SEO output and crawlable, semantic HTML.
 4. Preserve explicit, typed, machine-readable contracts for agents.
 
-When working on Proteum itself, optimize for agent ergonomics first:
+## Core Rules
 
-- Prefer explicit, typed, machine-readable contracts over implicit runtime magic, hidden conventions, ambient globals, or tribal knowledge.
-- Enforce strong, consistent TypeScript typings across the whole project. Do not introduce `any` or `unknown`.
-- Make routes, data loading, server actions / controllers, services, SEO metadata, sitemap generation, static generation, and environment contracts easy to discover, inspect, and explain.
-- Treat SSR and SEO as first-class framework primitives, not app-level patchwork.
-- Prefer server-first designs that avoid shipping client JavaScript unless it is required for user-facing behavior.
-- Favor small, single-purpose files and modules that reduce context load and make edits easier for agents to scope safely.
-- Generated code should improve traceability and type safety, not obscure behavior. It should be deterministic, auditable, and easy for agents to map back to source files.
-- Prefer inference from the explicit application class in `server/index.ts` whenever possible. Treat `server/index.ts` as the canonical type root for application services, router services, router context, and models instead of duplicating manual type declarations.
-- Prefer exact end-to-end contracts for inputs, outputs, errors, side effects, and caching behavior.
-- Prefer framework features that make impact analysis, verification, and debugging easier for agents.
-- Prefer output that is fast to render, easy to crawl, semantically rich, and easy for LLMs to parse reliably.
-- Avoid introducing abstractions that require broad codebase memory to use correctly.
+- Prefer explicit typed contracts over runtime magic or hidden conventions.
+- Keep `server/index.ts` as the canonical type root for services, router context, request context, and models.
+- Keep generated code deterministic, auditable, and easy to map back to source.
+- Prefer typed traces and manifest-backed diagnostics over ad hoc logging.
+- Check existing repo dependencies and npm before inventing a new helper, runtime, plugin, or abstraction.
+- Prefer established, flexible, well-typed packages; build custom only when packages fail on bundle size, performance, SSR behavior, typing, flexibility, or maintenance risk.
+- Delete obsolete compatibility layers, helper indirection, and unused packages when safe.
 
-When proposing or implementing a core change, evaluate it against this question:
+## Workflow
 
-- Does this make Proteum easier for an AI agent to understand, modify, verify, and operate with high confidence?
+- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+- End your work with `Commit message`: one short top-level sentence, max 90 characters.
 
-# Workflow
+## Core Changes
 
-- Everytime I input error messages without any instructions, don't implement fixes.
-Instead, ivestigate the potential causes of the errors, and for each: 
-  1. Evaluate / quantify the probabiliies 
-  2. Give why and 
-  3. Suggest how to fix it
-- When you have finished your work, summarize in one top-level short sentence ALL the changes you made since the beginning of the WHOLE conversation. Output as "Commit message". Max 90 characters.
+- Validate framework changes against both reference apps:
+  - `/Users/gaetan/Desktop/Projets/crosspath/platform`
+  - `/Users/gaetan/Desktop/Projets/unique.domains/website`
+- Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
+- Keep core changes aligned with the explicit controller/page architecture in `agents/framework/AGENTS.md`.
+- Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
+- Challenge any webpack plugin, Babel plugin, alias, helper, runtime service, or npm package that is not meaningfully used by both apps.
+- Remove dead docs, flags, helper files, and compatibility branches in the same pass when safe.
 
-## Framework Workflow
+## Proposals
 
-When changing Proteum itself, always ground the work in the real apps that use it.
+- Start from the concrete mismatch or risk visible in the reference apps.
+- Name the npm packages or package categories evaluated first when adding capability or infrastructure.
+- Show the target API with real Proteum-style client and server usage.
+- Separate the ideal end state from any migration rule.
+- Name the source files that drive generated artifacts when generation changes.
+- Explicitly name removed behavior and why it is obsolete.
 
-- Treat these two projects as the reference surface for current Proteum usage and needs:
-  - `/Users/gaetan/Desktop/Projets/crosspath/platform`
-  - `/Users/gaetan/Desktop/Projets/unique.domains/website`
-- Before proposing a framework change, inspect how both apps currently use the feature, runtime, API, compiler behavior, or generated files involved.
-- Prefer removing framework magic when the same result can be expressed with explicit runtime contracts, generated code, or typed context.
-- If a webpack plugin, Babel plugin, alias, helper, runtime service, or npm package is not meaningfully used by both reference apps, challenge its existence and prefer deleting it.
-
-## Current Proteum Direction
-
-Future changes should preserve and extend the current explicit model instead of reintroducing runtime magic.
-
-- Strong typings are mandatory across the whole project. Do not use `any` or `unknown`; keep types explicit, precise, and consistent.
-- Prefer deriving types from the explicit application class in `server/index.ts` instead of recreating them manually in feature code, helpers, or generated output.
-- Server route entrypoints live in `server/controllers/**/*.ts` files.
-- Controllers extend `Controller` and read request-scoped values from `this.request`.
-- Controllers validate request input via `this.input(schema)` inside the method body. Do not use decorators for validation metadata.
-- `server/config/*.ts` should export plain typed config constants with `Services.config(ServiceClass, { ... })`, for example `export const missionsConfig = Services.config(Missions, { ... })`.
-- `server/index.ts` should default-export the app `Application` subclass and instantiate root services as public fields via `new ServiceClass(this, config, this)`.
-- Normal services extend `Service` and should use `this.services`, `this.models`, and `this.app` instead of implicit globals or magic imports.
-- App services should be inferred from the explicit `server/index.ts` application graph and the config passed into each constructor, not hand-maintained parallel interfaces.
-- Router services and router/request context values such as `user`, `auth`, and similar request-scoped contracts should come from inferred request and app types, not ad hoc casts.
-- Models should be inferred from the app/model registry rooted at `server/index.ts` and exposed through generated app types, not from duplicated hand-written model maps.
-- Controllers should own auth, input parsing, and request concerns, then pass explicit typed values into services.
-- Do not reintroduce runtime server imports or globals such as `@request`, `@models`, or `@app`.
-- Client pages use `Router.page(path, render)` or `Router.page(path, setup, render)`.
-- SSR data loading belongs in the `setup` function returned object, not in `api.fetch(...)`.
-- Client-side controller access should come from the generated controller tree and client context, not from fake runtime imports.
-- When referencing an app service, a router service, or a model, expose it in the current block scope first by destructuring from `this.request`, `this.app`, or `this.app.Models.client`, then call methods on that local binding. The service, router value, or model should be the first element of the callee chain.
-
-## Solution Proposals
-
-When presenting a framework solution, make it easy to judge against the real apps.
-
-- Start from the actual mismatch or risk seen in the apps, not from abstract framework theory.
-- Show the target API with concrete client and server usage examples that match current Proteum conventions.
-- Distinguish:
-  - the ideal end-state API
-  - any transitional migration rule or guardrail
-- Call out what becomes impossible or safer after the change.
-- If the change affects generated code, explain what source files drive generation and what artifacts are produced.
-- If the change removes older behavior, explicitly name what is being deleted and why it is obsolete.
-
-## Implementation Rules
-
-- Keep framework changes aligned with the explicit controller/page architecture already adopted in the reference apps.
-- Prefer deleting client-side code, dependencies, and emitted assets when the same capability can stay on the server or be generated statically.
-- Prefer deleting obsolete branches, compatibility layers, plugins, and dependencies over keeping dead paths around.
-- Prefer compiler logic that is deterministic, auditable, and easy for another agent to trace from source to generated output.
-- Prefer local destructuring that exposes typed app services, router services, router context values, and models in the current block scope before use, instead of chaining through `this.request`, `this.app`, or `this.app.Models.client` at each call site.
-- Reject changes that increase bundle size, runtime cost, or crawlability risk unless the benefit is concrete and validated in both reference apps.
-- When removing old behavior, also remove the related packages, config flags, typings, docs, and dead helper files in the same pass when safe.
-- If a core change breaks one of the reference apps, keep iterating until the framework and the affected app usage are both corrected.
-
-## Real-World Validation
-
-Do not stop at static analysis or isolated core compilation when the change affects runtime behavior.
-
-- Validate framework changes against the two reference apps whenever the change touches routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
-- Preferred runtime validation:
-  - run `npx proteum dev --no-cache -port 3xxx` in both apps on explicit ports
-  - open the real pages with Playwright
-  - inspect browser console errors and warnings
-  - inspect server startup and runtime errors
-- Build-only checks are not sufficient for runtime/compiler changes. Use them as supplements, not as the final proof.
-- Keep fixing regressions exposed by the dev-server and browser pass until both apps boot and the browser console shows no new real errors.
-- Treat external/local-environment warnings separately from framework regressions, and say clearly when something is unrelated to the current change.
+## Runtime Validation
+
+Do not stop at static analysis for routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
+
+- Run `npx proteum dev --no-cache --port 3xxx` in both reference apps on explicit ports.
+- For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
+- Open the real pages with Playwright.
+- Inspect browser console errors and warnings.
+- Inspect server startup and runtime errors.
+
+Build-only checks are supplementary. Iterate until both apps boot and show no new framework regressions, and call unrelated environment warnings out separately.

package/README.md

@@ -28,7 +28,7 @@ Proteum combines:
 - **Explicit request entrypoints.** Controllers are classes. Request access is explicit through `this.request`.
 - **Local validation.** Validate handler input inside the handler with `this.input(schema)`.
 - **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
-- **Explainability matters.** `proteum explain` and `proteum doctor` expose the framework view of your app.
+- **Explainability matters.** `proteum explain`, `proteum doctor`, and `proteum trace` expose the framework view of your app and its live requests.
 - **SEO is not an afterthought.** Identity, routes, layouts, and SSR data are part of the app contract.
 
 ## What a Proteum App Looks Like
@@ -36,8 +36,9 @@ Proteum combines:
 ```text
 my-app/
   identity.yaml
-  env.yaml
+  .env               # optional file for required local env vars
   package.json
+  commands/
   client/
     pages/
       _layout/
@@ -63,14 +64,34 @@ my-app/
 Important files:
 
 - `identity.yaml`: app identity, naming, locale, and SEO-facing metadata defaults
-- `env.yaml`: environment contract loaded by the app
+- `process.env` / optional `.env`: `PORT`, `ENV_*`, `URL`, and `TRACE_*` environment variables loaded by the app
 - `server/config/*.ts`: plain typed config exports consumed by the explicit app bootstrap
 - `server/index.ts`: default-exported `Application` subclass that instantiates root services and router plugins
 - `client/pages/**`: SSR page entrypoints registered through `Router.page(...)`
 - `server/controllers/**`: request handlers that extend `Controller`
+- `commands/**`: dev-only internal commands that extend `Commands`
 - `server/services/**`: business logic that extends `Service`
 - `.proteum/**`: framework-owned generated contracts and manifests
 
+Required Proteum env vars:
+
+- `ENV_NAME`: `local` or `server`
+- `ENV_PROFILE`: `dev`, `testing`, or `prod`
+- `PORT`: default router port
+- `URL`: canonical absolute base URL for `Router.url(..., true)`
+
+Proteum does not provide defaults for required env vars. They must be defined explicitly in `process.env` or `.env`.
+
+Use `proteum explain env` to see the required env vars, their allowed values, and whether each one is currently provided.
+
+Optional trace env vars:
+
+- `TRACE_ENABLE`
+- `TRACE_REQUESTS_LIMIT`
+- `TRACE_EVENTS_LIMIT`
+- `TRACE_CAPTURE`
+- `TRACE_PERSIST_ON_ERROR`
+
 ## Example: Server Bootstrap
 
 Proteum app services are declared explicitly through typed config exports plus a concrete `Application` subclass.
@@ -87,7 +108,7 @@ type RouterBaseConfig = Omit<ServiceConfig<typeof Router>, 'plugins'>;
 export const usersConfig = Services.config(Users, {});
 
 export const routerBaseConfig = {
-  domains: AppContainer.Environment.router.domains,
+  currentDomain: AppContainer.Environment.router.currentDomain,
   http: {
     domain: 'example.com',
     port: AppContainer.Environment.router.port,
@@ -181,6 +202,35 @@ Controller rules:
 - call business logic through `this.services`, `this.models`, or `this.app`
 - return explicit values instead of relying on ambient globals
 
+## Example: Command
+
+Proteum commands are explicit dev-only internal entrypoints.
+
+```ts
+import { Commands } from '@server/app/commands';
+
+export default class DiagnosticsCommands extends Commands {
+  public async ping() {
+    const { Stats } = this.services;
+
+    return {
+      app: this.app.identity.identifier,
+      domains: await Stats.general(),
+    };
+  }
+}
+```
+
+Command rules:
+
+- files live under `commands/**/*.ts`
+- each file default-exports a class extending `Commands` from `@server/app/commands`
+- methods with bodies become generated dev commands
+- command path comes from the file path plus the method name
+- `export const commandPath = 'Custom/path'` can override the base path when needed
+- `commands/tsconfig.json` and `.proteum/server/commands.d.ts` give `/commands` its own dev-only alias and app typing surface
+- commands run only in dev contexts: `proteum command ...`, the dev profiler, or dev-only `__proteum/commands` endpoints
+
 ## Example: Service
 
 Proteum services keep business logic out of request handlers.
@@ -215,6 +265,7 @@ Typical generated artifacts:
 - `.proteum/client/controllers.ts`
 - `.proteum/client/layouts.ts`
 - `.proteum/common/controllers.ts`
+- `.proteum/server/commands.ts`
 - `.proteum/server/routes.ts`
 - `.proteum/server/controllers.ts`
 
@@ -236,6 +287,8 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum build --prod` | Produce the production server and client bundles into `bin/` |
 | `proteum doctor` | Inspect manifest diagnostics |
 | `proteum explain` | Explain routes, controllers, services, layouts, conventions, and env |
+| `proteum trace` | Inspect live dev-only request traces from the running SSR server |
+| `proteum command` | Run a dev-only internal command locally or against a running dev server |
 | `proteum init` | Experimental project scaffolding when scaffold assets are installed |
 
 Recommended daily workflow:
@@ -253,10 +306,68 @@ Useful inspection commands:
 proteum doctor
 proteum doctor --json
 proteum explain
-proteum explain --routes --controllers
+proteum explain --routes --controllers --commands
 proteum explain --all --json
+proteum command proteum/diagnostics/ping
+proteum command proteum/diagnostics/ping --port 3101
+proteum trace requests
+proteum trace arm --capture deep
+proteum trace latest
 ```
 
+## Dev Commands
+
+Proteum includes a dev-only command surface for internal testing, debugging, and one-off execution that should not become a normal controller or route.
+
+- commands live under `./commands/**/*.ts`
+- each file default-exports a class extending `Commands` from `@server/app/commands`
+- each method is addressed by `file/path/methodName`
+- Proteum creates `commands/tsconfig.json` when the folder exists so command files inherit the server alias/type project
+- `proteum command foo/bar` refreshes generated artifacts, builds the dev output, starts a temporary local dev server, runs the command, prints the result, and exits
+- `proteum command foo/bar --port 3101` runs the same command against an existing `proteum dev` instance
+- the dev profiler exposes the same command list and run action through the `Commands` tab
+
+Proteum itself also ships a small built-in diagnostic command at `proteum/diagnostics/ping`, so the command surface is never empty in dev.
+
+## Request Tracing
+
+Proteum includes a dev-only in-memory request trace buffer for routing, controller, context, SSR, and render debugging.
+
+When diagnosing or testing against an app, first read the default port from `PORT` or `./.proteum/manifest.json` and check whether a server is already running there. If it is, inspect the existing traces before reproducing the issue so you can collect past errors and their context.
+
+- `proteum trace requests`: list the most recent request summaries
+- `proteum trace latest`: show the latest captured request
+- `proteum trace show <requestId>`: inspect one trace in detail
+- `proteum trace arm --capture deep`: force the next request into deep capture mode
+- `proteum trace export <requestId>`: write one trace to disk
+- `proteum trace latest --url http://127.0.0.1:3010`: target a non-standard dev base URL directly
+
+Default behavior:
+
+- tracing is enabled only in `profile: dev`
+- traces live in memory and are bounded by `TRACE_REQUESTS_LIMIT` and `TRACE_EVENTS_LIMIT`
+- payloads are summarized, long strings are truncated, and sensitive fields such as cookies, passwords, and tokens are redacted
+- `TRACE_PERSIST_ON_ERROR` can export crashing requests under `var/traces/`
+- `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
+
+Trace env example:
+
+```bash
+export TRACE_ENABLE=true
+export TRACE_REQUESTS_LIMIT=200
+export TRACE_EVENTS_LIMIT=800
+export TRACE_CAPTURE=resolve
+export TRACE_PERSIST_ON_ERROR=true
+```
+
+Capture modes:
+
+- `summary`: request lifecycle plus high-signal events
+- `resolve`: adds route resolution and controller/context steps
+- `deep`: adds route skip reasons and deeper payload summaries for one request investigation
+
+The trace CLI talks to the running dev server over the dev-only `__proteum/trace` HTTP endpoints. Use `--port` for a different local port or `--url` when the host itself is non-standard. For the full guide, see [docs/request-tracing.md](docs/request-tracing.md).
+
 ## LLM-Friendly By Design
 
 Proteum is built so an agent can answer these questions quickly and reliably:
@@ -271,22 +382,25 @@ Proteum is built so an agent can answer these questions quickly and reliably:
 Proteum answers those questions with explicit artifacts:
 
 - `identity.yaml` for app identity
-- `env.yaml` for the environment surface
+- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env vars for the environment surface
 - `server/index.ts` for the explicit root service graph
 - `.proteum/manifest.json` for machine-readable app structure
 - `proteum explain --json` for structured framework introspection
 - `proteum doctor --json` for structured diagnostics
+- `proteum command ...` plus the profiler `Commands` tab for dev-only internal execution
 
 If you are an LLM or automation agent, start here:
 
 1. Read `identity.yaml`.
-2. Read `env.yaml`.
+2. Read `PORT`, the relevant `ENV_*`, `URL`, and `TRACE_*` env vars, or run `proteum explain env`.
 3. Inspect `server/index.ts` and `server/config/*.ts` for the explicit app bootstrap.
 4. Read `.proteum/manifest.json` or run `proteum explain --json`.
 5. Inspect `server/controllers/**` for request entrypoints.
 6. Inspect `server/services/**` for business logic.
 7. Inspect `client/pages/**` for SSR routes and page setup contracts.
 
+For implementation rules in a real Proteum app, treat the local `AGENTS.md` files plus `proteum explain`, `proteum doctor`, and `proteum trace` as the task contract. This README is the framework overview, not the project-local instruction layer.
+
 ## What Proteum Avoids
 
 Proteum intentionally avoids several patterns that make frameworks harder to inspect and harder to trust: