Skip to content

Write HTML. Render video. Built for agents.

fix(skills): skill scripts run through a symlinked skills dir and agents keep long renders alive (#5396)

Miguel Ángelf46033d04898
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 1de29db941..c9eab88f07 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -71,8 +71,9 @@ npx hyperframes render -o output.mp4
npx hyperframes render -c ./my-composition.html -o output.mp4
```
-Set `HYPERFRAMES_RENDER_DETACHED=1` when starting a render with `nohup` or
-`disown` so it keeps running after the invoking shell exits.
+A render stops when the process that started it exits. To keep one running after
+its launcher exits, set `HYPERFRAMES_RENDER_DETACHED=1` and start it in its own
+process group, e.g. `bash -c 'set -m; HYPERFRAMES_RENDER_DETACHED=1 npx hyperframes render -o out.mp4 < /dev/null > render.log 2>&1 &'`.
### `publish`
diff --git a/packages/cli/src/media-use/lib/cube-validate.mjs b/packages/cli/src/media-use/lib/cube-validate.mjs
index 4aef33ac03..d8ca4c0654 100644
--- a/packages/cli/src/media-use/lib/cube-validate.mjs
+++ b/packages/cli/src/media-use/lib/cube-validate.mjs
@@ -5,8 +5,7 @@
// parser cases to catch drift in accepted .cube files before freezing them.
import { readFileSync } from "node:fs";
-import { resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
+import { isMainModule } from "./main-module.mjs";
export const DEFAULT_MAX_CUBE_LUT_SIZE = 64;
@@ -193,6 +192,6 @@ function main(argv) {
console.log(`ok: LUT_3D_SIZE ${result.size}`);
}
-if (process.argv[1] && resolvePath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
main(process.argv);
}
diff --git a/packages/cli/src/media-use/lib/main-module.mjs b/packages/cli/src/media-use/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/packages/cli/src/media-use/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/scripts/generate-skill-module-copies.mjs b/scripts/generate-skill-module-copies.mjs
index 6c72a39e2a..18902a63a5 100644
--- a/scripts/generate-skill-module-copies.mjs
+++ b/scripts/generate-skill-module-copies.mjs
@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
@@ -17,6 +17,15 @@ export const skillModuleCopies = [
"skills/media-use/audio/scripts/lib/host-audio.mjs",
workflows.map((skill) => `skills/${skill}/scripts/lib/host-audio.mjs`),
],
+ [
+ "skills/hyperframes/scripts/lib/main-module.mjs",
+ [
+ ...[...workflows, "general-video", "hyperframes-audio", "media-use/audio"].map(
+ (skill) => `skills/${skill}/scripts/lib/main-module.mjs`,
+ ),
+ "packages/cli/src/media-use/lib/main-module.mjs",
+ ],
+ ],
[
"skills/hyperframes/scripts/lib/frame-packets-core.mjs",
[...workflows, "general-video"].map(
@@ -40,7 +49,7 @@ export function generateSkillModuleCopies({ check = false } = {}) {
});
}
-if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
const drifted = generateSkillModuleCopies({ check: process.argv.includes("--check") });
if (drifted.length) throw new Error("Regenerate skill module copies: " + drifted.join(", "));
console.log("Skill module copies are in sync");
diff --git a/skills-manifest.json b/skills-manifest.json
index 2e9f574955..8bc3b14675 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -6,31 +6,31 @@
"files": 144
},
"faceless-explainer": {
- "hash": "1f10a69e0f879698",
- "files": 28
+ "hash": "fe5ac45ac43dee42",
+ "files": 29
},
"figma": {
"hash": "f8cf9f2c78ea8374",
"files": 2
},
"general-video": {
- "hash": "7194a47a82647a88",
- "files": 5
+ "hash": "d654955cbceaf3c7",
+ "files": 6
},
"hyperframes": {
- "hash": "589ae40d15628917",
- "files": 29
+ "hash": "7995559a6ae64821",
+ "files": 31
},
"hyperframes-animation": {
"hash": "9370b856259f4586",
"files": 122
},
"hyperframes-audio": {
- "hash": "e96de47ed2e6097a",
- "files": 7
+ "hash": "e815fcede8a676b9",
+ "files": 8
},
"hyperframes-cli": {
- "hash": "5076477812cf2c37",
+ "hash": "5a0f95b33cc1e8ad",
"files": 11
},
"hyperframes-core": {
@@ -54,8 +54,8 @@
"files": 1
},
"media-use": {
- "hash": "c8800249da2d1ce6",
- "files": 109
+ "hash": "206565a9b0cc6ac2",
+ "files": 110
},
"motion-graphics": {
"hash": "6db77031ad839f6a",
@@ -66,12 +66,12 @@
"files": 169
},
"pr-to-video": {
- "hash": "88f4c68788eaba9e",
- "files": 34
+ "hash": "49dfd8081dfb3417",
+ "files": 35
},
"product-launch-video": {
- "hash": "76149a9f3514626e",
- "files": 36
+ "hash": "39c46bb51002d67c",
+ "files": 37
},
"remotion-to-hyperframes": {
"hash": "d02be65b7f3f4a63",
diff --git a/skills/faceless-explainer/scripts/captions.mjs b/skills/faceless-explainer/scripts/captions.mjs
index b2e2fa0168..e4abf3eec2 100644
--- a/skills/faceless-explainer/scripts/captions.mjs
+++ b/skills/faceless-explainer/scripts/captions.mjs
@@ -35,10 +35,10 @@ import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
import { parseStoryboard } from "./lib/storyboard.mjs";
import { captionBand, parseFormat } from "./lib/dimensions.mjs";
import { parseColors, parseFonts, semanticColors } from "./lib/tokens.mjs";
+import { isMainModule } from "./lib/main-module.mjs";
const flag = (argv, name, def) => {
const i = argv.indexOf(`--${name}`);
@@ -512,7 +512,7 @@ function buildCaptionsHtml(groups, total, W, H) {
`;
}
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
const sub = process.argv[2];
if (sub === "build" || sub === undefined) runBuild(process.argv.slice(sub === "build" ? 3 : 2));
else {
diff --git a/skills/faceless-explainer/scripts/lib/frame-packets-core.mjs b/skills/faceless-explainer/scripts/lib/frame-packets-core.mjs
index d165088ff8..d4cfbecba1 100644
--- a/skills/faceless-explainer/scripts/lib/frame-packets-core.mjs
+++ b/skills/faceless-explainer/scripts/lib/frame-packets-core.mjs
@@ -2,16 +2,8 @@
// Workflow wrappers supply resource paths and workflow-specific sections.
// The role combines the shared worker contract with the workflow delta.
-import {
- existsSync,
- mkdirSync,
- readFileSync,
- readdirSync,
- realpathSync,
- writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
export function field(block, name) {
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
@@ -160,17 +152,7 @@ export function flag(argv, name, fallback) {
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
- } catch {
- return false;
- }
-}
+export { isMainModule } from "./main-module.mjs";
export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
const argv = process.argv.slice(2);
diff --git a/skills/faceless-explainer/scripts/lib/main-module.mjs b/skills/faceless-explainer/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/faceless-explainer/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/skills/general-video/scripts/lib/frame-packets-core.mjs b/skills/general-video/scripts/lib/frame-packets-core.mjs
index d165088ff8..d4cfbecba1 100644
--- a/skills/general-video/scripts/lib/frame-packets-core.mjs
+++ b/skills/general-video/scripts/lib/frame-packets-core.mjs
@@ -2,16 +2,8 @@
// Workflow wrappers supply resource paths and workflow-specific sections.
// The role combines the shared worker contract with the workflow delta.
-import {
- existsSync,
- mkdirSync,
- readFileSync,
- readdirSync,
- realpathSync,
- writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
export function field(block, name) {
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
@@ -160,17 +152,7 @@ export function flag(argv, name, fallback) {
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
- } catch {
- return false;
- }
-}
+export { isMainModule } from "./main-module.mjs";
export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
const argv = process.argv.slice(2);
diff --git a/skills/general-video/scripts/lib/main-module.mjs b/skills/general-video/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/general-video/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/skills/hyperframes-audio/scripts/carve.mjs b/skills/hyperframes-audio/scripts/carve.mjs
index a9865ed550..4649117fee 100644
--- a/skills/hyperframes-audio/scripts/carve.mjs
+++ b/skills/hyperframes-audio/scripts/carve.mjs
@@ -26,9 +26,10 @@
import { execFileSync } from "node:child_process";
import { createRequire } from "node:module";
-import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { pathToFileURL } from "node:url";
+import { isMainModule } from "./lib/main-module.mjs";
/** Sample rate the analysis runs at. Matches Studio's own decode rate, so the
* bands and envelopes come out the same either way. */
@@ -554,19 +555,6 @@ async function main() {
// Only run as a CLI. Guarded so the pure helpers above can be unit-tested by
// importing this module (`skills/**/*.test.mjs`, run by `bun run test:skills`).
-//
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-function isMainModule(importMetaUrl) {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
- } catch {
- return false;
- }
-}
-
if (isMainModule(import.meta.url)) {
await main();
}
diff --git a/skills/hyperframes-audio/scripts/lib/main-module.mjs b/skills/hyperframes-audio/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/hyperframes-audio/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md
index fd74ca4f75..d920afac01 100644
--- a/skills/hyperframes-cli/SKILL.md
+++ b/skills/hyperframes-cli/SKILL.md
@@ -130,6 +130,8 @@ Use `selection.target.hfId` when available, otherwise its selector and source fi
| Self-managed distributed AWS render | `npx hyperframes lambda render <project> --width 1920 --height 1080 --wait` |
| Self-managed distributed GCP render | `npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait` |
+A render stops when whatever started it stops, so a Ctrl-C or a closed terminal never leaves Chrome running. If your tool kills its whole process group when a command times out or ends, a long render dies with it. Start such a render in its own process group with `HYPERFRAMES_RENDER_DETACHED=1`, for example `bash -c 'set -m; HYPERFRAMES_RENDER_DETACHED=1 npx hyperframes render --output out.mp4 < /dev/null > render.log 2>&1 &'` (works on macOS and Linux), then check the log and the output file instead of waiting on the command.
+
Skill attribution is automatic — the examples above need no `--skill`. A project scaffolded by a workflow (`hyperframes init --skill=<workflow>`) records its owning skill in `hyperframes.json`, and every later render inherits it on anonymous telemetry: re-renders, `npm run render`, and `--batch` alike. Pass `--skill=<slug>` explicitly only to stamp a project that was not created through a workflow (its first render then persists it).
Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS. Use Lambda only when AWS ownership is a requirement. Use Cloud Run only when GCP ownership is a requirement. Read the matching reference before running any cloud path.
diff --git a/skills/hyperframes/scripts/lib/frame-packets-core.mjs b/skills/hyperframes/scripts/lib/frame-packets-core.mjs
index d165088ff8..d4cfbecba1 100644
--- a/skills/hyperframes/scripts/lib/frame-packets-core.mjs
+++ b/skills/hyperframes/scripts/lib/frame-packets-core.mjs
@@ -2,16 +2,8 @@
// Workflow wrappers supply resource paths and workflow-specific sections.
// The role combines the shared worker contract with the workflow delta.
-import {
- existsSync,
- mkdirSync,
- readFileSync,
- readdirSync,
- realpathSync,
- writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
export function field(block, name) {
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
@@ -160,17 +152,7 @@ export function flag(argv, name, fallback) {
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
- } catch {
- return false;
- }
-}
+export { isMainModule } from "./main-module.mjs";
export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
const argv = process.argv.slice(2);
diff --git a/skills/hyperframes/scripts/lib/main-module.mjs b/skills/hyperframes/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/hyperframes/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/skills/hyperframes/scripts/lib/main-module.test.mjs b/skills/hyperframes/scripts/lib/main-module.test.mjs
new file mode 100644
index 0000000000..8ce3a206e3
--- /dev/null
+++ b/skills/hyperframes/scripts/lib/main-module.test.mjs
@@ -0,0 +1,51 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, relative, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const SKILLS = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const CLI_MEDIA_USE = resolve(SKILLS, "../packages/cli/src/media-use");
+
+// Agents install skills by symlinking the skills dir, so each script must still run its CLI.
+test("skill CLIs run when invoked through a symlinked skills dir", () => {
+ const dir = mkdtempSync(join(tmpdir(), "skills-link-"));
+ try {
+ symlinkSync(SKILLS, join(dir, "skills"), "dir");
+ for (const script of [
+ "faceless-explainer/scripts/captions.mjs",
+ "pr-to-video/scripts/captions.mjs",
+ "product-launch-video/scripts/captions.mjs",
+ "media-use/audio/scripts/heygen-voice.mjs",
+ ]) {
+ const run = spawnSync(process.execPath, [join(dir, "skills", script), "not-a-command"], {
+ encoding: "utf8",
+ });
+ assert.notEqual(run.status, 0, `${script} exited ${run.status} without running its CLI`);
+ assert.match(run.stderr, /usage/, script);
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+function skillScripts(dir) {
+ return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) return entry.name === "node_modules" ? [] : skillScripts(path);
+ return /\.(mjs|js)$/.test(entry.name) && !/\.test\.mjs$/.test(entry.name) ? [path] : [];
+ });
+}
+
+test("skill scripts detect their CLI entry through lib/main-module.mjs only", () => {
+ const handRolled = [...skillScripts(SKILLS), ...skillScripts(CLI_MEDIA_USE)].filter(
+ (path) =>
+ !path.endsWith("main-module.mjs") && readFileSync(path, "utf8").includes("process.argv[1]"),
+ );
+ assert.deepEqual(
+ handRolled.map((path) => relative(SKILLS, path)),
+ [],
+ );
+});
diff --git a/skills/hyperframes/scripts/plugin-cli.mjs b/skills/hyperframes/scripts/plugin-cli.mjs
index 4fa4e6d770..4eeb01b8bd 100644
--- a/skills/hyperframes/scripts/plugin-cli.mjs
+++ b/skills/hyperframes/scripts/plugin-cli.mjs
@@ -1,9 +1,10 @@
#!/usr/bin/env node
// Run from the user's project; locate the release from this installed file.
import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
import { join, win32 } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./lib/main-module.mjs";
const root = fileURLToPath(new URL("../../../", import.meta.url));
const manifests = [
@@ -71,7 +72,7 @@ export function invocation(
return { command: node, args: [npx, ...cliArgs], env: childEnv };
}
-if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+if (isMainModule(import.meta.url)) {
try {
const command = invocation(process.argv.slice(2));
const result = spawnSync(command.command, command.args, {
diff --git a/skills/hyperframes/scripts/plugin-cli.test.mjs b/skills/hyperframes/scripts/plugin-cli.test.mjs
index df2d3e5f93..d1a42cc5f3 100644
--- a/skills/hyperframes/scripts/plugin-cli.test.mjs
+++ b/skills/hyperframes/scripts/plugin-cli.test.mjs
@@ -17,11 +17,15 @@ import { invocation, pluginVersion } 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"), { recursive: 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 }));
const launcher = join(root, "skills/hyperframes/scripts/plugin-cli.mjs");
copyFileSync(new URL("./plugin-cli.mjs", import.meta.url), launcher);
+ copyFileSync(
+ new URL("./lib/main-module.mjs", import.meta.url),
+ join(root, "skills/hyperframes/scripts/lib/main-module.mjs"),
+ );
return { root, launcher };
}
diff --git a/skills/media-use/audio/scripts/heygen-voice.mjs b/skills/media-use/audio/scripts/heygen-voice.mjs
index 7a5559750b..0e25377f51 100644
--- a/skills/media-use/audio/scripts/heygen-voice.mjs
+++ b/skills/media-use/audio/scripts/heygen-voice.mjs
@@ -5,9 +5,9 @@
import { readFileSync } from "node:fs";
import { extname } from "node:path";
-import { fileURLToPath } from "node:url";
import { parseArgs } from "node:util";
import { heygenAuthHeaders, heygenJSON, heygenMessage, loadEnvFromDir } from "./lib/heygen.mjs";
+import { isMainModule } from "./lib/main-module.mjs";
const MEDIA_TYPES = { ".mp3": "audio/mpeg", ".wav": "audio/wav" };
const POLL_MS = 2_000;
@@ -92,7 +92,7 @@ export async function main(
}
}
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
loadEnvFromDir(process.cwd());
process.exitCode = await main(process.argv.slice(2));
}
diff --git a/skills/media-use/audio/scripts/lib/main-module.mjs b/skills/media-use/audio/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/media-use/audio/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/skills/pr-to-video/scripts/captions.mjs b/skills/pr-to-video/scripts/captions.mjs
index b2e2fa0168..e4abf3eec2 100644
--- a/skills/pr-to-video/scripts/captions.mjs
+++ b/skills/pr-to-video/scripts/captions.mjs
@@ -35,10 +35,10 @@ import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
import { parseStoryboard } from "./lib/storyboard.mjs";
import { captionBand, parseFormat } from "./lib/dimensions.mjs";
import { parseColors, parseFonts, semanticColors } from "./lib/tokens.mjs";
+import { isMainModule } from "./lib/main-module.mjs";
const flag = (argv, name, def) => {
const i = argv.indexOf(`--${name}`);
@@ -512,7 +512,7 @@ function buildCaptionsHtml(groups, total, W, H) {
`;
}
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
const sub = process.argv[2];
if (sub === "build" || sub === undefined) runBuild(process.argv.slice(sub === "build" ? 3 : 2));
else {
diff --git a/skills/pr-to-video/scripts/lib/frame-packets-core.mjs b/skills/pr-to-video/scripts/lib/frame-packets-core.mjs
index d165088ff8..d4cfbecba1 100644
--- a/skills/pr-to-video/scripts/lib/frame-packets-core.mjs
+++ b/skills/pr-to-video/scripts/lib/frame-packets-core.mjs
@@ -2,16 +2,8 @@
// Workflow wrappers supply resource paths and workflow-specific sections.
// The role combines the shared worker contract with the workflow delta.
-import {
- existsSync,
- mkdirSync,
- readFileSync,
- readdirSync,
- realpathSync,
- writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
export function field(block, name) {
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
@@ -160,17 +152,7 @@ export function flag(argv, name, fallback) {
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
- } catch {
- return false;
- }
-}
+export { isMainModule } from "./main-module.mjs";
export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
const argv = process.argv.slice(2);
diff --git a/skills/pr-to-video/scripts/lib/main-module.mjs b/skills/pr-to-video/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/pr-to-video/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}
diff --git a/skills/pr-to-video/scripts/preflight.mjs b/skills/pr-to-video/scripts/preflight.mjs
index 50ef799a23..4874799ad6 100644
--- a/skills/pr-to-video/scripts/preflight.mjs
+++ b/skills/pr-to-video/scripts/preflight.mjs
@@ -1,8 +1,7 @@
#!/usr/bin/env node
import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
-import { pathToFileURL } from "node:url";
+import { isMainModule } from "./lib/main-module.mjs";
export function hasCliCommand(helpText, command) {
const escaped = command.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -36,16 +35,4 @@ function main() {
}
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-function isMainModule() {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
- } catch {
- return false;
- }
-}
-
-if (isMainModule()) main();
+if (isMainModule(import.meta.url)) main();
diff --git a/skills/pr-to-video/scripts/project-dir.mjs b/skills/pr-to-video/scripts/project-dir.mjs
index 55284a5f7a..a7f108daa3 100644
--- a/skills/pr-to-video/scripts/project-dir.mjs
+++ b/skills/pr-to-video/scripts/project-dir.mjs
@@ -2,8 +2,7 @@
import { homedir } from "node:os";
import { join, resolve } from "node:path";
-import { realpathSync } from "node:fs";
-import { pathToFileURL } from "node:url";
+import { isMainModule } from "./lib/main-module.mjs";
function safeSegment(value) {
const normalized = value
@@ -77,16 +76,4 @@ function main() {
}
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-function isMainModule() {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
- } catch {
- return false;
- }
-}
-
-if (isMainModule()) main();
+if (isMainModule(import.meta.url)) main();
diff --git a/skills/product-launch-video/scripts/captions.mjs b/skills/product-launch-video/scripts/captions.mjs
index b2e2fa0168..e4abf3eec2 100644
--- a/skills/product-launch-video/scripts/captions.mjs
+++ b/skills/product-launch-video/scripts/captions.mjs
@@ -35,10 +35,10 @@ import { stageCapturedFonts } from "./lib/captured-fonts.mjs";
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
import { parseStoryboard } from "./lib/storyboard.mjs";
import { captionBand, parseFormat } from "./lib/dimensions.mjs";
import { parseColors, parseFonts, semanticColors } from "./lib/tokens.mjs";
+import { isMainModule } from "./lib/main-module.mjs";
const flag = (argv, name, def) => {
const i = argv.indexOf(`--${name}`);
@@ -512,7 +512,7 @@ function buildCaptionsHtml(groups, total, W, H) {
`;
}
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
const sub = process.argv[2];
if (sub === "build" || sub === undefined) runBuild(process.argv.slice(sub === "build" ? 3 : 2));
else {
diff --git a/skills/product-launch-video/scripts/lib/frame-packets-core.mjs b/skills/product-launch-video/scripts/lib/frame-packets-core.mjs
index d165088ff8..d4cfbecba1 100644
--- a/skills/product-launch-video/scripts/lib/frame-packets-core.mjs
+++ b/skills/product-launch-video/scripts/lib/frame-packets-core.mjs
@@ -2,16 +2,8 @@
// Workflow wrappers supply resource paths and workflow-specific sections.
// The role combines the shared worker contract with the workflow delta.
-import {
- existsSync,
- mkdirSync,
- readFileSync,
- readdirSync,
- realpathSync,
- writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
export function field(block, name) {
const match = block.match(new RegExp(`^-\\s+${name}:\\s*(.+)$`, "im"));
@@ -160,17 +152,7 @@ export function flag(argv, name, fallback) {
return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
}
-// realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
-// module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
-// a raw compare silently skips main() when invoked through any symlinked path.
-export function isMainModule(importMetaUrl) {
- if (!process.argv[1]) return false;
- try {
- return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
- } catch {
- return false;
- }
-}
+export { isMainModule } from "./main-module.mjs";
export function runCli({ buildFramePackets: build, buildRolePayload: buildRole }) {
const argv = process.argv.slice(2);
diff --git a/skills/product-launch-video/scripts/lib/main-module.mjs b/skills/product-launch-video/scripts/lib/main-module.mjs
new file mode 100644
index 0000000000..5fd2fa9d04
--- /dev/null
+++ b/skills/product-launch-video/scripts/lib/main-module.mjs
@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+ if (!process.argv[1]) return false;
+ try {
+ return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+ } catch {
+ return false;
+ }
+}