@drip-apex/apex-cli 0.13.0 → 0.14.1

package/AGENTS.md

@@ -2,6 +2,17 @@
 
 Use `apex` as the canonical command name. `drip` is a compatibility alias.
 
+## Choosing a workflow
+
+The default loop for agents building or editing a test is `apex experiments pull`, edit supported files, `apex experiments plan`, `apex experiments apply`, then `apex experiments qa status`.
+
+| Workflow | Use when | What it writes | Do not use when |
+| --- | --- | --- | --- |
+| `apex push` | Syncing config-as-code goals, targeting, and flags by slug. | Server configuration declared in `.drip.config.ts`. | Editing one test's variation files or QA state. |
+| `apex experiments pull/plan/apply` | An agent is building or editing a test. This is the default. | Supported experiment files and server draft state after review of the plan. | You need a live operator code workbench. |
+| `apex workspace` | An operator needs a live-preview draft for one variation. | Workspace draft files and published draft variation code. | You need the default full-experiment agent loop. |
+| `apex harness` | An external `ab-harness` project needs build and QA integration. | External harness project artifacts and QA sessions. | Apex owns the experiment files directly. |
+
 ## Canonical Loop
 
 1. `apex experiments pull <id-or-slug> --out <folder>`
@@ -10,7 +21,8 @@ Use `apex` as the canonical command name. `drip` is a compatibility alias.
 4. `apex experiments apply <folder> --json`
 5. `apex experiments qa status <folder> --json`
 6. Update QA with `apex experiments qa check`, `notes`, and `approve`.
-7. Publish or launch only through the dashboard approval surface.
+7. `apex experiments status <folder> --json` before handover. Unknown approval-version matching is not readiness.
+8. Publish or launch only through the dashboard approval surface.
 
 ## Invariants
 
@@ -118,3 +130,35 @@ Create/get return `dashboard_url`; apply returns `dashboardUrl`. These links
 switch the signed-in dashboard user's active shop before opening the experiment.
 
 Filesystem apply caches uploaded asset URLs by byte SHA-256 in `.apex/experiment-filesystem.json`, so unchanged images reuse their URL across applies without rewriting authored files.
+
+## Error recovery and update notices
+
+JSON errors keep the numeric `error.code` exit code and add `error.reason`,
+`error.next_steps` (an array of `{ command, why }`), and optional `error.request_id`.
+The request ID comes from `x-request-id`, falling back to `x-vercel-id` (the Apex app) and then `cf-ray`; include it
+when reporting an API failure. API-provided reason codes are preserved verbatim.
+Otherwise reasons are `auth_required`, `auth_forbidden`, `shop_context_required`,
+`validation_failed`, `confirmation_required`, `conflict`, `not_found`,
+`rate_limited`, `network_timeout`, `network_connect_timeout`, `network_dns`,
+`network_refused`, `network_reset`, `network_tls`, `network_unknown`,
+`local_file_error`, or `internal_error`.
+
+Inspect `next_steps` for login, key permissions, shop selection, network settings,
+folder validation, or rate-limit recovery. Steps are suggestions, never automatic
+approval to retry a write. Confirmation errors retain `error.details.retry`.
+Human output prints recovery steps as `Next:` lines on stderr and request IDs
+on the error line. Trigger commands now follow the same exit codes as every other
+command: authentication failures exit **2** (previously 4), invalid local input exits
+**3** (previously 2), and other API failures follow their HTTP status (validation
+**3**, conflict **5**, anything else **1**). The `TRIGGERS_AUTH`, `TRIGGERS_CONFIG_ABSENT` and `TRIGGERS_NO_DATA`
+verdict prefixes are unchanged, so scripts can key on them instead of exit codes.
+
+When a newer CLI release is available, success and error JSON envelopes include
+`update: { current, latest, breaking, notes_url }`. `breaking` is true for a
+major-version change, or a minor-version change while the installed version is
+0.x. `notes_url` links to the published CLI command/output documentation. A one-line notice also goes
+to stderr, including in non-TTY agent runs; stdout remains one JSON document.
+The latest version is cached in `~/.drip/update-check.json` for 24 hours, and a
+failed lookup for one hour. The best-effort check has a 900 ms budget, never fails
+the command, and is skipped when the `CI` environment variable is set. Set
+`APEX_NO_UPDATE_CHECK=1` to disable both the check and the `update` field.

