@loucompanion/forge-bridge 0.1.3-dev.d1ca67076aa9 → 0.1.3-dev.eeefdb0d19c1

package/dist/runtime/playwright-host-runtime-adapter.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const maximumConfigBytes = 1024 * 1024;
+/**
+ * Prepares a finite Playwright test boundary for a managed-host attempt.
+ * The generated overlay points tests at Forge's verified listener, disables
+ * Playwright-managed web servers, and keeps writable artifacts attempt-local.
+ */
+export class PlaywrightHostRuntimeAdapter {
+    async prepare(config, context) {
+        const worktreePath = path.resolve(context.worktreePath);
+        const sourceConfig = path.resolve(worktreePath, config.config);
+        const [realWorktree, realSource] = await Promise.all([
+            fs.realpath(worktreePath),
+            fs.realpath(sourceConfig),
+        ]);
+        assertContained(realWorktree, realSource, "project Playwright config");
+        const sourceStat = await fs.stat(realSource);
+        if (!sourceStat.isFile() || sourceStat.size < 1 || sourceStat.size > maximumConfigBytes) {
+            throw new Error(`playwright_runtime_adapter_invalid: project config must be a regular 1-${maximumConfigBytes} byte file.`);
+        }
+        const temporaryDirectory = await realContainedDirectory(context.temporaryDirectory, realWorktree, "temporary directory");
+        const testOutputDirectory = await realContainedDirectory(context.testOutputDirectory, realWorktree, "test output directory");
+        const browserProfileDirectory = await realContainedDirectory(context.browserProfileDirectory, realWorktree, "browser profile directory");
+        const attemptRoot = path.dirname(temporaryDirectory);
+        if (path.dirname(testOutputDirectory) !== attemptRoot || path.dirname(browserProfileDirectory) !== attemptRoot) {
+            throw new Error("playwright_runtime_adapter_invalid: writable directories must belong to the same attempt root.");
+        }
+        const baseUrl = loopbackHttpUrl(context.baseUrl);
+        const overlayPath = path.join(temporaryDirectory, "forge.playwright.config.mjs");
+        const browserCache = await resolvePlaywrightBrowserCache(attemptRoot);
+        const browserInstallCommand = await resolvePlaywrightBrowserInstallCommand(context.worktreePath, path.dirname(realSource));
+        await fs.writeFile(overlayPath, renderOverlay({
+            projectConfigUrl: pathToFileURL(realSource).href,
+            projectConfigDirectory: path.dirname(realSource),
+            testOutputDirectory,
+            baseUrl,
+            workers: config.workers,
+        }), { encoding: "utf8", mode: 0o600 });
+        return {
+            configPath: overlayPath,
+            environment: {
+                FORGE_PLAYWRIGHT_CONFIG: overlayPath,
+                FORGE_PLAYWRIGHT_BASE_URL: baseUrl,
+                FORGE_E2E_WEB_URL: baseUrl,
+                FORGE_PLAYWRIGHT_BROWSER_READY: browserCache.ready ? "true" : "false",
+                FORGE_PLAYWRIGHT_BROWSER_INSTALL_COMMAND: browserInstallCommand,
+                PLAYWRIGHT_BROWSERS_PATH: browserCache.path,
+                PLAYWRIGHT_HTML_OUTPUT_DIR: path.join(testOutputDirectory, "html-report"),
+                PLAYWRIGHT_BLOB_OUTPUT_DIR: path.join(testOutputDirectory, "blob-report"),
+                PLAYWRIGHT_JUNIT_OUTPUT_NAME: path.join(testOutputDirectory, "results.xml"),
+                PLAYWRIGHT_JSON_OUTPUT_NAME: path.join(testOutputDirectory, "results.json"),
+                FORGE_BROWSER_PROFILE_DIR: browserProfileDirectory,
+                FORGE_TEST_OUTPUT_DIR: testOutputDirectory,
+            },
+        };
+    }
+}
+async function resolvePlaywrightBrowserInstallCommand(worktreePath, configDirectory) {
+    const relativeDirectory = path.relative(worktreePath, configDirectory).replaceAll(path.sep, "/") || ".";
+    if (await isFile(path.join(configDirectory, "pnpm-lock.yaml"))) {
+        return `pnpm --dir ${quoteCommandArgument(relativeDirectory)} exec playwright install chromium`;
+    }
+    if (await isFile(path.join(configDirectory, "yarn.lock"))) {
+        return `yarn --cwd ${quoteCommandArgument(relativeDirectory)} playwright install chromium`;
+    }
+    return `npm --prefix ${quoteCommandArgument(relativeDirectory)} exec playwright install chromium`;
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function quoteCommandArgument(value) {
+    return /[\s"']/u.test(value) ? JSON.stringify(value) : value;
+}
+async function resolvePlaywrightBrowserCache(attemptRoot) {
+    const candidates = [
+        process.env.PLAYWRIGHT_BROWSERS_PATH,
+        process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "ms-playwright") : null,
+        path.join(os.homedir(), ".cache", "ms-playwright"),
+    ].filter((candidate) => Boolean(candidate?.trim()));
+    for (const candidate of [...new Set(candidates.map(candidate => path.resolve(candidate)))]) {
+        if (await hasChromiumExecutable(candidate)) {
+            return { path: candidate, ready: true };
+        }
+    }
+    const attemptCache = path.join(attemptRoot, "cache", "ms-playwright");
+    await fs.mkdir(attemptCache, { recursive: true });
+    return { path: attemptCache, ready: false };
+}
+async function hasChromiumExecutable(cachePath) {
+    let entries;
+    try {
+        entries = await fs.readdir(cachePath, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    const executableSuffixes = process.platform === "win32"
+        ? [path.join("chrome-win64", "chrome.exe"), path.join("chrome-win", "chrome.exe")]
+        : process.platform === "darwin"
+            ? [path.join("chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium")]
+            : [path.join("chrome-linux", "chrome"), path.join("chrome-linux64", "chrome")];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith("chromium-"))
+            continue;
+        for (const suffix of executableSuffixes) {
+            try {
+                const stat = await fs.stat(path.join(cachePath, entry.name, suffix));
+                if (stat.isFile())
+                    return true;
+            }
+            catch {
+                // Continue through known Playwright layouts.
+            }
+        }
+    }
+    return false;
+}
+function renderOverlay(values) {
+    return [
+        "// Generated by forge-bridge for one fenced host attempt.",
+        "import path from \"node:path\";",
+        `import projectConfig from ${JSON.stringify(values.projectConfigUrl)};`,
+        `const projectConfigDirectory = ${JSON.stringify(values.projectConfigDirectory)};`,
+        "const resolveConfigPath = value => typeof value === \"string\" && !path.isAbsolute(value)",
+        "  ? path.resolve(projectConfigDirectory, value)",
+        "  : value;",
+        "const resolveModulePath = value => typeof value === \"string\" && value.startsWith(\".\")",
+        "  ? path.resolve(projectConfigDirectory, value)",
+        "  : value;",
+        "const resolveUse = use => ({",
+        "  ...(use ?? {}),",
+        "  storageState: typeof use?.storageState === \"string\" ? resolveConfigPath(use.storageState) : use?.storageState,",
+        "  baseURL: " + JSON.stringify(values.baseUrl) + ",",
+        "});",
+        "const forgeUse = resolveUse(projectConfig.use);",
+        "const forgeProjects = Array.isArray(projectConfig.projects)",
+        "  ? projectConfig.projects.map(project => ({",
+        "      ...project,",
+        "      testDir: resolveConfigPath(project.testDir),",
+        "      snapshotDir: resolveConfigPath(project.snapshotDir),",
+        "      use: resolveUse(project.use),",
+        "    }))",
+        "  : projectConfig.projects;",
+        "const forgeReporter = Array.isArray(projectConfig.reporter)",
+        "  ? projectConfig.reporter.map(reporter => Array.isArray(reporter)",
+        "      ? [resolveModulePath(reporter[0]), ...reporter.slice(1)]",
+        "      : resolveModulePath(reporter))",
+        "  : resolveModulePath(projectConfig.reporter);",
+        "const forgeProviderOnlySpecs = (() => {",
+        "  try {",
+        "    const parsed = JSON.parse(process.env.FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS ?? '[]');",
+        "    return Array.isArray(parsed) ? parsed.filter(value => typeof value === 'string' && value.length > 0) : [];",
+        "  } catch {",
+        "    return [];",
+        "  }",
+        "})();",
+        "const forgeTestIgnore = forgeProviderOnlySpecs.length === 0",
+        "  ? projectConfig.testIgnore",
+        "  : [...(Array.isArray(projectConfig.testIgnore) ? projectConfig.testIgnore : projectConfig.testIgnore ? [projectConfig.testIgnore] : []), ...forgeProviderOnlySpecs];",
+        "export default {",
+        "  ...projectConfig,",
+        "  testDir: resolveConfigPath(projectConfig.testDir),",
+        "  snapshotDir: resolveConfigPath(projectConfig.snapshotDir),",
+        "  globalSetup: resolveModulePath(projectConfig.globalSetup),",
+        "  globalTeardown: resolveModulePath(projectConfig.globalTeardown),",
+        "  reporter: forgeReporter,",
+        "  testIgnore: forgeTestIgnore,",
+        `  outputDir: ${JSON.stringify(values.testOutputDirectory)},`,
+        `  workers: ${values.workers},`,
+        "  webServer: undefined,",
+        "  use: forgeUse,",
+        "  projects: forgeProjects,",
+        "};",
+        "",
+    ].join("\n");
+}
+async function realContainedDirectory(target, realWorktree, label) {
+    const realTarget = await fs.realpath(path.resolve(target));
+    if (realTarget === realWorktree || isContained(realWorktree, realTarget)) {
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must be attempt-private and outside the worktree.`);
+    }
+    const stat = await fs.stat(realTarget);
+    if (!stat.isDirectory())
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must be a directory.`);
+    return realTarget;
+}
+function assertContained(parent, child, label) {
+    if (!isContained(parent, child)) {
+        throw new Error(`playwright_runtime_adapter_invalid: ${label} must stay inside the prepared worktree.`);
+    }
+}
+function isContained(parent, child) {
+    const relative = path.relative(parent, child);
+    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function loopbackHttpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("playwright_runtime_adapter_invalid: base URL must be an HTTP loopback URL.");
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || url.hostname !== "127.0.0.1"
+        || !url.port
+        || url.username
+        || url.password) {
+        throw new Error("playwright_runtime_adapter_invalid: base URL must be an HTTP loopback URL.");
+    }
+    return url.href.replace(/\/$/u, "");
+}

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

