dr-claw 1.1.3 → 1.1.4

package/server/routes/cli-auth.js

@@ -25,6 +25,9 @@ const PROVIDER_INSTALLERS = {
       darwin: [
         { bin: 'brew', args: ['install', 'claude-code'], label: 'brew install claude-code' },
       ],
+      linux: [
+        { bin: 'npm', args: ['install', '-g', '@anthropic-ai/claude-code'], label: 'npm install -g @anthropic-ai/claude-code' },
+      ],
       win32: [
         { bin: 'winget', args: ['install', '--id', 'Anthropic.ClaudeCode', '-e'], label: 'winget install Anthropic.ClaudeCode' },
       ],
@@ -51,6 +54,9 @@ const PROVIDER_INSTALLERS = {
       darwin: [
         { bin: 'npm', args: ['install', '-g', '@openai/codex'], label: 'npm install -g @openai/codex' },
       ],
+      linux: [
+        { bin: 'npm', args: ['install', '-g', '@openai/codex'], label: 'npm install -g @openai/codex' },
+      ],
       win32: [
         { bin: 'npm.cmd', args: ['install', '-g', '@openai/codex'], label: 'npm install -g @openai/codex' },
       ],
@@ -64,11 +70,42 @@ const PROVIDER_INSTALLERS = {
       darwin: [
         { bin: 'npm', args: ['install', '-g', '@google/gemini-cli'], label: 'npm install -g @google/gemini-cli' },
       ],
+      linux: [
+        { bin: 'npm', args: ['install', '-g', '@google/gemini-cli'], label: 'npm install -g @google/gemini-cli' },
+      ],
       win32: [
         { bin: 'npm.cmd', args: ['install', '-g', '@google/gemini-cli'], label: 'npm install -g @google/gemini-cli' },
       ],
     },
   },
+  nano: {
+    displayName: 'Nano Claude Code',
+    docsUrl: 'https://github.com/OpenLAIR/nano-claude-code',
+    fallbackDownloadUrl: 'https://github.com/OpenLAIR/nano-claude-code',
+    commands: {
+      darwin: [
+        {
+          bin: 'pip3',
+          args: ['install', '-U', 'git+https://github.com/OpenLAIR/nano-claude-code.git'],
+          label: 'pip3 install from GitHub (recommended)',
+        },
+      ],
+      linux: [
+        {
+          bin: 'pip3',
+          args: ['install', '-U', 'git+https://github.com/OpenLAIR/nano-claude-code.git'],
+          label: 'pip3 install from GitHub (use a venv if your distro manages system Python)',
+        },
+      ],
+      win32: [
+        {
+          bin: 'pip',
+          args: ['install', '-U', 'git+https://github.com/OpenLAIR/nano-claude-code.git'],
+          label: 'pip install from GitHub',
+        },
+      ],
+    },
+  },
 };
 
 function buildCliInstallHint(agent) {
@@ -88,6 +125,8 @@ function buildCliInstallHint(agent) {
       return 'Gemini CLI is not installed. Install it first, then retry login.';
     case 'openrouter':
       return 'Set OPENROUTER_API_KEY in your .env file. Get a key at https://openrouter.ai/keys';
+    case 'nano':
+      return 'nano-claude-code is not on PATH. Install from https://github.com/OpenLAIR/nano-claude-code or set NANO_CLAUDE_CODE_COMMAND to the executable.';
     default:
       return 'Required CLI is not installed. Install it first, then retry login.';
   }
@@ -217,6 +256,30 @@ router.get('/providers', async (_req, res) => {
   }
 });
 
