proteum 2.1.0 → 2.1.1

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,86 @@
+## 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
+
+### 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/request-tracing.md

@@ -0,0 +1,122 @@
+# 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
+- 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
+- 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.
+
+## 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/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.0",
+	"version": "2.1.1",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",
@@ -70,7 +70,6 @@
 		"preact-render-to-string": "^6.6.1",
 		"prompts": "^2.4.2",
 		"replace-once": "^1.0.0",
-		"request": "^2.88.2",
 		"responsive-loader": "^3.1.2",
 		"serialize-javascript": "^6.0.2",
 		"sharp": "^0.34.3",