@brightsideoy/kama 0.1.0-alpha.98 → 1.0.0-alpha.10

package/templates/astro-starter/src/middleware.ts

@@ -0,0 +1,508 @@
+// src/middleware.ts
+
+import { defineMiddleware } from "astro:middleware";
+
+/**
+ * Safely extracts environment variables across Astro 7, Node.js, and Cloudflare Workers
+ * without triggering the `@astrojs/cloudflare` runtime.env getter exception.
+ */
+async function getSafeEnv(locals: any): Promise<Record<string, any>> {
+    // 1. Try native Cloudflare Workers module (Astro 5+ / workerd)
+    try {
+        // @ts-ignore
+        const cf = await import("cloudflare:workers");
+        if (cf?.env) return cf.env;
+    } catch (e) {
+        // Not running inside a Cloudflare Worker container
+    }
+
+    // 2. Safe check for locals.runtime / cfContext (Local Node.js / Hono)
+    const runtime = locals?.runtime || locals?.cfContext;
+    if (runtime && typeof runtime === "object") {
+        if ("CMS_WORKER" in runtime || "PUBLIC_API_URL" in runtime) {
+            return runtime;
+        }
+
+        // Safely check property descriptor to avoid triggering throwing getters
+        try {
+            const desc = Object.getOwnPropertyDescriptor(runtime, "env");
+            if (desc && !desc.get) {
+                return runtime.env;
+            }
+        } catch (e) {
+            // Ignore getter throws
+        }
+    }
+
+    // 3. Fallback for standalone Node.js mode
+    return typeof process !== "undefined" ? process.env || {} : {};
+}
+
+export const onRequest = defineMiddleware(async (context, next) => {
+    const pathname = context.url.pathname;
+    const pathLower = pathname.toLowerCase();
+
+    // 🎯 Detect if we are previewing a draft or looking at a snapshot revision
+    const isPreview = context.url.searchParams.get("preview") === "true";
+    const hasRevision = context.url.searchParams.has("revisionId");
+    const isTimeTraveling = isPreview || hasRevision;
+
+    // 🎯 Detect Local Vite Dev Mode to bypass edge caching locally
+    const isDev = import.meta.env.DEV;
+
+    // 🎯 Safe dual-environment context extraction
+    const workerEnv = await getSafeEnv(context.locals);
+
+    // Attach to locals so Astro components (like Header.astro) don't have to re-evaluate it
+    (context.locals as any).safeEnv = workerEnv;
+
+    // 🎯 Safe ctx extraction (Fixing the runtime.ctx crash in Astro 6/7)
+    let cfContext = (context.locals as any).cfContext;
+    if (!cfContext) {
+        const runtime = (context.locals as any).runtime;
+        if (runtime && typeof runtime === "object") {
+            try {
+                const desc = Object.getOwnPropertyDescriptor(runtime, "ctx");
+                if (desc && !desc.get) {
+                    cfContext = runtime.ctx;
+                }
+            } catch (e) { }
+        }
+    }
+    cfContext = cfContext || {};
+
+    const HTML_CACHE = workerEnv?.HTML_CACHE; // KV Namespace binding
+
+    // 🎯 0. INSTANT EDGE SPAM DROP (Blocks bots before hit to CMS worker/database)
+    const isSpam =
+        pathLower.includes("wp-") ||
+        pathLower.includes("wordpress") ||
+        pathLower.endsWith(".php") ||
+        pathLower === "/wp";
+
+    if (isSpam) {
+        return new Response("Not Found", { status: 404 });
+    }
+
+    // 🎯 0B. DIRECT MEDIA PROXY VIA SERVICE BINDING
+    // 🎯 0B. DIRECT MEDIA PROXY VIA SERVICE BINDING WITH SURGICAL WORKER CACHING
+    if (pathname.startsWith("/media/")) {
+        const cache = typeof caches !== "undefined" && caches.default ? caches.default : null;
+        // Construct a clean cache key ignoring session headers
+        const cacheKey = new Request(context.url.toString(), { method: "GET" });
+
+        // 1. Check surgical Worker Edge Cache for pre-encoded media (15ms HIT)
+        if (!isDev && cache) {
+            try {
+                const cachedResponse = await cache.match(cacheKey);
+                if (cachedResponse) {
+                    return cachedResponse;
+                }
+            } catch (e) {
+                // Fall back to fetch if cache read fails
+            }
+        }
+
+        // 2. Cold Fetch: Pass to CMS worker for AVIF transformation
+        const cmsWorker = workerEnv?.CMS_WORKER;
+        const envApiUrl = import.meta.env?.PUBLIC_API_URL;
+        const workerApiUrl = workerEnv?.PUBLIC_API_URL;
+        const baseApiUrl = String(envApiUrl || workerApiUrl || "https://kama.kamaengine.com");
+        const cleanApiUrl = baseApiUrl.endsWith("/") ? baseApiUrl.slice(0, -1) : baseApiUrl;
+
+        const mediaUrl = `${cleanApiUrl}${pathname}${context.url.search}`;
+        const mediaReq = new Request(mediaUrl, { headers: context.request.headers });
+
+        let mediaResponse: Response;
+        if (cmsWorker && typeof cmsWorker.fetch === "function") {
+            mediaResponse = await cmsWorker.fetch(mediaReq);
+        } else {
+            mediaResponse = await fetch(mediaReq);
+        }
+
+        const newHeaders = new Headers(mediaResponse.headers);
+
+        if (!isDev) {
+            newHeaders.set("Cache-Control", "public, max-age=31536000, s-maxage=31536000, immutable");
+        }
+        newHeaders.set("Access-Control-Allow-Origin", "*");
+
+        const finalResponse = new Response(mediaResponse.body, {
+            status: mediaResponse.status,
+            statusText: mediaResponse.statusText,
+            headers: newHeaders
+        });
+
+        // 3. Store ONLY successful image transformations in Worker Edge Cache
+        if (!isDev && cache && mediaResponse.status === 200) {
+            if (cfContext && typeof cfContext.waitUntil === 'function') {
+                cfContext.waitUntil(cache.put(cacheKey, finalResponse.clone()));
+            } else {
+                cache.put(cacheKey, finalResponse.clone()).catch(() => { });
+            }
+        }
+
+        return finalResponse;
+    }
+
+    // 🎯 0C. DIRECT EDGE INTERCEPT FOR CACHE PURGE ENDPOINT
+    if (pathname === "/api/purge" || pathname === "/api/purge/") {
+        if (context.request.method !== "POST") {
+            return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
+                status: 405,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+
+        const authHeader = context.request.headers.get("Authorization");
+        const expectedToken = workerEnv.CLOUDFLARE_API_TOKEN;
+
+        if (!expectedToken || authHeader !== `Bearer ${expectedToken}`) {
+            return new Response(JSON.stringify({ error: "Unauthorized Token Mismatch" }), {
+                status: 401,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+
+        try {
+            const body = await context.request.json();
+            const cache = typeof caches !== "undefined" && caches.default ? caches.default : null;
+            const origin = context.url.origin;
+
+            // A. Purge Workers Caching Layer (Astro cfContext)
+            if (typeof cfContext?.cache?.purge === 'function') {
+                try {
+                    // 🎯 FIX: Only execute global purge if the CMS explicitly requested it!
+                    if (body.purge_everything) {
+                        await cfContext.cache.purge({ purgeEverything: true });
+                        console.log("✅ New Cloudflare Workers Cache Engine Purged (Global)");
+                    }
+                } catch (e) {
+                    console.error("❌ Failed to purge new Workers Cache Engine", e);
+                }
+            }
+
+            // B. Version-Based Instant Invalidation (0ms KV Write)
+            if (HTML_CACHE) {
+                try {
+                    const now = Date.now().toString();
+
+                    if (body.purge_everything) {
+                        // 🎯 GLOBAL PURGE: Bumping site_version instantly invalidates ALL KV pages globally!
+                        try {
+                            await HTML_CACHE.put("site_version", now);
+                            await HTML_CACHE.put("v:/", now);
+                            console.log(`✅ [Version Tagging] Global site_version updated to ${now}`);
+                        } catch (kvLimitErr: any) {
+                            console.warn(`[KV Warning] Skipped global version bump: ${kvLimitErr.message}`);
+                        }
+                    } else if (Array.isArray(body.urls) && body.urls.length > 0) {
+                        // 🎯 SURGICAL PURGE: Parallel execution for page version bumps safely wrapped for quota
+                        const purgeTasks = body.urls.map(async (targetUrl: string) => {
+                            const urlPath = new URL(targetUrl).pathname;
+                            const cleanPath = urlPath.replace(/\/$/, "") || "/";
+                            try {
+                                await HTML_CACHE.put(`v:${cleanPath}`, now);
+                            } catch (kvLimitErr: any) {
+                                console.warn(`[KV Warning] Skipped version tag for ${cleanPath}: ${kvLimitErr.message}`);
+                            }
+                        });
+                        await Promise.all(purgeTasks);
+                        console.log(`✅ [Version Tagging] Updated versions for ${body.urls.length} URLs`);
+                        // CMS CacheManager will automatically send the X-Cache-Warmer requests now!
+                    }
+                } catch (kvErr) {
+                    console.error("❌ KV Version Tagging Error:", kvErr);
+                }
+            }
+
+            // C. Global Legacy Worker Cache Purge
+            if (body.purge_everything) {
+                if (cache) {
+                    const rootUrls = [
+                        origin,
+                        `${origin}/`
+                    ];
+                    for (const url of rootUrls) {
+                        await cache.delete(new Request(url));
+                    }
+                }
+
+                return new Response(JSON.stringify({
+                    success: true,
+                    message: "All Worker Caches Purged"
+                }), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+
+            // D. Surgical Legacy Worker Cache Purge
+            if (Array.isArray(body.urls) && body.urls.length > 0) {
+                const results = [];
+
+                for (const targetUrl of body.urls) {
+                    const cleanUrl = targetUrl.split('?')[0];
+                    const urlNoSlash = cleanUrl.replace(/\/$/, "");
+                    const urlWithSlash = urlNoSlash + "/";
+                    const pathsToClear = [urlNoSlash, urlWithSlash];
+
+                    let purged = false;
+                    if (cache) {
+                        for (const p of pathsToClear) {
+                            const res = await cache.delete(new Request(p));
+                            if (res) purged = true;
+                        }
+                    }
+
+                    results.push({ url: targetUrl, purged });
+                }
+
+                return new Response(JSON.stringify({
+                    success: true,
+                    message: "URLs processed and version tags updated",
+                    results
+                }), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+
+            // 🎯 E. SURGICAL DELETION FOR DELETED PAGES
+            if (Array.isArray(body.deleted_urls) && body.deleted_urls.length > 0) {
+                const results: any[] = [];
+
+                const deleteTasks = body.deleted_urls.map(async (targetUrl: string) => {
+                    const urlPath = new URL(targetUrl).pathname;
+                    const cleanPath = urlPath.replace(/\/$/, "") || "/";
+
+                    let purgedKv = false;
+
+                    if (HTML_CACHE) {
+                        try {
+                            const [siteVer, pageVer] = await Promise.all([
+                                HTML_CACHE.get("site_version"),
+                                HTML_CACHE.get(`v:${cleanPath}`)
+                            ]);
+
+                            if (siteVer || pageVer) {
+                                const activeCacheKey = `${cleanPath}:v:${siteVer || "1"}:${pageVer || "1"}`;
+                                await HTML_CACHE.delete(activeCacheKey);
+                                purgedKv = true;
+                            }
+                            await HTML_CACHE.delete(`v:${cleanPath}`);
+                        } catch (kvLimitErr: any) {
+                            console.warn(`[KV Warning] Skipped deletion for ${cleanPath}: ${kvLimitErr.message}`);
+                        }
+                    }
+
+                    const cleanUrl = targetUrl.split('?')[0];
+                    const urlNoSlash = cleanUrl.replace(/\/$/, "");
+                    const urlWithSlash = urlNoSlash + "/";
+                    const pathsToClear = [urlNoSlash, urlWithSlash];
+
+                    let purgedLegacy = false;
+                    if (cache) {
+                        for (const p of pathsToClear) {
+                            const res = await cache.delete(new Request(p));
+                            if (res) purgedLegacy = true;
+                        }
+                    }
+
+                    results.push({ url: targetUrl, purgedKv, purgedLegacy });
+                });
+
+                await Promise.all(deleteTasks);
+
+                return new Response(JSON.stringify({
+                    success: true,
+                    message: "Deleted URLs processed and KV keys permanently removed",
+                    results
+                }), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+
+            return new Response(JSON.stringify({ error: "Invalid payload format" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+
+        } catch (err: any) {
+            return new Response(JSON.stringify({ error: err.message }), {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+    }
+
+    // 🎯 1. KV STATIC "FILE" CACHE READ WITH VERSION TAGGING
+    const isWarmer = context.request.headers.get("X-Cache-Warmer") === "true";
+    const isHtmlPage = !pathname.includes('.') && !pathname.startsWith('/api/');
+    // 🎯 The ONLY way we refer to the homepage in KV is "/"
+    const cleanLookupPath = pathname === "/index" || pathname === "/index/"
+        ? "/"
+        : (pathname.replace(/\/$/, "") || "/");
+
+    let activeCacheKey = cleanLookupPath;
+
+    if (!isDev && isHtmlPage && HTML_CACHE && !isWarmer && !isTimeTraveling) {
+        try {
+            const [siteVer, pageVer] = await Promise.all([
+                HTML_CACHE.get("site_version"),
+                HTML_CACHE.get(`v:${cleanLookupPath}`)
+            ]);
+
+            // 🎯 Combine versions deterministically
+            activeCacheKey = `${cleanLookupPath}:v:${siteVer || "1"}:${pageVer || "1"}`;
+
+            const cachedData = await HTML_CACHE.get(activeCacheKey);
+            if (cachedData) {
+                let finalHtml = cachedData;
+
+                try {
+                    if (cachedData.startsWith("{")) {
+                        const parsed = JSON.parse(cachedData);
+                        if (parsed.html) {
+                            finalHtml = parsed.html;
+                        }
+                    }
+                } catch (jsonErr) {
+                    // Fallback to raw HTML
+                }
+
+                return new Response(finalHtml, {
+                    status: 200,
+                    headers: {
+                        "Content-Type": "text/html; charset=utf-8",
+                        "X-Cache-Status": "HIT-KV-STATICFILE",
+                        "X-Cache-Key": activeCacheKey,
+                        // 🎯 ARCHITECTURE FIX: Prevent Cloudflare Edge from locking stale HTML in RAM.
+                        // Force Edge to revalidate with Worker logic while keeping browser cache fresh.
+                        "Cache-Control": "public, max-age=0, must-revalidate"
+                    }
+                });
+            }
+        } catch (e) {
+            console.warn("[Middleware] KV lookup bypass:", e);
+        }
+    }
+
+    // Process downstream SSR routes
+    const response = await next();
+
+    // 🎯 2. KV STATIC "FILE" CACHE WRITE (Save HTML under active Version Key)
+    if (
+        !isDev &&
+        isHtmlPage && HTML_CACHE &&
+        !isTimeTraveling &&
+        response.status === 200 &&
+        response.headers.get("content-type")?.includes("text/html")
+    ) {
+        const htmlText = await response.clone().text();
+
+        // Extract the TTL injected by Astro SSR
+        const kvTtlHeader = response.headers.get("X-KV-Expiration");
+        const kvTtl = kvTtlHeader ? parseInt(kvTtlHeader, 10) : undefined;
+
+        // Clean up the internal header so it doesn't leak to the public browser
+        response.headers.delete("X-KV-Expiration");
+
+        const writeTask = (async () => {
+            if (activeCacheKey === cleanLookupPath || isWarmer) {
+                const forcedVersion = Date.now().toString();
+                try {
+                    await HTML_CACHE.put(`v:${cleanLookupPath}`, forcedVersion);
+                    const siteVer = await HTML_CACHE.get("site_version") || "1";
+                    activeCacheKey = `${cleanLookupPath}:v:${siteVer}:${forcedVersion}`;
+                } catch (kvLimitErr: any) {
+                    console.warn(`[KV Warning] Skipped prewarm version bump: ${kvLimitErr.message}`);
+                }
+            }
+
+            // 🎯 Architecture Fix: Save TTL alongside HTML so CDN can properly cache reads
+            const storedTtl = kvTtl !== undefined ? Math.max(60, kvTtl) : 31536000;
+            const payload = JSON.stringify({ html: htmlText, ttl: storedTtl });
+
+            try {
+                if (kvTtl !== undefined) {
+                    await HTML_CACHE.put(activeCacheKey, payload, { expirationTtl: storedTtl });
+                    console.log(`✅ [Middleware] Saved HTML to KV under key: ${activeCacheKey} (Expires in ${storedTtl}s)`);
+                } else {
+                    await HTML_CACHE.put(activeCacheKey, payload);
+                    console.log(`✅ [Middleware] Saved HTML to KV under key: ${activeCacheKey} (Infinite TTL)`);
+                }
+            } catch (kvLimitErr: any) {
+                console.warn(`[KV Warning] Skipped HTML cache save (Quota limit exceeded): ${kvLimitErr.message}`);
+            }
+        })();
+
+        if (cfContext && typeof cfContext.waitUntil === 'function') {
+            cfContext.waitUntil(writeTask);
+        } else {
+            writeTask.catch((e: any) => console.error("KV write error:", e));
+        }
+    }
+
+    // 🎯 3. SERVE LLMS & LLXML ENDPOINTS
+    if (pathname === "/llms.txt" || pathname === "/llms-full.txt") {
+        response.headers.set("Content-Type", "text/plain; charset=utf-8");
+        response.headers.set("Cache-Control", "public, max-age=3600");
+        response.headers.set("Access-Control-Allow-Origin", "*");
+        return response;
+    }
+
+    if (pathname === "/llxml.txt") {
+        response.headers.set("Content-Type", "application/xml; charset=utf-8");
+        response.headers.set("Cache-Control", "public, max-age=3600");
+        response.headers.set("Access-Control-Allow-Origin", "*");
+        return response;
+    }
+
+    // 🎯 4. STATIC ASSET CACHING FOR COMPRESSED BUNDLES / ASSETS
+    if (!isDev) {
+        if (
+            pathname.startsWith("/_image") ||
+            pathname.startsWith("/cdn-cgi/image/") ||
+            pathname.match(/\.(png|jpg|jpeg|webp|avif|svg|gif|ico|woff2?|css|js)$/i)
+        ) {
+            response.headers.set(
+                "Cache-Control",
+                "public, max-age=31536000, s-maxage=31536000, immutable"
+            );
+            response.headers.set("Access-Control-Allow-Origin", "*");
+            return response;
+        }
+    }
+
+    // 🎯 5. SECURITY HEADERS FOR HTML PAGES
+    if (response.headers.get("content-type")?.includes("text/html")) {
+        response.headers.set("Strict-Transport-Security", "max-age=31536000; includeSubDomains; preload");
+        response.headers.set("X-Content-Type-Options", "nosniff");
+
+        // 🎯 Extract origin from env dynamically
+        const cmsUrl = workerEnv?.PUBLIC_CMS_URL || workerEnv?.PUBLIC_API_URL || "http://localhost:8787";
+        let cmsOrigin = "";
+        try {
+            cmsOrigin = new URL(cmsUrl).origin;
+        } catch (e) { }
+
+        if (isDev) {
+            response.headers.set("X-Frame-Options", "ALLOWALL");
+            response.headers.set(
+                "Content-Security-Policy",
+                "default-src 'self' http: https: data: 'unsafe-inline' 'unsafe-eval'; img-src 'self' http: https: data: blob:; connect-src 'self' http: https: ws: wss:; frame-ancestors *;"
+            );
+        } else {
+            // Production headers
+            response.headers.set("Cross-Origin-Opener-Policy", "same-origin-allow-popups");
+            response.headers.set(
+                "Content-Security-Policy",
+                `default-src 'self' https: data: 'unsafe-inline' 'unsafe-eval'; img-src 'self' https: data: blob:; connect-src 'self' https:; frame-ancestors 'self' https://*.kamaengine.com https://kama.kamaengine.com ${cmsOrigin};`
+            );
+        }
+    }
+
+    return response;
+});

package/templates/astro-starter/src/pages/404.astro

@@ -0,0 +1,46 @@
+---
+// src/pages/404.astro
+import StandardLayout from "../layouts/StandardLayout.astro";
+
+const node = {
+  title: "Page Not Found",
+  summary: "We couldn't find the page you were looking for.",
+};
+---
+
+<StandardLayout
+  node={node}
+  isHomePage={false}
+  hasSidebar={false}
+  content={{}}
+  normalizedSlug="404"
+  headerBlocks={[]}
+>
+  <div class="error-page">
+    <h1>404</h1>
+    <h2>Page Not Found</h2>
+    <p>Sorry, the page you are looking for doesn't exist or has been moved.</p>
+    <a href="/" class="button">Go back home</a>
+  </div>
+</StandardLayout>
+
+<style>
+  .error-page {
+    text-align: center;
+    padding: 100px 20px;
+  }
+  .error-page h1 {
+    font-size: 6rem;
+    margin-bottom: 0;
+    color: #0284c7;
+  }
+  .button {
+    display: inline-block;
+    margin-top: 24px;
+    padding: 12px 24px;
+    background: #0f172a;
+    color: white;
+    text-decoration: none;
+    border-radius: 4px;
+  }
+</style>