@stelstone/server 0.26.0

package/src/adapters/_shared.mjs

@@ -0,0 +1,401 @@
+/**
+ * Shared helpers used across content and template adapters.
+ */
+
+/**
+ * Strips all characters outside [a-zA-Z0-9._-].
+ * Used to sanitize path segments coming from config (collection names, etc.).
+ */
+export function sanitize(p) {
+  return String(p).replace(/[^a-zA-Z0-9._-]/g, "");
+}
+
+/**
+ * Validates a filename (e.g. "en-hello.json") from a route param.
+ * Returns the input unchanged if it is safe, or null if it should be rejected.
+ *
+ * Rules:
+ *  - Must match /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+ *  - Must not be "." or ".." or consist entirely of dots
+ */
+export function safeFileName(name) {
+  if (typeof name !== "string") return null;
+  if (name === "." || name === ".." || /^\.+$/.test(name)) return null;
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) return null;
+  return name;
+}
+
+/**
+ * True when a filename is a content entry (and not a generated manifest such
+ * as `_index.json`). Manifest/index files are list projections, not entries,
+ * so every directory-scan that enumerates entries must exclude them.
+ *
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function isEntryFile(file) {
+  return typeof file === "string" && file.endsWith(".json") && !file.startsWith("_");
+}
+
+/**
+ * Sorts a pages array in-place and returns it.
+ *
+ * When sortConfig is provided, sorts by `data.meta?.[sortConfig.field]`.
+ * Missing values are always placed at the end, regardless of direction.
+ * When sortConfig is null/undefined, sorts by title (localeCompare).
+ *
+ * @param {Array} pages  Each element must have `.meta` and `.title`.
+ * @param {Object|null} sortConfig  { field: string, direction: "asc"|"desc" }
+ */
+export function sortPages(pages, sortConfig) {
+  if (sortConfig) {
+    const dir = sortConfig.direction === "desc" ? -1 : 1;
+    pages.sort((a, b) => {
+      const av = a[sortConfig.field] ?? a.meta?.[sortConfig.field];
+      const bv = b[sortConfig.field] ?? b.meta?.[sortConfig.field];
+      const aMissing = av === undefined || av === null;
+      const bMissing = bv === undefined || bv === null;
+      if (aMissing && bMissing) return 0;
+      if (aMissing) return 1;   // missing always last
+      if (bMissing) return -1;  // missing always last
+      if (av < bv) return -1 * dir;
+      if (av > bv) return 1 * dir;
+      return 0;
+    });
+  } else {
+    pages.sort((a, b) => a.title.localeCompare(b.title));
+  }
+  return pages;
+}
+
+/**
+ * Recursively regenerates block IDs.
+ * Children columns are arrays of block arrays (columns), so we recurse into each.
+ */
+export function reid(blocks) {
+  if (!Array.isArray(blocks)) return blocks;
+  return blocks.map((b) => {
+    const next = { ...b, id: "b-" + Math.random().toString(36).slice(2, 9) };
+    if (Array.isArray(b.children)) {
+      next.children = b.children.map((col) => reid(col));
+    }
+    return next;
+  });
+}
+
+/**
+ * Builds a duplicate page payload from a source page object.
+ * Returns { data, fileName }.
+ */
+export function buildDuplicateData(src) {
+  const lang = src.lang || "en";
+  const baseSlug = (src.slug || "page").replace(/-copy(-\d+)?$/, "");
+  const newSlug = `${baseSlug}-copy-${Math.floor(Date.now() / 1000)}`;
+  const data = {
+    ...src,
+    id: `${lang}/${newSlug}`,
+    slug: newSlug,
+    meta: { ...(src.meta || {}), title: `${src.meta?.title || newSlug} (Copy)` },
+    blocks: reid(src.blocks || []),
+  };
+  const fileName = `${sanitize(lang)}-${sanitize(newSlug)}.json`;
+  return { data, fileName };
+}
+
+/**
+ * Scans all collections in `adapter` and returns entries whose
+ * `meta.publishAt` is in the past.
+ *
+ * @param {import('./types.mjs').ContentAdapter} adapter
+ * @returns {Promise<Array<{collection: string, file: string, data: object}>>}
+ */
+export async function listScheduledDue(adapter) {
+  const collections = await adapter.listCollections();
+  const now = new Date();
+  const due = [];
+  for (const { name } of collections) {
+    const pages = await adapter.listPages(name);
+    for (const page of pages || []) {
+      if (page.meta?.publishAt && new Date(page.meta.publishAt) <= now) {
+        const data = await adapter.readPage(name, page.file);
+        if (data?.meta?.publishAt) due.push({ collection: name, file: page.file, data });
+      }
+    }
+  }
+  return due;
+}
+
+/** Top-level keys read directly from the page object; all others come from page.meta. */
+const TOP_LEVEL_KEYS = new Set(["id", "slug", "lang", "collection", "title", "file"]);
+
+/**
+ * Resolves a field value from a page object using the admin-UI field resolution rule.
+ * Top-level keys (id, slug, lang, collection, title, file) are read from the page directly;
+ * every other key is read from page.meta.
+ *
+ * @param {object} page
+ * @param {string} key
+ * @returns {string}
+ */
+export function pageFieldValue(page, key) {
+  if (TOP_LEVEL_KEYS.has(key)) return page[key] ?? "";
+  return page.meta?.[key] ?? "";
+}
+
+/**
+ * Meta keys the server and admin UI always need on a list entry regardless of
+ * a collection's `listFields`, because core workflow logic reads them:
+ *   - `publishAt` — scheduled-publish detection (listScheduledDue) + status badge
+ *   - `draft`     — publish/draft/scheduled status badge
+ * These must never be dropped from the list index.
+ */
+export const SYSTEM_LIST_META_KEYS = ["draft", "publishAt"];
+
+/**
+ * Computes the set of `meta` keys that a list index must store for a
+ * collection. This is the union of the keys the list view actually consumes —
+ * `listFields`, `filters`, and sort keys — plus the always-required
+ * SYSTEM_LIST_META_KEYS. Top-level keys (id/slug/lang/collection/title/file)
+ * are excluded because they are stored at the top level of each entry, not
+ * under `meta`.
+ *
+ * Driving the index off config (instead of dumping the whole `meta` object)
+ * keeps manifests small and guarantees that every searchable/filterable/
+ * sortable field is present — so the admin list never shows a configured
+ * column or filter as silently empty.
+ *
+ * @param {object} [colConfig]  A single collection's config object.
+ * @returns {string[]} Meta keys to project into the list entry.
+ */
+export function listMetaKeys(colConfig) {
+  const keys = new Set(SYSTEM_LIST_META_KEYS);
+  const addFields = (arr) => {
+    for (const f of arr || []) {
+      if (f && f.key) keys.add(f.key);
+    }
+  };
+  addFields(colConfig?.listFields);
+  addFields(colConfig?.filters);
+  // Relation fields exist to be queried — "which entries point at this one" is
+  // the whole reason to declare one. Leaving them out of the manifest meant a
+  // reverse lookup had to open every entry body instead of reading the index.
+  for (const key of Object.keys(relationFields(colConfig))) keys.add(key);
+
+  // `sort` appears in two shapes in the wild. The canonical one — and the only
+  // one the API actually sorts by (see routes.mjs) — is a spec:
+  // `{ field, direction }`. An array of `{ key }` also exists. This function
+  // only needs the key names, so it accepts both; iterating the object form as
+  // an array used to throw and take `stelstone build-index` down with it.
+  if (Array.isArray(colConfig?.sort)) {
+    addFields(colConfig.sort);
+  } else {
+    const sortKey = colConfig?.sort?.field ?? colConfig?.sort?.key;
+    if (sortKey) keys.add(sortKey);
+  }
+  if (colConfig?.defaultSort?.key) keys.add(colConfig.defaultSort.key);
+  for (const k of TOP_LEVEL_KEYS) keys.delete(k);
+  return [...keys];
+}
+
+/**
+ * Builds the list-index record for a single page entry. Top-level
+ * id/slug/lang/collection/title/file are always stored; `meta` is projected
+ * down to only the keys returned by {@link listMetaKeys} for the collection.
+ *
+ * This is the single source of truth for list-entry shape, shared by every
+ * code path that produces one (fs listing, GitHub index read/write/bootstrap,
+ * and the `stelstone build-index` CLI) so they cannot diverge.
+ *
+ * Relation fields (a metaField with a `collection` target, e.g. a `combobox`)
+ * store a slug in the source data. When a `lookups` table for the target
+ * collection is supplied, the stored value is resolved to the referenced
+ * entry's display name so the admin list shows names instead of raw slugs.
+ * Resolution is best-effort: an unknown slug, or a missing lookup table, keeps
+ * the original slug. Producers that cannot cheaply load other collections
+ * (e.g. the GitHub edge write-path) simply omit `lookups` and store slugs.
+ *
+ * @param {object} [colConfig]    The collection's config (for listFields etc.).
+ * @param {string} collection     Collection name (fallback for entry.collection).
+ * @param {string} file           Source file name.
+ * @param {object} data           Full page object (has id/slug/lang/meta/...).
+ * @param {Object<string, Record<string,string>|Map<string,string>>} [lookups]
+ *        Per-collection slug→displayName tables, keyed by target collection name.
+ * @returns {object} The projected list entry.
+ */
+export function buildListEntry(colConfig, collection, file, data, lookups = {}) {
+  const fullMeta = data.meta || {};
+  const meta = {};
+  for (const key of listMetaKeys(colConfig)) {
+    if (fullMeta[key] !== undefined) meta[key] = fullMeta[key];
+  }
+  resolveRelationLabels(meta, colConfig, lookups);
+  return {
+    id: data.id,
+    slug: data.slug,
+    lang: data.lang,
+    collection: data.collection ?? collection,
+    title: fullMeta.title || fullMeta.name || file,
+    file,
+    meta,
+  };
+}
+
+/** Separates a collection name from a slug in a qualified relation value. */
+export const RELATION_SEPARATOR = ":";
+
+/**
+ * Splits `"blog:en/my-post"` into its parts. Slugs may contain `/` but never
+ * `:`, so the first separator is the boundary. Returns null for an unqualified
+ * value.
+ */
+export function parseRelationValue(value) {
+  if (typeof value !== "string") return null;
+  const at = value.indexOf(RELATION_SEPARATOR);
+  if (at <= 0) return null;
+  return { collection: value.slice(0, at), slug: value.slice(at + 1) };
+}
+
+/**
+ * Maps each relation field key of a collection to its target collections and
+ * cardinality. A metaField is a relation when it declares a `collection`
+ * target: `type: "combobox", collection: "authors"`, or several targets,
+ * `collection: ["reference", "blog"]`.
+ *
+ * With more than one target a bare slug no longer identifies an entry — the
+ * same slug can exist in two collections — so those values are stored
+ * qualified as `"collection:slug"`. Single-target fields keep storing a bare
+ * slug, so existing content and configs are unaffected.
+ *
+ * @param {object} [colConfig]
+ * @returns {Record<string, { collections: string[], multiple: boolean, qualified: boolean }>}
+ */
+export function relationFields(colConfig) {
+  const map = {};
+  for (const f of colConfig?.metaFields || []) {
+    if (!f || !f.key) continue;
+    const targets = typeof f.collection === "string"
+      ? [f.collection]
+      : Array.isArray(f.collection)
+        ? f.collection.filter((c) => typeof c === "string" && c)
+        : null;
+    if (!targets || targets.length === 0) continue;
+    map[f.key] = {
+      collections: targets,
+      multiple: !!f.multiple,
+      qualified: targets.length > 1,
+    };
+  }
+  return map;
+}
+
+/**
+ * In-place resolution of relation slugs in a projected `meta` object to the
+ * referenced entries' display names, using the supplied `lookups` tables.
+ * Handles both single values and arrays (multiple-select). Best-effort: leaves
+ * the slug untouched when no resolution is available.
+ *
+ * @param {object} meta       The projected meta object (mutated).
+ * @param {object} [colConfig]
+ * @param {object} [lookups]  Per-collection slug→displayName tables.
+ */
+export function resolveRelationLabels(meta, colConfig, lookups = {}) {
+  const relations = relationFields(colConfig);
+  for (const key of Object.keys(meta)) {
+    const rel = relations[key];
+    if (!rel) continue;
+
+    const lookIn = (target, slug) => {
+      const table = lookups[target];
+      if (!table) return null;
+      const name = table instanceof Map ? table.get(slug) : table[slug];
+      return name != null && name !== "" ? name : null;
+    };
+
+    const resolveOne = (raw) => {
+      // A qualified value names its own collection; an unqualified one belongs
+      // to the field's single target.
+      const parsed = rel.qualified ? parseRelationValue(raw) : null;
+      if (parsed) return lookIn(parsed.collection, parsed.slug) ?? raw;
+      return lookIn(rel.collections[0], raw) ?? raw;
+    };
+
+    const value = meta[key];
+    meta[key] = Array.isArray(value) ? value.map(resolveOne) : resolveOne(value);
+  }
+}
+
+/**
+ * Applies pagination, search, and filtering to a pre-sorted pages array.
+ * Does not mutate the input array.
+ *
+ * @param {object[]} pages  Pre-sorted array of page objects.
+ * @param {object}   opts
+ * @param {number}   [opts.page=1]        Current page (1-based).
+ * @param {number|"all"} [opts.perPage=20] Items per page, or "all" / 0 for no pagination.
+ * @param {string}   [opts.search=""]     Substring search term.
+ * @param {string[]} [opts.searchFields=[]] Keys to search across.
+ * @param {string[]} [opts.filterKeys=[]]  Keys for which to compute facet values.
+ * @param {object}   [opts.filters={}]    Active filters: { key: exactValue }.
+ * @returns {{ items: object[], total: number, facets: Record<string, string[]> }}
+ */
+export function queryPages(pages, {
+  page = 1,
+  perPage = 20,
+  search = "",
+  searchFields = [],
+  filterKeys = [],
+  filters = {},
+} = {}) {
+  // 1. Facets — computed over the full pages array
+  /** @type {Record<string, string[]>} */
+  const facets = {};
+  for (const key of filterKeys) {
+    const seen = new Set();
+    for (const p of pages) {
+      const v = String(pageFieldValue(p, key));
+      if (v !== "") seen.add(v);
+    }
+    facets[key] = [...seen].sort();
+  }
+
+  // 2. Filter
+  const activeFilters = Object.entries(filters).filter(([, v]) => v);
+  const filtered = activeFilters.length === 0
+    ? pages
+    : pages.filter((p) =>
+        activeFilters.every(([k, v]) => String(pageFieldValue(p, k)) === v)
+      );
+
+  // 3. Search
+  const term = search ? search.toLowerCase() : "";
+  const searched = term
+    ? filtered.filter((p) =>
+        searchFields.some((k) =>
+          String(pageFieldValue(p, k)).toLowerCase().includes(term)
+        )
+      )
+    : filtered;
+
+  // 4. Total
+  const total = searched.length;
+
+  // 5. Paginate
+  const perPageNum = perPage === "all" ? 0 : Number(perPage);
+  const items =
+    perPage === "all" || perPageNum === 0
+      ? searched.slice()
+      : searched.slice((page - 1) * perPageNum, page * perPageNum);
+
+  return { items, total, facets };
+}
+
+/**
+ * Produces a commit message string.
+ *
+ * @param {((ts: string) => string) | undefined} commitMessage
+ * @param {string} [fallback="Content updated"]
+ */
+export function commitMsg(commitMessage, fallback = "Content updated") {
+  const ts = new Date().toISOString().replace("T", " ").slice(0, 19);
+  return commitMessage ? commitMessage(ts) : `${fallback} ${ts}`;
+}

