agent-skillboard 0.1.2 → 0.2.1

package/src/control/variant-files.mjs

@@ -0,0 +1,265 @@
+import { constants as fsConstants } from "node:fs";
+import { copyFile, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { normalizeSkillPath } from "../skill-paths.mjs";
+import { skillContentDigest } from "../source-verification.mjs";
+
+const SNAPSHOT_ROOT = ".skillboard/variant-snapshots";
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+export function resolveVariantLiveSkillFile({ skillsRoot, skill }) {
+  if (skill === null || typeof skill !== "object") {
+    throw new Error("skill must be an object with id and path");
+  }
+  const root = resolveRequiredPath(skillsRoot, "skills root");
+  const skillPath = normalizeSkillPath(skill.path, `skills.${skill.id ?? "<unknown>"}.path`);
+  const liveFile = resolve(root, skillPath, "SKILL.md");
+  assertPathInside(root, liveFile, "live skill file");
+  return liveFile;
+}
+
+export function variantSnapshotTarget({ configPath, skillId, snapshotName }) {
+  const encodedSkillId = encodeSkillIdSegment(skillId);
+  const fileName = snapshotFileName(snapshotName);
+  const storedPath = `${SNAPSHOT_ROOT}/${encodedSkillId}/${fileName}`;
+  return resolveVariantSnapshotFile({ configPath, snapshotPath: storedPath });
+}
+
+export function resolveVariantSnapshotFile({ configPath, snapshotPath }) {
+  const configDir = dirname(resolveRequiredPath(configPath, "config path"));
+  const normalized = normalizeStoredSnapshotPath(snapshotPath);
+  const root = resolve(configDir, SNAPSHOT_ROOT);
+  const absolutePath = resolve(configDir, normalized);
+  if (!isPathInside(root, absolutePath)) {
+    throw new Error(`snapshot path must stay under ${SNAPSHOT_ROOT}`);
+  }
+  return {
+    storedPath: relative(configDir, absolutePath).replaceAll("\\", "/"),
+    absolutePath,
+    rootPath: root
+  };
+}
+
+export function variantTempPath(absolutePath) {
+  return join(dirname(resolveRequiredPath(absolutePath, "target path")), `.${basename(absolutePath)}.${randomUUID()}.tmp`);
+}
+
+export function requireVariantDigest(value, label = "content digest") {
+  if (typeof value !== "string" || !DIGEST_PATTERN.test(value)) {
+    throw new Error(`${label} must use sha256:<64 hex chars>`);
+  }
+  return value;
+}
+
+export const digestVariantFile = skillContentDigest;
+
+export async function writeVariantSnapshot(options) {
+  const target = variantSnapshotTarget(options);
+  const content = normalizeFileContent(options.content, "snapshot content");
+  if (options.expectedDigest !== undefined) {
+    requireVariantDigest(options.expectedDigest, "expected snapshot digest");
+  }
+  const plan = filePlan("write-snapshot", {
+    path: target.storedPath,
+    absolutePath: target.absolutePath,
+    bytes: Buffer.byteLength(content),
+    overwrite: options.allowOverwrite === true,
+    dryRun: options.dryRun === true
+  });
+  if (options.dryRun === true) {
+    return plan;
+  }
+  if (options.allowOverwrite !== true) {
+    await assertMissing(target.absolutePath, "Snapshot target");
+  }
+  await writeFileByRename(target.absolutePath, content, { expectedDigest: options.expectedDigest });
+  return plan;
+}
+
+export async function copySkillFileForFork(options) {
+  const sourceFile = resolveRequiredPath(options.sourceFile, "source skill file");
+  const targetFile = resolveRequiredPath(options.targetFile, "fork target skill file");
+  const sourceStats = await lstat(sourceFile);
+  if (!sourceStats.isFile()) {
+    throw new Error(`Source skill file must be a regular file: ${sourceFile}`);
+  }
+  await assertMissing(targetFile, "Fork target");
+  const plan = filePlan("copy-skill-for-fork", {
+    from: sourceFile,
+    path: targetFile,
+    absolutePath: targetFile,
+    bytes: sourceStats.size,
+    dryRun: options.dryRun === true
+  });
+  if (options.dryRun === true) {
+    return plan;
+  }
+  await writeFileByRename(targetFile, await readFile(sourceFile));
+  return plan;
+}
+
+export async function createResetBackup(liveFile) {
+  const absolutePath = resolveRequiredPath(liveFile, "live skill file");
+  await assertResetTargetFile(absolutePath);
+  const backupPath = join(dirname(absolutePath), `.${basename(absolutePath)}.${randomUUID()}.bak`);
+  await copyFile(absolutePath, backupPath, fsConstants.COPYFILE_EXCL);
+  return {
+    liveFile: absolutePath,
+    backupPath,
+    restore: () => copyFile(backupPath, absolutePath),
+    cleanup: () => rm(backupPath, { force: true })
+  };
+}
+
+export async function replaceLiveSkillFileForReset(options) {
+  const liveFile = resolveRequiredPath(options.liveFile, "live skill file");
+  const content = normalizeFileContent(options.content, "reset content");
+  await assertResetTargetFile(liveFile);
+  const plan = filePlan("replace-live-skill-for-reset", {
+    path: liveFile,
+    absolutePath: liveFile,
+    bytes: Buffer.byteLength(content),
+    overwrite: true,
+    dryRun: options.dryRun === true
+  });
+  if (options.dryRun === true) {
+    return plan;
+  }
+
+  const backup = await createResetBackup(liveFile);
+  try {
+    await writeFileByRename(liveFile, content);
+    return { ...plan, backupPath: backup.backupPath };
+  } catch (error) {
+    await backup.restore().catch(() => undefined);
+    throw error;
+  } finally {
+    await backup.cleanup();
+  }
+}
+
+export async function cleanupCreatedVariantFile(path, options = {}) {
+  const absolutePath = resolveRequiredPath(path, "created variant file");
+  if (options.expectedDigest !== undefined) {
+    const expectedDigest = requireVariantDigest(options.expectedDigest, "expected cleanup digest");
+    const actualDigest = await skillContentDigest(absolutePath).catch(() => null);
+    if (actualDigest !== expectedDigest) {
+      return { removed: false, reason: "digest-mismatch", actualDigest };
+    }
+  }
+  await rm(absolutePath, { force: true });
+  return { removed: true };
+}
+
+export function isPathInside(root, candidate) {
+  const relativePath = relative(resolve(root), resolve(candidate));
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+export function assertPathInside(root, candidate, label = "path") {
+  if (!isPathInside(root, candidate)) {
+    throw new Error(`${label} must stay under ${root}`);
+  }
+}
+
+function filePlan(action, values) {
+  return { action, changed: true, ...values };
+}
+
+async function writeFileByRename(targetPath, content, options = {}) {
+  await mkdir(dirname(targetPath), { recursive: true });
+  const tempPath = variantTempPath(targetPath);
+  try {
+    await writeFile(tempPath, content, { flag: "wx" });
+    if (options.expectedDigest !== undefined) {
+      const actualDigest = await skillContentDigest(tempPath);
+      if (actualDigest !== options.expectedDigest) {
+        throw new Error(`snapshot content digest mismatch: expected ${options.expectedDigest}, got ${actualDigest}`);
+      }
+    }
+    await rename(tempPath, targetPath);
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+async function assertMissing(path, label) {
+  try {
+    await lstat(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  throw new Error(`${label} already exists: ${path}`);
+}
+
+async function assertResetTargetFile(path) {
+  const stats = await lstat(path);
+  if (stats.isSymbolicLink()) {
+    throw new Error(`Refusing to overwrite symlink target for reset: ${path}`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`Reset target must be a regular file: ${path}`);
+  }
+}
+
+function normalizeStoredSnapshotPath(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error("snapshot path must be a non-empty relative path");
+  }
+  if (value.includes("\0")) {
+    throw new Error("snapshot path must not contain null bytes");
+  }
+  const normalized = value.replaceAll("\\", "/");
+  if (normalized.startsWith("/") || normalized.startsWith("//") || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error("snapshot path must be relative to the config directory");
+  }
+  if (!normalized.startsWith(`${SNAPSHOT_ROOT}/`)) {
+    throw new Error(`snapshot path must stay under ${SNAPSHOT_ROOT}`);
+  }
+  return normalized;
+}
+
+function encodeSkillIdSegment(skillId) {
+  if (typeof skillId !== "string" || skillId.length === 0) {
+    throw new Error("skill id must be a non-empty string");
+  }
+  if (skillId.includes("\0")) {
+    throw new Error("skill id must not contain null bytes");
+  }
+  const encoded = encodeURIComponent(skillId);
+  if (encoded === ".") {
+    return "%2E";
+  }
+  return encoded === ".." ? "%2E%2E" : encoded;
+}
+
+function snapshotFileName(snapshotName) {
+  if (typeof snapshotName !== "string" || snapshotName.length === 0) {
+    throw new Error("snapshot name must be a non-empty string");
+  }
+  if (!/^[A-Za-z0-9_-]+$/.test(snapshotName)) {
+    throw new Error("snapshot name may only contain letters, numbers, underscores, and dashes");
+  }
+  return `${snapshotName}.md`;
+}
+
+function resolveRequiredPath(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${label} must be a non-empty path`);
+  }
+  if (value.includes("\0")) {
+    throw new Error(`${label} must not contain null bytes`);
+  }
+  return resolve(value);
+}
+
+function normalizeFileContent(value, label) {
+  if (typeof value === "string" || Buffer.isBuffer(value)) {
+    return value;
+  }
+  throw new Error(`${label} must be a string or Buffer`);
+}

package/src/control/variant-lifecycle-config.mjs

@@ -0,0 +1,156 @@
+import {
+  addUnique,
+  ensureSeq,
+  nodeScalarValue,
+  optionalMap,
+  optionalRootMap,
+  readMapString,
+  removeValue,
+  requireMapAt,
+  requireYamlMap,
+  sequenceIncludes
+} from "./config-write.mjs";
+
+export function requireConfigSkill(document, skillId) {
+  const skills = requireMapAt(document, ["skills"], "skills");
+  const skill = skills.get(skillId, true);
+  if (skill === undefined) {
+    throw new Error(`Unknown skill: ${skillId}`);
+  }
+  return requireYamlMap(skill, `skills.${skillId}`);
+}
+
+export function requireConfigWorkflow(document, workflowName) {
+  const workflows = requireMapAt(document, ["workflows"], "workflows");
+  const workflow = workflows.get(workflowName, true);
+  if (workflow === undefined) {
+    throw new Error(`Unknown workflow: ${workflowName}`);
+  }
+  const raw = requireYamlMap(workflow, `workflows.${workflowName}`);
+  ensureSeq(raw, "active_skills", document);
+  ensureSeq(raw, "blocked_skills", document);
+  return raw;
+}
+
+export function requireConfigCapability(document, capabilityName) {
+  const capabilities = requireMapAt(document, ["capabilities"], "capabilities");
+  const capability = capabilities.get(capabilityName, true);
+  if (capability === undefined) {
+    throw new Error(`Unknown capability: ${capabilityName}`);
+  }
+  return requireYamlMap(capability, `capabilities.${capabilityName}`);
+}
+
+export function addVariantCapabilityAlternative(document, capability, options) {
+  const alternatives = ensureSeq(capability, "alternatives", document);
+  const canonical = readMapString(capability, "canonical", "");
+  if (canonical !== options.baseId && !sequenceIncludes(alternatives, options.baseId)) {
+    addUnique(alternatives, options.baseId);
+  }
+  if (canonical !== options.variantId && !sequenceIncludes(alternatives, options.variantId)) {
+    addUnique(alternatives, options.variantId);
+  }
+}
+
+export function promoteVariantInWorkflow(document, workflow, capabilityDefinition, options) {
+  const required = ensureRequiredCapability(workflow, options.capability, document);
+  const previousPreferred = readMapString(required, "preferred", "");
+  const canonical = readMapString(capabilityDefinition, "canonical", "");
+  const fallback = ensureSeq(required, "fallback", document);
+  required.set("preferred", options.variantId);
+  setFallbackValues(fallback, orderedVariantFallbacks(sequenceValues(fallback), [previousPreferred, options.baseId, canonical], options.variantId));
+  addUnique(ensureSeq(workflow, "active_skills", document), options.variantId);
+  removeValue(ensureSeq(workflow, "blocked_skills", document), options.variantId);
+  return required;
+}
+
+export function ensureRequiredCapability(workflow, capabilityName, document) {
+  let capabilities = workflow.get("required_capabilities", true);
+  if (capabilities === undefined) {
+    capabilities = document.createNode({});
+    workflow.set("required_capabilities", capabilities);
+  }
+  const capabilityMap = requireYamlMap(capabilities, "required_capabilities");
+  if (capabilityMap.get(capabilityName, true) === undefined) {
+    capabilityMap.set(capabilityName, document.createNode({ preferred: "", fallback: [], policy: "manual-only" }));
+  }
+  const capability = requireYamlMap(capabilityMap.get(capabilityName, true), `required_capabilities.${capabilityName}`);
+  ensureSeq(capability, "fallback", document);
+  return capability;
+}
+
+export function readRequiredCapabilityPolicy(workflow, capabilityName) {
+  const capabilities = optionalMap(workflow, "required_capabilities");
+  if (capabilities === undefined || capabilities.get(capabilityName, true) === undefined) {
+    return "";
+  }
+  return readMapString(requireYamlMap(capabilities.get(capabilityName, true), `required_capabilities.${capabilityName}`), "policy", "");
+}
+
+export function orderedVariantFallbacks(existingValues, priorityValues, variantId) {
+  const next = [];
+  const seen = new Set();
+  for (const value of [...priorityValues, ...existingValues]) {
+    if (typeof value === "string" && value.length > 0 && value !== variantId && !seen.has(value)) {
+      next.push(value);
+      seen.add(value);
+    }
+  }
+  return next;
+}
+
+export function setFallbackValues(sequence, values) {
+  while (sequence.items.length > 0) {
+    sequence.delete(0);
+  }
+  for (const value of values) {
+    sequence.add(value);
+  }
+}
+
+export function sequenceValues(sequence) {
+  return sequence.items.map((item) => nodeScalarValue(item));
+}
+
+export function appendSkillToOwnerInstallUnit(document, unitId, skillId) {
+  const installUnits = optionalRootMap(document, "install_units");
+  if (installUnits === undefined || installUnits.get(unitId, true) === undefined) {
+    throw new Error(`Unknown install unit: ${unitId}`);
+  }
+  const unit = requireYamlMap(installUnits.get(unitId, true), `install_units.${unitId}`);
+  let components = unit.get("components", true);
+  if (components === undefined) {
+    components = document.createNode({});
+    unit.set("components", components);
+  }
+  addUnique(ensureSeq(requireYamlMap(components, `install_units.${unitId}.components`), "skills", document), skillId);
+}
+
+export function variantConfigMetadata(variant) {
+  return stripUndefined({
+    of: variant.of,
+    adapted_for: variant.adaptedFor ?? undefined,
+    capability: variant.capability,
+    workflow: variant.workflow,
+    status: variant.status,
+    base: {
+      content_digest: variant.base.contentDigest,
+      snapshot: variant.base.snapshot
+    },
+    approved: checkpointConfigMetadata(variant.approved)
+  });
+}
+
+export function checkpointConfigMetadata(checkpoint) {
+  if (checkpoint === undefined || checkpoint === null) {
+    return undefined;
+  }
+  return {
+    content_digest: checkpoint.contentDigest,
+    snapshot: checkpoint.snapshot
+  };
+}
+
+export function stripUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}

package/src/control/variant-reset.mjs

@@ -0,0 +1,171 @@
+import { readFile } from "node:fs/promises";
+import { loadWorkspace } from "../workspace.mjs";
+import {
+  ensureSeq,
+  loadConfig,
+  readMapString,
+  removeValue,
+  writeCheckedConfig
+} from "./config-write.mjs";
+import {
+  addVariantCapabilityAlternative,
+  ensureRequiredCapability,
+  promoteVariantInWorkflow,
+  readRequiredCapabilityPolicy,
+  requireConfigCapability,
+  requireConfigSkill,
+  requireConfigWorkflow,
+  variantConfigMetadata
+} from "./variant-lifecycle-config.mjs";
+import {
+  createResetBackup,
+  digestVariantFile,
+  replaceLiveSkillFileForReset,
+  resolveVariantLiveSkillFile,
+  resolveVariantSnapshotFile
+} from "./variant-files.mjs";
+
+const APPROVED_INVOCATIONS = new Set(["manual-only", "router-only", "workflow-auto"]);
+
+export async function resetSkillVariant(options) {
+  if (options.dryRun !== true && options.yes !== true) {
+    throw new Error("reset requires --yes unless --dry-run is used");
+  }
+  const target = resetTarget(options);
+  const current = await lifecycleSkill(options);
+  const checkpoint = resetCheckpoint(current.variant, target);
+  const snapshot = resolveVariantSnapshotFile({ configPath: options.configPath, snapshotPath: checkpoint.snapshot });
+  const content = await readSnapshotContent(snapshot.absolutePath, target, checkpoint.contentDigest);
+  const liveFile = resolveVariantLiveSkillFile({ skillsRoot: options.skillsRoot, skill: current });
+  const { document, originalText } = await loadConfig(options.configPath);
+  const skill = requireConfigSkill(document, options.variantId);
+  const workflow = requireConfigWorkflow(document, current.variant.workflow);
+  const capability = requireConfigCapability(document, current.variant.capability);
+  const variant = { ...current.variant, status: target === "base" ? "draft" : "approved" };
+
+  if (target === "base") {
+    demoteToBase(document, skill, workflow, variant, options.variantId);
+  } else {
+    promoteToApproved(document, skill, workflow, capability, variant, options);
+  }
+
+  const writeOptions = target === "approved"
+    ? { ...options, validateUse: { skillId: options.variantId, workflow: variant.workflow } }
+    : options;
+  const filePlan = [await replaceLiveSkillFileForReset({ liveFile, content, dryRun: true })];
+
+  if (options.dryRun === true) {
+    const result = await writeCheckedConfig(document, originalText, writeOptions, resetMessage(options.variantId, target));
+    return { ...result, skill: options.variantId, variant, target, filePlan, warnings: [] };
+  }
+
+  await writeCheckedConfig(document, originalText, { ...writeOptions, dryRun: true }, resetMessage(options.variantId, target));
+  const backup = await createResetBackup(liveFile);
+  try {
+    filePlan[0] = await replaceLiveSkillFileForReset({ liveFile, content });
+    const result = await writeCheckedConfig(document, originalText, writeOptions, resetMessage(options.variantId, target));
+    return { ...result, skill: options.variantId, variant, target, filePlan, warnings: [] };
+  } catch (error) {
+    await backup.restore().catch(() => undefined);
+    throw error;
+  } finally {
+    await backup.cleanup();
+  }
+}
+
+function demoteToBase(document, skill, workflow, variant, variantId) {
+  skill.set("status", "candidate");
+  skill.set("invocation", "manual-only");
+  skill.set("variant", document.createNode(variantConfigMetadata(variant)));
+  const required = ensureRequiredCapability(workflow, variant.capability, document);
+  if (readMapString(required, "preferred", "") === variantId) {
+    required.set("preferred", variant.of);
+  }
+  const fallback = ensureSeq(required, "fallback", document);
+  removeValue(fallback, variantId);
+  removeValue(fallback, variant.of);
+  removeValue(ensureSeq(workflow, "active_skills", document), variantId);
+}
+
+function promoteToApproved(document, skill, workflow, capability, variant, options) {
+  const invocation = approvedInvocation(options, workflow, capability, variant.capability);
+  skill.set("status", "active");
+  skill.set("invocation", invocation);
+  skill.set("variant", document.createNode(variantConfigMetadata(variant)));
+  addVariantCapabilityAlternative(document, capability, { baseId: variant.of, variantId: options.variantId });
+  promoteVariantInWorkflow(document, workflow, capability, { baseId: variant.of, variantId: options.variantId, capability: variant.capability });
+}
+
+function resetTarget(options) {
+  const values = [
+    options.toBase === true ? "base" : null,
+    options.toApproved === true ? "approved" : null,
+    options.to === "base" || options.target === "base" ? "base" : null,
+    options.to === "approved" || options.target === "approved" ? "approved" : null
+  ].filter(Boolean);
+  if (values.length !== 1) {
+    throw new Error("reset requires exactly one of --to-base or --to-approved");
+  }
+  return values[0];
+}
+
+function resetCheckpoint(variant, target) {
+  if (target === "base") {
+    return variant.base;
+  }
+  if (variant.approved === undefined) {
+    throw new Error("reset --to-approved requires approved snapshot metadata");
+  }
+  return variant.approved;
+}
+
+async function lifecycleSkill(options) {
+  const workspace = await loadWorkspace({ configPath: options.configPath, skillsRoot: options.skillsRoot });
+  const skill = workspace.skills.find((candidate) => candidate.id === options.variantId);
+  if (skill === undefined) {
+    throw new Error(`Unknown skill: ${options.variantId}`);
+  }
+  if (skill.variant === null || skill.variant === undefined) {
+    throw new Error(`Skill ${options.variantId} is not a lifecycle variant`);
+  }
+  return skill;
+}
+
+async function readSnapshotContent(path, label, expectedDigest) {
+  let content;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`Missing ${label} snapshot: ${path}`);
+    }
+    throw error;
+  }
+  const actualDigest = await digestVariantFile(path);
+  if (actualDigest !== expectedDigest) {
+    throw new Error(`${label} snapshot digest mismatch: expected ${expectedDigest}, got ${actualDigest}`);
+  }
+  return content;
+}
+
+function approvedInvocation(options, workflow, capability, capabilityName) {
+  const computed = firstNonEmpty([
+    options.mode,
+    options.invocation,
+    readRequiredCapabilityPolicy(workflow, capabilityName),
+    readMapString(capability, "default_policy", ""),
+    "manual-only"
+  ]);
+  if (!APPROVED_INVOCATIONS.has(computed)) {
+    throw new Error("reset --to-approved requires --mode manual-only, router-only, or workflow-auto");
+  }
+  return computed;
+}
+
+function firstNonEmpty(values) {
+  return values.find((value) => typeof value === "string" && value.length > 0) ?? "manual-only";
+}
+
+function resetMessage(variantId, target) {
+  return `Reset variant ${variantId} to ${target}`;
+}

package/src/control/variant-status.mjs

@@ -0,0 +1,75 @@
+import { loadWorkspace } from "../workspace.mjs";
+import {
+  digestVariantFile,
+  resolveVariantLiveSkillFile,
+  resolveVariantSnapshotFile
+} from "./variant-files.mjs";
+
+export async function variantLifecycleStatus(options) {
+  const workspace = await loadWorkspace({ configPath: options.configPath, skillsRoot: options.skillsRoot });
+  const skill = workspace.skills.find((candidate) => candidate.id === options.variantId);
+  if (skill === undefined) {
+    throw new Error(`Unknown skill: ${options.variantId}`);
+  }
+  if (skill.variant === null || skill.variant === undefined) {
+    throw new Error(`Skill ${options.variantId} is not a lifecycle variant`);
+  }
+
+  const warnings = [];
+  const liveFile = resolveVariantLiveSkillFile({ skillsRoot: options.skillsRoot, skill });
+  const live = await inspectDigestFile(liveFile);
+  const baseSnapshot = await inspectSnapshot(options.configPath, "base", skill.variant.base, warnings);
+  const approvedSnapshot = skill.variant.approved === undefined
+    ? null
+    : await inspectSnapshot(options.configPath, "approved", skill.variant.approved, warnings);
+  const approvedDigest = skill.variant.approved?.contentDigest ?? null;
+  return {
+    skill: skill.id,
+    variant: skill.variant,
+    computedStatus: computeStatus(skill.variant.status, live.digest, skill.variant.base.contentDigest, approvedDigest),
+    liveDigest: live.digest,
+    baseDigest: skill.variant.base.contentDigest,
+    approvedDigest,
+    files: {
+      live: { path: liveFile, exists: live.exists, digest: live.digest },
+      baseSnapshot,
+      approvedSnapshot
+    },
+    warnings
+  };
+}
+
+function computeStatus(lifecycleStatus, liveDigest, baseDigest, approvedDigest) {
+  if (liveDigest === null) {
+    return "missing-live-file";
+  }
+  if (approvedDigest !== null && liveDigest === approvedDigest) {
+    return "approved";
+  }
+  if (lifecycleStatus === "approved" && approvedDigest !== null) {
+    return "drifted";
+  }
+  return liveDigest === baseDigest ? "draft-base" : "draft-changed";
+}
+
+async function inspectSnapshot(configPath, label, checkpoint, warnings) {
+  const resolved = resolveVariantSnapshotFile({ configPath, snapshotPath: checkpoint.snapshot });
+  const digest = await inspectDigestFile(resolved.absolutePath);
+  if (!digest.exists) {
+    warnings.push(`${label} snapshot missing: ${checkpoint.snapshot}`);
+  } else if (digest.digest !== checkpoint.contentDigest) {
+    warnings.push(`${label} snapshot digest mismatch: expected ${checkpoint.contentDigest}, got ${digest.digest}`);
+  }
+  return { path: resolved.storedPath, absolutePath: resolved.absolutePath, exists: digest.exists, digest: digest.digest };
+}
+
+async function inspectDigestFile(path) {
+  try {
+    return { exists: true, digest: await digestVariantFile(path) };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return { exists: false, digest: null };
+    }
+    throw error;
+  }
+}