@everstateai/mcp 1.3.2 → 1.3.3

package/src/setup/commands/repair.ts

@@ -0,0 +1,260 @@
+/**
+ * Repair Command
+ *
+ * Automatically fixes detected Everstate issues.
+ *
+ * Usage:
+ *   npx @everstateai/mcp repair
+ *   npx @everstateai/mcp repair --include-warnings
+ *   npx @everstateai/mcp repair --force
+ */
+
+import * as fs from 'fs';
+import {
+  ValidationContext,
+  ValidationResult,
+  RepairOptions,
+  c,
+  getEverstateDir,
+} from '../types.js';
+import { validateAll, repairResult } from '../validators/index.js';
+import { updateVersionFile, createVersionFile, getMcpProxyVersion, HOOK_VERSIONS } from '../version.js';
+
+interface RepairSummary {
+  attempted: number;
+  succeeded: number;
+  failed: number;
+  skipped: number;
+  details: Array<{
+    check: string;
+    result: 'fixed' | 'failed' | 'skipped' | 'manual';
+  }>;
+}
+
+export async function repair(options: RepairOptions = {}): Promise<void> {
+  const context = buildContext(options);
+
+  console.log('');
+  console.log(c('bold', 'Everstate Repair'));
+  console.log(c('dim', '─'.repeat(40)));
+  console.log('');
+
+  // Run validation first
+  console.log('Checking installation...');
+  const summary = await validateAll(context);
+
+  // Find issues to repair
+  const toRepair = summary.results.filter((r) => {
+    if (r.status === 'fail') return true;
+    if (r.status === 'warn' && options.includeWarnings) return true;
+    return false;
+  });
+
+  if (toRepair.length === 0) {
+    console.log('');
+    console.log(c('green', '✓ No issues to repair'));
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log(`Found ${toRepair.length} issue(s) to repair:`);
+  for (const issue of toRepair) {
+    console.log(`  ${c('yellow', '•')} ${issue.component}: ${issue.check}`);
+  }
+  console.log('');
+
+  // Perform repairs
+  const repairSummary = await performRepairs(toRepair, context, options);
+
+  // Update version file on success
+  if (repairSummary.succeeded > 0) {
+    updateVersionFile({
+      components: {
+        mcpProxy: getMcpProxyVersion(),
+        hooks: HOOK_VERSIONS,
+      },
+    });
+  }
+
+  // Output summary
+  outputRepairSummary(repairSummary);
+
+  // Exit code
+  if (repairSummary.failed > 0) {
+    process.exit(1);
+  }
+}
+
+function buildContext(options: RepairOptions): ValidationContext {
+  const context: ValidationContext = {
+    projectDir: options.projectDir || process.cwd(),
+  };
+
+  // Try to load API key
+  const apiKeyPath = `${getEverstateDir()}/api-key`;
+  if (fs.existsSync(apiKeyPath)) {
+    try {
+      context.apiKey = fs.readFileSync(apiKeyPath, 'utf8').trim();
+    } catch {
+      // Will be handled during repair
+    }
+  }
+
+  return context;
+}
+
+async function performRepairs(
+  issues: ValidationResult[],
+  context: ValidationContext,
+  options: RepairOptions
+): Promise<RepairSummary> {
+  const summary: RepairSummary = {
+    attempted: 0,
+    succeeded: 0,
+    failed: 0,
+    skipped: 0,
+    details: [],
+  };
+
+  for (const issue of issues) {
+    const checkName = `${issue.component}: ${issue.check}`;
+
+    // Check if repair is available
+    if (!issue.repairAction) {
+      console.log(`  ${c('dim', '○')} ${checkName}: ${c('dim', 'No automatic repair available')}`);
+      summary.skipped++;
+      summary.details.push({ check: checkName, result: 'manual' });
+      continue;
+    }
+
+    // Check if repair requires confirmation
+    if (!issue.repairAction.automatic && !options.force) {
+      console.log(`  ${c('yellow', '?')} ${checkName}: Requires --force or manual intervention`);
+      summary.skipped++;
+      summary.details.push({ check: checkName, result: 'skipped' });
+      continue;
+    }
+
+    // Attempt repair
+    summary.attempted++;
+    console.log(`  ${c('cyan', '→')} Repairing: ${checkName}...`);
+
+    try {
+      const success = await repairResult(issue, context);
+
+      if (success) {
+        console.log(`    ${c('green', '✓')} Fixed`);
+        summary.succeeded++;
+        summary.details.push({ check: checkName, result: 'fixed' });
+      } else {
+        console.log(`    ${c('red', '✗')} Failed`);
+        summary.failed++;
+        summary.details.push({ check: checkName, result: 'failed' });
+      }
+    } catch (error) {
+      console.log(`    ${c('red', '✗')} Error: ${String(error)}`);
+      summary.failed++;
+      summary.details.push({ check: checkName, result: 'failed' });
+    }
+  }
+
+  return summary;
+}
+
+function outputRepairSummary(summary: RepairSummary): void {
+  console.log('');
+  console.log(c('bold', 'Repair Summary'));
+  console.log(c('dim', '─'.repeat(40)));
+
+  if (summary.succeeded > 0) {
+    console.log(`  ${c('green', '✓')} ${summary.succeeded} fixed`);
+  }
+  if (summary.failed > 0) {
+    console.log(`  ${c('red', '✗')} ${summary.failed} failed`);
+  }
+  if (summary.skipped > 0) {
+    console.log(`  ${c('yellow', '○')} ${summary.skipped} skipped`);
+  }
+
+  console.log('');
+
+  if (summary.failed > 0) {
+    console.log(c('yellow', 'Some repairs failed. You may need to:'));
+    console.log(c('dim', '  1. Run with --force for non-automatic repairs'));
+    console.log(c('dim', '  2. Manually fix issues that cannot be auto-repaired'));
+    console.log(c('dim', '  3. Re-run setup: npx @everstateai/mcp setup <api-key>'));
+    console.log('');
+  } else if (summary.succeeded > 0) {
+    console.log(c('green', 'All repairs completed successfully!'));
+    console.log(c('dim', 'Run `npx @everstateai/mcp doctor` to verify.'));
+    console.log('');
+  }
+}
+
+// CLI entry point
+export async function repairCli(args: string[]): Promise<void> {
+  const options: RepairOptions = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    switch (arg) {
+      case '--force':
+      case '-f':
+        options.force = true;
+        break;
+      case '--include-warnings':
+      case '-w':
+        options.includeWarnings = true;
+        break;
+      case '--component':
+      case '-c':
+        options.component = args[++i];
+        break;
+      case '--project':
+      case '-p':
+        options.projectDir = args[++i];
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+    }
+  }
+
+  await repair(options);
+}
+
+function printHelp(): void {
+  console.log(`
+Everstate Repair - Fix installation issues
+
+Usage:
+  npx @everstateai/mcp repair [options]
+
+Options:
+  --force, -f              Force non-automatic repairs
+  --include-warnings, -w   Also repair warnings (not just failures)
+  --component, -c          Repair only a specific component
+  --project, -p            Specify project directory
+  --help, -h               Show this help
+
+What can be repaired:
+  • Missing API key file (if you provide it)
+  • Incorrect file permissions
+  • Missing or outdated hooks
+  • MCP configuration issues
+  • Hook registration in Claude config
+
+What requires manual intervention:
+  • Invalid API key (get a new one from dashboard)
+  • Missing project configuration (run setup)
+  • Network connectivity issues
+
+Examples:
+  npx @everstateai/mcp repair
+  npx @everstateai/mcp repair --force
+  npx @everstateai/mcp repair --include-warnings
+`);
+}

