proteum 2.1.0 → 2.1.1

package/cli/presentation/commands.ts

@@ -13,6 +13,8 @@ export const proteumCommandNames = [
     'check',
     'doctor',
     'explain',
+    'trace',
+    'command',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -45,7 +47,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'] },
-    { title: 'Manifest and contracts', names: ['doctor', 'explain'] },
+    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command'] },
     { title: 'Project scaffolding', names: ['init'] },
 ];
 
@@ -170,20 +172,72 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         name: 'explain',
         category: 'Manifest and contracts',
         summary: 'Explain the generated Proteum manifest.',
-        usage: 'proteum explain [--all|--app|--conventions|--env|--services|--controllers|--routes|--layouts|--diagnostics] [--json]',
+        usage: 'proteum explain [--all|--app|--conventions|--env|--services|--controllers|--commands|--routes|--layouts|--diagnostics] [--json]',
         bestFor:
-            'Inspecting how source files became generated routes, controllers, layouts, services, and diagnostics without reading compiler internals.',
+            'Inspecting how source files became generated routes, controllers, commands, layouts, services, and diagnostics without reading compiler internals.',
         examples: [
             { description: 'Show the default human summary', command: 'proteum explain' },
             {
-                description: 'Inspect generated routes and controllers together',
-                command: 'proteum explain --routes --controllers',
+                description: 'Inspect generated routes, controllers, and commands together',
+                command: 'proteum explain --routes --controllers --commands',
             },
             { description: 'Emit the selected manifest sections as JSON', command: 'proteum explain --routes --json' },
         ],
         notes: ['Legacy positional section selection remains supported, for example `proteum explain routes services`.'],
         status: 'stable',
     },
+    trace: {
+        name: 'trace',
+        category: 'Manifest and contracts',
+        summary: 'Inspect live in-memory request traces from a running Proteum dev server.',
+        usage: 'proteum trace [latest|show <requestId>|requests|arm|export <requestId>] [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Debugging route resolution, context creation, SSR payloads, renders, and runtime errors without attaching a debugger.',
+        examples: [
+            { description: 'Show the latest request trace', command: 'proteum trace latest' },
+            { description: 'List recent trace summaries', command: 'proteum trace requests' },
+            { description: 'Arm the next request for deep capture', command: 'proteum trace arm --capture deep' },
+            { description: 'Export a request trace to disk', command: 'proteum trace export <requestId>' },
+            { description: 'Target a custom dev base URL directly', command: 'proteum trace latest --url http://127.0.0.1:3010' },
+        ],
+        notes: [
+            'This command talks to the running app over the dev-only `__proteum/trace` HTTP endpoints.',
+            'Traces are stored in a bounded in-memory buffer with payload summarization and sensitive-field redaction.',
+            'Use `--port` when the app is not running on the router port declared in `PORT`, or `--url` when the host itself is non-standard.',
+        ],
+        status: 'experimental',
+    },
+    command: {
+        name: 'command',
+        category: 'Manifest and contracts',
+        summary: 'Run a dev-only app command from /commands or against an existing dev instance.',
+        usage: 'proteum command <path> [--port <port>|--url <baseUrl>] [--json]',
+        bestFor:
+            'Internal testing, debugging, and one-off service execution that should not be exposed as a normal controller or route.',
+        examples: [
+            {
+                description: 'Run a local command through a temporary bundled dev server',
+                command: 'proteum command proteum/diagnostics/ping',
+            },
+            {
+                description: 'Run a command against an existing dev server',
+                command: 'proteum command proteum/diagnostics/ping --port 3101',
+            },
+            {
+                description: 'Emit the command execution as JSON',
+                command: 'proteum command proteum/diagnostics/ping --json',
+            },
+        ],
+        notes: [
+            'Commands live under `./commands/**/*.ts` and default-export a class that extends `{ Commands }` from `@server/app/commands`.',
+            'Methods are addressed by file path plus method name, mirroring controller path generation.',
+            'Proteum creates `./commands/tsconfig.json` and `.proteum/server/commands.d.ts` so `/commands` gets a command-specific alias/type project.',
+            'Prefer `extends Commands` directly inside `/commands`; importing the app class is still supported through a generated command-only `@/server/index` type alias.',
+            'Without `--port` or `--url`, Proteum refreshes generated artifacts, builds the dev output, starts a temporary local dev server, runs the command, and exits.',
+            'With `--port` or `--url`, Proteum talks to the running app over the dev-only `__proteum/commands` HTTP endpoints.',
+        ],
+        status: 'experimental',
+    },
 };
 
 export const isLikelyProteumAppRoot = (workdir: string) =>

