proteum 2.5.5 → 2.5.6

package/cli/runtime/worktreeBootstrap.ts

@@ -2,6 +2,7 @@ import cp from 'child_process';
 import crypto from 'crypto';
 import fs from 'fs-extra';
 import path from 'path';
+import { findProteumAppRootsUnder } from '../utils/appRoots';
 
 /*----------------------------------
 - TYPES
@@ -124,6 +125,30 @@ export type TRunWorktreeBootstrapCreateOptions = TRunWorktreeBootstrapInitOption
     targetRepoRoot: string;
 };
 
+export type TMonorepoWorktreeBootstrapAppResult = {
+    appRoot: string;
+    error?: string;
+    markerFilepath?: string;
+    ok: boolean;
+    refresh?: string;
+    relativeAppRoot: string;
+    runtimeStatus?: string;
+    sourceAppRoot?: string;
+    status?: TWorktreeBootstrapStatus;
+};
+
+export type TRunMonorepoWorktreeBootstrapInitOptions = Omit<TRunWorktreeBootstrapInitOptions, 'appRoot' | 'source'> & {
+    appRoots?: string[];
+    monorepoRoot: string;
+    source?: string;
+};
+
+export type TRunMonorepoWorktreeBootstrapCreateOptions = TRunMonorepoWorktreeBootstrapInitOptions & {
+    base?: string;
+    branch: string;
+    targetRepoRoot: string;
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -139,6 +164,16 @@ const codexWorktreeSegment = `${path.sep}.codex${path.sep}worktrees${path.sep}`;
 
 const normalizePath = (value: string) => path.normalize(path.resolve(value));
 
+const normalizeExistingPath = (value: string) => {
+    const normalized = normalizePath(value);
+
+    try {
+        return path.normalize(fs.realpathSync(normalized));
+    } catch {
+        return normalized;
+    }
+};
+
 const isTruthyEnv = (value: string | undefined) => value === '1' || value === 'true' || value === 'yes';
 
 const nowIso = () => new Date().toISOString();
@@ -699,3 +734,131 @@ export const runWorktreeBootstrapCreate = async ({
         worktreeBootstrap: initResult,
     };
 };
+
+const findBootstrapInstallRoot = (appRoot: string) => {
+    const packageLockFilepath = findNearestExistingPath(appRoot, 'package-lock.json');
+    return packageLockFilepath ? path.dirname(packageLockFilepath) : normalizePath(appRoot);
+};
+
+const createSharedDependencyRunner = (runDependencies: (appRoot: string) => Promise<void> = runNpmInstall) => {
+    const completedInstallRoots = new Set<string>();
+
+    return async (appRoot: string) => {
+        const installRoot = findBootstrapInstallRoot(appRoot);
+        if (completedInstallRoots.has(installRoot)) return;
+
+        completedInstallRoots.add(installRoot);
+        await runDependencies(installRoot);
+    };
+};
+
+const resolveSourceAppRoot = ({
+    relativeAppRoot,
+    sourceRoot,
+}: {
+    relativeAppRoot: string;
+    sourceRoot?: string;
+}) => {
+    if (!sourceRoot) return undefined;
+
+    const normalizedSourceRoot = normalizeExistingPath(sourceRoot);
+    const sourceAppRoot = path.join(normalizedSourceRoot, relativeAppRoot);
+
+    if (fs.existsSync(sourceAppRoot)) return sourceAppRoot;
+
+    return undefined;
+};
+
+export const runMonorepoWorktreeBootstrapInit = async ({
+    appRoots,
+    monorepoRoot,
+    runDependencies,
+    source,
+    ...initOptions
+}: TRunMonorepoWorktreeBootstrapInitOptions) => {
+    const normalizedMonorepoRoot = normalizeExistingPath(monorepoRoot);
+    const targetAppRoots = (appRoots || findProteumAppRootsUnder(normalizedMonorepoRoot))
+        .map((appRoot) => normalizeExistingPath(appRoot))
+        .sort((left, right) => left.localeCompare(right));
+    const sharedDependencyRunner = createSharedDependencyRunner(runDependencies);
+    const apps: TMonorepoWorktreeBootstrapAppResult[] = [];
+
+    if (targetAppRoots.length === 0) throw new Error(`No Proteum app roots were found under ${normalizedMonorepoRoot}.`);
+
+    for (const appRoot of targetAppRoots) {
+        const relativeAppRoot = path.relative(normalizedMonorepoRoot, appRoot) || '.';
+        const sourceAppRoot = resolveSourceAppRoot({
+            relativeAppRoot,
+            sourceRoot: source,
+        });
+
+        try {
+            const result = await runWorktreeBootstrapInit({
+                ...initOptions,
+                appRoot,
+                runDependencies: sharedDependencyRunner,
+                source: sourceAppRoot,
+            });
+
+            apps.push({
+                appRoot,
+                markerFilepath: result.markerFilepath,
+                ok: true,
+                refresh: result.refresh,
+                relativeAppRoot,
+                runtimeStatus: result.runtimeStatus,
+                sourceAppRoot,
+                status: result.status,
+            });
+        } catch (error) {
+            apps.push({
+                appRoot,
+                error: error instanceof Error ? error.message : String(error),
+                ok: false,
+                relativeAppRoot,
+                sourceAppRoot,
+            });
+        }
+    }
+
+    return {
+        appRoots: targetAppRoots,
+        apps,
+        failed: apps.filter((entry) => !entry.ok).length,
+        monorepoRoot: normalizedMonorepoRoot,
+        ok: apps.every((entry) => entry.ok),
+        sourceRoot: source ? normalizeExistingPath(source) : undefined,
+    };
+};
+
+export const runMonorepoWorktreeBootstrapCreate = async ({
+    base = 'HEAD',
+    branch,
+    source,
+    targetRepoRoot,
+    ...initOptions
+}: TRunMonorepoWorktreeBootstrapCreateOptions) => {
+    if (!branch.trim()) throw new Error('worktree create requires --branch <branch>.');
+    if (!targetRepoRoot.trim()) throw new Error('worktree create requires <target-repo-root>.');
+
+    const normalizedSourceRoot = normalizeExistingPath(source || initOptions.monorepoRoot);
+    const normalizedTargetRepoRoot = path.resolve(targetRepoRoot);
+    const sourceRepoRoot = await findGitRepoRoot(normalizedSourceRoot);
+
+    await runCapture('git', ['worktree', 'add', '-b', branch, normalizedTargetRepoRoot, base], { cwd: sourceRepoRoot });
+
+    const initResult = await runMonorepoWorktreeBootstrapInit({
+        ...initOptions,
+        monorepoRoot: normalizedTargetRepoRoot,
+        refresh: true,
+        source: normalizedSourceRoot,
+    });
+
+    return {
+        branch,
+        sourceMonorepoRoot: normalizedSourceRoot,
+        sourceRepoRoot,
+        targetRepoRoot: normalizedTargetRepoRoot,
+        worktreeBootstrap: initResult,
+    };
+};

package/cli/utils/agents.ts

@@ -12,14 +12,30 @@ import { createStartDevCommand, findProteumAppRootsUnder, readProteumAppRootSumm
 - TYPES
 ----------------------------------*/
 
