@callstack/apex 0.2.0

package/README.md

@@ -0,0 +1,71 @@
+# Apex CLI
+
+Configures the AI coding assistants installed on your machine to use
+[Callstack Apex](https://api.callstack.ai) — an OpenAI-compatible endpoint
+serving the `callstack/Apex` model.
+
+## Install
+
+```sh
+curl -fsSL https://apex.callstack.ai/install.sh | sh
+```
+
+This checks for Node.js 18+ and then runs `npx @callstack/apex init` for you.
+
+If you already have Node.js, you can skip the script entirely:
+
+```sh
+npx @callstack/apex init
+```
+
+## What `init` does
+
+It detects which of these are installed and writes (or updates) their config
+to point at Apex, backing up any existing file first (`<file>.bak-<timestamp>`):
+
+| Assistant | Config written |
+| --- | --- |
+| Claude Code | `~/.claude/settings.json` |
+| Codex | `~/.codex/config.toml`, `~/.codex/callstack_ai.config.toml` |
+| OpenCode | `~/.config/opencode/opencode.json` (v1 or v2 format, auto-detected), `~/.local/share/opencode/auth.json` (if absent, v1 only) |
+| pi | `~/.pi/agent/models.json` |
+| Cursor | manual steps (GUI-only, printed to the terminal) |
+| VS Code + GitHub Copilot | manual steps (GUI-only, printed to the terminal) |
+| Vercel AI SDK / Eve | `.env` in the current project, if it depends on `ai`/`eve` |
+
+You'll be prompted for your Apex API key (input hidden), or pass it directly:
+
+```sh
+npx @callstack/apex init --api-key sk-XXX
+# or
+APEX_API_KEY=sk-XXX npx @callstack/apex init --yes
+```
+
+Other flags: `--dry-run` (show changes without writing), `--only <ids>` /
+`--skip <ids>` (comma-separated, see `apex list` for ids).
+
+## Commands
+
+```sh
+apex init      # detect + configure
+apex list      # show which assistants are detected, without changing anything
+```
+
+## Security
+
+Your Apex API key is written locally to config files under your home
+directory (and, for JS projects, to a local `.env`). Never commit these
+files or share the key. Rotate it if you suspect it leaked.
+
+## Troubleshooting
+
+See the internal "Apex - how to use it?" Notion page, or ask in `#apex` on
+Slack. Known issue: some `pi` users have hit Cloudflare 403s — this has come
+up more than once and is being tracked there.
+
+## Local development
+
+```sh
+npm link
+apex --help
+```

package/bin/apex.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli.js').main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@callstack/apex",
+  "version": "0.2.0",
+  "description": "Detects the AI coding assistants installed on your machine and configures them to use Callstack Apex.",
+  "license": "MIT",
+  "bin": {
+    "apex": "bin/apex.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "callstack",
+    "apex",
+    "ai"
+  ]
+}

