@comento/pota-harness 0.0.0-stage → 1.0.0

package/scripts/pota-lifecycle-lock.mjs

@@ -0,0 +1,205 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+export const DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS = 60_000;
+
+export function createLifecycleLock({ lifecycleLockPath }) {
+async function withLifecycleLock(operation, {
+  timeoutMs = DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS,
+  retryMs = 25,
+  malformedStaleMs = 30_000,
+  afterRelease,
+  testHooks = {},
+} = {}) {
+  await mkdir(dirname(lifecycleLockPath), { recursive: true });
+  if (process.env.POTA_TEST_PRUNE_LOCK_PARENT_BEFORE_ACQUIRE === "1") await rmdir(dirname(lifecycleLockPath));
+  const owner = { schemaVersion: 1, pid: process.pid, hostname: hostname(), nonce: randomUUID(), acquiredAt: new Date().toISOString() };
+  const deadline = Date.now() + timeoutMs;
+  let waitReported = false;
+  while (true) {
+    let acquired = false;
+    try {
+      await writeFile(lifecycleLockPath, `${JSON.stringify(owner)}\n`, { flag: "wx" });
+      await testHooks.afterLockWritten?.({ owner: structuredClone(owner) });
+      if (process.env.POTA_TEST_REPLACE_LOCK_AFTER_ACQUIRE === "1") {
+        await writeFile(lifecycleLockPath, `${JSON.stringify({ ...owner, nonce: randomUUID() })}\n`);
+      }
+      const written = parseLifecycleLock(await readFile(lifecycleLockPath, "utf8"));
+      if (written?.nonce !== owner.nonce) throw new Error("Pota lifecycle lock ownership changed after acquisition");
+      acquired = !(await activeReclaimClaimExists());
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        if (Date.now() >= deadline) throw new Error(`Timed out waiting for Pota lifecycle lock after ${timeoutMs}ms`);
+        await mkdir(dirname(lifecycleLockPath), { recursive: true });
+        continue;
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (!waitReported && process.env.POTA_TEST_REPORT_LOCK_WAIT === "1") {
+        console.log("POTA_TEST_LOCK_WAIT");
+        waitReported = true;
+      }
+      await testHooks.beforeContendedLockConfirmation?.();
+      acquired = await confirmsUnclaimedLifecycleLockOwnership(owner.nonce);
+      if (!acquired && await reclaimLifecycleLock(owner, malformedStaleMs, testHooks)) continue;
+    }
+    if (acquired) {
+      if (process.env.POTA_TEST_HOLD_LOCK_STDIN === "1") {
+        console.log("POTA_TEST_LOCK_ACQUIRED");
+        await new Promise((resolvePromise) => process.stdin.once("data", resolvePromise));
+      }
+      break;
+    }
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for Pota lifecycle lock after ${timeoutMs}ms`);
+    await delay(Math.min(retryMs, Math.max(1, deadline - Date.now())));
+  }
+  let operationSucceeded = false;
+  try {
+    const result = await operation();
+    operationSucceeded = true;
+    return result;
+  } finally {
+    if (process.env.POTA_TEST_REPLACE_LOCK_BEFORE_RELEASE === "1") {
+      await writeFile(lifecycleLockPath, `${JSON.stringify({ ...owner, nonce: randomUUID() })}\n`);
+    }
+    const released = await releaseOwnedLock(lifecycleLockPath, owner);
+    if (operationSucceeded && released && afterRelease) await afterRelease();
+  }
+}
+
+async function releaseOwnedLock(path, owner) {
+  let current;
+  try {
+    current = parseLifecycleLock(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  if (current?.nonce !== owner.nonce) return false;
+  const releasedPath = `${path}.released.${owner.nonce}`;
+  try {
+    await rename(path, releasedPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+  const released = parseLifecycleLock(await readFile(releasedPath, "utf8"));
+  if (released?.nonce !== owner.nonce) {
+    if (!(await exists(path))) await rename(releasedPath, path);
+    return false;
+  }
+  await rm(releasedPath, { force: true });
+  return true;
+}
+
+async function reclaimLifecycleLock(owner, malformedStaleMs, testHooks) {
+  let observed;
+  let info;
+  try {
+    [observed, info] = await Promise.all([readFile(lifecycleLockPath, "utf8"), lstat(lifecycleLockPath)]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  if (info.isSymbolicLink()) throw new Error(`Lifecycle lock must not be a symlink: ${lifecycleLockPath}`);
+  const record = parseLifecycleLock(observed);
+  if (!isReclaimableLifecycleLock(record, info, malformedStaleMs)) return false;
+  await testHooks.afterStaleObserved?.();
+
+  const claimPath = `${lifecycleLockPath}.reclaim.${owner.nonce}`;
+  await writeFile(claimPath, `${JSON.stringify(owner)}\n`, { flag: "wx" });
+  try {
+    await testHooks.afterReclaimInterlock?.();
+    let claimed;
+    let claimedInfo;
+    try {
+      [claimed, claimedInfo] = await Promise.all([readFile(lifecycleLockPath, "utf8"), lstat(lifecycleLockPath)]);
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+    if (claimedInfo.isSymbolicLink()) throw new Error(`Lifecycle lock must not be a symlink: ${lifecycleLockPath}`);
+    const claimedRecord = parseLifecycleLock(claimed);
+    if (!isReclaimableLifecycleLock(claimedRecord, claimedInfo, malformedStaleMs)) return false;
+
+    const quarantine = `${lifecycleLockPath}.stale.${claimedRecord?.nonce ?? "malformed"}.${randomUUID()}`;
+    try {
+      await rename(lifecycleLockPath, quarantine);
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+    if (await readFile(quarantine, "utf8") !== claimed) {
+      if (!(await exists(lifecycleLockPath))) await rename(quarantine, lifecycleLockPath);
+      throw new Error("Pota lifecycle lock ownership changed during stale recovery");
+    }
+    await rm(quarantine, { force: true });
+    return true;
+  } finally {
+    await releaseOwnedLock(claimPath, owner);
+  }
+}
+
+function isReclaimableLifecycleLock(record, info, malformedStaleMs) {
+  if (record) return record.hostname === hostname() && !pidIsAlive(record.pid);
+  return Date.now() - info.mtimeMs > malformedStaleMs;
+}
+
+async function confirmsUnclaimedLifecycleLockOwnership(nonce) {
+  if (await activeReclaimClaimExists()) return false;
+  try {
+    return parseLifecycleLock(await readFile(lifecycleLockPath, "utf8"))?.nonce === nonce;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function activeReclaimClaimExists() {
+  const claimNames = (await readdir(dirname(lifecycleLockPath)))
+    .filter((name) => name.startsWith(`${basename(lifecycleLockPath)}.reclaim.`));
+  for (const name of claimNames) {
+    const claimPath = join(dirname(lifecycleLockPath), name);
+    let info;
+    let record;
+    try {
+      [info, record] = await Promise.all([lstat(claimPath), readFile(claimPath, "utf8").then(parseLifecycleLock)]);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+    if (info.isSymbolicLink()) throw new Error(`Lifecycle reclaim claim must not be a symlink: ${claimPath}`);
+    if (record?.hostname === hostname() && !pidIsAlive(record.pid)) {
+      await releaseOwnedLock(claimPath, record);
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+function parseLifecycleLock(text) {
+  try {
+    const value = JSON.parse(text);
+    if (value?.schemaVersion !== 1 || !Number.isSafeInteger(value.pid) || value.pid <= 0
+        || typeof value.hostname !== "string" || value.hostname.length === 0 || typeof value.nonce !== "string" || value.nonce.length === 0
+        || typeof value.acquiredAt !== "string" || Number.isNaN(Date.parse(value.acquiredAt))) return null;
+    return value;
+  } catch { return null; }
+}
+
+function pidIsAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; }
+}
+
+function delay(ms) { return new Promise((resolvePromise) => setTimeout(resolvePromise, ms)); }
+
+
+  return { withLifecycleLock };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/pota-lifecycle-mirror.mjs

@@ -0,0 +1,83 @@
+import { lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve, win32 } from "node:path";
+import {
+  RUNTIME_LOCATOR_SCHEMA_VERSION,
+  createRuntimeLocator,
+  runtimeRequiredPaths,
+} from "./pota-paths.mjs";
+
+export function antigravityRuntimeLocatorPath(root) {
+  return join(root, "pota", "runtime.json");
+}
+
+export function installedSkillLocatorPath(runtimeRoot, name) {
+  return join(runtimeRoot, "skills", name, "references", "pota-runtime.json");
+}
+
+export function antigravitySkillLocatorPath(root, name) {
+  return join(root, "skills", name, "references", "pota-runtime.json");
+}
+
+export async function writeLocator(path, root) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(createRuntimeLocator(root), null, 2)}\n`);
+}
+
+export async function validRuntimeLocator(path, runtimeRoot) {
+  try {
+    const locator = JSON.parse(await readFile(path, "utf8"));
+    const expected = createRuntimeLocator(runtimeRoot);
+    if (locator?.schemaVersion !== RUNTIME_LOCATOR_SCHEMA_VERSION || resolve(locator.pluginRoot ?? ".") !== resolve(runtimeRoot)) return false;
+    for (const [name, value] of Object.entries(expected.entrypoints)) if (locator.entrypoints?.[name] !== value) return false;
+    for (const [name, value] of Object.entries(expected.resources)) if (locator.resources?.[name] !== value) return false;
+    return (await Promise.all(runtimeRequiredPaths(locator).map(exists))).every(Boolean);
+  } catch {
+    return false;
+  }
+}
+
+export async function renderMirrorFile(source, destination, { locatorPath, runtimeRoot, includeLocatorNotice = false }) {
+  const content = await readFile(source, "utf8");
+  const notice = includeLocatorNotice ? `\n\n## Installed Pota runtime\n\nRead the structured runtime locator at \`${JSON.stringify(locatorPath)}\`. Resolve Pota scripts and static resources from its absolute paths, never from the target project.\n` : "";
+  await mkdir(dirname(destination), { recursive: true });
+  await writeFile(destination, `${renderInstalledMirror(content, { runtimeRoot, locatorPath }).trimEnd()}${notice}`);
+}
+
+export function renderInstalledMirror(content, { runtimeRoot, locatorPath, platform = process.platform }) {
+  const platformJoin = platform === "win32" ? win32.join : posix.join;
+  const quotedCli = quoteShellArg(platformJoin(runtimeRoot, "scripts", "pota.mjs"), platform);
+  let rendered = content.replaceAll("{{POTA_RUNTIME_LOCATOR_JSON}}", JSON.stringify(locatorPath))
+    .replace(/\bnode\s+scripts\/pota\.mjs\b/g, `node ${quotedCli}`)
+    .replace(/\bnode\s+scripts\/([A-Za-z0-9._/-]+)/g, (_, path) => `node ${quoteShellArg(platformJoin(runtimeRoot, "scripts", path), platform)}`);
+  rendered = rendered.replace(/(^|[\s`("'=])(commands|agents|templates|docs\/model-guidance)\/([A-Za-z0-9._<>/-]+)/gm,
+    (_, prefix, directory, suffix) => `${prefix}${platformJoin(runtimeRoot, directory, suffix)}`);
+  return rendered;
+}
+
+export function quoteShellArg(value, platform = process.platform) {
+  return platform === "win32" ? `"${value.replaceAll('"', '""')}"` : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export async function validateAntigravitySkills(root, skillNames, runtimeRoot) {
+  try {
+    if (!(await validRuntimeLocator(antigravityRuntimeLocatorPath(root), runtimeRoot))) return false;
+    for (const name of skillNames) {
+      const content = await readFile(join(root, "skills", `${name}.md`), "utf8");
+      if (!/^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(content) || !/^name:\s*\S+/m.test(content) || !/^description:\s*\S+/m.test(content)) return false;
+      if (!content.includes(JSON.stringify(antigravityRuntimeLocatorPath(root)))) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}

package/scripts/pota-lifecycle-staging.mjs

@@ -0,0 +1,156 @@
+import { copyFile, cp, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { readSharedConfigSnapshot, trustedHookStates } from "./pota-lifecycle-config.mjs";
+import {
+  antigravityRuntimeLocatorPath, antigravitySkillLocatorPath, renderMirrorFile, writeLocator,
+} from "./pota-lifecycle-mirror.mjs";
+import { stageClaudePlugin } from "./pota-lifecycle-claude.mjs";
+import { HOSTS } from "./pota-lifecycle-hosts.mjs";
+
+export function createStaging(context) {
+  const {
+    agentNames, antigravityCliHome, antigravityHome, claudeHome, claudePluginMarketplaceRoot,
+    claudeRuntimeLocatorPath, codexRuntimeRoot, commandNames, releaseVersion, configPath, installedPluginRoot,
+    marketplaceJsonPath, marketplaceName, pluginName,
+    pluginRoot, runtimeRoot, skillNames, updateConfig, assertRegularTree,
+  } = context;
+// The canonical runtime is always staged; each selected host adds its own targets (see pota-lifecycle-hosts.mjs).
+async function stageInstall(stageRoot, hosts = HOSTS) {
+  const targets = [];
+  const add = (id, phase, destination, staged, type = "tree", details = {}) => targets.push({ id, phase, path: destination, staged, type, ...details });
+  // Every copy carries locators to the canonical runtime, so mirrors and hooks never depend on a host cache.
+  const runtimeStage = join(stageRoot, "runtime");
+  await copyPluginCandidate(runtimeStage, runtimeRoot);
+  add("runtime", "core", runtimeRoot, runtimeStage);
+  if (hosts.includes("codex")) await stageCodex(stageRoot, add);
+  if (hosts.includes("claude")) await stageClaude(stageRoot, runtimeStage, add);
+  if (hosts.includes("antigravity")) {
+    await stageAntigravity(targets, stageRoot, runtimeStage, antigravityHome, "ide", false);
+    await stageAntigravity(targets, stageRoot, runtimeStage, antigravityCliHome, "cli", true);
+  }
+  if (hosts.includes("codex")) {
+    const configStage = join(stageRoot, "config.toml");
+    const hookStates = await trustedHookStates(runtimeStage);
+    const configSnapshot = await readSharedConfigSnapshot(configPath);
+    await writeFile(configStage, updateConfig(configSnapshot.text, hookStates));
+    add("codex-config", "config", configPath, configStage, "config", { configSourceDigest: configSnapshot.digest });
+  }
+  for (const target of targets) await assertRegularTree(target.staged);
+  return targets;
+}
+
+async function stageCodex(stageRoot, add) {
+  const sourceStage = join(stageRoot, "codex-source");
+  const codexRuntimeStage = join(stageRoot, "codex-runtime");
+  await copyPluginCandidate(sourceStage, runtimeRoot);
+  await copyPluginCandidate(codexRuntimeStage, runtimeRoot);
+  add("codex-source", "codex", installedPluginRoot, sourceStage);
+  add("codex-runtime", "codex", codexRuntimeRoot, codexRuntimeStage);
+
+  const marketplaceStage = join(stageRoot, "marketplace.json");
+  await writeFile(marketplaceStage, `${JSON.stringify({
+    name: marketplaceName,
+    interface: { displayName: "Pota" },
+    plugins: [{ name: pluginName, source: { source: "local", path: "./plugins/pota" }, policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: "Productivity" }],
+  }, null, 2)}\n`);
+  add("marketplace", "codex", marketplaceJsonPath, marketplaceStage, "file");
+}
+
+async function stageClaude(stageRoot, runtimeStage, add) {
+  const claudeLocator = join(stageRoot, "claude-runtime.json");
+  await writeLocator(claudeLocator, runtimeRoot);
+  add("claude-runtime", "claude", claudeRuntimeLocatorPath, claudeLocator, "file");
+  for (const name of commandNames()) {
+    const staged = join(stageRoot, "claude-commands", `pota-${name}.md`);
+    await renderMirrorFile(join(runtimeStage, ".claude", "commands", `pota-${name}.md`), staged, { locatorPath: claudeRuntimeLocatorPath, runtimeRoot });
+    add(`claude-command-${name}`, "claude", join(claudeHome, "commands", `pota-${name}.md`), staged, "file");
+  }
+  for (const name of agentNames()) {
+    const staged = join(stageRoot, "claude-agents", `pota-${name}.md`);
+    await renderMirrorFile(join(runtimeStage, ".claude", "agents", `${name}.md`), staged, { locatorPath: claudeRuntimeLocatorPath, runtimeRoot });
+    add(`claude-agent-${name}`, "claude", join(claudeHome, "agents", `pota-${name}.md`), staged, "file");
+  }
+
+  const claudePluginStage = await stageClaudePlugin({
+    stageRoot, runtimeStage, destinationRoot: claudePluginMarketplaceRoot, runtimeRoot,
+    marketplaceName, pluginName, releaseVersion, skillNames: skillNames(),
+  });
+  add("claude-plugin", "claude", claudePluginMarketplaceRoot, claudePluginStage);
+}
+
+async function stageAntigravity(targets, stageRoot, runtimeStage, destinationRoot, label, flatSkills) {
+  const locatorPath = antigravityRuntimeLocatorPath(destinationRoot);
+  const locatorStage = join(stageRoot, `${label}-runtime.json`);
+  await writeLocator(locatorStage, runtimeRoot);
+  targets.push({ id: `${label}-runtime`, phase: "antigravity", path: locatorPath, staged: locatorStage, type: "file" });
+  for (const name of skillNames()) {
+    if (flatSkills) {
+      const staged = join(stageRoot, `${label}-skills`, `${name}.md`);
+      await renderMirrorFile(join(runtimeStage, "skills", name, "SKILL.md"), staged, { locatorPath, runtimeRoot, includeLocatorNotice: true });
+      targets.push({ id: `${label}-skill-${name}`, phase: "antigravity", path: join(destinationRoot, "skills", `${name}.md`), staged, type: "file" });
+    } else {
+      const staged = join(stageRoot, `${label}-skills`, name);
+      await cp(join(runtimeStage, "skills", name), staged, { recursive: true });
+      await renderMirrorFile(join(runtimeStage, "skills", name, "SKILL.md"), join(staged, "SKILL.md"), {
+        locatorPath: antigravitySkillLocatorPath(destinationRoot, name),
+        runtimeRoot,
+        includeLocatorNotice: true,
+      });
+      await writeLocator(join(staged, "references", "pota-runtime.json"), runtimeRoot);
+      targets.push({ id: `${label}-skill-${name}`, phase: "antigravity", path: join(destinationRoot, "skills", name), staged, type: "tree" });
+    }
+  }
+  for (const name of commandNames()) {
+    const staged = join(stageRoot, `${label}-workflows`, `pota-${name}.md`);
+    await renderMirrorFile(join(runtimeStage, ".agents", "workflows", `pota-${name}.md`), staged, { locatorPath, runtimeRoot });
+    targets.push({ id: `${label}-workflow-${name}`, phase: "antigravity", path: join(destinationRoot, "workflows", `pota-${name}.md`), staged, type: "file" });
+  }
+}
+
+async function copyPluginCandidate(destination, locatorRoot) {
+  await copyPluginTree(pluginRoot, destination);
+  const manifestPath = join(destination, ".codex-plugin", "plugin.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.hooks = "./hooks/hooks.json";
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeLocator(join(destination, ".pota-runtime.json"), locatorRoot);
+  for (const name of skillNames()) await writeLocator(join(destination, "skills", name, "references", "pota-runtime.json"), locatorRoot);
+}
+
+async function copyPluginTree(source, destination) {
+  if (!shouldCopyPluginPath(source, pluginRoot)) return;
+  const info = await lstat(source);
+  if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) {
+    throw new Error(`Plugin source must contain only regular files and directories: ${source}`);
+  }
+  if (info.isFile()) {
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(source, destination);
+    return;
+  }
+  await mkdir(destination, { recursive: true });
+  const entries = await readdir(source);
+  entries.sort();
+  for (const entry of entries) await copyPluginTree(join(source, entry), join(destination, entry));
+}
+
+  return { stageInstall };
+}
+
+export function pathHasSegment(path, segment) { return path.split(/[\\/]+/).includes(segment); }
+
+export function shouldCopyPluginPath(source, pluginRoot) {
+  const name = source.split(/[\\/]+/).at(-1);
+  if ([".git", "node_modules", ".pota"].includes(name)) return false;
+  if (sep === "/" && source.includes("\\")) return true;
+  const relativePath = relative(pluginRoot, source);
+  if (isAbsolute(relativePath)) return true;
+  const path = relativePath.split(sep).join("/");
+  if (path === "") return true;
+  if (path.startsWith("../") || path === "..") return true;
+  if (/^(package\.json|LICENSE|README(?:\.[^.]+)?\.md)$/.test(path)) return true;
+  if (path === "docs") return true;
+  if (path.startsWith("docs/")) return path === "docs/model-guidance" || path.startsWith("docs/model-guidance/");
+  return [".agents", ".claude", ".codex-plugin", "agents", "commands", "hooks", "scripts", "skills", "templates"]
+    .some((directory) => path === directory || path.startsWith(`${directory}/`));
+}