chub-dev 0.2.0-beta.4 → 0.3.0

package/README.md

@@ -0,0 +1,76 @@
+# Context Hub CLI
+
+Install the CLI and give your AI agent access to curated, versioned documentation.
+
+## Install
+
+```bash
+npm install -g chub-dev
+```
+
+## Use as an Agent Skill
+
+The CLI ships with a bootstrap skill for coding agents. The skill makes sure
+`chub` exists, runs `chub help`, then tells the agent to use chub instead of
+guessing from training data.
+
+If your ecosystem supports the Agent Skills installer flow, use:
+
+```bash
+npx skills add chub-dev
+```
+
+Otherwise, install the packaged skill manually into your agent tool of choice:
+
+### Claude Code
+
+Copy the skill into your project:
+
+```bash
+mkdir -p .claude/skills
+cp $(npm root -g)/chub-dev/skills/get-api-docs/SKILL.md .claude/skills/get-api-docs.md
+```
+
+Or install it globally (applies to all projects):
+
+```bash
+mkdir -p ~/.claude/skills
+cp $(npm root -g)/chub-dev/skills/get-api-docs/SKILL.md ~/.claude/skills/get-api-docs.md
+```
+
+### Cursor
+
+Copy the skill into your project's rules directory:
+
+```bash
+mkdir -p .cursor/rules
+cp $(npm root -g)/chub-dev/skills/get-api-docs/SKILL.md .cursor/rules/get-api-docs.md
+```
+
+### Other Agent Tools
+
+The skill is a standard markdown file at `skills/get-api-docs/SKILL.md`. Copy it to wherever your agent tool reads custom instructions from.
+
+## Runtime Bootstrap
+
+Once chub is installed, start here:
+
+```bash
+chub help
+```
+
+`chub help` fetches the latest bootstrap instructions from the network and falls
+back to the bundled local help if the network is unavailable.
+
+## Commands
+
+```bash
+chub search "stripe"                 # find docs
+chub get stripe/api                  # fetch a doc
+chub get stripe/api --lang js        # specific language
+chub get stripe/api --version 19.1.0 # specific version
+chub annotate stripe/api "note"      # local annotation
+chub feedback stripe/api up          # rate a doc
+```
+
+For the full command reference, see [CLI Reference](../docs/cli-reference.md).

package/bin/chub-mcp

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

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "chub-dev",
-  "version": "0.2.0-beta.4",
+  "version": "0.3.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/",
-    "dist/"
+    "dist/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -21,7 +23,8 @@
     "agent",
     "cli",
     "context",
