@natilon/cms-server 0.8.0 → 0.10.0

package/README.md

@@ -103,3 +103,77 @@ All under `src/adapters/`. Each is a pure factory; no module-scoped state.
 JSDoc contracts in `src/adapters/types.mjs`. Swap in your own
 implementation by passing different adapter instances; the server
 glue is agnostic.
+
+## Collection listing & the content index
+
+### The problem
+
+Listing a collection traditionally fetches every entry's full JSON via GraphQL or a fallback REST approach (one request per file). On Cloudflare Workers this exceeds the 50-subrequest limit. On GitHub's GraphQL, large collections return 502 errors. The solution: **a lightweight per-collection `_index.json` manifest** containing only entry metadata (id, slug, lang, collection, title, and brief meta). The server reads one manifest per collection instead of fetching every entry.
+
+### How `_index.json` works
+
+Each collection maintains a manifest at `<pagesDir>/<collection>/_index.json`:
+
+```json
+{
+  "entries": [
+    {
+      "id": "entry-1",
+      "slug": "my-first-post",
+      "lang": "en",
+      "collection": "blog",
+      "title": "My First Post",
+      "file": "entry-1.json",
+      "meta": { /* custom fields from metaFields */ }
+    }
+  ]
+}
+```
+
+The index is maintained **incrementally**: `createPage`, `writePage`, and `deletePage` upsert or remove entries. On batch operations, `writeBatch` regenerates the `_index.json` in the same commit. Normal CMS edits keep the index in sync automatically — no rebuild needed.
+
+### Configuration: the `content.list` block
+
+In `cms.config.mjs`, configure listing behavior under `content.list`:
+
+```js
+content: {
+  provider: "github",
+  // ...
+  list: {
+    strategy: "index",        // default; reads _index.json
+    rebuild: "build",         // "build" (default) | "lazy"
+    indexFile: "_index.json", // manifest filename
+    resolve: undefined,       // optional: custom listing function
+  },
+}
+```
+
+| Option    | Values                  | Description |
+| --------- | ----------------------- | ----------- |
+| `strategy` | `"index"` | Built-in strategy: reads the `_index.json` manifest. Only option currently shipped. |
+| `rebuild` | `"build"` (default), `"lazy"` | **`"build"`**: server never cold-rebuilds an index at request time. If missing, returns empty and logs a warning to run the CLI. Safest for serverless (avoids subrequest blowups). **`"lazy"`**: if an index is missing, the server bootstraps it with one GraphQL request and persists it. Convenient for small/self-hosted setups, but risky on very large collections (GraphQL may fail). |
+| `indexFile` | string | Override the manifest filename (default: `_index.json`). |
+| `resolve` | `async (collection, { sortConfig }) => entries[] \| null` | Optional: bring your own listing logic. Completely replaces the built-in strategy. Return `null` for unknown collections. Plug in D1, KV, Algolia, Pagefind, or any external index here — this is the scale/search extension point. |
+
+### Out-of-band rebuild: the `build-index` CLI
+
+Regenerate all `_index.json` manifests locally:
+
+```sh
+npx natilon-cms build-index --config ./cms.config.mjs
+```
+
+Walks the local `pagesDir`, regenerates `_index.json` for every collection, and prints per-collection entry counts. Commit the result.
+
+**When to run:**
+- Once when adopting the index on an existing repo.
+- After bulk imports or migrations.
+- After content changed outside the CMS (e.g., direct git edits).
+- **Recommended in CI/deployment for serverless**: build and commit the index locally or in your CI pipeline, so the Worker only ever reads it (pairs with `rebuild: "build"`).
+
+### Quick decision guide
+
+- **Small site or self-hosted**: `rebuild: "lazy"` keeps setup simple.
+- **Serverless (Cloudflare Workers) or large collections (default, recommended)**: Use `rebuild: "build"` and run `build-index` in your build/deploy pipeline. Commit the index and the Worker reads it once per request — zero surprise subrequests.
+- **Real full-text search, faceting, or huge scale**: Provide a `resolve` hook backed by D1, KV, Algolia, Pagefind, or another external index.

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.
@@ -16,41 +19,163 @@
 
 import { pathToFileURL } from "url";
 import path from "path";
