@koda-sl/baker-cli 0.423.0 → 0.424.0

package/dist/{chunk-XNFV6BQU.js → chunk-PHLFNYGQ.js}

@@ -2,13 +2,13 @@ import {
   handleConnectionError,
   needsConnectionFix,
   writeAdsJson
-} from "./chunk-3X2EMLBQ.js";
+} from "./chunk-RFZYRG2Q.js";
 import {
   ApiError
-} from "./chunk-G5L5FX2B.js";
+} from "./chunk-Q6F5UNOU.js";
 import {
   getEnv
-} from "./chunk-5JVAP5DC.js";
+} from "./chunk-FQOKJYKN.js";
 
 // src/commands/ads/meta/shared.ts
 var DAY_MS = 864e5;
@@ -133,4 +133,4 @@ export {
   resolveEffectiveStatus,
   statusFilterHints
 };
-//# sourceMappingURL=chunk-XNFV6BQU.js.map
+//# sourceMappingURL=chunk-PHLFNYGQ.js.map

package/dist/{chunk-G5L5FX2B.js → chunk-Q6F5UNOU.js}

@@ -1,10 +1,10 @@
 import {
   debugLogHttp,
   readBodyForLog
-} from "./chunk-S36N4SOX.js";
+} from "./chunk-GCTR4MDE.js";
 import {
   getEnv
-} from "./chunk-5JVAP5DC.js";
+} from "./chunk-FQOKJYKN.js";
 
 // src/client.ts
 var MAX_RATE_LIMIT_RETRIES = 3;
@@ -208,4 +208,4 @@ export {
   apiGet,
   apiPost
 };
-//# sourceMappingURL=chunk-G5L5FX2B.js.map
+//# sourceMappingURL=chunk-Q6F5UNOU.js.map

package/dist/{chunk-3X2EMLBQ.js → chunk-RFZYRG2Q.js}

