@blocofy/cli 0.14.0 → 0.16.0

package/lib/secret-store.mjs

@@ -1,22 +1,35 @@
 import { spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { dirname } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
 /**
  * CF-T1 (contract C1) — where credential SECRETS live. `credentials.json` only records which store holds a
- * context's secret (`secret: { store: "file" | "keychain" }`); the value itself is in one of:
+ * context's secret (`secret: { store: "file" | "keychain" | "dpapi" | "secret-service" }`); the value itself is in:
  *
- *   file      `~/.blocofy/secrets.json` (0600, atomic tmp+rename) `{ "<context>": { dev_token, api_key } }`.
- *   keychain  macOS Keychain via the `security` binary: service `blocofy-cli`, account `<context>:dev|api`.
- *             Opt-in only (`BLOCOFY_SECRET_STORE=keychain` or `login --keychain`); other platforms → error.
+ *   file      `~/.blocofy/secrets.json` (0600, atomic tmp+rename) `{ "<context>": { dev_token, api_key, oauth_tokens } }`.
+ *   keychain  macOS Keychain via the `security` binary: service `blocofy-cli`, account `<context>:dev|api|oauth`.
+ *             Opt-in for a pasted token (`BLOCOFY_SECRET_STORE=keychain` or `login --keychain`); other platforms → error.
  *
- * Both stores expose `get(context, kind)`, `set(context, kind, value)`, `remove(context)` with kind `dev|api`.
- * No method ever puts a secret into an error message.
+ * ADR-0014 §5.4 (wave P4) — the browser login's token set (kind `oauth`: one JSON string `{access_token,
+ * refresh_token, expires_at}`) lives in the OS secure store by default (`oauthSecretStore`):
+ *
+ *   macOS    keychain        (above)
+ *   Windows  dpapi           `%APPDATA%\blocofy\secrets.dpapi`: each value protected with DPAPI (user scope) by
+ *                            PowerShell `ConvertFrom-SecureString`; the secret goes in on stdin, never argv
+ *   Linux    secret-service  libsecret's `secret-tool` (stdin), when a DBus session is present
+ *   any      file            only when chosen explicitly (`--insecure-storage` / `BLOCOFY_SECRET_STORE=file`) and
+ *                            announced; an unavailable OS store is an error, never a silent plaintext downgrade
+ *
+ * Every store exposes `get(context, kind)`, `set(context, kind, value)`, `remove(context, kind?)` with kind
+ * `dev|api|oauth`. No method ever puts a secret into an error message.
  */
 
 export const KEYCHAIN_SERVICE = "blocofy-cli";
-const FIELD = { dev: "dev_token", api: "api_key" };
+const FIELD = { dev: "dev_token", api: "api_key", oauth: "oauth_tokens" };
+/** Every store name a context may record (`secret: { store }`). */
+export const STORE_NAMES = ["file", "keychain", "dpapi", "secret-service"];
 
 export class SecretStoreError extends Error {
   constructor(code, message) {
@@ -125,9 +138,163 @@ export function createKeychainSecretStore({ exec = defaultExec, platform = proce
   };
 }
 
+const storeAccount = (context, kind) => `${context}:${kind}`;
+
+/** Windows: the protect/unprotect scripts. The value travels on stdin both ways; argv carries only the script. */
+const PS_PROTECT =
+  "$s=[Console]::In.ReadToEnd(); $ss=ConvertTo-SecureString -String $s -AsPlainText -Force; [Console]::Out.Write((ConvertFrom-SecureString -SecureString $ss))";
+const PS_UNPROTECT =
+  "$e=[Console]::In.ReadToEnd().Trim(); $ss=ConvertTo-SecureString -String $e; $b=[Runtime.InteropServices.Marshal]::SecureStringToBSTR($ss); " +
+  "try { [Console]::Out.Write([Runtime.InteropServices.Marshal]::PtrToStringBSTR($b)) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($b) }";
+const powershell = (exec, script, input) => exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { input });
+
+/** The DPAPI file's default place: `%APPDATA%\blocofy\secrets.dpapi` (user scope). */
+export function dpapiPath(env = process.env) {
+  return join(env.APPDATA || join(homedir(), "AppData", "Roaming"), "blocofy", "secrets.dpapi");
+}
+
+/**
+ * Windows DPAPI adapter: the file maps `<context>:<kind>` to a DPAPI-protected blob (useless to another user or
+ * machine). An unreadable blob is an error (SECRET_STORE_FAILED), never "not logged in".
+ */
+export function createDpapiSecretStore({ exec = defaultExec, platform = process.platform, filePath = dpapiPath() } = {}) {
+  const ensure = () => {
+    if (platform !== "win32") throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "The DPAPI secret store is only available on Windows.");
+  };
+  const readAll = () => {
+    let raw;
+    try {
+      raw = readFileSync(filePath, "utf8");
+    } catch (error) {
+      if (error?.code === "ENOENT") return {};
+      throw error;
+    }
+    try {
+      const data = JSON.parse(raw);
+      if (data && typeof data === "object" && !Array.isArray(data)) return data;
+    } catch {
+      /* fall through */
+    }
+    throw new SecretStoreError("CREDENTIALS_CORRUPT", `The protected secrets file is not valid JSON: ${filePath}. Nothing was written.`);
+  };
+  return {
+    name: "dpapi",
+    get(context, kind) {
+      ensure();
+      const blob = readAll()[storeAccount(context, kind)];
+      if (typeof blob !== "string" || !blob) return null;
+      const r = powershell(exec, PS_UNPROTECT, blob);
+      if (r.status !== 0 || r.error) throw new SecretStoreError("SECRET_STORE_FAILED", `Could not read the secret from the Windows protected store (${filePath}); it was not used.`);
+      return r.stdout || null;
+    },
+    set(context, kind, value) {
+      ensure();
+      const r = powershell(exec, PS_PROTECT, String(value));
+      const blob = String(r.stdout ?? "").trim();
+      if (r.status !== 0 || r.error || !blob) throw new SecretStoreError("SECRET_STORE_FAILED", "Could not protect the secret with Windows DPAPI. Nothing was saved.");
+      const data = readAll();
+      data[storeAccount(context, kind)] = blob;
+      writeJsonAtomic(filePath, data);
+    },
+    remove(context, kind = null) {
+      ensure();
+      const data = readAll();
+      let changed = false;
+      for (const k of kind ? [kind] : Object.keys(FIELD)) {
+        if (storeAccount(context, k) in data) {
+          delete data[storeAccount(context, k)];
+          changed = true;
+        }
+      }
+      if (changed) writeJsonAtomic(filePath, data);
+    },
+  };
+}
+
+/** Linux Secret Service (libsecret) adapter through `secret-tool`; the secret goes in on stdin. */
+export function createSecretServiceStore({ exec = defaultExec, platform = process.platform } = {}) {
+  const ensure = () => {
+    if (platform !== "linux") throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "The Secret Service store is only used on Linux.");
+  };
+  const attrs = (context, kind) => ["service", KEYCHAIN_SERVICE, "account", storeAccount(context, kind)];
+  return {
+    name: "secret-service",
+    get(context, kind) {
+      ensure();
+      const r = exec("secret-tool", ["lookup", ...attrs(context, kind)]);
+      if (r.error && r.error.code === "ENOENT") throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", "`secret-tool` (libsecret) is not installed; the saved login cannot be read.");
+      if (r.status !== 0) return null;
+      const v = String(r.stdout ?? "").replace(/\r?\n$/, "");
+      return v || null;
+    },
+    set(context, kind, value) {
+      ensure();
+      const r = exec("secret-tool", ["store", `--label=Blocofy CLI (${context})`, ...attrs(context, kind)], { input: String(value) });
+      if (r.status !== 0 || r.error) throw new SecretStoreError("SECRET_STORE_FAILED", `Could not save the secret to the Secret Service (secret-tool exit ${r.status}). Nothing was saved.`);
+    },
+    remove(context, kind = null) {
+      ensure();
+      for (const k of kind ? [kind] : Object.keys(FIELD)) exec("secret-tool", ["clear", ...attrs(context, k)]);
+    },
+  };
+}
+
 /** `store` name → adapter. Unknown names are a usage error. */
