@blocofy/cli 0.9.0 → 0.10.0

package/lib/local-theme.mjs

@@ -8,8 +8,13 @@ import { extname, join, relative, sep } from "node:path";
  */
 
 // Mirror of the platform's theme-paths.ts THEME_DIRS (incl. `layer`, added M5 B1 — 0.5.0 closes the
-// drift where a pulled layer/ file was silently dropped from the next push).
-export const THEME_DIRS = new Set(["layout", "section", "block", "layer", "partial", "asset", "template"]);
+// drift where a pulled layer/ file was silently dropped from the next push; `locales`, added CF-T5, for
+// legacy locale files `locales/<tag>.json` / `locales/<tag>.default.json`). `locales` is not a Liquid
+// kind (raw content, like `asset` — no `.liquid` stripped on push or re-added on pull). The CLI does not
+// validate the tag regex or require a `.json` extension under `locales/` — it reads/writes/sends whatever
+// is there and lets the platform's own write-time validation (tag format, JSON-ness) reject a bad file;
+// duplicating that check here would drift from the server's rules.
+export const THEME_DIRS = new Set(["layout", "section", "block", "layer", "partial", "asset", "template", "locales"]);
 const LIQUID_KINDS = new Set(["layout", "section", "block", "partial", "template"]);
 
 /**

package/lib/media-uses.mjs

@@ -7,13 +7,18 @@
  *
  * Authentication is a `blcf_live_…` API key (Bearer). The dev `bcf_…` token is NOT accepted for v1.
  *
- * NO RETRIES. A decision batch is applied atomically on the server but a lost response is only
- * safe to replay with the SAME idempotency keys, which is the caller's decision, not this
- * client's — so a 5xx/network failure surfaces once and the command exits 1. A 4xx is a server
+ * RETRIES (CF-T3, lib/http.mjs: 429/502/503/504 + network errors, Retry-After honoured). The GET is a
+ * read and always retried. A decision POST is applied atomically on the server, and a lost response is
+ * only safe to replay with the SAME idempotency keys — so the POST is retried ONLY when every decision
+ * item carries an `idempotency_key` (the CLI adds a UUID to every item lacking one BEFORE the first
+ * attempt, so each retry resends the identical body and the server replays instead of applying twice).
+ * A batch with an unkeyed item is sent once. A final 5xx/network failure exits 1. A 4xx is a server
  * REFUSAL (`CliRefusal`): the `{ error }` envelope is carried verbatim for the command to print
  * as JSON on stderr with exit code 2.
  */
 
+import { fetchWithRetry } from "./http.mjs";
+
 export const API_KEY_PREFIX = "blcf_live_";
 export const DEFAULT_API_URL = "https://app.blocofy.com";
 
@@ -36,14 +41,19 @@ function mediaUsesUrl(apiUrl, page) {
   return `${String(apiUrl).replace(/\/+$/, "")}/api/v1/pages/${encodeURIComponent(page)}/media-uses`;
 }
 
