forge-remote 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "forge-remote",
+  "version": "0.1.0",
+  "description": "Desktop relay for Forge Remote — monitor and control Claude Code sessions from your phone",
+  "type": "module",
+  "license": "AGPL-3.0",
+  "author": "Daniel Wendel <daniel@ironforgeapps.com> (https://ironforgeapps.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IronForgeApps/forge-remote.git"
+  },
+  "bugs": {
+    "url": "https://github.com/IronForgeApps/forge-remote/issues"
+  },
+  "homepage": "https://github.com/IronForgeApps/forge-remote#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "forge-remote": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/cli.js start",
+    "pair": "node src/cli.js pair"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "mobile",
+    "remote",
+    "relay",
+    "firebase",
+    "developer-tools"
+  ],
+  "dependencies": {
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "firebase-admin": "^13.0.0",
+    "localtunnel": "^2.0.2",
+    "qrcode-terminal": "^0.12.0",
+    "uuid": "^11.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+// Forge Remote Relay — Desktop Agent for Forge Remote
+// Copyright (c) 2025-2026 Iron Forge Apps
+// Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
+// AGPL-3.0 License — See LICENSE
+
+import { program } from "commander";
+import { execSync } from "child_process";
+import { readFileSync, existsSync, writeFileSync } from "fs";
+import { join } from "path";
+import { hostname, homedir } from "os";
+import qrcode from "qrcode-terminal";
+
+import { runInit } from "./init.js";
+import { initFirebase } from "./firebase.js";
+import {
+  registerDesktop,
+  markOffline,
+  startHeartbeat,
+  createPairingToken,
+  updateProjects,
+  getPlatformName,
+  getDesktopId,
+} from "./desktop.js";
+import {
+  listenForCommands,
+  shutdownAllSessions,
+  cleanupOrphanedSessions,
+} from "./session-manager.js";
+import { stopAllTunnels } from "./tunnel-manager.js";
+import { stopAllCaptures } from "./screenshot-manager.js";
+import { scanProjects } from "./project-scanner.js";
+import * as log from "./logger.js";
+
+program
+  .name("forge-remote")
+  .description("Desktop relay for Forge Remote")
+  .version("0.1.0");
+
+/**
+ * Load Firebase web SDK config.
+ * Tries: 1) cached file from `init`, 2) Firebase CLI `apps:sdkconfig`.
+ */
+function loadSdkConfig() {
+  const forgeDir = join(homedir(), ".forge-remote");
+  const cachedPath = join(forgeDir, "sdk-config.json");
+
+  // 1. Try cached config (saved by `init`).
+  if (existsSync(cachedPath)) {
+    try {
+      return JSON.parse(readFileSync(cachedPath, "utf-8"));
+    } catch {
+      // Fall through to CLI.
+    }
+  }
+
+  // 2. Get project ID from service account key.
+  const saPath = join(forgeDir, "service-account.json");
+  if (!existsSync(saPath)) return null;
+
+  let projectId;
+  try {
+    const sa = JSON.parse(readFileSync(saPath, "utf-8"));
+    projectId = sa.project_id;
+  } catch {
+    return null;
+  }
+
+  // 3. Fetch via Firebase CLI.
+  try {
+    const output = execSync(
+      `firebase apps:sdkconfig web --project ${projectId}`,
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+    );
+
+    const parse = (field) => {
+      const m = output.match(new RegExp(`${field}:\\s*"([^"]+)"`));
+      return m ? m[1] : null;
+    };
+
+    const config = {
+      apiKey: parse("apiKey"),
+      authDomain: parse("authDomain"),
+      projectId: parse("projectId"),
+      storageBucket: parse("storageBucket"),
+      messagingSenderId: parse("messagingSenderId"),
+      appId: parse("appId"),
+    };
+
+    if (!config.apiKey || !config.projectId) return null;
+
+    // Cache for next time.
+    writeFileSync(cachedPath, JSON.stringify(config, null, 2));
+    return config;
+  } catch {
+    return null;
+  }
+}
+
+program
+  .command("start")
+  .description(
+    "Start the desktop relay (register, heartbeat, listen for commands)",
+  )
+  .action(async () => {
+    initFirebase();
+    const desktopId = await registerDesktop();
+
+    // Scan and register projects.
+    const projects = await scanProjects();
+    await updateProjects(desktopId, projects);
+
+    // Clean up any orphaned sessions from a previous relay run.
+    await cleanupOrphanedSessions(desktopId);
+
+    const heartbeat = startHeartbeat(desktopId);
+
+    listenForCommands(desktopId);
+
+    // Print startup banner.
+    log.banner(hostname(), getPlatformName(), desktopId, projects.length);
+
+    // Graceful shutdown with timeout so Ctrl+C always works.
+    let shuttingDown = false;
+    const cleanup = async () => {
+      if (shuttingDown) {
+        log.info("Force quitting...");
+        process.exit(1);
+      }
+      shuttingDown = true;
+
+      log.info("Shutting down relay...");
+      clearInterval(heartbeat);
+
+      // Give cleanup 5 seconds, then force exit.
+      const forceExit = setTimeout(() => {
+        log.info("Cleanup timed out. Force quitting.");
+        process.exit(1);
+      }, 5000);
+
+      try {
+        await shutdownAllSessions();
+        stopAllTunnels();
+        stopAllCaptures();
+        await markOffline(desktopId);
+        log.success("Desktop marked offline. Goodbye!");
+      } catch (e) {
+        log.error(`Cleanup error: ${e.message}`);
+      }
+
+      clearTimeout(forceExit);
+      process.exit(0);
+    };
+
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  });
+
+program
+  .command("pair")
+  .description("Generate a pairing QR code for the mobile app")
+  .action(async () => {
+    initFirebase();
+    const desktopId = await registerDesktop();
+
+    // Build the BYOF-compatible QR payload with Firebase SDK config.
+    const sdkConfig = loadSdkConfig();
+    if (!sdkConfig) {
+      console.error("\nCould not load Firebase SDK config.");
+      console.error(
+        "Run `forge-remote init` first, or ensure the Firebase CLI is installed.\n",
+      );
+      process.exit(1);
+    }
+
+    const pairingData = JSON.stringify({
+      v: 1,
+      firebase: {
+        apiKey: sdkConfig.apiKey,
+        projectId: sdkConfig.projectId,
+        appId: sdkConfig.appId,
+        messagingSenderId: sdkConfig.messagingSenderId,
+        storageBucket: sdkConfig.storageBucket,
+      },
+      desktop: {
+        id: desktopId,
+        hostname: hostname(),
+        platform: getPlatformName(),
+      },
+    });
+
+    console.log("\n=== Forge Remote Pairing ===\n");
+    console.log("Scan this QR code with the Forge Remote app:\n");
+    qrcode.generate(pairingData, { small: true });
+
+    console.log("\nRaw pairing data (for manual entry):\n");
+    console.log(pairingData);
+    console.log();
+  });
+
+program
+  .command("init")
+  .description("Set up Firebase project and generate pairing QR code")
+  .option(
+    "--project-id <id>",
+    "Custom Firebase project ID (default: forge-remote-<hostname>)",
+  )
+  .action(async (opts) => {
+    await runInit({ projectId: opts.projectId });
+  });
+
+program.parse();

package/src/desktop.js

@@ -0,0 +1,121 @@
+import { getDb, FieldValue, Timestamp } from "./firebase.js";
+import { hostname, platform } from "os";
+import { v4 as uuidv4 } from "uuid";
+import * as log from "./logger.js";
+
+/**
+ * Register or update this desktop in Firestore.
+ * Returns the desktop document ID.
+ */
+export async function registerDesktop() {
+  const db = getDb();
+  const desktopId = getDesktopId();
+
+  const desktopRef = db.collection("desktops").doc(desktopId);
+  const doc = await desktopRef.get();
+
+  const platformName = getPlatformName();
+
+  if (doc.exists) {
+    await desktopRef.update({
+      status: "online",
+      lastHeartbeat: FieldValue.serverTimestamp(),
+      platform: platformName,
+      hostname: hostname(),
+    });
+  } else {
+    await desktopRef.set({
+      ownerUid: "", // Will be set during pairing.
+      hostname: hostname(),
+      platform: platformName,
+      status: "online",
+      lastHeartbeat: FieldValue.serverTimestamp(),
+      projects: [],
+      createdAt: FieldValue.serverTimestamp(),
+    });
+  }
+
+  console.log(`Desktop registered: ${desktopId} (${hostname()})`);
+  return desktopId;
+}
+
+/**
+ * Mark desktop as offline.
+ */
+export async function markOffline(desktopId) {
+  const db = getDb();
+  await db.collection("desktops").doc(desktopId).update({
+    status: "offline",
+    lastHeartbeat: FieldValue.serverTimestamp(),
+  });
+}
+
+/**
+ * Start a heartbeat interval that updates lastHeartbeat every 30s.
+ */
+export function startHeartbeat(desktopId) {
+  const interval = setInterval(async () => {
+    try {
+      const db = getDb();
+      await db.collection("desktops").doc(desktopId).update({
+        lastHeartbeat: FieldValue.serverTimestamp(),
+      });
+      log.heartbeat();
+    } catch (e) {
+      log.error(`Heartbeat failed: ${e.message}`);
+    }
+  }, 30_000);
+
+  return interval;
+}
+
+/**
+ * Update the project list for this desktop.
+ */
+export async function updateProjects(desktopId, projects) {
+  const db = getDb();
+  await db.collection("desktops").doc(desktopId).update({ projects });
+}
+
+/**
+ * Create a pairing token for this desktop.
+ */
+export async function createPairingToken(desktopId) {
+  const db = getDb();
+  const tokenId = uuidv4().slice(0, 8); // Short code for easy manual entry.
+
+  await db
+    .collection("pairingTokens")
+    .doc(tokenId)
+    .set({
+      desktopId,
+      hostname: hostname(),
+      platform: getPlatformName(),
+      token: tokenId,
+      expiresAt: Timestamp.fromDate(new Date(Date.now() + 10 * 60 * 1000)), // 10 min
+      used: false,
+      claimedBy: null,
+      createdAt: FieldValue.serverTimestamp(),
+    });
+
+  return tokenId;
+}
+
+/**
+ * Get a stable desktop ID based on hostname.
+ * In production you'd store this in a config file.
+ */
+export function getDesktopId() {
+  // Use a consistent ID so the same machine always maps to the same doc.
+  const name = hostname()
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "-");
+  return `desktop-${name}`;
+}
+
+export function getPlatformName() {
+  const p = platform();
+  if (p === "darwin") return "macos";
+  if (p === "win32") return "windows";
+  return "linux";
+}

