robot-resources 1.9.2 → 1.9.4

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

@@ -19,12 +19,25 @@ import { header, step, success, warn, error, info, blank, summary } from './ui.j
  */
 function classifyRouterError(err) {
   const msg = (err?.message || String(err)).toLowerCase();
+  const stderr = (err?.stderr || '').toString().toLowerCase();
+  const combined = msg + '\n' + stderr;
   let reason = 'unknown';
 
-  if (msg.includes('python 3.10+') || msg.includes('python is required')) {
+  // Order matters — check specific patterns before generic ones.
+  // python_venv_missing is specific (Debian/Ubuntu ships python3 without
+  // the venv module) — previously showed up as 'unknown' in telemetry.
+  if (/python venv module|ensurepip.*not (installed|available)|python\d*-venv/.test(combined)) {
+    reason = 'python_venv_missing';
+  } else 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 (/failed building wheel|metadata-generation-failed|cargo|rust compiler|subprocess-exited-with-error/.test(combined)) {
+    // Wheel-build failures: pip tried to compile a native dep from source
+    // because no binary wheel was available for the user's platform. This
+    // was silently categorized as 'pip_install_failed' before — surfacing
+    // it separately lets us see affected packages in aggregate.
+    reason = 'wheel_build_failed';
   } 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')) {
@@ -158,24 +171,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');
-      // Record the reason so install_complete tells us why router=false.
-      results.routerError = { reason: 'python_not_found', detail: 'Python 3.10+ not detected on PATH' };
-    } 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 = classifyRouterError(err);
-      }
+    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);
     }
   }
 
@@ -340,6 +355,12 @@ export async function runWizard({ nonInteractive = 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;

package/package.json

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