package/src/adapters/basic-auth.mjs

@@ -0,0 +1,102 @@
+import crypto from "crypto";
+
+/**
+ * HTTP Basic auth + HMAC-SHA256 JWT for media tokens.
+ *
+ * @param {Object} opts
+ * @param {string} opts.user
+ * @param {string|undefined} opts.pass
+ * @param {string|undefined} opts.jwtSecret
+ * @param {number} opts.jwtTtl
+ * @param {string} [opts.realm="Admin"]
+ * @returns {import('./types.mjs').AuthAdapter}
+ */
+function safeEq(a, b) {
+  const bufA = Buffer.from(a || "", "utf8");
+  const bufB = Buffer.from(b || "", "utf8");
+  if (bufA.length !== bufB.length) return false;
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+export function createBasicAuth({
+  user,
+  pass,
+  users,
+  jwtSecret,
+  jwtTtl,
+  realm = "Admin",
+}) {
+  // Normalise: prefer `users` array, fall back to single user/pass pair.
+  // Each entry may use `pass` (plaintext) or `passEnv` (env var name).
+  // Passwords arrive already resolved (see core/adapter-options.mjs). An
+  // adapter that reads process.env itself cannot run in a Worker, which is
+  // what forced the Worker to re-resolve this list by hand.
+  const userList = (users?.length
+    ? users
+    : pass ? [{ user: user || "admin", pass, role: "admin" }] : []
+  )
+    // A user whose password resolves to empty/undefined must be DISABLED,
+    // not matchable — otherwise an empty submitted password would log in.
+    // Reporting is left to config validation (core/config-schema.mjs), which
+    // names the config path and the environment variable; warning here too
+    // just prints the same problem twice.
+    .filter((entry) => Boolean(entry.pass));
+
+  const configured = userList.length > 0;
+
+  function findUser(u, p) {
+    return userList.find(
+      (entry) => safeEq(u, entry.user) && safeEq(p, entry.pass),
+    ) ?? null;
+  }
+
+  function issueMediaToken(tenantId) {
+    if (!jwtSecret) throw new Error("JWT_SECRET not set");
+    const header = Buffer.from(
+      JSON.stringify({ alg: "HS256", typ: "JWT" }),
+    ).toString("base64url");
+    const payload = Buffer.from(
+      JSON.stringify({
+        sub: user,
+        tenant_id: tenantId,
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + jwtTtl,
+      }),
+    ).toString("base64url");
+    const sig = crypto
+      .createHmac("sha256", jwtSecret)
+      .update(`${header}.${payload}`)
+      .digest("base64url");
+    return `${header}.${payload}.${sig}`;
+  }
+
+  /**
+   * Resolve the caller from the request.
+   *
+   * The CMS never sends WWW-Authenticate on failure: credentials were supplied
+   * and rejected, and the header would pop the browser's native Basic Auth
+   * dialog over the app's own error UI.
+   *
+   * @param {Request} request
+   * @returns {Promise<object|null>}
+   */
+  async function verify(request) {
+    const authHeader = request.headers.get("authorization");
+    if (!authHeader?.startsWith("Basic ")) return null;
+    const decoded = Buffer.from(authHeader.slice(6), "base64").toString();
+    const colon = decoded.indexOf(":");
+    const u = decoded.slice(0, colon);
+    const p = decoded.slice(colon + 1);
+    const entry = findUser(u, p);
+    if (!entry) return null;
+    return { login: entry.user, name: entry.name || entry.user, role: entry.role || "editor" };
+  }
+
+  return {
+    configured,
+    /** @param {string} capability */
+    supports: (capability) => capability === "mediaToken",
+    issueMediaToken,
+    verify,
+  };
+}

package/src/adapters/build-netlify.mjs

@@ -0,0 +1,60 @@
+/**
+ * Netlify deploys API integration.
+ *
+ * @param {Object} opts
+ * @param {string|undefined} opts.token
+ * @param {string|undefined} opts.siteId
+ * @param {string} opts.defaultBranch
+ * @returns {import('./types.mjs').BuildAdapter}
+ */
+export function createNetlifyBuild({ token, siteId, defaultBranch }) {
+  const configured = Boolean(token && siteId);
+
+  return {
+    configured,
+
+    async getDeployStatus({ branch, sha } = {}) {
+      if (!configured) return { configured: false };
+      const targetBranch = branch || defaultBranch;
+      const url = `https://api.netlify.com/api/v1/sites/${siteId}/deploys?per_page=20&branch=${encodeURIComponent(
+        targetBranch,
+      )}`;
+      const r = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (!r.ok) {
+        const err = new Error(`Netlify API ${r.status}`);
+        err.upstreamStatus = r.status;
+        throw err;
+      }
+      const deploys = await r.json();
+      let deploy = null;
+      if (sha) {
+        deploy = deploys.find(
+          (d) => d.commit_ref && d.commit_ref.startsWith(sha),
+        );
+        // SHA not found yet — Netlify hasn't picked up the commit, keep waiting
+        if (!deploy) return { configured: true, deploy: null };
+      }
+      if (!deploy) deploy = deploys[0] || null;
+      if (!deploy) return { configured: true, deploy: null };
+      return {
+        configured: true,
+        deploy: {
+          id: deploy.id,
+          state: deploy.state,
+          branch: deploy.branch,
+          commitRef: deploy.commit_ref,
+          deployUrl: deploy.deploy_ssl_url || deploy.deploy_url,
+          adminUrl: deploy.admin_url
+            ? `${deploy.admin_url}/deploys/${deploy.id}`
+            : null,
+          createdAt: deploy.created_at,
+          updatedAt: deploy.updated_at,
+          errorMessage: deploy.error_message || null,
+          title: deploy.title || null,
+        },
+      };
+    },
+  };
+}

package/src/adapters/cdn-proxy-media.mjs

@@ -0,0 +1,79 @@
+import { sanitize } from "./_shared.mjs";
+
+/**
+ * CDN-backed media adapter that proxies requests to a remote media
+ * service expecting Bearer-token auth (e.g. the natilon media-cdn lambda).
+ *
+ * The admin server calls these methods server-side, so the browser never
+ * needs to talk to the CDN directly — eliminating CORS friction and
+ * keeping the media JWT off the client.
+ *
+ * Backend contract (mirrors the lambda):
+ *   GET /             → { folders: string[] }
+ *   GET /{folder}/    → { items, page, pages, total }
+ *   POST /_upload     → { key, ... }
+ *
+ * @param {Object} opts
+ * @param {string} opts.baseUrl              e.g. "https://media.natilon.com"
+ * @param {() => string} opts.getToken       Returns a fresh JWT each call.
+ * @returns {{
+ *   listFolders: () => Promise<object>,
+ *   listFolder: (folder: string, q?: {page?: number, perPage?: number, search?: string}) => Promise<object>,
+ *   upload: (payload: object) => Promise<object>,
+ * }}
+ */
+
+export function createCdnProxyMedia({ baseUrl, getToken }) {
+  const ROOT = baseUrl.replace(/\/+$/, "");
+
+  async function call(path, opts = {}) {
+    const r = await fetch(ROOT + path, {
+      ...opts,
+      headers: {
+        Authorization: `Bearer ${getToken()}`,
+        ...(opts.body ? { "Content-Type": "application/json" } : {}),
+        ...(opts.headers || {}),
+      },
+    });
+    const text = await r.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch {
+      const err = new Error(`Media backend returned non-JSON (${r.status})`);
+      err.upstreamStatus = r.status;
+      throw err;
+    }
+    if (!r.ok) {
+      const err = new Error(body?.error || `Media backend ${r.status}`);
+      err.upstreamStatus = r.status;
+      err.body = body;
+      throw err;
+    }
+    return body;
+  }
+
+  return {
+    listFolders() {
+      // `/_list/` matches CloudFront's `*/` behavior so it routes to the
+      // lambda; bare `/` would hit the S3 default behavior and 403.
+      return call("/_list/");
+    },
+
+    listFolder(folder, { page = 1, perPage = 30, search = "" } = {}) {
+      const params = new URLSearchParams({
+        page: String(page),
+        per_page: String(perPage),
+      });
+      if (search) params.set("search", search);
+      return call(`/${sanitize(folder)}/?${params.toString()}`);
+    },
+
+    upload(payload) {
+      return call("/_upload", {
+        method: "POST",
+        body: JSON.stringify(payload),
+      });
+    },
+  };
+}