@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/diagnose.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+/**
+ * Diagnose Script for Everything Claude Code
+ * Deep diagnostics for troubleshooting issues
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getClaudeDir, getSessionsDir, readFile, findFiles, log } = require('./lib/utils');
+
+// Status indicators
+const OK = '[OK]';
+const WARN = '[WARN]';
+const FAIL = '[FAIL]';
+
+const recommendations = [];
+
+function padRight(str, len) {
+  return str.padEnd(len);
+}
+
+function addRecommendation(text) {
+  recommendations.push(text);
+}
+
+// Configuration Checks
+function checkJsonFile(name, filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { status: WARN, message: 'Not found' };
+  }
+  try {
+    const content = readFile(filePath);
+    const parsed = JSON.parse(content);
+
+    // Additional validation based on file type
+    if (name === 'hooks.json' && parsed.hooks) {
+      return { status: OK, message: `Valid, ${parsed.hooks.length} hooks` };
+    }
+    if (name === 'settings.json' && parsed.mcpServers) {
+      const mcpCount = Object.keys(parsed.mcpServers).length;
+      return { status: OK, message: `Valid, ${mcpCount} MCPs` };
+    }
+
+    return { status: OK, message: 'Valid' };
+  } catch (err) {
+    addRecommendation(`Fix JSON syntax error in ${name}: ${err.message}`);
+    return { status: FAIL, message: `Invalid JSON: ${err.message.slice(0, 50)}` };
+  }
+}
+
+function checkConfigurations() {
+  log('Checking configurations...');
+
+  const hooksFile = path.join(process.cwd(), 'hooks', 'hooks.json');
+  const hooksResult = checkJsonFile('hooks.json', hooksFile);
+  log(`  ${padRight('hooks.json:', 20)} ${hooksResult.status} ${hooksResult.message}`);
+
+  const settingsFile = path.join(getClaudeDir(), 'settings.json');
+  const settingsResult = checkJsonFile('settings.json', settingsFile);
+  log(`  ${padRight('settings.json:', 20)} ${settingsResult.status} ${settingsResult.message}`);
+
+  const packageFile = path.join(process.cwd(), 'package.json');
+  const packageResult = checkJsonFile('package.json', packageFile);
+  log(`  ${padRight('package.json:', 20)} ${packageResult.status} ${packageResult.message}`);
+
+  // Check if node_modules exists
+  const nodeModules = path.join(process.cwd(), 'node_modules');
+  if (!fs.existsSync(nodeModules)) {
+    log(`  ${padRight('Dependencies:', 20)} ${FAIL} node_modules not found`);
+    addRecommendation('Run "npm install" to install dependencies');
+  } else {
+    log(`  ${padRight('Dependencies:', 20)} ${OK} Installed`);
+  }
+
+  log('');
+}
+
+// Permission Checks
+function checkPermission(name, dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return { status: WARN, message: 'Does not exist' };
+  }
+  try {
+    const testFile = path.join(dirPath, '.diagnose-test');
+    fs.writeFileSync(testFile, 'test');
+    fs.unlinkSync(testFile);
+    return { status: OK, message: 'Writable' };
+  } catch (err) {
+    addRecommendation(`Fix permissions on ${dirPath}: ${err.code}`);
+    return { status: FAIL, message: `Not writable: ${err.code}` };
+  }
+}
+
+function checkPermissions() {
+  log('Checking permissions...');
+
+  const claudeDir = getClaudeDir();
+  const claudeResult = checkPermission('~/.claude/', claudeDir);
+  log(`  ${padRight('~/.claude/:', 20)} ${claudeResult.status} ${claudeResult.message}`);
+
+  const memoryDir = path.join(claudeDir, 'memory');
+  const memoryResult = checkPermission('~/.claude/memory/', memoryDir);
+  log(`  ${padRight('~/.claude/memory/:', 20)} ${memoryResult.status} ${memoryResult.message}`);
+
+  const skillsDir = path.join(claudeDir, 'skills');
+  const skillsResult = checkPermission('~/.claude/skills/', skillsDir);
+  log(`  ${padRight('~/.claude/skills/:', 20)} ${skillsResult.status} ${skillsResult.message}`);
+
+  log('');
+}
+
+// Recent Errors Check
+function checkRecentErrors() {
+  log('Checking recent errors (last 24h)...');
+
+  const sessionsDir = getSessionsDir();
+  if (!fs.existsSync(sessionsDir)) {
+    log(`  No sessions directory found`);
+    log('');
+    return;
+  }
+
+  const recentFiles = findFiles(sessionsDir, '*.jsonl', { maxAge: 1 });
+
+  if (recentFiles.length === 0) {
+    log(`  No recent sessions found`);
+    log('');
+    return;
+  }
+
+  let errorCount = 0;
+  let timeoutCount = 0;
+  let jsonErrors = 0;
+  const errorPatterns = [];
+
+  for (const file of recentFiles.slice(0, 10)) {
+    // Check last 10 sessions
+    try {
+      const content = readFile(file.path);
+      const lines = content.split('\n').filter(Boolean);
+
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line);
+          // Look for error patterns
+          if (entry.error || (entry.type && entry.type.includes('error'))) {
+            errorCount++;
+            if (entry.error && !errorPatterns.includes(entry.error.slice(0, 50))) {
+              errorPatterns.push(entry.error.slice(0, 50));
+            }
+          }
+          if (entry.timeout || (entry.message && entry.message.includes('timeout'))) {
+            timeoutCount++;
+          }
+        } catch {
+          jsonErrors++;
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  if (errorCount === 0 && timeoutCount === 0 && jsonErrors === 0) {
+    log(`  ${OK} No errors found in recent sessions`);
+  } else {
+    if (errorCount > 0) {
+      log(`  ${WARN} ${errorCount} errors found`);
+      errorPatterns.slice(0, 3).forEach((pattern) => {
+        log(`      - ${pattern}...`);
+      });
+    }
+    if (timeoutCount > 0) {
+      log(`  ${WARN} ${timeoutCount} timeouts found`);
+      addRecommendation('Check hook timeout settings in hooks.json');
+    }
+    if (jsonErrors > 0) {
+      log(`  ${WARN} ${jsonErrors} JSON parse errors in session files`);
+      addRecommendation('Some session files may be corrupted');
+    }
+  }
+
+  log('');
+}
+
+// MCP Connectivity Check
+function checkMCPs() {
+  log('Checking MCPs...');
+
+  const settingsFile = path.join(getClaudeDir(), 'settings.json');
+  if (!fs.existsSync(settingsFile)) {
+    log(`  ${WARN} No settings.json found - MCPs not configured`);
+    addRecommendation('Configure MCPs in ~/.claude/settings.json');
+    log('');
+    return;
+  }
+
+  try {
+    const content = readFile(settingsFile);
+    const settings = JSON.parse(content);
+
+    if (!settings.mcpServers || Object.keys(settings.mcpServers).length === 0) {
+      log(`  ${WARN} No MCPs configured`);
+      addRecommendation('Add MCP servers to ~/.claude/settings.json');
+      log('');
+      return;
+    }
+
+    for (const [name, config] of Object.entries(settings.mcpServers)) {
+      // We can't actually test connectivity without running the MCP
+      // So we just verify the configuration looks valid
+      if (config.command || config.url) {
+        log(`  ${padRight(name + ':', 20)} ${OK} Configured`);
+      } else {
+        log(`  ${padRight(name + ':', 20)} ${WARN} Missing command or url`);
+        addRecommendation(`Check ${name} MCP configuration`);
+      }
+    }
+  } catch (err) {
+    log(`  ${FAIL} Cannot parse settings.json: ${err.message}`);
+    addRecommendation('Fix JSON syntax in ~/.claude/settings.json');
+  }
+
+  log('');
+}
+
+// Common Misconfigurations
+function checkCommonIssues() {
+  log('Checking common issues...');
+
+  // Check for .env file
+  const envFile = path.join(getClaudeDir(), '.env');
+  if (!fs.existsSync(envFile)) {
+    log(`  ${WARN} No ~/.claude/.env file found`);
+    addRecommendation('Create ~/.claude/.env with required credentials');
+  } else {
+    log(`  ${padRight('.env file:', 20)} ${OK} Found`);
+  }
+
+  // Check tutorial progress file
+  const milestonesFile = path.join(getClaudeDir(), 'onboarding', 'milestones.json');
+  if (fs.existsSync(milestonesFile)) {
+    try {
+      const content = readFile(milestonesFile);
+      const milestones = JSON.parse(content);
+      const completed = Object.values(milestones).filter((v) => v === true).length;
+      log(`  ${padRight('Tutorial progress:', 20)} ${OK} ${completed} milestones completed`);
+    } catch {
+      log(`  ${padRight('Tutorial progress:', 20)} ${WARN} Invalid milestones file`);
+    }
+  } else {
+    log(`  ${padRight('Tutorial progress:', 20)} ${WARN} Not started`);
+    addRecommendation('Run /tutorial to start the tutorial');
+  }
+
+  // Check git status
+  try {
+    const { execSync } = require('child_process');
+    execSync('git rev-parse --git-dir', { stdio: 'pipe' });
+    const upstream = execSync('git remote -v', { encoding: 'utf8' });
+    if (upstream.includes('upstream')) {
+      log(`  ${padRight('Git upstream:', 20)} ${OK} Configured`);
+    } else {
+      log(`  ${padRight('Git upstream:', 20)} ${WARN} No upstream remote`);
+      addRecommendation('Add upstream remote: git remote add upstream [central-repo-url]');
+    }
+  } catch {
+    log(`  ${padRight('Git repo:', 20)} ${WARN} Not a git repository`);
+  }
+
+  log('');
+}
+
+function printRecommendations() {
+  log('─'.repeat(50));
+  log('');
+
+  if (recommendations.length === 0) {
+    log('DIAGNOSIS: All checks passed');
+    log('');
+    log('No issues found. System appears healthy.');
+  } else {
+    log(`DIAGNOSIS: ${recommendations.length} issue(s) found`);
+    log('');
+    log('Recommendations:');
+    recommendations.forEach((rec, i) => {
+      log(`  ${i + 1}. ${rec}`);
+    });
+  }
+
+  log('');
+}
+
+function runDiagnose(options = {}) {
+  const { config, permissions, errors, mcp } = options;
+  const runAll = !config && !permissions && !errors && !mcp;
+
+  log('');
+  log('Running diagnostics...');
+  log('');
+
+  if (runAll || config) checkConfigurations();
+  if (runAll || permissions) checkPermissions();
+  if (runAll || errors) checkRecentErrors();
+  if (runAll || mcp) checkMCPs();
+  if (runAll) checkCommonIssues();
+
+  printRecommendations();
+
+  // Exit with appropriate code for CI/CD
+  process.exit(recommendations.length > 0 ? 1 : 0);
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+const options = {
+  config: args.includes('--config'),
+  permissions: args.includes('--permissions'),
+  errors: args.includes('--errors'),
+  mcp: args.includes('--mcp'),
+};
+
+runDiagnose(options);

package/scripts/doc-freshness.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Documentation Freshness Checker
+ * Identifies stale documentation files that haven't been modified recently.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const failOnStale = args.find((a) => a.startsWith('--fail-on-stale='));
+const staleThresholdDays = failOnStale ? parseInt(failOnStale.split('=')[1], 10) : 90;
+const jsonOutput = args.includes('--json');
+const verbose = args.includes('--verbose');
+
+/**
+ * Get all markdown files recursively
+ */
+function getMarkdownFiles(dir, files = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip node_modules, .git, archived
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '_archived') {
+        continue;
+      }
+      getMarkdownFiles(fullPath, files);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Check for TODO/PLACEHOLDER markers
+ */
+function hasPlaceholders(content) {
+  const markers = ['TODO:', 'PLACEHOLDER', 'FIXME:', 'TBD:', 'XXX:'];
+  return markers.some((m) => content.includes(m));
+}
+
+/**
+ * Get file modification date
+ */
+function getModDate(file) {
+  const stats = fs.statSync(file);
+  return stats.mtime;
+}
+
+/**
+ * Calculate days since modification
+ */
+function daysSince(date) {
+  const now = new Date();
+  const diff = now - date;
+  return Math.floor(diff / (1000 * 60 * 60 * 24));
+}
+
+// Get all markdown files
+const markdownFiles = getMarkdownFiles(ROOT);
+const now = new Date();
+
+// Analyze each file
+const results = {
+  total: markdownFiles.length,
+  stale: [],
+  hasPlaceholders: [],
+  recent: [],
+  byAge: {
+    last7Days: 0,
+    last30Days: 0,
+    last90Days: 0,
+    older: 0,
+  },
+};
+
+for (const file of markdownFiles) {
+  const relativePath = path.relative(ROOT, file);
+  const content = fs.readFileSync(file, 'utf8');
+  const modDate = getModDate(file);
+  const days = daysSince(modDate);
+
+  // Categorize by age
+  if (days <= 7) {
+    results.byAge.last7Days++;
+    results.recent.push({ file: relativePath, days });
+  } else if (days <= 30) {
+    results.byAge.last30Days++;
+  } else if (days <= 90) {
+    results.byAge.last90Days++;
+  } else {
+    results.byAge.older++;
+    results.stale.push({
+      file: relativePath,
+      days,
+      lastModified: modDate.toISOString().split('T')[0],
+    });
+  }
+
+  // Check for placeholders
+  if (hasPlaceholders(content)) {
+    results.hasPlaceholders.push({ file: relativePath });
+  }
+}
+
+// Sort stale by age (oldest first)
+results.stale.sort((a, b) => b.days - a.days);
+
+// Output results
+if (jsonOutput) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  console.log('\n=== Documentation Freshness Report ===\n');
+  console.log(`Total files: ${results.total}`);
+  console.log(`\nAge Distribution:`);
+  console.log(`  Last 7 days:   ${results.byAge.last7Days}`);
+  console.log(`  Last 30 days:  ${results.byAge.last30Days}`);
+  console.log(`  Last 90 days:  ${results.byAge.last90Days}`);
+  console.log(`  Older:         ${results.byAge.older}`);
+
+  if (results.stale.length > 0) {
+    console.log(`\n\u26A0  Stale Files (>90 days):`);
+    const displayCount = verbose ? results.stale.length : Math.min(10, results.stale.length);
+    for (let i = 0; i < displayCount; i++) {
+      const { file, days, lastModified } = results.stale[i];
+      console.log(`  - ${file} (${days} days old, last: ${lastModified})`);
+    }
+    if (!verbose && results.stale.length > 10) {
+      console.log(`  ... and ${results.stale.length - 10} more (use --verbose to see all)`);
+    }
+  }
+
+  if (results.hasPlaceholders.length > 0) {
+    console.log(`\n\u26A0  Files with TODO/PLACEHOLDER markers:`);
+    for (const { file } of results.hasPlaceholders.slice(0, 10)) {
+      console.log(`  - ${file}`);
+    }
+    if (results.hasPlaceholders.length > 10) {
+      console.log(`  ... and ${results.hasPlaceholders.length - 10} more`);
+    }
+  }
+
+  if (results.recent.length > 0 && verbose) {
+    console.log(`\n\u2713 Recently Updated (last 7 days):`);
+    for (const { file, days } of results.recent.slice(0, 10)) {
+      console.log(`  - ${file} (${days} days ago)`);
+    }
+  }
+
+  console.log('\n');
+}
+
+// Exit with error if --fail-on-stale is set and there are stale files
+if (failOnStale && results.stale.length > 0) {
+  const criticalStale = results.stale.filter((f) => f.days > staleThresholdDays);
+  if (criticalStale.length > 0) {
+    console.error(
+      `\u2717 Found ${criticalStale.length} files older than ${staleThresholdDays} days`
+    );
+    process.exit(1);
+  }
+}
+
+process.exit(0);