@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/scripts/lib/tutorial-renderer.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+/**
+ * Tutorial visual rendering module.
+ * Provides rich terminal output for the interactive tutorial.
+ *
+ * Uses chalk, boxen, and figures for cross-platform styled output.
+ * Respects NO_COLOR environment variable for accessibility.
+ */
+
+// Dynamic imports for ESM modules (chalk, boxen, figures, ora)
+let chalk, boxen, figures, ora;
+
+/**
+ * Initialize ESM modules.
+ * Must be called before using any rendering functions.
+ */
+async function init() {
+  if (!chalk) {
+    chalk = (await import('chalk')).default;
+    boxen = (await import('boxen')).default;
+    figures = (await import('figures')).default;
+    ora = (await import('ora')).default;
+
+    // Force colors ON by default (Windows terminals often misdetect)
+    // User can still disable with NO_COLOR=1 or --no-color
+    if (!process.env.NO_COLOR && !process.argv.includes('--no-color')) {
+      chalk.level = 3; // Full truecolor support
+    }
+  }
+}
+
+/**
+ * Check if colors should be disabled.
+ * @returns {boolean} True if colors should be disabled
+ */
+function isAccessible() {
+  return (
+    process.env.NO_COLOR ||
+    process.env.TERM === 'dumb' ||
+    process.argv.includes('--no-color') ||
+    process.argv.includes('--accessible')
+  );
+}
+
+/**
+ * Get the appropriate checkmark symbol.
+ * @returns {string} Checkmark symbol
+ */
+function getCheck() {
+  return figures ? figures.tick : '✓';
+}
+
+/**
+ * Get the appropriate arrow symbol.
+ * @returns {string} Arrow symbol
+ */
+function getArrow() {
+  return figures ? figures.arrowRight : '→';
+}
+
+/**
+ * Get the appropriate circle symbol.
+ * @returns {string} Circle symbol
+ */
+function getCircle() {
+  return figures ? figures.circle : '○';
+}
+
+/**
+ * Render the welcome banner.
+ * @returns {string} Formatted banner
+ */
+function renderBanner() {
+  const title = 'EVERYTHING CLAUDE CODE TUTORIAL';
+  const subtitle = 'Learn the system in 15 interactive lessons';
+
+  if (isAccessible()) {
+    return ['═'.repeat(56), '', `  ${title}`, `  ${subtitle}`, '', '═'.repeat(56)].join('\n');
+  }
+
+  const content = [chalk.bold.cyan(title), chalk.dim(subtitle)].join('\n');
+
+  return boxen(content, {
+    padding: 1,
+    margin: 0,
+    borderStyle: 'double',
+    borderColor: 'cyan',
+    textAlignment: 'center',
+  });
+}
+
+/**
+ * Render a progress bar.
+ * @param {number} completed - Number of completed items
+ * @param {number} total - Total number of items
+ * @returns {string} Formatted progress bar
+ */
+function renderProgressBar(completed, total) {
+  const percent = Math.round((completed / total) * 100);
+  const width = 20;
+  const filled = Math.round((completed / total) * width);
+  const empty = width - filled;
+
+  const filledChar = '█';
+  const emptyChar = '░';
+
+  const bar = filledChar.repeat(filled) + emptyChar.repeat(empty);
+
+  if (isAccessible()) {
+    return `Progress: [${bar}] ${completed}/${total} lessons (${percent}%)`;
+  }
+
+  return `Progress: ${chalk.cyan('[')}${chalk.green(filledChar.repeat(filled))}${chalk.dim(emptyChar.repeat(empty))}${chalk.cyan(']')} ${completed}/${total} lessons ${chalk.dim(`(${percent}%)`)}`;
+}
+
+/**
+ * Render the lesson list with status indicators.
+ * @param {object} progress - Progress state from tutorial-progress
+ * @param {Array} lessons - Array of lesson info objects
+ * @returns {string} Formatted lesson list
+ */
+function renderLessonList(progress, lessons) {
+  const lines = [];
+
+  for (const lesson of lessons) {
+    const isCompleted = progress.completedLessons.includes(lesson.num);
+    const isCurrent = lesson.num === progress.currentLesson;
+
+    let indicator, style, suffix;
+
+    if (isCompleted) {
+      indicator = getCheck();
+      style = isAccessible() ? (s) => s : chalk.green;
+      suffix = '';
+    } else if (isCurrent) {
+      indicator = getArrow();
+      style = isAccessible() ? (s) => s : chalk.yellow.bold;
+      suffix = isAccessible() ? ' <- YOU ARE HERE' : chalk.dim(' ← YOU ARE HERE');
+    } else {
+      indicator = getCircle();
+      style = isAccessible() ? (s) => s : chalk.dim;
+      suffix = '';
+    }
+
+    lines.push(style(`  ${indicator} Lesson ${lesson.num}: ${lesson.title}${suffix}`));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render a lesson header.
+ * @param {object} lesson - Lesson info object
+ * @returns {string} Formatted lesson header
+ */
+function renderLessonHeader(lesson) {
+  const title = `LESSON ${lesson.num}: ${lesson.title.toUpperCase()}`;
+  const line = '━'.repeat(56);
+
+  if (isAccessible()) {
+    return [line, '', `  ${title}`, '', line].join('\n');
+  }
+
+  return [chalk.dim(line), '', chalk.bold.white(`  ${title}`), '', chalk.dim(line)].join('\n');
+}
+
+/**
+ * Render a completion badge for a lesson.
+ * @param {object} lesson - Lesson info object
+ * @param {Array} commandsLearned - Array of command names learned
+ * @param {number|null} nextLesson - Next lesson number or null if complete
+ * @returns {string} Formatted completion badge
+ */
+function renderCompletionBadge(lesson, commandsLearned, nextLesson) {
+  const check = getCheck();
+  const lines = [
+    `  ${check} LESSON ${lesson.num} COMPLETE!`,
+    '',
+    '  Commands learned:',
+    `  ${commandsLearned.map((c) => `• ${c}`).join('   ')}`,
+    '',
+  ];
+
+  if (nextLesson) {
+    lines.push('  Next:');
+    lines.push(`    Terminal:    node scripts/tutorial-runner.js ${nextLesson}`);
+    lines.push(`    Claude Code: /tutorial ${nextLesson}`);
+  } else {
+    lines.push('  Tutorial complete! Get certificate:');
+    lines.push('    Terminal:    node scripts/tutorial-runner.js certificate');
+    lines.push('    Claude Code: /tutorial certificate');
+  }
+
+  if (isAccessible()) {
+    return [
+      '┌' + '─'.repeat(58) + '┐',
+      ...lines.map((l) => '│' + l.padEnd(58) + '│'),
+      '└' + '─'.repeat(58) + '┘',
+    ].join('\n');
+  }
+
+  return boxen(lines.join('\n'), {
+    padding: { top: 0, bottom: 0, left: 0, right: 0 },
+    margin: 0,
+    borderStyle: 'round',
+    borderColor: 'green',
+  });
+}
+
+/**
+ * Render the completion certificate.
+ * @param {object} progress - Progress state
+ * @param {string} completionId - Unique certificate ID
+ * @returns {string} Formatted certificate
+ */
+function renderCertificate(progress, completionId) {
+  const completedDate = progress.completedAt
+    ? new Date(progress.completedAt).toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+      })
+    : new Date().toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+      });
+
+  const content = [
+    '',
+    '         CERTIFICATE OF COMPLETION',
+    '',
+    '  This certifies completion of the',
+    '  Everything Claude Code Tutorial',
+    '',
+    '  15/15 Lessons • 22 Commands • 13 Agents',
+    '',
+    `  Completed: ${completedDate}`,
+    `  ID: ${completionId}`,
+    '',
+  ].join('\n');
+
+  if (isAccessible()) {
+    const width = 58;
+    return [
+      '╔' + '═'.repeat(width) + '╗',
+      ...content.split('\n').map((l) => '║' + l.padEnd(width) + '║'),
+      '╚' + '═'.repeat(width) + '╝',
+    ].join('\n');
+  }
+
+  return boxen(content, {
+    padding: 1,
+    margin: 0,
+    borderStyle: 'double',
+    borderColor: 'yellow',
+    textAlignment: 'center',
+  });
+}
+
+/**
+ * Render a session resume prompt.
+ * @param {object} progress - Progress state
+ * @returns {string} Formatted resume prompt
+ */
+function renderResumePrompt(progress) {
+  const lastAccessed = new Date(progress.lastAccessed).toLocaleDateString();
+
+  const lines = [
+    'Tutorial in progress!',
+    '',
+    renderProgressBar(progress.completedLessons.length, 15),
+    '',
+    `Last accessed: ${lastAccessed}`,
+    'Resume:',
+    `  Terminal:    node scripts/tutorial-runner.js ${progress.currentLesson}`,
+    `  Claude Code: /tutorial ${progress.currentLesson}`,
+  ];
+
+  if (isAccessible()) {
+    return lines.join('\n');
+  }
+
+  return boxen(lines.join('\n'), {
+    padding: 1,
+    margin: 0,
+    borderStyle: 'round',
+    borderColor: 'blue',
+    title: 'Tutorial Progress',
+    titleAlignment: 'center',
+  });
+}
+
+/**
+ * Render lesson content with markdown styling.
+ * @param {string} content - Raw markdown content
+ * @returns {string} Styled content
+ */
+function renderLessonContent(content) {
+  if (isAccessible()) {
+    return content;
+  }
+
+  const lines = content.split('\n');
+  const styledLines = [];
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    // Code block toggle
+    if (line.startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      styledLines.push(chalk.dim(line));
+      continue;
+    }
+
+    // Inside code block - dim styling
+    if (inCodeBlock) {
+      styledLines.push(chalk.dim.cyan(line));
+      continue;
+    }
+
+    // H1 headers
+    if (line.startsWith('# ')) {
+      styledLines.push(chalk.bold.cyan(line));
+      continue;
+    }
+
+    // H2 headers
+    if (line.startsWith('## ')) {
+      styledLines.push(chalk.bold.yellow(line));
+      continue;
+    }
+
+    // H3 headers
+    if (line.startsWith('### ')) {
+      styledLines.push(chalk.bold.white(line));
+      continue;
+    }
+
+    // Blockquotes
+    if (line.startsWith('> ')) {
+      styledLines.push(chalk.italic.green(line));
+      continue;
+    }
+
+    // List items
+    if (line.match(/^[-*] /)) {
+      const styled = line
+        .replace(/^([-*]) /, chalk.cyan('• '))
+        .replace(/\*\*([^*]+)\*\*/g, (_, text) => chalk.bold(text))
+        .replace(/`([^`]+)`/g, (_, code) => chalk.cyan(code));
+      styledLines.push(styled);
+      continue;
+    }
+
+    // Table rows
+    if (line.startsWith('|')) {
+      styledLines.push(chalk.dim(line));
+      continue;
+    }
+
+    // Regular text - style inline elements
+    let styled = line
+      .replace(/\*\*([^*]+)\*\*/g, (_, text) => chalk.bold(text))
+      .replace(/`([^`]+)`/g, (_, code) => chalk.cyan(code));
+    styledLines.push(styled);
+  }
+
+  return styledLines.join('\n');
+}
+
+/**
+ * Render an error message.
+ * @param {string} message - Error message
+ * @returns {string} Formatted error
+ */
+function renderError(message) {
+  if (isAccessible()) {
+    return `ERROR: ${message}`;
+  }
+  return chalk.red(`${figures.cross} ${message}`);
+}
+
+/**
+ * Render a success message.
+ * @param {string} message - Success message
+ * @returns {string} Formatted success
+ */
+function renderSuccess(message) {
+  if (isAccessible()) {
+    return `SUCCESS: ${message}`;
+  }
+  return chalk.green(`${figures.tick} ${message}`);
+}
+
+/**
+ * Render a spinner (returns ora instance).
+ * @param {string} text - Spinner text
+ * @returns {object} Ora spinner instance
+ */
+function createSpinner(text) {
+  if (isAccessible()) {
+    // In accessible mode, just log the text
+    console.log(text);
+    return {
+      succeed: (msg) => console.log(`SUCCESS: ${msg || text}`),
+      fail: (msg) => console.log(`FAILED: ${msg || text}`),
+      stop: () => {},
+    };
+  }
+  return ora({ text, color: 'cyan' }).start();
+}
+
+module.exports = {
+  init,
+  isAccessible,
+  renderBanner,
+  renderProgressBar,
+  renderLessonList,
+  renderLessonHeader,
+  renderLessonContent,
+  renderCompletionBadge,
+  renderCertificate,
+  renderResumePrompt,
+  renderError,
+  renderSuccess,
+  createSpinner,
+  getCheck,
+  getArrow,
+  getCircle,
+};