proteum 2.1.6 → 2.1.8

package/cli/runtime/devSessions.ts

@@ -0,0 +1,337 @@
+import path from 'path';
+
+import fs from 'fs-extra';
+
+export const devSessionRegistryVersion = 1 as const;
+
+export type TDevSessionState = 'starting' | 'ready';
+
+export type TDevSessionRecord = {
+    version: typeof devSessionRegistryVersion;
+    pid: number;
+    appRoot: string;
+    routerPort: number;
+    publicUrl: string;
+    startedAt: string;
+    updatedAt: string;
+    sessionFilePath: string;
+    state: TDevSessionState;
+};
+
+export type TDevSessionInspection = {
+    sessionFilePath: string;
+    record: TDevSessionRecord | null;
+    live: boolean;
+    stale: boolean;
+    invalid: boolean;
+    parseError: string;
+};
+
+export type TStopDevSessionResult = {
+    sessionFilePath: string;
+    pid: number | null;
+    routerPort: number | null;
+    publicUrl: string;
+    state: TDevSessionState | '';
+    matched: boolean;
+    stopped: boolean;
+    removed: boolean;
+    stale: boolean;
+    live: boolean;
+    invalid: boolean;
+    parseError: string;
+};
+
+const defaultRegistryDirectoryParts = ['var', 'run', 'proteum', 'dev'];
+
+const sleep = async (durationMs: number) => await new Promise((resolve) => setTimeout(resolve, durationMs));
+
+const isRecordShape = (value: unknown): value is TDevSessionRecord => {
+    if (!value || typeof value !== 'object') return false;
+
+    const candidate = value as Partial<TDevSessionRecord>;
+
+    return (
+        candidate.version === devSessionRegistryVersion &&
+        typeof candidate.pid === 'number' &&
+        Number.isInteger(candidate.pid) &&
+        candidate.pid > 0 &&
+        typeof candidate.appRoot === 'string' &&
+        candidate.appRoot.length > 0 &&
+        typeof candidate.routerPort === 'number' &&
+        Number.isInteger(candidate.routerPort) &&
+        candidate.routerPort > 0 &&
+        typeof candidate.publicUrl === 'string' &&
+        typeof candidate.startedAt === 'string' &&
+        typeof candidate.updatedAt === 'string' &&
+        typeof candidate.sessionFilePath === 'string' &&
+        candidate.sessionFilePath.length > 0 &&
+        (candidate.state === 'starting' || candidate.state === 'ready')
+    );
+};
+
+const canSignalProcess = (pid: number, signal: NodeJS.Signals | 0) => {
+    try {
+        process.kill(pid, signal);
+        return true;
+    } catch (error) {
+        const errno = error as NodeJS.ErrnoException;
+
+        if (errno.code === 'ESRCH') return false;
+        if (errno.code === 'EPERM') return true;
+
+        throw error;
+    }
+};
+
+export const isProcessAlive = (pid: number) => canSignalProcess(pid, 0);
+
+const waitForProcessExit = async (pid: number, timeoutMs: number) => {
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) return true;
+        await sleep(100);
+    }
+
+    return !isProcessAlive(pid);
+};
+
+export const getDevSessionRegistryDirectory = (appRoot: string) => path.join(appRoot, ...defaultRegistryDirectoryParts);
+
+export const resolveDevSessionFilePath = ({
+    appRoot,
+    port,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    port: number;
+    sessionFilePath?: string;
+}) => {
+    if (sessionFilePath && sessionFilePath.trim()) {
+        return path.isAbsolute(sessionFilePath)
+            ? path.normalize(sessionFilePath)
+            : path.resolve(appRoot, sessionFilePath);
+    }
+
+    return path.join(getDevSessionRegistryDirectory(appRoot), `${port}.json`);
+};
+
+export const createDevSessionRecord = ({
+    appRoot,
+    port,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    port: number;
+    sessionFilePath: string;
+}): TDevSessionRecord => {
+    const timestamp = new Date().toISOString();
+
+    return {
+        version: devSessionRegistryVersion,
+        pid: process.pid,
+        appRoot,
+        routerPort: port,
+        publicUrl: '',
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        sessionFilePath,
+        state: 'starting',
+    };
+};
+
+export const writeDevSessionRecord = async (record: TDevSessionRecord) => {
+    await fs.ensureDir(path.dirname(record.sessionFilePath));
+    await fs.writeJson(record.sessionFilePath, record, { spaces: 2 });
+};
+
+export const updateDevSessionRecord = async ({
+    sessionFilePath,
+    patch,
+}: {
+    sessionFilePath: string;
+    patch: Partial<Omit<TDevSessionRecord, 'version' | 'pid' | 'appRoot' | 'routerPort' | 'startedAt' | 'sessionFilePath'>>;
+}) => {
+    const inspection = await inspectDevSessionFile(sessionFilePath);
+    if (!inspection || !inspection.record) return;
+
+    await writeDevSessionRecord({
+        ...inspection.record,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    });
+};
+
+export const removeDevSessionRecord = async (sessionFilePath: string) => {
+    await fs.remove(sessionFilePath);
+};
+
+export const removeDevSessionRecordSync = (sessionFilePath: string) => {
+    try {
+        fs.removeSync(sessionFilePath);
+    } catch {
+        // Best-effort cleanup during process exit.
+    }
+};
+
+export const inspectDevSessionFile = async (sessionFilePath: string): Promise<TDevSessionInspection | null> => {
+    if (!(await fs.pathExists(sessionFilePath))) return null;
+
+    try {
+        const rawValue = await fs.readJson(sessionFilePath);
+        if (!isRecordShape(rawValue)) {
+            return {
+                sessionFilePath,
+                record: null,
+                live: false,
+                stale: true,
+                invalid: true,
+                parseError: 'Session file contents do not match the Proteum dev session schema.',
+            };
+        }
+
+        const record = rawValue;
+        const live = isProcessAlive(record.pid);
+
+        return {
+            sessionFilePath,
+            record,
+            live,
+            stale: !live,
+            invalid: false,
+            parseError: '',
+        };
+    } catch (error) {
+        return {
+            sessionFilePath,
+            record: null,
+            live: false,
+            stale: true,
+            invalid: true,
+            parseError: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+
+export const listDevSessionFiles = async ({
+    appRoot,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    sessionFilePath?: string;
+}) => {
+    if (sessionFilePath && sessionFilePath.trim())
+        return [resolveDevSessionFilePath({ appRoot, port: 1, sessionFilePath })];
+
+    const registryDirectory = getDevSessionRegistryDirectory(appRoot);
+    if (!(await fs.pathExists(registryDirectory))) return [];
+
+    const entries = await fs.readdir(registryDirectory);
+
+    return entries
+        .filter((entry) => entry.endsWith('.json'))
+        .sort((left, right) => left.localeCompare(right))
+        .map((entry) => path.join(registryDirectory, entry));
+};
+
+export const listDevSessionInspections = async ({
+    appRoot,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    sessionFilePath?: string;
+}) => {
+    const sessionFilePaths = await listDevSessionFiles({ appRoot, sessionFilePath });
+    const inspections = await Promise.all(sessionFilePaths.map((entryPath) => inspectDevSessionFile(entryPath)));
+
+    return inspections.filter((inspection): inspection is TDevSessionInspection => inspection !== null);
+};
+
+export const stopDevSessionFile = async (sessionFilePath: string): Promise<TStopDevSessionResult> => {
+    const inspection = await inspectDevSessionFile(sessionFilePath);
+
+    if (!inspection) {
+        return {
+            sessionFilePath,
+            pid: null,
+            routerPort: null,
+            publicUrl: '',
+            state: '',
+            matched: false,
+            stopped: false,
+            removed: false,
+            stale: false,
+            live: false,
+            invalid: false,
+            parseError: '',
+        };
+    }
+
+    if (!inspection.record) {
+        await removeDevSessionRecord(sessionFilePath);
+
+        return {
+            sessionFilePath,
+            pid: null,
+            routerPort: null,
+            publicUrl: '',
+            state: '',
+            matched: true,
+            stopped: true,
+            removed: true,
+            stale: true,
+            live: false,
+            invalid: true,
+            parseError: inspection.parseError,
+        };
+    }
+
+    const { record } = inspection;
+
+    if (!inspection.live) {
+        await removeDevSessionRecord(sessionFilePath);
+
+        return {
+            sessionFilePath,
+            pid: record.pid,
+            routerPort: record.routerPort,
+            publicUrl: record.publicUrl,
+            state: record.state,
+            matched: true,
+            stopped: true,
+            removed: true,
+            stale: true,
+            live: false,
+            invalid: false,
+            parseError: '',
+        };
+    }
+
+    if (canSignalProcess(record.pid, 'SIGTERM')) {
+        const exitedAfterTerm = await waitForProcessExit(record.pid, 5000);
+        if (!exitedAfterTerm && canSignalProcess(record.pid, 'SIGKILL')) {
+            await waitForProcessExit(record.pid, 2000);
+        }
+    }
+
+    const live = isProcessAlive(record.pid);
+    if (!live) {
+        await removeDevSessionRecord(sessionFilePath);
+    }
+
+    return {
+        sessionFilePath,
+        pid: record.pid,
+        routerPort: record.routerPort,
+        publicUrl: record.publicUrl,
+        state: record.state,
+        matched: true,
+        stopped: !live,
+        removed: !live,
+        stale: !live,
+        live,
+        invalid: false,
+        parseError: '',
+    };
+};

package/cli/scaffold/index.ts

@@ -5,7 +5,7 @@ import { UsageError } from 'clipanion';
 
 import cli from '..';
 import { loadApplicationIdentityConfig } from '../../common/applicationConfigLoader';
-import { ensureProjectAgentSymlinks } from '../utils/agents';
+import { ensureProjectAgentSymlinks, renderProjectInstructionGitignoreBlock } from '../utils/agents';
 import { runProcess } from '../utils/runProcess';
 import {
     createClientTsconfigTemplate,
@@ -633,7 +633,9 @@ const createInitFilePlans = (config: TScaffoldInitConfig): TScaffoldFilePlan[] =
     },
     {
         relativePath: '.gitignore',
-        content: createGitignoreTemplate(),
+        content: createGitignoreTemplate({
+            projectInstructionGitignoreBlock: renderProjectInstructionGitignoreBlock({ coreRoot: cli.paths.core.root }),
+        }),
     },
     {
         relativePath: 'eslint.config.mjs',

package/cli/scaffold/templates.ts

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

package/cli/utils/agents.ts

@@ -11,6 +11,7 @@ import { logVerbose } from '../runtime/verbose';
 - TYPES
 ----------------------------------*/
 
+type TProjectInstructionArgs = { coreRoot: string };
 type TEnsureProjectAgentSymlinksArgs = { appRoot: string; coreRoot: string };
 
 type TAgentLinkDefinition = { projectPath: string; sourcePath: string; ensureParentDir?: boolean };
@@ -34,41 +35,107 @@ const projectAgentLinkDefinitions: TAgentLinkDefinition[] = [
     { projectPath: path.join('server', 'routes', 'AGENTS.md'), sourcePath: path.join('server', 'routes', 'AGENTS.md') },
     { projectPath: path.join('tests', 'e2e', 'AGENTS.md'), sourcePath: path.join('tests', 'AGENTS.md') },
 ];
+const projectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
+const projectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction symlinks';
 
 /*----------------------------------
 - PUBLIC API
 ----------------------------------*/
 
 export function ensureProjectAgentSymlinks({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
-    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
-    const agentLinks = projectAgentLinkDefinitions.map((linkDefinition) => ({
-        ...linkDefinition,
-        sourcePath: path.join(agentSourceRoot, linkDefinition.sourcePath),
-    }));
+    ensureSymlinks(appRoot, getProjectAgentLinkDefinitions({ coreRoot }), '[agents]');
+    ensureSymlinks(appRoot, getProjectSkillLinkDefinitions({ coreRoot }), '[skills]');
+    ensureProjectInstructionGitignoreEntries({ appRoot, coreRoot });
+}
+
+export function getProjectInstructionGitignoreEntries({ coreRoot }: TProjectInstructionArgs) {
+    const entries = new Set<string>();
 
-    ensureSymlinks(appRoot, agentLinks, '[agents]');
-    ensureProjectSkillSymlinks({ appRoot, coreRoot });
+    for (const linkDefinition of [
+        ...getProjectAgentLinkDefinitions({ coreRoot }),
+        ...getProjectSkillLinkDefinitions({ coreRoot }),
+    ]) {
+        entries.add(`/${normalizeProjectPathForGitignore(linkDefinition.projectPath)}`);
+    }
+
+    return Array.from(entries);
+}
+
+export function renderProjectInstructionGitignoreBlock({ coreRoot }: TProjectInstructionArgs) {
+    return [
+        projectInstructionGitignoreBlockStart,
+        ...getProjectInstructionGitignoreEntries({ coreRoot }),
+        projectInstructionGitignoreBlockEnd,
+    ].join('\n');
 }
 
 /*----------------------------------
 - HELPERS
 ----------------------------------*/
 
-function ensureProjectSkillSymlinks({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
+function getProjectAgentLinkDefinitions({ coreRoot }: TProjectInstructionArgs) {
+    const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
+
+    return projectAgentLinkDefinitions.map((linkDefinition) => ({
+        ...linkDefinition,
+        sourcePath: path.join(agentSourceRoot, linkDefinition.sourcePath),
+    }));
+}
+
+function getProjectSkillLinkDefinitions({ coreRoot }: TProjectInstructionArgs) {
     const frameworkSkillsRoot = path.join(coreRoot, 'skills');
-    if (!fs.existsSync(frameworkSkillsRoot)) return;
+    if (!fs.existsSync(frameworkSkillsRoot)) return [];
 
-    const skillLinks: TAgentLinkDefinition[] = fs
+    return fs
         .readdirSync(frameworkSkillsRoot, { withFileTypes: true })
         .filter((dirent) => dirent.isDirectory())
+        .sort((left, right) => left.name.localeCompare(right.name))
         .map((dirent) => ({
             projectPath: path.join('skills', dirent.name),
             sourcePath: path.join(frameworkSkillsRoot, dirent.name),
             ensureParentDir: true,
         }))
         .filter((linkDefinition) => pathEntryExists(path.join(linkDefinition.sourcePath, 'SKILL.md')));
+}
+
+function ensureProjectInstructionGitignoreEntries({ appRoot, coreRoot }: TEnsureProjectAgentSymlinksArgs) {
+    const gitignoreFilepath = path.join(appRoot, '.gitignore');
+    if (!pathEntryExists(gitignoreFilepath)) return;
+
+    const managedEntries = getProjectInstructionGitignoreEntries({ coreRoot });
+    const managedNormalizedEntries = new Set(managedEntries.map(normalizeGitignoreEntry));
+    const lines = fs.readFileSync(gitignoreFilepath, 'utf8').split(/\r?\n/);
+    const filteredLines: string[] = [];
+
+    let insideManagedBlock = false;
 
-    ensureSymlinks(appRoot, skillLinks, '[skills]');
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+
+        if (trimmedLine === projectInstructionGitignoreBlockStart) {
+            insideManagedBlock = true;
+            continue;
+        }
+
+        if (trimmedLine === projectInstructionGitignoreBlockEnd) {
+            insideManagedBlock = false;
+            continue;
+        }
+
+        if (insideManagedBlock) continue;
+        if (shouldSkipLegacyManagedGitignoreLine(line, managedNormalizedEntries)) continue;
+
+        filteredLines.push(line);
+    }
+
+    const baseContent = trimTrailingBlankLines(filteredLines).join('\n');
+    const managedBlock = renderProjectInstructionGitignoreBlock({ coreRoot });
+    const nextContent = baseContent ? `${baseContent}\n\n${managedBlock}\n` : `${managedBlock}\n`;
+
+    if (nextContent === fs.readFileSync(gitignoreFilepath, 'utf8')) return;
+
+    fs.writeFileSync(gitignoreFilepath, nextContent);
+    logVerbose(`[agents] Updated ${path.relative(appRoot, gitignoreFilepath) || '.gitignore'} with Proteum-managed instruction ignore entries.`);
 }
 
 function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[], logPrefix: string) {
@@ -93,6 +160,30 @@ function ensureSymlinks(appRoot: string, linkDefinitions: TAgentLinkDefinition[]
     }
 }
 
+function normalizeProjectPathForGitignore(projectPath: string) {
+    return projectPath.replace(/\\/g, '/');
+}
+
+function normalizeGitignoreEntry(value: string) {
+    return value.trim().replace(/#.*/, '').replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function shouldSkipLegacyManagedGitignoreLine(line: string, managedNormalizedEntries: Set<string>) {
+    const normalizedLine = normalizeGitignoreEntry(line);
+    if (!normalizedLine) return false;
+    if (line.trim().startsWith('#')) return false;
+
+    return managedNormalizedEntries.has(normalizedLine);
+}
+
+function trimTrailingBlankLines(lines: string[]) {
+    const trimmedLines = [...lines];
+
+    while (trimmedLines.length > 0 && trimmedLines[trimmedLines.length - 1].trim() === '') trimmedLines.pop();
+
+    return trimmedLines;
+}
+
 function pathEntryExists(filepath: string) {
     try {
         fs.lstatSync(filepath);

package/package.json

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

package/server/app/container/index.ts

@@ -74,7 +74,13 @@ export class ApplicationContainer<TServicesIndex extends StartedServicesIndex =
 
         // Start application
         try {
-            this.application.start();
+            void this.application.start().catch(async (error) => {
+                try {
+                    await this.handleBug(error, 'Failed to start the Application');
+                } finally {
+                    process.exit(1);
+                }
+            });
         } catch (error) {
             this.handleBug(error, 'Failed to start the Application');
             process.exit(1);

package/server/services/router/http/index.ts

@@ -92,6 +92,27 @@ const createContentSecurityPolicy = (config: Config['csp']): TContentSecurityPol
     };
 };
 
+const immutablePublicAssetCacheControl = 'public, max-age=31536000, immutable';
+const revalidatedPublicAssetCacheControl = 'public, max-age=0, must-revalidate';
+const hashedPublicAssetPattern = /(^|[-_.])[a-f0-9]{6,}(?=(\.[^.]+)+$)/i;
+const connectedProjectBootRetryCount = 10;
+const connectedProjectBootRetryDelayMs = 5_000;
+
+const isVersionedPublicAssetRequest = (res: express.Response, filePath: string) => {
+    const requestUrl = res.req?.originalUrl || res.req?.url || '';
+    const searchParams = new URL(requestUrl, 'http://proteum.local').searchParams;
+    if (searchParams.has('v')) return true;
+
+    return hashedPublicAssetPattern.test(path.basename(filePath));
+};
+
+const resolvePublicAssetCacheControl = (res: express.Response, filePath: string) =>
+    isVersionedPublicAssetRequest(res, filePath) ? immutablePublicAssetCacheControl : revalidatedPublicAssetCacheControl;
+const wait = async (durationMs: number) =>
+    await new Promise<void>((resolve) => {
+        setTimeout(resolve, durationMs);
+    });
+
 /*----------------------------------
 - FUNCTION
 ----------------------------------*/
@@ -149,22 +170,38 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
     private async verifyConnectedProjectsBeforeStart() {
         for (const connectedProject of Object.values(this.app.connectedProjects || {})) {
             const healthUrl = new URL(connectedProjectHealthPath, connectedProject.urlInternal).toString();
+            let lastError: Error | undefined;
 
-            let response: Response;
-            try {
-                response = await fetch(healthUrl, {
-                    headers: { Accept: 'application/json' },
-                });
-            } catch (error) {
-                throw new Error(
-                    `Connected project "${connectedProject.namespace}" is unreachable at ${connectedProject.urlInternal}. ${error instanceof Error ? error.message : String(error)}`,
-                );
-            }
+            for (let retryIndex = 0; retryIndex <= connectedProjectBootRetryCount; retryIndex++) {
+                try {
+                    const response = await fetch(healthUrl, {
+                        headers: { Accept: 'application/json' },
+                    });
+
+                    if (!response.ok) {
+                        throw new Error(
+                            `Connected project "${connectedProject.namespace}" health check failed at ${healthUrl} with status ${response.status}.`,
+                        );
+                    }
+
+                    lastError = undefined;
+                    break;
+                } catch (error) {
+                    lastError =
+                        error instanceof Error && error.message.startsWith(`Connected project "${connectedProject.namespace}"`)
+                            ? error
+                            : new Error(
+                                  `Connected project "${connectedProject.namespace}" is unreachable at ${connectedProject.urlInternal}. ${error instanceof Error ? error.message : String(error)}`,
+                              );
+                }
 
-            if (!response.ok) {
-                throw new Error(
-                    `Connected project "${connectedProject.namespace}" health check failed at ${healthUrl} with status ${response.status}.`,
+                if (!lastError) continue;
+                if (retryIndex === connectedProjectBootRetryCount) throw lastError;
+
+                console.warn(
+                    `[connect] ${lastError.message} Retrying ${retryIndex + 1}/${connectedProjectBootRetryCount} in ${connectedProjectBootRetryDelayMs / 1000}s.`,
                 );
+                await wait(connectedProjectBootRetryDelayMs);
             }
         }
     }
@@ -329,17 +366,8 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
             '/public',
             express.static(path.join(Container.path.root, APP_OUTPUT_DIR, 'public'), {
                 dotfiles: 'deny',
-                setHeaders: function setCustomCacheControl(res, path) {
-                    const dontCache = ['/public/icons', '/public/client'];
-
-                    res.setHeader('Cache-Control', 'public, max-age=0');
-
-                    // Set long term cache, except for non-hashed filenames
-                    /*if (dontCache.some( p => path.startsWith( p ))) {
-                        res.setHeader('Cache-Control', 'public, max-age=0');
-                    } else {
-                        res.setHeader('Cache-Control', 'public, max-age=604800000'); // 7 Days
-                    }*/
+                setHeaders: function setCustomCacheControl(res, filePath) {
+                    res.setHeader('Cache-Control', resolvePublicAssetCacheControl(res, filePath));
                 },
             }),
             (req, res) => {