dxai-cli 1.0.0

package/src/mcp-cmd.js

@@ -0,0 +1,282 @@
+// Fast-path MCP commands: `dxai add <id...>` and `dxai remove <id...>`.
+// No wizard — resolve target agents (from --agents or detection), validate the
+// server IDs, and write/remove directly. Honours --project, --dry-run, --json,
+// and --yes, matching the setup flow's conventions.
+//
+// `add` also accepts official MCP Registry names (`io.github.owner/server`):
+// the record is resolved live and becomes a catalogue entry for this run.
+
+import os from 'os';
+import path from 'path';
+
+import {
+  printBanner, sectionHeader, successMsg, warnMsg, infoMsg, theme, reportMcpResults,
+} from './branding.js';
+import { detectAgents, AGENT_DEFINITIONS } from './detect.js';
+import { MCP_SERVERS, deriveConfigs } from './registry/mcp-servers.js';
+import { fetchRegistryServer, pickTransport, slugForRegistryName } from './registry/mcp-registry.js';
+import { isValidRegistryName, validateRegistryPayload } from './registry/validate.js';
+import {
+  writeMcpConfigs, writeProjectMcpConfigs, previewMcpConfigs,
+} from './config-writer.js';
+import {
+  scanJsonMcpConfig, removeJsonMcpServers,
+  scanTomlMcpConfig, removeTomlMcpServers,
+  scanClaudeCodeMcpServers, removeClaudeCodeMcpServers,
+} from './config-remover.js';
+import {
+  recordSystemMcp, recordProjectMcp, unrecordSystemMcp, unrecordProjectMcp,
+} from './manifest.js';
+import { normalizeOptions, partitionByKnown } from './runtime.js';
+import { collectMcpInputs } from './index.js';
+
+// Validate a list of IDs against a registry; throw a "Known: ..." hint on any miss.
+function requireKnown(ids, knownIds, label) {
+  const { valid, invalid } = partitionByKnown(ids, knownIds);
+  if (invalid.length) {
+    throw new Error(`Unknown ${label}: ${invalid.join(', ')}. Known: ${knownIds.join(', ')}`);
+  }
+  if (valid.length === 0) {
+    throw new Error(`No ${label} given.`);
+  }
+  return valid;
+}
+
+const KNOWN_MCP_IDS = MCP_SERVERS.map((s) => s.id);
+
+// Turn a live registry record into a catalogue entry for this invocation only.
+// Validated like fetched catalogue data before its configs are derived.
+function entryFromRegistry(name, record) {
+  const r = pickTransport(record);
+  if (!r.transport) throw new Error(`${name}: no usable transport (${r.warnings.join('; ')})`);
+  const entry = {
+    id: slugForRegistryName(name),
+    name: r.title || slugForRegistryName(name),
+    description: r.description || '',
+    category: 'registry',
+    registry: { name, resolved: { version: r.registryVersion, at: new Date().toISOString(), fields: ['transport'] } },
+    transport: r.transport,
+  };
+  if (Object.keys(r.requiresEnv).length) entry.requiresEnv = r.requiresEnv;
+  if (Object.keys(r.requiresInput).length) entry.requiresInput = r.requiresInput;
+  if (r.stale) Object.assign(entry, { stale: true, staleReason: r.staleReason });
+  const problems = validateRegistryPayload('servers', [entry]);
+  if (problems.length) throw new Error(`${name}: ${problems.join('; ')}`);
+  return { ...entry, configs: deriveConfigs(entry) };
+}
+
+// Resolve the requested servers to catalogue ids plus the server list to use.
+// Catalogue ids pass through. A registry name maps to the catalogue entry that
+// links to it, or is looked up live and appended as a synthetic entry. Anything
+// else is unknown.
+async function resolveServerList(requested) {
+  const servers = [...MCP_SERVERS];
+  const ids = [];
+  const unknown = [];
+  const live = {};
+  for (const raw of requested) {
+    if (KNOWN_MCP_IDS.includes(raw)) { ids.push(raw); continue; }
+    if (!isValidRegistryName(raw)) { unknown.push(raw); continue; }
+    const linked = MCP_SERVERS.find((s) => s.registry?.name === raw);
+    if (linked) { ids.push(linked.id); continue; }
+    const slug = slugForRegistryName(raw);
+    if (KNOWN_MCP_IDS.includes(slug)) {
+      throw new Error(`${raw} would use the id "${slug}", which already names a different catalogue server. Use the catalogue id instead.`);
+    }
+    if (live[slug]) { ids.push(slug); continue; }
+    const record = await fetchRegistryServer(raw);
+    if (!record) throw new Error(`Not found in the MCP Registry: ${raw}`);
+    const entry = entryFromRegistry(raw, record);
+    servers.push(entry);
+    live[slug] = { registry: raw, requiresEnv: Object.keys(entry.requiresEnv || {}) };
+    ids.push(slug);
+  }
+  if (unknown.length) {
+    throw new Error(`Unknown MCP server(s): ${unknown.join(', ')}. Known: ${KNOWN_MCP_IDS.join(', ')} (or an MCP Registry name like io.github.owner/server)`);
+  }
+  if (ids.length === 0) throw new Error('No MCP server(s) given.');
+  return { ids: [...new Set(ids)], servers, live };
+}
+
+// Which agents to target: --agents wins (validated); otherwise detected+installed.
+// For --project, keep only agents that support a project-level MCP path.
+function resolveTargetAgents(runtime, home, { project = false } = {}) {
+  let agents;
+  if (runtime.agents && runtime.agents.length) {
+    const known = AGENT_DEFINITIONS.map((a) => a.id);
+    const valid = requireKnown(runtime.agents, known, 'agent(s)');
+    agents = AGENT_DEFINITIONS.filter((a) => valid.includes(a.id));
+  } else {
+    agents = detectAgents(home).filter((a) => a.installed);
+  }
+  if (project) agents = agents.filter((a) => typeof a.projectMcpPath === 'function');
+  return agents;
+}
+
+// ── dxai add <id...> ──
+export async function addMcp(serverIds = [], opts = {}) {
+  const runtime = normalizeOptions(opts);
+  const project = !!opts.project;
+  const home = os.homedir();
+
+  const { ids, servers, live } = await resolveServerList(serverIds);
+  const agents = resolveTargetAgents(runtime, home, { project });
+  if (agents.length === 0) {
+    throw new Error(project
+      ? `No project-capable agents. Pass --agents with one of: ${AGENT_DEFINITIONS.filter((a) => a.projectMcpPath).map((a) => a.id).join(', ')}.`
+      : 'No target agents detected. Pass --agents <ids> or install a supported agent.');
+  }
+
+  const inputs = await collectMcpInputs(ids, servers, runtime);
+
+  if (!runtime.json) {
+    printBanner();
+    sectionHeader(`Add — ${ids.join(', ')} → ${project ? 'project' : 'system'}`);
+  }
+
+  if (runtime.dryRun && !project) {
+    const previews = previewMcpConfigs(agents, ids, servers, inputs);
+    if (runtime.json) {
+      process.stdout.write(JSON.stringify({ ok: true, dryRun: true, previews }, null, 2) + '\n');
+      return;
+    }
+    for (const p of Object.values(previews)) {
+      const tag = p.exists ? theme.dim('(merge)') : theme.dim('(create)');
+      console.log(`  ${theme.label(p.agent)} ${tag} → ${p.path}`);
+      if (p.wouldAdd.length) console.log(`    ${theme.success('+ would add:')} ${p.wouldAdd.join(', ')}`);
+      if (p.wouldSkip.length) console.log(`    ${theme.dim('· already present:')} ${p.wouldSkip.join(', ')}`);
+    }
+    console.log();
+    warnMsg('Dry run — no files were changed.');
+    return;
+  }
+
+  if (runtime.dryRun && project) {
+    if (runtime.json) {
+      process.stdout.write(JSON.stringify({ ok: true, dryRun: true, project: true, wouldAdd: ids, agents: agents.map((a) => a.id) }, null, 2) + '\n');
+      return;
+    }
+    for (const a of agents) infoMsg(`Would add ${ids.join(', ')} to ${a.name} project config (${a.projectMcpPath()})`);
+    console.log();
+    warnMsg('Dry run — no files were changed.');
+    return;
+  }
+
+  const results = project
+    ? writeProjectMcpConfigs(agents, ids, servers, inputs)
+    : writeMcpConfigs(agents, ids, servers, inputs);
+  if (project) recordProjectMcp(results, undefined, live); else recordSystemMcp(results, live);
+
+  // Per-agent write failures land in results[*].errors — exit non-zero so
+  // scripted callers can detect a partial failure.
+  const errorCount = Object.values(results).reduce((n, r) => n + (r.errors || []).length, 0);
+  if (errorCount > 0) process.exitCode = 1;
+
+  if (runtime.json) {
+    process.stdout.write(JSON.stringify({ ok: errorCount === 0, added: ids, project, results }, null, 2) + '\n');
+    return;
+  }
+  reportMcpResults(results);
+  console.log();
+}
+
+// Scan one agent for which of `ids` are actually present in its config.
+function scanPresent(agent, ids, home, project) {
+  if (project) {
+    const p = path.join(process.cwd(), agent.projectMcpPath());
+    const format = agent.projectConfigFormat || agent.configFormat;
+    return format === 'toml'
+      ? { path: p, present: scanTomlMcpConfig(p, ids) }
+      : { path: p, present: scanJsonMcpConfig(p, agent.projectMcpKey || agent.mcpKey, ids) };
+  }
+  switch (agent.configFormat) {
+    case 'json': {
+      const p = agent.globalMcpPath(home);
+      return { path: p, present: scanJsonMcpConfig(p, agent.mcpKey, ids) };
+    }
+    case 'toml': {
+      const p = agent.globalMcpPath(home);
+      return { path: p, present: scanTomlMcpConfig(p, ids) };
+    }
+    case 'cli':
+      return { path: null, present: scanClaudeCodeMcpServers(ids) };
+    default:
+      return { path: null, present: [] };
+  }
+}
+
+// Remove `ids` from one agent's config; returns the count removed.
+function removeFrom(agent, ids, configPath) {
+  switch (agent.configFormat) {
+    case 'json':
+      return removeJsonMcpServers(configPath, agent.mcpKey, ids).removed;
+    case 'toml':
+      return removeTomlMcpServers(configPath, ids).removed;
+    case 'cli':
+      return removeClaudeCodeMcpServers(ids).removed;
+    default:
+      return 0;
+  }
+}
+
+// ── dxai remove <id...> ──
+export async function removeMcp(serverIds = [], opts = {}) {
+  const runtime = normalizeOptions(opts);
+  const project = !!opts.project;
+  const home = os.homedir();
+
+  // Removal is by catalogue id or the slug a registry name was added under;
+  // no live lookup is needed to take something out of a config.
+  const ids = serverIds.map((raw) => (isValidRegistryName(raw) ? slugForRegistryName(raw) : raw));
+  if (ids.length === 0) throw new Error('No MCP server(s) given.');
+  const agents = resolveTargetAgents(runtime, home, { project });
+  if (agents.length === 0) {
+    throw new Error('No target agents detected. Pass --agents <ids> or install a supported agent.');
+  }
+
+  if (!runtime.json) {
+    printBanner();
+    sectionHeader(`Remove — ${ids.join(', ')} from ${project ? 'project' : 'system'}`);
+  }
+
+  const removed = [];
+  for (const agent of agents) {
+    const { path: configPath, present } = scanPresent(agent, ids, home, project);
+    if (present.length === 0) continue;
+
+    if (runtime.dryRun) {
+      removed.push({ agent: agent.name, agentId: agent.id, path: configPath, removed: present });
+      continue;
+    }
+
+    let count;
+    try {
+      count = removeFrom(agent, present, configPath);
+    } catch (err) {
+      if (!runtime.json) warnMsg(`${agent.name}: ${err.message}`);
+      continue;
+    }
+    if (count > 0) {
+      if (project) unrecordProjectMcp(agent.id, present);
+      else unrecordSystemMcp(agent.id, present);
+      removed.push({ agent: agent.name, agentId: agent.id, path: configPath, removed: present });
+    }
+  }
+
+  if (runtime.json) {
+    process.stdout.write(JSON.stringify({ ok: true, dryRun: runtime.dryRun, project, removed }, null, 2) + '\n');
+    return;
+  }
+
+  if (removed.length === 0) {
+    infoMsg(`None of [${ids.join(', ')}] were present in the targeted ${project ? 'project' : 'system'} configs.`);
+    console.log();
+    return;
+  }
+  for (const r of removed) {
+    const verb = runtime.dryRun ? 'would remove' : 'removed';
+    successMsg(`${r.agent}: ${verb} ${r.removed.join(', ')}` + (r.path ? ` → ${r.path}` : ''));
+  }
+  console.log();
+  if (runtime.dryRun) warnMsg('Dry run — no files were changed.');
+}

