@natilon/cms-server 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @natilon/cms-server
+
+Express-based CMS server with pluggable adapters for content storage,
+media, auth, and build-status. Designed to be mounted from any Node
+process or — via [`@natilon/astro-cms`](../astro-cms) — directly into
+`astro dev`.
+
+The server is **glue code**: routes, JSON wiring, error handling. All
+behavior comes from adapter factories you instantiate from your
+`cms.config.mjs`.
+
+## Install
+
+```sh
+npm i @natilon/cms-server
+# Optional, only needed for the dev-mode admin UI middleware:
+npm i -D vite
+```
+
+## Usage
+
+```js
+// scripts/admin-server.mjs
+import path from "path";
+import { fileURLToPath } from "url";
+import { startCmsServer } from "@natilon/cms-server";
+import cmsConfig, { publicConfig } from "../cms.config.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = path.join(__dirname, "..");
+
+await startCmsServer({
+  config: cmsConfig,
+  publicConfig,
+  rootDir: ROOT_DIR,
+  realm: "My Site Admin",
+  adminUi: {
+    mode: "auto", // vite-dev when NODE_ENV !== "production", static otherwise
+    distDir: path.join(ROOT_DIR, "node_modules/@natilon/admin-ui/dist"),
+    sourceDir: path.join(ROOT_DIR, "node_modules/@natilon/admin-ui"),
+  },
+});
+```
+
+## API
+
+### `createCmsServer({ config, rootDir, publicConfig?, realm? })`
+Returns `{ app, adapters }`. Routes are already mounted; you can add
+your own middleware before/after and call `app.listen()` yourself.
+
+### `mountAdminUi(app, adminUi)`
+Mounts the admin SPA under `/admin`. Modes:
+
+- `{ mode: "static", dir }` — serves a prebuilt SPA bundle.
+- `{ mode: "vite-dev", root, base? }` — dev middleware with HMR (requires `vite`).
+- `{ mode: "auto", distDir, sourceDir }` — `vite-dev` when `NODE_ENV !== "production"`, `static` otherwise.
+
+### `startCmsServer(opts)`
+Convenience: builds the app, mounts the admin UI, listens. Returns
+`{ server, app, adapters }`.
+
+## Subpath exports
+
+- `@natilon/cms-server/media-url` — pure `createMediaUrl(mediaConfig)`
+  factory for building CDN URLs in your site code. No `express`
+  dependency, safe to import from Astro components.
+- `@natilon/cms-server/adapters` — direct access to each adapter
+  factory if you want to compose your own server.
+
+## Routes
+
+| Method  | Path                                   | Purpose                  |
+| ------- | -------------------------------------- | ------------------------ |
+| GET     | `/api/config`                          | sanitized `publicConfig` (allowlisted before auth) |
+| GET     | `/api/collections`                     | collection summaries     |
+| GET     | `/api/collections/:c`                  | list entries             |
+| GET     | `/api/collections/:c/:file`            | read entry               |
+| PUT     | `/api/collections/:c/:file`            | update entry             |
+| POST    | `/api/collections/:c`                  | create entry             |
+| DELETE  | `/api/collections/:c/:file`            | delete entry             |
+| GET     | `/api/assets`                          | grouped local-assets list (allowlisted before auth) |
+| GET     | `/api/assets/:folder`                  | files in one local folder |
+| GET     | `/api/media/folders`                   | CDN folders (proxy)      |
+| GET     | `/api/media/folder/:folder`            | CDN files (proxy)        |
+| POST    | `/api/media/upload`                    | upload to CDN (proxy)    |
+| POST    | `/api/publish`                         | git commit + push        |
+| GET     | `/api/publish/status`                  | pending changes          |
+| GET     | `/api/deploy/status`                   | Netlify deploy status    |
+
+## Adapters
+
+All under `src/adapters/`. Each is a pure factory; no module-scoped state.
+
+| Factory                  | Implements        | Notes                                  |
+| ------------------------ | ----------------- | -------------------------------------- |
+| `createFsJsonContent`    | ContentAdapter    | JSON files on disk + `git push`        |
+| `createLocalAssetsMedia` | MediaAdapter      | legacy `src/assets/` file picker       |
+| `createCdnProxyMedia`    | MediaAdapter      | proxies CloudFront/S3 listing + upload |
+| `createBasicAuth`        | AuthAdapter       | HTTP Basic + HMAC-SHA256 JWT for media |
+| `createNetlifyBuild`     | BuildAdapter      | Netlify deploy status                  |
+| `createMediaUrl`         | (URL helper)      | `cdnBase` + resize-prefix → URLs       |
+
+JSDoc contracts in `src/adapters/types.mjs`. Swap in your own
+implementation by passing different adapter instances; the server
+glue is agnostic.

