rushes 0.2.1 → 0.2.2

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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "rushes",
3
3
  "description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent reads and acts on.",
4
- "version": "0.2.1",
4
+ "version": "0.2.2",
5
5
  "author": { "name": "Red Morley Hewitt" },
6
6
  "homepage": "https://github.com/iamredmh/rushes",
7
7
  "repository": "https://github.com/iamredmh/rushes",
package/AGENTS.md CHANGED
@@ -53,7 +53,7 @@ No project to show yet? Run `npx -y rushes demo <folder> --no-browser`, then `ru
53
53
 
54
54
  ## Locked tabs and the prompts they copy
55
55
 
56
- Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. If the user pastes you one of these, it's a direct, already-scoped request — act on it the same as any other instruction, e.g.:
56
+ Every tab is visible from the start, in workflow order, even before it has anything in it. Opening a locked tab explains what it's for and what unlocks it, and offers a **Copy prompt for your agent** button. When Rushes has found files for a locked Voiceover, Music or Sound effects tab in the project folder, the page adds a line under the prompt, such as "14 music files found in this project", with a **Review** button that opens Assets › Found filtered to that kind. So a user may open a locked tab, see files you haven't brought in, and ask you about them: call `rushes_scan` to list them, and `rushes_bring_in` for the ones that belong. If the user pastes you one of these, it's a direct, already-scoped request — act on it the same as any other instruction, e.g.:
57
57
 
58
58
  > In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
59
59
 
@@ -65,7 +65,7 @@ Every tab is visible from the start, in workflow order, even before it has anyth
65
65
  - A voice read: `rushes_add_variant` with `stage: "voice"` and `round` (the round's name, e.g. "Round 2 · Gerald, tone" — reads in one round are compared side by side; a new direction gets a new round, a small fix to a marked word can stay in the current one). Say in `description` what the read is, or what changed from the one it's based on. `rushes_add_take` stays in the file format and API for compatibility only; voiceover work doesn't use it.
66
66
  - Music beds or SFX passes: `rushes_add_variant` with `stage` `music` or `sfx`. Give it `meta: {description: "..."}`, shown on its lane card in place of `bpm`/`key`; SFX passes also take `cues` (`{name, t}` in seconds), labelled on the waveform.
67
67
  - The storyboard's shots, once you have the first cut: `rushes_set_shots` with `video`, optional `version` (defaults to the newest) and `shots` as `{start, name, tag?}`. Send new timings whenever a later cut moves them.
68
- 2. **Open it for the user:** `rushes_open`. Each project's dashboard lives at its own address, `/p/<id>/` — safe to run more than one project at once. A tab unlocks as soon as it has something in it.
68
+ 2. **Open it for the user:** `rushes_open`. It also looks through the project folder and brings in the files that go with the cut (next section). Each project's dashboard lives at its own address, `/p/<id>/` — safe to run more than one project at once. A tab unlocks as soon as it has something in it.
69
69
  3. **Wait for feedback.** The user presses **Send to agent**, which saves a batch and gives them a prompt to paste to you. Call `rushes_get_batch` to read the latest batch, its notes and any changed script sections.
70
70
  4. **Fix each note.** A note has `stage`, `scope` (`point`, `range` or `whole` — Voiceover only ever uses `point` or `whole`; it has no Range scope), `t`, `tOut`, `on` (the lane, variant, take, cue or section it's about), `text`, and optionally `box` (normalised 0 to 1), `grab` (a PNG path in `screenshots/`; older notes may point to `.rushes/grabs/`) and `shot` (the shot it falls in, `{n, name}`, worked out by the server from the version's shots — not yours to set). On an audio stage, `on` is `"<laneId>/<variantId>"` for a music bed, SFX pass or voice read (the lane and variant ids `rushes_add_variant` returns) — on Voiceover the lane id is the round's slugged name, so `on` names the round and the read together — or `"<laneId>/<variantId>:<cueId>"` for an SFX cue. On Mix it's `null` for the whole mix, `"vo"` for the VO lane (the newest round with a pick), or `"<laneId>/<variantId>"` for the music or SFX lane. Older notes may carry a bare variant id, `"vo"` on Voiceover itself, a section id, `"<sectionId>:<takeId>"` for a take, `"<variantId>:<cueId>"` or a bare cue id; Rushes still lists these with a sensible label, but none of them name a read any more. On Music, Sound effects and Mix, a note can also carry `marks` — short feedback like `Fall` (bring the level down over the range) or `Quieter 3 dB` (3 dB lower over the range). `rushes_list_notes`, `rushes_get_batch` and exported notes all show them. Marks are the user's, like a note's text and times — you read and act on them, you don't set them. Voiceover notes carry no marks: a note there is **Whole** (`Speaker`, `Pacing`, `Tone` or `Overall` — about the read as a whole) or **Point** (`Fix this` or `Keep this`, marked at the playhead).
71
71
  5. **Register the new cut** with `rushes_add_version` and note what changed. If the video is locked, the reply carries `warning: "Picture is locked at vN"`; the version is still added.
@@ -77,9 +77,21 @@ Every tab is visible from the start, in workflow order, even before it has anyth
77
77
  Then reply as in step 6. Mix plays the newest round's picked voice read; takes are never mixed.
78
78
  8. **Script batches.** When a section's `proposed` differs from `current`, the user rewrote the line. Adopt it by calling `rushes_set_script` with just that section's `id`, `start`, `end` and the new `current`; the other sections stay as they are. The proposal then clears itself, and a flagged section goes back to draft. If voiceover already exists, re-record the picked voice with the corrected script and register it with `rushes_add_variant` as a new read in a new round.
79
79
 
80
+ ## Opening a project, and the files that go with the cut
81
+
82
+ When asked to open or review work in Rushes, call `rushes_open`, then tell the user what it brought in and what it left. Rushes looks through the project folder itself, and only inside it: it never follows a link out and never reads a file's contents. It brings in the current set of files that go with the newest cut, unpicked, so Voiceover, Music and Sound effects have something to review, and leaves everything else one step away in Assets › Found. At most one file per kind comes in, and only when it clearly matches the cut by length, time and name. Nothing is ever picked; the user chooses in the dashboard.
83
+
84
+ `rushes_open` returns `broughtIn` (every file Rushes has brought in since it started, so it can include files from earlier calls and ones the user brought in by hand; each has its kind, lane, reasons and `origin`: `auto` for the scoring, `include` for yours, `hand` for the user's), `alreadyIn` (your `include` files that were already registered), `failed` (files that couldn't come in, with the reason) and `found` (counts of what it left, by kind; `rushes_scan` calls the same counts `counts`). It waits about 20 seconds for the folder to be looked through. On a big folder it answers with `scanning: true` and carries on in the background; call `rushes_scan` or `rushes_open` again later for the rest. Say it plainly, for example: "I brought in `vo_jules/read.wav` as a voice read and `bed/theme.wav` as music. 14 more files are in Assets › Found."
85
+
86
+ Pass `include` for files you made for this cut: `include: [{ path, kind?, round? }]`. They come in whatever they score, and they win over the scoring: a kind you include (voice, music or sfx) isn't also guessed for that cut, on any later scan or restart (Rushes keeps this in `.rushes/found.json`). A newer cut is a fresh decision, and nothing already registered is ever removed. One narrow case: if Rushes had just started and had already brought in its own pick before your call arrived, both are in, unpicked. Give `kind` (`voice`, `music`, `sfx`, `cut` or `doc`) when the name doesn't say, and `round` for a voice read. `rushes_open` also takes `film`, to match the files to a film other than the newest cut's. If the scoring picked the wrong file, bring the right one in with `include` (or `rushes_bring_in`) and say which.
87
+
88
+ `rushes_scan` (CLI `rushes scan [--film NAME] [--json]`) looks again, brings in the current set as opening does, and returns the candidates that are left, best score first, up to 200 (default 100), each with its reasons. `rushes_bring_in` (CLI `rushes bring-in <file>... [--kind K] [--round NAME] [--film NAME]`, which exits 1 if any file can't come in) brings chosen files in: voice, music and sfx as variants, video as cuts, `md`, `txt` and `pdf` as docs. It refuses any path outside the project folder, reports each file it can't bring in with the reason, and takes up to 60 files at a time and up to 12 files of each kind per call (the dashboard's **Bring in** has the same cap per click, so the tabs stay quick). Each refusal is `{ path, reason, code }`: match on `code` (`outside`, `gone`, `already`, `cap`, `link`, `folder`, `hiddenFile`, `skippedFolder`, `chooseKind`, `notAudio`, `notVideo`, `notDoc`, `unknownType`, or `other`), never on the words.
89
+
90
+ The user sees the rest in **Assets › Found**, the first folder in Assets: files grouped by folder with their reasons, a play button to audition each one, **Bring in N** (the ticked files, up to 12 of each kind per click), **Not these** (hides them for good, with a **Hidden** list and **Restore**), **Look again** (the same scan as `rushes_scan`) and a header chip, "3 brought in · 118 more found", while something is new. Files in Found are never an agent's to pick for the user; whatever comes in, by you or by Rushes, is unpicked.
91
+
80
92
  ## Tools
81
93
 
82
- The MCP server has seventeen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes` and `rushes_doctor`. Each takes an optional `project` folder, which defaults to the folder the harness started in.
94
+ The MCP server has nineteen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor`. Each takes an optional `project` folder, which defaults to the folder the harness started in.
83
95
 
84
96
  ## Rules
85
97
 
@@ -105,6 +117,8 @@ npx -y rushes add shots shots.json --video "Hero 60s" --version v2
105
117
  npx -y rushes add file brief.pdf --kind doc
106
118
  npx -y rushes export notes
107
119
  npx -y rushes doctor --json
120
+ npx -y rushes scan --json
121
+ npx -y rushes bring-in audio/music/bed.wav --kind music
108
122
  ```
