@ainyc/canonry 4.154.1 → 4.156.0

package/dist/cli.js

@@ -30,7 +30,7 @@ import {
   showFirstRunNotice,
   trackCliCommandFinished,
   trackEvent
-} from "./chunk-JOP2DGXL.js";
+} from "./chunk-ZWESOFA5.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -50,7 +50,7 @@ import {
   saveConfigPatch,
   systemError,
   usageError
-} from "./chunk-ANSQ6JNO.js";
+} from "./chunk-CPASKGUE.js";
 import {
   apiKeys,
   createClient,
@@ -58,7 +58,7 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-KRMLGFY3.js";
+} from "./chunk-ABNN2ZVR.js";
 import {
   AdsDeliverySnapshotStatuses,
   AdsHistoricalCampaignRollupStatuses,
@@ -122,7 +122,7 @@ import {
   providerQuotaPolicySchema,
   resolveProviderInput,
   winnabilityClassSchema
-} from "./chunk-NNW7TJUZ.js";
+} from "./chunk-AMPT2EP7.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -13829,11 +13829,339 @@ async function technicalAeoTrend(project, opts) {
   }
   console.log(lines.join("\n"));
 }
+async function technicalAeoCrawl(project, opts) {
+  const crawl = await getClient27().getTechnicalAeoCrawl(project, { runId: opts.runId });
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(crawl, null, 2));
+    return;
+  }
+  if (!crawl.hasCrawlData) {
+    console.log(`No persisted site crawl for "${project}". Run \`canonry technical-aeo run ${project}\` first.`);
+    return;
+  }
+  const lines = [
+    `Site crawl: ${crawl.complete ? "complete" : "partial"} (${crawl.runStatus ?? "unknown"})`,
+    `Root: ${crawl.rootUrl ?? "-"}`,
+    `Pages: ${crawl.counts.pagesFetched} fetched \xB7 ${crawl.counts.pagesDiscovered} discovered \xB7 ${crawl.counts.pagesEligible} eligible`,
+    `Links: ${crawl.counts.edges} internal/external observations \xB7 ${crawl.counts.findings} findings`,
+    `Dead links: ${formatDeadLinkState(crawl.deadLinks)}`
+  ];
+  if (crawl.termination) lines.push(`Stopped: ${crawl.termination}`);
+  console.log(lines.join("\n"));
+}
+async function technicalAeoSubgraph(project, opts) {
+  const res = await getClient27().getSiteHealthSubgraph(project, opts);
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (!res.hasCrawlData) {
+    console.log(`No persisted Site Health crawl for "${project}". Run \`canonry technical-aeo run ${project}\` first.`);
+    return;
+  }
+  if (res.state !== "ready") {
+    console.log(`Site Health subgraph details are unavailable for crawl ${res.runId ?? "-"}.`);
+    return;
+  }
+  const focus = res.focusUrl ?? res.focusNodeKey ?? "crawl root";
+  const totalQualifier = res.countAccuracy === "lower-bound" ? "at least " : "";
+  const lines = [
+    `Site Health subgraph: ${focus} (${res.hops} hop${res.hops === 1 ? "" : "s"})`,
+    `${res.nodes.length} of ${totalQualifier}${res.totalNodes} node(s) \xB7 ${res.edges.length} of ${totalQualifier}${res.totalEdges} edge(s)`,
+    `Crawl: ${res.complete ? "complete" : `partial (${res.termination ?? "incomplete"})`}`
+  ];
+  if (res.countAccuracy === "lower-bound") lines.push("Count accuracy: lower bound; traversal reached a cap, so totals and omissions may be higher.");
+  if (res.truncated) lines.push(`Truncated: at least ${res.omittedNodes} node(s) and ${res.omittedEdges} edge(s) omitted. Narrow or refocus the request.`);
+  if (!res.complete) lines.push(`Partial crawl: ${res.termination ?? "incomplete"}. Results describe only persisted observations.`);
+  console.log(lines.join("\n"));
+}
+async function technicalAeoPath(project, opts) {
+  const res = await getClient27().getSiteHealthPath(project, opts);
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.state === "no-crawl") {
+    console.log(`No persisted Site Health crawl for "${project}". Run \`canonry technical-aeo run ${project}\` first.`);
+    return;
+  }
+  if (res.state === "details-unavailable") {
+    console.log(`Site Health path details are unavailable for crawl ${res.runId ?? "-"}.`);
+    return;
+  }
+  if (res.state === "unreachable") {
+    const qualification = res.complete ? "" : ` in the partial crawl (${res.termination ?? "incomplete"}); this is not a site-wide conclusion`;
+    console.log(`No directed followable path found${qualification} to ${res.to?.url ?? "the requested destination"} within ${res.maxDepth} hop(s).`);
+    return;
+  }
+  if (res.state === "truncated") {
+    const qualification = res.complete ? "" : ` The crawl is partial (${res.termination ?? "incomplete"}), so this is not a site-wide conclusion.`;
+    console.log(`Path search reached its exploration cap before resolving ${res.to?.url ?? "the requested destination"}. Narrow the route or reduce max depth.${qualification}`);
+    return;
+  }
+  const lines = [res.nodes.map((node) => node.url).join("\n\u2192 ")];
+  if (!res.complete) lines.push("", `Partial crawl: ${res.termination ?? "incomplete"}. This path covers only persisted observations.`);
+  console.log(lines.join("\n"));
+}
+async function technicalAeoChanges(project, opts) {
+  const res = await getClient27().getSiteHealthChanges(project, opts);
+  if (opts.format === "jsonl") {
+    if (res.state === "ready") {
+      const { changes, ...header } = res;
+      emitJsonl([{ kind: "site-health-changes-header", ...header }]);
+      emitJsonl(changes.map((record) => ({ project, fromRunId: res.fromRunId, toRunId: res.toRunId, ...record })));
+    } else {
+      emitJsonl([{ kind: "site-health-changes-header", ...res }]);
+    }
+    return;
+  }
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.state === "unavailable") {
+    console.log(`Site Health changes unavailable: ${res.reason.replaceAll("-", " ")}.`);
+    return;
+  }
+  if (res.state === "incompatible") {
+    console.log(`Site Health changes unavailable: snapshots use incompatible ${res.mismatchedVersions.join(", ")} versions.`);
+    return;
+  }
+  const lines = [
+    `Site Health changes: ${res.fromRunId} \u2192 ${res.toRunId}`,
+    `Filters: ${res.filters.scope} \xB7 ${res.filters.change}`
+  ];
+  if (res.summaryState === "exact" && res.summary !== null && res.total !== null) {
+    lines.push(`Pages: +${res.summary.pages.added} / -${res.summary.pages.removed} / ${res.summary.pages.changed} changed`);
+    lines.push(`Links: +${res.summary.links.added} / -${res.summary.links.removed} / ${res.summary.links.changed}`);
+    lines.push(`${res.changes.length} of ${res.total} change(s)${res.nextCursor ? " (more available)" : ""}`);
+  } else {
+    lines.push(`Summary: omitted on continuation; ${res.changes.length} returned change(s)${res.nextCursor ? " (more available)" : ""}`);
+  }
+  if (res.changes.length > 0) {
+    lines.push("", "Changes:");
+    for (const record of res.changes) lines.push(`  ${formatSiteHealthChangeRecord(record)}`);
+  }
+  if (res.nextCursor) lines.push(`Next cursor: ${res.nextCursor}`);
+  console.log(lines.join("\n"));
+}
+function formatSiteHealthChangeRecord(record) {
+  const target = record.entity === "page" ? record.after?.url ?? record.before?.url ?? record.key : (() => {
+    const edge = record.after ?? record.before;
+    return edge ? `${edge.sourceUrl} \u2192 ${edge.targetUrl}` : record.key;
+  })();
+  const fields = record.changedFields.length > 0 ? ` (${record.changedFields.join(", ")})` : "";
+  return `${record.entity} ${record.change}: ${target}${fields}`;
+}
+async function technicalAeoCrawlPages(project, opts) {
+  const res = await getClient27().getTechnicalAeoCrawlPages(project, opts);
+  if (opts.format === "jsonl") {
+    emitJsonl([{
+      kind: "technical-aeo-crawl-pages-header",
+      project,
+      runId: res.runId,
+      total: res.total,
+      nextCursor: res.nextCursor
+    }]);
+    emitJsonl(res.pages.map((page) => ({ project, runId: res.runId, ...page })));
+    return;
+  }
+  if (opts.format === "json") {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.pages.length === 0) {
+    console.log(`No persisted crawl pages for "${project}".`);
+    return;
+  }
+  const lines = [`${res.pages.length} of ${res.total} crawl page(s)${res.nextCursor ? " (more available)" : ""}:`, ""];
+  lines.push(`${"Depth".padStart(5)}  ${"Score".padStart(5)}  ${"Indexability".padEnd(15)}  URL`);
+  for (const page of res.pages) {
+    lines.push(`${String(page.depth ?? "-").padStart(5)}  ${String(page.auditScore ?? "-").padStart(5)}  ${page.indexabilityState.slice(0, 15).padEnd(15)}  ${page.url}`);
+  }
+  if (res.nextCursor) lines.push(`
+Next cursor: ${res.nextCursor}`);
+  console.log(lines.join("\n"));
+}
+async function technicalAeoPageAudit(project, opts) {
+  const res = await getClient27().getTechnicalAeoPageAudit(project, {
+    runId: opts.runId,
+    nodeKey: opts.nodeKey,
+    url: opts.url
+  });
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.state === "no-crawl") {
+    console.log(`No persisted Site Health crawl for "${project}". Run \`canonry technical-aeo run ${project}\` first.`);
+    return;
+  }
+  const provenance = [`Run: ${res.runId} \xB7 ${res.complete ? "complete" : "partial"}`];
+  if (!res.complete) provenance.push(`Partial crawl: ${res.termination ?? "termination reason unavailable"}`);
+  if (res.state === "details-unavailable") {
+    console.log([
+      "Page audit details are unavailable for this retained crawl.",
+      ...provenance
+    ].join("\n"));
+    return;
+  }
+  if (res.state === "not-found") {
+    console.log([
+      "The selected page was not found in this crawl.",
+      ...provenance
+    ].join("\n"));
+    return;
+  }
+  const lines = [
+    `Page audit: ${res.auditScore == null ? "not scored" : `${res.auditScore}/100`} \xB7 ${res.url}`,
+    ...provenance
+  ];
+  if (res.state === "not-audited") {
+    lines.push(`Audit evidence unavailable: page state is ${res.auditState}.`);
+    console.log(lines.join("\n"));
+    return;
+  }
+  if (res.evidenceState === "scores-only") {
+    lines.push("Evidence: scores only; this historical row predates persisted finding prose.");
+  }
+  if (res.criticalDefects.length > 0) {
+    lines.push("", "Score-independent defects:");
+    for (const defect of res.criticalDefects) {
+      lines.push(`  [${defect.severity}] [${defect.id}] ${defect.detail}`);
+      lines.push(`    Fix: ${defect.recommendation}`);
+    }
+  }
+  if (res.factors.length > 0) {
+    lines.push("", "Factors:");
+    for (const factor of res.factors) {
+      lines.push(`  ${factor.name}: ${factor.score}/100 (${factor.status})`);
+      for (const finding of factor.findings) lines.push(`    [${finding.code}] ${finding.message}`);
+      for (const recommendation of factor.recommendations) lines.push(`    Fix: ${recommendation}`);
+    }
+  }
+  console.log(lines.join("\n"));
+}
+async function technicalAeoStructure(project, opts) {
+  const res = await getClient27().getTechnicalAeoStructure(project, opts);
+  if (opts.format === "jsonl") {
+    emitJsonl([{
+      kind: "technical-aeo-structure-header",
+      project,
+      runId: res.runId,
+      parentPath: res.parentPath,
+      returned: res.children.length,
+      nextCursor: res.nextCursor
+    }]);
+    emitJsonl(res.children.map((child) => ({ project, runId: res.runId, parentPath: res.parentPath, ...child })));
+    return;
+  }
+  if (opts.format === "json") {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.children.length === 0) {
+    console.log(`No crawl structure below ${res.parentPath} for "${project}".`);
+    return;
+  }
+  const lines = [`${res.children.length} child path(s) below ${res.parentPath}${res.nextCursor ? " (more available)" : ""}:`, ""];
+  for (const child of res.children) {
+    lines.push(`${String(child.pageCount).padStart(5)} pages  ${String(child.inventoryEligibleCount).padStart(5)} eligible  ${child.path}`);
+  }
+  if (res.nextCursor) lines.push(`
+Next cursor: ${res.nextCursor}`);
+  console.log(lines.join("\n"));
+}
+async function technicalAeoInternalLinks(project, opts) {
+  const res = await getClient27().getTechnicalAeoInternalLinks(project, opts);
+  if (opts.format === "jsonl") {
+    emitJsonl([{
+      kind: "technical-aeo-internal-links-header",
+      project,
+      runId: res.runId,
+      total: res.total,
+      nextCursor: res.nextCursor
+    }]);
+    emitJsonl(res.edges.map((edge) => ({ project, runId: res.runId, ...edge })));
+    return;
+  }
+  if (opts.format === "json") {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.edges.length === 0) {
+    console.log(`No persisted internal links for "${project}".`);
+    return;
+  }
+  const lines = [`${res.edges.length} of ${res.total} internal link(s)${res.nextCursor ? " (more available)" : ""}:`, ""];
+  for (const edge of res.edges) {
+    lines.push(`${edge.followable ? "follow" : "nofollow"} \xD7${edge.occurrences}  ${edge.sourceUrl} \u2192 ${edge.targetUrl}`);
+  }
+  if (res.nextCursor) lines.push(`
+Next cursor: ${res.nextCursor}`);
+  console.log(lines.join("\n"));
+}
+async function technicalAeoLinkNeighbors(project, opts) {
+  const res = await getClient27().getTechnicalAeoInternalLinkNeighbors(project, opts);
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  const title = res.url ?? res.nodeKey ?? "page";
+  const lines = [`Internal links for ${title}:`, "", "Inbound:"];
+  for (const edge of res.inbound) lines.push(`  ${edge.sourceUrl} \u2192 ${edge.targetUrl}`);
+  if (res.inbound.length === 0) lines.push("  (none)");
+  if (res.inboundTruncated) lines.push("  (truncated)");
+  lines.push("", "Outbound:");
+  for (const edge of res.outbound) lines.push(`  ${edge.sourceUrl} \u2192 ${edge.targetUrl}`);
+  if (res.outbound.length === 0) lines.push("  (none)");
+  if (res.outboundTruncated) lines.push("  (truncated)");
+  console.log(lines.join("\n"));
+}
+async function technicalAeoDeadLinks(project, opts) {
+  const res = await getClient27().getTechnicalAeoDeadLinks(project, opts);
+  if (opts.format === "jsonl") {
+    if ("deadLinks" in res) {
+      const { deadLinks, ...header } = res;
+      emitJsonl([{ kind: "technical-aeo-dead-links-header", ...header }]);
+      emitJsonl(deadLinks.map((finding) => ({ project, runId: res.runId, state: res.state, ...finding })));
+    } else {
+      emitJsonl([{ kind: "technical-aeo-dead-links-header", ...res }]);
+    }
+    return;
+  }
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  if (res.state === "disabled") {
+    console.log(`Dead-link checks were disabled for crawl ${res.runId}. Re-run with \`--check-dead-links\` to enable them.`);
+    return;
+  }
+  if (res.state === "unavailable") {
+    console.log(`No dead-link check is available for "${project}".`);
+    return;
+  }
+  const lines = [`Dead links: ${res.found} found from ${res.checked} checked (${res.state})`];
+  for (const finding of res.deadLinks) lines.push(`${finding.sourceUrl ?? "-"} \u2192 ${finding.targetUrl ?? "-"}`);
+  if (res.nextCursor) lines.push(`Next cursor: ${res.nextCursor}`);
+  console.log(lines.join("\n"));
+}
+function formatDeadLinkState(value) {
+  if (value.state === "disabled") return "disabled (opt in with --check-dead-links)";
+  if (value.state === "unavailable") return "unavailable";
+  return `${value.found ?? 0} found / ${value.checked ?? 0} checked (${value.state})`;
+}
 async function technicalAeoRun(project, opts) {
   const client = getClient27();
   const { runId, status } = await client.triggerSiteAudit(project, {
     sitemapUrl: opts.sitemapUrl,
-    limit: opts.limit
+    limit: opts.limit,
+    maxPages: opts.maxPages,
+    maxEdges: opts.maxEdges,
+    maxDepth: opts.maxDepth,
+    // Explicit opt-in: absence and false are both intentionally disabled.
+    checkDeadLinks: opts.checkDeadLinks === true
   });
   if (!opts.wait) {
     if (isMachineFormat(opts.format)) {
@@ -13865,7 +14193,24 @@ async function technicalAeoRun(project, opts) {
 }
 
 // src/cli-commands/technical-aeo.ts
-var TECHNICAL_AEO_CLI_COMMANDS = [
+function parseOptionalBoolean(input, key, config) {
+  const value = getString(input.values, key);
+  if (value === void 0) return void 0;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw usageError(`Error: --${key} must be true or false
+Usage: ${config.usage}`, {
+    message: `--${key} must be true or false`,
+    details: { command: config.command, usage: config.usage, option: key, value }
+  });
+}
+function isSiteHealthScope(value) {
+  return value === "all" || value === "pages" || value === "links";
+}
+function isSiteHealthChange(value) {
+  return value === "all" || value === "added" || value === "removed" || value === "changed";
+}
+var TECHNICAL_AEO_CLI_COMMANDS_BASE = [
   {
     path: ["technical-aeo", "score"],
     usage: "canonry technical-aeo score <project> [--run-id <id>] [--format json]",
@@ -13927,14 +14272,18 @@ var TECHNICAL_AEO_CLI_COMMANDS = [
   },
   {
     path: ["technical-aeo", "run"],
-    usage: "canonry technical-aeo run <project> [--sitemap-url <url>] [--limit <n>] [--wait] [--format json]",
+    usage: "canonry technical-aeo run <project> [--sitemap-url <url>] [--max-pages <n>] [--max-edges <n>] [--max-depth <n>] [--check-dead-links] [--wait] [--format json]",
     options: {
       "sitemap-url": stringOption(),
       limit: stringOption(),
+      "max-pages": stringOption(),
+      "max-edges": stringOption(),
+      "max-depth": stringOption(),
+      "check-dead-links": { type: "boolean", default: false },
       wait: { type: "boolean", default: false }
     },
     run: async (input) => {
-      const usage = "canonry technical-aeo run <project> [--sitemap-url <url>] [--limit <n>] [--wait] [--format json]";
+      const usage = "canonry technical-aeo run <project> [--sitemap-url <url>] [--max-pages <n>] [--max-edges <n>] [--max-depth <n>] [--check-dead-links] [--wait] [--format json]";
       const project = requireProject(input, "technical-aeo.run", usage);
       await technicalAeoRun(project, {
         sitemapUrl: getString(input.values, "sitemap-url"),
@@ -13943,12 +14292,397 @@ var TECHNICAL_AEO_CLI_COMMANDS = [
           usage,
           message: "--limit must be an integer"
         }),
+        maxPages: parseIntegerOption(input, "max-pages", {
+          command: "technical-aeo.run",
+          usage,
+          message: "--max-pages must be an integer"
+        }),
+        maxEdges: parseIntegerOption(input, "max-edges", {
+          command: "technical-aeo.run",
+          usage,
+          message: "--max-edges must be an integer"
+        }),
+        maxDepth: parseIntegerOption(input, "max-depth", {
+          command: "technical-aeo.run",
+          usage,
+          message: "--max-depth must be an integer"
+        }),
+        checkDeadLinks: getBoolean(input.values, "check-dead-links"),
         wait: getBoolean(input.values, "wait"),
         format: input.format
       });
     }
+  },
+  {
+    path: ["technical-aeo", "crawl"],
+    usage: "canonry technical-aeo crawl <project> [--run-id <id>] [--format json]",
+    options: { "run-id": stringOption() },
+    run: async (input) => {
+      const usage = "canonry technical-aeo crawl <project> [--run-id <id>] [--format json]";
+      const project = requireProject(input, "technical-aeo.crawl", usage);
+      await technicalAeoCrawl(project, { runId: getString(input.values, "run-id"), format: input.format });
+    }
+  },
+  {
+    path: ["technical-aeo", "subgraph"],
+    usage: "canonry technical-aeo subgraph <project> [--run-id <id>] [--node-key <key>|--url <url>] [--hops <n>] [--max-nodes <n>] [--max-edges <n>] [--format json]",
+    options: {
+      "run-id": stringOption(),
+      "node-key": stringOption(),
+      url: stringOption(),
+      hops: stringOption(),
+      "max-nodes": stringOption(),
+      "max-edges": stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry technical-aeo subgraph <project> [--run-id <id>] [--node-key <key>|--url <url>] [--hops <n>] [--max-nodes <n>] [--max-edges <n>] [--format json]";
+      const project = requireProject(input, "technical-aeo.subgraph", usage);
+      const nodeKey = getString(input.values, "node-key");
+      const url = getString(input.values, "url");
+      if (nodeKey && url) {
+        throw usageError(`Error: --node-key and --url cannot be combined
+Usage: ${usage}`, {
+          message: "--node-key and --url cannot be combined",
+          details: { command: "technical-aeo.subgraph", usage }
+        });
+      }
+      await technicalAeoSubgraph(project, {
+        runId: getString(input.values, "run-id"),
+        nodeKey,
+        url,
+        hops: parseIntegerOption(input, "hops", { command: "technical-aeo.subgraph", usage, message: "--hops must be an integer" }),
+        maxNodes: parseIntegerOption(input, "max-nodes", { command: "technical-aeo.subgraph", usage, message: "--max-nodes must be an integer" }),
+        maxEdges: parseIntegerOption(input, "max-edges", { command: "technical-aeo.subgraph", usage, message: "--max-edges must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "path"],
+    usage: "canonry technical-aeo path <project> (--to-node-key <key>|--to-url <url>) [--run-id <id>] [--from-node-key <key>|--from-url <url>] [--max-depth <n>] [--format json]",
+    options: {
+      "run-id": stringOption(),
+      "from-node-key": stringOption(),
+      "from-url": stringOption(),
+      "to-node-key": stringOption(),
+      "to-url": stringOption(),
+      "max-depth": stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry technical-aeo path <project> (--to-node-key <key>|--to-url <url>) [--run-id <id>] [--from-node-key <key>|--from-url <url>] [--max-depth <n>] [--format json]";
+      const project = requireProject(input, "technical-aeo.path", usage);
+      const fromNodeKey = getString(input.values, "from-node-key");
+      const fromUrl = getString(input.values, "from-url");
+      const toNodeKey = getString(input.values, "to-node-key");
+      const toUrl = getString(input.values, "to-url");
+      if (!toNodeKey && !toUrl) {
+        throw usageError(`Error: --to-node-key or --to-url is required
+Usage: ${usage}`, {
+          message: "--to-node-key or --to-url is required",
+          details: { command: "technical-aeo.path", usage }
+        });
+      }
+      if (fromNodeKey && fromUrl || toNodeKey && toUrl) {
+        throw usageError(`Error: node-key and URL selectors cannot be combined
+Usage: ${usage}`, {
+          message: "node-key and URL selectors cannot be combined",
+          details: { command: "technical-aeo.path", usage }
+        });
+      }
+      await technicalAeoPath(project, {
+        runId: getString(input.values, "run-id"),
+        fromNodeKey,
+        fromUrl,
+        toNodeKey,
+        toUrl,
+        maxDepth: parseIntegerOption(input, "max-depth", { command: "technical-aeo.path", usage, message: "--max-depth must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "changes"],
+    usage: "canonry technical-aeo changes <project> [--from-run-id <id>] [--to-run-id <id>] [--scope all|pages|links] [--change all|added|removed|changed] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]",
+    options: {
+      "from-run-id": stringOption(),
+      "to-run-id": stringOption(),
+      scope: stringOption(),
+      change: stringOption(),
+      cursor: stringOption(),
+      limit: stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry technical-aeo changes <project> [--from-run-id <id>] [--to-run-id <id>] [--scope all|pages|links] [--change all|added|removed|changed] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]";
+      const project = requireProject(input, "technical-aeo.changes", usage);
+      const fromRunId = getString(input.values, "from-run-id");
+      const toRunId = getString(input.values, "to-run-id");
+      const scope = getString(input.values, "scope");
+      const change = getString(input.values, "change");
+      if (scope !== void 0 && !isSiteHealthScope(scope)) {
+        throw usageError(`Error: --scope must be all, pages, or links
+Usage: ${usage}`, {
+          message: "--scope must be all, pages, or links",
+          details: { command: "technical-aeo.changes", usage, option: "scope", value: scope }
+        });
+      }
+      if (change !== void 0 && !isSiteHealthChange(change)) {
+        throw usageError(`Error: --change must be all, added, removed, or changed
+Usage: ${usage}`, {
+          message: "--change must be all, added, removed, or changed",
+          details: { command: "technical-aeo.changes", usage, option: "change", value: change }
+        });
+      }
+      await technicalAeoChanges(project, {
+        fromRunId,
+        toRunId,
+        scope,
+        change,
+        cursor: getString(input.values, "cursor"),
+        limit: parseIntegerOption(input, "limit", { command: "technical-aeo.changes", usage, message: "--limit must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "crawl-pages"],
+    usage: "canonry technical-aeo crawl-pages <project> [--run-id <id>] [--inventory-eligible true|false] [--fetch-state <state>] [--indexability-state <state>] [--audit-state <state>] [--sort url|path|score-asc|score-desc] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]",
+    options: {
+      "run-id": stringOption(),
+      "inventory-eligible": stringOption(),
+      "fetch-state": stringOption(),
+      "indexability-state": stringOption(),
+      "audit-state": stringOption(),
+      sort: stringOption(),
+      cursor: stringOption(),
+      limit: stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry technical-aeo crawl-pages <project> [--run-id <id>] [--inventory-eligible true|false] [--fetch-state <state>] [--indexability-state <state>] [--audit-state <state>] [--sort url|path|score-asc|score-desc] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]";
+      const project = requireProject(input, "technical-aeo.crawl-pages", usage);
+      const sort = getString(input.values, "sort");
+      if (sort !== void 0 && !["url", "path", "score-asc", "score-desc"].includes(sort)) {
+        throw usageError(`Error: --sort must be url, path, score-asc, or score-desc
+Usage: ${usage}`, {
+          message: "--sort must be url, path, score-asc, or score-desc",
+          details: { command: "technical-aeo.crawl-pages", usage, option: "sort", value: sort }
+        });
+      }
+      await technicalAeoCrawlPages(project, {
+        runId: getString(input.values, "run-id"),
+        inventoryEligible: parseOptionalBoolean(input, "inventory-eligible", { command: "technical-aeo.crawl-pages", usage }),
+        fetchState: getString(input.values, "fetch-state"),
+        indexabilityState: getString(input.values, "indexability-state"),
+        auditState: getString(input.values, "audit-state"),
+        sort,
+        cursor: getString(input.values, "cursor"),
+        limit: parseIntegerOption(input, "limit", { command: "technical-aeo.crawl-pages", usage, message: "--limit must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "page-audit"],
+    usage: "canonry technical-aeo page-audit <project> (--node-key <key>|--url <url>) [--run-id <id>] [--format json]",
+    options: { "run-id": stringOption(), "node-key": stringOption(), url: stringOption() },
+    run: async (input) => {
+      const usage = "canonry technical-aeo page-audit <project> (--node-key <key>|--url <url>) [--run-id <id>] [--format json]";
+      const project = requireProject(input, "technical-aeo.page-audit", usage);
+      const nodeKey = getString(input.values, "node-key");
+      const url = getString(input.values, "url");
+      if (!nodeKey && !url) {
+        throw usageError(`Error: --node-key or --url is required
+Usage: ${usage}`, {
+          message: "--node-key or --url is required",
+          details: { command: "technical-aeo.page-audit", usage }
+        });
+      }
+      if (nodeKey && url) {
+        throw usageError(`Error: --node-key and --url cannot be combined
+Usage: ${usage}`, {
+          message: "--node-key and --url cannot be combined",
+          details: { command: "technical-aeo.page-audit", usage }
+        });
+      }
+      await technicalAeoPageAudit(project, {
+        runId: getString(input.values, "run-id"),
+        nodeKey,
+        url,
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "structure"],
+    usage: "canonry technical-aeo structure <project> [--run-id <id>] [--parent-path <path>] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]",
+    options: { "run-id": stringOption(), "parent-path": stringOption(), cursor: stringOption(), limit: stringOption() },
+    run: async (input) => {
+      const usage = "canonry technical-aeo structure <project> [--run-id <id>] [--parent-path <path>] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]";
+      const project = requireProject(input, "technical-aeo.structure", usage);
+      await technicalAeoStructure(project, {
+        runId: getString(input.values, "run-id"),
+        parentPath: getString(input.values, "parent-path"),
+        cursor: getString(input.values, "cursor"),
+        limit: parseIntegerOption(input, "limit", { command: "technical-aeo.structure", usage, message: "--limit must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "links"],
+    usage: "canonry technical-aeo links <project> [--run-id <id>] [--source-url <url>] [--target-url <url>] [--followable|--nofollow] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]",
+    options: {
+      "run-id": stringOption(),
+      "source-url": stringOption(),
+      "target-url": stringOption(),
+      followable: { type: "boolean", default: false },
+      nofollow: { type: "boolean", default: false },
+      cursor: stringOption(),
+      limit: stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry technical-aeo links <project> [--run-id <id>] [--source-url <url>] [--target-url <url>] [--followable|--nofollow] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]";
+      const project = requireProject(input, "technical-aeo.links", usage);
+      const followable = getBoolean(input.values, "followable");
+      const nofollow = getBoolean(input.values, "nofollow");
+      if (followable && nofollow) {
+        throw usageError(`Error: --followable and --nofollow cannot be combined
+Usage: ${usage}`, {
+          message: "--followable and --nofollow cannot be combined",
+          details: { command: "technical-aeo.links", usage }
+        });
+      }
+      await technicalAeoInternalLinks(project, {
+        runId: getString(input.values, "run-id"),
+        sourceUrl: getString(input.values, "source-url"),
+        targetUrl: getString(input.values, "target-url"),
+        followable: followable ? true : nofollow ? false : void 0,
+        cursor: getString(input.values, "cursor"),
+        limit: parseIntegerOption(input, "limit", { command: "technical-aeo.links", usage, message: "--limit must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "links", "neighbors"],
+    usage: "canonry technical-aeo links neighbors <project> (--node-key <key>|--url <url>) [--run-id <id>] [--limit <n>] [--format json]",
+    options: { "run-id": stringOption(), "node-key": stringOption(), url: stringOption(), limit: stringOption() },
+    run: async (input) => {
+      const usage = "canonry technical-aeo links neighbors <project> (--node-key <key>|--url <url>) [--run-id <id>] [--limit <n>] [--format json]";
+      const project = requireProject(input, "technical-aeo.links.neighbors", usage);
+      const nodeKey = getString(input.values, "node-key");
+      const url = getString(input.values, "url");
+      if (!nodeKey && !url) {
+        throw usageError(`Error: --node-key or --url is required
+Usage: ${usage}`, {
+          message: "--node-key or --url is required",
+          details: { command: "technical-aeo.links.neighbors", usage }
+        });
+      }
+      await technicalAeoLinkNeighbors(project, {
+        runId: getString(input.values, "run-id"),
+        nodeKey,
+        url,
+        limit: parseIntegerOption(input, "limit", { command: "technical-aeo.links.neighbors", usage, message: "--limit must be an integer" }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["technical-aeo", "dead-links"],
+    usage: "canonry technical-aeo dead-links <project> [--run-id <id>] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]",
+    options: { "run-id": stringOption(), cursor: stringOption(), limit: stringOption() },
+    run: async (input) => {
+      const usage = "canonry technical-aeo dead-links <project> [--run-id <id>] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]";
+      const project = requireProject(input, "technical-aeo.dead-links", usage);
+      await technicalAeoDeadLinks(project, {
+        runId: getString(input.values, "run-id"),
+        cursor: getString(input.values, "cursor"),
+        limit: parseIntegerOption(input, "limit", { command: "technical-aeo.dead-links", usage, message: "--limit must be an integer" }),
+        format: input.format
+      });
+    }
   }
 ];
+function siteHealthAlias(sourcePath, path12, usage) {
+  const source = TECHNICAL_AEO_CLI_COMMANDS_BASE.find(
+    (candidate) => candidate.path.join(" ") === sourcePath.join(" ")
+  );
+  if (!source) throw new Error(`Missing Site Health compatibility source: ${sourcePath.join(" ")}`);
+  return {
+    ...source,
+    path: path12,
+    usage,
+    run: async (input) => {
+      try {
+        await source.run(input);
+      } catch (error) {
+        if (!(error instanceof CliError) || error.code !== "CLI_USAGE_ERROR") throw error;
+        const firstLine = error.displayMessage?.split("\n", 1)[0] ?? `Error: ${error.message}`;
+        throw usageError(`${firstLine}
+Usage: ${usage}`, {
+          message: error.message,
+          details: { ...error.details, command: path12.join("."), usage }
+        });
+      }
+    }
+  };
+}
+var SITE_HEALTH_COMPATIBILITY_COMMANDS = [
+  siteHealthAlias(
+    ["technical-aeo", "crawl"],
+    ["site-health", "overview"],
+    "canonry site-health overview <project> [--run-id <id>] [--format json]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "crawl-pages"],
+    ["site-health", "pages"],
+    "canonry site-health pages <project> [--run-id <id>] [--inventory-eligible true|false] [--fetch-state <state>] [--indexability-state <state>] [--audit-state <state>] [--sort url|path|score-asc|score-desc] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "page-audit"],
+    ["site-health", "page-audit"],
+    "canonry site-health page-audit <project> (--node-key <key>|--url <url>) [--run-id <id>] [--format json]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "structure"],
+    ["site-health", "structure"],
+    "canonry site-health structure <project> [--run-id <id>] [--parent-path <path>] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "links"],
+    ["site-health", "links"],
+    "canonry site-health links <project> [--run-id <id>] [--source-url <url>] [--target-url <url>] [--followable|--nofollow] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "links", "neighbors"],
+    ["site-health", "neighbors"],
+    "canonry site-health neighbors <project> (--node-key <key>|--url <url>) [--run-id <id>] [--limit <n>] [--format json]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "dead-links"],
+    ["site-health", "dead-links"],
+    "canonry site-health dead-links <project> [--run-id <id>] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "subgraph"],
+    ["site-health", "subgraph"],
+    "canonry site-health subgraph <project> [--run-id <id>] [--node-key <key>|--url <url>] [--hops <n>] [--max-nodes <n>] [--max-edges <n>] [--format json]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "path"],
+    ["site-health", "path"],
+    "canonry site-health path <project> (--to-node-key <key>|--to-url <url>) [--run-id <id>] [--from-node-key <key>|--from-url <url>] [--max-depth <n>] [--format json]"
+  ),
+  siteHealthAlias(
+    ["technical-aeo", "changes"],
+    ["site-health", "changes"],
+    "canonry site-health changes <project> [--from-run-id <id>] [--to-run-id <id>] [--scope all|pages|links] [--change all|added|removed|changed] [--cursor <cursor>] [--limit <n>] [--format json|jsonl]"
+  )
+];
+var TECHNICAL_AEO_CLI_COMMANDS = [
+  ...TECHNICAL_AEO_CLI_COMMANDS_BASE,
+  ...SITE_HEALTH_COMPATIBILITY_COMMANDS
+];
 
 // src/commands/visibility-stats.ts
 async function showVisibilityStats(project, opts) {