@koda-sl/baker-cli 0.150.0-dev.a970fa118 → 0.151.0-dev.1a051172a

package/README.md

@@ -300,11 +300,22 @@ When a query fails, the error includes a `fix` object with the exact corrected c
 
 ### `baker ads google changes`
 
-Get recent change logs for an account.
+Read the change history of an account.
+
+Google keeps account history in two layers, and neither reaches past 90 days:
+
+| Scope       | Reach   | What you get                                                        |
+|-------------|---------|---------------------------------------------------------------------|
+| `detail`    | 30 days | What changed, old → new value, and who changed it                   |
+| `summary`   | 90 days | Which resources were added, changed or removed — no values, no user  |
+
+Beyond 90 days there is no API. Infer the change from a monthly spend trend per campaign
+instead, or ask the user to check the change history in the Google Ads web UI.
 
 ```bash
 baker ads google changes --customer-id 1234567890
 baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMPAIGN
+baker ads google changes --customer-id 1234567890 --days 60 --scope summary
 ```
 
 **Flags:**
@@ -312,7 +323,8 @@ baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMP
 | Flag              | Description                                                   |
 |-------------------|---------------------------------------------------------------|
 | `--customer-id`   | Google Ads customer ID. Falls back to `BAKER_GOOGLE_ADS_CUSTOMER_ID` env var. |
-| `--days`          | Lookback days (default 7, max 90)                             |
+| `--scope`         | `detail` (default, 30 days) or `summary` (90 days)            |
+| `--days`          | Lookback days (default 7). Max 30 with `detail`, 90 with `summary` |
 | `--resource-type` | Filter: CAMPAIGN, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION   |
 | `--limit`         | Max results (default 50)                                      |
 | `--output`        | Format: `json` \| `csv` \| `jsonl` \| `md`                   |
