@stackone/cli 1.44.1 → 1.45.0

package/README.md

@@ -396,6 +396,51 @@ stackone run --account-id <account-id> --api-key <your-api-key>
 - `--builtin` - Use the builtin (StackOne) version of the connector when fetching from the registry
 - `--custom` - Use the custom (organization) version of the connector when fetching from the registry
 - `--owner <owner>` - Explicitly specify the owner to disambiguate between multiple versions of the same connector in the registry
+- `--sync-full` - Walk the action's `dataSync` config to exhaustion the way a full sync would, reporting pages, records and the checkpoint the run would persist. Reads only — nothing is indexed
+- `--sync-incremental [checkpoint]` - Test incremental sync. With a checkpoint value, resumes from it. Without one, runs a full pass first and then resumes from the checkpoint that pass produced, exercising the handoff that normally spans two scheduled runs
+- `--sync-max-pages <pages>` - Cap pages for a sync run, clamped to the production limit of 2000
+- `--sync-page-size <size>` - Override the provider page size for a sync run, so a small sample account still produces several pages (`page` and `offset` strategies only)
+
+#### Testing a `dataSync` config
+
+`--sync-full` and `--sync-incremental` mirror the page loop the sync workflow runs in production: the same paginator and incremental strategies from `@stackone/connect-sdk`, the same item extraction, the same stop conditions (`exhausted`, `maxIterations`, `duplicatePage`), and the same rule that a truncated run does not advance its watermark. They never write to OpenSearch, so the org record and byte caps that can stop a production run are not reachable locally.
+
+```bash
+# Walk every page and show the watermark the run would persist
+stackone run --connector connector.s1.yaml --account account.json --action-id list_employees --sync-full
+
+# Full pass, then an incremental pass resuming from its checkpoint
+stackone run --connector connector.s1.yaml --account account.json --action-id list_employees --sync-incremental
+
+# Reproduce a specific resume point
+stackone run --connector connector.s1.yaml --account account.json --action-id list_employees --sync-incremental 2026-08-05T00:00:00Z
+```
+
+The summary reports, per phase, the pages walked, the record count, why the loop stopped, and the checkpoint the run consumed and would persist — plus a `sampleRecord` (the first record fetched) so the record shape is visible without opening the output file. Add `-d, --debug` to include the resolved request inputs for every page, which is what a surprising stop verdict has to be diagnosed from. `--output-file` always includes those per-page inputs, along with every fetched record under `records` (one array per phase); records are never printed to the terminal.
+
+#### Forcing multiple pages on a small account
+
+A sample account with three records returns everything on page one, so a full walk never proves the iterator advances. `--sync-page-size` shrinks the page size for the run:
+
+```bash
+stackone run --connector connector.s1.yaml --account '{"auth_config_key":"custom"}' \
+  --credentials '{"apiKey":"..."}' --action-id list_things --sync-full --sync-page-size 1
+```
+
+This cannot be done with `--params`. The `page` and `offset` strategies rewrite their size key from the connector config on every page (`params[pageSizeKey] = defaultPageSize`, `params[limitKey] = defaultLimit`), so any value supplied through `--params` is overwritten before the request is sent. The flag overrides `iterator.defaultPageSize` / `iterator.defaultLimit` on a copy of the config instead, leaving the connector file untouched.
+
+`cursor` pagination is the exception and is rejected with an explanation: the cursor strategy only ever writes the cursor itself, so there is no size key to override. A provider that takes a page size alongside a cursor (GraphQL `first`, for example) exposes it as an ordinary action input, which `--params` sets and the paginator preserves across every page.
+
+The checkpoint's kind (`timestamp` for `time_filter`, `cursor` for `delta_token`) is derived from the connector, so a bare value cannot be mismatched — a mismatched checkpoint is silently ignored by the strategy, which would make a run report success while fetching an unfiltered dataset.
+
+The run exits non-zero when its conclusions are invalid — an ignored checkpoint, or an iterator that is not advancing. A page-capped run exits zero, since a large dataset is not a misconfiguration.
+
+Warnings call out failure modes that are silent in production, including:
+
+- An iterator that never reaches the provider. `stackone validate` checks that the iterator key is declared as an action input, but not that the request step forwards it via `args` — if it does not, every page returns the same records
+- A `time_filter` whose `response.updatedAtPath` resolves on no record, so the watermark falls back to the local clock rather than provider timestamps
+- A `delta_token` run that emits no token, which makes production abandon every following incremental fire
+- An incremental pass that does not narrow the result set
 
 **Note:** You must provide either `--profile` or `--api-key` when using `--account-id`. If using `--api-key`, the `--api-url` option is optional and will default to the production API URL.
 

package/dist/cli.cjs

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-const e=require(`./agentConfig-KBkYYmMr.cjs`),t=require(`./cliCore-DUvOvrms.cjs`);require(`./setupMigration-rqPZ8MV6.cjs`),require(`./agentApiKey-BDp7EFMI.cjs`);let n=require(`dotenv`);process.env.DOTENV_CONFIG_QUIET=`true`,(0,n.config)(),new t.t().run();
+const e=require(`./agentConfig-KBkYYmMr.cjs`),t=require(`./cliCore-BqpUU92Z.cjs`);require(`./setupMigration-rqPZ8MV6.cjs`),require(`./agentApiKey-BDp7EFMI.cjs`);let n=require(`dotenv`);process.env.DOTENV_CONFIG_QUIET=`true`,(0,n.config)(),new t.t().run();

package/dist/cli.mjs

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{t as e}from"./cliCore-DSgrBC4x.mjs";import"./agentConfig-BWQWMYKQ.mjs";import"./setupMigration-C1ShGzOu.mjs";import"./agentApiKey-CWXxJgCO.mjs";import{config as t}from"dotenv";process.env.DOTENV_CONFIG_QUIET=`true`,t(),new e().run();export{};
+import{t as e}from"./cliCore-BharJXXM.mjs";import"./agentConfig-BWQWMYKQ.mjs";import"./setupMigration-C1ShGzOu.mjs";import"./agentApiKey-CWXxJgCO.mjs";import{config as t}from"dotenv";process.env.DOTENV_CONFIG_QUIET=`true`,t(),new e().run();export{};