@brightsideoy/kama 0.1.0-alpha.120 → 0.1.0-alpha.121

package/package.json

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

package/templates/astro-starter/public/css/standard-theme.css

@@ -0,0 +1,157 @@
+/* =======================================
+   1. GLOBAL RESETS & TYPOGRAPHY
+   ======================================= */
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+    border-radius: 0 !important;
+}
+
+html {
+    font-size: 16px;
+    -webkit-text-size-adjust: 100%;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+}
+
+body {
+    margin: 0;
+    padding: 0;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    font-display: swap;
+    background-color: #ffffff;
+    color: #1e293b;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    line-height: 1.65;
+    letter-spacing: -0.011em;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    color: #0f172a;
+    font-weight: 700;
+    line-height: 1.25;
+    letter-spacing: -0.022em;
+    margin-top: 1.6em;
+    margin-bottom: 0.6em;
+}
+
+h1 {
+    font-size: 2.25rem;
+}
+
+h2 {
+    font-size: 1.65rem;
+}
+
+h3 {
+    font-size: 1.35rem;
+}
+
+p {
+    margin-top: 0;
+    margin-bottom: 1.25em;
+    color: #334155;
+    font-size: 1.03rem;
+}
+
+a {
+    color: #0284c7;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 3px;
+    transition: color 0.15s ease;
+}
+
+a:hover {
+    color: #0369a1;
+}
+
+li>p:last-child {
+    margin-bottom: 0;
+}
+
+/* =======================================
+   2. MAIN LAYOUT SHELL
+   ======================================= */
+.content-block {
+    flex: 1;
+    padding: 40px 0 64px 0;
+}
+
+.content-container {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 0 24px;
+    width: 100%;
+    box-sizing: border-box;
+}
+
+/* =======================================
+   3. ROUTER REGIONS (from slug.astro)
+   ======================================= */
+.region-header {
+    margin-bottom: 24px;
+}
+
+.breadcrumb-wrapper {
+    margin-bottom: 24px;
+}
+
+.content-layout {
+    width: 100%;
+    display: block;
+}
+
+.main-column {
+    width: 100%;
+    min-width: 0;
+}
+
+@media (min-width: 768px) {
+    .content-layout.has-sidebar {
+        display: grid !important;
+        grid-template-columns: calc(100% - 360px) 310px !important;
+        column-gap: 48px !important;
+        align-items: start !important;
+    }
+
+    .main-column {
+        grid-column: 1 / 2 !important;
+    }
+
+    .sidebar-column {
+        grid-column: 2 / 3 !important;
+        position: sticky;
+        top: 32px;
+    }
+}
+
+.sidebar-column {
+    background: #f8fafc;
+    border: 1px solid #e2e8f0;
+    padding: 28px;
+    box-sizing: border-box;
+}
+
+@media (max-width: 767px) {
+    .sidebar-column {
+        margin-top: 40px;
+    }
+}
+
+.empty-content {
+    padding: 32px;
+    border: 1px dashed #cbd5e1;
+    background: #f8fafc;
+    color: #64748b;
+    font-size: 0.95rem;
+    text-align: center;
+}

package/templates/astro-starter/public/robots.txt

