@janmarkuslanger/astro-strapi-platform 0.1.0 → 0.1.1

package/dist/strapi/mapper.js

@@ -0,0 +1,100 @@
+import { marked } from "marked";
+/**
+ * Component id of the reference block. Adapter-internal: references are
+ * resolved here and never reach the domain model.
+ */
+export const REFERENCE_COMPONENT = "blocks.reference";
+/** Populate query for a dynamic zone holding these blocks plus references. */
+export function blockPopulate(mappings) {
+    return [
+        ...Object.values(mappings).map((m) => `populate[blocks][on][${m.component}]${m.populate ?? "[populate]=*"}`),
+        `populate[blocks][on][${REFERENCE_COMPONENT}][populate]=block`,
+    ].join("&");
+}
+/**
+ * Media URLs arrive relative from Strapi ("/uploads/x.jpg"). They must become
+ * absolute against the PUBLIC base, not the build-time base — the visitor's
+ * browser loads them, not the build. See CLAUDE.md §4.
+ *
+ * Offered to every block's `map` as `ctx.image`, so no block can get this
+ * wrong — it is the classic production-only bug.
+ */
+export function mapImage(raw, mediaUrl) {
+    if (!raw)
+        return undefined;
+    const src = raw.url ?? "";
+    return {
+        src: src.startsWith("http") ? src : `${mediaUrl}${src}`,
+        alt: raw.alternativeText ?? "",
+        width: raw.width ?? undefined,
+        height: raw.height ?? undefined,
+    };
+}
+function mapLink(raw) {
+    if (!raw?.href)
+        return undefined;
+    return { label: raw.label ?? "", href: raw.href };
+}
+/** Markdown → HTML once, at build time, so components never parse content. */
+function md(value) {
+    return value ? marked.parse(String(value), { async: false }) : "";
+}
+/** The helpers handed to every `map`, bound to the public media URL. */
+export function mapContext(mediaUrl) {
+    return { image: (value) => mapImage(value, mediaUrl), markdown: md };
+}
+function mapSeo(raw, fallbackTitle) {
+    return {
+        title: raw?.title ?? fallbackTitle,
+        description: raw?.description ?? "",
+    };
+}
+/**
+ * Turns Strapi's dynamic zone into domain blocks, using the registered
+ * mappings.
+ *
+ * Unknown component ids are SKIPPED, not thrown on: a block added in the CMS
+ * before the frontend knows it must never take the site down.
+ */
+export function mapBlocks(raw, mediaUrl, mappings, resolve) {
+    const ctx = mapContext(mediaUrl);
+    const byComponent = new Map(Object.entries(mappings).map(([type, m]) => [m.component, { type, m }]));
+    const blocks = [];
+    for (const item of raw ?? []) {
+        // Resolved here, never surfaced: the domain model has no reference type,
+        // so pages cannot tell a shared block from an inline one.
+        if (item.__component === REFERENCE_COMPONENT) {
+            const id = item.block?.documentId ?? item.block?.id;
+            if (id && resolve)
+                blocks.push(...resolve(String(id)));
+            continue;
+        }
+        const entry = byComponent.get(item.__component);
+        if (!entry)
+            continue;
+        blocks.push({ ...entry.m.map(item, ctx), type: entry.type });
+    }
+    return blocks;
+}
+// Site fields first: a platform field always wins, so an extension can add
+// to a page but never change what the platform's own code relies on.
+export function mapPage(entry, mediaUrl, mappings, resolve, extension) {
+    return {
+        ...extension?.map(entry, mapContext(mediaUrl)),
+        slug: entry.slug ?? "",
+        title: entry.title ?? "",
+        seo: mapSeo(entry.seo, entry.title ?? ""),
+        blocks: mapBlocks(entry.blocks ?? [], mediaUrl, mappings, resolve),
+    };
+}
+export function mapGlobal(entry, mediaUrl, extension) {
+    const links = (raw) => (raw ?? []).map(mapLink).filter(Boolean);
+    return {
+        ...extension?.map(entry, mapContext(mediaUrl)),
+        siteName: entry.siteName ?? "",
+        claim: entry.claim ?? undefined,
+        email: entry.email ?? "",
+        navigation: links(entry.navigation),
+        footerLinks: links(entry.footerLinks),
+    };
+}