109
123
 
110
124
  `shots.json` is a JSON array of `{name, start, tag?}`, or that array wrapped as `{"shots": [...]}`.
package/README.md CHANGED
@@ -40,7 +40,7 @@ If your user asked you to use Rushes, do this:
40
40
  2. If it added anything, tell the user to restart the app (or start a new session) so the `rushes_*` tools load.
41
41
  3. From then on, follow [AGENTS.md](AGENTS.md). In short: register what you made, call `rushes_open`, wait for the user to press **Send to agent**, then `rushes_get_batch`, fix the notes, and `rushes_reply`.
42
42
 
43
- The MCP server has seventeen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes` and `rushes_doctor`.
43
+ The MCP server has nineteen tools: `rushes_open`, `rushes_status`, `rushes_add_version`, `rushes_add_variant`, `rushes_set_script`, `rushes_get_script`, `rushes_add_take`, `rushes_list_notes`, `rushes_list_assets`, `rushes_get_batch`, `rushes_reply`, `rushes_get_picks`, `rushes_set_shots`, `rushes_lock_picture`, `rushes_add_file`, `rushes_export_notes`, `rushes_scan`, `rushes_bring_in` and `rushes_doctor`.
44
44
 
45
45
  If you can't run commands, give the user the matching line from **Manual setup** below.
46
46
 
@@ -69,6 +69,8 @@ npx -y rushes open # opens the review desk in your browser
69
69
  npx -y rushes stop # stops it
70
70
  ```
