@blocofy/cli 0.8.0 → 0.10.0

package/lib/site-migrate.mjs

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { folderConflicts, resolveContained } from "./page-files.mjs";
+import { THEME_DIRS } from "./local-theme.mjs";
+import { MANIFEST_PATH, THEME_SETTINGS_PATH, checkSiteStatePath, ownerOfPath } from "./site-state.mjs";
+import { readSiteStateTree } from "./site-state-fs.mjs";
+
+/**
+ * CF-T4 — `blocofy site migrate`: turns a directory produced by the OLDER separate pulls (`theme pull`'s
+ * theme-dirs-at-root layout, `pages pull`'s canonical `pages/<locale>/…/index.json`, `settings pull`'s
+ * `config/settings.json`) into the site-state v1 tree layout (contract §A1). Purely local, zero network:
+ * this reuses `readSiteStateTree` — the same symlink-refusing walk `site export`/`site validate` use — to
+ * read, and the same contained-path helpers (`resolveContained`, `folderConflicts`) `pages migrate-layout`
+ * writes with. No new fs primitives, no identity/target call.
+ *
+ * `pages/**` files are NEVER moved — a site state uses the exact canonical location `pages pull` already
+ * writes (contract §A1). A page still at the OLD flat layout (`pages/<slug>.json`) is left alone with a
+ * note pointing at `blocofy pages migrate-layout`, which already owns that reasoning (locale resolution,
+ * legacy-vs-canonical detection); duplicating it here would drift.
+ *
+ * This never invents the owners a directory of separate pulls never had — site/locales.json, globals,
+ * media-policy, content-model, translations, navigation, theme/chrome/**, blocofy-site.json itself. Those
+ * can only come from the server; `needsExport` says whether this tree is missing its manifest for exactly
+ * that reason, so the caller can point at `blocofy site export`.
+ */
+
+const SETTINGS_SOURCE = "config/settings.json";
+const SETTINGS_SCHEMA_SOURCE = "config/settings_schema.json";
+const SETTINGS_SCHEMA_TARGET = "theme/config/settings_schema.json";
+
+/** Old-format relative path → its site-state v1 target, or null when this command does not know how to move it. */
+function mapOldPath(path) {
+  if (path === SETTINGS_SOURCE) return THEME_SETTINGS_PATH;
+  if (path === SETTINGS_SCHEMA_SOURCE) return SETTINGS_SCHEMA_TARGET;
+  const top = path.split("/")[0];
+  return THEME_DIRS.has(top) ? `theme/${path}` : null;
+}
+
+/**
+ * Read-only plan: every move this tree needs, every file left alone (and why), every refusal. Never
+ * touches disk beyond the read. `moves` is empty and `refused` true together only on a hard error
+ * (conflict, symlink, unreadable entry) — never on "nothing to migrate".
+ */
+export function planSiteMigrate(dir) {
+  const tree = readSiteStateTree(dir);
+  const errors = [...tree.diagnostics];
+  const moves = [];
+  const untouched = [];
+  const claimed = new Map();
+
+  for (const path of Object.keys(tree.files).sort()) {
+    if (path === MANIFEST_PATH || ownerOfPath(path) !== null) {
+      untouched.push({ path, reason: "already in the site-state tree layout" });
+      continue;
+    }
+    const target = mapOldPath(path);
+    if (target === null) {
+      untouched.push({
+        path,
+        reason: path.startsWith("pages/")
+          ? "old flat page layout — run `blocofy pages migrate-layout` first"
+          : "not part of the site-state tree — left alone",
+      });
+      continue;
+    }
+    const refusal = checkSiteStatePath(target);
+    if (refusal) {
+      errors.push({ level: "error", code: refusal.code, message: `${path} → ${target}: ${refusal.reason}`, path });
+      continue;
+    }
+    const existing = tree.files[target];
+    if (existing !== undefined) {
+      if (existing === tree.files[path]) {
+        untouched.push({ path, reason: `${target} already holds the same content; left in place (remove ${path} yourself)` });
+        continue;
+      }
+      errors.push({ level: "error", code: "SITE_STATE_MIGRATE_CONFLICT", message: `${target} already exists with different content than ${path}`, path });
+      continue;
+    }
+    const claimant = claimed.get(target);
+    if (claimant) {
+      errors.push({ level: "error", code: "SITE_STATE_MIGRATE_CONFLICT", message: `${path} and ${claimant} would both move to ${target}`, path });
+      continue;
+    }
+    claimed.set(target, path);
+    moves.push({ from: path, to: target, content: tree.files[path] });
+  }
+  for (const asset of tree.assets) untouched.push({ path: asset.path, reason: "already in the site-state tree layout" });
+
+  moves.sort((a, b) => (a.from < b.from ? -1 : 1));
+  const remaining = Object.keys(tree.files).filter((p) => !moves.some((m) => m.from === p));
+  errors.push(...folderConflicts([...remaining, ...moves.map((m) => m.to)]));
+
+  const refused = errors.length > 0;
+  const needsExport = tree.files[MANIFEST_PATH] === undefined;
+  return { root: tree.root, moves, untouched, diagnostics: errors, refused, needsExport };
+}
+
+/**
+ * Performs `moves` (from `planSiteMigrate`) on `root`: every target is revalidated (contained, not already
+ * present) before the first byte is written; then each file is written+renamed into place and only then is
+ * its old location removed. A mid-loop fs failure (real I/O error, not a logic conflict — those were already
+ * refused by the plan) leaves everything moved so far in place and throws, naming how many completed.
+ */
+export function writeSiteMigrate(root, moves) {
+  for (const m of moves) {
+    const r = resolveContained(root, m.to);
+    if (r.error) throw new Error(`internal: ${m.to} is not a valid site-state target (${r.error.reason})`);
+    if (existsSync(r.target)) throw new Error(`${m.to} appeared during migration; stopped before moving it.`);
+  }
+  let moved = 0;
+  for (const m of moves) {
+    const { target } = resolveContained(root, m.to);
+    mkdirSync(dirname(target), { recursive: true });
+    const temp = `${target}.blocofy-tmp`;
+    writeFileSync(temp, m.content, { flag: "wx" });
+    renameSync(temp, target);
+    const { target: legacy } = resolveContained(root, m.from);
+    rmSync(legacy);
+    moved += 1;
+  }
+  return moved;
+}
+
+/** `blocofy site migrate`: plan, and with `write: true` perform it. Any refusal moves zero files. */
+export function migrateSiteState({ dir, write = false }) {
+  const plan = planSiteMigrate(dir);
+  if (!write || plan.refused) return { ...plan, moved: 0 };
+  const moved = writeSiteMigrate(plan.root, plan.moves);
+  return { ...plan, moved };
+}

