chub-dev 0.1.0 → 0.2.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chub-dev",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.1",
   "description": "CLI for Context Hub - search and retrieve LLM-optimized docs and skills",
   "type": "module",
   "bin": {
@@ -31,10 +31,19 @@
     "url": "https://github.com/andrewyng/context-hub/issues"
   },
   "homepage": "https://github.com/andrewyng/context-hub#readme",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
   "dependencies": {
-    "commander": "^12.0.0",
     "chalk": "^5.3.0",
-    "yaml": "^2.3.0",
-    "tar": "^7.0.0"
+    "commander": "^12.0.0",
+    "posthog-node": "^5.24.17",
+    "tar": "^7.5.8",
+    "yaml": "^2.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
   }
 }

package/src/commands/build.js

@@ -3,6 +3,7 @@ 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';
 
 /**
  * Recursively find all DOC.md and SKILL.md files under a directory.
@@ -307,11 +308,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 arguments. Usage: 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,6 +4,7 @@ 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';
 
 /**
  * Core fetch logic shared by `get docs` and `get skills`.
@@ -61,6 +62,15 @@ async function fetchEntries(type, ids, opts, globalOpts) {
     }
   }
 
+  // Track fetches
+  for (const r of results) {
+    trackEvent(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) {

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}".`));

package/src/index.js

@@ -9,6 +9,8 @@ import { registerCacheCommand } from './commands/cache.js';
 import { registerSearchCommand } from './commands/search.js';
 import { registerGetCommand } from './commands/get.js';
 import { registerBuildCommand } from './commands/build.js';
+import { registerFeedbackCommand } from './commands/feedback.js';
+import { trackEvent, shutdownAnalytics } from './lib/analytics.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -63,7 +65,7 @@ ${chalk.bold.underline('Multi-Source Config')} ${chalk.dim('(~/.chub/config.yaml
 
   ${chalk.dim('sources:')}
   ${chalk.dim('  - name: community')}
-  ${chalk.dim('    url: https://cdn.contexthub.dev/v1')}
+  ${chalk.dim('    url: https://cdn.aichub.org/v1')}
   ${chalk.dim('  - name: internal')}
   ${chalk.dim('    path: /path/to/local/docs')}
 
@@ -83,10 +85,14 @@ program
   });
 
 // Commands that don't need registry
-const SKIP_REGISTRY = ['update', 'cache', 'build', 'help'];
+const SKIP_REGISTRY = ['update', 'cache', 'build', 'feedback', 'help'];
 
 program.hook('preAction', async (thisCommand) => {
   const cmdName = thisCommand.args?.[0] || thisCommand.name();
+  // Track command usage (fire-and-forget, never blocks)
+  if (cmdName !== 'chub') {
+    trackEvent('command_run', { command: cmdName }).catch(() => {});
+  }
   if (SKIP_REGISTRY.includes(cmdName)) return;
   if (thisCommand.parent?.name() === 'cache') return;
   // Don't fetch registry for default action (no command)
@@ -105,5 +111,9 @@ registerCacheCommand(program);
 registerSearchCommand(program);
 registerGetCommand(program);
 registerBuildCommand(program);
+registerFeedbackCommand(program);
 
 program.parse();
+
+// Flush analytics before exit (best-effort)
+process.on('beforeExit', () => shutdownAnalytics().catch(() => {}));

package/src/lib/analytics.js

@@ -0,0 +1,90 @@
+/**
+ * PostHog Cloud analytics for general CLI usage tracking.
+ *
+ * Tracks: command usage, search patterns, doc/skill popularity, errors.
+ * Does NOT track feedback ratings (those go to the custom API via telemetry.js).
+ *
+ * Respects the same telemetry opt-out: `telemetry: false` in config or CHUB_TELEMETRY=0.
+ */
+
+import { isTelemetryEnabled } from './telemetry.js';
+
+// PostHog project API key (public — standard for client-side analytics)
+const POSTHOG_KEY = 'phc_cUPXY1tAUkIOU9perzGcFYEtFQeCgUhUO6ejT79YLIk';
+const POSTHOG_HOST = 'https://us.i.posthog.com';
+
+let _posthog = null;
+let _initFailed = false;
+
+/**
+ * Lazily initialize PostHog client. Returns null if telemetry is disabled
+ * or posthog-node is not installed.
+ */
+async function getClient() {
+  if (_initFailed) return null;
+  if (_posthog) return _posthog;
+
+  if (!isTelemetryEnabled()) {
+    _initFailed = true;
+    return null;
+  }
+
+  try {
+    const { PostHog } = await import('posthog-node');
+    _posthog = new PostHog(POSTHOG_KEY, {
+      host: POSTHOG_HOST,
+      flushAt: 1,        // Send immediately (CLI is short-lived)
+      flushInterval: 0,  // Don't batch
+    });
+    return _posthog;
+  } catch {
+    // posthog-node not installed — skip analytics silently
+    _initFailed = true;
+    return null;
+  }
+}
+
+/**
+ * Track an analytics event. Fire-and-forget — never throws, never blocks.
+ *
+ * @param {string} event - Event name (e.g., 'command_run', 'search', 'doc_fetched')
+ * @param {object} properties - Event properties
+ */
+export async function trackEvent(event, properties = {}) {
+  try {
+    const client = await getClient();
+    if (!client) return;
+
+    const { getOrCreateClientId } = await import('./identity.js');
+    const distinctId = await getOrCreateClientId();
+
+    client.capture({
+      distinctId,
+      event,
+      properties: {
+        ...properties,
+        platform: process.platform,
+        node_version: process.version,
+      },
+    });
+
+    // Flush immediately since CLI process exits soon
+    await client.flush();
+  } catch {
+    // Silent fail — analytics should never disrupt CLI
+  }
+}
+
+/**
+ * Shut down the PostHog client gracefully.
+ * Call this before process exit if possible.
+ */
+export async function shutdownAnalytics() {
+  if (_posthog) {
+    try {
+      await _posthog.shutdown();
+    } catch {
+      // Silent
+    }
+  }
+}

