@koda-sl/baker-cli 0.553.0 → 0.555.0

package/dist/google-ads-RRKKSKDD.js

@@ -0,0 +1,198 @@
+import {
+  googleAdsHints
+} from "./chunk-UCJAPB5Y.js";
+import {
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-CXYX6G3I.js";
+import {
+  RESEARCH_GOOGLE_ADS_DEFAULT_LIMIT,
+  RESEARCH_GOOGLE_ADS_MAX_COPY,
+  RESEARCH_GOOGLE_ADS_MAX_LIMIT,
+  researchGoogleAdsFormatSchema,
+  researchGoogleAdsPlatformSchema
+} from "./chunk-MKLAZD23.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-MSMTG6OC.js";
+import {
+  apiPost
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/google-ads.ts
+import { defineCommand } from "citty";
+var TIMEOUT_MS = 18e4;
+var PLATFORMS = researchGoogleAdsPlatformSchema.options;
+var FORMATS = ["all", ...researchGoogleAdsFormatSchema.options];
+registerSchema({
+  command: "research.google-ads",
+  description: "A competitor's Google ads, from Google's Ads Transparency Center: who runs each one, its format (text, image, video), when it was first and last shown and how many days it has run \u2014 the longest-running are the ones that pay. With --copy, the headline, description and display URL of up to 20 text ads. Start here: `baker research google-ads <competitor.com> --location <cc> --copy`. Never drive the Transparency Center in a browser instead.",
+  args: {
+    target: {
+      type: "string",
+      description: "Competitor domain (competitor.com, or any URL on it) or a Transparency advertiser id (AR\u2026)",
+      required: true
+    },
+    location: {
+      type: "string",
+      description: "Country code (es, mx, us\u2026) where the ads were shown. Omit for every region",
+      required: false
+    },
+    platform: { type: "string", description: "Where they ran", required: false, enum: [...PLATFORMS] },
+    format: { type: "string", description: "Only one ad format", required: false, enum: [...FORMATS] },
+    since: { type: "string", description: "Only ads shown on or after this day (YYYY-MM-DD)", required: false },
+    limit: {
+      type: "number",
+      description: `Max ads (1-${RESEARCH_GOOGLE_ADS_MAX_LIMIT}, default ${RESEARCH_GOOGLE_ADS_DEFAULT_LIMIT}; billed per 40)`,
+      required: false
+    },
+    copy: {
+      type: "boolean",
+      description: `Read headline, description and display URL of up to ${RESEARCH_GOOGLE_ADS_MAX_COPY} text ads`,
+      required: false,
+      default: false
+    },
+    full: {
+      type: "boolean",
+      description: "Add creative/advertiser ids, verification and preview image URL",
+      required: false,
+      default: false
+    }
+  }
+});
+var FIELDS = {
+  advertiser: "The Google Ads account that runs the ad (a brand can run several)",
+  format: "text | image | video",
+  first_shown: "First day Google showed it (UTC)",
+  last_shown: "Most recent day Google showed it (UTC) \u2014 recent means still running",
+  days_running: "First to last shown, inclusive: how long the advertiser has kept paying for it",
+  copy: "headline / description / display_url, read off the text ad's image (--copy); null otherwise",
+  transparency_url: "The ad on Google's Ads Transparency Center \u2014 the link to show the user"
+};
+function compact(ad) {
+  return {
+    advertiser: ad.advertiser,
+    format: ad.format,
+    first_shown: ad.first_shown,
+    last_shown: ad.last_shown,
+    days_running: ad.days_running,
+    copy: ad.copy,
+    transparency_url: ad.transparency_url
+  };
+}
+function googleAdsFix(code) {
+  if (code === "BAD_REQUEST" || code === "VALIDATION_ERROR") {
+    return {
+      action: "retry_with_changes",
+      explanation: "Pass the competitor's domain (competitor.com) or an advertiser id (AR\u2026), and check the flag values."
+    };
+  }
+  return {
+    action: "continue_without",
+    explanation: "This read failed. Finish the rest of the job and name the competitor's Google ads as a gap \u2014 do not open the Transparency Center in a browser instead."
+  };
+}
+function invalid(message) {
+  writeResearchJson({ ok: false, error: { code: "VALIDATION_ERROR", message, fix: googleAdsFix("VALIDATION_ERROR") } });
+  process.exit(1);
+}
+var googleAdsCommand = defineCommand({
+  meta: {
+    name: "google-ads",
+    description: `A competitor's Google ads, read from Google's Ads Transparency Center \u2014 no browser. Each ad: who runs it, format, first and last shown, days running, and its Transparency link. --copy reads the headline and description of the text ads.
+
+Examples:
+  baker research google-ads competitor.com --location es --copy
+  baker research google-ads competitor.com --platform google_search --format text --copy
+  baker research google-ads competitor.com --since 2026-07-01 --limit 80
+  baker research google-ads AR06744629793381154817 --output md`
+  },
+  args: {
+    target: { type: "positional", description: "Competitor domain or advertiser id (AR\u2026)", required: false },
+    location: {
+      type: "string",
+      description: "Country code where the ads were shown (default: every region)",
+      required: false
+    },
+    platform: { type: "string", description: `${PLATFORMS.join("|")} (default all)`, required: false },
+    format: { type: "string", description: `${FORMATS.join("|")} (default all)`, required: false },
+    since: { type: "string", description: "Only ads shown on or after YYYY-MM-DD", required: false },
+    limit: {
+      type: "string",
+      description: `Max ads (default ${RESEARCH_GOOGLE_ADS_DEFAULT_LIMIT}, max ${RESEARCH_GOOGLE_ADS_MAX_LIMIT})`,
+      required: false
+    },
+    copy: { type: "boolean", description: "Read the text ads' headline and description", required: false },
+    full: { type: "boolean", description: "Add ids, verification and preview image URL", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip the 6h server cache", required: false }
+  },
+  run: async ({ args }) => {
+    const target = args.target?.trim();
+    if (!target) invalid("A competitor domain or advertiser id is required");
+    const platform = args.platform ?? "all";
+    if (!researchGoogleAdsPlatformSchema.safeParse(platform).success) {
+      invalid(`--platform must be one of ${PLATFORMS.join(", ")}`);
+    }
+    const format = args.format ?? "all";
+    if (!FORMATS.includes(format)) invalid(`--format must be one of ${FORMATS.join(", ")}`);
+    const body = {
+      target,
+      platform,
+      format,
+      copy: Boolean(args.copy)
+    };
+    if (args.location) body.location = args.location;
+    if (args.since) body.since = args.since;
+    if (args.limit) body.limit = Number(args.limit);
+    if (args["no-cache"]) body.skipCache = true;
+    try {
+      const result = await apiPost("/api/research/google-ads", body, {
+        timeoutMs: TIMEOUT_MS
+      });
+      const hints = googleAdsHints({
+        target: result.target,
+        adCount: result.ads.length,
+        located: body.location !== void 0,
+        textWithoutCopy: result.ads.filter((ad) => ad.format === "text" && ad.copy === null).length,
+        copyAsked: body.copy === true,
+        copyUnread: result.copy_unread,
+        visual: result.ads.filter((ad) => ad.format !== "text").length
+      });
+      const ads = args.full ? result.ads : result.ads.map(compact);
+      const output = args.output || "json";
+      if (output !== "json") {
+        writeResearchOutput(ads, output);
+        writeResearchHints(hints, output);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        data: ads,
+        fields: FIELDS,
+        target: result.target,
+        total_ads: result.total_ads,
+        check_url: result.check_url,
+        hints
+      });
+    } catch (err) {
+      handleResearchError(err, googleAdsFix);
+    }
+  }
+});
+export {
+  googleAdsCommand
+};
+//# sourceMappingURL=google-ads-RRKKSKDD.js.map

package/dist/history-2UANIBRN.js

@@ -0,0 +1,102 @@
+import {
+  failApi,
+  failValidation,
+  validateScheduledAgentRef
+} from "./chunk-7BVRFQN4.js";
+import "./chunk-WR5Y64OE.js";
+import "./chunk-MKLAZD23.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-MSMTG6OC.js";
+import {
+  apiPost
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/scheduled-agents/history.ts
+import { defineCommand } from "citty";
+var ONLY_DESCRIPTION = "ran: only the firings that opened a run. skipped: only the ones that did not \u2014 its rules or its AI check turned down what arrived, its last run was still going, its quiet period, not one of its times, switched off.";
+var LIMIT_DESCRIPTION = "How many lines on this page, 1\u2013200. Default 50.";
+var CURSOR_DESCRIPTION = "The nextCursor of the previous page, to read older firings. Left out, the newest page.";
+var FULL_DESCRIPTION = "Include what arrived with each firing (emails and phones masked).";
+registerSchema({
+  command: "scheduled-agents.history",
+  description: "Every time a published scheduled agent's trigger fired, newest first, and what became of it: `ran` with the run's chatId and runStatus, or why it did not run (rules, ai_check with the AI check's score, busy, already_handled, cooling_down, occurrence, paused, closed). Start here when the user asks why an agent did or did not run. --full adds what arrived. Paged, newest first: pass the returned nextCursor as --cursor for older firings.",
+  args: {
+    id: { type: "string", description: "Published scheduled agent ID", required: true },
+    limit: { type: "string", description: LIMIT_DESCRIPTION, required: false },
+    cursor: { type: "string", description: CURSOR_DESCRIPTION, required: false },
+    only: { type: "string", description: ONLY_DESCRIPTION, required: false, enum: ["ran", "skipped"] },
+    full: { type: "boolean", description: FULL_DESCRIPTION, required: false }
+  }
+});
+var historyCommand = defineCommand({
+  meta: {
+    name: "history",
+    description: "What happened each time a scheduled agent was triggered: the runs, and the firings that did not run and why. Start here: baker scheduled-agents history <id> | baker scheduled-agents history <id> --only skipped --full"
+  },
+  args: {
+    id: { type: "positional", description: "Published scheduled agent ID", required: false },
+    "scheduled-agent-id": {
+      type: "string",
+      description: "Scheduled agent ID (alternative to positional)",
+      required: false
+    },
+    limit: { type: "string", description: LIMIT_DESCRIPTION, required: false },
+    cursor: { type: "string", description: CURSOR_DESCRIPTION, required: false },
+    only: { type: "string", description: ONLY_DESCRIPTION, required: false },
+    full: { type: "boolean", description: FULL_DESCRIPTION, required: false, default: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const id = args.id || args["scheduled-agent-id"];
+      if (!id) {
+        failValidation("Scheduled agent ID is required.");
+      }
+      validateScheduledAgentRef(id);
+      const body = {
+        id,
+        ...historyLimit(args.limit),
+        ...typeof args.cursor === "string" && args.cursor.length > 0 ? { cursor: args.cursor } : {},
+        ...historyOnly(args.only),
+        ...args.full === true ? { full: true } : {}
+      };
+      writeJson(await apiPost("/api/scheduled-agents/history", body));
+    } catch (err) {
+      failApi(err);
+    }
+  }
+});
+function historyLimit(raw) {
+  if (raw === void 0) {
+    return {};
+  }
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+    failValidation("--limit must be a whole number from 1 to 200.");
+  }
+  return { limit };
+}
+function historyOnly(raw) {
+  if (raw === void 0) {
+    return {};
+  }
+  if (raw !== "ran" && raw !== "skipped") {
+    failValidation("--only must be ran or skipped.");
+  }
+  return { only: raw };
+}
+export {
+  historyCommand
+};
+//# sourceMappingURL=history-2UANIBRN.js.map

package/dist/history-YZ727ZRG.js

@@ -0,0 +1,153 @@
+import {
+  failApi
+} from "./chunk-BS2MC62Y.js";
+import "./chunk-MKLAZD23.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-MSMTG6OC.js";
+import {
+  apiPost
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/history/index.ts
+import { defineCommand } from "citty";
+var CURSOR_DESCRIPTION = "The meta.nextCursor of the previous page, to read the entries older than it (same --days and --category). Left out, the newest page.";
+registerSchema({
+  command: "history.list",
+  description: "Start here: unified account history (audit log) \u2014 everything that changed on this account, newest first: publishes, chat lifecycle, backlog actions, team changes, setup links, tags, schedules, ad-platform writes, followed advertisers, media, creatives, reports, domains, and integrations. Use it to see what happened recently before planning work. Compact by default; add --full for raw metadata per entry. Paged, newest first: meta.hasMore says older entries exist, and passing meta.nextCursor as --cursor reads them.",
+  args: {
+    limit: {
+      type: "string",
+      description: "Max entries to return, 1-200 (default: 30)",
+      required: false
+    },
+    cursor: { type: "string", description: CURSOR_DESCRIPTION, required: false },
+    category: {
+      type: "string",
+      description: "Filter: publish|chat|action|team|setup_link|company|tag|schedule|ads|advertiser|media|creative|report|domain|integration",
+      required: false
+    },
+    days: {
+      type: "string",
+      description: "Only entries from the last N days (1-365)",
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "Include raw metadata for each entry",
+      required: false,
+      default: false
+    }
+  }
+});
+var CATEGORIES = [
+  "publish",
+  "chat",
+  "action",
+  "team",
+  "setup_link",
+  "company",
+  "tag",
+  "schedule",
+  "ads",
+  "advertiser",
+  "media",
+  "creative",
+  "report",
+  "domain",
+  "integration"
+];
+function parseBoundedInt(raw, name, min, max) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const value = Number.parseInt(raw, 10);
+  if (Number.isNaN(value) || value < min || value > max) {
+    throw new Error(`--${name} must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+function fullPageHint(entries, nextCursor, days) {
+  const oldest = entries[entries.length - 1];
+  const reached = oldest ? `reaches back only to ${new Date(oldest.at).toISOString()}` : "is not the whole window";
+  const window = days === void 0 ? "" : ` of the --days ${days} asked for`;
+  return `This page holds ${entries.length} entries and ${reached}${window}: older entries exist and are NOT shown. Do not report it as everything that changed \u2014 re-run the same command with --cursor ${nextCursor} for the next page, or narrow with --category.`;
+}
+var listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List recent account changes (unified audit log), newest first."
+  },
+  args: {
+    limit: { type: "string", description: "Max entries (1-200, default 30)", required: false },
+    category: {
+      type: "string",
+      description: "Filter: publish|chat|action|team|setup_link|company|tag|schedule|ads|advertiser|media|creative|report|domain|integration",
+      required: false
+    },
+    days: { type: "string", description: "Only the last N days (1-365)", required: false },
+    cursor: { type: "string", description: CURSOR_DESCRIPTION, required: false },
+    full: { type: "boolean", description: "Include raw metadata", required: false, default: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const body = {};
+      const limit = parseBoundedInt(args.limit, "limit", 1, 200);
+      if (limit !== void 0) {
+        body.limit = limit;
+      }
+      const days = parseBoundedInt(args.days, "days", 1, 365);
+      if (days !== void 0) {
+        body.days = days;
+      }
+      if (args.category) {
+        if (!CATEGORIES.includes(args.category)) {
+          throw new Error(`--category must be one of: ${CATEGORIES.join("|")}`);
+        }
+        body.category = args.category;
+      }
+      if (args.cursor) {
+        body.cursor = args.cursor;
+      }
+      if (args.full) {
+        body.full = true;
+      }
+      const response = await apiPost("/api/history/list", body);
+      const { entries, nextCursor } = response.data;
+      const hints = [
+        ...entries.length === 0 ? ["No history entries matched. Widen with a larger --days or drop --category."] : [],
+        ...nextCursor ? [fullPageHint(entries, nextCursor, days)] : []
+      ];
+      writeJson({
+        ...response,
+        meta: { count: entries.length, hasMore: Boolean(nextCursor), ...nextCursor ? { nextCursor } : {} },
+        ...hints.length > 0 ? { hints } : {}
+      });
+    } catch (err) {
+      failApi(err);
+    }
+  }
+});
+var historyCommand = defineCommand({
+  meta: {
+    name: "history",
+    description: `Unified account history (audit log): what changed, who did it, and when.
+Full guide: __tooling__/docs/tools/baker/history.md`
+  },
+  subCommands: { list: listCommand }
+});
+export {
+  historyCommand
+};
+//# sourceMappingURL=history-YZ727ZRG.js.map