@koda-sl/baker-cli 0.562.0 → 0.563.0-dev.25ca3cbc8

package/dist/chunk-BRSEAVWZ.js

@@ -0,0 +1,163 @@
+import {
+  failApi
+} from "./chunk-HC6464KT.js";
+import {
+  CREATIVE_PERFORMANCE_DEFAULT_DAYS,
+  CREATIVE_PERFORMANCE_MAX_DAYS
+} from "./chunk-OVNVYNVH.js";
+import {
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-CCYZJMZ7.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-BRSEAVWZ.js.map

package/dist/chunk-DWA42GNM.js

@@ -0,0 +1,131 @@
+import {
+  holdUnbilledSpend
+} from "./chunk-Y5PNLB24.js";
+import {
+  askAboutText
+} from "./chunk-IZMSISEN.js";
+
+// src/engine/brand/brand-doc.ts
+import { createHash } from "crypto";
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { z } from "zod";
+var BRAND_DOC_MODEL = "google/gemini-3.5-flash-lite";
+var REQUEST = {
+  provider: { order: ["google-vertex"], allow_fallbacks: false },
+  seed: 0,
+  response_format: { type: "json_object" }
+};
+var PROMPT_VERSION = 3;
+var TIMEOUT_MS = 3e4;
+var BRAND_MD_CHARS = 32e3;
+var NOTE_CHARS = 600;
+var COMPANY_MD_CHARS = 4e3;
+var Font = z.object({
+  family: z.string().trim().min(1).max(60),
+  role: z.enum(["heading", "body", "any"]).catch("any"),
+  use: z.boolean()
+});
+var Color = z.object({
+  hex: z.string().trim().regex(/^#?[0-9a-fA-F]{6}$/).transform((h) => `#${h.replace(/^#/, "").toLowerCase()}`),
+  use: z.boolean()
+});
+var note = z.string().trim().min(1).max(NOTE_CHARS).nullable().optional().catch(null);
+var Reading = z.object({
+  name: z.string().trim().min(1).max(80).nullable().catch(null),
+  wordmark: z.array(z.string().trim().min(1).max(40)).catch([]),
+  logoNames: z.array(z.string().trim().min(1).max(40)).catch([]),
+  fonts: z.array(z.unknown()).catch([]),
+  colors: z.array(z.unknown()).catch([]),
+  voice: note,
+  imagery: note,
+  logoUsage: note
+});
+function brandDocPrompt(docs) {
+  return [
+    "You read a company's brand guidelines (BRAND.md), the start of its company profile (COMPANY.md) and the file names of its logos. They may be written in any language, or several. Extract only what they state; never invent a value.",
+    "",
+    "Return JSON only, in this shape:",
+    '{"name": string | null, "wordmark": string[], "logoNames": string[], "fonts": [{"family": string, "role": "heading" | "body" | "any", "use": boolean}], "colors": [{"hex": "#rrggbb", "use": boolean}], "voice": string | null, "imagery": string | null, "logoUsage": string | null}',
+    "",
+    `- name: the brand's name exactly as written ("# Zernio Brand Guidelines" names Zernio). null when neither document states one, as in an unfilled template ("# Brand Guidelines", "# Company", TODO).`,
+    `- wordmark: every word the documents say the logo prints, as they quote it ("Wordmark: \\"permut\\"" gives "permut"; 'symbol plus "Cubbo" wordmark' gives "Cubbo"), even when it is also the name. [] when they quote none.`,
+    '- logoNames: a product or brand name a logo file name carries ("logo-engage-blue.png" gives "Engage"). Colours, variants, sizes and formats (dark, white, icon, isotype, png) are not names. [] when none.',
+    `- fonts: every typeface the guidelines name, by its family name exactly, the banned ones included. role is heading, body, or any when they do not say. use is false when the guidelines ban it, forbid it or say to avoid it or never use it, in any wording or language; true when the brand uses it. Only a named typeface counts: a generic family (sans-serif, serif, monospace, system-ui) or the operating system's own fonts ("system stack", "system fonts") is not one, so leave it out.`,
+    "- colors: every hex colour the guidelines give. use is false when they ban it or say to avoid it, true when it is a brand colour.",
+    "- voice: how the brand speaks, as the guidelines put it, at most two sentences in their language. null when they do not say.",
+    "- imagery: what the brand's pictures look like and never look like (photography, illustration, people; a ```generation-style block says it too), at most two sentences in their language. null when they do not say.",
+    "- logoUsage: which logo file an ad uses and how it must appear (which file for which product, line or background, what never to do to it), at most two sentences in their language. null when they do not say.",
+    "",
+    "<brand_md>",
+    (docs.brandMd ?? "").slice(0, BRAND_MD_CHARS),
+    "</brand_md>",
+    "<company_md>",
+    (docs.companyMd ?? "").slice(0, COMPANY_MD_CHARS),
+    "</company_md>",
+    "<logo_files>",
+    (docs.logoFiles ?? []).join("\n"),
+    "</logo_files>"
+  ].join("\n");
+}
+function parseBrandDoc(answer) {
+  const parsed = Reading.safeParse(answer);
+  if (!parsed.success) return null;
+  const fonts = parsed.data.fonts.flatMap((f) => {
+    const font = Font.safeParse(f);
+    return font.success ? [font.data] : [];
+  });
+  const colors = parsed.data.colors.flatMap((c) => {
+    const color = Color.safeParse(c);
+    return color.success ? [color.data] : [];
+  });
+  const { voice, imagery, logoUsage } = parsed.data;
+  return {
+    ...parsed.data.name ? { name: parsed.data.name } : {},
+    wordmark: [.../* @__PURE__ */ new Set([...parsed.data.wordmark, ...parsed.data.logoNames])],
+    fonts,
+    colors,
+    ...voice ? { voice } : {},
+    ...imagery ? { imagery } : {},
+    ...logoUsage ? { logoUsage } : {}
+  };
+}
+function brandDocReader(cacheDir, onSpend) {
+  return async (docs) => {
+    const prompt = brandDocPrompt(docs);
+    const key = createHash("sha256").update(JSON.stringify([PROMPT_VERSION, BRAND_DOC_MODEL, prompt])).digest("hex");
+    const file = path.join(cacheDir, "brand-doc", `${key}.json`);
+    const cached = parseBrandDoc(await readFile(file, "utf8").then(JSON.parse, () => null));
+    if (cached) return cached;
+    const spent = [];
+    const answer = await askAboutText(BRAND_DOC_MODEL, prompt, (u) => onSpend ? onSpend(u) : spent.push(u), {
+      timeoutMs: TIMEOUT_MS,
+      request: REQUEST
+    }).catch(() => null);
+    await holdUnbilledSpend(cacheDir, spent).catch(() => void 0);
+    const reading = parseBrandDoc(answer);
+    if (reading) {
+      await mkdir(path.dirname(file), { recursive: true }).catch(() => void 0);
+      await writeFile(file, JSON.stringify(reading), "utf8").catch(() => void 0);
+    }
+    return reading;
+  };
+}
+var LOGO_FILE = /logo|lockup|wordmark|isotype|isologo/i;
+async function workspaceBrandDocs(root) {
+  const read = (rel) => readFile(path.join(root, rel), "utf8").catch(() => null);
+  const logoFiles = (await readdir(path.join(root, "src", "brand", "logos")).catch(() => [])).filter((f) => /\.(png|jpe?g|webp|svg)$/i.test(f) && LOGO_FILE.test(f)).sort();
+  return { brandMd: await read("src/brand/BRAND.md"), companyMd: await read("COMPANY.md"), logoFiles };
+}
+async function readWorkspaceBrandDoc(root, opts = {}) {
+  const docs = await workspaceBrandDocs(root);
+  if (!docs.brandMd?.trim() && !docs.companyMd?.trim()) return null;
+  const read = opts.read ?? brandDocReader(path.join(root, "canvas", ".cache"), opts.onSpend);
+  return await read(docs).catch(() => null);
+}
+
+export {
+  LOGO_FILE,
+  readWorkspaceBrandDoc
+};
+//# sourceMappingURL=chunk-DWA42GNM.js.map