@ainyc/canonry 1.37.1 → 1.39.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node --import tsx
 import {
+  IntelligenceService,
   apiKeys,
   configExists,
   createClient,
@@ -26,22 +27,26 @@ import {
   setGoogleAuthConfig,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-U2ZNKIWK.js";
+} from "./chunk-4W7EW7SN.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
 
 // src/cli-error.ts
+var EXIT_USER_ERROR = 1;
+var EXIT_SYSTEM_ERROR = 2;
 var CliError = class extends Error {
   code;
   displayMessage;
   details;
+  exitCode;
   constructor(options) {
     super(options.message);
     this.name = "CliError";
     this.code = options.code;
     this.displayMessage = options.displayMessage;
     this.details = options.details;
+    this.exitCode = options.exitCode ?? EXIT_USER_ERROR;
   }
 };
 function usageError(displayMessage, options) {
@@ -223,6 +228,41 @@ async function backfillAnswerVisibilityCommand(opts) {
   console.log(`  Updated:  ${updated}`);
   console.log(`  Visible:  ${visible}`);
 }
+async function backfillInsightsCommand(project, opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const service = new IntelligenceService(db);
+  const isJson = opts?.format === "json";
+  if (!isJson) {
+    process.stderr.write(`Backfilling insights for "${project}"...
+`);
+  }
+  const result = service.backfill(project, {
+    fromRunId: opts?.fromRun,
+    toRunId: opts?.toRun
+  }, (info) => {
+    if (!isJson) {
+      process.stderr.write(`  [${info.index}/${info.total}] ${info.runId} \u2014 ${info.insights} insights
+`);
+    }
+  });
+  const output = {
+    project,
+    processed: result.processed,
+    skipped: result.skipped,
+    totalInsights: result.totalInsights
+  };
+  if (isJson) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log(`
+Backfill complete.`);
+  console.log(`  Processed: ${result.processed}`);
+  console.log(`  Skipped:   ${result.skipped}`);
+  console.log(`  Insights:  ${result.totalInsights}`);
+}
 
 // src/cli-command-helpers.ts
 function getString(values, key) {
@@ -320,14 +360,31 @@ var BACKFILL_CLI_COMMANDS = [
       });
     }
   },
+  {
+    path: ["backfill", "insights"],
+    usage: "canonry backfill insights <project> [--from-run <id>] [--to-run <id>] [--format json]",
+    options: {
+      "from-run": stringOption(),
+      "to-run": stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry backfill insights <project> [--from-run <id>] [--to-run <id>] [--format json]";
+      const project = requireProject(input, "backfill insights", usage);
+      await backfillInsightsCommand(project, {
+        fromRun: getString(input.values, "from-run"),
+        toRun: getString(input.values, "to-run"),
+        format: input.format
+      });
+    }
+  },
   {
     path: ["backfill"],
-    usage: "canonry backfill <answer-visibility> [--project <name>] [--format json]",
+    usage: "canonry backfill <answer-visibility|insights> [options]",
     run: async (input) => {
       unknownSubcommand(input.positionals[0], {
         command: "backfill",
-        usage: "canonry backfill <answer-visibility> [--project <name>] [--format json]",
-        available: ["answer-visibility"]
+        usage: "canonry backfill <answer-visibility|insights> [options]",
+        available: ["answer-visibility", "insights"]
       });
     }
   }
