@koda-sl/baker-cli 0.354.0 → 0.355.0

package/README.md

@@ -98,7 +98,12 @@ All commands return a JSON envelope:
 ### 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
+real one it was most likely reaching for, with the first sentence of that option's own
+description. A word the command spells differently is matched by meaning (`--from` and
+`--since` → `--start-date`, `--to` and `--until` → `--end-date`, `--path` and `--url` →
+`--landing`, each only where the command has it); otherwise only a near spelling is
+offered, so a short option is never pointed at an unrelated one (`--from` at `--full`).
+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. The error's `fix` names the exact call
@@ -1333,7 +1338,7 @@ Shared flags: `--days <n>` (default 30) or `--start-date` / `--end-date` (`YYYY-
 
 `--measure` decides whose activity is measured and defaults to `campaigns` (only visitors a Baker landing brought). `--measure all` measures the client's entire website and is a decision somebody has to ask for. `host` is the client's own landing domain when one shares a domain with the site being measured, so the script and its events stay first-party; `firstParty` in the response says which, and removing that domain from Baker means re-running this command.
 
-**Paging the list reports.** `people`, `submissions` and `delivery` are lists of individual things rather than breakdowns — `delivery` and `submissions` are the ones the CLI exposes, `people` backs the People section of the dashboard's landing Analytics screen over the same wire — and only they take `--page <n>` (1-based) and `--page-size <n>` (up to 200, default 50). The response carries `pageInfo` with `hasMore` — when it is true there **are** more rows, so a total must never be reported from one page. Pass neither flag and a list comes back at the size it always did.
+**Paging the list reports.** `people`, `submissions` and `delivery` are lists of individual things rather than breakdowns — `delivery` and `submissions` are the ones the CLI exposes, `people` backs the People section of the dashboard's landing Analytics screen over the same wire — and only they take `--page <n>` (1-based) and `--page-size <n>` (up to 200, default 50). The response carries `pageInfo` with `hasMore` — when it is true there **are** more rows, so a total must never be reported from one page. Pass neither flag and a list comes back at the size it always did. A value that is not a whole positive number (`--page /pricing`) is refused before any request, naming `--landing` as the flag that narrows a report to one page of the site.
 
 **A conversion is a company-level named event, not a property of a Form.** `baker analytics conversions` is the only place "what counts" is decided, and an empty `definitions` list means every conversion number in every other report is zero — not because nobody converted, but because nothing is named as an outcome and Baker never guesses which event is the point of a page. `--candidates` lists every event these pages actually produced — each Form step and trigger, every `data-baker-*` event, every outbound destination — with volume and whether it is already counted; that list is where an event key comes from, so never invent one. `--event <key> --name "Booked a call"` starts counting it **immediately and retroactively**: the whole stored history is rescored, so naming the right event today also fixes last month. Nothing here is staged and publishing is not involved. Two events given the same `--name` become one row and one number, which is how a call booked on three different Forms reads as one outcome. `--count-mode every_time` is for the outcomes people genuinely repeat (a guide downloaded twice is two downloads); the default counts once per visit.
 

package/dist/cli.js

@@ -33563,6 +33563,19 @@ function pageOf(args5) {
     ...size ? { pageSize: Number(size) } : {}
   };
 }
+function isWholePositive(raw) {
+  return /^[1-9]\d*$/.test(String(raw));
+}
+function paginationError(args5) {
+  if (args5.page !== void 0 && !isWholePositive(args5.page)) {
+    return `--page takes a page number of a list report (1, 2, \u2026), not "${String(args5.page)}". To narrow a report to one page of the site, pass --landing <internalId> (from \`baker analytics landings\`), or read one path with \`baker analytics page --path /pricing\`.`;
+  }
+  const size = args5["page-size"];
+  if (size !== void 0 && !isWholePositive(size)) {
+    return `--page-size takes a number of rows (1 to 200), not "${String(size)}".`;
+  }
+  return null;
+}
 function requestBody(args5, options) {
   const candidates = {
     preset: options.preset,
@@ -33627,6 +33640,11 @@ async function runPreset(args5, options) {
     });
     process.exit(1);
   }
+  const pagination = paginationError(args5);
+  if (pagination) {
+    writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message: pagination } });
+    process.exit(1);
+  }
   try {
     const response = await apiPost("/api/analytics/query", requestBody(args5, options));
     const requestedPlatform = args5.platform === void 0 ? "" : String(args5.platform);
@@ -68772,19 +68790,36 @@ function findUnknownFlags(root, argv) {
   }
   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 <= 3).sort((a, b) => b.prefix - a.prefix || a.distance - b.distance);
+  })).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]) {
@@ -68808,6 +68843,24 @@ function commandFor(root, argv) {
   const { command, resolved } = resolveCommand2(root, argv);
   return resolved ? command : null;
 }
+function suggestFlag(unknown, command) {
+  const flag = closestFlag(unknown, command);
+  if (!flag) {
+    return null;
+  }
+  const args5 = argsOf(command) ?? {};
+  const name = flag.slice(2);
+  const def = args5[name] ?? args5[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(", ");
@@ -68818,7 +68871,7 @@ function unknownFlagEnvelope(unknown, commandPath, suggestion, hasSchema) {
       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 : "") + (suggestion ? `Did you mean ${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.`
+        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
     }
@@ -68848,7 +68901,7 @@ function refuseUnknownFlags(root, argv) {
   }
   const command = commandFor(root, argv);
   const first = unknown[0];
-  const suggestion = command && first ? closestFlag(first, command) : null;
+  const suggestion = command && first ? suggestFlag(first, command) : null;
   const path48 = commandPathOf(root, argv);
   process.stdout.write(
     `${JSON.stringify(unknownFlagEnvelope(unknown, path48, suggestion, findSchema(path48.split(" ")) !== void 0), null, 2)}