proteum 2.2.2 → 2.2.6

package/cli/utils/agents.ts

@@ -12,7 +12,7 @@ import { logVerbose } from '../runtime/verbose';
 ----------------------------------*/
 
 type TProjectInstructionArgs = { coreRoot: string };
-type TConfigureProjectAgentSymlinksArgs = {
+type TConfigureProjectAgentInstructionsArgs = {
     appRoot: string;
     coreRoot: string;
     dryRun?: boolean;
@@ -20,9 +20,14 @@ type TConfigureProjectAgentSymlinksArgs = {
     overwriteBlockedPaths?: string[];
 };
 
-type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensureParentDir?: boolean };
+type TAgentInstructionDefinition = {
+    includeWorktreeBootstrap?: boolean;
+    projectPath: string;
+    sourcePath: string;
+    ensureParentDir?: boolean;
+};
 
-type TEnsureSymlinksResult = {
+type TEnsureInstructionStubsResult = {
     blocked: string[];
     created: string[];
     overwritten: string[];
@@ -30,7 +35,7 @@ type TEnsureSymlinksResult = {
     updated: string[];
 };
 
-export type TConfigureProjectAgentSymlinksResult = {
+export type TConfigureProjectAgentInstructionsResult = {
     appRoot: string;
     blocked: string[];
     created: string[];
@@ -51,7 +56,24 @@ export type TProjectAgentFileInspection = {
 - CONSTANTS
 ----------------------------------*/
 
-const sharedAppAgentLinkDefinitions: TAgentLinkDefinition[] = [
+const managedInstructionStubHeader = '# Proteum Managed Instructions';
+const managedInstructionStubIntro = 'This file is managed by `proteum configure agents`.';
+const newProteumWorktreeBootstrapBlock = [
+    '## New Proteum Worktree Bootstrap',
+    '',
+    'When starting work in a newly created Proteum worktree, immediately copy the `.env` file from the main worktree, change it to use a different free port by updating `PORT`, `URL`, and `URL_INTERNAL`, and run:',
+    '',
+    '```',
+    'npx proteum configure agents',
+    'npm i',
+    'npx prisma generate',
+    'npx proteum refresh',
+    '```',
+    '',
+    'Run it before reading project-specific AGENTS files or making code changes. If the command is interactive, answer according to the current repository layout, then continue by reading the generated AGENTS.md files.',
+];
+
+const sharedAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'CODING_STYLE.md', sourcePath: 'CODING_STYLE.md' },
     { projectPath: 'diagnostics.md', sourcePath: 'diagnostics.md' },
     { projectPath: 'optimizations.md', sourcePath: 'optimizations.md' },
@@ -65,34 +87,36 @@ const sharedAppAgentLinkDefinitions: TAgentLinkDefinition[] = [
     { projectPath: path.join('tests', 'e2e', 'AGENTS.md'), sourcePath: path.join('tests', 'AGENTS.md') },
 ];
 
-const standaloneAppAgentLinkDefinitions: TAgentLinkDefinition[] = [
-    { projectPath: 'AGENTS.md', sourcePath: 'AGENTS.md' },
-    ...sharedAppAgentLinkDefinitions,
+const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: 'AGENTS.md', sourcePath: 'AGENTS.md', includeWorktreeBootstrap: true },
+    ...sharedAppAgentInstructionDefinitions,
 ];
 
-const monorepoAppAgentLinkDefinitions: TAgentLinkDefinition[] = [
+const monorepoAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md', sourcePath: path.join('app-root', 'AGENTS.md') },
-    ...sharedAppAgentLinkDefinitions,
+    ...sharedAppAgentInstructionDefinitions,
 ];
 
-const monorepoRootAgentLinkDefinitions: TAgentLinkDefinition[] = [
-    { projectPath: 'AGENTS.md', sourcePath: path.join('root', 'AGENTS.md') },
+const monorepoRootAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: 'AGENTS.md', sourcePath: path.join('root', 'AGENTS.md'), includeWorktreeBootstrap: true },
 ];
 
-const projectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
-const projectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction symlinks';
+const legacyProjectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
+const legacyProjectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction symlinks';
+const projectInstructionGitignoreBlockStart = '# Proteum-managed instruction files';
+const projectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction files';
 
 /*----------------------------------
 - PUBLIC API
 ----------------------------------*/
 
-export function configureProjectAgentSymlinks({
+export function configureProjectAgentInstructions({
     appRoot,
     coreRoot,
     dryRun = false,
     monorepoRoot,
     overwriteBlockedPaths = [],
-}: TConfigureProjectAgentSymlinksArgs): TConfigureProjectAgentSymlinksResult {
+}: TConfigureProjectAgentInstructionsArgs): TConfigureProjectAgentInstructionsResult {
     const normalizedAppRoot = path.resolve(appRoot);
     const normalizedMonorepoRoot = monorepoRoot ? path.resolve(monorepoRoot) : undefined;
     const normalizedOverwriteBlockedPaths = new Set(
@@ -100,7 +124,7 @@ export function configureProjectAgentSymlinks({
     );
     const mode =
         normalizedMonorepoRoot && normalizedMonorepoRoot !== normalizedAppRoot ? ('monorepo' as const) : ('standalone' as const);
-    const result: TConfigureProjectAgentSymlinksResult = {
+    const result: TConfigureProjectAgentInstructionsResult = {
         appRoot: normalizedAppRoot,
         blocked: [],
         created: [],
@@ -114,50 +138,66 @@ export function configureProjectAgentSymlinks({
     if (mode === 'monorepo' && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
 
-        const rootLinks = getRootAgentLinkDefinitions({ coreRoot });
-        const rootSymlinks = ensureSymlinks(normalizedMonorepoRoot, rootLinks, '[agents]', path.join(coreRoot, 'agents', 'project'), {
-            dryRun,
-            overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
-        });
-        mergeSymlinkResults(result, rootSymlinks, normalizedMonorepoRoot);
-
-        if (!dryRun && ensureInstructionGitignoreEntries({ rootDir: normalizedMonorepoRoot, linkDefinitions: rootLinks }))
+        const rootInstructions = getRootAgentInstructionDefinitions({ coreRoot });
+        const rootStubs = ensureInstructionStubs(
+            normalizedMonorepoRoot,
+            rootInstructions,
+            '[agents]',
+            path.join(coreRoot, 'agents', 'project'),
+            {
+                dryRun,
+                overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
+            },
+        );
+        mergeInstructionResults(result, rootStubs, normalizedMonorepoRoot);
+
+        if (!dryRun && ensureInstructionGitignoreEntries({ rootDir: normalizedMonorepoRoot, instructionDefinitions: rootInstructions }))
             result.updatedGitignores.push(path.join(normalizedMonorepoRoot, '.gitignore'));
     }
 
-    const appLinks = getAppAgentLinkDefinitions({ coreRoot, mode });
-    const appSymlinks = ensureSymlinks(normalizedAppRoot, appLinks, '[agents]', path.join(coreRoot, 'agents', 'project'), {
-        dryRun,
-        overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
-    });
-    mergeSymlinkResults(result, appSymlinks, normalizedAppRoot);
+    const appInstructions = getAppAgentInstructionDefinitions({ coreRoot, mode });
+    const appStubs = ensureInstructionStubs(
+        normalizedAppRoot,
+        appInstructions,
+        '[agents]',
+        path.join(coreRoot, 'agents', 'project'),
+        {
+            dryRun,
+            overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
+        },
+    );
+    mergeInstructionResults(result, appStubs, normalizedAppRoot);
 
-    if (!dryRun && ensureInstructionGitignoreEntries({ rootDir: normalizedAppRoot, linkDefinitions: appLinks }))
+    if (!dryRun && ensureInstructionGitignoreEntries({ rootDir: normalizedAppRoot, instructionDefinitions: appInstructions }))
         result.updatedGitignores.push(path.join(normalizedAppRoot, '.gitignore'));
 
     return result;
 }
 
+export const configureProjectAgentSymlinks = configureProjectAgentInstructions;
+
 export function getProjectInstructionGitignoreEntries({ coreRoot }: TProjectInstructionArgs) {
     return Array.from(
         new Set(
-            getAppAgentLinkDefinitions({ coreRoot, mode: 'standalone' }).map((linkDefinition) =>
-                `/${normalizeProjectPathForGitignore(linkDefinition.projectPath)}`,
+            getAppAgentInstructionDefinitions({ coreRoot, mode: 'standalone' }).map((instructionDefinition) =>
+                `/${normalizeProjectPathForGitignore(instructionDefinition.projectPath)}`,
             ),
         ),
     );
 }
 
 export function renderProjectInstructionGitignoreBlock({ coreRoot }: TProjectInstructionArgs) {
-    return renderInstructionGitignoreBlock({ linkDefinitions: getAppAgentLinkDefinitions({ coreRoot, mode: 'standalone' }) });
+    return renderInstructionGitignoreBlock({
+        instructionDefinitions: getAppAgentInstructionDefinitions({ coreRoot, mode: 'standalone' }),
+    });
 }
 
 export function inspectProjectAgentFiles({ appRoot }: { appRoot: string }): TProjectAgentFileInspection {
     const normalizedAppRoot = path.resolve(appRoot);
     const expectedAgentPaths = Array.from(
         new Set(
-            standaloneAppAgentLinkDefinitions
-                .map((linkDefinition) => linkDefinition.projectPath)
+            standaloneAppAgentInstructionDefinitions
+                .map((instructionDefinition) => instructionDefinition.projectPath)
                 .filter((projectPath) => projectPath.endsWith('AGENTS.md')),
         ),
     );
@@ -187,42 +227,47 @@ export function inspectProjectAgentFiles({ appRoot }: { appRoot: string }): TPro
 - HELPERS
 ----------------------------------*/
 
-function getAppAgentLinkDefinitions({
+function getAppAgentInstructionDefinitions({
     coreRoot,
     mode,
 }: TProjectInstructionArgs & { mode: 'monorepo' | 'standalone' }) {
     const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
-    const sourceDefinitions = mode === 'monorepo' ? monorepoAppAgentLinkDefinitions : standaloneAppAgentLinkDefinitions;
+    const sourceDefinitions =
+        mode === 'monorepo' ? monorepoAppAgentInstructionDefinitions : standaloneAppAgentInstructionDefinitions;
 
-    return resolveAgentLinkDefinitions({
+    return resolveAgentInstructionDefinitions({
         agentSourceRoot,
-        linkDefinitions: sourceDefinitions,
+        instructionDefinitions: sourceDefinitions,
     });
 }
 
-function getRootAgentLinkDefinitions({ coreRoot }: TProjectInstructionArgs) {
-    return resolveAgentLinkDefinitions({
+function getRootAgentInstructionDefinitions({ coreRoot }: TProjectInstructionArgs) {
+    return resolveAgentInstructionDefinitions({
         agentSourceRoot: path.join(coreRoot, 'agents', 'project'),
-        linkDefinitions: monorepoRootAgentLinkDefinitions,
+        instructionDefinitions: monorepoRootAgentInstructionDefinitions,
     });
 }
 
-function resolveAgentLinkDefinitions({
+function resolveAgentInstructionDefinitions({
     agentSourceRoot,
-    linkDefinitions,
+    instructionDefinitions,
 }: {
     agentSourceRoot: string;
-    linkDefinitions: TAgentLinkDefinition[];
+    instructionDefinitions: TAgentInstructionDefinition[];
 }) {
-    return linkDefinitions.map((linkDefinition) => ({
-        ...linkDefinition,
-        sourcePath: path.join(agentSourceRoot, linkDefinition.sourcePath),
+    return instructionDefinitions.map((instructionDefinition) => ({
+        ...instructionDefinition,
+        sourcePath: path.join(agentSourceRoot, instructionDefinition.sourcePath),
     }));
 }
 
-function renderInstructionGitignoreBlock({ linkDefinitions }: { linkDefinitions: TAgentLinkDefinition[] }) {
+function renderInstructionGitignoreBlock({ instructionDefinitions }: { instructionDefinitions: TAgentInstructionDefinition[] }) {
     const entries = Array.from(
-        new Set(linkDefinitions.map((linkDefinition) => `/${normalizeProjectPathForGitignore(linkDefinition.projectPath)}`)),
+        new Set(
+            instructionDefinitions.map(
+                (instructionDefinition) => `/${normalizeProjectPathForGitignore(instructionDefinition.projectPath)}`,
+            ),
+        ),
     );
 
     return [projectInstructionGitignoreBlockStart, ...entries, projectInstructionGitignoreBlockEnd].join('\n');
@@ -230,15 +275,17 @@ function renderInstructionGitignoreBlock({ linkDefinitions }: { linkDefinitions:
 
 function ensureInstructionGitignoreEntries({
     rootDir,
-    linkDefinitions,
+    instructionDefinitions,
 }: {
     rootDir: string;
-    linkDefinitions: TAgentLinkDefinition[];
+    instructionDefinitions: TAgentInstructionDefinition[];
 }) {
     const gitignoreFilepath = path.join(rootDir, '.gitignore');
     if (!pathEntryExists(gitignoreFilepath)) return false;
 
-    const managedEntries = new Set(linkDefinitions.map((linkDefinition) => normalizeGitignoreEntry(linkDefinition.projectPath)));
+    const managedEntries = new Set(
+        instructionDefinitions.map((instructionDefinition) => normalizeGitignoreEntry(instructionDefinition.projectPath)),
+    );
     const lines = fs.readFileSync(gitignoreFilepath, 'utf8').split(/\r?\n/);
     const filteredLines: string[] = [];
     let insideManagedBlock = false;
@@ -246,12 +293,12 @@ function ensureInstructionGitignoreEntries({
     for (const line of lines) {
         const trimmedLine = line.trim();
 
-        if (trimmedLine === projectInstructionGitignoreBlockStart) {
+        if (trimmedLine === projectInstructionGitignoreBlockStart || trimmedLine === legacyProjectInstructionGitignoreBlockStart) {
             insideManagedBlock = true;
             continue;
         }
 
-        if (trimmedLine === projectInstructionGitignoreBlockEnd) {
+        if (trimmedLine === projectInstructionGitignoreBlockEnd || trimmedLine === legacyProjectInstructionGitignoreBlockEnd) {
             insideManagedBlock = false;
             continue;
         }
@@ -263,7 +310,7 @@ function ensureInstructionGitignoreEntries({
     }
 
     const baseContent = trimTrailingBlankLines(filteredLines).join('\n');
-    const managedBlock = renderInstructionGitignoreBlock({ linkDefinitions });
+    const managedBlock = renderInstructionGitignoreBlock({ instructionDefinitions });
     const nextContent = baseContent ? `${baseContent}\n\n${managedBlock}\n` : `${managedBlock}\n`;
 
     if (nextContent === fs.readFileSync(gitignoreFilepath, 'utf8')) return false;
@@ -274,9 +321,9 @@ function ensureInstructionGitignoreEntries({
     return true;
 }
 
-function ensureSymlinks(
+function ensureInstructionStubs(
     rootDir: string,
-    linkDefinitions: TAgentLinkDefinition[],
+    instructionDefinitions: TAgentInstructionDefinition[],
     logPrefix: string,
     managedSourceRoot: string,
     {
@@ -286,8 +333,8 @@ function ensureSymlinks(
         dryRun: boolean;
         overwriteBlockedPaths: Set<string>;
     },
-): TEnsureSymlinksResult {
-    const result: TEnsureSymlinksResult = {
+): TEnsureInstructionStubsResult {
+    const result: TEnsureInstructionStubsResult = {
         blocked: [],
         created: [],
         overwritten: [],
@@ -295,24 +342,31 @@ function ensureSymlinks(
         updated: [],
     };
 
-    for (const linkDefinition of linkDefinitions) {
-        const projectFilepath = path.join(rootDir, linkDefinition.projectPath);
+    for (const instructionDefinition of instructionDefinitions) {
+        const projectFilepath = path.join(rootDir, instructionDefinition.projectPath);
         const projectParentDir = path.dirname(projectFilepath);
         const relativeProjectPath = path.relative(rootDir, projectFilepath) || '.';
 
-        if (linkDefinition.ensureParentDir) fs.ensureDirSync(projectParentDir);
+        if (instructionDefinition.ensureParentDir) fs.ensureDirSync(projectParentDir);
         else if (!fs.existsSync(projectParentDir)) {
             result.skipped.push(relativeProjectPath);
             continue;
         }
 
-        const sourceFilepath = linkDefinition.sourcePath;
+        const sourceFilepath = instructionDefinition.sourcePath;
         if (!fs.existsSync(sourceFilepath)) throw new Error(`Missing project instruction asset: ${sourceFilepath}`);
 
+        const stubContent = renderInstructionStub({
+            includeWorktreeBootstrap: instructionDefinition.includeWorktreeBootstrap === true,
+            projectFilepath,
+            sourceFilepath,
+        });
+
         const existingState = inspectExistingPath({
             managedSourceRoot,
             projectFilepath,
             sourceFilepath,
+            stubContent,
         });
 
         if (existingState.kind === 'match') {
@@ -326,57 +380,94 @@ function ensureSymlinks(
             continue;
         }
 
-        const symlinkTarget = path.relative(projectParentDir, sourceFilepath);
-
         if (existingState.kind === 'managed-different') {
             if (!dryRun) {
-                fs.unlinkSync(projectFilepath);
-                fs.symlinkSync(symlinkTarget, projectFilepath);
+                fs.removeSync(projectFilepath);
+                fs.writeFileSync(projectFilepath, stubContent);
             }
             result.updated.push(relativeProjectPath);
-            logVerbose(`${logPrefix} Updated ${relativeProjectPath} -> ${symlinkTarget}`);
+            logVerbose(`${logPrefix} Updated ${relativeProjectPath}`);
             continue;
         }
 
         if (existingState.kind === 'blocked') {
             if (!dryRun) {
                 fs.removeSync(projectFilepath);
-                fs.symlinkSync(symlinkTarget, projectFilepath);
+                fs.writeFileSync(projectFilepath, stubContent);
             }
             result.overwritten.push(relativeProjectPath);
-            logVerbose(`${logPrefix} Replaced ${relativeProjectPath} -> ${symlinkTarget}`);
+            logVerbose(`${logPrefix} Replaced ${relativeProjectPath}`);
             continue;
         }
 
-        if (!dryRun) fs.symlinkSync(symlinkTarget, projectFilepath);
+        if (!dryRun) fs.writeFileSync(projectFilepath, stubContent);
         result.created.push(relativeProjectPath);
-        logVerbose(`${logPrefix} Created ${relativeProjectPath} -> ${symlinkTarget}`);
+        logVerbose(`${logPrefix} Created ${relativeProjectPath}`);
     }
 
     return result;
 }
 
+function renderInstructionStub({
+    includeWorktreeBootstrap,
+    projectFilepath,
+    sourceFilepath,
+}: {
+    includeWorktreeBootstrap: boolean;
+    projectFilepath: string;
+    sourceFilepath: string;
+}) {
+    const sourcePath = normalizeProjectPathForGitignore(path.relative(path.dirname(projectFilepath), sourceFilepath));
+    const lines = [
+        ...(includeWorktreeBootstrap ? [...newProteumWorktreeBootstrapBlock, ''] : []),
+        managedInstructionStubHeader,
+        '',
+        managedInstructionStubIntro,
+        '',
+        'Before reading or applying instructions from this file, read and follow the canonical Proteum instruction file at:',
+        '',
+        `\`${sourcePath}\``,
+        '',
+        'Resolve that path relative to this file. Treat the canonical file as if its full contents were written here.',
+        '',
+        'If the canonical file cannot be read, stop and run `npx proteum configure agents` before continuing.',
+        '',
+    ];
+
+    return lines.join('\n');
+}
+
 function inspectExistingPath({
     managedSourceRoot,
     projectFilepath,
     sourceFilepath,
+    stubContent,
 }: {
     managedSourceRoot: string;
     projectFilepath: string;
     sourceFilepath: string;
+    stubContent: string;
 }) {
     if (!pathEntryExists(projectFilepath)) return { kind: 'missing' as const };
 
     const stats = fs.lstatSync(projectFilepath);
-    if (!stats.isSymbolicLink()) return { kind: 'blocked' as const };
+    if (!stats.isSymbolicLink()) {
+        if (!stats.isFile()) return { kind: 'blocked' as const };
+
+        const existingContent = fs.readFileSync(projectFilepath, 'utf8');
+        if (existingContent === stubContent) return { kind: 'match' as const };
+        if (isManagedInstructionStub(existingContent)) return { kind: 'managed-different' as const };
+
+        return { kind: 'blocked' as const };
+    }
 
     const existingTarget = resolveSymlinkTarget(projectFilepath);
     const normalizedExistingTarget = normalizeAbsolutePath(existingTarget);
     const normalizedSourceFilepath = normalizeAbsolutePath(sourceFilepath);
     const normalizedManagedSourceRoot = normalizeAbsolutePath(managedSourceRoot);
 
-    if (normalizedExistingTarget === normalizedSourceFilepath) return { kind: 'match' as const };
     if (
+        normalizedExistingTarget === normalizedSourceFilepath ||
         normalizedExistingTarget === normalizedManagedSourceRoot ||
         normalizedExistingTarget.startsWith(`${normalizedManagedSourceRoot}/`)
     )
@@ -385,15 +476,19 @@ function inspectExistingPath({
     return { kind: 'blocked' as const };
 }
 
+function isManagedInstructionStub(content: string) {
+    return content.includes(`${managedInstructionStubHeader}\n\n${managedInstructionStubIntro}\n`);
+}
+
 function resolveSymlinkTarget(projectFilepath: string) {
     const projectParentDir = path.dirname(projectFilepath);
     const rawTarget = fs.readlinkSync(projectFilepath);
     return path.resolve(projectParentDir, rawTarget);
 }
 
-function mergeSymlinkResults(
-    result: TConfigureProjectAgentSymlinksResult,
-    next: TEnsureSymlinksResult,
+function mergeInstructionResults(
+    result: TConfigureProjectAgentInstructionsResult,
+    next: TEnsureInstructionStubsResult,
     rootDir: string,
 ) {
     result.created.push(...next.created.map((entry) => formatResultPath(rootDir, entry)));

package/cli/utils/check.ts

@@ -2,10 +2,11 @@ import fs from 'fs';
 import path from 'path';
 
 import cli from '..';
-import Compiler from '../compiler';
 import { runProcess } from './runProcess';
 
-const tsconfigPaths = ['client/tsconfig.json', 'server/tsconfig.json', 'commands/tsconfig.json'];
+const appConfigPaths = ['identity.config.ts', 'proteum.config.ts'];
+const appTsconfigPaths = ['client/tsconfig.json', 'server/tsconfig.json', 'commands/tsconfig.json'];
+const frameworkTsconfigPaths = ['client/app.tsconfig.json', 'server/app.tsconfig.json', 'cli/tsconfig.json'];
 const eslintConfigPaths = ['eslint.config.mjs', 'eslint.config.js', 'eslint.config.cjs'];
 
 const resolveInstalledBinary = (packageName: string, binName: string) => cli.paths.resolveBinary(packageName, binName);
@@ -15,6 +16,28 @@ const resolveExistingAppPaths = (paths: string[]) =>
         .map((relativePath) => ({ relativePath, absolutePath: path.join(cli.paths.appRoot, relativePath) }))
         .filter(({ absolutePath }) => fs.existsSync(absolutePath));
 
+const isFrameworkCheckout = () => {
+    let packageJson: { name?: unknown } | undefined;
+
+    try {
+        packageJson = JSON.parse(fs.readFileSync(path.join(cli.paths.appRoot, 'package.json'), 'utf8'));
+    } catch {}
+
+    return packageJson?.name === 'proteum' && fs.existsSync(path.join(cli.paths.appRoot, 'cli', 'bin.js'));
+};
+
+const resolveTypecheckProjects = () => {
+    const appProjects = resolveExistingAppPaths(appTsconfigPaths);
+    if (appProjects.length > 0) return appProjects;
+
+    if (isFrameworkCheckout()) return resolveExistingAppPaths(frameworkTsconfigPaths);
+
+    return [];
+};
+
+export const hasAppConfig = () =>
+    appConfigPaths.every((relativePath) => fs.existsSync(path.join(cli.paths.appRoot, relativePath)));
+
 const getTypecheckEnv = () => {
     const existingNodeOptions = process.env.NODE_OPTIONS ?? '';
 
@@ -26,16 +49,21 @@ const getTypecheckEnv = () => {
 };
 
 export const refreshGeneratedTypings = async () => {
+    const { default: Compiler } = await import('../compiler');
     const compiler = new Compiler('dev');
 
     await compiler.refreshGeneratedTypings();
 };
 
 export const runAppTypecheck = async () => {
-    const existingProjects = resolveExistingAppPaths(tsconfigPaths);
+    const existingProjects = resolveTypecheckProjects();
 
     if (existingProjects.length === 0)
-        throw new Error(`No TypeScript app projects found. Expected one of: ${tsconfigPaths.join(', ')}.`);
+        throw new Error(
+            `No TypeScript projects found. Expected one of: ${[...appTsconfigPaths, ...frameworkTsconfigPaths].join(
+                ', ',
+            )}.`,
+        );
 
     const tsc = resolveInstalledBinary('typescript', 'tsc');
 

package/docs/dev-sessions.md

@@ -1,6 +1,6 @@
 # Dev Sessions
 
-Proteum ships a dev-only auth bootstrap command so `proteum verify browser`, Playwright runs, and local debugging can start from an authenticated state without driving the login UI.
+Proteum ships dev-only auth bootstrap commands so `proteum verify browser`, `proteum e2e`, Playwright runs, and local debugging can start from an authenticated state without driving the login UI.
 
 ## When To Use It
 
@@ -31,10 +31,18 @@ proteum session admin@example.com --role ADMIN --port 3101
 proteum session god@example.com --role GOD --url http://localhost:3102 --json
 ```
 
+Playwright wrapper mode:
+
+```bash
+proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/admin.spec.ts
+proteum e2e --url http://localhost:3101 --env FEATURE_FLAG=true --grep smoke
+```
+
 Behavior:
 
 - local mode refreshes generated artifacts, builds the dev output, starts a temporary local dev server, creates the session, prints the payload, and exits
 - remote mode talks to an already running `proteum dev` instance
+- `proteum e2e` talks to an already running `proteum dev` instance when `--session-email` is present, then starts Playwright with `E2E_BASE_URL`, optional `E2E_PORT`, optional `E2E_AUTH_TOKEN`, and any explicit `--env` or `--env-file` values in the child process environment
 - the command requires an explicit email and optionally asserts a role before returning the session
 - the command is available only in dev mode
 - browser verification flows should keep browser state app-local and disposable through `proteum verify browser` or direct Playwright instead of reusing a shared temp profile
@@ -68,7 +76,7 @@ curl -H "$(jq -r '.curlCookieHeader' session.json)" http://localhost:3101/api/Au
 ## Agent Guidance
 
 - Prefer `proteum session` over UI login automation when the goal is to test or debug protected application behavior.
-- Prefer `proteum verify browser` for focused browser-visible verification. When lower-level control is required, use direct Playwright with a disposable profile.
+- Prefer `proteum verify browser` for focused browser-visible verification, and `proteum e2e --port <port>` for targeted or full Playwright suites. When lower-level control is required, use direct Playwright with a disposable profile.
 - Use UI login automation only when the auth UX itself is the feature under test.
 - Pair it with `proteum diagnose` for a fast protected-route summary, `proteum perf request` for a one-request timing breakdown, then use `proteum trace` when you need lower-level request events.
 - Only the final verifier agent should usually run browser flows. Earlier agents should stay on `orient`, `verify owner`, `verify request`, and request-level diagnostics unless browser execution is required.
@@ -78,6 +86,7 @@ Typical flow:
 ```bash
 proteum orient /dashboard
 proteum session admin@example.com --role ADMIN --port 3101 --json > session.json
+proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/dashboard.spec.ts
 proteum diagnose /dashboard --hit /dashboard --port 3101
 proteum perf request /dashboard --port 3101
 proteum trace latest --port 3101

package/docs/diagnostics.md

@@ -53,6 +53,7 @@ proteum diagnose /api/Auth/CurrentUser --url http://127.0.0.1:3101
 proteum verify owner /api/Auth/CurrentUser
 proteum verify request /dashboard --port 3101
 proteum verify browser /dashboard --port 3101 --session-email admin@example.com --session-role ADMIN
+proteum e2e --port 3101 --session-email admin@example.com --session-role ADMIN tests/e2e/features/dashboard.spec.ts
 
 proteum perf top --since today
 proteum perf request /dashboard --port 3101
@@ -210,7 +211,7 @@ For AI coding agents or automation:
 2. Read `./.proteum/manifest.json` or run `proteum explain --json` only after you know which surface matters.
 3. Run `proteum doctor --json` and `proteum doctor --contracts --json` to inspect framework and generated-artifact diagnostics.
 4. Use `proteum verify owner <query>` or `proteum diagnose <path> --port <port>` for the smallest trustworthy runtime surface before broad checks.
-5. Use `proteum verify browser` for browser-visible verification, and only drop to direct Playwright when request-level verification cannot reproduce the issue. Keep auth sourced from `proteum session`, and reserve browser flows for the final verifier agent unless they are the only trustworthy surface.
+5. Use `proteum verify browser` for browser-visible verification, or `proteum e2e --port <port>` for targeted/full Playwright suites. Only drop to direct Playwright when the Proteum wrapper cannot express the needed control. Keep auth sourced from Proteum session helpers, and reserve browser flows for the final verifier agent unless they are the only trustworthy surface.
 6. For performance, CPU, SQL, render, cache, or connected-boundary questions, use `proteum perf request <requestId|path>` against the same running dev server.
 7. Use `proteum trace ...` when you need lower-level event detail than `diagnose` or `perf` provides.
 8. Run global checks second, not first. Unrelated diagnostics should remain visible but non-blocking during focused verification unless strict global mode is required.

package/package.json

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

package/scripts/update-codex-agents.ts

@@ -6,7 +6,7 @@
 import path from 'path';
 
 // Core
-import { configureProjectAgentSymlinks } from '../cli/utils/agents';
+import { configureProjectAgentInstructions } from '../cli/utils/agents';
 
 /*----------------------------------
 - TYPES
@@ -31,5 +31,5 @@ for (const projectRoot of projectRoots) {
     }
 
     console.log(`[update-codex-agents] Syncing project Codex assets in ${projectRoot}`);
-    configureProjectAgentSymlinks({ appRoot: projectRoot, coreRoot: proteumRoot });
+    configureProjectAgentInstructions({ appRoot: projectRoot, coreRoot: proteumRoot });
 }