+import fs from "fs";
 import { startCmsServer } from "../src/index.mjs";
+import { buildListEntry } from "../src/adapters/_shared.mjs";
 
 const args = process.argv.slice(2).filter((a) => a !== "start");
 
+// Detect subcommand (first non-flag positional arg)
+const subcommand = process.argv.slice(2).find((a) => !a.startsWith("-"));
+
 function flag(name) {
   const i = args.indexOf(name);
   return i !== -1 ? args[i + 1] : null;
 }
 
+function boolFlag(name) {
+  return args.includes(name);
+}
+
+// Load config helper
+async function loadConfig(cfgPath) {
+  try {
+    const mod = await import(pathToFileURL(cfgPath).href);
+    const config = mod.default;
+    const publicConfig = mod.publicConfig;
+    if (!config) throw new Error("cms.config.mjs must have a default export");
+    return { config, publicConfig };
+  } catch (err) {
+    if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "ERR_LOAD_URL") {
+      console.error(`[natilon-cms] Cannot find config file: ${cfgPath}`);
+      console.error("  Create cms.config.mjs in your project root, or use --config <path>.");
+    } else {
+      console.error(`[natilon-cms] Failed to load ${cfgPath}:\n  ${err.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+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);
 const realm    = flag("--realm") || "CMS Admin";
 
-// Load the consumer's config file.
-let config, publicConfig;
-try {
-  const mod = await import(pathToFileURL(cfgPath).href);
-  config = mod.default;
-  publicConfig = mod.publicConfig; // optional — server auto-derives if absent
-  if (!config) throw new Error("cms.config.mjs must have a default export");
-} catch (err) {
-  if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "ERR_LOAD_URL") {
-    console.error(`[natilon-cms] Cannot find config file: ${cfgPath}`);
-    console.error("  Create cms.config.mjs in your project root, or use --config <path>.");
-  } else {
-    console.error(`[natilon-cms] Failed to load ${cfgPath}:\n  ${err.message}`);
+// Handle build-index subcommand
+if (subcommand === "build-index") {
+  const { config } = await loadConfig(cfgPath);
+
+  const pagesDir = config.content?.pagesDir;
+  if (!pagesDir) {
+    console.error("[natilon-cms] config.content.pagesDir is not set");
+    process.exit(1);
+  }
+
+  const pagesDirAbs = path.resolve(cwd, pagesDir);
+  if (!fs.existsSync(pagesDirAbs)) {
+    console.error(`[natilon-cms] Pages directory does not exist: ${pagesDirAbs}`);
+    process.exit(1);
+  }
+
+  const indexFileName = config.content?.list?.indexFile || "_index.json";
+
+  try {
+    const collections = fs.readdirSync(pagesDirAbs);
+    let totalEntries = 0;
+
+    // Pre-pass: build slug→displayName lookup tables for every collection so
+    // relation fields (e.g. a blog's `author` combobox) can be resolved to the
+    // referenced entry's name instead of storing a raw slug.
+    const lookups = {};
+    for (const collectionName of collections) {
+      if (collectionName.startsWith(".")) continue;
+      const collectionPath = path.join(pagesDirAbs, collectionName);
+      let stat;
+      try {
+        stat = fs.statSync(collectionPath);
+      } catch {
+        continue;
+      }
+      if (!stat.isDirectory()) continue;
+
+      const table = {};
+      for (const fileName of fs.readdirSync(collectionPath)) {
+        if (fileName === indexFileName || fileName.startsWith(".")) continue;
+        if (!fileName.endsWith(".json")) continue;
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(collectionPath, fileName), "utf-8"));
+          if (data.slug) table[data.slug] = data.meta?.title || data.meta?.name || data.slug;
+        } catch {
+          // Skip files that fail to parse
+        }
+      }
+      lookups[collectionName] = table;
+    }
+
+    for (const collectionName of collections) {
+      // Skip hidden names and non-directories
+      if (collectionName.startsWith(".")) continue;
+
+      const collectionPath = path.join(pagesDirAbs, collectionName);
+      let stat;
+      try {
+        stat = fs.statSync(collectionPath);
+      } catch {
+        continue;
+      }
+      if (!stat.isDirectory()) continue;
+
+      // Read JSON files in the collection
+      const entries = [];
+      const files = fs.readdirSync(collectionPath);
+
+      for (const fileName of files) {
+        // Skip _index.json and hidden files
+        if (fileName === indexFileName || fileName.startsWith(".")) continue;
+        if (!fileName.endsWith(".json")) continue;
+
+        const filePath = path.join(collectionPath, fileName);
+        let data;
+        try {
+          const content = fs.readFileSync(filePath, "utf-8");
+          data = JSON.parse(content);
+        } catch {
+          // Skip files that fail to parse
+          continue;
+        }
+
+        entries.push(buildListEntry(config.collections?.[collectionName], collectionName, fileName, data, lookups));
+      }
+
+      // Write the index file
+      const indexPath = path.join(collectionPath, indexFileName);
+      fs.writeFileSync(indexPath, JSON.stringify({ entries }, null, 2));
+
+      console.log(`${collectionName}: ${entries.length} entries`);
+      totalEntries += entries.length;
+    }
+
+    console.log(`\n[natilon-cms] Indexed ${totalEntries} entries across all collections`);
+    process.exit(0);
+  } catch (err) {
+    console.error(`[natilon-cms] Failed to build index:\n  ${err.message}`);
+    process.exit(1);
   }
-  process.exit(1);
 }
 
+// Load config for server start
+let config, publicConfig;
+const { config: loadedConfig, publicConfig: loadedPublicConfig } = await loadConfig(cfgPath);
+config = loadedConfig;
+publicConfig = loadedPublicConfig;
+
 await startCmsServer({
   config,
   publicConfig,   // undefined is fine — server uses defaultPublicConfig(config)
   rootDir: cwd,
   realm,
   port,
+  dev,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natilon/cms-server",
-  "version": "0.8.0",
+  "version": "0.10.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,216 @@ 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] ?? "";
+}
+
+/**
+ * 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);
+  addFields(colConfig?.sort);
+  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 `natilon-cms 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,
+  };
+}
+
+/**
+ * Maps each relation field key of a collection to its target collection and
+ * cardinality. A metaField is treated as a relation when it declares a
+ * `collection` target (e.g. `type: "combobox", collection: "authors"`).
+ *
+ * @param {object} [colConfig]
+ * @returns {Record<string, { collection: string, multiple: boolean }>}
+ */
+export function relationFields(colConfig) {
+  const map = {};
+  for (const f of colConfig?.metaFields || []) {
+    if (f && f.key && typeof f.collection === "string") {
+      map[f.key] = { collection: f.collection, multiple: !!f.multiple };
+    }
+  }
+  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 table = lookups[rel.collection];
+    if (!table) continue;
+    const get = (slug) => (table instanceof Map ? table.get(slug) : table[slug]);
+    const resolveOne = (slug) => {
+      const name = get(slug);
+      return name != null && name !== "" ? name : slug;
+    };
+    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.
  *

package/src/adapters/fs-json-content.mjs

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
-import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue } from "./_shared.mjs";
+import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue, buildListEntry, relationFields } from "./_shared.mjs";
 
 const HISTORY_KEEP = 50; // max revisions kept per file
 
