roforge-cli 0.3.0

package/src/bridge/server.js

@@ -0,0 +1,154 @@
+// Local Studio bridge: a tiny HTTP server on 127.0.0.1 that the RoForge
+// Bridge plugin (installed in Studio) polls for commands.
+//
+// Protocol (see docs/BRIDGE.md):
+//   GET  /v1/bridge/ping                  → {ok, time}
+//   GET  /v1/bridge/jobs                  → {jobs: [ ...pending ]}  (first job is claimed)
+//   POST /v1/bridge/jobs/:id/result       → {ok}
+// Auth: Authorization: Bearer <bridge token> (loopback-only by design).
+import http from "node:http";
+import { json } from "./wire.js";
+
+export class BridgeServer {
+  constructor({ port, host = "127.0.0.1", token, jobTimeoutMs = 60000 }) {
+    this.port = port;
+    this.host = host;
+    this.token = token;
+    this.jobTimeoutMs = jobTimeoutMs;
+    this.jobs = new Map(); // id → {id, tool, args, status, resolve, timer}
+    this.lastPingAt = null;
+    this.lastSeenAt = null;
+    this.nextJobId = 1;
+    this.server = null;
+    this.onEvent = null; // (kind, payload) hook for UI
+  }
+
+  get connected() {
+    return this.lastSeenAt !== null && Date.now() - this.lastSeenAt < 10_000;
+  }
+  get lastSeen() {
+    return this.lastSeenAt;
+  }
+
+  start() {
+    this.server = http.createServer((req, res) => this._handle(req, res));
+    return new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(this.port, this.host, () => {
+        const { port } = this.server.address();
+        this.port = port;
+        resolve(this);
+      });
+    });
+  }
+
+  stop() {
+    for (const job of this.jobs.values()) {
+      clearTimeout(job.timer);
+      job.resolve({ ok: false, error: "bridge shut down" });
+    }
+    this.jobs.clear();
+    if (this.server) {
+      const s = this.server;
+      this.server = null;
+      s.close();
+    }
+  }
+
+  _authorized(req) {
+    const h = String(req.headers["authorization"] || "");
+    const m = /^Bearer\s+(.+)$/i.exec(h);
+    return Boolean(m && m[1].trim() === this.token);
+  }
+
+  _handle(req, res) {
+    const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    const emit = (kind, payload) => this.onEvent && this.onEvent(kind, payload);
+
+    try {
+      if (req.method === "GET" && path === "/health") {
+        return json(res, 200, { ok: true, service: "roforge-bridge", connected: this.connected, port: this.port });
+      }
+      if (!this._authorized(req)) {
+        return json(res, 401, { error: "unauthorized — use the token printed by roforge (or `roforge studio`)", code: "UNAUTHORIZED" });
+      }
+      this.lastSeenAt = Date.now();
+
+      if (req.method === "GET" && path === "/v1/bridge/ping") {
+        this.lastPingAt = Date.now();
+        emit("connected", this.lastPingAt);
+        return json(res, 200, { ok: true, time: new Date().toISOString(), jobsPending: this.jobs.size });
+      }
+
+      if (req.method === "GET" && path === "/v1/bridge/jobs") {
+        // claim the first pending job (FIFO)
+        for (const job of this.jobs.values()) {
+          if (job.status === "pending") {
+            job.status = "claimed";
+            job.claimedAt = Date.now();
+            emit("job_claimed", job);
+            return json(res, 200, { jobs: [{ id: job.id, tool: job.tool, args: job.args }] });
+          }
+        }
+        return json(res, 200, { jobs: [] });
+      }
+
+      const m = /^\/v1\/bridge\/jobs\/(\w+)\/result$/.exec(path);
+      if (req.method === "POST" && m) {
+        const job = this.jobs.get(m[1]);
+        if (!job) return json(res, 404, { error: "unknown job", code: "JOB_NOT_FOUND" });
+        let body = {};
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+          size += c.length;
+          // 16MB cap: a 1024x576 viewport PNG is ~3MB in base64 inside JSON.
+          if (size < 16 * 1024 * 1024) chunks.push(c);
+        });
+        req.on("end", () => {
+          try {
+            body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : {};
+          } catch {
+            body = { error: "bad json" };
+          }
+          clearTimeout(job.timer);
+          const out = body.error ? { ok: false, error: body.error } : { ok: true, result: body.result ?? "" };
+          this.jobs.delete(job.id);
+          job.resolve(out);
+          emit("job_done", { id: job.id, ...out });
+          json(res, 200, { ok: true });
+        });
+        return;
+      }
+
+      return json(res, 404, { error: `no route: ${req.method} ${path}`, code: "NOT_FOUND" });
+    } catch (e) {
+      json(res, 500, { error: e.message, code: "INTERNAL" });
+    }
+  }
+
+  // Submit a tool job and wait for the plugin's result. Resolves to
+  // {ok:true, result:string} or {ok:false, error:string}.
+  submit(tool, args, { timeoutMs = this.jobTimeoutMs } = {}) {
+    return new Promise((resolve) => {
+      if (!this.connected) {
+        return resolve({
+          ok: false,
+          error:
+            "Studio bridge is not connected. Open Roblox Studio with the RoForge Bridge plugin active " +
+            `(bridge: http://${this.host}:${this.port}).`,
+        });
+      }
+      const id = `job_${this.nextJobId++}`;
+      const job = { id, tool, args, status: "pending", resolve, claimedAt: null, timer: null };
+      job.timer = setTimeout(() => {
+        if (this.jobs.get(id) === job) {
+          this.jobs.delete(id);
+          job.resolve({ ok: false, error: `studio job timed out after ${Math.round(timeoutMs / 1000)}s` });
+        }
+      }, timeoutMs);
+      this.jobs.set(id, job);
+    });
+  }
+}

