mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
fix(cli): address skills install and update hints to the person (#7160)
* fix(cli): address skills install and update hints to the person DeltaVerdict D5 fails any text an agent reads that tells the agent to install, update or remove skills, even when gated on the user. #7094 and #7102 fixed the update notice and skills/; the scaffolded CLAUDE.md and AGENTS.md, CLI output and the quickstart prompt still told the agent to run `skills update`. Reword them to state the fact and name the command the person runs ("For the user: ..."), matching the #7094 `_meta.updateNotice` style. The two scaffold templates stay byte-identical. No behavior changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): address media-use repair and update --check hints to the person Review follow-up on #7160. The media-use SFX repair error and its `resolve --doctor` line still told the agent to run `npx hyperframes skills update media-use`; `update --check` printed a bare `Run: <cmd>`; and the README addressed agents directly. Reword them in the "For the user:" form. The JSON `fix` field keeps the bare command. Pin the wording in tests: both scaffold templates, the stderr nudge, the `init --skip-skills` hint, the media-use error and doctor line, and the `update --check` output. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
b3b6a8116b
commit
604a25fbaa
@@ -64,7 +64,7 @@ For standalone skills (including OpenCode), use:
|
||||
npx skills add heygen-com/hyperframes
|
||||
```
|
||||
|
||||
> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video`, `/style-sampling` and `/figma` install on demand. Agents and non-interactive runs should use `npx hyperframes skills update` instead — it installs exactly the core set, whereas `skills add --all` installs all 9 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`.
|
||||
> The picker opens with nothing pre-selected — the **Core Skills** group is all you need; `/slideshow`, `/remotion-to-hyperframes`, `/reverse-any-video`, `/style-sampling` and `/figma` install on demand. Without the picker (a script or a CI job), `npx hyperframes skills update` installs exactly the core set, whereas `skills add --all` installs all 9 published skills. The six repo-internal skills under `.claude/skills` / `.agents/skills` are excluded by default. For the full published set use `npx hyperframes skills`.
|
||||
>
|
||||
> `skills add` resolves the skills.sh registry blob, which can lag `main` by hours. `npx hyperframes skills update` installs the skills from the release tag that matches your CLI version, so they match the CLI that runs them.
|
||||
|
||||
|
||||
+9
-3
@@ -55,13 +55,19 @@ system.
|
||||
|
||||
### The short way
|
||||
|
||||
If you already have a coding agent open in a folder, paste this. It installs the skills, makes the video, and opens
|
||||
the preview. You only change the URL.
|
||||
Unless the HyperFrames plugin is installed, install the skills once from a terminal in your project folder, then
|
||||
open or restart your coding agent there:
|
||||
|
||||
```bash
|
||||
npx hyperframes skills update
|
||||
```
|
||||
|
||||
Paste this into the agent. It makes the video and opens the preview. You only change the URL.
|
||||
|
||||
```text
|
||||
Set this folder up for HyperFrames and make me a video.
|
||||
|
||||
1. If the HyperFrames plugin is installed, use its bundled skills and launcher. Otherwise run: npx hyperframes skills update
|
||||
1. If the HyperFrames plugin is installed, use its bundled skills and launcher. If the HyperFrames skills are missing, stop and tell me: I install them with npx hyperframes skills update
|
||||
2. Then, using /hyperframes, make a 10-second product intro for https://example.com
|
||||
3. Open the local preview when it is done and tell me the project folder.
|
||||
```
|
||||
|
||||
@@ -174,4 +174,19 @@ describe("media treatment routing documentation", () => {
|
||||
expect(template).not.toContain("run_in_background: true");
|
||||
}
|
||||
});
|
||||
|
||||
// DeltaVerdict D5: text an agent reads may name the person's skills command but never
|
||||
// tell the agent to install, update or remove skills, even gated on consent.
|
||||
it("leaves installing and updating skills to the person in new project instructions", () => {
|
||||
for (const file of ["AGENTS.md", "CLAUDE.md"]) {
|
||||
const template = read("packages", "cli", "src", "templates", "_shared", file);
|
||||
expect(template).toContain("do not run the install yourself");
|
||||
expect(template).toContain("For the user:\n> `npx hyperframes skills update <name>`");
|
||||
for (const line of template.split("\n").filter((l) => /skills (update|add)/.test(l))) {
|
||||
expect(line, file).not.toMatch(
|
||||
/\b(Run|run|Re-run|Install|Update|Repair|Reinstall)\b[^`]*`npx (hyperframes )?skills/,
|
||||
);
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
@@ -180,6 +180,10 @@ describe("hyperframes init flag rename", () => {
|
||||
expect(res.status).toBe(0);
|
||||
expect(res.stdout).not.toContain("Checking AI coding skills");
|
||||
expect(res.stdout).not.toContain("temporarily ignored");
|
||||
// Installing skills is the person's step, so the hint is addressed to them.
|
||||
expect(res.stdout).toContain(
|
||||
"For the user: use your HyperFrames plugin, or install standalone skills with:",
|
||||
);
|
||||
} finally {
|
||||
rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
@@ -690,7 +690,9 @@ async function keepSkillsCurrent(destDir: string): Promise<void> {
|
||||
// "up to date"; the engine already reported what it could verify or
|
||||
// blind-install. Point at the recovery command instead.
|
||||
console.log(
|
||||
c.dim("Skills freshness unverified — run `npx hyperframes skills update` when online."),
|
||||
c.dim(
|
||||
"Skills freshness unverified (offline?). For the user: `npx hyperframes skills update` refreshes them once online.",
|
||||
),
|
||||
);
|
||||
} else if (result.installed.length === 0) {
|
||||
console.log(c.success("AI coding skills are already up to date."));
|
||||
@@ -977,7 +979,7 @@ export default defineCommand({
|
||||
console.log();
|
||||
if (skipSkills) {
|
||||
console.log(
|
||||
` ${c.accent("1.")} Use your HyperFrames plugin, or install standalone skills:`,
|
||||
` ${c.accent("1.")} For the user: use your HyperFrames plugin, or install standalone skills with:`,
|
||||
);
|
||||
console.log(` ${c.accent("npx hyperframes skills update")}`);
|
||||
} else {
|
||||
|
||||
@@ -380,7 +380,7 @@ export async function updateSkills(
|
||||
// reinstate the 26-skill sweep this path exists to avoid.
|
||||
clack.log.warn(
|
||||
c.warn(
|
||||
"Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. Re-run `hyperframes skills` online for the full set.",
|
||||
"Can't resolve the published skill set (manifest unreachable) — installing the pinned core set only. For the user: `hyperframes skills` installs the full set once online.",
|
||||
),
|
||||
);
|
||||
}
|
||||
@@ -550,7 +550,7 @@ function renderCheck(result: SkillsCheckResult): void {
|
||||
|
||||
if (!result.location) {
|
||||
console.log(` ${c.dim("No HyperFrames skills found in the usual locations.")}`);
|
||||
console.log(` ${c.accent("Install: npx hyperframes skills")}`);
|
||||
console.log(` ${c.accent("For the user: npx hyperframes skills installs them")}`);
|
||||
console.log();
|
||||
return;
|
||||
}
|
||||
@@ -577,14 +577,14 @@ function renderCheck(result: SkillsCheckResult): void {
|
||||
printSkillSection(
|
||||
result,
|
||||
"missing",
|
||||
"Available on demand (install with `hyperframes skills update <name>`):",
|
||||
"Available on demand (`hyperframes skills update <name>` installs one):",
|
||||
"◦",
|
||||
c.dim,
|
||||
(s) => !isCoreSkill(s.name),
|
||||
);
|
||||
console.log();
|
||||
if (result.updateAvailable) {
|
||||
console.log(` ${c.accent("Update: npx hyperframes skills update")}`);
|
||||
console.log(` ${c.accent("For the user: npx hyperframes skills update refreshes them")}`);
|
||||
} else {
|
||||
console.log(` ${c.success("◇")} ${c.success("Installed skills are up to date")}`);
|
||||
}
|
||||
|
||||
@@ -202,6 +202,14 @@ describe("hyperframes update --check", () => {
|
||||
expect(text).not.toContain("latest");
|
||||
});
|
||||
|
||||
it("names both commands for the person, not as a bare Run: line", async () => {
|
||||
await runUpdate(ENTRIES.npm, { check: true });
|
||||
const text = stdout.join("\n");
|
||||
expect(text).toContain("For the user: run npm install -g hyperframes@0.9.8");
|
||||
expect(text).toContain("For the user: run hyperframes update");
|
||||
expect(text).not.toMatch(/\bRun:/);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["npm", ENTRIES.npm, "npm install -g hyperframes@0.9.8"],
|
||||
["pnpm", ENTRIES.pnpm, "pnpm add -g hyperframes@0.9.8"],
|
||||
|
||||
@@ -153,10 +153,12 @@ function printCheck(cli: CliReport, skills: SkillsReport): void {
|
||||
: c.success(`${cli.current} (${cli.checkedAt ? "latest" : "npm registry not reached"})`);
|
||||
console.log(` ${c.bold("CLI".padEnd(8))}${version}`);
|
||||
console.log(` ${" ".repeat(8)}${c.dim(where)}`);
|
||||
if (cli.command) console.log(` ${" ".repeat(8)}${c.accent(`Run: ${cli.command}`)}`);
|
||||
if (cli.command) {
|
||||
console.log(` ${" ".repeat(8)}${c.accent(`For the user: run ${cli.command}`)}`);
|
||||
}
|
||||
console.log(` ${c.bold("Skills".padEnd(8))}${skillsLine(skills)}`);
|
||||
if (skills.status === "checked" && skills.command) {
|
||||
console.log(` ${" ".repeat(8)}${c.accent(`Run: ${skills.command}`)}`);
|
||||
console.log(` ${" ".repeat(8)}${c.accent(`For the user: run ${skills.command}`)}`);
|
||||
}
|
||||
console.log();
|
||||
}
|
||||
|
||||
@@ -27,7 +27,7 @@ export const BUNDLED_SFX_RECOVERY_COMMAND = "npx hyperframes skills update media
|
||||
export class BundledSfxAssetsError extends Error {
|
||||
constructor(health) {
|
||||
super(
|
||||
`bundled SFX assets are missing or incomplete (${health.detail}). Repair the installed media-use skill: ${health.fix}`,
|
||||
`bundled SFX assets are missing or incomplete (${health.detail}). For the user: \`${health.fix}\` repairs the installed media-use skill.`,
|
||||
);
|
||||
this.name = "BundledSfxAssetsError";
|
||||
this.code = health.code;
|
||||
|
||||
@@ -56,7 +56,11 @@ import {
|
||||
flushHeygenFailureTracking,
|
||||
versionLessThan,
|
||||
} from "./lib/heygen-cli.mjs";
|
||||
import { BundledSfxAssetsError, inspectBundledSfxAssets } from "./lib/bundled-sfx-provider.mjs";
|
||||
import {
|
||||
BUNDLED_SFX_RECOVERY_COMMAND,
|
||||
BundledSfxAssetsError,
|
||||
inspectBundledSfxAssets,
|
||||
} from "./lib/bundled-sfx-provider.mjs";
|
||||
import { OPENVERSE_SFX_PROVIDER } from "./lib/sfx-provider.mjs";
|
||||
import { writeSfxCredit } from "./lib/openverse.mjs";
|
||||
import {
|
||||
@@ -1150,7 +1154,13 @@ function printDoctor(checks) {
|
||||
const freePath = heygenChecks.has(check.name)
|
||||
? " — free-usage path: bgm/image/voice/avatar-video"
|
||||
: "";
|
||||
const fix = check.ok || !check.fix ? "" : ` — fix: ${check.fix}`;
|
||||
// Repairing a skill is the person's step, so that fix is addressed to them, not to the agent.
|
||||
const fix =
|
||||
check.ok || !check.fix
|
||||
? ""
|
||||
: check.fix === BUNDLED_SFX_RECOVERY_COMMAND
|
||||
? ` — For the user: \`${check.fix}\` repairs it`
|
||||
: ` — fix: ${check.fix}`;
|
||||
console.log(`${prefix} ${check.detail}${freePath}${fix}`);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -280,6 +280,23 @@ test("missing bundled SFX install returns a typed recovery command", () => {
|
||||
assert.equal(parsed.fix, "npx hyperframes skills update media-use");
|
||||
assert.match(parsed.error, /bundled SFX assets are missing or incomplete/);
|
||||
assert.match(parsed.error, /manifest not found/);
|
||||
// Repairing a skill is the person's step: the message names it for them, not the agent.
|
||||
assert.match(parsed.error, /For the user: `npx hyperframes skills update media-use` repairs/);
|
||||
assert.doesNotMatch(parsed.error, /Repair the installed/);
|
||||
cleanup();
|
||||
});
|
||||
|
||||
test("--doctor addresses the bundled SFX repair to the person", () => {
|
||||
setup();
|
||||
const result = spawnResolve(["--doctor"], {
|
||||
env: {
|
||||
HOME: tmp,
|
||||
PATH: tmp,
|
||||
HYPERFRAMES_MEDIA_USE_SFX_DIR: join(tmp, "missing-sfx-library"),
|
||||
},
|
||||
});
|
||||
assert.match(result.stdout, /For the user: `npx hyperframes skills update media-use` repairs it/);
|
||||
assert.doesNotMatch(result.stdout, /fix: npx hyperframes skills/);
|
||||
cleanup();
|
||||
});
|
||||
|
||||
|
||||
@@ -25,13 +25,14 @@ MP4.
|
||||
> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind).
|
||||
|
||||
> **Using a HyperFrames plugin?** Load skills from that installed bundle and follow
|
||||
> its `hyperframes/references/plugin-installation.md` execution rules. Update via
|
||||
> the plugin manager, not the standalone commands below.
|
||||
> its `hyperframes/references/plugin-installation.md` execution rules. The person updates
|
||||
> the plugin through its plugin manager; the standalone commands below do not apply.
|
||||
>
|
||||
> **Standalone skill missing or stale?** Run `npx hyperframes skills update <name>` to install/refresh
|
||||
> the specific skill you need, or bare `npx hyperframes skills update` to refresh the core set plus
|
||||
> everything already installed — neither pulls the full set. Restart the agent session so
|
||||
> newly installed skills load.
|
||||
> **Standalone skill missing or stale?** Installing and updating skills is the person's step:
|
||||
> tell them which skill is missing or stale, and do not run the install yourself. For the user:
|
||||
> `npx hyperframes skills update <name>` installs/refreshes that skill, and bare
|
||||
> `npx hyperframes skills update` refreshes the core set plus everything already installed —
|
||||
> neither pulls the full set. Newly installed skills load in a new agent session.
|
||||
|
||||
## Commands
|
||||
|
||||
|
||||
@@ -25,13 +25,14 @@ MP4.
|
||||
> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind).
|
||||
|
||||
> **Using a HyperFrames plugin?** Load skills from that installed bundle and follow
|
||||
> its `hyperframes/references/plugin-installation.md` execution rules. Update via
|
||||
> the plugin manager, not the standalone commands below.
|
||||
> its `hyperframes/references/plugin-installation.md` execution rules. The person updates
|
||||
> the plugin through its plugin manager; the standalone commands below do not apply.
|
||||
>
|
||||
> **Standalone skill missing or stale?** Run `npx hyperframes skills update <name>` to install/refresh
|
||||
> the specific skill you need, or bare `npx hyperframes skills update` to refresh the core set plus
|
||||
> everything already installed — neither pulls the full set. Restart the agent session so
|
||||
> newly installed skills load.
|
||||
> **Standalone skill missing or stale?** Installing and updating skills is the person's step:
|
||||
> tell them which skill is missing or stale, and do not run the install yourself. For the user:
|
||||
> `npx hyperframes skills update <name>` installs/refreshes that skill, and bare
|
||||
> `npx hyperframes skills update` refreshes the core set plus everything already installed —
|
||||
> neither pulls the full set. Newly installed skills load in a new agent session.
|
||||
|
||||
## Commands
|
||||
|
||||
|
||||
@@ -191,6 +191,9 @@ describe("skillsUpdateCheck", () => {
|
||||
gate.noTty = true;
|
||||
const text = await noticeTextFor({ skillsOutdatedCount: 2, skillsMissingCount: 1 });
|
||||
expect(text).toContain("3 HyperFrames skills out of date or missing");
|
||||
// The agent reads stderr too: the command is the person's to run (DeltaVerdict D5).
|
||||
expect(text).toContain("For the user: npx hyperframes skills update");
|
||||
expect(text).not.toMatch(/\bRun:/);
|
||||
});
|
||||
|
||||
it("prints at most once a day per project", async () => {
|
||||
|
||||
@@ -113,7 +113,7 @@ function skillsNoticeText(meta: SkillsUpdateMeta): string | null {
|
||||
const total = meta.outdated + meta.missing;
|
||||
if (total < 1) return null;
|
||||
const noun = total === 1 ? "skill" : "skills";
|
||||
return `\n ${total} HyperFrames ${noun} out of date or missing.\n Run: npx hyperframes skills update\n\n`;
|
||||
return `\n ${total} HyperFrames ${noun} out of date or missing.\n For the user: npx hyperframes skills update refreshes them.\n\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user