@blocofy/cli 0.7.0 → 0.9.0

package/README.md

@@ -29,12 +29,67 @@ 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 pages pull [dir] [--strict]
+                          # Download published pages, one folder per language:
+                          # pages/<locale>/index.json and pages/<locale>/routes/<path>/index.json.
+                          # Old-layout files are reported, never deleted or overwritten. If the site
+                          # cannot export every page, nothing is written (PAGES_EXPORT_INCOMPLETE).
+blocofy pages push [dir] [--dry-run] [--strict]
+                          # Update EXISTING pages only. Every file is checked first; any invalid file,
+                          # duplicate target or folder/locale mismatch changes NO page. An error after
+                          # that check may leave some pages applied: the per-file result is printed,
+                          # exit 1, and re-running is safe. --dry-run checks on the server, writes nothing.
+blocofy pages check [dir] [--strict]
+                          # Offline file/path/layout checks; with login also the server dry run.
+blocofy pages migrate-layout [dir] [--dry-run | --write] [--strict]
+                          # Move old-layout files (pages/<slug>.json) to language folders. Any
+                          # ambiguity or conflict moves nothing (exit 1).
 blocofy --version
 blocofy --help
 ```
 
 ## Changelog
 
+- **0.9.0** — Locale-aware page files for multilingual sites (needs a platform with page file protocol 2;
+  against an older server page commands stop with `PAGES_SERVER_UPGRADE_REQUIRED` and write nothing).
+  `pages pull` writes `pages/<locale>/index.json` and `pages/<locale>/routes/<path>/index.json`, so the same
+  URL in two languages no longer shares one file. `pages push` preflights the whole directory and the server
+  refuses the batch before any write on an invalid file, duplicate target or folder/locale mismatch; a
+  failure after preflight prints the per-file result. New `pages check`, `pages push --dry-run` and
+  `pages migrate-layout [--dry-run | --write]`. Pull validates every server path, never follows symlinks,
+  never writes outside the target directory and stages its writes (0.8.0 could write a server-supplied
+  `../` path outside it). An incomplete export prints every reason with `PAGES_EXPORT_INCOMPLETE` and writes
+  nothing. Limits: 500 page files, 2 MiB per file, 4 MiB total.
+- **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 +149,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
 
@@ -107,7 +165,7 @@ A theme is a directory of files grouped by top-level folder:
 | `block/` | Repeatable pieces used inside sections |
 | `partial/` | Shared snippets (header/footer, …) |
 | `asset/` | CSS and static files (`theme.css`) |
-| `pages/<slug>.json` | Page content (`/` → `pages/index.json`) |
+| `pages/<locale>/index.json`, `pages/<locale>/routes/<path>/index.json` | Page content, one folder per language (`blocofy pages pull/push/check/migrate-layout`). The old `pages/<slug>.json` layout is still read, with a warning |
 | `config/settings.json` | Theme settings + color schemes |
 | `config/settings_schema.json` | Theme settings panel schema (synced with `pull`/`push`) |
 

package/bin/blocofy.mjs

@@ -9,17 +9,20 @@
  * 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 { checkPages, migrateLayout, pullContent, pushContent } from "../lib/content-sync.mjs";
+import { PagesCliError, formatDiagnostic } from "../lib/page-files.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,14 +35,21 @@ 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"],
   themePublish: ["instance"],
   themeRename: ["name"],
   content: [],
+  pagesPull: ["strict"],
+  pagesPush: ["dry-run", "strict"],
+  pagesCheck: ["strict"],
+  pagesMigrate: ["dry-run", "write", "strict"],
 };
 function parseArgsOrExit(rest, known) {
   const parsed = parseArgs(rest, new Set([...known, "help", "version"]));
@@ -66,6 +76,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.
@@ -113,10 +130,47 @@ Usage
       Show the live theme, page distribution per instance, drafts, and a health flag
       (ok / live_instance_empty / pages_split). Run before/after publishing.
 
-  blocofy pages pull [dir] / pages push [dir]
-      pull: download published pages → pages/<slug>.json.
-      push: write pages/*.json to the site. Updates EXISTING pages only —
-            never creates or deletes a page; unchanged pages are skipped.
+  blocofy pages pull [dir] [--strict]
+      Download published pages, one folder per language:
+        pages/<locale>/index.json                 the home page ("/")
+        pages/<locale>/routes/<path>/index.json   every other page ("/about" → routes/about/index.json)
+      Files from the old layout (pages/<slug>.json) are reported, never deleted or overwritten.
+      If the site cannot export every published page, nothing is written, every reason is
+      printed (PAGES_EXPORT_INCOMPLETE) and the exit code is 1 (--strict: warnings also exit 1).
+
+  blocofy pages push [dir] [--dry-run] [--strict]
+      Write pages/**.json to the site. Updates EXISTING pages only — never creates or
+      deletes a page; unchanged pages are skipped. Every file is checked first: if any
+      file is invalid, two files point at the same page, or a folder's language does not
+      match the file's "locale", NO page is changed. If publishing then stops unexpectedly
+      (PAGES_APPLY_FAILED or another publish error), some pages may already be applied: the per-file
+      result printed is authoritative, the exit code is 1, and running the push again is safe.
+      --dry-run: check on the server, write nothing.
+      Needs a platform that supports language folders (else PAGES_SERVER_UPGRADE_REQUIRED).
+
+  blocofy pages check [dir] [--strict]
+      Check page files. Offline: paths, JSON, layout, duplicates. Logged in: also the
+      site's languages and the server-side dry run. Exit 1 on errors (--strict: warnings too).
+
+  blocofy pages migrate-layout [dir] [--dry-run | --write] [--strict]
+      Move old-layout files (pages/<slug>.json) to language folders. --dry-run (default)
+      prints the plan; --write moves only proven files. Any ambiguity or conflict: nothing
+      is moved, exit 1. Files without "locale" use the site's default language (login needed).
+
+  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 +183,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 +204,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() : "";
 
@@ -451,26 +561,123 @@ async function themePush(rest) {
   }
 }
 
-async function contentPush(scope, rest) {
-  const { positionals } = parseArgsOrExit(rest, KNOWN.content);
+/** PS-19 — print platform/CLI findings; returns the exit code they imply. */
+function reportPageDiagnostics(diagnostics, { strict = false } = {}) {
+  for (const d of diagnostics) (d.level === "error" ? console.error : console.warn)(formatDiagnostic(d));
+  const errors = diagnostics.filter((d) => d.level === "error").length;
+  const warnings = diagnostics.length - errors;
+  return errors > 0 || (strict && warnings > 0) ? 1 : 0;
+}
+
+function exitForPagesError(error) {
+  if (error instanceof PagesCliError) {
+    if (error.diagnostics?.length) reportPageDiagnostics(error.diagnostics);
+    else console.error(`error [${error.code}]:\n    ${error.message}`);
+    // The stable top code always prints, after the individual findings it summarises.
+    if (error.diagnostics?.length) console.error(`\nerror [${error.code}]:\n    ${error.message}`);
+    if (Array.isArray(error.pages) && error.pages.length) {
+      console.error("Per-file result:");
+      for (const p of error.pages) console.error(`  ${p.outcome ?? p.action}  ${p.path}`);
+    }
+    process.exit(1);
+  }
+  console.error(error?.message ?? error);
+  process.exit(1);
+}
+
+function localeLabel(p) {
+  return `${p.locale} ${p.slug}`;
+}
+
+async function pagesPush(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.pagesPush);
   const dir = resolve(positionals[0] ?? process.cwd());
   if (!existsSync(dir)) {
     console.error(`Directory not found: ${dir}`);
     process.exit(1);
   }
   const creds = requireCreds();
-  const result = await pushContent({ dir, url: creds.url, token: creds.token, scope });
-  if (scope === "settings") {
-    console.log(
-      `Settings push: ${result.settingsUpdated ? "theme settings updated" : "theme settings unchanged"}, ` +
-        `${result.schemesUpserted} color scheme(s) upserted (${result.fileCount} file).`,
-    );
+  const dryRun = Boolean(flags["dry-run"]);
+  const result = await pushContent({ dir, url: creds.url, token: creds.token, scope: "pages", dryRun });
+  const code = reportPageDiagnostics(result.diagnostics ?? [], { strict: Boolean(flags.strict) });
+  const pages = result.pages ?? [];
+  const count = (k, v) => pages.filter((p) => p[k] === v).length;
+  const warnings = (result.diagnostics ?? []).filter((d) => d.level === "warning").length;
+  if (dryRun) {
+    console.log(`Preflight passed: ${count("action", "publish")} updates, ${count("action", "draft")} drafts, ${count("action", "unchanged")} unchanged, 0 conflicts, ${warnings} warning(s).`);
+    console.log("Dry run only; no pages were changed.");
   } else {
+    for (const p of pages) if (p.outcome !== "unchanged") console.log(`  ${p.outcome}  ${localeLabel(p)}  (${p.path})`);
     console.log(
-      `Pages push: ${result.pagesUpdated} updated, ${result.pagesSkipped} skipped ` +
+      `Pages push: ${result.pagesUpdated} updated, ${result.pagesSkipped} skipped, ${warnings} warning(s) ` +
         `(only existing pages are updated — none created or deleted).`,
     );
   }
+  process.exit(code);
+}
+
+async function pagesPull(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.pagesPull);
+  const dir = resolve(positionals[0] ?? process.cwd());
+  const creds = requireCreds();
+  const { count, diagnostics } = await pullContent({ dir, url: creds.url, token: creds.token, scope: "pages" });
+  const code = reportPageDiagnostics(diagnostics, { strict: Boolean(flags.strict) });
+  console.log(`Downloaded ${count} page file(s) → ${dir}`);
+  process.exit(code);
+}
+
+async function pagesCheck(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.pagesCheck);
+  const dir = resolve(positionals[0] ?? process.cwd());
+  if (!existsSync(dir)) {
+    console.error(`Directory not found: ${dir}`);
+    process.exit(1);
+  }
+  const creds = loadCredentials();
+  const online = Boolean(creds?.url && creds?.token);
+  const r = await checkPages({ dir, ...(online ? { url: creds.url, token: creds.token } : {}) });
+  const code = reportPageDiagnostics(r.diagnostics, { strict: Boolean(flags.strict) });
+  const errors = r.diagnostics.filter((d) => d.level === "error").length;
+  console.log(`Checked ${r.fileCount} page file(s) ${r.online ? "(with the site's languages and a server dry run)" : "(offline — log in to also check against the site)"}: ${errors} error(s), ${r.diagnostics.length - errors} warning(s).`);
+  process.exit(code);
+}
+
+async function pagesMigrate(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.pagesMigrate);
+  if (flags["dry-run"] && flags.write) {
+    console.error("Use either --dry-run or --write, not both. Nothing was moved.");
+    process.exit(1);
+  }
+  const dir = resolve(positionals[0] ?? process.cwd());
+  if (!existsSync(dir)) {
+    console.error(`Directory not found: ${dir}`);
+    process.exit(1);
+  }
+  const creds = loadCredentials();
+  const online = Boolean(creds?.url && creds?.token);
+  const write = Boolean(flags.write);
+  const r = await migrateLayout({ dir, write, ...(online ? { url: creds.url, token: creds.token } : {}) });
+  const code = reportPageDiagnostics(r.diagnostics, { strict: Boolean(flags.strict) });
+  for (const m of r.moves) console.log(`  ${write && !r.refused ? "moved" : "move"}  ${m.from} → ${m.to}`);
+  if (r.refused) console.error(`Migration refused; no files were moved.`);
+  else if (write) console.log(`Moved ${r.moved} file(s) to the language-folder layout.`);
+  else console.log(`${r.moves.length} file(s) would move. Dry run only; run with --write to move them.`);
+  process.exit(r.refused ? 1 : code);
+}
+
+async function contentPush(scope, rest) {
+  const { positionals } = parseArgsOrExit(rest, KNOWN.content);
+  const dir = resolve(positionals[0] ?? process.cwd());
+  if (!existsSync(dir)) {
+    console.error(`Directory not found: ${dir}`);
+    process.exit(1);
+  }
+  const creds = requireCreds();
+  const result = await pushContent({ dir, url: creds.url, token: creds.token, scope });
+  console.log(
+    `Settings push: ${result.settingsUpdated ? "theme settings updated" : "theme settings unchanged"}, ` +
+      `${result.schemesUpserted} color scheme(s) upserted (${result.fileCount} file).`,
+  );
 }
 
 async function contentPull(scope, rest) {
@@ -478,7 +685,131 @@ async function contentPull(scope, rest) {
   const dir = resolve(positionals[0] ?? process.cwd());
   const creds = requireCreds();
   const { count } = await pullContent({ dir, url: creds.url, token: creds.token, scope });
-  console.log(`Downloaded ${count} ${scope === "settings" ? "settings" : "page"} file(s) → ${dir}`);
+  console.log(`Downloaded ${count} settings 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) {
@@ -755,16 +1086,18 @@ 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);
-    process.exit(1);
-  });
+  pagesPull(rest.slice(1)).catch(exitForPagesError);
 } else if (first === "pages" && rest[0] === "push") {
-  contentPush("pages", rest.slice(1)).catch((error) => {
-    console.error(error?.message ?? error);
-    process.exit(1);
-  });
+  pagesPush(rest.slice(1)).catch(exitForPagesError);
+} else if (first === "pages" && rest[0] === "check") {
+  pagesCheck(rest.slice(1)).catch(exitForPagesError);
+} else if (first === "pages" && rest[0] === "migrate-layout") {
+  pagesMigrate(rest.slice(1)).catch(exitForPagesError);
 } else if (first === "settings" && rest[0] === "pull") {
   contentPull("settings", 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", "strict", "write"]);
 
 /**
  * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`