proteum 2.3.0 → 2.4.1

package/server/app/devMcp.ts

@@ -10,7 +10,9 @@ import {
     compactOrientationResponse,
     compactPerfRequestResponse,
     compactPerfTopResponse,
+    compactRouteCandidatesResponse,
     compactTraceResponse,
+    compactWorkflowStartResponse,
     resolveInstructionRouting,
 } from '@common/dev/mcpPayloads';
 import type { TProteumMcpProvider } from '@common/dev/mcpServer';
@@ -64,6 +66,42 @@ export const createRuntimeProteumMcpProvider = ({
                 },
             });
         },
+        async workflowStart({ file, query, route, task }) {
+            const manifest = readManifest();
+            const doctor = buildDoctorResponse(manifest);
+            const contracts = buildContractsDoctorResponse(manifest);
+            const ownerQuery = [route, file, query]
+                .map((value) => value?.trim())
+                .find((value): value is string => Boolean(value));
+
+            return compactWorkflowStartResponse({
+                contracts,
+                doctor,
+                file,
+                health: {
+                    reachable: true,
+                    doctor: doctor.summary,
+                    contracts: contracts.summary,
+                },
+                manifest,
+                owner: ownerQuery ? explainOwner(manifest, ownerQuery) : undefined,
+                query,
+                route,
+                runtime: {
+                    publicUrl,
+                    routerPort,
+                    source: 'proteum-dev-runtime',
+                    mcpUrl: `${publicUrl}/__proteum/mcp`,
+                    traceEnabled: app.container.Trace.isDevTraceEnabled(),
+                    profilerEnabled: app.container.Trace.isProfilingEnabled(),
+                    connectedProjects: Object.entries(app.connectedProjects || {}).map(([namespace, project]) => ({
+                        namespace,
+                        urlInternal: (project as { urlInternal?: string }).urlInternal,
+                    })),
+                },
+                task,
+            });
+        },
         async orient({ query }) {
             return compactOrientationResponse(buildOrientationResponse(readManifest(), query));
         },
@@ -80,6 +118,13 @@ export const createRuntimeProteumMcpProvider = ({
                 query: normalizedQuery,
             });
         },
