@koda-sl/baker-cli 0.462.0 → 0.464.0

package/dist/variant-ZFCOXYUK.js

@@ -0,0 +1,338 @@
+import {
+  nextVariantNumber,
+  repointFile,
+  variantNumberOf,
+  variantOfSlug,
+  variantSlug
+} from "./chunk-LA6PPSNA.js";
+import {
+  repeatedValues
+} from "./chunk-ERSX3MKH.js";
+import {
+  apiPost
+} from "./chunk-64RONDRZ.js";
+import "./chunk-EDC5L2GA.js";
+import "./chunk-S25EINEI.js";
+import {
+  registerSchema
+} from "./chunk-RHA6K4WJ.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/landing/variant.ts
+import { randomUUID } from "crypto";
+import { mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+registerSchema({
+  command: "landing.variant",
+  description: "Create a new variant of a page, for an A/B test. The variant shares the page's sections instead of copying them, so the only difference between the two is the one you fork \u2014 which is the only way the test measures what you think it measures. Run `baker experiment plan` FIRST: most pages cannot settle most questions.",
+  args: {
+    page: { type: "string", description: "The page to make a variant of, by slug", required: true },
+    fork: {
+      type: "string",
+      description: "The component the variant owns its own copy of, named as it appears under _components/ (`Hero.astro`, or `hero/Card.astro`). Repeat for several. Everything else is shared with the control, so a later edit to the control reaches both arms and cannot skew the test.",
+      required: false
+    },
+    because: {
+      type: "string",
+      description: "What you SAW that makes this worth building \u2014 the observation, not the change. Required here, before the page exists, because a reason written afterwards is a caption for a page rather than the reason for one.",
+      required: true
+    },
+    change: {
+      type: "string",
+      description: "What is different about this version, in the client's words \u2014 \u201Cput the booking form in the hero\u201D.",
+      required: true
+    }
+  }
+});
+var SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+async function readInternalId(definitionPath) {
+  try {
+    const text = await readFile(definitionPath, "utf8");
+    return /^internalId:\s*"?([^"\s]+)"?\s*$/m.exec(text)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+async function archivedVariantNumbers(root, internalId) {
+  if (!internalId) return [];
+  try {
+    const entries = await readdir(path.resolve(root, "src/_variants", internalId), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => Number(entry.name)).filter((n) => Number.isInteger(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
+function fail(code, message, fix) {
+  process.stderr.write(
+    `${JSON.stringify({ ok: false, error: { code, message, ...fix ? { fix } : {} } }, null, 2)}
+`
+  );
+  process.exit(2);
+}
+async function isDir(p) {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function listLandingSlugs(root) {
+  try {
+    const entries = await readdir(path.resolve(root, "src", "pages"), { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith(".")).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+async function listComponents(componentsDir, prefix = "") {
+  let entries;
+  try {
+    entries = await readdir(componentsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...await listComponents(path.join(componentsDir, entry.name), rel));
+    else if (entry.name.endsWith(".astro")) out.push(rel);
+  }
+  return out.sort();
+}
+function resolveForkName(requested, available) {
+  const cleaned = requested.replace(/^\.?\/?(_components\/)?/, "");
+  for (const candidate of [cleaned, `${cleaned}.astro`]) {
+    if (available.includes(candidate)) return candidate;
+  }
+  const basename = (p) => p.slice(p.lastIndexOf("/") + 1);
+  const matches = available.filter((a) => basename(a) === cleaned || basename(a) === `${cleaned}.astro`);
+  return matches.length === 1 ? matches[0] ?? null : null;
+}
+function parseForks(fork, rawArgs) {
+  const names = repeatedValues(rawArgs, "fork", fork).flatMap((s) => s.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+  return [...new Set(names)];
+}
+function pageInTest(status, page) {
+  for (const test of status.experiments) {
+    if (test.landingSlug !== page) continue;
+    if (test.status !== "finished") {
+      return `${page} is already in a test (${test.experimentId}, against ${test.variantSlug}, ${test.status}). One page has one test at a time \u2014 read it with \`baker experiment status --landing ${page}\`, and end it with \`baker experiment finish\` before building the next version.`;
+    }
+    if (test.fold === "owed" || test.fold === "landing") {
+      return `The last test on ${page} was won by ${test.variantSlug}, and the page is still being updated to match \u2014 run \`baker experiment fold\` and publish before building the next version.`;
+    }
+  }
+  return null;
+}
+function buildVariantDefinition(controlDefinition, opts) {
+  const frontmatter = controlDefinition.match(/^---\n[\s\S]*?\n---/)?.[0] ?? "---\n---";
+  let out = frontmatter;
+  out = out.replace(/^internalId:.*$/m, `internalId: "${opts.internalId}"`);
+  out = out.replace(/^internalTitle:\s*(.*)$/m, (_m, title) => `internalTitle: ${title.trim()} (variant)`);
+  const shared = opts.forks.length > 0 ? opts.forks.join(", ") : "nothing yet";
+  const note = [
+    "",
+    `# Version ${variantNumberOf(opts.variantSlug) ?? "?"} of \`${opts.controlSlug}\` \u2014 for an A/B test`,
+    "",
+    `This is not a page. It is one version of \`${opts.controlSlug}\`, shown to half of that page's visitors while a test runs; the address bar keeps saying \`/${opts.controlSlug}/\` and this folder has no address of its own. Everything about the page \u2014 the campaign, the audience, the offer, the proof \u2014 is in \`src/pages/${opts.controlSlug}/_definition.md\`, and that is where it is edited. This file only says what is different here.`,
+    "",
+    `**Only this differs:** ${shared}. Every other section is imported from \`${opts.controlSlug}\`, on purpose \u2014 an edit to the page reaches both versions, so the test keeps measuring the one difference rather than a drift between two copies. Edit only the files under \`src/pages/${opts.variantSlug}/_components/\`.`,
+    ...opts.because ? ["", `**Because:** ${opts.because}`] : [],
+    ...opts.change ? ["", `**We changed:** ${opts.change}`] : [],
+    "",
+    `Run \`baker experiment start --landing ${opts.controlSlug} --variant ${opts.variantSlug} --because "\u2026" --change "\u2026"\` to begin, and read the result with \`baker experiment status\`. When the test ends, \`baker experiment fold\` moves the version that won into the page and removes this folder.`,
+    ""
+  ].join("\n");
+  return `${out.trimEnd()}
+${note}`;
+}
+async function resolveTargets(projectRoot, opts) {
+  const { controlSlug } = opts;
+  if (!SLUG_RE.test(controlSlug)) {
+    fail(
+      "INVALID_SLUG",
+      `"${controlSlug}" is not a page slug \u2014 use the folder name directly under src/pages/ (lowercase letters, digits and dashes).`,
+      { argument: "page", availableSlugs: await listLandingSlugs(projectRoot) }
+    );
+  }
+  if (variantOfSlug(controlSlug) !== null) {
+    fail(
+      "INVALID_SLUG",
+      `"${controlSlug}" is already a variant of "${variantOfSlug(controlSlug)}". Make the next variant of the page itself: \`baker landing variant ${variantOfSlug(controlSlug)}\`.`
+    );
+  }
+  const controlDir = path.resolve(projectRoot, "src", "pages", controlSlug);
+  if (!await isDir(controlDir)) {
+    fail("NOT_FOUND", `No page at src/pages/${controlSlug}/`, {
+      availableSlugs: await listLandingSlugs(projectRoot)
+    });
+  }
+  if (!await exists(path.join(controlDir, "index.astro"))) {
+    fail("NOT_FOUND", `src/pages/${controlSlug}/index.astro is missing, so there is no page to make a variant of.`);
+  }
+  const internalId = await readInternalId(path.join(controlDir, "_definition.md"));
+  const variantSlugValue = variantSlug(
+    controlSlug,
+    nextVariantNumber(
+      controlSlug,
+      await listLandingSlugs(projectRoot),
+      await archivedVariantNumbers(projectRoot, internalId)
+    )
+  );
+  const variantDir = path.resolve(projectRoot, "src", "pages", variantSlugValue);
+  const available = await listComponents(path.join(controlDir, "_components"));
+  const forks = [];
+  for (const name of parseForks(opts.fork, opts.rawArgs)) {
+    const resolved = resolveForkName(name, available);
+    if (resolved === null) {
+      fail("NOT_FOUND", `"${name}" is not a component of ${controlSlug}.`, {
+        availableComponents: available,
+        hint: "Name it as it appears under _components/ \u2014 `Hero.astro`, or `hero/Card.astro`."
+      });
+    }
+    forks.push(resolved);
+  }
+  return { controlDir, variantDir, variantSlug: variantSlugValue, available, forks };
+}
+async function writeVariant(opts) {
+  const { controlDir, variantDir, controlSlug, variantSlug: variantSlug2, forks } = opts;
+  const forkedTargets = new Set(forks.map((f) => path.join(controlDir, "_components", f)));
+  const written = [];
+  const indexText = await readFile(path.join(controlDir, "index.astro"), "utf8");
+  await mkdir(variantDir, { recursive: true });
+  await writeFile(
+    path.join(variantDir, "index.astro"),
+    repointFile(indexText, { fromDir: controlDir, toDir: variantDir, controlDir, variantDir, forkedTargets }),
+    "utf8"
+  );
+  written.push(`src/pages/${variantSlug2}/index.astro`);
+  for (const fork of forks) {
+    const fromFile = path.join(controlDir, "_components", fork);
+    const toFile = path.join(variantDir, "_components", fork);
+    const text = await readFile(fromFile, "utf8");
+    await mkdir(path.dirname(toFile), { recursive: true });
+    await writeFile(
+      toFile,
+      repointFile(text, {
+        fromDir: path.dirname(fromFile),
+        toDir: path.dirname(toFile),
+        controlDir,
+        variantDir,
+        forkedTargets
+      }),
+      "utf8"
+    );
+    written.push(`src/pages/${variantSlug2}/_components/${fork}`);
+  }
+  const controlDefinitionPath = path.join(controlDir, "_definition.md");
+  if (await exists(controlDefinitionPath)) {
+    const definition = buildVariantDefinition(await readFile(controlDefinitionPath, "utf8"), {
+      internalId: randomUUID().replace(/-/g, "").slice(0, 8),
+      variantSlug: variantSlug2,
+      controlSlug,
+      forks,
+      ...opts.because ? { because: opts.because } : {},
+      ...opts.change ? { change: opts.change } : {}
+    });
+    await writeFile(path.join(variantDir, "_definition.md"), definition, "utf8");
+    written.push(`src/pages/${variantSlug2}/_definition.md`);
+  }
+  await mkdir(path.join(variantDir, "_images"), { recursive: true });
+  await writeFile(path.join(variantDir, "_images", ".gitkeep"), "", "utf8");
+  return written;
+}
+var variantCommand = defineCommand({
+  meta: {
+    name: "variant",
+    description: "Create a new variant of a page, for an A/B test. The variant SHARES the page's sections and forks only the component you name, so the two versions differ by exactly the thing you are testing. It is a version of that page, not a page of its own: it is never indexed, never listed, and has no public URL \u2014 both versions answer at the page's own address. Run `baker experiment plan` first \u2014 most pages do not have the traffic to settle most questions."
+  },
+  args: {
+    page: { type: "positional", required: true, description: "The page to make a variant of, by slug" },
+    fork: {
+      type: "string",
+      description: "Component the variant owns its own copy of (`Hero.astro`). Repeat for several."
+    },
+    because: {
+      type: "string",
+      required: true,
+      description: "What you SAW that makes this worth building \u2014 the observation, not the change. Required here, before the page exists, because a reason written afterwards is a caption for a page rather than the reason for one, and a test with no stated belief teaches nothing whichever way it lands. Recorded in the page's notes and passed to `baker experiment start`."
+    },
+    change: {
+      type: "string",
+      required: true,
+      description: "What is different about this version, in the client's words \u2014 \u201Cput the booking form in the hero\u201D."
+    }
+  },
+  async run({ args, rawArgs }) {
+    const projectRoot = process.cwd();
+    const controlSlug = String(args.page);
+    const { controlDir, variantDir, variantSlug: variantSlug2, available, forks } = await resolveTargets(projectRoot, {
+      controlSlug,
+      fork: args.fork,
+      rawArgs
+    });
+    let status;
+    try {
+      const response = await apiPost("/api/experiments/status", {
+        landingSlug: controlSlug
+      });
+      status = response.data;
+    } catch (error) {
+      fail(
+        "UNAVAILABLE",
+        `Could not check whether ${controlSlug} is already in a test (${error instanceof Error ? error.message : String(error)}). Nothing was written \u2014 run \`baker experiment status --landing ${controlSlug}\` and try again.`
+      );
+    }
+    const taken = pageInTest(status, controlSlug);
+    if (taken) fail("CONFLICT", taken, { landing: controlSlug });
+    const written = await writeVariant({
+      controlDir,
+      variantDir,
+      controlSlug,
+      variantSlug: variantSlug2,
+      forks,
+      because: String(args.because),
+      change: String(args.change)
+    });
+    const hints = [
+      forks.length === 0 ? `MISSING --fork: ${variantSlug2} currently renders exactly ${controlSlug}, so a test between them cannot conclude anything. Re-run with --fork <Component>, or copy the one section your change touches into src/pages/${variantSlug2}/_components/ and repoint that import.` : `Edit only src/pages/${variantSlug2}/_components/${forks.join(", ")} \u2014 every other section is shared with ${controlSlug}, and editing a shared one changes both arms at once.`,
+      `Preview both at http://localhost:4321/${controlSlug}/ and http://localhost:4321/${variantSlug2}/ and check they differ only where you meant. Once it is live, only the first of those two answers \u2014 a variant has no public address of its own, and \`/${controlSlug}/?_bkr_preview=b\` is how anyone looks at it.`,
+      `Then: baker experiment start --landing ${controlSlug} --variant ${variantSlug2} --because "${String(args.because)}" --change "${String(args.change)}". Nothing is split until the session is published \u2014 the person publishing is the review of this page.`
+    ];
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          ok: true,
+          data: {
+            page: controlSlug,
+            slug: variantSlug2,
+            forked: forks,
+            shared: available.filter((c) => !forks.includes(c)),
+            written
+          },
+          hints
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+});
+export {
+  buildVariantDefinition,
+  pageInTest,
+  parseForks,
+  resolveForkName,
+  variantCommand
+};
+//# sourceMappingURL=variant-ZFCOXYUK.js.map

package/dist/videos-W2TSVOMR.js

@@ -0,0 +1,39 @@
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/videos/index.ts
+import { defineCommand } from "citty";
+var videosCommand = defineCommand({
+  meta: {
+    name: "videos",
+    description: `Find and manage videos in Baker. Subcommands: search, get, upload, ingest, fetch, describe, delete, retry, tags.
+
+Examples:
+  baker videos search "product demo" --limit 5
+  baker videos search "tutorial" --tags explainer
+  baker videos get <video-id>
+  baker videos upload ./demo.mp4
+  baker videos ingest https://www.youtube.com/watch?v=abc123
+  baker videos fetch https://www.youtube.com/watch?v=abc123 --out ./clips
+  baker videos describe <video-id> --description "Customer testimonial, 30s"
+  baker videos delete <video-id> --dry-run
+  baker videos retry <video-id>                    # process a failed video again
+  baker videos tags                                # list; tags create|update|delete for custom tags
+Full guide: __tooling__/docs/tools/baker/videos.md`
+  },
+  subCommands: {
+    get: () => import("./get-YKFBTKJJ.js").then((m) => m.getCommand),
+    group: () => import("./group-2QWXJVOI.js").then((m) => m.groupCommand),
+    search: () => import("./search-VVH3YL53.js").then((m) => m.searchCommand),
+    upload: () => import("./upload-X47VGLAY.js").then((m) => m.uploadCommand),
+    ingest: () => import("./ingest-4OPQQPM3.js").then((m) => m.ingestCommand),
+    fetch: () => import("./fetch-EGI25WL6.js").then((m) => m.fetchCommand),
+    describe: () => import("./describe-TWIGHSV7.js").then((m) => m.describeCommand),
+    delete: () => import("./delete-6NVCUFEA.js").then((m) => m.deleteCommand),
+    retry: () => import("./retry-67PVKNVK.js").then((m) => m.retryCommand),
+    tags: () => import("./tags-IXVMXJ3E.js").then((m) => m.tagsCommand)
+  }
+});
+export {
+  videosCommand
+};
+//# sourceMappingURL=videos-W2TSVOMR.js.map

package/dist/view-KOD7WF3O.js

@@ -0,0 +1,121 @@
+import {
+  READABLE_SHOT,
+  downloadReadableShot
+} from "./chunk-DNCLWSHO.js";
+import {
+  INSPIRATION_HINTS,
+  fidelityHint,
+  reportError
+} from "./chunk-AK5XXL4U.js";
+import {
+  apiGet
+} from "./chunk-64RONDRZ.js";
+import "./chunk-EDC5L2GA.js";
+import "./chunk-S25EINEI.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-RHA6K4WJ.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/landing/inspiration/view.ts
+import path from "path";
+import { defineCommand } from "citty";
+registerSchema({
+  command: "landing.inspiration.view",
+  description: "Everything known about one section: composition, motion, design tokens, the copy it uses, why it works, and what must change to make it yours. Downloads the desktop and mobile screenshots plus the motion filmstrip so you can look at them.",
+  args: {
+    id: { type: "string", description: "Section id from search", required: true },
+    full: {
+      type: "boolean",
+      description: "Add the classification facets (theme, density, rank, interactions, media, devices, tags) and the reproduction notes",
+      required: false
+    }
+  }
+});
+var viewCommand = defineCommand({
+  meta: {
+    name: "view",
+    description: "Full detail for one reference section. Example: baker landing inspiration view k57abc\u2026 \u2014 read the screenshots it saves before you build."
+  },
+  args: {
+    id: { type: "positional", description: "Section id from search", required: true },
+    full: {
+      type: "boolean",
+      description: "Include classification facets and reproduction notes",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const id = args.id;
+      const data = await apiGet("/api/landing-inspiration/section", { id });
+      const section = data.section;
+      const dir = path.join(process.cwd(), ".baker", "inspiration", id);
+      const ext = READABLE_SHOT.extension;
+      const [desktop, mobile, filmstrip] = await Promise.all([
+        downloadReadableShot(section.desktopShotUrl, path.join(dir, `desktop.${ext}`)),
+        downloadReadableShot(section.mobileShotUrl, path.join(dir, `mobile.${ext}`)),
+        downloadReadableShot(section.motionFilmstripUrl, path.join(dir, `motion-filmstrip.${ext}`))
+      ]);
+      const full = args.full;
+      const hints = [INSPIRATION_HINTS.structureNotCopy, INSPIRATION_HINTS.adapt];
+      if (desktop) hints.push(`Read ${desktop} before you build \u2014 the description is not the section.`);
+      hints.push("Need the mechanics? `baker landing inspiration code <id>` writes the standalone HTML+CSS to disk.");
+      const fidelity = fidelityHint(section.fidelity);
+      if (fidelity) hints.push(fidelity);
+      if (filmstrip) {
+        hints.push(
+          `${filmstrip} shows this section animating in, six frames left-to-right then top-to-bottom, with the elapsed time on each. Read it if you want the motion, not just the layout.`
+        );
+      }
+      writeJson({
+        ok: true,
+        data: {
+          id: section.id,
+          page_id: section.sourceId,
+          section: section.sectionType,
+          composition: section.composition,
+          look: section.visualRegister,
+          motion: section.motionSummary,
+          design_tokens: section.designTokens,
+          size: section.boundingBox,
+          copy: {
+            headline: section.headline,
+            subhead: section.subhead,
+            ctas: section.ctaLabels,
+            proof: section.proofSignals
+          },
+          why_it_works: section.whyItWorks,
+          adaptation_notes: section.adaptationNotes,
+          craft: section.craftScore,
+          fidelity: section.fidelity,
+          source_url: section.sourceUrl,
+          screenshots: { desktop, mobile, motion_filmstrip: filmstrip },
+          // Behind --full: exactly the block `search` already gates, plus the
+          // reproduction notes, which `code` returns again for the one caller
+          // that acts on them. Everything above is what you design *from*;
+          // these are how the section was filed and how it rebuilds.
+          ...full ? {
+            theme: section.theme,
+            density: section.density,
+            show_tell_rank: section.showTellRank,
+            interactions: section.interactions,
+            media: section.mediaKinds,
+            devices: section.contentDevices,
+            tags: section.tags,
+            reproduction_notes: section.reproductionNotes
+          } : {}
+        },
+        hints
+      });
+    } catch (error) {
+      reportError(error);
+    }
+  }
+});
+export {
+  viewCommand
+};
+//# sourceMappingURL=view-KOD7WF3O.js.map

package/dist/viewer-check-IXXLB54G.js

@@ -0,0 +1,69 @@
+import {
+  OFFER_READ,
+  VIEWER_CLARITY,
+  VIEWER_QUESTIONS,
+  VIEWER_REQUIRED_CLARITY,
+  ViewerAnswerSchema,
+  buildViewerPrompt,
+  checkViewer,
+  describeViewer,
+  gatewayViewerModel,
+  jevReadJudge,
+  judgeViewerAnswer,
+  liveViewerLookups,
+  misreadings,
+  personaSegments,
+  readCreativeForViewerCheck,
+  readPersonas,
+  resolveViewer,
+  sureEnough,
+  viewerCheckBeforeRender,
+  viewerCheckCacheKey,
+  viewerCheckCommand,
+  viewerCheckFailure,
+  viewerCheckSkip
+} from "./chunk-DONJRIX5.js";
+import "./chunk-NFSLRRIE.js";
+import "./chunk-FGTFSVGG.js";
+import "./chunk-SEWU2A5Q.js";
+import "./chunk-IIJGBQTR.js";
+import "./chunk-CW36LVKM.js";
+import "./chunk-OD62ZR6E.js";
+import "./chunk-CHSNHVYF.js";
+import "./chunk-DRXGPVX6.js";
+import "./chunk-5HYSKH77.js";
+import "./chunk-KIGGMKAE.js";
+import "./chunk-XYA2VVLM.js";
+import "./chunk-77Q7WH7F.js";
+import "./chunk-V5YMTW6L.js";
+import "./chunk-AJN2QXU5.js";
+import "./chunk-EDC5L2GA.js";
+import "./chunk-S25EINEI.js";
+import "./chunk-RHA6K4WJ.js";
+import "./chunk-YQSBHWOI.js";
+export {
+  OFFER_READ,
+  VIEWER_CLARITY,
+  VIEWER_QUESTIONS,
+  VIEWER_REQUIRED_CLARITY,
+  ViewerAnswerSchema,
+  buildViewerPrompt,
+  checkViewer,
+  describeViewer,
+  gatewayViewerModel,
+  jevReadJudge,
+  judgeViewerAnswer,
+  liveViewerLookups,
+  misreadings,
+  personaSegments,
+  readCreativeForViewerCheck,
+  readPersonas,
+  resolveViewer,
+  sureEnough,
+  viewerCheckBeforeRender,
+  viewerCheckCacheKey,
+  viewerCheckCommand,
+  viewerCheckFailure,
+  viewerCheckSkip
+};
+//# sourceMappingURL=viewer-check-IXXLB54G.js.map