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

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

@@ -0,0 +1,295 @@
+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 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 playwrightKeys = new Set(["config", "baseUrlPort", "workers"]);
+export async function loadHostRuntimeContract(worktreePath) {
+    const target = path.join(path.resolve(worktreePath), hostRuntimeContractPath);
+    let targetStat;
+    try {
+        targetStat = await fs.stat(target);
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return { contract: defaultHostRuntimeContract(), source: "default" };
+        throw error;
+    }
+    if (!targetStat.isFile() || targetStat.size < 1 || targetStat.size > maximumContractBytes) {
+        throw new Error(`runtime_contract_invalid: forge.runtime.yml must be a regular 1-${maximumContractBytes} byte file.`);
+    }
+    const [realWorktree, realTarget] = await Promise.all([fs.realpath(worktreePath), fs.realpath(target)]);
+    const relative = path.relative(realWorktree, realTarget);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("runtime_contract_invalid: forge.runtime.yml must remain inside the prepared worktree.");
+    }
+    return {
+        contract: validateHostRuntimeContract(await fs.readFile(realTarget, "utf8")),
+        source: "project",
+    };
+}
+export function defaultHostRuntimeContract() {
+    return {
+        schemaVersion: 1,
+        runtime: {
+            hostConcurrency: "serial",
+            ports: [],
+            playwright: null,
+            browserProfile: "isolated",
+            singletonResources: [],
+        },
+    };
+}
+export function validateHostRuntimeContract(source) {
+    const byteLength = Buffer.byteLength(source, "utf8");
+    if (byteLength === 0 || byteLength > maximumContractBytes) {
+        throw new Error(`runtime_contract_invalid: forge.runtime.yml must be 1-${maximumContractBytes} bytes.`);
+    }
+    if (Array.from(source).some(character => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint === 127 || (codePoint < 32 && codePoint !== 9 && codePoint !== 10 && codePoint !== 13);
+    })) {
+        throw new Error("runtime_contract_invalid: control characters are not allowed.");
+    }
+    const document = parseDocument(source, { uniqueKeys: true, prettyErrors: false, strict: true });
+    if (document.errors.length > 0) {
+        throw new Error(`runtime_contract_invalid: ${document.errors[0]?.message ?? "invalid YAML"}`);
+    }
+    visit(document, {
+        Node(_key, node) {
+            if (isAlias(node) || node.anchor) {
+                throw new Error("runtime_contract_invalid: YAML aliases and anchors are not allowed.");
+            }
+        },
+    });
+    const parsed = document.toJS({ maxAliasCount: 0 });
+    assertDepth(parsed, 0);
+    const root = object(parsed, "contract");
+    rejectUnknownKeys(root, topLevelKeys, "contract");
+    if (root.schemaVersion !== 1)
+        throw new Error("runtime_contract_invalid: schemaVersion must be 1.");
+    const runtime = object(root.runtime, "runtime");
+    rejectUnknownKeys(runtime, runtimeKeys, "runtime");
+    const hostConcurrency = runtime.hostConcurrency ?? "serial";
+    if (hostConcurrency !== "serial" && hostConcurrency !== "parallel" && hostConcurrency !== "disabled") {
+        throw new Error("runtime_contract_invalid: runtime.hostConcurrency must be serial, parallel, or disabled.");
+    }
+    const browserProfile = runtime.browserProfile ?? "isolated";
+    if (browserProfile !== "isolated") {
+        throw new Error("runtime_contract_invalid: runtime.browserProfile must be isolated.");
+    }
+    const ports = parsePorts(runtime.ports);
+    return {
+        schemaVersion: 1,
+        runtime: {
+            hostConcurrency,
+            ports,
+            playwright: parsePlaywright(runtime.playwright, ports),
+            browserProfile,
+            singletonResources: parseSingletonResources(runtime.singletonResources),
+        },
+    };
+}
+function parsePlaywright(value, ports) {
+    if (value === undefined || value === null)
+        return null;
+    const playwright = object(value, "runtime.playwright");
+    rejectUnknownKeys(playwright, playwrightKeys, "runtime.playwright");
+    const config = containedPortablePath(playwright.config, "runtime.playwright.config");
+    const baseUrlPort = requiredString(playwright.baseUrlPort, "runtime.playwright.baseUrlPort");
+    const port = ports.find(entry => entry.name === baseUrlPort);
+    if (!port?.launch || !port.baseUrlEnv || !port.format) {
+        throw new Error("runtime_contract_invalid: runtime.playwright.baseUrlPort must reference a launched HTTP port.");
+    }
+    const workers = playwright.workers === undefined || playwright.workers === null ? 1 : playwright.workers;
+    if (!Number.isSafeInteger(workers) || workers < 1 || workers > 16) {
+        throw new Error("runtime_contract_invalid: runtime.playwright.workers must be an integer between 1 and 16.");
+    }
+    return { config, baseUrlPort, workers: workers };
+}
+export function hostPortEnvironment(config, hostIp, hostPort) {
+    if (!Number.isSafeInteger(hostPort) || hostPort < 1 || hostPort > 65535) {
+        throw new Error("runtime_contract_invalid: assigned host port must be valid.");
+    }
+    const baseUrl = config.format
+        ?.replaceAll("{host}", hostIp)
+        .replaceAll("{port}", String(hostPort));
+    const environment = {
+        [config.env]: config.adapter === "aspnetcore" && baseUrl ? baseUrl : String(hostPort),
+    };
+    if (config.baseUrlEnv && config.format) {
+        environment[config.baseUrlEnv] = baseUrl;
+    }
+    return environment;
+}
+function parsePorts(value) {
+    if (value === undefined || value === null)
+        return [];
+    const ports = object(value, "runtime.ports");
+    if (Object.keys(ports).length > 16) {
+        throw new Error("runtime_contract_invalid: runtime.ports cannot contain more than 16 entries.");
+    }
+    const environmentNames = new Set();
+    const parsed = Object.entries(ports).sort(([left], [right]) => left.localeCompare(right)).map(([name, raw]) => {
+        if (!/^[a-z][a-z0-9_-]{0,63}$/u.test(name)) {
+            throw new Error(`runtime_contract_invalid: port name '${name}' is invalid.`);
+        }
+        const port = object(raw, `runtime.ports.${name}`);
+        rejectUnknownKeys(port, portKeys, `runtime.ports.${name}`);
+        const adapter = parsePortAdapter(port.adapter, name);
+        const launch = parseLaunch(port.launch, adapter, name);
+        const env = environmentName(port.env, `runtime.ports.${name}.env`);
+        if (adapter === "aspnetcore" && env !== "ASPNETCORE_URLS") {
+            throw new Error(`runtime_contract_invalid: runtime.ports.${name}.env must be ASPNETCORE_URLS for the aspnetcore adapter.`);
+        }
+        const baseUrlEnv = port.baseUrlEnv === undefined || port.baseUrlEnv === null
+            ? null
+            : environmentName(port.baseUrlEnv, `runtime.ports.${name}.baseUrlEnv`);
+        if (environmentNames.has(env) || (baseUrlEnv !== null && environmentNames.has(baseUrlEnv)) || env === baseUrlEnv) {
+            throw new Error("runtime_contract_invalid: port environment names must be unique.");
+        }
+        environmentNames.add(env);
+        if (baseUrlEnv)
+            environmentNames.add(baseUrlEnv);
+        const format = parseFormat(port.format, baseUrlEnv, name);
+        if (launch && (!baseUrlEnv || !format)) {
+            throw new Error(`runtime_contract_invalid: runtime.ports.${name}.launch requires an HTTP baseUrlEnv and format.`);
+        }
+        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) {
+    if (value === undefined || value === null)
+        return null;
+    if (value !== "node" && value !== "vite" && value !== "next" && value !== "aspnetcore") {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${name}.adapter must be node, vite, next, or aspnetcore.`);
+    }
+    return value;
+}
+function parseLaunch(value, adapter, name) {
+    if (value === undefined || value === null)
+        return null;
+    if (!adapter) {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${name}.launch requires an explicit adapter.`);
+    }
+    const launch = object(value, `runtime.ports.${name}.launch`);
+    rejectUnknownKeys(launch, launchKeys, `runtime.ports.${name}.launch`);
+    const command = boundedString(launch.command, 1024, `runtime.ports.${name}.launch.command`);
+    const args = launch.args === undefined || launch.args === null ? [] : launch.args;
+    if (!Array.isArray(args) || args.length > 128) {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${name}.launch.args must contain at most 128 strings.`);
+    }
+    const parsedArgs = args.map((argument, index) => boundedString(argument, 4096, `runtime.ports.${name}.launch.args[${index}]`));
+    const portableDirectory = launch.workingDirectory === undefined || launch.workingDirectory === null
+        ? "."
+        : containedPortablePath(launch.workingDirectory, `runtime.ports.${name}.launch.workingDirectory`);
+    return { command, args: parsedArgs, workingDirectory: portableDirectory };
+}
+function containedPortablePath(value, label) {
+    const original = boundedString(value, 1024, label);
+    const portable = original.replaceAll("\\", "/");
+    if (path.posix.isAbsolute(portable)
+        || path.win32.isAbsolute(original)
+        || portable.split("/").some(segment => segment === "..")) {
+        throw new Error(`runtime_contract_invalid: ${label} must stay inside the worktree.`);
+    }
+    return portable;
+}
+function parseFormat(value, baseUrlEnv, name) {
+    if (baseUrlEnv === null) {
+        if (value !== undefined && value !== null) {
+            throw new Error(`runtime_contract_invalid: runtime.ports.${name}.format requires baseUrlEnv.`);
+        }
+        return null;
+    }
+    const format = value === undefined || value === null ? "http://{host}:{port}" : requiredString(value, `runtime.ports.${name}.format`);
+    if (format.length > 512 || !format.includes("{port}")) {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${name}.format must include {port}.`);
+    }
+    const rendered = format.replaceAll("{host}", "127.0.0.1").replaceAll("{port}", "12345");
+    let url;
+    try {
+        url = new URL(rendered);
+    }
+    catch {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${name}.format must produce a URL.`);
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.hostname !== "127.0.0.1" || url.port !== "12345") {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${name}.format must produce an HTTP loopback URL using the assigned port.`);
+    }
+    return format;
+}
+function parseSingletonResources(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.length > 32 || value.some(entry => typeof entry !== "string")) {
+        throw new Error("runtime_contract_invalid: runtime.singletonResources must be a string array with at most 32 entries.");
+    }
+    const resources = value.map((entry, index) => {
+        const resource = requiredString(entry, `runtime.singletonResources[${index}]`).toLowerCase();
+        if (!/^[a-z][a-z0-9_.:-]{0,127}$/u.test(resource)) {
+            throw new Error(`runtime_contract_invalid: singleton resource '${resource}' is invalid.`);
+        }
+        return resource;
+    });
+    if (new Set(resources).size !== resources.length) {
+        throw new Error("runtime_contract_invalid: runtime.singletonResources cannot contain duplicates.");
+    }
+    return resources.sort((left, right) => left.localeCompare(right));
+}
+function environmentName(value, label) {
+    const name = requiredString(value, label);
+    if (!/^[A-Z_][A-Z0-9_]{0,127}$/u.test(name) || name.startsWith("FORGE_") || name === "PATH" || name === "HOME") {
+        throw new Error(`runtime_contract_invalid: ${label} is reserved or invalid.`);
+    }
+    return name;
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`runtime_contract_invalid: ${label} must be an object.`);
+    }
+    return value;
+}
+function rejectUnknownKeys(value, allowed, label) {
+    const unknown = Object.keys(value).find(key => !allowed.has(key));
+    if (unknown)
+        throw new Error(`runtime_contract_invalid: unknown ${label} key '${unknown}'.`);
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`runtime_contract_invalid: ${label} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function boundedString(value, maximumLength, label) {
+    const text = requiredString(value, label);
+    if (text.length > maximumLength || Array.from(text).some(character => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint < 32 || codePoint === 127;
+    })) {
+        throw new Error(`runtime_contract_invalid: ${label} is too long or contains control characters.`);
+    }
+    return text;
+}
+function assertDepth(value, depth) {
+    if (depth > maximumDepth)
+        throw new Error(`runtime_contract_invalid: YAML nesting exceeds ${maximumDepth}.`);
+    if (Array.isArray(value)) {
+        value.forEach(entry => assertDepth(entry, depth + 1));
+    }
+    else if (value && typeof value === "object") {
+        Object.values(value).forEach(entry => assertDepth(entry, depth + 1));
+    }
+}
+function isFileNotFound(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

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

@@ -0,0 +1,122 @@
+import type { RunOnceDispatchPacket } from "../session/session.types.js";
+import { type ProviderProcessRunner } from "../session/provider-cli/provider-cli.process.js";
+import { type RuntimeIsolationLease } from "./runtime-isolation-lease.js";
+import { type LoadedHostRuntimeContract } from "./host-runtime-contract.js";
+import { HostPortBroker } from "./host-port-broker.js";
+import { NodeHostRuntimeAdapter, type NodeRuntimeAdapterLaunch, type NodeRuntimeCommand, type NodeRuntimeCommandLauncher } from "./node-host-runtime-adapter.js";
+import { AttemptProcessSupervisorRegistry } from "./attempt-process-supervisor-registry.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import { PlaywrightHostRuntimeAdapter } from "./playwright-host-runtime-adapter.js";
+import { HostParallelPromotionStore } from "./host-runtime-promotion.js";
+import { type HostProcessRecovery } from "../shared/process/host-process-recovery.js";
+export interface HostRuntimeLeaseStart {
+    readonly lease: RuntimeIsolationLease;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly runtimeContract: LoadedHostRuntimeContract;
+}
+export type HostRuntimeSafetyClass = "host_serial_only" | "host_parallel_candidate" | "host_parallel_safe";
+export interface HostRuntimeProjectCapacitySnapshot {
+    readonly repoId: string;
+    readonly safetyClass: HostRuntimeSafetyClass;
+    readonly activeAttempts: number;
+    readonly reservedAttempts: number;
+    readonly waitingAttempts: number;
+    readonly degradedAttempts: number;
+}
+export interface HostRuntimeCapacitySnapshot {
+    readonly activeAttempts: number;
+    readonly reservedAttempts: number;
+    readonly waitingAttempts: number;
+    readonly degradedAttempts: number;
+    readonly exclusiveReservations: number;
+    readonly sharedReservations: number;
+    readonly projects: readonly HostRuntimeProjectCapacitySnapshot[];
+}
+export interface HostRuntimeReapOptions {
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly nowMs?: number;
+}
+export interface HostRuntimeReapReport {
+    readonly examined: number;
+    readonly reaped: number;
+    readonly processesTerminated: number;
+    readonly reusedPidsProtected: number;
+    readonly degraded: number;
+}
+export interface HostNodeRuntimeLaunch<T> extends NodeRuntimeAdapterLaunch<T> {
+    readonly runtimeLease: RuntimeIsolationLease;
+}
+export interface HostRuntimeLeaseRuntime {
+    acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    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>;
+    release(dispatchAttemptId: string, fencingToken: string): Promise<RuntimeIsolationLease | null>;
+    reap?(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
+    snapshot?(): HostRuntimeCapacitySnapshot;
+}
+export declare class HostRuntimeLeaseManager implements HostRuntimeLeaseRuntime {
+    private readonly stateRoot;
+    private readonly processSupervisors;
+    private readonly processRunner;
+    private readonly listenerInspector;
+    private readonly promotionStore;
+    private readonly playwrightAdapter;
+    private readonly processRecovery;
+    private readonly active;
+    private readonly pendingRenewals;
+    private readonly admissions;
+    private readonly singletonOwners;
+    private readonly singletonWaiters;
+    private readonly parallelProjectOwners;
+    private readonly parallelProjectWaiters;
+    private readonly degraded;
+    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);
+    reap(options: HostRuntimeReapOptions): Promise<HostRuntimeReapReport>;
+    snapshot(): HostRuntimeCapacitySnapshot;
+    acquire(dispatch: RunOnceDispatchPacket, signal?: AbortSignal): Promise<readonly string[]>;
+    private reserveSingletonKeys;
+    private reserveParallelProject;
+    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>;
+    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>;
+    private readLedgers;
+    private recoverPersistedProcesses;
+    private markLedgerDegraded;
+    private rememberDegraded;
+    private forgetDegraded;
+    private attemptRoot;
+    private writeLedger;
+    private ledgerPath;
+    private singletonKeysAvailable;
+    private assignSingletonKeys;
+    private releaseSingletonKeys;
+    private convertSingletonToParallelProject;
+    private parallelProjectOwned;
+    private parallelProjectAvailable;
+    private assignParallelProject;
+    private releaseParallelProjectNoDrain;
+    private releaseParallelProjects;
+    private deleteAdmission;
+    private renewAdmissionWaiterDeadline;
+    private clearPendingRenewal;
+    private cancelAdmissionWaiters;
+    private drainSingletonWaiters;
+    private drainParallelProjectWaiters;
+    private drainAdmissionWaiters;
+}
+export declare class HostRuntimeLeaseCleanupError extends Error {
+    readonly lease: RuntimeIsolationLease;
+    constructor(lease: RuntimeIsolationLease, cause: unknown);
+}
+export declare class HostRuntimeAdmissionExpiredError extends Error {
+    constructor();
+}
+export declare function hostRuntimeEventResources(lease: RuntimeIsolationLease, runtimeContract?: LoadedHostRuntimeContract): Record<string, unknown>;
+export declare function hostRuntimeSingletonKeys(dispatch: RunOnceDispatchPacket): readonly string[];