dxai-cli 1.0.0

package/src/inspect.js

@@ -0,0 +1,283 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import {
+  printBanner, sectionHeader, successMsg, warnMsg, errorMsg, infoMsg, theme,
+} from './branding.js';
+import { detectOS, AGENT_DEFINITIONS, commandExists } from './detect.js';
+import { MCP_SERVERS } from './registry/mcp-servers.js';
+import {
+  readManifest, SYSTEM_MANIFEST_PATH, PROJECT_MANIFEST_PATH,
+} from './manifest.js';
+import {
+  scanJsonMcpConfig, scanTomlMcpConfig, scanClaudeCodeMcpServers,
+} from './config-remover.js';
+import { handshakeServer, resolveSpawnSpec } from './handshake.js';
+
+const KNOWN_MCP_IDS = MCP_SERVERS.map((s) => s.id);
+
+function loadBoth(cwd = process.cwd()) {
+  const system = readManifest(SYSTEM_MANIFEST_PATH);
+  const project = readManifest(path.join(cwd, PROJECT_MANIFEST_PATH));
+  return { system, project };
+}
+
+// ── list ──
+export async function listCmd(opts = {}) {
+  const { system, project } = loadBoth();
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ ok: true, system, project }, null, 2) + '\n');
+    return;
+  }
+
+  printBanner();
+
+  sectionHeader('System (~/.dxai/manifest.json)');
+  if (system.agents.length === 0 && Object.keys(system.mcp).length === 0 && Object.keys(system.skills).length === 0) {
+    infoMsg('No system-level dxai installs recorded.');
+  } else {
+    if (system.agents.length > 0) successMsg(`Agents: ${system.agents.join(', ')}`);
+    for (const [agentId, servers] of Object.entries(system.mcp)) {
+      const list = Object.keys(servers).join(', ');
+      console.log(`  ${theme.label(agentId.padEnd(14))} ${theme.dim('MCP:')} ${list}`);
+    }
+    if (Object.keys(system.skills).length > 0) {
+      console.log(`  ${theme.label('skills'.padEnd(14))} ${theme.dim('→')} ${Object.keys(system.skills).join(', ')}`);
+    }
+  }
+
+  console.log();
+  sectionHeader('Project (./.dxai/manifest.json)');
+  if (project.agents.length === 0 && Object.keys(project.mcp).length === 0 && project.files.length === 0) {
+    infoMsg('No project-level dxai installs recorded in cwd.');
+  } else {
+    if (project.agents.length > 0) successMsg(`Agents: ${project.agents.join(', ')}`);
+    for (const [agentId, servers] of Object.entries(project.mcp)) {
+      const list = Object.keys(servers).join(', ');
+      console.log(`  ${theme.label(agentId.padEnd(14))} ${theme.dim('MCP:')} ${list}`);
+    }
+    if (project.files.length > 0) {
+      console.log(`  ${theme.label('files'.padEnd(14))} ${theme.dim('→')} ${project.files.map((f) => f.relativePath).join(', ')}`);
+    }
+  }
+  console.log();
+}
+
+// ── status ──
+// Diff manifest vs actual config files. Reports drift.
+// `ids` is the catalogue plus whatever the manifest recorded — servers added
+// live by registry name are not in the catalogue but must still be scanned.
+function readActualMcp(agent, home, cwd, ids = KNOWN_MCP_IDS) {
+  const out = { global: [], project: [] };
+
+  if (agent.configFormat === 'json' && typeof agent.globalMcpPath === 'function') {
+    const legacy = typeof agent.legacyGlobalMcpPaths === 'function' ? agent.legacyGlobalMcpPaths(home) : [];
+    out.global = [...new Set([agent.globalMcpPath(home), ...legacy].flatMap((p) => scanJsonMcpConfig(p, agent.mcpKey, ids)))];
+  } else if (agent.configFormat === 'toml' && typeof agent.globalMcpPath === 'function') {
+    out.global = scanTomlMcpConfig(agent.globalMcpPath(home), ids);
+  } else if (agent.configFormat === 'cli') {
+    out.global = scanClaudeCodeMcpServers(ids);
+  }
+
+  if (typeof agent.projectMcpPath === 'function') {
+    const projPath = path.join(cwd, agent.projectMcpPath());
+    if (fs.existsSync(projPath)) {
+      out.project = (agent.projectConfigFormat || agent.configFormat) === 'toml'
+        ? scanTomlMcpConfig(projPath, ids)
+        : scanJsonMcpConfig(projPath, agent.projectMcpKey || agent.mcpKey, ids);
+    }
+  }
+
+  return out;
+}
+
+export async function statusCmd(opts = {}) {
+  const { home } = detectOS();
+  const cwd = process.cwd();
+  const { system, project } = loadBoth(cwd);
+
+  const drift = { system: {}, project: {} };
+
+  for (const agent of AGENT_DEFINITIONS) {
+    const recordedSystem = Object.keys(system.mcp[agent.id] || {});
+    const recordedProject = Object.keys(project.mcp[agent.id] || {});
+    if (recordedSystem.length === 0 && recordedProject.length === 0) continue;
+
+    const actual = readActualMcp(agent, home, cwd, [...new Set([...KNOWN_MCP_IDS, ...recordedSystem, ...recordedProject])]);
+
+    // Missing: in manifest but not in config (someone removed it).
+    // Extra: in config but not in manifest (added outside dxai or by another tool).
+    const sysMissing = recordedSystem.filter((id) => !actual.global.includes(id));
+    const sysExtra = actual.global.filter((id) => !recordedSystem.includes(id));
+    const projMissing = recordedProject.filter((id) => !actual.project.includes(id));
+    const projExtra = actual.project.filter((id) => !recordedProject.includes(id));
+
+    if (sysMissing.length || sysExtra.length) {
+      drift.system[agent.id] = { missing: sysMissing, extra: sysExtra };
+    }
+    if (projMissing.length || projExtra.length) {
+      drift.project[agent.id] = { missing: projMissing, extra: projExtra };
+    }
+  }
+
+  // Project files: did manifest-recorded files actually survive?
+  const fileDrift = [];
+  for (const f of project.files || []) {
+    const abs = path.join(cwd, f.relativePath);
+    if (!fs.existsSync(abs)) fileDrift.push(f.relativePath);
+  }
+
+  const clean =
+    Object.keys(drift.system).length === 0 &&
+    Object.keys(drift.project).length === 0 &&
+    fileDrift.length === 0;
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ ok: true, clean, drift, fileDrift }, null, 2) + '\n');
+    return;
+  }
+
+  printBanner();
+  sectionHeader('Status — Manifest vs Actual Config');
+
+  if (clean) {
+    console.log();
+    successMsg('In sync. Manifest and live config agree.');
+    console.log();
+    return;
+  }
+
+  for (const [agentId, d] of Object.entries(drift.system)) {
+    console.log();
+    console.log(theme.label(`  System / ${agentId}`));
+    if (d.missing.length) warnMsg(`Missing in config (manifest expected): ${d.missing.join(', ')}`);
+    if (d.extra.length) infoMsg(`Extra in config (not added by dxai): ${d.extra.join(', ')}`);
+  }
+  for (const [agentId, d] of Object.entries(drift.project)) {
+    console.log();
+    console.log(theme.label(`  Project / ${agentId}`));
+    if (d.missing.length) warnMsg(`Missing in config (manifest expected): ${d.missing.join(', ')}`);
+    if (d.extra.length) infoMsg(`Extra in config (not added by dxai): ${d.extra.join(', ')}`);
+  }
+  if (fileDrift.length > 0) {
+    console.log();
+    console.log(theme.label('  Project files'));
+    warnMsg(`Removed since install: ${fileDrift.join(', ')}`);
+  }
+  console.log();
+}
+
+// ── doctor ──
+// Validate that configs parse, env vars are set, and (best-effort) MCP commands exist.
+export async function doctorCmd(opts = {}) {
+  const { home } = detectOS();
+  const cwd = process.cwd();
+  const { system, project } = loadBoth(cwd);
+
+  const findings = [];
+  const ok = (msg) => findings.push({ severity: 'ok', msg });
+  const warn = (msg) => findings.push({ severity: 'warn', msg });
+  const fail = (msg) => findings.push({ severity: 'error', msg });
+  const info = (msg) => findings.push({ severity: 'info', msg });
+
+  // Config files parse.
+  for (const agent of AGENT_DEFINITIONS) {
+    if (typeof agent.globalMcpPath !== 'function') continue;
+    if (agent.configFormat === 'cli') continue; // no file to parse
+    const p = agent.globalMcpPath(home);
+    if (!fs.existsSync(p)) continue;
+
+    if (agent.configFormat === 'json') {
+      try {
+        fs.readJsonSync(p);
+        ok(`${agent.name}: config parses (${p})`);
+      } catch (err) {
+        fail(`${agent.name}: config malformed at ${p} — ${err.message}`);
+      }
+    } else if (agent.configFormat === 'toml') {
+      try {
+        fs.readFileSync(p, 'utf-8'); // shallow check; deeper TOML parse optional
+        ok(`${agent.name}: config readable (${p})`);
+      } catch (err) {
+        fail(`${agent.name}: config unreadable at ${p} — ${err.message}`);
+      }
+    }
+  }
+
+  // Env vars for installed servers. Catalogue entries carry requiresEnv; servers
+  // added live by registry name carry the env var names in their manifest record.
+  const installed = new Map();
+  for (const servers of [...Object.values(system.mcp), ...Object.values(project.mcp)]) {
+    for (const [id, rec] of Object.entries(servers)) if (!installed.has(id)) installed.set(id, rec);
+  }
+
+  for (const [id, rec] of installed) {
+    const meta = MCP_SERVERS.find((s) => s.id === id);
+    const label = meta?.name || rec.registry || id;
+    const envEntries = meta?.requiresEnv
+      ? Object.entries(meta.requiresEnv)
+      : (rec.requiresEnv || []).map((v) => [v, `required by ${label}`]);
+    for (const [envVar, desc] of envEntries) {
+      if (process.env[envVar]) ok(`env: ${envVar} set (${label})`);
+      else warn(`env: ${envVar} not set — needed by ${label} (${desc})`);
+    }
+  }
+
+  // Most MCP servers spawn via npx.
+  if (commandExists('npx')) ok('npx is on PATH');
+  else fail('npx not found on PATH — most MCP servers spawn via `npx`.');
+
+  // Project files referenced in manifest still exist.
+  for (const f of project.files || []) {
+    const abs = path.join(cwd, f.relativePath);
+    if (fs.existsSync(abs)) ok(`project file present: ${f.relativePath}`);
+    else warn(`project file missing: ${f.relativePath} (recorded in manifest)`);
+  }
+
+  // Handshake (opt-in) — spawn each installed MCP server and verify JSON-RPC.
+  if (opts.handshake) {
+    for (const id of installed.keys()) {
+      const meta = MCP_SERVERS.find((s) => s.id === id);
+      if (!meta) { info(`handshake: ${id} is not in the catalogue — skipped`); continue; }
+      const spec = resolveSpawnSpec(meta);
+      if (!spec) {
+        info(`handshake: ${meta.name} is a remote/URL server — skipped`);
+        continue;
+      }
+      if (meta.requiresEnv && Object.keys(meta.requiresEnv).some((v) => !process.env[v])) {
+        warn(`handshake: ${meta.name} skipped — required env not set`);
+        continue;
+      }
+      const res = await handshakeServer(spec, { timeoutMs: 10000 });
+      if (res.ok) ok(`handshake: ${meta.name} responded to initialize`);
+      else fail(`handshake: ${meta.name} failed — ${res.error}`);
+    }
+  }
+
+  const summary = {
+    ok: findings.filter((f) => f.severity === 'ok').length,
+    warn: findings.filter((f) => f.severity === 'warn').length,
+    error: findings.filter((f) => f.severity === 'error').length,
+  };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ ok: summary.error === 0, summary, findings }, null, 2) + '\n');
+    if (summary.error > 0) process.exit(1);
+    return;
+  }
+
+  printBanner();
+  sectionHeader('Doctor — Health Check');
+  console.log();
+  for (const f of findings) {
+    if (f.severity === 'ok') successMsg(f.msg);
+    else if (f.severity === 'warn') warnMsg(f.msg);
+    else if (f.severity === 'info') infoMsg(f.msg);
+    else errorMsg(f.msg);
+  }
+  console.log();
+  infoMsg(`${summary.ok} ok · ${summary.warn} warn · ${summary.error} error`);
+  console.log();
+  if (summary.error > 0) process.exit(1);
+}