package/src/bridge/wire.js

@@ -0,0 +1,10 @@
+import { Buffer } from "node:buffer";
+
+export function json(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}

package/src/config.js

@@ -0,0 +1,227 @@
+// RoForge CLI configuration.
+// Precedence: env vars > ~/.roforge/config.json > defaults.
+//
+// Privacy: API keys live ONLY in this local config (or env). They are sent
+// ONLY to the model provider. The Studio bridge and MCP traffic are local-only.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomToken } from "./util.js";
+
+export const CONFIG_DIR = process.env.ROFORGE_CONFIG_DIR || path.join(os.homedir(), ".roforge");
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+// Provider registry. "auto" (default) picks the first configured provider,
+// free-tier providers first (gemini → groq → openrouter → anthropic → openai).
+export const PROVIDERS = {
+  gemini: {
+    label: "Google Gemini",
+    keyField: "geminiKey",
+    env: "GEMINI_API_KEY",
+    baseField: "geminiBaseUrl",
+    defaultModel: "gemini-2.5-flash",
+    freeModel: "gemini-2.5-flash", // free tier: ~1,500 req/day, no card
+    hasFreeTier: true,
+  },
+  groq: {
+    label: "Groq",
+    keyField: "groqKey",
+    env: "GROQ_API_KEY",
+    baseField: "groqBaseUrl",
+    defaultModel: "llama-3.3-70b-versatile",
+    freeModel: "llama-3.3-70b-versatile", // free tier: ~1,000 req/day per model
+    hasFreeTier: true,
+  },
+  openrouter: {
+    label: "OpenRouter",
+    keyField: "openrouterKey",
+    env: "OPENROUTER_API_KEY",
+    baseField: "openrouterBaseUrl",
+    defaultModel: "qwen/qwen3-coder",
+    freeModel: "qwen/qwen3-coder:free", // :free models: req/day limit, no billing
+    hasFreeTier: true,
+  },
+  anthropic: {
+    label: "Anthropic",
+    keyField: "anthropicKey",
+    env: "ANTHROPIC_API_KEY",
+    baseField: "anthropicBaseUrl",
+    defaultModel: "claude-sonnet-4-5",
+    freeModel: null,
+    hasFreeTier: false,
+  },
+  openai: {
+    label: "OpenAI",
+    keyField: "openaiKey",
+    env: "OPENAI_API_KEY",
+    baseField: "openaiBaseUrl",
+    defaultModel: "gpt-4.1",
+    freeModel: null,
+    hasFreeTier: false,
+  },
+};
+
+// auto-routing order. freeFirst (default) prefers the free tiers so the CLI
+// works out of the box with a free AI Studio key.
+const ORDER_FREE_FIRST = ["gemini", "groq", "openrouter", "anthropic", "openai"];
+const ORDER_PAID_FIRST = ["anthropic", "openai", "gemini", "groq", "openrouter"];
+
+const DEFAULTS = {
+  provider: "auto", // auto | gemini | groq | openrouter | anthropic | openai
+  model: "", // empty = provider default; "provider:model" pins a provider
+  freeFirst: true, // auto mode: prefer free-tier providers/models
+  geminiKey: "",
+  groqKey: "",
+  openrouterKey: "",
+  anthropicKey: "",
+  openaiKey: "",
+  geminiBaseUrl: "https://generativelanguage.googleapis.com",
+  groqBaseUrl: "https://api.groq.com/openai",
+  openrouterBaseUrl: "https://openrouter.ai/api",
+  anthropicBaseUrl: "https://api.anthropic.com",
+  openaiBaseUrl: "https://api.openai.com",
+  maxTokens: 8000,
+  maxIterations: 12,
+  // web search
+  searchProvider: "auto", // auto | serper | brave | wikipedia
+  serperKey: "",
+  braveKey: "",
+  // studio connection
+  studioMode: "auto", // auto | mcp | bridge
+  mcpUrl: "http://localhost:3004/mcp",
+  bridge: {
+    port: 8790,
+    host: "127.0.0.1",
+    token: "",
+  },
+  // approvals: "ask" (default) or "yolo"
+  approve: "ask",
+  // approximate pricing per 1M tokens (USD) for the cost display.
+  // Free-tier models are 0/0.
+  pricing: {
+    "claude-sonnet-4-5": { input: 3, output: 15 },
+    "claude-opus-4-5": { input: 5, output: 25 },
+    "claude-haiku-4-5": { input: 1, output: 5 },
+    "gpt-4.1": { input: 2, output: 8 },
+    "gpt-4o": { input: 2.5, output: 10 },
+    "gemini-2.5-flash": { input: 0, output: 0 },
+    "llama-3.3-70b-versatile": { input: 0, output: 0 },
+    "qwen/qwen3-coder:free": { input: 0, output: 0 },
+  },
+};
+
+export function loadFileConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveFileConfig(patch) {
+  const current = loadFileConfig();
+  const next = deepMerge(current, patch);
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2));
+  return next;
+}
+
+function deepMerge(a, b) {
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    out[k] = v && typeof v === "object" && !Array.isArray(v) && a[k] && typeof a[k] === "object" ? deepMerge(a[k], v) : v;
+  }
+  return out;
+}
+
+// Resolved, runtime config (env overrides applied, defaults filled).
+export function resolveConfig() {
+  const file = loadFileConfig();
+  const cfg = deepMerge(DEFAULTS, file);
+
+  cfg.geminiKey = process.env.GEMINI_API_KEY || cfg.geminiKey || "";
+  cfg.groqKey = process.env.GROQ_API_KEY || cfg.groqKey || "";
+  cfg.openrouterKey = process.env.OPENROUTER_API_KEY || cfg.openrouterKey || "";
+  cfg.anthropicKey = process.env.ANTHROPIC_API_KEY || cfg.anthropicKey || "";
+  cfg.openaiKey = process.env.OPENAI_API_KEY || cfg.openaiKey || "";
+  cfg.model = process.env.ROFORGE_MODEL || cfg.model;
+  if (process.env.ROFORGE_PROVIDER) cfg.provider = process.env.ROFORGE_PROVIDER;
+  if (process.env.ROFORGE_MCP_URL) cfg.mcpUrl = process.env.ROFORGE_MCP_URL;
+  if (process.env.ROFORGE_BRIDGE_PORT) cfg.bridge.port = Number(process.env.ROFORGE_BRIDGE_PORT);
+  if (process.env.ROFORGE_STUDIO_MODE) cfg.studioMode = process.env.ROFORGE_STUDIO_MODE;
+  if (process.env.ROFORGE_MAX_ITERATIONS) cfg.maxIterations = Number(process.env.ROFORGE_MAX_ITERATIONS);
+  if (process.env.ROFORGE_FREE_FIRST === "0" || process.env.ROFORGE_FREE_FIRST === "false") cfg.freeFirst = false;
+
+  if (!cfg.bridge.token) {
+    cfg.bridge.token = randomToken(24);
+    // persist so the token survives restarts (the plugin stores it once)
+    try {
+      saveFileConfig({ bridge: { token: cfg.bridge.token } });
+    } catch {
+      /* non-fatal */
+    }
+  }
+  return cfg;
+}
+
+export function providerMeta(name) {
+  return PROVIDERS[name] || null;
+}
+
+export function providerHasKey(cfg, name) {
+  const meta = PROVIDERS[name];
+  return Boolean(meta && cfg[meta.keyField]);
+}
+
+// The provider that will actually serve requests:
+// an explicit (valid, key-held) cfg.provider wins; otherwise "auto" walks
+// the configured providers free-tier-first (or paid-first when freeFirst=false).
+export function effectiveProvider(cfg) {
+  if (cfg.provider && cfg.provider !== "auto") {
+    return PROVIDERS[cfg.provider] && providerHasKey(cfg, cfg.provider) ? cfg.provider : null;
+  }
+  const order = cfg.freeFirst === false ? ORDER_PAID_FIRST : ORDER_FREE_FIRST;
+  return order.find((p) => providerHasKey(cfg, p)) || null;
+}
+
+// "gemini:gemini-2.5-flash" → {provider:"gemini", model:"gemini-2.5-flash"}.
+// Models may contain ":" themselves (OpenRouter), so only the FIRST segment
+// counts as a provider prefix.
+export function parseModelRef(model) {
+  if (typeof model === "string" && model.includes(":")) {
+    const i = model.indexOf(":");
+    const p = model.slice(0, i);
+    const rest = model.slice(i + 1);
+    if (PROVIDERS[p] && rest) return { provider: p, model: rest };
+  }
+  return null;
+}
+
+export function modelFor(cfg) {
+  // an explicit model ref like "provider:model" pins both
+  const ref = parseModelRef(cfg.model);
+  if (ref && providerHasKey(cfg, ref.provider)) {
+    return ref.model;
+  }
+  const prov = ref ? null : effectiveProvider(cfg);
+  const meta = prov && PROVIDERS[prov];
+  if (!meta) return cfg.model || "claude-sonnet-4-5";
+  // auto mode + freeFirst → the provider's free model; explicit provider →
+  // its default model
+  const wantFree = cfg.provider === "auto" && cfg.freeFirst !== false;
+  return wantFree && meta.freeModel ? meta.freeModel : meta.defaultModel;
+}
+
+export function apiKeyFor(cfg) {
+  const prov = effectiveProvider(cfg);
+  const meta = prov && PROVIDERS[prov];
+  return meta ? cfg[meta.keyField] || "" : "";
+}
+
+export function estimateCost(cfg, usage) {
+  if (!usage) return null;
+  const p = cfg.pricing && cfg.pricing[modelFor(cfg)];
+  if (!p) return { tokens: usage, cost: null };
+  const cost = ((usage.input_tokens || 0) * p.input + (usage.output_tokens || 0) * p.output) / 1_000_000;
+  return { tokens: usage, cost };
+}

