forge-remote 0.1.13 → 0.1.15

package/firestore.rules

@@ -37,6 +37,14 @@ service cloud.firestore {
         allow create: if isSignedIn();
         allow update: if isSignedIn();
       }
+
+      // ---- Webhooks (subcollection) ----
+      match /webhooks/{webhookId} {
+        allow read: if isSignedIn();
+        allow create: if isSignedIn();
+        allow update: if isSignedIn();
+        allow delete: if isSignedIn();
+      }
     }
 
     // ---- Sessions ----

package/package.json

@@ -1,18 +1,11 @@
 {
   "name": "forge-remote",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Desktop relay for Forge Remote — monitor and control Claude Code sessions from your phone",
   "type": "module",
   "license": "UNLICENSED",
   "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",
+  "homepage": "https://forgeremote.com",
   "engines": {
     "node": ">=18.0.0"
   },

package/src/cli.js

@@ -30,7 +30,10 @@ import {
 import { stopAllTunnels } from "./tunnel-manager.js";
 import { stopAllCaptures } from "./screenshot-manager.js";
 import { scanProjects } from "./project-scanner.js";
+import { startWebhookServer, stopWebhookServer } from "./webhook-server.js";
+import { watchWebhookConfigs, stopWatching } from "./webhook-watcher.js";
 import * as log from "./logger.js";
+import { checkForUpdate } from "./update-checker.js";
 
 program
   .name("forge-remote")
@@ -126,6 +129,7 @@ program
     "Start the desktop relay (register, heartbeat, listen for commands)",
   )
   .action(async () => {
+    await checkForUpdate();
     initFirebase();
     const desktopId = await registerDesktop();
 
@@ -140,6 +144,13 @@ program
 
     listenForCommands(desktopId);
 
+    // Start webhook server with tunnel for external integrations.
+    const webhookServer = await startWebhookServer(desktopId);
+    if (webhookServer) {
+      watchWebhookConfigs(desktopId, webhookServer.tunnelUrl);
+      log.info(`Webhook server ready at ${webhookServer.tunnelUrl}`);
+    }
+
     // Print startup banner.
     log.banner(hostname(), getPlatformName(), desktopId, projects.length);
 
@@ -162,6 +173,8 @@ program
       }, 5000);
 
       try {
+        stopWatching();
+        await stopWebhookServer();
         await shutdownAllSessions();
         stopAllTunnels();
         stopAllCaptures();
@@ -183,6 +196,7 @@ program
   .command("pair")
   .description("Generate a pairing QR code for the mobile app")
   .action(async () => {
+    await checkForUpdate();
     initFirebase();
     const desktopId = await registerDesktop();
 
@@ -232,4 +246,52 @@ program
     await runInit({ projectId: opts.projectId });
   });
 
+program
+  .command("set-pro <uid>")
+  .description(
+    "Grant permanent Pro access to a Firebase Auth UID via custom claims",
+  )
+  .action(async (uid) => {
+    initFirebase();
+
+    const { getAuth } = await import("firebase-admin/auth");
+    const auth = getAuth();
+
+    try {
+      // Verify the UID exists.
+      const user = await auth.getUser(uid);
+      log.info(
+        `Found user: ${user.uid} (created ${user.metadata.creationTime})`,
+      );
+
+      // Set the custom claim.
+      await auth.setCustomUserClaims(uid, { pro: true });
+      log.success(`Set pro: true custom claim on UID ${uid}`);
+      log.info(
+        "The user must re-open the app (or force-refresh their token) for this to take effect.",
+      );
+    } catch (e) {
+      log.error(`Failed to set custom claims: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("remove-pro <uid>")
+  .description("Revoke permanent Pro access from a Firebase Auth UID")
+  .action(async (uid) => {
+    initFirebase();
+
+    const { getAuth } = await import("firebase-admin/auth");
+    const auth = getAuth();
+
+    try {
+      await auth.setCustomUserClaims(uid, { pro: false });
+      log.success(`Removed pro claim from UID ${uid}`);
+    } catch (e) {
+      log.error(`Failed to remove custom claims: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/firebase.js

@@ -1,5 +1,6 @@
 import { initializeApp, cert } from "firebase-admin/app";
 import { getFirestore, FieldValue, Timestamp } from "firebase-admin/firestore";
+import { getMessaging as _getMessaging } from "firebase-admin/messaging";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
@@ -43,4 +44,8 @@ export function getDb() {
   return db;
 }
 
+export function getMessaging() {
+  return _getMessaging();
+}
+
 export { FieldValue, Timestamp };

package/src/init.js

@@ -1039,7 +1039,7 @@ export async function runInit({ projectId: overrideProjectId } = {}) {
 
   console.log(
     chalk.dim(
-      "  Love Forge Remote? Support us: https://github.com/sponsors/IronForgeApps\n",
+      "  Love Forge Remote? Support us: https://buy.stripe.com/7sY5kDcL7e792rs06E5J606\n",
     ),
   );
 }

package/src/notifications.js

@@ -0,0 +1,202 @@
+// Forge Remote Relay — Push Notification Module
+// Copyright (c) 2025-2026 Iron Forge Apps
+// Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
+
+import { getDb, getMessaging } from "./firebase.js";
+import * as log from "./logger.js";
+
+// ---------------------------------------------------------------------------
+// FCM token retrieval
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all FCM tokens for a desktop from Firestore.
+ * Tokens are stored at: desktops/{desktopId}/fcmTokens/{platform}
+ * Returns an array of { token, platform, docRef } objects.
+ */
+async function getFcmTokens(desktopId) {
+  const db = getDb();
+  const snap = await db
+    .collection("desktops")
+    .doc(desktopId)
+    .collection("fcmTokens")
+    .get();
+
+  return snap.docs.map((doc) => ({
+    token: doc.data().token,
+    platform: doc.id,
+    docRef: doc.ref,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Core send function
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a push notification to all devices registered for a desktop.
+ * Uses FCM HTTP v1 API via Firebase Admin SDK.
+ *
+ * @param {string} desktopId - Desktop document ID
+ * @param {object} notification - { title, body }
+ * @param {object} data - Custom data payload (all values must be strings)
+ */
+async function sendPushNotification(desktopId, notification, data = {}) {
+  let tokens;
+  try {
+    tokens = await getFcmTokens(desktopId);
+  } catch (e) {
+    log.warn(
+      `[notifications] Failed to read FCM tokens for ${desktopId}: ${e.message}`,
+    );
+    return;
+  }
+
+  if (tokens.length === 0) return;
+
+  const messaging = getMessaging();
+
+  for (const { token, platform, docRef } of tokens) {
+    try {
+      await messaging.send({
+        token,
+        notification,
+        data,
+        // Use high priority for permission requests on Android.
+        android: {
+          priority: data.type === "permission_request" ? "high" : "normal",
+          notification: {
+            channelId:
+              data.type === "permission_request"
+                ? "permissions_channel"
+                : "sessions_channel",
+          },
+        },
+        apns: {
+          payload: {
+            aps: {
+              alert: notification,
+              sound: "default",
+              // Use critical alert priority for permission requests.
+              ...(data.type === "permission_request" && {
+                "interruption-level": "time-sensitive",
+              }),
+            },
+          },
+        },
+      });
+    } catch (e) {
+      const code = e.code || "";
+      // Clean up invalid/expired tokens.
+      if (
+        code === "messaging/registration-token-not-registered" ||
+        code === "messaging/invalid-registration-token"
+      ) {
+        log.warn(
+          `[notifications] Removing stale FCM token for ${platform}: ${code}`,
+        );
+        try {
+          await docRef.delete();
+        } catch {
+          // Best-effort cleanup.
+        }
+      } else {
+        log.warn(`[notifications] Failed to send to ${platform}: ${e.message}`);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience methods — called from session-manager.js
+// ---------------------------------------------------------------------------
+
+/**
+ * Notify mobile that a permission request needs approval.
+ */
+export async function notifyPermissionRequest(
+  desktopId,
+  sessionId,
+  { toolName, commandPreview, projectName },
+) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Permission Needed",
+      body: `${toolName}: ${commandPreview}`.slice(0, 200),
+    },
+    {
+      type: "permission_request",
+      sessionId,
+      toolName: toolName || "",
+      commandPreview: (commandPreview || "").slice(0, 200),
+      projectName: projectName || "",
+    },
+  );
+}
+
+/**
+ * Notify mobile that a session completed successfully.
+ */
+export async function notifySessionComplete(
+  desktopId,
+  sessionId,
+  { projectName },
+) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Task Complete",
+      body: `${projectName}: Claude finished the task`,
+    },
+    {
+      type: "session_complete",
+      sessionId,
+      projectName: projectName || "",
+    },
+  );
+}
+
+/**
+ * Notify mobile that a session encountered an error.
+ */
+export async function notifySessionError(
+  desktopId,
+  sessionId,
+  { projectName, errorMessage },
+) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Session Error",
+      body: `${projectName}: ${errorMessage || "An error occurred"}`.slice(
+        0,
+        200,
+      ),
+    },
+    {
+      type: "session_error",
+      sessionId,
+      projectName: projectName || "",
+      errorMessage: (errorMessage || "").slice(0, 200),
+    },
+  );
+}
+
+/**
+ * Notify mobile that Claude is waiting for input.
+ */
+export async function notifySessionIdle(desktopId, sessionId, { projectName }) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Claude is Waiting",
+      body: `${projectName}: Claude needs your input`,
+    },
+    {
+      type: "session_idle",
+      sessionId,
+      projectName: projectName || "",
+    },
+  );
+}

package/src/session-manager.js

@@ -15,6 +15,13 @@ import {
   stopCapturing,
   hasActiveSimulator,
 } from "./screenshot-manager.js";
+import { postToSlack } from "./webhook-server.js";
+import {
+  notifyPermissionRequest,
+  notifySessionComplete,
+  notifySessionError,
+  notifySessionIdle,
+} from "./notifications.js";
 
 // ---------------------------------------------------------------------------
 // Resolve the user's shell environment so spawned processes inherit PATH,
@@ -153,10 +160,15 @@ const activeSessions = new Map();
  */
 const MAX_SESSIONS = parseInt(process.env.FORGE_MAX_SESSIONS, 10) || 3;
 
+/**
+ * Maximum concurrent sessions allowed via webhook triggers.
+ */
+export const MAX_WEBHOOK_SESSIONS = 5;
+
 /**
  * Returns the count of real sessions (excluding command-watcher sentinel keys).
  */
-function getActiveSessionCount() {
+export function getActiveSessionCount() {
   let count = 0;
   for (const key of activeSessions.keys()) {
     if (!key.startsWith("cmd-watcher-")) count++;
@@ -458,7 +470,7 @@ export async function startNewSession(desktopId, payload) {
     );
   }
 
-  const { prompt, projectPath, model } = payload || {};
+  const { prompt, projectPath, model, webhookMeta } = payload || {};
   const db = getDb();
   const resolvedModel = model || "sonnet";
   const resolvedPath = projectPath || process.cwd();
@@ -503,6 +515,7 @@ export async function startNewSession(desktopId, payload) {
     process: null,
     desktopId,
     projectPath: resolvedPath,
+    projectName,
     model: resolvedModel,
     startTime: Date.now(),
     messageCount: 0,
@@ -511,6 +524,8 @@ export async function startNewSession(desktopId, payload) {
     lastToolCall: null, // Last tool_use block (for permission requests)
     permissionNeeded: false, // True when Claude reports permission denial
     permissionWatcher: null, // Firestore unsubscribe for permission doc
+    webhookMeta: webhookMeta || null, // Webhook metadata for reply callbacks
+    lastAssistantText: "", // Last assistant message text (for webhook replies)
   });
 
   // Desktop terminal banner.
@@ -705,6 +720,13 @@ async function runClaudeProcess(sessionId, prompt) {
           "Process timed out — no output received. Claude CLI may need re-authentication or the model may be unavailable.",
       });
 
+      // Push notification for timeout error.
+      const timeoutSess = activeSessions.get(sessionId);
+      notifySessionError(timeoutSess?.desktopId || desktopId, sessionId, {
+        projectName: timeoutSess?.projectName || "Unknown",
+        errorMessage: "Process timed out — no output received",
+      }).catch(() => {});
+
       await db
         .collection("sessions")
         .doc(sessionId)
@@ -862,6 +884,17 @@ async function runClaudeProcess(sessionId, prompt) {
           lastActivity: FieldValue.serverTimestamp(),
         });
         watchPermissionDecision(sessionId, permDocId);
+
+        // Push notification for permission request.
+        notifyPermissionRequest(sess.desktopId, sessionId, {
+          toolName: toolForPermission.name || "Unknown tool",
+          commandPreview:
+            toolForPermission.input?.command ||
+            toolForPermission.input?.content ||
+            JSON.stringify(toolForPermission.input || {}).slice(0, 200),
+          projectName: sess.projectName || "Unknown",
+        }).catch(() => {});
+
         log.session(
           sessionId,
           "Permission needed — waiting for mobile approval",
@@ -884,6 +917,19 @@ async function runClaudeProcess(sessionId, prompt) {
             timestamp: FieldValue.serverTimestamp(),
           });
 
+        // Push notification for idle.
+        notifySessionIdle(sess.desktopId, sessionId, {
+          projectName: sess.projectName || "Unknown",
+        }).catch(() => {});
+
+        // If this session was triggered by a webhook with a reply URL,
+        // post Claude's last response back to the source (e.g., Slack).
+        if (sess?.webhookMeta?.replyUrl && sess.lastAssistantText) {
+          postToSlack(sess.webhookMeta.replyUrl, sess.lastAssistantText).catch(
+            () => {},
+          );
+        }
+
         log.session(
           sessionId,
           "Turn complete — session idle, waiting for input",
@@ -917,6 +963,12 @@ async function runClaudeProcess(sessionId, prompt) {
           timestamp: FieldValue.serverTimestamp(),
         });
 
+      // Push notification for error.
+      notifySessionError(sess?.desktopId || desktopId, sessionId, {
+        projectName: sess?.projectName || "Unknown",
+        errorMessage: `Process exited with code ${code}`,
+      }).catch(() => {});
+
       log.sessionEnded({
         sessionId,
         status: "error",
@@ -938,6 +990,12 @@ async function runClaudeProcess(sessionId, prompt) {
       errorMessage: `Failed to start: ${err.message}`,
     });
 
+    // Push notification for spawn error.
+    notifySessionError(sess?.desktopId || desktopId, sessionId, {
+      projectName: sess?.projectName || "Unknown",
+      errorMessage: `Failed to start: ${err.message}`,
+    }).catch(() => {});
+
     await db
       .collection("sessions")
       .doc(sessionId)
@@ -1005,6 +1063,13 @@ async function stopSession(sessionId) {
       timestamp: FieldValue.serverTimestamp(),
     });
 
+  // Push notification for session completion.
+  if (session?.desktopId) {
+    notifySessionComplete(session.desktopId, sessionId, {
+      projectName: session.projectName || "Unknown",
+    }).catch(() => {});
+  }
+
   log.sessionEnded({
     sessionId,
     status: "completed",
@@ -1263,7 +1328,10 @@ const PERMISSION_PATTERNS = [
 async function storeAssistantMessage(sessionId, text) {
   const db = getDb();
   const session = activeSessions.get(sessionId);
-  if (session) session.messageCount = (session.messageCount || 0) + 1;
+  if (session) {
+    session.messageCount = (session.messageCount || 0) + 1;
+    session.lastAssistantText = text; // Track for webhook reply callbacks
+  }
 
   await db.collection("sessions").doc(sessionId).collection("messages").add({
     type: "assistant",

package/src/update-checker.js

@@ -0,0 +1,72 @@
+/**
+ * Checks npm registry for newer versions and warns the user.
+ *
+ * Runs non-blocking — never delays startup if the check fails or times out.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import * as log from "./logger.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Read the local package version from package.json. */
+function getLocalVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
+    );
+    return pkg.version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver strings. Returns true if remote is newer than local.
+ */
+function isNewer(local, remote) {
+  const parse = (v) => v.split(".").map(Number);
+  const [lMaj, lMin, lPat] = parse(local);
+  const [rMaj, rMin, rPat] = parse(remote);
+  if (rMaj !== lMaj) return rMaj > lMaj;
+  if (rMin !== lMin) return rMin > lMin;
+  return rPat > lPat;
+}
+
+/**
+ * Check npm for a newer version. Logs a warning if one is found.
+ * Never throws — silently returns on any failure.
+ */
+export async function checkForUpdate() {
+  const localVersion = getLocalVersion();
+  if (!localVersion) return;
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+
+    const res = await fetch("https://registry.npmjs.org/forge-remote/latest", {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return;
+
+    const data = await res.json();
+    const remoteVersion = data.version;
+
+    if (remoteVersion && isNewer(localVersion, remoteVersion)) {
+      console.log();
+      log.warn(
+        `A new version of forge-remote is available: ${localVersion} → ${remoteVersion}`,
+      );
+      log.warn("  Run:  npm update -g forge-remote");
+      log.warn("  Then: forge-remote init    (to update Firestore rules)");
+      console.log();
+    }
+  } catch {
+    // Network error, timeout, etc. — don't bother the user.
+  }
+}