Add Electron release request contract

docs/eve-migration-roadmap.md

@@ -437,10 +437,12 @@ Recently cut:
   lifecycle smoke at `scripts/run-eveelectron-lifecycle-smoke.ps1`. The
   manifest declares provider advertisement consumption, command transport, and
   surface-tree projection, claims `electron-shell` world/editor lowering, and
-  now carries an executable capture request contract through
+  now carries executable release and capture request contracts. Release uses
+  `tools/eveelectron/eveelectron-release-contract.mjs` and
+  `scripts/run-eveelectron-release-contract-smoke.ps1`; capture uses
   `tools/eveelectron/eveelectron-capture-contract.mjs` and
-  `scripts/run-eveelectron-capture-contract-smoke.ps1`. Package release,
-  packaged window rendering, plugin projection, and actual Electron window
+  `scripts/run-eveelectron-capture-contract-smoke.ps1`. The packaged Electron
+  app, packaged window rendering, plugin projection, and actual Electron window
   capture artifacts remain pending EveElectron work.
 - Electron and TUI pending lifecycle details now live in their runtime
   capability manifests rather than being duplicated in
@@ -515,6 +517,14 @@ Recently cut:
   `scripts/run-eveelectron-capture-contract-smoke.ps1` proves that request path
   without pretending an Electron window PNG has been captured. The actual
   capture artifact remains a split blocker for EveElectron.
+- EveElectron release lifecycle now carries a structured pending release
+  request contract. `releaseContract` names
+  `gamecult.eve.runtime_release_request.v1`, the
+  `tools/eveelectron/eveelectron-release-contract.mjs` request builder,
+  `runtimes/incubating/eve-electron/package.json` as the version source, and
+  the `eveelectron-v{version}` tag/artifact pattern.
+  `scripts/run-eveelectron-release-contract-smoke.ps1` proves the request
+  without pretending a packaged Electron app has been published.
 - Unity scene capture now uses that same request-contract shape. The
   `unity-scene` runtime capability manifest names
   `gamecult.eve.runtime_capture_request.v1`, the shared

runtimes/incubating/eve-electron/eve-runtime-capability.json

@@ -62,16 +62,22 @@
         "ownerRepo": "EveElectron",
         "packageName": "eve-electron",
         "packageRoot": "runtimes/incubating/eve-electron",
-        "versionSource": "runtimes/incubating/eve-electron/eve-runtime-capability.json",
+        "versionSource": "runtimes/incubating/eve-electron/package.json",
         "tagPattern": "eveelectron-v{version}",
         "artifactKind": "electron-app",
