@rayrun/cli 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Rayrun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @rayrun/cli
+
+Connect supported MCP clients to a Rayrun workspace endpoint without copying configuration by hand.
+
+```sh
+pnpm --package @rayrun/cli@latest dlx rayrun setup https://copy-the-endpoint-from-rayrun.example/mcp
+```
+
+The command detects Claude Code, Codex/ChatGPT desktop, Cursor, VS Code, Windsurf/Devin Local, and OpenCode v2. It shows the detected clients before changing anything. Pass `--client cursor` more than once for automation, or `--all --yes` to configure every detected client.
+
+It writes only the public Rayrun endpoint. OAuth stays inside each client; no bearer token or API key is put in a config file or shell history. Before changing configuration it stores byte-for-byte backups under `~/.rayrun/backups/setup`, writes JSON atomically, and restores every target if a configuration write fails. A later client-login failure leaves the valid configuration in place and prints the exact login command to retry.
+
+Backups are private to your user account (`0700` directories and `0600` files) and are retained until you remove old backup directories after their rollback window is no longer useful.
+
+```sh
+rayrun setup <endpoint> --dry-run --all
+rayrun setup <endpoint> --client cursor --client opencode --yes
+rayrun setup <endpoint> --client codex --yes --login
+rayrun setup rollback <backup-id>
+```
+
+Use `--project` for project-local configuration in Claude Code, Codex, Cursor, VS Code, Devin, and OpenCode. Legacy Windsurf remains user-scoped. Claude Code asks you to approve a project MCP server when that project opens. Codex loads `.codex/config.toml` only after you trust the project; restart Codex after doing so.
+
+Interactive setup runs supported clients' OAuth login commands. `--yes` and non-interactive setup never launch login unless you explicitly pass `--login`; the command prints the exact login command when it skips one. Pass `--no-login` to make the choice explicit in scripts.

