diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index ea2ae142df..f8b9a10b96 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -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 ` 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 diff --git a/packages/cli/src/commands/doctor.install.test.ts b/packages/cli/src/commands/doctor.install.test.ts index f133466cf1..a702cecc40 100644 --- a/packages/cli/src/commands/doctor.install.test.ts +++ b/packages/cli/src/commands/doctor.install.test.ts @@ -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"); diff --git a/packages/cli/src/commands/reverse/start.test.ts b/packages/cli/src/commands/reverse/start.test.ts index d2140a9897..7f96cec5a7 100644 --- a/packages/cli/src/commands/reverse/start.test.ts +++ b/packages/cli/src/commands/reverse/start.test.ts @@ -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[]); @@ -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/, ), }, }); diff --git a/packages/cli/src/commands/reverse/start.ts b/packages/cli/src/commands/reverse/start.ts index 1305b87e08..fa9b3dc07e 100644 --- a/packages/cli/src/commands/reverse/start.ts +++ b/packages/cli/src/commands/reverse/start.ts @@ -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} \`. 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 } { diff --git a/packages/cli/src/commands/update.test.ts b/packages/cli/src/commands/update.test.ts index 6702191b49..fb0131141a 100644 --- a/packages/cli/src/commands/update.test.ts +++ b/packages/cli/src/commands/update.test.ts @@ -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"], ])( diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.ts index 2b1923c351..8b673009db 100644 --- a/packages/cli/src/commands/upgrade.ts +++ b/packages/cli/src/commands/upgrade.ts @@ -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( diff --git a/packages/cli/src/registry/compatibility.test.ts b/packages/cli/src/registry/compatibility.test.ts index 26edaf9ee9..dfe0644ab7 100644 --- a/packages/cli/src/registry/compatibility.test.ts +++ b/packages/cli/src/registry/compatibility.test.ts @@ -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", () => { diff --git a/packages/cli/src/registry/compatibility.ts b/packages/cli/src/registry/compatibility.ts index c935d83ff6..e7a02d1809 100644 --- a/packages/cli/src/registry/compatibility.ts +++ b/packages/cli/src/registry/compatibility.ts @@ -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.", }; } diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index b369b12d2c..c86d98873a 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -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 # 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 diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index b369b12d2c..c86d98873a 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -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 # 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 diff --git a/packages/cli/src/utils/homeCliCommand.ts b/packages/cli/src/utils/homeCliCommand.ts new file mode 100644 index 0000000000..461c07603b --- /dev/null +++ b/packages/cli/src/utils/homeCliCommand.ts @@ -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})`; +} diff --git a/packages/cli/src/utils/installerDetection.test.ts b/packages/cli/src/utils/installerDetection.test.ts index e09ac053a7..3f29aafa89 100644 --- a/packages/cli/src/utils/installerDetection.test.ts +++ b/packages/cli/src/utils/installerDetection.test.ts @@ -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, }); }); diff --git a/packages/cli/src/utils/installerDetection.ts b/packages/cli/src/utils/installerDetection.ts index c38e13aa3d..b848c76402 100644 --- a/packages/cli/src/utils/installerDetection.ts +++ b/packages/cli/src/utils/installerDetection.ts @@ -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(["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), + }; } diff --git a/packages/cli/src/utils/updateCheck.stalepin.test.ts b/packages/cli/src/utils/updateCheck.stalepin.test.ts index fe8f67ce78..7c6e941f55 100644 --- a/packages/cli/src/utils/updateCheck.stalepin.test.ts +++ b/packages/cli/src/utils/updateCheck.stalepin.test.ts @@ -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"); }); diff --git a/packages/cli/src/utils/updateCheck.test.ts b/packages/cli/src/utils/updateCheck.test.ts index 6a41a18f69..3fdbb1b24e 100644 --- a/packages/cli/src/utils/updateCheck.test.ts +++ b/packages/cli/src/utils/updateCheck.test.ts @@ -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, ); } }, diff --git a/packages/cli/src/utils/updateCheck.ts b/packages/cli/src/utils/updateCheck.ts index fe354323e9..43d8b35d6c 100644 --- a/packages/cli/src/utils/updateCheck.ts +++ b/packages/cli/src/utils/updateCheck.ts @@ -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`, ); } diff --git a/scripts/lint-skills.test.mjs b/scripts/lint-skills.test.mjs index 2c97bbd0d8..195f73d0d5 100644 --- a/scripts/lint-skills.test.mjs +++ b/scripts/lint-skills.test.mjs @@ -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 = "\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 "/hyperframes/scripts/plugin-cli.mjs" --cli-version latest --version`.', + ), + [], + ); +}); diff --git a/scripts/lint-skills.ts b/scripts/lint-skills.ts index 3f72c978b9..0b5eb0ced5 100644 --- a/scripts/lint-skills.ts +++ b/scripts/lint-skills.ts @@ -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, 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++; diff --git a/skills-manifest.json b/skills-manifest.json index 9263002ddc..6d5e4578a0 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -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": { diff --git a/skills/hyperframes-cli/references/upgrade-info-misc.md b/skills/hyperframes-cli/references/upgrade-info-misc.md index 67ade4d954..53a58488e5 100644 --- a/skills/hyperframes-cli/references/upgrade-info-misc.md +++ b/skills/hyperframes-cli/references/upgrade-info-misc.md @@ -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@…` in `/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@…` in `/package.json` (default cwd) to npm-latest. With standalone skills, use `node "/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 diff --git a/skills/hyperframes/references/plugin-installation.md b/skills/hyperframes/references/plugin-installation.md index 78d64f4ff9..2f465c9dce 100644 --- a/skills/hyperframes/references/plugin-installation.md +++ b/skills/hyperframes/references/plugin-installation.md @@ -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 ` before the command. +Use the launcher from the loaded skill installation for commands shown in CLI output, too. +For example, run `node "/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 diff --git a/skills/hyperframes/references/skill-lifecycle.md b/skills/hyperframes/references/skill-lifecycle.md index 9192258c89..d2559762cf 100644 --- a/skills/hyperframes/references/skill-lifecycle.md +++ b/skills/hyperframes/references/skill-lifecycle.md @@ -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@` 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 "/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 "/hyperframes/scripts/plugin-cli.mjs" --cli-version latest upgrade --project . +node "/hyperframes/scripts/plugin-cli.mjs" --cli-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. diff --git a/skills/hyperframes/scripts/plugin-cli.mjs b/skills/hyperframes/scripts/plugin-cli.mjs index 8093290b2a..cd2da97675 100644 --- a/skills/hyperframes/scripts/plugin-cli.mjs +++ b/skills/hyperframes/scripts/plugin-cli.mjs @@ -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 }; diff --git a/skills/hyperframes/scripts/plugin-cli.test.mjs b/skills/hyperframes/scripts/plugin-cli.test.mjs index 89ff02d3d7..48e4972f42 100644 --- a/skills/hyperframes/scripts/plugin-cli.test.mjs +++ b/skills/hyperframes/scripts/plugin-cli.test.mjs @@ -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", diff --git a/skills/reverse-any-video/references/start.md b/skills/reverse-any-video/references/start.md index d5ea957e6e..cf923a94a1 100644 --- a/skills/reverse-any-video/references/start.md +++ b/skills/reverse-any-video/references/start.md @@ -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@ `, 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 "/hyperframes/scripts/plugin-cli.mjs" --cli-version latest --version` once and run `reverse start` again and every later +command of this run as `node "/hyperframes/scripts/plugin-cli.mjs" --cli-version `, 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 `) for them to run instead +(`npx hyperframes billing subscribe --feature reverse --skill reverse-any-video --session `) 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: -> (or run ``), then tell me and I'll carry on. +> (or run `` 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 --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: (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