golem-bridge 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nickils
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# Golem
+
+`golem-bridge` connects an AI coding agent to a live Roblox Studio session
+running the Golem plugin.
+
+This repo holds the npm package (the AI side). The Studio plugin itself is
+distributed through the Roblox Creator Store, not from here.
+
+## How it connects
+
+The plugin shows one line in Studio (popup on first run, also in Settings):
+
+```
+Connect to my Roblox Studio, Run: npx golem-bridge connect <channelId>
+```
+
+The user sends that line to their AI. It downloads this package, which asks
+the plugin for its two connection files and stores them under `./.golem/`:
+
+```sh
+npx golem-bridge connect <channelId>
+python3 ./.golem/golem.py ping
+```
+
+`ping` should return `"ok": true` plus the open place name. Then the agent
+reads `./.golem/golem.md` for the full tool reference.
+
+## Files
+
+- `cli.js` - source of the `golem-bridge` package
+- `package.json` - npm manifest

package/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+"use strict";
+
+// golem-bridge: pulls golem.py and golem.md from the Golem Studio plugin
+// over Firebase and writes them to ./.golem/
+
+const fs = require("fs");
+const path = require("path");
+
+const DB_URL = "https://roblox-golem-default-rtdb.firebaseio.com";
+const POLL_INTERVAL_MS = 2000;
+const POLL_ATTEMPTS = 45;
+
+function usage() {
+  console.error("Usage: golem-bridge connect <channelId>");
+  console.error("  <channelId> is shown in the Golem plugin widget inside Roblox Studio.");
+  process.exit(1);
+}
+
+async function postJson(url, body) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw new Error(`POST ${url} failed: HTTP ${res.status}`);
+  }
+  return res.json();
+}
+
+async function getJson(url) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`GET ${url} failed: HTTP ${res.status}`);
+  }
+  const text = await res.text();
+  return text === "null" ? null : JSON.parse(text);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function fetchSetupResult(channelId) {
+  const cmdId = `setup${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  await postJson(`${DB_URL}/channels/${channelId}/cmd.json`, {
+    id: cmdId,
+    op: "setup",
+    ts: Math.floor(Date.now() / 1000),
+  });
+
+  for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt++) {
+    await sleep(POLL_INTERVAL_MS);
+    let keys;
+    try {
+      keys = await getJson(`${DB_URL}/channels/${channelId}/res.json?shallow=true`);
+    } catch {
+      continue;
+    }
+    if (!keys) continue;
+    for (const key of Object.keys(keys).sort()) {
+      let entry;
+      try {
+        entry = await getJson(`${DB_URL}/channels/${channelId}/res/${key}.json`);
+      } catch {
+        continue;
+      }
+      if (entry && entry.id === cmdId) {
+        return entry;
+      }
+    }
+  }
+  return null;
+}
+
+async function connect(channelId) {
+  if (!channelId || channelId.length < 8) {
+    usage();
+  }
+
+  console.log(`Contacting Golem plugin on channel ${channelId} ...`);
+  const entry = await fetchSetupResult(channelId);
+
+  if (!entry) {
+    console.error("No response from the Studio plugin. Is Roblox Studio open with Golem running?");
+    process.exit(1);
+  }
+  if (!entry.ok) {
+    console.error(`Setup failed: ${entry.error || "unknown error"}`);
+    process.exit(1);
+  }
+
+  let result = entry.result;
+  if (entry.resultEncoded) {
+    result = JSON.parse(result);
+  }
+
+  const dir = path.join(process.cwd(), ".golem");
+  fs.mkdirSync(dir, { recursive: true });
+
+  const pyPath = path.join(dir, "golem.py");
+  const mdPath = path.join(dir, "golem.md");
+  fs.writeFileSync(pyPath, result.source);
+  fs.writeFileSync(mdPath, result.prompt);
+
+  console.log("");
+  console.log(result.instructions || "Connected.");
+  console.log("");
+  console.log(`Wrote ${path.relative(process.cwd(), pyPath)} and ${path.relative(process.cwd(), mdPath)}`);
+  console.log(`Next: read ${path.relative(process.cwd(), mdPath)}, then run:`);
+  console.log(`  python3 ${path.relative(process.cwd(), pyPath)} ping`);
+}
+
+async function main() {
+  const [cmd, arg] = process.argv.slice(2);
+  if (cmd !== "connect") {
+    usage();
+  }
+  try {
+    await connect(arg);
+  } catch (err) {
+    console.error(`golem-bridge error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "golem-bridge",
+  "version": "1.0.1",
+  "description": "Connects an AI coding agent to a running Roblox Studio session via the Golem plugin.",
+  "bin": {
+    "golem-bridge": "./cli.js"
+  },
+  "type": "commonjs",
+  "files": ["cli.js", "README.md"],
+  "keywords": ["roblox", "roblox-studio", "ai", "cli"],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickils/Golem.git"
+  },
+  "homepage": "https://github.com/nickils/Golem#readme",
+  "bugs": {
+    "url": "https://github.com/nickils/Golem/issues"
+  }
+}