@natilon/cms-server 0.1.0

package/src/adapters/types.mjs

@@ -0,0 +1,78 @@
+/**
+ * Adapter interface contracts for the natilon CMS core.
+ *
+ * These are JSDoc typedefs only — no runtime code. Concrete implementations
+ * (fs-json-content, local-assets-media, basic-auth, build-netlify) export
+ * factory functions that return objects matching these shapes.
+ *
+ * The admin server depends only on these interfaces, so swapping a backend
+ * (e.g. GitHub Contents API instead of local fs, S3 instead of local
+ * assets, OAuth instead of basic-auth) is a one-line config change.
+ */
+
+/**
+ * @typedef {Object} PageSummary
+ * @property {string} id
+ * @property {string} slug
+ * @property {string} lang
+ * @property {string} collection
+ * @property {string} title
+ * @property {string} file
+ */
+
+/**
+ * @typedef {Object} CollectionSummary
+ * @property {string} name
+ * @property {number} count
+ */
+
+/**
+ * @typedef {Object} PublishResult
+ * @property {boolean} ok
+ * @property {string} message
+ * @property {string} [sha]
+ * @property {string} [shortSha]
+ * @property {string} [branch]
+ */
+
+/**
+ * @typedef {Object} PendingChanges
+ * @property {boolean} hasChanges
+ * @property {number} changedFiles
+ */
+
+/**
+ * @typedef {Object} ContentAdapter
+ * @property {() => Promise<CollectionSummary[]>} listCollections
+ * @property {(collection: string) => Promise<PageSummary[]|null>} listPages
+ * @property {(collection: string, file: string) => Promise<object|null>} readPage
+ * @property {(collection: string, file: string, data: object) => Promise<void>} writePage
+ * @property {(collection: string, data: object) => Promise<{file: string}>} createPage
+ * @property {(collection: string, file: string) => Promise<boolean>} deletePage
+ * @property {(collection: string, file: string) => Promise<{file: string}|null>} duplicatePage
+ * @property {() => Promise<PendingChanges>} pendingChanges
+ * @property {() => Promise<PublishResult>} publish
+ */
+
+/**
+ * @typedef {Object} MediaAdapter
+ * @property {() => Promise<Record<string, string[]>>} listGrouped
+ * @property {(folder: string) => Promise<string[]>} listFolder
+ * @property {(relPath: string) => string|null} resolveLocalPath
+ */
+
+/**
+ * @typedef {Object} AuthAdapter
+ * @property {boolean} configured
+ * @property {import('express').RequestHandler} middleware
+ * @property {(allowlist: ((req: import('express').Request) => boolean)|null) => import('express').RequestHandler} middlewareWith
+ * @property {() => string} issueMediaToken
+ */
+
+/**
+ * @typedef {Object} BuildAdapter
+ * @property {boolean} configured
+ * @property {(opts?: {branch?: string, sha?: string}) => Promise<object>} getDeployStatus
+ */
+
+export {};

package/src/admin-ui-path.mjs

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the absolute path to the built admin-ui dist directory.
+ *
+ * In the monorepo the layout is:
+ *   packages/cms-server/src/   ← this file
+ *   packages/admin-ui/dist/    ← bundled SPA
+ *
+ * Returns null when the dist hasn't been built yet (development without a
+ * prior `npm run build:admin-ui`). The server will throw a helpful error
+ * via mountAdminUi rather than crashing on a missing index.html.
+ */
+export function resolveAdminUiDir() {
+  const candidate = path.resolve(__dirname, "../../admin-ui/dist");
+  return fs.existsSync(path.join(candidate, "index.html")) ? candidate : null;
+}

package/src/default-public-config.mjs

@@ -0,0 +1,23 @@
+/**
+ * Derive a safe browser-facing config from the full cms.config object.
+ *
+ * Never exposes: auth credentials env var names, build tokens, git config,
+ * GitHub OAuth secrets, content adapter internals.
+ *
+ * Used automatically by createCmsServer when the consumer does not supply
+ * their own publicConfig function.
+ *
+ * @param {Object} config  Full cms.config object
+ * @returns {Object}       Safe subset for the browser
+ */
+export function defaultPublicConfig(config) {
+  return {
+    mountPath:          config.mountPath,
+    locales:            config.locales,
+    defaultLocale:      config.defaultLocale,
+    previewUrlPattern:  config.previewUrlPattern,
+    media:              config.media,
+    collections:        config.collections,
+    blocks:             config.blocks,
+  };
+}

