@koda-sl/baker-cli 0.202.0 → 0.204.0

package/README.md

@@ -86,8 +86,20 @@ All commands return a JSON envelope:
 
 // Dry-run
 { "ok": true, "dryRun": true, "operation": "images.delete", "params": { "id": "abc123" } }
+
+// Unknown option — the command stops instead of running without it
+{ "ok": false, "error": { "code": "UNKNOWN_ARGUMENT", "message": "--dimension-filter is not an option of `baker ga4 query`.", "fix": { "action": "check_schema", "explanation": "Did you mean --dimensions? Run `baker schema ga4 query` ..." }, "retryable": false } }
 ```
 
+### Unknown options are refused
+
+An option a command does not declare stops the run with `UNKNOWN_ARGUMENT`, naming the
+closest real one. Previously such an option was accepted and ignored, so a call that
+looked like it had filtered or narrowed a result was in fact answering the unfiltered
+question — and nothing in the output said so. Both spellings of an option work
+(`--run-id` and `--runId`), as they always did. Run `baker schema <command>` to see
+every option a command takes.
+
 Use `--output` to change format:
 
 | Format  | Description                        | Best for           | Available on |
@@ -2505,6 +2517,16 @@ List testimonials with optional filters.
 baker testimonials list --source google --sentiment positive --limit 20
 ```
 
+When `list` or `search` returns nothing, the envelope carries `meta.empty` explaining why, checked against the company's connected review sources rather than inferred from the empty result:
+
+| `meta.empty.reason` | Meaning | What to do |
+| --- | --- | --- |
+| `filtered_out` | Filters were applied, so the corpus itself was not examined | Drop every filter and re-run once |
+| `no_corpus_connected` | The company has no review source connected | Terminal — source proof another way; no rewording will help |
+| `corpus_empty` | A source is connected but holds no testimonials yet | Ingestion may still be running; do not report the client as having no reviews |
+
+If the source check itself fails, `meta.empty` is omitted entirely and the hint says so — an unverified absence is never reported as one.
+
 ### `baker testimonials tags`
 
 List the available testimonial tag names — built-in defaults plus the company's custom tags. Use it before filtering with `--tags`. Defaults to a markdown list (`--output json` for the `{ ok, data }` envelope).

package/dist/cli.js

@@ -18463,7 +18463,7 @@ Performance (the workhorse):
   baker ads meta insights --object act_123 --level ad --intent ranking                        \u2014 flag creatives to refresh
   baker ads meta insights --object act_123 --level adset --breakdowns publisher_platform,age  \u2014 placement \xD7 age
   baker ads meta insights --object act_123 --level ad --since 2026-01-01 --until 2026-03-31   \u2014 auto-async
-  baker ads meta insights --list-presets
+  baker ads meta insights --list-intents
 
 Audit & review:
   baker ads meta activities --account-id act_123 --days 14
