proteum 2.2.9 → 2.4.1

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'));
     }
 }
@@ -324,14 +392,16 @@ class ConnectCommand extends ProteumCommand {
     public controllers = Option.Boolean('--controllers', false, {
         description: 'Include imported connected controllers in the output.',
     });
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    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 connect payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any connect diagnostics exist.' });
     public legacyArgs = Option.Rest();
 
     public async execute() {
-        const args = { controllers: this.controllers, json: this.json, strict: this.strict } satisfies TArgsObject;
+        const args = { controllers: this.controllers, full: this.full, human: this.human, json: this.json, strict: this.strict } satisfies TArgsObject;
 
-        applyLegacyBooleanArgs('connect', this.legacyArgs, ['controllers', 'json', 'strict'], args);
+        applyLegacyBooleanArgs('connect', this.legacyArgs, ['controllers', 'full', 'human', 'json', 'strict'], args);
         this.setCliArgs(args);
         await runCommandModule(() => import('../commands/connect'));
     }
@@ -345,14 +415,16 @@ class DoctorCommand extends ProteumCommand {
     public contracts = Option.Boolean('--contracts', false, {
         description: 'Run contract-focused diagnostics for generated artifacts and manifest-owned source files.',
     });
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    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 doctor payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public strict = Option.Boolean('--strict', false, { description: 'Exit with failure if any diagnostics exist.' });
     public legacyArgs = Option.Rest();
 
     public async execute() {
-        const args = { contracts: this.contracts, json: this.json, strict: this.strict } satisfies TArgsObject;
+        const args = { contracts: this.contracts, full: this.full, human: this.human, json: this.json, strict: this.strict } satisfies TArgsObject;
 
-        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['contracts', 'json', 'strict'], args);
+        applyLegacyBooleanArgs('doctor', this.legacyArgs, ['contracts', 'full', 'human', 'json', 'strict'], args);
         this.setCliArgs(args);
         await runCommandModule(() => import('../commands/doctor'));
     }
@@ -363,19 +435,22 @@ class ExplainCommand extends ProteumCommand {
 
     public static usage = buildUsage('explain');
 
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
-    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 json = Option.Boolean('--json', false, { description: 'Compatibility flag; compact JSON is the default output.' });
+    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: '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();
 
@@ -384,6 +459,9 @@ class ExplainCommand extends ProteumCommand {
         if (mode === 'owner') {
             this.setCliArgs({
                 json: this.json,
+                full: this.full,
+                human: this.human,
+                manifest: this.manifest,
                 ownerQuery: restArgs.join(' ').trim(),
             });
             await runCommandModule(() => import('../commands/explain'));
@@ -392,6 +470,9 @@ class ExplainCommand extends ProteumCommand {
 
         const args = {
             json: this.json,
+            full: this.full,
+            human: this.human,
+            manifest: this.manifest,
             all: this.all,
             app: this.app,
             conventions: this.conventions,
@@ -408,7 +489,7 @@ class ExplainCommand extends ProteumCommand {
         applyLegacyBooleanArgs(
             'explain',
             this.args,
-            ['json', 'all', 'app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
+            ['json', 'full', 'human', 'manifest', 'all', 'app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
             args,
         );
         this.setCliArgs(args);
@@ -423,7 +504,9 @@ class OrientCommand extends ProteumCommand {
 
     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 json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    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 orientation payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public args = Option.Rest();
 
     public async execute() {
@@ -431,6 +514,8 @@ class OrientCommand extends ProteumCommand {
 
         this.setCliArgs({
             json: this.json,
+            full: this.full,
+            human: this.human,
             port: this.port ?? '',
             query,
             url: this.url ?? '',
@@ -447,7 +532,10 @@ class TraceCommand extends ProteumCommand {
 
     public port = Option.String('--port', { description: 'Override the router port used to query the running dev server.' });
     public url = Option.String('--url', { description: 'Override the full base URL used to query the running dev server.' });
-    public json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    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 trace response.' });
+    public events = Option.Boolean('--events', false, { description: 'Include full event, call, SQL, and payload detail.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable trace report.' });
     public capture = Option.String('--capture', { description: 'Capture mode used by `proteum trace arm`.' });
     public output = Option.String('--output', { description: 'Output filepath used by `proteum trace export`.' });
     public args = Option.Rest();
@@ -461,6 +549,9 @@ class TraceCommand extends ProteumCommand {
             port: this.port ?? '',
             url: this.url ?? '',
             json: this.json,
+            full: this.full,
+            events: this.events,
+            human: this.human,
             capture: this.capture ?? '',
             output: this.output ?? '',
         });
@@ -526,7 +617,9 @@ class DiagnoseCommand extends ProteumCommand {
 
     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 json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    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 diagnose payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public hit = Option.String('--hit', { description: 'Issue one HTTP request before diagnosing. Defaults to the target path when it starts with /.' });
     public method = Option.String('--method', { description: 'HTTP method used with `--hit`.' });
     public dataJson = Option.String('--data-json', { description: 'JSON request body used with `--hit`.' });
@@ -547,6 +640,8 @@ class DiagnoseCommand extends ProteumCommand {
             dataJson: this.dataJson ?? '',
             hit: this.hit ?? '',
             json: this.json,
+            full: this.full,
+            human: this.human,
             logsLevel: this.logsLevel ?? '',
             logsLimit: this.logsLimit ?? '',
             method: this.method ?? '',
@@ -568,7 +663,9 @@ class PerfCommand extends ProteumCommand {
 
     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 json = Option.Boolean('--json', false, { description: 'Print JSON output.' });
+    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 perf payload.' });
+    public human = Option.Boolean('--human', false, { description: 'Print the legacy human-readable report.' });
     public since = Option.String('--since', { description: 'Window used by `top` and `memory`, for example `today`, `yesterday`, or `1h`.' });
     public baseline = Option.String('--baseline', { description: 'Baseline window used by `compare`.' });
     public target = Option.String('--target', { description: 'Target window used by `compare`.' });
@@ -584,6 +681,8 @@ class PerfCommand extends ProteumCommand {
             baseline: this.baseline ?? '',
             groupBy: this.groupBy ?? '',
             json: this.json,
+            full: this.full,
+            human: this.human,
             limit: this.limit ?? '',
             port: this.port ?? '',
             since: this.since ?? '',
@@ -596,6 +695,94 @@ class PerfCommand extends ProteumCommand {
     }
 }
 
+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.',
+    });
+    public args = Option.Rest();
+
+    public async execute() {
+        const [action = 'status'] = this.args;
+
+        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'));
+    }
+}
+
+class McpCommand extends ProteumCommand {
+    public static paths = [['mcp']];
+
+    public static usage = buildUsage('mcp');
+
+    public daemon = Option.Boolean('--daemon', false, {
+        description: 'Run the managed machine-scope MCP daemon over local HTTP.',
+    });
+    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() {
+        const [action = 'start', ...restArgs] = this.args;
+
+        assertNoLegacyArgs('mcp', restArgs);
+        this.setCliArgs({
+            action,
+            daemon: this.daemon,
+            stdio: this.stdio,
+            port: this.port ?? '',
+            json: this.json,
+        });
+
+        await runCommandModule(() => import('../commands/mcp'));
+    }
+}
+
 class VerifyCommand extends ProteumCommand {
     public static paths = [['verify']];
 
@@ -672,6 +859,8 @@ export const registeredCommands = {
     orient: OrientCommand,
     diagnose: DiagnoseCommand,
     perf: PerfCommand,
+    runtime: RuntimeCommand,
+    mcp: McpCommand,
     trace: TraceCommand,
     command: CommandCommand,
     session: SessionCommand,
@@ -705,6 +894,8 @@ export const createCli = (version: string) => {
     clipanion.register(OrientCommand);
     clipanion.register(DiagnoseCommand);
     clipanion.register(PerfCommand);
+    clipanion.register(RuntimeCommand);
+    clipanion.register(McpCommand);
     clipanion.register(TraceCommand);
     clipanion.register(CommandCommand);
     clipanion.register(SessionCommand);