@brightsideoy/kama 0.1.0-alpha.16 → 0.1.0-alpha.161

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

@@ -0,0 +1,171 @@
+// 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 || "main-channel";
+    const treeId = getTreeId() || import.meta.env.PUBLIC_TREE_ID || "main-tree";
+
+    // 🎯 Extract configurable fallback home slug
+    const envHomeSlug = import.meta.env.PUBLIC_HOME_SLUG;
+    const workerHomeSlug = cfEnv.PUBLIC_HOME_SLUG || (typeof process !== "undefined" ? process.env?.PUBLIC_HOME_SLUG : undefined);
+    const homeSlug = String(envHomeSlug || workerHomeSlug || "home").trim();
+
+    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 Navigation Tree first to determine root nodes
+        const rawNavTree = await getTree(treeId, channelId, customFetch).catch(() => []);
+        const navTree = Array.isArray(rawNavTree)
+            ? rawNavTree
+            : (rawNavTree?.tree || rawNavTree?.items || rawNavTree?.data || []);
+
+        // Determine home page slug (first root node in tree, or fallback home slug)
+        const rootTreeSlug = navTree.length > 0 ? (navTree[0].slug || navTree[0].key || "") : "";
+        const resolvedHomeSlug = rootTreeSlug || homeSlug;
+
+        // Fetch Home Node (for global context)
+        const homeData = await getNodeByPath(resolvedHomeSlug, channelId, false, customFetch).catch(() => null);
+
+        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 itemSlug = nodeData.slug || nodeData.path || "";
+                const isRootItem = itemSlug === resolvedHomeSlug || itemSlug === "" || itemSlug === "/";
+                const itemUrl = isRootItem ? siteOrigin : `${siteOrigin}/${itemSlug.replace(/^\//, "")}`;
+                const itemTitle = nodeData.title || nodeData.label || "Untitled Page";
+
+                const fetchSlug = isRootItem ? resolvedHomeSlug : itemSlug.replace(/^\//, "");
+
+                // Fetch node's block contents
+                const pageData = await getNodeByPath(
+                    fetchSlug,
+                    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

@@ -0,0 +1,113 @@
+// src/pages/llms.txt.ts
+import type { APIRoute } from "astro";
+import { getTree, getTreeId, getChannelId, getNodeByPath } from "../lib/cms";
+
+// Ensure this route is dynamically rendered (SSR)
+export const prerender = false;
+
+export const GET: APIRoute = async (context) => {
+    // 1. Setup Cloudflare Worker Fetch Binding safely
+    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);
+    };
+
+    // 2. Load keys from environment or fallback defaults
+    const channelId = getChannelId() || import.meta.env.PUBLIC_CHANNEL_ID || "main-channel";
+    const treeId = getTreeId() || import.meta.env.PUBLIC_TREE_ID || "main-tree";
+
+    // 🎯 Extract configurable fallback home slug
+    const envHomeSlug = import.meta.env.PUBLIC_HOME_SLUG;
+    const workerHomeSlug = cfEnv.PUBLIC_HOME_SLUG || (typeof process !== "undefined" ? process.env?.PUBLIC_HOME_SLUG : undefined);
+    const homeSlug = String(envHomeSlug || workerHomeSlug || "home").trim();
+
+    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 {
+        // 3. Parallel fetch for Navigation Tree first to resolve root node slug
+        const rawNavTree = await getTree(treeId, channelId, customFetch).catch(() => []);
+        const navTree = Array.isArray(rawNavTree)
+            ? rawNavTree
+            : (rawNavTree?.tree || rawNavTree?.items || rawNavTree?.data || []);
+
+        const rootTreeSlug = navTree.length > 0 ? (navTree[0].slug || navTree[0].key || "") : "";
+        const resolvedHomeSlug = rootTreeSlug || homeSlug;
+
+        // Fetch Home Node summary
+        const homeData = await getNodeByPath(resolvedHomeSlug, channelId, false, customFetch).catch(() => null);
+
+        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`;
+
+        // Recursive tree flattener with link annotations
+        const buildList = (nodes: any[], depth = 0) => {
+            let list = "";
+            const indent = "  ".repeat(depth);
+
+            for (const item of nodes) {
+                const nodeData = item.node || item;
+                if (!nodeData || nodeData.isHidden) continue;
+
+                const itemSlug = nodeData.slug || nodeData.path || "";
+                const isRootItem = itemSlug === resolvedHomeSlug || itemSlug === "" || itemSlug === "/";
+                const itemUrl = isRootItem ? siteOrigin : `${siteOrigin}/${itemSlug.replace(/^\//, "")}`;
+
+                const itemTitle = nodeData.title || nodeData.label || nodeData.menuTitle || "Untitled";
+                const abstract = nodeData.abstract || nodeData.summary || nodeData.description;
+                const annotation = abstract ? `: ${abstract.trim()}` : "";
+
+                list += `${indent}- [${itemTitle}](${itemUrl})${annotation}\n`;
+
+                if (Array.isArray(item.children) && item.children.length > 0) {
+                    list += buildList(item.children, depth + 1);
+                }
+            }
+            return list;
+        };
+
+        if (navTree.length > 0) {
+            markdown += buildList(navTree);
+        } else {
+            const homeTitle = homeData?.node?.title || brandName;
+            markdown += `- [${homeTitle}](${siteOrigin}): Main landing page.\n`;
+        }
+
+        markdown += `\n---\n*Generated dynamically by Kama Engine.*`;
+
+        return new Response(markdown, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/plain; charset=utf-8",
+                "Cache-Control": "public, max-age=3600, s-maxage=86400"
+            },
+        });
+
+    } catch (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" }
+        });
+    }
+};

