diff --git a/docs/studio/assets-and-blocks.mdx b/docs/studio/assets-and-blocks.mdx index 2bfc6ff8f6..e47040a173 100644 --- a/docs/studio/assets-and-blocks.mdx +++ b/docs/studio/assets-and-blocks.mdx @@ -124,7 +124,9 @@ Use **Edit** to change a variable's label, description, or saved default. For fo At the bottom of the panel, **Use this template** can copy either: - the effective values as JSON; -- a ready-to-run `npx hyperframes render ... --variables ...` command. +- a ready-to-run `npx hyperframes render -c --variables-file .hyperframes/render-variables.json` command. + +Copying the command also saves the values you are previewing to `.hyperframes/render-variables.json`, so run it from the project folder. The values travel in that file rather than in the command, so no value can be read as shell syntax in bash, zsh, fish, PowerShell or Command Prompt. If the composition's file name has characters other than letters, digits, `_`, `.`, `/` and `-`, the browser editor offers only the JSON; rename the file to get the command. This keeps the values you just reviewed attached to the render request instead of asking the next person to reconstruct them. diff --git a/packages/core/src/projectFolders.ts b/packages/core/src/projectFolders.ts index f54a004713..81bcd13002 100644 --- a/packages/core/src/projectFolders.ts +++ b/packages/core/src/projectFolders.ts @@ -21,3 +21,5 @@ export const RENDER_TEMP_DIR = export const isProjectIgnoredDir = (name: string): boolean => PREVIEW_IGNORED_DIRS.has(name) || RENDER_TEMP_DIR.test(name); + +export const RENDER_VARIABLES_FILE = ".hyperframes/render-variables.json"; diff --git a/packages/studio-server/src/routes/render.ts b/packages/studio-server/src/routes/render.ts index 42e5ccefad..e43191871c 100644 --- a/packages/studio-server/src/routes/render.ts +++ b/packages/studio-server/src/routes/render.ts @@ -14,8 +14,11 @@ import { Readable } from "node:stream"; import type { StudioApiAdapter, RenderJobState } from "../types.js"; import { VALID_CANVAS_RESOLUTIONS, type CanvasResolution } from "@hyperframes/parsers"; import { formatRenderOutputTimestamp, parseFps, fpsToNumber } from "@hyperframes/core"; +import { replaceFileAtomically } from "@hyperframes/core/atomic-file"; +import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders"; import { folderGone, + isLinkFreeWithinProject, isPrivateProjectFile, mkdirWithinProject, resolveWithinProject, @@ -217,6 +220,23 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void return c.json({ jobId, status: "rendering" }); }); + api.put("/projects/:id/render-variables", async (c) => { + const project = await adapter.resolveProject(c.req.param("id")); + if (!project) return c.json({ error: "not found" }, 404); + const values: unknown = await c.req.json().catch(() => undefined); + if (!isVariablesPayload(values)) return c.json({ error: VARIABLES_PAYLOAD_ERROR }, 400); + if (folderGone(project.dir)) return projectDirMissing(c); + // The variable ids are the composition's, so a write through a link could put chosen JSON in package.json. A link + // on the way is refused; a link in the file's place is replaced by the rename, not written through. + const path = join(project.dir, RENDER_VARIABLES_FILE); + if (!isLinkFreeWithinProject(project.dir, dirname(path))) { + return c.json({ error: "forbidden", why: "link" }, 403); + } + mkdirWithinProject(project.dir, dirname(path)); + replaceFileAtomically(path, JSON.stringify(values, null, 2) + "\n", 0o644); + return c.json({ path: RENDER_VARIABLES_FILE }); + }); + // SSE progress stream api.get("/render/:jobId/progress", (c) => { const { jobId } = c.req.param(); diff --git a/packages/studio-server/src/routes/render.variablesFile.test.ts b/packages/studio-server/src/routes/render.variablesFile.test.ts new file mode 100644 index 0000000000..2bb9cf2e74 --- /dev/null +++ b/packages/studio-server/src/routes/render.variablesFile.test.ts @@ -0,0 +1,123 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { Hono } from "hono"; +import { + closeSync, + constants, + existsSync, + mkdirSync, + mkdtempSync, + openSync, + readFileSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { registerRenderRoutes } from "./render"; +import type { StudioApiAdapter } from "../types"; + +const folders: string[] = []; + +afterEach(() => { + for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }); +}); + +function folder(): string { + const dir = mkdtempSync(join(tmpdir(), "hf-render-variables-")); + folders.push(dir); + return dir; +} + +function appFor(projectDir: string): Hono { + const adapter: StudioApiAdapter = { + listProjects: () => [], + resolveProject: async (id: string) => ({ id, dir: projectDir }), + bundle: async () => null, + lint: async () => ({ findings: [] }), + runtimeUrl: "/api/runtime.js", + rendersDir: () => join(projectDir, "renders"), + startRender: () => { + throw new Error("not used"); + }, + }; + const app = new Hono(); + registerRenderRoutes(app, adapter); + return app; +} + +const put = (app: Hono, body: string) => + app.request("http://localhost/projects/demo/render-variables", { + method: "PUT", + headers: { "content-type": "application/json" }, + body, + }); + +describe("PUT /projects/:id/render-variables", () => { + it("writes the values to .hyperframes/render-variables.json", async () => { + const project = folder(); + const values = { title: `x'; calc.exe; '" & calc | $(id)`, count: 3 }; + + const response = await put(appFor(project), JSON.stringify(values)); + + expect(response.status).toBe(200); + expect(await response.json()).toEqual({ path: ".hyperframes/render-variables.json" }); + const written = readFileSync(join(project, ".hyperframes/render-variables.json"), "utf8"); + expect(JSON.parse(written)).toEqual(values); + }); + + it.each(["[1,2]", '"text"', "null", "{not json"])( + "refuses %s, which is not an object", + async (body) => { + const project = folder(); + + const response = await put(appFor(project), body); + + expect(response.status).toBe(400); + expect(existsSync(join(project, ".hyperframes/render-variables.json"))).toBe(false); + }, + ); + + it("does not write through a .hyperframes link that leaves the project", async () => { + const project = folder(); + const elsewhere = folder(); + symlinkSync(elsewhere, join(project, ".hyperframes"), "dir"); + + const response = await put(appFor(project), JSON.stringify({ title: "x" })); + + expect(response.status).toBe(403); + expect(existsSync(join(elsewhere, "render-variables.json"))).toBe(false); + }); + + it("does not write through a .hyperframes link to a folder in the project", async () => { + const project = folder(); + mkdirSync(join(project, "scripts")); + symlinkSync(join(project, "scripts"), join(project, ".hyperframes"), "dir"); + + const response = await put(appFor(project), JSON.stringify({ title: "x" })); + + expect(response.status).toBe(403); + expect(existsSync(join(project, "scripts/render-variables.json"))).toBe(false); + }); + + it("replaces a file link planted in its place instead of writing to package.json", async () => { + const project = folder(); + const manifest = '{"name":"demo"}\n'; + writeFileSync(join(project, "package.json"), manifest); + mkdirSync(join(project, ".hyperframes")); + const record = join(project, ".hyperframes/render-variables.json"); + symlinkSync(join(project, "package.json"), record, "file"); + const values = { scripts: { postinstall: "calc.exe" } }; + + const response = await put(appFor(project), JSON.stringify(values)); + + expect(response.status).toBe(200); + expect(readFileSync(join(project, "package.json"), "utf8")).toBe(manifest); + const fd = openSync(record, constants.O_RDONLY | constants.O_NOFOLLOW); + try { + expect(JSON.parse(readFileSync(fd, "utf8"))).toEqual(values); + } finally { + closeSync(fd); + } + }); +}); diff --git a/packages/studio/src/components/panels/VariablesPanel.test.tsx b/packages/studio/src/components/panels/VariablesPanel.test.tsx index ec31c90b15..773d4fb5c1 100644 --- a/packages/studio/src/components/panels/VariablesPanel.test.tsx +++ b/packages/studio/src/components/panels/VariablesPanel.test.tsx @@ -24,11 +24,20 @@ const shell = { activeCompPath: "index.html" as string | null, compositions: ["index.html", "scene.html"], }; +const showToast = vi.fn(); +const copyTextToClipboard = vi.fn(async (_text: string) => true); vi.mock("../../contexts/StudioContext", () => ({ - useStudioShellContext: () => ({ activeCompPath: shell.activeCompPath, showToast: vi.fn() }), + useStudioShellContext: () => ({ + projectId: "demo", + activeCompPath: shell.activeCompPath, + showToast, + }), useStudioPlaybackContext: () => ({ refreshKey: 0 }), })); +vi.mock("../../utils/clipboard", () => ({ + copyTextToClipboard: (text: string) => copyTextToClipboard(text), +})); vi.mock("../../contexts/DomEditContext", () => ({ useDomEditContext: () => ({ domEditSelection: null }), })); @@ -47,8 +56,29 @@ afterEach(() => { act(() => root?.unmount()); root = null; document.body.innerHTML = ""; + showToast.mockClear(); + copyTextToClipboard.mockClear(); + vi.unstubAllGlobals(); }); +async function renderPanel(html: string): Promise { + const host = document.createElement("div"); + document.body.append(host); + root = createRoot(host); + const session = await openComposition(html, { history: false }); + await act(async () => { + root?.render( + {})} + />, + ); + }); + return host; +} + async function renderOtherCompositions(sessionPath: string): Promise { const host = document.createElement("div"); document.body.append(host); @@ -84,3 +114,62 @@ describe("VariablesPanel other compositions", () => { expect(await renderOtherCompositions("main.html")).not.toContain("main.html"); }); }); + +// A shared project's author writes these, so they reach the copied command as hostile text. +const HOSTILE = `x'; calc.exe; '" & calc.exe | calc.exe \\ $(id) %PATH%`; +const withHostileDefault = ` + +
+`; + +const button = (host: HTMLElement, label: string) => + [...host.querySelectorAll("button")].find((b) => b.textContent === label); + +describe("VariablesPanel render command", () => { + it("does not let a hostile variable default into the copied render command", async () => { + shell.activeCompPath = "compositions/intro.html"; + const fetch = vi.fn(async (_url: string, _init?: RequestInit) => new Response("{}")); + vi.stubGlobal("fetch", fetch); + const host = await renderPanel(withHostileDefault); + const expected = + "npx hyperframes render -c compositions/intro.html --variables-file .hyperframes/render-variables.json"; + + expect(host.querySelector("code")?.textContent).toBe(expected); + await act(async () => button(host, "Copy render command")?.click()); + + expect(copyTextToClipboard).toHaveBeenCalledWith(expected); + await vi.waitFor(() => expect(showToast).toHaveBeenCalledWith("Render command copied", "info")); + const [url, init] = fetch.mock.calls[0]!; + expect(url).toBe("/api/projects/demo/render-variables"); + expect(JSON.parse(String(init?.body))).toEqual({ title: HOSTILE }); + }); + + it("says the values were not saved when the server refuses them", async () => { + shell.activeCompPath = "index.html"; + vi.stubGlobal( + "fetch", + vi.fn(async () => new Response("{}", { status: 403 })), + ); + const host = await renderPanel(withHostileDefault); + + await act(async () => button(host, "Copy render command")?.click()); + + await vi.waitFor(() => + expect(showToast).toHaveBeenCalledWith( + "Couldn't save the values to .hyperframes/render-variables.json", + "error", + ), + ); + }); + + it("offers no render command for a composition whose name a shell reads as syntax", async () => { + shell.activeCompPath = "x';calc;'.html"; + const host = await renderPanel(withHostileDefault); + + expect(button(host, "Copy render command")).toBeUndefined(); + expect(button(host, "Copy values JSON")).toBeDefined(); + expect(host.textContent).not.toContain("npx hyperframes render"); + }); +}); diff --git a/packages/studio/src/components/panels/VariablesPanel.tsx b/packages/studio/src/components/panels/VariablesPanel.tsx index 0405dab98f..4d58ca8613 100644 --- a/packages/studio/src/components/panels/VariablesPanel.tsx +++ b/packages/studio/src/components/panels/VariablesPanel.tsx @@ -24,11 +24,8 @@ import { PreviewValueControl } from "./VariablesValueControls"; import { copyTextToClipboard } from "../../utils/clipboard"; import { resolveMasterCompositionPath } from "../../utils/studioUrlState"; import { isScalarVariableValue as isScalar } from "@hyperframes/core/variables"; - -/** POSIX single-quote escaping so the copied command survives quotes in values. */ -function shellSingleQuote(value: string): string { - return `'${value.replace(/'/g, `'\\''`)}'`; -} +import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders"; +import { renderHandoffCommand, saveRenderVariables } from "./renderHandoff"; export interface StudioEditPersistenceProps { sdkSession: Composition | null; @@ -195,34 +192,45 @@ function PreviewModeHeader({ } /** - * Developer/agent handoff: copy the effective values as JSON or as a - * ready-to-run render command mirroring exactly what the preview shows. + * Developer/agent handoff: copy the effective values as JSON, or a render + * command that reads them from the file Studio writes when it is copied. */ function HandoffFooter({ effectiveValues, compPath, onCopy, + onCopyCommand, }: { effectiveValues: Record; compPath: string; onCopy: (text: string, what: string) => void; + onCopyCommand: (command: string) => void; }) { const json = JSON.stringify(effectiveValues); - const command = `npx hyperframes render ${shellSingleQuote(compPath)} --variables ${shellSingleQuote(json)}`; + const command = renderHandoffCommand(compPath); return (

