robot-resources 1.12.4 → 1.14.0

package/lib/install-node-shim.js

@@ -1,65 +1,110 @@
 import { writeShellLine, hasShellLine } from './shell-config.js';
 import { readConfig } from './config.mjs';
 import { detectNodeAgent } from './detect.js';
+import { installRouterFiles } from './install-router-files.js';
+import { writePersistedNodeOptions } from './windows-env.js';
 
 const PLATFORM_URL = process.env.RR_PLATFORM_URL || 'https://api.robotresources.ai';
 
 /**
- * Install the Node shim into the user's shell config. Phase 3 entry for
- * the non-OC Node path.
+ * Install the Node shim into the user's shell config (POSIX) or user
+ * environment registry (Windows).
  *
- * Steps:
- *   1. Append the marker block to detected rc files (zsh / bash / fish)
- *      via shell-config.writeShellLine. Idempotent: re-running does nothing
- *      if the block is already present.
- *   2. Emit `node_shim_installed` telemetry with the shell list, sdks
- *      detected, dry-run flag, plus per-file errors.
+ * POSIX path (Phases 3 + 8):
+ *   1. Copy `@robot-resources/router` to ~/.robot-resources/router/
+ *      (absolute path; survives cwd changes + npm/npx cache cleanup).
+ *   2. Append marker block with `--require <abs path>` to detected rc files
+ *      (zsh / bash / fish).
  *
- * The user has to start a new shell (or `source` the file) for the
- * NODE_OPTIONS to take effect — we tell them this in the wizard's
- * post-install message. For Phase 3 we don't try to mutate the running
- * shell; that's a Phase 6 nice-to-have.
+ * Windows path (Phase 9):
+ *   1. Same router-files copy — `homedir()` is platform-aware.
+ *   2. `setx NODE_OPTIONS "..."` writes to HKCU\\Environment so every new
+ *      cmd / PowerShell / Win+R-launched Node process inherits it.
  *
- * Windows: shell-config.writeShellLine returns no rc files on Windows
- * (we only support POSIX in P3). The wizard prints manual instructions
- * for Windows users in `non-oc-wizard.js`.
+ * Both paths emit `node_shim_installed` telemetry. The user has to open a
+ * new terminal for the change to take effect.
  *
  * Returns a UI-friendly result the wizard can format and print.
  */
 export async function installNodeShim({ cwd = process.cwd(), dryRun = false } = {}) {
-  if (process.platform === 'win32') {
+  const sdks = detectSdks(cwd);
+
+  if (dryRun) {
+    await emit({
+      shell: 'dryrun',
+      shell_config_path: null,
+      sdks_detected: sdks,
+      dry_run: true,
+      reason: null,
+    });
+    return { ok: true, message: 'Dry-run: would have written NODE_OPTIONS.' };
+  }
+
+  // Phase 8: copy router to an absolute path under ~/.robot-resources/router/
+  // before we wire the env config. If the copy fails, we don't write a
+  // broken NODE_OPTIONS line on either platform.
+  let autoPath;
+  try {
+    autoPath = installRouterFiles();
+  } catch (err) {
     await emit({
-      shell: 'unsupported',
+      shell: process.platform === 'win32' ? 'win32' : 'unknown',
       shell_config_path: null,
-      sdks_detected: detectSdks(cwd),
-      dry_run: dryRun,
-      reason: 'windows_not_supported_yet',
+      sdks_detected: sdks,
+      dry_run: false,
+      reason: 'router_copy_failed',
+      error_messages: [err.message],
     });
     return {
       ok: false,
-      reason: 'windows_not_supported_yet',
-      message:
-        'Windows shell-config writing is not yet supported. Set ' +
-        'NODE_OPTIONS=--require @robot-resources/router/auto manually in your ' +
-        'system environment variables, or wait for Phase 6.',
+      message: `Could not copy router files to ~/.robot-resources/router/: ${err.message}`,
     };
   }
 
-  const sdks = detectSdks(cwd);
-
-  if (dryRun) {
+  // Windows branch — Phase 9. Mirrors the POSIX flow in shape: detect
+  // already-installed via the persisted registry value, write via setx,
+  // emit equivalent telemetry.
+  if (process.platform === 'win32') {
+    const winResult = writePersistedNodeOptions({ autoPath });
     await emit({
-      shell: 'dryrun',
-      shell_config_path: null,
+      shell: 'win32',
+      shell_config_path: 'HKCU\\Environment\\NODE_OPTIONS',
       sdks_detected: sdks,
-      dry_run: true,
-      reason: null,
+      dry_run: false,
+      already_installed: !!winResult.already,
+      files_written: winResult.ok && !winResult.already ? 1 : 0,
+      files_with_errors: winResult.ok ? 0 : 1,
+      error_messages: winResult.ok ? [] : [winResult.error_message || winResult.reason || 'unknown'],
+      auto_path: autoPath,
+      win_node_options_length: winResult.length,
+      reason: winResult.ok ? null : winResult.reason,
     });
-    return { ok: true, message: 'Dry-run: would have written NODE_OPTIONS to shell rc.' };
+    if (winResult.ok && winResult.already) {
+      return {
+        ok: true,
+        already: true,
+        message: 'NODE_OPTIONS already includes the auto-attach line. No changes made.',
+      };
+    }
+    if (!winResult.ok) {
+      return {
+        ok: false,
+        reason: winResult.reason,
+        message: `Could not set NODE_OPTIONS via setx (${winResult.reason}): ${winResult.error_message || ''}`,
+      };
+    }
+    return {
+      ok: true,
+      written: ['HKCU\\Environment\\NODE_OPTIONS'],
+      errors: [],
+      message:
+        'Set NODE_OPTIONS in your user environment (HKCU\\Environment). ' +
+        'Open a new terminal for it to take effect. Existing terminals will not see the change.',
+    };
   }
 
   const alreadyInstalled = hasShellLine();
-  const result = writeShellLine();
+  const result = writeShellLine({ autoPath });
 
   // Single shell value for the funnel even though we may have written to
   // multiple rc files. Pick the dominant one for telemetry.
@@ -74,6 +119,7 @@ export async function installNodeShim({ cwd = process.cwd(), dryRun = false } =
     files_written: result.written.length,
     files_with_errors: result.errors.length,
     error_messages: result.errors.map((e) => `${e.path}: ${e.message}`).slice(0, 3),
+    auto_path: autoPath,
   });
 
   if (alreadyInstalled && result.written.length === 0) {

package/lib/install-router-files.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, copyFileSync, cpSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Copy `@robot-resources/router` to ~/.robot-resources/router/ and return
+ * the absolute path to its auto.cjs.
+ *
+ * Phase 8 fix. Mirrors `installPluginFiles()` in tool-config.js (the OC
+ * plugin path that's worked since Phase 0). The destination is a stable
+ * user-scoped location that survives npm/npx cache cleanups, so the
+ * NODE_OPTIONS line we write to shell rc doesn't break when caches expire.
+ *
+ * Files copied: auto.cjs, index.js, package.json, lib/ (recursive).
+ * Each call wipes lib/ first so files removed in newer router versions
+ * don't linger from a previous install.
+ *
+ * Why this is its own module: extracted from install-node-shim.js for
+ * testability — vitest can mock the whole module without us mocking
+ * node:fs / node:module manually in every install-shim test case.
+ */
+export function installRouterFiles({ home = homedir() } = {}) {
+  const pkgPath = require.resolve('@robot-resources/router/package.json');
+  const pkgDir = dirname(pkgPath);
+  const targetDir = join(home, '.robot-resources', 'router');
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const file of ['auto.cjs', 'index.js', 'package.json']) {
+    const src = join(pkgDir, file);
+    if (existsSync(src)) {
+      copyFileSync(src, join(targetDir, file));
+    }
+  }
+
+  // Refresh lib/ — wipe + recopy so we don't accumulate stale files across
+  // router upgrades. Same pattern as tool-config.js installPluginFiles().
+  const srcLib = join(pkgDir, 'lib');
+  const dstLib = join(targetDir, 'lib');
+  if (existsSync(srcLib)) {
+    rmSync(dstLib, { recursive: true, force: true });
+    cpSync(srcLib, dstLib, { recursive: true });
+  }
+
+  return join(targetDir, 'auto.cjs');
+}

package/lib/non-oc-wizard.js

@@ -107,12 +107,21 @@ async function showJsPath() {
     blank();
     info('Once your shell picks up the new NODE_OPTIONS, every Node agent on');
     info('this machine routes Anthropic SDK calls through Robot Resources.');
-    info('Open a new terminal — or run:  source ~/.zshrc   (or your shell rc)');
+    if (process.platform === 'win32') {
+      info('Open a new cmd / PowerShell window — current terminals will not see the change.');
+    } else {
+      info('Open a new terminal — or run:  source ~/.zshrc   (or your shell rc)');
+    }
   } else {
     warn(result.message);
     blank();
-    info('Manual install (paste into ~/.zshrc or ~/.bashrc):');
-    info('  export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"');
+    if (process.platform === 'win32') {
+      info('Manual install: in a new cmd, run:');
+      info('  setx NODE_OPTIONS "--require %USERPROFILE%\\.robot-resources\\router\\auto.cjs"');
+    } else {
+      info('Manual install (paste into ~/.zshrc or ~/.bashrc):');
+      info('  export NODE_OPTIONS="${NODE_OPTIONS:-} --require ~/.robot-resources/router/auto.cjs"');
+    }
   }
   blank();
   info('Docs: https://robotresources.ai/docs/langchain');

package/lib/shell-config.js

@@ -11,10 +11,19 @@ import { join } from 'node:path';
  * regex-matching against the user's actual shell content:
  *
  *     # >>> robot-resources: NODE_OPTIONS auto-attach >>>
- *     export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"
+ *     export NODE_OPTIONS="${NODE_OPTIONS:-} --require /Users/x/.robot-resources/router/auto.cjs"
  *     # <<< robot-resources <<<
  *
- * Behavior decisions (see plan):
+ * Phase 8 fix: NODE_OPTIONS now uses an ABSOLUTE PATH to the auto.cjs the
+ * wizard copied to ~/.robot-resources/router/. The previous bare-module
+ * form `--require @robot-resources/router/auto` only resolved when the user
+ * was cd'd inside a project that had `@robot-resources/router` in its
+ * node_modules — and broke EVERY Node command from any other cwd with
+ * `Cannot find module`. Result: every wizard-success Node user pre-Phase-8
+ * had a NODE_OPTIONS line that crashed `node`/`npm`/etc. Symptom in
+ * Supabase: `node_shim_installed: 8` but `adapter_attached: 0`.
+ *
+ * Behavior decisions (preserved from Phase 3):
  *   - If NODE_OPTIONS is already set with a different --require (rare; e.g.
  *     dd-trace), append ours after theirs. Both load. The user keeps their
  *     existing tooling. The shell expansion `${NODE_OPTIONS:-} ...` handles
@@ -27,12 +36,14 @@ import { join } from 'node:path';
 const MARK_BEGIN = '# >>> robot-resources: NODE_OPTIONS auto-attach >>>';
 const MARK_END = '# <<< robot-resources <<<';
 
-const POSIX_LINE =
-  'export NODE_OPTIONS="${NODE_OPTIONS:-} --require @robot-resources/router/auto"';
+function buildPosixLine(autoPath) {
+  return `export NODE_OPTIONS="\${NODE_OPTIONS:-} --require ${autoPath}"`;
+}
 
-// Fish has different syntax (no `export`, uses `set -x`). Detected separately.
-const FISH_LINE =
-  'set -x NODE_OPTIONS "$NODE_OPTIONS --require @robot-resources/router/auto"';
+function buildFishLine(autoPath) {
+  // Fish has different syntax (no `export`, uses `set -x`).
+  return `set -x NODE_OPTIONS "$NODE_OPTIONS --require ${autoPath}"`;
+}
 
 /**
  * Discover which rc files are present for this user. Returns a list of
@@ -73,7 +84,11 @@ export function hasShellLine(home = homedir()) {
  * others on one failure. Per-file errors are returned as warnings the
  * caller can surface.
  */
-export function writeShellLine(home = homedir()) {
+export function writeShellLine({ autoPath, home = homedir() }) {
+  if (!autoPath) {
+    throw new Error('writeShellLine requires { autoPath } — absolute path to auto.cjs');
+  }
+
   const rcs = listShellRcFiles(home);
   const written = [];
   const errors = [];
@@ -97,7 +112,7 @@ export function writeShellLine(home = homedir()) {
         continue;
       }
 
-      const line = rc.kind === 'fish' ? FISH_LINE : POSIX_LINE;
+      const line = rc.kind === 'fish' ? buildFishLine(autoPath) : buildPosixLine(autoPath);
       const block =
         (text && !text.endsWith('\n') ? '\n' : '') +
         '\n' + MARK_BEGIN + '\n' + line + '\n' + MARK_END + '\n';
@@ -165,4 +180,4 @@ function getMode(path) {
 }
 
 // Exported for tests + telemetry payloads.
-export { MARK_BEGIN, MARK_END, POSIX_LINE, FISH_LINE };
+export { MARK_BEGIN, MARK_END, buildPosixLine, buildFishLine };

package/lib/uninstall.js

@@ -5,6 +5,7 @@ import { stripJson5 } from './json5.js';
 import { removeShellLine } from './shell-config.js';
 import { detectVenv } from './venv-detect.js';
 import { spawnSync } from 'node:child_process';
+import { removePersistedNodeOptions } from './windows-env.js';
 
 /**
  * Single source of truth for `npx robot-resources --uninstall`.
@@ -86,18 +87,45 @@ export function runUninstall({ purge = false } = {}) {
     }
   }
 
-  // 3. Shell config — remove the NODE_OPTIONS marker block from any rc
-  //    files Phase 3's wizard wrote to. Idempotent: no-op if not present.
-  try {
-    const result = removeShellLine();
-    if (result.removed.length > 0) {
-      components_removed.push('shell_config_node_options');
+  // 3. Shell config / Windows registry — remove the NODE_OPTIONS line
+  //    Phase 3's wizard wrote to. Idempotent: no-op if not present.
+  if (process.platform === 'win32') {
+    // Phase 9: restore from backup or clear HKCU\Environment\NODE_OPTIONS.
+    try {
+      const result = removePersistedNodeOptions();
+      if (result.ok && result.action !== 'noop') {
+        components_removed.push(`win_node_options_${result.action}`);
+      } else if (!result.ok) {
+        errors.push({ component: 'win_node_options', message: 'reg_restore_failed' });
+      }
+    } catch (err) {
+      errors.push({ component: 'win_node_options', message: err.message });
+    }
+  } else {
+    try {
+      const result = removeShellLine();
+      if (result.removed.length > 0) {
+        components_removed.push('shell_config_node_options');
+      }
+      for (const e of result.errors) {
+        errors.push({ component: 'shell_config_node_options', message: `${e.path}: ${e.message}` });
+      }
+    } catch (err) {
+      errors.push({ component: 'shell_config_node_options', message: err.message });
     }
-    for (const e of result.errors) {
-      errors.push({ component: 'shell_config_node_options', message: `${e.path}: ${e.message}` });
+  }
+
+  // 3b. Copied router dir at ~/.robot-resources/router/ (Phase 8). The shell
+  //     line points at this absolute path — once the line is gone, the
+  //     copied files are dead weight. Remove them.
+  const routerDir = join(homedir(), '.robot-resources', 'router');
+  if (existsSync(routerDir)) {
+    try {
+      rmSync(routerDir, { recursive: true, force: true });
+      components_removed.push('node_shim_router_dir');
+    } catch (err) {
+      errors.push({ component: 'node_shim_router_dir', message: err.message });
     }
-  } catch (err) {
-    errors.push({ component: 'shell_config_node_options', message: err.message });
   }
 
   // 4. Python shim — `pip uninstall -y robot-resources` against the resolved

package/lib/windows-env.js

@@ -0,0 +1,202 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Windows NODE_OPTIONS persistence (Phase 9).
+ *
+ * The POSIX path uses a marker block in `~/.bashrc` / `~/.zshrc`. Windows
+ * has no equivalent shell rc that all Node-launched processes read — cmd,
+ * PowerShell, and Win+R-launched .exe all draw env vars from the user
+ * registry under HKCU\Environment.
+ *
+ * `setx NODE_OPTIONS "value"` writes there. New processes pick it up.
+ * The current shell does NOT see the change — user has to open a new
+ * terminal. Same UX caveat as POSIX.
+ *
+ * Why not edit PowerShell `$PROFILE`: ExecutionPolicy on locked-down
+ * corporate fleets often blocks unsigned `.ps1`. cmd-launched Node
+ * processes also miss it. setx is universal across both.
+ *
+ * Idempotency: we read the persisted NODE_OPTIONS via `reg query` (not
+ * `process.env.NODE_OPTIONS`, which is the current-shell value, not the
+ * persistent one). If our `--require <auto>` is already present, no-op.
+ *
+ * Uninstall: backup the user's PRE-modification value to
+ * `~/.robot-resources/windows-prior-node-options.txt`. On `--uninstall`,
+ * restore from backup; if the backup is missing or empty, clear the var.
+ *
+ * Truncation note: `setx` truncates values at 1024 chars. If a user
+ * already has a long NODE_OPTIONS plus other dev tooling, we may be
+ * close to the limit. We surface the merged length in telemetry so we
+ * can spot truncation in Supabase.
+ */
+
+const REG_PATH = 'HKCU\\Environment';
+const VAR_NAME = 'NODE_OPTIONS';
+const SETX_LIMIT = 1024;
+
+function backupFilePath(home = homedir()) {
+  return join(home, '.robot-resources', 'windows-prior-node-options.txt');
+}
+
+/**
+ * Read the persisted NODE_OPTIONS value from HKCU\Environment.
+ * Returns the string (possibly empty) or null if reading failed.
+ */
+export function readPersistedNodeOptions() {
+  const res = spawnSync(
+    'reg.exe',
+    ['query', REG_PATH, '/v', VAR_NAME],
+    { stdio: 'pipe', encoding: 'utf-8' },
+  );
+  if (res.status !== 0) {
+    // `reg query` returns non-zero when the value doesn't exist. That's a
+    // valid state — empty NODE_OPTIONS — not an error.
+    const stderr = (res.stderr || '').toLowerCase();
+    if (stderr.includes('unable to find') || stderr.includes('not exist')) {
+      return '';
+    }
+    return null;
+  }
+  // Output looks like:
+  //   HKEY_CURRENT_USER\Environment
+  //       NODE_OPTIONS    REG_SZ    --require ...
+  // We extract the value after REG_SZ. The value can contain spaces; take
+  // everything after the last "REG_SZ" occurrence on its line.
+  const lines = (res.stdout || '').split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/^\s*NODE_OPTIONS\s+REG_(?:SZ|EXPAND_SZ)\s+(.*)$/);
+    if (m) return m[1].trim();
+  }
+  return '';
+}
+
+/**
+ * Set NODE_OPTIONS in HKCU\Environment to the given value (idempotent
+ * append of `--require <autoPath>` to whatever was there).
+ *
+ * Returns:
+ *   { ok: true,  already: boolean, prior: string, written: string, length: number }
+ *   { ok: false, reason, error_message? }
+ */
+export function writePersistedNodeOptions({ autoPath, home = homedir() }) {
+  if (!autoPath) {
+    return { ok: false, reason: 'missing_auto_path' };
+  }
+
+  const prior = readPersistedNodeOptions();
+  if (prior === null) {
+    return { ok: false, reason: 'reg_query_failed' };
+  }
+
+  // Quote the path so a path with spaces survives Node's --require parser.
+  // Node accepts both quoted and unquoted forms; quoting is safer.
+  const ourArg = `--require "${autoPath}"`;
+
+  if (prior.includes(ourArg) || prior.includes(`--require ${autoPath}`)) {
+    return {
+      ok: true,
+      already: true,
+      prior,
+      written: prior,
+      length: prior.length,
+    };
+  }
+
+  const merged = prior ? `${prior} ${ourArg}` : ourArg;
+
+  if (merged.length > SETX_LIMIT) {
+    // setx truncates silently at 1024 chars. Refuse rather than write a
+    // broken value. User must shorten their existing NODE_OPTIONS first.
+    return {
+      ok: false,
+      reason: 'setx_limit_exceeded',
+      error_message: `merged value is ${merged.length} chars; setx truncates at ${SETX_LIMIT}`,
+      length: merged.length,
+    };
+  }
+
+  // Backup the prior value BEFORE writing, so --uninstall can restore.
+  // Even if backup write fails (disk full, permissions), we still proceed —
+  // the registry-level setx is the source of truth, the backup is just a
+  // convenience for restore.
+  try {
+    const backup = backupFilePath(home);
+    mkdirSync(join(home, '.robot-resources'), { recursive: true });
+    writeFileSync(backup, prior, { encoding: 'utf-8' });
+  } catch {
+    // Best-effort backup; continue.
+  }
+
+  const setxRes = spawnSync(
+    'setx.exe',
+    [VAR_NAME, merged],
+    { stdio: 'pipe', encoding: 'utf-8' },
+  );
+  if (setxRes.status !== 0) {
+    const stderr = (setxRes.stderr || '').toString().trim();
+    return {
+      ok: false,
+      reason: 'setx_failed',
+      error_message: stderr.slice(0, 200) || `exit ${setxRes.status}`,
+      length: merged.length,
+    };
+  }
+
+  return {
+    ok: true,
+    already: false,
+    prior,
+    written: merged,
+    length: merged.length,
+  };
+}
+
+/**
+ * Reverse `writePersistedNodeOptions`. Reads the backup file (if present)
+ * and restores that value via setx. If no backup is present or the backup
+ * is empty, clears the registry value entirely (`reg delete`).
+ *
+ * Returns { ok, restored_to: string, action: 'restored'|'cleared'|'noop' }
+ */
+export function removePersistedNodeOptions({ home = homedir() } = {}) {
+  const current = readPersistedNodeOptions();
+  if (current === null) return { ok: false, action: 'noop' };
+  if (current === '') return { ok: true, restored_to: '', action: 'noop' };
+
+  const backupPath = backupFilePath(home);
+  let priorValue = '';
+  if (existsSync(backupPath)) {
+    try { priorValue = readFileSync(backupPath, 'utf-8'); } catch { /* */ }
+  }
+
+  if (priorValue === '') {
+    // No prior value to restore — clear the var entirely.
+    const res = spawnSync(
+      'reg.exe',
+      ['delete', REG_PATH, '/v', VAR_NAME, '/f'],
+      { stdio: 'pipe', encoding: 'utf-8' },
+    );
+    if (existsSync(backupPath)) try { unlinkSync(backupPath); } catch { /* */ }
+    return {
+      ok: res.status === 0,
+      restored_to: '',
+      action: 'cleared',
+    };
+  }
+
+  // Restore the prior value.
+  const res = spawnSync(
+    'setx.exe',
+    [VAR_NAME, priorValue],
+    { stdio: 'pipe', encoding: 'utf-8' },
+  );
+  if (existsSync(backupPath)) try { unlinkSync(backupPath); } catch { /* */ }
+  return {
+    ok: res.status === 0,
+    restored_to: priorValue,
+    action: 'restored',
+  };
+}

package/package.json

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