+        "requestSchema": "gamecult.eve.runtime_release_request.v1",
+        "requestBuilder": "tools/eveelectron/eveelectron-release-contract.mjs",
+        "artifactPattern": "artifacts/eveelectron-release/{version}/eve-electron-{version}.zip",
         "publishProof": "Packaged Electron release is created from the EveElectron repo and references the provider-agnostic shell package root."
       },
       "evidencePaths": [
         "runtimes/incubating/eve-electron/package.json",
         "runtimes/incubating/eve-electron/src/eve-electron-shell.mjs",
         "runtimes/incubating/eve-electron/eveelectron-split-handoff.json",
-        "scripts/run-eveelectron-split-handoff-smoke.ps1"
+        "scripts/run-eveelectron-split-handoff-smoke.ps1",
+        "scripts/run-eveelectron-release-contract-smoke.ps1",
+        "tools/eveelectron/eveelectron-release-contract.mjs",
+        "tools/eveelectron/eveelectron-release-contract.test.mjs"
       ],
       "pendingProofs": [
         "Electron packaged app release is cut from EveElectron rather than Eve incubation."

scripts/run-eveelectron-lifecycle-smoke.ps1

@@ -106,11 +106,14 @@ foreach ($stage in @("release", "test", "capture")) {
 }
 
 $releaseContract = $manifest.lifecycle.release.releaseContract
-foreach ($field in @("ownerRepo", "packageName", "packageRoot", "versionSource", "tagPattern", "artifactKind", "publishProof")) {
+foreach ($field in @("ownerRepo", "packageName", "packageRoot", "versionSource", "tagPattern", "artifactKind", "requestSchema", "requestBuilder", "artifactPattern", "publishProof")) {
   if (-not $releaseContract.$field) {
     throw "EveElectron release contract missing $field"
   }
 }
+if ($releaseContract.requestSchema -ne "gamecult.eve.runtime_release_request.v1") {
+  throw "EveElectron release contract has unexpected request schema: $($releaseContract.requestSchema)"
+}
 foreach ($pathProperty in @("packageRoot", "versionSource")) {
   $relativePath = $releaseContract.$pathProperty
   $absolutePath = Join-Path $projectRoot $relativePath
@@ -118,6 +121,13 @@ foreach ($pathProperty in @("packageRoot", "versionSource")) {
     throw "EveElectron release contract $pathProperty does not exist: $relativePath"
   }
 }
+foreach ($pathProperty in @("requestBuilder")) {
+  $relativePath = $releaseContract.$pathProperty
+  $absolutePath = Join-Path $projectRoot $relativePath
+  if (-not (Test-Path -LiteralPath $absolutePath)) {
+    throw "EveElectron release contract $pathProperty does not exist: $relativePath"
+  }
+}
 
 $testContract = $manifest.lifecycle.test.testContract
 foreach ($field in @("ownerRepo", "runnerKind", "runnerScript", "consumerProject", "packageName", "testAssembly", "testPlatform", "resultsArtifact", "logArtifact", "manifestMutation")) {
@@ -164,6 +174,7 @@ foreach ($pathProperty in @("requestBuilder", "advertisementPath")) {
 }
 
 & (Join-Path $projectRoot "scripts\run-eveelectron-split-handoff-smoke.ps1")
+& (Join-Path $projectRoot "scripts\run-eveelectron-release-contract-smoke.ps1")
 & (Join-Path $projectRoot "scripts\run-eveelectron-provider-shell-smoke.ps1")
 & (Join-Path $projectRoot "scripts\run-eveelectron-capture-contract-smoke.ps1")
 

scripts/run-eveelectron-release-contract-smoke.ps1

@@ -0,0 +1,98 @@
+param(
+  [string] $CapabilityManifestPath = "runtimes\incubating\eve-electron\eve-runtime-capability.json",
+  [string] $OutputPath = "artifacts\eveelectron-release-contract\latest\release-request.json"
+)
+
+$ErrorActionPreference = "Stop"
+
+$projectRoot = Split-Path -Parent $PSScriptRoot
+$absoluteCapabilityPath = if ([System.IO.Path]::IsPathRooted($CapabilityManifestPath)) {
+  $CapabilityManifestPath
+} else {
+  Join-Path $projectRoot $CapabilityManifestPath
+}
+$absoluteOutputPath = if ([System.IO.Path]::IsPathRooted($OutputPath)) {
+  $OutputPath
+} else {
+  Join-Path $projectRoot $OutputPath
+}
+
+if (-not (Test-Path -LiteralPath $absoluteCapabilityPath)) {
+  throw "EveElectron release contract input not found: $absoluteCapabilityPath"
+}
+
+$manifest = Get-Content -LiteralPath $absoluteCapabilityPath -Raw | ConvertFrom-Json
+$releaseContract = $manifest.lifecycle.release.releaseContract
+if ($null -eq $releaseContract) {
+  throw "EveElectron release contract missing lifecycle.release.releaseContract"
+}
+foreach ($field in @("ownerRepo", "packageName", "packageRoot", "versionSource", "tagPattern", "artifactKind", "requestSchema", "requestBuilder", "artifactPattern", "publishProof")) {
+  if (-not $releaseContract.$field) {
+    throw "EveElectron release contract missing $field"
+  }
+}
+if ($releaseContract.ownerRepo -ne "EveElectron") {
+  throw "Unexpected EveElectron release owner: $($releaseContract.ownerRepo)"
+}
+if ($releaseContract.packageName -ne "eve-electron") {
+  throw "Unexpected EveElectron package name: $($releaseContract.packageName)"
+}
+if ($releaseContract.requestSchema -ne "gamecult.eve.runtime_release_request.v1") {
+  throw "Unexpected EveElectron release request schema: $($releaseContract.requestSchema)"
+}
+if ($releaseContract.artifactKind -ne "electron-app") {
+  throw "Unexpected EveElectron release artifact kind: $($releaseContract.artifactKind)"
+}
+
+$builderPath = Join-Path $projectRoot $releaseContract.requestBuilder
+$packagePath = Join-Path $projectRoot $releaseContract.versionSource
+$packageRoot = Join-Path $projectRoot $releaseContract.packageRoot
+foreach ($path in @($builderPath, $packagePath, $packageRoot)) {
+  if (-not (Test-Path -LiteralPath $path)) {
+    throw "EveElectron release contract path not found: $path"
+  }
+}
+
+node --test (Join-Path $projectRoot "tools\eveelectron\eveelectron-release-contract.test.mjs")
+if ($LASTEXITCODE -ne 0) {
+  throw "EveElectron release contract tests failed with exit code $LASTEXITCODE"
+}
+
+node $builderPath --capability $absoluteCapabilityPath --package $packagePath --output $absoluteOutputPath
+if ($LASTEXITCODE -ne 0) {
+  throw "EveElectron release request builder failed with exit code $LASTEXITCODE"
+}
+if (-not (Test-Path -LiteralPath $absoluteOutputPath)) {
+  throw "EveElectron release request was not written: $absoluteOutputPath"
+}
+
+$request = Get-Content -LiteralPath $absoluteOutputPath -Raw | ConvertFrom-Json
+$packageManifest = Get-Content -LiteralPath $packagePath -Raw | ConvertFrom-Json
+foreach ($expectation in @(
+  @{ field = "schema"; value = "gamecult.eve.runtime_release_request.v1" },
+  @{ field = "ownerRepo"; value = "EveElectron" },
+  @{ field = "repository"; value = "GameCult/EveElectron" },
+  @{ field = "packageName"; value = "eve-electron" },
+  @{ field = "version"; value = $packageManifest.version },
+  @{ field = "packageRoot"; value = "runtimes/incubating/eve-electron" },
+  @{ field = "versionSource"; value = "runtimes/incubating/eve-electron/package.json" },
+  @{ field = "artifactKind"; value = "electron-app" }
+)) {
+  if ($request.($expectation.field) -ne $expectation.value) {
+    throw "EveElectron release request $($expectation.field) expected $($expectation.value) got $($request.($expectation.field))"
+  }
+}
+
+$expectedTagName = $releaseContract.tagPattern.Replace("{version}", $packageManifest.version)
+if ($request.tagName -ne $expectedTagName) {
+  throw "Unexpected EveElectron release tag: $($request.tagName)"
+}
+$expectedArtifactPath = $releaseContract.artifactPattern.Replace("{version}", $packageManifest.version)
+if ($request.artifactPath -ne $expectedArtifactPath) {
+  throw "Unexpected EveElectron release artifact path: $($request.artifactPath)"
+}
+if ($request.main -ne $packageManifest.main) {
+  throw "EveElectron release request lost package main entry"
+}
+
+Write-Host "EveElectron release contract smoke passed: $absoluteOutputPath"

scripts/run-runtime-owner-conformance-consumer-smoke.ps1

@@ -172,6 +172,10 @@ node $consumerScript $consumerExport `
   --expect-runtime-lifecycle-pending "electron-shell:test:Electron provider-advertisement smoke runs from EveElectron in a packaged Electron window" `
   --expect-runtime-lifecycle-pending "electron-shell:capture:Electron window capture artifact" `
   --expect-runtime-lifecycle-field "electron-shell:release:releaseContract.artifactKind:electron-app" `
+  --expect-runtime-lifecycle-field "electron-shell:release:releaseContract.versionSource:runtimes/incubating/eve-electron/package.json" `
+  --expect-runtime-lifecycle-field "electron-shell:release:releaseContract.requestSchema:gamecult.eve.runtime_release_request.v1" `
+  --expect-runtime-lifecycle-field "electron-shell:release:releaseContract.requestBuilder:tools/eveelectron/eveelectron-release-contract.mjs" `
+  --expect-runtime-lifecycle-field "electron-shell:release:releaseContract.artifactPattern:artifacts/eveelectron-release/{version}/eve-electron-{version}.zip" `
   --expect-runtime-lifecycle-field "electron-shell:test:testContract.runnerKind:electron-provider-shell-smoke" `
   --expect-runtime-lifecycle-field "electron-shell:test:testContract.runnerScript:scripts/run-eveelectron-provider-shell-smoke.ps1" `
   --expect-runtime-lifecycle-field "electron-shell:capture:captureContract.captureKind:electron-window-png" `

tools/eveelectron/eveelectron-release-contract.mjs

@@ -0,0 +1,114 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function buildElectronReleaseRequest({
+  capabilityManifest,
+  packageManifest,
+  capabilityManifestPath = "",
+  packageManifestPath = "",
+  repository = "GameCult/EveElectron",
+} = {}) {
+  if (!capabilityManifest || typeof capabilityManifest !== "object") {
+    throw new Error("capabilityManifest is required");
+  }
+  if (!packageManifest || typeof packageManifest !== "object") {
+    throw new Error("packageManifest is required");
+  }
+
+  const releaseContract = capabilityManifest.lifecycle?.release?.releaseContract;
+  if (!releaseContract) {
+    throw new Error("capability manifest is missing lifecycle.release.releaseContract");
+  }
+
+  if (packageManifest.name !== releaseContract.packageName) {
+    throw new Error(`package name mismatch: expected ${releaseContract.packageName} got ${packageManifest.name || "missing"}`);
+  }
+  if (!packageManifest.version || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(packageManifest.version)) {
+    throw new Error(`package version is not a SemVer-compatible release version: ${packageManifest.version || "missing"}`);
+  }
+
+  const tagName = replaceVersion(releaseContract.tagPattern, packageManifest.version);
+  const artifactPath = replaceVersion(
+    releaseContract.artifactPattern || `artifacts/eveelectron-release/{version}/${releaseContract.packageName}-{version}.zip`,
+    packageManifest.version,
+  );
+
+  return {
+    schema: releaseContract.requestSchema || "gamecult.eve.runtime_release_request.v1",
+    ownerRepo: releaseContract.ownerRepo,
+    repository,
+    packageName: releaseContract.packageName,
+    version: packageManifest.version,
+    packageRoot: releaseContract.packageRoot,
+    versionSource: releaseContract.versionSource,
+    tagName,
+    artifactKind: releaseContract.artifactKind,
+    artifactPath,
+    publishProof: releaseContract.publishProof,
+    sourceCapabilityManifestPath: capabilityManifestPath,
+    sourcePackageManifestPath: packageManifestPath,
+    main: packageManifest.main || "",
+    scripts: packageManifest.scripts || {},
+    dependencies: packageManifest.dependencies || {},
+    devDependencies: packageManifest.devDependencies || {},
+  };
+}
+
+export function loadJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+
+export function writeReleaseRequest(request, outputPath) {
+  mkdirSync(path.dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(request, null, 2)}\n`, "utf8");
+}
+
+function replaceVersion(pattern, version) {
+  if (!pattern || !pattern.includes("{version}")) {
+    throw new Error(`release pattern must include {version}: ${pattern || "missing"}`);
+  }
+  return pattern.replaceAll("{version}", version);
+}
+
+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 ["capability", "package", "output"]) {
+    if (!args[required]) {
+      throw new Error(`missing required --${required}`);
+    }
+  }
+
+  const request = buildElectronReleaseRequest({
+    capabilityManifest: loadJsonFile(args.capability),
+    packageManifest: loadJsonFile(args.package),
+    capabilityManifestPath: args.capability,
+    packageManifestPath: args.package,
+    repository: args.repository || "GameCult/EveElectron",
+  });
+  writeReleaseRequest(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();
+}

