@shaykec/claude-teach 0.2.0

package/src/author.js

@@ -0,0 +1,355 @@
+/**
+ * Module authoring tools — scaffold, validate, and preview module packs.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, symlinkSync, rmSync, statSync } from 'fs';
+import { join, resolve, basename } from 'path';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+import { ensureHome, LOCAL_MODULES } from './marketplace.js';
+
+/* ------------------------------------------------------------------ */
+/*  Scaffold a new module pack                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Create a new module pack directory with the required structure.
+ *   <cwd>/<name>/
+ *     pack.yaml
+ *     modules/
+ *     README.md
+ */
+export async function initPack(name) {
+  const dest = resolve(process.cwd(), name);
+
+  if (existsSync(dest)) {
+    throw new Error(`Directory "${name}" already exists.`);
+  }
+
+  mkdirSync(join(dest, 'modules'), { recursive: true });
+
+  const packYaml = {
+    name,
+    author: '',
+    description: '',
+    version: '1.0.0',
+    modules: [],
+  };
+
+  writeFileSync(
+    join(dest, 'pack.yaml'),
+    yaml.dump(packYaml, { lineWidth: 120 }),
+    'utf-8',
+  );
+
+  writeFileSync(
+    join(dest, 'README.md'),
+    [
+      `# ${name}`,
+      '',
+      'A ClaudeTeach module pack.',
+      '',
+      '## Modules',
+      '',
+      '_None yet. Run `claude-teach author add <pack>/<module>` to add one._',
+      '',
+      '## Install',
+      '',
+      '```bash',
+      `claude-teach install <your-git-url>`,
+      '```',
+      '',
+    ].join('\n'),
+    'utf-8',
+  );
+
+  console.log(chalk.green(`Pack "${name}" scaffolded at ${dest}`));
+  console.log(`  Next: cd ${name} && claude-teach author add ${name}/my-module`);
+}
+
+/* ------------------------------------------------------------------ */
+/*  Add a module to a pack                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Add a new module inside an existing pack.
+ *   <packPath>/modules/<moduleName>/
+ *     module.yaml
+ *     content.md
+ *
+ * @param {string} packPath  — path to the pack directory
+ * @param {string} moduleName — slug for the new module
+ */
+export async function addModule(packPath, moduleName) {
+  const absPackPath = resolve(process.cwd(), packPath);
+
+  if (!existsSync(join(absPackPath, 'pack.yaml'))) {
+    throw new Error(`No pack.yaml found at "${absPackPath}". Is this a module pack?`);
+  }
+
+  const moduleDir = join(absPackPath, 'modules', moduleName);
+  if (existsSync(moduleDir)) {
+    throw new Error(`Module "${moduleName}" already exists in this pack.`);
+  }
+
+  mkdirSync(moduleDir, { recursive: true });
+
+  const moduleYaml = {
+    slug: moduleName,
+    title: moduleName.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+    version: '1.0.0',
+    description: '',
+    category: 'uncategorized',
+    tags: [],
+    difficulty: 'beginner',
+    xp: { read: 10 },
+    time: { read: 10 },
+    prerequisites: [],
+    related: [],
+    triggers: [],
+  };
+
+  writeFileSync(
+    join(moduleDir, 'module.yaml'),
+    yaml.dump(moduleYaml, { lineWidth: 120 }),
+    'utf-8',
+  );
+
+  writeFileSync(
+    join(moduleDir, 'content.md'),
+    [
+      `# ${moduleYaml.title}`,
+      '',
+      '_Write your module content here._',
+      '',
+    ].join('\n'),
+    'utf-8',
+  );
+
+  // Update pack.yaml modules list
+  const packYamlPath = join(absPackPath, 'pack.yaml');
+  const pack = yaml.load(readFileSync(packYamlPath, 'utf-8')) || {};
+  if (!Array.isArray(pack.modules)) pack.modules = [];
+  if (!pack.modules.includes(moduleName)) {
+    pack.modules.push(moduleName);
+    writeFileSync(packYamlPath, yaml.dump(pack, { lineWidth: 120 }), 'utf-8');
+  }
+
+  console.log(chalk.green(`Module "${moduleName}" added to pack at ${moduleDir}`));
+}
+
+/* ------------------------------------------------------------------ */
+/*  Validate a pack                                                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Validate a module pack for correctness.
+ *
+ * Checks:
+ *   - pack.yaml exists and has required fields (name, version)
+ *   - Each listed module has a directory with module.yaml
+ *   - Each module.yaml has required fields (slug, title)
+ *   - Referenced files (content.md, walkthrough.md, etc.) exist
+ *   - XP values are numbers
+ *   - Triggers are arrays
+ *   - Prerequisites reference valid slugs (within pack or built-in)
+ *
+ * @param {string} packPath — path to the pack directory
+ * @param {string[]} [builtinSlugs] — optional list of built-in module slugs for prereq validation
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+export async function validatePack(packPath, builtinSlugs = []) {
+  const absPath = resolve(process.cwd(), packPath);
+  const errors = [];
+  const warnings = [];
+
+  // 1. pack.yaml
+  const packYamlPath = join(absPath, 'pack.yaml');
+  if (!existsSync(packYamlPath)) {
+    errors.push('Missing pack.yaml');
+    return { valid: false, errors, warnings };
+  }
+
+  let pack;
+  try {
+    pack = yaml.load(readFileSync(packYamlPath, 'utf-8'));
+  } catch (err) {
+    errors.push(`pack.yaml parse error: ${err.message}`);
+    return { valid: false, errors, warnings };
+  }
+
+  if (!pack.name) errors.push('pack.yaml: missing "name" field');
+  if (!pack.version) warnings.push('pack.yaml: missing "version" field');
+  if (!pack.author) warnings.push('pack.yaml: missing "author" field');
+  if (!pack.description) warnings.push('pack.yaml: missing "description" field');
+
+  // 2. Modules directory
+  const modulesDir = join(absPath, 'modules');
+  if (!existsSync(modulesDir)) {
+    errors.push('Missing modules/ directory');
+    return { valid: errors.length === 0, errors, warnings };
+  }
+
+  const listedModules = Array.isArray(pack.modules) ? pack.modules : [];
+  const allPackSlugs = [];
+
+  // Scan actual module directories
+  const actualDirs = readdirSync(modulesDir).filter(name => {
+    const full = join(modulesDir, name);
+    return existsSync(full) && statSync(full).isDirectory();
+  });
+
+  // Warn about modules listed in pack.yaml but not found on disk
+  for (const listed of listedModules) {
+    if (!actualDirs.includes(listed)) {
+      errors.push(`Module "${listed}" is listed in pack.yaml but has no directory`);
+    }
+  }
+
+  // Warn about directories not listed in pack.yaml
+  for (const dir of actualDirs) {
+    if (!listedModules.includes(dir)) {
+      warnings.push(`Directory "modules/${dir}" exists but is not listed in pack.yaml`);
+    }
+  }
+
+  // 3. Validate each module directory
+  for (const dirName of actualDirs) {
+    const moduleDir = join(modulesDir, dirName);
+    const moduleYamlPath = join(moduleDir, 'module.yaml');
+
+    if (!existsSync(moduleYamlPath)) {
+      errors.push(`modules/${dirName}: missing module.yaml`);
+      continue;
+    }
+
+    let mod;
+    try {
+      mod = yaml.load(readFileSync(moduleYamlPath, 'utf-8'));
+    } catch (err) {
+      errors.push(`modules/${dirName}/module.yaml: parse error — ${err.message}`);
+      continue;
+    }
+
+    const slug = mod.slug || dirName;
+    allPackSlugs.push(slug);
+
+    if (!mod.slug) warnings.push(`modules/${dirName}: missing "slug" field`);
+    if (!mod.title) errors.push(`modules/${dirName}: missing "title" field`);
+
+    // content.md must exist
+    if (!existsSync(join(moduleDir, 'content.md'))) {
+      errors.push(`modules/${dirName}: missing content.md`);
+    }
+
+    // Optional files — warn if referenced but missing (via capabilities detection)
+    for (const opt of ['walkthrough.md', 'exercises.md', 'quiz.md', 'quick-ref.md']) {
+      // We don't error if optional files are missing — they're optional.
+      // But we do check if referenced in visuals or similar.
+    }
+
+    // XP values must be numbers
+    if (mod.xp && typeof mod.xp === 'object') {
+      for (const [key, val] of Object.entries(mod.xp)) {
+        if (typeof val !== 'number') {
+          errors.push(`modules/${dirName}: xp.${key} must be a number, got ${typeof val}`);
+        }
+      }
+    }
+
+    // Triggers must be an array
+    if (mod.triggers !== undefined && !Array.isArray(mod.triggers)) {
+      errors.push(`modules/${dirName}: triggers must be an array`);
+    }
+
+    // Time values must be numbers
+    if (mod.time && typeof mod.time === 'object') {
+      for (const [key, val] of Object.entries(mod.time)) {
+        if (typeof val !== 'number') {
+          errors.push(`modules/${dirName}: time.${key} must be a number, got ${typeof val}`);
+        }
+      }
+    }
+  }
+
+  // 4. Validate prerequisites
+  const validSlugs = new Set([...allPackSlugs, ...builtinSlugs]);
+  for (const dirName of actualDirs) {
+    const moduleYamlPath = join(modulesDir, dirName, 'module.yaml');
+    if (!existsSync(moduleYamlPath)) continue;
+    try {
+      const mod = yaml.load(readFileSync(moduleYamlPath, 'utf-8'));
+      const prereqs = mod.prerequisites || [];
+      for (const prereq of prereqs) {
+        if (!validSlugs.has(prereq)) {
+          warnings.push(`modules/${dirName}: prerequisite "${prereq}" not found in pack or built-in modules`);
+        }
+      }
+    } catch {
+      // Already reported parse error above
+    }
+  }
+
+  const valid = errors.length === 0;
+  return { valid, errors, warnings };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Preview a module locally                                           */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Preview a module by copying/symlinking it to ~/.claude-teach/modules/local/_preview/.
+ *
+ * @param {string} modulePath — path to a module directory (must contain module.yaml)
+ */
+export async function previewModule(modulePath) {
+  ensureHome();
+
+  const absPath = resolve(process.cwd(), modulePath);
+
+  if (!existsSync(join(absPath, 'module.yaml'))) {
+    throw new Error(`No module.yaml found at "${absPath}". Point to a module directory.`);
+  }
+
+  const previewDir = join(LOCAL_MODULES, '_preview');
+  if (!existsSync(previewDir)) {
+    mkdirSync(previewDir, { recursive: true });
+  }
+
+  const moduleName = basename(absPath);
+  const dest = join(previewDir, moduleName);
+
+  // Remove previous preview of the same module
+  if (existsSync(dest)) {
+    rmSync(dest, { recursive: true, force: true });
+  }
+
+  // Try symlink first, fall back to copy
+  try {
+    symlinkSync(absPath, dest, 'dir');
+  } catch {
+    // Symlink failed (e.g. Windows without admin), copy instead
+    copyDirRecursive(absPath, dest);
+  }
+
+  console.log(chalk.green(`Previewing "${moduleName}" — available in the module registry.`));
+  console.log(`  Run ${chalk.cyan('claude-teach list')} to verify.`);
+  console.log(`  To stop previewing, delete ${dest}`);
+}
+
+/**
+ * Simple recursive directory copy (no external deps).
+ */
+function copyDirRecursive(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      writeFileSync(destPath, readFileSync(srcPath));
+    }
+  }
+}

