proteum 2.5.8 → 2.5.10

package/common/dev/session.ts

@@ -22,3 +22,35 @@ export type TDevSessionStartResponse = {
 export type TDevSessionErrorResponse = {
     error: string;
 };
+
+export const devSessionLoginPath = '/__proteum/session/login';
+export const devSessionStartPath = '/__proteum/session/start';
+
+export const normalizeDevSessionRedirectPath = (value: string): string => {
+    const redirect = value.trim() || '/';
+    if (!redirect.startsWith('/') || redirect.startsWith('//') || redirect.startsWith('/\\') || /[\r\n]/.test(redirect)) {
+        throw new Error('Redirect must be a local absolute path such as /dashboard.');
+    }
+
+    return redirect;
+};
+
+export const buildDevSessionLoginUrl = ({
+    baseUrl,
+    email,
+    redirect,
+    role,
+}: {
+    baseUrl: string;
+    email: string;
+    redirect: string;
+    role?: string;
+}): string => {
+    const params = new URLSearchParams({
+        email,
+        redirect: normalizeDevSessionRedirectPath(redirect),
+    });
+    if (role?.trim()) params.set('role', role.trim());
+
+    return `${baseUrl.replace(/\/+$/, '')}${devSessionLoginPath}?${params.toString()}`;
+};

package/common/errors/index.tsx

@@ -36,7 +36,6 @@ type TErrorDetails = {
 export type ServerBug = {
     // Context
     hash: string;
-    isDuplicate: boolean;
     date: Date; // Timestamp
     channelType?: string;
     channelId?: string;

package/docs/agent-routing.md

@@ -96,11 +96,11 @@ Standard triggered reads:
 - Worktree Preflight (`cwd` inside `/.codex/worktrees/`, newly created Proteum worktree, or before editing in a Codex worktree): root contract fallback, then `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command, `npx proteum runtime status`, and tracked `npx proteum dev` for runtime-visible work.
 - Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): root contract fallback.
 - Before git writes after a bug fix, behavior change, decision change, or docs-relevant production change: `DOCUMENTATION.md`.
-- Before finishing production code changes: root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, and touched area `AGENTS.md`.
+- Before finishing production code changes: root contract fallback, `DOCUMENTATION.md`, `CODING_STYLE.md`, and touched area `AGENTS.md`, then the `CODING_STYLE.md` self-check on the final diff; a non-obvious decision without a why-comment is a defect.
 - Runtime-visible, request-time, router, SSR, browser, or controller behavior: root contract fallback plus `diagnostics.md`.
 - Bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes: `DOCUMENTATION.md`.
 - Non-trivial feature, product, business-rule, UX, copy, or docs changes: `DOCUMENTATION.md`.
-- Implementation edits: `CODING_STYLE.md` plus the matching area file from the routing table.
+- Implementation edits: `CODING_STYLE.md` plus the matching area file from the routing table; record non-obvious decisions, workarounds, and constraints as why-comments while editing.
 
 `workflow_start`, `orient`, `route_candidates`, and MCP `instructions_resolve` should promote obvious triggered files into selected instruction previews; ambiguous conditional reads can remain in `readWhen`.
 

package/package.json

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

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

@@ -6,7 +6,6 @@
 import { serialize } from 'v8';
 import { formatWithOptions } from 'util';
 import md5 from 'md5';
-import dayjs from 'dayjs';
 import stringify from 'fast-safe-stringify';
 
 // Npm
@@ -178,7 +177,6 @@ export default class Console {
     public logger!: Logger<ILogObj>;
     // Buffers
     public logs: TJsonLog[] = [];
-    private reported: { [hash: string]: { times: number; last: Date } } = {};
 
     /*----------------------------------
     - LIFECYCLE
@@ -371,24 +369,9 @@ export default class Console {
         // Genertae unique error hash
         const hash = md5(inspection.stacktraces[0]);
 
-        // Don't send the same error twice in a row (avoid email spamming)
-        const lastReport = this.reported[hash];
-        let isDuplicate = false;
-        if (lastReport === undefined) {
-            this.reported[hash] = { times: 0, last: new Date() };
-
-            // If error older than 1 day
-        } else if (dayjs(now).diff(dayjs(lastReport.last), 'day') > 1) {
-            lastReport.times++;
-            lastReport.last = now;
-        } else {
-            isDuplicate = true;
-        }
-
         const bugReport: ServerBug = {
             // Context
             hash: hash,
-            isDuplicate,
             date: now,
             channelType,
             channelId,

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

@@ -30,7 +30,13 @@ import type { TServerRouter } from '..';
 import type { TDevConsoleLogLevel } from '@common/dev/console';
 import type { TPerfGroupBy } from '@common/dev/performance';
 import type { TServerReadyConnectedProject } from '@common/dev/serverHotReload';
-import type { TDevSessionStartResponse, TDevSessionUserSummary } from '@common/dev/session';
+import {
+    devSessionLoginPath,
+    devSessionStartPath,
+    normalizeDevSessionRedirectPath,
+    type TDevSessionStartResponse,
+    type TDevSessionUserSummary,
+} from '@common/dev/session';
 import { serverHotReloadMessageType } from '@common/dev/serverHotReload';
 import { explainSectionNames } from '@common/dev/diagnostics';
 import {
@@ -88,6 +94,16 @@ type TDevSessionAuthService = {
     createSession: (session: { email: string }, request: { id: string; res: express.Response }) => string;
     decodeSession: (session: { email: string }, req: express.Request) => Promise<TBasicUser | null>;
 };
+type TDevSessionResult =
+    | {
+          ok: true;
+          response: TDevSessionStartResponse;
+      }
+    | {
+          ok: false;
+          error: string;
+          statusCode: number;
+      };
 
 const createContentSecurityPolicy = (config: Config['csp']): TContentSecurityPolicyOptions => {
     const directives: TContentSecurityPolicyDirectives = {
@@ -177,6 +193,77 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
         };
     }
 
+    private getSingleQueryValue(value: express.Request['query'][string]): string {
+        if (typeof value === 'string') return value.trim();
+        if (Array.isArray(value) && value.length === 1 && typeof value[0] === 'string') return value[0].trim();
+        return '';
+    }
+
+    private normalizeDevSessionRedirect(value: express.Request['query'][string]): string {
+        try {
+            return normalizeDevSessionRedirectPath(this.getSingleQueryValue(value));
+        } catch {
+            return '';
+        }
+    }
+
+    private isLocalDevSessionRequest(req: express.Request): boolean {
+        const hostname = req.hostname.toLowerCase();
+        return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+    }
+
+    private async createDevSessionResponse({
+        email,
+        req,
+        requiredRole,
+        res,
+        source,
+    }: {
+        email: string;
+        req: express.Request;
+        requiredRole: string;
+        res: express.Response;
+        source: 'login' | 'start';
+    }): Promise<TDevSessionResult> {
+        if (!email) return { ok: false, statusCode: 400, error: 'Email is required.' };
+
+        const auth = this.resolveDevSessionAuthService();
+        const user = await auth.decodeSession({ email }, req);
+
+        if (!user) return { ok: false, statusCode: 404, error: `No user could be resolved for "${email}".` };
+        if (requiredRole && !user.roles.includes(requiredRole)) {
+            return {
+                ok: false,
+                statusCode: 403,
+                error: `User "${email}" does not have required role "${requiredRole}".`,
+            };
+        }
+
+        const token = auth.createSession(
+            { email },
+            {
+                id: `proteum-session-${source}:${Date.now()}`,
+                res,
+            },
+        );
+        const issuedAt = new Date().toISOString();
+        const expiresAt = new Date(Date.now() + auth.config.jwt.expiration).toISOString();
+
+        return {
+            ok: true,
+            response: {
+                user: this.summarizeDevSessionUser(user),
+                session: {
+                    token,
+                    cookieName: 'authorization',
+                    expiresInMs: auth.config.jwt.expiration,
+                    issuedAt,
+                    expiresAt,
+                },
+            },
+        };
+    }
+
     private async verifyConnectedProjectsBeforeStart(): Promise<TServerReadyConnectedProject[]> {
         const verifiedConnectedProjects: TServerReadyConnectedProject[] = [];
 
@@ -766,50 +853,60 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
             }
         });
 
-        routes.post('/__proteum/session/start', async (req, res) => {
-            const email = typeof req.body?.email === 'string' ? req.body.email.trim() : '';
-            const requiredRole = typeof req.body?.role === 'string' ? req.body.role.trim() : '';
+        routes.get(devSessionLoginPath, async (req, res) => {
+            if (!this.isLocalDevSessionRequest(req)) {
+                res.status(403).send('Proteum session login is only available from localhost.');
+                return;
+            }
 
-            if (!email) {
-                res.status(400).json({ error: 'Email is required.' });
+            const email = this.getSingleQueryValue(req.query.email);
+            const requiredRole = this.getSingleQueryValue(req.query.role);
+            const redirect = this.normalizeDevSessionRedirect(req.query.redirect);
+
+            if (!redirect) {
+                res.status(400).send('Redirect must be a local absolute path.');
                 return;
             }
 
             try {
-                const auth = this.resolveDevSessionAuthService();
-                const user = await auth.decodeSession({ email }, req);
+                const result = await this.createDevSessionResponse({
+                    email,
+                    req,
+                    requiredRole,
+                    res,
+                    source: 'login',
+                });
 
-                if (!user) {
-                    res.status(404).json({ error: `No user could be resolved for "${email}".` });
+                if (!result.ok) {
+                    res.status(result.statusCode).send(result.error);
                     return;
                 }
 
-                if (requiredRole && !user.roles.includes(requiredRole)) {
-                    res.status(403).json({ error: `User "${email}" does not have required role "${requiredRole}".` });
+                res.redirect(302, redirect);
+            } catch (error) {
+                res.status(500).send(error instanceof Error ? error.message : String(error));
+            }
+        });
+
+        routes.post(devSessionStartPath, async (req, res) => {
+            const email = typeof req.body?.email === 'string' ? req.body.email.trim() : '';
+            const requiredRole = typeof req.body?.role === 'string' ? req.body.role.trim() : '';
+
+            try {
+                const result = await this.createDevSessionResponse({
+                    email,
+                    req,
+                    requiredRole,
+                    res,
+                    source: 'start',
+                });
+
+                if (!result.ok) {
+                    res.status(result.statusCode).json({ error: result.error });
                     return;
                 }
 
-                const token = auth.createSession(
-                    { email },
-                    {
-                        id: `proteum-session:${Date.now()}`,
-                        res,
-                    },
-                );
-                const issuedAt = new Date().toISOString();
-                const expiresAt = new Date(Date.now() + auth.config.jwt.expiration).toISOString();
-                const response: TDevSessionStartResponse = {
-                    user: this.summarizeDevSessionUser(user),
-                    session: {
-                        token,
-                        cookieName: 'authorization',
-                        expiresInMs: auth.config.jwt.expiration,
-                        issuedAt,
-                        expiresAt,
-                    },
-                };
-
-                res.json(response);
+                res.json(result.response);
             } catch (error) {
                 res.status(500).json({ error: error instanceof Error ? error.message : String(error) });
             }

package/tests/agents-utils.test.cjs

@@ -108,10 +108,6 @@ test('project instruction sources require unit tests for applicable production c
         fs.readFileSync(path.join(projectAgentsRoot, 'AGENTS.md'), 'utf8'),
         /production changes must always add or update focused unit tests/,
     );
-    assert.match(
-        fs.readFileSync(path.join(projectAgentsRoot, 'root', 'AGENTS.md'), 'utf8'),
-        /always add or update focused unit tests/,
-    );
     assert.match(
         fs.readFileSync(path.join(projectAgentsRoot, 'tests', 'AGENTS.md'), 'utf8'),
         /For every production change, add or update focused unit tests/,

package/tests/dev-session-login-url.test.cjs

@@ -0,0 +1,33 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+const {
+    buildDevSessionLoginUrl,
+    normalizeDevSessionRedirectPath,
+} = require('../common/dev/session.ts');
+
+test('buildDevSessionLoginUrl creates a local browser handoff URL', () => {
+    const url = buildDevSessionLoginUrl({
+        baseUrl: 'http://127.0.0.1:3020/',
+        email: 'contact@gaetan-legac.fr',
+        redirect: '/projects/project-123?tab=radar',
+        role: 'GOD',
+    });
+
+    assert.equal(
+        url,
+        'http://127.0.0.1:3020/__proteum/session/login?email=contact%40gaetan-legac.fr&redirect=%2Fprojects%2Fproject-123%3Ftab%3Dradar&role=GOD',
+    );
+});
+
+test('normalizeDevSessionRedirectPath rejects external redirects', () => {
+    assert.throws(() => normalizeDevSessionRedirectPath('https://example.com'), /local absolute path/);
+    assert.throws(() => normalizeDevSessionRedirectPath('//example.com'), /local absolute path/);
+    assert.throws(() => normalizeDevSessionRedirectPath('/\nadmin'), /local absolute path/);
+    assert.equal(normalizeDevSessionRedirectPath(''), '/');
+});

package/tests/server-externals.test.cjs

@@ -0,0 +1,67 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+
+require('ts-node/register/transpile-only');
+
+const {
+    isFrameworkSourceContext,
+    resolveServerExternalRequest,
+} = require('../cli/compiler/server/externals.ts');
+
+test('server external resolution prefers app dependencies outside framework source', () => {
+    const optionsSeen = [];
+    const resolved = resolveServerExternalRequest({
+        context: '/repo/node_modules/@klair/usecases/src/mcp/groups/workers',
+        frameworkRoots: ['/framework/core'],
+        request: '@prisma/client',
+        resolveRequest: (request, options) => {
+            optionsSeen.push(options);
+            assert.equal(request, '@prisma/client');
+            return options.preferApp
+                ? '/repo/node_modules/@prisma/client/default.js'
+                : '/framework/core/node_modules/@prisma/client/default.js';
+        },
+    });
+
+    assert.equal(resolved, '/repo/node_modules/@prisma/client/default.js');
+    assert.deepEqual(optionsSeen, [{ preferApp: true }]);
+});
+
+test('server external resolution prefers framework dependencies for framework source', () => {
+    const resolved = resolveServerExternalRequest({
+        context: '/framework/core/server',
+        frameworkRoots: ['/framework/core'],
+        request: 'express',
+        resolveRequest: (request, options) => {
+            assert.equal(request, 'express');
+            return options.preferApp
+                ? '/repo/node_modules/express/index.js'
+                : '/framework/core/node_modules/express/index.js';
+        },
+    });
+
+    assert.equal(resolved, '/framework/core/node_modules/express/index.js');
+});
+
+test('server external resolution falls back to the bare request when resolution fails', () => {
+    const resolved = resolveServerExternalRequest({
+        context: '/repo/server',
+        frameworkRoots: ['/framework/core'],
+        request: 'optional-peer',
+        resolveRequest: () => {
+            throw new Error('missing');
+        },
+    });
+
+    assert.equal(resolved, 'optional-peer');
+});
+
+test('framework source context matching handles exact and nested roots', () => {
+    assert.equal(isFrameworkSourceContext('/framework/core', ['/framework/core']), true);
+    assert.equal(isFrameworkSourceContext('/framework/core/server', ['/framework/core']), true);
+    assert.equal(isFrameworkSourceContext('/repo/node_modules/@klair/usecases', ['/framework/core']), false);
+});

package/tests/ui-singletons.test.cjs

@@ -0,0 +1,104 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+
+require('ts-node/register/transpile-only');
+
+const {
+    isUiSingletonRequest,
+    resolveUiSingletonAliases,
+    resolveUiSingletonServerExternalRequest,
+} = require('../cli/compiler/common/uiSingletons.ts');
+
+test('UI singleton matcher includes React and Preact runtime packages', () => {
+    assert.equal(isUiSingletonRequest('preact'), true);
+    assert.equal(isUiSingletonRequest('preact/hooks'), true);
+    assert.equal(isUiSingletonRequest('preact-render-to-string'), true);
+    assert.equal(isUiSingletonRequest('react'), true);
+    assert.equal(isUiSingletonRequest('react-dom/client'), true);
+});
+
+test('UI singleton matcher does not match unrelated React-prefixed packages', () => {
+    assert.equal(isUiSingletonRequest('react-number-format'), false);
+    assert.equal(isUiSingletonRequest('reactive-stream'), false);
+    assert.equal(isUiSingletonRequest('@radix-ui/react-popover'), false);
+    assert.equal(isUiSingletonRequest(undefined), false);
+});
+
+test('UI singleton aliases resolve React imports to Preact runtime requests', () => {
+    const seenRequests = [];
+    const seenPackageRoots = [];
+    const aliases = resolveUiSingletonAliases({
+        resolvePackageRoot: (packageName) => {
+            seenPackageRoots.push(packageName);
+            return `/app/node_modules/${packageName}`;
+        },
+        resolveRequest: (request) => {
+            seenRequests.push(request);
+            return `/app/node_modules/${request}`;
+        },
+    });
+
+    assert.equal(aliases['preact'], '/app/node_modules/preact');
+    assert.equal(aliases['preact$'], '/app/node_modules/preact');
+    assert.equal(aliases['preact/hooks$'], '/app/node_modules/preact/hooks');
+    assert.equal(aliases['react$'], '/app/node_modules/preact/compat');
+    assert.equal(aliases['react-dom$'], '/app/node_modules/preact/compat');
+    assert.equal(aliases['react-dom/client$'], '/app/node_modules/preact/compat/client');
+    assert.equal(aliases['react/jsx-runtime$'], '/app/node_modules/preact/jsx-runtime');
+    assert.equal(aliases['preact-render-to-string'], '/app/node_modules/preact-render-to-string');
+    assert.equal(aliases['preact-render-to-string$'], '/app/node_modules/preact-render-to-string');
+    assert.deepEqual(seenPackageRoots, ['preact', 'preact-render-to-string']);
+    assert.equal(
+        Object.keys(aliases).indexOf('preact/jsx-dev-runtime$') < Object.keys(aliases).indexOf('preact'),
+        true,
+    );
+    assert.deepEqual(
+        seenRequests.filter((request) => request === 'preact-render-to-string'),
+        ['preact-render-to-string'],
+    );
+});
+
+test('UI singleton server externals resolve Preact and React compat requests from the app', () => {
+    const seenRequests = [];
+    const resolveRequest = (request) => {
+        seenRequests.push(request);
+        return `/app/node_modules/${request}`;
+    };
+
+    assert.equal(resolveUiSingletonServerExternalRequest('preact', resolveRequest), '/app/node_modules/preact');
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('preact/hooks', resolveRequest),
+        '/app/node_modules/preact/hooks',
+    );
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('react', resolveRequest),
+        '/app/node_modules/preact/compat',
+    );
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('react/jsx-runtime', resolveRequest),
+        '/app/node_modules/preact/jsx-runtime',
+    );
+    assert.equal(
+        resolveUiSingletonServerExternalRequest('react-dom/client', resolveRequest),
+        '/app/node_modules/preact/compat/client',
+    );
+    assert.deepEqual(seenRequests, [
+        'preact',
+        'preact/hooks',
+        'preact/compat',
+        'preact/jsx-runtime',
+        'preact/compat/client',
+    ]);
+});
+
+test('UI singleton server externals keep the SSR renderer compiled', () => {
+    const resolveRequest = () => {
+        throw new Error('should not resolve');
+    };
+
+    assert.equal(resolveUiSingletonServerExternalRequest('preact-render-to-string', resolveRequest), undefined);
+});

package/agents/project/app-root/AGENTS.md

@@ -1,14 +0,0 @@
-# Proteum App-Root Addendum
-
-This file is the app-root-only addendum for a Proteum app that lives inside a larger monorepo.
-Keep the reusable Proteum contract in the nearest ancestor root `AGENTS.md`, and keep this file only for instructions that depend on the current directory being the Proteum app root.
-Role: keep only app-root workflow and local project-semantic rules here.
-Do not put here: reusable Proteum architecture contracts, shared verification rules, documentation-driven coding workflow, diagnostics workflow, optimization checklists, coding-style details, or area-specific rules already covered by broader `AGENTS.md` files or the root-level `DOCUMENTATION.md`, `diagnostics.md`, `optimizations.md`, and `CODING_STYLE.md`.
-
-## App-Root Triggers
-
-- If you are working in a newly created Proteum worktree, before following the rest of these instructions:
-  - Run `npx proteum worktree init --source <source-app-root>`.
-  - Read and acknowledge the applicable `AGENTS.md` files.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link. If `proteum dev` reports blocked instruction paths, resolve them before continuing.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.