robot-resources 1.9.1 → 1.9.3

package/lib/python-bridge.js

@@ -1,5 +1,6 @@
 import {
   findPython,
+  findOrInstallPython,
   ensureVenv,
   installRouter,
   isRouterInstalled,
@@ -7,22 +8,31 @@ import {
 } from '@robot-resources/cli-core/python-bridge.mjs';
 
 // Re-export shared primitives used by wizard.js and other CLI code.
-export { ensureVenv, isRouterInstalled, getVenvPythonPath };
+export { findPython, ensureVenv, isRouterInstalled, getVenvPythonPath };
 
 /**
- * Full setup: find Python, create venv, install router.
- * Returns { venvPython, pythonVersion } or throws.
+ * Full setup: find Python (or bootstrap one via uv), create venv, install router.
+ *
+ * The uv-fallback path is what unblocks users without system Python. It
+ * downloads the uv binary to ~/.robot-resources/bin/ and uses it to
+ * install a standalone Python — nothing touches the user's system.
+ *
+ * Returns { venvPython, pythonVersion, pythonSource } or throws.
  */
 export async function setupRouter() {
-  const python = findPython();
+  const python = await findOrInstallPython();
   if (!python) {
     throw new Error(
-      'Python 3.10+ not found. Install Python from https://python.org and try again.\n' +
-      '  The Router requires Python. Scraper and MCP tools work without it.'
+      'Python 3.10+ not found and uv bootstrap failed. ' +
+      'Install Python from https://python.org and try again.'
     );
   }
 
   const venvPython = ensureVenv(python.bin);
   await installRouter();
-  return { venvPython, pythonVersion: python.version };
+  return {
+    venvPython,
+    pythonVersion: python.version,
+    pythonSource: python.source,  // 'system' | 'uv'
+  };
 }

package/lib/wizard.js

@@ -9,6 +9,40 @@ import { installService, isServiceRunning, isServiceInstalled } from './service.
 import { configureToolRouting, registerScraperMcp, restartOpenClawGateway } from './tool-config.js';
 import { checkHealth } from './health-report.js';
 import { header, step, success, warn, error, info, blank, summary } from './ui.js';
+/**
+ * Classify an install error into a short reason code + bounded detail string.
+ *
+ * Before this existed, install_complete telemetry reported router:false with
+ * no context — 100% of rr-router installs failed and we couldn't diagnose.
+ * The reason code slots into a small enum so we can aggregate in the admin
+ * dashboard; detail is the tail of stderr/error message for deep-dives.
+ */
+function classifyRouterError(err) {
+  const msg = (err?.message || String(err)).toLowerCase();
+  let reason = 'unknown';
+
+  if (msg.includes('python 3.10+') || msg.includes('python is required')) {
+    reason = 'python_not_found';
+  } else if (err?.code === 'ENOENT' || msg.includes('enoent')) {
+    reason = 'spawn_enoent';
+  } else if (msg.includes('timeout') || msg.includes('timed out') || err?.code === 'ETIMEDOUT') {
+    reason = 'timeout';
+  } else if (msg.includes('exited with code') || msg.includes('pip install')) {
+    reason = 'pip_install_failed';
+  } else if (msg.includes('permission denied') || err?.code === 'EACCES') {
+    reason = 'permission_denied';
+  } else if (msg.includes('disk') || msg.includes('space') || err?.code === 'ENOSPC') {
+    reason = 'disk_full';
+  } else if (msg.includes('network') || msg.includes('getaddrinfo') || msg.includes('enetunreach')) {
+    reason = 'network';
+  }
+
+  const rawDetail = err?.stderr?.trim?.() || err?.message || String(err);
+  const detail = rawDetail.slice(-500);
+
+  return { reason, detail, exitCode: err?.exitCode ?? null };
+}
+
 /**
  * Main setup wizard. Handles the full onboarding flow:
  * 1. Router installation (Python venv + pip)
@@ -124,22 +158,26 @@ export async function runWizard({ nonInteractive = false } = {}) {
     results.router = true;
   } else {
     const python = findPython();
-    if (!python) {
-      warn('Python 3.10+ not found — skipping Router installation');
-      info('Install Python from https://python.org and re-run this wizard');
-      info('Scraper works without Python');
-    } else {
+    if (python) {
       info(`Found Python ${python.version} (${python.bin})`);
-      step('Installing Router (this may take a moment)...');
+    } else {
+      // No system Python — setupRouter() will bootstrap uv + install a
+      // standalone Python into ~/.robot-resources/. This used to be a hard
+      // fail; now it's the dominant auto-heal for the python_not_found
+      // cohort (2/3 of failures in recent telemetry).
+      warn('No system Python detected — bootstrapping one via uv.');
+      info('This downloads the uv binary (~15MB) and a managed Python to ~/.robot-resources/');
+    }
+    step('Installing Router (this may take a moment)...');
 
-      try {
-        await setupRouter();
-        success('Router installed');
-        results.router = true;
-      } catch (err) {
-        error(`Router installation failed: ${err.message}`);
-        results.routerError = 'install-failed';
-      }
+    try {
+      const { pythonSource } = await setupRouter();
+      success(`Router installed${pythonSource === 'uv' ? ' (uv-managed Python)' : ''}`);
+      results.router = true;
+      results.pythonSource = pythonSource;
+    } catch (err) {
+      error(`Router installation failed: ${err.message}`);
+      results.routerError = classifyRouterError(err);
     }
   }
 
@@ -298,15 +336,27 @@ export async function runWizard({ nonInteractive = false } = {}) {
     try {
       const config = readConfig();
       const platformUrl = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
+      const installPayload = {
+        router: results.router || false,
+        service: results.service || false,
+        scraper: results.scraper || false,
+        source: 'wizard',
+      };
+      if (results.pythonSource) {
+        // 'system' when the user had Python installed, 'uv' when we
+        // auto-bootstrapped one. Lets us measure how many installs were
+        // rescued by the uv fallback.
+        installPayload.pythonSource = results.pythonSource;
+      }
+      if (results.routerError && typeof results.routerError === 'object') {
+        installPayload.routerError = results.routerError.reason;
+        installPayload.routerErrorDetail = results.routerError.detail;
+        installPayload.platform = process.platform;
+      }
       const body = JSON.stringify({
         product: 'cli',
         event_type: 'install_complete',
-        payload: {
-          router: results.router || false,
-          service: results.service || false,
-          scraper: results.scraper || false,
-          source: 'wizard',
-        },
+        payload: installPayload,
       });
 
       for (let attempt = 0; attempt < 2; attempt++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robot-resources",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Robot Resources — AI agent tools. One command to install everything.",
   "type": "module",
   "bin": {