@koda-sl/baker-cli 0.457.0 → 0.458.0

package/dist/chunk-EOWMPN3Q.js

@@ -0,0 +1,51 @@
+import {
+  failApi
+} from "./chunk-IH4NS3NT.js";
+import {
+  HUBSPOT_MISSING_GRANT_MARKER,
+  HUBSPOT_NOT_CONNECTED_MESSAGE
+} from "./chunk-ZJVHZHYP.js";
+import {
+  ApiError
+} from "./chunk-TOYLG3ZY.js";
+import {
+  writeJson
+} from "./chunk-ZZFYDAJQ.js";
+
+// src/commands/hubspot/refusal.ts
+var CONTINUE = "Keep going with the wider task: say which part you could not read, skip it, and finish everything else. If the `request_connection` call fails, say so plainly and give the exact route: dashboard \u2192 Brain \u2192 Integrations \u2192 Platforms \u2192 HubSpot.";
+function hubspotRefusal(code, message, reason = "so I can count a contact becoming a customer") {
+  if (code === "NOT_FOUND" && message.includes(HUBSPOT_NOT_CONNECTED_MESSAGE)) {
+    return {
+      code: "NO_HUBSPOT_CONNECTION",
+      fix: {
+        action: "request_connection",
+        explanation: `AGENT INSTRUCTION: HubSpot is not connected, and only the user can connect it. Call the \`request_connection\` tool with { platform: "hubspot", reason } \u2014 reason in their words, e.g. "${reason}" \u2014 and they connect it inside the chat; then run this command again. ` + CONTINUE
+      }
+    };
+  }
+  if (code === "FORBIDDEN" && message.includes(HUBSPOT_MISSING_GRANT_MARKER)) {
+    return {
+      code: "HUBSPOT_RECONNECT_REQUIRED",
+      fix: {
+        action: "request_connection",
+        explanation: 'AGENT INSTRUCTION: HubSpot is connected \u2014 do not tell the user it is missing, and do not retry. Its access does not cover this read (it was connected before Baker asked for it, or the access was withdrawn), and only the user can widen it. Call the `request_connection` tool with { platform: "hubspot", reason } naming what you need to read; the card offers them a Reconnect button. Run this command again once they have. ' + CONTINUE
+      }
+    };
+  }
+  return null;
+}
+function failNotConnected(err, reason) {
+  const refusal = err instanceof ApiError ? hubspotRefusal(err.code, err.message, reason) : null;
+  if (err instanceof ApiError && refusal !== null) {
+    writeJson({ ok: false, error: { code: refusal.code, message: err.message, fix: refusal.fix } });
+    process.exit(1);
+  }
+  failApi(err);
+}
+
+export {
+  hubspotRefusal,
+  failNotConnected
+};
+//# sourceMappingURL=chunk-EOWMPN3Q.js.map

package/dist/chunk-F66W4QQL.js

