proteum 2.2.9 → 2.3.0

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

@@ -8,7 +8,10 @@ import express from 'express';
 import http from 'http';
 import https from 'https';
 import path from 'path';
+import { randomUUID } from 'crypto';
 import cors, { CorsOptions } from 'cors';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 
 // Middlewares (npm)
 import morgan from 'morgan';
@@ -37,9 +40,16 @@ import {
     parseConnectedProjectProxyPath,
 } from '@common/connectedProjects';
 import { profilerTraceRequestIdHeader } from '@common/dev/profiler';
+import { createProteumMcpServer } from '@common/dev/mcpServer';
+import { createRuntimeProteumMcpProvider } from '@server/app/devMcp';
 
 // Middlewaees (core)
 import { isMutipart, MiddlewareFormData } from './multipart';
+import {
+    resolveHttpCacheConfig,
+    resolvePublicAssetCacheControl,
+    type THttpCacheConfig,
+} from './cache';
 
 /*----------------------------------
 - CONFIG
@@ -58,12 +68,15 @@ export type Config = {
         maxSize: string; // Expression package bytes
     };
     csp: { default?: string[]; styles?: string[]; images?: string[]; scripts: string[] };
+    cache?: THttpCacheConfig;
     cors?: CorsOptions;
     helmet?: Parameters<typeof helmet>[0];
 };
 
 export type Hooks = {};
 
+export { resolveHttpCacheConfig, type THttpCacheConfig } from './cache';
+
 type TContentSecurityPolicyOptions = NonNullable<Parameters<typeof helmet.contentSecurityPolicy>[0]>;
 type TContentSecurityPolicyDirectives = NonNullable<TContentSecurityPolicyOptions['directives']>;
 type TDevSessionAuthService = {
@@ -94,37 +107,9 @@ const createContentSecurityPolicy = (config: Config['csp']): TContentSecurityPol
     };
 };
 
-const immutablePublicAssetCacheControl = 'public, max-age=31536000, immutable';
-const devPublicAssetCacheControl = 'no-store';
-const revalidatedPublicAssetCacheControl = 'public, max-age=0, must-revalidate';
-const hashedPublicAssetPattern = /(^|[-_.])[a-f0-9]{6,}(?=(\.[^.]+)+$)/i;
 const connectedProjectBootRetryCount = 10;
 const connectedProjectBootRetryDelayMs = 5_000;
 
-const isVersionedPublicAssetRequest = (res: undefined | express.Response | http.ServerResponse, filePath: string) => {
-    const request =
-        res && typeof res === 'object' && 'req' in res
-            ? ((res as express.Response | (http.ServerResponse & { req?: express.Request })).req ?? undefined)
-            : undefined;
-    const requestUrl = request?.originalUrl || request?.url || '';
-    const searchParams = new URL(requestUrl, 'http://proteum.local').searchParams;
-    if (searchParams.has('v')) return true;
-
-    return hashedPublicAssetPattern.test(path.basename(filePath));
-};
-
-const resolvePublicAssetCacheControl = ({
-    res,
-    filePath,
-    profile,
-}: {
-    res: undefined | express.Response | http.ServerResponse;
-    filePath: string;
-    profile: string;
-}) => {
-    if (profile === 'dev') return devPublicAssetCacheControl;
-    return isVersionedPublicAssetRequest(res, filePath) ? immutablePublicAssetCacheControl : revalidatedPublicAssetCacheControl;
-};
 const wait = async (durationMs: number) =>
     await new Promise<void>((resolve) => {
         setTimeout(resolve, durationMs);
@@ -406,20 +391,22 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
         // Normalement, seulement utile pour le mode production,
         // Quand mode debug, les ressources client semblent servies par le dev middlewae
         // Sauf que les ressources serveur ne semblent pas trouvées par le dev-middleware
-        const disablePublicAssetCaching = this.app.env.profile === 'dev';
+        const publicAssetCache = resolveHttpCacheConfig(this.config.cache).publicAssets;
+        const defaultPublicAssetValidators = this.app.env.profile !== 'dev';
+        const publicAssetEtag = publicAssetCache.etag ?? defaultPublicAssetValidators;
+        const publicAssetLastModified = publicAssetCache.lastModified ?? defaultPublicAssetValidators;
+
         routes.use(compression());
         routes.use('/public', cors());
         routes.use(
             '/public',
             express.static(path.join(Container.path.root, APP_OUTPUT_DIR, 'public'), {
                 dotfiles: 'deny',
-                etag: !disablePublicAssetCaching,
-                lastModified: !disablePublicAssetCaching,
+                etag: publicAssetEtag,
+                lastModified: publicAssetLastModified,
                 setHeaders: (res, filePath) => {
-                    if (disablePublicAssetCaching) {
-                        res.removeHeader('ETag');
-                        res.removeHeader('Last-Modified');
-                    }
+                    if (!publicAssetEtag) res.removeHeader('ETag');
+                    if (!publicAssetLastModified) res.removeHeader('Last-Modified');
 
                     res.setHeader(
                         'Cache-Control',
@@ -427,6 +414,7 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
                             res,
                             filePath,
                             profile: this.app.env.profile,
+                            cache: publicAssetCache,
                         }),
                     );
                 },
@@ -510,6 +498,8 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
     private registerDevTraceRoutes(routes: express.Express) {
         if (!__DEV__ || this.app.env.profile !== 'dev') return;
 
+        this.registerDevMcpRoute(routes);
+
         if (this.app.container.Trace.isDevTraceEnabled()) {
             routes.get('/__proteum/trace/requests', (req, res) => {
                 const rawLimit = Array.isArray(req.query.limit) ? req.query.limit[0] : req.query.limit;
@@ -836,4 +826,73 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
     private getCronManager() {
         return (this.app as typeof this.app & { Cron?: CronManager }).Cron;
     }
+
+    private registerDevMcpRoute(routes: express.Express) {
+        type TMcpTransportEntry = {
+            server: ReturnType<typeof createProteumMcpServer>;
+            transport: StreamableHTTPServerTransport;
+        };
+        const transports = new Map<string, TMcpTransportEntry>();
+        const readSessionId = (req: express.Request) => {
+            const value = req.headers['mcp-session-id'];
+            if (Array.isArray(value)) return value[0];
+            return typeof value === 'string' && value.trim() ? value : undefined;
+        };
+        const writeJsonRpcError = (res: express.Response, statusCode: number, message: string) => {
+            res.status(statusCode).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message,
+                },
+                id: null,
+            });
+        };
+
+        routes.all('/__proteum/mcp', async (req, res) => {
+            const sessionId = readSessionId(req);
+            let entry = sessionId ? transports.get(sessionId) : undefined;
+
+            try {
+                if (!entry && !sessionId && req.method === 'POST' && isInitializeRequest(req.body)) {
+                    const provider = createRuntimeProteumMcpProvider({
+                        app: this.app,
+                        publicUrl: this.publicUrl,
+                        routerPort: this.config.port,
+                    });
+                    const server = createProteumMcpServer({
+                        provider,
+                        version: String(process.env.npm_package_version || 'runtime'),
+                    });
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: (initializedSessionId) => {
+                            transports.set(initializedSessionId, { server, transport });
+                        },
+                    });
+
+                    transport.onclose = () => {
+                        const transportSessionId = transport.sessionId;
+                        if (transportSessionId) transports.delete(transportSessionId);
+                        void server.close().catch(() => undefined);
+                    };
+
+                    await server.connect(transport);
+                    entry = { server, transport };
+                }
+
+                if (!entry) {
+                    writeJsonRpcError(res, 400, 'Bad Request: initialize the Proteum MCP session before sending tool or resource requests.');
+                    return;
+                }
+
+                await entry.transport.handleRequest(req, res, req.body);
+            } catch (error) {
+                console.error('Error handling Proteum MCP request:', error);
+                if (!res.headersSent) {
+                    writeJsonRpcError(res, 500, 'Internal Proteum MCP server error.');
+                }
+            }
+        });
+    }
 }

package/server/services/router/index.ts

@@ -52,7 +52,7 @@ import { AnyRouterService } from './service';
 import ServerRequest from './request';
 import ServerResponse, { TRouterContext, TRouterContextServices } from './response';
 import Page from './response/page';
-import HTTP, { Config as HttpServiceConfig } from './http';
+import HTTP, { Config as HttpServiceConfig, resolveHttpCacheConfig } from './http';
 import DocumentRenderer from './response/page/document';
 import { loadGeneratedRuntimeBundle } from './generatedRuntime';
 
@@ -97,9 +97,6 @@ export type TApiResponseData = { data: any; triggers?: { [cle: string]: any } };
 
 export type HttpHeaders = { [cle: string]: string };
 
-const dynamicHtmlCacheControl = 'no-store, no-cache, must-revalidate, proxy-revalidate';
-const staticHtmlCacheControl = 'public, max-age=0, must-revalidate';
-
 /*----------------------------------
 - SERVICE CONFIG
 ----------------------------------*/
