@shaykec/claude-teach 0.2.0 → 0.4.0

package/src/cli.e2e.test.js

@@ -0,0 +1,962 @@
+/**
+ * Level 1 E2E tests — run the claude-teach CLI binary and assert on output.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
+import { spawn } from 'child_process';
+import { existsSync, mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import yaml from 'js-yaml';
+import { writeFileSync, mkdirSync } from 'fs';
+import {
+  runCli,
+  runNpx,
+  stripAnsi,
+  createTempHome,
+  createTestPack,
+  backupProgress,
+  restoreProgress,
+  seedProgress,
+  PROJECT_ROOT,
+} from './cli.e2e.helpers.js';
+
+// =====================================================================
+//  Group A — Learning commands (read-only, no isolation needed)
+// =====================================================================
+
+describe('CLI E2E: Learning commands', () => {
+  describe('list', () => {
+    it('lists available modules with count', () => {
+      const { stdout } = runCli(['list']);
+      const clean = stripAnsi(stdout);
+      expect(clean).toContain('Available Modules');
+      expect(clean).toContain('git');
+      expect(clean).toContain('hooks');
+      expect(clean).toContain('daily-workflow');
+    });
+
+    it('filters by difficulty beginner', () => {
+      const { stdout } = runCli(['list', '--difficulty', 'beginner']);
+      const clean = stripAnsi(stdout);
+      expect(clean).toContain('git');
+    });
+
+    it('shows no modules for non-matching difficulty', () => {
+      const { stdout } = runCli(['list', '--difficulty', 'nonexistent-level']);
+      const clean = stripAnsi(stdout);
+      expect(clean).toContain('No modules found');
+    });
+
+    it('filters by category', () => {
+      const { stdout } = runCli(['list', '--category', 'developer-skills']);
+      const clean = stripAnsi(stdout);
+      expect(clean).toContain('git');
+    });
+
+    it('filters by tag', () => {
+      const { stdout } = runCli(['list', '--tag', 'git']);
+      const clean = stripAnsi(stdout);
+      expect(clean).toContain('git');
+    });
+
+    it('filters by source', () => {
+      const { stdout } = runCli(['list', '--source', 'built-in']);
+      const clean = stripAnsi(stdout);
+      expect(clean).toContain('Available Modules');
+    });
+  });
+
+  describe('get', () => {
+    it('outputs walkthrough content for git module', () => {
+      const { stdout, exitCode } = runCli(['get', 'git']);
+      expect(exitCode).toBe(0);
+      // walkthrough.md exists for git
+      expect(stdout.length).toBeGreaterThan(100);
+    });
+
+    it('outputs quick reference for git module', () => {
+      const { stdout, exitCode } = runCli(['get', 'git', '--quick']);
+      expect(exitCode).toBe(0);
+      expect(stdout.length).toBeGreaterThan(50);
+    });
+
+    it('outputs quiz for git module', () => {
+      const { stdout, exitCode } = runCli(['get', 'git', '--quiz-only']);
+      expect(exitCode).toBe(0);
+      expect(stdout.length).toBeGreaterThan(50);
+    });
+
+    it('shows no progress for unstudied module', () => {
+      const { stdout, exitCode } = runCli(['get', 'git', '--status']);
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('No progress recorded');
+    });
+
+    it('fails for nonexistent module', () => {
+      const { stderr, exitCode } = runCli(['get', 'nonexistent-module-xyz'], { expectError: true });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('not found');
+    });
+
+    it('fails for quick ref on module without it', () => {
+      const { stderr, exitCode } = runCli(['get', 'hooks', '--quick'], { expectError: true });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('No quick reference');
+    });
+
+    it('outputs content.md for module without walkthrough', () => {
+      const { stdout, exitCode } = runCli(['get', 'hooks']);
+      expect(exitCode).toBe(0);
+      expect(stdout.length).toBeGreaterThan(50);
+    });
+  });
+
+  describe('stats', () => {
+    it('outputs dashboard with default belt', () => {
+      const { stdout, exitCode } = runCli(['stats']);
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('ClaudeTeach Dashboard');
+    });
+  });
+
+  describe('level-up', () => {
+    it('outputs belt info and recommendations', () => {
+      const { stdout, exitCode } = runCli(['level-up']);
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      // Should mention at least one thing about the belt system or recommendations
+      expect(clean.length).toBeGreaterThan(20);
+    });
+  });
+
+  describe('global flags', () => {
+    it('outputs version matching semver', () => {
+      const { stdout, exitCode } = runCli(['--version']);
+      expect(exitCode).toBe(0);
+      expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+
+    it('outputs help text', () => {
+      const { stdout, exitCode } = runCli(['--help']);
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain('Socratic AI teaching platform');
+    });
+  });
+});
+
+// =====================================================================
+//  Group B — Progress commands (backup/restore .teach-progress.yaml)
+// =====================================================================
+
+describe('CLI E2E: Progress commands', () => {
+  let progressBackup;
+
+  beforeEach(() => {
+    progressBackup = backupProgress();
+  });
+
+  afterEach(() => {
+    restoreProgress(progressBackup);
+  });
+
+  it('resets progress for a module', () => {
+    // Seed some progress first
+    seedProgress({
+      user: { xp: 50, belt: 'yellow', modules_completed: 0 },
+      modules: { git: { status: 'in-progress', xp_earned: 50 } },
+    });
+
+    const { stdout, exitCode } = runCli(['get', 'git', '--reset']);
+    const clean = stripAnsi(stdout);
+    expect(exitCode).toBe(0);
+    expect(clean).toContain('Progress reset');
+  });
+
+  it('shows status for module with progress', () => {
+    seedProgress({
+      user: { xp: 100, belt: 'yellow', modules_completed: 0 },
+      modules: { git: { status: 'in-progress', xp_earned: 100, walkthrough_step: 3 } },
+    });
+
+    const { stdout, exitCode } = runCli(['get', 'git', '--status']);
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout);
+    expect(parsed.status).toBe('in-progress');
+    expect(parsed.xp_earned).toBe(100);
+  });
+
+  it('stats shows seeded XP and belt', () => {
+    seedProgress({
+      user: { xp: 200, belt: 'green', modules_completed: 1 },
+      modules: { git: { status: 'completed', xp_earned: 200 } },
+    });
+
+    const { stdout, exitCode } = runCli(['stats']);
+    const clean = stripAnsi(stdout);
+    expect(exitCode).toBe(0);
+    expect(clean).toContain('200');
+  });
+});
+
+// =====================================================================
+//  Group C — Authoring commands (temp dir as cwd)
+// =====================================================================
+
+describe('CLI E2E: Authoring commands', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'teach-e2e-author-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('author init', () => {
+    it('scaffolds a new pack', () => {
+      const { stdout, exitCode } = runCli(['author', 'init', 'test-pack'], { cwd: tmpDir });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('scaffolded');
+
+      // Verify file structure
+      expect(existsSync(join(tmpDir, 'test-pack', 'pack.yaml'))).toBe(true);
+      expect(existsSync(join(tmpDir, 'test-pack', 'modules'))).toBe(true);
+      expect(existsSync(join(tmpDir, 'test-pack', 'README.md'))).toBe(true);
+    });
+
+    it('fails if directory already exists', () => {
+      runCli(['author', 'init', 'test-pack'], { cwd: tmpDir });
+      const { stderr, exitCode } = runCli(['author', 'init', 'test-pack'], {
+        cwd: tmpDir,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('already exists');
+    });
+  });
+
+  describe('author add', () => {
+    it('adds a module to a pack', () => {
+      runCli(['author', 'init', 'test-pack'], { cwd: tmpDir });
+      const { stdout, exitCode } = runCli(['author', 'add', 'test-pack/my-module'], { cwd: tmpDir });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('my-module');
+
+      const moduleDir = join(tmpDir, 'test-pack', 'modules', 'my-module');
+      expect(existsSync(join(moduleDir, 'module.yaml'))).toBe(true);
+      expect(existsSync(join(moduleDir, 'content.md'))).toBe(true);
+    });
+
+    it('fails for nonexistent pack', () => {
+      const { stderr, exitCode } = runCli(['author', 'add', 'no-pack/mod'], {
+        cwd: tmpDir,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('No pack.yaml');
+    });
+
+    it('fails for duplicate module', () => {
+      runCli(['author', 'init', 'test-pack'], { cwd: tmpDir });
+      runCli(['author', 'add', 'test-pack/my-module'], { cwd: tmpDir });
+      const { stderr, exitCode } = runCli(['author', 'add', 'test-pack/my-module'], {
+        cwd: tmpDir,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('already exists');
+    });
+  });
+
+  describe('author validate', () => {
+    it('validates a correct pack', () => {
+      runCli(['author', 'init', 'test-pack'], { cwd: tmpDir });
+      runCli(['author', 'add', 'test-pack/my-module'], { cwd: tmpDir });
+      const { stdout, exitCode } = runCli(['author', 'validate', 'test-pack'], { cwd: tmpDir });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('Pack is valid');
+    });
+
+    it('fails for missing pack.yaml', () => {
+      const { stdout, exitCode } = runCli(['author', 'validate', '.'], {
+        cwd: tmpDir,
+        expectError: true,
+      });
+      const clean = stripAnsi(stdout + '');
+      expect(exitCode).toBe(1);
+    });
+  });
+
+  describe('author preview', () => {
+    let tempHome;
+
+    beforeEach(() => {
+      tempHome = createTempHome();
+    });
+
+    afterEach(() => {
+      tempHome.cleanup();
+    });
+
+    it('previews a valid module', () => {
+      // Create a module directory with module.yaml
+      const packDir = createTestPack(tmpDir, 'test-pack', ['my-mod']);
+      const modulePath = join(packDir, 'modules', 'my-mod');
+
+      const { stdout, exitCode } = runCli(['author', 'preview', modulePath], {
+        cwd: tmpDir,
+        env: tempHome.env,
+      });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('Previewing');
+    });
+
+    it('fails for path without module.yaml', () => {
+      const { stderr, exitCode } = runCli(['author', 'preview', tmpDir], {
+        cwd: tmpDir,
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('No module.yaml');
+    });
+  });
+});
+
+// =====================================================================
+//  Group D — Marketplace commands (HOME isolation)
+// =====================================================================
+
+describe('CLI E2E: Marketplace commands', () => {
+  let tempHome;
+
+  beforeEach(() => {
+    tempHome = createTempHome();
+  });
+
+  afterEach(() => {
+    tempHome.cleanup();
+  });
+
+  describe('packs', () => {
+    it('shows no packs when none installed', () => {
+      const { stdout, exitCode } = runCli(['packs'], { env: tempHome.env });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('No module packs installed');
+    });
+  });
+
+  describe('install error handling', () => {
+    it('fails for invalid URL format', () => {
+      const { stderr, exitCode } = runCli(['install', 'not-a-valid!!!url'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('Invalid URL');
+    });
+
+    it('fails for unreachable git repo', () => {
+      const { stderr, exitCode } = runCli(
+        ['install', 'https://github.com/nonexistent-user-xyz/nonexistent-repo-xyz'],
+        { env: tempHome.env, expectError: true, timeout: 20000 },
+      );
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('Error');
+    });
+  });
+
+  describe('packs + remove (with manually placed pack)', () => {
+    /**
+     * Simulate a previously installed pack by writing files directly
+     * into the HOME/.claude-teach/modules/ directory.
+     */
+    function placePack(homePath, packName) {
+      const packDir = join(homePath, '.claude-teach', 'modules', packName);
+      const modulesDir = join(packDir, 'modules', 'test-mod');
+      mkdirSync(modulesDir, { recursive: true });
+
+      writeFileSync(join(packDir, 'pack.yaml'), yaml.dump({
+        name: packName,
+        author: 'test',
+        description: 'A test pack',
+        version: '1.0.0',
+        modules: ['test-mod'],
+      }), 'utf-8');
+
+      writeFileSync(join(modulesDir, 'module.yaml'), yaml.dump({
+        slug: 'test-mod',
+        title: 'Test Module',
+        version: '1.0.0',
+        difficulty: 'beginner',
+        xp: { read: 10 },
+      }), 'utf-8');
+
+      writeFileSync(join(modulesDir, 'content.md'), '# Test\n', 'utf-8');
+    }
+
+    it('lists an installed pack', () => {
+      placePack(tempHome.path, 'test-pack');
+
+      const { stdout, exitCode } = runCli(['packs'], { env: tempHome.env });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('test-pack');
+      expect(clean).toContain('Installed Packs');
+    });
+
+    it('removes an installed pack', () => {
+      placePack(tempHome.path, 'test-pack');
+
+      const { stdout, exitCode } = runCli(['remove', 'test-pack'], { env: tempHome.env });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('removed');
+
+      const packDir = join(tempHome.path, '.claude-teach', 'modules', 'test-pack');
+      expect(existsSync(packDir)).toBe(false);
+    });
+  });
+
+  describe('remove edge cases', () => {
+    it('fails for nonexistent pack', () => {
+      const { stderr, exitCode } = runCli(['remove', 'nonexistent-pack'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('not installed');
+    });
+
+    it('fails for reserved "local" name', () => {
+      const { stderr, exitCode } = runCli(['remove', 'local'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('cannot be removed');
+    });
+  });
+
+  describe('update', () => {
+    it('fails for nonexistent pack', () => {
+      const { stderr, exitCode } = runCli(['update', 'nonexistent-pack'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('not installed');
+    });
+
+    it('fails for reserved "local" name', () => {
+      const { stderr, exitCode } = runCli(['update', 'local'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('cannot be updated');
+    });
+  });
+
+  describe('search', () => {
+    it('handles no results gracefully', () => {
+      const { stdout, exitCode } = runCli(['search', 'xyznonexistent999'], {
+        env: tempHome.env,
+        timeout: 15000,
+      });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('No packs found');
+    });
+  });
+
+  describe('registry', () => {
+    it('lists default registry', () => {
+      const { stdout, exitCode } = runCli(['registry', 'list'], { env: tempHome.env });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('default');
+      expect(clean).toContain('Configured Registries');
+    });
+
+    it('adds a registry', () => {
+      const { stdout, exitCode } = runCli(['registry', 'add', 'user/test-registry'], {
+        env: tempHome.env,
+      });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('added');
+    });
+
+    it('lists added registry', () => {
+      runCli(['registry', 'add', 'user/test-registry'], { env: tempHome.env });
+
+      const { stdout, exitCode } = runCli(['registry', 'list'], { env: tempHome.env });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('test-registry');
+    });
+
+    it('removes a registry', () => {
+      runCli(['registry', 'add', 'user/test-registry'], { env: tempHome.env });
+
+      const { stdout, exitCode } = runCli(['registry', 'remove', 'test-registry'], {
+        env: tempHome.env,
+      });
+      const clean = stripAnsi(stdout);
+      expect(exitCode).toBe(0);
+      expect(clean).toContain('removed');
+    });
+
+    it('fails to remove nonexistent registry', () => {
+      const { stderr, exitCode } = runCli(['registry', 'remove', 'nonexistent'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('not found');
+    });
+
+    it('fails to add duplicate registry', () => {
+      runCli(['registry', 'add', 'user/test-registry'], { env: tempHome.env });
+      const { stderr, exitCode } = runCli(['registry', 'add', 'user/test-registry'], {
+        env: tempHome.env,
+        expectError: true,
+      });
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain('already configured');
+    });
+  });
+});
+
+// =====================================================================
+//  Group E — Server command (spawn + kill)
+// =====================================================================
+
+describe('CLI E2E: Server command', () => {
+  it('serve starts and responds to /health', async () => {
+    const port = 13456 + Math.floor(Math.random() * 1000);
+    const child = spawn('node', [
+      join(PROJECT_ROOT, 'packages/core/src/cli.js'),
+      'serve',
+      '--port',
+      String(port),
+    ], {
+      cwd: PROJECT_ROOT,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    try {
+      // Wait for server to be ready (try hitting /health with retries)
+      let ready = false;
+      for (let i = 0; i < 20; i++) {
+        await new Promise(r => setTimeout(r, 500));
+        try {
+          const resp = await fetch(`http://localhost:${port}/health`);
+          if (resp.ok) {
+            ready = true;
+            break;
+          }
+        } catch {
+          // Server not ready yet
+        }
+      }
+
+      expect(ready).toBe(true);
+
+      // Verify health response
+      const resp = await fetch(`http://localhost:${port}/health`);
+      const data = await resp.json();
+      expect(data).toHaveProperty('status', 'ok');
+    } finally {
+      child.kill('SIGTERM');
+      await new Promise(resolve => child.on('close', resolve));
+    }
+  }, 15000);
+});
+
+// =====================================================================
+//  Group F — System commands
+// =====================================================================
+
+describe('CLI E2E: System commands', () => {
+  it('registry:build outputs rebuild summary', () => {
+    const { stdout, exitCode } = runCli(['registry:build']);
+    const clean = stripAnsi(stdout);
+    expect(exitCode).toBe(0);
+    expect(clean).toContain('Registry rebuilt');
+    expect(clean).toContain('built-in');
+  });
+});
+
+// =====================================================================
+//  Group G — npx commands (published package)
+// =====================================================================
+
+describe('CLI E2E: npx @shaykec/claude-teach', () => {
+  it('npx --version outputs semver', () => {
+    const { stdout, exitCode } = runNpx(['--version']);
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  it('npx list shows available modules', () => {
+    const { stdout, exitCode } = runNpx(['list']);
+    const clean = stripAnsi(stdout);
+    expect(exitCode).toBe(0);
+    expect(clean).toContain('Available Modules');
+    expect(clean).toContain('git');
+  });
+
+  it('npx stats shows dashboard', () => {
+    const { stdout, exitCode } = runNpx(['stats']);
+    const clean = stripAnsi(stdout);
+    expect(exitCode).toBe(0);
+    expect(clean).toContain('ClaudeTeach Dashboard');
+  });
+
+  it('npx get git outputs module content', () => {
+    const { stdout, exitCode } = runNpx(['get', 'git']);
+    expect(exitCode).toBe(0);
+    expect(stdout.length).toBeGreaterThan(100);
+  });
+
+  it('npx --help shows description', () => {
+    const { stdout, exitCode } = runNpx(['--help']);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain('Socratic AI teaching platform');
+  });
+});
+
+// =====================================================================
+//  Group H — Setup command (all options)
+// =====================================================================
+
+describe('CLI E2E: Setup command', () => {
+  it('setup --show-path outputs plugin path containing packages/plugin', () => {
+    const { stdout, exitCode } = runCli(['setup', '--show-path']);
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toContain('packages/plugin');
+  });
+
+  it('setup --show-path outputs an absolute path', () => {
+    const { stdout, exitCode } = runCli(['setup', '--show-path']);
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toMatch(/^\//); // starts with /
+  });
+
+  it('setup --show-path path actually has plugin.json', () => {
+    const { stdout, exitCode } = runCli(['setup', '--show-path']);
+    expect(exitCode).toBe(0);
+    const pluginDir = stdout.trim();
+    expect(existsSync(join(pluginDir, '.claude-plugin', 'plugin.json'))).toBe(true);
+  });
+
+  it('setup --help shows all options', () => {
+    const { stdout, exitCode } = runCli(['setup', '--help']);
+    expect(exitCode).toBe(0);
+    const clean = stripAnsi(stdout);
+    expect(clean).toContain('Check environment');
+    expect(clean).toContain('--show-path');
+    expect(clean).toContain('--extension');
+  });
+
+  it('start --help shows command description and options', () => {
+    const { stdout, exitCode } = runCli(['start', '--help']);
+    expect(exitCode).toBe(0);
+    const clean = stripAnsi(stdout);
+    expect(clean).toContain('Launch Claude Code');
+    expect(clean).toContain('--no-server');
+    expect(clean).toContain('--port');
+  });
+});
+
+// =====================================================================
+//  Group I — Start command (spawn-based, no actual Claude)
+// =====================================================================
+
+describe('CLI E2E: Start command', () => {
+  it('start --no-server fails gracefully when claude is not on PATH', () => {
+    // Build a PATH that includes node but excludes claude
+    const nodeBinDir = join(process.execPath, '..');
+    const { exitCode, stderr, stdout } = runCli(['start', '--no-server'], {
+      env: { PATH: `${nodeBinDir}:/usr/bin:/bin` },
+      expectError: true,
+      timeout: 10000,
+    });
+    const output = stripAnsi(stdout + stderr);
+    // Should fail because claude is not found on this restricted PATH
+    expect(exitCode).not.toBe(0);
+    expect(output).toContain('Claude Code CLI not found');
+  });
+
+  it('start spawns bridge server on custom port', async () => {
+    const port = 14456 + Math.floor(Math.random() * 1000);
+    // Spawn start with a bogus claude path to test bridge startup
+    // Use a wrapper script that just exits so we can verify bridge started
+    const child = spawn('node', [
+      join(PROJECT_ROOT, 'packages/core/src/cli.js'),
+      'start',
+      '--port', String(port),
+    ], {
+      cwd: PROJECT_ROOT,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+
+    try {
+      // Wait a bit for the bridge to start
+      let bridgeStarted = false;
+      for (let i = 0; i < 10; i++) {
+        await new Promise(r => setTimeout(r, 500));
+        try {
+          const resp = await fetch(`http://localhost:${port}/health`);
+          if (resp.ok) {
+            bridgeStarted = true;
+            break;
+          }
+        } catch { /* not ready */ }
+      }
+
+      // If claude is installed, bridge should have started
+      // If claude is not installed, the process exits with error before bridge starts
+      // Either way, the test should not fail - just verify the behavior
+      const cleanOutput = stripAnsi(stdout);
+      if (bridgeStarted) {
+        const resp = await fetch(`http://localhost:${port}/health`);
+        const data = await resp.json();
+        expect(data).toHaveProperty('status', 'ok');
+      } else {
+        // Process exited because claude is not on PATH — valid behavior
+        expect(true).toBe(true);
+      }
+    } finally {
+      child.kill('SIGTERM');
+      await new Promise(resolve => child.on('close', resolve));
+    }
+  }, 15000);
+});
+
+// =====================================================================
+//  Group J — Bridge server /api/open-extension endpoint
+// =====================================================================
+
+describe('CLI E2E: Bridge API endpoints', () => {
+  let port;
+  let child;
+
+  beforeAll(async () => {
+    port = 15456 + Math.floor(Math.random() * 1000);
+    child = spawn('node', [
+      join(PROJECT_ROOT, 'packages/core/src/cli.js'),
+      'serve',
+      '--port', String(port),
+    ], {
+      cwd: PROJECT_ROOT,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    // Wait for server to be ready
+    for (let i = 0; i < 20; i++) {
+      await new Promise(r => setTimeout(r, 500));
+      try {
+        const resp = await fetch(`http://localhost:${port}/health`);
+        if (resp.ok) break;
+      } catch { /* not ready */ }
+    }
+  }, 15000);
+
+  afterAll(async () => {
+    if (child) {
+      child.kill('SIGTERM');
+      await new Promise(resolve => child.on('close', resolve));
+    }
+  });
+
+  it('POST /api/open-extension returns ok with extension path', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/open-extension`, {
+      method: 'POST',
+    });
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data.path).toContain('extension');
+  });
+
+  it('GET /health returns status ok and tier info', async () => {
+    const resp = await fetch(`http://localhost:${port}/health`);
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    expect(data.status).toBe('ok');
+    expect(data).toHaveProperty('tier');
+    expect(data).toHaveProperty('uptime');
+  });
+
+  it('GET /api/tier returns tier info', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/tier`);
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    expect(data).toHaveProperty('tier');
+  });
+
+  it('GET /api/progress returns progress data', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/progress`);
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    // Default empty progress
+    expect(data).toHaveProperty('user');
+  });
+
+  it('GET /api/events returns empty events array', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/events`);
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    expect(data).toHaveProperty('events');
+    expect(Array.isArray(data.events)).toBe(true);
+    expect(data).toHaveProperty('count');
+  });
+
+  it('GET /api/templates returns templates list', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/templates`);
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    expect(data).toHaveProperty('templates');
+    expect(Array.isArray(data.templates)).toBe(true);
+  });
+
+  it('POST /api/event with invalid body returns 400', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/event`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: 'not-json',
+    });
+    expect(resp.status).toBe(400);
+  });
+
+  it('POST /api/capture saves a capture file', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/capture`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'test-capture', content: 'hello' }),
+    });
+    const data = await resp.json();
+    expect(resp.status).toBe(200);
+    expect(data.ok).toBe(true);
+    expect(data.saved).toContain('test-capture');
+  });
+
+  it('GET /nonexistent returns 404', async () => {
+    const resp = await fetch(`http://localhost:${port}/nonexistent.xyz`);
+    expect(resp.status).toBe(404);
+  });
+
+  it('OPTIONS returns 204 (CORS preflight)', async () => {
+    const resp = await fetch(`http://localhost:${port}/api/event`, {
+      method: 'OPTIONS',
+    });
+    expect(resp.status).toBe(204);
+  });
+});
+
+// =====================================================================
+//  Group K — All CLI subcommand help texts
+// =====================================================================
+
+describe('CLI E2E: Subcommand help texts', () => {
+  const subcommands = [
+    { args: ['list', '--help'], contains: 'List available learning modules' },
+    { args: ['get', '--help'], contains: 'Get module content' },
+    { args: ['stats', '--help'], contains: 'gamification dashboard' },
+    { 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: ['setup', '--help'], contains: 'Check environment' },
+    { args: ['registry:build', '--help'], contains: 'Rebuild the module registry' },
+    { args: ['install', '--help'], contains: 'Install a module pack' },
+    { args: ['packs', '--help'], contains: 'installed module packs' },
+    { args: ['update', '--help'], contains: 'Update an installed module pack' },
+    { args: ['remove', '--help'], contains: 'Remove an installed module pack' },
+    { args: ['search', '--help'], contains: 'Search configured registries' },
+    { args: ['author', '--help'], contains: 'authoring tools' },
+  ];
+
+  for (const { args, contains } of subcommands) {
+    it(`${args[0]} --help shows description`, () => {
+      const { stdout, exitCode } = runCli(args);
+      expect(exitCode).toBe(0);
+      expect(stripAnsi(stdout)).toContain(contains);
+    });
+  }
+});
+
+// =====================================================================
+//  Group L — Comprehensive npx tests (all commands)
+// =====================================================================
+
+describe('CLI E2E: npx comprehensive', () => {
+  it('npx setup --show-path resolves plugin via npm', () => {
+    const { stdout, exitCode } = runNpx(['setup', '--show-path'], { timeout: 60000 });
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toContain('plugin');
+    expect(stdout.trim().length).toBeGreaterThan(5);
+  });
+
+  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');
+  });
+
+  it('npx setup --help shows setup options', () => {
+    const { stdout, exitCode } = runNpx(['setup', '--help'], { timeout: 60000 });
+    expect(exitCode).toBe(0);
+    const clean = stripAnsi(stdout);
+    expect(clean).toContain('--show-path');
+    expect(clean).toContain('--extension');
+  });
+
+  it('npx level-up outputs recommendations', () => {
+    const { stdout, exitCode } = runNpx(['level-up'], { timeout: 60000 });
+    expect(exitCode).toBe(0);
+    expect(stdout.trim().length).toBeGreaterThan(20);
+  });
+
+  it('npx get git --quick outputs quick reference', () => {
+    const { stdout, exitCode } = runNpx(['get', 'git', '--quick'], { timeout: 60000 });
+    expect(exitCode).toBe(0);
+    expect(stdout.length).toBeGreaterThan(50);
+  });
+
+  it('npx get nonexistent-module fails with exit 1', () => {
+    const { exitCode, stderr } = runNpx(['get', 'nonexistent-module-xyz'], {
+      timeout: 60000,
+      expectError: true,
+    });
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain('not found');
+  });
+
+  it('npx list --difficulty beginner shows filtered modules', () => {
+    const { stdout, exitCode } = runNpx(['list', '--difficulty', 'beginner'], { timeout: 60000 });
+    expect(exitCode).toBe(0);
+    expect(stripAnsi(stdout)).toContain('git');
+  });
+
+  it('npx registry:build rebuilds registry', () => {
+    const { stdout, exitCode } = runNpx(['registry:build'], { timeout: 60000 });
+    expect(exitCode).toBe(0);
+    expect(stripAnsi(stdout)).toContain('Registry rebuilt');
+  });
+});