@drip-apex/apex-cli 0.6.2 → 0.7.0

package/AGENTS.md

@@ -50,7 +50,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.
 
@@ -70,3 +70,39 @@ the first writes: `apex experiments create`, `apex goals create`,
 - Edit experiment files, variation code, metrics, and targeting only through supported paths.
 - 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
+apex project-code get --shop example.com --json
+apex project-code diff --file project-code.json --shop example.com --json
+apex project-code set --file project-code.json --shop example.com --backup previous-code.json --json
+```
+
+The input is a partial projectCode object, for example `{ "css": "body { color: red; }" }`.
+Supported fields are `enabled` (boolean) and `css`, `helperJs`, and `js` (strings or null).
+Each code field permits at most 20,000 characters. Omitted fields remain unchanged.
+Null or blank code clears that field. Unknown fields and empty objects are rejected.
+
+GET returns complete code, shop identity, and an opaque version. DIFF returns effective
+before/after values and changed fields without writing. SET creates a new backup file
+with complete previous code, identity, capture time, and the exact version before PATCH.
+It never replaces an existing backup. Backup failures prevent the write. An effective
+no-op returns `unchanged`, without a PATCH or backup file.
+
+The backed-up version becomes expectedVersion unchanged. A conflict returns exit 5,
+keeps the backup, and does not retry. Read the latest state and preview it before a new
+attempt with a new backup path. Authentication uses exit 2; invalid input uses exit 3.
+A successful write returns `saved`, its diff, backup path, current version, writtenVersion,
+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.

package/README.md

@@ -109,6 +109,10 @@ including every subcommand, argument, option, and alias.
 ### Experiments and delivery
 
 - `apex consent` — manage consent gating.
+- `apex project-code` — inspect and safely change shop project code.
+- `apex project-code get` — read complete code and its opaque version.
+- `apex project-code diff` — preview a partial JSON change without writing.
+- `apex project-code set` — create a backup before a version-checked write.
 - `apex triggers` — manage data-layer triggers and temporary setup capture.
 - `apex triggers get --shop <domain-or-id>` — read the identified shop's runtime triggers.
 - `apex triggers set` — replace the shop's runtime triggers from a JSON file.
@@ -123,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.
@@ -174,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
@@ -228,3 +267,39 @@ Read the CLI reference on the docs site:
 - https://docs.drip-apex.com/cli/commands-output
 
 Maintainers: see the [CLI release runbook](../../docs/cli-releases.md).
+
+
+## Project code
+
+```sh
+apex project-code get --shop example.com --json
+apex project-code diff --file project-code.json --shop example.com --json
+apex project-code set --file project-code.json --shop example.com --backup previous-code.json --json
+```
+
+The input is a partial projectCode object, for example `{ "css": "body { color: red; }" }`.
+Supported fields are `enabled` (boolean) and `css`, `helperJs`, and `js` (strings or null).
+Each code field permits at most 20,000 characters. Omitted fields remain unchanged.
+Null or blank code clears that field. Unknown fields and empty objects are rejected.
+
+GET returns complete code, shop identity, and an opaque version. DIFF returns effective
+before/after values and changed fields without writing. SET creates a new backup file
+with complete previous code, identity, capture time, and the exact version before PATCH.
+It never replaces an existing backup. Backup failures prevent the write. An effective
+no-op returns `unchanged`, without a PATCH or backup file.
+
+The backed-up version becomes expectedVersion unchanged. A conflict returns exit 5,
+keeps the backup, and does not retry. Read the latest state and preview it before a new
+attempt with a new backup path. Authentication uses exit 2; invalid input uses exit 3.
+A successful write returns `saved`, its diff, backup path, current version, writtenVersion,
+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.