forge-memory 0.2.114 → 0.2.116

package/README.md

@@ -38,11 +38,12 @@ tools). It also exposes `forge_memory_mcp_diagnostics` so adapter startup issues
 show up as a tool result instead of a closed MCP transport.
 
 `pair-ios` prefers the Iroh QR. Forge starts a Rust Iroh host, prints a QR payload
-with the desktop node id, pairing token, optional relay hint, and ALPN
-`forge-companion/1`, and the iPhone app connects through its native Rust bridge. The
-CLI renders a short-schema QR to keep the terminal code scannable and saves the
-full manual payload under `~/.forge/pairing/` so you can paste it into the iPhone
-app if the camera cannot scan.
+with the desktop node id, pairing token, optional relay hint, ALPN
+`forge-companion/1`, and the request URL as a direct fallback when it is
+phone-reachable. The iPhone app connects through its native Rust bridge first and can
+retry through URLSession when that bridge times out. The CLI renders a short-schema QR
+to keep the terminal code scannable and saves the full manual payload under
+`~/.forge/pairing/` so you can paste it into the iPhone app if the camera cannot scan.
 Use `--manual-http` only when you intentionally want a LAN, Tailscale, or direct
 HTTP/TCP route. For a real iPhone, pass a phone-reachable URL:
 
@@ -56,10 +57,12 @@ the iOS Simulator but not for a physical phone.
 The base install stays one command on purpose. The detailed companion transport
 reference lives in the Forge repo at `docs/companion-iroh.md` and in the published
 docs at `https://albertbuchard.github.io/forge/companion-transport.html`. Forge
-Memory ships prebuilt Iroh host binaries for common desktop platforms and a bundled
-Rust source fallback for other machines. If neither a prebuilt host nor Cargo is
-available, `pair-ios` stops with transport-specific repair guidance instead of
-printing a localhost QR that a physical iPhone cannot use.
+Memory ships Forge's Iroh host source and lockfile, not native desktop binaries. When
+the default iOS pairing flow is selected, the installer checks for Cargo, offers to
+install the minimal Rust toolchain when the platform supports it, builds the local
+host from the bundled source, then creates the QR. If Cargo cannot be installed
+automatically, `install`, `configure`, and `pair-ios` stop with platform-specific
+steps instead of printing a localhost QR that a physical iPhone cannot use.
 
 `configure` reruns the full guided flow using the current config as defaults.
 Install and configure run Forge doctor before finishing. `doctor --repair` creates

package/bin/forge-memory.mjs

@@ -277,6 +277,231 @@ function runCapture(command, args, timeoutMs = 2_000) {
   return `${result.stdout}${result.stderr}`.trim();
 }
 
