@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/tutorial-runner.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * Tutorial Runner - Visual Interactive Tutorial for Everything Claude Code
+ *
+ * Usage:
+ *   node scripts/tutorial-runner.js                 # Show status and current lesson
+ *   node scripts/tutorial-runner.js <lesson>        # Go to specific lesson (0-14)
+ *   node scripts/tutorial-runner.js status          # Show progress status
+ *   node scripts/tutorial-runner.js reset           # Reset all progress
+ *   node scripts/tutorial-runner.js complete <num>  # Mark lesson as complete
+ *   node scripts/tutorial-runner.js certificate     # Show completion certificate
+ *   node scripts/tutorial-runner.js stats           # Show usage statistics
+ *   node scripts/tutorial-runner.js --accessible    # Disable colors for accessibility
+ */
+
+const path = require('path');
+const fs = require('fs');
+const progress = require('./lib/tutorial-progress');
+const renderer = require('./lib/tutorial-renderer');
+const metrics = require('./lib/tutorial-metrics');
+
+// Lessons directory
+const LESSONS_DIR = path.join(__dirname, '..', 'skills', 'tutorial', 'lessons');
+
+/**
+ * Generate a unique certificate ID.
+ * @returns {string} Certificate ID
+ */
+function generateCertificateId() {
+  const date = new Date();
+  const year = date.getFullYear();
+  const random = Math.random().toString(36).substring(2, 6).toUpperCase();
+  return `ECC-${year}-${random}`;
+}
+
+/**
+ * Load lesson content from file.
+ * @param {number} lessonNum - Lesson number
+ * @returns {string|null} Lesson content or null
+ */
+function loadLessonContent(lessonNum) {
+  const lesson = progress.getLessonInfo(lessonNum);
+  if (!lesson) return null;
+
+  const filePath = path.join(LESSONS_DIR, lesson.file);
+  if (!fs.existsSync(filePath)) return null;
+
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+/**
+ * Extract commands from lesson content.
+ * @param {string} content - Lesson markdown content
+ * @returns {Array<string>} Array of command names
+ */
+function extractCommands(content) {
+  const commands = [];
+  const regex = /\/(\w+[-\w]*)/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const cmd = `/${match[1]}`;
+    if (!commands.includes(cmd)) {
+      commands.push(cmd);
+    }
+  }
+  return commands.slice(0, 5); // Limit to 5 for display
+}
+
+/**
+ * Show tutorial status.
+ */
+async function showStatus() {
+  await renderer.init();
+
+  const state = progress.loadProgress();
+
+  console.log('');
+  console.log(renderer.renderBanner());
+  console.log('');
+  console.log(renderer.renderProgressBar(state.completedLessons.length, progress.TOTAL_LESSONS));
+  console.log('');
+  console.log(renderer.renderLessonList(state, progress.LESSONS));
+  console.log('');
+
+  if (progress.isComplete(state)) {
+    console.log(renderer.renderSuccess('Tutorial complete!'));
+    console.log('  Terminal:    node scripts/tutorial-runner.js certificate');
+    console.log('  Claude Code: /tutorial certificate');
+  } else {
+    console.log('Next lesson:');
+    console.log(`  Terminal:    node scripts/tutorial-runner.js ${state.currentLesson}`);
+    console.log(`  Claude Code: /tutorial ${state.currentLesson}`);
+  }
+  console.log('');
+}
+
+/**
+ * Show a specific lesson.
+ * @param {number} lessonNum - Lesson number
+ */
+async function showLesson(lessonNum) {
+  await renderer.init();
+
+  const lesson = progress.getLessonInfo(lessonNum);
+  if (!lesson) {
+    console.error(
+      renderer.renderError(
+        `Invalid lesson number: ${lessonNum}. Valid: 0-${progress.TOTAL_LESSONS - 1}`
+      )
+    );
+    process.exit(1);
+  }
+
+  // Record metrics
+  metrics.recordLessonStart(lessonNum);
+
+  const state = progress.setCurrentLesson(lessonNum);
+
+  console.log('');
+  console.log(renderer.renderBanner());
+  console.log('');
+  console.log(renderer.renderProgressBar(state.completedLessons.length, progress.TOTAL_LESSONS));
+  console.log('');
+  console.log(renderer.renderLessonHeader(lesson));
+  console.log('');
+
+  const content = loadLessonContent(lessonNum);
+  if (content) {
+    // Output styled lesson content
+    console.log(renderer.renderLessonContent(content));
+  } else {
+    console.log(`Lesson file not found: ${lesson.file}`);
+  }
+
+  console.log('');
+  console.log('To mark complete:');
+  console.log(`  Terminal:    node scripts/tutorial-runner.js complete ${lessonNum}`);
+  console.log('  Claude Code: (automatic when exercise completed)');
+  console.log('');
+}
+
+/**
+ * Mark a lesson as complete.
+ * @param {number} lessonNum - Lesson number
+ */
+async function completeLesson(lessonNum) {
+  await renderer.init();
+
+  const lesson = progress.getLessonInfo(lessonNum);
+  if (!lesson) {
+    console.error(renderer.renderError(`Invalid lesson number: ${lessonNum}`));
+    process.exit(1);
+  }
+
+  // Record metrics
+  metrics.recordLessonEnd(lessonNum);
+
+  const state = progress.completeLesson(lessonNum);
+
+  const content = loadLessonContent(lessonNum);
+  const commands = content ? extractCommands(content) : [];
+
+  const nextLesson = lessonNum < progress.TOTAL_LESSONS ? lessonNum + 1 : null;
+
+  console.log('');
+  console.log(renderer.renderCompletionBadge(lesson, commands, nextLesson));
+  console.log('');
+
+  if (progress.isComplete(state)) {
+    metrics.markComplete();
+    console.log(renderer.renderSuccess('Congratulations! You completed all lessons!'));
+    console.log('Get your certificate:');
+    console.log('  Terminal:    node scripts/tutorial-runner.js certificate');
+    console.log('  Claude Code: /tutorial certificate');
+  }
+  console.log('');
+}
+
+/**
+ * Reset all progress.
+ */
+async function resetProgress() {
+  await renderer.init();
+
+  progress.resetProgress();
+  console.log('');
+  console.log(renderer.renderSuccess('Tutorial progress has been reset.'));
+  console.log('Start from beginning:');
+  console.log('  Terminal:    node scripts/tutorial-runner.js 0');
+  console.log('  Claude Code: /tutorial 0');
+  console.log('');
+}
+
+/**
+ * Show completion certificate.
+ */
+async function showCertificate() {
+  await renderer.init();
+
+  const state = progress.loadProgress();
+
+  if (!progress.isComplete(state)) {
+    console.error(renderer.renderError('Tutorial not complete. Complete all 15 lessons first.'));
+    console.log('');
+    console.log(renderer.renderProgressBar(state.completedLessons.length, progress.TOTAL_LESSONS));
+    console.log('');
+    process.exit(1);
+  }
+
+  const certId = generateCertificateId();
+
+  console.log('');
+  console.log(renderer.renderCertificate(state, certId));
+  console.log('');
+}
+
+/**
+ * Show resume prompt (for session-start hook).
+ */
+async function showResumePrompt() {
+  await renderer.init();
+
+  if (!progress.hasProgress()) {
+    return; // No progress to show
+  }
+
+  const state = progress.loadProgress();
+
+  if (progress.isComplete(state)) {
+    return; // Already complete
+  }
+
+  console.log('');
+  console.log(renderer.renderResumePrompt(state));
+  console.log('');
+}
+
+/**
+ * Show usage statistics.
+ */
+async function showStats() {
+  await renderer.init();
+
+  if (!metrics.hasMetrics()) {
+    console.log('');
+    console.log('No metrics data yet. Start a lesson to begin tracking.');
+    console.log('');
+    return;
+  }
+
+  const stats = metrics.getStats();
+
+  console.log('');
+  console.log('Tutorial Statistics:');
+  console.log('');
+  console.log(`  Total time:      ${stats.totalTime}`);
+  console.log(`  Sessions:        ${stats.totalSessions}`);
+  console.log(`  Lessons visited: ${stats.lessonsVisited}/${progress.TOTAL_LESSONS}`);
+
+  if (stats.mostVisited) {
+    const lessonInfo = progress.getLessonInfo(stats.mostVisited);
+    console.log(
+      `  Most visited:    Lesson ${stats.mostVisited}: ${lessonInfo.title} (${stats.mostVisitedCount} visits)`
+    );
+  }
+
+  console.log(`  Avg per lesson:  ${stats.averageTimePerLesson}`);
+  console.log('');
+
+  if (stats.completedAt) {
+    const completedDate = new Date(stats.completedAt).toLocaleDateString();
+    console.log(`  Completed:       ${completedDate}`);
+    console.log('');
+  }
+
+  // Show per-lesson breakdown if there's data
+  if (Object.keys(stats.lessonMetrics).length > 0) {
+    console.log('  Per-lesson breakdown:');
+    for (const [lessonNum, data] of Object.entries(stats.lessonMetrics)) {
+      const lessonInfo = progress.getLessonInfo(parseInt(lessonNum, 10));
+      const timeStr = metrics.formatTime(data.totalTimeMs);
+      console.log(`    Lesson ${lessonNum}: ${data.visits} visit(s), ${timeStr}`);
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  const args = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+
+  if (args.length === 0) {
+    await showStatus();
+    return;
+  }
+
+  const command = args[0].toLowerCase();
+
+  switch (command) {
+    case 'status':
+      await showStatus();
+      break;
+
+    case 'reset':
+      await resetProgress();
+      break;
+
+    case 'certificate':
+    case 'cert':
+      await showCertificate();
+      break;
+
+    case 'complete':
+      if (!args[1]) {
+        console.error('Usage: node scripts/tutorial-runner.js complete <lesson-number>');
+        process.exit(1);
+      }
+      await completeLesson(parseInt(args[1], 10));
+      break;
+
+    case 'resume':
+      await showResumePrompt();
+      break;
+
+    case 'stats':
+    case 'metrics':
+      await showStats();
+      break;
+
+    default: {
+      // Assume it's a lesson number
+      const lessonNum = parseInt(command, 10);
+      if (isNaN(lessonNum) || lessonNum < 0 || lessonNum >= progress.TOTAL_LESSONS) {
+        console.error(`Invalid command or lesson number: ${command}`);
+        console.error(`Valid lessons: 0-${progress.TOTAL_LESSONS - 1}`);
+        console.error('Commands: status, reset, complete <n>, certificate, stats');
+        process.exit(1);
+      }
+      await showLesson(lessonNum);
+      break;
+    }
+  }
+}
+
+// Run
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/scripts/validate-all.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Master Validation Orchestrator
+ * Runs all validation phases in sequence with proper error handling.
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const quickMode = args.includes('--quick');
+const verbose = args.includes('--verbose');
+const continueOnError = args.includes('--continue');
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  dim: '\x1b[2m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function header(message) {
+  console.log('\n' + '='.repeat(60));
+  log(message, 'blue');
+  console.log('='.repeat(60));
+}
+
+/**
+ * Run a command and return a promise
+ */
+function runCommand(command, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const proc = spawn(command, args, {
+      cwd: ROOT,
+      stdio: verbose ? 'inherit' : 'pipe',
+      shell: true,
+      ...options,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (!verbose && proc.stdout) {
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+    }
+
+    if (!verbose && proc.stderr) {
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+    }
+
+    proc.on('close', (code) => {
+      const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+      if (code === 0) {
+        resolve({ success: true, duration, stdout, stderr });
+      } else {
+        reject({ success: false, code, duration, stdout, stderr });
+      }
+    });
+
+    proc.on('error', (err) => {
+      reject({ success: false, error: err.message, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * Validation phases
+ */
+const phases = [
+  {
+    name: 'Environment Check',
+    command: 'npm',
+    args: ['run', 'verify:quick'],
+    required: true,
+    quick: true,
+  },
+  {
+    name: 'Plugin Structure Validation',
+    command: 'npm',
+    args: ['run', 'validate'],
+    required: true,
+    quick: true,
+  },
+  {
+    name: 'Full Test Suite',
+    command: 'npm',
+    args: ['test'],
+    required: true,
+    quick: false,
+  },
+  {
+    name: 'ESLint Check',
+    command: 'npm',
+    args: ['run', 'lint'],
+    required: true,
+    quick: false,
+  },
+  {
+    name: 'Prettier Format Check',
+    command: 'npm',
+    args: ['run', 'format'],
+    required: true,
+    quick: false,
+  },
+  {
+    name: 'Markdown Link Validation',
+    command: 'node',
+    args: ['tests/structure/links.test.js'],
+    required: true,
+    quick: false,
+  },
+  {
+    name: 'Documentation Freshness',
+    command: 'node',
+    args: ['scripts/doc-freshness.js'],
+    required: false,
+    quick: false,
+  },
+];
+
+async function main() {
+  log('\n\u2728 CloudStream Claude Code - Enterprise Validation\n', 'blue');
+  log(`Mode: ${quickMode ? 'Quick' : 'Full'}`, 'dim');
+  log(`Continue on error: ${continueOnError ? 'Yes' : 'No'}`, 'dim');
+
+  const results = [];
+  let hasFailure = false;
+
+  for (const phase of phases) {
+    // Skip non-quick phases in quick mode
+    if (quickMode && !phase.quick) {
+      continue;
+    }
+
+    header(`Phase: ${phase.name}`);
+
+    try {
+      const result = await runCommand(phase.command, phase.args);
+      log(`\u2713 ${phase.name} passed (${result.duration}s)`, 'green');
+      results.push({ phase: phase.name, success: true, duration: result.duration });
+    } catch (err) {
+      log(`\u2717 ${phase.name} failed`, 'red');
+      if (!verbose && err.stderr) {
+        console.log(colors.dim + err.stderr.slice(0, 500) + colors.reset);
+      }
+      results.push({ phase: phase.name, success: false, duration: err.duration });
+
+      if (phase.required) {
+        hasFailure = true;
+        if (!continueOnError) {
+          break;
+        }
+      }
+    }
+  }
+
+  // Summary
+  header('Validation Summary');
+
+  const passed = results.filter((r) => r.success).length;
+  const failed = results.filter((r) => !r.success).length;
+  const totalTime = results.reduce((sum, r) => sum + parseFloat(r.duration || 0), 0).toFixed(1);
+
+  for (const result of results) {
+    const icon = result.success ? '\u2713' : '\u2717';
+    const color = result.success ? 'green' : 'red';
+    log(`  ${icon} ${result.phase} (${result.duration}s)`, color);
+  }
+
+  console.log('\n' + '-'.repeat(40));
+  log(`Passed: ${passed}`, 'green');
+  if (failed > 0) log(`Failed: ${failed}`, 'red');
+  log(`Total time: ${totalTime}s`, 'dim');
+
+  if (hasFailure) {
+    log('\n\u2717 Validation FAILED', 'red');
+    process.exit(1);
+  } else {
+    log('\n\u2713 All validations PASSED', 'green');
+    process.exit(0);
+  }
+}
+
+main().catch((err) => {
+  console.error('Unexpected error:', err);
+  process.exit(1);
+});