@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/lib/collective/vendor-skills.test.mjs

@@ -0,0 +1,306 @@
+/**
+ * Tests for lib/collective/vendor-skills.mjs — installing the VENDORED design
+ * skill packs into a seat's ~/.claude/skills.
+ *
+ * Three properties carry the weight, and each is pinned here:
+ *
+ *   1. **It installs under the frontmatter name**, not the directory name —
+ *      `taste-skill/skills/soft-skill` is `high-end-visual-design` to every
+ *      piece of prose that refers to it, including the harmoniser skill.
+ *   2. **It is idempotent.** A second run over an unchanged tree writes
+ *      nothing, because `global-setup` runs on every upgrade hop on 40+ seats.
+ *   3. **It never clobbers a directory that is not ours.** A human who
+ *      installed upstream `impeccable` themselves — launcher, hooks, live mode
+ *      — keeps it, and the run says so instead of silently taking it away.
+ *
+ * The end-to-end cases run against the REAL vendored trees in a throwaway HOME,
+ * because a plan that is right about a synthetic pack and wrong about
+ * `emilkowalski`'s nested skill roots would ship.
+ *
+ * @module lib/collective/vendor-skills.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  frontmatterName, ownership, planVendorSkills, installVendorSkills, markerFor,
+  packSize, looksLikeSkillsDir, MARKER_FILE, MARKER_OWNER,
+} from "./vendor-skills.mjs";
+import { PACKS, findPack } from "../../scripts/vendor/skill-packs.mjs";
+
+const SDK_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** A throwaway HOME. Returns {home, skillsDir, cleanup}. */
+function throwawayHome() {
+  const home = mkdtempSync(join(tmpdir(), "maestro-vendor-home-"));
+  return {
+    home,
+    skillsDir: join(home, ".claude", "skills"),
+    cleanup: () => rmSync(home, { recursive: true, force: true }),
+  };
+}
+
+describe("vendor-skills: pure helpers", () => {
+  it("frontmatterName reads the name and refuses a body that has none", () => {
+    assert.equal(frontmatterName("---\nname: impeccable\nversion: 4.3.1\n---\n# x"), "impeccable");
+    assert.equal(frontmatterName('---\nname: "quoted-name"\n---\n'), "quoted-name");
+    assert.equal(frontmatterName("# no frontmatter\n"), null);
+    assert.equal(frontmatterName("---\ndescription: no name here\n---\n"), null);
+  });
+
+  it("frontmatterName refuses a name that would escape the skills directory", () => {
+    assert.equal(frontmatterName("---\nname: ../../etc\n---\n"), null);
+    assert.equal(frontmatterName("---\nname: a/b\n---\n"), null);
+  });
+
+  it("looksLikeSkillsDir only accepts a path ending in skills/", () => {
+    assert.equal(looksLikeSkillsDir("/home/x/.claude/skills"), true);
+    assert.equal(looksLikeSkillsDir("/home/x/.claude"), false);
+  });
+
+  it("markerFor is deterministic — no clock, so a re-run writes nothing", () => {
+    const pack = findPack("unlazy");
+    assert.equal(markerFor(pack, "unlazy"), markerFor(pack, "unlazy"));
+    const doc = JSON.parse(markerFor(pack, "unlazy"));
+    assert.equal(doc.owner, MARKER_OWNER);
+    assert.equal(doc.sha, pack.sha);
+  });
+});
+
+describe("vendor-skills: ownership", () => {
+  it("reports absent / ours / foreign", () => {
+    const { home, cleanup } = throwawayHome();
+    try {
+      const absent = join(home, "nothing");
+      assert.equal(ownership(absent), "absent");
+
+      const foreign = join(home, "impeccable");
+      mkdirSync(foreign, { recursive: true });
+      writeFileSync(join(foreign, "SKILL.md"), "the human's own install\n");
+      assert.equal(ownership(foreign), "foreign");
+
+      const ours = join(home, "unlazy");
+      mkdirSync(ours, { recursive: true });
+      writeFileSync(join(ours, MARKER_FILE), markerFor(findPack("unlazy"), "unlazy"));
+      assert.equal(ownership(ours), "ours");
+
+      writeFileSync(join(ours, MARKER_FILE), "{not json");
+      assert.equal(ownership(ours), "foreign", "an unreadable marker is not proof of ownership");
+
+      writeFileSync(join(ours, MARKER_FILE), JSON.stringify({ owner: "someone-else" }));
+      assert.equal(ownership(ours), "foreign");
+    } finally { cleanup(); }
+  });
+});
+
+describe("vendor-skills: the plan over the real vendored trees", () => {
+  const { skills, errors } = planVendorSkills({ sdkRoot: SDK_ROOT, skillsDir: "/tmp/unused", packs: PACKS });
+
+  it("plans one skill per declared skill root, with no errors", () => {
+    assert.deepEqual(errors, [], "every pack's tree is present and every root has a SKILL.md");
+    const roots = PACKS.reduce((n, p) => n + p.skillRoots.length, 0);
+    assert.equal(skills.length, roots);
+  });
+
+  it("installs under the frontmatter name, not the directory name", () => {
+    const names = skills.map((s) => s.name);
+    for (const expected of [
+      "impeccable", "unlazy",
+      "emil-design-eng", "animate", "animation-vocabulary", "apple-design",
+      "find-animation-opportunities", "improve-animations", "review-animations", "prototype",
+      "design-taste-frontend", "redesign-existing-projects", "high-end-visual-design", "minimalist-ui",
+    ]) assert.ok(names.includes(expected), `expected skill ${expected}, got ${names.join(", ")}`);
+    assert.equal(new Set(names).size, names.length, "no two packs claim the same directory");
+  });
+
+  it("gives every skill a SKILL.md at its root and never a sibling skill's files", () => {
+    for (const s of skills) {
+      assert.ok(s.files.some((f) => f.to === "SKILL.md"), `${s.name} has SKILL.md at its root`);
+      assert.ok(s.files.every((f) => !f.to.startsWith("skills/")), `${s.name} carries no nested skills/ path`);
+    }
+    const animate = skills.find((s) => s.name === "animate");
+    assert.ok(animate.files.some((f) => f.to === "RECIPES.md"), "sibling reference file comes along");
+    assert.ok(animate.files.some((f) => f.to === "LICENSE"), "a sub-directory skill still ships its licence");
+    assert.ok(!animate.files.some((f) => f.to.includes("apple-design")), "a sibling skill's files stay out");
+  });
+
+  it("impeccable brings its reference tree, its subordinate briefs and its NOTICE", () => {
+    const imp = skills.find((s) => s.name === "impeccable");
+    assert.ok(imp.files.some((f) => f.to === "NOTICE.md"));
+    assert.ok(imp.files.some((f) => f.to.startsWith("reference/")));
+    assert.ok(imp.files.some((f) => f.to.startsWith("agents/impeccable-")));
+  });
+
+  it("a pack whose vendored tree is absent is an error, not a crash", () => {
+    const r = planVendorSkills({ sdkRoot: join(tmpdir(), "no-such-sdk-root"), skillsDir: "/tmp/unused", packs: PACKS });
+    assert.equal(r.skills.length, 0);
+    assert.equal(r.errors.length, PACKS.length);
+  });
+});
+
+describe("vendor-skills: install into a throwaway HOME", () => {
+  it("installs every pack skill, is idempotent, and heals a tampered file", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const first = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.deepEqual(first.errors, []);
+      assert.deepEqual(first.skipped, []);
+      assert.equal(first.unchanged.length, 0);
+      assert.ok(first.installed.length >= 14, `installed ${first.installed.length} skills`);
+
+      // The bytes landed, under the frontmatter name, with our marker.
+      const impeccable = join(skillsDir, "impeccable");
+      assert.ok(existsSync(join(impeccable, "SKILL.md")));
+      assert.ok(existsSync(join(impeccable, "reference", "critique.md")));
+      assert.ok(existsSync(join(impeccable, "LICENSE")));
+      assert.equal(ownership(impeccable), "ours");
+      assert.equal(statSync(join(impeccable, "SKILL.md")).mode & 0o777, 0o644);
+
+      const minimalist = join(skillsDir, "minimalist-ui");
+      assert.match(readFileSync(join(minimalist, "SKILL.md"), "utf8"), /name: minimalist-ui/);
+
+      // Second run: nothing written.
+      const second = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.deepEqual(second.installed, [], "idempotent");
+      assert.equal(second.unchanged.length, first.installed.length);
+
+      // A locally edited file is restored; a stray file inside a directory we
+      // own is removed (it would otherwise be read as skill content forever).
+      writeFileSync(join(impeccable, "SKILL.md"), "tampered\n");
+      writeFileSync(join(impeccable, "stray.md"), "not upstream\n");
+      const third = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.ok(third.installed.includes("impeccable"));
+      assert.match(readFileSync(join(impeccable, "SKILL.md"), "utf8"), /^---\nname: impeccable/);
+      assert.equal(existsSync(join(impeccable, "stray.md")), false);
+    } finally { cleanup(); }
+  });
+
+  it("leaves a FOREIGN directory exactly as it is and says which one", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      // The human installed upstream impeccable themselves — launcher and all.
+      const foreign = join(skillsDir, "impeccable");
+      mkdirSync(join(foreign, "scripts"), { recursive: true });
+      const own = "---\nname: impeccable\n---\nthe human's own copy, with its launcher\n";
+      writeFileSync(join(foreign, "SKILL.md"), own);
+      writeFileSync(join(foreign, "scripts", "impeccable"), "#!/bin/sh\n");
+
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      assert.deepEqual(r.installed.includes("impeccable"), false, "not installed over the human's copy");
+      assert.equal(r.skipped.length, 1);
+      assert.equal(r.skipped[0].name, "impeccable");
+      assert.match(r.skipped[0].reason, /not maestro's/);
+      assert.equal(readFileSync(join(foreign, "SKILL.md"), "utf8"), own, "byte-for-byte untouched");
+      assert.ok(existsSync(join(foreign, "scripts", "impeccable")), "their launcher is still theirs");
+      // Every other pack still installed.
+      assert.ok(r.installed.includes("unlazy"));
+      assert.ok(existsSync(join(skillsDir, "unlazy", "SKILL.md")));
+    } finally { cleanup(); }
+  });
+
+  it("dryRun reports what it would do and writes nothing", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, dryRun: true });
+      assert.ok(r.installed.length > 0);
+      assert.equal(existsSync(skillsDir), false, "nothing written");
+    } finally { cleanup(); }
+  });
+
+  it("refuses a destination that is not a skills directory, and writes nothing", () => {
+    // The failure this pins: an unset variable interpolated to
+    // "undefined/home/.claude/skills" and a full 14-skill tree was created at
+    // ./undefined/ relative to the cwd, inside a repo checkout.
+    const home = mkdtempSync(join(tmpdir(), "maestro-vendor-bogus-"));
+    try {
+      const bogus = join(home, ".claude", "skulls");
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir: bogus, packs: PACKS });
+      assert.equal(r.ok, false);
+      assert.deepEqual(r.installed, []);
+      assert.match(r.errors[0].error, /not a skills directory/);
+      assert.equal(existsSync(bogus), false, "nothing was created");
+    } finally { rmSync(home, { recursive: true, force: true }); }
+  });
+
+  it("refuses to install two packs into one skill name rather than letting one eat the other", () => {
+    // No collision exists today; the registry is meant to grow, and
+    // ownership() reads only the owner string, so the second pack would see
+    // "ours", delete the first pack's files as stale and report a normal
+    // install.
+    const fakeSdk = mkdtempSync(join(tmpdir(), "maestro-vendor-sdk-"));
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const packs = ["alpha", "beta"].map((id) => {
+        const dir = join(fakeSdk, "plugins", "maestro-skills", "vendor", id);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "SKILL.md"), `---\nname: shared-skill\n---\nfrom ${id}\n`);
+        return { id, repo: `example/${id}`, sha: "0".repeat(40), license: "MIT", skillRoots: ["."] };
+      });
+      const r = planVendorSkills({ sdkRoot: fakeSdk, skillsDir, packs });
+      assert.equal(r.skills.length, 1, "only the first claim stands");
+      assert.equal(r.skills[0].pack.id, "alpha");
+      assert.ok(r.errors.some((e) => e.pack === "beta" && /already claimed by pack alpha/.test(e.error)), JSON.stringify(r.errors));
+
+      const inst = installVendorSkills({ sdkRoot: fakeSdk, skillsDir, packs });
+      assert.equal(inst.ok, false, "a collision is an error, not a silent overwrite");
+      assert.match(readFileSync(join(skillsDir, "shared-skill", "SKILL.md"), "utf8"), /from alpha/);
+    } finally { cleanup(); rmSync(fakeSdk, { recursive: true, force: true }); }
+  });
+
+  it("copies a directory aside before overwriting work somebody did in it", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      const dir = join(skillsDir, "impeccable");
+      const tuned = "---\nname: impeccable\n---\ntuned for Cohort\n";
+      writeFileSync(join(dir, "SKILL.md"), tuned);
+      writeFileSync(join(dir, "cohort-notes.md"), "a person's own notes\n");
+
+      const r = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      const b = r.backups.find((x) => x.name === "impeccable");
+      assert.ok(b, `expected a backup, got ${JSON.stringify(r.backups)}`);
+      assert.deepEqual(b.files.sort(), ["SKILL.md", "cohort-notes.md"]);
+      assert.equal(readFileSync(join(b.path, "SKILL.md"), "utf8"), tuned, "their edit survives");
+      assert.equal(readFileSync(join(b.path, "cohort-notes.md"), "utf8"), "a person's own notes\n");
+      // …and the live directory is back to the vendored bytes.
+      assert.match(readFileSync(join(dir, "SKILL.md"), "utf8"), /^---\nname: impeccable/);
+      assert.equal(existsSync(join(dir, "cohort-notes.md")), false);
+    } finally { cleanup(); }
+  });
+
+  it("backs nothing up when it only rewrites files it wrote itself", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      const first = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      assert.deepEqual(first.backups, []);
+      const second = installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS, stamp: "STAMP" });
+      assert.deepEqual(second.backups, [], "an idempotent re-run leaves no backup directories behind");
+      assert.deepEqual(second.installed, []);
+    } finally { cleanup(); }
+  });
+
+  it("puts no hook machinery on the seat", () => {
+    const { skillsDir, cleanup } = throwawayHome();
+    try {
+      installVendorSkills({ sdkRoot: SDK_ROOT, skillsDir, packs: PACKS });
+      const unlazy = join(skillsDir, "unlazy");
+      assert.ok(existsSync(join(unlazy, "scripts", "gate-check.mjs")), "the gate checker is the reason scripts/ is vendored");
+      for (const name of ["install-hooks.mjs", "stop-hook.mjs"]) {
+        assert.equal(existsSync(join(unlazy, "scripts", name)), false,
+          `${name} would be one \`node <path>\` away from a Stop hook in the settings file every session reads`);
+      }
+    } finally { cleanup(); }
+  });
+
+  it("packSize reports a file count and a byte size for every pack", () => {
+    for (const pack of PACKS) {
+      const s = packSize(SDK_ROOT, pack);
+      assert.ok(s.files > 0, `${pack.id} has files`);
+      assert.ok(s.bytes > 0, `${pack.id} has bytes`);
+    }
+  });
+});