@shaykec/claude-teach 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaykec/claude-teach",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Socratic AI teaching platform — learn anything through guided dialogue, visual canvas, and gamification",
   "type": "module",
   "main": "src/cli.js",
@@ -15,8 +15,10 @@
     "commander": "^12.0.0",
     "js-yaml": "^4.1.0",
     "chalk": "^5.3.0",
-    "@shaykec/bridge": "0.1.0",
-    "@shaykec/shared": "0.1.0"
+    "@shaykec/bridge": "0.2.0",
+    "@shaykec/shared": "0.1.0",
+    "@shaykec/plugin": "0.1.0",
+    "@shaykec/extension": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/cli.e2e.helpers.js

@@ -0,0 +1,289 @@
+/**
+ * E2E test helpers for running the claude-teach CLI binary.
+ */
+
+import { execFileSync } from 'child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, copyFileSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
+import yaml from 'js-yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const CLI_PATH = resolve(__dirname, 'cli.js');
+export const PROJECT_ROOT = resolve(__dirname, '..', '..', '..');
+const PROGRESS_FILE = '.teach-progress.yaml';
+
+/**
+ * Strip ANSI escape codes from a string.
+ */
+export function stripAnsi(str) {
+  return str.replace(
+    // eslint-disable-next-line no-control-regex
+    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+    '',
+  );
+}
+
+/**
+ * Run the CLI binary and capture output.
+ *
+ * @param {string[]} args — CLI arguments
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] — working directory (defaults to PROJECT_ROOT)
+ * @param {object} [opts.env] — extra env vars (merged with process.env)
+ * @param {number} [opts.timeout] — timeout in ms (default 10000)
+ * @param {boolean} [opts.expectError] — if true, don't throw on non-zero exit
+ * @returns {{ stdout: string, stderr: string, exitCode: number }}
+ */
+export function runCli(args, opts = {}) {
+  const {
+    cwd = PROJECT_ROOT,
+    env = {},
+    timeout = 10000,
+    expectError = false,
+  } = opts;
+
+  const mergedEnv = { ...process.env, ...env };
+
+  try {
+    const stdout = execFileSync('node', [CLI_PATH, ...args], {
+      cwd,
+      env: mergedEnv,
+      timeout,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { stdout, stderr: '', exitCode: 0 };
+  } catch (err) {
+    if (expectError || err.status !== null) {
+      return {
+        stdout: err.stdout || '',
+        stderr: err.stderr || '',
+        exitCode: err.status ?? 1,
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Run the package via npx and capture output.
+ *
+ * @param {string[]} args — CLI arguments
+ * @param {object} [opts]
+ * @param {number} [opts.timeout] — timeout in ms (default 30000)
+ * @param {boolean} [opts.expectError] — if true, don't throw on non-zero exit
+ * @returns {{ stdout: string, stderr: string, exitCode: number }}
+ */
+export function runNpx(args, opts = {}) {
+  const { timeout = 30000, expectError = false } = opts;
+
+  try {
+    const stdout = execFileSync('npx', ['@shaykec/claude-teach', ...args], {
+      cwd: PROJECT_ROOT,
+      env: process.env,
+      timeout,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { stdout, stderr: '', exitCode: 0 };
+  } catch (err) {
+    if (expectError || err.status !== null) {
+      return {
+        stdout: err.stdout || '',
+        stderr: err.stderr || '',
+        exitCode: err.status ?? 1,
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Create an isolated temp HOME directory with .claude-teach/ structure.
+ * Marketplace commands use homedir() for paths, so setting HOME isolates them.
+ *
+ * @returns {{ path: string, env: object, cleanup: () => void }}
+ */
+export function createTempHome() {
+  const tmpHome = mkdtempSync(join(tmpdir(), 'teach-e2e-home-'));
+  const teachDir = join(tmpHome, '.claude-teach');
+  const modulesDir = join(teachDir, 'modules');
+  const localDir = join(modulesDir, 'local');
+
+  mkdirSync(localDir, { recursive: true });
+
+  return {
+    path: tmpHome,
+    env: { HOME: tmpHome },
+    cleanup() {
+      rmSync(tmpHome, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Create a valid test module pack in the given directory.
+ *
+ * @param {string} dir — parent directory to create the pack in
+ * @param {string} name — pack name
+ * @param {string[]} [modules] — module names to create
+ * @returns {string} — path to the created pack
+ */
+export function createTestPack(dir, name, modules = []) {
+  const packDir = join(dir, name);
+  const modulesDir = join(packDir, 'modules');
+  mkdirSync(modulesDir, { recursive: true });
+
+  const packYaml = {
+    name,
+    author: 'test',
+    description: 'Test pack for e2e tests',
+    version: '1.0.0',
+    modules,
+  };
+
+  writeFileSync(
+    join(packDir, 'pack.yaml'),
+    yaml.dump(packYaml, { lineWidth: 120 }),
+    'utf-8',
+  );
+
+  writeFileSync(join(packDir, 'README.md'), `# ${name}\n`, 'utf-8');
+
+  for (const mod of modules) {
+    const moduleDir = join(modulesDir, mod);
+    mkdirSync(moduleDir, { recursive: true });
+
+    const moduleYaml = {
+      slug: mod,
+      title: mod.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+      version: '1.0.0',
+      description: 'Test module',
+      category: 'developer-skills',
+      tags: ['test'],
+      difficulty: 'beginner',
+      xp: { read: 10 },
+      time: { read: 5 },
+      prerequisites: [],
+      related: [],
+      triggers: [],
+    };
+
+    writeFileSync(
+      join(moduleDir, 'module.yaml'),
+      yaml.dump(moduleYaml, { lineWidth: 120 }),
+      'utf-8',
+    );
+
+    writeFileSync(
+      join(moduleDir, 'content.md'),
+      `# ${moduleYaml.title}\n\nTest content.\n`,
+      'utf-8',
+    );
+  }
+
+  return packDir;
+}
+
+/**
+ * Backup the progress file if it exists.
+ * @returns {string|null} — path to backup, or null if no file existed
+ */
+export function backupProgress() {
+  const filePath = join(PROJECT_ROOT, PROGRESS_FILE);
+  if (!existsSync(filePath)) return null;
+
+  const backupPath = join(PROJECT_ROOT, `${PROGRESS_FILE}.e2e-backup`);
+  copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Restore the progress file from backup, or remove it if no backup existed.
+ * @param {string|null} backupPath — path from backupProgress()
+ */
+export function restoreProgress(backupPath) {
+  const filePath = join(PROJECT_ROOT, PROGRESS_FILE);
+
+  if (backupPath && existsSync(backupPath)) {
+    copyFileSync(backupPath, filePath);
+    rmSync(backupPath, { force: true });
+  } else {
+    // No backup means file didn't exist before — remove any created during test
+    if (existsSync(filePath)) rmSync(filePath, { force: true });
+  }
+}
+
+/**
+ * Write a seeded progress file for testing.
+ * @param {object} progress — progress data
+ */
+export function seedProgress(progress) {
+  const filePath = join(PROJECT_ROOT, PROGRESS_FILE);
+  writeFileSync(filePath, yaml.dump(progress, { lineWidth: 120, noRefs: true }), 'utf-8');
+}
+
+/**
+ * Create a bare git repo with a valid pack.yaml for testing install.
+ * @param {string} parentDir — directory to create the fixture in
+ * @param {string} packName — pack name
+ * @param {string[]} [modules] — module names
+ * @returns {string} — file:// URL to the bare repo
+ */
+export function createGitFixture(parentDir, packName, modules = []) {
+  const bareRepo = join(parentDir, `${packName}.git`);
+  const tmpClone = join(parentDir, `${packName}-clone`);
+
+  // Create bare repo
+  execFileSync('git', ['init', '--bare', bareRepo], { stdio: 'pipe' });
+
+  // Clone, add content, push
+  execFileSync('git', ['clone', bareRepo, tmpClone], { stdio: 'pipe' });
+
+  // Create pack structure in clone
+  createTestPack(tmpClone, '.', modules);
+
+  // Move files up (createTestPack creates a subdirectory, but we want them at root)
+  // Actually, createTestPack creates in dir/name, so for root we need to handle differently
+  // Let's just write the files directly
+  const modulesDir = join(tmpClone, 'modules');
+  if (!existsSync(modulesDir)) mkdirSync(modulesDir, { recursive: true });
+
+  const packYaml = {
+    name: packName,
+    author: 'test',
+    description: 'Test fixture pack',
+    version: '1.0.0',
+    modules,
+  };
+  writeFileSync(join(tmpClone, 'pack.yaml'), yaml.dump(packYaml), 'utf-8');
+
+  for (const mod of modules) {
+    const moduleDir = join(modulesDir, mod);
+    mkdirSync(moduleDir, { recursive: true });
+    writeFileSync(join(moduleDir, 'module.yaml'), yaml.dump({
+      slug: mod,
+      title: mod,
+      version: '1.0.0',
+      description: 'test',
+      category: 'developer-skills',
+      difficulty: 'beginner',
+      xp: { read: 10 },
+    }), 'utf-8');
+    writeFileSync(join(moduleDir, 'content.md'), `# ${mod}\n`, 'utf-8');
+  }
+
+  // Git add + commit + push
+  execFileSync('git', ['-C', tmpClone, 'add', '.'], { stdio: 'pipe' });
+  execFileSync('git', ['-C', tmpClone, '-c', 'user.name=test', '-c', 'user.email=test@test.com', 'commit', '-m', 'init'], { stdio: 'pipe' });
+  execFileSync('git', ['-C', tmpClone, 'push'], { stdio: 'pipe' });
+
+  // Clean up the clone
+  rmSync(tmpClone, { recursive: true, force: true });
+
+  return `file://${bareRepo}`;
+}

package/src/cli.e2e.test.js

@@ -0,0 +1,673 @@
+/**
+ * Level 1 E2E tests — run the claude-teach CLI binary and assert on output.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, beforeAll } 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 — Plugin integration (setup + start)
+// =====================================================================
+
+describe('CLI E2E: Plugin integration', () => {
+  it('setup outputs plugin and extension paths', () => {
+    const { stdout, exitCode } = runCli(['setup', '--show-path']);
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toContain('packages/plugin');
+  });
+
+  it('setup shows checklist with plugin and extension info', () => {
+    // setup without --show-path prints the full checklist but also
+    // starts the bridge + opens browser. We can't let it do that in tests.
+    // Instead, just test --show-path (machine-readable) works.
+    const { stdout, exitCode } = runCli(['setup', '--show-path']);
+    expect(exitCode).toBe(0);
+    expect(stdout.trim().length).toBeGreaterThan(0);
+  });
+
+  it('start --help shows command description', () => {
+    const { stdout, exitCode } = runCli(['start', '--help']);
+    expect(exitCode).toBe(0);
+    const clean = stripAnsi(stdout);
+    expect(clean).toContain('Launch Claude Code');
+  });
+
+  it('setup --help shows command description', () => {
+    const { stdout, exitCode } = runCli(['setup', '--help']);
+    expect(exitCode).toBe(0);
+    const clean = stripAnsi(stdout);
+    expect(clean).toContain('Check environment');
+  });
+});

package/src/cli.js

@@ -2,9 +2,10 @@
 
 import { Command } from 'commander';
 import { readFileSync, existsSync } from 'fs';
-import { resolve, join } from 'path';
+import { resolve, join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { exec, spawn, execFileSync as execFileSyncChild } from 'child_process';
+import { createRequire } from 'module';
 import chalk from 'chalk';
 import { buildRegistry, loadRegistry, getModule } from './registry.js';
 import { loadProgress, saveProgress, getStats } from './progress.js';
@@ -14,6 +15,73 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const ROOT = resolve(__dirname, '..', '..', '..');
 
+// =====================================================================
+//  Helpers — plugin, extension, and Claude Code resolution
+// =====================================================================
+
+const require_ = createRequire(import.meta.url);
+
+/** Resolve the Claude Code plugin directory. */
+function resolvePluginDir() {
+  // Strategy 1: monorepo layout
+  const monoRepo = join(ROOT, 'packages', 'plugin');
+  if (existsSync(join(monoRepo, '.claude-plugin', 'plugin.json'))) return monoRepo;
+  // Strategy 2: resolve installed @shaykec/plugin package
+  try {
+    const pkgPath = require_.resolve('@shaykec/plugin/package.json');
+    const dir = dirname(pkgPath);
+    if (existsSync(join(dir, '.claude-plugin', 'plugin.json'))) return dir;
+  } catch { /* not installed */ }
+  return null;
+}
+
+/** Resolve the Chrome extension directory. */
+function resolveExtensionDir() {
+  const monoRepo = join(ROOT, 'packages', 'extension');
+  if (existsSync(join(monoRepo, 'manifest.json'))) return monoRepo;
+  try {
+    const pkgPath = require_.resolve('@shaykec/extension/package.json');
+    const dir = dirname(pkgPath);
+    if (existsSync(join(dir, 'manifest.json'))) return dir;
+  } catch { /* not installed */ }
+  return null;
+}
+
+/** Check if the `claude` CLI is available on PATH. */
+function findClaude() {
+  try {
+    const version = execFileSyncChild('claude', ['--version'], {
+      stdio: 'pipe', encoding: 'utf-8',
+    }).trim();
+    return { found: true, version };
+  } catch {
+    return { found: false, version: null };
+  }
+}
+
+/** Open the extension folder + chrome://extensions page (cross-platform). */
+function openExtensionInstall(extensionDir) {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    exec(`open "${extensionDir}"`);
+    exec('open -a "Google Chrome" "chrome://extensions"');
+  } else if (platform === 'linux') {
+    exec(`xdg-open "${extensionDir}"`);
+    exec('google-chrome "chrome://extensions" 2>/dev/null || chromium-browser "chrome://extensions" 2>/dev/null');
+  } else if (platform === 'win32') {
+    exec(`explorer "${extensionDir}"`);
+    exec('start chrome "chrome://extensions"');
+  }
+}
+
+/** Open a URL in the default browser (cross-platform). */
+function openUrl(url) {
+  const platform = process.platform;
+  if (platform === 'darwin') exec(`open "${url}"`);
+  else if (platform === 'linux') exec(`xdg-open "${url}"`);
+  else if (platform === 'win32') exec(`start "" "${url}"`);
+}
+
 const program = new Command();
 
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
@@ -36,6 +104,10 @@ Examples:
   $ 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 start                          Launch Claude Code with teaching skills
+  $ claude-teach start -p "teach me git"        One-shot teaching prompt
+  $ claude-teach setup                          Check environment and plugin path
+  $ claude-teach setup --extension              Install the Chrome extension
   $ claude-teach serve                          Start the bridge server for visuals`)
   .version(pkg.version);
 
@@ -218,6 +290,138 @@ program
     showInbox();
   });
 
+// =====================================================================
+//  Plugin integration commands — launch Claude Code, setup environment
+// =====================================================================
+
+// --- start ---
+program
+  .command('start')
+  .description('Launch Claude Code with ClaudeTeach — starts bridge server + loads teaching skills')
+  .option('--no-server', 'Skip starting the bridge server')
+  .option('--port <port>', 'Bridge server port', '3456')
+  .allowUnknownOption(true)
+  .action(async (opts, cmd) => {
+    // 1. Resolve plugin
+    const pluginDir = resolvePluginDir();
+    if (!pluginDir) {
+      console.error(chalk.red('Could not find the ClaudeTeach plugin directory.'));
+      console.error('Make sure @shaykec/plugin is installed or you are in the ClaudeTeach repo.');
+      process.exit(1);
+    }
+
+    // 2. Check claude
+    const claude = findClaude();
+    if (!claude.found) {
+      console.error(chalk.red('Claude Code CLI not found.'));
+      console.error('Install it from: https://claude.ai/download');
+      process.exit(1);
+    }
+
+    // 3. Start bridge server (unless --no-server)
+    let server;
+    if (opts.server !== false) {
+      try {
+        const { startServer } = await import('@shaykec/bridge');
+        server = startServer({
+          port: parseInt(opts.port, 10),
+          progressProvider: { getProgress: () => loadProgress(ROOT) },
+        });
+        console.log(chalk.dim(`  Bridge server on port ${opts.port}`));
+      } catch (err) {
+        console.warn(chalk.yellow(`  Bridge server failed to start: ${err.message}`));
+      }
+    }
+
+    // 4. Launch
+    console.log(chalk.green('Launching Claude Code with ClaudeTeach...'));
+    console.log(chalk.dim(`  Plugin: ${pluginDir}`));
+
+    const claudeArgs = ['--plugin-dir', pluginDir, ...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('close', (code) => {
+      if (server) server.close();
+      process.exit(code ?? 0);
+    });
+  });
+
+// --- setup ---
+program
+  .command('setup')
+  .description('Check environment, show plugin status, and install Chrome extension')
+  .option('--show-path', 'Print only the plugin directory path')
+  .option('--extension', 'Open Chrome to install the ClaudeTeach extension')
+  .action(async (opts) => {
+    const pluginDir = resolvePluginDir();
+    const extensionDir = resolveExtensionDir();
+
+    // --show-path: machine-readable plugin path
+    if (opts.showPath) {
+      if (!pluginDir) process.exit(1);
+      console.log(pluginDir);
+      return;
+    }
+
+    // --extension: open Finder + Chrome extensions page
+    if (opts.extension) {
+      if (!extensionDir) {
+        console.error(chalk.red('Could not find the ClaudeTeach extension directory.'));
+        process.exit(1);
+      }
+      openExtensionInstall(extensionDir);
+      console.log(chalk.green('\nChrome Extensions page + extension folder opened.'));
+      console.log(`\n  1. Enable ${chalk.cyan('Developer mode')} (toggle, top-right)`);
+      console.log(`  2. Click ${chalk.cyan('Load unpacked')}`);
+      console.log(`  3. Select the folder that just opened: ${chalk.cyan(extensionDir)}`);
+      return;
+    }
+
+    // Default: full setup — checklist + welcome page
+    const claude = findClaude();
+
+    console.log(chalk.bold('\n  ClaudeTeach Setup\n'));
+    console.log(`  Plugin path:    ${pluginDir ? chalk.green(pluginDir) : chalk.red('not found')}`);
+    console.log(`  Extension path: ${extensionDir ? chalk.green(extensionDir) : chalk.red('not found')}`);
+    console.log(`  Claude Code:    ${claude.found ? chalk.green(claude.version) : chalk.red('not installed')}`);
+
+    if (!pluginDir) {
+      console.error(chalk.red('\n  Plugin not found. Make sure @shaykec/plugin is installed.'));
+      process.exit(1);
+    }
+
+    if (!claude.found) {
+      console.log(chalk.yellow('\n  Claude Code not found. Install from: https://claude.ai/download'));
+    }
+
+    // Start bridge + open welcome page
+    let server;
+    try {
+      const { startServer } = await import('@shaykec/bridge');
+      const port = 3456;
+      server = startServer({
+        port,
+        progressProvider: { getProgress: () => loadProgress(ROOT) },
+      });
+      console.log(chalk.dim(`\n  Bridge server started on port ${port}`));
+      openUrl(`http://localhost:${port}/?mode=welcome`);
+      console.log(chalk.green('  Welcome page opened in your browser.'));
+    } catch (err) {
+      console.warn(chalk.yellow(`\n  Could not start bridge server: ${err.message}`));
+    }
+
+    console.log(chalk.bold('\n  Next steps:\n'));
+    console.log(`  ${chalk.cyan('claude-teach start')}               Launch Claude Code with teaching skills`);
+    console.log(`  ${chalk.cyan('claude-teach setup --extension')}    Install the Chrome extension`);
+    console.log();
+  });
+
 // =====================================================================
 //  System commands
 // =====================================================================