@calo-design/cli 0.10.0 → 0.12.0

package/bin/checkpoints.js

@@ -160,15 +160,15 @@ async function cmdSave(args = []) {
  * user doing anything. Best-effort by contract — a checkpoint hiccup must never turn a
  * successful deploy into a failed command.
  */
-async function autoCheckpoint({ root, note, publishedUrl }) {
+async function autoCheckpoint({ root, note, publishedUrl, artifact }) {
   try {
-    await saveFlow({ root, note, publishedUrl, force: true, quiet: true });
+    await saveFlow({ root, note, publishedUrl, artifact, force: true, quiet: true });
   } catch (e) {
     elog(`${c.y("!")} deploy succeeded, but the source checkpoint didn't: ${e.message}`);
   }
 }
 
-async function saveFlow({ root, slugOverride, note = "", force = false, json = false, quiet = false, publishedUrl }) {
+async function saveFlow({ root, slugOverride, note = "", force = false, json = false, quiet = false, publishedUrl, artifact }) {
   if (!fs.existsSync(path.join(root, "package.json"))) {
     throw new Error("no package.json here — run `calo-design save` from a prototype folder");
   }
@@ -212,6 +212,7 @@ async function saveFlow({ root, slugOverride, note = "", force = false, json = f
           ...(basedOn != null ? { "x-calo-based-on": String(basedOn) } : {}),
           ...(isFork && forkedFrom ? { "x-calo-forked-from": forkedFrom } : {}),
           ...(publishedUrl ? { "x-calo-published-url": publishedUrl } : {}),
+          ...(artifact ? { "x-calo-artifact": encodeURIComponent(JSON.stringify(artifact)) } : {}),
           ...(force ? { "x-calo-force": "1" } : {}),
         },
         body: tgz,

package/bin/mirror-push.js

@@ -93,11 +93,28 @@ let easEnv = process.env;
 const easRun = (argv, opts = {}) => { const [b, ...p] = easPrefix(); return run(b, [...p, ...argv], { env: easEnv, ...opts }); };
 const easCapture = (argv, opts = {}) => { const [b, ...p] = easPrefix(); return capture(b, [...p, ...argv], { env: easEnv, ...opts }); };
 
+// Pull the EAS update GROUP id (the immutable per-version ref checkpoints record) out
+// of a `capture()` result from `eas update:list --json`. Regex, not JSON.parse: eas
+// output shapes and banner noise vary by version, and this must stay best-effort.
+function extractEasGroup(captured) {
+  if (!captured || captured.status !== 0 || typeof captured.out !== "string") return undefined;
+  const found = captured.out.match(/"group":\s*"([0-9a-fA-F-]{16,64})"/);
+  return found ? found[1] : undefined;
+}
+
+// The per-version EAS branch/channel name. Deterministic from (slug, group) so any
+// party — CLI, broker page, Mirror launcher — can derive it, but it's also stored in
+// artifact.easBranch so the convention can evolve without re-deriving. EAS channel
+// names share the slug charset; slug ≤63 + "--g" + 8 = ≤74, under EAS's limits.
+const versionBranchOf = (slug, group) => `${slug}--g${String(group).slice(0, 8).toLowerCase()}`;
+
 function runtimeDir() {
   const home = process.env.DESIGNCHEF_HOME || path.join(os.homedir(), ".designchef");
   return path.join(home, "runtime");
 }
-const slugify = (s) => String(s).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "prototype";
+// Capped at 63 (SLUG_RE's bound everywhere else) — an uncapped slug would silently
+// break the checkpoint stamp and overflow EAS channel-name limits on version pins.
+const slugify = (s) => String(s).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63).replace(/-+$/, "") || "prototype";
 const titleize = (s) => String(s).replace(/[-_]+/g, " ").replace(/\b\w/g, (m) => m.toUpperCase());
 
 function appDir(root) {
@@ -839,12 +856,49 @@ async function cmdPush(args) {
     log(c.b("\n✨ Live in the Mirror.") + " Open Calo Mirror and tap Refresh — your prototype is at the top.");
 
     // Deploy-stamped versioning: every successful push leaves a source checkpoint, so
-    // the thing on the phone and its exact source are permanently paired. Best-effort —
-    // never fails the push. (Lazy require: mirror-push is also loaded by art-push.)
+    // the thing on the phone and its exact source are permanently paired. The artifact
+    // records the EAS update GROUP id — the immutable per-version bundle — so a future
+    // Mirror shell can load exactly this version (channel head keeps moving). Group id
+    // capture is best-effort (a quick update:list after the publish); so is the whole
+    // stamp — never fails the push. (Lazy require: mirror-push is also loaded by art-push.)
+    let easGroup;
+    let easBranch;
+    try {
+      // easCapture → { status, out }. Tolerant extraction: eas --json shapes (and
+      // banner noise) vary by version, so regex the output for the first uuid-shaped
+      // `group` value instead of parsing. Known race, accepted as best-effort: this
+      // lists the branch head, so a concurrent push to the same slug in this window
+      // could stamp the other push's group — rare, and a stamp is advisory metadata.
+      easGroup = extractEasGroup(easCapture(["update:list", "--branch", slug, "--limit", "1", "--json", "--non-interactive"], { cwd: stage }));
+      if (easGroup) {
+        // Pin this exact version behind its own channel: `slug--g<group[:8]>`.
+        // republish is a metadata copy (no rebundle); ensureChannel links channel →
+        // branch of the same name, which is what the Mirror's channel-name header
+        // switch loads. This is what makes "open v3 on your phone" possible after
+        // the channel head (slug) has moved on. Best-effort like the whole stamp.
+        const vb = versionBranchOf(slug, easGroup);
+        ensureChannel(stage, vb);
+        const rp = easCapture(
+          ["update:republish", "--group", easGroup, "--destination-branch", vb, "-m", `pin ${slug} @ ${easGroup.slice(0, 8)}`, "--non-interactive"],
+          { cwd: stage }
+        );
+        if (rp.status === 0) easBranch = vb;
+        else warn(`version pin skipped (republish → ${rp.out.trim().split("\n").slice(-1)[0] || rp.status})`);
+      }
+    } catch {
+      /* no artifact ref — the stamp still records source + deep link */
+    }
     await require("./checkpoints").autoCheckpoint({
       root: process.cwd(),
       note: flag(args, "note") || `pushed to the Mirror (${slug})`,
       publishedUrl: `designchef://open/${slug}`,
+      artifact: {
+        kind: "mirror",
+        channel: slug,
+        runtimeVersion: RUNTIME_VERSION,
+        ...(easGroup ? { easGroup } : {}),
+        ...(easBranch ? { easBranch } : {}),
+      },
     });
 
     // Share target: the deep link the Mirror scanner (and iOS camera) opens.
@@ -865,4 +919,4 @@ async function cmdPush(args) {
   }
 }
 
-module.exports = { cmdPush, _s3Put: s3Put, _upsertRegistry: upsertRegistry, _publicBase: PUBLIC_BASE };
+module.exports = { cmdPush, _s3Put: s3Put, _upsertRegistry: upsertRegistry, _publicBase: PUBLIC_BASE, _extractEasGroup: extractEasGroup, _versionBranchOf: versionBranchOf };

package/bin/share.js

@@ -168,10 +168,17 @@ async function cmdShare(args = []) {
       log(c.dim(`  Re-run \`calo-design share\` to update “${slug}” in place. Share the link above.`));
     }
     if (r.version) log(c.dim(`  this version: ${r.version}`));
-    // Deploy-stamped versioning: every successful share leaves a source checkpoint
-    // (with the live URL in its meta), so the deployed thing and its exact source are
-    // permanently paired. Best-effort — never fails the share.
-    await autoCheckpoint({ root, note: flag(args, "note") || `shared to the web (${slug})`, publishedUrl: url });
+    // Deploy-stamped versioning: every successful share leaves a source checkpoint, so
+    // the deployed thing and its exact source are permanently paired. publishedUrl
+    // prefers the IMMUTABLE per-deploy URL (Cloudflare Pages keeps every deployment
+    // forever) so the version page opens exactly this version, not whatever the alias
+    // points at by then; the artifact keeps both. Best-effort — never fails the share.
+    await autoCheckpoint({
+      root,
+      note: flag(args, "note") || `shared to the web (${slug})`,
+      publishedUrl: r.version || url,
+      artifact: { kind: "web", aliasUrl: url, ...(r.version ? { deployUrl: r.version } : {}) },
+    });
   } finally {
     try { fs.rmSync(tgz); } catch {}
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calo-design/cli",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "One-line setup for Calo design tooling: logs in with your Calo email and installs the calo-design skill + design-system packages. No GitHub account needed.",
   "bin": {
     "calo-design": "bin/cli.js"