@blocofy/cli 0.2.4 → 0.5.0

package/README.md

@@ -17,13 +17,45 @@ blocofy login [--url <url>] [--token <bcf_…>]
                           # Save your platform URL + dev token (~/.blocofy/credentials.json, 0600).
 blocofy theme dev [dir]   # Local dev server. Prints 3 views — local preview, a live-domain
                           # preview link, and the theme editor — all auto-reloading on save.
-                          # --port <n> (default 3030), --no-sync (local preview only)
+                          # --port <n> (default 3030), --no-sync (local preview only),
+                          # --name <name> (name the draft when first created)
 blocofy theme pull [dir]  # Download the live theme to disk.
-blocofy theme push [dir]  # Write the local theme to the live site (create/update; no delete).
+blocofy theme push [dir]  # Write the local theme to a DRAFT by default (create/update; no
+                          # delete) — preview & publish from the admin panel. --live writes
+                          # to the live site immediately (asks to confirm; add --yes for CI).
+                          # --name <name> names the new draft (draft mode only).
+blocofy theme rename <handle> <new name>
+                          # Rename a theme (label only). Works on any theme, live included.
+                          # Handle from the panel theme card or `blocofy status`.
 blocofy --version
 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).
+- **0.3.0** — `theme push` now writes to a **draft** by default; use `--live` for the old
+  immediate-live behavior (with a confirmation prompt; `--yes` to skip it in CI). `blocofy
+  status` now names the exact pages at 404 risk when a theme's pages are split off the live theme.
+
 ## How it works
 
 `theme dev` starts a local HTTP server. For each page request it reads your local theme

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,14 +20,36 @@ 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 } from "../lib/theme-sync.mjs";
-import { isAffirmative, livePushDecision } from "../lib/confirm.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";
 
 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 "";
@@ -43,13 +66,14 @@ Usage
       Save your platform URL + dev token to ~/.blocofy/credentials.json.
       Get a token from the admin panel → Settings → Theme CLI tokens.
 
-  blocofy theme dev [dir] [--port <n>] [--no-sync]
+  blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
       Start a dev server and print 3 auto-reloading views — Local, live-domain
       Preview, and the theme Editor. Press l / p / e to open each, q to quit.
       Edit a file and save → every open view reloads. Saves sync to a DRAFT theme
       only (never the live site). (dir defaults to cwd)
         --port <n>   local port (default 3030)
         --no-sync    local preview only (skip draft sync + remote views)
+        --name <name>  name the draft when it is first created (ignored if it already exists)
 
   blocofy theme pull [dir] [--draft] [--instance <handle>]
       Download the live theme to disk. (dir defaults to cwd)
@@ -57,14 +81,25 @@ Usage
         --instance <handle>  pull a specific theme by its handle (from the admin
                              panel theme card, or \`blocofy status\`)
 
-  blocofy theme push [dir] [--draft] [--yes] [--instance <handle>]
-      Write the local theme to the LIVE site IMMEDIATELY (create/update; no delete,
-      no preview). Asks for confirmation first; non-interactive shells must pass --yes.
-        --draft      write to a draft theme instead — preview & publish it from the
-                     admin panel (recommended; never touches the live site)
-        --yes        confirm the live push without prompting (for CI / agents)
+  blocofy theme push [dir] [--live] [--yes] [--instance <handle>]
+      By DEFAULT writes to a DRAFT theme (create/update; no delete) — preview & publish
+      it from the admin panel, never touching the live site. Publish it with
+      'blocofy theme publish'.
+        --live       write to the LIVE site IMMEDIATELY (no preview). Asks for
+                     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)
+        --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,
+      including the live one. Handle comes from the panel theme card or 'blocofy status'.
 
   blocofy theme publish [--instance <handle>]
       Publish a draft theme to the LIVE site. With no flag, publishes the draft that
@@ -90,7 +125,7 @@ Usage
 Examples
   blocofy login --url https://store.myblocofy.com --token bcf_xxxxxxxx
   blocofy theme pull && blocofy theme dev
-  blocofy theme push --draft && blocofy theme publish
+  blocofy theme push && blocofy theme publish
   blocofy status
 
 Auth: ~/.blocofy/credentials.json (from \`login\`), or BLOCOFY_URL + BLOCOFY_TOKEN env vars.
@@ -110,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() : "";
 
@@ -178,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);
@@ -189,15 +224,56 @@ 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}`);
     process.exit(1);
   }
   const creds = requireCreds();
