@callstack/apex 0.2.1 → 0.3.0

package/package.json

@@ -1,22 +1,39 @@
 {
   "name": "@callstack/apex",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Detects the AI coding assistants installed on your machine and configures them to use Callstack Apex.",
   "license": "MIT",
+  "keywords": [
+    "callstack",
+    "apex",
+    "ai"
+  ],
+  "type": "module",
   "bin": {
     "apex": "bin/apex.js"
   },
   "files": [
     "bin",
-    "src",
+    "dist",
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
-  "keywords": [
-    "callstack",
-    "apex",
-    "ai"
-  ]
+  "scripts": {
+    "build": "tsdown",
+    "pretest": "npm run build",
+    "prepack": "npm run build",
+    "test": "node --test",
+    "check": "for f in src/*.js bin/apex.js; do node --check \"$f\" || exit 1; done && npm run build"
+  },
+  "devDependencies": {
+    "@clack/prompts": "1.8.1",
+    "jsonc-parser": "3.3.1",
+    "smol-toml": "1.4.2",
+    "tsdown": "^0.22.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/assistants/aiSdk.js

@@ -1,54 +0,0 @@
-'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

@@ -1,37 +0,0 @@
-'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

@@ -1,56 +0,0 @@
-'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

@@ -1,30 +0,0 @@
-'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

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

package/src/assistants/opencode.js

@@ -1,103 +0,0 @@
-'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

@@ -1,55 +0,0 @@
-'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

@@ -1,34 +0,0 @@
-'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

@@ -1,89 +0,0 @@
-'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

@@ -1,91 +0,0 @@
-'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

@@ -1,49 +0,0 @@
-'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,
-};