@@ -24,6 +24,7 @@ export function createFsJsonContent({
   publishBranch,
   publishPaths,
   commitMessage,
+  collections = {},
 }) {
   const PAGES_DIR = path.join(rootDir, pagesDir);
   const HISTORY_DIR = path.join(rootDir, ".cms-history");
@@ -72,18 +73,32 @@ export function createFsJsonContent({
     async listPages(collection, sortConfig = null) {
       const dir = path.join(PAGES_DIR, sanitize(collection));
       if (!fs.existsSync(dir)) return null;
+
+      // Build slug→displayName lookups for collections referenced by this
+      // collection's relation fields, so list columns/filters show names
+      // instead of raw slugs.
+      const lookups = {};
+      for (const { collection: target } of Object.values(relationFields(collections[collection]))) {
+        if (lookups[target]) continue;
+        const targetDir = path.join(PAGES_DIR, sanitize(target));
+        if (!fs.existsSync(targetDir)) continue;
+        const table = {};
+        for (const f of fs.readdirSync(targetDir)) {
+          if (!f.endsWith(".json") || f === "_index.json") continue;
+          try {
+            const d = JSON.parse(fs.readFileSync(path.join(targetDir, f), "utf-8"));
+            if (d.slug) table[d.slug] = d.meta?.title || d.meta?.name || d.slug;
+          } catch {
+            // Skip unreadable entries
+          }
+        }
+        lookups[target] = table;
+      }
+
       const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
       const pages = files.map((file) => {
         const data = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
-        return {
-          id: data.id,
-          slug: data.slug,
-          lang: data.lang,
-          collection: data.collection,
-          title: data.meta?.title || data.meta?.name || file,
-          file,
-          meta: data.meta || {},
-        };
+        return buildListEntry(collections[collection], collection, file, data, lookups);
       });
       return sortPages(pages, sortConfig);
     },

package/src/adapters/github-content.mjs

@@ -1,5 +1,5 @@
 import { createGitHubApi } from "./github-api.mjs";
-import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue, commitMsg } from "./_shared.mjs";
+import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue, commitMsg, buildListEntry } from "./_shared.mjs";
 
 /**
  * GitHub Contents API adapter — serverless content backend.
@@ -7,6 +7,12 @@ import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue
  * Every writePage/createPage/deletePage is an immediate commit to GitHub.
  * No git binary required. Safe to run on Vercel, Cloudflare Workers, etc.
  *
+ * Listing strategy: each collection keeps a `_index.json` manifest that
+ * contains only the listing metadata (id, slug, lang, title, file, meta).
+ * listPages fetches this single file — 1 subrequest regardless of size.
+ * On first call (no index yet) it bootstraps via GraphQL and persists the
+ * index. All write operations keep the index in sync.
+ *
  * Config (cms.config.mjs):
  *   content: {
  *     provider: "github",
@@ -16,11 +22,14 @@ import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue
  *     branch: "main",
  *     pagesDir: "src/pages-data",
  *     commitMessage: (ts) => `Content updated ${ts}`,
+ *     list: {
+ *       strategy: "index",       // "index" (default) — only built-in strategy
+ *       rebuild: "build",        // "build" (default) | "lazy"
+ *       indexFile: "_index.json", // manifest filename
+ *       resolve: undefined,      // optional async (collection, { sortConfig }) => entries[]|null
+ *     },
  *   }
  *
- * History is backed by GitHub's commit history for each file.
- * restoreHistory treats the `ts` field as a commit SHA.
- *
  * @param {Object} opts
  * @param {string} opts.token
  * @param {string} opts.owner
@@ -28,9 +37,17 @@ import { sanitize, safeFileName, sortPages, buildDuplicateData, listScheduledDue
  * @param {string} opts.branch
  * @param {string} opts.pagesDir
  * @param {(ts: string) => string} opts.commitMessage
+ * @param {Object} [opts.list]  Listing strategy config (see above)
  * @returns {import('./types.mjs').ContentAdapter}
  */
-export function createGitHubContent({ token, owner, repo, branch, pagesDir, commitMessage }) {
+export function createGitHubContent({ token, owner, repo, branch, pagesDir, commitMessage, list = {}, collections = {} }) {
+  const listConfig = {
+    strategy: "index",
+    rebuild: "build",
+    indexFile: "_index.json",
+    resolve: undefined,
+    ...list,
+  };
   const { apiGet, apiPut, apiDelete, apiPost, apiPatch, graphql } = createGitHubApi({ token, owner, repo });
   // SHA cache: avoid extra GET before every PUT. Invalidated on write.
   const shaCache = new Map();
@@ -39,6 +56,10 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
     return `${pagesDir}/${collection}/${file}`;
   }
 
+  function indexFilePath(collection) {
+    return `${pagesDir}/${collection}/${listConfig.indexFile}`;
+  }
+
   async function getFileSha(path) {
     if (shaCache.has(path)) return shaCache.get(path);
     const data = await apiGet(`/contents/${path}?ref=${branch}`);
@@ -56,6 +77,76 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
     return Buffer.from(JSON.stringify(obj, null, 2), "utf-8").toString("base64");
   }
 
+  /** Build the listing record stored in _index.json for a single entry. */
+  function buildIndexEntry(collection, file, data) {
+    return buildListEntry(collections[collection], collection, file, data);
+  }
+
+  /** Read _index.json for a collection; returns { entries: [] } if absent. */
+  async function readIndex(collection) {
+    try {
+      const path = indexFilePath(collection);
+      const data = await apiGet(`/contents/${path}?ref=${branch}`);
+      if (!data || Array.isArray(data)) return { entries: [] };
+      shaCache.set(path, data.sha);
+      return decodeContent(data);
+    } catch {
+      return { entries: [] };
+    }
+  }
+
+  /** Persist an updated index object to _index.json (single commit). */
+  async function writeIndex(collection, index) {
+    const path = indexFilePath(collection);
+    const sha = shaCache.get(path) ?? await getFileSha(path);
+    const result = await apiPut(`/contents/${path}`, {
+      message: commitMsg(commitMessage),
+      content: encodeContent(index),
+      branch,
+      ...(sha ? { sha } : {}),
+    });
+    shaCache.set(path, result.content?.sha);
+  }
+
+  /** Add or replace one entry in _index.json, then persist. */
+  async function upsertIndexEntry(collection, file, data) {
+    const index = await readIndex(collection);
+    const entry = buildIndexEntry(collection, file, data);
+    const pos = index.entries.findIndex((e) => e.file === file);
+    if (pos >= 0) index.entries[pos] = entry;
+    else index.entries.push(entry);
+    await writeIndex(collection, index);
+  }
+
+  /** Remove one entry from _index.json, then persist. */
+  async function removeIndexEntry(collection, file) {
+    const index = await readIndex(collection);
+    index.entries = index.entries.filter((e) => e.file !== file);
+    await writeIndex(collection, index);
+  }
+
+  // GraphQL query for lazy bootstrap: fetch all blob text in one request.
+  const BOOTSTRAP_QUERY = `
+    query($owner: String!, $repo: String!, $expr: String!) {
+      repository(owner: $owner, name: $repo) {
+        object(expression: $expr) {
+          ... on Tree {
+            entries {
+              name
+              oid
+              type
+              object {
+                ... on Blob {
+                  text
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `;
+
   return {
     async listCollections() {
       const items = await apiGet(`/contents/${pagesDir}?ref=${branch}`);
@@ -64,114 +155,77 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
       return Promise.all(
         dirs.map(async (d) => {
           const files = await apiGet(`/contents/${pagesDir}/${d.name}?ref=${branch}`);
-          const count = Array.isArray(files) ? files.filter((f) => f.name.endsWith(".json")).length : 0;
+          const count = Array.isArray(files)
+            ? files.filter((f) => f.name.endsWith(".json") && f.name !== "_index.json").length
+            : 0;
           return { name: d.name, count };
         }),
       );
     },
 
-    async _listPagesRest(collection, sortConfig) {
-      const items = await apiGet(`/contents/${pagesDir}/${collection}?ref=${branch}`);
-      if (!Array.isArray(items)) return null;
-      const jsonFiles = items.filter((i) => i.type === "file" && i.name.endsWith(".json"));
-
-      const pages = await Promise.all(
-        jsonFiles.map(async (item) => {
-          shaCache.set(item.path, item.sha);
-          const r = await fetch(item.download_url, {
-            headers: {
-              Authorization: `Bearer ${token}`,
-              "User-Agent": "natilon-cms",
-            },
-          });
-          if (!r.ok) return null;
-          const data = await r.json();
-          return {
-            id: data.id,
-            slug: data.slug,
-            lang: data.lang,
-            collection: data.collection,
-            title: data.meta?.title || data.meta?.name || item.name,
-            file: item.name,
-            meta: data.meta || {},
-          };
-        }),
-      );
-
-      const valid = pages.filter(Boolean);
-      return sortPages(valid, sortConfig);
-    },
-
     async listPages(collection, sortConfig = null) {
-      // Primary path: single GraphQL request fetches all blob contents at once.
-      // Falls back to the REST N+1 path if GraphQL throws.
       const safeCollection = sanitize(collection);
-      const expression = `${branch}:${pagesDir}/${safeCollection}`;
-      const QUERY = `
-        query($owner: String!, $repo: String!, $expr: String!) {
-          repository(owner: $owner, name: $repo) {
-            object(expression: $expr) {
-              ... on Tree {
-                entries {
-                  name
-                  oid
-                  type
-                  object {
-                    ... on Blob {
-                      text
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      `;
 
-      let useRest = false;
-      let gqlData = null;
+      // 1. Custom resolver takes full control — nothing else runs.
+      if (typeof listConfig.resolve === "function") {
+        return await listConfig.resolve(collection, { sortConfig });
+      }
+
+      // 2. strategy "index": try the pre-built manifest first (1 subrequest).
+      const idxPath = indexFilePath(safeCollection);
       try {
-        gqlData = await graphql(QUERY, { owner, repo, expr: expression });
+        const data = await apiGet(`/contents/${idxPath}?ref=${branch}`);
+        if (data && !Array.isArray(data)) {
+          shaCache.set(idxPath, data.sha);
+          const index = decodeContent(data);
+          if (Array.isArray(index.entries)) {
+            return sortPages(index.entries, sortConfig);
+          }
+        }
       } catch {
-        useRest = true;
+        // Non-404 error reading index — fall through to rebuild logic.
       }
 
-      if (!useRest) {
+      // Index absent: behaviour depends on rebuild strategy.
+      if (listConfig.rebuild === "lazy") {
+        // Bootstrap: one GraphQL call fetching all blob text, then persist.
+        // On GraphQL failure, throw — never fall back to REST N+1.
+        const expression = `${branch}:${pagesDir}/${safeCollection}`;
+        const gqlData = await graphql(BOOTSTRAP_QUERY, { owner, repo, expr: expression });
+
         const treeObj = gqlData?.repository?.object;
-        // collection directory doesn't exist
-        if (treeObj === null || treeObj === undefined) {
-          // If GraphQL returned data but object is null, collection is missing
-          if (gqlData?.repository !== undefined) return null;
-          // Otherwise fall back
-          useRest = true;
-        } else {
-          const entries = treeObj.entries || [];
-          const pages = [];
-          for (const entry of entries) {
-            if (entry.type !== "blob" || !entry.name.endsWith(".json")) continue;
-            const path = `${pagesDir}/${safeCollection}/${entry.name}`;
-            shaCache.set(path, entry.oid);
-            let data;
-            try {
-              data = JSON.parse(entry.object.text);
-            } catch {
-              continue;
-            }
-            pages.push({
-              id: data.id,
-              slug: data.slug,
-              lang: data.lang,
-              collection: data.collection,
-              title: data.meta?.title || data.meta?.name || entry.name,
-              file: entry.name,
-              meta: data.meta || {},
-            });
-          }
-          return sortPages(pages, sortConfig);
+        if (!treeObj) return null;
+
+        const pages = [];
+        for (const entry of treeObj.entries || []) {
+          if (entry.type !== "blob" || !entry.name.endsWith(".json") || entry.name === listConfig.indexFile) continue;
+          shaCache.set(`${pagesDir}/${safeCollection}/${entry.name}`, entry.oid);
+          let data;
+          try { data = JSON.parse(entry.object.text); } catch { continue; }
+          pages.push(buildIndexEntry(collection, entry.name, data));
+        }
+
+        // Persist for all future calls.
+        try {
+          await writeIndex(safeCollection, { entries: pages });
+        } catch (err) {
+          console.warn(`[listPages] Could not write ${listConfig.indexFile}:`, err?.message);
         }
+
+        return sortPages(pages, sortConfig);
       }
 
-      return this._listPagesRest(collection, sortConfig);
+      // rebuild === "build" (default): never fetch all bodies at runtime.
+      // Check whether the collection directory actually exists.
+      const items = await apiGet(`/contents/${pagesDir}/${safeCollection}?ref=${branch}`);
+      if (!Array.isArray(items)) return null; // 404 or non-dir → unknown collection
+
+      // Collection exists but index hasn't been built yet.
+      console.warn(
+        `[listPages] No ${listConfig.indexFile} found for collection "${safeCollection}". ` +
+        `Run \`natilon-cms build-index\` to generate it.`,
+      );
+      return [];
     },
 
     async readPage(collection, file) {
@@ -193,6 +247,7 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
         ...(sha ? { sha } : {}),
       });
       shaCache.set(path, result.content?.sha);
+      await upsertIndexEntry(collection, file, data);
     },
 
     async createPage(collection, data) {
@@ -205,6 +260,7 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
         branch,
       });
       shaCache.set(path, result.content?.sha);
+      await upsertIndexEntry(collection, fileName, data);
       return { file: fileName };
     },
 
@@ -215,6 +271,7 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
       if (!sha) return false;
       await apiDelete(`/contents/${path}`, { message: commitMsg(commitMessage), sha, branch });
       shaCache.delete(path);
+      await removeIndexEntry(collection, file);
       return true;
     },
 
