roforge-cli 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roforge-cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "RoForge \u2014 Claude-Code-style local AI agent for Roblox Studio. BYOK, zero backend, zero dependencies.",
   "type": "module",
   "bin": {

package/src/bridge/server.js

@@ -7,6 +7,7 @@
 //   POST /v1/bridge/jobs/:id/result       → {ok}
 // Auth: Authorization: Bearer <bridge token> (loopback-only by design).
 import http from "node:http";
+import { timingSafeEqual } from "node:crypto";
 import { json } from "./wire.js";
 
 export class BridgeServer {
@@ -59,7 +60,13 @@ export class BridgeServer {
   _authorized(req) {
     const h = String(req.headers["authorization"] || "");
     const m = /^Bearer\s+(.+)$/i.exec(h);
-    return Boolean(m && m[1].trim() === this.token);
+    if (!m) return false;
+    // Constant-time compare (defence in depth; the server is loopback-only).
+    const given = m[1].trim();
+    const a = Buffer.from(given);
+    const b = Buffer.from(this.token);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
   }
 
   _handle(req, res) {

package/src/config.js

@@ -133,14 +133,25 @@ export function loadFileConfig() {
 export function saveFileConfig(patch) {
   const current = loadFileConfig();
   const next = deepMerge(current, patch);
-  fs.mkdirSync(configDir(), { recursive: true });
-  fs.writeFileSync(configFile(), JSON.stringify(next, null, 2));
+  fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(configFile(), JSON.stringify(next, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(configFile(), 0o600); // writeFileSync mode is ignored on existing files
+  } catch {
+    /* best effort */
+  }
   return next;
 }
 
+const POLLUTION_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 function deepMerge(a, b) {
-  const out = { ...a };
+  const out = Object.create(null);
+  for (const [k, v] of Object.entries(a)) {
+    if (POLLUTION_KEYS.has(k)) continue;
+    out[k] = v;
+  }
   for (const [k, v] of Object.entries(b)) {
+    if (POLLUTION_KEYS.has(k)) continue;
     out[k] = v && typeof v === "object" && !Array.isArray(v) && a[k] && typeof a[k] === "object" ? deepMerge(a[k], v) : v;
   }
   return out;

package/src/plugins.js

@@ -0,0 +1,533 @@
+// RoForge CLI — strict declarative plugin system.
+//
+// A plugin is a JSON file. That is the whole trust model:
+//
+//   • NO code fields. Not a script, not a handler, not an eval, not a
+//     template engine. The validator is a strict allowlist — any key that is
+//     not explicitly permitted (at any depth) rejects the plugin. A plugin
+//     therefore cannot contain malicious intent by construction.
+//   • Actions are limited to four: http (public https only, no
+//     localhost/private addresses), command (allowlisted binary, argv array,
+//     no shell), read-file (relative path inside the project root, size-capped),
+//     transform (placeholder fill from validated args only).
+//   • The CLI never passes its own API keys or environment to plugins. There
+//     is no variable expansion at all — the only template syntax is
+//     {{argname}} and only for args declared in the tool's input_schema.
+//   • Mutations are approval-gated: http POST/PUT and command tools always
+//     require approval.
+//   • Every output is size-capped (per-tool, hard ceiling 64 KB).
+//
+// Placement: <project>/plugins/*.json (project-local) and
+// ~/.roforge/plugins/*.json (user-wide). ROFORGE_PLUGINS_DIR overrides for tests.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+
+export const HARD_OUTPUT_LIMIT = 65536;
+const DEFAULT_OUTPUT_LIMIT = 8000;
+const DEFAULT_HTTP_TIMEOUT_MS = 15000;
+const DEFAULT_READ_BYTES = 256 * 1024;
+const MAX_READ_BYTES = 1024 * 1024;
+const MAX_TOOLS = 50;
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,47}$/;
+
+// Fields that are never allowed at the top level, even if a future allowlist
+// regressed — these are the classic "hidden code" shapes.
+const BANNED_TOP_KEYS = /^(code|script|eval|exec|shell|js|javascript|python|lua|luau|handler|entrypoint|main)$/i;
+
+const ACTION_TYPES = new Set(["http", "command", "read-file", "transform"]);
+const HTTP_METHODS = new Set(["GET", "POST", "PUT"]);
+const FORBIDDEN_ARG_CHARS = /[;|&`$<>\n\r]/;
+const PRIVATE_HOST_RE =
+  /^(localhost|127\.[0-9.]+|0\.0\.0\.0|10\.[0-9.]+|192\.168\.[0-9.]+|172\.(1[6-9]|2[0-9]|3[01])\.[0-9.]+|169\.254\.[0-9.]+|metadata\.google\.internal|.*\.local|.*\.internal)$/i;
+
+// Fail-closed host check. new URL() normalizes IPv4 numerics (2130706433 →
+// 127.0.0.1) but keeps IPv6 bracketed, so bracketed/unknown IPv6 is rejected
+// outright — public dev endpoints use domain names, not raw IPv6.
+function isPublicHost(hostIn) {
+  let host = String(hostIn || "").toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+  if (host.includes(":")) {
+    if (host === "" || host === "::" || host === "::1") return false;
+    if (/^fe[89ab]/.test(host)) return false; // link-local fe80::/10
+    if (/^f[cd]/.test(host)) return false; // ULA fc00::/7
+    const mapped = /^::ffff:(.+)$/.exec(host); // IPv4-mapped ::ffff:a.b.c.d
+    if (mapped) return isPublicHost(mapped[1]);
+    return false; // any other IPv6: fail closed
+  }
+  if (!host || host.length > 253) return false;
+  if (PRIVATE_HOST_RE.test(host)) return false;
+  return true;
+}
+
+function isObj(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function err(msg, extra = {}) {
+  return { ok: false, error: msg, ...extra };
+}
+
+function checkName(name, what) {
+  if (typeof name !== "string" || !NAME_RE.test(name)) {
+    return err(`${what} name must match ${NAME_RE} (got ${JSON.stringify(name)})`);
+  }
+  if (name.startsWith("forge_")) {
+    return err(`${what} name "${name}" is reserved for Studio bridge tools`);
+  }
+  return { ok: true, value: name };
+}
+
+function checkDesc(desc) {
+  if (typeof desc !== "string" || desc.length === 0 || desc.length > 300) {
+    return err("description must be a non-empty string (max 300 chars)");
+  }
+  return { ok: true, value: desc };
+}
+
+// input_schema: JSON-schema object shape, strict, no $ref, no patterns
+// beyond simple strings. Returns the property names for template checks.
+function checkInputSchema(schema) {
+  if (!isObj(schema)) return err("input_schema must be an object");
+  const allowed = new Set(["type", "properties", "required", "additionalProperties", "description"]);
+  for (const k of Object.keys(schema)) {
+    if (!allowed.has(k)) return err(`input_schema: unknown key "${k}"`);
+  }
+  if (schema.type !== "object") return err('input_schema.type must be "object"');
+  if (schema.additionalProperties !== false) {
+    return err('input_schema must set "additionalProperties": false (strict)');
+  }
+  const props = schema.properties || {};
+  const propNames = new Set();
+  for (const [pname, pdef] of Object.entries(props)) {
+    if (!NAME_RE.test(pname)) return err(`input_schema property "${pname}" has an invalid name`);
+    if (!isObj(pdef)) return err(`input_schema property "${pname}" must be an object`);
+    const pAllowed = new Set(["type", "description", "minimum", "maximum", "minLength", "maxLength", "items"]);
+    for (const k of Object.keys(pdef)) {
+      if (!pAllowed.has(k)) return err(`input_schema property "${pname}": unknown key "${k}"`);
+    }
+    if (!["string", "integer", "number", "boolean", "array"].includes(pdef.type)) {
+      return err(`input_schema property "${pname}": unsupported type "${pdef.type}"`);
+    }
+    if (pdef.type === "array" && !isObj(pdef.items)) {
+      return err(`input_schema property "${pname}": array needs "items"`);
+    }
+    propNames.add(pname);
+  }
+  const required = schema.required || [];
+  if (!Array.isArray(required)) return err('input_schema.required must be an array');
+  for (const r of required) {
+    if (!propNames.has(r)) return err(`input_schema.required references unknown property "${r}"`);
+  }
+  return { ok: true, value: propNames };
+}
+
+// Template strings: only {{argname}} placeholders, and only names that are
+// declared in the input schema. Everything else is a literal.
+function checkTemplate(str, propNames, what) {
+  if (typeof str !== "string") return err(`${what} must be a string`);
+  if (str.length > 20000) return err(`${what} too long`);
+  const refs = [...str.matchAll(/{{\s*([a-zA-Z0-9_][a-zA-Z0-9_-]*)\s*}}/g)];
+  for (const m of refs) {
+    if (!propNames.has(m[1])) {
+      return err(`${what} references undeclared arg "${m[1]}" (only input_schema properties may be used)`);
+    }
+  }
+  // Any other {{...}} (env-ish, nested, malformed) is rejected.
+  const stripped = str.replace(/{{\s*[a-zA-Z0-9_][a-zA-Z0-9_-]*\s*}}/g, "");
+  if (stripped.includes("{{") || stripped.includes("}}")) {
+    return err(`${what} contains an unsupported {{...}} expression (only declared args may be referenced)`);
+  }
+  return { ok: true, value: str };
+}
+
+function fillTemplate(str, args) {
+  return str.replace(/{{\s*([a-zA-Z0-9_][a-zA-Z0-9_-]*)\s*}}/g, (_, name) => {
+    const v = args[name];
+    if (v === undefined || v === null) return "";
+    return encodeURIComponent(String(v));
+  });
+}
+// Raw fill (command argv): no URL-encoding.
+function fillTemplateRaw(str, args) {
+  return str.replace(/{{\s*([a-zA-Z0-9_][a-zA-Z0-9_-]*)\s*}}/g, (_, name) => {
+    const v = args[name];
+    if (v === undefined || v === null) return "";
+    return String(v);
+  });
+}
+
+function checkOutputMax(v) {
+  if (v === undefined) return { ok: true, value: DEFAULT_OUTPUT_LIMIT };
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > HARD_OUTPUT_LIMIT) {
+    return err(`output_max_chars must be an integer 1..${HARD_OUTPUT_LIMIT}`);
+  }
+  return { ok: true, value: v };
+}
+
+// ---- action validators (strict allowlists) ----
+
+function checkHttpAction(a, propNames) {
+  const allowed = new Set(["type", "method", "url", "headers", "body", "query", "timeout_ms", "output_max_chars"]);
+  for (const k of Object.keys(a)) if (!allowed.has(k)) return err(`http action: unknown key "${k}"`);
+  if (!HTTP_METHODS.has(a.method)) return err('http action.method must be GET, POST, or PUT');
+  if (typeof a.url !== "string" || a.url.length > 2000) return err("http action.url must be a string");
+  let u;
+  try {
+    u = new URL(a.url);
+  } catch {
+    return err(`http action.url is not a valid URL: ${a.url}`);
+  }
+  if (u.protocol !== "https:") return err("http action.url must be https (public web only)");
+  if (!isPublicHost(u.hostname)) return err(`http action.url host "${u.hostname}" is not public (localhost/private ranges are forbidden)`);
+  if (u.port !== "" && u.port !== "443") return err("http action.url may only use the default https port");
+
+  let query = {};
+  if (a.query !== undefined) {
+    if (!isObj(a.query)) return err("http action.query must be an object");
+    const QUERY_KEY_RE = /^[A-Za-z0-9._-]{1,64}$/; // API param names (e.g. universeIds)
+    for (const [k, v] of Object.entries(a.query)) {
+      if (!QUERY_KEY_RE.test(k)) return err(`http action.query key "${k}" invalid`);
+      const t = checkTemplate(String(v), propNames, `http action.query.${k}`);
+      if (!t.ok) return t;
+      query[k] = t.value;
+    }
+  }
+  const headers = a.headers !== undefined ? (isObj(a.headers) ? a.headers : err("http action.headers must be an object")) : {};
+  if (isObj(a.headers)) {
+    for (const [k, v] of Object.entries(a.headers)) {
+      if (typeof k !== "string" || /[\r\n]/.test(k)) return err(`http header key is invalid: ${JSON.stringify(k)}`);
+      if (typeof v !== "string" || v.length > 500) return err(`http header "${k}" must be a short string`);
+      if (/[\r\n\u0000]/.test(v)) return err(`http header "${k}" value contains forbidden control characters`);
+    }
+  }
+  let body;
+  if (a.body !== undefined) {
+    if (a.method === "GET") return err("http action.body is not allowed with GET");
+    const t = checkTemplate(String(a.body), propNames, "http action.body");
+    if (!t.ok) return t;
+    body = t.value;
+  }
+  const to =
+    a.timeout_ms !== undefined
+      ? typeof a.timeout_ms === "number" && a.timeout_ms >= 100 && a.timeout_ms <= 60000
+        ? a.timeout_ms
+        : err("http action.timeout_ms must be 100..60000")
+      : DEFAULT_HTTP_TIMEOUT_MS;
+  if (!Number.isInteger(to)) return to;
+  const out = checkOutputMax(a.output_max_chars);
+  if (!out.ok) return out;
+  return { ok: true, value: { kind: "http", method: a.method, url: a.url, query, headers, body, timeoutMs: to, outputMax: out.value } };
+}
+
+function checkCommandAction(a, propNames, allowedCommands) {
+  const allowed = new Set(["type", "command", "args", "output_max_chars"]);
+  for (const k of Object.keys(a)) if (!allowed.has(k)) return err(`command action: unknown key "${k}"`);
+  if (!allowedCommands.includes(a.command)) {
+    return err(`command action: "${a.command}" is not in the allowlist (${allowedCommands.join(", ")})`);
+  }
+  const args = [];
+  if (a.args !== undefined) {
+    if (!Array.isArray(a.args) || a.args.length > 32) return err("command action.args must be an array (max 32)");
+    for (const v of a.args) {
+      if (typeof v !== "string" || v.length > 200) return err("command action.args entries must be strings (max 200)");
+      if (FORBIDDEN_ARG_CHARS.test(v)) return err(`command arg "${v}" contains shell metacharacters (not allowed)`);
+      const t = checkTemplate(v, propNames, "command arg");
+      if (!t.ok) return t;
+      args.push(t.value);
+    }
+  }
+  const out = checkOutputMax(a.output_max_chars);
+  if (!out.ok) return out;
+  return { ok: true, value: { kind: "command", command: a.command, args, outputMax: out.value } };
+}
+
+function checkReadFileAction(a) {
+  const allowed = new Set(["type", "path", "max_bytes"]);
+  for (const k of Object.keys(a)) if (!allowed.has(k)) return err(`read-file action: unknown key "${k}"`);
+  if (typeof a.path !== "string" || a.path.length === 0 || a.path.length > 500) return err("read-file action.path must be a string");
+  if (path.isAbsolute(a.path) || a.path.startsWith("~")) return err("read-file action.path must be relative to the project root");
+  // Both separator styles: manifests are validated cross-platform, and a
+  // backslash path is traversal on Windows.
+  if (a.path.split(/[\\/]+/).includes("..")) {
+    return err("read-file action.path may not traverse above the project root");
+  }
+  const norm = path.normalize(a.path);
+  const mb = a.max_bytes !== undefined
+    ? typeof a.max_bytes === "number" && Number.isInteger(a.max_bytes) && a.max_bytes >= 1 && a.max_bytes <= MAX_READ_BYTES
+      ? a.max_bytes
+      : err(`read-file action.max_bytes must be 1..${MAX_READ_BYTES}`)
+    : DEFAULT_READ_BYTES;
+  if (!Number.isInteger(mb)) return mb;
+  return { ok: true, value: { kind: "read-file", path: norm, maxBytes: mb, outputMax: Math.min(DEFAULT_OUTPUT_LIMIT, mb) } };
+}
+
+function checkTransformAction(a, propNames) {
+  const allowed = new Set(["type", "template", "output_max_chars"]);
+  for (const k of Object.keys(a)) if (!allowed.has(k)) return err(`transform action: unknown key "${k}"`);
+  const t = checkTemplate(a.template, propNames, "transform action.template");
+  if (!t.ok) return t;
+  const out = checkOutputMax(a.output_max_chars);
+  if (!out.ok) return out;
+  return { ok: true, value: { kind: "transform", template: t.value, outputMax: out.value } };
+}
+
+// ---- manifest validation ----
+
+export function validateManifest(obj, allowedCommands = ALLOWED_COMMANDS) {
+  if (!isObj(obj)) return err("manifest must be a JSON object");
+  for (const k of Object.keys(obj)) {
+    if (BANNED_TOP_KEYS.test(k)) {
+      return err(`plugin manifest contains a code field ("${k}") — plugins are declarative only`);
+    }
+  }
+  const allowed = new Set(["name", "version", "description", "tools"]);
+  for (const k of Object.keys(obj)) if (!allowed.has(k)) return err(`unknown manifest key "${k}"`);
+  const name = checkName(obj.name, "plugin");
+  if (!name.ok) return name;
+  if (typeof obj.version !== "string" || !/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(obj.version)) {
+    return err('version must be semver-like "1.2.3"');
+  }
+  const desc = checkDesc(obj.description);
+  if (!desc.ok) return desc;
+  if (!Array.isArray(obj.tools) || obj.tools.length < 1 || obj.tools.length > MAX_TOOLS) {
+    return err(`tools must be an array of 1..${MAX_TOOLS}`);
+  }
+  const tools = [];
+  const seen = new Set();
+  for (const t of obj.tools) {
+    if (!isObj(t)) return err("each tool must be an object");
+    const tAllowed = new Set(["name", "description", "input_schema", "action"]);
+    for (const k of Object.keys(t)) {
+      if (BANNED_TOP_KEYS.test(k)) return err(`tool contains a code field ("${k}") — plugins are declarative only`);
+      if (!tAllowed.has(k)) return err(`tool: unknown key "${k}"`);
+    }
+    const tn = checkName(t.name, "tool");
+    if (!tn.ok) return tn;
+    if (seen.has(tn.value)) return err(`duplicate tool name "${tn.value}"`);
+    seen.add(tn.value);
+    const td = checkDesc(t.description);
+    if (!td.ok) return td;
+    const sch = checkInputSchema(t.input_schema);
+    if (!sch.ok) return err(`tool "${tn.value}": ${sch.error}`);
+    const action = t.action;
+    if (!isObj(action)) return err(`tool "${tn.value}": action must be an object`);
+    if (!ACTION_TYPES.has(action.type)) {
+      return err(`tool "${tn.value}": action.type must be one of ${[...ACTION_TYPES].join(", ")}`);
+    }
+    let av;
+    switch (action.type) {
+      case "http":
+        av = checkHttpAction(action, sch.value);
+        break;
+      case "command":
+        av = checkCommandAction(action, sch.value, allowedCommands);
+        break;
+      case "read-file":
+        av = checkReadFileAction(action);
+        break;
+      case "transform":
+        av = checkTransformAction(action, sch.value);
+        break;
+    }
+    if (!av.ok) return err(`tool "${tn.value}": ${av.error}`);
+    const destructive = av.value.kind === "command" || (av.value.kind === "http" && av.value.method !== "GET");
+    tools.push({
+      name: tn.value,
+      description: td.value,
+      inputSchema: t.input_schema,
+      action: av.value,
+      requiresApproval: destructive,
+    });
+  }
+  return { ok: true, manifest: { name: name.value, version: obj.version, description: desc.value, tools } };
+}
+
+// Default allowlist; overridable per load call (config / tests).
+export const DEFAULT_ALLOWED_COMMANDS = ["roforge"];
+const ALLOWED_COMMANDS = DEFAULT_ALLOWED_COMMANDS;
+
+// ---- execution ----
+
+function capText(text, max, label) {
+  const s = String(text);
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}\n… truncated (${s.length - max} more chars; ${label} is capped at ${max})`;
+}
+
+export function pluginToolExecutor(plugin, tool) {
+  return async (args) => {
+    const a = tool.action;
+    args = isObj(args) ? args : {};
+    try {
+      if (a.kind === "http") {
+        // Manual redirects: every hop must re-pass the public-host guard
+        // (a 302 to a private address is an SSRF and gets refused).
+        const start = new URL(a.url);
+        for (const [k, tmpl] of Object.entries(a.query)) start.searchParams.set(k, fillTemplate(tmpl, args));
+        let res = null;
+        let cur = start;
+        for (let hop = 0; hop <= 3; hop++) {
+          res = await fetch(cur.toString(), {
+            method: hop === 0 ? a.method : "GET",
+            headers: a.headers,
+            body: hop === 0 && a.body !== undefined ? fillTemplate(a.body, args) : undefined,
+            redirect: "manual",
+            signal: AbortSignal.timeout(a.timeoutMs),
+          });
+          if ([301, 302, 303, 307, 308].includes(res.status)) {
+            const loc = res.headers.get("location");
+            if (!loc) return "ERROR: redirect without Location";
+            let next;
+            try {
+              next = new URL(loc, cur);
+            } catch {
+              return "ERROR: invalid redirect Location";
+            }
+            if (next.protocol !== "https:" || !isPublicHost(next.hostname) || (next.port !== "" && next.port !== "443")) {
+              return "ERROR: redirect to a non-public https target is refused (SSRF guard)";
+            }
+            cur = next;
+            continue;
+          }
+          break;
+        }
+        if (!res) return "ERROR: too many redirects";
+        // Cap the response body (a hostile public host cannot stream gigabytes
+        // into memory): read up to 1 MiB, stop, discard the rest.
+        const MAX_BODY = 1024 * 1024;
+        const reader = res.body ? res.body.getReader() : null;
+        let text;
+        if (reader) {
+          const parts = [];
+          let total = 0;
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            const room = MAX_BODY - total;
+            if (value.length > room) {
+              parts.push(value.subarray(0, room));
+              total += room;
+              try { await reader.cancel(); } catch { /* ignore */ }
+              break;
+            }
+            parts.push(value);
+            total += value.length;
+          }
+          text = Buffer.concat(parts).toString("utf8");
+        } else {
+          text = await res.text();
+        }
+        if (!res.ok) return `ERROR: HTTP ${res.status} ${res.statusText} from ${a.url}`;
+        return capText(text, a.outputMax, "plugin output");
+      }
+      if (a.kind === "command") {
+        const out = await new Promise((resolve, reject) => {
+          execFile(a.command, a.args.map((t) => fillTemplateRaw(t, args)), {
+            timeout: 30000,
+            maxBuffer: Math.max(a.outputMax * 2, 64 * 1024),
+          }, (e, stdout, stderr) => (e ? reject(e) : resolve(stdout)));
+        });
+        return capText(out, a.outputMax, "plugin output");
+      }
+      if (a.kind === "read-file") {
+        const root = fs.realpathSync(process.cwd());
+        let full;
+        try {
+          full = fs.realpathSync(path.resolve(root, a.path));
+        } catch {
+          return `ERROR: file not found: ${a.path}`;
+        }
+        // realpath follows symlinks — a link pointing outside the project is
+        // rejected here, not at parse time.
+        if (full !== root && !full.startsWith(root + path.sep)) return "ERROR: path escapes the project root";
+        if (!fs.statSync(full).isFile()) return `ERROR: not a file: ${a.path}`;
+        const st = fs.statSync(full);
+        if (st.size > a.maxBytes) return `ERROR: file too large (${st.size} > ${a.maxBytes} bytes)`;
+        return capText(fs.readFileSync(full, "utf8"), a.outputMax, "file output");
+      }
+      if (a.kind === "transform") {
+        // Plain-text output: raw (unencoded) values.
+        return capText(fillTemplateRaw(a.template, args), a.outputMax, "plugin output");
+      }
+    } catch (e) {
+      return `ERROR: ${e.message || String(e)}`;
+    }
+    return "ERROR: unknown action";
+  };
+}
+
+// ---- discovery + build ----
+
+export function pluginDirs({ cwd, configDirBase }) {
+  const dirs = [];
+  if (process.env.ROFORGE_PLUGINS_DIR) dirs.push(process.env.ROFORGE_PLUGINS_DIR);
+  if (cwd) dirs.push(path.join(cwd, "plugins"));
+  if (configDirBase) dirs.push(path.join(configDirBase, "plugins"));
+  return [...new Set(dirs)];
+}
+
+export function loadPlugins({ cwd, configDirBase, allowedCommands = ALLOWED_COMMANDS } = {}) {
+  // Bind the allowlist for this load (validateManifest reads ALLOWED_COMMANDS
+  // via the closure below).
+  const tools = [];
+  const plugins = [];
+  const errors = [];
+  const seenTool = new Set();
+  for (const dir of pluginDirs({ cwd, configDirBase })) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+    } catch {
+      continue;
+    }
+    for (const f of entries) {
+      const file = path.join(dir, f);
+      let raw;
+      try {
+        raw = fs.readFileSync(file);
+      } catch {
+        errors.push({ file, error: "unreadable" });
+        continue;
+      }
+      if (raw.length > MAX_MANIFEST_BYTES) {
+        errors.push({ file, error: `manifest too large (${raw.length} > ${MAX_MANIFEST_BYTES} bytes)` });
+        continue;
+      }
+      let obj;
+      try {
+        obj = JSON.parse(raw.toString("utf8"));
+      } catch (e) {
+        errors.push({ file, error: `invalid JSON: ${e.message}` });
+        continue;
+      }
+      const res = validateManifest(obj, allowedCommands);
+      if (!res.ok) {
+        errors.push({ file, error: res.error });
+        continue;
+      }
+      const m = res.manifest;
+      const dupTools = m.tools.filter((t) => seenTool.has(t.name));
+      if (dupTools.length) {
+        errors.push({ file, error: `tool name conflict with an already-loaded plugin: ${dupTools.map((t) => t.name).join(", ")}` });
+        continue;
+      }
+      plugins.push({ name: m.name, version: m.version, file, toolCount: m.tools.length });
+      for (const t of m.tools) {
+        seenTool.add(t.name);
+        tools.push({
+          name: t.name,
+          description: `[plugin:${m.name}] ${t.description}`,
+          inputSchema: t.inputSchema,
+          tier: "plugin",
+          plugin: m.name,
+          requiresApproval: t.requiresApproval,
+          execute: pluginToolExecutor(m, t),
+        });
+      }
+    }
+  }
+  return { tools, plugins, errors };
+}

package/src/session.js

@@ -49,7 +49,14 @@ export class Session {
       luauAnalyzePath: this.luauAnalyzePath,
     });
     this.tools = info.tools;
-    this.studioInfo = { mcp: info.mcp, bridge: info.bridge, mcpToolCount: info.mcpToolCount, mcpCapture: info.mcpCapture || [] };
+    this.studioInfo = {
+      mcp: info.mcp,
+      bridge: info.bridge,
+      mcpToolCount: info.mcpToolCount,
+      mcpCapture: info.mcpCapture || [],
+      plugins: info.plugins || [],
+      pluginErrors: info.pluginErrors || [],
+    };
     this.cfg._activeModel = this.model;
     return this.studioInfo;
   }
@@ -90,7 +97,19 @@ Rules:
 Current state:
 - Model: ${this.model} (${this.providerName}${PROVIDERS[this.providerName] && PROVIDERS[this.providerName].hasFreeTier && this.cfg.freeFirst !== false ? ", free tier" : ""})
 - ${studio.join(" ")}
-- Tools: ${this.tools.map((t) => t.name).join(", ")}`;
+- Tools: ${this.tools.map((t) => t.name).join(", ")}${
+    this.studioInfo.plugins && this.studioInfo.plugins.length
+      ? `\n\nPlugins (strict declarative JSON — no code, outputs capped, mutations approval-gated): ${this.studioInfo.plugins
+          .map((p) => `${p.name}@${p.version} (${p.toolCount} tools)`)
+          .join(", ")}.`
+      : ""
+  }${
+    this.studioInfo.pluginErrors && this.studioInfo.pluginErrors.length
+      ? `\n\nRejected plugins (tell the user if they ask; fix the JSON and restart): ${this.studioInfo.pluginErrors
+          .map((e) => `${e.file}: ${e.error}`)
+          .join("; ")}.`
+      : ""
+  }`;
   }
 
   async send(userText) {

package/src/tools/index.js

@@ -7,6 +7,8 @@ import { robloxTools } from "./roblox.js";
 import { projectTools } from "./project.js";
 import { bridgeTools, mcpToolsFromList, mcpCaptureNames } from "./studio.js";
 import { McpClient } from "../mcp.js";
+import { loadPlugins, DEFAULT_ALLOWED_COMMANDS } from "../plugins.js";
+import { configDir } from "../config.js";
 
 export async function buildTools({ cfg, cwd, bridgeServer, luauAnalyzePath }) {
   const tools = [];
@@ -24,6 +26,18 @@ export async function buildTools({ cfg, cwd, bridgeServer, luauAnalyzePath }) {
   add(projectTools({ cwd, luauAnalyzePath }));
   if (bridgeServer) add(bridgeTools(bridgeServer));
 
+  // Strict declarative plugins (JSON only — no code fields, ever).
+  const pcfg = (cfg && cfg.plugins) || {};
+  const allowedCommands =
+    Array.isArray(pcfg.allowedCommands) && pcfg.allowedCommands.length
+      ? pcfg.allowedCommands.filter((c) => typeof c === "string" && /^[a-z0-9._-]{1,32}$/i.test(c))
+      : DEFAULT_ALLOWED_COMMANDS;
+  const pluginInfo =
+    pcfg.enabled === false
+      ? { tools: [], plugins: [], pluginErrors: [] }
+      : loadPlugins({ cwd, configDirBase: configDir(), allowedCommands });
+  add(pluginInfo.tools);
+
   // MCP tier (official, built into Studio)
   if (cfg.studioMode === "mcp" || cfg.studioMode === "auto") {
     try {
@@ -34,14 +48,30 @@ export async function buildTools({ cfg, cwd, bridgeServer, luauAnalyzePath }) {
         add(mcpToolsFromList(client, raw));
         cfg._mcpClient = client;
         cfg._mcpConnected = true;
-        return { tools, mcp: true, bridge: Boolean(bridgeServer), mcpToolCount: raw.length, mcpCapture: mcpCaptureNames(raw) };
+        return {
+          tools,
+          mcp: true,
+          bridge: Boolean(bridgeServer),
+          mcpToolCount: raw.length,
+          mcpCapture: mcpCaptureNames(raw),
+          plugins: pluginInfo.plugins,
+          pluginErrors: pluginInfo.errors,
+        };
       }
     } catch {
       /* fall through to bridge-only */
     }
   }
 
-  return { tools, mcp: false, bridge: Boolean(bridgeServer), mcpToolCount: 0, mcpCapture: [] };
+  return {
+    tools,
+    mcp: false,
+    bridge: Boolean(bridgeServer),
+    mcpToolCount: 0,
+    mcpCapture: [],
+    plugins: pluginInfo.plugins,
+    pluginErrors: pluginInfo.errors,
+  };
 }
 
 export function listToolNames(tools) {

package/src/tools/studio.js

@@ -29,6 +29,10 @@ const BRIDGE_TOOL_NAMES = [
   "forge_export",
   "forge_import",
   "forge_pro",
+  "forge_pro_features",
+  "forge_cloud_snapshot",
+  "forge_cloud_restore",
+  "forge_team_share",
 ];
 
 const BRIDGE_DESCRIPTIONS = {
@@ -57,6 +61,10 @@ const BRIDGE_DESCRIPTIONS = {
   forge_export: "Export a DataModel subtree as JSON (properties, script sources truncated, attributes). Defaults to workspace, depth 3 (max 6; 10 with RoForge Pro).",
   forge_import: "Apply a forge_export JSON back into Studio: recreates the instance tree (properties, sources, attributes) under a parent. dry_run=true only reports. Destructive; max 500 nodes (2500 with RoForge Pro).",
   forge_pro: "Report the current RoForge Pro entitlement: Free or Pro, which pass/product the Studio user owns, and the active limits + Pro features. Call it to know whether the user has Pro.",
+  forge_pro_features: "Status of the Pro feature component (closed module): installed or absent, plus its report (snapshot store, team workspace, MCP relay). Read-only; call before offering Pro features.",
+  forge_cloud_snapshot: "PRO: save a named snapshot of a place subtree (default: workspace) to the Pro store for later restore. Needs the Pro module installed and the Pro pass.",
+  forge_cloud_restore: "PRO: restore a named Pro snapshot into the place (default under workspace). Destructive: rebuilds the instance tree. Needs the Pro module installed and the Pro pass.",
+  forge_team_share: "PRO: publish a reference (place id, checkpoint label, or note) to the shared team workspace visible to teammates in the place. Destructive: writes the shared store. Needs the Pro module installed and the Pro pass.",
 };
 
 const BRIDGE_SCHEMAS = {
@@ -216,6 +224,33 @@ const BRIDGE_SCHEMAS = {
     additionalProperties: false,
   },
   forge_pro: { type: "object", properties: {}, additionalProperties: false },
+  forge_pro_features: { type: "object", properties: {}, additionalProperties: false },
+  forge_cloud_snapshot: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Dotted subtree root (default: workspace)" },
+      name: { type: "string", description: "Snapshot label (default: auto)" },
+    },
+    additionalProperties: false,
+  },
+  forge_cloud_restore: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Snapshot label to restore" },
+      path: { type: "string", description: "Dotted parent to restore into (default: workspace)" },
+    },
+    required: ["name"],
+    additionalProperties: false,
+  },
+  forge_team_share: {
+    type: "object",
+    properties: {
+      label: { type: "string", description: "Short name, e.g. 'level1-wip'" },
+      ref: { type: "string", description: "The reference to share, e.g. 'place:12345'" },
+    },
+    required: ["label", "ref"],
+    additionalProperties: false,
+  },
 };
 
 // Tools that modify the DataModel — gated by the approval prompt.
@@ -229,6 +264,8 @@ const DESTRUCTIVE = new Set([
   "forge_undo",
   "forge_bulk_create",
   "forge_import",
+  "forge_cloud_restore",
+  "forge_team_share",
 ]);
 
 export function bridgeTools(bridgeServer) {

package/src/tui/tui.js

@@ -312,6 +312,12 @@ export class TUI {
         );
       }
     }
+    if (s.plugins && s.plugins.length) {
+      lines.push(`${green("●")} plugins: ${s.plugins.map((p) => `${p.name}@${p.version}`).join(", ")} (declarative JSON, no code)`);
+    }
+    if (s.pluginErrors && s.pluginErrors.length) {
+      lines.push(`${red("✕")} rejected plugins: ${s.pluginErrors.map((e) => `${e.file}: ${e.error}`).join("; ")}`);
+    }
     return lines.join("\n");
   }