proteum 2.1.0-2 → 2.1.0-4

package/AGENTS.md

@@ -1,11 +1,13 @@
-# Proteum Framework
+# Proteum Core
+
+This file governs work in the Proteum framework repository itself.
+
+For the canonical Proteum app contract used by downstream projects, use `agents/framework/AGENTS.md`.
 
 ## Vision
 
 Proteum aims to become the first SSR / SEO / TypeScript framework built primarily for non-human developers and AI agents.
 
-The framework should maximize LLM efficiency, correctness, determinism, and performance when building Proteum-based projects.
-
 When tradeoffs exist, prioritize framework decisions in this order:
 
 1. Reduce shipped client bundle size and unnecessary runtime code.
@@ -13,101 +15,57 @@ When tradeoffs exist, prioritize framework decisions in this order:
 3. Improve SEO output and LLM-friendly, crawlable, semantic HTML.
 4. Preserve explicit, typed, machine-readable contracts for agents.
 
-When working on Proteum itself, optimize for agent ergonomics first:
-
-- 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.
+When working on Proteum itself:
 
-When proposing or implementing a core change, evaluate it against this question:
+- prefer explicit, typed, machine-readable contracts over runtime magic or hidden conventions
+- keep `server/index.ts` as the canonical type root for app services, router services, request context, and models
+- keep generated code deterministic, auditable, and easy to map back to source files
+- prefer typed request traces and manifest-backed diagnostics over ad hoc runtime logging
+- prefer deleting obsolete compatibility layers, helper indirection, and unused packages over preserving dead paths
 
-- Does this make Proteum easier for an AI agent to understand, modify, verify, and operate with high confidence?
+## Workflow
 
-# Workflow
+- Every time I input error messages without any instructions, do not implement fixes. Instead, investigate the potential causes and, for each one:
+  1. evaluate or quantify the probability
+  2. explain why
+  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 conversation. Output as `Commit message`. Max 90 characters.
 
-- 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.
+## Framework Change Rules
 
-## Framework Workflow
+When changing Proteum itself:
 
-When changing Proteum itself, always ground the work in the real apps that use it.
-
-- Treat these two projects as the reference surface for current Proteum usage and needs:
+- validate the change against these two reference apps:
   - `/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.
+- inspect how both apps currently use the feature, runtime, API, compiler behavior, or generated files before proposing or implementing a core change
+- 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 apps, challenge its existence
+- keep core changes aligned with the explicit controller/page architecture described in `agents/framework/AGENTS.md`
+- remove related dead docs, config flags, helper files, and compatibility branches in the same pass when safe
+
+## Proposal Rules
+
+When proposing a core change:
+
+- start from the concrete mismatch or risk seen in the reference apps
+- show the target API with real client and server usage examples that match current Proteum conventions
+- distinguish the ideal end-state API from any transitional migration rule
+- explain which source files drive generated artifacts when generation changes
+- explicitly name removed behavior and why it is obsolete
+
+## Validation
+
+Do not stop at static analysis when the change affects runtime behavior.
+
+If a change touches 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
+- use `proteum trace arm --capture deep`, reproduce the request once, then inspect `proteum trace latest` or `proteum trace show <requestId>` when the issue is request-time behavior
+- open the real pages with Playwright
+- inspect browser console errors and warnings
+- inspect server startup and runtime errors
+
+Build-only checks are supplements, not final proof.
+
+Keep iterating until both apps boot and the browser console shows no new framework regressions. Treat unrelated environment warnings separately and call them out clearly.

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
@@ -236,6 +236,7 @@ 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 init` | Experimental project scaffolding when scaffold assets are installed |
 
 Recommended daily workflow:
@@ -255,8 +256,50 @@ proteum doctor --json
 proteum explain
 proteum explain --routes --controllers
 proteum explain --all --json
+proteum trace requests
+proteum trace arm --capture deep
+proteum trace latest
 ```
 
+## 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 `env.yaml` 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.requestsLimit` and `trace.eventsLimit`
+- payloads are summarized, long strings are truncated, and sensitive fields such as cookies, passwords, and tokens are redacted
+- `persistOnError` can export crashing requests under `var/traces/`
+
+`env.yaml` example:
+
+```yaml
+trace:
+  enable: true
+  requestsLimit: 200
+  eventsLimit: 800
+  capture: resolve
+  persistOnError: 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:
@@ -287,6 +330,8 @@ If you are an LLM or automation agent, start here:
 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: