@natilon/astro-cms 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @natilon/astro-cms
+
+Astro integration that mounts [`@natilon/cms-server`](../cms-server) +
+[`@natilon/admin-ui`](../admin-ui) into `astro dev`, so the site and
+its CMS run from a single command on a single origin.
+
+In production (`astro build`), this integration does nothing — the CMS
+is a separate Node process you deploy alongside (or behind) the static
+site. Use `@natilon/cms-server`'s `startCmsServer` for that.
+
+## Install
+
+```sh
+npm i @natilon/astro-cms @natilon/cms-server @natilon/admin-ui
+```
+
+## Usage
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import natilonCms from "@natilon/astro-cms";
+import cmsConfig, { publicConfig } from "./cms.config.mjs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  integrations: [
+    natilonCms({
+      config: cmsConfig,
+      publicConfig,
+      rootDir: __dirname,
+      adminUiSourceDir: path.join(__dirname, "node_modules/@natilon/admin-ui"),
+      realm: "My Site Admin",
+    }),
+  ],
+});
+```
+
+Now `npm run dev` boots Astro's Vite server with the admin mounted at
+`/admin`. No second process needed for local development.
+
+## Content helpers
+
+```js
+import { listEntries, getEntry } from "@natilon/astro-cms/content";
+
+// In a .astro file:
+const posts = await listEntries({
+  rootDir: process.cwd(),
+  pagesDir: "src/pages-data",
+  collection: "blog",
+  locales: ["en", "tr"],
+});
+```
+
+These read the same JSON files the CMS writes. Use them from
+`getStaticPaths()` to drive Astro routes.
+
+## Options
+
+| Option              | Type                       | Default                                |
+| ------------------- | -------------------------- | -------------------------------------- |
+| `config`            | `Object` (required)        | your `cms.config` object               |
+| `publicConfig`      | `() => Object`             | sanitizer for `/api/config`            |
+| `rootDir`           | `string`                   | Astro's `config.root`                  |
+| `adminUiSourceDir`  | `string`                   | path to `@natilon/admin-ui` package    |
+| `realm`             | `string`                   | HTTP basic-auth realm                  |

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@natilon/astro-cms",
+  "version": "0.1.0",
+  "description": "Astro integration that mounts the Natilon CMS admin under /admin during `astro dev` and exposes content helpers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/natilon/cms.git",
+    "directory": "packages/astro-cms"
+  },
+  "keywords": ["astro", "astro-integration", "cms", "natilon"],
+  "type": "module",
+  "exports": {
+    ".":        "./src/index.mjs",
+    "./content": "./src/content.mjs",
+    "./loader": "./src/loader.mjs",
+    "./schema": "./src/schema.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "@natilon/cms-server": "*",
+    "astro": "^4.0.0 || ^5.0.0",
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  }
+}

package/src/content.mjs

@@ -0,0 +1,60 @@
+import fs from "fs/promises";
+import path from "path";
+
+/**
+ * Read all JSON pages of a collection from disk.
+ * Filenames are decoded into entry objects: { slug, locale, data }.
+ *
+ * Files are expected to follow the pattern:
+ *   {locale}-{slug}.json   e.g. en-about.json
+ * Files without a recognized locale prefix are returned with locale=null.
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir       absolute project root
+ * @param {string} opts.pagesDir      relative path to pages dir (e.g. "src/pages-data")
+ * @param {string} opts.collection    collection name (subdirectory)
+ * @param {string[]} [opts.locales]   recognized locale prefixes (default ["en"])
+ */
+export async function listEntries({ rootDir, pagesDir, collection, locales = ["en"] }) {
+  const dir = path.join(rootDir, pagesDir, collection);
+  let files = [];
+  try {
+    files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const localeRe = new RegExp(`^(${locales.join("|")})-(.+)\\.json$`);
+  const entries = await Promise.all(
+    files.map(async (file) => {
+      const raw = await fs.readFile(path.join(dir, file), "utf8");
+      const data = JSON.parse(raw);
+      const m = file.match(localeRe);
+      return {
+        file,
+        slug: m ? m[2] : file.replace(/\.json$/, ""),
+        locale: m ? m[1] : null,
+        data,
+      };
+    }),
+  );
+  return entries;
+}
+
+/**
+ * Read a single JSON entry. Returns null if not found.
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir
+ * @param {string} opts.pagesDir
+ * @param {string} opts.collection
+ * @param {string} opts.file        bare filename, e.g. "en-about.json"
+ */
+export async function getEntry({ rootDir, pagesDir, collection, file }) {
+  try {
+    const full = path.join(rootDir, pagesDir, collection, file);
+    const raw = await fs.readFile(full, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}

package/src/index.mjs

@@ -0,0 +1,70 @@
+import { fileURLToPath } from "url";
+import { createCmsServer, mountAdminUi } from "@natilon/cms-server";
+
+/**
+ * Astro integration for the Natilon CMS.
+ *
+ * In `astro dev`, mounts the CMS Express app + admin UI as middleware on
+ * Astro's Vite server, so the site and `/admin` are served from one origin.
+ * In `astro build`, does nothing — the CMS is a separate process in prod.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.config              cms.config object (imported by the consumer)
+ * @param {() => Object} [opts.publicConfig] returns sanitized config for the browser
+ * @param {string} [opts.rootDir]           absolute project root (defaults to Astro's `config.root`)
+ * @param {string} [opts.adminUiSourceDir]  absolute path to the admin-ui package (for vite-dev)
+ * @param {string} [opts.realm]             HTTP basic-auth realm
+ * @returns {import("astro").AstroIntegration}
+ */
+export default function natilonCms(opts = {}) {
+  return {
+    name: "@natilon/astro-cms",
+    hooks: {
+      "astro:server:setup": async ({ server, logger }) => {
+        // server is Astro's underlying Vite dev server.
+        const rootDir = (() => {
+          if (opts.rootDir) return opts.rootDir;
+          const r = server.config?.root;
+          if (!r) return process.cwd();
+          // Vite 5+ gives an absolute path; Vite 4 gave a file:// URL.
+          if (r.startsWith("file://")) return fileURLToPath(new URL(".", r));
+          return r;
+        })();
+
+        const { app } = createCmsServer({
+          config: opts.config,
+          publicConfig: opts.publicConfig,
+          rootDir,
+          realm: opts.realm,
+        });
+
+        if (opts.adminUiSourceDir) {
+          await mountAdminUi(app, {
+            mode: "vite-dev",
+            root: opts.adminUiSourceDir,
+            base: "/admin/",
+          });
+        }
+
+        // Scope the CMS Express app to /admin and /api/* — without this,
+        // Astro's own paths (`/src/assets/*`, etc.) would be caught by the
+        // basic-auth middleware or the local-media route.
+        server.middlewares.use((req, res, next) => {
+          const url = req.url || "";
+          if (
+            url === "/admin" ||
+            url.startsWith("/admin/") ||
+            url.startsWith("/admin?") ||
+            url.startsWith("/api/")
+          ) {
+            return app(req, res, next);
+          }
+          return next();
+        });
+        logger.info("Natilon CMS mounted at /admin");
+      },
+    },
+  };
+}
+
+export { createCmsServer, mountAdminUi };

package/src/loader.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Astro Content Layer loader for Natilon CMS JSON files.
+ *
+ * Usage in src/content.config.ts:
+ *
+ *   import { jsonContentLoader } from '@natilon/astro-cms/loader';
+ *
+ *   export const collections = {
+ *     blog: defineCollection({
+ *       loader: jsonContentLoader('blog'),
+ *       schema: z.object({ title: z.string(), ... }),
+ *     }),
+ *   };
+ *
+ * Files are expected at: src/pages-data/{collection}/{locale}-{slug}.json
+ * Override the base directory via the second argument:
+ *   jsonContentLoader('blog', { pagesDir: 'content/pages' })
+ *
+ * @param {string}  collection  Collection name (subdirectory name)
+ * @param {Object}  [opts]
+ * @param {string}  [opts.pagesDir="src/pages-data"]  Relative to project root
+ */
+export function jsonContentLoader(collection, { pagesDir = "src/pages-data" } = {}) {
+  return {
+    name: `natilon-cms-${collection}`,
+
+    async load({ store, parseData, logger, watcher }) {
+      const dir = path.join(process.cwd(), pagesDir, collection);
+
+      if (!fs.existsSync(dir)) {
+        logger.warn(`[natilon-cms] ${dir} does not exist — skipping collection "${collection}"`);
+        return;
+      }
+
+      const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+      store.clear();
+
+      for (const file of files) {
+        await loadFile(path.join(dir, file), store, parseData, logger, collection);
+      }
+
+      if (!watcher) return;
+
+      watcher.add(dir);
+      watcher.on("add", async (fp) => {
+        if (fp.startsWith(dir) && fp.endsWith(".json"))
+          await loadFile(fp, store, parseData, logger, collection);
+      });
+      watcher.on("change", async (fp) => {
+        if (fp.startsWith(dir) && fp.endsWith(".json"))
+          await loadFile(fp, store, parseData, logger, collection);
+      });
+      watcher.on("unlink", (fp) => {
+        if (fp.startsWith(dir) && fp.endsWith(".json")) {
+          try {
+            const raw = JSON.parse(fs.readFileSync(fp, "utf-8"));
+            store.delete(raw.id || raw.slug);
+          } catch {}
+        }
+      });
+    },
+  };
+}
+
+async function loadFile(filePath, store, parseData, logger, collection) {
+  const file = path.basename(filePath);
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    const data = {
+      ...raw.meta,
+      // Core fields always present at the top level
+      id:         raw.id,
+      slug:       raw.slug,
+      lang:       raw.lang,
+      collection: raw.collection,
+      draft:      raw.meta?.draft ?? false,
+      publishAt:  raw.meta?.publishAt,
+      // Normalise JSON-stored arrays (stored as strings in some older entries)
+      categorySlugs: normaliseArray(raw.meta?.categorySlugs),
+      categoryNames: normaliseArray(raw.meta?.categoryNames),
+      tagSlugs:      normaliseArray(raw.meta?.tagSlugs),
+      tagNames:      normaliseArray(raw.meta?.tagNames),
+      aliases:       normaliseArray(raw.meta?.aliases),
+      // Blocks
+      blocks: raw.blocks || [],
+    };
+    const parsed = await parseData({ id: raw.id || raw.slug, data });
+    store.set({
+      id:       raw.id || raw.slug,
+      data:     parsed,
+      body:     extractHtml(raw.blocks || []),
+      rendered: { html: extractHtml(raw.blocks || []) },
+    });
+  } catch (err) {
+    logger.error(`[natilon-cms] ${collection}/${file}: ${err.message}`);
+  }
+}
+
+function normaliseArray(val) {
+  if (Array.isArray(val)) return val;
+  if (typeof val === "string") {
+    try {
+      const p = JSON.parse(val);
+      return Array.isArray(p) ? p : [];
+    } catch {
+      return val ? [val] : [];
+    }
+  }
+  return [];
+}
+
+function extractHtml(blocks) {
+  return blocks
+    .flatMap((b) => {
+      const p = b.properties || {};
+      switch (b.type) {
+        case "html":
+        case "text":       return [String(p.content ?? "")];
+        case "heading": {
+          const t = `h${Math.min(Math.max(Number(p.level ?? 2), 1), 6)}`;
+          return [`<${t}>${p.text ?? ""}</${t}>`];
+        }
+        case "image":
+          return p.src ? [`<figure><img src="${p.src}" alt="${p.alt ?? ""}" /></figure>`] : [];
+        case "blockquote": return [`<blockquote>${p.content ?? ""}</blockquote>`];
+        case "divider":    return ["<hr />"];
+        case "list": {
+          let items = [];
+          try { items = JSON.parse(p.items || "[]"); } catch {}
+          const tag = p.ordered ? "ol" : "ul";
+          return [`<${tag}>${items.map((i) => `<li>${i}</li>`).join("")}</${tag}>`];
+        }
+        default: return [];
+      }
+    })
+    .join("\n");
+}