@@ -0,0 +1,92 @@
+import {
+  claimNewCreativeInWorkspace,
+  creativeLimitRefusal
+} from "./chunk-SMVHUBXE.js";
+import {
+  leadVersion,
+  writeSeriesMemberCanvas
+} from "./chunk-O5MNUL7C.js";
+import {
+  definitionFieldsOf,
+  setDefinitionFields,
+  setSpecMessage
+} from "./chunk-35QYDREI.js";
+import {
+  IDEAS_DIR
+} from "./chunk-6C4S466W.js";
+
+// src/commands/creatives/make-series.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { parseDocument } from "yaml";
+var LEAD_ONLY = ["idea", "message", "evidence", "angle", "persona", "awareness", "hypothesis", "series", "title"];
+function withoutFields(raw, keys) {
+  const match = raw.match(/^---\r?\n([\s\S]*?\r?\n)?---/);
+  if (!match) return raw;
+  const doc = parseDocument(match[1] ?? "");
+  if (doc.errors.length > 0) return raw;
+  for (const key of keys) doc.delete(key);
+  return `---
+${doc.toString()}---${raw.slice(match[0].length)}`;
+}
+async function makeSeriesAd(root, idea, slug, lead, evidence, deps) {
+  if (slug === lead) {
+    return {
+      code: "series_of_itself",
+      message: `"${slug}" is the lead itself.`,
+      fix: "Give the new ad its own --slug."
+    };
+  }
+  const version = await leadVersion(root, lead);
+  if ("refused" in version) return version.refused;
+  const dir = path.join(root, "src", "creatives", slug);
+  const definitionPath = path.join(dir, "_definition.md");
+  const claim = await claimNewCreativeInWorkspace(path.join(root, "canvas"), slug, deps.chatId, definitionPath);
+  if (!claim.allowed) return creativeLimitRefusal(slug).error;
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, "prompt.json"), setSpecMessage(JSON.stringify(version.spec), idea.message), "utf8");
+  const leadDefinition = await readFile(path.join(root, "src", "creatives", lead, "_definition.md"), "utf8").catch(
+    () => "---\nkind: static\n---\n"
+  );
+  const definition = setDefinitionFields(withoutFields(leadDefinition, LEAD_ONLY), {
+    title: idea.message.slice(0, 120),
+    series: lead,
+    status: "draft",
+    ...definitionFieldsOf(idea, evidence)
+  });
+  await writeFile(definitionPath, definition, "utf8");
+  const made = await writeSeriesMemberCanvas(root, slug, { leadWords: true });
+  if (made === null || "refused" in made) {
+    return made?.refused ?? { code: "series_not_made", message: `"${slug}" could not be made in the series of "${lead}".` };
+  }
+  if (idea.status === "idea") {
+    const ideaPath = path.join(root, IDEAS_DIR, `${idea.id}.md`);
+    const raw = await readFile(ideaPath, "utf8").catch(() => null);
+    if (raw !== null) await writeFile(ideaPath, setDefinitionFields(raw, { status: "built" }), "utf8");
+  }
+  await deps.sync(dir);
+  return { slug, lead, leadRunId: version.lead.runId, canvasPath: made.canvasPath };
+}
+function seriesMadeEnvelope(made, idea) {
+  return {
+    ok: true,
+    data: {
+      creative: made.slug,
+      idea: idea.id,
+      message: idea.message,
+      series: made.lead,
+      canvas_path: made.canvasPath
+    },
+    hints: [
+      `Write this ad's words in src/creatives/${made.slug}/prompt.json \`copy\`: one line for each of the lead's, in the same roles and about as long, saying this idea's message. Change nothing else: the picture, layout and colours are the lead's (${made.lead}), and every word you write replaces the lead's line in its place.`,
+      `When every ad of the series has its words: baker canvas run --series ${made.lead} (renders them all at once, each reviewed and corrected on its own).`
+    ]
+  };
+}
+
+export {
+  withoutFields,
+  makeSeriesAd,
+  seriesMadeEnvelope
+};
+//# sourceMappingURL=chunk-F66W4QQL.js.map

package/dist/chunk-FCADB4RG.js

@@ -0,0 +1,535 @@
+import {
+  adFieldPlan,
+  adRows
+} from "./chunk-OIS3WG2U.js";
+import {
+  reportError,
+  splitList
+} from "./chunk-3FOE4P6A.js";
+import {
+  scopedWinnersSearchRequestSchema,
+  staticFormatPatternSchema,
+  winnerSearchScopeSchema,
+  winnersSortSchema
+} from "./chunk-VAOMHPEX.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-TOYLG3ZY.js";
+import {
+  registerSchema,
+  winningAdNormalizer,
+  writeJson,
+  writeOutput
+} from "./chunk-ZZFYDAJQ.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 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 },
+    "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 (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(", ")}.` };
+  }
+  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. 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 },
+    "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"],
+        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-FCADB4RG.js.map