@blocofy/cli 0.7.0 → 0.8.0

package/README.md

@@ -29,12 +29,42 @@ blocofy theme push [dir]  # Write the local theme to a DRAFT by default (create/
 blocofy theme rename <handle> <new name>
                           # Rename a theme (label only). Works on any theme, live included.
                           # Handle from the panel theme card or `blocofy status`.
+blocofy login --api-key [--api-url <url>]
+                          # Save a v1 API key (blcf_live_…) for the `pages media-*` commands.
+                          # The flag takes NO value: the key is typed into a hidden prompt, so
+                          # it never lands in argv or shell history. Non-interactive shells use
+                          # BLOCOFY_API_KEY + BLOCOFY_API_URL instead (no prompt, nothing
+                          # written without them). --api-url defaults to https://app.blocofy.com.
+blocofy pages media-uses <page-handle> [--json]
+                          # List a page's localized-media decisions on its newest draft
+                          # (v1 API, pages:read) with the draft revision id/version.
+blocofy pages media-decide <page-handle> --decisions <file.json>
+                          [--expected-revision-id <n> --expected-version <n>] [--json]
+                          # Apply the file's { "decisions": [...] } (max 20) to the draft
+                          # atomically (v1 API, pages:write). Without the --expected-* pair
+                          # the CLI GETs the draft first and uses its current revision;
+                          # items without idempotency_key get a random UUID. Exit 0 applied
+                          # (or "No changes" when already recorded), 1 usage/auth/network/5xx
+                          # (no retry), 2 server refusal (4xx) — {error} JSON on stderr.
 blocofy --version
 blocofy --help
 ```
 
 ## Changelog
 
+- **0.8.0** — Page media decisions over the public v1 API: `pages media-uses <page-handle>` lists a
+  page's localized-media decisions on its newest draft, and `pages media-decide <page-handle>
+  --decisions <file.json>` applies a batch of decisions to that draft atomically (all or nothing;
+  a replayed batch answers "No changes"). Both use a **v1 API key** (`blcf_live_…`, scopes
+  `pages:read` / `pages:write`) — the `bcf_` dev token is not accepted. `blocofy login --api-key`
+  stores the key from a **hidden prompt**; the flag deliberately takes no value so the key never
+  enters argv or shell history, and a non-interactive shell without `BLOCOFY_API_KEY` +
+  `BLOCOFY_API_URL` exits without writing. The API pair lives next to the dev pair in
+  `~/.blocofy/credentials.json` (still 0600): logging in one way keeps the other. Exit codes for
+  the new commands: 0 success, 1 usage/auth/network/5xx (no automatic retry), 2 server refusal
+  (4xx, with the server's `{error}` JSON on stderr). Existing commands and the dev-token flow are
+  unchanged.
+
 - **0.7.0** — `theme push --prune`: files that exist on the platform but no longer exist locally are
   removed. Until now a push merged remote-only files back into the upload, so a file deleted locally
   stayed on the theme forever. The list is printed before anything is written; pruning the LIVE theme
@@ -94,7 +124,10 @@ editor — without affecting your published theme. Save a file and **every open
 the draft from the theme editor when you're ready.
 
 Credentials come from `~/.blocofy/credentials.json` (written by `blocofy login`) or the
-`BLOCOFY_URL` + `BLOCOFY_TOKEN` environment variables (for CI/automation).
+`BLOCOFY_URL` + `BLOCOFY_TOKEN` environment variables (for CI/automation). The v1 API commands
+(`pages media-uses`, `pages media-decide`) use a separate `blcf_live_…` key from the same file
+(written by `blocofy login --api-key`) or `BLOCOFY_API_KEY` + `BLOCOFY_API_URL` — both variables
+together; with only one set the CLI fails instead of falling back to the file.
 
 ## Theme structure
 

package/bin/blocofy.mjs

@@ -9,17 +9,19 @@
  * livereload. No monorepo required.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 import { parseArgs } from "../lib/args.mjs";
 import { pullContent, pushContent } from "../lib/content-sync.mjs";
-import { credentialsPath, loadCredentials, saveCredentials } from "../lib/credentials.mjs";
+import { credentialsPath, loadApiCredentials, loadCredentials, saveCredentials } from "../lib/credentials.mjs";
 import { startDevServer } from "../lib/dev-server.mjs";
 import { readLocalTemplates } from "../lib/local-theme.mjs";
+import { CliRefusal, DEFAULT_API_URL, decidePageMediaUses, fetchPageMediaUses, isValidApiKey } from "../lib/media-uses.mjs";
 import { githubNote, retryNotice, statusLine, syncScopeNote } from "../lib/messages.mjs";
+import { promptSecret } from "../lib/secret-prompt.mjs";
 import { diffTheme, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, fetchWhoami, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
 import { isAffirmative, livePushDecision, resolvePushMode } from "../lib/confirm.mjs";
 import { hyperlink, openUrl } from "../lib/term.mjs";
@@ -32,8 +34,11 @@ const args = process.argv.slice(2);
 // bayrak YAZIMSIZ çıkışla reddedilir (eskiden sonraki token'ı değer olarak yutup hedef dizini sessizce
 // kaydırıyordu). `--confirm` ve `--dry` belgelenmemiş ama gerçek bayraklardır; `--dry` (theme dev'in
 // sunucu-başlatmama kancası) `--dry-run`'dan (sunucu-tarafı doğrulama) FARKLIDIR, alias değildir.
+// 0.8.0: `login --api-key` DEĞERSİZ bayraktır (parser'da boolean) — sır gizli prompt'tan ya da
+// BLOCOFY_API_KEY'den gelir, argv'ye asla girmez. `pages media-uses` / `media-decide` v1 API komutlarıdır.
 const KNOWN = {
-  login: ["url", "token"],
+  login: ["url", "token", "api-key", "api-url"],
+  pages: ["decisions", "expected-revision-id", "expected-version", "json"],
   themePull: ["draft", "instance"],
   themePush: ["diff", "draft", "instance", "name", "live", "yes", "confirm", "dry-run", "validate", "idempotency-key", "prune"],
   themeDev: ["port", "dry", "no-sync", "name"],
@@ -66,6 +71,13 @@ Usage
       Save your platform URL + dev token to ~/.blocofy/credentials.json.
       Get a token from the admin panel → Settings → Theme CLI tokens.
 
+  blocofy login --api-key [--api-url <url>]
+      Save a v1 API key (blcf_live_…) for the \`pages media-*\` commands. The key is read
+      from a HIDDEN prompt — the flag takes no value, so the key never lands in your shell
+      history. Kept alongside the dev token in the same credentials file.
+        --api-url <url>  API origin (default https://app.blocofy.com)
+      Non-interactive shells: set BLOCOFY_API_KEY + BLOCOFY_API_URL instead.
+
   blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
       Start a dev server and print 3 auto-reloading views — Local, live-domain
       Preview, and the theme Editor. Press l / p / e to open each, q to quit.
@@ -118,6 +130,21 @@ Usage
       push: write pages/*.json to the site. Updates EXISTING pages only —
             never creates or deletes a page; unchanged pages are skipped.
 
+  blocofy pages media-uses <page-handle> [--json]
+      List a page's localized-media decisions on its newest DRAFT (v1 API, pages:read).
+      Prints the draft's revision id/version needed by media-decide. --json: raw response.
+
+  blocofy pages media-decide <page-handle> --decisions <file.json>
+                             [--expected-revision-id <n> --expected-version <n>] [--json]
+      Apply one or more media decisions to the page's draft atomically (v1 API, pages:write).
+      The file is { "decisions": [ { path, facet, decision, target_asset?, alt?, caption?,
+      decorative?, idempotency_key?, witness? } ] } (max 20). Without the two --expected-*
+      flags the CLI first GETs the draft and uses its current revision id/version; items
+      without an idempotency_key get a random UUID.
+      Exit codes: 0 applied (or "No changes" when every item was already recorded);
+      1 usage/auth/network/5xx (no retry); 2 the server refused (4xx) — the {error} JSON
+      is printed to stderr.
+
   blocofy settings pull [dir] / settings push [dir]
       Download / upload config/settings.json (theme tokens/settings + color schemes).
 
@@ -129,8 +156,12 @@ Examples
   blocofy theme pull && blocofy theme dev
   blocofy theme push && blocofy theme publish
   blocofy status
+  blocofy login --api-key
+  blocofy pages media-uses pg_abc123 --json
+  blocofy pages media-decide pg_abc123 --decisions decisions.json
 
 Auth: ~/.blocofy/credentials.json (from \`login\`), or BLOCOFY_URL + BLOCOFY_TOKEN env vars.
+v1 API (pages media-*): \`login --api-key\`, or BLOCOFY_API_KEY + BLOCOFY_API_URL env vars.
 The CLI does not build assets — bring your own (npm/Vite/Tailwind); the platform serves
 plain Liquid + static assets.`);
 }
