@ainyc/canonry 4.64.1 → 4.67.0

package/assets/agent-workspace/skills/canonry/references/canonry-cli.md

@@ -524,4 +524,33 @@ cnry agent detach <project> --format json              # JSON output
 
 ## Output Formats
 
-Most commands support `--format json` for machine-readable output.
+Every command takes `--format`:
+
+- **`text`** (default) — human-readable, decorated. Not a stable parse target.
+- **`json`** — one pretty-printed JSON document (the full envelope). Stable contract.
+- **`jsonl`** — newline-delimited JSON: the command's **primary collection**, one self-contained record per line. The agent-friendly machine format — no envelope key to guess (`.checks` vs `.results` vs `.rows`), no `jq` flattening, greppable line by line.
+
+`jsonl` is supported by every **collection** command — one whose primary output is a list: `insights`, `runs`, `evidence`, `history`, `query/keyword/competitor list`, `notify list/events`, `google` reads (`performance`, `performance-daily`, `inspections`, `coverage-history`, `deindexed`, `status`, `properties`, `list-sitemaps`), `bing` reads (`coverage-history`, `inspections`, `performance`, `sites`), `ga` reads (`ai-referral-history`, `social-referral-history`, `session-history`, `coverage`), `traffic events/sources/status`, `discover list/show`, `content targets/sources/gaps`, `backlinks list/releases`, `project list/locations`, `agent memory list`, `agent providers`, and `doctor`.
+
+Each `jsonl` line re-injects the envelope context it would otherwise lose, so a line lifted out still self-describes:
+
+- project-scoped lists stamp `{ "project": "<name>", …row }`;
+- `ga *-history` also stamps `window`; `traffic events` stamps `windowStart`/`windowEnd`; `backlinks list` stamps `release`/`targetDomain`; `discover show` stamps `sessionId`; `content targets` stamps `latestRunId`; `project locations` stamps `isDefault`;
+- global lists whose rows already self-identify (`project list`, `notify events`, `backlinks releases`) emit bare rows.
+
+Empty collection → **no output** (the exit code still conveys success, so "no records" stays distinct from "failure"). On failure a command prints its records (if any), then exits non-zero — branch on the **exit code**, never on parsing stderr. JSON field names and the `{ "error": { "code", "message" } }` envelope are a public contract.
+
+**Composite** commands return a single aggregate object (not a list), so there is nothing to stream — on them `--format jsonl` **degrades to the same JSON document** as `--format json`; it never falls through to decorated human text. So `--format jsonl` is safe to pass to *any* command: collection commands stream their records, every other command emits its JSON document. Composite shapes are below.
+
+## Output schema per command
+
+Compact reference for the composite / keyed commands agents read most (shapes can drift — the linked DTO source file is the source of truth; collection commands simply emit their primary array, see each command's own section above).
+
+| Command | JSON output shape (top-level keys → DTO) | `jsonl` |
+|---|---|---|
+| `cnry doctor [--project p] [--all]` | `{ scope, project, generatedAt, durationMs, summary{total,ok,warn,fail,skipped}, checks[] }` — `DoctorReportDto` @ `contracts/doctor.ts`. `checks[]` = `CheckResultDto{ id, category, scope, title, status(ok\|warn\|fail\|skipped), code, summary, remediation?, details?, durationMs }`. With `--all`: an object keyed by `__global__` + each project name, each value a full report. | ✅ one check / line as `{project, …check}`; still exits non-zero if any `fail` |
+| `cnry analytics <p> [--feature metrics\|gaps\|sources] [--window 7d\|30d\|90d\|all]` | Object **keyed by feature**: `{ metrics?, gaps?, sources? }` (all three present with no `--feature`; one with `--feature X`). `metrics`=`BrandMetricsDto{ window, buckets[], overall, byProvider, trend, mentionTrend, queryChanges[] }`; `gaps`=`GapAnalysisDto{ cited[], gap[], uncited[], mentionedQueries[], mentionGap[], notMentioned[], runId, window }` (each `[]`=`GapQuery`); `sources`=`SourceBreakdownDto{ overall[], byQuery, runId, window }`. @ `contracts/analytics.ts` | → degrades to the `json` document |
+| `cnry google coverage <p>` (index coverage) | `{ summary{total,indexed,notIndexed,deindexed,percentage}, lastInspectedAt, lastSyncedAt, indexed[], notIndexed[], deindexed[], reasonGroups[] }` — `GscCoverageSummaryDto` @ `contracts/google.ts`. `indexed[]`/`notIndexed[]`=`GscUrlInspectionDto`, `deindexed[]`=`GscDeindexedRowDto`. | → degrades to the `json` document. The single-array reads `google inspections` / `coverage-history` / `deindexed` **stream** `jsonl`. |
+| `cnry ga traffic <p> [--window …]` | Object summary — `GA4TrafficSummaryDto` / `GaTrafficResponse` @ `contracts/ga.ts`: `{ totalSessions, totalOrganicSessions, totalDirectSessions, totalUsers, aiSessionsDeduped, aiUsersDeduped, aiSessionsBySession, aiUsersBySession, socialSessions, socialUsers, channelBreakdown{organic,social,direct,ai,other→{sessions,sharePct,sharePctDisplay}}, *SharePct (+ `*Display`), topPages[], aiReferrals[], aiReferralLandingPages[], socialReferrals[], lastSyncedAt, periodStart, periodEnd }`. | → degrades to the `json` document |
+| `cnry ga attribution <p> [--trend]` | Object — a **renamed projection** of `GaTrafficResponse` (⚠️ field names differ from the DTO): `aiSessions`(←`aiSessionsDeduped`), `organicSessions`(←`totalOrganicSessions`), `directSessions`(←`totalDirectSessions`), plus `totalSessions, totalUsers, aiUsers, aiSessionsBySession, aiUsersBySession, socialSessions, socialUsers, {ai,social,organic,direct}SharePct (+ `*Display`), otherSessions, otherSharePct, channelBreakdown, aiReferrals[], aiReferralLandingPages[], socialReferrals[], periodStart, periodEnd`. With `--trend`: drops `periodStart/End`, adds `trend` (`GaAttributionTrendResponse`). Assembled inline in `commands/ga.ts`. | → degrades to the `json` document |
+| `cnry gbp summary <p> [--location …]` | `{ scope{locationName,locationCount}, performance{totals,recent7d,prior7d,deltaPct} (metric-keyed maps; keys are raw `BUSINESS_*` / `WEBSITE_CLICKS` tokens — label via `formatGbpMetricLabel`), freshness{dataThroughDate,latestStoredDate,pendingDays}, timeseries[], keywords{total,thresholdedCount,thresholdedPct}, placeActions{total,hasReservationCta,hasBookingCta,hasDirectMerchantCta}, lodging{lodgingLocationCount,populatedLodgingCount,emptyLodgingCount} }` — `GbpSummaryDto` @ `contracts/gbp.ts`. `timeseries[]`=`{date,pending,metrics}`. | → degrades to the `json` document |

package/dist/{chunk-MDNDIBUM.js → chunk-4V3V4MFF.js}

@@ -5,10 +5,11 @@ import {
   canonryMcpTools,
   configExists,
   getConfigPath,
+  isMachineFormat,
   loadConfig,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-64IDABSF.js";
+} from "./chunk-RQCVITY4.js";
 import {
   CC_CACHE_DIR,
   DUCKDB_SPEC,
@@ -5296,7 +5297,7 @@ async function backfillAnswerVisibilityCommand(opts) {
     result.dryRun = true;
     result.wouldUpdate = wouldUpdate;
   }
-  if (opts?.format === "json") {
+  if (isMachineFormat(opts?.format)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
@@ -5366,7 +5367,7 @@ async function backfillNormalizedPathsCommand(opts) {
         updated: 0,
         unchanged: 0
       };
-      if (opts?.format === "json") {
+      if (isMachineFormat(opts?.format)) {
         console.log(JSON.stringify(result2, null, 2));
         return;
       }
@@ -5382,7 +5383,7 @@ async function backfillNormalizedPathsCommand(opts) {
     updated,
     unchanged
   };
-  if (opts?.format === "json") {
+  if (isMachineFormat(opts?.format)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
@@ -5438,7 +5439,7 @@ async function backfillAiReferralPathsCommand(opts) {
         updated: 0,
         unchanged: 0
       };
-      if (opts?.format === "json") {
+      if (isMachineFormat(opts?.format)) {
         console.log(JSON.stringify(result2, null, 2));
         return;
       }
@@ -5454,7 +5455,7 @@ async function backfillAiReferralPathsCommand(opts) {
     updated,
     unchanged
   };
-  if (opts?.format === "json") {
+  if (isMachineFormat(opts?.format)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
@@ -5579,7 +5580,7 @@ async function backfillAnswerMentionsCommand(opts) {
     result.dryRun = true;
     result.wouldUpdate = wouldUpdate;
   }
-  if (opts?.format === "json") {
+  if (isMachineFormat(opts?.format)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
@@ -5621,7 +5622,7 @@ async function backfillInsightsCommand(project, opts) {
   const db = createClient(config.database);
   migrate(db);
   const service = new IntelligenceService2(db);
-  const isJson = opts?.format === "json";
+  const isJson = isMachineFormat(opts?.format);
   const isDryRun = opts?.dryRun === true;
   if (!isJson) {
     const scope = opts?.since ? ` (since ${opts.since})` : "";
@@ -5779,7 +5780,7 @@ async function backfillSnapshotAttributionCommand(opts) {
   if (!project) {
     throw new Error(`Project "${opts.project}" not found`);
   }
-  const isJson = opts.format === "json";
+  const isJson = isMachineFormat(opts.format);
   const isDryRun = opts.dryRun === true;
   if (!isJson) {
     const mode = isDryRun ? " [DRY RUN \u2014 no writes]" : "";
@@ -5958,7 +5959,7 @@ async function backfillTrafficClassificationCommand(opts) {
   migrate(db);
   const projectFilter = opts?.project?.trim();
   const isDryRun = opts?.dryRun === true;
-  const isJson = opts?.format === "json";
+  const isJson = isMachineFormat(opts?.format);
   const scopedProjects = projectFilter ? db.select().from(projects).where(eq10(projects.name, projectFilter)).all() : db.select().from(projects).all();
   if (scopedProjects.length === 0) {
     if (projectFilter && !isJson) {
@@ -6395,7 +6396,7 @@ async function installSkills(opts = {}) {
 }
 async function listSkills(opts = {}) {
   const skills = getBundledSkills();
-  if (opts.format === "json") {
+  if (isMachineFormat(opts.format)) {
     console.log(JSON.stringify({
       skills: skills.map((s) => ({
         name: s.name,
@@ -6416,7 +6417,7 @@ async function listSkills(opts = {}) {
   }
 }
 function emitInstallSummary(summary, format) {
-  if (format === "json") {
+  if (isMachineFormat(format)) {
     console.log(JSON.stringify(summary, null, 2));
     return;
   }

package/dist/{chunk-64IDABSF.js → chunk-RQCVITY4.js}

@@ -190,6 +190,9 @@ function configExists() {
 }
 
 // src/cli-error.ts
+function isMachineFormat(format) {
+  return format === "json" || format === "jsonl";
+}
 var EXIT_USER_ERROR = 1;
 var EXIT_SYSTEM_ERROR = 2;
 var CliError = class extends Error {
@@ -221,36 +224,9 @@ function isEndpointMissing(err) {
   return status === 404 || status === 405;
 }
 function printCliError(err, format) {
-  if (format === "json") {
-    if (err instanceof CliError) {
-      console.error(
-        JSON.stringify(
-          {
-            error: {
-              code: err.code,
-              message: err.message,
-              ...err.details ? { details: err.details } : {}
-            }
-          },
-          null,
-          2
-        )
-      );
-      return;
-    }
-    const message = err instanceof Error ? err.message : "An unexpected error occurred";
-    console.error(
-      JSON.stringify(
-        {
-          error: {
-            code: "CLI_ERROR",
-            message
-          }
-        },
-        null,
-        2
-      )
-    );
+  if (isMachineFormat(format)) {
+    const envelope = err instanceof CliError ? { error: { code: err.code, message: err.message, ...err.details ? { details: err.details } : {} } } : { error: { code: "CLI_ERROR", message: err instanceof Error ? err.message : "An unexpected error occurred" } };
+    console.error(JSON.stringify(envelope, null, format === "jsonl" ? 0 : 2));
     return;
   }
   if (err instanceof CliError && err.displayMessage) {
@@ -6256,6 +6232,7 @@ export {
   saveConfig,
   saveConfigPatch,
   configExists,
+  isMachineFormat,
   EXIT_USER_ERROR,
   EXIT_SYSTEM_ERROR,
   CliError,