@blocofy/cli 0.9.0 → 0.10.0

package/lib/theme-sync.mjs

@@ -1,12 +1,17 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 
 import { THEME_DIRS, localPathFor, readLocalTemplates } from "./local-theme.mjs";
+import { fetchWithRetry } from "./http.mjs";
+import { PagesCliError, stagedWrite } from "./page-files.mjs";
 
 /**
  * `blocofy theme pull/push`. Talks to the platform's `/api/dev/theme` endpoint
  * (Bearer token). pull = GET → write to disk (re-adding `.liquid`); push =
  * readLocalTemplates → POST (create/update; no delete).
+ *
+ * CF-T3: every request goes through `fetchWithRetry` (lib/http.mjs — 429/502/503/504 + network errors, Retry-After).
+ * All are safe to resend: reads, a keyed (or naturally idempotent upsert) theme POST, publish (sets a pointer),
+ * rename (sets a label). `onRetry` surfaces each retry on stderr.
  */
 
 /**
@@ -18,6 +23,13 @@ import { THEME_DIRS, localPathFor, readLocalTemplates } from "./local-theme.mjs"
 const CANONICAL_PROTOCOL = "1";
 const CANONICAL_CAPABILITIES = "validate,dry-run,diff,idempotency-key,target-instance";
 
+/**
+ * CF-T5 review I1 — OPTIONAL capabilities (never part of the required fence above). `theme-locales`: this CLI sends the
+ * workspace's `locales/*` files, so a canonical deploy may replace `locales/` like any other theme folder (a server
+ * that sees no declaration keeps stored locale rows). Sent on every theme POST; GETs don't need it.
+ */
+const OPTIONAL_CAPABILITIES = "theme-locales";
+
 function canonicalHeaders(extra = {}) {
   return { "x-blocofy-protocol": CANONICAL_PROTOCOL, "x-blocofy-capabilities": CANONICAL_CAPABILITIES, ...extra };
 }
@@ -35,6 +47,16 @@ async function errorText(res) {
   return text || `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""}`;
 }
 
+/** `errorText` as an Error that keeps the HTTP status (exit codes: 4xx → 2, 5xx → 1). */
+async function responseError(res) {
+  const detail = await errorText(res);
+  const err = new Error(typeof detail === "string" ? detail : detail?.message ?? JSON.stringify(detail));
+  err.status = res.status;
+  if (typeof detail === "object" && detail && typeof detail.code === "string") err.code = detail.code;
+  else if (typeof detail === "string" && /^[a-z][a-z0-9_]*$/.test(detail)) err.code = detail;
+  return err;
+}
+
 /**
  * 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`
@@ -61,57 +83,57 @@ async function httpError(res) {
  * 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 }) {
+export async function fetchCanonicalSupport({ url, token, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/theme`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme`, {
     headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
-  });
+  }, { onRetry });
   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];
-
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
 /**
- * fetch wrapper that retries ONLY on transient failures: a thrown fetch (network
- * error / connection reset) or a 5xx / 429 response. Permanent 4xx (401/403/422 …)
- * fail immediately — no retry. Max 2 retries with a short backoff (300ms, 900ms).
- *
- * Safe because every endpoint here is idempotent: theme push is a file upsert
- * (create/update, no delete), pull/whoami/session/site are reads, publish sets a
- * pointer. Re-sending the same request cannot double-apply anything.
+ * CF-T1/T2 review I1 — a pulled path is accepted only if `readLocalTemplates` would read it back: a top-level theme dir
+ * (exact case) with a file below it, or `config/settings_schema.json`. Any `.blocofy`/staging segment (compared
+ * case-insensitively: APFS/NTFS fold case, so `.BLOCOFY/project.json` IS the binding) and any dot-directory (`.git`…)
+ * is refused. Returns a reason string, or null when the path is acceptable.
+ */
+/**
+ * The flat root files a theme actually HAS. The platform's starter themes ship exactly these two, so exactly
+ * these two come down.
  *
- * `onRetry({ attempt, retries, reason })` is called before each wait so callers can
- * surface a "Network error, retrying…" line (not silent).
+ * This is an allowlist on purpose. It was briefly a denylist of tooling filenames, and that inverted the rule
+ * the rest of this function is built on: anything the server named that was not a lockfile - `CLAUDE.md`,
+ * `AGENTS.md`, `next.config.js` - was written straight into the developer's project root by an ordinary pull.
+ * A theme download must never be able to place a file the developer's own tooling then trusts. If a theme
+ * legitimately grows another root file, this set is where it is added, deliberately.
  */
