@bigbrainforge/setup 3.18.0

package/README.md

@@ -0,0 +1,53 @@
+# @bigbrainforge/setup
+
+Forge workstation setup — paste one license, get a working Forge install.
+
+```
+npx @bigbrainforge/setup <your-forge-license>
+```
+
+Or run it with no argument and paste the license when prompted (the value is
+never echoed to the terminal):
+
+```
+npx @bigbrainforge/setup
+```
+
+## What it does
+
+1. Checks the machine has `tar` (needed to unpack the plugin bundle).
+2. Stores the license at `~/.claude/forge/license` (0600).
+3. Discovers and pins your Forge instance (`~/.claude/forge/config.json`).
+4. Seeds `~/.npmrc` with the `@bigbrainforge` registry + auth line.
+5. Downloads and sha256-verifies the Forge plugin bundle, then stages it as a
+   local Claude Code marketplace under `~/.claude/forge/plugin-bundle/`.
+6. Registers the marketplace and installs the plugin via the `claude` CLI —
+   if `claude` isn't on this machine, prints the two commands to run by hand.
+7. Hands off to the plugin's own bootstrap (server check + issue tracker
+   setup).
+
+Every step names its own failure tier (machine / credential / instance
+discovery / package plane / distribution plane / Claude Code CLI / plugin
+bootstrap) and the one fix to try next — nothing is a silent skip.
+
+### If a step fails after setup has already run once
+
+Step 4 seeds `~/.npmrc` so `@bigbrainforge/forge` resolves through your Forge
+instance. Once that has happened, a bare `npx @bigbrainforge/setup` no longer
+resolves this package itself (it lives on the public npm registry, not your
+Forge instance) — if a later step fails and you need to run setup again, use:
+
+```
+npx --@bigbrainforge:registry=https://registry.npmjs.org @bigbrainforge/setup
+```
+
+This one-shot override is what any printed "rerun" fix hint means when it
+names this exact command.
+
+## Runtime dependencies
+
+None. This package is published PUBLIC to npmjs and runs via `npx` on a
+machine with zero prior Forge configuration; everything it needs beyond
+Node's own builtins is bundled at build time (`scripts/build.mjs`, esbuild).
+It carries no secrets and no sealed Forge IP — anything of value it downloads
+is license-gated server-side.

package/dist/setup.cjs

