qaa-agent 1.9.1 → 1.9.5

package/bin/lib/context7-cache.cjs

@@ -0,0 +1,299 @@
+/**
+ * Context7 Cache — version-specific cache of Context7 query responses.
+ *
+ * Stores cached responses in `.qa-output/frameworks/<framework>-<version>.json`
+ * (project-local). When agents need framework documentation, they check the
+ * cache first before querying Context7. This:
+ *   - Reduces Context7 API calls (free tier: 60/hour)
+ *   - Speeds up subsequent pipeline runs
+ *   - Auto-invalidates when project version changes (filename includes version)
+ *
+ * Cache file format:
+ * {
+ *   "framework": "playwright",
+ *   "version": "1.40.0",
+ *   "cached_at": "2026-05-05",
+ *   "ttl_days": 30,
+ *   "library_id": "/microsoft/playwright/v1.40.0",
+ *   "metadata_from_template": { ... },  // copied from frameworks/<name>.json
+ *   "context7_cache": {
+ *     "queries": {
+ *       "<query-key>": {
+ *         "queried_at": "2026-05-05",
+ *         "response": "...raw response..."
+ *       }
+ *     }
+ *   },
+ *   "version_note": {
+ *     "project_version": "1.40.0",
+ *     "latest_stable": "1.50.0",
+ *     "notable_changes": [...]
+ *   }
+ * }
+ *
+ * Cache invalidation triggers:
+ *   1. Filename includes version → version change auto-invalidates
+ *   2. ttl_days expired → entry needs refresh
+ *   3. Force refresh via --refresh-cache flag in commands
+ *
+ * Usage from bash:
+ *   node bin/lib/context7-cache.cjs read <framework> <version> <query-key>
+ *   node bin/lib/context7-cache.cjs write <framework> <version> <query-key> <response>
+ *   node bin/lib/context7-cache.cjs status <framework> <version>
+ *   node bin/lib/context7-cache.cjs init <framework> <version>     # bootstrap from registry
+ *
+ * Usage from JS:
+ *   const cache = require('./context7-cache.cjs');
+ *   const cached = cache.read('playwright', '1.40.0', 'selector-syntax');
+ *   if (!cached) {
+ *     const response = await callContext7(...);
+ *     cache.write('playwright', '1.40.0', 'selector-syntax', response);
+ *   }
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_TTL_DAYS = 30;
+
+// Where the cache lives (project-local)
+function cacheDir(outputDir) {
+  return path.join(outputDir || '.qa-output', 'frameworks');
+}
+
+function cachePath(framework, version, outputDir) {
+  return path.join(cacheDir(outputDir), `${framework}-${version}.json`);
+}
+
+function registryPath(framework) {
+  return path.join('frameworks', `${framework}.json`);
+}
+
+// ── Date helpers ──────────────────────────────────────────────────────────
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function daysBetween(dateStr) {
+  const cached = new Date(dateStr);
+  const now = new Date();
+  const ms = now - cached;
+  return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+
+// ── Core cache operations ─────────────────────────────────────────────────
+
+/**
+ * Initialize a cache file for (framework, version) if it doesn't exist.
+ * Bootstraps with metadata from the registry. Returns the cache object.
+ */
+function init(framework, version, outputDir) {
+  const cp = cachePath(framework, version, outputDir);
+  if (fs.existsSync(cp)) {
+    return JSON.parse(fs.readFileSync(cp, 'utf-8'));
+  }
+
+  // Load metadata from registry if available
+  let metadataFromTemplate = {};
+  const rp = registryPath(framework);
+  if (fs.existsSync(rp)) {
+    try {
+      metadataFromTemplate = JSON.parse(fs.readFileSync(rp, 'utf-8'));
+    } catch (e) {
+      // ignore registry parse errors
+    }
+  }
+
+  const libraryId = metadataFromTemplate.context7_keys && metadataFromTemplate.context7_keys[0]
+    ? `/${metadataFromTemplate.context7_keys[0]}/v${version}`
+    : null;
+
+  const cache = {
+    framework,
+    version,
+    cached_at: today(),
+    ttl_days: DEFAULT_TTL_DAYS,
+    library_id: libraryId,
+    metadata_from_template: metadataFromTemplate,
+    context7_cache: {
+      queries: {}
+    },
+    version_note: {
+      project_version: version,
+      latest_stable: null,
+      notable_changes: []
+    }
+  };
+
+  fs.mkdirSync(cacheDir(outputDir), { recursive: true });
+  fs.writeFileSync(cp, JSON.stringify(cache, null, 2) + '\n', 'utf-8');
+  return cache;
+}
+
+/**
+ * Read a cached query response. Returns null if not cached or expired.
+ */
+function read(framework, version, queryKey, outputDir) {
+  const cp = cachePath(framework, version, outputDir);
+  if (!fs.existsSync(cp)) return null;
+
+  let cache;
+  try {
+    cache = JSON.parse(fs.readFileSync(cp, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+
+  const entry = cache.context7_cache?.queries?.[queryKey];
+  if (!entry) return null;
+
+  // Check TTL
+  const ttl = cache.ttl_days || DEFAULT_TTL_DAYS;
+  const age = daysBetween(entry.queried_at || cache.cached_at);
+  if (age > ttl) return null;  // expired
+
+  return entry.response;
+}
+
+/**
+ * Write a query response to the cache. Creates the cache file if needed.
+ */
+function write(framework, version, queryKey, response, outputDir) {
+  const cp = cachePath(framework, version, outputDir);
+  let cache;
+  if (fs.existsSync(cp)) {
+    cache = JSON.parse(fs.readFileSync(cp, 'utf-8'));
+  } else {
+    cache = init(framework, version, outputDir);
+  }
+
+  if (!cache.context7_cache) cache.context7_cache = { queries: {} };
+  if (!cache.context7_cache.queries) cache.context7_cache.queries = {};
+
+  cache.context7_cache.queries[queryKey] = {
+    queried_at: today(),
+    response: response
+  };
+
+  fs.mkdirSync(cacheDir(outputDir), { recursive: true });
+  fs.writeFileSync(cp, JSON.stringify(cache, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Get cache freshness/status info for (framework, version).
+ */
+function status(framework, version, outputDir) {
+  const cp = cachePath(framework, version, outputDir);
+  if (!fs.existsSync(cp)) {
+    return { exists: false, framework, version };
+  }
+
+  const cache = JSON.parse(fs.readFileSync(cp, 'utf-8'));
+  const ttl = cache.ttl_days || DEFAULT_TTL_DAYS;
+  const age = daysBetween(cache.cached_at);
+  const queryKeys = Object.keys(cache.context7_cache?.queries || {});
+
+  return {
+    exists: true,
+    framework,
+    version,
+    cache_path: cp,
+    cached_at: cache.cached_at,
+    age_days: age,
+    ttl_days: ttl,
+    expired: age > ttl,
+    library_id: cache.library_id,
+    cached_queries: queryKeys,
+    cached_query_count: queryKeys.length
+  };
+}
+
+/**
+ * Force refresh: delete the cache file. Next read will trigger Context7 query.
+ */
+function clear(framework, version, outputDir) {
+  const cp = cachePath(framework, version, outputDir);
+  if (fs.existsSync(cp)) {
+    fs.unlinkSync(cp);
+    return true;
+  }
+  return false;
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────
+
+module.exports = {
+  init,
+  read,
+  write,
+  status,
+  clear,
+  cachePath,
+  cacheDir,
+  registryPath,
+  DEFAULT_TTL_DAYS
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const [cmd, ...args] = process.argv.slice(2);
+
+  function usage() {
+    console.error('Usage:');
+    console.error('  context7-cache.cjs init <framework> <version>');
+    console.error('  context7-cache.cjs read <framework> <version> <query-key>');
+    console.error('  context7-cache.cjs write <framework> <version> <query-key> <response-text>');
+    console.error('  context7-cache.cjs status <framework> <version>');
+    console.error('  context7-cache.cjs clear <framework> <version>');
+    process.exit(1);
+  }
+
+  try {
+    switch (cmd) {
+      case 'init': {
+        if (args.length < 2) usage();
+        const cache = init(args[0], args[1]);
+        console.log(JSON.stringify(cache, null, 2));
+        break;
+      }
+      case 'read': {
+        if (args.length < 3) usage();
+        const r = read(args[0], args[1], args[2]);
+        if (r === null) {
+          console.log('CACHE_MISS');
+          process.exit(2);
+        } else {
+          console.log(r);
+        }
+        break;
+      }
+      case 'write': {
+        if (args.length < 4) usage();
+        const response = args.slice(3).join(' ');
+        write(args[0], args[1], args[2], response);
+        console.log('OK');
+        break;
+      }
+      case 'status': {
+        if (args.length < 2) usage();
+        console.log(JSON.stringify(status(args[0], args[1]), null, 2));
+        break;
+      }
+      case 'clear': {
+        if (args.length < 2) usage();
+        const ok = clear(args[0], args[1]);
+        console.log(ok ? 'CLEARED' : 'NOT_FOUND');
+        break;
+      }
+      default:
+        usage();
+    }
+  } catch (e) {
+    console.error('ERROR:', e.message);
+    process.exit(1);
+  }
+}