Files
hyperframes/packages/cli/src/timeline/a2Commands.ts
T

370 lines
12 KiB
TypeScript

import {
applyFileMutations,
fileContentVersion,
type AppliedFileMutation,
} from "@hyperframes/studio-server";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { readFileSync } from "node:fs";
import { join, relative } from "node:path";
import { describeProject, type ProjectTimeline, type TimelineRow } from "./describeProject.js";
import { resolveRef } from "./resolveRef.js";
import { parseTimeExpression } from "./timeExpr.js";
import { ensureDOMParser } from "../utils/dom.js";
import { resolveProject } from "../utils/project.js";
import { withMeta } from "../utils/updateCheck.js";
import {
allRows,
decideMutation,
diff,
fpsFor,
isRecord,
FIELDS_READ_BY_VERB,
mutationConflict,
positional,
publicReceipt,
refuse,
rowAt,
type MutationContext,
type MutationVerb,
isFileChanged,
refusal,
} from "./a2Shared.js";
export async function runIds(args: Record<string, unknown>): Promise<void> {
const project = resolveProject(typeof args.dir === "string" ? args.dir : undefined);
const json = args.json === true;
ensureDOMParser();
const beforeTimeline = await describeProject(project.indexPath);
const files = [...new Set(["index.html", ...allRows(beforeTimeline).map((row) => row.file)])];
const inputs = files.flatMap((file) => {
const before = readFileSync(join(project.dir, file), "utf-8");
const after = ensureHfIds(before);
return after === before
? []
: [
{
sourceFile: file,
absPath: join(project.dir, file),
before,
after,
expectedVersion: fileContentVersion(before),
},
];
});
let receipts: AppliedFileMutation[] = [];
try {
if (inputs.length > 0) receipts = applyFileMutations(project.dir, inputs);
} catch (error) {
if (isFileChanged(error))
return refusal(error.message, "re-run hyperframes timeline ids", json);
throw error;
}
const afterTimeline = await describeProject(project.indexPath);
const result = {
ok: true,
receipt: receipts.map((receipt) => publicReceipt(receipt)),
file: files,
before: allRows(beforeTimeline),
after: allRows(afterTimeline),
diff: "",
warnings: [],
};
if (json) console.log(JSON.stringify(withMeta(result), null, 2));
else console.log(`ids: stamped ${receipts.length} file${receipts.length === 1 ? "" : "s"}`);
}
type ApplyEditResult =
| { ok: true; file: string; after: string }
| { ok: false; reason: string; fix: string };
const PLAN_VERBS = new Set<MutationVerb>(["move", "trim", "split", "delete", "set", "duplicate"]);
type PreparedPlanEdit = {
ok: true;
edit: Record<string, unknown>;
row: TimelineRow;
before: string;
resolved: Extract<ReturnType<typeof resolveRef>, { ok: true }>;
};
function preparePlanEdit(
edit: unknown,
timeline: ProjectTimeline,
sourceByFile: Map<string, string>,
): PreparedPlanEdit | { ok: false; reason: string; fix: string } {
if (!isRecord(edit) || typeof edit.verb !== "string" || typeof edit.ref !== "string") {
return {
ok: false,
reason: "each edit needs a verb and ref",
fix: "pass {verb, ref, ...} objects",
};
}
if (!PLAN_VERBS.has(edit.verb as MutationVerb)) {
return {
ok: false,
reason: `unsupported edit verb ${edit.verb}`,
fix: "use move, trim, split, delete, set, or duplicate",
};
}
const fields = FIELDS_READ_BY_VERB[edit.verb as MutationVerb];
const unused = Object.keys(edit).find(
(key) => key !== "verb" && key !== "ref" && !fields.includes(key),
);
if (unused) {
return {
ok: false,
reason: `${edit.verb} does not use ${unused}`,
fix: `remove ${unused}; ${edit.verb} takes ${fields.join(", ")}`,
};
}
const resolved = resolveRef(timeline, edit.ref);
if (!resolved.ok) return resolved;
const before = sourceByFile.get(resolved.row.file);
return before === undefined
? { ok: false, reason: `${resolved.row.file} was not found`, fix: "choose an existing clip" }
: { ok: true, edit, row: resolved.row, before, resolved };
}
function applyPlanEdit(
edit: unknown,
timeline: ProjectTimeline,
project: ReturnType<typeof resolveProject>,
sourceByFile: Map<string, string>,
): ApplyEditResult {
const prepared = preparePlanEdit(edit, timeline, sourceByFile);
if (!prepared.ok) return prepared;
const { edit: planEdit, row, before, resolved } = prepared;
const verb = planEdit.verb as MutationVerb;
const context: MutationContext = {
ref: planEdit.ref as string,
row,
before,
resolved,
parseTime: (expression) =>
parseTimeExpression(expression, {
row,
duration: timeline.duration,
fps: fpsFor(project.indexPath),
resolveAnchor: (anchorRef) => {
const anchor = resolveRef(timeline, anchorRef);
return anchor.ok ? anchor.row : undefined;
},
}),
duration: row.nested && row.hostRow ? rowAt(timeline, row.hostRow).duration : timeline.duration,
};
const decision = decideMutation(verb, context, { ...planEdit, _: [planEdit.ref] });
if (!decision.ok) return { ok: false, reason: decision.reason, fix: decision.fix };
const conflict = mutationConflict(
verb as MutationVerb,
planEdit.overwrite === true,
row,
timeline,
decision.nextStart,
decision.nextDuration,
);
if (conflict) return { ok: false, reason: conflict.reason, fix: conflict.fix };
return { ok: true, file: row.file, after: decision.after };
}
type EditPlan = { ok: true; edits: unknown[] } | { ok: false; reason: string; fix: string };
function readEditPlan(file: string): EditPlan {
const raw = file === "-" ? readFileSync(0, "utf-8") : readFileSync(file, "utf-8");
try {
const edits: unknown = JSON.parse(raw);
return Array.isArray(edits)
? { ok: true, edits }
: { ok: false, reason: "edit plan must be a JSON array", fix: "pass a JSON array of edits" };
} catch {
return { ok: false, reason: "edit plan is not valid JSON", fix: "pass a JSON array of edits" };
}
}
function readPlanSources(
timeline: ProjectTimeline,
project: ReturnType<typeof resolveProject>,
): { sourceByFile: Map<string, string>; beforeByFile: Map<string, string> } {
const sourceByFile = new Map<string, string>();
const beforeByFile = new Map<string, string>();
for (const fileName of new Set(allRows(timeline).map((row) => row.file))) {
const source = readFileSync(join(project.dir, fileName), "utf-8");
sourceByFile.set(fileName, source);
beforeByFile.set(fileName, source);
}
return { sourceByFile, beforeByFile };
}
async function applyPlanEdits(
edits: unknown[],
timeline: ProjectTimeline,
project: ReturnType<typeof resolveProject>,
sourceByFile: Map<string, string>,
): Promise<{ ok: true } | { ok: false; reason: string; fix: string }> {
for (const edit of edits) {
const result = applyPlanEdit(edit, timeline, project, sourceByFile);
if (!result.ok) return result;
sourceByFile.set(result.file, result.after);
timeline = await describeProject(project.indexPath, undefined, sourceByFile);
}
return { ok: true };
}
export async function runApply(args: Record<string, unknown>): Promise<void> {
const project = resolveProject(typeof args.dir === "string" ? args.dir : undefined);
const json = args.json === true;
const plan = args.plan === true;
const file = typeof args.file === "string" ? args.file : positional(args)[1];
if (!file)
return refuse(
"timeline apply",
{ reason: "an edit plan is required", fix: "pass an edits.json path or -" },
json,
);
const planInput = readEditPlan(file);
if (!planInput.ok) return refuse("timeline apply", planInput, json);
ensureDOMParser();
const timeline = await describeProject(project.indexPath);
const { sourceByFile, beforeByFile } = readPlanSources(timeline, project);
const editsResult = await applyPlanEdits(planInput.edits, timeline, project, sourceByFile);
if (!editsResult.ok) return refuse("timeline apply", editsResult, json);
const inputs = [...sourceByFile].flatMap(([fileName, after]) => {
const before = beforeByFile.get(fileName)!;
return after === before
? []
: [
{
sourceFile: fileName,
absPath: join(project.dir, fileName),
before,
after,
expectedVersion: fileContentVersion(before),
},
];
});
const afterTimeline = await describeProject(project.indexPath, undefined, sourceByFile);
const result = {
ok: true,
planned: plan,
receipt: null as unknown,
file: inputs.map((input) => input.sourceFile),
before: allRows(timeline),
after: allRows(afterTimeline),
diff: inputs
.map((input) => diff(input.before, input.after))
.filter(Boolean)
.join("\n"),
warnings: [],
};
if (!plan) {
const receipts = inputs.length > 0 ? applyFileMutations(project.dir, inputs) : [];
result.receipt = receipts.map((receipt) => publicReceipt(receipt));
}
if (json) console.log(JSON.stringify(withMeta(result), null, 2));
else
console.log(
`${plan ? "planned" : "applied"} ${inputs.length} file${inputs.length === 1 ? "" : "s"}`,
);
}
type UndoReceipt = { file: string; version: string; backupPath: string };
function isUndoReceipt(value: unknown): value is UndoReceipt {
return (
isRecord(value) &&
typeof value.file === "string" &&
typeof value.version === "string" &&
typeof value.backupPath === "string"
);
}
type UndoInput =
| { ok: true; receipts: UndoReceipt[]; batch: boolean }
| { ok: false; reason: string; fix: string };
function readUndoInput(input: string): UndoInput {
let raw: string;
try {
raw = readFileSync(input, "utf-8");
} catch {
raw = input;
}
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return {
ok: false,
reason: "undo receipt is not valid JSON",
fix: "pass the applied JSON receipt",
};
}
const value = isRecord(parsed) && "receipt" in parsed ? parsed.receipt : parsed;
const values: unknown[] = Array.isArray(value) ? value : [value];
if (!values.every(isUndoReceipt)) {
return {
ok: false,
reason: "undo receipt is missing file, version, or backupPath",
fix: "pass an applied timeline receipt",
};
}
return { ok: true, receipts: values, batch: Array.isArray(value) };
}
function refuseUndoError(error: unknown, projectDir: string, json: boolean): void {
if (isRecord(error) && error.code === "ENOENT" && typeof error.path === "string")
return refuse(
"timeline undo",
{
reason: `undo file is missing: ${relative(projectDir, error.path).split("\\").join("/")}`,
fix: "restore the missing target or backup file before retrying undo",
},
json,
);
if (isFileChanged(error))
return refusal(error.message, "read the latest timeline before retrying undo", json);
throw error;
}
export async function runUndo(args: Record<string, unknown>): Promise<void> {
const project = resolveProject(typeof args.dir === "string" ? args.dir : undefined, {
requireIndex: false,
});
const json = args.json === true;
const input = typeof args.receipt === "string" ? args.receipt : positional(args)[1];
if (!input)
return refuse(
"timeline undo",
{ reason: "an undo receipt is required", fix: "pass the receipt JSON or its file" },
json,
);
const undo = readUndoInput(input);
if (!undo.ok) return refuse("timeline undo", undo, json);
let receipts: AppliedFileMutation[];
try {
const inputs = undo.receipts.map((receipt) => {
const target = join(project.dir, receipt.file);
return {
sourceFile: receipt.file,
absPath: target,
before: readFileSync(target, "utf-8"),
after: readFileSync(join(project.dir, receipt.backupPath), "utf-8"),
expectedVersion: receipt.version,
};
});
receipts = applyFileMutations(project.dir, inputs);
} catch (error) {
return refuseUndoError(error, project.dir, json);
}
const result = {
ok: true,
receipt: receipts.map((receipt) => publicReceipt(receipt)),
file: undo.batch ? undo.receipts.map((receipt) => receipt.file) : undo.receipts[0]!.file,
};
if (json) console.log(JSON.stringify(withMeta(result), null, 2));
else
console.log(
undo.batch
? `undid ${receipts.length} file${receipts.length === 1 ? "" : "s"}`
: `undid ${undo.receipts[0]!.file}`,
);
}