@aravindc26/velu 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/schema/velu.schema.json

@@ -75,28 +75,16 @@
     },
     "navigation": {
       "type": "object",
-      "description": "Defines the site navigation hierarchy: tabs → groups → pages.",
+      "description": "Defines the site navigation hierarchy: tabs → groups → pages. Groups must belong to a tab.",
+      "required": ["tabs"],
       "properties": {
         "tabs": {
           "type": "array",
-          "description": "Top-level navigation tabs.",
+          "description": "Top-level navigation tabs. Each tab contains groups and/or pages.",
           "items": {
             "$ref": "#/definitions/tab"
-          }
-        },
-        "groups": {
-          "type": "array",
-          "description": "Top-level navigation groups (used when there are no tabs, or as default content).",
-          "items": {
-            "$ref": "#/definitions/group"
-          }
-        },
-        "pages": {
-          "type": "array",
-          "description": "Top-level standalone pages.",
-          "items": {
-            "$ref": "#/definitions/page"
-          }
+          },
+          "minItems": 1
         }
       },
       "additionalProperties": false
@@ -111,12 +99,17 @@
     "group": {
       "type": "object",
       "description": "A group of pages, optionally nested.",
-      "required": ["group", "pages"],
+      "required": ["group", "slug", "pages"],
       "properties": {
         "group": {
           "type": "string",
           "description": "Display name for the group."
         },
+        "slug": {
+          "type": "string",
+          "description": "URL slug prefix for pages in this group. Used as the route prefix: /<slug>/<page-basename>.",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
         "icon": {
           "type": "string",
           "description": "Icon identifier for the group."
@@ -146,12 +139,17 @@
     "tab": {
       "type": "object",
       "description": "A top-level navigation tab.",
-      "required": ["tab"],
+      "required": ["tab", "slug"],
       "properties": {
         "tab": {
           "type": "string",
           "description": "Display name for the tab."
         },
+        "slug": {
+          "type": "string",
+          "description": "URL slug prefix for pages in this tab. Used as the route prefix: /<slug>/<page-basename>.",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
         "icon": {
           "type": "string",
           "description": "Icon identifier for the tab."

package/src/build.ts

@@ -6,11 +6,13 @@ import { generateThemeCss, type ThemeConfig, type VeluColors, type VeluStyling }
 
 interface VeluGroup {
   group: string;
+  slug: string;
   pages: (string | VeluGroup)[];
 }
 
 interface VeluTab {
   tab: string;
+  slug: string;
   href?: string;
   pages?: string[];
   groups?: VeluGroup[];
@@ -23,9 +25,7 @@ interface VeluConfig {
   appearance?: "system" | "light" | "dark";
   styling?: VeluStyling;
   navigation: {
-    tabs?: VeluTab[];
-    groups?: VeluGroup[];
-    pages?: string[];
+    tabs: VeluTab[];
   };
 }
 
@@ -41,6 +41,10 @@ function pageLabelFromSlug(slug: string): string {
   return last.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+function pageBasename(page: string): string {
+  return page.split("/").pop()!;
+}
+
 function collectPagesFromGroup(group: VeluGroup): string[] {
   const pages: string[] = [];
   for (const item of group.pages) {
@@ -50,18 +54,45 @@ function collectPagesFromGroup(group: VeluGroup): string[] {
   return pages;
 }
 
-function collectAllPages(config: VeluConfig): string[] {
-  const pages: string[] = [];
-  const nav = config.navigation;
-  if (nav.pages) pages.push(...nav.pages);
-  if (nav.groups) for (const g of nav.groups) pages.push(...collectPagesFromGroup(g));
-  if (nav.tabs) {
-    for (const tab of nav.tabs) {
-      if (tab.pages) pages.push(...tab.pages);
-      if (tab.groups) for (const g of tab.groups) pages.push(...collectPagesFromGroup(g));
+interface PageMapping {
+  src: string;   // original page reference (file path without .md)
+  dest: string;  // slug-based destination path (slug/basename)
+}
+
+function buildPageMap(config: VeluConfig): PageMapping[] {
+  const mappings: PageMapping[] = [];
+
+  function addPagesFromGroup(group: VeluGroup, tabSlug: string) {
+    for (const item of group.pages) {
+      if (typeof item === "string") {
+        mappings.push({ src: item, dest: `${tabSlug}/${group.slug}/${pageBasename(item)}` });
+      } else {
+        addPagesFromGroup(item, tabSlug);
+      }
     }
   }
-  return pages;
+
+  for (const tab of config.navigation.tabs) {
+    if (tab.href) continue;
+    // Direct pages in tab use tab slug
+    if (tab.pages) {
+      for (const page of tab.pages) {
+        mappings.push({ src: page, dest: `${tab.slug}/${pageBasename(page)}` });
+      }
+    }
+    // Groups inside tab: <tab-slug>/<group-slug>/<page-basename>
+    if (tab.groups) {
+      for (const group of tab.groups) {
+        addPagesFromGroup(group, tab.slug);
+      }
+    }
+  }
+
+  return mappings;
+}
+
+function collectAllPages(config: VeluConfig): string[] {
+  return buildPageMap(config).map(m => m.src);
 }
 
 // ── Build ──────────────────────────────────────────────────────────────────────
@@ -85,11 +116,11 @@ function build(docsDir: string, outDir: string) {
   copyFileSync(join(docsDir, "velu.json"), join(outDir, "velu.json"));
   console.log("📋 Copied velu.json");
 
-  // ── 2. Copy all referenced .md files ──────────────────────────────────────
-  const allPages = collectAllPages(config);
-  for (const page of allPages) {
-    const srcPath = join(docsDir, `${page}.md`);
-    const destPath = join(outDir, "src", "content", "docs", `${page}.md`);
+  // ── 2. Copy all referenced .md files (slug-based destinations) ───────────
+  const pageMap = buildPageMap(config);
+  for (const { src, dest } of pageMap) {
+    const srcPath = join(docsDir, `${src}.md`);
+    const destPath = join(outDir, "src", "content", "docs", `${dest}.md`);
 
     if (!existsSync(srcPath)) {
       console.warn(`⚠️  Missing: ${srcPath}`);
@@ -101,7 +132,7 @@ function build(docsDir: string, outDir: string) {
     let content = readFileSync(srcPath, "utf-8");
     if (!content.startsWith("---")) {
       const titleMatch = content.match(/^#\s+(.+)$/m);
-      const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(page);
+      const title = titleMatch ? titleMatch[1] : pageLabelFromSlug(src);
       if (titleMatch) {
         content = content.replace(/^#\s+.+$/m, "").trimStart();
       }
@@ -110,7 +141,7 @@ function build(docsDir: string, outDir: string) {
 
     writeFileSync(destPath, content, "utf-8");
   }
-  console.log(`📄 Copied ${allPages.length} pages`);
+  console.log(`📄 Copied ${pageMap.length} pages`);
 
   // ── 3. Generate src/lib/velu.ts — the single source of truth ──────────────
   // This module reads velu.json at Astro build/render time. No hardcoded data.
@@ -121,6 +152,7 @@ import { resolve } from 'node:path';
 
 export interface VeluGroup {
   group: string;
+  slug: string;
   icon?: string;
   tag?: string;
   expanded?: boolean;
@@ -129,6 +161,7 @@ export interface VeluGroup {
 
 export interface VeluTab {
   tab: string;
+  slug: string;
   icon?: string;
   href?: string;
   pages?: string[];
@@ -142,9 +175,7 @@ export interface VeluConfig {
   appearance?: 'system' | 'light' | 'dark';
   styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
-    tabs?: VeluTab[];
-    groups?: VeluGroup[];
-    pages?: string[];
+    tabs: VeluTab[];
   };
 }
 
@@ -152,7 +183,7 @@ export interface TabMeta {
   label: string;
   icon?: string;
   href?: string;
-  pathPrefix: string;
+  slugs: string[];
   firstPage?: string;
 }
 
@@ -170,37 +201,19 @@ export function loadVeluConfig(): VeluConfig {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-function collectPagesFromGroup(group: VeluGroup): string[] {
-  const pages: string[] = [];
-  for (const item of group.pages) {
-    if (typeof item === 'string') pages.push(item);
-    else pages.push(...collectPagesFromGroup(item));
-  }
-  return pages;
-}
-
-function collectTabPages(tab: VeluTab): string[] {
-  const pages: string[] = [];
-  if (tab.pages) pages.push(...tab.pages);
-  if (tab.groups) for (const g of tab.groups) pages.push(...collectPagesFromGroup(g));
-  return pages;
-}
-
-function detectPathPrefix(slugs: string[]): string {
-  if (slugs.length === 0) return '';
-  const first = slugs[0];
-  const idx = first.indexOf('/');
-  if (idx === -1) return '';
-  const prefix = first.substring(0, idx);
-  if (slugs.every((s) => s.startsWith(prefix + '/'))) return prefix;
-  return '';
+function pageBasename(page: string): string {
+  return page.split('/').pop()!;
 }
 
-function veluGroupToSidebar(group: VeluGroup): any {
+/** Convert a group to a Starlight sidebar entry, using slug-based page paths */
+function veluGroupToSidebar(group: VeluGroup, tabSlug: string): any {
   const items: any[] = [];
   for (const item of group.pages) {
-    if (typeof item === 'string') items.push(item);
-    else items.push(veluGroupToSidebar(item));
+    if (typeof item === 'string') {
+      items.push(tabSlug + '/' + group.slug + '/' + pageBasename(item));
+    } else {
+      items.push(veluGroupToSidebar(item, tabSlug));
+    }
   }
   const result: any = { label: group.group, items };
   if (group.tag) result.badge = group.tag;
@@ -208,33 +221,44 @@ function veluGroupToSidebar(group: VeluGroup): any {
   return result;
 }
 
+/** Get the first page dest path for a tab */
+function firstTabPage(tab: VeluTab): string | undefined {
+  if (tab.pages && tab.pages.length > 0) {
+    return tab.slug + '/' + pageBasename(tab.pages[0]);
+  }
+  if (tab.groups) {
+    for (const g of tab.groups) {
+      const first = firstGroupPage(g, tab.slug);
+      if (first) return first;
+    }
+  }
+  return undefined;
+}
+
+function firstGroupPage(group: VeluGroup, tabSlug: string): string | undefined {
+  for (const item of group.pages) {
+    if (typeof item === 'string') return tabSlug + '/' + group.slug + '/' + pageBasename(item);
+    const nested = firstGroupPage(item, tabSlug);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
 // ── Public API ──────────────────────────────────────────────────────────────
 
 /** Build the full Starlight sidebar array from velu.json */
 export function getSidebar(): any[] {
   const config = loadVeluConfig();
-  const nav = config.navigation;
   const sidebar: any[] = [];
 
-  // Default groups
-  if (nav.groups) {
-    for (const group of nav.groups) sidebar.push(veluGroupToSidebar(group));
-  }
-
-  // Default standalone pages
-  if (nav.pages) {
-    for (const page of nav.pages) sidebar.push(page);
-  }
-
-  // Tab content as top-level groups
-  if (nav.tabs) {
-    for (const tab of nav.tabs) {
-      if (tab.href) continue;
-      const items: any[] = [];
-      if (tab.groups) for (const g of tab.groups) items.push(veluGroupToSidebar(g));
-      if (tab.pages) for (const p of tab.pages) items.push(p);
-      sidebar.push({ label: tab.tab, items });
+  for (const tab of config.navigation.tabs) {
+    if (tab.href) continue;
+    const items: any[] = [];
+    if (tab.groups) for (const g of tab.groups) items.push(veluGroupToSidebar(g, tab.slug));
+    if (tab.pages) {
+      for (const p of tab.pages) items.push(tab.slug + '/' + pageBasename(p));
     }
+    sidebar.push({ label: tab.tab, items });
   }
 
   return sidebar;
@@ -243,60 +267,33 @@ export function getSidebar(): any[] {
 /** Get tab metadata for the header navigation */
 export function getTabs(): TabMeta[] {
   const config = loadVeluConfig();
-  const nav = config.navigation;
   const tabs: TabMeta[] = [];
 
-  // Default "Docs" tab from groups/pages
-  const defaultPages: string[] = [];
-  if (nav.groups) for (const g of nav.groups) defaultPages.push(...collectPagesFromGroup(g));
-  if (nav.pages) defaultPages.push(...nav.pages);
-
-  if (defaultPages.length > 0) {
-    tabs.push({
-      label: 'Docs',
-      icon: 'book-open',
-      pathPrefix: detectPathPrefix(defaultPages) || '__default__',
-      firstPage: defaultPages[0],
-    });
-  }
-
-  if (nav.tabs) {
-    for (const tab of nav.tabs) {
-      if (tab.href) {
-        tabs.push({ label: tab.tab, icon: tab.icon, href: tab.href, pathPrefix: '' });
-      } else {
-        const tabPages = collectTabPages(tab);
-        tabs.push({
-          label: tab.tab,
-          icon: tab.icon,
-          pathPrefix: detectPathPrefix(tabPages) || tabPages[0]?.split('/')[0] || '',
-          firstPage: tabPages[0],
-        });
-      }
+  for (const tab of config.navigation.tabs) {
+    if (tab.href) {
+      tabs.push({ label: tab.tab, icon: tab.icon, href: tab.href, slugs: [] });
+    } else {
+      tabs.push({
+        label: tab.tab,
+        icon: tab.icon,
+        slugs: [tab.slug],
+        firstPage: firstTabPage(tab),
+      });
     }
   }
 
   return tabs;
 }
 
-/** Get the mapping of path prefix → sidebar group labels for filtering */
+/** Get the mapping of slug → sidebar group labels for filtering.
+ *  Maps every slug (tab, group, nested group) to the labels that should be visible. */
 export function getTabSidebarMap(): Record<string, string[]> {
   const config = loadVeluConfig();
-  const nav = config.navigation;
   const map: Record<string, string[]> = {};
 
-  // Default tab owns top-level groups
-  const defaultLabels: string[] = [];
-  if (nav.groups) for (const g of nav.groups) defaultLabels.push(g.group);
-  map['__default__'] = defaultLabels;
-
-  if (nav.tabs) {
-    for (const tab of nav.tabs) {
-      if (tab.href) continue;
-      const tabPages = collectTabPages(tab);
-      const prefix = detectPathPrefix(tabPages) || tabPages[0]?.split('/')[0] || '';
-      map[prefix] = [tab.tab];
-    }
+  for (const tab of config.navigation.tabs) {
+    if (tab.href) continue;
+    map[tab.slug] = [tab.tab];
   }
 
   return map;
@@ -364,30 +361,25 @@ const currentPath = Astro.url.pathname;
 
 function isTabActive(tab: any, path: string): boolean {
   if (tab.href) return false;
-  if (tab.pathPrefix === '__default__') {
-    const otherPrefixes = tabs
-      .filter((t: any) => t.pathPrefix && t.pathPrefix !== '__default__' && !t.href)
-      .map((t: any) => t.pathPrefix);
-    return !otherPrefixes.some((p: string) => path.startsWith('/' + p + '/'));
-  }
-  return path.startsWith('/' + tab.pathPrefix + '/');
+  if (!tab.slugs || tab.slugs.length === 0) return false;
+  return tab.slugs.some((s: string) => path.startsWith('/' + s + '/'));
 }
 
-function getActivePrefix(path: string): string {
-  const prefixes = Object.keys(tabSidebarMap).filter(p => p !== '__default__');
-  for (const prefix of prefixes) {
+function getActiveTabSlug(path: string): string {
+  const allPrefixes = Object.keys(tabSidebarMap);
+  for (const prefix of allPrefixes) {
     if (path.startsWith('/' + prefix + '/')) return prefix;
   }
-  return '__default__';
+  return '';
 }
 
-const activePrefix = getActivePrefix(currentPath);
-const visibleLabels = new Set(tabSidebarMap[activePrefix] || []);
+const activeSlug = getActiveTabSlug(currentPath);
+const visibleLabels = new Set(tabSidebarMap[activeSlug] || []);
 
 const { sidebar } = Astro.locals.starlightRoute;
 const filteredSidebar = sidebar.filter((entry: any) => {
   if (entry.type === 'group') return visibleLabels.has(entry.label);
-  return activePrefix === '__default__';
+  return false;
 });
 ---
 
@@ -726,7 +718,7 @@ const title = Astro.locals.starlightRoute.entry.data.title;
 
   function connectSSE() {
     if (state.eventSource) state.eventSource.close();
-    var url = API_BASE + '/conversations/' + state.conversationId + '/events?after_seq=' + state.lastSeq;
+    var url = API_BASE + '/conversations/' + state.conversationId + '/events?after_seq=' + state.lastSeq + '&token=' + encodeURIComponent(state.conversationToken || '');
     state.eventSource = new EventSource(url);
 
     state.eventSource.addEventListener('assistant.completed', function(e) {
@@ -1497,7 +1489,7 @@ html.velu-assistant-wide .velu-ask-bar {
     "utf-8"
   );
 
-  const firstPage = allPages[0] || "quickstart";
+  const firstPage = pageMap[0]?.dest || "quickstart";
   writeFileSync(
     join(outDir, "src", "content", "docs", "index.mdx"),
     `---\ntitle: "Welcome to Velu Docs"\ndescription: Documentation powered by Velu\n---\n\nWelcome to the documentation. Head over to the [Quickstart](/${firstPage}/) to get started.\n`,

package/src/cli.ts

@@ -42,18 +42,21 @@ function init(targetDir: string) {
     navigation: {
       tabs: [
         {
-          tab: "API Reference",
-          pages: ["api-reference/overview", "api-reference/authentication"],
-        },
-      ],
-      groups: [
-        {
-          group: "Getting Started",
+          tab: "Getting Started",
+          slug: "getting-started",
           pages: ["quickstart", "installation"],
+          groups: [
+            {
+              group: "Guides",
+              slug: "guides",
+              pages: ["guides/configuration", "guides/deployment"],
+            },
+          ],
         },
         {
-          group: "Guides",
-          pages: ["guides/configuration", "guides/deployment"],
+          tab: "API Reference",
+          slug: "api-reference",
+          pages: ["api-reference/overview", "api-reference/authentication"],
         },
       ],
     },
@@ -64,7 +67,7 @@ function init(targetDir: string) {
   const pages: Record<string, string> = {
     "quickstart.md": `# Quickstart\n\nWelcome to your new documentation site!\n\n## Prerequisites\n\n- Node.js 18+\n- npm\n\n## Getting Started\n\n1. Edit the markdown files in this directory\n2. Update \`velu.json\` to configure navigation\n3. Run \`velu run\` to start the dev server\n\n\`\`\`bash\nvelu run\n\`\`\`\n\nYour site is live at \`http://localhost:4321\`.\n`,
     "installation.md": `# Installation\n\nInstall Velu globally:\n\n\`\`\`bash\nnpm install -g @aravindc26/velu\n\`\`\`\n\nOr run directly with npx:\n\n\`\`\`bash\nnpx @aravindc26/velu run\n\`\`\`\n`,
-    "guides/configuration.md": `# Configuration\n\nVelu uses a \`velu.json\` file to define your site's navigation.\n\n## Navigation Structure\n\n- **Tabs** — Top-level horizontal navigation\n- **Groups** — Collapsible sidebar sections\n- **Pages** — Individual markdown documents\n\n## Example\n\n\`\`\`json\n{\n  "navigation": {\n    "groups": [\n      {\n        "group": "Getting Started",\n        "pages": ["quickstart"]\n      }\n    ]\n  }\n}\n\`\`\`\n`,
+    "guides/configuration.md": `# Configuration\n\nVelu uses a \`velu.json\` file to define your site's navigation.\n\n## Navigation Structure\n\n- **Tabs** — Top-level horizontal navigation\n- **Groups** — Collapsible sidebar sections within a tab\n- **Pages** — Individual markdown documents\n\n## Example\n\n\`\`\`json\n{\n  "navigation": {\n    "tabs": [\n      {\n        "tab": "Getting Started",\n        "slug": "getting-started",\n        "groups": [\n          {\n            "group": "Basics",\n            "slug": "getting-started",\n            "pages": ["quickstart"]\n          }\n        ]\n      }\n    ]\n  }\n}\n\`\`\`\n`,
     "guides/deployment.md": `# Deployment\n\nBuild your site for production:\n\n\`\`\`bash\nvelu build\n\`\`\`\n\nThe output is a static site you can deploy anywhere — Netlify, Vercel, GitHub Pages, etc.\n`,
     "api-reference/overview.md": `# API Overview\n\nThis section covers the API reference for your project.\n\n## Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /api/health | Health check |\n| POST | /api/data | Create data |\n`,
     "api-reference/authentication.md": `# Authentication\n\nAll API requests require an API key.\n\n## Headers\n\n\`\`\`\nAuthorization: Bearer YOUR_API_KEY\n\`\`\`\n\n## Getting an API Key\n\nVisit the dashboard to generate your API key.\n`,

package/src/validate.ts

@@ -5,6 +5,7 @@ import { resolve, join } from "node:path";
 
 interface VeluGroup {
   group: string;
+  slug: string;
   icon?: string;
   tag?: string;
   expanded?: boolean;
@@ -13,6 +14,7 @@ interface VeluGroup {
 
 interface VeluTab {
   tab: string;
+  slug: string;
   icon?: string;
   href?: string;
   pages?: string[];
@@ -26,9 +28,7 @@ interface VeluConfig {
   appearance?: "system" | "light" | "dark";
   styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
-    tabs?: VeluTab[];
-    groups?: VeluGroup[];
-    pages?: string[];
+    tabs: VeluTab[];
   };
 }
 
@@ -50,27 +50,13 @@ function collectPages(config: VeluConfig): string[] {
     }
   }
 
-  const nav = config.navigation;
-
-  if (nav.pages) {
-    pages.push(...nav.pages);
-  }
-
-  if (nav.groups) {
-    for (const group of nav.groups) {
-      collectFromGroup(group);
+  for (const tab of config.navigation.tabs) {
+    if (tab.pages) {
+      pages.push(...tab.pages);
     }
-  }
-
-  if (nav.tabs) {
-    for (const tab of nav.tabs) {
-      if (tab.pages) {
-        pages.push(...tab.pages);
-      }
-      if (tab.groups) {
-        for (const group of tab.groups) {
-          collectFromGroup(group);
-        }
+    if (tab.groups) {
+      for (const group of tab.groups) {
+        collectFromGroup(group);
       }
     }
   }