Skip to content

Commit 88daa82

Browse files
jrusso1020claude
andcommitted
fix(cli): close skills removed-detection power-user gaps (follow-up to heygen-com#1740)
Address power-user follow-ups deferred from heygen-com#1740 (skills removed-detection): - `--dir` installs now run removed-detection. `locateInstall` hardcoded scope "project" for every `--dir`, so a `--dir ~/.claude/skills` (a global install) read a non-existent `<cwd>/skills-lock.json` and found zero removed skills. New `scopeForDir` infers global vs project from whether the dir is under $HOME, so the right lock is read. - Pin the upstream lock paths to vercel-labs/[email protected] (verified against src/skill-lock.ts + src/local-lock.ts) and warn loudly when the lock is absent where expected, so removed-detection no longer silently no-ops if upstream moves the lock. checkSkills returns lockMissing; --json surfaces it. - skills update gains --source/--dir (parity with check), plumbed into its internal prune checkSkills() so the prune respects the same overrides. - Add the missing test for the all-rejected-names early-return in runSkillsRemove (no skills remove spawned when every candidate name is rejected), plus tests for the --dir scope inference and update flag parity. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent c9e8dd3 commit 88daa82

4 files changed

Lines changed: 204 additions & 19 deletions

File tree

‎packages/cli/src/commands/skills.test.ts‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,11 +64,11 @@ function setPlatform(platform: NodeJS.Platform): void {
6464
}
6565

6666
/** Invoke the `skills update` subcommand from a freshly-imported module. */
67-
async function runSkillsUpdate(): Promise<void> {
67+
async function runSkillsUpdate(args: Record<string, unknown> = {}): Promise<void> {
6868
const { default: skillsCmd } = await import("./skills.js");
6969
const subs = skillsCmd.subCommands as unknown as Record<string, typeof skillsCmd>;
7070
expect(subs.update).toBeDefined();
71-
await subs.update!.run?.({ args: {}, rawArgs: [], cmd: subs.update } as never);
71+
await subs.update!.run?.({ args, rawArgs: [], cmd: subs.update } as never);
7272
}
7373

7474
describe("hyperframes skills", () => {
@@ -213,6 +213,19 @@ describe("hyperframes skills", () => {
213213
expect(state.spawnCalls.some((s) => s.args.includes("remove"))).toBe(false);
214214
});
215215

216+
// `update`'s prune runs the same removed-detection as `check`, so its
217+
// --source/--dir must reach the internal checkSkills() — otherwise the prune
218+
// reconciles against defaults even when the user pointed elsewhere.
219+
it("skills update plumbs --source/--dir to its prune detection (parity with check)", async () => {
220+
setPlatform("linux");
221+
const { checkSkills } = await import("../utils/skillsManifest.js");
222+
vi.mocked(checkSkills).mockResolvedValueOnce({ scope: "project", skills: [] } as never);
223+
224+
await runSkillsUpdate({ source: "owner/repo", dir: "/custom/skills" });
225+
226+
expect(checkSkills).toHaveBeenCalledWith({ source: "owner/repo", dir: "/custom/skills" });
227+
});
228+
216229
// Skill names come from lock-file JSON keys; a flag-like / shell-special name
217230
// must never reach the spawn (esp. the Windows cmd.exe path).
218231
it("skills update never passes a non-slug skill name to remove", async () => {
@@ -233,4 +246,29 @@ describe("hyperframes skills", () => {
233246
expect(removeCall!.args).toContain("graphic-overlays");
234247
expect(removeCall!.args).not.toContain("--config=evil.js");
235248
});
249+
250+
// The early-return guard in runSkillsRemove: when EVERY candidate name is
251+
// rejected as non-slug, no `skills remove` is spawned at all (the prior test
252+
// only covers a mix of valid + invalid). A spawn here would run `skills remove
253+
// --yes` with no names — which the upstream CLI treats as "remove nothing" at
254+
// best, or prompts interactively at worst — so we must not reach it.
255+
it("skills update spawns no remove when every removed name is rejected", async () => {
256+
setPlatform("linux");
257+
const { checkSkills } = await import("../utils/skillsManifest.js");
258+
vi.mocked(checkSkills).mockResolvedValueOnce({
259+
scope: "global",
260+
skills: [
261+
{ name: "--config=evil.js", status: "removed" },
262+
{ name: "../escape", status: "removed" },
263+
],
264+
} as never);
265+
266+
await runSkillsUpdate();
267+
268+
expect(state.spawnCalls.some((s) => s.args.includes("remove"))).toBe(false);
269+
// The install still ran and the update still succeeded — a cleanup no-op
270+
// doesn't fail the update.
271+
expect(state.spawnCalls[0]?.args).toContain("add");
272+
expect(process.exitCode).toBe(0);
273+
});
236274
});

‎packages/cli/src/commands/skills.ts‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,12 @@ import * as clack from "@clack/prompts";
44
import { c } from "../ui/colors.js";
55
import { buildNpxCommand } from "../utils/npxCommand.js";
66
import { withMeta } from "../utils/updateCheck.js";
7-
import { checkSkills, type SkillDiff, type SkillsCheckResult } from "../utils/skillsManifest.js";
7+
import {
8+
checkSkills,
9+
SKILLS_CLI_LOCK_PATHS_VERIFIED_AT,
10+
type SkillDiff,
11+
type SkillsCheckResult,
12+
} from "../utils/skillsManifest.js";
813
import type { Example } from "./_examples.js";
914

1015
export const examples: Example[] = [
@@ -157,6 +162,19 @@ function renderCheck(result: SkillsCheckResult): void {
157162
c.warn,
158163
);
159164

165+
// Removed-detection cross-references the upstream skills lock. If that lock is
166+
// absent where we expect it (e.g. upstream moved its path), removed-detection
167+
// silently reports zero — so warn rather than imply a clean "up to date".
168+
if (result.lockMissing) {
169+
console.log();
170+
console.log(
171+
` ${c.warn(`! Skills lock not found — can't check for skills removed upstream.`)}`,
172+
);
173+
console.log(
174+
` ${c.dim(` (lock paths verified against ${SKILLS_CLI_LOCK_PATHS_VERIFIED_AT})`)}`,
175+
);
176+
}
177+
160178
console.log();
161179
if (result.updateAvailable) {
162180
console.log(` ${c.accent("Update: npx hyperframes skills update")}`);
@@ -199,12 +217,31 @@ const updateCommand = defineCommand({
199217
description:
200218
"Update all HyperFrames skills to the latest — installs any not yet present, removes any no longer published",
201219
},
202-
args: {},
203-
async run() {
220+
// Mirror `check`'s flags: the prune step runs the same removed-detection, so it
221+
// must respect the same overrides. Without these, `update`'s internal
222+
// checkSkills() fell back to defaults — pruning the auto-detected install
223+
// against the default manifest even when the user pointed `check` elsewhere.
224+
args: {
225+
dir: { type: "string", description: "Skills directory to reconcile (default: auto-detect)" },
226+
source: {
227+
type: "string",
228+
description: "Where 'latest' comes from: local path, owner/repo, or URL",
229+
},
230+
},
231+
async run({ args }) {
232+
const dir = args.dir as string | undefined;
233+
const source = args.source as string | undefined;
234+
204235
// `skills add --all` re-fetches every skill to the latest AND installs ones
205236
// not yet present — so "update" pulls the full set, not just what is already
206237
// installed. This is where `init` and the stale-skills nudge both lead.
207238
//
239+
// Note: the upstream `skills add` CLI has no `--dir` flag (it installs into
240+
// detected agent dirs), so `--dir` here scopes only the *prune* detection
241+
// below, not the install. `--source` likewise drives where the prune's
242+
// "latest" manifest comes from; the install always targets the canonical
243+
// HyperFrames repo so `update` reliably pulls the published set.
244+
//
208245
// strict: this is the documented recovery path for the agent/CI contract
209246
// `hyperframes skills check || hyperframes skills update`. If the install
210247
// fails (no npx, `skills add` exits non-zero) it must exit non-zero too —
@@ -229,7 +266,7 @@ const updateCommand = defineCommand({
229266
// failure doesn't fail the update — the install the CI contract gates on
230267
// already succeeded.
231268
try {
232-
const { skills, scope } = await checkSkills();
269+
const { skills, scope } = await checkSkills({ dir, source });
233270
const removed = skills.filter((s) => s.status === "removed").map((s) => s.name);
234271
if (removed.length) {
235272
console.log();

‎packages/cli/src/utils/skillsManifest.test.ts‎

Lines changed: 62 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,14 @@ describe("checkSkills removed-upstream detection", () => {
294294
else process.env.XDG_STATE_HOME = xdg;
295295
});
296296

297+
// Install one or more `<skillsDir>/<name>/SKILL.md` bundles.
298+
function installSkills(skillsDir: string, names: string[]): void {
299+
for (const name of names) {
300+
mkdirSync(join(skillsDir, name), { recursive: true });
301+
writeFileSync(join(skillsDir, name, "SKILL.md"), `# ${name}`);
302+
}
303+
}
304+
297305
// Shared fixture: a project + home with two skills installed globally
298306
// (alpha + gamma), plus a manifest path. Tests then write the lock they need.
299307
function setup(manifest: SkillsManifest): {
@@ -303,11 +311,7 @@ describe("checkSkills removed-upstream detection", () => {
303311
const project = join(root, "project");
304312
const home = join(root, "home");
305313
mkdirSync(project, { recursive: true });
306-
const skillsDir = join(home, ".agents/skills");
307-
for (const name of ["alpha", "gamma"]) {
308-
mkdirSync(join(skillsDir, name), { recursive: true });
309-
writeFileSync(join(skillsDir, name, "SKILL.md"), `# ${name}`);
310-
}
314+
installSkills(join(home, ".agents/skills"), ["alpha", "gamma"]);
311315
const manifestPath = join(root, "manifest.json");
312316
writeFileSync(manifestPath, JSON.stringify(manifest));
313317
return { home, opts: { source: manifestPath, cwd: project, home } };
@@ -352,5 +356,58 @@ describe("checkSkills removed-upstream detection", () => {
352356
const res = await checkSkills(opts);
353357
expect(res.summary.removed).toBe(0);
354358
expect(res.skills.some((s) => s.status === "removed")).toBe(false);
359+
// No install was located via auto-detect (skills live under <home>/.agents/skills
360+
// which IS discovered) — so lockMissing reflects the genuinely-absent lock.
361+
expect(res.lockMissing).toBe(true);
362+
});
363+
364+
// A `--dir` pointing at a global-scoped install (under $HOME) must resolve the
365+
// GLOBAL lock (<home>/.agents/.skill-lock.json), not the project lock
366+
// (<cwd>/skills-lock.json). Before this fix, locateInstall hardcoded scope
367+
// "project" for every --dir, so the global lock was never read and
368+
// removed-detection silently found nothing for --dir installs.
369+
it("--dir under $HOME resolves the global lock so removed-detection works", async () => {
370+
const { home, opts } = setup({ source: "test", skills: { alpha: { hash: "x", files: 1 } } });
371+
writeGlobalLock(home, {
372+
alpha: { source: "test" }, // ours and still in the manifest
373+
gamma: { source: "test" }, // ours, dropped from manifest → removed
374+
});
375+
376+
const dir = join(home, ".agents/skills");
377+
const res = await checkSkills({ source: opts.source, dir, cwd: opts.cwd, home });
378+
expect(res.scope).toBe("global");
379+
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
380+
expect(byName.gamma).toBe("removed");
381+
expect(res.summary.removed).toBe(1);
382+
expect(res.lockMissing).toBe(false);
383+
});
384+
385+
// The complementary case: a `--dir` under the project tree (not $HOME) stays
386+
// project-scoped and reads <cwd>/skills-lock.json.
387+
it("--dir outside $HOME stays project-scoped and reads the project lock", async () => {
388+
const project = join(root, "proj2");
389+
const skillsDir = join(project, ".claude/skills");
390+
installSkills(skillsDir, ["alpha", "gamma"]);
391+
const manifestPath = join(root, "m2.json");
392+
writeFileSync(
393+
manifestPath,
394+
JSON.stringify({ source: "test", skills: { alpha: { hash: "x", files: 1 } } }),
395+
);
396+
// Project lock lives at <cwd>/skills-lock.json — point cwd at the project.
397+
writeFileSync(
398+
join(project, "skills-lock.json"),
399+
JSON.stringify({
400+
version: 1,
401+
skills: { alpha: { source: "test" }, gamma: { source: "test" } },
402+
}),
403+
);
404+
const home = join(root, "home2");
405+
mkdirSync(home, { recursive: true });
406+
407+
const res = await checkSkills({ source: manifestPath, dir: skillsDir, cwd: project, home });
408+
expect(res.scope).toBe("project");
409+
const byName = Object.fromEntries(res.skills.map((s) => [s.name, s.status]));
410+
expect(byName.gamma).toBe("removed");
411+
expect(res.summary.removed).toBe(1);
355412
});
356413
});

‎packages/cli/src/utils/skillsManifest.ts‎

Lines changed: 61 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import { execFile } from "node:child_process";
1919
import { createHash } from "node:crypto";
2020
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
2121
import { homedir } from "node:os";
22-
import { isAbsolute, join, relative, sep } from "node:path";
22+
import { isAbsolute, join, relative, resolve, sep } from "node:path";
2323
import { promisify } from "node:util";
2424

2525
const execFileAsync = promisify(execFile);
@@ -86,6 +86,13 @@ export interface SkillsCheckResult {
8686
updateAvailable: boolean;
8787
summary: { current: number; outdated: number; missing: number; removed: number };
8888
skills: SkillDiff[];
89+
/**
90+
* True when an install was located but the upstream skills lock was absent at
91+
* the expected path, so removed-detection couldn't run (it silently reports
92+
* zero removed). Lets the CLI warn instead of misreporting "up to date" — a
93+
* guard against the lock path silently no-op'ing if upstream moves it.
94+
*/
95+
lockMissing: boolean;
8996
}
9097

9198
const DEFAULT_REPO_SLUG = "heygen-com/hyperframes";
@@ -212,18 +219,41 @@ function discoverSkillRoots(base: string, scope: "project" | "global"): SkillRoo
212219
});
213220
}
214221

222+
/**
223+
* Decide whether an explicit `--dir` is a project- or global-scoped install, so
224+
* removed-detection reads the *right* lock. The upstream `skills` CLI keeps two
225+
* locks: a project lock at `<cwd>/skills-lock.json` and a global lock under
226+
* `$HOME` (see lockPathForScope). A `--dir` that lives under `$HOME` (e.g.
227+
* `~/.claude/skills`) is a global install; one under the project tree (or
228+
* anywhere else) is treated as project. Without this, `--dir ~/.claude/skills`
229+
* was always scoped "project", so detectRemoved looked for a non-existent
230+
* `<cwd>/skills-lock.json` and silently found zero removed skills.
231+
*/
232+
function scopeForDir(dir: string, home: string): "project" | "global" {
233+
const norm = (p: string): string => {
234+
const r = resolve(p);
235+
return r.endsWith(sep) ? r : r + sep;
236+
};
237+
return norm(dir).startsWith(norm(home)) ? "global" : "project";
238+
}
239+
215240
/**
216241
* Find the first skill root that actually contains HyperFrames skills. A
217-
* `--dir` override (if given) is treated as a `.../skills` directory directly.
218-
* Otherwise scan project (cwd) then global ($HOME), auto-discovering hosts.
242+
* `--dir` override (if given) is treated as a `.../skills` directory directly;
243+
* its scope is inferred (see scopeForDir) so removed-detection reads the right
244+
* lock. Otherwise scan project (cwd) then global ($HOME), auto-discovering hosts.
219245
*/
220246
function locateInstall(
221247
skillNames: string[],
222248
opts: { dir?: string; cwd?: string; home?: string } = {},
223249
): SkillRoot | null {
224250
if (opts.dir) {
225251
return existsSync(opts.dir)
226-
? { dir: opts.dir, agent: agentFromDir(opts.dir), scope: "project" }
252+
? {
253+
dir: opts.dir,
254+
agent: agentFromDir(opts.dir),
255+
scope: scopeForDir(opts.dir, opts.home ?? homedir()),
256+
}
227257
: null;
228258
}
229259
const roots = [
@@ -327,7 +357,19 @@ export function skillsAttributedToSource(lock: SkillLock | null, source: string)
327357
.map(([name]) => name);
328358
}
329359

330-
/** Locate the vercel-labs/skills lock for a scope, mirroring that CLI's paths. */
360+
// Removed-detection reads the vercel-labs/skills lock, whose on-disk paths live
361+
// in *their* repo, not ours — so if upstream moves the lock, our cross-reference
362+
// silently finds nothing and `detectRemoved` no-ops without a peep. Pin the
363+
// upstream version these paths were verified against so a future bump is a
364+
// deliberate, reviewable edit (re-check src/skill-lock.ts `getSkillLockPath`
365+
// and src/local-lock.ts `getLocalLockPath` when bumping):
366+
// - global: $XDG_STATE_HOME/skills/.skill-lock.json else ~/.agents/.skill-lock.json
367+
// - project: <cwd>/skills-lock.json
368+
// https://github.com/vercel-labs/skills/blob/v1.5.13/src/skill-lock.ts (global)
369+
// https://github.com/vercel-labs/skills/blob/v1.5.13/src/local-lock.ts (project)
370+
export const SKILLS_CLI_LOCK_PATHS_VERIFIED_AT = "vercel-labs/[email protected]";
371+
372+
/** Locate the vercel-labs/skills lock for a scope (paths pinned to the version above). */
331373
function lockPathForScope(
332374
scope: "project" | "global",
333375
opts: { cwd?: string; home?: string },
@@ -347,17 +389,24 @@ function readSkillLock(path: string): SkillLock | null {
347389
}
348390
}
349391

392+
interface RemovedResult {
393+
removed: SkillDiff[];
394+
/** The lock was absent at the expected path — removed-detection silently no-ops. */
395+
lockMissing: boolean;
396+
}
397+
350398
/** Skills the lock attributes to our source that the manifest no longer ships. */
351399
function detectRemoved(
352400
root: SkillRoot,
353401
latest: SkillsManifest,
354402
opts: { cwd?: string; home?: string },
355-
): SkillDiff[] {
403+
): RemovedResult {
356404
const lock = readSkillLock(lockPathForScope(root.scope, opts));
357-
return skillsAttributedToSource(lock, latest.source)
405+
const removed = skillsAttributedToSource(lock, latest.source)
358406
.filter((name) => !(name in latest.skills))
359407
.sort()
360408
.map((name) => ({ name, status: "removed" as const }));
409+
return { removed, lockMissing: lock === null };
361410
}
362411

363412
// ── Resolving the "latest" manifest ──────────────────────────────────────────
@@ -487,7 +536,10 @@ export async function checkSkills(
487536
const root = locateInstall(skillNames, { dir: opts.dir, cwd: opts.cwd, home: opts.home });
488537
const installed = root ? hashInstalled(root, skillNames) : {};
489538
const diff = diffSkills(installed, latest);
490-
const removed = root ? detectRemoved(root, latest, { cwd: opts.cwd, home: opts.home }) : [];
539+
const removedResult = root
540+
? detectRemoved(root, latest, { cwd: opts.cwd, home: opts.home })
541+
: { removed: [], lockMissing: false };
542+
const { removed, lockMissing } = removedResult;
491543
return {
492544
location: root?.dir ?? null,
493545
agent: root?.agent ?? null,
@@ -497,5 +549,6 @@ export async function checkSkills(
497549
updateAvailable: diff.updateAvailable || removed.length > 0,
498550
summary: { ...diff.summary, removed: removed.length },
499551
skills: [...diff.skills, ...removed],
552+
lockMissing,
500553
};
501554
}

0 commit comments

Comments
 (0)