@blocofy/cli 0.7.0 → 0.9.0

package/lib/content-sync.mjs

@@ -1,14 +1,29 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, sep } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import {
+  PagesCliError,
+  checkLocalBatch,
+  folderConflicts,
+  classifyPageFile,
+  collectPageFiles,
+  pageFileSemanticKey,
+  pageFilePath,
+  resolveContained,
+  serializeV2PageFile,
+  stagedWrite,
+} from "./page-files.mjs";
+import { checkRelativePagePath, parsePageFilePath } from "./page-path-codec.mjs";
 
 /**
- * `blocofy pages pull/push` + `settings pull/push` (#119). CLI'nın yerel içerik
- * dosyalarını (`pages/<slug>.json` + `config/settings.json`) platformun
- * `/api/dev/content` endpoint'iyle çeker/gönderir. Tema KODU `theme pull/push`'a
- * gider; bu yalnız içerik+ayar. Güvenlik platformda: push yalnız mevcut sayfayı
- * günceller, yeni oluşturmaz, silmez.
+ * `blocofy pages pull/push/check/migrate-layout` + `settings pull/push` (#119, PS-19). Page files use the
+ * locale-aware layout (`pages/<locale>/index.json`, `pages/<locale>/routes/…/index.json`); the platform's
+ * `/api/dev/content` protocol v2 is required for every page operation. Tema KODU `theme pull/push`'a gider.
+ * Güvenlik platformda: push yalnız mevcut sayfayı günceller, yeni oluşturmaz, silmez.
  */
 
