chub-dev 0.1.0 → 0.1.2-beta.0

package/src/index.js

@@ -9,6 +9,10 @@ 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 { registerAnnotateCommand } from './commands/annotate.js';
+import { trackEvent, shutdownAnalytics } from './lib/analytics.js';
+import { error } from './lib/output.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -24,17 +28,31 @@ ${chalk.bold.underline('Getting Started')}
   ${chalk.dim('$')} chub search                                ${chalk.dim('# list everything available')}
   ${chalk.dim('$')} chub search "stripe"                       ${chalk.dim('# fuzzy search')}
   ${chalk.dim('$')} chub search stripe/payments                ${chalk.dim('# exact id → full detail')}
-  ${chalk.dim('$')} chub get docs stripe/payments              ${chalk.dim('# print doc to terminal')}
-  ${chalk.dim('$')} chub get docs stripe/payments -o doc.md    ${chalk.dim('# save to file')}
-  ${chalk.dim('$')} chub get docs stripe/payments --lang py    ${chalk.dim('# specific language')}
-  ${chalk.dim('$')} chub get skills pw/login-flows             ${chalk.dim('# fetch a skill')}
-  ${chalk.dim('$')} chub get docs openai/chat stripe/payments  ${chalk.dim('# fetch multiple')}
+  ${chalk.dim('$')} chub get stripe/api                        ${chalk.dim('# print doc to terminal')}
+  ${chalk.dim('$')} chub get stripe/api -o doc.md              ${chalk.dim('# save to file')}
+  ${chalk.dim('$')} chub get openai/chat --lang py             ${chalk.dim('# specific language')}
+  ${chalk.dim('$')} chub get pw-community/login-flows          ${chalk.dim('# fetch a skill')}
+  ${chalk.dim('$')} chub get openai/chat stripe/api            ${chalk.dim('# fetch multiple')}
+
+${chalk.bold.underline('Learn & Improve')}
+
+  After using a doc, save what you learned so future sessions start smarter:
+
+  ${chalk.dim('$')} chub annotate stripe/api "Webhook needs raw body"   ${chalk.dim('# persists across sessions')}
+  ${chalk.dim('$')} chub annotate --list                                 ${chalk.dim('# see all saved notes')}
+  ${chalk.dim('$')} chub annotate stripe/api --clear                     ${chalk.dim('# remove a note')}
+
+  Rate docs so authors can improve them (ask the user before sending):
+
+  ${chalk.dim('$')} chub feedback stripe/api up                          ${chalk.dim('# worked well')}
+  ${chalk.dim('$')} chub feedback stripe/api down --label outdated       ${chalk.dim('# needs updating')}
 
 ${chalk.bold.underline('Commands')}
 
   ${chalk.bold('search')} [query]              Search docs and skills (no query = list all)
-  ${chalk.bold('get docs')} <ids...>           Fetch documentation content
-  ${chalk.bold('get skills')} <ids...>         Fetch skill content
+  ${chalk.bold('get')} <ids...>                 Fetch docs or skills by ID
+  ${chalk.bold('annotate')} [id] [note]        Save a note — appears on future fetches
+  ${chalk.bold('feedback')} <id> <up|down>     Rate a doc (helps authors improve it)
   ${chalk.bold('update')}                      Refresh the cached registry
   ${chalk.bold('cache')} status|clear          Manage the local cache
   ${chalk.bold('build')} <content-dir>        Build registry from content directory
@@ -54,20 +72,20 @@ ${chalk.bold.underline('Agent Piping Patterns')}
 
   ${chalk.dim('# Search → pick → fetch → save')}
   ${chalk.dim('$')} ID=$(chub search "stripe" --json | jq -r '.results[0].id')
-  ${chalk.dim('$')} chub get docs "$ID" --lang js -o .context/stripe.md
+  ${chalk.dim('$')} chub get "$ID" --lang js -o .context/stripe.md
 
-  ${chalk.dim('# Fetch multiple docs at once')}
-  ${chalk.dim('$')} chub get docs openai/chat stripe/payments -o .context/
+  ${chalk.dim('# Fetch multiple at once')}
+  ${chalk.dim('$')} chub get openai/chat stripe/api -o .context/
 
 ${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')}
 
-  ${chalk.dim('# On id collision, use source: prefix: chub get docs internal:openai/chat')}
+  ${chalk.dim('# On id collision, use source: prefix: chub get internal:openai/chat')}
 `);
 }
 
@@ -76,17 +94,21 @@ const program = new Command();
 program
   .name('chub')
   .description('Context Hub - search and retrieve LLM-optimized docs and skills')
-  .version(pkg.version)
+  .version(pkg.version, '-V, --cli-version')
   .option('--json', 'Output as JSON (machine-readable)')
   .action(() => {
     printUsage();
   });
 
 // Commands that don't need registry
-const SKIP_REGISTRY = ['update', 'cache', 'build', 'help'];
+const SKIP_REGISTRY = ['update', 'cache', 'build', 'feedback', 'annotate', '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)
@@ -94,9 +116,8 @@ program.hook('preAction', async (thisCommand) => {
   try {
     await ensureRegistry();
   } catch (err) {
-    process.stderr.write(`Warning: Could not load registry: ${err.message}\n`);
-    process.stderr.write(`Run \`chub update\` to initialize.\n`);
-    process.exit(1);
+    const globalOpts = thisCommand.optsWithGlobals?.() || {};
+    error(`Registry not available: ${err.message}. Run \`chub update\` to refresh remote registries, or check that local source paths in ~/.chub/config.yaml are correct.`, globalOpts);
   }
 });
 