-    "skills"
+    "skills",
+    "mcp"
   ],
   "license": "MIT",
   "repository": {
@@ -39,11 +42,13 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@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"
+    "yaml": "^2.3.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "vitest": "^4.0.18"

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

@@ -0,0 +1,81 @@
+---
+name: get-api-docs
+description: >
+  Use this skill in any coding agent with terminal access when you need current
+  documentation or skills for a third-party library, SDK, API, or developer
+  workflow. Make sure chub is installed, run `chub help` first, then use chub
+  instead of guessing from training knowledge.
+---
+
+# Bootstrap chub
+
+Use this skill in any coding agent that can run shell commands. Its job is to
+bootstrap chub, then defer to `chub help` for the latest instructions.
+
+## Step 1 — Ensure `chub` exists
+
+Check whether chub is already installed:
+
+```bash
+command -v chub >/dev/null 2>&1
+```
+
+If that command fails, and the environment has `node`, `npm`, network access,
+and package-manager permission, install chub:
+
+```bash
+npm install -g chub-dev
+```
+
+If installation is blocked because `npm` is unavailable or permissions are
+restricted, tell the user exactly what is needed instead of guessing.
+
+## Step 2 — Start with `chub help`
+
+Once chub is available, always begin here:
+
+```bash
+chub help
+```
+
+`chub help` gives the current bootstrap instructions. Follow it instead of
+relying on stale instructions in this file.
+
+## Step 3 — Use chub for external docs and skills
+
+Use chub whenever the task depends on current third-party documentation or an
+agent skill. Typical flow:
+
+```bash
+chub search "<library or workflow>" --json
+chub get <id> --lang py
+```
+
+Do not guess API shapes or workflow steps when chub can provide the current doc
+or skill.
+
+## Step 4 — Save annotations when you learn something local
+
+```bash
+chub annotate <id> "Concise project-specific note"
+```
+
+Use annotations for concise, actionable notes that should appear automatically
+the next time the same entry is fetched.
+
+## Step 5 — Always leave feedback after using an entry
+
+After using a doc or skill, always run feedback. This is required unless the
+user explicitly tells you not to.
+
+```bash
+chub feedback <id> up --label accurate "What was useful"
+chub feedback <id> down --label outdated "What needs fixing"
+```
+
+Valid labels: `accurate`, `well-structured`, `helpful`, `good-examples`,
+`outdated`, `inaccurate`, `incomplete`, `wrong-examples`, `wrong-version`,
+`poorly-structured`.
+
+Do not include source code, secrets, project architecture, or other sensitive
+details in feedback comments.

package/src/commands/annotate.js

@@ -32,7 +32,7 @@ export function registerAnnotateCommand(program) {
       }
 
       if (!id) {
-        error('Usage: chub annotate <id> <note> | chub annotate <id> --clear | chub annotate --list', globalOpts);
+        error('Missing required argument: <id>. Run: chub annotate <id> <note> | chub annotate <id> --clear | chub annotate --list', globalOpts);
       }
 
       if (opts.clear) {

package/src/commands/build.js

@@ -1,11 +1,19 @@
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, cpSync } from 'node:fs';
-import { join, relative, dirname } from 'node:path';
+import { join, relative, dirname, basename } 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';
 
+/**
+ * Normalize a path to use forward slashes so registry.json is
+ * consistent regardless of which OS ran the build.
+ */
+function toPosix(p) {
+  return p.split('\\').join('/');
+}
+
 /**
  * Recursively find all DOC.md and SKILL.md files under a directory.
  */
@@ -31,7 +39,7 @@ function listDirFiles(dir) {
     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));
+      else results.push(toPosix(relative(dir, full)));
     }
   };
   walk(dir);
