@shaykec/claude-teach 0.6.5 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaykec/claude-teach",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Socratic AI teaching platform — learn anything through guided dialogue, visual canvas, and gamification",
   "type": "module",
   "main": "src/cli.js",
@@ -15,9 +15,9 @@
     "commander": "^12.0.0",
     "js-yaml": "^4.1.0",
     "chalk": "^5.3.0",
-    "@shaykec/bridge": "0.4.6",
+    "@shaykec/bridge": "0.4.8",
     "@shaykec/shared": "0.1.3",
-    "@shaykec/plugin": "0.2.11",
+    "@shaykec/plugin": "0.2.12",
     "@shaykec/extension": "0.1.0"
   },
   "publishConfig": {

package/src/game-yaml.test.js

@@ -0,0 +1,209 @@
+/**
+ * Validates game.yaml structure for all modules that include one.
+ * Ensures YAML is well-formed, every game has a valid type, and
+ * game-type-specific required fields are present.
+ */
+
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { GAME_TYPES } from '../../shared/src/constants.js';
+
+const MODULES_DIR = path.resolve(import.meta.dirname, '../../modules');
+
+const VALID_TYPES = new Set(GAME_TYPES);
+
+const REQUIRED_FIELDS = {
+  'speed-round': ['rounds'],
+  'bug-hunt': ['snippets'],
+  'classify': ['categories', 'items'],
+  'scenario': ['steps'],
+  'command-sprint': ['challenges'],
+  'memory-match': ['pairs'],
+};
+
+function getModulesWithGames() {
+  const modules = fs.readdirSync(MODULES_DIR, { withFileTypes: true })
+    .filter(d => d.isDirectory());
+
+  const result = [];
+  for (const mod of modules) {
+    const gamePath = path.join(MODULES_DIR, mod.name, 'game.yaml');
+    if (fs.existsSync(gamePath)) {
+      result.push({ slug: mod.name, gamePath });
+    }
+  }
+  return result;
+}
+
+const modulesWithGames = getModulesWithGames();
+
+describe('game.yaml validation', () => {
+  it('finds at least 5 modules with game.yaml', () => {
+    expect(modulesWithGames.length).toBeGreaterThanOrEqual(5);
+  });
+
+  describe.each(modulesWithGames)('$slug', ({ slug, gamePath }) => {
+    let doc;
+
+    it('parses as valid YAML', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      expect(doc).toBeTruthy();
+    });
+
+    it('has a top-level "games" array with at least one entry', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      expect(Array.isArray(doc.games)).toBe(true);
+      expect(doc.games.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('every game has a valid type', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        expect(VALID_TYPES.has(game.type), `invalid type "${game.type}" in ${slug}`).toBe(true);
+      }
+    });
+
+    it('every game has a non-empty title', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        expect(typeof game.title).toBe('string');
+        expect(game.title.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('every game has its type-specific required fields', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        const required = REQUIRED_FIELDS[game.type] || [];
+        for (const field of required) {
+          expect(game[field], `missing "${field}" in ${slug}/${game.type}/${game.title}`).toBeDefined();
+        }
+      }
+    });
+
+    it('speed-round games have valid rounds', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        if (game.type !== 'speed-round') continue;
+        expect(Array.isArray(game.rounds)).toBe(true);
+        expect(game.rounds.length).toBeGreaterThanOrEqual(3);
+        for (const round of game.rounds) {
+          expect(typeof round.question).toBe('string');
+          expect(Array.isArray(round.options)).toBe(true);
+          expect(round.options.length).toBeGreaterThanOrEqual(2);
+          expect(typeof round.answer).toBe('number');
+          expect(round.answer).toBeGreaterThanOrEqual(0);
+          expect(round.answer).toBeLessThan(round.options.length);
+        }
+      }
+    });
+
+    it('bug-hunt games have valid snippets', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        if (game.type !== 'bug-hunt') continue;
+        expect(Array.isArray(game.snippets)).toBe(true);
+        expect(game.snippets.length).toBeGreaterThanOrEqual(3);
+        for (const snippet of game.snippets) {
+          expect(typeof snippet.code).toBe('string');
+          expect(snippet.code.trim().length).toBeGreaterThan(0);
+          expect(typeof snippet.bugLine).toBe('number');
+          expect(snippet.bugLine).toBeGreaterThanOrEqual(1);
+          expect(typeof snippet.explanation).toBe('string');
+        }
+      }
+    });
+
+    it('classify games have valid categories and items', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        if (game.type !== 'classify') continue;
+        expect(Array.isArray(game.categories)).toBe(true);
+        expect(game.categories.length).toBeGreaterThanOrEqual(2);
+        const catNames = new Set(game.categories.map(c => c.name));
+        for (const cat of game.categories) {
+          expect(typeof cat.name).toBe('string');
+          expect(typeof cat.color).toBe('string');
+          expect(cat.color).toMatch(/^#[0-9a-fA-F]{6}$/);
+        }
+        expect(Array.isArray(game.items)).toBe(true);
+        expect(game.items.length).toBeGreaterThanOrEqual(4);
+        for (const item of game.items) {
+          expect(typeof item.text).toBe('string');
+          expect(catNames.has(item.category),
+            `item "${item.text}" references unknown category "${item.category}"`).toBe(true);
+        }
+      }
+    });
+
+    it('scenario games have valid steps', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        if (game.type !== 'scenario') continue;
+        expect(Array.isArray(game.steps)).toBe(true);
+        expect(game.steps.length).toBeGreaterThanOrEqual(3);
+        expect(typeof game.startHealth).toBe('number');
+        expect(game.startHealth).toBeGreaterThan(0);
+        const stepIds = new Set(game.steps.map(s => s.id));
+        stepIds.add('end');
+        expect(stepIds.has('start')).toBe(true);
+        for (const step of game.steps) {
+          expect(typeof step.id).toBe('string');
+          expect(typeof step.situation).toBe('string');
+          expect(Array.isArray(step.choices)).toBe(true);
+          expect(step.choices.length).toBeGreaterThanOrEqual(1);
+          for (const choice of step.choices) {
+            expect(typeof choice.text).toBe('string');
+            expect(typeof choice.consequence).toBe('string');
+            expect(typeof choice.health).toBe('number');
+            expect(stepIds.has(choice.next),
+              `choice in step "${step.id}" points to unknown next "${choice.next}"`).toBe(true);
+          }
+        }
+      }
+    });
+
+    it('command-sprint games have valid challenges', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        if (game.type !== 'command-sprint') continue;
+        expect(Array.isArray(game.challenges)).toBe(true);
+        expect(game.challenges.length).toBeGreaterThanOrEqual(3);
+        for (const ch of game.challenges) {
+          expect(typeof ch.prompt).toBe('string');
+          expect(typeof ch.answer).toBe('string');
+          expect(ch.answer.trim().length).toBeGreaterThan(0);
+          if (ch.alternates !== undefined) {
+            expect(Array.isArray(ch.alternates)).toBe(true);
+          }
+        }
+      }
+    });
+
+    it('memory-match games have valid pairs', () => {
+      const raw = fs.readFileSync(gamePath, 'utf-8');
+      doc = yaml.load(raw);
+      for (const game of doc.games) {
+        if (game.type !== 'memory-match') continue;
+        expect(Array.isArray(game.pairs)).toBe(true);
+        expect(game.pairs.length).toBeGreaterThanOrEqual(3);
+        for (const pair of game.pairs) {
+          expect(typeof pair.term).toBe('string');
+          expect(typeof pair.definition).toBe('string');
+        }
+      }
+    });
+  });
+});