@@ -146,8 +177,60 @@ async function promptValid(rl, question, normalize, valid, hint, tries = 3) {
   process.exit(1);
 }
 
+/**
+ * `blocofy login --api-key [--api-url <url>]` — v1 API key login (0.8.0, D3 §4.7).
+ * The key is NEVER taken from argv: a hidden prompt on a TTY, BLOCOFY_API_KEY otherwise.
+ * Non-TTY without the env var → message + exit 1, nothing written (fail-closed). No message
+ * printed by this function ever contains the key (not even a prefix).
+ */
+async function loginApiKey(flags, positionals) {
+  if (positionals.length > 0 || flags.url !== undefined || flags.token !== undefined) {
+    console.error("`login --api-key` takes no value and no --url/--token: the API key is read from a hidden prompt (or BLOCOFY_API_KEY). Nothing was written.");
+    process.exit(1);
+  }
+  let apiUrl;
+  if (typeof flags["api-url"] === "string") apiUrl = normalizeUrl(flags["api-url"]);
+  else if (process.env.BLOCOFY_API_URL) apiUrl = normalizeUrl(process.env.BLOCOFY_API_URL);
+  else apiUrl = DEFAULT_API_URL;
+  if (!isValidUrl(apiUrl)) {
+    console.error("Invalid --api-url — must be a valid http(s):// URL. Nothing was written.");
+    process.exit(1);
+  }
+
+  let apiKey = null;
+  if (process.stdin.isTTY) {
+    apiKey = await promptSecret("API key (blcf_live_…, hidden): ");
+    if (apiKey === null) {
+      console.error("Cancelled. Nothing was written.");
+      process.exit(1);
+    }
+    apiKey = apiKey.trim();
+  } else if (process.env.BLOCOFY_API_KEY) {
+    apiKey = process.env.BLOCOFY_API_KEY.trim();
+  } else {
+    console.error("Non-interactive shell: `login --api-key` needs a terminal for the hidden prompt. Set BLOCOFY_API_KEY (+ BLOCOFY_API_URL) instead. Nothing was written.");
+    process.exit(1);
+  }
+  if (!isValidApiKey(apiKey)) {
+    console.error("Invalid API key — a v1 key starts with blcf_live_ (a bcf_ dev token is not accepted for the v1 API). Nothing was written.");
+    process.exit(1);
+  }
+
+  saveCredentials({ apiUrl, apiKey });
+  console.log(`✓ API key saved → ${credentialsPath()} (API: ${apiUrl})`);
+  console.log("Next: blocofy pages media-uses <page-handle>");
+}
+
 async function login(rest) {
-  const { flags } = parseArgsOrExit(rest, KNOWN.login);
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.login);
+  if (flags["api-key"] || flags["api-url"] !== undefined) {
+    if (!flags["api-key"]) {
+      console.error("--api-url is only used with --api-key. Nothing was written.");
+      process.exit(1);
+    }
+    await loginApiKey(flags, positionals);
+    return;
+  }
   let url = typeof flags.url === "string" ? normalizeUrl(flags.url) : "";
   let token = typeof flags.token === "string" ? flags.token.trim() : "";
 