package/src/setup/hooks/templates.ts

@@ -0,0 +1,239 @@
+/**
+ * Hook Templates
+ *
+ * Versioned hook templates for installation and updates.
+ * Each hook includes a VERSION header for validation.
+ */
+
+import { HookConfig, HOOK_VERSIONS, EVERSTATE_API_URL, getEverstateDir } from '../types.js';
+
+/**
+ * Get the sync-todos.js hook content
+ */
+export function getSyncTodosHook(config?: Partial<HookConfig>): string {
+  const apiKeyPath = config?.apiKeyPath || `${getEverstateDir()}/api-key`;
+  const apiUrl = config?.apiUrl || EVERSTATE_API_URL;
+  const generatedAt = config?.generatedAt || new Date().toISOString();
+
+  return `#!/usr/bin/env node
+/**
+ * Everstate Sync Todos Hook v${HOOK_VERSIONS.syncTodos}
+ * VERSION: ${HOOK_VERSIONS.syncTodos}
+ * GENERATED: ${generatedAt}
+ *
+ * Syncs Claude's TodoWrite tasks with Everstate.
+ * Runs after every TodoWrite tool call.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const API_KEY_PATH = '${apiKeyPath}';
+const API_URL = '${apiUrl}';
+
+async function main() {
+  try {
+    // Read API key
+    if (!fs.existsSync(API_KEY_PATH)) {
+      console.error('[everstate] API key not found at', API_KEY_PATH);
+      process.exit(0); // Don't block Claude
+    }
+    const apiKey = fs.readFileSync(API_KEY_PATH, 'utf8').trim();
+
+    // Parse input from Claude
+    const input = JSON.parse(process.env.TOOL_INPUT || '{}');
+    const todos = input.todos || [];
+
+    if (todos.length === 0) {
+      process.exit(0);
+    }
+
+    // Find project config
+    let projectId = null;
+    let cwd = process.cwd();
+    for (let i = 0; i < 10; i++) {
+      const configPath = path.join(cwd, '.everstate.json');
+      if (fs.existsSync(configPath)) {
+        try {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+          projectId = config.projectId;
+          break;
+        } catch {}
+      }
+      const parent = path.dirname(cwd);
+      if (parent === cwd) break;
+      cwd = parent;
+    }
+
+    if (!projectId) {
+      // No project config - skip sync
+      process.exit(0);
+    }
+
+    // Send to API for matching and storage
+    const response = await fetch(\`\${API_URL}/api/session/sync-todos\`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': \`Bearer \${apiKey}\`,
+      },
+      body: JSON.stringify({
+        projectId,
+        todos,
+        sessionId: process.env.SESSION_ID || null,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      console.error('[everstate] Sync failed:', response.status, text);
+    }
+  } catch (error) {
+    console.error('[everstate] Hook error:', error.message);
+  }
+
+  process.exit(0);
+}
+
+main();
+`;
+}
+
+/**
+ * Get the session-start.sh hook content
+ */
+export function getSessionStartHook(config?: Partial<HookConfig>): string {
+  const generatedAt = config?.generatedAt || new Date().toISOString();
+
+  return `#!/bin/bash
+# Everstate Session Start Hook v${HOOK_VERSIONS.sessionStart}
+# VERSION: ${HOOK_VERSIONS.sessionStart}
+# GENERATED: ${generatedAt}
+#
+# Loads context at session start.
+# Place in .claude/hooks/ directory.
+
+# Check for MCP - if available, tools handle context loading
+if command -v claude &> /dev/null; then
+  # Claude Code detected - MCP tools will load context
+  exit 0
+fi
+
+# Fallback for environments without MCP
+echo "[everstate] Session starting - use sync() to load context"
+`;
+}
+
+/**
+ * Get the session-end.sh hook content
+ */
+export function getSessionEndHook(config?: Partial<HookConfig>): string {
+  const apiKeyPath = config?.apiKeyPath || `${getEverstateDir()}/api-key`;
+  const apiUrl = config?.apiUrl || EVERSTATE_API_URL;
+  const generatedAt = config?.generatedAt || new Date().toISOString();
+
+  return `#!/bin/bash
+# Everstate Session End Hook v${HOOK_VERSIONS.sessionEnd}
+# VERSION: ${HOOK_VERSIONS.sessionEnd}
+# GENERATED: ${generatedAt}
+#
+# Saves session summary when Claude session ends.
+
+API_KEY_PATH="${apiKeyPath}"
+API_URL="${apiUrl}"
+
+# Read API key
+if [ ! -f "$API_KEY_PATH" ]; then
+  exit 0
+fi
+API_KEY=$(cat "$API_KEY_PATH")
+
+# Find project config
+find_project_id() {
+  local dir="$PWD"
+  for i in {1..10}; do
+    if [ -f "$dir/.everstate.json" ]; then
+      grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' "$dir/.everstate.json" | cut -d'"' -f4
+      return
+    fi
+    dir=$(dirname "$dir")
+    [ "$dir" = "/" ] && break
+  done
+}
+
+PROJECT_ID=$(find_project_id)
+if [ -z "$PROJECT_ID" ]; then
+  exit 0
+fi
+
+# Signal session end to API
+curl -s -X POST "$API_URL/api/session/end" \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer $API_KEY" \\
+  -d "{\\"projectId\\": \\"$PROJECT_ID\\"}" > /dev/null 2>&1
+
+exit 0
+`;
+}
+
+/**
+ * Get the pre-compact.sh hook content (for context compaction)
+ */
+export function getPreCompactHook(config?: Partial<HookConfig>): string {
+  const apiKeyPath = config?.apiKeyPath || `${getEverstateDir()}/api-key`;
+  const apiUrl = config?.apiUrl || EVERSTATE_API_URL;
+  const generatedAt = config?.generatedAt || new Date().toISOString();
+
+  return `#!/bin/bash
+# Everstate Pre-Compact Hook v${HOOK_VERSIONS.sessionEnd}
+# VERSION: ${HOOK_VERSIONS.sessionEnd}
+# GENERATED: ${generatedAt}
+#
+# Saves session context before Claude's context compaction.
+
+API_KEY_PATH="${apiKeyPath}"
+API_URL="${apiUrl}"
+
+# Read API key
+if [ ! -f "$API_KEY_PATH" ]; then
+  exit 0
+fi
+API_KEY=$(cat "$API_KEY_PATH")
+
+# Find project config
+find_project_id() {
+  local dir="$PWD"
+  for i in {1..10}; do
+    if [ -f "$dir/.everstate.json" ]; then
+      grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' "$dir/.everstate.json" | cut -d'"' -f4
+      return
+    fi
+    dir=$(dirname "$dir")
+    [ "$dir" = "/" ] && break
+  done
+}
+
+PROJECT_ID=$(find_project_id)
+if [ -z "$PROJECT_ID" ]; then
+  exit 0
+fi
+
+# Get transcript from environment if available
+TRANSCRIPT="\${CLAUDE_TRANSCRIPT:-}"
+
+# Signal pre-compact to API
+curl -s -X POST "$API_URL/api/session/pre-compact" \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer $API_KEY" \\
+  -d "{\\"projectId\\": \\"$PROJECT_ID\\", \\"transcript\\": \\"\$TRANSCRIPT\\"}" > /dev/null 2>&1
+
+exit 0
+`;
+}
+
+export const hookTemplates = {
+  syncTodos: getSyncTodosHook,
+  sessionStart: getSessionStartHook,
+  sessionEnd: getSessionEndHook,
+  preCompact: getPreCompactHook,
+};