package/src/manifest.js

@@ -0,0 +1,179 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { warnMsg } from './branding.js';
+import { writeJsonAtomic } from './fs-atomic.js';
+import { AGENT_ID_ALIASES } from './detect.js';
+
+const HOME = os.homedir();
+
+export const SYSTEM_MANIFEST_PATH = path.join(HOME, '.dxai', 'manifest.json');
+export const PROJECT_MANIFEST_PATH = path.join('.dxai', 'manifest.json');
+export const MANIFEST_VERSION = 1;
+
+export function emptyManifest() {
+  return {
+    version: MANIFEST_VERSION,
+    createdAt: null,
+    updatedAt: null,
+    agents: [],
+    mcp: {},     // { [agentId]: { [serverId]: { addedAt, configPath } } }
+    skills: {},  // { [skillId]: { addedAt, path } }
+    tools: {},   // { [toolId]: { addedAt } }
+    files: [],   // [{ relativePath, addedAt }]
+  };
+}
+
+export function readManifest(filePath) {
+  if (!fs.existsSync(filePath)) return emptyManifest();
+  try {
+    const data = fs.readJsonSync(filePath);
+    // Future migrations would go here, gated on data.version.
+    return migrateAgentIds({ ...emptyManifest(), ...data });
+  } catch (err) {
+    // A corrupt manifest must not silently read as "nothing installed" — that
+    // would hide real installs from `list`/`status` and let a subsequent write
+    // clobber recoverable data. Preserve the bad file and warn loudly.
+    try {
+      const salvage = `${filePath}.corrupt`;
+      if (!fs.existsSync(salvage)) fs.copySync(filePath, salvage);
+      warnMsg(`Manifest at ${filePath} is unreadable (${err.message}); preserved a copy at ${path.basename(salvage)}.`);
+    } catch { /* best-effort salvage */ }
+    return emptyManifest();
+  }
+}
+
+// Fold entries recorded under a former agent id (e.g. `windsurf`) into the
+// current id so list/status/cleanup keep seeing them after a rename. The next
+// write persists the migrated shape.
+function migrateAgentIds(manifest) {
+  for (const [alias, target] of Object.entries(AGENT_ID_ALIASES)) {
+    if (manifest.mcp && manifest.mcp[alias]) {
+      manifest.mcp[target] = { ...(manifest.mcp[alias]), ...(manifest.mcp[target] || {}) };
+      delete manifest.mcp[alias];
+    }
+    if (Array.isArray(manifest.agents) && manifest.agents.includes(alias)) {
+      manifest.agents = [...new Set(manifest.agents.map((id) => (id === alias ? target : id)))];
+    }
+  }
+  return manifest;
+}
+
+export function writeManifest(filePath, manifest) {
+  const now = new Date().toISOString();
+  const out = {
+    ...manifest,
+    version: MANIFEST_VERSION,
+    createdAt: manifest.createdAt || now,
+    updatedAt: now,
+  };
+  writeJsonAtomic(filePath, out, { spaces: 2 });
+  return out;
+}
+
+// Convenience: load → mutate → save.
+function updateManifest(filePath, mutator) {
+  const m = readManifest(filePath);
+  mutator(m);
+  return writeManifest(filePath, m);
+}
+
+// Record MCP installs from a writeMcpConfigs / writeProjectMcpConfigs result map.
+// `mcpResults` is { [agentId]: { agent, added, skipped, errors, path, addedIds } }.
+// Only the IDs each agent actually merged (r.addedIds) are recorded, so the
+// manifest never claims servers that were skipped because they were already present.
+// `meta` ({ [serverId]: { registry, requiresEnv } }) carries provenance for servers
+// that are not in the bundled catalogue (added live by registry name), so
+// `doctor`/`status` can still reason about them later.
+function recordMcp(filePath, mcpResults, meta = {}) {
+  if (!mcpResults) return;
+  updateManifest(filePath, (m) => {
+    const now = new Date().toISOString();
+    for (const [agentId, r] of Object.entries(mcpResults)) {
+      const ids = r.addedIds || [];
+      if (ids.length === 0) continue;
+      if (!m.mcp[agentId]) m.mcp[agentId] = {};
+      for (const serverId of ids) {
+        m.mcp[agentId][serverId] = { addedAt: now, configPath: r.path || null, ...(meta[serverId] || {}) };
+      }
+      if (!m.agents.includes(agentId)) m.agents.push(agentId);
+    }
+  });
+}
+
+// `skillResults.installed` holds skill IDs (which are also the on-disk
+// directory names), so manifest keys line up with what cleanup scans for.
+function recordSkills(filePath, skillResults) {
+  if (!skillResults || skillResults.installed.length === 0) return;
+  updateManifest(filePath, (m) => {
+    const now = new Date().toISOString();
+    for (const skillId of skillResults.installed) {
+      m.skills[skillId] = { addedAt: now, path: skillResults.directory };
+    }
+  });
+}
+
+export function recordSystemMcp(mcpResults, meta) {
+  recordMcp(SYSTEM_MANIFEST_PATH, mcpResults, meta);
+}
+
+export function recordProjectMcp(mcpResults, cwd = process.cwd(), meta) {
+  recordMcp(path.join(cwd, PROJECT_MANIFEST_PATH), mcpResults, meta);
+}
+
+export function recordSystemSkills(skillResults) {
+  recordSkills(SYSTEM_MANIFEST_PATH, skillResults);
+}
+
+export function recordProjectSkills(skillResults, cwd = process.cwd()) {
+  recordSkills(path.join(cwd, PROJECT_MANIFEST_PATH), skillResults);
+}
+
+export function recordSystemTools(toolResults) {
+  if (!toolResults || toolResults.installed.length === 0) return;
+  updateManifest(SYSTEM_MANIFEST_PATH, (m) => {
+    if (!m.tools) m.tools = {};
+    const now = new Date().toISOString();
+    for (const toolId of toolResults.installed) {
+      m.tools[toolId] = { addedAt: now };
+    }
+  });
+}
+
+// Remove specific MCP server IDs for one agent from a manifest file, cleaning up
+// an emptied agent bucket. No-op (and never creates the file) when the manifest
+// doesn't exist. Returns the count actually removed.
+export function unrecordMcp(filePath, agentId, ids) {
+  if (!fs.existsSync(filePath)) return 0;
+  let removed = 0;
+  updateManifest(filePath, (m) => {
+    if (!m.mcp[agentId]) return;
+    for (const id of ids) {
+      if (m.mcp[agentId][id]) { delete m.mcp[agentId][id]; removed++; }
+    }
+    if (Object.keys(m.mcp[agentId]).length === 0) delete m.mcp[agentId];
+  });
+  return removed;
+}
+
+export function unrecordSystemMcp(agentId, ids) {
+  return unrecordMcp(SYSTEM_MANIFEST_PATH, agentId, ids);
+}
+
+export function unrecordProjectMcp(agentId, ids, cwd = process.cwd()) {
+  return unrecordMcp(path.join(cwd, PROJECT_MANIFEST_PATH), agentId, ids);
+}
+
+export function recordProjectFiles(filePaths, cwd = process.cwd()) {
+  if (!filePaths || filePaths.length === 0) return;
+  const filePath = path.join(cwd, PROJECT_MANIFEST_PATH);
+  updateManifest(filePath, (m) => {
+    const now = new Date().toISOString();
+    const have = new Set(m.files.map((f) => f.relativePath));
+    for (const rel of filePaths) {
+      if (!have.has(rel)) {
+        m.files.push({ relativePath: rel, addedAt: now });
+      }
+    }
+  });
+}