@shaykec/claude-teach 0.2.0

package/src/progress.test.js

@@ -0,0 +1,360 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadProgress, saveProgress, recordXP, completeModule, updateWalkthroughStep, recordQuizScore, getStats } from './progress.js';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'teach-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+/* ================================================================== */
+/*  loadProgress                                                       */
+/* ================================================================== */
+
+describe('loadProgress', () => {
+  it('should return default progress when file does not exist', () => {
+    const progress = loadProgress(tmpDir);
+    expect(progress).toEqual({
+      user: { xp: 0, belt: 'white', modules_completed: 0 },
+      modules: {},
+    });
+  });
+
+  it('should return default progress when file is empty', () => {
+    fs.writeFileSync(path.join(tmpDir, '.teach-progress.yaml'), '', 'utf-8');
+    const progress = loadProgress(tmpDir);
+    expect(progress).toEqual({
+      user: { xp: 0, belt: 'white', modules_completed: 0 },
+      modules: {},
+    });
+  });
+
+  it('should return default progress when file has invalid YAML', () => {
+    fs.writeFileSync(path.join(tmpDir, '.teach-progress.yaml'), '{{invalid yaml: [', 'utf-8');
+    const progress = loadProgress(tmpDir);
+    expect(progress).toEqual({
+      user: { xp: 0, belt: 'white', modules_completed: 0 },
+      modules: {},
+    });
+  });
+
+  it('should load valid progress from file', () => {
+    const data = {
+      user: { xp: 500, belt: 'blue', modules_completed: 3 },
+      modules: {
+        git: { status: 'completed', xp_earned: 200 },
+      },
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, '.teach-progress.yaml'),
+      'user:\n  xp: 500\n  belt: blue\n  modules_completed: 3\nmodules:\n  git:\n    status: completed\n    xp_earned: 200\n',
+      'utf-8',
+    );
+    const progress = loadProgress(tmpDir);
+    expect(progress.user.xp).toBe(500);
+    expect(progress.user.belt).toBe('blue');
+    expect(progress.modules.git.status).toBe('completed');
+  });
+});
+
+/* ================================================================== */
+/*  saveProgress + loadProgress roundtrip                              */
+/* ================================================================== */
+
+describe('saveProgress + loadProgress roundtrip', () => {
+  it('should save and reload progress identically', () => {
+    const data = {
+      user: { xp: 1234, belt: 'purple', modules_completed: 5 },
+      modules: {
+        git: { status: 'completed', xp_earned: 200, quiz_score: '5/5' },
+        hooks: { status: 'in-progress', xp_earned: 50, walkthrough_step: 3 },
+      },
+    };
+    saveProgress(tmpDir, data);
+
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.user.xp).toBe(1234);
+    expect(loaded.user.belt).toBe('purple');
+    expect(loaded.user.modules_completed).toBe(5);
+    expect(loaded.modules.git.status).toBe('completed');
+    expect(loaded.modules.git.xp_earned).toBe(200);
+    expect(loaded.modules.git.quiz_score).toBe('5/5');
+    expect(loaded.modules.hooks.status).toBe('in-progress');
+    expect(loaded.modules.hooks.walkthrough_step).toBe(3);
+  });
+
+  it('should create the progress file on disk', () => {
+    const data = { user: { xp: 0 }, modules: {} };
+    saveProgress(tmpDir, data);
+    const filePath = path.join(tmpDir, '.teach-progress.yaml');
+    expect(fs.existsSync(filePath)).toBe(true);
+  });
+
+  it('should overwrite existing progress file', () => {
+    saveProgress(tmpDir, { user: { xp: 100 }, modules: {} });
+    saveProgress(tmpDir, { user: { xp: 999 }, modules: {} });
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.user.xp).toBe(999);
+  });
+});
+
+/* ================================================================== */
+/*  recordXP                                                           */
+/* ================================================================== */
+
+describe('recordXP', () => {
+  it('should add XP to user total for a new module', () => {
+    const result = recordXP(tmpDir, 'git', 'read', 25);
+    expect(result.user.xp).toBe(25);
+    expect(result.modules.git).toBeDefined();
+    expect(result.modules.git.xp_earned).toBe(25);
+  });
+
+  it('should create module entry with in-progress status when new', () => {
+    const result = recordXP(tmpDir, 'git', 'read', 10);
+    expect(result.modules.git.status).toBe('in-progress');
+    expect(result.modules.git.started).toBeDefined();
+  });
+
+  it('should accumulate XP on existing module', () => {
+    recordXP(tmpDir, 'git', 'read', 10);
+    const result = recordXP(tmpDir, 'git', 'walkthrough', 20);
+    expect(result.modules.git.xp_earned).toBe(30);
+    expect(result.user.xp).toBe(30);
+  });
+
+  it('should accumulate XP across different modules', () => {
+    recordXP(tmpDir, 'git', 'read', 10);
+    const result = recordXP(tmpDir, 'hooks', 'read', 15);
+    expect(result.user.xp).toBe(25);
+    expect(result.modules.git.xp_earned).toBe(10);
+    expect(result.modules.hooks.xp_earned).toBe(15);
+  });
+
+  it('should persist XP to disk', () => {
+    recordXP(tmpDir, 'git', 'read', 42);
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.user.xp).toBe(42);
+    expect(loaded.modules.git.xp_earned).toBe(42);
+  });
+
+  it('should update last_session date', () => {
+    const result = recordXP(tmpDir, 'git', 'read', 10);
+    const today = new Date().toISOString().split('T')[0];
+    expect(result.modules.git.last_session).toBe(today);
+  });
+
+  it('should count completed modules correctly', () => {
+    // First complete a module, then record XP on another
+    completeModule(tmpDir, 'git');
+    const result = recordXP(tmpDir, 'hooks', 'read', 10);
+    expect(result.user.modules_completed).toBe(1);
+  });
+});
+
+/* ================================================================== */
+/*  completeModule                                                     */
+/* ================================================================== */
+
+describe('completeModule', () => {
+  it('should set status to completed', () => {
+    const result = completeModule(tmpDir, 'git');
+    expect(result.modules.git.status).toBe('completed');
+  });
+
+  it('should set completion date', () => {
+    const result = completeModule(tmpDir, 'git');
+    const today = new Date().toISOString().split('T')[0];
+    expect(result.modules.git.completed).toBe(today);
+  });
+
+  it('should increment modules_completed count', () => {
+    completeModule(tmpDir, 'git');
+    const result = completeModule(tmpDir, 'hooks');
+    expect(result.user.modules_completed).toBe(2);
+  });
+
+  it('should create module entry if it did not exist', () => {
+    const result = completeModule(tmpDir, 'new-module');
+    expect(result.modules['new-module']).toBeDefined();
+    expect(result.modules['new-module'].status).toBe('completed');
+  });
+
+  it('should preserve existing module data when completing', () => {
+    recordXP(tmpDir, 'git', 'read', 25);
+    const result = completeModule(tmpDir, 'git');
+    expect(result.modules.git.xp_earned).toBe(25);
+    expect(result.modules.git.status).toBe('completed');
+  });
+
+  it('should persist completion to disk', () => {
+    completeModule(tmpDir, 'git');
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.modules.git.status).toBe('completed');
+  });
+});
+
+/* ================================================================== */
+/*  updateWalkthroughStep                                              */
+/* ================================================================== */
+
+describe('updateWalkthroughStep', () => {
+  it('should update the walkthrough step number', () => {
+    const result = updateWalkthroughStep(tmpDir, 'git', 3);
+    expect(result.modules.git.walkthrough_step).toBe(3);
+  });
+
+  it('should create module entry if it did not exist', () => {
+    const result = updateWalkthroughStep(tmpDir, 'new-mod', 1);
+    expect(result.modules['new-mod']).toBeDefined();
+    expect(result.modules['new-mod'].status).toBe('in-progress');
+    expect(result.modules['new-mod'].walkthrough_step).toBe(1);
+  });
+
+  it('should update last_session date', () => {
+    const result = updateWalkthroughStep(tmpDir, 'git', 2);
+    const today = new Date().toISOString().split('T')[0];
+    expect(result.modules.git.last_session).toBe(today);
+  });
+
+  it('should overwrite previous step number', () => {
+    updateWalkthroughStep(tmpDir, 'git', 1);
+    const result = updateWalkthroughStep(tmpDir, 'git', 5);
+    expect(result.modules.git.walkthrough_step).toBe(5);
+  });
+
+  it('should persist step to disk', () => {
+    updateWalkthroughStep(tmpDir, 'git', 7);
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.modules.git.walkthrough_step).toBe(7);
+  });
+
+  it('should preserve existing module data', () => {
+    recordXP(tmpDir, 'git', 'read', 20);
+    const result = updateWalkthroughStep(tmpDir, 'git', 4);
+    expect(result.modules.git.xp_earned).toBe(20);
+    expect(result.modules.git.walkthrough_step).toBe(4);
+  });
+});
+
+/* ================================================================== */
+/*  recordQuizScore                                                    */
+/* ================================================================== */
+
+describe('recordQuizScore', () => {
+  it('should record the quiz score string', () => {
+    const result = recordQuizScore(tmpDir, 'git', '4/5');
+    expect(result.modules.git.quiz_score).toBe('4/5');
+  });
+
+  it('should create module entry if it did not exist', () => {
+    const result = recordQuizScore(tmpDir, 'new-mod', '3/5');
+    expect(result.modules['new-mod']).toBeDefined();
+    expect(result.modules['new-mod'].status).toBe('in-progress');
+  });
+
+  it('should update last_session date', () => {
+    const result = recordQuizScore(tmpDir, 'git', '5/5');
+    const today = new Date().toISOString().split('T')[0];
+    expect(result.modules.git.last_session).toBe(today);
+  });
+
+  it('should overwrite previous quiz score', () => {
+    recordQuizScore(tmpDir, 'git', '2/5');
+    const result = recordQuizScore(tmpDir, 'git', '4/5');
+    expect(result.modules.git.quiz_score).toBe('4/5');
+  });
+
+  it('should persist score to disk', () => {
+    recordQuizScore(tmpDir, 'git', '5/5');
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.modules.git.quiz_score).toBe('5/5');
+  });
+
+  it('should handle numeric score as well', () => {
+    const result = recordQuizScore(tmpDir, 'git', 80);
+    expect(result.modules.git.quiz_score).toBe(80);
+  });
+
+  it('should preserve existing module data', () => {
+    recordXP(tmpDir, 'git', 'read', 15);
+    updateWalkthroughStep(tmpDir, 'git', 5);
+    const result = recordQuizScore(tmpDir, 'git', '4/5');
+    expect(result.modules.git.xp_earned).toBe(15);
+    expect(result.modules.git.walkthrough_step).toBe(5);
+    expect(result.modules.git.quiz_score).toBe('4/5');
+  });
+});
+
+/* ================================================================== */
+/*  getStats                                                           */
+/* ================================================================== */
+
+describe('getStats', () => {
+  it('should return xp, belt, modulesCompleted, and modulesInProgress', () => {
+    const progress = {
+      user: { xp: 300, belt: 'green', modules_completed: 2 },
+      modules: {
+        git: { status: 'completed' },
+        hooks: { status: 'completed' },
+        daily: { status: 'in-progress' },
+      },
+    };
+    const stats = getStats(progress);
+    expect(stats.xp).toBe(300);
+    expect(stats.belt).toBe('green');
+    expect(stats.modulesCompleted).toBe(2);
+    expect(stats.modulesInProgress).toBe(1);
+  });
+
+  it('should handle empty progress', () => {
+    const stats = getStats({ user: {}, modules: {} });
+    expect(stats.xp).toBe(0);
+    expect(stats.belt).toBe('white');
+    expect(stats.modulesCompleted).toBe(0);
+    expect(stats.modulesInProgress).toBe(0);
+  });
+
+  it('should handle missing user field', () => {
+    const stats = getStats({ modules: {} });
+    expect(stats.xp).toBe(0);
+    expect(stats.belt).toBe('white');
+    expect(stats.modulesCompleted).toBe(0);
+  });
+
+  it('should handle missing modules field', () => {
+    const stats = getStats({ user: { xp: 100 } });
+    expect(stats.xp).toBe(100);
+    expect(stats.modulesInProgress).toBe(0);
+  });
+
+  it('should handle completely empty object', () => {
+    const stats = getStats({});
+    expect(stats.xp).toBe(0);
+    expect(stats.belt).toBe('white');
+    expect(stats.modulesCompleted).toBe(0);
+    expect(stats.modulesInProgress).toBe(0);
+  });
+
+  it('should count only in-progress modules, not completed', () => {
+    const progress = {
+      user: { xp: 100, modules_completed: 1 },
+      modules: {
+        a: { status: 'completed' },
+        b: { status: 'in-progress' },
+        c: { status: 'in-progress' },
+        d: { status: 'completed' },
+      },
+    };
+    const stats = getStats(progress);
+    expect(stats.modulesInProgress).toBe(2);
+    expect(stats.modulesCompleted).toBe(1); // from user field, not recounted
+  });
+});