package/src/progress.js

@@ -132,6 +132,33 @@ export function recordQuizScore(rootDir, slug, score) {
   return progress;
 }
 
+/**
+ * Record a game score for a module. Tracks latest and best scores.
+ */
+export function recordGameScore(rootDir, slug, score, maxScore) {
+  const progress = loadProgress(rootDir);
+
+  if (!progress.modules[slug]) {
+    progress.modules[slug] = {
+      status: 'in-progress',
+      started: new Date().toISOString().split('T')[0],
+      xp_earned: 0,
+    };
+  }
+
+  const mod = progress.modules[slug];
+  mod.game_score = `${score}/${maxScore}`;
+  mod.last_session = new Date().toISOString().split('T')[0];
+
+  const currentBest = mod.game_best ? parseInt(mod.game_best.split('/')[0], 10) : 0;
+  if (score > currentBest) {
+    mod.game_best = `${score}/${maxScore}`;
+  }
+
+  saveProgress(rootDir, progress);
+  return progress;
+}
+
 /**
  * Get summary stats from progress.
  */

package/src/progress.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { loadProgress, saveProgress, recordXP, completeModule, updateWalkthroughStep, recordQuizScore, getStats } from './progress.js';
+import { loadProgress, saveProgress, recordXP, completeModule, updateWalkthroughStep, recordQuizScore, recordGameScore, getStats } from './progress.js';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -293,6 +293,59 @@ describe('recordQuizScore', () => {
   });
 });
 
