@drip-apex/apex-cli 0.6.3 → 0.8.0

package/AGENTS.md

@@ -24,7 +24,6 @@ Use `apex` as the canonical command name. `drip` is a compatibility alias.
   "did you mean" hints — those are stderr diagnostics for humans; machine
   callers resolve names via `apex schema --json`.
 
-
 ## Zero-Experiment Shop Bootstrap
 
 CLI-only bootstrap is supported for a fresh shop before any experiments exist.
@@ -50,7 +49,7 @@ the first writes: `apex experiments create`, `apex goals create`,
 - Missing auth: run `apex login` interactively, or set `APEX_API_KEY`.
 - Headless login: pass `--api-key` or set `APEX_API_KEY`; `DRIP_API_KEY` remains a compatibility fallback.
 - Do not wait for prompts in CI or agent runs. If a command returns exit `4`, rerun with the exact flag named in the JSON error details only after checking the plan or destructive action.
-- Apply invalidates QA: inspect `apex experiments plan`, then rerun apply with `--force` if intended.
+- Apply invalidates QA: inspect `apex experiments plan`, then rerun apply with `--accept-qa-invalidation` if intended.
 - Stale workspace or filesystem: pull fresh files, reapply your edits, and plan again.
 - Server limit errors: read the JSON error details; Apex includes server-owned limits when available.
 
@@ -71,7 +70,6 @@ the first writes: `apex experiments create`, `apex goals create`,
 - Do not bypass the variation artifact persistence path with direct API writes.
 - Keep generated evidence outside `qa.json`; attach it through QA commands.
 
-
 ## Project code
 
 ```sh
@@ -98,3 +96,22 @@ A successful write returns `saved`, its diff, backup path, current version, writ
 and precompile result. A failed precompile is a saved-write warning. All warnings remain
 in JSON and are also written to stderr. User keys resolve domains or pin UUID context;
 shop keys must match the requested identity before any backup or write.
+
+Classification uses `--counting-type standard|setup_test|aa_test|non_program` on
+`apex experiments create` (default `standard`) and `apex experiments update`.
+Classification writes are draft-only. In pulled `experiment.json`, `experimentType`
+and `countingType` equal `delivery_type` and `counting_type` from
+`apex experiments get --json`. Omitting or setting `countingType` to null preserves
+the stored value. Classification edits invalidate QA approval; paused and running
+experiments reject these metadata changes.
+
+Experiment references accept an ID, slug, or test key (for example `BIO-085`). Test keys resolve within the selected shop; use `--shop <shop-id>` to change it. Bare lowercase references remain slugs.
+
+Filesystem apply preserves authored local bytes by default. Use
+`apex experiments apply <folder> --sync` to refresh them from stored server bytes.
+The receipt's `files` contains SHA-256 digests for every pull path; `synced` reports
+whether a full refresh succeeded. Server-owned QA and launch files are healed.
+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.

package/README.md

@@ -127,7 +127,7 @@ including every subcommand, argument, option, and alias.
 - `apex webhooks` — manage shop webhooks.
 - `apex simulate` — simulate data-layer triggers without emitting events.
 - `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. 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.
+  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.
 - `apex preview` — open a variation QA preview.
 - `apex roadmap` — consume approved roadmap ideas and handoffs.
@@ -178,6 +178,41 @@ means it is an `apex workspace checkout/status/publish` workspace. Keep the two
 formats in different folders; when the wrong command is run, Apex points to the
 matching status command.
 
+## Page targeting: URL rules and Pages
+
+Page targeting has two supported authoring paths, and both stay supported.
+
+| Key in `targeting` | What it is |
+| --- | --- |
+| `url` | An array of URL rules: `{ "type": "simple" \| "regex", "pattern": "/products/*", "include": true, "matchType": "exact" \| "contains" \| "wildcard" \| "regex" }`. |
+| `authorUrl` | Read-only, and present on every pull. The subset of `url` that an author wrote, recorded by the server; an empty array means no author-written rules. An apply ignores it and the server recomputes it. |
+| `pages` | An array of `{ "id": "<page id>", "include": true }` references to saved Pages. |
+| `pageRules` | Read-only. The server's expanded copy of each referenced Page, including its name and its own URL rules. |
+| `pageMatchMode` | `"any"` (default) or `"all"` when more than one Page is referenced. |
+
+**URL rules work without a saved Page.** `apex experiments create --source-url`
+and a hand-written `url` array in `targeting.json` are complete targeting on
+their own. Nothing rejects them, and no Page is required.
+
+**An included Page decides where the test runs.** At runtime the URL gate and
+the page-rules gate must BOTH match, but the URL gate is an OR over the whole
+expanded `url` list, and a Page referenced with `"include": true` copies that
+Page's own include rules into `url`. A visitor on the Page therefore passes the
+URL gate through the derived copy even when no authored include rule matches,
+so while an included Page is referenced your authored INCLUDE rules add no
+pages. A Page referenced with `"include": false` contributes only an exclude
+rule, so it can only veto and your authored INCLUDE rules still provide the
+positive match. Authored EXCLUDE rules always apply, and detaching an included
+Page gives the authored rules the decision back.
+
+`apex experiments get` prints the result of those two rules as one
+`Targeting:` line, in the same words the dashboard Setup tab uses, for example
+`2 URL rules (no saved Page)` or `Cart page and 1 URL rule`.
+
+In a pulled `targeting.json`, `url` is the expanded rule set and `authorUrl` is
+the authored subset, always present. Edit `url` and `pages`; treat `authorUrl`
+and `pageRules` as output.
+
 ## Push config format
 
 Run `apex push -c <config>` to load a JavaScript or TypeScript config. The
@@ -233,7 +268,6 @@ Read the CLI reference on the docs site:
 
 Maintainers: see the [CLI release runbook](../../docs/cli-releases.md).
 
-
 ## Project code
 
 ```sh
@@ -260,3 +294,22 @@ A successful write returns `saved`, its diff, backup path, current version, writ
 and precompile result. A failed precompile is a saved-write warning. All warnings remain
 in JSON and are also written to stderr. User keys resolve domains or pin UUID context;
 shop keys must match the requested identity before any backup or write.
+
+Classification uses `--counting-type standard|setup_test|aa_test|non_program` on
+`apex experiments create` (default `standard`) and `apex experiments update`.
+Classification writes are draft-only. In pulled `experiment.json`, `experimentType`
+and `countingType` equal `delivery_type` and `counting_type` from
+`apex experiments get --json`. Omitting or setting `countingType` to null preserves
+the stored value. Classification edits invalidate QA approval; paused and running
+experiments reject these metadata changes.
+
+Experiment references accept an ID, slug, or test key (for example `BIO-085`). Test keys resolve within the selected shop; use `--shop <shop-id>` to change it. Bare lowercase references remain slugs.
+
+Filesystem apply preserves authored local bytes by default. Use
+`apex experiments apply <folder> --sync` to refresh them from stored server bytes.
+The receipt's `files` contains SHA-256 digests for every pull path; `synced` reports
+whether a full refresh succeeded. Server-owned QA and launch files are healed.
+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.