mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
fix(skills): run bundled TTS helpers from the skill folder, not the working directory (#8035)
The media-use TTS and captions references ran heygen-tts.mjs and heygen-voice.mjs as skills/media-use/... paths relative to the working directory. Agents run these commands from the user's project, so a project that ships a file at that path would run instead of the bundled helper. Name the helpers through <SKILL_DIR>, as the rest of media-use does, and add a skill lint rule that fails when a code block or inline command runs node, python, bash, sh, tsx or bun on a relative script path. Docs whose commands run inside a HyperFrames checkout, or only on a checked template kit, opt out with a marker that states the reason.
This commit is contained in:
@@ -7,6 +7,8 @@ metadata:
|
||||
|
||||
# Changelog → Branded Video
|
||||
|
||||
<!-- skill-scripts: relative-ok, runs from the HyperFrames repo root -->
|
||||
|
||||
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-<range>/`. Render only when asked.
|
||||
|
||||
@@ -7,6 +7,8 @@ metadata:
|
||||
|
||||
# Changelog → Branded Video
|
||||
|
||||
<!-- skill-scripts: relative-ok, runs from the HyperFrames repo root -->
|
||||
|
||||
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-<range>/`. Render only when asked.
|
||||
|
||||
@@ -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 <SKILL_DIR>/audio/scripts/heygen-tts.mjs a.txt",
|
||||
'node "<SKILLS>/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 = "<!-- skill-scripts: relative-ok, runs inside a HyperFrames checkout -->\n" + body;
|
||||
assert.deepEqual(lintRelativeScriptRuns(marked), []);
|
||||
const noReason = "<!-- skill-scripts: relative-ok -->\n" + body;
|
||||
assert.equal(lintRelativeScriptRuns(noReason).length, 1);
|
||||
});
|
||||
|
||||
@@ -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 (`<SKILL_DIR>/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:
|
||||
//
|
||||
// <!-- skill-scripts: relative-ok, runs inside a HyperFrames checkout -->
|
||||
//
|
||||
// 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 = /<!--\s*skill-scripts:\s*relative-ok,\s*\S[^>]*-->/;
|
||||
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 \`<SKILL_DIR>/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<string>, 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++;
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Contributing a Block or Component to the Registry
|
||||
|
||||
<!-- skill-scripts: relative-ok, runs inside a HyperFrames checkout -->
|
||||
|
||||
Guide the user from idea to merged PR for a new registry block or component.
|
||||
|
||||
## Workflow
|
||||
|
||||
@@ -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 <SKILL_DIR>/audio/scripts/heygen-tts.mjs \
|
||||
script.txt --output narration.wav --words narration.words.json
|
||||
```
|
||||
|
||||
|
||||
@@ -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 <SKILL_DIR>/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 <SKILL_DIR>/audio/scripts/heygen-tts.mjs ./script.txt -o narration.wav
|
||||
node <SKILL_DIR>/audio/scripts/heygen-tts.mjs --list # public starfish voices
|
||||
```
|
||||
|
||||
- **Voice:** `--voice <id>` 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 <voice_id>
|
||||
node <SKILL_DIR>/audio/scripts/heygen-voice.mjs clone take.mp3 --name "My voice" # → {"voice_id":"..."}
|
||||
node <SKILL_DIR>/audio/scripts/heygen-voice.mjs list --prefix "My" # → [{"voice_id","name","created_at"}]
|
||||
node <SKILL_DIR>/audio/scripts/heygen-voice.mjs delete <voice_id>
|
||||
```
|
||||
|
||||
`clone` waits up to 120 s for the clone to finish. `list` reads
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Eval: how to validate a translation end-to-end
|
||||
|
||||
<!-- skill-scripts: relative-ok, runs inside a HyperFrames checkout -->
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Making the episode
|
||||
|
||||
<!-- skill-scripts: relative-ok, kit tools run only from a template this session pulled and checked -->
|
||||
|
||||
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`
|
||||
|
||||
Reference in New Issue
Block a user