@natilon/cms-server 0.6.0 → 0.9.0

package/bin/natilon-cms.mjs

@@ -3,7 +3,10 @@
  * natilon-cms CLI
  *
  * Usage:
- *   natilon-cms [start] [--port 4001] [--config ./cms.config.mjs]
+ *   natilon-cms [start] [--port 4001] [--config ./cms.config.mjs] [--dev]
+ *
+ * --dev serves the admin UI via Vite dev middleware (HMR, no rebuild step).
+ *   Requires a linked/monorepo admin-ui source; falls back to static dist.
  *
  * Reads cms.config.mjs from the current working directory (or --config path),
  * auto-discovers the admin-ui dist, and starts the CMS server.
@@ -25,6 +28,12 @@ function flag(name) {
   return i !== -1 ? args[i + 1] : null;
 }
 
+function boolFlag(name) {
+  return args.includes(name);
+}
+
+const dev = boolFlag("--dev");
+
 const cwd      = process.cwd();
 const cfgPath  = path.resolve(cwd, flag("--config") || "cms.config.mjs");
 const port     = parseInt(flag("--port") || process.env.ADMIN_PORT || "4001", 10);
@@ -53,4 +62,5 @@ await startCmsServer({
   rootDir: cwd,
   realm,
   port,
+  dev,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natilon/cms-server",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Express-based CMS server with pluggable adapters for content, media, auth, and build.",
   "license": "MIT",
   "repository": {

package/src/adapters/_shared.mjs

@@ -39,8 +39,8 @@ export function sortPages(pages, sortConfig) {
   if (sortConfig) {
     const dir = sortConfig.direction === "desc" ? -1 : 1;
     pages.sort((a, b) => {
-      const av = a.meta?.[sortConfig.field];
-      const bv = b.meta?.[sortConfig.field];
+      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;
@@ -113,6 +113,88 @@ export async function listScheduledDue(adapter) {
   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] ?? "";
+}
+
+/**
+ * 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.
  *

package/src/admin-ui-path.mjs

@@ -19,3 +19,16 @@ export function resolveAdminUiDir() {
   const candidate = path.resolve(__dirname, "../../admin-ui/dist");
   return fs.existsSync(path.join(candidate, "index.html")) ? candidate : null;
 }
+
+/**
+ * Resolve the admin-ui source root (the Vite project root) for dev/HMR mode.
+ * Only available when the admin-ui source is present alongside cms-server
+ * (monorepo or linked checkout). Returns null when only a published dist exists.
+ */
+export function resolveAdminUiSourceDir() {
+  const candidate = path.resolve(__dirname, "../../admin-ui");
+  return fs.existsSync(path.join(candidate, "vite.config.js")) &&
+    fs.existsSync(path.join(candidate, "index.html"))
+    ? candidate
+    : null;
+}

package/src/routes.mjs

@@ -25,6 +25,11 @@
 
 
 import { acquireLock, renewLock, releaseLock, getLock } from "./locks.mjs";
+import { queryPages } from "./adapters/_shared.mjs";
+import { createRequire } from "module";
+
+const _require = createRequire(import.meta.url);
+const SERVER_VERSION = _require("../package.json").version;
 
 function ok(json) {
   return { json };
@@ -39,6 +44,14 @@ function badRequest(error) {
 }
 
 export const apiRoutes = [
+  // ── About ──────────────────────────────────────────────────────────────
+  {
+    method: "GET",
+    path: "/api/about",
+    auth: "public",
+    handler: () => ok({ serverVersion: SERVER_VERSION }),
+  },
+
   // ── Config ─────────────────────────────────────────────────────────────
   {
     method: "GET",
@@ -66,11 +79,33 @@ export const apiRoutes = [
     method: "GET",
     path: "/api/collections/:collection",
     auth: "any",
-    handler: async ({ adapters, config, params }) => {
-      const sortConfig = config.collections?.[params.collection]?.sort ?? null;
-      const pages = await adapters.content.listPages(params.collection, sortConfig);
+    handler: async ({ adapters, config, params, query }) => {
+      const col = params.collection;
+      // ?sortField and ?sortDir override the collection's static sort config
+      const sortConfig = query.sortField
+        ? { field: query.sortField, direction: query.sortDir === "desc" ? "desc" : "asc" }
+        : (config.collections?.[col]?.sort ?? null);
+      const pages = await adapters.content.listPages(col, sortConfig);
       if (pages === null) return notFound();
-      return ok(pages);
+
+      // Parse pagination params
+      const rawPerPage = query.perPage ?? query.per_page;
+      const perPage = rawPerPage === "all" ? "all" : Math.max(1, parseInt(rawPerPage, 10) || 20);
+      const page = Math.max(1, parseInt(query.page, 10) || 1);
+      const search = query.search ?? "";
+
+      // Build active filters from f_* query keys
+      const filters = {};
+      for (const [k, v] of Object.entries(query)) {
+        if (k.startsWith("f_") && v) filters[k.slice(2)] = v;
+      }
+
+      const colConfig = config.collections?.[col];
+      const searchFields = (colConfig?.listFields ?? [{ key: "title" }, { key: "lang" }, { key: "slug" }]).map((f) => f.key);
+      const filterKeys = (colConfig?.filters ?? []).map((f) => f.key);
+
+      const { items, total, facets } = queryPages(pages, { page, perPage, search, searchFields, filterKeys, filters });
+      return ok({ items, total, page, perPage, facets });
     },
   },
 
@@ -170,6 +205,35 @@ export const apiRoutes = [
     },
   },
 
+  // ── Preview URL ────────────────────────────────────────────────────────
+  // Resolves the preview URL for an entry. Supports both `config.previewUrl`
+  // (a function, called server-side with the page data) and the simpler
+  // `config.previewUrlPattern` (template string with {collection}/{slug}/{lang}).
+  {
+    method: "GET",
+    path: "/api/preview-url/:collection/:file",
+    auth: "any",
+    handler: async ({ adapters, params, config }) => {
+      const data = await adapters.content.readPage(params.collection, params.file);
+      if (!data) return notFound();
+
+      let url = null;
+      if (typeof config.previewUrl === "function") {
+        try {
+          url = config.previewUrl({ collection: params.collection, data });
+        } catch (err) {
+          return { status: 500, json: { error: `previewUrl(): ${err.message}` } };
+        }
+      } else if (config.previewUrlPattern) {
+        url = config.previewUrlPattern
+          .replace("{collection}", data.collection || params.collection)
+          .replace("{slug}", data.slug || "")
+          .replace("{lang}", data.lang || "");
+      }
+      return ok({ url });
+    },
+  },
+
   // ── History ────────────────────────────────────────────────────────────
   {
     method: "GET",

package/src/server.mjs

@@ -1,7 +1,7 @@
 import express from "express";
 import fs from "fs";
 import path from "path";
-import { resolveAdminUiDir } from "./admin-ui-path.mjs";
+import { resolveAdminUiDir, resolveAdminUiSourceDir } from "./admin-ui-path.mjs";
 import { defaultPublicConfig } from "./default-public-config.mjs";
 import { allRoutes } from "./routes.mjs";
 import { mountRoutes, buildPublicAllowlist } from "./express-shim.mjs";
@@ -266,6 +266,11 @@ export async function startCmsServer(opts) {
       : null;
 
   const adminUi = opts.adminUi ?? (() => {
+    if (opts.dev) {
+      const root = resolveAdminUiSourceDir();
+      if (root) return { mode: "vite-dev", root, base: "/admin/", previewThemeCss };
+      console.warn("admin-ui source not found — dev mode requires a linked/monorepo admin-ui. Falling back to static dist.");
+    }
     const dir = resolveAdminUiDir();
     if (!dir) {
       console.warn("admin-ui dist not found — run `npm run build:admin-ui` first, or pass adminUi option explicitly.");