package/src/mcp.js

@@ -0,0 +1,159 @@
+// Minimal MCP (Model Context Protocol) client over the Streamable HTTP
+// transport — used to talk to the MCP server built into Roblox Studio
+// (File → Studio Settings → Beta Features → "MCP Server", default
+// http://localhost:3004/mcp).
+//
+// Implements just enough of the protocol: initialize → tools/list → tools/call.
+// Responses may arrive as a single JSON object or as an SSE stream; both handled.
+import { parseSSEStream } from "./util.js";
+
+export class McpError extends Error {}
+
+export class McpClient {
+  constructor(url, { timeoutMs = 30000 } = {}) {
+    this.url = url;
+    this.timeoutMs = timeoutMs;
+    this.sessionId = null;
+    this.nextId = 1;
+    this.serverInfo = null;
+  }
+
+  async request(method, params) {
+    const id = this.nextId++;
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    };
+    if (this.sessionId) headers["mcp-session-id"] = this.sessionId;
+
+    let res;
+    try {
+      res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (e) {
+      const reason = e.name === "TimeoutError" ? "timed out " : "";
+      throw new McpError(`Studio MCP unreachable at ${this.url} (${reason}${e.cause?.code || e.message})`);
+    }
+
+    const sid = res.headers.get("mcp-session-id");
+    if (sid) this.sessionId = sid;
+    const ctype = res.headers.get("content-type") || "";
+    const bodyText = await res.text();
+
+    if (!res.ok) {
+      let msg = bodyText.slice(0, 200);
+      try {
+        const j = JSON.parse(bodyText);
+        msg = (j.error && j.error.message) || msg;
+      } catch {
+        /* keep slice */
+      }
+      throw new McpError(`MCP HTTP ${res.status}: ${msg}`);
+    }
+
+    let payload = null;
+    if (ctype.includes("text/event-stream")) {
+      for (const ev of parseSSEStream(bodyText)) {
+        if (ev.event === "message" && ev.data && ev.data.id === id) {
+          payload = ev.data;
+          break;
+        }
+      }
+      if (!payload) {
+        // some servers send the result in an unnamed message event
+        const first = parseSSEStream(bodyText).find((e) => e.data && typeof e.data === "object" && e.data.result);
+        if (first) payload = first.data;
+      }
+    } else {
+      try {
+        payload = JSON.parse(bodyText);
+      } catch {
+        if (bodyText.trim()) throw new McpError(`MCP: unparseable response: ${bodyText.slice(0, 120)}`);
+      }
+    }
+    if (!payload) throw new McpError(`MCP: no response for request ${id}`);
+    if (payload.error) throw new McpError(`MCP error ${payload.error.code}: ${payload.error.message}`);
+    return payload.result;
+  }
+
+  async notify(method, params) {
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    };
+    if (this.sessionId) headers["mcp-session-id"] = this.sessionId;
+    try {
+      const res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ jsonrpc: "2.0", method, params }),
+        signal: AbortSignal.timeout(10000),
+      });
+      await res.arrayBuffer(); // drain
+    } catch {
+      /* notifications are best-effort */
+    }
+  }
+
+  async connect() {
+    const result = await this.request("initialize", {
+      protocolVersion: "2025-03-26",
+      capabilities: {},
+      clientInfo: { name: "roforge-cli", version: "0.2.0" },
+    });
+    this.serverInfo = result.serverInfo || null;
+    await this.notify("notifications/initialized", {});
+    return result;
+  }
+
+  async listTools() {
+    const result = await this.request("tools/list", {});
+    return (result && result.tools) || [];
+  }
+
+  // Returns { text, isError, image? } — image is {base64, mediaType} when the
+  // tool returned an MCP image content block (e.g. Studio's built-in
+  // screenshot/capture tools) or a resource blob.
+  async callTool(name, args) {
+    const result = await this.request("tools/call", { name, arguments: args || {} });
+    const content = (result && result.content) || [];
+    const texts = [];
+    let image = null;
+    for (const c of content) {
+      if (c.type === "text" && typeof c.text === "string") {
+        texts.push(c.text);
+      } else if (c.type === "image" && typeof c.data === "string" && c.data.length) {
+        image = image || { base64: c.data, mediaType: c.mimeType || "image/png" };
+      } else if (c.type === "resource" && c.resource) {
+        if (typeof c.resource.blob === "string" && c.resource.blob.length) {
+          image = image || { base64: c.resource.blob, mediaType: c.resource.mimeType || "image/png" };
+        }
+        if (typeof c.resource.text === "string") texts.push(c.resource.text);
+      } else {
+        texts.push(JSON.stringify(c));
+      }
+    }
+    return { text: texts.join("\n") || "(no output)", isError: Boolean(result && result.isError), image: image || undefined };
+  }
+}
+
+// Probe: is a Studio MCP server answering at url? Returns {ok, serverInfo, toolCount} or {ok:false, error}.
+export async function probeMcp(url, { timeoutMs = 4000 } = {}) {
+  const client = new McpClient(url, { timeoutMs });
+  try {
+    const init = await client.connect();
+    let toolCount = -1;
+    try {
+      toolCount = (await client.listTools()).length;
+    } catch {
+      /* connected but tools/list failed — still ok */
+    }
+    return { ok: true, serverInfo: init.serverInfo, toolCount };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}