package/templates/astro-starter/src/pages/media/[...path].ts

@@ -0,0 +1,14 @@
+// src/pages/media/[...path].ts
+import type { APIRoute } from "astro";
+import { handleMediaProxy } from "../../lib/media/media-proxy";
+
+export const prerender = false;
+
+export const GET: APIRoute = async (context) => {
+    try {
+        return await handleMediaProxy(context);
+    } catch (error: any) {
+        console.error("❌ [Media Proxy Error]:", error?.message || error);
+        return new Response("Media Proxy Failed", { status: 500 });
+    }
+};

package/templates/astro-starter/src/pages/partials/footer.astro

@@ -0,0 +1,69 @@
+---
+// src/pages/partials/footer.astro
+export const partial = true;
+
+import BlockRenderer from "@/components/blocks/BlockRenderer.astro";
+import { getChannelId } from "@/lib/cms";
+
+const safeEnv = (Astro.locals as any).safeEnv || {};
+const cmsWorker = safeEnv.CMS_WORKER;
+const channelId = getChannelId() || "website";
+
+const customFetch = (input: RequestInfo | URL, init?: RequestInit) => {
+  const reqInit = { ...init };
+  delete reqInit.cache;
+
+  let urlStr = input instanceof URL ? input.toString() : String(input);
+  if (urlStr.startsWith("/")) {
+    const baseUrl =
+      import.meta.env.PUBLIC_API_URL ||
+      safeEnv.PUBLIC_API_URL ||
+      "http://127.0.0.1:8787";
+    urlStr = `${baseUrl}${urlStr}`;
+  }
+
+  const req = new Request(urlStr, reqInit);
+  if (cmsWorker && typeof cmsWorker.fetch === "function")
+    return cmsWorker.fetch(req);
+  return fetch(req);
+};
+
+// 🎯 Resolve the Home Page slug
+const homeSlug = String(import.meta.env.PUBLIC_HOME_SLUG || "home").trim();
+
+let footerBlocks: any[] = [];
+let contentMap: Record<string, any[]> = {};
+
+try {
+  // 🎯 Fetch the Home Page node from Kama CMS Public API
+  const res = await customFetch(
+    `/api/v1/node/${homeSlug}?channelId=${channelId}`,
+  );
+  if (res.ok) {
+    const data = await res.json();
+
+    // Kama CMS public node endpoints usually organize blocks inside a 'content' object mapped by region
+    const allContent = data.content || {};
+
+    // Extract specifically the footer region from the Home page
+    footerBlocks = allContent.footer || [];
+    contentMap = allContent;
+  }
+} catch (e) {
+  console.error("[Partials/Footer] Failed to fetch home page blocks:", e);
+}
+---
+
+{
+  footerBlocks && footerBlocks.length > 0 ? (
+    <BlockRenderer
+      blocks={footerBlocks}
+      contentMap={contentMap}
+      region="footer"
+    />
+  ) : (
+    <div class="footer-default">
+      <p>&copy; {new Date().getFullYear()} all rights reserved.</p>
+    </div>
+  )
+}

