@shaykec/core 0.1.0

package/src/marketplace.js

@@ -0,0 +1,349 @@
+/**
+ * Module Marketplace — install, update, remove, and search module packs.
+ *
+ * Packs are git repos cloned into ~/.claude-teach/modules/<pack-name>/.
+ * Registries are remote repos listing available packs for discovery.
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, rmSync } from 'fs';
+import { join, basename } from 'path';
+import { execFileSync } from 'child_process';
+import { homedir } from 'os';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+
+/* ------------------------------------------------------------------ */
+/*  Paths                                                              */
+/* ------------------------------------------------------------------ */
+
+const TEACH_HOME = join(homedir(), '.claude-teach');
+const MODULES_HOME = join(TEACH_HOME, 'modules');
+const LOCAL_MODULES = join(MODULES_HOME, 'local');
+const CONFIG_PATH = join(TEACH_HOME, 'config.yaml');
+
+const DEFAULT_REGISTRY = {
+  name: 'default',
+  url: 'https://github.com/shayke-cohen/claudeteach-registry',
+  enabled: true,
+};
+
+/* ------------------------------------------------------------------ */
+/*  Internal helpers                                                    */
+/* ------------------------------------------------------------------ */
+
+/** Ensure the ~/.claude-teach/ directory tree exists. */
+export function ensureHome() {
+  if (!existsSync(TEACH_HOME)) mkdirSync(TEACH_HOME, { recursive: true });
+  if (!existsSync(MODULES_HOME)) mkdirSync(MODULES_HOME, { recursive: true });
+  if (!existsSync(LOCAL_MODULES)) mkdirSync(LOCAL_MODULES, { recursive: true });
+}
+
+/** Load ~/.claude-teach/config.yaml (create with defaults if missing). */
+export function loadConfig() {
+  ensureHome();
+  if (!existsSync(CONFIG_PATH)) {
+    const defaults = { registries: [DEFAULT_REGISTRY] };
+    writeFileSync(CONFIG_PATH, yaml.dump(defaults, { lineWidth: 120 }), 'utf-8');
+    return defaults;
+  }
+  try {
+    return yaml.load(readFileSync(CONFIG_PATH, 'utf-8')) || { registries: [DEFAULT_REGISTRY] };
+  } catch {
+    return { registries: [DEFAULT_REGISTRY] };
+  }
+}
+
+/** Persist config back to disk. */
+function saveConfig(config) {
+  ensureHome();
+  writeFileSync(CONFIG_PATH, yaml.dump(config, { lineWidth: 120, noRefs: true }), 'utf-8');
+}
+
+/**
+ * Normalise a URL or GitHub shorthand into a full git clone URL.
+ * Supports:
+ *   - Full HTTPS URL (https://github.com/user/repo)
+ *   - GitHub shorthand (user/repo)
+ */
+function normaliseUrl(urlOrShorthand) {
+  if (/^https?:\/\//.test(urlOrShorthand)) {
+    return urlOrShorthand.replace(/\/+$/, '');
+  }
+  if (/^[\w.-]+\/[\w.-]+$/.test(urlOrShorthand)) {
+    return `https://github.com/${urlOrShorthand}`;
+  }
+  throw new Error(`Invalid URL or shorthand: "${urlOrShorthand}". Use a full URL or GitHub shorthand (user/repo).`);
+}
+
+/** Derive a pack name from a git URL (last path segment, sans .git). */
+function packNameFromUrl(url) {
+  const last = basename(url.replace(/\/+$/, ''));
+  return last.replace(/\.git$/, '');
+}
+
+/** Verify git is available. */
+function requireGit() {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'pipe' });
+  } catch {
+    throw new Error('git is not installed or not in PATH. Install git and try again.');
+  }
+}
+
+/**
+ * Convert a GitHub repo URL to a raw content URL for fetching files.
+ * e.g. https://github.com/user/repo -> https://raw.githubusercontent.com/user/repo/main/
+ */
+function rawContentBase(repoUrl) {
+  const cleaned = repoUrl.replace(/\/+$/, '').replace(/\.git$/, '');
+  const match = cleaned.match(/github\.com\/(.+)/);
+  if (!match) return null;
+  return `https://raw.githubusercontent.com/${match[1]}/main/`;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Pack management                                                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Install a module pack from a git URL or GitHub shorthand.
+ * Clones to ~/.claude-teach/modules/<pack-name>/ and validates pack.yaml.
+ */
+export async function installPack(urlOrShorthand) {
+  ensureHome();
+  requireGit();
+
+  const url = normaliseUrl(urlOrShorthand);
+  const name = packNameFromUrl(url);
+  const dest = join(MODULES_HOME, name);
+
+  if (name === 'local') {
+    throw new Error('"local" is reserved for user-authored modules. Choose a different pack name.');
+  }
+
+  if (existsSync(dest)) {
+    throw new Error(`Pack "${name}" is already installed at ${dest}. Use "update" to pull latest.`);
+  }
+
+  console.log(chalk.blue(`Cloning ${url} ...`));
+  try {
+    execFileSync('git', ['clone', '--depth', '1', url, dest], { stdio: 'pipe' });
+  } catch (err) {
+    throw new Error(`git clone failed: ${err.stderr?.toString().trim() || err.message}`);
+  }
+
+  // Validate pack.yaml
+  const packYaml = join(dest, 'pack.yaml');
+  if (!existsSync(packYaml)) {
+    // Clean up
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error(`Invalid module pack: no pack.yaml found in ${url}`);
+  }
+
+  let pack;
+  try {
+    pack = yaml.load(readFileSync(packYaml, 'utf-8'));
+  } catch (err) {
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error(`Invalid pack.yaml: ${err.message}`);
+  }
+
+  if (!pack.name) {
+    rmSync(dest, { recursive: true, force: true });
+    throw new Error('pack.yaml is missing the required "name" field.');
+  }
+
+  const moduleCount = Array.isArray(pack.modules) ? pack.modules.length : 0;
+  console.log(chalk.green(`Installed "${pack.name}" (${moduleCount} module${moduleCount !== 1 ? 's' : ''}).`));
+  return pack;
+}
+
+/**
+ * List all installed module packs.
+ * Reads ~/.claude-teach/modules/STAR/pack.yaml (skips the local directory).
+ */
+export async function listPacks() {
+  ensureHome();
+  const packs = [];
+
+  if (!existsSync(MODULES_HOME)) return packs;
+
+  for (const entry of readdirSync(MODULES_HOME)) {
+    if (entry === 'local') continue;
+    const packDir = join(MODULES_HOME, entry);
+    const packYaml = join(packDir, 'pack.yaml');
+    if (!existsSync(packYaml)) continue;
+
+    try {
+      const data = yaml.load(readFileSync(packYaml, 'utf-8'));
+      packs.push({
+        name: data.name || entry,
+        author: data.author || 'unknown',
+        description: data.description || '',
+        version: data.version || '0.0.0',
+        modules: data.modules || [],
+        path: packDir,
+      });
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return packs;
+}
+
+/**
+ * Update an installed pack by running git pull.
+ */
+export async function updatePack(packName) {
+  ensureHome();
+  requireGit();
+
+  const dest = join(MODULES_HOME, packName);
+  if (!existsSync(dest)) {
+    throw new Error(`Pack "${packName}" is not installed.`);
+  }
+  if (packName === 'local') {
+    throw new Error('"local" is your custom modules directory and cannot be updated via git.');
+  }
+
+  console.log(chalk.blue(`Updating "${packName}" ...`));
+  try {
+    execFileSync('git', ['-C', dest, 'pull', '--ff-only'], { stdio: 'pipe' });
+  } catch (err) {
+    throw new Error(`git pull failed: ${err.stderr?.toString().trim() || err.message}`);
+  }
+
+  console.log(chalk.green(`Pack "${packName}" updated.`));
+}
+
+/**
+ * Remove an installed pack.
+ */
+export async function removePack(packName) {
+  ensureHome();
+
+  if (packName === 'local') {
+    throw new Error('"local" is your custom modules directory and cannot be removed.');
+  }
+
+  const dest = join(MODULES_HOME, packName);
+  if (!existsSync(dest)) {
+    throw new Error(`Pack "${packName}" is not installed.`);
+  }
+
+  rmSync(dest, { recursive: true, force: true });
+  console.log(chalk.green(`Pack "${packName}" removed.`));
+}
+
+/**
+ * Search configured registries for packs matching a query.
+ * Fetches registry.yaml from each enabled registry's raw GitHub content.
+ */
+export async function searchPacks(query) {
+  const config = loadConfig();
+  const registries = (config.registries || []).filter(r => r.enabled !== false);
+  const results = [];
+  const q = query.toLowerCase();
+
+  for (const reg of registries) {
+    const base = rawContentBase(reg.url);
+    if (!base) {
+      console.warn(chalk.yellow(`Skipping non-GitHub registry: ${reg.url}`));
+      continue;
+    }
+
+    const registryUrl = `${base}registry.yaml`;
+
+    try {
+      const resp = await fetch(registryUrl);
+      if (!resp.ok) {
+        console.warn(chalk.yellow(`Registry "${reg.name || reg.url}" returned HTTP ${resp.status}`));
+        continue;
+      }
+      const text = await resp.text();
+      const data = yaml.load(text);
+      const packs = data?.packs || data?.modules || [];
+
+      for (const pack of packs) {
+        const searchable = [
+          pack.name || '',
+          pack.description || '',
+          ...(pack.tags || []),
+          pack.author || '',
+        ].join(' ').toLowerCase();
+
+        if (searchable.includes(q)) {
+          results.push({
+            ...pack,
+            registry: reg.name || reg.url,
+          });
+        }
+      }
+    } catch (err) {
+      console.warn(chalk.yellow(`Failed to fetch from "${reg.name || reg.url}": ${err.message}`));
+    }
+  }
+
+  return results;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Registry configuration                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Get the list of configured registries.
+ */
+export function getRegistries() {
+  const config = loadConfig();
+  return config.registries || [];
+}
+
+/**
+ * Add a registry by URL or GitHub shorthand.
+ */
+export function addRegistry(urlOrShorthand) {
+  const config = loadConfig();
+  const url = normaliseUrl(urlOrShorthand);
+  const name = packNameFromUrl(url);
+
+  if (!config.registries) config.registries = [];
+
+  const existing = config.registries.find(r => r.url === url || r.name === name);
+  if (existing) {
+    throw new Error(`Registry "${name}" is already configured.`);
+  }
+
+  config.registries.push({ name, url, enabled: true });
+  saveConfig(config);
+  console.log(chalk.green(`Registry "${name}" added.`));
+}
+
+/**
+ * Remove a registry by name or URL.
+ */
+export function removeRegistry(nameOrUrl) {
+  const config = loadConfig();
+  if (!config.registries) {
+    throw new Error('No registries configured.');
+  }
+
+  const idx = config.registries.findIndex(
+    r => r.name === nameOrUrl || r.url === nameOrUrl
+  );
+
+  if (idx === -1) {
+    throw new Error(`Registry "${nameOrUrl}" not found.`);
+  }
+
+  const removed = config.registries.splice(idx, 1)[0];
+  saveConfig(config);
+  console.log(chalk.green(`Registry "${removed.name || removed.url}" removed.`));
+}
+
+/* ------------------------------------------------------------------ */
+/*  Exports for registry.js integration                                */
+/* ------------------------------------------------------------------ */
+
+export { TEACH_HOME, MODULES_HOME, LOCAL_MODULES };

package/src/progress.js

@@ -0,0 +1,157 @@
+/**
+ * Unified progress store — reads/writes .teach-progress.yaml
+ * Stores both tutorial state and gamification state.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+
+const PROGRESS_FILE = '.teach-progress.yaml';
+
+/**
+ * Load progress from .teach-progress.yaml in the project root.
+ * Returns a default structure if the file doesn't exist.
+ */
+export function loadProgress(rootDir) {
+  const filePath = join(rootDir, PROGRESS_FILE);
+  if (!existsSync(filePath)) {
+    return defaultProgress();
+  }
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data = yaml.load(raw);
+    return data || defaultProgress();
+  } catch {
+    return defaultProgress();
+  }
+}
+
+/**
+ * Save progress to .teach-progress.yaml.
+ */
+export function saveProgress(rootDir, progress) {
+  const filePath = join(rootDir, PROGRESS_FILE);
+  const out = yaml.dump(progress, { lineWidth: 120, noRefs: true });
+  writeFileSync(filePath, out, 'utf-8');
+}
+
+/**
+ * Record XP earned for a module activity.
+ */
+export function recordXP(rootDir, slug, activity, xpAmount) {
+  const progress = loadProgress(rootDir);
+
+  if (!progress.modules[slug]) {
+    progress.modules[slug] = {
+      status: 'in-progress',
+      started: new Date().toISOString().split('T')[0],
+      last_session: new Date().toISOString().split('T')[0],
+      xp_earned: 0,
+    };
+  }
+
+  const mod = progress.modules[slug];
+  mod.last_session = new Date().toISOString().split('T')[0];
+  mod.xp_earned = (mod.xp_earned || 0) + xpAmount;
+
+  progress.user.xp = (progress.user.xp || 0) + xpAmount;
+
+  // Recount completed modules
+  progress.user.modules_completed = Object.values(progress.modules)
+    .filter(m => m.status === 'completed')
+    .length;
+
+  saveProgress(rootDir, progress);
+  return progress;
+}
+
+/**
+ * Mark a module as completed.
+ */
+export function completeModule(rootDir, slug) {
+  const progress = loadProgress(rootDir);
+
+  if (!progress.modules[slug]) {
+    progress.modules[slug] = {
+      started: new Date().toISOString().split('T')[0],
+      xp_earned: 0,
+    };
+  }
+
+  progress.modules[slug].status = 'completed';
+  progress.modules[slug].completed = new Date().toISOString().split('T')[0];
+
+  progress.user.modules_completed = Object.values(progress.modules)
+    .filter(m => m.status === 'completed')
+    .length;
+
+  saveProgress(rootDir, progress);
+  return progress;
+}
+
+/**
+ * Update walkthrough step for a module.
+ */
+export function updateWalkthroughStep(rootDir, slug, step) {
+  const progress = loadProgress(rootDir);
+
+  if (!progress.modules[slug]) {
+    progress.modules[slug] = {
+      status: 'in-progress',
+      started: new Date().toISOString().split('T')[0],
+      xp_earned: 0,
+    };
+  }
+
+  progress.modules[slug].walkthrough_step = step;
+  progress.modules[slug].last_session = new Date().toISOString().split('T')[0];
+
+  saveProgress(rootDir, progress);
+  return progress;
+}
+
+/**
+ * Record a quiz score for a module.
+ */
+export function recordQuizScore(rootDir, slug, score) {
+  const progress = loadProgress(rootDir);
+
+  if (!progress.modules[slug]) {
+    progress.modules[slug] = {
+      status: 'in-progress',
+      started: new Date().toISOString().split('T')[0],
+      xp_earned: 0,
+    };
+  }
+
+  progress.modules[slug].quiz_score = score;
+  progress.modules[slug].last_session = new Date().toISOString().split('T')[0];
+
+  saveProgress(rootDir, progress);
+  return progress;
+}
+
+/**
+ * Get summary stats from progress.
+ */
+export function getStats(progress) {
+  return {
+    xp: progress.user?.xp || 0,
+    belt: progress.user?.belt || 'white',
+    modulesCompleted: progress.user?.modules_completed || 0,
+    modulesInProgress: Object.values(progress.modules || {})
+      .filter(m => m.status === 'in-progress').length,
+  };
+}
+
+function defaultProgress() {
+  return {
+    user: {
+      xp: 0,
+      belt: 'white',
+      modules_completed: 0,
+    },
+    modules: {},
+  };
+}