@koda-sl/baker-cli 0.532.0 → 0.534.0-dev.4da06ee4d

package/dist/web-J3EJVEVU.js

@@ -0,0 +1,173 @@
+import {
+  webDepthHints,
+  webSourceHints
+} from "./chunk-GONAHHY5.js";
+import {
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson
+} from "./chunk-MZOVTEEY.js";
+import "./chunk-WNIDYKWO.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-NSBNIPIW.js";
+import "./chunk-MUS2UTWU.js";
+import {
+  apiGet,
+  apiPost
+} from "./chunk-IKZHHMG4.js";
+import "./chunk-DUWJG6QH.js";
+import "./chunk-XKJO6WSY.js";
+import {
+  registerSchema
+} from "./chunk-ERCYMMBF.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/web.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.web",
+  description: "Search the web with AI to answer marketing questions \u2014 competitors, ICP, pricing, pain points, market trends. Each source is the page itself plus the part of the answer it backs. Depths: medium (Gemini Flash, quick, default), high (the same Flash model thinking longer \u2014 not a stronger model), xhigh (Gemini Deep Research, minutes).",
+  args: {
+    question: {
+      type: "string",
+      description: "The research question to answer using live web data",
+      required: true
+    },
+    depth: {
+      type: "string",
+      description: "Research depth: medium (quick), high (thorough), xhigh (exhaustive). Default: medium",
+      required: false,
+      enum: ["medium", "high", "xhigh"]
+    }
+  }
+});
+var TIMEOUT_MS = {
+  medium: 18e4,
+  high: 36e4,
+  xhigh: 9e5
+};
+var FIELDS = {
+  answer: "AI-generated research answer (markdown)",
+  sources: "Array of {title, url, resolved, cites}: url is the page Google read; cites are the parts of the answer that page backs (verbatim). resolved:false = an opaque Google link that could not be followed \u2014 do not cite it"
+};
+function webMarkdown(data) {
+  const lines = [data.answer];
+  if (data.sources.length > 0) {
+    lines.push("", "## Sources");
+    for (const s of data.sources) {
+      if (s.resolved === false) {
+        lines.push(`- ${s.title} \u2014 unresolved Google link, do not cite: ${s.url}`);
+        continue;
+      }
+      lines.push(`- [${s.title}](${s.url})`);
+      for (const cite of s.cites ?? []) lines.push(`  > "${cite}"`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+var DEEP_RESEARCH_FINISHED = /* @__PURE__ */ new Set(["completed", "incomplete"]);
+var DEEP_RESEARCH_RUNNING = /* @__PURE__ */ new Set(["queued", "in_progress"]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runDeepResearch(question) {
+  const { interactionId } = await apiPost("/api/research/deep-research/start", { question });
+  process.stderr.write(`Deep research started (${interactionId}). Polling...
+`);
+  const deadline = Date.now() + TIMEOUT_MS.xhigh;
+  while (Date.now() < deadline) {
+    await sleep(1e4);
+    const poll = await apiGet("/api/research/deep-research/poll", {
+      id: interactionId
+    });
+    if (DEEP_RESEARCH_FINISHED.has(poll.status) && poll.result) {
+      return { data: poll.result, incomplete: poll.status === "incomplete" };
+    }
+    if (!DEEP_RESEARCH_RUNNING.has(poll.status)) {
+      throw new Error(`Deep research ${poll.status}`);
+    }
+    process.stderr.write(`  status: ${poll.status}
+`);
+  }
+  throw new Error("Deep research timed out");
+}
+var webCommand = defineCommand({
+  meta: {
+    name: "web",
+    description: `Search the web with AI to answer any open-ended marketing question. Uses live internet data via Google Search.
+
+Depth levels:
+  medium  \u2014 Quick lookup: Gemini Flash with minimal thinking (default)
+  high    \u2014 The SAME Gemini Flash model and the same web search, thinking longer. Not a stronger model:
+            it reasons more over similar sources, so do not present a high answer as better-sourced.
+  xhigh   \u2014 Gemini Deep Research: plans, searches and reads many pages, writes a cited report
+            (minutes; use sparingly)
+
+Sources: every source is the page itself (Google's redirect links are followed for you), with
+"cites" \u2014 the parts of the answer that page is attached to, verbatim. Cite a URL only for the
+claim it backs. resolved:false means the link could not be followed: do not cite it or guess a path.
+An answer with no sources is synthesis, not a citable fact.
+
+Examples:
+  baker research web "Who are the main competitors of HubSpot CRM?"
+  baker research web "What are the top pain points for SMB CRM buyers?" --depth high
+  baker research web "Full competitive analysis of project management SaaS" --depth xhigh`
+  },
+  args: {
+    question: { type: "positional", description: "The research question", required: true },
+    depth: { type: "string", description: "Research depth: medium|high|xhigh (default: medium)", required: false },
+    output: { type: "string", description: "Format: json|md (default: json)", required: false, default: "json" }
+  },
+  run: async ({ args }) => {
+    const question = args.question;
+    if (question.length < 5) {
+      writeResearchJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: "Question must be at least 5 characters" }
+      });
+      process.exit(1);
+    }
+    const depth = args.depth || "medium";
+    if (!["medium", "high", "xhigh"].includes(depth)) {
+      writeResearchJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: "Depth must be one of: medium, high, xhigh" }
+      });
+      process.exit(1);
+    }
+    try {
+      const { data, incomplete } = depth === "xhigh" ? await runDeepResearch(question) : {
+        data: await apiPost(
+          "/api/research/explore",
+          { question, depth },
+          { timeoutMs: TIMEOUT_MS[depth] }
+        ),
+        incomplete: false
+      };
+      const format = args.output || "json";
+      const hints = [
+        ...webSourceHints(data.sources),
+        ...incomplete ? ["Deep research stopped at its budget, so the end of this report may be missing \u2014 say so if you use it."] : [],
+        ...webDepthHints({ answer: data.answer, sourceCount: data.sources.length, depth })
+      ];
+      if (format === "md") {
+        process.stdout.write(webMarkdown(data));
+        writeResearchHints(hints, format);
+        return;
+      }
+      writeResearchJson({ ok: true, data, fields: FIELDS, hints });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  webCommand,
+  webMarkdown
+};
+//# sourceMappingURL=web-J3EJVEVU.js.map

package/dist/web-J3EJVEVU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/research/web.ts"],"sourcesContent":["import type { ResearchDeepResearchPollResponse, ResearchWebResponse, ResearchWebSource } from \"@baker/api\";\nimport { defineCommand } from \"citty\";\nimport { apiGet, apiPost } from \"../../client.ts\";\nimport { registerSchema } from \"../../schemas.ts\";\nimport { webDepthHints, webSourceHints } from \"./hints.ts\";\nimport { handleResearchError, writeResearchHints, writeResearchJson } from \"./output.ts\";\n\nregisterSchema({\n  command: \"research.web\",\n  description:\n    \"Search the web with AI to answer marketing questions — competitors, ICP, pricing, pain points, market trends. Each source is the page itself plus the part of the answer it backs. Depths: medium (Gemini Flash, quick, default), high (the same Flash model thinking longer — not a stronger model), xhigh (Gemini Deep Research, minutes).\",\n  args: {\n    question: {\n      type: \"string\",\n      description: \"The research question to answer using live web data\",\n      required: true,\n    },\n    depth: {\n      type: \"string\",\n      description: \"Research depth: medium (quick), high (thorough), xhigh (exhaustive). Default: medium\",\n      required: false,\n      enum: [\"medium\", \"high\", \"xhigh\"],\n    },\n  },\n});\n\ntype Depth = \"medium\" | \"high\" | \"xhigh\";\n\nconst TIMEOUT_MS: Record<Depth, number> = {\n  medium: 180_000,\n  high: 360_000,\n  xhigh: 900_000,\n};\n\n// An older backend sends sources without `resolved`/`cites`; read both as optional.\ntype WebSource = Pick<ResearchWebSource, \"title\" | \"url\"> & Partial<Pick<ResearchWebSource, \"resolved\" | \"cites\">>;\ntype WebResult = Omit<ResearchWebResponse, \"sources\"> & { sources: WebSource[] };\n\nconst FIELDS: Record<string, string> = {\n  answer: \"AI-generated research answer (markdown)\",\n  sources:\n    \"Array of {title, url, resolved, cites}: url is the page Google read; cites are the parts of the answer that page backs (verbatim). resolved:false = an opaque Google link that could not be followed — do not cite it\",\n};\n\n/** `--output md`: the answer, then each page with the claims it backs; unfollowable links are marked, not linked. */\nexport function webMarkdown(data: WebResult): string {\n  const lines = [data.answer];\n  if (data.sources.length > 0) {\n    lines.push(\"\", \"## Sources\");\n    for (const s of data.sources) {\n      if (s.resolved === false) {\n        lines.push(`- ${s.title} — unresolved Google link, do not cite: ${s.url}`);\n        continue;\n      }\n      lines.push(`- [${s.title}](${s.url})`);\n      for (const cite of s.cites ?? []) lines.push(`  > \"${cite}\"`);\n    }\n  }\n  return `${lines.join(\"\\n\")}\\n`;\n}\n\n/** `completed`, or `incomplete` — finished but cut short by a budget, so the report's tail may be missing. */\nconst DEEP_RESEARCH_FINISHED = new Set([\"completed\", \"incomplete\"]);\nconst DEEP_RESEARCH_RUNNING = new Set([\"queued\", \"in_progress\"]);\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nasync function runDeepResearch(question: string): Promise<{ data: WebResult; incomplete: boolean }> {\n  const { interactionId } = await apiPost<{ interactionId: string }>(\"/api/research/deep-research/start\", { question });\n\n  process.stderr.write(`Deep research started (${interactionId}). Polling...\\n`);\n\n  const deadline = Date.now() + TIMEOUT_MS.xhigh;\n  while (Date.now() < deadline) {\n    await sleep(10_000);\n    const poll = await apiGet<ResearchDeepResearchPollResponse>(\"/api/research/deep-research/poll\", {\n      id: interactionId,\n    });\n\n    if (DEEP_RESEARCH_FINISHED.has(poll.status) && poll.result) {\n      return { data: poll.result, incomplete: poll.status === \"incomplete\" };\n    }\n    if (!DEEP_RESEARCH_RUNNING.has(poll.status)) {\n      throw new Error(`Deep research ${poll.status}`);\n    }\n    process.stderr.write(`  status: ${poll.status}\\n`);\n  }\n\n  throw new Error(\"Deep research timed out\");\n}\n\nexport const webCommand = defineCommand({\n  meta: {\n    name: \"web\",\n    description: `Search the web with AI to answer any open-ended marketing question. Uses live internet data via Google Search.\n\nDepth levels:\n  medium  — Quick lookup: Gemini Flash with minimal thinking (default)\n  high    — The SAME Gemini Flash model and the same web search, thinking longer. Not a stronger model:\n            it reasons more over similar sources, so do not present a high answer as better-sourced.\n  xhigh   — Gemini Deep Research: plans, searches and reads many pages, writes a cited report\n            (minutes; use sparingly)\n\nSources: every source is the page itself (Google's redirect links are followed for you), with\n\"cites\" — the parts of the answer that page is attached to, verbatim. Cite a URL only for the\nclaim it backs. resolved:false means the link could not be followed: do not cite it or guess a path.\nAn answer with no sources is synthesis, not a citable fact.\n\nExamples:\n  baker research web \"Who are the main competitors of HubSpot CRM?\"\n  baker research web \"What are the top pain points for SMB CRM buyers?\" --depth high\n  baker research web \"Full competitive analysis of project management SaaS\" --depth xhigh`,\n  },\n  args: {\n    question: { type: \"positional\", description: \"The research question\", required: true },\n    depth: { type: \"string\", description: \"Research depth: medium|high|xhigh (default: medium)\", required: false },\n    output: { type: \"string\", description: \"Format: json|md (default: json)\", required: false, default: \"json\" },\n  },\n  run: async ({ args }) => {\n    const question = args.question as string;\n    if (question.length < 5) {\n      writeResearchJson({\n        ok: false,\n        error: { code: \"VALIDATION_ERROR\", message: \"Question must be at least 5 characters\" },\n      });\n      process.exit(1);\n    }\n\n    const depth = ((args.depth as string) || \"medium\") as Depth;\n    if (![\"medium\", \"high\", \"xhigh\"].includes(depth)) {\n      writeResearchJson({\n        ok: false,\n        error: { code: \"VALIDATION_ERROR\", message: \"Depth must be one of: medium, high, xhigh\" },\n      });\n      process.exit(1);\n    }\n\n    try {\n      const { data, incomplete } =\n        depth === \"xhigh\"\n          ? await runDeepResearch(question)\n          : {\n              data: await apiPost<WebResult>(\n                \"/api/research/explore\",\n                { question, depth },\n                { timeoutMs: TIMEOUT_MS[depth] },\n              ),\n              incomplete: false,\n            };\n\n      const format = (args.output as string) || \"json\";\n      const hints = [\n        ...webSourceHints(data.sources),\n        ...(incomplete\n          ? [\"Deep research stopped at its budget, so the end of this report may be missing — say so if you use it.\"]\n          : []),\n        ...webDepthHints({ answer: data.answer, sourceCount: data.sources.length, depth }),\n      ];\n      if (format === \"md\") {\n        process.stdout.write(webMarkdown(data));\n        writeResearchHints(hints, format);\n        return;\n      }\n      writeResearchJson({ ok: true, data, fields: FIELDS, hints });\n    } catch (err) {\n      handleResearchError(err);\n    }\n  },\n});\n"],"mappings":"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","names":[]}

