chub-dev 0.1.0 → 0.1.2-beta.0

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "chub-dev",
-  "version": "0.1.0",
+  "version": "0.1.2-beta.0",
   "description": "CLI for Context Hub - search and retrieve LLM-optimized docs and skills",
   "type": "module",
   "bin": {
-    "chub": "./bin/chub"
+    "chub": "./bin/chub",
+    "chub-mcp": "./bin/chub-mcp"
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "dist/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -20,7 +23,8 @@
     "agent",
     "cli",
     "context",
-    "skills"
+    "skills",
+    "mcp"
   ],
   "license": "MIT",
   "repository": {
@@ -31,10 +35,22 @@
     "url": "https://github.com/andrewyng/context-hub/issues"
   },
   "homepage": "https://github.com/andrewyng/context-hub#readme",
+  "scripts": {
+    "prepublish": "node bin/chub build ../content -o dist --base-url https://cdn.aichub.org/v1",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
   "dependencies": {
-    "commander": "^12.0.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "posthog-node": "^5.24.17",
+    "tar": "^7.5.8",
     "yaml": "^2.3.0",
-    "tar": "^7.0.0"
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
   }
 }

package/skills/get-api-docs/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: get-api-docs
+description: >
+  Use this skill when you need documentation for a third-party library, SDK, or API
+  before writing code that uses it — for example, "use the OpenAI API", "call the
+  Stripe API", "use the Anthropic SDK", "query Pinecone", or any time the user asks
+  you to write code against an external service and you need current API reference.
+  Fetch the docs with chub before answering, rather than relying on training knowledge.
+---
+
+# Get API Docs via chub
+
+When you need documentation for a library or API, fetch it with the `chub` CLI
+rather than guessing from training data. This gives you the current, correct API.
+
+## Step 1 — Find the right doc ID
+
+```bash
+chub search "<library name>" --json
+```
+
+Pick the best-matching `id` from the results (e.g. `openai/chat`, `anthropic/sdk`,
+`stripe/api`). If nothing matches, try a broader term.
+
+## Step 2 — Fetch the docs
+
+```bash
+chub get <id> --lang py    # or --lang js, --lang ts
+```
+
+Omit `--lang` if the doc has only one language variant — it will be auto-selected.
+
+## Step 3 — Use the docs
+
+Read the fetched content and use it to write accurate code or answer the question.
+Do not rely on memorized API shapes — use what the docs say.
+
+## Step 4 — Annotate what you learned
+
+After completing the task, if you discovered something not in the doc — a gotcha,
+workaround, version quirk, or project-specific detail — save it so future sessions
+start smarter:
+
+```bash
+chub annotate <id> "Webhook verification requires raw body — do not parse before verifying"
+```
+
+Annotations are local, persist across sessions, and appear automatically on future
+`chub get` calls. Keep notes concise and actionable. Don't repeat what's already in
+the doc.
+
+## Step 5 — Give feedback
+
+Rate the doc so authors can improve it. Ask the user before sending.
+
+```bash
+chub feedback <id> up                        # doc worked well
+chub feedback <id> down --label outdated     # doc needs updating
+```
+
+Available labels: `outdated`, `inaccurate`, `incomplete`, `wrong-examples`,
+`wrong-version`, `poorly-structured`, `accurate`, `well-structured`, `helpful`,
+`good-examples`.
+
+## Quick reference
+
+| Goal | Command |
+|------|---------|
+| List everything | `chub search` |
+| Find a doc | `chub search "stripe"` |
+| Exact id detail | `chub search stripe/api` |
+| Fetch Python docs | `chub get stripe/api --lang py` |
+| Fetch JS docs | `chub get openai/chat --lang js` |
+| Save to file | `chub get anthropic/sdk --lang py -o docs.md` |
+| Fetch multiple | `chub get openai/chat stripe/api --lang py` |
+| Save a note | `chub annotate stripe/api "needs raw body"` |
+| List notes | `chub annotate --list` |
+| Rate a doc | `chub feedback stripe/api up` |
+
+## Notes
+
+- `chub search` with no query lists everything available
+- IDs are `<author>/<name>` — confirm the ID from search before fetching
+- If multiple languages exist and you don't pass `--lang`, chub will tell you which are available

package/src/commands/annotate.js

