@drip-apex/apex-cli 0.8.1 → 0.10.0

package/README.md

@@ -129,7 +129,7 @@ including every subcommand, argument, option, and alias.
 - `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.
-- `apex preview` — open a variation QA preview.
+- `apex preview` — open a variation QA preview; `--proxy` returns a `qa_run` receipt. Its `automated_evidence_count` counts the normalized `evidenceRecords` across all evidence kinds, matching the list shown by `apex experiments qa status`.
 - `apex roadmap` — consume approved roadmap ideas and handoffs.
 - `apex harness` — develop AB Test Harness projects with live QA sessions.
 - `apex workspace` — check out, preview, and publish draft workspace files.
@@ -313,3 +313,22 @@ 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.
+
+`--instructions` cannot be combined with `--out` (or its legacy alias `--output`); file exports always contain the full JSON contract.
+
+Roadmap handoff JSON identifies itself as `apex.roadmap_handoff.v1`; backlog get/list
+items identify themselves as `apex.backlog_item.v1`, both with `schema_version: 1`.
+The handoff embeds the same closed item projection that backlog responses serve
+alongside their existing raw fields. Published schemas and fixtures live in
+[`docs/contracts/experiment-os`](../../docs/contracts/experiment-os/README.md).
+Breaking changes require a new v2 contract; the backlog `version` is a separate
+optimistic concurrency token.
+
+| Key | Source |
+| --- | --- |
+| `approval` | Roadmap decision status (`proposed` without a decision), item stage, and decision's nullable `decided_at`. Top-level `status` remains the item lifecycle status. |
+| `goals` | `apex_goal_id` is the linked experiment goal or null. |
+
+QA status creates a run only when none exists. Reading an existing run never writes
+to it: `updatedAt` is its last stored mutation time, while `computedAt` is the ISO
+timestamp when the current checklist and summary were computed.

package/dist/cli.js

@@ -7112,7 +7112,7 @@ var import_node_os3 = __toESM(require("node:os"));
 // package.json
 var package_default = {
   name: "@drip-apex/apex-cli",
-  version: "0.8.1",
+  version: "0.10.0",
   license: "MIT",
   description: "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   private: false,
@@ -9639,6 +9639,7 @@ function printQaPreviewUrls(experimentId, result) {
 function printQaRun(run3) {
   console.log();
   console.log(source_default.bold(`QA run ${run3.id}`));
+  console.log(`  computedAt: ${run3.computedAt}`);
   console.log(`  Status:   ${statusBadge(run3.summary.status)}`);
   console.log(`  Required: ${run3.summary.completedRequired}/${run3.summary.required}`);
   if (run3.approvedAt) console.log(`  Approved: ${run3.approvedAt}`);
@@ -10826,7 +10827,9 @@ var applyFilesystem = new Command("apply").option("--sync", "Refresh local autho
     fail(this, error instanceof Error ? error.message : String(error));
   }
 });
-var qaStatus = new Command("status").description("Show or create the latest experiment QA run").argument(
+var qaStatus = new Command("status").description(
+  "Show the latest experiment QA run (creates one only when none exists; reads never change updatedAt)"
+).argument(
   "[folder-or-id]",
   "Experiment filesystem folder, ID, slug, or test key (for example BIO-085)",
   "."
@@ -11791,7 +11794,9 @@ var pushCommand = new Command("push").description("Push experiment definitions f
 
 // src/commands/preview.ts
 init_source();
-var previewCommand = new Command("preview").description("Open QA preview URL for an experiment variation").argument("<id-or-slug>", "Experiment ID or slug").argument("[variation-id]", "Variation ID (defaults to first non-control)").option("--store-url <url>", "Override experiment store_url (target website URL)").option("--proxy", "Create an artifact-injecting proxy preview").option("--ttl <hours>", "Proxy preview lifetime in hours (1-168)").option("--no-open", "Print URL instead of opening browser").action(
+var previewCommand = new Command("preview").description(
+  "Open QA preview URL for an experiment variation; proxy previews return a QA run receipt"
+).argument("<id-or-slug>", "Experiment ID or slug").argument("[variation-id]", "Variation ID (defaults to first non-control)").option("--store-url <url>", "Override experiment store_url (target website URL)").option("--proxy", "Create an artifact-injecting proxy preview").option("--ttl <hours>", "Proxy preview lifetime in hours (1-168)").option("--no-open", "Print URL instead of opening browser").action(
   async (idOrSlug, variationId, opts) => {
     const creds = requireCredentials();
     if (opts?.proxy) {
@@ -11819,6 +11824,9 @@ var previewCommand = new Command("preview").description("Open QA preview URL for
       const data = created.data;
       output(previewCommand, data, () => {
         console.log(source_default.cyan(data.preview_url));
+        console.log(
+          data.qa_run.created ? `QA run ${data.qa_run.id} created` : `QA run ${data.qa_run.id} refreshed (${data.qa_run.automated_evidence_count} automated evidence records)`
+        );
         const expiresAt = new Date(data.expires_at);
         const remainingMs = expiresAt.getTime() - Date.now();
         const value = remainingMs < 864e5 ? Math.max(1, Math.round(remainingMs / 36e5)) : Math.round(remainingMs / 864e5);
@@ -12790,7 +12798,11 @@ More results: --cursor ${res.data.pagination.next_cursor}`));
     }
   );
 });
