chub-dev 0.1.0

package/bin/chub

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "chub-dev",
+  "version": "0.1.0",
+  "description": "CLI for Context Hub - search and retrieve LLM-optimized docs and skills",
+  "type": "module",
+  "bin": {
+    "chub": "./bin/chub"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "documentation",
+    "agent",
+    "cli",
+    "context",
+    "skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andrewyng/context-hub"
+  },
+  "bugs": {
+    "url": "https://github.com/andrewyng/context-hub/issues"
+  },
+  "homepage": "https://github.com/andrewyng/context-hub#readme",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "yaml": "^2.3.0",
+    "tar": "^7.0.0"
+  }
+}

package/src/commands/build.js

@@ -0,0 +1,321 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, cpSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import chalk from 'chalk';
+import { parseFrontmatter } from '../lib/frontmatter.js';
+import { info } from '../lib/output.js';
+
+/**
+ * Recursively find all DOC.md and SKILL.md files under a directory.
+ */
+function findEntryFiles(dir, base = dir) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findEntryFiles(full, base));
+    } else if (entry.name === 'DOC.md' || entry.name === 'SKILL.md') {
+      results.push({ path: full, relPath: relative(base, full), type: entry.name === 'SKILL.md' ? 'skill' : 'doc' });
+    }
+  }
+  return results;
+}
+
+/**
+ * Get all files in a directory (relative to that directory).
+ */
+function listDirFiles(dir) {
+  const results = [];
+  const walk = (d) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else results.push(relative(dir, full));
+    }
+  };
+  walk(dir);
+  return results;
+}
+
+/**
+ * Compute total size of all files in a directory.
+ */
+function dirSize(dir) {
+  let total = 0;
+  const walk = (d) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else total += statSync(full).size;
+    }
+  };
+  walk(dir);
+  return total;
+}
+
+/**
+ * Process an author directory with auto-discovery.
+ */
+function discoverAuthor(authorDir, authorName, contentDir) {
+  const entryFiles = findEntryFiles(authorDir);
+  const docs = new Map(); // name → { description, source, tags, languages: Map<lang, versions[]> }
+  const skills = new Map(); // name → skill entry
+  const warnings = [];
+  const errors = [];
+
+  for (const ef of entryFiles) {
+    const content = readFileSync(ef.path, 'utf8');
+    const { attributes } = parseFrontmatter(content);
+
+    if (!attributes.name) {
+      errors.push(`${ef.relPath}: missing 'name' in frontmatter`);
+      continue;
+    }
+    if (!attributes.description) {
+      warnings.push(`${ef.relPath}: missing 'description' in frontmatter`);
+    }
+
+    const meta = attributes.metadata || {};
+    const name = attributes.name;
+    const description = attributes.description || '';
+    const source = meta.source || 'community';
+    const tags = meta.tags ? meta.tags.split(',').map((t) => t.trim()) : [];
+    const updatedOn = meta['updated-on'] || new Date().toISOString().split('T')[0];
+    const entryDir = dirname(ef.path);
+    const entryPath = relative(contentDir, entryDir);
+    const files = listDirFiles(entryDir);
+    const size = dirSize(entryDir);
+
+    if (!meta.source) {
+      warnings.push(`${ef.relPath}: missing 'metadata.source', defaulting to 'community'`);
+    }
+
+    if (ef.type === 'skill') {
+      // Skills are flat — no language/version
+      if (skills.has(name)) {
+        errors.push(`${ef.relPath}: duplicate skill name '${name}'`);
+        continue;
+      }
+      skills.set(name, {
+        id: `${authorName}/${name}`,
+        name,
+        description,
+        source,
+        tags,
+        path: entryPath,
+        files,
+        size,
+        lastUpdated: updatedOn,
+      });
+    } else {
+      // Docs need language and version
+      const languages = meta.languages
+        ? meta.languages.split(',').map((l) => l.trim().toLowerCase())
+        : null;
+      const versions = meta.versions
+        ? meta.versions.split(',').map((v) => v.trim())
+        : null;
+
+      if (!languages || languages.length === 0) {
+        errors.push(`${ef.relPath}: missing 'metadata.languages' in frontmatter`);
+        continue;
+      }
+      if (!versions || versions.length === 0) {
+        errors.push(`${ef.relPath}: missing 'metadata.versions' in frontmatter`);
+        continue;
+      }
+
+      if (!docs.has(name)) {
+        docs.set(name, { description, source, tags, languages: new Map() });
+      }
+
+      const doc = docs.get(name);
+
+      for (const lang of languages) {
+        if (!doc.languages.has(lang)) {
+          doc.languages.set(lang, []);
+        }
+        for (const ver of versions) {
+          doc.languages.get(lang).push({
+            version: ver,
+            path: entryPath,
+            files,
+            size,
+            lastUpdated: updatedOn,
+          });
+        }
+      }
+    }
+  }
+
+  // Convert docs map to array format
+  const docsArray = [];
+  for (const [name, doc] of docs) {
+    const languages = [];
+    for (const [lang, versions] of doc.languages) {
+      // Sort versions descending (simple string sort, good enough for semver)
+      versions.sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }));
+      languages.push({
+        language: lang,
+        versions,
+        recommendedVersion: versions[0].version,
+      });
+    }
+    docsArray.push({
+      id: `${authorName}/${name}`,
+      name,
+      description: doc.description,
+      source: doc.source,
+      tags: doc.tags,
+      languages,
+    });
+  }
+
+  return {
+    docs: docsArray,
+    skills: [...skills.values()],
+    warnings,
+    errors,
+  };
+}
+
+export function registerBuildCommand(program) {
+  program
+    .command('build <content-dir>')
+    .description('Build registry.json from a content directory')
+    .option('-o, --output <dir>', 'Output directory')
+    .option('--base-url <url>', 'Base URL for CDN deployment')
+    .option('--validate-only', 'Validate without writing output')
+    .action((contentDir, opts) => {
+      const globalOpts = program.optsWithGlobals();
+
+      if (!existsSync(contentDir)) {
+        process.stderr.write(`Error: Content directory not found: ${contentDir}\n`);
+        process.exit(1);
+      }
+
+      const outputDir = opts.output || join(contentDir, 'dist');
+      const allDocs = [];
+      const allSkills = [];
+      const allWarnings = [];
+      const allErrors = [];
+
+      // List top-level directories (author directories)
+      const topLevel = readdirSync(contentDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name !== 'dist' && !e.name.startsWith('.'));
+
+      for (const authorEntry of topLevel) {
+        const authorDir = join(contentDir, authorEntry.name);
+        const authorRegistry = join(authorDir, 'registry.json');
+
+        if (existsSync(authorRegistry)) {
+          // Author provides registry.json — use it directly
+          try {
+            const reg = JSON.parse(readFileSync(authorRegistry, 'utf8'));
+            // Prefix paths with author dir name
+            if (reg.docs) {
+              for (const doc of reg.docs) {
+                if (!doc.id) doc.id = `${authorEntry.name}/${doc.name}`;
+                else if (!doc.id.includes('/')) doc.id = `${authorEntry.name}/${doc.id}`;
+                for (const lang of doc.languages || []) {
+                  for (const ver of lang.versions || []) {
+                    ver.path = `${authorEntry.name}/${ver.path}`;
+                  }
+                }
+                allDocs.push(doc);
+              }
+            }
+            if (reg.skills) {
+              for (const skill of reg.skills) {
+                if (!skill.id) skill.id = `${authorEntry.name}/${skill.name}`;
+                else if (!skill.id.includes('/')) skill.id = `${authorEntry.name}/${skill.id}`;
+                skill.path = `${authorEntry.name}/${skill.path}`;
+                allSkills.push(skill);
+              }
+            }
+            info(`${authorEntry.name}: loaded registry.json`);
+          } catch (err) {
+            allErrors.push(`${authorEntry.name}/registry.json: ${err.message}`);
+          }
+        } else {
+          // Auto-discover
+          const result = discoverAuthor(authorDir, authorEntry.name, contentDir);
+          allDocs.push(...result.docs);
+          allSkills.push(...result.skills);
+          allWarnings.push(...result.warnings);
+          allErrors.push(...result.errors);
+        }
+      }
+
+      // Check for id collisions (should be rare since ids are author/name)
+      const docIds = new Map();
+      for (const doc of allDocs) {
+        if (docIds.has(doc.id)) {
+          allErrors.push(`Duplicate doc id '${doc.id}'`);
+        }
+        docIds.set(doc.id, true);
+      }
+      const skillIds = new Map();
+      for (const skill of allSkills) {
+        if (skillIds.has(skill.id)) {
+          allErrors.push(`Duplicate skill id '${skill.id}'`);
+        }
+        skillIds.set(skill.id, true);
+      }
+
+      // Print warnings
+      for (const w of allWarnings) {
+        process.stderr.write(chalk.yellow(`Warning: ${w}\n`));
+      }
+
+      // Print errors
+      if (allErrors.length > 0) {
+        for (const e of allErrors) {
+          process.stderr.write(chalk.red(`Error: ${e}\n`));
+        }
+        process.exit(1);
+      }
+
+      const registry = {
+        version: '1.0.0',
+        generated: new Date().toISOString(),
+        docs: allDocs,
+        skills: allSkills,
+      };
+
+      if (opts.baseUrl) {
+        registry.base_url = opts.baseUrl;
+      }
+
+      if (opts.validateOnly) {
+        const summary = { docs: allDocs.length, skills: allSkills.length, warnings: allWarnings.length };
+        if (globalOpts.json) {
+          console.log(JSON.stringify(summary));
+        } else {
+          console.log(chalk.green(`Valid: ${summary.docs} docs, ${summary.skills} skills, ${summary.warnings} warnings`));
+        }
+        return;
+      }
+
+      // Write output
+      mkdirSync(outputDir, { recursive: true });
+      writeFileSync(join(outputDir, 'registry.json'), JSON.stringify(registry, null, 2));
+
+      // Copy content tree
+      for (const authorEntry of topLevel) {
+        const src = join(contentDir, authorEntry.name);
+        const dest = join(outputDir, authorEntry.name);
+        // Skip registry.json in author dirs
+        cpSync(src, dest, {
+          recursive: true,
+          filter: (s) => !s.endsWith('/registry.json') || s === join(src, 'registry.json') === false,
+        });
+      }
+
+      const summary = { docs: allDocs.length, skills: allSkills.length, warnings: allWarnings.length };
+      if (globalOpts.json) {
+        console.log(JSON.stringify({ ...summary, output: outputDir }));
+      } else {
+        console.log(chalk.green(`Built: ${summary.docs} docs, ${summary.skills} skills → ${outputDir}`));
+      }
+    });
+}

