rushes 0.4.0 → 0.5.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.
@@ -25,10 +25,13 @@ import { osRevealer, osOpener, OPEN_SAFE_EXT } from "./reveal.js";
25
25
  import { LaneStageSchema, SectionStatusSchema, StageSchema, BoxSchema, FileKindSchema, MarkSchema, ProjectIdSchema, ShotSchema, LEVEL_MIN, LEVEL_MAX, LEVEL_STEP } from "../core/schema.js";
26
26
  import { LABEL_MAX, oneLineOf } from "../core/labels.js";
27
27
  import { byOf, logBookFor } from "./logbook.js";
28
+ import { BriefService } from "./brief.js";
29
+ import { StoryboardService } from "./storyboard.js";
30
+ import { buildState, planWarning } from "../core/plan.js";
28
31
  import { broughtInEvent, cutEvent, fileEvent, formatEvent, lineEvent, lockEvent, notesSentEvent, picksEvent, repliesEvent, scriptEvent, takeEvent, variantEvent, } from "../core/logEvents.js";
29
32
  import { LOG_AREAS, LOG_MAX, changeLogFileName, logText, recentChanges } from "../core/logText.js";
30
33
  import { defaultRunner, measureMix } from "./loudness.js";
31
- export const VERSION = "0.4.0";
34
+ export const VERSION = "0.5.0";
32
35
  async function body(c, schema) {
33
36
  let json;
34
37
  try {
@@ -128,6 +131,19 @@ const SectionEditBody = z.object({
128
131
  status: SectionStatusSchema.optional(),
129
132
  });
130
133
  const TakeBody = z.object({ file: z.string().min(1) });
134
+ // §24 step 2: a save of one brief.md section, and the approval. `hash` proves the page saw the current file.
135
+ const BriefSectionBody = z.object({ heading: z.string().min(1).max(200), text: z.string().max(100_000), hash: z.string().min(1).max(64) });
136
+ const BriefStatusBody = z.object({ status: z.enum(["draft", "approved"]), hash: z.string().min(1).max(64) });
137
+ // §24.12: a change to one storyboard shot: its words, its direction, its status, in any combination.
138
+ const StoryboardShotBody = z
139
+ .object({
140
+ heading: z.string().min(1).max(200),
141
+ description: z.string().max(100_000).optional(),
142
+ direction: z.string().max(1000).optional(),
143
+ status: z.enum(["draft", "approved"]).optional(),
144
+ hash: z.string().min(1).max(64),
145
+ })
146
+ .refine((b) => b.description !== undefined || b.direction !== undefined || b.status !== undefined, { message: "Nothing to change" });
131
147
  // A pick is a variant or take id; null clears it. picks.json itself only ever holds strings.
132
148
  const PickMap = z.record(z.string(), z.string().nullable());
133
149
  // §19.6: a level is −24..6 dB in 0.5 dB steps; null resets it to 0 (removes the key).
@@ -244,6 +260,13 @@ export function createApp(store, opts = {}) {
244
260
  const jobs = opts.proxyJobs ?? new ProxyJobs(store);
245
261
  const peaks = opts.peakJobs ?? new PeakJobs(store, { run: jobs.run, available: () => jobs.available() });
246
262
  const found = opts.found ?? new FoundScanner({ store, probe: ffprobeDuration, announce: foundAnnouncer(store) });
263
+ const brief = opts.brief ?? new BriefService(store);
264
+ const storyboard = opts.storyboard ?? new StoryboardService(store);
265
+ /** §24.12: whether the plan (brief, script, storyboard) is approved, from the files as they are now. */
266
+ const planBuild = async () => {
267
+ const [b, script, sb] = await Promise.all([brief.view(), store.read("script"), storyboard.view()]);
268
+ return buildState({ brief: b, script: script.sections, storyboard: sb });
269
+ };
247
270
  // §22: the Change Log, shared with the found scanner (logBookFor keeps one per store).
248
271
  const log = logBookFor(store);
249
272
  const by = (c) => byOf(c.req.header("x-rushes-project"));
@@ -402,7 +425,10 @@ export function createApp(store, opts = {}) {
402
425
  // and the one a byte-range video seek hits over and over. Only a path that misses all three
403
426
  // falls through to candidatePaths, which does the readdir-backed discovery (§16.2's
404
427
  // auto-discovered docs/captions/exports) that a registered path never needs.
405
- const known = registeredMedia(project, script).has(path) || GRAB_PATH.test(path) || SCREENSHOT_PATH.test(path);
428
+ let known = registeredMedia(project, script).has(path) || GRAB_PATH.test(path) || SCREENSHOT_PATH.test(path);
429
+ // §24.12: a picture storyboard.md names (a safe, project-relative image path) is served too, registered or not.
430
+ if (!known && (await storyboard.stills()).has(path))
431
+ known = true;
406
432
  // The file on disk to send. For a found file it's exactly the path that was checked.
407
433
  let file = fromManifestPath(store.root, path);
408
434
  let viaFound = false;
@@ -481,8 +507,9 @@ export function createApp(store, opts = {}) {
481
507
  // the symlink's target, so the write can never escape screenshots/ that way. It also means
482
508
  // nothing ever lists a half-written PNG. The temp name starts with "." and ends in ".tmp",
483
509
  // which SCREENSHOT_PATH (the safe-name filter) already excludes from both /media and the
484
- // Assets listing.
485
- const tmp = join(store.root, "screenshots", `.${name}.${process.pid}.tmp`);
510
+ // Assets listing. The random part keeps two grabs of the same frame in the same instant (a
511
+ // double-click on the camera) from sharing one temp file: the second rename would find it gone.
512
+ const tmp = join(store.root, "screenshots", `.${name}.${process.pid}.${randomUUID()}.tmp`);
486
513
  await writeFile(tmp, bytes);
487
514
  await rename(tmp, fromManifestPath(store.root, grab));
488
515
  return c.json({ grab }, 201);
@@ -607,8 +634,8 @@ export function createApp(store, opts = {}) {
607
634
  app.get("/api/state", async (c) => {
608
635
  // §20.6: found is what the last scan left in memory; it never waits on a scan or a probe.
609
636
  // §22.8: the log's head is read-only, so a state request never writes (R6).
610
- const [project, script, notes, picks, batches, ffmpeg, foundSummary, logHead] = await Promise.all([
611
- store.read("project"), store.read("script"), store.read("notes"), store.read("picks"), store.read("batches"), jobs.available(), found.summary(), log.head(),
637
+ const [project, script, notes, picks, batches, ffmpeg, foundSummary, logHead, briefView, storyboardView] = await Promise.all([
638
+ store.read("project"), store.read("script"), store.read("notes"), store.read("picks"), store.read("batches"), jobs.available(), found.summary(), log.head(), brief.view(), storyboard.view(),
612
639
  ]);
613
640
  const tabs = tabStates(project, script, notes);
614
641
  // §19.5: why each cut may play badly (or null). Never waits on a probe: an unprobed cut is
@@ -617,7 +644,7 @@ export function createApp(store, opts = {}) {
617
644
  ...v,
618
645
  versions: await Promise.all(v.versions.map(async (ver) => ({ ...ver, proxyNeed: await jobs.needNow(fromManifestPath(store.root, ver.file)) }))),
619
646
  })));
620
- return c.json({ project: { ...project, videos }, script, notes, picks, batches, tabs, proxies: { ffmpeg, jobs: jobs.list() }, found: foundSummary, log: logHead });
647
+ return c.json({ project: { ...project, videos }, script, notes, picks, batches, tabs, proxies: { ffmpeg, jobs: jobs.list() }, found: foundSummary, log: logHead, brief: briefView, storyboard: storyboardView, build: buildState({ brief: briefView, script: script.sections, storyboard: storyboardView }) });
621
648
  });
622
649
  // ---- found: the project's other files (§20) ----
623
650
  app.get("/api/found", async (c) => {
@@ -704,7 +731,33 @@ export function createApp(store, opts = {}) {
704
731
  });
705
732
  app.get("/api/tabs", async (c) => {
706
733
  const [project, script, notes] = await Promise.all([store.read("project"), store.read("script"), store.read("notes")]);
707
- return c.json({ tabs: tabStates(project, script, notes) });
734
+ const [b, sb] = await Promise.all([brief.view(), storyboard.view()]);
735
+ return c.json({
736
+ tabs: tabStates(project, script, notes),
737
+ brief: { exists: b.exists, status: b.status, changed: b.changed },
738
+ storyboard: { exists: sb.exists, shots: sb.total, approved: sb.approved, changed: sb.changed },
739
+ build: buildState({ brief: b, script: script.sections, storyboard: sb }),
740
+ });
741
+ });
742
+ // ---- brief: brief.md is the file of record (§24 step 2) ----
743
+ app.put("/api/brief/sections/:index", async (c) => {
744
+ const index = Number(c.req.param("index"));
745
+ if (!Number.isInteger(index) || index < 0)
746
+ throw new InvalidError("Section index must be a whole number from 0");
747
+ const b = await body(c, BriefSectionBody);
748
+ return c.json({ brief: await brief.setSection(index, b.heading, b.text, b.hash) });
749
+ });
750
+ // ---- storyboard: storyboard.md is the file of record (§24.12) ----
751
+ app.put("/api/storyboard/shots/:index", async (c) => {
752
+ const index = Number(c.req.param("index"));
753
+ if (!Number.isInteger(index) || index < 0)
754
+ throw new InvalidError("Shot index must be a whole number from 0");
755
+ const b = await body(c, StoryboardShotBody);
756
+ return c.json({ storyboard: await storyboard.setShot(index, b.heading, { description: b.description, direction: b.direction, status: b.status }, b.hash) });
757
+ });
758
+ app.put("/api/brief/status", async (c) => {
759
+ const b = await body(c, BriefStatusBody);
760
+ return c.json({ brief: await brief.setStatus(b.status, b.hash) });
708
761
  });
709
762
  // ---- notes ----
710
763
  app.get("/api/notes", async (c) => {
@@ -791,6 +844,8 @@ export function createApp(store, opts = {}) {
791
844
  // before formats (a formats call was refused above).
792
845
  const size = read && isPictureSize(read.width, read.height) ? read : null;
793
846
  const formatWarnings = [];
847
+ // §24.12: the storyboard's shots, read before the write so the write itself waits for nothing.
848
+ const planned = await storyboard.cutShots();
794
849
  let lockedVersion = null;
795
850
  let autoProxy = false;
796
851
  let films = 1;
@@ -816,6 +871,12 @@ export function createApp(store, opts = {}) {
816
871
  if (added.warning)
817
872
  formatWarnings.push(added.warning);
818
873
  }
874
+ // A film's first cut starts with the storyboard's shots, once (never recomputed). Those at or past the cut's end are left out.
875
+ if (planned.length && out.video.versions.length === 1 && out.version.shots.length === 0) {
876
+ const reachable = planned.filter((s) => out.version.duration === null || s.start < out.version.duration);
877
+ if (reachable.length)
878
+ setShots(p, out.video.id, out.version.id, reachable);
879
+ }
819
880
  lockedVersion = out.video.lockedVersion;
820
881
  autoProxy = p.autoProxy;
821
882
  films = p.videos.length;
@@ -838,7 +899,9 @@ export function createApp(store, opts = {}) {
838
899
  if (autoProxy && !jobs.isClosing)
839
900
  proxy.proxyJob = jobs.start(result.video.id, result.version.id);
840
901
  }
841
- const warnings = formatWarnings.length ? { formatWarnings } : {};
902
+ // §24.12: a soft nudge, never a refusal: the plan (brief, script, storyboard) is not all approved yet.
903
+ const planNote = planWarning(await planBuild());
904
+ const warnings = { ...(formatWarnings.length ? { formatWarnings } : {}), ...(planNote ? { planWarning: planNote } : {}) };
842
905
  if (lockedVersion)
843
906
  return c.json({ ...result, ...proxy, ...warnings, warning: `Picture is locked at ${lockedVersion}` }, 201);
844
907
  return c.json({ ...result, ...proxy, ...warnings }, 201);
@@ -1094,21 +1157,31 @@ export function createApp(store, opts = {}) {
1094
1157
  return c.json(result);
1095
1158
  });
1096
1159
  // ---- batches ----
1097
- // A batch touches two files (notes and batches), so batch creation runs one at a time.
1160
+ // A batch touches two files (notes and batches), so batch creation runs one at a time. The batch
1161
+ // is recorded first and the notes are marked second: if the second write fails, the notes are
1162
+ // still unsent and go out again in the next batch. The other way round, a failure stranded notes
1163
+ // naming a batch that was never recorded, and the next batch reused its id.
1098
1164
  let batchQueue = Promise.resolve();
1099
1165
  app.post("/api/batches", async (c) => {
1100
1166
  const { stage } = await body(c, BatchBody);
1101
1167
  const run = batchQueue.catch(() => undefined).then(async () => {
1102
- const [project, script, batches] = await Promise.all([store.read("project"), store.read("script"), store.read("batches")]);
1103
- const { result } = await store.update("notes", (notes) => createBatch({ project, script, notes, batches }, stage));
1168
+ const [project, script, notes, batches] = await Promise.all([store.read("project"), store.read("script"), store.read("notes"), store.read("batches")]);
1169
+ // createBatch marks the notes it takes and files the batch in `batches`; on copies, it only
1170
+ // tells us what goes in.
1171
+ const result = createBatch({ project, script, notes: structuredClone(notes), batches: structuredClone(batches) }, stage);
1104
1172
  // R11: the prompt ends with the last five lines of the log, from before this send. A log that
1105
- // can't be read adds nothing: the notes are already marked as sent, so the batch must be kept.
1173
+ // can't be read adds nothing: the batch must still be sent.
1106
1174
  const recent = await Promise.all([store.read("project"), store.read("script")])
1107
1175
  .then(async ([projectNow, scriptNow]) => recentChanges((await log.view({ limit: 5 }, { project: projectNow, script: scriptNow })).entries))
1108
1176
  .catch(() => "");
1109
1177
  if (recent)
1110
1178
  result.prompt = `${result.prompt}\n\n${recent}`;
1111
1179
  await store.update("batches", (f) => { f.batches.push(result); });
1180
+ await store.update("notes", (f) => {
1181
+ for (const n of f.notes)
1182
+ if (n.batch === null && result.noteIds.includes(n.id))
1183
+ n.batch = result.id;
1184
+ });
1112
1185
  await log.add(() => notesSentEvent(result), by(c));
1113
1186
  return result;
1114
1187
  });
@@ -0,0 +1,63 @@
1
+ import { BRIEF_FILE, hashText, parseBrief, setSectionBody, setStatus } from "../core/brief.js";
2
+ import { InvalidError, RushesError } from "../core/errors.js";
3
+ import { RecordFile } from "./record.js";
4
+ // §24 step 2: brief.md is the file of record. See RecordFile for how it is kept.
5
+ export class BriefChangedError extends RushesError {
6
+ constructor() {
7
+ super("brief.md changed since you loaded it. Showing the file as it is now.", 409, "brief_changed");
8
+ }
9
+ }
10
+ export const NO_BRIEF = { exists: false, title: "", status: null, hash: "", sections: [], changed: 0 };
11
+ export class BriefService extends RecordFile {
12
+ constructor(store) {
13
+ super(store, BRIEF_FILE, "brief", () => new BriefChangedError());
14
+ }
15
+ build(text, state) {
16
+ if (text === null)
17
+ return NO_BRIEF;
18
+ const hash = hashText(text);
19
+ const yours = parseBrief(text);
20
+ // Until Rushes has looked at the file, or when it changed before the poll noticed, the file itself is the agent's version.
21
+ const base = state.seen !== "" && state.seen === hash ? parseBrief(state.baseline) : yours;
22
+ const seen = new Map();
23
+ const sections = yours.sections.map((s, index) => {
24
+ const n = seen.get(s.heading) ?? 0;
25
+ seen.set(s.heading, n + 1);
26
+ const match = base.sections.filter((b) => b.heading === s.heading)[n];
27
+ const current = match ? match.body : s.body;
28
+ return { index, heading: s.heading, current, yours: s.body, changed: current !== s.body };
29
+ });
30
+ return { exists: true, title: yours.title, status: yours.status, hash, sections, changed: sections.filter((s) => s.changed).length };
31
+ }
32
+ view() {
33
+ return this.run(async () => this.build(await this.readText(), await this.store.read("brief")));
34
+ }
35
+ /** Saves one section. An edit to an approved brief reopens it: the status line goes back to draft. */
36
+ setSection(index, heading, text, expectHash) {
37
+ return this.run(async () => {
38
+ const prev = await this.current(expectHash);
39
+ let next;
40
+ try {
41
+ next = setSectionBody(prev, index, heading, text);
42
+ }
43
+ catch (e) {
44
+ throw new InvalidError(e.message);
45
+ }
46
+ if (parseBrief(next).status === "approved")
47
+ next = setStatus(next, "draft");
48
+ if (next !== prev)
49
+ await this.write(prev, next);
50
+ return this.build(next, await this.store.read("brief"));
51
+ });
52
+ }
53
+ /** Approves or reopens the brief by setting its status line. Only the dashboard calls this. */
54
+ setStatus(status, expectHash) {
55
+ return this.run(async () => {
56
+ const prev = await this.current(expectHash);
57
+ const next = setStatus(prev, status);
58
+ if (next !== prev)
59
+ await this.write(prev, next);
60
+ return this.build(next, await this.store.read("brief"));
61
+ });
62
+ }
63
+ }
@@ -1,4 +1,4 @@
1
- import { link, readFile, realpath, rm, writeFile } from "node:fs/promises";
1
+ import { link, open, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
2
2
  import { randomUUID } from "node:crypto";
3
3
  import { basename, dirname, join, resolve } from "node:path";
4
4
  import { RUSHES_DIR } from "../core/store.js";
@@ -98,6 +98,52 @@ async function claim(tmp, path, text, linkInto) {
98
98
  throw e;
99
99
  }
100
100
  }
101
+ /** How long a guard may stand before it is taken to be left behind by a claimant that died holding it. */
102
+ const GUARD_STALE_MS = 3000;
103
+ /** How long a claimant waits for another to finish removing a stale lock before it goes round again. */
104
+ const GUARD_WAIT_MS = 5000;
105
+ function sameLock(a, b) {
106
+ return a.token === b.token && a.pid === b.pid && a.startedAt === b.startedAt;
107
+ }
108
+ /**
109
+ * Remove the lock we judged stale, and only that lock. Judging and removing are two steps, and
110
+ * another claimant can put a fresh lock there in between: a plain remove then deletes it, and two
111
+ * servers each believe they own the project. So removing takes an exclusive guard file and checks
112
+ * again inside it. Nobody can replace a lock without first removing it, and only the guard's
113
+ * holder may remove one, so what is checked is what is removed. `judged` is null when no readable
114
+ * lock was seen. Returns false when another claimant holds the guard: wait a moment and go round.
115
+ */
116
+ async function removeStale(root, judged) {
117
+ const guard = `${lockPath(root)}.break.tmp`;
118
+ let handle;
119
+ try {
120
+ handle = await open(guard, "wx");
121
+ }
122
+ catch (e) {
123
+ if (e.code !== "EEXIST")
124
+ throw e;
125
+ // A guard left by a claimant that died holding it would otherwise block every later start.
126
+ try {
127
+ if (Date.now() - (await stat(guard)).mtimeMs > GUARD_STALE_MS)
128
+ await rm(guard, { force: true });
129
+ }
130
+ catch {
131
+ /* it went while we looked */
132
+ }
133
+ return false;
134
+ }
135
+ try {
136
+ const now = await readLockFile(root);
137
+ const unchanged = judged === null ? now === null : now !== null && sameLock(now, judged);
138
+ if (unchanged)
139
+ await rm(lockPath(root), { force: true });
140
+ }
141
+ finally {
142
+ await handle.close().catch(() => undefined);
143
+ await rm(guard, { force: true });
144
+ }
145
+ return true;
146
+ }
101
147
  /**
102
148
  * Claim the project's lock. The lock is written to a temporary file and then
103
149
  * hard-linked into place, so it appears complete or not at all, and only one
@@ -120,11 +166,10 @@ export async function writeLock(root, port, opts = {}) {
120
166
  if (existing && alive(existing.pid) && (await isRushesFor(existing.port, root))) {
121
167
  throw new AlreadyRunningError(`http://127.0.0.1:${existing.port}`);
122
168
  }
123
- // Stale: remove it only if it's still the lock we just judged.
124
- const again = await readLockFile(root);
125
- if (!existing || (again && again.token === existing.token && again.pid === existing.pid && again.startedAt === existing.startedAt)) {
126
- await rm(path, { force: true });
127
- }
169
+ // Stale: remove it, and only it. Another claimant may be removing it too, so wait for the guard.
170
+ const until = Date.now() + GUARD_WAIT_MS;
171
+ while (!(await removeStale(root, existing)) && Date.now() < until)
172
+ await new Promise((r) => setTimeout(r, 5));
128
173
  continue;
129
174
  }
130
175
  await new Promise((r) => setTimeout(r, 25));
@@ -0,0 +1,114 @@
1
+ import { lstat, readFile, rename, writeFile } from "node:fs/promises";
2
+ import { join } from "node:path";
3
+ import { hashText } from "../core/brief.js";
4
+ import { NotFoundError } from "../core/errors.js";
5
+ // §24 steps 2 and 3: brief.md and storyboard.md are files of record. The agent writes them with its own tools; the
6
+ // dashboard writes them through a service built on this. Rushes keeps only `.rushes/<key>.json` for each: the agent's
7
+ // last text (the "Current" column) and the hash it last saw, so it can tell the dashboard's writes from anyone else's.
8
+ /** A record is a page or two. Anything bigger than this is some other file, and is not read. */
9
+ export const MAX_RECORD_BYTES = 1_000_000;
10
+ export class RecordFile {
11
+ store;
12
+ file;
13
+ key;
14
+ changed;
15
+ path;
16
+ queue = Promise.resolve();
17
+ /**
18
+ * @param file the file's name in the project folder's root
19
+ * @param key which `.rushes/*.json` holds its baseline and hash
20
+ * @param changed the error a save gets when the file changed since the page loaded
21
+ */
22
+ constructor(store, file, key, changed) {
23
+ this.store = store;
24
+ this.file = file;
25
+ this.key = key;
26
+ this.changed = changed;
27
+ this.path = join(store.root, file);
28
+ }
29
+ /** One operation at a time, so a save and a look at the file can never interleave. */
30
+ run(fn) {
31
+ const next = this.queue.catch(() => undefined).then(fn);
32
+ this.queue = next;
33
+ return next;
34
+ }
35
+ /** The file's text, or null when there is none: missing, a folder, a link (never followed), or too big to be one. */
36
+ async readText() {
37
+ try {
38
+ const st = await lstat(this.path);
39
+ if (!st.isFile() || st.size > MAX_RECORD_BYTES)
40
+ return null;
41
+ return await readFile(this.path, "utf8");
42
+ }
43
+ catch (e) {
44
+ if (["ENOENT", "ENOTDIR", "EISDIR", "ELOOP"].includes(e.code ?? ""))
45
+ return null;
46
+ throw e;
47
+ }
48
+ }
49
+ /** Notices a change made by anyone but the dashboard: that text becomes the agent's version. */
50
+ sync() {
51
+ return this.run(async () => {
52
+ const text = await this.readText();
53
+ if (text === null)
54
+ return;
55
+ const hash = hashText(text);
56
+ if ((await this.store.read(this.key)).seen === hash)
57
+ return;
58
+ await this.store.update(this.key, (d) => {
59
+ d.baseline = text;
60
+ d.seen = hash;
61
+ });
62
+ });
63
+ }
64
+ async write(prev, next) {
65
+ const tmp = join(this.store.root, `.${this.file}.${process.pid}.${Date.now()}.tmp`);
66
+ await writeFile(tmp, next, "utf8");
67
+ await rename(tmp, this.path);
68
+ const prevHash = hashText(prev);
69
+ const nextHash = hashText(next);
70
+ // If Rushes had not yet seen `prev`, it is the agent's version: keep it as the baseline before the edit lands.
71
+ await this.store.update(this.key, (d) => {
72
+ if (d.seen !== prevHash)
73
+ d.baseline = prev;
74
+ d.seen = nextHash;
75
+ });
76
+ }
77
+ /** The file's text, once the page has proved it saw it: 404 with no file, 409 when it has changed since. */
78
+ async current(expectHash) {
79
+ const text = await this.readText();
80
+ if (text === null)
81
+ throw new NotFoundError(this.file === "brief.md" ? "Brief" : "Storyboard", this.file);
82
+ if (hashText(text) !== expectHash)
83
+ throw this.changed();
84
+ return text;
85
+ }
86
+ /** Looks for changes made outside the dashboard every `pollMs`, and once at the start. Returns a stop function. */
87
+ start(pollMs = 500) {
88
+ let stopped = false;
89
+ let last = null;
90
+ let timer;
91
+ const tick = async () => {
92
+ try {
93
+ const st = await lstat(this.path).catch(() => null);
94
+ const sig = st ? `${st.mtimeMs}:${st.size}:${st.ino}` : "";
95
+ if (sig !== last) {
96
+ last = sig;
97
+ await this.sync();
98
+ }
99
+ }
100
+ catch {
101
+ // A file that cannot be read now is looked at again on the next change.
102
+ }
103
+ if (!stopped) {
104
+ timer = setTimeout(() => void tick(), pollMs);
105
+ timer.unref?.();
106
+ }
107
+ };
108
+ void tick();
109
+ return () => {
110
+ stopped = true;
111
+ clearTimeout(timer);
112
+ };
113
+ }
114
+ }
@@ -7,6 +7,8 @@ import { ensureProjectIdOnce } from "../core/project.js";
7
7
  import { createApp } from "./app.js";
8
8
  import { removeLock, writeLock } from "./lock.js";
9
9
  import { watchStore } from "./watch.js";
10
+ import { BriefService } from "./brief.js";
11
+ import { StoryboardService } from "./storyboard.js";
10
12
  import { ProxyJobs, removePartials } from "./proxy.js";
11
13
  import { PeakJobs, removeOrphanPeaks, removePeakTemps } from "./peaks.js";
12
14
  import { FoundScanner, ffprobeDuration, foundAnnouncer } from "./found.js";
@@ -49,7 +51,9 @@ export async function startServer(rootDir, opts = {}) {
49
51
  const peakJobs = new PeakJobs(store, { available: () => proxyJobs.available(), ...opts.peaks });
50
52
  // §20: the project's other files. Its first scan starts once this server owns the project (below).
51
53
  const found = new FoundScanner({ store, probe: opts.found?.probe ?? ffprobeDuration, announce: foundAnnouncer(store), limits: opts.found?.limits });
52
- const appOpts = { webDir: opts.webDir, onShutdown: () => void close(), reveal: opts.reveal, proxyJobs, peakJobs, found, formatProbe: opts.formats?.probe };
54
+ const brief = new BriefService(store);
55
+ const storyboard = new StoryboardService(store);
56
+ const appOpts = { brief, storyboard, webDir: opts.webDir, onShutdown: () => void close(), reveal: opts.reveal, proxyJobs, peakJobs, found, formatProbe: opts.formats?.probe };
53
57
  const app = createApp(store, appOpts);
54
58
  const listener = getRequestListener(app.fetch);
55
59
  let lastRequest = Date.now();
@@ -102,6 +106,8 @@ export async function startServer(rootDir, opts = {}) {
102
106
  appOpts.projectId = id;
103
107
  const url = `http://${host}:${port}`;
104
108
  const stopWatching = await watchStore(store);
109
+ const stopBrief = brief.start();
110
+ const stopStoryboard = storyboard.start();
105
111
  // §20.1: a first look through the folder on open. Never awaited, so it never delays start-up;
106
112
  // the tabs hear a change when it lands.
107
113
  // Then §20.4's current set comes in (a no-op without a cut, or when it's already in).
@@ -117,6 +123,8 @@ export async function startServer(rootDir, opts = {}) {
117
123
  closing ??= (async () => {
118
124
  clearTimeout(idleTimer);
119
125
  stopWatching();
126
+ stopBrief();
127
+ stopStoryboard();
120
128
  // No probe starts after this, and those in flight are stopped.
121
129
  found.close();
122
130
  // A running proxy's ffmpeg must not outlive the server; its partial file is deleted too.
@@ -0,0 +1,109 @@
1
+ import { lstat } from "node:fs/promises";
2
+ import { join } from "node:path";
3
+ import { hashText } from "../core/brief.js";
4
+ import { InvalidError, RushesError } from "../core/errors.js";
5
+ import { STORYBOARD_FILE, cutShots, editShot, parseStoryboard } from "../core/storyboard.js";
6
+ import { RecordFile } from "./record.js";
7
+ // §24.12: storyboard.md is the file of record for the shots. See RecordFile for how it is kept.
8
+ export class StoryboardChangedError extends RushesError {
9
+ constructor() {
10
+ super("storyboard.md changed since you loaded it. Showing the file as it is now.", 409, "storyboard_changed");
11
+ }
12
+ }
13
+ export const NO_STORYBOARD = { exists: false, title: "", hash: "", shots: [], changed: 0, approved: 0, total: 0, plannedLength: 0 };
14
+ export class StoryboardService extends RecordFile {
15
+ constructor(store) {
16
+ super(store, STORYBOARD_FILE, "storyboard", () => new StoryboardChangedError());
17
+ }
18
+ build(text, state) {
19
+ if (text === null)
20
+ return NO_STORYBOARD;
21
+ const hash = hashText(text);
22
+ const yours = parseStoryboard(text);
23
+ // Until Rushes has looked at the file, or when it changed before the poll noticed, the file itself is the agent's version.
24
+ const base = state.seen !== "" && state.seen === hash ? parseStoryboard(state.baseline) : yours;
25
+ const seen = new Map();
26
+ const shots = yours.shots.map((s) => {
27
+ const n = seen.get(s.heading) ?? 0;
28
+ seen.set(s.heading, n + 1);
29
+ const match = base.shots.filter((b) => b.heading === s.heading)[n];
30
+ const current = match ? match.description : s.description;
31
+ const directionCurrent = match ? match.direction : s.direction;
32
+ return { ...s, current, directionCurrent, changed: current !== s.description || directionCurrent !== s.direction };
33
+ });
34
+ return {
35
+ exists: true,
36
+ title: yours.title,
37
+ hash,
38
+ shots,
39
+ changed: shots.filter((s) => s.changed).length,
40
+ approved: shots.filter((s) => s.status === "approved").length,
41
+ total: shots.length,
42
+ plannedLength: Math.round(shots.reduce((a, s) => a + (s.length ?? 0), 0) * 1000) / 1000,
43
+ };
44
+ }
45
+ /** Whether a still, or any folder on the way to it, is a link. The project's own files are never followed out of it. */
46
+ async linked(still) {
47
+ let at = this.store.root;
48
+ for (const seg of still.split("/")) {
49
+ at = join(at, seg);
50
+ try {
51
+ if ((await lstat(at)).isSymbolicLink())
52
+ return true;
53
+ }
54
+ catch {
55
+ return false;
56
+ }
57
+ }
58
+ return false;
59
+ }
60
+ /** The view with every still that goes through a link taken out: it is no still. */
61
+ async safe(v) {
62
+ const shots = await Promise.all(v.shots.map(async (s) => (s.still && (await this.linked(s.still)) ? { ...s, still: null } : s)));
63
+ return { ...v, shots };
64
+ }
65
+ view() {
66
+ return this.run(async () => this.safe(this.build(await this.readText(), await this.store.read("storyboard"))));
67
+ }
68
+ /**
69
+ * Saves a change to one shot. Changing an approved shot's description or direction reopens it (its status goes
70
+ * back to draft) unless the same edit sets the status.
71
+ */
72
+ setShot(index, heading, edit, expectHash) {
73
+ return this.run(async () => {
74
+ const prev = await this.current(expectHash);
75
+ const was = parseStoryboard(prev).shots.find((s) => s.index === index);
76
+ const changesWords = was && ((edit.description !== undefined && edit.description.trim() !== was.description) || (edit.direction !== undefined && edit.direction.replace(/\s*\r?\n\s*/g, " ").trim() !== was.direction));
77
+ const full = was?.status === "approved" && changesWords && edit.status === undefined ? { ...edit, status: "draft" } : edit;
78
+ let next;
79
+ try {
80
+ next = editShot(prev, index, heading, full);
81
+ }
82
+ catch (e) {
83
+ throw new InvalidError(e.message);
84
+ }
85
+ if (next !== prev)
86
+ await this.write(prev, next);
87
+ return this.safe(this.build(next, await this.store.read("storyboard")));
88
+ });
89
+ }
90
+ /** The pictures the storyboard names, for the media route: only safe, project-relative image paths. */
91
+ stills() {
92
+ return this.run(async () => {
93
+ const text = await this.readText();
94
+ const named = text === null ? [] : parseStoryboard(text).shots.flatMap((s) => (s.still ? [s.still] : []));
95
+ const safe = [];
96
+ for (const still of named)
97
+ if (!(await this.linked(still)))
98
+ safe.push(still);
99
+ return new Set(safe);
100
+ });
101
+ }
102
+ /** The shots as a new cut's shot list (each start the running total of the lengths), or none without a storyboard. */
103
+ cutShots() {
104
+ return this.run(async () => {
105
+ const text = await this.readText();
106
+ return text === null ? [] : cutShots(parseStoryboard(text).shots);
107
+ });
108
+ }
109
+ }