proteum 2.1.0 → 2.1.2

package/common/env/proteumEnv.ts

@@ -0,0 +1,284 @@
+import fs from 'fs';
+import path from 'path';
+import dotenv from 'dotenv';
+
+export type TProteumEnvName = 'local' | 'server';
+export type TProteumEnvProfile = 'dev' | 'testing' | 'prod';
+export type TProteumTraceCapture = 'summary' | 'resolve' | 'deep';
+export type TProteumRequiredEnvVariable = {
+    key: TProteumRequiredEnvVariableKey;
+    possibleValues: string[];
+    provided: boolean;
+};
+export type TProteumEnvInspection = {
+    loadedVariableKeys: string[];
+    requiredVariables: TProteumRequiredEnvVariable[];
+};
+
+export type TProteumEnvConfig = {
+    name: TProteumEnvName;
+    profile: TProteumEnvProfile;
+    router: {
+        port: number;
+        currentDomain: string;
+    };
+    trace: {
+        enable: boolean;
+        requestsLimit: number;
+        eventsLimit: number;
+        capture: TProteumTraceCapture;
+        persistOnError: boolean;
+    };
+};
+
+export type TProteumLoadedEnvConfig = TProteumEnvConfig & { version: string };
+
+const dotenvFileNames = ['.env'];
+const requiredProteumEnvVariableKeys = ['ENV_NAME', 'ENV_PROFILE', 'PORT', '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'],
+};
+
+const envDefinitionHint = (appDir: string) => `Define it in process.env or ${appDir}/.env.`;
+const isProvidedEnvValue = (value: string | undefined) => typeof value === 'string' && value.trim() !== '';
+
+const formatRequiredEnvVariableStatus = (variable: TProteumRequiredEnvVariable) =>
+    `- ${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`;
+
+const createProteumEnvError = ({
+    appDir,
+    message,
+}: {
+    appDir: string;
+    message: string;
+}) => {
+    const inspection = inspectProteumEnv(appDir);
+
+    return new Error(
+        [message, envDefinitionHint(appDir), '', 'Required env variables:', ...inspection.requiredVariables.map(formatRequiredEnvVariableStatus)].join(
+            '\n',
+        ),
+    );
+};
+
+const parseBooleanEnvValue = ({
+    key,
+    value,
+    appDir,
+}: {
+    key: string;
+    value: string | undefined;
+    appDir: string;
+}) => {
+    if (value === undefined || value === '') return undefined;
+
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+
+    throw createProteumEnvError({
+        appDir,
+        message: `Invalid boolean value for ${key}: "${value}". Expected one of: 1, 0, true, false, yes, no, on, off.`,
+    });
+};
+
+const parseIntegerEnvValue = ({
+    key,
+    value,
+    appDir,
+    min = 1,
+}: {
+    key: string;
+    value: string;
+    appDir: string;
+    min?: number;
+}) => {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < min) {
+        throw createProteumEnvError({
+            appDir,
+            message: `Invalid integer value for ${key}: "${value}". Expected an integer greater than or equal to ${min}.`,
+        });
+    }
+
+    return parsed;
+};
+
+const getRequiredEnvValue = ({ key, appDir }: { key: TProteumRequiredEnvVariableKey; appDir: string }) => {
+    const value = process.env[key]?.trim();
+    if (value) return value;
+
+    throw createProteumEnvError({
+        appDir,
+        message: `Missing required Proteum env variable "${key}".`,
+    });
+};
+
+const parseEnvName = (value: string, appDir: string): TProteumEnvName => {
+    if (value === 'local' || value === 'server') return value;
+    throw createProteumEnvError({
+        appDir,
+        message: `Invalid ENV_NAME "${value}". Expected "local" or "server".`,
+    });
+};
+
+const parseEnvProfile = (value: string, appDir: string): TProteumEnvProfile => {
+    if (value === 'dev' || value === 'testing' || value === 'prod') return value;
+    throw createProteumEnvError({
+        appDir,
+        message: `Invalid ENV_PROFILE "${value}". Expected "dev", "testing", or "prod".`,
+    });
+};
+
+const parseTraceCapture = ({
+    value,
+    appDir,
+}: {
+    value: string | undefined;
+    appDir: string;
+}): TProteumTraceCapture | undefined => {
+    if (value === undefined || value === '') return undefined;
+    if (value === 'summary' || value === 'resolve' || value === 'deep') return value;
+
+    throw createProteumEnvError({
+        appDir,
+        message: `Invalid TRACE_CAPTURE "${value}". Expected "summary", "resolve", or "deep".`,
+    });
+};
+
+const parseAbsoluteUrl = ({
+    key,
+    value,
+    appDir,
+}: {
+    key: string;
+    value: string;
+    appDir: string;
+}) => {
+    let url: URL;
+
+    try {
+        url = new URL(value);
+    } catch {
+        throw createProteumEnvError({
+            appDir,
+            message: `Invalid absolute URL for ${key}: "${value}". Expected an absolute http:// or https:// URL.`,
+        });
+    }
+
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw createProteumEnvError({
+            appDir,
+            message: `Invalid absolute URL for ${key}: "${value}". Expected an absolute http:// or https:// URL.`,
+        });
+    }
+
+    return value;
+};
+
+export const loadOptionalProteumDotenv = (appDir: string) => {
+    for (const filename of dotenvFileNames) {
+        const filepath = path.join(appDir, filename);
+        if (!fs.existsSync(filepath)) continue;
+        dotenv.config({ path: filepath, quiet: true });
+    }
+};
+
+export const getLoadedProteumEnvVariableKeys = () =>
+    Object.keys(process.env)
+        .filter(
+            (key) =>
+                requiredProteumEnvVariableKeys.includes(key as TProteumRequiredEnvVariableKey) ||
+                optionalProteumEnvVariablePrefixes.some((prefix) => key.startsWith(prefix)),
+        )
+        .sort((a, b) => a.localeCompare(b));
+
+export const inspectProteumEnv = (appDir: string): TProteumEnvInspection => {
+    loadOptionalProteumDotenv(appDir);
+
+    return {
+        loadedVariableKeys: getLoadedProteumEnvVariableKeys(),
+        requiredVariables: requiredProteumEnvVariableKeys.map((key) => ({
+            key,
+            possibleValues: [...requiredProteumEnvVariablePossibleValues[key]],
+            provided: isProvidedEnvValue(process.env[key]),
+        })),
+    };
+};
+
+export const parseProteumEnvConfig = ({
+    appDir,
+    routerPortOverride,
+}: {
+    appDir: string;
+    routerPortOverride?: number;
+}): TProteumEnvConfig => {
+    loadOptionalProteumDotenv(appDir);
+
+    const name = parseEnvName(getRequiredEnvValue({ key: 'ENV_NAME', appDir }), appDir);
+    const profile = parseEnvProfile(getRequiredEnvValue({ key: 'ENV_PROFILE', appDir }), appDir);
+    const configuredRouterPort = parseIntegerEnvValue({
+        key: 'PORT',
+        value: getRequiredEnvValue({ key: 'PORT', appDir }),
+        appDir,
+    });
+    const currentDomain = parseAbsoluteUrl({
+        key: 'URL',
+        value: getRequiredEnvValue({ key: 'URL', appDir }),
+        appDir,
+    });
+
+    const traceEnable = parseBooleanEnvValue({
+        key: 'TRACE_ENABLE',
+        value: process.env.TRACE_ENABLE,
+        appDir,
+    });
+    const tracePersistOnError = parseBooleanEnvValue({
+        key: 'TRACE_PERSIST_ON_ERROR',
+        value: process.env.TRACE_PERSIST_ON_ERROR,
+        appDir,
+    });
+    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,
+    });
+
+    return {
+        name,
+        profile,
+        router: {
+            port: routerPortOverride === undefined ? configuredRouterPort : routerPortOverride,
+            currentDomain,
+        },
+        trace: {
+            enable: traceEnable ?? profile === 'dev',
+            requestsLimit:
+                traceRequestsLimit === undefined || traceRequestsLimit === ''
+                    ? 200
+                    : parseIntegerEnvValue({
+                          key: 'TRACE_REQUESTS_LIMIT',
+                          value: traceRequestsLimit,
+                          appDir,
+                      }),
+            eventsLimit:
+                traceEventsLimit === undefined || traceEventsLimit === ''
+                    ? 800
+                    : parseIntegerEnvValue({
+                          key: 'TRACE_EVENTS_LIMIT',
+                          value: traceEventsLimit,
+                          appDir,
+                      }),
+            capture: traceCapture ?? 'resolve',
+            persistOnError: tracePersistOnError ?? profile === 'dev',
+        },
+    };
+};

