diff --git a/context7.json b/context7.json index 6157b2dc01..75973de7a0 100644 --- a/context7.json +++ b/context7.json @@ -10,6 +10,7 @@ "A composition is an HTML file whose root element has data-composition-id, data-width, data-height and data-duration. Timed elements use class=\"clip\" with data-start and data-duration.", "Register one paused GSAP root timeline per composition on window.__timelines[\"\"]. The runtime seeks it frame by frame, so never play it yourself.", "Rendering is deterministic: no Date.now(), no unseeded Math.random(), no network fetches at render time.", - "Check before rendering: `npx hyperframes lint`, `npx hyperframes check`, and `npx hyperframes snapshot --at 1,3,5` for frames. Make the MP4 with `npx hyperframes render --output video.mp4`." + "Run the CLI through the installed skills' launcher, `node /hyperframes/scripts/plugin-cli.mjs `, in the project. `npx hyperframes` inside a project can start a program the project supplies, so never run it in a project someone else made.", + "Check before rendering with the CLI's `lint`, `check`, and `snapshot --at 1,3,5` for frames. Make the MP4 with `render --output video.mp4`." ] } diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 5347619ed4..a493db7d72 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -139,6 +139,15 @@ Make any video by asking for it; the `/hyperframes` skill carries the contract a You can name a skill directly, but you do not need to memorize the names to start. +## How the agent runs the CLI + +The skills have your agent start the CLI through a launcher that ships with them, +`hyperframes/scripts/plugin-cli.mjs`, from your project folder. The launcher starts npm in +your home folder, so a project's `package.json`, `node_modules` or `.npmrc` cannot swap in a +different program. This matters most for a project someone sent you. With standalone skills it +runs the newest published CLI; in a plugin it runs the version the plugin pins. The agent runs +a project's own npm scripts only when you ask for one by name. + ## Install more only when you need it Install the complete published set deliberately with: diff --git a/scripts/check-core-skills.mjs b/scripts/check-core-skills.mjs index 50127b192a..ae15a3d674 100644 --- a/scripts/check-core-skills.mjs +++ b/scripts/check-core-skills.mjs @@ -11,19 +11,20 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), ".."); // Every installed skill's description is listed on every turn; an entry is read in full when it opens. export const DESCRIPTION_MAX = 320; -// Each budget carries +192 B for the usage beacon line (`beaconProblems`). +// Each budget carries +192 B for the usage beacon line (`beaconProblems`) and +160 B for the line +// that has every CLI command run through the launcher (`launcherProblems`). export const CORE_SKILLS = { // +128 B for the routing rows to the video rebuilds and to a reference's style, which only trigger when the entry hands them on. - hyperframes: 7488, + hyperframes: 7648, // +256 B for the `_meta.updateNotice` line: the agent relays it, the person updates. - "hyperframes-cli": 7616, - "hyperframes-registry": 5312, - "media-use": 5312, - figma: 7360, - slideshow: 5312, - "remotion-to-hyperframes": 5312, - "reverse-any-video": 5312, - "style-sampling": 5312, + "hyperframes-cli": 7776, + "hyperframes-registry": 5472, + "media-use": 5472, + figma: 7520, + slideshow: 5472, + "remotion-to-hyperframes": 5472, + "reverse-any-video": 5472, + "style-sampling": 5472, }; /** @param {string} skill */ @@ -95,6 +96,18 @@ export function beaconProblems(skill, content) { : [`${skill}/SKILL.md does not run \`npx hyperframes events --skill=${skill}\` as it starts`]; } +/** The line that has the skill run every CLI command through the launcher, never a project's npx. */ +export const LAUNCHER_LINE = "means `node /hyperframes/scripts/plugin-cli.mjs `"; + +/** @param {string} skill @param {string} content */ +export function launcherProblems(skill, content) { + const beacon = content.indexOf(beaconCommand(skill)); + const launcher = content.indexOf(LAUNCHER_LINE); + return launcher !== -1 && (beacon === -1 || launcher < beacon) + ? [] + : [`${skill}/SKILL.md does not run the CLI through the launcher before its beacon`]; +} + /** @param {string} root */ export function checkCoreSkills(root = REPO_ROOT) { const commands = registeredCommands(readFileSync(join(root, "packages/cli/src/cli.ts"), "utf8")); @@ -102,7 +115,12 @@ export function checkCoreSkills(root = REPO_ROOT) { const file = skillFile(skill, root); const content = readFileSync(file, "utf8"); const names = maxBytes === null ? [] : nameProblems(skill, content, dirname(file), commands); - return [...sizeProblems(skill, content, maxBytes), ...names, ...beaconProblems(skill, content)]; + return [ + ...sizeProblems(skill, content, maxBytes), + ...names, + ...beaconProblems(skill, content), + ...launcherProblems(skill, content), + ]; }); } diff --git a/scripts/check-core-skills.test.mjs b/scripts/check-core-skills.test.mjs index a1859efec5..c8ae0aaedd 100644 --- a/scripts/check-core-skills.test.mjs +++ b/scripts/check-core-skills.test.mjs @@ -5,6 +5,8 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { beaconProblems, + launcherProblems, + LAUNCHER_LINE, checkCoreSkills, descriptionOf, missingPaths, @@ -102,6 +104,27 @@ test("flags a skill that never reports its own run", () => { ); }); +// fails without the fix: the skills ran `npx hyperframes` in the project, so npm could start the +// project's own `hyperframes` bin, node_modules/.bin copy or .npmrc settings. +test("flags a skill whose beacon runs before it names the launcher", () => { + const beacon = "Run `npx hyperframes events --skill=slideshow` first."; + const rule = `Every \`npx hyperframes \` ${LAUNCHER_LINE}.`; + assert.deepEqual(launcherProblems("slideshow", `${rule}\n${beacon}`), []); + assert.equal(launcherProblems("slideshow", beacon).length, 1); + assert.equal(launcherProblems("slideshow", `${beacon}\n${rule}`).length, 1); +}); + +test("the launcher rules cover standalone installs and never send the agent to a project wrapper", () => { + const rules = readFileSync( + new URL("../skills/hyperframes/references/plugin-installation.md", import.meta.url), + "utf8", + ); + assert.match(rules, /## Standalone skill installs/); + assert.match(rules, /Do not run\s+`npx hyperframes` in the project directly/); + const cli = readFileSync(new URL("../skills/hyperframes-cli/SKILL.md", import.meta.url), "utf8"); + assert.doesNotMatch(cli, /then use the wrapper/); +}); + 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 3cb148cd20..c9236d179f 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -2,39 +2,39 @@ "source": "heygen-com/hyperframes", "skills": { "figma": { - "hash": "aac6a22fd9f15a86", + "hash": "674455e54a2df3f5", "files": 3 }, "hyperframes": { - "hash": "6be2c44bf6fc87de", + "hash": "f3c1d8e7a6668bd9", "files": 80 }, "hyperframes-cli": { - "hash": "4ecb93b795a81101", + "hash": "a1b8be77ce157ce4", "files": 13 }, "hyperframes-registry": { - "hash": "a032ccc5c7948ac2", + "hash": "da95c563e9698001", "files": 13 }, "media-use": { - "hash": "fe57eec6df8af903", + "hash": "031ac4bf2de6cd34", "files": 125 }, "remotion-to-hyperframes": { - "hash": "072dfcb3fe917d67", + "hash": "a9a3672260f402f1", "files": 76 }, "reverse-any-video": { - "hash": "233fe054956345f6", + "hash": "addcf365498eb4aa", "files": 5 }, "slideshow": { - "hash": "1ab359d60230a336", + "hash": "c022f24e53ce376a", "files": 2 }, "style-sampling": { - "hash": "b131690aa8a7c47f", + "hash": "46f7b0d23385baf3", "files": 2 } } diff --git a/skills/figma/SKILL.md b/skills/figma/SKILL.md index 2978b51309..5d491eb58a 100644 --- a/skills/figma/SKILL.md +++ b/skills/figma/SKILL.md @@ -3,7 +3,7 @@ name: figma description: Bring Figma into a HyperFrames video - rendered assets, brand tokens, components, storyboard frames as reconstructed motion (frames read as states, not slides), shaders and connector-assisted motion. Use when the person pastes a figma.com link or asks to use a Figma design, frame, logo or brand. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=figma` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md index d7ce8f536e..f761550c7b 100644 --- a/skills/hyperframes-cli/SKILL.md +++ b/skills/hyperframes-cli/SKILL.md @@ -3,13 +3,13 @@ name: hyperframes-cli description: HyperFrames CLI - scaffold, check frames, edit timelines, preview, render, share and project history; read JSON and recover from failures. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=hyperframes-cli` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. # HyperFrames CLI -Run `npx hyperframes ` unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero. +Run `npx hyperframes ` as above, never a project's own scripts or wrapper unless the person names that command. It needs Node.js 22+ and FFmpeg. Every command has `--help`; most take `--json`, and a failure prints `✗ …`, a `Fix:` line and exits non-zero. A `--json` result may carry `_meta.updateNotice`: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide. diff --git a/skills/hyperframes-registry/SKILL.md b/skills/hyperframes-registry/SKILL.md index f03773cfcd..56099a2502 100644 --- a/skills/hyperframes-registry/SKILL.md +++ b/skills/hyperframes-registry/SKILL.md @@ -3,7 +3,7 @@ name: hyperframes-registry description: About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=hyperframes-registry` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index e711653cd6..0d05ef59b3 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -3,7 +3,7 @@ name: hyperframes description: Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=hyperframes` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/hyperframes/references/plugin-installation.md b/skills/hyperframes/references/plugin-installation.md index 89262edab7..89a7405bba 100644 --- a/skills/hyperframes/references/plugin-installation.md +++ b/skills/hyperframes/references/plugin-installation.md @@ -1,12 +1,36 @@ -# Running from an installed plugin +# Running the HyperFrames CLI + +`` is the folder that holds the loaded skill's folder. Every skill and reference writes +the CLI as `npx hyperframes` (or bare `hyperframes`). Run each of those commands as: + +```bash +node "/hyperframes/scripts/plugin-cli.mjs" +``` + +Run it in the user's project directory, never in the skills directory. npm starts in the home +folder, so the project's `package.json`, `node_modules` and `.npmrc` cannot choose the CLI or the +registry; the CLI then moves into the project and works there. This holds for every command, +including the usage beacon, and for a project the person received from someone else. Do not run +`npx hyperframes` in the project directly, and do not run a project's own scripts or wrappers in +its place unless the person asks for that command by name. + +For bundled Node helpers, use the same launcher with +`--script `. Helpers that call the CLI then run it through the +launcher. + +## Standalone skill installs + +Without a plugin manifest, the launcher runs the newest published CLI. The person installs and +updates standalone skills with `npx hyperframes skills update`. + +## Plugin installs Check the directory two levels above the loaded `SKILL.md` for `plugin.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, or `.cursor-plugin/plugin.json` identifying `hyperframes`, or a Gemini extension manifest. -That directory is ``. If none exists, this is a standalone skill -install; run `npx hyperframes` directly. +That directory is ``, and `` is `/skills`. -For a plugin installation, these rules apply in every skill and reference: +For a plugin installation, these rules also apply in every skill and reference: - Do not run `hyperframes skills update`, `skills check`, or `npx skills add`. The agent's plugin manager owns installation and updates. Read the skill at @@ -14,27 +38,14 @@ For a plugin installation, these rules apply in every skill and reference: of downloading a different release. Resolve all skill references inside this bundle, even if a standalone copy is also installed. Claude exposes the router as `/hyperframes:hyperframes`; other clients may expose `/hyperframes`. -- Replace `npx hyperframes` (or bare `hyperframes`) in command examples with: - - ```bash - node "/skills/hyperframes/scripts/plugin-cli.mjs" - ``` - - Run in the user's project directory, never in the plugin directory. The launcher - selects the manifest's CLI version and disables automatic standalone skill +- The launcher selects the manifest's CLI version and disables automatic standalone skill installation, including during `init`. The first call may download that exact - CLI version through npm. npm runs from the home folder, so the project's - `node_modules`, `package.json` and `.npmrc` cannot choose the CLI; the CLI then - works in the project. A download failure is an error, not permission to use + CLI version through npm. A download failure is an error, not permission to use latest. Existing project dependency files and lockfiles must not be overwritten to match the plugin; surface a runtime incompatibility before changing them. - -- For bundled Node helpers, use the same - launcher with `--script `. This passes the - release version to their dependency loader, and helpers that call the CLI run - it through the launcher. External providers, registry - downloads, and existing project dependencies have their own versions; a plugin - version alone does not freeze those inputs. +- For bundled Node helpers, the launcher also passes the release version to their + dependency loader. External providers, registry downloads, and existing project + dependencies have their own versions; a plugin version alone does not freeze those inputs. - Treat the plugin directory as read-only. Put outputs and temporary work in the project or a temporary directory. Pass this plugin root and launcher convention to any delegated agent so it does not fall back to global skills. diff --git a/skills/hyperframes/scripts/plugin-cli.mjs b/skills/hyperframes/scripts/plugin-cli.mjs index 1a76a28021..99b461a7e5 100644 --- a/skills/hyperframes/scripts/plugin-cli.mjs +++ b/skills/hyperframes/scripts/plugin-cli.mjs @@ -1,5 +1,6 @@ #!/usr/bin/env node -// Run from the user's project; locate the release from this installed file. +// Every skill starts the CLI through this file, from the user's project. A plugin install pins the +// release in its manifest; a standalone skill install takes the newest release from npm. import "./lib/windows-exe-search.mjs"; import { spawnSync } from "node:child_process"; import { existsSync, readFileSync } from "node:fs"; @@ -30,11 +31,13 @@ export function pluginVersion(pluginRoot = root) { } return manifest.version; } - throw new Error( - "No HyperFrames plugin manifest found. This is a standalone skill install; run `npx hyperframes` directly.", - ); + return undefined; } +// The first release whose bin moves into HYPERFRAMES_PLUGIN_CWD. An older one would run the +// command in the home folder. +export const STANDALONE_CLI = "hyperframes@>=0.9.34"; + // npm takes the package, bin links and .npmrc from the folder it starts in, so npx starts // in the home folder and the CLI moves into the project before it runs a command. A shared // folder such as the temp folder is no substitute, so there is no fallback. @@ -56,24 +59,26 @@ export function invocation( launcher = fileURLToPath(import.meta.url), } = {}, ) { - if (args[0] === "skills") + if (version && args[0] === "skills") throw new Error( "Bundled skills are release-managed; the person updates HyperFrames through their agent's plugin manager.", ); - const childEnv = { - ...env, - HYPERFRAMES_SKIP_SKILLS: "1", - HYPERFRAMES_SKILL_PKG_VERSION: version, - HYPERFRAMES_PLUGIN_VERSION: version, - HYPERFRAMES_NO_UPDATE_CHECK: "1", - }; + const childEnv = version + ? { + ...env, + HYPERFRAMES_SKIP_SKILLS: "1", + HYPERFRAMES_SKILL_PKG_VERSION: version, + HYPERFRAMES_PLUGIN_VERSION: version, + HYPERFRAMES_NO_UPDATE_CHECK: "1", + } + : { ...env }; if (args[0] === "--script") { 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 }; return { command: node, args: args.slice(1), env, cwd }; } - const cliArgs = ["--yes", `hyperframes@${version}`, ...args]; + const cliArgs = ["--yes", version ? `hyperframes@${version}` : 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 d2c39c4b52..50f8ca72ae 100644 --- a/skills/hyperframes/scripts/plugin-cli.test.mjs +++ b/skills/hyperframes/scripts/plugin-cli.test.mjs @@ -13,14 +13,16 @@ import { delimiter, join } from "node:path"; import { tmpdir } from "node:os"; import { test } from "node:test"; import { pathToFileURL } from "node:url"; -import { invocation, npmFolder, pluginVersion } from "./plugin-cli.mjs"; +import { invocation, npmFolder, pluginVersion, STANDALONE_CLI } from "./plugin-cli.mjs"; function fixture(t, manifest = "plugin.json", version = "1.2.3") { const root = mkdtempSync(join(tmpdir(), "hf-plugin-")); t.after(() => rmSync(root, { recursive: true, force: true })); mkdirSync(join(root, "skills/hyperframes/scripts/lib"), { recursive: true }); - mkdirSync(join(root, manifest, ".."), { recursive: true }); - writeFileSync(join(root, manifest), JSON.stringify({ name: "hyperframes", version })); + if (manifest) { + mkdirSync(join(root, manifest, ".."), { recursive: true }); + writeFileSync(join(root, manifest), JSON.stringify({ name: "hyperframes", version })); + } const launcher = join(root, "skills/hyperframes/scripts/plugin-cli.mjs"); copyFileSync(new URL("./plugin-cli.mjs", import.meta.url), launcher); for (const lib of ["main-module.mjs", "windows-exe-search.mjs"]) { @@ -45,11 +47,26 @@ for (const manifest of [ }); } -test("rejects missing and floating plugin versions", (t) => { +test("rejects a floating plugin version and reads no manifest as a standalone install", (t) => { const { root } = fixture(t, "plugin.json", "latest"); assert.throws(() => pluginVersion(root), /Invalid HyperFrames plugin release/); rmSync(join(root, "plugin.json")); - assert.throws(() => pluginVersion(root), /No HyperFrames plugin manifest/); + assert.equal(pluginVersion(root), undefined); +}); + +test("a standalone install runs the newest CLI that moves into the project, and manages its own skills", () => { + const result = invocation(["skills", "update"], { + version: null, + platform: "darwin", + env: { PATH: "/bin" }, + cwd: "/work/project", + npmCwd: "/home/person", + }); + assert.equal(STANDALONE_CLI, "hyperframes@>=0.9.34"); + assert.equal(result.command, "npx"); + assert.equal(result.cwd, "/home/person"); + assert.deepEqual(result.args, ["--yes", STANDALONE_CLI, "skills", "update"]); + assert.deepEqual(result.env, { PATH: "/bin", HYPERFRAMES_PLUGIN_CWD: "/work/project" }); }); test("pins CLI, suppresses standalone refresh, preserves unrelated environment", () => { @@ -155,41 +172,48 @@ test("on Windows, a helper and the programs it starts skip the working-directory assert.equal(stdoutOf(run({ ...env, NoDefaultCurrentDirectoryInExePath: "yes" })), "yes"); }); -test( - "npx starts outside the project, so its packages, bin links and .npmrc cannot pick the CLI", - { skip: process.platform === "win32" }, - (t) => { - const { root, launcher } = fixture(t); - const home = join(root, "home"); - const bin = join(root, "bin"); - const project = join(root, "user project"); - mkdirSync(home); - mkdirSync(bin); - mkdirSync(join(project, "node_modules/.bin"), { recursive: true }); - writeFileSync( - join(project, ".npmrc"), - "registry=http://127.0.0.1:9/\nscript-shell=/bin/false\n", - ); - writeFileSync(join(project, "package.json"), '{"name":"hyperframes","bin":"x.js"}'); - writeFileSync(join(project, "node_modules/.bin/hyperframes"), "#!/bin/sh\n", { mode: 0o755 }); - writeFileSync( - join(bin, "npx"), - `#!${process.execPath}\nconsole.log(JSON.stringify({cwd:process.cwd(),args:process.argv.slice(2),project:process.env.HYPERFRAMES_PLUGIN_CWD}));`, - { mode: 0o755 }, - ); - const result = spawnSync(process.execPath, [launcher, "--version"], { - cwd: project, - encoding: "utf8", - env: { ...process.env, HOME: home, PATH: `${bin}${delimiter}${process.env.PATH}` }, - }); - assert.equal(result.status, 0, result.stderr); - assert.deepEqual(JSON.parse(result.stdout), { - cwd: realpathSync(home), - args: ["--yes", "hyperframes@1.2.3", "--version"], - project: realpathSync(project), - }); - }, -); +// fails without the fix: a standalone install had no launcher, so the skills ran `npx hyperframes` +// in the project and npm took the project's bin, node_modules/.bin or .npmrc. +for (const [install, manifest, spec] of [ + ["plugin", "plugin.json", "hyperframes@1.2.3"], + ["standalone", null, STANDALONE_CLI], +]) { + test( + `${install} install: npx starts outside the project, so its packages, bin links and .npmrc cannot pick the CLI`, + { skip: process.platform === "win32" }, + (t) => { + const { root, launcher } = fixture(t, manifest); + const home = join(root, "home"); + const bin = join(root, "bin"); + const project = join(root, "user project"); + mkdirSync(home); + mkdirSync(bin); + mkdirSync(join(project, "node_modules/.bin"), { recursive: true }); + writeFileSync( + join(project, ".npmrc"), + "registry=http://127.0.0.1:9/\nscript-shell=/bin/false\n", + ); + writeFileSync(join(project, "package.json"), '{"name":"hyperframes","bin":"x.js"}'); + writeFileSync(join(project, "node_modules/.bin/hyperframes"), "#!/bin/sh\n", { mode: 0o755 }); + writeFileSync( + join(bin, "npx"), + `#!${process.execPath}\nconsole.log(JSON.stringify({cwd:process.cwd(),args:process.argv.slice(2),project:process.env.HYPERFRAMES_PLUGIN_CWD}));`, + { mode: 0o755 }, + ); + const result = spawnSync(process.execPath, [launcher, "--version"], { + cwd: project, + encoding: "utf8", + env: { ...process.env, HOME: home, PATH: `${bin}${delimiter}${process.env.PATH}` }, + }); + assert.equal(result.status, 0, result.stderr); + assert.deepEqual(JSON.parse(result.stdout), { + cwd: realpathSync(home), + args: ["--yes", spec, "--version"], + project: realpathSync(project), + }); + }, + ); +} test("starts npx in the home folder and never falls back to a shared folder", () => { assert.equal( diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md index d9cbb02fbb..80ced5e1d0 100644 --- a/skills/media-use/SKILL.md +++ b/skills/media-use/SKILL.md @@ -3,7 +3,7 @@ name: media-use description: Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=media-use` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/remotion-to-hyperframes/SKILL.md b/skills/remotion-to-hyperframes/SKILL.md index df4fb15cf8..d4cce653a5 100644 --- a/skills/remotion-to-hyperframes/SKILL.md +++ b/skills/remotion-to-hyperframes/SKILL.md @@ -3,7 +3,7 @@ name: remotion-to-hyperframes description: Bring existing video code or footage into HyperFrames and verify it frame by frame against the original - Remotion first, also Motion Canvas, Lottie, Three.js, p5.js, canvas or plain HTML/CSS animation, or renders from Manim, After Effects or Blender. Use to port, convert, migrate or reuse work made with another tool. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=remotion-to-hyperframes` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/reverse-any-video/SKILL.md b/skills/reverse-any-video/SKILL.md index ad95dd9d8d..7d39b7d462 100644 --- a/skills/reverse-any-video/SKILL.md +++ b/skills/reverse-any-video/SKILL.md @@ -3,7 +3,7 @@ name: reverse-any-video description: Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=reverse-any-video` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/slideshow/SKILL.md b/skills/slideshow/SKILL.md index b0f0c0cc32..03b76f2c81 100644 --- a/skills/slideshow/SKILL.md +++ b/skills/slideshow/SKILL.md @@ -3,7 +3,7 @@ name: slideshow description: Build a HyperFrames slideshow to present live - slides, fragment reveals, branching hotspots and presenter mode with speaker notes, served by `hyperframes present` - or turn an existing page into one. Use when the person wants a deck or presentation rather than a rendered video. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=slideshow` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out. diff --git a/skills/style-sampling/SKILL.md b/skills/style-sampling/SKILL.md index 7b5f93401c..9331df651b 100644 --- a/skills/style-sampling/SKILL.md +++ b/skills/style-sampling/SKILL.md @@ -3,7 +3,7 @@ name: style-sampling description: Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video. --- -**Plugin installs:** Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md). +**Running the CLI:** every `npx hyperframes ` here, the beacon included, means `node /hyperframes/scripts/plugin-cli.mjs ` run in the project, where `` holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)). **Usage beacon:** run `npx hyperframes events --skill=style-sampling` once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out.