@@ -398,13 +455,16 @@ var ApiClient = class {
         body: serializedBody
       });
     } catch (err) {
+      if (err instanceof CliError) throw err;
       const msg = err instanceof Error ? err.message : String(err);
       if (msg.includes("fetch failed") || msg.includes("ECONNREFUSED") || msg.includes("connect ECONNREFUSED")) {
-        throw new Error(
-          `Could not connect to canonry server at ${this.baseUrl.replace("/api/v1", "")}. Start it with "canonry serve" (or "canonry serve &" to run in background).`
-        );
+        throw new CliError({
+          code: "CONNECTION_ERROR",
+          message: `Could not connect to canonry server at ${this.baseUrl.replace("/api/v1", "")}. Start it with "canonry serve" (or "canonry serve &" to run in background).`,
+          exitCode: EXIT_SYSTEM_ERROR
+        });
       }
-      throw err;
+      throw new CliError({ code: "CONNECTION_ERROR", message: msg, exitCode: EXIT_SYSTEM_ERROR });
     }
     if (!res.ok) {
       let errorBody;
@@ -413,8 +473,11 @@ var ApiClient = class {
       } catch {
         errorBody = { error: { code: "UNKNOWN", message: res.statusText } };
       }
-      const msg = errorBody && typeof errorBody === "object" && "error" in errorBody && errorBody.error && typeof errorBody.error === "object" && "message" in errorBody.error ? String(errorBody.error.message) : `HTTP ${res.status}: ${res.statusText}`;
-      throw new Error(msg);
+      const errorObj = errorBody && typeof errorBody === "object" && "error" in errorBody && errorBody.error && typeof errorBody.error === "object" ? errorBody.error : null;
+      const msg = errorObj?.message ? String(errorObj.message) : `HTTP ${res.status}: ${res.statusText}`;
+      const code = errorObj?.code ? String(errorObj.code) : "API_ERROR";
+      const exitCode = res.status >= 500 ? EXIT_SYSTEM_ERROR : EXIT_USER_ERROR;
+      throw new CliError({ code, message: msg, exitCode });
     }
     if (res.status === 204) {
       return void 0;
@@ -744,6 +807,24 @@ var ApiClient = class {
   async wordpressStagingPush(project) {
     return this.request("POST", `/projects/${encodeURIComponent(project)}/wordpress/staging/push`);
   }
+  // ── Intelligence ──────────────────────────────────────────────────────
+  async getInsights(project, opts) {
+    const params = new URLSearchParams();
+    if (opts?.dismissed) params.set("dismissed", "true");
+    if (opts?.runId) params.set("runId", opts.runId);
+    const qs = params.toString();
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/insights${qs ? `?${qs}` : ""}`);
+  }
+  async dismissInsight(project, id) {
+    return this.request("POST", `/projects/${encodeURIComponent(project)}/insights/${encodeURIComponent(id)}/dismiss`);
+  }
+  async getHealth(project) {
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/health/latest`);
+  }
+  async getHealthHistory(project, limit) {
+    const qs = limit ? `?limit=${limit}` : "";
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/health/history${qs}`);
+  }
 };
 
 // src/commands/bing.ts
@@ -751,22 +832,12 @@ function getClient() {
   return createApiClient();
 }
 async function bingConnect(project, opts) {
-  let apiKey = opts?.apiKey;
-  if (!apiKey) {
-    const readline2 = await import("readline");
-    const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
-    apiKey = await new Promise((resolve) => {
-      rl.question("Bing Webmaster Tools API key: ", (answer) => {
-        rl.close();
-        resolve(answer.trim());
-      });
-    });
-  }
+  const apiKey = opts?.apiKey;
   if (!apiKey) {
     throw new CliError({
       code: "BING_API_KEY_REQUIRED",
-      message: "API key is required (pass --api-key or enter interactively)",
-      displayMessage: "Error: API key is required (pass --api-key or enter interactively)",
+      message: "API key is required. Pass --api-key <key>.",
+      displayMessage: "Error: API key is required. Pass --api-key <key>.",
       details: {
         project
       }
@@ -3287,13 +3358,13 @@ async function showStatus(project, format) {
     console.log(JSON.stringify({ project: projectData, runs: runs2 }, null, 2));
     return;
   }
-  console.log(`Status: ${projectData.displayName} (${projectData.name})
+  console.log(`Status: ${projectData.displayName ?? projectData.name} (${projectData.name})
 `);
   console.log(`  Domain:   ${projectData.canonicalDomain}`);
   console.log(`  Country:  ${projectData.country}`);
   console.log(`  Language: ${projectData.language}`);
   if (runs2.length > 0) {
-    const latest = runs2[runs2.length - 1];
+    const latest = runs2[0];
     console.log(`
   Latest run:`);
     console.log(`    ID:       ${latest.id}`);
@@ -3313,25 +3384,25 @@ async function showStatus(project, format) {
 var OPERATOR_CLI_COMMANDS = [
   {
     path: ["status"],
-    usage: "canonry status <project>",
+    usage: "canonry status <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "status", "canonry status <project>");
+      const project = requireProject(input, "status", "canonry status <project> [--format json]");
       await showStatus(project, input.format);
     }
   },
   {
     path: ["evidence"],
-    usage: "canonry evidence <project>",
+    usage: "canonry evidence <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "evidence", "canonry evidence <project>");
+      const project = requireProject(input, "evidence", "canonry evidence <project> [--format json]");
       await showEvidence(project, input.format);
     }
   },
   {
     path: ["history"],
-    usage: "canonry history <project>",
+    usage: "canonry history <project> [--format json]",
     run: async (input) => {
-      const project = requireProject(input, "history", "canonry history <project>");
+      const project = requireProject(input, "history", "canonry history <project> [--format json]");
       await showHistory(project, input.format);
     }
   },
@@ -3437,7 +3508,7 @@ async function showProject(name, format) {
     console.log(JSON.stringify(project, null, 2));
     return;
   }
-  console.log(`Project: ${project.displayName}
+  console.log(`Project: ${project.displayName ?? project.name}
 `);
   console.log(`  Name:             ${project.name}`);
   console.log(`  ID:               ${project.id}`);
@@ -3453,8 +3524,8 @@ async function showProject(name, format) {
   console.log(`  Tags:             ${project.tags.length > 0 ? project.tags.join(", ") : "(none)"}`);
   const labelEntries = Object.entries(project.labels);
   console.log(`  Labels:           ${labelEntries.length > 0 ? labelEntries.map(([k, v]) => `${k}=${v}`).join(", ") : "(none)"}`);
-  console.log(`  Created:          ${project.createdAt}`);
-  console.log(`  Updated:          ${project.updatedAt}`);
+  if (project.createdAt) console.log(`  Created:          ${project.createdAt}`);
+  if (project.updatedAt) console.log(`  Updated:          ${project.updatedAt}`);
 }
 async function updateProjectSettings(name, opts) {
   const client = getClient12();
@@ -3469,7 +3540,7 @@ async function updateProjectSettings(name, opts) {
     ownedDomains = ownedDomains.filter((d) => !toRemove.has(d));
   }
   const result = await client.putProject(name, {
-    displayName: opts.displayName ?? project.displayName,
+    displayName: opts.displayName ?? project.displayName ?? project.name,
     canonicalDomain: opts.domain ?? project.canonicalDomain,
     ownedDomains,
     country: opts.country ?? project.country,
@@ -4855,6 +4926,126 @@ var SNAPSHOT_CLI_COMMANDS = [
   }
 ];
 
+// src/commands/insights.ts
+async function listInsights(project, opts) {
+  const client = createApiClient();
+  const insights = await client.getInsights(project, { dismissed: opts.dismissed });
+  if (opts.format === "json") {
+    console.log(JSON.stringify(insights, null, 2));
+    return;
+  }
+  if (insights.length === 0) {
+    console.log("No insights found.");
+    return;
+  }
+  for (const insight of insights) {
+    const severity = insight.severity.toUpperCase().padEnd(8);
+    const dismissed = insight.dismissed ? " [dismissed]" : "";
+    console.log(`${severity} ${insight.type.padEnd(12)} ${insight.title}${dismissed}`);
+    if (insight.recommendation) {
+      console.log(`         Action: ${insight.recommendation.action}${insight.recommendation.target ? ` \u2192 ${insight.recommendation.target}` : ""}`);
+      console.log(`         Reason: ${insight.recommendation.reason}`);
+    }
+    if (insight.cause) {
+      console.log(`         Cause: ${insight.cause.cause}${insight.cause.competitorDomain ? ` (${insight.cause.competitorDomain})` : ""}`);
+    }
+    console.log("");
+  }
+}
+async function dismissInsight(project, id, opts) {
+  const client = createApiClient();
+  const result = await client.dismissInsight(project, id);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Insight ${id} dismissed.`);
+}
+
+// src/commands/health-cmd.ts
+async function showHealth(project, opts) {
+  const client = createApiClient();
+  if (opts.history) {
+    const snapshots = await client.getHealthHistory(project, opts.limit);
+    if (opts.format === "json") {
+      console.log(JSON.stringify(snapshots, null, 2));
+      return;
+    }
+    if (snapshots.length === 0) {
+      console.log("No health history available.");
+      return;
+    }
+    console.log("Date                      Cited Rate   Cited/Total");
+    console.log("\u2500".repeat(55));
+    for (const snap of snapshots) {
+      const rate2 = (snap.overallCitedRate * 100).toFixed(1).padStart(5) + "%";
+      const ratio = `${snap.citedPairs}/${snap.totalPairs}`;
+      const date = snap.createdAt.slice(0, 19).padEnd(25);
+      console.log(`${date} ${rate2}        ${ratio}`);
+    }
+    return;
+  }
+  const health = await client.getHealth(project);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(health, null, 2));
+    return;
+  }
+  const rate = (health.overallCitedRate * 100).toFixed(1);
+  console.log(`Health: ${rate}% cited (${health.citedPairs}/${health.totalPairs} pairs)`);
+  console.log("");
+  if (health.providerBreakdown && Object.keys(health.providerBreakdown).length > 0) {
+    console.log("Provider Breakdown:");
+    for (const [provider, stats] of Object.entries(health.providerBreakdown)) {
+      const pRate = (stats.citedRate * 100).toFixed(1);
+      console.log(`  ${provider.padEnd(15)} ${pRate}% (${stats.cited}/${stats.total})`);
+    }
+  }
+}
+
+// src/cli-commands/intelligence.ts
+var INTELLIGENCE_CLI_COMMANDS = [
+  {
+    path: ["insights"],
+    usage: "canonry insights <project> [--dismissed] [--format json]",
+    options: {
+      dismissed: { type: "boolean" }
+    },
+    run: async (input) => {
+      const usage = "canonry insights <project> [--dismissed] [--format json]";
+      const project = requireProject(input, "insights", usage);
+      const dismissed = input.values.dismissed === true;
+      await listInsights(project, { dismissed, format: input.format });
+    }
+  },
+  {
+    path: ["insights", "dismiss"],
+    usage: "canonry insights dismiss <project> <id> [--format json]",
+    options: {},
+    run: async (input) => {
+      const usage = "canonry insights dismiss <project> <id> [--format json]";
+      const project = requireProject(input, "insights dismiss", usage);
+      const id = requirePositional(input, 1, { command: "insights dismiss", usage, message: "insight ID is required" });
+      await dismissInsight(project, id, { format: input.format });
+    }
+  },
+  {
+    path: ["health"],
+    usage: "canonry health <project> [--history] [--limit <n>] [--format json]",
+    options: {
+      history: { type: "boolean" },
+      limit: { type: "string" }
+    },
+    run: async (input) => {
+      const usage = "canonry health <project> [--history] [--limit <n>] [--format json]";
+      const project = requireProject(input, "health", usage);
+      const history = input.values.history === true;
+      const limitStr = getString(input.values, "limit");
+      const limit = limitStr ? Number.parseInt(limitStr, 10) : void 0;
+      await showHealth(project, { history, limit, format: input.format });
+    }
+  }
+];
+
 // src/commands/bootstrap.ts
 import crypto from "crypto";
 import path2 from "path";
@@ -5035,15 +5226,17 @@ async function bootstrapCommand(_opts) {
   const keyPrefix = rawApiKey.slice(0, 9);
   const db = createClient(databasePath);
   migrate(db);
-  db.delete(apiKeys).where(eq2(apiKeys.name, "default")).run();
-  db.insert(apiKeys).values({
-    id: crypto.randomUUID(),
-    name: "default",
-    keyHash,
-    keyPrefix,
-    scopes: '["*"]',
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  }).run();
+  db.transaction((tx) => {
+    tx.delete(apiKeys).where(eq2(apiKeys.name, "default")).run();
+    tx.insert(apiKeys).values({
+      id: crypto.randomUUID(),
+      name: "default",
+      keyHash,
+      keyPrefix,
+      scopes: '["*"]',
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    }).run();
+  });
   saveConfig({
     apiUrl: env.apiUrl || existingConfig?.apiUrl || `http://localhost:${process.env.CANONRY_PORT || "4100"}`,
     database: databasePath,
@@ -5454,6 +5647,15 @@ async function serveCommand(format = "text") {
   const db = createClient(config.database);
   migrate(db);
   const app = await createServer({ config, db });
+  const shutdown = () => {
+    app.close().then(() => {
+      process.exit(0);
+    }).catch(() => {
+      process.exit(1);
+    });
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
   try {
     await app.listen({ host, port });
     const url = `http://${host === "0.0.0.0" ? "localhost" : host}:${port}`;
@@ -5758,16 +5960,6 @@ import fs6 from "fs";
 function getClient17() {
   return createApiClient();
 }
-async function promptForAppPassword() {
-  const readline2 = await import("readline");
-  const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
-  return new Promise((resolve) => {
-    rl.question("WordPress Application Password: ", (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -5903,12 +6095,12 @@ Staging:`);
   console.log(`  Snippet:      ${diff.staging.contentSnippet || "(empty)"}`);
 }
 async function wordpressConnect(project, opts) {
-  const appPassword = opts.appPassword ?? await promptForAppPassword();
+  const appPassword = opts.appPassword;
   if (!appPassword) {
     throw new CliError({
       code: "WORDPRESS_APP_PASSWORD_REQUIRED",
       message: "WordPress Application Password is required",
-      displayMessage: "Error: WordPress Application Password is required (pass --app-password or enter interactively).",
+      displayMessage: "Error: WordPress Application Password is required. Pass --app-password <password>.",
       details: { project }
     });
   }
@@ -6200,12 +6392,12 @@ async function wordpressSchemaStatus(project, opts) {
   }
 }
 async function wordpressOnboard(project, opts) {
-  const appPassword = opts.appPassword ?? await promptForAppPassword();
+  const appPassword = opts.appPassword;
   if (!appPassword) {
     throw new CliError({
       code: "WORDPRESS_APP_PASSWORD_REQUIRED",
       message: "WordPress Application Password is required",
-      displayMessage: "Error: WordPress Application Password is required (pass --app-password or enter interactively).",
+      displayMessage: "Error: WordPress Application Password is required. Pass --app-password <password>.",
       details: { project }
     });
   }
@@ -6815,7 +7007,8 @@ var REGISTERED_CLI_COMMANDS = [
   ...BING_CLI_COMMANDS,
   ...WORDPRESS_CLI_COMMANDS,
   ...CDP_CLI_COMMANDS,
-  ...GA_CLI_COMMANDS
+  ...GA_CLI_COMMANDS,
+  ...INTELLIGENCE_CLI_COMMANDS
 ];
 
 // src/cli.ts
@@ -6828,6 +7021,7 @@ Usage:
   canonry init --gemini-key <key>     Initialize non-interactively (also reads env vars)
   canonry bootstrap [--force]          Bootstrap config/database from env vars
   canonry backfill answer-visibility   Backfill answer-level visibility from stored answers
+  canonry backfill insights <project>  Backfill intelligence insights [--from-run <id>] [--to-run <id>]
   canonry serve                       Start the local server (foreground)
   canonry start                       Start the server as a background daemon
   canonry stop                        Stop the background daemon
@@ -6857,10 +7051,13 @@ Usage:
   canonry run --all                   Trigger runs for all projects
   canonry run show <id>               Show run details and snapshots
   canonry runs <project>              List runs for a project (--limit <n>)
-  canonry status <project>            Show project summary
-  canonry evidence <project>          Show per-phrase results
+  canonry status <project>            Show project summary [--format json]
+  canonry evidence <project>          Show per-phrase results [--format json]
   canonry analytics <project>         Show analytics (--feature metrics|gaps|sources, --window 7d|30d|90d|all)
-  canonry history <project>           Show audit trail
+  canonry insights <project>           Show intelligence insights [--dismissed] [--format json]
+  canonry insights dismiss <project> <id>  Dismiss an insight [--format json]
+  canonry health <project>             Show citation health [--history] [--limit <n>] [--format json]
+  canonry history <project>           Show audit trail [--format json]
   canonry export <project>            Export project as YAML
   canonry apply <file...>              Apply declarative config (multi-doc YAML supported)
   canonry schedule set <project>      Set schedule (--preset or --cron)
@@ -7019,7 +7216,7 @@ Run "canonry --help" for usage.`, {
     });
   } catch (err) {
     printCliError(err, format);
-    return 1;
+    return err instanceof CliError ? err.exitCode : EXIT_SYSTEM_ERROR;
   }
 }
 async function main(args = process.argv.slice(2)) {

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   createServer,
   loadConfig
-} from "./chunk-U2ZNKIWK.js";
+} from "./chunk-4W7EW7SN.js";
 export {
   createServer,
   loadConfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "1.37.1",
+  "version": "1.39.0",
   "type": "module",
   "description": "The ultimate open-source AEO monitoring tool - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -55,17 +55,18 @@
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "@ainyc/canonry-api-routes": "0.0.0",
-    "@ainyc/canonry-contracts": "0.0.0",
-    "@ainyc/canonry-integration-google": "0.0.0",
-    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-config": "0.0.0",
+    "@ainyc/canonry-db": "0.0.0",
+    "@ainyc/canonry-contracts": "0.0.0",
     "@ainyc/canonry-integration-bing": "0.0.0",
+    "@ainyc/canonry-intelligence": "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-provider-local": "0.0.0",
-    "@ainyc/canonry-provider-openai": "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-provider-perplexity": "0.0.0"
   },
   "scripts": {