@koda-sl/baker-cli 0.463.0 → 0.465.0

package/dist/chunk-PBHQPJZG.js

@@ -0,0 +1,474 @@
+import {
+  holdUnbilledSpend
+} from "./chunk-DZD3XEBO.js";
+import {
+  findWorkspaceRoot
+} from "./chunk-YOFHPTWU.js";
+import {
+  bytesOf
+} from "./chunk-UC4C6JUW.js";
+import {
+  CONCEPT_CARRY_LEVELS
+} from "./chunk-FPUVMFR6.js";
+import {
+  AD_DESCRIBE_MODEL
+} from "./chunk-CHSNHVYF.js";
+import {
+  askAboutImages
+} from "./chunk-PGZ4EHAA.js";
+import {
+  apiGet
+} from "./chunk-T2MH5SCT.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-SHVQFDNY.js";
+
+// src/commands/winning-ads/fit.ts
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+import sharp from "sharp";
+import { z } from "zod";
+
+// src/commands/canvas/library-reference.ts
+var LIBRARY_PLATFORMS = ["meta", "linkedin", "tiktok", "google"];
+function resolveSourcePlatform(flag) {
+  const value = flag?.trim();
+  if (!value) return { ok: true, platform: "meta" };
+  if (LIBRARY_PLATFORMS.includes(value)) return { ok: true, platform: value };
+  return {
+    ok: false,
+    message: `--source-platform "${value}" is not a library platform. Use one of: ${LIBRARY_PLATFORMS.join(", ")}.`
+  };
+}
+var PICK_A_DESIGN = "To build a static on a proven design, pick a Google display ad or a static from another platform (`baker winning-ads search --format static`); a YouTube ad is a video reference, read with `baker winning-ads content`.";
+function notADesignReference(platform, adId, ad) {
+  if (platform !== "google") return null;
+  if (ad.format === "text" || ad.google_ad_type === "search") {
+    return {
+      code: "NOT_A_DESIGN_REFERENCE",
+      message: `Google ad ${adId} is a search text ad: a reference for wording, not a design.`,
+      fix: `Read it with \`baker winning-ads content ${adId} --platform google\` and write our own copy. ${PICK_A_DESIGN}`
+    };
+  }
+  const assembled = ad.google_ad_type === "shopping" ? "a Shopping product listing, which Google builds from a product feed" : ad.google_ad_type === "app" ? "an app-install ad, which Google builds from the app's store page" : null;
+  if (assembled) {
+    return {
+      code: "NOT_A_DESIGN_REFERENCE",
+      message: `Google ad ${adId} is ${assembled}: there is no design of the advertiser's to build on.`,
+      fix: PICK_A_DESIGN
+    };
+  }
+  return null;
+}
+async function fetchLibraryReference(adId, platform) {
+  const data = await apiGet("/api/ad-library/ad-content", { id: adId, platform });
+  if (!data?.ad) throw new Error(`the library returned no ad for ${adId} on ${platform}`);
+  return data.ad;
+}
+function filled(entries) {
+  return Object.fromEntries(
+    Object.entries(entries).filter(([, v]) => v !== null && v !== void 0 && !(Array.isArray(v) && v.length === 0))
+  );
+}
+function libraryReferenceBlock(ad, ids) {
+  const textBlocks = ad.on_screen_text.flatMap(
+    (o) => o.text ? [{ text: o.text, ...o.role ? { role: o.role } : {}, ...o.position ? { position: o.position } : {} }] : []
+  );
+  const advertiser = ad.advertiser ?? void 0;
+  const advertiserId = ids.advertiserId ?? ad.advertiser_id ?? void 0;
+  return {
+    ad_id: ids.adId,
+    platform: ids.platform,
+    ...advertiser ? { advertiser } : {},
+    ...advertiserId ? { advertiser_id: advertiserId } : {},
+    ...ad.layout.format_pattern ? { format_pattern: ad.layout.format_pattern } : {},
+    layout: filled({
+      composition: ad.layout.composition,
+      focal_subject: ad.layout.focal_subject,
+      aspect_ratio: ad.layout.aspect_ratio,
+      background: ad.layout.background,
+      palette_mood: ad.layout.palette_mood,
+      colors: ad.layout.colors,
+      production: ad.layout.production,
+      aesthetic: ad.layout.aesthetic,
+      cta_in_image: ad.layout.cta_in_image,
+      markers: ad.layout.markers
+    }),
+    message: filled({
+      mechanism: ad.message.mechanism,
+      awareness: ad.message.awareness_stage,
+      sophistication: ad.message.sophistication,
+      angle: ad.angle,
+      hook_archetype: ad.hook_archetype,
+      pain_points: ad.message.pain_points,
+      desires: ad.message.desires,
+      value_props: ad.message.value_props,
+      objections_handled: ad.message.objections_handled,
+      proof: ad.message.proof,
+      risk_reversal: ad.message.risk_reversal
+    }),
+    offer: filled({
+      offer_type: ad.offer.offer_type,
+      pricing_model: ad.offer.pricing_model,
+      entry_price: ad.offer.entry_price,
+      no_credit_card: ad.offer.no_credit_card,
+      guarantee: ad.offer.guarantee,
+      guarantee_days: ad.offer.guarantee_days,
+      urgency: ad.offer.urgency,
+      bonus: ad.offer.bonus
+    }),
+    text_blocks: textBlocks,
+    copy: filled({ primary_text: ad.primary_text, headline: ad.headline, cta: ad.cta })
+  };
+}
+function referenceDescribeContext(reference, agentContext) {
+  const own = agentContext?.trim() || void 0;
+  if (!reference) return own;
+  const facts = [];
+  if (reference.advertiser) facts.push(`advertiser: ${reference.advertiser}`);
+  if (reference.format_pattern) facts.push(`container (format_pattern): ${reference.format_pattern}`);
+  if (typeof reference.layout.composition === "string") facts.push(`composition: ${reference.layout.composition}`);
+  if (typeof reference.message.mechanism === "string") facts.push(`persuasion mechanism: ${reference.message.mechanism}`);
+  if (typeof reference.message.awareness === "string") facts.push(`awareness stage: ${reference.message.awareness}`);
+  if (typeof reference.offer.offer_type === "string") facts.push(`offer: ${reference.offer.offer_type}`);
+  if (reference.text_blocks.length > 0) {
+    facts.push(
+      `text blocks: ${reference.text_blocks.map((b) => `"${b.text}"${b.role ? ` (${b.role})` : ""}`).join("; ")}`
+    );
+  }
+  const library = `The ads library has already read this ad: ${facts.join(". ")}. Your blueprint must agree with it on the container and the mechanism; refine and detail them, never contradict them, and transcribe the text blocks exactly.`;
+  return own ? `${own}. ${library}` : library;
+}
+function mergeReferenceIntoBlueprint(blueprint, reference) {
+  if (!reference || !blueprint || typeof blueprint !== "object" || Array.isArray(blueprint)) return blueprint;
+  return { ...blueprint, reference };
+}
+
+// src/commands/winning-ads/fit.ts
+var Layers = z.object({
+  disguise: z.string().optional(),
+  voice: z.string().optional(),
+  trigger: z.string().optional(),
+  attention: z.string().optional(),
+  logic: z.string().optional()
+}).strip();
+var FitAnswerSchema = z.object({
+  why_it_wins: Layers.default({}),
+  load_bearing: z.array(
+    z.object({
+      element: z.string().trim().min(1),
+      needs: z.string().optional(),
+      have: z.enum(["have", "adapt", "missing"]),
+      ours: z.string().optional()
+    }).strip()
+  ).default([]),
+  verdict: z.enum(["use", "adapt", "reject"]),
+  transfer_note: z.string().optional(),
+  brand_presence: z.enum(["native", "standard"]).optional(),
+  recognition: z.string().optional(),
+  carry: z.enum(CONCEPT_CARRY_LEVELS).optional(),
+  carry_why: z.string().optional()
+});
+function buildFitPrompt(input) {
+  const lib = input.library;
+  const facts = [
+    lib.advertiser ? `advertiser: ${lib.advertiser}` : "",
+    lib.format_pattern ? `container: ${lib.format_pattern}` : "",
+    lib.mechanism ? `persuasion mechanism: ${lib.mechanism}` : "",
+    lib.awareness ? `awareness stage: ${lib.awareness}` : "",
+    lib.offer ? `offer: ${lib.offer}` : "",
+    lib.winner_category ? `evidence it won: ${lib.winner_category}` : "",
+    lib.angle ? `angle: ${lib.angle}` : "",
+    lib.hook_archetype ? `hook: ${lib.hook_archetype}` : "",
+    lib.composition ? `composition: ${lib.composition}` : "",
+    lib.text && lib.text.length > 0 ? `its words: ${lib.text.map((t) => `"${t}"`).join("; ")}` : ""
+  ].filter(Boolean);
+  return [
+    "The image is a winning ad by another advertiser. We want to build an ad for OUR company on its concept: keep why it wins, change everything else to ours.",
+    ...facts.length > 0 ? [`The ads library read it as: ${facts.join(". ")}.`] : [],
+    "",
+    "What OUR company has (its own documents):",
+    input.knowledge.trim() || "(nothing written down yet)",
+    "",
+    "Answer in English:",
+    "why_it_wins, in layers, one short phrase each, empty when a layer does nothing: disguise (what the ad pretends to be: a note, a tweet, a newspaper, a chat, a plain ad), voice (who speaks and how: a peer, a founder, a brand), trigger (the emotion or need it pulls: a free gift, fear of a hidden loss, status, curiosity), attention (what stops the scroll), logic (why it convinces: reciprocity, social proof, a comparison, a price anchor).",
+    "load_bearing: the 1-4 elements the ad stops working without (never decoration), each with: element, needs (what it takes to carry it), have (have: we have it as it is; adapt: we can carry it with something of ours; missing: we have nothing that carries it), ours (what of ours carries it, when we have or can adapt it; never invent an offer, a gift, a price, a review or a customer we do not have).",
+    "verdict: use (it transfers as it is), adapt (it transfers with ours in place of theirs), reject (a load-bearing element is missing: without it our version loses why it wins).",
+    "transfer_note: one sentence on how the idea becomes ours, or why it cannot.",
+    "brand_presence: native when the disguise only works without looking like an ad (the logo as the sender's picture, no big button), else standard.",
+    'recognition: what kind of product a stranger must take OUR version for in one second, never its format ("a trade course", "a social media API for developers", "a payroll app").',
+    "carry: what made it a winner, so what OUR ad takes from it: whole_ad (it wins as one piece: its disguise, layout and hook together; ours keeps all three with our words, brand and pictures), layout (its composition or container does the work: ours keeps that arrangement), hook (its opening line or first visual stops the scroll: ours opens on the same pattern in our words), angle (the argument or need it pulls wins, its look is ordinary: ours keeps the argument and looks like ours). carry_why: one sentence on why that level.",
+    "",
+    'Reply with only this JSON: {"why_it_wins":{"disguise":"","voice":"","trigger":"","attention":"","logic":""},"load_bearing":[{"element":"","needs":"","have":"have|adapt|missing","ours":""}],"verdict":"use|adapt|reject","transfer_note":"","brand_presence":"native|standard","recognition":"","carry":"whole_ad|layout|hook|angle","carry_why":""}'
+  ].join("\n");
+}
+function fitHints(fit, adId, platform = "meta") {
+  const missing = fit.load_bearing.filter((l) => l.have === "missing" && !l.ours?.trim()).map((l) => l.element);
+  if (fit.verdict === "reject" || missing.length > 0) {
+    return [
+      `Pick another reference: this one wins on ${missing.length > 0 ? missing.map((m) => `"${m}"`).join(" and ") : "something we cannot supply"}, and our version would lose why it won.${fit.transfer_note ? ` ${fit.transfer_note}` : ""} Do not stop or ask the person: check the next candidates (\`baker winning-ads fit <adId> --platform ${platform}\`, about three) and scaffold the first that fits.`
+    ];
+  }
+  return [
+    `It fits (${fit.verdict}). Scaffold it: \`baker canvas scaffold-static-ad --source-ad-id ${adId} --source-platform ${platform} --slug <slug>\`: prompt.json's \`concept\` is seeded from this fit, and every render keeps ${fit.load_bearing.map((l) => `"${l.element}"`).join(", ") || "its idea"}.`,
+    ...fit.brand_presence === "native" ? [
+      "The concept is a native disguise: the brand shows as the sender (the logo small, as its picture or signature) and there is no big button; prompt.json says `brand_presence: native`."
+    ] : []
+  ];
+}
+var NO_FIT_HINT = "No fit was made of this reference";
+function conceptFromFit(fit, adId) {
+  return {
+    concept: {
+      reference_ad_id: adId,
+      why_it_wins: fit.why_it_wins,
+      load_bearing: fit.load_bearing,
+      verdict: fit.verdict,
+      ...fit.transfer_note ? { transfer_note: fit.transfer_note } : {},
+      // A fit that names no level (cached before `carry`) is read as the whole ad, and says so.
+      carry: fit.carry ?? "whole_ad",
+      ...fit.carry_why ? { carry_why: fit.carry_why } : {}
+    },
+    ...fit.brand_presence ? { brand_presence: fit.brand_presence } : {},
+    ...fit.recognition ? { recognition: fit.recognition } : {}
+  };
+}
+var MAX_DOC_CHARS = 1500;
+var MAX_ENTRY_CHARS = 400;
+var KNOWLEDGE_COLLECTIONS = ["offers", "products", "personas"];
+function readText(file) {
+  return readFile(file, "utf8").catch(() => null);
+}
+async function readKnowledge(root) {
+  const parts = [];
+  const company = await readText(path.join(root, "COMPANY.md"));
+  if (company) parts.push(`COMPANY.md:
+${company.slice(0, MAX_DOC_CHARS)}`);
+  const brand = await readText(path.join(root, "src", "brand", "BRAND.md"));
+  if (brand) parts.push(`BRAND.md (start):
+${brand.slice(0, MAX_DOC_CHARS)}`);
+  for (const collection of KNOWLEDGE_COLLECTIONS) {
+    const dir = path.join(root, "src", "content", collection);
+    const files = (await readdir(dir, { recursive: true }).catch(() => [])).filter(
+      (f) => f.endsWith(".md")
+    );
+    for (const file of files.sort().slice(0, 12)) {
+      const text = await readText(path.join(dir, file));
+      if (text) parts.push(`${collection}/${file}:
+${text.slice(0, MAX_ENTRY_CHARS)}`);
+    }
+  }
+  return parts.join("\n\n");
+}
+var ReviewSchema = z.object({
+  reviewText: z.string(),
+  sourceType: z.string().optional(),
+  rating: z.number().optional()
+});
+function reviewsForFit(data) {
+  const list = Array.isArray(data) ? data : [];
+  const lines = list.slice(0, 15).flatMap((item) => {
+    const review = ReviewSchema.safeParse(item);
+    if (!review.success || !review.data.reviewText.trim()) return [];
+    const { reviewText, sourceType, rating } = review.data;
+    const label = [sourceType, rating !== void 0 ? `${rating}\u2605` : ""].filter(Boolean).join(" ");
+    return [`- ${label ? `${label} ` : ""}"${reviewText.slice(0, 160)}"`];
+  });
+  return lines.length > 0 ? `Reviews we have (${lines.length}):
+${lines.join("\n")}` : "Reviews we have: none on file.";
+}
+async function readReviews() {
+  try {
+    return reviewsForFit(await apiGet("/api/testimonials", { limit: "15" }));
+  } catch {
+    return "";
+  }
+}
+function fitCachePath(root, platform, adId) {
+  return path.join(root, "canvas", ".cache", "fit", `${platform}-${adId.replace(/[^a-zA-Z0-9_-]/g, "_")}.json`);
+}
+async function readCachedFit(root, platform, adId) {
+  const raw = await readText(fitCachePath(root, platform, adId));
+  if (!raw) return null;
+  try {
+    const parsed = FitAnswerSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+var DESCRIPTION = "Does a winning ad fit this company? One vision call reads the reference beside what the company has (COMPANY.md, the brand's rules, the offers, products and personas in the Knowledge, its reviews) and says why the ad wins (disguise, voice, trigger, attention, logic), the elements it stops working without, whether we have each, and a verdict: use, adapt or reject. Start here before scaffolding a static ad from the library: check about three candidates, scaffold only one that fits. `baker canvas scaffold-static-ad --source-ad-id <adId>` then seeds prompt.json's `concept` from this verdict, and a run refuses a rejected concept. Example: baker winning-ads fit 1310524137919413 --platform meta. Output is compact; --full adds the whole read.";
+var ARGS = {
+  "ad-id": { type: "positional", required: true, description: "The library ad id (from search/winners/feed)." },
+  platform: {
+    type: "string",
+    required: false,
+    description: `Which platform the ad id is on: ${LIBRARY_PLATFORMS.join("|")} (default meta). The fit reads a still picture: a static ad (on google, a display ad). A video ad, YouTube included, is read with \`content\`; a Google search, Shopping or app ad is refused.`
+  },
+  full: {
+    type: "boolean",
+    required: false,
+    default: false,
+    description: "Add the whole read: every layer, need and note."
+  }
+};
+registerSchema({ command: "winning-ads.fit", description: DESCRIPTION, args: ARGS });
+async function pictureOf(url) {
+  if (!url) return null;
+  try {
+    const bytes = await bytesOf(url);
+    return (await sharp(bytes).resize(1024, 1024, { fit: "inside" }).jpeg({ quality: 85 }).toBuffer()).toString(
+      "base64"
+    );
+  } catch {
+    return null;
+  }
+}
+function libraryRead(ad) {
+  return {
+    ...ad.advertiser ? { advertiser: ad.advertiser } : {},
+    ...ad.layout.format_pattern ? { format_pattern: ad.layout.format_pattern } : {},
+    ...ad.message.mechanism ? { mechanism: ad.message.mechanism } : {},
+    ...ad.message.awareness_stage ? { awareness: ad.message.awareness_stage } : {},
+    ...ad.offer.offer_type ? { offer: ad.offer.offer_type } : {},
+    ...ad.winner_category ? { winner_category: ad.winner_category } : {},
+    ...ad.angle ? { angle: ad.angle } : {},
+    ...ad.hook_archetype ? { hook_archetype: ad.hook_archetype } : {},
+    ...ad.layout.composition ? { composition: ad.layout.composition } : {},
+    text: ad.on_screen_text.flatMap((o) => o.text ? [o.text] : []).slice(0, 10)
+  };
+}
+async function fitOnce(root, platform, adId, ask) {
+  const cached = await readCachedFit(root, platform, adId);
+  if (cached) return cached;
+  const fit = await ask();
+  if (!fit) return null;
+  const file = fitCachePath(root, platform, adId);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(fit, null, 2)}
+`, "utf8");
+  return fit;
+}
+async function askFit(jpeg, prompt, onSpend) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const parsed = FitAnswerSchema.safeParse(await askAboutImages(AD_DESCRIBE_MODEL, [jpeg], prompt, onSpend));
+    if (parsed.success) return parsed.data;
+  }
+  return null;
+}
+async function fitReference(root, platform, adId) {
+  let failure = null;
+  const fit = await fitOnce(root, platform, adId, async () => {
+    let ad;
+    try {
+      ad = await fetchLibraryReference(adId, platform);
+    } catch (e) {
+      failure = {
+        code: "NOT_FOUND",
+        message: `The library could not return ad ${adId} on ${platform} (${e instanceof Error ? e.message : String(e)}).`,
+        fix: "Check the ad id and --platform against `baker winning-ads search`."
+      };
+      return null;
+    }
+    const refusal = notADesignReference(platform, adId, ad);
+    if (refusal) {
+      failure = refusal;
+      return null;
+    }
+    if (ad.format === "video") {
+      failure = {
+        code: "VIDEO_REFERENCE",
+        message: `Ad ${adId} is a video: the fit reads still pictures.`,
+        fix: `Read it with \`baker winning-ads content ${adId} --platform ${platform}\` (transcript, on-screen text, pacing) and build the video with \`baker canvas scaffold-ad\`. For a static, pick a static ad.`
+      };
+      return null;
+    }
+    const jpeg = await pictureOf(ad.media_url);
+    if (!jpeg) {
+      failure = {
+        code: "NOT_FOUND",
+        message: `Ad ${adId} has no picture the fit can read.`,
+        fix: "Pick a static ad with a picture."
+      };
+      return null;
+    }
+    const knowledge = [await readKnowledge(root), await readReviews()].filter(Boolean).join("\n\n");
+    const prompt = buildFitPrompt({ library: libraryRead(ad), knowledge });
+    const spent = [];
+    const answer = await askFit(jpeg, prompt, (u) => spent.push(u));
+    await holdUnbilledSpend(path.join(root, "canvas", ".cache"), spent);
+    return answer;
+  });
+  if (fit) return { ok: true, fit };
+  return {
+    ok: false,
+    error: failure ?? {
+      code: "UNAVAILABLE",
+      message: "The fit model did not answer (no gateway key here, or it failed twice).",
+      fix: "Run it again, or read the reference yourself with `baker winning-ads content <adId> --full` and write prompt.json's `concept` by hand."
+    }
+  };
+}
+var fitCommand = defineCommand({
+  meta: { name: "fit", description: DESCRIPTION },
+  args: ARGS,
+  async run({ args }) {
+    const adId = String(args["ad-id"]);
+    const platformResult = resolveSourcePlatform(args.platform ? String(args.platform) : void 0);
+    if (!platformResult.ok) {
+      writeJson({ ok: false, error: { code: "INVALID_ARGUMENT", message: platformResult.message } });
+      process.exit(1);
+    }
+    const platform = platformResult.platform;
+    const root = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    const result = await fitReference(root, platform, adId);
+    if (!result.ok) {
+      writeJson({ ok: false, error: result.error });
+      process.exit(1);
+    }
+    const fit = result.fit;
+    const why = [fit.why_it_wins.disguise, fit.why_it_wins.trigger, fit.why_it_wins.logic].filter(Boolean).join("; ");
+    writeJson({
+      ok: true,
+      data: {
+        ad_id: adId,
+        verdict: fit.verdict,
+        why_it_wins: why,
+        load_bearing: fit.load_bearing.map((l) => ({
+          element: l.element,
+          have: l.have,
+          ...l.ours ? { ours: l.ours } : {}
+        })),
+        ...fit.brand_presence ? { brand_presence: fit.brand_presence } : {},
+        ...fit.carry ? { carry: fit.carry } : {},
+        ...args.full ? { read: fit } : {}
+      },
+      hints: fitHints(fit, adId, platform)
+    });
+  }
+});
+
+export {
+  LIBRARY_PLATFORMS,
+  resolveSourcePlatform,
+  notADesignReference,
+  fetchLibraryReference,
+  libraryReferenceBlock,
+  referenceDescribeContext,
+  mergeReferenceIntoBlueprint,
+  FitAnswerSchema,
+  buildFitPrompt,
+  fitHints,
+  NO_FIT_HINT,
+  conceptFromFit,
+  readKnowledge,
+  reviewsForFit,
+  fitCachePath,
+  readCachedFit,
+  fitOnce,
+  fitReference,
+  fitCommand
+};
+//# sourceMappingURL=chunk-PBHQPJZG.js.map