@natilon/cms-server 0.9.0 → 0.10.1

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

@@ -19,10 +19,15 @@
 
 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;
@@ -32,6 +37,25 @@ 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();
@@ -39,23 +63,114 @@ 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)

package/package.json

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

package/src/adapters/_shared.mjs

@@ -25,6 +25,18 @@ export function safeFileName(name) {
   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.
  *
@@ -130,6 +142,134 @@ export function pageFieldValue(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.

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, isEntryFile } 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");
@@ -64,7 +65,7 @@ export function createFsJsonContent({
       return dirs.map((dir) => {
         const files = fs
           .readdirSync(path.join(PAGES_DIR, dir))
-          .filter((f) => f.endsWith(".json"));
+          .filter(isEntryFile);
         return { name: dir, count: files.length };
       });
     },
@@ -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;
-      const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+
+      // 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 (!isEntryFile(f)) 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(isEntryFile);
       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/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

@@ -28,8 +28,18 @@ 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;
+// 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 };

package/src/server.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({