@brightsideoy/kama 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/schema-compiler.js

@@ -30,7 +30,7 @@ async function f() {
 	if (n(f)) l = (await import(t(f).href)).compileDefinitions;
 	else if (n(p)) l = (await import(t(p).href)).compileDefinitions;
 	else try {
-		l = (await import("./dist-cK3xGnBZ.js")).compileDefinitions;
+		l = (await import("./dist-BmDMKgKk.js")).compileDefinitions;
 	} catch (e) {
 		console.error("\x1B[31m  ✖\x1B[0m \x1B[31mCould not resolve Kama Schema Engine:\x1B[0m", e), process.exit(1);
 	}

package/npm-update.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Exit immediately if any command fails
+set -e
+
+# 1. Require a target directory argument
+TARGET_DIR=$1
+if [ -z "$TARGET_DIR" ]; then
+  echo "❌ Error: Please provide the target project directory."
+  echo "Usage: ./npm-update.sh ../my-existing-project"
+  exit 1
+fi
+
+# Convert to absolute path so we don't lose it when changing directories
+TARGET_DIR=$(cd "$TARGET_DIR" && pwd)
+
+echo "🧹 1. Clearing npm cache..."
+npm cache clean --force
+
+echo "🔥 2. Building & packing KAMA package locally..."
+npm run build --loglevel error
+npm pack --loglevel error
+
+# Find the newly created tarball
+TARBALL=$(ls -1t *.tgz | head -n 1)
+
+if [ -z "$TARBALL" ]; then
+  echo "❌ Error: Failed to find the packed .tgz file."
+  exit 1
+fi
+
+# Get the absolute path to the tarball
+TARBALL_PATH="$(pwd)/$TARBALL"
+
+echo "🚀 3. Navigating to target project: $TARGET_DIR"
+cd "$TARGET_DIR"
+
+echo "🗑️ 4. Nailing old Kama modules to force fresh extraction..."
+# If we don't delete these, npm will aggressively cache the old version!
+rm -rf node_modules/@brightsideoy/kama
+if [ -d "kama-worker" ]; then rm -rf kama-worker/node_modules/@brightsideoy/kama; fi
+if [ -d "sites" ]; then rm -rf sites/*/node_modules/@brightsideoy/kama; fi
+
+echo "📦 5. Injecting fresh tarball into workspace..."
+npm install "$TARBALL_PATH" --save --loglevel error
+
+if [ -d "kama-worker" ]; then
+  echo "   -> Updating kama-worker..."
+  npm install "$TARBALL_PATH" -w kama-worker --save --loglevel error
+fi
+
+# Automatically loop through ALL frontend sites and update them
+if [ -d "sites" ]; then
+  for site in sites/*; do
+    if [ -d "$site" ]; then
+      echo "   -> Updating $site..."
+      npm install "$TARBALL_PATH" -w "$site" --save --loglevel error
+    fi
+  done
+fi
+
+echo ""
+echo "======================================================"
+echo "✨ KAMA PACKAGE UPDATED SUCCESSFULLY!"
+echo "Target: $TARGET_DIR"
+echo "======================================================"
+echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightsideoy/kama",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/astro-starter/src/layouts/StandardLayout.astro

@@ -28,11 +28,12 @@ const {
   language,
 } = Astro.props;
 
-// 🎯 Language Cascade
+// 🎯 Language Cascade: explicit prop -> node language -> fallback undefined
+// (MetaHead will resolve channel.defaultLanguage if this remains undefined)
 const pageLang = language || node?.language || undefined;
 
-// 🎯 Extract the footer blocks the backend already thoughtfully provided
-const footerBlocks = content?.footer || [];
+// ❌ Removed: const footerBlocks = content?.footer || [];
+// (The new Footer component handles its own data now!)
 ---
 
 <!doctype html>
@@ -56,7 +57,6 @@ const footerBlocks = content?.footer || [];
       </div>
     </main>
 
-    <!-- 🎯 Pass the blocks and content map directly -->
-    <Footer blocks={footerBlocks} contentMap={content} />
+    <Footer />
   </body>
 </html>

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

@@ -85,7 +85,25 @@ export const onRequest = defineMiddleware(async (context, next) => {
     }
 
     // 🎯 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;
@@ -93,12 +111,9 @@ export const onRequest = defineMiddleware(async (context, next) => {
         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
-        });
+        const mediaReq = new Request(mediaUrl, { headers: context.request.headers });
 
         let mediaResponse: Response;
-
         if (cmsWorker && typeof cmsWorker.fetch === "function") {
             mediaResponse = await cmsWorker.fetch(mediaReq);
         } else {
@@ -107,17 +122,27 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
         const newHeaders = new Headers(mediaResponse.headers);
 
-        // 🎯 DEV FIX: Only apply 1-year cache on media in Production
         if (!isDev) {
             newHeaders.set("Cache-Control", "public, max-age=31536000, s-maxage=31536000, immutable");
         }
         newHeaders.set("Access-Control-Allow-Origin", "*");
 
-        return new Response(mediaResponse.body, {
+        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
@@ -147,8 +172,11 @@ export const onRequest = defineMiddleware(async (context, next) => {
             // A. Purge Workers Caching Layer (Astro cfContext)
             if (typeof cfContext?.cache?.purge === 'function') {
                 try {
-                    await cfContext.cache.purge({ purgeEverything: true });
-                    console.log("✅ New Cloudflare Workers Cache Engine Purged");
+                    // 🎯 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);
                 }
@@ -161,22 +189,27 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
                     if (body.purge_everything) {
                         // 🎯 GLOBAL PURGE: Bumping site_version instantly invalidates ALL KV pages globally!
-                        await HTML_CACHE.put("site_version", now);
-                        // Ensure root alias is forced to new version
-                        await HTML_CACHE.put("v:/", now);
-
-                        console.log(`✅ [Version Tagging] Global site_version updated to ${now}`);
+                        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
-                        const purgeTasks = [];
-                        for (const targetUrl of body.urls) {
+                        // 🎯 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(/\/$/, "") || "/";
-
-                            purgeTasks.push(HTML_CACHE.put(`v:${cleanPath}`, now));
-                        }
+                            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);
@@ -246,18 +279,21 @@ export const onRequest = defineMiddleware(async (context, next) => {
                     let purgedKv = false;
 
                     if (HTML_CACHE) {
-                        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;
+                        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}`);
                         }
-
-                        await HTML_CACHE.delete(`v:${cleanPath}`);
                     }
 
                     const cleanUrl = targetUrl.split('?')[0];
@@ -318,17 +354,33 @@ export const onRequest = defineMiddleware(async (context, next) => {
                 HTML_CACHE.get(`v:${cleanLookupPath}`)
             ]);
 
+            // 🎯 Combine versions deterministically
             activeCacheKey = `${cleanLookupPath}:v:${siteVer || "1"}:${pageVer || "1"}`;
 
-            const cachedHtml = await HTML_CACHE.get(activeCacheKey);
-            if (cachedHtml) {
-                return new Response(cachedHtml, {
+            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,
-                        "Cache-Control": "no-store, no-cache, must-revalidate, proxy-revalidate"
+                        // 🎯 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"
                     }
                 });
             }
@@ -343,26 +395,47 @@ export const onRequest = defineMiddleware(async (context, next) => {
     // 🎯 2. KV STATIC "FILE" CACHE WRITE (Save HTML under active Version Key)
     if (
         !isDev &&
-        isHtmlPage &&
-        HTML_CACHE &&
+        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}`);
+                }
+            }
 
-                await HTML_CACHE.put(`v:${cleanLookupPath}`, forcedVersion);
+            // 🎯 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 });
 
-                const siteVer = await HTML_CACHE.get("site_version") || "1";
-                activeCacheKey = `${cleanLookupPath}:v:${siteVer}:${forcedVersion}`;
+            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}`);
             }
-
-            await HTML_CACHE.put(activeCacheKey, htmlText);
-            console.log(`✅ [Middleware] Saved HTML to KV under key: ${activeCacheKey}`);
         })();
 
         if (cfContext && typeof cfContext.waitUntil === 'function') {

package/templates/astro-starter/src/pages/[...slug].astro

@@ -26,7 +26,7 @@ Astro.response.headers.set(
   "public, no-cache, must-revalidate",
 );
 
-// 1. STATIC ASSET & SYSTEM ROUTE CHECK
+// 1. STATIC ASSET CHECK
 const staticExts = [
   ".ico",
   ".png",
@@ -36,33 +36,13 @@ const staticExts = [
   ".txt",
   ".xml",
   ".webmanifest",
-  ".astro",
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".css",
-  ".map",
-  ".json",
 ];
-
 const slugStr = String(slug || "");
-// Strip leading slashes to correctly evaluate both "src/..." and "/src/..."
-const cleanSlug = slugStr.replace(/^\/+/, "").toLowerCase();
-
-// Check extension regardless of slash placement
-const isStaticAsset = staticExts.some(ext => cleanSlug.endsWith(ext));
-
-// Block Vite client internal hits, source file paths, and node_modules
-const isSystemPath =
-  cleanSlug.startsWith("src/") ||
-  cleanSlug.startsWith("@vite/") ||
-  cleanSlug.startsWith("node_modules/") ||
-  cleanSlug.startsWith("users/") ||
-  cleanSlug.includes("components/") ||
-  cleanSlug.includes("npm-test/");
-
-if (isStaticAsset || isSystemPath) {
+const isStaticAsset =
+  !slugStr.includes("/") &&
+  staticExts.some(ext => slugStr.toLowerCase().endsWith(ext));
+
+if (isStaticAsset) {
   return new Response(null, { status: 404 });
 }
 
@@ -70,6 +50,11 @@ if (isStaticAsset || isSystemPath) {
 const safeEnv = (Astro.locals as any).safeEnv || {};
 const cmsWorker = safeEnv.CMS_WORKER;
 
+// Extract environment configuration & fallback slug
+const envHomeSlug = import.meta.env.PUBLIC_HOME_SLUG;
+const workerHomeSlug = safeEnv.PUBLIC_HOME_SLUG;
+const homeSlug = String(envHomeSlug || workerHomeSlug || "index").trim();
+
 const envApiUrl = import.meta.env.PUBLIC_API_URL;
 const workerApiUrl = safeEnv.PUBLIC_API_URL;
 const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787");
@@ -121,7 +106,8 @@ const treeId = getTreeId();
 // 3. PATH & CONCURRENT FETCH RESOLUTION
 const rawSlug = Array.isArray(slug) ? slug.join("/") : slugStr;
 const pathParts = rawSlug.split("/").filter(part => part.trim() !== "");
-const targetSlug = pathParts.join("/"); // 🎯 This is now "" for the root URL!
+const requestedSlug = pathParts.join("/");
+const targetSlug = requestedSlug || homeSlug;
 
 let pageData: NodeResponse | null = null;
 let navTree: TreeNode[] = [];
@@ -133,7 +119,6 @@ try {
       console.error(`❌ [SSR Error] Failed to fetch tree "${treeId}":`, err);
       return [];
     }),
-    // 🎯 We just pass the targetSlug (even if it's empty). The backend handles it!
     getNodeByPath(targetSlug, channelId, isPreview, customFetch).catch(err => {
       console.error(
         `❌ [SSR Error] Failed to fetch page data for path "${targetSlug}":`,
@@ -144,7 +129,7 @@ try {
   ]);
 
   navTree = treeResult || [];
-  pageData = nodeResult;
+  pageData = nodeResult as NodeResponse | null;
 } catch (err) {
   console.error("❌ [SSR Error] Failed concurrent fetch execution:", err);
 }
@@ -156,8 +141,53 @@ if (!pageData || !pageData.node) {
 const node = pageData.node;
 const content = pageData.content || {};
 
-// 🎯 Vastly simplified homepage detection!
-const isHomePage = targetSlug === "" || node?.path === "/";
+// 🎯 SMART EDGE CACHING LOGIC (Dynamic TTL Math)
+let cacheTtl = 31536000; // Default: 1 Year (Forever)
+
+const now = Date.now();
+const publishAt = node?.publishAt ? new Date(node.publishAt).getTime() : null;
+const unpublishAt = node?.unpublishAt
+  ? new Date(node.unpublishAt).getTime()
+  : null;
+
+// If the page is scheduled to appear in the future, cache the 404/current state until that exact second
+if (publishAt && publishAt > now) {
+  cacheTtl = Math.floor((publishAt - now) / 1000);
+}
+// If the page is scheduled to disappear, cache the live page until that exact second
+else if (unpublishAt && unpublishAt > now) {
+  cacheTtl = Math.floor((unpublishAt - now) / 1000);
+}
+
+// Clamp to Cloudflare's 60-second minimum for KV expirations
+cacheTtl = Math.max(60, cacheTtl);
+
+if (isTimeTraveling) {
+  Astro.response.headers.set(
+    "Cache-Control",
+    "no-cache, no-store, must-revalidate",
+  );
+} else {
+  // 🎯 FIX: max-age=0 prevents local browser caching. s-maxage handles Cloudflare CDN!
+  Astro.response.headers.set(
+    "Cache-Control",
+    `public, max-age=0, s-maxage=${cacheTtl}, must-revalidate`,
+  );
+  // Tell middleware how long to store in KV
+  Astro.response.headers.set("X-KV-Expiration", cacheTtl.toString());
+}
+
+const rootTreeSlug =
+  navTree && navTree.length > 0
+    ? navTree[0].slug || (navTree[0] as any).key
+    : "";
+
+const isHomePage =
+  targetSlug === homeSlug ||
+  (rootTreeSlug && targetSlug === rootTreeSlug) ||
+  node?.path === "/" ||
+  pathParts.length === 0;
+
 const normalizedSlug = isHomePage ? "" : targetSlug;
 
 const headerBlocks = content?.header || [];