plotcoder-board 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# PlotCoder
+
+A storylining app for screenwriters, live at [plotcoder.com](http://plotcoder.com).
+
+PlotCoder is a set of tools for building a storyline, covering the activities a writer does today in Final Draft. It is designed so that an **agent driven by a person** has every one of those tools: the person directs, the agent operates, and the board on screen is the person's window onto the same records. The first tool is the wall, a digital corkboard for breaking and rearranging plot before writing the script, because that is the part of the job Final Draft does worst. Pages come last. Once the tools exist, workflows get launched on top of them. The horizon, a long way off: a person makes a storyline they believe in, then the app helps them drive agents that build segments of the movie with video generation tools.
+
+The full statement of purpose, every decision, and every requirement lives in [REQUIREMENTS.md](REQUIREMENTS.md). Read it before changing anything. It is the source of truth; this file is the front door.
+
+## The method the tools serve
+
+1. State the **logline**: the central question, what the story is arguing.
+2. Mark the **beats**: the 8 to 15 major turns.
+3. Fill the space between them with **scene cards**. One card is one scene.
+4. **Read the wall**: find the act that sags, the setup with no payoff, the character who disappears.
+5. Only then **write pages**.
+
+Steps 1 to 4 are built. Step 4 reads the runs between beats and the setups and their payoffs, and asks ten kinds of question, including a sagging act, a setup with no payoff, a character who disappears, and two scenes doing the same job, in the Reminders modal and as a `read_wall` tool. The Story Map, a strip under the wall, draws the same reading along a page axis and jumps the wall to any card you click. A board has a cast: type "with Maya, Tom" on a card, and see the wall by person from the Cast lens. Step 5 is not started. See "What is built and what is left" in the requirements.
+
+## Run it
+
+```bash
+npm ci
+npm run dev
+```
+
+Opens on `http://localhost:5173`. The board lives in the browser's localStorage and, while the dev server runs, is mirrored to `.plotcoder/board.json` so an agent can read and write it.
+
+```bash
+npm test          # kernel, geometry, layout, project file, MCP server
+npm run test:e2e  # the doors into the kernel, in a real browser (Playwright)
+npm run build     # typecheck and bundle to dist/
+```
+
+The end-to-end suite starts its own dev server on port 5174 with its own board file, so it never touches your wall. It needs Chromium once: `npx playwright install chromium`.
+
+Pushes to `main` run both suites and deploy `dist/` to GitHub Pages. A failing test blocks the deploy.
+
+## Drive it from an agent
+
+Every board verb goes through one command kernel, `src/board/reducer.js`, and there are three doors into it:
+
+- **The wall.** Tap the words to type, drag the paper to move. Lasso to select, then Group. Drag a card's handle onto another card for an arrow. ⌘Z takes back any change, whichever door made it.
+- **`window.plotcoder`** on the page, for a console or a CDP session.
+- **The MCP server**, published to npm as `plotcoder-board`: `npx -y plotcoder-board@latest` is the server, `npx -y plotcoder-board@latest call <tool> '{json}'` one call from a shell, `npx -y plotcoder-board@latest serve` the hosted door on a port (a `Dockerfile` is here too). Inside the repo it is `scripts/plotcoder-mcp.mjs`, wired for Cursor in `.cursor/mcp.json` and for Claude Code in `.mcp.json` (run `npm ci` once first). A version tag (`v0.2.0`) publishes it, with `NPM_TOKEN` in the repo's secrets. Seventy-one tools: reading (`list_board`, `read_wall`, `read_pages`, `read_character`, `page_count`, `list_words`, `list_workflows`, `segment_brief`); the card, cast, place, group and arrow verbs, `set_logline`, `set_target`, `set_rank`, `set_plant`, `write_scene`, `organize`, `apply_template` with `list_structures`, `save_structure`, `remove_structure`; `undo` and `redo`; the project's `list_boards`, `open_board`, `new_board`, `rename_board`, `delete_board`, `set_premise`, `rename_project` and the reminders; Fountain and Final Draft both ways; the production half (`lock_numbers`, `unlock_numbers`, `start_revision`, `end_revision`); the project as a file both ways (`export_project`, `import_project`); and, through the account door, `list_projects`, `open_project`, `new_project`, `delete_project`, `empty_account`, `delete_account`, `add_picture`, `add_take`, `list_takes`, `list_files`, `remove_file`, `build_segment`. If the dev app is open, a tool call lands on the wall within a second; if not, it edits the board file and the wall catches up on the next load.
+- **The account door.** With `PLOTCODER_EMAIL` and `PLOTCODER_PASSWORD` in the agent's environment — the writer's own — and no dev app answering, the same server works the writer's project on the account directly, and every change lands live on every open wall. `PLOTCODER_PROJECT` picks a project by name or id. No account yet? `claim_account` makes one with the writer's email and a password they chose. The on-ramp — the doors, what to call first, the rules — is in the app behind *Are you an agent? Start here* and served at [plotcoder.com/llms.txt](https://plotcoder.com/llms.txt), both from `src/board/agents.js`.
+
+An agent should call the tools, never fake mouse drags. The skill in `.cursor/skills/plotcoder-board/SKILL.md` says how; `.claude/skills/plotcoder-board` is a symlink to the same file.
+
+## Blind runs, and the test account
+
+A **blind run** is a fresh agent given the on-ramp and a treatment and nothing
+else, asked to build a wall and to keep a log of everything that made the job
+harder than it should have been. The friction log is the product; the wall is
+just what produces it. Three rounds have been run and all 73 of their
+findings are fixed; the fourth ran through the account door and its twenty-three
+are fixed too. [`blind-runs/`](blind-runs/) holds the rules that keep a round honest,
+the table of rounds, and the next round's prompt with the test account filled in.
+
+A round works a **test account** — a throwaway marked on its writer row, and the
+only kind of account the wipe script will touch (R44). Mark it once, then empty
+it between rounds:
+
+```bash
+node scripts/wipe-test-account.mjs test@test.com --mark        # once, to make it wipeable
+node scripts/wipe-test-account.mjs test@test.com               # the plan; changes nothing
+node scripts/wipe-test-account.mjs test@test.com --empty --yes # projects go, account stays
+node scripts/wipe-test-account.mjs test@test.com --delete --yes # the account goes too
+node scripts/wipe-test-account.mjs test@test.com --unmark      # back to a writer's account
+```
+
+Needs `SUPABASE_SERVICE_ROLE_KEY` in the shell; it is not in the repo and must
+not be. Nothing changes without `--yes`, and the script refuses any address that
+is not marked, so a mistyped address cannot take a writer's work. A project
+merely *shared with* the test account belongs to whoever made it and survives.
+
+**Prefer `--empty` between rounds.** `--delete` means claiming the address
+again, which changes the credentials in the round's prompt and quietly turns the
+next round into a test of `claim_account` instead of the door it meant to test.
+
+## Layout of the repo
+
+| Path | What it is |
+| --- | --- |
+| `REQUIREMENTS.md` | Purpose, decisions, requirements, open questions, what is left. The source of truth. |
+| `src/board/reducer.js` | The kernel. Pure, DOM-free, runs in the browser and in Node. |
+| `src/board/store.ts` | Browser store: localStorage, the dev bridge, `window.plotcoder`. |
+| `src/App.tsx`, `src/NoteBoard.tsx`, `src/NoteCard.tsx` | The wall. |
+| `src/GeneralBar.tsx`, `src/Logline.tsx` | Screen chrome: the bottom-right bar and the logline strip. |
+| `src/viewport.ts`, `src/arrowGeometry.ts`, `src/organizeLayout.ts` | Pure helpers, tested. |
+| `scripts/plotcoder-mcp.mjs` | The MCP server's front door: starts `plotcoder-mcp-server.mjs`, or answers in words when `npm ci` has not been run. |
+| `scripts/plotcoder-mcp-server.mjs` | The MCP server. |
+| `vite.config.ts` | The dev bridge that mirrors the board to a file on localhost. Never ships. |
+| `.github/workflows/deploy.yml` | Test, build, deploy to Pages. |
+| `blind-runs/` | The blind-run practice: the rules, the rounds, and each round's prompt and treatment. |
+| `scripts/wipe-test-account.mjs` | Empty or remove a marked test account (R44). `wipe-plan.mjs` is the pure rail it decides by. |
+
+## Status
+
+Version 0.1.0. A project of boards; sign in with your email and a password from the PlotCoder mark and your projects follow you to every device, share one with another writer by email and write it together live, or stay signed out and work on this device as before. Pages sit beside the wall: a scene's text lives on its card, measures it, paginates to the industry's rules, prints, and goes out and comes in as Fountain or Final Draft. It installs as a progressive web app and opens offline; plotcoder.com serves over HTTPS. The wall, beats, card length, groups, arrows, pan and zoom, save and open, and the agent surface are in use.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "plotcoder-board",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "prebuild": "node scripts/write-agents-text.mjs",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "serve": "node scripts/plotcoder-http.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@supabase/supabase-js": "^2.116.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "ws": "^8.21.3",
+    "zod": "^4.6.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^22.20.2",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^4.3.4",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.2",
+    "vite": "^5.4.19",
+    "vite-plugin-pwa": "^1.3.0",
+    "vitest": "^3.2.7"
+  },
+  "description": "PlotCoder's MCP server: a storyline wall for screenwriters, driven by an agent. `npx plotcoder-board` is the server; `npx plotcoder-board call <tool>` makes one call from a shell.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plot-coder/plotcoder.github.io.git"
+  },
+  "homepage": "https://plotcoder.com/llms.txt",
+  "bin": {
+    "plotcoder-board": "scripts/plotcoder-mcp.mjs"
+  },
+  "files": [
+    "scripts/plotcoder-mcp.mjs",
+    "scripts/plotcoder-mcp-server.mjs",
+    "scripts/plotcoder-call.mjs",
+    "scripts/plotcoder-http.mjs",
+    "src/board/*.js",
+    "src/board/*.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/plotcoder-call.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// One tool call to the PlotCoder MCP server, from a shell — for an agent
+// without MCP support, or a person checking a tool by hand.
+//
+//   node scripts/plotcoder-call.mjs list_words
+//   node scripts/plotcoder-call.mjs create_note '{"headline":"Maya finds the letter","change":"She decides not to tell Tom."}'
+//   node scripts/plotcoder-call.mjs tools            # every tool, with its description
+//
+// Speaks JSON-RPC over stdio to scripts/plotcoder-mcp.mjs and prints the
+// reply's text. The same environment applies: PLOTCODER_ROOT for where the
+// files live, PLOTCODER_EMAIL and PLOTCODER_PASSWORD for the account door.
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SERVER = fileURLToPath(new URL("./plotcoder-mcp.mjs", import.meta.url));
+const [tool, rawArgs] = process.argv.slice(2);
+
+const USAGE = `usage: node scripts/plotcoder-call.mjs <tool> ['{json arguments}']
+       node scripts/plotcoder-call.mjs --batch < calls.jsonl   many calls on one server
+       node scripts/plotcoder-call.mjs tools        every tool, with its description
+       node scripts/plotcoder-call.mjs --help
+
+One call, one server: each run starts scripts/plotcoder-mcp.mjs, makes the call,
+and stops it. So undo, and the project new_project or open_project chose, do not
+carry from one call to the next — set PLOTCODER_PROJECT for the calls that need
+it, or run them as a batch: one call per line on stdin, as
+{"tool": "create_note", "arguments": {"headline": "…", "change": "…"}},
+all on one server, so undo and the opened project hold within the batch. Each
+reply is printed under a line naming its tool. An MCP session keeps one server
+for the whole conversation.
+
+The environment is the server's:
+  PLOTCODER_ROOT       the folder whose wall you mean (default: this one)
+  PLOTCODER_EMAIL      the writer's sign-in: the account door, no app needed
+  PLOTCODER_PASSWORD   a wrong password is refused by every tool, never worked around
+  PLOTCODER_PROJECT    which of the writer's projects, by name or id
+  PLOTCODER_SESSION=0  sign in on every call instead of keeping the sign-in in .plotcoder/
+  PLOTCODER_JSON=1     keep the JSON tail on replies (off on this door)
+  PLOTCODER_VERBOSE=1  show the server's own log lines`;
+
+const batch = tool === "--batch";
+if (!tool || tool === "--help" || tool === "-h" || tool === "help") {
+  console.error(USAGE);
+  process.exit(tool ? 0 : 2);
+}
+
+let args = {};
+if (rawArgs && !batch) {
+  try {
+    args = JSON.parse(rawArgs);
+  } catch (error) {
+    console.error(`arguments must be JSON: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(2);
+  }
+}
+
+// The server's own log lines ("ready", "account door") stay off the reply
+// unless PLOTCODER_VERBOSE=1 asks for them.
+// PLOTCODER_ONE_CALL tells the server it will not live past this call, so its
+// replies can say what does not carry to the next one.
+// The JSON tail is off on this door unless asked for: the text carries the ids.
+const child = spawn("node", [SERVER], {
+  stdio: ["pipe", "pipe", process.env.PLOTCODER_VERBOSE ? "inherit" : "ignore"],
+  env: { ...process.env, PLOTCODER_ONE_CALL: "1", PLOTCODER_JSON: process.env.PLOTCODER_JSON === "1" ? "1" : "0" },
+});
+let buffer = "";
+const pending = new Map();
+let nextId = 1;
+child.stdout.setEncoding("utf8");
+child.stdout.on("data", (chunk) => {
+  buffer += chunk;
+  let cut;
+  while ((cut = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, cut).trim();
+    buffer = buffer.slice(cut + 1);
+    if (!line) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const waiting = pending.get(message.id);
+    if (waiting) {
+      pending.delete(message.id);
+      waiting(message);
+    }
+  }
+});
+
+const send = (message) => child.stdin.write(`${JSON.stringify(message)}\n`);
+const request = (method, params) =>
+  new Promise((resolve, reject) => {
+    const id = nextId++;
+    const timer = setTimeout(() => reject(new Error(`timed out waiting for ${method}`)), 30_000);
+    pending.set(id, (message) => {
+      clearTimeout(timer);
+      if (message.error) reject(new Error(message.error.message));
+      else resolve(message.result);
+    });
+    send({ jsonrpc: "2.0", id, method, params });
+  });
+
+try {
+  await request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "plotcoder-call", version: "1.0.0" } });
+  send({ jsonrpc: "2.0", method: "notifications/initialized" });
+  if (tool === "tools") {
+    const { tools } = await request("tools/list", {});
+    for (const item of tools) console.log(`${item.name} — ${item.description}\n`);
+  } else if (batch) {
+    // One server for every line: undo and the opened project hold within the batch.
+    let input = "";
+    for await (const chunk of process.stdin) input += chunk;
+    const lines = input.split("\n").map((line) => line.trim()).filter(Boolean);
+    for (const line of lines) {
+      let call;
+      try {
+        call = JSON.parse(line);
+      } catch {
+        console.log(`--- (skipped: not JSON) ${line.slice(0, 80)}`);
+        process.exitCode = 1;
+        continue;
+      }
+      const name = call.tool ?? call.name;
+      console.log(`--- ${name}`);
+      const result = await request("tools/call", { name, arguments: call.arguments ?? call.args ?? {} });
+      for (const part of result.content ?? []) if (part.type === "text") console.log(part.text);
+      if (result.isError) process.exitCode = 1;
+    }
+  } else {
+    const result = await request("tools/call", { name: tool, arguments: args });
+    for (const part of result.content ?? []) if (part.type === "text") console.log(part.text);
+    if (result.isError) process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+} finally {
+  child.kill();
+}

package/scripts/plotcoder-http.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// The hosted door (R48): PlotCoder's MCP server over HTTP, for a writer's
+// agent with nothing installed. One server per request, made from the
+// writer's own sign-in on the request — Authorization: Basic base64(email:
+// password), or X-PlotCoder-Email and X-PlotCoder-Password — so two writers
+// never share a door, and the account wins as it does everywhere else. No
+// disk: the file door is off, and export_project answers with the file as
+// JSON. Stateless streamable HTTP: any MCP client that speaks it connects
+// with `--transport http` and the two headers.
+//
+//   PORT=8787 node scripts/plotcoder-http.mjs      (or: npx plotcoder-board serve)
+//
+// Deploy it anywhere Node runs (a Dockerfile is in the repo); put it behind
+// HTTPS, since the sign-in travels in the header.
+
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createPlotcoderServer } from "./plotcoder-mcp-server.mjs";
+
+const PORT = Number(process.env.PORT ?? 8787);
+const HOST = process.env.HOST ?? "0.0.0.0";
+const SCRATCH = path.join(os.tmpdir(), "plotcoder-hosted");
+
+const ABOUT = `PlotCoder's hosted MCP door.
+
+POST /mcp with the writer's sign-in on the request:
+  Authorization: Basic base64(email:password)
+  (or X-PlotCoder-Email and X-PlotCoder-Password)
+  X-PlotCoder-Project: a project name or id   (optional)
+
+For Claude Code, once:
+  claude mcp add plotcoder --transport http https://<this host>/mcp --header "Authorization: Basic <base64 of email:password>"
+
+The on-ramp: https://plotcoder.com/llms.txt
+`;
+
+/** The writer's sign-in from the request, or null. */
+export function credentialsFrom(headers) {
+  const auth = String(headers.authorization ?? "");
+  if (/^basic\s+/i.test(auth)) {
+    const decoded = Buffer.from(auth.replace(/^basic\s+/i, ""), "base64").toString("utf8");
+    const cut = decoded.indexOf(":");
+    if (cut > 0) return { email: decoded.slice(0, cut), password: decoded.slice(cut + 1) };
+  }
+  const email = headers["x-plotcoder-email"];
+  const password = headers["x-plotcoder-password"];
+  if (typeof email === "string" && typeof password === "string" && email && password) return { email, password };
+  return null;
+}
+
+/** The environment one request's server runs with: the writer's sign-in, no bridge, no disk. */
+export function envFor(headers, base = process.env) {
+  const creds = credentialsFrom(headers);
+  if (!creds) return null;
+  return {
+    PLOTCODER_HOSTED: "1",
+    PLOTCODER_NO_BRIDGE: "1",
+    PLOTCODER_ROOT: SCRATCH,
+    PLOTCODER_JSON: base.PLOTCODER_JSON ?? "1",
+    PLOTCODER_EMAIL: creds.email,
+    PLOTCODER_PASSWORD: creds.password,
+    PLOTCODER_PROJECT: typeof headers["x-plotcoder-project"] === "string" ? headers["x-plotcoder-project"] : "",
+    ...(base.VITE_SUPABASE_URL ? { VITE_SUPABASE_URL: base.VITE_SUPABASE_URL } : {}),
+    ...(base.VITE_SUPABASE_KEY ? { VITE_SUPABASE_KEY: base.VITE_SUPABASE_KEY } : {}),
+    ...(base.PLOTCODER_VIDEO_PROVIDER ? { PLOTCODER_VIDEO_PROVIDER: base.PLOTCODER_VIDEO_PROVIDER } : {}),
+  };
+}
+
+export function createHostedDoor(base = process.env) {
+  return http.createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname === "/" || url.pathname === "/health") {
+      res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+      res.end(ABOUT);
+      return;
+    }
+    if (url.pathname !== "/mcp") {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Not here. The door is POST /mcp.\n");
+      return;
+    }
+    const env = envFor(req.headers, base);
+    if (!env) {
+      res.writeHead(401, { "content-type": "text/plain; charset=utf-8", "www-authenticate": 'Basic realm="PlotCoder"' });
+      res.end("The hosted door needs the writer's sign-in on the request: Authorization: Basic base64(email:password), or X-PlotCoder-Email and X-PlotCoder-Password.\n");
+      return;
+    }
+    // One server per request, stateless: the sign-in is the session.
+    const { server } = createPlotcoderServer(env);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res);
+    } catch (error) {
+      if (!res.headersSent) {
+        res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+        res.end(`The door failed: ${error instanceof Error ? error.message : String(error)}\n`);
+      }
+    }
+  });
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+if (isMain || process.env.PLOTCODER_SERVE === "1") {
+  createHostedDoor().listen(PORT, HOST, () => {
+    process.stderr.write(`[plotcoder-http] the hosted door is open on http://${HOST}:${PORT}/mcp\n`);
+  });
+}