package/src/bridge-server.js

@@ -0,0 +1,60 @@
+/**
+ * DEPRECATED — Bridge server has moved to @shaykec/bridge.
+ *
+ * This file is preserved for backward compatibility.
+ * The `serve` command in cli.js now uses the new bridge package.
+ * The `showInbox` function is re-exported from the new location.
+ *
+ * Migration:
+ *   Old: import { startServer } from './bridge-server.js'
+ *   New: import { startServer } from '@shaykec/bridge'
+ */
+
+import { readFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const INBOX_DIR = '.teach/inbox';
+
+/**
+ * Start the bridge server — delegates to @shaykec/bridge.
+ * @deprecated Use `import { startServer } from '@shaykec/bridge'` instead.
+ */
+export async function startServer(port = 3456) {
+  const { startServer: start } = await import('@shaykec/bridge');
+  return start({ port });
+}
+
+/**
+ * Show inbox contents.
+ * Preserved here since the inbox command still references this file.
+ */
+export function showInbox() {
+  ensureInboxDir();
+
+  const files = readdirSync(INBOX_DIR).filter(f => f.endsWith('.json')).sort();
+
+  if (files.length === 0) {
+    console.log('Inbox is empty. Start the bridge server and capture content from your browser.');
+    return;
+  }
+
+  console.log(`\n  Inbox (${files.length} items)\n`);
+  for (const file of files) {
+    try {
+      const data = JSON.parse(readFileSync(join(INBOX_DIR, file), 'utf-8'));
+      const title = data.title || 'Untitled';
+      const url = data.url || '';
+      console.log(`  \u2022 ${title}`);
+      if (url) console.log(`    ${url}`);
+    } catch {
+      console.log(`  \u2022 ${file} (unreadable)`);
+    }
+  }
+  console.log();
+}
+
+function ensureInboxDir() {
+  if (!existsSync(INBOX_DIR)) {
+    mkdirSync(INBOX_DIR, { recursive: true });
+  }
+}