-type TProjectInstructionArgs = { appRoot?: string; coreRoot: string; includeMonorepoRegistry?: boolean; monorepoRoot?: string };
+type TProjectInstructionArgs = {
+    appRoot?: string;
+    coreRoot: string;
+    includeMonorepoRegistry?: boolean;
+    monorepoRegistryCurrentAppRoot?: string;
+    monorepoRoot?: string;
+};
 type TConfigureProjectAgentInstructionsArgs = {
     appRoot: string;
     coreRoot: string;
     dryRun?: boolean;
+    includeAppInstructions?: boolean;
+    includeRootInstructions?: boolean;
+    markCurrentAppInMonorepoRegistry?: boolean;
     monorepoRoot?: string;
     overwriteBlockedPaths?: string[];
 };
+type TConfigureMonorepoProjectAgentInstructionsArgs = {
+    appRoots: string[];
+    coreRoot: string;
+    dryRun?: boolean;
+    monorepoRoot: string;
+    overwriteBlockedPaths?: string[];
+};
 
 type TAgentInstructionDefinition = {
     projectPath: string;
@@ -49,6 +65,12 @@ export type TConfigureProjectAgentInstructionsResult = {
     updatedGitignores: string[];
 };
 
+export type TConfigureMonorepoProjectAgentInstructionsResult = Omit<TConfigureProjectAgentInstructionsResult, 'appRoot'> & {
+    appRoots: string[];
+    monorepoRoot: string;
+    mode: 'monorepo';
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -115,6 +137,9 @@ export function configureProjectAgentInstructions({
     appRoot,
     coreRoot,
     dryRun = false,
+    includeAppInstructions = true,
+    includeRootInstructions = true,
+    markCurrentAppInMonorepoRegistry = true,
     monorepoRoot,
     overwriteBlockedPaths = [],
 }: TConfigureProjectAgentInstructionsArgs): TConfigureProjectAgentInstructionsResult {
@@ -147,11 +172,12 @@ export function configureProjectAgentInstructions({
                   appRoot: normalizedAppRoot,
                   coreRoot,
                   includeMonorepoRegistry: true,
+                  monorepoRegistryCurrentAppRoot: markCurrentAppInMonorepoRegistry ? normalizedAppRoot : undefined,
                   monorepoRoot: normalizedMonorepoRoot,
               })
             : appEmbeddedInstructions;
 
-    if (mode === 'monorepo' && normalizedMonorepoRoot) {
+    if (includeRootInstructions && mode === 'monorepo' && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
 
         const rootInstructions = getRootAgentInstructionDefinitions();
@@ -172,52 +198,127 @@ export function configureProjectAgentInstructions({
             result.updatedGitignores.push(path.join(normalizedMonorepoRoot, '.gitignore'));
     }
 
-    const appInstructions = getAppAgentInstructionDefinitions({ mode });
-    const appFiles = ensureInstructionFiles(
-        normalizedAppRoot,
-        appInstructions,
-        '[agents]',
-        path.join(coreRoot, 'agents', 'project'),
-        appEmbeddedInstructions,
-        {
-            dryRun,
-            overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
-        },
-    );
-    mergeInstructionResults(result, appFiles, normalizedAppRoot);
-
-    if (mode === 'monorepo') {
-        const retiredAppRootFiles = removeManagedInstructionFiles(
+    if (includeAppInstructions) {
+        const appInstructions = getAppAgentInstructionDefinitions({ mode });
+        const appFiles = ensureInstructionFiles(
             normalizedAppRoot,
-            [...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions],
+            appInstructions,
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
+            appEmbeddedInstructions,
             {
                 dryRun,
+                overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
             },
         );
-        mergeInstructionResults(result, retiredAppRootFiles, normalizedAppRoot);
-    }
+        mergeInstructionResults(result, appFiles, normalizedAppRoot);
+
+        if (mode === 'monorepo') {
+            const retiredAppRootFiles = removeManagedInstructionFiles(
+                normalizedAppRoot,
+                [...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions],
+                '[agents]',
+                path.join(coreRoot, 'agents', 'project'),
+                {
+                    dryRun,
+                },
+            );
+            mergeInstructionResults(result, retiredAppRootFiles, normalizedAppRoot);
+        }
 
-    const appGitignoreCleanupInstructions =
-        mode === 'monorepo'
-            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions]
-            : appInstructions;
-
-    if (
-        !dryRun &&
-        removeInstructionGitignoreEntries({
-            rootDir: normalizedAppRoot,
-            instructionDefinitions: appGitignoreCleanupInstructions,
-        })
-    )
-        result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
+        const appGitignoreCleanupInstructions =
+            mode === 'monorepo'
+                ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions]
+                : appInstructions;
+
+        if (
+            !dryRun &&
+            removeInstructionGitignoreEntries({
+                rootDir: normalizedAppRoot,
+                instructionDefinitions: appGitignoreCleanupInstructions,
+            })
+        )
+            result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
+    }
 
     return result;
 }
 
 export const configureProjectAgentSymlinks = configureProjectAgentInstructions;
 
+export function configureMonorepoProjectAgentInstructions({
+    appRoots,
+    coreRoot,
+    dryRun = false,
+    monorepoRoot,
+    overwriteBlockedPaths = [],
+}: TConfigureMonorepoProjectAgentInstructionsArgs): TConfigureMonorepoProjectAgentInstructionsResult {
+    const normalizedMonorepoRoot = path.resolve(monorepoRoot);
+    const normalizedAppRoots = [...new Set(appRoots.map((appRoot) => path.resolve(appRoot)))].sort((left, right) =>
+        left.localeCompare(right),
+    );
+    const [firstAppRoot] = normalizedAppRoots;
+
+    if (!firstAppRoot) throw new Error('No Proteum app roots were found under the monorepo root.');
+
+    const result: TConfigureMonorepoProjectAgentInstructionsResult = {
+        appRoots: normalizedAppRoots,
+        blocked: [],
+        created: [],
+        mode: 'monorepo',
+        monorepoRoot: normalizedMonorepoRoot,
+        overwritten: [],
+        removed: [],
+        skipped: [],
+        updated: [],
+        updatedGitignores: [],
+    };
+    const mergeProjectResult = (next: TConfigureProjectAgentInstructionsResult) => {
+        result.blocked = [...new Set([...result.blocked, ...next.blocked])];
+        result.created = [...new Set([...result.created, ...next.created])];
+        result.overwritten = [...new Set([...result.overwritten, ...next.overwritten])];
+        result.removed = [...new Set([...result.removed, ...next.removed])];
+        result.skipped = [...new Set([...result.skipped, ...next.skipped])];
+        result.updated = [...new Set([...result.updated, ...next.updated])];
+        result.updatedGitignores = [...new Set([...result.updatedGitignores, ...next.updatedGitignores])];
+    };
+
+    mergeProjectResult(
+        configureProjectAgentInstructions({
+            appRoot: firstAppRoot,
+            coreRoot,
+            dryRun,
+            includeAppInstructions: false,
+            markCurrentAppInMonorepoRegistry: false,
+            monorepoRoot: normalizedMonorepoRoot,
+            overwriteBlockedPaths,
+        }),
+    );
+
+    for (const appRoot of normalizedAppRoots) {
+        mergeProjectResult(
+            configureProjectAgentInstructions({
+                appRoot,
+                coreRoot,
+                dryRun,
+                includeRootInstructions: false,
+                monorepoRoot: normalizedMonorepoRoot,
+                overwriteBlockedPaths,
+            }),
+        );
+    }
+
+    result.blocked = [...new Set(result.blocked)];
+    result.created = [...new Set(result.created)];
+    result.overwritten = [...new Set(result.overwritten)];
+    result.removed = [...new Set(result.removed)];
+    result.skipped = [...new Set(result.skipped)];
+    result.updated = [...new Set(result.updated)];
+    result.updatedGitignores = [...new Set(result.updatedGitignores)];
+
+    return result;
+}
+
 export function resolveProjectAgentMonorepoRoot(appRoot: string) {
     const normalizedAppRoot = resolveCanonicalPath(appRoot);
     const likelyRepoRoot = findLikelyRepoRoot(normalizedAppRoot);
@@ -831,9 +932,11 @@ function renderSingleProjectInstruction({
 
 function renderMonorepoAppRegistry({
     appRoot,
+    currentAppRoot,
     monorepoRoot,
 }: {
     appRoot?: string;
+    currentAppRoot?: string;
     monorepoRoot?: string;
 }) {
     if (!monorepoRoot || !appRoot || path.resolve(monorepoRoot) === path.resolve(appRoot)) return [];
@@ -846,10 +949,13 @@ function renderMonorepoAppRegistry({
     return [
         '## Known Proteum Apps',
         '',
-        'This is a monorepo root wrapper. Do not start `npx proteum dev` from this root; start it from one app root below.',
+        'This is a monorepo root wrapper. Eligible Proteum commands run across the apps below from this root; use an app root when you need to target exactly one app.',
         '',
         ...summaries.map((summary) => {
-            const marker = path.resolve(summary.appRoot) === path.resolve(appRoot) ? ' (current configured app)' : '';
+            const marker =
+                currentAppRoot && path.resolve(summary.appRoot) === path.resolve(currentAppRoot)
+                    ? ' (current configured app)'
+                    : '';
             const port = summary.manifest?.routerPort ? `, default port ${summary.manifest.routerPort}` : '';
             const command = createStartDevCommand({
                 appRoot: summary.appRoot,
@@ -863,7 +969,13 @@ function renderMonorepoAppRegistry({
     ];
 }
 
-function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoRegistry = false, monorepoRoot }: TProjectInstructionArgs) {
+function renderEmbeddedProjectInstructions({
+    appRoot,
+    coreRoot,
+    includeMonorepoRegistry = false,
+    monorepoRegistryCurrentAppRoot,
+    monorepoRoot,
+}: TProjectInstructionArgs) {
     const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
     if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
 
@@ -895,7 +1007,13 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '',
         'CLI remains the reproducible surface for `dev`, `build`, `check`, `verify`, migrations, and final command evidence. MCP remains read-only and returns compact `proteum-mcp-v1` JSON.',
         '',
-        ...(includeMonorepoRegistry ? renderMonorepoAppRegistry({ appRoot, monorepoRoot }) : []),
+        ...(includeMonorepoRegistry
+            ? renderMonorepoAppRegistry({
+                  appRoot,
+                  currentAppRoot: monorepoRegistryCurrentAppRoot,
+                  monorepoRoot,
+              })
+            : []),
         '## Always-On Safety',
         '',
         '- Never edit generated files under `.proteum`.',

package/package.json

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

package/tests/agents-utils.test.cjs

@@ -8,7 +8,11 @@ process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 require('ts-node/register/transpile-only');
 
-const { configureProjectAgentInstructions, resolveProjectAgentMonorepoRoot } = require('../cli/utils/agents.ts');
+const {
+    configureMonorepoProjectAgentInstructions,
+    configureProjectAgentInstructions,
+    resolveProjectAgentMonorepoRoot,
+} = require('../cli/utils/agents.ts');
 
 const writeFile = (filepath, content) => {
     fs.mkdirSync(path.dirname(filepath), { recursive: true });
@@ -271,7 +275,7 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /## Known Proteum Apps/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /apps\/product/);
-    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Do not start `npx proteum dev` from this root/);
+    assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Eligible Proteum commands run across the apps below/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8'), /Worktree Preflight/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'CODING_STYLE.md'), 'utf8'), /## Source: CODING_STYLE\.md/);
     assert.match(fs.readFileSync(path.join(monorepoRoot, 'DOCUMENTATION.md'), 'utf8'), /## Source: DOCUMENTATION\.md/);
@@ -291,7 +295,7 @@ test('monorepo configure writes root and app instruction files', () => {
     const appAgentsContent = fs.readFileSync(path.join(appRoot, 'AGENTS.md'), 'utf8');
     assert.match(appAgentsContent, /## Agent Routing Contract/);
     assert.doesNotMatch(appAgentsContent, /## Known Proteum Apps/);
-    assert.doesNotMatch(appAgentsContent, /Do not start `npx proteum dev` from this root/);
+    assert.doesNotMatch(appAgentsContent, /Eligible Proteum commands run across the apps below/);
     assert.match(fs.readFileSync(path.join(appRoot, 'client', 'AGENTS.md'), 'utf8'), /## Source: client\/AGENTS\.md/);
     assertClaudeSymlink(appRoot);
     assertClaudeSymlink(appRoot, 'client');
@@ -302,6 +306,62 @@ test('monorepo configure writes root and app instruction files', () => {
     assert.equal(result.removed.some((entry) => entry.endsWith('/apps/product/CODING_STYLE.md')), true);
 });
 
+test('monorepo-wide configure writes shared root once and all app instruction files', () => {
+    const coreRoot = createCoreFixture();
+    const monorepoRoot = makeTempRoot();
+    const productRoot = path.join(monorepoRoot, 'apps', 'product');
+    const websiteRoot = path.join(monorepoRoot, 'apps', 'website');
+
+    for (const appRoot of [productRoot, websiteRoot]) {
+        fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+        fs.mkdirSync(path.join(appRoot, 'server'), { recursive: true });
+        writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
+        writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+        writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    }
+
+    const result = configureMonorepoProjectAgentInstructions({
+        appRoots: [websiteRoot, productRoot],
+        coreRoot,
+        monorepoRoot,
+    });
+    const rootAgentsContent = fs.readFileSync(path.join(monorepoRoot, 'AGENTS.md'), 'utf8');
+
+    assert.equal(result.mode, 'monorepo');
+    assert.deepEqual(result.appRoots, [productRoot, websiteRoot]);
+    assert.match(rootAgentsContent, /apps\/product/);
+    assert.match(rootAgentsContent, /apps\/website/);
+    assert.doesNotMatch(rootAgentsContent, /current configured app/);
+    assert.match(fs.readFileSync(path.join(productRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
+    assert.match(fs.readFileSync(path.join(websiteRoot, 'AGENTS.md'), 'utf8'), /## Agent Routing Contract/);
+    assert.equal(fs.existsSync(path.join(productRoot, 'CODING_STYLE.md')), false);
+    assert.equal(fs.existsSync(path.join(websiteRoot, 'CODING_STYLE.md')), false);
+});
+
+test('monorepo-wide configure dedupes app roots and blocked paths', () => {
+    const coreRoot = createCoreFixture();
+    const monorepoRoot = makeTempRoot();
+    const productRoot = path.join(monorepoRoot, 'apps', 'product');
+    const blockedClaudePath = path.join(productRoot, 'CLAUDE.md');
+
+    fs.mkdirSync(path.join(productRoot, 'client'), { recursive: true });
+    fs.mkdirSync(path.join(productRoot, 'server'), { recursive: true });
+    writeFile(path.join(productRoot, 'package.json'), '{"name":"fixture"}\n');
+    writeFile(path.join(productRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(productRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(blockedClaudePath, '# Local Claude Notes\n');
+
+    const result = configureMonorepoProjectAgentInstructions({
+        appRoots: [productRoot, productRoot],
+        coreRoot,
+        dryRun: true,
+        monorepoRoot,
+    });
+
+    assert.deepEqual(result.appRoots, [productRoot]);
+    assert.equal(result.blocked.filter((entry) => entry === blockedClaudePath).length, 1);
+});
+
 test('monorepo configure preserves local app-root documents', () => {
     const coreRoot = createCoreFixture();
     const monorepoRoot = makeTempRoot();

package/tests/cli-mcp-command.test.cjs

@@ -16,8 +16,32 @@ const writeFile = (filepath, content) => {
 
 const createProteumApp = (appRoot, { routerPort = 3020 } = {}) => {
     writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
-    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(
+        path.join(appRoot, 'identity.config.ts'),
+        `export default {
+    name: 'Product',
+    identifier: 'ProductApp',
+    description: 'Fixture app',
+    author: { name: 'Test', url: 'https://example.com', email: 'test@example.com' },
+    language: 'en',
+    maincolor: '#000000',
+    web: {
+        title: 'Product',
+        titleSuffix: 'Product',
+        fullTitle: 'Product',
+        description: 'Fixture app',
+        version: '1.0.0',
+        metas: {},
+        jsonld: {},
+    },
+};
+`,
+    );
     writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(
+        path.join(appRoot, '.env'),
+        `ENV_NAME=local\nENV_PROFILE=dev\nPORT=${routerPort}\nURL=http://localhost:${routerPort}\nURL_INTERNAL=http://localhost:${routerPort}\n`,
+    );
     fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
     fs.mkdirSync(path.join(appRoot, 'server'), { recursive: true });
     writeFile(
@@ -293,7 +317,7 @@ test('explain help describes compact section summaries', () => {
     assert.match(output, /Explicit section flags summarize those sections by default/);
 });
 
-test('runtime status from a monorepo wrapper returns app candidates instead of treating wrapper as app', () => {
+test('runtime status from a monorepo wrapper aggregates app runtime status', () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-wrapper-'));
     createProteumApp(path.join(repoRoot, 'apps', 'product'));
 
@@ -303,18 +327,38 @@ test('runtime status from a monorepo wrapper returns app candidates instead of t
     });
     const payload = JSON.parse(result.stdout);
 
-    assert.equal(result.status, 1);
-    assert.equal(payload.ok, false);
-    assert.equal(payload.data.appCandidates.length, 1);
-    assert.match(payload.nextActions[0].command, /cd "apps\/product"/);
-    assert.match(payload.nextActions[0].command, /npx proteum runtime status/);
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(payload.ok, true);
+    assert.equal(payload.data.apps.length, 1);
+    assert.equal(payload.data.apps[0].relativeAppRoot, 'apps/product');
+    assert.equal(payload.data.apps[0].ok, true);
+    assert.equal(payload.data.apps[0].json.data.appRoot, fs.realpathSync(path.join(repoRoot, 'apps', 'product')));
 });
 
-test('dev from a monorepo wrapper returns exact app-root start command', () => {
+test('dev list from a monorepo wrapper aggregates app session lists', () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-dev-wrapper-'));
     createProteumApp(path.join(repoRoot, 'apps', 'product'));
 
-    const result = spawnSync(process.execPath, [cliBin, 'dev', 'list'], {
+    const result = spawnSync(process.execPath, [cliBin, 'dev', 'list', '--json'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+    });
+    const payload = JSON.parse(result.stdout);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(payload.ok, true);
+    assert.equal(payload.data.apps.length, 1);
+    assert.equal(payload.data.apps[0].relativeAppRoot, 'apps/product');
+    assert.equal(payload.data.apps[0].json.sessions.length, 0);
+});
+
+test('monorepo command fan-out continues after app command failures', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-cli-dev-wrapper-failure-'));
+    createProteumApp(path.join(repoRoot, 'apps', 'product'));
+    createProteumApp(path.join(repoRoot, 'apps', 'website'));
+    writeFile(path.join(repoRoot, 'apps', 'website', 'identity.config.ts'), 'export default {};\n');
+
+    const result = spawnSync(process.execPath, [cliBin, 'dev', 'list', '--json'], {
         cwd: repoRoot,
         encoding: 'utf8',
     });
@@ -322,8 +366,13 @@ test('dev from a monorepo wrapper returns exact app-root start command', () => {
 
     assert.equal(result.status, 1);
     assert.equal(payload.ok, false);
-    assert.match(payload.nextActions[0].command, /cd "apps\/product"/);
-    assert.match(payload.nextActions[0].command, /npx proteum dev --session-file/);
+    assert.deepEqual(
+        payload.data.apps.map((app) => app.relativeAppRoot),
+        ['apps/product', 'apps/website'],
+    );
+    assert.equal(payload.data.apps[0].ok, true);
+    assert.equal(payload.data.apps[1].ok, false);
+    assert.match(payload.data.apps[1].stdout, /Invalid author/);
 });
 
 test('runtime status manifest guard points to explain manifest', () => {