proteum 2.1.1 → 2.1.2

package/README.md

@@ -28,7 +28,7 @@ Proteum combines:
 - **Explicit request entrypoints.** Controllers are classes. Request access is explicit through `this.request`.
 - **Local validation.** Validate handler input inside the handler with `this.input(schema)`.
 - **Deterministic generation.** Proteum owns `.proteum/` and regenerates it from source.
-- **Explainability matters.** `proteum explain`, `proteum doctor`, and `proteum trace` expose the framework view of your app and its live requests.
+- **Explainability matters.** `proteum explain`, `proteum doctor`, and `proteum trace` expose the framework view of your app and its live requests, and the profiler renders the same diagnostics surfaces for humans in dev.
 - **SEO is not an afterthought.** Identity, routes, layouts, and SSR data are part of the app contract.
 
 ## What a Proteum App Looks Like
@@ -289,7 +289,8 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum explain` | Explain routes, controllers, services, layouts, conventions, and env |
 | `proteum trace` | Inspect live dev-only request traces from the running SSR server |
 | `proteum command` | Run a dev-only internal command locally or against a running dev server |
-| `proteum init` | Experimental project scaffolding when scaffold assets are installed |
+| `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
+| `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
 Recommended daily workflow:
 
@@ -315,6 +316,18 @@ proteum trace arm --capture deep
 proteum trace latest
 ```
 
+Useful scaffolding commands:
+
+```bash
+proteum init my-app --name "My App"
+proteum init my-app --name "My App" --dry-run --json
+proteum create page marketing/faq --route /faq
+proteum create controller Founder/projects --method list
+proteum create service Conversion/Plans
+```
+
+`proteum explain` and `proteum doctor` share the same manifest-backed diagnostics contract as the profiler `Explain` and `Doctor` tabs. For the full dev diagnostics model, see [docs/diagnostics.md](docs/diagnostics.md).
+
 ## Dev Commands
 
 Proteum includes a dev-only command surface for internal testing, debugging, and one-off execution that should not become a normal controller or route.
@@ -326,12 +339,15 @@ Proteum includes a dev-only command surface for internal testing, debugging, and
 - `proteum command foo/bar` refreshes generated artifacts, builds the dev output, starts a temporary local dev server, runs the command, prints the result, and exits
 - `proteum command foo/bar --port 3101` runs the same command against an existing `proteum dev` instance
 - the dev profiler exposes the same command list and run action through the `Commands` tab
+- the same profiler also exposes `Explain` and `Doctor` tabs backed by the same manifest diagnostics contract as the CLI
 
 Proteum itself also ships a small built-in diagnostic command at `proteum/diagnostics/ping`, so the command surface is never empty in dev.
 
 ## Request Tracing
 
-Proteum includes a dev-only in-memory request trace buffer for routing, controller, context, SSR, and render debugging.
+Proteum includes a dev-only in-memory request trace buffer for auth, routing, controller, context, SSR, and render debugging.
+
+This is separate from `proteum explain` and `proteum doctor`: tracing is live request-time data, while explain/doctor are manifest-backed structure and diagnostics.
 
 When diagnosing or testing against an app, first read the default port from `PORT` or `./.proteum/manifest.json` and check whether a server is already running there. If it is, inspect the existing traces before reproducing the issue so you can collect past errors and their context.
 
@@ -363,7 +379,7 @@ export TRACE_PERSIST_ON_ERROR=true
 Capture modes:
 
 - `summary`: request lifecycle plus high-signal events
-- `resolve`: adds route resolution and controller/context steps
+- `resolve`: adds auth, route resolution, and controller/context steps
 - `deep`: adds route skip reasons and deeper payload summaries for one request investigation
 
 The trace CLI talks to the running dev server over the dev-only `__proteum/trace` HTTP endpoints. Use `--port` for a different local port or `--url` when the host itself is non-standard. For the full guide, see [docs/request-tracing.md](docs/request-tracing.md).
@@ -387,6 +403,7 @@ Proteum answers those questions with explicit artifacts:
 - `.proteum/manifest.json` for machine-readable app structure
 - `proteum explain --json` for structured framework introspection
 - `proteum doctor --json` for structured diagnostics
+- the profiler `Explain` and `Doctor` tabs for a human-readable view over the same manifest-backed contract
 - `proteum command ...` plus the profiler `Commands` tab for dev-only internal execution
 
 If you are an LLM or automation agent, start here:
@@ -449,15 +466,17 @@ Install in an app:
 npm install proteum
 ```
 
-If the scaffold assets are available in your distribution, you can bootstrap a new app with:
+You can bootstrap a new app with:
 
 ```bash
-npx proteum init
+npx proteum init my-app --name "My App"
+npx proteum init my-app --name "My App" --dry-run --json
 ```
 
 Then use the normal workflow:
 
 ```bash
+npm install
 npx proteum dev
 npx proteum check
 npx proteum build --prod

package/agents/framework/AGENTS.md

@@ -66,6 +66,14 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - `npx proteum doctor --json`
 - `npx proteum trace ...`
 - `npx proteum command ...`
