@koda-sl/baker-cli 0.371.0 → 0.372.0

package/README.md

@@ -110,6 +110,22 @@ question — and nothing in the output said so. Both spellings of an option work
 that lists every option: `baker schema <command>` (`check_schema`) when the command
 registers a schema, `baker <command> --help` (`check_help`) when it does not.
 
+### Narrowing a result: `--fields`
+
+`--fields a,b,c` works on every command that prints the JSON envelope. It keeps only
+those keys of each record in `data` — the rows when `data` is a list or wraps one
+(`baker chats list --fields id,title`), `data` itself when it is a single record
+(`baker experiment plan ... --fields traffic,warning`). Naming a key of the wrapper beside
+keys of its rows narrows both. `meta`, `hints` and warnings are
+kept, and a name no record carries is reported in `hints` alongside the keys that do
+exist. Commands that declare `--fields` themselves keep their own meaning
+(`ads meta insights` chooses which metrics to request; `ads linkedin creatives` takes dotted
+paths; `actions draft` picks the columns of `--output md|files` and leaves its JSON
+whole). A command whose default output is text needs `--output json` for there to be an
+envelope to narrow; without it a note on stderr says the flag changed nothing. A success
+that prints its result beside `ok` rather than under `data` (`canvas validate`,
+`canvas critique`) comes back whole, with a hint saying `--fields` was not applied.
+
 ### Fresh reads: `--no-cache`
 
 Every command that caches takes `--no-cache`, and it skips **both** cache layers — the

package/dist/{chunk-L4QXAYIC.js → chunk-4ACU7GBN.js}

@@ -2,13 +2,13 @@ import {
   handleConnectionError,
   needsConnectionFix,
   writeAdsJson
-} from "./chunk-FXVELNAS.js";
+} from "./chunk-ZI7TPBXB.js";
 import {
   ApiError
-} from "./chunk-MZQC4LII.js";
+} from "./chunk-MF7YA62W.js";
 import {
   getEnv
-} from "./chunk-2OKSJNLA.js";
+} from "./chunk-HJEMOSPH.js";
 
 // src/commands/ads/meta/shared.ts
 var DAY_MS = 864e5;
@@ -120,4 +120,4 @@ export {
   resolveEffectiveStatus,
   statusFilterHints
 };
-//# sourceMappingURL=chunk-L4QXAYIC.js.map
+//# sourceMappingURL=chunk-4ACU7GBN.js.map

package/dist/{chunk-3NIBJ3GL.js → chunk-FGHMWBUD.js}

