forge-remote 2.1.5 → 2.2.0

package/src/cloud-mode.js

@@ -0,0 +1,126 @@
+// Forge Remote — Cloud Mode (managed pairing)
+// Copyright (c) 2025-2026 Iron Forge Apps
+
+import { initializeApp } from "firebase/app";
+import {
+  getFirestore,
+  doc,
+  setDoc,
+  onSnapshot,
+  deleteDoc,
+  serverTimestamp,
+  Timestamp,
+} from "firebase/firestore";
+import { hostname } from "os";
+import qrcode from "qrcode-terminal";
+
+import * as log from "./logger.js";
+import { getPlatformName, getDesktopId } from "./desktop.js";
+
+/**
+ * Forge Remote Cloud (managed Firebase project) — public web SDK config.
+ * Replace these placeholders with the real `forge-remote-cloud` values
+ * once the project has been provisioned.
+ */
+const CLOUD_CONFIG = {
+  apiKey: "REPLACE_WITH_CLOUD_WEB_API_KEY",
+  authDomain: "forge-remote-cloud.firebaseapp.com",
+  projectId: "forge-remote-cloud",
+  storageBucket: "forge-remote-cloud.firebasestorage.app",
+  messagingSenderId: "REPLACE_WITH_CLOUD_SENDER_ID",
+  appId: "REPLACE_WITH_CLOUD_WEB_APP_ID",
+};
+
+export function isCloudConfigured() {
+  return !CLOUD_CONFIG.apiKey.startsWith("REPLACE_WITH_");
+}
+
+function generatePairingCode() {
+  return String(Math.floor(100000 + Math.random() * 900000));
+}
+
+/**
+ * Cloud-mode start: prints a 6-digit code, waits for the mobile app to
+ * claim it, then registers the desktop under `users/{uid}/desktops/`.
+ *
+ * Returns when the desktop has been claimed and `desktopId` is known.
+ */
+export async function pairWithCloud() {
+  if (!isCloudConfigured()) {
+    log.error(
+      "Cloud mode is not configured yet. Use BYOF: `npx forge-remote init`.",
+    );
+    log.info("Cloud project provisioning is in progress — check back soon.");
+    process.exit(1);
+  }
+
+  const app = initializeApp(CLOUD_CONFIG, "forge-remote-cloud");
+  const db = getFirestore(app);
+
+  const code = generatePairingCode();
+  const desktopId = await getDesktopId();
+  const expiresAt = Timestamp.fromDate(new Date(Date.now() + 10 * 60 * 1000));
+
+  await setDoc(doc(db, "pairing_codes", code), {
+    desktopId,
+    hostname: hostname(),
+    platform: getPlatformName(),
+    createdAt: serverTimestamp(),
+    expiresAt,
+  });
+
+  log.info("");
+  log.info("════════════════════════════════════════════");
+  log.info(`  Forge Remote Cloud — Pairing Code:  ${code}`);
+  log.info("════════════════════════════════════════════");
+  log.info("");
+  log.info(
+    "In the Forge Remote app, choose 'Get Started Free' and enter the code.",
+  );
+  log.info("Code expires in 10 minutes.");
+  qrcode.generate(`forgeremote://pair/${code}`, { small: true });
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(
+      () => {
+        reject(
+          new Error("Pairing code expired. Restart with --cloud to retry."),
+        );
+      },
+      10 * 60 * 1000,
+    );
+
+    const unsub = onSnapshot(doc(db, "pairing_codes", code), async (snap) => {
+      if (!snap.exists()) return;
+      const data = snap.data();
+      const userUid = data.userUid;
+      if (!userUid) return;
+
+      try {
+        await setDoc(
+          doc(db, "users", userUid, "desktops", desktopId),
+          {
+            id: desktopId,
+            hostname: hostname(),
+            platform: getPlatformName(),
+            ownerUid: userUid,
+            status: "online",
+            lastHeartbeat: serverTimestamp(),
+            createdAt: serverTimestamp(),
+          },
+          { merge: true },
+        );
+        await deleteDoc(doc(db, "pairing_codes", code));
+        log.success(`Paired with user ${userUid}`);
+        clearTimeout(timeout);
+        unsub();
+        resolve({ userUid, desktopId, app, db });
+      } catch (e) {
+        log.error(`Cloud pairing failed: ${e.message}`);
+        clearTimeout(timeout);
+        unsub();
+        reject(e);
+      }
+    });
+  });
+}

