rushes 0.3.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.
package/dist/mcp/tools.js CHANGED
@@ -146,12 +146,12 @@ export function createMcpServer(ctx) {
146
146
  }, safe(async ({ project, video, version }) => (await ctx.client(project)).put(`/api/videos/${encodeURIComponent(video)}/lock`, { version })));
147
147
  server.registerTool("rushes_status", {
148
148
  title: "Rushes status",
149
- description: "Which tabs are unlocked and how many open items each has.",
149
+ description: "Which tabs are unlocked and how many open items each has. Also `brief`: whether brief.md exists, its status (draft or approved, set when the user presses Approve) and how many sections the user changed; `storyboard`: whether storyboard.md exists, how many shots there are, how many are approved and how many the user changed; and `build`: whether planning has begun (`started`), whether the brief, every script section (when there is a script) and every shot are approved (`ready`), and what it is `waitingOn`.",
150
150
  inputSchema: { project },
151
151
  }, safe(async ({ project }) => (await ctx.client(project)).get("/api/tabs")));
152
152
  server.registerTool("rushes_add_version", {
153
153
  title: "Add a cut",
154
- description: "Register a new cut of a video. The first cut creates the video. Returns the new version id (v1, v2 ...). When the cut is likely to play badly in a browser (4K, over 1.5 GB, or a codec such as ProRes), it also returns proxySuggested: true and proxyReason; Picture offers the user a proxy. If the project has autoProxy on, proxyJob is the proxy already being made. Give every cut a short `label` (" + LABEL_MAX + " characters at most) saying what changed, e.g. \"launch 1.45x slower\", and put the detail in `note`: the version list shows the label. Pass `formats` to register the other shapes of the same cut in one call; the reply then carries `formatWarnings` (a list, one entry for each shape more than 0.1 s off the cut's length; `warning` here means Picture is locked).",
154
+ description: "Register a new cut of a video. The first cut creates the video. Returns the new version id (v1, v2 ...). When the cut is likely to play badly in a browser (4K, over 1.5 GB, or a codec such as ProRes), it also returns proxySuggested: true and proxyReason; Picture offers the user a proxy. If the project has autoProxy on, proxyJob is the proxy already being made. Give every cut a short `label` (" + LABEL_MAX + " characters at most) saying what changed, e.g. \"launch 1.45x slower\", and put the detail in `note`: the version list shows the label. Pass `formats` to register the other shapes of the same cut in one call; the reply then carries `formatWarnings` (a list, one entry for each shape more than 0.1 s off the cut's length; `warning` here means Picture is locked). When the plan (brief, script, storyboard) has been started but is not all approved, it carries `planWarning` saying what is outstanding: a nudge, never a refusal. A film's first cut also starts with the storyboard's shots.",
155
155
  inputSchema: {
156
156
  project,
157
157
  video: z.string().describe("Video id or name, e.g. \"Hero 60s\"."),
@@ -224,7 +224,19 @@ export function createMcpServer(ctx) {
224
224
  .max(200)
225
225
  .optional()
226
226
  .describe("One line on what this read, bed or pass is, shown on its lane card. Stored as meta.description, and wins over one given in meta."),
227
- cues: z.array(z.object({ name: z.string(), t: z.number().nonnegative() })).optional().describe("SFX cues with times in seconds."),
227
+ cues: z
228
+ .array(z.object({
229
+ name: z.string(),
230
+ t: z.number().nonnegative(),
231
+ // No .max here: the 1024 limit is on the stored path, so checkCueFile enforces it and names the cue (§23.6).
232
+ file: z
233
+ .string()
234
+ .min(1)
235
+ .optional()
236
+ .describe("Optional: the sample you placed at this cue (an audio file, a path of up to 1024 characters), so the user can see which it is and hear it on its own."),
237
+ }))
238
+ .optional()
239
+ .describe("SFX cues with times in seconds, each optionally with the `file` of its sample. Give a sound the same name every time it comes back: the tab groups cues by name."),
228
240
  },
229
241
  }, safe(async ({ project, ...b }) => (await ctx.client(project)).post("/api/variants", b)));
230
242
  server.registerTool("rushes_set_script", {
@@ -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.3.0";
34
+ export const VERSION = "0.5.0";
32
35
  async function body(c, schema) {
33
36
  let json;
34
37
  try {
@@ -113,7 +116,9 @@ const VariantBody = z.object({
113
116
  file: z.string().min(1),
114
117
  meta: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
115
118
  description: z.string().min(1).max(200).optional(),
116
- cues: z.array(z.object({ name: z.string().min(1), t })).optional(),
119
+ // §23.6: a cue's file has no length cap here. The 1024 limit applies to the stored (manifest) form,
120
+ // which checkCueFile enforces with a 400 naming the cue.
121
+ cues: z.array(z.object({ name: z.string().min(1), t, file: z.string().min(1).optional() })).optional(),
117
122
  });
118
123
  const ScriptBody = z.object({
119
124
  wordsPerSecond: z.number().positive().optional(),
@@ -126,6 +131,19 @@ const SectionEditBody = z.object({
126
131
  status: SectionStatusSchema.optional(),
127
132
  });
128
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" });
129
147
  // A pick is a variant or take id; null clears it. picks.json itself only ever holds strings.
130
148
  const PickMap = z.record(z.string(), z.string().nullable());
131
149
  // §19.6: a level is −24..6 dB in 0.5 dB steps; null resets it to 0 (removes the key).
@@ -242,6 +260,13 @@ export function createApp(store, opts = {}) {
242
260
  const jobs = opts.proxyJobs ?? new ProxyJobs(store);
243
261
  const peaks = opts.peakJobs ?? new PeakJobs(store, { run: jobs.run, available: () => jobs.available() });
244
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
+ };
245
270
  // §22: the Change Log, shared with the found scanner (logBookFor keeps one per store).
246
271
  const log = logBookFor(store);
247
272
  const by = (c) => byOf(c.req.header("x-rushes-project"));
@@ -400,7 +425,10 @@ export function createApp(store, opts = {}) {
400
425
  // and the one a byte-range video seek hits over and over. Only a path that misses all three
401
426
  // falls through to candidatePaths, which does the readdir-backed discovery (§16.2's
402
427
  // auto-discovered docs/captions/exports) that a registered path never needs.
403
- 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;
404
432
  // The file on disk to send. For a found file it's exactly the path that was checked.
405
433
  let file = fromManifestPath(store.root, path);
406
434
  let viaFound = false;
@@ -479,8 +507,9 @@ export function createApp(store, opts = {}) {
479
507
  // the symlink's target, so the write can never escape screenshots/ that way. It also means
480
508
  // nothing ever lists a half-written PNG. The temp name starts with "." and ends in ".tmp",
481
509
  // which SCREENSHOT_PATH (the safe-name filter) already excludes from both /media and the
482
- // Assets listing.
483
- 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`);
484
513
  await writeFile(tmp, bytes);
485
514
  await rename(tmp, fromManifestPath(store.root, grab));
486
515
  return c.json({ grab }, 201);
@@ -605,8 +634,8 @@ export function createApp(store, opts = {}) {
605
634
  app.get("/api/state", async (c) => {
606
635
  // §20.6: found is what the last scan left in memory; it never waits on a scan or a probe.
607
636
  // §22.8: the log's head is read-only, so a state request never writes (R6).
608
- const [project, script, notes, picks, batches, ffmpeg, foundSummary, logHead] = await Promise.all([
609
- 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(),
610
639
  ]);
611
640
  const tabs = tabStates(project, script, notes);
612
641
  // §19.5: why each cut may play badly (or null). Never waits on a probe: an unprobed cut is
@@ -615,7 +644,7 @@ export function createApp(store, opts = {}) {
615
644
  ...v,
616
645
  versions: await Promise.all(v.versions.map(async (ver) => ({ ...ver, proxyNeed: await jobs.needNow(fromManifestPath(store.root, ver.file)) }))),
617
646
  })));
618
- 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 }) });
619
648
  });
620
649
  // ---- found: the project's other files (§20) ----
621
650
  app.get("/api/found", async (c) => {
@@ -702,7 +731,33 @@ export function createApp(store, opts = {}) {
702
731
  });
703
732
  app.get("/api/tabs", async (c) => {
704
733
  const [project, script, notes] = await Promise.all([store.read("project"), store.read("script"), store.read("notes")]);
705
- 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) });
706
761
  });
707
762
  // ---- notes ----
708
763
  app.get("/api/notes", async (c) => {
@@ -789,6 +844,8 @@ export function createApp(store, opts = {}) {
789
844
  // before formats (a formats call was refused above).
790
845
  const size = read && isPictureSize(read.width, read.height) ? read : null;
791
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();
792
849
  let lockedVersion = null;
793
850
  let autoProxy = false;
794
851
  let films = 1;
@@ -814,6 +871,12 @@ export function createApp(store, opts = {}) {
814
871
  if (added.warning)
815
872
  formatWarnings.push(added.warning);
816
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
+ }
817
880
  lockedVersion = out.video.lockedVersion;
818
881
  autoProxy = p.autoProxy;
819
882
  films = p.videos.length;
@@ -836,7 +899,9 @@ export function createApp(store, opts = {}) {
836
899
  if (autoProxy && !jobs.isClosing)
837
900
  proxy.proxyJob = jobs.start(result.video.id, result.version.id);
838
901
  }
839
- 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 } : {}) };
840
905
  if (lockedVersion)
841
906
  return c.json({ ...result, ...proxy, ...warnings, warning: `Picture is locked at ${lockedVersion}` }, 201);
842
907
  return c.json({ ...result, ...proxy, ...warnings }, 201);
@@ -1007,7 +1072,9 @@ export function createApp(store, opts = {}) {
1007
1072
  });
1008
1073
  app.post("/api/variants", async (c) => {
1009
1074
  const b = await body(c, VariantBody);
1010
- const { result } = await store.update("project", (p) => addVariant(p, { ...b, file: toManifestPath(store.root, b.file) }));
1075
+ // §23: a cue's file is stored as a manifest path, like the variant's own.
1076
+ const cues = b.cues?.map((q) => (q.file === undefined ? q : { ...q, file: toManifestPath(store.root, q.file) }));
1077
+ const { result } = await store.update("project", (p) => addVariant(p, { ...b, cues, file: toManifestPath(store.root, b.file) }));
1011
1078
  await log.add(() => variantEvent(result.lane, result.variant), by(c));
1012
1079
  return c.json(result, 201);
1013
1080
  });
@@ -1090,21 +1157,31 @@ export function createApp(store, opts = {}) {
1090
1157
  return c.json(result);
1091
1158
  });
1092
1159
  // ---- batches ----
1093
- // 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.
1094
1164
  let batchQueue = Promise.resolve();
1095
1165
  app.post("/api/batches", async (c) => {
1096
1166
  const { stage } = await body(c, BatchBody);
1097
1167
  const run = batchQueue.catch(() => undefined).then(async () => {
1098
- const [project, script, batches] = await Promise.all([store.read("project"), store.read("script"), store.read("batches")]);
1099
- 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);
1100
1172
  // R11: the prompt ends with the last five lines of the log, from before this send. A log that
1101
- // 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.
1102
1174
  const recent = await Promise.all([store.read("project"), store.read("script")])
1103
1175
  .then(async ([projectNow, scriptNow]) => recentChanges((await log.view({ limit: 5 }, { project: projectNow, script: scriptNow })).entries))
1104
1176
  .catch(() => "");
1105
1177
  if (recent)
1106
1178
  result.prompt = `${result.prompt}\n\n${recent}`;
1107
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
+ });
1108
1185
  await log.add(() => notesSentEvent(result), by(c));
1109
1186
  return result;
1110
1187
  });
@@ -222,11 +222,12 @@ export async function listAssets(store, project, script) {
222
222
  return [...screenshots, ...cuts, ...proxies, ...takes, ...voice, ...music, ...sfx, ...library];
223
223
  }
224
224
  /**
225
- * Every path `/api/assets` would list, without stat'ing any of them: registered media (cuts,
226
- * takes, variants -- present whether or not the file is actually there) plus every *.png
227
- * directly inside screenshots/ and .rushes/grabs/ whose name the matching safe-name regex would
228
- * let /media serve. POST /api/reveal uses this to check a path cheaply, stat'ing only the one
229
- * file it actually needs instead of every asset in the project.
225
+ * Every path the project knows, without stat'ing any of them: registered media (cuts, takes,
226
+ * variants -- present whether or not the file is actually there), plus every *.png directly
227
+ * inside screenshots/ and .rushes/grabs/ whose name the matching safe-name regex would let /media
228
+ * serve. That is everything `/api/assets` lists and also cue samples (§23), which Assets doesn't
229
+ * list (§23.7). POST /api/reveal and /api/open use this to check a path cheaply, stat'ing only
230
+ * the one file they actually need instead of every asset in the project.
230
231
  */
231
232
  export async function candidatePaths(store, project, script) {
232
233
  const paths = registeredMedia(project, script);
@@ -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
+ }
@@ -2,6 +2,7 @@ import { createReadStream } from "node:fs";
2
2
  import { lstat, realpath, stat } from "node:fs/promises";
3
3
  import { extname, isAbsolute, join, normalize, sep } from "node:path";
4
4
  import { Readable } from "node:stream";
5
+ import { cueFiles } from "../core/cues.js";
5
6
  import { VIDEO_EXT } from "../core/media.js";
6
7
  import { PROXY_PATH } from "./proxy.js";
7
8
  export const CONTENT_TYPES = {
@@ -82,6 +83,9 @@ export function registeredMedia(project, script) {
82
83
  for (const l of project.lanes)
83
84
  for (const variant of l.variants)
84
85
  files.add(variant.file);
86
+ // §23: each cue's sample, when it is an audio file; served only because it is registered.
87
+ for (const f of cueFiles(project))
88
+ files.add(f);
85
89
  for (const s of script.sections)
86
90
  for (const t of s.takes)
87
91
  files.add(t.file);
@@ -7,6 +7,7 @@ import { slugify } from "../core/ids.js";
7
7
  import { AUDIO_FORMATS, probe as ffprobe } from "../core/media.js";
8
8
  import { fromManifestPath, toManifestPath } from "../core/paths.js";
9
9
  import { addFile, addVariant, addVersion, resolveVideo } from "../core/project.js";
10
+ import { cueFiles } from "../core/cues.js";
10
11
  import { logBookFor } from "./logbook.js";
11
12
  import { broughtInEvent, cutName } from "../core/logEvents.js";
12
13
  /** The audio kinds, which an include can settle. */
@@ -217,7 +218,7 @@ export function foundAnnouncer(store) {
217
218
  store.emit("change", { file: "found", rev: ++seq });
218
219
  };
219
220
  }
220
- /** Every manifest path the project has registered: cuts and their formats, variants, library files and script takes. */
221
+ /** Every manifest path the project has registered: cuts and their formats, variants, cue samples, library files and script takes. */
221
222
  export function registeredPaths(project, script) {
222
223
  const out = [];
223
224
  for (const v of project.videos) {
@@ -231,6 +232,9 @@ export function registeredPaths(project, script) {
231
232
  for (const l of project.lanes)
232
233
  for (const variant of l.variants)
233
234
  out.push(variant.file);
235
+ // §23: a cue's sample is part of its pass, not a pass of its own to bring in.
236
+ for (const f of cueFiles(project))
237
+ out.push(f);
234
238
  for (const f of project.files)
235
239
  out.push(f.file);
236
240
  for (const s of script.sections)
@@ -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.