proteum 2.5.9 → 2.5.11

package/common/dev/mcpPayloads.ts

@@ -45,8 +45,34 @@ type TNodePath = {
     resolve: (...segments: string[]) => string;
 };
 
+type TDocAnchorEntry = {
+    line: number;
+    tag: string;
+    value: string;
+};
+
+type TDocAnchorGroups = {
+    adr: string[];
+    docs: string[];
+    entries: TDocAnchorEntry[];
+    fix: string[];
+    rules: string[];
+};
+
+type TDocAnchorsModule = {
+    collectDocAnchors: (sourceText: string, options?: { maxLength?: number }) => TDocAnchorGroups;
+};
+
+export type TOwnerDocAnchors = {
+    adr?: string[];
+    docs?: string[];
+    fix?: string[];
+    rules?: string[];
+};
+
 const maxInstructionPreviewLength = 360;
 const maxTextLength = 220;
+const maxOwnerDocAnchorRules = 3;
 const nodeRequire = (() => {
     try {
         return eval('require') as NodeRequire;
@@ -56,6 +82,23 @@ const nodeRequire = (() => {
 })();
 const fs = nodeRequire ? (nodeRequire('fs') as TNodeFs) : undefined;
 const path = nodeRequire ? (nodeRequire('path') as TNodePath) : undefined;
+const docAnchors = (() => {
+    if (!nodeRequire) return undefined;
+
+    // Relative resolution covers the linked framework checkout; the package
+    // specifier covers an installed copy whose transpiled layout may differ.
+    // Owner payloads stay valid without anchors, so a resolution failure
+    // degrades to the previous behaviour instead of breaking the tool.
+    for (const specifier of ['../../docAnchors.js', 'proteum/docAnchors.js']) {
+        try {
+            return nodeRequire(specifier) as TDocAnchorsModule;
+        } catch (_error) {
+            continue;
+        }
+    }
+
+    return undefined;
+})();
 
 const hasNodeFs = () => fs !== undefined;
 const hasNodePath = () => path !== undefined;
@@ -217,14 +260,49 @@ export const summarizeManifest = (manifest: TProteumManifest | undefined) => {
     };
 };
 
-const compactOwnerMatch = (match: TExplainOwnerResponse['matches'][number]) => ({
-    kind: match.kind,
-    label: match.label,
-    score: match.score,
-    scope: match.scopeLabel,
-    origin: match.originHint,
-    source: match.source,
-});
+/**
+ * Resolve the doc anchors declared in an owner's source file.
+ *
+ * This is what makes the documentation corpus discoverable at the point an
+ * agent asks who owns a route: the governing feature pack, decision record and
+ * fix note arrive with the owner instead of costing a separate search.
+ */
+export const readOwnerDocAnchors = (filepath?: string): TOwnerDocAnchors | undefined => {
+    if (!filepath || !docAnchors || fs === undefined || !fileExists(filepath)) return undefined;
+
+    let groups: TDocAnchorGroups;
+    try {
+        groups = docAnchors.collectDocAnchors(fs.readFileSync(filepath, 'utf8'));
+    } catch (_error) {
+        return undefined;
+    }
+
+    if (groups.entries.length === 0) return undefined;
+
+    return {
+        docs: groups.docs.length > 0 ? groups.docs : undefined,
+        adr: groups.adr.length > 0 ? groups.adr : undefined,
+        fix: groups.fix.length > 0 ? groups.fix : undefined,
+        rules:
+            groups.rules.length > 0
+                ? compactList(groups.rules, maxOwnerDocAnchorRules).map((rule) => truncateForMcp(rule))
+                : undefined,
+    };
+};
+
+const compactOwnerMatch = (match: TExplainOwnerResponse['matches'][number]) => {
+    const docs = readOwnerDocAnchors(match.source.filepath);
+
+    return {
+        kind: match.kind,
+        label: match.label,
+        score: match.score,
+        scope: match.scopeLabel,
+        origin: match.originHint,
+        source: match.source,
+        ...(docs ? { docs } : {}),
+    };
+};
 
 const compactDiagnostic = (diagnostic: TDoctorResponse['diagnostics'][number]) => ({
     level: diagnostic.level,

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/docAnchors.js

@@ -0,0 +1,135 @@
+/*
+ * Shared doc-anchor contract.
+ *
+ * A doc anchor ties a source file to the durable documentation that governs it,
+ * so an agent editing the file sees the governing rule without first reading the
+ * whole documentation corpus.
+ *
+ * Supported tags, written in any leading block comment:
+ *
+ *   @docs docs/features/search
+ *   @adr  ADR-0004
+ *   @fix  docs/fixes/2026-06-09-keyword-search-semantic-order.md
+ *   @rule Composite ordering stays alias-aware. Never rewrite ORDER BY with regex.
+ *
+ * `@docs`, `@adr` and `@fix` are pointers resolved by the MCP owner payloads.
+ * `@rule` carries the one-line invariant inline, where an agent cannot miss it.
+ *
+ * This module is plain CommonJS with no dependencies because both the ESLint
+ * rules and the TypeScript MCP payload builder load it. Keep it that way so the
+ * lint surface and the agent-facing surface can never disagree on the format.
+ */
+
+const docAnchorTags = ['docs', 'adr', 'fix', 'rule'];
+const pathDocAnchorTags = ['docs', 'fix'];
+const maxDocAnchorScanLength = 64 * 1024;
+const minDocAnchorRuleLength = 8;
+
+const blockCommentPattern = /\/\*[\s\S]*?\*\//g;
+const commentGutterPattern = /^\s*\*+[ \t]?/;
+const tagPattern = /^@([a-zA-Z][\w-]*)[ \t]*(.*)$/;
+
+const countLinesBefore = (text, index) => {
+    let line = 1;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        if (text[cursor] === '\n') line += 1;
+    }
+
+    return line;
+};
+
+const stripCommentGutter = (line) => line.replace(commentGutterPattern, '').trim();
+
+const isDocAnchorTag = (tag) => docAnchorTags.includes(tag);
+const isPathDocAnchorTag = (tag) => pathDocAnchorTags.includes(tag);
+
+/**
+ * Parse the inner text of a single block comment.
+ *
+ * `startLine` is the 1-based line the comment opens on, so reported entries
+ * point at the exact anchor line rather than the top of the file.
+ */
+const parseDocAnchorComment = (commentValue, startLine = 1) => {
+    const entries = [];
+    const lines = String(commentValue === undefined || commentValue === null ? '' : commentValue).split('\n');
+    let current;
+
+    lines.forEach((rawLine, index) => {
+        const line = stripCommentGutter(rawLine);
+        if (line === '') {
+            current = undefined;
+            return;
+        }
+
+        const tagMatch = line.match(tagPattern);
+        if (tagMatch) {
+            const tag = tagMatch[1].toLowerCase();
+            if (!isDocAnchorTag(tag)) {
+                current = undefined;
+                return;
+            }
+
+            current = { tag, value: tagMatch[2].trim(), line: startLine + index };
+            entries.push(current);
+            return;
+        }
+
+        // A non-empty line that opens no new tag continues the previous value,
+        // which keeps multi-line `@rule` invariants readable in source.
+        if (current) current.value = `${current.value} ${line}`.trim();
+    });
+
+    return entries.filter((entry) => entry.value !== '');
+};
+
+const uniqueValues = (entries, tag) => {
+    const values = [];
+    entries.forEach((entry) => {
+        if (entry.tag !== tag || values.includes(entry.value)) return;
+        values.push(entry.value);
+    });
+
+    return values;
+};
+
+const buildDocAnchorGroups = (entries) => ({
+    entries,
+    docs: uniqueValues(entries, 'docs'),
+    adr: uniqueValues(entries, 'adr'),
+    fix: uniqueValues(entries, 'fix'),
+    rules: uniqueValues(entries, 'rule'),
+});
+
+const hasDocAnchorTag = (groups, tag) => groups.entries.some((entry) => entry.tag === tag);
+
+/**
+ * Collect every doc anchor in raw source text.
+ *
+ * Used by the MCP owner payloads, which read a file from disk and have no AST.
+ * The scan is capped so enriching an owner match stays cheap on large files.
+ */
+const collectDocAnchors = (sourceText, options) => {
+    const maxLength = options && options.maxLength ? options.maxLength : maxDocAnchorScanLength;
+    const text = String(sourceText === undefined || sourceText === null ? '' : sourceText).slice(0, maxLength);
+    const entries = [];
+
+    blockCommentPattern.lastIndex = 0;
+    let match = blockCommentPattern.exec(text);
+    while (match !== null) {
+        const body = match[0].slice(2, -2);
+        entries.push(...parseDocAnchorComment(body, countLinesBefore(text, match.index)));
+        match = blockCommentPattern.exec(text);
+    }
+
+    return buildDocAnchorGroups(entries);
+};
+
+module.exports = {
+    buildDocAnchorGroups,
+    collectDocAnchors,
+    docAnchorTags,
+    hasDocAnchorTag,
+    isPathDocAnchorTag,
+    minDocAnchorRuleLength,
+    parseDocAnchorComment,
+};

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/eslint.js

@@ -1,8 +1,19 @@
+const fs = require('node:fs');
+const path = require('node:path');
 const tseslint = require('typescript-eslint');
 const reactPlugin = require('eslint-plugin-react');
 const reactHooksPlugin = require('eslint-plugin-react-hooks');
 const jsxA11yPlugin = require('eslint-plugin-jsx-a11y');
 
+const {
+    buildDocAnchorGroups,
+    docAnchorTags,
+    hasDocAnchorTag,
+    isPathDocAnchorTag,
+    minDocAnchorRuleLength,
+    parseDocAnchorComment,
+} = require('./docAnchors.js');
+
 const defaultIgnores = [
     '**/node_modules/**',
     '**/bin/**',
@@ -307,7 +318,250 @@ const createNoAppImportRule = () => ({
     },
 });
 
-const createProteumEslintConfig = ({ ignores = [] } = {}) => [
+// Error routes are deliberately absent: a `_messages/404` page renders a status
+// message and carries no feature-specific rule, so requiring a feature pack for
+// one would manufacture documentation to satisfy the linter. An error page that
+// does carry a real rule can still add an anchor, and `valid-doc-anchor` keeps
+// checking it.
+const defaultDocAnchorDefinitions = [
+    'defineController',
+    'definePageRoute',
+    'defineServerRoute',
+    'defineServerRoutes',
+];
+
+const docsRootCache = new Map();
+const directoryEntriesCache = new Map();
+
+const getSourceCode = (context) => context.sourceCode || context.getSourceCode?.();
+
+const getContextCwd = (context) => context.cwd || context.getCwd?.() || process.cwd();
+
+const pathExists = (candidate) => {
+    try {
+        return fs.existsSync(candidate);
+    } catch (_error) {
+        return false;
+    }
+};
+
+const readDirectoryEntries = (directory) => {
+    if (directoryEntriesCache.has(directory)) return directoryEntriesCache.get(directory);
+
+    let entries = [];
+    try {
+        entries = fs.readdirSync(directory);
+    } catch (_error) {
+        entries = [];
+    }
+
+    directoryEntriesCache.set(directory, entries);
+    return entries;
+};
+
+/**
+ * Collect every ancestor of a linted file that holds a `docs/` directory,
+ * nearest first.
+ *
+ * All of them are candidates, not just the nearest: a monorepo app commonly has
+ * its own `apps/<app>/docs/` alongside the repository-level corpus, and stopping
+ * at the first match would make every anchor aimed at the shared corpus fail to
+ * resolve.
+ */
+const findDocsRoots = (startDirectory) => {
+    if (docsRootCache.has(startDirectory)) return docsRootCache.get(startDirectory);
+
+    const resolved = [];
+    let current = startDirectory;
+    while (current) {
+        if (pathExists(path.join(current, 'docs'))) resolved.push(current);
+
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+
+    docsRootCache.set(startDirectory, resolved);
+    return resolved;
+};
+
+const resolveAnchorRoots = (context) => {
+    const filename = context.filename || context.getFilename?.() || '';
+    const fileDirectory = filename ? path.dirname(filename) : undefined;
+    const cwd = getContextCwd(context);
+    const roots = [];
+
+    const addRoot = (root) => {
+        if (root && !roots.includes(root)) roots.push(root);
+    };
+
+    if (fileDirectory) findDocsRoots(fileDirectory).forEach(addRoot);
+    addRoot(cwd);
+    addRoot(fileDirectory);
+
+    return roots;
+};
+
+const resolvePathAnchor = (value, roots) => {
+    if (path.isAbsolute(value)) return pathExists(value);
+
+    return roots.some((root) => pathExists(path.resolve(root, value)));
+};
+
+const resolveAdrAnchor = (value, roots) => {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) return false;
+
+    const decisionDirectories = roots
+        .map((root) => path.join(root, 'docs', 'decisions'))
+        .filter((directory) => pathExists(directory));
+
+    // Projects without a decisions corpus never fail this check, so the rule
+    // stays silent instead of inventing a convention the app has not adopted.
+    if (decisionDirectories.length === 0) return true;
+
+    return decisionDirectories.some((directory) =>
+        readDirectoryEntries(directory).some((entry) => entry.toLowerCase().startsWith(normalized)),
+    );
+};
+
+const collectFileDocAnchors = (context) => {
+    const sourceCode = getSourceCode(context);
+    if (!sourceCode) return buildDocAnchorGroups([]);
+
+    const entries = [];
+    sourceCode.getAllComments().forEach((comment) => {
+        if (comment.type !== 'Block') return;
+        entries.push(...parseDocAnchorComment(comment.value, comment.loc?.start?.line || 1));
+    });
+
+    return buildDocAnchorGroups(entries);
+};
+
+const unwrapExpression = (node) => {
+    let current = node;
+    while (
+        current &&
+        (current.type === 'TSAsExpression' ||
+            current.type === 'TSSatisfiesExpression' ||
+            current.type === 'TSNonNullExpression')
+    ) {
+        current = current.expression;
+    }
+
+    return current;
+};
+
+const getDefinitionCalleeName = (node, definitions) => {
+    const expression = unwrapExpression(node);
+    if (expression?.type !== 'CallExpression') return null;
+
+    const name = getCalleePropertyName(expression.callee);
+    return name && definitions.includes(name) ? name : null;
+};
+
+const createRequireDocAnchorRule = () => ({
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require Proteum definition files to anchor the documentation that governs them.',
+        },
+        messages: {
+            missingAnchor:
+                '`{{definition}}` files must carry a doc anchor. Add a leading block comment with `@docs <path to the feature pack>`, plus `@rule <one-line invariant>` when a fix or decision constrains this file.',
+            missingTag:
+                '`{{definition}}` files must carry a `@{{tag}}` doc anchor in a leading block comment.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    definitions: { type: 'array', items: { type: 'string' } },
+                    requiredTags: { type: 'array', items: { enum: docAnchorTags } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    create(context) {
+        const options = context.options?.[0] || {};
+        const definitions = options.definitions || defaultDocAnchorDefinitions;
+        const requiredTags = options.requiredTags || ['docs'];
+
+        return {
+            ExportDefaultDeclaration(node) {
+                const definition = getDefinitionCalleeName(node.declaration, definitions);
+                if (!definition) return;
+
+                const anchors = collectFileDocAnchors(context);
+                if (anchors.entries.length === 0) {
+                    context.report({ node, messageId: 'missingAnchor', data: { definition } });
+                    return;
+                }
+
+                const missingTag = requiredTags.find((tag) => !hasDocAnchorTag(anchors, tag));
+                if (missingTag) {
+                    context.report({ node, messageId: 'missingTag', data: { definition, tag: missingTag } });
+                }
+            },
+        };
+    },
+});
+
+const createValidDocAnchorRule = () => ({
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require doc anchors to point at documentation that still exists.',
+        },
+        messages: {
+            unresolvedPath:
+                'Doc anchor `@{{tag}} {{value}}` does not resolve to a file or directory. Update the anchor to the current documentation path, or remove it.',
+            unresolvedAdr:
+                'Doc anchor `@adr {{value}}` matches no decision record under `docs/decisions`. Use the current ADR identifier.',
+            emptyRule:
+                'Doc anchor `@rule` must state the invariant in full so an agent editing this file can apply it without opening the linked document.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            'Program:exit'() {
+                const anchors = collectFileDocAnchors(context);
+                if (anchors.entries.length === 0) return;
+
+                const roots = resolveAnchorRoots(context);
+                anchors.entries.forEach((entry) => {
+                    const loc = { line: entry.line, column: 0 };
+
+                    if (entry.tag === 'rule') {
+                        if (entry.value.length < minDocAnchorRuleLength) {
+                            context.report({ loc, messageId: 'emptyRule' });
+                        }
+                        return;
+                    }
+
+                    if (isPathDocAnchorTag(entry.tag)) {
+                        if (!resolvePathAnchor(entry.value, roots)) {
+                            context.report({
+                                loc,
+                                messageId: 'unresolvedPath',
+                                data: { tag: entry.tag, value: entry.value },
+                            });
+                        }
+                        return;
+                    }
+
+                    if (entry.tag === 'adr' && !resolveAdrAnchor(entry.value, roots)) {
+                        context.report({ loc, messageId: 'unresolvedAdr', data: { value: entry.value } });
+                    }
+                });
+            },
+        };
+    },
+});
+
+const createProteumEslintConfig = ({ docAnchors = 'warn', ignores = [] } = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
     },
@@ -334,6 +588,8 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
                 rules: {
                     'no-app-import': createNoAppImportRule(),
                     'no-swallowed-caught-error': createSwallowedErrorRule(),
+                    'require-doc-anchor': createRequireDocAnchorRule(),
+                    'valid-doc-anchor': createValidDocAnchorRule(),
                 },
             },
             react: reactPlugin,
@@ -344,6 +600,13 @@ const createProteumEslintConfig = ({ ignores = [] } = {}) => [
             '@typescript-eslint/no-explicit-any': 'error',
             'proteum/no-app-import': 'error',
             'proteum/no-swallowed-caught-error': 'error',
+            // Missing anchors warn by default so adopting apps see the backlog
+            // without a failing build; pass `docAnchors: 'error'` once backfilled.
+            'proteum/require-doc-anchor': docAnchors,
+            // A stale anchor is always an error: it only fires on files that
+            // already opted in, and a pointer to a deleted document is worse
+            // than no pointer at all.
+            'proteum/valid-doc-anchor': docAnchors === 'off' ? 'off' : 'error',
             'no-restricted-syntax': [
                 'error',
                 {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.9",
+	"version": "2.5.11",
 	"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,