@blocofy/cli 0.8.0 → 0.9.0

package/README.md

@@ -46,12 +46,37 @@ blocofy pages media-decide <page-handle> --decisions <file.json>
                           # 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;
@@ -140,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

@@ -15,7 +15,8 @@ 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 { 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";
@@ -45,6 +46,10 @@ const KNOWN = {
   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"]));
@@ -125,10 +130,32 @@ 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).
@@ -534,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) {
@@ -561,7 +685,7 @@ 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. */
@@ -967,15 +1091,13 @@ if (first === "--version" || first === "-v") {
 } 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

@@ -8,7 +8,7 @@
  * 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"]);
+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`

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/page-files.mjs

@@ -0,0 +1,308 @@
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+
+import {
+  PAGE_FILE_FORMAT_VERSION,
+  PageFileError,
+  canonicalizeLocaleCode,
+  checkPageSlug,
+  checkRelativePagePath,
+  isCanonicalLayoutPath,
+  legacyPageFilePath,
+  pageFilePath,
+  parsePageFilePath,
+} from "./page-path-codec.mjs";
+
+/**
+ * PS-19 — local page files: what a file is (mirror of the platform's `page-files/file-format.ts`), how the CLI
+ * reads and writes them without leaving the target directory, and how findings are printed.
+ */
+
+export const PAGE_META_KEYS = ["title", "seo_title", "seo_description", "og_image", "canonical_url"];
+const NULLABLE_STRING_KEYS = [...PAGE_META_KEYS, "status", "template"];
+const V2_KEY_ORDER = ["format_version", "slug", "title", "status", "seo_title", "seo_description", "og_image", "canonical_url", "locale", "template", "data"];
+
+/** A refusal the CLI prints with its stable code. `diagnostics` are platform-shaped findings. */
+export class PagesCliError extends Error {
+  constructor(code, message, { diagnostics = [], pages = null, status = null } = {}) {
+    super(message);
+    this.name = "PagesCliError";
+    this.code = code;
+    this.diagnostics = diagnostics;
+    this.pages = pages;
+    this.status = status;
+  }
+}
+
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isCanonicalLocale = (v) => typeof v === "string" && canonicalizeLocaleCode(v) === v;
+
+/**
+ * Classify one page file. `ctx.defaultLocale` null means offline: a legacy file with no locale key is accepted
+ * with `locale: null` (the server decides). `ctx.supportedLocales` omitted → not checked.
+ */
+export function classifyPageFile(path, content, ctx = {}) {
+  const fail = (code, message, extra = {}) => ({ ok: false, path, code, message, ...extra });
+  const unsafe = checkRelativePagePath(path);
+  if (unsafe) return fail(unsafe.code, unsafe.reason);
+  let json;
+  try {
+    json = JSON.parse(content);
+  } catch {
+    return fail("PAGES_INVALID_JSON", "file is not valid JSON");
+  }
+  if (!isPlainObject(json)) return fail("PAGES_INVALID_JSON", "file must contain a JSON object");
+  const isV2 = Object.prototype.hasOwnProperty.call(json, "format_version");
+  if (isV2 && json.format_version !== PAGE_FILE_FORMAT_VERSION) {
+    return fail("PAGES_UNSUPPORTED_FORMAT", `format_version ${JSON.stringify(json.format_version)} is not supported`);
+  }
+  const slugReason = checkPageSlug(json.slug);
+  if (slugReason) return fail("PAGES_INVALID_SLUG", `slug ${JSON.stringify(json.slug)}: ${slugReason}`);
+  const slug = json.slug;
+  if (!isPlainObject(json.data)) return fail("PAGES_INVALID_JSON", "data must be a JSON object", { slug });
+  for (const key of NULLABLE_STRING_KEYS) {
+    if (key in json && json[key] !== null && typeof json[key] !== "string") return fail("PAGES_INVALID_JSON", `${key} must be a string or null`, { slug });
+  }
+  const hasLocale = Object.prototype.hasOwnProperty.call(json, "locale");
+  let locale = null;
+  let localeSource;
+  if (hasLocale) {
+    if (!isCanonicalLocale(json.locale)) return fail("PAGES_INVALID_LOCALE", `locale ${JSON.stringify(json.locale)} is not a canonical locale code`, { slug });
+    locale = json.locale;
+    localeSource = "file";
+  } else if (isV2) {
+    return fail("PAGES_INVALID_LOCALE", "format_version 2 files must carry an explicit locale", { slug });
+  } else {
+    locale = ctx.defaultLocale ?? null;
+    localeSource = ctx.defaultLocale ? "default" : "unresolved";
+  }
+
+  if (isV2) {
+    const parsed = parsePageFilePath(path);
+    if (parsed.kind === "invalid") return fail(parsed.code, parsed.reason, { locale, slug });
+    if (parsed.kind === "other") return fail("PAGES_INVALID_PATH", `format_version 2 files must use the canonical layout (${pageFilePath(locale, slug)})`, { locale, slug });
+    if (parsed.locale !== locale) return fail("PAGES_LOCALE_PATH_MISMATCH", `folder locale "${parsed.locale}" does not match file locale "${locale}"`, { locale, slug });
+    const expected = pageFilePath(locale, slug);
+    if (expected !== path) return fail("PAGES_INVALID_PATH", `slug ${JSON.stringify(slug)} belongs at ${expected}`, { locale, slug });
+  } else if (isCanonicalLayoutPath(path) || legacyPageFilePath(slug) !== path) {
+    return fail("PAGES_AMBIGUOUS_LAYOUT", `file has no format_version but is not at its legacy location (${legacyPageFilePath(slug)})`, { ...(locale ? { locale } : {}), slug });
+  }
+  if (locale && ctx.supportedLocales && !ctx.supportedLocales.includes(locale)) {
+    return fail("PAGES_UNSUPPORTED_LOCALE", `locale "${locale}" is not published on this site`, { locale, slug });
+  }
+  return { ok: true, path, layout: isV2 ? "v2" : "legacy", locale, slug, localeSource, parsed: json };
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (isPlainObject(value)) return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+export function pageFileSemanticKey(parsed) {
+  const meta = {};
+  for (const key of PAGE_META_KEYS) meta[key] = typeof parsed[key] === "string" ? parsed[key] : null;
+  return stableStringify({ meta, data: parsed.data ?? null });
+}
+
+/** A legacy payload re-serialised as a v2 file: `format_version` first, explicit locale, unknown keys kept. */
+export function serializeV2PageFile(parsed, locale) {
+  const out = {};
+  const source = { ...parsed, format_version: PAGE_FILE_FORMAT_VERSION, locale };
+  for (const key of V2_KEY_ORDER) if (key in source) out[key] = source[key];
+  for (const key of Object.keys(parsed)) if (!(key in out)) out[key] = parsed[key];
+  return JSON.stringify(out, null, 2) + "\n";
+}
+
+/**
+ * Local files checked for errors that only the local tree can have: duplicates between legacy and v2 files for
+ * the same (locale, slug). Files whose locale is unresolved offline are left to the server.
+ */
+export function checkLocalBatch(classified) {
+  const diagnostics = [];
+  const groups = new Map();
+  for (const c of classified) {
+    if (!c.ok) {
+      diagnostics.push({ level: "error", code: c.code, message: c.message, path: c.path, ...(c.locale ? { locale: c.locale } : {}), ...(c.slug ? { slug: c.slug } : {}) });
+      continue;
+    }
+    if (c.layout === "legacy") {
+      diagnostics.push({
+        level: "warning",
+        code: "PAGES_LEGACY_LAYOUT",
+        message: c.locale ? `legacy layout (deprecated); canonical location is ${pageFilePath(c.locale, c.slug)}` : "legacy layout (deprecated); its language is decided by the site's default locale",
+        path: c.path,
+        ...(c.locale ? { locale: c.locale } : {}),
+        slug: c.slug,
+      });
+    }
+    if (!c.locale) continue;
+    const key = `${c.locale} ${c.slug}`;
+    groups.set(key, [...(groups.get(key) ?? []), c]);
+  }
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const { locale, slug } = group[0];
+    if (new Set(group.map((c) => pageFileSemanticKey(c.parsed))).size === 1) {
+      for (const c of group.slice(1)) diagnostics.push({ level: "warning", code: "PAGES_DUPLICATE_EQUIVALENT", message: `same content as ${group[0].path}`, path: c.path, locale, slug });
+    } else {
+      for (const c of group) {
+        diagnostics.push({ level: "error", code: "PAGES_DUPLICATE_TARGET", message: `Two files resolve to locale "${locale}", slug "${slug}": ${group.map((g) => g.path).join(", ")}`, path: c.path, locale, slug });
+      }
+    }
+  }
+  return diagnostics;
+}
+
+// ── filesystem ────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Generic repository-relative path safety (pages and config). */
+export function checkRelativePath(rel) {
+  if (typeof rel !== "string" || rel === "") return { code: "PAGES_INVALID_PATH", reason: "empty path" };
+  if (rel.startsWith("/") || /^[A-Za-z]:/.test(rel) || isAbsolute(rel)) return { code: "PAGES_PATH_ESCAPE", reason: "absolute path" };
+  if (rel.includes("\\")) return { code: "PAGES_PATH_ESCAPE", reason: "backslash in path" };
+  const parts = rel.split("/");
+  if (parts.includes("..")) return { code: "PAGES_PATH_ESCAPE", reason: "'..' in path" };
+  if (/[\x00-\x1f\x7f-\x9f]/.test(rel)) return { code: "PAGES_INVALID_PATH", reason: "control character in path" };
+  if (parts.some((p) => p === "" || p === ".")) return { code: "PAGES_INVALID_PATH", reason: "empty or '.' path segment" };
+  return null;
+}
+
+function lstatOrNull(p) {
+  try {
+    return lstatSync(p);
+  } catch (error) {
+    if (error && error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * `root` (already realpath'd) + a relative path → the absolute target, refusing anything that would leave the
+ * root: traversal, absolute paths, backslashes, a symlink at any existing ancestor or at the target, and a
+ * target that exists but is not a regular file. Null error means safe.
+ */
+export function resolveContained(root, rel) {
+  const unsafe = checkRelativePath(rel);
+  if (unsafe) return { error: { ...unsafe, path: rel } };
+  const parts = rel.split("/");
+  const target = join(root, ...parts);
+  const back = relative(root, target);
+  if (back.startsWith("..") || isAbsolute(back)) return { error: { code: "PAGES_PATH_ESCAPE", reason: "path leaves the target directory", path: rel } };
+  let current = root;
+  for (let i = 0; i < parts.length; i++) {
+    current = join(current, parts[i]);
+    const st = lstatOrNull(current);
+    if (!st) break;
+    if (st.isSymbolicLink()) return { error: { code: "PAGES_PATH_ESCAPE", reason: `${parts.slice(0, i + 1).join("/")} is a symbolic link`, path: rel } };
+    const last = i === parts.length - 1;
+    if (!last && !st.isDirectory()) return { error: { code: "PAGES_INVALID_PATH", reason: `${parts.slice(0, i + 1).join("/")} is not a directory`, path: rel } };
+    if (last && !st.isFile()) return { error: { code: "PAGES_INVALID_PATH", reason: "target exists and is not a regular file", path: rel } };
+  }
+  return { target };
+}
+
+/**
+ * Every `pages/**.json` under `dir`, in lexical path order, WITHOUT following symlinks. Symlinks and non-regular
+ * files are findings, not files. Other extensions are ignored (a README next to the pages is fine).
+ */
+export function collectPageFiles(dir) {
+  const root = realpathSync(dir);
+  const files = [];
+  const errors = [];
+  const pagesDir = join(root, "pages");
+  const top = lstatOrNull(pagesDir);
+  if (!top) return { root, files, errors };
+  if (top.isSymbolicLink()) return { root, files, errors: [{ level: "error", code: "PAGES_PATH_ESCAPE", message: "pages/ is a symbolic link", path: "pages" }] };
+  if (!top.isDirectory()) return { root, files, errors: [{ level: "error", code: "PAGES_INVALID_PATH", message: "pages is not a directory", path: "pages" }] };
+  const walk = (abs, relParts) => {
+    const names = readdirSync(abs).sort();
+    for (const name of names) {
+      const childAbs = join(abs, name);
+      const childRel = ["pages", ...relParts, name].join("/");
+      const st = lstatSync(childAbs);
+      if (st.isSymbolicLink()) {
+        errors.push({ level: "error", code: "PAGES_PATH_ESCAPE", message: "symbolic links are not followed", path: childRel });
+      } else if (st.isDirectory()) {
+        walk(childAbs, [...relParts, name]);
+      } else if (!st.isFile()) {
+        if (name.endsWith(".json")) errors.push({ level: "error", code: "PAGES_INVALID_PATH", message: "not a regular file", path: childRel });
+      } else if (name.endsWith(".json")) {
+        files.push([childRel, readFileSync(childAbs, "utf8")]);
+      } else if (/\.json\s*$/i.test(name)) {
+        // `about.JSON` or `about.json ` would otherwise be skipped silently while the author believes it was pushed.
+        errors.push({ level: "error", code: "PAGES_INVALID_PATH", message: "page file names must end in lowercase .json", path: childRel });
+      }
+    }
+  };
+  walk(pagesDir, []);
+  files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  errors.sort((a, b) => (a.path < b.path ? -1 : 1));
+  return { root, files, errors };
+}
+
+/** A target that another target needs as a folder (`a/index.json` vs `a/index.json/index.json`) cannot coexist. */
+export function folderConflicts(rels) {
+  const set = new Set(rels);
+  const out = [];
+  for (const rel of rels) {
+    const parts = rel.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      const prefix = parts.slice(0, i).join("/");
+      if (set.has(prefix)) out.push({ level: "error", code: "PAGES_INVALID_PATH", message: `${prefix} would have to be both a file and a folder`, path: rel });
+    }
+  }
+  return out;
+}
+
+/**
+ * Write `entries` ([rel, content]) under `root` in two phases. Every path is validated first; then all content is
+ * written to a staging directory inside `root`; only when every file is staged are they renamed into place.
+ * A failure before the rename phase leaves the destination exactly as it was.
+ */
+export function stagedWrite(root, entries, { writeFile = writeFileSync, rename = renameSync } = {}) {
+  const errors = folderConflicts(entries.map(([rel]) => rel));
+  const targets = [];
+  for (const [rel, content] of entries) {
+    const r = resolveContained(root, rel);
+    if (r.error) errors.push({ level: "error", code: r.error.code, message: r.error.reason, path: rel });
+    else targets.push([rel, r.target, content]);
+  }
+  if (errors.length > 0) throw new PagesCliError(errors[0].code, "Refusing to write outside the target directory; nothing was written.", { diagnostics: errors });
+
+  const staging = mkdtempSync(join(root, ".blocofy-staging-"));
+  try {
+    targets.forEach(([rel, , content], i) => {
+      const staged = join(staging, String(i));
+      writeFile(staged, typeof content === "string" ? content : "");
+    });
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw new PagesCliError("PAGES_WRITE_FAILED", `Could not stage files (${error?.message ?? error}); nothing was written.`);
+  }
+  let written = 0;
+  try {
+    targets.forEach(([, target], i) => {
+      mkdirSync(dirname(target), { recursive: true });
+      rename(join(staging, String(i)), target);
+      written += 1;
+    });
+  } catch (error) {
+    throw new PagesCliError(
+      "PAGES_WRITE_FAILED",
+      `Stopped after writing ${written} of ${targets.length} files (${error?.message ?? error}); written: ${targets.slice(0, written).map(([rel]) => rel).join(", ") || "none"}.`,
+    );
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  return written;
+}
+
+// ── output ────────────────────────────────────────────────────────────────────────────────────────────────
+
+export function formatDiagnostic(d) {
+  const where = d.path ? `\n    ${d.path}` : d.slug ? `\n    ${d.locale ? `locale "${d.locale}", ` : ""}slug "${d.slug}"` : "";
+  return `${d.level} [${d.code}]:\n    ${d.message}${where}`;
+}
+
+export { PageFileError, pageFilePath };

package/lib/page-path-codec.mjs

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+
+/**
+ * PS-19 — page file layout, mirrored from the platform (Blocofy/blocofy `packages/cms/src/page-files/path-codec.ts`).
+ * The platform is the authority; this copy lets `pages check` and `pages migrate-layout` judge files offline.
+ * `test/fixtures/page-path-vectors.json` is byte-identical on both sides and is the drift oracle.
+ *
+ *   pages/<locale>/index.json                      slug "/"
+ *   pages/<locale>/routes/<seg>/…/index.json       any other slug ("/index" included)
+ *   pages/<locale>/hashed/<sha256 hex>/index.json  a slug over the segment/depth/path limits
+ *
+ * Segments: safe bytes [a-z0-9-_.] stay readable; everything else (uppercase included) becomes `~hh` (lowercase
+ * hex per UTF-8 byte); `~` itself is `~7e`; a leading/trailing dot and the first byte of a Windows reserved name
+ * are escaped. Nothing is normalised: a non-canonical slug or locale is refused.
+ */
+
+export const PAGE_FILE_FORMAT_VERSION = 2;
+export const PAGE_SEGMENT_MAX_BYTES = 100;
+export const PAGE_ROUTE_DEPTH_MAX = 16;
+export const PAGE_PATH_MAX_BYTES = 200;
+export const PAGE_SLUG_MAX_BYTES = 2048;
+
+export class PageFileError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "PageFileError";
+    this.code = code;
+  }
+}
+
+const utf8 = new TextEncoder();
+const utf8Strict = new TextDecoder("utf-8", { fatal: true });
+
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const CONTROL = /[\x00-\x1f\x7f-\x9f]/;
+// COM0/LPT0 included: Microsoft lists them as reserved too.
+const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+const LOCALE_CODE_PATTERN = /^[A-Za-z]{2,3}(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?$/;
+
+/** `en-us` → `en-US`; null for anything outside the platform's accepted shapes (mirror of locale-route-key.ts). */
+export function canonicalizeLocaleCode(code) {
+  if (typeof code !== "string") return null;
+  const trimmed = code.trim();
+  if (!LOCALE_CODE_PATTERN.test(trimmed)) return null;
+  return trimmed
+    .split("-")
+    .map((part, index) => {
+      if (index === 0) return part.toLowerCase();
+      if (part.length === 4) return part[0].toUpperCase() + part.slice(1).toLowerCase();
+      return part.toUpperCase();
+    })
+    .join("-");
+}
+
+export function checkPageSlug(slug) {
+  if (typeof slug !== "string") return "slug must be a string";
+  if (slug === "/") return null;
+  if (!slug.startsWith("/")) return "slug must start with /";
+  if (slug.endsWith("/")) return "slug must not end with /";
+  if (LONE_SURROGATE.test(slug)) return "slug is not well-formed Unicode";
+  if (utf8.encode(slug).length > PAGE_SLUG_MAX_BYTES) return `slug is longer than ${PAGE_SLUG_MAX_BYTES} bytes`;
+  if (slug.normalize("NFC") !== slug) return "slug is not in Unicode NFC form";
+  if (CONTROL.test(slug)) return "slug contains a control character";
+  if (slug.includes("\\")) return "slug contains a backslash";
+  if (slug.includes("?") || slug.includes("#")) return "slug contains a query or fragment";
+  if (/%(2f|5c)/i.test(slug)) return "slug contains an encoded slash or backslash";
+  for (const segment of slug.slice(1).split("/")) {
+    if (segment === "") return "slug contains an empty segment";
+    const dotted = segment.replace(/%2e/gi, ".");
+    if (dotted === "." || dotted === "..") return "slug contains a . or .. segment";
+  }
+  return null;
+}
+
+const isSafeByte = (b) => (b >= 0x61 && b <= 0x7a) || (b >= 0x30 && b <= 0x39) || b === 0x2d || b === 0x5f || b === 0x2e;
+
+export function encodeSegment(segment) {
+  const bytes = utf8.encode(segment);
+  // A segment spelled `index.json` would make a route's own file name (`…/<seg>/index.json`) the folder of a
+  // child route (`/blog` vs `/blog/index.json`), which no filesystem or git tree can hold. Escaping its first
+  // byte keeps the two apart.
+  const reserved = WINDOWS_RESERVED.test(segment.split(".")[0] ?? "") || segment === "index.json";
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    const edgeDot = b === 0x2e && (i === 0 || i === bytes.length - 1);
+    if (!isSafeByte(b) || edgeDot || (reserved && i === 0)) out += "~" + b.toString(16).padStart(2, "0");
+    else out += String.fromCharCode(b);
+  }
+  return out;
+}
+
+export function decodeSegment(encoded) {
+  const bytes = [];
+  for (let i = 0; i < encoded.length; i++) {
+    const c = encoded.charCodeAt(i);
+    if (c === 0x7e) {
+      const pair = encoded.slice(i + 1, i + 3);
+      if (!/^[0-9a-f]{2}$/.test(pair)) return null;
+      bytes.push(parseInt(pair, 16));
+      i += 2;
+    } else if (isSafeByte(c)) {
+      bytes.push(c);
+    } else {
+      return null;
+    }
+  }
+  let decoded;
+  try {
+    decoded = utf8Strict.decode(new Uint8Array(bytes));
+  } catch {
+    return null;
+  }
+  return encodeSegment(decoded) === encoded ? decoded : null;
+}
+
+export function pageFilePath(locale, slug) {
+  if (typeof locale !== "string" || canonicalizeLocaleCode(locale) !== locale) {
+    throw new PageFileError("PAGES_INVALID_LOCALE", `locale ${JSON.stringify(locale)} is not a canonical locale code`);
+  }
+  const reason = checkPageSlug(slug);
+  if (reason) throw new PageFileError("PAGES_INVALID_SLUG", `${JSON.stringify(slug)}: ${reason}`);
+  if (slug === "/") return `pages/${locale}/index.json`;
+  const segments = slug.slice(1).split("/").map(encodeSegment);
+  const path = `pages/${locale}/routes/${segments.join("/")}/index.json`;
+  const tooLong =
+    segments.length > PAGE_ROUTE_DEPTH_MAX || segments.some((s) => s.length > PAGE_SEGMENT_MAX_BYTES) || path.length > PAGE_PATH_MAX_BYTES;
+  if (!tooLong) return path;
+  return `pages/${locale}/hashed/${createHash("sha256").update(utf8.encode(slug)).digest("hex")}/index.json`;
+}
+
+/** The pre-PS-19 formula; only for recognising and migrating legacy files. */
+export function legacyPageFilePath(slug) {
+  const clean = slug.replace(/^\/+|\/+$/g, "").trim();
+  return `pages/${clean || "index"}.json`;
+}
+
+export function checkRelativePagePath(path) {
+  if (typeof path !== "string" || path === "") return { code: "PAGES_INVALID_PATH", reason: "empty path" };
+  if (path.startsWith("/") || /^[A-Za-z]:/.test(path)) return { code: "PAGES_PATH_ESCAPE", reason: "absolute path" };
+  if (path.includes("\\")) return { code: "PAGES_PATH_ESCAPE", reason: "backslash in path" };
+  const parts = path.split("/");
+  if (parts.includes("..")) return { code: "PAGES_PATH_ESCAPE", reason: "'..' in path" };
+  if (CONTROL.test(path) || LONE_SURROGATE.test(path)) return { code: "PAGES_INVALID_PATH", reason: "control character in path" };
+  if (parts.some((p) => p === "" || p === ".")) return { code: "PAGES_INVALID_PATH", reason: "empty or '.' path segment" };
+  if (parts[0] !== "pages" || parts.length < 2) return { code: "PAGES_INVALID_PATH", reason: "path must be under pages/" };
+  if (!path.endsWith(".json")) return { code: "PAGES_INVALID_PATH", reason: "page files end in .json" };
+  return null;
+}
+
+const invalid = (reason) => ({ kind: "invalid", code: "PAGES_INVALID_PATH", reason });
+
+export function parsePageFilePath(path) {
+  const unsafe = checkRelativePagePath(path);
+  if (unsafe) return { kind: "invalid", ...unsafe };
+  const parts = path.split("/");
+  const folder = parts[1];
+  const rest = parts.slice(2);
+  const canonical = canonicalizeLocaleCode(folder);
+  if (canonical === null || rest.length === 0) return { kind: "other" };
+  const shaped = rest[0] === "index.json" || rest[0] === "routes" || rest[0] === "hashed";
+  if (!shaped) return { kind: "other" };
+  if (canonical !== folder) return invalid(`locale folder ${JSON.stringify(folder)} is not canonical (${canonical})`);
+  if (rest[0] === "index.json") {
+    return rest.length === 1 ? { kind: "canonical", locale: folder, slug: "/" } : invalid("unexpected path after index.json");
+  }
+  if (rest[rest.length - 1] !== "index.json") return invalid("canonical page files are named index.json");
+  if (rest[0] === "hashed") {
+    return rest.length === 3 && /^[0-9a-f]{64}$/.test(rest[1])
+      ? { kind: "hashed", locale: folder, hash: rest[1] }
+      : invalid("hashed page paths are hashed/<sha256 hex>/index.json");
+  }
+  const encoded = rest.slice(1, -1);
+  if (encoded.length === 0) return invalid("routes/ needs at least one segment");
+  const decoded = [];
+  for (const segment of encoded) {
+    const value = decodeSegment(segment);
+    if (value === null) return invalid(`segment ${JSON.stringify(segment)} is not canonically encoded`);
+    decoded.push(value);
+  }
+  const slug = "/" + decoded.join("/");
+  if (checkPageSlug(slug) !== null) return invalid("path decodes to an invalid slug");
+  if (pageFilePath(folder, slug) !== path) return invalid("path is not the canonical spelling of its slug");
+  return { kind: "canonical", locale: folder, slug };
+}
+
+export function isCanonicalLayoutPath(path) {
+  if (checkRelativePagePath(path)) return false;
+  const parts = path.split("/");
+  const rest = parts.slice(2);
+  if (canonicalizeLocaleCode(parts[1] ?? "") === null || rest.length === 0) return false;
+  return rest[0] === "index.json" || rest[0] === "routes" || rest[0] === "hashed";
+}

package/package.json

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