@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,668 @@
+// src/content/catalog.ts
+import fs2 from "node:fs";
+import path2 from "node:path";
+import { createHash as createHash2 } from "node:crypto";
+
+// src/content/resources.ts
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+function collectSkillResources(skillRoot) {
+  const root = path.resolve(skillRoot);
+  const files = [];
+  function checkReference(from, reference) {
+    if (/^(?:https?:|mailto:|data:|#)/i.test(reference)) return;
+    const clean = decodeURIComponent(reference.split(/[?#]/)[0]);
+    if (!clean) return;
+    const target = path.resolve(path.dirname(from), clean);
+    const relative = path.relative(root, target);
+    if (path.isAbsolute(clean) || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+      throw new Error(`\u8D44\u6E90\u5F15\u7528\u8D8A\u8FC7\u6280\u80FD\u8FB9\u754C\uFF1A${reference}`);
+    if (!fs.existsSync(target))
+      throw new Error(`\u7F3A\u5C11\u5F15\u7528\u8D44\u6E90\uFF1A${reference}\uFF08${from}\uFF09`);
+  }
+  function walk(dir) {
+    if (fs.lstatSync(dir).isSymbolicLink())
+      throw new Error(`\u6280\u80FD\u8D44\u6E90\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${dir}`);
+    for (const name of fs.readdirSync(dir).sort()) {
+      const file = path.join(dir, name);
+      const stat = fs.lstatSync(file);
+      if (stat.isSymbolicLink())
+        throw new Error(`\u6280\u80FD\u8D44\u6E90\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${file}`);
+      if (stat.isDirectory()) {
+        walk(file);
+        continue;
+      }
+      if (!stat.isFile()) throw new Error(`\u4E0D\u652F\u6301\u7684\u8D44\u6E90\u7C7B\u578B\uFF1A${file}`);
+      const content = fs.readFileSync(file);
+      files.push({
+        relativePath: path.relative(root, file).split(path.sep).join("/"),
+        hash: createHash("sha256").update(content).digest("hex")
+      });
+      if (file.endsWith(".md"))
+        for (const match of content.toString("utf8").matchAll(/\]\(([^\s)]+)(?:\s+"[^"]*")?\)/g))
+          checkReference(file, match[1]);
+      if (/\.[cm]?[jt]s$/.test(file)) {
+        for (const match of content.toString("utf8").matchAll(/(?:\bfrom\s*|\bimport\s*\(?\s*)["'](\.[^"']+)["']/g))
+          checkReference(file, match[1]);
+      }
+    }
+  }
+  walk(root);
+  return files.sort(
+    (a, b) => a.relativePath < b.relativePath ? -1 : a.relativePath > b.relativePath ? 1 : 0
+  );
+}
+
+// src/content/catalog.ts
+function readMethodResource(packageRoot, method, language) {
+  const allowed = [
+    "source-driven-development",
+    "doc-sync",
+    "debug",
+    "refactoring",
+    "tdd"
+  ];
+  if (!allowed.includes(method))
+    throw new Error(`\u672A\u77E5\u516C\u5171\u65B9\u6CD5\uFF1A${String(method)}`);
+  if (language !== "en" && language !== "zh-CN")
+    throw new Error(`\u4E0D\u652F\u6301\u7684\u8BED\u8A00\uFF1A${String(language)}`);
+  const root = language === "en" ? packageRoot : path2.join(packageRoot, "localized", language);
+  const file = path2.join(root, "methods", `${method}.md`);
+  if (fs2.lstatSync(file).isSymbolicLink())
+    throw new Error(`\u65B9\u6CD5\u8D44\u6E90\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${file}`);
+  return fs2.readFileSync(file);
+}
+function hash(content) {
+  return createHash2("sha256").update(content).digest("hex");
+}
+function readContentCatalog(packageRoot, language) {
+  if (language !== "en" && language !== "zh-CN")
+    throw new Error(`\u4E0D\u652F\u6301\u7684\u8BED\u8A00\uFF1A${String(language)}`);
+  const root = fs2.realpathSync(packageRoot);
+  const pkg = JSON.parse(
+    fs2.readFileSync(path2.join(root, "package.json"), "utf8")
+  );
+  if (!pkg || typeof pkg !== "object") throw new Error("\u516C\u5171\u5305\u5143\u6570\u636E\u65E0\u6548");
+  const { name, version, repository } = pkg;
+  const repositoryUrl = typeof repository === "string" ? repository : repository && typeof repository === "object" ? repository.url : void 0;
+  if (name !== "@bovinphang/craft-common" || typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version) || typeof repositoryUrl !== "string")
+    throw new Error("\u516C\u5171\u5305\u540D\u79F0\u3001\u7248\u672C\u6216 repository \u65E0\u6548");
+  const contentRoot = language === "en" ? root : path2.join(root, "localized", language);
+  const skillsDir = path2.join(contentRoot, "skills");
+  if (!fs2.existsSync(skillsDir))
+    throw new Error(`\u7F3A\u5C11 ${language} \u516C\u5171\u5185\u5BB9\uFF1A${skillsDir}`);
+  if (fs2.lstatSync(skillsDir).isSymbolicLink())
+    throw new Error(`\u516C\u5171\u6280\u80FD\u76EE\u5F55\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${skillsDir}`);
+  const skills = fs2.readdirSync(skillsDir).sort().flatMap((id) => {
+    const skillRoot = path2.join(skillsDir, id);
+    const stat = fs2.lstatSync(skillRoot);
+    if (stat.isSymbolicLink())
+      throw new Error(`\u516C\u5171\u6280\u80FD\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${skillRoot}`);
+    if (!stat.isDirectory()) return [];
+    if (!/^cc-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id))
+      throw new Error(`\u516C\u5171\u6280\u80FD ID \u65E0\u6548\uFF1A${id}`);
+    const files = collectSkillResources(skillRoot);
+    if (!files.some((file) => file.relativePath === "SKILL.md"))
+      throw new Error(`\u7F3A\u5C11\u516C\u5171\u6280\u80FD\u5165\u53E3\uFF1A${id}/SKILL.md`);
+    return [
+      { id, version, sourcePackage: name, repository: repositoryUrl, files }
+    ];
+  });
+  if (!skills.length) throw new Error(`\u6CA1\u6709 ${language} \u516C\u5171\u6280\u80FD`);
+  const content = {
+    schemaVersion: 1,
+    packageName: name,
+    packageVersion: version,
+    language,
+    skills
+  };
+  return {
+    ...content,
+    root: contentRoot,
+    digest: hash(JSON.stringify(content))
+  };
+}
+
+// src/install/identity.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
+import { createHash as createHash3 } from "node:crypto";
+function canonicalPath(input) {
+  let current = path3.resolve(input);
+  const missing = [];
+  while (!fs3.existsSync(current)) {
+    const parent = path3.dirname(current);
+    if (parent === current) throw new Error(`\u65E0\u6CD5\u89E3\u6790\u771F\u5B9E\u8DEF\u5F84\uFF1A${input}`);
+    missing.unshift(path3.basename(current));
+    current = parent;
+  }
+  return path3.join(fs3.realpathSync.native(current), ...missing);
+}
+function resolveSharedIdentity(skillsDir) {
+  const target = canonicalPath(skillsDir);
+  const store = path3.join(path3.dirname(target), "craft-manifests");
+  if (fs3.existsSync(store) && fs3.lstatSync(store).isSymbolicLink())
+    throw new Error("\u516C\u5171\u8D26\u672C\u76EE\u5F55\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5");
+  const key = createHash3("sha256").update(process.platform === "win32" ? target.toLowerCase() : target).digest("hex");
+  const ledgerDir = path3.join(store, key);
+  if (fs3.existsSync(ledgerDir) && fs3.lstatSync(ledgerDir).isSymbolicLink())
+    throw new Error("\u516C\u5171\u8D26\u672C\u76EE\u5F55\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5");
+  return { target, ledgerDir };
+}
+
+// src/install/planner.ts
+import fs4 from "node:fs";
+import path4 from "node:path";
+import { createHash as createHash4 } from "node:crypto";
+var hashBytes = (bytes) => createHash4("sha256").update(bytes).digest("hex");
+function consumerIdentity(consumer) {
+  if (!consumer.product || !["local", "global"].includes(consumer.scope) || !path4.isAbsolute(consumer.manifestPath))
+    throw new Error("\u516C\u5171\u4F9D\u8D56\u6D88\u8D39\u8005\u8EAB\u4EFD\u65E0\u6548");
+  const manifest = canonicalPath(consumer.manifestPath);
+  return hashBytes(
+    JSON.stringify([
+      consumer.product,
+      process.platform === "win32" ? manifest.toLowerCase() : manifest,
+      consumer.scope
+    ])
+  );
+}
+function safeManagedPath(root, relative) {
+  if (!relative || relative.includes("\\") || path4.isAbsolute(relative) || relative.split("/").some((part) => !part || part === "." || part === ".."))
+    throw new Error(`\u516C\u5171\u8D44\u6E90\u8DEF\u5F84\u8D8A\u754C\uFF1A${relative}`);
+  const target = path4.resolve(root, relative);
+  const remainder = path4.relative(path4.resolve(root), target);
+  if (!remainder || remainder.startsWith(`..${path4.sep}`) || remainder === ".." || path4.isAbsolute(remainder))
+    throw new Error(`\u516C\u5171\u8D44\u6E90\u8D8A\u8FC7\u8FB9\u754C\uFF1A${relative}`);
+  let current = target;
+  const boundary = path4.resolve(root);
+  while (true) {
+    if (fs4.existsSync(current) && fs4.lstatSync(current).isSymbolicLink())
+      throw new Error(`\u6258\u7BA1\u8DEF\u5F84\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${current}`);
+    if (current === boundary) break;
+    current = path4.dirname(current);
+  }
+  return target;
+}
+function currentHash(file) {
+  try {
+    const stat = fs4.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+      throw new Error(`\u6258\u7BA1\u8DEF\u5F84\u4E0D\u662F\u666E\u901A\u6587\u4EF6\uFF1A${file}`);
+    return hashBytes(fs4.readFileSync(file));
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function readJson(file) {
+  const hash2 = currentHash(file);
+  if (hash2 === null) return void 0;
+  try {
+    return JSON.parse(fs4.readFileSync(file, "utf8"));
+  } catch {
+    throw new Error(`\u516C\u5171\u8D26\u672C JSON \u635F\u574F\uFF1A${file}`);
+  }
+}
+var object = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function json(value) {
+  return Buffer.from(`${JSON.stringify(value, null, 2)}
+`);
+}
+function planSharedDeployment(request) {
+  if (!["install", "update", "uninstall"].includes(request.action))
+    throw new Error("\u672A\u77E5\u516C\u5171\u5B89\u88C5\u64CD\u4F5C");
+  const { target, ledgerDir } = resolveSharedIdentity(request.skillsDir);
+  const id = consumerIdentity(request.consumer);
+  const catalog = request.catalog;
+  if (request.action !== "uninstall" && !catalog)
+    throw new Error("\u516C\u5171\u5B89\u88C5\u7F3A\u5C11\u5185\u5BB9\u76EE\u5F55");
+  const desired = /* @__PURE__ */ new Map();
+  if (catalog && request.action !== "uninstall") {
+    if (catalog.schemaVersion !== 1 || catalog.packageName !== "@bovinphang/craft-common" || !["en", "zh-CN"].includes(catalog.language))
+      throw new Error("\u516C\u5171\u5185\u5BB9\u76EE\u5F55\u65E0\u6548");
+    for (const skill of catalog.skills) {
+      if (!/^cc-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.id))
+        throw new Error(`\u516C\u5171\u6280\u80FD\u8DEF\u5F84\u65E0\u6548\uFF1A${skill.id}`);
+      for (const file of skill.files) {
+        const relative = `${skill.id}/${file.relativePath}`;
+        safeManagedPath(target, relative);
+        const source = safeManagedPath(catalog.root, `skills/${relative}`);
+        const bytes = fs4.readFileSync(source);
+        if (hashBytes(bytes) !== file.hash)
+          throw new Error(`\u516C\u5171\u5185\u5BB9\u6765\u6E90\u6458\u8981\u4E0D\u5339\u914D\uFF1A${relative}`);
+        if (desired.has(relative))
+          throw new Error(`\u91CD\u590D\u516C\u5171\u8D44\u6E90\u8DEF\u5F84\uFF1A${relative}`);
+        desired.set(relative, bytes);
+      }
+    }
+  }
+  const manifestPath = safeManagedPath(ledgerDir, "craft-common.json");
+  const lockPath = safeManagedPath(ledgerDir, "dependencies.lock.json");
+  const rawManifest = readJson(manifestPath), rawLock = readJson(lockPath);
+  if (Boolean(rawManifest) !== Boolean(rawLock))
+    throw new Error("\u516C\u5171\u8D26\u672C\u4E0D\u5B8C\u6574\uFF0C\u4FDD\u7559\u8D44\u6E90\u7B49\u5F85\u4FEE\u590D");
+  let manifest;
+  let lock = { schemaVersion: 1, target, consumers: {} };
+  if (rawManifest !== void 0) {
+    if (!object(rawManifest) || rawManifest.schemaVersion !== 1 || rawManifest.target !== target || typeof rawManifest.packageVersion !== "string" || !["en", "zh-CN"].includes(String(rawManifest.language)) || typeof rawManifest.sourceDigest !== "string" || !object(rawManifest.files) || typeof rawManifest.residual !== "boolean" || !object(rawLock) || rawLock.schemaVersion !== 1 || rawLock.target !== target || !object(rawLock.consumers))
+      throw new Error("\u516C\u5171\u8D26\u672C\u7ED3\u6784\u6216\u76EE\u6807\u8EAB\u4EFD\u65E0\u6548");
+    for (const [relative, hash2] of Object.entries(rawManifest.files)) {
+      safeManagedPath(target, relative);
+      if (!relative.startsWith("cc-") || typeof hash2 !== "string" || !/^[a-f0-9]{64}$/.test(hash2))
+        throw new Error("\u516C\u5171\u8D26\u672C\u6587\u4EF6\u6240\u6709\u6743\u65E0\u6548");
+    }
+    for (const [key, entry] of Object.entries(rawLock.consumers)) {
+      if (!object(entry) || !object(entry.consumer) || typeof entry.requiredVersion !== "string" || typeof entry.digest !== "string" || !["en", "zh-CN"].includes(String(entry.language)))
+        throw new Error("\u516C\u5171\u6D88\u8D39\u8005\u8D26\u672C\u65E0\u6548");
+      const consumer = entry.consumer;
+      if (consumerIdentity(consumer) !== key)
+        throw new Error("\u516C\u5171\u6D88\u8D39\u8005\u6807\u8BC6\u4E0D\u5339\u914D");
+      if (entry.requiredVersion !== rawManifest.packageVersion || entry.language !== rawManifest.language || entry.digest !== rawManifest.sourceDigest)
+        throw new Error("\u516C\u5171\u4F9D\u8D56\u58F0\u660E\u4E0E\u5185\u5BB9\u8D26\u672C\u4E0D\u4E00\u81F4");
+    }
+    manifest = rawManifest;
+    lock = rawLock;
+  }
+  const plan = {
+    schemaVersion: 1,
+    target,
+    stateDigest: hashBytes(
+      JSON.stringify([rawManifest ?? null, rawLock ?? null])
+    ),
+    mutations: [],
+    conflicts: []
+  };
+  if (catalog && request.action !== "uninstall") {
+    const { root: _root, digest, ...content } = catalog;
+    if (hashBytes(JSON.stringify(content)) !== digest) {
+      plan.conflicts.push("\u516C\u5171\u5185\u5BB9\u76EE\u5F55\u6458\u8981\u65E0\u6548\uFF0C\u62D2\u7EDD\u8986\u76D6\u76F8\u540C\u7248\u672C");
+      return plan;
+    }
+  }
+  const mutate = (file, after) => {
+    const beforeHash = currentHash(file);
+    if (after === null ? beforeHash !== null : beforeHash !== hashBytes(after))
+      plan.mutations.push({
+        path: file,
+        beforeHash,
+        after
+      });
+  };
+  if (request.action === "uninstall") {
+    if (!manifest || !lock.consumers[id]) return plan;
+    if (request.retainConsumer) return plan;
+    delete lock.consumers[id];
+    if (Object.keys(lock.consumers).length) {
+      mutate(lockPath, json(lock));
+      return plan;
+    }
+    const residual = {};
+    for (const [relative, ownedHash] of Object.entries(manifest.files)) {
+      const dest = safeManagedPath(target, relative);
+      const actualHash = currentHash(dest);
+      if (actualHash === null) continue;
+      if (actualHash === ownedHash) mutate(dest, null);
+      else residual[relative] = ownedHash;
+    }
+    if (Object.keys(residual).length) {
+      mutate(
+        manifestPath,
+        json({ ...manifest, files: residual, residual: true })
+      );
+      mutate(lockPath, json(lock));
+    } else {
+      mutate(manifestPath, null);
+      mutate(lockPath, null);
+    }
+    return plan;
+  }
+  if (!catalog) throw new Error("\u516C\u5171\u5B89\u88C5\u7F3A\u5C11\u6765\u6E90");
+  const others = Object.entries(lock.consumers).filter(([key]) => key !== id);
+  if (manifest && (manifest.packageVersion !== catalog.packageVersion || manifest.language !== catalog.language || manifest.sourceDigest !== catalog.digest) && (others.length || request.action !== "update"))
+    plan.conflicts.push("\u516C\u5171\u7248\u672C\u3001\u8BED\u8A00\u6216\u6E90\u6458\u8981\u51B2\u7A81\uFF0C\u8BF7\u534F\u8C03\u6D88\u8D39\u8005\u540E\u66F4\u65B0");
+  for (const [relative, ownedHash] of Object.entries(manifest?.files ?? {})) {
+    const actualHash = currentHash(safeManagedPath(target, relative));
+    if (actualHash !== null && actualHash !== ownedHash)
+      plan.conflicts.push(`\u516C\u5171\u6258\u7BA1\u6587\u4EF6\u5DF2\u4FEE\u6539\uFF1A${relative}`);
+  }
+  for (const [relative] of desired) {
+    if (currentHash(safeManagedPath(target, relative)) !== null && !manifest?.files[relative])
+      plan.conflicts.push(`\u672A\u77E5\u6765\u6E90\u540C\u540D\u516C\u5171\u6587\u4EF6\uFF1A${relative}`);
+  }
+  if (plan.conflicts.length) return plan;
+  for (const [relative, bytes] of desired)
+    mutate(safeManagedPath(target, relative), bytes);
+  for (const relative of Object.keys(manifest?.files ?? {}))
+    if (!desired.has(relative)) mutate(safeManagedPath(target, relative), null);
+  lock.consumers[id] = {
+    consumer: {
+      ...request.consumer,
+      manifestPath: canonicalPath(request.consumer.manifestPath)
+    },
+    requiredVersion: catalog.packageVersion,
+    language: catalog.language,
+    digest: catalog.digest
+  };
+  const updated = {
+    schemaVersion: 1,
+    target,
+    packageVersion: catalog.packageVersion,
+    language: catalog.language,
+    sourceDigest: catalog.digest,
+    files: Object.fromEntries(
+      [...desired].map(([relative, bytes]) => [relative, hashBytes(bytes)])
+    ),
+    residual: false
+  };
+  mutate(manifestPath, json(updated));
+  mutate(lockPath, json(lock));
+  return plan;
+}
+
+// src/install/transaction.ts
+import fs5 from "node:fs";
+import path5 from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+var journalName = "transaction.json";
+function atomicWrite(file, bytes, token) {
+  fs5.mkdirSync(path5.dirname(file), { recursive: true });
+  const temp = `${file}.${token}.tmp`;
+  try {
+    const mode = fs5.existsSync(file) ? fs5.statSync(file).mode & 511 : 384;
+    fs5.writeFileSync(temp, bytes, { flag: "wx", mode });
+    fs5.renameSync(temp, file);
+  } catch (error) {
+    try {
+      fs5.unlinkSync(temp);
+    } catch (cleanupError) {
+      if (cleanupError.code !== "ENOENT")
+        throw new AggregateError(
+          [error, cleanupError],
+          "\u539F\u5B50\u5199\u5165\u53CA\u4E34\u65F6\u6587\u4EF6\u6E05\u7406\u5931\u8D25"
+        );
+    }
+    throw error;
+  }
+}
+function release(lockFile, lease) {
+  if (!fs5.existsSync(lockFile)) return;
+  const existing = JSON.parse(fs5.readFileSync(lockFile, "utf8"));
+  if (existing.token !== lease.token)
+    throw new Error("\u516C\u5171\u5B89\u88C5\u9501\u5F52\u5C5E\u6539\u53D8\uFF0C\u4FDD\u7559\u73B0\u573A");
+  fs5.unlinkSync(lockFile);
+}
+function acquire(ledgerDir) {
+  const lockFile = safeManagedPath(ledgerDir, "install.lock");
+  fs5.mkdirSync(ledgerDir, { recursive: true, mode: 448 });
+  const lease = {
+    pid: process.pid,
+    host: os.hostname(),
+    token: randomUUID()
+  };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      fs5.writeFileSync(lockFile, JSON.stringify(lease), {
+        flag: "wx",
+        mode: 384
+      });
+      return { lockFile, lease };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      let previous;
+      try {
+        previous = JSON.parse(fs5.readFileSync(lockFile, "utf8"));
+      } catch {
+        throw new Error("\u65E0\u6CD5\u786E\u8BA4\u516C\u5171\u5B89\u88C5\u9501\u8EAB\u4EFD\uFF0C\u8BF7\u68C0\u67E5\u4FDD\u7559\u73B0\u573A");
+      }
+      if (previous.host !== os.hostname() || !Number.isSafeInteger(previous.pid) || previous.pid <= 0 || typeof previous.token !== "string")
+        throw new Error("\u65E0\u6CD5\u786E\u8BA4\u516C\u5171\u5B89\u88C5\u9501\u6240\u5C5E\u8FDB\u7A0B");
+      try {
+        process.kill(previous.pid, 0);
+      } catch (probe) {
+        if (probe.code !== "ESRCH")
+          throw new Error("\u65E0\u6CD5\u786E\u8BA4\u516C\u5171\u5B89\u88C5\u9501\u662F\u5426\u5931\u6548");
+        const reclaimFile = safeManagedPath(ledgerDir, "reclaim.lock");
+        try {
+          fs5.writeFileSync(reclaimFile, JSON.stringify(lease), {
+            flag: "wx",
+            mode: 384
+          });
+        } catch {
+          throw new Error("\u516C\u5171\u5B89\u88C5\u9501\u6B63\u5728\u6062\u590D\u6216\u6062\u590D\u9501\u9700\u4EBA\u5DE5\u68C0\u67E5");
+        }
+        try {
+          if (fs5.readFileSync(lockFile, "utf8") !== JSON.stringify(previous))
+            throw new Error("\u516C\u5171\u5B89\u88C5\u9501\u53D1\u751F\u5E76\u53D1\u53D8\u5316");
+          fs5.unlinkSync(lockFile);
+        } finally {
+          fs5.unlinkSync(reclaimFile);
+        }
+        continue;
+      }
+      throw new Error(`\u516C\u5171\u5B89\u88C5\u6B63\u5728\u6267\u884C\uFF0C\u9501\u8FDB\u7A0B ${previous.pid}`);
+    }
+  }
+  throw new Error("\u65E0\u6CD5\u53D6\u5F97\u516C\u5171\u5B89\u88C5\u9501");
+}
+function validateDestination(file, target, ledgerDir, productRoots) {
+  const absolute = path5.resolve(file);
+  const sharedRelative = path5.relative(target, absolute).split(path5.sep).join("/");
+  if (sharedRelative.startsWith("cc-") && !sharedRelative.startsWith("../")) {
+    safeManagedPath(target, sharedRelative);
+    return;
+  }
+  if (["craft-common.json", "dependencies.lock.json"].some(
+    (name) => absolute === path5.join(ledgerDir, name)
+  )) {
+    safeManagedPath(ledgerDir, path5.basename(absolute));
+    return;
+  }
+  for (const root of productRoots) {
+    const relative = path5.relative(root, absolute).split(path5.sep).join("/");
+    if (relative && relative !== ".." && !relative.startsWith("../") && !path5.isAbsolute(relative)) {
+      safeManagedPath(root, relative);
+      return;
+    }
+  }
+  throw new Error(`\u4E8B\u52A1\u5199\u5165\u8D8A\u8FC7\u5141\u8BB8\u8FB9\u754C\uFF1A${file}`);
+}
+function validateJournal(value, target, ledgerDir, productRoots) {
+  const journal = value;
+  if (!journal || journal.schemaVersion !== 1 || journal.target !== target || !["prepared", "committed"].includes(journal.phase) || !/^[a-f0-9-]{36}$/.test(journal.token) || !Array.isArray(journal.entries))
+    throw new Error("\u516C\u5171\u4E8B\u52A1\u8BB0\u5F55\u65E0\u6548\uFF0C\u4FDD\u7559\u73B0\u573A");
+  const paths = /* @__PURE__ */ new Set();
+  for (const entry of journal.entries) {
+    if (!entry || typeof entry.path !== "string" || !path5.isAbsolute(entry.path) || paths.has(entry.path))
+      throw new Error("\u516C\u5171\u4E8B\u52A1\u8DEF\u5F84\u65E0\u6548");
+    paths.add(entry.path);
+    validateDestination(entry.path, target, ledgerDir, productRoots);
+    for (const side of ["before", "after"]) {
+      const bytes = entry[side], hash2 = entry[`${side}Hash`];
+      if (bytes === null ? hash2 !== null : typeof bytes !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        bytes
+      ) || hashBytes(Buffer.from(bytes, "base64")) !== hash2)
+        throw new Error("\u516C\u5171\u4E8B\u52A1\u5185\u5BB9\u6458\u8981\u65E0\u6548");
+    }
+  }
+  return journal;
+}
+function restore(journal, token) {
+  for (const entry of [...journal.entries].reverse()) {
+    const actual = currentHash(entry.path);
+    if (actual !== entry.beforeHash && actual !== entry.afterHash)
+      throw new Error(`\u4E8B\u52A1\u671F\u95F4\u6587\u4EF6\u88AB\u4FEE\u6539\uFF0C\u4FDD\u7559\u6062\u590D\u8BB0\u5F55\uFF1A${entry.path}`);
+    if (actual === entry.beforeHash) continue;
+    if (entry.before === null) fs5.unlinkSync(entry.path);
+    else atomicWrite(entry.path, Buffer.from(entry.before, "base64"), token);
+  }
+}
+function recoverUnderLease(target, ledgerDir, token, productRoots) {
+  const file = safeManagedPath(ledgerDir, journalName);
+  if (!fs5.existsSync(file)) return "clean";
+  const journal = validateJournal(
+    JSON.parse(fs5.readFileSync(file, "utf8")),
+    target,
+    ledgerDir,
+    productRoots
+  );
+  if (journal.phase === "prepared") restore(journal, token);
+  else
+    for (const entry of journal.entries)
+      if (currentHash(entry.path) !== entry.afterHash)
+        throw new Error(`\u5DF2\u63D0\u4EA4\u4E8B\u52A1\u5B58\u5728\u5916\u90E8\u4FEE\u6539\uFF0C\u4FDD\u7559\u6062\u590D\u8BB0\u5F55\uFF1A${entry.path}`);
+  fs5.unlinkSync(file);
+  return "recovered";
+}
+async function recoverSharedTransaction(skillsDir, allowedProductRoots = []) {
+  const { target, ledgerDir } = resolveSharedIdentity(skillsDir);
+  if (!fs5.existsSync(ledgerDir)) return "clean";
+  const { lockFile, lease } = acquire(ledgerDir);
+  try {
+    return recoverUnderLease(
+      target,
+      ledgerDir,
+      lease.token,
+      allowedProductRoots.map(canonicalPath)
+    );
+  } finally {
+    release(lockFile, lease);
+  }
+}
+function normalizeProductPath(file, roots) {
+  const absolute = path5.resolve(file);
+  const candidates = roots.flatMap((root) => {
+    const real = canonicalPath(root);
+    return [
+      { boundary: path5.resolve(root), real },
+      { boundary: real, real }
+    ];
+  }).sort((a, b) => b.boundary.length - a.boundary.length);
+  for (const { boundary, real } of candidates) {
+    const relative = path5.relative(boundary, absolute);
+    if (!relative || relative === ".." || relative.startsWith(`..${path5.sep}`) || path5.isAbsolute(relative))
+      continue;
+    let current = absolute;
+    while (current !== boundary) {
+      try {
+        if (fs5.lstatSync(current).isSymbolicLink())
+          throw new Error(`\u4EA7\u54C1\u6258\u7BA1\u8DEF\u5F84\u4E0D\u5141\u8BB8\u7B26\u53F7\u94FE\u63A5\uFF1A${current}`);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      current = path5.dirname(current);
+    }
+    return safeManagedPath(real, relative.split(path5.sep).join("/"));
+  }
+  throw new Error(`\u4EA7\u54C1\u5199\u5165\u8D8A\u8FC7\u5141\u8BB8\u8FB9\u754C\uFF1A${file}`);
+}
+async function executeSharedPlan(request, options) {
+  const { target, ledgerDir } = resolveSharedIdentity(request.skillsDir);
+  const roots = (options.allowedProductRoots ?? []).map(canonicalPath);
+  const products = (options.productMutations ?? []).map((mutation) => ({
+    ...mutation,
+    path: normalizeProductPath(
+      mutation.path,
+      options.allowedProductRoots ?? []
+    )
+  }));
+  for (const mutation of products) {
+    const file = mutation.path;
+    const shared = path5.relative(target, file).split(path5.sep).join("/");
+    const ledger = path5.relative(ledgerDir, file).split(path5.sep).join("/");
+    if (shared.toLowerCase().startsWith("cc-") && !shared.startsWith("../") || !ledger || ledger !== ".." && !ledger.startsWith("../") && !path5.isAbsolute(ledger))
+      throw new Error(`\u4EA7\u54C1\u4E0D\u80FD\u8BA4\u9886\u516C\u5171\u8D44\u6E90\u6216\u8D26\u672C\uFF1A${file}`);
+    validateDestination(file, target, ledgerDir, roots);
+  }
+  if (options.dryRun) {
+    if (fs5.existsSync(path5.join(ledgerDir, journalName)))
+      throw new Error("\u5B58\u5728\u5F85\u6062\u590D\u516C\u5171\u4E8B\u52A1\uFF0Cdry-run \u4E0D\u6267\u884C\u6062\u590D");
+    const plan = planSharedDeployment(request);
+    if (plan.conflicts.length) throw new Error(plan.conflicts.join("\n"));
+    for (const entry of products) {
+      validateDestination(entry.path, target, ledgerDir, roots);
+      if (currentHash(entry.path) !== entry.beforeHash)
+        throw new Error(`\u4EA7\u54C1\u6587\u4EF6\u5728\u89C4\u5212\u540E\u5DF2\u4FEE\u6539\uFF1A${entry.path}`);
+    }
+    return plan;
+  }
+  if (!fs5.existsSync(path5.join(ledgerDir, journalName))) {
+    const initial = planSharedDeployment(request);
+    if (initial.conflicts.length) throw new Error(initial.conflicts.join("\n"));
+  }
+  const { lockFile, lease } = acquire(ledgerDir);
+  const journalFile = safeManagedPath(ledgerDir, journalName);
+  let journal;
+  try {
+    recoverUnderLease(target, ledgerDir, lease.token, roots);
+    const plan = planSharedDeployment(request);
+    if (plan.conflicts.length) throw new Error(plan.conflicts.join("\n"));
+    const mutations = [...plan.mutations, ...products];
+    const paths = /* @__PURE__ */ new Set();
+    const entries = mutations.map((mutation) => {
+      const file = path5.resolve(mutation.path);
+      validateDestination(file, target, ledgerDir, roots);
+      if (paths.has(file)) throw new Error(`\u516C\u5171\u4E0E\u4EA7\u54C1\u5199\u5165\u91CD\u590D\u8BA4\u9886\uFF1A${file}`);
+      paths.add(file);
+      if (currentHash(file) !== mutation.beforeHash)
+        throw new Error(`\u4EA7\u54C1\u6216\u516C\u5171\u6587\u4EF6\u5728\u89C4\u5212\u540E\u5DF2\u4FEE\u6539\uFF1A${file}`);
+      return {
+        path: file,
+        before: mutation.beforeHash === null ? null : fs5.readFileSync(file).toString("base64"),
+        after: mutation.after?.toString("base64") ?? null,
+        beforeHash: mutation.beforeHash,
+        afterHash: mutation.after === null ? null : hashBytes(mutation.after)
+      };
+    });
+    if (!entries.length) return plan;
+    journal = {
+      schemaVersion: 1,
+      target,
+      phase: "prepared",
+      token: lease.token,
+      entries
+    };
+    atomicWrite(journalFile, Buffer.from(JSON.stringify(journal)), lease.token);
+    for (const entry of entries) {
+      if (currentHash(entry.path) !== entry.beforeHash)
+        throw new Error(`\u4E8B\u52A1\u6267\u884C\u524D\u6587\u4EF6\u5DF2\u4FEE\u6539\uFF1A${entry.path}`);
+      if (entry.after === null) fs5.unlinkSync(entry.path);
+      else
+        atomicWrite(
+          entry.path,
+          Buffer.from(entry.after, "base64"),
+          lease.token
+        );
+    }
+    journal.phase = "committed";
+    atomicWrite(journalFile, Buffer.from(JSON.stringify(journal)), lease.token);
+    fs5.unlinkSync(journalFile);
+    return plan;
+  } catch (error) {
+    if (journal?.phase === "prepared") {
+      try {
+        restore(journal, lease.token);
+        fs5.unlinkSync(journalFile);
+      } catch (rollbackError) {
+        throw new AggregateError(
+          [error, rollbackError],
+          "\u516C\u5171\u5B89\u88C5\u5931\u8D25\u4E14\u9700\u4FDD\u7559\u4E8B\u52A1\u8BB0\u5F55\u7EE7\u7EED\u6062\u590D"
+        );
+      }
+    }
+    throw error;
+  } finally {
+    release(lockFile, lease);
+  }
+}
+export {
+  collectSkillResources,
+  executeSharedPlan,
+  planSharedDeployment,
+  readContentCatalog,
+  readMethodResource,
+  recoverSharedTransaction,
+  resolveSharedIdentity
+};

package/dist/install/identity.d.ts

@@ -0,0 +1,5 @@
+export declare function canonicalPath(input: string): string;
+export declare function resolveSharedIdentity(skillsDir: string): {
+    target: string;
+    ledgerDir: string;
+};

package/dist/install/planner.d.ts

@@ -0,0 +1,6 @@
+import type { CommonPlan, Consumer, SharedRequest } from "./types.js";
+export declare const hashBytes: (bytes: string | Buffer) => string;
+export declare function consumerIdentity(consumer: Consumer): string;
+export declare function safeManagedPath(root: string, relative: string): string;
+export declare function currentHash(file: string): string | null;
+export declare function planSharedDeployment(request: SharedRequest): CommonPlan;

package/dist/install/transaction.d.ts

@@ -0,0 +1,7 @@
+import type { CommonPlan, FileMutation, SharedRequest } from "./types.js";
+export declare function recoverSharedTransaction(skillsDir: string, allowedProductRoots?: string[]): Promise<"clean" | "recovered">;
+export declare function executeSharedPlan(request: SharedRequest, options: {
+    dryRun: boolean;
+    productMutations?: FileMutation[];
+    allowedProductRoots?: string[];
+}): Promise<CommonPlan>;