@@ -1 +1,23 @@
-<link rel="author" type="text/plain" href="/llms.txt" title="LLM Directory" />
+# Allow standard search engine crawlers
+User-agent: *
+Allow: /
+
+# Block sensitive or irrelevant paths
+Disallow: /api/
+Disallow: /*?*search=
+
+# Explicitly block AI scrapers / Training Bots (Optional)
+# User-agent: GPTBot
+# Disallow: /
+
+# User-agent: CCBot
+# Disallow: /
+
+# User-agent: Anthropic-ai
+# Disallow: /
+
+# User-agent: Google-Extended
+# Disallow: /
+
+# XML Sitemap location
+# Sitemap: https://yourdomain.com/sitemap-index.xml

package/templates/astro-starter/src/components/blocks/BlockRenderer.astro

@@ -4,6 +4,7 @@ import ImageBlock from "@/components/blocks/ImageBlock.astro";
 import HeaderImage from "@/components/blocks/HeaderImage.astro";
 import ColumnLayout from "@/components/blocks/ColumnLayout.astro";
 import HtmlBlock from "@/components/blocks/HtmlBlock.astro";
+import { extractHtml } from "@/utils/tiptap";
 
 interface Block {
   instanceId: number;
@@ -63,8 +64,8 @@ const visibleBlocks = safeBlocks.filter(b => {
       case "headline":
       case "header-block":
       case "header_block": {
-        const headline = data.headline || data.title || "";
-        const subhead = data.subhead || data.body || "";
+        const headline = extractHtml(data.headline || data.title);
+        const subhead = extractHtml(data.subhead || data.body);
         return (
           <header class="cms-block cms-block-header">
             {headline && <Fragment set:html={headline} />}
@@ -76,7 +77,7 @@ const visibleBlocks = safeBlocks.filter(b => {
       case "text":
       case "text-block":
       case "text_block": {
-        const bodyText = data.body || data.text || data.content || "";
+        const bodyText = extractHtml(data.body || data.text || data.content);
         return (
           <div class="cms-block cms-block-text">
             <Fragment set:html={bodyText} />
@@ -84,7 +85,6 @@ const visibleBlocks = safeBlocks.filter(b => {
         );
       }
 
-      // 🎯 Handles all HTML block component identifiers
       case "html":
       case "html-block":
       case "html_block":
@@ -99,7 +99,6 @@ const visibleBlocks = safeBlocks.filter(b => {
         );
       }
 
-      // 🎯 Handles all image component identifiers from the payload
       case "image":
       case "image-block":
       case "image_block":

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

@@ -0,0 +1,52 @@
+---
+import Header from "@/components/global/Header.astro";
+import Footer from "@/components/global/Footer.astro";
+import SeoHead from "@/components/seo/SeoHead.astro";
+import type { TreeNode, ContentBlock } from "@/lib/cms";
+
+interface Props {
+  node: Record<string, any>;
+  content: Record<string, ContentBlock[]>;
+  normalizedSlug: string;
+  isHomePage: boolean;
+  hasSidebar?: boolean;
+  headerBlocks?: ContentBlock[];
+  tree?: TreeNode[];
+}
+
+const {
+  node = {},
+  content = {},
+  normalizedSlug,
+  isHomePage,
+  headerBlocks = [],
+  tree,
+} = Astro.props;
+
+const footerBlocks = content?.footer || [];
+---
+
+<html lang="en">
+  <head>
+    <SeoHead
+      node={node}
+      content={content}
+      normalizedSlug={normalizedSlug}
+      isHomePage={isHomePage}
+      headerBlocks={headerBlocks}
+    />
+    <!-- 🎯 Standard CSS is decoupled from the bundler -->
+    <link rel="stylesheet" href="/css/standard-theme.css" />
+  </head>
+  <body>
+    <Header node={node} tree={tree} />
+
+    <main class="content-block">
+      <div class="content-container">
+        <slot />
+      </div>
+    </main>
+
+    <Footer blocks={footerBlocks} contentMap={content} />
+  </body>
+</html>

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

@@ -1,6 +1,6 @@
 ---
 // src/pages/404.astro
-import Layout from "../layouts/Layout.astro";
+import StandardLayout from "../layouts/StandardLayout.astro";
 
 const node = {
   title: "Page Not Found",
@@ -8,7 +8,7 @@ const node = {
 };
 ---
 
-<Layout
+<StandardLayout
   node={node}
   isHomePage={false}
   hasSidebar={false}
@@ -22,7 +22,7 @@ const node = {
     <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>
-</Layout>
+</StandardLayout>
 
 <style>
   .error-page {

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

@@ -1,6 +1,6 @@
 ---
 // src/pages/[...slug].astro
-import Layout from "../layouts/Layout.astro";
+import StandardLayout from "../layouts/StandardLayout.astro";
 import SkeletonLayout from "../layouts/SkeletonLayout.astro";
 import BlockRenderer from "../components/blocks/BlockRenderer.astro";
 import Breadcrumb from "../components/global/Breadcrumb.astro";
@@ -142,7 +142,7 @@ const isSkeleton = node?.nodeType === "page-skeleton";
       <BlockRenderer blocks={mainBlocks} contentMap={content} region="main" />
     </SkeletonLayout>
   ) : (
-    <Layout
+    <StandardLayout
       node={node}
       content={content}
       normalizedSlug={normalizedSlug}
@@ -196,58 +196,6 @@ const isSkeleton = node?.nodeType === "page-skeleton";
           </aside>
         )}
       </div>
-    </Layout>
+    </StandardLayout>
   )
 }
-
-<style>
-  .region-header {
-    margin-bottom: 24px;
-  }
-  .breadcrumb-wrapper {
-    margin-bottom: 24px;
-  }
-  .content-layout {
-    width: 100%;
-    display: block;
-  }
-  .main-column {
-    width: 100%;
-    min-width: 0;
-  }
-  @media (min-width: 768px) {
-    .content-layout.has-sidebar {
-      display: grid !important;
-      grid-template-columns: calc(100% - 360px) 310px !important;
-      column-gap: 48px !important;
-      align-items: start !important;
-    }
-    .main-column {
-      grid-column: 1 / 2 !important;
-    }
-    .sidebar-column {
-      grid-column: 2 / 3 !important;
-      position: sticky;
-      top: 32px;
-    }
-  }
-  .sidebar-column {
-    background: #f8fafc;
-    border: 1px solid #e2e8f0;
-    padding: 28px;
-    box-sizing: border-box;
-  }
-  @media (max-width: 767px) {
-    .sidebar-column {
-      margin-top: 40px;
-    }
-  }
-  .empty-content {
-    padding: 32px;
-    border: 1px dashed #cbd5e1;
-    background: #f8fafc;
-    color: #64748b;
-    font-size: 0.95rem;
-    text-align: center;
-  }
-</style>

package/templates/astro-starter/src/pages/llms-full.txt.ts

@@ -0,0 +1,161 @@
+// src/pages/llms-full.txt.ts
+import type { APIRoute } from "astro";
+import { getTree, getTreeId, getChannelId, getNodeByPath } from "../lib/cms";
+import { renderTiptapNode } from "../utils/tiptap";
+
+export const prerender = false;
+
+export const GET: APIRoute = async (context) => {
+    // 1. Setup Worker Fetch Binding
+    const locals = (context.locals as any) || {};
+    const cfEnv = locals.cfContext?.env || {};
+    const cmsWorker = cfEnv.CMS_WORKER;
+
+    const envApiUrl = import.meta.env.PUBLIC_API_URL;
+    const workerApiUrl = cfEnv.PUBLIC_API_URL || (typeof process !== "undefined" ? process.env?.PUBLIC_API_URL : undefined);
+    const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787").replace(/\/$/, "");
+
+    const customFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+        let urlStr = input instanceof URL ? input.toString() : String(input);
+        if (urlStr.startsWith("/")) urlStr = `${baseApiUrl}${urlStr}`;
+
+        const req = new Request(urlStr, init);
+        if (cmsWorker && typeof cmsWorker.fetch === "function") {
+            return cmsWorker.fetch(req);
+        }
+        return fetch(req);
+    };
+
+    const channelId = getChannelId() || import.meta.env.PUBLIC_CHANNEL_ID || "website";
+    const treeId = getTreeId() || import.meta.env.PUBLIC_TREE_ID || "main-navigation";
+
+    const rawOrigin = import.meta.env.PUBLIC_SITE_URL || context.url.origin;
+    const siteOrigin = String(rawOrigin).replace(/\/$/, "");
+    const brandName = import.meta.env.PUBLIC_SITE_NAME || "KAMA Starter";
+
+    try {
+        // 2. Fetch Home Node (for global context) and Navigation Tree
+        const [homeData, rawNavTree] = await Promise.all([
+            getNodeByPath("home", channelId, false, customFetch).catch(() => null),
+            getTree(treeId, channelId, customFetch).catch(() => []),
+        ]);
+
+        const navTree = Array.isArray(rawNavTree)
+            ? rawNavTree
+            : (rawNavTree?.tree || rawNavTree?.items || rawNavTree?.data || []);
+
+        const siteSummary = homeData?.node?.abstract || homeData?.node?.summary || "Full Application Documentation Corpus";
+
+        // 3. Header section matching llmstxt.org spec
+        let fullText = `# ${brandName} - Full Corpus\n\n`;
+        fullText += `> ${siteSummary}\n\n`;
+        fullText += `This file contains the complete unabridged text content for all pages across the application.\n\n`;
+
+        // Helper to extract text from block data (handles TipTap AST & raw strings)
+        const parseBlockText = (blockData: any): string => {
+            if (!blockData) return "";
+            let rawText = "";
+
+            if (typeof blockData === "string") {
+                rawText = blockData;
+            } else if (blockData.type === "doc") {
+                rawText = renderTiptapNode(blockData);
+            } else if (blockData.body) {
+                rawText = parseBlockText(blockData.body);
+            } else if (blockData.text) {
+                rawText = parseBlockText(blockData.text);
+            }
+
+            // Convert basic HTML block tags to plain text linebreaks
+            return rawText
+                .replace(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/gi, "## $1\n")
+                .replace(/<p[^>]*>(.*?)<\/p>/gi, "$1\n")
+                .replace(/<br\s*\/?>/gi, "\n")
+                .replace(/<[^>]+>/g, ""); // Strip any remaining tags
+        };
+
+        // Recursive walker to fetch each page's full content
+        const processNodes = async (nodes: any[], depth = 1) => {
+            let sectionContent = "";
+
+            for (const item of nodes) {
+                const nodeData = item.node || item;
+                if (!nodeData || nodeData.isHidden) continue;
+
+                const rawPath = nodeData.path || nodeData.slug || "/";
+                const cleanPath = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+                const itemUrl = cleanPath === "/" ? siteOrigin : `${siteOrigin}${cleanPath}`;
+                const itemTitle = nodeData.title || nodeData.label || "Untitled Page";
+
+                // Fetch node's block contents
+                const pageData = await getNodeByPath(
+                    cleanPath.replace(/^\//, "") || "home",
+                    channelId,
+                    false,
+                    customFetch
+                ).catch(() => null);
+
+                // Add Document Title Header
+                sectionContent += `\n---\n\n`;
+                sectionContent += `# ${itemTitle}\n`;
+                sectionContent += `**URL:** ${itemUrl}\n`;
+                if (nodeData.abstract || nodeData.summary) {
+                    sectionContent += `**Abstract:** ${nodeData.abstract || nodeData.summary}\n`;
+                }
+                sectionContent += `\n`;
+
+                // Render all blocks on the node
+                const regions = pageData?.content || {};
+                let blockCount = 0;
+
+                Object.entries(regions).forEach(([regionName, blocks]) => {
+                    if (!Array.isArray(blocks)) return;
+
+                    blocks.forEach((block: any) => {
+                        const data = block.data || {};
+                        const renderedText = parseBlockText(data);
+
+                        if (renderedText && renderedText.trim()) {
+                            sectionContent += `${renderedText.trim()}\n\n`;
+                            blockCount++;
+                        }
+                    });
+                });
+
+                if (blockCount === 0) {
+                    sectionContent += `*(No text content available for this node)*\n\n`;
+                }
+
+                // Recursively process child pages
+                if (Array.isArray(item.children) && item.children.length > 0) {
+                    sectionContent += await processNodes(item.children, depth + 1);
+                }
+            }
+
+            return sectionContent;
+        };
+
+        if (navTree.length > 0) {
+            fullText += await processNodes(navTree);
+        } else {
+            fullText += `\n---\n\n# Home\n**URL:** ${siteOrigin}\n\nNo additional pages found in navigation tree.\n`;
+        }
+
+        fullText += `\n---\n*Generated dynamically by Kama Engine.*`;
+
+        return new Response(fullText, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/plain; charset=utf-8",
+                "Cache-Control": "public, max-age=3600, s-maxage=86400"
+            },
+        });
+
+    } catch (error) {
+        console.error("[llms-full.txt Generator Error]:", error);
+        return new Response("# Error\nCould not generate full AI context corpus.", {
+            status: 500,
+            headers: { "Content-Type": "text/plain; charset=utf-8" }
+        });
+    }
+};

package/templates/astro-starter/src/pages/llms.txt.ts

@@ -1,16 +1,18 @@
 // src/pages/llms.txt.ts
 import type { APIRoute } from "astro";
 import { getTree, getTreeId, getChannelId, getNodeByPath } from "../lib/cms";
-import { env } from "cloudflare:workers";
+
+// Ensure this route is dynamically rendered (SSR)
+export const prerender = false;
 
 export const GET: APIRoute = async (context) => {
-    // 1. Setup Worker Fetch Binding (Same as your [...slug].astro)
+    // 1. Setup Cloudflare Worker Fetch Binding safely
     const locals = (context.locals as any) || {};
-    const workerEnv = env || process.env || {};
-    const cmsWorker = locals.cfContext?.env?.CMS_WORKER || workerEnv.CMS_WORKER;
+    const cfEnv = locals.cfContext?.env || {};
+    const cmsWorker = cfEnv.CMS_WORKER;
 
     const envApiUrl = import.meta.env.PUBLIC_API_URL;
-    const workerApiUrl = workerEnv.PUBLIC_API_URL;
+    const workerApiUrl = cfEnv.PUBLIC_API_URL || (typeof process !== "undefined" ? process.env?.PUBLIC_API_URL : undefined);
     const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787").replace(/\/$/, "");
 
     const customFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
@@ -24,71 +26,79 @@ export const GET: APIRoute = async (context) => {
         return fetch(req);
     };
 
-    const channelId = getChannelId();
-    const treeId = getTreeId();
-    const siteOrigin = import.meta.env.PUBLIC_SITE_URL || context.url.origin;
+    // 2. Load keys from environment or fallback defaults
+    const channelId = getChannelId() || import.meta.env.PUBLIC_CHANNEL_ID || "website";
+    const treeId = getTreeId() || import.meta.env.PUBLIC_TREE_ID || "main-navigation";
+
+    const rawOrigin = import.meta.env.PUBLIC_SITE_URL || context.url.origin;
+    const siteOrigin = String(rawOrigin).replace(/\/$/, "");
     const brandName = import.meta.env.PUBLIC_SITE_NAME || "KAMA Starter";
 
     try {
-        // 2. Fetch the Home Page (for global context) and the Navigation Tree (for the directory)
-        const [homeData, navTree] = await Promise.all([
-            getNodeByPath("home", channelId, false, customFetch),
-            getTree(treeId, channelId, customFetch),
+        // 3. Parallel fetch for Home Node summary and Navigation Tree
+        const [homeData, rawNavTree] = await Promise.all([
+            getNodeByPath("home", channelId, false, customFetch).catch(() => null),
+            getTree(treeId, channelId, customFetch).catch(() => []),
         ]);
 
-        const siteDescription = homeData?.node?.summary || "Corporate Web Application.";
+        // Normalize tree data payload across direct array or wrapped responses
+        const navTree = Array.isArray(rawNavTree)
+            ? rawNavTree
+            : (rawNavTree?.tree || rawNavTree?.items || rawNavTree?.data || []);
 
-        // 3. Build the Markdown Output for the AI
-        let markdown = `# ${brandName}\n\n`;
-        markdown += `> ${siteDescription}\n\n`;
-        markdown += `## About This Site\n`;
-        markdown += `This file serves as a directory for AI agents and language models. The links below contain the primary content and structure of the application.\n\n`;
+        const siteSummary = homeData?.node?.abstract || homeData?.node?.summary || "Global Content Delivery at the Edge";
 
+        // 4. Build standard-compliant llms.txt Markdown
+        let markdown = `# ${brandName}\n\n`;
+        markdown += `> ${siteSummary}\n\n`;
+        markdown += `This file serves as a structured directory for AI agents and language models.\n\n`;
         markdown += `## Site Directory\n\n`;
 
-        // Recursively flatten the CMS tree into a Markdown list
+        // Recursive tree flattener with link annotations
         const buildList = (nodes: any[], depth = 0) => {
             let list = "";
             const indent = "  ".repeat(depth);
 
             for (const item of nodes) {
-                if (!item.node) continue;
+                const nodeData = item.node || item;
+                if (!nodeData || nodeData.isHidden) continue;
+
+                const rawPath = nodeData.path || nodeData.slug || "/";
+                const cleanPath = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+                const itemUrl = cleanPath === "/" ? siteOrigin : `${siteOrigin}${cleanPath}`;
 
-                // Build the absolute URL for the AI to crawl if needed
-                const itemUrl = item.node.path === "/"
-                    ? siteOrigin
-                    : `${siteOrigin}${item.node.path.startsWith('/') ? '' : '/'}${item.node.path}`;
+                const itemTitle = nodeData.title || nodeData.label || nodeData.menuTitle || "Untitled";
+                const abstract = nodeData.abstract || nodeData.summary || nodeData.description;
+                const annotation = abstract ? `: ${abstract.trim()}` : "";
 
-                list += `${indent}- [${item.node.title}](${itemUrl})\n`;
+                list += `${indent}- [${itemTitle}](${itemUrl})${annotation}\n`;
 
-                if (item.children && item.children.length > 0) {
+                if (Array.isArray(item.children) && item.children.length > 0) {
                     list += buildList(item.children, depth + 1);
                 }
             }
             return list;
         };
 
-        if (navTree && navTree.length > 0) {
+        if (navTree.length > 0) {
             markdown += buildList(navTree);
         } else {
-            // 🎯 Use the actual CMS title for the home page, or fallback to the brand name
             const homeTitle = homeData?.node?.title || brandName;
-            markdown += `- [${homeTitle}](${siteOrigin})\n`;
+            markdown += `- [${homeTitle}](${siteOrigin}): Main landing page.\n`;
         }
 
         markdown += `\n---\n*Generated dynamically by Kama Engine.*`;
 
-        // 4. Return as raw text
         return new Response(markdown, {
             status: 200,
-            // Your middleware will attach the caching headers, but we set the content type here
             headers: {
                 "Content-Type": "text/plain; charset=utf-8",
+                "Cache-Control": "public, max-age=3600, s-maxage=86400"
             },
         });
 
     } catch (error) {
-        console.error("Failed to generate llms.txt:", error);
+        console.error("[llms.txt Generator Error]:", error);
         return new Response("# Error\nCould not generate AI directory.", {
             status: 500,
             headers: { "Content-Type": "text/plain; charset=utf-8" }