Skip to content

Commit ee7ef45

Browse files
fix(cli): invalidate the skills nudge cache after a successful install/update/check
The passive "N skills out of date or missing" nudge reads a 24h config cache that only the background check (on non-skills commands) ever wrote. The skills commands themselves are excluded from the nudge pipeline, so a successful `skills update`/install/check never refreshed or dropped the cached verdict — the pre-install count kept printing on every other command for up to 24h. Reconcile commands now drop the cached verdict (counts + timestamp) so the next command's background check re-runs for real. The offline presence-only path deliberately keeps the cache: that run learned nothing about freshness. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent 10b3351 commit ee7ef45

4 files changed

Lines changed: 191 additions & 3 deletions

File tree

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

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,15 @@ vi.mock("../utils/skillsMirror.js", () => ({
112112
mirrorGlobalSkills: vi.fn(() => ({ source: null, mirrored: [] })),
113113
}));
114114

115+
// The reconcile commands drop the background nudge's cached verdict on
116+
// success (the stale-24h-cache fix). Stub it so these tests never touch the
117+
// dev machine's real ~/.hyperframes config; the invalidation behavior itself
118+
// is unit-tested in skillsUpdateCheck.test.ts.
119+
const invalidateSkillsCache = vi.fn();
120+
vi.mock("../utils/skillsUpdateCheck.js", () => ({
121+
invalidateSkillsCache: (...args: unknown[]) => invalidateSkillsCache(...args),
122+
}));
123+
115124
// The global install command this CLI runs (after `skills add <url>` and the
116125
// per-name `--skill` selection).
117126
const GLOBAL_ARGS_TAIL = [
@@ -133,7 +142,7 @@ function setPlatform(platform: NodeJS.Platform): void {
133142

134143
/** Invoke a `skills <name>` subcommand from a freshly-imported module. */
135144
async function runSkillsSub(
136-
name: "update",
145+
name: "update" | "check",
137146
args: Record<string, unknown> = {},
138147
positionals: string[] = [],
139148
): Promise<void> {
@@ -570,6 +579,65 @@ describe("hyperframes skills", () => {
570579
expect(state.spawnCalls).toHaveLength(0);
571580
expect(process.exitCode).toBe(1);
572581
});
582+
583+
// The stale-24h-cache regression: the skills commands are excluded from the
584+
// background nudge pipeline (cli.ts), so unless they drop the cached verdict
585+
// themselves, a successful install keeps the pre-install "N out of date or
586+
// missing" nag alive on every other command for up to 24h.
587+
describe("nudge-cache invalidation", () => {
588+
it("skills update drops the cached nudge verdict on success", async () => {
589+
setPlatform("linux");
590+
invalidateSkillsCache.mockClear();
591+
592+
await runSkillsUpdate();
593+
594+
expect(process.exitCode).toBe(0);
595+
expect(invalidateSkillsCache).toHaveBeenCalled();
596+
});
597+
598+
it("skills update keeps the cached verdict when the install fails", async () => {
599+
setPlatform("linux");
600+
invalidateSkillsCache.mockClear();
601+
state.spawnExitCode = 1; // `skills add` exits non-zero → strict throw
602+
603+
await runSkillsUpdate();
604+
605+
expect(process.exitCode).toBe(1);
606+
expect(invalidateSkillsCache).not.toHaveBeenCalled();
607+
});
608+
609+
it("skills update keeps the cached verdict on the offline (presence-only) path", async () => {
610+
setPlatform("linux");
611+
invalidateSkillsCache.mockClear();
612+
const { checkSkills } = await import("../utils/skillsManifest.js");
613+
vi.mocked(checkSkills).mockRejectedValue(new Error("offline"));
614+
615+
await runSkillsUpdate();
616+
617+
// Presence-only run never learned anything about freshness — the cached
618+
// verdict is still the best information available.
619+
expect(invalidateSkillsCache).not.toHaveBeenCalled();
620+
});
621+
622+
it("bare `skills` (full install) drops the cached nudge verdict", async () => {
623+
setPlatform("linux");
624+
invalidateSkillsCache.mockClear();
625+
626+
const { default: skillsCmd } = await import("./skills.js");
627+
await skillsCmd.run?.({ args: {}, rawArgs: [], cmd: skillsCmd } as never);
628+
629+
expect(invalidateSkillsCache).toHaveBeenCalled();
630+
});
631+
632+
it("skills check drops the cached verdict — the fresh result supersedes it", async () => {
633+
setPlatform("linux");
634+
invalidateSkillsCache.mockClear();
635+
636+
await runSkillsSub("check", { json: true });
637+
638+
expect(invalidateSkillsCache).toHaveBeenCalled();
639+
});
640+
});
573641
});
574642

575643
// The router contract: `/hyperframes` picks a workflow, then runs

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
type SkillsCheckResult,
1717
} from "../utils/skillsManifest.js";
1818
import { mirrorGlobalSkills } from "../utils/skillsMirror.js";
19+
import { invalidateSkillsCache } from "../utils/skillsUpdateCheck.js";
1920
import { trackSkillsInstallSkipped } from "../telemetry/events.js";
2021
import type { Example } from "./_examples.js";
2122