tools/eveelectron/eveelectron-release-contract.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { buildElectronReleaseRequest } from "./eveelectron-release-contract.mjs";
+
+const capabilityManifest = JSON.parse(readFileSync(new URL("../../runtimes/incubating/eve-electron/eve-runtime-capability.json", import.meta.url), "utf8"));
+const packageManifest = JSON.parse(readFileSync(new URL("../../runtimes/incubating/eve-electron/package.json", import.meta.url), "utf8"));
+
+test("builds EveElectron release request from package manifest", () => {
+  const request = buildElectronReleaseRequest({
+    capabilityManifest,
+    packageManifest,
+    capabilityManifestPath: "runtimes/incubating/eve-electron/eve-runtime-capability.json",
+    packageManifestPath: "runtimes/incubating/eve-electron/package.json",
+  });
+
+  assert.equal(request.schema, "gamecult.eve.runtime_release_request.v1");
+  assert.equal(request.ownerRepo, "EveElectron");
+  assert.equal(request.repository, "GameCult/EveElectron");
+  assert.equal(request.packageName, "eve-electron");
+  assert.equal(request.version, "0.1.0");
+  assert.equal(request.packageRoot, "runtimes/incubating/eve-electron");
+  assert.equal(request.versionSource, "runtimes/incubating/eve-electron/package.json");
+  assert.equal(request.tagName, "eveelectron-v0.1.0");
+  assert.equal(request.artifactKind, "electron-app");
+  assert.equal(request.artifactPath, "artifacts/eveelectron-release/0.1.0/eve-electron-0.1.0.zip");
+  assert.equal(request.main, "src/eve-electron-shell.mjs");
+});
+
+test("rejects package manifests that do not match the Electron release contract", () => {
+  const wrongPackage = { ...packageManifest, name: "eve-wrong" };
+
+  assert.throws(
+    () => buildElectronReleaseRequest({ capabilityManifest, packageManifest: wrongPackage }),
+    /package name mismatch/,
+  );
+});

