kaizen-agent 1.49.0 → 1.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/agents/kaizen-reviewer.md +1 -1
  2. package/cli/hermes.ts +5 -2
  3. package/cli/notes.test.ts +1 -1
  4. package/cli/settings.test.ts +2 -0
  5. package/cli/settings.ts +2 -2
  6. package/cli/state.test.ts +24 -0
  7. package/cli/state.ts +18 -0
  8. package/cli/versions.test.ts +154 -0
  9. package/cli/versions.ts +272 -0
  10. package/cli/video.test.ts +64 -3
  11. package/cli/video.ts +111 -18
  12. package/cli/web.ts +15 -0
  13. package/package.json +1 -1
  14. package/skills/kaizen/README.md +5 -5
  15. package/skills/kaizen/SKILL.md +10 -14
  16. package/skills/kaizen/config.default.yml +3 -3
  17. package/skills/kaizen/spec-main.md +18 -16
  18. package/skills/kaizen/spec-plan.md +6 -6
  19. package/skills/kaizen/spec-review.md +2 -2
  20. package/skills/kaizen-help/SKILL.md +6 -5
  21. package/skills/media/kaizen-video/SKILL.md +20 -2
  22. package/skills/media/kaizen-video/canvas.html +241 -0
  23. package/skills/media/kaizen-video/examples/canvas-film/cat.txt +31 -0
  24. package/skills/media/kaizen-video/examples/canvas-film/film.json +460 -0
  25. package/skills/media/kaizen-video/examples/canvas-film/lines.json +10 -0
  26. package/skills/media/kaizen-video/examples/canvas-film/skip.txt +18 -0
  27. package/skills/media/kaizen-video/examples/canvas-film/talk.txt +23 -0
  28. package/skills/media/kaizen-video/examples/canvas-film/wow.txt +24 -0
  29. package/skills/media/kaizen-video/examples/kaizen-promo/promo.json +17 -0
  30. package/skills/media/kaizen-video/examples/kaizen-promo/record.json +10 -0
  31. package/skills/media/kaizen-video/examples/notula-promo/promo.json +41 -0
  32. package/skills/media/kaizen-video/examples/notula-promo/record.json +135 -0
  33. package/skills/media/kaizen-video/examples/notula-promo/seed.php +20 -0
  34. package/skills/media/kaizen-video/examples/notula-promo/seed.py +38 -0
  35. package/skills/media/kaizen-video/presets/app-promo/CREDITS.txt +2 -0
  36. package/skills/media/kaizen-video/presets/app-promo/README.md +21 -0
  37. package/skills/media/kaizen-video/presets/app-promo/preset.json +7 -0
  38. package/skills/media/kaizen-video/presets/app-promo/template/compositions/end.html +25 -0
  39. package/skills/media/kaizen-video/presets/app-promo/template/compositions/hook.html +19 -0
  40. package/skills/media/kaizen-video/presets/app-promo/template/compositions/name.html +19 -0
  41. package/skills/media/kaizen-video/presets/app-promo/template/compositions/step.html +52 -0
  42. package/skills/media/kaizen-video/presets/app-promo/template/index.html +24 -0
  43. package/skills/media/kaizen-video/presets/film-cinematic-drama/.hidden +1 -0
  44. package/skills/media/kaizen-video/presets/film-explainer-canvas/.hidden +1 -0
  45. package/skills/media/kaizen-video/presets/film-explainer-canvas/CREDITS.txt +3 -0
  46. package/skills/media/kaizen-video/presets/film-explainer-canvas/README.md +7 -0
  47. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/fonts/InstrumentSerif.ttf +0 -0
  48. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/fonts/SpaceMono.ttf +0 -0
  49. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/boing.wav +0 -0
  50. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/ding.wav +0 -0
  51. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/ending.wav +0 -0
  52. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/pop.wav +0 -0
  53. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/reveal.wav +0 -0
  54. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/shutter.wav +0 -0
  55. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/stamp.wav +0 -0
  56. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/tick.wav +0 -0
  57. package/skills/media/kaizen-video/presets/film-explainer-canvas/assets/sfx/whoosh.wav +0 -0
  58. package/skills/media/kaizen-video/presets/film-explainer-canvas/style.json +15 -0
  59. package/skills/media/kaizen-video/presets/film-fun-energetic/.hidden +1 -0
  60. package/skills/media/kaizen-video/presets/film-promo-booth/.hidden +1 -0
  61. package/skills/media/kaizen-video/presets/film-viral-social/.hidden +1 -0
  62. package/skills/media/kaizen-video/presets/tiktok-explainer/index.html +1 -1
  63. package/skills/media/kaizen-video/references/canvas.md +60 -0
  64. package/skills/media/kaizen-video/references/presets.md +31 -0
  65. package/skills/media/kaizen-video/references/promo.md +148 -0
  66. package/skills/media/kaizen-video/references/revisions.md +11 -2
  67. package/skills/media/kaizen-video/scripts/make_film.py +157 -4
  68. package/skills/media/kaizen-video/scripts/make_promo.py +297 -0
  69. package/skills/media/kaizen-video/scripts/make_tiktok.py +34 -6
  70. package/skills/media/kaizen-video/scripts/pixel.py +40 -0
  71. package/skills/media/kaizen-video/scripts/record.mjs +103 -0
  72. package/web/board/approvals.ts +2 -2
  73. package/web/board/cards.ts +4 -4
  74. package/web/board/icebox.ts +6 -5
  75. package/web/board/panel.ts +2 -2
  76. package/web/board.html +24 -9
  77. package/web/board.js +24 -24
  78. package/web/notebook.js +10 -10
  79. package/web/notebook.ts +5 -1
  80. package/web/notes.html +19 -3
  81. package/web/term.js +1 -1
  82. package/web/video.html +62 -12
  83. package/web/video.js +67 -56
  84. package/web/video.ts +266 -33
