proteum 2.5.9 → 2.5.11

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/doc-anchors.test.cjs

@@ -0,0 +1,115 @@
+const assert = require('node:assert/strict');
+
+const {
+    buildDocAnchorGroups,
+    collectDocAnchors,
+    hasDocAnchorTag,
+    isPathDocAnchorTag,
+    parseDocAnchorComment,
+} = require('../docAnchors.js');
+
+test('doc anchor parser reads every supported tag from a block comment', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @docs docs/features/search
+         * @adr  ADR-0004
+         * @fix  docs/fixes/2026-06-09-keyword-search-semantic-order.md
+         * @rule Composite ordering stays alias-aware.
+         */
+        export default definePageRoute({ path: '/browse' });
+    `);
+
+    assert.deepEqual(groups.docs, ['docs/features/search']);
+    assert.deepEqual(groups.adr, ['ADR-0004']);
+    assert.deepEqual(groups.fix, ['docs/fixes/2026-06-09-keyword-search-semantic-order.md']);
+    assert.deepEqual(groups.rules, ['Composite ordering stays alias-aware.']);
+});
+
+test('doc anchor parser joins multi-line rule invariants into one value', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @rule Composite ordering stays alias-aware.
+         *       Never rewrite ORDER BY with regex.
+         */
+    `);
+
+    assert.deepEqual(groups.rules, ['Composite ordering stays alias-aware. Never rewrite ORDER BY with regex.']);
+});
+
+test('doc anchor parser reports the line each anchor sits on', () => {
+    const groups = collectDocAnchors(['const a = 1;', '', '/**', ' * @docs docs/features/search', ' */'].join('\n'));
+
+    assert.equal(groups.entries.length, 1);
+    assert.equal(groups.entries[0].line, 4);
+});
+
+test('doc anchor parser ignores unrelated jsdoc tags', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @param input The request payload.
+         * @returns The parsed row.
+         */
+    `);
+
+    assert.equal(groups.entries.length, 0);
+});
+
+test('doc anchor parser stops a value at a blank comment line', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @rule Never rewrite ORDER BY with regex.
+         *
+         * Unrelated prose that must not join the invariant.
+         */
+    `);
+
+    assert.deepEqual(groups.rules, ['Never rewrite ORDER BY with regex.']);
+});
+
+test('doc anchor parser collects anchors from several comments and drops duplicates', () => {
+    const groups = collectDocAnchors(`
+        /** @docs docs/features/search */
+        const first = 1;
+        /** @docs docs/features/search */
+        /** @docs docs/features/billing */
+        const second = 2;
+    `);
+
+    assert.deepEqual(groups.docs, ['docs/features/search', 'docs/features/billing']);
+});
+
+test('doc anchor parser ignores tags with no value', () => {
+    const groups = collectDocAnchors(`
+        /**
+         * @docs
+         * @rule
+         */
+    `);
+
+    assert.equal(groups.entries.length, 0);
+});
+
+test('doc anchor parser caps how much source it scans', () => {
+    const padding = `${'// filler\n'.repeat(200)}`;
+    const source = `${padding}/** @docs docs/features/search */`;
+
+    assert.equal(collectDocAnchors(source, { maxLength: 50 }).entries.length, 0);
+    assert.equal(collectDocAnchors(source).docs.length, 1);
+});
+
+test('doc anchor parser tolerates empty and missing input', () => {
+    assert.equal(collectDocAnchors('').entries.length, 0);
+    assert.equal(collectDocAnchors(undefined).entries.length, 0);
+    assert.equal(parseDocAnchorComment(undefined).length, 0);
+});
+
+test('doc anchor helpers expose the tag contract', () => {
+    const groups = buildDocAnchorGroups(parseDocAnchorComment('* @docs docs/features/search', 1));
+
+    assert.equal(hasDocAnchorTag(groups, 'docs'), true);
+    assert.equal(hasDocAnchorTag(groups, 'rule'), false);
+    assert.equal(isPathDocAnchorTag('docs'), true);
+    assert.equal(isPathDocAnchorTag('fix'), true);
+    assert.equal(isPathDocAnchorTag('adr'), false);
+    assert.equal(isPathDocAnchorTag('rule'), false);
+});