-export async function fetchWithRetry(input, init, { retries = 2, onRetry, backoff = RETRY_BACKOFF_MS } = {}) {
-  let lastErr;
-  for (let attempt = 0; attempt <= retries; attempt += 1) {
-    let res;
-    try {
-      res = await fetch(input, init);
-    } catch (err) {
-      // Thrown fetch = network-level failure (DNS, reset, "fetch failed"). Transient.
-      lastErr = err;
-      if (attempt === retries) throw err;
-      onRetry?.({ attempt: attempt + 1, retries, reason: err?.message ?? String(err) });
-      await sleep(backoff[attempt] ?? 0);
-      continue;
-    }
-    // 5xx / 429 = transient server-side; retry. Other statuses (incl. 4xx) return as-is.
-    if ((res.status >= 500 || res.status === 429) && attempt < retries) {
-      onRetry?.({ attempt: attempt + 1, retries, reason: `HTTP ${res.status}` });
-      await sleep(backoff[attempt] ?? 0);
-      continue;
-    }
-    return res;
+const ROOT_FILES_ALLOWED = new Set(["readme.md", "blueprint.json"]);
+
+function pullPathProblem(rel) {
+  const segs = rel.split("/");
+  if (segs.some((seg) => { const l = seg.toLowerCase(); return l === ".blocofy" || l.startsWith(".blocofy-staging-"); })) return "reserved CLI path";
+  if (segs.slice(0, -1).some((seg) => seg.startsWith("."))) return "hidden directory";
+  // `config/` — the theme's own configuration rows. `settings_schema.json` is the one a push sends back; the
+  // platform serves the others (a starter theme ships `config/theme.json`) and a pull that refused them
+  // refused the WHOLE download, so a freshly provisioned site could not be pulled at all. They are written
+  // read-only: the push gate accepts only `settings_schema.json` under `config/`, and `pages`/`settings`
+  // have their own commands. One flat level, no nesting.
+  if (segs[0] === "config") {
+    if (segs.length !== 2) return "config files are one level deep";
+    // `settings pull` owns this name; a theme row must not shadow the file that command writes.
+    return segs[1] === "settings.json" ? "config/settings.json belongs to `settings pull`" : null;
+  }
+  if (segs.length === 1) {
+    // A FLAT FILE AT THE THEME ROOT. The platform stores rows a push does not send (the starter themes ship
+    // `README.md` and `blueprint.json`) and serves them on pull; refusing them refused the whole download.
+    // Case-folded, because APFS and NTFS fold case: `Readme.MD` and `README.md` are one file on disk.
+    if (segs[0].startsWith(".")) return "hidden file";
+    return ROOT_FILES_ALLOWED.has(segs[0].toLowerCase()) ? null : "not a theme file at the theme root";
   }
-  // Unreachable (loop returns or throws), but keeps the type honest.
-  throw lastErr;
+  if (!THEME_DIRS.has(segs[0])) return "not a theme file (would not be pushed back)";
+  return null;
 }
 
 /**
@@ -119,22 +141,32 @@ export async function fetchWithRetry(input, init, { retries = 2, onRetry, backof
  * With `draft`, pulls the "CLI Draft" instance (what `theme dev` syncs into)
  * instead of the live theme — symmetric with `push --draft`.
  */
-export async function pullTheme({ dir, url, token, draft = false, instance = null }) {
+export async function pullTheme({ dir, url, token, draft = false, instance = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const query = instance ? `?instance=${encodeURIComponent(instance)}` : draft ? "?draft=1" : "";
-  const res = await fetch(`${base}/api/dev/theme${query}`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme${query}`, {
     headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   const { files } = await res.json();
-  let count = 0;
-  for (const [key, content] of Object.entries(files ?? {})) {
-    const full = join(dir, localPathFor(key));
-    mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, typeof content === "string" ? content : "");
-    count += 1;
+  // CF-T2: staged + contained (all-or-nothing). Every path is validated before the first byte is written; a
+  // server path that escapes the directory, targets the CLI's own `.blocofy/` binding, or would not be read back by
+  // the next push refuses the whole pull.
+  const entries = Object.entries(files ?? {}).map(([key, content]) => [localPathFor(key), content]);
+  const rejected = entries.map(([rel]) => [rel, pullPathProblem(rel)]).filter(([, problem]) => problem);
+  if (rejected.length) {
+    throw new PagesCliError("PAGES_PATH_ESCAPE", "The server sent a path this CLI does not write; nothing was written.", {
+      diagnostics: rejected.map(([rel, problem]) => ({ level: "error", code: "PAGES_PATH_ESCAPE", message: problem, path: rel })),
+    });
+  }
+  const created = !existsSync(dir);
+  mkdirSync(dir, { recursive: true });
+  try {
+    return { count: stagedWrite(realpathSync(dir), entries) };
+  } catch (error) {
+    if (created) rmSync(dir, { recursive: true, force: true }); // no empty directory left behind
+    throw error;
   }
-  return { count };
 }
 
 /**
@@ -143,12 +175,12 @@ export async function pullTheme({ dir, url, token, draft = false, instance = nul
  * öncesi (hedef tenant'ı yaz) çağırır; yanlış-tenant'a yazımı görünür kılar.
  * `{ site: { id, slug, name }, liveThemeId }`.
  */
-export async function fetchWhoami({ url, token }) {
+export async function fetchWhoami({ url, token, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/whoami`, {
+  const res = await fetchWithRetry(`${base}/api/dev/whoami`, {
     headers: { authorization: `Bearer ${token}` },
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }
 
@@ -156,12 +188,12 @@ 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, name = null }) {
+export async function fetchDevSession({ url, token, name = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const query = name ? `?name=${encodeURIComponent(name)}` : "";
-  const res = await fetch(`${base}/api/dev/session${query}`, {
+  const res = await fetchWithRetry(`${base}/api/dev/session${query}`, {
     headers: { authorization: `Bearer ${token}` },
-  });
+  }, { onRetry });
   if (!res.ok) {
     const detail = await errorText(res);
     // Yeni sunucular 410'da açıklayıcı bir gövde döndürür — onu olduğu gibi göster, o otoritedir.
@@ -173,7 +205,7 @@ export async function fetchDevSession({ url, token, name = null }) {
           "(HTTP 410). Draft sync and `theme publish` are unaffected — they use different endpoints.",
       );
     }
-    throw new Error(detail);
+    throw Object.assign(new Error(detail), { status: res.status });
   }
   return res.json();
 }
@@ -187,6 +219,7 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   const base = url.replace(/\/+$/, "");
   const files = readLocalTemplates(dir);
   const headersFor = (extra = {}) => canonicalHeaders({ authorization: `Bearer ${token}`, ...extra });
+  const postHeaders = (extra = {}) => headersFor({ "content-type": "application/json", "x-blocofy-optional-capabilities": OPTIONAL_CAPABILITIES, ...extra });
   const remoteOnlyKept = [];
   const remoteOnlyRemoved = [];
   if (idempotencyKey && !dryRun) {
@@ -205,20 +238,20 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
     //  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 }) },
+      { method: "POST", headers: postHeaders({ "x-idempotency-key": idempotencyKey }), body: JSON.stringify({ ...(instance ? { files, instance } : { files, draft, ...(name ? { name } : {}) }), dryRun: true }) },
       { onRetry },
     );
     if (!pre.ok) throw await httpError(pre);
 
     let probeInstance = instance;
     if (!instance && draft) {
-      const status = await fetchSiteStatus({ url, token });
+      const status = await fetchSiteStatus({ url, token, onRetry });
       probeInstance = (status?.drafts ?? []).find((d) => d.source === "import")?.id ?? null;
     }
     let remote = {};
     if (probeInstance || !draft) {
       const query = probeInstance ? `?instance=${encodeURIComponent(probeInstance)}` : "";
-      const probe = await fetch(`${base}/api/dev/theme${query}`, { headers: headersFor() });
+      const probe = await fetchWithRetry(`${base}/api/dev/theme${query}`, { headers: headersFor() }, { onRetry });
       if (!probe.ok) throw await httpError(probe);
       remote = (await probe.json()).files ?? {};
     }
@@ -245,7 +278,7 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   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}` });
+  const headers = postHeaders();
   if (idempotencyKey) headers["x-idempotency-key"] = idempotencyKey;
   const res = await fetchWithRetry(
     `${base}/api/dev/theme`,
@@ -267,13 +300,13 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
  * (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 }) {
+export async function diffTheme({ dir, url, token, instance = null, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
   const query = instance ? `?instance=${encodeURIComponent(instance)}` : "";
-  const res = await fetch(`${base}/api/dev/theme${query}`, {
+  const res = await fetchWithRetry(`${base}/api/dev/theme${query}`, {
     headers: canonicalHeaders({ authorization: `Bearer ${token}` }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   const { files: remote = {} } = await res.json();
   const local = readLocalTemplates(dir);
   const added = [];
@@ -291,14 +324,14 @@ export async function diffTheme({ dir, url, token, instance = null }) {
  * 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 }) {
+export async function publishInstance({ url, token, instanceId, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/publish`, {
+  const res = await fetchWithRetry(`${base}/api/dev/publish`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
     body: JSON.stringify({ instanceId }),
-  });
-  if (!res.ok) throw new Error(await errorText(res));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }
 
@@ -307,14 +340,14 @@ export async function publishInstance({ url, token, instanceId }) {
  * 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 }) {
+export async function renameInstance({ url, token, instance, name, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/theme/rename`, {
+  const res = await fetchWithRetry(`${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));
+  }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }
 
@@ -322,9 +355,9 @@ export async function renameInstance({ url, token, instance, name }) {
  * 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.
  */
-export async function fetchSiteStatus({ url, token }) {
+export async function fetchSiteStatus({ url, token, onRetry = null }) {
   const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/site`, { headers: { authorization: `Bearer ${token}` } });
-  if (!res.ok) throw new Error(await errorText(res));
+  const res = await fetchWithRetry(`${base}/api/dev/site`, { headers: { authorization: `Bearer ${token}` } }, { onRetry });
+  if (!res.ok) throw await responseError(res);
   return res.json();
 }

package/package.json

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