@datarails-ai/dr-cli 1.6.80 → 1.6.82

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.80",
+  version: "1.6.82",
   description: "Datarails CLI",
   type: "module",
   engines: {
@@ -38,7 +38,7 @@ var package_default = {
     postinstall: "node scripts/postinstall.mjs"
   },
   dependencies: {
-    "@datarails-ai/dr-appspace-cli": "0.10.4",
+    "@datarails-ai/dr-appspace-cli": "0.10.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "^1.3.0",
     commander: "^12.1.0",
@@ -67,7 +67,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-09-30T14:50:43.133Z";
+var BUILD_TIME = "2026-09-30T16:01:09.322Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);

package/dist/scopes-map.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "cliVersion": "1.6.80",
+  "cliVersion": "1.6.82",
   "_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/create-connector-lib/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: create-connector-lib
+description: Use when a vendor's connector code should be shared across Datarails orgs in dr-connectors - a vendor with no `lib/<vendor>/` yet that a second customer is likely to need, a Workato migration of a vendor we already run for another org, a second org asking for the same vendor with different columns, or an existing per-org connector being moved onto `lib/`. Triggers - "create a lib for <vendor>", "make <vendor> a shared lib", "generic connector", "pass the field names", "select_query", "the next customer needs different columns", "move this connector onto lib", "lib/<vendor>", "same vendor, another org".
+---
+
+# Create a connector lib
+
+## Overview
+
+A lib is the vendor's code written once: `lib/<vendor>/` owns the request, auth, pagination and the
+file format, and each org's connector is two thin files that **pass their field names** plus a few
+optional parameters. The worked example is `lib/ramp/dataqueries/select_query.py`; find its thin
+connectors with `grep -rl "lib.ramp.dataqueries.select_query" --include=*.py us us2 uk ca`. Read both first.
+
+**REQUIRED:** `datarails-connectors-onboard-connector` for everything around the code: branch,
+publish, datasource, filebox, binding. Its memory, streaming and 4xx rules apply to lib code too.
+
+## Layout
+
+```
+lib/<vendor>/
+  __init__.py                    what the lib holds: each module and its output, no one who uses it
+  _core.py                       output-neutral: credentials, token, client, pagination, query vars, logger
+  connections/base_connection.py the one connection: auth only, no scope or other per-customer value
+  dataqueries/select_query.py    the generic engine
+  tests/test_select_query.py     the engine, on synthetic data
+  tests/test_artifact.py         every thin connector that imports lib.<vendor>, found by glob
+<dc>/<org_id>_(<domain>)/<vendor>/
+  connections/<conn>.py          subclasses the lib connection and sets its SCOPE (or other auth parameter)
+  dataqueries/<dq>.py            the org's COLUMNS, OBJECT_TYPES, get_query_class
+  tests/test_<dq>.py             the org's exact header, each org-specific source it uses, and its SCOPE
+```
+
+## The engine contract
+
+The connector's thin dataquery subclasses `SelectQuery` and sets only data:
+
+| Attribute | Meaning |
+|---|---|
+| `PATH` | endpoint under the vendor base URL |
+| `WINDOW` | the endpoint's from/to parameter names, filled from the Sync-query's `startDate`/`endDate`; omit for undated datasets |
+| `COLUMNS` | `(label, source)` pairs in file order |
+
+Sources are small functions in the engine module: `field("a.b.c")` (dotted path; a missing step is
+empty), `timestamp(...)` (re-rendered in the source system's format), and one per vendor-specific
+lookup (Ramp: `category(remote_name, key)`; a custom-fields array would be `custom_field(name)`).
+Add a source only when a column needs it. Add an engine attribute (e.g. `EXPLODE` for one row per line
+item) only when a real connector needs it, with its test.
+
+`OBJECT_TYPES` is a literal in the thin file. The engine module declares no columns, no object types,
+no `get_query_class`. The connection works the same way: one lib connection whose parameters (Ramp:
+`SCOPE`, the read scopes the customer's app was granted) the thin connection sets; an unset required
+parameter fails in `connect()` before the vendor is called.
+
+## Rules
+
+- **No company names anywhere under `lib/`**: no customer, org id, domain, or the tool being replaced
+  (Workato), in code, docstrings, comments, test names, fixture data or test ids. Test data is
+  synthetic. Per-customer values (columns, category or custom-field names) live only in thin files.
+  Before committing, grep the lib diff for the customer's name, domain and org id.
+- **Reuse before adding.** Use `_core` helpers and an existing connection that fits; never a second
+  copy. Name modules after what they do, never after who uses them. Hand the user a list of lib
+  improvements you noticed (duplicated helpers, code that belongs in `_core`), done in their own PR.
+- **Never change what another org lands.** A change to a module other orgs import must be proven
+  output-neutral: their tests pass, and for text-only edits, each module's AST with docstrings stripped
+  equals `origin/main`'s. A lib merge cuts new versions of every connector that bundles it; none moves
+  until its binding is repointed.
+- **Take the file format from a real landed file, not from memory.** Download the file the old
+  integration landed (`dr filebox download <fb> --doc-version <id>`) and profile it: BOM, line endings,
+  trailing newline, how empty and null cells are written, when values are quoted, number and boolean
+  forms, timestamp formats. The engine's cell writer reproduces exactly that.
+- **Credentials resolve at runtime from the datasource** (`get_credentials`), never from code, tests
+  or logs (`tech/security.md` §4). Check a migrated credential's shape without printing it; a stored
+  header value may carry its scheme (`Basic <base64>`).
+
+## Before the first merge
+
+Run the thin connector's dataquery locally against the live vendor for one closed period and compare
+its bytes with the old integration's landed file for the same period (the `validate-workato-migration`
+skill's `compare_files.py`). Differences only in fields edited after the old run are data drift;
+anything in quoting, format, order or header is a bug to fix before merging. For a refactor, render
+the same fetched records through the old and new code and require identical bytes.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Customer column list or category names as the lib default | Empty default in the lib; the thin file sets them |
+| "A thin connector needs no test" | A thin file that declares columns tests its header and its org-specific sources |
+| One lib connection per scope, named after an output variant (`flat`) | One parameterized connection; the thin file sets `SCOPE` |
+| `csv.writer` / `str(True)` for the file | Write cells the way the landed file shows (`""`, LF, `true`) |
+| Artifact test that lists each client's folder | Discover thin connectors by glob on `from lib.<vendor>.` |
+| A page cap that logs and returns | The cap raises `PermanentError`; test landing exactly on it and exceeding it |

package/dist/skills/datarails-connectors-onboard-connector/SKILL.md

@@ -85,17 +85,46 @@ CONNECTION = "<conn>"
 ```
 
 - **Pick the variant by output, not by customer.** A lib can hold several output shapes of one vendor
-  (`lib/ramp`: `curated` / `reports` / `flat`). Read the lib's `__init__.py` — it names each variant and
-  who uses it — and match the columns the customer expects (a Workato migration wants the variant built
-  for Workato parity). Never merge or edit a variant another org lands data through: that changes their
-  live output.
+  (`lib/ramp`: `curated` / `reports` / `flat` / `pivoted`). Read the lib's `__init__.py` — it names each
+  variant and its output — and match the columns the customer expects (a Workato migration wants the
+  variant built for Workato parity). Never merge or edit a variant another org lands data through: that
+  changes their live output.
+- **Reuse the lib's code before adding any.** A new variant still reuses what the lib already has: the
+  helpers in `_core.py` and the lib's one connection. `lib/ramp` has a single
+  `connections/base_connection.py`; a thin connection subclasses it and sets `SCOPE`, never a copy. Name a new variant after its output,
+  never after the tool or customer it came from. While you're in the lib, list what could be shared or
+  cleaned up (a helper two variants duplicate, a pattern that belongs in `_core`) and give that list to
+  the user as lib suggestions. Make those changes in their own PR unless the user asks otherwise.
+- **The lib is shared: it never names a client or holds a client's config or data.** No customer or org
+  id in its code, docstrings or tests; no client-specific default (a customer's accounting-category
+  names, their GL codes); test fixtures are synthetic, never rows copied from a customer's file. Grep the
+  lib diff for the customer's name and org id before committing.
 - **A per-org difference is config or a one-attribute extension, never a copy.** First look for a
   binding parameter the lib already reads (`lib/ramp`: optional `scope` in `query_config`). Otherwise
-  subclass the lib's class in the thin connection file and override one attribute —
-  `samples/sample_lib_connector/` shows both forms.
+  subclass the lib's class in the thin connection or dataquery file and override one attribute —
+  `samples/sample_lib_connector/` shows the connection form. A dataquery extension also defines its own
+  `get_query_class`, keeping `OBJECT_TYPES` one import hop from the lib:
+
+  ```python
+  # <datacenter>/<org_id>_(<org_name>)/<vendor>/dataqueries/<dq>.py
+  from dr_integrations_sdk import DataQuery
+
+  from lib.<vendor>.dataqueries.<variant> import OBJECT_TYPES, TransactionsQuery as _TransactionsQuery  # noqa: F401
+
+  CONNECTION = "<conn>"
+
+
+  class TransactionsQuery(_TransactionsQuery):
+      CATEGORIES = ("<the customer's field>", "<another>")
+
+
+  def get_query_class(name: str) -> type[DataQuery]:
+      return TransactionsQuery
+  ```
 - **No new test is needed**: a dataquery that only references a lib counts as tested by the lib's own
   `lib/<vendor>/tests/` (`scripts/check_connector_tests.py`). An extension that adds behaviour tests that
-  behaviour in the lib or next to the connector.
+  behaviour next to the connector (`<vendor>/tests/test_<dq>.py`), since the lib's tests never see the
+  customer's values.
 - **The lib is missing a dataset, or has a bug** → change the lib (with its tests) in its own PR. A lib
   change republishes every connector that bundles it — new versions, never promoted — so each org moves
   only when its binding is repointed.

package/dist/skills/plugins.json

@@ -1,6 +1,7 @@
 {
   "dr-cli-integrations": [
     "connector-sandbox",
+    "create-connector-lib",
     "datarails-connect-workato",
     "datarails-connectors-onboard-connector",
     "dr-error-enrichment",

package/dist/skills/validate-workato-migration/reference/gotchas.md

@@ -7,6 +7,7 @@
 | `dr connectors publish` aborts "published under org A … authenticated as org B" | Passed the customer's dataquery path with `$STG` | Use `<dc>/<staging_org>_(test-workato-migration.com)/…` + `--tag vN` |
 | Copy workflow: "target exists with DIFFERENT bytes" | A different artifact was already copied for that `vN` | Stop and investigate. Never overwrite: the staging copy must equal what the customer runs |
 | Second sync of a filebox never runs | The previous run still holds the filebox Singleton | Wait for the version to land before re-triggering |
+| Vendor token call 401 "credentials not found or malformed" with a Workato-sourced credential | The environment property holds the whole header value, scheme included (`Basic <base64>`), because the recipe pastes the pill straight into `Authorization` | Strip the scheme before decoding, then store the decoded parts (e.g. `client_id` / `client_secret`) in the datasource. Check the shape (prefix, lengths) without printing the value |
 | One row differs, on a recent period only | Vendor data changed after Workato's run | Re-pick older, closed periods before calling it a connector bug |
 | Only bytes differ, values equal | Quoting / float formatting / line endings | Still a FAIL: match Workato's CSV writer in the connector |
 | Sync-query shows escaped quotes / doesn't render | `config.query` written as a JSON string | Write it as a nested object; the CLI encodes it |

package/package.json

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