package/src/assistants/aiSdk.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { readJsonIfExists, pathExists, backupFile } = require('../util/fsHelpers');
+
+const id = 'ai-sdk';
+const name = 'Vercel AI SDK / Eve (programmatic)';
+
+function projectDeps(cwd) {
+  const pkg = readJsonIfExists(path.join(cwd, 'package.json'));
+  if (!pkg) return null;
+  return { ...pkg.dependencies, ...pkg.devDependencies };
+}
+
+function detect({ cwd }) {
+  const deps = projectDeps(cwd);
+  if (!deps) return false;
+  return Boolean(deps['ai'] || deps['@ai-sdk/openai'] || deps['eve']);
+}
+
+function apply({ cwd, apiKey, dryRun, log }) {
+  const deps = projectDeps(cwd) || {};
+  const envPath = path.join(cwd, '.env');
+  const existingEnv = pathExists(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+
+  if (apiKey && !/^APEX_API_KEY=/m.test(existingEnv)) {
+    const separator = existingEnv && !existingEnv.endsWith('\n') ? '\n' : '';
+    const nextEnv = `${existingEnv}${separator}APEX_API_KEY=${apiKey}\n`;
+    if (!dryRun) {
+      backupFile(envPath);
+      fs.writeFileSync(envPath, nextEnv);
+    }
+    log(`wrote APEX_API_KEY to ${envPath} (make sure .env is gitignored)`);
+  } else if (!apiKey) {
+    log(`no API key provided — add APEX_API_KEY manually to ${envPath}`);
+  } else {
+    log(`${envPath} already has APEX_API_KEY, left untouched`);
+  }
+
+  log('connector snippet (Vercel AI SDK):');
+  log("  import { createOpenAI } from '@ai-sdk/openai';");
+  log('  const apex = createOpenAI({ apiKey: process.env.APEX_API_KEY, baseURL: "https://api.callstack.ai/v1", name: "callstack" });');
+  log('  // use apex(\'callstack/Apex\') with generateText / streamText');
+  log('  // reasoning effort (none/low/medium/xhigh): pass providerOptions: { callstack: { reasoningEffort: "medium" } }');
+
+  if (deps['eve']) {
+    log('Eve note: set modelContextWindowTokens: 262_144 on defineAgent, or compaction will fail to compile.');
+  }
+
+  return { configured: Boolean(apiKey) };
+}
+
+module.exports = { id, name, detect, apply };

package/src/assistants/claudeCode.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const path = require('node:path');
+const { commandExists, dirExists, homeDir } = require('../util/detect');
+const { readJsonIfExists, backupFile, writeJson } = require('../util/fsHelpers');
+
+const id = 'claude-code';
+const name = 'Claude Code';
+
+function detect() {
+  return commandExists('claude') || dirExists(homeDir(), '.claude');
+}
+
+function apply({ apiKey, dryRun, log }) {
+  const settingsPath = path.join(homeDir(), '.claude', 'settings.json');
+  const settings = readJsonIfExists(settingsPath) || {};
+  settings.env = settings.env || {};
+  settings.env.CLAUDE_CODE_ATTRIBUTION_HEADER = '0';
+  settings.env.ANTHROPIC_BASE_URL = 'https://api.callstack.ai';
+  settings.env.ANTHROPIC_MODEL = 'callstack/Apex';
+  if (apiKey) {
+    settings.env.ANTHROPIC_AUTH_TOKEN = apiKey;
+  }
+
+  if (!dryRun) {
+    backupFile(settingsPath);
+    writeJson(settingsPath, settings);
+  }
+  log(`wrote ${settingsPath}`);
+  if (!apiKey) {
+    log('no API key provided — set ANTHROPIC_AUTH_TOKEN in that file manually');
+  }
+
+  return { configured: true };
+}
+
+module.exports = { id, name, detect, apply };

package/src/assistants/codex.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const path = require('node:path');
+const { commandExists, dirExists, homeDir } = require('../util/detect');
+const { readTextIfExists, backupFile, writeFileEnsuringDir } = require('../util/fsHelpers');
+const { upsertTomlSection } = require('../util/toml');
+
+const id = 'codex';
+const name = 'Codex';
+
+function detect() {
+  return commandExists('codex') || dirExists(homeDir(), '.codex');
+}
+
+function apply({ dryRun, log }) {
+  const home = homeDir();
+  const configPath = path.join(home, '.codex', 'config.toml');
+  const profilePath = path.join(home, '.codex', 'callstack_ai.config.toml');
+
+  const providerBody = [
+    'name                  = "callstack.ai"',
+    'base_url              = "https://api.callstack.ai/v1"',
+    'env_key               = "CALLSTACK_AUTH_TOKEN"',
+    'wire_api              = "responses"',
+    'requires_openai_auth  = false',
+    '',
+  ].join('\n');
+
+  const existingConfig = readTextIfExists(configPath);
+  const nextConfig = upsertTomlSection(existingConfig, 'model_providers.callstack_ai', providerBody);
+  if (!dryRun) {
+    backupFile(configPath);
+    writeFileEnsuringDir(configPath, nextConfig);
+  }
+  log(`wrote ${configPath}`);
+
+  const profileContents = [
+    'model_provider = "callstack_ai"',
+    'model          = "callstack/Apex"',
+    'model_context_window    = 262144',
+    'model_max_output_tokens = 16384',
+    'model_reasoning_effort  = "medium"',
+    '',
+  ].join('\n');
+  if (!dryRun) {
+    backupFile(profilePath);
+    writeFileEnsuringDir(profilePath, profileContents);
+  }
+  log(`wrote ${profilePath}`);
+
+  log('run with: export CALLSTACK_AUTH_TOKEN="<your Apex API key>" && codex -p callstack_ai');
+
+  return { configured: true };
+}
+
+module.exports = { id, name, detect, apply };

package/src/assistants/cursor.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { commandExists, dirExists, anyAppPathExists, homeDir } = require('../util/detect');
+
+const id = 'cursor';
+const name = 'Cursor';
+
+function detect() {
+  return (
+    commandExists('cursor') ||
+    dirExists(homeDir(), '.cursor') ||
+    anyAppPathExists(['/Applications/Cursor.app'])
+  );
+}
+
+// Cursor's model configuration lives behind its GUI and isn't a documented file
+// format, so this can't be written automatically — print the manual steps instead.
+function apply({ log }) {
+  log('Cursor requires manual setup (no config file to write automatically):');
+  log('  1. Cursor Settings -> Models');
+  log('  2. Enable API Keys -> OpenAI API Key, confirm the prompt');
+  log('  3. Paste your Apex API key, and set "Override OpenAI Base URL" to https://api.callstack.ai/v1');
+  log('  4. In Models, "Add Custom Model" -> enter callstack/Apex -> enable it');
+  log('  5. Cmd+L -> pick "Apex" from the model dropdown');
+  log('Note: Cursor has no way to declare model capabilities (tool calling, vision, reasoning) for a custom model — it infers them, so the steps above are all there is to configure.');
+
+  return { configured: false, manual: true };
+}
+
+module.exports = { id, name, detect, apply };

package/src/assistants/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+module.exports = [
+  require('./claudeCode'),
+  require('./codex'),
+  require('./opencode'),
+  require('./pi'),
+  require('./cursor'),
+  require('./vscodeCopilot'),
+  require('./aiSdk'),
+];

package/src/assistants/opencode.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const path = require('node:path');
+const { commandExists, commandVersion, dirExists, homeDir } = require('../util/detect');
+const { readJsonIfExists, backupFile, writeJson, pathExists } = require('../util/fsHelpers');
+
+const id = 'opencode';
+const name = 'OpenCode';
+
+function detect() {
+  return commandExists('opencode') || dirExists(homeDir(), '.config', 'opencode');
+}
+
+// OpenCode 2 renamed the config's top-level `provider` map to `providers` and
+// changed the per-model capability field names (tool_call -> capabilities.tools,
+// etc). It's still invoked as `opencode`, so version is the only way to tell
+// v1 and v2 apart. If detection fails, default to the v1 shape: OpenCode 2
+// still reads and normalizes v1-style config, but v1 installs can't read v2-only fields.
+function isV2() {
+  const version = commandVersion('opencode', ['--version']);
+  return Boolean(version && version.major >= 2);
+}
+
+function modelConfigV1() {
+  return {
+    name: 'Apex',
+    reasoning: true,
+    tool_call: true,
+    attachment: true,
+    modalities: { input: ['text', 'image'], output: ['text'] },
+    limit: { context: 262144, input: 240000, output: 16384 },
+    options: { reasoningEffort: 'medium' },
+    variants: {
+      none: { reasoningEffort: 'none' },
+      low: { reasoningEffort: 'low' },
+      medium: { reasoningEffort: 'medium' },
+      xhigh: { reasoningEffort: 'xhigh' },
+    },
+  };
+}
+
+function modelConfigV2() {
+  return {
+    name: 'Apex',
+    capabilities: { tools: true, input: ['text', 'image'], output: ['text'] },
+    limit: { context: 262144, input: 240000, output: 16384 },
+    settings: { reasoningEffort: 'medium' },
+    variants: [
+      { id: 'none', settings: { reasoningEffort: 'none' } },
+      { id: 'low', settings: { reasoningEffort: 'low' } },
+      { id: 'medium', settings: { reasoningEffort: 'medium' } },
+      { id: 'xhigh', settings: { reasoningEffort: 'xhigh' } },
+    ],
+  };
+}
+
+function apply({ apiKey, dryRun, log }) {
+  const home = homeDir();
+  const configPath = path.join(home, '.config', 'opencode', 'opencode.json');
+  const authPath = path.join(home, '.local', 'share', 'opencode', 'auth.json');
+  const v2 = isV2();
+
+  const config = readJsonIfExists(configPath) || { $schema: 'https://opencode.ai/config.json' };
+
+  if (v2) {
+    config.providers = config.providers || {};
+    config.providers['callstack.ai'] = {
+      name: 'callstack.ai',
+      package: '@opencode/ai/providers/openai-compatible',
+      settings: { baseURL: 'https://api.callstack.ai/v1' },
+      models: { 'callstack/Apex': modelConfigV2() },
+    };
+  } else {
+    config.provider = config.provider || {};
+    config.provider['callstack.ai'] = {
+      npm: '@ai-sdk/openai-compatible',
+      name: 'callstack.ai',
+      options: { baseURL: 'https://api.callstack.ai/v1' },
+      models: { 'callstack/Apex': modelConfigV1() },
+    };
+  }
+
+  if (!dryRun) {
+    backupFile(configPath);
+    writeJson(configPath, config);
+  }
+  log(`wrote ${configPath} (OpenCode ${v2 ? 'v2' : 'v1'} config format)`);
+
+  if (v2) {
+    log('run `/connect`, select `callstack.ai` -> "Manually enter API Key", then paste your Apex API key');
+  } else if (pathExists(authPath)) {
+    log(`skipped ${authPath} (already exists — leaving your existing credentials untouched)`);
+  } else if (apiKey) {
+    if (!dryRun) writeJson(authPath, { 'callstack.ai': { type: 'api', key: apiKey } });
+    log(`wrote ${authPath}`);
+  } else {
+    log(`skipped ${authPath} (no API key provided — create it manually, see docs)`);
+  }
+
+  return { configured: true };
+}
+
+module.exports = { id, name, detect, apply };

package/src/assistants/pi.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const path = require('node:path');
+const { dirExists, homeDir } = require('../util/detect');
+const { readJsonIfExists, backupFile, writeJson } = require('../util/fsHelpers');
+
+const id = 'pi';
+const name = 'pi';
+
+function detect() {
+  // ".pi" is checked instead of the "pi" binary, which collides with unrelated tools on PATH.
+  return dirExists(homeDir(), '.pi');
+}
+
+function apply({ apiKey, dryRun, log }) {
+  const configPath = path.join(homeDir(), '.pi', 'agent', 'models.json');
+  const config = readJsonIfExists(configPath) || { providers: {} };
+  config.providers = config.providers || {};
+  config.providers.callstack = {
+    baseUrl: 'https://api.callstack.ai/v1',
+    api: 'openai-completions',
+    apiKey: apiKey || 'XXX',
+    models: [
+      {
+        id: 'callstack/Apex',
+        reasoning: true,
+        input: ['text', 'image'],
+        thinkingLevelMap: {
+          off: 'none',
+          minimal: null,
+          low: 'low',
+          medium: 'medium',
+          high: null,
+          xhigh: 'xhigh',
+          max: null,
+        },
+        contextWindow: 262144,
+      },
+    ],
+  };
+
+  if (!dryRun) {
+    backupFile(configPath);
+    writeJson(configPath, config);
+  }
+  log(`wrote ${configPath}`);
+  if (!apiKey) {
+    log('no API key provided — replace the placeholder "XXX" in that file manually');
+  }
+  log('known issue: some users have hit Cloudflare 403s with pi — ask in #apex if this happens to you');
+
+  return { configured: true };
+}
+
+module.exports = { id, name, detect, apply };

package/src/assistants/vscodeCopilot.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { commandExists, dirExists, anyAppPathExists, homeDir } = require('../util/detect');
+
+const id = 'vscode-copilot';
+const name = 'VS Code (GitHub Copilot)';
+
+function detect() {
+  return (
+    commandExists('code') ||
+    dirExists(homeDir(), '.vscode') ||
+    anyAppPathExists(['/Applications/Visual Studio Code.app'])
+  );
+}
+
+// Adding a custom Copilot model endpoint goes through VS Code's GUI and an
+// interactive secret input, so this can't be written automatically.
+function apply({ log }) {
+  log('VS Code + GitHub Copilot requires manual setup (make sure VS Code is up to date):');
+  log('  1. Open the GitHub Copilot panel -> model selector -> "Manage Models..."');
+  log('  2. "Add Models" -> "Custom Endpoint"');
+  log('  3. Name it "callstack.ai", paste your Apex API key, choose "Chat Completions"');
+  log('  4. In the JSON editor that opens, set the "models" array to:');
+  log('     [{');
+  log('       "id": "callstack/Apex", "name": "Apex", "url": "https://api.callstack.ai/v1",');
+  log('       "toolCalling": true, "vision": true, "thinking": true,');
+  log('       "contextWindow": 262144, "maxOutputTokens": 16384,');
+  log('       "supportsReasoningEffort": ["none", "low", "medium", "xhigh"], "reasoningEffortFormat": "chat-completions"');
+  log('     }]');
+
+  return { configured: false, manual: true };
+}
+
+module.exports = { id, name, detect, apply };

package/src/cli.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { runInit, runList } = require('./init');
+
+const VERSION = require('../package.json').version;
+
+const HELP = `apex — configure your AI coding assistants to use Callstack Apex
+
+Usage:
+  apex init [options]     Detect installed assistants and configure them
+  apex list               Show which supported assistants are detected
+  apex --help             Show this help
+  apex --version          Show the CLI version
+
+Options for "init":
+  --api-key <key>   Apex API key (else reads APEX_API_KEY / CALLSTACK_AUTH_TOKEN, else prompts)
+  --yes, -y         Don't prompt; skip anything that needs interactive input
+  --dry-run         Show what would change without writing any files
+  --only <ids>      Comma-separated assistant ids to limit to (see "apex list")
+  --skip <ids>      Comma-separated assistant ids to skip
+`;
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--api-key':
+        opts.apiKey = argv[++i];
+        break;
+      case '--only':
+        opts.only = (argv[++i] || '').split(',').filter(Boolean);
+        break;
+      case '--skip':
+        opts.skip = (argv[++i] || '').split(',').filter(Boolean);
+        break;
+      case '--yes':
+      case '-y':
+        opts.yes = true;
+        break;
+      case '--dry-run':
+        opts.dryRun = true;
+        break;
+      case '--no-key':
+        opts.noKey = true;
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      case '--version':
+      case '-v':
+        opts.version = true;
+        break;
+      default:
+        opts._.push(arg);
+    }
+  }
+  return opts;
+}
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (opts.help || opts._.length === 0) {
+    console.log(HELP);
+    return;
+  }
+
+  const command = opts._[0];
+  switch (command) {
+    case 'init':
+      await runInit(opts);
+      break;
+    case 'list':
+      await runList(opts);
+      break;
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.log(HELP);
+      process.exitCode = 1;
+  }
+}
+
+module.exports = { main, parseArgs };