+- `npx proteum create ... --dry-run --json`
+
+Prefer scaffold commands before hand-writing boilerplate:
+
+- Use `npx proteum init <directory> --name <name>` for new apps.
+- Use `npx proteum init ... --dry-run --json` when an agent needs a machine-readable app plan before writing files.
+- Use `npx proteum create page|controller|command|route|service <target>` for new app artifacts before creating the files manually.
+- Use `npx proteum create ... --dry-run --json` when an agent needs a machine-readable artifact plan before writing files.
 
 ## File Contracts
 
@@ -79,6 +87,7 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
 - Keep auth, input parsing, locale, cookies, and request-derived values in controllers, then pass explicit typed arguments into services.
 - Split growing features into explicit subservices.
+- `proteum create service ...` scaffolds the service file, its `service.json`, a typed config export under `server/config/*.ts`, and the root registration in `server/index.ts`; review and adapt the generated names before committing.
 
 ### Controllers
 
@@ -87,6 +96,7 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - Route path comes from the controller file path plus the method name.
 - `export const controllerPath = 'Custom/path'` can override the base path.
 - Generated client calls use `POST`.
+- Prefer `proteum create controller ...` for new controller boilerplate, then adapt the generated method to real service calls.
 
 ### Commands
 
@@ -96,6 +106,7 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - `export const commandPath = 'Custom/path'` can override the base path.
 - Commands are for dev-only internal execution through `proteum command ...` or the profiler `Commands` tab.
 - Keep command logic internal; do not turn it into a normal controller unless it is a real app API.
+- Prefer `proteum create command ...` for new command boilerplate.
 
 ### Client Pages
 
@@ -108,6 +119,7 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - `render` consumes resolved setup data and uses generated controller methods from render args or `@/client/context`.
 - Use `api.reload(...)` or `api.set(...)` only when intentionally mutating active page setup state.
 - Error pages use `Router.error(code, options, render)` in `client/pages/_messages/**`.
+- Prefer `proteum create page ...` for new page boilerplate, then review the explicit route path and setup payload.
 
 ### Manual Routes
 
@@ -115,6 +127,7 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - Good fits include redirects, sitemap or RSS output, OAuth callbacks, webhooks, and public resources with custom semantics.
 - Import server-side app services from `@app` and use route handler context for `request`, `response`, router plugins, and custom router context.
 - If the route is a normal app API, prefer a controller.
+- Prefer `proteum create route ...` for new manual-route boilerplate.
 
 ### Models And Aliases
 
@@ -161,4 +174,4 @@ Verify at the correct layer:
 
 When an app may already be running, check the default port from `PORT` or `./.proteum/manifest.json` and inspect `proteum trace requests`, `proteum trace latest`, and `proteum trace show <requestId>` before reproducing the issue. If those traces are not enough, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
 