@@ -0,0 +1,83 @@
+import chalk from 'chalk';
+import { readAnnotation, writeAnnotation, clearAnnotation, listAnnotations } from '../lib/annotations.js';
+import { output, error, info } from '../lib/output.js';
+
+export function registerAnnotateCommand(program) {
+  program
+    .command('annotate [id] [note]')
+    .description('Attach agent notes to a doc or skill')
+    .option('--clear', 'Remove annotation for this entry')
+    .option('--list', 'List all annotations')
+    .action((id, note, opts) => {
+      const globalOpts = program.optsWithGlobals();
+
+      if (opts.list) {
+        const annotations = listAnnotations();
+        output(
+          annotations,
+          (data) => {
+            if (data.length === 0) {
+              console.log('No annotations.');
+              return;
+            }
+            for (const a of data) {
+              console.log(`${chalk.bold(a.id)} ${chalk.dim(`(${a.updatedAt})`)}`);
+              console.log(`  ${a.note}`);
+              console.log();
+            }
+          },
+          globalOpts
+        );
+        return;
+      }
+
+      if (!id) {
+        error('Missing required argument: <id>. Run: chub annotate <id> <note> | chub annotate <id> --clear | chub annotate --list', globalOpts);
+      }
+
+      if (opts.clear) {
+        const removed = clearAnnotation(id);
+        output(
+          { id, cleared: removed },
+          (data) => {
+            if (data.cleared) {
+              console.log(`Annotation cleared for ${chalk.bold(id)}.`);
+            } else {
+              console.log(`No annotation found for ${chalk.bold(id)}.`);
+            }
+          },
+          globalOpts
+        );
+        return;
+      }
+
+      if (!note) {
+        // Show existing annotation
+        const existing = readAnnotation(id);
+        if (existing) {
+          output(
+            existing,
+            (data) => {
+              console.log(`${chalk.bold(data.id)} ${chalk.dim(`(${data.updatedAt})`)}`);
+              console.log(data.note);
+            },
+            globalOpts
+          );
+        } else {
+          output(
+            { id, note: null },
+            () => console.log(`No annotation for ${chalk.bold(id)}.`),
+            globalOpts
+          );
+        }
+        return;
+      }
+
+      const data = writeAnnotation(id, note);
+      output(
+        data,
+        (d) => console.log(`Annotation saved for ${chalk.bold(d.id)}.`),
+        globalOpts
+      );
+    });
+}

package/src/commands/build.js

@@ -3,6 +3,8 @@ import { join, relative, dirname } from 'node:path';
 import chalk from 'chalk';
 import { parseFrontmatter } from '../lib/frontmatter.js';
 import { info } from '../lib/output.js';
