proteum 2.5.4 → 2.5.5

package/docs/agent-routing.md

@@ -66,9 +66,9 @@ Use MCP for repeated reads when a client is available:
 proteum mcp
 ```
 
-The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
+The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include readiness and port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
 
-If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's next action from the app root, not from the monorepo wrapper. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
+If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's readiness and next actions from the app root, not from the monorepo wrapper. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
 
 Prefer CLI over MCP when the result must be reproducible as a shell command, part of verification, or copied into CI/debug instructions.
 
@@ -135,6 +135,6 @@ The latest Product `/domains` benchmark used routed instructions plus the compac
 The result confirms the intended routing:
 
 - use CLI for reproducible verification and final command evidence
-- use `workflow_start` to collapse project resolution, runtime status, instruction previews, owner summary, and first next actions into one read
+- use `workflow_start` to collapse project resolution, fresh-copy readiness, runtime status, instruction previews, owner summary, and first next actions into one read
 - use machine MCP with `projectId` for repeated runtime reads against an already running app
 - use `instructions_resolve` to refresh routing instead of rereading full instruction files

package/docs/diagnostics.md

@@ -114,7 +114,7 @@ Default compact command output follows this shape:
 
 Inside `/.codex/worktrees/`, `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` require a fresh `.proteum/worktree-bootstrap.json`. If the marker is missing, run `npx proteum worktree init --source <source-app-root>`. If hashes, app `.env`, workspace-root `.env` for monorepos with root tooling, `.proteum/manifest.json`, `node_modules`, or the Proteum version are stale, run the returned `npx proteum worktree init --source <source-app-root> --refresh` command. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor diagnostics, and MCP output.
 
-During `proteum dev`, `/__proteum/mcp` exposes compact `workflow_start`, `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each repeated read. `proteum dev` also ensures one managed machine `proteum mcp` daemon is running. Through the machine router, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, follow the selected app root's port-inspected next action when needed, then pass the selected live `projectId` to follow-up app-bound tools.
+During `proteum dev`, `/__proteum/mcp` exposes compact `workflow_start`, `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each repeated read. `proteum dev` also ensures one managed machine `proteum mcp` daemon is running. Through the machine router, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, follow the selected app root's fresh-copy readiness and port-inspected next actions when needed, then pass the selected live `projectId` to follow-up app-bound tools. `workflow_start` returns `data.readiness` with read-only setup checks for `.env`, dependencies, generated manifest state, connected producers, Prisma/client readiness, redacted database URL shape, and local database TCP reachability.
 
 MCP tool/resource output follows compact single-line `proteum-mcp-v1` JSON:
 
@@ -251,7 +251,7 @@ Treat these as framework contract failures first. The fix usually belongs at the
 
 For AI coding agents or automation:
 
-1. When MCP is available, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start dev from that app root when needed, then retry with the selected stable live `projectId`.
+1. When MCP is available, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, resolve any returned `data.readiness.state="blocked"` setup actions, start dev from that app root when needed, then retry with the selected stable live `projectId`.
 2. Use the returned `projectId` for MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` read-only runtime, owner, route, instruction, trace, perf, and log reads.
 3. Do not run CLI equivalents after a successful MCP result for the same read, and do not run broad source searches for ownership MCP already returned. Use CLI for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final terminal evidence.
 4. Use selected instruction previews for read-only discovery and diagnostics; read full files only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.

package/docs/mcp.md

@@ -28,7 +28,7 @@ The router is read-only. It does not start or stop dev servers, mutate files, re
 Use this flow:
 
 1. Call MCP `workflow_start` with `cwd` or a known `projectId`.
-2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, start exactly one `proteum dev` server from that app root when needed, then retry `workflow_start`.
+2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, resolve any returned `data.readiness.state="blocked"` setup actions, start exactly one `proteum dev` server from that app root when needed, then retry `workflow_start`.
 3. Pass the returned live `projectId` to every follow-up app-bound MCP call.
 4. After an MCP read succeeds, do not run the equivalent CLI command or broad source search for the same state; keep CLI for fallback, validation, and final terminal evidence.
 