package/src/commands/cache.js

@@ -0,0 +1,52 @@
+import chalk from 'chalk';
+import { getCacheStats, clearCache } from '../lib/cache.js';
+import { output } from '../lib/output.js';
+
+export function registerCacheCommand(program) {
+  const cache = program
+    .command('cache')
+    .description('Manage the local cache');
+
+  cache
+    .command('status')
+    .description('Show cache information')
+    .action(() => {
+      const globalOpts = program.optsWithGlobals();
+      const stats = getCacheStats();
+
+      output(stats, (s) => {
+        if (!s.exists || s.sources.length === 0) {
+          console.log(chalk.yellow('No cache found. Run `chub update` to initialize.'));
+          return;
+        }
+        console.log(chalk.bold('Cache Status\n'));
+        for (const src of s.sources) {
+          if (src.type === 'local') {
+            console.log(`  ${chalk.bold(src.name)} ${chalk.dim('(local)')}`);
+            console.log(`    Path: ${src.path}`);
+          } else {
+            console.log(`  ${chalk.bold(src.name)} ${chalk.dim('(remote)')}`);
+            console.log(`    Registry: ${src.hasRegistry ? chalk.green('yes') : chalk.red('no')}`);
+            console.log(`    Last updated: ${src.lastUpdated || 'never'}`);
+            console.log(`    Full bundle: ${src.fullBundle ? 'yes' : 'no'}`);
+            console.log(`    Cached files: ${src.fileCount}`);
+            console.log(`    Size: ${(src.dataSize / 1024).toFixed(1)} KB`);
+          }
+        }
+      }, globalOpts);
+    });
+
+  cache
+    .command('clear')
+    .description('Clear cached data')
+    .option('--force', 'Skip confirmation')
+    .action((opts) => {
+      const globalOpts = program.optsWithGlobals();
+      clearCache();
+      output(
+        { status: 'cleared' },
+        () => console.log(chalk.green('Cache cleared.')),
+        globalOpts
+      );
+    });
+}