@@ -0,0 +1,67 @@
+export declare const runtimeIsolationLeaseStates: readonly ["reserved", "starting", "active", "releasing", "released", "degraded"];
+export type RuntimeIsolationLeaseState = typeof runtimeIsolationLeaseStates[number];
+export type RuntimeIsolationMode = "docker" | "host";
+export interface RuntimeIsolationPort {
+    readonly name: string;
+    readonly protocol: "tcp" | "udp";
+    readonly hostIp: "127.0.0.1" | "::1";
+    readonly hostPort: number;
+    readonly targetPort: number;
+}
+export interface RuntimeIsolationPath {
+    readonly path: string;
+    readonly role: string;
+}
+export interface RuntimeIsolationDockerResource {
+    readonly type: "container" | "network" | "volume";
+    readonly name: string;
+    readonly role: string;
+    readonly id?: string | null;
+}
+export interface RuntimeIsolationResources {
+    readonly memoryReservationBytes: number;
+    readonly cpuMillis: number;
+    readonly pids: number;
+    readonly ports: readonly RuntimeIsolationPort[];
+    readonly paths: readonly RuntimeIsolationPath[];
+    readonly processSupervisorId: string | null;
+    readonly dockerResources: readonly RuntimeIsolationDockerResource[];
+    readonly singletonKeys: readonly string[];
+}
+export interface RuntimeIsolationLease {
+    readonly schemaVersion: 1;
+    readonly leaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly worktreeKey: string;
+    readonly worktreePath: string;
+    readonly mode: RuntimeIsolationMode;
+    readonly state: RuntimeIsolationLeaseState;
+    readonly createdAt: string;
+    readonly stateChangedAt: string;
+    readonly expiresAt: string;
+    readonly releasedAt: string | null;
+    readonly resources: RuntimeIsolationResources;
+}
+export interface RuntimeIsolationLeaseInput {
+    readonly leaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly worktreeKey: string;
+    readonly worktreePath: string;
+    readonly mode: RuntimeIsolationMode;
+    readonly expiresAt: string;
+    readonly resources: RuntimeIsolationResources;
+    readonly createdAt?: string;
+}
+export declare function createRuntimeIsolationLease(input: RuntimeIsolationLeaseInput): RuntimeIsolationLease;
+export declare function transitionRuntimeIsolationLease(lease: RuntimeIsolationLease, nextState: RuntimeIsolationLeaseState, occurredAt?: string): RuntimeIsolationLease;
+export declare function renewRuntimeIsolationLease(lease: RuntimeIsolationLease, fencingToken: string, expiresAt: string): RuntimeIsolationLease | null;
+export declare function withRuntimeIsolationResources(lease: RuntimeIsolationLease, resources: RuntimeIsolationResources): RuntimeIsolationLease;
+export declare function validRuntimeIsolationLease(value: unknown): value is RuntimeIsolationLease;