package/src/lib/cache.js

@@ -51,7 +51,14 @@ async function fetchRemoteRegistry(source, force = false) {
   }
 
   const url = `${source.url}/registry.json`;
-  const res = await fetch(url);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30000);
+  let res;
+  try {
+    res = await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
   if (!res.ok) {
     throw new Error(`Failed to fetch registry from ${source.name}: ${res.status} ${res.statusText}`);
   }
@@ -95,7 +102,14 @@ export async function fetchFullBundle(sourceName) {
   const url = `${source.url}/bundle.tar.gz`;
   const tmpPath = join(getSourceDir(sourceName), 'bundle.tar.gz');
 
-  const res = await fetch(url);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30000);
+  let res;
+  try {
+    res = await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
   if (!res.ok) {
     throw new Error(`Failed to fetch bundle from ${sourceName}: ${res.status} ${res.statusText}`);
   }
@@ -141,7 +155,14 @@ export async function fetchDoc(source, docPath) {
 
   // Fetch from CDN
   const url = `${source.url}/${docPath}`;
-  const res = await fetch(url);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30000);
+  let res;
+  try {
+    res = await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
   if (!res.ok) {
     throw new Error(`Failed to fetch ${docPath} from ${source.name}: ${res.status} ${res.statusText}`);
   }

package/src/lib/config.js

@@ -3,13 +3,16 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
 
-const DEFAULT_CDN_URL = 'https://github.com/context-hub/context-hub/releases/latest/download';
+const DEFAULT_CDN_URL = 'https://cdn.aichub.org/v1';
+const DEFAULT_TELEMETRY_URL = 'https://api.aichub.org/v1';
 
 const DEFAULTS = {
   output_dir: '.context',
   refresh_interval: 86400,
   output_format: 'human',
   source: 'official,maintainer,community',
+  telemetry: true,
+  telemetry_url: DEFAULT_TELEMETRY_URL,
 };
 
 let _config = null;
@@ -46,6 +49,8 @@ export function loadConfig() {
     refresh_interval: fileConfig.refresh_interval ?? DEFAULTS.refresh_interval,
     output_format: fileConfig.output_format || DEFAULTS.output_format,
     source: fileConfig.source || DEFAULTS.source,
+    telemetry: fileConfig.telemetry !== undefined ? fileConfig.telemetry : DEFAULTS.telemetry,
+    telemetry_url: fileConfig.telemetry_url || DEFAULTS.telemetry_url,
   };
 
   return _config;

package/src/lib/identity.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getChubDir } from './config.js';
+
+let _cachedClientId = null;
+
+/**
+ * Get the platform-native machine UUID.
+ */
+function getMachineUUID() {
+  const plat = platform();
+
+  if (plat === 'darwin') {
+    return execSync(
+      `ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}'`,
+      { encoding: 'utf8' }
+    ).trim();
+  }
+
+  if (plat === 'linux') {
+    try {
+      return readFileSync('/etc/machine-id', 'utf8').trim();
+    } catch {
+      return readFileSync('/var/lib/dbus/machine-id', 'utf8').trim();
+    }
+  }
+
+  if (plat === 'win32') {
+    const output = execSync(
+      'reg query "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid',
+      { encoding: 'utf8' }
+    );
+    const match = output.match(/MachineGuid\s+REG_SZ\s+(.+)/);
+    if (match) return match[1].trim();
+    throw new Error('Could not parse MachineGuid from registry');
+  }
+
+  throw new Error(`Unsupported platform: ${plat}`);
+}
+
+/**
+ * Get or create a stable, anonymous client ID.
+ * Checks ~/.chub/client_id for a cached 64-char hex string.
+ * If not found, hashes the machine UUID with SHA-256 and saves it.
+ */
+export async function getOrCreateClientId() {
+  if (_cachedClientId) return _cachedClientId;
+
+  const chubDir = getChubDir();
+  const idPath = join(chubDir, 'client_id');
+
+  // Try to read existing client id
+  try {
+    const existing = readFileSync(idPath, 'utf8').trim();
+    if (/^[0-9a-f]{64}$/.test(existing)) {
+      _cachedClientId = existing;
+      return existing;
+    }
+  } catch {
+    // File doesn't exist or is unreadable
+  }
+
+  // Generate from machine UUID
+  const uuid = getMachineUUID();
+  const hash = createHash('sha256').update(uuid).digest('hex');
+
+  // Ensure directory exists
+  if (!existsSync(chubDir)) {
+    mkdirSync(chubDir, { recursive: true });
+  }
+
+  writeFileSync(idPath, hash, 'utf8');
+  _cachedClientId = hash;
+  return hash;
+}
+
+/**
+ * Auto-detect the AI coding tool from environment variables.
+ */
+export function detectAgent() {
+  if (process.env.CLAUDE_CODE || process.env.CLAUDE_SESSION_ID) return 'claude-code';
+  if (process.env.CURSOR_SESSION_ID || process.env.CURSOR_TRACE_ID) return 'cursor';
+  if (process.env.CODEX_HOME || process.env.CODEX_SESSION) return 'codex';
+  if (process.env.WINDSURF_SESSION) return 'windsurf';
+  if (process.env.AIDER_MODEL || process.env.AIDER) return 'aider';
+  if (process.env.CLINE_SESSION) return 'cline';
+  if (process.env.GITHUB_COPILOT) return 'copilot';
+  return 'unknown';
+}
+
+/**
+ * Detect the version of the AI coding tool, if available.
+ */
+export function detectAgentVersion() {
+  return process.env.CLAUDE_CODE_VERSION || process.env.CURSOR_VERSION || undefined;
+}

package/src/lib/telemetry.js

@@ -0,0 +1,86 @@
+import { loadConfig } from './config.js';
+
+const DEFAULT_TELEMETRY_URL = 'https://api.aichub.org/v1';
+
+export function isTelemetryEnabled() {
+  if (process.env.CHUB_TELEMETRY === '0' || process.env.CHUB_TELEMETRY === 'false') return false;
+  const config = loadConfig();
+  return config.telemetry !== false;
+}
+
+export function getTelemetryUrl() {
+  const url = process.env.CHUB_TELEMETRY_URL;
+  if (url) return url;
+  const config = loadConfig();
+  return config.telemetry_url || DEFAULT_TELEMETRY_URL;
+}
+
+/**
+ * Send feedback to the API.
+ *
+ * @param {string} entryId - e.g. "openai/chat"
+ * @param {string} entryType - "doc" or "skill"
+ * @param {string} rating - "up" or "down"
+ * @param {object} opts - Additional context
+ * @param {string} [opts.comment]
+ * @param {string} [opts.docLang] - Language variant fetched
+ * @param {string} [opts.docVersion] - Version fetched
+ * @param {string} [opts.targetFile] - Specific file within the entry
+ * @param {string[]} [opts.labels] - Structured feedback labels
+ * @param {string} [opts.agent] - Agent name override
+ * @param {string} [opts.model] - LLM model override
+ * @param {string} [opts.cliVersion]
+ * @param {string} [opts.source] - Registry source name
+ */
+export async function sendFeedback(entryId, entryType, rating, opts = {}) {
+  if (!isTelemetryEnabled()) return { status: 'skipped', reason: 'telemetry_disabled' };
+
+  const { getOrCreateClientId, detectAgent, detectAgentVersion } = await import('./identity.js');
+  const clientId = await getOrCreateClientId();
+  const telemetryUrl = getTelemetryUrl();
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+
+  try {
+    const res = await fetch(`${telemetryUrl}/feedback`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Client-ID': clientId,
+      },
+      body: JSON.stringify({
+        entry_id: entryId,
+        entry_type: entryType,
+        rating,
+        // Doc-specific dimensions
+        doc_lang: opts.docLang || undefined,
+        doc_version: opts.docVersion || undefined,
+        target_file: opts.targetFile || undefined,
+        // Structured feedback
+        labels: opts.labels || undefined,
+        comment: opts.comment || undefined,
+        // Agent info
+        agent: {
+          name: opts.agent || detectAgent(),
+          version: detectAgentVersion(),
+          model: opts.model || undefined,
+        },
+        // Context
+        cli_version: opts.cliVersion || undefined,
+        source: opts.source || undefined,
+      }),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (res.ok) {
+      const data = await res.json();
+      return { status: 'sent', feedback_id: data.feedback_id || data.id };
+    }
+    return { status: 'error', code: res.status };
+  } catch (err) {
+    clearTimeout(timeout);
+    return { status: 'error', reason: 'network' };
+  }
+}