@creativeintelligence/abbie 0.1.0

package/src/lib/doctor/index.ts

@@ -0,0 +1,647 @@
+/**
+ * Doctor - Environment validation for abbie CLI
+ *
+ * Checks:
+ * - ~/.abbie directories existence
+ * - Runtime detection (node/bun)
+ * - Agent binaries (claude, codex, copilot, gemini)
+ * - Optional tools (slack, messages, linear) - warn not fail
+ * - Template system (v2)
+ * - Per-repo contracts (v2)
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, accessSync, constants as fsConstants } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getDefaultSlackWorkspace, toSlackTokenEnvVar } from "../slack-workspace.js";
+import { checkRepos, type RepoCheckResult, summarizeRepoChecks } from "./repos.js";
+// v2 imports
+import { checkTemplates } from "./templates.js";
+import { getSyncDir, getAdapter, getLatestBackup } from "../config-sync/index.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type CheckStatus = "ok" | "missing" | "warn";
+
+export interface Check {
+  name: string;
+  status: CheckStatus;
+  detail: string;
+}
+
+export interface Fix {
+  if: string;
+  hint: string;
+}
+
+export interface DoctorResult {
+  ok: boolean;
+  checks: Check[];
+  fixes: Fix[];
+  // v2 additions
+  templateChecks?: Check[];
+  repoResults?: RepoCheckResult[];
+  summary?: {
+    environment: { ok: number; warn: number; missing: number };
+    templates?: { ok: number; warn: number; missing: number };
+    repos?: ReturnType<typeof summarizeRepoChecks>;
+  };
+  exitCode?: number;
+}
+
+// ============================================================================
+// Directory checks
+// ============================================================================
+
+const REQUIRED_DIRS = ["plans", "active-sessions", "prompts", "events", "resources"] as const;
+
+function getAgentsRoot(): string {
+  return join(homedir(), ".abbie");
+}
+
+export function checkDirectories(): Check[] {
+  const root = getAgentsRoot();
+  const checks: Check[] = [];
+
+  // Check root directory
+  if (existsSync(root)) {
+    checks.push({
+      name: "agents-root",
+      status: "ok",
+      detail: `~/.abbie exists`,
+    });
+  } else {
+    checks.push({
+      name: "agents-root",
+      status: "missing",
+      detail: `~/.abbie directory not found`,
+    });
+  }
+
+  // Check subdirectories
+  for (const dir of REQUIRED_DIRS) {
+    const path = join(root, dir);
+    if (existsSync(path)) {
+      checks.push({
+        name: `dir-${dir}`,
+        status: "ok",
+        detail: `~/.abbie/${dir} exists`,
+      });
+    } else {
+      checks.push({
+        name: `dir-${dir}`,
+        status: "missing",
+        detail: `~/.abbie/${dir} not found`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+export function fixDirectories(): string[] {
+  const root = getAgentsRoot();
+  const created: string[] = [];
+
+  // Create root if missing
+  if (!existsSync(root)) {
+    mkdirSync(root, { recursive: true });
+    created.push(root);
+  }
+
+  // Create subdirectories
+  for (const dir of REQUIRED_DIRS) {
+    const path = join(root, dir);
+    if (!existsSync(path)) {
+      mkdirSync(path, { recursive: true });
+      created.push(path);
+    }
+  }
+
+  return created;
+}
+
+// ============================================================================
+// Runtime detection
+// ============================================================================
+
+export function checkRuntime(): Check {
+  // Check if running under bun or node
+  const isBun = typeof process.versions.bun !== "undefined";
+  const runtime = isBun ? "bun" : "node";
+  const version = isBun ? process.versions.bun : process.versions.node;
+
+  return {
+    name: "runtime",
+    status: "ok",
+    detail: `${runtime} ${version}`,
+  };
+}
+
+// ============================================================================
+// Binary checks
+// ============================================================================
+
+function commandExists(cmd: string): { exists: boolean; version?: string } {
+  try {
+    // Try to get version - most CLIs support --version
+    const output = execSync(`${cmd} --version 2>/dev/null`, {
+      encoding: "utf-8",
+      timeout: 5000,
+    }).trim();
+    // Extract first line and limit length
+    const version = output.split("\n")[0]?.slice(0, 50) || "installed";
+    return { exists: true, version };
+  } catch {
+    // Try just running with no args to see if it exists
+    try {
+      execSync(`which ${cmd} 2>/dev/null`, {
+        encoding: "utf-8",
+        timeout: 2000,
+      });
+      return { exists: true, version: "installed" };
+    } catch {
+      return { exists: false };
+    }
+  }
+}
+
+// Core agents expected on every machine. Extended agents (pi, opencode, droid) are optional.
+const REQUIRED_BINARIES = ["claude", "codex", "copilot", "gemini"] as const;
+const _OPTIONAL_AGENT_BINARIES = ["pi", "opencode", "droid"] as const;
+const OPTIONAL_BINARIES = ["slack", "messages", "linear"] as const;
+
+export function checkBinaries(): Check[] {
+  const checks: Check[] = [];
+
+  // Required binaries - status: ok or missing
+  for (const bin of REQUIRED_BINARIES) {
+    const result = commandExists(bin);
+    if (result.exists) {
+      checks.push({
+        name: `bin-${bin}`,
+        status: "ok",
+        detail: result.version || "installed",
+      });
+    } else {
+      checks.push({
+        name: `bin-${bin}`,
+        status: "missing",
+        detail: `${bin} not found in PATH`,
+      });
+    }
+  }
+
+  // Optional binaries - status: ok or warn (not missing)
+  for (const bin of OPTIONAL_BINARIES) {
+    const result = commandExists(bin);
+    if (result.exists) {
+      checks.push({
+        name: `bin-${bin}`,
+        status: "ok",
+        detail: result.version || "installed",
+      });
+    } else {
+      checks.push({
+        name: `bin-${bin}`,
+        status: "warn",
+        detail: `${bin} not found (optional)`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+// ============================================================================
+// Environment variable checks
+// ============================================================================
+
+const DEFAULT_SLACK_WORKSPACE = getDefaultSlackWorkspace();
+
+const OPTIONAL_ENV_VARS: ReadonlyArray<{ name: string; description: string }> = [
+  { name: "LINEAR_API_KEY", description: "Linear integration" },
+  { name: "SLACK_BOT_TOKEN", description: "Slack integration" },
+  {
+    name: toSlackTokenEnvVar(DEFAULT_SLACK_WORKSPACE),
+    description: `Slack (${DEFAULT_SLACK_WORKSPACE} workspace)`,
+  },
+];
+
+export function checkEnvVars(): Check[] {
+  const checks: Check[] = [];
+
+  for (const { name, description } of OPTIONAL_ENV_VARS) {
+    const value = process.env[name];
+    if (value) {
+      checks.push({
+        name: `env-${name}`,
+        status: "ok",
+        detail: `${description} configured`,
+      });
+    } else {
+      checks.push({
+        name: `env-${name}`,
+        status: "warn",
+        detail: `${name} not set (${description})`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+// ============================================================================
+// Symlink checks for unified tooling
+// ============================================================================
+
+import { lstatSync, readlinkSync } from "node:fs";
+
+interface SymlinkSpec {
+  name: string;
+  path: string;
+  expectedTarget: string;
+  description: string;
+}
+
+const EXPECTED_SYMLINKS: SymlinkSpec[] = [
+  {
+    name: "claude-commands",
+    path: join(homedir(), ".claude", "commands"),
+    expectedTarget: join(homedir(), ".abbie", "prompts", "commands", "core"),
+    description: "Claude Code commands",
+  },
+  {
+    name: "codex-prompts",
+    path: join(homedir(), ".codex", "prompts"),
+    expectedTarget: join(homedir(), ".abbie", "prompts", "commands", "core"),
+    description: "Codex custom prompts",
+  },
+  {
+    name: "claude-rules",
+    path: join(homedir(), ".claude", "rules"),
+    expectedTarget: join(homedir(), ".abbie", "rules"),
+    description: "Claude Code rules",
+  },
+  {
+    name: "codex-rules",
+    path: join(homedir(), ".codex", "rules"),
+    expectedTarget: join(homedir(), ".abbie", "rules"),
+    description: "Codex rules",
+  },
+  {
+    name: "claude-skills",
+    path: join(homedir(), ".claude", "skills"),
+    expectedTarget: join(homedir(), ".abbie", "skills"),
+    description: "Claude Code skills",
+  },
+  {
+    name: "codex-skills",
+    path: join(homedir(), ".codex", "skills"),
+    expectedTarget: join(homedir(), ".abbie", "skills"),
+    description: "Codex skills",
+  },
+  {
+    name: "copilot-skills",
+    path: join(homedir(), ".copilot", "skills"),
+    expectedTarget: join(homedir(), ".abbie", "skills"),
+    description: "Copilot CLI skills",
+  },
+];
+
+export function checkSymlinks(): Check[] {
+  const checks: Check[] = [];
+
+  for (const spec of EXPECTED_SYMLINKS) {
+    try {
+      const stats = lstatSync(spec.path);
+      if (stats.isSymbolicLink()) {
+        const target = readlinkSync(spec.path);
+        if (target === spec.expectedTarget) {
+          checks.push({
+            name: `symlink-${spec.name}`,
+            status: "ok",
+            detail: `${spec.description} → ~/.abbie/...`,
+          });
+        } else {
+          checks.push({
+            name: `symlink-${spec.name}`,
+            status: "warn",
+            detail: `${spec.description} points to ${target} (expected ${spec.expectedTarget})`,
+          });
+        }
+      } else {
+        checks.push({
+          name: `symlink-${spec.name}`,
+          status: "warn",
+          detail: `${spec.description} exists but is not a symlink`,
+        });
+      }
+    } catch {
+      checks.push({
+        name: `symlink-${spec.name}`,
+        status: "missing",
+        detail: `${spec.description} not found`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+// ============================================================================
+// Fix suggestions
+// ============================================================================
+
+const SYMLINK_FIX_COMMANDS: Record<string, string> = {
+  "claude-commands": "ln -s ~/.abbie/prompts/commands/core ~/.claude/commands",
+  "codex-prompts": "ln -s ~/.abbie/prompts/commands/core ~/.codex/prompts",
+  "claude-rules": "ln -s ~/.abbie/rules ~/.claude/rules",
+  "codex-rules": "ln -s ~/.abbie/rules ~/.codex/rules",
+  "claude-skills": "ln -s ~/.abbie/skills ~/.claude/skills",
+  "codex-skills": "ln -s ~/.abbie/skills ~/.codex/skills",
+  "copilot-skills": "ln -s ~/.abbie/skills ~/.copilot/skills",
+};
+
+export function generateFixes(checks: Check[]): Fix[] {
+  const fixes: Fix[] = [];
+
+  for (const check of checks) {
+    if (check.status === "missing") {
+      // Directory fixes
+      if (check.name === "agents-root" || check.name.startsWith("dir-")) {
+        fixes.push({
+          if: check.detail,
+          hint: "Run `abbie doctor --fix` to create missing directories",
+        });
+      }
+      // Binary fixes
+      else if (check.name.startsWith("bin-")) {
+        const bin = check.name.replace("bin-", "");
+        const hints: Record<string, string> = {
+          claude: "Install Claude Code: https://claude.ai/download",
+          codex: "Install Codex: npm install -g @openai/codex",
+          copilot: "Install Copilot CLI: npm install -g @github/copilot-cli",
+          gemini: "Install Gemini CLI: npm install -g @google/gemini-cli",
+        };
+        fixes.push({
+          if: check.detail,
+          hint: hints[bin] || `Install ${bin}`,
+        });
+      }
+      // Symlink fixes
+      else if (check.name.startsWith("symlink-")) {
+        const name = check.name.replace("symlink-", "");
+        const cmd = SYMLINK_FIX_COMMANDS[name];
+        if (cmd) {
+          fixes.push({
+            if: check.detail,
+            hint: `Create symlink: ${cmd}`,
+          });
+        }
+      }
+    }
+    // Warn status for symlinks (wrong target or not a symlink)
+    else if (check.status === "warn" && check.name.startsWith("symlink-")) {
+      const name = check.name.replace("symlink-", "");
+      const cmd = SYMLINK_FIX_COMMANDS[name];
+      if (cmd) {
+        fixes.push({
+          if: check.detail,
+          hint: `Remove and recreate: rm -f <path> && ${cmd}`,
+        });
+      }
+    }
+  }
+
+  return fixes;
+}
+
+// ============================================================================
+// Main doctor function
+// ============================================================================
+
+export interface DoctorOptions {
+  fix?: boolean;
+  includeTemplates?: boolean;
+  includeRepos?: boolean;
+  reposPath?: string;
+}
+
+// ============================================================================
+// Config sync checks
+// ============================================================================
+
+export function checkConfigSync(): Check[] {
+  const checks: Check[] = [];
+  const syncDir = getSyncDir();
+  const statePath = join(syncDir, "config-sync-state.json");
+
+  // Check sync freshness
+  if (existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, "utf-8"));
+      const lastSync = state.lastSuccessAt ?? 0;
+      const hoursSinceSync = (Date.now() - lastSync) / (1000 * 60 * 60);
+
+      if (hoursSinceSync > 12) {
+        checks.push({
+          name: "config-sync-freshness",
+          status: "warn",
+          detail: `Last config sync ${Math.round(hoursSinceSync)}h ago (>12h stale)`,
+        });
+      } else {
+        checks.push({
+          name: "config-sync-freshness",
+          status: "ok",
+          detail: `Last config sync ${Math.round(hoursSinceSync)}h ago`,
+        });
+      }
+
+      if (state.consecutiveFailures > 0) {
+        checks.push({
+          name: "config-sync-failures",
+          status: state.consecutiveFailures >= 5 ? "missing" : "warn",
+          detail: `${state.consecutiveFailures} consecutive sync failures`,
+        });
+      }
+    } catch {
+      checks.push({
+        name: "config-sync-freshness",
+        status: "warn",
+        detail: "Config sync state file corrupt",
+      });
+    }
+  } else {
+    checks.push({
+      name: "config-sync-freshness",
+      status: "warn",
+      detail: "Config sync has never run",
+    });
+  }
+
+  // Check per-agent config file writability
+  const AGENTS = ["claude", "codex", "copilot", "gemini"] as const;
+  for (const agent of AGENTS) {
+    const adapter = getAdapter(agent);
+    if (!adapter) continue;
+
+    const configPath = adapter.configPath();
+    const dir = configPath.substring(0, configPath.lastIndexOf("/"));
+
+    if (existsSync(dir)) {
+      try {
+        accessSync(dir, fsConstants.W_OK);
+        checks.push({
+          name: `config-${agent}-writable`,
+          status: "ok",
+          detail: `${configPath} directory writable`,
+        });
+      } catch {
+        checks.push({
+          name: `config-${agent}-writable`,
+          status: "missing",
+          detail: `${configPath} directory not writable`,
+        });
+      }
+    }
+
+    // Check if config file parses correctly
+    if (adapter.configExists()) {
+      try {
+        adapter.read();
+        checks.push({
+          name: `config-${agent}-parseable`,
+          status: "ok",
+          detail: `${configPath} parses correctly`,
+        });
+      } catch {
+        checks.push({
+          name: `config-${agent}-parseable`,
+          status: "warn",
+          detail: `${configPath} failed to parse`,
+        });
+      }
+    }
+
+    // Check backup existence
+    const hasBackup = !!getLatestBackup(agent);
+    if (hasBackup) {
+      checks.push({
+        name: `config-${agent}-backup`,
+        status: "ok",
+        detail: `Backup exists for ${agent}`,
+      });
+    }
+    // Don't warn about missing backups — they appear after first sync
+  }
+
+  return checks;
+}
+
+export async function runDoctor(options: DoctorOptions = {}): Promise<DoctorResult> {
+  const checks: Check[] = [];
+
+  // Run all environment checks
+  checks.push(...checkDirectories());
+  checks.push(checkRuntime());
+  checks.push(...checkBinaries());
+  checks.push(...checkEnvVars());
+  checks.push(...checkSymlinks());
+  checks.push(...checkConfigSync());
+
+  // Apply fixes if requested
+  if (options.fix) {
+    const _created = fixDirectories();
+    // Update checks for fixed directories
+    for (const check of checks) {
+      if (
+        check.status === "missing" &&
+        (check.name === "agents-root" || check.name.startsWith("dir-"))
+      ) {
+        check.status = "ok";
+        check.detail = `${check.detail.replace(" not found", "")} (created)`;
+      }
+    }
+  }
+
+  // Generate fix suggestions for remaining issues
+  const fixes = generateFixes(checks);
+
+  // v2: Template checks
+  let templateChecks: Check[] | undefined;
+  if (options.includeTemplates) {
+    templateChecks = checkTemplates();
+    // Add template fixes
+    for (const check of templateChecks) {
+      if (check.status === "missing" && check.name === "templates-root") {
+        fixes.push({
+          if: check.detail,
+          hint: "Create templates: mkdir -p ~/.abbie/templates/schemas",
+        });
+      }
+    }
+  }
+
+  // v2: Repo contract checks
+  let repoResults: RepoCheckResult[] | undefined;
+  if (options.includeRepos) {
+    repoResults = checkRepos(options.reposPath);
+    // Add repo fixes
+    for (const result of repoResults) {
+      for (const check of result.checks) {
+        if (check.status === "missing" && check.name.includes("-extends")) {
+          fixes.push({
+            if: check.detail,
+            hint: `Create missing template or update extends path in ${result.repo}`,
+          });
+        }
+      }
+    }
+  }
+
+  // Calculate summary
+  const envChecks = checks;
+  const summary: DoctorResult["summary"] = {
+    environment: {
+      ok: envChecks.filter((c) => c.status === "ok").length,
+      warn: envChecks.filter((c) => c.status === "warn").length,
+      missing: envChecks.filter((c) => c.status === "missing").length,
+    },
+  };
+
+  if (templateChecks) {
+    summary.templates = {
+      ok: templateChecks.filter((c) => c.status === "ok").length,
+      warn: templateChecks.filter((c) => c.status === "warn").length,
+      missing: templateChecks.filter((c) => c.status === "missing").length,
+    };
+  }
+
+  if (repoResults) {
+    summary.repos = summarizeRepoChecks(repoResults);
+  }
+
+  // Determine overall status - ok if no "missing" status (warns are acceptable)
+  const allChecks = [
+    ...checks,
+    ...(templateChecks || []),
+    ...(repoResults?.flatMap((r) => r.checks) || []),
+  ];
+  const ok = !allChecks.some((c) => c.status === "missing");
+
+  return { ok, checks, fixes, templateChecks, repoResults, summary };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { REQUIRED_DIRS, REQUIRED_BINARIES, OPTIONAL_BINARIES, OPTIONAL_ENV_VARS, getAgentsRoot };
+
+export * from "./repos.js";
+// Re-export v2 modules
+export * from "./templates.js";