package/dist/runtime/runtime-isolation-lease.js

@@ -0,0 +1,158 @@
+export const runtimeIsolationLeaseStates = [
+    "reserved",
+    "starting",
+    "active",
+    "releasing",
+    "released",
+    "degraded",
+];
+const allowedTransitions = {
+    reserved: new Set(["starting", "releasing", "degraded"]),
+    starting: new Set(["active", "releasing", "degraded"]),
+    active: new Set(["releasing", "degraded"]),
+    releasing: new Set(["released", "degraded"]),
+    released: new Set(),
+    degraded: new Set(["releasing"]),
+};
+export function createRuntimeIsolationLease(input) {
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    const lease = {
+        schemaVersion: 1,
+        leaseId: input.leaseId,
+        dispatchAttemptId: input.dispatchAttemptId,
+        executionLeaseId: input.executionLeaseId,
+        fencingToken: input.fencingToken,
+        runnerId: input.runnerId,
+        runnerInstanceId: input.runnerInstanceId,
+        worktreeKey: input.worktreeKey,
+        worktreePath: input.worktreePath,
+        mode: input.mode,
+        state: "reserved",
+        createdAt,
+        stateChangedAt: createdAt,
+        expiresAt: input.expiresAt,
+        releasedAt: null,
+        resources: input.resources,
+    };
+    if (!validRuntimeIsolationLease(lease)) {
+        throw new Error("runtime_lease_invalid: lease identity, lifetime, or resources are invalid.");
+    }
+    return lease;
+}
+export function transitionRuntimeIsolationLease(lease, nextState, occurredAt = new Date().toISOString()) {
+    if (lease.state === nextState)
+        return lease;
+    if (!allowedTransitions[lease.state].has(nextState) || !validTimestamp(occurredAt)) {
+        throw new Error(`runtime_lease_transition_invalid: cannot transition ${lease.state} to ${nextState}.`);
+    }
+    const transitioned = {
+        ...lease,
+        state: nextState,
+        stateChangedAt: occurredAt,
+        releasedAt: nextState === "released" ? occurredAt : null,
+    };
+    if (!validRuntimeIsolationLease(transitioned)) {
+        throw new Error("runtime_lease_invalid: transitioned lease is invalid.");
+    }
+    return transitioned;
+}
+export function renewRuntimeIsolationLease(lease, fencingToken, expiresAt) {
+    if (lease.fencingToken !== fencingToken || lease.state === "released" || !validTimestamp(expiresAt))
+        return null;
+    const renewed = { ...lease, expiresAt };
+    return validRuntimeIsolationLease(renewed) ? renewed : null;
+}
+export function withRuntimeIsolationResources(lease, resources) {
+    if (lease.state === "released") {
+        throw new Error("runtime_lease_transition_invalid: released leases cannot acquire resources.");
+    }
+    const updated = { ...lease, resources };
+    if (!validRuntimeIsolationLease(updated)) {
+        throw new Error("runtime_lease_invalid: resources are invalid.");
+    }
+    return updated;
+}
+export function validRuntimeIsolationLease(value) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 1
+        || !isUuid(value.leaseId)
+        || !isUuid(value.dispatchAttemptId)
+        || !isUuid(value.executionLeaseId)
+        || !isUuid(value.fencingToken)
+        || !isUuid(value.runnerId)
+        || !isUuid(value.runnerInstanceId)
+        || !boundedText(value.worktreeKey, 255)
+        || !boundedText(value.worktreePath, 4096)
+        || (value.mode !== "docker" && value.mode !== "host")
+        || !runtimeIsolationLeaseStates.includes(value.state)
+        || !validTimestamp(value.createdAt)
+        || !validTimestamp(value.stateChangedAt)
+        || !validTimestamp(value.expiresAt)
+        || Date.parse(value.stateChangedAt) < Date.parse(value.createdAt)
+        || Date.parse(value.expiresAt) < Date.parse(value.createdAt)
+        || (value.state === "released") !== validTimestamp(value.releasedAt)) {
+        return false;
+    }
+    if (value.releasedAt !== null && Date.parse(value.releasedAt) < Date.parse(value.createdAt))
+        return false;
+    return validResources(value.resources, value.mode);
+}
+function validResources(value, mode) {
+    if (!isRecord(value)
+        || !nonNegativeInteger(value.memoryReservationBytes)
+        || !nonNegativeInteger(value.cpuMillis)
+        || !nonNegativeInteger(value.pids)
+        || !Array.isArray(value.ports) || value.ports.length > 64
+        || !Array.isArray(value.paths) || value.paths.length > 64
+        || !Array.isArray(value.dockerResources) || value.dockerResources.length > 128
+        || !Array.isArray(value.singletonKeys) || value.singletonKeys.length > 64
+        || (value.processSupervisorId !== null && !boundedText(value.processSupervisorId, 255))) {
+        return false;
+    }
+    if (value.ports.some(port => !validPort(port))
+        || value.paths.some(entry => !isRecord(entry) || !boundedText(entry.path, 4096) || !boundedText(entry.role, 128))
+        || value.singletonKeys.some(key => !boundedText(key, 255))
+        || value.dockerResources.some(resource => !validDockerResource(resource))) {
+        return false;
+    }
+    return mode === "docker" || value.dockerResources.length === 0;
+}
+function validPort(value) {
+    return isRecord(value)
+        && boundedText(value.name, 128)
+        && (value.protocol === "tcp" || value.protocol === "udp")
+        && (value.hostIp === "127.0.0.1" || value.hostIp === "::1")
+        && validPortNumber(value.hostPort)
+        && validPortNumber(value.targetPort);
+}
+function validDockerResource(value) {
+    return isRecord(value)
+        && (value.type === "container" || value.type === "network" || value.type === "volume")
+        && boundedText(value.name, 255)
+        && boundedText(value.role, 128)
+        && (value.id === undefined || value.id === null || boundedText(value.id, 255));
+}
+function validPortNumber(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= 65535;
+}
+function nonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function boundedText(value, maximumLength) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximumLength
+        && Array.from(value).every((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint > 31 && codePoint !== 127;
+        });
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/iu.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/sandbox/command-runner.d.ts

