@ainyc/canonry 2.9.0 → 2.10.3

package/dist/cli.js

@@ -17,7 +17,7 @@ import {
   setGoogleAuthConfig,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-MGBXRWLX.js";
+} from "./chunk-FAP76VXF.js";
 import {
   CcReleaseSyncStatuses,
   CliError,
@@ -29,6 +29,7 @@ import {
   createApiClient,
   determineAnswerMentioned,
   effectiveDomains,
+  formatRunErrorOneLine,
   getConfigDir,
   getConfigPath,
   isEndpointMissing,
@@ -40,7 +41,7 @@ import {
   saveConfig,
   saveConfigPatch,
   usageError
-} from "./chunk-FPZUQADO.js";
+} from "./chunk-Z3BWDCBJ.js";
 import {
   apiKeys,
   competitors,
@@ -50,7 +51,7 @@ import {
   projects,
   querySnapshots,
   runs
-} from "./chunk-PYHANJ3B.js";
+} from "./chunk-UM6RDSRJ.js";
 import "./chunk-MLKGABMK.js";
 
 // src/cli.ts
@@ -298,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);
@@ -677,7 +678,7 @@ async function backlinksExtract(opts) {
     return;
   }
   if (opts.wait) process.stderr.write("\n");
-  console.log(`Run ${final.id} (${final.status})${final.error ? " \u2014 " + final.error : ""}`);
+  console.log(`Run ${final.id} (${final.status})${final.error ? " \u2014 " + formatRunErrorOneLine(final.error) : ""}`);
 }
 async function backlinksCachePrune(opts) {
   if (!opts.release) {
@@ -4923,7 +4924,14 @@ function printRunDetail(run) {
   if (run.startedAt) console.log(`  Started:  ${run.startedAt}`);
   if (run.finishedAt) console.log(`  Finished: ${run.finishedAt}`);
   if (run.createdAt) console.log(`  Created:  ${run.createdAt}`);
-  if (run.error) console.log(`  Error:    ${run.error}`);
+  if (run.error) {
+    if (run.error.message) console.log(`  Error:    ${run.error.message}`);
+    if (run.error.providers) {
+      for (const [provider, detail] of Object.entries(run.error.providers)) {
+        console.log(`  Error (${provider}): ${detail.message}`);
+      }
+    }
+  }
   if (run.snapshots && run.snapshots.length > 0) {
     console.log(`
   Snapshots: ${run.snapshots.length}`);
@@ -6002,6 +6010,10 @@ async function showHealth(project, opts) {
     console.log(JSON.stringify(health, null, 2));
     return;
   }
+  if (health.status === "no-data") {
+    console.log("No health data yet \u2014 run a sweep first (canonry run <project>).");
+    return;
+  }
   const rate = (health.overallCitedRate * 100).toFixed(1);
   console.log(`Health: ${rate}% cited (${health.citedPairs}/${health.totalPairs} pairs)`);
   console.log("");
@@ -6063,6 +6075,137 @@ var INTELLIGENCE_CLI_COMMANDS = [
   }
 ];
 
+// 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 });
+    }
+  }
+];
+
 // src/commands/bootstrap.ts
 import crypto from "crypto";
 import path5 from "path";
