proteum 2.3.0 → 2.4.2

package/cli/commands/explain.ts

@@ -42,8 +42,30 @@ const compactOwnerMatch = (match: ReturnType<typeof explainOwner>['matches'][num
     source: match.source,
 });
 
-const hasExplicitDetailSelection = (selectedSections: TExplainSectionName[]) =>
-    cli.args.full === true || cli.args.manifest === true || cli.args.all === true || selectedSections.length > 0;
+const hasExplicitDetailSelection = () => cli.args.full === true || cli.args.manifest === true;
+
+const buildSectionFlagCommand = (selectedSections: TExplainSectionName[]) =>
+    selectedSections.length === explainSectionNames.length
+        ? 'proteum explain --all --full'
+        : `proteum explain ${selectedSections.map((sectionName) => `--${sectionName}`).join(' ')} --full`;
+
+const summarizeSelectedSection = (manifest: ReturnType<typeof readProteumManifest>, sectionName: TExplainSectionName) => {
+    if (sectionName === 'app') return { section: sectionName, count: 1 };
+    if (sectionName === 'conventions')
+        return {
+            section: sectionName,
+            count: manifest.conventions.routeOptionKeys.length + manifest.conventions.reservedRouteOptionKeys.length,
+        };
+    if (sectionName === 'env') return { section: sectionName, count: manifest.env.requiredVariables.length };
+    if (sectionName === 'connected') return { section: sectionName, count: manifest.connectedProjects.length };
+    if (sectionName === 'services')
+        return { section: sectionName, count: manifest.services.app.length + manifest.services.routerPlugins.length };
+    if (sectionName === 'controllers') return { section: sectionName, count: manifest.controllers.length };
+    if (sectionName === 'commands') return { section: sectionName, count: manifest.commands.length };
+    if (sectionName === 'routes') return { section: sectionName, count: manifest.routes.client.length + manifest.routes.server.length };
+    if (sectionName === 'layouts') return { section: sectionName, count: manifest.layouts.length };
+    return { section: sectionName, count: manifest.diagnostics.length };
+};
 
 const printCompactOwner = (ownerQuery: string, response: ReturnType<typeof explainOwner>) => {
     const topOwner = response.matches[0];
@@ -70,13 +92,17 @@ const printCompactOwner = (ownerQuery: string, response: ReturnType<typeof expla
     });
 };
 
