Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): route timeline project directories to inspection (#5240)
Abdullah M. Nazifee64ebe33815
diff --git a/packages/cli/src/commands/timeline.ts b/packages/cli/src/commands/timeline.tsindex 3b8b126a41..6de540cf50 100644--- a/packages/cli/src/commands/timeline.ts+++ b/packages/cli/src/commands/timeline.ts@@ -8,6 +8,8 @@ import { withMeta } from "../utils/updateCheck.js";import { runApply, runIds, runUndo } from "../timeline/a2Commands.js";import { runMutation } from "../timeline/a2MutationCommand.js";import type { MutationVerb } from "../timeline/a2Shared.js";+import { resolveExtraPositionals } from "../utils/reject-extra-positionals.js";+import { assertKnownFlags } from "../utils/reject-unknown-flags.js";export const examples: Example[] = [["Show every track and clip of the project in the current directory", "hyperframes timeline"],@@ -37,55 +39,72 @@ function mutationCommand(verb: MutationVerb) {});}+const subCommands = {+ move: () => mutationCommand("move"),+ trim: () => mutationCommand("trim"),+ split: () => mutationCommand("split"),+ delete: () => mutationCommand("delete"),+ set: () => mutationCommand("set"),+ duplicate: () => mutationCommand("duplicate"),+ ids: () =>+ defineCommand({+ meta: { name: "ids", description: "Stamp stable ids on timeline clips" },+ args: { dir: { type: "string" }, json: { type: "boolean", default: false } },+ async run({ args }) {+ await runIds(args);+ },+ }),+ apply: () =>+ defineCommand({+ meta: { name: "apply", description: "Apply an atomic timeline edit plan" },+ args: {+ file: { type: "positional", required: true },+ dir: { type: "string" },+ json: { type: "boolean", default: false },+ plan: { type: "boolean", default: false },+ },+ async run({ args }) {+ await runApply(args);+ },+ }),+ undo: () =>+ defineCommand({+ meta: { name: "undo", description: "Restore a timeline mutation receipt" },+ args: {+ receipt: { type: "positional", required: true },+ dir: { type: "string" },+ json: { type: "boolean", default: false },+ },+ async run({ args }) {+ await runUndo(args);+ },+ }),+};++function isTimelineSubcommand(first: string | undefined, rawArgs: string[]): boolean {+ if (!first || !Object.hasOwn(subCommands, first)) return false;+ const separator = rawArgs.indexOf("--");+ return separator < 0 || rawArgs.indexOf(first) < separator;+}+export default defineCommand({meta: { name: "timeline", description: "Print and edit the project's tracks and clips" },args: {dir: { type: "positional", description: "Project directory", required: false },json: { type: "boolean", description: "Output as JSON", default: false },},- subCommands: {- move: () => mutationCommand("move"),- trim: () => mutationCommand("trim"),- split: () => mutationCommand("split"),- delete: () => mutationCommand("delete"),- set: () => mutationCommand("set"),- duplicate: () => mutationCommand("duplicate"),- ids: () =>- defineCommand({- meta: { name: "ids", description: "Stamp stable ids on timeline clips" },- args: { dir: { type: "string" }, json: { type: "boolean", default: false } },- async run({ args }) {- await runIds(args);- },- }),- apply: () =>- defineCommand({- meta: { name: "apply", description: "Apply an atomic timeline edit plan" },- args: {- file: { type: "positional", required: true },- dir: { type: "string" },- json: { type: "boolean", default: false },- plan: { type: "boolean", default: false },- },- async run({ args }) {- await runApply(args);- },- }),- undo: () =>- defineCommand({- meta: { name: "undo", description: "Restore a timeline mutation receipt" },- args: {- receipt: { type: "positional", required: true },- dir: { type: "string" },- json: { type: "boolean", default: false },- },- async run({ args }) {- await runUndo(args);- },- }),+ subCommands,+ setup({ args, rawArgs, cmd }) {+ const first = args._[0];+ if (!first || isTimelineSubcommand(first, rawArgs)) return;+ assertKnownFlags({ args: cmd.args }, rawArgs);+ const separator = rawArgs.indexOf("--");+ const directoryIndex = rawArgs.indexOf(first);+ if (separator < 0 || directoryIndex < separator) rawArgs.splice(directoryIndex, 0, "--");},- async run({ args }) {- if (args._?.[0]) return;+ async run({ args, rawArgs, cmd }) {+ if (isTimelineSubcommand(args._[0], rawArgs)) return;+ resolveExtraPositionals({ args: cmd.args }, "timeline", args);const project = resolveProject(args.dir);ensureDOMParser();const timeline = await describeProject(project.indexPath);diff --git a/packages/cli/src/timeline/timeline.e2e.test.ts b/packages/cli/src/timeline/timeline.e2e.test.tsindex 3451cf1ca3..118399a0a5 100644--- a/packages/cli/src/timeline/timeline.e2e.test.ts+++ b/packages/cli/src/timeline/timeline.e2e.test.ts@@ -1,5 +1,5 @@import { spawnSync } from "node:child_process";-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join, resolve } from "node:path";import { fileURLToPath } from "node:url";@@ -30,6 +30,78 @@ function run(dir: string, ...args: string[]) {);}+describe("timeline project inspection", () => {+ it.each([+ { name: "absolute", directory: "absolute", json: true, flagFirst: false },+ { name: "relative", directory: "relative", json: true, flagFirst: false },+ { name: "JSON before directory", directory: "absolute", json: true, flagFirst: true },+ { name: "text", directory: "relative", json: false, flagFirst: false },+ { name: "subcommand-named directory", directory: "move", json: true, flagFirst: false },+ { name: "literal subcommand name", directory: "literalMove", json: true, flagFirst: false },+ ])("inspects a $name project from another directory", ({ directory, json, flagFirst }) => {+ const parent = mkdtempSync(join(tmpdir(), "hf-timeline-inspect-"));+ try {+ const name =+ directory === "move" || directory === "literalMove" ? "move" : "project with spaces";+ const target = join(parent, name);+ mkdirSync(target);+ const source =+ '<div data-composition-id="main" data-duration="7"><div id="chosen-project" data-start="1" data-duration="2"></div></div>';+ writeFileSync(join(target, "index.html"), source);+ const argument = directory === "absolute" ? target : `./${name}`;+ const args =+ directory === "literalMove"+ ? ["--json", "--", "move"]+ : json+ ? flagFirst+ ? ["--json", argument]+ : [argument, "--json"]+ : [argument];+ const result = spawnSync("bun", ["run", cliEntry, "timeline", ...args], {+ cwd: parent,+ encoding: "utf8",+ timeout: 30_000,+ env: { ...process.env, HYPERFRAMES_SKIP_UPDATE_CHECK: "1" },+ });+ expect(result.status, result.stderr).toBe(0);+ if (json) {+ const output: unknown = JSON.parse(result.stdout);+ expect(output).toMatchObject({+ timeline: { duration: 7, tracks: [{ rows: [{ id: "chosen-project" }] }] },+ });+ } else {+ expect(result.stdout).toContain("timeline 7s");+ expect(result.stdout).toContain("#chosen-project chosen-project 1-3s");+ }+ expect(readFileSync(join(target, "index.html"), "utf8")).toBe(source);+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it.each([+ { args: ["--json", "--unknown-option"], diagnostic: "Unknown flag: --unknown-option" },+ { args: ["--json", "extra-project"], diagnostic: "Unexpected extra argument" },+ { args: ["--", "extra-project"], diagnostic: "Unexpected extra argument" },+ ])("keeps inspection argument validation for $diagnostic", ({ args, diagnostic }) => {+ const dir = project();+ const source = readFileSync(join(dir, "index.html"), "utf8");+ try {+ const result = spawnSync("bun", ["run", cliEntry, "timeline", dir, ...args], {+ cwd: dir,+ encoding: "utf8",+ timeout: 30_000,+ env: { ...process.env, HYPERFRAMES_SKIP_UPDATE_CHECK: "1" },+ });+ expect(result.status).not.toBe(0);+ expect(result.stderr + result.stdout).toContain(diagnostic);+ expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(source);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });+});+describe("timeline edit command", () => {it.each([["move", ["#clip", "+1"], 'data-start="2"'],@@ -63,6 +135,23 @@ describe("timeline edit command", () => {}});+ it("runs an edit subcommand whose clip reference follows an argument separator", () => {+ const dir = project();+ try {+ const result = run(dir, "move", "--plan", "--", "#clip", "+1");+ expect(result.status, result.stderr).toBe(0);+ const output: unknown = JSON.parse(result.stdout);+ expect(output).toMatchObject({+ ok: true,+ planned: true,+ after: expect.arrayContaining([expect.objectContaining({ ref: "#clip", start: 2 })]),+ });+ expect(readFileSync(join(dir, "index.html"), "utf8")).toContain('data-start="1"');+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });+it("names an id-less hf ref split from its stable id", () => {const dir = project();try {