@blocofy/cli 0.9.0 → 0.11.0

package/lib/theme-sync.mjs

@@ -1,12 +1,18 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 
 import { THEME_DIRS, localPathFor, readLocalTemplates } from "./local-theme.mjs";
+import { fetchWithRetry } from "./http.mjs";
+import { PagesCliError, stagedWrite } from "./page-files.mjs";
 
 /**
  * `blocofy theme pull/push`. Talks to the platform's `/api/dev/theme` endpoint
  * (Bearer token). pull = GET → write to disk (re-adding `.liquid`); push =
  * readLocalTemplates → POST (create/update; no delete).
+ *
+ * CF-T3: every request goes through `fetchWithRetry` (lib/http.mjs — 429/502/503/504 + network errors, Retry-After).
+ * All are safe to resend: reads, a keyed (or naturally idempotent upsert) theme POST, publish (sets a pointer),
+ * rename (sets a label). `onRetry` surfaces each retry on stderr.
  */
 
 /**
@@ -18,6 +24,13 @@ import { THEME_DIRS, localPathFor, readLocalTemplates } from "./local-theme.mjs"
 const CANONICAL_PROTOCOL = "1";
 const CANONICAL_CAPABILITIES = "validate,dry-run,diff,idempotency-key,target-instance";
 
+/**
+ * CF-T5 review I1 — OPTIONAL capabilities (never part of the required fence above). `theme-locales`: this CLI sends the
+ * workspace's `locales/*` files, so a canonical deploy may replace `locales/` like any other theme folder (a server
+ * that sees no declaration keeps stored locale rows). Sent on every theme POST; GETs don't need it.
+ */
+const OPTIONAL_CAPABILITIES = "theme-locales";
+
 function canonicalHeaders(extra = {}) {
   return { "x-blocofy-protocol": CANONICAL_PROTOCOL, "x-blocofy-capabilities": CANONICAL_CAPABILITIES, ...extra };
 }
@@ -35,6 +48,16 @@ async function errorText(res) {
   return text || `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""}`;
 }
 
+/** `errorText` as an Error that keeps the HTTP status (exit codes: 4xx → 2, 5xx → 1). */
+async function responseError(res) {
+  const detail = await errorText(res);
+  const err = new Error(typeof detail === "string" ? detail : detail?.message ?? JSON.stringify(detail));
+  err.status = res.status;
+  if (typeof detail === "object" && detail && typeof detail.code === "string") err.code = detail.code;
+  else if (typeof detail === "string" && /^[a-z][a-z0-9_]*$/.test(detail)) err.code = detail;
+  return err;
+}
+
 /**
  * Yapılandırılmış HTTP hatası (0.5.0): mesajın yanında `code` (sunucunun `error` alanı), `status` ve tam
  * `body` taşınır — 426 `cli_upgrade_required` (fence.missing/requiredVersion) ve 409 `idempotency_conflict`
@@ -61,57 +84,57 @@ async function httpError(res) {
  * alanını hiç dönmez → false → `--dry-run` reddedilir; aksi hâlde eski sunucu `dryRun`'ı yok sayıp GERÇEK
  * yazım yapardı (0.5.0 öncesi sessiz-yazım regresyonu).
  */
-export async function fetchCanonicalSupport({ url, token }) {
+export async function fetchCanonicalSupport({ url, token, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/theme`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme`, {
     headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
-  });
+  }, { onRetry });
   if (!res.ok) throw await httpError(res);
   const body = await res.json();
   return { supported: body?.protocol === 1 };
 }
 