-var handoff = new Command("handoff").description("Get the full build brief for an approved roadmap item").argument("<id>", "Roadmap/backlog item ID").option("--out <path>", "Write handoff JSON to a file").addOption(new Option("-o, --output <path>", "Legacy alias for --out").hideHelp()).option("--instructions", "Print only the build instructions").action(async function action32(id, opts) {
+var handoff = new Command("handoff").description(
+  "Get apex.roadmap_handoff.v1 JSON: contract, schema_version, item, experiment, instructions, goals, mockups, acceptance_criteria, harness, scoring, source, metadata"
+).argument("<id>", "Roadmap/backlog item ID").option("--out <path>", "Write handoff JSON to a file").addOption(new Option("-o, --output <path>", "Legacy alias for --out").hideHelp()).addOption(
+  new Option("--instructions", "Print only the build instructions").conflicts(["out", "output"])
+).action(async function action32(id, opts) {
   if (opts.output !== void 0) {
     process.stderr.write(
       `Warning: --output is deprecated for apex roadmap handoff; use --out instead. --output will be removed in v${LEGACY_OUTPUT_REMOVAL_VERSION}.
@@ -12811,7 +12823,8 @@ var handoff = new Command("handoff").description("Get the full build brief for a
       classifyStatus(res.status),
       res.errorDetails
     );
-  const payload = res.data ?? {};
+  const payload = res.data;
+  if (!payload) fail(this, "Missing roadmap handoff response");
   const rendered = opts.instructions ? String(payload.instructions ?? "") : `${JSON.stringify(payload, null, 2)}
 `;
   const outputData = opts.instructions ? { roadmapItemId: id, instructions: String(payload.instructions ?? "") } : payload;
@@ -17011,7 +17024,7 @@ async function fieldLabels(command, item) {
     (fields3.ok && fields3.data ? fields3.data.data : []).map((field) => [field.key, field.label])
   );
 }
-var list7 = new Command("list").alias("ls").description("List backlog").option("-n, --limit <n>", "Max results", "50").option("--cursor <cursor>", "Continue from cursor").option("--include-archived", "Include archived backlog items").action(async function(o) {
+var list7 = new Command("list").alias("ls").description("List backlog items identified as apex.backlog_item.v1").option("-n, --limit <n>", "Max results", "50").option("--cursor <cursor>", "Continue from cursor").option("--include-archived", "Include archived backlog items").action(async function(o) {
   const r = await listInsights(
     requireCredentials(),
     kind2,
@@ -17035,7 +17048,7 @@ var list7 = new Command("list").alias("ls").description("List backlog").option("
     )
   );
 });
-var get6 = new Command("get").description("Get a backlog item").argument("<id>", "backlog item ID").action(async function(id) {
+var get6 = new Command("get").description("Get a backlog item identified as apex.backlog_item.v1").argument("<id>", "backlog item ID").action(async function(id) {
   const r = await getInsight(requireCredentials(), kind2, id);
   if (!r.ok || !r.data)
     fail(this, r.error ?? "Failed to get", classifyStatus(r.status), r.errorDetails);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drip-apex/apex-cli",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "license": "MIT",
   "description": "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   "private": false,