@calo-design/cli 0.12.4 → 0.13.1

package/bin/backend.js

@@ -0,0 +1,380 @@
+"use strict";
+
+// calo-design backend <verb> — per-prototype backend primitives (Cloudflare Workers/
+// D1/KV/R2), provisioned and deployed through the broker. The designer's machine never
+// holds a Cloudflare credential: the CLI tars worker/ and the broker does the rest.
+//
+// State on disk (both prototype-root, both git-tracked):
+//   backend.json   { slug, owner, workerUrl, appKey, deployHash, recipe } — the pointer
+//                  file. NOT carried by checkpoints (the key is per-owner); a teammate
+//                  who `open`s a prototype with worker/ reconnects via `backend init`.
+//   worker/        the deployable unit: index.js (+ migrations/*.sql for D1 recipes).
+//
+// Verbs are non-interactive and idempotent; --json output follows the house rule
+// (leading newline, machine callers parse the last non-empty stdout line).
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { spawnSync } = require("node:child_process");
+
+const { ensureSession, loadSession, BROKER } = require("./login");
+const { autoCheckpoint } = require("./checkpoints");
+
+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 emitJson = (obj) => process.stdout.write("\n" + (typeof obj === "string" ? obj : JSON.stringify(obj)) + "\n");
+
+const flag = (args, name) => {
+  const eq = args.find((a) => a.startsWith(`--${name}=`));
+  if (eq) return eq.slice(name.length + 3);
+  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 SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const slugify = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
+
+// Bounded broker fetch, GET+POST+raw-Buffer bodies (feedback.js's call(), plus a
+// per-call timeout — worker deploys legitimately take a minute).
+async function call(method, pathname, { body, raw, headers, timeoutMs = 30000 } = {}) {
+  const session = await ensureSession();
+  let res;
+  try {
+    res = await fetch(BROKER + pathname, {
+      method,
+      headers: {
+        authorization: `Bearer ${session}`,
+        ...(body !== undefined && !Buffer.isBuffer(body) ? { "content-type": "application/json" } : {}),
+        ...(Buffer.isBuffer(body) ? { "content-type": "application/gzip" } : {}),
+        ...(headers || {}),
+      },
+      body: body === undefined ? undefined : Buffer.isBuffer(body) ? body : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } 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) {
+    const err = new Error([json.error || `${pathname} → HTTP ${res.status}`, json.detail].filter(Boolean).join("\n  "));
+    err.status = res.status;
+    throw err;
+  }
+  return raw ? text : json;
+}
+
+// --- prototype-local state ----------------------------------------------------------
+
+const backendJsonPath = (root) => path.join(root, "backend.json");
+const readBackendJson = (root) => {
+  try { return JSON.parse(fs.readFileSync(backendJsonPath(root), "utf8")); } catch { return null; }
+};
+const writeBackendJson = (root, obj) =>
+  fs.writeFileSync(backendJsonPath(root), JSON.stringify(obj, null, 2) + "\n");
+
+function resolveSlug(args, root) {
+  const bj = readBackendJson(root);
+  let marker = null;
+  try { marker = JSON.parse(fs.readFileSync(path.join(root, ".calo-checkpoint.json"), "utf8")); } catch {}
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")); } catch {}
+  const slug = slugify(flag(args, "slug") || (bj && bj.slug) || (marker && marker.slug) || (pkg && pkg.name) || path.basename(root));
+  if (!SLUG_RE.test(slug)) throw new Error("can't derive a valid slug from this folder — pass --slug <name>");
+  return slug;
+}
+
+// The recipes corpus ships in @calo/backend — prototype-local node_modules first, then
+// the shared runtime (the DS two-step path rule; a folder with no @calo is normal).
+function recipesDir(root) {
+  const home = process.env.DESIGNCHEF_HOME || path.join(os.homedir(), ".designchef");
+  for (const base of [path.join(root, "node_modules"), path.join(home, "runtime", "node_modules")]) {
+    const p = path.join(base, "@calo", "backend", "recipes");
+    if (fs.existsSync(p)) return p;
+  }
+  throw new Error("@calo/backend isn't in the shared runtime yet — run `calo-design update` first");
+}
+
+const listRecipes = (dir) => fs.readdirSync(dir).filter((r) => fs.existsSync(path.join(dir, r, "recipe.json")));
+
+// --- verbs ----------------------------------------------------------------------------
+
+// Scaffold (recipe → worker/) + provision + write backend.json + glue. One command in
+// three situations: fresh start, reconnect (worker/ exists, backend.json missing —
+// checkpoints carry the code but never the pointer file), and re-run (fully idempotent).
+async function cmdInit(args) {
+  const root = process.cwd();
+  if (!fs.existsSync(path.join(root, "package.json"))) {
+    throw new Error("no package.json here — run `calo-design backend init` from a prototype folder");
+  }
+  const slug = resolveSlug(args, root);
+  const workerDir = path.join(root, "worker");
+  const hadWorker = fs.existsSync(workerDir);
+  const existing = readBackendJson(root);
+
+  let recipe = flag(args, "recipe");
+  let recipeResources = [];
+  if (!hadWorker) {
+    const dir = recipesDir(root);
+    const available = listRecipes(dir);
+    if (!recipe) {
+      throw new Error(`pick a recipe: calo-design backend init --recipe <${available.join("|")}>`);
+    }
+    if (!available.includes(recipe)) {
+      throw new Error(`unknown recipe "${recipe}" — available: ${available.join(", ")}`);
+    }
+    const meta = JSON.parse(fs.readFileSync(path.join(dir, recipe, "recipe.json"), "utf8"));
+    recipeResources = meta.resources || [];
+    fs.cpSync(path.join(dir, recipe, "worker"), workerDir, { recursive: true });
+    ok(`worker/ scaffolded from the ${c.b(recipe)} recipe`);
+  } else {
+    log(c.dim(`worker/ already exists — ${existing ? "re-checking provisioning" : "reconnecting it to a provisioned backend"}`));
+    recipe = recipe || (existing && existing.recipe) || undefined;
+    // Infer the resource need from the code we have: migrations ⇒ D1.
+    if (fs.existsSync(path.join(workerDir, "migrations"))) recipeResources = ["d1"];
+  }
+
+  // Provision. When we hold no backend.json we always ask for a key: for a brand-new
+  // prototype one is minted anyway; for an existing row (reconnect) this mints a
+  // replacement — the old plaintext is gone with the old backend.json, by design.
+  const r = await call("POST", "/v1/backend/provision", {
+    body: { slug, kind: "worker", recipe, needKey: !existing || undefined },
+  });
+  for (const kind of recipeResources) {
+    await call("POST", "/v1/backend/provision", { body: { slug, kind } });
+    ok(`${kind} provisioned`);
+  }
+
+  const email = (loadSession() || {}).email || null;
+  writeBackendJson(root, {
+    slug,
+    owner: r.appKey ? email : (existing && existing.owner) || email,
+    workerUrl: r.workerUrl,
+    appKey: r.appKey || (existing && existing.appKey),
+    deployHash: r.deployHash || null,
+    recipe: recipe || r.recipe || null,
+  });
+  ok(`backend.json written ${c.dim("(git-tracked — commit it)")}`);
+  if (r.appKey && r.deployHash) {
+    warn("app key was re-minted for this reconnect — run `calo-design backend deploy` to activate it");
+  }
+
+  // Glue: the one sanctioned way app code reaches the backend.
+  const glue = path.join(root, "src", "backend.ts");
+  if (fs.existsSync(path.join(root, "src")) && !fs.existsSync(glue)) {
+    fs.writeFileSync(
+      glue,
+      `// Generated by \`calo-design backend init\` — app code talks to this prototype's\n` +
+        `// backend through here (auth + request-ids handled by @calo/backend).\n` +
+        `import { createBackend } from "@calo/backend";\n` +
+        `import config from "../backend.json";\n\n` +
+        `// user tags rows server-side (x-calo-user; self-reported in v1)\n` +
+        `export const backend = createBackend({ ...config, user: config.owner });\n` +
+        `export const useBackend = () => backend;\n`
+    );
+    ok("src/backend.ts glue written");
+  }
+
+  log(`\n${c.b("Next:")} edit worker/, then ${c.b("calo-design backend deploy")} → ${c.b("backend check")}`);
+}
+
+async function cmdAdd(args) {
+  const kind = (args[0] || "").toLowerCase();
+  if (!["d1", "kv", "r2"].includes(kind)) throw new Error("usage: calo-design backend add <d1|kv|r2>");
+  const root = process.cwd();
+  const slug = resolveSlug(args.slice(1), root);
+  const r = await call("POST", "/v1/backend/provision", { body: { slug, kind } });
+  ok(`${kind} ready ${c.dim(`(${(r.resources.find((x) => x.kind === kind) || {}).name || ""})`)}`);
+  log(c.dim("  binding lands on the next `calo-design backend deploy`"));
+}
+
+async function cmdDeploy(args) {
+  const root = process.cwd();
+  const bj = readBackendJson(root);
+  if (!bj || !bj.appKey) throw new Error("no backend.json here — run `calo-design backend init` first");
+  const workerDir = path.join(root, "worker");
+  if (!fs.existsSync(path.join(workerDir, "index.js"))) {
+    throw new Error("no worker/index.js — run `calo-design backend init --recipe <name>` to scaffold one");
+  }
+
+  const tgz = path.join(os.tmpdir(), `calo-backend-${bj.slug}-${process.pid}.tgz`);
+  const r = spawnSync("tar", ["-czf", tgz, "-C", workerDir, "."]);
+  if (r.status !== 0) throw new Error("tar failed packaging worker/");
+
+  log(c.b("\n[backend] Deploying worker"));
+  try {
+    const out = await call("POST", "/v1/backend/deploy", {
+      body: fs.readFileSync(tgz),
+      timeoutMs: 180000,
+      headers: {
+        "x-calo-slug": bj.slug,
+        "x-calo-parent": bj.deployHash || "none",
+        "x-calo-app-key": bj.appKey,
+        ...(flag(args, "note") ? { "x-calo-note": encodeURIComponent(flag(args, "note")) } : {}),
+      },
+    });
+    writeBackendJson(root, { ...bj, workerUrl: out.url, deployHash: out.deployHash });
+    ok(`${out.verified ? "Live" : "deployed (not yet verified — give it a few seconds)"} → ${c.b(out.url)}`);
+    if (out.migrations && out.migrations.ran) log(c.dim("  migrations applied"));
+    log(c.dim(`  next: calo-design backend check`));
+    // Pair the deploy with its exact source — best-effort by contract, never fails the deploy.
+    await autoCheckpoint({ root, note: `backend deploy ${out.deployHash.slice(0, 8)}`, publishedUrl: out.url });
+  } finally {
+    fs.rmSync(tgz, { force: true });
+  }
+}
+
+async function cmdStatus(args) {
+  const root = process.cwd();
+  const slug = resolveSlug(args, root);
+  const text = await call("GET", `/v1/backend/status?slug=${encodeURIComponent(slug)}`, { raw: true });
+  if (has(args, "json")) return emitJson(text);
+  const s = JSON.parse(text);
+  log(`${c.b(s.slug)} ${c.dim(`(${s.base})`)}`);
+  log(`  worker   ${s.workerUrl}${s.deployHash ? "" : c.dim("  (never deployed)")}`);
+  if (s.deployHash) log(`  deploy   ${s.deployHash.slice(0, 12)} ${c.dim(new Date(s.deployedAt).toISOString())}`);
+  for (const r of s.resources) log(`  ${r.kind.padEnd(8)} ${r.name}`);
+  if (!s.resources.length) log(c.dim("  no resources — `calo-design backend add <d1|kv|r2>`"));
+}
+
+const parseSince = (v) => {
+  if (!v) return Date.now() - 15 * 60_000;
+  const m = /^(\d+)(s|m|h|d)$/.exec(v);
+  if (!m) throw new Error("--since wants 30s | 10m | 2h | 1d");
+  return Date.now() - Number(m[1]) * { s: 1e3, m: 60e3, h: 3600e3, d: 86400e3 }[m[2]];
+};
+
+async function cmdLogs(args) {
+  const root = process.cwd();
+  const slug = resolveSlug(args, root);
+  const level = has(args, "errors") ? "error" : undefined;
+  const fetchLogs = async (fromMs) => {
+    const q = new URLSearchParams({ slug, since: String(fromMs), ...(level ? { level } : {}) });
+    return call("GET", `/v1/backend/logs?${q}`, { raw: true });
+  };
+  if (has(args, "tail")) {
+    log(c.dim("tailing (5s poll, Ctrl-C to stop; ingestion lags a few seconds)…"));
+    let from = parseSince(flag(args, "since") || "1m");
+    for (;;) {
+      const body = JSON.parse(await fetchLogs(from));
+      for (const e of body.events || []) {
+        log(`${c.dim(e.ts ? new Date(e.ts).toISOString() : "")} ${e.level === "error" ? c.y(e.level) : c.dim(e.level || "log")} ${e.message}`);
+        if (e.ts) from = Math.max(from, e.ts + 1);
+      }
+      await new Promise((r) => setTimeout(r, 5000));
+    }
+  }
+  const text = await fetchLogs(parseSince(flag(args, "since")));
+  if (has(args, "json")) return emitJson(text);
+  const body = JSON.parse(text);
+  if (!body.events.length) return log(c.dim(body.note || "no events"));
+  for (const e of body.events) {
+    log(`${c.dim(e.ts ? new Date(e.ts).toISOString() : "")} ${e.level === "error" ? c.y(e.level) : c.dim(e.level || "log")} ${e.message}`);
+  }
+}
+
+async function cmdSql(args) {
+  const query = args.find((a) => !a.startsWith("--"));
+  if (!query) throw new Error('usage: calo-design backend sql "SELECT * FROM items"');
+  const root = process.cwd();
+  const slug = resolveSlug(args.filter((a) => a !== query), root);
+  const text = await call("POST", "/v1/backend/sql", { body: { slug, query }, raw: true });
+  if (has(args, "json")) return emitJson(text);
+  const body = JSON.parse(text);
+  log(JSON.stringify(body.results, null, 2));
+  if (body.meta) log(c.dim(`  ${body.meta.rows_read ?? "?"} read / ${body.meta.rows_written ?? "?"} written`));
+}
+
+// End-to-end gate: hits the worker's own /__health (directly, not via the broker) with
+// the app key — proving deploy + auth + bindings + migrations + seeds in one round trip.
+async function cmdCheck(args) {
+  const root = process.cwd();
+  const bj = readBackendJson(root);
+  if (!bj || !bj.workerUrl) throw new Error("no backend.json here — run `calo-design backend init` first");
+  let res, body;
+  // Right after a deploy, two kinds of lag are normal and NOT failures: network-level
+  // (route/DNS propagation) and 401/5xx while the fresh APP_KEY secret version reaches
+  // running isolates. Retry through both with the reason on screen; a state that
+  // persists past the retries is a real failure.
+  const TRIES = 6;
+  for (let i = 1; ; i++) {
+    try {
+      res = await fetch(`${bj.workerUrl}/__health`, {
+        headers: { authorization: `Bearer ${bj.appKey}` },
+        signal: AbortSignal.timeout(15000),
+      });
+      body = await res.json().catch(() => ({}));
+      if (res.ok || i >= TRIES) break;
+      log(c.dim(`  not healthy yet (HTTP ${res.status}) — retrying ${i}/${TRIES - 1} in 5s (fresh deploys propagate for a few seconds)`));
+      await new Promise((r) => setTimeout(r, 5000));
+    } catch (e) {
+      if (i >= TRIES) {
+        throw new Error(
+          `worker unreachable at ${bj.workerUrl} (${e.message}) — deployed yet? try \`calo-design backend deploy\`, ` +
+            "then re-run `calo-design backend check`"
+        );
+      }
+      log(c.dim(`  worker not reachable yet (${e.message}) — retrying ${i}/${TRIES - 1} in 5s`));
+      await new Promise((r) => setTimeout(r, 5000));
+    }
+  }
+  if (has(args, "json")) return emitJson(JSON.stringify({ status: res.status, ...body }));
+  const checks = body.checks || {};
+  for (const [k, v] of Object.entries(checks)) {
+    if (v === null) log(`  ${c.dim("–")} ${k} ${c.dim("(not provisioned)")}`);
+    else if (v === false) log(`  ${c.y("✗")} ${k}`);
+    else log(`  ${c.g("✓")} ${k}${typeof v === "number" ? c.dim(` (${v})`) : ""}`);
+  }
+  if (res.ok && body.ok) ok("backend healthy");
+  else {
+    warn(`health check failed (HTTP ${res.status}) — \`calo-design backend logs --errors\` has the story`);
+    process.exit(1);
+  }
+}
+
+async function cmdSecrets(args) {
+  if (args[0] !== "set") throw new Error("usage: calo-design backend secrets set <KEY> --value <v>");
+  const key = args[1];
+  const value = flag(args, "value");
+  if (!key || !value) throw new Error("usage: calo-design backend secrets set <KEY> --value <v>");
+  const root = process.cwd();
+  const slug = resolveSlug(args.slice(2), root);
+  await call("POST", "/v1/backend/secret", { body: { slug, key, value } });
+  ok(`${key} set ${c.dim("(worker reads it as env." + key + ")")}`);
+}
+
+async function cmdRotateKey(args) {
+  const root = process.cwd();
+  const bj = readBackendJson(root);
+  if (!bj) throw new Error("no backend.json here — run `calo-design backend init` first");
+  const r = await call("POST", "/v1/backend/rotate-key", { body: { slug: bj.slug } });
+  writeBackendJson(root, { ...bj, appKey: r.appKey });
+  ok(`app key rotated${r.live ? "" : " (activates on next deploy)"}`);
+  warn("published web shares still carry the OLD key baked into their bundle — re-run `calo-design share` to fix them");
+}
+
+async function cmdBackend(args) {
+  const sub = args[0] && !args[0].startsWith("--") ? args[0] : "";
+  const rest = args.slice(1);
+  if (sub === "init") return cmdInit(rest);
+  if (sub === "add") return cmdAdd(rest);
+  if (sub === "deploy") return cmdDeploy(rest);
+  if (sub === "status") return cmdStatus(rest);
+  if (sub === "logs") return cmdLogs(rest);
+  if (sub === "sql") return cmdSql(rest);
+  if (sub === "check") return cmdCheck(rest);
+  if (sub === "secrets") return cmdSecrets(rest);
+  if (sub === "rotate-key") return cmdRotateKey(rest);
+  throw new Error(
+    "unknown backend command — one of: init, add <d1|kv|r2>, deploy, status, logs, sql, check, secrets set, rotate-key"
+  );
+}
+
+module.exports = { cmdBackend, _resolveSlug: resolveSlug, _parseSince: parseSince, _readBackendJson: readBackendJson };

package/bin/cli.js

@@ -22,6 +22,7 @@ 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 { cmdBackend } = require("./backend");
 
 const ORG = "Calo-Design";
 const SKILL_REPO = `${ORG}/calo-design`;
@@ -52,7 +53,8 @@ const PEERS = [
 const PKG_SPECS = [
   `git+https://github.com/${ORG}/calo-design-system.git`,
   `git+https://github.com/${ORG}/calo-flows.git`,
-  `git+https://github.com/${ORG}/calo-creatives.git`
+  `git+https://github.com/${ORG}/calo-creatives.git`,
+  `git+https://github.com/${ORG}/calo-backend.git`
 ];
 
 const args = process.argv.slice(2);
@@ -150,6 +152,8 @@ function runtimeExists() {
     fs.existsSync(runtimeManifestPath()) &&
     fs.existsSync(path.join(rt, "node_modules", "@calo", "design-system", "package.json")) &&
     fs.existsSync(path.join(rt, "node_modules", "@calo", "flows", "package.json")) &&
+    fs.existsSync(path.join(rt, "node_modules", "@calo", "creatives", "package.json")) &&
+    fs.existsSync(path.join(rt, "node_modules", "@calo", "backend", "package.json")) &&
     fs.existsSync(path.join(rt, "node_modules", "expo", "package.json"))
   );
 }
@@ -786,6 +790,8 @@ function help() {
   ${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("backend init --recipe <name>")}              provision THIS prototype a real backend (Cloudflare worker + data; login only)
+  ${c.dim("    backend add <d1|kv|r2>   deploy   status   logs --since 10m --errors   sql \"…\"   check   secrets set K --value v   rotate-key")}
   ${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)
@@ -819,6 +825,7 @@ function help() {
     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 if (cmd === "backend") await cmdBackend(args.slice(1));
     else help();
   } catch (err) {
     // Diagnostics go to stderr so stdout stays pure for machine callers (The Pass parses

package/package.json

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