package/src/distribution.js

@@ -0,0 +1,192 @@
+// Forge Remote — Build distribution
+// Copyright (c) 2025-2026 Iron Forge Apps
+//
+// Per-platform "publish this build somewhere installable" flows.
+//
+//   web      → existing deployToFirebaseHosting (channel deploy)
+//   android  → existing deployToAppDistribution
+//   ios      → uploadToTestFlight (this file)
+//
+// TestFlight is the right answer for iOS because Apple won't let you
+// install a .ipa from a download URL — the user has to go through
+// TestFlight, an MDM, or have their UDID registered against an ad-hoc
+// profile. TestFlight Internal Testing (up to 100 testers) skips App
+// Store review entirely, so it's a clean "build → install on phone"
+// experience.
+
+import { execFileSync } from "child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+import * as log from "./logger.js";
+import { loadTestflightCreds } from "./ios-setup.js";
+
+function which(cmd) {
+  try {
+    execFileSync("/bin/sh", ["-c", `command -v ${cmd}`], {
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveIpa(projectPath, buildPath) {
+  const full = path.isAbsolute(buildPath)
+    ? buildPath
+    : path.join(projectPath, buildPath);
+  if (!full.includes("*") && existsSync(full)) return full;
+  // Glob fallback for `build/ios/ipa/*.ipa`.
+  const dir = path.dirname(full);
+  if (!existsSync(dir)) return full;
+  try {
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".ipa"))
+      .map((f) => ({
+        p: path.join(dir, f),
+        m: statSync(path.join(dir, f)).mtimeMs,
+      }))
+      .sort((a, b) => b.m - a.m);
+    return files[0]?.p || full;
+  } catch {
+    return full;
+  }
+}
+
+/**
+ * Upload an .ipa to TestFlight using `xcrun altool`. Requires App Store
+ * Connect API key credentials — either:
+ *
+ *   1. ASC_API_KEY_PATH env var pointing at AuthKey_XYZ.p8, plus
+ *      ASC_KEY_ID and ASC_ISSUER_ID env vars.
+ *   2. Username + app-specific password (legacy fallback) via
+ *      APPLE_ID and APP_SPECIFIC_PASSWORD env vars.
+ *
+ * Returns:
+ *   {
+ *     uploaded: true,
+ *     testflightUrl: "https://appstoreconnect.apple.com/.../testflight",
+ *     openUrl: "itms-beta://"
+ *   }
+ */
+export async function uploadToTestFlight(projectPath, buildPath, options = {}) {
+  if (!which("xcrun")) {
+    throw new Error(
+      "xcrun not found. TestFlight upload requires Xcode Command Line Tools.",
+    );
+  }
+
+  const ipaPath = resolveIpa(projectPath, buildPath);
+  if (!existsSync(ipaPath)) {
+    throw new Error(`IPA not found at ${ipaPath}. Run an iOS build first.`);
+  }
+
+  // Resolve credentials — saved manifest first, then options/env overrides.
+  const saved = loadTestflightCreds() || {};
+  const apiKeyPath =
+    options.apiKeyPath || process.env.ASC_API_KEY_PATH || saved.apiKeyPath;
+  const apiKeyId = options.apiKeyId || process.env.ASC_KEY_ID || saved.apiKeyId;
+  const apiIssuerId =
+    options.apiIssuerId || process.env.ASC_ISSUER_ID || saved.apiIssuerId;
+
+  const appleId = options.appleId || process.env.APPLE_ID;
+  const appPassword =
+    options.appSpecificPassword || process.env.APP_SPECIFIC_PASSWORD;
+
+  let authArgs;
+  if (apiKeyPath && apiKeyId && apiIssuerId) {
+    if (!existsSync(apiKeyPath)) {
+      throw new Error(`ASC API key not found at ${apiKeyPath}`);
+    }
+    authArgs = [
+      "--apiKey",
+      apiKeyId,
+      "--apiIssuer",
+      apiIssuerId,
+      "--apiKeyPath",
+      apiKeyPath,
+    ];
+  } else if (appleId && appPassword) {
+    authArgs = ["--username", appleId, "--password", appPassword];
+  } else {
+    throw new Error(
+      "TestFlight upload needs App Store Connect credentials. Set " +
+        "ASC_API_KEY_PATH + ASC_KEY_ID + ASC_ISSUER_ID, or APPLE_ID + " +
+        "APP_SPECIFIC_PASSWORD.",
+    );
+  }
+
+  log.info(`Uploading ${path.basename(ipaPath)} to TestFlight...`);
+
+  const args = [
+    "altool",
+    "--upload-app",
+    "--type",
+    "ios",
+    "--file",
+    ipaPath,
+    ...authArgs,
+    "--output-format",
+    "json",
+  ];
+
+  const startedAt = Date.now();
+  try {
+    execFileSync("xcrun", args, {
+      stdio: ["ignore", "inherit", "inherit"],
+      timeout: 30 * 60 * 1000, // 30 min — uploads are slow.
+    });
+  } catch (err) {
+    throw new Error(`altool upload failed: ${err.message}`);
+  }
+
+  const duration = Math.round((Date.now() - startedAt) / 1000);
+  log.success(`TestFlight upload complete (${duration}s)`);
+
+  return {
+    uploaded: true,
+    duration,
+    testflightUrl:
+      options.appStoreConnectUrl || "https://appstoreconnect.apple.com/apps",
+    openUrl: "itms-beta://",
+  };
+}
+
+/**
+ * Smart router: given a platform + build path, pick the appropriate
+ * distribution backend. Used by the `deploy_distribute` relay command.
+ */
+export async function distribute({
+  platform,
+  projectPath,
+  buildPath,
+  options = {},
+  // Lazy-loaded to avoid a circular import with build-manager.
+  hostingFn,
+  appDistFn,
+}) {
+  switch (platform) {
+    case "ios":
+      return {
+        backend: "testflight",
+        result: await uploadToTestFlight(projectPath, buildPath, options),
+      };
+    case "web":
+      if (!hostingFn) throw new Error("hostingFn not provided");
+      return {
+        backend: "hosting_preview",
+        result: await hostingFn(projectPath, buildPath, {
+          ...options,
+          channelId: options.channelId || `preview-${Date.now()}`,
+        }),
+      };
+    case "android":
+    default:
+      if (!appDistFn) throw new Error("appDistFn not provided");
+      return {
+        backend: "app_distribution",
+        result: await appDistFn(projectPath, buildPath, options),
+      };
+  }
+}

package/src/ios-setup.js

@@ -0,0 +1,281 @@
+// Forge Remote — iOS readiness + TestFlight credential setup
+// Copyright (c) 2025-2026 Iron Forge Apps
+//
+// Two prerequisites for iOS distribution:
+//   1. Code signing — needs a Development Team set in Runner.xcodeproj
+//      and a matching signing identity in the Mac's keychain. Has to be
+//      configured in Xcode (Apple won't let us automate it).
+//   2. App Store Connect API key — for `xcrun altool` uploads. Saved to
+//      ~/.forge-remote/asc-credentials.json (mode 0600) so future
+//      uploads just work.
+
+import { execFileSync } from "child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { homedir } from "os";
+
+import * as log from "./logger.js";
+
+const FORGE_DIR = path.join(homedir(), ".forge-remote");
+const CREDS_PATH = path.join(FORGE_DIR, "asc-credentials.json");
+const KEYS_DIR = path.join(FORGE_DIR, "asc-keys");
+
+function ensureForgeDir() {
+  if (!existsSync(FORGE_DIR)) mkdirSync(FORGE_DIR, { recursive: true });
+  if (!existsSync(KEYS_DIR))
+    mkdirSync(KEYS_DIR, { recursive: true, mode: 0o700 });
+}
+
+// ─── Readiness check ─────────────────────────────────────────────────────────
+
+/**
+ * Inspect a Flutter project for iOS-distribution readiness. Pure-read,
+ * never modifies anything. Returns:
+ *
+ *   {
+ *     signing: {
+ *       ok: boolean,
+ *       teamId: string | null,
+ *       projectPath: string,
+ *       hint: string | null,
+ *     },
+ *     testflight: {
+ *       ok: boolean,
+ *       hasApiKey: boolean,
+ *       keyId: string | null,
+ *       issuerId: string | null,
+ *       hint: string | null,
+ *     },
+ *     xcode: { ok: boolean, hint: string | null },
+ *     ready: boolean,
+ *   }
+ */
+export function checkIosReadiness(projectPath) {
+  const xcode = checkXcodeAvailable();
+  const signing = checkSigning(projectPath);
+  const testflight = checkTestflightCreds();
+  return {
+    xcode,
+    signing,
+    testflight,
+    ready: xcode.ok && signing.ok && testflight.ok,
+  };
+}
+
+function checkXcodeAvailable() {
+  try {
+    execFileSync("xcrun", ["--version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, hint: null };
+  } catch {
+    return {
+      ok: false,
+      hint: "Install Xcode Command Line Tools: xcode-select --install",
+    };
+  }
+}
+
+function checkSigning(projectPath) {
+  const xcodeprojPath = path.join(
+    projectPath,
+    "ios",
+    "Runner.xcodeproj",
+    "project.pbxproj",
+  );
+  if (!existsSync(xcodeprojPath)) {
+    return {
+      ok: false,
+      teamId: null,
+      projectPath: xcodeprojPath,
+      hint: "No ios/Runner.xcodeproj found. Is this a Flutter iOS project?",
+    };
+  }
+
+  // Read the pbxproj and look for DEVELOPMENT_TEAM in any non-default
+  // build configuration. Empty string or missing = not configured.
+  let pbx;
+  try {
+    pbx = readFileSync(xcodeprojPath, "utf-8");
+  } catch (e) {
+    return {
+      ok: false,
+      teamId: null,
+      projectPath: xcodeprojPath,
+      hint: `Failed to read ${xcodeprojPath}: ${e.message}`,
+    };
+  }
+
+  const matches = [...pbx.matchAll(/DEVELOPMENT_TEAM = ([A-Z0-9]+);/g)]
+    .map((m) => m[1])
+    .filter((t) => t && t !== '""');
+
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      teamId: null,
+      projectPath: xcodeprojPath,
+      hint:
+        "Open Xcode → Runner → Signing & Capabilities → pick your Team. " +
+        "Or run `npx forge-remote setup-ios-signing` to open Xcode now.",
+    };
+  }
+
+  // Confirm there's at least one matching signing identity in the keychain.
+  let hasIdentity = true;
+  try {
+    const out = execFileSync(
+      "security",
+      ["find-identity", "-v", "-p", "codesigning"],
+      { stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    );
+    hasIdentity = /Apple (Development|Distribution)/.test(out);
+  } catch {
+    hasIdentity = false;
+  }
+
+  if (!hasIdentity) {
+    return {
+      ok: false,
+      teamId: matches[0],
+      projectPath: xcodeprojPath,
+      hint:
+        "No Apple signing identity found in your keychain. In Xcode → " +
+        "Settings → Accounts, sign in with your Apple ID and download " +
+        "manual profiles.",
+    };
+  }
+
+  return {
+    ok: true,
+    teamId: matches[0],
+    projectPath: xcodeprojPath,
+    hint: null,
+  };
+}
+
+function checkTestflightCreds() {
+  if (!existsSync(CREDS_PATH)) {
+    return {
+      ok: false,
+      hasApiKey: false,
+      keyId: null,
+      issuerId: null,
+      hint:
+        "Save your App Store Connect API key from the mobile app, or " +
+        "run `npx forge-remote setup-testflight`.",
+    };
+  }
+  try {
+    const data = JSON.parse(readFileSync(CREDS_PATH, "utf-8"));
+    const keyPath = data.apiKeyPath;
+    const ok =
+      data.apiKeyId && data.apiIssuerId && keyPath && existsSync(keyPath);
+    return {
+      ok,
+      hasApiKey: !!keyPath,
+      keyId: data.apiKeyId || null,
+      issuerId: data.apiIssuerId || null,
+      hint: ok ? null : "Saved credentials are incomplete. Re-run setup.",
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      hasApiKey: false,
+      keyId: null,
+      issuerId: null,
+      hint: `Couldn't read credentials: ${e.message}`,
+    };
+  }
+}
+
+// ─── Credential persistence ─────────────────────────────────────────────────
+
+/**
+ * Save App Store Connect API credentials. The mobile app passes the .p8
+ * file's contents inline (base64 or raw) since the phone can't push a
+ * file. We write the .p8 to ~/.forge-remote/asc-keys/AuthKey_<id>.p8
+ * and a manifest pointing to it.
+ *
+ * @param {{ apiKeyId: string, apiIssuerId: string, apiKeyContent: string,
+ *           appStoreConnectUrl?: string }} creds
+ */
+export function saveTestflightCreds(creds) {
+  const { apiKeyId, apiIssuerId, apiKeyContent, appStoreConnectUrl } = creds;
+  if (!apiKeyId || !apiIssuerId || !apiKeyContent) {
+    throw new Error("apiKeyId, apiIssuerId, and apiKeyContent are required");
+  }
+  if (!/^[A-Z0-9]+$/.test(apiKeyId)) {
+    throw new Error("apiKeyId must be uppercase alphanumeric");
+  }
+
+  ensureForgeDir();
+
+  const keyPath = path.join(KEYS_DIR, `AuthKey_${apiKeyId}.p8`);
+  // Normalize: accept "BEGIN PRIVATE KEY" content as-is, or base64 of it.
+  const trimmed = apiKeyContent.trim();
+  const content = trimmed.startsWith("-----BEGIN")
+    ? trimmed + "\n"
+    : Buffer.from(trimmed, "base64").toString("utf-8");
+  writeFileSync(keyPath, content, { mode: 0o600 });
+
+  const manifest = {
+    apiKeyId,
+    apiIssuerId,
+    apiKeyPath: keyPath,
+    appStoreConnectUrl: appStoreConnectUrl || null,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(CREDS_PATH, JSON.stringify(manifest, null, 2), {
+    mode: 0o600,
+  });
+  // Belt and suspenders: chmod in case writeFileSync mode was masked.
+  chmodSync(CREDS_PATH, 0o600);
+  chmodSync(keyPath, 0o600);
+
+  log.success(`Saved TestFlight credentials to ${CREDS_PATH}`);
+  return manifest;
+}
+
+/** Load saved credentials, or null if none exist. */
+export function loadTestflightCreds() {
+  if (!existsSync(CREDS_PATH)) return null;
+  try {
+    const stat = statSync(CREDS_PATH);
+    if ((stat.mode & 0o077) !== 0) {
+      log.warn(`Tightening permissions on ${CREDS_PATH}`);
+      chmodSync(CREDS_PATH, 0o600);
+    }
+    return JSON.parse(readFileSync(CREDS_PATH, "utf-8"));
+  } catch (e) {
+    log.warn(`Failed to load ASC credentials: ${e.message}`);
+    return null;
+  }
+}
+
+// ─── Xcode helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Open Runner.xcworkspace (or .xcodeproj as a fallback) so the user can
+ * configure signing. Returns the path that was opened.
+ */
+export function openXcodeSigning(projectPath) {
+  const workspace = path.join(projectPath, "ios", "Runner.xcworkspace");
+  const xcodeproj = path.join(projectPath, "ios", "Runner.xcodeproj");
+  const target = existsSync(workspace) ? workspace : xcodeproj;
+  if (!existsSync(target)) {
+    throw new Error(
+      `No Xcode project found under ${path.join(projectPath, "ios")}`,
+    );
+  }
+  execFileSync("open", [target], { stdio: ["ignore", "ignore", "ignore"] });
+  log.info(`Opened ${target}`);
+  return target;
+}