+function binaryNameForPlatform() {
+  return process.platform === "win32"
+    ? "forge-companion-iroh.exe"
+    : "forge-companion-iroh";
+}
+
+function candidateIrohRoots(config) {
+  const roots = [];
+  if (config.mode === "dev" && config.repo) {
+    roots.push(config.repo);
+    roots.push(path.join(config.repo, "openclaw-plugin", "dist"));
+  }
+  const pluginRoot = resolveOpenClawPluginRoot();
+  if (pluginRoot) {
+    roots.push(pluginRoot);
+    roots.push(path.join(pluginRoot, "dist"));
+  }
+  return [...new Set(roots.map((entry) => path.resolve(entry)))];
+}
+
+function candidateIrohBinariesForInstall(config) {
+  const binaryName = binaryNameForPlatform();
+  const platformKey = `${process.platform}-${process.arch}`;
+  const explicitBin = process.env.FORGE_COMPANION_IROH_BIN?.trim();
+  return [
+    ...(explicitBin ? [explicitBin] : []),
+    ...candidateIrohRoots(config).flatMap((root) => [
+      path.join(root, "companion-iroh", "target", "release", binaryName),
+      path.join(root, "companion-iroh", "target", "debug", binaryName),
+      path.join(root, "companion-iroh-src", "target", "release", binaryName),
+      path.join(root, "companion-iroh-src", "target", "debug", binaryName),
+      path.join(root, "companion-iroh", platformKey, binaryName),
+      path.join(root, "companion-iroh", binaryName)
+    ])
+  ];
+}
+
+function findIrohBinaryForInstall(config) {
+  return candidateIrohBinariesForInstall(config).find((candidate) =>
+    fs.existsSync(candidate)
+  );
+}
+
+function candidateIrohManifestsForInstall(config) {
+  return candidateIrohRoots(config).flatMap((root) => [
+    path.join(root, "companion-iroh", "Cargo.toml"),
+    path.join(root, "companion-iroh-src", "Cargo.toml")
+  ]);
+}
+
+function findIrohManifestForInstall(config) {
+  return candidateIrohManifestsForInstall(config).find((candidate) =>
+    fs.existsSync(candidate)
+  );
+}
+
+function rustInstallGuidance() {
+  if (process.platform === "darwin") {
+    return [
+      "Install Apple's command line tools first if prompted: xcode-select --install",
+      "Then install Rust with the official minimal installer:",
+      "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal",
+      "Restart the terminal or run: source ~/.cargo/env"
+    ];
+  }
+  if (process.platform === "linux") {
+    return [
+      "Install build tools with your system package manager, for example: sudo apt-get install -y build-essential pkg-config libssl-dev",
+      "Then install Rust with the official minimal installer:",
+      "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal",
+      "Restart the terminal or run: source ~/.cargo/env"
+    ];
+  }
+  if (process.platform === "win32") {
+    return [
+      "Install Rustup for Windows:",
+      "winget install Rustlang.Rustup",
+      "Then reopen PowerShell and rerun: npx forge-memory install"
+    ];
+  }
+  return [
+    "Install Rust/Cargo from https://rustup.rs, then rerun: npx forge-memory install"
+  ];
+}
+
+function refreshCargoPath() {
+  const cargoBin = path.join(homeDir(), ".cargo", "bin");
+  if (fs.existsSync(cargoBin)) {
+    const current = process.env.PATH ?? "";
+    if (!current.split(path.delimiter).includes(cargoBin)) {
+      process.env.PATH = `${cargoBin}${path.delimiter}${current}`;
+    }
+  }
+}
+
+async function maybeInstallRustToolchain(flags) {
+  refreshCargoPath();
+  if (commandExists("cargo")) {
+    return { ok: true, installed: false };
+  }
+  const guidance = rustInstallGuidance();
+  const canUseRustupScript =
+    (process.platform === "darwin" || process.platform === "linux") &&
+    commandExists("curl");
+  const canUseWinget = process.platform === "win32" && commandExists("winget");
+  if (!canUseRustupScript && !canUseWinget) {
+    return {
+      ok: false,
+      installed: false,
+      guidance:
+        process.platform === "darwin" || process.platform === "linux"
+          ? ["Install curl first, then install Rust/Cargo.", ...guidance]
+          : guidance
+    };
+  }
+  if (flags?.json || flags?.dryRun) {
+    return { ok: false, installed: false, guidance };
+  }
+  const shouldInstall = flags?.yes
+    ? true
+    : await promptYesNo(
+        "Forge Companion Iroh needs Rust/Cargo to build the local transport host. Install the minimal Rust toolchain now?",
+        true
+      );
+  if (!shouldInstall) {
+    return { ok: false, installed: false, guidance };
+  }
+  console.log(color.cyan("Installing minimal Rust toolchain..."));
+  const result = canUseWinget
+    ? await runCommand("winget", [
+        "install",
+        "--id",
+        "Rustlang.Rustup",
+        "-e",
+        "--source",
+        "winget",
+        "--accept-package-agreements",
+        "--accept-source-agreements"
+      ])
+    : await runCommand("sh", [
+        "-c",
+        "curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal"
+      ]);
+  refreshCargoPath();
+  return {
+    ok: result.ok && commandExists("cargo"),
+    installed: result.ok,
+    guidance
+  };
+}
+
+async function ensureIrohTransportPrepared(config, flags = {}) {
+  const existingBinary = findIrohBinaryForInstall(config);
+  if (existingBinary) {
+    return { ok: true, built: false, binary: existingBinary };
+  }
+
+  if (config.mode !== "dev") {
+    await ensurePackagedRuntimeInstalled();
+  }
+
+  const manifestPath = findIrohManifestForInstall(config);
+  if (!manifestPath) {
+    throw new Error(
+      [
+        "Forge could not find the bundled companion Iroh source.",
+        "Run npx forge-memory doctor --repair so Forge Memory refreshes the packaged runtime.",
+        `Runtime log: ${logPath()}.`
+      ].join(" ")
+    );
+  }
+
+  const rust = await maybeInstallRustToolchain(flags);
+  if (!rust.ok) {
+    throw new Error(
+      [
+        "Forge Companion Iroh is source-built on this machine, but Rust/Cargo is not installed yet.",
+        "Install steps:",
+        ...rustInstallGuidance().map((entry) => `- ${entry}`),
+        "Then rerun: npx forge-memory install",
+        "For a temporary direct network fallback, use: npx forge-memory pair-ios --manual-http --public-url <phone-reachable Forge URL>"
+      ].join("\n")
+    );
+  }
+
+  const result = await runLoggedCommand(
+    "cargo",
+    [
+      "build",
+      "--release",
+      "--manifest-path",
+      manifestPath,
+      "--bin",
+      "forge-companion-iroh"
+    ],
+    {
+      cwd: path.dirname(manifestPath),
+      dryRun: flags.dryRun,
+      env: process.env,
+      logFile: logPath()
+    }
+  );
+  if (!result.ok) {
+    throw new Error(
+      [
+        "Forge could not build the local companion Iroh transport host from source.",
+        `Manifest: ${manifestPath}`,
+        `Log: ${logPath()}`,
+        "Install or repair Rust/Cargo, then rerun: npx forge-memory install"
+      ].join(" ")
+    );
+  }
+  const binary = findIrohBinaryForInstall(config);
+  if (!binary && !flags.dryRun) {
+    throw new Error(
+      [
+        "Cargo finished, but Forge could not find the built companion Iroh binary.",
+        `Manifest: ${manifestPath}`,
+        `Expected one of: ${candidateIrohBinariesForInstall(config).join(", ")}`
+      ].join(" ")
+    );
+  }
+  return { ok: true, built: true, binary: binary ?? null, manifestPath };
+}
+
 function detectOpenClaw() {
   const installed =
     commandExists("openclaw") ||
@@ -606,6 +831,59 @@ function findForgeRepo(start = process.cwd()) {
   }
 }
 
