alsk1992/doctor

Doctor - Complete API Reference

Run system diagnostics, check health status, and troubleshoot issues.

---

Chat Commands

Health Checks

/doctor                                     Run all diagnostics
/doctor quick                               Quick health check
/doctor full                                Full diagnostic scan
/doctor <component>                         Check specific component

Component Checks

/doctor system                              OS, memory, disk
/doctor node                                Node.js version, memory
/doctor network                             Connectivity tests
/doctor api                                 API key validation
/doctor database                            Database connection
/doctor channels                            Channel health

Status

/health                                     Quick health status
/status                                     System status overview
/status verbose                             Detailed status

---

TypeScript API Reference

Create Doctor Service

import { createDoctorService } from 'clodds/doctor';

const doctor = createDoctorService({
  // Checks to run
  checks: ['system', 'node', 'network', 'api', 'database', 'channels'],

  // Thresholds
  thresholds: {
    memoryWarning: 80,    // % memory usage
    memoryCritical: 95,
    diskWarning: 80,      // % disk usage
    diskCritical: 95,
    latencyWarning: 1000, // ms
    latencyCritical: 5000,
  },

  // Timeout
  timeoutMs: 30000,
});

Run Diagnostics

// Run all checks
const report = await doctor.runDiagnostics();

console.log(`Overall: ${report.status}`);  // 'healthy' | 'degraded' | 'unhealthy'
console.log(`Checks passed: ${report.passed}/${report.total}`);

for (const check of report.checks) {
  const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '⚠' : '✗';
  console.log(`${icon} ${check.name}: ${check.message}`);
  if (check.details) {
    console.log(`  ${JSON.stringify(check.details)}`);
  }
}

Run Specific Check

// Check system resources
const system = await doctor.checkSystem();

console.log(`OS: ${system.os} ${system.version}`);
console.log(`CPU: ${system.cpuUsage}%`);
console.log(`Memory: ${system.memoryUsage}% (${system.memoryUsedGB}/${system.memoryTotalGB} GB)`);
console.log(`Disk: ${system.diskUsage}% (${system.diskUsedGB}/${system.diskTotalGB} GB)`);

Check Node.js

const node = await doctor.checkNode();

console.log(`Node.js: ${node.version}`);
console.log(`Heap: ${node.heapUsed}/${node.heapTotal} MB`);
console.log(`RSS: ${node.rss} MB`);
console.log(`Uptime: ${node.uptime} seconds`);

Check Network

const network = await doctor.checkNetwork();

console.log(`Internet: ${network.internet ? 'Connected' : 'Disconnected'}`);
console.log(`DNS: ${network.dns ? 'Working' : 'Failed'}`);

for (const [endpoint, result] of Object.entries(network.endpoints)) {
  console.log(`${endpoint}: ${result.reachable ? 'OK' : 'Failed'} (${result.latencyMs}ms)`);
}

Check API Keys

const api = await doctor.checkApiKeys();

for (const [provider, status] of Object.entries(api)) {
  console.log(`${provider}: ${status.valid ? 'Valid' : 'Invalid'}`);
  if (status.error) {
    console.log(`  Error: ${status.error}`);
  }
  if (status.quota) {
    console.log(`  Quota: ${status.quota.used}/${status.quota.limit}`);
  }
}

Check Database

const db = await doctor.checkDatabase();

console.log(`Connected: ${db.connected}`);
console.log(`Latency: ${db.latencyMs}ms`);
console.log(`Version: ${db.version}`);
console.log(`Tables: ${db.tables}`);
console.log(`Size: ${db.sizeMB} MB`);

Check Channels

const channels = await doctor.checkChannels();

for (const channel of channels) {
  console.log(`${channel.name}: ${channel.status}`);
  if (channel.error) {
    console.log(`  Error: ${channel.error}`);
  }
  console.log(`  Connected: ${channel.connected}`);
  console.log(`  Last message: ${channel.lastMessage}`);
}

Format Report

// Get formatted report
const report = await doctor.runDiagnostics();
const formatted = doctor.formatReport(report);

console.log(formatted);
// Outputs nicely formatted diagnostic report

---

Diagnostic Checks

| Check | What it Tests | |-------|---------------| | system | OS, CPU, memory, disk | | node | Node.js version, heap, memory | | network | Internet, DNS, API endpoints | | api | API key validity and quotas | | database | Connection, latency, schema | | channels | Channel connections, health | | mcp | MCP server connections | | dependencies | npm packages, versions |

---

Status Levels

| Status | Meaning | |--------|---------| | healthy | All checks pass | | degraded | Some warnings, still functional | | unhealthy | Critical failures, action needed |

Check Results

| Result | Meaning | |--------|---------| | pass | Check succeeded | | warn | Warning threshold exceeded | | fail | Critical failure | | skip | Check skipped (not applicable) |

---

CLI Commands

# Run all diagnostics
clodds doctor

# Quick check
clodds doctor --quick

# Check specific component
clodds doctor --check system

# JSON output
clodds doctor --json

---

Common Issues

High Memory Usage

⚠ Memory: 85% used

Solution: Restart the service or increase available memory

API Key Invalid

✗ Anthropic API: Invalid key

Solution: Check ANTHROPIC_API_KEY in .env

Database Connection Failed

✗ Database: Connection refused

Solution: Check DATABASE_URL and ensure PostgreSQL is running

Channel Disconnected

⚠ Telegram: Disconnected

Solution: Check TELEGRAM_BOT_TOKEN and network connectivity

---

Best Practices

1. Run regularly — Check health daily or after changes
2. Monitor trends — Watch for gradual degradation
3. Set alerts — Alert on unhealthy status
4. Fix warnings — Don't wait for failures
5. Review before deploy — Run doctor before production changes