proteum 2.1.9-7 → 2.1.9-8

package/AGENTS.md

@@ -44,6 +44,8 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
   [optional body]
   ```
   If the user replies exactly `commit`, use that Conventional Commit message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, then create the commit by running `git commit`.
+  After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
 ## Core Changes
 

package/README.md

@@ -336,7 +336,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum session` | Mint a dev-only auth session token and Playwright-ready cookie payload |
 | `proteum verify` | Validate framework-facing workflows across one or more running dev apps; `framework-change` is the built-in cross-reference-app check |
 | `proteum init` | Scaffold a new Proteum app with built-in deterministic templates |
-| `proteum configure agents` | Interactively configure Proteum-managed instruction symlinks for standalone or monorepo apps |
+| `proteum configure agents` | Interactively configure Proteum-managed instruction symlinks and confirm overwrites for standalone or monorepo apps |
 | `proteum create` | Scaffold a page, controller, command, route, or root service inside an app |
 
 Recommended daily workflow:
@@ -392,6 +392,8 @@ proteum create controller Founder/projects --method list
 proteum create service Conversion/Plans
 ```
 
+`proteum configure agents` asks before replacing any existing non-managed instruction file or foreign symlink. If you decline, that path is left untouched.
+
 `proteum connect`, `proteum explain`, `proteum doctor`, and `proteum diagnose` share the same generated manifest and contract state. `proteum perf` uses the same dev request-trace store as the profiler `Perf` tab. For the full diagnostics and tracing model, see [docs/diagnostics.md](docs/diagnostics.md) and [docs/request-tracing.md](docs/request-tracing.md).
 
 ## Dev Commands

package/agents/project/AGENTS.md

@@ -39,6 +39,8 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
   [optional body]
   ```
   Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
 ## Task Lifecycle
 
@@ -60,7 +62,8 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
-- When you have finished your work, ask the user whether they want a commit message.
+- When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
 ## Core Contracts
 

package/agents/project/root/AGENTS.md

@@ -31,6 +31,8 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
   [optional body]
   ```
   Then use that generated message, stage the task-related changed files with `git add` while avoiding unrelated user changes or incidental untracked files, and create the commit by running `git commit`. Do not stop at only suggesting the message.
+  After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
 ## Task Lifecycle
 
@@ -52,7 +54,8 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
 - Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
-- When you have finished your work, ask the user whether they want a commit message.
+- When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
+  `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
 
 ## Core Contracts
 

package/cli/commands/configure.ts

@@ -13,7 +13,7 @@ import cli from '..';
 import { renderRows } from '../presentation/layout';
 import { isLikelyProteumAppRoot } from '../presentation/commands';
 import { renderStep, renderSuccess, renderTitle, renderWarning } from '../presentation/ink';
-import { configureProjectAgentSymlinks } from '../utils/agents';
+import { configureProjectAgentSymlinks, type TConfigureProjectAgentSymlinksResult } from '../utils/agents';
 
 /*----------------------------------
 - HELPERS
@@ -89,6 +89,65 @@ const promptMonorepoRoot = async ({
     return resolveCanonicalPath(String(response.value || defaultRoot || ''));
 };
 
+const promptBlockedOverwritePaths = async (blockedPaths: string[]) => {
+    if (blockedPaths.length === 0) return [];
+
+    console.info(await renderWarning('Proteum found existing non-managed instruction paths.'));
+    console.info(['Choose whether to overwrite each path with a Proteum-managed symlink:', ...blockedPaths.map((entry) => `- ${entry}`)].join('\n'));
+
+    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 configure agents`.');
+                },
+            },
+        );
+
+        if (response.value === true) overwriteBlockedPaths.push(blockedPath);
+    }
+
+    return overwriteBlockedPaths;
+};
+
+const renderConfigureResultSections = (result: TConfigureProjectAgentSymlinksResult) => {
+    const sections: string[] = [];
+
+    sections.push(
+        renderRows(
+            [
+                { label: 'mode', value: result.mode },
+                ...(result.monorepoRoot ? [{ label: 'monorepo root', value: result.monorepoRoot }] : []),
+            ],
+            { minLabelWidth: 16, maxLabelWidth: 16 },
+        ),
+    );
+
+    if (result.created.length > 0) sections.push(['Created:', ...result.created.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.updated.length > 0) sections.push(['Updated:', ...result.updated.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.overwritten.length > 0)
+        sections.push(['Overwritten:', ...result.overwritten.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.updatedGitignores.length > 0)
+        sections.push(['Updated .gitignore:', ...result.updatedGitignores.map((entry) => `- ${entry}`)].join('\n'));
+    if (result.blocked.length > 0)
+        sections.push(
+            [
+                'Skipped existing non-managed paths:',
+                ...result.blocked.map((entry) => `- ${entry}`),
+            ].join('\n'),
+        );
+
+    return sections;
+};
+
 /*----------------------------------
 - COMMAND
 ----------------------------------*/