-export function secretStoreFor(name, { filePath, exec, platform } = {}) {
+export function secretStoreFor(name, { filePath, exec, platform, dpapiPath: dpapiFile } = {}) {
   if (name === "file") return createFileSecretStore(filePath);
   if (name === "keychain") return createKeychainSecretStore({ exec, platform });
-  throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", `Unknown secret store "${name}" (use "file" or "keychain").`);
+  if (name === "dpapi") return createDpapiSecretStore({ exec, platform, ...(dpapiFile ? { filePath: dpapiFile } : {}) });
+  if (name === "secret-service") return createSecretServiceStore({ exec, platform });
+  throw new SecretStoreError("SECRET_STORE_UNAVAILABLE", `Unknown secret store "${name}" (use ${STORE_NAMES.map((n) => `"${n}"`).join(", ")}).`);
+}
+
+/** Where a store keeps secrets, in words (login output names it). */
+export function storeLabel(name) {
+  switch (name) {
+    case "keychain":
+      return "macOS Keychain";
+    case "dpapi":
+      return "Windows DPAPI-protected file (OS protected file)";
+    case "secret-service":
+      return "Linux Secret Service (libsecret)";
+    case "file":
+      return "plain file ~/.blocofy/secrets.json (0600) — chosen explicitly";
+    default:
+      return String(name);
+  }
+}
+
+const OS_STORE = { darwin: "keychain", win32: "dpapi", linux: "secret-service" };
+
+/** Is the Secret Service usable here? A DBus session and an installed `secret-tool`. */
+function secretServiceAvailable(env, exec) {
+  if (!env.DBUS_SESSION_BUS_ADDRESS) return false;
+  const r = exec("secret-tool", ["--help"]);
+  return !(r.error && r.error.code === "ENOENT");
+}
+
+/**
+ * ADR-0014 §5.4 — the store for the browser login's tokens. `insecure` (`--insecure-storage`) or
+ * `BLOCOFY_SECRET_STORE=file` choose the 0600 file (`explicit: true`; the caller announces it); another
+ * `BLOCOFY_SECRET_STORE` value names an OS store, which must be this OS's. Otherwise this platform's OS store; none
+ * available → SECRET_STORE_UNAVAILABLE (never a silent plaintext downgrade).
+ */
+export function oauthSecretStore({ platform = process.platform, env = process.env, insecure = false, exec = defaultExec } = {}) {
+  const unavailable = (why) =>
+    new SecretStoreError(
+      "SECRET_STORE_UNAVAILABLE",
+      `${why} The CLI login is never saved in a plain file automatically. To keep it in ~/.blocofy/secrets.json (0600) instead, choose that explicitly: blocofy login --insecure-storage (or BLOCOFY_SECRET_STORE=file). Nothing was saved.`,
+    );
+  const requested = env.BLOCOFY_SECRET_STORE;
+  if (insecure || requested === "file") return { name: "file", explicit: true };
+  if (requested !== undefined && requested !== "") {
+    if (!STORE_NAMES.includes(requested)) throw unavailable(`BLOCOFY_SECRET_STORE="${requested}" is not a known store (${STORE_NAMES.join(", ")}).`);
+    if (OS_STORE[platform] !== requested) throw unavailable(`The "${requested}" store is not available on this operating system (${platform}).`);
+  }
+  const name = OS_STORE[platform];
+  if (!name) throw unavailable(`No OS secure store is supported on this operating system (${platform}).`);
+  if (name === "secret-service" && !secretServiceAvailable(env, exec)) {
+    throw unavailable("No Secret Service is available (it needs a desktop DBus session and `secret-tool` from libsecret).");
+  }
+  return { name, explicit: false };
 }

package/lib/target.mjs

@@ -3,7 +3,7 @@ import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import { dirname, join, resolve } from "node:path";
 
 import { fetchWithRetry } from "./http.mjs";
-import { API_KEY_PREFIX } from "./media-uses.mjs";
+import { API_KEY_PREFIX, isValidApiKey } from "./media-uses.mjs";
 
 /**
  * CF-T1/T2 (contract C2) — project binding + target resolution + remote identity verification.
@@ -108,7 +108,7 @@ function lstatOrNull(p) {
  * before the first write); each file is written to a fresh temp file in the same directory (`wx`, 0644) and
  * renamed into place. `staleLocal: true` (link) removes a `local.json` that an env-context binding does not own.
  */
-export function writeBinding(root, { site, platformOrigin, contextName, staleLocal = false }) {
+export function writeBinding(root, { site, platformOrigin, contextName, staleLocal = false, profile = null, ignore = ["local.json"] }) {
   const d = join(root, PROJECT_DIR);
   const refuse = (path, what) => {
     throw new TargetError("TARGET_BINDING_INVALID", `${path} ${what}; the project binding was not written.`, { binding: path });
@@ -122,10 +122,12 @@ export function writeBinding(root, { site, platformOrigin, contextName, staleLoc
     if (st.isSymbolicLink() || !st.isDirectory()) refuse(d, "is not a real directory");
   }
   const project = { schema_version: 1, site_id: site.id, site_slug: site.slug ?? null, platform_origin: origin(platformOrigin) };
+  // ADR-0014 §5.6 step 6 — additive: the profile the project was set up with (an older CLI ignores it; the server decides).
+  if (profile && typeof profile.id === "string") project.profile = { id: profile.id, version: profile.version ?? null };
   const writes = [["project.json", JSON.stringify(project, null, 2) + "\n"]];
   const ownsLocal = contextName && contextName !== ENV_CONTEXT;
   if (ownsLocal) writes.push(["local.json", JSON.stringify({ context: contextName }, null, 2) + "\n"]);
-  writes.push([".gitignore", "local.json\n"]);
+  writes.push([".gitignore", ignore.join("\n") + "\n"]);
   for (const name of ["project.json", "local.json", ".gitignore"]) {
     const f = lstatOrNull(join(d, name));
     if (f && (f.isSymbolicLink() || !f.isFile())) refuse(join(d, name), "is a symlink or not a regular file");
@@ -352,7 +354,7 @@ export function assertCredentialTypes({ resolved, secrets }) {
   const refuse = (kind, secret) => {
     const env = Boolean(resolved.env);
     const where = kind === "dev" ? (env ? "BLOCOFY_TOKEN" : `The dev token of context "${resolved.name}"`) : env ? "BLOCOFY_API_KEY" : `The API key of context "${resolved.name}"`;
-    const other = kind === "dev" ? secret.startsWith("blcf_") : secret.startsWith(DEV_TOKEN_PREFIX);
+    const other = kind === "dev" ? secret.startsWith("blcf_") : secret.startsWith(DEV_TOKEN_PREFIX) || secret.startsWith("bcf2_");
     const holds = kind === "dev" ? (other ? "holds a v1 API key (blcf_…)" : "is not a dev token") : other ? "holds a theme dev token (bcf_…)" : "is not a v1 API key";
     const expected = kind === "dev" ? `a theme dev token starts with ${DEV_TOKEN_PREFIX}` : `a v1 API key starts with ${API_KEY_PREFIX}`;
     const fix = env
@@ -369,8 +371,10 @@ export function assertCredentialTypes({ resolved, secrets }) {
       1,
     );
   };
-  if (resolved.context.dev && typeof secrets.devToken === "string" && !secrets.devToken.startsWith(DEV_TOKEN_PREFIX)) refuse("dev", secrets.devToken);
-  if (resolved.context.api && typeof secrets.apiKey === "string" && !(secrets.apiKey.startsWith(API_KEY_PREFIX) && secrets.apiKey.length > API_KEY_PREFIX.length)) refuse("api", secrets.apiKey);
+  // A CLI login's context carries its own short-lived token in both places; the refresh layer vouches for it.
+  if (resolved.oauth) return;
+  if (resolved.context.dev && typeof secrets.devToken === "string" && !(secrets.devToken.startsWith(DEV_TOKEN_PREFIX) || secrets.devToken.startsWith("bcf2_"))) refuse("dev", secrets.devToken);
+  if (resolved.context.api && typeof secrets.apiKey === "string" && !isValidApiKey(secrets.apiKey)) refuse("api", secrets.apiKey);
 }
 
 // ── remote identity ─────────────────────────────────────────────────────────────────────────────────────────
@@ -386,7 +390,17 @@ async function getJson(fetchImpl, url, secret, retry = {}) {
     return { error: `unreachable (${error?.name === "TimeoutError" ? "timeout" : "network error"})` };
   }
   const text = await res.text().catch(() => "");
-  if (!res.ok) return { error: `HTTP ${res.status}` };
+  if (!res.ok) {
+    // ADR-0014: keep the server's refusal code (v1 `{error:{code}}`, renderer `{error, code}`) — e.g. audience_mismatch.
+    let code = null;
+    try {
+      const j = JSON.parse(text);
+      code = typeof j?.error?.code === "string" ? j.error.code : typeof j?.code === "string" ? j.code : null;
+    } catch {
+      code = null;
+    }
+    return { error: `HTTP ${res.status}${code ? ` ${code}` : ""}`, serverCode: code };
+  }
   try {
     return { body: JSON.parse(text) };
   } catch {
@@ -394,15 +408,15 @@ async function getJson(fetchImpl, url, secret, retry = {}) {
   }
 }
 
-function unverified(what, url, reason) {
-  return new TargetError("TARGET_UNVERIFIED", `Could not verify the target site via ${what} (${reason}). Nothing was sent or written.`, { endpoint: url, reason });
+function unverified(what, url, reason, serverCode = null) {
+  return new TargetError("TARGET_UNVERIFIED", `Could not verify the target site via ${what} (${reason}). Nothing was sent or written.`, { endpoint: url, reason, ...(serverCode ? { server_code: serverCode } : {}) });
 }
 
 /** `GET {url}/api/dev/whoami` → `{ site, platformOrigin, liveThemeId }` or TARGET_UNVERIFIED. */
 export async function verifyDev({ url, token, fetchImpl = globalThis.fetch, retry = {} }) {
   const endpoint = `${url.replace(/\/+$/, "")}/api/dev/whoami`;
   const r = await getJson(fetchImpl, endpoint, token, retry);
-  if (r.error) throw unverified("/api/dev/whoami", endpoint, r.error);
+  if (r.error) throw unverified("/api/dev/whoami", endpoint, r.error, r.serverCode);
   const site = r.body?.site;
   if (!isObj(site) || !(typeof site.id === "string" || Number.isFinite(site.id)) || typeof site.slug !== "string") {
     throw unverified("/api/dev/whoami", endpoint, "malformed response (no site id/slug)");
@@ -414,7 +428,7 @@ export async function verifyDev({ url, token, fetchImpl = globalThis.fetch, retr
 export async function verifyApi({ url, apiKey, fetchImpl = globalThis.fetch, retry = {} }) {
   const endpoint = `${url.replace(/\/+$/, "")}/api/v1/ping`;
   const r = await getJson(fetchImpl, endpoint, apiKey, retry);
-  if (r.error) throw unverified("/api/v1/ping", endpoint, r.error);
+  if (r.error) throw unverified("/api/v1/ping", endpoint, r.error, r.serverCode);
   const site = r.body?.site;
   if (!isObj(site) || !(typeof site.id === "string" || Number.isFinite(site.id))) {
     throw unverified("/api/v1/ping", endpoint, "malformed response (no site id)");

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,8 +67,14 @@ 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;
+  // ADR-0014: a credential refusal's details (e.g. credential_reapproval_required's due date) for the CLI's words.
+  if (body && typeof body.details === "object" && body.details !== null) err.serverDetails = body.details;
   return err;
 }
 
@@ -89,6 +95,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 +168,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 +177,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 +677,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 +690,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;
       },
     });