-  const draft = Boolean(flags.draft);
-  const instance = typeof flags.instance === "string" ? flags.instance : null;
+  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"
+  // modu canlıya yazar ve onay gerektirir.
+  const { mode, instance } = resolvePushMode({
+    live: Boolean(flags.live),
+    draft: Boolean(flags.draft),
+    instance: instanceFlag,
+  });
 
   // Hedef tenant'ı çöz ve GÖSTER — site sunucuda TOKEN'dan çözülür (URL kozmetik),
   // yanlış-tenant'a yazımı görünür kılar ("klarosa sandım, ksc'ye yazdım"). whoami
@@ -209,21 +285,27 @@ async function themePush(rest) {
     /* best-effort */
   }
   const target = site ? siteLabel(site) : creds.url;
-  if (site) {
-    console.log(`→ ${draft ? "Pushing to a draft" : "Pushing to the LIVE theme"} of ${target}`);
+  if (mode === "instance") {
+    console.log(`→ Pushing to theme ${instance}${site ? ` of ${target}` : ""}`);
+  } else if (mode === "live") {
+    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}` : ""}`);
   }
 
-  // Canlı push (flag'siz) ANINDA canlı temayı değiştirir (önizleme yok). Agent/CI
-  // kazara canlıya basmasın diye açık onay şart (#431 L2).
+  // 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: draft || Boolean(instance),
+    draft: mode !== "live" || dryRun,
     yes: Boolean(flags.yes),
     confirm: Boolean(flags.confirm),
     isTTY: Boolean(process.stdin.isTTY),
   });
   if (decision.mustAbort) {
-    console.error(`⚠ 'theme push' writes to the LIVE theme of ${target} immediately (no preview).`);
-    console.error(`  Non-interactive shell: pass --yes to confirm, or use --draft for a safe draft.`);
+    console.error(`⚠ 'theme push --live' writes to the LIVE theme of ${target} 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);
   }
   if (decision.needsPrompt) {
@@ -235,22 +317,90 @@ async function themePush(rest) {
       rl.close();
     }
     if (!isAffirmative(answer)) {
-      console.error("Aborted. Use `--draft` to push to a draft, or `--yes` to confirm the live push.");
+      console.error("Aborted. Omit `--live` to push to a safe draft, or pass `--live --yes` to confirm.");
       process.exit(1);
     }
   }
 
-  const result = await pushTheme({
-    dir,
-    url: creds.url,
-    token: creds.token,
-    draft,
-    instance,
-    onRetry: (info) => console.error(retryNotice(info)),
-  });
+  // `--name` yalnızca YENİ taslak yaratırken (draft modu) anlamlı — canlıya/mevcut
+  // instance'a yazarken ad kaydedilmez, sessizce kaybolmasın diye açıkça uyar.
+  if (name && mode !== "draft") {
+    console.error("Note: --name yalnız yeni taslak yaratırken (varsayılan push) geçerli, yok sayıldı.");
+  }
+
+  // 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) {
+    console.error(`\n⚠ ${result.message}\n`);
+  }
+
   if (result.instanceId) {
     console.log(`Pushed to theme ${result.instanceId} (${result.created} created, ${result.updated} updated).`);
-    console.log(`Preview & publish it in the admin panel: Theme → Theme library → "Open in editor".`);
+    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`);
+    } else {
+      console.log(`Preview & publish it in the admin panel: Theme → Theme library → "Open in editor".`);
+    }
   } else {
     const extra = result.skippedDeletes
       ? `, ${result.skippedDeletes} remote file(s) absent locally (not deleted)`
@@ -260,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}`);
@@ -282,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 });
@@ -290,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)) {
@@ -306,7 +456,8 @@ async function themeDev(rest) {
   let session = null;
   if (!flags["no-sync"]) {
     try {
-      session = await fetchDevSession({ url: creds.url, token: creds.token });
+      const name = typeof flags.name === "string" ? flags.name : null;
+      session = await fetchDevSession({ url: creds.url, token: creds.token, name });
     } catch (error) {
       console.warn(
         `Warning: dev session unavailable (${error?.message ?? error}). ` +
@@ -430,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) {
@@ -444,6 +595,20 @@ async function themePublish(rest) {
   );
 }
 
+async function themeRename(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) {
+    console.error("Usage: blocofy theme rename <handle> <new name>");
+    console.error("  Rename a theme (handle from the panel theme card or `blocofy status`).");
+    process.exit(1);
+  }
+  const creds = requireCreds();
+  const result = await renameInstance({ url: creds.url, token: creds.token, instance: handle, name });
+  console.log(`✓ Renamed to "${result.name}" (${result.id}).`);
+}
+
 async function status() {
   const creds = requireCreds();
   const s = await fetchSiteStatus({ url: creds.url, token: creds.token });
@@ -455,12 +620,23 @@ async function status() {
       : `Live theme: none`,
   );
   console.log(`Health: ${s.health}`);
+  // orphan_missing_slugs yeni sunucu alanı (PR #661). Eski/deploy-edilmemiş sunucuda
+  // yok → null; o durumda eski (yumuşatılmış) sayaç satırına düş.
+  const missing = Array.isArray(s.orphan_missing_slugs) ? s.orphan_missing_slugs : null;
   if (s.health === "live_instance_empty") {
     console.error(
       `  ⚠ The live theme has no pages — the site will 404. Publish a theme with content:  blocofy theme publish`,
     );
   } else if (s.health === "pages_split") {
-    console.warn(`  ⚠ ${s.orphaned_pages} page(s) live on a non-live instance (orphan).`);
+    if (missing && missing.length) {
+      console.warn(
+        `  ⚠ These pages are published only on a non-live theme, so visitors can't reach them (404 risk): ` +
+          `${missing.join(", ")}\n` +
+          `  Fix: publish the theme that has them —  blocofy theme publish`,
+      );
+    } else {
+      console.warn(`  ⚠ ${s.orphaned_pages} page(s) published on a non-live theme.`);
+    }
   }
   if (Array.isArray(s.drafts) && s.drafts.length > 0) {
     console.log(`Drafts: ${s.drafts.map((d) => `${d.id}${d.name ? ` ${d.name}` : ""}`).join(", ")}`);
@@ -474,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);
@@ -499,6 +682,11 @@ if (first === "--version" || first === "-v") {
     console.error(error?.message ?? error);
     process.exit(1);
   });