package/cli/presentation/devSession.ts

@@ -43,6 +43,8 @@ export const renderDevSession = async ({
                 { label: 'root', value: appRoot },
                 { label: 'router', value: `http://localhost:${routerPort}` },
                 { label: 'hmr', value: `http://localhost:${devEventPort}/__proteum_hmr` },
+                { label: 'trace', value: `proteum trace latest --port ${routerPort}` },
+                { label: 'trace deep', value: `proteum trace arm --capture deep --port ${routerPort}` },
                 { label: 'hotkeys', value: 'Ctrl+R reload, Ctrl+C stop' },
             ],
             { minLabelWidth: 12, maxLabelWidth: 12 },
@@ -52,9 +54,11 @@ export const renderDevSession = async ({
 export const renderServerReadyBanner = async ({
     appName,
     publicUrl,
+    routerPort,
 }: {
     appName: string;
     publicUrl: string;
+    routerPort: number;
 }) =>
     renderInk(({ Box, Text }) => {
         const createElement = React.createElement;
@@ -66,5 +70,6 @@ export const renderServerReadyBanner = async ({
             createElement(Text, { bold: true, color: 'green' }, appName),
             createElement(Text, { bold: true }, publicUrl),
             createElement(Text, { dimColor: true }, 'SSR server is listening for requests and hot reloads.'),
+            createElement(Text, { dimColor: true }, `Trace latest: proteum trace latest --port ${routerPort}`),
         );
     });

package/cli/runtime/commands.ts

@@ -153,6 +153,7 @@ class ExplainCommand extends ProteumCommand {
     public env = Option.Boolean('--env', false, { description: 'Include the env 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 diagnostics = Option.Boolean('--diagnostics', false, {
@@ -169,6 +170,7 @@ class ExplainCommand extends ProteumCommand {
             env: this.env,
             services: this.services,
             controllers: this.controllers,
+            commands: this.commands,
             routes: this.routes,
             layouts: this.layouts,
             diagnostics: this.diagnostics,
@@ -177,7 +179,7 @@ class ExplainCommand extends ProteumCommand {
         applyLegacyBooleanArgs(
             'explain',
             this.legacyArgs,
-            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'routes', 'layouts', 'diagnostics'],
+            ['json', 'all', 'app', 'conventions', 'env', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'],
             args,
         );
         this.setCliArgs(args);
@@ -185,6 +187,59 @@ class ExplainCommand extends ProteumCommand {
     }
 }
 
+class TraceCommand extends ProteumCommand {
+    public static paths = [['trace']];
+
+    public static usage = buildUsage('trace');
+
+    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 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();
+
+    public async execute() {
+        const [action = 'latest', id = ''] = this.args;
+
+        this.setCliArgs({
+            action,
+            id,
+            port: this.port ?? '',
+            url: this.url ?? '',
+            json: this.json,
+            capture: this.capture ?? '',
+            output: this.output ?? '',
+        });
+
+        await runCommandModule(() => import('../commands/trace'));
+    }
+}
+
+class CommandCommand extends ProteumCommand {
+    public static paths = [['command']];
+
+    public static usage = buildUsage('command');
+
+    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 args = Option.Rest();
+
+    public async execute() {
+        const [path = ''] = this.args;
+
+        this.setCliArgs({
+            path,
+            port: this.port ?? '',
+            url: this.url ?? '',
+            json: this.json,
+        });
+
+        await runCommandModule(() => import('../commands/command'));
+    }
+}
+
 export const registeredCommands = {
     init: InitCommand,
     dev: DevCommand,
@@ -195,6 +250,8 @@ export const registeredCommands = {
     check: CheckCommand,
     doctor: DoctorCommand,
     explain: ExplainCommand,
+    trace: TraceCommand,
+    command: CommandCommand,
 } as const;
 
 export const createCli = (version: string) => {
@@ -216,6 +273,8 @@ export const createCli = (version: string) => {
     clipanion.register(CheckCommand);
     clipanion.register(DoctorCommand);
     clipanion.register(ExplainCommand);
+    clipanion.register(TraceCommand);
+    clipanion.register(CommandCommand);
 
     return clipanion;
 };

package/cli/tsconfig.json

@@ -29,9 +29,12 @@
         "outDir": "./bin",
 
         "paths": {
+            "@client/*": [ "../client/*" ],
             "@cli/*": [ "./*" ],
             "@cli/app": [ "./app" ],
-            "@cli": [ "./" ]
+            "@cli": [ "./" ],
+            "@common/*": [ "../common/*" ],
+            "@server/*": [ "../server/*" ]
         },
     },
 

package/cli/utils/check.ts

@@ -5,7 +5,7 @@ import cli from '..';
 import Compiler from '../compiler';
 import { runProcess } from './runProcess';
 
-const tsconfigPaths = ['client/tsconfig.json', 'server/tsconfig.json'];
+const tsconfigPaths = ['client/tsconfig.json', 'server/tsconfig.json', 'commands/tsconfig.json'];
 const eslintConfigPaths = ['eslint.config.mjs', 'eslint.config.js', 'eslint.config.cjs'];
 
 const resolveInstalledBinary = (name: string) => {

package/client/app/component.tsx

@@ -21,10 +21,17 @@ export default function App({ context }: { context: ClientContext }) {
     const curLayout = context.page?.layout;
     const [layout, setLayout] = React.useState<Layout | false | undefined>(curLayout);
     const [apiData, setApiData] = React.useState<{ [k: string]: any } | null>(context.page?.data || {});
+    const shouldEnableDevProfiler = __DEV__ && typeof window !== 'undefined' && window.dev;
+    const [isDevProfilerMounted, setDevProfilerMounted] = React.useState(false);
 
     // TODO: context.page is always provided in the context on the client side
     if (context.app.side === 'client') context.app.setLayout = setLayout;
 
+    React.useEffect(() => {
+        if (!shouldEnableDevProfiler) return;
+        setDevProfilerMounted(true);
+    }, [shouldEnableDevProfiler]);
+
     const layoutProps: LayoutProps = {
         ...context,
         context,
@@ -32,22 +39,19 @@ export default function App({ context }: { context: ClientContext }) {
         menu: undefined,
         children: undefined,
     };
+    const DevProfiler = shouldEnableDevProfiler
+        ? ((require('@client/dev/profiler') as typeof import('@client/dev/profiler')).default as React.ComponentType)
+        : null;
 
     return (
         <ReactClientContext.Provider value={context}>
             <DialogManager />
+            {DevProfiler && isDevProfilerMounted ? <DevProfiler /> : null}
 
             {!layout ? (
-                <>
-                    {/* TODO: move to app, because here, we're not aware that the router service has been defined */}
-                    <RouterComponent service={context.Router} />
-                </>
+                <RouterComponent service={context.Router} />
             ) : (
-                <>
-                    {' '}
-                    {/* Same as router/components/Page.tsx */}
-                    <layout.Component {...layoutProps} />
-                </>
+                <layout.Component {...layoutProps} />
             )}
         </ReactClientContext.Provider>
     );