package/lib/site-state-client.mjs

@@ -0,0 +1,92 @@
+import { CliRefusal } from "./media-uses.mjs";
+import { fetchWithRetry } from "./http.mjs";
+
+/**
+ * CF-T4 — the v1 `site-state` HTTP client: `GET /api/v1/site-state`, `POST …/plan`, `…/apply`, `…/publish`,
+ * and `POST /api/v1/media` (asset upload, reused for `awaiting_assets`). Bearer `blcf_live_…` API key —
+ * same authentication and error-envelope shape as `lib/media-uses.mjs`, whose `CliRefusal` this reuses so
+ * `bin/blocofy.mjs`'s exit-code mapping (`error instanceof CliRefusal` → 2) needs no second branch.
+ *
+ * Retries (CF-T3, `lib/http.mjs`): every one of these calls is safe to resend blindly.
+ *   - export/plan are reads.
+ *   - apply and publish are idempotent BY DESIGN (contract §A3): every step re-reads before writing and
+ *     no-ops when the target already matches, and "publishing the same state twice rewrites nothing".
+ *   - a media upload has no idempotency key in this contract; a duplicate upload after a connection reset
+ *     is at worst a second file with the SAME bytes, which the next plan's sha256 match treats identically
+ *     to the first (harmless, unlike creating a second logical record).
+ * A 4xx is a server refusal (`CliRefusal`, exit 2 — see `bin/blocofy.mjs`'s `exitCodeFor`). A final
+ * 5xx/network failure after retries throws a plain `Error` with `.status` (exit 1).
+ */
+
+export { CliRefusal };
+
+function url(apiUrl, path) {
+  return `${String(apiUrl).replace(/\/+$/, "")}${path}`;
+}
+
+/** A response → its JSON body, or the standard refusal/error thrown (shared by every call below). */
+async function readJsonOrThrow(res) {
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = null;
+  }
+  if (res.ok) {
+    if (json === null) throw new Error(`HTTP ${res.status}: empty or non-JSON response`);
+    return json;
+  }
+  if (res.status >= 400 && res.status < 500) {
+    const error = json?.error && typeof json.error === "object" ? json.error : { code: `http_${res.status}`, message: text.slice(0, 200) || `HTTP ${res.status}` };
+    throw new CliRefusal(res.status, error);
+  }
+  const detail = json?.error?.message ?? (text ? text.slice(0, 200) : "");
+  throw Object.assign(new Error(`HTTP ${res.status}${detail ? `: ${detail}` : ""}`), { status: res.status });
+}
+
+async function requestJson(method, target, { apiKey, onRetry = null, body }) {
+  const headers = { authorization: `Bearer ${apiKey}`, accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  const res = await fetchWithRetry(target, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) }, { onRetry });
+  return readJsonOrThrow(res);
+}
+
+/** `GET /api/v1/site-state` → `{schema_version, manifest, files, assets, diagnostics}`. */
+export function fetchSiteStateExport({ apiUrl, apiKey, onRetry = null }) {
+  return requestJson("GET", url(apiUrl, "/api/v1/site-state"), { apiKey, onRetry });
+}
+
+/** `POST /api/v1/site-state/plan` → the plan (read-only; no side effects). */
+export function planSiteState({ apiUrl, apiKey, body, onRetry = null }) {
+  return requestJson("POST", url(apiUrl, "/api/v1/site-state/plan"), { apiKey, onRetry, body });
+}
+
+/** `POST /api/v1/site-state/apply` → `{status, plan_hash, applied, not_applied, report, theme_source}`. */
+export function applySiteState({ apiUrl, apiKey, body, onRetry = null }) {
+  return requestJson("POST", url(apiUrl, "/api/v1/site-state/apply"), { apiKey, onRetry, body });
+}
+
+/** `POST /api/v1/site-state/publish` → `{status:"published", plan_hash, target_instance, swapped, navigation, globals}`. */
+export function publishSiteState({ apiUrl, apiKey, body, onRetry = null }) {
+  return requestJson("POST", url(apiUrl, "/api/v1/site-state/publish"), { apiKey, onRetry, body });
+}
+
+/** Download one exported asset's bytes from its own delivery URL (not the v1 API — no auth header). */
+export async function downloadAssetBytes({ url: assetUrl, onRetry = null }) {
+  const res = await fetchWithRetry(assetUrl, {}, { onRetry });
+  if (!res.ok) throw new Error(`could not download ${assetUrl} (HTTP ${res.status})`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/** `POST /api/v1/media` (multipart `file` field) → `{file: {...}}`. Used to satisfy `assets_missing`. */
+export async function uploadMediaAsset({ apiUrl, apiKey, filename, content, mime = "application/octet-stream", onRetry = null }) {
+  const form = new FormData();
+  form.set("file", new Blob([content], { type: mime }), filename);
+  const res = await fetchWithRetry(
+    url(apiUrl, "/api/v1/media"),
+    { method: "POST", headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" }, body: form },
+    { onRetry },
+  );
+  return readJsonOrThrow(res);
+}

package/lib/site-state-fs.mjs

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { folderConflicts, resolveContained } from "./page-files.mjs";
+import { ASSET_FILES_PREFIX } from "./site-state.mjs";
+
+/**
+ * CF-T4 — the site-state tree on a real filesystem: a read that refuses symlinks (lstat every entry) and
+ * an all-or-nothing staged write. Kept separate from `lib/site-state.mjs` (pure, read-free) and from
+ * `lib/page-files.mjs` (PS-19 `pages/**` specifically) because a site-state tree has its own root shape
+ * (`blocofy-site.json`, `site/`, `theme/`, `pages/`, `media/`) and its own binary member (`media/files/<sha256>`).
+ */
+
+export class SiteStateFsError extends Error {
+  constructor(code, message, diagnostics = []) {
+    super(message);
+    this.name = "SiteStateFsError";
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+}
+
+/**
+ * Read every file under `root`. Returns `{ root, files, assets, diagnostics }`:
+ *   - `files`: relPath → utf8 content, for every path EXCEPT `media/files/<sha256>` (those are binary
+ *     asset bytes, never decoded as text — the request body never carries them either, contract §A1).
+ *   - `assets`: `{ path, sha256, abs, bytes }` for every `media/files/<sha256>` entry found.
+ *   - `diagnostics`: a symlink or a non-regular-file entry (`SITE_STATE_SYMLINK` / `SITE_STATE_INVALID_PATH`),
+ *     never thrown — callers that must refuse on any diagnostic (export, plan, apply) check the array.
+ * A dot-prefixed entry AT THE ROOT (`.git`, `.blocofy`, `.DS_Store`, …) is silently skipped: those are
+ * project tooling, not part of the site-state tree. A dot-prefixed entry found INSIDE a known folder
+ * (`theme/assets/.hidden.css`) is walked into and reported by `checkSiteStatePath`, same as the platform.
+ */
+export function readSiteStateTree(root) {
+  const realRoot = realpathSync(root);
+  const files = {};
+  const assets = [];
+  const diagnostics = [];
+  const walk = (abs, relParts) => {
+    let names;
+    try {
+      names = readdirSync(abs).sort();
+    } catch (error) {
+      diagnostics.push({ level: "error", code: "SITE_STATE_INVALID_PATH", message: `could not read directory (${error?.message ?? error})`, path: relParts.join("/") || "." });
+      return;
+    }
+    for (const name of names) {
+      if (relParts.length === 0 && name.startsWith(".")) continue;
+      const childAbs = join(abs, name);
+      const childRel = [...relParts, name].join("/");
+      const st = lstatSync(childAbs);
+      if (st.isSymbolicLink()) {
+        diagnostics.push({ level: "error", code: "SITE_STATE_SYMLINK", message: "symbolic links are not read", path: childRel });
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(childAbs, [...relParts, name]);
+        continue;
+      }
+      if (!st.isFile()) {
+        diagnostics.push({ level: "error", code: "SITE_STATE_INVALID_PATH", message: "not a regular file", path: childRel });
+        continue;
+      }
+      if (childRel.startsWith(ASSET_FILES_PREFIX)) {
+        assets.push({ path: childRel, sha256: childRel.slice(ASSET_FILES_PREFIX.length), abs: childAbs, bytes: st.size });
+      } else {
+        files[childRel] = readFileSync(childAbs, "utf8");
+      }
+    }
+  };
+  walk(realRoot, []);
+  return { root: realRoot, files, assets, diagnostics };
+}
+
+/** sha256 (lowercase hex) of a `Buffer`. */
+export function hashBuffer(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+/** sha256 (lowercase hex) of a local file's actual bytes. */
+export function hashFile(abs) {
+  return hashBuffer(readFileSync(abs));
+}
+
+/**
+ * Staged write of a site-state tree. `entries` is `[relPath, content]`, content a string or a `Buffer`
+ * (asset bytes). Every path is validated (traversal/absolute/backslash/symlink-in-ancestor) before the
+ * first byte is written; then every file is staged into a temp directory under `root`, and only when
+ * every file is staged are they renamed into place. Mirrors `page-files.mjs`'s `stagedWrite`,
+ * generalized to binary content.
+ *
+ * WHAT THIS DOES AND DOES NOT GUARANTEE. A failure anywhere BEFORE the rename phase - a bad path, a
+ * symlinked ancestor, a full disk while staging - leaves the destination exactly as it was. The rename
+ * phase itself is not atomic across files: renames land one at a time, across directories, and an I/O
+ * failure part-way through leaves the ones already renamed in place and throws "Stopped after writing
+ * N of M files". The caller is `site export`, a local read-then-write that is safe to re-run, so a
+ * partial tree is recoverable by running it again. Do not reuse this for a remote mutation, or for
+ * anything where a half-applied tree is not recoverable, without adding a real commit step.
+ */
+export function stagedWriteTree(root, entries) {
+  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 SiteStateFsError("SITE_STATE_WRITE_FAILED", "Refusing to write outside the target directory; nothing was written.", errors);
+  }
+
+  mkdirSync(root, { recursive: true });
+  const staging = mkdtempSync(join(root, ".blocofy-site-state-staging-"));
+  try {
+    targets.forEach(([, , content], i) => writeFileSync(join(staging, String(i)), content));
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw new SiteStateFsError("SITE_STATE_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 });
+      renameSync(join(staging, String(i)), target);
+      written += 1;
+    });
+  } catch (error) {
+    throw new SiteStateFsError(
+      "SITE_STATE_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;
+}