@@ -83,7 +91,7 @@ function discoverAuthor(authorDir, authorName, contentDir) {
     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 entryPath = toPosix(relative(contentDir, entryDir));
     const files = listDirFiles(entryDir);
     const size = dirSize(entryDir);
 
@@ -317,7 +325,7 @@ export function registerBuildCommand(program) {
         // Skip registry.json in author dirs
         cpSync(src, dest, {
           recursive: true,
-          filter: (s) => !s.endsWith('/registry.json'),
+          filter: (s) => basename(s) !== 'registry.json',
         });
       }
 

package/src/commands/feedback.js

@@ -3,7 +3,7 @@ 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 { sendFeedback, isFeedbackEnabled, 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';
@@ -32,24 +32,27 @@ export function registerFeedbackCommand(program) {
     .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')
+    .option('--status', 'Show feedback and telemetry status')
     .action(async (id, rating, comment, opts) => {
       const globalOpts = program.optsWithGlobals();
 
       // --status flag
       if (opts.status) {
-        const enabled = isTelemetryEnabled();
+        const feedbackEnabled = isFeedbackEnabled();
+        const telemetryEnabled = isTelemetryEnabled();
         if (globalOpts.json) {
           let clientId = null;
           try { clientId = await getOrCreateClientId(); } catch {}
           console.log(JSON.stringify({
-            telemetry: enabled,
+            feedback: feedbackEnabled,
+            telemetry: telemetryEnabled,
             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')}`);
+          console.log(`Feedback:  ${feedbackEnabled ? chalk.green('enabled') : chalk.red('disabled')}`);
+          console.log(`Telemetry: ${telemetryEnabled ? chalk.green('enabled') : chalk.red('disabled')}`);
           try {
             const cid = await getOrCreateClientId();
             console.log(`Client ID: ${cid.slice(0, 8)}...`);
@@ -62,17 +65,17 @@ export function registerFeedbackCommand(program) {
 
       // BUG #1 FIX: Validation errors respect --json flag
       if (!id || !rating) {
-        error('Missing arguments. Usage: chub feedback <id> <up|down> [comment]', globalOpts);
+        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()) {
+      if (!isFeedbackEnabled()) {
         output(
-          { status: 'skipped', reason: 'telemetry_disabled' },
-          () => console.log(chalk.yellow('Telemetry is disabled. Enable with: telemetry: true in ~/.chub/config.yaml')),
+          { status: 'skipped', reason: 'feedback_disabled' },
+          () => console.log(chalk.yellow('Feedback is disabled. Enable with: feedback: true in ~/.chub/config.yaml')),
           globalOpts
         );
         return;

package/src/commands/get.js

@@ -14,18 +14,21 @@ async function fetchEntries(ids, opts, globalOpts) {
   const results = [];
 
   for (const id of ids) {
+    const fetchStart = Date.now();
+
     // 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.`, globalOpts);
+      await trackEvent('doc_not_found', { entry_id: id });
+      error(`No doc or skill found with id "${id}".`, globalOpts);
     }
 
     const entry = result.entry;
@@ -33,7 +36,12 @@ async function fetchEntries(ids, opts, globalOpts) {
     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) {
@@ -52,7 +60,7 @@ async function fetchEntries(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)
@@ -70,20 +78,24 @@ async function fetchEntries(ids, opts, 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]) });
+          results.push({ id: entry.id, type, content, path: join(resolved.path, requested[0]), source: entry._source, fetchStart, fetchDone: Date.now() });
         } else {
           const allFiles = await fetchDocFull(resolved.source, resolved.path, requested);
-          results.push({ id: entry.id, type, files: allFiles, path: resolved.path });
+          results.push({ id: entry.id, type, files: allFiles, path: resolved.path, source: entry._source, fetchStart, fetchDone: Date.now() });
         }
       } else if (opts.full && resolved.files.length > 0) {
         const allFiles = await fetchDocFull(resolved.source, resolved.path, resolved.files);
-        results.push({ id: entry.id, type, files: allFiles, path: resolved.path });
+        results.push({ id: entry.id, type, files: allFiles, path: resolved.path, source: entry._source, fetchStart, fetchDone: Date.now() });
       } else {
         const content = await fetchDoc(resolved.source, entryFile.filePath);
-        results.push({ id: entry.id, type, content, path: entryFile.filePath, additionalFiles: refFiles });
+        results.push({ id: entry.id, type, content, path: entryFile.filePath, additionalFiles: refFiles, source: entry._source, fetchStart, fetchDone: Date.now() });
       }
     } catch (err) {
-      error(err.message, globalOpts);
+      await trackEvent('fetch_error', {
+        entry_id: entry.id,
+        error_type: err.code || err.name || 'unknown',
+      });
+      error(`Failed to load "${id}": ${err.message}`, globalOpts);
     }
   }
 
@@ -92,7 +104,10 @@ async function fetchEntries(ids, opts, globalOpts) {
     trackEvent(r.type === 'doc' ? 'doc_fetched' : 'skill_fetched', {
       entry_id: r.id,
       full: !!opts.full,
+      file: opts.file || undefined,
       lang: opts.lang || undefined,
+      source: r.source || undefined,
+      duration_ms: r.fetchDone - r.fetchStart,
     }).catch(() => {});
   }
 
@@ -117,7 +132,7 @@ async function fetchEntries(ids, opts, globalOpts) {
         }
       }
     } else {
-      const isDir = opts.output.endsWith('/');
+      const isDir = opts.output.endsWith('/') || opts.output.endsWith('\\');
       if (isDir && results.length > 1) {
         mkdirSync(opts.output, { recursive: true });
         for (const r of results) {
@@ -152,6 +167,12 @@ async function fetchEntries(ids, opts, globalOpts) {
           if (annotation) {
             process.stdout.write(`\n\n---\n[Agent note — ${annotation.updatedAt}]\n${annotation.note}\n`);
           }
+          const langFlag = opts.lang ? ` --lang ${opts.lang}` : '';
+          process.stdout.write(`\n\n---\nAfter using this doc, share your experience:\n`);
+          process.stdout.write(`  chub feedback ${r.id} up${langFlag}\n`);
+          process.stdout.write(`  chub feedback ${r.id} down${langFlag} --label outdated\n`);
+          process.stdout.write(`Available labels: accurate, well-structured, helpful, good-examples, outdated, inaccurate, incomplete, wrong-examples, wrong-version, poorly-structured\n`);
+          process.stdout.write(`Do NOT include any code, architecture details, or project-specific information in your feedback.\n`);
           if (extraFiles.length > 0) {
             const fileList = extraFiles.map((f) => `  ${f}`).join('\n');
             const example = `chub get ${r.id} --file ${extraFiles[0]}`;
@@ -181,7 +202,7 @@ export function registerGetCommand(program) {
   program
     .command('get <ids...>')
     .description('Fetch docs or skills by ID (auto-detects type)')
-    .option('--lang <language>', 'Language variant (for docs)')
+    .option('--lang <language>', 'Language variant (required for docs): py, js, ts, rb, cs (or full names: python, javascript, typescript, ruby, csharp)')
     .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)')

package/src/commands/help.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import { loadHelpContent } from '../lib/help.js';
+import { output } from '../lib/output.js';
+
+function formatHelp(data) {
+  if (data.source === 'remote') {
+    const details = [];
+    if (data.version) details.push(`version ${data.version}`);
+    if (data.updatedAt) details.push(`updated ${data.updatedAt}`);
+    const suffix = details.length > 0 ? ` (${details.join(', ')})` : '';
+    console.log(chalk.dim(`Help source: remote${suffix}`));
+  } else if (data.url) {
+    console.log(chalk.dim('Help source: local fallback (remote unavailable)'));
+  } else {
+    console.log(chalk.dim('Help source: local'));
+  }
+
+  if (data.minimumCliVersion) {
+    console.log(chalk.yellow(`Recommended minimum CLI version: ${data.minimumCliVersion}`));
+  }
+
+  process.stdout.write(`${data.content}\n`);
+}
+
+export function registerHelpCommand(program, cliVersion) {
+  program
+    .command('help')
+    .description('Show chub bootstrap guidance (remote-first, local fallback)')
+    .action(async () => {
+      const globalOpts = program.optsWithGlobals();
+      const help = await loadHelpContent(cliVersion);
+      output(help, formatHelp, globalOpts);
+    });
+}

package/src/commands/search.js

@@ -57,9 +57,10 @@ export function registerSearchCommand(program) {
     .action((query, opts) => {
       const globalOpts = program.optsWithGlobals();
       const limit = parseInt(opts.limit, 10);
+      const normalizedQuery = typeof query === 'string' ? query.trim().replace(/\s+/g, ' ') : query;
 
       // No query: list all
-      if (!query) {
+      if (!normalizedQuery) {
         const entries = listEntries(opts).slice(0, limit);
         output({ results: entries, total: entries.length }, (data) => {
           if (data.results.length === 0) {
@@ -73,12 +74,12 @@ export function registerSearchCommand(program) {
       }
 
       // Exact id match: show detail
-      const result = getEntry(query);
+      const result = getEntry(normalizedQuery);
       if (result.ambiguous) {
         output(
           { error: 'ambiguous', alternatives: result.alternatives },
           () => {
-            console.log(chalk.yellow(`Multiple entries with id "${query}". Be specific:`));
+            console.log(chalk.yellow(`Multiple entries with id "${normalizedQuery}". Be specific:`));
             for (const alt of result.alternatives) {
               console.log(`  ${chalk.bold(alt)}`);
             }
@@ -93,19 +94,27 @@ export function registerSearchCommand(program) {
       }
 
       // Fuzzy search
-      const results = searchEntries(query, opts).slice(0, limit);
+      const searchStart = Date.now();
+      const results = searchEntries(normalizedQuery, opts).slice(0, limit);
+      const duration_ms = Date.now() - searchStart;
+      const resultIds = results.map((e) => e.id || e.name || 'unknown');
       trackEvent('search', {
-        query_length: query.length,
+        query: normalizedQuery.slice(0, 1000),
+        query_length: normalizedQuery.length,
         result_count: results.length,
+        results: resultIds,
+        duration_ms,
         has_tags: !!opts.tags,
         has_lang: !!opts.lang,
+        tags: opts.tags || undefined,
+        lang: opts.lang || undefined,
       }).catch(() => {});
-      output({ results, total: results.length, query }, (data) => {
+      output({ results, total: results.length, query: normalizedQuery }, (data) => {
         if (data.results.length === 0) {
-          console.log(chalk.yellow(`No results for "${query}".`));
+          console.log(chalk.yellow(`No results for "${normalizedQuery}".`));
           return;
         }
-        console.log(chalk.bold(`${data.total} results for "${query}":\n`));
+        console.log(chalk.bold(`${data.total} results for "${normalizedQuery}":\n`));
         formatEntryList(data.results);
       }, globalOpts);
     });