@ainyc/canonry 2.10.1 → 2.12.0

package/dist/cli.js

@@ -17,7 +17,7 @@ import {
   setGoogleAuthConfig,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-SZSWQG3J.js";
+} from "./chunk-FCYNFM4B.js";
 import {
   CcReleaseSyncStatuses,
   CliError,
@@ -41,7 +41,7 @@ import {
   saveConfig,
   saveConfigPatch,
   usageError
-} from "./chunk-KWQCQMPY.js";
+} from "./chunk-PLI7EOPM.js";
 import {
   apiKeys,
   competitors,
@@ -51,7 +51,7 @@ import {
   projects,
   querySnapshots,
   runs
-} from "./chunk-PYHANJ3B.js";
+} from "./chunk-UM6RDSRJ.js";
 import "./chunk-MLKGABMK.js";
 
 // src/cli.ts
@@ -299,7 +299,7 @@ async function backfillAnswerVisibilityCommand(opts) {
   console.log(`  Errors:   ${providerErrors}`);
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService } = await import("./intelligence-service-2ZABHNR4.js");
+  const { IntelligenceService } = await import("./intelligence-service-54F3NGPM.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);
@@ -1847,7 +1847,7 @@ async function gaSocialReferralSummary(project, opts) {
     console.log(`  Sessions: ${traffic.socialSessions} (${traffic.socialSharePct}% of ${traffic.totalSessions} total)`);
     console.log(`  Users:    ${traffic.socialUsers}`);
     console.log();
-    const fmtTrend = (pct) => pct === null ? "n/a" : `${pct >= 0 ? "+" : ""}${pct}%`;
+    const fmtTrend = (pct2) => pct2 === null ? "n/a" : `${pct2 >= 0 ? "+" : ""}${pct2}%`;
     console.log(`  7d trend:  ${fmtTrend(trend.trend7dPct)} (${trend.socialSessions7d} vs ${trend.socialSessionsPrev7d})`);
     console.log(`  30d trend: ${fmtTrend(trend.trend30dPct)} (${trend.socialSessions30d} vs ${trend.socialSessionsPrev30d})`);
     if (trend.biggestMover) {
@@ -1890,7 +1890,7 @@ async function gaSocialReferralSummary(project, opts) {
 async function gaAttribution(project, opts) {
   const client = getClient4();
   const traffic = await client.gaTraffic(project);
-  const fmtTrend = (pct) => pct === null ? "n/a" : `${pct >= 0 ? "+" : ""}${pct}%`;
+  const fmtTrend = (pct2) => pct2 === null ? "n/a" : `${pct2 >= 0 ? "+" : ""}${pct2}%`;
   if (opts?.trend) {
     const trend = await client.gaAttributionTrend(project);
     if (opts.format === "json") {
@@ -4047,14 +4047,14 @@ function printMetrics(data) {
   console.log(`
 Citation Rate Trends (${data.window})`);
   console.log("\u2500".repeat(50));
-  const pct = (n) => `${(n * 100).toFixed(1)}%`;
-  console.log(`  Overall: ${pct(data.overall.citationRate)} (${data.overall.cited}/${data.overall.total})`);
+  const pct2 = (n) => `${(n * 100).toFixed(1)}%`;
+  console.log(`  Overall: ${pct2(data.overall.citationRate)} (${data.overall.cited}/${data.overall.total})`);
   console.log(`  Trend:   ${data.trend}`);
   if (Object.keys(data.byProvider).length > 0) {
     console.log(`
   By Provider:`);
     for (const [provider, metric] of Object.entries(data.byProvider)) {
-      console.log(`    ${provider.padEnd(10)} ${pct(metric.citationRate).padStart(6)} (${metric.cited}/${metric.total})`);
+      console.log(`    ${provider.padEnd(10)} ${pct2(metric.citationRate).padStart(6)} (${metric.cited}/${metric.total})`);
     }
   }
   if (data.buckets.length > 0) {
@@ -4063,7 +4063,7 @@ Citation Rate Trends (${data.window})`);
     for (const bucket of data.buckets) {
       const start = bucket.startDate.slice(0, 10);
       const bar = bucket.total > 0 ? "\u2588".repeat(Math.round(bucket.citationRate * 20)) : "";
-      console.log(`    ${start}  ${pct(bucket.citationRate).padStart(6)}  ${bar}`);
+      console.log(`    ${start}  ${pct2(bucket.citationRate).padStart(6)}  ${bar}`);
     }
   }
 }
@@ -4100,9 +4100,9 @@ Source Origin Breakdown`);
     return;
   }
   for (const cat of data.overall) {
-    const pct = `${(cat.percentage * 100).toFixed(1)}%`;
+    const pct2 = `${(cat.percentage * 100).toFixed(1)}%`;
     const domains = cat.topDomains.slice(0, 3).map((d) => d.domain).join(", ");
-    console.log(`  ${cat.label.padEnd(20)} ${pct.padStart(6)}  (${cat.count})  ${domains}`);
+    console.log(`  ${cat.label.padEnd(20)} ${pct2.padStart(6)}  (${cat.count})  ${domains}`);
   }
 }
 
@@ -6026,6 +6026,84 @@ async function showHealth(project, opts) {
   }
 }
 
+// src/commands/overview.ts
+async function showOverview(project, opts) {
+  const client = createApiClient();
+  const overview = await client.getProjectOverview(project);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(overview, null, 2));
+    return;
+  }
+  const { project: meta, latestRun, health, topInsights, keywordCounts, providers, transitions } = overview;
+  console.log(`Overview: ${meta.displayName ?? meta.name} (${meta.name})
+`);
+  console.log(`  Domain:   ${meta.canonicalDomain}`);
+  console.log(`  Country:  ${meta.country}`);
+  console.log(`  Language: ${meta.language}`);
+  if (latestRun.run) {
+    const finished = latestRun.run.finishedAt ?? "\u2014";
+    console.log(`
+  Latest run: ${latestRun.run.id} (${latestRun.run.status}, ${finished})`);
+    console.log(`  Total runs: ${latestRun.totalRuns}`);
+  } else {
+    console.log("\n  No runs yet.");
+  }
+  console.log(`
+  Keywords cited: ${keywordCounts.citedKeywords}/${keywordCounts.totalKeywords} (${pct(keywordCounts.citedRate)})`);
+  if (providers.length > 0) {
+    console.log("  Providers:");
+    for (const p of providers) {
+      console.log(`    ${p.provider.padEnd(10)} ${p.cited}/${p.total} (${pct(p.citedRate)})`);
+    }
+  }
+  if (transitions.since) {
+    console.log(`
+  vs run at ${transitions.since}: +${transitions.gained} gained, -${transitions.lost} lost, ${transitions.emerging} emerging`);
+  }
+  if (health) {
+    console.log(`
+  Health: ${pct(health.overallCitedRate)} cited (${health.citedPairs}/${health.totalPairs} pairs)`);
+  }
+  if (topInsights.length > 0) {
+    console.log("\n  Top insights:");
+    for (const insight of topInsights) {
+      console.log(`    [${insight.severity.toUpperCase()}] ${insight.type} \u2014 ${insight.title}`);
+    }
+  }
+}
+function pct(value) {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+// src/commands/search.ts
+async function searchProject(project, opts) {
+  const client = createApiClient();
+  const result = await client.searchProject(project, { q: opts.query, limit: opts.limit });
+  if (opts.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Search: "${result.query}" \u2014 ${result.totalHits} hit${result.totalHits === 1 ? "" : "s"}${result.truncated ? " (truncated)" : ""}
+`);
+  if (result.hits.length === 0) {
+    console.log("  No matches.");
+    return;
+  }
+  for (const hit of result.hits) {
+    if (hit.kind === "snapshot") {
+      console.log(`  [snapshot] ${hit.keyword} (${hit.provider}, ${hit.citationState}) \u2014 ${hit.matchedField}`);
+      console.log(`    ${hit.snippet}`);
+      console.log(`    run=${hit.runId}  at ${hit.createdAt}`);
+    } else {
+      const dismissed = hit.dismissed ? " [dismissed]" : "";
+      console.log(`  [insight ${hit.severity.toUpperCase()}] ${hit.type} \u2014 ${hit.title}${dismissed}`);
+      console.log(`    ${hit.snippet}`);
+      console.log(`    keyword=${hit.keyword}  at ${hit.createdAt}`);
+    }
+    console.log("");
+  }
+}
+
 // src/cli-commands/intelligence.ts
 var INTELLIGENCE_CLI_COMMANDS = [
   {
@@ -6072,6 +6150,165 @@ var INTELLIGENCE_CLI_COMMANDS = [
       });
       await showHealth(project, { history, limit, format: input.format });
     }
+  },
+  {
+    path: ["overview"],
+    usage: "canonry overview <project> [--format json]",
+    options: {},
+    run: async (input) => {
+      const usage = "canonry overview <project> [--format json]";
+      const project = requireProject(input, "overview", usage);
+      await showOverview(project, { format: input.format });
+    }
+  },
+  {
+    path: ["search"],
+    usage: "canonry search <project> <query> [--limit <n>] [--format json]",
+    options: {
+      limit: { type: "string" }
+    },
+    run: async (input) => {
+      const usage = "canonry search <project> <query> [--limit <n>] [--format json]";
+      const project = requireProject(input, "search", usage);
+      const query = requirePositional(input, 1, { command: "search", usage, message: "query is required" });
+      const limit = parseIntegerOption(input, "limit", {
+        command: "search",
+        usage,
+        message: "--limit must be an integer"
+      });
+      await searchProject(project, { query, limit, format: input.format });
+    }
+  }
+];
+
+// src/commands/content.ts
+async function listContentTargets(project, opts) {
+  const client = createApiClient();
+  const response = await client.getContentTargets(project, {
+    limit: opts.limit,
+    includeInProgress: opts.includeInProgress
+  });
+  if (opts.format === "json") {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+  if (response.targets.length === 0) {
+    console.log("No content targets surfaced. (Run `canonry run` to generate fresh signal.)");
+    return;
+  }
+  console.log(
+    `${response.targets.length} target${response.targets.length === 1 ? "" : "s"} (latestRunId=${response.contextMetrics.latestRunId})`
+  );
+  console.log("");
+  for (const target of response.targets) {
+    const action = target.action.toUpperCase().padEnd(11);
+    const score = target.score.toFixed(1).padStart(6);
+    const conf = target.actionConfidence.padEnd(6);
+    console.log(`${action} ${score}  conf=${conf}  ${target.query}`);
+    if (target.ourBestPage) {
+      const posLabel = target.ourBestPage.gscAvgPosition !== null ? `pos #${target.ourBestPage.gscAvgPosition}` : "no GSC ranking";
+      console.log(`            our page: ${target.ourBestPage.url} (${posLabel})`);
+    }
+    if (target.winningCompetitor) {
+      console.log(`            winning:  ${target.winningCompetitor.url} (${target.winningCompetitor.citationCount}\xD7 cited)`);
+    }
+    if (target.drivers.length > 0) {
+      console.log(`            why:      ${target.drivers.join(" \xB7 ")}`);
+    }
+    if (target.existingAction) {
+      console.log(`            in-flight action: ${target.existingAction.actionId} (${target.existingAction.state})`);
+    }
+    console.log("");
+  }
+}
+async function listContentSources(project, opts) {
+  const client = createApiClient();
+  const response = await client.getContentSources(project);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+  if (response.sources.length === 0) {
+    console.log("No grounding sources captured yet.");
+    return;
+  }
+  for (const row of response.sources) {
+    console.log(`Q: ${row.query}`);
+    if (row.groundingSources.length === 0) {
+      console.log("   (no grounding sources)");
+    } else {
+      for (const g of row.groundingSources) {
+        const tag = g.isOurDomain ? "OURS    " : g.isCompetitor ? "COMP    " : "OTHER   ";
+        console.log(`   ${tag} ${g.uri} (${g.citationCount}\xD7)`);
+      }
+    }
+    console.log("");
+  }
+}
+async function listContentGaps(project, opts) {
+  const client = createApiClient();
+  const response = await client.getContentGaps(project);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+  if (response.gaps.length === 0) {
+    console.log("No competitor-only-cited queries detected.");
+    return;
+  }
+  console.log(`${response.gaps.length} gap${response.gaps.length === 1 ? "" : "s"} found`);
+  console.log("");
+  for (const gap of response.gaps) {
+    const missPct = Math.round(gap.missRate * 100);
+    console.log(`${missPct.toString().padStart(3)}%  ${gap.competitorCount} competitor(s)  ${gap.query}`);
+    console.log(`       competitors: ${gap.competitorDomains.join(", ")}`);
+    console.log("");
+  }
+}
+
+// src/cli-commands/content.ts
+var CONTENT_CLI_COMMANDS = [
+  {
+    path: ["content", "targets"],
+    usage: "canonry content targets <project> [--limit <n>] [--include-in-progress] [--format json]",
+    options: {
+      limit: { type: "string" },
+      "include-in-progress": { type: "boolean" }
+    },
+    run: async (input) => {
+      const usage = "canonry content targets <project> [--limit <n>] [--include-in-progress] [--format json]";
+      const project = requireProject(input, "content targets", usage);
+      const limit = parseIntegerOption(input, "limit", {
+        command: "content targets",
+        usage,
+        message: "--limit must be a non-negative integer"
+      });
+      await listContentTargets(project, {
+        limit,
+        includeInProgress: input.values["include-in-progress"] === true,
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["content", "sources"],
+    usage: "canonry content sources <project> [--format json]",
+    options: {},
+    run: async (input) => {
+      const usage = "canonry content sources <project> [--format json]";
+      const project = requireProject(input, "content sources", usage);
+      await listContentSources(project, { format: input.format });
+    }
+  },
+  {
+    path: ["content", "gaps"],
+    usage: "canonry content gaps <project> [--format json]",
+    options: {},
+    run: async (input) => {
+      const usage = "canonry content gaps <project> [--format json]";
+      const project = requireProject(input, "content gaps", usage);
+      await listContentGaps(project, { format: input.format });
+    }
   }
 ];
 
@@ -8567,6 +8804,7 @@ var REGISTERED_CLI_COMMANDS = [
   ...CDP_CLI_COMMANDS,
   ...GA_CLI_COMMANDS,
   ...INTELLIGENCE_CLI_COMMANDS,
+  ...CONTENT_CLI_COMMANDS,
   ...AGENT_CLI_COMMANDS,
   ...MCP_CLI_COMMANDS
 ];

package/dist/index.js

@@ -1,10 +1,10 @@
 import {
   createServer
-} from "./chunk-SZSWQG3J.js";
+} from "./chunk-FCYNFM4B.js";
 import {
   loadConfig
-} from "./chunk-KWQCQMPY.js";
-import "./chunk-PYHANJ3B.js";
+} from "./chunk-PLI7EOPM.js";
+import "./chunk-UM6RDSRJ.js";
 import "./chunk-MLKGABMK.js";
 export {
   createServer,

package/dist/{intelligence-service-2ZABHNR4.js → intelligence-service-54F3NGPM.js}

@@ -1,6 +1,6 @@
 import {
   IntelligenceService
-} from "./chunk-PYHANJ3B.js";
+} from "./chunk-UM6RDSRJ.js";
 import "./chunk-MLKGABMK.js";
 export {
   IntelligenceService

package/dist/mcp.js

@@ -10,7 +10,7 @@ import {
   projectUpsertRequestSchema,
   runTriggerRequestSchema,
   scheduleUpsertRequestSchema
-} from "./chunk-KWQCQMPY.js";
+} from "./chunk-PLI7EOPM.js";
 import "./chunk-MLKGABMK.js";
 
 // src/mcp/cli.ts
@@ -202,6 +202,32 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}"],
     handler: (client, input) => client.getProject(input.project)
   }),
+  defineTool({
+    name: "canonry_project_overview",
+    title: "Get project overview (composite)",
+    description: 'One-call summary for "how is project X doing?" \u2014 bundles project info, latest run, top undismissed insights, latest health snapshot, keyword cited rate, per-provider breakdown, and gained/lost/emerging vs the previous run. Prefer this over fanning out to separate tools.',
+    access: "read",
+    tier: "core",
+    inputSchema: projectInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/overview"],
+    handler: (client, input) => client.getProjectOverview(input.project)
+  }),
+  defineTool({
+    name: "canonry_search",
+    title: "Search project (composite)",
+    description: "Search query snapshots and intelligence insights for the given text. Looks at snapshot answer text, cited domains, raw provider responses, and insight title/keyword/recommendation/cause. Returns ranked hits with snippets \u2014 use it instead of paginating snapshots when you need to find a competitor mention or term.",
+    access: "read",
+    tier: "core",
+    inputSchema: z2.object({
+      project: projectNameSchema,
+      q: z2.string().min(2).describe("Search term, at least 2 characters."),
+      limit: z2.number().int().positive().max(50).optional().describe("Max combined hits (1-50, default 25).")
+    }),
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/search"],
+    handler: (client, input) => client.searchProject(input.project, { q: input.q, limit: input.limit })
+  }),
   defineTool({
     name: "canonry_project_export",
     title: "Export project config",
@@ -885,7 +911,9 @@ var DynamicToolCatalog = class {
   loaded = /* @__PURE__ */ new Set();
   eager;
   scope;
-  constructor(entries, scope, options = {}) {
+  server;
+  constructor(server, entries, scope, options = {}) {
+    this.server = server;
     this.entries = entries;
     this.scope = scope;
     this.eager = Boolean(options.eager);
@@ -899,9 +927,11 @@ var DynamicToolCatalog = class {
   }
   applyInitialEnablement() {
     if (this.eager) return;
-    for (const entry of this.entries) {
-      if (entry.tool.tier !== "core") entry.registered.disable();
-    }
+    this.batchListChanged(() => {
+      for (const entry of this.entries) {
+        if (entry.tool.tier !== "core") entry.registered.disable();
+      }
+    });
   }
   loadToolkit(rawName) {
     if (!isCanonryMcpToolkitName(rawName)) {
@@ -916,9 +946,11 @@ var DynamicToolCatalog = class {
     if (this.loaded.has(name)) {
       return { status: "already-loaded", name, tools: matches.map((entry) => entry.tool.name) };
     }
-    for (const entry of matches) {
-      entry.registered.enable();
-    }
+    this.batchListChanged(() => {
+      for (const entry of matches) {
+        entry.registered.enable();
+      }
+    });
     this.loaded.add(name);
     return { status: "loaded", name, tools: matches.map((entry) => entry.tool.name) };
   }
@@ -929,7 +961,7 @@ var DynamicToolCatalog = class {
       loadedToolkits: [...this.loaded].sort(),
       coreTools: this.entries.filter((entry) => entry.tool.tier === "core").map((entry) => entry.tool.name),
       toolkits: CANONRY_MCP_TOOLKITS.map((toolkit) => this.toolkitEntry(toolkit)).filter((entry) => entry.toolCount > 0),
-      usage: "Call canonry_load_toolkit with one of the toolkit names listed in `toolkits[].name` to register its tools for the rest of this session."
+      usage: "Call canonry_load_toolkit with one of the toolkit names listed in `toolkits[].name` to register its tools for the rest of this session. Wait for its response before calling any newly enabled tool."
     };
   }
   toolkitEntry(toolkit) {
@@ -947,6 +979,25 @@ var DynamicToolCatalog = class {
   toolsForToolkit(name) {
     return this.entries.filter((entry) => entry.tool.tier === name).map((entry) => entry.tool.name);
   }
+  // RegisteredTool.enable/disable each call sendToolListChanged on the McpServer
+  // we registered with. Loading an 11-tool toolkit emits 11 notifications under
+  // that contract, which a spec-compliant client will treat as 11 catalog
+  // refetches. Coalesce them into one notification per batch by intercepting
+  // the SDK's sender for the duration of the batch.
+  batchListChanged(fn) {
+    const host = this.server;
+    const original = host.sendToolListChanged;
+    let suppressed = false;
+    host.sendToolListChanged = () => {
+      suppressed = true;
+    };
+    try {
+      fn();
+    } finally {
+      host.sendToolListChanged = original;
+    }
+    if (suppressed) original.call(host);
+  }
 };
 
 // src/mcp/server.ts
@@ -981,7 +1032,7 @@ function createCanonryMcpServerWithCatalog(options = {}) {
     );
     entries.push({ tool, registered });
   }
-  const catalog = new DynamicToolCatalog(entries, scope, { eager: options.eager });
+  const catalog = new DynamicToolCatalog(server, entries, scope, { eager: options.eager });
   catalog.applyInitialEnablement();
   registerMetaTools(server, catalog);
   return { server, catalog };
@@ -1004,7 +1055,7 @@ function registerMetaTools(server, catalog) {
     "canonry_load_toolkit",
     {
       title: "Load a Canonry MCP toolkit",
-      description: "Register a toolkit's tools for this session and emit notifications/tools/list_changed. Idempotent. Loaded toolkits remain loaded for the rest of the session.",
+      description: `Register a toolkit's tools for this session and emit one notifications/tools/list_changed. Idempotent. Loaded toolkits remain loaded for the rest of the session. Wait for this call to return before calling any newly enabled tool \u2014 pipelining the call with a tools/call on the same connection can race the registration and fail with "Tool ... disabled".`,
       inputSchema: loadToolkitInputSchema.shape,
       annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "type": "module",
   "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -59,21 +59,21 @@
     "@types/node-cron": "^3.0.11",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
+    "@ainyc/canonry-api-routes": "0.0.0",
+    "@ainyc/canonry-contracts": "0.0.0",
+    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-config": "0.0.0",
     "@ainyc/canonry-intelligence": "0.0.0",
-    "@ainyc/canonry-db": "0.0.0",
-    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-integration-bing": "0.0.0",
     "@ainyc/canonry-integration-commoncrawl": "0.0.0",
-    "@ainyc/canonry-integration-google": "0.0.0",
-    "@ainyc/canonry-contracts": "0.0.0",
     "@ainyc/canonry-integration-wordpress": "0.0.0",
+    "@ainyc/canonry-integration-google": "0.0.0",
     "@ainyc/canonry-provider-cdp": "0.0.0",
-    "@ainyc/canonry-provider-claude": "0.0.0",
-    "@ainyc/canonry-provider-local": "0.0.0",
-    "@ainyc/canonry-provider-perplexity": "0.0.0",
     "@ainyc/canonry-provider-gemini": "0.0.0",
-    "@ainyc/canonry-provider-openai": "0.0.0"
+    "@ainyc/canonry-provider-local": "0.0.0",
+    "@ainyc/canonry-provider-claude": "0.0.0",
+    "@ainyc/canonry-provider-openai": "0.0.0",
+    "@ainyc/canonry-provider-perplexity": "0.0.0"
   },
   "scripts": {
     "build": "tsx scripts/copy-agent-assets.ts && tsup && tsx build-web.ts",