@@ -1,10 +1,10 @@
 import {
   ApiError,
   apiGet
-} from "./chunk-G5L5FX2B.js";
+} from "./chunk-Q6F5UNOU.js";
 import {
   getEnv
-} from "./chunk-5JVAP5DC.js";
+} from "./chunk-FQOKJYKN.js";
 
 // src/error-handler.ts
 var REQUEST_CONNECTION_PLATFORM = {
@@ -298,4 +298,4 @@ export {
   writeAdsOutput,
   resolveCustomerId
 };
-//# sourceMappingURL=chunk-3X2EMLBQ.js.map
+//# sourceMappingURL=chunk-RFZYRG2Q.js.map

package/dist/cli.js

@@ -249,6 +249,7 @@ import {
   spellNumber,
   splitScriptFor,
   spokenWordsIn,
+  staticFormatPatternSchema,
   staticMasterFormat,
   staticRenderNodes,
   staticVerdict,
@@ -284,7 +285,7 @@ import {
   wordCount,
   xDraftOpInputSchema,
   ytDlpBlockSignal
-} from "./chunk-SWYBHYB5.js";
+} from "./chunk-IR4ZOEZV.js";
 import {
   NAME_CONTAINS_ARG,
   csvOrJson,
@@ -295,7 +296,7 @@ import {
   resolveEffectiveStatus,
   statusFilterHints,
   todayIso
-} from "./chunk-XNFV6BQU.js";
+} from "./chunk-PHLFNYGQ.js";
 import {
   buildQueryCacheKey,
   cacheGet,
@@ -311,32 +312,35 @@ import {
   writeAdsJson,
   writeAdsOutput,
   writeJsonEnvelope
-} from "./chunk-3X2EMLBQ.js";
+} from "./chunk-RFZYRG2Q.js";
 import {
   ApiError,
   apiGet,
   apiGetWithHeaders,
   apiPost,
   validateConvexId
-} from "./chunk-G5L5FX2B.js";
+} from "./chunk-Q6F5UNOU.js";
 import {
   installExitRecord,
   installStreamTaps,
   logInvocation
-} from "./chunk-S36N4SOX.js";
+} from "./chunk-GCTR4MDE.js";
 import {
   __commonJS,
   __esm,
   __glob,
   __toESM,
   adContentNormalizer,
+  applyFieldMask,
   captureBudgetMs,
   captureProxyCredentials,
   captureVimeoCookie,
   commandPathOf,
   compactImage,
   compactVideo,
+  compactWinningAd,
   findSchema,
+  fullWinningAd,
   getEnv,
   installFieldMask,
   isProxyFailure,
@@ -358,7 +362,7 @@ import {
   winningAdNormalizer,
   writeJson,
   writeOutput
-} from "./chunk-5JVAP5DC.js";
+} from "./chunk-FQOKJYKN.js";
 
 // ../../node_modules/.pnpm/i18n-iso-countries@7.14.0/node_modules/i18n-iso-countries/langs/af.json
 var require_af = __commonJS({
@@ -45234,10 +45238,10 @@ Example: baker ads meta ads retag 120252158038400247 --url-tags "utm_source={{si
     }
   },
   run: async ({ args: args8 }) => {
-    const { apiPost: apiPost2 } = await import("./client-PIKJZFRA.js");
-    const { requireChatId: requireChatId2 } = await import("./env-6UAIAY4M.js");
-    const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-CFDBWWYJ.js");
-    const { handleMetaError: handleMetaError2 } = await import("./shared-3O5RKQYZ.js");
+    const { apiPost: apiPost2 } = await import("./client-GS7T7ETG.js");
+    const { requireChatId: requireChatId2 } = await import("./env-SL22S6CM.js");
+    const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-OFDKEPPJ.js");
+    const { handleMetaError: handleMetaError2 } = await import("./shared-XR54KFMH.js");
     try {
       const accountId = bareAccountId2(args8);
       const urlTags = typeof args8["url-tags"] === "string" ? args8["url-tags"] : void 0;
@@ -45388,10 +45392,10 @@ function duplicateCommand2(entity, label) {
       replace: { type: "boolean", description: "Pause the original once the copy publishes" }
     },
     run: async ({ args: args8 }) => {
-      const { apiPost: apiPost2 } = await import("./client-PIKJZFRA.js");
-      const { requireChatId: requireChatId2 } = await import("./env-6UAIAY4M.js");
-      const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-CFDBWWYJ.js");
-      const { handleMetaError: handleMetaError2 } = await import("./shared-3O5RKQYZ.js");
+      const { apiPost: apiPost2 } = await import("./client-GS7T7ETG.js");
+      const { requireChatId: requireChatId2 } = await import("./env-SL22S6CM.js");
+      const { writeJsonEnvelope: writeJsonEnvelope2 } = await import("./output-OFDKEPPJ.js");
+      const { handleMetaError: handleMetaError2 } = await import("./shared-XR54KFMH.js");
       try {
         const accountId = bareAccountId2(args8);
         const chatId = requireChatId2();
@@ -94660,9 +94664,8 @@ registerSchema({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin|tiktok", required: false },
     "per-advertiser": {
       type: "number",
-      description: "Max winners kept per advertiser 0-50 (0 = no cap, default 5)",
-      required: false,
-      default: 5
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after, none dropped. Set 1-50 to keep at most N per brand, 0 for rank order",
+      required: false
     },
     limit: {
       type: "number",
@@ -94677,7 +94680,7 @@ registerSchema({
 var feedCommand2 = defineCommand295({
   meta: {
     name: "feed",
-    description: "Winners across every brand you follow (browse, then trim per advertiser). Example: baker winning-ads feed --per-advertiser 5 --output md"
+    description: "Winners across every brand you follow, each brand's best first. Example: baker winning-ads feed --output md"
   },
   args: {
     advertiser: {
@@ -94688,7 +94691,7 @@ var feedCommand2 = defineCommand295({
     platform: { type: "string", description: "Filter to a single platform: meta|linkedin|tiktok", required: false },
     "per-advertiser": {
       type: "string",
-      description: "Max winners per advertiser 0-50 (0 = no cap, default 5)",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after, none dropped. Set 1-50 to keep at most N per brand, 0 for rank order",
       required: false
     },
     limit: { type: "string", description: "Total winners 1-200 (default 40)", required: false },
@@ -95089,6 +95092,8 @@ var refreshCommand = defineCommand299({
 
 // src/commands/winning-ads/search.ts
 import { defineCommand as defineCommand300 } 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 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. A value outside a closed list (--platform, --format, --winner-category, --awareness, --audience-temperature, --funnel-stage, --advertiser-size, --format-pattern, --sort) is refused with error.fix.validValues.",
@@ -95108,9 +95113,8 @@ registerSchema({
     limit: { type: "number", description: "Max results 1-100 (default 10)", required: false, default: 10 },
     "max-per-advertiser": {
       type: "number",
-      description: "Cap results per advertiser 0-50 (default 3; 0 = no cap), also when the company follows one brand",
-      required: false,
-      default: 3
+      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: {
@@ -95150,10 +95154,10 @@ registerSchema({
     },
     country: {
       type: "string",
-      description: "Comma list of ISO country codes (US,GB) \u2014 an unknown code is refused with the codes that have ads",
+      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: "Comma list of language codes", 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)",
@@ -95181,7 +95185,7 @@ registerSchema({
     },
     "format-pattern": {
       type: "string",
-      description: "Comma list of static containers (from `winning-ads formats`, e.g. comparison_table,before_after_split) \u2014 the best proven ads in that container, whatever they sell",
+      description: FORMAT_PATTERN_DESCRIPTION,
       required: false
     },
     diverse: {
@@ -95236,7 +95240,7 @@ function buildSearchBody2(args8) {
     hardFilters.presumes_brand_knowledge = false;
   }
   setList(hardFilters, "country", args8.country);
-  setList(hardFilters, "language", args8.language);
+  setList(hardFilters, "language", args8.language?.toLowerCase());
   setList(hardFilters, "advertiser_ids", args8.advertiserId);
   setList(hardFilters, "exclude_advertiser_ids", args8.excludeAdvertiser);
   setList(hardFilters, "hook_archetype_seeds", args8.hookArchetype);
@@ -95258,6 +95262,10 @@ function searchHints2(data) {
     hints2.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) {
+    hints2.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 adapted = (data.results ?? []).filter(
     (r) => r?.baker_uses?.ours === true
@@ -95287,8 +95295,17 @@ function unknownCountryFix(message) {
     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 ? unknownCountryFix(err.message) : null;
+  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);
@@ -95364,12 +95381,38 @@ function searchRejection(args8, body) {
   }
   return schemaRejection(body);
 }
+var EVERY_SIGNAL = {
+  dna: {
+    visual: "-",
+    container: "-",
+    mechanism: "-",
+    audience_temperature: "-",
+    funnel_stage: "-",
+    advertiser_size: "-",
+    presumes_brand_knowledge: true,
+    brand_knowledge_reason: "-"
+  },
+  baker_uses: { companies: 1, ours: true, approved: 1, rejected: 1 },
+  source: "followed"
+};
+var COMPACT_FIELDS = new Set(Object.keys(compactWinningAd(EVERY_SIGNAL)));
+var ALL_FIELDS = Object.keys(fullWinningAd(EVERY_SIGNAL));
+function searchFields(requested, full) {
+  if (!requested) return { fields: void 0, full };
+  const fields = requested.map((f) => f.trim()).filter(Boolean);
+  const invalid = fields.filter((f) => !ALL_FIELDS.includes(f));
+  if (invalid.length > 0) return { invalid, valid: ALL_FIELDS };
+  return { fields, full: full || fields.some((f) => !COMPACT_FIELDS.has(f)) };
+}
 function writeSearchResult(data, opts) {
   const rawResults = Array.isArray(data?.results) ? data.results : [];
   const hints2 = searchHints2(data ?? {});
   const withHints2 = hints2.length > 0 ? { hints: hints2 } : {};
   if (opts.output === "json") {
-    const results = rawResults.map((r) => winningAdNormalizer(r, opts.full));
+    const results = rawResults.map((r) => {
+      const row2 = winningAdNormalizer(r, opts.full);
+      return opts.fields ? applyFieldMask(row2, opts.fields) : row2;
+    });
     writeJson({
       ok: true,
       data: {
@@ -95409,7 +95452,7 @@ var searchCommand6 = defineCommand300({
     },
     "max-per-advertiser": {
       type: "string",
-      description: "Cap results per advertiser 0-50 (default 3; 0 = no cap), also when the company follows one brand",
+      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 },
@@ -95445,10 +95488,10 @@ var searchCommand6 = defineCommand300({
     },
     country: {
       type: "string",
-      description: "Comma list of ISO country codes (US,GB) \u2014 an unknown code is refused with the codes that have ads",
+      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: "Comma list of language codes", 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",
@@ -95464,7 +95507,7 @@ var searchCommand6 = defineCommand300({
     },
     "format-pattern": {
       type: "string",
-      description: "Comma list of static containers (from `winning-ads formats`, e.g. comparison_table) \u2014 the best proven ads in it from any category",
+      description: FORMAT_PATTERN_DESCRIPTION,
       required: false
     },
     diverse: {
@@ -95510,6 +95553,27 @@ var searchCommand6 = defineCommand300({
         formatPattern: args8["format-pattern"],
         diverse: args8.diverse
       };
+      const fieldPlan = searchFields(
+        args8.fields ? args8.fields.split(",") : void 0,
+        args8.full
+      );
+      if ("invalid" in fieldPlan) {
+        writeJson({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `Unknown --fields: ${fieldPlan.invalid.join(", ")}`,
+            fix: {
+              action: "retry_with_valid_values",
+              explanation: "Pass only fields a search row carries.",
+              flag: "--fields",
+              invalidValues: fieldPlan.invalid,
+              validValues: fieldPlan.valid
+            }
+          }
+        });
+        process.exit(1);
+      }
       const body = buildSearchBody2(searchArgs);
       const rejection = searchRejection(searchArgs, body);
       if (rejection) {
@@ -95519,11 +95583,7 @@ var searchCommand6 = defineCommand300({
       const data = await apiPost("/api/ad-library/winners/search", body, {
         timeoutMs: SEARCH_TIMEOUT_MS
       });
-      writeSearchResult(data, {
-        output: args8.output || "json",
-        fields: args8.fields ? args8.fields.split(",") : void 0,
-        full: args8.full
-      });
+      writeSearchResult(data, { output: args8.output || "json", ...fieldPlan });
     } catch (err) {
       reportSearchError(err);
     }
@@ -95724,7 +95784,7 @@ Examples:
   baker winning-ads advertisers "Acme" --output md
   baker winning-ads follow "deel.com" --platform meta
   baker winning-ads follow-competitors "deel.com,notion.so,hubspot.com"
-  baker winning-ads feed --per-advertiser 5 --output md
+  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 --top 15 --output md
   baker winning-ads content adg_123 --full --output md