proteum 2.1.0 → 2.1.2

package/cli/presentation/commands.ts

@@ -5,6 +5,7 @@ import type { TRow } from './layout';
 
 export const proteumCommandNames = [
     'init',
+    'create',
     'dev',
     'refresh',
     'build',
@@ -13,6 +14,8 @@ export const proteumCommandNames = [
     'check',
     'doctor',
     'explain',
+    'trace',
+    'command',
 ] as const;
 
 export type TProteumCommandName = (typeof proteumCommandNames)[number];
@@ -45,21 +48,56 @@ 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: 'Project scaffolding', names: ['init'] },
+    { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command'] },
+    { title: 'Project scaffolding', names: ['init', 'create'] },
 ];
 
 export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> = {
     init: {
         name: 'init',
         category: 'Project scaffolding',
-        summary: 'Scaffold a new Proteum project.',
-        usage: 'proteum init',
-        bestFor: 'Bootstrap a new app when the Proteum scaffold assets are installed in the current package.',
-        examples: [{ description: 'Create a new app interactively', command: 'proteum init' }],
+        summary: 'Scaffold a new Proteum app with deterministic built-in templates.',
+        usage: 'proteum init [directory] [--name <name>] [--identifier <identifier>] [--port <port>] [--install] [--dry-run] [--json]',
+        bestFor: 'Bootstrapping a new app in a way that is explicit, machine-readable, and safe for LLM coding agents.',
+        examples: [
+            { description: 'Create a new app in ./my-app', command: 'proteum init my-app --name "My App"' },
+            {
+                description: 'Scaffold an app and install dependencies immediately',
+                command: 'proteum init my-app --name "My App" --install',
+            },
+            {
+                description: 'Emit scaffold details as JSON for an agent',
+                command: 'proteum init my-app --name "My App" --json',
+            },
+            {
+                description: 'Preview the full app scaffold without writing files',
+                command: 'proteum init my-app --name "My App" --dry-run --json',
+            },
+        ],
         notes: [
-            'This command is still experimental.',
-            'In source checkouts it requires `cli/skeleton` to exist.',
+            'When Proteum is invoked from a local framework checkout, init writes a file: dependency to that checkout by default.',
+            'Use `--dry-run --json` when an agent needs a machine-readable app scaffold plan before writing files.',
+            'Without `--install`, init only writes files and does not touch the network.',
+        ],
+        status: 'experimental',
+    },
+    create: {
+        name: 'create',
+        category: 'Project scaffolding',
+        summary: 'Generate a page, controller, command, route, or root service inside a Proteum app.',
+        usage: 'proteum create <page|controller|command|route|service> <target> [--route <url>] [--method <name>] [--http-method <verb>] [--dry-run] [--json]',
+        bestFor: 'Fast deterministic scaffolding inside an existing Proteum app without inventing file layouts or boilerplate by hand.',
+        examples: [
+            { description: 'Create a new SSR page', command: 'proteum create page marketing/faq --route /faq' },
+            { description: 'Create a new controller', command: 'proteum create controller Founder/projects --method list' },
+            { description: 'Create a new command', command: 'proteum create command diagnostics --method ping' },
+            { description: 'Preview a new route without writing files', command: 'proteum create route webhooks/stripe --dry-run --json' },
+            { description: 'Create and register a new root service', command: 'proteum create service Conversion/Plans' },
+        ],
+        notes: [
+            'Page scaffolds write `client/pages/**/index.tsx` and default the route path from the logical target path unless `--route` is provided.',
+            'Service scaffolds create `server/services/**/index.ts`, `service.json`, a config export under `server/config/*.ts`, and then try to register the new root service in `server/index.ts`.',
+            'Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.',
         ],
         status: 'experimental',
     },
@@ -170,20 +208,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) =>
@@ -194,8 +284,8 @@ export const isLikelyProteumAppRoot = (workdir: string) =>
 
 export const getInitAvailabilityNote = (initAvailable: boolean) =>
     initAvailable
-        ? 'Scaffold assets are installed in this checkout.'
-        : 'This checkout does not include `cli/skeleton`, so `proteum init` is unavailable until the scaffold assets are restored.';
+        ? 'Init is built into the CLI and does not depend on external scaffold assets.'
+        : 'Init scaffolding is currently unavailable in this checkout.';
 
 export const createClipanionUsage = (command: TProteumCommandDoc) => ({
     category: command.category,

package/cli/presentation/devSession.ts

@@ -11,6 +11,8 @@ const ProteumWordmark = [
     String.raw`|_|   |_| \_\\___/ |_| |_____|\___/|_|  |_|`,
 ];
 
+const ProteumTagline = 'Agent-first SSR compiler and server loop.';
+
 export const renderDevSession = async ({
     appName,
     appRoot,
@@ -32,9 +34,9 @@ export const renderDevSession = async ({
             return createElement(
                 Box,
                 { borderStyle: 'round', borderColor: 'cyan', paddingX: 2, paddingY: 0, flexDirection: 'column' },
-                createElement(Text, { bold: true, color: 'green' }, 'PROTEUM DEV'),
-                createElement(Text, { dimColor: true }, 'Agent-first SSR compiler and server loop.'),
-                createElement(Box, { flexDirection: 'column', marginTop: 1 }, ...wordmark),
+                createElement(Text, { bold: true, backgroundColor: 'cyan', color: 'black' }, ' WELCOME TO '),
+                createElement(Box, { flexDirection: 'column' }, ...wordmark),
+                createElement(Text, { dimColor: true }, ProteumTagline),
             );
         }),
         renderRows(
@@ -43,6 +45,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 +56,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 +72,18 @@ 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}`),
+        );
+    });
+
+export const renderDevShutdownBanner = async () =>
+    renderInk(({ Box, Text }) => {
+        const createElement = React.createElement;
+
+        return createElement(
+            Box,
+            { borderStyle: 'round', borderColor: 'yellow', paddingX: 2, paddingY: 0, flexDirection: 'column' },
+            createElement(Text, { bold: true, backgroundColor: 'yellow', color: 'black' }, ' SHUTTING DOWN '),
+            createElement(Text, { bold: true, color: 'yellow' }, 'Thank you for developping with Proteum'),
         );
     });