diff --git a/.agents/skills/changelog-video/SKILL.md b/.agents/skills/changelog-video/SKILL.md index 765bf050c8..f986f160bf 100644 --- a/.agents/skills/changelog-video/SKILL.md +++ b/.agents/skills/changelog-video/SKILL.md @@ -7,6 +7,8 @@ metadata: # Changelog → Branded Video + + Input: a changelog .md (themes + items, like the weekly HyperFrames digest). Output: a lint-clean, seam-gate-green HyperFrames project in `projects/active/weekly-changelog-/`. Render only when asked. diff --git a/.claude/skills/changelog-video/SKILL.md b/.claude/skills/changelog-video/SKILL.md index 765bf050c8..f986f160bf 100644 --- a/.claude/skills/changelog-video/SKILL.md +++ b/.claude/skills/changelog-video/SKILL.md @@ -7,6 +7,8 @@ metadata: # Changelog → Branded Video + + Input: a changelog .md (themes + items, like the weekly HyperFrames digest). Output: a lint-clean, seam-gate-green HyperFrames project in `projects/active/weekly-changelog-/`. Render only when asked. diff --git a/scripts/lint-skills.test.mjs b/scripts/lint-skills.test.mjs index d01595a049..2c97bbd0d8 100644 --- a/scripts/lint-skills.test.mjs +++ b/scripts/lint-skills.test.mjs @@ -11,7 +11,13 @@ import assert from "node:assert/strict"; import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { headingSlugs, lintDocRefs, lintFrontmatter, lintRegistryItemRefs } from "./lint-skills.ts"; +import { + headingSlugs, + lintDocRefs, + lintFrontmatter, + lintRegistryItemRefs, + lintRelativeScriptRuns, +} from "./lint-skills.ts"; const wrap = (frontmatter) => `---\n${frontmatter}\n---\n\n# body\n`; @@ -337,3 +343,61 @@ test("heading slugs: GitHub-style lowercasing, punctuation strip, dedupe", () => ); assert.deepEqual([...slugs], ["hello-world", "code--stuff", "hello-world-1"]); }); + +// --------------------------------------------------------------------------- +// Helper scripts run by a working-directory-relative path +// --------------------------------------------------------------------------- + +const fenced = (body) => "# Doc\n\n```bash\n" + body + "\n```\n"; + +test("relative scripts: a cwd-relative helper path in a code block is flagged", () => { + const violations = lintRelativeScriptRuns( + fenced("node skills/media-use/audio/scripts/heygen-tts.mjs a.txt -o a.wav"), + ); + assert.equal(violations.length, 1); + assert.equal(violations[0].line, 4); + assert.match(violations[0].message, /skills\/media-use\/audio\/scripts\/heygen-tts\.mjs/); +}); + +test("relative scripts: other interpreters, bare names and ./ paths are flagged", () => { + for (const body of [ + "python3 scripts/lint_source.py ./src", + "bash ./scripts/run.sh", + "npx tsx scripts/generate.ts", + "cd out && node locate.mjs overlay", + ]) { + assert.equal(lintRelativeScriptRuns(fenced(body)).length, 1, body); + } +}); + +test("relative scripts: an inline code span in prose is checked too", () => { + const violations = lintRelativeScriptRuns("Run `python3 tools/voice.py --silent` first.\n"); + assert.equal(violations.length, 1); + assert.equal(violations[0].line, 1); +}); + +test("relative scripts: skill-anchored, variable and absolute paths pass", () => { + for (const body of [ + "node /audio/scripts/heygen-tts.mjs a.txt", + 'node "/hyperframes/scripts/plugin-cli.mjs" list', + 'node "$SKILL_DIR/scripts/x.mjs"', + "node /opt/tools/x.mjs", + "node ~/tools/x.mjs", + "node -e 'console.log(1)'", + "npx hyperframes render", + ]) { + assert.deepEqual(lintRelativeScriptRuns(fenced(body)), [], body); + } +}); + +test("relative scripts: a script named in prose without an interpreter is not flagged", () => { + assert.deepEqual(lintRelativeScriptRuns("`scripts/locate.mjs` narrows it with a grid.\n"), []); +}); + +test("relative scripts: a marker with a reason opts the doc out", () => { + const body = fenced("npx tsx scripts/generate.ts"); + const marked = "\n" + body; + assert.deepEqual(lintRelativeScriptRuns(marked), []); + const noReason = "\n" + body; + assert.equal(lintRelativeScriptRuns(noReason).length, 1); +}); diff --git a/scripts/lint-skills.ts b/scripts/lint-skills.ts index 079ae4efd6..3f72c978b9 100644 --- a/scripts/lint-skills.ts +++ b/scripts/lint-skills.ts @@ -509,6 +509,65 @@ export function lintDocRefs(filePath: string, content: string): LineViolation[] .flatMap((ref) => checkDocRef(ref, filePath, content) ?? []); } +// --------------------------------------------------------------------------- +// Helper scripts run by a working-directory-relative path +// --------------------------------------------------------------------------- +// +// An agent runs a skill's commands from the user's project directory, and that +// project may come from someone else. `node skills/x/scripts/y.mjs` or +// `node scripts/y.mjs` resolves inside that project, so a planted file with +// the same name runs instead of the bundled helper. A doc names its helpers +// through the skill's own folder (`/scripts/y.mjs`) instead. +// +// A doc whose relative commands are safe opts out with a marker line that +// says why, for example when its commands run inside a HyperFrames checkout +// rather than a user project: +// +// +// +// Only interpreter invocations are seen: a script run directly (`./setup.sh`) +// or after interpreter flags (`node --test x.mjs`) is a known false negative. + +const RELATIVE_SCRIPT_OPT_OUT = //; +const CODE_FENCE = /^ {0,3}(?:```|~~~)/; +const RELATIVE_SCRIPT_RUN = + /(?:^|[\s(;&|])(?:node|python3?|bash|sh|tsx|bun)\s+["']?((?![<$/~"'-])[^\s"'`]+\.(?:mjs|cjs|js|ts|py|sh))(?=["'\s;)|&]|$)/; + +/** Each fenced-block line and each inline code span, with its 1-based line number. */ +function codeSegments(content: string): { text: string; line: number }[] { + const segments: { text: string; line: number }[] = []; + let inFence = false; + content.split("\n").forEach((text, index) => { + if (CODE_FENCE.test(text)) { + inFence = !inFence; + return; + } + if (inFence) { + segments.push({ text, line: index + 1 }); + return; + } + for (const span of text.matchAll(INLINE_CODE_SPAN)) { + segments.push({ text: span[1] ?? "", line: index + 1 }); + } + }); + return segments; +} + +export function lintRelativeScriptRuns(content: string): LineViolation[] { + if (RELATIVE_SCRIPT_OPT_OUT.test(content)) return []; + return codeSegments(content).flatMap(({ text, line }) => { + const script = RELATIVE_SCRIPT_RUN.exec(text)?.[1]; + if (!script) return []; + return [ + violation( + line, + `Runs \`${script}\` by a path relative to the working directory, which resolves inside the user's project. Name the bundled helper through its skill folder, for example \`/scripts/...\`.`, + text, + ), + ]; + }); +} + function collectMarkdownFiles(dir: string): string[] { return readdirSync(dir, { withFileTypes: true, recursive: true }) .filter((entry) => entry.isFile() && entry.name.endsWith(".md")) @@ -537,6 +596,7 @@ function lintMarkdownFiles(paths: string[], knownItems: Set, report: Rep const content = readFileSync(path, "utf-8"); const file = relative(process.cwd(), path); report(file, lintDocRefs(path, content)); + report(file, lintRelativeScriptRuns(content)); const found = lintRegistryItemRefs(content, knownItems); if (found === null) continue; snapshotsChecked++; diff --git a/skills-manifest.json b/skills-manifest.json index e0ecfb3cf5..01f74e9001 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -14,15 +14,15 @@ "files": 13 }, "hyperframes-registry": { - "hash": "560a5f11064f82c9", + "hash": "25e0d7a72fe285a0", "files": 13 }, "media-use": { - "hash": "2784d98fa34ffc2e", + "hash": "65317a8d5de8e4ae", "files": 128 }, "remotion-to-hyperframes": { - "hash": "e7982839c333759e", + "hash": "27f757cb659e1aaa", "files": 76 }, "reverse-any-video": { @@ -34,7 +34,7 @@ "files": 2 }, "style-sampling": { - "hash": "5378b0a22d46cd0d", + "hash": "59e52f3f688b9277", "files": 2 } } diff --git a/skills/hyperframes-registry/references/contributing.md b/skills/hyperframes-registry/references/contributing.md index de02d47661..9f04682260 100644 --- a/skills/hyperframes-registry/references/contributing.md +++ b/skills/hyperframes-registry/references/contributing.md @@ -1,5 +1,7 @@ # Contributing a Block or Component to the Registry + + Guide the user from idea to merged PR for a new registry block or component. ## Workflow diff --git a/skills/media-use/audio/references/tts-to-captions.md b/skills/media-use/audio/references/tts-to-captions.md index 4b99fa0a8c..a4e27f39a3 100644 --- a/skills/media-use/audio/references/tts-to-captions.md +++ b/skills/media-use/audio/references/tts-to-captions.md @@ -8,7 +8,7 @@ HeyGen returns word timestamps in the same response as the audio. Use the bundled REST helper (the `hyperframes tts` command is Kokoro-only): ```bash -node skills/media-use/audio/scripts/heygen-tts.mjs \ +node /audio/scripts/heygen-tts.mjs \ script.txt --output narration.wav --words narration.words.json ``` diff --git a/skills/media-use/audio/references/tts.md b/skills/media-use/audio/references/tts.md index 70923223ee..b8900c5e7b 100644 --- a/skills/media-use/audio/references/tts.md +++ b/skills/media-use/audio/references/tts.md @@ -77,11 +77,11 @@ rather than selecting a saved API key, with a hint to run `npx hyperframes auth export HEYGEN_API_KEY=... # a project .env key is used only when nothing is saved # Synthesize + capture word timestamps in one call (skips a Whisper pass) -node skills/media-use/audio/scripts/heygen-tts.mjs \ +node /audio/scripts/heygen-tts.mjs \ "Welcome to HyperFrames." -o narration.wav --words narration.words.json -node skills/media-use/audio/scripts/heygen-tts.mjs ./script.txt -o narration.wav -node skills/media-use/audio/scripts/heygen-tts.mjs --list # public starfish voices +node /audio/scripts/heygen-tts.mjs ./script.txt -o narration.wav +node /audio/scripts/heygen-tts.mjs --list # public starfish voices ``` - **Voice:** `--voice ` must be a **starfish** voice_id (`--list`, or `GET /v3/voices?engine=starfish`) or one of your cloned voice ids (below). v2-catalog ids are rejected with HTTP 400. Omit `--voice` (English) and it defaults to **Marcia** (`05f19352e8f74b0392a8f411eba40de1`, a fixed default so the choice is deterministic). Non-English with no `--voice` falls back to the first matching catalog voice. @@ -97,9 +97,9 @@ Clone a voice from an mp3 or wav recording, then pass the printed id to message to stderr and exits 1. ```bash -node skills/media-use/audio/scripts/heygen-voice.mjs clone take.mp3 --name "My voice" # → {"voice_id":"..."} -node skills/media-use/audio/scripts/heygen-voice.mjs list --prefix "My" # → [{"voice_id","name","created_at"}] -node skills/media-use/audio/scripts/heygen-voice.mjs delete +node /audio/scripts/heygen-voice.mjs clone take.mp3 --name "My voice" # → {"voice_id":"..."} +node /audio/scripts/heygen-voice.mjs list --prefix "My" # → [{"voice_id","name","created_at"}] +node /audio/scripts/heygen-voice.mjs delete ``` `clone` waits up to 120 s for the clone to finish. `list` reads diff --git a/skills/remotion-to-hyperframes/references/eval.md b/skills/remotion-to-hyperframes/references/eval.md index 9f16ed0145..2466de1563 100644 --- a/skills/remotion-to-hyperframes/references/eval.md +++ b/skills/remotion-to-hyperframes/references/eval.md @@ -1,5 +1,7 @@ # Eval: how to validate a translation end-to-end + + Every translation should be measured. The skill ships a source linter and a tiered test corpus; the CLI's `diff` command scores the result. Together they gate translation quality. diff --git a/skills/style-sampling/references/remix.md b/skills/style-sampling/references/remix.md index 3e0e200d31..ed6bfdea9e 100644 --- a/skills/style-sampling/references/remix.md +++ b/skills/style-sampling/references/remix.md @@ -1,5 +1,7 @@ # Making the episode + + The template holds every rule and tool; this file sets the order and the discipline. When this file and the template disagree, the template wins, except on the length the person picked (§3) and on Pro and credits (SKILL.md). Order: `read → settle the voice → say what's coming → ask (only what is open) → facts + script → stop 1 (storyboard) → voice → face → footage → shot plan + build → checks → stop 2 (draft) → render → reply`