package/src/setup/types.ts

@@ -0,0 +1,199 @@
+/**
+ * Everstate Setup Types
+ *
+ * Shared types for the setup, doctor, and repair commands.
+ */
+
+// ============================================================================
+// Validation Types
+// ============================================================================
+
+export type ValidationStatus = 'pass' | 'warn' | 'fail';
+
+export type RepairType = 'install' | 'update' | 'configure' | 'delete' | 'chmod';
+
+export interface RepairAction {
+  type: RepairType;
+  description: string;
+  automatic: boolean; // Can be auto-repaired without user input
+}
+
+export interface ValidationResult {
+  component: string;
+  check: string;
+  status: ValidationStatus;
+  message: string;
+  details?: Record<string, unknown>;
+  repairAction?: RepairAction;
+}
+
+export interface Validator {
+  name: string;
+  validate(context: ValidationContext): Promise<ValidationResult[]>;
+  repair?(result: ValidationResult, context: ValidationContext): Promise<boolean>;
+}
+
+export interface ValidationContext {
+  projectDir?: string;
+  apiKey?: string;
+  verbose?: boolean;
+  skipNetwork?: boolean;
+}
+
+export interface ValidationSummary {
+  passed: number;
+  warnings: number;
+  failed: number;
+  results: ValidationResult[];
+}
+
+// ============================================================================
+// Version Tracking Types
+// ============================================================================
+
+export interface HookVersions {
+  sessionStart: string;
+  sessionEnd: string;
+  syncTodos: string;
+}
+
+export interface ComponentVersions {
+  mcpProxy: string;
+  hooks: HookVersions;
+}
+
+export interface ConfigPaths {
+  claudeCode: string;
+  claudeDesktop?: string;
+  apiKey: string;
+  globalHooks: string;
+}
+
+export interface ProjectInstallation {
+  projectId: string;
+  configVersion: string;
+  hooksVersion: string;
+  lastValidated: string;
+}
+
+export interface VersionFile {
+  installedAt: string;
+  installedBy: 'setup' | 'npx' | 'manual';
+  components: ComponentVersions;
+  configPaths: ConfigPaths;
+  projects: Record<string, ProjectInstallation>;
+  lastUpdateCheck?: string;
+}
+
+// ============================================================================
+// Hook Types
+// ============================================================================
+
+export interface HookTemplate {
+  name: string;
+  version: string;
+  filename: string;
+  content: (config: HookConfig) => string;
+}
+
+export interface HookConfig {
+  apiKeyPath: string;
+  apiUrl: string;
+  generatedAt: string;
+}
+
+// ============================================================================
+// Setup Types
+// ============================================================================
+
+export interface SetupOptions {
+  apiKey: string;
+  projectDir: string;
+  projectId?: string;
+  skipHooks?: boolean;
+  force?: boolean;
+  globalOnly?: boolean;
+}
+
+export interface DoctorOptions {
+  projectDir?: string;
+  json?: boolean;
+  verbose?: boolean;
+  component?: string;
+}
+
+export interface RepairOptions {
+  projectDir?: string;
+  force?: boolean;
+  component?: string;
+  includeWarnings?: boolean;
+}
+
+// ============================================================================
+// Console Output Types
+// ============================================================================
+
+export interface Colors {
+  reset: string;
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  cyan: string;
+  bold: string;
+  dim: string;
+}
+
+export const COLORS: Colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+};
+
+export function supportsColor(): boolean {
+  return (
+    process.stdout.isTTY === true &&
+    process.env.FORCE_COLOR !== '0' &&
+    (process.platform !== 'win32' ||
+      process.env.TERM === 'xterm-256color' ||
+      !!process.env.WT_SESSION)
+  );
+}
+
+export function c(color: keyof Colors, text: string): string {
+  return supportsColor() ? `${COLORS[color]}${text}${COLORS.reset}` : text;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const HOOK_VERSIONS = {
+  sessionStart: '1.1.0',
+  sessionEnd: '1.1.0',
+  syncTodos: '5.0.0',
+};
+
+export const EVERSTATE_API_URL = 'https://www.everstate.ai';
+
+export function getEverstateDir(): string {
+  return `${process.env.HOME}/.everstate`;
+}
+
+export function getClaudeConfigPath(): string {
+  return `${process.env.HOME}/.claude.json`;
+}
+
+export function getClaudeDesktopConfigPath(): string {
+  if (process.platform === 'darwin') {
+    return `${process.env.HOME}/Library/Application Support/Claude/claude_desktop_config.json`;
+  } else if (process.platform === 'win32') {
+    return `${process.env.APPDATA}/Claude/claude_desktop_config.json`;
+  }
+  return ''; // Linux - no known Claude Desktop location
+}