+} else if (first === "theme" && rest[0] === "rename") {
+  themeRename(rest.slice(1)).catch((error) => {
+    console.error(error?.message ?? error);
+    process.exit(1);
+  });
 } else if (first === "status") {
   status().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", "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/confirm.mjs

@@ -15,6 +15,22 @@ export function livePushDecision({ draft, yes, confirm, isTTY }) {
   return { autoApproved: false, needsPrompt: true, mustAbort: false };
 }
 
+/**
+ * `theme push` hedefini seç (saf, yan etkisiz). Yeni varsayılan: DRAFT (güvenli).
+ * `--live` eski "anında canlı" davranışını açıkça geri getirir.
+ *   - `instance` verilmişse → { mode: "instance", instance } (açık-hedef; `--live`
+ *     olsa bile instance KAZANIR — kullanıcı belirli bir temayı adresledi).
+ *   - `--live` (instance yok) → { mode: "live" } (onay gerektiren tek yol).
+ *   - aksi halde → { mode: "draft" } (varsayılan; açık `--draft` dahil).
+ *   - `--live` + `--draft` birlikte → draft (güvenli olan kazanır).
+ */
+export function resolvePushMode({ live, draft, instance } = {}) {
+  if (instance) return { mode: "instance", instance };
+  if (draft) return { mode: "draft" };
+  if (live) return { mode: "live" };
+  return { mode: "draft" };
+}
+
 /** y/N yanıtını yorumla (yes/y → onay). */
 export function isAffirmative(answer) {
   const a = String(answer ?? "").trim().toLowerCase();

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();
@@ -103,9 +152,10 @@ export async function fetchWhoami({ url, token }) {
  * Dev session bilgisi (#119 `theme dev`): platform draft instance'ı hazırlar ve
  * 3 görünümün URL'lerini döner — `{ draftInstanceId, previewUrl, editorUrl, site }`.
  */
-export async function fetchDevSession({ url, token }) {
+export async function fetchDevSession({ url, token, name = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/session`, {
+  const query = name ? `?name=${encodeURIComponent(name)}` : "";
+  const res = await fetch(`${base}/api/dev/session${query}`, {
     headers: { authorization: `Bearer ${token}` },
   });
   if (!res.ok) throw new Error(await errorText(res));
@@ -117,21 +167,86 @@ export async function fetchDevSession({ url, token }) {
  * 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, 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 } : { 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() };
 }
 
 /**
@@ -150,6 +265,22 @@ export async function publishInstance({ url, token, instanceId }) {
   return res.json();
 }
 
+/**
+ * Bir tema instance'ının adını değiştir (`POST /api/dev/theme/rename`). Ad yalnızca
+ * bir etiket — canlı instance dahil sahip olunan her instance yeniden adlandırılabilir.
+ * `{ ok, id, name }` döner.
+ */
+export async function renameInstance({ url, token, instance, name }) {
+  const base = url.replace(/\/+$/, "");
+  const res = await fetch(`${base}/api/dev/theme/rename`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify({ instance, name }),
+  });
+  if (!res.ok) throw new Error(await errorText(res));
+  return res.json();
+}
+
 /**
  * Site sağlık/durum özeti (`GET /api/dev/site`) — `blocofy status`. Canlı tema instance'ı,
  * instance-başına sayfa dağılımı, taslaklar ve health döner.

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.2.4",
+  "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",