@calo-design/cli 0.2.1 → 0.4.0

package/README.md

@@ -1,54 +1,67 @@
-# @calo-design/cli — one-line Calo design setup
+# @calo-design/cli
 
-A tiny **installer** (not a runtime). It logs you in with your Calo email, sets up the
-[`calo-design`](https://github.com/Calo-Design/calo-design) Claude Code skill and the
-design-system packages, then gets out of the way — the Claude Code agent is the
-runtime, the skill is the guidance.
+One-line setup for Calo design tooling. It's a small **installer**, not a runtime: it
+logs you in with your Calo email, installs the `calo-design` Claude Code skill, and sets
+up the design-system stack (`@calo/design-system` + `@calo/flows` + the React Native
+peers) on your machine. After that it gets out of the way — Claude Code is the runtime,
+the skill is the guidance.
 
-**No GitHub account, PAT, or SSH key needed.** Access is gated by your `@calo.app`
-email via the Calo broker, which mints a short-lived GitHub token at install time.
+Access is gated by your `@calo.app` email through the Calo broker, which mints a
+short-lived GitHub token at install time. No GitHub account, PAT, or SSH key needed.
 
-## Use
+Package: https://www.npmjs.com/package/@calo-design/cli
+
+## Setup
 
 ```bash
-npx @calo-design/cli login          # one-time: enter your Calo email + the emailed code
-npx @calo-design/cli init           # skill + @calo/design-system + @calo/flows + RN peers
+npx @calo-design/cli login    # one-time: your Calo email + the emailed code
+npx @calo-design/cli init     # skill + the shared ds/flows runtime, and a prototype here
 ```
 
-Then start a new Claude Code session and ask for a screen
-(e.g. *"build a Calo-native meal-swap screen"*).
+> **`@calo-design/cli` is a public npm package.** If npx reports it can't be found — "not in
+> this registry", "404", or "not a public package" — your npm is pointed at a private or
+> corporate registry that doesn't carry it (common on managed laptops). Check with
+> `npm config get registry` (it should be `https://registry.npmjs.org/`). To run regardless
+> of your `.npmrc`, pin just this scope to public npm:
+>
+> ```bash
+> npx --@calo-design:registry=https://registry.npmjs.org/ @calo-design/cli login
+> ```
+
+`init` does two machine-level things every time: it installs the skill into
+`~/.claude/skills/`, and it ensures the shared runtime at `~/.designchef/runtime/` — one
+copy of `@calo/design-system`, `@calo/flows`, Expo and the peers, shared by every
+prototype. Then, if the current folder is empty or an existing Expo project, it links a
+prototype here that points at that runtime.
+
+To start a prototype from inside a workspace folder (where the current directory isn't
+empty), give it a name and `init` creates the subfolder for you:
 
 ```bash
-npx @calo-design/cli init --skip-packages   # skill only
-npx @calo-design/cli update                 # re-install latest skill + re-pin the shared runtime
-npx @calo-design/cli logout                 # forget the saved session
+npx @calo-design/cli init my-prototype   # creates ./my-prototype/ and links it
+cd my-prototype
+npx expo start                           # press w for web, or scan the QR in Expo Go
 ```
 
-The login session is stored at `~/.designchef/session.json` (chmod 600) and refreshes
-automatically. Override the broker with `CALO_BROKER_URL` (used for local dev).
-
-## Publish
-
-Share a prototype with the team via the [Calo Mirror](https://github.com/Calo-Design/calo-design-mirror).
-Run from **inside a standalone prototype folder** (a plain Expo app with a `src/app/` route dir):
+Other commands:
 
 ```bash
-calo-design push --slug <slug> --title "<Title>" --owner "<name>" --message "<msg>"
+npx @calo-design/cli init --skip-packages   # skill only, no runtime
+npx @calo-design/cli init --isolated        # install the stack into THIS folder (no shared runtime)
+npx @calo-design/cli update                 # refresh the skill + re-pin the shared runtime
+npx @calo-design/cli logout                 # forget the saved session
 ```
 
-**No EAS or Tigris credentials needed** — just `calo-design login`. The broker vends the
-Expo token for the `eas update` and performs the registry write server-side. It does two things:
+The login session lives at `~/.designchef/session.json` (chmod 600) and refreshes
+automatically. Set `CALO_BROKER_URL` to point at a local broker for development.
 
-- `eas update --branch <slug>` — publishes the prototype's JS bundle to its own EAS Update
-  channel in the shared project (creating the channel on first push; latest wins on re-push).
-  Bundling runs locally; auth uses the broker-vended Expo token.
-- Hands the registry entry (and `screenshot.png` if present) to the broker, which upserts the
-  Tigris `index.json` feed so the prototype shows up in the Mirror's browsable list.
+## Building a screen
 
-Use `--dry-run` to stage a managed copy and print what would happen, without publishing.
-`--direct` is the legacy path that publishes from your own local EAS + Tigris creds (maintainer/debug).
+Start a Claude Code session in a prototype folder, load the skill with `/calo-design`,
+and describe the screen — for example, "build a Calo-native meal-swap screen." The skill
+composes it from the design-system primitives.
 
-Fonts ship with `@calo/design-system`. Load them in your root layout:
+Fonts ship with `@calo/design-system`; load them in your root layout:
 
 ```tsx
 import { useFonts } from "expo-font";
@@ -56,20 +69,44 @@ import { caloFonts } from "@calo/design-system";
 const [fontsLoaded] = useFonts(caloFonts);
 ```
 
+## Publishing to the Mirror
+
+Run from inside a standalone prototype folder (a plain Expo app with a `src/app/` route
+directory):
+
+```bash
+calo-design push --slug <slug> --title "<Title>" --owner "<name>" --message "<msg>"
+```
+
+No EAS or Tigris credentials needed — just `calo-design login`. The broker vends the Expo
+token and writes the registry server-side. Under the hood it:
+
+- runs `eas update --branch <slug>` to publish the prototype's JS bundle to its own EAS
+  Update channel in the shared project (created on first push; latest wins on re-push).
+  Bundling runs locally; auth uses the broker-vended Expo token.
+- hands the registry entry (and `screenshot.png` if present) to the broker, which upserts
+  the Tigris `index.json` feed so the prototype appears in the Mirror's browsable list.
+
+`--dry-run` stages a managed copy and prints what would happen without publishing.
+`--direct` is the legacy path that publishes from your own local EAS + Tigris credentials
+(maintainer/debug).
+
 ## How access works
 
 ```
-npx @calo-design/cli login → broker verifies @calo.app + emails OTP → session JWT (~/.designchef)
-npx @calo-design/cli init  → broker mints a 1h read-only GitHub token → private npm installs
-calo-design push           → broker vends the Expo token + writes the Mirror registry server-side
+login → broker verifies @calo.app + emails a code → session JWT in ~/.designchef
+init  → broker mints a 1-hour read-only GitHub token → private installs
+push  → broker vends the Expo token + writes the Mirror registry server-side
 ```
 
-The broker (`../calo-broker`) is the only place the GitHub / Expo / Tigris secrets
-live. See its README for the one-time provisioning checklist.
+The broker is the only place the GitHub / Expo / Tigris secrets live.
+
+## Local development
 
-## Tests
+Point the CLI at a local broker and run the client-spine test:
 
 ```bash
-# with a dev broker running (cd ../calo-broker && npm run dev):
+cd ../calo-broker && npm run dev                                 # one shell
+CALO_BROKER_URL=http://localhost:8080 npx @calo-design/cli login # another shell
 BASE=http://localhost:8080 bash test/client-spine.sh
 ```

package/bin/cli.js

@@ -16,6 +16,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const { cmdPush } = require("./mirror-push");
+const { cmdShare } = require("./share");
 const { cmdLogin, cmdLogout, ensureLoggedIn, githubToken } = require("./login");
 
 const ORG = "Calo-Design";
@@ -130,9 +131,23 @@ function runtimeExists() {
   );
 }
 
+// expo-router needs babel-preset-expo (its Babel plugin injects the route require.context);
+// without a babel.config.js, `expo export` produces an empty, routeless app. The shared
+// runtime isn't always scaffolded with one, so guarantee it. Linked prototypes inherit it
+// via writeThinConfigs; push staging backstops it again (see mirror-push.js).
+function ensureBabelConfig(dir) {
+  const p = path.join(dir, "babel.config.js");
+  if (fs.existsSync(p)) return;
+  fs.writeFileSync(p, 'module.exports = (api) => {\n  api.cache(true);\n  return { presets: ["babel-preset-expo"] };\n};\n');
+}
+
 async function ensureRuntime({ force } = {}) {
   const rt = runtimeDir();
-  if (!force && runtimeExists()) { ok(`shared runtime ready (${tilde(rt)})`); return; }
+  if (!force && runtimeExists()) {
+    ensureBabelConfig(rt); // backfill: runtimes built before this shipped no babel.config.js
+    ok(`shared runtime ready (${tilde(rt)})`);
+    return;
+  }
   log(c.b("\n[runtime] Building the shared Calo runtime (one-time, ~a couple of minutes)"));
   fs.mkdirSync(rt, { recursive: true });
   if (force) {
@@ -143,6 +158,7 @@ async function ensureRuntime({ force } = {}) {
     if (!scaffoldExpoApp(rt)) throw new Error("runtime scaffold failed");
   }
   await installCaloDeps(rt);
+  ensureBabelConfig(rt); // a freshly scaffolded runtime may also lack one
   fs.writeFileSync(
     runtimeManifestPath(),
     JSON.stringify({ builtAt: new Date().toISOString(), pkgSpecs: PKG_SPECS, peers: PEERS }, null, 2) + "\n"
@@ -369,18 +385,20 @@ function isExistingProject() {
 
 // ---------------------------------------------------------------- commands
 
-function nextSteps({ linked } = {}) {
+function nextSteps({ linked, cd } = {}) {
   log(c.b("\n✨ Done. In Claude Code — no restart needed:"));
-  log(`\n  ${c.b("1.")} Load the skill — type:`);
+  let n = 1;
+  if (cd) log(`\n  ${c.b(n++ + ".")} Enter the prototype — run ${c.b(c.g("cd " + cd))}`);
+  log(`\n  ${c.b(n++ + ".")} Load the skill — type:`);
   log(`       ${c.b(c.g("/calo-design"))}`);
-  log(`\n  ${c.b("2.")} Create a prototype — describe the screen, e.g.:`);
+  log(`\n  ${c.b(n++ + ".")} Create a prototype — describe the screen, e.g.:`);
   log(`       ${c.b(c.g("build a Calo-native meal-swap screen"))}`);
-  log(`\n  ${c.b("3.")} Preview — run ${c.dim("npx expo start")} (press w for web, or scan the QR in Expo Go).`);
+  log(`\n  ${c.b(n++ + ".")} Preview — run ${c.dim("npx expo start")} (press w for web, or scan the QR in Expo Go).`);
   if (linked) {
     log(c.dim(`\n  This prototype shares one install at ${tilde(runtimeDir())} — \`calo-design update\` refreshes it for every prototype.`));
     log(c.dim("  (expo-doctor may flag dependency versions on linked projects; that's expected and harmless.)"));
   }
-  log(c.dim(`\n  Docs: https://github.com/${SKILL_REPO}`));
+  log(c.dim(`\n  Docs: https://www.npmjs.com/package/@calo-design/cli`));
 }
 
 async function cmdInit() {
@@ -389,40 +407,63 @@ async function cmdInit() {
   if (has("--skip-packages")) return nextSteps({});
   if (has("--isolated")) { await installHere(); return nextSteps({}); }
 
-  if (isLinkedProject()) {
-    // Re-running in an already-linked prototype: ensure runtime + refresh the link.
+  // `init <name>`: create ./<name>/ and set the prototype up there, so you can spin
+  // one up from inside a workspace container without cd-ing into an empty folder first.
+  const targetName = args.slice(1).find((a) => !a.startsWith("-"));
+  if (targetName) {
+    const dir = path.resolve(process.cwd(), targetName);
+    fs.mkdirSync(dir, { recursive: true });
+    process.chdir(dir);
+    log(c.dim(`\n  Prototype folder: ${tilde(dir)}`));
+  }
+  const cd = targetName;
+
+  // Machine setup runs every time, independent of this folder: the skill is installed
+  // above; ensure the shared runtime so @calo/design-system + @calo/flows live on this
+  // machine (one copy, shared by every prototype).
+  let runtimeReady = true;
+  try {
     await ensureRuntime({ force: false });
-    linkProject(process.cwd());
-    return nextSteps({ linked: true });
+  } catch (e) {
+    runtimeReady = false;
+    warn(`couldn't build the shared runtime (${e.message}).`);
+  }
+
+  // Per-folder prototype (a separate, optional step): link or scaffold one here.
+  if (isLinkedProject()) {
+    // Re-running in an already-linked prototype: refresh the link if the runtime is ok.
+    if (runtimeReady) linkProject(process.cwd());
+    else warn("shared runtime unavailable — left the existing link untouched.");
+    return nextSteps({ linked: true, cd });
   }
   if (isExistingProject()) {
     warn("existing project detected — installing the Calo stack here (not linking), to avoid clobbering your node_modules.");
     await installCaloDeps(process.cwd());
     ok("packages + peers installed in this project");
-    return nextSteps({});
+    return nextSteps({ cd });
   }
   if (!dirIsScaffoldable()) {
-    warn("this folder isn't empty and isn't an Expo project.");
-    log(c.dim("  Run init in an empty folder to use the shared runtime, or `init --isolated` to install here."));
+    // Machine setup is done; we just won't scaffold a prototype into a non-empty,
+    // non-Expo folder (e.g. a workspace container). Say what's ready and how to proceed.
+    log("");
+    ok(`Machine setup complete — skill installed${runtimeReady ? ", ds + flows runtime ready" : ""}.`);
+    if (runtimeReady) log(c.dim(`  ds + flows live at ${tilde(path.join(runtimeDir(), "node_modules", "@calo"))}, shared by every prototype.`));
+    warn("No prototype scaffolded here — this folder isn't empty and isn't an Expo project.");
+    log(`  Create one with:  ${c.b(c.g("npx @calo-design/cli init <name>"))}  ${c.dim("(makes ./<name>/ and links it)")}`);
+    log(c.dim("  …or run init in an empty folder or an existing Expo project, or pass --isolated to install into this folder."));
     return;
   }
 
-  // Fresh prototype folder → shared runtime + symlink, with graceful fallbacks.
-  try {
-    await ensureRuntime({ force: false });
-  } catch (e) {
-    warn(`couldn't build the shared runtime (${e.message}); falling back to a per-project install.`);
-    await installHere();
-    return nextSteps({});
-  }
+  // Fresh prototype folder → link to the shared runtime, with a per-project fallback.
+  if (!runtimeReady) { await installHere(); return nextSteps({ cd }); }
   try {
     linkProject(process.cwd());
   } catch (e) {
     warn(`couldn't link to the shared runtime (${e.message}); falling back to a per-project install.`);
     await installHere();
-    return nextSteps({});
+    return nextSteps({ cd });
   }
-  nextSteps({ linked: true });
+  nextSteps({ linked: true, cd });
 }
 
 async function cmdUpdate() {
@@ -441,15 +482,20 @@ function help() {
   log(`${c.b("calo-design")} — one-line setup for Calo design tooling
 
   ${c.b("npx @calo-design/cli login")}               log in with your Calo email (one-time; no GitHub account needed)
-  ${c.b("npx @calo-design/cli init")}                skill + a prototype linked to the shared runtime (empty folder, or an existing project)
-  ${c.dim("init --isolated")}                          install the Calo stack into THIS project (no shared runtime)
-  ${c.dim("init --skip-packages")}                      skill only
+  ${c.b("npx @calo-design/cli init")}                skill + shared ds/flows runtime, and link a prototype in this folder
+  ${c.b("npx @calo-design/cli init <name>")}         same, but scaffold the prototype in ./<name>/ (handy inside a workspace)
+  ${c.dim("init --isolated")}                          install the Calo stack into THIS folder (no shared runtime)
+  ${c.dim("init --skip-packages")}                      skill only (no runtime)
   ${c.dim("update")}                                    refresh the skill + re-pin the shared runtime (all linked prototypes float to latest)
   ${c.dim("logout")}                                    forget the saved Calo session
   ${c.dim("push")}                                      publish THIS prototype to the Calo Mirror (login only — no EAS/Tigris creds needed)
   ${c.dim("    push --slug x --title \"…\" --owner \"…\" --screenshot path  --dry-run  --direct")}
+  ${c.dim("share")}                                     publish THIS web prototype (React/Vite/CRA/Next) to Cloudflare Pages → share link
+  ${c.dim("    share --slug x --dir dist --build --project calo-prototypes  --dry-run")}
 
   Login is required once before init; the session refreshes automatically.
+  init always installs the skill and ensures the shared ds/flows runtime on your machine;
+  scaffolding a prototype is a separate step (needs an empty folder, an Expo project, or a name).
   Prototypes share one install at ${c.dim(tilde(runtimeDir()))} (override with DESIGNCHEF_HOME).
 `);
 }
@@ -461,6 +507,7 @@ function help() {
     else if (cmd === "init") await cmdInit();
     else if (cmd === "update") await cmdUpdate();
     else if (cmd === "push") await cmdPush(args.slice(1));
+    else if (cmd === "share") await cmdShare(args.slice(1));
     else help();
   } catch (err) {
     log(`\n\x1b[31m✗\x1b[0m ${err.message}`);

package/bin/login.js

@@ -155,6 +155,34 @@ async function easToken() {
   return r.token;
 }
 
+// Hand a built web prototype (gzipped tarball) to the broker, which runs
+// `wrangler pages deploy` server-side — its Cloudflare token never reaches the client —
+// and returns the share URL. slug = Pages branch alias. Raw body (not JSON), so it
+// doesn't use api().
+async function publishWeb({ slug, project, tarball }) {
+  const session = await ensureSession();
+  let res;
+  try {
+    res = await fetch(BROKER + "/v1/publish-web", {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${session}`,
+        "content-type": "application/gzip",
+        "x-calo-slug": slug,
+        ...(project ? { "x-calo-project": project } : {}),
+      },
+      body: tarball,
+    });
+  } catch (e) {
+    throw new Error(`can't reach the Calo broker at ${BROKER} (${e.message})`);
+  }
+  const text = await res.text();
+  let json;
+  try { json = text ? JSON.parse(text) : {}; } catch { json = { raw: text }; }
+  if (!res.ok) throw new Error([json.error || `publish-web → HTTP ${res.status}`, json.detail].filter(Boolean).join("\n  "));
+  return json;
+}
+
 // Hand a built registry entry (+ optional base64 screenshot) to the broker, which
 // performs the Tigris writes server-side. Returns the broker's JSON result.
 async function publishToMirror(payload) {
@@ -162,4 +190,4 @@ async function publishToMirror(payload) {
   return api("/v1/publish", payload, session);
 }
 
-module.exports = { cmdLogin, cmdLogout, ensureSession, ensureLoggedIn, githubToken, easToken, publishToMirror, BROKER, loadSession };
+module.exports = { cmdLogin, cmdLogout, ensureSession, ensureLoggedIn, githubToken, easToken, publishWeb, publishToMirror, BROKER, loadSession };

package/bin/mirror-push.js

@@ -122,6 +122,18 @@ function writeJSON(p, obj) {
   fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
 }
 
+// A babel.config.js with babel-preset-expo MUST exist wherever `expo export` runs. Without
+// it the expo-router Babel plugin never injects the route require.context, so the export is
+// a routeless, empty shell (no screens, no design system, no assets). The shared runtime
+// doesn't always ship one, so guarantee it: prefer the prototype's own config, else default.
+function ensureBabelConfig(dir, fallbackFrom) {
+  const dst = path.join(dir, "babel.config.js");
+  if (fs.existsSync(dst)) return;
+  const fb = fallbackFrom && path.join(fallbackFrom, "babel.config.js");
+  if (fb && fs.existsSync(fb)) { fs.cpSync(fb, dst); return; }
+  fs.writeFileSync(dst, 'module.exports = (api) => {\n  api.cache(true);\n  return { presets: ["babel-preset-expo"] };\n};\n');
+}
+
 function stageProject({ root, stage, slug, title, ad }) {
   // Copy the author's routes + assets verbatim.
   const stageSrcParent = path.join(stage, path.relative(root, path.dirname(ad)));
@@ -164,6 +176,9 @@ function stageProject({ root, stage, slug, title, ad }) {
     const src = path.join(runtimeDir(), f);
     if (fs.existsSync(src)) fs.cpSync(src, path.join(stage, f));
   }
+  // The runtime may not have a babel.config.js; without one the staged export is an empty,
+  // routeless app. Backstop it from the prototype's own config, else a default.
+  ensureBabelConfig(stage, root);
 
   writeMetroConfig(stage);
   linkNodeModules(stage);
@@ -213,7 +228,7 @@ function injectBackChrome({ stagedAppDir, mirrorChromeDir, libRel }) {
   if (fs.existsSync(layout)) {
     const cur = fs.readFileSync(layout, "utf8");
     const standard = /useFonts\(caloFonts\)/.test(cur) && /<Stack/.test(cur);
-    if (!standard) warn("custom root _layout detected — Mirror wraps it with a Stack; custom providers won't carry over.");
+    if (!standard) warn("custom root _layout detected — Mirror wraps it with a Stack; providers in the ROOT layout won't carry over. Move them to a nested layout (e.g. src/app/(group)/_layout.tsx), which the Mirror preserves.");
   }
   fs.writeFileSync(
     layout,

package/bin/share.js

@@ -0,0 +1,170 @@
+"use strict";
+
+/**
+ * `calo-design share` — publish THIS web prototype (a static React / Vite / CRA /
+ * Next-export build) to Cloudflare Pages and print a share link.
+ *
+ * Default: tar the build → POST it to the broker (/v1/publish-web) → the broker runs
+ * `wrangler pages deploy` server-side with its own token and returns the URL. Teammates
+ * need only `calo-design login` — no Cloudflare account, no wrangler, nothing to install.
+ *
+ * `--direct`: deploy from here with your own `wrangler login` (no broker) — for
+ * debugging or when the broker isn't configured. Mirrors `push --direct`.
+ *
+ * Either way each prototype is a Pages branch alias (slug) → a stable
+ * https://<slug>.calo-prototypes.pages.dev that updates on re-share. SPA deep links
+ * work via an injected `_redirects`.
+ */
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { publishWeb } = require("./login");
+
+const PROJECT = process.env.CALO_PAGES_PROJECT || "calo-prototypes";
+const aliasUrl = (slug, project) => `https://${slug}.${project}.pages.dev`;
+
+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 ok = (s) => log(`${c.g("✓")} ${s}`);
+const warn = (s) => log(`${c.y("!")} ${s}`);
+const tilde = (p) => p.replace(os.homedir(), "~");
+
+// Supports both `--slug x` and `--slug=x`.
+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}`);
+
+// Cloudflare Pages branch aliases must be a DNS label: [a-z0-9-], <=63 chars.
+function slugify(s) {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 63);
+}
+
+function readPkg(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")); } catch { return null; }
+}
+
+function run(bin, argv, opts = {}) {
+  const r = spawnSync(bin, argv, { stdio: "inherit", ...opts });
+  if (r.error) throw r.error;
+  if (typeof r.status === "number" && r.status !== 0) throw new Error(`${bin} ${argv.join(" ")} exited ${r.status}`);
+  return r;
+}
+
+// Run while capturing combined output (to parse the deploy URL) but still show it.
+function runCapture(bin, argv, opts = {}) {
+  const r = spawnSync(bin, argv, { encoding: "utf8", ...opts });
+  if (r.error) throw r.error;
+  const out = (r.stdout || "") + (r.stderr || "");
+  process.stdout.write(out);
+  if (typeof r.status === "number" && r.status !== 0) throw new Error(`${bin} pages deploy exited ${r.status}`);
+  return out;
+}
+
+// Prefer an installed wrangler (project-local, then global); else npx. Only used by
+// --direct — the default path needs no wrangler on this machine.
+function wranglerCmd(root) {
+  const local = path.join(root, "node_modules", ".bin", "wrangler");
+  if (fs.existsSync(local)) return [local, []];
+  const probe = spawnSync("wrangler", ["--version"], { stdio: "ignore" });
+  if (!probe.error && probe.status === 0) return ["wrangler", []];
+  return ["npx", ["--yes", "wrangler@latest"]];
+}
+
+// Find the static build to deploy: an explicit dir, a framework output (Vite=dist,
+// CRA=build, Next-export=out), building first if needed, or a plain static folder.
+function resolveBuildDir(root, { build }) {
+  const candidates = ["dist", "build", "out"];
+  const hasIndex = (d) => fs.existsSync(path.join(d, "index.html"));
+  const pj = readPkg(root);
+  const hasBuildScript = pj && pj.scripts && pj.scripts.build;
+
+  const existing = candidates.map((d) => path.join(root, d)).find(hasIndex);
+  if (existing && !build) return existing;
+
+  if (hasBuildScript && (build || !existing)) {
+    log(c.b("\n[build] npm run build"));
+    run("npm", ["run", "build"], { cwd: root });
+  }
+  const built = candidates.map((d) => path.join(root, d)).find(hasIndex);
+  if (built) return built;
+
+  if (hasIndex(root)) return root; // already-static folder (no build tooling)
+
+  throw new Error("no build output found — looked for dist/, build/, out/ with an index.html. Build first, or pass --dir <folder>.");
+}
+
+// SPA fallback so client-side routes (React Router etc.) don't 404 on deep links /
+// refresh. Respect a prototype's own _redirects if it ships one.
+function ensureSpaRedirects(dir) {
+  const f = path.join(dir, "_redirects");
+  if (fs.existsSync(f)) return false;
+  fs.writeFileSync(f, "/*    /index.html   200\n");
+  return true;
+}
+
+// Gzipped tarball of the build (relative entries), for the broker to extract + deploy.
+function createTarball(buildDir) {
+  const tgz = path.join(os.tmpdir(), `calo-share-${path.basename(buildDir)}-${process.pid}.tgz`);
+  run("tar", ["-czf", tgz, "-C", buildDir, "."]);
+  return tgz;
+}
+
+async function cmdShare(args = []) {
+  const root = process.cwd();
+  const project = flag(args, "project") || PROJECT;
+  const slug = slugify(flag(args, "slug") || (readPkg(root) || {}).name || path.basename(root));
+  if (!slug) throw new Error("couldn't determine a slug — pass --slug <name>.");
+
+  log(c.b(`\nShare “${slug}” → Cloudflare Pages (${project})`));
+
+  const dirFlag = flag(args, "dir");
+  const buildDir = dirFlag ? path.resolve(root, dirFlag) : resolveBuildDir(root, { build: has(args, "build") });
+  if (!fs.existsSync(path.join(buildDir, "index.html"))) throw new Error(`no index.html in ${buildDir}`);
+  ok(`build dir: ${tilde(buildDir)}`);
+
+  if (ensureSpaRedirects(buildDir)) ok("added _redirects (SPA fallback: /* → /index.html 200)");
+
+  if (has(args, "direct")) return shareDirect({ buildDir, slug, project, args });
+
+  // Default: hand the build to the broker, which deploys server-side with its own token.
+  if (has(args, "dry-run")) { log(c.dim("\n--dry-run: stopping before upload.")); return; }
+  const tgz = createTarball(buildDir);
+  try {
+    const sizeMb = (fs.statSync(tgz).size / 1e6).toFixed(1);
+    log(c.b(`\n[upload] ${sizeMb} MB → broker → wrangler pages deploy`));
+    const r = await publishWeb({ slug, project, tarball: fs.readFileSync(tgz) });
+    log("");
+    ok(`Live: ${c.g(r.url || aliasUrl(slug, project))}`);
+    if (r.version) log(c.dim(`  this version: ${r.version}`));
+    log(c.dim(`  Re-run \`calo-design share\` to update “${slug}” in place. Share the link above.`));
+  } finally {
+    try { fs.rmSync(tgz); } catch {}
+  }
+}
+
+// --direct: deploy from this machine with the caller's own `wrangler login`.
+function shareDirect({ buildDir, slug, project, args }) {
+  if (has(args, "dry-run")) { log(c.dim("\n--dry-run: stopping before deploy.")); return; }
+  warn("--direct: deploying with your local `wrangler login` (not via the broker)");
+  const [bin, pre] = wranglerCmd(process.cwd());
+  const argv = [...pre, "pages", "deploy", buildDir, "--project-name", project, "--branch", slug, "--commit-dirty=true"];
+  log(c.b(`\n[deploy] wrangler pages deploy → branch ${slug}`));
+  const out = runCapture(bin, argv);
+  const version = (out.match(/https:\/\/[a-z0-9]+\.[a-z0-9-]+\.pages\.dev/gi) || []).find((u) => !u.includes(`${slug}.`));
+  log("");
+  ok(`Live: ${c.g(aliasUrl(slug, project))}`);
+  if (version) log(c.dim(`  this version: ${version}`));
+}
+
+module.exports = { cmdShare };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calo-design/cli",
-  "version": "0.2.1",
+  "version": "0.4.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" },
   "files": ["bin"],