@@ -481,6 +564,130 @@ async function contentPull(scope, rest) {
   console.log(`Downloaded ${count} ${scope === "settings" ? "settings" : "page"} file(s) → ${dir}`);
 }
 
+/** Resolve the v1 API pair (blcf_live_ key only) or exit 1 with guidance. Never prints the key. */
+function requireApiCreds() {
+  let creds;
+  try {
+    creds = loadApiCredentials();
+  } catch (error) {
+    console.error(error?.message ?? error);
+    process.exit(1);
+  }
+  if (!creds) {
+    console.error("API key required: run `blocofy login --api-key` (or set BLOCOFY_API_KEY + BLOCOFY_API_URL). The dev token (bcf_) is not accepted for the v1 API.");
+    process.exit(1);
+  }
+  if (!isValidApiKey(creds.apiKey)) {
+    console.error(`The stored API key (${creds.source}) is not a v1 key — it must start with blcf_live_. Run \`blocofy login --api-key\`.`);
+    process.exit(1);
+  }
+  return creds;
+}
+
+/** v1 refusal (4xx) → {error} JSON on stderr, exit 2; anything else → message, exit 1. */
+function exitForApiError(error) {
+  if (error instanceof CliRefusal) {
+    console.error(JSON.stringify({ error: error.error }));
+    process.exit(2);
+  }
+  console.error(error?.message ?? error);
+  process.exit(1);
+}
+
+function printMediaUsesView(view) {
+  if (view.applicable === false) {
+    console.log(`Page ${view.page?.id}: media decisions not applicable (${view.reason}).`);
+    return;
+  }
+  const uses = Array.isArray(view.uses) ? view.uses : [];
+  console.log(`Page ${view.page?.id} — draft revision ${view.revision?.id} v${view.revision?.version} — ${view.locale} ← ${view.source_locale}`);
+  console.log(`${view.counts?.total ?? uses.length} use(s), ${view.counts?.blocked ?? 0} blocked`);
+  for (const u of uses) {
+    const marks = [u.stale ? "stale" : null, u.blocks ? "BLOCKS" : null, u.editable ? null : "read-only"].filter(Boolean);
+    const extra = marks.length ? ` [${marks.join(", ")}]` : "";
+    const reasons = Array.isArray(u.reasons) && u.reasons.length ? ` — ${u.reasons.join(", ")}` : "";
+    console.log(`  ${u.decision.padEnd(9)} ${u.path} (${u.facet}, ${u.kind})${extra}${reasons}`);
+  }
+}
+
+async function pagesMediaUses(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.pages);
+  const page = positionals[0];
+  if (!page) {
+    console.error("Usage: blocofy pages media-uses <page-handle> [--json]");
+    process.exit(1);
+  }
+  const { apiUrl, apiKey } = requireApiCreds();
+  const view = await fetchPageMediaUses({ apiUrl, apiKey, page });
+  if (flags.json) console.log(JSON.stringify(view, null, 2));
+  else printMediaUsesView(view);
+}
+
+function parseExpected(flags, name) {
+  const raw = flags[name];
+  if (raw === undefined) return null;
+  const n = Number(raw);
+  if (typeof raw !== "string" || !Number.isSafeInteger(n) || n < 0) {
+    console.error(`--${name} must be a non-negative integer.`);
+    process.exit(1);
+  }
+  return n;
+}
+
+async function pagesMediaDecide(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.pages);
+  const page = positionals[0];
+  const file = typeof flags.decisions === "string" ? resolve(flags.decisions) : null;
+  if (!page || !file) {
+    console.error("Usage: blocofy pages media-decide <page-handle> --decisions <file.json> [--expected-revision-id <n> --expected-version <n>] [--json]");
+    process.exit(1);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    console.error(`Cannot read decisions file ${file}: ${error?.message ?? error}`);
+    process.exit(1);
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.decisions) || parsed.decisions.length === 0) {
+    console.error(`Decisions file must be { "decisions": [ ... ] } with at least one item: ${file}`);
+    process.exit(1);
+  }
+  let expectedRevisionId = parseExpected(flags, "expected-revision-id");
+  let expectedVersion = parseExpected(flags, "expected-version");
+  if ((expectedRevisionId === null) !== (expectedVersion === null)) {
+    console.error("--expected-revision-id and --expected-version must be given together (or both omitted to use the current draft).");
+    process.exit(1);
+  }
+
+  const { apiUrl, apiKey } = requireApiCreds();
+  if (expectedRevisionId === null) {
+    const view = await fetchPageMediaUses({ apiUrl, apiKey, page });
+    if (view.applicable === false) {
+      console.error(`Page ${page}: media decisions not applicable (${view.reason}). Nothing was written.`);
+      process.exit(1);
+    }
+    expectedRevisionId = view.revision.id;
+    expectedVersion = view.revision.version;
+  }
+  const decisions = parsed.decisions.map((item) =>
+    item && typeof item === "object" && typeof item.idempotency_key !== "string" ? { ...item, idempotency_key: randomUUID() } : item,
+  );
+
+  const out = await decidePageMediaUses({ apiUrl, apiKey, page, expectedRevisionId, expectedVersion, decisions });
+  if (flags.json) {
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+  if (out.written === false) {
+    console.log("No changes — the decisions were already recorded (replay).");
+    return;
+  }
+  const applied = Array.isArray(out.applied) ? out.applied : [];
+  console.log(`✓ Applied ${applied.length} decision(s) → draft revision ${out.revision?.id} v${out.revision?.version}`);
+  for (const a of applied) console.log(`  ${a.decision.padEnd(9)} ${a.path} (${a.facet})${a.replayed ? " [replayed]" : ""}`);
+}
+
 async function themeDev(rest) {
   const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeDev);
   const themeDir = resolve(positionals[0] ?? process.cwd());