+import { trackEvent } from '../lib/analytics.js';
+import { buildIndex } from '../lib/bm25.js';
 
 /**
  * Recursively find all DOC.md and SKILL.md files under a directory.
@@ -300,6 +302,14 @@ export function registerBuildCommand(program) {
       mkdirSync(outputDir, { recursive: true });
       writeFileSync(join(outputDir, 'registry.json'), JSON.stringify(registry, null, 2));
 
+      // Build and write BM25 search index
+      const allEntries = [
+        ...allDocs.map((d) => ({ ...d, _type: 'doc' })),
+        ...allSkills.map((s) => ({ ...s, _type: 'skill' })),
+      ];
+      const searchIndex = buildIndex(allEntries);
+      writeFileSync(join(outputDir, 'search-index.json'), JSON.stringify(searchIndex));
+
       // Copy content tree
       for (const authorEntry of topLevel) {
         const src = join(contentDir, authorEntry.name);
@@ -307,11 +317,12 @@ export function registerBuildCommand(program) {
         // Skip registry.json in author dirs
         cpSync(src, dest, {
           recursive: true,
-          filter: (s) => !s.endsWith('/registry.json') || s === join(src, 'registry.json') === false,
+          filter: (s) => !s.endsWith('/registry.json'),
         });
       }
 
       const summary = { docs: allDocs.length, skills: allSkills.length, warnings: allWarnings.length };
+      trackEvent('build', { doc_count: allDocs.length, skill_count: allSkills.length }).catch(() => {});
       if (globalOpts.json) {
         console.log(JSON.stringify({ ...summary, output: outputDir }));
       } else {

package/src/commands/feedback.js

@@ -0,0 +1,150 @@
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { getEntry } from '../lib/registry.js';
+import { sendFeedback, isTelemetryEnabled, getTelemetryUrl } from '../lib/telemetry.js';
+import { getOrCreateClientId } from '../lib/identity.js';
+import { output, error } from '../lib/output.js';
+import { trackEvent } from '../lib/analytics.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const VALID_LABELS = [
+  'accurate', 'well-structured', 'helpful', 'good-examples',
+  'outdated', 'inaccurate', 'incomplete', 'wrong-examples',
+  'wrong-version', 'poorly-structured',
+];
+
+function collect(val, acc) {
+  acc.push(val);
+  return acc;
+}
+
+export function registerFeedbackCommand(program) {
+  program
+    .command('feedback [id] [rating] [comment]')
+    .description('Rate a doc or skill (up/down)')
+    .option('--type <type>', 'Explicit type: doc or skill')
+    .option('--lang <language>', 'Language variant of the doc')
+    .option('--doc-version <version>', 'Version of the doc')
+    .option('--file <file>', 'Specific file within the entry (e.g. references/streaming.md)')
+    .option('--label <label>', 'Feedback label (repeatable: --label outdated --label wrong-examples)', collect, [])
+    .option('--agent <name>', 'AI coding tool name')
+    .option('--model <model>', 'LLM model name')
+    .option('--status', 'Show telemetry status')
+    .action(async (id, rating, comment, opts) => {
+      const globalOpts = program.optsWithGlobals();
+
+      // --status flag
+      if (opts.status) {
+        const enabled = isTelemetryEnabled();
+        if (globalOpts.json) {
+          let clientId = null;
+          try { clientId = await getOrCreateClientId(); } catch {}
+          console.log(JSON.stringify({
+            telemetry: enabled,
+            client_id_prefix: clientId ? clientId.slice(0, 8) : null,
+            endpoint: getTelemetryUrl(),
+            valid_labels: VALID_LABELS,
+          }));
+        } else {
+          console.log(`Telemetry: ${enabled ? chalk.green('enabled') : chalk.red('disabled')}`);
+          try {
+            const cid = await getOrCreateClientId();
+            console.log(`Client ID: ${cid.slice(0, 8)}...`);
+          } catch {}
+          console.log(`Endpoint:  ${getTelemetryUrl()}`);
+          console.log(`Labels:    ${VALID_LABELS.join(', ')}`);
+        }
+        return;
+      }
+
+      // BUG #1 FIX: Validation errors respect --json flag
+      if (!id || !rating) {
+        error('Missing required arguments: <id> and <rating>. Run: chub feedback <id> <up|down> [comment]', globalOpts);
+      }
+
+      if (rating !== 'up' && rating !== 'down') {
+        error('Rating must be "up" or "down".', globalOpts);
+      }
+
+      if (!isTelemetryEnabled()) {
+        output(
+          { status: 'skipped', reason: 'telemetry_disabled' },
+          () => console.log(chalk.yellow('Telemetry is disabled. Enable with: telemetry: true in ~/.chub/config.yaml')),
+          globalOpts
+        );
+        return;
+      }
+
+      // BUG #2 FIX: Only auto-detect type if --type not explicitly set
+      let entryType = opts.type || null;
+      let docLang = opts.lang || undefined;
+      let docVersion = opts.docVersion || undefined;
+      let source;
+      try {
+        const result = getEntry(id);
+        if (result.entry) {
+          if (!entryType) {
+            entryType = result.entry.languages ? 'doc' : 'skill';
+          }
+          source = result.entry._source;
+
+          // If doc and user didn't specify lang/version, try to infer from entry
+          if (result.entry.languages && !docLang && result.entry.languages.length === 1) {
+            docLang = result.entry.languages[0].language;
+          }
+          if (result.entry.languages && !docVersion) {
+            const lang = result.entry.languages.find((l) => l.language === docLang) || result.entry.languages[0];
+            if (lang) docVersion = lang.recommendedVersion;
+          }
+        }
+      } catch {
+        // Registry not loaded — use explicit flags
+      }
+      if (!entryType) entryType = 'doc'; // Final fallback
+
+      // Parse labels (--label is repeatable, collected into an array)
+      let labels;
+      if (opts.label && opts.label.length > 0) {
+        labels = opts.label.map((l) => l.trim().toLowerCase()).filter((l) => VALID_LABELS.includes(l));
+        if (labels.length === 0) labels = undefined;
+      }
+
+      // Read CLI version
+      let cliVersion;
+      try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
+        cliVersion = pkg.version;
+      } catch {}
+
+      const result = await sendFeedback(id, entryType, rating, {
+        comment,
+        docLang,
+        docVersion,
+        targetFile: opts.file,
+        labels,
+        agent: opts.agent,
+        model: opts.model,
+        cliVersion,
+        source,
+      });
+
+      if (result.status === 'sent') {
+        trackEvent('feedback_sent', { entry_id: id, rating, entry_type: entryType }).catch(() => {});
+      }
+
+      output(result, (data) => {
+        if (data.status === 'sent') {
+          const parts = [chalk.green(`Feedback recorded for ${id}`)];
+          if (docLang) parts.push(chalk.dim(`lang=${docLang}`));
+          if (docVersion) parts.push(chalk.dim(`version=${docVersion}`));
+          if (opts.file) parts.push(chalk.dim(`file=${opts.file}`));
+          console.log(parts.join(' '));
+        } else if (data.status === 'error') {
+          process.stderr.write(chalk.red(`Failed to send feedback: ${data.reason || `HTTP ${data.code}`}\n`));
+        }
+      }, globalOpts);
+    });
+}

package/src/commands/get.js

@@ -4,36 +4,48 @@ 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';
+import { trackEvent } from '../lib/analytics.js';
+import { readAnnotation } from '../lib/annotations.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)
+ * Fetch one or more entries by ID. Auto-detects doc vs skill per entry.
  */
