proteum 2.3.0 → 2.4.2

package/cli/presentation/commands.ts

@@ -21,6 +21,7 @@ export const proteumCommandNames = [
     'orient',
     'diagnose',
     'perf',
+    'db',
     'runtime',
     'mcp',
     'trace',
@@ -59,7 +60,7 @@ export const proteumRecommendedFlow: TRow[] = [
 export const proteumCommandGroups: Array<{ title: string; names: TProteumCommandName[] }> = [
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check', 'e2e'] },
-    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
+    { title: 'Manifest and contracts', names: ['connect', 'doctor', 'explain', 'orient', 'diagnose', 'perf', 'db', 'runtime', 'mcp', 'trace', 'command', 'session', 'verify'] },
     { title: 'Project scaffolding', names: ['init', 'configure', 'create', 'migrate'] },
 ];
 
@@ -128,7 +129,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root instruction files.',
             'Standalone mode writes tracked instruction files into the current Proteum app root.',
-            'Monorepo mode writes reusable root documents such as `AGENTS.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
+            'Monorepo mode writes reusable root documents such as `AGENTS.md`, `DOCUMENTATION.md`, `CODING_STYLE.md`, `diagnostics.md`, and `optimizations.md` into the chosen monorepo root, then writes only app-root and area instruction files into the current Proteum app root.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],
@@ -170,11 +171,14 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Start the app on its configured router port', command: 'proteum dev' },
             {
                 description: 'Start a worktree or sibling checkout without changing your shell directory',
-                command: 'proteum dev --cwd /path/to/platform-worktree --port 3101 --replace-existing',
+                command: 'proteum dev --cwd /path/to/platform-worktree --port 3101',
             },
-            { description: 'Replace the tracked dev session on another port', command: 'proteum dev --port 3101 --replace-existing' },
             {
                 description: 'Start a tracked dev session with an explicit session file for an agent task',
+                command: 'proteum dev --port 3101 --session-file var/run/proteum/dev/agents/task.json',
+            },
+            {
+                description: 'Restart the exact tracked session file from the current task',
                 command: 'proteum dev --port 3101 --session-file var/run/proteum/dev/agents/task.json --replace-existing',
             },
             {
@@ -193,8 +197,9 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'Use `--cwd` when the target Proteum app lives in another worktree or checkout and you do not want to `cd` first.',
             'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
+            'Before registering a new session, Proteum removes stale same-worktree session files and fails fast if another live tracked session remains.',
             'Before the dev loop starts, Proteum ensures tracked instruction files contain the current managed `# Proteum Instructions` section.',
-            'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
+            'Use `--replace-existing` only when retrying the exact requested session file.',
             '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
             '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',
             '`proteum dev` clears the interactive terminal once at startup, then shows `CTRL+R` reload and `CTRL+C` shutdown hotkeys in the session banner.',
@@ -359,11 +364,15 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         examples: [
             { description: 'Show the default compact agent summary', command: 'proteum explain' },
             {
-                description: 'Inspect generated routes, controllers, and commands together',
+                description: 'Summarize generated routes, controllers, and commands together',
                 command: 'proteum explain --routes --controllers --commands',
             },
             {
-                description: 'Inspect configured connected projects and imported controllers',
+                description: 'Emit selected route/controller/command arrays only when needed',
+                command: 'proteum explain --routes --controllers --commands --full',
+            },
+            {
+                description: 'Summarize configured connected projects and imported controllers',
                 command: 'proteum explain --connected --controllers',
             },
             { description: 'Resolve the most likely manifest owner for a path or file', command: 'proteum explain owner /api/Auth/CurrentUser' },
@@ -371,7 +380,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'Default output is compact `proteum-agent-v1` JSON because the CLI is optimized for agents.',
-            '`--full`, `--manifest`, or explicit section flags are the escape hatch for large details.',
+            'Explicit section flags summarize those sections by default; add `--full` or use `--manifest` for raw manifest arrays.',
             'Legacy positional section selection remains supported, for example `proteum explain routes services`.',
             '`proteum explain owner <query>` ranks matching routes, controllers, services, commands, layouts, and diagnostics from the manifest.',
             'Connected projects are emitted from explicit `proteum.config.ts` `connect.<Namespace>.*` values plus the resolved connected contract.',
@@ -391,7 +400,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             { description: 'Use a running dev server when the local manifest is unavailable', command: 'proteum orient /domains --port 3101' },
         ],
         notes: [
-            'Default output is compact `proteum-agent-v1` JSON with `mustRead`, conditional docs, owner matches, and next commands.',
+            'Default output is compact `proteum-agent-v1` JSON with `mustRead`, triggered instruction files, conditional docs, owner matches, and next commands.',
             'Use it before reading source when the query might map to generated code, connected imports, framework-owned files, or area instructions.',
             'When `--port` or `--url` is provided, Proteum can read the manifest from a running dev server instead of only from disk.',
         ],
@@ -444,6 +453,26 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         status: 'experimental',
     },
+    db: {
+        name: 'db',
+        category: 'Manifest and contracts',
+        summary: 'Run one capped read-only database diagnostic query against a running Proteum dev server.',
+        usage: 'proteum db [query] <sql> [--limit <rows>] [--timeout <ms>] [--port <port>|--url <baseUrl>] [--full]',
+        bestFor:
+            'Inspecting live MySQL or MariaDB state during diagnosis without giving agents a write-capable SQL execution surface.',
+        examples: [
+            { description: 'Run a small SELECT diagnostic', command: 'proteum db query "SELECT id, email FROM User LIMIT 5"' },
+            { description: 'Inspect table metadata', command: 'proteum db "SHOW TABLES"' },
+            { description: 'Explain a query plan', command: 'proteum db query "EXPLAIN SELECT * FROM User WHERE id = 1"' },
+        ],
+        notes: [
+            'Only SELECT, SHOW, and EXPLAIN statements are allowed.',
+            'The dev runtime executes the query with the app DATABASE_URL and returns rows, columns, elapsedMs, and cap metadata.',
+            'Multi-statement SQL, EXPLAIN ANALYZE, locking reads, LOAD_FILE, SELECT INTO OUTFILE, sleep, and benchmark functions are rejected.',
+            'Default output is compact `proteum-agent-v1` JSON with capped rows; use `--full` for the raw dev endpoint payload.',
+        ],
+        status: 'experimental',
+    },
     runtime: {
         name: 'runtime',
         category: 'Manifest and contracts',
@@ -457,6 +486,10 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         ],
         notes: [
             'Default output is compact `proteum-agent-v1` JSON with the selected session, health, and next command.',
+            'When no tracked session exists, the configured router and HMR ports are inspected before suggesting Start Dev.',
+            'If the same app already responds on the configured port, the next action uses or repairs that runtime instead of starting a second server.',
+            'The selected live session includes its dev-hosted MCP URL when available.',
+            'Use this command instead of curling page routes to identify port ownership.',
             'Use `--full` to include every tracked session field.',
         ],
         status: 'experimental',
@@ -464,26 +497,24 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     mcp: {
         name: 'mcp',
         category: 'Manifest and contracts',
-        summary: 'Start a read-only Proteum MCP server for compact agent diagnostics and runtime data.',
-        usage: 'proteum mcp [--cwd <path>] [--url <baseUrl>] [--session-file <path>]',
+        summary: 'Start or attach to the machine-scope MCP router for live Proteum dev projects.',
+        usage: 'proteum mcp [status|stop] [--stdio|--daemon] [--port <port>]',
         bestFor:
-            'Agent integrations that need repeated low-token access to Proteum manifest, instruction routing, runtime status, trace, perf, diagnose, and log summaries.',
+            'Registering a single MCP server in an LLM and keeping one managed machine daemon available while dev servers run.',
         examples: [
-            { description: 'Start the MCP server for the current app over stdio', command: 'proteum mcp' },
-            {
-                description: 'Point the MCP server at a running dev server',
-                command: 'proteum mcp --url http://localhost:3101',
-            },
-            {
-                description: 'Resolve runtime data from an explicit tracked session file',
-                command: 'proteum mcp --session-file var/run/proteum/dev/agents/task.json',
-            },
+            { description: 'Start or reuse the managed machine MCP daemon from a terminal', command: 'proteum mcp' },
+            { description: 'Force stdio MCP transport for an MCP client', command: 'proteum mcp --stdio' },
+            { description: 'Inspect the managed machine MCP daemon', command: 'proteum mcp status' },
         ],
         notes: [
-            '`proteum mcp` is read-only in v1 and does not start/stop dev servers, refresh generated code, write files, or mutate traces.',
-            'Tool and resource payloads are compact single-line `proteum-mcp-v1` JSON for low-token agent reads.',
-            'Use the CLI for reproducible build/dev/check workflows; use MCP for repeated agent reads and progressive detail loading.',
-            'A running `proteum dev` server also exposes the same tool contract at `/__proteum/mcp` for runtime-adjacent access.',
+            '`proteum dev` ensures one managed machine MCP daemon is running before the app dev loop starts.',
+            '`proteum mcp` is a router, not an app dev server. It discovers live `proteum dev` sessions from the machine registry and can resolve offline app candidates from `cwd`.',
+            'Agents should call MCP `workflow_start` with `cwd` or a known `projectId`; use `project_resolve { cwd }` when routing is ambiguous or no live dev server exists yet.',
+            'When an offline app candidate is returned, start exactly one `proteum dev` from that app root before runtime diagnose, trace, or perf reads.',
+            'After an MCP read succeeds, agents should not run the equivalent CLI command or broad owner search for the same runtime state.',
+            'App runtime data still comes from the selected dev-hosted `/__proteum/mcp` endpoint.',
+            'Only one managed machine MCP daemon may run at a time; stale daemon records are cleaned automatically.',
+            'MCP remains read-only and optimized for compact `proteum-mcp-v1` payloads.',
         ],
         status: 'experimental',
     },

package/cli/presentation/help.ts

@@ -174,7 +174,7 @@ export const renderCommandHelp = async ({
     const notes = [...(command.notes ?? [])];
 
     if (commandName === 'init') notes.push(getInitAvailabilityNote(initAvailable));
-    if (commandName !== 'init' && !isLikelyProteumAppRoot(workdir)) {
+    if (commandName !== 'init' && commandName !== 'mcp' && !isLikelyProteumAppRoot(workdir)) {
         notes.push(
             'This command expects to run inside a Proteum app root. The current directory does not contain the usual `client/` and `server/` folders.',
         );

package/cli/runtime/commands.ts

@@ -1,8 +1,72 @@
 import { Builtins, Cli, Option } from 'clipanion';
+import path from 'path';
 
-import type { TArgsObject } from '../context';
+import cli, { type TArgsObject } from '../context';
 import { applyLegacyBooleanArgs, assertNoLegacyArgs } from './argv';
 import { buildUsage, ProteumCommand, runCommandModule } from './command';
+import { createStartDevCommand, quoteShellPath, resolveProteumAppRootContext } from '../utils/appRoots';
+import { printJson } from '../utils/agentOutput';
+
+const createRunInAppCommand = ({
+    appRoot,
+    baseRoot,
+    command,
+}: {
+    appRoot: string;
+    baseRoot: string;
+    command: string;
+}) => {
+    const relativeAppRoot = path.relative(baseRoot, appRoot) || '.';
+    if (relativeAppRoot === '.') return command;
+    return `cd ${quoteShellPath(relativeAppRoot)} && ${command}`;
+};
+
+const printNonAppRootResponse = ({
+    commandName,
+    cwd,
+}: {
+    commandName: 'dev' | 'runtime';
+    cwd: string;
+}) => {
+    const context = resolveProteumAppRootContext(cwd);
+    const appCandidates = context.appCandidates;
+    const commandLabel = commandName === 'dev' ? 'Dev' : 'Runtime Status';
+
+    printJson({
+        ok: false,
+        format: 'proteum-agent-v1',
+        summary:
+            appCandidates.length > 0
+                ? `${cwd} is a Proteum workspace wrapper or nested directory, not an app root. Found ${appCandidates.length} app candidate${appCandidates.length === 1 ? '' : 's'}.`
+                : `${cwd} is not a Proteum app root.`,
+        data: {
+            cwd: context.cwd,
+            appCandidates,
+        },
+        nextActions: appCandidates.map((candidate) => ({
+            label: `${commandLabel}: ${candidate.relativeAppRoot || candidate.appRoot}`,
+            command:
+                commandName === 'dev'
+                    ? createStartDevCommand({
+                          appRoot: candidate.appRoot,
+                          baseRoot: context.cwd,
+                          port: candidate.manifest?.routerPort,
+                      })
+                    : createRunInAppCommand({
+                          appRoot: candidate.appRoot,
+                          baseRoot: context.cwd,
+                          command: 'npx proteum runtime status',
+                      }),
+            reason:
+                commandName === 'dev'
+                    ? 'Start Proteum dev from the app root, not the workspace wrapper.'
+                    : 'Inspect tracked runtime sessions from the app root, not the workspace wrapper.',
+        })),
+    });
+    process.exitCode = 1;
+};
+
+const isCurrentWorkdirProteumAppRoot = () => resolveProteumAppRootContext(String(cli.args.workdir || process.cwd())).isAppRoot;
 
 class InitCommand extends ProteumCommand {
     public static paths = [['init']];
@@ -154,6 +218,10 @@ class DevCommand extends ProteumCommand {
             all: this.all,
             stale: this.stale,
         });
+        if (!isCurrentWorkdirProteumAppRoot()) {
+            printNonAppRootResponse({ commandName: 'dev', cwd: String(cli.args.workdir || process.cwd()) });
+            return 1;
+        }
         await runCommandModule(() => import('../commands/dev'));
     }
 }
@@ -371,18 +439,18 @@ class ExplainCommand extends ProteumCommand {
     public full = Option.Boolean('--full', false, { description: 'Print the full selected machine-readable detail.' });
     public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public manifest = Option.Boolean('--manifest', false, { description: 'Print the full generated manifest.' });
-    public all = Option.Boolean('--all', false, { description: 'Include every explain section.' });
-    public app = Option.Boolean('--app', false, { description: 'Include the app section.' });
-    public conventions = Option.Boolean('--conventions', false, { description: 'Include the conventions section.' });
-    public env = Option.Boolean('--env', false, { description: 'Include the env section.' });
-    public connected = Option.Boolean('--connected', false, { description: 'Include the connected-projects section.' });
-    public services = Option.Boolean('--services', false, { description: 'Include the services section.' });
-    public controllers = Option.Boolean('--controllers', false, { description: 'Include the controllers section.' });
-    public commands = Option.Boolean('--commands', false, { description: 'Include the commands section.' });
-    public routes = Option.Boolean('--routes', false, { description: 'Include the routes section.' });
-    public layouts = Option.Boolean('--layouts', false, { description: 'Include the layouts section.' });
+    public all = Option.Boolean('--all', false, { description: 'Summarize every explain section; add --full for raw arrays.' });
+    public app = Option.Boolean('--app', false, { description: 'Summarize the app section; add --full for raw detail.' });
+    public conventions = Option.Boolean('--conventions', false, { description: 'Summarize the conventions section; add --full for raw detail.' });
+    public env = Option.Boolean('--env', false, { description: 'Summarize the env section; add --full for raw detail.' });
+    public connected = Option.Boolean('--connected', false, { description: 'Summarize the connected-projects section; add --full for raw detail.' });
+    public services = Option.Boolean('--services', false, { description: 'Summarize the services section; add --full for raw detail.' });
+    public controllers = Option.Boolean('--controllers', false, { description: 'Summarize the controllers section; add --full for raw detail.' });
+    public commands = Option.Boolean('--commands', false, { description: 'Summarize the commands section; add --full for raw detail.' });
+    public routes = Option.Boolean('--routes', false, { description: 'Summarize the routes section; add --full for raw detail.' });
+    public layouts = Option.Boolean('--layouts', false, { description: 'Summarize the layouts section; add --full for raw detail.' });
     public diagnostics = Option.Boolean('--diagnostics', false, {
-        description: 'Include the diagnostics section.',
+        description: 'Summarize the diagnostics section; add --full for raw detail.',
     });
     public args = Option.Rest();
 
@@ -627,12 +695,47 @@ class PerfCommand extends ProteumCommand {
     }
 }
 
+class DbCommand extends ProteumCommand {
+    public static paths = [['db']];
+
+    public static usage = buildUsage('db');
+
+    public port = Option.String('--port', { description: 'Target an existing dev server on the given port.' });
+    public url = Option.String('--url', { description: 'Target an existing dev server at the given base URL.' });
+    public limit = Option.String('--limit', { description: 'Maximum number of result rows to return, up to 500.' });
+    public timeout = Option.String('--timeout', { description: 'Database query timeout in milliseconds, up to 30000.' });
+    public json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    public full = Option.Boolean('--full', false, { description: 'Print the full database query payload.' });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [first = '', ...restArgs] = this.args;
+        const sql = first === 'query' ? restArgs.join(' ').trim() : [first, ...restArgs].join(' ').trim();
+
+        this.setCliArgs({
+            action: 'query',
+            full: this.full,
+            json: this.json,
+            limit: this.limit ?? '',
+            port: this.port ?? '',
+            sql,
+            timeout: this.timeout ?? '',
+            url: this.url ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/db'));
+    }
+}
+
 class RuntimeCommand extends ProteumCommand {
     public static paths = [['runtime']];
 
     public static usage = buildUsage('runtime');
 
     public full = Option.Boolean('--full', false, { description: 'Print full tracked-session and health detail.' });
+    public manifest = Option.Boolean('--manifest', false, {
+        description: 'Unsupported compatibility guard. Use `proteum explain --manifest` instead.',
+    });
     public sessionFile = Option.String('--session-file', {
         description: 'Inspect one explicit dev session file instead of the app registry.',
     });
@@ -644,9 +747,35 @@ class RuntimeCommand extends ProteumCommand {
         this.setCliArgs({
             action,
             full: this.full,
+            manifest: this.manifest,
             sessionFile: this.sessionFile ?? '',
         });
 
+        if (this.manifest) {
+            printJson({
+                ok: false,
+                format: 'proteum-agent-v1',
+                summary: '`proteum runtime status --manifest` is not supported. Use `proteum explain --manifest` from the app root.',
+                data: {
+                    command: 'proteum runtime status --manifest',
+                },
+                nextActions: [
+                    {
+                        label: 'Explain Manifest',
+                        command: 'npx proteum explain --manifest',
+                        reason: 'The generated manifest belongs to the explain command, not runtime status.',
+                    },
+                ],
+            });
+            process.exitCode = 1;
+            return 1;
+        }
+
+        if (!isCurrentWorkdirProteumAppRoot()) {
+            printNonAppRootResponse({ commandName: 'runtime', cwd: String(cli.args.workdir || process.cwd()) });
+            return 1;
+        }
+
         await runCommandModule(() => import('../commands/runtime'));
     }
 }
@@ -656,19 +785,30 @@ class McpCommand extends ProteumCommand {
 
     public static usage = buildUsage('mcp');
 
-    public cwd = Option.String('--cwd', { description: 'Run the MCP server against another Proteum app root.' });
-    public sessionFile = Option.String('--session-file', {
-        description: 'Inspect one explicit dev session file when resolving runtime data.',
+    public daemon = Option.Boolean('--daemon', false, {
+        description: 'Run the managed machine-scope MCP daemon over local HTTP.',
     });
-    public url = Option.String('--url', { description: 'Use a running Proteum dev server as the live runtime data source.' });
-    public legacyArgs = Option.Rest();
+    public stdio = Option.Boolean('--stdio', false, {
+        description: 'Force stdio MCP transport for an MCP client.',
+    });
+    public port = Option.String('--port', {
+        description: 'Port for the managed machine MCP daemon.',
+    });
+    public json = Option.Boolean('--json', false, {
+        description: 'Print machine-readable daemon status output.',
+    });
+    public args = Option.Rest();
 
     public async execute() {
-        assertNoLegacyArgs('mcp', this.legacyArgs);
+        const [action = 'start', ...restArgs] = this.args;
+
+        assertNoLegacyArgs('mcp', restArgs);
         this.setCliArgs({
-            sessionFile: this.sessionFile ?? '',
-            url: this.url ?? '',
-            workdir: this.cwd ?? '',
+            action,
+            daemon: this.daemon,
+            stdio: this.stdio,
+            port: this.port ?? '',
+            json: this.json,
         });
 
         await runCommandModule(() => import('../commands/mcp'));
@@ -751,6 +891,7 @@ export const registeredCommands = {
     orient: OrientCommand,
     diagnose: DiagnoseCommand,
     perf: PerfCommand,
+    db: DbCommand,
     runtime: RuntimeCommand,
     mcp: McpCommand,
     trace: TraceCommand,
@@ -786,6 +927,7 @@ export const createCli = (version: string) => {
     clipanion.register(OrientCommand);
     clipanion.register(DiagnoseCommand);
     clipanion.register(PerfCommand);
+    clipanion.register(DbCommand);
     clipanion.register(RuntimeCommand);
     clipanion.register(McpCommand);
     clipanion.register(TraceCommand);