@@ -40550,7 +40550,7 @@ registerSchema({
     },
     "from-video": {
       type: "string",
-      description: "The same, but from the VIDEO LIBRARY: comma-separated video ids (see `baker videos library`) to build on. Use this for footage the client uploaded or synced rather than something the Studio rendered. Counts against the same 10 source clips as --from-clip. The first use of a given video spends a minute encoding a reusable copy and is refused with a 'try again shortly' message; every use after that is instant.",
+      description: "The same, but from the VIDEO LIBRARY: comma-separated video ids (see `baker videos search`) to build on. Use this for footage the client uploaded or synced rather than something the Studio rendered. Counts against the same 10 source clips as --from-clip. The first use of a given video spends a minute encoding a reusable copy and is refused with a 'try again shortly' message; every use after that is instant.",
       required: false
     },
     model: {
@@ -42193,26 +42193,85 @@ var getCommand5 = defineCommand193({
 import { defineCommand as defineCommand194 } from "citty";
 
 // src/commands/testimonials/emptyCorpusHints.ts
-var NO_CORPUS_TAIL = 'this company has NO review corpus connected. Testimonials are ingested from the client\'s Google/Trustpilot reviews \u2014 an agent cannot write one \u2014 so no rewording will find quotes. Stop searching and source proof another way: a result or case study the client already published, a named-customer logo (`baker images logo`), or a founder claim attributed as a claim. Otherwise ship without a testimonial block and file the gap: `baker actions create --name "Collect customer quotes for <page>" --priority medium --tags <slug>`. Never invent, paraphrase-into-existence, or pad with unrelated praise.';
-var LEAD2 = {
-  // Search reranks the whole corpus, so an empty result is a property of the
-  // corpus far more often than of the query — but only an unfiltered `list`
-  // proves it, so send it there once rather than letting it re-query.
-  search: "No hits. Search reranks the whole corpus, so an empty result is nearly always an empty library rather than a missed query \u2014 confirm once with `baker testimonials list --limit 1`. If that is empty too, ",
-  list: "No rows on an unfiltered browse, which is proof rather than a hint: "
-};
-function emptyCorpusHints({ command, resultCount, activeFilters }) {
+function resolveEmptyReason({
+  resultCount,
+  activeFilters,
+  sourceCount
+}) {
   if (resultCount > 0) {
-    return [];
+    return null;
   }
-  const hints = [];
   if (activeFilters.length > 0) {
-    hints.push(
+    return "filtered_out";
+  }
+  return sourceCount === 0 ? "no_corpus_connected" : "corpus_empty";
+}
+var NO_CORPUS_EXIT = 'Testimonials are ingested from the client\'s Google/Trustpilot reviews \u2014 an agent cannot write one \u2014 so no rewording will find quotes. Stop searching and source proof another way: a result or case study the client already published, a named-customer logo (`baker images logo`), or a founder claim attributed as a claim. Otherwise ship without a testimonial block and file the gap: `baker actions create --name "Collect customer quotes for <page>" --priority medium --tags <slug>`. Never invent, paraphrase-into-existence, or pad with unrelated praise.';
+function emptyReasonDetail(reason, sourceCount, activeFilters) {
+  if (reason === "filtered_out") {
+    return `No rows matched, and ${activeFilters.join(", ")} narrowed this read. The corpus was not checked \u2014 drop every filter to see whether the library itself is empty.`;
+  }
+  if (reason === "no_corpus_connected") {
+    return "This company has no review source connected \u2014 checked against its source list, not inferred from the empty result.";
+  }
+  return `${sourceCount} review source${sourceCount === 1 ? " is" : "s are"} connected but hold no testimonials yet \u2014 the source is there, the rows are not. Ingestion may still be running.`;
+}
+async function measureEmptyCorpus({
+  command,
+  resultCount,
+  activeFilters
+}) {
+  if (resultCount > 0) {
+    return { hints: [] };
+  }
+  if (activeFilters.length > 0) {
+    const reason2 = "filtered_out";
+    return {
+      hints: emptyCorpusHints({ command, reason: reason2, sourceCount: 0, activeFilters }),
+      empty: { reason: reason2, detail: emptyReasonDetail(reason2, 0, activeFilters) }
+    };
+  }
+  let sourceCount;
+  try {
+    const sources = await apiGet("/api/testimonials/sources");
+    sourceCount = Array.isArray(sources) ? sources.length : 0;
+  } catch {
+    return {
+      hints: [
+        "No rows, and the check for connected review sources failed \u2014 so this is NOT evidence that the client has no reviews. Do not record an absence you could not verify. Re-run once; if it fails again, say the library could not be read rather than that it is empty."
+      ]
+    };
+  }
+  const reason = resolveEmptyReason({ resultCount, activeFilters, sourceCount });
+  if (reason === null) {
+    return { hints: [] };
+  }
+  return {
+    hints: emptyCorpusHints({ command, reason, sourceCount, activeFilters }),
+    empty: { reason, detail: emptyReasonDetail(reason, sourceCount, activeFilters) }
+  };
+}
+function emptyCorpusHints({
+  command,
+  reason,
+  sourceCount,
+  activeFilters
+}) {
+  if (reason === null) {
+    return [];
+  }
+  if (reason === "filtered_out") {
+    return [
       `No rows \u2014 ${activeFilters.join(", ")} narrowed this. Drop every filter and re-run once before touching the query; a filter combination and an empty library look identical from here.`
-    );
+    ];
   }
-  hints.push(`${LEAD2[command]}${NO_CORPUS_TAIL}`);
-  return hints;
+  const lead = command === "search" ? "No hits" : "No rows";
+  if (reason === "no_corpus_connected") {
+    return [`${lead}, and this company's source list is empty: there is no review corpus to search. ${NO_CORPUS_EXIT}`];
+  }
+  return [
+    `${lead}. ${sourceCount} review source${sourceCount === 1 ? " is" : "s are"} connected but no testimonials have landed yet \u2014 so this is a timing or ingestion gap, not a missing connection, and re-querying will not change it. Ingestion may still be running: say so rather than reporting the client has no reviews. ${NO_CORPUS_EXIT}`
+  ];
 }
 
 // src/commands/testimonials/list.ts
@@ -42287,14 +42346,14 @@ var listCommand18 = defineCommand194({
   run: async ({ args }) => {
     try {
       const data = await apiGet("/api/testimonials", buildListParams(args));
-      const hints = emptyCorpusHints({
+      const { hints, empty } = await measureEmptyCorpus({
         command: "list",
         resultCount: data.length,
         activeFilters: activeFilterFlags(args, FILTER_FLAGS)
       });
       const outputFormat = args.output || "json";
       writeOutput(
-        { ok: true, data, ...hints.length > 0 ? { hints } : {} },
+        { ok: true, data, ...empty ? { meta: { empty } } : {}, ...hints.length > 0 ? { hints } : {} },
         outputFormat,
         args.fields ? args.fields.split(",") : void 0,
         args.full,
@@ -42426,17 +42485,15 @@ var searchCommand3 = defineCommand195({
       const body = buildSearchRequest(query, args);
       const data = await apiPost("/api/testimonials/search", body);
       const languageHint = languageBiasHint(data, body.language);
-      const hints = [
-        ...emptyCorpusHints({
-          command: "search",
-          resultCount: data.length,
-          activeFilters: activeFilterFlags(args, FILTER_FLAGS2)
-        }),
-        ...languageHint ? [languageHint] : []
-      ];
+      const { hints: emptyHints, empty } = await measureEmptyCorpus({
+        command: "search",
+        resultCount: data.length,
+        activeFilters: activeFilterFlags(args, FILTER_FLAGS2)
+      });
+      const hints = [...emptyHints, ...languageHint ? [languageHint] : []];
       const outputFormat = args.output || "json";
       writeOutput(
-        { ok: true, data, ...hints.length > 0 ? { hints } : {} },
+        { ok: true, data, ...empty ? { meta: { empty } } : {}, ...hints.length > 0 ? { hints } : {} },
         outputFormat,
         args.fields ? args.fields.split(",") : void 0,
         args.full,
@@ -43985,6 +44042,172 @@ Full guide: __tooling__/docs/tools/baker/winning-ads.md`
   }
 });
 
+// src/unknown-flags.ts
+var ALWAYS_ACCEPTED = /* @__PURE__ */ new Set(["help", "h", "version"]);
+function subCommandsOf(command) {
+  const sub = command.subCommands;
+  return sub && typeof sub === "object" ? sub : null;
+}
+function argsOf(command) {
+  const args = command.args;
+  return args && typeof args === "object" ? args : null;
+}
+function resolveCommand2(root, argv) {
+  let command = root;
+  for (const token of argv) {
+    if (token === "--" || token.startsWith("-")) {
+      break;
+    }
+    const subCommands = subCommandsOf(command);
+    if (!subCommands) {
+      break;
+    }
+    const next = subCommands[token];
+    if (next === void 0) {
+      break;
+    }
+    if (typeof next !== "object") {
+      return { command, resolved: false };
+    }
+    command = next;
+  }
+  return { command, resolved: true };
+}
+function typeOf(def) {
+  return def && typeof def === "object" ? def.type : void 0;
+}
+function acceptedNames(command) {
+  const args = argsOf(command);
+  if (!args) {
+    return null;
+  }
+  const names = new Set(ALWAYS_ACCEPTED);
+  for (const [name, def] of Object.entries(args)) {
+    if (typeOf(def) === "positional") {
+      continue;
+    }
+    for (const spelling of [name, kebab(name), camel(name)]) {
+      names.add(spelling);
+      if (typeOf(def) === "boolean") {
+        names.add(`no-${spelling}`);
+      }
+    }
+  }
+  return names;
+}
+function kebab(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function camel(name) {
+  return name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function findUnknownFlags(root, argv) {
+  const { command, resolved } = resolveCommand2(root, argv);
+  if (!resolved) {
+    return [];
+  }
+  const accepted = acceptedNames(command);
+  if (!accepted) {
+    return [];
+  }
+  const unknown = [];
+  for (const token of argv) {
+    if (token === "--") {
+      break;
+    }
+    if (!token.startsWith("--")) {
+      continue;
+    }
+    const name = token.slice(2).split("=")[0] ?? "";
+    if (name.length > 0 && !accepted.has(name) && !unknown.includes(token)) {
+      unknown.push(token);
+    }
+  }
+  return unknown;
+}
+function closestFlag(unknown, command) {
+  const accepted = acceptedNames(command);
+  if (!accepted) {
+    return null;
+  }
+  const name = unknown.replace(/^--/, "").split("=")[0] ?? "";
+  const scored = [...accepted].filter((candidate) => !ALWAYS_ACCEPTED.has(candidate)).map((candidate) => ({
+    candidate,
+    prefix: sharedPrefix(name, candidate),
+    distance: editDistance(name, candidate)
+  })).filter(({ prefix, distance }) => prefix >= 4 || distance <= 3).sort((a, b) => b.prefix - a.prefix || a.distance - b.distance);
+  return scored[0] ? `--${scored[0].candidate}` : null;
+}
+function sharedPrefix(a, b) {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) {
+    i++;
+  }
+  return i;
+}
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+      current.push(Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution));
+    }
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function commandFor(root, argv) {
+  const { command, resolved } = resolveCommand2(root, argv);
+  return resolved ? command : null;
+}
+function unknownFlagEnvelope(unknown, commandPath, suggestion) {
+  const list = unknown.join(", ");
+  return {
+    ok: false,
+    error: {
+      code: "UNKNOWN_ARGUMENT",
+      message: `${list} ${unknown.length > 1 ? "are not options" : "is not an option"} of \`baker ${commandPath}\`.`,
+      fix: {
+        action: "check_schema",
+        explanation: (suggestion ? `Did you mean ${suggestion}? ` : "") + `Run \`baker schema ${commandPath}\` to see every option this command takes. Do not re-run the same call: until this version an unrecognised option was accepted and ignored, so a command that looked like it had filtered or narrowed the result was in fact answering the unfiltered question.`
+      },
+      retryable: false
+    }
+  };
+}
+function commandPathOf(root, argv) {
+  const path37 = [];
+  let command = root;
+  for (const token of argv) {
+    if (token === "--" || token.startsWith("-")) {
+      break;
+    }
+    const subCommands = subCommandsOf(command);
+    const next = subCommands?.[token];
+    if (next === void 0 || typeof next !== "object") {
+      break;
+    }
+    path37.push(token);
+    command = next;
+  }
+  return path37.join(" ");
+}
+function refuseUnknownFlags(root, argv) {
+  const unknown = findUnknownFlags(root, argv);
+  if (unknown.length === 0) {
+    return;
+  }
+  const command = commandFor(root, argv);
+  const first = unknown[0];
+  const suggestion = command && first ? closestFlag(first, command) : null;
+  process.stdout.write(
+    `${JSON.stringify(unknownFlagEnvelope(unknown, commandPathOf(root, argv), suggestion), null, 2)}
+`
+  );
+  process.exit(1);
+}
+
 // src/version.ts
 import { readFileSync as readFileSync14 } from "fs";
 function packageJsonUrl() {
@@ -44044,5 +44267,6 @@ Introspection: Run 'baker schema <command>' to inspect argument schemas.`
 });
 installStreamTaps();
 logInvocation(process.argv.slice(2));
+refuseUnknownFlags(main, process.argv.slice(2));
 runMain(main);
 //# sourceMappingURL=cli.js.map