package/tests/docs-check.test.cjs

@@ -0,0 +1,138 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+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');
+require('../cli/context.ts');
+
+const { buildDocsCheckReport } = require('../cli/commands/docs.ts');
+
+const createRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-docs-check-'));
+
+const writeFile = (root, filepath, content) => {
+    const full = path.join(root, filepath);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+};
+
+const kinds = (report, kind) => report.findings.filter((finding) => finding.kind === kind);
+
+test('docs check accepts anchors that resolve against the corpus', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    const report = buildDocsCheckReport(root);
+
+    assert.equal(kinds(report, 'unresolved-anchor').length, 0);
+    assert.equal(kinds(report, 'orphan-feature-pack').length, 0);
+    assert.equal(report.anchoredFiles, 1);
+});
+
+test('docs check reports an anchor pointing at a deleted document', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/deleted\n */\nexport default {};\n',
+    );
+
+    const report = buildDocsCheckReport(root);
+    const unresolved = kinds(report, 'unresolved-anchor');
+
+    assert.equal(unresolved.length, 1);
+    assert.equal(unresolved[0].detail, '@docs docs/features/deleted');
+});
+
+test('docs check resolves anchors from an app that owns a nested docs directory', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'apps/product/docs/fixes/local.md', '# Local\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    assert.equal(kinds(buildDocsCheckReport(root), 'unresolved-anchor').length, 0);
+});
+
+test('docs check resolves anchors aimed at the repo corpus when run from an app root', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    // Running from the app root must not orphan an anchor that points at the
+    // repository-level corpus one directory up.
+    const report = buildDocsCheckReport(path.join(root, 'apps', 'product'));
+
+    assert.equal(kinds(report, 'unresolved-anchor').length, 0);
+    assert.equal(report.anchoredFiles, 1);
+});
+
+test('docs check reports a fix note whose invariant no code anchors', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/fixes/2026-06-14-watchdog.md', '# Fix\n\n## Agent warning\n\nDo not remove the guards.\n');
+    writeFile(root, 'apps/daemon/src/rdap.ts', 'export default {};\n');
+
+    const unanchored = kinds(buildDocsCheckReport(root), 'unanchored-fix-note');
+
+    assert.equal(unanchored.length, 1);
+    assert.equal(unanchored[0].subject, 'docs/fixes/2026-06-14-watchdog.md');
+});
+
+test('docs check clears a fix note once code anchors it', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/fixes/2026-06-14-watchdog.md', '# Fix\n\n## Agent warning\n\nDo not remove the guards.\n');
+    writeFile(
+        root,
+        'apps/daemon/src/rdap.ts',
+        '/**\n * @fix  docs/fixes/2026-06-14-watchdog.md\n * @rule Do not remove the guards.\n */\nexport default {};\n',
+    );
+
+    assert.equal(kinds(buildDocsCheckReport(root), 'unanchored-fix-note').length, 0);
+});
+
+test('docs check reports a feature pack that no code points at', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'docs/features/orphan/README.md', '# Orphan\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    const orphans = kinds(buildDocsCheckReport(root), 'orphan-feature-pack');
+
+    assert.deepEqual(orphans.map((finding) => finding.subject), ['docs/features/orphan']);
+});
+
+test('docs check ignores generated and vendored directories', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(
+        root,
+        'node_modules/some-package/index.ts',
+        '/**\n * @docs docs/features/nope\n */\nexport default {};\n',
+    );
+    writeFile(root, 'apps/product/var/generated.ts', '/**\n * @docs docs/features/nope\n */\nexport default {};\n');
+
+    const report = buildDocsCheckReport(root);
+
+    assert.equal(kinds(report, 'unresolved-anchor').length, 0);
+    assert.equal(report.anchoredFiles, 0);
+});