package/dist/strapi-kit/config.d.ts

@@ -0,0 +1,102 @@
+import type { Core } from "@strapi/strapi";
+/**
+ * The CMS app's config, shared by every site. Each helper has the shape of a
+ * Strapi config function, so a site's config file is one line — or spreads
+ * the result and overrides what it needs:
+ *
+ *   // config/server.ts
+ *   export default serverConfig;
+ *   // config/middlewares.ts, with one more middleware
+ *   export default (params) => [...middlewaresConfig(params), "global::my-middleware"];
+ *
+ * The environment variable names are part of the platform: the deployment
+ * docs and every site's server .env use them.
+ */
+type Params = Core.Config.Shared.ConfigParams;
+export declare const adminConfig: ({ env }: Params) => {
+    auth: {
+        secret: string | undefined;
+    };
+    apiToken: {
+        salt: string | undefined;
+    };
+    transfer: {
+        token: {
+            salt: string | undefined;
+        };
+    };
+};
+export declare const serverConfig: ({ env }: Params) => {
+    host: string;
+    port: number;
+    app: {
+        keys: string[] | undefined;
+    };
+    url: string;
+};
+/**
+ * SQLite locally, Postgres in production. Switch with DATABASE_CLIENT.
+ *
+ * @param appRoot the CMS app directory; the SQLite file (default
+ *   `.tmp/data.db`, gitignored) lives under it. Deleting it is the supported
+ *   way to re-seed.
+ */
+export declare const databaseConfig: ({ env }: Params, appRoot: string) => {
+    connection: {
+        client: string;
+        connection: {
+            host: string;
+            port: number;
+            database: string;
+            user: string;
+            password: string | undefined;
+            ssl: boolean;
+            filename?: undefined;
+        };
+        pool: {
+            min: number;
+            max: number;
+        };
+        useNullAsDefault?: undefined;
+    };
+} | {
+    connection: {
+        client: string;
+        connection: {
+            filename: string;
+            host?: undefined;
+            port?: undefined;
+            database?: undefined;
+            user?: undefined;
+            password?: undefined;
+            ssl?: undefined;
+        };
+        useNullAsDefault: boolean;
+        pool?: undefined;
+    };
+};
+export declare const middlewaresConfig: ({ env }: Params) => (string | {
+    name: string;
+    config: object;
+})[];
+export declare const pluginsConfig: ({ env }: Params) => {
+    email: {
+        config: {
+            provider: string;
+            providerOptions: {
+                host: string | undefined;
+                port: number;
+                secure: boolean;
+                auth: {
+                    user: string | undefined;
+                    pass: string | undefined;
+                };
+            };
+            settings: {
+                defaultFrom: string | undefined;
+                defaultReplyTo: string | (string & Record<never, never>) | undefined;
+            };
+        };
+    };
+};
+export {};