package/src/commands/get.js

@@ -0,0 +1,157 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import chalk from 'chalk';
+import { getEntry, resolveDocPath, resolveEntryFile } from '../lib/registry.js';
+import { fetchDoc, fetchDocFull } from '../lib/cache.js';
+import { output, error, info } from '../lib/output.js';
+
+/**
+ * Core fetch logic shared by `get docs` and `get skills`.
+ * @param {string} type - "doc" or "skill"
+ * @param {string[]} ids - one or more entry ids
+ * @param {object} opts - command options (lang, version, output, full)
+ * @param {object} globalOpts - global options (json)
+ */
+async function fetchEntries(type, ids, opts, globalOpts) {
+  const results = [];
+
+  for (const id of ids) {
+    const result = getEntry(id, type);
+
+    if (result.ambiguous) {
+      error(
+        `Multiple entries with id "${id}". Be specific:\n  ${result.alternatives.join('\n  ')}`,
+        globalOpts
+      );
+    }
+
+    if (!result.entry) {
+      error(`Entry "${id}" not found in ${type}s.`, globalOpts);
+    }
+
+    const entry = result.entry;
+    const resolved = resolveDocPath(entry, opts.lang, opts.version);
+
+    if (!resolved) {
+      error(`Could not resolve path for "${id}" ${opts.lang || ''} ${opts.version || ''}`.trim(), globalOpts);
+    }
+
+    if (resolved.needsLanguage) {
+      error(
+        `Multiple languages available for "${id}": ${resolved.available.join(', ')}. Specify --lang.`,
+        globalOpts
+      );
+    }
+
+    const entryFile = resolveEntryFile(resolved, type);
+    if (entryFile.error) {
+      error(`"${id}" ${entryFile.error}`, globalOpts);
+    }
+
+    try {
+      if (opts.full && resolved.files.length > 0) {
+        const allFiles = await fetchDocFull(resolved.source, resolved.path, resolved.files);
+        results.push({ id: entry.id, files: allFiles, path: resolved.path });
+      } else {
+        const content = await fetchDoc(resolved.source, entryFile.filePath);
+        results.push({ id: entry.id, content, path: entryFile.filePath });
+      }
+    } catch (err) {
+      error(err.message, globalOpts);
+    }
+  }
+
+  // Output
+  if (opts.output) {
+    if (opts.full) {
+      // --full -o: write individual files preserving directory structure
+      for (const r of results) {
+        if (r.files) {
+          const baseDir = ids.length > 1 ? join(opts.output, r.id) : opts.output;
+          mkdirSync(baseDir, { recursive: true });
+          for (const f of r.files) {
+            const outPath = join(baseDir, f.name);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, f.content);
+          }
+          info(`Written ${r.files.length} files to ${baseDir}`);
+        } else {
+          const outPath = join(opts.output, `${r.id}.md`);
+          mkdirSync(dirname(outPath), { recursive: true });
+          writeFileSync(outPath, r.content);
+          info(`Written to ${outPath}`);
+        }
+      }
+    } else {
+      const isDir = opts.output.endsWith('/');
+      if (isDir && results.length > 1) {
+        mkdirSync(opts.output, { recursive: true });
+        for (const r of results) {
+          const outPath = join(opts.output, `${r.id}.md`);
+          writeFileSync(outPath, r.content);
+          info(`Written to ${outPath}`);
+        }
+      } else {
+        const outPath = isDir ? join(opts.output, `${results[0].id}.md`) : opts.output;
+        mkdirSync(dirname(outPath), { recursive: true });
+        const combined = results.map((r) => r.content).join('\n\n---\n\n');
+        writeFileSync(outPath, combined);
+        info(`Written to ${outPath}`);
+      }
+    }
+    if (globalOpts.json) {
+      console.log(JSON.stringify(results.map((r) => ({ id: r.id, path: opts.output }))));
+    }
+  } else {
+    // stdout
+    if (results.length === 1 && !results[0].files) {
+      output(
+        { id: results[0].id, content: results[0].content, path: results[0].path },
+        (data) => process.stdout.write(data.content),
+        globalOpts
+      );
+    } else {
+      // Concatenate all content (--full to stdout, or multiple entries)
+      const parts = results.flatMap((r) => {
+        if (r.files) {
+          return r.files.map((f) => `# FILE: ${f.name}\n\n${f.content}`);
+        }
+        return [r.content];
+      });
+      const combined = parts.join('\n\n---\n\n');
+      output(
+        results.map((r) => ({ id: r.id, path: r.path })),
+        () => process.stdout.write(combined),
+        globalOpts
+      );
+    }
+  }
+}
+
+export function registerGetCommand(program) {
+  const get = program
+    .command('get')
+    .description('Retrieve docs or skills');
+
+  get
+    .command('docs <ids...>')
+    .description('Fetch documentation content')
+    .option('--lang <language>', 'Language variant')
+    .option('--version <version>', 'Specific version')
+    .option('-o, --output <path>', 'Write to file or directory')
+    .option('--full', 'Fetch all files (not just entry point)')
+    .action(async (ids, opts) => {
+      const globalOpts = program.optsWithGlobals();
+      await fetchEntries('doc', ids, opts, globalOpts);
+    });
+
+  get
+    .command('skills <ids...>')
+    .description('Fetch skill content')
+    .option('-o, --output <path>', 'Write to file or directory')
+    .option('--full', 'Fetch all files (not just entry point)')
+    .action(async (ids, opts) => {
+      const globalOpts = program.optsWithGlobals();
+      await fetchEntries('skill', ids, opts, globalOpts);
+    });
+}