package/src/index.mjs

@@ -0,0 +1,12 @@
+export { createCmsServer, mountAdminUi, startCmsServer, startScheduler } from "./server.mjs";
+export { defaultPublicConfig } from "./default-public-config.mjs";
+export {
+  createFsJsonContent,
+  createGitHubContent,
+  createLocalAssetsMedia,
+  createCdnProxyMedia,
+  createBasicAuth,
+  createGitHubOAuth,
+  createNetlifyBuild,
+  createMediaUrl,
+} from "./adapters/index.mjs";

package/src/server.mjs

@@ -0,0 +1,417 @@
+import express from "express";
+import fs from "fs";
+import path from "path";
+import { resolveAdminUiDir } from "./admin-ui-path.mjs";
+import { defaultPublicConfig } from "./default-public-config.mjs";
+import {
+  createFsJsonContent,
+  createGitHubContent,
+  createLocalAssetsMedia,
+  createCdnProxyMedia,
+  createBasicAuth,
+  createGitHubOAuth,
+  createNetlifyBuild,
+} from "./adapters/index.mjs";
+
+/**
+ * Build a configured Express app for the CMS (no listen).
+ *
+ * @param {Object} opts
+ * @param {Object} opts.config              cms.config object
+ * @param {string} opts.rootDir             absolute path to consumer project root
+ * @param {() => Object} [opts.publicConfig] returns sanitized config for the browser
+ * @param {string} [opts.realm]             HTTP basic-auth realm (default "CMS Admin")
+ */
+export function createCmsServer({ config, rootDir, publicConfig: publicConfigFn, realm = "CMS Admin" }) {
+  // Auto-derive publicConfig when the consumer doesn't provide one.
+  const publicConfig = publicConfigFn ?? (() => defaultPublicConfig(config));
+  const content =
+    config.content?.provider === "github"
+      ? createGitHubContent({
+          token: process.env[config.content.githubTokenEnv || "GITHUB_TOKEN"],
+          owner: config.content.owner,
+          repo: config.content.repo,
+          branch: process.env.STAGING_BRANCH || config.content.branch || "main",
+          pagesDir: config.content.pagesDir,
+          commitMessage: config.content.commitMessage,
+        })
+      : createFsJsonContent({
+          rootDir,
+          pagesDir: config.content.pagesDir,
+          publishBranch: process.env.STAGING_BRANCH || config.content.publishBranch,
+          publishPaths: config.content.publishPaths,
+          commitMessage: config.content.commitMessage,
+        });
+
+  const localMedia = createLocalAssetsMedia({
+    rootDir,
+    assetsDir: config.content.assetsDir,
+  });
+
+  const auth =
+    config.auth?.provider === "github-oauth"
+      ? createGitHubOAuth({
+          clientId: process.env[config.auth.githubClientIdEnv || "GITHUB_CLIENT_ID"],
+          clientSecret: process.env[config.auth.githubClientSecretEnv || "GITHUB_CLIENT_SECRET"],
+          allowedLogins: config.auth.allowedLogins || [],
+          roles: config.auth.roles || {},
+          jwtSecret: process.env[config.auth.jwtSecretEnv],
+          jwtTtl: config.auth.jwtTtl,
+          realm,
+        })
+      : createBasicAuth({
+          user: process.env[config.auth.userEnv] || "admin",
+          pass: process.env[config.auth.passEnv],
+          jwtSecret: process.env[config.auth.jwtSecretEnv],
+          jwtTtl: config.auth.jwtTtl,
+          realm,
+        });
+
+  const cdnMedia = createCdnProxyMedia({
+    baseUrl: config.media.cdnBase,
+    getToken: () => auth.issueMediaToken(config.media.tenantId),
+  });
+
+  const build = createNetlifyBuild({
+    token: process.env[config.build?.netlifyTokenEnv || "NETLIFY_AUTH_TOKEN"],
+    siteId: process.env[config.build?.netlifySiteIdEnv || "NETLIFY_SITE_ID"],
+    defaultBranch: process.env.STAGING_BRANCH || config.content.publishBranch,
+  });
+
+  const app = express();
+  app.use(express.json({ limit: "10mb" }));
+
+  app.use((_req, res, next) => {
+    res.header("Access-Control-Allow-Origin", "*");
+    res.header("Access-Control-Allow-Methods", "GET,PUT,POST,DELETE,OPTIONS");
+    res.header("Access-Control-Allow-Headers", "Content-Type,Authorization");
+    if (_req.method === "OPTIONS") return res.sendStatus(204);
+    next();
+  });
+
+  // GitHub OAuth routes (unauthenticated — must be mounted before the auth guard)
+  if (auth.oauthRoutes) {
+    app.get("/admin/oauth/login", (req, res) => auth.oauthRoutes.login(req, res));
+    app.get("/admin/oauth/callback", (req, res) => auth.oauthRoutes.callback(req, res));
+  }
+
+  if (auth.configured) {
+    app.use(
+      auth.middlewareWith(
+        (req) =>
+          req.path.startsWith(`${localMedia.urlPrefix}/`) ||
+          req.path === "/api/config" ||
+          req.path.startsWith("/admin/oauth/"),
+      ),
+    );
+  } else {
+    console.warn(`WARNING: ${config.auth.passEnv} not set — running without authentication`);
+  }
+
+  const TEMPLATES_DIR = path.join(rootDir, ".cms-templates");
+
+  function sanitizeSlug(s) {
+    return String(s).replace(/[^a-zA-Z0-9._-]/g, "");
+  }
+
+  function requireAdmin(req, res, next) {
+    if (req.cmsUser && req.cmsUser.role !== "admin") {
+      return res.status(403).json({ error: "Admin role required" });
+    }
+    next();
+  }
+
+  app.get("/api/config", (_req, res) => {
+    const cfg = publicConfig ? publicConfig() : {};
+    // Always expose auth provider and previewUrlPattern to the browser
+    if (!cfg.auth) cfg.auth = {};
+    if (!cfg.auth.provider) cfg.auth.provider = config.auth?.provider || "basic";
+    if (!cfg.previewUrlPattern && config.previewUrlPattern) {
+      cfg.previewUrlPattern = config.previewUrlPattern;
+    }
+    res.json(cfg);
+  });
+
+  app.get("/api/me", (req, res) => {
+    res.json(req.cmsUser || { login: "admin", role: "admin" });
+  });
+
+  app.get("/api/collections", async (_req, res) => {
+    res.json(await content.listCollections());
+  });
+
+  app.get("/api/collections/:collection", async (req, res) => {
+    const sortConfig = config.collections?.[req.params.collection]?.sort ?? null;
+    const pages = await content.listPages(req.params.collection, sortConfig);
+    if (pages === null) return res.status(404).json({ error: "Not found" });
+    res.json(pages);
+  });
+
+  app.get("/api/collections/:collection/:file", async (req, res) => {
+    const data = await content.readPage(req.params.collection, req.params.file);
+    if (!data) return res.status(404).json({ error: "Not found" });
+    res.json(data);
+  });
+
+  app.put("/api/collections/:collection/:file", async (req, res) => {
+    await content.writePage(req.params.collection, req.params.file, req.body);
+    res.json({ ok: true });
+  });
+
+  app.post("/api/collections/:collection", async (req, res) => {
+    const result = await content.createPage(req.params.collection, req.body);
+    res.json({ ok: true, file: result.file });
+  });
+
+  app.delete("/api/collections/:collection/:file", requireAdmin, async (req, res) => {
+    const ok = await content.deletePage(req.params.collection, req.params.file);
+    if (!ok) return res.status(404).json({ error: "Not found" });
+    res.json({ ok: true });
+  });
+
+  app.post("/api/collections/:collection/:file/duplicate", async (req, res) => {
+    const result = await content.duplicatePage(req.params.collection, req.params.file);
+    if (!result) return res.status(404).json({ error: "Not found" });
+    res.json({ ok: true, file: result.file });
+  });
+
+  app.get("/api/history/:collection/:file", async (req, res) => {
+    try {
+      res.json(await content.listHistory(req.params.collection, req.params.file));
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post("/api/history/:collection/:file/:ts/restore", async (req, res) => {
+    try {
+      const ok = await content.restoreHistory(req.params.collection, req.params.file, req.params.ts);
+      if (!ok) return res.status(404).json({ error: "Revision not found" });
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.get("/api/templates", (_req, res) => {
+    if (!fs.existsSync(TEMPLATES_DIR)) return res.json([]);
+    const files = fs.readdirSync(TEMPLATES_DIR).filter((f) => f.endsWith(".json"));
+    const list = files.map((f) => {
+      const data = JSON.parse(fs.readFileSync(path.join(TEMPLATES_DIR, f), "utf-8"));
+      return { name: data.name, slug: f.replace(".json", ""), blockCount: (data.blocks || []).length };
+    });
+    res.json(list);
+  });
+
+  app.get("/api/templates/:slug", (req, res) => {
+    const file = path.join(TEMPLATES_DIR, sanitizeSlug(req.params.slug) + ".json");
+    if (!fs.existsSync(file)) return res.status(404).json({ error: "Not found" });
+    res.json(JSON.parse(fs.readFileSync(file, "utf-8")));
+  });
+
+  app.post("/api/templates", (req, res) => {
+    const { name, blocks } = req.body;
+    if (!name || !blocks) return res.status(400).json({ error: "name and blocks required" });
+    if (!fs.existsSync(TEMPLATES_DIR)) fs.mkdirSync(TEMPLATES_DIR, { recursive: true });
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const file = path.join(TEMPLATES_DIR, slug + ".json");
+    fs.writeFileSync(file, JSON.stringify({ name, blocks }, null, 2), "utf-8");
+    res.json({ ok: true, slug });
+  });
+
+  app.delete("/api/templates/:slug", requireAdmin, (req, res) => {
+    const file = path.join(TEMPLATES_DIR, sanitizeSlug(req.params.slug) + ".json");
+    if (!fs.existsSync(file)) return res.status(404).json({ error: "Not found" });
+    fs.unlinkSync(file);
+    res.json({ ok: true });
+  });
+
+  app.get("/api/assets", async (_req, res) => {
+    res.json(await localMedia.listGrouped());
+  });
+
+  app.get("/api/assets/:folder", async (req, res) => {
+    res.json(await localMedia.listFolder(req.params.folder));
+  });
+
+  app.get(`${localMedia.urlPrefix}/{*filepath}`, (req, res) => {
+    const sub = Array.isArray(req.params.filepath)
+      ? req.params.filepath.join("/")
+      : req.params.filepath;
+    const full = localMedia.resolveLocalPath(sub);
+    if (!full) return res.status(404).send("Not found");
+    res.sendFile(full);
+  });
+
+  function handleMediaError(res, err) {
+    const status = err.upstreamStatus || 500;
+    res.status(status >= 400 && status < 600 ? status : 502).json({
+      error: err.message,
+    });
+  }
+
+  app.get("/api/media/folders", async (_req, res) => {
+    try {
+      res.json(await cdnMedia.listFolders());
+    } catch (err) {
+      handleMediaError(res, err);
+    }
+  });
+
+  app.get("/api/media/folder/:folder", async (req, res) => {
+    try {
+      res.json(
+        await cdnMedia.listFolder(req.params.folder, {
+          page: parseInt(req.query.page) || 1,
+          perPage: parseInt(req.query.per_page) || 30,
+          search: req.query.search || "",
+        }),
+      );
+    } catch (err) {
+      handleMediaError(res, err);
+    }
+  });
+
+  app.post("/api/media/upload", async (req, res) => {
+    try {
+      res.json(await cdnMedia.upload(req.body));
+    } catch (err) {
+      handleMediaError(res, err);
+    }
+  });
+
+  app.post("/api/publish", requireAdmin, async (_req, res) => {
+    try {
+      const result = await content.publish();
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ ok: false, message: err.message });
+    }
+  });
+
+  app.get("/api/publish/status", async (_req, res) => {
+    try {
+      res.json(await content.pendingChanges());
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.get("/api/deploy/status", async (req, res) => {
+    if (!build.configured) return res.json({ configured: false });
+    try {
+      res.json(
+        await build.getDeployStatus({
+          branch: req.query.branch,
+          sha: req.query.sha,
+        }),
+      );
+    } catch (err) {
+      if (err.upstreamStatus) {
+        return res.status(502).json({ configured: true, error: err.message });
+      }
+      res.status(500).json({ configured: true, error: err.message });
+    }
+  });
+
+  return { app, adapters: { content, localMedia, cdnMedia, auth, build } };
+}
+
+/**
+ * Start a background scheduler that auto-publishes entries whose
+ * `meta.publishAt` timestamp has passed. Runs every 60 seconds.
+ * Returns a stop function.
+ */
+export function startScheduler(content, intervalMs = 60_000) {
+  async function run() {
+    try {
+      const due = await content.listScheduled();
+      if (!due.length) return;
+      for (const { collection, file, data } of due) {
+        delete data.meta.publishAt;
+        data.meta.draft = false;
+        await content.writePage(collection, file, data);
+        console.log(`[scheduler] Auto-published ${collection}/${file}`);
+      }
+      const result = await content.publish();
+      console.log("[scheduler] " + result.message);
+    } catch (err) {
+      console.error("[scheduler] Error:", err.message);
+    }
+  }
+  const timer = setInterval(run, intervalMs);
+  return () => clearInterval(timer);
+}
+
+/**
+ * Mount the admin UI under /admin. Three modes:
+ *   { mode: "static", dir }                       serve a prebuilt SPA bundle
+ *   { mode: "vite-dev", root, base="/admin/" }    use Vite middleware (HMR)
+ *   { mode: "auto", distDir, sourceDir }          vite-dev when NODE_ENV !== "production"
+ */
+export async function mountAdminUi(app, adminUi) {
+  if (!adminUi) return;
+
+  const resolved =
+    adminUi.mode === "auto"
+      ? process.env.NODE_ENV === "production"
+        ? { mode: "static", dir: adminUi.distDir }
+        : { mode: "vite-dev", root: adminUi.sourceDir, base: adminUi.base || "/admin/" }
+      : adminUi;
+
+  if (resolved.mode === "static") {
+    if (!fs.existsSync(path.join(resolved.dir, "index.html"))) {
+      throw new Error(
+        `admin-ui not built at ${resolved.dir}. Run the admin-ui build before starting the server in production.`,
+      );
+    }
+    app.use("/admin", express.static(resolved.dir));
+    app.get("/admin", (_req, res) => {
+      res.sendFile(path.join(resolved.dir, "index.html"));
+    });
+    return;
+  }
+
+  if (resolved.mode === "vite-dev") {
+    const { createServer: createViteServer } = await import("vite");
+    const vite = await createViteServer({
+      root: resolved.root,
+      base: resolved.base || "/admin/",
+      server: { middlewareMode: true },
+      appType: "spa",
+    });
+    app.use("/admin", vite.middlewares);
+    console.log("Admin UI: Vite dev middleware (HMR enabled)");
+    return;
+  }
+
+  throw new Error(`Unknown adminUi mode: ${resolved.mode}`);
+}
+
+/**
+ * Convenience: build the app, mount the admin UI, listen on a port.
+ * Returns { server, app, adapters }.
+ */
+export async function startCmsServer(opts) {
+  const { app, adapters } = createCmsServer(opts);
+
+  // Auto-detect admin UI dist when not explicitly configured.
+  const adminUi = opts.adminUi ?? (() => {
+    const dir = resolveAdminUiDir();
+    if (!dir) {
+      console.warn("admin-ui dist not found — run `npm run build:admin-ui` first, or pass adminUi option explicitly.");
+      return null;
+    }
+    return { mode: "static", dir };
+  })();
+
+  await mountAdminUi(app, adminUi);
+  const stopScheduler = startScheduler(adapters.content);
+  const port = opts.port || process.env.ADMIN_PORT || 4000;
+  return await new Promise((resolve) => {
+    const server = app.listen(port, () => {
+      console.log(`Admin server running at http://localhost:${port}/admin`);
+      resolve({ server, app, adapters, stopScheduler });
+    });
+  });
+}