@blocofy/cli 0.14.0 → 0.15.0

package/lib/theme-sync.mjs

@@ -50,9 +50,9 @@ async function errorText(res) {
 
 /** `errorText` as an Error that keeps the HTTP status (exit codes: 4xx → 2, 5xx → 1). */
 async function responseError(res) {
+  // #989: keep `reason`/`candidates` (errorText keeps only `error`). Read from a clone so the fallback below still can.
+  const body = await res.clone().json().catch(() => null);
   if (res.status === 409) {
-    // #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), {
@@ -67,7 +67,11 @@ 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;
+  const retryAfter = res.headers.get("retry-after");
+  if (retryAfter) err.retryAfter = retryAfter;
   if (typeof detail === "object" && detail && typeof detail.code === "string") err.code = detail.code;
+  // `{ error: "<sentence>", code }` (e.g. dev/publish `work_not_publishable`): the code sits beside the sentence.
+  else if (typeof body?.code === "string" && /^[a-z][a-z0-9_]*$/.test(body.code)) err.code = body.code;
   else if (typeof detail === "string" && /^[a-z][a-z0-9_]*$/.test(detail)) err.code = detail;
   return err;
 }
@@ -89,6 +93,8 @@ async function httpError(res) {
   err.status = res.status;
   err.code = typeof body?.error === "string" ? body.error : null;
   err.body = body;
+  const retryAfter = res.headers.get("retry-after");
+  if (retryAfter) err.retryAfter = retryAfter;
   return withDraftTargetDetails(err, body);
 }
 
@@ -160,7 +166,7 @@ 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.
+ * sentence, the theme-capacity refusals (`themeCapacityRefusal`) theirs, anything else its message. Never swallowed.
  */
 export function draftSyncErrorLine(err) {
   if (err?.code === "draft_target_unverifiable") {
@@ -169,9 +175,151 @@ export function draftSyncErrorLine(err) {
   if (err?.code === "draft_target_is_live") {
     return "draft sync refused: that is the LIVE theme, and a draft sync never writes live. Nothing was written; pass a draft's handle with --instance (`blocofy status`).";
   }
+  const capacity = themeCapacityRefusal(err);
+  if (capacity) return `draft sync: ${capacity.short}`;
   return `draft sync failed: ${err?.message ?? String(err)}`;
 }
 
+const trNumber = new Intl.NumberFormat("tr-TR", { maximumFractionDigits: 1 });
+const isAmount = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const bytesLabel = (b) => (b >= 1024 ** 3 ? `${trNumber.format(b / 1024 ** 3)} GB` : `${trNumber.format(b / 1024 ** 2)} MB`);
+
+/** The admission's typed meter in words (V2 storage bytes; V1 / other `used / limit`), or null. */
+function quotaMeter(d) {
+  if (!d || typeof d !== "object") return null;
+  if (isAmount(d.usedBytes) && isAmount(d.limitBytes)) {
+    const need = isAmount(d.estimateBytes) ? `; yeni taslak yaklaşık ${bytesLabel(d.estimateBytes)} gerektiriyor` : "";
+    return `Kullanılan depolama: ${bytesLabel(d.usedBytes)} / ${bytesLabel(d.limitBytes)}${need}.`;
+  }
+  if (isAmount(d.used) && isAmount(d.limit)) {
+    const what = d.resource === "theme_drafts" ? "Taslak tema sayısı" : typeof d.resource === "string" ? d.resource : "Kullanım";
+    return `${what}: ${d.used} / ${d.limit}.`;
+  }
+  return null;
+}
+
+const CAPACITY_CODES = new Set(["target_missing", "quota_exceeded", "capacity_unavailable", "resource_busy", "source_stale"]);
+/** Transient admission refusals: every attempt answering one of these wrote nothing (a definite answer). */
+export const CAPACITY_RETRYABLE = new Set(["capacity_unavailable", "resource_busy"]);
+
+/**
+ * Theme-capacity program (ADR-0013) — the dev theme endpoint's refusals around the CLI draft, in words:
+ *  - 404 `target_missing`: `pull --draft` found no CLI draft. A read never creates a theme; `push --draft` does.
+ *  - 422 `quota_exceeded`, by `details.resource`:
+ *      `theme_bytes` — the site's theme space (a technical allowance, not the plan) is full. Any theme write can meet
+ *        it, a push to an existing draft included: no "new draft" wording, no plan upgrade; free space by deleting
+ *        unused draft themes (cancelled works' themes included; cancel releases only a work's reserved publish space,
+ *        archive frees no theme bytes), or contact support.
+ *      `theme_drafts` (the legacy draft count of a site not on theme space) — not tied to the plan: remove a draft
+ *        you no longer need; never a plan upgrade.
+ *      `storage_mb` (the plan's storage) — the NEW draft was refused for the plan: the plan message.
+ *  - 503 `capacity_unavailable` / `resource_busy`: transient (Retry-After), never the plan. lib/http.mjs has already
+ *    resent the request within its retry policy; this is the last answer.
+ *  - 409 `source_stale`: the live theme the new draft copies changed meanwhile; running the command again copies it anew.
+ * The platform wrote nothing for that answer. Returns `{ lines, short, message, details }`: `lines` the plain Turkish
+ * explanation (stderr, human mode; first line non-technical), `short` one line for `theme dev`, `message`/`details` the
+ * technical `error [code]` line and `--json` envelope. `null` for any other code (draft_target_ambiguous keeps its own).
+ * `pushCommand` is the user's push command line (its directory argument kept). A refusal of a RESENT push apply
+ * (`earlierAttempt`) says nothing about that earlier attempt, so it never claims "nothing was written" then.
+ */
+export function themeCapacityRefusal(error, { pushCommand = "blocofy theme push" } = {}) {
+  const code = error?.code;
+  if (!CAPACITY_CODES.has(code)) return null;
+  const earlier = error?.phase === "apply" && (error.earlierAttempt === "unknown" || error.earlierAttempt === "committed") ? error.earlierAttempt : null;
+  const done =
+    earlier === "committed"
+      ? "Bu deneme hiçbir şey yazmadı; ancak bu push'un önceki bir denemesi işlendi (yanıtı öyle söyledi)."
+      : earlier === "unknown"
+        ? "Bu deneme hiçbir şey yazmadı; ancak bu push'un önceki bir denemesi kesin yanıt alamadı, yazıp yazmadığı bilinmiyor."
+        : "Hiçbir şey yazılmadı.";
+  const doneEn =
+    earlier === "committed"
+      ? "This attempt wrote nothing, but an earlier attempt of this push was committed (its answer said so)."
+      : earlier === "unknown"
+        ? "This attempt wrote nothing, but an earlier attempt of this push got no definite answer, so whether it wrote is unknown."
+        : "Nothing was written.";
+  const check = earlier ? ["  Tekrar çalıştırmadan önce sitenin taslaklarını `blocofy status` ile kontrol et."] : [];
+  const checkEn = earlier ? " Check the site's drafts with `blocofy status` before running the push again." : "";
+  const extra = earlier ? { earlierAttempt: earlier } : {};
+
+  if (code === "target_missing") {
+    return {
+      lines: [
+        "Bu sitede henüz bir CLI taslağı yok; indirilecek taslak bulunamadı. Hiçbir dosya yazılmadı.",
+        `  Önce taslağı oluştur:  ${pushCommand} --draft`,
+        "  (Canlı temayı indirmek istiyorsan --draft olmadan çalıştır.)",
+      ],
+      short: "Bu sitede henüz bir CLI taslağı yok.",
+      message: `No CLI draft on this site yet (a read never creates one). Nothing was written. Create it first: ${pushCommand} --draft`,
+      details: {},
+    };
+  }
+  if (code === "quota_exceeded") {
+    const d = error?.body?.details && typeof error.body.details === "object" ? error.body.details : null;
+    if (d?.resource === "theme_bytes") {
+      // The site's theme space (a technical allowance, not the plan): any theme write can meet it — a push to an
+      // existing draft included — so no "new draft" wording and no plan upgrade; space is freed by removing drafts.
+      const head = "Sitenin tema alanı dolu; bu değişiklik için yer kalmadı.";
+      const meter = isAmount(d.usedBytes) && isAmount(d.allowanceBytes)
+        ? `Kullanılan tema alanı: ${bytesLabel(d.usedBytes)} / ${bytesLabel(d.allowanceBytes)}${isAmount(d.estimateBytes) ? `; bu değişiklik yaklaşık ${bytesLabel(d.estimateBytes)} gerektiriyor` : ""}.`
+        : null;
+      return {
+        lines: [
+          `${head} ${done}`,
+          ...(meter ? [`  ${meter}`] : []),
+          "  Yer açmak için kullanmadığın taslak temaları (iptal edilmiş çalışmaların temaları dahil) tema kütüphanesinden sil (admin paneli → Tasarım); açık bir çalışmayı iptal etmek ayrıca onun için ayrılan yayın alanını bırakır.",
+          "  Sorun sürerse destek ekibine yaz.",
+          ...check,
+        ],
+        short: `${head}${meter ? ` ${meter}` : ""} Hiçbir şey yazılmadı; yer açmak için kullanılmayan bir taslağı sil.`,
+        message: `The site's theme space is full; this change does not fit (quota_exceeded, theme_bytes). ${doneEn} Free space by deleting unused draft themes from the theme library (cancelled works' themes included); cancelling an open work also releases its reserved publish space. Or contact support.${checkEn}`,
+        details: { ...d, ...extra },
+      };
+    }
+    const meter = quotaMeter(d);
+    if (d?.resource === "theme_drafts") {
+      // The legacy draft count of a site not (yet) on theme space: not tied to the plan, so no upgrade advice.
+      const head = "Sitenin taslak tema sınırına ulaşıldı; yeni taslak oluşturulamadı.";
+      return {
+        lines: [`${head} ${done}`, ...(meter ? [`  ${meter}`] : []), "  Artık kullanmadığın bir taslak temayı sil (admin paneli → Tasarım).", ...check],
+        short: `${head}${meter ? ` ${meter}` : ""} Hiçbir şey yazılmadı; kullanmadığın bir taslağı sil.`,
+        message: `The site's draft limit refused the new draft this push needs (quota_exceeded, theme_drafts). ${doneEn} Remove a draft you no longer need.${checkEn}`,
+        details: { ...d, ...extra },
+      };
+    }
+    const head = `${d?.resource === "storage_mb" || isAmount(d?.usedBytes) ? "Depolama alanın dolu" : "Planının sınırına ulaşıldı"}; yeni taslak oluşturulamadı.`;
+    return {
+      lines: [`${head} ${done}`, ...(meter ? [`  ${meter}`] : []), "  Yeni taslak için planını yükseltebilirsin: admin paneli → Ayarlar → Plan & faturalandırma.", ...check],
+      short: `${head}${meter ? ` ${meter}` : ""} Hiçbir şey yazılmadı.`,
+      message: `The plan's capacity refused the new draft this push needs (quota_exceeded). ${doneEn}${checkEn}`,
+      details: { ...(d ?? {}), ...extra },
+    };
+  }
+  if (code === "source_stale") {
+    const head = "Canlı tema bu sırada değişti; yeni taslak onun güncel hâlinden oluşturulamadı.";
+    return {
+      lines: [`${head} ${done}`, `  Komutu yeniden çalıştır; taslak canlının güncel hâlinden oluşturulur:  ${pushCommand}`, ...check],
+      short: `${head} Hiçbir şey yazılmadı; bir sonraki kayıt yeniden dener.`,
+      message: `The live theme a new draft copies changed while it was prepared (source_stale). ${doneEn} Run the command again.${checkEn}`,
+      details: extra,
+    };
+  }
+  // capacity_unavailable / resource_busy: transient, already resent within the CLI's retry policy.
+  // Neither is about the plan or a full space, and either can answer a push to an existing draft: no "new draft" wording.
+  const head =
+    code === "resource_busy"
+      ? "Site şu anda meşgul (başka bir yazım sürüyor); işlem şimdilik yapılamadı."
+      : "Platform tema alanını şu an doğrulayamadı; bu geçici bir durum, işlem şimdilik yapılamadı.";
+  const raw = String(error?.retryAfter ?? "").trim();
+  const seconds = /^\d+$/.test(raw) ? Number(raw) : null;
+  return {
+    lines: [`${head} ${done}`, `  Biraz sonra tekrar dene${seconds ? ` (en az ${seconds} sn sonra)` : ""}:  ${pushCommand}`, ...check],
+    short: `${head} Hiçbir şey yazılmadı. Biraz sonra tekrar dene; bir sonraki kayıt yeniden dener.`,
+    message: `${code === "resource_busy" ? "The site is busy with another write" : "The platform could not check the theme space right now (temporary)"}; the change was not applied (${code}). ${doneEn} Try again later.${checkEn}`,
+    details: { ...(seconds != null ? { retryAfterSeconds: seconds } : {}), ...extra },
+  };
+}
+
 /** A local #989 refusal with the server's shape (used where the CLI selects the draft itself, e.g. `push --diff`). */
 function draftTargetAmbiguous(reason, candidates) {
   for (const c of candidates) c.restore = SITE_STATE_DRAFT_NAME.test(c.name ?? "");
@@ -527,6 +675,8 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   // An apply attempt without a certain answer (network error, 429/502/503/504) is resent under the same key. A
   // refusal of the resend says nothing about that earlier attempt: "unknown", or "committed" when its answer said so.
   let earlierAttempt = null;
+  // ADR-0013: a 503 capacity_unavailable / resource_busy is a definite "nothing was written" answer, not an unknown one.
+  let definiteNothing = false;
   const applyError = (err) => {
     Object.assign(err, { phase: "apply" });
     // target_changed names the current target; the one this push planned against is known only here.
@@ -538,11 +688,14 @@ export async function pushTheme({ dir, url, token, draft = false, instance = nul
   try {
     res = await post({ ...target, ...bindings }, idempotencyKey, {
       onRetry: (info) => {
-        earlierAttempt ??= "unknown";
+        if (!definiteNothing) earlierAttempt ??= "unknown";
+        definiteNothing = false;
         onRetry?.(info);
       },
       isFinal: async (attempt) => {
-        if ((await attempt.json().catch(() => null))?.committed === true) earlierAttempt = "committed";
+        const answer = await attempt.json().catch(() => null);
+        if (answer?.committed === true) earlierAttempt = "committed";
+        definiteNothing = CAPACITY_RETRYABLE.has(answer?.error);
         return false;
       },
     });

package/lib/theme-work.mjs

@@ -0,0 +1,369 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { fetchWithRetry } from "./http.mjs";
+import { CliRefusal } from "./media-uses.mjs";
+
+/**
+ * Theme work sessions ("çalışma") — the v1 client and the project's saved work handle.
+ *
+ *   POST /api/v1/theme-work                     (themes:write, Idempotency-Key required) → 201 { work } | 200 { work, replayed }
+ *   GET  /api/v1/theme-work/{handle}            (themes:read)                            → { work }
+ *   POST /api/v1/theme-work/{handle}/resume     (themes:read, { require_fresh? })         → { work }
+ *   POST /api/v1/theme-work/{handle}/cancel     (themes:write, { expected_state_version }) → { work }
+ *
+ * Authentication is the v1 API key (`blcf_live_…`, Bearer) — the same pair `site plan` and `pages media-uses` use.
+ * The dev token (`bcf_…`) has no theme-work endpoint: the work is bound to the credential that started it (here the
+ * API key), and only that credential (or the site owner, from the panel) can continue it.
+ *
+ * A work is always named by its exact handle (`wk_…`), never "the latest". The project remembers the handle it
+ * started or resumed last in `.blocofy/local.json` (git-ignored, per user, no secret: the handle alone grants nothing)
+ * so the CLI can name it in hints; every command still takes the handle explicitly.
+ *
+ * Retries (lib/http.mjs: network errors, 429/502/503/504): the start carries the Idempotency-Key, so a resend returns
+ * the SAME work (`replayed`), never a second one; get and resume are reads; cancel is a compare-and-set on
+ * `state_version` (a resend after a lost answer meets `work_state_conflict` with the work already cancelled).
+ */
+
+export const WORK_HANDLE_RE = /^wk_[a-z2-7]{26}$/;
+export const WORK_KEY_RE = /^[A-Za-z0-9._:-]{8,120}$/;
+export const WORK_INTENT_MAX = 120;
+export const DEFAULT_WORK_INTENT = "CLI ile tema çalışması";
+
+export const isWorkHandle = (v) => typeof v === "string" && WORK_HANDLE_RE.test(v);
+export const newWorkKey = () => `cli-work-${randomUUID()}`;
+
+const base = (apiUrl) => String(apiUrl).replace(/\/+$/, "");
+
+async function readJsonOrThrow(res) {
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  if (res.ok) {
+    if (json === null || typeof json !== "object") throw new Error(`HTTP ${res.status}: empty or non-JSON response`);
+    return json;
+  }
+  if (res.status >= 400 && res.status < 500) {
+    const error = json?.error && typeof json.error === "object" ? json.error : { code: `http_${res.status}`, message: text.slice(0, 200) || `HTTP ${res.status}` };
+    throw new CliRefusal(res.status, error);
+  }
+  const detail = json?.error?.message ?? (text ? text.slice(0, 200) : "");
+  const code = typeof json?.error?.code === "string" ? json.error.code : undefined;
+  throw Object.assign(new Error(`HTTP ${res.status}${detail ? `: ${detail}` : ""}`), {
+    status: res.status,
+    ...(code ? { code, error: json.error } : {}),
+    retryAfter: res.headers.get("retry-after"),
+  });
+}
+
+async function request(method, url, { apiKey, body, headers = {}, onRetry = null }) {
+  const h = { authorization: `Bearer ${apiKey}`, accept: "application/json", ...headers };
+  if (body !== undefined) h["content-type"] = "application/json";
+  const res = await fetchWithRetry(url, { method, headers: h, body: body === undefined ? undefined : JSON.stringify(body) }, { onRetry });
+  return readJsonOrThrow(res);
+}
+
+const workUrl = (apiUrl, handle, tail = "") => `${base(apiUrl)}/api/v1/theme-work/${encodeURIComponent(handle)}${tail}`;
+
+/** Start a work from the site's CURRENT live theme. The same key again returns the same work (`replayed: true`). */
+export function startWork({ apiUrl, apiKey, intent, idempotencyKey, onRetry = null }) {
+  return request("POST", `${base(apiUrl)}/api/v1/theme-work`, { apiKey, body: { intent }, headers: { "idempotency-key": idempotencyKey }, onRetry });
+}
+
+export function getWork({ apiUrl, apiKey, handle, onRetry = null }) {
+  return request("GET", workUrl(apiUrl, handle), { apiKey, onRetry });
+}
+
+export function resumeWork({ apiUrl, apiKey, handle, requireFresh = false, onRetry = null }) {
+  return request("POST", workUrl(apiUrl, handle, "/resume"), { apiKey, body: requireFresh ? { require_fresh: true } : {}, onRetry });
+}
+
+export function cancelWork({ apiUrl, apiKey, handle, expectedStateVersion, onRetry = null }) {
+  return request("POST", workUrl(apiUrl, handle, "/cancel"), { apiKey, body: { expected_state_version: expectedStateVersion }, onRetry });
+}
+
+// ── review + human approval ─────────────────────────────────────────────────────────────────────────────────
+//
+//   POST /api/v1/theme-work/{handle}/seal            (themes:write) → { status: "ready_for_review", already_sealed, work, package }
+//   POST /api/v1/theme-work/{handle}/approvals       (themes:write) → { status: "approval_required", approval, work }
+//   GET  /api/v1/theme-work/{handle}/publish-status  (themes:read)  → { work, phase, phase_label, package, approval }
+//
+// The CLI never publishes a work: it asks for a person's approval and reads the status. The approval URL carries no
+// token (holding the link is not a permission); a signed-in site member with the theme permission decides on it. A
+// resend after a lost answer is safe: a sealed work is answered as is, and an unused approval request is returned
+// again (the server's idempotency).
+
+/** Seal alone ("İncelemeye hazır"): the work's content is frozen for review. Requests no approval. */
+export function sealWork({ apiUrl, apiKey, handle, onRetry = null }) {
+  return request("POST", workUrl(apiUrl, handle, "/seal"), { apiKey, body: {}, onRetry });
+}
+
+/** Ask a person to publish the work (an open work is sealed first). Never publishes. */
+export function requestApproval({ apiUrl, apiKey, handle, onRetry = null }) {
+  return request("POST", workUrl(apiUrl, handle, "/approvals"), { apiKey, body: {}, onRetry });
+}
+
+/** Where the work stands (read-only). */
+export function getPublishStatus({ apiUrl, apiKey, handle, onRetry = null }) {
+  return request("GET", workUrl(apiUrl, handle, "/publish-status"), { apiKey, onRetry });
+}
+
+export const APPROVAL_HANDLE_RE = /^ap_[a-z2-7]{26}$/;
+
+/**
+ * The approval page URL, only when it is exactly this platform's approval page: same origin as the API, the path
+ * `/approve/ap_…`, no query, fragment or credentials. Anything else is not opened (and the caller says so).
+ */
+export function safeApprovalUrl(raw, apiUrl) {
+  if (typeof raw !== "string" || !raw) return null;
+  let origin;
+  let u;
+  try {
+    origin = new URL(base(apiUrl)).origin;
+    u = new URL(raw, `${origin}/`);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return null;
+  if (u.origin !== origin || u.username || u.password || u.search || u.hash) return null;
+  const m = u.pathname.match(/^\/approve\/([^/]+)$/);
+  if (!m || !APPROVAL_HANDLE_RE.test(m[1])) return null;
+  return u.href;
+}
+
+/**
+ * Where an approval request ended, from a publish-status answer: "published" | "stale" | "expired" | "declined" |
+ * "superseded" | "cancelled" | "failed" | "pending". `approvalId` is the request this command made.
+ */
+export function approvalWaitState(status, approvalId) {
+  const phase = status?.phase;
+  if (phase === "published") return "published";
+  if (phase === "cancelled") return "cancelled";
+  if (phase === "failed") return "failed";
+  const a = status?.approval ?? null;
+  if (!a || a.id !== approvalId) return phase === "preparing" ? "superseded" : "pending";
+  if (a.state === "consumed") return a.outcome?.status === "stale" ? "stale" : a.outcome?.status === "published" ? "published" : "pending";
+  if (a.state === "revoked") return a.revoke_reason === "stale" ? "stale" : a.revoke_reason === "declined" ? "declined" : "superseded";
+  if (a.expired === true) return "expired";
+  if (phase === "needs_update") return "stale";
+  return "pending";
+}
+
+/**
+ * The end of a wait in words: `{ ok, lines, code, message }` — `lines` plain Turkish (stdout on success, stderr
+ * otherwise), `code`/`message` the technical `error [code]` line of an end that is not "published".
+ */
+export function approvalOutcome(state, { handle, status = null } = {}) {
+  const theme = status?.approval?.outcome?.theme ?? null;
+  const again = `  Yeniden onay iste:  blocofy theme work request-approval ${handle}`;
+  const fresh = "  Değişikliği sürdürmek için güncel canlı sürümden yeni bir çalışma başlat:  blocofy theme work start";
+  switch (state) {
+    case "published":
+      return { ok: true, lines: [`✓ Yayınlandı: çalışma ${handle} onaylandı ve canlı sitede${theme ? ` (tema ${theme})` : ""}.`] };
+    case "stale":
+      return { ok: false, code: "approval_stale", message: "The live site changed after the approval was requested; nothing was published (approval_stale).", lines: ["Canlı site bu arada değişti; onay geçersiz oldu ve hiçbir şey yayınlanmadı. Hiçbir şeyin üzerine yazılmadı.", fresh] };
+    case "expired":
+      return { ok: false, code: "approval_expired", message: "The approval request expired before anyone decided; nothing was published (approval_expired).", lines: ["Onay isteğinin süresi doldu; kimse karar vermedi ve hiçbir şey yayınlanmadı.", again] };
+    case "declined":
+      return { ok: false, code: "approval_declined", message: "The approval request was declined; nothing was published (approval_declined).", lines: ["Onay isteği reddedildi; hiçbir şey yayınlanmadı."] };
+    case "superseded":
+      return { ok: false, code: "approval_superseded", message: "The work was reopened for changes; this approval request is no longer valid. Nothing was published (approval_superseded).", lines: ["Çalışma düzenlemeye geri alındı; bu onay isteği artık geçerli değil. Hiçbir şey yayınlanmadı.", again] };
+    case "cancelled":
+      return { ok: false, code: "work_cancelled", message: "The work was cancelled; nothing was published (work_cancelled).", lines: ["Çalışma iptal edildi; hiçbir şey yayınlanmadı."] };
+    case "failed":
+      return { ok: false, code: "publish_failed", message: "The work could not be completed (publish_failed).", lines: ["İşlem tamamlanamadı; hiçbir şey yayınlanmadı.", `  Durumu gör:  blocofy theme work status ${handle}`] };
+    default:
+      return { ok: false, code: "wait_timeout", message: "No decision yet; stopped waiting. Nothing is published until the status says so (wait_timeout).", lines: ["Bekleme süresi doldu; henüz karar verilmedi. Onaylanana kadar canlı site değişmez.", `  Durumu gör:  blocofy theme work status ${handle}`] };
+  }
+}
+
+/** The publish status in words (for `theme work status`). */
+export function publishStatusLines(status) {
+  if (!status || typeof status !== "object") return [];
+  const lines = [`  Yayın:  ${status.phase_label ?? status.phase ?? "?"}`];
+  const a = status.approval;
+  if (a && a.state === "unused" && a.expired !== true) {
+    lines.push(`  Onay bekleniyor: ${a.approval_url ?? a.id}${a.expires_at ? ` (son geçerlilik ${a.expires_at})` : ""}`);
+  }
+  return lines;
+}
+
+// ── messages ────────────────────────────────────────────────────────────────────────────────────────────────
+
+const STATE_LABEL = {
+  open: "açık (üzerinde çalışılabilir)",
+  sealed: "incelemede (şu an değiştirilemez)",
+  publishing: "yayınlanıyor",
+  published: "yayınlandı",
+  cancelled: "iptal edildi",
+  archived: "arşivlendi",
+  failed: "kapandı",
+};
+export const stateLabel = (state) => STATE_LABEL[state] ?? String(state ?? "?");
+
+const STALE_LABEL = {
+  live_theme_changed: "canlı tema değişti",
+  theme_version_changed: "temanın sürümü değişti",
+  live_source_advanced: "canlı temanın dosyaları değişti",
+  live_settings_changed: "canlı temanın ayarları değişti",
+};
+export const staleLabel = (reason) => STALE_LABEL[reason] ?? String(reason);
+
+/** The stale note (plain Turkish), or null when the work is up to date / unknown. */
+export function staleLines(work) {
+  if (work?.stale !== true) return null;
+  const reasons = Array.isArray(work.stale_reasons) && work.stale_reasons.length ? ` (${work.stale_reasons.map(staleLabel).join(", ")})` : "";
+  return [
+    `Not: Site bu çalışma başladıktan sonra değişti${reasons}. Çalışman güncel değil; hiçbir şeyin üzerine yazılmadı.`,
+    "  Yayına almadan önce çalışmanın güncellenmesi gerekecek; değişiklikleri panelde gözden geçir.",
+  ];
+}
+
+/** Human summary of a work (stdout). */
+export function workLines(work) {
+  const lines = [
+    `Çalışma: ${work.id}${work.intent ? ` — ${work.intent}` : ""}`,
+    `  Durum:  ${stateLabel(work.state)} (state_version ${work.state_version})`,
+    `  Tema:   ${work.theme ?? "(silinmiş)"}${work.sandbox ? " · yapay zekâ taslağı" : ""}`,
+  ];
+  if (work.base?.theme) lines.push(`  Başlangıç: canlı tema ${work.base.theme}${work.base.theme_version ? ` (sürüm ${work.base.theme_version})` : ""}`);
+  return lines;
+}
+
+const NOTHING = "Hiçbir şey yazılmadı.";
+
+/**
+ * A theme-work refusal in words: `{ lines, message, details }` — `lines` the plain Turkish explanation (stderr, human
+ * mode; first line non-technical), `message`/`details` the technical `error [code]` line and `--json` envelope.
+ * `op`: "start" | "status" | "resume" | "cancel" | "push" | "seal" | "request-approval" | "wait". Returns null for a code it does not know (the caller prints
+ * the server's own envelope then).
+ */
+export function themeWorkRefusal(error, { op = "status", handle = null, startCommand = "blocofy theme work start" } = {}) {
+  const e = error instanceof CliRefusal ? error.error ?? {} : error ?? {};
+  const code = typeof e.code === "string" ? e.code : error?.code;
+  const details = e.details && typeof e.details === "object" ? e.details : {};
+  const serverMessage = typeof e.message === "string" ? e.message : "";
+  const name = handle ? ` ${handle}` : "";
+  const out = (lines, message) => ({ lines, message: serverMessage ? `${message} (${serverMessage})` : message, details });
+  switch (code) {
+    case "not_found":
+      if (op === "start") {
+        return out(["Bu platform tema çalışmalarını henüz desteklemiyor. " + NOTHING], "This platform has no theme work endpoint yet (404 on POST /api/v1/theme-work).");
+      }
+      if (details.reason === "target_deleted") {
+        return out([`Çalışmanın${name} teması silinmiş; bu çalışmaya devam edilemez. ${NOTHING}`, `  Yeni bir çalışma başlat:  ${startCommand}`], "The work's theme was deleted (not_found, target_deleted).");
+      }
+      return out([`Çalışma bulunamadı${handle ? `: ${handle}` : ""}. Tanıtıcıyı (wk_…) kontrol et. ${NOTHING}`], "No such work on this site (not_found).");
+    case "work_forbidden":
+      return details.reason === "revoked"
+        ? out([`Bu bağlantının çalışmaya erişimi iptal edilmiş. ${NOTHING}`, "  Çalışmaya panelden devam edebilir ya da yeni bir çalışma başlatabilirsin."], "This credential's access to the work was revoked (work_forbidden).")
+        : out([`Bu çalışma başka bir bağlantıya ait (başka bir API anahtarı ya da yapay zekâ bağlantısı başlatmış). ${NOTHING}`, "  Kendi çalışmanı başlat ya da çalışmaya panelden devam et."], "The work belongs to another credential (work_forbidden).");
+    case "work_state_conflict": {
+      const now = typeof details.state === "string" ? ` Şu anki durumu: ${stateLabel(details.state)}.` : "";
+      return out([`Çalışma bu işlem için uygun durumda değil ya da bu sırada değişti.${now} ${NOTHING}`, `  Güncel durumu gör:  blocofy theme work status${name}`], "The work is not in a state that allows this, or it changed meanwhile (work_state_conflict).");
+    }
+    case "work_stale":
+      return out([`Site bu çalışma başladıktan sonra değişti; çalışma güncel değil. ${NOTHING}`, "  Hiçbir şeyin üzerine yazılmadı. Değişiklikleri panelde gözden geçir ya da yeni bir çalışma başlat."], "The live site changed since the work started (work_stale).");
+    case "work_sealed":
+      return out([`Çalışma incelemeye gönderildi; içeriği şu an değiştirilemez. ${NOTHING}`], "The work is sealed for review (work_sealed).");
+    case "work_revision_limit": {
+      const limit = Number.isInteger(details.limit) && details.limit > 0 ? details.limit : 20;
+      return out([`Bir çalışma en fazla ${limit} kez incelemeye gönderilebilir; yeni bir çalışma başlat. ${NOTHING}`, "  Bu çalışmanın incelemedeki hâli yine onaylanabilir ya da çalışma iptal edilebilir.", `  Yeni bir çalışma:  ${startCommand}`], `The work was sent for review its maximum number of times (${limit}); start a new work (work_revision_limit).`);
+    }
+    case "work_not_publishable":
+      return out([`Bu tema bir çalışma kopyası; doğrudan yayınlanamaz. Çalışmayı incelemeye gönder ve onay iste. ${NOTHING}`, `  Yayın için onay iste:  blocofy theme work request-approval${name || " <wk_…>"}`], "A theme work's copy is never published directly; ask for its approval (work_not_publishable).");
+    case "conflict":
+      return out([`Onay isteği bu sırada değişti (süresi dolmuş, kullanılmış ya da artık geçersiz olabilir). ${NOTHING}`, `  Güncel durumu gör:  blocofy theme work status${name}`], "The approval record changed meanwhile (conflict).");
+    case "live_effect_not_permitted":
+      return out([`Bu bağlantı canlı siteyi etkileyen bu işlemi yapamaz. ${NOTHING}`], "This connection may not touch the live site (live_effect_not_permitted).");
+    case "work_base_unavailable":
+      return out([`Sitenin yayında bir teması yok; çalışma başlatılamadı. ${NOTHING}`, "  Önce panelden bir temayı yayına al."], "The site has no live theme to start from (work_base_unavailable).");
+    case "quota_exceeded":
+      // `theme_bytes` is the site's technical theme space (not the plan): free space, never "upgrade". The legacy draft
+      // count (`theme_drafts`, a site not on theme space) is not tied to the plan either: remove a draft, never "upgrade".
+      return details.resource === "theme_drafts"
+        ? out([`Sitenin taslak tema sınırına ulaşıldı; çalışma başlatılamadı. ${NOTHING}`, "  Artık kullanmadığın bir taslak temayı sil (admin paneli → Tasarım)."], "The site's draft limit is reached (quota_exceeded, theme_drafts); remove a draft you no longer need.")
+        : out([`Tema alanı bu çalışma için yetmiyor (sitenin tema alanı dolu); çalışma başlatılamadı. ${NOTHING}`, "  Yer açmak için kullanmadığın taslak temaları (iptal edilmiş çalışmaların temaları dahil) tema kütüphanesinden sil (admin paneli → Tasarım); açık bir çalışmayı iptal etmek ayrıca onun için ayrılan yayın alanını bırakır. Sorun sürerse destek ekibine yaz."], "The site's theme space cannot hold this work (quota_exceeded, theme_bytes).");
+    case "capacity_unavailable":
+    case "resource_busy":
+      return out([`${code === "resource_busy" ? "Site şu anda meşgul (başka bir yazım sürüyor)" : "Platform şu an alanı doğrulayamadı"}; işlem yapılamadı. ${NOTHING}`, "  Biraz sonra aynı komutu tekrar çalıştır."], `Transient refusal (${code}); try again later.`);
+    case "idempotency_key_reuse":
+      return out([`Bu işlem anahtarı daha önce başka bir istekle kullanılmış. ${NOTHING}`, "  Yeni bir anahtarla dene ya da --idempotency-key vermeden çalıştır (her başlatma yeni anahtar üretir)."], "The idempotency key was used with another request (idempotency_key_reuse).");
+    case "idempotency_key_invalid":
+    case "idempotency_key_required":
+      return out([`İşlem anahtarı geçersiz (8-120 karakter: harf, rakam, . _ : -). ${NOTHING}`], `The idempotency key is ${code === "idempotency_key_required" ? "missing" : "malformed"} (${code}).`);
+    case "validation_failed":
+      return out([`İstek geçersiz${op === "start" ? " (çalışma açıklaması 1-120 karakter olmalı)" : ""}. ${NOTHING}`], "The request was refused as invalid (validation_failed).");
+    case "forbidden_scope":
+      return out([`API anahtarının bu işlem için yetkisi yok (${op === "status" || op === "resume" || op === "wait" ? "themes:read" : "themes:write"} gerekir). ${NOTHING}`, "  Panelde Ayarlar → API anahtarları'ndan uygun yetkili bir anahtar oluştur."], "The API key lacks the scope for this operation (forbidden_scope).");
+    case "invalid_key":
+    case "key_expired":
+      return out([`API anahtarı geçersiz ya da süresi dolmuş. ${NOTHING}`, "  Yeniden giriş yap:  blocofy login --api-key"], `The API key was refused (${code}).`);
+    default:
+      return null;
+  }
+}
+
+// ── the project's saved work (.blocofy/local.json, git-ignored) ─────────────────────────────────────────────
+
+const localPath = (root) => join(root, ".blocofy", "local.json");
+
+function readLocal(root) {
+  const p = localPath(root);
+  if (!existsSync(p)) return {};
+  try {
+    const v = JSON.parse(readFileSync(p, "utf8"));
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The work this project saved, when it belongs to the project's bound site: `{ handle, theme, intent }` | null. */
+export function readSavedWork(binding) {
+  if (!binding?.root) return null;
+  const w = readLocal(binding.root).theme_work;
+  if (!w || typeof w !== "object" || !isWorkHandle(w.handle)) return null;
+  if (w.site_id != null && String(w.site_id) !== String(binding.project?.site_id)) return null;
+  return { handle: w.handle, theme: typeof w.theme === "string" ? w.theme : null, intent: typeof w.intent === "string" ? w.intent : null };
+}
+
+/**
+ * Save (or, with `work: null`, forget) the project's work in `.blocofy/local.json`, keeping every other key (the
+ * context choice). Same rules as the binding writer: never through a symlink, a temp file renamed into place.
+ */
+export function saveWork(binding, work) {
+  if (!binding?.root) return false;
+  const dir = join(binding.root, ".blocofy");
+  const p = localPath(binding.root);
+  for (const path of [dir, p]) {
+    let st = null;
+    try {
+      st = lstatSync(path);
+    } catch {
+      st = null;
+    }
+    if (st?.isSymbolicLink()) return false;
+  }
+  if (!existsSync(dir)) return false;
+  const local = readLocal(binding.root);
+  if (work) {
+    local.theme_work = { handle: work.id, theme: work.theme ?? null, intent: work.intent ?? null, site_id: binding.project?.site_id ?? null, saved_at: new Date().toISOString() };
+  } else {
+    delete local.theme_work;
+  }
+  const tmp = join(dir, `.local.json.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    writeFileSync(tmp, JSON.stringify(local, null, 2) + "\n", { flag: "wx", mode: 0o644 });
+    renameSync(tmp, p);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+  return true;
+}

package/package.json

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