package/templates/astro-starter/src/pages/partials/nav.astro

@@ -0,0 +1,141 @@
+---
+// src/pages/partials/nav.astro
+export const partial = true; // 🎯 Tells Astro not to wrap this in <html><body>
+
+import { getTree, getTreeId, getChannelId } from "@/lib/cms";
+import type { TreeNode } from "@/lib/cms";
+
+const safeEnv = (Astro.locals as any).safeEnv || {};
+const cmsWorker = safeEnv.CMS_WORKER;
+
+const customFetch = (input: RequestInfo | URL, init?: RequestInit) => {
+  const reqInit = { ...init };
+  delete reqInit.cache;
+
+  let urlStr = input instanceof URL ? input.toString() : String(input);
+  if (urlStr.startsWith("/")) {
+    const baseUrl =
+      import.meta.env.PUBLIC_API_URL ||
+      safeEnv.PUBLIC_API_URL ||
+      "http://127.0.0.1:8787";
+    urlStr = `${baseUrl}${urlStr}`;
+  }
+
+  const req = new Request(urlStr, reqInit);
+  if (cmsWorker && typeof cmsWorker.fetch === "function")
+    return cmsWorker.fetch(req);
+  return fetch(req);
+};
+
+// Fetch fresh tree from CMS
+const channelId = getChannelId() || "website";
+const treeId = getTreeId() || "main-nav";
+let tree: TreeNode[] = [];
+try {
+  tree = (await getTree(treeId, channelId, customFetch)) || [];
+} catch (e) {
+  console.error("[Partials/Nav] Failed to fetch tree:", e);
+}
+
+// Get the current path from the client's fetch request
+const currentPath =
+  (Astro.url.searchParams.get("path") || "/").replace(/\/$/, "") || "/";
+const homeSlug = String(import.meta.env.PUBLIC_HOME_SLUG || "home").trim();
+
+const homeNode = tree.find(
+  item =>
+    item.slug === homeSlug ||
+    item.slug === "" ||
+    item.path === "/" ||
+    item.path === "",
+);
+
+const topLevelNavItems =
+  homeNode?.children && homeNode.children.length > 0
+    ? homeNode.children
+    : tree.filter(
+        item =>
+          item.slug !== homeSlug &&
+          item.slug !== "" &&
+          item.path !== "/" &&
+          item.path !== "",
+      );
+
+const isPathActive = (itemPath?: string) => {
+  const normItem = (itemPath || "").replace(/\/$/, "") || "/";
+  if (normItem === "/") return currentPath === "/";
+  return currentPath === normItem || currentPath.startsWith(`${normItem}/`);
+};
+
+const isExactActive = (itemPath?: string) => {
+  return currentPath === ((itemPath || "").replace(/\/$/, "") || "/");
+};
+---
+
+<ul class="nav-list">
+  {
+    topLevelNavItems.map(item => {
+      const hasChildren = item.children && item.children.length > 0;
+      const isParentActive = isPathActive(item.path);
+
+      if (hasChildren) {
+        return (
+          <li class="nav-item">
+            <details class="nav-details">
+              <summary
+                class:list={[
+                  "nav-button",
+                  "dropdown-summary",
+                  { active: isParentActive },
+                ]}
+              >
+                <span>{item.title}</span>
+                <span class="indicator">▼</span>
+              </summary>
+              <div class="submenu-container">
+                <ul class="dropdown-panel">
+                  <li>
+                    <a
+                      href={item.path}
+                      class:list={[
+                        "dropdown-item",
+                        "overview-item",
+                        { active: isExactActive(item.path) },
+                      ]}
+                    >
+                      {item.title} Overview
+                    </a>
+                  </li>
+                  {item.children?.map(child => (
+                    <li>
+                      <a
+                        href={child.path}
+                        class:list={[
+                          "dropdown-item",
+                          { active: isExactActive(child.path) },
+                        ]}
+                      >
+                        {child.title}
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            </details>
+          </li>
+        );
+      }
+
+      return (
+        <li class="nav-item">
+          <a
+            href={item.path}
+            class:list={["nav-button", { active: isExactActive(item.path) }]}
+          >
+            {item.title}
+          </a>
+        </li>
+      );
+    })
+  }
+</ul>

package/templates/astro-starter/src/styles/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;
+}