@koda-sl/baker-cli 0.559.0 → 0.561.0

package/dist/chunk-OWEON2S7.js

@@ -0,0 +1,1246 @@
+import {
+  googlePresetSyncedHint
+} from "./chunk-Y2FAUFWK.js";
+import {
+  getFieldDescriptions,
+  parseCampaignIds
+} from "./chunk-JQDYH5XP.js";
+import {
+  LIST_FIELDS,
+  NO_OR_EXPLANATION,
+  PRESETS,
+  SERVING_CHAINS,
+  duringLiteralExplanation,
+  equivalentBetween,
+  expandPreset,
+  getPreset,
+  isDuringLiteral,
+  isInventoryPreset,
+  listFieldGuidance,
+  parseApiError
+} from "./chunk-TCR6KI6P.js";
+import {
+  buildQueryCacheKey,
+  cacheGet,
+  cacheSet,
+  getManagerIdForCustomer,
+  getQueryTtl,
+  resolveCustomerId,
+  toCsvRow,
+  writeAdsJson
+} from "./chunk-RBCO3C3Q.js";
+import {
+  GOOGLE_ADS_QUERY_MAX_PAGE_SIZE
+} from "./chunk-MSMTG6OC.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+
+// src/commands/ads/google/query.ts
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { defineCommand } from "citty";
+
+// src/commands/ads/google/preflight.ts
+function buildCommand(query, customerId) {
+  return `baker ads google query "${query}" --customer-id ${customerId}`;
+}
+var RUNG_PIN_FIELDS = {
+  "campaign.status": ["campaign.id", "campaign.resource_name"],
+  "ad_group.status": ["ad_group.id", "ad_group.resource_name"],
+  "ad_group_criterion.status": ["ad_group_criterion.criterion_id", "ad_group_criterion.resource_name"],
+  "ad_group_ad.status": ["ad_group_ad.ad.id", "ad_group_ad.resource_name"],
+  "asset_group.status": ["asset_group.id", "asset_group.resource_name"],
+  "asset_group_asset.status": ["asset_group_asset.resource_name"],
+  "campaign_asset.status": ["campaign_asset.resource_name"],
+  "ad_group_asset.status": ["ad_group_asset.resource_name"]
+};
+function whereClause(query) {
+  const match = query.match(/\bWHERE\b([\s\S]*)$/i);
+  if (!match?.[1]) return "";
+  let rest = match[1];
+  for (const trailing of [/\bORDER\s+BY\b/i, /\bLIMIT\b/i, /\bPARAMETERS\b/i]) {
+    const idx = rest.search(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function selectClause(query) {
+  return query.split(/\bFROM\b/i)[0] ?? "";
+}
+function mentions(clause, field) {
+  return new RegExp(`(?<![\\w.])${field.replace(/\./g, "\\.")}\\b`, "i").test(clause);
+}
+function analyzeServingChain(query) {
+  const resource = fromResource(query);
+  const chain = resource ? SERVING_CHAINS[resource] : void 0;
+  if (!chain) return null;
+  const where = whereClause(query);
+  if (/ad_group_criterion\.negative\s*=\s*TRUE/i.test(where)) return null;
+  const unscoped = chain.filter((rung) => {
+    if (mentions(where, rung)) return false;
+    return !(RUNG_PIN_FIELDS[rung] ?? []).some((pin) => mentions(where, pin));
+  });
+  const assertsServing = chain.some(
+    (rung) => new RegExp(`${rung.replace(/\./g, "\\.")}\\s*=\\s*'ENABLED'`, "i").test(where)
+  );
+  return { chain, unscoped, assertsServing };
+}
+function rejectPartialChain(query, customerId, analysis) {
+  if (!analysis.assertsServing || analysis.unscoped.length === 0) return null;
+  const added = analysis.unscoped.map((rung) => `${rung} = 'ENABLED'`).join(" AND ");
+  const fixed = addRequiredAncestorFields(query.replace(/\bWHERE\b/i, `WHERE ${added} AND`)).query;
+  return {
+    ok: false,
+    error: {
+      code: "INCOMPLETE_STATUS_CHAIN",
+      message: `This query filters on serving status but leaves ${analysis.unscoped.join(", ")} unscoped. Google Ads has no single serving flag \u2014 a row is live only when its whole chain (${analysis.chain.join(" \u2192 ")}) is ENABLED, so rows under a paused parent will come back looking live.`,
+      fix: {
+        action: "retry_with_modified_query",
+        correctedCommand: buildCommand(fixed, customerId),
+        explanation: `Add the missing rungs: ${added}. To look at paused entities on purpose, scope every rung explicitly instead (e.g. ${analysis.unscoped.map((rung) => `${rung} != 'REMOVED'`).join(" AND ")}), or use --preset ... --include-paused.`
+      },
+      retryable: false
+    }
+  };
+}
+function annotateUnscopedChain(query, analysis) {
+  if (analysis.assertsServing || analysis.unscoped.length === 0) return { query, warnings: [] };
+  const select = selectClause(query);
+  const missing = analysis.unscoped.filter((rung) => !mentions(select, rung));
+  if (missing.length === 0) return { query, warnings: [] };
+  return {
+    query: query.replace(/SELECT\s+/i, `SELECT ${missing.join(", ")}, `),
+    warnings: [
+      {
+        code: "SERVING_STATUS_ADDED",
+        message: `Added ${missing.join(", ")} to SELECT \u2014 this query does not scope ${analysis.unscoped.join(", ")}, so it returns paused-parent rows that are not serving. Read those columns before calling any row live; filter every rung = 'ENABLED' to get serving rows only.`
+      }
+    ]
+  };
+}
+var SINGLE_ROW_RESOURCES = ["customer"];
+function fromResource(query) {
+  const match = query.match(/\bFROM\s+([A-Za-z_][A-Za-z0-9_]*)/i);
+  return match?.[1]?.toLowerCase() ?? null;
+}
+function isSingleRowRead(query) {
+  const resource = fromResource(query);
+  if (!resource || !SINGLE_ROW_RESOURCES.includes(resource)) return false;
+  return !/\bsegments\./i.test(selectClause(query));
+}
+var SEGMENTING_ANCESTORS = {
+  campaign_budget: ["campaign"],
+  campaign_asset: ["campaign"],
+  ad_group_asset: ["campaign", "ad_group"]
+};
+function missingRequiredSelectFields(query) {
+  const ancestors = SEGMENTING_ANCESTORS[fromResource(query) ?? ""];
+  if (!ancestors) return [];
+  const select = selectClause(query);
+  const where = query.split(/\bWHERE\b/i)[1] ?? "";
+  const filtered = ancestors.flatMap(
+    (ancestor) => where.match(new RegExp(`(?<![\\w.])${ancestor}\\.[\\w.]+`, "g")) ?? []
+  );
+  return [...new Set(filtered)].filter((field) => !mentions(select, field));
+}
+function addRequiredAncestorFields(query) {
+  const missing = missingRequiredSelectFields(query);
+  if (missing.length === 0) return { query, warnings: [] };
+  return {
+    query: query.replace(/SELECT\s+/i, `SELECT ${missing.join(", ")}, `),
+    warnings: [
+      {
+        code: "REQUIRED_FIELD_ADDED",
+        message: `Added ${missing.join(", ")} to SELECT \u2014 ${fromResource(query)} queries must select the ancestor fields used in WHERE`
+      }
+    ]
+  };
+}
+function applyAutoFixes(query) {
+  let corrected = query;
+  const warnings = [];
+  if (/(?<![\w.])keyword\.text\b/.test(corrected)) {
+    corrected = corrected.replace(/(?<![\w.])keyword\.text\b/g, "ad_group_criterion.keyword.text");
+    warnings.push({ code: "FIELD_RENAMED", message: "keyword.text \u2192 ad_group_criterion.keyword.text" });
+  }
+  if (/(?<![\w.])keyword\.match_type\b/.test(corrected)) {
+    corrected = corrected.replace(/(?<![\w.])keyword\.match_type\b/g, "ad_group_criterion.keyword.match_type");
+    warnings.push({ code: "FIELD_RENAMED", message: "keyword.match_type \u2192 ad_group_criterion.keyword.match_type" });
+  }
+  if (/shopping_performance_view\.product_\w+/.test(corrected)) {
+    corrected = corrected.replace(/shopping_performance_view\.product_(\w+)/g, "segments.product_$1");
+    warnings.push({ code: "FIELD_RENAMED", message: "shopping_performance_view.product_* \u2192 segments.product_*" });
+  }
+  if (/asset\.\w+_asset\.final_(mobile_)?urls\b/.test(corrected)) {
+    corrected = corrected.replace(/asset\.\w+_asset\.final_(mobile_)?urls\b/g, "asset.final_$1urls");
+    warnings.push({ code: "FIELD_RENAMED", message: "asset.<type>_asset.final_urls \u2192 asset.final_urls" });
+  }
+  const ancestorFix = addRequiredAncestorFields(corrected);
+  corrected = ancestorFix.query;
+  warnings.push(...ancestorFix.warnings);
+  if (/campaign\.status\s*=\s*'ACTIVE'/i.test(corrected)) {
+    corrected = corrected.replace(/campaign\.status\s*=\s*'ACTIVE'/gi, "campaign.status = 'ENABLED'");
+    warnings.push({ code: "ENUM_CORRECTED", message: "campaign.status ACTIVE \u2192 ENABLED" });
+  }
+  if (/ad_group\.status\s*=\s*'ACTIVE'/i.test(corrected)) {
+    corrected = corrected.replace(/ad_group\.status\s*=\s*'ACTIVE'/gi, "ad_group.status = 'ENABLED'");
+    warnings.push({ code: "ENUM_CORRECTED", message: "ad_group.status ACTIVE \u2192 ENABLED" });
+  }
+  return { query: corrected, warnings };
+}
+var DURING_CLAUSE = /(?<=[a-z_]\.[a-z_.]+\s+)DURING\s+([A-Za-z0-9_]+)/gi;
+function rejectUnsupportedDuring(query, customerId) {
+  const unsupported = [...query.matchAll(DURING_CLAUSE)].map((match) => match[1] ?? "").filter((literal2) => !isDuringLiteral(literal2));
+  const literal = unsupported[0];
+  if (literal === void 0) return null;
+  const now = /* @__PURE__ */ new Date();
+  const between = equivalentBetween(literal, now);
+  const fixed = unsupported.every((l) => equivalentBetween(l, now) !== null) ? query.replace(
+    DURING_CLAUSE,
+    (clause, l) => isDuringLiteral(l) ? clause : equivalentBetween(l, now) ?? clause
+  ) : void 0;
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_DATE_RANGE",
+      message: `DURING ${literal} is not a Google Ads date range, so Google would refuse this query.`,
+      fix: {
+        action: "narrow_date_range",
+        ...fixed ? { correctedCommand: buildCommand(fixed, customerId) } : {},
+        explanation: duringLiteralExplanation(literal, between)
+      },
+      retryable: false
+    }
+  };
+}
+var WHERE_OPERATOR = /(?<![\w.])([a-z_]+(?:\.[a-z_]+)+)\s*(CONTAINS\s+(?:ALL|ANY|NONE)|IS\s+NOT\s+NULL|IS\s+NULL|NOT\s+LIKE|NOT\s+IN|NOT\s+REGEXP_MATCH|REGEXP_MATCH|LIKE|IN|BETWEEN|DURING|!=|<=|>=|=|<|>)/gi;
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function withoutNullTest(query, field) {
+  const test = `${escapeRegExp(field)}\\s+IS\\s+(?:NOT\\s+)?NULL\\b`;
+  const dropped = query.replace(new RegExp(`\\bWHERE\\s+${test}\\s+AND\\s+`, "i"), "WHERE ").replace(new RegExp(`\\s+AND\\s+${test}`, "i"), "").replace(new RegExp(`\\s*\\bWHERE\\s+${test}`, "i"), "");
+  return mentions(selectClause(dropped), field) ? dropped : dropped.replace(/SELECT\s+/i, `SELECT ${field}, `);
+}
+function asListCondition(query, field) {
+  const condition = new RegExp(
+    `(?<![\\w.])${escapeRegExp(field)}\\s*(NOT\\s+IN\\b|IN\\b|!=|=)\\s*('[^']*'|\\([^)]*\\))`,
+    "i"
+  );
+  const match = query.match(condition);
+  if (!match) return null;
+  const [, operator = "", value = ""] = match;
+  const contains = /^(=|IN)$/i.test(operator.trim()) ? "CONTAINS ANY" : "CONTAINS NONE";
+  const values = value.startsWith("(") ? value : `(${value})`;
+  return query.replace(condition, `${field} ${contains} ${values}`);
+}
+function rejectListFieldOperator(query, customerId) {
+  const where = whereClause(query).replace(/'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/g, "''");
+  const refusals = [...where.matchAll(WHERE_OPERATOR)].map(([, field = "", operator = ""]) => ({
+    field: field.toLowerCase(),
+    operator: operator.toUpperCase().replace(/\s+/g, " ")
+  })).filter(({ field, operator }) => LIST_FIELDS.has(field) && !operator.startsWith("CONTAINS"));
+  const first = refusals[0];
+  if (!first) return null;
+  const fixed = refusals.reduce(
+    (corrected, { field, operator }) => corrected === null ? null : operator.startsWith("IS ") ? withoutNullTest(corrected, field) : asListCondition(corrected, field),
+    query
+  );
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_OPERATOR",
+      message: `${first.operator} cannot be used on ${first.field}: it is a list field, so Google would refuse this query.`,
+      fix: {
+        action: "change_operator",
+        ...fixed ? { correctedCommand: buildCommand(fixed, customerId) } : {},
+        explanation: listFieldGuidance(first.field)
+      },
+      retryable: false
+    }
+  };
+}
+function rejectContainsCall(query, customerId) {
+  const containsMatch = query.match(/CONTAINS\s*\(\s*([^,]+),\s*'([^']+)'\s*\)/i);
+  if (!containsMatch) return null;
+  const field = containsMatch[1]?.trim();
+  const value = containsMatch[2] ?? "";
+  const fixed = query.replace(/CONTAINS\s*\(\s*[^,]+,\s*'[^']+'\s*\)/i, `${field} LIKE '%${value}%'`);
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_OPERATOR",
+      message: "GAQL does not support CONTAINS. Use LIKE with % wildcards.",
+      fix: {
+        action: "change_operator",
+        correctedCommand: buildCommand(fixed, customerId),
+        explanation: "GAQL uses LIKE '%value%' for substring matching, not CONTAINS()"
+      },
+      retryable: false
+    }
+  };
+}
+function rejectOrCondition(query) {
+  const where = whereClause(query).replace(/'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"/g, "''");
+  const hasOr = /(?<![\w.])OR(?![\w.])/i.test(where);
+  const hasGroup = /(?:^|\bAND|\bNOT)\s*\(/i.test(where);
+  if (!hasOr && !hasGroup) return null;
+  return {
+    ok: false,
+    error: {
+      code: "INVALID_SYNTAX",
+      message: `${hasOr ? "OR" : "A parenthesised condition"} in WHERE: Google would refuse this query.`,
+      fix: { action: "retry_with_modified_query", explanation: NO_OR_EXPLANATION },
+      retryable: false
+    }
+  };
+}
+function validatePreflight(query, customerId) {
+  const warnings = [];
+  const corrected = query;
+  const firstWord = corrected.trim().split(/\s+/)[0]?.toUpperCase();
+  if (firstWord && firstWord !== "SELECT") {
+    return {
+      valid: false,
+      warnings: [],
+      error: {
+        ok: false,
+        error: {
+          code: "READ_ONLY",
+          message: `Only SELECT queries are allowed. Got: ${firstWord}`,
+          fix: {
+            action: "reject",
+            explanation: "This CLI only supports GAQL SELECT queries for reading data"
+          },
+          retryable: false
+        }
+      }
+    };
+  }
+  const openDateMatch = corrected.match(/segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i);
+  if (openDateMatch && !/BETWEEN/i.test(corrected)) {
+    const startDate = openDateMatch[1] ?? "";
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const fixed = corrected.replace(
+      /segments\.date\s*>=\s*'(\d{4}-\d{2}-\d{2})'/i,
+      `segments.date BETWEEN '${startDate}' AND '${today}'`
+    );
+    return {
+      valid: false,
+      warnings: [],
+      error: {
+        ok: false,
+        error: {
+          code: "OPEN_ENDED_DATE",
+          message: "Open-ended date ranges are not supported. Use BETWEEN or DURING.",
+          fix: {
+            action: "narrow_date_range",
+            correctedCommand: buildCommand(fixed, customerId),
+            explanation: "Use BETWEEN with explicit start and end dates"
+          },
+          retryable: false
+        }
+      }
+    };
+  }
+  for (const reject of [rejectContainsCall, rejectOrCondition, rejectListFieldOperator, rejectUnsupportedDuring]) {
+    const rejection2 = reject(corrected, customerId);
+    if (rejection2) return { valid: false, warnings: [], error: rejection2 };
+  }
+  if (/\bsegments\.conversion_action_name\b/i.test(corrected) && /\bmetrics\.cost_micros\b/i.test(corrected)) {
+    return {
+      valid: false,
+      warnings: [],
+      error: {
+        ok: false,
+        error: {
+          code: "INCOMPATIBLE_FIELDS",
+          message: "segments.conversion_action_name cannot be selected with metrics.cost_micros in one GAQL query.",
+          fix: {
+            action: "split_query",
+            explanation: "Run one campaign spend query with metrics.cost_micros and a separate conversion-action query without cost metrics, then join the results by campaign."
+          },
+          retryable: false
+        }
+      }
+    };
+  }
+  if (/FROM\s+ad_group_criterion\b/i.test(corrected) && !/ad_group_criterion\.negative/i.test(corrected)) {
+    warnings.push({
+      code: "NEGATIVE_FIELD_MISSING",
+      message: "ad_group_criterion returns BOTH positive and negative keywords. Add ad_group_criterion.negative to SELECT or filter with WHERE ad_group_criterion.negative = FALSE (positives) / TRUE (negatives). Use --preset positive-keywords or negative-keywords instead."
+    });
+  }
+  const { query: autoFixed, warnings: autoFixWarnings } = applyAutoFixes(corrected);
+  warnings.push(...autoFixWarnings);
+  const analysis = analyzeServingChain(autoFixed);
+  if (!analysis) return { valid: true, correctedQuery: autoFixed, warnings };
+  const rejection = rejectPartialChain(autoFixed, customerId, analysis);
+  if (rejection) return { valid: false, warnings: [], error: rejection };
+  const annotated = annotateUnscopedChain(autoFixed, analysis);
+  warnings.push(...annotated.warnings);
+  return { valid: true, correctedQuery: annotated.query, warnings };
+}
+
+// src/commands/ads/google/conversion-mix.ts
+var CONVERSION_METRICS = [
+  "METRICS.CONVERSIONS",
+  "METRICS.ALL_CONVERSIONS",
+  "METRICS.CONVERSIONS_VALUE",
+  "METRICS.ALL_CONVERSIONS_VALUE",
+  "METRICS.COST_PER_CONVERSION",
+  "METRICS.COST_PER_ALL_CONVERSIONS",
+  "METRICS.CONVERSIONS_FROM_INTERACTIONS_RATE",
+  "METRICS.ALL_CONVERSIONS_FROM_INTERACTIONS_RATE",
+  "METRICS.VALUE_PER_CONVERSION",
+  "METRICS.VALUE_PER_ALL_CONVERSIONS"
+];
+var CONVERSION_SEGMENTS = ["SEGMENTS.CONVERSION_ACTION_NAME", "SEGMENTS.CONVERSION_ACTION="];
+var CAMPAIGN_EQUALITY = /\bCAMPAIGN\.(ID|NAME|RESOURCE_NAME)\s*=/;
+function whereClause2(upperQuery) {
+  const whereIdx = upperQuery.indexOf(" WHERE ");
+  if (whereIdx === -1) return "";
+  let rest = upperQuery.slice(whereIdx + 7);
+  for (const trailing of [" ORDER BY ", " GROUP BY ", " LIMIT ", " PARAMETERS "]) {
+    const idx = rest.indexOf(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function conversionMixWarnings(finalQuery) {
+  const upper = ` ${finalQuery.toUpperCase().replace(/\s+/g, " ")} `;
+  const readsConversions = CONVERSION_METRICS.some((metric) => upper.includes(metric));
+  if (!readsConversions) return [];
+  if (CONVERSION_SEGMENTS.some((segment) => upper.includes(segment))) return [];
+  if (CAMPAIGN_EQUALITY.test(whereClause2(upper))) return [];
+  if (isSingleRowRead(finalQuery)) return [];
+  return [
+    {
+      code: "CONVERSION_MIX",
+      message: "MIXED CONVERSION ACTIONS \u2014 this read covers more than one campaign, and a campaign's conversion figures count whatever conversion actions are primary for it. Those differ campaign by campaign (a webinar registration, an info request, a CRM-stage SQL), so a total across these rows adds different events and a conversion rate from one campaign is not comparable with another's. Before totalling or comparing, re-run segmented by segments.conversion_action_name and check the campaigns you are putting side by side count the same action. If they do not, compare only within one action \u2014 and carry that caveat into anything you write for the user, not just the analysis."
+    }
+  ];
+}
+
+// src/commands/ads/google/keyword-serving.ts
+var BELOW_FIRST_PAGE_BID = "AD_GROUP_CRITERION_BELOW_FIRST_PAGE_BID";
+var ACTIONABLE_REASONS = {
+  [BELOW_FIRST_PAGE_BID]: {
+    label: "Below first page bid",
+    advice: "raise the max CPC (keywords update --cpc-bid) to at least the first-page estimate, or move the ad group onto a smart bidding strategy that sets the bid itself"
+  },
+  AD_GROUP_CRITERION_LOW_QUALITY: {
+    label: "Low quality score",
+    advice: "a bid raise does not lift quality \u2014 tighten ad relevance to the keyword and the landing page it points at (ad_group_criterion.quality_info.* breaks the score into its three parts)"
+  },
+  AD_GROUP_CRITERION_RARELY_SERVED: {
+    label: "Rarely served",
+    advice: "too few people search this term \u2014 broaden the match type or drop it, don't bid it up"
+  },
+  AD_GROUP_CRITERION_DISAPPROVED: {
+    label: "Disapproved",
+    advice: "select ad_group_criterion.disapproval_reasons to see which policy blocked it"
+  },
+  AD_GROUP_CRITERION_RESTRICTED: {
+    label: "Restricted",
+    advice: "policy limits where and to whom this keyword may show"
+  },
+  AD_GROUP_CRITERION_UNDER_REVIEW: {
+    label: "Under review",
+    advice: "waiting on Google's review \u2014 nothing to change yet"
+  },
+  AD_GROUP_CRITERION_PENDING_REVIEW: {
+    label: "Pending review",
+    advice: "waiting on Google's review \u2014 nothing to change yet"
+  },
+  AD_GROUP_CRITERION_PAUSED_DUE_TO_LOW_ACTIVITY: {
+    label: "Auto-paused for low activity",
+    advice: "Google paused it after prolonged low serving \u2014 resume it only alongside a change that gives it traffic"
+  }
+};
+var REASON_ORDER = Object.keys(ACTIONABLE_REASONS);
+var MAX_NAMED_KEYWORDS = 5;
+function toMicros(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
+  return null;
+}
+function formatMoney(micros) {
+  return (micros / 1e6).toFixed(2);
+}
+function keywordLabel(row) {
+  const text = row["ad_group_criterion.keyword.text"];
+  const id = row["ad_group_criterion.criterion_id"];
+  const name = typeof text === "string" && text !== "" ? text : id == null ? "(unnamed keyword)" : `criterion ${id}`;
+  const adGroup = row["ad_group.name"];
+  return typeof adGroup === "string" && adGroup !== "" ? `${name} (ad group ${adGroup})` : name;
+}
+function keywordKey(row) {
+  const adGroup = row["ad_group.id"] ?? row["ad_group.name"] ?? "";
+  const criterion = row["ad_group_criterion.criterion_id"] ?? row["ad_group_criterion.keyword.text"] ?? "";
+  return `${String(adGroup)}~${String(criterion)}` === "~" ? keywordLabel(row) : `${adGroup}~${criterion}`;
+}
+function reasonsOn(row) {
+  const raw = row["ad_group_criterion.primary_status_reasons"];
+  if (!Array.isArray(raw)) return null;
+  return raw.filter((r) => typeof r === "string");
+}
+function bidShortfall(row) {
+  const bid = toMicros(row["ad_group_criterion.effective_cpc_bid_micros"] ?? row["ad_group_criterion.cpc_bid_micros"]);
+  const firstPage = toMicros(row["ad_group_criterion.position_estimates.first_page_cpc_micros"]);
+  if (bid == null || firstPage == null || bid >= firstPage) return null;
+  return `bids ${formatMoney(bid)} against a ${formatMoney(firstPage)} first-page estimate`;
+}
+function limitsOn(row, options) {
+  const reasons = reasonsOn(row);
+  const shortfall = bidShortfall(row);
+  const label = keywordLabel(row);
+  const applicable = reasons ? reasons.filter((reason) => reason in ACTIONABLE_REASONS) : options.statusReasonsSelected || shortfall === null ? [] : [BELOW_FIRST_PAGE_BID];
+  return applicable.map((reason) => ({
+    reason,
+    detail: reason === BELOW_FIRST_PAGE_BID && shortfall ? `"${label}" ${shortfall}` : `"${label}"`
+  }));
+}
+function describeLimit(reason, details) {
+  const named = details.slice(0, MAX_NAMED_KEYWORDS).join("; ");
+  const rest = details.length > MAX_NAMED_KEYWORDS ? ` (+${details.length - MAX_NAMED_KEYWORDS} more)` : "";
+  const { label, advice } = ACTIONABLE_REASONS[reason];
+  return `${label} \u2014 ${details.length}: ${named}${rest}. Fix: ${advice}.`;
+}
+function collectKeywordLimits(rows, options, acc = { detailsByReason: /* @__PURE__ */ new Map(), keywords: /* @__PURE__ */ new Set() }) {
+  for (const row of rows) {
+    const limits = limitsOn(row, options);
+    if (limits.length === 0) continue;
+    acc.keywords.add(keywordKey(row));
+    for (const { reason, detail } of limits) {
+      const bucket = acc.detailsByReason.get(reason);
+      if (bucket) bucket.push(detail);
+      else acc.detailsByReason.set(reason, [detail]);
+    }
+  }
+  return acc;
+}
+function renderKeywordLimits(limits) {
+  if (limits.detailsByReason.size === 0) return [];
+  const sentences = REASON_ORDER.filter((reason) => limits.detailsByReason.has(reason)).map(
+    (reason) => describeLimit(reason, limits.detailsByReason.get(reason) ?? [])
+  );
+  const count = limits.keywords.size;
+  return [
+    {
+      code: "KEYWORD_SERVING_LIMITED",
+      message: `${count} ${count === 1 ? "keyword is" : "keywords are"} limited and not getting the traffic they could. ${sentences.join(" ")} Amounts are in the account currency (baker ads google currency).`
+    }
+  ];
+}
+function keywordServingWarnings(rows, options) {
+  return renderKeywordLimits(collectKeywordLimits(rows, options));
+}
+
+// src/commands/ads/google/money-units.ts
+function isSettingMicros(field) {
+  return field.endsWith("_micros") && !field.startsWith("metrics.") && !field.endsWith("_fraction_micros");
+}
+function moneyUnitWarnings(fields) {
+  const example = fields.find(isSettingMicros);
+  if (!example) return [];
+  return [
+    {
+      code: "MONEY_IN_MICROS",
+      message: `Budgets and bids in these rows are in micros, millionths of the account currency: ${example} 20000000 is 20. Write flags (--amount, --cpc-bid, --max-cpc, --target-cpa, --target-cpc) take whole currency: --amount 20, never the micros.`
+    }
+  ];
+}
+
+// src/commands/ads/google/query.ts
+registerSchema({
+  command: "ads.google.query",
+  description: "Run a GAQL (Google Ads Query Language) query, one page at a time. Start here: `baker ads google query --preset campaign-performance` (--list-presets for all). Each read returns one page of --limit rows and, when the account holds more, `pagination.cursor` \u2014 pass it back with --cursor for the next page, or use --all --out <file> to read every page. A LIMIT in your own GAQL caps the whole read.",
+  args: {
+    query: { type: "positional", description: "GAQL SELECT statement (or pass it with --gaql)", required: false },
+    gaql: {
+      type: "string",
+      description: 'GAQL SELECT statement as a flag \u2014 same as the positional, for when quoting a positional is awkward: --gaql "SELECT campaign.name FROM campaign"',
+      required: false
+    },
+    "customer-id": {
+      type: "string",
+      description: "Google Ads customer ID (10 digits, no dashes). Falls back to BAKER_GOOGLE_ADS_CUSTOMER_ID env var.",
+      required: false
+    },
+    preset: {
+      type: "string",
+      description: `Named query preset (--list-presets shows each one's GAQL and page size): ${PRESETS.map((p) => p.name).join(", ")}. Presets return only actually-serving entities (enabled campaign AND ad group AND ad) by default \u2014 pass --include-paused to include paused ones.`,
+      required: false
+    },
+    "date-range": {
+      type: "string",
+      description: "Date range for presets: a Google date literal (TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH \u2026) or BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'. Google has no LAST_90_DAYS \u2014 use BETWEEN for any other window.",
+      required: false
+    },
+    "include-paused": {
+      type: "boolean",
+      description: "Include paused entities in preset results. Off by default: presets return only actually-serving entities. Google Ads has no single serving flag \u2014 an entity serves only when its whole chain (campaign, ad group, ad) is ENABLED, so recommendations should target serving entities unless the user asks about paused ones.",
+      required: false
+    },
+    limit: {
+      type: "number",
+      description: `Rows per page (default: the preset's page size, else 200; at most ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}). A page size, not a cap: when more rows exist the read returns a cursor, and --all keeps paging.`,
+      required: false
+    },
+    "list-presets": { type: "boolean", description: "List all available query presets", required: false },
+    cursor: {
+      type: "string",
+      description: "Resume after a previous page: pass its pagination.cursor with the same query and --limit",
+      required: false
+    },
+    all: {
+      type: "boolean",
+      description: "Follow every page until the account has no more rows (use with --out for large reads). Needed for any read you will count or total. Only a LIMIT written in the GAQL itself can stop it early.",
+      required: false
+    },
+    out: {
+      type: "string",
+      description: "Write data to file (format from extension: .csv, .jsonl, .json)",
+      required: false
+    },
+    append: { type: "boolean", description: "Append to existing file (skip CSV headers)", required: false },
+    output: {
+      type: "string",
+      description: "Output format: json|csv|jsonl|md",
+      required: false,
+      default: "json",
+      enum: ["json", "csv", "jsonl", "md"]
+    },
+    "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
+    full: {
+      type: "boolean",
+      description: "Include the field description glossary in the JSON envelope. Off by default \u2014 rows already carry the data; only ask for this when you need a field's meaning explained.",
+      required: false
+    }
+  }
+});
+function extractFields(rows) {
+  const keys = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, keys);
+  return [...keys];
+}
+function resultColumns(gaql, rows) {
+  const observed = extractFields(rows);
+  const columns = [];
+  for (const field of parseSelectedFields(gaql)) {
+    const leaves = observed.filter((key) => key.startsWith(`${field}.`));
+    columns.push(...leaves.length > 0 ? leaves : [field]);
+  }
+  for (const key of observed) columns.push(key);
+  return [...new Set(columns)];
+}
+function isCsvPath(filePath) {
+  return filePath.split(".").pop()?.toLowerCase() === "csv";
+}
+function writeRowsToFile(filePath, rows, fields, append) {
+  if (isCsvPath(filePath)) {
+    if (!append || !existsSync(filePath)) {
+      writeFileSync(filePath, `${toCsvRow(fields)}
+`, "utf-8");
+    }
+    const csvRows = rows.map((row) => toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+    appendFileSync(filePath, `${csvRows.join("\n")}
+`, "utf-8");
+  } else if (filePath.split(".").pop()?.toLowerCase() === "jsonl") {
+    const lines = rows.map((row) => JSON.stringify(row));
+    if (append && existsSync(filePath)) {
+      appendFileSync(filePath, `${lines.join("\n")}
+`, "utf-8");
+    } else {
+      writeFileSync(filePath, `${lines.join("\n")}
+`, "utf-8");
+    }
+  } else if (append && existsSync(filePath)) {
+    const existing = JSON.parse(readFileSync(filePath, "utf-8"));
+    writeFileSync(filePath, JSON.stringify([...existing, ...rows], null, 2), "utf-8");
+  } else {
+    writeFileSync(filePath, JSON.stringify(rows, null, 2), "utf-8");
+  }
+}
+function effectiveRowLimit(finalQuery) {
+  if (isSingleRowRead(finalQuery)) return void 0;
+  const match = finalQuery.match(/\bLIMIT\s+(\d+)/i);
+  return match?.[1] ? Number(match[1]) : void 0;
+}
+function warningLines(warnings, format) {
+  return warnings.map((w) => {
+    const message = w.message.replace(/\s*\n\s*/g, " ");
+    if (format === "jsonl") return JSON.stringify({ _baker_warning: { code: w.code, message } });
+    if (format === "md") return `> **${w.code}** \u2014 ${message}`;
+    return `# baker ${w.code}: ${message}`;
+  });
+}
+function completenessWarnings(read) {
+  const cap = read.effectiveLimit;
+  const filledTheCap = cap !== void 0 && cap > 0 && read.rowCount >= cap;
+  if (!read.hasMore && !filledTheCap) return [];
+  const [cause, fix] = read.hasMore ? [
+    "More rows are waiting: the account returned a next-page cursor this run did not follow.",
+    "Re-run with --all --out <file> to read every page, or pass --cursor <pagination.cursor> (same query, same --limit) for the next page."
+  ] : [
+    `The ${read.rowCount} rows returned exactly fill the LIMIT in the statement (${cap}).`,
+    `Raise the LIMIT in the statement above ${cap}, or drop it \u2014 without a LIMIT, --all pages through every row.`
+  ];
+  return [
+    {
+      code: "TRUNCATED_RESULTS",
+      message: `INCOMPLETE READ \u2014 ${cause} These rows are a page, not the data set. Don't count, total or describe them as the whole picture. ${fix}`
+    }
+  ];
+}
+function buildQueryEnvelope(rows, fieldDescs, warnings, options) {
+  const notice = summariseWarnings(warnings);
+  return {
+    ok: true,
+    ...options.cached ? { cached: true } : {},
+    ...warnings.length > 0 ? { warnings } : {},
+    ...options.nextCursor ? { pagination: { hasMore: true, cursor: options.nextCursor } } : {},
+    data: rows,
+    ...options.full && Object.keys(fieldDescs).length > 0 ? { fields: fieldDescs } : {},
+    ...notice ? { notice } : {}
+  };
+}
+function summariseWarnings(warnings) {
+  if (warnings.length === 0) return void 0;
+  const codes = [...new Set(warnings.map((w) => w.code))].join(", ");
+  return `Read the "warnings" above before using these rows: ${codes}.`;
+}
+function buildFileSummary(input) {
+  const notice = summariseWarnings(input.warnings);
+  return {
+    ok: true,
+    fields: {},
+    file: input.file,
+    rows: input.rows,
+    complete: input.complete,
+    ...input.warnings.length > 0 ? { warnings: input.warnings } : {},
+    ...notice ? { notice } : {}
+  };
+}
+var REPEAT_NOTICE_ABOVE_ROWS = 20;
+function emitToStderr(notices) {
+  for (const line of notices) process.stderr.write(`${line}
+`);
+}
+function writeLine(line) {
+  process.stdout.write(`${line}
+`);
+}
+var writeCsvRows = (rows, fields, notices) => {
+  writeLine(toCsvRow(fields));
+  for (const line of notices) writeLine(line);
+  for (const row of rows) writeLine(toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+};
+var writeJsonlRows = (rows, _fields, notices) => {
+  for (const line of notices) writeLine(line);
+  for (const row of rows) writeLine(JSON.stringify(row));
+};
+var OMITTED = "(omitted)";
+var OMITTED_FALSE = `false ${OMITTED}`;
+var OMITTED_LEGEND = `> ${OMITTED} = Google left this field off the row, which is how it sends false, 0 and "not set": the field WAS read. A field with no column here was not read.`;
+function mdCell(row, field, booleanColumns) {
+  if (!(field in row)) return booleanColumns.has(field) ? OMITTED_FALSE : OMITTED;
+  return String(row[field] ?? "").replace(/\|/g, "\\|");
+}
+var writeMdRows = (rows, fields, notices) => {
+  const booleanColumns = new Set(fields.filter((f) => rows.some((row) => typeof row[f] === "boolean")));
+  for (const line of notices) writeLine(line);
+  writeLine(`| ${fields.join(" | ")} |`);
+  writeLine(`| ${fields.map(() => "---").join(" | ")} |`);
+  for (const row of rows) writeLine(`| ${fields.map((f) => mdCell(row, f, booleanColumns)).join(" | ")} |`);
+  if (rows.some((row) => fields.some((f) => !(f in row)))) writeLine(OMITTED_LEGEND);
+};
+var ROW_WRITERS = { csv: writeCsvRows, jsonl: writeJsonlRows, md: writeMdRows };
+function writeRows(format, rows, columns, notices) {
+  const write = ROW_WRITERS[format] ?? writeMdRows;
+  write(rows, columns, notices);
+  if (rows.length > REPEAT_NOTICE_ABOVE_ROWS) {
+    for (const line of notices) writeLine(line);
+  }
+}
+function outputResults(rows, fieldDescs, warnings, args, cached, read) {
+  const format = args.output || "json";
+  const allWarnings = [
+    ...warnings,
+    ...completenessWarnings({
+      rowCount: rows.length,
+      effectiveLimit: read.effectiveLimit,
+      hasMore: Boolean(read.nextCursor)
+    })
+  ];
+  emitToStderr(warningLines(allWarnings, "csv"));
+  if (format === "json") {
+    writeAdsJson(
+      buildQueryEnvelope(rows, fieldDescs, allWarnings, {
+        full: Boolean(args.full),
+        cached,
+        nextCursor: read.nextCursor
+      })
+    );
+    return;
+  }
+  writeRows(format, rows, resultColumns(read.gaql, rows), warningLines(allWarnings, format));
+}
+function resolveGaqlInput(args) {
+  const positional = typeof args.query === "string" ? args.query.trim() : "";
+  const flag = typeof args.gaql === "string" ? args.gaql.trim() : "";
+  if (positional && flag && positional !== flag) {
+    return { ok: false, message: "Pass the GAQL statement once \u2014 as the positional or as --gaql, not both." };
+  }
+  return { ok: true, gaql: positional || flag };
+}
+function resolveGaql(args) {
+  if (args.preset) {
+    const preset = getPreset(args.preset);
+    if (!preset) {
+      const available = PRESETS.map((p) => p.name).join(", ");
+      writeAdsJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: `Unknown preset: "${args.preset}". Available: ${available}` }
+      });
+      return null;
+    }
+    const campaigns = parseCampaignIds(args["campaign-id"]);
+    if (!campaigns.ok) {
+      writeAdsJson({ ok: false, error: campaigns.error });
+      return null;
+    }
+    const expanded = expandPreset(preset, {
+      dateRange: args["date-range"],
+      includePaused: Boolean(args["include-paused"]),
+      campaignIds: campaigns.ids
+    });
+    if (expanded.dateRangeError) {
+      writeAdsJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: expanded.dateRangeError }
+      });
+      return null;
+    }
+    return expanded.query;
+  }
+  const input = resolveGaqlInput(args);
+  if (!input.ok || !input.gaql) {
+    writeAdsJson({
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: input.ok ? "Provide a GAQL query (positional or --gaql) or use --preset. Run --list-presets to see options." : input.message
+      }
+    });
+    return null;
+  }
+  return input.gaql;
+}
+var SERVING_HIERARCHY_RESOURCES = [
+  "campaign",
+  "ad_group",
+  "ad_group_ad",
+  "ad_group_criterion",
+  "keyword_view",
+  "search_term_view",
+  "shopping_performance_view",
+  "asset_group_asset"
+].filter((resource) => !(resource in SERVING_CHAINS));
+function whereClause3(upperQuery) {
+  const whereIdx = upperQuery.indexOf(" WHERE ");
+  if (whereIdx === -1) return "";
+  let rest = upperQuery.slice(whereIdx + 7);
+  for (const trailing of [" ORDER BY ", " GROUP BY ", " LIMIT ", " PARAMETERS "]) {
+    const idx = rest.indexOf(trailing);
+    if (idx !== -1) rest = rest.slice(0, idx);
+  }
+  return rest;
+}
+function servingScopeWarnings(args, finalQuery) {
+  if (args.preset) {
+    const name = String(args.preset);
+    if (!args["include-paused"] || isInventoryPreset(name) || !getPreset(name)?.statusFields?.length) return [];
+    return [
+      {
+        code: "SERVING_SCOPE",
+        message: "Paused entities are included (--include-paused). Only recommend changes for actually-serving entities (enabled campaign, ad group, and ad) unless the user asked about paused ones."
+      }
+    ];
+  }
+  const upper = finalQuery.toUpperCase();
+  const fromMatch = upper.match(/\bFROM\s+([A-Z_]+)/);
+  const resource = fromMatch?.[1]?.toLowerCase();
+  const hierarchical = resource ? SERVING_HIERARCHY_RESOURCES.includes(resource) : false;
+  const filtersStatus = whereClause3(upper).includes(".STATUS");
+  if (hierarchical && !filtersStatus) {
+    return [
+      {
+        code: "SERVING_SCOPE",
+        message: "This query has no status filter, so it may return paused entities that aren't actually serving. Google Ads has no single serving flag \u2014 an entity serves only when its whole chain is ENABLED. Add campaign.status = 'ENABLED' AND ad_group.status = 'ENABLED' AND ad_group_ad.status = 'ENABLED' (as applicable), or use a --preset, unless you intend to include paused entities."
+      }
+    ];
+  }
+  return [];
+}
+function syncedCopyWarnings(args) {
+  const hint = googlePresetSyncedHint(typeof args.preset === "string" ? args.preset : void 0);
+  return hint ? [{ code: "SYNCED_COPY", message: hint }] : [];
+}
+function parseSelectedFields(gaql) {
+  const match = gaql.match(/\bSELECT\b([\s\S]*?)\bFROM\b/i);
+  const list = match?.[1];
+  if (!list) return [];
+  return list.split(",").map((field) => field.trim()).filter((field) => /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)*$/.test(field));
+}
+function foldObservedFields(rows, observed) {
+  for (const row of rows) {
+    for (const key of Object.keys(row)) observed.add(key);
+  }
+}
+function unobservedSelectedFields(gaql, rows) {
+  const observed = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, observed);
+  return unobservedFields(gaql, observed);
+}
+function unobservedFields(gaql, observed) {
+  return parseSelectedFields(gaql).filter((field) => {
+    if (field.endsWith(".resource_name")) return false;
+    if (observed.has(field)) return false;
+    return ![...observed].some((key) => key.startsWith(`${field}.`));
+  });
+}
+function missingFieldWarnings(gaql, rows) {
+  const observed = /* @__PURE__ */ new Set();
+  foldObservedFields(rows, observed);
+  return missingFieldWarningsFor(gaql, observed, rows.length);
+}
+function missingFieldWarningsFor(gaql, observed, rowCount) {
+  if (rowCount === 0) return [];
+  const missing = unobservedFields(gaql, observed);
+  if (missing.length === 0) return [];
+  return [
+    {
+      code: "MISSING_FIELDS",
+      message: `These SELECTed fields came back on no row: ${missing.join(", ")}. Google Ads omits a field entirely when it has no value, so this does NOT mean the setting is empty \u2014 it means this read didn't observe it. Check the level that owns the setting before concluding it is unset.`
+    }
+  ];
+}
+function unwrittenColumnWarnings(header, observed) {
+  const written = new Set(header);
+  const unwritten = [...observed].filter((key) => !written.has(key));
+  if (unwritten.length === 0) return [];
+  return [
+    {
+      code: "UNWRITTEN_COLUMNS",
+      message: `The file has no column for ${unwritten.join(", ")}: the header was fixed on the first page, which carried none of them, so their values from later pages are NOT in the file. Do not read those columns as empty. SELECT these fields by name instead of their parent, or write to a .jsonl file, then re-run.`
+    }
+  ];
+}
+function keywordServingOptions(gaql) {
+  return { statusReasonsSelected: parseSelectedFields(gaql).includes("ad_group_criterion.primary_status_reasons") };
+}
+async function fetchAllPages(gaql, body, args, servingOptions) {
+  let allRows = [];
+  let pageToken = args.cursor;
+  let totalRowsWritten = 0;
+  let keywordLimits;
+  const observedFields = /* @__PURE__ */ new Set();
+  let fileColumns;
+  do {
+    const requestBody = { ...body };
+    if (pageToken) requestBody.pageToken = pageToken;
+    const response = await apiPost("/api/ads/google/query", requestBody);
+    const rows = response.rows ?? [];
+    pageToken = response.pageToken;
+    if (args.out) {
+      const shouldAppend = args.append || totalRowsWritten > 0;
+      fileColumns ??= resultColumns(gaql, rows);
+      writeRowsToFile(resolve(args.out), rows, fileColumns, shouldAppend);
+      totalRowsWritten += rows.length;
+      keywordLimits = collectKeywordLimits(rows, servingOptions, keywordLimits);
+      foldObservedFields(rows, observedFields);
+    } else {
+      allRows = allRows.concat(rows);
+    }
+    if (!args.all) break;
+  } while (pageToken);
+  return {
+    allRows,
+    lastPageToken: pageToken,
+    totalRowsWritten,
+    keywordLimits: keywordLimits ?? collectKeywordLimits([], servingOptions),
+    observedFields,
+    fileColumns: fileColumns ?? []
+  };
+}
+function pageCacheKey(customerId, query, pageSize, cursor) {
+  return buildQueryCacheKey(customerId, `${query}\0page=${pageSize}\0cursor=${cursor ?? ""}`);
+}
+async function executeQuery(finalQuery, args, customerId, limit, warnings, useCache, cacheKey) {
+  const body = { customerId, query: finalQuery, pageSize: limit };
+  const managerId = getManagerIdForCustomer(customerId);
+  if (managerId) body.managerId = managerId;
+  if (!useCache) body.skipCache = true;
+  const servingOptions = keywordServingOptions(finalQuery);
+  const { allRows, lastPageToken, totalRowsWritten, keywordLimits, observedFields, fileColumns } = await fetchAllPages(
+    finalQuery,
+    body,
+    args,
+    servingOptions
+  );
+  if (args.out) {
+    const truncation = completenessWarnings({
+      rowCount: totalRowsWritten,
+      effectiveLimit: effectiveRowLimit(finalQuery),
+      hasMore: Boolean(lastPageToken)
+    });
+    const fileWarnings = [
+      ...warnings,
+      ...renderKeywordLimits(keywordLimits),
+      ...missingFieldWarningsFor(finalQuery, observedFields, totalRowsWritten),
+      // Only a CSV has a header to fall out of; json and jsonl files carry every row whole.
+      ...isCsvPath(args.out) ? unwrittenColumnWarnings(fileColumns, observedFields) : [],
+      ...conversionMixWarnings(finalQuery),
+      ...moneyUnitWarnings(parseSelectedFields(finalQuery)),
+      ...truncation
+    ];
+    emitToStderr(warningLines(fileWarnings, "csv"));
+    writeAdsJson(
+      buildFileSummary({
+        file: resolve(args.out),
+        rows: totalRowsWritten,
+        warnings: fileWarnings,
+        complete: truncation.length === 0
+      })
+    );
+    return;
+  }
+  if (useCache && !args.all && allRows.length > 0) {
+    const page = { rows: allRows, ...lastPageToken ? { cursor: lastPageToken } : {} };
+    cacheSet("queries", cacheKey, page, getQueryTtl(finalQuery), getFieldDescriptions(extractFields(allRows)));
+  }
+  const fields = extractFields(allRows);
+  outputResults(
+    allRows,
+    getFieldDescriptions(fields),
+    [
+      ...warnings,
+      ...missingFieldWarnings(finalQuery, allRows),
+      ...keywordServingWarnings(allRows, servingOptions),
+      ...conversionMixWarnings(finalQuery),
+      ...moneyUnitWarnings(resultColumns(finalQuery, allRows))
+    ],
+    args,
+    false,
+    {
+      gaql: finalQuery,
+      effectiveLimit: effectiveRowLimit(finalQuery),
+      nextCursor: lastPageToken
+    }
+  );
+}
+function shouldReadCache(args) {
+  return !args["no-cache"] && !args.out && !args.all;
+}
+var DEFAULT_QUERY_LIMIT = 200;
+function parseQueryLimit(raw, fallback = DEFAULT_QUERY_LIMIT) {
+  if (raw === void 0 || raw === null || raw === "") return { ok: true, limit: fallback };
+  const limit = Number(raw);
+  if (Number.isInteger(limit) && limit >= 1 && limit <= GOOGLE_ADS_QUERY_MAX_PAGE_SIZE) return { ok: true, limit };
+  return {
+    ok: false,
+    error: {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `--limit must be a whole number from 1 to ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE}, got '${String(raw)}'.`,
+        fix: {
+          action: "retry_with_flag",
+          explanation: `--limit is the size of one page, at most ${GOOGLE_ADS_QUERY_MAX_PAGE_SIZE} rows. For more rows, keep the page size and add --all --out <file>: it reads every page.`
+        },
+        retryable: false
+      }
+    }
+  };
+}
+function queryPageSize(args) {
+  const preset = typeof args.preset === "string" ? getPreset(args.preset) : void 0;
+  return parseQueryLimit(args.limit, preset?.defaultLimit ?? DEFAULT_QUERY_LIMIT);
+}
+async function validateArgs(args) {
+  const parsedLimit = queryPageSize(args);
+  if (!parsedLimit.ok) {
+    writeAdsJson(parsedLimit.error);
+    process.exit(1);
+  }
+  const { limit } = parsedLimit;
+  const customerId = await resolveCustomerId(args);
+  const gaql = resolveGaql(args);
+  if (!gaql) {
+    process.exit(1);
+  }
+  const preflight = validatePreflight(gaql, customerId);
+  if (!preflight.valid && preflight.error) {
+    writeAdsJson(preflight.error);
+    process.exit(1);
+  }
+  const finalQuery = preflight.correctedQuery ?? gaql;
+  return {
+    customerId,
+    limit,
+    finalQuery,
+    warnings: [...preflight.warnings, ...servingScopeWarnings(args, finalQuery), ...syncedCopyWarnings(args)],
+    useCache: !args["no-cache"],
+    cacheKey: pageCacheKey(customerId, finalQuery, limit, args.cursor)
+  };
+}
+function handleQueryError(err, finalQuery, customerId) {
+  if (err instanceof ApiError) {
+    const envelope = parseApiError(err.message, finalQuery, customerId, err.code);
+    envelope.error.gaqlExecuted = finalQuery;
+    writeAdsJson(envelope);
+    process.exit(1);
+  }
+  writeAdsJson({
+    ok: false,
+    error: {
+      code: "NETWORK_ERROR",
+      message: err instanceof Error ? err.message : "Unexpected error",
+      fix: { action: "wait_and_retry", explanation: "Network error \u2014 check connectivity and retry" },
+      retryable: true,
+      gaqlExecuted: finalQuery
+    }
+  });
+  process.exit(1);
+}
+async function runQuery(args) {
+  const validated = await validateArgs(args);
+  if (!validated) return;
+  const { customerId, limit, finalQuery, warnings, useCache, cacheKey } = validated;
+  if (shouldReadCache(args)) {
+    const cached = cacheGet("queries", cacheKey);
+    if (cached && Array.isArray(cached.data.rows)) {
+      const rows = cached.data.rows;
+      outputResults(
+        rows,
+        cached.fields ?? getFieldDescriptions(extractFields(rows)),
+        [
+          ...warnings,
+          ...missingFieldWarnings(finalQuery, rows),
+          ...keywordServingWarnings(rows, keywordServingOptions(finalQuery)),
+          ...conversionMixWarnings(finalQuery),
+          ...moneyUnitWarnings(resultColumns(finalQuery, rows))
+        ],
+        args,
+        true,
+        { gaql: finalQuery, effectiveLimit: effectiveRowLimit(finalQuery), nextCursor: cached.data.cursor }
+      );
+      return;
+    }
+  }
+  try {
+    await executeQuery(finalQuery, args, customerId, limit, warnings, useCache, cacheKey);
+  } catch (err) {
+    handleQueryError(err, finalQuery, customerId);
+  }
+}
+var queryCommand = defineCommand({
+  meta: {
+    name: "query",
+    description: `Run GAQL against Google Ads, one page at a time. Supports raw GAQL, presets, paging, file export, and caching.
+
+Start here:
+  baker ads google query --list-presets
+  baker ads google query --preset campaign-performance --customer-id 1234567890
+
+Each read returns one page (--limit rows; the preset's page size by default, else 200). When the
+account holds more, the envelope carries pagination.cursor: pass it with --cursor for the next page,
+or read everything with --all --out <file>. A LIMIT written in the GAQL caps the whole read.
+
+Examples:
+  baker ads google query "SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS" --customer-id 1234567890
+  baker ads google query --gaql "SELECT ad_group.name FROM ad_group WHERE ad_group.status = 'ENABLED'" --customer-id 1234567890
+  baker ads google query --preset search-terms --customer-id 1234567890 --date-range LAST_7_DAYS --all --out terms.csv
+  baker ads google query --preset keyword-serving --customer-id 1234567890 --cursor <pagination.cursor>`
+  },
+  args: {
+    query: { type: "positional", description: "GAQL SELECT statement", required: false },
+    gaql: {
+      type: "string",
+      description: "GAQL SELECT statement as a flag (instead of the positional)",
+      required: false
+    },
+    "customer-id": { type: "string", description: "Google Ads customer ID (10 digits, no dashes)", required: false },
+    preset: { type: "string", description: "Named query preset", required: false },
+    "date-range": { type: "string", description: "Date range override for presets", required: false },
+    "include-paused": {
+      type: "boolean",
+      description: "Include paused entities in preset results (default: serving entities only)",
+      required: false
+    },
+    limit: {
+      type: "string",
+      description: "Rows per page (default: the preset's page size, else 200)",
+      required: false
+    },
+    "list-presets": { type: "boolean", description: "List available presets", required: false },
+    cursor: { type: "string", description: "pagination.cursor from the previous page", required: false },
+    all: { type: "boolean", description: "Follow every page (use with --out for large reads)", required: false },
+    out: { type: "string", description: "File path for output", required: false },
+    append: { type: "boolean", description: "Append to file", required: false },
+    output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false },
+    full: { type: "boolean", description: "Include the field description glossary", required: false }
+  },
+  run: async ({ args }) => {
+    if (args["list-presets"]) {
+      writeAdsJson({
+        ok: true,
+        data: PRESETS.map((p) => ({
+          name: p.name,
+          description: p.description,
+          defaultDateRange: p.defaultDateRange,
+          pageSize: p.defaultLimit,
+          servingOnly: (p.statusFields?.length ?? 0) > 0,
+          gaql: expandPreset(p, {}).query
+        }))
+      });
+      return;
+    }
+    await runQuery(args);
+  }
+});
+
+export {
+  resultColumns,
+  effectiveRowLimit,
+  warningLines,
+  completenessWarnings,
+  buildQueryEnvelope,
+  summariseWarnings,
+  buildFileSummary,
+  outputResults,
+  resolveGaqlInput,
+  servingScopeWarnings,
+  parseSelectedFields,
+  unobservedSelectedFields,
+  unobservedFields,
+  missingFieldWarnings,
+  missingFieldWarningsFor,
+  unwrittenColumnWarnings,
+  keywordServingOptions,
+  pageCacheKey,
+  shouldReadCache,
+  parseQueryLimit,
+  queryPageSize,
+  runQuery,
+  queryCommand
+};
+//# sourceMappingURL=chunk-OWEON2S7.js.map