@@ -135,7 +135,7 @@ After the findings, an `## Acceptance` section: one line per criterion,
135
135
  `G-01 PASS: …`, `R-01 CANNOT VERIFY: …`. Never number these lines — numbered lines are
136
136
  read as findings to fix.
137
137
 
138
- End the file with a one-line verdict: `PASS` (nothing at or above medium and no
138
+ End the file with a one-line verdict: `PASS` (no findings and no
139
139
  `CANNOT VERIFY`) or `FINDINGS: <n> critical, <n> high, <n> medium, <n> low`, followed
140
140
  by `; <n> cannot verify` when any criterion was — even when every count is 0, so an
141
141
  open human check never reads as a clean pass.
package/cli/hermes.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // WhatsApp through Hermes (`hermes send`): the chats it knows, and one file with a
2
2
  // message to one of them. Always argv, never a shell line: the message is one argument.
3
3
  import { spawn } from "node:child_process";
4
- import { existsSync } from "node:fs";
4
+ import { existsSync, statSync } from "node:fs";
5
5
  import { join } from "node:path";
6
6
 
7
7
  export type Chat = { id: string; name: string; type: string };
@@ -47,8 +47,11 @@ export function message(text: string, file: string): string | { error: string }
47
47
  if (text.length > 1000) return { error: "the message is over 1,000 characters" };
48
48
  if (/MEDIA:/i.test(text)) return { error: "the message may not contain MEDIA:" };
49
49
  if (/[`\n\r]/.test(file)) return { error: "the file's path cannot be passed to Hermes" };
50
+ let size: number;
51
+ try { size = statSync(file).size; } catch { return { error: "the file is no longer available" }; }
52
+ if (size > 2_000_000_000) return { error: "WhatsApp documents must be 2 GB or smaller" };
50
53
  // The path in backticks: Hermes reads a quoted path whole, spaces and all.
51
- return `${text.trim()}${text.trim() ? "\n" : ""}MEDIA:\`${file}\``;
54
+ return `${file.toLowerCase().endsWith(".mp4") && size > 64 * 1024 * 1024 ? "[[as_document]] " : ""}${text.trim()}${text.trim() ? "\n" : ""}MEDIA:\`${file}\``;
52
55
  }
53
56
 
54
57
  // Sent only when Hermes exits 0 with {success: true}; anything else is its own error.
package/cli/notes.test.ts CHANGED
@@ -224,7 +224,7 @@ test("the side menu is the board's on the notebook, line for line", () => {
224
224
  };
225
225
  for (const [from, to] of [["/* side menu:", "/* end side menu */"], ['<nav class="rail"', "</script>"]] as const)
226
226
  for (const page of ["notes.html", "video.html"]) expect(between(page, from, to)).toBe(between("board.html", from, to));
227
- const syms = (f: string) => ["board", "note", "video", "link", "gear", "side", "sun", "moon"].map((n) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(`<symbol id="i-${n}"`)));
227
+ const syms = (f: string) => ["board", "note", "video", "link", "gear", "side", "sun", "moon", "more"].map((n) => readFileSync(join(root, "web", f), "utf8").split("\n").find((l) => l.startsWith(`<symbol id="i-${n}"`)));
228
228
  expect(syms("notes.html")).toEqual(syms("board.html"));
229
229
  expect(syms("video.html")).toEqual(syms("board.html"));
230
230
  expect(syms("board.html").every(Boolean)).toBe(true);
@@ -82,9 +82,11 @@ test("a row dims while the setting it depends on has it switched off, and a left
82
82
 
83
83
  test("a config still holding git.branch_before_implement keeps its preset", () => {
84
84
  const text = readFileSync(defaults, "utf8");
85
+ expect(inProject(`return value("auto_fix.min_severity")`)).toBe("low");
85
86
  const low = applyPreset(text, "low", text).replace("git:\n", "git:\n branch_before_implement: true\n");
86
87
  expect(detectPreset(low, text)).toBe("low");
87
88
  expect(detectPreset(text, text)).toBe("medium");
89
+ expect(applyPreset(text, "medium", text)).toContain("min_severity: low");
88
90
  });
89
91
 
90
92
  test("a low-preset config saved before review.executor existed still reads as low", () => {
package/cli/settings.ts CHANGED
@@ -38,7 +38,7 @@ export const PRESETS: Record<PresetName, {
38
38
  },
39
39
  medium: {
40
40
  label: "Medium",
41
- hint: "balanced (recommended) — full runner, subagents, plan approval, auto-fix high/critical",
41
+ hint: "balanced (recommended) — full runner, subagents, plan approval, auto-fix all findings",
42
42
  settings: {
43
43
  mode: "approve",
44
44
  runner: "full",
@@ -47,7 +47,7 @@ export const PRESETS: Record<PresetName, {
47
47
  "approvals.review": "false",
48
48
  "approvals.each_file": "false",
49
49
  "auto_fix.enabled": "true",
50
- "auto_fix.min_severity": "high",
50
+ "auto_fix.min_severity": "low",
51
51
  "auto_fix.max_iterations": "2",
52
52
  "git.auto_commit": "false",
53
53
  "git.worktree_per_run": "true",
package/cli/state.test.ts CHANGED
@@ -77,6 +77,17 @@ test("inbox round-trips and ignores malformed lines", () => {
77
77
  expect(readInbox(state).map((l) => l.status)).toEqual(["open", "open", "started", "rejected"]);
78
78
  });
79
79
 
80
+ test("inbox reads a bullet typed by hand as an open idea", () => {
81
+ const dir = mkdtempSync(join(tmpdir(), "kz-inbox-"));
82
+ writeFileSync(join(dir, "inbox.md"), "# Ideas\n- Add dark mode\n* [ ] Faster search\n- done: shipped\n a note\n");
83
+ expect(readInbox(dir).map((l) => [l.status, l.text, l.notes])).toEqual([
84
+ ["open", "Add dark mode", undefined],
85
+ ["open", "Faster search", undefined],
86
+ ["done", "shipped", "a note"],
87
+ ]);
88
+ rmSync(dir, { recursive: true, force: true });
89
+ });
90
+
80
91
  test("boardCards: idea retired once a run's request contains it; started idea sits in planning", () => {
81
92
  const cards = boardCards([state], Date.now());
82
93
  const ideas = cards.filter((k) => k.kind === "idea").map((k) => [k.text, k.column, k.status]);
@@ -210,6 +221,19 @@ test("parseItem: finding line splits into where, severity, text", () => {
210
221
  expect(parseItem("plain item").severity).toBeNull();
211
222
  });
212
223
 
224
+ test("parseItem: severity written as a range, a tag in brackets, or a numbered line", () => {
225
+ const sev = (s: string) => parseItem(s).severity;
226
+ expect(parseItem("cli/a.ts:4-9, cli/b.ts:2: high: crashes. Fix: catch.")).toMatchObject({ severity: "high", where: "b.ts:2", text: "crashes." });
227
+ expect(sev("bot/x.ts `ctxNow` - low - no test")).toBe("low");
228
+ expect(parseItem("1. low — defaults are Bahasa")).toMatchObject({ severity: "low", where: null });
229
+ expect(sev("Finding 1 (medium) — proxy checks host only")).toBe("medium");
230
+ expect(sev("Tech Lead turn per item; watch cost. (review finding 3, low)")).toBe("low");
231
+ expect(sev("[low] Test for ptyOf")).toBe("low");
232
+ expect(sev("Crane top may touch low (2.2 m) storeys")).toBeNull();
233
+ expect(sev("add dark mode (low priority)")).toBeNull();
234
+ expect(sev("the price is too low")).toBeNull();
235
+ });
236
+
213
237
  test("reviewFindings: numbered lines under Findings, closed by the backlog; the prompt names only what was picked", () => {
214
238
  const dir = join(state, "runs", "2026-09-02-done");
215
239
  writeFileSync(join(dir, "04-review.md"),
package/cli/state.ts CHANGED
@@ -576,6 +576,18 @@ export function parseItem(raw: string): Item {
576
576
  }
577
577
  const sev = /^(critical|high|medium|low)\s*[:—-]\s*(.+)$/i.exec(raw);
578
578
  if (sev) return { severity: sev[1]!.toLowerCase(), where: null, text: tidy(sev[2]!), raw };
579
+ // The other shapes backlogs hold: a place with ranges or backticks before the
580
+ // severity ("a.ts:4-9, b.ts:2: high: …", "x.ts `fn` - low - …"), "1. low — …",
581
+ // and a severity tag in brackets ("Finding 1 (medium) — …", "(review 2, low)",
582
+ // "[low] …"). A severity loose in prose ("too low") is not one.
583
+ const at = /^(.{1,160}?)\s*[:—-]\s*(critical|high|medium|low)\s*[:—-]\s*(.+)$/i.exec(raw);
584
+ // Only a real place counts as one (a path, or a line number): an idea's own words
585
+ // before a severity stay its words.
586
+ if (at && /\/|:\d/.test(at[1]!)) return { severity: at[2]!.toLowerCase(), where: at[1]!.replace(/`/g, "").trim().split("/").pop()!, text: tidy(at[3]!), raw };
587
+ const num = /^\d+\.\s*(critical|high|medium|low)\s*[:—-]\s*(.+)$/i.exec(raw);
588
+ if (num) return { severity: num[1]!.toLowerCase(), where: null, text: tidy(num[2]!), raw };
589
+ const tag = /[(\[](?:[^()\[\]]*,\s*)?(critical|high|medium|low)\s*[,)\]]/i.exec(raw);
590
+ if (tag) return { severity: tag[1]!.toLowerCase(), where: null, text: tidy(raw), raw };
579
591
  return { severity: null, where: null, text: tidy(raw), raw };
580
592
  }
581
593
 
@@ -811,6 +823,12 @@ export function readInbox(state: string): InboxLine[] {
811
823
  out.push(a ? { status: m[1]!, text: m[2]!.slice(0, a.index).trim(), added: +a[1]! } : { status: m[1]!, text: m[2]!.trim() });
812
824
  continue;
813
825
  }
826
+ // A bullet typed by hand, without a status, is an open idea.
827
+ const b = /^[-*]\s+(?:\[ \]\s+)?(.+)$/.exec(raw);
828
+ if (b) {
829
+ out.push({ status: "open", text: b[1]!.trim() });
830
+ continue;
831
+ }
814
832
  // An indented line belongs to the bullet above it; anything else is noise.
815
833
  const last = out[out.length - 1];
816
834
  if (last && /^\s{2,}\S/.test(raw)) last.notes = (last.notes ? last.notes + "\n" : "") + raw.trim();
@@ -0,0 +1,154 @@
1
+ import { test, expect } from "bun:test";
2
+ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { tmpdir } from "node:os";
5
+ import { createHash } from "node:crypto";
6
+ import * as v from "./versions.ts";
7
+
8
+ const md5 = (f: string) => createHash("md5").update(readFileSync(f)).digest("hex");
9
+ const LATER = Date.now() + 60_000; // "now" well past the settle time, so fresh test files file
10
+
11
+ // A place with one video "clip": a draft (film.json, lines.json, a voice line, footage that is never
12
+ // part of a recipe) and renders in the scripts' layout, output/clip/<preset>/clip.mp4.
13
+ function place() {
14
+ const p = mkdtempSync(join(tmpdir(), "kaizen-versions-"));
15
+ const vd = join(p, "videos", "clip");
16
+ mkdirSync(join(vd, "raw"), { recursive: true });
17
+ writeFileSync(join(vd, "film.json"), '{"preset":"film-a","title":"one"}');
18
+ writeFileSync(join(vd, "lines.json"), '{"v01":"hello"}');
19
+ writeFileSync(join(vd, "v01.mp3"), "voice");
20
+ writeFileSync(join(vd, "raw", "take.mp4"), "footage");
21
+ return p;
22
+ }
23
+ function render(p: string, preset: string, body: string, extras = true) {
24
+ const d = join(p, "output", "clip", preset);
25
+ mkdirSync(d, { recursive: true });
26
+ writeFileSync(join(d, "clip.mp4"), body);
27
+ if (extras) { writeFileSync(join(d, "clip.srt"), "srt " + body); writeFileSync(join(d, "clip-thumb.jpg"), "jpg"); writeFileSync(join(d, "CREDITS.txt"), "credits"); }
28
+ }
29
+
30
+ test("first sight: existing renders become versions oldest first, previous/ copies their history, recipe unknown", () => {
31
+ const p = place();
32
+ render(p, "film-a", "A");
33
+ mkdirSync(join(p, "output", "clip", "film-a", "previous"), { recursive: true });
34
+ writeFileSync(join(p, "output", "clip", "film-a", "previous", "clip-20261020.mp4"), "A-old");
35
+ writeFileSync(join(p, "output", "clip", "film-a", "previous", "clip-thumb-20261020.jpg"), "old-jpg");
36
+ render(p, "film-b", "B");
37
+ v.fileRenders(p, "clip", LATER);
38
+ const s = v.readStore(p, "clip")!;
39
+ expect(s.versions.map((x) => [x.letter, x.preset, x.current, x.revs.length])).toEqual([["a", "film-a", 2, 2], ["b", "film-b", 1, 1]]);
40
+ expect(s.versions.every((x) => x.revs.every((r) => !r.recipe))).toBe(true);
41
+ const files = v.revFiles(p, "clip");
42
+ expect(files.map((f) => `${f.letter}${f.n}:${f.kind}`)).toEqual(["a1:history", "a2:current", "b1:current"]);
43
+ expect(readFileSync(join(p, "output", "clip", "versions", "a", "2", "clip.mp4"), "utf8")).toBe("A");
44
+ expect(readFileSync(join(p, "output", "clip", "versions", "a", "1", "clip-20261020.mp4"), "utf8")).toBe("A-old");
45
+ expect(files[0]!.thumb).toBe("o/versions/a/1/clip-20261020-thumb.jpg");
46
+ // Moved, not copied: nothing left in the old place but its CREDITS.txt.
47
+ expect(existsSync(join(p, "output", "clip", "film-a", "clip.mp4"))).toBe(false);
48
+ expect(v.revise(p, "clip", "a")).toContain("cannot be revised");
49
+ });
50
+
51
+ test("a render still settling is not filed", () => {
52
+ const p = place();
53
+ render(p, "film-a", "A");
54
+ v.fileRenders(p, "clip", Date.now());
55
+ expect(v.readStore(p, "clip")).toBe(null);
56
+ expect(existsSync(join(p, "output", "clip", "film-a", "clip.mp4"))).toBe(true);
57
+ });
58
+
59
+ test("revise b, try, keep, restore, revert: a and the other files are never touched", () => {
60
+ const p = place();
61
+ // A store already exists, so new renders are filed with their recipe.
62
+ render(p, "film-a", "A"); v.fileRenders(p, "clip", LATER);
63
+ render(p, "film-b", "B"); v.fileRenders(p, "clip", LATER);
64
+ const aMp4 = join(p, "output", "clip", "versions", "b", "1", "clip.mp4");
65
+ expect(v.readStore(p, "clip")!.versions.map((x) => x.letter)).toEqual(["a", "b"]);
66
+ const b1 = v.readStore(p, "clip")!.versions[1]!.revs[0]!;
67
+ expect(b1.recipe).toBe(true);
68
+ const keepA = md5(join(p, "output", "clip", "versions", "a", "1", "clip.mp4"));
69
+
70
+ // Revise b: its recipe becomes the draft.
71
+ writeFileSync(join(p, "videos", "clip", "film.json"), '{"preset":"film-b","title":"changed elsewhere"}');
72
+ expect(v.revise(p, "clip", "b")).toBe(null);
73
+ expect(v.readStore(p, "clip")!.revising).toBe("b");
74
+ // (the recipe saved at b's filing held the film.json of that moment)
75
+ expect(readFileSync(join(p, "videos", "clip", "film.json"), "utf8")).toBe('{"preset":"film-a","title":"one"}');
76
+ expect(existsSync(join(p, "videos", "clip", "raw", "take.mp4"))).toBe(true);
77
+
78
+ // A change and a render: filed as b's try, from b1.
79
+ writeFileSync(join(p, "videos", "clip", "film.json"), '{"preset":"film-b","title":"horror"}');
80
+ render(p, "film-b", "B2"); v.fileRenders(p, "clip", LATER);
81
+ let b = v.readStore(p, "clip")!.versions.find((x) => x.letter === "b")!;
82
+ expect([b.current, b.trying, b.revs.at(-1)!.from]).toEqual([1, 2, "b1"]);
83
+ expect(v.revFiles(p, "clip").filter((f) => f.letter === "b").map((f) => `${f.n}:${f.kind}`)).toEqual(["1:current", "2:trying"]);
84
+
85
+ // A second try replaces the first (one try at a time).
86
+ render(p, "film-b", "B3"); v.fileRenders(p, "clip", LATER);
87
+ b = v.readStore(p, "clip")!.versions.find((x) => x.letter === "b")!;
88
+ expect([b.current, b.trying, b.revs.map((r) => r.n)]).toEqual([1, 3, [1, 3]]);
89
+ expect(existsSync(join(p, "output", "clip", "versions", "b", "2"))).toBe(false);
90
+
91
+ // Keep: the try is b; b1 is history.
92
+ expect(v.keep(p, "clip", "b")).toBe(null);
93
+ expect(v.revFiles(p, "clip").filter((f) => f.letter === "b").map((f) => `${f.n}:${f.kind}`)).toEqual(["1:history", "3:current"]);
94
+ // Restore b1: swapped back.
95
+ expect(v.restore(p, "clip", "b", 1)).toBe(null);
96
+ expect(v.revFiles(p, "clip").filter((f) => f.letter === "b").map((f) => `${f.n}:${f.kind}`)).toEqual(["1:current", "3:history"]);
97
+ expect(readFileSync(aMp4, "utf8")).toBe("B");
98
+ // b is being revised, so the draft followed b back to v1's recipe.
99
+ expect(readFileSync(join(p, "videos", "clip", "film.json"), "utf8")).toBe('{"preset":"film-a","title":"one"}');
100
+
101
+ // Another try, then Revert: its files go, the draft goes back to b's current recipe.
102
+ render(p, "film-b", "B4"); v.fileRenders(p, "clip", LATER);
103
+ expect(v.revert(p, "clip", "b")).toBe(null);
104
+ b = v.readStore(p, "clip")!.versions.find((x) => x.letter === "b")!;
105
+ expect([b.current, b.trying]).toEqual([1, null]);
106
+ expect(existsSync(join(p, "output", "clip", "versions", "b", "4"))).toBe(false);
107
+ expect(readFileSync(join(p, "videos", "clip", "film.json"), "utf8")).toBe('{"preset":"film-a","title":"one"}');
108
+
109
+ // a never moved or changed.
110
+ expect(md5(join(p, "output", "clip", "versions", "a", "1", "clip.mp4"))).toBe(keepA);
111
+
112
+ // Delete a history revision, then the whole version.
113
+ expect(v.remove(p, "clip", "b", 1)).toBe("only a history revision can be deleted on its own");
114
+ expect(v.remove(p, "clip", "b", 3)).toBe(null);
115
+ expect(v.remove(p, "clip", "b", undefined)).toBe("only a history revision can be deleted on its own");
116
+ expect(v.remove(p, "clip", "b", "all")).toBe(null);
117
+ expect(v.readStore(p, "clip")!.versions.map((x) => x.letter)).toEqual(["a"]);
118
+ expect(existsSync(join(p, "output", "clip", "versions", "b"))).toBe(false);
119
+ expect(existsSync(join(p, "videos", "clip", "versions", "b"))).toBe(false);
120
+ expect(v.readStore(p, "clip")!.revising).toBe(null);
121
+ });
122
+
123
+ test("two renders settling in one pass while revising: the first is the try, the second a new letter", () => {
124
+ const p = place();
125
+ writeFileSync(join(p, "videos", "clip", "versions.json"), '{"revising":null,"versions":[]}');
126
+ render(p, "film-a", "A"); v.fileRenders(p, "clip", LATER);
127
+ expect(v.revise(p, "clip", "a")).toBe(null);
128
+ render(p, "film-a", "A2"); render(p, "film-b", "B");
129
+ v.fileRenders(p, "clip", LATER);
130
+ const s = v.readStore(p, "clip")!;
131
+ expect(s.versions.map((x) => [x.letter, x.current, x.trying])).toEqual([["a", 1, 2], ["b", 1, null]]);
132
+ expect(readFileSync(join(p, "output", "clip", "versions", "a", "2", "clip.mp4"), "utf8")).toBe("A2");
133
+ expect(readFileSync(join(p, "output", "clip", "versions", "b", "1", "clip.mp4"), "utf8")).toBe("B");
134
+ });
135
+
136
+ test("files a crashed filing left behind are kept on disk and never listed", () => {
137
+ const p = place();
138
+ mkdirSync(join(p, "output", "clip", "versions", "a", "1"), { recursive: true });
139
+ writeFileSync(join(p, "output", "clip", "versions", "a", "1", "aaa-orphan.mp4"), "orphan");
140
+ render(p, "film-a", "A"); v.fileRenders(p, "clip", LATER);
141
+ expect(v.revFiles(p, "clip").map((f) => f.mp4)).toEqual(["o/versions/b/1/clip.mp4"]);
142
+ expect(readFileSync(join(p, "output", "clip", "versions", "a", "1", "aaa-orphan.mp4"), "utf8")).toBe("orphan");
143
+ });
144
+
145
+ test("bad letters and revisions are refused", () => {
146
+ const p = place();
147
+ render(p, "film-a", "A"); v.fileRenders(p, "clip", LATER);
148
+ for (const l of ["../a", "A", "", "abcd", 3, null]) expect(v.keep(p, "clip", l)).toBe("unknown version");
149
+ expect(v.keep(p, "clip", "z")).toBe("unknown version");
150
+ expect(v.keep(p, "clip", "a")).toBe("nothing is being tried on this version");
151
+ expect(v.restore(p, "clip", "a", 1)).toBe("not a history revision of this version");
152
+ expect(v.restore(p, "clip", "a", "../../x")).toBe("not a history revision of this version");
153
+ expect(readdirSync(join(p, "output", "clip", "versions"))).toEqual(["a"]);
154
+ });
@@ -0,0 +1,272 @@
1
+ // Video versions: every render becomes a version (a, b, c…) with its own revisions and the recipe that
2
+ // made it, so a version can be revised, tried, kept, reverted or restored (references/revisions.md).
3
+ //
4
+ // The render scripts keep writing output/<name>/<preset>/<name>.mp4 (with .srt, -thumb.jpg and
5
+ // CREDITS.txt), whoever runs them; the board files those "loose" renders here the next time it lists
6
+ // the video. Files move by rename inside output/<name>/, never copied, so nothing is lost on the way.
7
+ //
8
+ // videos/<name>/versions.json the store (below)
9
+ // output/<name>/versions/<letter>/<n>/ a revision's MP4, captions, thumbnail, credits
10
+ // videos/<name>/versions/<letter>/<n>/ the recipe: the small files that made it
11
+ import { cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
12
+ import { join } from "node:path";
13
+
14
+ export type Rev = { n: number; at: number; from: string | null; recipe: boolean };
15
+ export type Version = { letter: string; preset: string; current: number; trying: number | null; revs: Rev[] };
16
+ export type Store = { revising: string | null; versions: Version[] };
17
+
18
+ // A render the scripts are still writing must not move: only MP4s left alone this long are filed.
19
+ const SETTLED_MS = 15_000;
20
+ // Recipe files above this size stay out (footage, music): the recipe is the small files that describe the film.
21
+ const RECIPE_MAX = 20 * 1024 * 1024;
22
+ const MEDIA = /\.(mp4|mov|mkv|webm|wav|m4a|flac)$/i;
23
+
24
+ const okLetter = (l: unknown): l is string => typeof l === "string" && /^[a-z]{1,3}$/.test(l);
25
+ const storeFile = (place: string, name: string) => join(place, "videos", name, "versions.json");
26
+ const revDir = (place: string, name: string, l: string, n: number) => join(place, "output", name, "versions", l, String(n));
27
+ const recipeDir = (place: string, name: string, l: string, n: number) => join(place, "videos", name, "versions", l, String(n));
28
+
29
+ export function readStore(place: string, name: string): Store | null {
30
+ try {
31
+ const s = JSON.parse(readFileSync(storeFile(place, name), "utf8"));
32
+ return s && Array.isArray(s.versions) ? { revising: okLetter(s.revising) ? s.revising : null, versions: s.versions } : null;
33
+ } catch { return null; }
34
+ }
35
+ function writeStore(place: string, name: string, s: Store) {
36
+ const f = storeFile(place, name), tmp = `${f}.${process.pid}.tmp`;
37
+ writeFileSync(tmp, JSON.stringify(s, null, 1));
38
+ renameSync(tmp, f);
39
+ }
40
+
41
+ // Two boards (or a board and a test) can list the same video at once: one files, the other waits its turn.
42
+ // Returns { value } when it ran, null when another holder had the lock.
43
+ function locked<T>(place: string, name: string, fn: () => T): { value: T } | null {
44
+ const lock = join(place, "videos", name, ".versions.lock");
45
+ try { if (Date.now() - statSync(lock).mtimeMs > 60_000) unlinkSync(lock); } catch { /* none */ }
46
+ let fd: number;
47
+ try { fd = openSync(lock, "wx"); } catch { return null; }
48
+ try { return { value: fn() }; } finally { closeSync(fd); try { unlinkSync(lock); } catch { /* gone */ } }
49
+ }
50
+
51
+ // A letter neither in the store nor on disk: folders a crashed filing left behind are skipped, never cleared.
52
+ const nextLetter = (s: Store, place: string, name: string) => {
53
+ const used = new Set(s.versions.map((v) => v.letter));
54
+ for (let i = 0; ; i++) {
55
+ let l = "", k = i;
56
+ do { l = String.fromCharCode(97 + (k % 26)) + l; k = Math.floor(k / 26) - 1; } while (k >= 0);
57
+ if (!used.has(l) && !existsSync(join(place, "output", name, "versions", l)) && !existsSync(join(place, "videos", name, "versions", l))) return l;
58
+ }
59
+ };
60
+
61
+ // The recipe: the video folder's own small files (film.json or config.json, lines, words, voice lines,
62
+ // pictures) plus transcript/*.json and images/, never the footage or the build.
63
+ function snapshotRecipe(vdir: string, to: string) {
64
+ mkdirSync(to, { recursive: true });
65
+ for (const f of readdirSync(vdir)) {
66
+ const p = join(vdir, f);
67
+ let st; try { st = statSync(p); } catch { continue; }
68
+ // .mp3 is not MEDIA here: a film's voice lines (vNN.mp3) are part of what made it.
69
+ if (st.isFile() && !MEDIA.test(f) && st.size <= RECIPE_MAX && !f.startsWith(".") && f !== "versions.json") cpSync(p, join(to, f));
70
+ }
71
+ for (const sub of ["images", "transcript"]) {
72
+ const d = join(vdir, sub);
73
+ if (!existsSync(d)) continue;
74
+ for (const f of readdirSync(d)) {
75
+ const p = join(d, f);
76
+ const st = statSync(p);
77
+ if (st.isFile() && st.size <= RECIPE_MAX && (sub === "images" || f.endsWith(".json"))) { mkdirSync(join(to, sub), { recursive: true }); cpSync(p, join(to, sub, f)); }
78
+ }
79
+ }
80
+ }
81
+
82
+ // Move one render (the MP4 and whatever of .srt / -thumb.jpg / CREDITS.txt sits beside it) into a revision folder.
83
+ function moveRender(fromDir: string, base: string, to: string, credits: boolean) {
84
+ mkdirSync(to, { recursive: true });
85
+ for (const [src, dst] of [[`${base}.mp4`, `${base}.mp4`], [`${base}.srt`, `${base}.srt`], [`${base}-thumb.jpg`, `${base}-thumb.jpg`]]) {
86
+ if (existsSync(join(fromDir, src))) renameSync(join(fromDir, src), join(to, dst));
87
+ }
88
+ if (credits && existsSync(join(fromDir, "CREDITS.txt"))) cpSync(join(fromDir, "CREDITS.txt"), join(to, "CREDITS.txt"));
89
+ }
90
+
91
+ // File every settled loose render of this video. The first time (no store yet) existing renders are
92
+ // taken in as they are, oldest first, with their previous/ copies as history; they are marked
93
+ // recipe:false (what made them was not kept). After that, a new render becomes the "trying" revision
94
+ // of the version being revised, or a new letter, with the draft's recipe beside it.
95
+ export function fileRenders(place: string, name: string, now = Date.now()): void {
96
+ const out = join(place, "output", name);
97
+ let dirs: string[] = [];
98
+ try { dirs = readdirSync(out).filter((d) => d !== "versions" && statSync(join(out, d)).isDirectory()); } catch { return; }
99
+ const loose: { dir: string; preset: string; base: string; at: number }[] = [];
100
+ for (const d of dirs) for (const f of readdirSync(join(out, d))) {
101
+ if (!f.endsWith(".mp4") || f.endsWith(".raw.mp4")) continue;
102
+ const at = statSync(join(out, d, f)).mtimeMs;
103
+ if (now - at < SETTLED_MS) continue;
104
+ loose.push({ dir: join(out, d), preset: d, base: f.slice(0, -4), at });
105
+ }
106
+ if (!loose.length) return;
107
+ locked(place, name, () => {
108
+ const vdir = join(place, "videos", name);
109
+ const first = !existsSync(storeFile(place, name));
110
+ const s = readStore(place, name) ?? { revising: null, versions: [] };
111
+ let tried = false;
112
+ for (const r of loose.sort((a, b) => a.at - b.at || a.preset.localeCompare(b.preset))) {
113
+ if (!existsSync(join(r.dir, `${r.base}.mp4`))) continue; // the other board filed it
114
+ // Only the first render of a pass becomes the try: a second one (another shape or preset from the
115
+ // same job) would replace it before anyone saw it, so it gets a letter of its own instead.
116
+ const target = !first && !tried && s.revising ? s.versions.find((v) => v.letter === s.revising) : undefined;
117
+ if (target) {
118
+ // One try at a time: a newer try replaces the one not yet kept or reverted. Numbers only go up,
119
+ // so a revision number always means the same render.
120
+ let n = Math.max(0, ...target.revs.map((x) => x.n)) + 1;
121
+ // A crashed filing may have left files at that number (even this very render): skip, never clear.
122
+ while (existsSync(revDir(place, name, target.letter, n)) || existsSync(recipeDir(place, name, target.letter, n))) n++;
123
+ if (target.trying != null) dropRev(place, name, target, target.trying);
124
+ moveRender(r.dir, r.base, revDir(place, name, target.letter, n), true);
125
+ snapshotRecipe(vdir, recipeDir(place, name, target.letter, n));
126
+ target.revs.push({ n, at: r.at, from: `${target.letter}${target.current}`, recipe: true });
127
+ target.trying = n;
128
+ tried = true;
129
+ } else {
130
+ const v: Version = { letter: nextLetter(s, place, name), preset: r.preset, current: 1, trying: null, revs: [] };
131
+ // Earlier deliveries master.sh kept (previous/<base>-<stamp>.mp4) become this version's history.
132
+ let n = 0;
133
+ const prev = join(r.dir, "previous");
134
+ if (first && existsSync(prev)) {
135
+ for (const f of readdirSync(prev).filter((f) => f.endsWith(".mp4")).sort()) {
136
+ const pb = f.slice(0, -4);
137
+ n++;
138
+ moveRender(prev, pb, revDir(place, name, v.letter, n), false);
139
+ // master.sh named the earlier thumbnail <name>-thumb-<stamp>.jpg, not <name>-<stamp>-thumb.jpg.
140
+ const thumb = `${r.base}-thumb${pb.slice(r.base.length)}.jpg`;
141
+ if (pb.startsWith(r.base) && existsSync(join(prev, thumb))) renameSync(join(prev, thumb), join(revDir(place, name, v.letter, n), `${pb}-thumb.jpg`));
142
+ v.revs.push({ n, at: statSync(join(revDir(place, name, v.letter, n), `${pb}.mp4`)).mtimeMs, from: null, recipe: false });
143
+ }
144
+ }
145
+ n++;
146
+ moveRender(r.dir, r.base, revDir(place, name, v.letter, n), true);
147
+ if (!first) snapshotRecipe(vdir, recipeDir(place, name, v.letter, n));
148
+ v.revs.push({ n, at: r.at, from: null, recipe: !first });
149
+ v.current = n;
150
+ s.versions.push(v);
151
+ }
152
+ // Written after every render, so a crash leaves at most one render half filed.
153
+ writeStore(place, name, s);
154
+ }
155
+ });
156
+ }
157
+
158
+ function dropRev(place: string, name: string, v: Version, n: number) {
159
+ rmSync(revDir(place, name, v.letter, n), { recursive: true, force: true });
160
+ rmSync(recipeDir(place, name, v.letter, n), { recursive: true, force: true });
161
+ v.revs = v.revs.filter((r) => r.n !== n);
162
+ if (v.trying === n) v.trying = null;
163
+ }
164
+
165
+ // The files of one revision, for listing: the MP4 and its captions and thumbnail, as page paths.
166
+ export type RevFile = { letter: string; preset: string; n: number; kind: "current" | "trying" | "history"; at: number; recipe: boolean; from: string | null; mp4: string; srt: string | null; thumb: string | null };
167
+ export function revFiles(place: string, name: string): RevFile[] {
168
+ const s = readStore(place, name);
169
+ if (!s) return [];
170
+ const list: RevFile[] = [];
171
+ for (const v of s.versions) for (const r of v.revs) {
172
+ const d = revDir(place, name, v.letter, r.n);
173
+ let files: string[] = [];
174
+ try { files = readdirSync(d); } catch { continue; }
175
+ const mp4 = files.find((f) => f.endsWith(".mp4"));
176
+ if (!mp4) continue;
177
+ const base = mp4.slice(0, -4), rel = `o/versions/${v.letter}/${r.n}/`;
178
+ list.push({
179
+ letter: v.letter, preset: v.preset, n: r.n, kind: r.n === v.trying ? "trying" : r.n === v.current ? "current" : "history",
180
+ at: r.at, recipe: r.recipe, from: r.from, mp4: rel + mp4,
181
+ srt: files.includes(`${base}.srt`) ? rel + `${base}.srt` : null, thumb: files.includes(`${base}-thumb.jpg`) ? rel + `${base}-thumb.jpg` : null,
182
+ });
183
+ }
184
+ return list;
185
+ }
186
+
187
+ // ---- actions. Each returns an error a person can act on, or null. The caller checks no job or send runs.
188
+
189
+ function withVersion(place: string, name: string, letter: unknown, fn: (s: Store, v: Version) => string | null): string | null {
190
+ if (!okLetter(letter)) return "unknown version";
191
+ const r = locked(place, name, () => {
192
+ const s = readStore(place, name);
193
+ const v = s?.versions.find((x) => x.letter === letter);
194
+ if (!s || !v) return "unknown version";
195
+ const err = fn(s, v);
196
+ if (!err) writeStore(place, name, s);
197
+ return err;
198
+ });
199
+ return r === null ? "the versions are being updated; try again in a moment" : r.value;
200
+ }
201
+
202
+ // Copy a revision's recipe back into the video folder: it becomes the draft. Only recipe files are
203
+ // written; nothing else in the folder is removed.
204
+ function restoreRecipe(place: string, name: string, letter: string, n: number) {
205
+ const from = recipeDir(place, name, letter, n), vdir = join(place, "videos", name);
206
+ const copy = (src: string, dst: string) => {
207
+ for (const f of readdirSync(src)) {
208
+ const p = join(src, f);
209
+ if (statSync(p).isDirectory()) { mkdirSync(join(dst, f), { recursive: true }); copy(p, join(dst, f)); }
210
+ else cpSync(p, join(dst, f));
211
+ }
212
+ };
213
+ copy(from, vdir);
214
+ }
215
+
216
+ // Revise: the version's current revision becomes the draft, and new renders file as its tries.
217
+ export const revise = (place: string, name: string, letter: unknown) => withVersion(place, name, letter, (s, v) => {
218
+ const cur = v.revs.find((r) => r.n === v.current);
219
+ if (!cur?.recipe) return "this version was rendered before kaizen kept recipes, so it cannot be revised; it can still be played, sent or deleted";
220
+ restoreRecipe(place, name, v.letter, v.current);
221
+ s.revising = v.letter;
222
+ return null;
223
+ });
224
+
225
+ // Keep: the try becomes the version; the revision it replaced stays in the history.
226
+ export const keep = (place: string, name: string, letter: unknown) => withVersion(place, name, letter, (_s, v) => {
227
+ if (v.trying == null) return "nothing is being tried on this version";
228
+ v.current = v.trying;
229
+ v.trying = null;
230
+ return null;
231
+ });
232
+
233
+ // Revert: the try is deleted, and the draft goes back to the version's own recipe (when it has one).
234
+ export const revert = (place: string, name: string, letter: unknown) => withVersion(place, name, letter, (_s, v) => {
235
+ if (v.trying == null) return "nothing is being tried on this version";
236
+ // The draft goes back first: if that copy fails, the try is still there.
237
+ if (v.revs.find((r) => r.n === v.current)?.recipe) restoreRecipe(place, name, v.letter, v.current);
238
+ dropRev(place, name, v, v.trying);
239
+ return null;
240
+ });
241
+
242
+ // Restore: a history revision becomes the version again; the current one goes to the history.
243
+ export const restore = (place: string, name: string, letter: unknown, n: unknown) => withVersion(place, name, letter, (s, v) => {
244
+ const r = v.revs.find((x) => x.n === Number(n));
245
+ if (!r || r.n === v.trying || r.n === v.current) return "not a history revision of this version";
246
+ v.current = r.n;
247
+ // The draft follows the version it is revising.
248
+ if (s.revising === v.letter && r.recipe) restoreRecipe(place, name, v.letter, r.n);
249
+ return null;
250
+ });
251
+
252
+ // Delete a history revision, or (n === "all") the whole version with every revision. Leaving n out
253
+ // deletes nothing, so a request missing it cannot take a whole version.
254
+ export const remove = (place: string, name: string, letter: unknown, n: unknown) => withVersion(place, name, letter, (s, v) => {
255
+ if (n === "all") {
256
+ for (const r of [...v.revs]) dropRev(place, name, v, r.n);
257
+ rmSync(join(place, "output", name, "versions", v.letter), { recursive: true, force: true });
258
+ rmSync(join(place, "videos", name, "versions", v.letter), { recursive: true, force: true });
259
+ s.versions = s.versions.filter((x) => x !== v);
260
+ if (s.revising === v.letter) s.revising = null;
261
+ return null;
262
+ }
263
+ const r = v.revs.find((x) => x.n === Number(n));
264
+ if (!r || r.n === v.current || r.n === v.trying) return "only a history revision can be deleted on its own";
265
+ dropRev(place, name, v, r.n);
266
+ return null;
267
+ });
268
+
269
+ // Stop revising (a render then makes a new letter again).
270
+ export function stopRevising(place: string, name: string) {
271
+ locked(place, name, () => { const s = readStore(place, name); if (s?.revising) { s.revising = null; writeStore(place, name, s); } });
272
+ }