-/** Backoff delays (ms) between attempts — index 0 = after the first failure. */
-const RETRY_BACKOFF_MS = [300, 900];
-
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
 /**
- * fetch wrapper that retries ONLY on transient failures: a thrown fetch (network
- * error / connection reset) or a 5xx / 429 response. Permanent 4xx (401/403/422 …)
- * fail immediately — no retry. Max 2 retries with a short backoff (300ms, 900ms).
- *
- * Safe because every endpoint here is idempotent: theme push is a file upsert
- * (create/update, no delete), pull/whoami/session/site are reads, publish sets a
- * pointer. Re-sending the same request cannot double-apply anything.
+ * CF-T1/T2 review I1 — a pulled path is accepted only if `readLocalTemplates` would read it back: a top-level theme dir
+ * (exact case) with a file below it, or `config/settings_schema.json`. Any `.blocofy`/staging segment (compared
+ * case-insensitively: APFS/NTFS fold case, so `.BLOCOFY/project.json` IS the binding) and any dot-directory (`.git`…)
+ * is refused. Returns a reason string, or null when the path is acceptable.
+ */
+/**
+ * The flat root files a theme actually HAS. The platform's starter themes ship exactly these two, so exactly
+ * these two come down.
  *
- * `onRetry({ attempt, retries, reason })` is called before each wait so callers can
- * surface a "Network error, retrying…" line (not silent).
+ * This is an allowlist on purpose. It was briefly a denylist of tooling filenames, and that inverted the rule
+ * the rest of this function is built on: anything the server named that was not a lockfile - `CLAUDE.md`,
+ * `AGENTS.md`, `next.config.js` - was written straight into the developer's project root by an ordinary pull.
+ * A theme download must never be able to place a file the developer's own tooling then trusts. If a theme
+ * legitimately grows another root file, this set is where it is added, deliberately.
  */
