@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

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

@@ -0,0 +1,813 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isAlias, parseDocument, visit } from "yaml";
+import { readCanonicalSourceFile } from "./canonical-source-file.js";
+import { isGeneratedOutputDirectoryName } from "./generated-output-reset.js";
+export const hostRuntimeContractPath = ".forge/forge.runtime.yml";
+export const hostRuntimeTestPostgresAdminEnvironment = "FORGE_TEST_POSTGRES_ADMIN_CONNECTION_STRING";
+export const hostRuntimeLegacyTestPostgresEnvironment = "FORGE_TEST_POSTGRES_CONNECTION_STRING";
+const maximumContractBytes = 64 * 1024;
+const maximumDepth = 12;
+// Every discovery scan stops after this many directory entries. A monorepo needs a few
+// thousand; the bound only keeps a pathological tree from stalling attempt preparation.
+const maximumDiscoveryEntries = 20_000;
+/**
+ * A discovery scan reached its entry budget before seeing the whole tree, so what it did not
+ * find may still exist. Discovery must not treat that as absence: a partial runtime (for
+ * example a web app without its API) would send the attempt's traffic to the wrong server.
+ */
+class IncompleteRuntimeDiscoveryError extends Error {
+}
+// Dependency, build and editor folders never hold an application entrypoint, and counting
+// them would exhaust the budget and serialize a repository for no reason.
+const ignoredDiscoveryDirectories = new Set([
+    ".forge",
+    ".forge-designer",
+    ".git",
+    ".gradle",
+    ".idea",
+    ".local",
+    ".next",
+    ".pnpm",
+    ".turbo",
+    ".venv",
+    ".vs",
+    ".vscode",
+    ".yarn",
+    "bin",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "obj",
+    "target",
+    "vendor",
+    "venv",
+]);
+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", "environment"]);
+const playwrightKeys = new Set(["config", "baseUrlPort", "workers"]);
+export async function loadHostRuntimeContract(worktreePath, snapshot, directorySnapshot) {
+    worktreePath = await fs.realpath(worktreePath);
+    const target = path.join(path.resolve(worktreePath), hostRuntimeContractPath);
+    let source;
+    try {
+        const captured = snapshot ? await snapshot(target) : await readCanonicalSourceFile(target, maximumContractBytes);
+        if (captured === null)
+            return await discoverHostRuntimeContract(worktreePath, snapshot, directorySnapshot);
+        source = captured;
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return await discoverHostRuntimeContract(worktreePath, snapshot, directorySnapshot);
+        throw error;
+    }
+    return {
+        contract: validateHostRuntimeContract(source.toString("utf8")),
+        source: "project",
+    };
+}
+async function discoverHostRuntimeContract(worktreePath, snapshot, directorySnapshot) {
+    const root = path.resolve(worktreePath);
+    let nodeDiscovery;
+    let aspNetDiscovery;
+    try {
+        [nodeDiscovery, aspNetDiscovery] = await Promise.all([
+            discoverNodeRuntimes(root, snapshot, directorySnapshot),
+            discoverAspNetRuntimes(root, snapshot, directorySnapshot),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof IncompleteRuntimeDiscoveryError)
+            return incompleteRuntimeDiscovery();
+        throw error;
+    }
+    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, snapshot, directorySnapshot) {
+    const manifests = [...new Set([
+            path.join(root, "package.json"),
+            ...await findFiles(root, file => path.basename(file).toLowerCase() === "package.json", 4, maximumDiscoveryEntries, directorySnapshot),
+        ])];
+    const candidates = (await Promise.all(manifests.map(async (manifestPath) => await discoverNodeRuntime(root, manifestPath, snapshot, directorySnapshot)))).filter((candidate) => candidate !== null);
+    return { candidates: candidates.length === 1 ? candidates : [], ambiguous: candidates.length > 1 };
+}
+async function discoverNodeRuntime(root, manifestPath, snapshot, directorySnapshot) {
+    const source = await readBoundedOptionalFile(manifestPath, 256 * 1024, snapshot);
+    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), snapshot);
+    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), snapshot) ? path.join(root, candidate) : null),
+            findFiles(root, file => /^playwright\.config\.(?:ts|js|mjs|cjs)$/iu.test(path.basename(file)), 4, maximumDiscoveryEntries, directorySnapshot),
+        ])).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, snapshot, directorySnapshot) {
+    // Deep enough for nested solutions (src/<area>/<Project>/<Project>.csproj); the entry budget,
+    // not the depth, bounds the scan, and a scan that exceeds it is reported as incomplete.
+    const projects = await findFiles(root, file => file.toLowerCase().endsWith(".csproj"), 6, maximumDiscoveryEntries, directorySnapshot);
+    const webProjects = [];
+    for (const projectPath of projects) {
+        const source = await readBoundedOptionalFile(projectPath, 512 * 1024, snapshot);
+        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, snapshot);
+    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 incompleteRuntimeDiscovery() {
+    return {
+        contract: defaultHostRuntimeContract(),
+        source: "default",
+        discovery: {
+            status: "ambiguous",
+            reasonCode: "runtime_discovery_incomplete",
+            summary: "Forge could not scan the whole repository within its discovery budget, so host application runs remain serialized.",
+        },
+    };
+}
+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, snapshot) {
+    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"), snapshot).then(exists => exists ? "pnpm" : null),
+            optionalFileExists(path.join(directory, "yarn.lock"), snapshot).then(exists => exists ? "yarn" : null),
+            optionalFileExists(path.join(directory, "package-lock.json"), snapshot).then(exists => exists ? "npm" : null),
+            optionalFileExists(path.join(directory, "npm-shrinkwrap.json"), snapshot).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, snapshot) {
+    const target = path.join(root, path.dirname(projectRelativePath), "Properties", "launchSettings.json");
+    const source = await readBoundedOptionalFile(target, 512 * 1024, snapshot);
+    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: {} };
+    }
+}
+// A project's "forge-attempt" profile configures its API for managed attempts. The
+// attempt's pre-publication checks then run against the same settings the project's own
+// e2e suite uses, instead of the developer's "http" profile.
+const attemptLaunchProfileName = "forge-attempt";
+function aspNetProfilePriority(name) {
+    if (name.toLowerCase() === attemptLaunchProfileName)
+        return -1;
+    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_")
+        && !isUnsafeDotnetEnvironmentName(name)
+        && !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, snapshot) {
+    const results = [];
+    let examined = 0;
+    const directories = [{ directory: root, depth: 0 }];
+    while (directories.length > 0) {
+        const current = directories.shift();
+        if (current.depth > maximumDepth)
+            continue;
+        const entries = snapshot
+            ? await snapshot(current.directory)
+            : await fs.readdir(current.directory, { withFileTypes: true }).then(found => found.map(entry => ({
+                name: entry.name,
+                isDirectory: entry.isDirectory(),
+                isFile: entry.isFile(),
+            }))).catch((error) => {
+                // A directory removed since it was listed holds nothing; one that cannot be read
+                // (permissions, open-file limits) may hold the entrypoint discovery is looking for.
+                if (isFileNotFound(error))
+                    return [];
+                throw new IncompleteRuntimeDiscoveryError();
+            });
+        const orderedEntries = [...entries].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const entry of orderedEntries) {
+            if (entry.isDirectory
+                && (ignoredDiscoveryDirectories.has(entry.name.toLowerCase()) || isGeneratedOutputDirectoryName(entry.name)))
+                continue;
+            if (examined++ >= maximumEntries)
+                throw new IncompleteRuntimeDiscoveryError();
+            const target = path.join(current.directory, entry.name);
+            if (entry.isDirectory)
+                directories.push({ directory: target, depth: current.depth + 1 });
+            else if (entry.isFile && accepts(target))
+                results.push(target);
+        }
+    }
+    return results.sort((left, right) => left.localeCompare(right));
+}
+async function readBoundedOptionalFile(target, maximumBytes, snapshot) {
+    if (snapshot) {
+        const source = await snapshot(target);
+        return source && source.length > 0 && source.length <= maximumBytes ? source.toString("utf8") : null;
+    }
+    try {
+        const stat = await fs.stat(target);
+        if (!stat.isFile() || stat.size < 1 || stat.size > maximumBytes)
+            return null;
+        return (await readCanonicalSourceFile(target, maximumBytes)).toString("utf8");
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return null;
+        throw error;
+    }
+}
+async function optionalFileExists(target, snapshot) {
+    if (snapshot)
+        return await snapshot(target) !== null;
+    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,
+        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 };
+    });
+    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}]`));
+    rejectProjectAuthoredForgeArguments(parsedArgs, adapter, name);
+    const portableDirectory = launch.workingDirectory === undefined || launch.workingDirectory === null
+        ? "."
+        : containedPortablePath(launch.workingDirectory, `runtime.ports.${name}.launch.workingDirectory`);
+    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.`);
+        }
+        if (name.toLowerCase().startsWith("forge_") || isUnsafeDotnetEnvironmentName(name)) {
+            throw new Error(`runtime_contract_invalid: launch environment name '${name}' is host-owned or enables pre-startup code injection and cannot be project-authored.`);
+        }
+        return [name, boundedString(raw, 8192, `runtime.ports.${portName}.launch.environment.${name}`)];
+    }));
+}
+function isUnsafeDotnetEnvironmentName(name) {
+    const normalized = name.toUpperCase();
+    return normalized === "DOTNET_STARTUP_HOOKS"
+        || normalized === "DOTNET_ADDITIONAL_DEPS"
+        || normalized === "DOTNET_SHARED_STORE"
+        || normalized === "DOTNET_HOST_PATH"
+        || normalized === "MSBUILD_EXE_PATH"
+        || normalized === "MSBUILDSDKSPATH"
+        || normalized === "NUGET_PLUGIN_PATHS"
+        || normalized === "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES"
+        || normalized === "ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES"
+        || normalized.startsWith("CUSTOMBEFOREMICROSOFTCOMMON")
+        || normalized.startsWith("CUSTOMAFTERMICROSOFTCOMMON")
+        || normalized.startsWith("DOTNET_ROOT")
+        || normalized.startsWith("CORECLR_")
+        || normalized.startsWith("COR_")
+        || normalized.startsWith("COMPLUS_")
+        || normalized.startsWith("LD_")
+        || normalized.startsWith("DYLD_");
+}
+function rejectProjectAuthoredForgeArguments(args, adapter, portName) {
+    if (adapter !== "aspnetcore")
+        return;
+    const applicationArgumentIndex = args.indexOf("--");
+    if (applicationArgumentIndex < 0)
+        return;
+    const forbidden = args.slice(applicationArgumentIndex + 1).find(argument => {
+        const key = argument.split("=", 1)[0].replace(/^(?:--?|\/)/u, "");
+        return /^forge(?:[_:.-]|$)/iu.test(key);
+    });
+    if (forbidden) {
+        throw new Error(`runtime_contract_invalid: runtime.ports.${portName}.launch.args cannot override the host-owned FORGE_* namespace.`);
+    }
+}
+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";
+}