+async function checkNanoCliForInstall() {
+  const resolvedCliCommand = await resolveAvailableCliCommand({
+    envVarName: 'NANO_CLAUDE_CODE_COMMAND',
+    defaultCommands: ['nano-claude-code'],
+    args: ['--version'],
+    appendWindowsSuffixes: true,
+  });
+  if (!resolvedCliCommand) {
+    return {
+      authenticated: false,
+      email: null,
+      error: 'nano-claude-code CLI not found',
+      cliAvailable: false,
+      cliCommand: 'nano-claude-code',
+    };
+  }
+  return {
+    authenticated: true,
+    email: 'Nano Claude Code',
+    cliAvailable: true,
+    cliCommand: resolvedCliCommand,
+  };
+}
+
 router.post('/install/:provider', async (req, res) => {
   const provider = String(req.params.provider || '').toLowerCase();
   const definition = getInstallerDefinition(provider);
@@ -230,7 +293,7 @@ router.post('/install/:provider', async (req, res) => {
     return res.status(400).json({
       ok: false,
       provider,
-      error: `No automatic installer is configured for ${definition.displayName} on ${process.platform}`,
+      error: `No automatic installer is configured for ${definition.displayName} on ${process.platform}. See the official docs for manual Linux steps.`,
       docsUrl: definition.docsUrl,
       downloadUrl: definition.fallbackDownloadUrl,
     });
@@ -245,7 +308,9 @@ router.post('/install/:provider', async (req, res) => {
       ? checkCursorStatus
       : provider === 'codex'
         ? checkCodexCredentials
-        : checkGeminiCredentials;
+        : provider === 'nano'
+          ? checkNanoCliForInstall
+          : checkGeminiCredentials;
 
   const latestStatus = await checker();
 
@@ -371,6 +436,42 @@ router.get('/gemini/status', async (req, res) => {
   }
 });
 
+router.get('/nano/status', async (req, res) => {
+  try {
+    const resolvedCliCommand = await resolveAvailableCliCommand({
+      envVarName: 'NANO_CLAUDE_CODE_COMMAND',
+      defaultCommands: ['nano-claude-code'],
+      args: ['--version'],
+      appendWindowsSuffixes: true,
+    });
+
+    if (!resolvedCliCommand) {
+      return res.json(buildStatusPayload({
+        authenticated: false,
+        email: null,
+        error: 'nano-claude-code CLI not found',
+        cliAvailable: false,
+        cliCommand: 'nano-claude-code',
+        installHint: buildCliInstallHint('nano'),
+      }, 'nano'));
+    }
+
+    return res.json(buildStatusPayload({
+      authenticated: true,
+      email: 'Nano Claude Code',
+      cliAvailable: true,
+      cliCommand: resolvedCliCommand,
+    }, 'nano'));
+  } catch (error) {
+    console.error('Error checking Nano Claude Code status:', error);
+    res.status(500).json({
+      authenticated: false,
+      email: null,
+      error: error.message,
+    });
+  }
+});
+
 async function checkGeminiCredentials() {
   console.log('[DEBUG] Checking Gemini credentials...');
   let cliCommand = process.env.GEMINI_CLI_PATH || 'gemini';

package/server/routes/commands.js

@@ -126,6 +126,12 @@ const builtInCommands = [
     description: 'Rewind the conversation to a previous state',
     namespace: 'builtin',
     metadata: { type: 'builtin' }
+  },
+  {
+    name: '/btw',
+    description: 'Ask a quick side question in an overlay (Claude only; does not add to chat history)',
+    namespace: 'builtin',
+    metadata: { type: 'builtin' }
   }
 ];
 
@@ -396,7 +402,25 @@ Custom commands can be created in:
         message: `Rewinding conversation by ${steps} step${steps > 1 ? 's' : ''}...`
       }
     };
-  }
+  },
+
+  '/btw': async (args) => {
+    const question = args.join(' ').trim();
+    if (!question) {
+      return {
+        type: 'builtin',
+        action: 'btw',
+        data: {
+          error: 'Usage: /btw <your question>',
+        },
+      };
+    }
+    return {
+      type: 'builtin',
+      action: 'btw',
+      data: { question },
+    };
+  },
 };
 
 /**

package/server/routes/community-tools.js

@@ -121,27 +121,32 @@ router.post('/configure', async (req, res) => {
     // ── Step 2: Register MCP server ──
     if (mcpBackend) {
       try {
-        // Check if already registered
-        let alreadyRegistered = false;
-        try {
-          const { stdout } = await spawnAsync('claude', ['mcp', 'list'], { env: EXTENDED_ENV });
-          alreadyRegistered = stdout.includes(mcpBackend);
-        } catch {
-          // claude mcp list failed, proceed with registration
-        }
-
-        if (alreadyRegistered) {
-          results.steps.push({ step: 'mcp', status: 'skipped', message: `${mcpBackend} MCP already registered` });
-        } else {
-          const mcpCommands = {
-            codex: ['mcp', 'add', 'codex', '-s', 'user', '--', 'codex', 'mcp-server'],
-            'llm-chat': ['mcp', 'add', 'llm-chat', '-s', 'user', '--', 'python3', path.join(resolvedPath, 'skills/aris-infra/mcp-servers/llm-chat/server.py')],
-            gemini: ['mcp', 'add', 'gemini-review', '-s', 'user', '--', 'python3', path.join(resolvedPath, 'skills/aris-infra/mcp-servers/gemini-review/server.py')],
-          };
-
-          const args = mcpCommands[mcpBackend];
-          if (!args) {
+        const mcpCommands = {
+          codex: ['mcp', 'add', 'codex', '-s', 'user', '--', 'codex', 'mcp-server'],
+          'llm-chat': ['mcp', 'add', 'llm-chat', '-s', 'user', '--', 'python3', path.join(resolvedPath, 'skills/aris-infra/mcp-servers/llm-chat/server.py')],
+          gemini: ['mcp', 'add', 'gemini-review', '-s', 'user', '--', 'python3', path.join(resolvedPath, 'skills/aris-infra/mcp-servers/gemini-review/server.py')],
+        };
+
+        const ENV_ONLY_BACKENDS = ['gemini-figure'];
+        const args = mcpCommands[mcpBackend];
+        if (!args) {
+          if (ENV_ONLY_BACKENDS.includes(mcpBackend)) {
+            results.steps.push({ step: 'mcp', status: 'skipped', message: `No MCP server needed for ${mcpBackend}` });
+          } else {
             results.errors.push({ step: 'mcp', error: `Unknown backend: ${mcpBackend}` });
+          }
+        } else {
+          // Check if already registered
+          let alreadyRegistered = false;
+          try {
+            const { stdout } = await spawnAsync('claude', ['mcp', 'list'], { env: EXTENDED_ENV });
+            alreadyRegistered = stdout.includes(mcpBackend);
+          } catch {
+            // claude mcp list failed, proceed with registration
+          }
+
+          if (alreadyRegistered) {
+            results.steps.push({ step: 'mcp', status: 'skipped', message: `${mcpBackend} MCP already registered` });
           } else {
             await spawnAsync('claude', args, { env: EXTENDED_ENV });
             results.steps.push({ step: 'mcp', status: 'ok', message: `Registered ${mcpBackend} MCP server` });
@@ -200,7 +205,7 @@ router.post('/configure', async (req, res) => {
       let linked = 0;
       const entries = await fs.readdir(skillsDir, { withFileTypes: true });
       for (const entry of entries) {
-        if (entry.isDirectory() && (entry.name.startsWith('aris-') || entry.name === 'autoresearch')) {
+        if (entry.isDirectory() && (entry.name.startsWith('aris-') || entry.name.startsWith('inno-') || entry.name === 'autoresearch')) {
           const target = path.join(claudeSkillsDir, entry.name);
           try {
             await fs.access(target);

package/server/routes/memory.js

@@ -0,0 +1,143 @@
+import express from 'express';
+import { memoryDb } from '../database/db.js';
+import { syncMemoryFiles } from '../utils/memoryPrompt.js';
+
+const router = express.Router();
+const MAX_CONTENT_LENGTH = 500;
+const VALID_CATEGORIES = new Set(['general', 'preference', 'context', 'workflow']);
+
+/** Parse and validate :id param as a positive integer. */
+function parseId(raw) {
+  const id = parseInt(raw, 10);
+  return Number.isNaN(id) || id <= 0 ? null : id;
+}
+
+// ===============================
+// Memory CRUD
+// ===============================
+
+// Get all memories for the authenticated user
+router.get('/', async (req, res) => {
+  try {
+    const memories = memoryDb.getAll(req.user.id);
+    res.json({ memories });
+  } catch (error) {
+    console.error('Error fetching memories:', error);
+    res.status(500).json({ error: 'Failed to fetch memories' });
+  }
+});
+
+// Create a new memory
+router.post('/', async (req, res) => {
+  try {
+    const { content, category } = req.body;
+    if (!content || !content.trim()) {
+      return res.status(400).json({ error: 'Memory content is required' });
+    }
+    if (content.length > MAX_CONTENT_LENGTH) {
+      return res.status(400).json({ error: `Memory content must be ${MAX_CONTENT_LENGTH} characters or less` });
+    }
+    const cat = VALID_CATEGORIES.has(category) ? category : 'general';
+    const memory = memoryDb.create(req.user.id, content.trim(), cat);
+    syncMemoryFiles(req.user.id).catch(err => console.warn('[memory] sync error:', err.message));
+    res.status(201).json({ memory });
+  } catch (error) {
+    if (error.message?.includes('Maximum of')) {
+      return res.status(400).json({ error: error.message });
+    }
+    console.error('Error creating memory:', error);
+    res.status(500).json({ error: 'Failed to create memory' });
+  }
+});
+
+// Update a memory
+router.put('/:id', async (req, res) => {
+  try {
+    const id = parseId(req.params.id);
+    if (!id) return res.status(400).json({ error: 'Invalid memory ID' });
+
+    const { content, category } = req.body;
+    if (content !== undefined && content.length > MAX_CONTENT_LENGTH) {
+      return res.status(400).json({ error: `Memory content must be ${MAX_CONTENT_LENGTH} characters or less` });
+    }
+    const updates = {};
+    if (content !== undefined) updates.content = content.trim();
+    if (category !== undefined) updates.category = VALID_CATEGORIES.has(category) ? category : 'general';
+
+    const memory = memoryDb.update(req.user.id, id, updates);
+    if (!memory) {
+      return res.status(404).json({ error: 'Memory not found' });
+    }
+    syncMemoryFiles(req.user.id).catch(err => console.warn('[memory] sync error:', err.message));
+    res.json({ memory });
+  } catch (error) {
+    console.error('Error updating memory:', error);
+    res.status(500).json({ error: 'Failed to update memory' });
+  }
+});
+
+// Toggle memory enabled/disabled
+router.patch('/:id/toggle', async (req, res) => {
+  try {
+    const id = parseId(req.params.id);
+    if (!id) return res.status(400).json({ error: 'Invalid memory ID' });
+
+    const memory = memoryDb.toggle(req.user.id, id);
+    if (!memory) {
+      return res.status(404).json({ error: 'Memory not found' });
+    }
+    syncMemoryFiles(req.user.id).catch(err => console.warn('[memory] sync error:', err.message));
+    res.json({ memory });
+  } catch (error) {
+    console.error('Error toggling memory:', error);
+    res.status(500).json({ error: 'Failed to toggle memory' });
+  }
+});
+
+// Delete a memory
+router.delete('/:id', async (req, res) => {
+  try {
+    const id = parseId(req.params.id);
+    if (!id) return res.status(400).json({ error: 'Invalid memory ID' });
+
+    const deleted = memoryDb.delete(req.user.id, id);
+    if (!deleted) {
+      return res.status(404).json({ error: 'Memory not found' });
+    }
+    syncMemoryFiles(req.user.id).catch(err => console.warn('[memory] sync error:', err.message));
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error deleting memory:', error);
+    res.status(500).json({ error: 'Failed to delete memory' });
+  }
+});
+
+// ===============================
+// Per-User Memory Settings
+// ===============================
+
+// Get memory enabled state for the authenticated user
+router.get('/settings', async (req, res) => {
+  try {
+    const enabled = memoryDb.getMemoryEnabled(req.user.id);
+    res.json({ enabled });
+  } catch (error) {
+    console.error('Error fetching memory settings:', error);
+    res.status(500).json({ error: 'Failed to fetch memory settings' });
+  }
+});
+
+// Set memory enabled state for the authenticated user
+router.patch('/settings', async (req, res) => {
+  try {
+    const { enabled } = req.body;
+    memoryDb.setMemoryEnabled(req.user.id, !!enabled);
+    syncMemoryFiles(req.user.id).catch(err => console.warn('[memory] sync error:', err.message));
+    res.json({ enabled: !!enabled });
+  } catch (error) {
+    console.error('Error updating memory settings:', error);
+    res.status(500).json({ error: 'Failed to update memory settings' });
+  }
+});
+
+export default router;