package/dist/strapi-kit/config.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginsConfig = exports.middlewaresConfig = exports.databaseConfig = exports.serverConfig = exports.adminConfig = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const adminConfig = ({ env }) => ({
+    auth: { secret: env("ADMIN_JWT_SECRET") },
+    apiToken: { salt: env("API_TOKEN_SALT") },
+    transfer: { token: { salt: env("TRANSFER_TOKEN_SALT") } },
+});
+exports.adminConfig = adminConfig;
+const serverConfig = ({ env }) => ({
+    host: env("HOST", "0.0.0.0"),
+    port: env.int("PORT", 1337),
+    app: { keys: env.array("APP_KEYS") },
+    // Absolute URLs Strapi generates (media, admin links) use this.
+    url: env("PUBLIC_URL", "http://127.0.0.1:1337"),
+});
+exports.serverConfig = serverConfig;
+/**
+ * SQLite locally, Postgres in production. Switch with DATABASE_CLIENT.
+ *
+ * @param appRoot the CMS app directory; the SQLite file (default
+ *   `.tmp/data.db`, gitignored) lives under it. Deleting it is the supported
+ *   way to re-seed.
+ */
+const databaseConfig = ({ env }, appRoot) => {
+    if (env("DATABASE_CLIENT", "sqlite") === "postgres") {
+        return {
+            connection: {
+                client: "postgres",
+                connection: {
+                    host: env("DATABASE_HOST", "127.0.0.1"),
+                    port: env.int("DATABASE_PORT", 5432),
+                    database: env("DATABASE_NAME", "strapi"),
+                    user: env("DATABASE_USERNAME", "strapi"),
+                    password: env("DATABASE_PASSWORD"),
+                    ssl: env.bool("DATABASE_SSL", false),
+                },
+                pool: { min: 0, max: 10 },
+            },
+        };
+    }
+    return {
+        connection: {
+            client: "sqlite",
+            connection: { filename: node_path_1.default.join(appRoot, env("DATABASE_FILENAME", ".tmp/data.db")) },
+            useNullAsDefault: true,
+        },
+    };
+};
+exports.databaseConfig = databaseConfig;
+const middlewaresConfig = ({ env }) => [
+    "strapi::logger",
+    "strapi::errors",
+    "strapi::security",
+    {
+        name: "strapi::cors",
+        config: {
+            // Restrict to the frontend domains in production. A wide-open CORS
+            // policy on a CMS that also receives form posts is an invitation.
+            origin: env.array("CORS_ORIGINS", ["http://localhost:4321"]),
+        },
+    },
+    "strapi::poweredBy",
+    "strapi::query",
+    "strapi::body",
+    "strapi::session",
+    "strapi::favicon",
+    "strapi::public",
+];
+exports.middlewaresConfig = middlewaresConfig;
+const pluginsConfig = ({ env }) => ({
+    email: {
+        config: {
+            provider: "nodemailer",
+            providerOptions: {
+                host: env("SMTP_HOST"),
+                port: env.int("SMTP_PORT", 587),
+                secure: env.bool("SMTP_SECURE", false),
+                auth: {
+                    user: env("SMTP_USERNAME"),
+                    pass: env("SMTP_PASSWORD"),
+                },
+            },
+            settings: {
+                defaultFrom: env("EMAIL_FROM"),
+                defaultReplyTo: env("EMAIL_REPLY_TO", env("EMAIL_FROM")),
+            },
+        },
+    },
+});
+exports.pluginsConfig = pluginsConfig;

package/dist/strapi-kit/index.d.ts

@@ -0,0 +1,5 @@
+export { setPublicPermissions } from "./permissions";
+export { seedContent, type SeedOptions, type SeedStep } from "./seed";
+export { registerRebuildTrigger, type RebuildOptions } from "./rebuild";
+export { PLATFORM_CONTENT_TYPES, PLATFORM_PUBLIC_ACTIONS } from "./platform";
+export { adminConfig, databaseConfig, middlewaresConfig, pluginsConfig, serverConfig, } from "./config";