71
71
 
72
+ `rushes open` also looks through the folder for the files that go with the cut, and says what it brought in and what it left (see **Finding your other files**).
73
+
72
74
  Each project opens at its own address, `http://127.0.0.1:4580/p/<id>/` — safe to run several projects at once.
73
75
 
74
76
  A server your agent starts in the background stops by itself after two hours with nothing connected.
@@ -123,8 +125,37 @@ Every tab is visible from the start, in workflow order, even before there's anyt
123
125
 
124
126
  > In Rushes project "Launch", make two or three music beds for "Hero" and add each with rushes_add_variant (stage "music") with a one-line description.
125
127
 
128
+ When the project's folder already holds files for a locked Voiceover, Music or Sound effects tab, its page also says how many were found and offers a **Review** button, such as "14 music files found in this project". See **Finding your other files**, below.
129
+
126
130
  Hovering a locked tab shows a short tooltip, e.g. "Locked: ask your agent for music beds". The Assets tab follows the same rule.
127
131
 
132
+ ## Finding your other files
133
+
134
+ An agent only shows what it registers, but the work that goes with a cut usually sits in the same folder: the voiceover, the music, the effects. So when a project is opened, Rushes looks through the folder itself, and brings in the **current set** for the newest cut so those tabs have something to review.
135
+
136
+ - **When.** On open (`rushes open`, or your agent's `rushes_open`) and whenever you press **Look again** or run `rushes scan`. There's no folder watcher.
137
+ - **Where.** Only inside the project folder, up to eight folders deep. It never follows a symlink out of it, never reads a file's contents, and skips hidden folders, `node_modules` and Rushes' own `.rushes`, `proxies`, `screenshots` and `exports`. It examines up to 5,000 files. The dashboard never waits for it: a big folder shows "Looking through the folder…" and fills in as it goes.
138
+ - **What each file probably is.** The nearest folder or file-name word decides: `vo`, `voice`, `narration` for voiceover; `bed`, `music`, `score` for music; `sfx`, `foley`, `whoosh` for sound effects. Audio with no such word is "Other audio", and you choose its kind. Video files other than the registered cut are offered as other cuts.
139
+ - **The current set.** Each audio file is scored against the cut: a similar length, being made around the same time, and sharing a word or version (such as `v20`) with its name. For each kind, the best file comes in on its own only when it clearly beats the rest. That's at most one voice read, one music bed and one sound effects pass, and nothing else. Nothing is ever picked: files come in unpicked, and you choose in the dashboard. Each one carries its reasons, in plain words.
140
+ - **Assets › Found.** Everything else stays one step away, in the **Found** folder at the top of Assets. Files are grouped by folder, with their length, size and reasons, and you can play one before you bring it in. A chip in the header ("3 brought in · 118 more found") opens it while there's something new to look at.
141
+ - **Bring in** registers the ticked files: voiceover, music and sound effects as variants, and video as cuts. It takes up to 12 files of each kind at a time, so the tabs stay quick; each voiceover folder becomes its own round.
142
+ - **Not these** hides the ticked files for good. A **Hidden** list brings them back with **Restore**.
143
+ - **Look again** runs the scan once more, and a filter box and kind buttons narrow the list.
144
+ - Files already in the project are never offered twice.
145
+ - **Locked tabs say so.** If the folder holds files for a tab that's still locked, its page adds a line under the prompt, such as "14 music files found in this project" (or "1 music file found in this project"), with a **Review** button that opens Found filtered to that kind. The line follows the live count.
146
+
147
+ If the guess is wrong, ask your agent to bring in the right file: `rushes_bring_in`, or `include` on `rushes_open` for files it made for this cut, which come in whatever they score and win over the guess. `rushes_scan` lists what's left, with reasons.
148
+
149
+ The same from the command line:
150
+
151
+ ```bash
152
+ npx -y rushes scan [--film NAME] [--json]
153
+ npx -y rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME] [--film NAME]
154
+ ```
155
+
156
+ - `rushes scan` looks again, brings in the current set as opening does, and prints what it brought in and the top candidates left with their reasons. `--json` prints all of them as data.
157
+ - `rushes bring-in` brings the named files in. Paths are read from the folder you run it in. `--kind` is needed when a name doesn't say (`doc` takes `md`, `txt` and `pdf`), `--round` names the voiceover round, and `--film` picks the film a cut joins. It prints one line per file, says why for any it can't bring in (a path outside the project folder is always refused), and exits 1 if any failed.
158
+
128
159
  ## Screenshots and the Assets library
129
160
 
130
161
  Press **G**, or the camera button, to grab the current frame. It's saved as a PNG to `screenshots/`, named for the film, version and timecode — grabbing the same frame twice overwrites the same file.
@@ -296,7 +296,7 @@ export async function runDoctor(env) {
296
296
  checks.push({ id: `file:${key}`, label: name, ok: true, required: true, detail: "valid." });
297
297
  }
298
298
  catch (e) {
299
- checks.push({ id: `file:${key}`, label: name, ok: false, required: true, detail: e.message, fix: `Fix or restore ${name}, or delete the ${RUSHES_DIR} folder and run rushes init to start over.` });
299
+ checks.push({ id: `file:${key}`, label: name, ok: false, required: true, detail: e.message, fix: key === "found" ? `Delete ${RUSHES_DIR}/${name}. Rushes recreates it; files you hid come back in Found and the current set may be chosen again. Nothing else is lost.` : `Fix or restore ${name}, or delete the ${RUSHES_DIR} folder and run rushes init to start over.` });
300
300
  }
301
301
  }
