mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +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:
@@ -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++;
|
||||
|
||||
Reference in New Issue
Block a user