package/dist/strapi-kit/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverConfig = exports.pluginsConfig = exports.middlewaresConfig = exports.databaseConfig = exports.adminConfig = exports.PLATFORM_PUBLIC_ACTIONS = exports.PLATFORM_CONTENT_TYPES = exports.registerRebuildTrigger = exports.seedContent = exports.setPublicPermissions = void 0;
+var permissions_1 = require("./permissions");
+Object.defineProperty(exports, "setPublicPermissions", { enumerable: true, get: function () { return permissions_1.setPublicPermissions; } });
+var seed_1 = require("./seed");
+Object.defineProperty(exports, "seedContent", { enumerable: true, get: function () { return seed_1.seedContent; } });
+var rebuild_1 = require("./rebuild");
+Object.defineProperty(exports, "registerRebuildTrigger", { enumerable: true, get: function () { return rebuild_1.registerRebuildTrigger; } });
+var platform_1 = require("./platform");
+Object.defineProperty(exports, "PLATFORM_CONTENT_TYPES", { enumerable: true, get: function () { return platform_1.PLATFORM_CONTENT_TYPES; } });
+Object.defineProperty(exports, "PLATFORM_PUBLIC_ACTIONS", { enumerable: true, get: function () { return platform_1.PLATFORM_PUBLIC_ACTIONS; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "adminConfig", { enumerable: true, get: function () { return config_1.adminConfig; } });
+Object.defineProperty(exports, "databaseConfig", { enumerable: true, get: function () { return config_1.databaseConfig; } });
+Object.defineProperty(exports, "middlewaresConfig", { enumerable: true, get: function () { return config_1.middlewaresConfig; } });
+Object.defineProperty(exports, "pluginsConfig", { enumerable: true, get: function () { return config_1.pluginsConfig; } });
+Object.defineProperty(exports, "serverConfig", { enumerable: true, get: function () { return config_1.serverConfig; } });

package/dist/strapi-kit/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/strapi-kit/permissions.d.ts

@@ -0,0 +1,15 @@
+import type { Core } from "@strapi/strapi";
+/**
+ * Grants the public role the given actions (e.g. "api::page.page.find"), so a
+ * statically built frontend can fetch without a token. Idempotent.
+ *
+ * Done in code rather than clicked in the panel: a fresh install has to work
+ * without a manual checklist, and a forgotten checkbox shows up as a
+ * confusing 403 during the frontend build.
+ *
+ * Note this is ROLE permission, not FIELD permission. Strapi's field-level
+ * permissions are separate and are NOT auto-granted for new fields — after
+ * adding a field, editors will report they cannot see it, and the fix is in
+ * Settings → Roles in the panel. See CLAUDE.md §5.
+ */
+export declare function setPublicPermissions(strapi: Core.Strapi, actions: string[]): Promise<void>;

package/dist/strapi-kit/permissions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPublicPermissions = setPublicPermissions;
+/**
+ * Grants the public role the given actions (e.g. "api::page.page.find"), so a
+ * statically built frontend can fetch without a token. Idempotent.
+ *
+ * Done in code rather than clicked in the panel: a fresh install has to work
+ * without a manual checklist, and a forgotten checkbox shows up as a
+ * confusing 403 during the frontend build.
+ *
+ * Note this is ROLE permission, not FIELD permission. Strapi's field-level
+ * permissions are separate and are NOT auto-granted for new fields — after
+ * adding a field, editors will report they cannot see it, and the fix is in
+ * Settings → Roles in the panel. See CLAUDE.md §5.
+ */
+async function setPublicPermissions(strapi, actions) {
+    const publicRole = await strapi.db
+        .query("plugin::users-permissions.role")
+        .findOne({ where: { type: "public" } });
+    if (!publicRole)
+        return;
+    for (const action of actions) {
+        const existing = await strapi.db
+            .query("plugin::users-permissions.permission")
+            .findOne({ where: { action, role: publicRole.id } });
+        if (!existing) {
+            await strapi.db
+                .query("plugin::users-permissions.permission")
+                .create({ data: { action, role: publicRole.id } });
+        }
+    }
+}

package/dist/strapi-kit/platform.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The content types this package's schemas define (see schemas/). A site
+ * spreads these into its own lists, so a platform type added or renamed in a
+ * new version is public and watched without a site change.
+ */
+export declare const PLATFORM_CONTENT_TYPES: string[];
+/** Read access the frontend needs to the platform types, nothing more. */
+export declare const PLATFORM_PUBLIC_ACTIONS: string[];

package/dist/strapi-kit/platform.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_PUBLIC_ACTIONS = exports.PLATFORM_CONTENT_TYPES = void 0;
+/**
+ * The content types this package's schemas define (see schemas/). A site
+ * spreads these into its own lists, so a platform type added or renamed in a
+ * new version is public and watched without a site change.
+ */
+exports.PLATFORM_CONTENT_TYPES = [
+    "api::page.page",
+    "api::shared-block.shared-block",
+    "api::global.global",
+];
+/** Read access the frontend needs to the platform types, nothing more. */
+exports.PLATFORM_PUBLIC_ACTIONS = [
+    "api::page.page.find",
+    "api::page.page.findOne",
+    "api::shared-block.shared-block.find",
+    "api::shared-block.shared-block.findOne",
+    "api::global.global.find",
+];

package/dist/strapi-kit/rebuild.d.ts

@@ -0,0 +1,47 @@
+import type { Core } from "@strapi/strapi";
+/**
+ * Triggers a rebuild of the static frontend when content changes.
+ *
+ * The site is static, so a publish is invisible until something rebuilds. This
+ * module decides *when*; HOW is a deployment detail and therefore a strategy:
+ *
+ *   hook     POST to a URL (Vercel/Netlify/Cloudflare deploy hook, or a CI
+ *            repository_dispatch endpoint). Works from anywhere.
+ *   script   run a local build script — only when the CMS and the site share a
+ *            machine. Fastest, no token, works when the internet doesn't. The
+ *            script is YOURS to write (the template ships none, because what it
+ *            does depends on the host); docs/deployment-targets.md describes
+ *            what it has to get right. Point REBUILD_SCRIPT at it.
+ *   none     rebuilds are handled elsewhere (or the site isn't live yet).
+ *
+ * Three decisions worth knowing:
+ *
+ * - **Which events count.** Content types with draft & publish only react to
+ *   publish/unpublish/delete — reacting to every save would rebuild the site
+ *   for a draft nobody should see yet. Types without draft & publish (global
+ *   settings, categories) have no publish step, so a plain update IS the
+ *   change.
+ * - **Which content types count.** Form submissions are content too, but a
+ *   visitor sending a message must never trigger a build.
+ * - **Bursts collapse.** Events are collected for a few seconds, so publishing
+ *   five pages costs one build instead of five.
+ *
+ * Configuration (all optional):
+ *   REBUILD_STRATEGY   "hook" | "script" | "none"  (default: none)
+ *   REBUILD_ENABLED    "false" disables entirely; in development it is off
+ *                      unless set to "true"
+ *   REBUILD_HOOK_URL   strategy=hook: the URL to POST to
+ *   REBUILD_SCRIPT     strategy=script: path to your build script (required —
+ *                      the default path is a convention, not a shipped file)
+ *   REBUILD_DELAY_MS   collection window (default 20000)
+ *   REBUILD_LOG        strategy=script: log file for build output
+ */
+export interface RebuildOptions {
+    /**
+     * Content types whose changes are visible on the site. Deliberately NOT
+     * here: form submissions — a visitor sending a message must not cause a
+     * deploy.
+     */
+    watched: string[];
+}
+export declare function registerRebuildTrigger(strapi: Core.Strapi, options: RebuildOptions): void;

package/dist/strapi-kit/rebuild.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRebuildTrigger = registerRebuildTrigger;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const PUBLISH_EVENTS = ["entry.publish", "entry.unpublish", "entry.delete"];
+const DIRECT_EVENTS = ["entry.create", "entry.update", "entry.delete"];
+const REPO_ROOT = node_path_1.default.resolve(process.cwd(), "..", "..");
+function resolveConfig() {
+    const enabled = process.env.REBUILD_ENABLED === "true" ||
+        (process.env.REBUILD_ENABLED !== "false" &&
+            process.env.NODE_ENV === "production");
+    return {
+        enabled,
+        strategy: (process.env.REBUILD_STRATEGY ?? "none"),
+        hookUrl: process.env.REBUILD_HOOK_URL ?? "",
+        script: process.env.REBUILD_SCRIPT ??
+            node_path_1.default.join(REPO_ROOT, "deploy", "rebuild-web.sh"),
+        delay: Number(process.env.REBUILD_DELAY_MS ?? 20_000),
+        logFile: process.env.REBUILD_LOG ??
+            node_path_1.default.resolve(REPO_ROOT, "..", "shared", "rebuild.log"),
+    };
+}
+function registerRebuildTrigger(strapi, options) {
+    const cfg = resolveConfig();
+    if (!cfg.enabled || cfg.strategy === "none") {
+        strapi.log.info(`Rebuild: inactive (strategy=${cfg.strategy}, enabled=${cfg.enabled}).`);
+        return;
+    }
+    if (cfg.strategy === "hook" && !cfg.hookUrl) {
+        strapi.log.warn("Rebuild: strategy=hook but REBUILD_HOOK_URL is empty.");
+        return;
+    }
+    if (cfg.strategy === "script" && !node_fs_1.default.existsSync(cfg.script)) {
+        strapi.log.warn(`Rebuild: script not found (${cfg.script}) — content changes will only ` +
+            "appear with the next deploy.");
+        return;
+    }
+    let timer = null;
+    let pending = 0;
+    const runHook = async () => {
+        try {
+            const res = await fetch(cfg.hookUrl, { method: "POST" });
+            if (res.ok)
+                strapi.log.info("Rebuild: hook triggered.");
+            else
+                strapi.log.warn(`Rebuild: hook returned ${res.status}.`);
+        }
+        catch (error) {
+            strapi.log.error(`Rebuild: hook failed: ${error}`);
+        }
+    };
+    const runScript = () => {
+        let out = "ignore";
+        try {
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(cfg.logFile), { recursive: true });
+            out = node_fs_1.default.openSync(cfg.logFile, "a");
+        }
+        catch (error) {
+            strapi.log.warn(`Rebuild: log file not writable (${error}).`);
+        }
+        // Detached: the build outlives this request and must not keep Strapi
+        // waiting. A failed build leaves the published site untouched.
+        const child = (0, node_child_process_1.spawn)("bash", [cfg.script], {
+            detached: true,
+            stdio: ["ignore", out, out],
+        });
+        // The child holds its own copy; keeping ours would leak one per rebuild.
+        if (typeof out === "number")
+            node_fs_1.default.closeSync(out);
+        child.on("error", (error) => strapi.log.error(`Rebuild: could not start script: ${error}`));
+        child.on("exit", (code) => {
+            if (code === 0)
+                strapi.log.info("Rebuild: site republished.");
+            else
+                strapi.log.warn(`Rebuild: script exited with ${code} — see ${cfg.logFile}.`);
+        });
+        child.unref();
+    };
+    const run = () => {
+        const count = pending;
+        timer = null;
+        pending = 0;
+        strapi.log.info(`Rebuild: starting (${count} change${count === 1 ? "" : "s"}).`);
+        if (cfg.strategy === "hook")
+            void runHook();
+        else
+            runScript();
+    };
+    const schedule = (event, uid) => {
+        pending += 1;
+        strapi.log.debug(`Rebuild: queued ${event} on ${uid}.`);
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(run, cfg.delay);
+        timer.unref?.();
+    };
+    for (const uid of options.watched) {
+        let contentType;
+        try {
+            contentType = strapi.contentType(uid);
+        }
+        catch {
+            // A content type that doesn't exist yet is not an error — the list above
+            // may run ahead of a deploy.
+            continue;
+        }
+        const events = contentType?.options?.draftAndPublish
+            ? PUBLISH_EVENTS
+            : DIRECT_EVENTS;
+        for (const event of events) {
+            strapi.eventHub.on(event, async (payload) => {
+                if (payload?.uid === uid)
+                    schedule(event, uid);
+            });
+        }
+    }
+    strapi.log.info(`Rebuild: active (strategy=${cfg.strategy}, debounce ${Math.round(cfg.delay / 1000)}s).`);
+}

package/dist/strapi-kit/schemas-cli.d.ts

@@ -0,0 +1,5 @@
+export declare function syncSchemas(appDir: string, platformDir?: string): {
+    written: number;
+    removed: number;
+};
+export declare function main(): void;