Use this template

- - {command} - + {command ? ( + + {command} + + ) : ( +

+ Rename this composition to letters, digits, _ . / - to + copy a render command. A shell would read other characters in its name as syntax. +

+ )}
- onCopy(command, "Render command")} - /> + {command && ( + onCopyCommand(command)} + /> + )} { + // Both start inside the click: a clipboard write after an await loses the user activation Safari requires. + const copied = copyTextToClipboard(command); + const saved = saveRenderVariables(projectId, effectiveValues); + void Promise.all([saved, copied]).then(([wasSaved, wasCopied]) => { + if (!wasCopied) showToast("Couldn't copy render command", "error"); + else if (!wasSaved) + showToast(`Couldn't save the values to ${RENDER_VARIABLES_FILE}`, "error"); + else showToast("Render command copied", "info"); + }); + }, + [projectId, effectiveValues, showToast], + ); + const dropPreviewOverride = useCallback( (id: string) => { if (previewValues && id in previewValues) { @@ -516,6 +539,7 @@ export const VariablesPanel = memo(function VariablesPanel({ effectiveValues={effectiveValues} compPath={effectiveCompPath ?? "index.html"} onCopy={copyToClipboard} + onCopyCommand={copyRenderCommand} /> )} {addOpen ? ( diff --git a/packages/studio/src/components/panels/renderHandoff.test.ts b/packages/studio/src/components/panels/renderHandoff.test.ts new file mode 100644 index 0000000000..239543f755 --- /dev/null +++ b/packages/studio/src/components/panels/renderHandoff.test.ts @@ -0,0 +1,86 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders"; +import { renderHandoffCommand, saveRenderVariables } from "./renderHandoff"; + +afterEach(() => { + vi.unstubAllGlobals(); +}); + +describe("renderHandoffCommand", () => { + it.each(["index.html", "compositions/intro.html", "scenes/v2_final-cut.html", "2026/q4.html"])( + "renders %s with the values file", + (compPath) => { + expect(renderHandoffCommand(compPath)).toBe( + `npx hyperframes render -c ${compPath} --variables-file .hyperframes/render-variables.json`, + ); + }, + ); + + it.each([ + "x';calc;'.html", + 'x";calc;".html', + "a&calc.html", + "a|calc.html", + "a;calc.html", + "a\\b.html", + "a b.html", + "$(id).html", + "`id`.html", + "%PATH%.html", + "a^b.html", + "a(b).html", + "a!b.html", + "a,b.html", + "a{b}.html", + "a*b.html", + "a\nb.html", + "~/a.html", + "@a.html", + "#a.html", + "-o.html", + "--output=x.html", + ".x.html", + "intró.html", + "", + ])("never puts a composition name a shell reads as syntax in the command: %j", (compPath) => { + expect(renderHandoffCommand(compPath)).toBeNull(); + }); + + it("names a values file that is one plain word in every shell", () => { + expect(RENDER_VARIABLES_FILE).toMatch(/^[A-Za-z0-9_./-]+$/); + }); +}); + +describe("saveRenderVariables", () => { + it("puts the values as JSON to the project's render-variables route", async () => { + const fetch = vi.fn(async () => new Response("{}", { status: 200 })); + vi.stubGlobal("fetch", fetch); + const values = { title: "It's Q4'; calc; '", count: 3 }; + + expect(await saveRenderVariables("my project", values)).toBe(true); + + expect(fetch).toHaveBeenCalledTimes(1); + const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit]; + expect(url).toBe("/api/projects/my%20project/render-variables"); + expect(init.method).toBe("PUT"); + expect(JSON.parse(String(init.body))).toEqual(values); + }); + + it("is false when the server refuses the write", async () => { + vi.stubGlobal( + "fetch", + vi.fn(async () => new Response("{}", { status: 403 })), + ); + expect(await saveRenderVariables("p", {})).toBe(false); + }); + + it("is false when the server cannot be reached", async () => { + vi.stubGlobal( + "fetch", + vi.fn(async () => { + throw new TypeError("Failed to fetch"); + }), + ); + expect(await saveRenderVariables("p", {})).toBe(false); + }); +}); diff --git a/packages/studio/src/components/panels/renderHandoff.ts b/packages/studio/src/components/panels/renderHandoff.ts new file mode 100644 index 0000000000..f9c3b0eebf --- /dev/null +++ b/packages/studio/src/components/panels/renderHandoff.ts @@ -0,0 +1,28 @@ +import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders"; +import { buildProjectApiPath } from "../../utils/projectRouting"; +import { studioApiFetch } from "../../utils/studioApiFetch"; + +// One literal word to sh, bash, zsh, fish, PowerShell and cmd.exe, also on cmd's second pass over npx.cmd's arguments. +// No one quoting is safe in all of them, so values go in a file and a path that is not such a word gets no command. +const SHELL_WORD = /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/; + +export function renderHandoffCommand(compPath: string): string | null { + if (!SHELL_WORD.test(compPath)) return null; + return `npx hyperframes render -c ${compPath} --variables-file ${RENDER_VARIABLES_FILE}`; +} + +export async function saveRenderVariables( + projectId: string, + values: Record, +): Promise { + try { + const response = await studioApiFetch(buildProjectApiPath(projectId, "/render-variables"), { + method: "PUT", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(values), + }); + return response.ok; + } catch { + return false; + } +} diff --git a/scripts/check-comment-citations.mjs b/scripts/check-comment-citations.mjs index 9c8c45cc2d..fa400b033f 100644 --- a/scripts/check-comment-citations.mjs +++ b/scripts/check-comment-citations.mjs @@ -191,8 +191,46 @@ function literalEnd(line, start, regex) { return -1; } +// Index just past the literal opening at `i` (string, template or regex), or -1. `before` is the code preceding it. +// A `/` after a value, `<`, `++` or `--` is division or a tag (`a / b`, `

`, `i++ / 2`). +function literalAt(line, i, before) { + const ch = line[i]; + if (ch === "`") return templateEnd(line, i); + // ponytail: `return /re/` reads as division; add a keyword check if that ever hides a comment. + const regex = ch === "/" && !/(?:[\w$)\]<]|\+\+|--)$/.test(before.trimEnd()); + const end = regex || `"'`.includes(ch) ? literalEnd(line, i, regex) : -1; + // A regex never closes on a comment opener: this `/` is division, e.g. continued from the line above. + return regex && (line[end] === "/" || line[end] === "*") ? -1 : end; +} + +// A `${…}` holds code, so a backtick in it opens a nested template rather than closing this one. +function templateEnd(line, start) { + for (let i = start + 1; i < line.length; i++) { + if (line[i] === "\\") i++; + else if (line[i] === "`") return i + 1; + else if (line[i] === "$" && line[i + 1] === "{") { + const end = substitutionEnd(line, i + 2); + if (end === -1) return -1; + i = end - 1; + } + } + return -1; +} + +function substitutionEnd(line, start) { + let depth = 0; + for (let i = start; i < line.length; ) { + const ch = line[i]; + if (ch === "}" && depth === 0) return i + 1; + if (ch === "{") depth++; + if (ch === "}") depth--; + const end = literalAt(line, i, line.slice(start, i)); + i = end === -1 ? i + 1 : end; + } + return -1; +} + /** stripStrings for C-like code, plus regex literals, so `/["'`]/` opens no string or template. - * A `/` after a value, `<`, `++` or `--` is division or a tag (`a / b`, `

`, `i++ / 2`). * Stops at the first comment. */ function stripLiterals(line) { let out = ""; @@ -200,11 +238,7 @@ function stripLiterals(line) { const ch = line[i]; const comment = ch === "/" && (line[i + 1] === "/" || line[i + 1] === "*"); if (comment) return out + line.slice(i); - // ponytail: `return /re/` reads as division; add a keyword check if that ever hides a comment. - const regex = ch === "/" && !/(?:[\w$)\]<]|\+\+|--)$/.test(out.trimEnd()); - let end = regex || `"'\``.includes(ch) ? literalEnd(line, i, regex) : -1; - // A regex never closes on a comment opener: this `/` is division, e.g. continued from the line above. - if (regex && (line[end] === "/" || line[end] === "*")) end = -1; + const end = literalAt(line, i, out); if (end === -1) { out += ch; i++; diff --git a/scripts/comment-ratchet.test.mjs b/scripts/comment-ratchet.test.mjs index ff78da3115..2d971616e1 100644 --- a/scripts/comment-ratchet.test.mjs +++ b/scripts/comment-ratchet.test.mjs @@ -44,6 +44,17 @@ test("quotes inside a regex literal open no string, so later comments still coun assert.equal(measure(source, ".ts").comment, 4); }); +test("a template nested in a substitution does not end the outer template, so later comments still count", () => { + const source = [ + "const quoted = `'${value.replace(/'/g, `'\\\\''`)}'`;", + "// one", + "const label = `${what} copied`; // two", + 'const deep = `a${b ? `c${d}` : "}"}e`;', + "// three", + ].join("\n"); + assert.equal(measure(source, ".ts").comment, 3); +}); + test("a JSX closing tag's slash opens no regex", () => { assert.equal(measure("const a =

x

; // c\n", ".tsx").comment, 1); assert.equal(measure("const a = x{/* note */};\n", ".tsx").comment, 1);