package/src/registry.js

@@ -0,0 +1,201 @@
+/**
+ * Module registry — discovers module.yaml files from three sources and builds
+ * a unified searchable index.
+ *
+ * Sources:
+ *   1. Built-in   — packages/modules/           (ships with ClaudeTeach)
+ *   2. Packs      — ~/.claude-teach/modules/<pack>/modules/  (installed via git)
+ *   3. Local      — ~/.claude-teach/modules/local/           (user-authored)
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+import { MODULES_HOME, LOCAL_MODULES, ensureHome } from './marketplace.js';
+
+const BUILTIN_MODULES_DIR = 'packages/modules';
+const REGISTRY_FILE = 'registry.yaml';
+
+/* ------------------------------------------------------------------ */
+/*  Scanning helpers                                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Scan a directory for subdirectories containing module.yaml files.
+ * Returns an array of { meta, modulePath } objects.
+ */
+function scanModuleDir(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir).filter(name => {
+    const fullPath = join(dir, name);
+    try {
+      return statSync(fullPath).isDirectory() && existsSync(join(fullPath, 'module.yaml'));
+    } catch {
+      return false;
+    }
+  });
+
+  for (const dirName of entries) {
+    const modulePath = join(dir, dirName);
+    const yamlPath = join(modulePath, 'module.yaml');
+    try {
+      const raw = readFileSync(yamlPath, 'utf-8');
+      const meta = yaml.load(raw);
+      results.push({ meta, modulePath, dirName });
+    } catch (err) {
+      console.warn(`  Skipping ${modulePath}: ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Turn raw scan result + source tag into a module registry entry.
+ */
+function toRegistryEntry({ meta, modulePath, dirName }, source) {
+  const capabilities = detectCapabilities(modulePath);
+
+  return {
+    slug: meta.slug || dirName,
+    title: meta.title || dirName,
+    description: meta.description || '',
+    category: meta.category || 'uncategorized',
+    difficulty: meta.difficulty || 'beginner',
+    tags: meta.tags || [],
+    narrative: meta.narrative || false,
+    prerequisites: meta.prerequisites || [],
+    related: meta.related || [],
+    xp: meta.xp || {},
+    time: meta.time || {},
+    triggers: meta.triggers || [],
+    source,
+    capabilities,
+    _path: modulePath,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Build unified registry                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Scan all three module sources and build a merged registry.
+ * Built-in modules win on slug collisions.
+ */
+export async function buildRegistry(rootDir) {
+  const slugMap = new Map(); // slug -> entry (first-seen wins)
+  const allModules = [];
+
+  // --- 1. Built-in modules ---
+  const builtinDir = resolve(rootDir, BUILTIN_MODULES_DIR);
+  for (const item of scanModuleDir(builtinDir)) {
+    const entry = toRegistryEntry(item, 'built-in');
+    slugMap.set(entry.slug, entry);
+    allModules.push(entry);
+  }
+
+  // --- 2. Installed packs ---
+  ensureHome();
+  if (existsSync(MODULES_HOME)) {
+    for (const packDir of readdirSync(MODULES_HOME)) {
+      if (packDir === 'local') continue;
+      const packModulesDir = join(MODULES_HOME, packDir, 'modules');
+      for (const item of scanModuleDir(packModulesDir)) {
+        const entry = toRegistryEntry(item, `pack:${packDir}`);
+        if (slugMap.has(entry.slug)) {
+          console.warn(
+            chalk.yellow(`  Warning: slug "${entry.slug}" from pack "${packDir}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
+          );
+          continue;
+        }
+        slugMap.set(entry.slug, entry);
+        allModules.push(entry);
+      }
+    }
+  }
+
+  // --- 3. Local custom modules ---
+  if (existsSync(LOCAL_MODULES)) {
+    // Scan top-level directories inside local/
+    for (const item of scanModuleDir(LOCAL_MODULES)) {
+      const entry = toRegistryEntry(item, 'local');
+      if (slugMap.has(entry.slug)) {
+        console.warn(
+          chalk.yellow(`  Warning: local slug "${entry.slug}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
+        );
+        continue;
+      }
+      slugMap.set(entry.slug, entry);
+      allModules.push(entry);
+    }
+
+    // Also scan local/_preview/ for preview modules
+    const previewDir = join(LOCAL_MODULES, '_preview');
+    if (existsSync(previewDir)) {
+      for (const item of scanModuleDir(previewDir)) {
+        const entry = toRegistryEntry(item, 'local');
+        if (slugMap.has(entry.slug)) {
+          console.warn(
+            chalk.yellow(`  Warning: preview slug "${entry.slug}" collides with ${slugMap.get(entry.slug).source} — skipping.`)
+          );
+          continue;
+        }
+        slugMap.set(entry.slug, entry);
+        allModules.push(entry);
+      }
+    }
+  }
+
+  // Sort: beginner first, then intermediate, then advanced
+  const diffOrder = { beginner: 0, intermediate: 1, advanced: 2 };
+  allModules.sort((a, b) => (diffOrder[a.difficulty] || 0) - (diffOrder[b.difficulty] || 0));
+
+  const registry = { modules: allModules };
+
+  // Write registry.yaml for built-in modules only (preserves original behavior)
+  const registryPath = join(builtinDir, REGISTRY_FILE);
+  const builtinOnly = allModules
+    .filter(m => m.source === 'built-in')
+    .map(({ _path, ...rest }) => rest);
+  writeFileSync(
+    registryPath,
+    yaml.dump({ modules: builtinOnly }, { lineWidth: 120, noRefs: true }),
+    'utf-8',
+  );
+
+  return registry;
+}
+
+/**
+ * Load existing registry.yaml (built-in only), then merge in packs + local on the fly.
+ */
+export async function loadRegistry(rootDir) {
+  // Always do a full scan to include all three sources.
+  // This is fast — just reads module.yaml files from known directories.
+  return buildRegistry(rootDir);
+}
+
+/**
+ * Find a module by slug.
+ */
+export function getModule(registry, slug) {
+  return registry.modules?.find(m => m.slug === slug) || null;
+}
+
+/**
+ * Detect capabilities from which files exist in a module directory.
+ */
+function detectCapabilities(modulePath) {
+  const caps = ['content']; // content.md is required
+
+  if (existsSync(join(modulePath, 'walkthrough.md'))) caps.push('walkthrough');
+  if (existsSync(join(modulePath, 'exercises.md'))) caps.push('exercises');
+  if (existsSync(join(modulePath, 'quiz.md'))) caps.push('quiz');
+  if (existsSync(join(modulePath, 'quick-ref.md'))) caps.push('quick-ref');
+
+  return caps;
+}