Skip to content

Write HTML. Render video. Built for agents.

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.ts
index 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.ts
index 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 {