@mcptoolshop/claude-synergy 1.0.0 → 1.1.0

package/dist/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import {
-  OllamaEmbeddingProvider,
-  VoyageEmbeddingProvider,
+  AppError,
+  browseChanges,
+  embedAll,
   entityFrequency,
+  formatError,
+  getChangesSince,
   hybridSearch,
   initSchema,
   listProducts,
@@ -10,411 +13,22 @@ import {
   openDb,
   recentReleases,
   searchChanges
-} from "./chunk-YFGUTT22.js";
+} from "./chunk-H3466JDH.js";
 import {
   ingestAll,
   loadProductsConfig
-} from "./chunk-HCIZPSW4.js";
+} from "./chunk-HZEQG3WT.js";
 
 // src/cli.ts
 import { Command, Option } from "commander";
-import { join as join4, resolve as resolve2 } from "path";
+import { join as join3, resolve as resolve2 } from "path";
 import { existsSync as existsSync2 } from "fs";
 import { createRequire } from "module";
 
-// src/embed.ts
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-
-// src/providers/context/none.ts
-var NoneContextProvider = class {
-  name = "none";
-  async contextFor(_chunk, _release) {
-    return "";
-  }
-};
-
-// src/providers/context/structured.ts
-var StructuredContextProvider = class {
-  name = "structured";
-  async contextFor(chunk, release) {
-    const date = release.releasedAt ?? "unknown date";
-    const positional = `change ${chunk.ordinalInRelease} of ${chunk.totalInRelease}`;
-    return `In ${release.product} ${release.version} (${date}), ${chunk.kind} (${positional}):`;
-  }
-};
-
-// src/providers/context/ollama.ts
-function providerTimeoutMs() {
-  const raw = process.env.CLAUDE_SYNERGY_PROVIDER_TIMEOUT_MS;
-  const n = raw === void 0 ? NaN : parseInt(raw, 10);
-  return Number.isFinite(n) && n > 0 ? n : 6e4;
-}
-async function safeErrorBody(res, max = 200) {
-  try {
-    const body = await res.text();
-    const safe = body.split("\n").filter((l) => !/x-api-key|authorization|bearer|api[-_]?key/i.test(l)).join("\n");
-    return safe.slice(0, max);
-  } catch {
-    return "<unreadable>";
-  }
-}
-var OllamaContextProvider = class {
-  name = "ollama";
-  host;
-  model;
-  constructor(opts = {}) {
-    const rawHost = opts.host ?? process.env.OLLAMA_HOST ?? "http://localhost:11434";
-    this.host = /^https?:\/\//.test(rawHost) ? rawHost : `http://${rawHost}`;
-    this.model = opts.model ?? process.env.OLLAMA_GEN_MODEL ?? "llama3.2:3b";
-  }
-  async contextFor(chunk, release) {
-    const releaseSnippet = release.siblings.map((s, i) => `${i + 1}. ${s.text}`).slice(0, 30).join("\n");
-    const prompt = [
-      `<document>`,
-      `${release.product} ${release.version} release notes (${release.releasedAt ?? "unknown date"}):`,
-      releaseSnippet,
-      `</document>`,
-      ``,
-      `Here is the chunk we want to situate within the whole document:`,
-      `<chunk>`,
-      chunk.text,
-      `</chunk>`,
-      ``,
-      `Please give a short succinct context (1 sentence, max 30 words) to situate this chunk within the overall document for improving search retrieval of the chunk. Mention any related product names, env vars, command names, or APIs. Answer only with the succinct context and nothing else.`
-    ].join("\n");
-    const timeoutMs = providerTimeoutMs();
-    let res;
-    try {
-      res = await fetch(`${this.host}/api/generate`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({
-          model: this.model,
-          prompt,
-          stream: false,
-          options: { temperature: 0, num_predict: 80 }
-        }),
-        signal: AbortSignal.timeout(timeoutMs)
-      });
-    } catch (e) {
-      if (e?.name === "TimeoutError" || e?.name === "AbortError") {
-        throw new Error(`Ollama context request timed out after ${timeoutMs}ms \u2014 is the Ollama server responsive?`);
-      }
-      throw e;
-    }
-    if (!res.ok) throw new Error(`Ollama ${res.status}: ${await safeErrorBody(res)}`);
-    const json = await res.json();
-    return json.response.trim();
-  }
-};
-
-// src/providers/context/claude-haiku.ts
-function providerTimeoutMs2() {
-  const raw = process.env.CLAUDE_SYNERGY_PROVIDER_TIMEOUT_MS;
-  const n = raw === void 0 ? NaN : parseInt(raw, 10);
-  return Number.isFinite(n) && n > 0 ? n : 6e4;
-}
-async function safeErrorBody2(res, max = 200) {
-  try {
-    const body = await res.text();
-    const safe = body.split("\n").filter((l) => !/x-api-key|authorization|bearer|api[-_]?key/i.test(l)).join("\n");
-    return safe.slice(0, max);
-  } catch {
-    return "<unreadable>";
-  }
-}
-var ClaudeHaikuContextProvider = class {
-  name = "claude-haiku";
-  apiKey;
-  model;
-  cachedDocByRelease = /* @__PURE__ */ new Map();
-  constructor(opts = {}) {
-    this.apiKey = opts.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
-    this.model = opts.model ?? "claude-haiku-4-5-20251001";
-    if (!this.apiKey) {
-      throw new Error("claude-haiku context provider requires ANTHROPIC_API_KEY");
-    }
-  }
-  async contextFor(chunk, release) {
-    const releaseKey = `${release.product}@${release.version}`;
-    let doc = this.cachedDocByRelease.get(releaseKey);
-    if (!doc) {
-      doc = release.siblings.map((s, i) => `${i + 1}. ${s.text}`).join("\n");
-      this.cachedDocByRelease.set(releaseKey, doc);
-    }
-    const userPrompt = [
-      `Chunk: ${chunk.text}`,
-      ``,
-      `Give a 1-sentence context (max 30 words) situating this chunk in the release. Mention related products, env vars, commands. Output ONLY the context.`
-    ].join("\n");
-    const timeoutMs = providerTimeoutMs2();
-    let res;
-    try {
-      res = await fetch("https://api.anthropic.com/v1/messages", {
-        method: "POST",
-        headers: {
-          "x-api-key": this.apiKey,
-          "anthropic-version": "2023-06-01",
-          "content-type": "application/json"
-        },
-        body: JSON.stringify({
-          model: this.model,
-          max_tokens: 80,
-          system: [
-            {
-              type: "text",
-              text: `${release.product} ${release.version} (${release.releasedAt}) release notes:
-${doc}`,
-              cache_control: { type: "ephemeral" }
-            }
-          ],
-          messages: [{ role: "user", content: userPrompt }]
-        }),
-        signal: AbortSignal.timeout(timeoutMs)
-      });
-    } catch (e) {
-      if (e?.name === "TimeoutError" || e?.name === "AbortError") {
-        throw new Error(`Anthropic API request timed out after ${timeoutMs}ms \u2014 is the API responsive?`);
-      }
-      throw e;
-    }
-    if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${await safeErrorBody2(res)}`);
-    const json = await res.json();
-    return (json.content.find((c) => c.type === "text")?.text ?? "").trim();
-  }
-};
-
-// src/embed.ts
-var __dirname2 = dirname(fileURLToPath(import.meta.url));
-function initVecSchema(db) {
-  const existing = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='chunks'`).get();
-  if (existing) return;
-  const schemaPath = resolveSchemaVecPath();
-  const sql = readFileSync(schemaPath, "utf-8");
-  db.exec(sql);
-}
-function resolveSchemaVecPath() {
-  const candidates = [
-    join(__dirname2, "..", "schema-vec.sql"),
-    join(process.cwd(), "schema-vec.sql")
-  ];
-  for (const p of candidates) {
-    try {
-      readFileSync(p);
-      return p;
-    } catch {
-    }
-  }
-  throw new Error(`schema-vec.sql not found in: ${candidates.join(", ")}`);
-}
-async function embedAll(db, opts) {
-  initVecSchema(db);
-  const ctx = makeContextProvider(opts.contextProviderName);
-  const emb = makeEmbeddingProvider(opts.embeddingProviderName);
-  const productFilter = opts.product ? "AND c.product = @product" : "";
-  const forceFilter = opts.force ? "" : "AND ch.id IS NULL";
-  const limitClause = opts.limit ? "LIMIT @limit" : "";
-  const pendingSql = `
-    SELECT c.id AS change_id, c.product, c.version, r.released_at, c.kind, c.text, c.ordinal
-    FROM changes c
-    JOIN releases r ON c.product = r.product AND c.version = r.version
-    LEFT JOIN chunks ch ON ch.change_id = c.id
-    WHERE 1=1
-      ${productFilter}
-      ${forceFilter}
-    ORDER BY c.product, c.version, c.ordinal
-    ${limitClause}
-  `;
-  const params = {};
-  if (opts.product) params.product = opts.product;
-  if (opts.limit) params.limit = opts.limit;
-  const pending = db.prepare(pendingSql).all(params);
-  if (pending.length === 0) {
-    return {
-      contextProvider: ctx.name,
-      embeddingProvider: emb.name,
-      chunksCreated: 0,
-      chunksSkipped: 0,
-      contextMs: 0,
-      embedMs: 0,
-      totalMs: 0
-    };
-  }
-  const byRelease = /* @__PURE__ */ new Map();
-  for (const row of pending) {
-    const key = `${row.product}@${row.version}`;
-    if (!byRelease.has(key)) byRelease.set(key, []);
-    byRelease.get(key).push({
-      changeId: row.change_id,
-      product: row.product,
-      releaseVersion: row.version,
-      releasedAt: row.released_at,
-      kind: row.kind,
-      text: row.text,
-      ordinalInRelease: row.ordinal,
-      totalInRelease: 0
-      // backfilled below
-    });
-  }
-  for (const [, list] of byRelease) {
-    for (const c of list) c.totalInRelease = list.length;
-  }
-  const startTotal = Date.now();
-  let contextMs = 0;
-  let embedMs = 0;
-  const contextsByChange = /* @__PURE__ */ new Map();
-  const allChunks = [];
-  for (const [, siblings] of byRelease) {
-    const release = {
-      product: siblings[0].product,
-      version: siblings[0].releaseVersion,
-      releasedAt: siblings[0].releasedAt,
-      siblings
-    };
-    for (const chunk of siblings) {
-      if (opts.signal?.aborted) break;
-      const t0 = Date.now();
-      const ctxPrefix = await ctx.contextFor(chunk, release);
-      contextMs += Date.now() - t0;
-      contextsByChange.set(chunk.changeId, ctxPrefix);
-      allChunks.push(chunk);
-    }
-    if (opts.signal?.aborted) break;
-  }
-  const batchSize = opts.batchSize ?? 64;
-  const insertChunk = db.prepare(`
-    INSERT OR REPLACE INTO chunks
-      (change_id, product, release_version, released_at, context_prefix, original_text, contextualized, context_provider, embedding_model, embedded_at)
-    VALUES
-      (@change_id, @product, @release_version, @released_at, @context_prefix, @original_text, @contextualized, @context_provider, @embedding_model, @embedded_at)
-  `);
-  const deleteVec = db.prepare(`DELETE FROM chunks_vec WHERE rowid = ?`);
-  const insertVec = db.prepare(`INSERT INTO chunks_vec(rowid, embedding) VALUES (?, ?)`);
-  let created = 0;
-  let stoppedEarly = false;
-  let stopReason;
-  const usage = { requests: 0, tokens: 0 };
-  const totalBatches = Math.ceil(allChunks.length / batchSize);
-  for (let i = 0; i < allChunks.length; i += batchSize) {
-    if (opts.signal?.aborted) {
-      stoppedEarly = true;
-      stopReason = "cancelled";
-      break;
-    }
-    if (opts.maxRequests !== void 0 && usage.requests >= opts.maxRequests) {
-      stoppedEarly = true;
-      stopReason = "budget_requests";
-      break;
-    }
-    if (opts.maxTokens !== void 0 && usage.tokens >= opts.maxTokens) {
-      stoppedEarly = true;
-      stopReason = "budget_tokens";
-      break;
-    }
-    const batch = allChunks.slice(i, i + batchSize);
-    const texts = batch.map((c) => {
-      const prefix = contextsByChange.get(c.changeId) ?? "";
-      return prefix ? `${prefix}
-
-${c.text}` : c.text;
-    });
-    const t0 = Date.now();
-    const vectors = await emb.embed(texts);
-    embedMs += Date.now() - t0;
-    usage.requests++;
-    if ("usage" in emb) {
-      const provUsage = emb.usage;
-      if (provUsage && typeof provUsage.tokens === "number") {
-        usage.tokens = provUsage.tokens;
-      }
-    }
-    const tx = db.transaction(() => {
-      for (let j = 0; j < batch.length; j++) {
-        const c = batch[j];
-        const prefix = contextsByChange.get(c.changeId) ?? "";
-        const contextualized = prefix ? `${prefix}
-
-${c.text}` : c.text;
-        const result = insertChunk.run({
-          change_id: c.changeId,
-          product: c.product,
-          release_version: c.releaseVersion,
-          released_at: c.releasedAt,
-          context_prefix: prefix,
-          original_text: c.text,
-          contextualized,
-          context_provider: ctx.name,
-          embedding_model: `${emb.name}:${emb.model}`,
-          embedded_at: (/* @__PURE__ */ new Date()).toISOString()
-        });
-        const chunkId = Number(result.lastInsertRowid);
-        deleteVec.run(chunkId);
-        insertVec.run(BigInt(chunkId), vectors[j]);
-        created++;
-      }
-    });
-    tx();
-    if (opts.onProgress) {
-      opts.onProgress({
-        batchesCompleted: Math.floor(i / batchSize) + 1,
-        batchesTotal: totalBatches,
-        chunksCompleted: created,
-        chunksTotal: allChunks.length,
-        provider: `${emb.name}:${emb.model}`,
-        tokensUsed: usage.tokens,
-        requestsMade: usage.requests
-      });
-    }
-  }
-  const stats = {
-    contextProvider: ctx.name,
-    embeddingProvider: `${emb.name}:${emb.model}`,
-    chunksCreated: created,
-    chunksSkipped: 0,
-    contextMs,
-    embedMs,
-    totalMs: Date.now() - startTotal
-  };
-  if (usage.requests > 0) {
-    stats.usage = usage;
-  }
-  if (stoppedEarly) {
-    stats.stoppedEarly = true;
-    stats.stopReason = stopReason;
-  }
-  return stats;
-}
-function makeContextProvider(name) {
-  switch (name) {
-    case "none":
-      return new NoneContextProvider();
-    case "structured":
-      return new StructuredContextProvider();
-    case "ollama":
-      return new OllamaContextProvider();
-    case "claude-haiku":
-      return new ClaudeHaikuContextProvider();
-    default:
-      throw new Error(`unknown context provider: ${name}`);
-  }
-}
-function makeEmbeddingProvider(name) {
-  switch (name) {
-    case "ollama":
-      return new OllamaEmbeddingProvider();
-    case "voyage":
-      return new VoyageEmbeddingProvider();
-    default:
-      throw new Error(`unknown embedding provider: ${name}`);
-  }
-}
-
 // src/fetch.ts
 import { execFileSync } from "child_process";
 import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, existsSync } from "fs";