@@ -6689,9 +6832,14 @@ Config saved to ${getConfigPath()}`);
 }
 
 // src/commands/serve.ts
+function resolveServePort(envPort, configPort) {
+  const trimmed = envPort?.trim();
+  if (trimmed) return parseInt(trimmed, 10);
+  return configPort ?? 4100;
+}
 async function serveCommand(format = "text") {
   const config = loadConfig();
-  const port = parseInt(process.env.CANONRY_PORT ?? "4100", 10);
+  const port = resolveServePort(process.env.CANONRY_PORT, config.port);
   const host = process.env.CANONRY_HOST ?? "127.0.0.1";
   config.port = port;
   const db = createClient(config.database);
@@ -6881,11 +7029,9 @@ function applyServerEnv(values) {
   const port = typeof values.port === "string" ? values.port : void 0;
   const host = typeof values.host === "string" ? values.host : void 0;
   const basePath = typeof values["base-path"] === "string" ? values["base-path"] : void 0;
-  process.env.CANONRY_PORT = port ?? "4100";
+  if (port) process.env.CANONRY_PORT = port;
   if (host) process.env.CANONRY_HOST = host;
-  else delete process.env.CANONRY_HOST;
   if (basePath) process.env.CANONRY_BASE_PATH = basePath;
-  else delete process.env.CANONRY_BASE_PATH;
 }
 var SYSTEM_CLI_COMMANDS = [
   {
@@ -8552,6 +8698,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-MGBXRWLX.js";
+} from "./chunk-FAP76VXF.js";
 import {
   loadConfig
-} from "./chunk-FPZUQADO.js";
-import "./chunk-PYHANJ3B.js";
+} from "./chunk-Z3BWDCBJ.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-FPZUQADO.js";
+} from "./chunk-Z3BWDCBJ.js";
 import "./chunk-MLKGABMK.js";
 
 // src/mcp/cli.ts
@@ -319,7 +319,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_health_latest",
     title: "Get latest health",
-    description: "Get the latest health snapshot for a Canonry project.",
+    description: 'Get the latest health snapshot for a Canonry project. Always returns a snapshot once the project exists: real data carries `status: "ready"`; newly-created projects (or projects with only failed runs) carry `status: "no-data"` with `reason: "no-runs-yet"` and zeroed metrics.',
     access: "read",
     tier: "monitoring",
     inputSchema: projectInputSchema,
@@ -753,6 +753,7 @@ var CANONRY_MCP_READ_TOOL_COUNT = canonryMcpTools.filter((tool) => tool.access =
 var CANONRY_MCP_CORE_TOOL_COUNT = canonryMcpTools.filter((tool) => tool.tier === "core").length;
 
 // src/mcp/results.ts
+import { ZodError } from "zod";
 function jsonToolResult(value) {
   const result = value === void 0 ? { ok: true } : value;
   return {
@@ -783,6 +784,15 @@ async function withToolErrors(handler) {
   }
 }
 function toCanonryErrorEnvelope(error) {
+  if (error instanceof ZodError) {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: zodErrorMessage(error),
+        details: { issues: error.issues.map(formatZodIssue) }
+      }
+    };
+  }
   if (error instanceof CliError) {
     return {
       error: {
@@ -821,6 +831,15 @@ function hasErrorEnvelope(value) {
   const error = value.error;
   return Boolean(error && typeof error === "object");
 }
+function formatZodIssue(issue) {
+  return { path: issue.path.map(String).join("."), message: issue.message };
+}
+function zodErrorMessage(error) {
+  const first = error.issues[0];
+  if (!first) return "Input validation failed";
+  const path = first.path.map(String).join(".");
+  return path ? `${path}: ${first.message}` : first.message;
+}
 
 // src/mcp/toolkits.ts
 var CANONRY_MCP_TOOLKIT_NAMES = ["monitoring", "setup", "gsc", "ga", "agent"];
@@ -942,6 +961,7 @@ function createCanonryMcpServerWithCatalog(options = {}) {
     name: "canonry",
     version: PACKAGE_VERSION
   });
+  server.validateToolInput = async (_tool, args) => args;
   const entries = [];
   for (const registryTool of getCanonryMcpTools(scope)) {
     const tool = registryTool;
@@ -954,7 +974,10 @@ function createCanonryMcpServerWithCatalog(options = {}) {
         inputSchema: tool.inputSchema,
         annotations: tool.annotations
       },
-      async (input) => withToolErrors(() => handler(client, input))
+      async (input) => withToolErrors(async () => {
+        const parsed = tool.inputSchema.parse(input ?? {});
+        return handler(client, parsed);
+      })
     );
     entries.push({ tool, registered });
   }
@@ -963,6 +986,9 @@ function createCanonryMcpServerWithCatalog(options = {}) {
   registerMetaTools(server, catalog);
   return { server, catalog };
 }
+var loadToolkitInputSchema = z3.object({
+  name: z3.enum(CANONRY_MCP_TOOLKIT_NAMES).describe("Toolkit name. List options with canonry_help.")
+});
 function registerMetaTools(server, catalog) {
   server.registerTool(
     "canonry_help",
@@ -979,12 +1005,13 @@ function registerMetaTools(server, catalog) {
     {
       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.",
-      inputSchema: {
-        name: z3.enum(CANONRY_MCP_TOOLKIT_NAMES).describe("Toolkit name. List options with canonry_help.")
-      },
+      inputSchema: loadToolkitInputSchema.shape,
       annotations: { readOnlyHint: false, idempotentHint: true, destructiveHint: false }
     },
-    async ({ name }) => withToolErrors(async () => catalog.loadToolkit(name))
+    async (input) => withToolErrors(async () => {
+      const parsed = loadToolkitInputSchema.parse(input ?? {});
+      return catalog.loadToolkit(parsed.name);
+    })
   );
 }
 function getCanonryMcpTools(scope = "all") {
@@ -992,12 +1019,46 @@ function getCanonryMcpTools(scope = "all") {
 }
 
 // src/mcp/cli.ts
+var HELP_TEXT = `Usage: canonry-mcp [--read-only | --scope=<all|read-only>] [--eager]
+
+Stdio MCP adapter over the Canonry public API. Inherits config from
+~/.canonry/config.yaml (or $CANONRY_CONFIG_DIR/config.yaml).
+
+Flags:
+  --read-only          Expose read tools only
+  --scope=<all|read-only>
+                       Same as --read-only when "read-only"
+  --eager              Load all toolkits at start (skip progressive discovery)
+  --help, -h           Show this message
+
+Environment variables:
+  CANONRY_MCP_SCOPE    "all" (default) or "read-only"
+  CANONRY_MCP_EAGER    "1" / "true" / "yes" to enable eager mode
+`;
+var HelpRequested = class extends Error {
+  constructor() {
+    super("canonry-mcp --help requested");
+    this.name = "HelpRequested";
+  }
+};
 async function main(argv = process.argv.slice(2)) {
-  const options = parseCliOptions(argv);
+  let options;
+  try {
+    options = parseCliOptions(argv);
+  } catch (error) {
+    if (error instanceof HelpRequested) {
+      process.stderr.write(HELP_TEXT);
+      return;
+    }
+    throw error;
+  }
   const server = createCanonryMcpServer({ scope: options.scope, eager: options.eager });
   await server.connect(new StdioServerTransport());
 }
 function parseCliOptions(argv, env = process.env) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    throw new HelpRequested();
+  }
   let scope = normalizeScope(env.CANONRY_MCP_SCOPE);
   let eager = parseEagerEnv(env.CANONRY_MCP_EAGER);
   for (let i = 0; i < argv.length; i += 1) {
@@ -1044,6 +1105,8 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   });
 }
 export {
+  HELP_TEXT,
+  HelpRequested,
   main,
   parseCliOptions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "2.9.0",
+  "version": "2.10.3",
   "type": "module",
   "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -61,18 +61,18 @@
     "tsx": "^4.19.0",
     "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-config": "0.0.0",
+    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-intelligence": "0.0.0",
     "@ainyc/canonry-contracts": "0.0.0",
-    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-integration-bing": "0.0.0",
     "@ainyc/canonry-integration-google": "0.0.0",
-    "@ainyc/canonry-integration-wordpress": "0.0.0",
     "@ainyc/canonry-provider-cdp": "0.0.0",
-    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
+    "@ainyc/canonry-integration-wordpress": "0.0.0",
     "@ainyc/canonry-provider-claude": "0.0.0",
     "@ainyc/canonry-provider-gemini": "0.0.0",
-    "@ainyc/canonry-provider-local": "0.0.0",
     "@ainyc/canonry-provider-openai": "0.0.0",
+    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
+    "@ainyc/canonry-provider-local": "0.0.0",
     "@ainyc/canonry-provider-perplexity": "0.0.0"
   },
   "scripts": {