@blocofy/cli 0.4.0 → 0.5.0

package/README.md

@@ -33,6 +33,22 @@ blocofy --help
 
 ## Changelog
 
+- **0.5.0** — M4 canonical deploy protocol. `theme push` now deploys through the platform's atomic
+  source pipeline: the CLI declares the protocol handshake and auto-generates a per-push idempotency
+  key (transport retries converge; `--idempotency-key <k>` overrides it for scripting). A `--live`
+  push is finally visible on the pinned production render again. "Push does not delete" still holds —
+  remote-only files are carried along, and server-retained rows survive. New flags: `--dry-run` /
+  `--validate` (server-side validation, nothing written — refused against a server that predates the
+  protocol, which would otherwise silently write), `--diff` (read-only compare vs the LIVE theme).
+  `--help` on ANY subcommand now prints help and never runs the command (0.4.0 executed a real push);
+  unknown flags exit write-free instead of silently swallowing the next argument. `layer/` joined the
+  synced theme directories. Server errors `cli_upgrade_required` (426) and `idempotency_conflict`
+  (409) get human messages. Token format check aligned to the server minimum (total length ≥24 incl. the
+  `bcf_` prefix; real tokens are 47 chars). Two honest costs of the canonical pipeline: re-pushing
+  identical bytes still records a NEW deployment (the revision itself is deduplicated server-side; on
+  a repo-linked live target it also produces a reconcile bot commit), and the no-delete guarantee is
+  bought by carrying remote-only files in the payload — a very large theme (local+remote > 256 files
+  or > 4 MiB) can now hit the server's payload limits where 0.4.0's upsert did not.
 - **0.4.0** — `theme push` / `theme dev` accept `--name <name>` to name a new draft (applied
   only when the draft is first created; reuse ignores it). New `theme rename <handle> <new name>`
   renames a theme (the name is a label; works on any theme, including the live one).

package/bin/blocofy.mjs

@@ -8,6 +8,7 @@
  * `/api/dev/render` endpoint (local theme files + live data) with file-watch
  * livereload. No monorepo required.
  */
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
@@ -19,7 +20,7 @@ import { credentialsPath, loadCredentials, saveCredentials } from "../lib/creden
 import { startDevServer } from "../lib/dev-server.mjs";
 import { readLocalTemplates } from "../lib/local-theme.mjs";
 import { githubNote, retryNotice, statusLine, syncScopeNote } from "../lib/messages.mjs";