package/README.md

@@ -1,5 +1,16 @@
 # Apex CLI
 
+## Choosing a workflow
+
+The default loop for agents building or editing a test is `apex experiments pull`, edit supported files, `apex experiments plan`, `apex experiments apply`, then `apex experiments qa status`.
+
+| Workflow | Use when | What it writes | Do not use when |
+| --- | --- | --- | --- |
+| `apex push` | Syncing config-as-code goals, targeting, and flags by slug. | Server configuration declared in `.drip.config.ts`. | Editing one test's variation files or QA state. |
+| `apex experiments pull/plan/apply` | An agent is building or editing a test. This is the default. | Supported experiment files and server draft state after review of the plan. | You need a live operator code workbench. |
+| `apex workspace` | An operator needs a live-preview draft for one variation. | Workspace draft files and published draft variation code. | You need the default full-experiment agent loop. |
+| `apex harness` | An external `ab-harness` project needs build and QA integration. | External harness project artifacts and QA sessions. | Apex owns the experiment files directly. |
+
 ## Purchase-capture verification
 
 The CLI exposes a read-only, publication-anchored purchase verification battery:
@@ -172,6 +183,7 @@ including every subcommand, argument, option, and alias.
 - `apex funnels` — manage analytics funnels.
 - `apex webhooks` — manage shop webhooks.
 - `apex simulate` — simulate data-layer triggers without emitting events.
+- `apex experiments status [folder-or-id]` — read context, file versions, QA, and handover next steps without writing. Defaults to the current pulled folder.
 - `apex experiments` — create, inspect, operate, and synchronize experiments.
   Use `apex experiments screenshots <id-or-slug>` to force-assign every capture, including control, to its variation server-side for deterministic screenshots. Resume a job that outlives the CLI timeout with `--job <id>`; polling continues without creating another job, and the stored job's devices and variations win, so `--devices`/`--variations` are ignored (the CLI warns). The command attaches terminal jobs to the QA run by default; use `--no-attach-qa` to opt out. Choose devices with `--devices`, filter treatments with `--variations`, and use `--json` for the signed result payload. Use `apex experiments qa evidence` with `--job`, repeatable `--file`, or `--records` to write QA evidence directly.
 - `apex push` — synchronize `.drip.config.ts` with Apex.
@@ -188,6 +200,8 @@ including every subcommand, argument, option, and alias.
 ### Analytics, targeting, and tracking
 
 - `apex tracking` — diagnose storefront tracking.
+- `apex events` — export raw tracking events.
+- `apex events export` — export all raw events in a fixed ISO 8601 window with automatic pagination.
 - `apex environments` — inspect delivery environments.
 - `apex analytics` — read shop analytics.
 - `apex pages` — manage page targeting resources.
@@ -414,3 +428,60 @@ Connection errors retain the underlying failure. JSON output exposes
 | `tls` | Certificate or TLS validation failed. Check expired certificates and your corporate TLS proxy's trusted CA configuration. |
 | `timeout` | The request was aborted or exceeded its deadline. Check server availability and network access. |
 | `unknown` | Another network failure occurred. Use the included cause message to diagnose network or sandbox restrictions. |