+function resolveRuntimeStorageRoot(healthResult) {
+  const storageRoot = healthResult?.payload?.runtime?.storageRoot;
+  return typeof storageRoot === "string" && storageRoot.trim()
+    ? path.resolve(storageRoot)
+    : null;
+}
+
+function pathsMatch(left, right) {
+  return path.resolve(left) === path.resolve(right);
+}
+
+async function resolveInstallRuntimeTarget({
+  origin,
+  requestedPort,
+  requestedWebPort,
+  dataRoot,
+  dataRootWasExplicit
+}) {
+  if (requestedPort !== 0) {
+    const desiredConfig = { origin, port: requestedPort };
+    const desiredHealth = await health(desiredConfig);
+    if (isHealthyForgeRuntime(desiredHealth)) {
+      const liveDataRoot = resolveRuntimeStorageRoot(desiredHealth);
+      if (liveDataRoot && !pathsMatch(liveDataRoot, dataRoot)) {
+        if (dataRootWasExplicit) {
+          throw new Error(
+            [
+              `A healthy Forge runtime is already running at ${baseUrl(desiredConfig)}, but it uses a different data folder.`,
+              `Live data folder: ${liveDataRoot}.`,
+              `Requested data folder: ${path.resolve(dataRoot)}.`,
+              "Stop or restart that runtime before switching data folders. Your data folder is unchanged."
+            ].join(" ")
+          );
+        }
+        dataRoot = liveDataRoot;
+      }
+      return {
+        port: requestedPort,
+        webPort: requestedWebPort,
+        dataRoot: path.resolve(dataRoot),
+        adoptedExistingRuntime: true
+      };
+    }
+  }
+
+  return {
+    port: await findFreePort(requestedPort),
+    webPort: await findFreePort(requestedWebPort),
+    dataRoot: path.resolve(dataRoot),
+    adoptedExistingRuntime: false
+  };
+}
+
 async function buildInstallConfig(parsed, currentConfig, discovery, command) {
   const repo = parsed.values.repo
     ? path.resolve(parsed.values.repo)
@@ -634,22 +912,25 @@ async function buildInstallConfig(parsed, currentConfig, discovery, command) {
   const dataRoot = parsed.flags.yes
     ? dataRootDefault
     : await promptLine("Forge data folder", dataRootDefault);
-  const portInput = parsed.values.port ?? currentConfig.port;
-  const port = await findFreePort(normalizePort(portInput, DEFAULT_PORT));
-  const webPort = await findFreePort(
-    normalizePort(
+  const origin = parsed.values.origin ?? currentConfig.origin ?? DEFAULT_ORIGIN;
+  const runtimeTarget = await resolveInstallRuntimeTarget({
+    origin,
+    requestedPort: normalizePort(parsed.values.port ?? currentConfig.port, DEFAULT_PORT),
+    requestedWebPort: normalizePort(
       parsed.values.webPort ?? currentConfig.webPort,
       DEFAULT_WEB_PORT
-    )
-  );
+    ),
+    dataRoot,
+    dataRootWasExplicit: typeof parsed.values.dataRoot === "string"
+  });
 
   return {
     version: VERSION,
     mode: parsed.flags.dev ? "dev" : mode,
-    origin: parsed.values.origin ?? currentConfig.origin ?? DEFAULT_ORIGIN,
-    port,
-    webPort,
-    dataRoot: path.resolve(dataRoot),
+    origin,
+    port: runtimeTarget.port,
+    webPort: runtimeTarget.webPort,
+    dataRoot: runtimeTarget.dataRoot,
     adapters,
     repo,
     command
@@ -1623,9 +1904,8 @@ class PairingTransportUnavailableError extends Error {
     this.code = "pairing_transport_unavailable";
     this.detail = detail;
     this.guidance = [
-      "Run npx forge-memory doctor --repair so Forge Memory refreshes the packaged runtime and companion transport files.",
-      "Then rerun npx forge-memory pair-ios.",
-      "On unsupported platforms, install Rust/Cargo so Forge can build the bundled companion Iroh source fallback.",
+      "Run npx forge-memory install or npx forge-memory configure so the installer can prepare the Iroh transport.",
+      "If Rust/Cargo is missing, the installer will guide you through installing the minimal Rust toolchain and building Forge's bundled Iroh host source.",
       "For an explicit Tailscale or LAN fallback, rerun with npx forge-memory pair-ios --manual-http --public-url <phone-reachable Forge URL>.",
       "Do not scan a QR whose API URL is 127.0.0.1 on a physical iPhone; that address only works in the iOS Simulator."
     ];
@@ -2004,6 +2284,25 @@ async function runInstall(parsed, command) {
         dryRun: parsed.flags.dryRun
       })
   );
+  const shouldPair =
+    parsed.flags.pairIos ||
+    (!parsed.flags.skipPairIos &&
+      (parsed.flags.yes
+        ? true
+        : await promptYesNo("Pair the iOS companion now?", true)));
+  let irohTransportResult = null;
+  if (
+    shouldPair &&
+    !parsed.flags.manualHttp &&
+    !parsed.flags.dryRun
+  ) {
+    irohTransportResult = await withProgress(
+      "Preparing Forge Companion Iroh transport",
+      "checking Rust/Cargo and building the local host",
+      parsed.flags,
+      () => ensureIrohTransportPrepared(config, parsed.flags)
+    );
+  }
   let runtimeResult = null;
   if (!parsed.flags.noStart && !parsed.flags.dryRun) {
     runtimeResult = await withProgress(
@@ -2041,12 +2340,6 @@ async function runInstall(parsed, command) {
       }
     }
   }
-  const shouldPair =
-    parsed.flags.pairIos ||
-    (!parsed.flags.skipPairIos &&
-      (parsed.flags.yes
-        ? true
-        : await promptYesNo("Pair the iOS companion now?", true)));
   let pairing = null;
   if (shouldPair && !parsed.flags.dryRun) {
     if (!runtimeResult) {
@@ -2085,6 +2378,7 @@ async function runInstall(parsed, command) {
     adapterResults,
     runtimeResult,
     doctorResult,
+    irohTransportResult,
     pairing: Boolean(pairing)
   };
   if (parsed.flags.json) console.log(JSON.stringify(summary, null, 2));
@@ -2295,6 +2589,14 @@ async function runPairIos(parsed) {
     transportMode,
     publicUrl: parsed.values.publicUrl
   });
+  if (transportMode === "iroh") {
+    await withProgress(
+      "Preparing Forge Companion Iroh transport",
+      "checking Rust/Cargo and building the local host",
+      parsed.flags,
+      () => ensureIrohTransportPrepared(config, parsed.flags)
+    );
+  }
   if (!parsed.flags.noStart) {
     const runtimeResult = await withProgress(
       "Starting Forge runtime for iOS pairing",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-memory",
-  "version": "0.2.114",
+  "version": "0.2.116",
   "description": "Guided Forge installer and local runtime manager for the Forge UI, OpenClaw, Hermes, Codex, and iOS pairing.",
   "type": "module",
   "license": "Apache-2.0",