@drip-apex/apex-cli 0.12.1 → 0.14.0

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
 
@@ -18,7 +30,10 @@ Use `apex` as the canonical command name. `drip` is a compatibility alias.
 - Launch is dashboard-only. The API and CLI do not start traffic.
 - Prefer `--json`; piped stdout defaults to JSON automatically.
 - JSON output is a stable contract: top level is `{ ok, version, command, data | error }`.
-- Diagnostics, prompts, progress, and update notices go to stderr.
+- With `--json`, stdout is exactly one JSON document. Diagnostics, prompts, progress,
+  and update notices go to stderr.
+- For single-request commands `data` is the API response body as returned (lists at
+  `.data.data[]`). API failures carry the API error body in `error.api`.
 - Do not parse human tables. Use `apex schema --json` first if you need flags.
 - Keep command names exact. Do not infer or guess names from the CLI's
   "did you mean" hints — those are stderr diagnostics for humans; machine
@@ -115,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:
@@ -100,6 +111,42 @@ Summary timestamps include `created_at` and `archived_at`; experiments have no `
 `--include-archived` to include them; archived rows display their archive date
 when the API provides `archived_at`.
 
+## JSON output contract
+
+With `--json`, or whenever stdout is piped, stdout carries exactly one JSON
+document and nothing else. Spinners, progress, prompts, warnings, human text and
+child-process output go to stderr, so `apex ... --json | jq` always parses.
+
+```json
+{ "ok": true, "version": "0.13.0", "command": "apex flags get", "data": {}, "context": {} }
+```
+
+- `data` is the API response body exactly as the API returned it for every command
+  backed by one API request. Lists keep the API's `{ "data": [...], "pagination": {...} }`
+  shape, so rows are at `.data.data[]`; single resources are at `.data` directly.
+- `apex experiments get` adds one CLI-derived key, `dashboard_url`, beside the
+  experiment fields.
+- Commands that combine several requests or local files (`experiments create`,
+  `pull`, `plan`, `apply`, `qa approve`, `triggers`, `project-code`, `harness`,
+  `workspace`, `doctor`, `whoami`, `push`, `analytics urls`, `flags status`,
+  `goals test`) print a documented CLI-composed `data` object.
+- Failures print `{ "ok": false, "version", "command", "error", "context" }`.
+  `error.code` is the CLI exit code, `error.details` carries retry hints and
+  server details, and `error.api` is `{ "status", "body" }` with the API error
+  envelope verbatim whenever an API response caused the failure.
+- `deprecated` appears on the envelope only when a deprecated flag was used.
+
+**Breaking in 0.13.0.** Earlier releases re-nested or renamed API bodies. Update
+scripts: `.data.experiments[]` becomes `.data.data[]`; `experiments get`
+`.data.experiment.id` becomes `.data.id`; `.data.flag`, `.data.goal`,
+`.data.funnel`, `.data.signal`, `.data.backlog_item`, `.data.personalization`,
+`.data.exclusion_group`, `.data.asset`, `.data.landing_page`, `.data.webhook`,
+`.data.targeting` and `.data.verification` wrappers are gone (read the fields at
+`.data`); `experiments results` reads at `.data` instead of `.data.results`,
+`funnels run` at `.data` instead of `.data.run`, and `brand` at `.data.data`
+instead of `.data.brandContext`; lifecycle and delete commands return the API's
+body instead of a CLI summary.
+
 ## Command index
 
 Use `apex schema --json` to emit the complete machine-readable command surface,
@@ -136,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.
@@ -152,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.
@@ -378,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.