package/server/routes/news.js

@@ -488,6 +488,9 @@ router.post('/search/:source', (req, res) => handleSearch(req.params.source, req
 // GET /api/news/logs/:source — poll search progress logs
 router.get('/logs/:source', async (req, res) => {
   try {
+    const entry = getSourceEntry(req.params.source);
+    if (!entry) return res.status(404).json({ error: `Unknown source: ${req.params.source}` });
+
     const logPath = path.join(DATA_DIR, `news-log-${req.params.source}.json`);
     const data = await fs.readFile(logPath, 'utf8');
     res.json({ logs: JSON.parse(data) });

package/server/routes/skills.js

@@ -5,6 +5,7 @@ import os from 'os';
 import { fileURLToPath } from 'url';
 import { extractProjectDirectory, ensureProjectSkillLinks } from '../projects.js';
 import { FORBIDDEN_PATHS } from './projects.js';
+import { findSkillMdPath } from '../utils/skillExpander.js';
 
 const GLOBAL_SKILLS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
 
@@ -223,6 +224,40 @@ async function validateZipBuffer(buffer) {
   };
 }
 
+// GET /resolve — resolve a skill name to its SKILL.md path and content
+router.get('/resolve', async (req, res) => {
+  try {
+    const { name, workingDir } = req.query;
+    if (!name || typeof name !== 'string') {
+      return res.status(400).json({ error: 'name query parameter is required' });
+    }
+    // Prevent path traversal
+    if (/[/\\]|\.\./.test(name)) {
+      return res.status(400).json({ error: 'Invalid skill name' });
+    }
+    const effectiveWorkingDir = (typeof workingDir === 'string' && workingDir.trim()) || process.cwd();
+    // Validate workingDir: must be absolute and not a forbidden system path
+    if (effectiveWorkingDir !== process.cwd()) {
+      if (!path.isAbsolute(effectiveWorkingDir)) {
+        return res.status(400).json({ error: 'workingDir must be an absolute path' });
+      }
+      const normalized = path.normalize(effectiveWorkingDir);
+      if (FORBIDDEN_PATHS.some((fp) => normalized === fp || normalized.startsWith(fp + path.sep))) {
+        return res.status(400).json({ error: 'Invalid workingDir' });
+      }
+    }
+    const skillMdPath = await findSkillMdPath(name, effectiveWorkingDir);
+    if (!skillMdPath) {
+      return res.status(404).json({ error: 'Skill not found' });
+    }
+    const content = await fs.readFile(skillMdPath, 'utf-8');
+    res.json({ path: skillMdPath, content });
+  } catch (error) {
+    console.error('[skills] resolve error:', error.message);
+    res.status(500).json({ error: error.message });
+  }
+});
+
 // GET / — return the file tree of the global skills/ directory
 router.get('/', async (req, res) => {
   try {

package/server/routes/user.js

@@ -2,10 +2,8 @@ import express from 'express';
 import { userDb } from '../database/db.js';
 import { authenticateToken } from '../middleware/auth.js';
 import { getSystemGitConfig } from '../utils/gitConfig.js';
-import { exec } from 'child_process';
-import { promisify } from 'util';
+import spawnAsync from '../utils/spawnAsync.js';
 
-const execAsync = promisify(exec);
 const router = express.Router();
 
 router.get('/git-config', authenticateToken, async (req, res) => {
@@ -55,8 +53,8 @@ router.post('/git-config', authenticateToken, async (req, res) => {
     userDb.updateGitConfig(userId, gitName, gitEmail);
 
     try {
-      await execAsync(`git config --global user.name "${gitName.replace(/"/g, '\\"')}"`);
-      await execAsync(`git config --global user.email "${gitEmail.replace(/"/g, '\\"')}"`);
+      await spawnAsync('git', ['config', '--global', 'user.name', gitName]);
+      await spawnAsync('git', ['config', '--global', 'user.email', gitEmail]);
       console.log(`Applied git config globally: ${gitName} <${gitEmail}>`);
     } catch (gitError) {
       console.error('Error applying git config:', gitError);

package/server/utils/__tests__/safePath.test.js

@@ -0,0 +1,93 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { safePath } from '../safePath.js';
+
+// Use a real temporary directory so realpathSync works correctly
+let ROOT;
+
+beforeAll(() => {
+  // Use realpathSync to normalize macOS /var -> /private/var symlink
+  ROOT = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'safepath-test-')));
+  fs.mkdirSync(path.join(ROOT, 'src'), { recursive: true });
+  fs.mkdirSync(path.join(ROOT, 'lib'), { recursive: true });
+  fs.writeFileSync(path.join(ROOT, 'src', 'index.js'), '');
+  fs.writeFileSync(path.join(ROOT, 'lib', 'utils.js'), '');
+});
+
+afterAll(() => {
+  fs.rmSync(ROOT, { recursive: true, force: true });
+});
+
+describe('safePath', () => {
+  it('resolves relative paths within root', () => {
+    const result = safePath('src/index.js', ROOT);
+    expect(result).toBe(path.join(ROOT, 'src', 'index.js'));
+  });
+
+  it('returns root when path is empty/null/undefined', () => {
+    expect(safePath('', ROOT)).toBe(ROOT);
+    expect(safePath(null, ROOT)).toBe(ROOT);
+    expect(safePath(undefined, ROOT)).toBe(ROOT);
+  });
+
+  it('allows absolute paths that land inside root', () => {
+    const absInside = path.join(ROOT, 'src', 'index.js');
+    const result = safePath(absInside, ROOT);
+    expect(result).toBe(absInside);
+  });
+
+  it('blocks absolute paths outside root', () => {
+    expect(() => safePath('/etc/passwd', ROOT)).toThrow(/Path traversal blocked/);
+  });
+
+  it('blocks .. traversal above root', () => {
+    expect(() => safePath('../../../etc/shadow', ROOT)).toThrow(/Path traversal blocked/);
+  });
+
+  it('blocks .. traversal disguised in deeper path', () => {
+    expect(() => safePath('src/../../../../../../etc/passwd', ROOT)).toThrow(
+      /Path traversal blocked/,
+    );
+  });
+
+  it('allows .. that stays within root', () => {
+    const result = safePath('src/../lib/utils.js', ROOT);
+    expect(result).toBe(path.join(ROOT, 'lib', 'utils.js'));
+  });
+
+  it('handles non-existent target gracefully', () => {
+    // Non-existent file in existing directory — should work
+    const result = safePath('src/newfile.js', ROOT);
+    expect(result).toBe(path.join(ROOT, 'src', 'newfile.js'));
+  });
+
+  it('handles non-existent nested path gracefully', () => {
+    // Non-existent nested path — should still resolve within root
+    const result = safePath('deep/nested/new/file.js', ROOT);
+    expect(result.startsWith(ROOT + path.sep)).toBe(true);
+  });
+
+  it('normalizes allowedRoot for falsy input', () => {
+    // Pass a non-normalized root (with trailing segments) to verify
+    // the falsy-input path returns path.resolve(allowedRoot), not the raw string.
+    const nonNormalized = ROOT + path.sep + 'src' + path.sep + '..';
+    const result = safePath('', nonNormalized);
+    expect(result).toBe(ROOT);
+  });
+
+  it('allows symlinks inside the project that point outside the root', () => {
+    // Simulate: project/data -> /tmp (an external location)
+    // This should NOT be blocked — legitimate workflow (shared datasets, etc.)
+    const linkPath = path.join(ROOT, 'external-data');
+    try {
+      fs.symlinkSync(os.tmpdir(), linkPath);
+      // Logical path is inside root, so safePath should allow it
+      const result = safePath('external-data/some-file.csv', ROOT);
+      expect(result).toBe(path.join(ROOT, 'external-data', 'some-file.csv'));
+    } finally {
+      try { fs.unlinkSync(linkPath); } catch { /* ignore cleanup errors */ }
+    }
+  });
+});

package/server/utils/cliResolution.js

@@ -9,6 +9,7 @@ function isCommandNotFoundExitCode(code) {
  *
  * @param {Object} options
  * @param {string} options.envVarName Environment variable name containing an override command.
+ * @param {string[]} [options.legacyEnvVarNames=[]] Older env var names checked after envVarName (migration).
  * @param {string[]} options.defaultCommands Fallback command names in preference order.
  * @param {string} [options.platform=process.platform] Runtime platform, used for Windows suffix handling.
  * @param {boolean} [options.appendWindowsSuffixes=false] Whether to append .cmd/.exe candidates on Windows.
@@ -16,11 +17,19 @@ function isCommandNotFoundExitCode(code) {
  */
 function getCliCommandCandidates({
     envVarName,
+    legacyEnvVarNames = [],
     defaultCommands,
     platform = process.platform,
     appendWindowsSuffixes = false
 }) {
-    const envCommand = String(process.env[envVarName] || '').trim();
+    let envCommand = '';
+    for (const key of [envVarName, ...legacyEnvVarNames].filter(Boolean)) {
+        const s = String(process.env[key] || '').trim();
+        if (s) {
+            envCommand = s;
+            break;
+        }
+    }
     const rawCandidates = [];
 
     if (envCommand) {
@@ -131,6 +140,7 @@ function checkCommandAvailable(command, args = ['--help'], { platform = process.
  *
  * @param {Object} options
  * @param {string} options.envVarName Environment variable with command override.
+ * @param {string[]} [options.legacyEnvVarNames=[]] Older env vars (after envVarName) for migration.
  * @param {string[]} options.defaultCommands Fallback command names in preference order.
  * @param {string[]} [options.args=['--help']] Probe arguments.
  * @param {string} [options.platform=process.platform] Runtime platform.
@@ -140,6 +150,7 @@ function checkCommandAvailable(command, args = ['--help'], { platform = process.
  */
 async function resolveAvailableCliCommand({
     envVarName,
+    legacyEnvVarNames = [],
     defaultCommands,
     args = ['--help'],
     platform = process.platform,
@@ -148,6 +159,7 @@ async function resolveAvailableCliCommand({
 }) {
     const candidates = getCliCommandCandidates({
         envVarName,
+        legacyEnvVarNames,
         defaultCommands,
         platform,
         appendWindowsSuffixes