package/common/router/index.ts

@@ -106,8 +106,6 @@ export type TRouteModule<TRegisteredRoute = any> = {
     __register: TAppArrowFunction<TRegisteredRoute>;
 };
 
-export type TDomainsList = { [endpointId: string]: string } & { current: string };
-
 export const defaultOptions: Pick<TRouteOptions, 'priority'> = { priority: 0 };
 
 /*----------------------------------
@@ -116,31 +114,15 @@ export const defaultOptions: Pick<TRouteOptions, 'priority'> = { priority: 0 };
 export const buildUrl = (
     path: string,
     params: { [key: string]: any },
-    domains: { [alias: string]: string },
+    currentDomain: string,
     absolute: boolean,
 ) => {
     let prefix: string = '';
 
     // Relative to domain
-    if (path[0] === '/' && absolute) prefix = domains.current;
-    // Other domains of the project
-    else if (path[0] === '@') {
-        // Extract domain ID from path
-        let domainId: string;
-        let slackPos = path.indexOf('/');
-        if (slackPos === -1) slackPos = path.length;
-        domainId = path.substring(1, slackPos);
-        path = path.substring(slackPos);
-
-        // Get domain
-        const domain = domains[domainId];
-        if (domain === undefined) throw new Error('Unknown API endpoint ID: ' + domainId);
-
-        // Return full url
-        prefix = domain;
-
-        // Absolute URL
-    }
+    if (path[0] === '/' && absolute) prefix = currentDomain;
+    else if (path[0] === '@')
+        throw new Error(`Proteum no longer supports Router.url() domain aliases. Use a root-relative path or absolute URL instead: "${path}".`);
 
     // Path parapeters
     const searchParams = new URLSearchParams();

package/docs/dev-commands.md

@@ -0,0 +1,93 @@
+## Dev Commands
+
+Proteum supports a dev-only internal command surface for testing, debugging, and one-off server-side execution that should not be exposed as a normal controller or route.
+
+### Source Contract
+
+- command files live under `./commands/**/*.ts`
+- each file default-exports a class extending `Commands` from `@server/app/commands`
+- every method with a body becomes a runnable command
+- the command path is `file/path/methodName`
+- `export const commandPath = 'Custom/path'` can override the file-derived base path
+
+Example:
+
+```ts
+import { Commands } from '@server/app/commands';
+
+export default class DiagnosticsCommands extends Commands {
+  public async ping() {
+    return {
+      app: this.app.identity.identifier,
+      env: this.app.env.profile,
+    };
+  }
+}
+```
+
+The example above is available as `diagnostics/ping`.
+
+When `./commands` exists, Proteum also creates `./commands/tsconfig.json` plus a generated command typing surface under `.proteum/server/commands.d.ts`.
+
+- command files inherit the server alias project
+- `extends Commands` works without importing your app class
+- `@/server/index` remains available inside `/commands` as a generated command-only app type alias
+
+### CLI
+
+Run a command locally:
+
+```bash
+proteum command proteum/diagnostics/ping
+```
+
+Local mode does this:
+
+1. refreshes `.proteum` artifacts
+2. picks a temporary local port
+3. builds the dev server output
+4. starts a temporary local dev server
+5. runs the command through the dev-only command endpoint
+6. prints the result and exits
+
+Run a command against an existing dev instance:
+
+```bash
+proteum command proteum/diagnostics/ping --port 3101
+proteum command proteum/diagnostics/ping --url http://127.0.0.1:3101
+```
+
+Use `--port` or `--url` when you want to reuse an existing `proteum dev` instance instead of building and starting a temporary local one.
+
+### Profiler
+
+In `proteum dev`, the bottom profiler exposes a `Commands` tab.
+
+- it lists every generated command path
+- 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
+
+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:
+
+- `GET /__proteum/commands`
+- `POST /__proteum/commands/run`
+
+These endpoints exist only in dev mode and are not available in production.
+
+### Built-In Command
+
+Proteum ships one framework command by default:
+
+- `proteum/diagnostics/ping`
+
+It returns the current app identifier, active env profile, and discovered root services so every dev app has a real command surface available immediately.

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

@@ -0,0 +1,132 @@
+# Request Tracing
+
+Proteum ships with a dev-only in-memory request trace buffer so routing, controller execution, SSR, and render behavior can be inspected without attaching a debugger or scattering temporary logs through the runtime.
+
+## Scope
+
+- 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
+
+```bash
+proteum trace requests
+proteum trace latest
+proteum trace show <requestId>
+proteum trace arm --capture deep
+proteum trace export <requestId>
+proteum trace latest --url http://127.0.0.1:3010
+```
+
+Before reproducing a bug or starting a new test pass:
+
+- read the default port from `PORT` or `./.proteum/manifest.json`
+- check whether a dev server is already running on that port
+- if it is, inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` first so you can capture past errors and their context
+
+Typical debugging flow:
+
+```bash
+proteum trace arm --capture deep --port 3103
+# reproduce the failing request once
+proteum trace requests --port 3103
+proteum trace show <requestId> --port 3103
+```
+
+Use `--url http://host:port` when the dev server is reachable on a non-standard host and `--port` is not enough.
+
+## What Gets Recorded
+
+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
+- created router/context keys
+- setup output keys and page data summaries
+- SSR payload shape and serialized byte size
+- render start/end timings and document output sizes
+- normalized request errors
+
+## Capture Modes
+
+- `summary`: smallest capture, focused on request lifecycle and high-signal events
+- `resolve`: adds route matching, controller, setup, and context milestones
+- `deep`: adds route skip reasons and deeper summarized payload inspection for one request
+
+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:
+
+```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
+```
+
+Notes:
+
+- `enable` and `persistOnError` still remain dev-only in the current runtime
+- `capture` defaults to `resolve`
+- `requestsLimit` defaults to `200`
+- `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
+
+## Memory Model
+
+Traces are kept in memory per Node process.
+
+- requests are stored in a ring buffer capped by `requestsLimit`
+- the oldest request traces are evicted first
+- each request is capped by `eventsLimit`
+- once the event cap is reached, extra events are dropped and counted in `droppedEvents`
+- payloads are summarized rather than stored as raw objects
+
+Current summarization rules:
+
+- arrays keep at most 10 sampled items
+- objects keep at most 20 keys per level
+- deep capture stops at depth 3
+- long strings are truncated
+
+## Redaction
+
+Sensitive values are redacted before they enter the trace store.
+
+This includes keys such as:
+
+- `cookie`
+- `authorization`
+- `password`
+- token-like fields such as `accessToken`, `refreshToken`, `apiKey`, `jwt`, and similar names
+- `rawBody`
+
+The goal is to make traces useful for debugging without turning the dev server into a secret dump.
+
+## Dev HTTP Endpoints
+
+These endpoints back the CLI:
+
+- `GET /__proteum/trace/requests`
+- `GET /__proteum/trace/latest`
+- `GET /__proteum/trace/requests/:id`
+- `POST /__proteum/trace/arm`
+
+The CLI should be the primary interface. Use the HTTP endpoints when you need direct machine access from another local dev tool.

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.',
                 },
             ],
         },