+/* ================================================================== */
+/*  recordGameScore                                                    */
+/* ================================================================== */
+
+describe('recordGameScore', () => {
+  it('should record the game score as a fraction string', () => {
+    const result = recordGameScore(tmpDir, 'git', 8, 10);
+    expect(result.modules.git.game_score).toBe('8/10');
+  });
+
+  it('should create module entry if it did not exist', () => {
+    const result = recordGameScore(tmpDir, 'new-mod', 5, 10);
+    expect(result.modules['new-mod']).toBeDefined();
+    expect(result.modules['new-mod'].status).toBe('in-progress');
+  });
+
+  it('should update last_session date', () => {
+    const result = recordGameScore(tmpDir, 'git', 7, 10);
+    const today = new Date().toISOString().split('T')[0];
+    expect(result.modules.git.last_session).toBe(today);
+  });
+
+  it('should track best score', () => {
+    recordGameScore(tmpDir, 'git', 5, 10);
+    const result = recordGameScore(tmpDir, 'git', 8, 10);
+    expect(result.modules.git.game_best).toBe('8/10');
+    expect(result.modules.git.game_score).toBe('8/10');
+  });
+
+  it('should not downgrade best score', () => {
+    recordGameScore(tmpDir, 'git', 9, 10);
+    const result = recordGameScore(tmpDir, 'git', 3, 10);
+    expect(result.modules.git.game_best).toBe('9/10');
+    expect(result.modules.git.game_score).toBe('3/10');
+  });
+
+  it('should persist to disk', () => {
+    recordGameScore(tmpDir, 'git', 6, 10);
+    const loaded = loadProgress(tmpDir);
+    expect(loaded.modules.git.game_score).toBe('6/10');
+    expect(loaded.modules.git.game_best).toBe('6/10');
+  });
+
+  it('should preserve existing module data', () => {
+    recordXP(tmpDir, 'git', 'read', 15);
+    recordQuizScore(tmpDir, 'git', '4/5');
+    const result = recordGameScore(tmpDir, 'git', 7, 10);
+    expect(result.modules.git.xp_earned).toBe(15);
+    expect(result.modules.git.quiz_score).toBe('4/5');
+    expect(result.modules.git.game_score).toBe('7/10');
+  });
+});
+
 /* ================================================================== */
 /*  getStats                                                           */
 /* ================================================================== */

package/src/registry.js

@@ -217,6 +217,7 @@ function detectCapabilities(modulePath) {
   if (existsSync(join(modulePath, 'quiz.md'))) caps.push('quiz');
   if (existsSync(join(modulePath, 'quick-ref.md'))) caps.push('quick-ref');
   if (existsSync(join(modulePath, 'resources.md'))) caps.push('resources');
+  if (existsSync(join(modulePath, 'game.yaml'))) caps.push('game');
 
   // Check for media entries in module.yaml
   try {

package/src/registry.test.js

@@ -345,6 +345,27 @@ describe('buildRegistry (filesystem)', () => {
     expect(mod.capabilities).not.toContain('media');
   });
 
+  it('should detect game capability when game.yaml exists', async () => {
+    const moduleDir = createModule('game-test');
+    fs.writeFileSync(path.join(moduleDir, 'game.yaml'), 'games:\n  - type: speed-round\n    title: Test\n', 'utf-8');
+
+    const { buildRegistry } = await import('./registry.js');
+    const registry = await buildRegistry(tmpDir);
+
+    const mod = registry.modules.find(m => m.slug === 'game-test');
+    expect(mod.capabilities).toContain('game');
+  });
+
+  it('should not detect game capability when game.yaml is absent', async () => {
+    createModule('no-game-test');
+
+    const { buildRegistry } = await import('./registry.js');
+    const registry = await buildRegistry(tmpDir);
+
+    const mod = registry.modules.find(m => m.slug === 'no-game-test');
+    expect(mod.capabilities).not.toContain('game');
+  });
+
   it('should skip directories without module.yaml', async () => {
     // Create a directory without module.yaml
     const emptyDir = path.join(tmpDir, 'packages', 'modules', 'no-yaml');