@jstn-sdk/ma 0.1.13 → 0.14.0

package/src/skill-installer.js

@@ -1,13 +1,19 @@
+import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { getAgent } from "./agents.js";
 import { getBundledDocsPath, packageRoot } from "./paths.js";
 
 function resolveCodexHome() {
   return process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex");
 }
 
-function resolveSkillInstallRoot() {
+function resolveSkillInstallRoot(agentType = "codex") {
+  const agent = getAgent(agentType);
+  if (agentType !== "codex" && agent.globalSkillsDir?.startsWith("~/")) {
+    return path.join(os.homedir(), agent.globalSkillsDir.slice(2));
+  }
   return path.join(resolveCodexHome(), "skills");
 }
 
@@ -15,14 +21,16 @@ function resolveSupportBundleRoot() {
   return path.join(resolveCodexHome(), "meta-architect-sdk");
 }
 
-async function copyDir(src, dest) {
+async function copyDir(src, dest, { omitIndex = false } = {}) {
   await fs.mkdir(dest, { recursive: true });
   const entries = await fs.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
+    if (omitIndex && entry.name === "index.json") continue;
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      await copyDir(srcPath, destPath);
+    const sourceStat = entry.isSymbolicLink() ? await fs.stat(srcPath) : entry;
+    if (sourceStat.isDirectory()) {
+      await copyDir(srcPath, destPath, { omitIndex });
     } else {
       await fs.copyFile(srcPath, destPath);
     }
@@ -38,8 +46,55 @@ async function pathExists(targetPath) {
   }
 }
 
-export function getSkillInstallRoot() {
-  return resolveSkillInstallRoot();
+async function listFiles(root, current = root, output = []) {
+  const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (entry.name === ".ma-install-receipt.json" || entry.name === ".ma-backups") continue;
+    const absolute = path.join(current, entry.name);
+    if (entry.isDirectory()) await listFiles(root, absolute, output);
+    else if (entry.isFile()) output.push(path.relative(root, absolute));
+  }
+  return output.sort();
+}
+
+async function treeHash(root) {
+  const hash = crypto.createHash("sha256");
+  for (const relative of await listFiles(root)) {
+    hash.update(relative);
+    hash.update(await fs.readFile(path.join(root, relative)));
+  }
+  return hash.digest("hex");
+}
+
+export async function readInstallReceipt(root, kind = "skills") {
+  try {
+    return JSON.parse(await fs.readFile(installReceiptPath(root, kind), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function installReceiptPath(root, kind = "skills") {
+  if (kind === "skills" && path.basename(root) === "skills") {
+    return path.join(path.dirname(root), ".ma", "codex-skills-install-receipt.json");
+  }
+  return path.join(root, ".ma-install-receipt.json");
+}
+
+async function writeInstallReceipt(root, receipt, kind = "skills") {
+  const receiptPath = installReceiptPath(root, kind);
+  await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+  await fs.writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+}
+
+async function backupPath(root, source, label) {
+  const backupRoot = path.join(root, ".ma-backups", `${Date.now()}-${label}`);
+  await copyPath(source, backupRoot);
+  return backupRoot;
+}
+
+export function getSkillInstallRoot(agentType = "codex") {
+  return resolveSkillInstallRoot(agentType);
 }
 
 export function getSupportBundleRoot() {
@@ -55,24 +110,59 @@ export async function loadSkillManifest() {
 export async function installSkills({ targetRoot = getSkillInstallRoot() } = {}) {
   const skills = await loadSkillManifest();
   await fs.mkdir(targetRoot, { recursive: true });
+  const previous = await readInstallReceipt(targetRoot, "skills");
+  const managed = new Set(previous?.managedPaths ?? []);
 
   const installed = [];
+  const conflicts = [];
+  const backups = [];
   for (const skill of skills) {
     const src = path.join(packageRoot, skill.path);
     const dest = path.join(targetRoot, path.basename(skill.path));
-    await fs.rm(dest, { recursive: true, force: true });
-    await copyDir(src, dest);
-    installed.push({ name: skill.name, dest });
+    if (await pathExists(dest)) {
+      if (!managed.has(path.basename(skill.path))) {
+        conflicts.push({ name: skill.name, dest, reason: "existing-unmanaged-path" });
+        continue;
+      }
+      backups.push({
+        name: skill.name,
+        path: await backupPath(targetRoot, dest, path.basename(skill.path)),
+      });
+      await fs.rm(dest, { recursive: true, force: true });
+    }
+    await copyDir(src, dest, {
+      omitIndex: dest.endsWith(path.join("plugins", "meta-architect", "skills")),
+    });
+    installed.push({ name: skill.name, dest, hash: await treeHash(dest) });
   }
 
-  return { targetRoot, installed };
+  await writeInstallReceipt(
+    targetRoot,
+    {
+      schemaVersion: "1.0.0",
+      record_type: "codex_skill_install_receipt",
+      packageName: "@jstn-sdk/ma",
+      packageVersion: JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"))
+        .version,
+      installedAt: new Date().toISOString(),
+      managedPaths: installed.map((entry) => path.basename(entry.dest)),
+      installed,
+      conflicts,
+      backups,
+    },
+    "skills",
+  );
+
+  return { targetRoot, installed, conflicts, backups };
 }
 
 async function copyPath(src, dest) {
   const stat = await fs.stat(src);
   if (stat.isDirectory()) {
     await fs.rm(dest, { recursive: true, force: true });
-    await copyDir(src, dest);
+    await copyDir(src, dest, {
+      omitIndex: dest.endsWith(path.join("plugins", "meta-architect", "skills")),
+    });
     return "directory";
   }
 
@@ -81,80 +171,143 @@ async function copyPath(src, dest) {
   return "file";
 }
 
-export async function installSupportBundle({ targetRoot = getSupportBundleRoot() } = {}) {
-  const assets = [
-    {
-      name: "mcp",
-      src: path.join(packageRoot, "mcp"),
-      dest: path.join(targetRoot, "mcp"),
-    },
-    {
-      name: "sprint",
-      src: path.join(packageRoot, "sprint"),
-      dest: path.join(targetRoot, "sprint"),
-    },
-    {
-      name: "prompts",
-      src: path.join(packageRoot, ".codex", "prompts"),
-      dest: path.join(targetRoot, "prompts"),
-    },
-    {
-      name: "scripts",
-      src: path.join(packageRoot, "scripts"),
-      dest: path.join(targetRoot, "scripts"),
-    },
-    {
-      name: "plugin",
-      src: path.join(packageRoot, "plugins", "meta-architect"),
-      dest: path.join(targetRoot, "plugins", "meta-architect"),
-    },
-    {
-      name: "templates",
-      src: path.join(packageRoot, "templates"),
-      dest: path.join(targetRoot, "templates"),
-    },
-    {
-      name: "docs-readme",
-      src: getBundledDocsPath("README.md"),
-      dest: path.join(targetRoot, "docs", "README.md"),
-    },
-  ];
-
-  const optionalAssets = [
-    {
-      name: "docs-reference",
-      src: getBundledDocsPath("reference"),
-      dest: path.join(targetRoot, "docs", "reference"),
-    },
-  ];
-
-  for (const asset of optionalAssets) {
-    if (await pathExists(asset.src)) {
-      assets.push(asset);
+export async function loadSupportBundleManifest() {
+  const manifest = JSON.parse(
+    await fs.readFile(path.join(packageRoot, "support-bundle.json"), "utf8"),
+  );
+  if (
+    manifest.schemaVersion !== "1.0.0" ||
+    !/^\d+\.\d+\.\d+$/.test(manifest.bundleVersion) ||
+    manifest.compatibility?.managedBy !== "@jstn-sdk/ma" ||
+    typeof manifest.compatibility?.node !== "string"
+  ) {
+    throw new Error("Invalid support bundle manifest version");
+  }
+  if (!Array.isArray(manifest.assets) || manifest.assets.length === 0) {
+    throw new Error("Support bundle manifest must define assets");
+  }
+  for (const asset of manifest.assets) {
+    if (
+      typeof asset.name !== "string" ||
+      typeof asset.source !== "string" ||
+      typeof asset.destination !== "string" ||
+      !["file", "directory"].includes(asset.type) ||
+      typeof asset.required !== "boolean"
+    ) {
+      throw new Error(`Invalid support bundle asset: ${asset.name ?? "(unnamed)"}`);
     }
   }
+  return manifest;
+}
+
+export async function installSupportBundle({ targetRoot = getSupportBundleRoot() } = {}) {
+  const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+  const bundle = await loadSupportBundleManifest();
+  if (bundle.bundleVersion !== pkg.version) {
+    throw new Error(
+      `Support bundle manifest ${bundle.bundleVersion} does not match package ${pkg.version}`,
+    );
+  }
 
   await fs.mkdir(targetRoot, { recursive: true });
+  const previous = await readInstallReceipt(targetRoot, "support");
+  const managed = new Set(previous?.managedPaths ?? []);
   const installed = [];
-  for (const asset of assets) {
-    await copyPath(asset.src, asset.dest);
-    installed.push({ name: asset.name, dest: asset.dest });
+  const conflicts = [];
+  const backups = [];
+  for (const asset of bundle.assets) {
+    const source =
+      asset.source === "docs/README.md"
+        ? getBundledDocsPath("README.md")
+        : asset.source === "docs/reference"
+          ? getBundledDocsPath("reference")
+          : path.join(packageRoot, asset.source);
+    if (!(await pathExists(source))) {
+      if (asset.required) throw new Error(`Missing required support bundle asset: ${asset.source}`);
+      continue;
+    }
+    const destination = path.join(targetRoot, asset.destination);
+    if (await pathExists(destination)) {
+      if (!managed.has(asset.destination)) {
+        conflicts.push({ name: asset.name, dest: destination, reason: "existing-unmanaged-path" });
+        continue;
+      }
+      backups.push({
+        name: asset.name,
+        path: await backupPath(targetRoot, destination, asset.name),
+      });
+    }
+    await copyPath(source, destination);
+    installed.push({
+      name: asset.name,
+      class: asset.class,
+      dest: destination,
+      relative: asset.destination,
+    });
   }
 
-  const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
   const manifest = {
+    schemaVersion: bundle.schemaVersion,
+    bundleVersion: bundle.bundleVersion,
     packageName: pkg.name,
     packageVersion: pkg.version,
     installedAt: new Date().toISOString(),
     root: targetRoot,
     assets: installed,
+    conflicts,
+    backups,
   };
   await fs.writeFile(
     path.join(targetRoot, "asset-manifest.json"),
     `${JSON.stringify(manifest, null, 2)}\n`,
   );
+  await writeInstallReceipt(
+    targetRoot,
+    {
+      ...manifest,
+      record_type: "codex_support_bundle_install_receipt",
+      managedPaths: installed.map((asset) => asset.relative),
+      conflicts,
+      backups,
+    },
+    "support",
+  );
 
-  return { targetRoot, installed };
+  return { targetRoot, installed, conflicts, backups };
+}
+
+export async function rollbackInstalledAssets({ targetRoot, kind = "skills" } = {}) {
+  const root = targetRoot ?? (kind === "skills" ? getSkillInstallRoot() : getSupportBundleRoot());
+  const receipt = await readInstallReceipt(root, kind);
+  if (!receipt) return { status: "nothing-to-rollback", removed: [], restored: [], skipped: [] };
+  const restored = [];
+  const removed = [];
+  const skipped = [];
+  for (const entry of receipt.installed ?? []) {
+    const relative = entry.relative ?? path.basename(entry.dest);
+    const dest = path.isAbsolute(entry.dest) ? entry.dest : path.join(root, relative);
+    if (!(await pathExists(dest))) continue;
+    if (entry.hash && (await treeHash(dest)) !== entry.hash) {
+      skipped.push({ path: dest, reason: "modified-after-install" });
+      continue;
+    }
+    await fs.rm(dest, { recursive: true, force: true });
+    removed.push(dest);
+  }
+  for (const backup of receipt.backups ?? []) {
+    if (!(await pathExists(backup.path))) continue;
+    const relative =
+      receipt.installed?.find((entry) => entry.name === backup.name)?.relative ?? backup.name;
+    const dest = path.join(root, relative);
+    await fs.rm(dest, { recursive: true, force: true });
+    await copyPath(backup.path, dest);
+    restored.push(dest);
+  }
+  if (kind === "support") {
+    await fs.rm(path.join(root, "asset-manifest.json"), { force: true });
+  }
+  if (skipped.length === 0) await fs.rm(installReceiptPath(root, kind), { force: true });
+  return { status: skipped.length ? "partial" : "rolled-back", removed, restored, skipped };
 }
 
 export async function areSkillsInstalled({ targetRoot = getSkillInstallRoot() } = {}) {
@@ -173,6 +326,8 @@ export async function areSkillsInstalled({ targetRoot = getSkillInstallRoot() }
 }
 
 export async function isSupportBundleInstalled({ targetRoot = getSupportBundleRoot() } = {}) {
+  const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+  const bundle = await loadSupportBundleManifest();
   const requiredFiles = [
     path.join(targetRoot, "asset-manifest.json"),
     path.join(targetRoot, "mcp", "servers.json"),
@@ -205,16 +360,16 @@ export async function isSupportBundleInstalled({ targetRoot = getSupportBundleRo
 
   const manifestPath = path.join(targetRoot, "asset-manifest.json");
   const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+  if (manifest.schemaVersion !== "1.0.0" || manifest.bundleVersion !== pkg.version) {
+    return false;
+  }
   const assetNames = new Set((manifest.assets ?? []).map((asset) => asset.name));
 
-  for (const requiredAssetName of ["mcp", "docs-readme"]) {
-    if (!assetNames.has(requiredAssetName)) {
+  for (const requiredAsset of bundle.assets.filter((asset) => asset.required)) {
+    if (!assetNames.has(requiredAsset.name)) {
       return false;
     }
   }
-  if ((await pathExists(getBundledDocsPath("reference"))) && !assetNames.has("docs-reference")) {
-    return false;
-  }
 
   return true;
 }