package/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { main } from './src/main.js';
+
+try {
+  await main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@rayrun/cli",
+  "version": "0.1.0",
+  "description": "Safely connect local MCP clients to Rayrun",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rayrundev/rayrun.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "rayrun": "index.js"
+  },
+  "files": [
+    "index.js",
+    "src/clients.js",
+    "src/config.js",
+    "src/main.js",
+    "src/setup.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.8.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/clients.js

@@ -0,0 +1,220 @@
+/* eslint-disable node/no-process-env -- the installer intentionally inspects the invoking user's environment */
+// cspell:ignore codemode
+import { access } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const executableExists = async (name, environment = process.env) => {
+  const pathValue = environment.PATH ?? '';
+  const extensions = process.platform === 'win32' ? ['', '.cmd', '.exe'] : [''];
+
+  for (const directory of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      try {
+        await access(path.join(directory, `${name}${extension}`));
+        return true;
+      } catch {
+        // Try the next PATH entry.
+      }
+    }
+  }
+
+  return false;
+};
+
+const fileExists = async (filePath) => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const vscodeUserPath = ({ environment, homeDirectory, platform }) => {
+  if (platform === 'darwin') {
+    return path.join(homeDirectory, 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+  }
+
+  if (platform === 'win32') {
+    return path.join(
+      environment.APPDATA ?? path.join(homeDirectory, 'AppData', 'Roaming'),
+      'Code',
+      'User',
+      'mcp.json',
+    );
+  }
+
+  return path.join(
+    environment.XDG_CONFIG_HOME ?? path.join(homeDirectory, '.config'),
+    'Code',
+    'User',
+    'mcp.json',
+  );
+};
+
+export const clientDefinitions = ({
+  cwd = process.cwd(),
+  environment = process.env,
+  homeDirectory = os.homedir(),
+  platform = process.platform,
+  project = false,
+} = {}) => {
+  const configHome = environment.XDG_CONFIG_HOME ?? path.join(homeDirectory, '.config');
+  const devinConfigHome =
+    platform === 'win32'
+      ? (environment.APPDATA ?? path.join(homeDirectory, 'AppData', 'Roaming'))
+      : configHome;
+
+  return [
+    {
+      detectCommand: 'claude',
+      detectPaths: [path.join(homeDirectory, '.claude')],
+      id: 'claude-code',
+      label: 'Claude Code',
+      loginCommand: {
+        args: ['mcp', 'login', 'rayrun'],
+        command: 'claude',
+        cwd: project ? cwd : homeDirectory,
+      },
+      path: project ? path.join(cwd, '.mcp.json') : path.join(homeDirectory, '.claude.json'),
+      propertyPath: ['mcpServers', 'rayrun'],
+      projectInstruction: project
+        ? 'Open Claude Code in this project and approve the rayrun server when prompted.'
+        : null,
+      type: 'json',
+      value: (url) => ({ type: 'http', url }),
+    },
+    {
+      detectCommand: 'codex',
+      detectPaths: [path.join(homeDirectory, '.codex')],
+      id: 'codex',
+      label: 'Codex and ChatGPT desktop',
+      loginCommand: {
+        args: ['mcp', 'login', 'rayrun'],
+        command: 'codex',
+        cwd: project ? cwd : homeDirectory,
+      },
+      path: project
+        ? path.join(cwd, '.codex', 'config.toml')
+        : path.join(homeDirectory, '.codex', 'config.toml'),
+      projectInstruction: project
+        ? 'Trust this project in Codex, then restart Codex so it loads .codex/config.toml.'
+        : null,
+      section: 'mcp_servers.rayrun',
+      type: 'toml',
+      value: (url) => ({ url }),
+    },
+    {
+      id: 'cursor',
+      label: 'Cursor',
+      detectCommand: 'cursor',
+      detectPaths: [path.join(homeDirectory, '.cursor')],
+      path: project
+        ? path.join(cwd, '.cursor', 'mcp.json')
+        : path.join(homeDirectory, '.cursor', 'mcp.json'),
+      propertyPath: ['mcpServers', 'rayrun'],
+      type: 'json',
+      value: (url) => ({ url }),
+    },
+    {
+      id: 'vscode',
+      label: 'VS Code',
+      detectCommand: 'code',
+      detectPaths: [path.dirname(vscodeUserPath({ environment, homeDirectory, platform }))],
+      path: project
+        ? path.join(cwd, '.vscode', 'mcp.json')
+        : vscodeUserPath({ environment, homeDirectory, platform }),
+      propertyPath: ['servers', 'rayrun'],
+      type: 'json',
+      value: (url) => ({ type: 'http', url }),
+    },
+    {
+      id: 'windsurf',
+      label: 'Windsurf (legacy Cascade)',
+      detectCommand: 'windsurf',
+      detectPaths: [path.join(homeDirectory, '.codeium', 'windsurf')],
+      path: path.join(homeDirectory, '.codeium', 'windsurf', 'mcp_config.json'),
+      propertyPath: ['mcpServers', 'rayrun'],
+      projectUnsupported: true,
+      type: 'json',
+      value: (url) => ({ serverUrl: url }),
+    },
+    {
+      detectCommand: 'devin',
+      id: 'devin',
+      label: 'Windsurf / Devin Local',
+      loginCommand: {
+        args: ['mcp', 'login', 'rayrun'],
+        command: 'devin',
+        cwd: project ? cwd : homeDirectory,
+      },
+      path: project
+        ? path.join(cwd, '.devin', 'mcp_config.json')
+        : path.join(devinConfigHome, 'devin', 'mcp_config.json'),
+      propertyPath: ['mcpServers', 'rayrun'],
+      type: 'json',
+      value: (url) => ({ transport: 'http', url }),
+    },
+    {
+      id: 'opencode',
+      label: 'OpenCode v2',
+      alternativePaths: project
+        ? [path.join(cwd, 'opencode.jsonc')]
+        : [path.join(configHome, 'opencode', 'opencode.jsonc')],
+      detectCommand: 'opencode2',
+      path: project
+        ? path.join(cwd, 'opencode.json')
+        : path.join(configHome, 'opencode', 'opencode.json'),
+      preferredExistingPaths: project
+        ? [
+            path.join(cwd, '.opencode', 'opencode.json'),
+            path.join(cwd, '.opencode', 'opencode.jsonc'),
+          ]
+        : [],
+      propertyPath: ['mcp', 'servers', 'rayrun'],
+      requireCommandForDetection: true,
+      type: 'json',
+      value: (url) => ({ codemode: false, type: 'remote', url }),
+    },
+  ];
+};
+
+export const detectClients = async (options = {}) => {
+  const definitions = clientDefinitions(options);
+  const environment = options.environment ?? process.env;
+  const detected = [];
+
+  for (const definition of definitions) {
+    if (options.project && definition.projectUnsupported) {
+      continue;
+    }
+    const candidatePaths = [
+      ...(definition.preferredExistingPaths ?? []),
+      definition.path,
+      ...(definition.alternativePaths ?? []),
+    ].filter(Boolean);
+    const existingPath = (
+      await Promise.all(
+        candidatePaths.map(async (candidate) => ((await fileExists(candidate)) ? candidate : null)),
+      )
+    ).find(Boolean);
+    const commandExists = definition.detectCommand
+      ? await executableExists(definition.detectCommand, environment)
+      : false;
+    const exists =
+      definition.type === 'native'
+        ? await executableExists(definition.command, environment)
+        : definition.requireCommandForDetection
+          ? commandExists
+          : existingPath !== undefined ||
+            commandExists ||
+            (await Promise.all((definition.detectPaths ?? []).map(fileExists))).some(Boolean);
+
+    if (exists) {
+      detected.push(existingPath ? { ...definition, path: existingPath } : definition);
+    }
+  }
+
+  return detected;
+};

package/src/config.js

@@ -0,0 +1,237 @@
+import { applyEdits, modify, parse, parseTree, printParseErrorCode } from 'jsonc-parser';
+import { parse as parseToml } from 'smol-toml';
+
+// cspell:ignore accesstoken apikey bearertoken clientsecret codemode httpheaders
+
+const hasCredentialMaterial = (value) => {
+  if (!value || typeof value !== 'object') return false;
+
+  return Object.entries(value).some(([key, child]) => {
+    const normalized = key.replaceAll(/[-_]/gu, '').toLowerCase();
+    const credentialKey =
+      normalized === 'authorization' ||
+      normalized === 'headers' ||
+      normalized.endsWith('apikey') ||
+      normalized.includes('bearertoken') ||
+      normalized.includes('clientsecret') ||
+      normalized.includes('credential') ||
+      normalized.includes('httpheaders') ||
+      normalized.includes('oauth') ||
+      normalized.includes('accesstoken') ||
+      normalized.endsWith('token') ||
+      normalized.endsWith('password') ||
+      normalized.endsWith('secret');
+
+    return credentialKey || hasCredentialMaterial(child);
+  });
+};
+
+const endpointResource = (value) => {
+  if (typeof value !== 'string') return null;
+
+  try {
+    const endpoint = new URL(value);
+    endpoint.pathname = endpoint.pathname.replace(/\/direct\/?$/u, '');
+    return endpoint.href;
+  } catch {
+    return null;
+  }
+};
+
+const assertCredentialsStayOnResource = ({ existing, value }) => {
+  if (!hasCredentialMaterial(existing)) return;
+
+  const existingResource = endpointResource(existing.url ?? existing.serverUrl);
+  const nextResource = endpointResource(value.url ?? value.serverUrl);
+
+  if (existingResource === null || nextResource === null || existingResource !== nextResource) {
+    throw new Error(
+      'Refusing to move a configuration that contains credentials to another server. Remove its credential fields after inspecting them, then run setup again.',
+    );
+  }
+};
+
+const assertNoDuplicateJsonKeys = (node, path = []) => {
+  if (!node) return;
+
+  if (node.type === 'object') {
+    const keys = new Set();
+    for (const property of node.children ?? []) {
+      const [keyNode, valueNode] = property.children ?? [];
+      const key = keyNode?.value;
+      if (typeof key !== 'string') continue;
+      if (keys.has(key)) {
+        throw new Error(
+          `Cannot safely update JSON configuration with duplicate key ${[...path, key].join('.')}.`,
+        );
+      }
+      keys.add(key);
+      assertNoDuplicateJsonKeys(valueNode, [...path, key]);
+    }
+    return;
+  }
+
+  for (const child of node.children ?? []) assertNoDuplicateJsonKeys(child, path);
+};
+
+export const updateJsonConfig = ({ source, propertyPath, value }) => {
+  const errors = [];
+  const parsed = parse(source === '' ? '{}' : source, errors, { allowTrailingComma: true });
+
+  if (errors.length > 0 || parsed === undefined) {
+    const first = errors[0];
+    throw new Error(
+      `Cannot safely update invalid JSON configuration${first ? `: ${printParseErrorCode(first.error)} at offset ${String(first.offset)}` : ''}.`,
+    );
+  }
+  assertNoDuplicateJsonKeys(parseTree(source === '' ? '{}' : source));
+
+  const existing = propertyPath.reduce((candidate, key) => {
+    return candidate && typeof candidate === 'object' ? candidate[key] : undefined;
+  }, parsed);
+  assertCredentialsStayOnResource({ existing, value });
+  const enabledValue = { ...value };
+
+  if (existing && typeof existing.disabled === 'boolean') enabledValue.disabled = false;
+  if (existing && typeof existing.enabled === 'boolean') enabledValue.enabled = true;
+  let result = source === '' ? '{}' : source;
+  const formattingOptions = { insertSpaces: true, tabSize: 2 };
+
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+    result = applyEdits(result, modify(result, propertyPath, {}, { formattingOptions }));
+  }
+
+  // These keys select mutually exclusive MCP transports across the supported clients. Remove a
+  // stale transport field while retaining unrelated client-specific settings and their comments.
+  for (const key of [
+    'args',
+    'codemode',
+    'command',
+    'cwd',
+    'env',
+    'environment',
+    'serverUrl',
+    'transport',
+    'type',
+    'url',
+  ]) {
+    if (existing && Object.hasOwn(existing, key) && !Object.hasOwn(enabledValue, key)) {
+      result = applyEdits(
+        result,
+        modify(result, [...propertyPath, key], undefined, { formattingOptions }),
+      );
+    }
+  }
+
+  for (const [key, nextValue] of Object.entries(enabledValue)) {
+    result = applyEdits(
+      result,
+      modify(result, [...propertyPath, key], nextValue, { formattingOptions }),
+    );
+  }
+
+  return result;
+};
+
+export const updateTomlConfig = ({ section, source, value }) => {
+  let parsed;
+  try {
+    parsed = parseToml(source === '' ? '' : source);
+  } catch (error) {
+    throw new Error(
+      `Cannot safely update invalid TOML configuration: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const lines = source.replace(/\r\n/gu, '\n').split('\n');
+  const escapePattern = (part) => part.replaceAll(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const sectionPatternSource = section
+    .split('.')
+    .map((part) => `(?:${escapePattern(part)}|"${escapePattern(part)}")`)
+    .join('\\s*\\.\\s*');
+  const sectionPattern = new RegExp(`^\\s*\\[\\s*${sectionPatternSource}\\s*\\]\\s*(?:#.*)?$`, 'u');
+  const nestedSectionPattern = new RegExp(
+    `^\\s*\\[\\s*${sectionPatternSource}\\s*\\.\\s*(.+?)\\s*\\]\\s*(?:#.*)?$`,
+    'u',
+  );
+  const sectionIndexes = lines
+    .map((line, index) => (sectionPattern.test(line) ? index : -1))
+    .filter((index) => index >= 0);
+
+  if (sectionIndexes.length > 1) {
+    throw new Error(`Cannot safely update duplicate TOML section [${section}].`);
+  }
+
+  const existing = section.split('.').reduce((candidate, key) => {
+    return candidate && typeof candidate === 'object' ? candidate[key] : undefined;
+  }, parsed);
+  assertCredentialsStayOnResource({ existing, value });
+  const enabledValue = { ...value };
+
+  if (existing && typeof existing.disabled === 'boolean') enabledValue.disabled = false;
+  if (existing && typeof existing.enabled === 'boolean') enabledValue.enabled = true;
+
+  if (existing !== undefined && sectionIndexes.length === 0) {
+    throw new Error(
+      `Cannot safely update [${section}] because it uses an inline or dotted TOML representation. Convert it to a table first.`,
+    );
+  }
+
+  const nestedSections = lines
+    .map((line) => nestedSectionPattern.exec(line)?.[1])
+    .filter((nested) => nested !== undefined);
+
+  if (nestedSections.some((nested) => /^(?:env|"env"|'env')(?:\s*\.|$)/u.test(nested))) {
+    throw new Error(
+      `Cannot safely replace [${section}] while [${section}.env] contains transport-specific settings. Move or remove that table first.`,
+    );
+  }
+
+  if (sectionIndexes.length === 0) {
+    const prefix = source.trimEnd();
+    const body = Object.entries(enabledValue)
+      .map(([key, item]) => `${key} = ${JSON.stringify(item)}`)
+      .join('\n');
+    const result = `${prefix}${prefix === '' ? '' : '\n\n'}[${section}]\n${body}\n`;
+
+    try {
+      parseToml(result);
+    } catch (error) {
+      throw new Error(
+        `Rayrun refused to write invalid TOML: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    return result;
+  }
+
+  const start = sectionIndexes[0];
+  const nextSectionOffset = lines.slice(start + 1).findIndex((line) => /^\s*\[/u.test(line));
+  const end = nextSectionOffset === -1 ? lines.length : start + 1 + nextSectionOffset;
+  const ownedKeys = new Set(['args', 'command', 'disabled', 'enabled', 'env', 'url']);
+  const seen = new Set();
+  const updated = lines.slice(start + 1, end).flatMap((line) => {
+    const match = /^\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))\s*=/u.exec(line);
+    const key = match?.[1] ?? match?.[2] ?? match?.[3];
+    if (!key || !ownedKeys.has(key)) return [line];
+    if (!Object.hasOwn(enabledValue, key)) return [];
+    seen.add(key);
+    return [`${key} = ${JSON.stringify(enabledValue[key])}`];
+  });
+
+  for (const [key, item] of Object.entries(enabledValue)) {
+    if (!seen.has(key)) updated.push(`${key} = ${JSON.stringify(item)}`);
+  }
+
+  const result = [...lines.slice(0, start + 1), ...updated, ...lines.slice(end)].join('\n');
+
+  try {
+    parseToml(result);
+  } catch (error) {
+    throw new Error(
+      `Rayrun refused to write invalid TOML: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return result;
+};

package/src/main.js

@@ -0,0 +1,198 @@
+import { clientDefinitions, detectClients } from './clients.js';
+import { applySetup, rollbackSetup } from './setup.js';
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline/promises';
+
+const packageVersion = createRequire(import.meta.url)('../package.json').version;
+
+const usage = `Usage:
+  rayrun setup <endpoint> [--client <id> ... | --all] [--project] [--yes] [--dry-run] [--login | --no-login]
+  rayrun setup rollback <backup-id>
+
+Clients: claude-code, codex, cursor, vscode, windsurf, devin, opencode`;
+
+export const validateEndpoint = (value) => {
+  let endpoint;
+
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new Error('Endpoint must be an absolute HTTP or HTTPS URL.');
+  }
+
+  if (!['http:', 'https:'].includes(endpoint.protocol)) {
+    throw new Error('Endpoint must use HTTP or HTTPS.');
+  }
+
+  if (
+    endpoint.protocol === 'http:' &&
+    !['127.0.0.1', '::1', 'localhost'].includes(endpoint.hostname)
+  ) {
+    throw new Error('HTTP endpoints are only allowed on localhost. Use HTTPS for remote gateways.');
+  }
+
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error('Endpoint cannot contain credentials, a query string, or a fragment.');
+  }
+
+  const pathname = endpoint.pathname.replace(/\/$/u, '');
+
+  if (!pathname.endsWith('/mcp') && !pathname.endsWith('/mcp/direct')) {
+    throw new Error('Endpoint path must end in /mcp or /mcp/direct.');
+  }
+
+  endpoint.pathname = pathname;
+  return endpoint.href;
+};
+
+export const parseArguments = (arguments_) => {
+  const options = {
+    all: false,
+    clientIds: [],
+    dryRun: false,
+    login: null,
+    project: false,
+    yes: false,
+  };
+  const positional = [];
+
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+
+    if (argument === '--client') {
+      const value = arguments_[index + 1];
+      if (!value) throw new Error('--client requires an id.');
+      options.clientIds.push(value);
+      index += 1;
+    } else if (argument === '--all') options.all = true;
+    else if (argument === '--project') options.project = true;
+    else if (argument === '--yes') options.yes = true;
+    else if (argument === '--dry-run') options.dryRun = true;
+    else if (argument === '--login') options.login = true;
+    else if (argument === '--no-login') options.login = false;
+    else if (argument?.startsWith('--')) throw new Error(`Unknown option: ${argument}`);
+    else if (argument) positional.push(argument);
+  }
+
+  return { options, positional };
+};
+
+export const resolveLogin = ({ isInteractive, login, yes }) => {
+  return login ?? (!yes && isInteractive);
+};
+
+export const assertInteractiveSelectionAllowed = (isInteractive) => {
+  if (!isInteractive) {
+    throw new Error('Non-interactive setup requires --client <id> or --all --yes.');
+  }
+};
+
+const selectInteractively = async (clients) => {
+  const terminal = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await terminal.question(
+    `${clients.map((client, index) => `${String(index + 1)}. ${client.label}`).join('\n')}\nSelect clients (comma-separated): `,
+  );
+  terminal.close();
+  const indexes = new Set(answer.split(',').map((part) => Number(part.trim()) - 1));
+  return clients.filter((_client, index) => indexes.has(index));
+};
+
+export const main = async (arguments_) => {
+  if (arguments_.includes('--help') || arguments_.includes('-h')) {
+    process.stdout.write(`${usage}\n`);
+    return;
+  }
+  if (arguments_.includes('--version') || arguments_.includes('-v')) {
+    process.stdout.write(`${String(packageVersion)}\n`);
+    return;
+  }
+  const { options, positional } = parseArguments(arguments_);
+
+  if (positional[0] !== 'setup') {
+    throw new Error(usage);
+  }
+
+  if (positional[1] === 'rollback') {
+    if (!positional[2]) throw new Error(usage);
+    const restored = await rollbackSetup({ id: positional[2] });
+    process.stdout.write(`Restored ${String(restored.length)} configuration files.\n`);
+    return;
+  }
+
+  if (!positional[1]) throw new Error(usage);
+  const endpoint = validateEndpoint(positional[1]);
+  const allDefinitions = clientDefinitions({ project: options.project });
+  const detected = await detectClients({ project: options.project });
+  const byId = new Map([...allDefinitions, ...detected].map((client) => [client.id, client]));
+  let clients;
+
+  if (options.clientIds.length > 0) {
+    clients = [...new Set(options.clientIds)].map((id) => {
+      const client = byId.get(id);
+      if (!client) throw new Error(`Unknown client: ${String(id)}`);
+      if (options.project && client.projectUnsupported) {
+        throw new Error(`${client.label} does not support project-scoped MCP configuration.`);
+      }
+      return client;
+    });
+  } else if (options.all) {
+    clients = detected;
+  } else if (options.yes) {
+    if (detected.length === 0) {
+      throw new Error('No supported clients were detected. Pass --client explicitly.');
+    }
+    clients = detected;
+  } else {
+    assertInteractiveSelectionAllowed(process.stdin.isTTY === true);
+    clients = await selectInteractively(detected);
+  }
+
+  if (clients.length === 0) {
+    throw new Error('No clients selected.');
+  }
+
+  const result = await applySetup({
+    clients,
+    dryRun: options.dryRun,
+    endpoint,
+    login: resolveLogin({
+      isInteractive: process.stdin.isTTY === true,
+      login: options.login,
+      yes: options.yes,
+    }),
+  });
+
+  if (options.dryRun) {
+    process.stdout.write(
+      `Would update:\n${result.changedTargets.map((target) => `- ${target}`).join('\n')}\n`,
+    );
+    return;
+  }
+
+  process.stdout.write(
+    result.changedTargets.length === 0
+      ? 'Rayrun is already configured. No files changed.\n'
+      : `Configured ${String(clients.length)} client(s).${result.backupId ? ` Roll back with: rayrun setup rollback ${result.backupId}` : ''}\n`,
+  );
+
+  for (const client of clients) {
+    if (client.projectInstruction)
+      process.stdout.write(`${client.label}: ${client.projectInstruction}\n`);
+  }
+
+  for (const failure of result.loginFailures) {
+    process.stderr.write(
+      `${failure.client} was configured but still needs login: ${failure.message}\n`,
+    );
+  }
+
+  for (const skipped of result.loginSkipped) {
+    process.stdout.write(`${skipped.client}: ${skipped.message}\n`);
+  }
+
+  if (result.loginFailures.length > 0) {
+    throw new Error(
+      `${String(result.loginFailures.length)} client login${result.loginFailures.length === 1 ? '' : 's'} failed. Configuration was kept; run the client's MCP login command after fixing the error.`,
+    );
+  }
+};

package/src/setup.js

@@ -0,0 +1,467 @@
+import { executableExists } from './clients.js';
+import { updateJsonConfig, updateTomlConfig } from './config.js';
+import { spawn } from 'node:child_process';
+/* eslint-disable node/no-process-env -- the installer intentionally writes under the invoking user's config home */
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const checksum = (value) => createHash('sha256').update(value).digest('hex');
+
+const assertNoSymbolicLinkComponents = async (target) => {
+  const absoluteTarget = path.resolve(target);
+  const root = path.parse(absoluteTarget).root;
+  const components = path.relative(root, absoluteTarget).split(path.sep).filter(Boolean);
+  let current = root;
+
+  for (const component of components) {
+    current = path.join(current, component);
+
+    try {
+      const metadata = await lstat(current);
+
+      if (metadata.isSymbolicLink()) {
+        throw new Error(`Refusing to use symbolic-link configuration path: ${current}`);
+      }
+    } catch (error) {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') return;
+      throw error;
+    }
+  }
+};
+
+const readSnapshot = async (target) => {
+  await assertNoSymbolicLinkComponents(target);
+
+  try {
+    const metadata = await lstat(target);
+
+    if (metadata.isSymbolicLink()) {
+      throw new Error(`Refusing to replace symbolic-link configuration: ${target}`);
+    }
+
+    const contents = await readFile(target);
+    return { contents, existed: true, mode: metadata.mode & 0o777, target };
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return { contents: Buffer.alloc(0), existed: false, mode: 0o600, target };
+    }
+
+    throw error;
+  }
+};
+
+const atomicWrite = async ({ contents, mode, target }) => {
+  await assertNoSymbolicLinkComponents(target);
+  await mkdir(path.dirname(target), { mode: 0o700, recursive: true });
+  await assertNoSymbolicLinkComponents(path.dirname(target));
+  const temporary = path.join(
+    path.dirname(target),
+    `.${path.basename(target)}.rayrun-${randomUUID()}`,
+  );
+
+  try {
+    await writeFile(temporary, contents, { mode });
+    await rename(temporary, target);
+    await chmod(target, mode);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+};
+
+const snapshotsEqual = (left, right) => {
+  return (
+    left.existed === right.existed &&
+    left.mode === right.mode &&
+    checksum(left.contents) === checksum(right.contents)
+  );
+};
+
+const restoreSnapshots = async (mutations) => {
+  const ordered = mutations.toReversed();
+  for (const { after, before } of ordered) {
+    const current = await readSnapshot(before.target);
+
+    if (!snapshotsEqual(current, after)) {
+      throw new Error(
+        `Refusing to overwrite configuration changed after Rayrun setup: ${before.target}`,
+      );
+    }
+  }
+
+  const restored = [];
+  try {
+    for (const mutation of ordered) {
+      if (mutation.before.existed) {
+        await atomicWrite(mutation.before);
+      } else {
+        await rm(mutation.before.target, { force: true });
+      }
+      restored.push(mutation);
+    }
+  } catch (error) {
+    for (const mutation of restored.toReversed()) {
+      if (mutation.after.existed) {
+        await atomicWrite(mutation.after);
+      } else {
+        await rm(mutation.after.target, { force: true });
+      }
+    }
+    throw error;
+  }
+};
+
+const run = async ({ args, command, cwd }) => {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: 'inherit' });
+
+    child.once('error', reject);
+    child.once('exit', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${command} exited with status ${String(code)}`));
+      }
+    });
+  });
+};
+
+const capture = async ({ args, command, cwd }) => {
+  return await new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    let output = '';
+
+    child.stdout.on('data', (chunk) => {
+      output += String(chunk);
+    });
+    child.once('error', () => resolve(null));
+    child.once('exit', (code) => resolve(code === 0 ? output : null));
+  });
+};
+
+export const outputContainsEndpoint = ({ endpoint, output }) => {
+  let candidates = [];
+
+  try {
+    const parsed = JSON.parse(output);
+    const visit = (value) => {
+      if (!value || typeof value !== 'object') return;
+      for (const [key, child] of Object.entries(value)) {
+        if ((key === 'url' || key === 'serverUrl') && typeof child === 'string') {
+          candidates.push(child);
+        } else {
+          visit(child);
+        }
+      }
+    };
+    visit(parsed);
+  } catch {
+    candidates = [
+      ...output.matchAll(/^\s*(?:server\s+)?url\s*[:=]\s*(https?:\/\/\S+)\s*$/gimu),
+    ].map((match) => match[1]);
+  }
+
+  return candidates.some((candidate) => {
+    try {
+      return new URL(candidate.replace(/[),}\]]+$/u, '')).href === endpoint;
+    } catch {
+      return false;
+    }
+  });
+};
+
+const assertUnchanged = async (snapshot) => {
+  const current = await readSnapshot(snapshot.target);
+
+  if (!snapshotsEqual(current, snapshot)) {
+    throw new Error(`Configuration changed while setup was running: ${snapshot.target}`);
+  }
+};
+
+const backupRoot = ({ environment = process.env, homeDirectory = os.homedir() } = {}) => {
+  return path.join(
+    environment.RAYRUN_CONFIG_HOME ?? path.join(homeDirectory, '.rayrun'),
+    'backups',
+    'setup',
+  );
+};
+
+const writeBackup = async ({ environment, homeDirectory, snapshots }) => {
+  const id = `${new Date().toISOString().replaceAll(/[:.]/gu, '-')}-${randomUUID().slice(0, 8)}`;
+  const directory = path.join(backupRoot({ environment, homeDirectory }), id);
+
+  await mkdir(directory, { mode: 0o700, recursive: true });
+  await chmod(directory, 0o700);
+  const entries = [];
+
+  for (const [index, snapshot] of snapshots.entries()) {
+    const backupName = `${String(index)}.backup`;
+
+    if (snapshot.existed) {
+      await writeFile(path.join(directory, backupName), snapshot.contents, { mode: 0o600 });
+    }
+
+    entries.push({
+      backupName: snapshot.existed ? backupName : null,
+      checksum: checksum(snapshot.contents),
+      existed: snapshot.existed,
+      mode: snapshot.mode,
+      installedChecksum: null,
+      installedExisted: null,
+      installedMode: null,
+      target: snapshot.target,
+    });
+  }
+
+  await writeFile(
+    path.join(directory, 'manifest.json'),
+    `${JSON.stringify({ createdAt: new Date().toISOString(), entries, id, version: 1 }, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+
+  return { directory, entries, id };
+};
+
+const completeBackup = async ({ backup, mutations }) => {
+  const afterByTarget = new Map(
+    mutations.map((mutation) => [mutation.after.target, mutation.after]),
+  );
+  const entries = backup.entries.map((entry) => {
+    const after = afterByTarget.get(entry.target);
+
+    return {
+      ...entry,
+      installedChecksum: after ? checksum(after.contents) : null,
+      installedExisted: after?.existed ?? null,
+      installedMode: after?.mode ?? null,
+    };
+  });
+
+  await atomicWrite({
+    contents: Buffer.from(
+      `${JSON.stringify({ completedAt: new Date().toISOString(), entries, id: backup.id, version: 1 }, null, 2)}\n`,
+    ),
+    mode: 0o600,
+    target: path.join(backup.directory, 'manifest.json'),
+  });
+};
+
+export const rollbackSetup = async ({ environment, homeDirectory, id }) => {
+  if (!/^[\w:-]+$/u.test(id) || path.basename(id) !== id) {
+    throw new Error('Invalid backup id.');
+  }
+
+  const directory = path.join(backupRoot({ environment, homeDirectory }), id);
+  const manifest = JSON.parse(await readFile(path.join(directory, 'manifest.json'), 'utf8'));
+  if (
+    !manifest ||
+    typeof manifest !== 'object' ||
+    manifest.version !== 1 ||
+    manifest.id !== id ||
+    typeof manifest.completedAt !== 'string' ||
+    !Array.isArray(manifest.entries)
+  ) {
+    throw new Error('Backup manifest is incomplete or unsupported.');
+  }
+  const snapshots = [];
+  const mutations = [];
+
+  for (const entry of manifest.entries) {
+    if (
+      !entry ||
+      typeof entry !== 'object' ||
+      typeof entry.target !== 'string' ||
+      !path.isAbsolute(entry.target) ||
+      entry.target === path.parse(entry.target).root ||
+      typeof entry.existed !== 'boolean' ||
+      !Number.isInteger(entry.mode) ||
+      entry.mode < 0 ||
+      entry.mode > 0o777 ||
+      (entry.backupName !== null &&
+        (typeof entry.backupName !== 'string' ||
+          path.basename(entry.backupName) !== entry.backupName ||
+          !/^\d+\.backup$/u.test(entry.backupName))) ||
+      typeof entry.checksum !== 'string' ||
+      typeof entry.installedExisted !== 'boolean' ||
+      !Number.isInteger(entry.installedMode) ||
+      entry.installedMode < 0 ||
+      entry.installedMode > 0o777 ||
+      typeof entry.installedChecksum !== 'string'
+    ) {
+      throw new Error('Backup manifest contains an invalid entry.');
+    }
+    const contents = entry.backupName
+      ? await readFile(path.join(directory, entry.backupName))
+      : Buffer.alloc(0);
+
+    if (checksum(contents) !== entry.checksum) {
+      throw new Error(`Backup checksum failed for ${String(entry.target)}.`);
+    }
+
+    const before = { contents, existed: entry.existed, mode: entry.mode, target: entry.target };
+    const current = await readSnapshot(entry.target);
+    const installed = {
+      contents: current.contents,
+      existed: entry.installedExisted,
+      mode: entry.installedMode,
+      target: entry.target,
+    };
+
+    if (
+      current.existed !== entry.installedExisted ||
+      current.mode !== entry.installedMode ||
+      checksum(current.contents) !== entry.installedChecksum
+    ) {
+      throw new Error(`Refusing to overwrite configuration changed after setup: ${entry.target}`);
+    }
+
+    snapshots.push(before);
+    mutations.push({ after: installed, before });
+  }
+
+  await restoreSnapshots(mutations);
+  return snapshots.map((snapshot) => snapshot.target);
+};
+
+export const applySetup = async ({
+  clients,
+  dryRun = false,
+  endpoint,
+  environment = process.env,
+  homeDirectory = os.homedir(),
+  login = true,
+}) => {
+  const targets = [
+    ...new Set(clients.map((client) => (client.type === 'native' ? client.target : client.path))),
+  ];
+  const snapshots = await Promise.all(targets.map(readSnapshot));
+  const directWrites = [];
+
+  for (const client of clients) {
+    if (client.type !== 'json' && client.type !== 'toml') {
+      continue;
+    }
+
+    const snapshot = snapshots.find((candidate) => candidate.target === client.path);
+    const source = snapshot?.contents.toString('utf8') ?? '';
+    const updated =
+      client.type === 'json'
+        ? updateJsonConfig({
+            propertyPath: client.propertyPath,
+            source,
+            value: client.value(endpoint),
+          })
+        : updateTomlConfig({ section: client.section, source, value: client.value(endpoint) });
+    const contents = Buffer.from(`${updated.trimEnd()}\n`);
+
+    if (!snapshot || !contents.equals(snapshot.contents)) {
+      directWrites.push({ contents, mode: snapshot?.mode ?? 0o600, target: client.path });
+    }
+  }
+
+  const nativeClients = [];
+
+  for (const client of clients.filter((candidate) => candidate.type === 'native')) {
+    const current = client.getArgs
+      ? await capture({ args: client.getArgs, command: client.command, cwd: client.cwd })
+      : null;
+
+    if (current === null || !outputContainsEndpoint({ endpoint, output: current })) {
+      nativeClients.push({ ...client, replaceExisting: current !== null });
+    }
+  }
+  const changedTargets = new Set(directWrites.map((write) => write.target));
+
+  for (const client of nativeClients) {
+    changedTargets.add(client.target);
+  }
+
+  if (dryRun) {
+    return { backupId: null, changedTargets: [...changedTargets], loginFailures: [] };
+  }
+
+  const changedSnapshots = snapshots.filter((snapshot) => changedTargets.has(snapshot.target));
+  const backup =
+    changedSnapshots.length === 0
+      ? null
+      : await writeBackup({ environment, homeDirectory, snapshots: changedSnapshots });
+  const mutations = [];
+
+  try {
+    for (const client of nativeClients) {
+      const snapshot = snapshots.find((candidate) => candidate.target === client.target);
+      if (snapshot) await assertUnchanged(snapshot);
+      try {
+        if (client.replaceExisting && client.removeArgs) {
+          await run({ args: client.removeArgs, command: client.command, cwd: client.cwd });
+        }
+        await run({ args: client.nativeArgs(endpoint), command: client.command, cwd: client.cwd });
+      } finally {
+        if (snapshot) {
+          const after = await readSnapshot(snapshot.target);
+          if (!snapshotsEqual(snapshot, after)) mutations.push({ after, before: snapshot });
+        }
+      }
+    }
+
+    for (const write of directWrites) {
+      const snapshot = snapshots.find((candidate) => candidate.target === write.target);
+      if (snapshot) await assertUnchanged(snapshot);
+      try {
+        await atomicWrite(write);
+      } finally {
+        if (snapshot) {
+          const after = await readSnapshot(write.target);
+          if (!snapshotsEqual(snapshot, after)) mutations.push({ after, before: snapshot });
+        }
+      }
+    }
+
+    if (backup) {
+      await completeBackup({ backup, mutations });
+    }
+  } catch (error) {
+    await restoreSnapshots(mutations);
+    throw new Error(
+      `Setup failed and every changed configuration was restored${backup ? ` from ${backup.id}` : ''}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const loginFailures = [];
+  const loginSkipped = login
+    ? []
+    : clients
+        .filter((candidate) => candidate.loginCommand)
+        .map((client) => ({
+          client: client.label,
+          message: `Run ${client.loginCommand.command} ${client.loginCommand.args.join(' ')} to authenticate.`,
+        }));
+
+  if (login) {
+    for (const client of clients.filter((candidate) => candidate.loginCommand)) {
+      if (!(await executableExists(client.loginCommand.command, environment))) {
+        loginSkipped.push({
+          client: client.label,
+          message: `${client.loginCommand.command} is not installed; authenticate Rayrun from the client's MCP settings.`,
+        });
+        continue;
+      }
+      try {
+        await run(client.loginCommand);
+      } catch (error) {
+        loginFailures.push({
+          client: client.label,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  }
+
+  return {
+    backupId: backup?.id ?? null,
+    changedTargets: [...changedTargets],
+    loginFailures,
+    loginSkipped,
+  };
+};