logwork-cli 1.2.0 → 1.3.1

package/lib/launcher.mjs

@@ -0,0 +1,303 @@
+import { spawn } from 'node:child_process';
+import { constants as fsConstants, promises as fs } from 'node:fs';
+import { posix, win32 } from 'node:path';
+import { atomicWriteFile } from './atomic-file.mjs';
+import { helperHome } from './paths.mjs';
+
+// IDE MCP configs and the reminder schedule must keep working after nvm,
+// Homebrew or a Node installer upgrade, without the user editing anything.
+//
+// - macOS/Linux: `logwork setup` writes <home>/bin/logwork-launch, a POSIX sh
+//   script that finds a usable Node 22+ at start time and runs
+//   <home>/bin/logwork.mjs with it. Configs point at the script, which never
+//   moves.
+// - Windows: GUI clients would need `cmd /c` for a .cmd launcher, so configs
+//   use a stable node.exe instead: the nvm-windows symlink when Node runs from
+//   an nvm-windows version folder, otherwise the running node.exe (usually
+//   C:\Program Files\nodejs\node.exe, which an installer upgrade keeps).
+
+export const LAUNCHER_FILE_NAME = 'logwork-launch';
+export const MIN_NODE_MAJOR = 22;
+// Makes the launcher print the Node it would use and exit, without starting
+// logwork. Used by `logwork doctor`.
+export const LAUNCHER_PRINT_NODE_ENV = 'LOGWORK_LAUNCHER_PRINT_NODE';
+const ENTRY_RELATIVE = ['bin', 'logwork.mjs'];
+
+export function launcherPath(home = helperHome()) {
+  return posix.join(home, 'bin', LAUNCHER_FILE_NAME);
+}
+
+export function entryPath(home = helperHome(), platform = process.platform) {
+  return pathApi(platform).join(home, ...ENTRY_RELATIVE);
+}
+
+// The command every MCP config and the reminder schedule run. MCP args are
+// [...argsPrefix, 'mcp'].
+// stable: true when the command survives a Node upgrade without re-running
+// `logwork setup`.
+export function resolveLaunchCommand({
+  platform = process.platform,
+  home = helperHome(),
+  execPath = process.execPath,
+  env = process.env
+} = {}) {
+  if (platform !== 'win32') {
+    return {
+      command: launcherPath(home),
+      argsPrefix: [],
+      kind: 'launcher',
+      stable: true
+    };
+  }
+  const entry = win32.join(home, ...ENTRY_RELATIVE);
+  const symlink = String(readEnv(env, 'NVM_SYMLINK') || '').trim();
+  if (symlink && isNvmWindowsNode(execPath, env)) {
+    return {
+      command: win32.join(symlink, 'node.exe'),
+      argsPrefix: [entry],
+      kind: 'nvm-symlink',
+      stable: true
+    };
+  }
+  return {
+    command: String(execPath),
+    argsPrefix: [entry],
+    kind: 'node',
+    stable: isStandardWindowsInstall(execPath)
+  };
+}
+
+export function mcpArgs(launch) {
+  return [...(launch?.argsPrefix || []), 'mcp'];
+}
+
+// Node inside an nvm-windows version folder, e.g. C:\Users\me\AppData\Roaming\nvm\v22.11.0\node.exe.
+export function isNvmWindowsNode(execPath, env = process.env) {
+  const path = String(execPath || '').toLowerCase().replaceAll('/', '\\');
+  const nvmHome = String(readEnv(env, 'NVM_HOME') || '').toLowerCase().replaceAll('/', '\\').replace(/\\+$/, '');
+  if (nvmHome && path.startsWith(`${nvmHome}\\`)) {
+    return true;
+  }
+  return /\\nvm\\v\d+\.\d+\.\d+[^\\]*\\node\.exe$/.test(path);
+}
+
+// The official installer keeps node.exe at <Program Files>\nodejs\node.exe
+// across upgrades.
+export function isStandardWindowsInstall(execPath) {
+  return /\\nodejs\\node\.exe$/i.test(String(execPath || '').replaceAll('/', '\\'));
+}
+
+export function buildPosixLauncherScript({ home, nodePath }) {
+  const entry = posix.join(home, ...ENTRY_RELATIVE);
+  return `#!/bin/sh
+# Generated by \`logwork setup\`; it is rewritten on every setup, so do not edit.
+# Starts logwork with the first usable Node.js ${MIN_NODE_MAJOR}+, so IDE MCP configs and the
+# reminder keep working after nvm, Homebrew or installer upgrades.
+LOGWORK_ENTRY=${quoteSh(entry)}
+LOGWORK_RECORDED_NODE=${quoteSh(nodePath || '')}
+
+logwork_node_ok() {
+  [ -n "$1" ] && [ -f "$1" ] && [ -x "$1" ] || return 1
+  "$1" -e 'process.exit(+process.versions.node.split(".")[0]>=${MIN_NODE_MAJOR}?0:1)' >/dev/null 2>&1
+}
+
+logwork_run() {
+  logwork_node=$1
+  shift
+  if [ "\${${LAUNCHER_PRINT_NODE_ENV}:-}" = "1" ]; then
+    printf '%s\\n' "$logwork_node"
+    exit 0
+  fi
+  exec "$logwork_node" "$LOGWORK_ENTRY" "$@"
+}
+
+logwork_newest_nvm_node() {
+  logwork_best=''
+  logwork_best_key=0
+  for logwork_dir in "$@"; do
+    [ -n "$logwork_dir" ] && [ -d "$logwork_dir/versions/node" ] || continue
+    for logwork_candidate in "$logwork_dir"/versions/node/v*/bin/node; do
+      [ -x "$logwork_candidate" ] || continue
+      logwork_version=\${logwork_candidate%/bin/node}
+      logwork_version=\${logwork_version##*/v}
+      logwork_major=\${logwork_version%%.*}
+      logwork_rest=\${logwork_version#*.}
+      logwork_minor=\${logwork_rest%%.*}
+      logwork_patch=\${logwork_rest#*.}
+      logwork_patch=\${logwork_patch%%[!0-9]*}
+      case "$logwork_major.$logwork_minor.$logwork_patch" in
+        *[!0-9.]*|.*|*..*|*.) continue ;;
+      esac
+      [ "$logwork_major" -ge ${MIN_NODE_MAJOR} ] || continue
+      logwork_key=$((logwork_major * 1000000 + logwork_minor * 1000 + logwork_patch))
+      if [ "$logwork_key" -gt "$logwork_best_key" ]; then
+        logwork_best=$logwork_candidate
+        logwork_best_key=$logwork_key
+      fi
+    done
+  done
+  printf '%s' "$logwork_best"
+}
+
+# 1. The Node recorded by setup. Its path names its version, so an existing
+#    file is still that Node: skip the version check for a fast start.
+if [ -n "$LOGWORK_RECORDED_NODE" ] && [ -f "$LOGWORK_RECORDED_NODE" ] && [ -x "$LOGWORK_RECORDED_NODE" ]; then
+  logwork_run "$LOGWORK_RECORDED_NODE" "$@"
+fi
+
+# 2. node on PATH.
+logwork_candidate=$(command -v node 2>/dev/null || true)
+if logwork_node_ok "$logwork_candidate"; then
+  logwork_run "$logwork_candidate" "$@"
+fi
+
+# 3. The newest nvm Node ${MIN_NODE_MAJOR}+.
+logwork_candidate=$(logwork_newest_nvm_node "\${NVM_DIR:-}" "\${HOME:-}/.nvm")
+if logwork_node_ok "$logwork_candidate"; then
+  logwork_run "$logwork_candidate" "$@"
+fi
+
+# 4. Volta and fnm defaults, then 5. Homebrew and /usr/local.
+for logwork_candidate in \\
+  "\${HOME:-}/.volta/bin/node" \\
+  "\${HOME:-}/.local/share/fnm/aliases/default/bin/node" \\
+  "\${HOME:-}/Library/Application Support/fnm/aliases/default/bin/node" \\
+  /opt/homebrew/bin/node \\
+  /usr/local/bin/node
+do
+  if logwork_node_ok "$logwork_candidate"; then
+    logwork_run "$logwork_candidate" "$@"
+  fi
+done
+
+echo "logwork: no usable Node.js ${MIN_NODE_MAJOR}+ found. Install Node.js ${MIN_NODE_MAJOR} or newer, or run \\\`logwork setup\\\` again." >&2
+exit 127
+`;
+}
+
+// Writes the launcher on macOS/Linux. A no-op on Windows (returns null).
+export async function writeLauncher({
+  home = helperHome(),
+  nodePath = process.execPath,
+  platform = process.platform,
+  writeFile = atomicWriteFile,
+  chmod = fs.chmod
+} = {}) {
+  if (platform === 'win32') {
+    return null;
+  }
+  const path = launcherPath(home);
+  await writeFile(path, buildPosixLauncherScript({ home, nodePath }), { mode: 0o755 });
+  // atomicWriteFile applies the mode through the umask; make it explicit.
+  await chmod(path, 0o755);
+  return { path, nodePath };
+}
+
+// Checks the command MCP configs and the reminder run. Read-only: it runs the
+// command with `--version` (which prints the logwork version through
+// bin/logwork.mjs) and, for the launcher, asks which Node it would pick.
+export async function checkLaunchCommand(launch = resolveLaunchCommand(), {
+  platform = process.platform,
+  access = fs.access,
+  run = runProcess,
+  env = process.env
+} = {}) {
+  const result = {
+    command: launch.command,
+    kind: launch.kind,
+    status: 'ok',
+    node: launch.kind === 'launcher' ? '' : launch.command,
+    version: ''
+  };
+  try {
+    await access(launch.command, fsConstants.F_OK);
+  } catch {
+    return { ...result, status: 'missing' };
+  }
+  if (platform !== 'win32') {
+    try {
+      await access(launch.command, fsConstants.X_OK);
+    } catch {
+      return { ...result, status: 'not_executable' };
+    }
+  }
+  const childEnv = withoutLogworkEnv(env);
+  if (launch.kind === 'launcher') {
+    const picked = await run(launch.command, [], { env: { ...childEnv, [LAUNCHER_PRINT_NODE_ENV]: '1' } }).catch((error) => ({ code: 1, stdout: '', stderr: error.message }));
+    if (picked.code !== 0) {
+      return { ...result, status: 'no_node', detail: firstLine(picked.stderr || picked.stdout) };
+    }
+    result.node = firstLine(picked.stdout);
+  }
+  const version = await run(launch.command, [...launch.argsPrefix, '--version'], { env: childEnv }).catch((error) => ({ code: 1, stdout: '', stderr: error.message }));
+  if (version.code !== 0) {
+    return { ...result, status: 'failed', detail: firstLine(version.stderr || version.stdout) };
+  }
+  result.version = firstLine(version.stdout);
+  return result;
+}
+
+export function formatLaunchCheckIssue(check) {
+  switch (check?.status) {
+    case 'missing':
+      return check.kind === 'launcher'
+        ? `Launcher: ${check.command} is missing, so IDE MCP configs and the reminder cannot start. Fix: run \`logwork setup\`.`
+        : `Node: ${check.command} no longer exists, so IDE MCP configs and the reminder cannot start. Fix: run \`logwork setup\`.`;
+    case 'not_executable':
+      return `Launcher: ${check.command} is not executable. Fix: run \`logwork setup\`.`;
+    case 'no_node':
+      return `Launcher: found no usable Node.js ${MIN_NODE_MAJOR}+. Fix: install Node.js ${MIN_NODE_MAJOR} or newer, then run \`logwork setup\`.`;
+    case 'failed':
+      return `Launcher: ${check.command} --version failed${check.detail ? ` (${check.detail})` : ''}. Fix: run \`logwork setup\`.`;
+    default:
+      return '';
+  }
+}
+
+export function runProcess(command, args, { env = process.env, cwd } = {}) {
+  return new Promise((resolveValue, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code, signal) => resolveValue({ code: signal ? 1 : (code ?? 1), stdout, stderr }));
+  });
+}
+
+export function pathApi(platform = process.platform) {
+  return platform === 'win32' ? win32 : posix;
+}
+
+// The launcher must not inherit a test or dev LOGWORK_HOME that points at a
+// different runtime than the one it launches.
+function withoutLogworkEnv(env) {
+  return Object.fromEntries(Object.entries(env || {}).filter(([key]) => !key.startsWith('LOGWORK_')));
+}
+
+function firstLine(value) {
+  return String(value || '').trim().split(/\r?\n/)[0] || '';
+}
+
+function quoteSh(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function readEnv(env, name) {
+  if (!env) {
+    return undefined;
+  }
+  if (env[name] !== undefined) {
+    return env[name];
+  }
+  const key = Object.keys(env).find((item) => item.toUpperCase() === name);
+  return key ? env[key] : undefined;
+}

package/lib/manual-commands.mjs

@@ -74,8 +74,8 @@ export const MANUAL_COMMANDS = [
   },
   {
     name: '/map',
-    description: 'Map ticket prefix or git repo to projectMemberId',
-    usage: '/map SCB 5234 | /map --repo [path] 5234',
+    description: 'Map ticket prefix or git repo to an RO project (picker)',
+    usage: '/map SCB [project] | /map --repo [path] [project]',
     aliases: []
   }
 ];

