@blocofy/cli 0.7.0 → 0.9.0

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/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.9.0",
   "description": "Develop your Blocofy theme locally against live data with instant preview — login, theme dev, pull, push.",
   "type": "module",
   "license": "MIT",