@drip-apex/apex-cli 0.8.0 → 0.9.0

package/README.md

@@ -313,3 +313,18 @@ 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. |

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.0",
+  version: "0.9.0",
   license: "MIT",
   description: "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   private: false,
@@ -8969,6 +8969,16 @@ function buildQaPreviewUrl2(storeUrl, experimentId, variationId) {
   return url;
 }
 
+// src/lib/device-label.ts
+function deviceLabel(targeting) {
+  if (!targeting || typeof targeting !== "object") return void 0;
+  const device = targeting.deviceType;
+  if (device === "desktop") return "Desktop only";
+  if (device === "mobile") return "Mobile only";
+  if (device === "tablet") return "Tablet only";
+  return void 0;
+}
+
 // src/lib/test-key.ts
 var TEST_KEY_RE = /^([A-Z0-9]{2,8})-(\d+)$/;
 function isTestKeyReference(value) {
@@ -9279,8 +9289,13 @@ function printExperiment(exp, dashboardUrl = null) {
   console.log(`  Status:  ${statusBadge(exp.status)}`);
   console.log(`  Classification: ${exp.counting_type}`);
   console.log(`  Traffic: ${(exp.traffic_allocation * 100).toFixed(0)}%`);
+  console.log(`  QA approved: ${exp.qa_approved_at ?? "none"}`);
+  console.log(`  Scheduled: ${exp.scheduled_start_at ?? "none"}`);
+  console.log(`  Started: ${exp.started_at ?? "none"}`);
   if (exp.targeting !== void 0) {
     console.log(`  Targeting: ${effectivePageTargetingLabel(exp.targeting)}`);
+    const device = deviceLabel(exp.targeting);
+    if (device) console.log(`  Device: ${device}`);
   }
   console.log(`  Created: ${formatDate(exp.created_at)}`);
   if (exp.linked_idea) {
@@ -9560,6 +9575,9 @@ function printFilesystemPlan(plan) {
     console.log(source_default.dim("  No changes."));
   } else {
     plan.changes.forEach((change) => {
+      if (change.entity === "experiment.targeting" && Array.isArray(change.detail?.changedKeys)) {
+        console.log(`  Changed keys: ${change.detail.changedKeys.join(", ")}`);
+      }
       const pathLabel = change.path ? source_default.dim(` ${change.path}`) : "";
       const qa3 = change.invalidatesQa ? source_default.yellow(" invalidates QA") : "";
       console.log(
@@ -9826,7 +9844,9 @@ var list = new Command("list").alias("ls").description("List experiments (archiv
     }
   });
 });
-var get = new Command("get").description("Get experiment details by ID or slug").argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).action(async function action4(idOrSlug) {
+var get = new Command("get").description(
+  "Get experiment details by ID or slug. JSON readback always carries started_at, scheduled_start_at and qa_approved_at as ISO-8601 UTC timestamps or null (all null on a fresh draft)."
+).argument("<id-or-slug>", EXPERIMENT_REFERENCE_DESCRIPTION).action(async function action4(idOrSlug) {
   const spinner = await createSpinner("Fetching experiment...");
   const exp = await resolveExperiment(idOrSlug);
   spinner?.stop();
@@ -10140,7 +10160,9 @@ ${rows.map((row, index) => `  ${index + 1}. ${row.name} (${row.id})`).join("\n")
 `
   );
 }
-var create = new Command("create").description("Create a new experiment").addOption(
+var create = new Command("create").description(
+  "Create a complete experiment with page targeting, audiences, goals, and an optional QA preview URL. JSON readback always carries started_at, scheduled_start_at and qa_approved_at as ISO-8601 UTC timestamps or null (all null on a fresh draft)."
+).addOption(
   new Option("--counting-type <type>", "Experiment classification").choices(countingTypes).default("standard")
 ).option("--name <name>", "Experiment name").option("--slug <slug>", "URL-safe slug for GitOps").option("--description <desc>", "Description").option("--type <type>", "Experiment type: mutation or redirect", "mutation").option(
   "--source-url <pattern>",
@@ -10963,6 +10985,7 @@ var qaApprove = new Command("approve").description("Approve QA and move the expe
       {
         experimentId: resolved.experimentId,
         qaStatus: "done",
+        experiment: res.data,
         experiment_status_before: before.status,
         experiment_status_after: res.data.status,
         transition
@@ -12767,7 +12790,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}.
@@ -12788,7 +12815,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;
@@ -16988,7 +17016,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,
@@ -17012,7 +17040,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.0",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   "private": false,