@eltonssouza/development-utility-kit 0.10.0

package/bin/lib/doctor.js

@@ -0,0 +1,527 @@
+'use strict';
+
+/**
+ * `duk doctor` — environment validation for the development-utility-kit harness.
+ *
+ * Mechanical, deterministic, no LLM. Per ADR-034:
+ *   "Mecânico, determinístico, scriptável → CLI duk."
+ *
+ * Checks:
+ *   1. environment   — Node version, git, npx, python3 (warn-only for hooks)
+ *   2. harness       — root directory, .claude/ structure, CLAUDE.md, package.json
+ *   3. settings      — ~/.claude/settings.json exists, parseable, hook paths live
+ *   4. stacks        — packs available in .claude/stacks/, README index present
+ *   5. credentials   — C:/development/tools/credentials/vps.txt (warn if missing)
+ *   6. project       — only if CWD is an adopted project: MANIFEST + Project Identity
+ *
+ * Output: aligned table (Category | Check | Status | Detail).
+ * Exit code: 0 if no FAIL, 1 if any FAIL. WARN never fails unless --strict.
+ *
+ * Flags:
+ *   --json     machine-readable output
+ *   --strict   exit non-zero on WARN too
+ *   --help     show help
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+// ── Status constants ────────────────────────────────────────────────────────
+
+const PASS = 'PASS';
+const WARN = 'WARN';
+const FAIL = 'FAIL';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Run a command and return { stdout, status }. Never throws.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {{ stdout: string, status: number|null }}
+ */
+function runCmd(cmd, args) {
+  try {
+    const r = spawnSync(cmd, args, {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      timeout: 5000,
+    });
+    return { stdout: (r.stdout || '').trim(), status: r.status };
+  } catch {
+    return { stdout: '', status: null };
+  }
+}
+
+function fileExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function packageRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+function harnessVersion() {
+  const pkg = readJsonSafe(path.join(packageRoot(), 'package.json'));
+  return pkg && pkg.version ? pkg.version : '0.0.0';
+}
+
+// ── Individual checks ───────────────────────────────────────────────────────
+
+/**
+ * @returns {Array<{category: string, name: string, status: string, detail: string}>}
+ */
+function checkEnvironment() {
+  const out = [];
+
+  // Node version
+  const nodeVer = process.version.replace(/^v/, '');
+  const major = parseInt(nodeVer.split('.')[0], 10);
+  out.push({
+    category: 'environment',
+    name: 'node',
+    status: major >= 18 ? PASS : FAIL,
+    detail: `${process.version} (need >= 18)`,
+  });
+
+  // git
+  const git = runCmd('git', ['--version']);
+  out.push({
+    category: 'environment',
+    name: 'git',
+    status: git.status === 0 ? PASS : FAIL,
+    detail: git.status === 0 ? git.stdout : 'not in PATH',
+  });
+
+  // npx
+  const npx = runCmd('npx', ['--version']);
+  out.push({
+    category: 'environment',
+    name: 'npx',
+    status: npx.status === 0 ? PASS : WARN,
+    detail: npx.status === 0 ? `v${npx.stdout}` : 'not in PATH (some skills need it)',
+  });
+
+  // python3 (used by some plugin hooks)
+  let py = runCmd('python3', ['--version']);
+  if (py.status !== 0) py = runCmd('python', ['--version']);
+  out.push({
+    category: 'environment',
+    name: 'python',
+    status: py.status === 0 ? PASS : WARN,
+    detail: py.status === 0 ? py.stdout : 'not in PATH (some hooks need it)',
+  });
+
+  return out;
+}
+
+function checkHarness() {
+  const out = [];
+  const root = packageRoot();
+
+  // Root exists and is a git repo
+  const isGitRepo = isDir(path.join(root, '.git'));
+  out.push({
+    category: 'harness',
+    name: 'root',
+    status: isGitRepo ? PASS : FAIL,
+    detail: `${root} ${isGitRepo ? '(git repo)' : '(NOT a git repo)'}`,
+  });
+
+  // Required structure
+  const required = [
+    { rel: '.claude', kind: 'dir' },
+    { rel: '.claude/agents', kind: 'dir' },
+    { rel: '.claude/skills', kind: 'dir' },
+    { rel: '.claude/stacks', kind: 'dir' },
+    { rel: 'CLAUDE.md', kind: 'file' },
+    { rel: 'package.json', kind: 'file' },
+    { rel: 'bin/cli.js', kind: 'file' },
+  ];
+
+  for (const r of required) {
+    const full = path.join(root, r.rel);
+    const ok = r.kind === 'dir' ? isDir(full) : fileExists(full);
+    out.push({
+      category: 'harness',
+      name: r.rel,
+      status: ok ? PASS : FAIL,
+      detail: ok ? r.kind : `missing (${r.kind})`,
+    });
+  }
+
+  // Harness version
+  out.push({
+    category: 'harness',
+    name: 'version',
+    status: PASS,
+    detail: harnessVersion(),
+  });
+
+  return out;
+}
+
+function checkSettings() {
+  const out = [];
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+
+  if (!fileExists(settingsPath)) {
+    out.push({
+      category: 'settings',
+      name: '~/.claude/settings.json',
+      status: WARN,
+      detail: 'not found (hooks/permissions empty)',
+    });
+    return out;
+  }
+
+  const settings = readJsonSafe(settingsPath);
+  if (!settings) {
+    out.push({
+      category: 'settings',
+      name: '~/.claude/settings.json',
+      status: FAIL,
+      detail: 'exists but not valid JSON',
+    });
+    return out;
+  }
+
+  out.push({
+    category: 'settings',
+    name: '~/.claude/settings.json',
+    status: PASS,
+    detail: 'valid JSON',
+  });
+
+  // Walk hooks looking for absolute paths that don't exist on disk.
+  const brokenHooks = [];
+  const allHooks = [];
+  try {
+    const hooks = settings.hooks || {};
+    for (const eventName of Object.keys(hooks)) {
+      const arr = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+      for (const entry of arr) {
+        const hookList = (entry && Array.isArray(entry.hooks)) ? entry.hooks : [];
+        for (const h of hookList) {
+          if (h && typeof h.command === 'string') {
+            // Extract first absolute-looking path from the command.
+            const m = h.command.match(/[A-Za-z]:[/\\][^\s"']+|\/[^\s"']+/);
+            if (m) {
+              const p = m[0];
+              allHooks.push({ event: eventName, path: p });
+              if (!fileExists(p)) brokenHooks.push({ event: eventName, path: p });
+            }
+          }
+        }
+      }
+    }
+  } catch {
+    // ignore — best-effort scan
+  }
+
+  out.push({
+    category: 'settings',
+    name: 'hooks.total',
+    status: PASS,
+    detail: `${allHooks.length} hook command(s) detected`,
+  });
+
+  if (brokenHooks.length > 0) {
+    for (const b of brokenHooks) {
+      out.push({
+        category: 'settings',
+        name: `hook.${b.event}`,
+        status: FAIL,
+        detail: `path does not exist: ${b.path}`,
+      });
+    }
+  } else if (allHooks.length > 0) {
+    out.push({
+      category: 'settings',
+      name: 'hooks.paths',
+      status: PASS,
+      detail: 'all hook paths exist',
+    });
+  }
+
+  return out;
+}
+
+function checkStacks() {
+  const out = [];
+  const stacksDir = path.join(packageRoot(), '.claude', 'stacks');
+
+  if (!isDir(stacksDir)) {
+    out.push({
+      category: 'stacks',
+      name: 'directory',
+      status: FAIL,
+      detail: 'missing .claude/stacks/',
+    });
+    return out;
+  }
+
+  // Index
+  const readme = path.join(stacksDir, 'README.md');
+  out.push({
+    category: 'stacks',
+    name: 'README.md',
+    status: fileExists(readme) ? PASS : WARN,
+    detail: fileExists(readme) ? 'present' : 'missing (index lost)',
+  });
+
+  // Walk languages/<framework>-<major>.md
+  let packs = [];
+  try {
+    const langs = fs.readdirSync(stacksDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+    for (const lang of langs) {
+      const langDir = path.join(stacksDir, lang);
+      const files = fs.readdirSync(langDir).filter((f) => f.endsWith('.md'));
+      for (const f of files) {
+        packs.push(`${lang}/${f.replace(/\.md$/, '')}`);
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  out.push({
+    category: 'stacks',
+    name: 'packs.count',
+    status: packs.length > 0 ? PASS : WARN,
+    detail: packs.length === 0 ? 'no packs found' : `${packs.length} pack(s): ${packs.join(', ')}`,
+  });
+
+  return out;
+}
+
+function checkOperationalGuardRail() {
+  return [{
+    category: 'guidance',
+    name: 'mass-edits',
+    status: PASS,
+    detail: 'Use Cowork/sandbox for mass reads & validates — avoid mass native-git edits in Claude Code CLI on Windows (OS locks, AV scans).',
+  }];
+}
+
+function checkCredentials() {
+  const out = [];
+  const credPath = process.platform === 'win32'
+    ? 'C:/development/tools/credentials/vps.txt'
+    : path.join(os.homedir(), 'development/tools/credentials/vps.txt');
+
+  out.push({
+    category: 'credentials',
+    name: 'vps.txt',
+    status: fileExists(credPath) ? PASS : WARN,
+    detail: fileExists(credPath) ? credPath : `not found at ${credPath} (skills that need VPS access will prompt)`,
+  });
+
+  return out;
+}
+
+/**
+ * Check whether a .claude.bak/ directory exists and is restorable
+ * (i.e., it contains at least one .md file — not an empty dir).
+ * @param {string} dir  Project directory to inspect.
+ * @returns {Array<{category,name,status,detail}>}
+ */
+function checkBackupRestore(dir) {
+  const out = [];
+  const bakDir = path.join(dir, '.claude.bak');
+
+  if (!isDir(bakDir)) {
+    // No backup present — this is fine (first install or intentionally cleaned).
+    out.push({
+      category: 'backup',
+      name: '.claude.bak',
+      status: PASS,
+      detail: 'no backup present (normal for first install)',
+    });
+    return out;
+  }
+
+  // Backup exists — verify it is restorable (contains agent/skill files).
+  let fileCount = 0;
+  try {
+    const walk = (d) => {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const full = path.join(d, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.isFile()) fileCount++;
+      }
+    };
+    walk(bakDir);
+  } catch {
+    // ignore
+  }
+
+  if (fileCount === 0) {
+    out.push({
+      category: 'backup',
+      name: '.claude.bak',
+      status: WARN,
+      detail: `backup directory exists but is empty — not restorable (rm -rf .claude.bak to clear)`,
+    });
+  } else {
+    out.push({
+      category: 'backup',
+      name: '.claude.bak',
+      status: PASS,
+      detail: `backup present and restorable (${fileCount} file(s) — restore: cp -r .claude.bak .claude)`,
+    });
+  }
+
+  return out;
+}
+
+function checkProject() {
+  // Only check the current working directory — and only if it looks like an adopted project (not the harness itself).
+  const out = [];
+  const cwd = process.cwd();
+  const root = packageRoot();
+
+  // Skip when invoked from the harness root itself.
+  if (path.resolve(cwd) === path.resolve(root)) {
+    return out;
+  }
+
+  // Always check backup regardless of whether .claude/ exists.
+  out.push(...checkBackupRestore(cwd));
+
+  const cwdClaude = path.join(cwd, '.claude');
+  if (!isDir(cwdClaude)) {
+    out.push({
+      category: 'project',
+      name: 'cwd',
+      status: WARN,
+      detail: 'CWD is not an adopted project (no .claude/) — run `duk install` to adopt',
+    });
+    return out;
+  }
+
+  // MANIFEST baseline
+  const manifest = path.join(cwdClaude, '.MANIFEST');
+  out.push({
+    category: 'project',
+    name: '.MANIFEST',
+    status: fileExists(manifest) ? PASS : WARN,
+    detail: fileExists(manifest) ? 'baseline present' : 'missing (run `duk install` to create)',
+  });
+
+  // Project Identity in CLAUDE.md (not the placeholder)
+  const claudeMd = path.join(cwd, 'CLAUDE.md');
+  if (fileExists(claudeMd)) {
+    const txt = fs.readFileSync(claudeMd, 'utf8');
+    const filled = !/Project name.*<project-name>/i.test(txt) && /## Project Identity/i.test(txt);
+    out.push({
+      category: 'project',
+      name: 'Project Identity',
+      status: filled ? PASS : WARN,
+      detail: filled ? 'filled' : 'placeholder `<project-name>` still present — run stack discovery',
+    });
+  } else {
+    out.push({
+      category: 'project',
+      name: 'CLAUDE.md',
+      status: FAIL,
+      detail: 'missing',
+    });
+  }
+
+  return out;
+}
+
+// ── Formatting ──────────────────────────────────────────────────────────────
+
+function formatTable(rows) {
+  if (rows.length === 0) return '';
+  const headers = ['CATEGORY', 'CHECK', 'STATUS', 'DETAIL'];
+  const widths = headers.map((h, i) => {
+    const colKey = ['category', 'name', 'status', 'detail'][i];
+    return Math.max(h.length, ...rows.map((r) => String(r[colKey] || '').length));
+  });
+
+  const pad = (s, w) => String(s || '').padEnd(w);
+  const sep = widths.map((w) => '─'.repeat(w)).join('─┼─');
+  const header = headers.map((h, i) => pad(h, widths[i])).join(' │ ');
+  const body = rows.map((r) =>
+    [r.category, r.name, r.status, r.detail].map((v, i) => pad(v, widths[i])).join(' │ ')
+  ).join('\n');
+
+  return `${header}\n${sep}\n${body}`;
+}
+
+function summarize(rows) {
+  const counts = { PASS: 0, WARN: 0, FAIL: 0 };
+  for (const r of rows) counts[r.status] = (counts[r.status] || 0) + 1;
+  return counts;
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+/**
+ * @param {{ json?: boolean, strict?: boolean }} [options]
+ * @returns {number} exit code
+ */
+function runDoctor(options) {
+  const opts = options || {};
+  const rows = [
+    ...checkEnvironment(),
+    ...checkHarness(),
+    ...checkSettings(),
+    ...checkStacks(),
+    ...checkCredentials(),
+    ...checkOperationalGuardRail(),
+    ...checkProject(),
+  ];
+
+  const counts = summarize(rows);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ summary: counts, checks: rows }, null, 2) + '\n');
+  } else {
+    process.stdout.write('duk doctor — environment validation\n\n');
+    process.stdout.write(formatTable(rows) + '\n\n');
+    process.stdout.write(
+      `Summary: ${counts.PASS} PASS, ${counts.WARN} WARN, ${counts.FAIL} FAIL\n`
+    );
+    if (counts.FAIL > 0) {
+      process.stdout.write('\nAction required: fix FAIL items before continuing.\n');
+    } else if (counts.WARN > 0) {
+      process.stdout.write('\nNon-blocking warnings present. Review when convenient.\n');
+    } else {
+      process.stdout.write('\nAll clear.\n');
+    }
+  }
+
+  if (counts.FAIL > 0) return 1;
+  if (opts.strict && counts.WARN > 0) return 1;
+  return 0;
+}
+
+module.exports = { runDoctor };