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.
@@ -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
+ }
@@ -33,6 +33,8 @@ export function mentionsLegacySource(text) {
33
33
  return LEGACY_SOURCES.some((source) => text.includes(source));
34
34
  }
35
35
  const DEFAULT_LAUNCH = { command: MCP_COMMAND, args: MCP_ARGS };
36
+ /** The harnesses setup knows, in the order it lists them. */
37
+ export const HARNESS_IDS = ["claude-code", "codex", "cursor", "claude-desktop", "gemini"];
36
38
  export function harnesses(home, platform, appData = join(home, "AppData", "Roaming")) {
37
39
  const desktopDir = platform === "darwin"
38
40
  ? join(home, "Library", "Application Support", "Claude")
@@ -47,9 +49,25 @@ export function harnesses(home, platform, appData = join(home, "AppData", "Roami
47
49
  { id: "gemini", name: "Gemini CLI", kind: "json", config: join(home, ".gemini", "settings.json"), marker: join(home, ".gemini"), bin: "gemini" },
48
50
  ];
49
51
  }
52
+ /**
53
+ * Does `args` launch the current Rushes package: `rushes`, or a pinned `rushes@x.y.z`, then `mcp`?
54
+ * Such an entry is a working registration however the user adjusted the rest of it (a full path to
55
+ * npx and an env PATH, which a GUI app such as Claude Desktop often needs under nvm). Setup leaves
56
+ * it alone, and doctor, which asks the mergers what would change, calls it registered.
57
+ */
58
+ export function launchesRushes(args) {
59
+ if (!Array.isArray(args))
60
+ return false;
61
+ const at = args.findIndex((a) => a === SOURCE || (typeof a === "string" && a.startsWith(`${SOURCE}@`)));
62
+ return at !== -1 && args[at + 1] === "mcp";
63
+ }
64
+ /** Rushes is already set up in a config in a form the mergers don't edit. Not a broken file: change it by hand. */
65
+ export class RegistrationFormError extends Error {
66
+ }
50
67
  /**
51
68
  * Add Rushes to a JSON config's "mcpServers" without touching anything else.
52
69
  * Throws if the existing file isn't a JSON object, so we never clobber it.
70
+ * An entry that already launches the current package is left as the user has it.
53
71
  */
54
72
  export function mergeJson(existing, launch = DEFAULT_LAUNCH) {
55
73
  const doc = existing && existing.trim() ? JSON.parse(existing) : {};
@@ -61,16 +79,56 @@ export function mergeJson(existing, launch = DEFAULT_LAUNCH) {
61
79
  const want = { command: launch.command, args: launch.args };
62
80
  if (JSON.stringify(servers.rushes) === JSON.stringify(want))
63
81
  return { text: existing ?? "", changed: false };
82
+ const have = servers.rushes;
83
+ if (typeof have === "object" && have !== null && launchesRushes(have.args))
84
+ return { text: existing ?? "", changed: false };
64
85
  doc.mcpServers = { ...servers, rushes: want };
65
86
  return { text: JSON.stringify(doc, null, 2) + "\n", changed: true };
66
87
  }
67
88
  const tomlBlock = (launch) => `[mcp_servers.rushes]\ncommand = ${JSON.stringify(launch.command)}\nargs = [${launch.args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
68
89
  const TOML_HEADER = /^\s*\[mcp_servers\.rushes\]\s*(#.*)?$/;
90
+ /**
91
+ * Is rushes already defined under mcp_servers in a way mergeToml doesn't edit: an inline entry
92
+ * (`rushes = { ... }` in [mcp_servers]), a quoted table name, or a dotted key at the top? Adding
93
+ * [mcp_servers.rushes] beside one of those defines it twice, and TOML refuses that.
94
+ */
95
+ function definedAnotherWay(lines) {
96
+ let section = "";
97
+ for (const raw of lines) {
98
+ const line = raw.replace(/#.*$/, "").trim();
99
+ const header = /^\[\[?\s*([^\]]+?)\s*\]\]?$/.exec(line);
100
+ if (header) {
101
+ section = header[1].replace(/\s+/g, "");
102
+ if (/^mcp_servers\.(["'])rushes\1(\.|$)/.test(section))
103
+ return true;
104
+ continue;
105
+ }
106
+ if (/^mcp_servers\.(["']?)rushes\1\s*[.=]/.test(line))
107
+ return true;
108
+ if (section === "mcp_servers" && /^(["']?)rushes\1\s*[.=]/.test(line))
109
+ return true;
110
+ }
111
+ return false;
112
+ }
113
+ /** The `args` list of a table body, or undefined when it can't be read (a comment inside it, single quotes). */
114
+ function tomlArgs(body) {
115
+ const m = /^[ \t]*args[ \t]*=[ \t]*(\[[\s\S]*?\])/m.exec(body);
116
+ if (!m)
117
+ return undefined;
118
+ try {
119
+ return JSON.parse(m[1].replace(/,(\s*\])$/, "$1"));
120
+ }
121
+ catch {
122
+ return undefined;
123
+ }
124
+ }
69
125
  /**
70
126
  * Add or replace the [mcp_servers.rushes] table in a Codex config.toml, leaving
71
127
  * everything else as written and keeping the file's line endings. This is line
72
128
  * surgery, not a TOML parser: it never makes a valid file invalid, and a file
73
129
  * that was already broken gets a backup (see setup.ts) and an appended table.
130
+ * A table that already launches the current package is left as the user has it,
131
+ * and an entry written in a form this can't edit throws RegistrationFormError.
74
132
  */
75
133
  export function mergeToml(existing, launch = DEFAULT_LAUNCH) {
76
134
  const text = existing ?? "";
@@ -79,6 +137,8 @@ export function mergeToml(existing, launch = DEFAULT_LAUNCH) {
79
137
  const lines = text.split(/\r?\n/);
80
138
  const start = lines.findIndex((l) => TOML_HEADER.test(l));
81
139
  if (start === -1) {
140
+ if (definedAnotherWay(lines))
141
+ throw new RegistrationFormError("rushes is already set up under mcp_servers in a form this can't edit (an inline, quoted or dotted entry); change it by hand");
82
142
  const body = text.replace(/(\r?\n)+$/, "");
83
143
  return { text: (body ? body + eol + eol : "") + block.join(eol) + eol, changed: true };
84
144
  }
@@ -88,6 +148,8 @@ export function mergeToml(existing, launch = DEFAULT_LAUNCH) {
88
148
  const current = lines.slice(start + 1, end).map((l) => l.trim()).filter(Boolean);
89
149
  if (current.join("\n") === block.slice(1).join("\n"))
90
150
  return { text, changed: false };
151
+ if (launchesRushes(tomlArgs(lines.slice(start + 1, end).join("\n"))))
152
+ return { text, changed: false };
91
153
  const next = [...lines.slice(0, start), ...block, "", ...lines.slice(end)].join(eol);
92
154
  return { text: next.replace(/(\r?\n){3,}/g, eol + eol), changed: true };
93
155
  }
package/package.json CHANGED
@@ -1,7 +1,27 @@
1
1
  {
2
2
  "name": "rushes",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "A local review desk for video made with AI agents: timecoded notes, script edits and audio picks your agent can read and act on.",
5
+ "keywords": [
6
+ "video",
7
+ "video-review",
8
+ "review",
9
+ "ai-agents",
10
+ "mcp",
11
+ "mcp-server",
12
+ "claude-code",
13
+ "codex",
14
+ "cursor",
15
+ "voiceover",
16
+ "music",
17
+ "sound-effects",
18
+ "notes",
19
+ "local-first"
20
+ ],
21
+ "homepage": "https://github.com/iamredmh/rushes#readme",
22
+ "bugs": {
23
+ "url": "https://github.com/iamredmh/rushes/issues"
24
+ },
5
25
  "type": "module",
6
26
  "license": "MIT",
7
27
  "author": "Red Morley Hewitt",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: rushes
3
- description: Review video work with the user in Rushes, a local review desk. Use when you've rendered a cut, written a VO script, recorded voice reads, music beds or SFX passes and the user should review them, or when the user says they left notes, pressed Send to agent, or pastes a Rushes batch prompt.
3
+ description: Plan and review video work with the user in Rushes, a local review desk. Use when the user wants to start a new film or video (plan it with them first, then build), when they want to bring a film they started in the chat into Rushes (rebuild the plan from the conversation), when you've rendered a cut, written a VO script, recorded voice reads, music beds or SFX passes and the user should review them, or when the user says they left notes, pressed Send to agent, or pastes a Rushes batch prompt.
4
4
  ---
5
5
 
6
6
  # Rushes
@@ -9,11 +9,51 @@ Rushes shows your work to the user stage by stage (script, picture, voiceover, m
9
9
 
10
10
  If the user pastes a prompt copied from a locked tab, act on it directly — it already names the project, the film and the tool to use.
11
11
 
12
+ ## Starting a film
13
+
14
+ When the user wants a new video ("start a new film", "make a launch video", "a new project in Rushes"), plan it with them in Rushes before you build anything. They approve each step, so nothing gets built that they haven't seen.
15
+
16
+ 1. **Create the project** unless one exists: `npx -y rushes new <folder> --no-browser`, then `rushes_open` with `project: "<folder>"`. It makes the folders and a `brief.md` to fill in. Always pass `--no-browser`: without it the command stays running as the server and never returns.
17
+ 2. **Interview, briefly.** Ask at most three questions, and only ones whose answer changes the film: length and formats, who it is for, tone. Give each a recommended answer with its trade-off ("30 seconds fits a feed; 60 leaves room for the demo"). Never send a list of ten.
18
+ 3. **Write `brief.md`.** Fill every section and leave `Status: draft`. Tell the user to open Planning › Brief in Rushes, change any row and press **Approve brief**. Rushes then sets `Status: approved` in the file itself. Never approve it yourself or change that line, and if they say it's approved in chat while the file still says `draft`, ask them to press Approve. When they press **Send to agent** on the Brief page, read `brief.md` again and keep their wording: your last version is shown as Current, so read the file before you rewrite it.
19
+ 4. **Script.** Add it with `rushes_set_script`. The user edits and approves each section in Planning › Script. Read `rushes_get_script` and wait until every section is `approved`.
20
+ 5. **Storyboard.** Write `storyboard.md` in the project root: a `# Storyboard: <film>` title, then one section per shot, in this shape:
21
+
22
+ ```markdown
23
+ ## Shot 02 · Drop a folder
24
+ Tag: ACTION
25
+ Length: 5
26
+ Still: storyboard/shot-02.png
27
+ Status: draft
28
+ Direction:
29
+
30
+ A folder of clips lands in the window from the right.
31
+ ```
32
+
33
+ `Length` is planned seconds (they become the cut's shot starts), `Still` is a project-relative picture (png, jpg, webp, gif or avif), best saved under `storyboard/`, and `Direction` is the user's line. Make a still for each shot if your tools can; the Storyboard page shows any still the file names, registered or not. The user reads and approves each shot in Planning › Storyboard, and Rushes sets `Status: approved` itself: never set or change a shot's status yourself. When they press **Send to agent** there, read `storyboard.md` again, keep their wording, and update the still if what happens has changed.
34
+ 6. **Build only when all three are approved** (`rushes_status` reports `build`: `ready`, and what it is `waitingOn`). If the user says "just build it", do. Build in whatever tool suits the film, and name each scene after its planned shot. Then register the cut with `rushes_add_version`: a film's first cut starts with the storyboard's shots by itself (each `start` the running total of the lengths before it), so call `rushes_set_shots` only when the real timings differ (a cut brought in with `rushes_scan` or `rushes_bring_in` does not: send its shots with `rushes_set_shots`). A film with no script has nothing to wait on there: the script is only waited on when the film has one. While the plan isn't all approved the reply carries `planWarning`: a nudge, not a refusal.
35
+
36
+ The brief and the storyboard are Markdown files the user reads and approves on their own pages under Planning.
37
+
38
+ ## Picking up a film that's underway
39
+
40
+ When the user asks to open or review a film they started in the chat, or the project already has files but no `brief.md`, don't make them start again. Rebuild the plan from what you have, then say what you did.
41
+
42
+ 1. **Open the project**, or create it where the work is: `npx -y rushes new <folder> --no-browser` (it never overwrites a `brief.md` and leaves every other file alone), then `rushes_open`.
43
+ 2. **Write `brief.md` from the conversation.** Fill each section from what the user actually said. Mark anything you had to infer with `(inferred)` so they can check it. Where the chat never touched a section, write `Not discussed yet.` rather than inventing something. Put ideas they floated but didn't settle, and anything you couldn't answer, under Open questions. Keep `Status: draft`, and never approve it yourself.
44
+ 3. **Register what you already made.** A script from the chat goes in with `rushes_set_script` (the user approves it in Planning › Script). Copy storyboard stills into a `storyboard/` folder in the project: copy them, never move them, so the originals stay where the user's other tools expect them. Write the shots into `storyboard.md` in the shot format above, each with `Status: draft` and a `Still:` line naming its copy (the Storyboard page shows any still the file names). Register other reference images with `rushes_add_file` (`kind: "image"`). Renders, voice reads and music beds go in as usual (`rushes_add_version`, `rushes_add_variant`). Run `rushes_scan` for audio and cuts in the folder; it doesn't look for images, so naming the stills in `storyboard.md` (or registering other images) is yours to do: you know where you saved them.
45
+ 4. **Say what you filled in:** what came from the user's words, what you inferred, what you registered, and what you looked for and couldn't find ("I found four of the six stills"). Ask them to read `brief.md` under Assets › Scripts & docs.
46
+ 5. **If the chat is one you can't see** (another session, another tool), say so and ask the user to paste it or point you to it. Don't reconstruct a brief from memory of a conversation you didn't have.
47
+
48
+ When a user starts briefing in the chat, offer to keep `brief.md` up to date as you go: run `rushes new` first, so the next session, or another tool, can pick it up.
49
+
50
+ ## Reviewing and fixing
51
+
12
52
  1. Register what you made:
13
53
  - `rushes_add_version` for a render. Give every cut a short `label` (48 characters at most) saying what changed, and put the detail in `note`. If the cut is likely to play badly in a browser, the reply carries `proxySuggested: true` and `proxyReason`; Picture offers the user a proxy. Prefer H.264 MP4 to avoid this;
14
54
  - `rushes_add_format` for each other shape of a cut (a 9:16, 1:1 or 4:5 of the same edit): register every shape you rendered, main one first, or pass `formats: [{ file }]` to `rushes_add_version`. Its `label` is only a ratio hint such as 2.39:1, never the cut's short label;
15
55
  - `rushes_set_script` for the VO script. It merges by `id`, so send only the sections you changed; sections you leave out are kept. `rushes_get_script` reads the whole script;
16
- - `rushes_add_variant` for each voice read, music bed or SFX pass. Voice reads carry `stage: "voice"` and a `round` (its name — reads in one round are compared side by side; a new direction gets a new round); say what the read is, or what changed, in `description`. Music and SFX carry `meta.description` for their lane card;
56
+ - `rushes_add_variant` for each voice read, music bed or SFX pass. Voice reads carry `stage: "voice"` and a `round` (its name — reads in one round are compared side by side; a new direction gets a new round); say what the read is, or what changed, in `description`. Music and SFX carry `meta.description` for their lane card, and SFX passes carry `cues` as `{name, t, file?}`: the same name each time a sound comes back, and `file` (an audio file) when you know which sample you placed;
17
57
  - `rushes_set_shots` for the storyboard's shots, once you have the first cut; send new timings when a later cut moves them.
18
58
  2. Call `rushes_open` and tell the user it's ready, with what it brought in and what it left (below). Each project's dashboard lives at its own address, `/p/<id>/`.
19
59
  3. When the user sends a batch, call `rushes_get_batch` and fix every note in it. A note carries the `shot` it falls in; on an audio stage, call `rushes_get_picks` first — on Mix it also returns `levels` (dB per lane), which you read, not set. Its `on` says what it's about: `"<lane>/<variant>"` for a bed, pass or voice read (on Voiceover the lane names the round), `"<lane>/<variant>:<cue>"` for an SFX cue, `"vo"` for the Mix VO lane, or `null` for the whole mix; older notes may carry a section id or `"<section>:<take>"`. On Music, Sound effects and Mix treat `marks` (e.g. "Fall", "Quieter 3 dB") as part of the note; Voiceover notes carry none — they're Whole (`Speaker`, `Pacing`, `Tone`, `Overall`) or Point (`Fix this`, `Keep this`) instead. A Picture note's `format` is null for every format, or a format id such as `"9x16"`: when it isn't null, fix only that format. Picks are set from the dashboard only — no tool or CLI command sets one.