@koda-sl/baker-cli 0.534.0 → 0.536.0

package/dist/learn-23DQ72LC.js

@@ -0,0 +1,207 @@
+import {
+  parseDays,
+  withDefinitions
+} from "./chunk-H4T5EMYZ.js";
+import {
+  setDefinitionFields
+} from "./chunk-EDIDGJ6Y.js";
+import {
+  IDEAS_DIR,
+  readIdeas
+} from "./chunk-LLJW5F2C.js";
+import "./chunk-YQIURUEL.js";
+import "./chunk-JE3RHIQE.js";
+import "./chunk-RJ675DP3.js";
+import {
+  findWorkspaceRoot
+} from "./chunk-V6F2QWUZ.js";
+import "./chunk-7BJZF77Q.js";
+import "./chunk-MCJ5I5LR.js";
+import "./chunk-AIOKWGMO.js";
+import "./chunk-EJWTQDKA.js";
+import "./chunk-7UTWZGIV.js";
+import "./chunk-6LU64W5J.js";
+import {
+  failApi
+} from "./chunk-5XRUOJOO.js";
+import "./chunk-3LH5ANM4.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-NSBNIPIW.js";
+import "./chunk-TI4UL56R.js";
+import {
+  apiPost
+} from "./chunk-X6AHLUC7.js";
+import "./chunk-TM5UTSE4.js";
+import "./chunk-6THXOWAP.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-S6WPMD3V.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/creatives/learn.ts
+import { readFileSync } from "fs";
+import { readFile, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+
+// src/commands/creatives/learn-model.ts
+var MIN_IMPRESSIONS = 1e3;
+var SEEN_ENOUGH = 5e3;
+var WINNER_RATIO = 0.8;
+var WINNER_MIN_RESULTS = 3;
+var FAILED_RATIO = 1.5;
+var SILENT_SPEND = 2;
+var SETTLED = /* @__PURE__ */ new Set(["winner", "failed", "inconclusive"]);
+var round = (n) => Math.round(n * 100) / 100;
+function totals(creatives) {
+  const spend = creatives.reduce((sum, c) => sum + c.spend, 0);
+  const impressions = creatives.reduce((sum, c) => sum + c.impressions, 0);
+  const results = creatives.reduce((sum, c) => sum + (c.results ?? 0), 0);
+  const clicks = creatives.reduce((sum, c) => sum + (c.ctr ?? 0) * c.impressions, 0);
+  return { spend, impressions, results, ctr: impressions > 0 ? round(clicks / impressions) : null };
+}
+function verdict(result, usual) {
+  if (result.impressions < MIN_IMPRESSIONS) return "testing";
+  if (usual !== null) {
+    if (result.results === 0 && result.spend >= SILENT_SPEND * usual) return "failed";
+    const ratio = result.vsAccount;
+    if (ratio !== null && result.results >= WINNER_MIN_RESULTS && ratio <= WINNER_RATIO) return "winner";
+    if (ratio !== null && ratio >= FAILED_RATIO) return "failed";
+  }
+  return result.impressions >= SEEN_ENOUGH ? "inconclusive" : "testing";
+}
+function ideaResult(own, usual, asOf) {
+  const mine = totals(own);
+  const costPerResult = mine.results > 0 ? round(mine.spend / mine.results) : null;
+  return {
+    asOf,
+    creatives: own.length,
+    ...own[0]?.currency ? { currency: own[0].currency } : {},
+    spend: round(mine.spend),
+    impressions: mine.impressions,
+    results: mine.results,
+    costPerResult,
+    ctr: mine.ctr,
+    vsAccount: usual !== null && costPerResult !== null ? round(costPerResult / usual) : null
+  };
+}
+function learnFromResults(ideas, creatives, asOf) {
+  const ideaOf = (c) => c.definition?.idea ?? null;
+  return ideas.flatMap((idea) => {
+    if (idea.status === "idea" || idea.status === "retired") return [];
+    const own = creatives.filter((c) => ideaOf(c) === idea.id);
+    if (own.length === 0) return [];
+    const rest = totals(creatives.filter((c) => ideaOf(c) !== idea.id));
+    const usual = rest.results > 0 ? rest.spend / rest.results : null;
+    const result = ideaResult(own, usual, asOf);
+    const to = verdict(result, usual);
+    if (to === "testing" && SETTLED.has(idea.status)) return [];
+    return [{ idea: idea.id, from: idea.status, to, result }];
+  });
+}
+
+// src/commands/creatives/learn.ts
+var DESCRIPTION = `Write back what each built idea's ads did in the live Meta account: every creative of the idea pooled, judged against the rest of the account's cost per result, and the verdict (winner, failed, inconclusive, testing) and frozen numbers written onto src/creatives/_ideas/<idea>.md. Run it before writing new ideas, and weekly.
+
+Start here:
+  baker creatives learn               # last 30 days, written onto the ideas
+  baker creatives learn --days 60
+  baker creatives learn --dry-run     # show the verdicts, write nothing
+
+A winner gets results at 0.8x the usual cost or less (3+ results); failed is 1.5x or more, or spend worth two usual results with none; under 1,000 impressions it is still testing.`;
+var ARGS = {
+  days: { type: "string", required: false, description: "Reporting window in days (default 30)" },
+  "dry-run": { type: "boolean", required: false, default: false, description: "Show the verdicts; write nothing" }
+};
+registerSchema({ command: "creatives.learn", description: DESCRIPTION, args: ARGS });
+function learnEnvelope(learnings, written, unreadable = []) {
+  const winners = learnings.filter((l) => l.to === "winner").map((l) => l.idea);
+  const failed = learnings.filter((l) => l.to === "failed").map((l) => l.idea);
+  const hints = [];
+  if (unreadable.length > 0) {
+    hints.push(
+      `Could not read ${unreadable.join(", ")}, so their results were not written: fix what \`baker creatives ideas\` names, then run this again.`
+    );
+  }
+  if (learnings.length === 0) {
+    hints.push(
+      "No built idea has ads delivering yet: nothing to learn. Ideas count once a published ad shows their creative."
+    );
+  }
+  if (winners.length > 0) {
+    hints.push(
+      `Build on ${winners.join(", ")}: keep the message and make it in a new format or for a new persona before any new idea.`
+    );
+  }
+  if (failed.length > 0) {
+    hints.push(
+      `${failed.join(", ")} lost: never repeat their message; \`baker creatives ideas\` flags an idea that does.`
+    );
+  }
+  return {
+    ok: true,
+    data: {
+      written,
+      ideas: learnings.map((l) => ({
+        idea: l.idea,
+        status: l.from === l.to ? l.to : `${l.from} \u2192 ${l.to}`,
+        ...l.result
+      }))
+    },
+    hints
+  };
+}
+async function writeBack(root, learnings) {
+  for (const learning of learnings) {
+    const file = path.join(root, IDEAS_DIR, `${learning.idea}.md`);
+    const raw = await readFile(file, "utf8");
+    await writeFile(file, setDefinitionFields(raw, { status: learning.to, result: learning.result }), "utf8");
+  }
+}
+function readDefinition(root, slug) {
+  try {
+    return readFileSync(path.join(root, "src", "creatives", slug, "_definition.md"), "utf8");
+  } catch {
+    return null;
+  }
+}
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+var learnCommand = defineCommand({
+  meta: { name: "learn", description: DESCRIPTION },
+  args: ARGS,
+  async run({ args }) {
+    try {
+      const root = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+      const days = parseDays(args.days);
+      const performance = withDefinitions(
+        await apiPost("/api/creatives/performance", days ? { days } : {}),
+        (slug) => readDefinition(root, slug)
+      );
+      const { ideas, unreadable } = await readIdeas(root);
+      const learnings = learnFromResults(ideas, performance.data.creatives, today());
+      const dryRun = args["dry-run"] === true;
+      if (!dryRun) await writeBack(root, learnings);
+      writeJson(
+        learnEnvelope(
+          learnings,
+          !dryRun && learnings.length > 0,
+          unreadable.map((u) => u.id)
+        )
+      );
+    } catch (err) {
+      failApi(err);
+    }
+  }
+});
+export {
+  learnCommand,
+  learnEnvelope
+};
+//# sourceMappingURL=learn-23DQ72LC.js.map

package/dist/library-5XZP2W22.js

@@ -0,0 +1,211 @@
+import {
+  readOutputFlags
+} from "./chunk-WZTSS4SH.js";
+import {
+  activeFilterFlags,
+  emptyResultHints
+} from "./chunk-Q6ULQMWG.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-X6AHLUC7.js";
+import "./chunk-TM5UTSE4.js";
+import "./chunk-6THXOWAP.js";
+import {
+  fullImage,
+  maskEnvelope,
+  registerSchema,
+  writeJson,
+  writeOutput
+} from "./chunk-S6WPMD3V.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/images/library.ts
+import { defineCommand } from "citty";
+
+// src/commands/images/libraryRows.ts
+var LINE_CHARS = 48;
+var SUBJECT_CHARS = 120;
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function clip(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max).trimEnd()}\u2026`;
+}
+function oneLine(lines) {
+  return lines.length === 0 ? null : clip(lines.join("; "), LINE_CHARS);
+}
+function peopleLine(value) {
+  if (!Array.isArray(value)) return null;
+  return oneLine(
+    value.flatMap((entry) => {
+      const person = asRecord(entry);
+      const role = str(person.role);
+      if (!role) return [];
+      const identity = str(person.identity);
+      return [identity ? `${role} \u2014 ${identity}` : role];
+    })
+  );
+}
+function textLine(value) {
+  if (!Array.isArray(value)) return null;
+  return oneLine(value.filter((line) => typeof line === "string" && line.length > 0));
+}
+function compactLibraryRow(row) {
+  const analysis = asRecord(row.analysis);
+  const description = str(row.description);
+  const score = num(row.score);
+  const entries = [
+    ["_id", String(row._id ?? "")],
+    ["name", String(row.name ?? "")],
+    ["imageUrl", String(row.imageUrl ?? "")],
+    // Placing a remote <BakerImage> needs both, or the build downloads it to measure.
+    ["width", num(row.width)],
+    ["height", num(row.height)],
+    ["subject", clip(str(analysis.subject) ?? description ?? "", SUBJECT_CHARS) || null],
+    ["brandOwnership", str(analysis.brandOwnership)],
+    ["people", peopleLine(analysis.people)],
+    ["textInImage", textLine(analysis.textInImage)],
+    ["score", score === null ? null : Math.round(score * 100) / 100],
+    ["group", row.group && typeof row.group === "object" ? row.group : null]
+  ];
+  return Object.fromEntries(entries);
+}
+function compactJsonRow(row) {
+  return Object.fromEntries(Object.entries(compactLibraryRow(row)).filter(([, value]) => value !== null));
+}
+function libraryRowNormalizer(row, full) {
+  return full ? fullImage(row) : compactLibraryRow(row);
+}
+var ROWS = "\0rows\0";
+function rowPerLine(envelope) {
+  const rows = Array.isArray(envelope.data) ? envelope.data : [];
+  const list = rows.length === 0 ? "[]" : `[
+${rows.map((row) => `    ${JSON.stringify(row)}`).join(",\n")}
+  ]`;
+  return JSON.stringify({ ...envelope, data: ROWS }, null, 2).replace(JSON.stringify(ROWS), () => list);
+}
+function writeLibraryRows(data, flags, hints) {
+  const withHints = hints.length > 0 ? { hints } : {};
+  if (flags.format === "json" && !flags.full) {
+    const compact = { ok: true, data: data.map(compactJsonRow), ...withHints };
+    process.stdout.write(`${rowPerLine(flags.fields ? maskEnvelope(compact, flags.fields) : compact)}
+`);
+    return;
+  }
+  writeOutput({ ok: true, data, ...withHints }, flags.format, flags.fields, flags.full, libraryRowNormalizer);
+}
+
+// src/commands/images/library.ts
+registerSchema({
+  command: "images.library",
+  description: "Search the company image library. Returns only ready images.",
+  args: {
+    query: { type: "string", description: "Search query text", required: true },
+    limit: { type: "number", description: "Maximum results", required: false, default: 5 },
+    "min-score": { type: "number", description: "Minimum relevance score (0-1)", required: false },
+    "aspect-ratio": {
+      type: "string",
+      description: "Filter by aspect ratio (1:1, 16:9, 9:16, 2:3, 3:4, 1:2, 2:1, 4:5, 3:2, 4:3)",
+      required: false
+    },
+    tags: { type: "string", description: "Comma-separated tags to filter by", required: false },
+    source: {
+      type: "string",
+      description: "Filter by source (uploaded, pexels, pixabay, brandfetch, google_images, firecrawl, screenshotone, iconify, giphy, \u2026)",
+      required: false
+    },
+    "external-url-host": {
+      type: "string",
+      description: "Filter to library rows whose externalUrl host contains this substring",
+      required: false
+    },
+    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
+    fields: {
+      type: "string",
+      description: "Comma-separated keys to keep, e.g. --fields _id,imageUrl,subject",
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "The whole record (description, tags, palette, analysis) instead of the compact row",
+      required: false,
+      default: false
+    }
+  }
+});
+var libraryCommand = defineCommand({
+  meta: {
+    name: "library",
+    description: "Search the company image library (hybrid BM25 + vector + rerank). Use this BEFORE any external provider. Each hit is a compact row (_id, name, imageUrl, width, height, subject, brandOwnership, people, textInImage, score, group; empty keys left out); --full gives the whole record.\n\nStart here: baker images library 'hero banner' --aspect-ratio 16:9\nIds and URLs only: baker images library 'logo' --fields _id,imageUrl"
+  },
+  args: {
+    query: { type: "positional", description: "Search query text", required: false },
+    limit: { type: "string", description: "Max results (default 5)", required: false },
+    "min-score": { type: "string", description: "Minimum relevance score (0-1)", required: false },
+    "aspect-ratio": { type: "string", description: "Aspect ratio filter", required: false },
+    tags: { type: "string", description: "Comma-separated tags to filter by", required: false },
+    source: { type: "string", description: "Filter by source", required: false },
+    "external-url-host": {
+      type: "string",
+      description: "Filter library by externalUrl host substring (e.g. competitor.com)",
+      required: false
+    },
+    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
+    fields: {
+      type: "string",
+      description: "Comma-separated keys to keep",
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "The whole record instead of the compact row",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const query = args.query;
+      if (!query) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", message: "Search query is required" } });
+        process.exit(1);
+      }
+      const body = { query };
+      if (args.limit) body.limit = Number(args.limit);
+      if (args["aspect-ratio"]) body.aspectRatio = args["aspect-ratio"];
+      if (args.tags) body.tags = args.tags.split(",").filter(Boolean);
+      if (args.source) body.source = args.source;
+      if (args["external-url-host"]) body.externalUrlHost = args["external-url-host"];
+      let data = await apiPost("/api/images/search", body);
+      const minScore = args["min-score"] ? Number(args["min-score"]) : void 0;
+      if (minScore !== void 0) {
+        data = data.filter((r) => typeof r.score === "number" && r.score >= minScore);
+      }
+      const hints = emptyResultHints({
+        provider: "library",
+        hitCount: data.length,
+        activeFilters: activeFilterFlags(args, ["aspect-ratio", "tags", "source", "external-url-host", "min-score"]),
+        subject: query
+      });
+      writeLibraryRows(data, readOutputFlags(args), hints);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeJson({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJson({ ok: false, error: { code: "INTERNAL_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+export {
+  libraryCommand
+};
+//# sourceMappingURL=library-5XZP2W22.js.map

package/dist/lighthouse-KAMY3KYG.js

@@ -0,0 +1,75 @@
+import {
+  handleResearchError,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-FQTMVJEO.js";
+import {
+  apiPost
+} from "./chunk-X6AHLUC7.js";
+import "./chunk-TM5UTSE4.js";
+import "./chunk-6THXOWAP.js";
+import {
+  registerSchema
+} from "./chunk-S6WPMD3V.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/lighthouse.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.lighthouse",
+  description: "Landing page performance audit. Returns metrics that affect Google Ads Quality Score and CPC.",
+  args: {
+    url: { type: "string", description: "Full URL to audit (with https://)", required: true },
+    mobile: { type: "boolean", description: "Test as mobile (default: true)", required: false },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var FIELDS = {
+  url: "URL that was audited",
+  performance_score: "Lighthouse performance score 0-100 (aim for 90+)",
+  fcp_ms: "First Contentful Paint in ms (good: < 1800)",
+  lcp_ms: "Largest Contentful Paint in ms (good: < 2500)",
+  cls: "Cumulative Layout Shift (good: < 0.1)",
+  speed_index_ms: "Speed Index in ms (good: < 3400)",
+  interactive_ms: "Time to Interactive in ms (good: < 3800)"
+};
+var lighthouseCommand = defineCommand({
+  meta: {
+    name: "lighthouse",
+    description: `Landing page performance audit. Metrics affecting Google Ads Quality Score.
+
+Examples:
+  baker research lighthouse "https://example.com/landing"
+  baker research lighthouse "https://example.com" --mobile false`
+  },
+  args: {
+    url: { type: "positional", description: "Full URL to audit (with https://)", required: true },
+    mobile: { type: "string", description: "Test as mobile: true|false (default: true)", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const url = args.url;
+    const mobile = args.mobile === "false" ? false : void 0;
+    const skipCache = args["no-cache"] ? true : void 0;
+    try {
+      const data = await apiPost("/api/research/lighthouse", {
+        url,
+        mobile,
+        skipCache
+      });
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeResearchOutput([data], format);
+        return;
+      }
+      writeResearchJson({ ok: true, data, fields: FIELDS });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  lighthouseCommand
+};
+//# sourceMappingURL=lighthouse-KAMY3KYG.js.map