302
302
  checks.push(await serverCheck(env.cwd));
package/dist/cli/main.js CHANGED
@@ -9,6 +9,7 @@ import { AlreadyRunningError, canonicalRoot } from "../server/lock.js";
9
9
  import { ApiError, RushesClient, dashboardUrlFor } from "../mcp/client.js";
10
10
  import { openBrowser, runStdio } from "../mcp/stdio.js";
11
11
  import { VERSION } from "../server/app.js";
12
+ import { BRING_IN_MAX } from "../server/found.js";
12
13
  import { markLabel } from "../core/schema.js";
13
14
  import { onLabel } from "../core/notes.js";
14
15
  import { setup } from "../setup/setup.js";
@@ -17,7 +18,8 @@ import { runDoctor, realDoctorEnv } from "./doctor.js";
17
18
  export const HELP = `rushes ${VERSION}: a local review desk for video made with AI agents
18
19
 
19
20
  Usage
20
- rushes open [dir] [--port 4580] [--no-browser] start the review desk and open it
21
+ rushes open [dir] [--film NAME] [--port 4580] [--no-browser]
22
+ start the review desk, bring in the files that go with the cut, and open it
21
23
  rushes serve [dir] [--port 4580] [--idle-minutes N]
22
24
  start the server without a browser (stops after N idle minutes)
23
25
  rushes stop [dir] stop the project's running server
@@ -38,6 +40,10 @@ Usage
38
40
  rushes notes [--stage S] [--status todo|done] [--batch ID] [--json]
39
41
  rushes reply <note-id> <text> [--done] [--fix-t SECONDS] [--fix-version V]
40
42
  rushes assets [--kind K] [--json] cuts, takes, variants, screenshots and library files
43
+ rushes scan [--film NAME] [--json] look through the folder for the files that go with the cut; also brings in the current set
44
+ rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME] [--film NAME]
45
+ register files from inside the project folder (nothing is picked);
46
+ exits 1 if any file can't come in
41
47
  rushes export notes write notes to exports/<slug>-notes-<date>.md
42
48
 
43
49
  Options
@@ -56,6 +62,7 @@ const OPTIONS = {
56
62
  status: { type: "string" },
57
63
  batch: { type: "string" },
58
64
  kind: { type: "string" },
65
+ film: { type: "string" },
59
66
  json: { type: "boolean" },
60
67
  done: { type: "boolean" },
61
68
  "fix-t": { type: "string" },
@@ -185,10 +192,29 @@ export async function main(argv, io) {
185
192
  if (cmd === "open" && !o["no-browser"])
186
193
  (io.openBrowser ?? openBrowser)(url);
187
194
  };
195
+ // §20.1: opening looks through the folder and brings in the current set, then says what it did.
196
+ // The desk is open either way, so a scan that fails says nothing.
197
+ const lookThrough = async (url) => {
198
+ if (cmd !== "open")
199
+ return;
200
+ io.err(LOOKING);
201
+ try {
202
+ const r = await new RushesClient(url).post("/api/found/scan", { wait: true, ...(o.film ? { film: o.film } : {}) });
203
+ if (r.added?.length)
204
+ io.out(broughtLine(r.added));
205
+ const left = foundTotal(r.found);
206
+ if (left)
207
+ io.out(`Found, left for you: ${count(left, "file")} \u2014 open Assets \u203a Found.`);
208
+ }
209
+ catch {
210
+ // Nothing to add to the line above.
211
+ }
212
+ };
188
213
  const already = async (url) => {
189
214
  const dashboardUrl = await dashboardUrlFor(url);
190
215
  io.out(`Rushes is already running for ${root}\n${dashboardUrl}`);
191
216
  show(dashboardUrl);
217
+ await lookThrough(url);
192
218
  return 0;
193
219
  };
194
220
  const running = await findServer(root);
@@ -209,13 +235,17 @@ export async function main(argv, io) {
209
235
  }
210
236
  io.out(`Rushes is running for ${root}\n${s.dashboardUrl}`);
211
237
  show(s.dashboardUrl);
212
- if (io.onServer)
213
- return io.onServer(s), 0;
214
- // Exit once the server closes for any reason: a signal, `rushes stop`, or the idle timer.
215
- void s.closed.then(() => process.exit(0));
216
- const stopSig = () => void s.close();
217
- process.once("SIGINT", stopSig);
218
- process.once("SIGTERM", stopSig);
238
+ if (io.onServer) {
239
+ io.onServer(s);
240
+ }
241
+ else {
242
+ // Exit once the server closes for any reason: a signal, `rushes stop`, or the idle timer.
243
+ void s.closed.then(() => process.exit(0));
244
+ const stopSig = () => void s.close();
245
+ process.once("SIGINT", stopSig);
246
+ process.once("SIGTERM", stopSig);
247
+ }
248
+ await lookThrough(s.url);
219
249
  return 0;
220
250
  }
221
251
  case "stop": {
@@ -390,6 +420,51 @@ export async function main(argv, io) {
390
420
  io.out("No assets");
391
421
  return 0;
392
422
  }
423
+ case "scan": {
424
+ const c = await client();
425
+ io.err(LOOKING);
426
+ const r = await c.post("/api/found/scan", { wait: true, ...(o.film ? { film: o.film } : {}) });
427
+ const { files } = await c.get("/api/found");
428
+ if (o.json)
429
+ return io.out(JSON.stringify({ files, counts: r.found ?? null, broughtIn: r.added ?? [], alreadyIn: r.alreadyIn ?? [], failed: r.failed ?? [], ...(r.scanning ? { scanning: true } : {}) }, null, 2)), 0;
430
+ if (r.added?.length)
431
+ io.out(broughtLine(r.added));
432
+ const left = foundTotal(r.found);
433
+ if (!left && !r.added?.length)
434
+ return io.out("Nothing found in this folder."), 0;
435
+ if (left) {
436
+ const kinds = Object.entries(r.found).filter(([, n]) => n > 0).map(([k, n]) => `${n} ${k === "cut" && n !== 1 ? "cuts" : k}`);
437
+ io.out(`Found, left for you: ${count(left, "file")} (${kinds.join(", ")})`);
438
+ for (const f of files.slice(0, SCAN_ROWS)) {
439
+ const why = f.reasons.length ? ` ${stripControl(f.reasons.join(" \u00b7 "))}` : "";
440
+ io.out(` ${f.kind.padEnd(6)} ${f.score === null ? "-" : String(f.score)} ${stripControl(f.path)}${why}`);
441
+ }
442
+ if (files.length > SCAN_ROWS)
443
+ io.out(` and ${files.length - SCAN_ROWS} more (rushes scan --json lists them all)`);
444
+ }
445
+ return 0;
446
+ }
447
+ case "bring-in": {
448
+ const bringInUsage = "rushes bring-in <file>... [--kind voice|music|sfx|cut|doc] [--round NAME]";
449
+ if (!rest.length)
450
+ return usage(io, bringInUsage);
451
+ if (o.kind !== undefined && !["voice", "music", "sfx", "cut", "doc"].includes(o.kind)) {
452
+ io.err(`--kind must be voice, music, sfx, cut or doc (got "${o.kind}")`);
453
+ return usage(io, bringInUsage);
454
+ }
455
+ if (rest.length > BRING_IN_MAX) {
456
+ io.err(`Up to ${BRING_IN_MAX} files at a time (and 12 of a kind), so the tabs stay quick. You gave ${rest.length}: bring the rest in with a second command.`);
457
+ return usage(io, bringInUsage);
458
+ }
459
+ // Paths are taken from the folder the command runs in; the server checks they're inside the project.
460
+ const files = rest.map((f) => ({ path: resolve(io.cwd, f), ...(o.kind ? { kind: o.kind } : {}), ...(o.round ? { round: o.round } : {}) }));
461
+ const r = await (await client()).post("/api/found/bring-in", { files, ...(o.film ? { film: o.film } : {}) });
462
+ for (const a of r.added)
463
+ io.out(`Brought in: ${stripControl(a.path)} (${a.kind})`);
464
+ for (const f of r.failed)
465
+ io.err(`Not brought in: ${stripControl(f.path)}: ${f.reason}`);
466
+ return r.failed.length ? 1 : 0;
467
+ }
393
468
  case "export": {
394
469
  const [what] = rest;
395
470
  if (what !== "notes")
@@ -430,6 +505,23 @@ export async function main(argv, io) {
430
505
  return 1;
431
506
  }
432
507
  }
508
+ /** Said on stderr while a scan is waited on, which can take several seconds on a big folder. */
509
+ const LOOKING = "Looking through the folder\u2026";
510
+ /** How many candidate rows `rushes scan` prints; --json has them all. */
511
+ const SCAN_ROWS = 10;
512
+ function count(n, word) {
513
+ return `${n} ${word}${n === 1 ? "" : "s"}`;
514
+ }
515
+ /** Everything a scan left, by kind, as one number. */
516
+ function foundTotal(counts) {
517
+ return Object.values(counts ?? {}).reduce((sum, n) => sum + n, 0);
518
+ }
519
+ /** "Brought in: a.wav (voice), b.wav (music)", the first few and then how many more. */
520
+ function broughtLine(added) {
521
+ const shown = added.slice(0, 6).map((a) => `${stripControl(a.path)} (${a.kind})`);
522
+ const more = added.length > 6 ? `, and ${added.length - 6} more` : "";
523
+ return `Brought in: ${shown.join(", ")}${more}`;
524
+ }
433
525
  function usage(io, line) {
434
526
  io.err(`Usage: ${line}`);
435
527
  return 2;
@@ -0,0 +1,333 @@
1
+ import { lstat, opendir, realpath } from "node:fs/promises";
2
+ import { setImmediate as yieldToLoop } from "node:timers/promises";
3
+ import { extname, join, sep } from "node:path";
4
+ import { toManifestPath } from "./paths.js";
5
+ export const DEFAULT_LIMITS = { maxDepth: 8, maxExamined: 5000, maxKept: 2000, budgetMs: 3000 };
6
+ /** §20.2: audio files the scan lists. */
7
+ export const AUDIO_EXT = new Set([".wav", ".mp3", ".m4a", ".aif", ".aiff", ".flac", ".ogg", ".opus"]);
8
+ /** §20.2: video files the scan lists, offered as cuts. */
9
+ export const VIDEO_EXT = new Set([".mp4", ".mov", ".m4v", ".webm"]);
10
+ /** Folders that are never walked: the project's own, and tool clutter. */
11
+ export const SKIPPED_FOLDERS = new Set(["node_modules", ".rushes", "proxies", "screenshots", "exports"]);
12
+ /** Let the event loop breathe this often, so a server using the scan stays responsive. */
13
+ const YIELD_EVERY = 200;
14
+ const VOICE_WORDS = new Set(["vo", "voice", "voiceover", "narration", "narrator", "vox", "speech", "dub", "read"]);
15
+ const MUSIC_WORDS = new Set(["bed", "music", "score", "track", "song", "theme"]);
16
+ const SFX_WORDS = new Set(["sfx", "fx", "foley", "whoosh", "hit", "riser", "impact"]);
17
+ const VERSION_WORD = /^v\d+[a-z]?$/;
18
+ function isInside(realRoot, real) {
19
+ return real === realRoot || real.startsWith(realRoot.endsWith(sep) ? realRoot : realRoot + sep);
20
+ }
21
+ /** Plain code-unit order, so the walk is the same on every machine and locale. */
22
+ function byName(a, b) {
23
+ return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
24
+ }
25
+ /**
26
+ * Reads at most `max` entries of a folder, so a folder with a hundred thousand
27
+ * entries is never loaded in one go. The order the file system gives them in is
28
+ * arbitrary, so the caller sorts what came back.
29
+ */
30
+ async function readSome(dir, max) {
31
+ const handle = await opendir(dir);
32
+ const out = [];
33
+ try {
34
+ while (out.length < max) {
35
+ const entry = await handle.read();
36
+ if (entry === null)
37
+ break;
38
+ out.push(entry);
39
+ }
40
+ }
41
+ finally {
42
+ await handle.close().catch(() => undefined);
43
+ }
44
+ return out;
45
+ }
46
+ /**
47
+ * Walks `root` within the limits, level by level, siblings in sorted order.
48
+ * Symlinks are skipped. Never reads contents. Stops (not complete) once
49
+ * `signal` aborts, checked before each folder is read. Rejects if `root` does not exist
50
+ * or cannot be resolved; anything unreadable below it is skipped quietly.
51
+ */
52
+ export async function scanFolder(root, opts = {}) {
53
+ const limits = { ...DEFAULT_LIMITS, ...opts.limits };
54
+ const now = opts.now ?? Date.now;
55
+ const skip = opts.skip;
56
+ const signal = opts.signal;
57
+ const started = now();
58
+ const realRoot = await realpath(root);
59
+ const files = [];
60
+ let examined = 0;
61
+ let complete = true;
62
+ let sinceYield = 0;
63
+ const overBudget = () => now() - started >= limits.budgetMs;
64
+ let level = [""];
65
+ let depth = 0;
66
+ walk: while (level.length > 0) {
67
+ const next = [];
68
+ for (const relDir of level) {
69
+ // Checked between folder reads: a closing server stops the walk here, not 5,000 entries later.
70
+ if (overBudget() || signal?.aborted) {
71
+ complete = false;
72
+ break walk;
73
+ }
74
+ const absDir = relDir === "" ? realRoot : join(realRoot, ...relDir.split("/"));
75
+ let entries;
76
+ try {
77
+ // A real folder can still resolve outside the root (a bind mount, say): check it.
78
+ if (relDir !== "" && !isInside(realRoot, await realpath(absDir)))
79
+ continue;
80
+ // One more than the examined limit still allows: enough to know there was more.
81
+ entries = await readSome(absDir, limits.maxExamined - examined + 1);
82
+ }
83
+ catch {
84
+ continue; // gone, or unreadable
85
+ }
86
+ entries.sort(byName);
87
+ for (const entry of entries) {
88
+ if (examined >= limits.maxExamined || overBudget()) {
89
+ complete = false;
90
+ break walk;
91
+ }
92
+ examined++;
93
+ if (++sinceYield >= YIELD_EVERY) {
94
+ sinceYield = 0;
95
+ await yieldToLoop();
96
+ }
97
+ const name = entry.name;
98
+ const rel = relDir === "" ? name : `${relDir}/${name}`;
99
+ // Some drives (network, FUSE) list names without types: then the file system is asked.
100
+ let isLink = entry.isSymbolicLink();
101
+ let isDir = entry.isDirectory();
102
+ let isPlain = entry.isFile();
103
+ if (!isLink && !isDir && !isPlain) {
104
+ try {
105
+ const info = await lstat(join(absDir, name));
106
+ isLink = info.isSymbolicLink();
107
+ isDir = info.isDirectory();
108
+ isPlain = info.isFile();
109
+ }
110
+ catch {
111
+ continue; // vanished mid-scan
112
+ }
113
+ }
114
+ if (isLink)
115
+ continue; // never followed, never listed
116
+ if (isDir) {
117
+ if (name.startsWith(".") || SKIPPED_FOLDERS.has(name.toLowerCase()))
118
+ continue;
119
+ if (skip?.(rel))
120
+ continue;
121
+ if (depth < limits.maxDepth)
122
+ next.push(rel);
123
+ continue;
124
+ }
125
+ if (!isPlain)
126
+ continue;
127
+ if (name.startsWith("."))
128
+ continue; // hidden files, such as macOS "._" companions
129
+ const ext = extname(name).toLowerCase();
130
+ const isAudio = AUDIO_EXT.has(ext);
131
+ if (!isAudio && !VIDEO_EXT.has(ext))
132
+ continue;
133
+ if (skip?.(rel))
134
+ continue;
135
+ let stat;
136
+ try {
137
+ stat = await lstat(join(absDir, name));
138
+ }
139
+ catch {
140
+ continue; // vanished mid-scan
141
+ }
142
+ if (!stat.isFile())
143
+ continue;
144
+ if (files.length >= limits.maxKept) {
145
+ complete = false;
146
+ break walk;
147
+ }
148
+ const abs = join(absDir, name);
149
+ files.push({
150
+ path: toManifestPath(realRoot, abs),
151
+ abs,
152
+ kind: isAudio ? kindOf(rel) : "cut",
153
+ folder: relDir,
154
+ size: stat.size,
155
+ modified: stat.mtimeMs,
156
+ duration: null,
157
+ });
158
+ }
159
+ }
160
+ level = next;
161
+ depth++;
162
+ }
163
+ return { files, complete, examined };
164
+ }
165
+ /**
166
+ * The words of a name: lower-cased, split on non-letters and camel case, with
167
+ * a version word such as "v20" or "v20J" kept whole. Digits are not words.
168
+ */
169
+ export function wordsOf(text) {
170
+ const words = [];
171
+ // NFKD, then drop the accents: "Thème" and "Theme", NFC or NFD, read alike.
172
+ const plain = text.normalize("NFKD").replace(/\p{M}/gu, "");
173
+ for (const chunk of plain.split(/[^\p{L}\p{N}]+/u)) {
174
+ if (chunk === "")
175
+ continue;
176
+ if (VERSION_WORD.test(chunk.toLowerCase())) {
177
+ words.push(chunk.toLowerCase());
178
+ continue;
179
+ }
180
+ for (const run of chunk.split(/[^\p{L}]+/u)) {
181
+ if (run === "")
182
+ continue;
183
+ const parts = run
184
+ .replace(/(\p{Ll})(\p{Lu})/gu, "$1 $2")
185
+ .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, "$1 $2")
186
+ .split(" ");
187
+ for (const part of parts)
188
+ if (part !== "")
189
+ words.push(part.toLowerCase());
190
+ }
191
+ }
192
+ return words;
193
+ }
194
+ function kindOfWord(word) {
195
+ if (VOICE_WORDS.has(word))
196
+ return "voice";
197
+ if (MUSIC_WORDS.has(word))
198
+ return "music";
199
+ if (SFX_WORDS.has(word))
200
+ return "sfx";
201
+ return null;
202
+ }
203
+ function withoutExtension(path) {
204
+ const ext = extname(path);
205
+ return ext === "" ? path : path.slice(0, -ext.length);
206
+ }
207
+ /**
208
+ * The kind a path suggests, from the nearest folder name or file-name word
209
+ * (§20.3). The file's own name is nearest, then its folder, then the folder
210
+ * above. Video files are cuts; an audio file with no match is "other".
211
+ */
212
+ export function kindOf(relPath) {
213
+ const normal = relPath.split("\\").join("/");
214
+ if (VIDEO_EXT.has(extname(normal).toLowerCase()))
215
+ return "cut";
216
+ const parts = withoutExtension(normal).split("/");
217
+ for (let i = parts.length - 1; i >= 0; i--) {
218
+ for (const word of wordsOf(parts[i])) {
219
+ const kind = kindOfWord(word);
220
+ if (kind)
221
+ return kind;
222
+ }
223
+ }
224
+ return "other";
225
+ }
226
+ const HOUR = 3600e3;
227
+ /** "12 min", "3 hours": the nearest minute, or the nearest hour once it is an hour or more. */
228
+ function spanText(ms) {
229
+ const minutes = Math.round(ms / 60e3);
230
+ if (minutes < 60)
231
+ return `${minutes} min`;
232
+ const hours = Math.round(minutes / 60);
233
+ return hours === 1 ? "1 hour" : `${hours} hours`;
234
+ }
235
+ function seconds(value) {
236
+ return `${value.toFixed(1)} s`;
237
+ }
238
+ /** §20.4's scoring table for one audio candidate. `commonWords` are the words most files share. */
239
+ export function scoreCandidate(file, anchor, commonWords) {
240
+ let score = 0;
241
+ const reasons = [];
242
+ // Length. Sound effects are short passes, so they get none.
243
+ const d = anchor.duration;
244
+ let lengthScored = false;
245
+ if (file.kind !== "sfx" && file.duration !== null && d !== null && d > 0) {
246
+ const off = Math.abs(file.duration - d) / d;
247
+ if (off <= 0.02) {
248
+ score += 3;
249
+ reasons.push(`same length as the cut (${seconds(file.duration)} vs ${seconds(d)})`);
250
+ lengthScored = true;
251
+ }
252
+ else if (off <= 0.1) {
253
+ score += 2;
254
+ reasons.push("close to the cut's length");
255
+ lengthScored = true;
256
+ }
257
+ else if (off <= 0.25) {
258
+ score += 1;
259
+ reasons.push("in the region of the cut's length");
260
+ lengthScored = true;
261
+ }
262
+ }
263
+ if (!lengthScored && file.duration !== null && file.duration < 15 && (file.kind === "voice" || file.kind === "other")) {
264
+ reasons.push(`a short line (${Math.round(file.duration)} s)`);
265
+ }
266
+ // Made around the same time as the cut.
267
+ const delta = file.modified - anchor.modified; // negative: made before the cut
268
+ if (delta >= -6 * HOUR && delta <= 1 * HOUR) {
269
+ score += 2;
270
+ reasons.push(timeReason(delta));
271
+ }
272
+ else if (delta >= -24 * HOUR && delta < -6 * HOUR) {
273
+ score += 1;
274
+ reasons.push(timeReason(delta));
275
+ }
276
+ // Name words the file and the cut share, ignoring words every file has.
277
+ const fileWords = new Set(wordsOf(withoutExtension(file.path)));
278
+ const shared = [];
279
+ for (const word of new Set(anchor.words)) {
280
+ if (word.length < 2 || VERSION_WORD.test(word) || commonWords.has(word))
281
+ continue;
282
+ if (fileWords.has(word))
283
+ shared.push(word);
284
+ }
285
+ if (shared.length > 0) {
286
+ const used = shared.slice(0, 2);
287
+ score += used.length;
288
+ reasons.push(`name shares ${used.map((w) => `“${w}”`).join(" and ")}`);
289
+ }
290
+ // The same version word.
291
+ // A version word every file carries tells the cuts nothing apart, so it weighs nothing.
292
+ const version = anchor.words.find((w) => VERSION_WORD.test(w) && fileWords.has(w) && !commonWords.has(w));
293
+ if (version) {
294
+ score += 2;
295
+ reasons.push(`same version (${version})`);
296
+ }
297
+ return { file, score, reasons };
298
+ }
299
+ function timeReason(delta) {
300
+ const abs = Math.abs(delta);
301
+ if (Math.round(abs / 60e3) === 0)
302
+ return "made at about the same time";
303
+ return `made ${spanText(abs)} ${delta < 0 ? "before" : "after"} it`;
304
+ }
305
+ /** The words that appear in more than half of `files`' paths: they say nothing about one cut. */
306
+ export function commonWordsOf(files) {
307
+ const counts = new Map();
308
+ for (const file of files) {
309
+ for (const word of new Set(wordsOf(withoutExtension(file.path))))
310
+ counts.set(word, (counts.get(word) ?? 0) + 1);
311
+ }
312
+ const common = new Set();
313
+ for (const [word, count] of counts)
314
+ if (count > files.length / 2)
315
+ common.add(word);
316
+ return common;
317
+ }
318
+ /** Per kind (voice, music, sfx), the top candidate only when score >= 4 and it beats the runner-up by >= 1. */
319
+ export function pickCurrentSet(scored) {
320
+ const picked = {};
321
+ for (const kind of ["voice", "music", "sfx"]) {
322
+ const ranked = scored
323
+ .filter((s) => s.file.kind === kind)
324
+ .sort((a, b) => b.score - a.score || (a.file.path < b.file.path ? -1 : a.file.path > b.file.path ? 1 : 0));
325
+ const [top, runnerUp] = ranked;
326
+ if (!top || top.score < 4)
327
+ continue;
328
+ if (runnerUp && top.score - runnerUp.score < 1)
329
+ continue;
330
+ picked[kind] = top;
331
+ }
332
+ return picked;
333
+ }
@@ -48,6 +48,8 @@ async function readProbe(file, timeout, signal) {
48
48
  try {
49
49
  const { stdout } = await run("ffprobe", [
50
50
  "-v", "error",
51
+ // Local files only: a playlist or container that names a URL is never followed.
52
+ "-protocol_whitelist", "file",
51
53
  "-show_entries", "format=duration:stream=codec_type,codec_name,width,height,pix_fmt,avg_frame_rate,r_frame_rate",
52
54
  "-of", "json",
53
55
  file,