@ainyc/canonry 4.35.0 → 4.39.0

package/dist/{chunk-MLS5KJWK.js → chunk-DOUV45KI.js}

@@ -8,7 +8,7 @@ import {
   categoryLabel,
   determineAnswerMentioned,
   normalizeProjectDomain
-} from "./chunk-EM5GVF3C.js";
+} from "./chunk-XJVYVURK.js";
 
 // src/intelligence-service.ts
 import { eq, desc, asc, and, or, inArray } from "drizzle-orm";
@@ -3256,24 +3256,51 @@ function buildAiSourceOrigin(snapshots, projectDomains, competitorDomains, topDo
 }
 
 // ../intelligence/src/movement-summary.ts
-function buildMovementSummary(currentSnapshots, previousSnapshots) {
+function buildMovementSummary(currentSnapshots, previousSnapshots, options = {}) {
   if (previousSnapshots.length === 0) {
-    const citedCount = collectCitedQueryIds(currentSnapshots).size;
+    const citedIds = collectCitedQueryIds(currentSnapshots);
+    const citedCount = citedIds.size;
     const tone2 = citedCount > 0 ? "positive" : "neutral";
-    return { gained: citedCount, lost: 0, tone: tone2, hasPreviousRun: false };
+    return withQueryLists(
+      { gained: citedCount, lost: 0, tone: tone2, hasPreviousRun: false },
+      citedIds,
+      /* @__PURE__ */ new Set(),
+      options.queryLookup
+    );
   }
   const latestCited = collectCitedQueryIds(currentSnapshots);
   const previousCited = collectCitedQueryIds(previousSnapshots);
-  let gained = 0;
-  let lost = 0;
+  const gainedIds = /* @__PURE__ */ new Set();
+  const lostIds = /* @__PURE__ */ new Set();
   for (const id of latestCited) {
-    if (!previousCited.has(id)) gained++;
+    if (!previousCited.has(id)) gainedIds.add(id);
   }
   for (const id of previousCited) {
-    if (!latestCited.has(id)) lost++;
+    if (!latestCited.has(id)) lostIds.add(id);
+  }
+  const tone = lostIds.size > gainedIds.size ? "negative" : gainedIds.size > lostIds.size ? "positive" : "neutral";
+  return withQueryLists(
+    { gained: gainedIds.size, lost: lostIds.size, tone, hasPreviousRun: true },
+    gainedIds,
+    lostIds,
+    options.queryLookup
+  );
+}
+function withQueryLists(base, gainedIds, lostIds, lookup) {
+  if (!lookup) return base;
+  return {
+    ...base,
+    gainedQueries: resolveQueryTexts(gainedIds, lookup),
+    lostQueries: resolveQueryTexts(lostIds, lookup)
+  };
+}
+function resolveQueryTexts(ids, lookup) {
+  const out = [];
+  for (const id of ids) {
+    const text2 = lookup.get(id);
+    if (text2) out.push(text2);
   }
-  const tone = lost > gained ? "negative" : gained > lost ? "positive" : "neutral";
-  return { gained, lost, tone, hasPreviousRun: true };
+  return out.sort();
 }
 function collectCitedQueryIds(snapshots) {
   const cited = /* @__PURE__ */ new Set();
@@ -3303,14 +3330,14 @@ function gapTone(gapCount, totalCount) {
 
 // ../intelligence/src/visibility-score.ts
 function buildVisibilityScore(snapshots, options) {
-  const tooltip = 'Percentage of tracked queries where your domain is cited by at least one AI answer engine. A query is "visible" if any configured provider includes your site in its response.';
+  const tooltip = "An LLM used a page on your domain as a source for its answer.";
   if (snapshots.length === 0) {
     return {
-      label: "Answer Visibility",
+      label: "Citation Coverage",
       value: "No data",
       delta: "Run a sweep first",
       tone: "neutral",
-      description: "No visibility data yet. Trigger a run to start tracking.",
+      description: "No citation data yet. Trigger a run to start tracking.",
       tooltip,
       trend: []
     };
@@ -3327,9 +3354,9 @@ function buildVisibilityScore(snapshots, options) {
   const runApiProviderCount = options.configuredApiProviders.filter((p) => runProviders.has(p)).length;
   const isPartialProviderRun = options.configuredApiProviders.length > 1 && runApiProviderCount < options.configuredApiProviders.length;
   return {
-    label: "Answer Visibility",
+    label: "Citation Coverage",
     value: `${score}`,
-    delta: `${citedCount} of ${totalCount} queries visible`,
+    delta: `${citedCount} of ${totalCount} queries cited`,
     tone: isPartialProviderRun ? "caution" : scoreTone(score),
     description: `${citedCount} of ${totalCount} tracked queries found your domain in at least one AI answer engine.`,
     tooltip,
@@ -3339,6 +3366,44 @@ function buildVisibilityScore(snapshots, options) {
   };
 }
 
+// ../intelligence/src/mention-coverage.ts
+function buildMentionCoverage(snapshots, options) {
+  const tooltip = "Your domain or company name was in the answer returned by the LLM.";
+  if (snapshots.length === 0) {
+    return {
+      label: "Mention Coverage",
+      value: "No data",
+      delta: "Run a sweep first",
+      tone: "neutral",
+      description: "No mention data yet. Trigger a run to start tracking.",
+      tooltip,
+      trend: []
+    };
+  }
+  const queryMentioned = /* @__PURE__ */ new Map();
+  for (const snap of snapshots) {
+    if (!queryMentioned.has(snap.queryId)) queryMentioned.set(snap.queryId, false);
+    if (snap.answerMentioned === true) queryMentioned.set(snap.queryId, true);
+  }
+  const totalCount = queryMentioned.size;
+  const mentionedCount = [...queryMentioned.values()].filter(Boolean).length;
+  const score = totalCount > 0 ? Math.round(mentionedCount / totalCount * 100) : 0;
+  const runProviders = new Set(snapshots.map((s) => s.provider));
+  const runApiProviderCount = options.configuredApiProviders.filter((p) => runProviders.has(p)).length;
+  const isPartialProviderRun = options.configuredApiProviders.length > 1 && runApiProviderCount < options.configuredApiProviders.length;
+  return {
+    label: "Mention Coverage",
+    value: `${score}`,
+    delta: `${mentionedCount} of ${totalCount} queries mentioned`,
+    tone: isPartialProviderRun ? "caution" : scoreTone(score),
+    description: `${mentionedCount} of ${totalCount} tracked queries had your brand or domain in the AI answer text.`,
+    tooltip,
+    trend: [],
+    progress: score,
+    providerCoverage: isPartialProviderRun ? `${runApiProviderCount} of ${options.configuredApiProviders.length} providers` : void 0
+  };
+}
+
 // ../intelligence/src/gap-query-score.ts
 function buildGapQueryScore(snapshots) {
   const tooltip = "Tracked queries where a competitor is cited in the latest run but your domain is not.";
@@ -3367,11 +3432,48 @@ function buildGapQueryScore(snapshots) {
   ).length;
   const gapQueryLabel = gapCount === 1 ? "query" : "queries";
   return {
-    label: "Gap Queries",
+    label: "Citation Gaps",
     value: `${gapCount}`,
     delta: `${gapCount} of ${totalCount} queries at risk`,
     tone: gapTone(gapCount, totalCount),
-    description: gapCount > 0 ? `${gapCount} tracked ${gapQueryLabel} currently cite competitors without citing your domain.` : "No competitive query gaps detected in the latest visibility run.",
+    description: gapCount > 0 ? `${gapCount} tracked ${gapQueryLabel} currently cite competitors without citing your domain.` : "No competitive citation gaps detected in the latest visibility run.",
+    tooltip,
+    trend: [],
+    progress: totalCount > 0 ? Math.round(gapCount / totalCount * 100) : 0
+  };
+}
+function buildMentionGapScore(snapshots) {
+  const tooltip = "Tracked queries where a competitor surfaces in the latest run but your brand / domain is not mentioned in the answer text.";
+  if (snapshots.length === 0) {
+    return {
+      label: "Mention Gaps",
+      value: "No data",
+      delta: "Run a sweep first",
+      tone: "neutral",
+      description: "Run a visibility sweep to identify queries where competitors are mentioned and your brand is not.",
+      tooltip,
+      trend: []
+    };
+  }
+  const byQuery = /* @__PURE__ */ new Map();
+  for (const snap of snapshots) {
+    const key = snap.queryId;
+    const current = byQuery.get(key) ?? { mentioned: false, competitorOverlap: /* @__PURE__ */ new Set() };
+    if (snap.answerMentioned === true) current.mentioned = true;
+    for (const domain of snap.competitorOverlap) current.competitorOverlap.add(domain);
+    byQuery.set(key, current);
+  }
+  const totalCount = byQuery.size;
+  const gapCount = [...byQuery.values()].filter(
+    (entry) => !entry.mentioned && entry.competitorOverlap.size > 0
+  ).length;
+  const gapQueryLabel = gapCount === 1 ? "query" : "queries";
+  return {
+    label: "Mention Gaps",
+    value: `${gapCount}`,
+    delta: `${gapCount} of ${totalCount} queries at risk`,
+    tone: gapTone(gapCount, totalCount),
+    description: gapCount > 0 ? `${gapCount} tracked ${gapQueryLabel} mention competitors but never your brand.` : "No competitive mention gaps detected in the latest visibility run.",
     tooltip,
     trend: [],
     progress: totalCount > 0 ? Math.round(gapCount / totalCount * 100) : 0
@@ -3487,6 +3589,92 @@ function buildRunHistory(runs2, snapshotsByRunId, limit = DEFAULT_RUN_HISTORY_LI
   });
 }
 
+// ../intelligence/src/share-of-voice.ts
+function sovTone(score) {
+  if (score >= 30) return "positive";
+  if (score >= 10) return "caution";
+  return "negative";
+}
+function buildShareOfVoice(snapshots, options) {
+  const tooltip = "Your domain's share of every distinct cited-source slot across the latest run. Subdomain-aware (cited docs.you.com counts for you.com). Distinct from Citation Coverage \u2014 SoV measures how much of the answer real-estate you own, not just whether you appear.";
+  if (snapshots.length === 0) {
+    return {
+      label: "Share of Voice",
+      value: "No data",
+      delta: "Run a sweep first",
+      tone: "neutral",
+      description: "No SoV data yet. Trigger a run to start tracking.",
+      tooltip,
+      trend: []
+    };
+  }
+  const breakdown = computeShareOfVoiceBreakdown(snapshots, options);
+  if (breakdown.totalSlots === 0) {
+    return {
+      label: "Share of Voice",
+      value: "0",
+      delta: "No citations in this run",
+      tone: "neutral",
+      description: "The latest run produced no source-list citations across any provider, so SoV cannot be measured. (Mention Coverage may still be non-zero \u2014 answers can mention you without grounding to a URL.)",
+      tooltip,
+      trend: [],
+      progress: 0
+    };
+  }
+  const { projectSlots, competitorSlots, otherSlots, totalSlots } = breakdown;
+  const score = Math.round(projectSlots / totalSlots * 100);
+  const competitorShare = Math.round(competitorSlots / totalSlots * 100);
+  const otherShare = Math.max(0, 100 - score - competitorShare);
+  const hasCompetitorsConfigured = options.competitorDomains.length > 0;
+  const description = describeBreakdown({
+    projectSlots,
+    competitorSlots,
+    otherSlots,
+    totalSlots,
+    score,
+    competitorShare,
+    otherShare,
+    hasCompetitorsConfigured
+  });
+  return {
+    label: "Share of Voice",
+    value: `${score}`,
+    delta: `${projectSlots} of ${totalSlots} cited slots`,
+    tone: sovTone(score),
+    description,
+    tooltip,
+    trend: [],
+    progress: score
+  };
+}
+function computeShareOfVoiceBreakdown(snapshots, options) {
+  let totalSlots = 0;
+  let projectSlots = 0;
+  let competitorSlots = 0;
+  for (const snap of snapshots) {
+    for (const domain of snap.citedDomains) {
+      totalSlots++;
+      if (citedDomainBelongsToProject(domain, options.projectDomains)) {
+        projectSlots++;
+      } else if (citedDomainBelongsToProject(domain, options.competitorDomains)) {
+        competitorSlots++;
+      }
+    }
+  }
+  const otherSlots = totalSlots - projectSlots - competitorSlots;
+  return { projectSlots, competitorSlots, otherSlots, totalSlots };
+}
+function describeBreakdown(parts) {
+  const { projectSlots, competitorSlots, totalSlots, score, competitorShare, otherShare, hasCompetitorsConfigured } = parts;
+  if (!hasCompetitorsConfigured) {
+    return `${projectSlots} of ${totalSlots} cited slots were yours (${score}%). Add tracked competitors to break out the rest.`;
+  }
+  if (competitorSlots === 0) {
+    return `${projectSlots} of ${totalSlots} cited slots were yours (${score}%); no tracked competitors surfaced in the run. The remaining ${otherShare}% goes to unrelated sources.`;
+  }
+  return `You own ${score}% of cited slots; tracked competitors hold ${competitorShare}%; the remaining ${otherShare}% goes to non-competitive sources.`;
+}
+
 // src/intelligence-service.ts
 import crypto from "crypto";
 
@@ -3611,8 +3799,13 @@ var IntelligenceService = class {
   /**
    * Analyze a single run given an explicit previous run (or null for first run).
    * Used by backfill where we control the run ordering.
+   *
+   * `dryRun: true` skips the DB write — `persistResult` is not called and
+   * dismissed flags / health rows are untouched. Callers receive the same
+   * AnalysisResult they would have, suitable for previewing what a write
+   * would have produced.
    */
-  analyzeRunWithPrevious(runRecord, previousRunRecord, historyRecords) {
+  analyzeRunWithPrevious(runRecord, previousRunRecord, historyRecords, opts) {
     const currentRun = this.buildRunData(
       runRecord.id,
       runRecord.projectId,
@@ -3632,23 +3825,44 @@ var IntelligenceService = class {
     const history = (historyRecords ?? []).map((r) => r.id === runRecord.id ? currentRun : this.buildRunData(r.id, r.projectId, r.finishedAt ?? r.createdAt, r.location ?? null));
     if (!previousRun) {
       const result2 = analyzeRuns(currentRun, currentRun, { trackedCompetitors, history });
-      this.persistResult(this.emptyAnalysisResult(result2), runRecord.id, runRecord.projectId);
+      const emptyResult = this.emptyAnalysisResult(result2);
+      if (!opts?.dryRun) this.persistResult(emptyResult, runRecord.id, runRecord.projectId);
       return result2;
     }
     const result = analyzeRuns(currentRun, previousRun, { trackedCompetitors, history });
     const tieredResult = this.tierResult(result, runRecord.id, runRecord.projectId);
-    this.persistResult(tieredResult, runRecord.id, runRecord.projectId);
+    if (!opts?.dryRun) this.persistResult(tieredResult, runRecord.id, runRecord.projectId);
     return tieredResult;
   }
   /**
    * Backfill intelligence for all completed/partial runs of a project.
    * Processes runs in chronological order so each run compares against its predecessor.
+   *
+   * Scoping options:
+   *   - `fromRunId` / `toRunId`: bound the target range by exact run ID.
+   *   - `since`: bound the target range by `finishedAt >= <date>`. Accepts
+   *     any string that `Date.parse` understands (ISO 8601, `YYYY-MM-DD`,
+   *     etc.). Runs before the cutoff are *not* re-processed but stay
+   *     available for predecessor lookup, so transition detection at the
+   *     boundary stays correct. Composes with `fromRunId` / `toRunId` —
+   *     all three filters intersect.
+   *   - `dryRun`: compute the analysis without writing. The return value
+   *     includes a `delta` describing what would change (rows to delete vs
+   *     create per run + aggregate). DB is left untouched.
    */
   backfill(projectName, opts, onProgress) {
     const project = this.db.select().from(projects).where(eq(projects.name, projectName)).get();
     if (!project) {
       throw new Error(`Project "${projectName}" not found`);
     }
+    let sinceTimestamp = null;
+    if (opts?.since !== void 0) {
+      const parsed = Date.parse(opts.since);
+      if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid --since value "${opts.since}": expected a parseable date (ISO 8601 or YYYY-MM-DD)`);
+      }
+      sinceTimestamp = parsed;
+    }
     const allRuns = this.db.select().from(runs).where(
       and(
         eq(runs.projectId, project.id),
@@ -3667,10 +3881,28 @@ var IntelligenceService = class {
       if (idx === -1) throw new Error(`Run "${opts.toRunId}" not found in project`);
       endIdx = idx + 1;
     }
-    const targetRuns = allRuns.slice(startIdx, endIdx);
+    let targetRuns = allRuns.slice(startIdx, endIdx);
+    if (sinceTimestamp !== null) {
+      targetRuns = targetRuns.filter((r) => {
+        const ts = r.finishedAt ?? r.createdAt;
+        const t = Date.parse(ts);
+        return !Number.isNaN(t) && t >= sinceTimestamp;
+      });
+    }
     let processed = 0;
     let skipped = 0;
     let totalInsights = 0;
+    const isDryRun = opts?.dryRun === true;
+    const perRunDelta = [];
+    let wouldDeleteTotal = 0;
+    const existingByRunId = /* @__PURE__ */ new Map();
+    if (isDryRun && targetRuns.length > 0) {
+      const rows = this.db.select({ runId: insights.runId }).from(insights).where(inArray(insights.runId, targetRuns.map((r) => r.id))).all();
+      for (const r of rows) {
+        if (r.runId == null) continue;
+        existingByRunId.set(r.runId, (existingByRunId.get(r.runId) ?? 0) + 1);
+      }
+    }
     for (let i = 0; i < targetRuns.length; i++) {
       const run = targetRuns[i];
       const runLocation = run.location ?? null;
@@ -3679,16 +3911,35 @@ var IntelligenceService = class {
       const previousRun = sameLocIdx > 0 ? sameLocationRuns[sameLocIdx - 1] : null;
       const historyStart = Math.max(0, sameLocIdx - (HISTORY_WINDOW_RUNS - 1));
       const historyRecords = sameLocationRuns.slice(historyStart, sameLocIdx + 1);
-      const result = this.analyzeRunWithPrevious(run, previousRun, historyRecords);
+      const result = this.analyzeRunWithPrevious(run, previousRun, historyRecords, { dryRun: isDryRun });
       if (result) {
         processed++;
         totalInsights += result.insights.length;
+        if (isDryRun) {
+          const existing = existingByRunId.get(run.id) ?? 0;
+          wouldDeleteTotal += existing;
+          perRunDelta.push({ runId: run.id, existingInsights: existing, newInsights: result.insights.length });
+        }
         onProgress?.({ runId: run.id, index: i + 1, total: targetRuns.length, insights: result.insights.length });
       } else {
         skipped++;
         onProgress?.({ runId: run.id, index: i + 1, total: targetRuns.length, insights: 0 });
       }
     }
+    if (isDryRun) {
+      return {
+        processed,
+        skipped,
+        totalInsights,
+        dryRun: true,
+        delta: {
+          wouldDelete: wouldDeleteTotal,
+          wouldCreate: totalInsights,
+          netChange: totalInsights - wouldDeleteTotal,
+          perRun: perRunDelta
+        }
+      };
+    }
     return { processed, skipped, totalInsights };
   }
   loadTrackedCompetitors(projectId) {
@@ -3838,17 +4089,28 @@ var IntelligenceService = class {
   buildRunData(runId, projectId, completedAt, location = null) {
     const rows = this.db.select({
       query: queries.query,
+      // Denormalized query text persisted by v58 — the fallback when the
+      // joined queries.query has been hard-deleted (or the query_id was
+      // nulled by the v58 dangling-FK cleanup).
+      queryText: querySnapshots.queryText,
       provider: querySnapshots.provider,
       citationState: querySnapshots.citationState,
       citedDomains: querySnapshots.citedDomains,
       competitorOverlap: querySnapshots.competitorOverlap,
       snapshotLocation: querySnapshots.location
     }).from(querySnapshots).leftJoin(queries, eq(querySnapshots.queryId, queries.id)).where(eq(querySnapshots.runId, runId)).all();
-    const snapshots = rows.map((r) => {
+    const snapshots = [];
+    let orphanCount = 0;
+    for (const r of rows) {
+      const resolvedQuery = r.query ?? r.queryText ?? null;
+      if (!resolvedQuery) {
+        orphanCount++;
+        continue;
+      }
       const domains = parseJsonColumn(r.citedDomains, []);
       const competitors2 = parseJsonColumn(r.competitorOverlap, []);
-      return {
-        query: r.query ?? "",
+      snapshots.push({
+        query: resolvedQuery,
         provider: r.provider,
         cited: r.citationState === CitationStates.cited,
         citationUrl: domains[0] ?? void 0,
@@ -3863,8 +4125,11 @@ var IntelligenceService = class {
         // sources). Cause analysis uses it to name the displacing source
         // when no tracked competitor appears in the response.
         citedDomains: domains
-      };
-    });
+      });
+    }
+    if (orphanCount > 0) {
+      log.warn("snapshot.orphan-skip", { runId, projectId, orphanCount });
+    }
     return { runId, projectId, completedAt, location, snapshots };
   }
 };
@@ -3928,12 +4193,15 @@ export {
   buildAiSourceOrigin,
   buildMovementSummary,
   buildVisibilityScore,
+  buildMentionCoverage,
   buildGapQueryScore,
+  buildMentionGapScore,
   buildCompetitorPressureScore,
   buildOverviewCompetitors,
   buildProviderScores,
   DEFAULT_RUN_HISTORY_LIMIT,
   buildRunHistory,
+  buildShareOfVoice,
   createLogger,
   IntelligenceService
 };

package/dist/{chunk-B3FBOECD.js → chunk-JS6KRBBZ.js}

@@ -22,7 +22,7 @@ import {
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema
-} from "./chunk-EM5GVF3C.js";
+} from "./chunk-XJVYVURK.js";
 
 // src/config.ts
 import fs from "fs";
@@ -466,9 +466,19 @@ var ApiClient = class {
   async deleteProject(name) {
     await this.request("DELETE", `/projects/${encodeURIComponent(name)}`);
   }
+  async previewProjectDelete(name) {
+    return this.request("GET", `/projects/${encodeURIComponent(name)}/delete-preview`);
+  }
   async putQueries(project, queries) {
     await this.request("PUT", `/projects/${encodeURIComponent(project)}/queries`, { queries });
   }
+  async previewReplaceQueries(project, queries) {
+    return this.request(
+      "POST",
+      `/projects/${encodeURIComponent(project)}/queries/replace-preview`,
+      { queries }
+    );
+  }
   async listQueries(project) {
     return this.request("GET", `/projects/${encodeURIComponent(project)}/queries`);
   }
@@ -1333,6 +1343,17 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}"],
     handler: (client, input) => client.getProject(input.project)
   }),
+  defineTool({
+    name: "canonry_project_delete_preview",
+    title: "Preview project delete impact",
+    description: "Returns the cascade impact of deleting a project \u2014 how many queries, competitors, runs, snapshots, and insights would be removed, plus how many audit_log rows would be detached (project_id set NULL). Read-only. Use this BEFORE invoking project delete on any project you didn't create yourself; the underlying delete is irreversible.",
+    access: "read",
+    tier: "setup",
+    inputSchema: projectInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/delete-preview"],
+    handler: (client, input) => client.previewProjectDelete(input.project)
+  }),
   defineTool({
     name: "canonry_project_overview",
     title: "Get project overview (composite)",
@@ -1981,6 +2002,17 @@ var canonryMcpTools = [
       await client.putQueries(input.project, uniqueStrings(input.request.queries));
     }
   }),
+  defineTool({
+    name: "canonry_queries_replace_preview",
+    title: "Preview query replace",
+    description: "Preview the impact of replacing a project's tracked query set: current vs proposed, added/removed/unchanged diff, and the count of snapshots that would detach (queryId \u2192 NULL; queryText preserved). Read-only.",
+    access: "read",
+    tier: "setup",
+    inputSchema: queriesInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["POST /api/v1/projects/{name}/queries/replace-preview"],
+    handler: (client, input) => client.previewReplaceQueries(input.project, uniqueStrings(input.request.queries))
+  }),
   defineTool({
     name: "canonry_keywords_replace",
     title: "Replace keywords (legacy alias)",