@@ -4671,6 +4683,7 @@ baker brand fonts fetch "Inter" --subsets latin,latin-ext  # add accented-glyph
 ```
 
 - **`check`** asks Google Fonts what it *actually* serves for every family and weight `src/styles/global.css` requests, and reports `requested` / `served` / `missing` plus the available unicode subsets. It exits 2 with `FONT_NOT_SERVED` when the brand asks for something Google won't serve, and distinguishes an unknown family name from a family that exists at other weights — the fix differs.
+- **Failures carry the numbers, so nothing needs a second call.** `check`'s error keeps the full per-family breakdown at `error.fix.families` (healthy families included, so a multi-family brand shows what not to touch), and both commands probe the standard weights to report the ones that *do* exist at `error.fix.served` — the remediation is "retry with one of these" rather than "run `check`", which would be the command that just failed.
 - **`fetch`** downloads the family into `src/brand/fonts/` and prints the `@font-face` block to paste above `@theme`. Defaults to the `latin` subset; `--subsets latin,latin-ext` adds accented-glyph coverage for Spanish and Portuguese copy. One file per weight *and* subset, since Google ships them separately and `unicode-range` is carried through verbatim.
 - **It does not edit `global.css` for you.** Paste the block, then drop that family from the Google `@import` — otherwise the page self-hosts *and* still calls Google. Record the weights in `src/brand/BRAND.md` in the same change.
 - **Licensing:** Google Fonts are open-licensed and safe to self-host. A client's own commercial typeface is not — confirm before re-hosting one.

package/dist/cli.js

@@ -4042,11 +4042,21 @@ var FIELD_DESCRIPTIONS = {
   "asset_group.status": "ENABLED, PAUSED, or REMOVED",
   "asset_group_asset.field_type": "Where the asset is used (HEADLINE, DESCRIPTION, LOGO, etc.)",
   "asset_group_asset.performance_label": "Performance rating: BEST, GOOD, LOW, LEARNING",
-  // Change events
+  // Change events (field-level detail, last 30 days)
   "change_event.change_date_time": "When the change occurred (ISO 8601)",
   "change_event.change_resource_type": "What was changed: CAMPAIGN, AD_GROUP, AD, etc.",
   "change_event.resource_change_operation": "CREATE, UPDATE, or REMOVE",
   "change_event.user_email": "Email of user who made the change",
+  // Change status (which resources changed, last 90 days — no values, no user)
+  "change_status.last_change_date_time": "When this resource last changed (ISO 8601)",
+  "change_status.resource_type": "What changed: CAMPAIGN, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, etc.",
+  "change_status.resource_status": "ADDED, CHANGED, or REMOVED \u2014 not the old or new value",
+  "change_status.resource_name": "Identifier of the changed resource; query it to read its current values",
+  "change_status.campaign": "Resource name of the campaign the change belongs to",
+  "change_status.ad_group": "Resource name of the ad group the change belongs to",
+  "change_status.ad_group_ad": "Resource name of the changed ad",
+  "change_status.ad_group_criterion": "Resource name of the changed keyword or criterion",
+  "change_status.campaign_criterion": "Resource name of the changed campaign-level criterion",
   // Landing pages
   "landing_page_view.unexpanded_final_url": "Landing page URL",
   // Geo
@@ -4064,6 +4074,89 @@ function getFieldDescriptions(fields) {
   return result;
 }
 
+// src/commands/ads/google/changes-window.ts
+var CHANGE_SCOPE_MAX_DAYS = {
+  detail: 30,
+  summary: 90
+};
+var DEFAULT_CHANGE_DAYS = 7;
+function isChangeScope(value) {
+  return value === "detail" || value === "summary";
+}
+function resolveChangesWindow(input) {
+  const scope = input.scope ?? "detail";
+  if (!isChangeScope(scope)) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_SCOPE",
+        message: `Unknown scope '${scope}'. Use 'detail' (field-level changes, 30 days) or 'summary' (which resources changed, 90 days).`,
+        fix: {
+          action: "retry_with_flag",
+          explanation: "Pass --scope detail or --scope summary."
+        }
+      }
+    };
+  }
+  const days = input.days ?? DEFAULT_CHANGE_DAYS;
+  if (!Number.isInteger(days) || days < 1) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_LOOKBACK",
+        message: `--days must be a whole number of days, got '${days}'.`,
+        fix: {
+          action: "retry_with_flag",
+          explanation: `Pass --days as a positive integer, e.g. --days ${DEFAULT_CHANGE_DAYS}.`
+        }
+      }
+    };
+  }
+  const max = CHANGE_SCOPE_MAX_DAYS[scope];
+  if (days > max) {
+    return { ok: false, error: lookbackTooLong(scope, days, max) };
+  }
+  return { ok: true, scope, days, hints: hintsFor(scope, days) };
+}
+function lookbackTooLong(scope, days, max) {
+  if (scope === "detail" && days <= CHANGE_SCOPE_MAX_DAYS.summary) {
+    return {
+      code: "LOOKBACK_TOO_LONG",
+      message: `Google keeps field-level change detail for ${max} days only; ${days} days is outside that window.`,
+      fix: {
+        action: "narrow_date_range",
+        explanation: `Re-run with --scope summary --days ${days} to reach back ${CHANGE_SCOPE_MAX_DAYS.summary} days. Summary tells you which campaigns, ad groups, ads and criteria changed and when, but not the old and new values \u2014 read the resource itself for current values.`
+      }
+    };
+  }
+  return {
+    code: "LOOKBACK_TOO_LONG",
+    message: `Google's account history API reaches back ${CHANGE_SCOPE_MAX_DAYS.summary} days at most; ${days} days is outside that window.`,
+    fix: {
+      action: "use_different_resource",
+      explanation: "Do not abort \u2014 infer the change from performance instead. Query monthly metrics per campaign (SELECT campaign.name, segments.month, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_12_MONTHS) to see which campaigns stopped or started spending. That shows what changed and when, though not who changed it. Older history exists only in the Google Ads web UI, which has no API \u2014 ask the user to check it if the 'who' matters."
+    }
+  };
+}
+function hintsFor(scope, days) {
+  const hints = [];
+  if (scope === "detail") {
+    hints.push(
+      `Detailed history covers the last ${CHANGE_SCOPE_MAX_DAYS.detail} days. For anything older use --scope summary (reaches ${CHANGE_SCOPE_MAX_DAYS.summary} days, reports which resources changed but not their values).`
+    );
+  } else {
+    hints.push(
+      "Summary history reports which resources changed and when, not old and new values. To see what a changed resource looks like now, query it by resource_name."
+    );
+    if (days > CHANGE_SCOPE_MAX_DAYS.detail) {
+      hints.push(
+        `Changes inside the last ${CHANGE_SCOPE_MAX_DAYS.detail} days also have field-level detail \u2014 re-run with --scope detail for those.`
+      );
+    }
+  }
+  return hints;
+}
+
 // src/commands/ads/google/correction-table.ts
 function buildCommand(query, ctx) {
   return `baker ads google query "${query}" --customer-id ${ctx.customerId}`;
@@ -4392,6 +4485,35 @@ var CORRECTION_RULES = [
       };
     }
   },
