@blocofy/cli 0.13.0 → 0.14.0

package/README.md

@@ -61,7 +61,7 @@ Show which site a command in `[dir]` would hit (verified), without writing anyth
 ### Theme
 
 ```
-blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
+blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>] [--instance <handle>]
 ```
 Start a local dev server that renders your local theme files with the site's live content.
 Press `l` to open it, `q` to quit. Edit a file and save → the view reloads. Saves sync to a
@@ -73,6 +73,8 @@ changing credentials, context or the project binding).
 - `--port <n>` — local port (default 3030).
 - `--no-sync` — local preview only (skip draft sync).
 - `--name <name>` — name the draft when it is first created (ignored if it already exists).
+- `--instance <handle>` — sync into this draft. Needed when the platform cannot tell which draft is the
+  CLI draft (see "Which draft a draft command writes to" below); the live theme's handle is refused.
 
 ```
 blocofy theme pull [dir] [--draft] [--instance <handle>]
@@ -94,11 +96,19 @@ the admin panel, never touching the live site. Publish it with `blocofy theme pu
   non-interactive shells must add `--yes`.
 - `--draft` — explicit draft (same as the default; safe).
 - `--yes` — confirm a `--live` push without prompting (CI/agents).
-- `--instance <handle>` — push to a specific theme by its handle (safe targeted write — no
-  live-confirmation prompt).
-- `--name <name>` — name the new draft (draft mode only; ignored on `--live`/`--instance`). A draft
-  push reuses the existing CLI draft whatever its name; then the push says `--name` was not applied
-  and prints the `blocofy theme rename` command for it.
+- `--instance <handle>` — push to a specific theme by its handle. The live theme's handle asks for
+  the same confirmation as `--live` (non-interactive shells add `--yes`); so does any handle the CLI
+  cannot tell apart from the live theme (the live theme is unknown, or a raw numeric id was given).
+  With `--draft --instance <handle>` the push is a draft write to that draft: it never writes the
+  live theme (refused locally and by the platform, `draft_target_is_live`).
+  On a site with **no live theme** (or when the live theme cannot be read) the CLI cannot tell any
+  handle apart from the live one, so it stays on the safe side by design: every `--instance` push
+  asks for confirmation (`--yes` in non-interactive shells), and `--draft --instance` and
+  `theme dev --instance` refuse.
+- `--name <name>` — name the new draft: it is created as `CLI Draft — <name>` (draft mode only;
+  ignored on `--live`/`--instance`). When the push reuses the existing CLI draft instead, it says
+  `--name` was not applied. Do not rename the CLI draft by hand to a name that does not start with
+  `CLI Draft — `: the next draft push would refuse it and ask for `--instance`.
 - `--dry-run` / `--validate` — check the push on the server without writing; the two flags are
   aliases. The dry run covers exactly the files the push would send (remote-only files it keeps
   included; with `--prune`, without the ones it would remove). A current platform plans the whole