package/src/commands/search.js

@@ -0,0 +1,105 @@
+import chalk from 'chalk';
+import { searchEntries, listEntries, getEntry, getDisplayId, isMultiSource } from '../lib/registry.js';
+import { displayLanguage } from '../lib/normalize.js';
+import { output } from '../lib/output.js';
+
+function formatEntryList(entries) {
+  const multi = isMultiSource();
+  for (const entry of entries) {
+    const id = getDisplayId(entry);
+    const source = entry.source ? chalk.dim(`[${entry.source}]`) : '';
+    const sourceName = multi ? chalk.cyan(`(${entry._source})`) : '';
+    const type = entry._type === 'skill' ? chalk.magenta('[skill]') : chalk.blue('[doc]');
+    const langs = (entry.languages || []).map((l) => displayLanguage(l.language)).join(', ');
+    const desc = entry.description
+      ? entry.description.length > 60
+        ? entry.description.slice(0, 57) + '...'
+        : entry.description
+      : '';
+    console.log(`  ${chalk.bold(id)}  ${type}  ${chalk.dim(langs)}  ${source} ${sourceName}`.trimEnd());
+    if (desc) console.log(`       ${chalk.dim(desc)}`);
+  }
+}
+
+function formatEntryDetail(entry) {
+  console.log(chalk.bold(entry.name));
+  if (isMultiSource()) console.log(`  Source: ${entry._source}`);
+  if (entry.source) console.log(`  Quality: ${entry.source}`);
+  if (entry.description) console.log(`  ${chalk.dim(entry.description)}`);
+  if (entry.tags?.length) console.log(`  Tags: ${entry.tags.join(', ')}`);
+  console.log();
+  if (entry.languages) {
+    for (const lang of entry.languages) {
+      console.log(`  ${chalk.bold(displayLanguage(lang.language))}`);
+      console.log(`    Recommended: ${lang.recommendedVersion}`);
+      for (const v of lang.versions || []) {
+        const size = v.size ? ` (${(v.size / 1024).toFixed(1)} KB)` : '';
+        console.log(`    ${v.version}${size}  updated: ${v.lastUpdated}`);
+      }
+    }
+  } else {
+    // Skill — flat structure
+    const size = entry.size ? ` (${(entry.size / 1024).toFixed(1)} KB)` : '';
+    console.log(`  Path: ${entry.path}${size}`);
+    if (entry.lastUpdated) console.log(`  Updated: ${entry.lastUpdated}`);
+    if (entry.files?.length) console.log(`  Files: ${entry.files.join(', ')}`);
+  }
+}
+
+export function registerSearchCommand(program) {
+  program
+    .command('search [query]')
+    .description('Search docs and skills (no query lists all)')
+    .option('--tags <tags>', 'Filter by tags (comma-separated)')
+    .option('--lang <language>', 'Filter by language')
+    .option('--limit <n>', 'Max results', '20')
+    .action((query, opts) => {
+      const globalOpts = program.optsWithGlobals();
+      const limit = parseInt(opts.limit, 10);
+
+      // No query: list all
+      if (!query) {
+        const entries = listEntries(opts).slice(0, limit);
+        output({ results: entries, total: entries.length }, (data) => {
+          if (data.results.length === 0) {
+            console.log(chalk.yellow('No entries found.'));
+            return;
+          }
+          console.log(chalk.bold(`${data.total} entries:\n`));
+          formatEntryList(data.results);
+        }, globalOpts);
+        return;
+      }
+
+      // Exact id match: show detail
+      const result = getEntry(query);
+      if (result.ambiguous) {
+        output(
+          { error: 'ambiguous', alternatives: result.alternatives },
+          () => {
+            console.log(chalk.yellow(`Multiple entries with id "${query}". Be specific:`));
+            for (const alt of result.alternatives) {
+              console.log(`  ${chalk.bold(alt)}`);
+            }
+          },
+          globalOpts
+        );
+        return;
+      }
+      if (result.entry) {
+        output(result.entry, formatEntryDetail, globalOpts);
+        return;
+      }
+
+      // Fuzzy search
+      const results = searchEntries(query, opts).slice(0, limit);
+      output({ results, total: results.length, query }, (data) => {
+        if (data.results.length === 0) {
+          console.log(chalk.yellow(`No results for "${query}".`));
+          return;
+        }
+        console.log(chalk.bold(`${data.total} results for "${query}":\n`));
+        formatEntryList(data.results);
+      }, globalOpts);
+    });
+}