@datarails-ai/dr-cli 1.6.121 → 1.6.123

package/dist/cli.js

@@ -8,7 +8,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-cli",
-  version: "1.6.121",
+  version: "1.6.123",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-12T10:41:54.439Z";
+var BUILD_TIME = "2026-10-12T11:20:38.309Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -891,7 +891,7 @@ async function exchangeApiKey(host, apiKey, options) {
 }
 function describeApiKeyExchangeFailure(err, identity2) {
   if (err.httpStatus === 401) {
-    return `the server refused the API key for ${identity2} \u2014 it may be revoked or expired, API keys may not be enabled for your organization (ask an admin), or the server may be temporarily unable to evaluate that.`;
+    return `the server refused the API key for ${identity2} \u2014 it may be revoked or expired, API keys may not be enabled for your organization (ask an admin), or the server may be temporarily unable to evaluate that. If the key was revoked or expired, start a new session with a new key; retrying with this one will not help.`;
   }
   if (err.httpStatus === 404) {
     return `${identity2}: this server does not support API keys (the exchange endpoint answered 404).`;
@@ -31029,6 +31029,96 @@ function formatCalcFieldError(name, preview2, full) {
   return `${head} looks like placeholder text, not a real expression. The server's ETL compiler rejects formulas with no [field] reference, "quoted" literal, function() call, or numeric value \u2014 replace it before retrying. Common cause: a GET \u2192 PUT round-trip on a pre-kickoff starter mapper carried the placeholder text forward.`;
 }
 
+// src/commands/_mapperConfigShape.ts
+var OBJECT_LIST_KEYS = [
+  "header",
+  "dimension",
+  "footer",
+  "attributes",
+  "calculated_fields",
+  "fx_conversions",
+  "table_id"
+];
+var GET_HINT = '`dr datamappers get <mapper_id> --json` shows the shape the server expects (a mapper with no anchor carries "table_id": []).';
+function describeValue(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "an array";
+  switch (typeof v) {
+    case "number":
+      return `a number (${String(v)})`;
+    case "string":
+      return `a string (${JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}\u2026` : v)})`;
+    case "boolean":
+      return `a boolean (${String(v)})`;
+    case "object":
+      return "an object";
+    default:
+      return typeof v;
+  }
+}
+function isPlainObject2(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function tableIdProblems(value) {
+  if (!Array.isArray(value)) {
+    return [
+      `config.table_id must be an array, got ${describeValue(value)}. It is the table anchor, not the table id: [] for none, or one cell object such as [{"coordinate": "A1", "value": "<text in that cell>", "match_type": "any_text"}]. The table id goes on the command line, not in the body.`
+    ];
+  }
+  const out = [];
+  if (value.length > 1) {
+    out.push(
+      `config.table_id holds ${value.length} entries; the server allows at most one anchor ("Only one anchor is allowed").`
+    );
+  }
+  value.forEach((entry, i) => {
+    if (!isPlainObject2(entry)) {
+      out.push(`config.table_id[${i}] must be an object, got ${describeValue(entry)}.`);
+    } else if (typeof entry["match_type"] !== "string") {
+      out.push(
+        `config.table_id[${i}].match_type is required (a string such as "any_text" or "location").`
+      );
+    }
+  });
+  return out;
+}
+function validateMapperConfigShape(config) {
+  if (config === void 0) return;
+  if (!isPlainObject2(config)) {
+    throw new Error(`config must be a JSON object, got ${describeValue(config)}. ${GET_HINT}`);
+  }
+  const problems = [];
+  for (const key of OBJECT_LIST_KEYS) {
+    if (!(key in config)) continue;
+    const value = config[key];
+    if (key === "table_id") {
+      problems.push(...tableIdProblems(value));
+      continue;
+    }
+    if (!Array.isArray(value)) {
+      problems.push(`config.${key} must be an array of objects, got ${describeValue(value)}.`);
+      continue;
+    }
+    value.forEach((entry, i) => {
+      if (!isPlainObject2(entry)) {
+        problems.push(`config.${key}[${i}] must be an object, got ${describeValue(entry)}.`);
+      }
+    });
+  }
+  if ("include_sheets" in config && !Array.isArray(config["include_sheets"])) {
+    problems.push(
+      `config.include_sheets must be an array, got ${describeValue(config["include_sheets"])}.`
+    );
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      `invalid datamapper config (the server would answer an unattributed HTTP 500 / "Unknown error"):
+  - ${problems.join("\n  - ")}
+${GET_HINT}`
+    );
+  }
+}
+
 // src/commands/_errorLog.ts
 import { promises as fs14 } from "fs";
 import * as os3 from "os";
@@ -31289,6 +31379,7 @@ async function runPreviewData(cfg) {
     throw new Error("--payload-file is required");
   }
   let body = await readJsonPayload(payloadFile);
+  validateMapperConfigShape(body["config"]);
   const { decoded, changeCount } = decodeBodyEntitiesDeep(body);
   if (changeCount > 0) {
     body = decoded;
@@ -31485,7 +31576,12 @@ async function runDatamappersCreate(cfg) {
     parseKeyEqualsValue(cfg.flags.calcs, "--calc");
     parseKeyEqualsValue(cfg.flags.attrs, "--attr");
     parseKeyEqualsValue(cfg.flags.dims, "--dim");
-    parseKeyEqualsValue(cfg.flags.tableIdCells ?? [], "--table-id-cell");
+    const tableIdCells = parseKeyEqualsValue(cfg.flags.tableIdCells ?? [], "--table-id-cell");
+    if (tableIdCells.length > 1) {
+      throw new Error(
+        `--table-id-cell takes one cell; got ${tableIdCells.length}. The server allows one table anchor per mapper.`
+      );
+    }
     parseKeyEqualsValue(cfg.flags.footers, "--footer");
     parseKeyEqualsValue(cfg.flags.renames, "--rename");
   }
@@ -31493,6 +31589,7 @@ async function runDatamappersCreate(cfg) {
   let body;
   if (payloadFile !== "") {
     body = await readJsonPayload(payloadFile);
+    validateMapperConfigShape(body["config"]);
   } else {
     body = await buildConveniencePayload(
       cfg.client,
@@ -31590,6 +31687,7 @@ async function runDatamappersUpdate(cfg) {
   }
   const rescanValue = resolveRescan(cfg.rescan, cfg.noRescan);
   let body = await readJsonPayload(payloadFile);
+  validateMapperConfigShape(body["config"]);
   if (rescanValue === "") {
     delete body["rescan"];
   } else {
@@ -32229,7 +32327,7 @@ function registerDatamappersCommand(root) {
   addAccountFlag(dimensionCmd);
   const multipleCmd = addConvenienceFlags(
     createCmd.command("multiple").description(
-      "Create a multiple-tables datamapper (requires --dim \u2265 1 AND --table-id-cell \u2265 1)"
+      "Create a multiple-tables datamapper (requires --dim \u2265 1 AND one --table-id-cell)"
     ).argument("<table_id>", "Table ID (positive integer)")
   ).requiredOption(
     "--dim <Coord=Label>",
@@ -32238,7 +32336,7 @@ function registerDatamappersCommand(root) {
     []
   ).requiredOption(
     "--table-id-cell <Coord=Label>",
-    "Add table_id entry \u2014 points at the cell carrying a per-section table identifier. Repeatable; at least one is required.",
+    "The table_id (anchor) cell \u2014 the cell carrying the per-section table identifier. Required; the server allows exactly one.",
     collectArrayOpt,
     []
   ).action(async (tableIdStr, opts) => {
@@ -37502,22 +37600,68 @@ async function runFileboxSetVersionWorkflow(cfg) {
       `document ${cfg.docId} has no WORKFLOW tag in its config (available: ${availMsg})`
     );
   }
-  const tagsToUpdate = JSON.stringify([
-    { id: tag.id, value: cfg.status, name: "WORKFLOW", label: cfg.status }
-  ]);
-  const res = await setVersionTagsAndLabel(
-    cfg.client,
-    cfg.versionId,
-    { tags_to_update: tagsToUpdate },
-    { signal: cfg.signal }
-  );
-  if (res.status >= 200 && res.status < 300) {
-    cfg.out.write(`Set WORKFLOW tag on version ${cfg.versionId}: "${cfg.status}".
-`);
+  const err = cfg.err ?? process.stderr;
+  const { target } = await loadTargetVersion(cfg.client, cfg.docId, cfg.versionId, cfg.signal);
+  const current = tagValueOf(target.tags, tag.id);
+  const previous = typeof current === "string" ? current : null;
+  const writer = new FullTagSetWriter({
+    client: cfg.client,
+    docId: cfg.docId,
+    versionId: cfg.versionId,
+    snapshot: target.tags,
+    tag: { id: tag.id, value: cfg.status, name: tag.name, label: cfg.status },
+    action: "set version workflow",
+    signal: cfg.signal,
+    sleep: cfg.sleep,
+    settleMs: cfg.tagSettleDelayMs
+  });
+  await writer.write();
+  const kept = await keepDateTagValue({
+    writer,
+    seen: await writer.readBack(),
+    dateBefore: target.date_tag_value,
+    versionId: cfg.versionId,
+    docId: cfg.docId,
+    what: "WORKFLOW tag",
+    signal: cfg.signal,
+    err
+  });
+  const { seen, dateAfter, datePreserved } = kept;
+  const now = seen === null ? void 0 : tagValueOf(seen.tags, tag.id);
+  const verified = seen !== null && now === cfg.status;
+  if (seen === null) {
+    err.write(
+      `warning: could not read version ${cfg.versionId} back to verify its WORKFLOW tag \u2014 confirm with \`dr filebox versions ${cfg.docId}\`
+`
+    );
+  } else if (!verified) {
+    err.write(
+      `warning: version ${cfg.versionId} reads WORKFLOW ${JSON.stringify(now ?? null)} after the write, not "${cfg.status}" \u2014 confirm with \`dr filebox versions ${cfg.docId}\`
+`
+    );
+  }
+  if (cfg.asJson) {
+    writeJSONIndented(cfg.out, {
+      version_id: cfg.versionId,
+      doc_id: cfg.docId,
+      tag_id: tag.id,
+      previous,
+      status: cfg.status,
+      verified,
+      reapplied: kept.reapplied,
+      date_tag_value: dateAfter,
+      date_tag_value_preserved: datePreserved
+    });
     return;
   }
