storyboard-bridge 0.2.0

package/README.md

@@ -0,0 +1,82 @@
+# Storyboard AI — Desktop Bridge
+
+This tiny program lets a **hosted** Storyboard AI webapp run on **your own** Claude Code / Gemini CLI
+login. It runs on your computer, connects out to the app, and answers the app's AI requests by running
+your local CLI under your own subscription. **No API key.** Nothing listens for inbound connections —
+the bridge dials out, so it works behind home routers and firewalls with no setup.
+
+## Prerequisites (one-time)
+
+1. **Node.js 18+**
+2. A logged-in AI CLI — at least one of:
+   - **Claude Code** — install, then `claude` once and sign in.
+   - **Gemini CLI** — install, then `gemini` once and sign in.
+
+## Run
+
+```bash
+# easiest — always runs the latest published version
+npx storyboard-bridge --server https://your-app.example.com
+
+# or install once and run
+npm i -g storyboard-bridge
+storyboard-bridge --server https://your-app.example.com
+```
+
+Leave it running while you use the webapp. (It auto-reconnects if the connection drops.)
+
+### Options
+
+| Flag | Env | Default | Meaning |
+|------|-----|---------|---------|
+| `--server <url>` | `STORYBOARD_SERVER` | `http://localhost:8787` | The app's URL (https→wss is derived automatically). |
+| `--token <tok>` | `STORYBOARD_TOKEN` | _(none)_ | Pairs the bridge to **one** browser. Copy it from the app's **Connect desktop** panel. Omit to run a **shared** bridge that powers every session (handy when self-hosting just for yourself). |
+| `--provider <name>` | `LLM_PROVIDER` | `claude` | `claude` or `gemini` — which CLI to serve jobs with. |
+| `--model <name>` | `LLM_MODEL` | _CLI default_ | Optional model override passed to the CLI. |
+| `--files <dir>` | `STORYBOARD_FILES` | _(none)_ | A local folder to **store & serve your assets** (e.g. a OneDrive folder). With this set, your uploads + generated images/videos/audio live on **your** machine — the hosted app keeps only keys. Omit it and the app stores assets server-side. |
+| — | `CLAUDE_BIN` / `GEMINI_BIN` | on PATH | Path to the CLI binary if it isn't on your PATH. |
+
+### Local asset storage (keep your media on your own machine)
+
+Point `--files` at a folder — ideally a synced one like OneDrive — and the bridge becomes the file
+store for your assets. The hosted backend never holds the bytes: it asks your bridge to read/write
+them over the same connection. Use **your OS's native path**:
+
+```bash
+# Windows (PowerShell/cmd)
+npx storyboard-bridge --server https://your-app.example.com --token <tok> ^
+  --files "C:\Users\You\OneDrive\Storybuilder-ai"
+
+# WSL
+npx storyboard-bridge --server https://your-app.example.com --token <tok> \
+  --files "/mnt/c/Users/You/OneDrive/Storybuilder-ai"
+
+# macOS
+npx storyboard-bridge --server https://your-app.example.com --token <tok> \
+  --files "/Users/you/OneDrive/Storybuilder-ai"
+```
+
+Caveat: your assets are only viewable/generatable **while this bridge is running** — if your machine
+is off, the app can't reach your files. (The same is already true for the AI: jobs run on your CLI.)
+
+The easiest path: open the app, click **Connect desktop**, and copy the ready-made command (it already
+includes the right `--server` and `--token`).
+
+## Updating
+
+`npx storyboard-bridge` always fetches the latest version. If you installed globally, run
+`npm i -g storyboard-bridge` again. When you connect, the server tells the bridge the latest version and
+it prints a notice if yours is older — so new features land by simply updating this one small package.
+
+## How it works
+
+```
+  your desktop (this bridge + your logged-in CLI)        hosted Storyboard AI
+        │                                                       │
+        │── dials out, "hello" (version + which CLIs) ─────────▶│
+        │◀──────────── job: { id, prompt } ─────────────────────│   (you click generate)
+        run `claude -p` / `gemini -p` locally
+        │── result: { id, text } ──────────────────────────────▶│── shows up in the app
+```
+
+Your CLI login never leaves your machine; only prompts in and text out cross the wire.