-import { fetchDevSession, fetchSiteStatus, fetchWhoami, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
+import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, fetchWhoami, 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";
@@ -27,6 +28,28 @@ import { isValidToken, isValidUrl, normalizeUrl } from "../lib/validate.mjs";
 const VERSION = createRequire(import.meta.url)("../package.json").version;
 const args = process.argv.slice(2);
 
+// 0.5.0 güvenlik sıkılaştırması: her komutun kabul ettiği bayraklar açık bir listedir. Bilinmeyen bir
+// bayrak YAZIMSIZ çıkışla reddedilir (eskiden sonraki token'ı değer olarak yutup hedef dizini sessizce
+// kaydırıyordu). `--confirm` ve `--dry` belgelenmemiş ama gerçek bayraklardır; `--dry` (theme dev'in
+// sunucu-başlatmama kancası) `--dry-run`'dan (sunucu-tarafı doğrulama) FARKLIDIR, alias değildir.
+const KNOWN = {
+  login: ["url", "token"],
+  themePull: ["draft", "instance"],
+  themePush: ["diff", "draft", "instance", "name", "live", "yes", "confirm", "dry-run", "validate", "idempotency-key"],
+  themeDev: ["port", "dry", "no-sync", "name"],
+  themePublish: ["instance"],
+  themeRename: ["name"],
+  content: [],
+};
+function parseArgsOrExit(rest, known) {
+  const parsed = parseArgs(rest, new Set([...known, "help", "version"]));
+  if (parsed.unknownFlag) {
+    console.error(`Unknown flag ${parsed.unknownFlag}. Nothing was written. See \`blocofy --help\`.`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
 /** Human label for a resolved site: "Name (slug)" or just the slug. */
 function siteLabel(site) {
   if (!site) return "";
@@ -69,6 +92,10 @@ Usage
         --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)
+        --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
+        --idempotency-key <k>  attach an idempotency key so a retried push is not double-applied
 
   blocofy theme rename <handle> <new name>
       Rename a theme (the name is just a label). Works on any of your themes,
@@ -118,7 +145,7 @@ async function promptValid(rl, question, normalize, valid, hint, tries = 3) {
 }
 
 async function login(rest) {
-  const { flags } = parseArgs(rest);
+  const { flags } = parseArgsOrExit(rest, KNOWN.login);
   let url = typeof flags.url === "string" ? normalizeUrl(flags.url) : "";
   let token = typeof flags.token === "string" ? flags.token.trim() : "";
 
@@ -186,7 +213,7 @@ function requireCreds() {
 }
 
 async function themePull(rest) {
-  const { flags, positionals } = parseArgs(rest);
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themePull);
   const dir = resolve(positionals[0] ?? process.cwd());
   const creds = requireCreds();
   const draft = Boolean(flags.draft);
@@ -197,7 +224,7 @@ async function themePull(rest) {
 }
 
 async function themePush(rest) {
-  const { flags, positionals } = parseArgs(rest);
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themePush);
   const dir = resolve(positionals[0] ?? process.cwd());
   if (!existsSync(dir)) {
     console.error(`Theme directory not found: ${dir}`);
@@ -206,6 +233,38 @@ async function themePush(rest) {
   const creds = requireCreds();
   const instanceFlag = typeof flags.instance === "string" ? flags.instance : null;
   const name = typeof flags.name === "string" ? flags.name : null;
+  const dryRun = Boolean(flags["dry-run"] || flags.validate);
+  // 0.5.0: her push'a otomatik idempotency key — kanonik dal (protokol + key) ancak böyle seçilir; key
+  // OLMADAN header'lar tek başına legacy writer'a düşer ve --live push pinned render'a YANSIMAZ (M4
+  // read cutover'ının ana CLI şikâyeti). Push-OPERASYONU-başına üretilir: fetchWithRetry'nin 5xx/429
+  // denemeleri aynı key'le yakınsar, ardışık push'lar farklı key alır (sabit key, settings/hedef
+  // değişiminde kalıcı 409 idempotency_conflict üretirdi). Ham id gönderilir — sunucu `idem:` ile
+  // ad-alanlar, önek EKLENMEZ.
+  const idempotencyKey = typeof flags["idempotency-key"] === "string" ? flags["idempotency-key"] : `cli-${randomUUID()}`;
+
+  // `--diff`: read-only preview vs the LIVE theme (or --instance). No write; the draft target is not
+  // diffable (a draft GET would PROVISION the draft server-side — a read-only command must not mutate).
+  if (flags.diff) {
+    let diffSite = null;
+    try {
+      diffSite = (await fetchWhoami({ url: creds.url, token: creds.token })).site;
+    } catch {
+      /* best-effort — etiket kozmetik, diff yine koşar */
+    }
+    const diffTarget = diffSite ? ` of ${siteLabel(diffSite)}` : "";
+    const d = await diffTheme({ dir, url: creds.url, token: creds.token, instance: instanceFlag });
+    console.log(instanceFlag ? `Diff vs theme ${instanceFlag}${diffTarget}:` : `Diff vs the LIVE theme${diffTarget} (push default writes to a DRAFT):`);
+    const total = d.added.length + d.changed.length + d.removed.length;
+    if (total === 0) {
+      console.log("No differences — local theme matches the target.");
+      return;
+    }
+    for (const k of d.added) console.log(`  + ${k}`);
+    for (const k of d.changed) console.log(`  ~ ${k}`);
+    for (const k of d.removed) console.log(`  - ${k} (present on target, absent locally — push does not delete)`);
+    console.log(`\n${d.added.length} added, ${d.changed.length} changed, ${d.removed.length} remote-only.`);
+    return;
+  }
 
   // Yeni varsayılan hedef: DRAFT (güvenli). `--live` eski anında-canlı davranışını
   // açıkça geri getirir; `--instance` belirli bir temayı adresler. Sadece "live"
@@ -229,7 +288,7 @@ async function themePush(rest) {
   if (mode === "instance") {
     console.log(`→ Pushing to theme ${instance}${site ? ` of ${target}` : ""}`);
   } else if (mode === "live") {
-    console.log(`→ Pushing to the LIVE theme of ${target}`);
+    console.log(dryRun ? `→ Validating against the LIVE theme of ${target} (dry run — nothing will be written)` : `→ Pushing to the LIVE theme of ${target}`);
   } else {
     console.log(`→ Pushing to a draft${site ? ` of ${target}` : ""}`);
   }
@@ -237,8 +296,9 @@ async function themePush(rest) {
   // Canlı push (`--live`) ANINDA canlı temayı değiştirir (önizleme yok). Agent/CI
   // 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).
   const decision = livePushDecision({
-    draft: mode !== "live",
+    draft: mode !== "live" || dryRun,
     yes: Boolean(flags.yes),
     confirm: Boolean(flags.confirm),
     isTTY: Boolean(process.stdin.isTTY),
@@ -268,15 +328,65 @@ async function themePush(rest) {
     console.error("Note: --name yalnız yeni taslak yaratırken (varsayılan push) geçerli, yok sayıldı.");
   }
 
-  const result = await pushTheme({
-    dir,
-    url: creds.url,
-    token: creds.token,
-    draft: mode === "draft",
-    instance: mode === "instance" ? instance : null,
-    name: mode === "draft" ? name : null,
-    onRetry: (info) => console.error(retryNotice(info)),
-  });
+  // 0.5.0: eski (protokolsüz) bir sunucu `dryRun` alanını bilmez ve SESSİZCE GERÇEK YAZIM yapardı —
+  // dry-run yalnız sunucu kanonik protokolü beyan ediyorsa koşar (sorgusuz, mutasyonsuz GET ön kontrolü).
+  if (dryRun) {
+    const { supported } = await fetchCanonicalSupport({ url: creds.url, token: creds.token });
+    if (!supported) {
+      console.error("✗ --dry-run needs a server that speaks the canonical protocol; this one does not.");
+      console.error("  An old server would IGNORE dryRun and write for real. Nothing was sent.");
+      process.exit(1);
+    }
+  }
+
+  let result;
+  try {
+    result = await pushTheme({
+      dir,
+      url: creds.url,
+      token: creds.token,
+      draft: mode === "draft",
+      instance: mode === "instance" ? instance : null,
+      name: mode === "draft" ? name : null,
+      dryRun,
+      idempotencyKey,
+      onRetry: (info) => console.error(retryNotice(info)),
+    });
+  } catch (error) {
+    if (error?.code === "cli_upgrade_required") {
+      const missing = Array.isArray(error?.body?.fence?.missing) ? error.body.fence.missing.join(", ") : "";
+      console.error("✗ Sunucu bu CLI sürümünü reddetti (cli_upgrade_required).");
+      console.error(`  Güncelle:  npm i -g @blocofy/cli@latest${missing ? `\n  Sunucunun istediği eksik yetenekler: ${missing}` : ""}`);
+      process.exit(1);
+    }
+    if (error?.code === "idempotency_conflict") {
+      console.error("✗ Idempotency çakışması: aynı anahtar daha önce FARKLI içerikle kullanılmış (409).");
+      console.error("  `--idempotency-key` verdiysen yeni bir anahtarla dene; vermediysen tekrar `blocofy theme push` yeterli (her koşu taze anahtar üretir).");
+      process.exit(1);
+    }
+    throw error;
+  }
+
+  // --dry-run / --validate: the server validated without writing. Report and stop.
+  if (result.dryRun) {
+    const warnings = Array.isArray(result.warnings) ? result.warnings : [];
+    console.log(`✓ Validation passed (dry run — nothing written).${warnings.length ? ` ${warnings.length} warning(s).` : ""}`);
+    for (const w of warnings) console.log(`  ⚠ ${w}`);
+    return;
+  }
+
+  // 0.5.0: kanonik boru hattı yanıtı (CP üzerinden atomik deploy) — legacy created/updated alanları yok.
+  if (result.committed === true) {
+    if (Array.isArray(result.remoteOnlyKept) && result.remoteOnlyKept.length) {
+      console.log(`  (kept ${result.remoteOnlyKept.length} remote-only file(s) — push does not delete)`);
+    }
+    console.log(`✓ Deployed atomically: deployment #${result.deploymentId}, revision #${result.sourceRevisionId}, pointer v${result.pointerVersion}.`);
+    if (mode === "draft") {
+      console.log("Preview & publish it in the admin panel: Theme -> Theme library -> \"Open in editor\".");
+      console.log("Publish it live with:  blocofy theme publish");
+    }
+    return;
+  }
 
   // Sunucu canlı-yazımı bildirdiyse (yeni alan; eski sunucuda yok) belirgin uyar.
   if (result.warning === "live_write" && result.message) {
@@ -300,7 +410,7 @@ async function themePush(rest) {
 }
 
 async function contentPush(scope, rest) {
-  const { positionals } = parseArgs(rest);
+  const { positionals } = parseArgsOrExit(rest, KNOWN.content);
   const dir = resolve(positionals[0] ?? process.cwd());
   if (!existsSync(dir)) {
     console.error(`Directory not found: ${dir}`);
@@ -322,7 +432,7 @@ async function contentPush(scope, rest) {
 }
 
 async function contentPull(scope, rest) {
-  const { positionals } = parseArgs(rest);
+  const { positionals } = parseArgsOrExit(rest, KNOWN.content);
   const dir = resolve(positionals[0] ?? process.cwd());
   const creds = requireCreds();
   const { count } = await pullContent({ dir, url: creds.url, token: creds.token, scope });
@@ -330,7 +440,7 @@ async function contentPull(scope, rest) {
 }
 
 async function themeDev(rest) {
-  const { flags, positionals } = parseArgs(rest);
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeDev);
   const themeDir = resolve(positionals[0] ?? process.cwd());
 
   if (!existsSync(themeDir)) {
@@ -471,7 +581,7 @@ async function themeDev(rest) {
 }
 
 async function themePublish(rest) {
-  const { flags } = parseArgs(rest);
+  const { flags } = parseArgsOrExit(rest, KNOWN.themePublish);
   const creds = requireCreds();
   let instance = typeof flags.instance === "string" ? flags.instance : null;
   if (!instance) {
@@ -486,7 +596,7 @@ async function themePublish(rest) {
 }
 
 async function themeRename(rest) {
-  const { flags, positionals } = parseArgs(rest);
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeRename);
   const handle = positionals[0];
   const name = positionals.slice(1).join(" ") || (typeof flags.name === "string" ? flags.name : null);
   if (!handle || !name) {
@@ -540,6 +650,13 @@ if (first === "--version" || first === "-v") {
   console.log(VERSION);
 } else if (!first || first === "--help" || first === "-h" || first === "help") {
   printHelp();
+} else if (args.includes("--help") || args.includes("-h")) {
+  // 0.5.0: `--help` HERHANGİ bir konumda YARDIMDIR — alt-komut handler'ı asla koşmaz.
+  // (0.4.0'da `blocofy theme push --help` GERÇEK bir push koşuyordu.)
+  printHelp();
+} else if (args.includes("--version") || args.includes("-v")) {
+  // Aynı simetri: `theme push <dir> --version` da yalnız sürüm basar, asla yazmaz.
+  console.log(VERSION);
 } else if (first === "login") {
   login(rest).catch((error) => {
     console.error(error?.message ?? error);

package/lib/args.mjs

@@ -5,9 +5,14 @@
  */
 
 /** Sonraki token'ı değer olarak almayan flag'ler. */
-const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "help", "version"]);
+const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version"]);
 
-export function parseArgs(rest) {
+/**
+ * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`
+ * `unknownFlag` olarak döner ve DEĞER YUTMAZ — eskiden `--halp mydir` `mydir`'i değer sanıp
+ * hedef dizini sessizce cwd'ye kaydırıyordu (0.5.0: bilinmeyen bayrak = yazımsız çıkış).
+ */
+export function parseArgs(rest, known = null) {
   const flags = {};
   const positionals = [];
   for (let i = 0; i < rest.length; i++) {
@@ -17,6 +22,9 @@ export function parseArgs(rest) {
       continue;
     }
     const key = arg.slice(2);
+    if (known && !known.has(key)) {
+      return { flags, positionals, unknownFlag: `--${key}` };
+    }
     if (BOOLEAN_FLAGS.has(key)) {
       flags[key] = true;
       continue;

package/lib/dev-server.mjs

@@ -97,6 +97,9 @@ export function startDevServer({ dir, url, token, port, syncDraft = false, onErr
     let error = null;
     if (syncDraft) {
       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.
         await pushTheme({ dir, url, token, draft: true, onRetry });
       } catch (err) {
         error = err?.message ?? String(err); // senkron hatası reload'u engellemesin

package/lib/local-theme.mjs

@@ -7,7 +7,9 @@ import { extname, join, relative, sep } from "node:path";
  * THEME_DIRS, keyed by relative path with the `.liquid` extension stripped.
  */
 
-export const THEME_DIRS = new Set(["layout", "section", "block", "partial", "asset", "template"]);
+// Mirror of the platform's theme-paths.ts THEME_DIRS (incl. `layer`, added M5 B1 — 0.5.0 closes the
+// drift where a pulled layer/ file was silently dropped from the next push).
+export const THEME_DIRS = new Set(["layout", "section", "block", "layer", "partial", "asset", "template"]);
 const LIQUID_KINDS = new Set(["layout", "section", "block", "partial", "template"]);
 
 /**
@@ -16,7 +18,11 @@ const LIQUID_KINDS = new Set(["layout", "section", "block", "partial", "template
  */
 export function localPathFor(key) {
   const top = key.split("/")[0] ?? "";
-  return LIQUID_KINDS.has(top) && !key.endsWith(".liquid") ? `${key}.liquid` : key;
+  // Platform repoPathFor aynası (0.5.0): `.liquid` yalnız UZANTISIZ basename'lere — `template/index.json`
+  // diske AYNEN yazılır; eski kural onu `.json.liquid` yapıp git-checkout'lu bir çalışma dizininde
+  // repo'daki gerçek dosyanın yanına churn-ikizi düşürüyordu.
+  const base = key.split("/").pop() ?? "";
+  return LIQUID_KINDS.has(top) && !base.includes(".") ? `${key}.liquid` : key;
 }
 
 /** Turn a theme directory into a `{ path: content }` map (sent to dev-render). */

package/lib/theme-sync.mjs

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { localPathFor, readLocalTemplates } from "./local-theme.mjs";
+import { THEME_DIRS, localPathFor, readLocalTemplates } from "./local-theme.mjs";
 
 /**
  * `blocofy theme pull/push`. Talks to the platform's `/api/dev/theme` endpoint
@@ -9,6 +9,19 @@ import { localPathFor, readLocalTemplates } from "./local-theme.mjs";
  * readLocalTemplates → POST (create/update; no delete).
  */
 
+/**
+ * M4 canonical source-write handshake. We declare the protocol version + the full canonical-write
+ * capability set; the server is authoritative and fences an under-declaring client (a NEW CLI against an
+ * OLD server just sees the headers ignored — forward compatible). Capabilities must match the server's
+ * CANONICAL_WRITE_CAPABILITIES exactly, in order.
+ */
+const CANONICAL_PROTOCOL = "1";
+const CANONICAL_CAPABILITIES = "validate,dry-run,diff,idempotency-key,target-instance";
+
+function canonicalHeaders(extra = {}) {
+  return { "x-blocofy-protocol": CANONICAL_PROTOCOL, "x-blocofy-capabilities": CANONICAL_CAPABILITIES, ...extra };
+}
+
 async function errorText(res) {
   const text = await res.text();
   try {
@@ -18,6 +31,42 @@ async function errorText(res) {
   }
 }
 
+/**
+ * Yapılandırılmış HTTP hatası (0.5.0): mesajın yanında `code` (sunucunun `error` alanı), `status` ve tam
+ * `body` taşınır — 426 `cli_upgrade_required` (fence.missing/requiredVersion) ve 409 `idempotency_conflict`
+ * için insan-dili mesajı ÇAĞIRAN kurar; buradaki throw yalnız veriyi kaybetmeden taşır.
+ */
+async function httpError(res) {
+  const text = await res.text();
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    /* düz metin gövde */
+  }
+  const err = new Error(typeof body?.error === "string" ? body.error : text || `HTTP ${res.status}`);
+  err.status = res.status;
+  err.code = typeof body?.error === "string" ? body.error : null;
+  err.body = body;
+  return err;
+}
+
+/**
+ * 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`
+ * alanını hiç dönmez → false → `--dry-run` reddedilir; aksi hâlde eski sunucu `dryRun`'ı yok sayıp GERÇEK
+ * yazım yapardı (0.5.0 öncesi sessiz-yazım regresyonu).
+ */
+export async function fetchCanonicalSupport({ url, token }) {
+  const base = url.replace(/\/+$/, "");
+  const res = await fetch(`${base}/api/dev/theme`, {
+    headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
+  });
+  if (!res.ok) throw await httpError(res);
+  const body = await res.json();
+  return { supported: body?.protocol === 1 };
+}
+
 /** Backoff delays (ms) between attempts — index 0 = after the first failure. */
 const RETRY_BACKOFF_MS = [300, 900];
 
@@ -70,7 +119,7 @@ export async function pullTheme({ dir, url, token, draft = false, instance = nul
   const base = url.replace(/\/+$/, "");
   const query = instance ? `?instance=${encodeURIComponent(instance)}` : draft ? "?draft=1" : "";
   const res = await fetch(`${base}/api/dev/theme${query}`, {
-    headers: { authorization: `Bearer ${token}` },
+    headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
   });
   if (!res.ok) throw new Error(await errorText(res));
   const { files } = await res.json();
@@ -118,21 +167,86 @@ export async function fetchDevSession({ url, token, name = null }) {
  * writes to a draft theme instance instead of the live theme — preview & publish
  * it from the admin panel without affecting the live site.
  */
-export async function pushTheme({ dir, url, token, draft = false, instance = null, name = null, onRetry = null }) {
+export async function pushTheme({ dir, url, token, draft = false, instance = null, name = null, dryRun = false, idempotencyKey = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const files = readLocalTemplates(dir);
-  const payload = instance ? { files, instance } : name ? { files, draft, name } : { files, draft };
+  const headersFor = (extra = {}) => canonicalHeaders({ authorization: `Bearer ${token}`, ...extra });
+  const remoteOnlyKept = [];
+  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. Taslak hedefte `?name=` taşınır: adsız probe taslağı
+    //     `CLI Draft — <tarih>` olarak yaratır ve POST'un --name'i reuse yolunda yok sayılırdı.
+    //  3) Gerçek POST. Dev-sync key göndermediği için bu aşamaların hiçbirini ödemez.
+    const pre = await fetchWithRetry(
+      `${base}/api/dev/theme`,
+      { method: "POST", headers: headersFor({ "content-type": "application/json", "x-idempotency-key": idempotencyKey }), body: JSON.stringify({ ...(instance ? { files, instance } : { files, draft, ...(name ? { name } : {}) }), dryRun: true }) },
+      { onRetry },
+    );
+    if (!pre.ok) throw await httpError(pre);
+
+    const query = instance
+      ? `?instance=${encodeURIComponent(instance)}`
+      : draft
+        ? `?draft=1${name ? `&name=${encodeURIComponent(name)}` : ""}`
+        : "";
+    const probe = await fetch(`${base}/api/dev/theme${query}`, { headers: headersFor() });
+    if (!probe.ok) throw await httpError(probe);
+    const { files: remote = {} } = await probe.json();
+    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") {
+        files[key] = typeof content === "string" ? content : "";
+        remoteOnlyKept.push(key);
+      }
+    }
+    remoteOnlyKept.sort();
+  }
+  const target = instance ? { files, instance } : name ? { files, draft, name } : { files, draft };
+  // dryRun asks the server to validate (auth + snapshot + hostile-Liquid worker) WITHOUT writing.
+  const payload = dryRun ? { ...target, dryRun: true } : target;
+  const headers = canonicalHeaders({ "content-type": "application/json", authorization: `Bearer ${token}` });
+  if (idempotencyKey) headers["x-idempotency-key"] = idempotencyKey;
   const res = await fetchWithRetry(
     `${base}/api/dev/theme`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-      body: JSON.stringify(payload),
-    },
+    { method: "POST", headers, body: JSON.stringify(payload) },
     { onRetry },
   );
+  if (!res.ok) throw await httpError(res);
+  const json = await res.json();
+  return remoteOnlyKept.length ? { ...json, remoteOnlyKept } : json;
+}
+
+/**
+ * `blocofy theme push --diff` — compare the LOCAL theme with the LIVE theme (or an explicit `--instance`).
+ * Read-only: the draft target is deliberately NOT diffable — `?draft=1` GET'i sunucuda taslak PROVİZYONLAR
+ * (sayfa klonları dahil), read-only bir komut mutasyon tetikleyemez (0.5.0 denetim düzeltmesi). Çağıran
+ * çıktıyı "canlıya göre fark" diye etiketler. Returns `{ added, changed, removed }` (stripped keys).
+ */
+export async function diffTheme({ dir, url, token, instance = null }) {
+  const base = url.replace(/\/+$/, "");
+  const query = instance ? `?instance=${encodeURIComponent(instance)}` : "";
+  const res = await fetch(`${base}/api/dev/theme${query}`, {
+    headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
+  });
   if (!res.ok) throw new Error(await errorText(res));
-  return res.json();
+  const { files: remote = {} } = await res.json();
+  const local = readLocalTemplates(dir);
+  const added = [];
+  const changed = [];
+  for (const [key, content] of Object.entries(local)) {
+    if (!(key in remote)) added.push(key);
+    else if (remote[key] !== content) changed.push(key);
+  }
+  const removed = Object.keys(remote).filter((k) => !(k in local));
+  return { added: added.sort(), changed: changed.sort(), removed: removed.sort() };
 }
 
 /**

package/lib/validate.mjs

@@ -14,5 +14,5 @@ export function isValidUrl(u) {
 }
 
 export function isValidToken(t) {
-  return typeof t === "string" && t.startsWith("bcf_") && t.length >= 12;
+  return typeof t === "string" && t.startsWith("bcf_") && t.length >= 24;
 }

package/package.json

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