package/bin/natilon-cms.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * natilon-cms CLI
+ *
+ * Usage:
+ *   natilon-cms [start] [--port 4001] [--config ./cms.config.mjs]
+ *
+ * Reads cms.config.mjs from the current working directory (or --config path),
+ * auto-discovers the admin-ui dist, and starts the CMS server.
+ *
+ * In your package.json:
+ *   "scripts": {
+ *     "admin": "node --env-file=.env node_modules/.bin/natilon-cms"
+ *   }
+ */
+
+import { pathToFileURL } from "url";
+import path from "path";
+import { startCmsServer } from "../src/index.mjs";
+
+const args = process.argv.slice(2).filter((a) => a !== "start");
+
+function flag(name) {
+  const i = args.indexOf(name);
+  return i !== -1 ? args[i + 1] : null;
+}
+
+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}`);
+  }
+  process.exit(1);
+}
+
+await startCmsServer({
+  config,
+  publicConfig,   // undefined is fine — server uses defaultPublicConfig(config)
+  rootDir: cwd,
+  realm,
+  port,
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@natilon/cms-server",
+  "version": "0.1.0",
+  "description": "Express-based CMS server with pluggable adapters for content, media, auth, and build.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/natilon/cms.git",
+    "directory": "packages/cms-server"
+  },
+  "keywords": ["cms", "headless-cms", "git-based", "astro", "express"],
+  "type": "module",
+  "bin": {
+    "natilon-cms": "./bin/natilon-cms.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./media-url": "./src/adapters/media-url.mjs",
+    "./adapters": "./src/adapters/index.mjs",
+    "./public-config": "./src/default-public-config.mjs"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "dependencies": {
+    "depd": "^2.0.0",
+    "express": "^4.21.0"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  }
+}

package/src/adapters/basic-auth.mjs

@@ -0,0 +1,81 @@
+import crypto from "crypto";
+
+/**
+ * HTTP Basic auth + HMAC-SHA256 JWT for media tokens.
+ *
+ * @param {Object} opts
+ * @param {string} opts.user
+ * @param {string|undefined} opts.pass
+ * @param {string|undefined} opts.jwtSecret
+ * @param {number} opts.jwtTtl
+ * @param {string} [opts.realm="Admin"]
+ * @returns {import('./types.mjs').AuthAdapter}
+ */
+export function createBasicAuth({
+  user,
+  pass,
+  jwtSecret,
+  jwtTtl,
+  realm = "Admin",
+}) {
+  const configured = Boolean(pass);
+
+  function issueMediaToken(tenantId) {
+    if (!jwtSecret) throw new Error("JWT_SECRET not set");
+    const header = Buffer.from(
+      JSON.stringify({ alg: "HS256", typ: "JWT" }),
+    ).toString("base64url");
+    const payload = Buffer.from(
+      JSON.stringify({
+        sub: user,
+        tenant_id: tenantId,
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + jwtTtl,
+      }),
+    ).toString("base64url");
+    const sig = crypto
+      .createHmac("sha256", jwtSecret)
+      .update(`${header}.${payload}`)
+      .digest("base64url");
+    return `${header}.${payload}.${sig}`;
+  }
+
+  function middlewareWith(allowlist) {
+    return (req, res, next) => {
+      if (allowlist && allowlist(req)) return next();
+      const auth = req.headers.authorization;
+      if (!auth || !auth.startsWith("Basic ")) {
+        res.set("WWW-Authenticate", `Basic realm="${realm}"`);
+        return res.status(401).send("Authentication required");
+      }
+      const [u, p] = Buffer.from(auth.slice(6), "base64")
+        .toString()
+        .split(":");
+      if (u === user && p === pass) {
+        req.cmsUser = { login: user, role: "admin" };
+        return next();
+      }
+      res.set("WWW-Authenticate", `Basic realm="${realm}"`);
+      res.status(401).send("Invalid credentials");
+    };
+  }
+
+  function verify(authHeader) {
+    if (!configured) return { login: user, role: "admin" };
+    if (!authHeader?.startsWith("Basic ")) return null;
+    const decoded = Buffer.from(authHeader.slice(6), "base64").toString();
+    const colon = decoded.indexOf(":");
+    const u = decoded.slice(0, colon);
+    const p = decoded.slice(colon + 1);
+    if (u === user && p === pass) return { login: user, role: "admin" };
+    return null;
+  }
+
+  return {
+    configured,
+    middleware: middlewareWith(null),
+    middlewareWith,
+    issueMediaToken,
+    verify,
+  };
+}

package/src/adapters/build-netlify.mjs

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

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

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

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

@@ -0,0 +1,248 @@
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+
+const HISTORY_KEEP = 50; // max revisions kept per file
+
+/**
+ * Filesystem-backed content adapter. Pages live as JSON files under
+ * `<rootDir>/<pagesDir>/<collection>/<file>.json`. Publishing means
+ * `git add && commit && push` to a configured branch.
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir
+ * @param {string} opts.pagesDir
+ * @param {string} opts.publishBranch
+ * @param {string[]} opts.publishPaths
+ * @param {(timestamp: string) => string} opts.commitMessage
+ * @returns {import('./types.mjs').ContentAdapter}
+ */
+export function createFsJsonContent({
+  rootDir,
+  pagesDir,
+  publishBranch,
+  publishPaths,
+  commitMessage,
+}) {
+  const PAGES_DIR = path.join(rootDir, pagesDir);
+  const HISTORY_DIR = path.join(rootDir, ".cms-history");
+  const PATHS_ARG = publishPaths.join(" ");
+
+  function historyDir(collection, file) {
+    return path.join(HISTORY_DIR, sanitize(collection), sanitize(file));
+  }
+
+  function saveHistory(collection, file) {
+    const src = pagePath(collection, file);
+    if (!fs.existsSync(src)) return;
+    const dir = historyDir(collection, file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    fs.copyFileSync(src, path.join(dir, `${ts}.json`));
+    // Prune old revisions beyond HISTORY_KEEP
+    const entries = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+    while (entries.length > HISTORY_KEEP) {
+      fs.unlinkSync(path.join(dir, entries.shift()));
+    }
+  }
+
+  function git(cmd) {
+    return execSync(`git ${cmd}`, { cwd: rootDir, encoding: "utf-8" }).trim();
+  }
+
+  function sanitize(p) {
+    return String(p).replace(/[^a-zA-Z0-9._-]/g, "");
+  }
+
+  function pagePath(collection, file) {
+    return path.join(PAGES_DIR, sanitize(collection), sanitize(file));
+  }
+
+  return {
+    async listCollections() {
+      if (!fs.existsSync(PAGES_DIR)) return [];
+      const dirs = fs
+        .readdirSync(PAGES_DIR)
+        .filter((d) => fs.statSync(path.join(PAGES_DIR, d)).isDirectory());
+      return dirs.map((dir) => {
+        const files = fs
+          .readdirSync(path.join(PAGES_DIR, dir))
+          .filter((f) => f.endsWith(".json"));
+        return { name: dir, count: files.length };
+      });
+    },
+
+    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"));
+      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 || {},
+          _sort: sortConfig ? (data.meta?.[sortConfig.field] ?? Infinity) : null,
+        };
+      });
+      if (sortConfig) {
+        const dir = sortConfig.direction === "desc" ? -1 : 1;
+        pages.sort((a, b) => {
+          if (a._sort < b._sort) return -1 * dir;
+          if (a._sort > b._sort) return 1 * dir;
+          return 0;
+        });
+      } else {
+        pages.sort((a, b) => a.title.localeCompare(b.title));
+      }
+      pages.forEach((p) => delete p._sort);
+      return pages;
+    },
+
+    async readPage(collection, file) {
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return null;
+      return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    },
+
+    async writePage(collection, file, data) {
+      saveHistory(collection, file);
+      const filePath = pagePath(collection, file);
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+    },
+
+    async createPage(collection, data) {
+      const slug = data.slug || data.id || `new-${Date.now()}`;
+      const fileName = `${sanitize(data.lang || "en")}-${sanitize(slug)}.json`;
+      const filePath = pagePath(collection, fileName);
+      const dir = path.dirname(filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+      return { file: fileName };
+    },
+
+    async deletePage(collection, file) {
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return false;
+      fs.unlinkSync(filePath);
+      return true;
+    },
+
+    async duplicatePage(collection, file) {
+      const filePath = pagePath(collection, file);
+      if (!fs.existsSync(filePath)) return null;
+      const src = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+
+      const lang = src.lang || "en";
+      const baseSlug = (src.slug || "page").replace(/-copy(-\d+)?$/, "");
+      const newSlug = `${baseSlug}-copy-${Math.floor(Date.now() / 1000)}`;
+
+      // Regenerate block IDs to avoid duplicates within the document if the
+      // same block is later edited in both copies.
+      function reid(blocks) {
+        if (!Array.isArray(blocks)) return blocks;
+        return blocks.map((b) => {
+          const next = { ...b, id: "b-" + Math.random().toString(36).slice(2, 9) };
+          if (Array.isArray(b.children)) {
+            next.children = b.children.map((col) => reid(col));
+          }
+          return next;
+        });
+      }
+
+      const data = {
+        ...src,
+        id: `${lang}/${newSlug}`,
+        slug: newSlug,
+        meta: { ...(src.meta || {}), title: `${src.meta?.title || newSlug} (Copy)` },
+        blocks: reid(src.blocks || []),
+      };
+
+      const fileName = `${sanitize(lang)}-${sanitize(newSlug)}.json`;
+      const dest = pagePath(collection, fileName);
+      const dir = path.dirname(dest);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(dest, JSON.stringify(data, null, 2), "utf-8");
+      return { file: fileName };
+    },
+
+    async pendingChanges() {
+      const status = git(`status --porcelain ${PATHS_ARG}`);
+      const hasChanges = status.length > 0;
+      const changedFiles = hasChanges
+        ? status.split("\n").filter(Boolean).length
+        : 0;
+      return { hasChanges, changedFiles };
+    },
+
+    async publish() {
+      const status = git(`status --porcelain ${PATHS_ARG}`);
+      if (!status) return { ok: false, message: "No changes to publish" };
+
+      git(`add ${PATHS_ARG}`);
+      const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+      const msg = commitMessage(timestamp);
+      git(`commit -m ${JSON.stringify(msg)}`);
+      git(`push origin HEAD:${publishBranch}`);
+
+      const shortSha = git("rev-parse --short HEAD");
+      const sha = git("rev-parse HEAD");
+      return {
+        ok: true,
+        message: `Published to ${publishBranch} (${shortSha})`,
+        sha,
+        shortSha,
+        branch: publishBranch,
+      };
+    },
+
+    async listHistory(collection, file) {
+      const dir = historyDir(collection, file);
+      if (!fs.existsSync(dir)) return [];
+      return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .sort()
+        .reverse()
+        .map((f) => {
+          const ts = f.replace(".json", "").replace(/-(\d{2})-(\d{3})$/, ".$1Z").replace(/-/g, (m, o, s) => {
+            // Reconstruct ISO: YYYY-MM-DDTHH-MM-SS-mmmZ → YYYY-MM-DDTHH:MM:SS.mmmZ
+            return s.slice(0, o).match(/T/) ? ":" : m;
+          });
+          const stat = fs.statSync(path.join(dir, f));
+          return { ts: f.replace(".json", ""), size: stat.size };
+        });
+    },
+
+    async restoreHistory(collection, file, ts) {
+      const src = path.join(historyDir(collection, file), sanitize(ts) + ".json");
+      if (!fs.existsSync(src)) return false;
+      const data = JSON.parse(fs.readFileSync(src, "utf-8"));
+      // writePage saves history of current version first, then overwrites
+      await this.writePage(collection, file, data);
+      return true;
+    },
+
+    async listScheduled() {
+      const collections = await this.listCollections();
+      const now = new Date();
+      const due = [];
+      for (const { name } of collections) {
+        const pages = await this.listPages(name);
+        for (const page of pages || []) {
+          if (page.meta?.publishAt && new Date(page.meta.publishAt) <= now) {
+            const data = await this.readPage(name, page.file);
+            if (data?.meta?.publishAt) due.push({ collection: name, file: page.file, data });
+          }
+        }
+      }
+      return due;
+    },
+  };
+}