@@ -108,6 +118,18 @@ the admin panel, never touching the live site. Publish it with `blocofy theme pu
   compares with the CLI draft it writes to (named by handle); with no CLI draft yet, with the live
   theme (the push would create the draft). `--live` compares with live, `--instance` with that theme.
 
+**Which draft a draft command writes to.** A draft push, `theme pull --draft` and the `theme dev`
+sync write to (or read) the CLI draft only when the platform can tell which draft that is: exactly
+one draft created by a CLI push, still carrying a name the platform gives it (`CLI Draft`,
+`CLI Draft — YYYY-MM-DD` or `CLI Draft — <name>`), and not a draft a site-state restore built.
+Otherwise — two such drafts, a site-state restore draft, or a CLI draft renamed by hand — the command
+writes nothing, lists the candidate drafts and exits 2 (`draft_target_ambiguous`). The message
+pre-fills `--instance <handle>` only for a CLI-named draft that is not a restore draft; naming any
+other listed draft would overwrite it. On a site whose only candidate is a site-state restore draft,
+create a new draft theme in the admin panel and pass its handle with `--instance`, or publish or
+delete the restore draft first. `theme publish` without `--instance` uses the same rule and never
+publishes a guessed draft. With no draft at all, the first push creates one as before.
+
 After a draft push the CLI prints the draft it wrote to (`Draft: <handle> "<name>" (new)` or
 `(existing CLI draft, updated)`) and the `blocofy theme publish --instance <handle>` command.
 - `--idempotency-key <k>` — attach a key so a retried push is not double-applied.
@@ -158,7 +180,9 @@ flag, publishes the draft that `theme dev` / `theme push --draft` writes into. T
 refuses to publish a theme that has no pages (it would 404); preview first. The site is the one
 `[dir]`'s project is bound to (`dir` defaults to cwd), so `blocofy theme push ./shop && blocofy
 theme publish ./shop` always publishes `./shop`'s site, whatever directory you run it from.
-- `--instance <handle>` — publish a specific theme.
+- `--instance <handle>` — publish a specific theme. Without it the platform publishes only the
+  site's CLI draft; any other theme (a site-state restore draft, a renamed or panel-copied theme) is
+  refused with `publish_target_unconfirmed` (exit 2, nothing published) — name it with `--instance`.
 
 ### Status
 
@@ -461,6 +485,30 @@ Each retry prints a notice on stderr.
 
 ## Changelog
 
+- **0.14.0** — Draft commands no longer guess their draft (platform #989).
+  - **Behaviour change:** `theme push` (draft), `theme push --diff`, `theme pull --draft` and the
+    `theme dev` sync refuse, writing nothing, when the platform answers `draft_target_ambiguous` (or the
+    site status shows the same case): the message lists the candidate drafts and the exact
+    `--instance <handle>` command; exit code 2; never retried. A CLI draft you renamed is refused too.
+  - The refusal pre-fills `--instance` only for a safe candidate (CLI-named, not a restore draft) and
+    otherwise warns that naming a listed draft would overwrite it.
+  - `theme dev --instance <handle>` and `theme push --draft --instance <handle>` write to a chosen draft
+    (sent with `draft: true`; never the live theme).
+  - `theme dev` reports a draft-sync failure in one line, also at startup (it was silent there):
+    `draft_target_unverifiable` (the next save tries again) and `draft_target_is_live` (stops).
+  - **Behaviour change:** `theme publish` without `--instance` uses the same rule; it never publishes
+    a guessed draft.
+  - **Behaviour change:** `--name X` creates the draft as `CLI Draft — X`; the rename advice after a
+    reused draft is gone (a draft renamed by hand to another name is refused).
+  - **Behaviour change (CI):** `theme push --instance <the live theme's handle>` asks for the same
+    confirmation as `--live` (`--yes` in non-interactive shells); so does a handle the CLI cannot tell
+    apart from the live theme (live theme unknown, or a raw numeric id).
+  - `theme publish --instance <handle>` tells the platform the theme was named explicitly
+    (`explicit: true`); the automatic pick sends no flag and the platform re-checks it. A theme that is
+    not the site's CLI draft (a site-state restore draft, a renamed or panel-copied theme) is published
+    through the CLI only with `--instance`; otherwise the platform refuses with
+    `publish_target_unconfirmed` (exit 2, nothing published). Older CLIs get that refusal as a generic
+    error and can never publish such a theme.
 - **0.13.0** — Draft push names its target (customer items PS-22/PS-23/PS-26).
   - `theme push` (draft) prints the draft it wrote to — handle, name, new or existing — and
     `blocofy theme publish --instance <handle>`. When it updated the existing CLI draft, it says

package/bin/blocofy.mjs

