@openagentpack/sdk 0.6.0 → 0.7.1

package/dist/chunk-56BB46YT.js

@@ -0,0 +1,1191 @@
+import {
+  UserError,
+  inspectProjectSource
+} from "./chunk-ZBJDMUJT.js";
+
+// src/internal/project-versions/directory.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+var DIRECTORY_STORE_SCHEMA = 1;
+var VERSION_ID = /^[a-f0-9]{64}$/;
+var SENSITIVE_KEY = /(access[_-]?key|api[_-]?key|authorization|credential|headers?|password|secret|signature|token)/i;
+var ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*(?::-[^}]*)?\}$/;
+var DirectoryProjectMutationConflictError = class extends UserError {
+  status = 409;
+  constructor(message) {
+    super(message);
+    this.name = "DirectoryProjectMutationConflictError";
+  }
+};
+function createDirectoryProjectVersionService(input) {
+  const context = directoryContext(input.projectRoot);
+  return {
+    status: async () => status(context, input.adapter),
+    enable: async (message = "Initialize project") => {
+      const lease = await acquireLease(context, "version_enable");
+      try {
+        const snapshot = await input.adapter.readSnapshot();
+        await assertSnapshotSafe(snapshot, context.projectRoot);
+        const store = await readStore(context, false) ?? emptyStore();
+        store.enabled = true;
+        const head = store.head_version ? await readEntry(context, store.head_version) : null;
+        const treeHash = snapshotTreeHash(snapshot);
+        const version = head?.tree_hash === treeHash ? null : await appendVersion(context, store, snapshot, message);
+        if (!version) await writeJsonAtomic(context.storePath, store);
+        return { version, versioning: await publicStatus(context, store, snapshot) };
+      } finally {
+        await releaseLease(context, lease.token);
+      }
+    },
+    disable: async () => {
+      const lease = await acquireLease(context, "version_disable");
+      try {
+        const store = await requireStore(context);
+        store.enabled = false;
+        await writeJsonAtomic(context.storePath, store);
+        return publicStatus(context, store, await input.adapter.readSnapshot());
+      } finally {
+        await releaseLease(context, lease.token);
+      }
+    },
+    listVersions: async (options = {}) => listVersions(context, options),
+    previewVersion: async (versionId) => previewVersion(context, input.adapter, versionId),
+    restoreVersion: async (versionId, base) => restoreVersion(context, input.adapter, versionId, base),
+    prepareVersion: async (provided) => prepareVersion(context, input.adapter, provided),
+    commitPrepared: async (prepared, message = "Publish project") => commitPrepared(context, prepared, message),
+    releasePrepared: async (prepared) => {
+      if (prepared) await releaseLease(context, prepared.leaseToken);
+    }
+  };
+}
+async function status(context, adapter) {
+  const [store, snapshot, blocker] = await Promise.all([
+    readStore(context, false),
+    adapter.readSnapshot(),
+    mutationBlocker(context)
+  ]);
+  if (!store) {
+    return {
+      initialized: false,
+      enabled: false,
+      store_root: context.storeRoot,
+      head_version: null,
+      source_status: "unversioned",
+      project_revision: snapshot.project_revision,
+      write_blockers: blocker ? [blocker] : [],
+      restore_blockers: blocker ? [blocker] : []
+    };
+  }
+  return publicStatus(context, store, snapshot, blocker ? [blocker] : []);
+}
+async function publicStatus(context, store, snapshot, blockers = []) {
+  const head = store.head_version ? await readEntry(context, store.head_version) : null;
+  return {
+    initialized: true,
+    enabled: store.enabled,
+    store_root: context.storeRoot,
+    head_version: store.head_version,
+    source_status: !head ? "unversioned" : head.tree_hash === snapshotTreeHash(snapshot) ? "clean" : "modified",
+    project_revision: snapshot.project_revision,
+    write_blockers: blockers,
+    restore_blockers: blockers
+  };
+}
+async function listVersions(context, input) {
+  const store = await requireStore(context);
+  const cursor = input.cursor ? decodeCursor(input.cursor) : { head: store.head_version, offset: 0 };
+  if (cursor.head !== store.head_version) throw new UserError("Version history changed. Restart pagination.");
+  const limit = Math.max(1, Math.min(input.limit ?? 50, 100));
+  const chain = await readChain(context, store.head_version);
+  return {
+    versions: chain.slice(cursor.offset, cursor.offset + limit).map(publicVersion),
+    next_cursor: cursor.offset + limit < chain.length ? Buffer.from(JSON.stringify({ head: store.head_version, offset: cursor.offset + limit })).toString("base64url") : null
+  };
+}
+async function previewVersion(context, adapter, versionId) {
+  const store = await requireStore(context);
+  if (!store.head_version) throw new UserError("The project version store has no versions.");
+  const selected = await requireReachable(context, store.head_version, versionId);
+  const [current, historical, blocker] = await Promise.all([
+    adapter.readSnapshot(),
+    readSnapshot(context, selected),
+    mutationBlocker(context)
+  ]);
+  return buildPreview(context, selected, store.head_version, current, historical, blocker ? [blocker] : []);
+}
+async function restoreVersion(context, adapter, versionId, base) {
+  const lease = await acquireLease(context, "version_restore");
+  try {
+    const store = await requireStore(context);
+    if (store.head_version !== base.headVersion) throw new UserError("Version history changed. Preview again.");
+    const selected = await requireReachable(context, base.headVersion, versionId);
+    const [current, historical] = await Promise.all([adapter.readSnapshot(), readSnapshot(context, selected)]);
+    if (current.project_revision !== base.projectRevision) {
+      throw new UserError("Project files changed. Preview the version again before restoring.");
+    }
+    await assertSnapshotSafe(historical, context.projectRoot);
+    await adapter.restoreSnapshot(historical, base.projectRevision);
+    return buildPreview(context, selected, base.headVersion, current, historical, []);
+  } finally {
+    await releaseLease(context, lease.token);
+  }
+}
+async function prepareVersion(context, adapter, provided) {
+  const lease = await acquireLease(context, "publish");
+  try {
+    const store = await readStore(context, false);
+    const snapshot = provided ?? await adapter.readSnapshot();
+    await assertSnapshotSafe(snapshot, context.projectRoot);
+    if (!store?.enabled) {
+      return {
+        projectRoot: context.projectRoot,
+        storeRoot: context.storeRoot,
+        baseHeadVersion: store?.head_version ?? null,
+        snapshot,
+        treeHash: snapshotTreeHash(snapshot),
+        needsVersion: false,
+        versioningEnabled: false,
+        leaseToken: lease.token
+      };
+    }
+    if (!store.head_version) throw new UserError("Enabled project versioning has no baseline version.");
+    const head = await readEntry(context, store.head_version);
+    const treeHash = snapshotTreeHash(snapshot);
+    return {
+      projectRoot: context.projectRoot,
+      storeRoot: context.storeRoot,
+      baseHeadVersion: store.head_version,
+      snapshot,
+      treeHash,
+      needsVersion: head.tree_hash !== treeHash,
+      versioningEnabled: true,
+      leaseToken: lease.token
+    };
+  } catch (error) {
+    await releaseLease(context, lease.token);
+    throw error;
+  }
+}
+async function commitPrepared(context, prepared, message) {
+  try {
+    await assertLease(context, prepared.leaseToken);
+    if (prepared.projectRoot !== context.projectRoot || prepared.storeRoot !== context.storeRoot) {
+      throw new UserError("Prepared version belongs to a different project.");
+    }
+    if (!prepared.versioningEnabled) return null;
+    const store = await requireStore(context);
+    if (!store.enabled || store.head_version !== prepared.baseHeadVersion) {
+      throw new UserError("Project version history changed while Publish was running.");
+    }
+    if (!prepared.needsVersion) return null;
+    return appendVersion(context, store, prepared.snapshot, message);
+  } finally {
+    await releaseLease(context, prepared.leaseToken);
+  }
+}
+async function appendVersion(context, store, snapshot, message) {
+  if (!message.trim() || /[\r\n]/.test(message)) throw new UserError("Version message must be one non-empty line.");
+  const files = [...snapshot.files].sort((left, right) => left.path.localeCompare(right.path));
+  const manifest = {
+    project_revision: snapshot.project_revision,
+    canonical_yaml_hash: hash(snapshot.canonical_yaml),
+    files: []
+  };
+  for (const file of files) {
+    assertRelativePath(file.path);
+    const blobHash = hash(file.content);
+    await writeBlob(context, blobHash, file.content);
+    manifest.files.push({ path: file.path, mode: file.mode, blob_hash: blobHash, size: file.content.byteLength });
+  }
+  const yamlHash = hash(snapshot.canonical_yaml);
+  await writeBlob(context, yamlHash, new TextEncoder().encode(snapshot.canonical_yaml));
+  const manifestSource = JSON.stringify(manifest);
+  const manifestHash = hash(manifestSource);
+  await writeJsonAtomic(resolve(context.manifestsRoot, `${manifestHash}.json`), manifest);
+  const entryBase = {
+    parent_version: store.head_version,
+    tree_hash: snapshotTreeHash(snapshot),
+    yaml_hash: yamlHash,
+    manifest_hash: manifestHash,
+    message: message.trim(),
+    created_by: process.env.USER || process.env.USERNAME || "local-user",
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    nonce: randomUUID()
+  };
+  const versionId = hash(JSON.stringify(entryBase));
+  const entry = {
+    version_id: versionId,
+    short_version: versionId.slice(0, 12),
+    ...entryBase
+  };
+  await writeJsonAtomic(resolve(context.entriesRoot, `${versionId}.json`), entry);
+  store.head_version = versionId;
+  await writeJsonAtomic(context.storePath, store);
+  return publicVersion(entry);
+}
+async function readSnapshot(context, entry) {
+  const manifest = await readJson(resolve(context.manifestsRoot, `${entry.manifest_hash}.json`));
+  const files = await Promise.all(
+    manifest.files.map(async (file) => ({
+      path: file.path,
+      mode: file.mode,
+      content: new Uint8Array(await readFile(resolve(context.blobsRoot, file.blob_hash)))
+    }))
+  );
+  return {
+    project_revision: manifest.project_revision,
+    canonical_yaml: (await readFile(resolve(context.blobsRoot, entry.yaml_hash))).toString("utf8"),
+    files
+  };
+}
+async function buildPreview(context, entry, headVersion, current, historical, blockers) {
+  const [currentInspection, historicalInspection] = await Promise.all([
+    inspectProjectSource(current.canonical_yaml, resolve(context.projectRoot, ".openagentpack/build/agents.yaml")),
+    inspectProjectSource(historical.canonical_yaml, resolve(context.projectRoot, ".openagentpack/build/agents.yaml"))
+  ]);
+  const changes = diffSnapshots(current, historical);
+  const canRestore = blockers.length === 0 && historicalInspection.diagnostics.every((diagnostic) => diagnostic.severity !== "error");
+  return {
+    version_id: entry.version_id,
+    base_head_version: headVersion,
+    base_project_revision: current.project_revision,
+    before_yaml: currentInspection.redacted_source,
+    after_yaml: historicalInspection.redacted_source,
+    changes,
+    diagnostics: historicalInspection.diagnostics,
+    can_restore: canRestore,
+    blockers
+  };
+}
+function diffSnapshots(current, historical) {
+  const before = new Map(current.files.map((file) => [file.path, file]));
+  const after = new Map(historical.files.map((file) => [file.path, file]));
+  const paths = [.../* @__PURE__ */ new Set([...before.keys(), ...after.keys()])].sort();
+  const changes = [];
+  for (const path of paths) {
+    const beforeFile = before.get(path);
+    const afterFile = after.get(path);
+    if (beforeFile && afterFile && hash(beforeFile.content) === hash(afterFile.content) && beforeFile.mode === afterFile.mode) {
+      continue;
+    }
+    const beforeText = beforeFile ? decodeText(beforeFile.content) : void 0;
+    const afterText = afterFile ? decodeText(afterFile.content) : void 0;
+    changes.push({
+      path,
+      change: !beforeFile ? "create" : !afterFile ? "delete" : "update",
+      binary: beforeFile !== void 0 && beforeText === null || afterFile !== void 0 && afterText === null,
+      before: beforeText === null ? void 0 : safeDiffText(path, beforeText),
+      after: afterText === null ? void 0 : safeDiffText(path, afterText)
+    });
+  }
+  return changes;
+}
+function safeDiffText(path, content) {
+  if (content === void 0 || !path.toLowerCase().endsWith(".json")) return content;
+  try {
+    return `${JSON.stringify(redactJson(JSON.parse(content)), null, 2)}
+`;
+  } catch {
+    return content;
+  }
+}
+function redactJson(value, key = "") {
+  if (Array.isArray(value)) return value.map((entry) => redactJson(entry));
+  if (!value || typeof value !== "object") {
+    return SENSITIVE_KEY.test(key) && typeof value === "string" && !ENV_REFERENCE.test(value) ? "[redacted]" : value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([entryKey, entry]) => [
+      entryKey,
+      redactJson(entry, entryKey)
+    ])
+  );
+}
+function decodeText(content) {
+  if (content.includes(0)) return null;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(content);
+  } catch {
+    return null;
+  }
+}
+async function assertSnapshotSafe(snapshot, projectRoot) {
+  const inspection = await inspectProjectSource(
+    snapshot.canonical_yaml,
+    resolve(projectRoot, ".openagentpack/build/agents.yaml")
+  );
+  const diagnostic = inspection.diagnostics.find((item) => item.severity === "error");
+  if (diagnostic) throw new UserError(diagnostic.message);
+  for (const file of snapshot.files) assertRelativePath(file.path);
+}
+function snapshotTreeHash(snapshot) {
+  const digest = createHash("sha256");
+  for (const file of [...snapshot.files].sort((left, right) => left.path.localeCompare(right.path))) {
+    digest.update(file.path).update("\0").update(String(file.mode)).update("\0").update(file.content).update("\0");
+  }
+  return digest.digest("hex");
+}
+function directoryContext(projectRoot) {
+  const normalized = resolve(projectRoot);
+  const storeRoot = resolve(normalized, ".openagentpack", "versions", "project");
+  return {
+    projectRoot: normalized,
+    storeRoot,
+    storePath: resolve(storeRoot, "store.json"),
+    entriesRoot: resolve(storeRoot, "entries"),
+    blobsRoot: resolve(storeRoot, "blobs"),
+    manifestsRoot: resolve(storeRoot, "manifests"),
+    lockRoot: resolve(normalized, ".openagentpack", "mutation.lock"),
+    leasePath: resolve(normalized, ".openagentpack", "mutation.lock", "lease.json")
+  };
+}
+function emptyStore() {
+  return { schema_version: DIRECTORY_STORE_SCHEMA, enabled: false, head_version: null };
+}
+async function readStore(context, required) {
+  try {
+    const value = await readJson(context.storePath);
+    if (value.schema_version !== DIRECTORY_STORE_SCHEMA || typeof value.enabled !== "boolean" || value.head_version !== null && !VERSION_ID.test(value.head_version)) {
+      throw new UserError("The project version store is invalid.");
+    }
+    return value;
+  } catch (error) {
+    if (isFsError(error, "ENOENT") && !required) return null;
+    if (isFsError(error, "ENOENT")) throw new UserError("No project version store exists. Run project init first.");
+    throw error;
+  }
+}
+async function requireStore(context) {
+  return await readStore(context, true);
+}
+async function readEntry(context, versionId) {
+  assertVersionId(versionId);
+  const entry = await readJson(resolve(context.entriesRoot, `${versionId}.json`));
+  if (entry.version_id !== versionId || entry.short_version !== versionId.slice(0, 12)) {
+    throw new UserError("A project version entry is invalid.");
+  }
+  return entry;
+}
+async function readChain(context, headVersion) {
+  const result = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = headVersion;
+  while (current) {
+    if (seen.has(current)) throw new UserError("The project version history contains a cycle.");
+    seen.add(current);
+    const entry = await readEntry(context, current);
+    result.push(entry);
+    current = entry.parent_version;
+  }
+  return result;
+}
+async function requireReachable(context, headVersion, versionId) {
+  assertVersionId(versionId);
+  const entry = (await readChain(context, headVersion)).find((candidate) => candidate.version_id === versionId);
+  if (!entry) throw new UserError("Project version is not reachable from the current history.");
+  return entry;
+}
+function publicVersion(entry) {
+  return {
+    version_id: entry.version_id,
+    short_version: entry.short_version,
+    parent_version: entry.parent_version,
+    tree_hash: entry.tree_hash,
+    yaml_hash: entry.yaml_hash,
+    message: entry.message,
+    created_by: entry.created_by,
+    created_at: entry.created_at
+  };
+}
+async function writeBlob(context, blobHash, content) {
+  const path = resolve(context.blobsRoot, blobHash);
+  try {
+    await stat(path);
+    return;
+  } catch (error) {
+    if (!isFsError(error, "ENOENT")) throw error;
+  }
+  await mkdir(context.blobsRoot, { recursive: true });
+  await writeFile(path, content, { flag: "wx" }).catch(async (error) => {
+    if (!isFsError(error, "EEXIST")) throw error;
+  });
+}
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  await rename(temporary, path);
+}
+async function acquireLease(context, kind) {
+  await mkdir(dirname(context.lockRoot), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await mkdir(context.lockRoot);
+      break;
+    } catch (error) {
+      if (!isFsError(error, "EEXIST")) throw error;
+      if (attempt === 0 && await recoverDeadLease(context)) continue;
+      throw new DirectoryProjectMutationConflictError(await mutationBlocker(context) ?? "Project is busy.");
+    }
+  }
+  const lease = { token: randomUUID(), pid: process.pid, kind, created_at: (/* @__PURE__ */ new Date()).toISOString() };
+  try {
+    await writeJsonAtomic(context.leasePath, lease);
+    return lease;
+  } catch (error) {
+    await rm(context.lockRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function assertLease(context, token) {
+  const lease = await readJson(context.leasePath);
+  if (lease.token !== token) throw new UserError("Project mutation lease changed.");
+}
+async function releaseLease(context, token) {
+  try {
+    await assertLease(context, token);
+    await rm(context.lockRoot, { recursive: true, force: true });
+  } catch (error) {
+    if (!isFsError(error, "ENOENT")) throw error;
+  }
+}
+async function mutationBlocker(context) {
+  try {
+    const lease = await readJson(context.leasePath);
+    if (!isProcessAlive(lease.pid) && await recoverDeadLease(context)) return null;
+    return `Project is busy with ${lease.kind} (pid ${lease.pid}).`;
+  } catch (error) {
+    return isFsError(error, "ENOENT") ? null : "Project mutation lock is unreadable.";
+  }
+}
+async function recoverDeadLease(context) {
+  let pid;
+  try {
+    const lease = await readJson(context.leasePath);
+    if (typeof lease.pid !== "number" || !Number.isSafeInteger(lease.pid) || lease.pid <= 0) return false;
+    pid = lease.pid;
+  } catch {
+    return false;
+  }
+  if (isProcessAlive(pid)) return false;
+  const stale = `${context.lockRoot}.stale.${randomUUID()}`;
+  try {
+    await rename(context.lockRoot, stale);
+  } catch (error) {
+    return isFsError(error, "ENOENT");
+  }
+  await rm(stale, { recursive: true, force: true });
+  return true;
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !isFsError(error, "ESRCH");
+  }
+}
+function decodeCursor(cursor) {
+  try {
+    const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (value.head !== null && (typeof value.head !== "string" || !VERSION_ID.test(value.head)) || !Number.isInteger(value.offset) || Number(value.offset) < 0) {
+      throw new Error("invalid");
+    }
+    return { head: value.head, offset: Number(value.offset) };
+  } catch {
+    throw new UserError("Invalid project version cursor.");
+  }
+}
+function hash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function assertRelativePath(path) {
+  if (!path || path.startsWith("/") || path.includes("\\") || path.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new UserError(`Invalid project snapshot path: ${path}`);
+  }
+}
+function assertVersionId(versionId) {
+  if (!VERSION_ID.test(versionId)) throw new UserError("Project version must be a full 64-character SHA-256 id.");
+}
+function isFsError(error, code) {
+  return !!error && typeof error === "object" && "code" in error && error.code === code;
+}
+
+// src/internal/project-versions/index.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { constants } from "fs";
+import { access, chmod, mkdir as mkdir2, open, readFile as readFile2, realpath, rename as rename2, rmdir, stat as stat2, unlink } from "fs/promises";
+import { basename, dirname as dirname2, relative, resolve as resolve2 } from "path";
+var STORE_SCHEMA_VERSION = 1;
+var SELF_IGNORE_SOURCE = "*\n";
+var ProjectVersionError = class extends UserError {
+  constructor(message, code = "storage_failed") {
+    super(message);
+    this.code = code;
+    this.name = "ProjectVersionError";
+  }
+  code;
+};
+var UserError2 = ProjectVersionError;
+async function readProjectVersionSource(configFile) {
+  const configPath = await resolveConfigPath(configFile);
+  return { configPath, source: await readFile2(configPath, "utf8") };
+}
+async function getProjectVersionStatus(configFile) {
+  const configPath = await resolveConfigPath(configFile);
+  const context = storeContext(configPath);
+  const store = await readStore2(context, false);
+  if (!store) return absentStatus(context);
+  const [source, blocker] = await Promise.all([readFile2(configPath, "utf8"), mutationBlocker2(context)]);
+  return publicStatus2(context, store, source, blocker ? [blocker] : []);
+}
+async function enableProjectVersioning(configFile, message = "Enable OpenAgentPack versioning") {
+  const { configPath, source } = await readProjectVersionSource(configFile);
+  await assertValidVersionSource(source, configPath);
+  const context = storeContext(configPath);
+  const lease = await acquireMutationLease(context, "version_enable");
+  try {
+    const store = await readStore2(context, false) ?? emptyStore2(context);
+    const head = await readHeadVersion(context, store);
+    store.enabled = true;
+    const version = head?.source_hash === sourceRevision(source) ? null : await appendVersion2(context, store, source, message);
+    if (!version) await writeStore(context, store);
+    return { version, versioning: await publicStatus2(context, store, source) };
+  } finally {
+    await releaseMutationLease(context, lease.token);
+  }
+}
+async function disableProjectVersioning(configFile) {
+  const configPath = await resolveConfigPath(configFile);
+  const context = storeContext(configPath);
+  const existing = await readStore2(context, false);
+  if (!existing) return absentStatus(context);
+  const lease = await acquireMutationLease(context, "version_disable");
+  try {
+    const store = await requireStore2(context);
+    store.enabled = false;
+    await writeStore(context, store);
+    return await publicStatus2(context, store, await readFile2(configPath, "utf8"));
+  } finally {
+    await releaseMutationLease(context, lease.token);
+  }
+}
+async function listProjectVersions(configFile, input = {}) {
+  const configPath = await resolveConfigPath(configFile);
+  const context = storeContext(configPath);
+  const store = await requireStore2(context);
+  const { offset, headVersion } = parseCursor(input.cursor, store.head_version);
+  if (headVersion !== store.head_version) {
+    throw new UserError2("Version history changed. Restart pagination from the first page.", "stale_snapshot");
+  }
+  const limit = Math.max(1, Math.min(input.limit ?? 50, 100));
+  const versions = await readVersionChain(context, store.head_version);
+  return {
+    versions: versions.slice(offset, offset + limit).map(publicVersion2),
+    next_cursor: offset + limit < versions.length ? encodeCursor({ headVersion: store.head_version, offset: offset + limit }) : null
+  };
+}
+async function previewProjectVersion(configFile, versionId) {
+  const configPath = await resolveConfigPath(configFile);
+  const context = storeContext(configPath);
+  const store = await requireStore2(context);
+  if (!store.head_version) throw new UserError2("The local version store has no versions.", "invalid_version");
+  const selected = await requireReachableVersion(context, store.head_version, versionId);
+  const [currentSource, historicalSource, blocker] = await Promise.all([
+    readFile2(configPath, "utf8"),
+    readBlob(context, selected),
+    mutationBlocker2(context)
+  ]);
+  const [currentInspection, historicalInspection] = await Promise.all([
+    inspectProjectSource(currentSource, configPath),
+    inspectProjectSource(historicalSource, configPath)
+  ]);
+  const blockers = blocker ? [blocker] : [];
+  return {
+    version_id: selected.version_id,
+    base_head_version: store.head_version,
+    base_source_revision: sourceRevision(currentSource),
+    before_yaml: currentInspection.redacted_source,
+    after_yaml: historicalInspection.redacted_source,
+    diagnostics: historicalInspection.diagnostics,
+    can_restore: historicalInspection.diagnostics.every((diagnostic) => diagnostic.severity !== "error") && blockers.length === 0,
+    blockers
+  };
+}
+async function restoreProjectVersion(configFile, versionId, base) {
+  const configPath = await resolveConfigPath(configFile);
+  const context = storeContext(configPath);
+  const lease = await acquireMutationLease(context, "version_restore");
+  try {
+    const store = await requireStore2(context);
+    assertHeadVersion(base.headVersion, store.head_version);
+    const selected = await requireReachableVersion(context, base.headVersion, versionId);
+    const currentSource = await readFile2(configPath, "utf8");
+    assertSourceRevision(base.sourceRevision, currentSource);
+    const historicalSource = await readBlob(context, selected);
+    const [currentInspection, historicalInspection] = await Promise.all([
+      inspectProjectSource(currentSource, configPath),
+      inspectProjectSource(historicalSource, configPath)
+    ]);
+    const validationError = historicalInspection.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+    if (validationError) throw new UserError2(validationError.message, "invalid_source");
+    await atomicWriteConfig(configPath, historicalSource, base.sourceRevision);
+    return {
+      version_id: selected.version_id,
+      base_head_version: base.headVersion,
+      base_source_revision: base.sourceRevision,
+      before_yaml: currentInspection.redacted_source,
+      after_yaml: historicalInspection.redacted_source,
+      diagnostics: historicalInspection.diagnostics,
+      can_restore: true,
+      blockers: []
+    };
+  } finally {
+    await releaseMutationLease(context, lease.token);
+  }
+}
+async function prepareProjectVersion(configFile, expectedSource) {
+  const configPath = await resolveConfigPath(configFile);
+  const context = storeContext(configPath);
+  const initialStore = await readStore2(context, false);
+  if (!initialStore?.enabled) return null;
+  const lease = await acquireMutationLease(context, "apply");
+  try {
+    const store = await requireStore2(context);
+    if (!store.enabled || !store.head_version) {
+      throw new UserError2("Automatic versioning changed while Apply was starting.", "stale_snapshot");
+    }
+    const source = await readFile2(configPath, "utf8");
+    if (source !== expectedSource) {
+      throw new UserError2(
+        "agents.yaml changed while Apply was being planned. Rerun Apply with the current file.",
+        "stale_snapshot"
+      );
+    }
+    await assertValidVersionSource(source, configPath);
+    const head = await readEntry2(context, store.head_version);
+    return {
+      configPath,
+      storeRoot: context.storeRoot,
+      baseHeadVersion: store.head_version,
+      source,
+      sourceRevision: sourceRevision(source),
+      needsVersion: head.source_hash !== sourceRevision(source),
+      leaseToken: lease.token
+    };
+  } catch (error) {
+    await releaseMutationLease(context, lease.token);
+    throw error;
+  }
+}
+async function commitPreparedProjectVersion(prepared, message = "Apply agents.yaml") {
+  const context = storeContext(prepared.configPath);
+  if (context.storeRoot !== prepared.storeRoot) {
+    throw postApplyVersionError("the local version store location changed");
+  }
+  try {
+    await assertMutationLease(context, prepared.leaseToken);
+    const currentSource = await readFile2(prepared.configPath, "utf8");
+    if (currentSource !== prepared.source || sourceRevision(currentSource) !== prepared.sourceRevision) {
+      throw new UserError2("agents.yaml changed while Apply was running", "stale_snapshot");
+    }
+    const store = await requireStore2(context);
+    if (!store.enabled) {
+      throw new UserError2("automatic versioning was disabled while Apply was running", "stale_snapshot");
+    }
+    assertHeadVersion(prepared.baseHeadVersion, store.head_version);
+    const head = await readEntry2(context, prepared.baseHeadVersion);
+    if (!prepared.needsVersion && head.source_hash === prepared.sourceRevision) return null;
+    return await appendVersion2(context, store, prepared.source, message);
+  } catch (error) {
+    if (error instanceof ProjectVersionError && error.message.startsWith("Remote Apply completed")) throw error;
+    throw postApplyVersionError(errorMessage(error));
+  } finally {
+    await releaseMutationLease(context, prepared.leaseToken).catch(() => void 0);
+  }
+}
+async function releasePreparedProjectVersion(prepared) {
+  if (!prepared) return;
+  await releaseMutationLease(storeContext(prepared.configPath), prepared.leaseToken);
+}
+function createProjectVersionService(input) {
+  const configPath = input.configPath;
+  return {
+    readSource: () => readProjectVersionSource(configPath),
+    status: () => getProjectVersionStatus(configPath),
+    enable: (message) => enableProjectVersioning(configPath, message),
+    disable: () => disableProjectVersioning(configPath),
+    listVersions: (options) => listProjectVersions(configPath, options),
+    previewVersion: (versionId) => previewProjectVersion(configPath, versionId),
+    restoreVersion: (versionId, base) => restoreProjectVersion(configPath, versionId, base),
+    prepareVersion: (expectedSource) => prepareProjectVersion(configPath, expectedSource),
+    commitPrepared: (prepared, message) => commitPreparedProjectVersion(prepared, message),
+    releasePrepared: (prepared) => releasePreparedProjectVersion(prepared)
+  };
+}
+async function appendVersion2(context, store, source, message) {
+  assertVersionMessage(message);
+  const sourceHash = sourceRevision(source);
+  await writeBlob2(context, sourceHash, source);
+  const entryWithoutId = {
+    parent_version: store.head_version,
+    source_hash: sourceHash,
+    message,
+    created_by: localAuthorName(),
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    nonce: randomUUID2()
+  };
+  const versionId = createHash2("sha256").update(JSON.stringify(entryWithoutId)).digest("hex");
+  const version = {
+    version_id: versionId,
+    short_version: versionId.slice(0, 12),
+    ...entryWithoutId
+  };
+  await writeEntry(context, version);
+  store.head_version = version.version_id;
+  await writeStore(context, store);
+  return publicVersion2(version);
+}
+function publicVersion2(version) {
+  const { nonce: _nonce, ...publicEntry } = version;
+  return publicEntry;
+}
+function storeContext(configPath) {
+  const storeRoot = resolve2(dirname2(configPath), ".openagentpack", "versions");
+  return {
+    configPath,
+    storeRoot,
+    storePath: resolve2(storeRoot, "store.json"),
+    entriesRoot: resolve2(storeRoot, "entries"),
+    blobsRoot: resolve2(storeRoot, "blobs"),
+    ignorePath: resolve2(storeRoot, ".gitignore"),
+    lockPath: resolve2(storeRoot, "mutation.lock"),
+    leasePath: resolve2(storeRoot, "mutation.lock", "lease.json"),
+    configRelativePath: relative(dirname2(configPath), configPath) || basename(configPath)
+  };
+}
+function emptyStore2(context) {
+  return {
+    schema_version: STORE_SCHEMA_VERSION,
+    config_path: context.configRelativePath,
+    enabled: false,
+    head_version: null
+  };
+}
+async function readStore2(context, required) {
+  let source;
+  try {
+    source = await readFile2(context.storePath, "utf8");
+  } catch (error) {
+    if (isFileSystemError(error, "ENOENT") && !required) return null;
+    if (isFileSystemError(error, "ENOENT")) {
+      throw new UserError2(
+        "No local version store exists for agents.yaml. Enable local versions first.",
+        "store_missing"
+      );
+    }
+    throw new UserError2(`Cannot read the local version store: ${errorMessage(error)}`, "storage_failed");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    throw new UserError2("The local version store is not valid JSON.", "storage_failed");
+  }
+  return parseStore(parsed, context);
+}
+async function requireStore2(context) {
+  return await readStore2(context, true);
+}
+function parseStore(value, context) {
+  if (!isRecord(value) || value.schema_version !== STORE_SCHEMA_VERSION) {
+    throw new UserError2("The local version store uses an unsupported schema.", "storage_failed");
+  }
+  if (value.config_path !== context.configRelativePath || typeof value.enabled !== "boolean") {
+    throw new UserError2("The local version store does not belong to this agents.yaml.", "storage_failed");
+  }
+  if (value.head_version !== null && !isVersionId(value.head_version)) {
+    throw new UserError2("The local version store has an invalid head version.", "storage_failed");
+  }
+  return {
+    schema_version: STORE_SCHEMA_VERSION,
+    config_path: value.config_path,
+    enabled: value.enabled,
+    head_version: value.head_version
+  };
+}
+async function readHeadVersion(context, store) {
+  return store.head_version ? readEntry2(context, store.head_version) : null;
+}
+async function readVersionChain(context, headVersion) {
+  const versions = [];
+  const seen = /* @__PURE__ */ new Set();
+  let currentVersion = headVersion;
+  while (currentVersion) {
+    if (seen.has(currentVersion)) {
+      throw new UserError2("The local version history contains a cycle.", "storage_failed");
+    }
+    seen.add(currentVersion);
+    const entry = await readEntry2(context, currentVersion);
+    versions.push(entry);
+    currentVersion = entry.parent_version;
+  }
+  return versions;
+}
+async function requireReachableVersion(context, headVersion, versionId) {
+  assertVersionId2(versionId);
+  const versions = await readVersionChain(context, headVersion);
+  const selected = versions.find((entry) => entry.version_id === versionId);
+  if (!selected) throw new UserError2("Local version was not found in the current history.", "invalid_version");
+  return selected;
+}
+async function readEntry2(context, versionId) {
+  assertVersionId2(versionId);
+  let source;
+  try {
+    source = await readFile2(resolve2(context.entriesRoot, `${versionId}.json`), "utf8");
+  } catch (error) {
+    if (isFileSystemError(error, "ENOENT")) {
+      throw new UserError2("A version entry in the local history is missing.", "storage_failed");
+    }
+    throw new UserError2(`Cannot read a version entry: ${errorMessage(error)}`, "storage_failed");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    throw new UserError2("A local version entry is not valid JSON.", "storage_failed");
+  }
+  return parseEntry(parsed, versionId);
+}
+function parseEntry(value, expectedVersionId) {
+  if (!isRecord(value) || value.version_id !== expectedVersionId || value.short_version !== expectedVersionId.slice(0, 12) || value.parent_version !== null && !isVersionId(value.parent_version) || !isVersionId(value.source_hash) || typeof value.message !== "string" || typeof value.created_by !== "string" || typeof value.created_at !== "string" || typeof value.nonce !== "string") {
+    throw new UserError2("The local version history contains an invalid entry.", "storage_failed");
+  }
+  const identity = {
+    parent_version: value.parent_version,
+    source_hash: value.source_hash,
+    message: value.message,
+    created_by: value.created_by,
+    created_at: value.created_at,
+    nonce: value.nonce
+  };
+  if (createHash2("sha256").update(JSON.stringify(identity)).digest("hex") !== expectedVersionId) {
+    throw new UserError2("A local version entry failed its identity check.", "storage_failed");
+  }
+  return {
+    version_id: expectedVersionId,
+    short_version: expectedVersionId.slice(0, 12),
+    ...identity
+  };
+}
+async function writeStore(context, store) {
+  await ensureStoreLayout(context);
+  await atomicWrite(context.storePath, `${JSON.stringify(store, null, 2)}
+`, 384);
+}
+async function writeEntry(context, version) {
+  await ensureStoreLayout(context);
+  await writeImmutable(
+    resolve2(context.entriesRoot, `${version.version_id}.json`),
+    `${JSON.stringify(version, null, 2)}
+`
+  );
+}
+async function writeBlob2(context, sourceHash, source) {
+  await ensureStoreLayout(context);
+  await writeImmutable(resolve2(context.blobsRoot, `${sourceHash}.yaml`), source);
+}
+async function readBlob(context, version) {
+  let source;
+  try {
+    source = await readFile2(resolve2(context.blobsRoot, `${version.source_hash}.yaml`), "utf8");
+  } catch (error) {
+    if (isFileSystemError(error, "ENOENT")) {
+      throw new UserError2("The YAML blob for this version is missing.", "invalid_version");
+    }
+    throw new UserError2(`Cannot read the YAML blob: ${errorMessage(error)}`, "storage_failed");
+  }
+  if (sourceRevision(source) !== version.source_hash) {
+    throw new UserError2("The YAML blob for this version failed its content hash check.", "invalid_version");
+  }
+  return source;
+}
+async function ensureStoreLayout(context) {
+  await mkdir2(context.entriesRoot, { recursive: true, mode: 448 });
+  await mkdir2(context.blobsRoot, { recursive: true, mode: 448 });
+  try {
+    await access(context.ignorePath, constants.F_OK);
+  } catch (error) {
+    if (!isFileSystemError(error, "ENOENT")) throw error;
+    await writeImmutable(context.ignorePath, SELF_IGNORE_SOURCE);
+  }
+}
+async function writeImmutable(path, source) {
+  try {
+    const existing = await readFile2(path, "utf8");
+    if (existing !== source) {
+      throw new UserError2("An immutable local version object has conflicting content.", "storage_failed");
+    }
+    return;
+  } catch (error) {
+    if (!isFileSystemError(error, "ENOENT")) throw error;
+  }
+  await atomicWrite(path, source, 384);
+}
+async function acquireMutationLease(context, kind) {
+  await ensureStoreLayout(context);
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      await mkdir2(context.lockPath, { mode: 448 });
+      const lease = {
+        pid: process.pid,
+        token: randomUUID2(),
+        kind,
+        created_at: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      await atomicWrite(context.leasePath, `${JSON.stringify(lease, null, 2)}
+`, 384);
+      return lease;
+    } catch (error) {
+      if (!isFileSystemError(error, "EEXIST")) {
+        throw new UserError2(`Cannot lock the local version store: ${errorMessage(error)}`, "storage_failed");
+      }
+      if (await recoverDeadLease2(context)) continue;
+      throw new UserError2(lockBlocker(context), "store_blocked");
+    }
+  }
+  throw new UserError2(lockBlocker(context), "store_blocked");
+}
+async function assertMutationLease(context, token) {
+  const lease = await readMutationLease(context);
+  if (!lease || lease.token !== token || lease.pid !== process.pid) {
+    throw new UserError2("The local version mutation lease changed while Apply was running.", "stale_snapshot");
+  }
+}
+async function releaseMutationLease(context, token) {
+  const lease = await readMutationLease(context);
+  if (!lease) return;
+  if (lease.token !== token || lease.pid !== process.pid) {
+    throw new UserError2("Refusing to release a local version lease owned by another process.", "store_blocked");
+  }
+  await unlink(context.leasePath);
+  await rmdir(context.lockPath);
+  await syncDirectory(context.storeRoot);
+}
+async function readMutationLease(context) {
+  let source;
+  try {
+    source = await readFile2(context.leasePath, "utf8");
+  } catch (error) {
+    if (isFileSystemError(error, "ENOENT")) return null;
+    throw new UserError2(`Cannot read the local version lease: ${errorMessage(error)}`, "storage_failed");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || typeof parsed.pid !== "number" || !Number.isSafeInteger(parsed.pid) || parsed.pid <= 0 || typeof parsed.token !== "string" || typeof parsed.kind !== "string" || typeof parsed.created_at !== "string") {
+    return null;
+  }
+  return {
+    pid: parsed.pid,
+    token: parsed.token,
+    kind: parsed.kind,
+    created_at: parsed.created_at
+  };
+}
+async function recoverDeadLease2(context) {
+  const lease = await readMutationLease(context);
+  if (!lease || isProcessAlive2(lease.pid)) return false;
+  const stalePath = `${context.lockPath}.stale.${lease.token}`;
+  try {
+    await rename2(context.lockPath, stalePath);
+  } catch (error) {
+    if (isFileSystemError(error, "ENOENT")) return true;
+    return false;
+  }
+  try {
+    await unlink(resolve2(stalePath, "lease.json"));
+    await rmdir(stalePath);
+    await syncDirectory(context.storeRoot);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isProcessAlive2(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !isFileSystemError(error, "ESRCH");
+  }
+}
+async function mutationBlocker2(context) {
+  try {
+    await access(context.lockPath, constants.F_OK);
+  } catch (error) {
+    if (isFileSystemError(error, "ENOENT")) return null;
+    throw new UserError2(`Cannot inspect the local version lease: ${errorMessage(error)}`, "storage_failed");
+  }
+  if (await recoverDeadLease2(context)) return null;
+  return lockBlocker(context);
+}
+function lockBlocker(context) {
+  return `Another process is changing this project. Wait for it to finish. Lock: ${context.lockPath}`;
+}
+async function publicStatus2(context, store, source, blockers = []) {
+  const head = await readHeadVersion(context, store);
+  const sourceVersioned = head?.source_hash === sourceRevision(source);
+  return {
+    initialized: true,
+    enabled: store.enabled,
+    store_root: context.storeRoot,
+    config_path: context.configRelativePath,
+    head_version: store.head_version,
+    source_status: head ? sourceVersioned ? "clean" : "modified" : "unversioned",
+    source_versioned: sourceVersioned,
+    write_blockers: blockers,
+    restore_blockers: blockers
+  };
+}
+function absentStatus(context) {
+  return {
+    initialized: false,
+    enabled: false,
+    store_root: context.storeRoot,
+    config_path: context.configRelativePath,
+    head_version: null,
+    source_status: "unversioned",
+    source_versioned: false,
+    write_blockers: [],
+    restore_blockers: []
+  };
+}
+async function assertValidVersionSource(source, configPath) {
+  const inspection = await inspectProjectSource(source, configPath);
+  const validationError = inspection.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+  if (validationError) throw new UserError2(validationError.message, "invalid_source");
+}
+async function resolveConfigPath(configFile) {
+  try {
+    return await realpath(resolve2(configFile));
+  } catch (error) {
+    throw new UserError2(`Cannot read agents.yaml: ${errorMessage(error)}`, "invalid_source");
+  }
+}
+async function atomicWriteConfig(configPath, source, expectedRevision) {
+  const currentSource = await readFile2(configPath, "utf8");
+  assertSourceRevision(expectedRevision, currentSource);
+  const fileStat = await stat2(configPath);
+  await atomicWrite(configPath, source, fileStat.mode & 511);
+}
+async function atomicWrite(path, source, mode) {
+  const temporaryPath = resolve2(dirname2(path), `.${basename(path)}.${process.pid}.${randomUUID2()}.tmp`);
+  const handle = await open(temporaryPath, "wx", mode);
+  try {
+    await handle.writeFile(source, "utf8");
+    await handle.sync();
+    await chmod(temporaryPath, mode);
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename2(temporaryPath, path);
+    await syncDirectory(dirname2(path));
+  } finally {
+    await unlink(temporaryPath).catch(() => void 0);
+  }
+}
+async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+function assertHeadVersion(expected, current) {
+  if (expected !== current) {
+    throw new UserError2("The current local version changed. Reload versions and retry.", "stale_snapshot");
+  }
+}
+function assertSourceRevision(expected, source) {
+  if (sourceRevision(source) !== expected) {
+    throw new UserError2("agents.yaml changed. Preview the version again before restoring.", "stale_snapshot");
+  }
+}
+function sourceRevision(source) {
+  return createHash2("sha256").update(source).digest("hex");
+}
+function assertVersionId2(versionId) {
+  if (!isVersionId(versionId)) {
+    throw new UserError2("Version ID must be a full 64-character hexadecimal value.", "invalid_version");
+  }
+}
+function isVersionId(value) {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+function assertVersionMessage(message) {
+  if (!message.trim() || message !== message.trim() || message.length > 120 || /[\r\n]/.test(message)) {
+    throw new UserError2("Version message must be one trimmed line between 1 and 120 characters.", "invalid_source");
+  }
+}
+function encodeCursor(input) {
+  return Buffer.from(JSON.stringify(input)).toString("base64url");
+}
+function parseCursor(cursor, currentHead) {
+  if (!cursor) return { headVersion: currentHead, offset: 0 };
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (!isRecord(parsed) || parsed.headVersion !== null && !isVersionId(parsed.headVersion) || typeof parsed.offset !== "number" || !Number.isSafeInteger(parsed.offset) || parsed.offset < 0) {
+      throw new Error("invalid");
+    }
+    return { headVersion: parsed.headVersion, offset: parsed.offset };
+  } catch {
+    throw new UserError2("Version cursor is invalid.", "invalid_version");
+  }
+}
+function localAuthorName() {
+  return process.env.OPENAGENTPACK_VERSION_AUTHOR?.trim() || process.env.USER?.trim() || process.env.USERNAME?.trim() || "local";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFileSystemError(error, code) {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function postApplyVersionError(reason) {
+  return new UserError2(
+    `Remote Apply completed, but agents.yaml could not be versioned: ${reason}. Fix the local version store and rerun Apply; a no-op Apply will retry the version.`,
+    "storage_failed"
+  );
+}
+
+export {
+  DirectoryProjectMutationConflictError,
+  createDirectoryProjectVersionService,
+  ProjectVersionError,
+  readProjectVersionSource,
+  getProjectVersionStatus,
+  enableProjectVersioning,
+  disableProjectVersioning,
+  listProjectVersions,
+  previewProjectVersion,
+  restoreProjectVersion,
+  prepareProjectVersion,
+  commitPreparedProjectVersion,
+  releasePreparedProjectVersion,
+  createProjectVersionService
+};