@loucompanion/forge-bridge 0.1.3-dev.ba7d36726eda → 0.1.3-dev.bca7d0ccee53

package/dist/runtime/host-runtime-contract.js

@@ -1,13 +1,25 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { isAlias, parseDocument, visit } from "yaml";
 export const hostRuntimeContractPath = ".forge/forge.runtime.yml";
 const maximumContractBytes = 64 * 1024;
 const maximumDepth = 12;
+const ignoredDiscoveryDirectories = new Set([
+    ".forge",
+    ".forge-designer",
+    ".git",
+    ".local",
+    "bin",
+    "coverage",
+    "dist",
+    "node_modules",
+    "obj",
+]);
 const topLevelKeys = new Set(["schemaVersion", "runtime"]);
 const runtimeKeys = new Set(["hostConcurrency", "ports", "playwright", "browserProfile", "singletonResources"]);
 const portKeys = new Set(["adapter", "launch", "env", "baseUrlEnv", "format"]);
-const launchKeys = new Set(["command", "args", "workingDirectory"]);
+const launchKeys = new Set(["command", "args", "workingDirectory", "environment"]);
 const playwrightKeys = new Set(["config", "baseUrlPort", "workers"]);
 export async function loadHostRuntimeContract(worktreePath) {
     const target = path.join(path.resolve(worktreePath), hostRuntimeContractPath);
@@ -17,7 +29,7 @@ export async function loadHostRuntimeContract(worktreePath) {
     }
     catch (error) {
         if (isFileNotFound(error))
-            return { contract: defaultHostRuntimeContract(), source: "default" };
+            return await discoverHostRuntimeContract(worktreePath);
         throw error;
     }
     if (!targetStat.isFile() || targetStat.size < 1 || targetStat.size > maximumContractBytes) {
@@ -33,6 +45,382 @@ export async function loadHostRuntimeContract(worktreePath) {
         source: "project",
     };
 }
+async function discoverHostRuntimeContract(worktreePath) {
+    const root = path.resolve(worktreePath);
+    const [nodeDiscovery, aspNetDiscovery] = await Promise.all([
+        discoverNodeRuntimes(root),
+        discoverAspNetRuntimes(root),
+    ]);
+    if (nodeDiscovery.ambiguous || aspNetDiscovery.ambiguous) {
+        return ambiguousRuntimeDiscovery();
+    }
+    const candidates = [...nodeDiscovery.candidates, ...aspNetDiscovery.candidates];
+    if (candidates.length === 1) {
+        const candidate = candidates[0];
+        return {
+            contract: candidate.contract,
+            source: "derived",
+            discovery: {
+                status: "derived",
+                reasonCode: candidate.reasonCode,
+                summary: candidate.summary,
+                candidateFingerprint: candidate.candidateFingerprint,
+            },
+        };
+    }
+    if (candidates.length === 2
+        && candidates.some(candidate => candidate.kind === "browser")
+        && candidates.some(candidate => candidate.kind === "api")
+        && candidates.find(candidate => candidate.kind === "browser")?.contract.runtime.playwright !== null) {
+        const browser = candidates.find(candidate => candidate.kind === "browser");
+        const api = candidates.find(candidate => candidate.kind === "api");
+        const combined = combineBrowserAndApiRuntime(browser, api);
+        return {
+            contract: combined.contract,
+            source: "derived",
+            discovery: {
+                status: "derived",
+                reasonCode: combined.reasonCode,
+                summary: combined.summary,
+                candidateFingerprint: combined.candidateFingerprint,
+            },
+        };
+    }
+    if (candidates.length > 1) {
+        return ambiguousRuntimeDiscovery();
+    }
+    return {
+        contract: defaultHostRuntimeContract(),
+        source: "default",
+        discovery: {
+            status: "unsupported",
+            reasonCode: "runtime_discovery_unsupported",
+            summary: "Forge did not find one deterministic supported application entrypoint; host application runs remain serialized.",
+        },
+    };
+}
+async function discoverNodeRuntimes(root) {
+    const manifests = [...new Set([
+            path.join(root, "package.json"),
+            ...await findFiles(root, file => path.basename(file).toLowerCase() === "package.json", 4, 500),
+        ])];
+    const candidates = (await Promise.all(manifests.map(async (manifestPath) => await discoverNodeRuntime(root, manifestPath)))).filter((candidate) => candidate !== null);
+    return { candidates: candidates.length === 1 ? candidates : [], ambiguous: candidates.length > 1 };
+}
+async function discoverNodeRuntime(root, manifestPath) {
+    const source = await readBoundedOptionalFile(manifestPath, 256 * 1024);
+    if (source === null)
+        return null;
+    let manifest;
+    try {
+        manifest = JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+    const scripts = objectOrEmpty(manifest.scripts);
+    const dependencies = { ...objectOrEmpty(manifest.dependencies), ...objectOrEmpty(manifest.devDependencies) };
+    const dev = typeof scripts.dev === "string" ? scripts.dev.trim() : "";
+    const start = typeof scripts.start === "string" ? scripts.start.trim() : "";
+    const scriptName = dev ? "dev" : start ? "start" : null;
+    const script = scriptName ? String(scripts[scriptName]).trim() : "";
+    if (!scriptName || !script || script.length > 1024 || /(?:&&|\|\||;|\n|\r)/u.test(script))
+        return null;
+    const vite = Object.hasOwn(dependencies, "vite") || /(^|\s)vite(?:\s|$)/u.test(script);
+    const next = Object.hasOwn(dependencies, "next") || /(^|\s)next(?:\s|$)/u.test(script);
+    if (vite === next)
+        return null;
+    const packageManager = await nearestPackageManager(root, path.dirname(manifestPath));
+    if (!packageManager)
+        return null;
+    const adapter = vite ? "vite" : "next";
+    const playwrightConfigs = [...new Set((await Promise.all([
+            ...["playwright.config.ts", "playwright.config.js", "playwright.config.mjs", "playwright.config.cjs"]
+                .flatMap(file => [file, `e2e/${file}`, `tests/e2e/${file}`])
+                .map(async (candidate) => await optionalFileExists(path.join(root, candidate)) ? path.join(root, candidate) : null),
+            findFiles(root, file => /^playwright\.config\.(?:ts|js|mjs|cjs)$/iu.test(path.basename(file)), 4, 2_000),
+        ])).flat().filter((value) => value !== null))]
+        .map(config => portableRelativePath(root, config));
+    const playwright = playwrightConfigs.length === 1
+        ? { config: playwrightConfigs[0], baseUrlPort: "web", workers: 1 }
+        : null;
+    const workingDirectory = portableRelativePath(root, path.dirname(manifestPath)) || ".";
+    const contract = {
+        schemaVersion: 1,
+        runtime: {
+            hostConcurrency: "parallel",
+            ports: [{
+                    name: "web",
+                    adapter,
+                    launch: {
+                        command: packageManager,
+                        args: packageManager === "npm" ? ["run", scriptName, "--"] : ["run", scriptName],
+                        workingDirectory,
+                    },
+                    env: "PORT",
+                    baseUrlEnv: "APP_BASE_URL",
+                    format: "http://{host}:{port}",
+                }],
+            playwright,
+            browserProfile: "isolated",
+            singletonResources: [],
+        },
+    };
+    return {
+        kind: "browser",
+        contract,
+        reasonCode: `runtime_discovery_${adapter}`,
+        summary: `Forge derived one ${adapter === "vite" ? "Vite" : "Next.js"} application entrypoint from package.json.`,
+        candidateFingerprint: detectorFingerprint({
+            manifest: portableRelativePath(root, manifestPath),
+            source,
+            packageManager,
+            scriptName,
+            script,
+            adapter,
+            playwrightConfigs,
+        }),
+    };
+}
+async function discoverAspNetRuntimes(root) {
+    const projects = await findFiles(root, file => file.toLowerCase().endsWith(".csproj"), 3, 200);
+    const webProjects = [];
+    for (const projectPath of projects) {
+        const source = await readBoundedOptionalFile(projectPath, 512 * 1024);
+        if (source && /<Project\s+Sdk=["']Microsoft\.NET\.Sdk\.Web["']/iu.test(source)) {
+            webProjects.push({ relativePath: path.relative(root, projectPath).replaceAll("\\", "/"), source });
+        }
+    }
+    if (webProjects.length !== 1)
+        return { candidates: [], ambiguous: webProjects.length > 1 };
+    const project = webProjects[0];
+    const launchProfile = await discoverAspNetLaunchProfile(root, project.relativePath);
+    const contract = {
+        schemaVersion: 1,
+        runtime: {
+            hostConcurrency: "parallel",
+            ports: [{
+                    name: "web",
+                    adapter: "aspnetcore",
+                    launch: {
+                        command: "dotnet",
+                        args: ["run", "--project", project.relativePath],
+                        workingDirectory: ".",
+                        ...(Object.keys(launchProfile.environment).length > 0
+                            ? { environment: launchProfile.environment }
+                            : {}),
+                    },
+                    env: "ASPNETCORE_URLS",
+                    baseUrlEnv: "APP_BASE_URL",
+                    format: "http://{host}:{port}",
+                }],
+            playwright: null,
+            browserProfile: "isolated",
+            singletonResources: [],
+        },
+    };
+    return { candidates: [{
+                kind: "api",
+                contract,
+                reasonCode: "runtime_discovery_aspnetcore",
+                summary: "Forge derived one ASP.NET Core application entrypoint from the repository project metadata.",
+                candidateFingerprint: detectorFingerprint({
+                    project: project.relativePath,
+                    source: project.source,
+                    launchSettings: launchProfile.source,
+                    launchProfile: launchProfile.name,
+                }),
+            }], ambiguous: false };
+}
+function combineBrowserAndApiRuntime(browser, api) {
+    const browserPort = browser.contract.runtime.ports.find(port => port.launch !== null);
+    const apiPort = api.contract.runtime.ports.find(port => port.launch !== null);
+    const combinedBrowserPort = {
+        ...browserPort,
+        name: "web",
+        env: "WEB_PORT",
+        baseUrlEnv: "WEB_BASE_URL",
+        launch: browserPort.launch ? {
+            ...browserPort.launch,
+            environment: {
+                ...browserPort.launch.environment,
+                FORGE_API_PROXY_TARGET: "${FORGE_API_URL}",
+                FORGE_DEV_PUBLIC_ORIGIN: "${FORGE_RUNTIME_BASE_URL}",
+            },
+        } : null,
+    };
+    const combinedApiPort = {
+        ...apiPort,
+        name: "api",
+        env: "ASPNETCORE_URLS",
+        baseUrlEnv: "API_BASE_URL",
+    };
+    return {
+        kind: "browser",
+        contract: {
+            schemaVersion: 1,
+            runtime: {
+                hostConcurrency: "parallel",
+                ports: [combinedApiPort, combinedBrowserPort],
+                playwright: browser.contract.runtime.playwright
+                    ? { ...browser.contract.runtime.playwright, baseUrlPort: "web" }
+                    : null,
+                browserProfile: "isolated",
+                singletonResources: [],
+            },
+        },
+        reasonCode: "runtime_discovery_full_stack",
+        summary: "Forge derived one supervised API and browser application pair from repository metadata.",
+        candidateFingerprint: detectorFingerprint({
+            browser: browser.candidateFingerprint,
+            api: api.candidateFingerprint,
+        }),
+    };
+}
+function ambiguousRuntimeDiscovery() {
+    return {
+        contract: defaultHostRuntimeContract(),
+        source: "default",
+        discovery: {
+            status: "ambiguous",
+            reasonCode: "runtime_discovery_multiple_applications",
+            summary: "Forge found more than one supported application entrypoint, so host application runs remain serialized.",
+        },
+    };
+}
+async function nearestPackageManager(root, start) {
+    let directory = path.resolve(start);
+    const resolvedRoot = path.resolve(root);
+    while (directory === resolvedRoot || directory.startsWith(`${resolvedRoot}${path.sep}`)) {
+        const lockfiles = (await Promise.all([
+            optionalFileExists(path.join(directory, "pnpm-lock.yaml")).then(exists => exists ? "pnpm" : null),
+            optionalFileExists(path.join(directory, "yarn.lock")).then(exists => exists ? "yarn" : null),
+            optionalFileExists(path.join(directory, "package-lock.json")).then(exists => exists ? "npm" : null),
+            optionalFileExists(path.join(directory, "npm-shrinkwrap.json")).then(exists => exists ? "npm" : null),
+        ])).filter((value) => value !== null);
+        const packageManagers = [...new Set(lockfiles)];
+        if (packageManagers.length > 1)
+            return null;
+        if (packageManagers.length === 1)
+            return packageManagers[0];
+        if (directory === resolvedRoot)
+            break;
+        directory = path.dirname(directory);
+    }
+    return "npm";
+}
+function portableRelativePath(root, target) {
+    return path.relative(root, target).replaceAll("\\", "/");
+}
+async function discoverAspNetLaunchProfile(root, projectRelativePath) {
+    const target = path.join(root, path.dirname(projectRelativePath), "Properties", "launchSettings.json");
+    const source = await readBoundedOptionalFile(target, 512 * 1024);
+    if (!source)
+        return { name: null, source: null, environment: {} };
+    try {
+        const document = objectOrEmpty(JSON.parse(source));
+        const profiles = objectOrEmpty(document.profiles);
+        const candidates = Object.entries(profiles)
+            .map(([name, value]) => ({ name, profile: objectOrEmpty(value) }))
+            .filter(candidate => String(candidate.profile.commandName ?? "").toLowerCase() === "project")
+            .sort((left, right) => aspNetProfilePriority(left.name) - aspNetProfilePriority(right.name)
+            || left.name.localeCompare(right.name));
+        const selected = candidates[0];
+        if (!selected)
+            return { name: null, source, environment: {} };
+        const environmentVariables = objectOrEmpty(selected.profile.environmentVariables);
+        const environment = Object.fromEntries(Object.entries(environmentVariables)
+            .filter((entry) => safeAspNetLaunchEnvironment(entry[0], entry[1]))
+            .sort(([left], [right]) => left.localeCompare(right))
+            .slice(0, 64));
+        return { name: selected.name, source, environment };
+    }
+    catch {
+        return { name: null, source, environment: {} };
+    }
+}
+function aspNetProfilePriority(name) {
+    if (name.toLowerCase() === "http")
+        return 0;
+    if (name.toLowerCase() === "https")
+        return 1;
+    return 2;
+}
+function safeAspNetLaunchEnvironment(name, value) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u.test(name)
+        || typeof value !== "string"
+        || value.length === 0
+        || value.length > 8192)
+        return false;
+    const normalized = name.toUpperCase();
+    return !normalized.startsWith("FORGE_")
+        && !new Set([
+            "ASPNETCORE_URLS",
+            "ASPNETCORE_HTTP_PORTS",
+            "ASPNETCORE_HTTPS_PORTS",
+            "DOTNET_URLS",
+            "HOST",
+            "PORT",
+            "PATH",
+            "HOME",
+            "TMP",
+            "TEMP",
+            "TMPDIR",
+        ]).has(normalized);
+}
+async function findFiles(root, accepts, maximumDepth, maximumEntries) {
+    const results = [];
+    let examined = 0;
+    const visitDirectory = async (directory, depth) => {
+        if (depth > maximumDepth || examined >= maximumEntries)
+            return;
+        const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (examined++ >= maximumEntries)
+                return;
+            if (entry.isDirectory() && ignoredDiscoveryDirectories.has(entry.name.toLowerCase()))
+                continue;
+            const target = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await visitDirectory(target, depth + 1);
+            else if (entry.isFile() && accepts(target))
+                results.push(target);
+        }
+    };
+    await visitDirectory(root, 0);
+    return results.sort((left, right) => left.localeCompare(right));
+}
+async function readBoundedOptionalFile(target, maximumBytes) {
+    try {
+        const stat = await fs.stat(target);
+        if (!stat.isFile() || stat.size < 1 || stat.size > maximumBytes)
+            return null;
+        return await fs.readFile(target, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return null;
+        throw error;
+    }
+}
+async function optionalFileExists(target) {
+    try {
+        return (await fs.stat(target)).isFile();
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return false;
+        throw error;
+    }
+}
+function objectOrEmpty(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function detectorFingerprint(value) {
+    return `sha256:${createHash("sha256").update(JSON.stringify({ adapterVersion: 2, value })).digest("hex")}`;
+}
 export function defaultHostRuntimeContract() {
     return {
         schemaVersion: 1,
@@ -162,9 +550,6 @@ function parsePorts(value) {
         }
         return { name, adapter, launch, env, baseUrlEnv, format };
     });
-    if (parsed.filter(port => port.launch !== null).length > 1) {
-        throw new Error("runtime_contract_invalid: only one project launch command is currently supported.");
-    }
     return parsed;
 }
 function parsePortAdapter(value, name) {
@@ -192,7 +577,27 @@ function parseLaunch(value, adapter, name) {
     const portableDirectory = launch.workingDirectory === undefined || launch.workingDirectory === null
         ? "."
         : containedPortablePath(launch.workingDirectory, `runtime.ports.${name}.launch.workingDirectory`);
-    return { command, args: parsedArgs, workingDirectory: portableDirectory };
+    const environment = parseLaunchEnvironment(launch.environment, name);
+    return {
+        command,
+        args: parsedArgs,
+        workingDirectory: portableDirectory,
+        ...(environment ? { environment } : {}),
+    };
+}
+function parseLaunchEnvironment(value, portName) {
+    if (value === undefined || value === null)
+        return undefined;
+    const environment = object(value, `runtime.ports.${portName}.launch.environment`);
+    if (Object.keys(environment).length > 64) {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${portName}.launch.environment cannot contain more than 64 entries.`);
+    }
+    return Object.fromEntries(Object.entries(environment).map(([name, raw]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u.test(name)) {
+            throw new Error(`runtime_contract_invalid: launch environment name '${name}' is invalid.`);
+        }
+        return [name, boundedString(raw, 8192, `runtime.ports.${portName}.launch.environment.${name}`)];
+    }));
 }
 function containedPortablePath(value, label) {
     const original = boundedString(value, 1024, label);

package/dist/runtime/host-runtime-lease.d.ts

@@ -13,7 +13,9 @@ export interface HostRuntimeLeaseStart {
     readonly lease: RuntimeIsolationLease;
     readonly environment: Readonly<Record<string, string>>;
     readonly runtimeContract: LoadedHostRuntimeContract;
+    readonly executionClass: HostRuntimeExecutionClass;
 }
+export type HostRuntimeExecutionClass = "analysis_only" | "managed_runtime";
 export type HostRuntimeSafetyClass = "host_serial_only" | "host_parallel_candidate" | "host_parallel_safe";
 export interface HostRuntimeProjectCapacitySnapshot {
     readonly repoId: string;
@@ -22,6 +24,9 @@ export interface HostRuntimeProjectCapacitySnapshot {
     readonly reservedAttempts: number;
     readonly waitingAttempts: number;
     readonly degradedAttempts: number;
+    readonly runtimeContractFingerprint?: string | null;
+    readonly runtimeContractSource?: "project" | "derived" | null;
+    readonly promotedAt?: string | null;
 }
 export interface HostRuntimeCapacitySnapshot {
     readonly activeAttempts: number;
@@ -52,7 +57,9 @@ export interface HostRuntimeLeaseRuntime {
     start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
     startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
     updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
+    providerProcessRunner?(dispatchAttemptId: string, fencingToken: string): ProviderProcessRunner | null;
     release(dispatchAttemptId: string, fencingToken: string): Promise<RuntimeIsolationLease | null>;
+    invalidatePromotion?(repoId: string): Promise<void>;
     reap?(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
     snapshot?(): HostRuntimeCapacitySnapshot;
 }
@@ -72,6 +79,7 @@ export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime
     private readonly parallelProjectOwners;
     private readonly parallelProjectWaiters;
     private readonly degraded;
+    private readonly knownPromotions;
     private readonly portBroker;
     private readonly nodeAdapter;
     constructor(stateRoot: string, portBroker?: HostPortBroker, nodeAdapter?: NodeHostRuntimeAdapter, processSupervisors?: AttemptProcessSupervisorRegistry, processRunner?: ProviderProcessRunner, listenerInspector?: HostListenerInspector, promotionStore?: HostParallelPromotionStore, playwrightAdapter?: PlaywrightHostRuntimeAdapter, processRecovery?: HostProcessRecovery);
@@ -83,6 +91,7 @@ export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime
     start(dispatch: RunOnceDispatchPacket, worktreePath: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
     updateLease(dispatchAttemptId: string, fencingToken: string, expiresAt: string): Promise<void>;
     startConfiguredProject(dispatchAttemptId: string, fencingToken: string, signal?: AbortSignal): Promise<HostRuntimeLeaseStart>;
+    providerProcessRunner(dispatchAttemptId: string, fencingToken: string): ProviderProcessRunner | null;
     private promoteVerifiedRuntime;
     launchNodeRuntime<T>(dispatchAttemptId: string, fencingToken: string, portName: string, command: NodeRuntimeCommand, launcher: NodeRuntimeCommandLauncher<T>, signal?: AbortSignal): Promise<HostNodeRuntimeLaunch<T>>;
     release(dispatchAttemptId: string, fencingToken: string): Promise<RuntimeIsolationLease | null>;
@@ -109,6 +118,8 @@ export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime
     private cancelAdmissionWaiters;
     private drainSingletonWaiters;
     private drainParallelProjectWaiters;
+    private refreshKnownPromotions;
+    invalidatePromotion(repoId: string): Promise<void>;
     private drainAdmissionWaiters;
 }
 export declare class HostRuntimeLeaseCleanupError extends Error {
@@ -118,5 +129,5 @@ export declare class HostRuntimeLeaseCleanupError extends Error {
 export declare class HostRuntimeAdmissionExpiredError extends Error {
     constructor();
 }
-export declare function hostRuntimeEventResources(lease: RuntimeIsolationLease, runtimeContract?: LoadedHostRuntimeContract): Record<string, unknown>;
+export declare function hostRuntimeEventResources(lease: RuntimeIsolationLease, runtimeContract?: LoadedHostRuntimeContract, executionClass?: HostRuntimeExecutionClass): Record<string, unknown>;
 export declare function hostRuntimeSingletonKeys(dispatch: RunOnceDispatchPacket): readonly string[];