@@ -271,7 +328,7 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
       const baseCommit = await apiGet(`/git/commits/${baseCommitSha}`);
       const baseTreeSha = baseCommit.tree.sha;
 
-      // 3. Create one blob per file
+      // 3. Create one blob per content file
       const treeItems = await Promise.all(
         items.map(async ({ collection, file, data }) => {
           const filePath = contentPath(sanitize(collection), sanitize(file));
@@ -281,13 +338,31 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
         }),
       );
 
-      // 4. Create tree
-      const newTree = await apiPost(`/git/trees`, {
-        base_tree: baseTreeSha,
-        tree: treeItems,
-      });
+      // 4. Compute updated _index.json for each affected collection and add
+      //    them to the same tree so the index stays in sync atomically.
+      const byCollection = {};
+      for (const item of items) {
+        const col = sanitize(item.collection ?? item.data?.collection ?? "");
+        if (!col) continue;
+        (byCollection[col] ??= []).push(item);
+      }
+      for (const [col, colItems] of Object.entries(byCollection)) {
+        const index = await readIndex(col);
+        for (const { file, data } of colItems) {
+          const entry = buildIndexEntry(col, file, data);
+          const pos = index.entries.findIndex((e) => e.file === file);
+          if (pos >= 0) index.entries[pos] = entry;
+          else index.entries.push(entry);
+        }
+        const idxContent = Buffer.from(JSON.stringify(index, null, 2), "utf-8").toString("base64");
+        const idxBlob = await apiPost(`/git/blobs`, { content: idxContent, encoding: "base64" });
+        treeItems.push({ path: indexFilePath(col), mode: "100644", type: "blob", sha: idxBlob.sha });
+      }
+
+      // 5. Create tree
+      const newTree = await apiPost(`/git/trees`, { base_tree: baseTreeSha, tree: treeItems });
 