-async function fetchEntries(type, ids, opts, globalOpts) {
+async function fetchEntries(ids, opts, globalOpts) {
   const results = [];
 
   for (const id of ids) {
-    const result = getEntry(id, type);
+    // Search both docs and skills — auto-detect type
+    const result = getEntry(id);
 
     if (result.ambiguous) {
       error(
-        `Multiple entries with id "${id}". Be specific:\n  ${result.alternatives.join('\n  ')}`,
+        `Multiple entries match "${id}". Use a source prefix:\n  ${result.alternatives.map((a) => `chub get ${a}`).join('\n  ')}`,
         globalOpts
       );
     }
 
     if (!result.entry) {
-      error(`Entry "${id}" not found in ${type}s.`, globalOpts);
+      error(`No doc or skill found with id "${id}".`, globalOpts);
     }
 
     const entry = result.entry;
+    const type = entry.languages ? 'doc' : 'skill';
     const resolved = resolveDocPath(entry, opts.lang, opts.version);
 
     if (!resolved) {
-      error(`Could not resolve path for "${id}" ${opts.lang || ''} ${opts.version || ''}`.trim(), globalOpts);
+      if (opts.lang && entry.languages) {
+        const available = entry.languages.map((l) => l.language).join(', ');
+        error(`Language "${opts.lang}" is not available for "${id}". Available languages: ${available}.`, globalOpts);
+      } else {
+        error(`No content found for "${id}".`, globalOpts);
+      }
+    }
+
+    if (resolved.versionNotFound) {
+      error(
+        `Version "${resolved.requested}" not found for "${id}". Available versions: ${resolved.available.join(', ')}`,
+        globalOpts
+      );
     }
 
     if (resolved.needsLanguage) {
@@ -45,26 +57,53 @@ async function fetchEntries(type, ids, opts, globalOpts) {
 
     const entryFile = resolveEntryFile(resolved, type);
     if (entryFile.error) {
-      error(`"${id}" ${entryFile.error}`, globalOpts);
+      error(`No content available for "${id}". Check that the source contains a valid DOC.md or SKILL.md, or run \`chub update\` to refresh remote registries.`, globalOpts);
     }
 
+    // Determine which reference files exist (beyond DOC.md/SKILL.md)
+    const entryFileName = type === 'skill' ? 'SKILL.md' : 'DOC.md';
+    const refFiles = resolved.files.filter((f) => f !== entryFileName);
+
     try {
-      if (opts.full && resolved.files.length > 0) {
+      if (opts.file) {
+        // --file mode: fetch specific file(s) by path
+        const requested = opts.file.split(',').map((f) => f.trim());
+        const invalid = requested.filter((f) => !resolved.files.includes(f));
+        if (invalid.length > 0) {
+          const available = refFiles.length > 0 ? refFiles.join(', ') : '(none)';
+          error(`File "${invalid[0]}" not found in ${id}. Available: ${available}`, globalOpts);
+        }
+        if (requested.length === 1) {
+          const content = await fetchDoc(resolved.source, join(resolved.path, requested[0]));
+          results.push({ id: entry.id, type, content, path: join(resolved.path, requested[0]) });
+        } else {
+          const allFiles = await fetchDocFull(resolved.source, resolved.path, requested);
+          results.push({ id: entry.id, type, files: allFiles, path: resolved.path });
+        }
+      } else 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 });
+        results.push({ id: entry.id, type, files: allFiles, path: resolved.path });
       } else {
         const content = await fetchDoc(resolved.source, entryFile.filePath);
-        results.push({ id: entry.id, content, path: entryFile.filePath });
+        results.push({ id: entry.id, type, content, path: entryFile.filePath, additionalFiles: refFiles });
       }
     } catch (err) {
-      error(err.message, globalOpts);
+      error(`Failed to load "${id}": ${err.message}`, globalOpts);
     }
   }
 
+  // Track fetches
+  for (const r of results) {
+    trackEvent(r.type === 'doc' ? 'doc_fetched' : 'skill_fetched', {
+      entry_id: r.id,
+      full: !!opts.full,
+      lang: opts.lang || undefined,
+    }).catch(() => {});
+  }
+
   // 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;
@@ -88,6 +127,7 @@ async function fetchEntries(type, ids, opts, globalOpts) {
         mkdirSync(opts.output, { recursive: true });
         for (const r of results) {
           const outPath = join(opts.output, `${r.id}.md`);
+          mkdirSync(dirname(outPath), { recursive: true });
           writeFileSync(outPath, r.content);
           info(`Written to ${outPath}`);
         }
@@ -100,18 +140,32 @@ async function fetchEntries(type, ids, opts, globalOpts) {
       }
     }
     if (globalOpts.json) {
-      console.log(JSON.stringify(results.map((r) => ({ id: r.id, path: opts.output }))));
+      console.log(JSON.stringify(results.map((r) => ({ id: r.id, type: r.type, path: opts.output }))));
     }
   } else {
-    // stdout
     if (results.length === 1 && !results[0].files) {
+      const r = results[0];
+      const extraFiles = r.additionalFiles || [];
+      const annotation = readAnnotation(r.id);
+      const jsonData = { id: r.id, type: r.type, content: r.content, path: r.path };
+      if (extraFiles.length > 0) jsonData.additionalFiles = extraFiles;
+      if (annotation) jsonData.annotation = annotation;
       output(
-        { id: results[0].id, content: results[0].content, path: results[0].path },
-        (data) => process.stdout.write(data.content),
+        jsonData,
+        (data) => {
+          process.stdout.write(data.content);
+          if (annotation) {
+            process.stdout.write(`\n\n---\n[Agent note — ${annotation.updatedAt}]\n${annotation.note}\n`);
+          }
+          if (extraFiles.length > 0) {
+            const fileList = extraFiles.map((f) => `  ${f}`).join('\n');
+            const example = `chub get ${r.id} --file ${extraFiles[0]}`;
+            process.stdout.write(`\n\n---\nAdditional files available (use --file to fetch):\n${fileList}\nExample: ${example}\n`);
+          }
+        },
         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}`);
@@ -120,7 +174,7 @@ async function fetchEntries(type, ids, opts, globalOpts) {
       });
       const combined = parts.join('\n\n---\n\n');
       output(
-        results.map((r) => ({ id: r.id, path: r.path })),
+        results.map((r) => ({ id: r.id, type: r.type, path: r.path })),
         () => process.stdout.write(combined),
         globalOpts
       );
@@ -129,29 +183,16 @@ async function fetchEntries(type, ids, opts, 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')
+  program
+    .command('get <ids...>')
+    .description('Fetch docs or skills by ID (auto-detects type)')
+    .option('--lang <language>', 'Language variant (for docs)')
+    .option('--version <version>', 'Specific version (for docs)')
     .option('-o, --output <path>', 'Write to file or directory')
     .option('--full', 'Fetch all files (not just entry point)')
+    .option('--file <paths>', 'Fetch specific file(s) by path (comma-separated)')
     .action(async (ids, opts) => {
       const globalOpts = program.optsWithGlobals();
-      await fetchEntries('skill', ids, opts, globalOpts);
+      await fetchEntries(ids, opts, globalOpts);
     });
 }

package/src/commands/search.js

@@ -2,6 +2,7 @@ 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';
+import { trackEvent } from '../lib/analytics.js';
 
 function formatEntryList(entries) {
   const multi = isMultiSource();
@@ -93,6 +94,12 @@ export function registerSearchCommand(program) {
 
       // Fuzzy search
       const results = searchEntries(query, opts).slice(0, limit);
+      trackEvent('search', {
+        query_length: query.length,
+        result_count: results.length,
+        has_tags: !!opts.tags,
+        has_lang: !!opts.lang,
+      }).catch(() => {});
       output({ results, total: results.length, query }, (data) => {
         if (data.results.length === 0) {
           console.log(chalk.yellow(`No results for "${query}".`));