@@ -1,7 +1,7 @@
 import {
   debugLogHttp,
   readBodyForLog
-} from "./chunk-XWHHYHKQ.js";
+} from "./chunk-VZEDAFAR.js";
 import {
   API_KEY_FORMAT_MESSAGE,
   DIRECT_ROUTE,
@@ -18,7 +18,7 @@ import {
   refuseNonPublicUrl,
   requireConnection,
   shouldEscalate
-} from "./chunk-2OKSJNLA.js";
+} from "./chunk-HJEMOSPH.js";
 
 // ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
 var require_safe_stable_stringify = __commonJS({
@@ -9986,4 +9986,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-3NIBJ3GL.js.map
+//# sourceMappingURL=chunk-FGHMWBUD.js.map

package/dist/{chunk-2OKSJNLA.js → chunk-HJEMOSPH.js}

@@ -282,6 +282,434 @@ function isBakerApiKey(value) {
   return KEY_PREFIXES.some((prefix) => value.startsWith(prefix));
 }
 
+// src/schemas.ts
+var registry = /* @__PURE__ */ new Map();
+function registerSchema(schema) {
+  registry.set(schema.command, schema);
+}
+function listSchemas() {
+  return [...registry.keys()];
+}
+function spellingKey(name) {
+  return name.toLowerCase().replaceAll("-", "");
+}
+function resolveSchemaName(words, names) {
+  const joined = words.join(".");
+  if (names.includes(joined)) {
+    return joined;
+  }
+  const matches = names.filter((name) => spellingKey(name) === spellingKey(joined));
+  return matches.length === 1 ? matches[0] : void 0;
+}
+function findSchema(words) {
+  const name = resolveSchemaName(words, listSchemas());
+  return name === void 0 ? void 0 : registry.get(name);
+}
+
+// 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 resolveCommand(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 } = resolveCommand(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;
+}
+var SYNONYMS = {
+  from: ["start-date", "start", "since"],
+  since: ["start-date", "start"],
+  start: ["start-date", "since"],
+  to: ["end-date", "end", "until"],
+  until: ["end-date", "end"],
+  end: ["end-date", "until"],
+  path: ["landing"],
+  url: ["landing"]
+};
+function closestFlag(unknown, command) {
+  const accepted = acceptedNames(command);
+  if (!accepted) {
+    return null;
+  }
+  const name = unknown.replace(/^--/, "").split("=")[0] ?? "";
+  const synonym = SYNONYMS[name]?.find((candidate) => accepted.has(candidate));
+  if (synonym) {
+    return `--${synonym}`;
+  }
+  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 <= typoBudget(name)).sort((a, b) => b.prefix - a.prefix || a.distance - b.distance);
+  return scored[0] ? `--${scored[0].candidate}` : null;
+}
+function typoBudget(name) {
+  return Math.max(1, Math.floor(name.length / 3));
+}
+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 } = resolveCommand(root, argv);
+  return resolved ? command : null;
+}
+function suggestFlag(unknown, command) {
+  const flag = closestFlag(unknown, command);
+  if (!flag) {
+    return null;
+  }
+  const args = argsOf(command) ?? {};
+  const name = flag.slice(2);
+  const def = args[name] ?? args[camel(name)];
+  const described = def && typeof def === "object" ? def.description : void 0;
+  const description = typeof described === "string" ? described.split(/(?<!\b(?:e\.g|i\.e|vs))\.\s/)[0]?.trim().replace(/\.$/, "") : "";
+  return description ? { flag, description } : { flag };
+}
+function suggestionText(suggestion) {
+  if (!suggestion) {
+    return "";
+  }
+  return suggestion.description ? `Did you mean ${suggestion.flag}? It is described as: ${suggestion.description}. ` : `Did you mean ${suggestion.flag}? `;
+}
+var OUTPUT_EXPLANATION = "This command has no --output option: `--output json` is accepted by every command that prints the JSON envelope, and md or files only where `baker schema` lists `output`. Drop the option and read the default output. ";
+function unknownFlagEnvelope(unknown, commandPath, suggestion, hasSchema) {
+  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: hasSchema ? "check_schema" : "check_help",
+        explanation: (unknown.some((flag) => flag === "--output" || flag.startsWith("--output=")) ? OUTPUT_EXPLANATION : "") + suggestionText(suggestion) + `Run \`${hasSchema ? `baker schema ${commandPath}` : `baker ${commandPath} --help`}\` 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 path = [];
+  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;
+    }
+    path.push(token);
+    command = next;
+  }
+  return path.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 ? suggestFlag(first, command) : null;
+  const path = commandPathOf(root, argv);
+  process.stdout.write(
+    `${JSON.stringify(unknownFlagEnvelope(unknown, path, suggestion, findSchema(path.split(" ")) !== void 0), null, 2)}
+`
+  );
+  process.exit(1);
+}
+
+// src/output-flag.ts
+var FLAG = "--output";
+var ENVELOPE = "json";
+var PRINTS_NO_ENVELOPE = /* @__PURE__ */ new Set([
+  "analytics sending-events",
+  "canvas run",
+  "canvas rerun",
+  "canvas sync-definition"
+]);
+function declaredArg(command, name) {
+  const args = command.args;
+  if (!args || typeof args !== "object" || !(name in args)) {
+    return null;
+  }
+  const def = args[name];
+  return def && typeof def === "object" ? def : {};
+}
+function envelopeRequests(argv) {
+  const end = argv.indexOf("--");
+  const limit = end === -1 ? argv.length : end;
+  const found = [];
+  for (let index = 0; index < limit; index++) {
+    const token = argv[index];
+    if (token === `${FLAG}=${ENVELOPE}`) {
+      found.push({ index, length: 1 });
+    } else if (token === FLAG && argv[index + 1] === ENVELOPE && index + 1 < limit) {
+      found.push({ index, length: 2 });
+      index++;
+    }
+  }
+  return found;
+}
+function outputFlagForCommand(root, argv) {
+  const requests = envelopeRequests(argv);
+  if (requests.length === 0) {
+    return argv;
+  }
+  const command = commandFor(root, argv);
+  if (!command || declaredArg(command, "output") || PRINTS_NO_ENVELOPE.has(commandPathOf(root, argv))) {
+    return argv;
+  }
+  const jsonSwitch = declaredArg(command, "json")?.type === "boolean";
+  const dropped = new Set(requests.flatMap(({ index, length }) => length === 2 ? [index, index + 1] : [index]));
+  const first = requests[0]?.index;
+  return argv.flatMap((token, index) => {
+    if (!dropped.has(index)) {
+      return [token];
+    }
+    return jsonSwitch && index === first ? ["--json"] : [];
+  });
+}
+
+// src/field-mask.ts
+var FLAG2 = "--fields";
+function parseFields(value) {
+  return value.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
+}
+function takeFieldsFlag(root, argv) {
+  const end = argv.indexOf("--");
+  const limit = end === -1 ? argv.length : end;
+  const taken = /* @__PURE__ */ new Set();
+  const fields = [];
+  for (let index = 0; index < limit; index++) {
+    const token = argv[index] ?? "";
+    if (token.startsWith(`${FLAG2}=`)) {
+      taken.add(index);
+      fields.push(...parseFields(token.slice(FLAG2.length + 1)));
+    } else if (token === FLAG2) {
+      const value = argv[index + 1];
+      if (value === void 0 || index + 1 >= limit || value.startsWith("-")) {
+        return { argv, fields: null };
+      }
+      taken.add(index).add(index + 1);
+      fields.push(...parseFields(value));
+      index++;
+    }
+  }
+  if (taken.size === 0 || fields.length === 0) {
+    return { argv, fields: null };
+  }
+  const command = commandFor(root, argv);
+  if (!command || declaredArg(command, "fields") || PRINTS_NO_ENVELOPE.has(commandPathOf(root, argv))) {
+    return { argv, fields: null };
+  }
+  return { argv: argv.filter((_, index) => !taken.has(index)), fields };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pick(record, fields) {
+  return Object.fromEntries(fields.filter((field) => field in record).map((field) => [field, record[field]]));
+}
+function soleList(data) {
+  const lists = Object.entries(data).filter(
+    (entry) => Array.isArray(entry[1]) && entry[1].length > 0 && entry[1].every((item) => isRecord(item))
+  );
+  return lists.length === 1 ? lists[0] ?? null : null;
+}
+function wrappedList(data, fields) {
+  const rowFields = fields.filter((field) => !(field in data));
+  const list = soleList(data);
+  if (list === null || !list[1].some((row) => rowFields.some((field) => field in row))) {
+    return null;
+  }
+  return list[0];
+}
+function recordsOf(data, fields) {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  if (!isRecord(data)) {
+    return [];
+  }
+  const list = wrappedList(data, fields);
+  return list === null ? [data] : data[list];
+}
+function maskData(data, fields) {
+  const maskWith = (keep) => (item) => isRecord(item) ? pick(item, keep) : item;
+  if (Array.isArray(data)) {
+    return data.map(maskWith(fields));
+  }
+  if (!isRecord(data)) {
+    return data;
+  }
+  const list = wrappedList(data, fields);
+  if (list === null) {
+    return pick(data, fields);
+  }
+  const wrapperFields = fields.filter((field) => field in data);
+  const rows = recordsOf(data, fields).map(maskWith(fields.filter((field) => !(field in data))));
+  return { ...wrapperFields.length > 0 ? pick(data, wrapperFields) : data, [list]: rows };
+}
+function unmatchedHint(data, fields) {
+  const records = recordsOf(data, fields).filter(isRecord);
+  if (records.length === 0) {
+    return null;
+  }
+  const keys = isRecord(data) ? [data, ...soleList(data)?.[1] ?? []] : records;
+  const carried = new Set(keys.flatMap((record) => Object.keys(record)));
+  const unmatched = fields.filter((field) => !carried.has(field));
+  if (unmatched.length === 0) {
+    return null;
+  }
+  return `--fields matched nothing for: ${unmatched.join(", ")}. The keys data carries are: ${[...carried].join(", ")}.`;
+}
+function reprint(text, envelope) {
+  const indent = text.trimStart().startsWith("{\n") ? 2 : void 0;
+  return `${JSON.stringify(envelope, null, indent)}${text.endsWith("\n") ? "\n" : ""}`;
+}
+function withHint(envelope, hint) {
+  return { ...envelope, hints: [...Array.isArray(envelope.hints) ? envelope.hints : [], hint] };
+}
+var NO_DATA_HINT = "--fields was not applied: this result carries no data to narrow, so it is printed whole. Drop --fields on this command.";
+function maskPrintedEnvelope(text, fields) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || typeof parsed.ok !== "boolean") {
+    return null;
+  }
+  if (parsed.ok !== true || "dryRun" in parsed) {
+    return text;
+  }
+  return reprint(text, maskEnvelope(parsed, fields));
+}
+function maskEnvelope(envelope, fields) {
+  if (!("data" in envelope)) {
+    return withHint(envelope, NO_DATA_HINT);
+  }
+  const masked = { ...envelope, data: maskData(envelope.data, fields) };
+  const miss = unmatchedHint(envelope.data, fields);
+  return miss ? withHint(masked, miss) : masked;
+}
+function maskWrites(stream, fields) {
+  let applied = false;
+  const write2 = stream.write.bind(stream);
+  stream.write = (chunk, ...rest) => {
+    const masked = typeof chunk === "string" ? maskPrintedEnvelope(chunk, fields) : null;
+    if (masked === null) {
+      return write2(chunk, ...rest);
+    }
+    applied = true;
+    return write2(masked, ...rest);
+  };
+  return { sawEnvelope: () => applied };
+}
+function installFieldMask(fields, commandPath) {
+  const mask = maskWrites(process.stdout, fields);
+  process.on("exit", () => {
+    if (!mask.sawEnvelope()) {
+      process.stderr.write(
+        `--fields was not applied: \`baker ${commandPath}\` printed no JSON envelope to narrow. Add --output json to get the envelope, or drop --fields.
+`
+      );
+    }
+  });
+}
+
 // src/output.ts
 var ASPECT_RATIO_MAP = {
   "1:1": 1,
@@ -671,7 +1099,8 @@ function writeOutput(envelope, format, fields, full, normalizer) {
     return;
   }
   if (format === "json") {
-    writeJson(envelope);
+    write(`${JSON.stringify(fields ? maskEnvelope(envelope, fields) : envelope, null, 2)}
+`);
     return;
   }
   if (format !== "files" && format !== "md") {
@@ -829,6 +1258,14 @@ export {
   plannedRoutes,
   API_KEY_FORMAT_MESSAGE,
   isBakerApiKey,
+  registerSchema,
+  listSchemas,
+  findSchema,
+  commandPathOf,
+  refuseUnknownFlags,
+  outputFlagForCommand,
+  takeFieldsFlag,
+  installFieldMask,
   compactImage,
   compactVideo,
   videoNormalizer,
@@ -852,4 +1289,4 @@ export {
   captureVimeoCookie,
   childEnvWith
 };
-//# sourceMappingURL=chunk-2OKSJNLA.js.map
+//# sourceMappingURL=chunk-HJEMOSPH.js.map