package/src/init.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const assistants = require('./assistants');
+const { askHidden } = require('./util/prompt');
+
+async function resolveApiKey(opts) {
+  if (opts.apiKey) return opts.apiKey;
+  if (process.env.APEX_API_KEY) return process.env.APEX_API_KEY;
+  if (process.env.CALLSTACK_AUTH_TOKEN) return process.env.CALLSTACK_AUTH_TOKEN;
+  if (opts.noKey || opts.yes) return null;
+  return askHidden('Apex API key (leave blank to skip, add it manually later): ');
+}
+
+function selectAssistants(opts) {
+  let list = assistants;
+  if (opts.only && opts.only.length) {
+    list = list.filter((a) => opts.only.includes(a.id));
+  }
+  if (opts.skip && opts.skip.length) {
+    list = list.filter((a) => !opts.skip.includes(a.id));
+  }
+  return list;
+}
+
+async function runInit(opts) {
+  const cwd = process.cwd();
+  const apiKey = await resolveApiKey(opts);
+  const ctx = { cwd, apiKey, dryRun: Boolean(opts.dryRun) };
+
+  const candidates = selectAssistants(opts);
+  const detected = candidates.filter((a) => {
+    try {
+      return a.detect(ctx);
+    } catch {
+      return false;
+    }
+  });
+
+  if (!detected.length) {
+    console.log('No supported AI assistants were detected on this machine.');
+    console.log(`Supported: ${assistants.map((a) => a.name).join(', ')}`);
+    return;
+  }
+
+  console.log(`Detected: ${detected.map((a) => a.name).join(', ')}`);
+  if (opts.dryRun) console.log('(dry run — no files will be written)\n');
+
+  const results = [];
+  for (const assistant of detected) {
+    console.log(`\n${assistant.name}`);
+    const log = (line) => console.log(`  ${line}`);
+    try {
+      const result = assistant.apply({ ...ctx, log });
+      results.push({ assistant, ...result });
+    } catch (err) {
+      log(`error: ${err.message}`);
+      results.push({ assistant, configured: false, error: err.message });
+    }
+  }
+
+  const configured = results.filter((r) => r.configured);
+  const manual = results.filter((r) => r.manual);
+  console.log('\nSummary:');
+  if (configured.length) {
+    console.log(`  Configured automatically: ${configured.map((r) => r.assistant.name).join(', ')}`);
+  }
+  if (manual.length) {
+    console.log(`  Needs manual steps: ${manual.map((r) => r.assistant.name).join(', ')}`);
+  }
+  if (!apiKey) {
+    console.log('  No API key was provided — some config files were written with a placeholder.');
+    console.log('  Never commit real API keys; keep them out of version control.');
+  }
+  console.log('\nDocs: see the internal "Apex - how to use it?" Notion page, or ask in #apex on Slack.');
+}
+
+async function runList(opts) {
+  const cwd = process.cwd();
+  const ctx = { cwd };
+  for (const assistant of assistants) {
+    let isDetected = false;
+    try {
+      isDetected = assistant.detect(ctx);
+    } catch {
+      isDetected = false;
+    }
+    console.log(`${isDetected ? '[x]' : '[ ]'} ${assistant.name}`);
+  }
+}
+
+module.exports = { runInit, runList };