+export const PAGES_PROTOCOL_VERSION = 2;
+
 async function errorText(res) {
   const text = await res.text();
   try {
@@ -18,7 +33,9 @@ async function errorText(res) {
   }
 }
 
-/** scope "pages" → pages dizinindeki tüm .json (recursive); "settings" → config/settings.json. `{path: content}`. */
+const baseOf = (url) => url.replace(/\/+$/, "");
+
+/** scope "pages" → pages/**.json (lexical order, no symlinks); "settings" → config/settings.json. `{path: content}`. */
 export function readContentFiles(dir, scope) {
   const out = {};
   if (scope === "settings") {
@@ -26,52 +43,263 @@ export function readContentFiles(dir, scope) {
     if (existsSync(p)) out["config/settings.json"] = readFileSync(p, "utf8");
     return out;
   }
-  // pages
-  const pagesDir = join(dir, "pages");
-  if (!existsSync(pagesDir)) return out;
-  const walk = (current) => {
-    for (const name of readdirSync(current)) {
-      const full = join(current, name);
-      if (statSync(full).isDirectory()) {
-        walk(full);
-        continue;
+  const { files, errors } = collectPageFiles(dir);
+  if (errors.length > 0) throw new PagesCliError(errors[0].code, "Local page files cannot be read safely; nothing was sent.", { diagnostics: errors });
+  for (const [path, content] of files) out[path] = content;
+  return out;
+}
+
+/**
+ * The server's page capabilities, or `PAGES_SERVER_UPGRADE_REQUIRED`. An old server answers `scope=capabilities`
+ * as a full export without `protocol_version`; nothing is written either way.
+ */
+export async function probePagesServer({ url, token }) {
+  const res = await fetch(`${baseOf(url)}/api/dev/content?scope=capabilities`, { headers: { authorization: `Bearer ${token}` } });
+  if (!res.ok) throw new Error(await errorText(res));
+  const body = await res.json().catch(() => null);
+  if (body?.protocol_version !== PAGES_PROTOCOL_VERSION) {
+    throw new PagesCliError(
+      "PAGES_SERVER_UPGRADE_REQUIRED",
+      "This site's server does not support locale-aware page files yet. Nothing was changed; update the platform or use an older CLI.",
+    );
+  }
+  return { defaultLocale: body.default_locale, supportedLocales: body.supported_locales ?? [] };
+}
+
+/** Site içeriğini diske çek (pull). Pages require protocol v2; every path is contained and staged. */
+export async function pullContent({ dir, url, token, scope, writeFile }) {
+  const res = await fetch(`${baseOf(url)}/api/dev/content?scope=${encodeURIComponent(scope)}`, {
+    headers: { authorization: `Bearer ${token}` },
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    // Nothing is written on a non-2xx: an incomplete export (PAGES_EXPORT_INCOMPLETE) carries every finding and no files.
+    throw new PagesCliError(body?.code ?? "PAGES_PULL_FAILED", body?.error ?? `Pull failed (HTTP ${res.status}); nothing was written.`, {
+      status: res.status,
+      diagnostics: Array.isArray(body?.diagnostics) ? body.diagnostics : [],
+    });
+  }
+  const files = body?.files ?? {};
+  const wantsPages = scope !== "settings";
+  if (wantsPages && body?.protocol_version !== PAGES_PROTOCOL_VERSION) {
+    throw new PagesCliError(
+      "PAGES_SERVER_UPGRADE_REQUIRED",
+      "This site's server still uses the old page layout, which cannot keep languages apart. Nothing was written.",
+    );
+  }
+
+  const diagnostics = [...(body?.diagnostics ?? [])];
+  const errors = [];
+  const entries = [];
+  for (const path of Object.keys(files).sort()) {
+    const content = files[path];
+    if (path === "config/settings.json" && scope !== "pages") {
+      entries.push([path, content]);
+      continue;
+    }
+    const unsafe = checkRelativePagePath(path);
+    const parsed = unsafe ? null : parsePageFilePath(path);
+    if (unsafe || !parsed || (parsed.kind !== "canonical" && parsed.kind !== "hashed") || !wantsPages) {
+      errors.push({ level: "error", code: unsafe?.code ?? "PAGES_INVALID_PATH", message: `server sent an unexpected path (${unsafe?.reason ?? "not a canonical page path"})`, path });
+      continue;
+    }
+    const c = classifyPageFile(path, typeof content === "string" ? content : "", {});
+    if (!c.ok || c.layout !== "v2") {
+      errors.push({ level: "error", code: c.ok ? "PAGES_INVALID_PATH" : c.code, message: `server sent a page file that does not match its path (${c.ok ? "legacy payload" : c.message})`, path });
+      continue;
+    }
+    entries.push([path, content]);
+  }
+  if (errors.length > 0) throw new PagesCliError(errors[0].code, "The server response failed validation; nothing was written.", { diagnostics: errors });
+
+  // Local files this pull does not own: reported, never deleted or overwritten.
+  if (wantsPages && existsSync(dir)) {
+    const local = collectPageFiles(dir);
+    for (const e of local.errors) diagnostics.push({ ...e, level: "warning" });
+    const remote = new Set(Object.keys(files));
+    for (const [path, content] of local.files) {
+      if (remote.has(path)) continue;
+      const c = classifyPageFile(path, content, { defaultLocale: body.default_locale });
+      if (c.ok && c.layout === "legacy") {
+        diagnostics.push({
+          level: "warning",
+          code: "PAGES_STALE_LEGACY_FILE",
+          message: `${path} was not written by this pull. Canonical replacement: ${pageFilePath(c.locale, c.slug)}`,
+          path,
+          locale: c.locale,
+          slug: c.slug,
+        });
+      } else {
+        diagnostics.push({ level: "warning", code: "PAGES_STALE_FILE", message: `${path} is not on the site and was not written by this pull.`, path });
       }
-      if (!name.endsWith(".json")) continue;
-      const key = "pages/" + relative(pagesDir, full).split(sep).join("/");
-      out[key] = readFileSync(full, "utf8");
     }
-  };
-  walk(pagesDir);
-  return out;
+  }
+
+  const count = stagedWrite(fsRoot(dir), entries, writeFile ? { writeFile } : {});
+  return { count, diagnostics, defaultLocale: body?.default_locale ?? null };
+}
+
+function fsRoot(dir) {
+  mkdirSync(dir, { recursive: true });
+  return collectPageFiles(dir).root;
 }
 
-/** Yerel içeriği push'la. Yanıt: platform sonucu + gönderilen dosya sayısı. */
-export async function pushContent({ dir, url, token, scope }) {
-  const files = readContentFiles(dir, scope);
-  const base = url.replace(/\/+$/, "");
+/**
+ * Push. `settings` keeps the v1 body. `pages`: server capability probe → local preflight (nothing is sent on a
+ * local error) → `POST {protocol_version: 2, dry_run, files}`. The server preflights the whole batch again and
+ * writes nothing unless every file passes.
+ */
+export async function pushContent({ dir, url, token, scope, dryRun = false }) {
+  const base = baseOf(url);
+  if (scope === "settings") {
+    const files = readContentFiles(dir, scope);
+    const res = await fetch(`${base}/api/dev/content`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ files }),
+    });
+    if (!res.ok) throw new Error(await errorText(res));
+    return { ...(await res.json()), fileCount: Object.keys(files).length };
+  }
+
+  const server = await probePagesServer({ url, token });
+  const { files: local, errors } = collectPageFiles(dir);
+  if (errors.length > 0) throw new PagesCliError(errors[0].code, "Local page files cannot be read safely; nothing was sent.", { diagnostics: errors });
+  const localDiagnostics = checkLocalBatch(local.map(([p, c]) => classifyPageFile(p, c, server)));
+  const localErrors = localDiagnostics.filter((d) => d.level === "error");
+  if (localErrors.length > 0) {
+    throw new PagesCliError(localErrors[0].code, "Preflight failed locally; no pages were sent or changed.", { diagnostics: localDiagnostics });
+  }
+
+  const files = {};
+  for (const [path, content] of local) files[path] = content;
   const res = await fetch(`${base}/api/dev/content`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-    body: JSON.stringify({ files }),
+    body: JSON.stringify({ protocol_version: PAGES_PROTOCOL_VERSION, dry_run: dryRun, files }),
   });
-  if (!res.ok) throw new Error(await errorText(res));
-  return { ...(await res.json()), fileCount: Object.keys(files).length };
+  const body = await res.json().catch(() => null);
+  if (!res.ok || body?.ok !== true) {
+    throw new PagesCliError(body?.code ?? "PAGES_PUSH_FAILED", body?.error ?? `Push failed (HTTP ${res.status}).`, {
+      diagnostics: body?.diagnostics ?? [],
+      pages: body?.pages ?? null,
+      status: res.status,
+    });
+  }
+  return { ...body, fileCount: local.length };
 }
 
-/** Site içeriğini diske çek (pull). scope "pages" | "settings" | "all". Yazılan dosya sayısı. */
-export async function pullContent({ dir, url, token, scope }) {
-  const base = url.replace(/\/+$/, "");
-  const res = await fetch(`${base}/api/dev/content?scope=${encodeURIComponent(scope)}`, {
-    headers: { authorization: `Bearer ${token}` },
+/**
+ * `pages check`. Offline: path, JSON, format, layout and local duplicates. With `server` credentials it also
+ * resolves the default/supported locales and asks the server for a dry-run preflight (targets, documents).
+ */
+export async function checkPages({ dir, url, token }) {
+  const { files: local, errors } = collectPageFiles(dir);
+  const diagnostics = [...errors];
+  let server = null;
+  if (url && token) server = await probePagesServer({ url, token });
+  diagnostics.push(...checkLocalBatch(local.map(([p, c]) => classifyPageFile(p, c, server ?? {}))));
+
+  let plan = null;
+  if (server && !diagnostics.some((d) => d.level === "error")) {
+    try {
+      plan = await pushContent({ dir, url, token, scope: "pages", dryRun: true });
+      for (const d of plan.diagnostics ?? []) {
+        if (!diagnostics.some((x) => x.code === d.code && x.path === d.path)) diagnostics.push(d);
+      }
+    } catch (error) {
+      if (!(error instanceof PagesCliError)) throw error;
+      diagnostics.push(...(error.diagnostics.length ? error.diagnostics : [{ level: "error", code: error.code, message: error.message }]));
+    }
+  }
+  return { fileCount: local.length, diagnostics, plan, online: Boolean(server) };
+}
+
+/**
+ * `pages migrate-layout`. Plans a move for every legacy file whose (locale, slug) is proven, and refuses the
+ * whole migration — zero moves — on any error or ambiguity. `write: true` rewrites each file as v2 at its
+ * canonical path (contained, staged per file, verified) and only then removes the legacy file.
+ */
+export async function migrateLayout({ dir, url, token, write = false }) {
+  const { root, files: local, errors } = collectPageFiles(dir);
+  const diagnostics = [...errors];
+  const needsDefault = local.some(([, c]) => {
+    try {
+      const j = JSON.parse(c);
+      return j && typeof j === "object" && !("format_version" in j) && !("locale" in j);
+    } catch {
+      return false;
+    }
   });
-  if (!res.ok) throw new Error(await errorText(res));
-  const { files } = await res.json();
-  let count = 0;
-  for (const [path, content] of Object.entries(files ?? {})) {
-    const full = join(dir, ...path.split("/"));
-    mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, typeof content === "string" ? content : "");
-    count += 1;
+  let server = null;
+  if (url && token) server = await probePagesServer({ url, token });
+
+  const classified = local.map(([p, c]) => classifyPageFile(p, c, server ?? {}));
+  diagnostics.push(...checkLocalBatch(classified).filter((d) => d.code !== "PAGES_LEGACY_LAYOUT"));
+  if (needsDefault && !server) {
+    for (const c of classified) {
+      if (c.ok && c.localeSource === "unresolved") {
+        diagnostics.push({ level: "error", code: "PAGES_AMBIGUOUS_LAYOUT", message: "file has no locale and the site's default language is unknown offline; log in (blocofy login) or add \"locale\" to the file", path: c.path, slug: c.slug });
+      }
+    }
+  }
+
+  const byPath = new Map(classified.filter((c) => c.ok).map((c) => [c.path, c]));
+  const moves = [];
+  const claimed = new Map();
+  for (const c of classified) {
+    if (!c.ok || c.layout !== "legacy" || !c.locale) continue;
+    const to = pageFilePath(c.locale, c.slug);
+    const existing = byPath.get(to);
+    if (existing) {
+      if (pageFileSemanticKey(existing.parsed) === pageFileSemanticKey(c.parsed)) {
+        diagnostics.push({ level: "warning", code: "PAGES_DUPLICATE_EQUIVALENT", message: `${to} already holds the same content; ${c.path} was left in place (remove it yourself)`, path: c.path, locale: c.locale, slug: c.slug });
+        continue;
+      }
+      // checkLocalBatch has already reported the conflicting pair as PAGES_DUPLICATE_TARGET.
+      continue;
+    }
+    if (claimed.has(to)) {
+      diagnostics.push({ level: "error", code: "PAGES_DUPLICATE_TARGET", message: `${c.path} and ${claimed.get(to)} both move to ${to}`, path: c.path, locale: c.locale, slug: c.slug });
+      continue;
+    }
+    claimed.set(to, c.path);
+    moves.push({ from: c.path, to, locale: c.locale, slug: c.slug, content: serializeV2PageFile(c.parsed, c.locale) });
+  }
+  moves.sort((a, b) => (a.from < b.from ? -1 : 1));
+  const remaining = local.map(([p]) => p).filter((p) => !moves.some((m) => m.from === p));
+  diagnostics.push(...folderConflicts([...remaining, ...moves.map((m) => m.to)]));
+
+  const refused = diagnostics.some((d) => d.level === "error");
+  if (!write || refused) return { moves, moved: 0, diagnostics, refused };
+
+  // Every target validated before the first move.
+  for (const m of moves) {
+    const r = resolveContained(root, m.to);
+    if (r.error) {
+      diagnostics.push({ level: "error", code: r.error.code, message: r.error.reason, path: m.to });
+      return { moves, moved: 0, diagnostics, refused: true };
+    }
+    if (existsSync(r.target)) {
+      diagnostics.push({ level: "error", code: "PAGES_DUPLICATE_TARGET", message: "target appeared during migration", path: m.to });
+      return { moves, moved: 0, diagnostics, refused: true };
+    }
+  }
+  let moved = 0;
+  for (const m of moves) {
+    const verify = classifyPageFile(m.to, m.content, { defaultLocale: m.locale });
+    if (!verify.ok || verify.layout !== "v2") throw new PagesCliError("PAGES_INVALID_PATH", `internal: ${m.to} would not be a valid v2 file; stopped after ${moved} move(s).`);
+    const resolved = resolveContained(root, m.to);
+    if (resolved.error) throw new PagesCliError(resolved.error.code, `${m.to}: ${resolved.error.reason}; stopped after ${moved} move(s).`);
+    const { target } = resolved;
+    mkdirSync(dirname(target), { recursive: true });
+    const temp = `${target}.blocofy-tmp`;
+    writeFileSync(temp, m.content, { flag: "wx" });
+    renameSync(temp, target);
+    const legacy = resolveContained(root, m.from);
+    if (legacy.error) throw new PagesCliError(legacy.error.code, `${m.from}: ${legacy.error.reason}; stopped after ${moved} move(s).`);
+    rmSync(legacy.target);
+    moved += 1;
   }
-  return { count };
+  return { moves, moved, diagnostics, refused: false };
 }

package/lib/credentials.mjs

@@ -8,20 +8,43 @@ import { join } from "node:path";
  * variables (BLOCOFY_URL/BLOCOFY_TOKEN) take precedence over the file (CI/agents).
  * The token is stored in plaintext on disk (the usual dev-CLI pattern), so the file
  * is locked down to 0600.
+ *
+ * 0.8.0: the same file also holds the v1 API pair `{ apiUrl, apiKey }` written by
+ * `blocofy login --api-key`. The two pairs coexist: `saveCredentials(patch)` MERGES the
+ * patch into the existing JSON (an unreadable/corrupt file counts as `{}`), so an API login
+ * keeps the dev pair and a later dev login keeps the API pair. `loadCredentials()` (dev
+ * pair) is unchanged; `loadApiCredentials()` resolves the v1 pair (BLOCOFY_API_KEY +
+ * BLOCOFY_API_URL first, then the file).
  */
 
-const DIR = join(homedir(), ".blocofy");
-const FILE = join(DIR, "credentials.json");
+const DIR_NAME = ".blocofy";
+const FILE_NAME = "credentials.json";
+
+// Resolved per call (not at import): tests redirect HOME to a temp dir, and os.homedir()
+// honours $HOME on POSIX.
+function dir() {
+  return join(homedir(), DIR_NAME);
+}
 
 export function credentialsPath() {
-  return FILE;
+  return join(dir(), FILE_NAME);
 }
 
-/** Write URL + token with 0600 permissions. */
-export function saveCredentials({ url, token }) {
-  mkdirSync(DIR, { recursive: true, mode: 0o700 });
-  writeFileSync(FILE, JSON.stringify({ url, token }, null, 2) + "\n", { mode: 0o600 });
-  chmodSync(FILE, 0o600); // create-mode is ignored if the file already exists → enforce it
+function readExisting() {
+  try {
+    const data = JSON.parse(readFileSync(credentialsPath(), "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {}; // missing/corrupt → start clean
+  }
+}
+
+/** Merge `patch` into the credentials file and write it with 0600 permissions. */
+export function saveCredentials(patch) {
+  mkdirSync(dir(), { recursive: true, mode: 0o700 });
+  const merged = { ...readExisting(), ...patch };
+  writeFileSync(credentialsPath(), JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(credentialsPath(), 0o600); // create-mode is ignored if the file already exists → enforce it
 }
 
 /**
@@ -34,13 +57,32 @@ export function loadCredentials() {
   if (envUrl && envToken) {
     return { url: stripSlash(envUrl), token: envToken, source: "env" };
   }
-  try {
-    const data = JSON.parse(readFileSync(FILE, "utf8"));
-    if (data && typeof data.url === "string" && typeof data.token === "string") {
-      return { url: stripSlash(data.url), token: data.token, source: "file" };
-    }
-  } catch {
-    // missing/corrupt file → null
+  const data = readExisting();
+  if (typeof data.url === "string" && typeof data.token === "string") {
+    return { url: stripSlash(data.url), token: data.token, source: "file" };
+  }
+  return null;
+}
+
+/**
+ * Resolve the v1 API pair: BLOCOFY_API_KEY + BLOCOFY_API_URL (BOTH required — with only one
+ * set this throws and does NOT fall through to the file, so a half-configured CI job fails
+ * loudly instead of silently using a developer's file), then the file's `{ apiUrl, apiKey }`.
+ * Returns `{ apiUrl, apiKey, source }` or null. The thrown message never contains the key.
+ */
+export function loadApiCredentials() {
+  const envKey = process.env.BLOCOFY_API_KEY;
+  const envUrl = process.env.BLOCOFY_API_URL;
+  if (envKey && envUrl) {
+    return { apiUrl: stripSlash(envUrl), apiKey: envKey, source: "env" };
+  }
+  if (envKey || envUrl) {
+    const missing = envKey ? "BLOCOFY_API_URL" : "BLOCOFY_API_KEY";
+    throw new Error(`${missing} is not set — BLOCOFY_API_KEY and BLOCOFY_API_URL must be set together (the credentials file is not consulted while either is set).`);
+  }
+  const data = readExisting();
+  if (typeof data.apiUrl === "string" && typeof data.apiKey === "string") {
+    return { apiUrl: stripSlash(data.apiUrl), apiKey: data.apiKey, source: "file" };
   }
   return null;
 }

package/lib/media-uses.mjs

@@ -0,0 +1,82 @@
+/**
+ * v1 client for a page's localized-media decisions (D3, CLI 0.8.0):
+ *   GET  /api/v1/pages/{id}/media-uses   (pages:read)   → PageMediaUsesView | PageMediaUsesNotApplicable
+ *   POST /api/v1/pages/{id}/media-uses   (pages:write)  → DecidePageMediaUsesOutput
+ *
+ * Plan: multisite-cms docs/architecture/plans/2026-09-16-d3-page-media-use-public-surfaces.md §4.5–4.7.
+ *
+ * Authentication is a `blcf_live_…` API key (Bearer). The dev `bcf_…` token is NOT accepted for v1.
+ *
+ * NO RETRIES. A decision batch is applied atomically on the server but a lost response is only
+ * safe to replay with the SAME idempotency keys, which is the caller's decision, not this
+ * client's — so a 5xx/network failure surfaces once and the command exits 1. A 4xx is a server
+ * REFUSAL (`CliRefusal`): the `{ error }` envelope is carried verbatim for the command to print
+ * as JSON on stderr with exit code 2.
+ */
+
+export const API_KEY_PREFIX = "blcf_live_";
+export const DEFAULT_API_URL = "https://app.blocofy.com";
+
+/** v1 accepts ONLY a live API key. Never echo the key back in a message. */
+export function isValidApiKey(key) {
+  return typeof key === "string" && key.startsWith(API_KEY_PREFIX) && key.length > API_KEY_PREFIX.length;
+}
+
+/** A 4xx response from v1: `status` + the server's `error` object ({ code, message, details? }). */
+export class CliRefusal extends Error {
+  constructor(status, error) {
+    super(`HTTP ${status} ${error?.code ?? ""}: ${error?.message ?? ""}`.trim());
+    this.name = "CliRefusal";
+    this.status = status;
+    this.error = error;
+  }
+}
+
+function mediaUsesUrl(apiUrl, page) {
+  return `${String(apiUrl).replace(/\/+$/, "")}/api/v1/pages/${encodeURIComponent(page)}/media-uses`;
+}
+
+async function request(method, { apiUrl, apiKey, page }, body) {
+  const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  const res = await fetch(mediaUsesUrl(apiUrl, page), {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  if (res.ok) {
+    if (json === null) 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);
+  }
+  // 5xx (no retry) — the message never includes the request headers.
+  const detail = json?.error?.message ?? (text ? text.slice(0, 200) : "");
+  throw new Error(`HTTP ${res.status}${detail ? `: ${detail}` : ""}`);
+}
+
+/** GET the page's media-use view (the newest draft's `revision{id,version}` is inside). */
+export function fetchPageMediaUses({ apiUrl, apiKey, page }) {
+  return request("GET", { apiUrl, apiKey, page });
+}
+
+/**
+ * POST a decision batch. The body is exactly `{ expected_revision_id, expected_version, decisions }`
+ * — items are sent as given (idempotency keys are the caller's responsibility).
+ */
+export function decidePageMediaUses({ apiUrl, apiKey, page, expectedRevisionId, expectedVersion, decisions }) {
+  return request(
+    "POST",
+    { apiUrl, apiKey, page },
+    { expected_revision_id: expectedRevisionId, expected_version: expectedVersion, decisions },
+  );
+}