@datarails-ai/dr-cli 1.6.120 → 1.6.122

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.120",
+  version: "1.6.122",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -69,7 +69,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-12T10:19:56.130Z";
+var BUILD_TIME = "2026-10-12T10:51:59.680Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -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) => {
@@ -37590,6 +37688,34 @@ function requireTagPermission(details, perm, docId, action) {
     );
   }
 }
+var TagWriteRefusedError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "TagWriteRefusedError";
+  }
+  reason;
+};
+function fullTagSetWith(stored, write) {
+  const kept = [];
+  for (const raw of stored ?? []) {
+    if (typeof raw !== "object" || raw === null) {
+      continue;
+    }
+    const t = raw;
+    const id = typeof t.id === "string" && t.id.trim() !== "" ? Number(t.id) : t.id;
+    if (typeof id !== "number" || !Number.isInteger(id) || id === write.id || kept.some((k) => k.id === id) || t.value === void 0 || t.value === null) {
+      continue;
+    }
+    kept.push({
+      id,
+      value: t.value,
+      ...typeof t.name === "string" ? { name: t.name } : {},
+      ...typeof t.label === "string" ? { label: t.label } : {}
+    });
+  }
+  return [...kept, write].sort((a, b) => a.id - b.id);
+}
 async function runFileboxSetVersionFileStatus(cfg) {
   if (cfg.docId <= 0) {
     throw new Error("document id must be positive");
@@ -37644,6 +37770,8 @@ async function runFileboxSetVersionFileStatus(cfg) {
         changed: false,
         verified: true,
         reapplied: false,
+        date_tag_value: target.date_tag_value ?? null,
+        date_tag_value_preserved: true,
         demoted_version_ids: [],
         rescan_queued: false
       });
@@ -37675,19 +37803,31 @@ async function runFileboxSetVersionFileStatus(cfg) {
       );
     }
   }
-  const tagsToUpdate = JSON.stringify([
-    { id: tag.id, value: cfg.status, name: tag.name, label: cfg.status }
-  ]);
+  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: tagsToUpdate },
+      { 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 Error(`set version file status refused (HTTP ${res.status}): ${body.trim()}`);
+      throw new TagWriteRefusedError(
+        `set version file status refused (HTTP ${res.status}): ${body.trim()}`,
+        `(HTTP ${res.status}): ${body.trim()}`
+      );
     }
   };
   const readBack = async () => {
@@ -37699,6 +37839,7 @@ async function runFileboxSetVersionFileStatus(cfg) {
   let seen = await readBack();
   if (seen !== null && tagValueOf(seen.tags, tag.id) !== cfg.status) {
     reapplied = true;
+    refreshBase(seen);
     await write();
     seen = await readBack();
     const now = seen === null ? void 0 : tagValueOf(seen.tags, tag.id);
@@ -37708,6 +37849,53 @@ 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\`
+`
+    );
+  }
   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}\`
@@ -37733,6 +37921,8 @@ async function runFileboxSetVersionFileStatus(cfg) {
       changed: true,
       verified,
       reapplied,
+      date_tag_value: dateAfter,
+      date_tag_value_preserved: datePreserved,
       demoted_version_ids: demotedIds,
       rescan_queued: true
     });
@@ -37743,6 +37933,12 @@ async function runFileboxSetVersionFileStatus(cfg) {
     `Set File Status on version ${cfg.versionId}: ${JSON.stringify(previous ?? "(unset)")} -> "${cfg.status}" (${verdict}).
 `
   );
+  if (datePreserved === false) {
+    cfg.out.write(
+      `date_tag_value NOT preserved: it reads ${JSON.stringify(dateAfter)}, was ${JSON.stringify(dateBefore)} (see the warning above).
+`
+    );
+  }
   if (demotedIds.length > 0) {
     cfg.out.write(
       `Only one version per period can be ${cfg.status}: ${plural2(demotedIds.length, "version", "versions")} ${demotedIds.join(", ")} ${plural2(demotedIds.length, "was", "were")} moved to Draft by the server.
@@ -56539,7 +56735,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"];
@@ -56598,11 +56794,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) {
@@ -56658,7 +56854,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"];
@@ -56723,7 +56919,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) {
@@ -56732,7 +56928,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.120",
+  "cliVersion": "1.6.122",
   "_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

@@ -154,7 +154,11 @@ set-version-include` (below).
 
 - `filebox set-version-date-tag <vid> --doc <id> --month|--quarter|--day|--year|--week …
   [--json]` — set the date tag on one version (resolves the tag id from the doc's
-  config; other tags untouched).
+  config; other tags untouched in `tags`). It sends the date tag alone, and the
+  server rebuilds the version's dimension value from the submitted tags, so on
+  a filebox with a second dimension tag (a cycle or plan LIST tag) that tag
+  drops out of the dimension. On a planning filebox use `set-version-cycle`,
+  which sends the date and the cycle together.
 - `filebox set-version-label <vid> --label "<text>" | --clear [--json]` — set or
   remove a version's free-text label; name, date and dimension tags are
   untouched, and a locked date tag does not block it. No confirm step. Address it
@@ -176,6 +180,27 @@ set-version-include` (below).
   moves that version to Draft (the output names it). The status is read back and
   re-applied once if it did not stick. The write queues a rescan of the version,
   so mapped tables show the new `File Status` only after it finishes.
+  Like the UI, it sends the version's **full tag set** with File Status
+  replaced, not File Status alone. The server merges the submitted tags into
+  `tags` but rebuilds the version's dimension value, and with it the
+  `date_tag_value` that `filebox versions --json` shows, from the submitted tags
+  only. A File Status-only body (CLI releases before DR-54157) therefore left
+  `date_tag_value` null while `tags` still held the month. That is not harmless:
+  the server uses the dimension value to pick the latest version per period, to
+  apply date locks and in rescan events. The command reads `date_tag_value` back,
+  re-applies the full set once if it changed, and otherwise reports it: a stderr
+  warning, a `date_tag_value NOT preserved` line, and
+  `date_tag_value_preserved: false` in `--json`. `--json` also returns
+  `date_tag_value`, and `date_tag_value_preserved: null` when the server does
+  not serve it. **To repair a version left with a null date**, run
+  `set-version-date-tag` with the period its `tags` hold. That writes the date
+  tag, and the server rebuilds the dimension from it. It sends the date tag
+  alone, so use it only when the date is the filebox's only dimension tag. On a
+  planning filebox, run `set-version-cycle` with the version's existing date
+  and scenario instead, which sends both. Re-running
+  `set-version-file-status` with the same status does not repair it, because
+  it writes nothing. A real status change does restore it, because it re-sends
+  the date tag.
 - `filebox set-version-cycle <vid> --doc <id> --date <date> --scenario <name>
   [--date-tag-name <n>] [--json]` — **forecast/budget (planning) fileboxes only.**
   Sets the cycle date tag and the scenario LIST-tag together (both flags

package/package.json

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