@datarails-ai/dr-cli 1.6.105 → 1.6.107

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.105",
+  "cliVersion": "1.6.107",
   "_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": {
@@ -739,6 +739,26 @@
         }
       ]
     },
+    "functions data": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "read"
+        }
+      ]
+    },
+    "functions drilldown": {
+      "requires": [
+        {
+          "resource": "tables",
+          "action": "read"
+        },
+        {
+          "resource": "dashboards",
+          "action": "read"
+        }
+      ]
+    },
     "functions delete": {
       "requires": [
         {

package/dist/skills/dr-cli/SKILL.md

@@ -239,7 +239,11 @@ area's gotchas.
 - `metrics suggestions list|refresh` + `metrics dimensions suggestions list|refresh` — AI suggestion agents (list shows suggestions + `last_run` status; `refresh` triggers a run, `--wait [--timeout <s>]` polls to completion). Gated per-org by Unleash flags; a successful `metrics migrate` auto-triggers both agents, so a 409 from `refresh` right after usually means it's already running — check `list`.
 - `metrics suggestions profile` — read-only: profiles every table and returns, per table, the `reporting_axis` (WHICH date column a BASE metric should bucket by, with `chosen_by` naming the rule), `row_grain.reads_as` (`movements` -> time_aggregation SUM, `balances` -> EOP), candidate `measures`, `categoricals`, and the metrics already defined there. Use this BEFORE proposing any metric: `date_field` cannot be read off the payload (no field marks the reporting column) and guessing it produces a silently wrong number that passes validation. `reporting_axis: null` and `reads_as: "unknown"` are real answers - do not substitute a guess. All measure statistics are SAMPLED from storage-ordered windows and named `sampled_*`; there is deliberately no sum/avg. Needs no Unleash flag. ~30s and ~230 requests on a 43-table org.
 - `metrics dimensions suggestions profile` — read-only: profiles every table/field and returns scored candidate dimension groups (value-overlap grouping, existing-dimension dedupe, machine-readable rejection reasons) in ONE call. Use this instead of looping `templates distinct` per field when reasoning about what dimensions an org should have. Needs no Unleash flag. `--json` for the payload, `--out <file>` when only `summary`/`groups` matter, `--suppression <file>` when you already hold the existing-dimension and dismissed lists. Also emits `near_misses` — pairs just under the merge threshold, for you to judge rather than silently dropped.
-- `functions list|get|create|update|delete|set-filters` — a function's **definition** only.
+- `functions list|get|create|update|delete|set-filters` — a function's **definition**.
+- `functions data <id> --filter "F=V1,V2" --date "Reporting Date=2025-01-31" [--agg YTD]` — the
+  function's **live value**, computed by the same endpoint the Excel add-in uses for
+  `DR.GET`/`DR.YTD`; `functions drilldown <id> … [--out rows.csv]` — the rows behind it.
+  `create`/`update --date-field <Date field>` is required for YTD/QTD/MTD to work.
   - _`set-filters <id> --file <json> [--confirm]` is the **only** way to author a
     function's row-level filters (create/update don't touch them). FULL REPLACE —
     an empty array clears all; dimension `values` are a plain list, date filters
@@ -552,8 +556,9 @@ returns the source rows behind the number.
 counts — and a token; re-run with `--confirm-token` to fire it) → poll `scans
 status` again. This is a **full historical** rescan (every calc field × every
 version). To only pick up a datamapper change on the live template, prefer
-`datamappers update <id> --rescan latest` (latest version of the mapper's bound
-documents only) — far cheaper and lower-blast.
+`datamappers update <id> --payload-file <p> --rescan latest` (latest version of
+the mapper's bound documents only) — far cheaper and lower-blast. It publishes a
+new mapper version, so the mapper gets a **new id**, which dr prints.
 
 **Build a `create` body from plain-English intent** (calc models, datamappers,
 metrics): you resolve names → integer IDs yourself against the tenant

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

@@ -67,12 +67,23 @@ value-inference behavior. `NAME` is the target **table field** name (the
 ## Update / preview / bind / delete
 
 - `datamappers update`, `datamappers delete` (two-step confirm).
-- `datamappers update --rescan latest` — after the PUT, dr watches the
-  template's scan status for up to 30s, because servers without the DR-54200 fix
-  save the config but ignore `rescan: "latest"`. If no new scan shows up, it
-  prints a warning with a ready `datamappers bind <id> --doc … --rescan latest`
-  command. Run `scans status <template_id>` first: the scan may only be queued,
-  and `bind` on a queued scan starts a second one. Don't re-run `update`.
+- `datamappers update <id> --payload-file <p>` publishes the payload as a **new
+  version** of the mapper, the same request the UI's "Publish and scan" sends
+  (`POST /api/templates/<tid>/mappers` with `datamapper_id` = the old id). The
+  server adds any new columns to the table, binds the new version to the old
+  one's documents, unbinds the old one, and rescans (`--rescan latest` by
+  default). The payload needs `config` and `sheet_name`; dr fills in `name`,
+  `ordinal`, the bound documents and the source version from the old mapper,
+  and any of those keys in the payload wins.
+- **The mapper gets a new id.** dr prints it (`note: mapper <old> was published
+  as new version <new>`). Use the new id for the next update, and keep an
+  old→new log if anything outside the table refers to the mapper id.
+  `update` refuses an old id that is bound to no documents, and points at
+  `datamappers list --table <tid>` for the current one.
+- A mapper made by an org import or template push has no source version on
+  record, and `update` stops with an error. Add `"document_version_id"` to the
+  payload: an ACTIVE version of one of its documents, with a `sheet_name` that
+  exists in it.
 - `datamappers preview --payload-file <p>` — renders mapper output for sample
   input ("what would this extract?") before saving.
 - `datamappers bind <mapper_id> --doc <id> [--rescan latest|all]` — change which
@@ -82,15 +93,15 @@ value-inference behavior. `NAME` is the target **table field** name (the
 
 `datamappers update <id> --payload-file <p> [--field NAME:TYPE ...]`. Repeatable;
 `TYPE` is `Text|Float|Date|Integer`. Each `--field` becomes a `fields_to_change`
-entry on the PUT body, telling the server to set that column's type **explicitly**
+entry in the body, telling the server to set that column's type **explicitly**
 instead of inferring it — this is exactly what the web UI's "Publish and scan"
-does (same `PUT api/templates/mappers/<id>` endpoint; the only payload difference
-is `fields_to_change`).
+does (same `POST api/templates/<tid>/mappers` endpoint; the only payload
+difference is `fields_to_change`).
 
 **When you need it:** adding a calc column that multiplies/divides by a
 **LUT-injected column**. LUT columns land as **Text**; the server infers Text for
 them, so a formula like `[Posting Amount] * [Sign]` fails to materialise and the
-PUT returns a bare `HTTP 500` (`ETLError: … incorrect formula syntax`) — even
+publish returns a bare `HTTP 500` (`ETLError: … incorrect formula syntax`) — even
 though the formula is valid. Fixing the LUT column's type up-front lets it
 materialise:
 
@@ -120,12 +131,12 @@ valid formula the ETL compiler can't resolve (unknown/wrong-cased function,
 unresolvable `[field]` reference, a string-constant that happens to be quoted)
 still returns a bare 500.
 
-After `create`, the CLI polls the template's `fields[]` for up to 30s for every
+After `create` and `update`, the CLI polls the template's `fields[]` for up to 30s for every
 declared calc field to materialise, and warns (pointing at `mapper-recipes get`
 for working formulas) if any are missing — this catches the EOMONTH failure
 mode. Skipped when `--no-rescan` is set.
 
-On a PUT 500, the CLI writes a `dr-cli-error-<timestamp>.md` to the cwd capturing
+On a create or update 500, the CLI writes a `dr-cli-error-<timestamp>.md` to the cwd capturing
 URL + status + request/response bodies; the path is named in the stderr error.
 
 Formula syntax:

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

@@ -12,7 +12,7 @@ Write:
 
 - `integrations add` (payload-file), `integrations sync`,
   `integrations test-connection`, `integrations update`,
-  `integrations delete` (two-step confirm).
+  `integrations delete` (two-step confirm, Tier A, see below).
 - `integrations revoke <id>` (two-step confirm; Tier A on prod) — Disconnect a
   `DatarailsConnector` OAuth data source: `POST /api/v2/data_integrations/<id>/revoke`.
   The grant is cleared locally first (`oauth_tokens`/`oauth_pending` dropped,
@@ -23,6 +23,38 @@ Write:
   `revoked` may leave the grant live at the vendor. Legacy vendors are refused.
 - `integrations share users` / `integrations share groups`.
 
+### Deleting a data source (`integrations delete <id>`)
+
+`DELETE /api/v3/data_integrations/<id>/`. It cannot be undone and **cascades to queries and
+documents**. Typical use: removing a validation or staging datasource that holds live customer
+credentials once its bindings are gone.
+
+1. **Plan:** run it without a token, as the identity that owns the data source (on a staging org,
+   the impersonated staging user, never the operator):
+   `dr integrations delete <id> --server <S> --account <user>`. It prints `name`, `type`, `status`,
+   `org` (name + id) and `shared` (user/group counts), plus the exact confirm command with a token
+   that expires in **10 minutes** and is bound to this id and verb. Check the org id and the name
+   before going on: the plan does **not** list the queries and documents the cascade will remove.
+   Make sure nothing you want to keep still points at this data source.
+2. **Relay and get a "yes"**: name, org and why it is being deleted.
+3. **Confirm:** re-run the printed command with `--confirm-token <tok>`. On a prod tenant (`US`,
+   `US2`, `UK`, `CA`, `EU`, `STUDIO`, `DEMO`) this is **Tier A**: the binary shows a fresh word in a
+   desktop dialog (or a TTY prompt) and a human must type it. With no interactive channel it exits
+   non-zero; hand the printed line to the user rather than retrying. Success prints
+   `Deleted integration <id> — "<name>".`
+4. **Verify:** `dr integrations get <id> --server <S> --account <user>` returns `HTTP 404`.
+
+Notes:
+
+- `dr connectors` `Connector` rows that reference the data source (`--secret-ref`) are **not**
+  deleted, and dr-cli has no connector delete. Delete the `dr connectors` bindings first
+  (`dr connectors query delete`), then record the orphaned connector id.
+- A `403` (`delete refused: …`) means the identity can't delete it: switch to the owner's account,
+  not to the operator.
+- Deleting a validation data source on the Workato-migration staging orgs left the staging fileboxes
+  in place (their data-query rows pointed at the data source). Check one with `dr filebox get` after
+  the delete if you need them as evidence.
+
 ## IT-admin file-sync (`integrations it`)
 
 File-sync connectors only — OneDrive / SharePoint / Egnyte. Output redacts

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

@@ -478,11 +478,10 @@ dr metrics dimensions suggestions profile -s DEV --account support@acme.com --js
     51-table org. Read `summary.empty_unverified` as "at least this many
     fields' emptiness is unproven", not as an exact census.
 
-## Functions (DR.GET definitions)
+## Functions (DR.GET definitions and values)
 
 - `functions list`, `functions get <id>` — `get` returns the **definition**,
-  **not** the live value. Live function values are computed in Excel via
-  `DR.GET(...)` through the add-in and are not exposed by this CLI.
+  not the value (for the value see `functions data` below).
   - The core row is `id / name / agg / template / value_field`; below it `get`
     prints a **FILTERS** section (one row per persisted filter: `field`, `name`,
     `type`, `excluded`, `values`) and the **default agg date field** when set.
@@ -492,6 +491,18 @@ dr metrics dimensions suggestions profile -s DEV --account support@acme.com --js
     blob (owned by the add-in), shown verbatim as compact JSON — read it there
     rather than asking the customer to re-check the UI.
 - `functions create`, `functions update`, `functions delete` (two-step confirm).
+  - `--date-field <id|name>` (create and update) sets the function's **default
+    aggregation date field** (must be a Date field of the template) and sends the
+    platform's default per-period roll-up config (every period by month, `sum`,
+    end-of-period — what UI-created functions carry; a function needing MTD by
+    day must be adjusted in the UI). **Without it `DR.YTD`/`QTD`/`MTD`/…
+    do not work for the function anywhere** — `functions data --agg YTD` answers
+    HTTP 400 `{"DateAgg":[…]}` and the xlsx auto-calculate engine fails outright.
+    `create` without it prints a one-line warning on stderr. A later
+    `update`/`set-filters` full PUT keeps the date field (verified) — so
+    `update --template <id>` on a function that has one is **refused unless
+    `--date-field` is passed too** (the old field belongs to the old table, and
+    the server checks only its type).
 - `functions set-filters <id> --file <json> [--confirm]` — **the only way to
   author a function's filters** (`create`/`update` don't touch them). **FULL
   REPLACE**: the server deletes every existing filter and recreates from the
@@ -505,6 +516,65 @@ dr metrics dimensions suggestions profile -s DEV --account support@acme.com --js
   `--confirm`; internally a read-modify-write PUT that preserves the core fields
   and calculated-value links.
 
+### Live values: `functions data`
+
+`functions data <id> [--filter "NAME=V1,V2"]… [--date "NAME=DATE[,DATE]"]… [--agg DEFAULT|YTD|YTG|QTD|QTG|MTD|MTG] [--json]`
+evaluates the function through `PUT /api/functions/<id>/data/v2` — the endpoint
+the Excel add-in calls for `DR.GET` (`--agg DEFAULT`) and `DR.YTD`/… — so the
+number is the one Excel shows, with the function's own filters always applied
+(a `--filter` can only narrow them, never override).
+
+- Fields are named (or given by id) and resolved on the function's template;
+  the add-in's canonical field name goes on the wire. An unknown field fails
+  client-side with the list of valid fields.
+- **Dates.** The endpoint wants **Excel serial numbers** (2025-01-31 = 45688);
+  epoch seconds and ISO strings are not rejected server-side, they silently
+  return nothing. The CLI converts: on a Date field (via `--date` or `--filter`)
+  pass `YYYY-MM-DD`, `M/D/YYYY`, an ISO datetime, a serial, or epoch seconds.
+  A bare month (`2025-06`) is **refused** — tables store a specific day
+  (usually month-END), so a month's 1st would match nothing (DEFAULT) or stop a
+  month short (YTD). Pass the stored day, e.g. `2025-06-30`.
+- Several values on one field return **one row per value combination**; the
+  table shows each field's key (serials rendered back as dates) and `VALUE`
+  (rounded to 4 decimals for display; `--json` is the server body verbatim).
+- No row at all prints `(no data: nothing matches these filters)` — a real
+  answer (unknown value, or the function's own filter excludes it), not an error.
+- Errors: a per-query `error.msg` (e.g. "Field X is not related to function")
+  and any non-2xx exit non-zero; an HTTP 400 such as
+  `{"DateAgg":["Function N has no default aggregation date field"]}` is shown
+  verbatim with the `--date-field` fix. Under `--json` the body is printed first.
+
+### Rows behind a value: `functions drilldown`
+
+`functions drilldown <id> [--filter …]… [--exclude …]… [--date …]… [--agg …] [--columns a,b] [--limit 20] [--out rows.csv] [--csv] [--json]`
+calls `PUT /api/functions/<id>/drilldown/v4` with the same filters (as the
+add-in's filter objects, field id + type resolved from the template).
+
+- Prints `N rows × M columns`, the function's own aggregate over those rows
+  (`SUM(Amount) over these rows: …` — equals `functions data` with the same
+  filters), then the first `--limit` rows (0 = all) of the filtered fields and
+  the value field, or of `--columns`. Date columns arrive as epoch seconds and
+  are shown as dates.
+- Above the server's inline cap (≈ tens of thousands of rows) the answer is
+  `too_large_data`. Without `--out` that is an error naming the size; narrow
+  with more `--filter`s or add `--out`. With `--out <file.csv>` the CLI takes
+  the add-in's **CSV export** path automatically (`export_to_csv` → cache-key
+  poll → report download, ~15 s for 25k rows × 215 columns, 20 MB); `--csv`
+  forces it. An inline answer with `--out` is written as CSV too (schema
+  columns, dates as `YYYY-MM-DD`). `--out` raises the command budget to 300 s
+  (`--timeout <s>` overrides).
+- `--json` prints the inline body verbatim (rows plus a trailing
+  `{fields, empty_fields}` schema object); with `--out`, a JSON summary
+  (`source`, `rows`, `columns`, `aggregate`, `report_id`).
+- **Credential scopes:** a scoped credential (API key) needs `tables:read`
+  **and `dashboards:read`** for `drilldown`. The CSV export path polls
+  `/api/cache/cache_keys_status` and downloads `/api/dashboards/report/<n>`,
+  both of which the server scopes to `dashboards`; without it the export fails
+  at the first status poll (error 40301) after the server has started the task.
+  The CLI declares `dashboards:read` for every drill-down, inline included,
+  because scopes are per command, not per flag. `functions data` needs
+  `tables:read` only.
+
 ## Customer-facing docs (KB)
 
 Help Center → the **"Semantic Layer"** category. Find current articles with `dr kb search "metric KPI"` (or

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

@@ -149,8 +149,9 @@ except on `update`, which resolves the range's own table automatically.
   the blast radius (document + version counts) and get a token, then re-run with
   `--confirm-token` — token-only, no word gate even on prod (a rescan re-derives
   data, it doesn't delete it). To pick up a datamapper change on the live template
-  **without** touching history, use `datamappers update <id> --rescan latest`
-  instead (re-extracts the latest version of the mapper's bound documents); a full rescan will re-run pre-existing
+  **without** touching history, use `datamappers update <id> --payload-file <p>
+  --rescan latest` instead (re-extracts the latest version of the mapper's bound
+  documents; it publishes a new mapper version, so the mapper gets a new id); a full rescan will re-run pre-existing
   calc fields against old rows, so a latent divide-by-null there fails the whole
   scan. Refuses `UsageStats` on every tenant (system data, not customer-owned).
 - `dataflow get` — the dependency graph: inputs → mappers → LUTs → table →

package/dist/skills/fx-conversion-matrix/SKILL.md

@@ -431,27 +431,20 @@ this path that advice does not hold.) The generator omits it.
 `document_version_id` is required and is **not** in `dr datamappers get` output —
 read it from the upload response or `dr filebox versions <filebox_id>`.
 
-### Changing a mapper that already exists: remap, don't update
+### Changing a mapper that already exists: remap
 
 Widening an existing feed mapper, or adding reporting-amount columns to a business
-table's mappers, means editing mappers that already exist. `dr datamappers update` is
-the obvious tool, and on many orgs **it cannot work.** A mapper created by an org
-import or template push has no source version on record. `PUT
-/api/templates/mappers/<id>` reads the mapper's source file, and for such a mapper it
-fails with a bare HTTP 500. The server log shows `AttributeError: 'NoneType' object has
-no attribute 'get_document_data'`. No request body fixes it, because the endpoint never
-reads a version from the body.
+table's mappers, means editing mappers that already exist. `dr datamappers update
+<id> --payload-file <p>` does this as a remap: it publishes the edited config as a new
+version of the mapper, the way the UI's "Publish and scan" does, and fills in `name`,
+`ordinal`, the bound documents and the source version from the old mapper.
 
-Remap instead. `dr datamappers create from-file <table_id>` with the existing
-mapper's id replaces it in place and records a real source version:
+A mapper created by an org import or template push has no source version on record,
+and `update` stops with an error saying so. Put a version in the payload:
 
 ```json
 {
-  "name": "<existing name>",
-  "datamapper_id": <existing mapper id>,
-  "ordinal": <existing ordinal>,
   "document_version_id": <an ACTIVE version of one of its documents>,
-  "selected_document_ids": [<its mapped_documents_ids>],
   "sheet_name": "<a sheet that exists in THAT version>",
   "config": { ... the edited config ... }
 }
@@ -459,7 +452,8 @@ mapper's id replaces it in place and records a real source version:
 
 - **The mapper gets a new id.** The old id stays behind bound to no documents, and
   lookups, which live on the table, are unaffected. Keep an old→new id log for rollback.
-- **`ordinal` must be the existing one.** A lower one is refused as a duplicate mapper.
+- **`ordinal` must be the existing one.** `update` sends it for you; a lower one in the
+  payload is refused as a duplicate mapper.
 - **`sheet_name` must exist in the version you pass**, and a mapper's
   `preview_sheet_name` is often stale. Check with `dr filebox sheets <version_id>`; when
   the preview sheet is gone and the version has one sheet, use that one.
@@ -754,7 +748,7 @@ the package layout reaches every producer.
 | `#NAME?` on the label cell | `TEXT()` wrapped around `DR.MONTH()` | Step 4 |
 | Self-rate is not exactly 1 | ratio not anchored to the target row | Step 4 |
 | Custom code rejected by the Tables dialog | never registered as an org currency | Step 1 |
-| `datamappers update` 500s on an unchanged config | mapper has no source version (org import) | remap, Step 6 |
+| `datamappers update`: mapper has no source document version | mapper made by an org import | `document_version_id` in the payload, Step 6 |
 | Remap 500s: `Cannot read sheet with name …` | chosen version is in `ERROR` status | use the newest ACTIVE version, Step 6 |
 | New lookup columns empty on every target row | lookup built while the FX table was still scanning | rebuild the lookup, Step 7 |
 | Opening balances have no currency amounts | calc-model rows skip the mappers | **Step 7c** |

package/dist/skills/validate-workato-migration/SKILL.md

@@ -152,8 +152,11 @@ goes merge → new vN → §3 → `dr connectors query repoint` → re-sync. Cut
 
 The staging datasource holds **live customer credentials**, so remove it right away:
 1. `dr connectors query list` → `dr connectors query delete <queryId>` for each binding.
-2. `dr integrations delete <ds>` (two-step confirm). dr-cli has no connector delete, so the orphaned
-   `Connector` row points at a deleted datasource. Record its id.
+2. `dr integrations delete <ds> $STG` prints a plan and a confirm token. Re-run it with
+   `--confirm-token <tok>`. Prod is Tier A, so a human types the word shown in the desktop dialog; with
+   no interactive channel, hand the line to the user. Verify with `dr integrations get <ds> $STG` → 404.
+   dr-cli has no connector delete, so the orphaned `Connector` row points at a deleted datasource.
+   Record its id. (dr-cli skill, `reference/integrations.md`, "Deleting a data source".)
 3. Keep the staging fileboxes as evidence until cut-over + ticket close, then delete the `<Customer>` tree.
 4. Delete the local `wk/` and `st/` downloads: they are customer data. Keep only `report.md`.
 5. Record the report, what was deleted and what was kept in the migration ticket.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datarails-ai/dr-cli",
-  "version": "1.6.105",
+  "version": "1.6.107",
   "description": "Datarails CLI",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@datarails-ai/dr-appspace-cli": "0.11.2",
+    "@datarails-ai/dr-appspace-cli": "0.11.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     "commander": "^12.1.0",