@@ -368,6 +369,13 @@ export async function updateSkills(
368369
await installSkills(result.installed, { cwd: opts.cwd, strict });
369370
verifyInstalled(result.installed, { strict, cwd: opts.cwd });
370371
}
372+
// The install (or the fresh canonical check confirming everything current)
373+
// supersedes whatever the background nudge cached before it — drop the
374+
// cached verdict so the next command re-checks instead of nagging from the
375+
// pre-install snapshot for up to 24h. Deliberately NOT done on the offline
376+
// (presence-only) path above: that run never learned anything about
377+
// freshness, so the cached verdict is the best information we still have.
378+
invalidateSkillsCache();
371379
return result;
372380
}
373381

@@ -555,6 +563,11 @@ const checkCommand = defineCommand({
555563
if (args.json) console.log(JSON.stringify(withMeta(result), null, 2));
556564
else renderCheck(result);
557565

566+
// This check just displayed a fresh verdict, superseding whatever the
567+
// background nudge cached — invalidate so the next command's nudge agrees
568+
// with what the user was just shown instead of a pre-check snapshot.
569+
invalidateSkillsCache();
570+
558571
// Exit non-zero when installed skills are stale, so agents and CI can gate:
559572
// hyperframes skills check || npx hyperframes skills update
560573
if (result.updateAvailable) process.exitCode = 1;
@@ -748,6 +761,11 @@ export default defineCommand({
748761
// citty runs this parent handler even when a subcommand matches; guard on
749762
// the positional so bare `hyperframes skills` installs, while
750763
// `hyperframes skills check|update` does not also re-install.
751-
if (!args._?.[0]) await installSkills("*");
764+
if (!args._?.[0]) {
765+
await installSkills("*");
766+
// Same as updateSkills: a full install supersedes the background
767+
// nudge's cached pre-install verdict.
768+
invalidateSkillsCache();
769+
}
752770
},
753771
});

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

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ let config: FakeConfig;
1111

1212
vi.mock("../telemetry/config.js", () => ({
1313
readConfig: () => ({ ...config }),
14+
readConfigFresh: () => ({ ...config }),
1415
writeConfig: (next: FakeConfig) => {
1516
config = { ...next };
1617
},
@@ -108,4 +109,71 @@ describe("skillsUpdateCheck", () => {
108109
});
109110
expect(text).toContain("1 HyperFrames skill out of date or missing");
110111
});
112+
113+
// Regression: the stale-24h-cache bug. A successful `skills update`/install
114+
// never wrote the cache, and the skills commands are excluded from the nudge
115+
// pipeline entirely — so the pre-install "20 out of date or missing" verdict
116+
// kept printing on every other command until the TTL expired.
117+
// invalidateSkillsCache() is the fix: reconcile commands drop the cached
118+
// verdict so the next command re-checks for real.
119+
describe("invalidateSkillsCache", () => {
120+
const PRE_INSTALL_CACHE = {
121+
lastSkillsCheck: new Date().toISOString(), // fresh — inside the 24h TTL
122+
skillsUpdateAvailable: true,
123+
skillsOutdatedCount: 12,
124+
skillsMissingCount: 8,
125+
skillsRemovedCount: 0,
126+
};
127+
128+
it("a fresh cache short-circuits the background check with the stale verdict (the bug's precondition)", async () => {
129+
config = { ...PRE_INSTALL_CACHE };
130+
const { checkSkillsForUpdate } = await import("./skillsUpdateCheck.js");
131+
132+
const meta = await checkSkillsForUpdate();
133+
134+
expect(mockCheckSkills).not.toHaveBeenCalled();
135+
expect(meta).toEqual({ updateAvailable: true, outdated: 12, missing: 8, removed: 0 });
136+
});
137+
138+
it("drops the cached verdict so the next background check re-runs for real", async () => {
139+
config = { ...PRE_INSTALL_CACHE };
140+
mockCheckSkills.mockResolvedValue({
141+
location: "/home/user/.claude/skills",
142+
updateAvailable: false,
143+
summary: { current: 20, outdated: 0, missing: 0, coreMissing: 0, removed: 0 },
144+
});
145+
146+
const { checkSkillsForUpdate, invalidateSkillsCache } =
147+
await import("./skillsUpdateCheck.js");
148+
invalidateSkillsCache();
149+
150+
// All five cached fields are gone — timestamp AND counts.
151+
expect(config["lastSkillsCheck"]).toBeUndefined();
152+
expect(config["skillsUpdateAvailable"]).toBeUndefined();
153+
expect(config["skillsOutdatedCount"]).toBeUndefined();
154+
expect(config["skillsMissingCount"]).toBeUndefined();
155+
expect(config["skillsRemovedCount"]).toBeUndefined();
156+
157+
const meta = await checkSkillsForUpdate();
158+
expect(mockCheckSkills).toHaveBeenCalledWith({ canonical: true });
159+
expect(meta).toEqual({ updateAvailable: false, outdated: 0, missing: 0, removed: 0 });
160+
});
161+
162+
it("counts are cleared, not just the timestamp — an offline machine goes quiet instead of resurrecting stale counts", async () => {
163+
config = { ...PRE_INSTALL_CACHE };
164+
mockCheckSkills.mockRejectedValue(new Error("offline"));
165+
166+
const { checkSkillsForUpdate, invalidateSkillsCache, printSkillsUpdateNotice } =
167+
await import("./skillsUpdateCheck.js");
168+
invalidateSkillsCache();
169+
170+
// Refresh fails (offline) → falls back to cached meta, which is now empty.
171+
const meta = await checkSkillsForUpdate();
172+
expect(meta).toEqual({ updateAvailable: false, outdated: 0, missing: 0, removed: 0 });
173+
174+
const writeSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
175+
printSkillsUpdateNotice();
176+
expect(writeSpy).not.toHaveBeenCalled();
177+
});
178+
});
111179
});

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

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
// check on their own, but they DO run render/lint/validate — so we piggyback
77
// the reminder on the commands they already run.
88

9-
import { readConfig, writeConfig } from "../telemetry/config.js";
9+
import { readConfig, readConfigFresh, writeConfig } from "../telemetry/config.js";
1010
import { checkSkills } from "./skillsManifest.js";
1111
import { updateNoticesSuppressed } from "./updateCheck.js";
1212

@@ -66,6 +66,40 @@ async function refreshSkillsCache(): Promise<SkillsUpdateMeta> {
6666
};
6767
}
6868

69+
/**
70+
* Drop the cached verdict (counts + timestamp) so the next command's
71+
* background check re-runs instead of nagging from a pre-reconcile snapshot.
72+
*
73+
* Called after a `skills` install/update/check has reconciled or re-measured
74+
* the install. Those commands are excluded from the nudge pipeline entirely
75+
* (see cli.ts), so nothing else refreshes the cache when they run — without
76+
* this, the last background verdict (taken BEFORE the install) keeps printing
77+
* "N skills out of date or missing" on every other command for up to 24h
78+
* after a successful install/update.
79+
*
80+
* Counts are cleared along with the timestamp — not left behind — so an
81+
* offline machine (where the next refresh fails and falls back to the cached
82+
* meta) goes quiet rather than resurrecting the stale pre-install counts.
83+
*
84+
* Best-effort: a config write failure must never fail the skills command
85+
* that just succeeded.
86+
*/
87+
export function invalidateSkillsCache(): void {
88+
try {
89+
// Fresh read narrows the lost-update window against a concurrently
90+
// running CLI process that wrote other config fields in the meantime.
91+
const config = readConfigFresh();
92+
delete config.lastSkillsCheck;
93+
delete config.skillsUpdateAvailable;
94+
delete config.skillsOutdatedCount;
95+
delete config.skillsMissingCount;
96+
delete config.skillsRemovedCount;
97+
writeConfig(config);
98+
} catch {
99+
// best-effort — never break the command that just reconciled skills
100+
}
101+
}
102+
69103
/**
70104
* Refresh the skills freshness cache if it is older than 24h. Best-effort:
71105
* any failure (offline, no manifest published yet, no skills installed) leaves

0 commit comments

Comments
 (0)