Skip to content

Commit d2b8ea7

Browse files
fix(cli): timeline delete --start/--end removes only that range (#5867)
* fix(cli): timeline delete --start/--end removes only that range timeline delete accepted --start and --end but never read them, so a range delete removed the whole clip. It now cuts out only that range, the same way split, split, delete would, and keeps the parts before and after. Every edit verb shared one flag set, so a verb silently ignored flags it does not use. Each verb now declares only the options it reads, from one table that also checks apply-plan keys, so an unused flag or key is refused before anything is written. * refactor(cli): name the per-verb option table instead of commenting it
1 parent 2a14cbc commit d2b8ea7

5 files changed

Lines changed: 206 additions & 32 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1125,14 +1125,15 @@ npx hyperframes timeline split '#outro' 6.5
11251125
npx hyperframes timeline set '#music' volume=0.5
11261126
npx hyperframes timeline duplicate '#intro' --at 3
11271127
npx hyperframes timeline delete '#outro' --json
1128+
npx hyperframes timeline delete '#outro' --start 6 --end 7 # cut one second out
11281129
```
11291130

11301131
| Command | What it does |
11311132
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
11321133
| `move <ref> <time>` | Start the clip at `<time>`, keeping its length |
11331134
| `trim <ref>` | Change the clip's `--start`, `--end`, or `--duration` (at least one) |
11341135
| `split <ref> <time>` | Cut the clip in two at `<time>` |
1135-
| `delete <ref>` | Remove the clip |
1136+
| `delete <ref>` | Remove the clip, or only its `--start` to `--end` range, keeping the parts before and after |
11361137
| `set <ref> <field>=<value>` | Set `volume`, `rate` (playback rate) or `track` (a whole number) |
11371138
| `duplicate <ref>` | Copy the clip to `--at <time>` (default: right after the clip) |
11381139
| `apply <file>` | Apply a JSON array of edits, such as `[{"verb": "move", "ref": "#intro", "time": "+1"}]`, all or nothing. Pass `-` to read it from stdin. |
@@ -1141,13 +1142,14 @@ npx hyperframes timeline delete '#outro' --json
11411142

11421143
A time is seconds (`4.5`), an offset from the clip's start (`+1`, `-0.5`),
11431144
frames (`30f`), `end`, or an anchor on another clip: `after:#intro`,
1144-
`before:#intro`, `start-of:#intro` or `end-of:#intro`.
1145+
`before:#intro`, `start-of:#intro` or `end-of:#intro`. A flag an edit command does not
1146+
use is refused before anything is written.
11451147

11461148
| Flag | Applies to | Description |
11471149
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
11481150
| `--plan` | `move`, `trim`, `split`, `delete`, `set`, `duplicate`, `apply` | Print the result and the diff without writing |
11491151
| `--overwrite` | `move`, `trim` | Allow the clip to overlap a neighbour on its track |
1150-
| `--snap` | `move`, `trim`, `split`, `duplicate` | Round times to whole frames. Needs `data-fps` on the project. |
1152+
| `--snap` | `move`, `trim`, `split`, `delete`, `duplicate` | Round times to whole frames. Needs `data-fps` on the project. |
11511153
| `--at` | `duplicate` | Where the copy starts |
11521154
| `--dir` | all edit commands | Project directory (default: current) |
11531155
| `--json` | all edit commands | Machine-readable result, with the receipt `undo` takes |

‎packages/cli/src/commands/timeline.ts‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { defineCommand } from "citty";
1+
import { defineCommand, type ArgDef } from "citty";
22
import type { Example } from "./_examples.js";
33
import { describeProject } from "../timeline/describeProject.js";
44
import { formatTimeline } from "../timeline/formatTimeline.js";
@@ -7,7 +7,7 @@ import { resolveProject } from "../utils/project.js";
77
import { withMeta } from "../utils/updateCheck.js";
88
import { runApply, runIds, runUndo } from "../timeline/a2Commands.js";
99
import { runMutation } from "../timeline/a2MutationCommand.js";
10-
import type { MutationVerb } from "../timeline/a2Shared.js";
10+
import { FIELDS_READ_BY_VERB, type MutationVerb } from "../timeline/a2Shared.js";
1111
import { resolveExtraPositionals } from "../utils/reject-extra-positionals.js";
1212
import { assertKnownFlags } from "../utils/reject-unknown-flags.js";
1313

@@ -17,21 +17,30 @@ export const examples: Example[] = [
1717
["Delete a clip and return a receipt", "hyperframes timeline delete '#hero' --json"],
1818
];
1919

20+
const MUTATION_OPTIONS: Record<string, ArgDef> = {
21+
time: { type: "positional", required: true },
22+
at: { type: "string" },
23+
start: { type: "string" },
24+
end: { type: "string" },
25+
duration: { type: "string" },
26+
volume: { type: "string" },
27+
rate: { type: "string" },
28+
track: { type: "string" },
29+
overwrite: { type: "boolean", default: false },
30+
};
31+
2032
function mutationCommand(verb: MutationVerb) {
33+
const fields = FIELDS_READ_BY_VERB[verb];
2134
return defineCommand({
2235
meta: { name: verb, description: `${verb} a timeline clip` },
2336
args: {
2437
ref: { type: "positional", required: true },
25-
time: { type: "positional", required: verb === "move" || verb === "split" },
26-
at: { type: "string" },
38+
...(verb === "set" && { assignment: { type: "positional", required: false } }),
39+
...Object.fromEntries(fields.map((field) => [field, MUTATION_OPTIONS[field]!])),
2740
dir: { type: "string" },
28-
start: { type: "string" },
29-
end: { type: "string" },
30-
duration: { type: "string" },
3141
plan: { type: "boolean", default: false },
3242
json: { type: "boolean", default: false },
33-
overwrite: { type: "boolean", default: false },
34-
snap: { type: "boolean", default: false },
43+
...(verb !== "set" && { snap: { type: "boolean", default: false } }),
3544
},
3645
async run({ args }) {
3746
await runMutation(verb, args);

‎packages/cli/src/timeline/a2Commands.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import {
1818
diff,
1919
fpsFor,
2020
isRecord,
21+
FIELDS_READ_BY_VERB,
2122
mutationConflict,
2223
positional,
2324
publicReceipt,
@@ -104,6 +105,17 @@ function preparePlanEdit(
104105
fix: "use move, trim, split, delete, set, or duplicate",
105106
};
106107
}
108+
const fields = FIELDS_READ_BY_VERB[edit.verb as MutationVerb];
109+
const unused = Object.keys(edit).find(
110+
(key) => key !== "verb" && key !== "ref" && !fields.includes(key),
111+
);
112+
if (unused) {
113+
return {
114+
ok: false,
115+
reason: `${edit.verb} does not use ${unused}`,
116+
fix: `remove ${unused}; ${edit.verb} takes ${fields.join(", ")}`,
117+
};
118+
}
107119
const resolved = resolveRef(timeline, edit.ref);
108120
if (!resolved.ok) return resolved;
109121
const before = sourceByFile.get(resolved.row.file);

‎packages/cli/src/timeline/a2Shared.ts‎

Lines changed: 97 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@ import {
44
removeElementFromHtml,
55
splitElementInHtml,
66
} from "@hyperframes/studio-server";
7-
import type { AppliedFileMutation, PatchOperation } from "@hyperframes/studio-server";
7+
import type {
8+
AppliedFileMutation,
9+
PatchOperation,
10+
SourceMutationTarget,
11+
} from "@hyperframes/studio-server";
812
import { fpsToNumber, parseFpsWithDefault } from "@hyperframes/core";
913
import { isInsideSpan, sameInstant, spansShareTime } from "@hyperframes/core/clip-facts";
1014
import { readCompositionFps } from "../utils/compositionFps.js";
@@ -17,6 +21,15 @@ import { parseSetAssignments, type SetAssignment } from "./a2Mutations.js";
1721

1822
export type MutationVerb = "move" | "trim" | "split" | "delete" | "set" | "duplicate";
1923

24+
export const FIELDS_READ_BY_VERB: Record<MutationVerb, readonly string[]> = {
25+
move: ["time", "overwrite"],
26+
trim: ["start", "end", "duration", "overwrite"],
27+
split: ["time"],
28+
delete: ["start", "end"],
29+
set: ["volume", "rate", "track"],
30+
duplicate: ["at"],
31+
};
32+
2033
export type MutationDecision =
2134
| { ok: true; after: string; nextStart: number; nextDuration: number }
2235
| { ok: false; reason: string; fix: string };
@@ -196,24 +209,14 @@ function splitMutation(context: MutationContext, args: Record<string, unknown>):
196209
const expression = typeof args.time === "string" ? args.time : "";
197210
const time = parseMutationTime(context, expression, "pass a valid time expression");
198211
if (!time.ok) return time;
199-
const split = splitElementInHtml(
212+
const split = splitSource(
213+
context,
200214
context.before,
201215
context.resolved.target,
202216
time.seconds,
203-
nextFreeSplitId(context.before, splitBaseId(context.row)),
204-
{
205-
start: context.row.start,
206-
duration: context.row.duration,
207-
track: context.row.trackIndex,
208-
},
217+
context.row.duration,
209218
);
210-
if (!split.matched || !split.newId) {
211-
return {
212-
ok: false,
213-
reason: `${context.ref} cannot be split at ${time.seconds}`,
214-
fix: "choose a time inside the clip",
215-
};
216-
}
219+
if (!split.ok) return split;
217220
return {
218221
ok: true,
219222
after: split.html,
@@ -222,6 +225,30 @@ function splitMutation(context: MutationContext, args: Record<string, unknown>):
222225
};
223226
}
224227

228+
function splitSource(
229+
context: MutationContext,
230+
source: string,
231+
target: SourceMutationTarget,
232+
seconds: number,
233+
duration: number,
234+
): { ok: true; html: string; newId: string } | { ok: false; reason: string; fix: string } {
235+
const split = splitElementInHtml(
236+
source,
237+
target,
238+
seconds,
239+
nextFreeSplitId(source, splitBaseId(context.row)),
240+
{ start: context.row.start, duration, track: context.row.trackIndex },
241+
);
242+
if (!split.matched || !split.newId) {
243+
return {
244+
ok: false,
245+
reason: `${context.ref} cannot be split at ${seconds}`,
246+
fix: "choose a time inside the clip",
247+
};
248+
}
249+
return { ok: true, html: split.html, newId: split.newId };
250+
}
251+
225252
function trimMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
226253
const bounds = trimBounds(context, args);
227254
if (!bounds.ok) return bounds;
@@ -321,15 +348,65 @@ function trimDuration(context: MutationContext, expression: string | undefined)
321348
return parseMutationTime(context, expression, "pass a valid duration");
322349
}
323350

324-
function deleteMutation(context: MutationContext): MutationDecision {
351+
function deleteMutation(context: MutationContext, args: Record<string, unknown>): MutationDecision {
352+
const { row, resolved } = context;
353+
const range = deleteRange(context, args);
354+
if (!range.ok) return range;
355+
let html = context.before;
356+
if (!sameInstant(range.end, row.end)) {
357+
const tail = splitSource(context, html, resolved.target, range.end, row.duration);
358+
if (!tail.ok) return tail;
359+
html = tail.html;
360+
}
361+
let removed = resolved.target;
362+
if (!sameInstant(range.start, row.start)) {
363+
const middle = splitSource(context, html, resolved.target, range.start, range.end - row.start);
364+
if (!middle.ok) return middle;
365+
html = middle.html;
366+
removed = { id: middle.newId };
367+
}
325368
return {
326369
ok: true,
327-
after: removeElementFromHtml(context.before, context.resolved.target),
328-
nextStart: context.row.start,
329-
nextDuration: context.row.duration,
370+
after: removeElementFromHtml(html, removed),
371+
nextStart: row.start,
372+
nextDuration: row.duration,
330373
};
331374
}
332375

376+
function deleteRange(
377+
context: MutationContext,
378+
args: Record<string, unknown>,
379+
): { ok: true; start: number; end: number } | { ok: false; reason: string; fix: string } {
380+
const { row } = context;
381+
const bound = (value: unknown, fallback: number): ParsedMutationTime =>
382+
typeof value === "string"
383+
? parseMutationTime(context, value, "pass a valid time expression")
384+
: { ok: true, seconds: fallback };
385+
const start = bound(args.start, row.start);
386+
if (!start.ok) return start;
387+
const end = bound(args.end, row.end);
388+
if (!end.ok) return end;
389+
const inside = (seconds: number) =>
390+
sameInstant(seconds, row.start) ||
391+
sameInstant(seconds, row.end) ||
392+
(seconds > row.start && seconds < row.end);
393+
if (!inside(start.seconds) || !inside(end.seconds)) {
394+
return {
395+
ok: false,
396+
reason: `delete range ${start.seconds}-${end.seconds} is not inside ${context.ref} (${row.start}-${row.end})`,
397+
fix: "pass --start and --end inside the clip",
398+
};
399+
}
400+
if (end.seconds <= start.seconds || sameInstant(start.seconds, end.seconds)) {
401+
return {
402+
ok: false,
403+
reason: "delete range must be positive",
404+
fix: "pass an --end later than --start",
405+
};
406+
}
407+
return { ok: true, start: start.seconds, end: end.seconds };
408+
}
409+
333410
function setOperation(assignment: SetAssignment): PatchOperation {
334411
const property =
335412
assignment.field === "volume"
@@ -403,7 +480,7 @@ export function decideMutation(
403480
case "split":
404481
return splitMutation(context, args);
405482
case "delete":
406-
return deleteMutation(context);
483+
return deleteMutation(context, args);
407484
case "set":
408485
return setMutation(context, args);
409486
case "duplicate":

‎packages/cli/src/timeline/timeline.e2e.test.ts‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,80 @@ describe("timeline edit command", () => {
212212
}
213213
});
214214

215+
it("deletes only the --start/--end range of a video clip, keeping both sides", () => {
216+
const dir = mkdtempSync(join(tmpdir(), "hf-timeline-range-delete-"));
217+
try {
218+
const indexPath = join(dir, "index.html");
219+
writeFileSync(
220+
indexPath,
221+
`<div data-composition-id="main" data-duration="12"><video id="clip" src="a.mp4" data-start="1" data-duration="4" data-track-index="0"></video></div>`,
222+
);
223+
const planned = run(dir, "delete", "#clip", "--start", "2", "--end", "3", "--plan");
224+
expect(planned.status, planned.stderr).toBe(0);
225+
const kept = [
226+
expect.objectContaining({ ref: "#clip", start: 1, end: 2 }),
227+
expect.objectContaining({ ref: "#clip-2", start: 3, end: 5 }),
228+
];
229+
expect(JSON.parse(planned.stdout).after).toEqual(kept);
230+
const applied = run(dir, "delete", "#clip", "--start", "2", "--end", "3");
231+
expect(applied.status, applied.stderr).toBe(0);
232+
expect(JSON.parse(applied.stdout).after).toEqual(kept);
233+
const html = readFileSync(indexPath, "utf8");
234+
const tag = (id: string) => html.match(new RegExp(`<[^>]*\\sid="${id}"[^>]*>`))?.[0];
235+
expect(tag("clip-2")).toContain('data-media-start="2"');
236+
expect(html).not.toContain('id="clip-3"');
237+
} finally {
238+
rmSync(dir, { recursive: true, force: true });
239+
}
240+
});
241+
242+
it("refuses a delete range that reaches outside the clip, without writing", () => {
243+
const dir = project();
244+
try {
245+
const before = readFileSync(join(dir, "index.html"), "utf8");
246+
const result = run(dir, "delete", "#clip", "--start", "2", "--end", "4");
247+
expect(result.status).toBe(2);
248+
expect(result.stderr).toContain("is not inside #clip");
249+
expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
250+
} finally {
251+
rmSync(dir, { recursive: true, force: true });
252+
}
253+
});
254+
255+
it.each([
256+
["--at", ["delete", "#clip", "--at", "2"]],
257+
["--start", ["split", "#clip", "2", "--start", "1"]],
258+
["--duration", ["move", "#clip", "+1", "--duration", "1"]],
259+
["--overwrite", ["duplicate", "#clip", "--overwrite"]],
260+
["--end", ["set", "#clip", "volume=0.5", "--end", "2"]],
261+
])("refuses a flag its verb does not use (%s), without writing", (flag, args) => {
262+
const dir = project();
263+
try {
264+
const before = readFileSync(join(dir, "index.html"), "utf8");
265+
const result = run(dir, ...args);
266+
expect(result.status).not.toBe(0);
267+
expect(result.stderr).toContain(`Unknown flag: ${flag}`);
268+
expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
269+
} finally {
270+
rmSync(dir, { recursive: true, force: true });
271+
}
272+
});
273+
274+
it("refuses an apply edit with a key its verb does not use, without writing", () => {
275+
const dir = project();
276+
try {
277+
const before = readFileSync(join(dir, "index.html"), "utf8");
278+
const planPath = join(dir, "edits.json");
279+
writeFileSync(planPath, JSON.stringify([{ verb: "delete", ref: "#clip", at: "2" }]));
280+
const result = run(dir, "apply", planPath);
281+
expect(result.status).toBe(2);
282+
expect(result.stderr).toContain("delete does not use at");
283+
expect(readFileSync(join(dir, "index.html"), "utf8")).toBe(before);
284+
} finally {
285+
rmSync(dir, { recursive: true, force: true });
286+
}
287+
});
288+
215289
it("uses the next free numeric split suffix on repeat", () => {
216290
const dir = project();
217291
try {

0 commit comments

Comments
 (0)