package/lib/manual-ink-app.mjs

@@ -44,6 +44,7 @@ export {
   OutputPanel,
   ProjectChart,
   ProjectPicker,
+  SelectPrompt,
   SelectionList,
   SlashMenu,
   StatusBar,
@@ -102,6 +103,7 @@ export function ManualApp({
   const { exit } = useApp();
   const sessionRef = useRef(controller.createManualSession());
   const confirmResolverRef = useRef(null);
+  const selectResolverRef = useRef(null);
   const authResolverRef = useRef(null);
   const authRejecterRef = useRef(null);
   const [inputValue, setInputValue] = useState('');
@@ -115,6 +117,7 @@ export function ManualApp({
   }));
   const [loading, setLoading] = useState('');
   const [pendingConfirm, setPendingConfirm] = useState(null);
+  const [pendingSelect, setPendingSelect] = useState(null);
   const [authPrompt, setAuthPrompt] = useState(null);
   const [authActive, setAuthActive] = useState(false);
   const [wizard, setWizard] = useState(null);
@@ -128,9 +131,35 @@ export function ManualApp({
           initialValue
         });
       });
+    },
+    // { message, options: [{ value, label, hint }], initialValue } -> the
+    // chosen value, or null on Escape.
+    select({ message, options = [], initialValue }) {
+      return new Promise((resolveValue) => {
+        selectResolverRef.current = resolveValue;
+        const initialIndex = Math.max(0, options.findIndex((option) => option.value === initialValue));
+        setPendingSelect({
+          message,
+          options,
+          selectedIndex: initialIndex
+        });
+      });
     }
   }), []);
 
+  const changeSelect = useCallback((index) => {
+    setPendingSelect((current) => (current ? { ...current, selectedIndex: index } : current));
+  }, []);
+
+  const resolveSelect = useCallback((value) => {
+    const resolver = selectResolverRef.current;
+    selectResolverRef.current = null;
+    setPendingSelect(null);
+    if (resolver) {
+      resolver(value ?? null);
+    }
+  }, []);
+
   const resolveConfirm = useCallback((value) => {
     const resolver = confirmResolverRef.current;
     confirmResolverRef.current = null;
@@ -343,7 +372,7 @@ export function ManualApp({
     const text = String(value || '');
     const trimmed = text.trim();
 
-    if (pendingConfirm) {
+    if (pendingConfirm || pendingSelect) {
       return;
     }
 
@@ -421,6 +450,7 @@ export function ManualApp({
     executeCommand,
     inputValue,
     pendingConfirm,
+    pendingSelect,
     authActive,
     authPrompt,
     selectedIndex,
@@ -450,6 +480,7 @@ export function ManualApp({
     authPrompt,
     authActive,
     pendingConfirm,
+    pendingSelect,
     wizard,
     inputValue,
     selectedIndex,
@@ -461,6 +492,8 @@ export function ManualApp({
     resolveAuthPrompt,
     rejectAuthPrompt,
     resolveConfirm,
+    changeSelect,
+    resolveSelect,
     exit,
     executeCommand,
     submitInput,

package/lib/manual-ink-interaction.mjs

@@ -11,6 +11,7 @@ import {
   DraftPicker,
   McpClientPicker,
   ProjectPicker,
+  SelectPrompt,
   TargetPicker,
   TaskEditPicker,
   TaskRemovePicker
@@ -24,6 +25,7 @@ export function renderManualInteraction({
   authPrompt,
   authActive,
   pendingConfirm,
+  pendingSelect,
   wizard,
   inputValue,
   selectedIndex,
@@ -35,6 +37,8 @@ export function renderManualInteraction({
   resolveAuthPrompt,
   rejectAuthPrompt,
   resolveConfirm,
+  changeSelect,
+  resolveSelect,
   exit,
   executeCommand,
   submitInput,
@@ -84,6 +88,14 @@ export function renderManualInteraction({
       initialValue: pendingConfirm.initialValue,
       onResolve: resolveConfirm
     })
+    : pendingSelect
+    ? h(SelectPrompt, {
+      message: pendingSelect.message,
+      options: pendingSelect.options,
+      selectedIndex: pendingSelect.selectedIndex || 0,
+      onChange: changeSelect,
+      onResolve: resolveSelect
+    })
     : wizard?.step === 'select_logwork_target'
       ? h(TargetPicker, {
         title: 'Pick logwork target',

package/lib/manual-ink-ui.mjs

@@ -387,6 +387,44 @@ export function McpClientPicker({
   });
 }
 
+// A generic single-choice prompt for prompts.select({ message, options }):
+// Enter picks the highlighted option, Escape cancels (null). Each option is
+// { value, label, hint? }; the hint is shown after the label.
+export function SelectPrompt({
+  message = 'Pick one',
+  options = [],
+  selectedIndex = 0,
+  onChange,
+  onResolve
+}) {
+  useInput((input, key) => {
+    if (key.upArrow) {
+      onChange(previousIndex(selectedIndex, options.length));
+      return;
+    }
+    if (key.downArrow) {
+      onChange(nextIndex(selectedIndex, options.length));
+      return;
+    }
+    if (key.return) {
+      onResolve(options[selectedIndex]?.value ?? null);
+      return;
+    }
+    if (key.escape) {
+      onResolve(null);
+    }
+  });
+
+  return h(SelectionList, {
+    title: `${message} · Esc cancel`,
+    items: options.map((option, index) => ({
+      key: `${index}:${option.value}`,
+      label: option.hint ? `${option.label} · ${option.hint}` : option.label
+    })),
+    selectedIndex
+  });
+}
+
 export function TaskEditPicker({
   tasks = [],
   selectedIndex = 0,

package/lib/manual-mcp.mjs

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { mcpArgs, resolveLaunchCommand } from './launcher.mjs';
 import { helperHome } from './paths.mjs';
 
 export const MCP_CLIENTS = [
@@ -39,18 +40,48 @@ export const MCP_CLIENTS = [
   }
 ];
 
-// IDE configs run `<absolute node> <runtime>/bin/logwork.mjs mcp`. Both paths
-// are absolute because GUI IDEs (Cursor, VS Code started from the Dock or
+// IDE configs run the launch command from lib/launcher.mjs: on macOS/Linux
+// the generated <home>/bin/logwork-launch script (it finds a usable Node 22+
+// at start time), on Windows a stable node.exe plus <home>\bin\logwork.mjs.
+// Both are absolute because GUI IDEs (Cursor, VS Code started from the Dock or
 // Finder) often start without the npm global bin directory or nvm's node on
 // PATH, so neither `logwork` nor a bare `node` would be found.
 export const MCP_SERVER_NAME = 'logwork';
 
-export const MCP_NODE_PATH_NOTE = 'The config uses the absolute path of the Node that ran this command. If Node is upgraded or moved (nvm, Homebrew, a new installer), re-run `logwork setup` and paste the new config.';
+// Only printed when the command is a raw Node path that an upgrade can remove.
+export const MCP_NODE_PATH_NOTE = 'The config uses the absolute path of the Node that ran this command. If Node is upgraded or moved (nvm, Homebrew, a new installer), re-run `logwork setup` (it updates the config for you).';
+
+export const MCP_LAUNCHER_NOTE = 'The command is the logwork launcher; it finds Node 22+ itself, so Node upgrades need no config change.';
+
+const INSTALL_CLIENT_KEYS = {
+  cursor: 'cursor',
+  antigravity: 'antigravity',
+  copilot: 'vscode',
+  'claude-code': 'claude',
+  codex: 'codex'
+};
 
 export function defaultMcpServerPath() {
   return join(helperHome(), 'bin', 'logwork.mjs');
 }
 
+// Accepts a launch command ({ command, argsPrefix }) or, for older callers, an
+// entry path plus { nodePath }: a raw `<node> <entry>` command.
+export function toLaunchCommand(launchOrServerPath, { nodePath } = {}) {
+  if (launchOrServerPath && typeof launchOrServerPath === 'object') {
+    return launchOrServerPath;
+  }
+  if (launchOrServerPath === undefined && nodePath === undefined) {
+    return resolveLaunchCommand();
+  }
+  return {
+    command: nodePath || process.execPath,
+    argsPrefix: [launchOrServerPath || defaultMcpServerPath()],
+    kind: 'node',
+    stable: false
+  };
+}
+
 export function resolveMcpClient(value) {
   const normalized = normalizeMcpClientValue(value);
   if (!normalized) {
@@ -85,19 +116,22 @@ export function formatMcpClientOptions(clients = MCP_CLIENTS) {
 
 export function formatMcpSetup({
   client,
-  serverPath = defaultMcpServerPath(),
-  nodePath = process.execPath,
+  launch,
+  serverPath,
+  nodePath,
   platform = process.platform
 } = {}) {
   const resolvedClient = typeof client === 'object' ? client : resolveMcpClient(client);
   if (!resolvedClient) {
     throw new Error('Unknown MCP client. Use: cursor, antigravity, copilot, claude-code, or codex.');
   }
+  const command = launch || (serverPath === undefined && nodePath === undefined
+    ? resolveLaunchCommand({ platform })
+    : toLaunchCommand(serverPath, { nodePath }));
 
   const lines = [
     `MCP setup: ${resolvedClient.label}`,
-    `Node: ${nodePath}`,
-    `Entry path: ${serverPath} (run with the "mcp" argument)`,
+    `Command: ${[command.command, ...mcpArgs(command)].join(' ')}`,
     ''
   ];
 
@@ -105,35 +139,38 @@ export function formatMcpSetup({
     lines.push(
       `Copy this TOML into ${resolvedClient.target}:`,
       '',
-      formatCodexToml(serverPath, { nodePath })
+      formatCodexToml(command)
     );
   } else if (resolvedClient.key === 'copilot') {
     lines.push(
       `Copy this JSON into ${resolvedClient.target}:`,
       '',
-      JSON.stringify(vscodeMcpConfig(serverPath, { nodePath }), null, 2)
+      JSON.stringify(vscodeMcpConfig(command), null, 2)
     );
   } else if (resolvedClient.key === 'claude-code') {
     lines.push(
       'Recommended command:',
       '',
-      `claude mcp add --transport stdio ${MCP_SERVER_NAME} -- ${quoteShellArg(nodePath, { platform })} ${quoteShellArg(serverPath, { platform })} mcp`,
+      formatClaudeMcpAddCommand(command, { platform }),
       '',
       'Or copy this JSON into project .mcp.json:',
       '',
-      JSON.stringify(stdioMcpServersConfig(serverPath, { nodePath }), null, 2)
+      JSON.stringify(stdioMcpServersConfig(command), null, 2)
     );
   } else {
     lines.push(
       `Copy this JSON into ${resolvedClient.target}:`,
       '',
-      JSON.stringify(stdioMcpServersConfig(serverPath, { nodePath }), null, 2)
+      JSON.stringify(stdioMcpServersConfig(command), null, 2)
     );
   }
 
+  const installKey = INSTALL_CLIENT_KEYS[resolvedClient.key];
+  const note = command.stable ? (command.kind === 'launcher' ? MCP_LAUNCHER_NOTE : '') : MCP_NODE_PATH_NOTE;
   lines.push(
     '',
-    MCP_NODE_PATH_NOTE,
+    ...(note ? [note] : []),
+    ...(installKey ? [`To let logwork write it for you instead, run: logwork mcp install --client ${installKey}`] : []),
     'After saving, restart or reload the MCP client.',
     'Do not paste passwords, 2FA codes, Bearer tokens, cookies, or raw auth logs into AI chat.'
   );
@@ -148,39 +185,48 @@ function normalizeMcpClientValue(value) {
     .replace(/[\s_]+/g, '-');
 }
 
-export function stdioMcpServersConfig(serverPath, { nodePath = process.execPath } = {}) {
+export function stdioMcpServersConfig(launchOrServerPath, options = {}) {
+  const launch = toLaunchCommand(launchOrServerPath, options);
   return {
     mcpServers: {
       [MCP_SERVER_NAME]: {
-        command: nodePath,
-        args: [serverPath, 'mcp']
+        command: launch.command,
+        args: mcpArgs(launch)
       }
     }
   };
 }
 
-export function vscodeMcpConfig(serverPath, { nodePath = process.execPath } = {}) {
+export function vscodeMcpConfig(launchOrServerPath, options = {}) {
+  const launch = toLaunchCommand(launchOrServerPath, options);
   return {
     servers: {
       [MCP_SERVER_NAME]: {
         type: 'stdio',
-        command: nodePath,
-        args: [serverPath, 'mcp']
+        command: launch.command,
+        args: mcpArgs(launch)
       }
     }
   };
 }
 
-export function formatCodexToml(serverPath, { nodePath = process.execPath } = {}) {
+export function formatCodexToml(launchOrServerPath, options = {}) {
+  const launch = toLaunchCommand(launchOrServerPath, options);
   return [
     `[mcp_servers.${MCP_SERVER_NAME}]`,
-    `command = "${escapeTomlString(nodePath)}"`,
-    `args = ["${escapeTomlString(serverPath)}", "mcp"]`,
+    `command = "${escapeTomlString(launch.command)}"`,
+    `args = [${mcpArgs(launch).map((arg) => `"${escapeTomlString(arg)}"`).join(', ')}]`,
     'startup_timeout_sec = 20',
     'tool_timeout_sec = 120'
   ].join('\n');
 }
 
+// User scope, so the server is available in every project.
+export function formatClaudeMcpAddCommand(launchOrServerPath, { platform = process.platform, ...options } = {}) {
+  const launch = toLaunchCommand(launchOrServerPath, options);
+  return `claude mcp add --transport stdio --scope user ${MCP_SERVER_NAME} -- ${[launch.command, ...mcpArgs(launch)].map((arg) => (arg === 'mcp' ? arg : quoteShellArg(arg, { platform }))).join(' ')}`;
+}
+
 // TOML basic string: escape backslashes (Windows paths), quotes and control
 // characters.
 function escapeTomlString(value) {