@blocofy/cli 0.8.0 → 0.10.0

package/lib/credentials.mjs

@@ -1,92 +1,248 @@
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync, chmodSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { SecretStoreError, secretStoreFor, writeJsonAtomic } from "./secret-store.mjs";
+
 /**
- * Blocofy CLI credentials. `blocofy login` writes the platform URL + dev token to
- * `~/.blocofy/credentials.json` (0600); `blocofy theme dev` reads it. Environment
- * variables (BLOCOFY_URL/BLOCOFY_TOKEN) take precedence over the file (CI/agents).
- * The token is stored in plaintext on disk (the usual dev-CLI pattern), so the file
- * is locked down to 0600.
+ * CF-T1 (contract C1) — Blocofy CLI credential store v2.
+ *
+ * `~/.blocofy/credentials.json` (0600, dir 0700, atomic tmp+rename) holds NAMED CONTEXTS and no secrets:
+ *
+ *   { "schema_version": 2, "current_context": "<name>|null",
+ *     "contexts": { "<name>": { platform_origin, site: {id,slug,name,domain}|null,
+ *                               dev: { url, secret: { store } }?, api: { url, secret: { store } }?, verified_at } } }
  *
- * 0.8.0: the same file also holds the v1 API pair `{ apiUrl, apiKey }` written by
- * `blocofy login --api-key`. The two pairs coexist: `saveCredentials(patch)` MERGES the
- * patch into the existing JSON (an unreadable/corrupt file counts as `{}`), so an API login
- * keeps the dev pair and a later dev login keeps the API pair. `loadCredentials()` (dev
- * pair) is unchanged; `loadApiCredentials()` resolves the v1 pair (BLOCOFY_API_KEY +
- * BLOCOFY_API_URL first, then the file).
+ * Secrets live in a secret store (lib/secret-store.mjs): `~/.blocofy/secrets.json` by default, the macOS keychain
+ * on opt-in. A pre-v2 flat file `{ url, token, apiUrl, apiKey }` is migrated losslessly on first read into
+ * `contexts.default` (unverified, `site: null`); the original bytes are kept in `credentials.v1.bak.json`
+ * (rollback: copy it back over credentials.json). A corrupt or half file is never rewritten: CREDENTIALS_CORRUPT.
+ *
+ * Environment variables form an ephemeral "env" context: BLOCOFY_URL+BLOCOFY_TOKEN and/or
+ * BLOCOFY_API_URL+BLOCOFY_API_KEY. A half-set pair is a loud error (never a silent fall-through to the file).
  */
 
-const DIR_NAME = ".blocofy";
-const FILE_NAME = "credentials.json";
+export const SCHEMA_VERSION = 2;
+export const ENV_CONTEXT = "env";
+
+/** A local credential problem (exit 1). Messages carry paths, never file content or secrets. */
+export class CredentialsError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "CredentialsError";
+    this.code = code;
+    this.details = details;
+    this.exitCode = 1;
+  }
+}
+
+// Resolved per call (not at import): tests redirect HOME, and os.homedir() honours $HOME on POSIX.
+const dir = () => join(homedir(), ".blocofy");
+export const credentialsPath = () => join(dir(), "credentials.json");
+export const secretsPath = () => join(dir(), "secrets.json");
+export const backupPath = () => join(dir(), "credentials.v1.bak.json");
+
+const stripSlash = (url) => String(url).replace(/\/+$/, "");
+const isStr = (v) => typeof v === "string" && v.length > 0;
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+export const emptyStore = () => ({ schema_version: SCHEMA_VERSION, current_context: null, contexts: {} });
+
+function corrupt(reason) {
+  return new CredentialsError("CREDENTIALS_CORRUPT", `The credentials file cannot be used (${reason}): ${credentialsPath()}. Nothing was written. Fix or remove it, then run \`blocofy login\`.`, { path: credentialsPath() });
+}
 
