@calo-design/cli 0.9.7 → 0.10.0

package/bin/checkpoints.js

@@ -0,0 +1,359 @@
+"use strict";
+
+/**
+ * Prototype checkpoints & sharing — `calo-design save | open | projects`.
+ *
+ * `save` tars this prototype's SOURCE (node_modules is a runtime symlink, .git and
+ * secrets are excluded, so a snapshot is kilobytes), hands it to the broker, and prints
+ * a share URL that unfurls in Slack. Every project is an append-only stream of immutable
+ * versions under the saver's handle (broker-derived from the login email — spoof-proof).
+ *
+ * `open owner/slug[@v]` unpacks any checkpoint into a fresh folder. The first save from
+ * that folder becomes YOUR fork (provenance recorded in meta.forkedFrom) — the original
+ * stream is never touched. No branches, no merges, no locks: a stale save gets a 409 and
+ * the human decides (--force saves on top; both versions stay in history forever).
+ *
+ * Reads go straight to the public bucket (same posture as art/screenshots); only writes
+ * need the broker session. Conflict/marker state lives in .calo-checkpoint.json at the
+ * prototype root (per-machine; excluded from snapshots).
+ */
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const zlib = require("node:zlib");
+const { spawnSync } = require("node:child_process");
+const { ensureSession, loadSession, BROKER } = require("./login");
+const { _publicBase: PUBLIC_BASE } = require("./mirror-push");
+
+const c = { dim: (s) => `\x1b[2m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`, g: (s) => `\x1b[32m${s}\x1b[0m`, y: (s) => `\x1b[33m${s}\x1b[0m` };
+const log = (s = "") => console.log(s);
+const elog = (s = "") => console.error(s);
+const ok = (s) => log(`${c.g("✓")} ${s}`);
+
+const MARKER = ".calo-checkpoint.json";
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const REF_RE = /^([a-z0-9][a-z0-9-]{0,63})\/([a-z0-9][a-z0-9-]{0,63})(?:@(\d{1,6}))?$/;
+
+// What a snapshot leaves out. .git is the owner's private history; node_modules &
+// build output are reproducible; .env* may hold secrets; the marker is per-machine
+// state; backend.json is a machine-generated pointer to the OWNER's provisioned
+// backend (a fork must provision its own — the worker/ source dir stays IN).
+// EXCLUDE_NAMES (basename match at any depth) must stay in lockstep with the tar
+// --exclude patterns below: the canonical hash walks exactly the set tar archives.
+const EXCLUDE_NAMES = new Set([".git", "node_modules", ".expo", ".expo-shared", "dist", "build", "web-build", ".DS_Store", MARKER, "backend.json"]);
+const EXCLUDES = [...EXCLUDE_NAMES, ".env*"];
+const isExcluded = (name) => EXCLUDE_NAMES.has(name) || name.startsWith(".env");
+
+// Keep byte-identical with the broker's handleOf (src/checkpoints.js) — it's only used
+// here to *predict* fork-vs-continue; the broker's derivation is authoritative.
+const handleOf = (email) => {
+  const local = String(email || "").toLowerCase().split("@")[0];
+  const h = local.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  return SLUG_RE.test(h) ? h : null;
+};
+
+const flag = (args, name) => {
+  const hit = args.find((a) => a.startsWith(`--${name}=`));
+  if (hit) return hit.split("=").slice(1).join("=");
+  const i = args.indexOf(`--${name}`);
+  if (i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")) return args[i + 1];
+  return undefined;
+};
+const has = (args, name) => args.includes(`--${name}`);
+const positionals = (args, valueFlags) =>
+  args.filter((a, i, all) => !a.startsWith("--") && !valueFlags.includes(all[i - 1]));
+
+const slugify = (s) =>
+  String(s || "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
+
+const readMarker = (root) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, MARKER), "utf8"));
+  } catch {
+    return null;
+  }
+};
+const writeMarker = (root, m) => fs.writeFileSync(path.join(root, MARKER), JSON.stringify(m, null, 2) + "\n");
+
+const ago = (ts) => {
+  const s = Math.max(1, Math.floor(Date.now() / 1000) - ts);
+  if (s < 3600) return `${Math.floor(s / 60) || 1}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+};
+
+// The one JSON-output rule: stdout carries EXACTLY the payload (last non-empty line
+// contract, same as `feed --json`); everything human goes to stderr.
+const emitJson = (obj) => process.stdout.write("\n" + JSON.stringify(obj) + "\n");
+
+async function publicJson(key) {
+  const res = await fetch(`${PUBLIC_BASE}/${key}?t=${Date.now()}`, { signal: AbortSignal.timeout(20000) });
+  if (res.status === 404 || res.status === 403) return null;
+  if (!res.ok) throw new Error(`checkpoint storage read failed (HTTP ${res.status}) — try again shortly`);
+  return res.json();
+}
+
+// Canonical content hash: sorted relative paths + sizes + bytes of every included
+// regular file. Deliberately NOT a hash of the tar (tar embeds mtimes, so byte-identical
+// trees re-tarred later would look "changed" — that's how no-op detection breaks).
+// The same function verifies an extracted checkpoint on `open` (an extracted tree has
+// no excluded names left, so the exclusion walk is a no-op there). Symlinks are skipped
+// on both sides (tar archives them as links, not content).
+function walkFiles(root) {
+  const out = [];
+  const rec = (dir, rel) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (isExcluded(e.name)) continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) rec(path.join(dir, e.name), r);
+      else if (e.isFile()) out.push(r);
+    }
+  };
+  rec(root, "");
+  return out.sort();
+}
+function canonicalHash(root) {
+  const h = crypto.createHash("sha256");
+  for (const r of walkFiles(root)) {
+    const buf = fs.readFileSync(path.join(root, r));
+    h.update(r);
+    h.update("\0");
+    h.update(String(buf.length));
+    h.update("\0");
+    h.update(buf);
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+
+// tar the prototype source with the exclusion list; returns { work, tarPath, hash }
+// in a tmpdir the caller must clean up.
+function makeSnapshot(root) {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "calo-ckpt-"));
+  const tarPath = path.join(work, "snapshot.tar");
+  const args = ["-cf", tarPath, ...EXCLUDES.map((e) => `--exclude=${e}`), "-C", root, "."];
+  const r = spawnSync("tar", args, { stdio: ["ignore", "pipe", "pipe"] });
+  if (r.status !== 0) {
+    fs.rmSync(work, { recursive: true, force: true });
+    throw new Error(`tar failed: ${String(r.stderr || r.stdout || "").slice(0, 300)}`);
+  }
+  return { work, tarPath, hash: canonicalHash(root) };
+}
+
+// ---------------------------------------------------------------------- save ----------
+
+async function cmdSave(args = []) {
+  return saveFlow({
+    root: process.cwd(),
+    slugOverride: flag(args, "slug"),
+    note: flag(args, "note") || "",
+    force: has(args, "force"),
+    json: has(args, "json"),
+  });
+}
+
+/**
+ * Deploy-stamped versioning: `share`/`push` call this after a successful publish, so
+ * every deploy leaves a source checkpoint (with the live URL in its meta) without the
+ * 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 }) {
+  try {
+    await saveFlow({ root, note, publishedUrl, 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 }) {
+  if (!fs.existsSync(path.join(root, "package.json"))) {
+    throw new Error("no package.json here — run `calo-design save` from a prototype folder");
+  }
+
+  const session = await ensureSession();
+  const me = handleOf((loadSession() || {}).email);
+  const marker = readMarker(root);
+  const slug = slugify(slugOverride || (marker && marker.slug) || path.basename(root));
+  if (!SLUG_RE.test(slug)) throw new Error(`can't derive a valid slug from this folder name — pass --slug <name>`);
+  note = String(note).slice(0, 500);
+
+  // Fork detection: a marker owned by someone else means this folder came from
+  // `open` on their checkpoint — the first save starts YOUR stream, with provenance.
+  // A tampered/partial marker (hand-copied folder, missing basedOn) must degrade to a
+  // plain fresh save, never to a malformed header that fails the whole checkpoint.
+  const FORKREF = /^[a-z0-9][a-z0-9-]{0,63}\/[a-z0-9][a-z0-9-]{0,63}@\d{1,6}$/;
+  const isFork = !!(marker && marker.owner && me && marker.owner !== me);
+  const basedOn = !isFork && marker && Number.isInteger(marker.basedOn) && marker.basedOn >= 0 ? marker.basedOn : null;
+  let forkedFrom = isFork ? `${marker.owner}/${marker.slug}@${marker.basedOn}` : (marker && marker.forkedFrom) || null;
+  if (forkedFrom && !FORKREF.test(forkedFrom)) forkedFrom = null;
+
+  const snap = makeSnapshot(root);
+  try {
+    if (!force && marker && marker.lastHash === snap.hash) {
+      if (json) emitJson({ ok: true, noop: true, owner: marker.owner, slug, v: marker.basedOn });
+      else log(`${c.dim("Nothing changed since")} v${marker.basedOn} ${c.dim("— no new checkpoint.")}`);
+      return;
+    }
+    const tgz = zlib.gzipSync(fs.readFileSync(snap.tarPath));
+
+    let res;
+    try {
+      res = await fetch(`${BROKER}/v1/checkpoints/save`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${session}`,
+          "content-type": "application/gzip",
+          "x-calo-slug": slug,
+          "x-calo-note": encodeURIComponent(note),
+          "x-calo-hash": snap.hash,
+          ...(basedOn != null ? { "x-calo-based-on": String(basedOn) } : {}),
+          ...(isFork && forkedFrom ? { "x-calo-forked-from": forkedFrom } : {}),
+          ...(publishedUrl ? { "x-calo-published-url": publishedUrl } : {}),
+          ...(force ? { "x-calo-force": "1" } : {}),
+        },
+        body: tgz,
+        signal: AbortSignal.timeout(60000),
+      });
+    } catch (e) {
+      throw new Error(`can't reach the Calo broker at ${BROKER} (${e.message})`);
+    }
+    const body = await res.json().catch(() => ({}));
+
+    if (res.status === 409) {
+      if (json) {
+        emitJson({ ok: false, conflict: true, ...body });
+        process.exitCode = 1;
+        return;
+      }
+      elog(`\n${c.y("!")} ${body.error}`);
+      if (body.headNote) elog(c.dim(`  their v${body.head}: "${body.headNote}" (${body.headAuthor || "?"})`));
+      return void (process.exitCode = 1);
+    }
+    if (!res.ok) throw new Error(body.error || `checkpoint save → HTTP ${res.status}`);
+
+    writeMarker(root, {
+      owner: body.owner,
+      slug: body.slug,
+      basedOn: body.v,
+      forkedFrom,
+      lastHash: snap.hash,
+      savedAt: Math.floor(Date.now() / 1000),
+    });
+
+    if (json) return void emitJson({ ok: true, ...body });
+    if (body.noop) return void log(`${c.dim("Nothing changed since")} v${body.v} ${c.dim("— no new checkpoint.")}`);
+    if (quiet) return void ok(`source checkpoint ${c.b(`v${body.v}`)} — ${body.url}`);
+    ok(`checkpoint ${c.b(`v${body.v}`)} — ${body.owner}/${body.slug}${note ? c.dim(`  "${note}"`) : ""}`);
+    log(`  ${c.b(c.g(body.url))}`);
+    log(c.dim("  Paste that link in Slack — it unfurls with the note. Teammates open it with:"));
+    log(c.dim(`    calo-design open ${body.owner}/${body.slug}@${body.v}`));
+  } finally {
+    fs.rmSync(snap.work, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------- open ----------
+
+async function cmdOpen(args = []) {
+  const json = has(args, "json");
+  const pos = positionals(args, []);
+  const ref = pos[0] || "";
+  const m = REF_RE.exec(ref);
+  if (!m) throw new Error("usage: calo-design open <owner>/<slug>[@version] [folder]");
+  const [, owner, slug, vRaw] = m;
+
+  const idx = await publicJson(`checkpoints/${owner}/${slug}/index.json`);
+  const versions = idx && Array.isArray(idx.versions) ? idx.versions : [];
+  const head = versions.reduce((mx, e) => Math.max(mx, e.v | 0), 0);
+  const v = vRaw ? Number(vRaw) : head;
+  const meta = versions.find((e) => (e.v | 0) === v) || (await publicJson(`checkpoints/${owner}/${slug}/v${v}/meta.json`));
+  if (!meta) throw new Error(`no checkpoint found at ${owner}/${slug}${vRaw ? `@${vRaw}` : ""} — check the link, or ask for a fresh one`);
+
+  const dir = path.resolve(process.cwd(), pos[1] || (vRaw && v !== head ? `${slug}-v${v}` : slug));
+  if (fs.existsSync(dir) && fs.readdirSync(dir).filter((f) => f !== ".DS_Store").length) {
+    throw new Error(`${path.basename(dir)}/ already exists and isn't empty — pass a new folder name: calo-design open ${ref} <folder>`);
+  }
+
+  const res = await fetch(`${PUBLIC_BASE}/checkpoints/${owner}/${slug}/v${v}/snapshot.tar.gz?t=${Date.now()}`, {
+    signal: AbortSignal.timeout(60000),
+  });
+  if (!res.ok) throw new Error(`snapshot download failed (HTTP ${res.status}) — try again shortly`);
+  const tgz = Buffer.from(await res.arrayBuffer());
+  const tar = zlib.gunzipSync(tgz, { maxOutputLength: 200e6 });
+
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "calo-ckpt-"));
+  try {
+    const tarPath = path.join(work, "snapshot.tar");
+    fs.writeFileSync(tarPath, tar);
+    fs.mkdirSync(dir, { recursive: true });
+    const r = spawnSync("tar", ["-xf", tarPath, "-C", dir], { stdio: ["ignore", "pipe", "pipe"] });
+    if (r.status !== 0) throw new Error(`extract failed: ${String(r.stderr || r.stdout || "").slice(0, 300)}`);
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+
+  // Integrity: recompute the canonical content hash over what actually landed on disk
+  // (an extracted tree has no excluded names, so this walks exactly the snapshot set).
+  const gotHash = canonicalHash(dir);
+  if (meta.contentHash && gotHash !== meta.contentHash) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    throw new Error("snapshot failed its integrity check (content hash mismatch) — retry; if it persists, ask for a fresh checkpoint link");
+  }
+
+  writeMarker(dir, {
+    owner,
+    slug,
+    basedOn: v,
+    forkedFrom: `${owner}/${slug}@${v}`,
+    lastHash: meta.contentHash || gotHash,
+    openedAt: Math.floor(Date.now() / 1000),
+  });
+
+  if (json) return void emitJson({ ok: true, owner, slug, v, dir, note: meta.note || "" });
+  ok(`opened ${c.b(`${owner}/${slug} v${v}`)} → ${path.basename(dir)}/${meta.note ? c.dim(`  "${meta.note}"`) : ""}`);
+  const mine = handleOf((loadSession() || {}).email);
+  log(`\n  ${c.b("1.")} ${c.g(`cd ${path.relative(process.cwd(), dir) || "."}`)}  then run ${c.g("calo-design init")} ${c.dim("(links the shared runtime)")}`);
+  log(`  ${c.b("2.")} Work on it in Claude Code (${c.g("/calo-design")}).`);
+  log(`  ${c.b("3.")} ${c.g("calo-design save")} ${c.dim(`publishes it as YOUR fork${mine ? ` (${mine}/${slug})` : ""} — ${owner}'s stream is never touched.`)}`);
+  if (fs.existsSync(path.join(dir, "worker"))) {
+    log(c.dim("\n  This prototype has a worker/ backend — run `calo-design backend init` to provision your own copy of it."));
+  }
+}
+
+// ------------------------------------------------------------------- projects ---------
+
+async function cmdProjects(args = []) {
+  const json = has(args, "json");
+  const session = await ensureSession();
+  let res;
+  try {
+    res = await fetch(`${BROKER}/v1/checkpoints/list`, {
+      headers: { authorization: `Bearer ${session}` },
+      signal: AbortSignal.timeout(15000),
+    });
+  } catch (e) {
+    throw new Error(`can't reach the Calo broker at ${BROKER} (${e.message})`);
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body.error || `checkpoints list → HTTP ${res.status}`);
+  let projects = Array.isArray(body.projects) ? body.projects : [];
+  projects.sort((a, b) => (b.ts || 0) - (a.ts || 0));
+  if (has(args, "mine")) {
+    const me = handleOf((loadSession() || {}).email);
+    projects = projects.filter((p) => p.owner === me);
+  }
+  if (json) return void emitJson({ ok: true, projects });
+  if (!projects.length) return void log(c.dim("No shared prototypes yet — `calo-design save` in a prototype folder mints the first one."));
+  log(c.b(`\nShared prototypes (${projects.length}):\n`));
+  for (const p of projects) {
+    const who = handleOf(p.author) || p.owner;
+    log(`  ${c.b(`${p.owner}/${p.slug}`)} ${c.g(`v${p.head}`)}  ${p.note ? `"${p.note}"` : c.dim("(no note)")}`);
+    log(c.dim(`    ${who} · ${p.ts ? ago(p.ts) : "?"}${p.forkedFrom ? ` · forked from ${p.forkedFrom}` : ""}  →  calo-design open ${p.owner}/${p.slug}`));
+  }
+  log("");
+}
+
+module.exports = { cmdSave, cmdOpen, cmdProjects, autoCheckpoint, _handleOf: handleOf, _makeSnapshot: makeSnapshot, _canonicalHash: canonicalHash, _EXCLUDES: EXCLUDES };

package/bin/cli.js

@@ -21,6 +21,7 @@ const { cmdShare } = require("./share");
 const { cmdImage } = require("./imagegen");
 const { cmdLogin, cmdLogout, ensureLoggedIn, githubToken, reportEvent, ensureSession, loadSession, BROKER } = require("./login");
 const { cmdFeedback, cmdTasks } = require("./feedback");
+const { cmdSave, cmdOpen, cmdProjects } = require("./checkpoints");
 
 const ORG = "Calo-Design";
 const SKILL_REPO = `${ORG}/calo-design`;
@@ -781,6 +782,10 @@ function help() {
   ${c.dim("    share --slug x --dir dist --build --project calo-prototypes  --dry-run")}
   ${c.dim("gallery")}                                   serve the @calo/design-system component gallery locally (live from the runtime)
   ${c.dim("    gallery --port 8091")}
+  ${c.dim("save")}                                      checkpoint THIS prototype's source → share URL (append-only; login only)
+  ${c.dim("    save --note \"what changed\"  --slug x  --force  --json")}
+  ${c.dim("open <owner>/<slug>[@v] [folder]")}          unpack a teammate's checkpoint; your first save becomes your own fork
+  ${c.dim("projects")}                                  all shared prototypes (--mine, --json)
   ${c.dim("feedback [slug]")}                           feedback inbox for shared prototypes (open threads; --all, --json)
   ${c.dim("    feedback new <slug> <text>   comment|resolve|reopen <threadId>   shot <slug> <png>")}
   ${c.dim("tasks [slug]")}                              triaged work items (--status todo|in_progress|done|wontfix, --json)
@@ -811,6 +816,9 @@ function help() {
     else if (cmd === "gallery") await cmdGallery();
     else if (cmd === "feedback") await cmdFeedback(args.slice(1));
     else if (cmd === "tasks") await cmdTasks(args.slice(1));
+    else if (cmd === "save") await cmdSave(args.slice(1));
+    else if (cmd === "open") await cmdOpen(args.slice(1));
+    else if (cmd === "projects") await cmdProjects(args.slice(1));
     else help();
   } catch (err) {
     // Diagnostics go to stderr so stdout stays pure for machine callers (The Pass parses

package/bin/mirror-push.js

@@ -838,6 +838,15 @@ 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.)
+    await require("./checkpoints").autoCheckpoint({
+      root: process.cwd(),
+      note: flag(args, "note") || `pushed to the Mirror (${slug})`,
+      publishedUrl: `designchef://open/${slug}`,
+    });
+
     // Share target: the deep link the Mirror scanner (and iOS camera) opens.
     // Print it + a scannable QR so a teammate can jump straight in.
     const deepLink = `designchef://open/${slug}`;

package/bin/share.js

@@ -21,6 +21,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const { publishWeb } = require("./login");
+const { autoCheckpoint } = require("./checkpoints");
 
 const PROJECT = process.env.CALO_PAGES_PROJECT || "calo-prototypes";
 const aliasUrl = (slug, project) => `https://${slug}.${project}.pages.dev`;
@@ -167,6 +168,10 @@ 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 });
   } finally {
     try { fs.rmSync(tgz); } catch {}
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calo-design/cli",
-  "version": "0.9.7",
+  "version": "0.10.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"