proteum 2.1.0-3 → 2.1.0-5

package/README.md

@@ -36,7 +36,7 @@ Proteum combines:
 ```text
 my-app/
   identity.yaml
-  env.yaml
+  .env               # optional file for required local env vars
   package.json
   client/
     pages/
@@ -63,7 +63,7 @@ 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(...)`
@@ -71,6 +71,25 @@ Important files:
 - `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 +106,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,
@@ -265,6 +284,8 @@ proteum trace latest
 
 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
@@ -275,19 +296,18 @@ Proteum includes a dev-only in-memory request trace buffer for routing, controll
 Default behavior:
 
 - tracing is enabled only in `profile: dev`
-- traces live in memory and are bounded by `trace.requestsLimit` and `trace.eventsLimit`
+- 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
-- `persistOnError` can export crashing requests under `var/traces/`
+- `TRACE_PERSIST_ON_ERROR` can export crashing requests under `var/traces/`
 
-`env.yaml` example:
+Trace env example:
 
-```yaml
-trace:
-  enable: true
-  requestsLimit: 200
-  eventsLimit: 800
-  capture: resolve
-  persistOnError: true
+```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:
@@ -312,7 +332,7 @@ 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
@@ -321,7 +341,7 @@ Proteum answers those questions with explicit artifacts:
 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.

package/agents/framework/AGENTS.md

@@ -12,7 +12,8 @@ When you enter a Proteum app, inspect it in this order:
 2. Inspect `./server/index.ts` and `./server/config/*.ts`.
 3. Inspect the touched `./server/controllers/**/*.ts`, `./server/services/**`, `./server/routes/**`, and `./client/pages/**` files.
 4. Run `npx proteum doctor` if routing or generation looks suspicious.
-5. For request-time issues in dev, use `npx proteum trace` before adding temporary logs.
+5. If you need to diagnose or test against a running app, check the default port in `PORT` or `./.proteum/manifest.json` first.
+6. If a server is already running on that port, use `npx proteum trace` to inspect past requests, errors, and their context before reproducing the issue or adding temporary logs.
 
 ## Non-Negotiable Rules
 
@@ -37,7 +38,7 @@ Proteum reads these source files directly:
 
 - `package.json`
 - `identity.yaml`
-- `env.yaml`
+- `process.env` via the `PORT`, `ENV_*`, `URL`, and `TRACE_*` env contract
 - `server/config/*.ts`
 - `server/index.ts`
 - `server/services/**/service.json`
@@ -238,12 +239,17 @@ Relevant aliases:
 
 1. Run `npx proteum explain --json`.
 2. Run `npx proteum doctor`.
-3. If the issue is request-time behavior in dev, run:
-   - `npx proteum trace arm --capture deep`
+3. Read the default port from `PORT` or `./.proteum/manifest.json` and check whether a server is already running there.
+4. If a server is already running on that default port, inspect existing traces first:
+   - `npx proteum trace requests --port <envPort>`
+   - `npx proteum trace latest --port <envPort>`
+   - `npx proteum trace show <requestId> --port <envPort>` when you need the full context for a past error
+5. If the issue is request-time behavior in dev and the existing traces are not enough, run:
+   - `npx proteum trace arm --capture deep --port <envPort>`
    - reproduce the failing request once
-   - `npx proteum trace latest` or `npx proteum trace show <requestId>`
-4. Inspect the touched controller, service, route, or page source.
-5. Only add temporary logging if the trace is insufficient.
+   - `npx proteum trace latest --port <envPort>` or `npx proteum trace show <requestId> --port <envPort>`
+6. Inspect the touched controller, service, route, or page source.
+7. Only add temporary logging if the trace is insufficient.
 
 For the full trace reference, see `node_modules/proteum/docs/request-tracing.md` in installed apps or `docs/request-tracing.md` in the framework repository.
 
@@ -274,6 +280,12 @@ Verify at the correct layer:
 - SSR changes: load the real page and inspect rendered HTML plus browser console
 - router/plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
 
+When you need to diagnose or test against an app that may already be running:
+
+- read the default port from `PORT` or `./.proteum/manifest.json`
+- check whether a server is already running on that port
+- if it is, inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue
+
 Useful app commands:
 
 - `proteum dev`

package/agents/project/AGENTS.md

@@ -25,6 +25,12 @@ For request-time issues in dev, inspect traces before adding temporary logs:
 - `npx proteum trace latest`
 - `npx proteum trace arm --capture deep`
 
+If you need to diagnose or test against a running app:
+
+- read the default port from `PORT` or `./.proteum/manifest.json`
+- check whether a server is already running on that port
+- if it is, inspect existing traces first to collect past errors and their context before reproducing the issue
+
 ## Project Structure
 
 This is a full-stack monolith project using TypeScript, Node.js, Preact, and Proteum.
@@ -77,13 +83,13 @@ When a feature depends on a curated list, keep one canonical catalog or registry
   1. evaluate or quantify the probability
   2. explain why
   3. suggest how to fix it
-- When the issue is request-time behavior in dev, prefer `npx proteum trace` over ad hoc logging.
+- When the issue is request-time behavior in dev, first check whether a server is already running on the default port from `PORT` or `./.proteum/manifest.json`. If it is, prefer `npx proteum trace` to inspect past errors and their context before reproducing the issue or adding logs.
 - When you have finished your work, summarize in one top-level short sentence the changes you made since the beginning of the conversation. Output as `Commit message`.
 
 ## High-Impact Files
 
 - `tsconfig*.json`
-- `env*.yaml`
+- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
 - Prisma-generated files
 - symbolic links
 

package/cli/app/config.ts

@@ -2,20 +2,12 @@
 - DEPENDANCES
 ----------------------------------*/
 
-/*
-    NOTE: This is a copy of core/sever/app/config
-    We can't import core deps here because it will cause the following error:
-        "Can't use import when not a module"
-    It will be possible to import core files when the CLI will be compiled as one output file with tsc
-    And for that, we need to fix the TS errors for the CLI
-*/
-
 // Npm
 import fs from 'fs-extra';
 import yaml from 'yaml';
 
 // Types
-import type { TEnvConfig } from '../../server/app/container/config';
+import { parseProteumEnvConfig, type TProteumLoadedEnvConfig } from '../../common/env/proteumEnv';
 import { logVerbose } from '../runtime/verbose';
 
 /*----------------------------------
@@ -34,18 +26,13 @@ export default class ConfigParser {
         return yaml.parse(rawConfig);
     }
 
-    public env(): TEnvConfig {
-        // We assume that when we run 5htp dev, we're in local
-        // Otherwise, we're in production environment (docker)
-        logVerbose('[app] Using environment:', process.env.NODE_ENV);
-        const envFileName = this.appDir + '/env.yaml';
-        const envFile = this.loadYaml(envFileName);
+    public env(): TProteumLoadedEnvConfig {
+        logVerbose('[app] Loading Proteum env vars from process.env');
         return {
-            ...envFile,
-            router:
-                this.routerPortOverride === undefined
-                    ? envFile.router
-                    : { ...envFile.router, port: this.routerPortOverride },
+            ...parseProteumEnvConfig({
+                appDir: this.appDir,
+                routerPortOverride: this.routerPortOverride,
+            }),
             version: 'CLI',
         };
     }

package/cli/bin.js

@@ -2,6 +2,12 @@
 
 const path = require('path');
 
+const clearInteractiveConsole = () => {
+    if (process.stdout.isTTY !== true || process.env.TERM === 'dumb') return;
+
+    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
+};
+
 /*
     Why this exists (npm i vs npm link difference)
 
@@ -30,6 +36,8 @@ if (!process.env.TS_NODE_IGNORE) {
 process.env.TS_NODE_PROJECT = path.join(__dirname, 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 
+clearInteractiveConsole();
+
 require('ts-node/register/transpile-only');
 
 const { runCli } = require('./index.ts');

package/cli/commands/deploy/web.ts

@@ -45,8 +45,7 @@ export async function run() {
         { spaces: 4 },
     );
 
-    // Copy config file
-    fs.copyFileSync(app.paths.root + (simulate ? '/env.yaml' : '/env.server.yaml'), temp + '/env.yaml');
+    // Deployment now relies on exported ENV_*, URL, TRACE_*, and PORT variables instead of copied env config files.
 
     // Compile & Run Docker
     await cli.shell(`docker compose up --build`);

package/cli/commands/explain.ts

@@ -115,10 +115,11 @@ const printSection = (title: string, lines: string[]) => {
 const renderSummary = (manifest: TProteumManifest) => {
     const errorsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
     const warningsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+    const providedRequiredEnvVariables = manifest.env.requiredVariables.filter((variable) => variable.provided).length;
     const lines = [
         `Proteum manifest: ${formatFilepath(manifest, path.join(manifest.app.root, '.proteum', 'manifest.json'))}`,
         `App: ${manifest.app.identity.name} (${manifest.app.identity.identifier})`,
-        `Env keys: ${manifest.env.loadedTopLevelKeys.join(', ') || 'none'}`,
+        `Env vars: ${providedRequiredEnvVariables}/${manifest.env.requiredVariables.length} required provided`,
         `Services: ${manifest.services.app.length} app, ${manifest.services.routerPlugins.length} router plugins`,
         `Controllers: ${manifest.controllers.length}`,
         `Routes: ${manifest.routes.client.length} client, ${manifest.routes.server.length} server`,
@@ -163,9 +164,16 @@ const renderHuman = (manifest: TProteumManifest, sectionNames: TExplainSectionNa
         if (sectionName === 'env') {
             sections.push(
                 printSection('Env', [
-                    `- source=${formatFilepath(manifest, manifest.env.sourceFilepath)}`,
-                    `- loadedTopLevelKeys=${manifest.env.loadedTopLevelKeys.join(', ') || 'none'}`,
-                    `- requiredTopLevelKeys=${manifest.env.requiredTopLevelKeys.join(', ')}`,
+                    `- source=${manifest.env.source}`,
+                    `- loadedVariableKeys=${manifest.env.loadedVariableKeys.join(', ') || 'none'}`,
+                    ...manifest.env.requiredVariables.map(
+                        (variable) =>
+                            `- ${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`,
+                    ),
+                    `- resolved.name=${manifest.env.resolved.name}`,
+                    `- resolved.profile=${manifest.env.resolved.profile}`,
+                    `- resolved.routerPort=${manifest.env.resolved.routerPort}`,
+                    `- resolved.routerCurrentDomain=${manifest.env.resolved.routerCurrentDomain}`,
                 ]),
             );
             continue;

package/cli/commands/trace.ts

@@ -1,7 +1,6 @@
 import fs from 'fs-extra';
 import got from 'got';
 import path from 'path';
-import yaml from 'yaml';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
@@ -12,7 +11,7 @@ import type {
     TRequestTraceListItem,
     TRequestTraceListResponse,
     TRequestTraceResponse,
-} from '@common/dev/requestTrace';
+} from '../../common/dev/requestTrace';
 
 type TTraceAction = 'latest' | 'show' | 'requests' | 'arm' | 'export';
 
@@ -31,22 +30,33 @@ const getAction = () => {
 
 const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
 
+const getRouterPortFromManifest = () => {
+    const manifestFilepath = path.join(cli.args.workdir as string, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    const manifest = fs.readJsonSync(manifestFilepath, { throws: false }) as
+        | { env?: { resolved?: { routerPort?: number } } }
+        | undefined;
+    const port = manifest?.env?.resolved?.routerPort;
+
+    if (typeof port !== 'number' || port <= 0) return undefined;
+
+    return String(port);
+};
+
 const getRouterPort = () => {
     const overridePort = typeof cli.args.port === 'string' && cli.args.port ? cli.args.port : '';
     if (overridePort) return overridePort;
 
-    const envFilepath = path.join(cli.args.workdir as string, 'env.yaml');
-    if (!fs.existsSync(envFilepath)) {
-        throw new UsageError(`Could not find env.yaml in ${cli.args.workdir as string}. Pass --port or --url explicitly.`);
-    }
+    const envPort = process.env.PORT?.trim();
+    if (envPort) return envPort;
 
-    const envFile = yaml.parse(fs.readFileSync(envFilepath, 'utf8')) as { router?: { port?: number } };
-    const port = envFile.router?.port;
-    if (!port) {
-        throw new UsageError(`Could not determine the router port from ${envFilepath}. Pass --port or --url explicitly.`);
-    }
+    const manifestPort = getRouterPortFromManifest();
+    if (manifestPort) return manifestPort;
 
-    return String(port);
+    throw new UsageError(
+        `Could not determine the router port from PORT or .proteum/manifest.json in ${cli.args.workdir as string}. Pass --port or --url explicitly.`,
+    );
 };
 
 const getRouterBaseUrls = () => {

package/cli/compiler/artifacts/manifest.ts

@@ -1,9 +1,10 @@
 import path from 'path';
-import fs from 'fs-extra';
-import yaml from 'yaml';
 
 import app from '../../app';
 import cli from '../..';
+import {
+    inspectProteumEnv,
+} from '../../../common/env/proteumEnv';
 import { reservedRouteSetupKeys, routeSetupOptionKeys } from '../../../common/router/pageSetup';
 import {
     TProteumManifest,
@@ -15,20 +16,6 @@ import {
 import { writeProteumManifest } from '../common/proteumManifest';
 import { normalizeAbsolutePath, normalizePath } from './shared';
 
-const envRequiredTopLevelKeys = ['name', 'profile', 'router', 'console'];
-
-const getEnvTopLevelKeys = () => {
-    const envFilepath = path.join(app.paths.root, 'env.yaml');
-
-    if (!fs.existsSync(envFilepath)) return [];
-
-    const rawEnv = yaml.parse(fs.readFileSync(envFilepath, 'utf8'));
-
-    if (!rawEnv || typeof rawEnv !== 'object' || Array.isArray(rawEnv)) return [];
-
-    return Object.keys(rawEnv).sort((a, b) => a.localeCompare(b));
-};
-
 const collectManifestDiagnostics = ({
     controllers,
     routes,
@@ -228,6 +215,8 @@ export const writeCurrentProteumManifest = ({
     routes: TProteumManifest['routes'];
     layouts: TProteumManifestLayout[];
 }) => {
+    const envInspection = inspectProteumEnv(app.paths.root);
+
     const manifest: TProteumManifest = {
         version: 1,
         app: {
@@ -252,9 +241,19 @@ export const writeCurrentProteumManifest = ({
             reservedRouteSetupKeys: [...reservedRouteSetupKeys],
         },
         env: {
-            sourceFilepath: normalizeAbsolutePath(path.join(app.paths.root, 'env.yaml')),
-            loadedTopLevelKeys: getEnvTopLevelKeys(),
-            requiredTopLevelKeys: [...envRequiredTopLevelKeys],
+            source: 'process.env',
+            loadedVariableKeys: envInspection.loadedVariableKeys,
+            requiredVariables: envInspection.requiredVariables.map((variable) => ({
+                key: variable.key,
+                possibleValues: [...variable.possibleValues],
+                provided: variable.provided,
+            })),
+            resolved: {
+                name: app.env.name,
+                profile: app.env.profile,
+                routerPort: app.env.router.port,
+                routerCurrentDomain: app.env.router.currentDomain,
+            },
         },
         services,
         controllers,

package/cli/compiler/common/index.ts

@@ -80,7 +80,7 @@ export default function createCommonConfig(
                 APP_NAME: JSON.stringify(app.identity.web.title),
                 APP_OUTPUT_DIR: JSON.stringify(path.basename(app.outputPath(outputTarget))),
                 PROTEUM_DEV_EVENT_PORT: JSON.stringify(dev ? (app.devEventPort ?? null) : null),
-                PROTEUM_ROUTER_PORT_OVERRIDE: JSON.stringify(app.routerPortOverride ?? null),
+                PROTEUM_PORT_OVERRIDE: JSON.stringify(app.routerPortOverride ?? null),
             }),
 
             ...(dev ? [] : []),

package/cli/compiler/common/proteumManifest.ts

@@ -100,9 +100,19 @@ export type TProteumManifest = {
         reservedRouteSetupKeys: string[];
     };
     env: {
-        sourceFilepath: string;
-        loadedTopLevelKeys: string[];
-        requiredTopLevelKeys: string[];
+        source: string;
+        loadedVariableKeys: string[];
+        requiredVariables: {
+            key: string;
+            possibleValues: string[];
+            provided: boolean;
+        }[];
+        resolved: {
+            name: string;
+            profile: string;
+            routerPort: number;
+            routerCurrentDomain: string;
+        };
     };
     services: {
         app: TProteumManifestService[];

package/cli/presentation/commands.ts

@@ -202,7 +202,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'This command talks to the running app over the dev-only `__proteum/trace` HTTP endpoints.',
             'Traces are stored in a bounded in-memory buffer with payload summarization and sensitive-field redaction.',
-            'Use `--port` when the app is not running on the router port declared in `env.yaml`, or `--url` when the host itself is non-standard.',
+            'Use `--port` when the app is not running on the router port declared in `PORT`, or `--url` when the host itself is non-standard.',
         ],
         status: 'experimental',
     },

package/client/app/component.tsx

@@ -38,16 +38,9 @@ export default function App({ context }: { context: ClientContext }) {
             <DialogManager />
 
             {!layout ? (
-                <>
-                    {/* TODO: move to app, because here, we're not aware that the router service has been defined */}
-                    <RouterComponent service={context.Router} />
-                </>
+                <RouterComponent service={context.Router} />
             ) : (
-                <>
-                    {' '}
-                    {/* Same as router/components/Page.tsx */}
-                    <layout.Component {...layoutProps} />
-                </>
+                <layout.Component {...layoutProps} />
             )}
         </ReactClientContext.Provider>
     );

package/client/services/router/index.tsx

@@ -21,7 +21,6 @@ import BaseRouter, {
     TErrorRoute,
     TRouteOptions,
     TRouteModule,
-    TDomainsList,
     matchRoute,
     buildUrl,
 } from '@common/router';
@@ -136,7 +135,7 @@ export default class ClientRouter<
     // Context data
     public ssrRoutes = browserWindow.routes || [];
     public ssrContext = browserWindow.ssr;
-    public domains: TDomainsList = browserWindow.ssr?.domains || ({ current: window.location.origin } as TDomainsList);
+    public currentDomain = browserWindow.ssr?.currentDomain || window.location.origin;
     public context!: TRouterContext<this, this['app']>;
 
     public setLoading!: React.Dispatch<React.SetStateAction<boolean>>;
@@ -153,7 +152,7 @@ export default class ClientRouter<
     }
 
     public url = (path: string, params: {} = {}, absolute: boolean = true) =>
-        buildUrl(path, params, this.domains, absolute);
+        buildUrl(path, params, this.currentDomain, absolute);
 
     public go(url: string | number, data: {} = {}, opt: { newTab?: boolean } = {}) {
         // Error code

package/common/dev/requestTrace.ts

@@ -1,6 +1,7 @@
 export const traceCaptureModes = ['summary', 'resolve', 'deep'] as const;
 
 export type TTraceCaptureMode = (typeof traceCaptureModes)[number];
+type TTracePrimitive = string | number | boolean;
 
 export const traceEventTypes = [
     'request.start',
@@ -27,7 +28,7 @@ export const traceEventTypes = [
 export type TTraceEventType = (typeof traceEventTypes)[number];
 
 export type TTraceSummaryValue =
-    | PrimitiveValue
+    | TTracePrimitive
     | null
     | { kind: 'undefined' }
     | { kind: 'redacted'; reason: string }

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/request-tracing.md

@@ -19,6 +19,12 @@ 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
@@ -54,15 +60,14 @@ Use `deep` selectively. It is for one-off investigation, not continuous capture.
 
 ## Configuration
 
-Add trace settings in `env.yaml`:
+Set trace behavior with env vars:
 
-```yaml
-trace:
-  enable: true
-  requestsLimit: 200
-  eventsLimit: 800
-  capture: resolve
-  persistOnError: true
+```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:

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.1.0-3",
+	"version": "2.1.0-5",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/app/container/config.ts

@@ -12,10 +12,10 @@ import fs from 'fs-extra';
 import yaml from 'yaml';
 
 // Types
-import type { TDomainsList } from '@common/router';
-import type { TLogProfile } from './console';
+import { parseProteumEnvConfig, type TProteumLoadedEnvConfig } from '../../../common/env/proteumEnv';
 
-declare const PROTEUM_ROUTER_PORT_OVERRIDE: number | null;
+declare const PROTEUM_PORT_OVERRIDE: number | null;
+declare const BUILD_DATE: string;
 
 /*----------------------------------
 - TYPES
@@ -31,50 +31,8 @@ declare global {
     }
 }
 
-/*
-    name: server
-    profile: prod
-
-    router:
-        port: 80
-        domains:
-            current: 'https://recruiters.becrosspath.com'
-            recruiters: 'https://recruiters.becrosspath.com'
-            landing: 'https://becrosspath.com'
-            employers: 'https://employers.becrosspath.com'
-            candidates: 'https://candidates.becrosspath.com'
-            csm: 'https://csm.becrosspath.com'
-
-    database:
-        name: 'aws'
-        databases: [railway]
-        host: 'mysql-z7vp.railway.internal'
-        port: 3306
-        login: root
-        password: "GMnVsczoyYkyzwvVqDkMUOAIjVsumEev"
-
-    console:
-        enable: false
-        debug: false
-        bufferLimit: 10000
-        level: 'log'
-*/
-
 export type TEnvName = TEnvConfig['name'];
-export type TEnvConfig = {
-    name: 'local' | 'server';
-    profile: 'dev' | 'testing' | 'prod';
-
-    router: { port: number; domains: TDomainsList };
-    console: { enable: boolean; debug: boolean; bufferLimit: number; level: TLogProfile };
-    trace: {
-        enable: boolean;
-        requestsLimit: number;
-        eventsLimit: number;
-        capture: 'summary' | 'resolve' | 'deep';
-        persistOnError: boolean;
-    };
-};
+export type TEnvConfig = TProteumLoadedEnvConfig;
 
 type AppIdentityConfig = {
     name: string;
@@ -105,8 +63,7 @@ export type AppConfig = { env: Config.Env; identity: Config.Identity };
 const debug = false;
 
 const getRouterPortOverride = () => {
-    if (typeof PROTEUM_ROUTER_PORT_OVERRIDE !== 'undefined' && PROTEUM_ROUTER_PORT_OVERRIDE !== null)
-        return PROTEUM_ROUTER_PORT_OVERRIDE;
+    if (typeof PROTEUM_PORT_OVERRIDE !== 'undefined' && PROTEUM_PORT_OVERRIDE !== null) return PROTEUM_PORT_OVERRIDE;
 
     return undefined;
 };
@@ -127,23 +84,13 @@ export default class ConfigParser {
     }
 
     public env(): TEnvConfig {
-        // We assume that when we run 5htp dev, we're in local
-        // Otherwise, we're in production environment (docker)
-        debug && console.info('[app] Using environment:', process.env.NODE_ENV);
-        const envFileName = this.appDir + '/env.yaml';
-        const envFile = this.loadYaml(envFileName);
-        const routerPortOverride = getRouterPortOverride();
-        const traceConfig = envFile.trace || {};
+        debug && console.info('[app] Loading Proteum env vars from process.env');
+
         return {
-            ...envFile,
-            router: routerPortOverride === undefined ? envFile.router : { ...envFile.router, port: routerPortOverride },
-            trace: {
-                enable: traceConfig.enable ?? envFile.profile === 'dev',
-                requestsLimit: traceConfig.requestsLimit ?? 200,
-                eventsLimit: traceConfig.eventsLimit ?? 800,
-                capture: traceConfig.capture ?? 'resolve',
-                persistOnError: traceConfig.persistOnError ?? envFile.profile === 'dev',
-            },
+            ...parseProteumEnvConfig({
+                appDir: this.appDir,
+                routerPortOverride: getRouterPortOverride(),
+            }),
             version: BUILD_DATE,
         };
     }

package/server/app/container/console/index.ts

@@ -23,9 +23,10 @@ import type ServerRequest from '@server/services/router/request';
 - SERVICE CONFIG
 ----------------------------------*/
 
-export type TLogProfile = 'silly' | 'info' | 'warn' | 'error';
+export type TLogProfile = 'silly' | 'log' | 'info' | 'warn' | 'error';
 
 export type Config = { debug?: boolean; enable: boolean; bufferLimit: number; level: TLogProfile };
+export const defaultConsoleConfig: Config = { enable: false, debug: false, bufferLimit: 10000, level: 'log' };
 
 export type Hooks = {};
 

package/server/app/container/index.ts

@@ -14,7 +14,7 @@ import type Application from '..';
 import type { StartedServicesIndex } from '../service';
 import Services, { ServicesContainer } from '../service/container';
 import ConfigParser, { TEnvConfig } from './config';
-import Console from './console';
+import Console, { defaultConsoleConfig } from './console';
 import Trace from './trace';
 import type ServerRequest from '@server/services/router/request';
 
@@ -53,7 +53,7 @@ export class ApplicationContainer<TServicesIndex extends StartedServicesIndex =
         const configParser = new ConfigParser(this.path.root);
         this.Environment = configParser.env();
         this.Identity = configParser.identity();
-        this.Console = new Console(this, this.Environment.console);
+        this.Console = new Console(this, defaultConsoleConfig);
         this.Trace = new Trace(this, this.Environment.trace);
     }
 

package/server/services/router/index.ts

@@ -32,7 +32,6 @@ import BaseRouter, {
     defaultOptions,
     matchRoute,
     buildUrl,
-    TDomainsList,
 } from '@common/router';
 import type { TSsrUnresolvedRoute, TRegisterPageArgs } from '@common/router/contracts';
 import { buildRegex, getRegisterPageArgs } from '@common/router/register';
@@ -108,7 +107,7 @@ export type Config<
 
     disk?: string; // Disk driver ID
 
-    domains: TDomainsList;
+    currentDomain: string;
 
     http: HttpServiceConfig;
 
@@ -356,7 +355,7 @@ export default class ServerRouter<
     }
 
     public url = (path: string, params: {} = {}, absolute: boolean = true) =>
-        buildUrl(path, params, this.config.domains, absolute);
+        buildUrl(path, params, this.config.currentDomain, absolute);
 
     /*----------------------------------
     - REGISTER

package/server/services/router/response/index.ts

@@ -14,7 +14,7 @@ import express from 'express';
 import context from '@server/context';
 import type { AnyRouterService, default as ServerRouter, TServerRouter, TAnyRouter } from '@server/services/router';
 import ServerRequest from '@server/services/router/request';
-import { TMatchedRoute, TRoute, TAnyRoute, TDomainsList } from '@common/router';
+import { TMatchedRoute, TRoute, TAnyRoute } from '@common/router';
 import { NotFound, Forbidden, Anomaly } from '@common/errors';
 import BaseResponse, { TResponseData } from '@common/router/response';
 import { splitRouteSetupResult } from '@common/router/pageSetup';
@@ -38,7 +38,7 @@ export type TBasicSSrData = {
     request: { data: TObjetDonnees; id: string };
     page: { chunkId: string; data?: TObjetDonnees };
     user: TBasicUser | null;
-    domains: TDomainsList;
+    currentDomain: string;
 };
 
 type TServerRouterApplication<TRouter extends TServerRouter> =
@@ -277,7 +277,7 @@ export default class ServerResponse<
             request: { id: this.request.id, data: this.request.data },
             page: { chunkId: page.chunkId || '', data: page.data },
             user: this.request.user,
-            domains: this.router.config.domains,
+            currentDomain: this.router.config.currentDomain,
             ...customSsrData,
         };
     }

package/types/global/utils.d.ts

@@ -43,24 +43,17 @@ declare type PrimitiveValue = string | number | boolean;
 /*type TEnvConfig = {
     name: 'local' | 'server',
     profile: 'dev' | 'testing' | 'prod',
-    
+
     router: {
         port: number,
-        domains: TDomainsList
-    },
-    database: {
-        name: string,
-        databases: string[],
-        host: string,
-        port: number,
-        login: string,
-        password: string,
+        currentDomain: string
     },
-    console: {
+    trace: {
         enable: boolean,
-        debug: boolean,
-        bufferLimit: number,
-        level: TLogProfile,
+        requestsLimit: number,
+        eventsLimit: number,
+        capture: 'summary' | 'resolve' | 'deep',
+        persistOnError: boolean,
     },
 }*/