@@ -136,6 +195,14 @@ export const run = async (): Promise<void> => {
           })
         : undefined;
 
+    const preview = configureProjectAgentSymlinks({
+        appRoot,
+        coreRoot: cli.paths.core.root,
+        dryRun: true,
+        monorepoRoot,
+    });
+    const overwriteBlockedPaths = await promptBlockedOverwritePaths(preview.blocked);
+
     console.info(
         await renderStep(
             '[1/1]',
@@ -149,30 +216,9 @@ export const run = async (): Promise<void> => {
         appRoot,
         coreRoot: cli.paths.core.root,
         monorepoRoot,
+        overwriteBlockedPaths,
     });
-    const sections: string[] = [];
-
-    sections.push(
-        renderRows(
-            [
-                { label: 'mode', value: result.mode },
-                ...(result.monorepoRoot ? [{ label: 'monorepo root', value: result.monorepoRoot }] : []),
-            ],
-            { minLabelWidth: 16, maxLabelWidth: 16 },
-        ),
-    );
-
-    if (result.created.length > 0) sections.push(['Created:', ...result.created.map((entry) => `- ${entry}`)].join('\n'));
-    if (result.updated.length > 0) sections.push(['Updated:', ...result.updated.map((entry) => `- ${entry}`)].join('\n'));
-    if (result.updatedGitignores.length > 0)
-        sections.push(['Updated .gitignore:', ...result.updatedGitignores.map((entry) => `- ${entry}`)].join('\n'));
-    if (result.blocked.length > 0)
-        sections.push(
-            [
-                'Skipped existing non-managed paths:',
-                ...result.blocked.map((entry) => `- ${entry}`),
-            ].join('\n'),
-        );
+    const sections = renderConfigureResultSections(result);
 
     console.info(await renderSuccess('Proteum-managed instruction symlinks are configured.'));
 

package/cli/presentation/commands.ts

@@ -125,7 +125,8 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             '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` symlink.',
             '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.',
-            'Existing non-managed files are never overwritten; Proteum only creates missing symlinks or updates symlinks it already manages.',
+            '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 symlink.',
+            'Declined non-managed paths are left untouched; Proteum still creates missing symlinks and updates symlinks it already manages.',
         ],
         status: 'experimental',
     },

package/cli/utils/agents.ts

@@ -12,13 +12,20 @@ import { logVerbose } from '../runtime/verbose';
 ----------------------------------*/
 
 type TProjectInstructionArgs = { coreRoot: string };
-type TConfigureProjectAgentSymlinksArgs = { appRoot: string; coreRoot: string; monorepoRoot?: string };
+type TConfigureProjectAgentSymlinksArgs = {
+    appRoot: string;
+    coreRoot: string;
+    dryRun?: boolean;
+    monorepoRoot?: string;
+    overwriteBlockedPaths?: string[];
+};
 
 type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensureParentDir?: boolean };
 
 type TEnsureSymlinksResult = {
     blocked: string[];
     created: string[];
+    overwritten: string[];
     skipped: string[];
     updated: string[];
 };
