proteum 2.2.3 → 2.2.7

package/cli/commands/dev.ts

@@ -22,7 +22,6 @@ import {
 
 // Configs
 import Compiler from '../compiler';
-import { regex } from '../compiler/common';
 import { createDevEventServer } from './devEvents';
 import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
 import { clearInteractiveConsole } from '../presentation/welcome';
@@ -41,8 +40,7 @@ import {
 } from '../runtime/devSessions';
 import { resolveFrameworkInstallInfo } from '../paths';
 import { logVerbose } from '../runtime/verbose';
-import { inspectProjectAgentFiles } from '../utils/agents';
-import { runConfigureAgentsWizard } from './configure';
+import { configureProjectAgentInstructions, resolveProjectAgentMonorepoRoot } from '../utils/agents';
 
 // Core
 import { app, App } from '../app';
@@ -61,6 +59,7 @@ const hotReloadableServerPathPatterns = [
     /^server\/services\/.+\.controller\.[jt]sx?$/,
 ];
 const hotReloadableRoots = [() => app.paths.root, () => cli.paths.core.root];
+const transpileSourceWatchPattern = /\.(ts|tsx|js|jsx|css|less|scss)$/;
 
 /*----------------------------------
 - STATE
@@ -144,43 +143,74 @@ const createIgnoredWatchMatcher = (outputPaths: string[]) => (watchPath: string)
     return ignoredWatchPathPatterns.test(normalizedWatchPath);
 };
 
-const promptToConfigureAgentsIfMissing = async () => {
-    if (cli.args.json === true) return;
-    if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-
-    const inspection = inspectProjectAgentFiles({ appRoot: app.paths.root });
-    if (!inspection.missing.includes('AGENTS.md')) return;
+const promptBlockedAgentInstructionOverwrites = async (blockedPaths: string[]) => {
+    if (blockedPaths.length === 0) return [];
+    if (cli.args.json === true || !process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new UsageError(
+            [
+                'Proteum could not update managed instruction files because existing paths are blocked:',
+                ...blockedPaths.map((entry) => `- ${entry}`),
+                'Run `proteum configure agents` in an interactive terminal to choose which paths can be replaced.',
+            ].join('\n'),
+        );
+    }
 
-    console.info(await renderWarning('Proteum could not find the app-root `AGENTS.md` instruction file.'));
+    console.info(await renderWarning('Proteum found existing paths that block managed instruction updates.'));
     console.info(
         [
-            'Missing standard AGENTS files:',
-            ...inspection.missing.map((entry) => `- ${entry}`),
-            '',
-            'Run `proteum configure agents` now before starting the dev server?',
+            'Choose whether to overwrite each blocked path with a tracked Proteum instruction file:',
+            ...blockedPaths.map((entry) => `- ${entry}`),
         ].join('\n'),
     );
 
-    const response = await prompts(
-        {
-            type: 'confirm',
-            name: 'value',
-            message: 'Run the configure-agents wizard now?',
-            initial: true,
-        },
-        {
-            onCancel: () => {
-                throw new UsageError('Cancelled `proteum dev`.');
+    const overwriteBlockedPaths: string[] = [];
+
+    for (const blockedPath of blockedPaths) {
+        const response = await prompts(
+            {
+                type: 'confirm',
+                name: 'value',
+                message: `Overwrite ${blockedPath}?`,
+                initial: false,
             },
-        },
-    );
+            {
+                onCancel: () => {
+                    throw new UsageError('Cancelled `proteum dev`.');
+                },
+            },
+        );
+
+        if (response.value === true) overwriteBlockedPaths.push(blockedPath);
+    }
 
-    if (response.value !== true) return;
+    return overwriteBlockedPaths;
+};
+
+const ensureProjectAgentInstructions = async () => {
+    const monorepoRoot = resolveProjectAgentMonorepoRoot(app.paths.root);
+    const preview = configureProjectAgentInstructions({
+        appRoot: app.paths.root,
+        coreRoot: cli.paths.core.root,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedAgentInstructionOverwrites(preview.blocked);
 
-    await runConfigureAgentsWizard({
+    const result = configureProjectAgentInstructions({
         appRoot: app.paths.root,
         coreRoot: cli.paths.core.root,
+        monorepoRoot,
+        overwriteBlockedPaths,
     });
+
+    if (result.blocked.length === 0) return;
+
+    throw new UsageError(
+        [
+            'Proteum could not update all managed instruction files because these paths were left blocked:',
+            ...result.blocked.map((entry) => `- ${entry}`),
+        ].join('\n'),
+    );
 };
 
 const getDevAppName = (app: App) =>
@@ -530,11 +560,11 @@ type TIndexedSourceWatchEvent = 'change' | 'rename';
 type TIndexedSourceWatchCompilerName = 'server' | 'client';
 type TIndexedSourceWatchInvalidateTarget = 'all' | TIndexedSourceWatchCompilerName;
 type TIndexedSourceWatchRule = {
-    compilerName: TIndexedSourceWatchCompilerName;
+    compilerNames: TIndexedSourceWatchCompilerName[];
     rootPath: string;
     relativePathPattern: RegExp;
     eventTypes: TIndexedSourceWatchEvent[];
-    invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+    invalidateTargets: TIndexedSourceWatchInvalidateTarget[];
 };
 type TNamedWatching = { compiler: { name?: string }; invalidate: () => void };
 type TMultiWatchingLike = TDevWatching & { watchings?: TNamedWatching[] };
@@ -553,26 +583,26 @@ const resolveIndexedSourceWatchRules = (): TIndexedSourceWatchRule[] => {
 
     return [
         {
-            compilerName: 'server',
+            compilerNames: ['server'],
             rootPath: app.paths.root,
             relativePathPattern: /^commands(?:\/|$)/,
             eventTypes: ['rename'],
-            invalidateTarget: 'all',
+            invalidateTargets: ['all'],
         },
         {
-            compilerName: 'server',
+            compilerNames: ['server'],
             rootPath: cli.paths.core.root,
             relativePathPattern: /^commands(?:\/|$)/,
             eventTypes: ['rename'],
-            invalidateTarget: 'all',
+            invalidateTargets: ['all'],
         },
         ...transpileWatchRoots.map(
             (rootPath): TIndexedSourceWatchRule => ({
-                compilerName: 'server',
+                compilerNames: ['client', 'server'],
                 rootPath,
-                relativePathPattern: regex.scripts,
+                relativePathPattern: transpileSourceWatchPattern,
                 eventTypes: ['change', 'rename'],
-                invalidateTarget: 'server',
+                invalidateTargets: ['client', 'server'],
             }),
         ),
     ];
@@ -587,6 +617,12 @@ const findCompilerWatching = (
     return childWatchings?.find((childWatching) => childWatching.compiler.name === compilerName);
 };
 
+const formatInvalidateTargets = (invalidateTargets: TIndexedSourceWatchCompilerName[]) => {
+    if (invalidateTargets.length === 1) return invalidateTargets[0];
+    if (invalidateTargets.length === 2) return `${invalidateTargets[0]} and ${invalidateTargets[1]}`;
+    return `${invalidateTargets.slice(0, -1).join(', ')}, and ${invalidateTargets[invalidateTargets.length - 1]}`;
+};
+
 const closeFsWatcher = async (watcher: FSWatcher) => {
     await new Promise<void>((resolve) => {
         watcher.once('close', () => resolve());
@@ -618,7 +654,7 @@ const createIndexedSourceWatching = ({
 
         if (pendingInvalidateTargets.has('all')) {
             pendingInvalidateTargets.clear();
-            logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
+            logVerbose('Indexed source files changed. Invalidating all dev compilers to refresh generated artifacts.');
             watching.invalidate();
             return;
         }
@@ -630,40 +666,57 @@ const createIndexedSourceWatching = ({
 
         if (invalidateTargets.length === 0) return;
 
-        logVerbose('Transpiled source files changed. Invalidating the server compiler to refresh mutable package code.');
+        const compilerWatchings: TNamedWatching[] = [];
+
         for (const invalidateTarget of invalidateTargets) {
             const compilerWatching = findCompilerWatching(watching, invalidateTarget);
 
             if (!compilerWatching) {
+                logVerbose('Transpiled source files changed. Invalidating all dev compilers to refresh mutable package code.');
                 watching.invalidate();
                 return;
             }
 
+            compilerWatchings.push(compilerWatching);
+        }
+
+        logVerbose(
+            `Transpiled source files changed. Invalidating ${formatInvalidateTargets(
+                invalidateTargets,
+            )} compilers to refresh mutable package code.`,
+        );
+        for (const compilerWatching of compilerWatchings) {
             compilerWatching.invalidate();
         }
     };
 
     const queueInvalidate = ({
-        compilerName,
+        compilerNames,
         filepath,
-        invalidateTarget,
+        invalidateTargets,
     }: {
-        compilerName: TIndexedSourceWatchCompilerName;
+        compilerNames: TIndexedSourceWatchCompilerName[];
         filepath: string;
-        invalidateTarget: TIndexedSourceWatchInvalidateTarget;
+        invalidateTargets: TIndexedSourceWatchInvalidateTarget[];
     }) => {
         const normalizedFilepath = normalizeWatchPath(filepath);
-        const queueKey = `${invalidateTarget}:${compilerName}:${normalizedFilepath}`;
+        const queueKey = `${invalidateTargets.join(',')}:${compilerNames.join(',')}:${normalizedFilepath}`;
         const queuedAt = recentQueuedChanges.get(queueKey);
 
         if (queuedAt !== undefined && Date.now() - queuedAt < 250) return;
 
         recentQueuedChanges.set(queueKey, Date.now());
-        const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
 
-        changedFiles.add(normalizedFilepath);
-        pendingChanges.set(compilerName, changedFiles);
-        pendingInvalidateTargets.add(invalidateTarget);
+        for (const compilerName of compilerNames) {
+            const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
+
+            changedFiles.add(normalizedFilepath);
+            pendingChanges.set(compilerName, changedFiles);
+        }
+
+        for (const invalidateTarget of invalidateTargets) {
+            pendingInvalidateTargets.add(invalidateTarget);
+        }
 
         if (invalidateTimer) return;
         invalidateTimer = setTimeout(flushInvalidate, 40);
@@ -682,9 +735,9 @@ const createIndexedSourceWatching = ({
                 if (!watchRule.eventTypes.includes(normalizedEventType) && relativePath) return;
 
                 queueInvalidate({
-                    compilerName: watchRule.compilerName,
+                    compilerNames: watchRule.compilerNames,
                     filepath: relativePath ? path.join(rootPath, relativePath) : rootPath,
-                    invalidateTarget: watchRule.invalidateTarget,
+                    invalidateTargets: watchRule.invalidateTargets,
                 });
             }),
         );
@@ -755,7 +808,7 @@ const runDevLoop = async () => {
             // - Node modules except 5HTP core (framework dev mode)
             // - Generated files during runtime (cause infinite loop. Ex: models.d.ts)
             // - Webpack output folders (`./dev`, legacy `./bin`)
-            ignored: ignoredWatchMatcher,
+            ignored: ignoredWatchMatcher as never,
 
             //aggregateTimeout: 1000,
         },
@@ -880,6 +933,6 @@ export const run = async () => {
         return;
     }
 
-    await promptToConfigureAgentsIfMissing();
+    await ensureProjectAgentInstructions();
     await runDevLoop();
 };

package/cli/compiler/artifacts/manifest.ts

@@ -5,7 +5,6 @@ import app from '../../app';
 import cli from '../..';
 import { inspectProteumEnv } from '../../../common/env/proteumEnv';
 import { reservedRouteOptionKeys, routeOptionKeys } from '../../../common/router/pageData';
-import { getProjectInstructionGitignoreEntries } from '../../utils/agents';
 import {
     TProteumManifest,
     TProteumManifestCommand,
@@ -40,10 +39,7 @@ const collectManifestDiagnostics = ({
     routes: TProteumManifest['routes'];
 }) => {
     const diagnostics: TProteumManifestDiagnostic[] = [];
-    const expectedGitignoreEntries = [
-        ...requiredGitignoreEntries,
-        ...getProjectInstructionGitignoreEntries({ coreRoot: cli.paths.core.root }),
-    ];
+    const expectedGitignoreEntries = [...requiredGitignoreEntries];
 
     const pushDiagnostic = (diagnostic: TProteumManifestDiagnostic) => {
         diagnostics.push(diagnostic);

package/cli/presentation/commands.ts

@@ -113,22 +113,22 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
     configure: {
         name: 'configure',
         category: 'Project scaffolding',
-        summary: 'Interactively configure Proteum-managed instruction stubs for a standalone app or monorepo app root.',
+        summary: 'Interactively configure tracked Proteum instruction files for a standalone app or monorepo app root.',
         usage: 'proteum configure agents',
         bestFor:
-            'Creating or switching the managed `AGENTS.md` instruction layout intentionally instead of having `init` or `dev` write instruction files implicitly.',
+            'Creating or switching the tracked instruction layout intentionally while keeping Proteum-owned instructions embedded in managed sections.',
         examples: [
             {
-                description: 'Configure instruction stubs for the current standalone app',
+                description: 'Configure instruction files for the current standalone app',
                 command: 'proteum configure agents',
             },
         ],
         notes: [
-            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` stub.',
-            'Standalone mode writes the full app-root instruction set into the current Proteum app root.',
-            'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and switches the current app root `AGENTS.md` to the app-root addendum.',
-            'If a target path already contains a non-managed file or foreign symlink, the interactive flow asks whether to overwrite it with the Proteum-managed stub.',
-            'Declined non-managed paths are left untouched; Proteum still creates missing stubs and updates stubs or symlinks it already manages.',
+            'This command is interactive. It asks whether the current Proteum app belongs to a monorepo and, if so, which ancestor path should receive the reusable root `AGENTS.md` file.',
+            'Standalone mode writes tracked instruction files into the current Proteum app root.',
+            'Monorepo mode writes the reusable root `AGENTS.md` into the chosen monorepo root and the app-root instruction files into the current Proteum app root.',
+            'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
+            'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
         ],
         status: 'experimental',
     },
@@ -191,7 +191,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
         notes: [
             'Use `--cwd` when the target Proteum app lives in another worktree or checkout and you do not want to `cd` first.',
             'Proteum writes a machine-readable dev session file under `var/run/proteum/dev/<port>.json` by default; override it with `--session-file` when an agent needs a stable path.',
-            'Before the interactive dev loop starts, Proteum offers to launch `proteum configure agents` when the app root is missing `AGENTS.md`.',
+            'Before the dev loop starts, Proteum ensures tracked instruction files contain the current managed `# Proteum Instructions` section.',
             'Use `--replace-existing` when retries should stop the previously tracked matching session before starting a new one.',
             '`proteum dev list` inspects tracked sessions for the current app root. Add `--stale` to show only orphaned or dead sessions.',
             '`proteum dev stop` targets the current session file by default. Add `--all` to stop every tracked session for the current app root.',

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('When the app root is missing `AGENTS.md`, the interactive `proteum dev` start offers to launch `proteum configure agents` before the dev loop begins.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/scaffold/index.ts

@@ -5,7 +5,6 @@ import { UsageError } from 'clipanion';
 
 import cli from '..';
 import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
-import { renderProjectInstructionGitignoreBlock } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
     createClientTsconfigTemplate,
@@ -656,9 +655,7 @@ const createInitFilePlans = ({ appRoot, config }: { appRoot: string; config: TSc
     },
     {
         relativePath: '.gitignore',
-        content: createGitignoreTemplate({
-            projectInstructionGitignoreBlock: renderProjectInstructionGitignoreBlock({ coreRoot: cli.paths.core.root }),
-        }),
+        content: createGitignoreTemplate(),
     },
     {
         relativePath: 'eslint.config.mjs',
@@ -727,7 +724,7 @@ export const runInitScaffold = async () => {
               ? 'Run `npm run dev` in the new app directory.'
               : 'Run `npm install`, then `npm run dev` in the new app directory.',
     );
-    result.nextSteps.push('Run `proteum configure agents` when you want Proteum-managed instruction stubs.');
+    result.nextSteps.push('Run `proteum configure agents` when you want tracked Proteum instruction files.');
     result.nextSteps.push('Use `proteum create page|controller|command|route|service ...` to add app artifacts.');
 
     printResult(result, createInitSummary(result, config));

package/cli/scaffold/templates.ts

@@ -253,11 +253,7 @@ export const createServerTsconfigTemplate = (paths: TTsconfigTemplatePaths) => `
 }
 `;
 
-export const createGitignoreTemplate = ({
-    projectInstructionGitignoreBlock,
-}: {
-    projectInstructionGitignoreBlock: string;
-}) => `node_modules
+export const createGitignoreTemplate = () => `node_modules
 /.proteum
 /.cache
 /bin
@@ -265,8 +261,6 @@ export const createGitignoreTemplate = ({
 /var
 /proteum.connected.json
 .env
-
-${projectInstructionGitignoreBlock}
 `;
 
 export const createEnvTemplate = ({ port, url }: { port: number; url: string }) => `ENV_NAME=local