-export async function fetchWithRetry(input, init, { retries = 2, onRetry, backoff = RETRY_BACKOFF_MS } = {}) {
-  let lastErr;
-  for (let attempt = 0; attempt <= retries; attempt += 1) {
-    let res;
-    try {
-      res = await fetch(input, init);
-    } catch (err) {
-      // Thrown fetch = network-level failure (DNS, reset, "fetch failed"). Transient.
-      lastErr = err;
-      if (attempt === retries) throw err;
-      onRetry?.({ attempt: attempt + 1, retries, reason: err?.message ?? String(err) });
-      await sleep(backoff[attempt] ?? 0);
-      continue;
-    }
-    // 5xx / 429 = transient server-side; retry. Other statuses (incl. 4xx) return as-is.
-    if ((res.status >= 500 || res.status === 429) && attempt < retries) {
-      onRetry?.({ attempt: attempt + 1, retries, reason: `HTTP ${res.status}` });
-      await sleep(backoff[attempt] ?? 0);
-      continue;
-    }
-    return res;
+const ROOT_FILES_ALLOWED = new Set(["readme.md", "blueprint.json"]);
+
+function pullPathProblem(rel) {
+  const segs = rel.split("/");
+  if (segs.some((seg) => { const l = seg.toLowerCase(); return l === ".blocofy" || l.startsWith(".blocofy-staging-"); })) return "reserved CLI path";
+  if (segs.slice(0, -1).some((seg) => seg.startsWith("."))) return "hidden directory";
+  // `config/` — the theme's own configuration rows. `settings_schema.json` is the one a push sends back; the
+  // platform serves the others (a starter theme ships `config/theme.json`) and a pull that refused them
+  // refused the WHOLE download, so a freshly provisioned site could not be pulled at all. They are written
+  // read-only: the push gate accepts only `settings_schema.json` under `config/`, and `pages`/`settings`
+  // have their own commands. One flat level, no nesting.
+  if (segs[0] === "config") {
+    if (segs.length !== 2) return "config files are one level deep";
+    // `settings pull` owns this name; a theme row must not shadow the file that command writes.
+    return segs[1] === "settings.json" ? "config/settings.json belongs to `settings pull`" : null;
+  }
+  if (segs.length === 1) {
+    // A FLAT FILE AT THE THEME ROOT. The platform stores rows a push does not send (the starter themes ship
+    // `README.md` and `blueprint.json`) and serves them on pull; refusing them refused the whole download.
+    // Case-folded, because APFS and NTFS fold case: `Readme.MD` and `README.md` are one file on disk.
+    if (segs[0].startsWith(".")) return "hidden file";
+    return ROOT_FILES_ALLOWED.has(segs[0].toLowerCase()) ? null : "not a theme file at the theme root";
   }
-  // Unreachable (loop returns or throws), but keeps the type honest.
-  throw lastErr;
+  if (!THEME_DIRS.has(segs[0])) return "not a theme file (would not be pushed back)";
+  return null;
 }
 
 /**
@@ -119,22 +142,32 @@ export async function fetchWithRetry(input, init, { retries = 2, onRetry, backof
  * With `draft`, pulls the "CLI Draft" instance (what `theme dev` syncs into)
  * instead of the live theme — symmetric with `push --draft`.
  */
-export async function pullTheme({ dir, url, token, draft = false, instance = null }) {
+export async function pullTheme({ dir, url, token, draft = false, instance = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const query = instance ? `?instance=${encodeURIComponent(instance)}` : draft ? "?draft=1" : "";
-  const res = await fetch(`${base}/api/dev/theme${query}`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme${query}`, {
     headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   const { files } = await res.json();
-  let count = 0;
-  for (const [key, content] of Object.entries(files ?? {})) {
-    const full = join(dir, localPathFor(key));
-    mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, typeof content === "string" ? content : "");
-    count += 1;
+  // CF-T2: staged + contained (all-or-nothing). Every path is validated before the first byte is written; a
+  // server path that escapes the directory, targets the CLI's own `.blocofy/` binding, or would not be read back by
+  // the next push refuses the whole pull.
+  const entries = Object.entries(files ?? {}).map(([key, content]) => [localPathFor(key), content]);
+  const rejected = entries.map(([rel]) => [rel, pullPathProblem(rel)]).filter(([, problem]) => problem);
+  if (rejected.length) {
+    throw new PagesCliError("PAGES_PATH_ESCAPE", "The server sent a path this CLI does not write; nothing was written.", {
+      diagnostics: rejected.map(([rel, problem]) => ({ level: "error", code: "PAGES_PATH_ESCAPE", message: problem, path: rel })),
+    });
+  }
+  const created = !existsSync(dir);
+  mkdirSync(dir, { recursive: true });
+  try {
+    return { count: stagedWrite(realpathSync(dir), entries) };
+  } catch (error) {
+    if (created) rmSync(dir, { recursive: true, force: true }); // no empty directory left behind
+    throw error;
   }
-  return { count };
 }
 
 /**
@@ -143,12 +176,12 @@ export async function pullTheme({ dir, url, token, draft = false, instance = nul
  * öncesi (hedef tenant'ı yaz) çağırır; yanlış-tenant'a yazımı görünür kılar.
  * `{ site: { id, slug, name }, liveThemeId }`.
  */
-export async function fetchWhoami({ url, token }) {
+export async function fetchWhoami({ url, token, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/whoami`, {
+  const res = await fetchWithRetry(`${base}/api/dev/whoami`, {
     headers: { authorization: `Bearer ${token}` },
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }
 
@@ -156,12 +189,12 @@ export async function fetchWhoami({ url, token }) {
  * Dev session bilgisi (#119 `theme dev`): platform draft instance'ı hazırlar ve
  * 3 görünümün URL'lerini döner — `{ draftInstanceId, previewUrl, editorUrl, site }`.
  */
-export async function fetchDevSession({ url, token, name = null }) {
+export async function fetchDevSession({ url, token, name = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const query = name ? `?name=${encodeURIComponent(name)}` : "";
-  const res = await fetch(`${base}/api/dev/session${query}`, {
+  const res = await fetchWithRetry(`${base}/api/dev/session${query}`, {
     headers: { authorization: `Bearer ${token}` },
-  });
+  }, { onRetry });
   if (!res.ok) {
     const detail = await errorText(res);
     // Yeni sunucular 410'da açıklayıcı bir gövde döndürür — onu olduğu gibi göster, o otoritedir.
@@ -173,11 +206,79 @@ export async function fetchDevSession({ url, token, name = null }) {
           "(HTTP 410). Draft sync and `theme publish` are unaffected — they use different endpoints.",
       );
     }
-    throw new Error(detail);
+    throw Object.assign(new Error(detail), { status: res.status });
   }
   return res.json();
 }
 
+/**
+ * TPUSH-5 (6.5) — what a dry run binds the apply to. A server with the 6.5 contract answers a keyed dry run with the
+ * `manifestHash` of the files it checked and the `pointerVersion` its plan ran from (null: no deployment yet); the
+ * apply sends both back (`manifestHash`, `expectedPointerVersion`) so it is refused unless it writes exactly those
+ * bytes over exactly that state. An older server answers neither and gets the 0.10 body unchanged.
+ * The pointer version is per instance, so the apply also names the instance the plan ran against: a server that
+ * answers `targetInstance` (an opaque theme handle, or null for "a new draft") gets it back as
+ * `expectedTargetInstance` and refuses 409 `target_changed` when the apply would write anywhere else.
+ */
+function pushBindings(plan) {
+  if (typeof plan?.manifestHash !== "string" || !/^[0-9a-f]{64}$/.test(plan.manifestHash)) return {};
+  const v = plan.pointerVersion;
+  const t = plan.targetInstance;
+  return {
+    manifestHash: plan.manifestHash,
+    ...(v === null || (Number.isInteger(v) && v >= 0) ? { expectedPointerVersion: v } : {}),
+    ...(t === null || (typeof t === "string" && t !== "") ? { expectedTargetInstance: t } : {}),
+  };
+}
+
+/**
+ * The paths a dry-run plan says the push would remove. `config/settings.json` is left out: a stored row there is the
+ * anomaly every canonical deploy cleans up (the settings themselves live in site_themes), not a theme file.
+ */
+function plannedRemovals(plan) {
+  if (!Array.isArray(plan?.files)) return [];
+  return plan.files.filter((f) => f?.outcome === "removed" && typeof f.path === "string" && f.path !== "config/settings.json").map((f) => f.path);
+}
+
+async function isReadbackUnverified(res) {
+  try {
+    return (await res.json())?.error === "readback_unverified";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The paths a push can send: the mirror of the server's gate — multi-segment paths under THEME_DIRS plus the one
+ * config exception (a slash-less remote key such as a bare `layout` would be refused 422 by the server).
+ */
+function sendable(key) {
+  return (key.includes("/") && THEME_DIRS.has(key.split("/")[0] ?? "")) || key === "config/settings_schema.json";
+}
+
+/**
+ * THEME_PUSH_TARGET_CHANGED — the plan would remove files this push did not carry, and says only what is true of them.
+ * A path the push cannot send (outside the merge mirror, e.g. a bare `layout`) is never kept by a re-run, nor by a
+ * local file at that path: only --prune gets past it. That includes every path the merge probe returned, since a
+ * sendable one would have been merged. Any other path was either added while the push ran (a re-run reads and keeps
+ * it) or is a row the probe cannot list (it lists published rows only), which no re-run keeps either.
+ */
+function targetChangedError(paths, remote) {
+  const notCarryable = paths.filter((p) => Object.hasOwn(remote, p) || !sendable(p));
+  const unseen = paths.filter((p) => !notCarryable.includes(p));
+  const parts = [`The dry run would remove ${paths.length} file(s) this push does not have locally (${paths.join(", ")}). Nothing was written.`];
+  if (notCarryable.length) {
+    parts.push(`${notCarryable.join(", ")}: the push cannot carry these paths, so running it again will not keep them; it can go ahead only with --prune, which removes them.`);
+  }
+  if (unseen.length) {
+    parts.push(
+      `${unseen.join(", ")}: not on the target when this push read it. If they were added while this push was running, run the push again and it keeps them. ` +
+        "If the same files stop the push again, the push cannot read them (for example a theme file that is not published) and cannot keep them: pass --prune to remove them, or add a local file at that path to replace it.",
+    );
+  }
+  return Object.assign(new Error(parts.join(" ")), { code: "THEME_PUSH_TARGET_CHANGED", details: { paths, notCarryable } });
+}
+
 /**
  * Write the local theme to the site (create/update; no delete). With `draft`,
  * writes to a draft theme instance instead of the live theme — preview & publish
@@ -187,78 +288,110 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   const base = url.replace(/\/+$/, "");
   const files = readLocalTemplates(dir);
   const headersFor = (extra = {}) => canonicalHeaders({ authorization: `Bearer ${token}`, ...extra });
-  const remoteOnlyKept = [];
-  const remoteOnlyRemoved = [];
-  if (idempotencyKey && !dryRun) {
-    // 0.5.0 kanonik push üç aşamadır (denetim düzeltmeleri):
-    //  1) PREFLIGHT dry-run POST (yalnız yerel küme): 422/426 sınıfı hatalar SUNUCUDA HİÇBİR ŞEY
-    //     provizyonlanmadan yakalanır — probe GET'i taslak yaratabildiği için başarısız bir push
-    //     arkada instance + sayfa klonu bırakıyordu.
-    //  2) MERGE PROBE GET: "push silmez" garantisi — uzakta olup yerelde olmayan, kapı-kabul-eden
-    //     dosyalar payload'a aynen eklenir; kapı-dışı satırları (README.md vb.) sunucunun
-    //     retained-rows kuralı korur. `--prune` bu dosyaları EKLEMEZ (kanonik deploy klasörleri
-    //     atomik değiştirir → silinirler) ve yazımdan ÖNCE `confirmPrune(liste)`'ye bildirir.
-    //     PS-09: taslak hedefte taslak-bayraklı GET KULLANILMAZ — sunucuda taslak provizyonlar (yan
-    //     etki; yarıda kalırsa boş taslak bırakırdı). Mevcut CLI taslağı `/api/dev/site`'tan
-    //     (`source === "import"`, sunucunun ensureDraftInstance seçimiyle aynı: id sıralı ilk) bulunup
-    //     `?instance=` ile yoklanır; yoksa yoklanacak uzak dosya da yoktur → probe atlanır.
-    //  3) Gerçek POST. Dev-sync key göndermediği için bu aşamaların hiçbirini ödemez.
-    const pre = await fetchWithRetry(
+  const postHeaders = (extra = {}) => headersFor({ "content-type": "application/json", "x-blocofy-optional-capabilities": OPTIONAL_CAPABILITIES, ...extra });
+  const target = instance ? { files, instance } : name ? { files, draft, name } : { files, draft };
+  const post = (body, key, retry = {}) =>
+    fetchWithRetry(
       `${base}/api/dev/theme`,
-      { method: "POST", headers: headersFor({ "content-type": "application/json", "x-idempotency-key": idempotencyKey }), body: JSON.stringify({ ...(instance ? { files, instance } : { files, draft, ...(name ? { name } : {}) }), dryRun: true }) },
-      { onRetry },
+      { method: "POST", headers: postHeaders(key ? { "x-idempotency-key": key } : {}), body: JSON.stringify(body) },
+      { onRetry, ...retry },
     );
-    if (!pre.ok) throw await httpError(pre);
 
-    let probeInstance = instance;
-    if (!instance && draft) {
-      const status = await fetchSiteStatus({ url, token });
-      probeInstance = (status?.drafts ?? []).find((d) => d.source === "import")?.id ?? null;
-    }
-    let remote = {};
-    if (probeInstance || !draft) {
-      const query = probeInstance ? `?instance=${encodeURIComponent(probeInstance)}` : "";
-      const probe = await fetch(`${base}/api/dev/theme${query}`, { headers: headersFor() });
-      if (!probe.ok) throw await httpError(probe);
-      remote = (await probe.json()).files ?? {};
-    }
-    for (const [key, content] of Object.entries(remote)) {
-      if (key in files) continue;
-      const top = key.split("/")[0] ?? "";
-      // Sunucu kapı-kabul kümesinin birebir aynası: THEME_DIRS altı ÇOK-SEGMENTLİ path'ler + tek
-      // config istisnası (çıplak `layout` gibi slash'sız bir uzak anahtar sunucuda 422 olurdu).
-      if ((key.includes("/") && THEME_DIRS.has(top)) || key === "config/settings_schema.json") {
-        if (prune) {
-          remoteOnlyRemoved.push(key);
-        } else {
-          files[key] = typeof content === "string" ? content : "";
-          remoteOnlyKept.push(key);
-        }
+  // Keyless (theme dev's draft sync): one POST to the per-file writer — no probe, no plan (deliberate legacy path).
+  if (!idempotencyKey) {
+    const res = await post(dryRun ? { ...target, dryRun: true } : target, null);
+    if (!res.ok) throw await httpError(res);
+    return res.json();
+  }
+
+  // Keyed canonical push (and its --dry-run), TPUSH-5: ONE manifest for the dry run and the apply.
+  //  1) MERGE PROBE GET — "push does not delete": remote files missing locally that the server's gate accepts are
+  //     added to the payload verbatim; rows outside that set (README.md…) are kept by the server's retained-rows
+  //     rule. `--prune` leaves them out instead (the canonical deploy replaces the folders, so they are removed).
+  //     PS-09: a draft target is never probed with a draft-flagged GET (that provisions a draft server-side). The
+  //     existing CLI draft is found via `/api/dev/site` (`source === "import"`, the server's own pick: the first by
+  //     id) and probed by handle; with no draft there is nothing remote to merge, so there is no probe.
+  //  2) DRY RUN of that MERGED payload. On a 6.5 server this is the control plane's rolled-back plan of the very
+  //     operation the apply runs: refused by what the apply is refused by, with per-file outcomes, the manifest hash
+  //     and the pointer version it ran from. It carries its OWN throwaway key: the control plane fingerprints the
+  //     action, so a plan under a key an earlier deploy already spent is refused 409 — a same-key retry of a
+  //     committed push could never converge. A plan removing a file the probe did not see means the target changed
+  //     under this push; without --prune that is refused (push does not delete), with --prune it is confirmed.
+  //  3) APPLY of the same payload under the push key, bound by `manifestHash` + `expectedPointerVersion`.
+  //  theme dev's sync sends no key and pays none of this.
+  const remoteOnlyKept = [];
+  const remoteOnlyRemoved = [];
+  let probeInstance = instance;
+  if (!instance && draft) {
+    const status = await fetchSiteStatus({ url, token, onRetry });
+    probeInstance = (status?.drafts ?? []).find((d) => d.source === "import")?.id ?? null;
+  }
+  let remote = {};
+  if (probeInstance || !draft) {
+    const query = probeInstance ? `?instance=${encodeURIComponent(probeInstance)}` : "";
+    const probe = await fetchWithRetry(`${base}/api/dev/theme${query}`, { headers: headersFor() }, { onRetry });
+    if (!probe.ok) throw await httpError(probe);
+    remote = (await probe.json()).files ?? {};
+  }
+  for (const [key, content] of Object.entries(remote)) {
+    if (key in files) continue;
+    if (sendable(key)) {
+      if (prune) {
+        remoteOnlyRemoved.push(key);
+      } else {
+        files[key] = typeof content === "string" ? content : "";
+        remoteOnlyKept.push(key);
       }
     }
-    remoteOnlyKept.sort();
-    remoteOnlyRemoved.sort();
-    if (remoteOnlyRemoved.length && confirmPrune && !(await confirmPrune(remoteOnlyRemoved))) {
-      return { aborted: true, remoteOnlyRemoved };
-    }
   }
-  const target = instance ? { files, instance } : name ? { files, draft, name } : { files, draft };
-  // dryRun asks the server to validate (auth + snapshot + hostile-Liquid worker) WITHOUT writing.
-  const payload = dryRun ? { ...target, dryRun: true } : target;
-  const headers = canonicalHeaders({ "content-type": "application/json", authorization: `Bearer ${token}` });
-  if (idempotencyKey) headers["x-idempotency-key"] = idempotencyKey;
-  const res = await fetchWithRetry(
-    `${base}/api/dev/theme`,
-    { method: "POST", headers, body: JSON.stringify(payload) },
-    { onRetry },
-  );
-  if (!res.ok) throw await httpError(res);
-  const json = await res.json();
-  return {
-    ...json,
+
+  // A plan's 502 readback_unverified is a verdict on a rolled-back plan, not a transient failure: not resent.
+  const pre = await post({ ...target, dryRun: true }, `cli-plan-${randomUUID()}`, { isFinal: isReadbackUnverified });
+  if (!pre.ok) throw Object.assign(await httpError(pre), { phase: "plan" });
+  const plan = await pre.json();
+  const unexpected = plannedRemovals(plan).filter((p) => !remoteOnlyRemoved.includes(p)).sort();
+  if (unexpected.length && !prune) throw targetChangedError(unexpected, remote);
+  remoteOnlyRemoved.push(...unexpected);
+  remoteOnlyKept.sort();
+  remoteOnlyRemoved.sort();
+  const extras = {
     ...(remoteOnlyKept.length ? { remoteOnlyKept } : {}),
     ...(remoteOnlyRemoved.length ? { remoteOnlyRemoved } : {}),
   };
+  if (dryRun) return { ...plan, ...extras };
+  if (remoteOnlyRemoved.length && confirmPrune && !(await confirmPrune(remoteOnlyRemoved))) {
+    return { aborted: true, remoteOnlyRemoved };
+  }
+
+  const bindings = pushBindings(plan);
+  // An apply attempt without a certain answer (network error, 429/502/503/504) is resent under the same key. A
+  // refusal of the resend says nothing about that earlier attempt: "unknown", or "committed" when its answer said so.
+  let earlierAttempt = null;
+  const applyError = (err) => {
+    Object.assign(err, { phase: "apply" });
+    // target_changed names the current target; the one this push planned against is known only here.
+    if ("expectedTargetInstance" in bindings) err.expectedTargetInstance = bindings.expectedTargetInstance;
+    if (earlierAttempt) err.earlierAttempt = earlierAttempt;
+    return err;
+  };
+  let res;
+  try {
+    res = await post({ ...target, ...bindings }, idempotencyKey, {
+      onRetry: (info) => {
+        earlierAttempt ??= "unknown";
+        onRetry?.(info);
+      },
+      isFinal: async (attempt) => {
+        if ((await attempt.json().catch(() => null))?.committed === true) earlierAttempt = "committed";
+        return false;
+      },
+    });
+  } catch (error) {
+    // No answer to the last attempt either (network error, timeout): the write's outcome is unknown.
+    throw applyError(error);
+  }
+  if (!res.ok) throw applyError(await httpError(res));
+  return { ...(await res.json()), ...extras };
 }
 
 /**
@@ -267,13 +400,13 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
  * (sayfa klonları dahil), read-only bir komut mutasyon tetikleyemez (0.5.0 denetim düzeltmesi). Çağıran
  * çıktıyı "canlıya göre fark" diye etiketler. Returns `{ added, changed, removed }` (stripped keys).
  */
-export async function diffTheme({ dir, url, token, instance = null }) {
+export async function diffTheme({ dir, url, token, instance = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const query = instance ? `?instance=${encodeURIComponent(instance)}` : "";
-  const res = await fetch(`${base}/api/dev/theme${query}`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme${query}`, {
     headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   const { files: remote = {} } = await res.json();
   const local = readLocalTemplates(dir);
   const added = [];
@@ -291,14 +424,14 @@ export async function diffTheme({ dir, url, token, instance = null }) {
  * içi-sayfasız bir instance'ı reddeder ya da canlının sayfalarını klonlar (#431) —
  * yayın sonrası site asla 404'e düşmez. `{ ok, published, cloned }` döner.
  */
-export async function publishInstance({ url, token, instanceId }) {
+export async function publishInstance({ url, token, instanceId, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/publish`, {
+  const res = await fetchWithRetry(`${base}/api/dev/publish`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
     body: JSON.stringify({ instanceId }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }
 
@@ -307,14 +440,14 @@ export async function publishInstance({ url, token, instanceId }) {
  * bir etiket — canlı instance dahil sahip olunan her instance yeniden adlandırılabilir.
  * `{ ok, id, name }` döner.
  */
-export async function renameInstance({ url, token, instance, name }) {
+export async function renameInstance({ url, token, instance, name, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/theme/rename`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme/rename`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
     body: JSON.stringify({ instance, name }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }
 
@@ -322,9 +455,9 @@ export async function renameInstance({ url, token, instance, name }) {
  * Site sağlık/durum özeti (`GET /api/dev/site`) — `blocofy status`. Canlı tema instance'ı,
  * instance-başına sayfa dağılımı, taslaklar ve health döner.
  */
-export async function fetchSiteStatus({ url, token }) {
+export async function fetchSiteStatus({ url, token, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/site`, { headers: { authorization: `Bearer ${token}` } });
-  if (!res.ok) throw new Error(await errorText(res));
+  const res = await fetchWithRetry(`${base}/api/dev/site`, { headers: { authorization: `Bearer ${token}` } }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocofy/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Develop your Blocofy theme locally against live data with instant preview — login, theme dev, pull, push.",
   "type": "module",
   "license": "MIT",