@godot-mcp/control-plane 0.0.0 → 0.1.0

package/dist/unsafe/unsafeFixtureService.js

@@ -0,0 +1,162 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, rm, rmdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { UnsafeFixtureJobReceiptSchema, UnsafeFixtureJobResultSchema, UnsafeFixtureOperationInputSchema } from "@godot-mcp/protocol";
+import { GodotMcpException } from "../errors.js";
+import { EvidenceStore } from "../evidence/evidenceStore.js";
+const OUTPUT_CHUNK_BYTES = 512 * 1024;
+function unsafeError(code, message) {
+    return new GodotMcpException({ code, message, retryable: false, correlationId: randomUUID(), partialEffects: false, rollback: "not_needed" });
+}
+async function ownedUnsafeDirectory(projectRoot, jobToken) {
+    let current = projectRoot;
+    for (const segment of [".godot", "evidence", "godot-mcp", "unsafe", jobToken]) {
+        current = join(current, segment);
+        let metadata = await lstat(current).catch(() => undefined);
+        if (!metadata) {
+            await mkdir(current, { mode: 0o700 });
+            metadata = await lstat(current);
+        }
+        if (metadata.isSymbolicLink() || !metadata.isDirectory())
+            throw new Error("Unsafe source directory must not contain symbolic links");
+    }
+    return current;
+}
+export class UnsafeFixtureService {
+    dependencies;
+    job;
+    runPromise;
+    now;
+    evidence;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.now = dependencies.now ?? (() => Date.now());
+        this.evidence = dependencies.evidence ?? new EvidenceStore(dependencies.activation.copyRoot);
+    }
+    isActive() { return this.job !== undefined && ["queued", "running"].includes(this.job.state); }
+    blocksExport() { return this.isActive() || this.job?.result?.cleanup === "failed"; }
+    async initialize() {
+        const root = join(this.dependencies.activation.copyRoot, ".godot", "evidence", "godot-mcp", "unsafe");
+        const metadata = await lstat(root).catch(() => undefined);
+        if (!metadata)
+            return;
+        if (metadata.isSymbolicLink() || !metadata.isDirectory())
+            throw unsafeError("CONFLICT", "Unsafe fixture residue root is invalid");
+        if ((await readdir(root)).length > 0)
+            throw unsafeError("CONFLICT", "Unsafe fixture crash residue requires explicit local cleanup before activation");
+    }
+    async execute(inputValue, correlationId) {
+        void correlationId;
+        const input = UnsafeFixtureOperationInputSchema.parse(inputValue);
+        if (input.operation === "execute_start")
+            return { data: this.start(input.source, input.deadlineMs) };
+        if (input.operation === "job_status")
+            return { data: this.status(input.jobToken) };
+        if (input.operation === "job_cancel")
+            return { data: this.cancel(input.jobToken) };
+        const result = this.result(input.jobToken);
+        return { data: result, evidence: result.evidence };
+    }
+    start(source, deadlineMs) {
+        if (this.isActive())
+            throw unsafeError("CONFLICT", "An unsafe fixture job is already active");
+        const sessionId = this.dependencies.sessionId();
+        if (!sessionId)
+            throw unsafeError("NOT_ATTACHED", "Unsafe fixture session is not attached");
+        const now = this.now();
+        const leaseExpiry = Date.parse(this.dependencies.activation.expiresAt);
+        if (now >= leaseExpiry || now + deadlineMs > leaseExpiry)
+            throw unsafeError("TIMEOUT", "Unsafe fixture activation expires before this job deadline");
+        const job = { token: `ujob_${randomBytes(32).toString("base64url")}`, sessionId, source, sourceSha256: createHash("sha256").update(source).digest("hex"), sourceBytes: Buffer.byteLength(source), deadlineAt: now + deadlineMs, state: "queued", controller: new AbortController() };
+        this.job = job;
+        this.runPromise = Promise.resolve().then(() => this.run(job));
+        void this.runPromise.catch(() => undefined);
+        return this.receipt(job);
+    }
+    status(token) { return this.receipt(this.requireJob(token)); }
+    cancel(token) { const job = this.requireJob(token); if (this.isActive())
+        job.controller.abort(unsafeError("CANCELLED", "Unsafe fixture job cancelled")); return this.receipt(job); }
+    result(token) { const job = this.requireJob(token); if (!job.result)
+        throw unsafeError("CONFLICT", "Unsafe fixture result is not terminal"); return job.result; }
+    async close() { if (!this.job)
+        return; if (this.isActive()) {
+        this.job.controller.abort(unsafeError("CANCELLED", "Unsafe fixture service closed"));
+        await this.job.process?.stop().catch(() => undefined);
+    } await this.runPromise; }
+    requireJob(token) { if (!this.job || this.job.token !== token || this.dependencies.sessionId() !== this.job.sessionId)
+        throw unsafeError("STALE_HANDLE", "Unsafe fixture job token is stale"); return this.job; }
+    receipt(job) { return UnsafeFixtureJobReceiptSchema.parse({ jobToken: job.token, state: job.state, unsafe: true, sandboxed: false, expiresAt: this.dependencies.activation.expiresAt }); }
+    async run(job) {
+        job.state = "running";
+        let exitCode = null;
+        let terminal = "failed";
+        let cleanup = "succeeded";
+        const evidence = [];
+        const deadlineTimer = setTimeout(() => job.controller.abort(unsafeError("TIMEOUT", "Unsafe fixture deadline expired")), Math.max(0, job.deadlineAt - this.now()));
+        let root = join(this.dependencies.activation.copyRoot, ".godot", "evidence", "godot-mcp", "unsafe", job.token);
+        const script = join(root, "script.gd");
+        try {
+            if (job.controller.signal.aborted)
+                throw job.controller.signal.reason;
+            root = await ownedUnsafeDirectory(this.dependencies.activation.copyRoot, job.token);
+            const handle = await open(script, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            try {
+                await handle.writeFile(job.source, "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            job.source = "";
+            if (job.controller.signal.aborted)
+                throw job.controller.signal.reason;
+            job.process = await this.dependencies.launch({ projectRoot: this.dependencies.activation.copyRoot, scriptPath: script, isolationRoot: join(root, "isolation"), signal: job.controller.signal });
+            exitCode = await this.interruptible(job, job.process.wait());
+            terminal = exitCode === 0 && !job.process.outputExceeded() ? "completed" : "failed";
+        }
+        catch {
+            try {
+                await job.process?.stop();
+            }
+            catch {
+                cleanup = "failed";
+            }
+            terminal = job.controller.signal.reason instanceof GodotMcpException && job.controller.signal.reason.code === "CANCELLED" ? "cancelled" : "failed";
+        }
+        finally {
+            clearTimeout(deadlineTimer);
+            const output = job.process?.diagnostics() ?? Buffer.alloc(0);
+            const chunkCount = Math.max(1, Math.ceil(output.byteLength / OUTPUT_CHUNK_BYTES));
+            for (let index = 0; index < chunkCount; index += 1) {
+                const chunk = output.subarray(index * OUTPUT_CHUNK_BYTES, (index + 1) * OUTPUT_CHUNK_BYTES);
+                const stored = await this.evidence.putJson(job.sessionId, { outputBase64: chunk.toString("base64"), encoding: "base64", chunkIndex: index, chunkCount, outputExceeded: job.process?.outputExceeded() ?? false, state: terminal, exitCode, unsafe: true, sandboxed: false }, { kind: "unsafe_fixture_output" }).catch(() => undefined);
+                if (stored)
+                    evidence.push(stored.observationUri);
+            }
+            const cleanupErrors = [];
+            await unlink(script).catch((error) => { if (error.code !== "ENOENT")
+                cleanupErrors.push(error); });
+            await rm(join(root, "isolation"), { recursive: true, force: true }).catch((error) => cleanupErrors.push(error));
+            await rmdir(root).catch((error) => { if (error.code !== "ENOENT")
+                cleanupErrors.push(error); });
+            if (cleanupErrors.length > 0)
+                cleanup = "failed";
+            job.state = terminal;
+            job.result = UnsafeFixtureJobResultSchema.parse({ ...this.receipt(job), state: terminal, exitCode, sourceSha256: job.sourceSha256, sourceBytes: job.sourceBytes, evidence, cleanup });
+        }
+    }
+    async interruptible(job, operation) {
+        if (job.controller.signal.aborted)
+            throw job.controller.signal.reason;
+        let listener;
+        const interruption = new Promise((_resolve, reject) => { listener = () => reject(job.controller.signal.reason); job.controller.signal.addEventListener("abort", listener, { once: true }); });
+        try {
+            return await Promise.race([operation, interruption]);
+        }
+        finally {
+            if (listener)
+                job.controller.signal.removeEventListener("abort", listener);
+        }
+    }
+}
+//# sourceMappingURL=unsafeFixtureService.js.map

package/dist/unsafe/unsafeFixtureService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsafeFixtureService.js","sourceRoot":"","sources":["../../src/unsafe/unsafeFixtureService.ts"],"names":[],"mappings":"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"}

package/dist/visual/pngComparison.d.ts

@@ -0,0 +1,12 @@
+import { type VisualComparisonResult } from "@godot-mcp/protocol";
+export interface ComparePngInput {
+    baseline: Uint8Array;
+    current: Uint8Array;
+    settings: unknown;
+}
+export interface ComparePngOutput {
+    result: VisualComparisonResult;
+    diffPng?: Uint8Array;
+}
+export declare function comparePng(input: ComparePngInput): ComparePngOutput;
+//# sourceMappingURL=pngComparison.d.ts.map

package/dist/visual/pngComparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pngComparison.d.ts","sourceRoot":"","sources":["../../src/visual/pngComparison.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,sBAAsB,EAE5B,MAAM,qBAAqB,CAAC;AAU7B,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AA2ED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CA+DnE"}

package/dist/visual/pngComparison.js

@@ -0,0 +1,136 @@
+import { createHash, randomUUID } from "node:crypto";
+import { canonicalJson, VisualComparisonResultSchema, VisualComparisonSettingsSchema, } from "@godot-mcp/protocol";
+import { PNG } from "pngjs";
+import { GodotMcpException } from "../errors.js";
+const MAX_PNG_BYTES = 8 * 1024 * 1024;
+const MAX_PIXELS = 4_194_304;
+const PNG_SIGNATURE = Buffer.from("89504e470d0a1a0a", "hex");
+const IHDR = Buffer.from("IHDR", "ascii");
+function comparisonError(code, message) {
+    return new GodotMcpException({
+        code,
+        message,
+        retryable: false,
+        correlationId: randomUUID(),
+        partialEffects: false,
+        rollback: "not_needed",
+    });
+}
+function decodePng(bytes) {
+    if (bytes.byteLength > MAX_PNG_BYTES)
+        throw comparisonError("PAYLOAD_TOO_LARGE", "Visual comparison PNG exceeds eight MiB");
+    const encoded = Buffer.from(bytes);
+    if (encoded.byteLength < 29 ||
+        !encoded.subarray(0, PNG_SIGNATURE.byteLength).equals(PNG_SIGNATURE) ||
+        encoded.readUInt32BE(8) !== 13 ||
+        !encoded.subarray(12, 16).equals(IHDR))
+        throw comparisonError("INVALID_REQUEST", "Visual comparison input is not a valid PNG");
+    const declaredWidth = encoded.readUInt32BE(16);
+    const declaredHeight = encoded.readUInt32BE(20);
+    if (declaredWidth < 1 || declaredHeight < 1 ||
+        declaredWidth > 2048 || declaredHeight > 2048 ||
+        declaredWidth * declaredHeight > MAX_PIXELS)
+        throw comparisonError("PAYLOAD_TOO_LARGE", "Visual comparison PNG dimensions exceed certified bounds");
+    if (encoded[28] === 1) {
+        throw comparisonError("INVALID_REQUEST", "Interlaced visual comparison PNGs are not supported");
+    }
+    let decoded;
+    try {
+        decoded = PNG.sync.read(encoded);
+    }
+    catch {
+        throw comparisonError("INVALID_REQUEST", "Visual comparison input is not a valid PNG");
+    }
+    if (!Number.isInteger(decoded.width) || !Number.isInteger(decoded.height) ||
+        decoded.width < 1 || decoded.height < 1 ||
+        decoded.width > 2048 || decoded.height > 2048 ||
+        decoded.width * decoded.height > MAX_PIXELS ||
+        decoded.data.byteLength !== decoded.width * decoded.height * 4)
+        throw comparisonError("PAYLOAD_TOO_LARGE", "Visual comparison PNG dimensions exceed certified bounds");
+    return { width: decoded.width, height: decoded.height, data: decoded.data };
+}
+function rectInside(rect, width, height) {
+    return rect.x + rect.width <= width && rect.y + rect.height <= height;
+}
+function pointInside(x, y, rect) {
+    return x >= rect.x && y >= rect.y && x < rect.x + rect.width && y < rect.y + rect.height;
+}
+function validateGeometry(settings, width, height) {
+    const region = settings.region ?? { x: 0, y: 0, width, height };
+    if (!rectInside(region, width, height))
+        throw comparisonError("INVALID_REQUEST", "Visual comparison region exceeds image bounds");
+    for (const mask of settings.masks) {
+        if (!rectInside(mask, width, height))
+            throw comparisonError("INVALID_REQUEST", "Visual comparison mask exceeds image bounds");
+    }
+    return { ...settings, region };
+}
+function digest(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function comparePng(input) {
+    const baseline = decodePng(input.baseline);
+    const current = decodePng(input.current);
+    if (baseline.width !== current.width || baseline.height !== current.height) {
+        throw comparisonError("INVALID_REQUEST", "Visual comparison image dimensions do not match");
+    }
+    const parsedSettings = VisualComparisonSettingsSchema.parse(input.settings);
+    const settings = validateGeometry(parsedSettings, baseline.width, baseline.height);
+    const region = settings.region;
+    let comparedPixels = 0;
+    let maskedPixels = 0;
+    let differentPixels = 0;
+    let maxObservedChannelDelta = 0;
+    const differentOffsets = [];
+    for (let y = region.y; y < region.y + region.height; y += 1) {
+        for (let x = region.x; x < region.x + region.width; x += 1) {
+            if (settings.masks.some((mask) => pointInside(x, y, mask))) {
+                maskedPixels += 1;
+                continue;
+            }
+            comparedPixels += 1;
+            const offset = (y * baseline.width + x) * 4;
+            let pixelDelta = 0;
+            for (let channel = 0; channel < 4; channel += 1) {
+                pixelDelta = Math.max(pixelDelta, Math.abs(baseline.data[offset + channel] - current.data[offset + channel]));
+            }
+            maxObservedChannelDelta = Math.max(maxObservedChannelDelta, pixelDelta);
+            if (pixelDelta > settings.maxChannelDelta) {
+                differentPixels += 1;
+                differentOffsets.push(offset);
+            }
+        }
+    }
+    const differentRatioMillionths = comparedPixels === 0
+        ? 0
+        : Math.floor(differentPixels * 1_000_000 / comparedPixels);
+    const passed = differentPixels <= settings.maxDifferentPixels &&
+        differentRatioMillionths <= settings.maxDifferentRatioMillionths;
+    const resultWithoutDigest = {
+        passed,
+        comparedPixels,
+        maskedPixels,
+        differentPixels,
+        differentRatioMillionths,
+        maxObservedChannelDelta,
+        baselineSha256: digest(input.baseline),
+        currentSha256: digest(input.current),
+        settings: parsedSettings,
+    };
+    const result = VisualComparisonResultSchema.parse({
+        ...resultWithoutDigest,
+        resultSha256: digest(Buffer.from(canonicalJson(resultWithoutDigest), "utf8")),
+    });
+    if (passed)
+        return { result };
+    const diff = new PNG({ width: current.width, height: current.height });
+    current.data.copy(diff.data);
+    for (const offset of differentOffsets) {
+        diff.data[offset] = 255;
+        diff.data[offset + 1] = 0;
+        diff.data[offset + 2] = 0;
+        diff.data[offset + 3] = 255;
+    }
+    return { result, diffPng: PNG.sync.write(diff, { colorType: 6, inputColorType: 6 }) };
+}
+//# sourceMappingURL=pngComparison.js.map

package/dist/visual/pngComparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pngComparison.js","sourceRoot":"","sources":["../../src/visual/pngComparison.ts"],"names":[],"mappings":"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"}

package/dist/visual/scenarioService.d.ts

@@ -0,0 +1,50 @@
+import { type InputOperationInput, type RuntimeCaptureFrameMetadata, type RuntimeCaptureInput, type RuntimeHandle, type RuntimeLaunchPins, type RuntimeOperationInput, type ScenarioJobReceipt, type ScenarioReport } from "@godot-mcp/protocol";
+import type { EvidenceStore } from "../evidence/evidenceStore.js";
+export interface ScenarioFrame {
+    data: Uint8Array;
+    metadata: RuntimeCaptureFrameMetadata;
+}
+export interface ScenarioRuntime {
+    launch(input: {
+        scenePath: string;
+        startupTimeoutMs: number;
+        pins: RuntimeLaunchPins;
+    }): Promise<{
+        handle: RuntimeHandle;
+        root: unknown;
+    }>;
+    execute(input: Exclude<RuntimeOperationInput, {
+        operation: "launch";
+    }>): Promise<unknown>;
+    input(input: InputOperationInput): Promise<unknown>;
+    capture(input: RuntimeCaptureInput): Promise<{
+        frames: ScenarioFrame[];
+    }>;
+}
+export interface ScenarioServiceDependencies {
+    projectId: string;
+    sessionId(): string | null;
+    runtime: ScenarioRuntime;
+    evidence: EvidenceStore;
+    now?: () => number;
+}
+export declare class ScenarioService {
+    private readonly dependencies;
+    private job;
+    private readonly now;
+    constructor(dependencies: ScenarioServiceDependencies);
+    hasActiveJob(): boolean;
+    start(input: unknown): ScenarioJobReceipt;
+    status(jobToken: string): ScenarioJobReceipt;
+    cancel(jobToken: string): ScenarioJobReceipt;
+    result(jobToken: string): ScenarioReport;
+    close(): Promise<void>;
+    private requireJob;
+    private receipt;
+    private run;
+    private runStep;
+    private assertRuntime;
+    private boundary;
+    private assertJobActive;
+}
+//# sourceMappingURL=scenarioService.d.ts.map

package/dist/visual/scenarioService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarioService.d.ts","sourceRoot":"","sources":["../../src/visual/scenarioService.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAE1B,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,2BAA2B,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,iBAAiB,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC3I,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,qBAAqB,EAAE;QAAE,SAAS,EAAE,QAAQ,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1F,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AA+DD,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,YAAY;IAHzC,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEN,YAAY,EAAE,2BAA2B;IAItE,YAAY,IAAI,OAAO;IAIvB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB;IAwBzC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB;IAI5C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB;IAQ5C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IAMlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,OAAO;YASD,GAAG;YA0HH,OAAO;YA0FP,aAAa;YA0Db,QAAQ;IAoBtB,OAAO,CAAC,eAAe;CAKxB"}