@koda-sl/baker-cli 0.491.0 → 0.492.0

package/dist/chunk-EW3JEKIV.js

@@ -0,0 +1,139 @@
+import {
+  brandVerificationHints
+} from "./chunk-IVIJJXXT.js";
+import {
+  OUTPUT_ARGS,
+  writeProviderHits
+} from "./chunk-IBTSIPYA.js";
+import {
+  AUTO_INGEST_MAX,
+  parseAutoIngest
+} from "./chunk-KKJ4KJCW.js";
+import {
+  emptyResultHints
+} from "./chunk-Q6ULQMWG.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-6YLNY6CK.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-QANGHND7.js";
+
+// src/commands/images/logo.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "images.logo",
+  description: "Brand logo lookup via Brandfetch. Auto-ingests by default. Returns `brandMatch` \u2014 Brandfetch's own verdict on whose brand the domain is (confirmed | mismatch | unverified). Branch on it: `mismatch` means the mark is another company's, so do not place it. `confirmed` verifies the record, not the artwork \u2014 read the ingested row back to check the mark itself.",
+  args: {
+    domain: { type: "string", description: "Brand domain (e.g. stripe.com)", required: true },
+    variant: { type: "string", description: "icon | logo | symbol", required: false },
+    "auto-ingest": {
+      type: "number",
+      description: `Ingest top N hits (0-${AUTO_INGEST_MAX.logo}). Defaults to 1 (the first variant). Brandfetch resolves at most ${AUTO_INGEST_MAX.logo} variants, so ${AUTO_INGEST_MAX.logo} ingests every one. Keep it at 1+ \u2014 the ingested row is the only way to check the mark is the brand you asked for.`,
+      required: false
+    },
+    "no-auto-ingest": {
+      type: "boolean",
+      description: "Skip auto-ingest (equivalent to --auto-ingest 0). Leaves the returned mark unverifiable.",
+      required: false,
+      default: false
+    },
+    context: {
+      type: "string",
+      description: "Free-text hint applied to ingested logo variants (e.g. 'Stripe \u2014 payments integration partner', 'Acme competitor brand mark')",
+      required: 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 full metadata", required: false, default: false }
+  }
+});
+var logoCommand = defineCommand({
+  meta: {
+    name: "logo",
+    description: "Brand logo via Brandfetch. Returns up to 5 variants (icon, light/dark logo, light/dark symbol) plus `brandMatch`. Auto-ingests the first variant.\n\nStart here: check `brandMatch.verdict`.\n  mismatch   \u2192 the mark belongs to `brandMatch.name`, a different company. Do not place it.\n  unverified \u2192 nothing confirmed whose logo this is. Treat as unchecked.\n  confirmed  \u2192 Brandfetch has this brand's record. That verifies the record, NOT the artwork \u2014 a confirmed domain has served another company's logo before.\n\n\u26A0 Whatever the verdict, read the ingested row back with `baker images get <imageId>` and check `textInImage`/`subject` before placing it. That is the only check that looks at the mark.\n\nExample: baker images logo stripe.com --variant logo"
+  },
+  args: {
+    domain: { type: "positional", description: "Brand domain", required: false },
+    variant: { type: "string", description: "icon|logo|symbol", required: false },
+    "auto-ingest": {
+      type: "string",
+      description: `Ingest top N (0-${AUTO_INGEST_MAX.logo}, default 1)`,
+      required: false
+    },
+    "no-auto-ingest": { type: "boolean", description: "Skip auto-ingest", required: false },
+    context: { type: "string", description: "Description context hint applied to ingested logos", required: false },
+    ...OUTPUT_ARGS
+  },
+  run: async ({ args }) => {
+    try {
+      const domain = args.domain;
+      if (!domain) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "Domain is required" } });
+        process.exit(1);
+      }
+      const body = { domain };
+      if (args.variant) body.variant = args.variant;
+      if (args["auto-ingest"] !== void 0) {
+        const parsed = parseAutoIngest(args["auto-ingest"], AUTO_INGEST_MAX.logo);
+        if (!parsed.ok) {
+          writeJson({
+            ok: false,
+            error: {
+              code: "VALIDATION_ERROR",
+              message: parsed.message,
+              fix: {
+                action: "retry_with_changes",
+                explanation: `Brandfetch resolves at most ${AUTO_INGEST_MAX.logo} variants for a domain, so --auto-ingest ${AUTO_INGEST_MAX.logo} already ingests every one. Re-run with a value in 0-${AUTO_INGEST_MAX.logo}.`
+              }
+            }
+          });
+          process.exit(1);
+        }
+        body.autoIngest = parsed.value;
+      } else if (args["no-auto-ingest"]) {
+        body.autoIngest = 0;
+      }
+      if (args.context) body.descriptionContext = args.context;
+      const data = await apiPost("/api/images/logo", body);
+      const hints = [
+        // `brandMatch` is Brandfetch's own answer to whose brand this domain is,
+        // so the warning can now be graded instead of fired blind: loud on a
+        // mismatch, honest about what a confirmation does and does not cover.
+        ...brandVerificationHints({
+          domain,
+          ingested: data.ingested,
+          hitCount: data.hits.length,
+          brandMatch: data.brandMatch
+        }),
+        ...emptyResultHints({ provider: "logo", hitCount: data.hits.length, activeFilters: [], subject: domain })
+      ];
+      writeProviderHits(data, data.hits, args, hints);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+async function fetchBrandLogo(domain) {
+  try {
+    const body = { domain, variant: "logo" };
+    const data = await apiPost("/api/images/logo", body);
+    if (data?.brandMatch?.verdict === "mismatch") return null;
+    return data?.ingested?.[0]?.imageUrl ?? data?.hits?.find((h) => h.imageUrl)?.imageUrl ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export {
+  logoCommand,
+  fetchBrandLogo
+};
+//# sourceMappingURL=chunk-EW3JEKIV.js.map

package/dist/chunk-F2OCUTMQ.js

@@ -0,0 +1,544 @@
+import {
+  adFieldPlan,
+  adRows
+} from "./chunk-YV7PKHFB.js";
+import {
+  reportError,
+  splitList
+} from "./chunk-LK6W5FDV.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-6YLNY6CK.js";
+import {
+  registerSchema,
+  scopedWinnersSearchRequestSchema,
+  staticFormatPatternSchema,
+  winnerSearchScopeSchema,
+  winnersSortSchema,
+  winningAdNormalizer,
+  writeJson,
+  writeOutput
+} from "./chunk-QANGHND7.js";
+
+// src/commands/winning-ads/search.ts
+import { defineCommand } from "citty";
+var FORMAT_PATTERN_DESCRIPTION = `Comma list of static containers, the best proven ads in them from any category (\`winning-ads formats\` ranks them for a segment): ${staticFormatPatternSchema.options.join(", ")}`;
+var STAGE_DESCRIPTION = "Comma list of where the ad is in its life: new (\u22647 days running), testing (\u226421), proven (\u226460), evergreen (longer), killed_early (stopped within 2 weeks: a lost test), retired, unverified (brand not checked recently). What competitors kept: --stage proven,evergreen";
+var SURVIVED_TEST_DESCRIPTION = "Only the version a brand kept after testing it against other versions of the same concept: the strongest public sign it works";
+var PARTNERSHIP_DESCRIPTION = "only = just Meta partnership ads (the brand ran it with a creator or another brand, both named in the ad; each row says who as partner); exclude = drop them, for the brand's own ads";
+var PARTNERSHIP_VALUES = { only: true, exclude: false };
+var LANGUAGE_DESCRIPTION = "Comma list of ISO 639-1 codes (es,en) for the language the ad's copy and voiceover are in; where it ran is --country";
+registerSchema({
+  command: "winning-ads.search",
+  description: "Search the ad-dna corpus of scored winning ads, the company's followed brands first. Returns a lean shortlist (advertiser, summary, scores, days_active/active/winner_category as proof, media_url, visual/container/mechanism, and who the ad was made for: audience_temperature/funnel_stage/advertiser_size/presumes_brand_knowledge, when known) to pick a reference to reproduce. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry. Each row carries its stage (new, testing, proven, evergreen, killed_early, retired, unverified) and survived_test when it is the version its brand kept after testing; --survived-test or --stage proven,evergreen keep only what competitors kept. Only designed pictures and videos come back by default (no Google search, Shopping or app ads); --format text asks for Google search ads (their words), --all-kinds for everything. A value outside a closed list (--platform, --format, --winner-category, --awareness, --audience-temperature, --funnel-stage, --advertiser-size, --format-pattern, --stage, --sort) is refused with error.fix.validValues.",
+  args: {
+    query: { type: "string", description: "Free-text natural-language query", required: false },
+    scope: {
+      type: "string",
+      description: "Which brands to draw from: followed-first (default: followed brands first, topped up from the library when too few clear the relevance floor; the whole library when the company follows nobody), followed (only brands the company follows), all (the whole shared library). Every result carries source: followed|library.",
+      required: false,
+      default: "followed-first"
+    },
+    "ref-ad-id": {
+      type: "string",
+      description: "Find ads similar to this ad id (instead of free text)",
+      required: false
+    },
+    limit: { type: "number", description: "Max results 1-100 (default 10)", required: false, default: 10 },
+    "max-per-advertiser": {
+      type: "number",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after the other brands, none dropped. Set 1-50 to drop past N (1 = one reference per brand), 0 for rank order",
+      required: false
+    },
+    "min-relevance": { type: "number", description: "Relevance floor 0-1; trims weak matches", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a browse with no query: winner (default, by winner score), longest_running (by days active), newest (by first seen). Ignored when a query is given: a query ranks by relevance blended with winner score.",
+      required: false,
+      default: "winner"
+    },
+    platform: {
+      type: "string",
+      description: "Comma list: meta,linkedin,tiktok,google",
+      required: false
+    },
+    format: { type: "string", description: "Comma list: video,static,carousel,text", required: false },
+    "winner-category": {
+      type: "string",
+      description: "Comma list: winner,scaled_winner,evergreen,rising,untested,dud,\u2026",
+      required: false
+    },
+    awareness: {
+      type: "string",
+      description: "Comma list: unaware,problem_aware,solution_aware,product_aware,most_aware",
+      required: false
+    },
+    "audience-temperature": {
+      type: "string",
+      description: "Comma list of who the ad was made for: 0_cold (strangers), 1_warm_engaged (engaged, not yet visited), 2_hot_visited (visited the site), 3_customer. A cold brief takes 0_cold references.",
+      required: false
+    },
+    "funnel-stage": { type: "string", description: "Comma list: TOF,MOF,BOF", required: false },
+    "advertiser-size": { type: "string", description: "Comma list: solo,smb,mid,enterprise", required: false },
+    "exclude-brand-reliant": {
+      type: "boolean",
+      description: "Drop ads whose copy only works if the viewer already knows the brand (an unexplained logo, mascot, nickname or promise). Ads not judged yet are kept and show no presumes_brand_knowledge. Use it whenever the ad you are making is for viewers who don't know the brand.",
+      required: false,
+      default: false
+    },
+    country: {
+      type: "string",
+      description: "Comma list of ISO country codes (US,GB): ads known to run there, plus ads with no country data (every Meta ad) in that country's main language. An unknown code is refused with the codes that have ads",
+      required: false
+    },
+    language: { type: "string", description: LANGUAGE_DESCRIPTION, required: false },
+    "advertiser-id": {
+      type: "string",
+      description: "Restrict to these advertiser ids (browse one brand's winners)",
+      required: false
+    },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids, usually your own brand (a reused ad is marked already_adapted instead)",
+      required: false
+    },
+    "first-seen-after": {
+      type: "string",
+      description: "ISO date (2026-01-01) or datetime; only ads first seen after this",
+      required: false
+    },
+    "first-seen-before": {
+      type: "string",
+      description: "ISO date (2026-01-01) or datetime; only ads first seen before this",
+      required: false
+    },
+    "hook-archetype": {
+      type: "string",
+      description: "Comma list of hook SEEDS (from `winning-ads hooks`) \u2014 narrow to ads on a proven hook pattern",
+      required: false
+    },
+    "format-pattern": {
+      type: "string",
+      description: FORMAT_PATTERN_DESCRIPTION,
+      required: false
+    },
+    stage: { type: "string", description: STAGE_DESCRIPTION, required: false },
+    "survived-test": { type: "boolean", description: SURVIVED_TEST_DESCRIPTION, required: false, default: false },
+    partnership: { type: "string", description: PARTNERSHIP_DESCRIPTION, required: false },
+    "all-kinds": {
+      type: "boolean",
+      description: "Also return ads nobody can build a creative on: Google search text, Shopping and app ads. By default a search returns only designed pictures and videos; --format text asks for search ads alone (their words: headlines, claims, offers).",
+      required: false,
+      default: false
+    },
+    diverse: {
+      type: "boolean",
+      description: "Return one varied set (different brands, containers, hooks) instead of rank order: one reference per concept in a single call",
+      required: false,
+      default: false
+    }
+  }
+});
+function setNumber(body, key, value) {
+  if (value !== void 0 && value !== "") {
+    body[key] = Number(value);
+  }
+}
+function setList(target, key, value) {
+  const list = splitList(value);
+  if (list.length) {
+    target[key] = list;
+  }
+}
+function setString(target, key, value) {
+  if (value) {
+    target[key] = value;
+  }
+}
+function buildSearchBody(args) {
+  const body = {};
+  if (args.query) {
+    body.free_text_query = args.query;
+  }
+  if (args.refAdId) {
+    body.ref_ad_id = args.refAdId;
+  }
+  setString(body, "scope", args.scope);
+  setNumber(body, "limit", args.limit);
+  setNumber(body, "max_per_advertiser", args.maxPerAdvertiser);
+  setNumber(body, "min_relevance", args.minRelevance);
+  setString(body, "sort", args.sort);
+  if (args.diverse) {
+    body.diverse = true;
+  }
+  const hardFilters = {};
+  setList(hardFilters, "platform", args.platform);
+  setList(hardFilters, "format", args.format);
+  setList(hardFilters, "winner_category", args.winnerCategory);
+  setList(hardFilters, "awareness_stage", args.awareness);
+  setList(hardFilters, "audience_temperature", args.audienceTemperature);
+  setList(hardFilters, "funnel_stage", args.funnelStage);
+  setList(hardFilters, "advertiser_size", args.advertiserSize);
+  if (args.excludeBrandReliant) {
+    hardFilters.presumes_brand_knowledge = false;
+  }
+  setList(hardFilters, "country", args.country);
+  setList(hardFilters, "language", args.language?.toLowerCase());
+  setList(hardFilters, "advertiser_ids", args.advertiserId);
+  setList(hardFilters, "exclude_advertiser_ids", args.excludeAdvertiser);
+  setList(hardFilters, "hook_archetype_seeds", args.hookArchetype);
+  setList(hardFilters, "static_format_patterns", args.formatPattern);
+  setString(hardFilters, "first_seen_after", args.firstSeenAfter);
+  setString(hardFilters, "first_seen_before", args.firstSeenBefore);
+  setList(hardFilters, "lifecycle_stage", args.stage);
+  if (args.survivedTest) {
+    hardFilters.survived_test = true;
+  }
+  if (args.partnership !== void 0 && args.partnership in PARTNERSHIP_VALUES) {
+    hardFilters.partnership = PARTNERSHIP_VALUES[args.partnership];
+  }
+  if (Object.keys(hardFilters).length) {
+    body.hard_filters = hardFilters;
+  }
+  return body;
+}
+function designedByDefault(body, opts) {
+  const filters = body.hard_filters ?? {};
+  const wantsText = Array.isArray(filters.format) && filters.format.includes("text");
+  if (opts.allKinds || wantsText) return body;
+  return { ...body, hard_filters: { ...filters, design_reference: true } };
+}
+function searchHints(data) {
+  const hints = [];
+  if ((data.following_count ?? 0) === 0) {
+    hints.push(
+      'The company follows no brands, so these references come from brands tracked by others and may be off-market. Follow competitors with `baker winning-ads follow-competitors "<domain,domain>"` to get on-market references, then search with --scope followed-first.'
+    );
+  } else if (data.scope === "followed" && (data.results?.length ?? 0) === 0) {
+    hints.push(
+      "No followed brand has an ad on this brief. Re-run with --scope followed-first to top up from the whole library."
+    );
+  } else if ((data.results?.length ?? 0) === 0) {
+    hints.push(
+      "No reference matched the brief and every filter. Search once more with ONE change: drop the narrowest filter (--country, --audience-temperature or one --awareness stage) or shorten the brief to the product and who it is for. For a container your concept needs, --format-pattern <container> with no query returns the best proven ads in it from any category."
+    );
+  }
+  const kept = keptHint(data.results ?? []);
+  if (kept) hints.push(kept);
+  const adapted = (data.results ?? []).filter(
+    (r) => r?.baker_uses?.ours === true
+  ).length;
+  if (adapted > 0) {
+    hints.push(
+      `${adapted} of these references you already adapted into a creative (already_adapted), so they are listed last. A second creative from the same ad is a variant, not a new concept: pick another unless the user asked for one.`
+    );
+  }
+  return hints;
+}
+var KEPT_STAGES = /* @__PURE__ */ new Set(["proven", "evergreen"]);
+var UNTESTED_STAGES = /* @__PURE__ */ new Set(["new", "testing"]);
+function keptHint(results) {
+  const rows = results.map((r) => r ?? {});
+  const kept = rows.filter((r) => r.survived_test === true || KEPT_STAGES.has(String(r.stage))).length;
+  if (kept > 0 && kept < rows.length) {
+    return `${kept} of these are what competitors kept after testing (survived_test, or stage proven/evergreen): prefer them as references; a new or testing ad may still be cut.`;
+  }
+  if (kept === 0 && rows.some((r) => UNTESTED_STAGES.has(String(r.stage)))) {
+    return "None of these has outlived a test yet (stage new/testing): to reference what competitors kept, search once more with --survived-test or --stage proven,evergreen.";
+  }
+  return null;
+}
+var UNKNOWN_COUNTRY_RE = /Unknown country code\(s\): ([^.]+)\. Countries with ads: ([^.]+)\./;
+function unknownCountryFix(message) {
+  const match = UNKNOWN_COUNTRY_RE.exec(message);
+  if (!match) {
+    return null;
+  }
+  const unknownCountries = splitList(match[1]);
+  const validCountries = splitList(match[2]);
+  if (unknownCountries.length === 0 || validCountries.length === 0) {
+    return null;
+  }
+  return {
+    action: "retry_with_a_valid_country",
+    explanation: `${unknownCountries.join(", ")} is not a country the winning-ads library holds ads for. Re-run with codes from \`validCountries\`, or drop --country to search every market.`,
+    unknownCountries,
+    validCountries
+  };
+}
+function searchErrorFix(code, message) {
+  if (code === "UNAVAILABLE") {
+    return {
+      action: "retry_narrower_once",
+      explanation: "The library did not answer this search in time. Retry once with a shorter brief, a lower --limit or fewer filters. If it fails again, continue without a reference and say so; do not stop the creative work."
+    };
+  }
+  return unknownCountryFix(message);
+}
+function reportSearchError(err) {
+  const fix = err instanceof ApiError ? searchErrorFix(err.code, err.message) : null;
+  if (err instanceof ApiError && fix) {
+    writeJson({ ok: false, error: { code: err.code, message: err.message, fix } });
+    process.exit(1);
+  }
+  reportError(err);
+}
+var FLAG_FOR_FIELD = {
+  limit: "--limit",
+  max_per_advertiser: "--max-per-advertiser",
+  min_relevance: "--min-relevance",
+  platform: "--platform",
+  format: "--format",
+  winner_category: "--winner-category",
+  awareness_stage: "--awareness",
+  audience_temperature: "--audience-temperature",
+  funnel_stage: "--funnel-stage",
+  advertiser_size: "--advertiser-size",
+  static_format_patterns: "--format-pattern",
+  first_seen_after: "--first-seen-after",
+  first_seen_before: "--first-seen-before",
+  lifecycle_stage: "--stage"
+};
+function flagFor(path) {
+  const field = String(path[0] === "hard_filters" ? path[1] : path[0]);
+  return FLAG_FOR_FIELD[field] ?? field;
+}
+function schemaRejection(body) {
+  const parsed = scopedWinnersSearchRequestSchema.safeParse(body, { reportInput: true });
+  if (parsed.success) {
+    return null;
+  }
+  const [first] = parsed.error.issues;
+  if (!first) {
+    return { message: "Invalid search" };
+  }
+  const flag = flagFor(first.path);
+  if (first.code === "invalid_value") {
+    const sameFlag = parsed.error.issues.filter((i) => i.code === "invalid_value" && flagFor(i.path) === flag);
+    const invalidValues = sameFlag.map((i) => String(i.input));
+    const validValues = first.values.map(String);
+    return {
+      message: `Unknown ${flag} value${invalidValues.length > 1 ? "s" : ""} ${invalidValues.map((v) => `"${v}"`).join(", ")}.`,
+      fix: {
+        action: "retry_with_valid_values",
+        explanation: `Re-run with values from \`validValues\` for ${flag}, or drop the flag.`,
+        flag,
+        invalidValues,
+        validValues
+      }
+    };
+  }
+  return { message: first.path.length > 0 ? `${flag}: ${first.message}` : first.message };
+}
+var NUMERIC_FLAGS = [
+  ["--limit", "limit"],
+  ["--max-per-advertiser", "maxPerAdvertiser"],
+  ["--min-relevance", "minRelevance"]
+];
+function searchRejection(args, body) {
+  if (args.scope !== void 0 && !winnerSearchScopeSchema.safeParse(args.scope).success) {
+    return { message: `Unknown --scope "${args.scope}". Use one of: ${winnerSearchScopeSchema.options.join(", ")}.` };
+  }
+  if (args.sort !== void 0 && !winnersSortSchema.safeParse(args.sort).success) {
+    return { message: `Unknown --sort "${args.sort}". Use one of: ${winnersSortSchema.options.join(", ")}.` };
+  }
+  if (args.partnership !== void 0 && !(args.partnership in PARTNERSHIP_VALUES)) {
+    return { message: `Unknown --partnership "${args.partnership}". Use one of: only, exclude.` };
+  }
+  for (const [flag, key] of NUMERIC_FLAGS) {
+    const value = args[key];
+    if (value !== void 0 && value !== "" && Number.isNaN(Number(value))) {
+      return { message: `${flag} must be a number, got "${value}".` };
+    }
+  }
+  if (!("free_text_query" in body || "ref_ad_id" in body || "hard_filters" in body)) {
+    return { message: "Provide a query, --ref-ad-id, or a filter flag" };
+  }
+  return schemaRejection(body);
+}
+function writeSearchResult(data, opts) {
+  const rawResults = Array.isArray(data?.results) ? data.results : [];
+  const hints = searchHints(data ?? {});
+  const withHints = hints.length > 0 ? { hints } : {};
+  if (opts.output === "json") {
+    const results = adRows(rawResults, opts);
+    writeJson({
+      ok: true,
+      data: {
+        results,
+        scope: data?.scope ?? null,
+        following_count: data?.following_count ?? null,
+        pool_size: data?.pool_size ?? null,
+        match_confidence: data?.match_confidence ?? null,
+        below_floor_count: data?.below_floor_count ?? null,
+        country_coverage: data?.country_coverage ?? null
+      },
+      ...withHints
+    });
+    return;
+  }
+  writeOutput({ ok: true, data: rawResults, ...withHints }, opts.output, opts.fields, opts.full, winningAdNormalizer);
+}
+var SEARCH_TIMEOUT_MS = 12e4;
+var searchCommand = defineCommand({
+  meta: {
+    name: "search",
+    description: "Search winning reference ads, the company's followed brands first. Start here: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --exclude-advertiser adv_123 --output md. A set of references for N concepts in one call: add --diverse --limit N. The best proven ad in one container from any category: --format-pattern comparison_table (no query needed; add --sort longest_running to order by staying power). References for viewers who don't know the brand: --audience-temperature 0_cold --exclude-brand-reliant. What competitors kept after testing: --survived-test. What competitors run through creators: --partnership only. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry."
+  },
+  args: {
+    query: { type: "positional", description: "Free-text search query", required: false },
+    scope: {
+      type: "string",
+      description: "followed-first (default) | followed | all. followed-first = the company's followed brands first, topped up from the whole library (the whole library when it follows nobody)",
+      required: false
+    },
+    "ref-ad-id": { type: "string", description: "Find ads similar to this ad id", required: false },
+    limit: {
+      type: "string",
+      description: "Max results 1-100 (default 10 \u2014 a shortlist)",
+      required: false,
+      default: "10"
+    },
+    "max-per-advertiser": {
+      type: "string",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after the other brands, none dropped. Set 1-50 to drop past N (1 = one reference per brand), 0 for rank order",
+      required: false
+    },
+    "min-relevance": { type: "string", description: "Relevance floor 0-1", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a no-query browse: winner (default) | longest_running | newest. Ignored when a query is given",
+      required: false
+    },
+    platform: {
+      type: "string",
+      description: "Comma list of platforms (meta,linkedin,tiktok,google) \u2014 search one or several",
+      required: false
+    },
+    format: { type: "string", description: "Comma list of formats (video,static,carousel,text)", required: false },
+    "winner-category": {
+      type: "string",
+      description: "Comma list of winner categories (default: all)",
+      required: false
+    },
+    awareness: { type: "string", description: "Comma list of awareness stages", required: false },
+    "audience-temperature": {
+      type: "string",
+      description: "Comma list of who the ad was made for: 0_cold | 1_warm_engaged | 2_hot_visited | 3_customer (a cold brief takes 0_cold)",
+      required: false
+    },
+    "funnel-stage": { type: "string", description: "Comma list: TOF,MOF,BOF", required: false },
+    "advertiser-size": { type: "string", description: "Comma list: solo,smb,mid,enterprise", required: false },
+    "exclude-brand-reliant": {
+      type: "boolean",
+      description: "Drop ads that only work if the viewer already knows the brand (ads not judged yet are kept). Use it when making ads for viewers who don't know the brand",
+      required: false,
+      default: false
+    },
+    country: {
+      type: "string",
+      description: "Comma list of ISO country codes (US,GB): ads known to run there, plus ads with no country data (every Meta ad) in that country's main language. An unknown code is refused with the codes that have ads",
+      required: false
+    },
+    language: { type: "string", description: LANGUAGE_DESCRIPTION, required: false },
+    "advertiser-id": { type: "string", description: "Restrict to these advertiser ids", required: false },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids, usually your own brand",
+      required: false
+    },
+    "first-seen-after": { type: "string", description: "ISO date or datetime lower bound", required: false },
+    "first-seen-before": { type: "string", description: "ISO date or datetime upper bound", required: false },
+    "hook-archetype": {
+      type: "string",
+      description: "Comma list of proven hook seeds (from `winning-ads hooks`) to narrow the search",
+      required: false
+    },
+    "format-pattern": {
+      type: "string",
+      description: FORMAT_PATTERN_DESCRIPTION,
+      required: false
+    },
+    stage: { type: "string", description: STAGE_DESCRIPTION, required: false },
+    "survived-test": { type: "boolean", description: SURVIVED_TEST_DESCRIPTION, required: false, default: false },
+    partnership: { type: "string", description: PARTNERSHIP_DESCRIPTION, required: false },
+    "all-kinds": {
+      type: "boolean",
+      description: "Also return Google search text, Shopping and app ads (default: designed pictures and videos only)",
+      required: false,
+      default: false
+    },
+    diverse: {
+      type: "boolean",
+      description: "One varied set (different brands, containers, hooks): a reference per concept in one call",
+      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, awareness, industry) + reach and media kind; mechanism, days_active, active, winner_category, audience_temperature, funnel_stage, advertiser_size and presumes_brand_knowledge are in the default output",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const searchArgs = {
+        query: args.query,
+        scope: args.scope,
+        refAdId: args["ref-ad-id"],
+        limit: args.limit,
+        maxPerAdvertiser: args["max-per-advertiser"],
+        minRelevance: args["min-relevance"],
+        sort: args.sort,
+        platform: args.platform,
+        format: args.format,
+        winnerCategory: args["winner-category"],
+        awareness: args.awareness,
+        audienceTemperature: args["audience-temperature"],
+        funnelStage: args["funnel-stage"],
+        advertiserSize: args["advertiser-size"],
+        excludeBrandReliant: args["exclude-brand-reliant"],
+        country: args.country,
+        language: args.language,
+        advertiserId: args["advertiser-id"],
+        excludeAdvertiser: args["exclude-advertiser"],
+        firstSeenAfter: args["first-seen-after"],
+        firstSeenBefore: args["first-seen-before"],
+        hookArchetype: args["hook-archetype"],
+        formatPattern: args["format-pattern"],
+        stage: args.stage,
+        survivedTest: args["survived-test"],
+        partnership: args.partnership,
+        diverse: args.diverse
+      };
+      const fieldPlan = adFieldPlan(args.fields, args.full);
+      const body = designedByDefault(buildSearchBody(searchArgs), { allKinds: args["all-kinds"] });
+      const rejection = searchRejection(searchArgs, body);
+      if (rejection) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", ...rejection } });
+        process.exit(1);
+      }
+      const data = await apiPost("/api/ad-library/winners/search", body, {
+        timeoutMs: SEARCH_TIMEOUT_MS
+      });
+      writeSearchResult(data, { output: args.output || "json", ...fieldPlan });
+    } catch (err) {
+      reportSearchError(err);
+    }
+  }
+});
+
+export {
+  buildSearchBody,
+  designedByDefault,
+  searchHints,
+  unknownCountryFix,
+  searchErrorFix,
+  searchRejection,
+  searchCommand
+};
+//# sourceMappingURL=chunk-F2OCUTMQ.js.map