tools/parity/parity-manifest.json

@@ -759,7 +759,10 @@
         "runtimes/incubating/eve-electron/eve-runtime-capability.json",
         "scripts/run-eveelectron-lifecycle-smoke.ps1",
         "scripts/run-eveelectron-provider-shell-smoke.ps1",
+        "scripts/run-eveelectron-release-contract-smoke.ps1",
         "scripts/run-eveelectron-capture-contract-smoke.ps1",
+        "tools/eveelectron/eveelectron-release-contract.mjs",
+        "tools/eveelectron/eveelectron-release-contract.test.mjs",
         "tools/eveelectron/eveelectron-capture-contract.mjs",
         "tools/eveelectron/eveelectron-capture-contract.test.mjs"
       ],
@@ -779,6 +782,14 @@
         {
           "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"]
+        },
+        {
+          "path": "tools/eveelectron/eveelectron-release-contract.mjs",
+          "contains": ["buildElectronReleaseRequest", "gamecult.eve.runtime_release_request.v1", "eveelectron-release", "writeReleaseRequest"]
+        },
+        {
+          "path": "tools/eveelectron/eveelectron-release-contract.test.mjs",
+          "contains": ["builds EveElectron release request from package manifest", "eveelectron-v0.1.0", "artifacts/eveelectron-release/0.1.0/eve-electron-0.1.0.zip"]
         }
       ],
       "capture": {