@blocofy/cli 0.13.0 → 0.15.0

package/lib/args.mjs

@@ -8,9 +8,9 @@
  * Sonraki token'ı değer olarak almayan flag'ler. 0.8.0: `api-key` de boolean'dır — `login --api-key`
  * gizli prompt açar; `--api-key <değer>` sözdizimi bilerek YOKTUR (sır argv'ye ve shell geçmişine girmez).
  * CF-T1: `--keychain` (login) ve `--adopt` (link) de değersizdir. CF-T3: `--force` (pages push) da; gerekçesi `--reason <text>`.
- * #925: `--publish` (translations import) da değersizdir.
+ * #925: `--publish` (translations import) da değersizdir. `--require-fresh` (theme work resume) da; `--open` ve `--wait` (theme work request-approval) da.
  */
-const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force", "publish"]);
+const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force", "publish", "require-fresh", "open", "wait"]);
 
 /**
  * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`

package/lib/dev-server.mjs

@@ -9,7 +9,7 @@ import {
   injectLivereload,
   readLocalTemplates,
 } from "./local-theme.mjs";
-import { pushTheme } from "./theme-sync.mjs";
+import { DRAFT_TARGET_AMBIGUOUS, draftSyncErrorLine, pushTheme } from "./theme-sync.mjs";
 
 /**
  * Standalone dev server. For each page request it reads the local theme files and
@@ -20,7 +20,7 @@ import { pushTheme } from "./theme-sync.mjs";
  * separate request); direct `/asset/*` references are served from disk. Images/JS
  * are remote (Directus/CDN), so no local serving is needed for them.
  */
-export function startDevServer({ dir, url, token, port, syncDraft = false, onError, onReload, onRetry, onWarn }) {
+export function startDevServer({ dir, url, token, port, syncDraft = false, instance = null, onError, onReload, onRetry, onWarn, onSyncRefused }) {
   const base = url.replace(/\/+$/, "");
   const clients = new Set();
 
@@ -46,10 +46,27 @@ export function startDevServer({ dir, url, token, port, syncDraft = false, onErr
 
   // Açılıştaki push'u BİR promise olarak tut: ilk render isteği bunu bekler, yoksa ilk sayfa
   // yüklemesi canlı içerikle gelir ve geliştirici "taslağım görünmüyor" sanır.
+  // #989: `instance` (theme dev --instance) syncs into that draft; otherwise the platform picks the CLI draft and
+  // refuses (409 draft_target_ambiguous) when it cannot prove which one that is. A refusal is final for the session:
+  // `onSyncRefused` is told once (the caller exits) — the sync is never retried in a loop.
+  const syncTarget = instance ? { instance, draft: true } : { draft: true };
+  let refused = false;
+  // Final for the session (the caller exits): the platform cannot pick the draft, or the named instance is live.
+  const refusedBy = (err) => {
+    if (err?.code !== DRAFT_TARGET_AMBIGUOUS && err?.code !== "draft_target_is_live") return false;
+    if (!refused) {
+      refused = true;
+      onSyncRefused?.(err);
+    }
+    return true;
+  };
   const draftReady = syncDraft
-    ? pushTheme({ dir, url, token, draft: true, onRetry })
+    ? pushTheme({ dir, url, token, ...syncTarget, onRetry })
         .then(noteHandle)
-        .catch(() => {})
+        .catch((err) => {
+          // #989 re-review P3: a startup sync failure is said, in one line — never swallowed.
+          if (!refusedBy(err)) onWarn?.(draftSyncErrorLine(err));
+        })
     : Promise.resolve();
 
   async function renderPath(pathname) {
@@ -131,14 +148,15 @@ export function startDevServer({ dir, url, token, port, syncDraft = false, onErr
   // hangi dosya, senkron oldu mu, kaç görünüm bağlı (clients.size = açık EventSource'lar).
   const watcher = startWatch(dir, async (file) => {
     let error = null;
-    if (syncDraft) {
+    if (syncDraft && !refused) {
       try {
         // BİLİNÇLE key'siz (0.5.0): dev sync her kayıtta koşar — kanonik mühür (key'li dal) kayıt
         // başına revizyon+deployment üretirdi (retention yok) ve taslak önizlemeye katkısı sıfır.
         // Key'siz istek sunucuda legacy draft yazımıdır; kanonik mühür bilinçli `theme push` işidir.
-        noteHandle(await pushTheme({ dir, url, token, draft: true, onRetry }));
+        noteHandle(await pushTheme({ dir, url, token, ...syncTarget, onRetry }));
       } catch (err) {
-        error = err?.message ?? String(err); // senkron hatası reload'u engellemesin
+        if (refusedBy(err)) return;
+        error = draftSyncErrorLine(err); // senkron hatası reload'u engellemesin
       }
     }
     broadcast();

package/lib/theme-sync.mjs

@@ -50,10 +50,28 @@ async function errorText(res) {
 
 /** `errorText` as an Error that keeps the HTTP status (exit codes: 4xx → 2, 5xx → 1). */
 async function responseError(res) {
+  // #989: keep `reason`/`candidates` (errorText keeps only `error`). Read from a clone so the fallback below still can.
+  const body = await res.clone().json().catch(() => null);
+  if (res.status === 409) {
+    if (body?.error === DRAFT_TARGET_AMBIGUOUS) return withDraftTargetDetails(Object.assign(new Error(DRAFT_TARGET_AMBIGUOUS), { status: 409, code: DRAFT_TARGET_AMBIGUOUS }), body);
+    if (body?.error === PUBLISH_TARGET_UNCONFIRMED) {
+      return Object.assign(new Error(PUBLISH_TARGET_UNCONFIRMED), {
+        status: 409,
+        code: PUBLISH_TARGET_UNCONFIRMED,
+        reason: typeof body.reason === "string" ? body.reason : null,
+        instance: typeof body.instance === "string" ? body.instance : null,
+        name: typeof body.name === "string" ? body.name : null,
+      });
+    }
+  }
   const detail = await errorText(res);
   const err = new Error(typeof detail === "string" ? detail : detail?.message ?? JSON.stringify(detail));
   err.status = res.status;
+  const retryAfter = res.headers.get("retry-after");
+  if (retryAfter) err.retryAfter = retryAfter;
   if (typeof detail === "object" && detail && typeof detail.code === "string") err.code = detail.code;
+  // `{ error: "<sentence>", code }` (e.g. dev/publish `work_not_publishable`): the code sits beside the sentence.
+  else if (typeof body?.code === "string" && /^[a-z][a-z0-9_]*$/.test(body.code)) err.code = body.code;
   else if (typeof detail === "string" && /^[a-z][a-z0-9_]*$/.test(detail)) err.code = detail;
   return err;
 }
@@ -75,9 +93,297 @@ async function httpError(res) {
   err.status = res.status;
   err.code = typeof body?.error === "string" ? body.error : null;
   err.body = body;
+  const retryAfter = res.headers.get("retry-after");
+  if (retryAfter) err.retryAfter = retryAfter;
+  return withDraftTargetDetails(err, body);
+}
+
+/**
+ * #989 — the platform refuses to GUESS which draft a draft push / `pull --draft` / `theme dev` sync writes to when it
+ * cannot prove the draft is the CLI's: more than one candidate draft, a site-state restore draft, or a single draft
+ * without the platform-generated "CLI Draft" name (a renamed CLI draft included). 409 `draft_target_ambiguous` with
+ * `reason` and `candidates` [{instance, name}]; nothing was written. The way through is an explicit `--instance`.
+ */
+export const DRAFT_TARGET_AMBIGUOUS = "draft_target_ambiguous";
+/** K1 (#989): the platform refused to publish a theme the user did not name that is not the site's CLI draft. */
+export const PUBLISH_TARGET_UNCONFIRMED = "publish_target_unconfirmed";
+
+/** The human message for a K1 refusal; `command` is the publish command line to repeat with `--instance`. */
+export function publishTargetUnconfirmedMessage(error, { command = "blocofy theme publish" } = {}) {
+  const why =
+    error?.reason === "site_state_restore"
+      ? "it is a site-state restore draft"
+      : error?.reason === "unrecognized_name"
+        ? 'it is not named "CLI Draft — …" (it may not be the CLI\'s draft)'
+        : error?.reason === "multiple_candidates"
+          ? "the site has more than one draft that could be the CLI draft"
+          : "it is not the site's CLI draft";
+  const h = error?.instance ?? "<handle>";
+  const head = `✗ Refused to publish theme ${h}${error?.name ? ` "${error.name}"` : ""} automatically: ${why}. Nothing was published.`;
+  // K1 review: a restore draft is never handed out as a ready-to-run command (the push rule) — naming it would make the
+  // restore's state live. The user-named themes keep the pre-filled command.
+  if (error?.reason === "site_state_restore") {
+    return [
+      head,
+      `  Warning: publishing ${h} with --instance would make the site-state restore draft LIVE.`,
+      "  Safe paths: publish the restore through its own site-state publish flow, or from the admin panel.",
+      `  If you meant another theme:  ${command} --instance <handle>`,
+      "  (`blocofy status` lists the site's drafts.)",
+    ].join("\n");
+  }
+  return [head, `  To publish exactly this theme, name it:  ${command} --instance ${h}`, "  (`blocofy status` lists the site's drafts.)"].join("\n");
+}
+/**
+ * The platform-generated CLI draft name — the server's TEMPORARY compatibility filter (never proof of ownership):
+ * "CLI Draft", "CLI Draft — <date>" or "CLI Draft — <name>" (what a push with `--name <name>` creates).
+ */
+const CLI_DRAFT_NAME = /^CLI Draft( — .+)?$/;
+/** The name the platform gives a draft a push creates with `--name` (mirror of the server's `cliDraftName`). */
+export function cliDraftName(name) {
+  const clean = String(name ?? "").trim().slice(0, 100);
+  if (!clean) return null;
+  return CLI_DRAFT_NAME.test(clean) ? clean : `CLI Draft — ${clean}`;
+}
+/** The name a site-state restore gives the draft it builds (`Site State · <12 hex>`). */
+const SITE_STATE_DRAFT_NAME = /^Site State · [0-9a-f]{12}$/;
+
+function withDraftTargetDetails(err, body) {
+  if (err.code !== DRAFT_TARGET_AMBIGUOUS) return err;
+  err.reason = typeof body?.reason === "string" ? body.reason : null;
+  err.candidates = Array.isArray(body?.candidates)
+    ? body.candidates
+        .filter((c) => c && typeof c.instance === "string")
+        .map((c) => ({ instance: c.instance, name: typeof c.name === "string" ? c.name : null, ...(typeof c.restore === "boolean" ? { restore: c.restore } : {}) }))
+    : [];
+  // The server names the one candidate safe to suggest (CLI-named, not a restore draft), or null for none.
+  if (body && "suggestedInstance" in body) err.suggestedInstance = typeof body.suggestedInstance === "string" ? body.suggestedInstance : null;
   return err;
 }
 
+/** A candidate that is a site-state restore draft — the server's flag, else its `Site State · …` name. */
+const isRestore = (c) => c.restore === true || SITE_STATE_DRAFT_NAME.test(c.name ?? "");
+
+/**
+ * #989 re-review P3 — one line for a `theme dev` draft-sync failure, in the push/pull wording: 503
+ * `draft_target_unverifiable` (transient; the next save tries again) and 422 `draft_target_is_live` get their own
+ * sentence, the theme-capacity refusals (`themeCapacityRefusal`) theirs, anything else its message. Never swallowed.
+ */
+export function draftSyncErrorLine(err) {
+  if (err?.code === "draft_target_unverifiable") {
+    return "draft sync: the platform could not verify which draft to write to (a read failed on its side). Nothing was written; the next save tries again.";
+  }
+  if (err?.code === "draft_target_is_live") {
+    return "draft sync refused: that is the LIVE theme, and a draft sync never writes live. Nothing was written; pass a draft's handle with --instance (`blocofy status`).";
+  }
+  const capacity = themeCapacityRefusal(err);
+  if (capacity) return `draft sync: ${capacity.short}`;
+  return `draft sync failed: ${err?.message ?? String(err)}`;
+}
+
+const trNumber = new Intl.NumberFormat("tr-TR", { maximumFractionDigits: 1 });
+const isAmount = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const bytesLabel = (b) => (b >= 1024 ** 3 ? `${trNumber.format(b / 1024 ** 3)} GB` : `${trNumber.format(b / 1024 ** 2)} MB`);
+
+/** The admission's typed meter in words (V2 storage bytes; V1 / other `used / limit`), or null. */
+function quotaMeter(d) {
+  if (!d || typeof d !== "object") return null;
+  if (isAmount(d.usedBytes) && isAmount(d.limitBytes)) {
+    const need = isAmount(d.estimateBytes) ? `; yeni taslak yaklaşık ${bytesLabel(d.estimateBytes)} gerektiriyor` : "";
+    return `Kullanılan depolama: ${bytesLabel(d.usedBytes)} / ${bytesLabel(d.limitBytes)}${need}.`;
+  }
+  if (isAmount(d.used) && isAmount(d.limit)) {
+    const what = d.resource === "theme_drafts" ? "Taslak tema sayısı" : typeof d.resource === "string" ? d.resource : "Kullanım";
+    return `${what}: ${d.used} / ${d.limit}.`;
+  }
+  return null;
+}
+
+const CAPACITY_CODES = new Set(["target_missing", "quota_exceeded", "capacity_unavailable", "resource_busy", "source_stale"]);
+/** Transient admission refusals: every attempt answering one of these wrote nothing (a definite answer). */
+export const CAPACITY_RETRYABLE = new Set(["capacity_unavailable", "resource_busy"]);
+
+/**
+ * Theme-capacity program (ADR-0013) — the dev theme endpoint's refusals around the CLI draft, in words:
+ *  - 404 `target_missing`: `pull --draft` found no CLI draft. A read never creates a theme; `push --draft` does.
+ *  - 422 `quota_exceeded`, by `details.resource`:
+ *      `theme_bytes` — the site's theme space (a technical allowance, not the plan) is full. Any theme write can meet
+ *        it, a push to an existing draft included: no "new draft" wording, no plan upgrade; free space by deleting
+ *        unused draft themes (cancelled works' themes included; cancel releases only a work's reserved publish space,
+ *        archive frees no theme bytes), or contact support.
+ *      `theme_drafts` (the legacy draft count of a site not on theme space) — not tied to the plan: remove a draft
+ *        you no longer need; never a plan upgrade.
+ *      `storage_mb` (the plan's storage) — the NEW draft was refused for the plan: the plan message.
+ *  - 503 `capacity_unavailable` / `resource_busy`: transient (Retry-After), never the plan. lib/http.mjs has already
+ *    resent the request within its retry policy; this is the last answer.
+ *  - 409 `source_stale`: the live theme the new draft copies changed meanwhile; running the command again copies it anew.
+ * The platform wrote nothing for that answer. Returns `{ lines, short, message, details }`: `lines` the plain Turkish
+ * explanation (stderr, human mode; first line non-technical), `short` one line for `theme dev`, `message`/`details` the
+ * technical `error [code]` line and `--json` envelope. `null` for any other code (draft_target_ambiguous keeps its own).
+ * `pushCommand` is the user's push command line (its directory argument kept). A refusal of a RESENT push apply
+ * (`earlierAttempt`) says nothing about that earlier attempt, so it never claims "nothing was written" then.
+ */
+export function themeCapacityRefusal(error, { pushCommand = "blocofy theme push" } = {}) {
+  const code = error?.code;
+  if (!CAPACITY_CODES.has(code)) return null;
+  const earlier = error?.phase === "apply" && (error.earlierAttempt === "unknown" || error.earlierAttempt === "committed") ? error.earlierAttempt : null;
+  const done =
+    earlier === "committed"
+      ? "Bu deneme hiçbir şey yazmadı; ancak bu push'un önceki bir denemesi işlendi (yanıtı öyle söyledi)."
+      : earlier === "unknown"
+        ? "Bu deneme hiçbir şey yazmadı; ancak bu push'un önceki bir denemesi kesin yanıt alamadı, yazıp yazmadığı bilinmiyor."
+        : "Hiçbir şey yazılmadı.";
+  const doneEn =
+    earlier === "committed"
+      ? "This attempt wrote nothing, but an earlier attempt of this push was committed (its answer said so)."
+      : earlier === "unknown"
+        ? "This attempt wrote nothing, but an earlier attempt of this push got no definite answer, so whether it wrote is unknown."
+        : "Nothing was written.";
+  const check = earlier ? ["  Tekrar çalıştırmadan önce sitenin taslaklarını `blocofy status` ile kontrol et."] : [];
+  const checkEn = earlier ? " Check the site's drafts with `blocofy status` before running the push again." : "";
+  const extra = earlier ? { earlierAttempt: earlier } : {};
+
+  if (code === "target_missing") {
+    return {
+      lines: [
+        "Bu sitede henüz bir CLI taslağı yok; indirilecek taslak bulunamadı. Hiçbir dosya yazılmadı.",
+        `  Önce taslağı oluştur:  ${pushCommand} --draft`,
+        "  (Canlı temayı indirmek istiyorsan --draft olmadan çalıştır.)",
+      ],
+      short: "Bu sitede henüz bir CLI taslağı yok.",
+      message: `No CLI draft on this site yet (a read never creates one). Nothing was written. Create it first: ${pushCommand} --draft`,
+      details: {},
+    };
+  }
+  if (code === "quota_exceeded") {
+    const d = error?.body?.details && typeof error.body.details === "object" ? error.body.details : null;
+    if (d?.resource === "theme_bytes") {
+      // The site's theme space (a technical allowance, not the plan): any theme write can meet it — a push to an
+      // existing draft included — so no "new draft" wording and no plan upgrade; space is freed by removing drafts.
+      const head = "Sitenin tema alanı dolu; bu değişiklik için yer kalmadı.";
+      const meter = isAmount(d.usedBytes) && isAmount(d.allowanceBytes)
+        ? `Kullanılan tema alanı: ${bytesLabel(d.usedBytes)} / ${bytesLabel(d.allowanceBytes)}${isAmount(d.estimateBytes) ? `; bu değişiklik yaklaşık ${bytesLabel(d.estimateBytes)} gerektiriyor` : ""}.`
+        : null;
+      return {
+        lines: [
+          `${head} ${done}`,
+          ...(meter ? [`  ${meter}`] : []),
+          "  Yer açmak için kullanmadığın taslak temaları (iptal edilmiş çalışmaların temaları dahil) tema kütüphanesinden sil (admin paneli → Tasarım); açık bir çalışmayı iptal etmek ayrıca onun için ayrılan yayın alanını bırakır.",
+          "  Sorun sürerse destek ekibine yaz.",
+          ...check,
+        ],
+        short: `${head}${meter ? ` ${meter}` : ""} Hiçbir şey yazılmadı; yer açmak için kullanılmayan bir taslağı sil.`,
+        message: `The site's theme space is full; this change does not fit (quota_exceeded, theme_bytes). ${doneEn} Free space by deleting unused draft themes from the theme library (cancelled works' themes included); cancelling an open work also releases its reserved publish space. Or contact support.${checkEn}`,
+        details: { ...d, ...extra },
+      };
+    }
+    const meter = quotaMeter(d);
+    if (d?.resource === "theme_drafts") {
+      // The legacy draft count of a site not (yet) on theme space: not tied to the plan, so no upgrade advice.
+      const head = "Sitenin taslak tema sınırına ulaşıldı; yeni taslak oluşturulamadı.";
+      return {
+        lines: [`${head} ${done}`, ...(meter ? [`  ${meter}`] : []), "  Artık kullanmadığın bir taslak temayı sil (admin paneli → Tasarım).", ...check],
+        short: `${head}${meter ? ` ${meter}` : ""} Hiçbir şey yazılmadı; kullanmadığın bir taslağı sil.`,
+        message: `The site's draft limit refused the new draft this push needs (quota_exceeded, theme_drafts). ${doneEn} Remove a draft you no longer need.${checkEn}`,
+        details: { ...d, ...extra },
+      };
+    }
+    const head = `${d?.resource === "storage_mb" || isAmount(d?.usedBytes) ? "Depolama alanın dolu" : "Planının sınırına ulaşıldı"}; yeni taslak oluşturulamadı.`;
+    return {
+      lines: [`${head} ${done}`, ...(meter ? [`  ${meter}`] : []), "  Yeni taslak için planını yükseltebilirsin: admin paneli → Ayarlar → Plan & faturalandırma.", ...check],
+      short: `${head}${meter ? ` ${meter}` : ""} Hiçbir şey yazılmadı.`,
+      message: `The plan's capacity refused the new draft this push needs (quota_exceeded). ${doneEn}${checkEn}`,
+      details: { ...(d ?? {}), ...extra },
+    };
+  }
+  if (code === "source_stale") {
+    const head = "Canlı tema bu sırada değişti; yeni taslak onun güncel hâlinden oluşturulamadı.";
+    return {
+      lines: [`${head} ${done}`, `  Komutu yeniden çalıştır; taslak canlının güncel hâlinden oluşturulur:  ${pushCommand}`, ...check],
+      short: `${head} Hiçbir şey yazılmadı; bir sonraki kayıt yeniden dener.`,
+      message: `The live theme a new draft copies changed while it was prepared (source_stale). ${doneEn} Run the command again.${checkEn}`,
+      details: extra,
+    };
+  }
+  // capacity_unavailable / resource_busy: transient, already resent within the CLI's retry policy.
+  // Neither is about the plan or a full space, and either can answer a push to an existing draft: no "new draft" wording.
+  const head =
+    code === "resource_busy"
+      ? "Site şu anda meşgul (başka bir yazım sürüyor); işlem şimdilik yapılamadı."
+      : "Platform tema alanını şu an doğrulayamadı; bu geçici bir durum, işlem şimdilik yapılamadı.";
+  const raw = String(error?.retryAfter ?? "").trim();
+  const seconds = /^\d+$/.test(raw) ? Number(raw) : null;
+  return {
+    lines: [`${head} ${done}`, `  Biraz sonra tekrar dene${seconds ? ` (en az ${seconds} sn sonra)` : ""}:  ${pushCommand}`, ...check],
+    short: `${head} Hiçbir şey yazılmadı. Biraz sonra tekrar dene; bir sonraki kayıt yeniden dener.`,
+    message: `${code === "resource_busy" ? "The site is busy with another write" : "The platform could not check the theme space right now (temporary)"}; the change was not applied (${code}). ${doneEn} Try again later.${checkEn}`,
+    details: { ...(seconds != null ? { retryAfterSeconds: seconds } : {}), ...extra },
+  };
+}
+
+/** A local #989 refusal with the server's shape (used where the CLI selects the draft itself, e.g. `push --diff`). */
+function draftTargetAmbiguous(reason, candidates) {
+  for (const c of candidates) c.restore = SITE_STATE_DRAFT_NAME.test(c.name ?? "");
+  return Object.assign(new Error(DRAFT_TARGET_AMBIGUOUS), { code: DRAFT_TARGET_AMBIGUOUS, status: 409, reason, candidates });
+}
+
+/**
+ * The human message for a #989 refusal: why, which drafts, and how to go on. `command` is the command line to repeat
+ * with `--instance <handle>` (e.g. "blocofy theme push ./shop"); `action` is what that command would do to the draft
+ * ("write" or "publish").
+ *
+ * #989 review P1 — `--instance` is pre-filled ONLY with a candidate that is CLI-named and not a site-state restore
+ * draft (the server's `suggestedInstance` when it sends one). Otherwise the command keeps the `<handle>` placeholder,
+ * the message warns that naming a listed draft would OVERWRITE (or publish) it, and names the safe ways forward.
+ *
+ * `earlierAttempt` (review P3, a keyed apply resent after an attempt without a certain answer): this refusal wrote
+ * nothing, but the earlier attempt may have — the message says so instead of "Nothing was written".
+ */
+export function draftTargetAmbiguousMessage(error, { command = "blocofy theme push", action = "write", earlierAttempt = null } = {}) {
+  const candidates = Array.isArray(error?.candidates) ? error.candidates : [];
+  const why =
+    error?.reason === "multiple_candidates"
+      ? "this site has more than one draft theme that could be the CLI draft"
+      : error?.reason === "site_state_restore"
+        ? "a candidate draft belongs to a site-state restore"
+        : error?.reason === "unrecognized_name"
+          ? 'the only draft it could pick is not named "CLI Draft — …" (it may not be the CLI\'s draft; a draft renamed by hand is refused too)'
+          : "it cannot tell which draft is the CLI draft";
+  const safe =
+    error?.suggestedInstance !== undefined
+      ? candidates.find((c) => c.instance === error.suggestedInstance) ?? null
+      : candidates.find((c) => !isRestore(c) && CLI_DRAFT_NAME.test(c.name ?? "")) ?? null;
+  const unsafe = candidates.filter((c) => c !== safe);
+  const done =
+    earlierAttempt === "committed"
+      ? "This attempt wrote nothing, but an earlier attempt of this push was committed (its answer said so)."
+      : earlierAttempt === "unknown"
+        ? "This attempt wrote nothing, but an earlier attempt of this push got no answer, so whether it wrote is unknown."
+        : action === "publish"
+          ? "Nothing was published."
+          : "Nothing was written.";
+  const lines = [`✗ Refused to pick a draft automatically: ${why}. ${done}`];
+  if (earlierAttempt) lines.push("  Check what the site holds now with `blocofy status` (and `blocofy theme push --diff --instance <handle>`) before running the push again.");
+  if (candidates.length) {
+    lines.push("  Candidate drafts:");
+    for (const c of candidates) lines.push(`    ${c.instance}${c.name ? `  "${c.name}"` : ""}${isRestore(c) ? "  (site-state restore draft)" : ""}`);
+  }
+  const verb = action === "publish" ? "PUBLISH it live" : "OVERWRITE it";
+  if (unsafe.length) {
+    lines.push(`  Warning: naming ${unsafe.map((c) => c.instance).join(", ")} with --instance would ${verb}${unsafe.some(isRestore) ? " (including the restore's work)" : ""}.`);
+  }
+  if (safe) {
+    lines.push(`  To use the CLI draft:  ${command} --instance ${safe.instance}`);
+  } else if (action === "publish") {
+    lines.push(`  Publish the draft you mean explicitly:  ${command} --instance <handle>`);
+  } else {
+    lines.push(`  Choose the draft explicitly:  ${command} --instance <handle>`);
+    lines.push("  Safe ways forward: create a new draft theme in the admin panel and pass its handle with --instance,");
+    lines.push("  or publish or delete the site-state restore draft first.");
+  }
+  lines.push("  (`blocofy status` lists the site's drafts.)");
+  return lines.join("\n");
+}
+
 /**
  * Sunucu kanonik protokolü konuşuyor mu? (0.5.0 `--dry-run` ön kontrolü.) SORGUSUZ canlı GET — mutasyonsuz
  * (`?draft=1` GET'i sunucuda taslak provizyonlar, o yüzden burada KULLANILMAZ). Eski bir sunucu `protocol`
@@ -289,7 +595,8 @@ 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 target = instance ? { files, instance } : name ? { files, draft, name } : { files, draft };
+  // #989 review: a draft push naming an instance sends both — the server then refuses the live instance (422).
+  const target = instance ? { files, instance, ...(draft ? { draft: true } : {}) } : name ? { files, draft, name } : { files, draft };
   const post = (body, key, retry = {}) =>
     fetchWithRetry(
       `${base}/api/dev/theme`,
@@ -368,6 +675,8 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   // 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;
+  // ADR-0013: a 503 capacity_unavailable / resource_busy is a definite "nothing was written" answer, not an unknown one.
+  let definiteNothing = false;
   const applyError = (err) => {
     Object.assign(err, { phase: "apply" });
     // target_changed names the current target; the one this push planned against is known only here.
@@ -379,11 +688,14 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   try {
     res = await post({ ...target, ...bindings }, idempotencyKey, {
       onRetry: (info) => {
-        earlierAttempt ??= "unknown";
+        if (!definiteNothing) earlierAttempt ??= "unknown";
+        definiteNothing = false;
         onRetry?.(info);
       },
       isFinal: async (attempt) => {
-        if ((await attempt.json().catch(() => null))?.committed === true) earlierAttempt = "committed";
+        const answer = await attempt.json().catch(() => null);
+        if (answer?.committed === true) earlierAttempt = "committed";
+        definiteNothing = CAPACITY_RETRYABLE.has(answer?.error);
         return false;
       },
     });
@@ -398,16 +710,29 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   // A server whose plan carries no `newDraft` created one exactly when a draft push found no CLI draft to reuse.
   const newDraft = typeof plan.newDraft === "boolean" ? plan.newDraft : Boolean(draft && !instance && cliDraft == null);
   const targetInstance = applied.targetInstance ?? plan.targetInstance ?? (newDraft ? null : probeInstance) ?? null;
-  const targetName = newDraft ? name : cliDraft && cliDraft.id === targetInstance ? cliDraft.name ?? null : null;
+  // #989 review: a draft this push created is named "CLI Draft — <name>" by the platform (date when no --name).
+  const targetName = newDraft ? cliDraftName(name) : cliDraft && cliDraft.id === targetInstance ? cliDraft.name ?? null : null;
   return { ...applied, ...extras, targetInstance, newDraft, targetName };
 }
 
 /**
- * The CLI draft a draft push writes into: the first `source: "import"` draft — `/api/dev/site` lists drafts by id,
- * the server's `ensureDraftInstance` reuses the first non-live import instance by id. `null` = a push would create one.
+ * The CLI draft a draft push writes into, or `null` when a push would create one. #989: mirrors the server's rule —
+ * exactly one `source: "import"` draft, carrying the platform-generated "CLI Draft" name and not a site-state restore
+ * draft — and otherwise throws the server's 409 `draft_target_ambiguous` shape, so `push --diff` and the push's merge
+ * probe never read a draft the push itself would refuse. The server stays authoritative (it also refuses a CLI-named
+ * draft a site-state theme deploy wrote to, which this list cannot show).
  */
 export function findCliDraft(status) {
-  return (status?.drafts ?? []).find((d) => d.source === "import") ?? null;
+  const candidates = (status?.drafts ?? []).filter((d) => d.source === "import");
+  if (candidates.length === 0) return null;
+  const listed = candidates.map((d) => ({ instance: d.id, name: d.name ?? null }));
+  if (candidates.length > 1) {
+    throw draftTargetAmbiguous(candidates.some((d) => SITE_STATE_DRAFT_NAME.test(d.name ?? "")) ? "site_state_restore" : "multiple_candidates", listed);
+  }
+  const [only] = candidates;
+  if (SITE_STATE_DRAFT_NAME.test(only.name ?? "")) throw draftTargetAmbiguous("site_state_restore", listed);
+  if (!CLI_DRAFT_NAME.test(only.name ?? "")) throw draftTargetAmbiguous("unrecognized_name", listed);
+  return only;
 }
 
 /**
@@ -440,12 +765,14 @@ export async function diffTheme({ dir, url, token, instance = null, onRetry = nu
  * 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, onRetry = null }) {
+export async function publishInstance({ url, token, instanceId, explicit = false, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const res = await fetchWithRetry(`${base}/api/dev/publish`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-    body: JSON.stringify({ instanceId }),
+    // K1 (#989): `explicit: true` ONLY when the user named the theme (`--instance`). Without it the platform publishes
+    // nothing but the site's provable CLI draft (409 publish_target_unconfirmed otherwise).
+    body: JSON.stringify(explicit ? { instanceId, explicit: true } : { instanceId }),
   }, { onRetry });
   if (!res.ok) throw await responseError(res);
   return res.json();