package/src/net.js

@@ -0,0 +1,72 @@
+// Shared network helpers: fetch with a per-attempt timeout, bounded retries, and
+// exponential backoff. The registry refresh and skill downloads both route through
+// here so timeout/retry behaviour lives in exactly one place instead of being
+// re-implemented (or forgotten) at each call site.
+
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_RETRIES = 2; // total attempts = retries + 1
+const DEFAULT_BACKOFF_MS = 300; // base delay, doubled each retry
+
+// Injectable so tests can advance "time" without real waits.
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Worth retrying? Transient failures (timeouts, dropped connections, 5xx, 429)
+// are; a definitive 4xx (bad URL, 404, 403) is permanent, so retrying just
+// wastes the caller's time and hammers the server.
+export function isRetriable(err) {
+  if (!err) return false;
+  if (err.name === 'AbortError' || err.name === 'TimeoutError') return true;
+  if (typeof err.status === 'number') {
+    if (err.status === 429) return true;
+    if (err.status >= 500) return true;
+    if (err.status >= 400) return false; // other 4xx — don't retry
+  }
+  // fetch() rejected at the network layer (DNS, connection refused, TLS): retry.
+  return true;
+}
+
+// Fetch with a fresh AbortSignal.timeout per attempt and exponential backoff
+// between retries. Returns the Response on the first 2xx; throws the last error
+// once retries are exhausted (or immediately for a non-retriable status).
+export async function fetchWithRetry(url, opts = {}) {
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retries = DEFAULT_RETRIES,
+    backoffMs = DEFAULT_BACKOFF_MS,
+    redirect = 'follow',
+    sleepFn = sleep,
+  } = opts;
+
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, { redirect, signal: AbortSignal.timeout(timeoutMs) });
+      if (!res.ok) {
+        const err = new Error(`HTTP ${res.status} for ${url}`);
+        err.status = res.status;
+        throw err;
+      }
+      return res;
+    } catch (err) {
+      lastErr = err;
+      if (attempt < retries && isRetriable(err)) {
+        await sleepFn(backoffMs * 2 ** attempt);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastErr;
+}
+
+export async function fetchJson(url, opts) {
+  const res = await fetchWithRetry(url, opts);
+  return res.json();
+}
+
+export async function fetchText(url, opts) {
+  const res = await fetchWithRetry(url, opts);
+  return res.text();
+}

package/src/profile.js

@@ -0,0 +1,139 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { writeJsonAtomic } from './fs-atomic.js';
+
+const HOME = os.homedir();
+
+// Keys allowed to live in a profile. Anything else is dropped silently
+// (forward-compatibility for new keys without erroring on old ones).
+export const PROFILE_KEYS = [
+  'mode',       // 'system' | 'project' | 'both'
+  'agents',     // string[]
+  'mcp',        // string[]
+  'skills',     // string[]
+  'features',   // string[]
+  'stack',      // string[]
+  'mcpInputs',  // { [serverId]: { [inputKey]: value } }
+];
+
+// Default project-level profile location.
+const PROJECT_PROFILE_PATH = path.join('.dxai', 'profile.json');
+
+// Default user-level profile dir.
+const USER_PROFILE_DIR = path.join(HOME, '.dxai', 'profiles');
+
+// Auto-discovery: first existing wins.
+function findDefaultProfile(cwd = process.cwd()) {
+  const candidates = [
+    path.join(cwd, '.dxai', 'profile.json'),
+    path.join(HOME, '.dxai', 'config.json'),
+    path.join(HOME, '.dxairc'),
+    path.join(HOME, '.dxairc.json'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+// Resolve `nameOrPath` to a real file path:
+//   - if it ends with .json or contains a path separator, treat as path
+//   - otherwise look up by name in user/project dirs
+export function resolveProfile(nameOrPath, cwd = process.cwd()) {
+  if (!nameOrPath) return findDefaultProfile(cwd);
+
+  // Treat as a path if it carries any separator. Check both `/` and `\` so a
+  // forward-slash path (e.g. `./team/dev`) is still recognized on Windows, where
+  // path.sep is `\`.
+  if (nameOrPath.includes('/') || nameOrPath.includes('\\') || nameOrPath.endsWith('.json')) {
+    const abs = path.isAbsolute(nameOrPath) ? nameOrPath : path.join(cwd, nameOrPath);
+    return fs.existsSync(abs) ? abs : null;
+  }
+
+  const candidates = [
+    path.join(cwd, '.dxai', `${nameOrPath}.json`),
+    path.join(USER_PROFILE_DIR, `${nameOrPath}.json`),
+    path.join(HOME, '.dxai', `${nameOrPath}.json`),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function readProfile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Profile not found: ${filePath}`);
+  }
+  let data;
+  try {
+    data = fs.readJsonSync(filePath);
+  } catch (err) {
+    throw new Error(`Failed to parse profile ${filePath}: ${err.message}`, { cause: err });
+  }
+  const out = {};
+  for (const k of PROFILE_KEYS) {
+    if (data[k] !== undefined) out[k] = data[k];
+  }
+  return out;
+}
+
+// CLI flags take precedence over profile values.
+// Only fills keys that are undefined on `cliOpts`.
+export function mergeWithProfile(cliOpts, profile) {
+  if (!profile) return cliOpts;
+  const merged = { ...cliOpts };
+  for (const key of PROFILE_KEYS) {
+    if (merged[key] === undefined && profile[key] !== undefined) {
+      merged[key] = profile[key];
+    }
+  }
+  return merged;
+}
+
+// Save a profile. `target` is one of:
+//   { user: true, name }   → ~/.dxai/profiles/<name>.json
+//   { here: true }         → ./.dxai/profile.json
+//   { path: '...' }        → exact path
+export function saveProfile(data, target = { user: true, name: 'default' }) {
+  const filtered = {};
+  for (const k of PROFILE_KEYS) {
+    if (data[k] !== undefined) filtered[k] = data[k];
+  }
+
+  let outPath;
+  if (target.path) {
+    outPath = target.path;
+  } else if (target.here) {
+    outPath = path.join(process.cwd(), PROJECT_PROFILE_PATH);
+  } else {
+    if (!target.name) throw new Error('saveProfile: target.name is required for user profiles');
+    outPath = path.join(USER_PROFILE_DIR, `${target.name}.json`);
+  }
+
+  writeJsonAtomic(outPath, filtered, { spaces: 2 });
+  return outPath;
+}
+
+// List discoverable profiles (user dir + cwd .dxai dir).
+export function listProfiles(cwd = process.cwd()) {
+  const found = [];
+
+  for (const dir of [USER_PROFILE_DIR, path.join(cwd, '.dxai')]) {
+    if (!fs.existsSync(dir)) continue;
+    try {
+      const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+      for (const f of files) {
+        found.push({
+          name: path.basename(f, '.json'),
+          path: path.join(dir, f),
+          scope: dir === USER_PROFILE_DIR ? 'user' : 'project',
+        });
+      }
+    } catch {
+      // skip
+    }
+  }
+  return found;
+}

package/src/registry/automation-tools.js

@@ -0,0 +1,6 @@
+import { loadRegistry } from './loader.js';
+
+const data = loadRegistry('automation-tools');
+
+export const AUTOMATION_TOOL_CATEGORIES = data.categories;
+export const AUTOMATION_TOOLS = data.tools;

package/src/registry/data/automation-tools.json

@@ -0,0 +1,37 @@
+{
+  "categories": [
+    {
+      "id": "automation",
+      "label": "🤖 Automation",
+      "description": "CLI tools that give AI agents browser & device control"
+    }
+  ],
+  "tools": [
+    {
+      "id": "agent-browser",
+      "name": "Agent Browser",
+      "description": "Browser automation CLI for AI agents",
+      "category": "automation",
+      "recommended": true,
+      "detectCommand": "agent-browser",
+      "installCommand": {
+        "macOS": "npm install -g agent-browser",
+        "Linux": "npm install -g agent-browser",
+        "Windows": "npm install -g agent-browser"
+      }
+    },
+    {
+      "id": "agent-device",
+      "name": "Agent Device",
+      "description": "iOS/Android device automation CLI for AI agents",
+      "category": "automation",
+      "recommended": true,
+      "detectCommand": "agent-device",
+      "installCommand": {
+        "macOS": "npm install -g agent-device",
+        "Linux": "npm install -g agent-device",
+        "Windows": "npm install -g agent-device"
+      }
+    }
+  ]
+}