@getformation/cloud-cli 1.0.0

package/src/installer.mjs

@@ -0,0 +1,520 @@
+import { randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  unlink,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { fail } from "./errors.mjs";
+import {
+  downloadSkillBundle,
+  isArtifactRevisionId,
+  isCanonicalSkillPath,
+  manifestFromOperation,
+  revalidateCurrentManifest,
+  sha256Bytes,
+  SKILL_LIMITS,
+} from "./manifest.mjs";
+
+export const RECEIPT_NAME = ".formation-cloud-install.json";
+const RECEIPT_SCHEMA_VERSION = 1;
+const PACKAGE_VERSION = "1.0.0";
+const MAX_LOCAL_ENTRIES = 512;
+const MAX_RECEIPT_BYTES = 65_536;
+const SHA256 = /^[0-9a-f]{64}$/u;
+
+function conflict(message, details) {
+  fail("install_conflict", message, "Choose an absent target path, or restore the exact receipt-owned install before replacement.", details);
+}
+
+function identity(info) {
+  return { dev: info.dev, ino: info.ino, uid: info.uid, gid: info.gid, mode: info.mode, type: info.isDirectory() ? "directory" : info.isFile() ? "file" : "other" };
+}
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.type === right.type;
+}
+
+function assertOwnedSafeMetadata(info, subject, {
+  uid = typeof process.getuid === "function" ? process.getuid() : info.uid,
+  gid = typeof process.getgid === "function" ? process.getgid() : info.gid,
+} = {}) {
+  if (info.uid !== uid || info.gid !== gid) conflict(`${subject} has foreign ownership.`);
+  if ((info.mode & 0o022) !== 0) conflict(`${subject} is group- or world-writable.`);
+}
+
+function currentIdentity(info, subject) {
+  assertOwnedSafeMetadata(info, subject);
+}
+
+async function maybeLstat(filePath) {
+  try { return await lstat(filePath); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function assertExactTarget(target) {
+  if (typeof target !== "string" || !path.isAbsolute(target) || path.resolve(target) !== target) {
+    fail("invalid_target", "The Skill target must be one exact normalized absolute path.",
+      "Pass --target with an absolute path that contains no dot segments or trailing separator.");
+  }
+  const root = path.parse(target).root;
+  const home = path.resolve(os.homedir());
+  if (target === root || target === home) {
+    fail("unsafe_target", "The filesystem root and home directory cannot be Skill install targets.",
+      "Choose a dedicated absent Skill directory below an owner-controlled parent.");
+  }
+  return target;
+}
+
+async function rejectSymlinkAncestors(target) {
+  const root = path.parse(target).root;
+  const relative = path.relative(root, path.dirname(target));
+  let cursor = root;
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    cursor = path.join(cursor, part);
+    const info = await maybeLstat(cursor);
+    if (!info) fail("invalid_target_parent", "A target ancestor does not exist.", "Create one owner-controlled parent directory first.");
+    if (info.isSymbolicLink()) conflict("A target ancestor is a symbolic link.", { path: cursor });
+    if (!info.isDirectory()) conflict("A target ancestor is not a directory.", { path: cursor });
+  }
+}
+
+async function safeParent(target) {
+  await rejectSymlinkAncestors(target);
+  const parent = path.dirname(target);
+  const info = await lstat(parent);
+  if (!info.isDirectory() || info.isSymbolicLink()) conflict("The target parent is not a real directory.");
+  currentIdentity(info, "The target parent");
+  return { path: parent, identity: identity(info) };
+}
+
+function receiptKeys(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value).sort() : [];
+}
+
+function validateReceipt(value, origin) {
+  const expected = ["schemaVersion", "installer", "installerVersion", "origin", "artifactRevisionId", "manifestDigest", "installedAt", "files"].sort();
+  const actual = receiptKeys(value);
+  if (actual.length !== expected.length || actual.some((entry, index) => entry !== expected[index])) conflict("The local install receipt is invalid.");
+  if (value.schemaVersion !== RECEIPT_SCHEMA_VERSION || value.installer !== "@getformation/cloud-cli" || value.installerVersion !== PACKAGE_VERSION) conflict("The local install receipt is not owned by this installer version.");
+  if (value.origin !== origin) conflict("The installed Skill belongs to a different Cloud origin.");
+  if (!isArtifactRevisionId(value.artifactRevisionId) || typeof value.manifestDigest !== "string" || !SHA256.test(value.manifestDigest)) conflict("The local install receipt identifiers are invalid.");
+  if (typeof value.installedAt !== "string" || !Number.isFinite(Date.parse(value.installedAt))) conflict("The local install receipt timestamp is invalid.");
+  if (!Array.isArray(value.files) || value.files.length < 1 || value.files.length > SKILL_LIMITS.fileCount) conflict("The local install receipt file list is invalid.");
+  const paths = [];
+  let totalBytes = 0;
+  for (const entry of value.files) {
+    const keys = receiptKeys(entry);
+    if (keys.join("\0") !== ["byteLength", "path", "sha256"].sort().join("\0") || !isCanonicalSkillPath(entry.path)
+      || !Number.isSafeInteger(entry.byteLength) || entry.byteLength < 1 || entry.byteLength > SKILL_LIMITS.fileBytes
+      || !SHA256.test(entry.sha256)) conflict("The local install receipt has an invalid file entry.");
+    paths.push(entry.path);
+    totalBytes += entry.byteLength;
+  }
+  if (!paths.includes("SKILL.md") || totalBytes > SKILL_LIMITS.totalBytes || new Set(paths).size !== paths.length
+    || paths.some((entry, index) => index > 0 && paths[index - 1] >= entry)) conflict("The local install receipt paths or aggregate bounds are invalid.");
+  return value;
+}
+
+async function readBoundedFile(filePath, maximumBytes) {
+  const before = await lstat(filePath);
+  if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > maximumBytes) conflict("A receipt-owned path is not one bounded regular file.", { path: filePath });
+  currentIdentity(before, "A receipt-owned file");
+  const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.nlink !== 1 || !sameIdentity(identity(before), identity(opened))) conflict("A receipt-owned file changed while it was opened.", { path: filePath });
+    currentIdentity(opened, "A receipt-owned file");
+    const chunks = [];
+    let total = 0;
+    while (true) {
+      const bytes = Buffer.allocUnsafe(Math.min(65_536, maximumBytes + 1 - total));
+      const { bytesRead } = await handle.read(bytes, 0, bytes.length, null);
+      if (bytesRead === 0) break;
+      total += bytesRead;
+      if (total > maximumBytes) conflict("A receipt-owned file exceeded its read bound.", { path: filePath });
+      chunks.push(bytes.subarray(0, bytesRead));
+    }
+    const after = await handle.stat();
+    if (!sameIdentity(identity(opened), identity(after)) || after.nlink !== 1) conflict("A receipt-owned file changed while it was read.", { path: filePath });
+    return Buffer.concat(chunks, total);
+  } finally { await handle.close(); }
+}
+
+async function inspectExistingTarget(target, origin) {
+  const targetInfo = await maybeLstat(target);
+  if (!targetInfo) return { exists: false, identity: null };
+  if (targetInfo.isSymbolicLink() || !targetInfo.isDirectory()) conflict("The Skill target is not a real directory.");
+  currentIdentity(targetInfo, "The Skill target");
+  const queue = [{ absolute: target, relative: "", depth: 0 }];
+  const foundFiles = [];
+  const foundDirectories = [];
+  let entries = 0;
+  while (queue.length) {
+    const current = queue.shift();
+    const children = await readdir(current.absolute, { withFileTypes: false });
+    for (const name of children) {
+      entries += 1;
+      if (entries > MAX_LOCAL_ENTRIES) conflict("The Skill target contains too many paths.");
+      const absolute = path.join(current.absolute, name);
+      const relative = current.relative ? `${current.relative}/${name}` : name;
+      const info = await lstat(absolute);
+      if (info.isSymbolicLink()) conflict("The Skill target contains a symbolic link.", { path: relative });
+      currentIdentity(info, `Skill target path ${relative}`);
+      if (info.isDirectory()) {
+        if (current.depth >= 1) conflict("The Skill target contains a directory below the allowed one-level tree.", { path: relative });
+        foundDirectories.push(relative);
+        queue.push({ absolute, relative, depth: current.depth + 1 });
+      } else if (info.isFile()) {
+        if (info.nlink !== 1) conflict("The Skill target contains a hard-linked file.", { path: relative });
+        foundFiles.push(relative);
+      } else {
+        conflict("The Skill target contains a device or other non-file path.", { path: relative });
+      }
+    }
+  }
+  if (!foundFiles.includes(RECEIPT_NAME)) conflict("The existing target is not owned by a Formation Cloud install receipt.");
+  const receiptBytes = await readBoundedFile(path.join(target, RECEIPT_NAME), MAX_RECEIPT_BYTES);
+  let receipt;
+  try { receipt = validateReceipt(JSON.parse(receiptBytes.toString("utf8")), origin); }
+  catch (error) {
+    if (error?.code) throw error;
+    conflict("The local install receipt is not valid JSON.");
+  }
+  const expectedFiles = [RECEIPT_NAME, ...receipt.files.map(({ path: filePath }) => filePath)].sort();
+  const actualFiles = foundFiles.sort();
+  if (actualFiles.length !== expectedFiles.length || actualFiles.some((entry, index) => entry !== expectedFiles[index])) conflict("The Skill target contains missing, modified, or extra files.", { expectedFiles, actualFiles });
+  const expectedDirectories = receipt.files.some(({ path: filePath }) => filePath.startsWith("references/")) ? ["references"] : [];
+  foundDirectories.sort();
+  if (foundDirectories.length !== expectedDirectories.length || foundDirectories.some((entry, index) => entry !== expectedDirectories[index])) conflict("The Skill target contains an undeclared directory.");
+  for (const descriptor of receipt.files) {
+    const bytes = await readBoundedFile(path.join(target, ...descriptor.path.split("/")), descriptor.byteLength);
+    if (bytes.byteLength !== descriptor.byteLength || sha256Bytes(bytes) !== descriptor.sha256) conflict("A receipt-owned Skill file has changed.", { path: descriptor.path });
+  }
+  return { exists: true, identity: identity(targetInfo), receipt };
+}
+
+async function assertIdentity(filePath, expected, subject) {
+  const info = await maybeLstat(filePath);
+  if (info) currentIdentity(info, subject);
+  if (!info || !sameIdentity(identity(info), expected)) conflict(`${subject} changed during installation.`);
+}
+
+async function fsyncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+async function writeExclusive(filePath, bytes, mode = 0o600) {
+  const handle = await open(filePath, "wx", mode);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+}
+
+function newReceipt(bundle, origin) {
+  return {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    installer: "@getformation/cloud-cli",
+    installerVersion: PACKAGE_VERSION,
+    origin,
+    artifactRevisionId: bundle.manifest.artifactRevisionId,
+    manifestDigest: bundle.manifest.manifestDigest,
+    installedAt: new Date().toISOString(),
+    files: bundle.files.map(({ path: filePath, sha256, byteLength }) => ({ path: filePath, sha256, byteLength })),
+  };
+}
+
+function receiptFilesForManifest(manifest) {
+  return manifest.files.map(({ path: filePath, sha256, byteLength }) => ({ path: filePath, sha256, byteLength }));
+}
+
+function receiptMatchesManifest(receipt, manifest) {
+  return receipt.manifestDigest === manifest.manifestDigest
+    && receipt.artifactRevisionId === manifest.artifactRevisionId
+    && isDeepStrictEqual(receipt.files, receiptFilesForManifest(manifest));
+}
+
+async function createStage(target, bundle, receipt, token, afterCreate) {
+  const parent = path.dirname(target);
+  const stage = path.join(parent, `.${path.basename(target)}.formation-cloud-stage-${token}`);
+  await mkdir(stage, { mode: 0o700 });
+  const stageIdentity = identity(await lstat(stage));
+  await afterCreate?.({ stage });
+  if (bundle.files.some(({ path: filePath }) => filePath.startsWith("references/"))) {
+    await mkdir(path.join(stage, "references"), { mode: 0o700 });
+  }
+  for (const file of bundle.files) await writeExclusive(path.join(stage, ...file.path.split("/")), file.bytes);
+  await writeExclusive(path.join(stage, RECEIPT_NAME), Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`, "utf8"));
+  if (bundle.files.some(({ path: filePath }) => filePath.startsWith("references/"))) await fsyncDirectory(path.join(stage, "references"));
+  await fsyncDirectory(stage);
+  await fsyncDirectory(parent);
+  return { path: stage, identity: stageIdentity };
+}
+
+async function acquireLock(target, parentIdentity, targetState, afterCreate) {
+  const lockPath = `${target}.formation-cloud.lock`;
+  const token = randomBytes(18).toString("hex");
+  await assertIdentity(path.dirname(target), parentIdentity, "The target parent");
+  const handle = await open(lockPath, "wx", 0o600).catch((error) => {
+    if (error?.code === "EEXIST") conflict("Another Skill install lock already exists.", { lockPath });
+    throw error;
+  });
+  const lockIdentity = identity(await handle.stat());
+  let setupError = null;
+  try {
+    await afterCreate?.({ lockPath });
+    await handle.writeFile(`${JSON.stringify({ schemaVersion: 1, token, parent: parentIdentity, target: targetState.identity })}\n`);
+    await handle.sync();
+    await fsyncDirectory(path.dirname(target));
+  } catch (error) { setupError = error; }
+  finally { await handle.close(); }
+  if (setupError) {
+    const info = await maybeLstat(lockPath).catch(() => null);
+    if (info && sameIdentity(identity(info), lockIdentity)) {
+      await unlink(lockPath).catch(() => {});
+      await fsyncDirectory(path.dirname(target)).catch(() => {});
+    }
+    throw setupError;
+  }
+  return {
+    token,
+    path: lockPath,
+    async release() {
+      const info = await maybeLstat(lockPath);
+      if (!info || !sameIdentity(identity(info), lockIdentity)) return;
+      const bytes = await readFile(lockPath).catch(() => null);
+      if (!bytes || !bytes.toString("utf8").includes(`"token":"${token}"`)) return;
+      await unlink(lockPath);
+      await fsyncDirectory(path.dirname(target));
+    },
+  };
+}
+
+async function isExactReceiptOwnedTree(treePath, expectedIdentity, expectedReceipt, origin) {
+  if (!treePath || !expectedIdentity || !expectedReceipt) return false;
+  try {
+    const state = await inspectExistingTarget(treePath, origin);
+    return state.exists && sameIdentity(state.identity, expectedIdentity) && isDeepStrictEqual(state.receipt, expectedReceipt);
+  } catch {
+    return false;
+  }
+}
+
+async function removeExactReceiptOwnedTree(treePath, expectedIdentity, expectedReceipt, origin) {
+  if (!await isExactReceiptOwnedTree(treePath, expectedIdentity, expectedReceipt, origin)) return false;
+  const quarantine = `${treePath}.formation-cloud-remove-${randomBytes(12).toString("hex")}`;
+  if (await maybeLstat(quarantine)) return false;
+  await rename(treePath, quarantine);
+  if (!await isExactReceiptOwnedTree(quarantine, expectedIdentity, expectedReceipt, origin)) {
+    if (!await maybeLstat(treePath)) await rename(quarantine, treePath).catch(() => {});
+    return false;
+  }
+  await rm(quarantine, { recursive: true, force: true });
+  return true;
+}
+
+export async function installSkill({
+  client,
+  artifactRevisionId,
+  target,
+  apply = false,
+  replace = false,
+  expectedInstalledManifest = null,
+  hooks = {},
+}) {
+  assertExactTarget(target);
+  if (replace && (!apply || !expectedInstalledManifest || !SHA256.test(expectedInstalledManifest))) {
+    fail("invalid_replacement", "Replacement requires --apply, --replace, and one exact expected installed manifest digest.",
+      "Read the local receipt, then pass --apply --replace --expected-installed-manifest <sha256>.");
+  }
+  if (!replace && expectedInstalledManifest !== null) {
+    fail("invalid_replacement", "An expected installed manifest is valid only for an explicit replacement.",
+      "Remove the replacement option, or provide the complete replacement command.");
+  }
+  const parent = await safeParent(target);
+  const before = await inspectExistingTarget(target, client.origin.origin);
+  if (before.exists) {
+    const installedManifest = manifestFromOperation(await client.manifest(before.receipt.artifactRevisionId), {
+      expectedOrigin: client.origin.origin,
+      expectedRevisionId: before.receipt.artifactRevisionId,
+    });
+    if (!receiptMatchesManifest(before.receipt, installedManifest)) {
+      conflict("The local receipt does not match the immutable installed manifest.");
+    }
+  }
+  const bundle = await downloadSkillBundle(client, artifactRevisionId);
+  if (before.exists) {
+    if (before.receipt.artifactRevisionId === bundle.manifest.artifactRevisionId
+      && receiptMatchesManifest(before.receipt, bundle.manifest)) {
+      return { status: "current", action: "unchanged", applied: false, target, artifactRevisionId, manifestDigest: bundle.manifest.manifestDigest };
+    }
+    if (!replace) conflict("The target already contains a different receipt-owned Skill revision.", { installedManifestDigest: before.receipt.manifestDigest });
+    if (before.receipt.manifestDigest !== expectedInstalledManifest) conflict("The expected installed manifest digest does not match the local receipt.");
+  } else if (replace) {
+    conflict("Replacement requires an existing receipt-owned Skill target.");
+  }
+  if (!apply) {
+    return { status: "ready", action: "would_install", applied: false, target, artifactRevisionId, manifestDigest: bundle.manifest.manifestDigest };
+  }
+  const lock = await acquireLock(target, parent.identity, before, hooks.afterLockCreate);
+  let stage = null;
+  let stageIdentity = null;
+  let stageSafeToRemove = true;
+  let backup = null;
+  let backupIdentity = null;
+  let displaced = null;
+  let displacedIdentity = null;
+  let installedIdentity = null;
+  let installReceipt = null;
+  try {
+    await hooks.afterLock?.({ target, lockPath: lock.path });
+    await assertIdentity(parent.path, parent.identity, "The target parent");
+    const lockedState = await inspectExistingTarget(target, client.origin.origin);
+    if (lockedState.exists !== before.exists || (before.exists && !sameIdentity(lockedState.identity, before.identity))) conflict("The Skill target changed before the locked install.");
+    installReceipt = newReceipt(bundle, client.origin.origin);
+    const staged = await createStage(target, bundle, installReceipt, lock.token, hooks.afterStageDirectoryCreate);
+    stage = staged.path;
+    stageIdentity = staged.identity;
+    const assertStageComplete = async () => {
+      let stagedState;
+      try { stagedState = await inspectExistingTarget(stage, client.origin.origin); }
+      catch (error) { stageSafeToRemove = false; throw error; }
+      if (!stagedState.exists || !sameIdentity(stagedState.identity, stageIdentity)
+        || !isDeepStrictEqual(stagedState.receipt, installReceipt)) {
+        stageSafeToRemove = false;
+        conflict("The staged Skill changed before installation.", { stage });
+      }
+    };
+    await hooks.afterStage?.({ target, stage });
+    await assertStageComplete();
+    await revalidateCurrentManifest(client, bundle.manifest);
+    await assertIdentity(parent.path, parent.identity, "The target parent");
+    await assertStageComplete();
+    const finalState = await inspectExistingTarget(target, client.origin.origin);
+    if (finalState.exists !== before.exists || (before.exists && !sameIdentity(finalState.identity, before.identity))) conflict("The Skill target changed before the atomic swap.");
+    if (!before.exists) {
+      await hooks.beforeFirstRename?.({ target, stage });
+      await assertIdentity(parent.path, parent.identity, "The target parent");
+      await assertStageComplete();
+      if (await maybeLstat(target)) conflict("The Skill target appeared before the atomic install.");
+      installedIdentity = stageIdentity;
+      await rename(stage, target);
+      stage = null;
+      stageIdentity = null;
+      await fsyncDirectory(parent.path);
+      if (!await isExactReceiptOwnedTree(target, installedIdentity, installReceipt, client.origin.origin)) {
+        conflict("The installed target changed before the first install committed.", { target });
+      }
+    } else {
+      backup = path.join(parent.path, `.${path.basename(target)}.formation-cloud-backup-${lock.token}`);
+      displaced = path.join(parent.path, `.${path.basename(target)}.formation-cloud-failed-${lock.token}`);
+      await rename(target, backup);
+      backupIdentity = before.identity;
+      await fsyncDirectory(parent.path);
+      try {
+        await hooks.afterBackup?.({ target, stage, backup });
+        await assertIdentity(parent.path, parent.identity, "The target parent");
+        await assertIdentity(backup, backupIdentity, "The receipt-owned replacement backup");
+        await assertStageComplete();
+        if (await maybeLstat(target)) conflict("A competing target appeared during replacement.", { backup });
+        await rename(stage, target);
+        stage = null;
+        stageIdentity = null;
+        installedIdentity = staged.identity;
+        await fsyncDirectory(parent.path);
+        await hooks.afterSwap?.({ target, backup });
+        if (!await isExactReceiptOwnedTree(target, installedIdentity, installReceipt, client.origin.origin)) {
+          conflict("The installed target changed before replacement commit.", { target });
+        }
+      } catch (error) {
+        if (!await isExactReceiptOwnedTree(backup, backupIdentity, before.receipt, client.origin.origin)) {
+          conflict("The receipt-owned replacement backup changed, so rollback was refused.", { backup });
+        }
+        const current = await maybeLstat(target);
+        if (!current) {
+          await rename(backup, target);
+          backup = null;
+          backupIdentity = null;
+          await fsyncDirectory(parent.path);
+        } else if (installedIdentity && sameIdentity(identity(current), installedIdentity)) {
+          await rename(target, displaced);
+          displacedIdentity = installedIdentity;
+          await rename(backup, target);
+          backup = null;
+          backupIdentity = null;
+          await fsyncDirectory(parent.path);
+          if (!await removeExactReceiptOwnedTree(displaced, displacedIdentity, installReceipt, client.origin.origin)) {
+            conflict("The failed replacement tree changed before cleanup.", { displaced });
+          }
+          displaced = null;
+          displacedIdentity = null;
+        } else {
+          conflict("A competing target blocked replacement rollback. The prior receipt-owned install remains in its sibling backup.", { backup });
+        }
+        throw error;
+      }
+      if (!await removeExactReceiptOwnedTree(backup, backupIdentity, before.receipt, client.origin.origin)) {
+        conflict("The receipt-owned replacement backup changed before cleanup.", { backup });
+      }
+      backup = null;
+      backupIdentity = null;
+      await fsyncDirectory(parent.path);
+    }
+    return { status: "current", action: before.exists ? "replaced" : "installed", applied: true, target,
+      artifactRevisionId, manifestDigest: bundle.manifest.manifestDigest };
+  } finally {
+    if (stageSafeToRemove) await removeExactReceiptOwnedTree(stage, stageIdentity, installReceipt, client.origin.origin).catch(() => {});
+    if (backup) {
+      const current = await maybeLstat(target).catch(() => null);
+      if (!current && await isExactReceiptOwnedTree(backup, backupIdentity, before.receipt, client.origin.origin)) await rename(backup, target).catch(() => {});
+    }
+    await removeExactReceiptOwnedTree(displaced, displacedIdentity, installReceipt, client.origin.origin).catch(() => {});
+    await lock.release().catch(() => {});
+  }
+}
+
+export async function checkSkill({ client, target }) {
+  assertExactTarget(target);
+  try {
+    await safeParent(target);
+    const installed = await inspectExistingTarget(target, client.origin.origin);
+    if (!installed.exists) {
+      return { status: "conflict", target, reason: "not_installed", deleted: false };
+    }
+    const remote = manifestFromOperation(await client.manifest(installed.receipt.artifactRevisionId), {
+      expectedOrigin: client.origin.origin,
+      expectedRevisionId: installed.receipt.artifactRevisionId,
+    });
+    if (!receiptMatchesManifest(installed.receipt, remote)) {
+      return { status: "conflict", target, artifactRevisionId: installed.receipt.artifactRevisionId,
+        reason: "immutable_manifest_changed", deleted: false };
+    }
+    return {
+      status: remote.status === "superseded" ? "stale" : remote.status,
+      target,
+      artifactRevisionId: remote.artifactRevisionId,
+      manifestDigest: remote.manifestDigest,
+      ...(remote.status === "superseded" ? { currentArtifactRevisionId: remote.supersededByArtifactRevisionId } : {}),
+      ...(remote.status === "withdrawn" ? { withdrawalReason: remote.withdrawalReason } : {}),
+      deleted: false,
+    };
+  } catch (error) {
+    if (["install_conflict", "invalid_skill_manifest", "skill_artifact_not_found"].includes(error?.code)) {
+      return { status: "conflict", target, reason: error.message, deleted: false };
+    }
+    throw error;
+  }
+}
+
+export const installerInternals = Object.freeze({ assertExactTarget, assertOwnedSafeMetadata, inspectExistingTarget, receiptMatchesManifest, validateReceipt });