@totalreclaw/totalreclaw 3.3.1-rc.9 → 3.3.1

package/fs-helpers.ts

@@ -56,6 +56,15 @@ export interface CredentialsFile {
   mnemonic?: string;
   /** Alias for `mnemonic`, accepted on read only. */
   recovery_phrase?: string;
+  /**
+   * Smart Account (scope) address derived from the mnemonic. Persisted at
+   * pair-finish so users + tools (`totalreclaw_status`) can read it before
+   * any on-chain write. Internal#130 — lazy SA derivation previously left
+   * the user blind to their scope address until first-write.
+   *
+   * Format: lowercase 0x-prefixed 40-hex-char address. Public, non-secret.
+   */
+  scope_address?: string;
   firstRunAnnouncementShown?: boolean;
   [extra: string]: unknown;
 }
@@ -252,6 +261,274 @@ export function deleteFileIfExists(filePath: string): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Install-staging cleanup (issue #126 — rc.20 finding F3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Clean up `.openclaw-install-stage-*` sibling directories left behind by
+ * an interrupted `openclaw plugins install` run.
+ *
+ * Background
+ * ----------
+ * `openclaw plugins install @totalreclaw/totalreclaw` extracts the npm
+ * tarball into a staging directory named
+ * `<extensionsDir>/.openclaw-install-stage-XXXXXX/` and then renames it
+ * to `<extensionsDir>/totalreclaw/` on success. If the install is
+ * interrupted partway through (e.g. an auto-gateway-restart triggered by
+ * the same install kills the process — see rc.20 QA finding F3), the
+ * staging dir survives. On the next gateway start, OpenClaw's plugin
+ * loader auto-discovers BOTH directories — the real `totalreclaw/` and
+ * the orphaned `.openclaw-install-stage-XXXXXX/` — and registers two
+ * copies of the plugin. Hooks fire twice, the user sees a duplicate
+ * `totalreclaw` row in `openclaw plugins list`, and the gateway log
+ * spams a duplicate-plugin-id warning every cycle.
+ *
+ * Fix scope: best-effort cleanup driven by the plugin itself at register
+ * time. We resolve the extensions dir as the parent of the loaded
+ * plugin's own directory, scan for `.openclaw-install-stage-*` siblings,
+ * and recursively remove each one. If anything fails (permission,
+ * race with a concurrent install), we swallow the error — the existing
+ * loader-warning behavior is no worse than before.
+ *
+ * Returns the list of staging-dir paths that were successfully removed.
+ * Callers may log this for ops visibility. Empty list on a clean install.
+ *
+ * Parameters
+ * ----------
+ * @param pluginDir  Absolute path to the loaded plugin's directory
+ *                   (typically `<extensionsDir>/totalreclaw/dist`). The
+ *                   helper walks up to the parent that holds sibling
+ *                   plugin directories (the `extensions/` root).
+ * @param _now       Optional clock injector for testing — defaults to
+ *                   Date.now().
+ */
+export function cleanupInstallStagingDirs(
+  pluginDir: string,
+  _now: () => number = Date.now,
+): string[] {
+  const removed: string[] = [];
+  try {
+    // pluginDir is `<extensionsDir>/totalreclaw/dist` after build, so the
+    // siblings live two levels up. Resolve both candidates so the helper
+    // works regardless of whether the caller passes the package root or
+    // its `dist/` subdir.
+    const candidates = [
+      path.resolve(pluginDir, '..'),       // <extensionsDir>/totalreclaw → siblings dir if pluginDir is `dist`
+      path.resolve(pluginDir, '..', '..'), // <extensionsDir>/             → siblings dir if pluginDir is package root
+    ];
+
+    for (const extensionsDir of candidates) {
+      let entries: string[];
+      try {
+        entries = fs.readdirSync(extensionsDir);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        if (!name.startsWith('.openclaw-install-stage-')) continue;
+        const target = path.join(extensionsDir, name);
+        try {
+          const st = fs.lstatSync(target);
+          if (!st.isDirectory()) continue;
+          fs.rmSync(target, { recursive: true, force: true });
+          removed.push(target);
+        } catch {
+          // Best-effort — skip unreadable / racy entries.
+        }
+      }
+    }
+  } catch {
+    // Best-effort — never crash plugin init on cleanup failure.
+  }
+  return removed;
+}
+
+// ---------------------------------------------------------------------------
+// Partial-install detection (rc.22 finding #5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Marker filename written into the plugin directory at register-time. Its
+ * presence means a prior install was interrupted before the plugin successfully
+ * loaded — a confirmed-broken half-state that the next `openclaw plugins
+ * install` retry can detect and clean.
+ *
+ * Conceptually the marker is dropped BEFORE npm install completes (the
+ * complementary npm script removes it on success) and additionally
+ * re-asserted at register-time as a second-line check. If you see this file
+ * in `<extensionsDir>/totalreclaw/`, the install never reached register()
+ * AND the marker drop wasn't undone.
+ *
+ * Constants are exported so the npm preinstall/cleanup scripts in
+ * `package.json` use the same name as the runtime detector.
+ */
+export const PARTIAL_INSTALL_MARKER = '.tr-partial-install';
+
+/** Package name we own — used to confirm a directory is OUR plugin, not a stray. */
+export const PLUGIN_PACKAGE_NAME = '@totalreclaw/totalreclaw';
+
+/**
+ * Outcome of `detectPartialInstall`.
+ *  - `'clean'`  — the dir is a fully-installed plugin (package.json claims our
+ *                 name AND `dist/index.js` exists AND no marker present).
+ *  - `'partial'` — the dir is OUR plugin but in a corrupt half-state. Caller
+ *                  should wipe + retry. Returned reasons include:
+ *                    * marker file present (preinstall fired, postinstall did not)
+ *                    * dist/index.js missing (build never finished)
+ *  - `'foreign'` — package.json missing or claims a different name. Helper
+ *                  refuses to act so we never delete an unrelated plugin.
+ *  - `'absent'`  — dir does not exist at all.
+ */
+export type PartialInstallStatus = 'clean' | 'partial' | 'foreign' | 'absent';
+
+export interface PartialInstallResult {
+  status: PartialInstallStatus;
+  /** Why the caller decided this is partial — surfaces in error messages. */
+  reasons: string[];
+}
+
+/**
+ * Inspect a plugin install directory to decide whether it is fully installed,
+ * a corrupted half-state from an interrupted install, or someone else's
+ * plugin. Pure filesystem inspection; never deletes anything.
+ *
+ * Background — rc.22 finding #5
+ * ------------------------------
+ * After a partial `openclaw plugins install @totalreclaw/totalreclaw` (e.g.
+ * the auto-gateway-restart kills npm mid-build), `extensions/totalreclaw/`
+ * survives with a populated package.json but a missing or empty `dist/`. The
+ * agent's recovery retry then fires another install; OpenClaw's plugin
+ * loader scans `extensions/` and tries to register the half-state as a "hook
+ * pack", failing with the cryptic "package.json missing openclaw.hooks". The
+ * fix: detect the partial state up-front so the retry can wipe + reinstall
+ * instead of cargo-culting a confused error.
+ *
+ * Decision rules
+ * --------------
+ *   1. `pluginRootDir` does not exist → `'absent'`.
+ *   2. package.json missing or unparsable → `'foreign'` (don't touch).
+ *   3. package.json `name !== '@totalreclaw/totalreclaw'` → `'foreign'`.
+ *   4. `<root>/.tr-partial-install` exists → `'partial'` (the canonical signal).
+ *   5. `<root>/dist/index.js` missing → `'partial'` (build never finished).
+ *   6. otherwise → `'clean'`.
+ *
+ * The function is intentionally conservative: it returns `'foreign'` on any
+ * ambiguous read. Callers should NEVER auto-wipe a `'foreign'` directory.
+ *
+ * @param pluginRootDir Absolute path to the suspect plugin dir, e.g.
+ *                      `~/.openclaw/extensions/totalreclaw`.
+ */
+export function detectPartialInstall(pluginRootDir: string): PartialInstallResult {
+  const reasons: string[] = [];
+
+  // Rule 1 — absent dir.
+  let rootStat: fs.Stats;
+  try {
+    rootStat = fs.statSync(pluginRootDir);
+  } catch {
+    return { status: 'absent', reasons: ['directory does not exist'] };
+  }
+  if (!rootStat.isDirectory()) {
+    return { status: 'foreign', reasons: ['path exists but is not a directory'] };
+  }
+
+  // Rules 2-3 — package.json must claim our name.
+  const pkgJsonPath = path.join(pluginRootDir, 'package.json');
+  let pkgRaw: string;
+  try {
+    pkgRaw = fs.readFileSync(pkgJsonPath, 'utf-8');
+  } catch {
+    return { status: 'foreign', reasons: ['package.json missing or unreadable'] };
+  }
+  let parsed: { name?: unknown };
+  try {
+    parsed = JSON.parse(pkgRaw) as { name?: unknown };
+  } catch {
+    return { status: 'foreign', reasons: ['package.json is not valid JSON'] };
+  }
+  if (parsed.name !== PLUGIN_PACKAGE_NAME) {
+    return {
+      status: 'foreign',
+      reasons: [`package.json declares "${String(parsed.name)}" not "${PLUGIN_PACKAGE_NAME}"`],
+    };
+  }
+
+  // Rule 4 — explicit partial marker wins.
+  const markerPath = path.join(pluginRootDir, PARTIAL_INSTALL_MARKER);
+  if (fs.existsSync(markerPath)) {
+    reasons.push(`${PARTIAL_INSTALL_MARKER} marker present (preinstall fired, postinstall did not)`);
+  }
+
+  // Rule 5 — dist/index.js must exist for the loader to register.
+  const distIndex = path.join(pluginRootDir, 'dist', 'index.js');
+  if (!fs.existsSync(distIndex)) {
+    reasons.push('dist/index.js missing (build artifact absent)');
+  }
+
+  if (reasons.length > 0) {
+    return { status: 'partial', reasons };
+  }
+  return { status: 'clean', reasons: [] };
+}
+
+/**
+ * Wipe a partial-install directory so the next `openclaw plugins install`
+ * starts from a blank slate. Only acts when `detectPartialInstall(...)`
+ * returns `'partial'` — `'foreign'` and `'clean'` are no-ops by design.
+ *
+ * Returns `true` if the directory was wiped, `false` otherwise.
+ *
+ * SAFETY: this helper is the only place that recursively deletes a plugin
+ * dir. It refuses to act on `'foreign'` and `'clean'` results so a
+ * misconfigured caller can never wipe a healthy install or someone else's
+ * plugin.
+ */
+export function wipePartialInstall(pluginRootDir: string): boolean {
+  const detection = detectPartialInstall(pluginRootDir);
+  if (detection.status !== 'partial') return false;
+  try {
+    fs.rmSync(pluginRootDir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
+ * (overwrites any existing marker) and best-effort — returns `true` on
+ * success, `false` if the dir doesn't exist or write fails. Used by the
+ * `preinstall` npm script and (defensively) by the runtime if the npm
+ * preinstall/cleanup script pair did not fire.
+ */
+export function writePartialInstallMarker(pluginRootDir: string): boolean {
+  try {
+    if (!fs.existsSync(pluginRootDir)) return false;
+    fs.writeFileSync(path.join(pluginRootDir, PARTIAL_INSTALL_MARKER), '');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove the partial-install marker. Called by the `postinstall` script and
+ * (defensively) at register-time once we've confirmed the load succeeded.
+ * Returns `true` if a marker was removed, `false` if there was nothing to
+ * remove.
+ */
+export function clearPartialInstallMarker(pluginRootDir: string): boolean {
+  try {
+    const markerPath = path.join(pluginRootDir, PARTIAL_INSTALL_MARKER);
+    if (!fs.existsSync(markerPath)) return false;
+    fs.unlinkSync(markerPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Auto-bootstrap of credentials.json (3.1.0 first-run UX)
 // ---------------------------------------------------------------------------

package/gateway-url.ts

@@ -126,27 +126,66 @@ function shouldSkipIface(name: string): boolean {
   return SKIP_IFACE_PREFIXES.some((p) => lower.startsWith(p));
 }
 
+/**
+ * Docker container internal IP detection — issue #110 fix 4.
+ *
+ * From INSIDE a Docker container, `eth0` carries the container's bridge IP
+ * (e.g. `172.18.0.2`). That IP is reachable from other containers on the
+ * SAME Docker network but NOT from the host browser, the user's phone, or
+ * any external device. Surfacing it as the pairing URL produces a hard-
+ * dead user experience: "scan QR" yields connection-refused.
+ *
+ * Docker default-bridge ranges:
+ *   - 172.17.0.0/16 — `bridge` (default)
+ *   - 172.18.0.0/16 .. 172.31.0.0/16 — user-defined networks
+ *
+ * We use the conservative test: 172.16.0.0/12 (the full RFC-1918 172.x
+ * range, which is what Docker draws from). If the host is clearly Docker
+ * (`/.dockerenv`), we treat 172.16-31.x.x AS Docker-internal and skip it.
+ *
+ * Outside Docker, 172.16.x.x can be a legitimate corporate LAN, so we
+ * only apply the rule when we have positive Docker evidence.
+ */
+export function isDockerInternalIp(addr: string): boolean {
+  if (!/^\d{1,3}(?:\.\d{1,3}){3}$/.test(addr)) return false;
+  const parts = addr.split('.').map((p) => Number.parseInt(p, 10));
+  if (parts[0] !== 172) return false;
+  return parts[1] >= 16 && parts[1] <= 31;
+}
+
 /**
  * Pick the first non-loopback, non-virtual IPv4 address. Returns null if
  * none found (headless VPS with only lo + tailscale, for example).
+ *
+ * issue #110 fix 4: when the host is detected as Docker (caller passes
+ * `isDocker: true`), skip Docker-bridge IPs in the 172.16/12 range — they
+ * are container-internal and useless for any external browser. Returning
+ * null from this function in that scenario lets `buildPairingUrl` fall
+ * through to the localhost-with-relay-fallback warning rather than handing
+ * the user a dead URL.
  */
 export function detectLanHost(options?: {
   /** Override os.networkInterfaces for tests. */
   networkInterfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+  /** True when the host is Docker — skips 172.16/12 bridge IPs. */
+  isDocker?: boolean;
 }): DetectedGatewayHost | null {
   const nif = (options?.networkInterfaces ?? os.networkInterfaces)();
   for (const [name, addrs] of Object.entries(nif)) {
     if (shouldSkipIface(name)) continue;
     if (!addrs) continue;
     for (const a of addrs) {
-      if (a.family === 'IPv4' && !a.internal) {
-        return {
-          kind: 'lan',
-          host: a.address,
-          tls: false,
-          note: `LAN IPv4 on interface ${name} — only reachable from the same network.`,
-        };
-      }
+      if (a.family !== 'IPv4' || a.internal) continue;
+      // issue #110 fix 4 — Docker container internal IP is unreachable
+      // from any external browser. Skip it so the caller falls back to
+      // the relay-brokered URL.
+      if (options?.isDocker && isDockerInternalIp(a.address)) continue;
+      return {
+        kind: 'lan',
+        host: a.address,
+        tls: false,
+        note: `LAN IPv4 on interface ${name} — only reachable from the same network.`,
+      };
     }
   }
   return null;
@@ -162,13 +201,22 @@ export function detectLanHost(options?: {
  *
  * Sync: no I/O, no subprocess, no network. Safe in sync callers like
  * `buildPairingUrl` in index.ts.
+ *
+ * issue #110 fix 4: the `isDocker` option, when true, skips the 172.16/12
+ * Docker-bridge range during LAN detection. The caller (index.ts) passes
+ * `isRunningInDocker()` so we don't surface a container-internal IP that
+ * no external browser can reach.
  */
 export function detectGatewayHost(options?: {
   networkInterfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+  isDocker?: boolean;
 }): DetectedGatewayHost | null {
   const ts = detectTailscaleHost({ networkInterfaces: options?.networkInterfaces });
   if (ts) return ts;
-  const lan = detectLanHost({ networkInterfaces: options?.networkInterfaces });
+  const lan = detectLanHost({
+    networkInterfaces: options?.networkInterfaces,
+    isDocker: options?.isDocker,
+  });
   if (lan) return lan;
   return null;
 }