+        async routeCandidates({ limit, query }) {
+            return compactRouteCandidatesResponse({
+                limit,
+                manifest: readManifest(),
+                query,
+            });
+        },
         async doctor({ contracts = true }) {
             const manifest = readManifest();
 

package/server/services/router/request/ip.test.cjs

@@ -1,5 +1,4 @@
 const assert = require('node:assert/strict');
-const test = require('node:test');
 
 const { resolveRequestIp } = require('./ip.ts');
 

package/tests/agents-utils.test.cjs

@@ -2,7 +2,6 @@ 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');
@@ -24,12 +23,14 @@ 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, 'DOCUMENTATION.md'), '# Documentation\n\n- Documentation 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', 'AGENTS.md'), '# Test Rules\n\n- Test 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'),
@@ -53,6 +54,7 @@ const createAppFixture = () => {
             '# Proteum-managed instruction files',
             '/AGENTS.md',
             '/CODING_STYLE.md',
+            '/DOCUMENTATION.md',
             '# End Proteum-managed instruction files',
             '/.proteum',
             '',
@@ -62,23 +64,61 @@ const createAppFixture = () => {
     return appRoot;
 };
 
+test('project instruction sources require unit tests for applicable production changes', () => {
+    const projectAgentsRoot = path.join(coreRoot, 'agents', 'project');
+
+    assert.match(
+        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/,
+    );
+});
+
 test('standalone configure creates tracked instruction files with routing contract and split docs', () => {
     const coreRoot = createCoreFixture();
     const appRoot = createAppFixture();
     const result = configureProjectAgentInstructions({ appRoot, coreRoot });
     const agentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
     const codingStyleContent = fs.readFileSync(path.join(appRoot, 'CODING_STYLE.md'), 'utf8');
+    const documentationContent = fs.readFileSync(path.join(appRoot, 'DOCUMENTATION.md'), 'utf8');
     const gitignoreContent = fs.readFileSync(path.join(appRoot, '.gitignore'), 'utf8');
 
     assert.equal(result.blocked.length, 0);
     assert.match(agentsContent, /^# Proteum Instructions/m);
     assert.match(agentsContent, /<!-- proteum-instructions:start -->/);
     assert.match(agentsContent, /## Agent Routing Contract/);
-    assert.match(agentsContent, /npx proteum orient <query>/);
+    assert.match(agentsContent, /npx proteum runtime status/);
+    assert.match(agentsContent, /MCP `workflow_start`/);
+    assert.match(agentsContent, /project_resolve \{ cwd \}/);
+    assert.match(agentsContent, /instructions_resolve \{ projectId \}/);
+    assert.match(agentsContent, /Do not run CLI equivalents after a successful MCP result/);
+    assert.match(agentsContent, /Read full files only before edits or git writes/);
+    assert.match(agentsContent, /explain_summary/);
+    assert.match(agentsContent, /\/__proteum\/mcp/);
+    assert.match(agentsContent, /proteum-mcp-v1/);
+    assert.match(agentsContent, /## Triggered Instruction Reads/);
+    assert.match(agentsContent, /Git lifecycle/);
+    assert.match(agentsContent, /read Root contract fallback before any git write/);
+    assert.match(agentsContent, /add or update focused unit tests/);
+    assert.match(agentsContent, /read Root contract fallback, `CODING_STYLE\.md`, `tests\/AGENTS\.md`/);
+    assert.match(agentsContent, /MCP-selected previews are enough/);
+    assert.doesNotMatch(agentsContent, /Conventional Commits/);
+    assert.match(agentsContent, /They are not deleted/);
     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.match(documentationContent, /## Source: DOCUMENTATION\.md/);
+    assert.match(documentationContent, /## Documentation/);
+    assert.equal(fs.existsSync(path.join(appRoot, 'tests', 'AGENTS.md')), true);
+    assert.match(fs.readFileSync(path.join(appRoot, 'tests', 'AGENTS.md'), 'utf8'), /Test rule/);
     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/);
@@ -86,6 +126,7 @@ test('standalone configure creates tracked instruction files with routing contra
     assert.doesNotMatch(agentsContent, /Before reading or applying instructions from this file/);
     assert.doesNotMatch(gitignoreContent, /Proteum-managed instruction files/);
     assert.doesNotMatch(gitignoreContent, /^\/AGENTS\.md$/m);
+    assert.doesNotMatch(gitignoreContent, /^\/DOCUMENTATION\.md$/m);
 });
 
 test('configure preserves project content outside the managed section', () => {
@@ -176,6 +217,10 @@ test('monorepo configure writes root and app instruction files', () => {
 
     fs.mkdirSync(path.join(monorepoRoot, '.git'));
     fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+    fs.mkdirSync(path.join(appRoot, 'server'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"product"}\n');
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
 
     configureProjectAgentInstructions({ appRoot, coreRoot });
 
@@ -184,16 +229,26 @@ 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'), /## Agent Routing Contract/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Known Proteum Apps/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /apps\/product/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Do not start `npx proteum dev` from this root/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'CODING_STYLE.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'DOCUMENTATION.md'), 'utf8'), /## Source: DOCUMENTATION\.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', 'AGENTS.md'), 'utf8'), /## Source: tests\/AGENTS\.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', 'AGENTS.md')), false);
     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/);
+    const appAgentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
+    assert.match(appAgentsContent, /## Agent Routing Contract/);
+    assert.doesNotMatch(appAgentsContent, /## Known Proteum Apps/);
+    assert.doesNotMatch(appAgentsContent, /Do not start `npx proteum dev` from this root/);
     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, 'DOCUMENTATION.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'diagnostics.md')), false);
     assert.equal(fs.existsSync(path.join(appRoot, 'optimizations.md')), false);
     assert.equal(result.removed.some((entry) => entry.endsWith('/apps/product/CODING_STYLE.md')), true);

package/tests/cli-mcp-command.test.cjs

@@ -0,0 +1,262 @@
+const assert = require('node:assert/strict');
+const { spawn, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const http = require('node:http');
+const os = require('node:os');
+const path = require('node:path');
+
+const coreRoot = path.resolve(__dirname, '..');
+const cliBin = path.join(coreRoot, 'cli', 'bin.js');
+
+const writeFile = (filepath, content) => {
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, content);
+};
+
+const createProteumApp = (appRoot, { routerPort = 3020 } = {}) => {
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+    fs.mkdirSync(path.join(appRoot, 'server'), { recursive: true });
+    writeFile(
+        path.join(appRoot, '.proteum', 'manifest.json'),
+        JSON.stringify({
+            version: 10,
+            app: {
+                root: appRoot,
+                coreRoot,
+                identityFilepath: path.join(appRoot, 'identity.config.ts'),
+                setupFilepath: path.join(appRoot, 'proteum.config.ts'),
+                identity: { name: 'Product', identifier: 'ProductApp', description: '' },
+                setup: {},
+            },
+            conventions: { routeOptionKeys: [], reservedRouteOptionKeys: [] },
+            env: {
+                source: 'test',
+                loadedVariableKeys: [],
+                requiredVariables: [],
+                resolved: {
+                    name: 'test',
+                    profile: 'dev',
+                    routerPort,
+                    routerCurrentDomain: 'localhost',
+                    routerInternalUrl: `http://localhost:${routerPort}`,
+                },
+            },
+            connectedProjects: [],
+            services: { app: [], routerPlugins: [] },
+            controllers: [],
+            commands: [],
+            routes: { client: [], server: [] },
+            layouts: [],
+            diagnostics: [],
+        }),
+    );
+};
+
+const listen = async (server, port = 0) =>
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => resolve(server.address().port));
+    });
+
+const closeServer = async (server) =>
+    await new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+
+const runCli = async (args, { cwd }) =>
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [cliBin, ...args], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.once('error', reject);
+        child.once('close', (status) => resolve({ status, stdout, stderr }));
+    });
+
+test('top-level help lists the machine-scope mcp router', () => {
+    const result = spawnSync(process.execPath, [cliBin, '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+
+    assert.equal(result.status, 0);
+    assert.match(result.stdout, /proteum mcp\b/);
+    assert.match(result.stdout, /machine-scope MCP router/);
+});
+
+test('mcp help describes projectId routing', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'mcp', '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /machine-scope MCP router/);
+    assert.match(output, /projectId/);
+    assert.match(output, /--daemon/);
+    assert.match(output, /--stdio/);
+});
+
+test('explain help describes compact section summaries', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'explain', '--help'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+
+    assert.equal(result.status, 0);
+    assert.match(output, /Summarize generated routes, controllers, and commands together/);
+    assert.match(output, /--routes --controllers --commands --full/);
+    assert.match(output, /Explicit section flags summarize those sections by default/);
+});
+
+test('runtime status from a monorepo wrapper returns app candidates instead of treating wrapper as app', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-wrapper-'));
+    createProteumApp(path.join(repoRoot, 'apps', 'product'));
+
+    const result = spawnSync(process.execPath, [cliBin, 'runtime', 'status'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    const payload = JSON.parse(result.stdout);
+
+    assert.equal(result.status, 1);
+    assert.equal(payload.ok, false);
+    assert.equal(payload.data.appCandidates.length, 1);
+    assert.match(payload.nextActions[0].command, /cd "apps\/product"/);
+    assert.match(payload.nextActions[0].command, /npx proteum runtime status/);
+});
+
+test('dev from a monorepo wrapper returns exact app-root start command', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-dev-wrapper-'));
+    createProteumApp(path.join(repoRoot, 'apps', 'product'));
+
+    const result = spawnSync(process.execPath, [cliBin, 'dev', 'list'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    const payload = JSON.parse(result.stdout);
+
+    assert.equal(result.status, 1);
+    assert.equal(payload.ok, false);
+    assert.match(payload.nextActions[0].command, /cd "apps\/product"/);
+    assert.match(payload.nextActions[0].command, /npx proteum dev --session-file/);
+});
+
+test('runtime status manifest guard points to explain manifest', () => {
+    const result = spawnSync(process.execPath, [cliBin, 'runtime', 'status', '--manifest'], {
+        cwd: coreRoot,
+        encoding: 'utf8',
+    });
+    const payload = JSON.parse(result.stdout);
+
+    assert.equal(result.status, 1);
+    assert.equal(payload.ok, false);
+    assert.match(payload.summary, /not supported/);
+    assert.match(payload.nextActions[0].command, /proteum explain --manifest/);
+});
+
+test('runtime status reports occupied configured port without probing page bodies', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-port-'));
+    const otherRoot = path.join(repoRoot, 'apps', 'other');
+    const appRoot = path.join(repoRoot, 'apps', 'product');
+    const server = http.createServer((req, res) => {
+        if (req.url && req.url.startsWith('/__proteum/explain')) {
+            res.setHeader('content-type', 'application/json');
+            res.end(
+                JSON.stringify({
+                    app: {
+                        root: otherRoot,
+                        identity: { identifier: 'OtherApp', name: 'Other' },
+                    },
+                }),
+            );
+            return;
+        }
+
+        res.setHeader('content-type', 'text/html');
+        res.end('<html><body>large wrong app page that should never be included</body></html>');
+    });
+    const occupiedPort = await listen(server);
+
+    try {
+        createProteumApp(appRoot, { routerPort: occupiedPort });
+
+        const result = await runCli(['runtime', 'status'], {
+            cwd: appRoot,
+        });
+        const payload = JSON.parse(result.stdout);
+
+        assert.equal(result.status, 0);
+        assert.equal(payload.ok, true);
+        assert.equal(payload.data.configuredDevPort.router.port, occupiedPort);
+        assert.equal(payload.data.configuredDevPort.router.available, false);
+        assert.equal(payload.data.configuredDevPort.router.proteum, true);
+        assert.equal(payload.data.configuredDevPort.router.matchesApp, false);
+        assert.equal(payload.data.configuredDevPort.router.app.identifier, 'OtherApp');
+        assert.notEqual(payload.data.configuredDevPort.recommendedPort, occupiedPort);
+        assert.match(payload.summary, /occupied by OtherApp/);
+        assert.match(payload.nextActions[0].command, /(npx )?proteum dev --session-file/);
+        assert.doesNotMatch(payload.nextActions[0].command, new RegExp(`--port ${occupiedPort}(\\D|$)`));
+        assert.match(payload.nextActions[0].reason, /do not probe page bodies/);
+        assert.doesNotMatch(result.stdout, /large wrong app page/);
+        assert.doesNotMatch(result.stdout, /<html>/);
+    } finally {
+        await closeServer(server);
+    }
+});
+
+test('runtime status avoids starting a second dev server when the same app owns the port', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-same-port-'));
+    const appRoot = path.join(repoRoot, 'apps', 'product');
+    const server = http.createServer((req, res) => {
+        if (req.url && req.url.startsWith('/__proteum/explain')) {
+            res.setHeader('content-type', 'application/json');
+            res.end(
+                JSON.stringify({
+                    app: {
+                        root: appRoot,
+                        identity: { identifier: 'ProductApp', name: 'Product' },
+                    },
+                }),
+            );
+            return;
+        }
+
+        res.setHeader('content-type', 'text/html');
+        res.end('<html><body>same app page body that should not be included</body></html>');
+    });
+    const occupiedPort = await listen(server);
+
+    try {
+        createProteumApp(appRoot, { routerPort: occupiedPort });
+
+        const result = await runCli(['runtime', 'status'], {
+            cwd: appRoot,
+        });
+        const payload = JSON.parse(result.stdout);
+
+        assert.equal(result.status, 0);
+        assert.equal(payload.data.configuredDevPort.router.matchesApp, true);
+        assert.equal(payload.nextActions[0].label, 'Use Existing Runtime');
+        assert.match(payload.nextActions[0].command, new RegExp(`proteum diagnose "/" --port ${occupiedPort}`));
+        assert.match(payload.nextActions[0].reason, /Do not start a second dev server/);
+        assert.equal(payload.nextActions.some((action) => action.label === 'Start Dev'), false);
+        assert.doesNotMatch(result.stdout, /same app page body/);
+    } finally {
+        await closeServer(server);
+    }
+});