package/src/util/detect.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { pathExists } = require('./fsHelpers');
+
+function commandExists(cmd) {
+  const finder = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    execFileSync(finder, [cmd], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Returns { major, minor, patch } parsed from `<cmd> <args>` output, or null
+// if the command fails or its output doesn't contain a semver-like version.
+function commandVersion(cmd, args = ['--version']) {
+  try {
+    const out = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const match = out.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return null;
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+  } catch {
+    return null;
+  }
+}
+
+function dirExists(...segments) {
+  return pathExists(path.join(...segments));
+}
+
+function anyAppPathExists(paths) {
+  return paths.some((p) => pathExists(p));
+}
+
+function homeDir() {
+  return os.homedir();
+}
+
+module.exports = {
+  commandExists,
+  commandVersion,
+  dirExists,
+  anyAppPathExists,
+  homeDir,
+};

package/src/util/fsHelpers.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const backedUpThisRun = new Set();
+
+function pathExists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJsonIfExists(filePath) {
+  if (!pathExists(filePath)) return null;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`${filePath} exists but is not valid JSON: ${err.message}`);
+  }
+}
+
+function readTextIfExists(filePath) {
+  return pathExists(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+}
+
+function backupFile(filePath) {
+  if (!pathExists(filePath) || backedUpThisRun.has(filePath)) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${filePath}.bak-${stamp}`;
+  fs.copyFileSync(filePath, backupPath);
+  backedUpThisRun.add(filePath);
+  return backupPath;
+}
+
+function writeFileEnsuringDir(filePath, contents) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents);
+}
+
+function writeJson(filePath, data) {
+  writeFileEnsuringDir(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+module.exports = {
+  pathExists,
+  readJsonIfExists,
+  readTextIfExists,
+  backupFile,
+  writeFileEnsuringDir,
+  writeJson,
+};

package/src/util/prompt.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const readline = require('node:readline');
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function confirm(question, defaultYes = true) {
+  if (!process.stdin.isTTY) return defaultYes;
+  const hint = defaultYes ? 'Y/n' : 'y/N';
+  const answer = (await ask(`${question} (${hint}) `)).toLowerCase();
+  if (!answer) return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+// Char codes, spelled out numerically to avoid embedding raw control bytes in source.
+const CODE_LF = 10;
+const CODE_CR = 13;
+const CODE_CTRL_C = 3;
+const CODE_CTRL_D = 4;
+const CODE_BACKSPACE = 8;
+const CODE_DEL = 127;
+
+function askHidden(question) {
+  if (!process.stdin.isTTY) return ask(question);
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const stdin = process.stdin;
+    process.stdout.write(question);
+
+    let value = '';
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    const onData = (chunk) => {
+      const char = chunk.toString();
+      const code = char.charCodeAt(0);
+
+      if (code === CODE_LF || code === CODE_CR) {
+        stdin.setRawMode(false);
+        stdin.removeListener('data', onData);
+        process.stdout.write('\n');
+        rl.close();
+        resolve(value.trim());
+        return;
+      }
+
+      if (code === CODE_CTRL_C || code === CODE_CTRL_D) {
+        stdin.setRawMode(false);
+        process.stdout.write('\n');
+        process.exit(130);
+        return;
+      }
+
+      if (code === CODE_BACKSPACE || code === CODE_DEL) {
+        value = value.slice(0, -1);
+        return;
+      }
+
+      value += char;
+    };
+    stdin.on('data', onData);
+  });
+}
+
+module.exports = { ask, askHidden, confirm };

package/src/util/toml.js

@@ -0,0 +1,35 @@
+'use strict';
+
+// Minimal helper to idempotently add/replace one top-level [section] block in a
+// TOML file's raw text, without pulling in a TOML parser dependency. Good enough
+// for the narrow, known-shape config files this CLI writes into.
+function upsertTomlSection(existingText, sectionHeader, sectionBody) {
+  const block = `[${sectionHeader}]\n${sectionBody}`;
+  if (!existingText) return block.endsWith('\n') ? block : `${block}\n`;
+
+  const headerLine = `[${sectionHeader}]`;
+  const lines = existingText.split('\n');
+  const startIdx = lines.findIndex((line) => line.trim() === headerLine);
+
+  if (startIdx === -1) {
+    const needsBlankLine = existingText.length > 0 && !existingText.endsWith('\n\n');
+    const separator = existingText.endsWith('\n') ? (needsBlankLine ? '\n' : '') : '\n\n';
+    const suffix = block.endsWith('\n') ? block : `${block}\n`;
+    return `${existingText}${separator}${suffix}`;
+  }
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i += 1) {
+    if (lines[i].trim().startsWith('[')) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  const before = lines.slice(0, startIdx);
+  const after = lines.slice(endIdx);
+  const newLines = [...before, ...block.split('\n').slice(0, -1), ...after];
+  return `${newLines.join('\n').replace(/\n+$/, '\n')}`;
+}
+
+module.exports = { upsertTomlSection };