@koda-sl/baker-cli 0.525.0 → 0.527.0

package/dist/chunk-3J3W23S4.js

@@ -0,0 +1,592 @@
+import {
+  findSubreddits,
+  searchReddit
+} from "./chunk-RUJS2NOA.js";
+import {
+  holdUnbilledSpend
+} from "./chunk-V2XEX2YR.js";
+import {
+  findWorkspaceRoot
+} from "./chunk-O37YK4P6.js";
+import {
+  askAboutText
+} from "./chunk-SDQLZYQG.js";
+import {
+  CUSTOMER_INSIGHTS_MODEL
+} from "./chunk-MCJ5I5LR.js";
+import {
+  apiGet,
+  apiPost
+} from "./chunk-B4UVJCJ4.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-FSGJSREN.js";
+
+// src/commands/research/customers.ts
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+var INSIGHT_TYPES = [
+  "accommodation",
+  "failed_solution",
+  "nearly_didnt",
+  "word",
+  "moment",
+  "pain",
+  "objection",
+  "desire",
+  "proof",
+  "other"
+];
+var FORCES = ["push", "pull", "anxiety", "habit"];
+var MAX_QUOTE_CHARS = 280;
+var SINGLE_QUOTES = /* @__PURE__ */ new Set([8216, 8217, 8218, 8219, 8242]);
+var DOUBLE_QUOTES = /* @__PURE__ */ new Set([8220, 8221, 8222, 8223, 8243]);
+function foldChar(char) {
+  if (/\s/.test(char)) return " ";
+  const code = char.codePointAt(0) ?? 0;
+  if (SINGLE_QUOTES.has(code)) return "'";
+  if (DOUBLE_QUOTES.has(code)) return '"';
+  return char.normalize("NFKC").toLowerCase();
+}
+function foldWithOffsets(text) {
+  let folded = "";
+  const offsets = [];
+  let at = 0;
+  for (const char of text) {
+    const out = foldChar(char);
+    const collapses = out === " " && (folded.length === 0 || folded.endsWith(" "));
+    if (!collapses) {
+      for (const piece of out) {
+        folded += piece;
+        offsets.push(at);
+      }
+    }
+    at += char.length;
+  }
+  if (folded.endsWith(" ")) {
+    folded = folded.slice(0, -1);
+    offsets.pop();
+  }
+  return { folded, offsets };
+}
+function findVerbatim(quote, text) {
+  const needle = foldWithOffsets(quote).folded;
+  if (needle.length === 0) return null;
+  const { folded, offsets } = foldWithOffsets(text);
+  const start = folded.indexOf(needle);
+  if (start < 0) return null;
+  const last = offsets[start + needle.length - 1] ?? 0;
+  const end = last + (String.fromCodePoint(text.codePointAt(last) ?? 0).length || 1);
+  return text.slice(offsets[start], end).replace(/\s+/g, " ").trim();
+}
+function keepVerbatim(candidates, sources) {
+  const kept = [];
+  let dropped = 0;
+  let tooLong = 0;
+  for (const { source: index, ...rest } of candidates) {
+    const source = sources[index - 1];
+    const quote = source ? findVerbatim(rest.quote, source.text) : null;
+    if (!source || !quote) {
+      dropped++;
+      continue;
+    }
+    if (quote.length > MAX_QUOTE_CHARS) {
+      tooLong++;
+      continue;
+    }
+    kept.push({ ...rest, quote, source });
+  }
+  return { kept, dropped, tooLong };
+}
+var SLUG_WORDS = 6;
+function asciiWords(text) {
+  return text.normalize("NFKD").replace(new RegExp("\\p{M}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim().split(" ").filter(Boolean);
+}
+function insightSlug(type, quote) {
+  return [type.replace(/_/g, "-"), ...asciiWords(quote).slice(0, SLUG_WORDS)].join("-");
+}
+function planInsightWrites(insights, existing, limit) {
+  const quotes = new Set(existing.map((e) => foldWithOffsets(e.quote).folded));
+  const ids = new Set(existing.map((e) => e.id));
+  const ranked = [...insights].sort((a, b) => INSIGHT_TYPES.indexOf(a.type) - INSIGHT_TYPES.indexOf(b.type));
+  const writes = [];
+  let skippedExisting = 0;
+  for (const insight of ranked) {
+    const folded = foldWithOffsets(insight.quote).folded;
+    if (quotes.has(folded)) {
+      skippedExisting++;
+      continue;
+    }
+    if (writes.length >= limit) continue;
+    const base = insightSlug(insight.type, insight.quote);
+    let id = base;
+    for (let n = 2; ids.has(id); n++) id = `${base}-${n}`;
+    quotes.add(folded);
+    ids.add(id);
+    writes.push({ id, insight });
+  }
+  return { writes, skippedExisting };
+}
+function yamlScalar(value) {
+  return JSON.stringify(value);
+}
+var TITLE_CHARS = 70;
+function insightTitle(quote) {
+  const text = quote.replace(/["“”]/g, "").replace(/\s+/g, " ").trim();
+  if (text.length <= TITLE_CHARS) return `\u201C${text}\u201D`;
+  const cut = text.slice(0, TITLE_CHARS);
+  return `\u201C${cut.slice(0, cut.lastIndexOf(" ")).replace(/[,;:.]$/, "")}\u2026\u201D`;
+}
+function renderInsightFile(insight, opts) {
+  const { source } = insight;
+  const lines = [
+    "---",
+    `title: ${yamlScalar(insightTitle(insight.quote))}`,
+    `type: ${insight.type}`,
+    `quote: ${yamlScalar(insight.quote)}`,
+    `source: ${yamlScalar(source.ref)}`,
+    `sourceKind: ${source.kind}`,
+    `seenAt: ${yamlScalar(source.saidOn ?? opts.today)}`,
+    "status: observed"
+  ];
+  if (insight.force) lines.push(`force: ${insight.force}`);
+  if (insight.persona?.trim()) lines.push(`persona: ${yamlScalar(insight.persona.trim())}`);
+  if (opts.product) lines.push(`product: ${yamlScalar(opts.product)}`);
+  lines.push("---", "", source.context.replace(/\s+/g, " ").trim(), "");
+  return lines.join("\n");
+}
+var MAX_SHORT_SOURCE_CHARS = 1500;
+var PLATFORM_NAMES = {
+  google: "Google",
+  trustpilot: "Trustpilot",
+  yelp: "Yelp",
+  tripadvisor: "Tripadvisor",
+  g2: "G2",
+  capterra: "Capterra",
+  amazon: "Amazon",
+  app_store: "App Store",
+  google_play: "Google Play"
+};
+var LibraryReviewSchema = z.object({
+  _id: z.string().min(1),
+  reviewText: z.string(),
+  sourceType: z.string().optional(),
+  reviewerName: z.string().optional(),
+  rating: z.number().optional(),
+  reviewDate: z.number().optional()
+});
+function dayOf(ms) {
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString().slice(0, 10);
+}
+function sentence(rest) {
+  const line = `${/^[aeiou]/i.test(rest) ? "An" : "A"} ${rest}`;
+  return line.endsWith(".") ? line : `${line}.`;
+}
+function reviewContext(review) {
+  const platform = review.sourceType ? `${PLATFORM_NAMES[review.sourceType] ?? review.sourceType} ` : "";
+  const rating = review.rating !== void 0 ? `${review.rating}\u2605 ` : "";
+  const by = review.reviewerName?.trim() ? ` by ${review.reviewerName.trim()}` : "";
+  return sentence(`${rating}${platform}review${by}`);
+}
+function sourcesFromTestimonials(data) {
+  const list = Array.isArray(data) ? data : [];
+  return list.flatMap((item) => {
+    const parsed = LibraryReviewSchema.safeParse(item);
+    if (!parsed.success) return [];
+    const review = parsed.data;
+    const text = review.reviewText.trim().slice(0, MAX_SHORT_SOURCE_CHARS);
+    if (!text) return [];
+    const saidOn = review.reviewDate !== void 0 ? dayOf(review.reviewDate) : void 0;
+    return [
+      {
+        ref: `testimonials:${review._id}`,
+        kind: "review",
+        text,
+        context: reviewContext(review),
+        ...saidOn ? { saidOn } : {}
+      }
+    ];
+  });
+}
+function sourcesFromReddit(items) {
+  return items.flatMap((item) => {
+    const words = item.kind === "post" ? [item.title ?? "", item.text].filter((t) => t.trim()).join("\n\n") : item.text;
+    const text = words.trim().slice(0, MAX_SHORT_SOURCE_CHARS);
+    if (!text) return [];
+    const under = item.kind === "comment" && item.title ? `, under ${JSON.stringify(item.title)}` : "";
+    const saidOn = dayOf(item.createdAt);
+    return [
+      {
+        ref: item.permalink,
+        kind: "reddit",
+        text,
+        context: `A Reddit ${item.kind} in r/${item.subreddit}${under}.`,
+        ...saidOn ? { saidOn } : {}
+      }
+    ];
+  });
+}
+var MAX_PAGE_SOURCE_CHARS = 6e3;
+function sourcesFromPages(pages) {
+  return pages.flatMap((page) => {
+    const text = page.content.trim().slice(0, MAX_PAGE_SOURCE_CHARS);
+    if (!text) return [];
+    const host = URL.canParse(page.finalUrl) ? new URL(page.finalUrl).host : page.finalUrl;
+    const title = page.title?.trim() ? `, ${JSON.stringify(page.title.trim())}` : "";
+    return [{ ref: page.finalUrl, kind: "web", text, context: `A page on ${host}${title}.` }];
+  });
+}
+function buildCustomersPrompt(sources, focus) {
+  return [
+    `Below are ${sources.length} numbered texts written by real customers (reviews, testimonials, forum posts and comments, web pages)${focus ? `, gathered about: ${focus}` : ""}.`,
+    "Find the customer truths in them, the material ads are written from.",
+    "",
+    "Rules:",
+    "- Every quote must be an EXACT substring of the text it cites: the same words, in the same order, with the same spelling and typos. Copy, never paraphrase, translate, summarize, correct or join two passages.",
+    `- The shortest span that carries the truth, at most ${MAX_QUOTE_CHARS} characters.`,
+    "- Only the customer's own words: skip a seller's reply, an ad, a page's marketing copy, and a text with no truth in it. Return fewer, or none, rather than invent.",
+    "- type: accommodation (a workaround they live with), failed_solution (what they tried before that failed them), nearly_didnt (what nearly stopped them buying), word (their own word or phrase for the problem), moment (the moment that started their search), pain, objection, desire, proof (a result they got), other.",
+    "- force, when it speaks to one: push (what pushes them off the old way), pull (what draws them to the new one), anxiety (what they fear about changing), habit (what keeps them where they are).",
+    '- persona: a few words on who is speaking, only when the text says it ("restaurant owner", "night-shift courier").',
+    "",
+    'Reply with only this JSON: {"insights":[{"source":1,"quote":"","type":"","force":"","persona":""}]}',
+    "",
+    "Texts:",
+    ...sources.map((source, i) => `[${i + 1}] ${source.text}`)
+  ].join("\n");
+}
+var AnswerSchema = z.object({ insights: z.array(z.unknown()) });
+var CandidateSchema = z.object({
+  source: z.coerce.number().int().positive(),
+  quote: z.string().trim().min(1),
+  type: z.enum(INSIGHT_TYPES).catch("other"),
+  force: z.enum(FORCES).optional().catch(void 0),
+  persona: z.string().trim().optional().catch(void 0)
+});
+function candidatesFrom(answer) {
+  const parsed = AnswerSchema.safeParse(answer);
+  if (!parsed.success) return null;
+  return parsed.data.insights.flatMap((item) => {
+    const candidate = CandidateSchema.safeParse(item);
+    if (!candidate.success) return [];
+    const { source, quote, type, force, persona } = candidate.data;
+    return [{ source, quote, type, ...force ? { force } : {}, ...persona ? { persona } : {} }];
+  });
+}
+function batchSources(sources, budget) {
+  const batches = [];
+  let current = [];
+  let size = 0;
+  for (const source of sources) {
+    if (current.length > 0 && size + source.text.length > budget) {
+      batches.push(current);
+      current = [];
+      size = 0;
+    }
+    current.push(source);
+    size += source.text.length;
+  }
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+var FEW_OBSERVED = 5;
+function customersHints(input) {
+  const { written, sources } = input;
+  const widen = `Search in the customers' own words with --query "<the words they write>" (their phrasing, not a category name), or add --web.`;
+  if (written === 0) {
+    return [
+      "No customer words were found to keep, so nothing was written. Import where customers already talk: `baker testimonials sources add <review page link>` (Google, Trustpilot, G2, app stores\u2026) brings their reviews into the library; then run this again.",
+      ...sources.reddit === null ? ['Reddit was not read: pass --focus "<product>" or --query "<their words>".'] : [widen],
+      "Until there are observed truths, ad ideas go in as explore bets: an idea with an empty `evidence` list."
+    ];
+  }
+  const cite = `Cite these by id in an idea's \`evidence\` (src/creatives/_ideas/<idea>.md); write the ad from the quote as said.`;
+  return written < FEW_OBSERVED ? [`Only ${written} observed. ${widen}`, cite] : [cite];
+}
+var INSIGHTS_DIR = path.join("src", "content", "insights");
+var BATCH_CHARS = 24e3;
+var MAX_BATCHES = 5;
+var WEB_PAGES = 3;
+var DEFAULT_LIMIT = 20;
+var SHOWN_QUOTE_CHARS = 120;
+var READ_TIMEOUT_MS = 18e4;
+var DESCRIPTION = `Gather what real customers say and keep it as Knowledge: one file per customer truth in src/content/insights/<id>.md, each a quote found word for word in its source (status: observed). Ads and ideas are written from these.
+
+Start here: baker research customers --focus "<product or persona>"
+
+Reads the company's review library, Reddit (with --focus or --query) and, with --web, a few web pages. A model only points at spans; a quote is kept only if it appears verbatim in the text it came from, and everything else is dropped and counted. Never write an insight by hand.
+
+Examples:
+  baker research customers --focus "payroll app for restaurants"
+  baker research customers --query "chasing invoices" --web
+  baker research customers --dry-run`;
+var ARGS = {
+  focus: {
+    type: "string",
+    required: false,
+    description: 'The product or persona to listen for, e.g. "payroll for restaurants". Also the Reddit search when --query is not given.'
+  },
+  query: {
+    type: "string",
+    required: false,
+    description: `Search terms in the customers' own words, e.g. "chasing invoices". Used for Reddit and the web.`
+  },
+  limit: { type: "string", required: false, description: `Most insights written (default ${DEFAULT_LIMIT}).` },
+  web: {
+    type: "boolean",
+    required: false,
+    default: false,
+    description: `Also read up to ${WEB_PAGES} web pages where customers talk about it (slower).`
+  },
+  "dry-run": {
+    type: "boolean",
+    required: false,
+    default: false,
+    description: "Show what would be written; write nothing."
+  },
+  full: {
+    type: "boolean",
+    required: false,
+    default: false,
+    description: "Add each insight's whole quote, source and context."
+  }
+};
+registerSchema({ command: "research.customers", description: DESCRIPTION, args: ARGS });
+var QuoteFrontmatter = z.object({ quote: z.string() });
+function quoteOf(raw) {
+  const front = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+  if (!front) return "";
+  try {
+    const parsed = QuoteFrontmatter.safeParse(parseYaml(front));
+    return parsed.success ? parsed.data.quote : "";
+  } catch {
+    return "";
+  }
+}
+async function readExistingInsights(dir) {
+  const files = (await readdir(dir).catch(() => [])).filter((f) => f.endsWith(".md"));
+  return await Promise.all(
+    files.map(async (file) => ({
+      id: file.slice(0, -3),
+      quote: quoteOf(await readFile(path.join(dir, file), "utf8").catch(() => ""))
+    }))
+  );
+}
+async function productSlugs(root) {
+  const files = await readdir(path.join(root, "src", "content", "products")).catch(() => []);
+  return files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
+}
+async function gatherTestimonials(focus) {
+  try {
+    const search = { query: focus ?? "", limit: 40 };
+    const data = focus ? await apiPost("/api/testimonials/search", search) : await apiGet("/api/testimonials", { limit: "50" });
+    return sourcesFromTestimonials(data);
+  } catch {
+    return null;
+  }
+}
+async function gatherReddit(query) {
+  const subreddits = await findSubreddits({ query: query.slice(0, 100), limit: 3 }).then((r) => r.results.filter((s) => s.access !== "private").map((s) => s.name)).catch(() => []);
+  const answers = await Promise.allSettled([
+    searchReddit({ query, subreddits, kind: "posts", limit: 15 }),
+    ...subreddits.length > 0 ? [searchReddit({ query, subreddits, kind: "comments", limit: 25 })] : []
+  ]);
+  if (answers.every((a) => a.status === "rejected")) return null;
+  const seen = /* @__PURE__ */ new Set();
+  const items = answers.flatMap((a) => a.status === "fulfilled" ? a.value.results : []).filter((item) => !seen.has(item.id) && Boolean(seen.add(item.id)));
+  return sourcesFromReddit(items);
+}
+var ExploreAnswer = z.object({ sources: z.array(z.object({ url: z.string() })) });
+async function resolveGroundingRedirect(url) {
+  if (!URL.canParse(url) || new URL(url).host !== "vertexaisearch.cloud.google.com") return url;
+  try {
+    const response = await fetch(url, { method: "HEAD", redirect: "manual", signal: AbortSignal.timeout(15e3) });
+    const location = response.headers.get("location");
+    return location && URL.canParse(location) ? location : url;
+  } catch {
+    return url;
+  }
+}
+async function gatherWeb(topic) {
+  let urls;
+  try {
+    const found = ExploreAnswer.parse(
+      await apiPost(
+        "/api/research/explore",
+        {
+          question: `Which pages carry first-hand customer comments about ${topic}, in the customers' own words: reviews, complaints, forum threads?`,
+          depth: "medium"
+        },
+        { timeoutMs: READ_TIMEOUT_MS }
+      )
+    );
+    urls = (await Promise.all(found.sources.slice(0, WEB_PAGES * 2).map((s) => resolveGroundingRedirect(s.url)))).filter((u) => !/reddit\.com/i.test(u)).filter((u, i, all) => all.indexOf(u) === i);
+  } catch {
+    return null;
+  }
+  const pages = await Promise.allSettled(
+    urls.slice(0, WEB_PAGES).map((url) => {
+      const body = { url };
+      return apiPost("/api/research/fetch", body, { timeoutMs: READ_TIMEOUT_MS });
+    })
+  );
+  return sourcesFromPages(pages.flatMap((p) => p.status === "fulfilled" ? [p.value] : []));
+}
+async function classifyBatch(batch, focus, onSpend) {
+  const prompt = buildCustomersPrompt(batch, focus);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const candidates = candidatesFrom(await askAboutText(CUSTOMER_INSIGHTS_MODEL, prompt, onSpend));
+    if (candidates) return candidates;
+  }
+  return null;
+}
+function interleave(lists) {
+  const out = [];
+  const longest = Math.max(0, ...lists.map((l) => l.length));
+  for (let i = 0; i < longest; i++) {
+    for (const list of lists) {
+      const source = list[i];
+      if (source) out.push(source);
+    }
+  }
+  return out;
+}
+function fail(code, message, fix) {
+  writeJson({ ok: false, error: { code, message, fix } });
+  process.exit(1);
+}
+async function gatherSources(opts) {
+  const { focus, topic, web: withWeb } = opts;
+  const [testimonials, reddit, web] = await Promise.all([
+    gatherTestimonials(focus),
+    topic ? gatherReddit(topic) : Promise.resolve(null),
+    withWeb && topic ? gatherWeb(topic) : Promise.resolve(null)
+  ]);
+  const counts = {
+    testimonials: testimonials?.length ?? null,
+    reddit: reddit?.length ?? null,
+    web: web?.length ?? null
+  };
+  return { all: interleave([testimonials ?? [], reddit ?? [], web ?? []]), counts };
+}
+async function classifyAll(sources, focus, root) {
+  const batches = batchSources(sources, BATCH_CHARS).slice(0, MAX_BATCHES);
+  const spent = [];
+  const answers = await Promise.all(batches.map((batch) => classifyBatch(batch, focus, (u) => spent.push(u))));
+  await holdUnbilledSpend(path.join(root, "canvas", ".cache"), spent);
+  if (batches.length > 0 && answers.every((a) => a === null)) return null;
+  const result = { kept: [], dropped: 0, tooLong: 0 };
+  batches.forEach((batch, i) => {
+    const gated = keepVerbatim(answers[i] ?? [], batch);
+    result.kept.push(...gated.kept);
+    result.dropped += gated.dropped;
+    result.tooLong += gated.tooLong;
+  });
+  return result;
+}
+async function writeInsights(dir, writes, opts) {
+  if (writes.length === 0) return [];
+  await mkdir(dir, { recursive: true });
+  const written = [];
+  for (const entry of writes) {
+    const file = renderInsightFile(entry.insight, opts);
+    const ok = await writeFile(path.join(dir, `${entry.id}.md`), file, { encoding: "utf8", flag: "wx" }).then(
+      () => true,
+      () => false
+    );
+    if (ok) written.push(entry);
+  }
+  return written;
+}
+function writtenRow({ id, insight }, full) {
+  const quote = insight.quote.length > SHOWN_QUOTE_CHARS ? `${insight.quote.slice(0, SHOWN_QUOTE_CHARS)}\u2026` : insight.quote;
+  if (!full) return { id, type: insight.type, quote };
+  return {
+    id,
+    type: insight.type,
+    quote,
+    full_quote: insight.quote,
+    source: insight.source.ref,
+    context: insight.source.context,
+    ...insight.force ? { force: insight.force } : {},
+    ...insight.persona ? { persona: insight.persona } : {}
+  };
+}
+async function resolveTopic(root, focus, query) {
+  const products = await productSlugs(root);
+  const product = focus ? products.find((slug) => slug === asciiWords(focus).join("-")) : void 0;
+  const firstProduct = products[0];
+  const topic = query ?? focus ?? (firstProduct ? asciiWords(firstProduct).join(" ") : void 0);
+  return { product, topic };
+}
+async function researchCustomers(root, opts) {
+  const { focus, query, limit = DEFAULT_LIMIT, web = false, dryRun = false } = opts;
+  const { product, topic } = await resolveTopic(root, focus, query);
+  const { all, counts } = await gatherSources({ focus, topic, web });
+  const gated = await classifyAll(all, focus, root);
+  if (!gated) return null;
+  const dir = path.join(root, INSIGHTS_DIR);
+  const plan = planInsightWrites(gated.kept, await readExistingInsights(dir), limit);
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const shown = dryRun ? plan.writes : await writeInsights(dir, plan.writes, { today, ...product ? { product } : {} });
+  return { shown, plan, gated, counts };
+}
+var customersCommand = defineCommand({
+  meta: { name: "customers", description: DESCRIPTION },
+  args: ARGS,
+  async run({ args }) {
+    const focus = args.focus?.trim() || void 0;
+    const query = args.query?.trim() || void 0;
+    const limit = args.limit === void 0 ? DEFAULT_LIMIT : Number(args.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      fail("VALIDATION_ERROR", "--limit must be a whole number from 1 to 100.", "Run it again with --limit 20.");
+    }
+    const dryRun = Boolean(args["dry-run"]);
+    const root = findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    const found = await researchCustomers(root, { focus, query, limit, web: Boolean(args.web), dryRun });
+    if (!found) {
+      fail(
+        "UNAVAILABLE",
+        "The model that picks out customer words did not answer (no gateway key here, or it failed twice).",
+        "Run it again. Do not write insights by hand: an insight is only a quote this command found in its source."
+      );
+    }
+    const { shown, plan, gated, counts } = found;
+    writeJson({
+      ok: true,
+      data: {
+        ...dryRun ? { dry_run: true } : {},
+        written: shown.map((entry) => writtenRow(entry, Boolean(args.full))),
+        skipped_existing: plan.skippedExisting,
+        dropped_not_verbatim: gated.dropped,
+        ...gated.tooLong > 0 ? { dropped_too_long: gated.tooLong } : {},
+        sources: counts
+      },
+      hints: customersHints({ written: shown.length, sources: counts })
+    });
+  }
+});
+
+export {
+  INSIGHT_TYPES,
+  FORCES,
+  MAX_QUOTE_CHARS,
+  keepVerbatim,
+  planInsightWrites,
+  renderInsightFile,
+  sourcesFromTestimonials,
+  sourcesFromReddit,
+  sourcesFromPages,
+  buildCustomersPrompt,
+  candidatesFrom,
+  batchSources,
+  customersHints,
+  researchCustomers,
+  customersCommand
+};
+//# sourceMappingURL=chunk-3J3W23S4.js.map

package/dist/chunk-3KMYOPBI.js

@@ -0,0 +1,98 @@
+import {
+  ApiError
+} from "./chunk-B4UVJCJ4.js";
+
+// src/commands/research/output.ts
+var RESEARCH_DATA_NOTE = "Estimates based on third-party SERP data \u2014 not exact figures. Use for directional insights, not precise measurement.";
+function writeResearchJson(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope, null, 2)}
+`);
+}
+function toCsvRow(values) {
+  return values.map((v) => {
+    if (v.includes(",") || v.includes('"') || v.includes("\n")) {
+      return `"${v.replace(/"/g, '""')}"`;
+    }
+    return v;
+  }).join(",");
+}
+function flattenRow(row) {
+  const flat = {};
+  for (const [key, val] of Object.entries(row)) {
+    flat[key] = typeof val === "object" && val !== null ? JSON.stringify(val) : String(val ?? "");
+  }
+  return flat;
+}
+function writeCsv(data, fields) {
+  if (data.length === 0) return;
+  const cols = fields ?? Object.keys(data[0] ?? {});
+  process.stdout.write(`${toCsvRow(cols)}
+`);
+  for (const row of data) {
+    const flat = flattenRow(row);
+    process.stdout.write(`${toCsvRow(cols.map((f) => flat[f] ?? ""))}
+`);
+  }
+}
+function writeJsonl(data) {
+  for (const row of data) {
+    process.stdout.write(`${JSON.stringify(row)}
+`);
+  }
+}
+function writeMd(data, fields) {
+  if (data.length === 0) return;
+  const cols = fields ?? Object.keys(data[0] ?? {});
+  process.stdout.write(`| ${cols.join(" | ")} |
+`);
+  process.stdout.write(`| ${cols.map(() => "---").join(" | ")} |
+`);
+  for (const row of data) {
+    const flat = flattenRow(row);
+    process.stdout.write(`| ${cols.map((f) => markdownCell(flat[f] ?? "")).join(" | ")} |
+`);
+  }
+}
+function markdownCell(value) {
+  return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function writeResearchOutput(data, format, fields) {
+  switch (format) {
+    case "csv":
+      writeCsv(data, fields);
+      break;
+    case "jsonl":
+      writeJsonl(data);
+      break;
+    case "md":
+      writeMd(data, fields);
+      break;
+    default:
+      writeResearchJson({ ok: true, data });
+  }
+}
+function writeResearchHints(hints, format) {
+  if (format === "json") {
+    return;
+  }
+  for (const hint of hints) {
+    process.stderr.write(`${hint}
+`);
+  }
+}
+function handleResearchError(err, fixFor) {
+  const code = err instanceof ApiError ? err.code : "NETWORK_ERROR";
+  const message = err instanceof ApiError ? err.message : err instanceof Error ? err.message : "Unexpected error";
+  const fix = fixFor?.(code);
+  writeResearchJson({ ok: false, error: { code, message, ...fix ? { fix } : {} } });
+  process.exit(1);
+}
+
+export {
+  RESEARCH_DATA_NOTE,
+  writeResearchJson,
+  writeResearchOutput,
+  writeResearchHints,
+  handleResearchError
+};
+//# sourceMappingURL=chunk-3KMYOPBI.js.map