diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index f8b9a10b96..8ad1d55610 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -148,10 +148,13 @@ different program. This matters most for a project someone sent you. With standa runs the newest published CLI; in a plugin it runs the version the plugin pins. The pin counts 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. +starts with a dot (such as `.claude`) sits between them. 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. A project's `package.json` pin does not choose that release; the agent runs a pinned +release only when you ask for it. The launcher refuses a release older than its floor, whether a +plugin pins it or the agent selects it. The floor is the oldest release with the protections for +projects you receive from others. 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/utils/updateCheck.stalepin.test.ts b/packages/cli/src/utils/updateCheck.stalepin.test.ts index 7c6e941f55..5d64f47b98 100644 --- a/packages/cli/src/utils/updateCheck.stalepin.test.ts +++ b/packages/cli/src/utils/updateCheck.stalepin.test.ts @@ -97,7 +97,11 @@ describe("printStalePinNotice", () => { const mismatch = writes.filter((w) => w.includes("This is hyperframes 0.7.71")); expect(mismatch.length).toBe(2); expect(mismatch[0]).toContain("--cli-version 0.9.66"); - expect(mismatch[0]).toContain("start in your home folder, run npx hyperframes@0.9.66"); + // fails without the fix: the notice told an agent to run the release the project's own + // package.json named, as if the project could choose the CLI. + expect(mismatch[0]).toContain("an agent runs the pinned release only when the person asks"); + expect(mismatch[0]).not.toContain("to run the pinned release."); + expect(mismatch[0]).toContain("starting in your home folder, running 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.ts b/packages/cli/src/utils/updateCheck.ts index 43d8b35d6c..aa6e483ead 100644 --- a/packages/cli/src/utils/updateCheck.ts +++ b/packages/cli/src/utils/updateCheck.ts @@ -389,10 +389,12 @@ export function printStalePinNotice(cwd: string = process.cwd()): void { // A CLI older than the pin (e.g. a stale npx cache) misjudges every run, so this is never throttled. const newerPins = pins.filter((v) => isNewerSemver(v, VERSION)).sort(compareVersions); if (newerPins.length > 0) { + const pin = newerPins.at(-1); process.stderr.write( `\n This is hyperframes ${VERSION}, but this project pins hyperframes@${newerPins.join(", ")}.\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`, + ` A project's pin does not choose the CLI; an agent runs the pinned release only when the person asks for it.\n` + + ` To choose it, pass --cli-version ${pin} to the installed standalone skill launcher.\n` + + ` Without standalone skills, choose it by starting in your home folder, running npx hyperframes@${pin} with the desired command, and passing the project by absolute path.\n\n`, ); return; } diff --git a/scripts/check-core-skills.test.mjs b/scripts/check-core-skills.test.mjs index c8ae0aaedd..cdd91e0ca7 100644 --- a/scripts/check-core-skills.test.mjs +++ b/scripts/check-core-skills.test.mjs @@ -125,6 +125,18 @@ test("the launcher rules cover standalone installs and never send the agent to a assert.doesNotMatch(cli, /then use the wrapper/); }); +// fails without the fix: after a failed check the lifecycle reference sent the agent back to the +// release the project's own package.json pinned. +test("the project upgrade flow stops on a failed check instead of running the project's pin", () => { + const lifecycle = readFileSync( + new URL("../skills/hyperframes/references/skill-lifecycle.md", import.meta.url), + "utf8", + ); + assert.doesNotMatch(lifecycle, /continue with the original exact version/); + assert.match(lifecycle, /report the old version, the new version and the failure, and stop/); + assert.match(lifecycle, /unless the person asks for that release/); +}); + test("reads the registered commands, quoted or not", () => { const source = `const commandLoaders = {\n init: () => x,\n "catch-up": () => y,\n};`; assert.deepEqual([...registeredCommands(source)], ["init", "catch-up"]); diff --git a/skills-manifest.json b/skills-manifest.json index 998130fc73..ef8f19ed63 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -6,7 +6,7 @@ "files": 3 }, "hyperframes": { - "hash": "1db6e25a6ac15568", + "hash": "4c6990e1a05bfec1", "files": 81 }, "hyperframes-cli": { diff --git a/skills/hyperframes/references/plugin-installation.md b/skills/hyperframes/references/plugin-installation.md index 2f465c9dce..5079cb5747 100644 --- a/skills/hyperframes/references/plugin-installation.md +++ b/skills/hyperframes/references/plugin-installation.md @@ -22,6 +22,10 @@ launcher. 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. +Take an exact version from the person, from the version an upgrade moves the pins to, or from +`--cli-version latest --version`. Never take it from the project's own files: a `package.json` +pin does not choose the CLI unless the person asks for that release. The launcher refuses a release older than its floor, the oldest one with the +protections for received projects, and its error names the floor. 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 @@ -45,7 +49,7 @@ when all three of these hold: Otherwise the skills are a standalone install, and the launcher ignores any manifest there. Ignore it too, and follow the standalone rules above. The launcher refuses a manifest that -pins a release older than 0.9.34. +pins a release older than its floor. For a plugin installation, these rules also apply in every skill and reference: diff --git a/skills/hyperframes/references/skill-lifecycle.md b/skills/hyperframes/references/skill-lifecycle.md index d2559762cf..4e274446e1 100644 --- a/skills/hyperframes/references/skill-lifecycle.md +++ b/skills/hyperframes/references/skill-lifecycle.md @@ -47,7 +47,7 @@ The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `c 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: +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. The pin is the project's record, not a choice of CLI: do not pass a version read from the project to `--cli-version` unless the person asks for that release. When resuming a project whose scripts carry a pin, probe once before the first render-affecting command: ```bash node "/hyperframes/scripts/plugin-cli.mjs" --cli-version latest upgrade --project . --check @@ -60,4 +60,4 @@ node "/hyperframes/scripts/plugin-cli.mjs" --cli-version latest upgrade 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. +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 old version, the new version and the failure, and stop. Do not go back to the project's pinned release on your own, above all for a project received from someone else or of unknown origin. If the person explicitly asks to keep working on the original release, pass it with `--cli-version `. The launcher refuses a release older than its floor; relay that refusal, so the person can fix the project on the new release instead. diff --git a/skills/hyperframes/scripts/plugin-cli.mjs b/skills/hyperframes/scripts/plugin-cli.mjs index cd2da97675..154792b4f4 100644 --- a/skills/hyperframes/scripts/plugin-cli.mjs +++ b/skills/hyperframes/scripts/plugin-cli.mjs @@ -18,9 +18,10 @@ const manifests = [ "gemini-extension.json", ]; -// The first release whose bin moves into HYPERFRAMES_PLUGIN_CWD. An older one would run the -// command in the home folder. -const CLI_FLOOR = "0.9.34"; +// The oldest release this launcher starts, for a plugin pin or any standalone selection. It matches +// the oldest release the HyperFrames Desktop app ships, which has every protection for projects +// received from someone else, so a pin copied from a project never runs a CLI without them. +const CLI_FLOOR = "0.9.64"; export const STANDALONE_CLI = `hyperframes@>=${CLI_FLOOR}`; const realOrResolved = (path) => { @@ -74,7 +75,10 @@ function standaloneRelease(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.`); + if (isBelowFloor(value)) + throw new Error( + `HyperFrames ${value} lacks protections for received projects; this launcher runs ${CLI_FLOOR} or newer. Use --cli-version latest or ${CLI_FLOOR} or newer.`, + ); return value; } diff --git a/skills/hyperframes/scripts/plugin-cli.test.mjs b/skills/hyperframes/scripts/plugin-cli.test.mjs index 48e4972f42..c74847478d 100644 --- a/skills/hyperframes/scripts/plugin-cli.test.mjs +++ b/skills/hyperframes/scripts/plugin-cli.test.mjs @@ -64,7 +64,7 @@ test("a standalone install runs the newest CLI that moves into the project, and cwd: "/work/project", npmCwd: "/home/person", }); - assert.equal(STANDALONE_CLI, "hyperframes@>=0.9.34"); + assert.equal(STANDALONE_CLI, "hyperframes@>=0.9.64"); assert.equal(result.command, "npx"); assert.equal(result.cwd, "/home/person"); assert.deepEqual(result.args, ["--yes", STANDALONE_CLI, "skills", "update"]); @@ -97,7 +97,7 @@ test("standalone release selection keeps npm in the home folder and passes only }; for (const [release, args] of [ ["latest", ["upgrade", "--project", ".", "--check"]], - ["0.9.34+build-1", ["--version"]], + ["0.9.64+build-1", ["--version"]], ["1.0.0-rc.1", ["reverse", "start", "a b.mp4"]], ]) { const run = invocation(["--cli-version", release, ...args], options); @@ -121,8 +121,8 @@ test("standalone release selection keeps npm in the home folder and passes only /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/); + for (const release of ["0.9.33", "0.9.64-rc.1+build"]) { + assert.throws(() => invocation(["--cli-version", release], options), /0\.9\.64 or newer/); } assert.throws( () => invocation(["--cli-version", "latest"], { version: "1.2.3" }), @@ -130,6 +130,25 @@ test("standalone release selection keeps npm in the home folder and passes only ); }); +// fails without the fix: a standalone selection below the security floor ran, so a pin copied from a +// received project's package.json could start a CLI without the protections for received projects. +test("a standalone selection older than the floor is refused, by flag or by environment", () => { + const options = { version: null, platform: "linux", npmCwd: "/home/person", env: {} }; + const tooOld = /lacks protections for received projects; this launcher runs 0\.9\.64 or newer/; + for (const release of ["0.9.34", "0.9.40", "0.9.63"]) { + assert.throws(() => invocation(["--cli-version", release, "check"], options), tooOld); + const env = { HYPERFRAMES_STANDALONE_CLI_VERSION: release }; + assert.throws(() => invocation(["check"], { ...options, env }), tooOld); + assert.throws(() => invocation(["--script", "helper.mjs"], { ...options, env }), tooOld); + } + for (const release of ["latest", "0.9.64", "0.10.0"]) { + const env = { HYPERFRAMES_STANDALONE_CLI_VERSION: release }; + const spec = `hyperframes@${release}`; + assert.equal(invocation(["--cli-version", release, "check"], options).args[1], spec); + assert.equal(invocation(["check"], { ...options, env }).args[1], spec); + } +}); + 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); @@ -285,11 +304,11 @@ for (const [install, manifest, spec] of [ } test("rejects a plugin release older than the first one this launcher runs", (t) => { - for (const version of ["0.9.33", "0.9.34-alpha.1", "0.8.99"]) { + for (const version of ["0.9.33", "0.9.64-alpha.1", "0.8.99"]) { const { root } = fixture(t, "plugin.json", version); - assert.throws(() => pluginVersion(root), /this launcher runs 0\.9\.34 or newer/); + assert.throws(() => pluginVersion(root), /this launcher runs 0\.9\.64 or newer/); } - for (const version of ["0.9.34", "0.10.0", "1.0.0-beta.1"]) { + for (const version of ["0.9.64", "0.10.0", "1.0.0-beta.1"]) { const { root } = fixture(t, "plugin.json", version); assert.equal(pluginVersion(root), version); }