@shaykec/claude-teach 0.2.0

package/src/cli.js

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import chalk from 'chalk';
+import { buildRegistry, loadRegistry, getModule } from './registry.js';
+import { loadProgress, saveProgress, getStats } from './progress.js';
+import { getBelt, formatDashboard, suggestNext } from './gamification.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = resolve(__dirname, '..', '..', '..');
+
+const program = new Command();
+
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
+
+program
+  .name('claude-teach')
+  .description(`Socratic AI teaching platform with gamification and visual ecosystem.
+
+  Learn through guided dialogue — the AI asks YOU questions, tracks your
+  progress with XP and belt ranks, and enhances lessons with browser-based
+  diagrams, interactive quizzes, and code playgrounds.
+
+Examples:
+  $ claude-teach list                          List available modules
+  $ claude-teach list --difficulty beginner     Filter by difficulty
+  $ claude-teach get git                        Start the Git walkthrough
+  $ claude-teach get git --quick                Show Git quick reference
+  $ claude-teach stats                          View your XP and belt progress
+  $ claude-teach install user/my-pack           Install a module pack from GitHub
+  $ claude-teach search docker                  Search registries for packs
+  $ claude-teach author init my-pack            Scaffold a new module pack
+  $ claude-teach author validate ./my-pack      Validate a pack
+  $ claude-teach serve                          Start the bridge server for visuals`)
+  .version(pkg.version);
+
+// =====================================================================
+//  Learning commands
+// =====================================================================
+
+// --- list ---
+program
+  .command('list')
+  .description('List available learning modules (filter with --category, --difficulty, --tag, --source)')
+  .option('-c, --category <category>', 'Filter by category')
+  .option('-d, --difficulty <level>', 'Filter by difficulty (beginner|intermediate|advanced)')
+  .option('-t, --tag <tag>', 'Filter by tag')
+  .option('-s, --source <source>', 'Filter by source (built-in|pack:<name>|local)')
+  .action(async (opts) => {
+    const registry = await loadRegistry(ROOT);
+    let modules = registry.modules;
+
+    if (opts.category) {
+      modules = modules.filter(m => m.category === opts.category);
+    }
+    if (opts.difficulty) {
+      modules = modules.filter(m => m.difficulty === opts.difficulty);
+    }
+    if (opts.tag) {
+      modules = modules.filter(m => m.tags?.includes(opts.tag));
+    }
+    if (opts.source) {
+      modules = modules.filter(m => m.source === opts.source);
+    }
+
+    if (modules.length === 0) {
+      console.log('No modules found matching your filters.');
+      return;
+    }
+
+    const progress = loadProgress(ROOT);
+    const difficultyIcon = { beginner: '🌱', intermediate: '🌿', advanced: '🌳' };
+
+    console.log(`\n  Available Modules (${modules.length})\n`);
+    for (const mod of modules) {
+      const icon = difficultyIcon[mod.difficulty] || ' ';
+      const status = progress.modules?.[mod.slug]?.status;
+      const statusMark = status === 'completed' ? ' ✓' : status === 'in-progress' ? ' ◐' : '';
+      const caps = [];
+      if (mod.capabilities.includes('walkthrough')) caps.push('guided');
+      if (mod.capabilities.includes('exercises')) caps.push('exercises');
+      if (mod.capabilities.includes('quiz')) caps.push('quiz');
+      if (mod.capabilities.includes('quick-ref')) caps.push('quick');
+      const capsStr = caps.length ? ` [${caps.join(', ')}]` : '';
+      const sourceTag = mod.source !== 'built-in' ? chalk.dim(` (${mod.source})`) : '';
+      console.log(`  ${icon} ${mod.slug}${statusMark} — ${mod.title}${capsStr}${sourceTag}`);
+    }
+    console.log();
+  });
+
+// --- get ---
+program
+  .command('get <module>')
+  .description('Get module content — walkthrough by default, or --quick, --quiz-only, --status, --reset')
+  .option('--quick', 'Show quick reference')
+  .option('--quiz-only', 'Run quiz only')
+  .option('--status', 'Show progress for this module')
+  .option('--reset', 'Reset progress for this module')
+  .action(async (slug, opts) => {
+    const registry = await loadRegistry(ROOT);
+    const mod = getModule(registry, slug);
+    if (!mod) {
+      console.error(`Module "${slug}" not found. Run "claude-teach list" to see available modules.`);
+      process.exit(1);
+    }
+
+    if (opts.status) {
+      const progress = loadProgress(ROOT);
+      const entry = progress.modules?.[slug];
+      if (!entry) {
+        console.log(`No progress recorded for "${slug}".`);
+      } else {
+        console.log(JSON.stringify(entry, null, 2));
+      }
+      return;
+    }
+
+    if (opts.reset) {
+      const progress = loadProgress(ROOT);
+      delete progress.modules?.[slug];
+      saveProgress(ROOT, progress);
+      console.log(`Progress reset for "${slug}".`);
+      return;
+    }
+
+    const modulePath = mod._path;
+
+    if (opts.quick) {
+      const quickPath = join(modulePath, 'quick-ref.md');
+      if (!existsSync(quickPath)) {
+        console.error(`No quick reference available for "${slug}".`);
+        process.exit(1);
+      }
+      console.log(readFileSync(quickPath, 'utf-8'));
+      return;
+    }
+
+    if (opts.quizOnly) {
+      const quizPath = join(modulePath, 'quiz.md');
+      if (!existsSync(quizPath)) {
+        console.error(`No quiz available for "${slug}".`);
+        process.exit(1);
+      }
+      console.log(readFileSync(quizPath, 'utf-8'));
+      return;
+    }
+
+    // Default: walkthrough if available, else content
+    const walkthroughPath = join(modulePath, 'walkthrough.md');
+    const contentPath = join(modulePath, 'content.md');
+    if (existsSync(walkthroughPath)) {
+      console.log(readFileSync(walkthroughPath, 'utf-8'));
+    } else if (existsSync(contentPath)) {
+      console.log(readFileSync(contentPath, 'utf-8'));
+    } else {
+      console.error(`No content found for module "${slug}".`);
+      process.exit(1);
+    }
+  });
+
+// --- stats ---
+program
+  .command('stats')
+  .description('Show gamification dashboard — XP, belt, progress')
+  .action(async () => {
+    const progress = loadProgress(ROOT);
+    const registry = await loadRegistry(ROOT);
+    const dashboard = formatDashboard(progress, registry);
+    console.log(dashboard);
+  });
+
+// --- level-up ---
+program
+  .command('level-up')
+  .description('See your belt roadmap and get suggestions for what to learn next')
+  .action(async () => {
+    const progress = loadProgress(ROOT);
+    const registry = await loadRegistry(ROOT);
+    const suggestion = suggestNext(progress, registry);
+    console.log(suggestion);
+  });
+
+// =====================================================================
+//  Visual Ecosystem commands
+// =====================================================================
+
+// --- serve (bridge server) ---
+program
+  .command('serve')
+  .description('Start the bridge server for visual canvas — diagrams, quizzes, dashboard (default port: 3456)')
+  .option('-p, --port <port>', 'Port number', '3456')
+  .action(async (opts) => {
+    const { startServer } = await import('@shaykec/bridge');
+    const progress = loadProgress(ROOT);
+    startServer({
+      port: parseInt(opts.port, 10),
+      progressProvider: {
+        getProgress: () => loadProgress(ROOT),
+      },
+      onTierChange: (oldTier, newTier) => {
+        const labels = { 1: 'Full', 2: 'Canvas', 3: 'Terminal' };
+        console.log(`  Tier changed: ${labels[oldTier]} -> ${labels[newTier]}`);
+      },
+    });
+  });
+
+// --- inbox ---
+program
+  .command('inbox')
+  .description('Show content captured from the browser bridge')
+  .action(async () => {
+    const { showInbox } = await import('./bridge-server.js');
+    showInbox();
+  });
+
+// =====================================================================
+//  System commands
+// =====================================================================
+
+// --- registry:build ---
+program
+  .command('registry:build')
+  .description('Rebuild the module registry from all sources (built-in, packs, local)')
+  .action(async () => {
+    const registry = await buildRegistry(ROOT);
+    const count = registry.modules.length;
+    const sources = {};
+    for (const m of registry.modules) {
+      const key = m.source.startsWith('pack:') ? 'pack' : m.source;
+      sources[key] = (sources[key] || 0) + 1;
+    }
+    console.log(chalk.green(`Registry rebuilt: ${count} module(s).`));
+    for (const [src, n] of Object.entries(sources)) {
+      console.log(`  ${src}: ${n}`);
+    }
+  });
+
+// =====================================================================
+//  Marketplace commands — install, manage, and discover module packs
+// =====================================================================
+
+// --- install ---
+program
+  .command('install <url>')
+  .description('Install a module pack from a git URL or GitHub shorthand (e.g., user/repo)')
+  .action(async (url) => {
+    try {
+      const { installPack } = await import('./marketplace.js');
+      await installPack(url);
+      // Rebuild registry after install
+      await buildRegistry(ROOT);
+      console.log(chalk.green('Registry rebuilt.'));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// --- packs ---
+program
+  .command('packs')
+  .description('List installed module packs')
+  .action(async () => {
+    try {
+      const { listPacks } = await import('./marketplace.js');
+      const packs = await listPacks();
+
+      if (packs.length === 0) {
+        console.log('No module packs installed.');
+        console.log(`  Install one with: ${chalk.cyan('claude-teach install <url>')}`);
+        return;
+      }
+
+      console.log(`\n  Installed Packs (${packs.length})\n`);
+      for (const pack of packs) {
+        console.log(`  ${chalk.bold(pack.name)} v${pack.version} — ${pack.description || '(no description)'}`);
+        console.log(`    Author: ${pack.author || 'unknown'}  |  Modules: ${pack.modules.length}`);
+        console.log(`    Path: ${chalk.dim(pack.path)}`);
+        console.log();
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// --- update ---
+program
+  .command('update <pack>')
+  .description('Update an installed module pack (git pull)')
+  .action(async (packName) => {
+    try {
+      const { updatePack } = await import('./marketplace.js');
+      await updatePack(packName);
+      await buildRegistry(ROOT);
+      console.log(chalk.green('Registry rebuilt.'));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// --- remove ---
+program
+  .command('remove <pack>')
+  .description('Remove an installed module pack')
+  .action(async (packName) => {
+    try {
+      const { removePack } = await import('./marketplace.js');
+      await removePack(packName);
+      await buildRegistry(ROOT);
+      console.log(chalk.green('Registry rebuilt.'));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// --- search ---
+program
+  .command('search <query>')
+  .description('Search configured registries for module packs')
+  .action(async (query) => {
+    try {
+      const { searchPacks } = await import('./marketplace.js');
+      const results = await searchPacks(query);
+
+      if (results.length === 0) {
+        console.log(`No packs found for "${query}".`);
+        return;
+      }
+
+      console.log(`\n  Search Results (${results.length})\n`);
+      for (const pack of results) {
+        console.log(`  ${chalk.bold(pack.name)} — ${pack.description || '(no description)'}`);
+        if (pack.author) console.log(`    Author: ${pack.author}`);
+        if (pack.tags?.length) console.log(`    Tags: ${pack.tags.join(', ')}`);
+        if (pack.repo) console.log(`    Install: ${chalk.cyan(`claude-teach install ${pack.repo}`)}`);
+        console.log(`    Registry: ${chalk.dim(pack.registry)}`);
+        console.log();
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// --- registry subcommand ---
+const registryCmd = program
+  .command('registry')
+  .description('Manage module pack registries');
+
+registryCmd
+  .command('add <url>')
+  .description('Add a registry by URL or GitHub shorthand')
+  .action(async (url) => {
+    try {
+      const { addRegistry } = await import('./marketplace.js');
+      addRegistry(url);
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+registryCmd
+  .command('list')
+  .description('List configured registries')
+  .action(async () => {
+    try {
+      const { getRegistries } = await import('./marketplace.js');
+      const regs = getRegistries();
+
+      if (regs.length === 0) {
+        console.log('No registries configured.');
+        return;
+      }
+
+      console.log(`\n  Configured Registries (${regs.length})\n`);
+      for (const reg of regs) {
+        const status = reg.enabled !== false ? chalk.green('enabled') : chalk.dim('disabled');
+        console.log(`  ${chalk.bold(reg.name || '(unnamed)')} [${status}]`);
+        console.log(`    ${reg.url}`);
+        console.log();
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+registryCmd
+  .command('remove <name>')
+  .description('Remove a registry by name or URL')
+  .action(async (nameOrUrl) => {
+    try {
+      const { removeRegistry } = await import('./marketplace.js');
+      removeRegistry(nameOrUrl);
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// =====================================================================
+//  Authoring commands — create, validate, and preview learning modules
+// =====================================================================
+
+const authorCmd = program
+  .command('author')
+  .description('Module authoring tools — scaffold packs, add modules, validate, and preview');
+
+authorCmd
+  .command('init <name>')
+  .description('Scaffold a new module pack')
+  .action(async (name) => {
+    try {
+      const { initPack } = await import('./author.js');
+      await initPack(name);
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+authorCmd
+  .command('add <pack-and-module>')
+  .description('Add a module to a pack (format: pack-path/module-name)')
+  .action(async (packAndModule) => {
+    try {
+      const slashIdx = packAndModule.lastIndexOf('/');
+      if (slashIdx === -1) {
+        console.error(chalk.red('Usage: claude-teach author add <pack-path>/<module-name>'));
+        process.exit(1);
+      }
+      const packPath = packAndModule.slice(0, slashIdx);
+      const moduleName = packAndModule.slice(slashIdx + 1);
+      if (!packPath || !moduleName) {
+        console.error(chalk.red('Usage: claude-teach author add <pack-path>/<module-name>'));
+        process.exit(1);
+      }
+
+      const { addModule } = await import('./author.js');
+      await addModule(packPath, moduleName);
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+authorCmd
+  .command('validate <path>')
+  .description('Validate a module pack')
+  .action(async (packPath) => {
+    try {
+      const { validatePack } = await import('./author.js');
+      // Provide built-in slugs for prerequisite validation
+      const registry = await loadRegistry(ROOT);
+      const builtinSlugs = registry.modules
+        .filter(m => m.source === 'built-in')
+        .map(m => m.slug);
+
+      const result = await validatePack(packPath, builtinSlugs);
+
+      if (result.errors.length > 0) {
+        console.log(chalk.red(`\n  Errors (${result.errors.length}):\n`));
+        for (const err of result.errors) {
+          console.log(`  ${chalk.red('✗')} ${err}`);
+        }
+      }
+
+      if (result.warnings.length > 0) {
+        console.log(chalk.yellow(`\n  Warnings (${result.warnings.length}):\n`));
+        for (const warn of result.warnings) {
+          console.log(`  ${chalk.yellow('!')} ${warn}`);
+        }
+      }
+
+      if (result.valid) {
+        console.log(chalk.green('\n  Pack is valid.\n'));
+      } else {
+        console.log(chalk.red('\n  Pack has errors. Fix them and try again.\n'));
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+authorCmd
+  .command('preview <path>')
+  .description('Preview a module locally (adds to registry temporarily)')
+  .action(async (modulePath) => {
+    try {
+      const { previewModule } = await import('./author.js');
+      await previewModule(modulePath);
+      // Rebuild registry so the previewed module appears
+      await buildRegistry(ROOT);
+      console.log(chalk.green('Registry rebuilt.'));
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/gamification.js

@@ -0,0 +1,176 @@
+/**
+ * Gamification engine — XP scoring, belt thresholds, level progression.
+ * Ported from claude-code-guide's game-mode + level-up skills.
+ */
+
+export const BELTS = [
+  { name: 'White',  minXP: 0,    badge: '⬜' },
+  { name: 'Yellow', minXP: 50,   badge: '🟨' },
+  { name: 'Green',  minXP: 150,  badge: '🟩' },
+  { name: 'Blue',   minXP: 400,  badge: '🟦' },
+  { name: 'Purple', minXP: 800,  badge: '🟪' },
+  { name: 'Brown',  minXP: 1500, badge: '🟫' },
+  { name: 'Black',  minXP: 3000, badge: '⬛' },
+];
+
+/**
+ * Get the current belt for a given XP total.
+ */
+export function getBelt(xp) {
+  let belt = BELTS[0];
+  for (const b of BELTS) {
+    if (xp >= b.minXP) belt = b;
+  }
+
+  // Black belt dans
+  if (xp >= 3000) {
+    const dans = [
+      { dan: 1, minXP: 3000 },
+      { dan: 2, minXP: 6000 },
+      { dan: 3, minXP: 12000 },
+      { dan: 4, minXP: 24000 },
+      { dan: 5, minXP: 48000 },
+    ];
+    let currentDan = 0;
+    for (const d of dans) {
+      if (xp >= d.minXP) currentDan = d.dan;
+    }
+    if (currentDan > 0) {
+      return { ...belt, dan: currentDan, display: `⬛ Black Belt (${ordinal(currentDan)} Dan)` };
+    }
+  }
+
+  return { ...belt, display: `${belt.badge} ${belt.name} Belt` };
+}
+
+/**
+ * Get the next belt target.
+ */
+export function getNextBelt(xp) {
+  for (const b of BELTS) {
+    if (xp < b.minXP) return b;
+  }
+  // Already at Black — show next dan
+  const dans = [6000, 12000, 24000, 48000];
+  for (const threshold of dans) {
+    if (xp < threshold) return { name: 'Black (next Dan)', minXP: threshold, badge: '⬛' };
+  }
+  return null; // Maxed out
+}
+
+/**
+ * Format a full dashboard string.
+ */
+export function formatDashboard(progress, registry) {
+  const xp = progress.user?.xp || 0;
+  const belt = getBelt(xp);
+  const next = getNextBelt(xp);
+  const modulesCompleted = progress.user?.modules_completed || 0;
+  const totalModules = registry?.modules?.length || 0;
+
+  let out = `\n  ╔══════════════════════════════════════╗\n`;
+  out += `  ║       ClaudeTeach Dashboard          ║\n`;
+  out += `  ╠══════════════════════════════════════╣\n`;
+  out += `  ║  ${belt.display.padEnd(35)}║\n`;
+  out += `  ║  XP: ${String(xp).padEnd(31)}║\n`;
+
+  if (next) {
+    const remaining = next.minXP - xp;
+    const progressBar = makeProgressBar(xp, belt.minXP, next.minXP, 20);
+    out += `  ║  Next: ${next.badge} ${next.name} (${remaining} XP to go)`.padEnd(39) + `║\n`;
+    out += `  ║  ${progressBar.padEnd(35)}║\n`;
+  }
+
+  out += `  ║  Modules: ${modulesCompleted}/${totalModules} completed`.padEnd(39) + `║\n`;
+  out += `  ╚══════════════════════════════════════╝\n`;
+
+  // Per-module breakdown
+  if (progress.modules && Object.keys(progress.modules).length > 0) {
+    out += `\n  Module Progress:\n`;
+    for (const [slug, data] of Object.entries(progress.modules)) {
+      const statusIcon = data.status === 'completed' ? '✓' : '◐';
+      out += `    ${statusIcon} ${slug} — ${data.xp_earned || 0} XP`;
+      if (data.quiz_score) out += ` (quiz: ${data.quiz_score})`;
+      out += `\n`;
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Suggest the next module to learn based on progress.
+ */
+export function suggestNext(progress, registry) {
+  const completedSlugs = new Set(
+    Object.entries(progress.modules || {})
+      .filter(([_, v]) => v.status === 'completed')
+      .map(([k]) => k)
+  );
+
+  const inProgressSlugs = Object.entries(progress.modules || {})
+    .filter(([_, v]) => v.status === 'in-progress')
+    .map(([k]) => k);
+
+  const xp = progress.user?.xp || 0;
+  const belt = getBelt(xp);
+  const next = getNextBelt(xp);
+
+  let out = `\n  ${belt.display}\n`;
+  out += `  Total XP: ${xp}\n`;
+  if (next) {
+    out += `  Next belt: ${next.badge} ${next.name} at ${next.minXP} XP (${next.minXP - xp} to go)\n`;
+  }
+
+  // In-progress modules first
+  if (inProgressSlugs.length > 0) {
+    out += `\n  Continue where you left off:\n`;
+    for (const slug of inProgressSlugs) {
+      const mod = registry.modules?.find(m => m.slug === slug);
+      const data = progress.modules[slug];
+      if (mod) {
+        out += `    → ${slug}: "${mod.title}"`;
+        if (data.walkthrough_step) out += ` (step ${data.walkthrough_step})`;
+        out += `\n`;
+      }
+    }
+  }
+
+  // Suggest uncompleted modules sorted by difficulty
+  const available = (registry.modules || [])
+    .filter(m => !completedSlugs.has(m.slug) && !inProgressSlugs.includes(m.slug))
+    .filter(m => {
+      // Check prerequisites
+      if (!m.prerequisites || m.prerequisites.length === 0) return true;
+      return m.prerequisites.every(p => completedSlugs.has(p));
+    });
+
+  const diffOrder = { beginner: 0, intermediate: 1, advanced: 2 };
+  available.sort((a, b) => (diffOrder[a.difficulty] || 0) - (diffOrder[b.difficulty] || 0));
+
+  if (available.length > 0) {
+    out += `\n  Recommended next:\n`;
+    const suggestions = available.slice(0, 3);
+    for (const mod of suggestions) {
+      const icon = { beginner: '🌱', intermediate: '🌿', advanced: '🌳' }[mod.difficulty] || ' ';
+      const xpInfo = mod.xp ? ` (${Object.values(mod.xp).reduce((a, b) => a + b, 0)} XP)` : '';
+      out += `    ${icon} ${mod.slug}: "${mod.title}"${xpInfo}\n`;
+    }
+  }
+
+  return out;
+}
+
+// --- helpers ---
+
+function makeProgressBar(current, rangeStart, rangeEnd, width) {
+  const pct = Math.min(1, Math.max(0, (current - rangeStart) / (rangeEnd - rangeStart)));
+  const filled = Math.round(pct * width);
+  return '[' + '█'.repeat(filled) + '░'.repeat(width - filled) + '] ' + Math.round(pct * 100) + '%';
+}
+
+function ordinal(n) {
+  const s = ['th', 'st', 'nd', 'rd'];
+  const v = n % 100;
+  return n + (s[(v - 20) % 10] || s[v] || s[0]);
+}