package/dist/winners-KZ7SEXZY.js

@@ -0,0 +1,113 @@
+import {
+  adFieldPlan,
+  adRows
+} from "./chunk-UMPAKBCB.js";
+import {
+  reportError
+} from "./chunk-CAYIC3ES.js";
+import {
+  apiGet
+} from "./chunk-IKZHHMG4.js";
+import "./chunk-DUWJG6QH.js";
+import "./chunk-XKJO6WSY.js";
+import {
+  registerSchema,
+  winningAdNormalizer,
+  writeJson,
+  writeOutput
+} from "./chunk-ERCYMMBF.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/winning-ads/winners.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "winning-ads.winners",
+  description: "Top winning ads for one advertiser id (from `advertisers` or `following`). Returns lean winner cards; add --full for DNA + longevity.",
+  args: {
+    advertiser: { type: "string", description: "Advertiser id to browse", required: true },
+    top: { type: "number", description: "Max winners 1-100 (default 10)", required: false, default: 10 },
+    platform: {
+      type: "string",
+      description: "Filter to a single platform: meta|linkedin|tiktok|google",
+      required: false
+    },
+    "per-platform": {
+      type: "boolean",
+      description: "Also rank each platform the brand runs on on its own (by_platform)",
+      required: false,
+      default: false
+    }
+  }
+});
+var winnersCommand = defineCommand({
+  meta: {
+    name: "winners",
+    description: "Top winning ads for a specific advertiser id, across its platforms, on one (--platform) or ranked per platform (--per-platform). Example: baker winning-ads winners adv_123 --top 5 --per-platform --fields ad_id,platform,summary,days_active"
+  },
+  args: {
+    advertiser: { type: "positional", description: "Advertiser id", required: true },
+    top: { type: "string", description: "Max winners 1-100 (default 10)", required: false },
+    platform: {
+      type: "string",
+      description: "Filter to a single platform: meta|linkedin|tiktok|google",
+      required: false
+    },
+    "per-platform": {
+      type: "boolean",
+      description: "Also return each platform's own top winners (by_platform); scores don't compare across platforms",
+      required: false,
+      default: false
+    },
+    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
+    fields: { type: "string", description: "Comma-separated field names to include", required: false },
+    full: {
+      type: "boolean",
+      description: "Include DNA detail (angle, persona, hook) + longevity",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const params = { id: String(args.advertiser) };
+      if (args.top) {
+        params.top = String(args.top);
+      }
+      if (args.platform) {
+        params.platform = String(args.platform);
+      } else if (args["per-platform"]) {
+        params.per_platform = "1";
+      }
+      const data = await apiGet("/api/ad-library/advertiser-winners", params);
+      const output = args.output || "json";
+      const plan = adFieldPlan(args.fields, args.full);
+      const rawWinners = Array.isArray(data?.winners) ? data.winners : [];
+      if (output === "json") {
+        const winners = adRows(rawWinners, plan);
+        const byPlatform = data?.by_platform?.map((g) => ({ platform: g.platform, winners: adRows(g.winners, plan) }));
+        writeJson({
+          ok: true,
+          data: {
+            advertiser_id: data?.advertiser_id ?? String(args.advertiser),
+            winners,
+            ...byPlatform ? { by_platform: byPlatform } : {}
+          }
+        });
+        return;
+      }
+      writeOutput(
+        { ok: true, data: data?.by_platform ? data.by_platform.flatMap((g) => g.winners) : rawWinners },
+        output,
+        plan.fields,
+        plan.full,
+        winningAdNormalizer
+      );
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+export {
+  winnersCommand
+};
+//# sourceMappingURL=winners-KZ7SEXZY.js.map

package/dist/winning-ads-H2LM75L5.js

@@ -0,0 +1,86 @@
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/winning-ads/index.ts
+import { defineCommand } from "citty";
+var winningAdsCommand = defineCommand({
+  meta: {
+    name: "winning-ads",
+    description: `Search the ad-dna corpus of scored "winning" ads for reference creatives to reproduce, and manage the brands your library tracks. Proxied through the Baker backend (BAKER_API_KEY) \u2014 no separate token needed.
+
+Auth: BAKER_API_KEY (bk_, bkr_ or bkv_) + BAKER_API_URL (your Convex .convex.site URL).
+
+Rows are compact. Filter at the source (--platform, --format, --running, --advertiser-id) and keep only the columns you need with --fields ad_id,summary,days_active; --full only for the 2-3 ads you will use.
+
+Subcommands:
+  baker winning-ads search "<free text>"      \u2014 semantic search, followed brands first; lean shortlist (advertiser, summary, scores, proof, media_url)
+  baker winning-ads advertisers "<brand>"     \u2014 list corpus brands \u2192 advertiser ids (for --exclude-advertiser / --advertiser-id)
+  baker winning-ads follow "<website|brand|link>" \u2014 add a brand's ads to your library: every platform, every account it runs
+  baker winning-ads discover "<website|brand|link>" \u2014 see every account a brand runs ads from, without following
+  baker winning-ads add "<website|brand|link>" \u2014 put a brand's ads in Baker's library WITHOUT following it (a client you study, not track)
+  baker winning-ads add-accounts <advertiser> "<link,link>" \u2014 track more accounts of a followed brand (another market's page)
+  baker winning-ads follow-competitors "<domain,domain,...>"   \u2014 add MANY brands at once (every competitor by domain)
+  baker winning-ads following                 \u2014 list brands you follow (status + counts)
+  baker winning-ads feed                      \u2014 winners across EVERY brand you follow; trim with --advertiser
+  baker winning-ads winners <advertiser>      \u2014 top winners for one advertiser id (--platform: one platform's; --per-platform: each platform's own)
+  baker winning-ads ads <advertiser>          \u2014 every ad one advertiser has run; narrow with --platform, --format video,static,carousel,text, --running running|stopped
+  baker winning-ads profile <advertiser>      \u2014 what a brand is doing: spend estimate, launches + what still runs, tests + the version kept, mixes, landing pages, audiences, similar brands
+  baker winning-ads launches [--since 7]      \u2014 what followed brands launched in the last N days and which ads still run
+  baker winning-ads landings <advertiser>     \u2014 every landing page a brand's ads point to; --analyse reads how each sells (value props, offer, pricing, proof)
+  baker winning-ads search-copy <advertiser>  \u2014 what a brand says on Google Search: headlines + their hooks, descriptions, sitelinks, each running or dropped
+  baker winning-ads content <ad-id>           \u2014 read ONE ad's transcript + on-screen text + copy (understand a reference before reproducing it)
+  baker winning-ads fit <ad-id>               \u2014 does this winner fit OUR company? why it wins, what it needs, what we have, use|adapt|reject
+  baker winning-ads unfollow <advertiser>     \u2014 stop following a brand
+  baker winning-ads refresh <advertiser>      \u2014 re-scrape a followed brand for its newest ads (max once per 6h)
+  baker winning-ads hooks                     \u2014 top winner-weighted HOOK seeds for a segment (feed the seed to search --hook-archetype)
+  baker winning-ads mechanisms                \u2014 top winner-weighted PRODUCT mechanism seeds (how the product claims to work)
+  baker winning-ads formats                   \u2014 top winner-weighted static FORMAT patterns for a segment
+
+Examples:
+  baker winning-ads search "B2B SaaS before/after AI automation" --platform meta --format static --output md
+  baker winning-ads advertisers "Acme" --output md
+  baker winning-ads follow "deel.com"
+  baker winning-ads add-accounts adv_123 "https://www.facebook.com/barkibu.it"
+  baker winning-ads follow-competitors "deel.com,notion.so,hubspot.com"
+  baker winning-ads feed --output md
+  baker winning-ads feed --advertiser adv_123,adv_456 --platform meta --output md
+  baker winning-ads winners adv_123 --per-platform --top 5 --output md
+  baker winning-ads ads adv_123 --platform google --format text --running running --fields ad_id,summary,days_active --output md
+  baker winning-ads profile adv_123 --platform meta
+  baker winning-ads launches --since 7
+  baker winning-ads landings adv_123 --analyse
+  baker winning-ads search-copy adv_123 --running
+  baker winning-ads content adg_123 --full --output md
+  baker winning-ads hooks --platform meta --awareness problem_aware --industry saas --output md
+  baker winning-ads search "fintech onboarding" --hook-archetype callout --winner-category winner --output md
+  baker winning-ads search --format-pattern comparison_table --sort longest_running --output md
+Full guide: __tooling__/docs/tools/baker/winning-ads.md`
+  },
+  subCommands: {
+    search: () => import("./search-JQ7CDJWO.js").then((m) => m.searchCommand),
+    advertisers: () => import("./advertisers-WQ2FDNHU.js").then((m) => m.advertisersCommand),
+    follow: () => import("./follow-NYSYOMPZ.js").then((m) => m.followCommand),
+    discover: () => import("./discover-BLUJYLBT.js").then((m) => m.discoverCommand),
+    add: () => import("./add-AYILCHML.js").then((m) => m.addCommand),
+    "add-accounts": () => import("./add-accounts-2KEM5SDH.js").then((m) => m.addAccountsCommand),
+    "follow-competitors": () => import("./follow-competitors-XK7AHXV5.js").then((m) => m.followCompetitorsCommand),
+    following: () => import("./following-5NSY62IF.js").then((m) => m.followingCommand),
+    feed: () => import("./feed-IN5DQ6QV.js").then((m) => m.feedCommand),
+    winners: () => import("./winners-KZ7SEXZY.js").then((m) => m.winnersCommand),
+    ads: () => import("./ads-3ZCUKPVZ.js").then((m) => m.adsCommand),
+    profile: () => import("./profile-VKYAKK5B.js").then((m) => m.profileCommand),
+    launches: () => import("./launches-C3ZQH4VF.js").then((m) => m.launchesCommand),
+    landings: () => import("./landings-23OMBXML.js").then((m) => m.landingsCommand),
+    "search-copy": () => import("./search-copy-Z7DVNT44.js").then((m) => m.searchCopyCommand),
+    content: () => import("./content-LNIBJKNQ.js").then((m) => m.contentCommand),
+    fit: () => import("./fit-TC4AACBU.js").then((m) => m.fitCommand),
+    unfollow: () => import("./unfollow-E2ZSYWUK.js").then((m) => m.unfollowCommand),
+    refresh: () => import("./refresh-H5RGVPYJ.js").then((m) => m.refreshCommand),
+    hooks: () => import("./seeds-BFXQKJP4.js").then((m) => m.hooksCommand),
+    mechanisms: () => import("./seeds-BFXQKJP4.js").then((m) => m.mechanismsCommand),
+    formats: () => import("./seeds-BFXQKJP4.js").then((m) => m.formatsCommand)
+  }
+});
+export {
+  winningAdsCommand
+};
+//# sourceMappingURL=winning-ads-H2LM75L5.js.map

package/dist/write-commands-2AKHGZ2J.js

@@ -0,0 +1,206 @@
+import {
+  loadJsonArg,
+  requireTarget,
+  stageOp
+} from "./chunk-DXHOUY74.js";
+import "./chunk-D5FY4FAK.js";
+import "./chunk-QG45DH5D.js";
+import "./chunk-IKZHHMG4.js";
+import "./chunk-DUWJG6QH.js";
+import "./chunk-XKJO6WSY.js";
+import {
+  registerSchema
+} from "./chunk-ERCYMMBF.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/tag-manager/write-commands.ts
+import { defineCommand } from "citty";
+var CONTAINER_ARG_DESCRIPTION = "Numeric container id (optional only when one container is connected \u2014 run `baker tag-manager containers`)";
+var ENTITIES = [
+  {
+    entity: "tag",
+    noun: "tag",
+    createHint: 'Payload needs name + type (e.g. "gaawe" for a GA4 event) and usually parameter[] and firingTriggerId[]. Reference a trigger by its numeric id, or by a gtm_temp_* ref if you are staging it in this same chat.',
+    example: '{"name":"GA4 - Generate Lead","type":"gaawe","firingTriggerId":["gtm_temp_trigger_x_0"]}'
+  },
+  {
+    entity: "trigger",
+    noun: "trigger",
+    createHint: 'Payload needs name + type (e.g. "pageview", "click", "customEvent"). Stage the trigger BEFORE the tag that fires on it, then reference it by its gtm_temp_* ref.',
+    example: '{"name":"Form - Submit","type":"formSubmission"}'
+  },
+  {
+    entity: "variable",
+    noun: "variable",
+    createHint: 'Payload needs name + type (e.g. "v" for a data layer variable, "c" for a constant). Other entities reference a variable by NAME as {{Variable Name}}.',
+    example: '{"name":"DL - lead_id","type":"v","parameter":[{"type":"template","key":"name","value":"lead_id"}]}'
+  },
+  {
+    entity: "folder",
+    noun: "folder",
+    createHint: "Payload needs name. Use folders to keep a large container legible.",
+    example: '{"name":"Google Ads"}'
+  }
+];
+for (const { entity, noun, createHint } of ENTITIES) {
+  registerSchema({
+    command: `tagManager.${entity}.create`,
+    description: `Stage the creation of a Tag Manager ${noun}. ${createHint} Staged only \u2014 applies when the chat completes.`,
+    args: {
+      json: { type: "string", description: `Inline JSON ${noun} definition`, required: false },
+      file: { type: "string", description: `Path to a JSON file with the ${noun} definition`, required: false },
+      container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+    }
+  });
+  registerSchema({
+    command: `tagManager.${entity}.update`,
+    description: `Stage an update to an existing Tag Manager ${noun}. Pass the ${noun} id or path as the positional argument and the changed fields as JSON. Read the container first so you send the fields you mean to change.`,
+    args: {
+      json: { type: "string", description: "Inline JSON with the changed fields", required: false },
+      file: { type: "string", description: "Path to a JSON file with the changed fields", required: false },
+      container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+    }
+  });
+  registerSchema({
+    command: `tagManager.${entity}.delete`,
+    description: `Stage the deletion of a Tag Manager ${noun}. Pass its id or path as the positional argument. Deleting is irreversible once the resulting version is published \u2014 confirm with the user first.`,
+    args: {
+      container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+    }
+  });
+}
+function entityCommand(entity, noun, example) {
+  return defineCommand({
+    meta: { name: entity, description: `Stage ${noun} changes on this chat's Tag Manager draft` },
+    subCommands: {
+      create: defineCommand({
+        meta: {
+          name: "create",
+          description: `Stage a new ${noun}
+
+Examples:
+  baker tag-manager ${entity} create --json '${example}'
+  baker tag-manager ${entity} create --file ./${entity}.json`
+        },
+        args: {
+          json: { type: "string", description: "Inline JSON definition", required: false },
+          file: { type: "string", description: "Path to a JSON file", required: false },
+          container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+        },
+        run: async ({ args }) => {
+          await stageOp({
+            kind: `tagManager.${entity}.create`,
+            payload: loadJsonArg(args),
+            ...typeof args.container === "string" ? { containerId: args.container } : {}
+          });
+        }
+      }),
+      update: defineCommand({
+        meta: {
+          name: "update",
+          description: `Stage an update to an existing ${noun} (pass its id or path)`
+        },
+        args: {
+          id: { type: "positional", description: `${noun} id or path`, required: false },
+          json: { type: "string", description: "Inline JSON with changed fields", required: false },
+          file: { type: "string", description: "Path to a JSON file", required: false },
+          container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+        },
+        run: async ({ args }) => {
+          await stageOp({
+            kind: `tagManager.${entity}.update`,
+            target: requireTarget(args, noun),
+            payload: loadJsonArg(args),
+            ...typeof args.container === "string" ? { containerId: args.container } : {}
+          });
+        }
+      }),
+      delete: defineCommand({
+        meta: { name: "delete", description: `Stage the deletion of a ${noun} (pass its id or path)` },
+        args: {
+          id: { type: "positional", description: `${noun} id or path`, required: false },
+          container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+        },
+        run: async ({ args }) => {
+          await stageOp({
+            kind: `tagManager.${entity}.delete`,
+            target: requireTarget(args, noun),
+            ...typeof args.container === "string" ? { containerId: args.container } : {}
+          });
+        }
+      })
+    }
+  });
+}
+var exampleFor = (entity) => ENTITIES.find((e) => e.entity === entity)?.example ?? "{}";
+var tagCommand = entityCommand("tag", "tag", exampleFor("tag"));
+var triggerCommand = entityCommand("trigger", "trigger", exampleFor("trigger"));
+var variableCommand = entityCommand("variable", "variable", exampleFor("variable"));
+var folderCommand = entityCommand("folder", "folder", exampleFor("folder"));
+registerSchema({
+  command: "tagManager.builtin",
+  description: "Enable or disable Tag Manager built-in variables by type (e.g. clickUrl, pageUrl, formId). Built-in variables must be enabled before a trigger or tag can reference them as {{Click URL}}.",
+  args: {
+    types: { type: "string", description: "Comma-separated built-in variable types", required: true },
+    container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+  }
+});
+function builtinTypes(args) {
+  const raw = args.types;
+  if (typeof raw !== "string" || raw.length === 0) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: false, error: { code: "VALIDATION_ERROR", message: "pass --types with comma-separated built-in variable types" } }, null, 2)}
+`
+    );
+    process.exit(1);
+  }
+  return raw.split(",").map((entry) => entry.trim());
+}
+var builtinCommand = defineCommand({
+  meta: {
+    name: "builtin",
+    description: `Enable or disable built-in variables
+
+Examples:
+  baker tag-manager builtin enable --types clickUrl,clickText
+  baker tag-manager builtin disable --types formId`
+  },
+  subCommands: {
+    enable: defineCommand({
+      meta: { name: "enable", description: "Stage enabling built-in variables" },
+      args: {
+        types: { type: "string", description: "Comma-separated types", required: false },
+        container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+      },
+      run: async ({ args }) => {
+        await stageOp({
+          kind: "tagManager.builtInVariable.enable",
+          payload: { type: builtinTypes(args) },
+          ...typeof args.container === "string" ? { containerId: args.container } : {}
+        });
+      }
+    }),
+    disable: defineCommand({
+      meta: { name: "disable", description: "Stage disabling built-in variables" },
+      args: {
+        types: { type: "string", description: "Comma-separated types", required: false },
+        container: { type: "string", description: CONTAINER_ARG_DESCRIPTION, required: false }
+      },
+      run: async ({ args }) => {
+        await stageOp({
+          kind: "tagManager.builtInVariable.disable",
+          payload: { type: builtinTypes(args) },
+          ...typeof args.container === "string" ? { containerId: args.container } : {}
+        });
+      }
+    })
+  }
+});
+export {
+  builtinCommand,
+  folderCommand,
+  tagCommand,
+  triggerCommand,
+  variableCommand
+};
+//# sourceMappingURL=write-commands-2AKHGZ2J.js.map