proteum 2.2.8 → 2.3.0

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/eslint-rules.test.cjs

@@ -0,0 +1,110 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { Linter } = require('eslint');
+
+const { createProteumEslintConfig } = require('../eslint.js');
+
+const lint = (code) => {
+    const linter = new Linter({ configType: 'flat' });
+    return linter.verify(code, createProteumEslintConfig(), {
+        filename: 'client/example.tsx',
+    });
+};
+
+const swallowedErrorRuleId = 'proteum/no-swallowed-caught-error';
+
+test('proteum lint rejects empty catch blocks', () => {
+    const messages = lint(`
+        export const run = () => {
+            try {
+                risky();
+            } catch {
+                return null;
+            }
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint rejects promise catches that discard the error', () => {
+    const messages = lint(`
+        export const run = () => {
+            api.load().catch(() => toast.error('Could not load'));
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint rejects generic catch feedback that drops original error details', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.getDashboard();
+            } catch (error) {
+                toast.error('Could not load API dashboard');
+            }
+        };
+    `);
+
+    assert.equal(messages.some((message) => message.ruleId === swallowedErrorRuleId), true);
+});
+
+test('proteum lint allows rethrowing the caught error', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.getDashboard();
+            } catch (error) {
+                toast.error('Could not load API dashboard');
+                throw error;
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows surfacing original error details', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.getDashboard();
+            } catch (error) {
+                toast.error('Could not load API dashboard', {
+                    description: error instanceof Error ? error.message : String(error),
+                });
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows surfacing a message derived from the caught error', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await Investor.api.getDashboard();
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                setError(message);
+            }
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});
+
+test('proteum lint allows routing promise failures to app error handling', () => {
+    const messages = lint(`
+        export const run = () => {
+            Investor.api.ensureApiKey().catch((error) => {
+                Router.app.handleError(error);
+            });
+        };
+    `);
+
+    assert.equal(messages.filter((message) => message.ruleId === swallowedErrorRuleId).length, 0);
+});

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, '/');
+});

package/tests/mcp.test.cjs

@@ -0,0 +1,127 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+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');
+require('../cli/context.ts');
+
+const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
+const { InMemoryTransport } = require('@modelcontextprotocol/sdk/inMemory.js');
+const { createMcpPayload, compactTraceResponse, resolveInstructionRouting } = require('../common/dev/mcpPayloads.ts');
+const { createProteumMcpServer } = require('../common/dev/mcpServer.ts');
+
+const writeFile = (filepath, content) => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+test('instruction routing returns compact selected files for a page query', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-app-'));
+
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# App Agents\n\n- root\n');
+    writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Client Agents\n\n- client\n');
+    writeFile(path.join(appRoot, 'client', 'pages', 'AGENTS.md'), '# Page Agents\n\n- pages\n');
+    writeFile(path.join(appRoot, 'diagnostics.md'), '# Diagnostics\n\n- diagnose\n');
+
+    const payload = resolveInstructionRouting({ appRoot, query: '/domains/:slug client/pages/domain.tsx' });
+
+    assert.equal(payload.ok, true);
+    assert.equal(payload.format, 'proteum-mcp-v1');
+    assert.deepEqual(
+        payload.data.selected.map((entry) => path.relative(appRoot, entry.file)).sort(),
+        ['AGENTS.md', 'client/AGENTS.md', 'client/pages/AGENTS.md'],
+    );
+    assert.equal(payload.data.readWhen.some((entry) => entry.file && entry.file.endsWith('diagnostics.md')), true);
+});
+
+test('trace payload keeps default output compact and paginates full details', () => {
+    const request = {
+        id: 'req_1',
+        method: 'GET',
+        path: '/domains',
+        url: 'http://localhost:3000/domains',
+        capture: 'deep',
+        startedAt: new Date().toISOString(),
+        finishedAt: new Date().toISOString(),
+        durationMs: 42,
+        statusCode: 200,
+        droppedEvents: 0,
+        calls: Array.from({ length: 3 }, (_, index) => ({
+            id: `call_${index}`,
+            origin: 'server',
+            label: `Call ${index}`,
+            method: 'POST',
+            path: `/api/${index}`,
+            statusCode: 200,
+            durationMs: 10 + index,
+            requestDataKeys: [],
+            resultKeys: [],
+        })),
+        events: Array.from({ length: 12 }, (_, index) => ({
+            index,
+            elapsedMs: index,
+            type: index === 2 ? 'error' : 'mark',
+            details: { index, long: 'x'.repeat(300) },
+        })),
+        sqlQueries: Array.from({ length: 4 }, (_, index) => ({
+            id: `sql_${index}`,
+            callerLabel: 'Service.query',
+            callerMethod: 'query',
+            callerPath: 'server/services/Domain/index.ts',
+            kind: 'query',
+            operation: 'findMany',
+            model: 'Domain',
+            durationMs: index + 1,
+            fingerprint: `fp_${index}`,
+            query: 'select * from Domain where id = ?',
+        })),
+    };
+
+    const compact = compactTraceResponse({ request });
+    const full = compactTraceResponse({ detail: 'full', limit: 5, offset: 4, request });
+
+    assert.equal(compact.data.page, undefined);
+    assert.equal(compact.omitted.length, 1);
+    assert.equal(full.data.page.events.length, 5);
+    assert.equal(full.data.page.hasMore, true);
+});
+
+test('MCP server registers the Proteum read-only tool contract', async () => {
+    const payload = createMcpPayload({ summary: 'ok', data: { value: 1 } });
+    const provider = {
+        diagnose: async () => payload,
+        doctor: async () => payload,
+        explainSummary: async () => payload,
+        instructionsResolve: async () => payload,
+        logsTail: async () => payload,
+        orient: async () => payload,
+        perfRequest: async () => payload,
+        perfTop: async () => payload,
+        readResource: async () => payload,
+        runtimeStatus: async () => payload,
+        traceLatest: async () => payload,
+        traceShow: async () => payload,
+    };
+    const server = createProteumMcpServer({ provider, version: 'test' });
+    const client = new Client({ name: 'mcp-test', version: '1.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    const tools = await client.listTools();
+    const result = await client.callTool({ name: 'runtime_status', arguments: {} });
+    const resource = await client.readResource({ uri: 'proteum://runtime/status' });
+
+    assert.equal(tools.tools.some((tool) => tool.name === 'runtime_status'), true);
+    assert.match(result.content[0].text, /proteum-mcp-v1/);
+    assert.match(resource.contents[0].text, /proteum-mcp-v1/);
+
+    await client.close();
+    await server.close();
+});

package/tests/router-cache-config.test.cjs

@@ -0,0 +1,74 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+require('ts-node/register/transpile-only');
+
+const {
+    resolveHttpCacheConfig,
+    resolvePublicAssetCacheControl,
+} = require('../server/services/router/http/cache');
+
+test('router cache config preserves current defaults', () => {
+    const cache = resolveHttpCacheConfig();
+
+    assert.equal(cache.html.dynamic.cacheControl, 'no-store, no-cache, must-revalidate, proxy-revalidate');
+    assert.equal(cache.html.dynamic.surrogateControl, 'no-store');
+    assert.equal(cache.html.static.cacheControl, 'public, max-age=0, must-revalidate');
+    assert.equal(cache.html.static.surrogateControl, false);
+    assert.equal(cache.publicAssets.dev, 'no-store');
+    assert.equal(cache.publicAssets.versioned, 'public, max-age=31536000, immutable');
+    assert.equal(cache.publicAssets.unversioned, 'public, max-age=0, must-revalidate');
+    assert.equal(cache.publicAssets.etag, undefined);
+    assert.equal(cache.publicAssets.lastModified, undefined);
+});
+
+test('router cache config resolves granular public asset policies', () => {
+    const cache = resolveHttpCacheConfig({
+        publicAssets: {
+            dev: 'dev-cache',
+            versioned: 'versioned-cache',
+            unversioned: 'unversioned-cache',
+            etag: false,
+            lastModified: false,
+        },
+    });
+
+    assert.equal(cache.publicAssets.etag, false);
+    assert.equal(cache.publicAssets.lastModified, false);
+    assert.equal(
+        resolvePublicAssetCacheControl({
+            res: undefined,
+            filePath: '/app/public/client.abc123.js',
+            profile: 'prod',
+            cache: cache.publicAssets,
+        }),
+        'versioned-cache',
+    );
+    assert.equal(
+        resolvePublicAssetCacheControl({
+            res: { req: { originalUrl: '/public/client.js?v=123' } },
+            filePath: '/app/public/client.js',
+            profile: 'prod',
+            cache: cache.publicAssets,
+        }),
+        'versioned-cache',
+    );
+    assert.equal(
+        resolvePublicAssetCacheControl({
+            res: { req: { originalUrl: '/public/client.js' } },
+            filePath: '/app/public/client.js',
+            profile: 'prod',
+            cache: cache.publicAssets,
+        }),
+        'unversioned-cache',
+    );
+    assert.equal(
+        resolvePublicAssetCacheControl({
+            res: { req: { originalUrl: '/public/client.abc123.js' } },
+            filePath: '/app/public/client.abc123.js',
+            profile: 'dev',
+            cache: cache.publicAssets,
+        }),
+        'dev-cache',
+    );
+});