package/index.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// ===== Storyboard AI — desktop bridge =====
+// Runs on YOUR machine, where your Claude Code / Gemini CLI is already logged in. It dials OUT to a
+// hosted Storyboard AI backend over a websocket and answers the backend's LLM jobs by running the CLI
+// locally, under your own subscription. No API key. Nothing inbound — the connection is opened from
+// here, so it works behind home routers/firewalls with no port-forwarding.
+//
+//   Usage:  npx storyboard-bridge --server https://your-app.example.com
+//           (or)  STORYBOARD_SERVER=https://your-app.example.com node index.mjs
+//
+// Flags / env:
+//   --server  <url>   STORYBOARD_SERVER   backend base URL (http/https; ws/wss derived). default http://localhost:8787
+//   --token   <tok>   STORYBOARD_TOKEN    pairing token shown in the webapp ("Connect desktop"). Omit to
+//                                         run as a SHARED bridge that powers every session (self-host).
+//   --provider <name> LLM_PROVIDER        claude | gemini. default claude
+//   --model   <name>  LLM_MODEL           optional model override passed to the CLI ('' = CLI default)
+//   --files   <dir>   STORYBOARD_FILES    local folder to store/serve this user's assets (e.g. a
+//                                         OneDrive folder). Enables local storage for a hosted backend.
+//                                         Native path for YOUR OS — Windows: C:\Users\you\OneDrive\…
+//                                         · WSL: /mnt/c/Users/you/OneDrive/… · macOS: /Users/you/OneDrive/…
+//   --                CLAUDE_BIN/GEMINI_BIN   path to the CLI binary if not on PATH
+import { spawn, execFile } from 'node:child_process';
+import { writeFile, readFile, unlink, stat, mkdir } from 'node:fs/promises';
+import { join, resolve, dirname, sep } from 'node:path';
+import { WebSocket } from 'ws';
+
+const VERSION = '0.2.0';
+
+// ---- config ----
+const arg = (name, fallback) => {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+};
+const SERVER = arg('server', process.env.STORYBOARD_SERVER || 'http://localhost:8787');
+const TOKEN = arg('token', process.env.STORYBOARD_TOKEN || ''); // '' = shared bridge (serves all sessions)
+const PROVIDER = arg('provider', process.env.LLM_PROVIDER || 'claude').toLowerCase();
+const MODEL = arg('model', process.env.LLM_MODEL || '');
+const BIN_FOR = { claude: process.env.CLAUDE_BIN || 'claude', gemini: process.env.GEMINI_BIN || 'gemini' };
+const BIN = BIN_FOR[PROVIDER] || BIN_FOR.claude;
+const FILES_ROOT = arg('files', process.env.STORYBOARD_FILES || ''); // '' = this bridge does no storage
+const IS_WIN = process.platform === 'win32';
+// claude supports `--output-format json` (wraps as {result}); gemini's CLI (<=0.1.x) does NOT — it
+// prints raw text, and passing the flag makes it dump --help. Newer gemini supports it (wraps as
+// {response}) — opt in with GEMINI_JSON=1. extractText() handles wrapped OR raw either way.
+const USE_JSON = PROVIDER === 'claude' || process.env.GEMINI_JSON === '1';
+const JOB_TIMEOUT_MS = 300_000;
+
+const log = (m) => console.log(`[bridge ${new Date().toISOString().slice(11, 19)}] ${m}`);
+
+function wsUrl(httpUrl) {
+  const u = new URL(httpUrl);
+  u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+  if (!u.pathname || u.pathname === '/') u.pathname = '/bridge';
+  if (TOKEN) u.searchParams.set('token', TOKEN); // pair to a specific webapp session
+  return u.toString();
+}
+
+// ---- the same CLI contract the backend uses: `<bin> -p <prompt> --output-format json [--model m]` ----
+function runCli(bin, args) {
+  return new Promise((resolve, reject) => {
+    // On Windows the CLI is usually a `.cmd` shim (claude.cmd) that spawn() can't launch without a
+    // shell; shell:true uses PATHEXT to resolve it. POSIX (Linux/WSL/macOS) spawns the binary directly.
+    const child = spawn(bin, args, { timeout: JOB_TIMEOUT_MS, shell: IS_WIN });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', reject);
+    child.on('close', (code) => (code === 0 ? resolve(out) : reject(new Error(`${bin} exited ${code}: ${err.slice(0, 300)}`))));
+    child.stdin.end();
+  });
+}
+// claude wraps the answer as { result }, gemini as { response }; read either, else raw stdout.
+function extractText(stdout) {
+  try {
+    const o = JSON.parse(stdout);
+    if (o && typeof o.result === 'string') return o.result;
+    if (o && typeof o.response === 'string') return o.response;
+  } catch {
+    /* not the JSON wrapper — raw text */
+  }
+  return stdout;
+}
+async function runJob(prompt) {
+  const args = ['-p', prompt];
+  if (USE_JSON) args.push('--output-format', 'json'); // claude wraps as JSON; gemini prints raw text
+  if (MODEL) args.push('--model', MODEL);
+  return extractText(await runCli(BIN, args));
+}
+
+// is a CLI installed / runnable? (best-effort; a logged-out CLI still answers --version)
+const cliAvailable = (bin) =>
+  new Promise((res) => execFile(bin, ['--version'], { timeout: 15000, shell: IS_WIN }, (e) => res(!e)));
+
+// ---- local asset store (file ops from a hosted backend) ----
+// Map a storage key (always '/'-separated, e.g. world__id/image/x.png) to an absolute path UNDER
+// FILES_ROOT, refusing anything that escapes it. path.resolve handles both '/' and '\' on every OS.
+function safePath(key) {
+  if (!FILES_ROOT) throw new Error('this bridge has no --files folder configured (pass --files <dir>)');
+  const root = resolve(FILES_ROOT);
+  const p = resolve(root, String(key));
+  if (p !== root && !p.startsWith(root + sep)) throw new Error('path escapes the files root');
+  return p;
+}
+async function handleFile(msg) {
+  const p = safePath(msg.key);
+  if (msg.op === 'write') {
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, Buffer.from(String(msg.data ?? ''), 'base64'));
+    return { ok: true };
+  }
+  if (msg.op === 'read') {
+    try { const buf = await readFile(p); return { ok: true, found: true, size: buf.length, data: buf.toString('base64') }; }
+    catch { return { ok: true, found: false }; }
+  }
+  if (msg.op === 'delete') {
+    try { await unlink(p); return { ok: true, found: true }; }
+    catch { return { ok: true, found: false }; }
+  }
+  if (msg.op === 'stat') {
+    try { const s = await stat(p); return { ok: true, found: true, size: s.size }; }
+    catch { return { ok: true, found: false }; }
+  }
+  throw new Error(`unknown file op: ${msg.op}`);
+}
+
+// ---- connection (reconnects forever with backoff) ----
+let backoff = 1000;
+function connect() {
+  const url = wsUrl(SERVER);
+  const ws = new WebSocket(url);
+
+  ws.on('open', async () => {
+    backoff = 1000;
+    const providers = {
+      claude: await cliAvailable(BIN_FOR.claude),
+      gemini: await cliAvailable(BIN_FOR.gemini),
+    };
+    ws.send(JSON.stringify({ type: 'hello', version: VERSION, provider: PROVIDER, providers, files: !!FILES_ROOT }));
+    log(`connected to ${url} — serving jobs with: ${PROVIDER} (${BIN})${FILES_ROOT ? `; files → ${FILES_ROOT}` : ''}`);
+    if (!providers[PROVIDER]) {
+      log(`WARNING: '${BIN}' was not found / not runnable. Install it and log in, or pass --provider/--*_BIN. Jobs will fail until then.`);
+    }
+  });
+
+  ws.on('message', async (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(data.toString());
+    } catch {
+      return;
+    }
+    if (msg.type === 'welcome') {
+      if (msg.latest && msg.latest !== VERSION) {
+        log(`UPDATE AVAILABLE: bridge v${msg.latest} (you have v${VERSION}). Update with:  npm i -g storyboard-bridge   (or just re-run via npx).`);
+      }
+    } else if (msg.type === 'job' && msg.id) {
+      const t0 = Date.now();
+      try {
+        const text = await runJob(String(msg.prompt ?? ''));
+        ws.send(JSON.stringify({ type: 'result', id: msg.id, text }));
+        log(`job ${msg.id} ✓ (${Date.now() - t0}ms)`);
+      } catch (e) {
+        ws.send(JSON.stringify({ type: 'error', id: msg.id, message: String(e?.message ?? e) }));
+        log(`job ${msg.id} ✗ ${e?.message ?? e}`);
+      }
+    } else if (msg.type === 'file' && msg.id) {
+      try {
+        const r = await handleFile(msg);
+        ws.send(JSON.stringify({ type: 'fileResult', id: msg.id, ...r }));
+      } catch (e) {
+        ws.send(JSON.stringify({ type: 'fileError', id: msg.id, message: String(e?.message ?? e) }));
+        log(`file ${msg.op} ${msg.id} ✗ ${e?.message ?? e}`);
+      }
+    }
+  });
+
+  ws.on('close', () => {
+    log(`disconnected — retrying in ${Math.round(backoff / 1000)}s`);
+    setTimeout(connect, backoff);
+    backoff = Math.min(backoff * 2, 30000);
+  });
+  ws.on('error', (e) => {
+    log(`socket error: ${e.message}`);
+    try {
+      ws.close();
+    } catch {
+      /* ignore */
+    }
+  });
+}
+
+log(`Storyboard bridge v${VERSION} → ${SERVER} (provider: ${PROVIDER}; ${TOKEN ? `paired to token ${TOKEN.slice(0, 6)}…` : 'SHARED — serves all sessions'}; storage: ${FILES_ROOT ? FILES_ROOT : 'off (no --files)'})`);
+connect();

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "storyboard-bridge",
+  "version": "0.2.0",
+  "description": "Desktop bridge that powers a hosted Storyboard AI webapp with your own local Claude Code / Gemini CLI login (no API key).",
+  "type": "module",
+  "bin": {
+    "storyboard-bridge": "index.mjs"
+  },
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}