proteum 2.1.1 → 2.1.2

package/common/dev/profiler.ts

@@ -9,6 +9,7 @@ export type TProfilerUiState = 'expanded' | 'minimized' | 'pinned-handle';
 export type TProfilerPanel =
     | 'summary'
     | 'timeline'
+    | 'auth'
     | 'routing'
     | 'controller'
     | 'ssr'

package/common/dev/requestTrace.ts

@@ -10,6 +10,12 @@ export type TTraceCallOrigin = (typeof traceCallOrigins)[number];
 export const traceEventTypes = [
     'request.start',
     'request.user',
+    'auth.decode',
+    'auth.route',
+    'auth.check.start',
+    'auth.check.rule',
+    'auth.check.result',
+    'auth.session',
     'resolve.start',
     'resolve.controller-route',
     'resolve.routes-evaluated',

package/docs/dev-commands.md

@@ -68,6 +68,13 @@ In `proteum dev`, the bottom profiler exposes a `Commands` tab.
 - 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
 
+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`
+
+For the shared diagnostics contract and the corresponding dev HTTP endpoints, see [diagnostics.md](diagnostics.md).
+
 ### HTTP Endpoints
 
 The CLI remote mode and the profiler use the same dev-only endpoints:

package/docs/diagnostics.md

@@ -0,0 +1,88 @@
+# Diagnostics and Explainability
+
+Proteum exposes two manifest-backed diagnostics surfaces:
+
+- `proteum explain`: inspect the generated app structure
+- `proteum doctor`: inspect manifest diagnostics
+
+These are not separate models for different tools. They share the same generated snapshot and the same diagnostics contract.
+
+## Shared Contract
+
+The canonical snapshot lives in `./.proteum/manifest.json`.
+
+Proteum uses that same manifest in four places:
+
+- `proteum explain` for human-readable and `--json` output
+- `proteum doctor` for human-readable and `--json` output
+- the dev-only `__proteum/explain` and `__proteum/doctor` HTTP endpoints
+- the `Explain` and `Doctor` tabs in the bottom profiler during `proteum dev`
+
+This means the CLI, the dev HTTP endpoints, and the profiler all describe the same manifest-backed snapshot.
+
+If a command such as `proteum explain`, `proteum doctor`, or `proteum refresh` regenerates `.proteum/manifest.json`, the next CLI call, HTTP call, or profiler refresh will reflect that same updated snapshot.
+
+## CLI
+
+Common usage:
+
+```bash
+proteum explain
+proteum explain --routes --controllers --commands
+proteum explain --all --json
+
+proteum doctor
+proteum doctor --json
+proteum doctor --strict
+```
+
+`proteum explain --json` emits the selected manifest sections as machine-readable JSON.
+
+`proteum doctor --json` emits:
+
+- `summary.errors`
+- `summary.warnings`
+- `summary.strictFailed`
+- `diagnostics`
+
+## Dev HTTP Endpoints
+
+In `profile: dev`, the running app exposes:
+
+- `GET /__proteum/explain`
+- `GET /__proteum/doctor`
+
+`/__proteum/explain` supports optional section selection:
+
+```text
+GET /__proteum/explain?sections=routes,controllers,commands
+GET /__proteum/explain?section=env&section=diagnostics
+```
+
+`/__proteum/doctor` supports optional strict mode:
+
+```text
+GET /__proteum/doctor?strict=true
+```
+
+These endpoints are intended for local tooling and are not available in production.
+
+## Profiler
+
+During `proteum dev`, the bottom profiler is the human-facing UI over the same dev diagnostics surfaces.
+
+- `Explain` calls `/__proteum/explain`
+- `Doctor` calls `/__proteum/doctor`
+- `Commands` uses the dev command endpoints
+- `Auth`, `Timeline`, `Routing`, `Controller`, `SSR`, `API`, and related panels remain request-trace views
+
+Use the profiler when a human needs to browse the same data that an agent or CLI command can already inspect directly.
+
+## Agent Workflow
+
+For AI coding agents or automation:
+
+1. Read `./.proteum/manifest.json` or run `proteum explain --json`.
+2. Run `proteum doctor --json` to inspect framework diagnostics.
+3. For request-time behavior, use `proteum trace ...` because traces are live runtime data, not manifest snapshots.
+4. Open the profiler only when a human-readable view helps; it should agree with the CLI after refresh.

package/docs/request-tracing.md

@@ -6,6 +6,7 @@ Proteum ships with a dev-only in-memory request trace buffer so routing, control
 
 - tracing is available only when the app runs with `profile: dev`
 - traces are exposed through `proteum trace` and the dev-only `__proteum/trace` HTTP endpoints
+- explain/doctor are separate manifest-backed diagnostics surfaces; see [diagnostics.md](diagnostics.md)
 - production requests are not traced by this feature
 
 ## Main Commands
@@ -41,6 +42,7 @@ Use `--url http://host:port` when the dev server is reachable on a non-standard
 Depending on capture mode, traces can include:
 
 - request start, finish, user identity, status code, and duration
+- auth decode input and outcome, route auth decisions, matched auth rules, rule inputs/results, and session create or clear events
 - direct controller route matches
 - route resolution start, match, and deep-mode skip reasons
 - controller start and result shape
@@ -58,6 +60,14 @@ Depending on capture mode, traces can include:
 
 Use `deep` selectively. It is for one-off investigation, not continuous capture.
 
+## Profiler
+
+During `proteum dev`, the bottom profiler renders the same live request traces.
+
+- `Timeline` shows the full request event stream
+- `Auth` filters the selected session down to auth-specific events so matched rules, tracking, and allow/deny outcomes can be inspected without scanning unrelated events
+- expanding an auth event shows the summarized detail payload exactly as stored in the trace
+
 ## Configuration
 
 Set trace behavior with env vars:

package/eslint.js

@@ -11,8 +11,8 @@ const defaultIgnores = [
     '**/var/**',
 ];
 
-const createDoubleAssertionSelector = (typeKeyword) =>
-    `TSAsExpression[expression.type='TSAsExpression'][expression.typeAnnotation.type='${typeKeyword}']`;
+const createZodTypeFactorySelector = (factoryName) =>
+    `CallExpression[callee.type='MemberExpression'][callee.computed=false][callee.object.type='Identifier'][callee.object.name=/^(schema|z|zod)$/][callee.property.name='${factoryName}']`;
 
 const createProteumEslintConfig = ({ ignores = [] } = {}) => [
     {
@@ -42,15 +42,20 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
             'jsx-a11y': jsxA11yPlugin,
         },
         rules: {
+            '@typescript-eslint/no-explicit-any': 'error',
             'no-restricted-syntax': [
                 'error',
                 {
-                    selector: createDoubleAssertionSelector('TSUnknownKeyword'),
-                    message: 'Do not use double assertions through `unknown`.',
+                    selector: 'TSUnknownKeyword',
+                    message: 'Do not use `unknown`; define an explicit type instead.',
                 },
                 {
-                    selector: createDoubleAssertionSelector('TSAnyKeyword'),
-                    message: 'Do not use double assertions through `any`.',
+                    selector: createZodTypeFactorySelector('any'),
+                    message: 'Do not use Zod `any()` schemas; define an explicit schema instead.',
+                },
+                {
+                    selector: createZodTypeFactorySelector('unknown'),
+                    message: 'Do not use Zod `unknown()` schemas; define an explicit schema instead.',
                 },
             ],
         },

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.1",
+	"version": "2.1.2",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -23,6 +23,7 @@
 		"@tailwindcss/postcss": "^4.1.17",
 		"accepts": "^1.3.7",
 		"ansi-to-html": "^0.7.1",
+		"apexcharts": "^5.10.4",
 		"autoprefixer": "^10.4.21",
 		"aws-sdk": "^2.1415.0",
 		"bowser": "^2.11.0",
@@ -41,7 +42,6 @@
 		"eslint-plugin-react": "^7.37.5",
 		"eslint-plugin-react-hooks": "^7.0.1",
 		"express": "^4.17.1",
-		"express-csp-header": "^5.0.0",
 		"express-fileupload": "^1.2.1",
 		"fast-safe-stringify": "^2.1.1",
 		"favicons": "^7.2.0",
@@ -69,6 +69,7 @@
 		"preact": "^10.27.1",
 		"preact-render-to-string": "^6.6.1",
 		"prompts": "^2.4.2",
+		"react-apexcharts": "^2.1.0",
 		"replace-once": "^1.0.0",
 		"responsive-loader": "^3.1.2",
 		"serialize-javascript": "^6.0.2",

package/server/app/index.ts

@@ -2,6 +2,8 @@
 - DEPENDANCES
 ----------------------------------*/
 
+process.env.DOTENV_CONFIG_QUIET ??= 'true';
+
 // Core
 import AppContainer from './container';
 import ApplicationService, { AnyService } from './service';
@@ -144,8 +146,6 @@ export abstract class Application<
     ----------------------------------*/
 
     public async start(options: TApplicationStartOptions = {}) {
-        console.log('Build date', BUILD_DATE);
-        console.log('Core version', CORE_VERSION);
         const startTime = Date.now();
 
         const startingServices = await this.ready(options);

package/server/index.ts

@@ -9,7 +9,6 @@ const shutdownApplication = async (reason: string) => {
     if (!shutdownPromise) {
         shutdownPromise = (async () => {
             try {
-                console.info(`[server] Shutting down (${reason}) ...`);
                 await application.runHook('cleanup');
             } catch (error) {
                 console.error('[server] Failed to run application cleanup.', error);