-      // 5. Create commit
+      // 6. Create commit
       const msg = message || commitMsg(commitMessage, "Batch content update");
       const newCommit = await apiPost(`/git/commits`, {
         message: msg,
@@ -295,13 +370,16 @@ export function createGitHubContent({ token, owner, repo, branch, pagesDir, comm
         parents: [baseCommitSha],
       });
 
-      // 6. Update ref
+      // 7. Update ref
       await apiPatch(`/git/refs/heads/${branch}`, { sha: newCommit.sha });
 
-      // 7. Invalidate shaCache for all written paths
+      // 8. Invalidate shaCache for all written paths
       for (const { collection, file } of items) {
         shaCache.delete(contentPath(sanitize(collection), sanitize(file)));
       }
+      for (const col of Object.keys(byCollection)) {
+        shaCache.delete(indexFilePath(col));
+      }
 
       return { ok: true, sha: newCommit.sha, commitCount: 1 };
     },

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/default-public-config.mjs

@@ -20,7 +20,14 @@ export function defaultPublicConfig(config, overrides = {}) {
     media:             config.media,
     collections:       config.collections,
     blocks:            config.blocks,
-    content:           { provider: config.content?.provider || "fs" },
+    content: {
+      provider: config.content?.provider || "fs",
+      list: {
+        strategy:  config.content?.list?.strategy  || "index",
+        rebuild:   config.content?.list?.rebuild   || "build",
+        indexFile: config.content?.list?.indexFile || "_index.json",
+      },
+    },
     auth:              { provider: config.auth?.provider || "basic" },
   };
   return Object.assign(cfg, overrides);

package/src/routes.mjs

@@ -25,6 +25,21 @@
 
 
 import { acquireLock, renewLock, releaseLock, getLock } from "./locks.mjs";
+import { queryPages } from "./adapters/_shared.mjs";
+import { createRequire } from "module";
+
+// Resolve the package version in a way that works in BOTH runtimes:
+//   - Node ESM: createRequire(import.meta.url) reads package.json.
+//   - Cloudflare Workers (bundled): import.meta.url is undefined, so this
+//     throws; we swallow it and fall back rather than crash the Worker.
+// (A static `import ... with { type: "json" }` works in Node but breaks
+//  wrangler's esbuild; a bare JSON import breaks Node — hence this approach.)
+let SERVER_VERSION = "unknown";
+try {
+  SERVER_VERSION = createRequire(import.meta.url)("../package.json").version;
+} catch {
+  // bundled/edge runtime — version stays "unknown"
+}
 
 function ok(json) {
   return { json };
@@ -39,6 +54,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 +89,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 });
     },
   },
 

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";
@@ -37,6 +37,8 @@ export function createCmsServer({ config, rootDir, publicConfig: publicConfigFn,
           branch: process.env.STAGING_BRANCH || config.content.branch || "main",
           pagesDir: config.content.pagesDir,
           commitMessage: config.content.commitMessage,
+          list: config.content.list,
+          collections: config.collections,
         })
       : createFsJsonContent({
           rootDir,
@@ -44,6 +46,7 @@ export function createCmsServer({ config, rootDir, publicConfig: publicConfigFn,
           publishBranch: process.env.STAGING_BRANCH || config.content.publishBranch,
           publishPaths: config.content.publishPaths,
           commitMessage: config.content.commitMessage,
+          collections: config.collections,
         });
 
   const localMedia = createLocalAssetsMedia({
@@ -266,6 +269,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.");