@@ -47,7 +47,7 @@ Example tool calls:
 {"tool":"db_query","arguments":{"projectId":"prj_0123abcd4567","sql":"SELECT id, email FROM User LIMIT 5","limit":5}}
 ```
 
-`workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
+`workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Its machine-router response includes `data.readiness`, a read-only fresh-copy preflight covering app/root `.env` files, dependency install root and package manager, generated Proteum manifest state, local connected producer apps, Prisma schema/client readiness, redacted database URL shape, and local TCP database reachability when the host is local. The preflight adds exact setup commands where safe, such as copying `.env.example`, installing dependencies, running `npx proteum refresh`, generating Prisma Client, checking Prisma migration status, preflighting connected producer apps, and starting `proteum dev` on a checked port. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
 
 When the selected app root is inside `/.codex/worktrees/`, `workflow_start` first checks `.proteum/worktree-bootstrap.json`. If the marker is missing or stale, it returns `ok: false` with a single next action such as `npx proteum worktree init --source <source-app-root>` or the same command with `--refresh`. The router does not forward to the app MCP endpoint until bootstrap is complete, unless `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` is set; bypasses remain visible in MCP, `runtime status`, and `doctor`.
 
@@ -79,9 +79,10 @@ If machine MCP routing fails:
 1. Run `proteum mcp status`.
 2. Run `proteum runtime status` from the intended app root. If you are in a monorepo wrapper, use the returned app candidates and exact next action instead of starting dev from the wrapper.
 3. If the app root is inside `/.codex/worktrees/` and runtime status or workflow start reports missing/stale bootstrap, run `proteum worktree init --source <source-app-root>` or the returned `--refresh` command first.
-4. If no live app session exists, use the exact Start Dev next action returned by runtime status. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
-5. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
-6. Retry MCP `workflow_start` and use the returned `projectId`.
+4. If `workflow_start` returns `data.readiness.state="blocked"`, run or resolve the readiness setup actions before starting dev.
+5. If no live app session exists, use the exact Start Dev next action returned by runtime status or `workflow_start`. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
+6. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
+7. Retry MCP `workflow_start` and use the returned `projectId`.
 
 Offline `project_resolve` and `workflow_start` candidates also inspect configured router/HMR ports before returning `nextAction`. If the configured port already serves the same app but no live machine project is registered, the next action is runtime tracking repair, not starting a second dev server.
 
@@ -122,7 +123,7 @@ App-bound tools require `projectId` when called through `proteum mcp`:
 
 | Tool | Purpose |
 | --- | --- |
-| `workflow_start` | One-call bootstrap with resolved project, runtime, selected instruction previews, owner summary, doctor summaries, duplicate-avoidance rules, and next actions |
+| `workflow_start` | One-call bootstrap with resolved project, fresh-copy readiness, runtime, selected instruction previews, owner summary, doctor summaries, duplicate-avoidance rules, and next actions |
 | `runtime_status` | Manifest summary, selected runtime, tracked sessions, health, and MCP URL |
 | `orient` | Owner, instruction routing, connected boundaries, and next actions |
 | `instructions_resolve` | Selected instruction files for a query, with short previews and full-read policy |

package/docs/request-tracing.md

@@ -33,7 +33,7 @@ proteum perf memory --since 1h --group-by controller
 
 Default trace output is compact `proteum-agent-v1` JSON with counts, failed calls, error events, hot calls, and hot SQL. Use `--events` or `--full` only when raw event details, payload summaries, or SQL text are needed.
 
-When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates or unreachable runtime health, start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
+When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates, `data.readiness.state="blocked"`, or unreachable runtime health, resolve the readiness setup actions and start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
 
 Before reproducing a bug or starting a new test pass:
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.4",
+	"version": "2.5.5",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/tests/mcp.test.cjs

@@ -99,8 +99,53 @@ const createManifest = (appRoot, overrides = {}) => ({
 
 const writeProteumAppFixture = (appRoot, manifestOverrides = {}) => {
     writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(
+        path.join(appRoot, '.env'),
+        [
+            'ENV_NAME=local',
+            'ENV_PROFILE=dev',
+            `PORT=${manifestOverrides.routerPort || 3104}`,
+            `URL=http://localhost:${manifestOverrides.routerPort || 3104}`,
+            `URL_INTERNAL=http://localhost:${manifestOverrides.routerPort || 3104}`,
+            '',
+        ].join('\n'),
+    );
+    fs.mkdirSync(path.join(appRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Client\n');
+    writeFile(path.join(appRoot, 'client', 'pages', 'AGENTS.md'), '# Pages\n');
+    writeFile(path.join(appRoot, 'server', 'AGENTS.md'), '# Server\n');
+    writeFile(path.join(appRoot, 'server', 'routes', 'AGENTS.md'), '# Routes\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# App\n');
+    writeFile(path.join(appRoot, 'diagnostics.md'), '# Diagnostics\n');
+    writeFile(path.join(appRoot, '.proteum', 'manifest.json'), JSON.stringify(createManifest(appRoot, manifestOverrides), null, 2));
+};
+
+const writeFreshCopyFixture = (appRoot, manifestOverrides = {}) => {
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fresh-copy"}\n');
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(
+        path.join(appRoot, '.env.example'),
+        [
+            'ENV_NAME=local',
+            'ENV_PROFILE=dev',
+            'PORT=3020',
+            'URL=http://localhost:3020',
+            'URL_INTERNAL=http://localhost:3020',
+            'DATABASE_URL=mysql://user:pass@localhost:3306/app',
+            '',
+        ].join('\n'),
+    );
     writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
     writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(
+        path.join(appRoot, 'prisma', 'schema.prisma'),
+        ['generator client {', '  provider = "prisma-client-js"', '  output = "../var/prisma"', '}', '', 'datasource db {', '  provider = "mysql"', '}'].join(
+            '\n',
+        ),
+    );
     writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Client\n');
     writeFile(path.join(appRoot, 'client', 'pages', 'AGENTS.md'), '# Pages\n');
     writeFile(path.join(appRoot, 'server', 'AGENTS.md'), '# Server\n');
@@ -700,7 +745,10 @@ test('machine MCP router resolves projects by cwd and bootstraps workflow withou
     assert.equal(forwardedCall.name, 'workflow_start');
     assert.deepEqual(forwardedCall.arguments, { route: '/domains', task: 'read-only runtime health pass' });
     assert.equal(workflowPayload.data.project.projectId, productMachineRecord.projectId);
-    assert.equal(workflowPayload.nextActions[0].toolArgs.projectId, productMachineRecord.projectId);
+    assert.equal(
+        workflowPayload.nextActions.find((action) => action.tool === 'diagnose').toolArgs.projectId,
+        productMachineRecord.projectId,
+    );
 
     await client.close();
     await server.close();
@@ -785,6 +833,55 @@ test('machine MCP router resolves offline monorepo app candidates before dev is
     await server.close();
 });
 
+test('machine MCP workflow_start reports fresh-copy setup blockers before dev start', async (t) => {
+    const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-fresh-copy-registry-'));
+    process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = registryDir;
+    t.onTestFinished(() => {
+        if (previousRegistryDir === undefined) delete process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+        else process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = previousRegistryDir;
+    });
+
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-fresh-copy-'));
+    const appRoot = path.join(repoRoot, 'apps', 'product');
+    writeFreshCopyFixture(appRoot, {
+        identifier: 'FreshCopyApp',
+        name: 'Fresh Copy',
+        routerPort: 3022,
+    });
+
+    const server = createProteumMachineMcpServer({ version: 'test' });
+    const client = new Client({ name: 'machine-mcp-test', version: '1.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    const workflow = await client.callTool({
+        name: 'workflow_start',
+        arguments: { cwd: appRoot, task: 'prepare fresh copy' },
+    });
+    const payload = JSON.parse(workflow.content[0].text);
+    const actionLabels = payload.nextActions.map((action) => action.label);
+
+    assert.equal(payload.ok, true);
+    assert.equal(payload.data.readiness.state, 'blocked');
+    assert.equal(payload.data.readiness.env.app.present, false);
+    assert.equal(payload.data.readiness.dependencies.nodeModulesPresent, false);
+    assert.equal(payload.data.readiness.database.detected, true);
+    assert.equal(payload.data.readiness.database.generatedClientPresent, false);
+    assert.equal(actionLabels.includes('Copy App Env Example'), true);
+    assert.equal(actionLabels.includes('Install Dependencies'), true);
+    assert.equal(actionLabels.includes('Generate Prisma Client'), true);
+    assert.equal(actionLabels.includes('Start Dev'), true);
+    assert.match(payload.nextActions.find((action) => action.label === 'Install Dependencies').command, /npm install/);
+    assert.match(payload.nextActions.find((action) => action.label === 'Generate Prisma Client').command, /prisma generate/);
+    assert.doesNotMatch(workflow.content[0].text, /mysql:\/\/user:pass/);
+
+    await client.close();
+    await server.close();
+});
+
 test('machine MCP workflow_start blocks offline unbootstrapped Codex worktrees', async (t) => {
     const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
     const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-worktree-offline-'));