-import { join as join3, resolve } from "path";
+import { join as join2, resolve } from "path";
 
 // src/fetch-rss.ts
 import { XMLParser } from "fast-xml-parser";
@@ -660,6 +274,51 @@ function parseAiderHistory(md) {
   flush();
   return out.filter((i) => i.body.length > 0 || i.version !== "main");
 }
+async function fetchKeepAChangelog(url, sinceIso, signal) {
+  const res = await fetchWithRetry(url, {
+    headers: { "user-agent": "claude-synergy/0.1.0" },
+    signal
+  });
+  if (!res.ok) throw new Error(`raw-changelog ${url} returned ${res.status}`);
+  const md = await res.text();
+  const items = parseKeepAChangelog(md);
+  return items.filter((i) => i.releasedAt !== null && i.releasedAt > sinceIso);
+}
+function parseKeepAChangelog(md) {
+  const lines = md.split(/\r?\n/);
+  const out = [];
+  const versionLineRe = /^##\s+(?:\[\s*)?(v?\d[\w.+\-]*?)(?:\s*\])?\s*(?:[-–(]\s*(\d{4}-\d{2}-\d{2})\s*\)?)?\s*$/i;
+  let currentVersion = null;
+  let currentDate = null;
+  let currentBody = [];
+  const flush = () => {
+    if (!currentVersion) return;
+    out.push({
+      version: currentVersion,
+      releasedAt: currentDate,
+      body: currentBody.join("\n").trim()
+    });
+    currentVersion = null;
+    currentDate = null;
+    currentBody = [];
+  };
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      const match = line.match(versionLineRe);
+      if (match) {
+        flush();
+        currentVersion = match[1].replace(/^v/i, "");
+        currentDate = match[2] ?? null;
+        continue;
+      }
+      flush();
+      continue;
+    }
+    if (currentVersion) currentBody.push(line);
+  }
+  flush();
+  return out.filter((i) => i.body.length > 0);
+}
 function aiderReleaseDates() {
   try {
     const out = execSync(`gh api "repos/Aider-AI/aider/releases?per_page=100"`, {
@@ -902,7 +561,7 @@ async function fetchHtmlReleases(parser, sinceIso, signal) {
 
 // src/fetch-mcp-registry.ts
 import { writeFileSync, mkdirSync } from "fs";
-import { join as join2 } from "path";
+import { join } from "path";
 var UA2 = { "user-agent": "claude-synergy/0.1.0", accept: "application/json" };
 async function fetchOfficialMcpRegistry(opts = {}) {
   const maxPages = opts.maxPages ?? 50;
@@ -974,7 +633,7 @@ async function fetchSmitheryRegistry(opts = {}) {
 }
 function writeCatalog(productDir, productName, entries) {
   mkdirSync(productDir, { recursive: true });
-  const catalogPath = join2(productDir, "CATALOG.md");
+  const catalogPath = join(productDir, "CATALOG.md");
   const lines = [];
   lines.push(`# ${productName} \u2014 MCP server catalog`);
   lines.push("");
@@ -1044,6 +703,9 @@ function assertSafeFilename(name, context) {
 }
 var HARDCODED_FALLBACK_TARGETS = [
   // ── Existing Anthropic GH-Releases sources ────────────────────────────────
+  // FE-1: claude-code is the flagship product — wired to gh-releases because the
+  // repo publishes Releases whose bodies mirror CHANGELOG.md but carry real dates.
+  { product: "claude-code", strategy: "gh-releases", repo: "anthropics/claude-code" },
   { product: "claude-agent-sdk-python", strategy: "gh-releases", repo: "anthropics/claude-agent-sdk-python" },
   { product: "claude-agent-sdk-typescript", strategy: "gh-releases", repo: "anthropics/claude-agent-sdk-typescript" },
   { product: "anthropic-cli", strategy: "gh-releases", repo: "anthropics/anthropic-cli" },
@@ -1193,8 +855,8 @@ async function fetchGhReleases(db, outDir, target, since) {
       assertSafeFilename(filename, `gh-releases filename for tag ${JSON.stringify(r.tag_name)}`);
       const vName = sanitizeFilename(`v${baseName}`);
       assertSafeFilename(vName, `gh-releases vName for tag ${JSON.stringify(r.tag_name)}`);
-      const path = join3(outDir, `${filename}.md`);
-      const vPath = join3(outDir, `${vName}.md`);
+      const path = join2(outDir, `${filename}.md`);
+      const vPath = join2(outDir, `${vName}.md`);
       if (existsSync(path) || existsSync(vPath)) {
         if (!latest || r.published_at > latest) latest = r.published_at;
         continue;
@@ -1223,7 +885,7 @@ function ghReleases(repo, sinceIso) {
       );
     } catch (e) {
       const stderr = (e.stderr ?? "").toString();
-      if (stderr.includes("404")) return page === 1 ? [] : all;
+      if (stderr.includes("404")) return page === 1 ? [] : filterAndShape(all, sinceIso);
       if (stderr.includes("403") || stderr.includes("429") || stderr.includes("rate limit")) {
         throw new Error(
           `GitHub API rate limit hit for ${repo}. Set GITHUB_TOKEN env var for 5000 req/hr (vs 60 unauthenticated). Original error: ${e.message}`
@@ -1235,12 +897,19 @@ function ghReleases(repo, sinceIso) {
     try {
       batch = JSON.parse(out);
     } catch {
-      return page === 1 ? [] : all;
+      return page === 1 ? [] : filterAndShape(all, sinceIso);
     }
     if (!Array.isArray(batch) || batch.length === 0) break;
     all.push(...batch);
+    if (batch.length === 100) {
+      const lastPubAt = batch[batch.length - 1]?.published_at;
+      if (lastPubAt && lastPubAt <= sinceIso) break;
+    }
     if (batch.length < 100) break;
   }
+  return filterAndShape(all, sinceIso);
+}
+function filterAndShape(all, sinceIso) {
   return all.filter((r) => r.published_at && r.published_at > sinceIso).map((r) => ({
     tag_name: r.tag_name,
     published_at: r.published_at,
@@ -1286,7 +955,7 @@ async function fetchRss(db, outDir, target, since, signal) {
     try {
       const safeSlug = sanitizeFilename(item.slug);
       assertSafeFilename(safeSlug, `rss slug for ${JSON.stringify(item.slug)}`);
-      const path = join3(outDir, `${safeSlug}.md`);
+      const path = join2(outDir, `${safeSlug}.md`);
       if (existsSync(path)) {
         if (!latest || item.pubDate > latest) latest = item.pubDate;
         continue;
@@ -1318,10 +987,17 @@ async function fetchRss(db, outDir, target, since, signal) {
 }
 async function fetchRawChangelog(db, outDir, target, since, signal) {
   if (!target.rawChangelogUrl) throw new Error(`${target.product}: raw-changelog requires url`);
-  if (target.rawChangelogParser !== "aider-history") {
-    throw new Error(`${target.product}: unsupported parser ${target.rawChangelogParser}`);
+  let items;
+  switch (target.rawChangelogParser) {
+    case "aider-history":
+      items = await fetchAiderHistory(target.rawChangelogUrl, since, signal);
+      break;
+    case "keep-a-changelog":
+      items = await fetchKeepAChangelog(target.rawChangelogUrl, since, signal);
+      break;
+    default:
+      throw new Error(`${target.product}: unsupported parser ${target.rawChangelogParser}`);
   }
-  const items = await fetchAiderHistory(target.rawChangelogUrl, since, signal);
   let latest = null;
   let fetched = 0;
   const errors = [];
@@ -1329,7 +1005,7 @@ async function fetchRawChangelog(db, outDir, target, since, signal) {
     try {
       const safeVersion = sanitizeFilename(item.version);
       assertSafeFilename(safeVersion, `raw-changelog version for ${JSON.stringify(item.version)}`);
-      const path = join3(outDir, `${safeVersion}.md`);
+      const path = join2(outDir, `${safeVersion}.md`);
       if (existsSync(path)) {
         if (item.releasedAt && (!latest || item.releasedAt > latest)) latest = item.releasedAt;
         continue;
@@ -1368,7 +1044,7 @@ async function fetchHtmlScrape(db, outDir, target, since, signal) {
     try {
       const safeSlug = sanitizeFilename(item.slug);
       assertSafeFilename(safeSlug, `html-scrape slug for ${JSON.stringify(item.slug)}`);
-      const path = join3(outDir, `${safeSlug}.md`);
+      const path = join2(outDir, `${safeSlug}.md`);
       if (existsSync(path)) {
         if (!latest || item.pubDate > latest) latest = item.pubDate;
         continue;
@@ -1408,7 +1084,7 @@ async function fetchPlaywrightStrategy(db, outDir, target, since) {
     try {
       const safeSlug = sanitizeFilename(item.slug);
       assertSafeFilename(safeSlug, `playwright slug for ${JSON.stringify(item.slug)}`);
-      const path = join3(outDir, `${safeSlug}.md`);
+      const path = join2(outDir, `${safeSlug}.md`);
       if (existsSync(path)) {
         if (!latest || item.pubDate > latest) latest = item.pubDate;
         continue;
@@ -1487,46 +1163,6 @@ function seedMarkersFromDb(db) {
   return out;
 }
 
-// src/errors.ts
-var AppError = class extends Error {
-  code;
-  hint;
-  cause;
-  retryable;
-  constructor(opts) {
-    super(opts.message);
-    this.name = "AppError";
-    this.code = opts.code;
-    this.hint = opts.hint;
-    this.cause = opts.cause;
-    this.retryable = opts.retryable ?? false;
-  }
-  /** Return the structured JSON shape (useful for --json output and MCP results). */
-  toJSON() {
-    return {
-      code: this.code,
-      message: this.message,
-      hint: this.hint,
-      ...this.cause ? { cause: this.cause } : {},
-      ...this.retryable ? { retryable: this.retryable } : {}
-    };
-  }
-};
-function formatError(err, verbose = false) {
-  if (err instanceof AppError) {
-    const lines = [`\u2717 [${err.code}] ${err.message}`];
-    lines.push(`  hint: ${err.hint}`);
-    if (verbose && err.cause) {
-      lines.push(`  cause: ${err.cause}`);
-    }
-    return lines.join("\n");
-  }
-  if (err instanceof Error) {
-    return `\u2717 ${err.message}`;
-  }
-  return `\u2717 ${String(err)}`;
-}
-
 // src/cli.ts
 var LOG_LEVELS = { silent: 0, normal: 1, verbose: 2, debug: 3 };
 function resolveLogLevel() {
@@ -1555,8 +1191,8 @@ function shutdown(signal) {
 process.on("SIGINT", () => shutdown("SIGINT"));
 process.on("SIGTERM", () => shutdown("SIGTERM"));
 var cwd = process.cwd();
-var DEFAULT_DB = join4(cwd, "data", "claude-synergy.db");
-var DEFAULT_PRODUCTS = join4(cwd, "products");
+var DEFAULT_DB = join3(cwd, "data", "claude-synergy.db");
+var DEFAULT_PRODUCTS = join3(cwd, "products");
 var _require = createRequire(import.meta.url);
 var { version: PKG_VERSION } = _require("../package.json");
 function intOpt(name, raw, defaultValue, min = 1, max = 1e4) {
@@ -1573,6 +1209,71 @@ function openTrackedDb(path) {
   activeDb = db;
   return db;
 }
+function parseRelativeDate(input, now = /* @__PURE__ */ new Date()) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new AppError({
+      code: "INVALID_DATE",
+      message: "date is empty",
+      hint: "Pass a date like 7d, 2w, 1m, 1y, or YYYY-MM-DD"
+    });
+  }
+  const relMatch = /^(\d+)([dwmy])$/i.exec(trimmed);
+  if (relMatch) {
+    const n = parseInt(relMatch[1], 10);
+    const unit = relMatch[2].toLowerCase();
+    if (!Number.isFinite(n) || n < 0) {
+      throw new AppError({
+        code: "INVALID_DATE",
+        message: `invalid relative date: ${input}`,
+        hint: "Relative dates must be a non-negative integer (e.g. 7d, 2w, 1m, 1y)"
+      });
+    }
+    const d = new Date(now);
+    switch (unit) {
+      case "d":
+        d.setUTCDate(d.getUTCDate() - n);
+        break;
+      case "w":
+        d.setUTCDate(d.getUTCDate() - n * 7);
+        break;
+      case "m":
+        d.setUTCMonth(d.getUTCMonth() - n);
+        break;
+      case "y":
+        d.setUTCFullYear(d.getUTCFullYear() - n);
+        break;
+    }
+    return d.toISOString().slice(0, 10);
+  }
+  const parsed = new Date(trimmed);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new AppError({
+      code: "INVALID_DATE",
+      message: `invalid date: ${input}`,
+      hint: "Use YYYY-MM-DD, a full ISO timestamp, or a relative form like 7d/2w/1m/1y"
+    });
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) return trimmed;
+  return parsed.toISOString();
+}
+function resolveDateOrExit(name, raw) {
+  if (raw === void 0) return void 0;
+  try {
+    return parseRelativeDate(raw);
+  } catch (e) {
+    if (e instanceof AppError) {
+      if (program.opts().json) {
+        console.log(JSON.stringify(e.toJSON()));
+      } else {
+        console.error(formatError(e, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+      }
+    } else {
+      console.error(`error: --${name} ${e.message}`);
+    }
+    process.exit(1);
+  }
+}
 var CONTEXT_PROVIDERS = ["none", "structured", "ollama", "claude-haiku"];
 var EMBED_PROVIDERS = ["ollama", "voyage"];
 var RERANK_PROVIDERS = ["none", "ollama-judge", "voyage", "cohere"];
@@ -1665,7 +1366,7 @@ program.command("ingest").description("Parse products/*/releases/*.md and load i
   }
   db.close();
 });
-program.command("query <text>").description('Full-text search across all change bullets (FTS5). Quote multi-word: hk query "managed agents"').option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "YYYY-MM-DD lower bound").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").option("-l, --limit <n>", "max results", "20").action((text, opts) => {
+program.command("query <text>").description('Full-text search across all change bullets (FTS5). Quote multi-word: hk query "managed agents"').option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "lower bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-u, --until <date>", "upper bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").option("-l, --limit <n>", "max results", "20").action((text, opts) => {
   logDebug(`text=${JSON.stringify(text)} opts=${JSON.stringify(opts)}`);
   const db = openTrackedDb(opts.db);
   if (warnIfEmpty(db)) {
@@ -1673,11 +1374,14 @@ program.command("query <text>").description('Full-text search across all change
     return;
   }
   const q = text;
+  const since = resolveDateOrExit("since", opts.since);
+  const until = resolveDateOrExit("until", opts.until);
   let results;
   try {
     results = searchChanges(db, q, {
       product: opts.product,
-      since: opts.since,
+      since,
+      until,
       kind: opts.kind,
       limit: intOpt("limit", opts.limit, 20)
     });
@@ -1857,7 +1561,7 @@ program.command("sync").description("Run fetch \u2192 ingest \u2192 embed in seq
         }
       }
       process.stderr.write("\n=== ingest ===\n");
-      const { ingestAll: ingestAll2 } = await import("./ingest-3LJNQWS7.js");
+      const { ingestAll: ingestAll2 } = await import("./ingest-Z45YH7OX.js");
       const ingestStats = ingestAll2(db, opts.productsRoot);
       console.log(`ingested ${ingestStats.releasesAdded} releases, ${ingestStats.changesAdded} changes, ${ingestStats.entitiesAdded} entities`);
       if (!opts.skipEmbed) {
@@ -1945,18 +1649,21 @@ program.command("embed").description("Generate contextual chunks + embeddings (T
     }
   }
 );
-program.command("hybrid <text>").description("Hybrid FTS5 + sqlite-vec search via RRF, optional rerank (requires `hk embed` first)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "YYYY-MM-DD lower bound").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").addOption(
+program.command("hybrid <text>").description("Hybrid FTS5 + sqlite-vec search via RRF, optional rerank (requires `hk embed` first)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "lower bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-u, --until <date>", "upper bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").addOption(
   new Option("-e, --embed <provider>", "embedding provider for query").default("ollama").choices([...EMBED_PROVIDERS])
 ).addOption(
   new Option("-r, --rerank <provider>", "rerank provider").default("none").choices([...RERANK_PROVIDERS])
 ).option("-l, --limit <n>", "max results", "10").option("--top-k <n>", "per-channel pull before fusion", "60").option("--rerank-candidates <n>", "how many RRF candidates to rerank", "20").action(
   async (text, opts) => {
     const db = openTrackedDb(opts.db);
+    const since = resolveDateOrExit("since", opts.since);
+    const until = resolveDateOrExit("until", opts.until);
     try {
       const t0 = Date.now();
       const results = await hybridSearch(db, text, {
         product: opts.product,
-        since: opts.since,
+        since,
+        until,
         kind: opts.kind,
         embedProviderName: opts.embed,
         rerankProviderName: opts.rerank,
@@ -2008,13 +1715,14 @@ ${results.length} result${results.length === 1 ? "" : "s"} in ${ms}ms (rerank: $
     }
   }
 );
-program.command("latest").description("Recent releases across all products (or one)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-l, --limit <n>", "max results", "20").action((opts) => {
+program.command("latest").description("Recent releases across all products (or one)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "lower bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-l, --limit <n>", "max results", "20").action((opts) => {
   const db = openTrackedDb(opts.db);
   if (warnIfEmpty(db)) {
     db.close();
     return;
   }
-  const releases = recentReleases(db, opts.product, intOpt("limit", opts.limit, 20));
+  const since = resolveDateOrExit("since", opts.since);
+  const releases = recentReleases(db, opts.product, intOpt("limit", opts.limit, 20), since);
   if (program.opts().json) {
     console.log(JSON.stringify(releases));
   } else if (releases.length === 0) {
@@ -2047,6 +1755,117 @@ program.command("products").description("List all products in the DB with releas
   }
   db.close();
 });
+program.command("diff [product]").description("Show changes in a date window, grouped by release. Default: last 7 days across all products.").option("-d, --db <path>", "database path", DEFAULT_DB).option("-s, --since <date>", "lower bound (YYYY-MM-DD or relative like 7d, 2w, 1m)", "7d").option("-u, --until <date>", "upper bound (YYYY-MM-DD or relative); default: now").option("-k, --kind <kind>", "added|fixed|breaking|deprecated|renamed|removed|improved|changed").option("-l, --limit <n>", "max change rows", "200").action((product, opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const since = resolveDateOrExit("since", opts.since);
+  const until = resolveDateOrExit("until", opts.until);
+  if (!since) {
+    console.error("error: --since is required");
+    db.close();
+    process.exit(1);
+    return;
+  }
+  let results;
+  try {
+    results = getChangesSince(db, {
+      since,
+      until,
+      product,
+      kind: opts.kind,
+      limit: intOpt("limit", opts.limit, 200, 1, 1e4)
+    });
+  } catch (e) {
+    const appErr = new AppError({
+      code: "DIFF_FAILED",
+      message: `diff failed: ${e.message}`,
+      hint: "Verify --since / --until parse correctly and the DB is initialized.",
+      cause: e.message
+    });
+    if (program.opts().json) console.log(JSON.stringify(appErr.toJSON()));
+    else console.error(formatError(appErr, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+    db.close();
+    process.exit(1);
+    return;
+  }
+  if (program.opts().json) {
+    console.log(JSON.stringify(results));
+  } else if (results.length === 0) {
+    const scope = product ? ` for product "${product}"` : "";
+    console.log(`(no changes in window since ${since}${until ? ` until ${until}` : ""}${scope})`);
+    console.log("Try widening the date window: hk diff --since 30d, or remove --kind / --product filters.");
+  } else {
+    let totalChanges = 0;
+    for (const rel of results) {
+      const date = rel.released_at ?? "????-??-??";
+      console.log(`
+${date}  ${rel.product}@${rel.version}  (${rel.changes.length} change${rel.changes.length === 1 ? "" : "s"})`);
+      for (const c of rel.changes) {
+        console.log(`  - [${c.kind}] ${c.text}`);
+      }
+      totalChanges += rel.changes.length;
+    }
+    const sinceLbl = opts.since;
+    const untilLbl = opts.until ? ` until ${opts.until}` : "";
+    console.log(`
+${totalChanges} change${totalChanges === 1 ? "" : "s"} across ${results.length} release${results.length === 1 ? "" : "s"} since ${sinceLbl}${untilLbl}`);
+  }
+  db.close();
+});
+program.command("breaking").description("List breaking changes, most recent first. Filter by product / date window.").option("-d, --db <path>", "database path", DEFAULT_DB).option("-p, --product <name>", "limit to one product").option("-s, --since <date>", "lower bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-u, --until <date>", "upper bound (YYYY-MM-DD or relative like 7d, 2w, 1m)").option("-l, --limit <n>", "max results", "50").action((opts) => {
+  const db = openTrackedDb(opts.db);
+  if (warnIfEmpty(db)) {
+    db.close();
+    return;
+  }
+  const since = resolveDateOrExit("since", opts.since);
+  const until = resolveDateOrExit("until", opts.until);
+  let results;
+  try {
+    results = browseChanges(db, {
+      product: opts.product,
+      since,
+      until,
+      kind: "breaking",
+      limit: intOpt("limit", opts.limit, 50, 1, 1e4)
+    });
+  } catch (e) {
+    const appErr = new AppError({
+      code: "BREAKING_FAILED",
+      message: `breaking query failed: ${e.message}`,
+      hint: "Verify --since / --until parse correctly and the DB is initialized.",
+      cause: e.message
+    });
+    if (program.opts().json) console.log(JSON.stringify(appErr.toJSON()));
+    else console.error(formatError(appErr, LOG_LEVELS[logLevel] >= LOG_LEVELS.verbose));
+    db.close();
+    process.exit(1);
+    return;
+  }
+  if (program.opts().json) {
+    console.log(JSON.stringify(results.map((r) => ({
+      released_at: r.released_at,
+      product: r.product,
+      version: r.version,
+      kind: r.kind,
+      text: r.text
+    }))));
+  } else if (results.length === 0) {
+    console.log("(no breaking changes)");
+    console.log('Note: ingest may not have classified any changes as breaking yet \u2014 try `hk query "" --kind breaking` patterns, or widen --since.');
+  } else {
+    for (const r of results) {
+      console.log(`${r.released_at ?? "????-??-??"}  ${r.product}@${r.version}  [${r.kind}]`);
+      console.log(`  ${r.text}`);
+    }
+    console.log(`
+${results.length} breaking change${results.length === 1 ? "" : "s"}`);
+  }
+  db.close();
+});
 program.command("top <entity-type>").description("Most-mentioned entities of a type (env_var, slash_command, cli_option, model_id, beta_header, cve, ghsa, hook_event, setting_key)").option("-d, --db <path>", "database path", DEFAULT_DB).option("-l, --limit <n>", "max results", "30").action((entityType, opts) => {
   const db = openTrackedDb(opts.db);
   if (warnIfEmpty(db)) {
@@ -2088,3 +1907,6 @@ program.parseAsync(process.argv).catch((e) => {
   }
   process.exitCode = 2;
 });
+export {
+  parseRelativeDate
+};