-const printCompactExplain = (manifest: ReturnType<typeof readProteumManifest>) => {
+const printCompactExplain = (manifest: ReturnType<typeof readProteumManifest>, selectedSections: TExplainSectionName[] = []) => {
     const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
     const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
     const requiredEnvProvided = manifest.env.requiredVariables.filter((variable) => variable.provided).length;
+    const hasSelectedSections = selectedSections.length > 0;
+    const fullDetailCommand = hasSelectedSections ? buildSectionFlagCommand(selectedSections) : 'proteum explain --manifest';
 
     printAgentResponse({
-        summary: `${manifest.app.identity.identifier}: ${manifest.controllers.length} controllers, ${manifest.routes.client.length + manifest.routes.server.length} routes, ${errors} errors, ${warnings} warnings`,
+        summary: hasSelectedSections
+            ? `${manifest.app.identity.identifier}: summarized ${selectedSections.join(', ')} sections; use --full for raw section arrays`
+            : `${manifest.app.identity.identifier}: ${manifest.controllers.length} controllers, ${manifest.routes.client.length + manifest.routes.server.length} routes, ${errors} errors, ${warnings} warnings`,
         data: {
             app: {
                 root: manifest.app.root,
@@ -96,6 +122,7 @@ const printCompactExplain = (manifest: ReturnType<typeof readProteumManifest>) =
                 servicesRouterPlugins: manifest.services.routerPlugins.length,
             },
             diagnostics: { errors, warnings },
+            selectedSections: hasSelectedSections ? selectedSections.map((sectionName) => summarizeSelectedSection(manifest, sectionName)) : undefined,
             env: {
                 requiredProvided: requiredEnvProvided,
                 requiredTotal: manifest.env.requiredVariables.length,
@@ -110,11 +137,13 @@ const printCompactExplain = (manifest: ReturnType<typeof readProteumManifest>) =
                 reason: 'Use orient for task-specific owner, instruction, and next-command routing.',
             },
         ],
-        fullDetailCommand: 'proteum explain --manifest',
+        fullDetailCommand,
         omitted: [
             {
-                reason: 'Full manifest sections are omitted from the default agent summary.',
-                command: 'proteum explain --manifest',
+                reason: hasSelectedSections
+                    ? 'Selected manifest sections are summarized by default to avoid large route/controller dumps.'
+                    : 'Full manifest sections are omitted from the default agent summary.',
+                command: fullDetailCommand,
             },
         ],
     });
@@ -158,7 +187,7 @@ export const run = async (): Promise<void> => {
 
     const selectedSections = getSelectedSections();
 
-    if (hasExplicitDetailSelection(selectedSections)) {
+    if (hasExplicitDetailSelection()) {
         printJson(pickExplainManifestSections(manifest, cli.args.manifest === true ? [...explainSectionNames] : selectedSections));
         return;
     }
@@ -168,5 +197,5 @@ export const run = async (): Promise<void> => {
         return;
     }
 
-    printCompactExplain(manifest);
+    printCompactExplain(manifest, selectedSections);
 };

package/cli/commands/mcp.ts

@@ -1,16 +1,133 @@
 import cli from '..';
-import { CliProteumMcpProvider } from '../mcp/provider';
-import { startProteumMcpStdioServer } from '../mcp/stdio';
+import { startProteumMachineMcpRouter, startProteumMachineMcpRouterHttp } from '../mcp/router';
+import {
+    ensureMachineMcpDaemonProcess,
+    inspectMachineMcpDaemonRecord,
+    resolveMachineMcpDaemonPort,
+    stopMachineMcpDaemonProcess,
+} from '../runtime/mcpDaemon';
 
-export const run = async () => {
-    const provider = new CliProteumMcpProvider({
-        appRoot: cli.paths.appRoot,
-        sessionFilePath: typeof cli.args.sessionFile === 'string' && cli.args.sessionFile ? cli.args.sessionFile : undefined,
-        url: typeof cli.args.url === 'string' && cli.args.url ? cli.args.url : undefined,
+const printJson = (payload: unknown) => {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+};
+
+const printStatus = async () => {
+    const inspection = await inspectMachineMcpDaemonRecord({ cleanStale: true });
+
+    if (cli.args.json === true) {
+        printJson({
+            daemon: inspection
+                ? {
+                      live: inspection.live,
+                      stale: inspection.stale,
+                      invalid: inspection.invalid,
+                      parseError: inspection.parseError,
+                      record: inspection.record,
+                  }
+                : null,
+        });
+        return;
+    }
+
+    if (!inspection?.record || !inspection.live) {
+        console.info('No live Proteum machine MCP daemon found.');
+        return;
+    }
+
+    console.info(
+        [
+            `Proteum machine MCP daemon is running.`,
+            `pid ${inspection.record.pid}`,
+            `mcp ${inspection.record.mcpUrl}`,
+            `health ${inspection.record.healthUrl}`,
+        ].join('\n'),
+    );
+};
+
+const runDaemon = async () => {
+    const existing = await inspectMachineMcpDaemonRecord({ cleanStale: true });
+
+    if (existing?.record && existing.live && existing.record.pid !== process.pid) {
+        if (cli.args.json === true) {
+            printJson({ started: false, daemon: existing.record });
+            return;
+        }
+
+        console.info(`Proteum machine MCP daemon is already running at ${existing.record.mcpUrl} (pid ${existing.record.pid}).`);
+        return;
+    }
+
+    const port = resolveMachineMcpDaemonPort(typeof cli.args.port === 'string' ? cli.args.port : undefined);
+
+    await startProteumMachineMcpRouterHttp({
+        port,
+        version: String(cli.packageJson.version || ''),
     });
 
-    await startProteumMcpStdioServer({
-        provider,
+    if (cli.args.json === true) {
+        printJson({
+            started: true,
+            daemon: {
+                pid: process.pid,
+                mcpUrl: `http://127.0.0.1:${port}/mcp`,
+                healthUrl: `http://127.0.0.1:${port}/health`,
+            },
+        });
+    } else {
+        console.info(`Proteum machine MCP daemon started at http://127.0.0.1:${port}/mcp.`);
+    }
+};
+
+const ensureDaemon = async () => {
+    const result = await ensureMachineMcpDaemonProcess({
+        coreRoot: cli.paths.core.root,
+        port: typeof cli.args.port === 'string' ? cli.args.port : undefined,
+    });
+
+    if (cli.args.json === true) {
+        printJson({ started: result.started, daemon: result.inspection.record });
+        return;
+    }
+
+    if (result.inspection.record) {
+        console.info(
+            result.started
+                ? `Proteum machine MCP daemon started at ${result.inspection.record.mcpUrl}.`
+                : `Proteum machine MCP daemon is already running at ${result.inspection.record.mcpUrl}.`,
+        );
+    }
+};
+
+export const run = async () => {
+    if (cli.args.action === 'status') {
+        await printStatus();
+        return;
+    }
+
+    if (cli.args.action === 'stop') {
+        const result = await stopMachineMcpDaemonProcess();
+        if (cli.args.json === true) {
+            printJson({ stopped: result.stopped, daemon: result.inspection?.record || null });
+        } else if (result.stopped) {
+            console.info('Proteum machine MCP daemon stopped.');
+        } else if (result.inspection?.record) {
+            console.info(`Could not stop Proteum machine MCP daemon pid ${result.inspection.record.pid}.`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+
+    if (cli.args.daemon === true) {
+        await runDaemon();
+        return;
+    }
+
+    if (cli.args.stdio !== true && (process.stdout.isTTY || cli.args.json === true)) {
+        await ensureDaemon();
+        return;
+    }
+
+    await startProteumMachineMcpRouter({
         version: String(cli.packageJson.version || ''),
     });
 };

package/cli/commands/orient.ts

@@ -7,6 +7,7 @@ import cli from '..';
 import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import { buildOrientationResponse, type TOrientResponse } from '@common/dev/inspection';
+import { resolveTriggeredInstructionReads } from '@common/dev/mcpPayloads';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
 import { compactList, printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 
@@ -125,6 +126,7 @@ const renderHuman = (response: TOrientResponse) =>
         ...(response.app.routerPort ? [`- routerPort=${response.app.routerPort}`] : []),
         'Guidance',
         `- agents=${response.guidance.agents}`,
+        `- documentation=${response.guidance.documentation}`,
         `- diagnostics=${response.guidance.diagnostics}`,
         `- optimizations=${response.guidance.optimizations}`,
         `- codingStyle=${response.guidance.codingStyle}`,
@@ -163,23 +165,48 @@ const compactOwnerMatch = (match: TOrientResponse['owner']['matches'][number]) =
     source: match.source,
 });
 
-const buildInstructionPlan = (response: TOrientResponse) => ({
-    mustRead: [...new Set([response.guidance.agents, ...response.guidance.areaAgents])],
-    readWhen: [
-        {
-            file: response.guidance.diagnostics,
-            when: 'Read only for raw errors, failing requests, traces, perf regressions, or reproduction work.',
-        },
-        {
-            file: response.guidance.codingStyle,
-            when: 'Read before editing implementation files.',
-        },
-        {
-            file: response.guidance.optimizations,
-            when: 'Read after client-side implementation or when the task explicitly concerns packages, build, runtime, or performance.',
-        },
-    ],
-});
+const buildInstructionPlan = (response: TOrientResponse) => {
+    const triggered = resolveTriggeredInstructionReads({
+        codingStyle: response.guidance.codingStyle,
+        diagnostics: response.guidance.diagnostics,
+        documentation: response.guidance.documentation,
+        optimizations: response.guidance.optimizations,
+        query: response.normalizedQuery || response.query,
+        rootAgentsFile:
+            response.app.repoRoot !== response.app.appRoot
+                ? path.join(response.app.repoRoot, 'AGENTS.md')
+                : response.guidance.agents,
+    });
+
+    return {
+        mustRead: [
+            ...new Set([
+                response.guidance.agents,
+                ...response.guidance.areaAgents,
+                ...triggered.map((entry) => entry.file),
+            ]),
+        ],
+        triggered,
+        readWhen: [
+            {
+                file: response.guidance.documentation,
+                when: 'Read before non-trivial coding tasks to choose the smallest `/docs` pack and update docs after changes.',
+            },
+            {
+                file: response.guidance.diagnostics,
+                when: 'Read only for raw errors, failing requests, traces, perf regressions, or reproduction work.',
+            },
+            {
+                file: response.guidance.codingStyle,
+                when: 'Read before editing implementation files.',
+            },
+            {
+                file: response.guidance.optimizations,
+                when: 'Read after client-side implementation or when the task explicitly concerns packages, build, runtime, or performance.',
+            },
+        ],
+    };
+};
 
 const printCompactOrient = (response: TOrientResponse) => {
     const topOwner = response.owner.matches[0];

package/cli/commands/runtime.ts

@@ -5,7 +5,8 @@ import { UsageError } from 'clipanion';
 
 import cli from '..';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
-import { listDevSessionInspections, type TDevSessionInspection } from '../runtime/devSessions';
+import { listDevSessionInspections, writeMachineDevSessionRecord, type TDevSessionInspection } from '../runtime/devSessions';
+import { inspectDevPort, type TDevPortInspection } from '../runtime/ports';
 import { printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 import type { TDoctorResponse } from '@common/dev/diagnostics';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
@@ -40,6 +41,11 @@ const getSessionUrl = (inspection: TDevSessionInspection) => {
     return `http://localhost:${inspection.record.routerPort}`;
 };
 
+const getSessionMcpUrl = (inspection: TDevSessionInspection) => {
+    const sessionUrl = getSessionUrl(inspection);
+    return sessionUrl ? `${sessionUrl}/__proteum/mcp` : '';
+};
+
 const probeDoctor = async (baseUrl: string) => {
     if (!baseUrl) return { reachable: false, error: 'No dev URL is registered.' };
 
@@ -78,11 +84,90 @@ const compactSession = (inspection: TDevSessionInspection) => ({
     pid: inspection.record?.pid,
     routerPort: inspection.record?.routerPort,
     publicUrl: inspection.record?.publicUrl,
+    mcpUrl: inspection.record ? getSessionMcpUrl(inspection) : undefined,
     state: inspection.record?.state,
     startedAt: inspection.record?.startedAt,
     updatedAt: inspection.record?.updatedAt,
 });
 
+const createStartDevCommand = (port?: number) =>
+    `proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port ${port || '<free-port>'}`;
+
+const describePortOwner = (portInspection?: TDevPortInspection) => {
+    if (!portInspection || portInspection.router.available) return '';
+    if (portInspection.router.proteum) {
+        const appLabel =
+            portInspection.router.app?.identifier ||
+            portInspection.router.app?.name ||
+            portInspection.router.app?.appRoot ||
+            'another Proteum app';
+        return `Configured router port ${portInspection.router.port} is already occupied by ${appLabel}.`;
+    }
+
+    return `Configured router port ${portInspection.router.port} is already occupied by a non-Proteum or unrecognized process.`;
+};
+
+const getNextActions = ({
+    health,
+    portInspection,
+    selectedSession,
+}: {
+    health: { reachable: boolean };
+    portInspection?: TDevPortInspection;
+    selectedSession: TDevSessionInspection | undefined;
+}) => {
+    if (!selectedSession?.record || !selectedSession.live) {
+        const portOwner = describePortOwner(portInspection);
+
+        if (portInspection?.router.proteum && portInspection.router.matchesApp) {
+            return [
+                {
+                    label: 'Use Existing Runtime',
+                    command: `proteum diagnose ${quoteCommandArgument('/')} --port ${portInspection.router.port}`,
+                    reason:
+                        'A Proteum runtime for this app already responds on the configured router port, but no tracked session file is live. Do not start a second dev server; use this port for CLI evidence or stop the owning process before starting a tracked session.',
+                },
+            ];
+        }
+
+        const startPort =
+            portInspection && !portInspection.canStartOnConfiguredPort ? portInspection.recommendedPort : portInspection?.router.port;
+
+        return [
+            {
+                label: 'Start Dev',
+                command: createStartDevCommand(startPort),
+                reason: portOwner
+                    ? `${portOwner} Use an alternate free router/HMR port pair; do not probe page bodies to identify port owners.`
+                    : 'Create a tracked dev session before request-time diagnostics.',
+            },
+        ];
+    }
+
+    if (!health.reachable) {
+        return [
+            {
+                label: 'Stop Unreachable Dev',
+                command: `proteum dev stop --session-file ${quoteCommandArgument(selectedSession.sessionFilePath)}`,
+                reason: 'A tracked session exists but the runtime and MCP endpoint are unreachable.',
+            },
+            {
+                label: 'Start Dev',
+                command: createStartDevCommand(portInspection?.recommendedPort),
+                reason: 'Start a fresh tracked session after stopping the unreachable one.',
+            },
+        ];
+    }
+
+    return [
+        {
+            label: 'Diagnose Root',
+            command: `proteum diagnose ${quoteCommandArgument('/')} --port ${selectedSession.record.routerPort}`,
+            reason: 'Use the selected runtime for the smallest request-level diagnostic pass.',
+        },
+    ];
+};
+
 export const run = async () => {
     const action = getAction();
     if (action !== 'status') return;
@@ -93,10 +178,21 @@ export const run = async () => {
         sessionFilePath: typeof cli.args.sessionFile === 'string' && cli.args.sessionFile ? cli.args.sessionFile : undefined,
     });
     const liveSessions = sessions.filter((inspection) => inspection.live && inspection.record);
+    await Promise.allSettled(
+        liveSessions.map((inspection) =>
+            inspection.record ? writeMachineDevSessionRecord(inspection.record) : Promise.resolve(undefined),
+        ),
+    );
     const selectedSession =
         liveSessions.find((inspection) => inspection.record?.state === 'ready') || liveSessions[0] || sessions.find((inspection) => inspection.record);
     const selectedBaseUrl = selectedSession ? getSessionUrl(selectedSession) : '';
     const health = selectedSession && selectedSession.live ? await probeDoctor(selectedBaseUrl) : { reachable: false, error: 'No live tracked dev session.' };
+    const configuredDevPort = manifest
+        ? await inspectDevPort({
+              appRoot: cli.paths.appRoot,
+              port: manifest.env.resolved.routerPort,
+          })
+        : undefined;
 
     const payload = {
         appRoot: cli.paths.appRoot,
@@ -119,6 +215,7 @@ export const run = async () => {
         selected: selectedSession ? compactSession(selectedSession) : undefined,
         sessions: sessions.map(compactSession),
         health,
+        configuredDevPort,
     };
 
     if (cli.args.full === true) {
@@ -129,23 +226,9 @@ export const run = async () => {
     printAgentResponse({
         summary: selectedSession
             ? `${selectedSession.live ? 'live' : 'stale'} dev session on ${selectedSession.record?.routerPort || 'unknown port'}; health=${health.reachable ? 'reachable' : 'unreachable'}`
-            : 'No tracked Proteum dev session found.',
+            : describePortOwner(configuredDevPort) || 'No tracked Proteum dev session found.',
         data: payload,
-        nextActions: selectedSession?.record
-            ? [
-                  {
-                      label: 'Diagnose Root',
-                      command: `proteum diagnose ${quoteCommandArgument('/')} --port ${selectedSession.record.routerPort}`,
-                      reason: 'Use the selected runtime for the smallest request-level diagnostic pass.',
-                  },
-              ]
-            : [
-                  {
-                      label: 'Start Dev',
-                      command: 'proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port <free-port>',
-                      reason: 'Create a tracked dev session before request-time diagnostics.',
-                  },
-              ],
+        nextActions: getNextActions({ health, portInspection: configuredDevPort, selectedSession }),
         fullDetailCommand: 'proteum runtime status --full',
     });
 };