package/src/firebase.js

@@ -0,0 +1,46 @@
+import { initializeApp, cert } from "firebase-admin/app";
+import { getFirestore, FieldValue, Timestamp } from "firebase-admin/firestore";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+let db;
+
+/**
+ * Initialize Firebase Admin SDK.
+ * Looks for a service account key at:
+ *   1. FORGE_REMOTE_SA_KEY env var
+ *   2. ~/.forge-remote/service-account.json
+ */
+export function initFirebase() {
+  const envPath = process.env.FORGE_REMOTE_SA_KEY;
+  const defaultPath = join(homedir(), ".forge-remote", "service-account.json");
+  const keyPath = envPath || defaultPath;
+
+  if (!existsSync(keyPath)) {
+    console.error(`\nFirebase service account key not found at: ${keyPath}`);
+    console.error("Download it from:");
+    console.error(
+      "  https://console.firebase.google.com/project/forge-remote/settings/serviceaccounts/adminsdk",
+    );
+    console.error(`Then save it to: ${defaultPath}\n`);
+    process.exit(1);
+  }
+
+  const serviceAccount = JSON.parse(readFileSync(keyPath, "utf-8"));
+
+  initializeApp({
+    credential: cert(serviceAccount),
+  });
+
+  db = getFirestore();
+  return db;
+}
+
+export function getDb() {
+  if (!db)
+    throw new Error("Firebase not initialized. Call initFirebase() first.");
+  return db;
+}
+
+export { FieldValue, Timestamp };