@@ -105,5 +126,10 @@ registerCacheCommand(program);
 registerSearchCommand(program);
 registerGetCommand(program);
 registerBuildCommand(program);
+registerFeedbackCommand(program);
+registerAnnotateCommand(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_tO9mXIgcCuBccfN2Ut0quf6UFsd06u3Y6g1kqMaYdQX';
+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/annotations.js

@@ -0,0 +1,57 @@
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getChubDir } from './config.js';
+
+function getAnnotationsDir() {
+  return join(getChubDir(), 'annotations');
+}
+
+function annotationPath(entryId) {
+  const safe = entryId.replace(/\//g, '--');
+  return join(getAnnotationsDir(), `${safe}.json`);
+}
+
+export function readAnnotation(entryId) {
+  try {
+    return JSON.parse(readFileSync(annotationPath(entryId), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeAnnotation(entryId, note) {
+  const dir = getAnnotationsDir();
+  mkdirSync(dir, { recursive: true });
+  const data = {
+    id: entryId,
+    note,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(annotationPath(entryId), JSON.stringify(data, null, 2));
+  return data;
+}
+
+export function clearAnnotation(entryId) {
+  try {
+    unlinkSync(annotationPath(entryId));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function listAnnotations() {
+  const dir = getAnnotationsDir();
+  try {
+    const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    return files.map((f) => {
+      try {
+        return JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/lib/bm25.js

@@ -0,0 +1,170 @@
+/**
+ * BM25 search implementation for Context Hub.
+ * Index is built at `chub build` time, scoring happens at search time.
+ * Tokenizer is shared between build and search to ensure consistency.
+ */
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from',
+  'has', 'have', 'in', 'is', 'it', 'its', 'of', 'on', 'or', 'that',
+  'the', 'to', 'was', 'were', 'will', 'with', 'this', 'but', 'not',
+  'you', 'your', 'can', 'do', 'does', 'how', 'if', 'may', 'no',
+  'so', 'than', 'too', 'very', 'just', 'about', 'into', 'over',
+  'such', 'then', 'them', 'these', 'those', 'through', 'under',
+  'use', 'using', 'used',
+]);
+
+// BM25 default parameters
+const DEFAULT_K1 = 1.5;
+const DEFAULT_B = 0.75;
+
+// Field weights for multi-field scoring
+const FIELD_WEIGHTS = {
+  name: 3.0,
+  tags: 2.0,
+  description: 1.0,
+};
+
+/**
+ * Tokenize text into lowercase terms with stop word removal.
+ * Must be used identically at build time and search time.
+ */
+export function tokenize(text) {
+  if (!text) return [];
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/[\s-]+/)
+    .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+
+/**
+ * Build a BM25 search index from registry entries.
+ * Called during `chub build`.
+ *
+ * @param {Array} entries - Combined docs and skills from registry
+ * @returns {Object} The search index
+ */
+export function buildIndex(entries) {
+  const documents = [];
+  const dfMap = {}; // document frequency per term (across all fields)
+  const fieldLengths = { name: [], description: [], tags: [] };
+
+  for (const entry of entries) {
+    const nameTokens = tokenize(entry.name);
+    const descTokens = tokenize(entry.description || '');
+    const tagTokens = (entry.tags || []).flatMap((t) => tokenize(t));
+
+    documents.push({
+      id: entry.id,
+      tokens: {
+        name: nameTokens,
+        description: descTokens,
+        tags: tagTokens,
+      },
+    });
+
+    fieldLengths.name.push(nameTokens.length);
+    fieldLengths.description.push(descTokens.length);
+    fieldLengths.tags.push(tagTokens.length);
+
+    // Count document frequency — a term counts once per document (union of all fields)
+    const allTerms = new Set([...nameTokens, ...descTokens, ...tagTokens]);
+    for (const term of allTerms) {
+      dfMap[term] = (dfMap[term] || 0) + 1;
+    }
+  }
+
+  const N = documents.length;
+
+  // Compute IDF for each term
+  const idf = {};
+  for (const [term, df] of Object.entries(dfMap)) {
+    idf[term] = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+  }
+
+  // Compute average field lengths
+  const avg = (arr) => arr.length === 0 ? 0 : arr.reduce((a, b) => a + b, 0) / arr.length;
+  const avgFieldLengths = {
+    name: avg(fieldLengths.name),
+    description: avg(fieldLengths.description),
+    tags: avg(fieldLengths.tags),
+  };
+
+  return {
+    version: '1.0.0',
+    algorithm: 'bm25',
+    params: { k1: DEFAULT_K1, b: DEFAULT_B },
+    totalDocs: N,
+    avgFieldLengths,
+    idf,
+    documents,
+  };
+}
+
+/**
+ * Compute BM25 score for a single field.
+ */
+function scoreField(queryTerms, fieldTokens, idf, avgFieldLen, k1, b) {
+  if (fieldTokens.length === 0) return 0;
+
+  // Build term frequency map for this field
+  const tf = {};
+  for (const t of fieldTokens) {
+    tf[t] = (tf[t] || 0) + 1;
+  }
+
+  let score = 0;
+  const dl = fieldTokens.length;
+
+  for (const term of queryTerms) {
+    const termFreq = tf[term] || 0;
+    if (termFreq === 0) continue;
+
+    const termIdf = idf[term] || 0;
+    const numerator = termFreq * (k1 + 1);
+    const denominator = termFreq + k1 * (1 - b + b * (dl / (avgFieldLen || 1)));
+    score += termIdf * (numerator / denominator);
+  }
+
+  return score;
+}
+
+/**
+ * Search the BM25 index with a query string.
+ *
+ * @param {string} query - The search query
+ * @param {Object} index - The pre-built BM25 index
+ * @param {Object} opts - Options: { limit }
+ * @returns {Array} Sorted results: [{ id, score }]
+ */
+export function search(query, index, opts = {}) {
+  const queryTerms = tokenize(query);
+  if (queryTerms.length === 0) return [];
+
+  const { k1, b } = index.params;
+  const results = [];
+
+  for (const doc of index.documents) {
+    let totalScore = 0;
+
+    for (const [field, weight] of Object.entries(FIELD_WEIGHTS)) {
+      const fieldTokens = doc.tokens[field] || [];
+      const avgLen = index.avgFieldLengths[field] || 1;
+      const fieldScore = scoreField(queryTerms, fieldTokens, index.idf, avgLen, k1, b);
+      totalScore += fieldScore * weight;
+    }
+
+    if (totalScore > 0) {
+      results.push({ id: doc.id, score: totalScore });
+    }
+  }
+
+  results.sort((a, b) => b.score - a.score);
+
+  if (opts.limit) {
+    return results.slice(0, opts.limit);
+  }
+
+  return results;
+}

package/src/lib/cache.js

@@ -1,9 +1,20 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { createWriteStream } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { getChubDir, loadConfig } from './config.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Path to bundled content shipped with the npm package.
+ * Contains registry.json + doc files built from content/ at publish time.
+ */
+function getBundledDir() {
+  return join(__dirname, '..', '..', 'dist');
+}
+
 function getSourceDir(sourceName) {
   return join(getChubDir(), 'sources', sourceName);
 }
@@ -51,7 +62,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 +113,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}`);
   }
@@ -139,9 +164,22 @@ export async function fetchDoc(source, docPath) {
     return readFileSync(cachedPath, 'utf8');
   }
 
-  // Fetch from CDN
+  // Check bundled content (shipped with npm package)
+  const bundledPath = join(getBundledDir(), docPath);
+  if (existsSync(bundledPath)) {
+    return readFileSync(bundledPath, 'utf8');
+  }
+
+  // Fetch from CDN (optional — only if source has a URL)
   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}`);
   }
@@ -187,6 +225,20 @@ export function loadSourceRegistry(source) {
   return JSON.parse(readFileSync(regPath, 'utf8'));
 }
 
+/**
+ * Load BM25 search index for a single source (if available).
+ */
+export function loadSearchIndex(source) {
+  const basePath = source.path || getSourceDir(source.name);
+  const indexPath = join(basePath, 'search-index.json');
+  if (!existsSync(indexPath)) return null;
+  try {
+    return JSON.parse(readFileSync(indexPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Get cache stats.
  */
@@ -282,6 +334,17 @@ export async function ensureRegistry() {
     return;
   }
 
-  // No registries at all — must download remote ones
+  // No registries at all — try bundled content first, then network
+  const bundledRegistry = join(getBundledDir(), 'registry.json');
+  if (existsSync(bundledRegistry)) {
+    // Seed cache from bundled content (ships with npm package)
+    const defaultDir = getSourceDir('default');
+    mkdirSync(defaultDir, { recursive: true });
+    writeFileSync(getSourceRegistryPath('default'), readFileSync(bundledRegistry, 'utf8'));
+    writeMeta('default', { lastUpdated: 0, bundledSeed: true }); // lastUpdated=0 → stale, so chub update will refresh
+    return;
+  }
+
+  // No bundled content either — must download from remote
   await fetchAllRegistries(true);
 }

package/src/lib/config.js

@@ -3,19 +3,22 @@ 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,
+  refresh_interval: 21600,
   output_format: 'human',
   source: 'official,maintainer,community',
+  telemetry: true,
+  telemetry_url: DEFAULT_TELEMETRY_URL,
 };
 
 let _config = null;
 
 export function getChubDir() {
-  return join(homedir(), '.chub');
+  return process.env.CHUB_DIR || join(homedir(), '.chub');
 }
 
 export function loadConfig() {
@@ -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;
+}