@koda-sl/baker-cli 0.510.0 → 0.511.0-dev.2d26314a2

package/dist/chunk-Y3EIDK4C.js

@@ -0,0 +1,163 @@
+import {
+  failApi
+} from "./chunk-STNKHWDE.js";
+import {
+  CREATIVE_PERFORMANCE_DEFAULT_DAYS,
+  CREATIVE_PERFORMANCE_MAX_DAYS
+} from "./chunk-4CNR3MNJ.js";
+import {
+  apiPost
+} from "./chunk-X7VQFLHI.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-Q7US4OOA.js";
+
+// src/commands/creatives/performance.ts
+import { readFileSync } from "fs";
+import path from "path";
+import { defineCommand } from "citty";
+import { parse as parseYaml } from "yaml";
+var DESCRIPTION = `How each Baker creative is doing in the live Meta ads that show it: spend, impressions, CTR, CPC, results, cost per result, frequency and a fatigue verdict, next to the angle, hook, mechanism and dominant slot its definition set out to test. Video creatives add hookRate (percent of impressions that watched 3 seconds) and holdRate (percent of those that reached a ThruPlay). Use it before briefing new creatives, to learn which angle and mechanism to make next and which creatives to replace.
+
+Start here:
+  baker creatives performance                      # every creative in an ad, last 30 days
+  baker creatives performance --slug spring-offer  # one creative
+  baker creatives performance --days 14 --full     # ids, last-7-day figures, a video's watch funnel, one row per ad
+
+Fatigue follows the Meta playbook (07-creative-audit.md): fresh, fading, fatigued, dead, or too_early (under 14 days or 1,000 impressions) and no_delivery. A low hook rate means the first 3 seconds need new hooks; a working hook with a low hold rate means the body loses people. A creative counts once a Session's publish created an ad with it.`;
+var ARGS = {
+  slug: { type: "string", description: "Only this creative (src/creatives/<slug>/)", required: false },
+  days: {
+    type: "string",
+    description: `Reporting window in days, ending today (1-${CREATIVE_PERFORMANCE_MAX_DAYS}, default ${CREATIVE_PERFORMANCE_DEFAULT_DAYS})`,
+    required: false
+  },
+  full: {
+    type: "boolean",
+    description: "Add ids, last-7-day CTR and cost per result, and one row per ad",
+    required: false,
+    default: false
+  }
+};
+registerSchema({ command: "creatives.performance", description: DESCRIPTION, args: ARGS });
+var INSIGHT_KEYS = [
+  "idea",
+  "message",
+  "evidence",
+  "angle",
+  "hook",
+  "mechanism",
+  "dominantSlot",
+  "persona",
+  "awareness",
+  "hypothesis"
+];
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+function insightValue(value) {
+  if (typeof value === "string") return value.trim() || null;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return null;
+}
+function definitionInsights(markdown) {
+  const block = FRONTMATTER.exec(markdown)?.[1];
+  if (!block) return null;
+  let parsed;
+  try {
+    parsed = parseYaml(block);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const insights = {};
+  for (const [key, raw] of Object.entries(parsed)) {
+    if (!(INSIGHT_KEYS.includes(key) || key.startsWith("source") || key.startsWith("reference"))) continue;
+    const value = insightValue(raw);
+    if (value !== null) insights[key] = value;
+  }
+  return Object.keys(insights).length > 0 ? insights : null;
+}
+function readLocalDefinition(slug) {
+  try {
+    return readFileSync(path.join(process.cwd(), "src", "creatives", slug, "_definition.md"), "utf8");
+  } catch {
+    return null;
+  }
+}
+var COMPARED_FIELDS = [
+  { key: "angle", label: "angle", advice: "Brief the next creative on the cheapest angle with a new hook." },
+  { key: "mechanism", label: "mechanism", advice: "Brief the next creative on the cheapest mechanism." },
+  { key: "dominantSlot", label: "dominant slot", advice: "Lead the next creative with the cheapest dominant slot." }
+];
+function cheapestHint(creatives, { key, label, advice }) {
+  const byValue = /* @__PURE__ */ new Map();
+  for (const creative of creatives) {
+    const value = creative.definition?.[key];
+    if (!value || creative.costPerResult === null) continue;
+    const best = byValue.get(value);
+    if (!best || (best.costPerResult ?? Number.POSITIVE_INFINITY) > creative.costPerResult)
+      byValue.set(value, creative);
+  }
+  if (byValue.size < 2) return null;
+  const ranked = [...byValue.entries()].sort(([, a], [, b]) => (a.costPerResult ?? 0) - (b.costPerResult ?? 0)).map(
+    ([value, creative]) => `"${value}" ${creative.costPerResult}${creative.currency ? ` ${creative.currency}` : ""} (${creative.slug ?? creative.title})`
+  );
+  return `Cost per result by ${label}: ${ranked.join(", ")}. ${advice}`;
+}
+function withDefinitions(response, readDefinition) {
+  const creatives = response.data.creatives.map((creative) => {
+    const markdown = creative.slug ? readDefinition(creative.slug) : null;
+    const definition = markdown ? definitionInsights(markdown) : null;
+    return definition ? { ...creative, definition } : creative;
+  });
+  const hints = [...response.hints ?? []];
+  for (const field of COMPARED_FIELDS) {
+    const hint = cheapestHint(creatives, field);
+    if (hint) hints.push(hint);
+  }
+  const unnamed = creatives.filter((creative) => !creative.definition?.angle).map((c) => c.slug ?? c.title);
+  if (unnamed.length > 0) {
+    hints.push(
+      `No angle recorded for: ${unnamed.join(", ")}. Add angle and hook to src/creatives/<slug>/_definition.md so results show which angle works.`
+    );
+  }
+  return { ...response, data: { ...response.data, creatives }, ...hints.length > 0 ? { hints } : {} };
+}
+function syncedCreativesHint(slug) {
+  return `Live Meta read. Across every platform, from the synced copy (no rate limit, full history): baker ads performance creatives ranks them against their ad-group peers (madeInBaker names this creative), and baker ads performance live-in --creative ${slug ?? "<slug>"} lists the live campaigns showing it.`;
+}
+function parseDays(raw) {
+  if (raw === void 0) return void 0;
+  const days = Number(raw);
+  if (!Number.isInteger(days) || days < 1 || days > CREATIVE_PERFORMANCE_MAX_DAYS) {
+    throw new Error(`--days must be a whole number from 1 to ${CREATIVE_PERFORMANCE_MAX_DAYS}`);
+  }
+  return days;
+}
+var performanceCommand = defineCommand({
+  meta: { name: "performance", description: DESCRIPTION },
+  args: ARGS,
+  run: async ({ args }) => {
+    try {
+      const body = {};
+      const slug = args.slug;
+      if (slug) body.slug = slug;
+      const days = parseDays(args.days);
+      if (days !== void 0) body.days = days;
+      if (args.full) body.full = true;
+      const response = await apiPost("/api/creatives/performance", body);
+      const out = withDefinitions(response, readLocalDefinition);
+      writeJson({ ...out, hints: [...out.hints ?? [], syncedCreativesHint(slug)] });
+    } catch (err) {
+      failApi(err);
+    }
+  }
+});
+
+export {
+  definitionInsights,
+  withDefinitions,
+  parseDays,
+  performanceCommand
+};
+//# sourceMappingURL=chunk-Y3EIDK4C.js.map

package/dist/chunk-YUIIO5VF.js

@@ -0,0 +1,142 @@
+import {
+  avatarsOf
+} from "./chunk-Z2PKXY3H.js";
+import {
+  readAvatars
+} from "./chunk-WHBFXR6F.js";
+import {
+  readCreativeContext,
+  workspaceOfCreative
+} from "./chunk-Z2NSX6Y5.js";
+import {
+  frontmatterOf,
+  ruleTells
+} from "./chunk-MKUA54QE.js";
+import {
+  findWorkspaceRoot
+} from "./chunk-EJGAJHLB.js";
+import {
+  isAdSpec,
+  nativeCopy,
+  readAdSpec
+} from "./chunk-QHZE62GP.js";
+import {
+  marketFromCompanyDoc
+} from "./chunk-2WZI36D3.js";
+
+// src/engine/creative-context/ad-words.ts
+import { readdir, readFile } from "fs/promises";
+import path from "path";
+var json = (file) => readFile(file, "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+var text = (value) => typeof value === "string" && value.trim() ? value.trim() : void 0;
+function waivedOf(spec) {
+  const waive = spec?.waive;
+  return Array.isArray(waive) ? waive.flatMap((w) => text(w?.rule) ?? []) : [];
+}
+function sceneWords(scene) {
+  const s = scene ?? {};
+  const spoken = Array.isArray(s.dialogue) ? s.dialogue.flatMap((d) => text(d?.line) ?? []) : [];
+  const shown = Array.isArray(s.overlays) ? s.overlays.flatMap((o) => text(o?.text) ?? []) : [];
+  return [...spoken, ...shown];
+}
+async function sceneFiles(creativeDir) {
+  const dir = path.join(creativeDir, "scenes");
+  const files = (await readdir(dir).catch(() => [])).filter((f) => f.endsWith(".json")).sort();
+  return await Promise.all(files.map((f) => json(path.join(dir, f))));
+}
+async function videoLanguage(creativeDir) {
+  const definition = frontmatterOf(await readFile(path.join(creativeDir, "_definition.md"), "utf8").catch(() => ""));
+  const beats = await json(path.join(creativeDir, "ad.spec.json"));
+  return text(definition?.language) ?? text(beats?.voice?.language);
+}
+async function videoWords(raw, creativeDir) {
+  const global = raw.global ?? {};
+  const transcript = text(global.transcript);
+  const scenes = [...Array.isArray(raw.scenes) ? raw.scenes : [], ...await sceneFiles(creativeDir)];
+  const lines = [.../* @__PURE__ */ new Set([...transcript ? [transcript] : [], ...scenes.flatMap(sceneWords)])];
+  const language = await videoLanguage(creativeDir);
+  return { kind: "video", lines, ...language ? { language } : {} };
+}
+function staticWords(raw) {
+  try {
+    const spec = readAdSpec(raw);
+    const lines = spec.native ? nativeCopy(spec.native) : spec.copy.map((l) => l.text);
+    const language = spec.viewer?.market?.language;
+    return { kind: "static", lines, ...language ? { language } : {} };
+  } catch {
+    return null;
+  }
+}
+async function readAdWords(creativeDir) {
+  const raw = await json(path.join(creativeDir, "prompt.json"));
+  if (!raw || typeof raw !== "object") return null;
+  const video = !isAdSpec(raw) && ("global" in raw || "scenes" in raw);
+  const words = video ? await videoWords(raw, creativeDir) : staticWords(raw);
+  if (!words) return null;
+  const product = text(raw.product);
+  const definition = frontmatterOf(await readFile(path.join(creativeDir, "_definition.md"), "utf8").catch(() => ""));
+  const platform = text(definition?.platform);
+  const listed = definition?.platforms;
+  const platforms = Array.isArray(listed) ? listed.map(text).filter((p) => p !== void 0) : [];
+  return {
+    ...words,
+    ...product ? { product } : {},
+    ...platform ? { platform } : {},
+    ...platforms.length > 0 ? { platforms } : {},
+    waived: waivedOf(raw)
+  };
+}
+
+// src/commands/canvas/rule-gate.ts
+import { readFile as readFile2 } from "fs/promises";
+import path2 from "path";
+function tellLine(tell) {
+  const where = tell.kind === "forbidden" ? `"${tell.line ?? ""}" says "${tell.phrase}"` : `No line says "${tell.phrase}"`;
+  const words = tell.quote ? ` Their words: ${tell.quote}` : "";
+  return `${where}: ${tell.rule} (${tell.strength}) \u2014 ${tell.text}${words}`;
+}
+function ruleRefusal(tells) {
+  if (tells.length === 0) return null;
+  return {
+    problems: [...new Set(tells.map(tellLine))],
+    fix: 'Rewrite each line named above within its rule (a static: its `copy` in prompt.json; a video: its scene files and ad.spec.json), then re-run. Only when the person explicitly asked for these words in this ad, keep them and add to prompt.json `"waive": [{"rule": "<id>", "why": "<their ask>"}]`.'
+  };
+}
+var liveRoster = () => readAvatars("/api/avatars", { status: "ready" }).then(avatarsOf, () => null);
+async function heldRules(creativeDir, ad) {
+  const words = ad === void 0 ? await readAdWords(creativeDir) : ad;
+  const root = findWorkspaceRoot(creativeDir) ?? workspaceOfCreative(creativeDir);
+  const context = await readCreativeContext(
+    root,
+    {
+      ...words ? { kind: words.kind } : {},
+      ...words?.product ? { product: words.product } : {},
+      ...words?.platform ? { platform: words.platform } : {},
+      ...words?.platforms ? { platforms: words.platforms } : {}
+    },
+    { waived: words?.waived ?? [] }
+  );
+  const language = words?.language ?? marketFromCompanyDoc(await readFile2(path2.join(root, "COMPANY.md"), "utf8").catch(() => null))?.language;
+  return { rules: context.rules, ...language ? { language } : {} };
+}
+async function ruleGate(creativeDir, roster = liveRoster) {
+  const ad = await readAdWords(creativeDir);
+  if (!ad) return { broken: null, realOnly: null };
+  const { rules, language } = await heldRules(creativeDir, ad);
+  const people = rules.find((r) => r.check?.people === "real" && r.strength !== "prefer");
+  return {
+    broken: ruleRefusal(ruleTells(ad.lines, rules, language)),
+    realOnly: people ? {
+      rule: { id: people.id, text: people.text, ...people.source.quote ? { quote: people.source.quote } : {} },
+      avatars: await roster().catch(() => null)
+    } : null
+  };
+}
+
+export {
+  readAdWords,
+  ruleRefusal,
+  heldRules,
+  ruleGate
+};
+//# sourceMappingURL=chunk-YUIIO5VF.js.map

package/dist/chunk-YZBB72TV.js

@@ -0,0 +1,150 @@
+import {
+  GEO_TARGET_COUNTRIES,
+  LANGUAGE_CONSTANTS
+} from "./chunk-HNNCAJNF.js";
+
+// src/geo-context.ts
+function toOptions(names) {
+  return Object.entries(names).map(([id, name]) => ({ id, name })).sort((a, b) => a.name.localeCompare(b.name));
+}
+var GOOGLE_ADS_LOCATIONS = toOptions(GEO_TARGET_COUNTRIES);
+var GOOGLE_ADS_LANGUAGES = toOptions(LANGUAGE_CONSTANTS);
+var DATAFORSEO_LOCATIONS = [
+  { code: "us", name: "United States" },
+  { code: "uk", name: "United Kingdom" },
+  { code: "gb", name: "United Kingdom" },
+  { code: "ca", name: "Canada" },
+  { code: "au", name: "Australia" },
+  { code: "de", name: "Germany" },
+  { code: "fr", name: "France" },
+  { code: "es", name: "Spain" },
+  { code: "it", name: "Italy" },
+  { code: "br", name: "Brazil" },
+  { code: "mx", name: "Mexico" },
+  { code: "nl", name: "Netherlands" },
+  { code: "be", name: "Belgium" },
+  { code: "at", name: "Austria" },
+  { code: "ch", name: "Switzerland" },
+  { code: "pt", name: "Portugal" },
+  { code: "se", name: "Sweden" },
+  { code: "no", name: "Norway" },
+  { code: "dk", name: "Denmark" },
+  { code: "fi", name: "Finland" },
+  { code: "ie", name: "Ireland" },
+  { code: "nz", name: "New Zealand" },
+  { code: "in", name: "India" },
+  { code: "jp", name: "Japan" },
+  { code: "kr", name: "South Korea" },
+  { code: "sg", name: "Singapore" },
+  { code: "ar", name: "Argentina" },
+  { code: "cl", name: "Chile" },
+  { code: "co", name: "Colombia" },
+  { code: "pe", name: "Peru" },
+  { code: "pl", name: "Poland" },
+  { code: "cz", name: "Czech Republic" },
+  { code: "ro", name: "Romania" },
+  { code: "hu", name: "Hungary" },
+  { code: "za", name: "South Africa" },
+  { code: "il", name: "Israel" },
+  { code: "ae", name: "United Arab Emirates" },
+  { code: "sa", name: "Saudi Arabia" },
+  { code: "tr", name: "Turkey" },
+  { code: "ph", name: "Philippines" },
+  { code: "th", name: "Thailand" },
+  { code: "my", name: "Malaysia" },
+  { code: "id", name: "Indonesia" },
+  { code: "vn", name: "Vietnam" },
+  { code: "tw", name: "Taiwan" },
+  { code: "hk", name: "Hong Kong" }
+];
+var DATAFORSEO_LANGUAGES = [
+  { code: "en", name: "English" },
+  { code: "es", name: "Spanish" },
+  { code: "fr", name: "French" },
+  { code: "de", name: "German" },
+  { code: "it", name: "Italian" },
+  { code: "pt", name: "Portuguese" },
+  { code: "nl", name: "Dutch" },
+  { code: "ja", name: "Japanese" },
+  { code: "ko", name: "Korean" },
+  { code: "zh", name: "Chinese" },
+  { code: "ar", name: "Arabic" },
+  { code: "ru", name: "Russian" },
+  { code: "pl", name: "Polish" },
+  { code: "tr", name: "Turkish" },
+  { code: "sv", name: "Swedish" },
+  { code: "no", name: "Norwegian" },
+  { code: "da", name: "Danish" },
+  { code: "fi", name: "Finnish" }
+];
+function toRecord(list) {
+  const map = {};
+  for (const item of list) {
+    const key = item.id ?? item.code;
+    if (key) map[key] = item.name;
+  }
+  return map;
+}
+var researchLocationMap = toRecord(DATAFORSEO_LOCATIONS);
+var researchLanguageMap = toRecord(DATAFORSEO_LANGUAGES);
+function buildAdsQueryContext(locationArg, languageArg) {
+  const locationId = locationArg ?? "2840";
+  const languageId = languageArg ?? "1000";
+  const locationIsDefault = !locationArg;
+  const languageIsDefault = !languageArg;
+  const locationName = GEO_TARGET_COUNTRIES[locationId] ?? `ID ${locationId}`;
+  const languageName = LANGUAGE_CONSTANTS[languageId] ?? `ID ${languageId}`;
+  const ctx = {
+    location: `${locationName} (${locationId})`,
+    language: `${languageName} (${languageId})`,
+    location_is_default: locationIsDefault,
+    language_is_default: languageIsDefault
+  };
+  if (locationIsDefault || languageIsDefault) {
+    const parts = [];
+    if (locationIsDefault) parts.push("--location");
+    if (languageIsDefault) parts.push("--language");
+    ctx.defaults_warning = `Location and/or language were not specified \u2014 using defaults. Results are for ${locationName} in ${languageName}. Pass ${parts.join(" and ")} to target a different market.`;
+  }
+  return ctx;
+}
+function buildResearchQueryContext(locationArg, languageArg, options) {
+  const skipLocation = options?.skipLocation ?? false;
+  const locationCode = locationArg ?? "us";
+  const languageCode = languageArg ?? "en";
+  const locationIsDefault = !locationArg && !skipLocation;
+  const languageIsDefault = !languageArg;
+  const locationName = researchLocationMap[locationCode.toLowerCase()] ?? `code ${locationCode}`;
+  const languageName = researchLanguageMap[languageCode.toLowerCase()] ?? `code ${languageCode}`;
+  const ctx = {
+    location: skipLocation ? "N/A" : `${locationName} (${locationCode})`,
+    language: `${languageName} (${languageCode})`,
+    location_is_default: locationIsDefault,
+    language_is_default: languageIsDefault
+  };
+  const defaultParts = [];
+  if (locationIsDefault) defaultParts.push("--location");
+  if (languageIsDefault) defaultParts.push("--language");
+  if (defaultParts.length > 0) {
+    const market = skipLocation ? `${languageName}` : `${locationName} in ${languageName}`;
+    ctx.defaults_warning = `Location and/or language were not specified \u2014 using defaults. Results are for ${market}. Pass ${defaultParts.join(" and ")} to target a different market.`;
+  }
+  return ctx;
+}
+function warnDefaults(ctx) {
+  if (ctx.defaults_warning) {
+    process.stderr.write(`
+[WARNING] ${ctx.defaults_warning}
+
+`);
+  }
+}
+
+export {
+  GOOGLE_ADS_LOCATIONS,
+  GOOGLE_ADS_LANGUAGES,
+  buildAdsQueryContext,
+  buildResearchQueryContext,
+  warnDefaults
+};
+//# sourceMappingURL=chunk-YZBB72TV.js.map