@@ -1136,15 +1133,15 @@ export default class ServerRouter<
     }
 
     private applyHtmlCacheHeaders(res: express.Response, isStaticHtml: boolean) {
-        if (isStaticHtml) {
+        const cache = resolveHttpCacheConfig(this.config.http.cache);
+        const htmlCache = isStaticHtml ? cache.html.static : cache.html.dynamic;
+
+        if (htmlCache.surrogateControl === false) {
             res.removeHeader('Surrogate-Control');
-            res.setHeader('Cache-Control', staticHtmlCacheControl);
-            return;
+        } else {
+            res.setHeader('Surrogate-Control', htmlCache.surrogateControl);
         }
 
-        // Don't cache dynamic HTML, because updated releases can change asset hashes.
-        // https://github.com/helmetjs/nocache/blob/main/index.ts
-        res.setHeader('Surrogate-Control', 'no-store');
-        res.setHeader('Cache-Control', dynamicHtmlCacheControl);
+        res.setHeader('Cache-Control', htmlCache.cacheControl);
     }
 }

package/tests/agents-utils.test.cjs

@@ -24,7 +24,17 @@ const createCoreFixture = () => {
 
     writeFile(path.join(agentsRoot, 'AGENTS.md'), '# Root Contract\n\n- Root rule\n');
     writeFile(path.join(agentsRoot, 'CODING_STYLE.md'), '# Coding Style\n\n- Style rule\n');
+    writeFile(path.join(agentsRoot, 'diagnostics.md'), '# Diagnostics\n\n- Diagnostics rule\n');
+    writeFile(path.join(agentsRoot, 'optimizations.md'), '# Optimizations\n\n- Optimization rule\n');
     writeFile(path.join(agentsRoot, 'client', 'AGENTS.md'), '# Client Rules\n\n- Client rule\n');
+    writeFile(path.join(agentsRoot, 'client', 'pages', 'AGENTS.md'), '# Page Rules\n\n- Page rule\n');
+    writeFile(path.join(agentsRoot, 'server', 'routes', 'AGENTS.md'), '# Route Rules\n\n- Route rule\n');
+    writeFile(path.join(agentsRoot, 'server', 'services', 'AGENTS.md'), '# Service Rules\n\n- Service rule\n');
+    writeFile(path.join(agentsRoot, 'tests', 'e2e', 'AGENTS.md'), '# E2E Rules\n\n- E2E rule\n');
+    writeFile(
+        path.join(agentsRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'),
+        '# Real World Journey Tests\n\n- Journey rule\n',
+    );
 
     return root;
 };
@@ -52,7 +62,7 @@ const createAppFixture = () => {
     return appRoot;
 };
 
-test('standalone configure creates tracked instruction files with embedded corpus', () => {
+test('standalone configure creates tracked instruction files with routing contract and split docs', () => {
     const coreRoot = createCoreFixture();
     const appRoot = createAppFixture();
     const result = configureProjectAgentInstructions({ appRoot, coreRoot });
@@ -63,10 +73,16 @@ test('standalone configure creates tracked instruction files with embedded corpu
     assert.equal(result.blocked.length, 0);
     assert.match(agentsContent, /^# Proteum Instructions/m);
     assert.match(agentsContent, /<!-- proteum-instructions:start -->/);
-    assert.match(agentsContent, /## Source: AGENTS\.md/);
-    assert.match(agentsContent, /## Root Contract/);
-    assert.match(agentsContent, /## Source: CODING_STYLE\.md/);
-    assert.match(codingStyleContent, /## Source: client\/AGENTS\.md/);
+    assert.match(agentsContent, /## Agent Routing Contract/);
+    assert.match(agentsContent, /npx proteum orient <query>/);
+    assert.doesNotMatch(agentsContent, /## Source: CODING_STYLE\.md/);
+    assert.match(codingStyleContent, /## Source: CODING_STYLE\.md/);
+    assert.match(codingStyleContent, /## Coding Style/);
+    assert.doesNotMatch(codingStyleContent, /## Source: client\/AGENTS\.md/);
+    assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'AGENTS.md')), true);
+    assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md')), true);
+    assert.match(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /Journey rule/);
+    assert.doesNotMatch(fs.readFileSync(path.join(appRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
     assert.doesNotMatch(agentsContent, /Before reading or applying instructions from this file/);
     assert.doesNotMatch(gitignoreContent, /Proteum-managed instruction files/);
     assert.doesNotMatch(gitignoreContent, /^\/AGENTS\.md$/m);
@@ -102,7 +118,8 @@ test('configure preserves project content outside the managed section', () => {
     const content = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
     assert.match(content, /# Product Notes/);
     assert.match(content, /Keep this product note\./);
-    assert.match(content, /## Source: CODING_STYLE\.md/);
+    assert.match(content, /## Agent Routing Contract/);
+    assert.doesNotMatch(content, /## Source: CODING_STYLE\.md/);
     assert.doesNotMatch(content, /Old managed content/);
     assert.match(content, /# Local Footer/);
     assert.match(content, /Keep this footer\./);
@@ -144,7 +161,8 @@ test('configure preserves project content around legacy managed stubs', () => {
     assert.match(content, /## Product Bootstrap/);
     assert.match(content, /Keep these local bootstrap notes\./);
     assert.match(content, /# Proteum Instructions/);
-    assert.match(content, /## Source: CODING_STYLE\.md/);
+    assert.match(content, /## Agent Routing Contract/);
+    assert.doesNotMatch(content, /## Source: CODING_STYLE\.md/);
     assert.doesNotMatch(content, /# Proteum Managed Instructions/);
     assert.doesNotMatch(content, /Before reading or applying instructions from this file/);
     assert.match(content, /## Local Footer/);
@@ -165,11 +183,16 @@ test('monorepo configure writes root and app instruction files', () => {
 
     assert.equal(result.mode, 'monorepo');
     assert.equal(resolveProjectAgentMonorepoRoot(appRoot), fs.realpathSync(monorepoRoot));
-    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Source: AGENTS\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'CODING_STYLE.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
-    assert.match(fs.readFileSync(path.join(monorepoRoot, 'diagnostics.md'), 'utf8'), /## Source: AGENTS\.md/);
-    assert.match(fs.readFileSync(path.join(monorepoRoot, 'optimizations.md'), 'utf8'), /## Source: AGENTS\.md/);
-    assert.match(fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'diagnostics.md'), 'utf8'), /## Source: diagnostics\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'optimizations.md'), 'utf8'), /## Source: optimizations\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'AGENTS.md'), 'utf8'), /## Source: tests\/e2e\/AGENTS\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: tests\/e2e\/REAL_WORLD_JOURNEY_TESTS\.md/);
+    assert.doesNotMatch(fs.readFileSync(path.join(monorepoRoot, 'tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'e2e', 'AGENTS.md')), false);
+    assert.match(fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
+    assert.match(fs.readFileSync(path.join(appRoot, 'client', 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
     assert.equal(fs.existsSync(path.join(appRoot, 'CODING_STYLE.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'diagnostics.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'optimizations.md')), false);
@@ -222,7 +245,7 @@ test('monorepo configure strips retired managed sections from local app-root doc
     assert.equal(result.updated.some((entry) => entry.endsWith('/apps/product/CODING_STYLE.md')), true);
 });
 
-test('configure migrates legacy managed symlinks to embedded files', () => {
+test('configure migrates legacy managed symlinks to tracked files', () => {
     const coreRoot = createCoreFixture();
     const appRoot = createAppFixture();
     const installedCoreRoot = createCoreFixture();
@@ -258,5 +281,5 @@ test('configure reports blocked paths unless overwrite is allowed', () => {
 
     assert.equal(result.overwritten.some((entry) => entry.endsWith('/CODING_STYLE.md')), true);
     assert.equal(fs.lstatSync(blockedPath).isFile(), true);
-    assert.match(fs.readFileSync(blockedPath, 'utf8'), /## Source: AGENTS\.md/);
+    assert.match(fs.readFileSync(blockedPath, 'utf8'), /## Source: CODING_STYLE\.md/);
 });

package/tests/dev-transpile-watch.test.cjs

@@ -65,6 +65,33 @@ const findAssetContaining = (appRoot, extension, marker) => {
     return candidates.find((filepath) => fs.readFileSync(filepath, 'utf8').includes(marker));
 };
 
+const toPublicAssetUrl = (appRoot, filepath) => {
+    const publicRoot = path.join(appRoot, 'dev', 'public');
+    const relativePath = path.relative(publicRoot, filepath).split(path.sep).join('/');
+
+    return `/public/${relativePath}`;
+};
+
+const request = async (port, urlPath, headers = {}) => {
+    const response = await fetch(`http://127.0.0.1:${port}${urlPath}`, { headers });
+    const body = await response.text();
+
+    return { response, body };
+};
+
+const waitForHeader = async (port, urlPath, headerName, expectedValue, timeoutMs = 60000) => {
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        const { response } = await request(port, urlPath, { Accept: 'text/html' });
+        if (response.headers.get(headerName) === expectedValue) return response;
+
+        await sleep(250);
+    }
+
+    throw new Error(`Timed out waiting for ${urlPath} header ${headerName}=${expectedValue}.`);
+};
+
 const waitForAssetContaining = async (appRoot, extension, marker, timeoutMs = 60000) => {
     const deadline = Date.now() + timeoutMs;
 
@@ -172,9 +199,10 @@ const createSharedStyleSource = (marker) => `.shared-style-marker {
 }
 `;
 
-const createFixture = (root, port) => {
+const createFixture = (root, port, options = {}) => {
     const appRoot = path.join(root, 'app');
     const sharedRoot = path.join(root, 'shared');
+    const cacheConfigSource = options.routerCache ? `        cache: ${options.routerCache},\n` : '';
 
     fs.mkdirSync(path.join(appRoot, 'public'), { recursive: true });
     fs.mkdirSync(path.join(appRoot, 'client', 'assets', 'identity'), { recursive: true });
@@ -332,6 +360,7 @@ export const routerBaseConfig = {
         upload: {
             maxSize: '10mb',
         },
+${cacheConfigSource}
         csp: {
             scripts: [],
         },
@@ -403,6 +432,31 @@ Router.page(
 );
 `,
     );
+    if (options.staticPage) {
+        writeFile(
+            path.join(appRoot, 'client', 'pages', 'static-cache.tsx'),
+            `import Router from '@/client/router';
+import { SharedMarker } from '@test/shared';
+
+Router.page(
+    '/static-cache',
+    {
+        auth: false,
+        layout: false,
+        static: { urls: ['/static-cache'] },
+    },
+    null,
+    () => {
+        return (
+            <main>
+                <SharedMarker />
+            </main>
+        );
+    },
+);
+`,
+        );
+    }
 
     writeFile(
         path.join(sharedRoot, 'package.json'),
@@ -448,13 +502,8 @@ const stopDevServer = async (child) => {
     });
 };
 
-test('proteum dev invalidates client assets and reloads for transpiled package scripts and styles', { timeout: 180000 }, async () => {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-transpile-watch-'));
-    const port = await resolvePortPair();
-    const { appRoot, sharedRoot } = createFixture(root, port);
-    const sessionFile = path.join(appRoot, 'var', 'run', 'proteum', 'dev', 'transpile-watch-test.json');
+const startDevServer = (appRoot, port, sessionFile) => {
     let output = '';
-
     const child = spawn(
         process.execPath,
         [cliBin, 'dev', '--cwd', appRoot, '--port', String(port), '--session-file', sessionFile, '--no-cache', '--verbose'],
@@ -476,8 +525,21 @@ test('proteum dev invalidates client assets and reloads for transpiled package s
         output += chunk.toString();
     });
 
+    return {
+        child,
+        getOutput: () => output,
+    };
+};
+
+test('proteum dev invalidates client assets and reloads for transpiled package scripts and styles', { timeout: 180000 }, async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-transpile-watch-'));
+    const port = await resolvePortPair();
+    const { appRoot, sharedRoot } = createFixture(root, port);
+    const sessionFile = path.join(appRoot, 'var', 'run', 'proteum', 'dev', 'transpile-watch-test.json');
+    const { child, getOutput } = startDevServer(appRoot, port, sessionFile);
+
     try {
-        await waitForSessionReady(sessionFile, child, () => output);
+        await waitForSessionReady(sessionFile, child, getOutput);
 
         const initialScriptAsset = await waitForAssetContaining(appRoot, '.js', 'SCRIPT_MARKER_INITIAL');
         const initialScriptContent = fs.readFileSync(initialScriptAsset, 'utf8');
@@ -511,3 +573,50 @@ test('proteum dev invalidates client assets and reloads for transpiled package s
         fs.rmSync(root, { recursive: true, force: true });
     }
 });
+
+test('proteum dev applies router HTTP cache config to HTML and public assets', { timeout: 180000 }, async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-router-cache-'));
+    const port = await resolvePortPair();
+    const dynamicHtmlCacheControl = 'private, max-age=7';
+    const staticHtmlCacheControl = 'private, max-age=13';
+    const publicAssetCacheControl = 'private, max-age=17';
+    const { appRoot } = createFixture(root, port, {
+        staticPage: true,
+        routerCache: `{
+            html: {
+                dynamic: { cacheControl: '${dynamicHtmlCacheControl}', surrogateControl: 'dynamic-surrogate' },
+                static: { cacheControl: '${staticHtmlCacheControl}', surrogateControl: 'static-surrogate' },
+            },
+            publicAssets: {
+                dev: '${publicAssetCacheControl}',
+                versioned: '${publicAssetCacheControl}',
+                unversioned: '${publicAssetCacheControl}',
+                etag: false,
+                lastModified: false,
+            },
+        }`,
+    });
+    const sessionFile = path.join(appRoot, 'var', 'run', 'proteum', 'dev', 'router-cache-test.json');
+    const { child, getOutput } = startDevServer(appRoot, port, sessionFile);
+
+    try {
+        await waitForSessionReady(sessionFile, child, getOutput);
+
+        const { response: dynamicResponse } = await request(port, '/', { Accept: 'text/html' });
+        assert.equal(dynamicResponse.headers.get('cache-control'), dynamicHtmlCacheControl);
+        assert.equal(dynamicResponse.headers.get('surrogate-control'), 'dynamic-surrogate');
+
+        const staticResponse = await waitForHeader(port, '/static-cache', 'cache-control', staticHtmlCacheControl);
+        assert.equal(staticResponse.headers.get('surrogate-control'), 'static-surrogate');
+
+        const asset = await waitForAssetContaining(appRoot, '.js', 'SCRIPT_MARKER_INITIAL');
+        const { response: assetResponse } = await request(port, toPublicAssetUrl(appRoot, asset));
+
+        assert.equal(assetResponse.headers.get('cache-control'), publicAssetCacheControl);
+        assert.equal(assetResponse.headers.get('etag'), null);
+        assert.equal(assetResponse.headers.get('last-modified'), null);
+    } finally {
+        await stopDevServer(child);
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});

package/tests/inspection.test.cjs

@@ -0,0 +1,67 @@
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const test = require('node:test');
+
+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 { explainOwner } = require('../common/dev/inspection.ts');
+
+const createRoute = (routePath, filepath) => ({
+    chunkFilepath: filepath,
+    chunkId: filepath.replace(/[^A-Za-z0-9]+/g, '_'),
+    codeRaw: routePath,
+    filepath,
+    hasData: false,
+    kind: 'page',
+    methodName: 'page',
+    normalizedOptionKeys: [],
+    path: routePath,
+    pathRaw: routePath,
+    scope: 'app',
+    sourceLocation: { line: 1, column: 1 },
+    targetResolution: 'literal',
+});
+
+const createManifest = (routes) => ({
+    app: {
+        coreRoot,
+        root: '/tmp/proteum-app',
+    },
+    commands: [],
+    connectedProjects: [],
+    controllers: [],
+    diagnostics: [],
+    layouts: [],
+    routes: {
+        client: routes,
+        server: [],
+    },
+    services: {
+        app: [],
+        routerPlugins: [],
+    },
+});
+
+test('root owner lookup does not match every dynamic route containing a slash', () => {
+    const manifest = createManifest([
+        createRoute('/domains/:slug((?!tlds$|tld$|sector$)[^/]+)', '/tmp/proteum-app/client/pages/domains/slug.tsx'),
+        createRoute('/admin/data/:tab([^/]+)', '/tmp/proteum-app/client/pages/admin/data.tsx'),
+    ]);
+
+    assert.deepEqual(explainOwner(manifest, '/').matches, []);
+});
+
+test('root owner lookup returns only the literal root route when present', () => {
+    const manifest = createManifest([
+        createRoute('/domains/:slug((?!tlds$|tld$|sector$)[^/]+)', '/tmp/proteum-app/client/pages/domains/slug.tsx'),
+        createRoute('/', '/tmp/proteum-app/client/pages/home.tsx'),
+    ]);
+
+    const matches = explainOwner(manifest, '/').matches;
+
+    assert.equal(matches.length, 1);
+    assert.equal(matches[0].label, '/');
+});