@@ -0,0 +1,1197 @@
+#!/usr/bin/env node
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __commonJS = (cb, mod) => function __require() {
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
+};
+
+// ../forge-plugin/lib/rename-with-retry.js
+var require_rename_with_retry = __commonJS({
+  "../forge-plugin/lib/rename-with-retry.js"(exports2, module2) {
+    var fs = require("node:fs");
+    var RENAME_RETRY_ERR_CODES_LIST = Object.freeze(["EACCES", "EBUSY", "ENOTEMPTY", "EPERM"]);
+    var RENAME_RETRY_ERR_CODES_SET = new Set(RENAME_RETRY_ERR_CODES_LIST);
+    function isWindows() {
+      return process.platform === "win32";
+    }
+    var RENAME_RETRY_MAX_ATTEMPTS = isWindows() ? 10 : 1;
+    var WAIT_SAB = new SharedArrayBuffer(4);
+    var WAIT_VIEW = new Int32Array(WAIT_SAB);
+    function osSleepSync(delayMs) {
+      if (delayMs <= 0) return;
+      Atomics.wait(WAIT_VIEW, 0, 0, delayMs);
+    }
+    function logRetry(attempt, err, src, dst) {
+      if (!process.env.FORGE_RENAME_DEBUG) return;
+      process.stderr.write(
+        `[rename-with-retry] attempt ${attempt + 1}/${RENAME_RETRY_MAX_ATTEMPTS} failed (${err.code}); retrying src=${src} dst=${dst}
+`
+      );
+    }
+    function renameWithRetry(src, dst, doRename = fs.renameSync) {
+      let lastErr;
+      for (let attempt = 0; attempt < RENAME_RETRY_MAX_ATTEMPTS; attempt++) {
+        try {
+          doRename(src, dst);
+          return;
+        } catch (err) {
+          lastErr = err;
+          if (!isWindows() || !RENAME_RETRY_ERR_CODES_SET.has(err.code)) throw err;
+          logRetry(attempt, err, src, dst);
+          const delayMs = Math.min(1 << attempt, 100);
+          osSleepSync(delayMs);
+        }
+      }
+      throw lastErr;
+    }
+    function unlinkWithRetry(target, doUnlink = fs.unlinkSync) {
+      let lastErr;
+      for (let attempt = 0; attempt < RENAME_RETRY_MAX_ATTEMPTS; attempt++) {
+        try {
+          doUnlink(target);
+          return;
+        } catch (err) {
+          lastErr = err;
+          if (!isWindows() || !RENAME_RETRY_ERR_CODES_SET.has(err.code)) throw err;
+          if (process.env.FORGE_RENAME_DEBUG) {
+            process.stderr.write(
+              `[unlink-with-retry] attempt ${attempt + 1}/${RENAME_RETRY_MAX_ATTEMPTS} failed (${err.code}); retrying target=${target}
+`
+            );
+          }
+          const delayMs = Math.min(1 << attempt, 100);
+          osSleepSync(delayMs);
+        }
+      }
+      throw lastErr;
+    }
+    module2.exports = {
+      renameWithRetry,
+      unlinkWithRetry,
+      RENAME_RETRY_MAX_ATTEMPTS,
+      RENAME_RETRY_ERR_CODES_LIST,
+      get RENAME_RETRY_ERR_CODES() {
+        return new Set(RENAME_RETRY_ERR_CODES_LIST);
+      }
+    };
+  }
+});
+
+// ../forge-plugin/lib/license.js
+var require_license = __commonJS({
+  "../forge-plugin/lib/license.js"(exports2, module2) {
+    var fs = require("node:fs");
+    var os2 = require("node:os");
+    var path2 = require("node:path");
+    var { renameWithRetry } = require_rename_with_retry();
+    var LICENSE_RE2 = /^forge_lic_[0-9A-Za-z]{43}$/;
+    function licensePath(io = {}) {
+      const env = io.env ?? process.env;
+      const homedir = io.homedir ?? os2.homedir();
+      return env.FORGE_LICENSE_FILE || path2.join(homedir, ".claude", "forge", "license");
+    }
+    function readLicenseFileValue(io = {}) {
+      try {
+        const raw = fs.readFileSync(licensePath(io), "utf8").trim();
+        return raw.length > 0 ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    function licenseFilePresent(io = {}) {
+      const raw = readLicenseFileValue(io);
+      return raw !== null && LICENSE_RE2.test(raw);
+    }
+    function missingHint() {
+      return "no Forge license on this machine \u2014 run /forge:setup license, or paste it in your own terminal with: node <plugin-root>/scripts/secrets.js set license";
+    }
+    function resolveLicense(io = {}) {
+      const env = io.env ?? process.env;
+      const warn = io.warn ?? ((line) => process.stderr.write(`${line}
+`));
+      const fromEnv = env.FORGE_LICENSE;
+      const envHit = typeof fromEnv === "string" && fromEnv.length > 0;
+      const fromFile = readLicenseFileValue(io);
+      if (envHit) {
+        if (!LICENSE_RE2.test(fromEnv)) {
+          return {
+            value: null,
+            reason: "malformed",
+            hint: "FORGE_LICENSE is set but is not a forge_lic_ key \u2014 check the value your CI/container injects."
+          };
+        }
+        let drift = false;
+        if (fromFile !== null && fromFile !== fromEnv) {
+          drift = true;
+          warn("FORGE_LICENSE differs between env and the license file; using env FORGE_LICENSE.");
+        }
+        return { value: fromEnv, source: "env FORGE_LICENSE", drift };
+      }
+      if (fromFile === null) {
+        return { value: null, reason: "missing", hint: missingHint() };
+      }
+      if (!LICENSE_RE2.test(fromFile)) {
+        return {
+          value: null,
+          reason: "malformed",
+          hint: `the license file exists but does not hold a forge_lic_ key \u2014 re-run /forge:setup license (${licensePath(io)})`
+        };
+      }
+      return { value: fromFile, source: "license file", drift: false };
+    }
+    function writeLicense2(value, io = {}) {
+      const trimmed = typeof value === "string" ? value.trim() : "";
+      if (!LICENSE_RE2.test(trimmed)) {
+        return {
+          ok: false,
+          error: "not a valid license \u2014 expected forge_lic_ followed by 43 base62 characters"
+        };
+      }
+      const target = licensePath(io);
+      const tmp = `${target}.tmp-${process.pid}`;
+      try {
+        fs.mkdirSync(path2.dirname(target), { recursive: true });
+        fs.writeFileSync(tmp, `${trimmed}
+`, { encoding: "utf8", mode: 384 });
+      } catch (err) {
+        try {
+          fs.unlinkSync(tmp);
+        } catch {
+        }
+        return { ok: false, error: `could not write the license file: ${err.code || "write failed"}` };
+      }
+      try {
+        renameWithRetry(tmp, target);
+      } catch (err) {
+        try {
+          fs.unlinkSync(tmp);
+        } catch {
+        }
+        return { ok: false, error: `could not write the license file: ${err.code || "rename failed"}` };
+      }
+      try {
+        fs.chmodSync(target, 384);
+      } catch {
+      }
+      return { ok: true, path: target };
+    }
+    module2.exports = {
+      resolveLicense,
+      writeLicense: writeLicense2,
+      licensePath,
+      licenseFilePresent,
+      readLicenseFileValue,
+      LICENSE_RE: LICENSE_RE2
+    };
+  }
+});
+
+// ../forge-plugin/lib/discover-instance.js
+var require_discover_instance = __commonJS({
+  "../forge-plugin/lib/discover-instance.js"(exports2, module2) {
+    var fs = require("node:fs");
+    var os2 = require("node:os");
+    var path2 = require("node:path");
+    var { resolveLicense } = require_license();
+    var DEFAULT_LICENSING_URL2 = "https://licensing.bigbrainforge.com";
+    var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+    function isSecureUrl2(value) {
+      let parsed;
+      try {
+        parsed = new URL(value);
+      } catch {
+        return false;
+      }
+      if (parsed.protocol === "https:") return true;
+      return parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+    }
+    function checkLicensingUrlTransportSecurity(base) {
+      if (isSecureUrl2(base)) return null;
+      let scheme;
+      try {
+        const parsed = new URL(base);
+        scheme = `${parsed.protocol}//${parsed.hostname}`;
+      } catch {
+        return {
+          ok: false,
+          reason: "insecure_licensing_url",
+          hint: `FORGE_LICENSING_URL is not a valid URL: ${base}`
+        };
+      }
+      return {
+        ok: false,
+        reason: "insecure_licensing_url",
+        hint: `FORGE_LICENSING_URL must use https:// (got ${scheme}). Plain http:// is allowed only for loopback (127.0.0.1, localhost, ::1) \u2014 refusing to send the license credential in cleartext.`
+      };
+    }
+    function pluginConfigPath(io = {}) {
+      const env = io.env ?? process.env;
+      const homedir = io.homedir ?? os2.homedir();
+      return env.FORGE_PLUGIN_CONFIG || path2.join(homedir, ".claude", "forge", "config.json");
+    }
+    function readPinnedUrl(io) {
+      try {
+        const config = JSON.parse(fs.readFileSync(pluginConfigPath(io), "utf8"));
+        return typeof config.mcp_url === "string" && config.mcp_url.length > 0 ? config.mcp_url : null;
+      } catch {
+        return null;
+      }
+    }
+    function pinInstanceUrl(io, instanceUrl) {
+      const target = pluginConfigPath(io);
+      let config = {};
+      if (fs.existsSync(target)) {
+        try {
+          config = JSON.parse(fs.readFileSync(target, "utf8"));
+        } catch {
+          return {
+            ok: false,
+            error: `existing ${target} is not valid JSON \u2014 fix or remove it, then retry`
+          };
+        }
+      }
+      config.mcp_url = instanceUrl.replace(/\/$/, "");
+      fs.mkdirSync(path2.dirname(target), { recursive: true });
+      fs.writeFileSync(target, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+      return { ok: true, mcp_url: config.mcp_url };
+    }
+    function sameHost(a, b) {
+      try {
+        return new URL(a).host === new URL(b).host;
+      } catch {
+        return false;
+      }
+    }
+    async function fetchDiscovery(doFetch, base, licenseValue) {
+      let response;
+      try {
+        response = await doFetch(`${base}/license/discover`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ license: licenseValue }),
+          signal: AbortSignal.timeout(15e3)
+        });
+      } catch {
+        return {
+          ok: false,
+          reason: "discovery_unreachable",
+          hint: `licensing service unreachable \u2014 check network egress to ${base}`
+        };
+      }
+      let body = {};
+      try {
+        body = await response.json();
+      } catch {
+        body = {};
+      }
+      if (response.status === 401) {
+        return {
+          ok: false,
+          reason: "license_invalid",
+          hint: body.error || "unknown or revoked license \u2014 contact your org admin"
+        };
+      }
+      if (!response.ok || typeof body.instance_url !== "string" || body.instance_url.length === 0) {
+        return {
+          ok: false,
+          reason: "discovery_unreachable",
+          hint: `discovery failed (HTTP ${response.status}) at ${base}/license/discover`
+        };
+      }
+      return {
+        ok: true,
+        instance_url: body.instance_url.replace(/\/$/, ""),
+        deployment_model: body.deployment_model ?? null
+      };
+    }
+    function checkPinConflict(pinned, discovered, acceptNewInstance) {
+      if (!pinned || sameHost(pinned, discovered) || acceptNewInstance === true) {
+        return null;
+      }
+      return {
+        ok: false,
+        reason: "pin_conflict",
+        pinned_url: pinned,
+        discovered_url: discovered,
+        hint: `discovery returned ${discovered} but this machine is pinned to ${pinned}. Refusing to release the license to a new host. If the change is expected (your org migrated instances), re-run with --accept-new-instance.`
+      };
+    }
+    async function discoverInstance2(io = {}) {
+      const env = io.env ?? process.env;
+      const doFetch = io.fetchImpl ?? fetch;
+      const license = resolveLicense(io);
+      if (license.value === null) {
+        return { ok: false, reason: "no_license", hint: license.hint };
+      }
+      const pinned = readPinnedUrl(io);
+      if (pinned && io.forceDiscovery !== true) {
+        return { ok: true, instance_url: pinned, deployment_model: null, source: "pin" };
+      }
+      const base = (env.FORGE_LICENSING_URL || DEFAULT_LICENSING_URL2).replace(/\/$/, "");
+      const transportFailure = checkLicensingUrlTransportSecurity(base);
+      if (transportFailure) {
+        return transportFailure;
+      }
+      const discovery = await fetchDiscovery(doFetch, base, license.value);
+      if (!discovery.ok) {
+        return discovery;
+      }
+      const { instance_url: discovered, deployment_model: deploymentModel } = discovery;
+      if (!isSecureUrl2(discovered)) {
+        return {
+          ok: false,
+          reason: "insecure_instance_url",
+          hint: `discovery returned an insecure instance_url (${discovered}) \u2014 refusing to pin it. The instance must be served over https:// (plain http:// is allowed only for loopback), so the license is never exchanged over a cleartext connection.`
+        };
+      }
+      const conflict = checkPinConflict(pinned, discovered, io.acceptNewInstance);
+      if (conflict) {
+        return conflict;
+      }
+      if (!pinned || !sameHost(pinned, discovered)) {
+        const pinResult = pinInstanceUrl(io, discovered);
+        if (!pinResult.ok) {
+          return { ok: false, reason: "discovery_unreachable", hint: pinResult.error };
+        }
+      }
+      return {
+        ok: true,
+        instance_url: discovered,
+        deployment_model: deploymentModel,
+        source: "discovery"
+      };
+    }
+    module2.exports = { discoverInstance: discoverInstance2, DEFAULT_LICENSING_URL: DEFAULT_LICENSING_URL2, isSecureUrl: isSecureUrl2 };
+  }
+});
+
+// ../forge-plugin/lib/npmrc-license.js
+var require_npmrc_license = __commonJS({
+  "../forge-plugin/lib/npmrc-license.js"(exports2, module2) {
+    var fs = require("node:fs");
+    var path2 = require("node:path");
+    var DIST_HOST = "registry.bigbrainforge.com";
+    var LEGACY_HOST = "npm.pkg.github.com";
+    var SCOPE_LINE = `@bigbrainforge:registry=https://${DIST_HOST}/npm/`;
+    function authLine(license) {
+      return `//${DIST_HOST}/npm/:_authToken=${license}`;
+    }
+    var DIST_AUTH_KEY = `//${DIST_HOST}/npm/`;
+    var LEGACY_AUTH_KEY = `//${LEGACY_HOST}/`;
+    var OWNED_SCOPE_TARGETS = /* @__PURE__ */ new Set([
+      `https://${DIST_HOST}/npm/`,
+      `https://${DIST_HOST}/npm`,
+      `https://${LEGACY_HOST}`,
+      `https://${LEGACY_HOST}/`
+    ]);
+    function isCommentLine(trimmed) {
+      return trimmed.startsWith("#") || trimmed.startsWith(";");
+    }
+    function ownsLine(trimmed) {
+      if (isCommentLine(trimmed)) return false;
+      const scopeMatch = trimmed.match(/^@bigbrainforge:registry=(.*)$/);
+      if (scopeMatch) {
+        return OWNED_SCOPE_TARGETS.has(scopeMatch[1].trim());
+      }
+      const m = trimmed.match(/^(.*):_authToken=/);
+      if (!m) return false;
+      const registry = m[1] ?? "";
+      return registry === DIST_AUTH_KEY || registry === LEGACY_AUTH_KEY;
+    }
+    function foreignScopeTargetOf(trimmed) {
+      if (trimmed.length === 0 || isCommentLine(trimmed)) return null;
+      const m = trimmed.match(/^@bigbrainforge:registry=(.*)$/);
+      return m ? m[1].trim() : null;
+    }
+    function partitionLines(src) {
+      const kept = [];
+      let replacedLegacy = false;
+      let foreignScopeTarget = null;
+      for (const raw of src.split("\n")) {
+        const trimmed = raw.trim();
+        if (trimmed.length > 0 && ownsLine(trimmed)) {
+          if (trimmed.includes(LEGACY_HOST) || trimmed.includes("FORGE_PACKAGE_TOKEN")) {
+            replacedLegacy = true;
+          }
+          continue;
+        }
+        const foreignTarget = foreignScopeTargetOf(trimmed);
+        if (foreignTarget !== null) foreignScopeTarget = foreignTarget;
+        kept.push(raw);
+      }
+      while (kept.length > 0 && kept[kept.length - 1] === "") kept.pop();
+      return { kept, replacedLegacy, foreignScopeTarget };
+    }
+    function applyNpmrcLicense(content, license) {
+      const src = String(content ?? "");
+      const { kept, replacedLegacy, foreignScopeTarget } = partitionLines(src);
+      const foreignScope = foreignScopeTarget !== null;
+      const linesToAdd = foreignScope ? [] : [SCOPE_LINE, authLine(license)];
+      const body = [...kept, ...linesToAdd, ""].join("\n");
+      const changed = body !== src;
+      const status = foreignScope ? "declined" : changed ? "seeded" : "already";
+      return { content: body, changed, replacedLegacy, foreignScope, foreignScopeTarget, status };
+    }
+    function writeNpmrcLicense2(license, io) {
+      const target = path2.join(io.homedir, ".npmrc");
+      let existing = "";
+      try {
+        existing = fs.readFileSync(target, "utf8");
+      } catch {
+      }
+      const result = applyNpmrcLicense(existing, license);
+      if (result.changed) {
+        fs.writeFileSync(target, result.content, { encoding: "utf8", mode: 384 });
+      }
+      try {
+        fs.chmodSync(target, 384);
+      } catch {
+      }
+      return { ...result, path: target };
+    }
+    module2.exports = { applyNpmrcLicense, writeNpmrcLicense: writeNpmrcLicense2, SCOPE_LINE, authLine, DIST_HOST };
+  }
+});
+
+// ../forge-plugin/lib/plugin-bundle.js
+var require_plugin_bundle = __commonJS({
+  "../forge-plugin/lib/plugin-bundle.js"(exports2, module2) {
+    var { createHash } = require("node:crypto");
+    var { execFileSync } = require("node:child_process");
+    var fs = require("node:fs");
+    var os2 = require("node:os");
+    var path2 = require("node:path");
+    var { renameWithRetry } = require_rename_with_retry();
+    var VERSION_RE = /^\d+\.\d+\.\d+$/;
+    function assertSafeVersion2(version) {
+      if (typeof version !== "string" || !VERSION_RE.test(version)) {
+        throw new Error(
+          `refusing to use manifest version ${JSON.stringify(version)} \u2014 it must be a plain semver-shaped string (digits.digits.digits) since it is used as a filesystem path segment. This looks like a corrupted or tampered distribution-plane response.`
+        );
+      }
+    }
+    function bundleRoot2(homeDir = os2.homedir()) {
+      return path2.join(homeDir, ".claude", "forge", "plugin-bundle");
+    }
+    function stagePath() {
+      return path2.resolve(__dirname, "..", "scripts", "stage.js");
+    }
+    function envFor(io) {
+      return io.homedir ? { ...process.env, HOME: io.homedir, USERPROFILE: io.homedir } : process.env;
+    }
+    function fetchTgzViaStage(manifest, io = {}) {
+      const tmp = fs.mkdtempSync(path2.join(os2.tmpdir(), "forge-bundle-"));
+      const out = path2.join(tmp, `${manifest.version}.tgz`);
+      try {
+        execFileSync(
+          process.execPath,
+          [
+            stagePath(),
+            "dist-fetch",
+            "--dist-path",
+            `/dist/plugin/${manifest.version}.tgz`,
+            "--output",
+            out
+          ],
+          { stdio: ["ignore", "pipe", "pipe"], timeout: 12e4, env: envFor(io) }
+        );
+        return fs.readFileSync(out);
+      } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+      }
+    }
+    function checkManifest(io = {}) {
+      const exec = io.execFileSync ?? execFileSync;
+      const tmp = fs.mkdtempSync(path2.join(os2.tmpdir(), "forge-manifest-"));
+      const out = path2.join(tmp, "manifest.json");
+      try {
+        exec(
+          process.execPath,
+          [stagePath(), "dist-fetch", "--dist-path", "/dist/plugin/manifest", "--output", out],
+          { stdio: ["ignore", "pipe", "pipe"], timeout: 15e3, env: envFor(io) }
+        );
+        const manifest = JSON.parse(fs.readFileSync(out, "utf8"));
+        if (!manifest?.version || !VERSION_RE.test(manifest.version) || !/^[0-9a-f]{64}$/.test(manifest?.sha256 ?? "")) {
+          return { ok: false, revoked: false, reason: "manifest missing version/sha256" };
+        }
+        return { ok: true, manifest };
+      } catch (err) {
+        const msg = String(err?.stderr ?? err?.message ?? err);
+        const revoked = /revoked or unknown|rejected this license/i.test(msg);
+        return { ok: false, revoked, reason: revoked ? "LICENSE_INVALID" : msg.split("\n")[0] };
+      } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+      }
+    }
+    function writeMarketplaceJson(root, version) {
+      const dir = path2.join(root, ".claude-plugin");
+      fs.mkdirSync(dir, { recursive: true });
+      const doc = {
+        name: "forge",
+        owner: { name: "Big Brain Forge" },
+        plugins: [
+          {
+            name: "forge",
+            source: `./${version}`,
+            description: "Forge for Claude Code \u2014 agentic orchestration for high-compliance environments."
+          }
+        ]
+      };
+      fs.writeFileSync(path2.join(dir, "marketplace.json"), `${JSON.stringify(doc, null, 2)}
+`);
+    }
+    function readInstalledVersion(root) {
+      let source;
+      try {
+        const mp = JSON.parse(
+          fs.readFileSync(path2.join(root, ".claude-plugin", "marketplace.json"), "utf8")
+        );
+        source = mp?.plugins?.[0]?.source;
+      } catch {
+        return null;
+      }
+      if (typeof source !== "string" || source.length === 0) return null;
+      const version = source.replace(/^\.\//, "");
+      try {
+        const pluginJson = JSON.parse(
+          fs.readFileSync(path2.join(root, version, ".claude-plugin", "plugin.json"), "utf8")
+        );
+        if (typeof pluginJson?.version === "string" && pluginJson.version.length > 0) {
+          return pluginJson.version;
+        }
+      } catch {
+      }
+      return version;
+    }
+    function readLiveVersionStamp(root) {
+      try {
+        return fs.readFileSync(path2.join(path2.dirname(root), "VERSION"), "utf8").trim() || null;
+      } catch {
+        return null;
+      }
+    }
+    function pruneOldVersions(root, keep = 2) {
+      const semver = /^\d+\.\d+\.\d+$/;
+      let entries;
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      const dirs = entries.filter((d) => d.isDirectory() && semver.test(d.name)).map((d) => d.name).sort((a, b) => {
+        const pa = a.split(".").map(Number);
+        const pb = b.split(".").map(Number);
+        return pa[0] - pb[0] || pa[1] - pb[1] || pa[2] - pb[2];
+      });
+      const liveVersion = readLiveVersionStamp(root);
+      const stale = dirs.slice(0, Math.max(0, dirs.length - keep)).filter((name) => name !== liveVersion);
+      for (const name of stale) {
+        fs.rmSync(path2.join(root, name), { recursive: true, force: true });
+      }
+    }
+    async function stageBundle2(manifest, io = {}) {
+      assertSafeVersion2(manifest?.version);
+      const homedir = io.homedir ?? os2.homedir();
+      const root = bundleRoot2(homedir);
+      const target = path2.join(root, manifest.version);
+      if (fs.existsSync(path2.join(target, ".claude-plugin", "plugin.json"))) {
+        writeMarketplaceJson(root, manifest.version);
+        return { staged: false, already: true, root, target };
+      }
+      const bytes = io.fetchTgz ? await io.fetchTgz(manifest) : fetchTgzViaStage(manifest, io);
+      const digest = createHash("sha256").update(bytes).digest("hex");
+      if (digest !== manifest.sha256) {
+        throw new Error(
+          `bundle sha256 mismatch for ${manifest.version} \u2014 refusing to unpack (expected the manifest digest; the download may be corrupt or tampered).`
+        );
+      }
+      const tmp = fs.mkdtempSync(path2.join(os2.tmpdir(), `forge-bundle-stage-${manifest.version}-`));
+      try {
+        const tgz = path2.join(tmp, "bundle.tgz");
+        fs.writeFileSync(tgz, bytes);
+        const dest = path2.join(tmp, "unpacked");
+        fs.mkdirSync(dest);
+        try {
+          execFileSync("tar", ["-xzf", tgz, "-C", dest, "--strip-components=1"], {
+            stdio: ["ignore", "pipe", "pipe"]
+          });
+        } catch (err) {
+          if (err?.code === "ENOENT") {
+            throw new Error("system `tar` was not found on this machine \u2014 cannot unpack the bundle");
+          }
+          throw new Error(`tar failed to unpack the bundle: ${err?.stderr ?? err?.message ?? err}`);
+        }
+        if (!fs.existsSync(path2.join(dest, ".claude-plugin", "plugin.json"))) {
+          throw new Error("unpacked bundle has no .claude-plugin/plugin.json \u2014 not a plugin bundle");
+        }
+        fs.mkdirSync(root, { recursive: true });
+        try {
+          renameWithRetry(dest, target, io.doRename);
+        } catch (err) {
+          if (err?.code === "EXDEV") {
+            throw new Error(
+              `could not publish the staged bundle: the OS temp directory and ${root} are on different filesystems (EXDEV) \u2014 set TMPDIR (or TMP/TEMP on Windows) to a path on the same volume as ~/.claude/forge and retry. A copy-based fallback was deliberately not used here because it cannot preserve this operation's atomicity guarantee.`
+            );
+          }
+          throw err;
+        }
+      } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+      }
+      writeMarketplaceJson(root, manifest.version);
+      pruneOldVersions(root);
+      return { staged: true, already: false, root, target };
+    }
+    module2.exports = {
+      bundleRoot: bundleRoot2,
+      checkManifest,
+      readInstalledVersion,
+      stageBundle: stageBundle2,
+      writeMarketplaceJson,
+      pruneOldVersions,
+      assertSafeVersion: assertSafeVersion2,
+      VERSION_RE
+    };
+  }
+});
+
+// ../forge-plugin/lib/windows-shell-quote.js
+var require_windows_shell_quote = __commonJS({
+  "../forge-plugin/lib/windows-shell-quote.js"(exports2, module2) {
+    function quoteForWindowsShell(arg) {
+      if (typeof arg !== "string") {
+        throw new TypeError("quoteForWindowsShell expects a string");
+      }
+      if (arg.length === 0) {
+        return '""';
+      }
+      if (!/[\s"&|<>^%]/.test(arg)) {
+        return arg;
+      }
+      const escaped = arg.replace(/(\\*)"/g, '$1$1""').replace(/(\\+)$/, "$1$1");
+      return `"${escaped}"`;
+    }
+    function buildWindowsCmdArgs(claudeCmd, argv) {
+      const commandLine = [claudeCmd, ...argv].map(quoteForWindowsShell).join(" ");
+      return ["/d", "/s", "/c", `"${commandLine}"`];
+    }
+    module2.exports = { quoteForWindowsShell, buildWindowsCmdArgs };
+  }
+});
+
+// ../forge-plugin/lib/exec-cli.js
+var require_exec_cli = __commonJS({
+  "../forge-plugin/lib/exec-cli.js"(exports2, module2) {
+    var { execFileSync, spawnSync: spawnSync2 } = require("node:child_process");
+    var { existsSync } = require("node:fs");
+    var { join } = require("node:path");
+    var { buildWindowsCmdArgs } = require_windows_shell_quote();
+    var DIRECT_EXTS = [".exe", ".com"];
+    var SHIM_EXTS = [".cmd", ".bat"];
+    function classifyWindowsCommand(cmd, env = process.env) {
+      const lower = cmd.toLowerCase();
+      const extMatch = /\.[^.\\/]+$/.exec(lower);
+      if (extMatch) {
+        if (DIRECT_EXTS.includes(extMatch[0])) return { kind: "direct", path: cmd };
+        if (SHIM_EXTS.includes(extMatch[0])) return { kind: "shim" };
+        return { kind: "shim" };
+      }
+      if (/[\\/]/.test(cmd)) {
+        for (const ext of pathExts(env)) {
+          if (existsSync(cmd + ext)) {
+            return DIRECT_EXTS.includes(ext) ? { kind: "direct", path: cmd + ext } : { kind: "shim" };
+          }
+        }
+        return { kind: "unknown" };
+      }
+      const dirs = (env.PATH || env.Path || "").split(";").filter(Boolean);
+      for (const dir of dirs) {
+        for (const ext of pathExts(env)) {
+          const candidate = join(dir, cmd + ext);
+          if (existsSync(candidate)) {
+            return DIRECT_EXTS.includes(ext) ? { kind: "direct", path: candidate } : { kind: "shim" };
+          }
+        }
+      }
+      return { kind: "unknown" };
+    }
+    function pathExts(env) {
+      return (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((e) => e.toLowerCase());
+    }
+    function resolveSpawn2(platform, cmd, argv = [], opts = {}, env = process.env) {
+      if (platform !== "win32") {
+        return { cmd, argv, opts };
+      }
+      const target = classifyWindowsCommand(cmd, env);
+      if (target.kind === "direct") {
+        return {
+          cmd: target.path,
+          argv,
+          opts: { ...opts, shell: false }
+        };
+      }
+      return {
+        cmd: "cmd.exe",
+        argv: buildWindowsCmdArgs(cmd, argv),
+        opts: {
+          ...opts,
+          shell: false,
+          windowsVerbatimArguments: true
+        }
+      };
+    }
+    function execCli(cmd, argv = [], opts = {}) {
+      const r = resolveSpawn2(process.platform, cmd, argv, opts);
+      return execFileSync(r.cmd, r.argv, r.opts);
+    }
+    function spawnCli(cmd, argv = [], opts = {}) {
+      const r = resolveSpawn2(process.platform, cmd, argv, opts);
+      return spawnSync2(r.cmd, r.argv, r.opts);
+    }
+    var winPath = require("node:path").win32;
+    var WINDOWS_PATH_DELIMITER = ";";
+    var WINDOWS_BASH_SHIM_DIRS = /* @__PURE__ */ new Set(["system32", "windowsapps"]);
+    function isWindowsBashShim(candidate) {
+      if (!candidate) return false;
+      const leaf = winPath.basename(winPath.dirname(String(candidate)));
+      return WINDOWS_BASH_SHIM_DIRS.has(leaf.toLowerCase());
+    }
+    function bashFromPath(env, exists) {
+      for (const raw of (env.PATH || env.Path || "").split(WINDOWS_PATH_DELIMITER)) {
+        const dir = raw.trim().replace(/^"|"$/g, "");
+        if (!dir) continue;
+        const candidate = winPath.join(dir, "bash.exe");
+        if (isWindowsBashShim(candidate)) continue;
+        if (exists(candidate)) return candidate;
+      }
+      return null;
+    }
+    var MSYS_BIN_RELATIVE = [["bin"], ["usr", "bin"]];
+    function bashFromKnownInstall(env, exists) {
+      const roots = [
+        env.GIT_INSTALL_ROOT,
+        env.ProgramFiles && winPath.join(env.ProgramFiles, "Git"),
+        env.ProgramW6432 && winPath.join(env.ProgramW6432, "Git"),
+        env["ProgramFiles(x86)"] && winPath.join(env["ProgramFiles(x86)"], "Git"),
+        env.LOCALAPPDATA && winPath.join(env.LOCALAPPDATA, "Programs", "Git"),
+        "C:\\msys64"
+      ].filter(Boolean);
+      for (const root of roots) {
+        for (const rel of MSYS_BIN_RELATIVE) {
+          const candidate = winPath.join(root, ...rel, "bash.exe");
+          if (exists(candidate)) return candidate;
+        }
+      }
+      return null;
+    }
+    function bashFromGitExecPath(exists, runGitExecPath) {
+      const out = runGitExecPath();
+      if (!out) return null;
+      let dir = winPath.normalize(String(out).trim().split("/").join("\\"));
+      for (let i = 0; i < 8; i++) {
+        for (const rel of MSYS_BIN_RELATIVE) {
+          const candidate = winPath.join(dir, ...rel, "bash.exe");
+          if (exists(candidate)) return candidate;
+        }
+        const parent = winPath.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+      return null;
+    }
+    function defaultRunGitExecPath() {
+      try {
+        const r = spawnCli("git", ["--exec-path"], { encoding: "utf8" });
+        return r.status === 0 ? r.stdout : null;
+      } catch {
+        return null;
+      }
+    }
+    function resolveBash({
+      platform = process.platform,
+      env = process.env,
+      exists = existsSync,
+      runGitExecPath = defaultRunGitExecPath
+    } = {}) {
+      if (platform !== "win32") return { command: "bash", source: "posix", shimOnly: false };
+      const fromPath = bashFromPath(env, exists);
+      if (fromPath) return { command: fromPath, source: "path", shimOnly: false };
+      const fromInstall = bashFromKnownInstall(env, exists);
+      if (fromInstall) return { command: fromInstall, source: "git-install", shimOnly: false };
+      const fromGit = bashFromGitExecPath(exists, runGitExecPath);
+      if (fromGit) return { command: fromGit, source: "git-exec-path", shimOnly: false };
+      const shimOnly = (env.PATH || env.Path || "").split(WINDOWS_PATH_DELIMITER).map((d) => d.trim().replace(/^"|"$/g, "")).filter(Boolean).some((dir) => {
+        const candidate = winPath.join(dir, "bash.exe");
+        return isWindowsBashShim(candidate) && exists(candidate);
+      });
+      return { command: null, source: "none", shimOnly };
+    }
+    function msysBinDirsFrom(bashPath) {
+      const bashDir = winPath.dirname(bashPath);
+      const dirs = [bashDir];
+      let root = bashDir;
+      for (let level = 0; level < MSYS_BIN_RELATIVE.length; level++) {
+        const parent = winPath.dirname(root);
+        if (parent === root) break;
+        root = parent;
+        for (const rel of MSYS_BIN_RELATIVE) {
+          const dir = winPath.join(root, ...rel);
+          if (!dirs.includes(dir)) dirs.push(dir);
+        }
+      }
+      return dirs;
+    }
+    function resolveMsysToolDirs({
+      tools = ["bash"],
+      platform = process.platform,
+      env = process.env,
+      exists = existsSync,
+      runGitExecPath = defaultRunGitExecPath
+    } = {}) {
+      if (platform !== "win32") {
+        return {
+          platform,
+          bash: "bash",
+          source: "posix",
+          shimOnly: false,
+          dirs: [],
+          resolved: {},
+          missing: []
+        };
+      }
+      const bash = resolveBash({ platform, env, exists, runGitExecPath });
+      if (!bash.command) {
+        return {
+          platform,
+          bash: null,
+          source: bash.source,
+          shimOnly: bash.shimOnly,
+          dirs: [],
+          resolved: {},
+          missing: [...tools]
+        };
+      }
+      const searchDirs = msysBinDirsFrom(bash.command);
+      const dirs = [];
+      const resolved = {};
+      const missing = [];
+      for (const tool of tools) {
+        const exe = /\.exe$/i.test(tool) ? tool : `${tool}.exe`;
+        const dir = searchDirs.find((d) => exists(winPath.join(d, exe)));
+        if (!dir) {
+          missing.push(tool);
+          continue;
+        }
+        resolved[tool] = winPath.join(dir, exe);
+        if (!dirs.includes(dir)) dirs.push(dir);
+      }
+      return {
+        platform,
+        bash: bash.command,
+        source: bash.source,
+        shimOnly: false,
+        dirs,
+        resolved,
+        missing
+      };
+    }
+    module2.exports = {
+      execCli,
+      spawnCli,
+      resolveSpawn: resolveSpawn2,
+      classifyWindowsCommand,
+      resolveBash,
+      isWindowsBashShim,
+      resolveMsysToolDirs
+    };
+  }
+});
+
+// src/setup.js
+var os = require("node:os");
+var path = require("node:path");
+var { spawnSync } = require("node:child_process");
+var { writeLicense } = require_license();
+var { discoverInstance, isSecureUrl } = require_discover_instance();
+var { writeNpmrcLicense } = require_npmrc_license();
+var {
+  stageBundle,
+  bundleRoot,
+  assertSafeVersion
+} = require_plugin_bundle();
+var { resolveSpawn } = require_exec_cli();
+var LICENSE_RE = /^forge_lic_[0-9A-Za-z]{43}$/;
+var DEFAULT_LICENSING_URL = "https://licensing.bigbrainforge.com";
+var DEFAULT_DIST_URL = "https://registry.bigbrainforge.com";
+var RERUN_SETUP_CMD = "npx --@bigbrainforge:registry=https://registry.npmjs.org @bigbrainforge/setup";
+function runShim(io, cmd, args) {
+  const platform = io.platform ?? process.platform;
+  const env = io.env ?? process.env;
+  const resolved = resolveSpawn(platform, cmd, args, {}, env);
+  return io.run(resolved.cmd, resolved.argv, resolved.opts);
+}
+function errMessage(err) {
+  return err && err.message ? err.message : String(err);
+}
+function defaultIo() {
+  return {
+    homedir: os.homedir(),
+    env: process.env,
+    print: (l) => process.stdout.write(`${l}
+`),
+    promptHidden: async (q) => {
+      const readline = require("node:readline");
+      return new Promise((res) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const orig = rl._writeToOutput.bind(rl);
+        rl._writeToOutput = (s) => s.includes("\n") || s === q ? orig(s) : orig("");
+        process.stdout.write(q);
+        rl.question("", (a) => {
+          rl.close();
+          process.stdout.write("\n");
+          res(a.trim());
+        });
+      });
+    },
+    fetch: (url, opts) => globalThis.fetch(url, opts),
+    run: (cmd, args = [], opts = {}) => {
+      const { stdio, ...rest } = opts;
+      const r = spawnSync(cmd, args, {
+        encoding: "utf8",
+        stdio: stdio ?? ["ignore", "pipe", "pipe"],
+        ...rest
+      });
+      return { status: r.status, stdout: r.stdout || "", stderr: r.stderr || "", error: r.error };
+    }
+  };
+}
+function fail(io, tier, message, fix) {
+  io.print("");
+  io.print(`\u2717 [${tier}] ${message}`);
+  if (fix) io.print(`  fix: ${fix}`);
+  return 1;
+}
+async function runSetup(argv, io = defaultIo()) {
+  const args = argv.filter((a) => !a.startsWith("--"));
+  const acceptNewInstance = argv.includes("--accept-new-instance");
+  const tarProbe = io.run("tar", ["--version"]);
+  if (tarProbe.error || tarProbe.status !== 0) {
+    return fail(
+      io,
+      "machine",
+      "the tar tool is missing (needed to unpack the plugin bundle)",
+      "macOS/Linux: install tar via your package manager; Windows 10+ ships it as tar.exe"
+    );
+  }
+  let license = args[0] ?? "";
+  if (!license) license = await io.promptHidden("Paste your Forge license: ");
+  if (!LICENSE_RE.test(license)) {
+    return fail(
+      io,
+      "credential",
+      "that license is not the right shape (expected forge_lic_ + 43 characters) \u2014 it may be malformed or truncated",
+      "re-paste it exactly as delivered, or contact your Forge administrator"
+    );
+  }
+  const wrote = writeLicense(license, { homedir: io.homedir, env: io.env });
+  if (!wrote.ok) {
+    return fail(
+      io,
+      "credential",
+      `could not store the license: ${wrote.error}`,
+      `fix the named problem (usually permissions on ~/.claude/forge), then rerun: ${RERUN_SETUP_CMD}`
+    );
+  }
+  io.print(`\u2713 license stored (${wrote.path})`);
+  const licensingUrl = io.env.FORGE_LICENSING_URL || DEFAULT_LICENSING_URL;
+  const discoveryFetch = async (url, opts) => {
+    const res = await io.fetch(url, opts);
+    return { ...res, ok: res.ok ?? (res.status >= 200 && res.status < 300) };
+  };
+  const discovered = await discoverInstance({
+    homedir: io.homedir,
+    env: io.env,
+    fetchImpl: discoveryFetch,
+    forceDiscovery: true,
+    acceptNewInstance
+  });
+  if (!discovered.ok) {
+    return fail(
+      io,
+      "instance discovery",
+      discovered.hint,
+      discovered.reason === "pin_conflict" ? (
+        // Non-blocking review residual (round 2): a pin conflict only ever
+        // fires on a machine that was ALREADY pinned by a prior successful
+        // run — i.e. exactly the state most likely to have already seeded
+        // ~/.npmrc, so this rerun needs the same registry-override form
+        // as the other three "rerun setup" hints (C5).
+        `rerun with --accept-new-instance only if your org really moved instances: ${RERUN_SETUP_CMD} --accept-new-instance`
+      ) : `check network egress to ${licensingUrl} (it must be on your allowlist)`
+    );
+  }
+  io.print(`\u2713 instance pinned: ${discovered.instance_url} (${discovered.deployment_model})`);
+  let npmrc;
+  try {
+    npmrc = writeNpmrcLicense(license, { homedir: io.homedir, env: io.env });
+  } catch (err) {
+    return fail(
+      io,
+      "package plane",
+      `could not seed npm auth: ${errMessage(err)}`,
+      `check that ~/.npmrc is a writable file (not a directory) and this account has permission, then rerun: ${RERUN_SETUP_CMD}`
+    );
+  }
+  if (npmrc.status === "declined") {
+    const legacyNote = npmrc.replacedLegacy ? " (a legacy npm.pkg.github.com credential line found alongside it was removed)" : "";
+    io.print(
+      npmrc.foreignScopeTarget === "" ? `! npm NOT seeded \u2014 ~/.npmrc has a malformed @bigbrainforge:registry= line (no value). Fix or remove that line, then rerun setup; otherwise no action is needed.${legacyNote}` : `! npm NOT seeded \u2014 @bigbrainforge:registry already points at ${npmrc.foreignScopeTarget} (an enterprise proxy or other custom config). If that isn't your organization's proxy, remove that line from ~/.npmrc and rerun setup; otherwise no action is needed.${legacyNote}`
+    );
+  } else {
+    io.print(
+      npmrc.status === "seeded" ? `\u2713 npm seeded (${npmrc.path})${npmrc.replacedLegacy ? " \u2014 legacy GitHub Packages lines replaced" : ""}` : `\u2713 npm already seeded (${npmrc.path}) \u2014 no change needed`
+    );
+  }
+  const distUrl = io.env.FORGE_DIST_URL || DEFAULT_DIST_URL;
+  if (!isSecureUrl(distUrl)) {
+    return fail(
+      io,
+      "distribution plane",
+      `FORGE_DIST_URL must use https:// (got ${distUrl}) \u2014 refusing to send the license to an insecure host`,
+      "unset FORGE_DIST_URL to use the default, or point it at an https:// endpoint (plain http:// is allowed only for loopback: 127.0.0.1, localhost, ::1)"
+    );
+  }
+  const auth = { headers: { authorization: `Bearer ${license}` } };
+  let mRes;
+  try {
+    mRes = await io.fetch(`${distUrl}/dist/plugin/manifest`, auth);
+  } catch (err) {
+    return fail(
+      io,
+      "distribution plane",
+      `could not reach ${distUrl}: ${errMessage(err)}`,
+      `check network egress to ${distUrl} (it must be on your allowlist)`
+    );
+  }
+  if (mRes.status === 401) {
+    return fail(
+      io,
+      "distribution plane",
+      "this license was reported revoked or unknown",
+      "contact your Forge administrator for a current license"
+    );
+  }
+  if (mRes.status !== 200) {
+    return fail(
+      io,
+      "distribution plane",
+      `manifest fetch failed (HTTP ${mRes.status})`,
+      `check network egress to ${distUrl}`
+    );
+  }
+  let manifest;
+  try {
+    manifest = await mRes.json();
+  } catch (err) {
+    return fail(
+      io,
+      "distribution plane",
+      `manifest response was not valid JSON: ${errMessage(err)}`,
+      `check network egress to ${distUrl} \u2014 a captive portal or proxy may have intercepted the response`
+    );
+  }
+  try {
+    assertSafeVersion(manifest?.version);
+  } catch (err) {
+    return fail(
+      io,
+      "distribution plane",
+      `manifest response was malformed: ${errMessage(err)}`,
+      `the download may be corrupted or tampered \u2014 rerun to retry: ${RERUN_SETUP_CMD} (if it persists, contact your Forge administrator)`
+    );
+  }
+  let tRes;
+  try {
+    tRes = await io.fetch(`${distUrl}/dist/plugin/${manifest.version}.tgz`, auth);
+  } catch (err) {
+    return fail(
+      io,
+      "distribution plane",
+      `could not reach ${distUrl}: ${errMessage(err)}`,
+      `check network egress to ${distUrl} (it must be on your allowlist)`
+    );
+  }
+  if (tRes.status !== 200) {
+    return fail(
+      io,
+      "distribution plane",
+      `bundle download failed (HTTP ${tRes.status})`,
+      `check network egress to ${distUrl}`
+    );
+  }
+  let staged;
+  try {
+    const bytes = Buffer.from(await tRes.arrayBuffer());
+    staged = await stageBundle(
+      { version: manifest.version, sha256: manifest.sha256, url: manifest.url },
+      { homedir: io.homedir, fetchTgz: async () => bytes }
+    );
+  } catch (err) {
+    return fail(
+      io,
+      "distribution plane",
+      `could not stage the plugin bundle: ${errMessage(err)}`,
+      `the download may be corrupted or tampered \u2014 rerun to retry: ${RERUN_SETUP_CMD} (if it persists, contact your Forge administrator)`
+    );
+  }
+  io.print(`\u2713 plugin bundle ${manifest.version} verified (sha256) and staged at ${staged.target}`);
+  const root = bundleRoot(io.homedir);
+  const addRes = runShim(io, "claude", ["plugin", "marketplace", "add", root]);
+  const installRes = addRes.status === 0 ? runShim(io, "claude", ["plugin", "install", "forge@forge"]) : addRes;
+  const alreadyRegistered = addRes.status === 0 && installRes.status !== 0 && /already installed|already exists/i.test(
+    `${installRes.stdout || ""}
+${installRes.stderr || ""}`
+  );
+  if (addRes.status === 0 && installRes.status === 0) {
+    io.print("\u2713 plugin installed from the local Forge marketplace");
+  } else if (alreadyRegistered) {
+    io.print("\u2713 plugin already installed from the local Forge marketplace \u2014 nothing to do");
+  } else {
+    io.print("");
+    io.print("! Claude Code CLI not reachable from this shell \u2014 run these two commands yourself:");
+    io.print("");
+    io.print(`    claude plugin marketplace add "${root}"`);
+    io.print("    claude plugin install forge@forge");
+    io.print("");
+  }
+  const bundledBootstrap = path.join(staged.target, "scripts", "bootstrap.js");
+  io.print("Handing off to the Forge plugin bootstrap (server check + issue tracker)\u2026");
+  const hand = io.run(process.execPath, [bundledBootstrap], { stdio: "inherit" });
+  if (hand.status !== 0) {
+    return fail(
+      io,
+      "plugin bootstrap",
+      "the plugin bootstrap did not finish",
+      `rerun it yourself: node "${bundledBootstrap}"`
+    );
+  }
+  io.print("");
+  io.print("Done. Open Claude Code \u2014 Forge is ready.");
+  return 0;
+}
+module.exports = { runSetup, LICENSE_RE, defaultIo, RERUN_SETUP_CMD };
+if (require.main === module) {
+  runSetup(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
+    process.stderr.write(`
+\u2717 [unexpected] ${errMessage(err)}
+`);
+    process.stderr.write(
+      "  fix: this is unexpected \u2014 please report it (including this message) to your Forge administrator\n"
+    );
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@bigbrainforge/setup",
+  "version": "3.18.0",
+  "description": "Forge workstation setup — paste one license, get a working Forge install.",
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/bigbrainforge/forge",
+  "bin": { "forge-setup": "dist/setup.cjs" },
+  "files": ["dist/", "README.md"],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test \"test/*.test.js\""
+  },
+  "engines": { "node": ">=24.18.1", "pnpm": ">=11.0.0" },
+  "publishConfig": { "registry": "https://registry.npmjs.org", "access": "public" },
+  "devDependencies": { "esbuild": "0.28.1" }
+}