Add Electron capture request contract

This commit is contained in:
Meta Vens 2026-07-09 11:15:59 +01:00
commit cc556c2c0c
13 changed files with 348 additions and 15 deletions

View file

@ -0,0 +1,122 @@
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
export function buildElectronCaptureRequest({
advertisement,
capabilityManifest,
advertisementPath = "",
capabilityManifestPath = "",
stamp = new Date().toISOString().replace(/[:.]/g, "-"),
} = {}) {
if (!advertisement || typeof advertisement !== "object") {
throw new Error("advertisement is required");
}
if (!capabilityManifest || typeof capabilityManifest !== "object") {
throw new Error("capabilityManifest is required");
}
const captureContract = capabilityManifest.lifecycle?.capture?.captureContract;
if (!captureContract) {
throw new Error("capability manifest is missing lifecycle.capture.captureContract");
}
if (advertisement.providerId !== captureContract.requiredProvider) {
throw new Error(
`capture provider mismatch: expected ${captureContract.requiredProvider} got ${advertisement.providerId || "missing"}`,
);
}
const targetId = captureContract.targetId || captureContract.runtimeId;
const surface = (advertisement.surfaces || []).find(candidate => candidate.surfaceId === captureContract.requiredSurface);
if (!surface) {
throw new Error(`capture surface not advertised: ${captureContract.requiredSurface}`);
}
const loweringTargets = surface.worldInteraction?.loweringTargets || [];
if (!loweringTargets.includes(targetId)) {
throw new Error(`surface ${surface.surfaceId} does not advertise lowering target ${targetId}`);
}
const artifactPath = replaceStamp(captureContract.artifactPattern, stamp);
return {
schema: captureContract.requestSchema || "gamecult.eve.runtime_capture_request.v1",
runtimeId: capabilityManifest.runtimeId,
ownerRepo: captureContract.ownerRepo,
providerId: advertisement.providerId,
surfaceId: surface.surfaceId,
surfaceKind: surface.surfaceKind || "",
targetId,
projectionKind: surface.worldInteraction?.projectionKind || "",
commandBoundary: surface.worldInteraction?.commandBoundary || "",
receiptSchema: surface.worldInteraction?.receiptSchema || "",
captureKind: captureContract.captureKind,
artifactKind: captureContract.artifactKind,
artifactPath,
conformanceAttachment: captureContract.conformanceAttachment,
authority: captureContract.authority,
sourceAdvertisementPath: advertisementPath,
sourceCapabilityManifestPath: capabilityManifestPath,
issuedAtUtc: stamp,
};
}
export function loadJsonFile(filePath) {
return JSON.parse(readFileSync(filePath, "utf8"));
}
export function writeCaptureRequest(request, outputPath) {
mkdirSync(path.dirname(outputPath), { recursive: true });
writeFileSync(outputPath, `${JSON.stringify(request, null, 2)}\n`, "utf8");
}
function replaceStamp(pattern, stamp) {
if (!pattern || !pattern.includes("{stamp}")) {
throw new Error(`capture artifact pattern must include {stamp}: ${pattern || "missing"}`);
}
return pattern.replace("{stamp}", stamp);
}
function parseArgs(argv) {
const args = {};
for (let index = 0; index < argv.length; index += 1) {
const value = argv[index];
if (!value.startsWith("--")) continue;
const key = value.slice(2);
const next = argv[index + 1];
if (!next || next.startsWith("--")) {
args[key] = true;
} else {
args[key] = next;
index += 1;
}
}
return args;
}
function runCli() {
const args = parseArgs(process.argv.slice(2));
for (const required of ["advertisement", "capability", "output"]) {
if (!args[required]) {
throw new Error(`missing required --${required}`);
}
}
const stamp = args.stamp || new Date().toISOString().replace(/[:.]/g, "-");
const request = buildElectronCaptureRequest({
advertisement: loadJsonFile(args.advertisement),
capabilityManifest: loadJsonFile(args.capability),
advertisementPath: args.advertisement,
capabilityManifestPath: args.capability,
stamp,
});
writeCaptureRequest(request, args.output);
process.stdout.write(`${args.output}\n`);
}
const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
const modulePath = fileURLToPath(import.meta.url);
if (invokedPath === modulePath) {
runCli();
}