-  const body = await res.text();
-  throw new Error(`set version workflow refused (HTTP ${res.status}): ${body.trim()}`);
+  const verdict = !verified ? "unverified" : kept.reapplied ? "verified after one re-apply" : "verified";
+  cfg.out.write(
+    `Set WORKFLOW tag on version ${cfg.versionId}: ${JSON.stringify(previous ?? "(unset)")} -> "${cfg.status}" (${verdict}).
+`
+  );
+  if (datePreserved === false) {
+    cfg.out.write(dateNotPreservedLine(dateAfter, target.date_tag_value));
+  }
 }
 var FILE_STATUS_VALUES = ["Draft", "Final"];
 function parseFileStatus(raw) {
@@ -37618,6 +37762,110 @@ function fullTagSetWith(stored, write) {
   }
   return [...kept, write].sort((a, b) => a.id - b.id);
 }
+var FullTagSetWriter = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.base = cfg.snapshot ?? [];
+  }
+  cfg;
+  base;
+  /** PUT the full set; a non-2xx answer throws `TagWriteRefusedError`. */
+  async write() {
+    const { cfg } = this;
+    const res = await setVersionTagsAndLabel(
+      cfg.client,
+      cfg.versionId,
+      { tags_to_update: JSON.stringify(fullTagSetWith(this.base, cfg.tag)) },
+      { signal: cfg.signal }
+    );
+    if (res.status < 200 || res.status >= 300) {
+      const body = (await res.text()).trim();
+      throw new TagWriteRefusedError(
+        `${cfg.action} refused (HTTP ${res.status}): ${body}`,
+        `(HTTP ${res.status}): ${body}`
+      );
+    }
+  }
+  /** Wait the settle delay, then read the version back (`null` = unreadable). */
+  async readBack() {
+    const { cfg } = this;
+    const sleep3 = cfg.sleep ?? defaultCycleTagSleep;
+    await sleep3(cfg.settleMs ?? CYCLE_TAG_SETTLE_DELAY_MS, cfg.signal);
+    return readVersionForConfirm(cfg.client, cfg.versionId, cfg.docId, cfg.signal);
+  }
+  /** Build the next write from this read-back instead of the earlier snapshot. */
+  refreshBase(v) {
+    if (v !== null && v.tags.length > 0) {
+      this.base = v.tags;
+    }
+  }
+};
+async function keepDateTagValue(cfg) {
+  const { dateBefore, err } = cfg;
+  let seen = cfg.seen;
+  const dateMoved = (v) => v !== null && typeof dateBefore === "number" && v.row.date_tag_value !== void 0 && v.row.date_tag_value !== dateBefore;
+  let reapplied = false;
+  let dateUnknown = false;
+  if (dateMoved(seen)) {
+    err.write(
+      `warning: date_tag_value on version ${cfg.versionId} changed (${JSON.stringify(dateBefore)} -> ${JSON.stringify(seen.row.date_tag_value ?? null)}) when its ${cfg.what} was set; re-applying the full tag set once
+`
+    );
+    reapplied = true;
+    cfg.writer.refreshBase(seen);
+    let refused = false;
+    try {
+      await cfg.writer.write();
+    } catch (e) {
+      if (cfg.signal.aborted) {
+        throw e;
+      }
+      if (e instanceof TagWriteRefusedError) {
+        refused = true;
+        err.write(`warning: re-applying the full tag set was refused ${e.reason}
+`);
+      } else {
+        err.write(
+          `warning: re-applying the full tag set failed (${e instanceof Error ? e.message : String(e)}); its outcome is unknown, reading the version again
+`
+        );
+      }
+    }
+    const after = refused ? seen : await cfg.writer.readBack();
+    if (after === null) {
+      dateUnknown = true;
+      err.write(
+        `warning: could not read version ${cfg.versionId} back to confirm its date_tag_value after re-applying the full tag set \u2014 check it with \`dr filebox versions ${cfg.docId} --json\`
+`
+      );
+    } else {
+      seen = after;
+    }
+  }
+  const dateAfter = dateUnknown || seen === null || seen.row.date_tag_value === void 0 ? null : seen.row.date_tag_value;
+  const datePreserved = dateUnknown || seen === null || dateBefore === void 0 || seen.row.date_tag_value === void 0 ? null : !dateMoved(seen);
+  if (datePreserved === false) {
+    err.write(
+      `warning: date_tag_value on version ${cfg.versionId} is still ${JSON.stringify(dateAfter)} (was ${JSON.stringify(dateBefore)}) after one re-apply; its tags still carry the date. Restore it with \`dr filebox set-version-date-tag ${cfg.versionId} --doc ${cfg.docId} --<dimension> <date>\` (it sends the date tag alone; on a planning filebox use \`dr filebox set-version-cycle ${cfg.versionId} --doc ${cfg.docId} --date <date> --scenario <name>\` instead, which keeps the cycle), then check \`dr filebox versions ${cfg.docId} --json\`
+`
+    );
+  }
+  return { seen, reapplied, dateAfter, datePreserved };
+}
+function dateNotPreservedLine(dateAfter, dateBefore) {
+  return `date_tag_value NOT preserved: it reads ${JSON.stringify(dateAfter)}, was ${JSON.stringify(dateBefore)} (see the warning above).
+`;
+}
+async function loadTargetVersion(client, docId, versionId, signal) {
+  const rows = await listVersions(client, docId, { includeAutoSaves: true }, { signal });
+  const target = rows.find((r) => r.id === versionId);
+  if (target === void 0) {
+    throw new Error(
+      `version ${versionId} is not a version of filebox ${docId} \u2014 list them with \`dr filebox versions ${docId} --all\``
+    );
+  }
+  return { rows, target };
+}
 async function runFileboxSetVersionFileStatus(cfg) {
   if (cfg.docId <= 0) {
     throw new Error("document id must be positive");
@@ -37626,8 +37874,6 @@ async function runFileboxSetVersionFileStatus(cfg) {
     throw new Error("version id must be positive");
   }
   const err = cfg.err ?? process.stderr;
-  const sleep3 = cfg.sleep ?? defaultCycleTagSleep;
-  const settleMs = cfg.tagSettleDelayMs ?? CYCLE_TAG_SETTLE_DELAY_MS;
   const details = await getDetails(cfg.client, cfg.docId, { signal: cfg.signal });
   const tag = (details.tags_config ?? []).find(isFileStatusTag);
   if (tag === void 0) {
@@ -37641,18 +37887,12 @@ async function runFileboxSetVersionFileStatus(cfg) {
       `File Status on document ${cfg.docId} does not allow "${cfg.status}" (allowed: ${tag.values.map((v) => JSON.stringify(v)).join(" | ")})`
     );
   }
-  const rows = await listVersions(
+  const { rows, target } = await loadTargetVersion(
     cfg.client,
     cfg.docId,
-    { includeAutoSaves: true },
-    { signal: cfg.signal }
+    cfg.versionId,
+    cfg.signal
   );
-  const target = rows.find((r) => r.id === cfg.versionId);
-  if (target === void 0) {
-    throw new Error(
-      `version ${cfg.versionId} is not a version of filebox ${cfg.docId} \u2014 list them with \`dr filebox versions ${cfg.docId} --all\``
-    );
-  }
   const current = tagValueOf(target.tags, tag.id);
   const previous = typeof current === "string" ? current : null;
   const options = tag.options ?? {};
@@ -37705,45 +37945,25 @@ async function runFileboxSetVersionFileStatus(cfg) {
       );
     }
   }
-  const statusWrite = {
-    id: tag.id,
-    value: cfg.status,
-    name: tag.name,
-    label: cfg.status
-  };
-  let base = target.tags ?? [];
-  const refreshBase = (v) => {
-    if (v !== null && v.tags.length > 0) {
-      base = v.tags;
-    }
-  };
-  const write = async () => {
-    const res = await setVersionTagsAndLabel(
-      cfg.client,
-      cfg.versionId,
-      { tags_to_update: JSON.stringify(fullTagSetWith(base, statusWrite)) },
-      { signal: cfg.signal }
-    );
-    if (res.status < 200 || res.status >= 300) {
-      const body = await res.text();
-      throw new TagWriteRefusedError(
-        `set version file status refused (HTTP ${res.status}): ${body.trim()}`,
-        `(HTTP ${res.status}): ${body.trim()}`
-      );
-    }
-  };
-  const readBack = async () => {
-    await sleep3(settleMs, cfg.signal);
-    return readVersionForConfirm(cfg.client, cfg.versionId, cfg.docId, cfg.signal);
-  };
-  await write();
+  const writer = new FullTagSetWriter({
+    client: cfg.client,
+    docId: cfg.docId,
+    versionId: cfg.versionId,
+    snapshot: target.tags,
+    tag: { id: tag.id, value: cfg.status, name: tag.name, label: cfg.status },
+    action: "set version file status",
+    signal: cfg.signal,
+    sleep: cfg.sleep,
+    settleMs: cfg.tagSettleDelayMs
+  });
+  await writer.write();
   let reapplied = false;
-  let seen = await readBack();
+  let seen = await writer.readBack();
   if (seen !== null && tagValueOf(seen.tags, tag.id) !== cfg.status) {
     reapplied = true;
-    refreshBase(seen);
-    await write();
-    seen = await readBack();
+    writer.refreshBase(seen);
+    await writer.write();
+    seen = await writer.readBack();
     const now = seen === null ? void 0 : tagValueOf(seen.tags, tag.id);
     if (seen !== null && now !== cfg.status) {
       throw new Error(
@@ -37751,53 +37971,19 @@ async function runFileboxSetVersionFileStatus(cfg) {
       );
     }
   }
-  const dateBefore = target.date_tag_value;
-  const dateMoved = (v) => v !== null && typeof dateBefore === "number" && v.row.date_tag_value !== void 0 && v.row.date_tag_value !== dateBefore;
-  let dateUnknown = false;
-  if (dateMoved(seen)) {
-    err.write(
-      `warning: date_tag_value on version ${cfg.versionId} changed (${JSON.stringify(dateBefore)} -> ${JSON.stringify(seen.row.date_tag_value ?? null)}) when its File Status was set; re-applying the full tag set once
-`
-    );
-    reapplied = true;
-    refreshBase(seen);
-    let refused = false;
-    try {
-      await write();
-    } catch (e) {
-      if (cfg.signal.aborted) {
-        throw e;
-      }
-      if (e instanceof TagWriteRefusedError) {
-        refused = true;
-        err.write(`warning: re-applying the full tag set was refused ${e.reason}
-`);
-      } else {
-        err.write(
-          `warning: re-applying the full tag set failed (${e instanceof Error ? e.message : String(e)}); its outcome is unknown, reading the version again
-`
-        );
-      }
-    }
-    const after = refused ? seen : await readBack();
-    if (after === null) {
-      dateUnknown = true;
-      err.write(
-        `warning: could not read version ${cfg.versionId} back to confirm its date_tag_value after re-applying the full tag set \u2014 check it with \`dr filebox versions ${cfg.docId} --json\`
-`
-      );
-    } else {
-      seen = after;
-    }
-  }
-  const dateAfter = dateUnknown || seen === null || seen.row.date_tag_value === void 0 ? null : seen.row.date_tag_value;
-  const datePreserved = dateUnknown || seen === null || dateBefore === void 0 || seen.row.date_tag_value === void 0 ? null : !dateMoved(seen);
-  if (datePreserved === false) {
-    err.write(
-      `warning: date_tag_value on version ${cfg.versionId} is still ${JSON.stringify(dateAfter)} (was ${JSON.stringify(dateBefore)}) after one re-apply; its tags still carry the date. Restore it with \`dr filebox set-version-date-tag ${cfg.versionId} --doc ${cfg.docId} --<dimension> <date>\` (it sends the date tag alone; on a planning filebox use \`dr filebox set-version-cycle ${cfg.versionId} --doc ${cfg.docId} --date <date> --scenario <name>\` instead, which keeps the cycle), then check \`dr filebox versions ${cfg.docId} --json\`
-`
-    );
-  }
+  const kept = await keepDateTagValue({
+    writer,
+    seen,
+    dateBefore: target.date_tag_value,
+    versionId: cfg.versionId,
+    docId: cfg.docId,
+    what: "File Status",
+    signal: cfg.signal,
+    err
+  });
+  seen = kept.seen;
+  reapplied ||= kept.reapplied;
+  const { dateAfter, datePreserved } = kept;
   if (seen === null) {
     err.write(
       `warning: could not read version ${cfg.versionId} back to verify its File Status \u2014 confirm with \`dr filebox versions ${cfg.docId}\`
@@ -37836,10 +38022,7 @@ async function runFileboxSetVersionFileStatus(cfg) {
 `
   );
   if (datePreserved === false) {
-    cfg.out.write(
-      `date_tag_value NOT preserved: it reads ${JSON.stringify(dateAfter)}, was ${JSON.stringify(dateBefore)} (see the warning above).
-`
-    );
+    cfg.out.write(dateNotPreservedLine(dateAfter, target.date_tag_value));
   }
   if (demotedIds.length > 0) {
     cfg.out.write(
@@ -39537,33 +39720,41 @@ function registerFileboxCommand(root) {
   ).requiredOption(
     "--status <s>",
     "New WORKFLOW value: Not Started | In Progress | Pending | Approved | Rejected. Setting Approved requires the `approve_workflow` permission server-side."
-  ).action(async (idStr, opts) => {
-    const versionId = parseFileboxIdArg(idStr);
-    if (opts.doc === void 0 || opts.doc === "") {
-      throw new Error("--doc is required");
-    }
-    const docId = parseFileboxIdArg(opts.doc);
-    const raw = opts.status ?? "";
-    if (!WORKFLOW_STATUSES.includes(raw)) {
-      throw new Error(
-        `invalid --status "${raw}" (expected one of: ${WORKFLOW_STATUSES.map((s) => `"${s}"`).join(" | ")})`
-      );
-    }
-    const status2 = raw;
-    const setup = await setupCall(opts.server, opts.account);
-    try {
-      await runFileboxSetVersionWorkflow({
-        client: setup.client,
-        docId,
-        versionId,
-        status: status2,
-        signal: setup.signal,
-        out: process.stdout
-      });
-    } finally {
-      setup.cleanup();
+  ).option(
+    "--json",
+    "Output a JSON record describing the write instead of the human confirmation",
+    false
+  ).action(
+    async (idStr, opts) => {
+      const versionId = parseFileboxIdArg(idStr);
+      if (opts.doc === void 0 || opts.doc === "") {
+        throw new Error("--doc is required");
+      }
+      const docId = parseFileboxIdArg(opts.doc);
+      const raw = opts.status ?? "";
+      if (!WORKFLOW_STATUSES.includes(raw)) {
+        throw new Error(
+          `invalid --status "${raw}" (expected one of: ${WORKFLOW_STATUSES.map((s) => `"${s}"`).join(" | ")})`
+        );
+      }
+      const status2 = raw;
+      const setup = await setupCall(opts.server, opts.account, { timeoutMs: 5 * 6e4 });
+      try {
+        await runFileboxSetVersionWorkflow({
+          client: setup.client,
+          docId,
+          versionId,
+          status: status2,
+          asJson: opts.json === true,
+          signal: setup.signal,
+          out: process.stdout,
+          err: process.stderr
+        });
+      } finally {
+        setup.cleanup();
+      }
     }
-  });
+  );
   addServerFlag(setVersionWorkflowCmd);
   addAccountFlag(setVersionWorkflowCmd);
   const setVersionFileStatusCmd = fb.command("set-version-file-status").description(
@@ -56637,7 +56828,7 @@ async function readHiddenRulesPayload(path12) {
   raw.forEach((entry, idx) => {
     const ctx = `rules[${idx}]`;
     const base = validateCreate(entry, ctx);
-    if (!isPlainObject2(entry)) {
+    if (!isPlainObject3(entry)) {
       throw new Error(`--file: ${ctx} must be a JSON object`);
     }
     const ctxnId = entry["customer_transaction_id"];
@@ -56696,11 +56887,11 @@ function parseReorderShorthand(raw) {
   }
   return { rules: entries };
 }
-function isPlainObject2(v) {
+function isPlainObject3(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 function validateCreate(raw, ctx) {
-  if (!isPlainObject2(raw)) {
+  if (!isPlainObject3(raw)) {
     throw new Error(`--file: ${ctx} must be a JSON object`);
   }
   if (!Array.isArray(raw["conditions"]) || raw["conditions"].length === 0) {
@@ -56756,7 +56947,7 @@ function validateCreate(raw, ctx) {
   return out;
 }
 function validateCondition(raw, ctx) {
-  if (!isPlainObject2(raw)) {
+  if (!isPlainObject3(raw)) {
     throw new Error(`--file: ${ctx} must be a JSON object`);
   }
   const inputField = raw["input_field"];
@@ -56821,7 +57012,7 @@ function validateArgsForOperation(op, args, ctx) {
   }
 }
 function validateReorder(raw, ctx) {
-  if (!isPlainObject2(raw)) {
+  if (!isPlainObject3(raw)) {
     throw new Error(`--file: ${ctx} must be a JSON object`);
   }
   if (!Array.isArray(raw["rules"]) || raw["rules"].length === 0) {
@@ -56830,7 +57021,7 @@ function validateReorder(raw, ctx) {
   const seenIds = /* @__PURE__ */ new Set();
   const entries = [];
   raw["rules"].forEach((entry, idx) => {
-    if (!isPlainObject2(entry)) {
+    if (!isPlainObject3(entry)) {
       throw new Error(`--file: ${ctx}.rules[${idx}] must be a JSON object`);
     }
     const id = entry["id"];

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.121",
+  "cliVersion": "1.6.123",
   "_contract": "Resolve a command path through `aliases` (canonical prefix + alias segment -> canonical path) before any lookup. A path listed in `pendingCommands`, or whose first segment is a key of `pending`, is UNDECIDED, not unrestricted: fail closed or skip it, and never read a path's absence from `commands` as 'no requirement'. An entry carrying `denied` is UNAVAILABLE to any AGENT-SCOPED credential — one whose `scopes` claim carries at least one `resource:action` entry; a claim that is absent, empty, capability-only or wholly unparseable is UNRESTRICTED, and this mark does not apply to it — whatever else that entry says: it is not a ceiling and it is not always-available, its `denied.reason` says why and `denied.until` names the ticket that lifts it, and the absence of `requires` on it must NEVER be read as 'no requirement'. Only an entry in `commands` with an empty `requires` means always-available.",
   "commands": {
     "login": {

package/dist/skills/dr-cli/reference/datamappers.md

@@ -26,7 +26,8 @@ the matching subcommand. `datamappers create <flat|dimension|multiple|from-file>
   `--version` — `--version` is reserved by the global `dr --version` and silently
   no-ops the subcommand.
 - `dimension` adds required `--dim Coord=Label` (≥1).
-- `multiple` adds required `--dim` and `--table-id-cell Coord=Label` (≥1).
+- `multiple` adds required `--dim` and one `--table-id-cell Coord=Label` (the
+  server allows a single table anchor; a second one is refused).
 - `from-file --file <path>` is the power mode — it ships the JSON body without
   the convenience-flag validation, but **not** strictly verbatim. Three things
   still rewrite it: `--rescan`/`--no-rescan` set or strip `rescan`; a source
@@ -35,6 +36,27 @@ the matching subcommand. `datamappers create <flat|dimension|multiple|from-file>
   Required body fields: `name`, `document_version_id`, `selected_document_ids`
   (GET returns this renamed as `mapped_documents_ids`), `config`, `sheet_name`.
 
+**`config` shape: `table_id` is not the table id (DR-54216).** `config.table_id`
+is the table *anchor*: `[]` for none (what `datamappers get --json` emits), or a
+list with exactly one cell object, e.g.
+`[{"coordinate": "A1", "value": "<text in that cell>", "match_type": "any_text"}]`.
+The table id goes on the command line. The server does not check `config`, so a
+wrong type gets a bare HTTP 500 on create and "Unknown error while processing
+data for preview" on preview, with no field named. `create` (payload-file /
+from-file), `update` and `preview` therefore check these keys before sending and
+fail naming the field:
+
+| Key | Must be |
+|-----|---------|
+| `table_id` | array of at most one object, with a `match_type` string |
+| `header`, `dimension`, `footer`, `attributes` | array of cell objects |
+| `calculated_fields`, `fx_conversions` | array of objects |
+| `include_sheets` | array |
+
+An absent key is fine; `null`, a number, a string or a list of strings is not.
+Writing a body from scratch, start from `datamappers get <mapper_id> --json` of a
+similar mapper.
+
 **Ordinal: mappers that share one are versions of one mapper.** Each mapper has
 an `ordinal` (the ORDINAL column of `datamappers list --table <id>`). The server
 binds documents per (table, ordinal): binding a mapper to a document moves that

package/dist/skills/dr-cli/reference/filebox-documents.md

@@ -170,8 +170,16 @@ set-version-include` (below).
   control characters, and not `auto-calculated` (reserved by the server for
   versions it generates); pass the label as one quoted argument. Needs change
   rights on the filebox or to be the version's uploader (HTTP 405 otherwise).
-- `filebox set-version-workflow <vid> --doc <id> --status <Not Started|In Progress|Pending|Approved|Rejected>`
-  — set the workflow LIST-tag value (setting `Approved` requires `approve_workflow`).
+- `filebox set-version-workflow <vid> --doc <id> --status <Not Started|In Progress|Pending|Approved|Rejected>
+  [--json]` — set the workflow LIST-tag value (setting `Approved` requires
+  `approve_workflow`). Like `set-version-file-status` below, it sends the
+  version's **full tag set** with WORKFLOW replaced, and reads the version back:
+  the WORKFLOW value is checked, and `date_tag_value` is re-applied once and
+  reported exactly as that command does (`date_tag_value`,
+  `date_tag_value_preserved`, `verified`, `reapplied` and `previous` in
+  `--json`). A WORKFLOW-only body (CLI releases before DR-55186) left the
+  version's `date_tag_value` null while `tags` still held the month; repair such
+  a version the way the `set-version-file-status` entry describes.
 - `filebox set-version-file-status <vid> --doc <id> --status <Draft|Final> [--json]`
   — set the File Status LIST-tag value (other tags untouched). This is how a
   version uploaded with `upload-version` (always Draft) is made Final without the
@@ -226,6 +234,11 @@ set-version-include` (below).
   tag's `sub_type`/name; a forecast filebox's `Forecast (New)` tag has none, so
   only the tag's presence is checked there. The scenario tag is compared
   exactly.
+  It sends those two tags only, and the server rebuilds the version's
+  dimension value from them. That is right when the filebox's dimension tags
+  are exactly the date and the scenario, as on the planning fileboxes this
+  command is for; a third dimension tag would drop out of the dimension.
+  `upload-version --date --scenario` writes the same two-tag body.
   On an upload the confirmed row is also cross-checked against the upload
   response (version number, name, filebox) — if the response only carried a
   `latest_version_id` the cascade had already moved, the tag went to the wrong

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.121",
+  "version": "1.6.123",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {