@canonry/canonry 7.25.0 → 7.43.2

package/dist/chunk-WRUKKEGR.js

@@ -0,0 +1,562 @@
+import {
+  emitJsonl,
+  readWindowOptions,
+  resolveCliAccess,
+  resolveCliAccessForInvocation,
+  windowOptions
+} from "./chunk-WU2BRWXY.js";
+import {
+  CliError,
+  EXIT_USER_ERROR,
+  usageError
+} from "./chunk-HGMYEDAQ.js";
+import {
+  OperationAccesses
+} from "./chunk-E43JM3QV.js";
+
+// src/cli-catalog.ts
+import { createRequire } from "module";
+
+// src/cli-dispatch.ts
+import { parseArgs } from "util";
+function commandId(spec) {
+  return spec.path.join(".");
+}
+function commandUsage(spec) {
+  let usage = spec.usage;
+  if (spec.windows) {
+    const selection = `[--window ${spec.windows.join("|")}]`;
+    if (usage.includes("[--window ")) usage = usage.replace(/\[--window [^\]]+\]/, selection);
+    else if (spec.windowAliases?.window === "period") usage = usage.replace(/\[--period [^\]]+\]/, selection);
+    else usage += ` ${selection}`;
+  }
+  for (const key of ["start", "end"]) {
+    const alias = spec.windowAliases?.[key];
+    if (alias) usage = usage.replace(`--${alias} `, `--${key} `);
+  }
+  return usage;
+}
+function printCommandHelp(spec) {
+  console.log(`
+Usage:  ${commandUsage(spec)}
+`);
+  const access = spec.access ?? OperationAccesses.stored;
+  console.log(`Access: ${access} (${access === OperationAccesses.live ? "calls a provider now" : access === OperationAccesses.write ? "changes server state" : "uses stored data"})
+`);
+  if (spec.help) console.log(`${spec.help}
+`);
+  const aliases = Object.entries(spec.windowAliases ?? {}).map(([canonical, alias]) => `--${alias} for --${canonical}`);
+  if (aliases.length) console.log(`Aliases: ${aliases.join("; ")}. Do not combine an alias with its canonical flag.
+`);
+}
+function matchesPath(args, path) {
+  if (args.length < path.length) return false;
+  return path.every((segment, index) => args[index] === segment);
+}
+var CLI_GLOBAL_OPTIONS = {
+  format: { type: "string" },
+  "dry-run": { type: "boolean" },
+  trace: { type: "boolean" },
+  access: { type: "string" },
+  "stored-only": { type: "boolean" }
+};
+function commandOptions(spec) {
+  return { ...CLI_GLOBAL_OPTIONS, ...spec.options, ...windowOptions({ window: Boolean(spec.windows), dates: Boolean(spec.options?.start || spec.windowAliases?.start), aliases: spec.windowAliases }) };
+}
+function accessFilterFromArgs(args) {
+  const index = args.findIndex((arg2) => arg2 === "--access" || arg2.startsWith("--access="));
+  if (index < 0) return void 0;
+  const arg = args[index];
+  const value = arg.startsWith("--access=") ? arg.slice("--access=".length) : args[index + 1];
+  if (!value || value.startsWith("--")) throw usageError("--access requires stored, live, or write", { details: { option: "access" } });
+  return value;
+}
+function validateAccessFilter(value) {
+  if (value !== void 0 && value !== OperationAccesses.stored && value !== OperationAccesses.live && value !== OperationAccesses.write) {
+    throw usageError(`Unknown access filter: ${value}`, { details: { access: value } });
+  }
+}
+function toFormat(value, fallbackFormat) {
+  if (value === "json") return "json";
+  if (value === "jsonl") return "jsonl";
+  return fallbackFormat;
+}
+function printGroupHelp(group, specs, accessFilter) {
+  const parentSpec = specs.find((s) => s.path.length === 1 && s.path[0] === group);
+  const groupSpecs = specs.filter((s) => s.path[0] === group && s.path.length > 1 && (!accessFilter || (s.access ?? OperationAccesses.stored) === accessFilter)).sort((a, b) => a.path.join(" ").localeCompare(b.path.join(" ")));
+  if (groupSpecs.length === 0) {
+    if (parentSpec && (!accessFilter || (parentSpec.access ?? OperationAccesses.stored) === accessFilter)) printCommandHelp(parentSpec);
+    else if (accessFilter) console.log(`No commands in group "${group}" match access "${accessFilter}".`);
+    return;
+  }
+  console.log(`
+Usage:  canonry ${group} <command> [options]
+`);
+  if (parentSpec && (!accessFilter || (parentSpec.access ?? OperationAccesses.stored) === accessFilter)) {
+    const access = parentSpec.access ?? OperationAccesses.stored;
+    console.log(`  [${access}] ${commandUsage(parentSpec)}
+`);
+  }
+  console.log("Subcommands:");
+  for (const spec of groupSpecs) {
+    console.log(`  [${spec.access ?? OperationAccesses.stored}] ${commandUsage(spec)}`);
+  }
+  console.log();
+}
+async function dispatchRegisteredCommand(args, fallbackFormat, specs) {
+  if (args.length >= 1 && (args.includes("--help") || args.includes("-h"))) {
+    const argsWithoutHelp = args.filter((a) => a !== "--help" && a !== "-h");
+    const accessValue = accessFilterFromArgs(argsWithoutHelp);
+    validateAccessFilter(accessValue);
+    if (fallbackFormat !== "text") {
+      const { printCliCatalog: printCliCatalog2 } = await import("./cli-catalog-J3O6W726.js");
+      const group2 = argsWithoutHelp.find((arg) => !arg.startsWith("--"));
+      printCliCatalog2(specs, fallbackFormat, group2, accessValue);
+      return true;
+    }
+    const exactMatch = [...specs].sort((a, b) => b.path.length - a.path.length).find((candidate) => matchesPath(argsWithoutHelp, candidate.path));
+    if (exactMatch && exactMatch.path.length > 1) {
+      if (accessValue !== void 0 && (exactMatch.access ?? OperationAccesses.stored) !== accessValue) {
+        console.log(`No command "${exactMatch.path.join(" ")}" matches access "${accessValue}".`);
+      } else {
+        printCommandHelp(exactMatch);
+      }
+      return true;
+    }
+    const group = argsWithoutHelp[0];
+    if (group) {
+      const groupSpecs = specs.filter((s) => s.path[0] === group && s.path.length > 1);
+      if (groupSpecs.length > 0) {
+        printGroupHelp(group, specs, accessValue);
+        return true;
+      }
+      const single = specs.find((s) => s.path.length === 1 && s.path[0] === group);
+      if (single) {
+        printGroupHelp(group, specs, accessValue);
+        return true;
+      }
+    }
+  }
+  const spec = [...specs].sort((a, b) => b.path.length - a.path.length).find((candidate) => matchesPath(args, candidate.path));
+  if (!spec) {
+    const root = args[0];
+    if (root && specs.some((candidate) => candidate.path[0] === root)) {
+      if (args.length === 1) {
+        printGroupHelp(root, specs);
+        return true;
+      }
+      throw usageError(`Error: unknown ${root} subcommand: ${args[1]}`, {
+        message: `unknown ${root} subcommand`,
+        details: { command: root, subcommand: args[1] }
+      });
+    }
+    return false;
+  }
+  const remainingArgs = args.slice(spec.path.length);
+  let values;
+  let positionals;
+  try {
+    const parsed = parseArgs({
+      args: remainingArgs,
+      options: commandOptions(spec),
+      allowPositionals: spec.allowPositionals ?? true
+    });
+    values = parsed.values;
+    positionals = [...parsed.positionals];
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "invalid command usage";
+    throw usageError(`Error: ${message}
+Usage: ${spec.usage}`, {
+      message,
+      details: {
+        command: commandId(spec),
+        usage: spec.usage
+      }
+    });
+  }
+  if (values.access !== void 0 && spec.path[0] !== "help") {
+    throw usageError("--access is supported only with help or --help", {
+      message: "--access is supported only with help or --help",
+      details: { command: commandId(spec), usage: commandUsage(spec) }
+    });
+  }
+  if (values.trace === true) {
+    process.env.CANONRY_TRACE = "1";
+  }
+  const dryRunRequested = values["dry-run"] === true;
+  const access = resolveCliAccessForInvocation(spec, { positionals, values, dryRun: dryRunRequested });
+  const storedOnly = values["stored-only"] === true || ["1", "true"].includes((process.env.CANONRY_STORED_ONLY ?? "").toLowerCase());
+  if (storedOnly) {
+    process.env.CANONRY_STORED_ONLY = "1";
+    if (access !== OperationAccesses.stored) {
+      throw new CliError({
+        code: "STORED_ONLY_REFUSED",
+        message: `Command "${spec.path.join(" ")}" is ${access}; --stored-only allows saved-data reads only`,
+        details: { command: commandId(spec), access },
+        exitCode: EXIT_USER_ERROR
+      });
+    }
+  }
+  if (dryRunRequested && !spec.supportsDryRun) {
+    throw usageError(
+      `Command "${spec.path.join(" ")}" does not support --dry-run. Either drop the flag, or run a different command that supports preview mode (e.g. \`canonry doctor\` for health checks, \`canonry status <project>\` for read-only state).`,
+      {
+        message: `Command "${spec.path.join(" ")}" does not support --dry-run`,
+        details: { command: commandId(spec), usage: spec.usage }
+      }
+    );
+  }
+  if (spec.windows || spec.windowAliases) {
+    const selection = readWindowOptions({ positionals, values, format: toFormat(values.format, fallbackFormat), dryRun: dryRunRequested }, { allowed: spec.windows, aliases: spec.windowAliases, command: commandId(spec), usage: commandUsage(spec) });
+    values.window = selection.window;
+    values.start = selection.startDate;
+    values.end = selection.endDate;
+  }
+  await spec.run({
+    positionals,
+    values,
+    format: toFormat(values.format, fallbackFormat),
+    dryRun: dryRunRequested
+  });
+  return true;
+}
+
+// src/cli-catalog.ts
+var { version } = createRequire(import.meta.url)("../package.json");
+var CLI_ROOT_SUMMARIES = {
+  "bootstrap": {
+    "section": "Setup",
+    "summary": "Create local config/database (no provider required)"
+  },
+  "serve": {
+    "section": "Setup",
+    "summary": "Start the local server (foreground)"
+  },
+  "demo": {
+    "section": "Setup",
+    "summary": "Serve a public view-only sample dashboard"
+  },
+  "init": {
+    "section": "Setup",
+    "summary": "Optional interactive provider/OAuth provisioning"
+  },
+  "skills": {
+    "section": "Setup",
+    "summary": "List or install bundled agent skills (claude/codex)"
+  },
+  "technical-aeo": {
+    "section": "Page Health",
+    "summary": "Crawl, score, and inspect site health evidence"
+  },
+  "doctor": {
+    "section": "Page Health",
+    "summary": "Diagnose runtime and integration health"
+  },
+  "project": {
+    "section": "Projects",
+    "summary": "Create, update, list, show, delete projects"
+  },
+  "query": {
+    "section": "Projects",
+    "summary": "Add, replace, remove, list, import, generate queries"
+  },
+  "competitor": {
+    "section": "Projects",
+    "summary": "Add, remove, list competitors and their aliases"
+  },
+  "run": {
+    "section": "Monitoring",
+    "summary": "Trigger visibility sweeps"
+  },
+  "runs": {
+    "section": "Monitoring",
+    "summary": "List runs (filter by --kind, --status, --since)"
+  },
+  "snapshot": {
+    "section": "Monitoring",
+    "summary": "One-shot AI perception report"
+  },
+  "status": {
+    "section": "Monitoring",
+    "summary": "Show project summary"
+  },
+  "evidence": {
+    "section": "Monitoring",
+    "summary": "Show per-query results"
+  },
+  "analytics": {
+    "section": "Monitoring",
+    "summary": "Show analytics (metrics, gaps, sources)"
+  },
+  "organic-evidence": {
+    "section": "Monitoring",
+    "summary": "Reconcile 60/90d search, GA4, and server AI evidence"
+  },
+  "insights": {
+    "section": "Monitoring",
+    "summary": "Show intelligence insights"
+  },
+  "health": {
+    "section": "Monitoring",
+    "summary": "Show citation health"
+  },
+  "apply": {
+    "section": "Config-as-Code",
+    "summary": "Apply declarative config (YAML)"
+  },
+  "export": {
+    "section": "Config-as-Code",
+    "summary": "Export project as YAML"
+  },
+  "google": {
+    "section": "Integrations",
+    "summary": "Google Search Console / Analytics"
+  },
+  "bing": {
+    "section": "Integrations",
+    "summary": "Bing Webmaster Tools"
+  },
+  "wordpress": {
+    "section": "Integrations",
+    "summary": "WordPress REST API"
+  },
+  "traffic": {
+    "section": "Integrations",
+    "summary": "Server-side traffic ingestion (Cloud Run)"
+  },
+  "schedule": {
+    "section": "Automation",
+    "summary": "Manage scheduled runs"
+  },
+  "notify": {
+    "section": "Automation",
+    "summary": "Manage webhook notifications"
+  },
+  "settings": {
+    "section": "Admin",
+    "summary": "Show/update provider and quota settings"
+  },
+  "dashboard": {
+    "section": "Admin",
+    "summary": "Reset the dashboard password"
+  },
+  "backfill": {
+    "section": "Admin",
+    "summary": "Backfill answer visibility or insights"
+  },
+  "telemetry": {
+    "section": "Admin",
+    "summary": "Manage anonymous telemetry"
+  },
+  "history": {
+    "section": "Admin",
+    "summary": "Show audit trail"
+  },
+  "support": {
+    "section": "Admin",
+    "summary": "Get help: Canonry Discord and issue tracker"
+  },
+  "start": {
+    "section": "Setup",
+    "summary": "Start/stop as a background daemon"
+  },
+  "stop": {
+    "section": "Setup",
+    "summary": "Start/stop as a background daemon"
+  },
+  "help": {
+    "section": "Setup",
+    "summary": "Find commands and inspect the CLI catalog"
+  },
+  "mcp": {
+    "section": "Setup",
+    "summary": "Install and manage MCP client connections"
+  },
+  "site-health": {
+    "section": "Page Health",
+    "summary": "Crawl, score, and inspect site health evidence"
+  },
+  "keyword": {
+    "section": "Projects",
+    "summary": "Inspect and maintain tracked query evidence"
+  },
+  "measurement-plan": {
+    "section": "Projects",
+    "summary": "Configure properties, targets, markets and measurement plans"
+  },
+  "overview": {
+    "section": "Monitoring",
+    "summary": "Show the stored project overview"
+  },
+  "results": {
+    "section": "Monitoring",
+    "summary": "Read stored run and query results"
+  },
+  "sources": {
+    "section": "Monitoring",
+    "summary": "Read stored citation sources"
+  },
+  "citations": {
+    "section": "Monitoring",
+    "summary": "Read stored citation evidence"
+  },
+  "visibility-stats": {
+    "section": "Monitoring",
+    "summary": "Show stored mention and citation statistics"
+  },
+  "visibility-compare": {
+    "section": "Monitoring",
+    "summary": "Compare stored mention and citation results"
+  },
+  "sentiment": {
+    "section": "Monitoring",
+    "summary": "Inspect and manage experimental sentiment measurement"
+  },
+  "ga": {
+    "section": "Integrations",
+    "summary": "Read and manage Google Analytics evidence"
+  },
+  "gbp": {
+    "section": "Integrations",
+    "summary": "Manage business profiles and stored evidence"
+  },
+  "google-ads": {
+    "section": "Integrations",
+    "summary": "Manage advertising connections and stored performance"
+  },
+  "gtm": {
+    "section": "Integrations",
+    "summary": "Manage tag manager accounts, containers and workspaces"
+  },
+  "conversion-tracking": {
+    "section": "Integrations",
+    "summary": "Configure and inspect conversion tracking"
+  },
+  "backlinks": {
+    "section": "Integrations",
+    "summary": "Inspect and sync stored backlink evidence"
+  },
+  "cdp": {
+    "section": "Integrations",
+    "summary": "Manage browser-backed provider connections"
+  },
+  "ads": {
+    "section": "Integrations",
+    "summary": "Manage advertising accounts, campaigns and performance"
+  },
+  "agent": {
+    "section": "Automation",
+    "summary": "Manage analyst agents and conversations"
+  },
+  "content": {
+    "section": "Automation",
+    "summary": "Create and manage content work"
+  },
+  "discover": {
+    "section": "Automation",
+    "summary": "Discover, inspect and promote query candidates"
+  },
+  "research": {
+    "section": "Automation",
+    "summary": "Research queries and inspect stored results"
+  },
+  "search": {
+    "section": "Automation",
+    "summary": "Search stored project evidence"
+  },
+  "get": {
+    "section": "Automation",
+    "summary": "Read a field from stored project evidence"
+  },
+  "key": {
+    "section": "Admin",
+    "summary": "Manage API keys and project scopes"
+  },
+  "user": {
+    "section": "Admin",
+    "summary": "Manage dashboard users"
+  },
+  "logs": {
+    "section": "Admin",
+    "summary": "Read stored runtime logs"
+  },
+  "feedback": {
+    "section": "Admin",
+    "summary": "Send product feedback"
+  }
+};
+function catalogOptions(options) {
+  return Object.entries(options).map(([name, option]) => ({ name, type: option.type, multiple: option.multiple ?? false }));
+}
+function buildCliCatalog(specs) {
+  const roots = [...new Set(specs.map((spec) => spec.path[0]))];
+  const groups = roots.map((root) => {
+    const summary = CLI_ROOT_SUMMARIES[root];
+    if (!summary) throw new Error(`Missing CLI root summary: ${root}`);
+    return {
+      root,
+      ...summary,
+      commands: specs.filter((spec) => spec.path[0] === root).map((spec) => ({
+        id: spec.path.join("."),
+        path: [...spec.path],
+        usage: commandUsage(spec),
+        supportsDryRun: spec.supportsDryRun ?? false,
+        ...spec.windows ? { windows: [...spec.windows] } : {},
+        options: catalogOptions(commandOptions(spec)),
+        access: resolveCliAccess(spec)
+      }))
+    };
+  });
+  return { version, globalOptions: catalogOptions({ ...CLI_GLOBAL_OPTIONS, help: { type: "boolean" }, version: { type: "boolean" } }), groups };
+}
+function renderTopLevelHelp(catalog) {
+  const sections = ["Setup", "Page Health", "Projects", "Monitoring", "Config-as-Code", "Integrations", "Automation", "Admin"];
+  const lines = ["cnry - Page Health and AI visibility CLI   ('canonry' also works)", "", "Usage:  cnry <command> [options]", ""];
+  for (const section of [.../* @__PURE__ */ new Set([...sections, ...catalog.groups.map((group) => group.section)])]) {
+    const groups = catalog.groups.filter((group) => group.section === section);
+    if (!groups.length) continue;
+    lines.push(`${section}:`, ...groups.map((group) => `  ${group.root.padEnd(22)}${group.summary}`), "");
+  }
+  lines.push(
+    "Global options:",
+    "  --format json         Machine-readable output: one JSON document (all commands)",
+    "  --format jsonl        Machine-readable output: one record per line, no jq needed",
+    "  --dry-run             Preview commands that support it",
+    "  --stored-only         Refuse provider and write operations",
+    "  --access <mode>       Filter help/catalog by stored, live, or write access",
+    "  --trace               Trace API requests to stderr",
+    "  --help, -h            Show help (use with any command group)",
+    "  --version, -v         Show version",
+    "",
+    "Run 'cnry <command> --help' for details on a specific command."
+  );
+  return lines.join("\n");
+}
+function printCliCatalog(specs, format, group, access) {
+  const catalog = buildCliCatalog(specs);
+  if (access !== void 0 && access !== OperationAccesses.stored && access !== OperationAccesses.live && access !== OperationAccesses.write) {
+    throw usageError(`Unknown access filter: ${access}`, { details: { access } });
+  }
+  const knownGroup = group ? catalog.groups.find((entry) => entry.root === group) : void 0;
+  if (group && !knownGroup) throw usageError(`Unknown command group: ${group}`, { details: { group, usage: "canonry help [<group>] [--format json|jsonl]" } });
+  if (access) {
+    for (const entry of catalog.groups) entry.commands = entry.commands.filter((command) => command.access === access);
+    catalog.groups = catalog.groups.filter((entry) => entry.commands.length > 0 || entry.root === group);
+  }
+  if (group) {
+    catalog.groups = catalog.groups.filter((entry) => entry.root === group);
+  }
+  if (format === "json") console.log(JSON.stringify(catalog, null, 2));
+  else if (format === "jsonl") emitJsonl(catalog.groups.flatMap((entry) => entry.commands.map((command) => ({ root: entry.root, ...command }))));
+  else if (group) printGroupHelp(group, specs, access);
+  else console.log(renderTopLevelHelp(catalog));
+}
+
+export {
+  accessFilterFromArgs,
+  dispatchRegisteredCommand,
+  CLI_ROOT_SUMMARIES,
+  buildCliCatalog,
+  renderTopLevelHelp,
+  printCliCatalog
+};