@maintainer-pro/ai-bridge 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# `@maintainer-pro/ai-bridge`
+
+Local bridge daemon that pairs a **developer machine** to a Maintainer Pro **partner**, then configures many client sandboxes from folders you choose in admin.
+
+## Flow
+
+1. In admin → **Bridges**, generate a pair code
+2. On the machine (any folder):
+
+```bash
+npx --yes @maintainer-pro/ai-bridge --pair AB12-CD34 --admin-url https://your-admin
+```
+
+Credentials are stored in `~/.maintainer-pro/bridge.json` (not the cwd).
+
+3. Keep the bridge running (`npx @maintainer-pro/ai-bridge`). It advertises the current folder (and any `--offer-folder` paths).
+4. In admin → Bridges: pick a reported folder + client sandbox → **Setup sandbox in folder**. The bridge writes `.env`, starts `ai-server` on an assigned port, and marks the sandbox setup complete.
+
+One bridge process can run many sandboxes (different folders / ports) for different clients.
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--pair <code>` | Claim a pair code (first run) |
+| `--admin-url <url>` | Admin base URL (required when pairing) |
+| `--offer-folder <path>` | Advertise an extra folder in admin |
+| `--no-ai-server` | Do not start sidecars |
+
+## Auth
+
+After pairing, the daemon uses a long-lived `mp_bridge_…` machine token (not a per-sandbox API key). Sandbox server/client keys are written into each workspace `.env` during setup.

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ *   npx --yes @maintainer-pro/ai-bridge
+ */
+import "../src/daemon.mjs";

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@maintainer-pro/ai-bridge",
+  "version": "0.1.0",
+  "description": "Local bridge daemon that pairs a machine to Maintainer Pro and configures multiple client sandboxes.",
+  "keywords": [
+    "maintainer-pro",
+    "bridge",
+    "ai-bridge",
+    "sandbox",
+    "npx",
+    "daemon"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ai-bridge": "bin/cli.js",
+    "maintainer-pro-ai-bridge": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/daemon.mjs

@@ -0,0 +1,664 @@
+#!/usr/bin/env node
+/**
+ * Maintainer Pro bridge — partner machine daemon.
+ *
+ * Pair once with a code from admin, then manage many sandboxes/folders:
+ *   npx @maintainer-pro/ai-bridge --pair ABCD-EF01
+ *   npx @maintainer-pro/ai-bridge
+ *   npx @maintainer-pro/ai-bridge --admin-url https://… --pair ABCD-EF01
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_VERSION = readPackageVersion();
+const HEARTBEAT_MS = 15_000;
+
+const log = (msg) => console.log(`[bridge] ${msg}`);
+const warn = (msg) => console.warn(`[bridge] ${msg}`);
+const fail = (msg) => {
+  console.error(`[bridge] ${msg}`);
+  process.exit(1);
+};
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")
+    );
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function parseArgs(argv) {
+  /** @type {Record<string, string | boolean>} */
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      out.help = true;
+      continue;
+    }
+    if (arg === "--no-ai-server") {
+      out.noAiServer = true;
+      continue;
+    }
+    if (arg === "--pair" && i + 1 < argv.length) {
+      out.pair = argv[++i];
+      continue;
+    }
+    if (
+      arg.startsWith("--") &&
+      i + 1 < argv.length &&
+      !argv[i + 1].startsWith("--")
+    ) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      out[key] = argv[++i];
+      continue;
+    }
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log(`Maintainer Pro bridge (multi-sandbox)
+
+Pair this machine to your partner account, then configure folders for any
+client sandbox from the Maintainer Pro admin UI.
+
+Usage:
+  npx @maintainer-pro/ai-bridge --pair ABCD-EF01 --admin-url https://admin.example.com
+  npx @maintainer-pro/ai-bridge
+  npx @maintainer-pro/ai-bridge --offer-folder D:\\apps\\client-a
+
+Config is stored in ~/.maintainer-pro/bridge.json (not the cwd).
+
+Flags:
+  --pair <code>           Claim a pair code from admin → Bridges page
+  --admin-url <url>       Maintainer Pro base URL (required for first pair)
+  --offer-folder <path>   Suggest this folder in admin (repeatable via config)
+  --no-ai-server          Do not start sidecars for workspaces
+  --help
+`);
+}
+
+function configDir() {
+  return path.join(os.homedir(), ".maintainer-pro");
+}
+
+function configPath() {
+  return path.join(configDir(), "bridge.json");
+}
+
+function loadConfig() {
+  const file = configPath();
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveConfig(cfg) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+function ensureMachineId(cfg) {
+  if (cfg.machineId && String(cfg.machineId).length >= 8) return cfg.machineId;
+  const machineId = `mpm_${randomBytes(16).toString("hex")}`;
+  cfg.machineId = machineId;
+  return machineId;
+}
+
+async function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function api(baseUrl, token, method, pathname, body) {
+  const url = `${baseUrl.replace(/\/$/, "")}${pathname}`;
+  const headers = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { raw: text };
+  }
+  if (!res.ok) {
+    throw new Error(
+      data?.error || `Bridge API ${method} ${pathname} failed (${res.status})`
+    );
+  }
+  return data;
+}
+
+function commandExists(cmd) {
+  try {
+    if (process.platform === "win32") {
+      execFileSync("where", [cmd], { stdio: "ignore" });
+    } else {
+      execFileSync("which", [cmd], { stdio: "ignore" });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function detectCliProviders() {
+  /** @type {string[]} */
+  const found = [];
+  if (commandExists("agent")) found.push("agent");
+  if (commandExists("claude")) found.push("claude");
+  if (commandExists("agy")) found.push("agy");
+  return found;
+}
+
+function probeUrl(url, timeoutMs = 2500) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    try {
+      const req = http.get(url, { timeout: timeoutMs }, (res) => {
+        res.resume();
+        done(Boolean(res.statusCode && res.statusCode < 500));
+      });
+      req.on("error", () => done(false));
+      req.on("timeout", () => {
+        req.destroy();
+        done(false);
+      });
+    } catch {
+      done(false);
+    }
+  });
+}
+
+function listDirEntries(dirPath) {
+  const resolved = path.resolve(dirPath);
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    return { error: "Not a directory", path: resolved, entries: [] };
+  }
+  const names = fs.readdirSync(resolved);
+  const entries = [];
+  for (const name of names) {
+    if (name === "node_modules" || name === ".git") continue;
+    const full = path.join(resolved, name);
+    try {
+      const st = fs.statSync(full);
+      entries.push({
+        name,
+        path: full,
+        isDir: st.isDirectory(),
+      });
+    } catch {
+      /* skip */
+    }
+  }
+  entries.sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { path: resolved, entries: entries.slice(0, 200) };
+}
+
+function mergeEnvFile(file, values) {
+  /** @type {Record<string, string>} */
+  const map = {};
+  if (fs.existsSync(file)) {
+    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) continue;
+      const eq = line.indexOf("=");
+      if (eq < 1) continue;
+      map[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+  }
+  for (const [k, v] of Object.entries(values)) {
+    map[k] = String(v);
+  }
+  const body = Object.entries(map)
+    .map(([k, v]) => `${k}=${v}`)
+    .join("\n");
+  fs.writeFileSync(file, body + "\n", "utf8");
+}
+
+function collectOfferedFolders(cfg) {
+  /** @type {string[]} */
+  const folders = [];
+  const add = (p) => {
+    if (!p) return;
+    const resolved = path.resolve(p);
+    if (!folders.includes(resolved)) folders.push(resolved);
+  };
+  add(process.cwd());
+  for (const f of cfg.offeredFolders || []) add(f);
+  for (const w of cfg.workspaces || []) add(w.folderPath);
+  return folders;
+}
+
+/** @type {Map<string, import('node:child_process').ChildProcess>} */
+const children = new Map();
+
+function stopChild(sandboxId) {
+  const child = children.get(sandboxId);
+  if (!child || child.killed) {
+    children.delete(sandboxId);
+    return;
+  }
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    /* ignore */
+  }
+  children.delete(sandboxId);
+}
+
+function startAiServerForWorkspace(ws) {
+  const key = ws.sandboxId;
+  if (children.has(key) && !children.get(key)?.killed) return;
+
+  const localCli = path.resolve(
+    __dirname,
+    "..",
+    "..",
+    "ai-server",
+    "bin",
+    "cli.js"
+  );
+  const useLocal = fs.existsSync(localCli);
+  const env = {
+    ...process.env,
+    PORT: String(ws.port),
+    AI_SERVER_URL: `http://localhost:${ws.port}`,
+    NEXT_PUBLIC_AI_SERVER_URL: `http://localhost:${ws.port}`,
+  };
+
+  log(`starting ai-server for ${ws.sandboxName || ws.sandboxId} on :${ws.port}`);
+  const child = spawn(
+    useLocal
+      ? process.execPath
+      : process.platform === "win32"
+        ? "npx.cmd"
+        : "npx",
+    useLocal ? [localCli] : ["--yes", "@maintainer-pro/ai-server"],
+    {
+      cwd: ws.folderPath,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: process.platform === "win32" && !useLocal,
+    }
+  );
+  const tag = ws.sandboxName || ws.sandboxId.slice(0, 8);
+  child.stdout?.on("data", (buf) => {
+    const line = String(buf).trimEnd();
+    if (line) console.log(`[ai-server:${tag}] ${line}`);
+  });
+  child.stderr?.on("data", (buf) => {
+    const line = String(buf).trimEnd();
+    if (line) console.error(`[ai-server:${tag}] ${line}`);
+  });
+  child.on("exit", (code, signal) => {
+    log(`ai-server ${tag} exited (code=${code}, signal=${signal})`);
+    children.delete(key);
+  });
+  children.set(key, child);
+}
+
+async function setupWorkspace(cfg, action) {
+  const folderPath = String(action.payload?.folderPath || "");
+  const sandboxId = String(
+    action.sandboxId || action.payload?.sandboxId || ""
+  );
+  const port = Number(action.payload?.port) || 3100;
+  if (!folderPath || !sandboxId) {
+    throw new Error("setup_workspace requires folderPath and sandboxId");
+  }
+  const resolved = path.resolve(folderPath);
+  fs.mkdirSync(resolved, { recursive: true });
+
+  const config = await api(
+    cfg.adminUrl,
+    cfg.token,
+    "GET",
+    `/api/v1/bridge/machine/sandboxes/${sandboxId}/setup-config?port=${port}`
+  );
+
+  const envPath = path.join(resolved, ".env");
+  const envValues = {
+    ...config.env,
+    AI_CLI_WORKSPACE: ".",
+    AI_SERVER_UI: ".",
+    CORS_ORIGIN: process.env.CORS_ORIGIN || `http://localhost:${port}`,
+    APP_URL: process.env.APP_URL || `http://localhost:3000`,
+  };
+  mergeEnvFile(envPath, envValues);
+
+  cfg.workspaces = cfg.workspaces || [];
+  const existing = cfg.workspaces.findIndex((w) => w.sandboxId === sandboxId);
+  const entry = {
+    sandboxId,
+    folderPath: resolved,
+    port,
+    sandboxName: config.sandbox?.name,
+    applicationName: config.sandbox?.applicationName,
+  };
+  if (existing >= 0) cfg.workspaces[existing] = entry;
+  else cfg.workspaces.push(entry);
+  if (!cfg.offeredFolders) cfg.offeredFolders = [];
+  if (!cfg.offeredFolders.includes(resolved)) cfg.offeredFolders.push(resolved);
+  saveConfig(cfg);
+
+  if (!cfg.noAiServer) {
+    startAiServerForWorkspace(entry);
+    await new Promise((r) => setTimeout(r, 1200));
+  }
+
+  return {
+    sandboxId,
+    folderPath: resolved,
+    port,
+    appUrl: envValues.APP_URL || null,
+    origins: envValues.CORS_ORIGIN ? [envValues.CORS_ORIGIN] : [],
+    wroteEnv: true,
+  };
+}
+
+async function runActions(cfg, actions) {
+  for (const action of actions) {
+    log(`action ${action.code} (${action.id})`);
+    let ok = true;
+    /** @type {Record<string, unknown>} */
+    let result = {};
+    try {
+      if (action.code === "browse") {
+        const p = String(action.payload?.path || process.cwd());
+        result = listDirEntries(p);
+      } else if (action.code === "setup_workspace") {
+        result = await setupWorkspace(cfg, action);
+      } else if (action.code === "recheck") {
+        result = { recheckedAt: new Date().toISOString() };
+      } else if (action.code === "start_ai_server") {
+        const sandboxId = action.sandboxId || action.payload?.sandboxId;
+        const ws =
+          (cfg.workspaces || []).find((w) => w.sandboxId === sandboxId) ||
+          (action.payload?.folderPath
+            ? {
+                sandboxId,
+                folderPath: String(action.payload.folderPath),
+                port: Number(action.payload.port) || 3100,
+              }
+            : null);
+        if (!ws || cfg.noAiServer) {
+          ok = false;
+          result = { error: "No workspace or --no-ai-server" };
+        } else {
+          startAiServerForWorkspace(ws);
+          await new Promise((r) => setTimeout(r, 1200));
+          result = {
+            up: await probeUrl(
+              `http://127.0.0.1:${ws.port}/embed-config.js`
+            ),
+          };
+        }
+      } else if (action.code === "refresh_public_url") {
+        result = {
+          appUrl: process.env.APP_URL || process.env.PUBLIC_URL || null,
+        };
+      } else if (action.code === "remove_workspace") {
+        const sandboxId = String(
+          action.sandboxId || action.payload?.sandboxId || ""
+        );
+        stopChild(sandboxId);
+        cfg.workspaces = (cfg.workspaces || []).filter(
+          (w) => w.sandboxId !== sandboxId
+        );
+        saveConfig(cfg);
+        result = { removedSandboxId: sandboxId };
+      } else {
+        ok = false;
+        result = { error: `Unknown action ${action.code}` };
+      }
+    } catch (err) {
+      ok = false;
+      result = { error: err instanceof Error ? err.message : String(err) };
+    }
+
+    try {
+      await api(
+        cfg.adminUrl,
+        cfg.token,
+        "POST",
+        `/api/v1/bridge/machine/actions/${action.id}/complete`,
+        { ok, result }
+      );
+    } catch (err) {
+      warn(
+        `failed to complete action: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+  }
+}
+
+function buildIssues(cfg, workspaceStates) {
+  /** @type {Array<Record<string, unknown>>} */
+  const issues = [];
+  const cli = detectCliProviders();
+  if (!cli.length) {
+    issues.push({
+      code: "missing_cli",
+      severity: "error",
+      title: "No coding agent CLI found",
+      message:
+        "PATH has no agent, claude, or agy. Chat turns will fail until one is installed.",
+      resolution: "Install and authenticate a CLI, then Recheck.",
+      actionCode: "recheck",
+      sandboxId: null,
+    });
+  }
+  for (const st of workspaceStates) {
+    if (!st.aiServerUp) {
+      issues.push({
+        code: "ai_server_down",
+        severity: "error",
+        title: `AI server down (${st.sandboxName || st.sandboxId})`,
+        message: `Cannot reach http://localhost:${st.port}`,
+        resolution: "Start ai-server from the Bridges page or restart the bridge.",
+        actionCode: "start_ai_server",
+        sandboxId: st.sandboxId,
+      });
+    }
+  }
+  return issues;
+}
+
+async function pairFlow(args) {
+  let cfg = loadConfig() || {};
+  ensureMachineId(cfg);
+
+  let adminUrl =
+    (typeof args.adminUrl === "string" && args.adminUrl) ||
+    cfg.adminUrl ||
+    process.env.MAINTAINER_PRO_URL ||
+    "";
+  let code = typeof args.pair === "string" ? args.pair : "";
+
+  if (!adminUrl) {
+    adminUrl = await ask("Maintainer Pro admin URL: ");
+  }
+  if (!code) {
+    code = await ask("Pair code (from admin → Bridges): ");
+  }
+  if (!adminUrl || !code) fail("admin URL and pair code are required");
+
+  const result = await api(adminUrl, null, "POST", "/api/v1/bridge/pair", {
+    code,
+    machineId: cfg.machineId,
+    hostname: os.hostname(),
+    platform: `${os.platform()}-${os.arch()}`,
+    bridgeVersion: PACKAGE_VERSION,
+    name: os.hostname(),
+  });
+
+  cfg.adminUrl = result.adminUrl || adminUrl.replace(/\/$/, "");
+  cfg.token = result.token;
+  cfg.partnerId = result.machine?.partnerId;
+  cfg.pairedAt = new Date().toISOString();
+  saveConfig(cfg);
+  log(`paired as ${result.machine?.name || cfg.machineId}`);
+  log(`config ${configPath()}`);
+  return cfg;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  let cfg = loadConfig() || {};
+  ensureMachineId(cfg);
+
+  if (typeof args.offerFolder === "string") {
+    cfg.offeredFolders = cfg.offeredFolders || [];
+    const resolved = path.resolve(args.offerFolder);
+    if (!cfg.offeredFolders.includes(resolved)) {
+      cfg.offeredFolders.push(resolved);
+      saveConfig(cfg);
+      log(`offering folder ${resolved}`);
+    }
+  }
+
+  if (args.pair || !cfg.token || !cfg.adminUrl) {
+    cfg = await pairFlow(args);
+  }
+
+  cfg.noAiServer = Boolean(args.noAiServer);
+  saveConfig(cfg);
+
+  log(`machine ${cfg.machineId}`);
+  log(`admin ${cfg.adminUrl}`);
+  log(`config ${configPath()}`);
+
+  const tick = async () => {
+    const remoteWorkspaces = [];
+    try {
+      // Heartbeat first — server returns assigned workspaces
+      const folders = collectOfferedFolders(cfg);
+      /** @type {Array<{sandboxId:string,sandboxName?:string,port:number,aiServerUp:boolean,folderPath:string}>} */
+      const localStates = [];
+
+      for (const ws of cfg.workspaces || []) {
+        const up = await probeUrl(
+          `http://127.0.0.1:${ws.port}/embed-config.js`
+        );
+        localStates.push({
+          sandboxId: ws.sandboxId,
+          sandboxName: ws.sandboxName,
+          port: ws.port,
+          folderPath: ws.folderPath,
+          aiServerUp: up,
+        });
+        if (!cfg.noAiServer && !up) {
+          startAiServerForWorkspace(ws);
+        }
+      }
+
+      const hb = await api(
+        cfg.adminUrl,
+        cfg.token,
+        "POST",
+        "/api/v1/bridge/machine/heartbeat",
+        {
+          hostname: os.hostname(),
+          platform: `${os.platform()}-${os.arch()}`,
+          bridgeVersion: PACKAGE_VERSION,
+          folders,
+          issues: buildIssues(cfg, localStates),
+        }
+      );
+
+      // Sync local workspace list from server assignments
+      if (Array.isArray(hb.workspaces)) {
+        for (const remote of hb.workspaces) {
+          remoteWorkspaces.push(remote);
+          const local = (cfg.workspaces || []).find(
+            (w) => w.sandboxId === remote.sandboxId
+          );
+          if (!local) {
+            cfg.workspaces = cfg.workspaces || [];
+            cfg.workspaces.push({
+              sandboxId: remote.sandboxId,
+              folderPath: remote.folderPath,
+              port: remote.port,
+              sandboxName: remote.sandboxName,
+              applicationName: remote.applicationName,
+            });
+            saveConfig(cfg);
+          } else if (local.folderPath !== remote.folderPath) {
+            local.folderPath = remote.folderPath;
+            local.port = remote.port;
+            saveConfig(cfg);
+          }
+        }
+      }
+
+      if (Array.isArray(hb.actions) && hb.actions.length > 0) {
+        await runActions(cfg, hb.actions);
+      }
+    } catch (err) {
+      warn(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  await tick();
+  setInterval(() => {
+    void tick();
+  }, HEARTBEAT_MS);
+
+  const shutdown = () => {
+    log("shutting down");
+    for (const id of [...children.keys()]) stopChild(id);
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((err) => fail(err instanceof Error ? err.message : String(err)));