+  // 20a. change_event past its 30-day reach → change_status, which reaches 90 days.
+  // The enum prefix in the API message is what separates this from the change_status
+  // case below; a bare START_DATE_TOO_OLD falls through to the query-pattern pass,
+  // which routes on the resource the caller actually queried.
+  {
+    matchQuery: /FROM\s+change_event\b/i,
+    matchApiError: /ChangeEventError\.START_DATE_TOO_OLD/i,
+    fix: (ctx) => {
+      const limit = ctx.originalQuery.match(/LIMIT\s+(\d+)/i)?.[1] ?? "50";
+      const requested = ctx.originalQuery.match(/change_date_time\s*>=\s*'([^']+)'/i)?.[1]?.slice(0, 10);
+      const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
+      const start = requested && requested > ninetyDaysAgo ? requested : ninetyDaysAgo;
+      const corrected = `SELECT change_status.last_change_date_time, change_status.resource_type, change_status.resource_status, change_status.resource_name, change_status.campaign, change_status.ad_group FROM change_status WHERE change_status.last_change_date_time >= '${start}' ORDER BY change_status.last_change_date_time DESC LIMIT ${limit}`;
+      return {
+        action: "use_different_resource",
+        correctedCommand: buildCommand(corrected, ctx),
+        explanation: `change_event only reaches back 30 days. change_status reaches 90 (from ${start}) but reports only which resources changed and whether they were added, changed or removed \u2014 no old/new values and no user email. Read a changed resource by its resource_name to see its current values.`
+      };
+    }
+  },
+  // 20b. Past 90 days no history resource reaches — infer the change from spend instead.
+  {
+    matchQuery: /FROM\s+change_status\b/i,
+    matchApiError: /ChangeStatusError\.START_DATE_TOO_OLD/i,
+    fix: () => ({
+      action: "use_different_resource",
+      explanation: "Google's account history reaches back 90 days at most, and this query asks for more. Do not abort \u2014 infer the change from performance: SELECT campaign.name, segments.month, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_12_MONTHS shows which campaigns started or stopped spending and when, though not who changed them. Anything older with attribution exists only in the Google Ads web UI, which has no API."
+    })
+  },
   // 20. change_event without date constraint
   {
     matchQuery: /FROM\s+change_event\b(?!.*change_date_time)/i,
@@ -4545,14 +4667,25 @@ function parseApiError(errorMessage, originalQuery, customerId) {
 // src/commands/ads/google/changes.ts
 registerSchema({
   command: "ads.google.changes",
-  description: "Get recent change logs with performance impact. Shows what changed and how it affected metrics.",
+  description: "Read the account's change history. --scope detail (default) shows what changed and to what value, back 30 days; --scope summary shows which resources changed, back 90 days.",
   args: {
     "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
     },
-    days: { type: "string", description: "Lookback days (default: 7, max: 90)", required: false, default: 7 },
+    days: {
+      type: "string",
+      description: `Lookback days (default: ${DEFAULT_CHANGE_DAYS}). Max ${CHANGE_SCOPE_MAX_DAYS.detail} with --scope detail, ${CHANGE_SCOPE_MAX_DAYS.summary} with --scope summary. Google keeps nothing older behind any API.`,
+      required: false,
+      default: DEFAULT_CHANGE_DAYS
+    },
+    scope: {
+      type: "string",
+      description: `detail|summary (default: detail). detail = old/new values plus who made the change, ${CHANGE_SCOPE_MAX_DAYS.detail} days. summary = which resources were added, changed or removed, ${CHANGE_SCOPE_MAX_DAYS.summary} days, without values.`,
+      required: false,
+      default: "detail"
+    },
     "resource-type": {
       type: "string",
       description: "Filter by type: CAMPAIGN, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION",
@@ -4565,15 +4698,24 @@ registerSchema({
 var changesCommand = defineCommand20({
   meta: {
     name: "changes",
-    description: `Get recent changes in a Google Ads account with performance data.
+    description: `Read the change history of a Google Ads account.
+
+Google keeps account history in two layers, and neither reaches past 90 days:
+  --scope detail  (default)  what changed, old \u2192 new value, who changed it   \u2014 last ${CHANGE_SCOPE_MAX_DAYS.detail} days
+  --scope summary            which resources were added, changed or removed  \u2014 last ${CHANGE_SCOPE_MAX_DAYS.summary} days
+
+For anything older, infer it from performance instead \u2014 a monthly spend trend per
+campaign shows what started or stopped, just not who did it.
 
 Examples:
   baker ads google changes --customer-id 1234567890
-  baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMPAIGN`
+  baker ads google changes --customer-id 1234567890 --days 14 --resource-type CAMPAIGN
+  baker ads google changes --customer-id 1234567890 --days 60 --scope summary`
   },
   args: {
     "customer-id": { type: "string", description: "Google Ads customer ID", required: false },
-    days: { type: "string", description: "Lookback days (default 7)", required: false },
+    days: { type: "string", description: `Lookback days (default ${DEFAULT_CHANGE_DAYS})`, required: false },
+    scope: { type: "string", description: "detail (30 days) or summary (90 days)", required: false },
     "resource-type": { type: "string", description: "Filter by resource type", required: false },
     limit: { type: "string", description: "Max results (default 50)", required: false },
     "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
@@ -4581,9 +4723,19 @@ Examples:
   },
   run: async ({ args }) => {
     const customerId = await resolveCustomerId(args);
+    const window = resolveChangesWindow({
+      days: args.days ? Number(args.days) : void 0,
+      scope: args.scope
+    });
+    if (!window.ok) {
+      writeJsonEnvelope({ ok: false, error: { ...window.error, retryable: false } });
+      process.exit(1);
+      return;
+    }
     const body = {
       customerId,
-      days: args.days ? Number(args.days) : 7,
+      days: window.days,
+      scope: window.scope,
       limit: args.limit ? Number(args.limit) : 50
     };
     const managerId = getManagerIdForCustomer(customerId);
@@ -4600,7 +4752,7 @@ Examples:
       const first = data[0];
       const fields = first ? Object.keys(first) : [];
       const fieldDescs = getFieldDescriptions(fields);
-      writeAdsJson({ ok: true, data, fields: fieldDescs });
+      writeJsonEnvelope({ ok: true, data, fields: fieldDescs, hints: window.hints });
     } catch (err) {
       if (err instanceof ApiError) {
         writeAdsJson(parseApiError(err.message, "", customerId));
@@ -15369,11 +15521,46 @@ function resolveFetchWeights(flag, declared) {
   return declared?.length ? declared : [400];
 }
 function googleFontCssUrl(family, weights) {
-  const name = family.trim().replace(/\s+/g, "+");
+  const name = family.trim().split(/\s+/).map(encodeURIComponent).join("+");
   const axis = [...new Set(weights)].sort((a, b) => a - b).join(";");
   const spec = axis ? `${name}:wght@${axis}` : name;
   return `${GOOGLE_CSS2}?family=${spec}&display=swap`;
 }
+var STANDARD_WEIGHTS = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+async function probeServedWeights(family, fetchCss) {
+  const probes = await Promise.all(
+    STANDARD_WEIGHTS.map(async (weight) => await fetchCss(googleFontCssUrl(family, [weight])) ? weight : null)
+  );
+  return probes.filter((w) => w !== null);
+}
+async function checkFontRequests(requests, fetchCss) {
+  const results = [];
+  for (const request of requests) {
+    const css = await fetchCss(googleFontCssUrl(request.family, request.weights));
+    if (css === null) {
+      const served2 = await probeServedWeights(request.family, fetchCss);
+      results.push({
+        family: request.family,
+        requested: request.weights,
+        served: served2,
+        missing: request.weights.filter((w) => !served2.includes(w)),
+        subsets: [],
+        cause: served2.length === 0 ? "unknown-family" : "unavailable-weight"
+      });
+      continue;
+    }
+    const faces = parseGoogleFontFaces(css);
+    const served = [...new Set(faces.map((f) => f.weight))].sort((a, b) => a - b);
+    results.push({
+      family: request.family,
+      requested: request.weights,
+      served,
+      missing: request.weights.filter((w) => !served.includes(w)),
+      subsets: [...new Set(faces.map((f) => f.subset))]
+    });
+  }
+  return results;
+}
 
 // src/commands/brand/fonts.ts
 var GLOBAL_CSS = path.join("src", "styles", "global.css");
@@ -15406,19 +15593,19 @@ function fail(code, message, fix) {
   writeJson({ ok: false, error: { code, message, ...fix ? { fix } : {} } });
   process.exit(2);
 }
+var REQUEST_TIMEOUT_MS = 15e3;
 async function fetchGoogleCss(url) {
   try {
-    const res = await fetch(url, { headers: { "User-Agent": BROWSER_UA } });
+    const res = await fetch(url, {
+      headers: { "User-Agent": BROWSER_UA },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
     if (!res.ok) return null;
     return await res.text();
   } catch {
     return null;
   }
 }
-async function diagnoseUnserved(family) {
-  const bare = await fetchGoogleCss(googleFontCssUrl(family, []));
-  return bare === null ? "unknown-family" : "unavailable-weight";
-}
 async function readGlobalCss() {
   try {
     return await readFile(path.resolve(process.cwd(), GLOBAL_CSS), "utf8");
@@ -15444,41 +15631,20 @@ var fontsCheckCommand = defineCommand85({
       });
       return;
     }
-    const families = [];
-    const unavailable = [];
-    for (const request of requests) {
-      const url = googleFontCssUrl(request.family, request.weights);
-      const served = await fetchGoogleCss(url);
-      if (served === null) {
-        const cause = await diagnoseUnserved(request.family);
-        unavailable.push(
-          cause === "unknown-family" ? `${request.family} (no such family on Google Fonts \u2014 check the exact spelling)` : `${request.family} ${request.weights.join("/")} (the family exists, these weights do not)`
-        );
-        families.push({
-          family: request.family,
-          requested: request.weights,
-          served: [],
-          missing: request.weights,
-          cause
-        });
-        continue;
-      }
-      const faces = parseGoogleFontFaces(served);
-      const servedWeights = [...new Set(faces.map((f) => f.weight))].sort((a, b) => a - b);
-      const missing = request.weights.filter((w) => !servedWeights.includes(w));
-      if (missing.length > 0) unavailable.push(`${request.family} ${missing.join("/")}`);
-      families.push({
-        family: request.family,
-        requested: request.weights,
-        served: servedWeights,
-        missing,
-        subsets: [...new Set(faces.map((f) => f.subset))]
-      });
-    }
-    if (unavailable.length > 0) {
-      fail("FONT_NOT_SERVED", `Google Fonts does not serve: ${unavailable.join("; ")}`, {
-        action: `Correct the family name or weight in ${GLOBAL_CSS} and src/brand/BRAND.md, or run \`baker brand fonts fetch\` for a weight that does exist.`,
-        explanation: "A requested weight Google does not serve is silently synthesized by the browser, so the page looks subtly wrong with nothing failing."
+    const families = await checkFontRequests(requests, fetchGoogleCss);
+    const broken = families.filter((f) => f.missing.length > 0);
+    if (broken.length > 0) {
+      const summary = broken.map(
+        (f) => f.cause === "unknown-family" ? `${f.family} (no such family on Google Fonts \u2014 check the exact spelling)` : `${f.family} ${f.missing.join("/")} (served: ${f.served.join("/") || "none"})`
+      ).join("; ");
+      fail("FONT_NOT_SERVED", `Google Fonts does not serve: ${summary}`, {
+        action: `Correct the family name or weight in ${GLOBAL_CSS} and src/brand/BRAND.md, picking from the \`served\` weights below.`,
+        explanation: "A requested weight Google does not serve is silently synthesized by the browser, so the page looks subtly wrong with nothing failing.",
+        // The per-family breakdown is the point of the command, so it ships on
+        // the failure path too — otherwise the only remedy is re-running the
+        // command that just failed. Healthy families are included so a
+        // multi-family brand shows what NOT to touch.
+        families
       });
     }
     writeJson({
@@ -15515,16 +15681,18 @@ var fontsFetchCommand = defineCommand85({
     );
     const servedCss = await fetchGoogleCss(googleFontCssUrl(family, weights));
     if (servedCss === null) {
-      const cause = await diagnoseUnserved(family);
+      const [diagnosis] = await checkFontRequests([{ family, weights }], fetchGoogleCss);
+      const served = diagnosis?.served ?? [];
       fail(
         "FONT_NOT_SERVED",
-        cause === "unknown-family" ? `Google Fonts has no family called "${family}".` : `"${family}" exists on Google Fonts but not at weight ${weights.join("/")}.`,
-        cause === "unknown-family" ? {
+        served.length === 0 ? `Google Fonts has no family called "${family}".` : `"${family}" exists on Google Fonts but not at weight ${weights.join("/")}.`,
+        served.length === 0 ? {
           action: "Check the exact family name at fonts.google.com, then retry.",
           explanation: "Family names are case- and space-sensitive in the Google Fonts API."
         } : {
-          action: `Run \`baker brand fonts check\` to see which weights this family really ships, then retry with --weights set to one of those.`,
-          explanation: "Google rejects the whole request when one requested weight does not exist."
+          action: `Retry with --weights set to one of these: ${served.join(",")}.`,
+          explanation: "Google rejects the whole request when one requested weight does not exist.",
+          served
         }
       );
     }
@@ -15539,7 +15707,10 @@ var fontsFetchCommand = defineCommand85({
     await mkdir(fontsDir, { recursive: true });
     const downloaded = [];
     for (const face of faces) {
-      const res = await fetch(face.url, { headers: { "User-Agent": BROWSER_UA } });
+      const res = await fetch(face.url, {
+        headers: { "User-Agent": BROWSER_UA },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
       if (!res.ok) continue;
       await writeFile(path.join(fontsDir, fontFileName(face)), Buffer.from(await res.arrayBuffer()));
       downloaded.push(face);