fix(skills): select standalone CLI releases through the launcher (#8102)

* fix(skills): select standalone CLI releases through the launcher

* fix(cli): clarify release commands and share launcher validation
This commit is contained in:
terencecho
2026-11-17 21:41:22 +00:00
committed by GitHub
parent a765c93791
commit 414adffb82
25 changed files with 252 additions and 65 deletions
+3
View File
@@ -149,6 +149,9 @@ runs the newest published CLI; in a plugin it runs the version the plugin pins.
only when the plugin folder's name does not start with a dot, the folder is not the one the
agent works in and does not contain it, and, if it lies inside that folder, a folder whose name
starts with a dot (such as `.claude`) sits between them. A pin older than 0.9.34 is refused.
For a standalone workflow that needs a particular release, the agent passes
`--cli-version latest` or `--cli-version <exact-version>` to the installed launcher before the CLI
command. This also works for releases with a prerelease suffix. Plugin installs keep their pin.
The agent runs a project's own npm scripts only when you ask for one by name.
## Install more only when you need it
@@ -2,6 +2,7 @@
// command for that install: the manager's for a global one, `npx hyperframes@latest` for npx.
// The install detection is real; only the resolved entry path and the cached latest are stubbed.
import { homeCliCommand } from "../utils/homeCliCommand.js";
import { afterEach, describe, expect, it, vi } from "vitest";
const ENTRIES = {
@@ -70,7 +71,7 @@ describe("doctor: the update hint fits the install", () => {
it.each([
["npm", ENTRIES.npm, "Run: npm install -g hyperframes@0.9.8"],
["brew", ENTRIES.brew, "Run: brew upgrade hyperframes"],
["npx", ENTRIES.npx, "Run: npx hyperframes@latest"],
["npx", ENTRIES.npx, `Run: ${homeCliCommand("latest")}`],
["project", ENTRIES.project, "Run: npm install hyperframes@0.9.8"],
])("%s", async (_channel, entry, hint) => {
const { checkVersion } = await doctorAt(entry, "0.9.8");
@@ -13,7 +13,7 @@ const server = vi.hoisted(() => ({
const probe = vi.hoisted(() => ({ fail: false }));
const terminal = vi.hoisted(() => ({ remote: false }));
const shadow = vi.hoisted(() => ({
install: null as { version: string; updateCommand: string } | null,
install: null as { version: string; updateCommand: string | null } | null,
}));
const commandRuns = vi.hoisted(() => [] as Record<string, unknown>[]);
@@ -189,7 +189,7 @@ describe("reverse start", () => {
login_command: "npx hyperframes auth login",
// The reason to sign in comes before the sign-in, as words the agent can say as they are.
next: expect.stringMatching(
/"To rebuild this video.*HeyGen.*"[^]*Run `npx hyperframes auth login` now and wait/,
/"To rebuild this video.*HeyGen.*"[^]*Run `auth login` through the same launcher now and wait/,
),
},
],
@@ -221,7 +221,7 @@ describe("reverse start", () => {
signed_in: false,
login_command: "npx hyperframes auth login --device",
next: expect.stringMatching(
/`npx hyperframes auth login --device` in the background[^]*one message: first why[^]*"To rebuild this video.*HeyGen.*"[^]*Then the link and code/,
/`auth login --device` through the same launcher in the background[^]*one message: first why[^]*"To rebuild this video.*HeyGen.*"[^]*Then the link and code/,
),
});
});
@@ -232,7 +232,7 @@ describe("reverse start", () => {
expect(output()).toMatchObject({
reverse: {
next: expect.stringMatching(
/^Their installed HyperFrames \(0\.9\.8\) is out of date[^]*"Your installed HyperFrames is out of date[^]*`npm install -g hyperframes@latest`\."[^]*Not signed in/,
/^Their installed HyperFrames \(0\.9\.8\) is out of date[^]*launcher with --cli-version [^ ]+[^]*"Your installed HyperFrames is out of date[^]*`npm install -g hyperframes@latest` from your home directory\."[^]*Not signed in/,
),
},
});
+6 -3
View File
@@ -52,19 +52,22 @@ function signInForThisTerminal() {
if (isRemoteOrHeadless()) {
return {
login_command: "npx hyperframes auth login --device",
next: `Not signed in, and no browser can open here. Start \`npx hyperframes auth login --device\` in the background now, then send the person one message: first why, in their language, for example: ${WHY} Then the link and code it printed. It returns once they approve; then run reverse start again. ${PLAIN}`,
next: `Not signed in, and no browser can open here. Start \`auth login --device\` through the same launcher in the background now, then send the person one message: first why, in their language, for example: ${WHY} Then the link and code it printed. It returns once they approve; then run reverse start again. ${PLAIN}`,
};
}
return {
login_command: "npx hyperframes auth login",
next: `Not signed in. Tell the person why first, in their language, for example: ${WHY} Run \`npx hyperframes auth login\` now and wait for it: it opens the browser and returns once they are signed in (when the browser does not open it prints a link: send it with the same reason). Then run reverse start again. ${PLAIN}`,
next: `Not signed in. Tell the person why first, in their language, for example: ${WHY} Run \`auth login\` through the same launcher now and wait for it: it opens the browser and returns once they are signed in (when the browser does not open it prints a link: send it with the same reason). Then run reverse start again. ${PLAIN}`,
};
}
function staleInstallLine(): string | null {
const stale = shadowingInstall(VERSION);
if (!stale) return null;
return `Their installed HyperFrames (${stale.version}) is out of date and answers plain \`npx hyperframes\`, so run every command of this run as \`npx -y hyperframes@${VERSION} <command>\`. Your next message to the person opens with this, in their language: "Your installed HyperFrames is out of date, so I'm using the latest release for this run. To update it, run \`${stale.updateCommand}\`."`;
const update = stale.updateCommand
? ` To update it, run \`${stale.updateCommand}\` from your home directory.`
: "";
return `Their installed HyperFrames (${stale.version}) is out of date. For this run, use the installed standalone skill launcher with --cli-version ${VERSION} before each command. Your next message to the person opens with this, in their language: "Your installed HyperFrames is out of date, so I'm using release ${VERSION} for this run.${update}"`;
}
function withStaleLine(next: string | undefined): { next?: string } {
+3 -2
View File
@@ -3,6 +3,7 @@
// the upgrade argv and the skills install run for real per install channel;
// only spawn, the config file, the manifest fetch/disk and the registry are stubbed.
import { homeCliCommand } from "../utils/homeCliCommand.js";
import { EventEmitter } from "node:events";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -215,7 +216,7 @@ describe("hyperframes update --check", () => {
["pnpm", ENTRIES.pnpm, "pnpm add -g hyperframes@0.9.8"],
["bun", ENTRIES.bun, "bun add -g hyperframes@0.9.8"],
["brew", ENTRIES.brew, "brew upgrade hyperframes"],
["npx", ENTRIES.npx, "npx hyperframes@latest"],
["npx", ENTRIES.npx, homeCliCommand("latest")],
["project", ENTRIES.project, "npm install hyperframes@0.9.8"],
])("names the %s install and the command that updates it", async (channel, entry, command) => {
await runUpdate(entry, { check: true, json: true });
@@ -271,7 +272,7 @@ describe("hyperframes update (install)", () => {
);
it.each([
["npx", ENTRIES.npx, "npx hyperframes@latest"],
["npx", ENTRIES.npx, homeCliCommand("latest")],
// The project's manager moves its dependency, as `--check` names it.
["project", ENTRIES.project, "npm install hyperframes@0.9.8"],
])(
+4 -4
View File
@@ -1,3 +1,4 @@
import { homeCliCommand } from "../utils/homeCliCommand.js";
import { setCommandExitCode } from "../utils/commandResult.js";
import { defineCommand } from "../utils/defineCommand.js";
import type { Example } from "./_examples.js";
@@ -138,14 +139,14 @@ function applyUpgrade(result: UpdateCheckResult, autoYes: boolean): void {
}
if (!autoYes) {
printManualCommands(plan.displayCmd, `npx hyperframes@${result.latest}`);
printManualCommands(plan.displayCmd, homeCliCommand(result.latest));
return;
}
runDetectedInstall(plan.invocation, plan.displayCmd, result.latest);
}
const NPX_LATEST = `npx hyperframes@${updateChannel()}`;
const NPX_LATEST = homeCliCommand(updateChannel());
/**
* How `upgrade --yes` moves this install to `latest`: the detected manager's argv, or, for an
@@ -318,8 +319,7 @@ function printProjectPinResult(
console.log(
` ${c.success("◇")} ${verb} project pins ${res.from.join(", ")} → ${c.accent(res.to)}`,
);
if (checkOnly)
console.log(` ${c.dim("Run `npx hyperframes@latest upgrade --project` to apply.")}`);
if (checkOnly) console.log(` ${c.dim("Repeat the same command without --check to apply.")}`);
}
export function runDetectedInstall(
@@ -43,6 +43,9 @@ describe("checkRegistryItemCompatibility", () => {
"0.6.79",
);
expect(result.error).toContain('Registry item "demo-block" requires hyperframes >= 0.6.80');
expect(result.error).toContain("Retry the original command");
expect(result.error).toContain("--cli-version latest");
expect(result.error).not.toContain("npx");
});
it("allows source/dev CLI builds to install future-gated registry items", () => {
+2 -2
View File
@@ -38,8 +38,8 @@ export function checkRegistryItemCompatibility(
warnings,
error:
`Registry item "${item.name}" requires hyperframes >= ${minCliVersion} ` +
`(current: ${currentCliVersion}). Run \`npx hyperframes@latest add ${item.name}\` ` +
"or upgrade your installed hyperframes CLI.",
`(current: ${currentCliVersion}). Retry the original command after updating your CLI or plugin. ` +
"With standalone skills, retry through the installed launcher with --cli-version latest.",
};
}
+3 -1
View File
@@ -24,6 +24,8 @@ MP4.
> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind).
> Follow the loaded skill’s launcher instructions for every CLI command below.
>
> **Using a HyperFrames plugin?** Load skills from that installed bundle and follow
> its `hyperframes/references/plugin-installation.md` execution rules. The person updates
> the plugin through its plugin manager; the standalone commands below do not apply.
@@ -60,7 +62,7 @@ npx hyperframes docs <topic> # reference docs in terminal
> **Back from the desktop app.** Once this project was opened in the HyperFrames desktop app, run `npx hyperframes catch-up` before your next change here: it lists what the person asked Framey in the app and which files changed since.
> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. To move up: `npx hyperframes@latest upgrade --project . --check` (shows the delta), then `npx hyperframes@latest upgrade --project .` to rewrite the pins. Always unpinned — the pinned script re-runs the old version against itself.
> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. With standalone skills, run the installed launcher with `--cli-version latest upgrade --project . --check` to see the delta. Repeat without `--check` to rewrite the pins. Plugin workflows keep their bundled CLI.
## Documentation
+3 -1
View File
@@ -24,6 +24,8 @@ MP4.
> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `hyperframes-cli/references/init-and-scaffold.md` (Tailwind).
> Follow the loaded skill’s launcher instructions for every CLI command below.
>
> **Using a HyperFrames plugin?** Load skills from that installed bundle and follow
> its `hyperframes/references/plugin-installation.md` execution rules. The person updates
> the plugin through its plugin manager; the standalone commands below do not apply.
@@ -60,7 +62,7 @@ npx hyperframes docs <topic> # reference docs in terminal
> **Back from the desktop app.** Once this project was opened in the HyperFrames desktop app, run `npx hyperframes catch-up` before your next change here: it lists what the person asked Framey in the app and which files changed since.
> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. To move up: `npx hyperframes@latest upgrade --project . --check` (shows the delta), then `npx hyperframes@latest upgrade --project .` to rewrite the pins. Always unpinned — the pinned script re-runs the old version against itself.
> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. With standalone skills, run the installed launcher with `--cli-version latest upgrade --project . --check` to see the delta. Repeat without `--check` to rewrite the pins. Plugin workflows keep their bundled CLI.
## Documentation
+12
View File
@@ -0,0 +1,12 @@
/** Manual update commands are often copied from a project terminal. Start npm in the home folder. */
export function homeCliCommand(
release: string,
action: "" | "update" = "",
platform = process.platform,
): string {
const args = `hyperframes@${release}${action ? " " + action : ""}`;
if (platform === "win32") {
return `powershell.exe -NoProfile -Command "Set-Location ~ -ErrorAction Stop; npx.cmd ${args}"`;
}
return `(cd ~ && npx ${args})`;
}
@@ -1,3 +1,4 @@
import { homeCliCommand } from "./homeCliCommand.js";
import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { delimiter, dirname, join } from "node:path";
@@ -214,12 +215,12 @@ describe("runningInstall: which binary runs, and the command that updates it", (
[
"npx",
"/home/me/.npm/_npx/4f1c2a/node_modules/hyperframes/dist/cli.js",
"npx hyperframes@latest",
homeCliCommand("latest"),
],
[
"npx",
"/tmp/bunx-1000-hyperframes@latest/node_modules/hyperframes/dist/cli.js",
"npx hyperframes@latest",
homeCliCommand("latest"),
],
[
"project",
@@ -231,8 +232,8 @@ describe("runningInstall: which binary runs, and the command that updates it", (
"/home/me/video/node_modules/.pnpm/hyperframes@0.9.5/node_modules/hyperframes/dist/cli.js",
"npm install hyperframes@0.9.8",
],
["workspace", "/home/me/hyperframes/packages/cli/dist/cli.js", "npx hyperframes@latest"],
["unknown", "/opt/tools/hyperframes/cli.js", "npx hyperframes@latest"],
["workspace", "/home/me/hyperframes/packages/cli/dist/cli.js", homeCliCommand("latest")],
["unknown", "/opt/tools/hyperframes/cli.js", homeCliCommand("latest")],
])("classifies a %s install at %s; update with: %s", async (channel, path, command) => {
const run = await runningAt(path);
expect(run.install).toEqual({ channel, path });
@@ -328,14 +329,14 @@ describe("shadowingInstall: the older global install a plain `npx hyperframes` r
return pkg;
}
it("moves an older project-local install with the project's own manager", async () => {
it("reports an older project-local install without a global update command", async () => {
const root = layout(null);
onPathInstead(root, "app/node_modules/hyperframes");
writeFileSync(join(root, "app/bun.lock"), "");
const { shadowingInstall } = await import("./installerDetection.js");
expect(shadowingInstall("0.9.29")).toEqual({
version: "0.9.8",
updateCommand: "bun add hyperframes@0.9.29",
updateCommand: null,
});
});
@@ -355,7 +356,7 @@ describe("shadowingInstall: the older global install a plain `npx hyperframes` r
expect(process.env["PATH"]).toBe(npxBin);
expect(shadowingInstall("0.9.29")).toEqual({
version: "0.9.8",
updateCommand: "bun add hyperframes@0.9.29",
updateCommand: null,
});
});
+8 -4
View File
@@ -6,6 +6,7 @@
* in charge.
*/
import { homeCliCommand } from "./homeCliCommand.js";
import { existsSync, readFileSync, realpathSync } from "node:fs";
import { delimiter, dirname, join, posix } from "node:path";
import { compareVersions } from "compare-versions";
@@ -286,7 +287,7 @@ export function updateCommandFor(install: RunningInstall, latest: string): strin
const invocation = installInvocation(kind, latest);
if (invocation) return `${invocation.bin} ${invocation.args.join(" ")}`;
}
return "npx hyperframes@latest";
return homeCliCommand("latest");
}
/** The version in the `hyperframes` package.json at or above a resolved bin script, or null. */
@@ -315,8 +316,8 @@ const UPDATABLE_CHANNELS = new Set<InstallChannel>(["npm", "pnpm", "bun", "brew"
export interface ShadowingInstall {
version: string;
/** What moves that install to the latest release. */
updateCommand: string;
/** Global update command the person can run from home. */
updateCommand: string | null;
}
function resolvedOrNull(path: string): string | null {
@@ -358,5 +359,8 @@ export function shadowingInstall(current: string): ShadowingInstall | null {
if (!global || !version || !isOlder(version, current)) return null;
const install = installAt(global);
if (!UPDATABLE_CHANNELS.has(install.channel)) return null;
return { version, updateCommand: updateCommandFor(install, current) };
return {
version,
updateCommand: install.channel === "project" ? null : updateCommandFor(install, current),
};
}
@@ -72,7 +72,7 @@ describe("printStalePinNotice", () => {
printStalePinNotice(dir);
printStalePinNotice(dir); // throttled — second call silent
expect(writes.join("")).toContain("0.7.48");
expect(writes.join("")).toContain("upgrade --project");
expect(writes.join("")).toContain("--cli-version latest upgrade --project .");
expect(writes.filter((w) => w.includes("upgrade --project")).length).toBe(1);
});
@@ -86,17 +86,19 @@ describe("printStalePinNotice", () => {
});
it("warns on every run when an older CLI than the pin is running", () => {
store = { latestVersion: "0.8.71" };
store = { latestVersion: "0.9.71" };
runningVersion = "0.7.71";
writeFileSync(
join(dir, "package.json"),
JSON.stringify({ scripts: { check: "npx --yes hyperframes@0.8.66 check" } }),
JSON.stringify({ scripts: { check: "npx --yes hyperframes@0.9.66 check" } }),
);
printStalePinNotice(dir);
printStalePinNotice(dir);
const mismatch = writes.filter((w) => w.includes("This is hyperframes 0.7.71"));
expect(mismatch.length).toBe(2);
expect(mismatch[0]).toContain("npx hyperframes@0.8.66");
expect(mismatch[0]).toContain("--cli-version 0.9.66");
expect(mismatch[0]).toContain("start in your home folder, run npx hyperframes@0.9.66");
expect(mismatch[0]).toContain("absolute path");
expect(writes.join("")).not.toContain("upgrade --project");
});
+16 -6
View File
@@ -1,3 +1,4 @@
import { homeCliCommand } from "./homeCliCommand.js";
import { mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
@@ -96,6 +97,15 @@ async function noticeWith(opts: {
return writes.join("");
}
describe("manual CLI update commands", () => {
it("starts npm in the home folder on both shell families", () => {
expect(homeCliCommand("beta", "update", "linux")).toBe("(cd ~ && npx hyperframes@beta update)");
expect(homeCliCommand("0.9.63", "", "win32")).toBe(
'powershell.exe -NoProfile -Command "Set-Location ~ -ErrorAction Stop; npx.cmd hyperframes@0.9.63"',
);
});
});
describe("printUpdateNotice — install-method-aware command", () => {
afterEach(() => {
vi.doUnmock("./env.js");
@@ -109,12 +119,12 @@ describe("printUpdateNotice — install-method-aware command", () => {
const out = await noticeWith({ installerCommand: "brew upgrade hyperframes" });
expect(out).toContain("Update available");
expect(out).toContain("brew upgrade hyperframes");
expect(out).not.toContain("npx hyperframes@latest");
expect(out).not.toContain(homeCliCommand("latest"));
});
it("falls back to npx hyperframes@latest when the install method is skip/unknown", async () => {
const out = await noticeWith({ installerCommand: null });
expect(out).toContain("npx hyperframes@latest");
expect(out).toContain(homeCliCommand("latest"));
});
it("is suppressed on a non-TTY stderr", async () => {
@@ -642,8 +652,8 @@ describe("updateCheckDue / cachedUpdateCheck — what the parent reads without f
[
"npx",
undefined,
"npx hyperframes@latest update",
"npx hyperframes@latest update",
homeCliCommand("latest", "update"),
homeCliCommand("latest", "update"),
"npx hyperframes update",
],
[
@@ -663,8 +673,8 @@ describe("updateCheckDue / cachedUpdateCheck — what the parent reads without f
];
for (const [config, command] of cases) {
const mod = await loadNotice(config, channel, path);
expect(mod.withMeta({ ok: true })._meta.updateNotice).toMatch(
new RegExp(`run: ${command.replaceAll(".", "\\.")}$`),
expect(mod.withMeta({ ok: true })._meta.updateNotice?.endsWith(`run: ${command}`)).toBe(
true,
);
}
},
+7 -4
View File
@@ -1,3 +1,4 @@
import { homeCliCommand } from "./homeCliCommand.js";
import { existsSync, readFileSync } from "node:fs";
import { join, resolve } from "node:path";
import { compareVersions } from "compare-versions";
@@ -237,7 +238,7 @@ export function updateCommandForThisInstall(
return projectNoticeCommand(install, cliBehind, skillsBehind, latest);
}
return install.channel === "npx" && cliBehind
? `npx hyperframes@${updateChannel()} update`
? homeCliCommand(updateChannel(), "update")
: "npx hyperframes update";
}
@@ -356,7 +357,7 @@ export function printUpdateNotice(): void {
// the suppression + update-available gates, so it adds no cost to normal runs.
const safeLatest = isSafeVersion(meta.latestVersion);
const managerCommand = safeLatest ? detectInstaller().installCommand(meta.latestVersion) : null;
const command = managerCommand ?? `npx hyperframes@${updateChannel()}`;
const command = managerCommand ?? homeCliCommand(updateChannel());
process.stderr.write(
`\n Update available: ${meta.version} \u2192 ${meta.latestVersion}\n` +
@@ -390,7 +391,8 @@ export function printStalePinNotice(cwd: string = process.cwd()): void {
if (newerPins.length > 0) {
process.stderr.write(
`\n This is hyperframes ${VERSION}, but this project pins hyperframes@${newerPins.join(", ")}.\n` +
` Run it through the project's npm scripts, or npx hyperframes@${newerPins.at(-1)}.\n\n`,
` Use the installed standalone skill launcher with --cli-version ${newerPins.at(-1)} to run the pinned release.\n` +
` Without standalone skills, start in your home folder, run npx hyperframes@${newerPins.at(-1)} with the desired command, and pass the project by absolute path.\n\n`,
);
return;
}
@@ -414,6 +416,7 @@ export function printStalePinNotice(cwd: string = process.cwd()): void {
process.stderr.write(
`\n This project pins hyperframes@${stale.join(", ")} (latest ${latest}).\n` +
` Bump it: npx hyperframes@latest upgrade --project\n\n`,
` Use the installed standalone skill launcher with --cli-version latest upgrade --project . to bump the pin.\n` +
` Without standalone skills, run the latest CLI from your home folder and pass the absolute project path to upgrade --project.\n\n`,
);
}
+13
View File
@@ -17,6 +17,7 @@ import {
lintFrontmatter,
lintRegistryItemRefs,
lintRelativeScriptRuns,
lintVersionedCliRuns,
} from "./lint-skills.ts";
const wrap = (frontmatter) => `---\n${frontmatter}\n---\n\n# body\n`;
@@ -401,3 +402,15 @@ test("relative scripts: a marker with a reason opts the doc out", () => {
const noReason = "<!-- skill-scripts: relative-ok -->\n" + body;
assert.equal(lintRelativeScriptRuns(noReason).length, 1);
});
test("versioned CLI examples use the installed launcher", () => {
for (const prefix of ["npx", "npx -y", "npx --yes", "npm exec --", "bunx"]) {
assert.equal(lintVersionedCliRuns(`Run \`${prefix} hyperframes@latest --version\`.`).length, 1);
}
assert.deepEqual(
lintVersionedCliRuns(
'Run `node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version latest --version`.',
),
[],
);
});
+18 -1
View File
@@ -10,7 +10,7 @@
*/
import { readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
import { dirname, join, relative, resolve } from "node:path";
import { dirname, join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";
import { parse as parseYaml, YAMLParseError } from "yaml";
import type { RegistryManifest } from "../packages/core/src/index.js";
@@ -568,6 +568,20 @@ export function lintRelativeScriptRuns(content: string): LineViolation[] {
});
}
export function lintVersionedCliRuns(content: string): LineViolation[] {
return codeSegments(content)
.filter(({ text }) =>
/\b(?:npx|npm\s+exec|bunx)\s+(?:-{1,2}[\w-]+\s+|--\s+)*hyperframes@/.test(text),
)
.map(({ text, line }) =>
violation(
line,
"Select the CLI release with the installed launcher's --cli-version option.",
text,
),
);
}
function collectMarkdownFiles(dir: string): string[] {
return readdirSync(dir, { withFileTypes: true, recursive: true })
.filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
@@ -597,6 +611,9 @@ function lintMarkdownFiles(paths: string[], knownItems: Set<string>, report: Rep
const file = relative(process.cwd(), path);
report(file, lintDocRefs(path, content));
report(file, lintRelativeScriptRuns(content));
if (path.startsWith(join(REPO_ROOT, "skills") + sep)) {
report(file, lintVersionedCliRuns(content));
}
const found = lintRegistryItemRefs(content, knownItems);
if (found === null) continue;
snapshotsChecked++;
+3 -3
View File
@@ -6,11 +6,11 @@
"files": 3
},
"hyperframes": {
"hash": "5e1305c67d48155a",
"hash": "1db6e25a6ac15568",
"files": 81
},
"hyperframes-cli": {
"hash": "8c7ba18bfc4e86c1",
"hash": "4ceea9a9ef69905c",
"files": 13
},
"hyperframes-registry": {
@@ -26,7 +26,7 @@
"files": 76
},
"reverse-any-video": {
"hash": "addcf365498eb4aa",
"hash": "e429671078249b3e",
"files": 5
},
"slideshow": {
@@ -23,7 +23,7 @@ npx hyperframes upgrade --yes # print upgrade commands without promptin
Compares the installed CLI version against npm latest.
`--project [dir]` bumps a **project's** pinned scripts instead of the global install: it rewrites every `npx …hyperframes@<version>…` in `<dir>/package.json` (default cwd) to npm-latest. Always invoke it unpinned (`npx hyperframes@latest upgrade --project`) — a project scaffolded on an old CLI stays frozen otherwise. `--project . --check` reports the delta without writing; add `--json` for `{ changed, from, to, path }`. Pass the dir explicitly whenever another flag follows `--project` — on older releases a bare `--project` consumes the next flag as its directory value.
`--project [dir]` bumps a **project's** pinned scripts instead of the global install: it rewrites every `npx …hyperframes@<version>…` in `<dir>/package.json` (default cwd) to npm-latest. With standalone skills, use `node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version latest upgrade --project .`. In a plugin, keep using its bundled CLI. `--project . --check` reports the delta without writing; add `--json` for `{ changed, from, to, path }`. Pass the dir explicitly whenever another flag follows `--project` — on older releases a bare `--project` consumes the next flag as its directory value.
## timeline
@@ -20,7 +20,12 @@ launcher.
## Standalone skill installs
Without a plugin manifest, the launcher runs the newest published CLI. The person installs and
Without a plugin manifest, the launcher runs the newest compatible published CLI. To select a
release, put `--cli-version latest` or `--cli-version <exact-version>` before the command.
Use the launcher from the loaded skill installation for commands shown in CLI output, too.
For example, run `node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version latest --version`
to read the current release. If the installed launcher lacks this option, ask the person to update
their skills. The person installs and
updates standalone skills with `npx hyperframes skills update`.
## Plugin installs
@@ -45,10 +45,19 @@ The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `c
## Keep the project's CLI current
For standalone skills, use the launcher from the loaded skill installation. Plugins keep their bundled CLI.
A scaffolded project pins `hyperframes@<version>` in its `package.json` scripts so renders stay reproducible; the pin never advances on its own, and a pinned run of an older CLI prints no warning about it. When resuming a project whose scripts carry a pin, probe once before the first render-affecting command:
```bash
npx hyperframes@latest upgrade --project . --check
node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version latest upgrade --project . --check
```
The probe is read-only and reports the pin against the latest release; keep the explicit `.` — on older CLI releases a bare `--project` followed by another flag consumes that flag as its directory value. When it reports the project behind — or any CLI output already shows it (the stderr notice `This project pins hyperframes@… (latest …)`, or `_meta.updateAvailable: true` in a `--json` result from a pinned script) — apply with `npx hyperframes@latest upgrade --project .`, then verify with `npx hyperframes check`. A passing check confirms the project's compositions still validate on the new version — not that rendered output is frame-identical to the old pin — so a successful bump is never silent: name the old and new version in the run's summary. A project with no composition yet needs no verification. If the check fails, revert the `package.json` change, continue on the pinned version, and report which version the project stays on and why. Act on the signal rather than relaying it to the user; never leave a bumped pin unverified.
The probe reads the current pin and the latest release. Keep the explicit `.` so older releases parse the project directory correctly. If the probe, the stale-pin notice, or the JSON update metadata shows the project is behind, apply the upgrade. Then use the exact version the upgrade reported to check the project:
```bash
node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version latest upgrade --project .
node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version <new-version> check
```
Report the old and new versions. The check validates the compositions. A project with no compositions yet can skip it. If validation fails, revert the pin changes, report the reason and continue with the original exact version if the launcher supports it.
+36 -7
View File
@@ -49,10 +49,33 @@ function isPluginBundle(pluginRoot, workDir) {
}
function isBelowFloor(version) {
const parts = (text) => text.split("-")[0].split(".").map(Number);
const parts = (text) => text.split(/[-+]/, 1)[0].split(".").map(Number);
const [have, floor] = [parts(version), parts(CLI_FLOOR)];
const at = have.findIndex((part, index) => part !== floor[index]);
return at === -1 ? version.includes("-") : have[at] < floor[at];
return at === -1 ? version.split("+", 1)[0].includes("-") : have[at] < floor[at];
}
function isExactRelease(value) {
const match =
typeof value === "string" &&
value.length <= 256 &&
/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
value,
);
return Boolean(
match &&
!match[4]?.split(".").some((id) => /^0\d+$/.test(id)) &&
match.slice(1, 4).every((part) => Number.isSafeInteger(Number(part))),
);
}
function standaloneRelease(value) {
if (value === "latest") return value;
if (!isExactRelease(value)) {
throw new Error("--cli-version requires latest or an exact HyperFrames version.");
}
if (isBelowFloor(value)) throw new Error(`This launcher runs HyperFrames ${CLI_FLOOR} or newer.`);
return value;
}
export function pluginVersion(pluginRoot = root, workDir = process.cwd()) {
@@ -61,10 +84,7 @@ export function pluginVersion(pluginRoot = root, workDir = process.cwd()) {
const file = join(pluginRoot, path);
if (!existsSync(file)) continue;
const manifest = JSON.parse(readFileSync(file, "utf8"));
if (
manifest.name !== "hyperframes" ||
!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.version ?? "")
) {
if (manifest.name !== "hyperframes" || !isExactRelease(manifest.version)) {
throw new Error(`Invalid HyperFrames plugin release: ${file}`);
}
if (isBelowFloor(manifest.version))
@@ -97,6 +117,14 @@ export function invocation(
launcher = fileURLToPath(import.meta.url),
} = {},
) {
let release = version;
if (args[0] === "--cli-version") {
if (version) throw new Error("The plugin manager selects this plugin's CLI version.");
release = standaloneRelease(args[1]);
args = args.slice(2);
} else if (!version && env.HYPERFRAMES_STANDALONE_CLI_VERSION !== undefined) {
release = standaloneRelease(env.HYPERFRAMES_STANDALONE_CLI_VERSION);
}
if (version && args[0] === "skills")
throw new Error(
"Bundled skills are release-managed; the person updates HyperFrames through their agent's plugin manager.",
@@ -114,9 +142,10 @@ export function invocation(
if (!args[1]) throw new Error("--script requires a Node script path.");
// Helpers that call the CLI run it through this launcher, never a `hyperframes` from the project.
const env = { ...childEnv, HYPERFRAMES_CLI_ENTRY: launcher };
if (!version && release) env.HYPERFRAMES_STANDALONE_CLI_VERSION = release;
return { command: node, args: args.slice(1), env, cwd };
}
const cliArgs = ["--yes", version ? `hyperframes@${version}` : STANDALONE_CLI, ...args];
const cliArgs = ["--yes", release ? `hyperframes@${release}` : STANDALONE_CLI, ...args];
const cliEnv = { ...childEnv, HYPERFRAMES_PLUGIN_CWD: cwd };
const npxCwd = npmCwd ?? npmFolder();
if (platform !== "win32") return { command: "npx", args: cliArgs, env: cliEnv, cwd: npxCwd };
@@ -71,6 +71,73 @@ test("a standalone install runs the newest CLI that moves into the project, and
assert.deepEqual(result.env, { PATH: "/bin", HYPERFRAMES_PLUGIN_CWD: "/work/project" });
});
test("manifest pins and standalone selectors use the same exact release syntax", (t) => {
const { root } = fixture(t);
for (const version of ["1.0.0-rc.1+build.2", "01.2.3", "1.0.0-01", "1.0.0-rc..1"]) {
writeFileSync(join(root, "plugin.json"), JSON.stringify({ name: "hyperframes", version }));
const select = () =>
invocation(["--cli-version", version, "--version"], { version: null, platform: "linux" });
if (version === "1.0.0-rc.1+build.2") {
assert.equal(pluginVersion(root), version);
assert.ok(select().args.includes(`hyperframes@${version}`));
} else {
assert.throws(() => pluginVersion(root), /Invalid HyperFrames plugin release/);
assert.throws(select, /exact HyperFrames version/);
}
}
});
test("standalone release selection keeps npm in the home folder and passes only CLI arguments", () => {
const options = {
version: null,
platform: "linux",
cwd: "/project",
npmCwd: "/home/person",
env: {},
};
for (const [release, args] of [
["latest", ["upgrade", "--project", ".", "--check"]],
["0.9.34+build-1", ["--version"]],
["1.0.0-rc.1", ["reverse", "start", "a b.mp4"]],
]) {
const run = invocation(["--cli-version", release, ...args], options);
assert.equal(run.cwd, options.npmCwd);
assert.deepEqual(run.args, ["--yes", `hyperframes@${release}`, ...args]);
assert.deepEqual(run.env, { HYPERFRAMES_PLUGIN_CWD: options.cwd });
}
for (const release of [
undefined,
"",
"beta",
"^1.2.3",
"./cli",
"--version",
"1.2.3-01",
"01.2.3",
"1.2.3+",
]) {
assert.throws(
() => invocation(["--cli-version", release], options),
/requires latest or an exact/,
);
}
for (const release of ["0.9.33", "0.9.34-rc.1+build"]) {
assert.throws(() => invocation(["--cli-version", release], options), /0.9.34 or newer/);
}
assert.throws(
() => invocation(["--cli-version", "latest"], { version: "1.2.3" }),
/plugin manager/,
);
});
test("a standalone helper passes its selected release to its own CLI calls", () => {
const options = { version: null, platform: "linux", npmCwd: "/home/person", env: {} };
const helper = invocation(["--cli-version", "1.2.3", "--script", "helper.mjs"], options);
assert.deepEqual(helper.args, ["helper.mjs"]);
const nested = invocation(["--version"], { ...options, env: helper.env });
assert.deepEqual(nested.args, ["--yes", "hyperframes@1.2.3", "--version"]);
});
test("pins CLI, suppresses standalone refresh, preserves unrelated environment", () => {
const result = invocation(["init", "project with spaces", "--non-interactive"], {
version: "1.2.3",
+7 -7
View File
@@ -17,8 +17,8 @@ which copies the video in untouched under its own file name and keeps the sessio
refuses a folder that already holds other files. Outside a plugin, a CLI is an old install (often a global one, which
never updates itself when an agent runs it) shadowing the current release when it does not know `reverse start`, when
its `reverse start` output has `_meta.updateAvailable: true`, or when that output says `signed_in: false` with no
`reverse.next`. Then run `npx -y hyperframes@latest --version` once and run `reverse start` again and every later
command of this run as `npx -y hyperframes@<that version> <command>`, so the whole run uses one release. That `reverse start` names the out-of-date install in `reverse.next` with the line
`reverse.next`. Then run `node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version latest --version` once and run `reverse start` again and every later
command of this run as `node "<SKILLS>/hyperframes/scripts/plugin-cli.mjs" --cli-version <that-version> <command>`, so the whole run uses one release. That `reverse start` names the out-of-date install in `reverse.next` with the line
to open your next message to the person with: say it.
Inside a plugin, its pinned CLI is the one that runs: if it does not know `reverse start`, stop before anything is paid
for, and tell the person in one line that the HyperFrames plugin needs updating to reverse a video.
@@ -37,7 +37,7 @@ the original. Keep that reason even when all you send is a link and a code. For
> Then it takes about 20–50 minutes: I study the video frame by frame, rebuild every layer as a project you can edit,
> and check it against the original until it matches.
Run the `reverse.login_command` that `reverse start` printed. `npx hyperframes auth login` opens the browser and returns
Run the auth subcommand from `reverse.login_command` through the same launcher and release. `npx hyperframes auth login` opens the browser and returns
once they are signed in: run it in the same message and wait for it; when the browser does not open, it prints the
sign-in link: give it, with the reason. `npx hyperframes auth login --device` is what it prints where no browser can open
(a remote or headless terminal; plain `auth login` refuses there too): start it in the background, then send one
@@ -47,12 +47,12 @@ message with the reason, the link and the code, before you wait on anything: the
Reverse is part of Pro. Upgrading is the person's to do: never run a `billing` command yourself. Say why in one line and
give them the `reverse.upgrade_url` as a link, and the `reverse.subscribe_command` exactly as printed
(`npx hyperframes billing subscribe --feature reverse --skill reverse-any-video --session <id>`) for them to run instead
(`npx hyperframes billing subscribe --feature reverse --skill reverse-any-video --session <id>`) for them to run from their home directory
if they prefer: either opens the plans page, where they see the price and decide. Start nothing until they say they are
on Pro, then run `reverse start` again. For example:
> Reverse is part of HyperFrames Pro: it re-shoots the people in your video with HeyGen. Upgrade here: <upgrade_url>
> (or run `<subscribe_command>`), then tell me and I'll carry on.
> (or run `<subscribe_command>` from your home directory), then tell me and I'll carry on.
When `reverse start` refuses the run (it exits with an error whose `fix` is that command), do the same with its `fix`.
When `subscribe_command` and `upgrade_url` are `null` (or the refusal names no command), a plan can't be purchased right
@@ -72,12 +72,12 @@ or at the end of a run. `reverse start` and `auth status` are for the sign-in: d
A refused step prints what it needs and the command that fixes it (buy add-on credits, or pick a plan). Buying is the
person's to do: never run a `billing` command yourself. Shots are launched all at once, so several refuse together: wait
until every launched step has answered, add up what each refused step needs, and give them `npx hyperframes billing add-credits --needed <total> --skill reverse-any-video` to run once for that total, never one step at a time, with the
refusal's `url` (on an older CLI, the link in its `fix`) as a link. If any refusal prints no amount, the total is unknown:
refusal's `url` (on an older CLI, the link in its `fix`) as a link. Tell them to run the billing command from their home directory. If any refusal prints no amount, the total is unknown:
give plain `billing add-credits` once instead, for the whole run, never one per step. Either opens the add-on credits page, where they see the price. When they say their
balance is topped up, relaunch every refused step, keeping the plan whole.
> Three steps need 633 credits together and you have 30. Add credits here: <url> (or run
> `npx hyperframes billing add-credits --needed 633 --skill reverse-any-video`), then tell me and I'll pick up right where I stopped.
> `npx hyperframes billing add-credits --needed 633 --skill reverse-any-video` from your home directory), then tell me and I'll pick up right where I stopped.
## Handing it over