-async function request(method, { apiUrl, apiKey, page }, body) {
+/** True when a replay of this decision batch is idempotent on the server. */
+export function everyDecisionKeyed(decisions) {
+  return Array.isArray(decisions) && decisions.length > 0 && decisions.every((d) => d && typeof d === "object" && typeof d.idempotency_key === "string" && d.idempotency_key !== "");
+}
+
+async function request(method, { apiUrl, apiKey, page, onRetry = null, retry = true }, body) {
   const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json" };
   if (body !== undefined) headers["content-type"] = "application/json";
-  const res = await fetch(mediaUsesUrl(apiUrl, page), {
-    method,
-    headers,
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
+  const res = await fetchWithRetry(
+    mediaUsesUrl(apiUrl, page),
+    { method, headers, body: body === undefined ? undefined : JSON.stringify(body) },
+    { onRetry, retries: retry ? undefined : 0 },
+  );
   const text = await res.text();
   let json;
   try {
@@ -59,24 +69,25 @@ async function request(method, { apiUrl, apiKey, page }, body) {
     const error = json?.error && typeof json.error === "object" ? json.error : { code: `http_${res.status}`, message: text.slice(0, 200) || `HTTP ${res.status}` };
     throw new CliRefusal(res.status, error);
   }
-  // 5xx (no retry) — the message never includes the request headers.
+  // 5xx (after any retries) — the message never includes the request headers.
   const detail = json?.error?.message ?? (text ? text.slice(0, 200) : "");
-  throw new Error(`HTTP ${res.status}${detail ? `: ${detail}` : ""}`);
+  throw Object.assign(new Error(`HTTP ${res.status}${detail ? `: ${detail}` : ""}`), { status: res.status });
 }
 
 /** GET the page's media-use view (the newest draft's `revision{id,version}` is inside). */
-export function fetchPageMediaUses({ apiUrl, apiKey, page }) {
-  return request("GET", { apiUrl, apiKey, page });
+export function fetchPageMediaUses({ apiUrl, apiKey, page, onRetry = null }) {
+  return request("GET", { apiUrl, apiKey, page, onRetry });
 }
 
 /**
  * POST a decision batch. The body is exactly `{ expected_revision_id, expected_version, decisions }`
- * — items are sent as given (idempotency keys are the caller's responsibility).
+ * — items are sent as given (idempotency keys are the caller's responsibility). Retried only when
+ * `everyDecisionKeyed(decisions)`.
  */
-export function decidePageMediaUses({ apiUrl, apiKey, page, expectedRevisionId, expectedVersion, decisions }) {
+export function decidePageMediaUses({ apiUrl, apiKey, page, expectedRevisionId, expectedVersion, decisions, onRetry = null }) {
   return request(
     "POST",
-    { apiUrl, apiKey, page },
+    { apiUrl, apiKey, page, onRetry, retry: everyDecisionKeyed(decisions) },
     { expected_revision_id: expectedRevisionId, expected_version: expectedVersion, decisions },
   );
 }

package/lib/messages.mjs

@@ -36,9 +36,11 @@ export function statusLine(session) {
  * (ve `theme dev` taslak senkronu) sessizce retry ETMESİN; stderr'e kısa bir satır
  * yazılır. `onRetry({ attempt, retries, reason })` payload'ından string üretir.
  */
-export function retryNotice({ attempt, retries, reason }) {
+export function retryNotice({ attempt, retries, reason, waitMs }) {
   const why = reason ? ` (${reason})` : "";
-  return `Network error${why} — retrying (${attempt}/${retries})…`;
+  const what = typeof reason === "string" && reason.startsWith("HTTP ") ? "Server temporarily unavailable" : "Network error";
+  const wait = Number.isFinite(waitMs) ? ` in ${Math.round(waitMs / 100) / 10}s` : "";
+  return `${what}${why} — retrying${wait} (${attempt}/${retries})…`;
 }
 
 /**
@@ -57,3 +59,41 @@ export function githubNote(session) {
     (session.githubConnected === false ? " Connect a GitHub repo for two-way sync." : "")
   );
 }
+
+/**
+ * CF-T9 — `blocofy status` health advice (pure). Never an imperative one-line fix: making another theme live
+ * replaces what every visitor sees, so the advice names the themes involved, the missing pages, why it happens,
+ * and SAFE next steps (preview first); `theme publish` is only mentioned as a separate, deliberate decision.
+ * Returns stderr lines ([] when healthy). Tolerates older servers without pages_by_instance/orphan_missing_slugs.
+ */
+export function healthAdvice(s) {
+  if (!s || (s.health !== "pages_split" && s.health !== "live_instance_empty")) return [];
+  const liveId = s.live_theme_instance?.id ?? null;
+  const names = new Map((Array.isArray(s.drafts) ? s.drafts : []).map((d) => [String(d.id), d.name]));
+  const holders = (Array.isArray(s.pages_by_instance) ? s.pages_by_instance : [])
+    .filter((p) => p && p.theme_instance != null && String(p.theme_instance) !== String(liveId) && p.count > 0)
+    .map((p) => ({ id: p.theme_instance, name: names.get(String(p.theme_instance)) ?? null, count: p.count }));
+  const label = (h) => `${h.id}${h.name ? ` "${h.name}"` : ""} (${h.count} published page${h.count === 1 ? "" : "s"})`;
+  const missing = Array.isArray(s.orphan_missing_slugs) ? s.orphan_missing_slugs : [];
+  const handle = holders.length === 1 ? String(holders[0].id) : "<handle>";
+
+  const out = [];
+  if (s.health === "live_instance_empty") {
+    out.push("  ⚠ The live theme has no published pages, so visitors get \"page not found\".");
+  } else {
+    out.push(`  ⚠ ${missing.length || s.orphaned_pages || "Some"} published page(s) cannot be reached by visitors.`);
+    if (missing.length) out.push(`    Missing on the live theme: ${missing.join(", ")}`);
+  }
+  if (holders.length) {
+    out.push(`    Published pages are held by ${holders.length === 1 ? "a theme that is" : "themes that are"} not live: ${holders.map(label).join(", ")}`);
+  } else {
+    out.push("    Published pages are held by a theme that is not live (this server does not say which; see the panel's theme library).");
+  }
+  out.push("    Why: pages belong to a theme. Pages published on a theme that is not live are not shown on the site.");
+  out.push("    Safe next steps:");
+  out.push(`      1. Preview that theme without changing the site:  blocofy theme pull <empty-dir> --instance ${handle}`);
+  out.push("         or in the panel: Theme → Theme library → \"Open in editor\".");
+  out.push("      2. Then decide: recreate the missing pages on the live theme, or make that theme live.");
+  out.push(`    Note: \`blocofy theme publish --instance ${handle}\` REPLACES the live theme for every visitor — a separate, deliberate decision.`);
+  return out;
+}

package/lib/output.mjs

@@ -0,0 +1,53 @@
+/**
+ * CF-T2 (contract C2) — shared output for target display and refusals. Everything here goes to stderr (stdout
+ * stays the command's own result, e.g. `--json` payloads). Known secrets are registered once and redacted from
+ * every string this module prints, as a last line of defence.
+ */
+
+const secrets = new Set();
+
+export function registerSecret(value) {
+  if (typeof value === "string" && value.length >= 8) secrets.add(value);
+}
+
+export function redact(text) {
+  let out = String(text);
+  for (const s of secrets) out = out.split(s).join("[redacted]");
+  return out;
+}
+
+/** The target block as data (used for `--json` and for `blocofy target`). */
+export function targetData({ site, url, contextName, bindingLabel, operation }) {
+  return {
+    site: { id: site.id, slug: site.slug ?? null, name: site.name ?? null, domain: site.domain ?? null },
+    url: url ?? null,
+    context: contextName,
+    binding: bindingLabel,
+    operation,
+  };
+}
+
+export function formatTargetBlock(t) {
+  const name = t.site.name ?? t.site.slug ?? String(t.site.id);
+  return [
+    `Target:    ${name} · ${t.site.id} · ${t.site.domain ?? t.url ?? "?"}`,
+    `Context:   ${t.context}`,
+    `Binding:   ${t.binding}`,
+    `Operation: ${t.operation}`,
+  ].join("\n");
+}
+
+export function printTarget(t, { json = false, stream = process.stderr } = {}) {
+  stream.write(redact(json ? JSON.stringify({ target: t }) : formatTargetBlock(t)) + "\n");
+}
+
+/** `{"error":{code,message,details}}` under --json, `error [CODE]: message` otherwise. */
+export function printError(error, { json = false, stream = process.stderr } = {}) {
+  const envelope = { error: { code: error.code ?? "ERROR", message: error.message ?? String(error), details: error.details ?? {} } };
+  stream.write(redact(json ? JSON.stringify(envelope) : `error [${envelope.error.code}]: ${envelope.error.message}`) + "\n");
+}
+
+/** One warning line: `{"warning":{code,message}}` under --json, `warning [CODE]: message` otherwise. */
+export function printWarning(warning, { json = false, stream = process.stderr } = {}) {
+  stream.write(redact(json ? JSON.stringify({ warning: { code: warning.code, message: warning.message } }) : `warning [${warning.code}]: ${warning.message}`) + "\n");
+}

package/lib/page-files.mjs

@@ -20,7 +20,7 @@ import {
 
 export const PAGE_META_KEYS = ["title", "seo_title", "seo_description", "og_image", "canonical_url"];
 const NULLABLE_STRING_KEYS = [...PAGE_META_KEYS, "status", "template"];
-const V2_KEY_ORDER = ["format_version", "slug", "title", "status", "seo_title", "seo_description", "og_image", "canonical_url", "locale", "template", "data"];
+const V2_KEY_ORDER = ["format_version", "base_revision", "slug", "title", "status", "seo_title", "seo_description", "og_image", "canonical_url", "locale", "template", "data"];
 
 /** A refusal the CLI prints with its stable code. `diagnostics` are platform-shaped findings. */
 export class PagesCliError extends Error {
@@ -34,6 +34,9 @@ export class PagesCliError extends Error {
   }
 }
 
+/** CF-T3 — the fingerprint `blocofy pages pull` stamps (mirror of the platform's `page-files/base-revision.ts`). */
+export const BASE_REVISION_PATTERN = /^r1_[0-9a-f]{32}$/;
+
 const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const isCanonicalLocale = (v) => typeof v === "string" && canonicalizeLocaleCode(v) === v;
 
@@ -63,6 +66,11 @@ export function classifyPageFile(path, content, ctx = {}) {
   for (const key of NULLABLE_STRING_KEYS) {
     if (key in json && json[key] !== null && typeof json[key] !== "string") return fail("PAGES_INVALID_JSON", `${key} must be a string or null`, { slug });
   }
+  // CF-T3 — absent/null is judged by the push (it needs the server state); anything else must be a pulled value.
+  if (json.base_revision != null && (typeof json.base_revision !== "string" || !BASE_REVISION_PATTERN.test(json.base_revision))) {
+    return fail("PAGES_INVALID_JSON", "base_revision is not a value `blocofy pages pull` wrote", { slug });
+  }
+
   const hasLocale = Object.prototype.hasOwnProperty.call(json, "locale");
   let locale = null;
   let localeSource;
@@ -302,7 +310,9 @@ export function stagedWrite(root, entries, { writeFile = writeFileSync, rename =
 
 export function formatDiagnostic(d) {
   const where = d.path ? `\n    ${d.path}` : d.slug ? `\n    ${d.locale ? `locale "${d.locale}", ` : ""}slug "${d.slug}"` : "";
-  return `${d.level} [${d.code}]:\n    ${d.message}${where}`;
+  // CF-T3 — a stale or base-less file shows what it was pulled at and what the page is now.
+  const revs = d.current_revision ? `\n    base_revision ${d.base_revision ?? "(none)"} → current ${d.current_revision}` : "";
+  return `${d.level} [${d.code}]:\n    ${d.message}${where}${revs}`;
 }
 
 export { PageFileError, pageFilePath };

package/lib/secret-store.mjs

@@ -0,0 +1,133 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+
+/**
+ * CF-T1 (contract C1) — where credential SECRETS live. `credentials.json` only records which store holds a
+ * context's secret (`secret: { store: "file" | "keychain" }`); the value itself is in one of:
+ *
+ *   file      `~/.blocofy/secrets.json` (0600, atomic tmp+rename) `{ "<context>": { dev_token, api_key } }`.
+ *   keychain  macOS Keychain via the `security` binary: service `blocofy-cli`, account `<context>:dev|api`.
+ *             Opt-in only (`BLOCOFY_SECRET_STORE=keychain` or `login --keychain`); other platforms → error.
+ *
+ * Both stores expose `get(context, kind)`, `set(context, kind, value)`, `remove(context)` with kind `dev|api`.
+ * No method ever puts a secret into an error message.
+ */
+
+export const KEYCHAIN_SERVICE = "blocofy-cli";
+const FIELD = { dev: "dev_token", api: "api_key" };
+
+export class SecretStoreError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "SecretStoreError";
+    this.code = code;
+  }
+}
+
+/** Atomic JSON write (unique tmp in the same dir + rename) with 0600 permissions. */
+export function writeJsonAtomic(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(path), 0o700); // an older, looser directory is tightened too
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+}
+
+export function createFileSecretStore(path) {
+  const read = () => {
+    let raw;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return {};
+      throw error;
+    }
+    try {
+      const data = JSON.parse(raw);
+      if (data && typeof data === "object" && !Array.isArray(data)) return data;
+    } catch {
+      /* fall through */
+    }
+    throw new SecretStoreError("CREDENTIALS_CORRUPT", `The secrets file is not valid JSON: ${path}. Nothing was written.`);
+  };
+  return {
+    name: "file",
+    get(context, kind) {
+      const v = read()[context]?.[FIELD[kind]];
+      return typeof v === "string" && v ? v : null;
+    },
+    set(context, kind, value) {
+      const data = read();
+      data[context] = { ...(data[context] ?? {}), [FIELD[kind]]: value };
+      writeJsonAtomic(path, data);
+    },
+    remove(context, kind = null) {
+      const data = read();
+      if (!(context in data)) return;
+      if (kind) {
+        delete data[context][FIELD[kind]];
+        if (Object.keys(data[context]).length === 0) delete data[context];
+      } else {
+        delete data[context];
+      }
+      writeJsonAtomic(path, data);
+    },
+  };
+}
+
+/** Default exec: `spawnSync` with the secret-bearing command on STDIN (never argv — argv is visible in `ps`). */
+export function defaultExec(command, args, { input } = {}) {
+  const r = spawnSync(command, args, { input, encoding: "utf8" });
+  return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error ?? null };
+}
+
+const quote = (s) => `"${String(s).replace(/["\\]/g, (c) => `\\${c}`)}"`;
+
+/**
+ * macOS Keychain adapter. `exec(command, args, { input })` is injectable so tests never touch a real keychain.
+ * Writes go through `security -i` (commands read from stdin) so the secret is not in the process argv.
+ */
+export function createKeychainSecretStore({ exec = defaultExec, platform = process.platform } = {}) {
+  const ensure = () => {
+    if (platform !== "darwin") {
+      throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "The keychain secret store is only available on macOS. Use the default file store (unset BLOCOFY_SECRET_STORE, omit --keychain).");
+    }
+  };
+  const account = (context, kind) => `${context}:${kind}`;
+  return {
+    name: "keychain",
+    get(context, kind) {
+      ensure();
+      const r = exec("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account(context, kind), "-w"]);
+      if (r.status !== 0) return null;
+      const v = r.stdout.replace(/\r?\n$/, "");
+      return v || null;
+    },
+    set(context, kind, value) {
+      ensure();
+      // Review M6: `security -i` reads one command per line; a CR/LF/NUL in the secret would start a new command.
+      if (/[\r\n\0]/.test(String(value)) || /[\r\n\0]/.test(account(context, kind))) {
+        throw new SecretStoreError("SECRET_STORE_INVALID_SECRET", "The secret contains a line break or NUL character and cannot be stored in the macOS keychain. Nothing was saved.");
+      }
+      const input = `add-generic-password -U -s ${quote(KEYCHAIN_SERVICE)} -a ${quote(account(context, kind))} -w ${quote(value)}\n`;
+      const r = exec("security", ["-i"], { input });
+      if (r.status !== 0) throw new SecretStoreError("SECRET_STORE_FAILED", `Could not save the secret to the macOS keychain (security exit ${r.status}). Nothing was saved.`);
+    },
+    remove(context, kind = null) {
+      ensure();
+      for (const k of kind ? [kind] : ["dev", "api"]) {
+        exec("security", ["delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account(context, k)]);
+      }
+    },
+  };
+}
+
+/** `store` name → adapter. Unknown names are a usage error. */
+export function secretStoreFor(name, { filePath, exec, platform } = {}) {
+  if (name === "file") return createFileSecretStore(filePath);
+  if (name === "keychain") return createKeychainSecretStore({ exec, platform });
+  throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", `Unknown secret store "${name}" (use "file" or "keychain").`);
+}

package/lib/site-migrate.mjs

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { folderConflicts, resolveContained } from "./page-files.mjs";
+import { THEME_DIRS } from "./local-theme.mjs";
+import { MANIFEST_PATH, THEME_SETTINGS_PATH, checkSiteStatePath, ownerOfPath } from "./site-state.mjs";
+import { readSiteStateTree } from "./site-state-fs.mjs";
+
+/**
+ * CF-T4 — `blocofy site migrate`: turns a directory produced by the OLDER separate pulls (`theme pull`'s
+ * theme-dirs-at-root layout, `pages pull`'s canonical `pages/<locale>/…/index.json`, `settings pull`'s
+ * `config/settings.json`) into the site-state v1 tree layout (contract §A1). Purely local, zero network:
+ * this reuses `readSiteStateTree` — the same symlink-refusing walk `site export`/`site validate` use — to
+ * read, and the same contained-path helpers (`resolveContained`, `folderConflicts`) `pages migrate-layout`
+ * writes with. No new fs primitives, no identity/target call.
+ *
+ * `pages/**` files are NEVER moved — a site state uses the exact canonical location `pages pull` already
+ * writes (contract §A1). A page still at the OLD flat layout (`pages/<slug>.json`) is left alone with a
+ * note pointing at `blocofy pages migrate-layout`, which already owns that reasoning (locale resolution,
+ * legacy-vs-canonical detection); duplicating it here would drift.
+ *
+ * This never invents the owners a directory of separate pulls never had — site/locales.json, globals,
+ * media-policy, content-model, translations, navigation, theme/chrome/**, blocofy-site.json itself. Those
+ * can only come from the server; `needsExport` says whether this tree is missing its manifest for exactly
+ * that reason, so the caller can point at `blocofy site export`.
+ */
+
+const SETTINGS_SOURCE = "config/settings.json";
+const SETTINGS_SCHEMA_SOURCE = "config/settings_schema.json";
+const SETTINGS_SCHEMA_TARGET = "theme/config/settings_schema.json";
+
+/** Old-format relative path → its site-state v1 target, or null when this command does not know how to move it. */
+function mapOldPath(path) {
+  if (path === SETTINGS_SOURCE) return THEME_SETTINGS_PATH;
+  if (path === SETTINGS_SCHEMA_SOURCE) return SETTINGS_SCHEMA_TARGET;
+  const top = path.split("/")[0];
+  return THEME_DIRS.has(top) ? `theme/${path}` : null;
+}
+
+/**
+ * Read-only plan: every move this tree needs, every file left alone (and why), every refusal. Never
+ * touches disk beyond the read. `moves` is empty and `refused` true together only on a hard error
+ * (conflict, symlink, unreadable entry) — never on "nothing to migrate".
+ */
+export function planSiteMigrate(dir) {
+  const tree = readSiteStateTree(dir);
+  const errors = [...tree.diagnostics];
+  const moves = [];
+  const untouched = [];
+  const claimed = new Map();
+
+  for (const path of Object.keys(tree.files).sort()) {
+    if (path === MANIFEST_PATH || ownerOfPath(path) !== null) {
+      untouched.push({ path, reason: "already in the site-state tree layout" });
+      continue;
+    }
+    const target = mapOldPath(path);
+    if (target === null) {
+      untouched.push({
+        path,
+        reason: path.startsWith("pages/")
+          ? "old flat page layout — run `blocofy pages migrate-layout` first"
+          : "not part of the site-state tree — left alone",
+      });
+      continue;
+    }
+    const refusal = checkSiteStatePath(target);
+    if (refusal) {
+      errors.push({ level: "error", code: refusal.code, message: `${path} → ${target}: ${refusal.reason}`, path });
+      continue;
+    }
+    const existing = tree.files[target];
+    if (existing !== undefined) {
+      if (existing === tree.files[path]) {
+        untouched.push({ path, reason: `${target} already holds the same content; left in place (remove ${path} yourself)` });
+        continue;
+      }
+      errors.push({ level: "error", code: "SITE_STATE_MIGRATE_CONFLICT", message: `${target} already exists with different content than ${path}`, path });
+      continue;
+    }
+    const claimant = claimed.get(target);
+    if (claimant) {
+      errors.push({ level: "error", code: "SITE_STATE_MIGRATE_CONFLICT", message: `${path} and ${claimant} would both move to ${target}`, path });
+      continue;
+    }
+    claimed.set(target, path);
+    moves.push({ from: path, to: target, content: tree.files[path] });
+  }
+  for (const asset of tree.assets) untouched.push({ path: asset.path, reason: "already in the site-state tree layout" });
+
+  moves.sort((a, b) => (a.from < b.from ? -1 : 1));
+  const remaining = Object.keys(tree.files).filter((p) => !moves.some((m) => m.from === p));
+  errors.push(...folderConflicts([...remaining, ...moves.map((m) => m.to)]));
+
+  const refused = errors.length > 0;
+  const needsExport = tree.files[MANIFEST_PATH] === undefined;
+  return { root: tree.root, moves, untouched, diagnostics: errors, refused, needsExport };
+}
+
+/**
+ * Performs `moves` (from `planSiteMigrate`) on `root`: every target is revalidated (contained, not already
+ * present) before the first byte is written; then each file is written+renamed into place and only then is
+ * its old location removed. A mid-loop fs failure (real I/O error, not a logic conflict — those were already
+ * refused by the plan) leaves everything moved so far in place and throws, naming how many completed.
+ */
+export function writeSiteMigrate(root, moves) {
+  for (const m of moves) {
+    const r = resolveContained(root, m.to);
+    if (r.error) throw new Error(`internal: ${m.to} is not a valid site-state target (${r.error.reason})`);
+    if (existsSync(r.target)) throw new Error(`${m.to} appeared during migration; stopped before moving it.`);
+  }
+  let moved = 0;
+  for (const m of moves) {
+    const { target } = resolveContained(root, m.to);
+    mkdirSync(dirname(target), { recursive: true });
+    const temp = `${target}.blocofy-tmp`;
+    writeFileSync(temp, m.content, { flag: "wx" });
+    renameSync(temp, target);
+    const { target: legacy } = resolveContained(root, m.from);
+    rmSync(legacy);
+    moved += 1;
+  }
+  return moved;
+}
+
+/** `blocofy site migrate`: plan, and with `write: true` perform it. Any refusal moves zero files. */
+export function migrateSiteState({ dir, write = false }) {
+  const plan = planSiteMigrate(dir);
+  if (!write || plan.refused) return { ...plan, moved: 0 };
+  const moved = writeSiteMigrate(plan.root, plan.moves);
+  return { ...plan, moved };
+}

package/lib/site-state-client.mjs

@@ -0,0 +1,92 @@
+import { CliRefusal } from "./media-uses.mjs";
+import { fetchWithRetry } from "./http.mjs";
+
+/**
+ * CF-T4 — the v1 `site-state` HTTP client: `GET /api/v1/site-state`, `POST …/plan`, `…/apply`, `…/publish`,
+ * and `POST /api/v1/media` (asset upload, reused for `awaiting_assets`). Bearer `blcf_live_…` API key —
+ * same authentication and error-envelope shape as `lib/media-uses.mjs`, whose `CliRefusal` this reuses so
+ * `bin/blocofy.mjs`'s exit-code mapping (`error instanceof CliRefusal` → 2) needs no second branch.
+ *
+ * Retries (CF-T3, `lib/http.mjs`): every one of these calls is safe to resend blindly.
+ *   - export/plan are reads.
+ *   - apply and publish are idempotent BY DESIGN (contract §A3): every step re-reads before writing and
+ *     no-ops when the target already matches, and "publishing the same state twice rewrites nothing".
+ *   - a media upload has no idempotency key in this contract; a duplicate upload after a connection reset
+ *     is at worst a second file with the SAME bytes, which the next plan's sha256 match treats identically
+ *     to the first (harmless, unlike creating a second logical record).
+ * A 4xx is a server refusal (`CliRefusal`, exit 2 — see `bin/blocofy.mjs`'s `exitCodeFor`). A final
+ * 5xx/network failure after retries throws a plain `Error` with `.status` (exit 1).
+ */
+
+export { CliRefusal };
+
+function url(apiUrl, path) {
+  return `${String(apiUrl).replace(/\/+$/, "")}${path}`;
+}
+
+/** A response → its JSON body, or the standard refusal/error thrown (shared by every call below). */
+async function readJsonOrThrow(res) {
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  if (res.ok) {
+    if (json === null) throw new Error(`HTTP ${res.status}: empty or non-JSON response`);
+    return json;
+  }
+  if (res.status >= 400 && res.status < 500) {
+    const error = json?.error && typeof json.error === "object" ? json.error : { code: `http_${res.status}`, message: text.slice(0, 200) || `HTTP ${res.status}` };
+    throw new CliRefusal(res.status, error);
+  }
+  const detail = json?.error?.message ?? (text ? text.slice(0, 200) : "");
+  throw Object.assign(new Error(`HTTP ${res.status}${detail ? `: ${detail}` : ""}`), { status: res.status });
+}
+
+async function requestJson(method, target, { apiKey, onRetry = null, body }) {
+  const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  const res = await fetchWithRetry(target, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) }, { onRetry });
+  return readJsonOrThrow(res);
+}
+
+/** `GET /api/v1/site-state` → `{schema_version, manifest, files, assets, diagnostics}`. */
+export function fetchSiteStateExport({ apiUrl, apiKey, onRetry = null }) {
+  return requestJson("GET", url(apiUrl, "/api/v1/site-state"), { apiKey, onRetry });
+}
+
+/** `POST /api/v1/site-state/plan` → the plan (read-only; no side effects). */
+export function planSiteState({ apiUrl, apiKey, body, onRetry = null }) {
+  return requestJson("POST", url(apiUrl, "/api/v1/site-state/plan"), { apiKey, onRetry, body });
+}
+
+/** `POST /api/v1/site-state/apply` → `{status, plan_hash, applied, not_applied, report, theme_source}`. */
+export function applySiteState({ apiUrl, apiKey, body, onRetry = null }) {
+  return requestJson("POST", url(apiUrl, "/api/v1/site-state/apply"), { apiKey, onRetry, body });
+}
+
+/** `POST /api/v1/site-state/publish` → `{status:"published", plan_hash, target_instance, swapped, navigation, globals}`. */
+export function publishSiteState({ apiUrl, apiKey, body, onRetry = null }) {
+  return requestJson("POST", url(apiUrl, "/api/v1/site-state/publish"), { apiKey, onRetry, body });
+}
+
+/** Download one exported asset's bytes from its own delivery URL (not the v1 API — no auth header). */
+export async function downloadAssetBytes({ url: assetUrl, onRetry = null }) {
+  const res = await fetchWithRetry(assetUrl, {}, { onRetry });
+  if (!res.ok) throw new Error(`could not download ${assetUrl} (HTTP ${res.status})`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/** `POST /api/v1/media` (multipart `file` field) → `{file: {...}}`. Used to satisfy `assets_missing`. */
+export async function uploadMediaAsset({ apiUrl, apiKey, filename, content, mime = "application/octet-stream", onRetry = null }) {
+  const form = new FormData();
+  form.set("file", new Blob([content], { type: mime }), filename);
+  const res = await fetchWithRetry(
+    url(apiUrl, "/api/v1/media"),
+    { method: "POST", headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" }, body: form },
+    { onRetry },
+  );
+  return readJsonOrThrow(res);
+}