View file

@ -0,0 +1,40 @@
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import test from "node:test";
import { buildElectronCaptureRequest } from "./eveelectron-capture-contract.mjs";
const advertisement = JSON.parse(readFileSync(new URL("../../web/fixtures/aetheria.provider-advertisement.json", import.meta.url), "utf8"));
const capabilityManifest = JSON.parse(readFileSync(new URL("../../runtimes/incubating/eve-electron/eve-runtime-capability.json", import.meta.url), "utf8"));
test("builds Electron shell capture request from provider advertisement", () => {
const request = buildElectronCaptureRequest({
advertisement,
capabilityManifest,
advertisementPath: "web/fixtures/aetheria.provider-advertisement.json",
capabilityManifestPath: "runtimes/incubating/eve-electron/eve-runtime-capability.json",
stamp: "smoke",
});
assert.equal(request.schema, "gamecult.eve.runtime_capture_request.v1");
assert.equal(request.runtimeId, "electron-shell");
assert.equal(request.ownerRepo, "EveElectron");
assert.equal(request.providerId, "aetheria");
assert.equal(request.surfaceId, "aetheria.daemon.game");
assert.equal(request.targetId, "electron-shell");
assert.equal(request.projectionKind, "provider-authored-world-surface");
assert.equal(request.commandBoundary, "aetheria.daemon.commands");
assert.equal(request.receiptSchema, "aetheria.eve_command_acceptance_status.v1");
assert.equal(request.artifactPath, "artifacts/eveelectron-capture/smoke/electron-shell.png");
assert.match(request.authority, /provider state/);
});
test("rejects capture request when the surface does not advertise Electron shell", () => {
const withoutTarget = structuredClone(advertisement);
const surface = withoutTarget.surfaces.find(candidate => candidate.surfaceId === "aetheria.daemon.game");
surface.worldInteraction.loweringTargets = surface.worldInteraction.loweringTargets.filter(target => target !== "electron-shell");
assert.throws(
() => buildElectronCaptureRequest({ advertisement: withoutTarget, capabilityManifest, stamp: "smoke" }),
/does not advertise lowering target electron-shell/,
);
});

View file

@ -758,7 +758,10 @@
"runtimes/incubating/eve-electron/eveelectron-split-handoff.json",
"runtimes/incubating/eve-electron/eve-runtime-capability.json",
"scripts/run-eveelectron-lifecycle-smoke.ps1",
"scripts/run-eveelectron-provider-shell-smoke.ps1"
"scripts/run-eveelectron-provider-shell-smoke.ps1",
"scripts/run-eveelectron-capture-contract-smoke.ps1",
"tools/eveelectron/eveelectron-capture-contract.mjs",
"tools/eveelectron/eveelectron-capture-contract.test.mjs"
],
"expectedSourceSymbols": [
{
@ -768,6 +771,14 @@
{
"path": "runtimes/incubating/eve-electron/test/eve-electron-shell.test.mjs",
"contains": ["selects the active advertised provider surface", "lowers provider surface trees into an Electron shell projection", "rejects surface documents that do not match the advertised target", "command intents carry provider-advertised boundaries", "aetheria.daemon.commands", "aetheria.eve_command_acceptance_status.v1"]
},
{
"path": "tools/eveelectron/eveelectron-capture-contract.mjs",
"contains": ["buildElectronCaptureRequest", "gamecult.eve.runtime_capture_request.v1", "loweringTargets", "artifactPattern", "writeCaptureRequest"]
},
{
"path": "tools/eveelectron/eveelectron-capture-contract.test.mjs",
"contains": ["builds Electron shell capture request from provider advertisement", "rejects capture request when the surface does not advertise Electron shell", "electron-shell", "aetheria.daemon.commands"]
}
],
"capture": {