@@ -71,7 +71,7 @@ import { MANIFEST_PATH, buildManifest, validateSiteStateTree, verifyManifest } f
 import { SiteStateFsError, hashBuffer, readSiteStateTree, stagedWriteTree } from "../lib/site-state-fs.mjs";
 import { migrateSiteState } from "../lib/site-migrate.mjs";
 import { applySiteState, downloadAssetBytes, fetchSiteStateExport, planSiteState, publishSiteState, uploadMediaAsset } from "../lib/site-state-client.mjs";
-import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, findCliDraft, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
+import { DRAFT_TARGET_AMBIGUOUS, PUBLISH_TARGET_UNCONFIRMED, publishTargetUnconfirmedMessage, diffTheme, draftSyncErrorLine, draftTargetAmbiguousMessage, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, findCliDraft, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
 import { isAffirmative, livePushDecision, resolvePushMode } from "../lib/confirm.mjs";
 import { hyperlink, openUrl } from "../lib/term.mjs";
 import { isValidToken, isValidUrl, normalizeUrl } from "../lib/validate.mjs";
@@ -90,7 +90,7 @@ const KNOWN = {
   pages: ["decisions", "expected-revision-id", "expected-version", "json", "dir"],
   themePull: ["draft", "instance"],
   themePush: ["diff", "draft", "instance", "name", "live", "yes", "confirm", "dry-run", "validate", "idempotency-key", "prune"],
-  themeDev: ["port", "dry", "no-sync", "name"],
+  themeDev: ["port", "dry", "no-sync", "name", "instance"],
   themePublish: ["instance"],
   themeRename: ["name", "dir"],
   content: [],
@@ -177,7 +177,7 @@ Usage
   blocofy target [dir] [--context <name>] [--json]
       Show which site a command in [dir] would hit (verified), without writing anything.
 
-  blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
+  blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>] [--instance <handle>]
       Start a local dev server that renders your local theme files with the site's
       live content. Press l to open it, q to quit. Edit a file and save → the view
       reloads. Saves sync to a DRAFT theme only (never the live site). (dir defaults to cwd)
@@ -188,6 +188,8 @@ Usage
         --port <n>   local port (default 3030)
         --no-sync    local preview only (skip draft sync)
         --name <name>  name the draft when it is first created (ignored if it already exists)
+        --instance <handle>  sync into this draft (when the platform cannot tell which draft is
+                             the CLI draft it refuses and asks for this; never the live theme)
 
   blocofy theme pull [dir] [--draft] [--instance <handle>]
       Download the live theme to disk. (dir defaults to cwd)
@@ -204,9 +206,11 @@ Usage
                      confirmation first; non-interactive shells must add --yes.
         --draft      explicit draft (same as the default; safe)
         --yes        confirm a --live push without prompting (for CI / agents)
-        --instance <handle>  push to a specific theme by its handle (safe targeted
-                             write — no live-confirmation prompt)
-        --name <name>  name the NEW draft (draft mode only; ignored on --live/--instance)
+        --instance <handle>  push to a specific theme by its handle. If the platform cannot
+                             tell which draft is the CLI draft, a draft push refuses and asks
+                             for this. The LIVE theme's handle asks for confirmation like --live
+        --name <name>  name the NEW draft "CLI Draft — <name>" (draft mode only; ignored on
+                       --live/--instance). With --draft --instance, writes that draft (never live)
         --dry-run    validate on the server WITHOUT writing (auth + snapshot + Liquid check)
         --validate   alias for --dry-run (validate only, nothing written)
         --diff       show what a push WOULD change vs the target (read-only), then stop
@@ -226,7 +230,9 @@ Usage
       'theme push ./shop && theme publish ./shop' always publishes ./shop's site.
       With no flag, publishes the draft that 'theme dev' / 'theme push --draft' writes into.
       The server refuses to publish a theme that has no pages (it would 404); preview first.
-        --instance <handle>  publish a specific theme (handle from the panel / status)
+        --instance <handle>  publish a specific theme (handle from the panel / status). Without it
+                             the platform publishes only the site's CLI draft; any other theme
+                             is refused (publish_target_unconfirmed) — name it with --instance
 
   blocofy status [dir]
       Show the live theme, page distribution per instance, drafts, and a health flag
@@ -503,6 +509,36 @@ function failAndExit(error) {
   process.exit(code);
 }
 
+/**
+ * #989 — the platform (or `findCliDraft`, which mirrors it) refused to pick the draft automatically. Says why, lists the
+ * candidate drafts and the exact command to repeat with `--instance`; exits 2 (409). Never retried.
+ */
+function failDraftTargetAmbiguous(error, command, { action = "write" } = {}) {
+  // Review P3: a refusal of a RESENT apply says nothing about the earlier attempt — never "Nothing was written" then.
+  const earlierAttempt = error?.phase === "apply" && (error.earlierAttempt === "unknown" || error.earlierAttempt === "committed") ? error.earlierAttempt : null;
+  failAndExit({
+    code: DRAFT_TARGET_AMBIGUOUS,
+    status: 409,
+    message: draftTargetAmbiguousMessage(error, { command, action, earlierAttempt }),
+    details: {
+      reason: error.reason ?? null,
+      candidates: error.candidates ?? [],
+      suggestedInstance: error.suggestedInstance ?? null,
+      ...(earlierAttempt ? { earlierAttempt } : {}),
+    },
+  });
+}
+
+/**
+ * Could `instance` be the live theme? Fail-closed (#989 review): yes when it is the live handle, when the live theme is
+ * not known, and when it is a raw numeric id (the server accepts one, the live handle comparison cannot see it).
+ */
+const instanceMaybeLive = (instance, liveThemeId) =>
+  liveThemeId == null || String(instance) === String(liveThemeId) || /^\d+$/.test(String(instance));
+
+/** The command line to repeat with `--instance` (the directory argument kept, as the user typed it). */
+const commandLine = (base, positionals) => [base, ...positionals.slice(0, 1)].join(" ");
+
 function contextNameOrExit(name) {
   if (name === ENV_CONTEXT || !CONTEXT_NAME_RE.test(name)) {
     throw new TargetError("TARGET_CONTEXT_INVALID", `"${name}" cannot be used as a context name (letters, digits, . _ -; "env" is reserved).`, { context: name }, 1);
@@ -927,7 +963,16 @@ async function themePull(rest) {
   const what = instance ? `instance ${instance}` : draft ? "draft" : "live";
   // Review M1: a draft pull provisions the draft server-side (`?draft=1`), so it is a remote mutation: binding required.
   const target = await prepareTarget({ command: draft ? "theme pull --draft" : "theme pull", commandClass: draft ? "remote-mutation" : "local-write", dir, flags, needs: "dev", mode: what });
-  const { count } = await withNewBindingClaim(target, dir, () => pullTheme({ dir, url: target.dev.url, token: target.dev.token, draft, instance, onRetry }));
+  let count;
+  try {
+    ({ count } = await withNewBindingClaim(target, dir, () => pullTheme({ dir, url: target.dev.url, token: target.dev.token, draft, instance, onRetry })));
+  } catch (error) {
+    if (error?.code === DRAFT_TARGET_AMBIGUOUS) failDraftTargetAmbiguous(error, commandLine("blocofy theme pull", positionals));
+    if (error?.code === "draft_target_unverifiable") {
+      failAndExit({ code: "draft_target_unverifiable", status: 503, message: "The platform could not verify which draft to pull (a read failed on its side). Nothing was written. Try again in a moment.", details: {} });
+    }
+    throw error;
+  }
   console.log(`Downloaded ${count} ${what} theme files → ${dir}`);
   bindAfterPull(target, dir);
 }
@@ -969,7 +1014,14 @@ async function themePush(rest) {
   // server-side (a read-only command must not mutate). With no CLI draft yet the push would create one: vs live.
   if (flags.diff) {
     const diffTarget = ` of ${siteLabel(target.identity.site)}`;
-    const cliDraft = mode === "draft" ? findCliDraft(await fetchSiteStatus({ url: creds.url, token: creds.token, onRetry })) : null;
+    let cliDraft = null;
+    try {
+      cliDraft = mode === "draft" ? findCliDraft(await fetchSiteStatus({ url: creds.url, token: creds.token, onRetry })) : null;
+    } catch (error) {
+      // #989: the diff compares with the draft the push would write to — and refuses exactly when the push would.
+      if (error?.code === DRAFT_TARGET_AMBIGUOUS) failDraftTargetAmbiguous(error, `${commandLine("blocofy theme push", positionals)} --diff`);
+      throw error;
+    }
     const diffInstance = instanceFlag ?? cliDraft?.id ?? null;
     const d = await diffTheme({ dir, url: creds.url, token: creds.token, instance: diffInstance, onRetry });
     if (instanceFlag) console.log(`Diff vs theme ${instanceFlag}${diffTarget}:`);
@@ -992,7 +1044,7 @@ async function themePush(rest) {
   const whoami = target.identity;
   const siteName = siteLabel(whoami.site) || String(whoami.site.id);
   if (mode === "instance") {
-    console.log(`→ Pushing to theme ${instance} of ${siteName}`);
+    console.log(`→ Pushing to theme ${instance} of ${siteName}${whoami.liveThemeId != null && String(instance) === String(whoami.liveThemeId) ? " (the LIVE theme)" : ""}`);
   } else if (mode === "live") {
     console.log(dryRun ? `→ Validating against the LIVE theme of ${siteName} (dry run — nothing will be written)` : `→ Pushing to the LIVE theme of ${siteName}`);
   } else {
@@ -1003,13 +1055,34 @@ async function themePush(rest) {
   // kazara canlıya basmasın diye açık onay şart (#431 L2). Draft/instance modu
   // güvenli → otomatik onay (prompt yok).
   // 0.5.0: `--dry-run` hiçbir şey yazmaz → canlı onayı gereksiz (draft:true gibi davranır).
+  // #989 review: `--instance <the live theme's handle>` writes the LIVE theme exactly like `--live`, so it needs the
+  // same confirmation (an explicit --instance is the documented way past a refused draft pick — it must not become a
+  // way to write live without asking).
+  const instanceIsLive = mode === "instance" && instanceMaybeLive(instance, whoami.liveThemeId);
+  // `--draft --instance <h>`: a draft write to a chosen draft. It never reaches the live theme — refused here when the
+  // handle may be live (fail-closed), and by the server (422 draft_target_is_live) in any case.
+  const draftInstance = mode === "instance" && Boolean(flags.draft);
+  if (draftInstance && instanceIsLive && !dryRun) {
+    console.error(`✗ --draft --instance ${instance}: ${whoami.liveThemeId != null && String(instance) === String(whoami.liveThemeId) ? "that is the LIVE theme" : "this may be the LIVE theme (it could not be told apart from it)"}; a draft push never writes live. Nothing was written.`);
+    console.error("  Pass a draft's handle (`blocofy status`), or drop --draft and confirm a live push.");
+    process.exit(2);
+  }
   const decision = livePushDecision({
-    draft: mode !== "live" || dryRun,
+    draft: (mode !== "live" && (!instanceIsLive || draftInstance)) || dryRun,
     yes: Boolean(flags.yes),
     confirm: Boolean(flags.confirm),
     isTTY: Boolean(process.stdin.isTTY),
   });
   if (decision.mustAbort) {
+    if (instanceIsLive) {
+      console.error(
+        whoami.liveThemeId != null && String(instance) === String(whoami.liveThemeId)
+          ? `⚠ Theme ${instance} is the LIVE theme of ${siteName}: this push writes to it immediately (no preview).`
+          : `⚠ Theme ${instance} may be the LIVE theme of ${siteName} (it could not be told apart from it): a push to it may write live immediately.`,
+      );
+      console.error(`  Non-interactive shell: pass --yes to confirm, or push to a draft instead. Nothing was written.`);
+      process.exit(1);
+    }
     console.error(`⚠ 'theme push --live' writes to the LIVE theme of ${siteName} immediately (no preview).`);
     console.error(`  Non-interactive shell: pass --live --yes to confirm, or omit --live to push to a safe draft.`);
     process.exit(1);
@@ -1033,7 +1106,7 @@ async function themePush(rest) {
   // `--yes`/`--confirm` → onaylı, TTY → liste basıldıktan sonra y/N, non-TTY → yazımsız çıkış.
   // TPUSH-5: `--dry-run --prune` plans the pruned payload (it writes nothing, so it asks nothing).
   const prune = Boolean(flags.prune);
-  const liveTarget = mode === "live" || (mode === "instance" && (whoami.liveThemeId == null || String(instance) === String(whoami.liveThemeId)));
+  const liveTarget = mode === "live" || instanceIsLive;
   const pruneDecision = livePushDecision({
     draft: !prune || dryRun || !liveTarget,
     yes: Boolean(flags.yes),
@@ -1080,7 +1153,7 @@ async function themePush(rest) {
       dir,
       url: creds.url,
       token: creds.token,
-      draft: mode === "draft",
+      draft: mode === "draft" || draftInstance,
       instance: mode === "instance" ? instance : null,
       name: mode === "draft" ? name : null,
       dryRun,
@@ -1098,6 +1171,10 @@ async function themePush(rest) {
       }
       failAndExit({ code: "cli_upgrade_required", status: error.status, message: "The server refused this CLI version; update it: npm i -g @blocofy/cli@latest", details: { missing } });
     }
+    if (error?.code === DRAFT_TARGET_AMBIGUOUS) failDraftTargetAmbiguous(error, commandLine("blocofy theme push", positionals));
+    if (error?.code === "draft_target_is_live") {
+      failAndExit({ code: "draft_target_is_live", status: 422, message: "A draft push cannot write the LIVE theme; nothing was written. Pass a draft's handle (`blocofy status`), or drop --draft and confirm a live push.", details: {} });
+    }
     if (error?.code === "idempotency_conflict") {
       if (!JSON_MODE) {
         console.error("✗ Idempotency çakışması: aynı anahtar daha önce FARKLI içerikle kullanılmış (409).");
@@ -1150,9 +1227,10 @@ async function themePush(rest) {
       const h = typeof result.targetInstance === "string" ? result.targetInstance : null;
       const label = result.targetName ? ` "${result.targetName}"` : "";
       if (h) console.log(result.newDraft ? `Draft: ${h}${label} (new)` : `Draft: ${h}${label} (existing CLI draft, updated)`);
-      // PS-22: the server reuses the CLI draft whatever its name; --name only names a draft this push creates.
+      // --name only names a draft this push creates. #989 review: no rename advice — a draft renamed by hand to a name
+      // that does not start with "CLI Draft — " is no longer picked automatically.
       if (name && result.newDraft !== true) {
-        console.log(`Note: --name was not applied — this push updated the existing CLI draft${h ? ` ${h}` : ""}. Rename it with:  blocofy theme rename ${h ?? "<handle>"} "${name}"`);
+        console.log(`Note: --name was not applied — it names only a draft this push creates; this push updated the existing CLI draft${h ? ` ${h}` : ""}.`);
       }
       console.log("Preview & publish it in the admin panel: Theme -> Theme library -> \"Open in editor\".");
       console.log(`Publish it live with:  blocofy theme publish${h ? ` --instance ${h}` : ""}`);
@@ -1235,6 +1313,12 @@ function themePushRefusal(error, { draft = false, idempotencyKey = null } = {})
     details: withEarlier({ phase: "apply", outcome: "unknown", idempotencyKey, ...(error?.status ? { status: error.status } : {}), ...(bound !== undefined ? { expectedTargetInstance: bound } : {}) }),
   });
   switch (error?.code) {
+    case "draft_target_unverifiable":
+      // #989 review P3: the platform could not read which draft to write to; it wrote nothing for this attempt.
+      return {
+        message: `The platform could not verify which draft this push would write to (a read failed on its side). ${nothing("Run the push again in a moment.")}`,
+        details: withEarlier({}),
+      };
     case "pointer_version_conflict":
       return {
         message: `The target theme was deployed again after this push checked it (now at pointer ${body.currentVersion == null ? "none" : `v${body.currentVersion}`}). ${nothing("Run the push again.")}`,
@@ -1989,6 +2073,13 @@ async function themeDev(rest) {
   const target = await prepareTarget({ command: "theme dev", commandClass: noSync ? "read" : "remote-mutation", dir: themeDir, flags, needs: "dev", mode: noSync ? "read · local preview" : "draft" });
   const creds = target.dev;
   const port = Number(flags.port) || 3030;
+  // #989: `--instance <handle>` names the draft to sync into, for a site where the platform refuses to pick one. Draft
+  // sync never writes the live theme, so the live theme's handle is refused here.
+  const devInstance = typeof flags.instance === "string" ? flags.instance : null;
+  if (devInstance && instanceMaybeLive(devInstance, target.identity?.liveThemeId ?? null)) {
+    console.error(`✗ ${devInstance} is (or could not be told apart from) the LIVE theme. 'theme dev' syncs to a draft only; pick a draft handle (\`blocofy status\`) or use --no-sync.`);
+    process.exit(2);
+  }
 
   // Dev session: live-domain preview + theme editor URLs (+ a draft to sync into).
   // Graceful: if the platform can't provide one, fall back to local-only preview.
@@ -2066,6 +2157,19 @@ async function themeDev(rest) {
     // session'dan hiçbir veri kullanmaz. Bu satır `Boolean(session)` iken, session 410 alınca senkron
     // da sessizce kapanıyordu — ölü bir uç, çalışan bir özelliği götürüyordu. Tek kapatma yolu --no-sync.
     syncDraft: !flags["no-sync"],
+    instance: devInstance,
+    // #989: the platform refused to pick the draft — say which drafts and how to choose, then stop (no retry loop).
+    onSyncRefused: (error) => {
+      try {
+        handle.close();
+      } catch {
+        /* yoksay */
+      }
+      if (error?.code === "draft_target_is_live") {
+        failAndExit({ code: "draft_target_is_live", status: 422, message: draftSyncErrorLine(error), details: {} });
+      }
+      failDraftTargetAmbiguous(error, commandLine("blocofy theme dev", positionals));
+    },
     onRetry: (info) => console.error(`  ${retryNotice(info)}`),
     onWarn: (msg) => console.warn(`  ⚠ ${msg}`),
     // Her kaydetmede ne olduğunu bas — "reloaded" = watch tetiklendi; "0 views"
@@ -2074,7 +2178,7 @@ async function themeDev(rest) {
     onReload: ({ file, synced, clients, error }) => {
       const what = file || "change";
       if (error) {
-        console.error(`  ↻ ${what} — draft sync failed: ${error} (local view still reloaded)`);
+        console.error(`  ↻ ${what} — ${error} (local view still reloaded)`);
         return;
       }
       const views = clients ? `${clients} view${clients === 1 ? "" : "s"}` : "no views connected";
@@ -2130,28 +2234,45 @@ async function themePublish(rest) {
   const creds = target.dev;
   let instance = typeof flags.instance === "string" ? flags.instance : null;
   if (!instance) {
-    // Belirtilmediyse: `theme dev` / `theme push --draft`'ın yazdığı taslağı yayınla. Kaynak
-    // `GET /api/dev/site` — eski `fetchDevSession` yolu sunucuda 410'a döndü ve bu komutu
-    // try/catch'siz, boş mesajlı bir Error ile tamamen çalışmaz hâle getirmişti.
-    //
-    // `drafts` canlı OLMAYAN HER instance'ı içerir; sunucunun `ensureDraftInstance`'ı ise
-    // `source === "import"` olanı seçer (yayınlanan taslak import'tan çıkarılır). Aynı seçimi
-    // burada tekrarla — yoksa bir kez yayın yapmış her sitede iki taslak görünür ve komut takılır.
+    // Belirtilmediyse: `theme dev` / `theme push --draft`'ın yazdığı taslağı yayınla. Kaynak `GET /api/dev/site`.
+    // #989 review P2: the SAME rule as a draft push (`findCliDraft`, mirroring the server) and the same refusal — a
+    // guessed draft (a site-state restore draft, a renamed one, one of several) is never published live.
     const status = await fetchSiteStatus({ url: creds.url, token: creds.token, onRetry });
     const drafts = status?.drafts ?? [];
-    const cliDrafts = drafts.filter((d) => d.source === "import");
-    if (cliDrafts.length === 1) {
-      instance = cliDrafts[0].id;
+    let cliDraft;
+    try {
+      cliDraft = findCliDraft(status);
+    } catch (error) {
+      if (error?.code === DRAFT_TARGET_AMBIGUOUS) failDraftTargetAmbiguous(error, commandLine("blocofy theme publish", positionals), { action: "publish" });
+      throw error;
+    }
+    if (cliDraft) {
+      instance = cliDraft.id;
     } else if (drafts.length === 0) {
       console.error("No draft theme to publish. Create one first:  blocofy theme push --draft");
       process.exit(1);
     } else {
-      console.error("Could not tell which draft to publish — pick one with --instance <handle>:");
+      // Drafts exist, but none is the CLI draft (panel copies, starter themes…): publishing one is a choice to make.
+      console.error("No CLI draft to publish. Publish one of the site's drafts explicitly with --instance <handle>:");
       for (const d of drafts) console.error(`  ${d.id}  ${d.name ?? "(unnamed)"}`);
       process.exit(1);
     }
   }
-  const result = await publishInstance({ url: creds.url, token: creds.token, instanceId: instance, onRetry });
+  let result;
+  try {
+    // K1 (#989): `explicit` only when the user named the theme; the automatic pick is re-checked by the platform.
+    result = await publishInstance({ url: creds.url, token: creds.token, instanceId: instance, explicit: typeof flags.instance === "string", onRetry });
+  } catch (error) {
+    if (error?.code === PUBLISH_TARGET_UNCONFIRMED) {
+      failAndExit({
+        code: PUBLISH_TARGET_UNCONFIRMED,
+        status: 409,
+        message: publishTargetUnconfirmedMessage(error, { command: commandLine("blocofy theme publish", positionals) }),
+        details: { reason: error.reason ?? null, instance: error.instance ?? null },
+      });
+    }
+    throw error;
+  }
   console.log(
     `✓ Theme ${result.published} is now LIVE${result.cloned ? " (pages cloned from the previous live theme)" : ""}.`,
   );

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,6 +50,20 @@ async function errorText(res) {
 
 /** `errorText` as an Error that keeps the HTTP status (exit codes: 4xx → 2, 5xx → 1). */
 async function responseError(res) {
+  if (res.status === 409) {
+    // #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 (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;
@@ -75,9 +89,153 @@ async function httpError(res) {
   err.status = res.status;
   err.code = typeof body?.error === "string" ? body.error : null;
   err.body = body;
+  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, 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`).";
+  }
+  return `draft sync failed: ${err?.message ?? String(err)}`;
+}
+
+/** 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 +447,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`,
@@ -398,16 +557,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 +612,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();

package/package.json

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