+
+### Read-only order journey
+
+```sh
+apex analytics order-journey --platform shopware --order-id <id> --environment production --from <iso> --to <iso> --json
+```
+
+Requires `analytics:read` through a secret or authorized user key. Supply exactly one of `--order-id` or `--order-number`, an explicit environment and an ISO interval of at most 31 days. `--include-qa` includes QA eligibility; bots remain excluded. The sanitized report includes all represented assignments and discloses incomplete coverage. Source failures and historical consent/fingerprint gaps remain unknown. Exit 0 means the report was fetched, not that the journey passed. `eligible_for_attributed_goal_read` uses only `attributed_goal_counts`; `finalStatisticalContribution` is always `not_evaluated`. Nothing is repaired or saved locally.
+
+Order journey diagnostics report current, stale, or unknown freshness for each retained receipt and assignment. Present attributed-goal reads identify their evaluated snapshot; they do not establish historical contribution or repair missing producer evidence.
+
+## Error recovery and update notices
+
+JSON errors keep the numeric `error.code` exit code and add `error.reason`,
+`error.next_steps` (an array of `{ command, why }`), and optional `error.request_id`.
+The request ID comes from `x-request-id`, falling back to `x-vercel-id` (the Apex app) and then `cf-ray`; include it
+when reporting an API failure. API-provided reason codes are preserved verbatim.
+Otherwise reasons are `auth_required`, `auth_forbidden`, `shop_context_required`,
+`validation_failed`, `confirmation_required`, `conflict`, `not_found`,
+`rate_limited`, `network_timeout`, `network_connect_timeout`, `network_dns`,
+`network_refused`, `network_reset`, `network_tls`, `network_unknown`,
+`local_file_error`, or `internal_error`.
+
+Inspect `next_steps` for login, key permissions, shop selection, network settings,
+folder validation, or rate-limit recovery. Steps are suggestions, never automatic
+approval to retry a write. Confirmation errors retain `error.details.retry`.
+Human output prints recovery steps as `Next:` lines on stderr and request IDs
+on the error line. Trigger commands now follow the same exit codes as every other
+command: authentication failures exit **2** (previously 4), invalid local input exits
+**3** (previously 2), and other API failures follow their HTTP status (validation
+**3**, conflict **5**, anything else **1**). The `TRIGGERS_AUTH`, `TRIGGERS_CONFIG_ABSENT` and `TRIGGERS_NO_DATA`
+verdict prefixes are unchanged, so scripts can key on them instead of exit codes.
+
+When a newer CLI release is available, success and error JSON envelopes include
+`update: { current, latest, breaking, notes_url }`. `breaking` is true for a
+major-version change, or a minor-version change while the installed version is
+0.x. `notes_url` links to the published CLI command/output documentation. A one-line notice also goes
+to stderr, including in non-TTY agent runs; stdout remains one JSON document.
+The latest version is cached in `~/.drip/update-check.json` for 24 hours, and a
+failed lookup for one hour. The best-effort check has a 900 ms budget, never fails
+the command, and is skipped when the `CI` environment variable is set. Set
+`APEX_NO_UPDATE_CHECK=1` to disable both the check and the `update` field.
+
+## Usage telemetry
+
+Authenticated invocations send a process invocation ID, command path, explicitly set
+option names (never values), JSON/TTY modes, credential kind, organization/shop IDs,
+CLI/Node versions, platform, exit code, error class, API response count, first failed
+response status/code/request ID and normalized route, and duration. Parse failures
+send `(parse)` and the first non-option token as `attempted`, redacted when it looks
+like a credential, URL or path, or is longer than 40 characters. No argument values beyond
+that attempted token, file contents, prompts, selectors, URLs, error messages, or secrets
+are sent. Login/logout, tests, the mock transport, and runs with no resolvable credentials
+(neither stored nor environment) skip telemetry. Environment-credential runs
+(`APEX_API_KEY` or `DRIP_API_KEY`) are recorded with credential kind `env` unless
+`APEX_TELEMETRY=0`. Set `APEX_TELEMETRY=0` to disable the beacon. The best-effort request has an
+800 ms timeout and never changes command output or exit status.