proteum 2.5.5 → 2.5.7

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,31 @@ import { createStartDevCommand, findProteumAppRootsUnder, readProteumAppRootSumm
 - TYPES
 ----------------------------------*/
 
-type TProjectInstructionArgs = { appRoot?: string; coreRoot: string; includeMonorepoRegistry?: boolean; monorepoRoot?: string };
+type TProjectInstructionArgs = {
+    appRoot?: string;
+    coreRoot: string;
+    includeMonorepoRegistry?: boolean;
+    instructionRoot: string;
+    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 +66,12 @@ export type TConfigureProjectAgentInstructionsResult = {
     updatedGitignores: string[];
 };
 
+export type TConfigureMonorepoProjectAgentInstructionsResult = Omit<TConfigureProjectAgentInstructionsResult, 'appRoot'> & {
+    appRoots: string[];
+    monorepoRoot: string;
+    mode: 'monorepo';
+};
+
 /*----------------------------------
 - CONSTANTS
 ----------------------------------*/
@@ -84,6 +107,14 @@ const sharedTestAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: path.join('tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), ensureParentDir: true, content: 'source' },
 ];
 
+const projectInstructionSourceMapEntries = [
+    { label: 'Root contract fallback', projectPath: 'AGENTS.md' },
+    { label: 'Documentation fallback', projectPath: 'DOCUMENTATION.md' },
+    { label: 'Diagnostics fallback', projectPath: 'diagnostics.md' },
+    { label: 'Optimization fallback', projectPath: 'optimizations.md' },
+    { label: 'Coding style fallback', projectPath: 'CODING_STYLE.md' },
+];
+
 const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md', content: 'router' },
     ...sharedRootDocumentInstructionDefinitions,
@@ -115,6 +146,9 @@ export function configureProjectAgentInstructions({
     appRoot,
     coreRoot,
     dryRun = false,
+    includeAppInstructions = true,
+    includeRootInstructions = true,
+    markCurrentAppInMonorepoRegistry = true,
     monorepoRoot,
     overwriteBlockedPaths = [],
 }: TConfigureProjectAgentInstructionsArgs): TConfigureProjectAgentInstructionsResult {
@@ -139,6 +173,7 @@ export function configureProjectAgentInstructions({
     const appEmbeddedInstructions = renderEmbeddedProjectInstructions({
         appRoot: normalizedAppRoot,
         coreRoot,
+        instructionRoot: normalizedAppRoot,
         monorepoRoot: normalizedMonorepoRoot,
     });
     const rootEmbeddedInstructions =
@@ -147,11 +182,13 @@ export function configureProjectAgentInstructions({
                   appRoot: normalizedAppRoot,
                   coreRoot,
                   includeMonorepoRegistry: true,
+                  instructionRoot: normalizedMonorepoRoot,
+                  monorepoRegistryCurrentAppRoot: markCurrentAppInMonorepoRegistry ? normalizedAppRoot : undefined,
                   monorepoRoot: normalizedMonorepoRoot,
               })
             : appEmbeddedInstructions;
 
-    if (mode === 'monorepo' && normalizedMonorepoRoot) {
+    if (includeRootInstructions && mode === 'monorepo' && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
 
         const rootInstructions = getRootAgentInstructionDefinitions();
@@ -172,52 +209,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 +943,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 +960,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 +980,14 @@ function renderMonorepoAppRegistry({
     ];
 }
 
-function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoRegistry = false, monorepoRoot }: TProjectInstructionArgs) {
+function renderEmbeddedProjectInstructions({
+    appRoot,
+    coreRoot,
+    includeMonorepoRegistry = false,
+    instructionRoot,
+    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 +1019,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`.',
@@ -945,11 +1075,14 @@ function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoR
         '',
         '## Canonical Source Map',
         '',
-        `- Root contract fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'AGENTS.md'))}`,
-        `- Documentation fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'DOCUMENTATION.md'))}`,
-        `- Diagnostics fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'diagnostics.md'))}`,
-        `- Optimization fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'optimizations.md'))}`,
-        `- Coding style fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'CODING_STYLE.md'))}`,
+        ...projectInstructionSourceMapEntries.map(
+            ({ label, projectPath }) =>
+                `- ${label}: ${formatProjectInstructionSourceMapPath({
+                    coreRoot,
+                    instructionRoot,
+                    projectPath,
+                })}`,
+        ),
         '',
     ];
 
@@ -1091,6 +1224,41 @@ function formatResultPath(rootDir: string, relativePath: string) {
     return normalizeProjectPathForGitignore(path.join(rootDir, relativePath));
 }
 
+function formatProjectInstructionSourceMapPath({
+    coreRoot,
+    instructionRoot,
+    projectPath,
+}: {
+    coreRoot: string;
+    instructionRoot: string;
+    projectPath: string;
+}) {
+    const sourceRoot = resolveProjectInstructionSourceMapRoot({ coreRoot, instructionRoot });
+    const sourcePath = path.resolve(sourceRoot, 'agents', 'project', projectPath);
+    const relativePath = path.relative(path.resolve(instructionRoot), sourcePath);
+
+    return normalizeProjectPathForGitignore(relativePath);
+}
+
+function resolveProjectInstructionSourceMapRoot({ coreRoot, instructionRoot }: { coreRoot: string; instructionRoot: string }) {
+    const visibleInstallRoot = findVisibleProteumInstructionRoot(instructionRoot);
+
+    return visibleInstallRoot || coreRoot;
+}
+
+function findVisibleProteumInstructionRoot(startRoot: string) {
+    let currentPath = path.resolve(startRoot);
+
+    while (true) {
+        const candidate = path.join(currentPath, 'node_modules', 'proteum');
+        if (fs.existsSync(path.join(candidate, 'agents', 'project'))) return candidate;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+}
+
 export function resolveCanonicalPath(inputPath: string) {
     const resolvedPath = path.resolve(inputPath);
 

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.7",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",