Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import {
chmodSync,
existsSync,
mkdtempSync,
mkdirSync,
readdirSync,
readFileSync,
rmSync,
statSync,
writeFileSync,
} from "node:fs";
import { execFile } from "node:child_process";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import {
hashSkillBundle,
buildManifest,
checkSkills,
diffSkills,
FALLBACK_CORE_SKILLS,
isCoreSkill,
MANIFEST_FILE,
presentSkills,
pruneOrphanedLockEntries,
RETIRED_SKILLS,
retiredSkillNotice,
skillsAttributedToSource,
type SkillsManifest,
type SkillEntry,
} from "./skillsManifest.js";
// The retired-skill regression tests below drive `checkSkills`'s real
// `canonical: true` network path (see resolveLatestManifest) instead of an
// explicit local `source` — that's the whole point (it must NOT read a stale
// local repo manifest). Stub the two network boundaries it can reach so those
// tests stay fast and offline: `git ls-remote` (remoteHeadSha) always "fails"
// so it falls back to the branch URL, and `fetch` is stubbed per-test. `vi.mock`
// is hoisted above these imports regardless of source position. No existing
// test in this file omits `source`, so nothing else touches this mock.
vi.mock("node:child_process", () => ({
execFile: vi.fn(
(
_cmd: string,
_args: readonly string[],
_opts: unknown,
callback: (err: Error | null) => void,
) => callback(new Error("no git in tests")),
),
}));
let root: string;
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), "skills-manifest-"));
});
afterEach(() => {
rmSync(root, { recursive: true, force: true });
});
function writeSkill(name: string, files: Record<string, string>): string {
const dir = join(root, name);
for (const [rel, content] of Object.entries(files)) {
const p = join(dir, rel);
mkdirSync(join(p, ".."), { recursive: true });
writeFileSync(p, content);
}
return dir;
}
describe("hashSkillBundle", () => {
it("is deterministic for identical content", () => {
const a = writeSkill("a", { "SKILL.md": "hello", "references/x.md": "x" });
const b = writeSkill("b", { "SKILL.md": "hello", "references/x.md": "x" });
expect(hashSkillBundle(a).hash).toBe(hashSkillBundle(b).hash);
});
it("changes when any file's content changes", () => {
const dir = writeSkill("a", { "SKILL.md": "hello", "references/x.md": "x" });
const before = hashSkillBundle(dir).hash;
writeFileSync(join(dir, "references/x.md"), "CHANGED");
expect(hashSkillBundle(dir).hash).not.toBe(before);
});
it("counts every file in the bundle, not just SKILL.md", () => {
const dir = writeSkill("a", {
"SKILL.md": "hello",
"references/x.md": "x",
"scripts/y.mjs": "export const y = 1;",
});
expect(hashSkillBundle(dir).files).toBe(3);
});
it("ignores Python bytecode a skill script leaves behind, but not a real edit", () => {
const dir = writeSkill("a", {
"SKILL.md": "hello",
"scripts/lib/auth.py": "x = 1\n",
});
const clean = hashSkillBundle(dir);
mkdirSync(join(dir, "scripts/lib/__pycache__"));
writeFileSync(join(dir, "scripts/lib/__pycache__/auth.cpython-312.pyc"), "\x00bytecode");
writeFileSync(join(dir, "scripts/lib/stray.pyc"), "\x00bytecode");
expect(hashSkillBundle(dir)).toEqual(clean);
writeFileSync(join(dir, "scripts/lib/auth.py"), "x = 2\n");
expect(hashSkillBundle(dir).hash).not.toBe(clean.hash);
});
it("ignores dependency installs, OS files, and editor swap files", () => {
const dir = writeSkill("a", { "SKILL.md": "hello", "scripts/run.mjs": "run();" });
const clean = hashSkillBundle(dir);
writeSkill("a", {
"node_modules/dep/index.js": "module.exports = 1;",
"scripts/.DS_Store": "",
"scripts/.run.mjs.swp": "swap",
"SKILL.md~": "backup",
});
expect(hashSkillBundle(dir)).toEqual(clean);
});
it("normalises CRLF so a Windows checkout is not flagged as different", () => {
const lf = writeSkill("lf", { "SKILL.md": "line1\nline2\n" });
const crlf = writeSkill("crlf", { "SKILL.md": "line1\r\nline2\r\n" });
expect(hashSkillBundle(lf).hash).toBe(hashSkillBundle(crlf).hash);
});
});
describe("buildManifest", () => {
it("includes only directories that contain a SKILL.md", () => {
writeSkill("real", { "SKILL.md": "x" });
writeSkill("not-a-skill", { "README.md": "x" });
const m = buildManifest(root, { source: "test" });
expect(Object.keys(m.skills)).toEqual(["real"]);
});
});
describe("isCoreSkill", () => {
it("classifies the entry router, hyperframes-* domain skills, and media-use as core", () => {
expect(isCoreSkill("hyperframes")).toBe(true);
expect(isCoreSkill("hyperframes-cli")).toBe(true);
expect(isCoreSkill("hyperframes-registry")).toBe(true);
expect(isCoreSkill("media-use")).toBe(true);
// Decks, ports and optional integrations install on demand.
expect(isCoreSkill("slideshow")).toBe(false);
expect(isCoreSkill("remotion-to-hyperframes")).toBe(false);
expect(isCoreSkill("figma")).toBe(false);
});
});
describe("FALLBACK_CORE_SKILLS pin", () => {
// The fallback list exists because isCoreSkill is a pattern and the offline
// path can't enumerate a pattern. This pins the list to the repo's actual
// skills/ tree so it can't drift silently when core membership changes.
it("matches the core skills present in the repo's skills/ tree exactly", () => {
const skillsRoot = join(
dirname(fileURLToPath(import.meta.url)),
"..",
"..",
"..",
"..",
"skills",
);
const onDisk = readdirSync(skillsRoot).filter((n) =>
existsSync(join(skillsRoot, n, "SKILL.md")),
);
const coreOnDisk = onDisk.filter((n) => isCoreSkill(n)).sort();
expect([...FALLBACK_CORE_SKILLS].sort()).toEqual(coreOnDisk);
});
});
describe(".claude-plugin/marketplace.json core-skills pin", () => {
// The marketplace `core-skills` entry's `skills` array drives two surfaces:
// the upstream `skills add` picker groups the listed skills under
// "Core Skills" (everything unlisted falls into "Other"), and Claude Code
// treats the array as that plugin's skill allowlist. That makes it a third
// enumeration of core membership — pin it to isCoreSkill and the skills/
// tree so neither surface can silently drift from the tiers `init` /
// `skills update` actually enforce. It lives on a separate marketplace
// entry (not plugin.json, and not the `hyperframes` entry) precisely so
// the full `hyperframes` plugin keeps auto-discovering all skills.
it("lists exactly the core skills present in the repo's skills/ tree", () => {
const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
const marketplace = JSON.parse(
readFileSync(join(repoRoot, ".claude-plugin", "marketplace.json"), "utf-8"),
) as { plugins?: { name?: string; skills?: string[] }[] };
const entry = marketplace.plugins?.find((p) => p.name === "core-skills");
if (!entry?.skills) {
throw new Error("marketplace.json is missing the core-skills entry's `skills` array");
}
const declared = entry.skills.map((p) => p.replace(/^\.\/skills\//, "")).sort();
const skillsRoot = join(repoRoot, "skills");
const coreOnDisk = readdirSync(skillsRoot)
.filter((n) => existsSync(join(skillsRoot, n, "SKILL.md")))
.filter((n) => isCoreSkill(n))
.sort();
expect(declared).toEqual(coreOnDisk);
// Upstream resolves each entry relative to the repo root — the "./skills/"
// prefix is load-bearing (see vercel-labs/skills plugin-manifest.ts).
for (const p of entry.skills) {
expect(p.startsWith("./skills/")).toBe(true);
}
// The full plugin must NOT carry a skills allowlist: Claude Code would
// narrow it to the listed subset instead of auto-discovering all skills.
const full = marketplace.plugins?.find((p) => p.name === "hyperframes");
expect(full).toBeDefined();
expect(full?.skills).toBeUndefined();
// Same for plugin.json (the direct-install manifest for the full plugin) —
// and upstream lets plugin.json groupings override marketplace ones, so a
// skills array here would also rename the picker group back to
// "Hyperframes".
const plugin = JSON.parse(
readFileSync(join(repoRoot, ".claude-plugin", "plugin.json"), "utf-8"),
) as { skills?: string[] };
expect(plugin.skills).toBeUndefined();
});
});
describe("diffSkills", () => {
const latest: SkillsManifest = {
source: "test",
skills: {
keep: { hash: "h1", files: 1 },
changed: { hash: "h2", files: 1 },
gone: { hash: "h3", files: 1 },
},
};
it("classifies current / outdated / missing and ignores skills not in the manifest", () => {
const installed: Record<string, SkillEntry> = {
keep: { hash: "h1", files: 1 }, // current
changed: { hash: "DIFFERENT", files: 1 }, // outdated
// gone: not installed → missing
extra: { hash: "hx", files: 1 }, // not in the manifest → ignored
};
const diff = diffSkills(installed, latest);
const byName = Object.fromEntries(diff.skills.map((s) => [s.name, s.status]));
expect(byName).toEqual({
keep: "current",
changed: "outdated",
gone: "missing",
});
expect(diff.summary).toEqual({ current: 1, outdated: 1, missing: 1, coreMissing: 0 });
});
it("flags updateAvailable for anything outdated", () => {
const hasOutdated = diffSkills({ changed: { hash: "X", files: 1 } }, latest);
expect(hasOutdated.updateAvailable).toBe(true);
// Everything present and current → no update.
const allCurrent = diffSkills(
{
keep: { hash: "h1", files: 1 },
changed: { hash: "h2", files: 1 },
gone: { hash: "h3", files: 1 },
},
latest,
);
expect(allCurrent.updateAvailable).toBe(false);
// A skill installed but not in the manifest is ignored — doesn't trigger one.
const withExtra = diffSkills(
{
keep: { hash: "h1", files: 1 },
changed: { hash: "h2", files: 1 },
gone: { hash: "h3", files: 1 },
extra: { hash: "hx", files: 1 },
},
latest,
);
expect(withExtra.updateAvailable).toBe(false);
});
it("a missing on-demand skill is NOT an update — a missing core skill is", () => {
// The old semantics ("full set is the goal") made any missing skill flip
// updateAvailable, which re-pulled all skills onto deliberate partial
// installs. On-demand skills now install when their workflow triggers.
const withCore: SkillsManifest = {
source: "test",
skills: {
hyperframes: { hash: "e1", files: 1 }, // core: entry router
slideshow: { hash: "w1", files: 1 }, // on-demand workflow
},
};
// Core current, workflow missing → partial install is fine, no update.
const workflowMissing = diffSkills({ hyperframes: { hash: "e1", files: 1 } }, withCore);
expect(workflowMissing.updateAvailable).toBe(false);
expect(workflowMissing.summary).toEqual({
current: 1,
outdated: 0,
missing: 1,
coreMissing: 0,
});
// Core itself missing → every workflow needs it, so that IS an update.
const coreMissing = diffSkills({ slideshow: { hash: "w1", files: 1 } }, withCore);
expect(coreMissing.updateAvailable).toBe(true);
expect(coreMissing.summary).toEqual({ current: 1, outdated: 0, missing: 1, coreMissing: 1 });
});
});
describe("presentSkills", () => {
it("returns only the names present in the located install", () => {
const home = join(root, "home");
const project = join(root, "project");
mkdirSync(project, { recursive: true });
const skillsDir = join(home, ".claude/skills");
mkdirSync(join(skillsDir, "hyperframes"), { recursive: true });
writeFileSync(join(skillsDir, "hyperframes", "SKILL.md"), "# hyperframes");
expect(presentSkills(["hyperframes", "slideshow"], { cwd: project, home })).toEqual([
"hyperframes",
]);
});
it("returns [] when no install exists at all", () => {
const home = join(root, "home");
const project = join(root, "project");
mkdirSync(home, { recursive: true });
mkdirSync(project, { recursive: true });
expect(presentSkills(["hyperframes"], { cwd: project, home })).toEqual([]);
});
});
describe("checkSkills install detection", () => {
// A spread of agent-host conventions across the upstream `skills` universe,
// including the XDG-nested OpenCode layout. Detection is structural
// (auto-discovered), so this list is illustrative, not exhaustive.
const CASES: ReadonlyArray<[string, string]> = [
[".claude/skills", "claude-code"],
[".agents/skills", "agents"],
[".codex/skills", "codex"],
[".cursor/skills", "cursor"],
[".config/opencode/skills", "opencode"],
[".factory/skills", "factory"],
[".slate/skills", "slate"],
[".kiro/skills", "kiro"],
[".hermes/skills", "hermes"],
[".gbrain/skills", "gbrain"],
[".openclaw/skills", "openclaw"],
];
function writeManifest(dir: string): string {
const p = join(dir, "manifest.json");
writeFileSync(
p,
JSON.stringify({
source: "test",
skills: { alpha: { hash: "x", files: 1 }, beta: { hash: "y", files: 1 } },
}),
);
return p;
}
function installSkill(skillsDir: string, name: string): void {
mkdirSync(join(skillsDir, name), { recursive: true });
writeFileSync(join(skillsDir, name, "SKILL.md"), `# ${name}`);
}
it.each(CASES)("locates skills under %s in the project scope", async (rel, agent) => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
const source = writeManifest(root);
installSkill(join(project, rel), "alpha");
const res = await checkSkills({ source, cwd: project, home });
expect(res.location).toBe(join(project, rel));
expect(res.agent).toBe(agent);
});
it.each(CASES)("locates skills under %s in the global scope", async (rel, agent) => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
const source = writeManifest(root);
installSkill(join(home, rel), "alpha");
const res = await checkSkills({ source, cwd: project, home });
expect(res.location).toBe(join(home, rel));
expect(res.agent).toBe(agent);
});
it("prefers global scope over project (matches how agents load skills)", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
const source = writeManifest(root);
installSkill(join(home, ".claude/skills"), "alpha"); // global — what the agent actually loads
installSkill(join(project, ".hermes/skills"), "alpha"); // project — overridden by the global copy
// Claude Code (and most agents) give the personal/global scope priority over
// the project scope, and HyperFrames installs globally — so check reports on
// the global copy the agent will really use, not a stale project copy.
const res = await checkSkills({ source, cwd: project, home });
expect(res.location).toBe(join(home, ".claude/skills"));
expect(res.agent).toBe("claude-code");
});
it("reports no location and an available update when nothing is installed", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
// A manifest with a core skill: a truly fresh machine is missing the core
// set, and THAT (not the missing on-demand skills) makes the update
// available.
const source = join(root, "manifest-core.json");
writeFileSync(
source,
JSON.stringify({
source: "test",
skills: { hyperframes: { hash: "x", files: 1 }, alpha: { hash: "y", files: 1 } },
}),
);
const res = await checkSkills({ source, cwd: project, home });
expect(res.location).toBeNull();
expect(res.summary.missing).toBe(2);
expect(res.summary.coreMissing).toBe(1);
expect(res.updateAvailable).toBe(true);
});
it("honors the --dir override and infers the agent from the path", async () => {
const dir = join(root, "home", ".kiro/skills");
installSkill(dir, "alpha");
const source = writeManifest(root);
const res = await checkSkills({ source, dir });
expect(res.location).toBe(dir);
expect(res.agent).toBe("kiro");
});
it("auto-discovers an unknown/new agent host (no closed list)", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
const source = writeManifest(root);
// A host this CLI has never heard of — structural discovery still finds it.
installSkill(join(home, ".some-future-agent/skills"), "alpha");
const res = await checkSkills({ source, cwd: project, home });
expect(res.location).toBe(join(home, ".some-future-agent/skills"));
expect(res.agent).toBe("some-future-agent");
});
it("prefers claude-code when multiple hosts in the same scope have skills", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
const source = writeManifest(root);
installSkill(join(home, ".factory/skills"), "alpha");
installSkill(join(home, ".claude/skills"), "alpha");
const res = await checkSkills({ source, cwd: project, home });
expect(res.location).toBe(join(home, ".claude/skills"));
expect(res.agent).toBe("claude-code");
});
});
describe("skillsAttributedToSource", () => {
it("matches by slug or git clone URL and ignores other sources", () => {
const lock = {
skills: {
a: { source: "heygen-com/hyperframes" },
b: { sourceUrl: "https://github.com/heygen-com/hyperframes.git" },
c: { source: "https://github.com/heygen-com/hyperframes" },
d: { source: "greensock/gsap-skills" },
},
};
expect(skillsAttributedToSource(lock, "heygen-com/hyperframes").sort()).toEqual([
"a",
"b",
"c",
]);
});
it("returns [] for a null/empty lock or empty source", () => {
expect(skillsAttributedToSource(null, "x")).toEqual([]);
expect(skillsAttributedToSource({}, "x")).toEqual([]);
expect(skillsAttributedToSource({ skills: { a: { source: "x" } } }, "")).toEqual([]);
});
});
describe("checkSkills removed-upstream detection", () => {
// The global lock path honours XDG_STATE_HOME; clear it so the fixture under
// <home>/.agents/.skill-lock.json is the one that's read.
let xdg: string | undefined;
beforeEach(() => {
xdg = process.env.XDG_STATE_HOME;
delete process.env.XDG_STATE_HOME;
});
afterEach(() => {
if (xdg === undefined) delete process.env.XDG_STATE_HOME;
else process.env.XDG_STATE_HOME = xdg;
});
// Install one or more `<skillsDir>/<name>/SKILL.md` bundles.
function installSkills(skillsDir: string, names: string[]): void {
for (const name of names) {
mkdirSync(join(skillsDir, name), { recursive: true });
writeFileSync(join(skillsDir, name, "SKILL.md"), `# ${name}`);
}
}
// Shared fixture: a project + home with two skills installed globally
// (alpha + gamma), plus a manifest path. Tests then write the lock they need.
function setup(manifest: SkillsManifest): {
home: string;
opts: { source: string; cwd: string; home: string };
} {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
installSkills(join(home, ".agents/skills"), ["alpha", "gamma"]);
const manifestPath = join(root, "manifest.json");
writeFileSync(manifestPath, JSON.stringify(manifest));
return { home, opts: { source: manifestPath, cwd: project, home } };
}
// Upstream writes a `skillPath` on every lock entry it creates (verified
// against a real ~/.agents/.skill-lock.json written by [email protected]), and
// removed-detection now reads it to tell manifest-covered skills apart from
// ones installed out of the repo's other skill roots — see
// manifestCoversSkill / GH #3111. Default to the covered root so each existing
// fixture keeps meaning "a normally published skill"; pass skillPath
// explicitly to model anything else.
function writeGlobalLock(
home: string,
skills: Record<string, { source: string; skillPath?: string }>,
): void {
const withPaths = Object.fromEntries(
Object.entries(skills).map(([name, entry]) => [
name,
{ skillPath: `skills/${name}/SKILL.md`, ...entry },
]),
);
writeFileSync(
join(home, ".agents/.skill-lock.json"),
JSON.stringify({ version: 3, skills: withPaths }),
);
}
it("flags a lock-attributed skill the manifest dropped, ignoring other sources", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
writeGlobalLock(home, {
alpha: { source: "test" }, // still ours and in the manifest
gamma: { source: "test" }, // ours, dropped from manifest → removed
delta: { source: "someone/else" }, // a different source → never ours
});
const res = await checkSkills(opts);
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
expect(byName.gamma).toBe("removed");
expect(byName.delta).toBeUndefined();
expect(res.summary.removed).toBe(1);
});
// GH #3111 — the data-loss regression. `skills add --skill '*'` installs every
// skill in the repo, including the repo-native ones under `.claude/skills/`
// and `.agents/skills/`, and attributes them all to our source. The published
// manifest is generated from `<repoRoot>/skills` ONLY (gen-skills-manifest.ts),
// so it never lists them — and reading that silence as "no longer published"
// deleted them from every agent directory on the machine, immediately after
// the same command installed them.
//
// Reproduced end-to-end pre-fix against the real CLI: `skills add` installed
// 25 skills, then `skills update` printed "Removing 6 skill(s) no longer
// published: captions-overlay, changelog-video, cut-the-curve, motion-doctrine,
// oversized-cursor, seam-craft" and deleted all six. Their lock entries carried
// `.agents/skills/<name>/SKILL.md`; the survivors carried `skills/<name>/…`.
it("never prunes a skill installed outside the manifest's coverage root", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
writeGlobalLock(home, {
alpha: { source: "test" }, // published, in the manifest → untouched
gamma: {
source: "test", // ours, absent from the manifest…
skillPath: ".agents/skills/gamma/SKILL.md", // …but the manifest never covered it
},
});
const res = await checkSkills(opts);
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
expect(byName.gamma).not.toBe("removed");
expect(res.summary.removed).toBe(0);
});
// The other half of the contract: the coverage filter must not blunt the
// retired-skill convergence #2176 added. A skill installed FROM `skills/` and
// since dropped from the manifest is still a real removal.
it("still prunes a manifest-covered skill that was genuinely dropped upstream", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
writeGlobalLock(home, {
alpha: { source: "test" },
gamma: { source: "test", skillPath: "skills/gamma/SKILL.md" },
});
const res = await checkSkills(opts);
expect(Object.fromEntries(res.skills.map((s) => [s.name, s.status])).gamma).toBe("removed");
expect(res.summary.removed).toBe(1);
});
// Fail safe on unknown provenance: an entry written by an older upstream that
// recorded no skillPath cannot be shown to be manifest-covered, and this is a
// DELETE path — so it is left alone rather than guessed at.
it("leaves an entry with no skillPath alone rather than guessing", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
writeFileSync(
join(home, ".agents/.skill-lock.json"),
JSON.stringify({
version: 3,
skills: { alpha: { source: "test" }, gamma: { source: "test" } }, // no skillPath at all
}),
);
const res = await checkSkills(opts);
expect(res.summary.removed).toBe(0);
});
// Retired skills (folded into guide folders of a remaining skill) are ours by
// name, so they are removed even where the generic rule fails safe: a lock
// entry with no skillPath, or a bundle on disk with no lock entry at all.
describe("retired skills", () => {
const retired = "hyperframes-core";
it("is one of RETIRED_SKILLS and absent from the skills/ tree", () => {
expect(RETIRED_SKILLS).toContain(retired);
const skillsRoot = join(dirname(fileURLToPath(import.meta.url)), "../../../../skills");
for (const name of RETIRED_SKILLS) expect(existsSync(join(skillsRoot, name))).toBe(false);
});
it("flags a retired skill whose lock entry has no skillPath", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
writeFileSync(
join(home, ".agents/.skill-lock.json"),
JSON.stringify({
version: 3,
skills: { alpha: { source: "test" }, [retired]: { source: "test" } },
}),
);
const res = await checkSkills(opts);
expect(res.skills.filter((s) => s.status === "removed").map((s) => s.name)).toEqual([
retired,
]);
});
it("flags a retired bundle on disk that no lock attributes", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
installSkills(join(home, ".agents/skills"), [retired]);
const res = await checkSkills(opts);
expect(res.skills.filter((s) => s.status === "removed").map((s) => s.name)).toEqual([
retired,
]);
expect(res.updateAvailable).toBe(true);
});
it("lists the eight retired workflow skills", () => {
for (const name of [
"embedded-captions",
"faceless-explainer",
"general-video",
"motion-graphics",
"music-to-video",
"pr-to-video",
"product-launch-video",
"talking-head-recut",
])
expect(RETIRED_SKILLS).toContain(name);
});
it("flags a retired workflow the lock attributes to us, even without a skillPath", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
installSkills(join(home, ".agents/skills"), ["general-video"]);
writeGlobalLock(home, { alpha: { source: "test" }, "general-video": { source: "test" } });
const res = await checkSkills(opts);
expect(res.skills.filter((s) => s.status === "removed").map((s) => s.name)).toEqual([
"general-video",
]);
});
it("leaves a same-named workflow bundle alone when no lock attributes it to us", async () => {
// Workflow names are generic: another source's `motion-graphics` must survive.
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
installSkills(join(home, ".agents/skills"), ["motion-graphics"]);
const res = await checkSkills(opts);
expect(res.summary.removed).toBe(0);
});
it("explains where a retired skill's knowledge lives", () => {
expect(retiredSkillNotice("pr-to-video")).toMatch(/\/hyperframes skill and its references/);
expect(retiredSkillNotice("hyperframes-audio")).toMatch(/\/media-use skill/);
});
it("leaves a retired name alone while the manifest still publishes it", async () => {
const { home, opts } = setup({
source: "test",
skills: { alpha: { hash: "x", files: 1 }, [retired]: { hash: "y", files: 1 } },
});
installSkills(join(home, ".agents/skills"), [retired]);
writeGlobalLock(home, { alpha: { source: "test" }, [retired]: { source: "test" } });
const res = await checkSkills(opts);
expect(res.summary.removed).toBe(0);
});
});
it("a removed skill alone makes an update available (no outdated/missing)", async () => {
// Manifest lists only alpha, with its REAL hash → "current" (not outdated).
const { home, opts } = setup({ source: "test", skills: {} });
const manifest: SkillsManifest = {
source: "test",
skills: { alpha: hashSkillBundle(join(home, ".agents/skills/alpha")) },
};
writeFileSync(opts.source, JSON.stringify(manifest));
writeGlobalLock(home, { alpha: { source: "test" }, gamma: { source: "test" } });
const res = await checkSkills(opts);
expect(res.summary).toEqual({
current: 1,
outdated: 0,
missing: 0,
coreMissing: 0,
removed: 1,
});
expect(res.updateAvailable).toBe(true);
});
it("reports no removed skills when there is no lock to attribute from", async () => {
const { opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
// gamma is an orphan on disk, but with no lock we can't attribute it to us.
const res = await checkSkills(opts);
expect(res.summary.removed).toBe(0);
expect(res.skills.some((s) => s.status === "removed")).toBe(false);
// No install was located via auto-detect (skills live under <home>/.agents/skills
// which IS discovered) — so lockMissing reflects the genuinely-absent lock.
expect(res.lockMissing).toBe(true);
});
// A `--dir` pointing at a global-scoped install (under $HOME) must resolve the
// GLOBAL lock (<home>/.agents/.skill-lock.json), not the project lock
// (<cwd>/skills-lock.json). Before this fix, locateInstall hardcoded scope
// "project" for every --dir, so the global lock was never read and
// removed-detection silently found nothing for --dir installs.
it("--dir under $HOME resolves the global lock so removed-detection works", async () => {
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
writeGlobalLock(home, {
alpha: { source: "test" }, // ours and still in the manifest
gamma: { source: "test" }, // ours, dropped from manifest → removed
});
const dir = join(home, ".agents/skills");
const res = await checkSkills({ source: opts.source, dir, cwd: opts.cwd, home });
expect(res.scope).toBe("global");
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
expect(byName.gamma).toBe("removed");
expect(res.summary.removed).toBe(1);
expect(res.lockMissing).toBe(false);
});
// Regression (Magi REQUEST_CHANGES at 88daa820): the common project-local case
// is *also* under $HOME — a project checkout at `<home>/work/proj` with skills
// at `<cwd>/.claude/skills`. A HOME-first heuristic misclassified this as
// global, so checkSkills read the global lock and `skills update` would prune
// with `-g` against a project install. CWD-containment must win: `--dir` under
// `cwd` resolves to PROJECT even when `cwd` itself is nested under $HOME.
it("--dir under a cwd that is itself nested under $HOME stays project-scoped", async () => {
const home = join(root, "home");
const project = join(home, "work", "proj"); // cwd nested INSIDE home
const skillsDir = join(project, ".claude/skills");
installSkills(skillsDir, ["alpha", "gamma"]);
const manifestPath = join(root, "m3.json");
writeFileSync(
manifestPath,
JSON.stringify({ source: "test", skills: { alpha: { hash: "x", files: 1 } } }),
);
// Project lock at <cwd>/skills-lock.json — only read if scope is "project".
// No global lock exists under $HOME, so a wrong-scope ("global") read would
// find no lock → zero removed (gamma would NOT be flagged). The project lock
// being read (gamma → removed) is the proof CWD-containment won.
writeFileSync(
join(project, "skills-lock.json"),
JSON.stringify({
version: 1,
skills: {
alpha: { source: "test", skillPath: "skills/alpha/SKILL.md" },
gamma: { source: "test", skillPath: "skills/gamma/SKILL.md" },
},
}),
);
const res = await checkSkills({ source: manifestPath, dir: skillsDir, cwd: project, home });
expect(res.scope).toBe("project");
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
expect(byName.gamma).toBe("removed");
expect(res.summary.removed).toBe(1);
});
// The complementary case: a `--dir` under the project tree (not $HOME) stays
// project-scoped and reads <cwd>/skills-lock.json.
it("--dir outside $HOME stays project-scoped and reads the project lock", async () => {
const project = join(root, "proj2");
const skillsDir = join(project, ".claude/skills");
installSkills(skillsDir, ["alpha", "gamma"]);
const manifestPath = join(root, "m2.json");
writeFileSync(
manifestPath,
JSON.stringify({ source: "test", skills: { alpha: { hash: "x", files: 1 } } }),
);
// Project lock lives at <cwd>/skills-lock.json — point cwd at the project.
writeFileSync(
join(project, "skills-lock.json"),
JSON.stringify({
version: 1,
skills: {
alpha: { source: "test", skillPath: "skills/alpha/SKILL.md" },
gamma: { source: "test", skillPath: "skills/gamma/SKILL.md" },
},
}),
);
const home = join(root, "home2");
mkdirSync(home, { recursive: true });
const res = await checkSkills({ source: manifestPath, dir: skillsDir, cwd: project, home });
expect(res.scope).toBe("project");
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
expect(byName.gamma).toBe("removed");
expect(res.summary.removed).toBe(1);
});
});
// Regression coverage for "variant 1" of the retired-skill bug: `updateSkills`
// (see commands/skills.ts) resolves its own targeted-install check with
// `canonical: true` specifically so it never trusts a stale local
// `skills-manifest.json` — this is the mechanism that makes that safe.
describe("checkSkills canonical bypass of the in-repo manifest shortcut", () => {
afterEach(() => {
vi.unstubAllGlobals();
});
function stubFetchedManifest(manifest: SkillsManifest): void {
vi.stubGlobal(
"fetch",
vi.fn(async () => ({ ok: true, json: async () => manifest }) as unknown as Response),
);
}
it("without canonical, a stale in-repo manifest wins (documented dev/CI shortcut)", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
// A checked-out repo's own manifest, stale: it still lists a skill that
// has since been retired from the canonical published repo.
writeFileSync(
join(project, MANIFEST_FILE),
JSON.stringify({
source: "heygen-com/hyperframes",
skills: { "retired-skill": { hash: "x", files: 1 } },
}),
);
const res = await checkSkills({ cwd: project, home });
expect(res.skills.map((s) => s.name)).toContain("retired-skill");
});
it("with canonical:true, the same stale in-repo manifest is ignored — the fetched manifest wins", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
writeFileSync(
join(project, MANIFEST_FILE),
JSON.stringify({
source: "heygen-com/hyperframes",
skills: { "retired-skill": { hash: "x", files: 1 }, kept: { hash: "y", files: 1 } },
}),
);
// The canonical (fetched) manifest no longer ships `retired-skill`.
stubFetchedManifest({
source: "heygen-com/hyperframes",
skills: { kept: { hash: "y", files: 1 } },
});
const res = await checkSkills({ cwd: project, home, canonical: true });
expect(res.skills.map((s) => s.name)).not.toContain("retired-skill");
expect(res.skills.map((s) => s.name)).toContain("kept");
// The background check runs this with no console; git must not open one on Windows.
expect(vi.mocked(execFile)).toHaveBeenCalledWith(
"git",
expect.arrayContaining(["ls-remote"]),
expect.objectContaining({ windowsHide: true }),
expect.any(Function),
);
});
it("canonical:true still honors an explicit local `source` override", async () => {
const project = join(root, "project");
const home = join(root, "home");
mkdirSync(project, { recursive: true });
mkdirSync(home, { recursive: true });
writeFileSync(
join(project, MANIFEST_FILE),
JSON.stringify({ source: "test", skills: { "from-repo-shortcut": { hash: "x", files: 1 } } }),
);
const explicitSource = join(root, "explicit-manifest.json");
writeFileSync(
explicitSource,
JSON.stringify({
source: "test",
skills: { "from-explicit-source": { hash: "y", files: 1 } },
}),
);
// An explicit `source` is a deliberate caller choice — canonical must not
// override it, only the silent in-repo shortcut.
const res = await checkSkills({ source: explicitSource, cwd: project, home, canonical: true });
expect(res.skills.map((s) => s.name)).toEqual(["from-explicit-source"]);
});
});
describe("pruneOrphanedLockEntries", () => {
function writeLock(path: string, skills: Record<string, { source: string }>): void {
writeFileSync(path, JSON.stringify({ version: 1, skills, dismissed: [] }));
}
it("removes only the given names, leaving other entries and lock fields intact", () => {
const home = join(root, "home");
mkdirSync(join(home, ".agents"), { recursive: true });
const lockPath = join(home, ".agents", ".skill-lock.json");
writeLock(lockPath, {
a: { source: "heygen-com/hyperframes" },
b: { source: "heygen-com/hyperframes" },
c: { source: "heygen-com/hyperframes" },
});
const pruned = pruneOrphanedLockEntries(["a", "b"], "global", { home });
expect(pruned.sort()).toEqual(["a", "b"]);
const rewritten = JSON.parse(readFileSync(lockPath, "utf8"));
expect(Object.keys(rewritten.skills)).toEqual(["c"]);
expect(rewritten.version).toBe(1); // other lock fields survive the rewrite
});
it("is idempotent — a second call with the same names finds nothing left and no-ops", () => {
const home = join(root, "home");
mkdirSync(join(home, ".agents"), { recursive: true });
const lockPath = join(home, ".agents", ".skill-lock.json");
writeLock(lockPath, { a: { source: "heygen-com/hyperframes" } });
const first = pruneOrphanedLockEntries(["a"], "global", { home });
expect(first).toEqual(["a"]);
const before = readFileSync(lockPath, "utf8");
const second = pruneOrphanedLockEntries(["a"], "global", { home });
expect(second).toEqual([]);
// No entries left to touch → the file is never rewritten a second time.
expect(readFileSync(lockPath, "utf8")).toBe(before);
});
it("writes atomically with no trailing newline, no leftover temp file, and preserves the file mode", () => {
const home = join(root, "home-atomic");
mkdirSync(join(home, ".agents"), { recursive: true });
const lockPath = join(home, ".agents", ".skill-lock.json");
writeLock(lockPath, {
a: { source: "heygen-com/hyperframes" },
b: { source: "heygen-com/hyperframes" },
});
chmodSync(lockPath, 0o640);
const pruned = pruneOrphanedLockEntries(["a"], "global", { home });
expect(pruned).toEqual(["a"]);
const raw = readFileSync(lockPath, "utf8");
expect(raw.endsWith("\n")).toBe(false);
expect(JSON.parse(raw).skills).toEqual({ b: { source: "heygen-com/hyperframes" } });
// No `.tmp` sibling left behind by the temp-file + rename.
expect(readdirSync(join(home, ".agents"))).toEqual([".skill-lock.json"]);
// Original permissions survive the rewrite (POSIX only — Windows's fs
// layer reports 0o666 regardless of the mode we set, so the bits aren't
// meaningful there).
if (process.platform !== "win32") {
expect(statSync(lockPath).mode & 0o777).toBe(0o640);
}
});
it("no-ops without throwing when the lock file doesn't exist", () => {
const home = join(root, "home-without-lock");
mkdirSync(home, { recursive: true });
expect(pruneOrphanedLockEntries(["a"], "global", { home })).toEqual([]);
});
it("resolves the project lock at <cwd>/skills-lock.json for scope: project", () => {
const project = join(root, "project");
mkdirSync(project, { recursive: true });
writeLock(join(project, "skills-lock.json"), {
a: { source: "heygen-com/hyperframes" },
b: { source: "heygen-com/hyperframes" },
});
const pruned = pruneOrphanedLockEntries(["a"], "project", { cwd: project });
expect(pruned).toEqual(["a"]);
const rewritten = JSON.parse(readFileSync(join(project, "skills-lock.json"), "utf8"));
expect(Object.keys(rewritten.skills)).toEqual(["b"]);
});
});