@shaykec/claude-teach 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaykec/claude-teach",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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.7",
+    "@shaykec/bridge": "0.4.9",
     "@shaykec/shared": "0.1.3",
-    "@shaykec/plugin": "0.2.11",
+    "@shaykec/plugin": "0.2.12",
     "@shaykec/extension": "0.1.0"
   },
   "publishConfig": {

package/src/cli.e2e.test.js

@@ -674,7 +674,7 @@ describe('CLI E2E: Setup command', () => {
     const { stdout, exitCode } = runCli(['start', '--help']);
     expect(exitCode).toBe(0);
     const clean = stripAnsi(stdout);
-    expect(clean).toContain('Launch Claude Code');
+    expect(clean).toContain('Launch ClaudeTeach');
     expect(clean).toContain('--no-server');
     expect(clean).toContain('--port');
   });
@@ -881,7 +881,7 @@ describe('CLI E2E: Subcommand help texts', () => {
     { args: ['level-up', '--help'], contains: 'belt roadmap' },
     { args: ['serve', '--help'], contains: 'bridge server' },
     { args: ['inbox', '--help'], contains: 'captured from the browser' },
-    { args: ['start', '--help'], contains: 'Launch Claude Code' },
+    { args: ['start', '--help'], contains: 'Launch ClaudeTeach' },
     { args: ['setup', '--help'], contains: 'Check environment' },
     { args: ['registry:build', '--help'], contains: 'Rebuild the module registry' },
     { args: ['install', '--help'], contains: 'Install a module pack' },
@@ -916,7 +916,7 @@ describe('CLI E2E: npx comprehensive', () => {
   it('npx start --help shows launch description', () => {
     const { stdout, exitCode } = runNpx(['start', '--help'], { timeout: 60000 });
     expect(exitCode).toBe(0);
-    expect(stripAnsi(stdout)).toContain('Launch Claude Code');
+    expect(stripAnsi(stdout)).toContain('Launch ClaudeTeach');
   });
 
   it('npx setup --help shows setup options', () => {

package/src/cli.js

@@ -435,7 +435,8 @@ program
 // --- start ---
 program
   .command('start')
-  .description('Launch Claude Code with ClaudeTeach — starts bridge server + loads teaching skills')
+  .description('Launch ClaudeTeach — browser chat by default, or --terminal for CLI mode')
+  .option('--terminal', 'Use terminal CLI mode instead of browser chat')
   .option('--no-server', 'Skip starting the bridge server')
   .option('--no-browser', 'Skip opening the canvas in the browser')
   .option('--port <port>', 'Bridge server port', '3456')
@@ -470,10 +471,10 @@ program
         server = await new Promise((resolve, reject) => {
           const srv = startServer({
             port,
+            pluginDir,
             progressProvider: { getProgress: () => loadProgress(ROOT) },
             onReady: () => resolve(srv),
           });
-          // Handle port-in-use and other startup errors
           srv.server.on('error', (err) => {
             if (err.code === 'EADDRINUSE') {
               reject(new Error(`Port ${port} is already in use. Kill the old process or use --port <other>`));
@@ -492,38 +493,51 @@ program
     // 4. Open canvas in browser (unless --no-browser or --no-server)
     if (server && opts.browser !== false) {
       const canvasUrl = `http://localhost:${opts.port}`;
-      const platform = process.platform;
-      if (platform === 'darwin') {
-        exec(`open "${canvasUrl}"`);
-      } else if (platform === 'linux') {
-        exec(`xdg-open "${canvasUrl}"`);
-      } else if (platform === 'win32') {
-        exec(`start "" "${canvasUrl}"`);
-      }
+      openUrl(canvasUrl);
       console.log(chalk.dim(`  Canvas: ${canvasUrl}`));
     }
 
-    // 5. Launch
-    console.log(chalk.green('Launching Claude Code with ClaudeTeach...'));
-    console.log(chalk.dim(`  Plugin: ${pluginDir}`));
+    if (opts.terminal) {
+      // --- Terminal mode: spawn Claude Code with stdio: 'inherit' (legacy) ---
+      console.log(chalk.green('Launching Claude Code in terminal mode...'));
+      console.log(chalk.dim(`  Plugin: ${pluginDir}`));
 
-    const claudeArgs = [
-      '--plugin-dir', pluginDir,
-      '--allowedTools', 'Bash(*),Read,Write,Edit,Glob,Grep',
-      ...cmd.args,
-    ];
-    const child = spawn('claude', claudeArgs, { stdio: 'inherit' });
+      const claudeArgs = [
+        '--plugin-dir', pluginDir,
+        '--allowedTools', 'Bash(*),Read,Write,Edit,Glob,Grep',
+        ...cmd.args,
+      ];
+      const child = spawn('claude', claudeArgs, { stdio: 'inherit' });
 
-    child.on('error', (err) => {
-      console.error(chalk.red(`Failed to start Claude Code: ${err.message}`));
-      if (server) server.close();
-      process.exit(1);
-    });
+      child.on('error', (err) => {
+        console.error(chalk.red(`Failed to start Claude Code: ${err.message}`));
+        if (server) server.close();
+        process.exit(1);
+      });
 
-    child.on('close', (code) => {
-      if (server) server.close();
-      process.exit(code ?? 0);
-    });
+      child.on('close', (code) => {
+        if (server) server.close();
+        process.exit(code ?? 0);
+      });
+    } else {
+      // --- Browser chat mode (default): Claude runs via SDK in the bridge ---
+      console.log(chalk.green('ClaudeTeach is ready — chat in your browser!'));
+      console.log(chalk.dim(`  Plugin: ${pluginDir}`));
+      console.log(chalk.dim(`  Claude Code runs via the Agent SDK (no terminal TTY)`));
+      console.log(chalk.dim(`  Use --terminal flag for classic CLI mode`));
+
+      // Keep the process alive — the bridge server handles everything.
+      // On SIGINT, clean up and exit.
+      process.on('SIGINT', () => {
+        console.log(chalk.dim('\nShutting down...'));
+        if (server) server.close();
+        process.exit(0);
+      });
+      process.on('SIGTERM', () => {
+        if (server) server.close();
+        process.exit(0);
+      });
+    }
   });
 
 // --- setup ---

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');