@@ -0,0 +1,4 @@
+import type { CommandOptions, CommandResult, CommandRunner } from "./sandbox.types.js";
+export declare class BoundedCommandRunner implements CommandRunner {
+    run(command: string, args: readonly string[], options?: CommandOptions): Promise<CommandResult>;
+}

package/dist/sandbox/command-runner.js

@@ -0,0 +1,47 @@
+import { spawn } from "node:child_process";
+export class BoundedCommandRunner {
+    async run(command, args, options = {}) {
+        const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
+        return await new Promise((resolve, reject) => {
+            const controller = new AbortController();
+            const abort = () => controller.abort(options.signal?.reason ?? "command cancelled");
+            options.signal?.addEventListener("abort", abort, { once: true });
+            const timeout = options.timeoutMs
+                ? setTimeout(() => controller.abort(`command exceeded ${options.timeoutMs}ms`), options.timeoutMs)
+                : null;
+            timeout?.unref?.();
+            const child = spawn(command, [...args], {
+                cwd: options.cwd,
+                env: options.env ? { ...options.env } : undefined,
+                stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+                signal: controller.signal,
+                windowsHide: true,
+            });
+            let stdout = Buffer.alloc(0);
+            let stderr = Buffer.alloc(0);
+            const append = (current, chunk) => {
+                if (current.length >= maxOutputBytes)
+                    return current;
+                return Buffer.concat([current, chunk.subarray(0, maxOutputBytes - current.length)]);
+            };
+            child.stdout.on("data", (chunk) => { stdout = append(stdout, chunk); });
+            child.stderr.on("data", (chunk) => { stderr = append(stderr, chunk); });
+            child.on("error", (error) => {
+                cleanup();
+                reject(error);
+            });
+            child.on("close", (code) => {
+                cleanup();
+                resolve({ exitCode: code ?? 1, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8") });
+            });
+            if (options.stdin !== undefined) {
+                child.stdin.end(options.stdin);
+            }
+            function cleanup() {
+                if (timeout)
+                    clearTimeout(timeout);
+                options.signal?.removeEventListener("abort", abort);
+            }
+        });
+    }
+}

package/dist/sandbox/contract.d.ts

@@ -0,0 +1,5 @@
+import type { ValidatedSandboxContract } from "./sandbox.types.js";
+export declare function validateSandboxContract(source: string): ValidatedSandboxContract;
+export declare function validateDockerfilePolicy(source: string, requirePinnedBase: boolean): readonly string[];
+export declare function dockerfileBaseImages(source: string): readonly string[];
+export declare function dockerfileUpstreamImages(source: string): readonly string[];