@spinabot/brigade 1.0.1 → 1.1.0

package/scripts/convex-dev.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// scripts/convex-dev.mjs
+//
+// Brigade local Convex orchestrator — fully air-gapped, zero cloud touch.
+// Spawns the self-hosted convex-local-backend binary + serves the dashboard
+// on 127.0.0.1:6791. Same path OSS users will use; no Convex account needed.
+//
+//   npm run convex:dev
+//
+// Persists state under F:\Brigade\.convex-data\:
+//   identity.json                       — stable instance name + secret (do not commit)
+//   admin-key.txt                       — derived admin key, written each run
+//   convex_local_backend.sqlite3        — database file
+//   storage/                            — Convex File Storage objects
+//   logs/                               — backend stderr captures
+
+import { spawn } from "node:child_process";
+import { mkdirSync, existsSync, writeFileSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const BIN_DIR = join(ROOT, "bin");
+const DATA_DIR = join(ROOT, ".convex-data");
+const DASHBOARD_DIR = join(BIN_DIR, "dashboard");
+const BACKEND_BIN = join(BIN_DIR, process.platform === "win32" ? "convex-local-backend.exe" : "convex-local-backend");
+
+const BACKEND_HOST = "127.0.0.1";
+const BACKEND_PORT = 3210;
+const SITE_PROXY_PORT = 3211;
+const DASHBOARD_PORT = 6791;
+
+const INSTANCE_NAME = "brigade-local";
+
+// ---------------------------------------------------------------------------
+// 1. Sanity checks
+// ---------------------------------------------------------------------------
+if (!existsSync(BACKEND_BIN)) {
+  console.error(`✖ Backend binary not found: ${BACKEND_BIN}`);
+  console.error(`  Run \`node scripts/install-convex.mjs\` to download it.`);
+  process.exit(1);
+}
+if (!existsSync(DASHBOARD_DIR)) {
+  console.error(`✖ Dashboard not found: ${DASHBOARD_DIR}`);
+  console.error(`  Run \`node scripts/install-convex.mjs\` to download it.`);
+  process.exit(1);
+}
+
+mkdirSync(DATA_DIR, { recursive: true });
+mkdirSync(join(DATA_DIR, "storage"), { recursive: true });
+mkdirSync(join(DATA_DIR, "logs"), { recursive: true });
+
+// Preflight: a second `npm run convex:dev` should say so plainly, not die
+// with an unhandled EADDRINUSE stack trace from deep inside node:net.
+import { createServer as createNetServer } from "node:net";
+function portFree(port) {
+  return new Promise((resolve) => {
+    const probe = createNetServer();
+    probe.once("error", () => resolve(false));
+    probe.once("listening", () => probe.close(() => resolve(true)));
+    probe.listen(port, BACKEND_HOST);
+  });
+}
+for (const [port, what] of [[BACKEND_PORT, "backend"], [SITE_PROXY_PORT, "site proxy"], [DASHBOARD_PORT, "dashboard"]]) {
+  if (!(await portFree(port))) {
+    console.error(`✖ Port ${port} (${what}) is already in use.`);
+    console.error(`  Is another \`npm run convex:dev\` already running?`);
+    console.error(`  If so, its dashboard is at http://${BACKEND_HOST}:${DASHBOARD_PORT} — or stop it and re-run.`);
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Stable identity — generate once, persist forever
+// ---------------------------------------------------------------------------
+const IDENTITY_FILE = join(DATA_DIR, "identity.json");
+let identity;
+if (existsSync(IDENTITY_FILE)) {
+  identity = JSON.parse(readFileSync(IDENTITY_FILE, "utf8"));
+} else {
+  identity = {
+    instanceName: INSTANCE_NAME,
+    instanceSecret: randomBytes(32).toString("hex"),
+    createdAt: new Date().toISOString(),
+  };
+  writeFileSync(IDENTITY_FILE, JSON.stringify(identity, null, 2));
+  console.log(`✓ Generated stable instance identity at ${IDENTITY_FILE}`);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Derive admin key via `keygen admin-key`
+// ---------------------------------------------------------------------------
+import { execSync } from "node:child_process";
+const adminKey = execSync(
+  `"${BACKEND_BIN}" keygen admin-key --instance-name "${identity.instanceName}" --instance-secret "${identity.instanceSecret}"`,
+  { encoding: "utf8" }
+).trim();
+writeFileSync(join(DATA_DIR, "admin-key.txt"), adminKey);
+
+// ---------------------------------------------------------------------------
+// 4. Write .env.local for the Convex CLI + Brigade gateway
+// ---------------------------------------------------------------------------
+const envContent = [
+  `# Auto-generated by scripts/convex-dev.mjs — do not commit`,
+  `CONVEX_SELF_HOSTED_URL=http://${BACKEND_HOST}:${BACKEND_PORT}`,
+  `CONVEX_SELF_HOSTED_ADMIN_KEY=${adminKey}`,
+  `# Also expose plain CONVEX_URL for client code:`,
+  `CONVEX_URL=http://${BACKEND_HOST}:${BACKEND_PORT}`,
+  ``,
+].join("\n");
+writeFileSync(join(ROOT, ".env.local"), envContent);
+
+// ---------------------------------------------------------------------------
+// 5. Spawn the backend
+// ---------------------------------------------------------------------------
+const dbPath = join(DATA_DIR, "convex_local_backend.sqlite3");
+const storagePath = join(DATA_DIR, "storage");
+
+console.log(`\x1b[36m▌ Starting Convex local backend\x1b[0m`);
+console.log(`\x1b[36m▌   backend  → http://${BACKEND_HOST}:${BACKEND_PORT}\x1b[0m`);
+console.log(`\x1b[36m▌   site     → http://${BACKEND_HOST}:${SITE_PROXY_PORT}\x1b[0m`);
+console.log(`\x1b[36m▌   db       → ${dbPath}\x1b[0m`);
+console.log(`\x1b[36m▌   storage  → ${storagePath}\x1b[0m`);
+
+const backend = spawn(BACKEND_BIN, [
+  "--interface", BACKEND_HOST,
+  "--port", String(BACKEND_PORT),
+  "--site-proxy-port", String(SITE_PROXY_PORT),
+  "--instance-name", identity.instanceName,
+  "--instance-secret", identity.instanceSecret,
+  "--local-storage", storagePath,
+  "--do-not-require-ssl",
+  dbPath,
+], { stdio: ["ignore", "pipe", "pipe"] });
+
+backend.stdout.on("data", (b) => process.stdout.write(`\x1b[90m[backend]\x1b[0m ${b}`));
+backend.stderr.on("data", (b) => process.stderr.write(`\x1b[90m[backend]\x1b[0m ${b}`));
+backend.on("exit", (code) => {
+  console.error(`\x1b[31m[backend] exited with code ${code}\x1b[0m`);
+  shutdown(code ?? 1);
+});
+
+// ---------------------------------------------------------------------------
+// 5b. Push the current convex/ functions once the backend answers.
+//
+// The runbook always promised "boots the local backend + pushes convex/
+// functions" — but nothing ever pushed, so the deployed bundle silently
+// drifted from the code: every function added after the last manual push
+// failed at runtime with "Could not find public function 'auth:readAuthFile'"
+// while the gateway limped along half-broken. Pushing here (and via the
+// standalone `npm run convex:push`) keeps backend and code in lockstep; the
+// boot-time bundle-version gate in src/storage/boot.ts is the backstop.
+// ---------------------------------------------------------------------------
+async function pushFunctionsWhenReady() {
+  const deadline = Date.now() + 60_000;
+  let up = false;
+  while (Date.now() < deadline && !shuttingDown) {
+    try {
+      const res = await fetch(`http://${BACKEND_HOST}:${BACKEND_PORT}/version`);
+      if (res.ok) {
+        up = true;
+        break;
+      }
+    } catch {
+      /* backend still starting */
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  if (!up || shuttingDown) {
+    if (!shuttingDown) {
+      console.error(
+        `\x1b[31m▌ Backend didn't answer within 60s — skipped the function push. Run \`npm run convex:push\` once it's up.\x1b[0m`,
+      );
+    }
+    return;
+  }
+  console.log(`\x1b[36m▌ Pushing convex/ functions…\x1b[0m`);
+  const push = spawn(process.execPath, [join(ROOT, "scripts", "convex-push.mjs")], {
+    stdio: "inherit",
+  });
+  push.on("exit", (code) => {
+    if (code === 0) {
+      console.log(`\x1b[32m▌ Functions up to date.\x1b[0m`);
+    } else {
+      console.error(
+        `\x1b[31m▌ Function push failed (code ${code}) — run \`npm run convex:push\` manually.\x1b[0m`,
+      );
+    }
+  });
+}
+// NOTE: invoked at the BOTTOM of this file — it reads `shuttingDown`, which
+// is declared in section 7 below; calling it here would hit the TDZ.
+
+// ---------------------------------------------------------------------------
+// 6. Spawn the static dashboard server on 127.0.0.1:6791
+// ---------------------------------------------------------------------------
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".css":  "text/css; charset=utf-8",
+  ".js":   "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg":  "image/svg+xml",
+  ".png":  "image/png",
+  ".ico":  "image/x-icon",
+  ".webmanifest": "application/manifest+json",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+const dashboardServer = createServer(async (req, res) => {
+  try {
+    let urlPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
+    if (urlPath === "/") urlPath = "/index.html";
+
+    let filePath = join(DASHBOARD_DIR, urlPath);
+
+    // SPA fallback — if the requested path has no extension and doesn't exist,
+    // try $path.html, then fall back to index.html.
+    let st;
+    try { st = await stat(filePath); } catch {}
+    if (!st || st.isDirectory()) {
+      const candidates = [
+        filePath + ".html",
+        join(filePath, "index.html"),
+        join(DASHBOARD_DIR, "index.html"),
+      ];
+      for (const c of candidates) {
+        try {
+          const s = await stat(c);
+          if (s.isFile()) { filePath = c; st = s; break; }
+        } catch {}
+      }
+    }
+    if (!st || !st.isFile()) { res.writeHead(404); res.end("Not Found"); return; }
+
+    const ext = extname(filePath).toLowerCase();
+    const mime = MIME[ext] ?? "application/octet-stream";
+    res.writeHead(200, { "content-type": mime, "cache-control": "no-store" });
+    // Zero-click login. The dashboard's logged-in flag is in-memory React
+    // state — sessionStorage alone never logs it in. The supported hook is
+    // a postMessage handshake: on load the app broadcasts
+    // "dashboard-credentials-request" to window.parent and auto-logs-in if
+    // anything replies with {type:"dashboard-credentials", adminKey,
+    // deploymentUrl, deploymentName}. The page is top-level here, so
+    // window.parent === window and our injected listener can be that
+    // responder. Always answer — "Log Out" is meaningless for a localhost
+    // dashboard whose admin key lives in a file on the same machine, and
+    // any logged-out heuristic is unreliable anyway (the dashboard's own
+    // storage hook writes the same empty marker on first load that Log Out
+    // writes). Localhost-only listener; same trust domain as the key file.
+    if (ext === ".html") {
+      const creds =
+        `{type:"dashboard-credentials",adminKey:${JSON.stringify(adminKey)},` +
+        `deploymentUrl:${JSON.stringify(`http://${BACKEND_HOST}:${BACKEND_PORT}`)},` +
+        `deploymentName:${JSON.stringify(identity.instanceName)}}`;
+      const html = (await readFile(filePath, "utf8")).replace(
+        /<head>/i,
+        `<head><script>(function(){try{` +
+          `window.addEventListener("message",function(ev){` +
+          `if(ev&&ev.data&&ev.data.type==="dashboard-credentials-request"){` +
+          `window.postMessage(${creds},"*");}});` +
+          `}catch(e){}})();</script>`,
+      );
+      res.end(html);
+      return;
+    }
+    res.end(await readFile(filePath));
+  } catch (err) {
+    res.writeHead(500);
+    res.end(String(err));
+  }
+});
+
+dashboardServer.listen(DASHBOARD_PORT, BACKEND_HOST, () => {
+  const dashboardUrl = `http://${BACKEND_HOST}:${DASHBOARD_PORT}`;
+  console.log(`\x1b[36m▌   dashboard → ${dashboardUrl} (logs in automatically)\x1b[0m`);
+  console.log(`\x1b[90m▌   admin key in .convex-data/admin-key.txt if you ever need it manually\x1b[0m`);
+
+  // Convenience: open the dashboard in the default browser — it logs in by
+  // itself via the credential handshake injected above, so there's nothing
+  // to paste. Opt out (CI / headless / "stop opening tabs") with
+  // BRIGADE_NO_BROWSER=1.
+  if (process.env.BRIGADE_NO_BROWSER !== "1") {
+    try {
+      if (process.platform === "win32") {
+        // `start` needs the empty-title arg.
+        spawn("cmd", ["/c", "start", "", dashboardUrl], { stdio: "ignore", detached: true }).unref();
+      } else if (process.platform === "darwin") {
+        spawn("open", [dashboardUrl], { stdio: "ignore", detached: true }).unref();
+      } else {
+        spawn("xdg-open", [dashboardUrl], { stdio: "ignore", detached: true }).unref();
+      }
+    } catch {
+      /* best-effort — the printed URL above always works */
+    }
+  }
+  console.log(``);
+});
+
+// ---------------------------------------------------------------------------
+// 7. Graceful shutdown
+// ---------------------------------------------------------------------------
+let shuttingDown = false;
+function shutdown(code = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(`\n\x1b[36m▌ Stopping...\x1b[0m`);
+  try { dashboardServer.close(); } catch {}
+  try { backend.kill("SIGTERM"); } catch {}
+  setTimeout(() => process.exit(code), 500);
+}
+process.on("SIGINT",  () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));
+
+// Kick off the function push LAST — after `shuttingDown` above is
+// initialized (pushFunctionsWhenReady reads it; an earlier call site hit
+// the let-binding TDZ and crashed the whole orchestrator at startup).
+void pushFunctionsWhenReady();

package/scripts/convex-push.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// scripts/convex-push.mjs — deploy convex/ functions to the LOCAL backend.
+//
+//   npm run convex:push
+//
+// Reads the admin key minted by convex-dev.mjs and runs `convex deploy`
+// against the self-hosted backend (default http://127.0.0.1:3210). Idempotent
+// — run any time the functions or schema change. `npm run convex:dev` also
+// runs this automatically once the backend is up, so the deployed bundle can
+// no longer silently drift from the code (the exact production failure:
+// per-domain "Could not find public function 'auth:readAuthFile'" spam while
+// the gateway limps along half-broken).
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DATA_DIR = join(ROOT, ".convex-data");
+
+// Pre-clean: compiled .js/.js.map artifacts INSIDE convex/ make the bundler
+// fail with "Two output files share the same path" (it treats both the .ts
+// and the stray .js as entry points). Historically the convex CLI's own
+// deploy-time typecheck planted them (no convex/tsconfig.json → emitting
+// mode — fixed by the noEmit tsconfig now in that folder), so pushes broke
+// the NEXT push. Sweep them before every deploy as a belt-and-suspenders so
+// no future emitter can re-break deploys. `_generated/` is the CLI's own
+// output and is exempt.
+const convexDir = join(ROOT, "convex");
+let cleaned = 0;
+for (const name of readdirSync(convexDir)) {
+  if (name.endsWith(".js") || name.endsWith(".js.map")) {
+    rmSync(join(convexDir, name), { force: true });
+    cleaned += 1;
+  }
+}
+if (cleaned > 0) {
+  console.log(`▌ Removed ${cleaned} stray compiled artifact(s) from convex/ (deploy-breaking).`);
+}
+const keyFile = join(DATA_DIR, "admin-key.txt");
+const url = process.env.CONVEX_SELF_HOSTED_URL?.trim() || "http://127.0.0.1:3210";
+
+if (!existsSync(keyFile) && !process.env.CONVEX_SELF_HOSTED_ADMIN_KEY) {
+  console.error(
+    "✖ No admin key found (.convex-data/admin-key.txt). Start the backend once first: npm run convex:dev",
+  );
+  process.exit(1);
+}
+const adminKey =
+  process.env.CONVEX_SELF_HOSTED_ADMIN_KEY?.trim() || readFileSync(keyFile, "utf8").trim();
+
+console.log(`▌ Pushing convex/ functions → ${url}`);
+const res = spawnSync("npx", ["convex", "deploy", "--yes"], {
+  cwd: ROOT,
+  stdio: "inherit",
+  shell: true, // resolves npx.cmd on Windows
+  env: {
+    ...process.env,
+    CONVEX_SELF_HOSTED_URL: url,
+    CONVEX_SELF_HOSTED_ADMIN_KEY: adminKey,
+  },
+});
+if (res.status === 0) {
+  console.log("✓ Convex functions are up to date.");
+} else {
+  console.error(`✖ convex deploy exited with code ${res.status ?? "unknown"}.`);
+}
+process.exit(res.status ?? 1);

package/scripts/install-convex.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// scripts/install-convex.mjs
+//
+// Auto-download the self-hosted Convex backend + dashboard binaries into
+// F:\Brigade\bin\ (or wherever the repo lives). Zero Convex Cloud account
+// needed. Runs as `npm run convex:install` and also fires on first run of
+// `npm run convex:dev` if binaries are missing.
+//
+// What it downloads:
+//   convex-local-backend-<platform>.zip   (~46 MB)
+//   dashboard.zip                          (~3 MB)
+//   LICENSE.md
+//
+// Source: github.com/get-convex/convex-backend releases.
+// License (verified): FSL-1.1-Apache-2.0 — Permitted Purpose for Brigade.
+
+import { existsSync, mkdirSync, createWriteStream, readFileSync } from "node:fs";
+import { writeFile, unlink, mkdir } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const BIN_DIR = join(ROOT, "bin");
+const BACKEND_BIN = join(BIN_DIR, process.platform === "win32" ? "convex-local-backend.exe" : "convex-local-backend");
+const DASHBOARD_DIR = join(BIN_DIR, "dashboard");
+
+// ---------------------------------------------------------------------------
+// Pin to a known-good release. Update this when a new Convex backend is needed.
+// Find latest tags at:
+//   https://github.com/get-convex/convex-backend/releases
+// ---------------------------------------------------------------------------
+const RELEASE_TAG = "precompiled-2026-06-03-7eff2e7";
+const RELEASE_BASE = `https://github.com/get-convex/convex-backend/releases/download/${RELEASE_TAG}`;
+
+function platformAsset() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === "win32"  && a === "x64")   return "convex-local-backend-x86_64-pc-windows-msvc.zip";
+  if (p === "darwin" && a === "arm64") return "convex-local-backend-aarch64-apple-darwin.zip";
+  if (p === "darwin" && a === "x64")   return "convex-local-backend-x86_64-apple-darwin.zip";
+  if (p === "linux"  && a === "x64")   return "convex-local-backend-x86_64-unknown-linux-gnu.zip";
+  if (p === "linux"  && a === "arm64") return "convex-local-backend-aarch64-unknown-linux-gnu.zip";
+  throw new Error(`Unsupported platform ${p}/${a}. Brigade ships Convex backend binaries for: win-x64, mac-x64, mac-arm64, linux-x64, linux-arm64.`);
+}
+
+async function download(url, destPath) {
+  console.log(`  → ${url}`);
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}
+
+async function unzip(zipPath, destDir) {
+  // Cross-platform unzip via PowerShell on Windows, `unzip` elsewhere.
+  await mkdir(destDir, { recursive: true });
+  if (process.platform === "win32") {
+    await runCmd("powershell", [
+      "-NoProfile", "-Command",
+      `Expand-Archive -Force -LiteralPath '${zipPath}' -DestinationPath '${destDir}'`,
+    ]);
+  } else {
+    await runCmd("unzip", ["-o", zipPath, "-d", destDir]);
+  }
+}
+
+function runCmd(cmd, args) {
+  return new Promise((resolveProm, rejectProm) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "inherit", "inherit"] });
+    child.on("exit", (code) => code === 0 ? resolveProm() : rejectProm(new Error(`${cmd} exited ${code}`)));
+    child.on("error", rejectProm);
+  });
+}
+
+async function main() {
+  mkdirSync(BIN_DIR, { recursive: true });
+  const asset = platformAsset();
+  const backendZip = join(BIN_DIR, "_backend.zip");
+  const dashboardZip = join(BIN_DIR, "_dashboard.zip");
+  const licensePath = join(BIN_DIR, "LICENSE.md");
+
+  const haveBackend = existsSync(BACKEND_BIN);
+  const haveDashboard = existsSync(DASHBOARD_DIR) && existsSync(join(DASHBOARD_DIR, "index.html"));
+  const haveLicense = existsSync(licensePath);
+
+  if (haveBackend && haveDashboard && haveLicense) {
+    console.log(`✓ Convex binaries already present in ${BIN_DIR}`);
+    return;
+  }
+
+  console.log(`Installing Convex local backend + dashboard for ${process.platform}/${process.arch}`);
+  console.log(`  Release: ${RELEASE_TAG}`);
+  console.log(`  Bin dir: ${BIN_DIR}`);
+  console.log();
+
+  if (!haveBackend) {
+    await download(`${RELEASE_BASE}/${asset}`, backendZip);
+    await unzip(backendZip, BIN_DIR);
+    await unlink(backendZip).catch(() => {});
+  }
+
+  if (!haveDashboard) {
+    await download(`${RELEASE_BASE}/dashboard.zip`, dashboardZip);
+    await unzip(dashboardZip, DASHBOARD_DIR);
+    await unlink(dashboardZip).catch(() => {});
+  }
+
+  if (!haveLicense) {
+    await download(`${RELEASE_BASE}/LICENSE.md`, licensePath);
+  }
+
+  console.log();
+  console.log(`✓ Installed Convex backend + dashboard.`);
+  console.log(`  License: FSL-1.1-Apache-2.0 (see bin/LICENSE.md)`);
+  console.log(`  Next:   npm run convex:dev`);
+}
+
+main().catch((err) => {
+  console.error(`✖ ${err.message}`);
+  process.exit(1);
+});