-// Resolved per call (not at import): tests redirect HOME to a temp dir, and os.homedir()
-// honours $HOME on POSIX.
-function dir() {
-  return join(homedir(), DIR_NAME);
+function validPair(pair) {
+  return pair === undefined || (isObj(pair) && isStr(pair.url) && isObj(pair.secret) && (pair.secret.store === "file" || pair.secret.store === "keychain"));
 }
 
-export function credentialsPath() {
-  return join(dir(), FILE_NAME);
+function validV2(data) {
+  if (data.schema_version !== SCHEMA_VERSION || !isObj(data.contexts)) return false;
+  if (data.current_context !== null && data.current_context !== undefined && typeof data.current_context !== "string") return false;
+  for (const ctx of Object.values(data.contexts)) {
+    if (!isObj(ctx) || !validPair(ctx.dev) || !validPair(ctx.api)) return false;
+    if (ctx.site !== null && ctx.site !== undefined && !(isObj(ctx.site) && (isStr(ctx.site.id) || Number.isFinite(ctx.site.id)))) return false;
+  }
+  return true;
 }
 
-function readExisting() {
+/**
+ * Read the store (migrating a v1 file). `{ secretStore }` options pass through to the secret adapters (tests).
+ * A missing file is an empty store and is NOT created.
+ */
+export function loadStore(options = {}) {
+  let raw;
+  try {
+    raw = readFileSync(credentialsPath(), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return emptyStore();
+    throw new CredentialsError("CREDENTIALS_UNREADABLE", `Cannot read ${credentialsPath()} (${error?.code ?? "error"}).`, { path: credentialsPath() });
+  }
+  let data;
   try {
-    const data = JSON.parse(readFileSync(credentialsPath(), "utf8"));
-    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+    data = JSON.parse(raw);
   } catch {
-    return {}; // missing/corrupt → start clean
+    throw corrupt("not valid JSON");
   }
+  if (!isObj(data)) throw corrupt("not a JSON object");
+  if ("schema_version" in data) {
+    if (!validV2(data)) throw corrupt("unexpected structure");
+    return { schema_version: SCHEMA_VERSION, current_context: data.current_context ?? null, contexts: data.contexts };
+  }
+  return migrateV1(raw, data, options);
 }
 
-/** Merge `patch` into the credentials file and write it with 0600 permissions. */
-export function saveCredentials(patch) {
+/** v1 `{url, token, apiUrl, apiKey}` → v2 `contexts.default`. Validates EVERYTHING before the first write. */
+function migrateV1(raw, data, options) {
+  const known = ["url", "token", "apiUrl", "apiKey"];
+  if (Object.keys(data).length === 0) return emptyStore();
+  for (const k of known) if (k in data && !isStr(data[k])) throw corrupt(`field "${k}" is not a string`);
+  const hasDev = isStr(data.url) || isStr(data.token);
+  const hasApi = isStr(data.apiUrl) || isStr(data.apiKey);
+  if (hasDev && !(isStr(data.url) && isStr(data.token))) throw corrupt("the dev URL/token pair is incomplete");
+  if (hasApi && !(isStr(data.apiUrl) && isStr(data.apiKey))) throw corrupt("the API URL/key pair is incomplete");
+  if (!hasDev && !hasApi) throw corrupt("no credential pair found");
+
+  const context = { platform_origin: null, site: null, verified_at: null };
+  if (hasDev) context.dev = { url: stripSlash(data.url), secret: { store: "file" } };
+  if (hasApi) context.api = { url: stripSlash(data.apiUrl), secret: { store: "file" } };
+  const store = { schema_version: SCHEMA_VERSION, current_context: "default", contexts: { default: context } };
+
+  // 1) exact-bytes backup (never overwrite an older, different backup)
   mkdirSync(dir(), { recursive: true, mode: 0o700 });
-  const merged = { ...readExisting(), ...patch };
-  writeFileSync(credentialsPath(), JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
-  chmodSync(credentialsPath(), 0o600); // create-mode is ignored if the file already exists → enforce it
+  let backup = backupPath();
+  if (existsSync(backup) && readFileSync(backup, "utf8") !== raw) backup = join(dir(), `credentials.v1.bak.${Date.now()}.json`);
+  if (!existsSync(backup)) {
+    writeFileSync(backup, raw, { mode: 0o600 });
+    chmodSync(backup, 0o600);
+  }
+  // 2) secrets, 3) the v2 file (a crash between steps re-runs an idempotent migration from the untouched v1 file)
+  const secrets = secretStoreFor("file", { filePath: secretsPath(), ...options.secretStore });
+  if (hasDev) secrets.set("default", "dev", data.token);
+  if (hasApi) secrets.set("default", "api", data.apiKey);
+  saveStore(store);
+  return store;
 }
 
+const LOCK_STALE_MS = 10000;
+const LOCK_WAIT_MS = 15000;
+export const lockPath = () => join(dir(), ".lock");
+
 /**
- * Resolve credentials: environment first (both vars), then the file. Returns
- * `{ url, token, source }` or null. Trailing slashes are stripped from the URL.
+ * Review M5 — run the synchronous load-modify-save `fn` under an exclusive `~/.blocofy/.lock` (O_EXCL create), so two
+ * concurrent logins/logouts cannot overwrite each other's context or secret. A lock older than 10 s is stale (a
+ * crashed process) and is taken over; waiting longer than 15 s is CREDENTIALS_LOCKED.
  */
-export function loadCredentials() {
-  const envUrl = process.env.BLOCOFY_URL;
-  const envToken = process.env.BLOCOFY_TOKEN;
-  if (envUrl && envToken) {
-    return { url: stripSlash(envUrl), token: envToken, source: "env" };
+export function withStoreLock(fn) {
+  mkdirSync(dir(), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  const pause = new Int32Array(new SharedArrayBuffer(4));
+  for (;;) {
+    try {
+      const fd = openSync(lockPath(), "wx", 0o600);
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+    try {
+      if (Date.now() - statSync(lockPath()).mtimeMs > LOCK_STALE_MS) {
+        rmSync(lockPath(), { force: true });
+        continue;
+      }
+    } catch {
+      continue; // released between the open and the stat
+    }
+    if (Date.now() > deadline) {
+      throw new CredentialsError("CREDENTIALS_LOCKED", `Another blocofy command is updating ${credentialsPath()}. Nothing was written; try again (or remove ${lockPath()} if no blocofy command is running).`, { path: lockPath() });
+    }
+    Atomics.wait(pause, 0, 0, 20);
   }
-  const data = readExisting();
-  if (typeof data.url === "string" && typeof data.token === "string") {
-    return { url: stripSlash(data.url), token: data.token, source: "file" };
+  try {
+    return fn();
+  } finally {
+    rmSync(lockPath(), { force: true });
   }
-  return null;
 }
 
-/**
- * Resolve the v1 API pair: BLOCOFY_API_KEY + BLOCOFY_API_URL (BOTH required — with only one
- * set this throws and does NOT fall through to the file, so a half-configured CI job fails
- * loudly instead of silently using a developer's file), then the file's `{ apiUrl, apiKey }`.
- * Returns `{ apiUrl, apiKey, source }` or null. The thrown message never contains the key.
- */
-export function loadApiCredentials() {
-  const envKey = process.env.BLOCOFY_API_KEY;
-  const envUrl = process.env.BLOCOFY_API_URL;
-  if (envKey && envUrl) {
-    return { apiUrl: stripSlash(envUrl), apiKey: envKey, source: "env" };
+export function saveStore(store) {
+  writeJsonAtomic(credentialsPath(), { schema_version: SCHEMA_VERSION, current_context: store.current_context ?? null, contexts: store.contexts });
+}
+
+/** The secret-store name for NEW secrets: `--keychain` flag or BLOCOFY_SECRET_STORE, default "file". */
+export function defaultSecretStoreName({ keychain = false, env = process.env } = {}) {
+  if (keychain) return "keychain";
+  const v = env.BLOCOFY_SECRET_STORE;
+  if (v === undefined || v === "" || v === "file") return "file";
+  if (v === "keychain") return "keychain";
+  throw new CredentialsError("SECRET_STORE_UNAVAILABLE", `BLOCOFY_SECRET_STORE must be "file" or "keychain".`);
+}
+
+export function openSecretStore(name, options = {}) {
+  try {
+    return secretStoreFor(name, { filePath: secretsPath(), ...options });
+  } catch (error) {
+    throw asCredentialsError(error);
+  }
+}
+
+function asCredentialsError(error) {
+  if (error instanceof SecretStoreError) return new CredentialsError(error.code, error.message);
+  return error;
+}
+
+/** `{ devToken, apiKey }` for a stored context (null where the pair or its secret is absent). */
+export function readSecrets(name, ctx, options = {}) {
+  try {
+    const get = (kind) => (ctx[kind] ? openSecretStore(ctx[kind].secret.store, options).get(name, kind) : null);
+    return { devToken: get("dev"), apiKey: get("api") };
+  } catch (error) {
+    throw asCredentialsError(error);
   }
-  if (envKey || envUrl) {
-    const missing = envKey ? "BLOCOFY_API_URL" : "BLOCOFY_API_KEY";
-    throw new Error(`${missing} is not set — BLOCOFY_API_KEY and BLOCOFY_API_URL must be set together (the credentials file is not consulted while either is set).`);
+}
+
+export function writeSecret(name, kind, storeName, value, options = {}) {
+  try {
+    openSecretStore(storeName, options).set(name, kind, value);
+  } catch (error) {
+    throw asCredentialsError(error);
   }
-  const data = readExisting();
-  if (typeof data.apiUrl === "string" && typeof data.apiKey === "string") {
-    return { apiUrl: stripSlash(data.apiUrl), apiKey: data.apiKey, source: "file" };
+}
+
+export function removeSecrets(name, ctx, options = {}) {
+  for (const kind of ["dev", "api"]) {
+    if (!ctx?.[kind]) continue;
+    try {
+      openSecretStore(ctx[kind].secret.store, options).remove(name, kind);
+    } catch (error) {
+      throw asCredentialsError(error);
+    }
   }
-  return null;
 }
 
-function stripSlash(url) {
-  return url.replace(/\/+$/, "");
+/**
+ * The ephemeral "env" context, or null when no variable is set. Half-set pairs throw (the message names the
+ * missing variable only).
+ */
+export function envContext(env = process.env) {
+  const pair = (urlVar, secretVar) => {
+    const url = env[urlVar];
+    const secret = env[secretVar];
+    if (url && secret) return { url: stripSlash(url), secret };
+    if (url || secret) {
+      const missing = url ? secretVar : urlVar;
+      throw new CredentialsError("ENV_CREDENTIALS_INCOMPLETE", `${missing} is not set — ${urlVar} and ${secretVar} must be set together (the credentials file is not consulted while either is set).`);
+    }
+    return null;
+  };
+  const dev = pair("BLOCOFY_URL", "BLOCOFY_TOKEN");
+  const api = pair("BLOCOFY_API_URL", "BLOCOFY_API_KEY");
+  if (!dev && !api) return null;
+  return {
+    name: ENV_CONTEXT,
+    source: "env",
+    context: { platform_origin: null, site: null, ...(dev ? { dev: { url: dev.url } } : {}), ...(api ? { api: { url: api.url } } : {}) },
+    secrets: { devToken: dev?.secret ?? null, apiKey: api?.secret ?? null },
+  };
 }

package/lib/http.mjs

@@ -0,0 +1,60 @@
+/**
+ * CF-T3 (contract C4, CLI half) — the ONE retry policy for every CLI request that is safe to resend.
+ *
+ * Retried: a thrown fetch (network error, connection reset, per-attempt timeout) and HTTP 429 / 502 / 503 / 504.
+ * NOT retried: 500 and every other status (a 500 may mean the server applied part of the work; a 4xx is a refusal).
+ * At most 3 retries (4 attempts). Wait before retry n: the response's `Retry-After` (delta-seconds or HTTP-date,
+ * capped at 30 s) when present, else 300 ms / 900 ms / 2000 ms. The SAME request is resent: the caller's `init`
+ * (method, headers incl. `x-idempotency-key`, body string) is reused unchanged, so a replay converges on the
+ * server's idempotency handling instead of applying a second, different mutation.
+ *
+ * Callers only route requests here that are safe to replay: reads, upserts, pointer sets, and mutations carrying
+ * an idempotency key. `onRetry({ attempt, retries, reason, waitMs })` fires before every wait (never silent).
+ */
+
+export const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+export const DEFAULT_RETRIES = 3;
+export const DEFAULT_BACKOFF_MS = [300, 900, 2000];
+export const MAX_RETRY_WAIT_MS = 30000;
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** `Retry-After` → milliseconds (capped), or null when absent/unparseable. */
+export function parseRetryAfter(value, nowMs = Date.now()) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const v = value.trim();
+  let ms;
+  if (/^\d+$/.test(v)) ms = Number(v) * 1000;
+  else if (/[A-Za-z]/.test(v)) {
+    const at = Date.parse(v);
+    if (Number.isNaN(at)) return null;
+    ms = at - nowMs;
+  } else return null;
+  return Math.min(Math.max(ms, 0), MAX_RETRY_WAIT_MS);
+}
+
+/**
+ * `fetch` with the retry contract above. Options: `retries`, `backoff` (ms per retry index), `onRetry`,
+ * `fetchImpl` (default: the global fetch at call time), `sleep(ms)`, `now()`, `timeoutMs` (per attempt).
+ */
+export async function fetchWithRetry(input, init = {}, { retries = DEFAULT_RETRIES, backoff = DEFAULT_BACKOFF_MS, onRetry, fetchImpl, sleep = realSleep, now = Date.now, timeoutMs } = {}) {
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  for (let attempt = 0; ; attempt += 1) {
+    const attemptInit = timeoutMs ? { ...init, signal: AbortSignal.timeout(timeoutMs) } : init;
+    let res;
+    try {
+      res = await doFetch(input, attemptInit);
+    } catch (error) {
+      if (attempt >= retries) throw error;
+      const waitMs = backoff[attempt] ?? backoff[backoff.length - 1] ?? 0;
+      onRetry?.({ attempt: attempt + 1, retries, reason: error?.name === "TimeoutError" ? "timeout" : error?.message ?? String(error), waitMs });
+      await sleep(waitMs);
+      continue;
+    }
+    if (!RETRY_STATUSES.has(res.status) || attempt >= retries) return res;
+    const waitMs = parseRetryAfter(res.headers.get("retry-after"), now()) ?? backoff[attempt] ?? backoff[backoff.length - 1] ?? 0;
+    await res.arrayBuffer().catch(() => {}); // release the connection before resending
+    onRetry?.({ attempt: attempt + 1, retries, reason: `HTTP ${res.status}`, waitMs });
+    await sleep(waitMs);
+  }
+}

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");
+}