@@ -755,6 +962,10 @@ if (first === "--version" || first === "-v") {
     console.error(error?.message ?? error);
     process.exit(1);
   });
+} else if (first === "pages" && rest[0] === "media-uses") {
+  pagesMediaUses(rest.slice(1)).catch(exitForApiError);
+} else if (first === "pages" && rest[0] === "media-decide") {
+  pagesMediaDecide(rest.slice(1)).catch(exitForApiError);
 } else if (first === "pages" && rest[0] === "pull") {
   contentPull("pages", rest.slice(1)).catch((error) => {
     console.error(error?.message ?? error);

package/lib/args.mjs

@@ -4,8 +4,11 @@
  * (tema dizini) sanılmaz. Boolean flag'ler sonraki token'ı YUTMAZ.
  */
 
-/** Sonraki token'ı değer olarak almayan flag'ler. */
-const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version"]);
+/**
+ * Sonraki token'ı değer olarak almayan flag'ler. 0.8.0: `api-key` de boolean'dır — `login --api-key`
+ * gizli prompt açar; `--api-key <değer>` sözdizimi bilerek YOKTUR (sır argv'ye ve shell geçmişine girmez).
+ */
+const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json"]);
 
 /**
  * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`

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 },
+  );
+}

package/lib/secret-prompt.mjs

@@ -0,0 +1,39 @@
+/**
+ * Hidden (non-echoing) secret prompt for `blocofy login --api-key` (0.8.0, D3 §4.7).
+ *
+ * Reads one line from a TTY in raw mode so the key never echoes to the terminal (and so it is
+ * never in argv or shell history — the flag takes no value). On a non-TTY stdin it resolves
+ * `null` WITHOUT reading anything: the caller must then use BLOCOFY_API_KEY or fail closed.
+ * Backspace edits, Enter finishes, Ctrl-C / Ctrl-D (empty) cancel with `null`. Raw mode is
+ * always restored.
+ */
+export function promptSecret(question, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY || typeof input.setRawMode !== "function") return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let buffer = "";
+    const finish = (value) => {
+      input.removeListener("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\n");
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const ch of String(chunk)) {
+        if (ch === "\r" || ch === "\n") return finish(buffer);
+        if (ch === "") return finish(null); // Ctrl-C
+        if (ch === "") return finish(buffer.length ? buffer : null); // Ctrl-D
+        if (ch === "" || ch === "\b") {
+          buffer = buffer.slice(0, -1);
+          continue;
+        }
+        buffer += ch;
+      }
+    };
+    output.write(question);
+    input.setRawMode(true);
+    input.setEncoding("utf8");
+    input.resume();
+    input.on("data", onData);
+  });
+}

package/package.json

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