@@ -29,6 +36,7 @@ export type TConfigureProjectAgentSymlinksResult = {
     created: string[];
     monorepoRoot?: string;
     mode: 'monorepo' | 'standalone';
+    overwritten: string[];
     skipped: string[];
     updated: string[];
     updatedGitignores: string[];
@@ -76,10 +84,15 @@ const projectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction s
 export function configureProjectAgentSymlinks({
     appRoot,
     coreRoot,
+    dryRun = false,
     monorepoRoot,
+    overwriteBlockedPaths = [],
 }: TConfigureProjectAgentSymlinksArgs): TConfigureProjectAgentSymlinksResult {
     const normalizedAppRoot = path.resolve(appRoot);
     const normalizedMonorepoRoot = monorepoRoot ? path.resolve(monorepoRoot) : undefined;
+    const normalizedOverwriteBlockedPaths = new Set(
+        overwriteBlockedPaths.map((blockedPath) => normalizeAbsolutePath(path.resolve(blockedPath))),
+    );
     const mode =
         normalizedMonorepoRoot && normalizedMonorepoRoot !== normalizedAppRoot ? ('monorepo' as const) : ('standalone' as const);
     const result: TConfigureProjectAgentSymlinksResult = {
@@ -87,6 +100,7 @@ export function configureProjectAgentSymlinks({
         blocked: [],
         created: [],
         mode,
+        overwritten: [],
         skipped: [],
         updated: [],
         updatedGitignores: [],
@@ -96,18 +110,24 @@ export function configureProjectAgentSymlinks({
         result.monorepoRoot = normalizedMonorepoRoot;
 
         const rootLinks = getRootAgentLinkDefinitions({ coreRoot });
-        const rootSymlinks = ensureSymlinks(normalizedMonorepoRoot, rootLinks, '[agents]', path.join(coreRoot, 'agents', 'project'));
+        const rootSymlinks = ensureSymlinks(normalizedMonorepoRoot, rootLinks, '[agents]', path.join(coreRoot, 'agents', 'project'), {
+            dryRun,
+            overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
+        });
         mergeSymlinkResults(result, rootSymlinks, normalizedMonorepoRoot);
 
-        if (ensureInstructionGitignoreEntries({ rootDir: normalizedMonorepoRoot, linkDefinitions: rootLinks }))
+        if (!dryRun && ensureInstructionGitignoreEntries({ rootDir: normalizedMonorepoRoot, linkDefinitions: rootLinks }))
             result.updatedGitignores.push(path.join(normalizedMonorepoRoot, '.gitignore'));
     }
 
     const appLinks = getAppAgentLinkDefinitions({ coreRoot, mode });
-    const appSymlinks = ensureSymlinks(normalizedAppRoot, appLinks, '[agents]', path.join(coreRoot, 'agents', 'project'));
+    const appSymlinks = ensureSymlinks(normalizedAppRoot, appLinks, '[agents]', path.join(coreRoot, 'agents', 'project'), {
+        dryRun,
+        overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
+    });
     mergeSymlinkResults(result, appSymlinks, normalizedAppRoot);
 
-    if (ensureInstructionGitignoreEntries({ rootDir: normalizedAppRoot, linkDefinitions: appLinks }))
+    if (!dryRun && ensureInstructionGitignoreEntries({ rootDir: normalizedAppRoot, linkDefinitions: appLinks }))
         result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
 
     return result;
@@ -223,10 +243,18 @@ function ensureSymlinks(
     linkDefinitions: TAgentLinkDefinition[],
     logPrefix: string,
     managedSourceRoot: string,
+    {
+        dryRun,
+        overwriteBlockedPaths,
+    }: {
+        dryRun: boolean;
+        overwriteBlockedPaths: Set<string>;
+    },
 ): TEnsureSymlinksResult {
     const result: TEnsureSymlinksResult = {
         blocked: [],
         created: [],
+        overwritten: [],
         skipped: [],
         updated: [],
     };
@@ -256,7 +284,8 @@ function ensureSymlinks(
             continue;
         }
 
-        if (existingState.kind === 'blocked') {
+        const normalizedProjectFilepath = normalizeAbsolutePath(projectFilepath);
+        if (existingState.kind === 'blocked' && !overwriteBlockedPaths.has(normalizedProjectFilepath)) {
             result.blocked.push(relativeProjectPath);
             continue;
         }
@@ -264,14 +293,26 @@ function ensureSymlinks(
         const symlinkTarget = path.relative(projectParentDir, sourceFilepath);
 
         if (existingState.kind === 'managed-different') {
-            fs.unlinkSync(projectFilepath);
-            fs.symlinkSync(symlinkTarget, projectFilepath);
+            if (!dryRun) {
+                fs.unlinkSync(projectFilepath);
+                fs.symlinkSync(symlinkTarget, projectFilepath);
+            }
             result.updated.push(relativeProjectPath);
             logVerbose(`${logPrefix} Updated ${relativeProjectPath} -> ${symlinkTarget}`);
             continue;
         }
 
-        fs.symlinkSync(symlinkTarget, projectFilepath);
+        if (existingState.kind === 'blocked') {
+            if (!dryRun) {
+                fs.removeSync(projectFilepath);
+                fs.symlinkSync(symlinkTarget, projectFilepath);
+            }
+            result.overwritten.push(relativeProjectPath);
+            logVerbose(`${logPrefix} Replaced ${relativeProjectPath} -> ${symlinkTarget}`);
+            continue;
+        }
+
+        if (!dryRun) fs.symlinkSync(symlinkTarget, projectFilepath);
         result.created.push(relativeProjectPath);
         logVerbose(`${logPrefix} Created ${relativeProjectPath} -> ${symlinkTarget}`);
     }
@@ -320,6 +361,7 @@ function mergeSymlinkResults(
     rootDir: string,
 ) {
     result.created.push(...next.created.map((entry) => formatResultPath(rootDir, entry)));
+    result.overwritten.push(...next.overwritten.map((entry) => formatResultPath(rootDir, entry)));
     result.updated.push(...next.updated.map((entry) => formatResultPath(rootDir, entry)));
     result.skipped.push(...next.skipped.map((entry) => formatResultPath(rootDir, entry)));
     result.blocked.push(...next.blocked.map((entry) => formatResultPath(rootDir, entry)));

package/package.json

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