-Useful commands: `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum command <path>`.
+Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum command <path>`.

package/agents/project/AGENTS.md

@@ -12,6 +12,8 @@ Coding style source of truth: `./CODING_STYLE.md`.
 ## Fast Start
 
 - Start with `./.proteum/manifest.json`, `npx proteum explain`, and `npx proteum doctor`.
+- For new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand.
+- Use `--dry-run --json` on scaffold commands when an agent needs a machine-readable plan before writing files.
 - For request-time issues in dev, inspect traces before adding logs.
 - If a server is already running on the default port from `PORT` or `./.proteum/manifest.json`, inspect existing traces before reproducing the issue.
 - If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request.
@@ -58,6 +60,7 @@ This is a TypeScript, Node.js, Preact, Proteum monolith:
 
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
 - For request-time behavior in dev, check whether a server is already running on the default port and prefer `npx proteum trace` before reproducing the issue or adding logs.
+- After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
 - End your work with `Commit message`: one short top-level sentence.
 
 ## High-Impact Files

package/cli/commands/create.ts

@@ -0,0 +1,5 @@
+import { runCreateScaffold } from '../scaffold';
+
+export const run = async (): Promise<void> => {
+    await runCreateScaffold();
+};

package/cli/commands/dev.ts

@@ -22,7 +22,7 @@ import {
 import Compiler from '../compiler';
 import { createDevEventServer } from './devEvents';
 import { ensureProjectAgentSymlinks } from '../utils/agents';
-import { renderDevSession, renderServerReadyBanner } from '../presentation/devSession';
+import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
 import { logVerbose } from '../runtime/verbose';
 
 // Core
@@ -448,6 +448,7 @@ export const run = async () => {
             await stopApp(reason);
             await cleanupPersistedDevTraces(app);
             await devEventServer.close();
+            console.info(await renderDevShutdownBanner());
         })();
 
         return shuttingDownPromise;

package/cli/commands/init.ts

@@ -1,97 +1,5 @@
-/*----------------------------------
-- DEPENDANCES
-----------------------------------*/
+import { runInitScaffold } from '../scaffold';
 
-// Npm
-import fs from 'fs-extra';
-import path from 'path';
-import prompts from 'prompts';
-import cmd from 'node-cmd';
-import replaceOnce from 'replace-once';
-import { UsageError } from 'clipanion';
-
-// Cor elibs
-import cli from '..';
-import { ensureProjectAgentSymlinks } from '../utils/agents';
-
-// Configs
-const filesToConfig = ['package.json', 'identity.yaml'];
-
-/*----------------------------------
-- COMMANDE
-----------------------------------*/
 export const run = async (): Promise<void> => {
-    const skeletonPath = path.join(cli.paths.core.cli, 'skeleton');
-
-    if (!fs.existsSync(skeletonPath)) {
-        throw new UsageError(
-            'Proteum init is unavailable in this checkout because `cli/skeleton` is missing. Restore the scaffold assets or use an installed Proteum package that includes them.',
-        );
-    }
-
-    const config = await prompts([
-        {
-            type: 'text',
-            name: 'name',
-            message: 'Project name ?',
-            initial: 'MyProject',
-            validate: (value) => /[a-z0-9\-\.]/i.test(value) || 'Must only include alphanumeric characters, and - . ',
-        },
-        {
-            type: 'text',
-            name: 'dirname',
-            message: 'Folder name ?',
-            initial: (value) => value.toLowerCase(),
-            validate: (value) =>
-                /[a-z0-9\-\.]/.test(value) || 'Must only include lowercase alphanumeric characters, and - . ',
-        },
-        {
-            type: 'text',
-            name: 'description',
-            message: 'Briefly describe your project to your mom:',
-            initial: 'It will revolutionnize the world',
-            validate: (value) => /[a-z0-9\-\. ]/i.test(value) || 'Must only include alphanumeric characters, and - . ',
-        },
-        { type: 'toggle', name: 'microservice', message: 'Separate API from the UI servers ?' },
-    ]);
-
-    const placeholders = {
-        PROJECT_NAME: config.name,
-        PACKAGE_NAME: config.name.toLowerCase(),
-        PROJECT_DESCRIPTION: config.description,
-    };
-
-    const paths = {
-        skeleton: skeletonPath,
-        project: path.join(process.cwd(), config.dirname),
-    };
-
-    // Copy skeleton to cwd/<project-name>
-    console.info('Creating project skeleton ...');
-    fs.copySync(paths.skeleton, paths.project);
-
-    // Sync framework-owned Codex assets into the new project.
-    ensureProjectAgentSymlinks({ appRoot: paths.project, coreRoot: cli.paths.core.root });
-
-    // Replace placeholders
-    console.info('Configuring project ...');
-    for (const file of filesToConfig) {
-        console.log('- ' + file);
-
-        const filepath = path.join(paths.project, file);
-        const content = fs.readFileSync(filepath, 'utf-8');
-
-        const placeholders_keys = Object.keys(placeholders).map((k) => '{{ ' + k + ' }}');
-        const values = Object.values(placeholders);
-
-        fs.writeFileSync(filepath, replaceOnce(content, placeholders_keys, values));
-    }
-
-    // Npm install
-    console.info('Installing packages ...');
-    cmd.runSync(`cd "${paths.project}" && npm i`);
-
-    // Run demo app
-    /*console.info("Run demo ...");
-await cli.shell('5htp dev');*/
+    await runInitScaffold();
 };

package/cli/index.ts

@@ -1,6 +1,5 @@
 process.traceDeprecation = true;
 
-import fs from 'fs';
 import { Cli } from 'clipanion';
 
 import cli from './context';
@@ -9,12 +8,10 @@ import { renderCliOverview, renderCommandHelp, resolveCustomHelpRequest } from '
 import { normalizeHelpArgv, normalizeLegacyArgv } from './runtime/argv';
 import { createCli, registeredCommands } from './runtime/commands';
 
-const hasInitScaffold = () => fs.existsSync(`${cli.paths.core.cli}/skeleton`);
-
 export const runCli = async (argv: string[] = process.argv.slice(2)) => {
     const normalizedArgv = normalizeHelpArgv(normalizeLegacyArgv(argv), proteumCommandNames);
     const clipanion = createCli(String(cli.packageJson.version || ''));
-    const initAvailable = hasInitScaffold();
+    const initAvailable = true;
     const helpRequest = resolveCustomHelpRequest(normalizedArgv);
 
     if (helpRequest.kind === 'overview') {

package/cli/presentation/commands.ts

@@ -5,6 +5,7 @@ import type { TRow } from './layout';
 
 export const proteumCommandNames = [
     'init',
+    'create',
     'dev',
     'refresh',
     'build',
@@ -48,20 +49,55 @@ export const proteumCommandGroups: Array<{ title: string; names: TProteumCommand
     { title: 'Daily workflow', names: ['dev', 'refresh', 'build'] },
     { title: 'Quality gates', names: ['typecheck', 'lint', 'check'] },
     { title: 'Manifest and contracts', names: ['doctor', 'explain', 'trace', 'command'] },
-    { title: 'Project scaffolding', names: ['init'] },
+    { 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: [
+            '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: [
-            'This command is still experimental.',
-            'In source checkouts it requires `cli/skeleton` to exist.',
+            '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',
     },
@@ -248,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(
@@ -73,3 +75,15 @@ export const renderServerReadyBanner = async ({
             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'),
+        );
+    });