proteum 2.3.0 → 2.4.1

package/cli/runtime/devSessions.ts

@@ -1,8 +1,11 @@
+import crypto from 'crypto';
+import os from 'os';
 import path from 'path';
 
 import fs from 'fs-extra';
 
 export const devSessionRegistryVersion = 1 as const;
+export const machineDevSessionRegistryVersion = 1 as const;
 
 export type TDevSessionState = 'starting' | 'ready';
 
@@ -18,6 +21,20 @@ export type TDevSessionRecord = {
     state: TDevSessionState;
 };
 
+export type TMachineDevSessionRecord = {
+    version: typeof machineDevSessionRegistryVersion;
+    projectId: string;
+    appRoot: string;
+    pid: number;
+    routerPort: number;
+    publicUrl: string;
+    mcpUrl: string;
+    startedAt: string;
+    updatedAt: string;
+    sessionFilePath: string;
+    state: TDevSessionState;
+};
+
 export type TDevSessionInspection = {
     sessionFilePath: string;
     record: TDevSessionRecord | null;
@@ -27,6 +44,15 @@ export type TDevSessionInspection = {
     parseError: string;
 };
 
+export type TMachineDevSessionInspection = {
+    registryFilePath: string;
+    record: TMachineDevSessionRecord | null;
+    live: boolean;
+    stale: boolean;
+    invalid: boolean;
+    parseError: string;
+};
+
 export type TStopDevSessionResult = {
     sessionFilePath: string;
     pid: number | null;
@@ -42,7 +68,14 @@ export type TStopDevSessionResult = {
     parseError: string;
 };
 
+export type TPrepareDevSessionStartResult = {
+    blocking: TDevSessionInspection[];
+    cleaned: TStopDevSessionResult[];
+    replaced: TStopDevSessionResult | null;
+};
+
 const defaultRegistryDirectoryParts = ['var', 'run', 'proteum', 'dev'];
+const defaultMachineRegistryDirectoryParts = ['.proteum', 'dev-sessions'];
 
 const sleep = async (durationMs: number) => await new Promise((resolve) => setTimeout(resolve, durationMs));
 
@@ -70,6 +103,33 @@ const isRecordShape = (value: unknown): value is TDevSessionRecord => {
     );
 };
 
+const isMachineRecordShape = (value: unknown): value is TMachineDevSessionRecord => {
+    if (!value || typeof value !== 'object') return false;
+
+    const candidate = value as Partial<TMachineDevSessionRecord>;
+
+    return (
+        candidate.version === machineDevSessionRegistryVersion &&
+        typeof candidate.projectId === 'string' &&
+        candidate.projectId.startsWith('prj_') &&
+        typeof candidate.appRoot === 'string' &&
+        candidate.appRoot.length > 0 &&
+        typeof candidate.pid === 'number' &&
+        Number.isInteger(candidate.pid) &&
+        candidate.pid > 0 &&
+        typeof candidate.routerPort === 'number' &&
+        Number.isInteger(candidate.routerPort) &&
+        candidate.routerPort > 0 &&
+        typeof candidate.publicUrl === 'string' &&
+        typeof candidate.mcpUrl === '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);
@@ -99,6 +159,39 @@ const waitForProcessExit = async (pid: number, timeoutMs: number) => {
 
 export const getDevSessionRegistryDirectory = (appRoot: string) => path.join(appRoot, ...defaultRegistryDirectoryParts);
 
+export const getMachineDevSessionRegistryDirectory = () =>
+    process.env.PROTEUM_MACHINE_DEV_SESSION_DIR && process.env.PROTEUM_MACHINE_DEV_SESSION_DIR.trim()
+        ? path.resolve(process.env.PROTEUM_MACHINE_DEV_SESSION_DIR)
+        : path.join(os.homedir(), ...defaultMachineRegistryDirectoryParts);
+
+const createProjectIdFromCanonicalAppRoot = (canonicalAppRoot: string) =>
+    `prj_${crypto.createHash('sha256').update(canonicalAppRoot).digest('hex').slice(0, 12)}`;
+
+export const resolveCanonicalAppRoot = async (appRoot: string) => {
+    try {
+        return path.normalize(await fs.realpath(appRoot));
+    } catch {
+        return path.resolve(appRoot);
+    }
+};
+
+export const resolveCanonicalAppRootSync = (appRoot: string) => {
+    try {
+        return path.normalize(fs.realpathSync(appRoot));
+    } catch {
+        return path.resolve(appRoot);
+    }
+};
+
+export const resolveProteumProjectId = async (appRoot: string) =>
+    createProjectIdFromCanonicalAppRoot(await resolveCanonicalAppRoot(appRoot));
+
+export const resolveProteumProjectIdSync = (appRoot: string) =>
+    createProjectIdFromCanonicalAppRoot(resolveCanonicalAppRootSync(appRoot));
+
+export const resolveMachineDevSessionFilePath = (projectId: string) =>
+    path.join(getMachineDevSessionRegistryDirectory(), `${projectId}.json`);
+
 export const resolveDevSessionFilePath = ({
     appRoot,
     port,
@@ -141,11 +234,184 @@ export const createDevSessionRecord = ({
     };
 };
 
+export const createMachineDevSessionRecord = async (record: TDevSessionRecord): Promise<TMachineDevSessionRecord> => {
+    const appRoot = await resolveCanonicalAppRoot(record.appRoot);
+    const projectId = createProjectIdFromCanonicalAppRoot(appRoot);
+    const publicUrl = record.publicUrl || `http://localhost:${record.routerPort}`;
+
+    return {
+        version: machineDevSessionRegistryVersion,
+        projectId,
+        appRoot,
+        pid: record.pid,
+        routerPort: record.routerPort,
+        publicUrl,
+        mcpUrl: `${publicUrl.replace(/\/+$/, '')}/__proteum/mcp`,
+        startedAt: record.startedAt,
+        updatedAt: record.updatedAt,
+        sessionFilePath: record.sessionFilePath,
+        state: record.state,
+    };
+};
+
 export const writeDevSessionRecord = async (record: TDevSessionRecord) => {
     await fs.ensureDir(path.dirname(record.sessionFilePath));
     await fs.writeJson(record.sessionFilePath, record, { spaces: 2 });
 };
 
+export const writeMachineDevSessionRecord = async (record: TDevSessionRecord) => {
+    const machineRecord = await createMachineDevSessionRecord(record);
+    const registryFilePath = resolveMachineDevSessionFilePath(machineRecord.projectId);
+
+    await fs.ensureDir(path.dirname(registryFilePath));
+    await fs.writeJson(registryFilePath, machineRecord, { spaces: 2 });
+
+    return machineRecord;
+};
+
+export const inspectMachineDevSessionFile = async (registryFilePath: string): Promise<TMachineDevSessionInspection | null> => {
+    if (!(await fs.pathExists(registryFilePath))) return null;
+
+    try {
+        const rawValue = await fs.readJson(registryFilePath);
+        if (!isMachineRecordShape(rawValue)) {
+            return {
+                registryFilePath,
+                record: null,
+                live: false,
+                stale: true,
+                invalid: true,
+                parseError: 'Machine session file contents do not match the Proteum dev session schema.',
+            };
+        }
+
+        const record = rawValue;
+        const live = isProcessAlive(record.pid);
+
+        return {
+            registryFilePath,
+            record,
+            live,
+            stale: !live,
+            invalid: false,
+            parseError: '',
+        };
+    } catch (error) {
+        return {
+            registryFilePath,
+            record: null,
+            live: false,
+            stale: true,
+            invalid: true,
+            parseError: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+
+export const listMachineDevSessionFiles = async () => {
+    const registryDirectory = getMachineDevSessionRegistryDirectory();
+    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 listMachineDevSessionInspections = async ({
+    cleanStale = true,
+}: {
+    cleanStale?: boolean;
+} = {}) => {
+    const registryFilePaths = await listMachineDevSessionFiles();
+    const inspections = (
+        await Promise.all(registryFilePaths.map((registryFilePath) => inspectMachineDevSessionFile(registryFilePath)))
+    ).filter((inspection): inspection is TMachineDevSessionInspection => inspection !== null);
+
+    if (cleanStale) {
+        await Promise.all(
+            inspections
+                .filter((inspection) => inspection.invalid || inspection.stale || !inspection.record)
+                .map((inspection) => fs.remove(inspection.registryFilePath)),
+        );
+    }
+
+    return cleanStale ? inspections.filter((inspection) => inspection.record && inspection.live) : inspections;
+};
+
+export const resolveMachineDevSessionInspection = async (projectId: string) => {
+    const inspection = await inspectMachineDevSessionFile(resolveMachineDevSessionFilePath(projectId));
+
+    if (!inspection) return null;
+
+    if (inspection.invalid || inspection.stale || !inspection.record) {
+        await fs.remove(inspection.registryFilePath);
+        return null;
+    }
+
+    return inspection;
+};
+
+const normalizeMaybeRelativePath = (value: string) => path.normalize(path.resolve(value));
+
+export const removeMachineDevSessionRecordForDevSession = async ({
+    appRoot,
+    pid = process.pid,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    pid?: number;
+    sessionFilePath: string;
+}) => {
+    const projectId = await resolveProteumProjectId(appRoot);
+    const registryFilePath = resolveMachineDevSessionFilePath(projectId);
+    const inspection = await inspectMachineDevSessionFile(registryFilePath);
+    if (!inspection?.record) {
+        if (inspection?.invalid) await fs.remove(registryFilePath);
+        return;
+    }
+
+    if (
+        inspection.record.pid === pid &&
+        normalizeMaybeRelativePath(inspection.record.sessionFilePath) === normalizeMaybeRelativePath(sessionFilePath)
+    ) {
+        await fs.remove(registryFilePath);
+    }
+};
+
+export const removeMachineDevSessionRecordForDevSessionSync = ({
+    appRoot,
+    pid = process.pid,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    pid?: number;
+    sessionFilePath: string;
+}) => {
+    try {
+        const projectId = resolveProteumProjectIdSync(appRoot);
+        const registryFilePath = resolveMachineDevSessionFilePath(projectId);
+        if (!fs.pathExistsSync(registryFilePath)) return;
+
+        const record = fs.readJsonSync(registryFilePath);
+        if (!isMachineRecordShape(record)) {
+            fs.removeSync(registryFilePath);
+            return;
+        }
+
+        if (
+            record.pid === pid &&
+            normalizeMaybeRelativePath(record.sessionFilePath) === normalizeMaybeRelativePath(sessionFilePath)
+        ) {
+            fs.removeSync(registryFilePath);
+        }
+    } catch {
+        // Best-effort cleanup during process exit.
+    }
+};
+
 export const updateDevSessionRecord = async ({
     sessionFilePath,
     patch,
@@ -156,19 +422,38 @@ export const updateDevSessionRecord = async ({
     const inspection = await inspectDevSessionFile(sessionFilePath);
     if (!inspection || !inspection.record) return;
 
-    await writeDevSessionRecord({
+    const updatedRecord = {
         ...inspection.record,
         ...patch,
         updatedAt: new Date().toISOString(),
-    });
+    };
+
+    await writeDevSessionRecord(updatedRecord);
+    await writeMachineDevSessionRecord(updatedRecord);
 };
 
 export const removeDevSessionRecord = async (sessionFilePath: string) => {
+    const inspection = await inspectDevSessionFile(sessionFilePath);
+    if (inspection?.record) {
+        await removeMachineDevSessionRecordForDevSession({
+            appRoot: inspection.record.appRoot,
+            pid: inspection.record.pid,
+            sessionFilePath,
+        });
+    }
     await fs.remove(sessionFilePath);
 };
 
 export const removeDevSessionRecordSync = (sessionFilePath: string) => {
     try {
+        const inspection = fs.pathExistsSync(sessionFilePath) ? fs.readJsonSync(sessionFilePath) : undefined;
+        if (isRecordShape(inspection)) {
+            removeMachineDevSessionRecordForDevSessionSync({
+                appRoot: inspection.appRoot,
+                pid: inspection.pid,
+                sessionFilePath,
+            });
+        }
         fs.removeSync(sessionFilePath);
     } catch {
         // Best-effort cleanup during process exit.
@@ -248,6 +533,47 @@ export const listDevSessionInspections = async ({
     return inspections.filter((inspection): inspection is TDevSessionInspection => inspection !== null);
 };
 
+const normalizeSessionFilePath = (sessionFilePath: string) => path.normalize(sessionFilePath);
+
+export const prepareDevSessionStart = async ({
+    appRoot,
+    currentPid = process.pid,
+    replaceExisting,
+    sessionFilePath,
+}: {
+    appRoot: string;
+    currentPid?: number;
+    replaceExisting: boolean;
+    sessionFilePath: string;
+}): Promise<TPrepareDevSessionStartResult> => {
+    const inspections = await listDevSessionInspections({ appRoot });
+    const normalizedSessionFilePath = normalizeSessionFilePath(sessionFilePath);
+    const blocking: TDevSessionInspection[] = [];
+    const cleaned: TStopDevSessionResult[] = [];
+    let replaced: TStopDevSessionResult | null = null;
+
+    for (const inspection of inspections) {
+        const isCurrentSessionFile = normalizeSessionFilePath(inspection.sessionFilePath) === normalizedSessionFilePath;
+
+        if (!inspection.record || !inspection.live) {
+            cleaned.push(await stopDevSessionFile(inspection.sessionFilePath));
+            continue;
+        }
+
+        if (inspection.record.pid === currentPid) continue;
+
+        if (isCurrentSessionFile && replaceExisting) {
+            replaced = await stopDevSessionFile(inspection.sessionFilePath);
+            if (!replaced.stopped) blocking.push(inspection);
+            continue;
+        }
+
+        blocking.push(inspection);
+    }
+
+    return { blocking, cleaned, replaced };
+};
+
 export const stopDevSessionFile = async (sessionFilePath: string): Promise<TStopDevSessionResult> => {
     const inspection = await inspectDevSessionFile(sessionFilePath);
 

package/cli/runtime/mcpDaemon.ts

@@ -0,0 +1,288 @@
+import { spawn } from 'child_process';
+import os from 'os';
+import path from 'path';
+
+import fs from 'fs-extra';
+
+export const machineMcpDaemonRegistryVersion = 1 as const;
+
+export type TMachineMcpDaemonRecord = {
+    version: typeof machineMcpDaemonRegistryVersion;
+    pid: number;
+    port: number;
+    host: string;
+    mcpUrl: string;
+    healthUrl: string;
+    startedAt: string;
+    updatedAt: string;
+    command: string[];
+};
+
+export type TMachineMcpDaemonInspection = {
+    registryFilePath: string;
+    record: TMachineMcpDaemonRecord | null;
+    live: boolean;
+    stale: boolean;
+    invalid: boolean;
+    parseError: string;
+};
+
+export type TEnsureMachineMcpDaemonResult = {
+    inspection: TMachineMcpDaemonInspection;
+    started: boolean;
+};
+
+const defaultMachineMcpDaemonDirectoryParts = ['.proteum', 'mcp'];
+const defaultMachineMcpDaemonPort = 3769;
+const machineMcpDaemonHost = '127.0.0.1';
+
+const sleep = async (durationMs: number) => await new Promise((resolve) => setTimeout(resolve, durationMs));
+
+const isRecordShape = (value: unknown): value is TMachineMcpDaemonRecord => {
+    if (!value || typeof value !== 'object') return false;
+
+    const candidate = value as Partial<TMachineMcpDaemonRecord>;
+
+    return (
+        candidate.version === machineMcpDaemonRegistryVersion &&
+        typeof candidate.pid === 'number' &&
+        Number.isInteger(candidate.pid) &&
+        candidate.pid > 0 &&
+        typeof candidate.port === 'number' &&
+        Number.isInteger(candidate.port) &&
+        candidate.port > 0 &&
+        typeof candidate.host === 'string' &&
+        candidate.host.length > 0 &&
+        typeof candidate.mcpUrl === 'string' &&
+        candidate.mcpUrl.length > 0 &&
+        typeof candidate.healthUrl === 'string' &&
+        candidate.healthUrl.length > 0 &&
+        typeof candidate.startedAt === 'string' &&
+        typeof candidate.updatedAt === 'string' &&
+        Array.isArray(candidate.command) &&
+        candidate.command.every((entry) => typeof entry === 'string')
+    );
+};
+
+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;
+    }
+};
+
+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 getMachineMcpDaemonRegistryDirectory = () =>
+    process.env.PROTEUM_MACHINE_MCP_DIR && process.env.PROTEUM_MACHINE_MCP_DIR.trim()
+        ? path.resolve(process.env.PROTEUM_MACHINE_MCP_DIR)
+        : path.join(os.homedir(), ...defaultMachineMcpDaemonDirectoryParts);
+
+export const resolveMachineMcpDaemonRecordFilePath = () =>
+    path.join(getMachineMcpDaemonRegistryDirectory(), 'router.json');
+
+export const resolveMachineMcpDaemonPort = (port?: string | number) => {
+    const rawPort =
+        port !== undefined && String(port).trim()
+            ? String(port).trim()
+            : process.env.PROTEUM_MCP_PORT && process.env.PROTEUM_MCP_PORT.trim()
+              ? process.env.PROTEUM_MCP_PORT.trim()
+              : String(defaultMachineMcpDaemonPort);
+    const parsedPort = Number(rawPort);
+
+    if (!Number.isInteger(parsedPort) || parsedPort <= 0 || parsedPort > 65535) {
+        throw new Error(`Invalid Proteum MCP daemon port: ${rawPort}.`);
+    }
+
+    return parsedPort;
+};
+
+export const createMachineMcpDaemonRecord = ({
+    command,
+    host = machineMcpDaemonHost,
+    pid = process.pid,
+    port,
+}: {
+    command: string[];
+    host?: string;
+    pid?: number;
+    port: number;
+}): TMachineMcpDaemonRecord => {
+    const timestamp = new Date().toISOString();
+    const baseUrl = `http://${host}:${port}`;
+
+    return {
+        version: machineMcpDaemonRegistryVersion,
+        pid,
+        port,
+        host,
+        mcpUrl: `${baseUrl}/mcp`,
+        healthUrl: `${baseUrl}/health`,
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        command,
+    };
+};
+
+export const writeMachineMcpDaemonRecord = async (record: TMachineMcpDaemonRecord) => {
+    const registryFilePath = resolveMachineMcpDaemonRecordFilePath();
+
+    await fs.ensureDir(path.dirname(registryFilePath));
+    await fs.writeJson(registryFilePath, record, { spaces: 2 });
+
+    return record;
+};
+
+export const removeMachineMcpDaemonRecord = async (pid = process.pid) => {
+    const inspection = await inspectMachineMcpDaemonRecord({ cleanStale: false });
+
+    if (!inspection?.record || inspection.record.pid === pid) {
+        await fs.remove(resolveMachineMcpDaemonRecordFilePath());
+    }
+};
+
+export const removeMachineMcpDaemonRecordSync = (pid = process.pid) => {
+    try {
+        const registryFilePath = resolveMachineMcpDaemonRecordFilePath();
+        if (!fs.pathExistsSync(registryFilePath)) return;
+
+        const record = fs.readJsonSync(registryFilePath);
+        if (!isRecordShape(record) || record.pid === pid) fs.removeSync(registryFilePath);
+    } catch {
+        // Best-effort cleanup during process exit.
+    }
+};
+
+export const inspectMachineMcpDaemonRecord = async ({
+    cleanStale = true,
+}: {
+    cleanStale?: boolean;
+} = {}): Promise<TMachineMcpDaemonInspection | null> => {
+    const registryFilePath = resolveMachineMcpDaemonRecordFilePath();
+    if (!(await fs.pathExists(registryFilePath))) return null;
+
+    try {
+        const rawValue = await fs.readJson(registryFilePath);
+        if (!isRecordShape(rawValue)) {
+            const inspection = {
+                registryFilePath,
+                record: null,
+                live: false,
+                stale: true,
+                invalid: true,
+                parseError: 'Machine MCP daemon file contents do not match the Proteum MCP daemon schema.',
+            };
+
+            if (cleanStale) await fs.remove(registryFilePath);
+            return inspection;
+        }
+
+        const record = rawValue;
+        const live = isProcessAlive(record.pid);
+        const inspection = {
+            registryFilePath,
+            record,
+            live,
+            stale: !live,
+            invalid: false,
+            parseError: '',
+        };
+
+        if (cleanStale && !live) await fs.remove(registryFilePath);
+
+        return inspection;
+    } catch (error) {
+        const inspection = {
+            registryFilePath,
+            record: null,
+            live: false,
+            stale: true,
+            invalid: true,
+            parseError: error instanceof Error ? error.message : String(error),
+        };
+
+        if (cleanStale) await fs.remove(registryFilePath);
+
+        return inspection;
+    }
+};
+
+export const ensureMachineMcpDaemonProcess = async ({
+    coreRoot,
+    port,
+}: {
+    coreRoot: string;
+    port?: string | number;
+}): Promise<TEnsureMachineMcpDaemonResult> => {
+    const existing = await inspectMachineMcpDaemonRecord();
+    if (existing?.record && existing.live) return { inspection: existing, started: false };
+
+    const resolvedPort = resolveMachineMcpDaemonPort(port);
+    const cliBin = path.join(coreRoot, 'cli', 'bin.js');
+    const args = [cliBin, 'mcp', '--daemon', '--port', String(resolvedPort)];
+    const child = spawn(process.execPath, args, {
+        cwd: coreRoot,
+        detached: true,
+        stdio: 'ignore',
+    });
+
+    child.unref();
+
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+        await sleep(100);
+        const inspection = await inspectMachineMcpDaemonRecord({ cleanStale: false });
+        if (inspection?.record && inspection.live && inspection.record.pid === child.pid) {
+            return { inspection, started: true };
+        }
+        if (child.exitCode !== null || child.signalCode !== null) break;
+    }
+
+    const latest = await inspectMachineMcpDaemonRecord({ cleanStale: false });
+    if (latest?.record && latest.live) return { inspection: latest, started: false };
+
+    throw new Error('Proteum could not start the machine MCP daemon.');
+};
+
+export const stopMachineMcpDaemonProcess = async () => {
+    const inspection = await inspectMachineMcpDaemonRecord({ cleanStale: false });
+
+    if (!inspection?.record) {
+        if (inspection?.invalid) await fs.remove(inspection.registryFilePath);
+        return { inspection, stopped: true };
+    }
+
+    if (!inspection.live) {
+        await fs.remove(inspection.registryFilePath);
+        return { inspection, stopped: true };
+    }
+
+    if (canSignalProcess(inspection.record.pid, 'SIGTERM')) {
+        const exitedAfterTerm = await waitForProcessExit(inspection.record.pid, 5000);
+        if (!exitedAfterTerm && canSignalProcess(inspection.record.pid, 'SIGKILL')) {
+            await waitForProcessExit(inspection.record.pid, 2000);
+        }
+    }
+
+    const live = isProcessAlive(inspection.record.pid);
+    if (!live) await fs.remove(inspection.registryFilePath);
+
+    return { inspection, stopped: !live };
+};