package/src/schema.mjs

@@ -0,0 +1,82 @@
+/**
+ * Build a Zod schema from a CMS collection config.
+ *
+ * IMPORTANT: Pass Astro's own `z` instance so schemas are compatible with
+ * Astro's content layer. Do NOT import z from "zod" directly in this file.
+ *
+ * Usage in src/content.config.ts:
+ *
+ *   import { z } from 'astro:content';
+ *   import { buildCollectionSchema } from '@natilon/astro-cms/schema';
+ *   import config from '../cms.config.mjs';
+ *
+ *   export const collections = {
+ *     blog: defineCollection({
+ *       loader: jsonContentLoader('blog'),
+ *       schema: buildCollectionSchema(config.collections.blog, { z }),
+ *     }),
+ *   };
+ *
+ * Override individual fields with .extend():
+ *
+ *   schema: buildCollectionSchema(config.collections.blog, { z }).extend({
+ *     pubDate: z.coerce.date(),   // make required instead of optional
+ *   }),
+ *
+ * @param {Object} collectionConfig  A single entry from config.collections
+ * @param {{ z: import('zod').ZodStatic }} opts  Zod instance from 'astro:content'
+ * @returns {import('zod').ZodObject<any>}
+ */
+export function buildCollectionSchema(collectionConfig, { z }) {
+  const typeMap = {
+    text:             () => z.string().optional(),
+    textarea:         () => z.string().optional(),
+    richtext:         () => z.string().optional(),
+    code:             () => z.string().optional(),
+    number:           () => z.number().optional(),
+    boolean:          () => z.boolean().optional().default(false),
+    date:             () => z.coerce.date().optional(),
+    select:           (f) => f.options?.length ? z.enum(f.options).optional() : z.string().optional(),
+    image:            () => z.string().optional(),
+    "meta-image":     () => z.string().nullable().optional(),
+    json:             () => z.unknown().optional(),
+    "collection-ref": () => z.string().optional(),
+  };
+
+  const fields = {
+    // Core fields
+    title:      z.string(),
+    slug:       z.string(),
+    lang:       z.string().optional(),
+    collection: z.string().optional(),
+    // Status
+    draft:     z.boolean().optional().default(false),
+    publishAt: z.string().optional(),
+    // Common meta
+    description:    z.string().optional(),
+    seoTitle:       z.string().optional(),
+    seoDescription: z.string().optional(),
+    // Standard array fields (stored as JSON strings in older entries — loader normalises)
+    categorySlugs: z.array(z.string()).optional().default([]),
+    categoryNames: z.array(z.string()).optional().default([]),
+    tagSlugs:      z.array(z.string()).optional().default([]),
+    tagNames:      z.array(z.string()).optional().default([]),
+    aliases:       z.array(z.string()).optional().default([]),
+    // Blocks
+    blocks: z.array(
+      z.object({
+        id:         z.string(),
+        type:       z.string(),
+        properties: z.record(z.unknown()),
+        children:   z.array(z.array(z.unknown())).optional(),
+      }),
+    ).optional().default([]),
+  };
+
+  for (const field of collectionConfig?.metaFields ?? []) {
+    const builder = typeMap[field.type] ?? (() => z.string().optional());
+    fields[field.key] = builder(field);
+  }
+
+  return z.object(fields);
+}