@blocofy/cli 0.10.0 → 0.11.0

package/lib/site-state.mjs

@@ -196,7 +196,17 @@ export function checkSiteStateTreePaths(paths) {
 
 export const ASSET_REF_PREFIX = "asset:sha256:";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const PLATFORM_ASSET_RE = /\/(?:cdn|assets)\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:[/?#]|$)/i;
+/** Mirror of the platform's `SVG_ASSET_ID_RE` (media/media-ref.ts): a platform SVG asset id, stored lowercase only. */
+const SVG_ASSET_ID_RE = /^bsvg_[0-9abcdefghjkmnpqrstvwxyz]{26}$/;
+// Mirror of the platform's asset-ref.ts grammar (W1 C1 + a8e8666c), piece for piece: FULL-VALUE anchored — only a
+// value that IS one platform asset URL matches; HTML, CSS url(...) or a sentence containing one is carried as is.
+// Whitespace, ", <, > and \ appear nowhere; the host also excludes ' ( ); the path, query and fragment admit ( ) '
+// (encodeURIComponent leaves them unescaped in a media-picker URL such as ".../logo%20(1).png").
+const ASSET_UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const ASSET_HOST = String.raw`(?:(?:https?:)?\/\/[^\s\/?#"'<>()\\]+)?`;
+const ASSET_TAIL = String.raw`(?:\/[^\s?#"<>\\]*)?(?:\?[^\s#"<>\\]*)?(?:#[^\s"<>\\]*)?`;
+export const PLATFORM_ASSET_RE = new RegExp(String.raw`^${ASSET_HOST}\/(?:cdn|assets)\/(${ASSET_UUID})${ASSET_TAIL}$`, "i");
+export const PLATFORM_SVG_RE = new RegExp(String.raw`^${ASSET_HOST}\/cdn\/svg\/(bsvg_[0-9abcdefghjkmnpqrstvwxyz]{26})${ASSET_TAIL}$`);
 export const PLATFORM_METADATA_KEY = "platform";
 export const MEDIA_DECISION_AUDIT_FIELDS = ["decided_by", "decided_at", "policy_version"];
 
@@ -208,14 +218,26 @@ export function parseAssetRef(value) {
   return SHA256_HEX.test(sha) ? sha : null;
 }
 
-/** Mirror of the platform's `normalizeAssetRef` (asset-ref.ts): a platform asset value → its raw uuid. */
+/**
+ * Mirror of the platform's `parseMediaRef` (media/media-ref.ts): a bare stored reference → its canonical id (a
+ * Directus uuid, lowercased; a platform SVG id exactly as stored), or null.
+ */
+function mediaRefId(value) {
+  if (typeof value !== "string") return null;
+  if (SVG_ASSET_ID_RE.test(value)) return value;
+  if (UUID_RE.test(value)) return value.toLowerCase();
+  return null;
+}
+
+/** Mirror of the platform's `normalizeAssetRef` (asset-ref.ts): a value that IS one platform asset reference → its id. */
 export function normalizeAssetRef(value) {
   if (typeof value !== "string") return value;
   const v = value.trim();
   if (!v) return value;
-  if (UUID_RE.test(v)) return v.toLowerCase();
-  const m = v.match(PLATFORM_ASSET_RE);
-  if (m) return m[1].toLowerCase();
+  const bare = mediaRefId(v);
+  if (bare) return bare;
+  const m = v.match(PLATFORM_ASSET_RE) ?? v.match(PLATFORM_SVG_RE);
+  if (m) return mediaRefId(m[1]) ?? value;
   return value;
 }
 
@@ -236,12 +258,13 @@ function mapStrings(value, fn) {
 
 export function encodeAssetRefs(value, shaOf, report) {
   return mapStrings(value, (s) => {
-    const ref = normalizeAssetRef(s);
-    if (typeof ref !== "string" || !UUID_RE.test(ref)) return s;
-    const uuid = ref.toLowerCase();
-    const sha = shaOf(uuid);
+    // Full-value anchored (W1 C1): only a string that IS one reference is rewritten. A platform SVG id goes through
+    // the same lookup as a Directus uuid.
+    const ref = mediaRefId(normalizeAssetRef(s));
+    if (ref === null) return s;
+    const sha = shaOf(ref);
     if (sha === null) {
-      report.foreign.add(uuid);
+      report.foreign.add(ref);
       return s;
     }
     report.used.add(sha);

package/lib/target.mjs

@@ -3,6 +3,7 @@ import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import { dirname, join, resolve } from "node:path";
 
 import { fetchWithRetry } from "./http.mjs";
+import { API_KEY_PREFIX } from "./media-uses.mjs";
 
 /**
  * CF-T1/T2 (contract C2) — project binding + target resolution + remote identity verification.
@@ -244,18 +245,32 @@ function contextMatchesBinding(ctx, project) {
   return isObj(ctx?.site) && sameId(ctx.site.id, project.site_id) && compareOrigin(ctx.platform_origin, project.platform_origin) !== "mismatch";
 }
 
+const authorityLabel = (a) => (a.source === "env" ? "env credentials (BLOCOFY_URL/BLOCOFY_TOKEN, BLOCOFY_API_URL/BLOCOFY_API_KEY)" : `${a.source}=${a.name}`);
+
 /**
  * Contract C2 order: --context → BLOCOFY_CONTEXT → full env pair → .blocofy/local.json → the unique context
  * matching the binding (site.id + platform_origin) → TTY pick among matching candidates → TARGET_CONTEXT_REQUIRED.
- * With a binding present `current_context` is ignored; without one it is used only by `read` commands.
+ *
+ * 1.8 closure (zero silent fallback): BLOCOFY_CONTEXT, the env pair and `.blocofy/local.json` are each a stated
+ * choice. When two of them name DIFFERENT contexts the command is refused before anything is read
+ * (TARGET_CONTEXT_CONFLICT, exit 3) — only an explicit `--context` settles it, and the result still lists what it
+ * overrode (`ignored`). With a binding present `current_context` is ignored; without one it is used only by the
+ * commands that opt in (`allowCurrentContext`: status, target, pages check — contract C2).
  *
  * `getStore()` is called only when a named context is needed (a corrupt file does not block the env context).
- * `prompt(candidates)` → name (TTY only). Returns `{ name, source, context, env? }`.
+ * `prompt(candidates)` → name (TTY only). Returns `{ name, source, context, ignored, env? }`; `ignored` lists the
+ * stated authorities (`{ source, name }`) that named another context.
  */
-export async function resolveContext({ flagContext = null, envContextName = null, envCtx = null, getStore, binding = null, commandClass, isTTY = false, prompt = null }) {
+export async function resolveContext({ flagContext = null, envContextName = null, envCtx = null, getStore, binding = null, allowCurrentContext = false, isTTY = false, prompt = null }) {
+  const stated = [];
+  if (envContextName) stated.push({ source: "BLOCOFY_CONTEXT", name: envContextName });
+  if (envCtx) stated.push({ source: "env", name: ENV_CONTEXT });
+  if (binding?.localContext) stated.push({ source: ".blocofy/local.json", name: binding.localContext });
+
   const named = (name, source) => {
+    const ignored = stated.filter((a) => a.name !== name);
     if (name === ENV_CONTEXT) {
-      if (envCtx) return { name: ENV_CONTEXT, source, context: envCtx.context, env: envCtx };
+      if (envCtx) return { name: ENV_CONTEXT, source, context: envCtx.context, env: envCtx, ignored };
       throw new TargetError("TARGET_CONTEXT_UNKNOWN", `Context "env" needs BLOCOFY_URL+BLOCOFY_TOKEN or BLOCOFY_API_URL+BLOCOFY_API_KEY.`, { context: name });
     }
     const store = getStore();
@@ -263,12 +278,18 @@ export async function resolveContext({ flagContext = null, envContextName = null
     if (!ctx) {
       throw new TargetError("TARGET_CONTEXT_UNKNOWN", `No context named "${name}" (from ${source}). List them with \`blocofy contexts\`.`, { context: name, source });
     }
-    return { name, source, context: ctx };
+    return { name, source, context: ctx, ignored };
   };
 
   if (flagContext) return named(flagContext, "--context");
-  if (envContextName) return named(envContextName, "BLOCOFY_CONTEXT");
-  if (envCtx) return { name: ENV_CONTEXT, source: "env", context: envCtx.context, env: envCtx };
+  if (new Set(stated.map((a) => a.name)).size > 1) {
+    throw new TargetError(
+      "TARGET_CONTEXT_CONFLICT",
+      `Conflicting context choices: ${stated.map(authorityLabel).join(" vs ")}. Nothing was read or written. Choose one explicitly with --context <name>, or unset the others.`,
+      { authorities: stated },
+    );
+  }
+  if (stated.length) return named(stated[0].name, stated[0].source);
 
   const store = getStore();
   const names = Object.keys(store.contexts);
@@ -277,12 +298,11 @@ export async function resolveContext({ flagContext = null, envContextName = null
   }
 
   if (binding) {
-    if (binding.localContext) return named(binding.localContext, ".blocofy/local.json");
     const candidates = names.filter((n) => contextMatchesBinding(store.contexts[n], binding.project));
-    if (candidates.length === 1) return { name: candidates[0], source: "binding", context: store.contexts[candidates[0]] };
+    if (candidates.length === 1) return { name: candidates[0], source: "binding", context: store.contexts[candidates[0]], ignored: [] };
     if (candidates.length > 1 && isTTY && prompt) {
       const picked = await prompt(candidates);
-      if (candidates.includes(picked)) return { name: picked, source: "prompt", context: store.contexts[picked] };
+      if (candidates.includes(picked)) return { name: picked, source: "prompt", context: store.contexts[picked], ignored: [] };
     }
     throw new TargetError(
       "TARGET_CONTEXT_REQUIRED",
@@ -293,10 +313,14 @@ export async function resolveContext({ flagContext = null, envContextName = null
     );
   }
 
-  if (commandClass === "read" && store.current_context && store.contexts[store.current_context]) {
-    return { name: store.current_context, source: "current_context", context: store.contexts[store.current_context] };
+  if (allowCurrentContext && store.current_context && store.contexts[store.current_context]) {
+    return { name: store.current_context, source: "current_context", context: store.contexts[store.current_context], ignored: [] };
   }
-  throw new TargetError("TARGET_CONTEXT_REQUIRED", "Choose the site: pass --context <name> (see `blocofy contexts`) or set BLOCOFY_CONTEXT.", { contexts: names });
+  throw new TargetError(
+    "TARGET_CONTEXT_REQUIRED",
+    "This directory is not bound to a site, so the site must be chosen explicitly: pass --context <name> (see `blocofy contexts`), set BLOCOFY_CONTEXT, or bind the directory (blocofy link <dir> --context <name>).",
+    { contexts: names },
+  );
 }
 
 /** Offline check before any network: a context already recorded for another site cannot serve this binding. */
@@ -312,6 +336,40 @@ export function precheckContext({ binding, resolved }) {
   }
 }
 
+/** The theme dev token's prefix (the v1 API key's is API_KEY_PREFIX, `blcf_live_`). */
+const DEV_TOKEN_PREFIX = "bcf_";
+
+/**
+ * 1.8: the dev token and the v1 API key are two separate credentials and stay two. A pair that holds the other
+ * type's secret is refused before any request (TARGET_CREDENTIAL_WRONG_TYPE, exit 1) — it is never sent to the
+ * other endpoint, and never silently used as the other type. The message names where the secret came from, never
+ * the secret.
+ */
+export function assertCredentialTypes({ resolved, secrets }) {
+  const refuse = (kind, secret) => {
+    const env = Boolean(resolved.env);
+    const where = kind === "dev" ? (env ? "BLOCOFY_TOKEN" : `The dev token of context "${resolved.name}"`) : env ? "BLOCOFY_API_KEY" : `The API key of context "${resolved.name}"`;
+    const other = kind === "dev" ? secret.startsWith("blcf_") : secret.startsWith(DEV_TOKEN_PREFIX);
+    const holds = kind === "dev" ? (other ? "holds a v1 API key (blcf_…)" : "is not a dev token") : other ? "holds a theme dev token (bcf_…)" : "is not a v1 API key";
+    const expected = kind === "dev" ? `a theme dev token starts with ${DEV_TOKEN_PREFIX}` : `a v1 API key starts with ${API_KEY_PREFIX}`;
+    const fix = env
+      ? kind === "dev"
+        ? "put the dev token in BLOCOFY_TOKEN and the API key in BLOCOFY_API_KEY (+ BLOCOFY_API_URL)"
+        : "put the API key in BLOCOFY_API_KEY and the dev token in BLOCOFY_TOKEN (+ BLOCOFY_URL)"
+      : kind === "dev"
+        ? `run \`blocofy login --context ${resolved.name}\``
+        : `run \`blocofy login --api-key --context ${resolved.name}\``;
+    throw new TargetError(
+      "TARGET_CREDENTIAL_WRONG_TYPE",
+      `${where} ${holds}; ${expected}. The dev token and the v1 API key are separate credentials: ${fix}. Nothing was sent.`,
+      { context: resolved.name, pair: kind },
+      1,
+    );
+  };
+  if (resolved.context.dev && typeof secrets.devToken === "string" && !secrets.devToken.startsWith(DEV_TOKEN_PREFIX)) refuse("dev", secrets.devToken);
+  if (resolved.context.api && typeof secrets.apiKey === "string" && !(secrets.apiKey.startsWith(API_KEY_PREFIX) && secrets.apiKey.length > API_KEY_PREFIX.length)) refuse("api", secrets.apiKey);
+}
+
 // ── remote identity ─────────────────────────────────────────────────────────────────────────────────────────
 
 const IDENTITY_TIMEOUT_MS = 15000;

package/lib/theme-sync.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 
 import { THEME_DIRS, localPathFor, readLocalTemplates } from "./local-theme.mjs";
@@ -210,6 +211,74 @@ export async function fetchDevSession({ url, token, name = null, onRetry = null
   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
@@ -220,78 +289,109 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   const files = readLocalTemplates(dir);
   const headersFor = (extra = {}) => canonicalHeaders({ authorization: `Bearer ${token}`, ...extra });
   const postHeaders = (extra = {}) => headersFor({ "content-type": "application/json", "x-blocofy-optional-capabilities": OPTIONAL_CAPABILITIES, ...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 target = instance ? { files, instance } : name ? { files, draft, name } : { files, draft };
+  const post = (body, key, retry = {}) =>
+    fetchWithRetry(
       `${base}/api/dev/theme`,
-      { method: "POST", headers: postHeaders({ "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, 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;
-      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 = postHeaders();
-  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 };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocofy/cli",
-  "version": "0.10.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",