@brainfish-ai/devdoc 0.1.42 → 0.1.43

package/renderer/lib/docs/mdx/frontmatter.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+/**
+ * Frontmatter Schema for MDX Documentation Pages
+ * 
+ * Defines the structure and validation for page metadata
+ * Compatible with Mintlify-style frontmatter
+ */ export const frontmatterSchema = z.object({
+    // Core metadata
+    title: z.string(),
+    description: z.string().optional(),
+    // Navigation
+    sidebarTitle: z.string().optional(),
+    icon: z.string().optional(),
+    // Page behavior
+    // - 'default': Standard documentation page with max-width container
+    // - 'wide': Wide container for content that needs more space
+    // - 'custom': Full-width custom layout (no container, no header) - for landing pages
+    mode: z.enum([
+        'default',
+        'wide',
+        'custom'
+    ]).optional(),
+    // Custom page options (only used when mode: 'custom')
+    // Hides the default page header (title & description)
+    hideHeader: z.boolean().optional(),
+    // Full-width layout without container constraints
+    fullWidth: z.boolean().optional(),
+    // Custom background color or gradient
+    background: z.string().optional(),
+    // OpenAPI integration
+    openapi: z.string().optional(),
+    api: z.string().optional(),
+    // SEO
+    'og:title': z.string().optional(),
+    'og:description': z.string().optional(),
+    'og:image': z.string().optional(),
+    'twitter:title': z.string().optional(),
+    'twitter:description': z.string().optional(),
+    // Visibility
+    hidden: z.boolean().optional(),
+    noindex: z.boolean().optional(),
+    // Version/Status
+    version: z.string().optional(),
+    deprecated: z.boolean().optional()
+});
+/**
+ * Parse and validate frontmatter data
+ * Returns the validated data or throws an error with details
+ */ export function parseFrontmatter(data) {
+    const result = frontmatterSchema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues || [];
+        const errors = issues.map((e)=>`${e.path.map(String).join('.')}: ${e.message}`).join('\n');
+        throw new Error(`Invalid frontmatter:\n${errors}`);
+    }
+    return result.data;
+}
+/**
+ * Safe parse that returns null on failure instead of throwing
+ */ export function safeParseFrontmatter(data) {
+    const result = frontmatterSchema.safeParse(data);
+    return result.success ? result.data : null;
+}
+/**
+ * Get default frontmatter values
+ */ export function getDefaultFrontmatter() {
+    return {
+        mode: 'default',
+        hidden: false,
+        noindex: false,
+        deprecated: false
+    };
+}

package/renderer/lib/docs/mdx/index.js

@@ -0,0 +1,8 @@
+/**
+ * MDX Library Exports
+ * 
+ * Core utilities for MDX compilation and processing
+ */ // Compiler utilities
+export { compileMDXContent, quickCompileMDX, validateMDXContent, extractFrontmatter, extractHeadings } from './compiler';
+// Frontmatter
+export { frontmatterSchema, parseFrontmatter, safeParseFrontmatter, getDefaultFrontmatter } from './frontmatter';

package/renderer/lib/docs/navigation/generator.js

@@ -0,0 +1,269 @@
+import { relative, basename, extname } from 'path';
+import { resolvePagePath, loadPageContent } from '../config';
+import { extractFrontmatter, safeParseFrontmatter } from '../mdx';
+/**
+ * Navigation Generator
+ * 
+ * Builds navigation structure from docs.json configuration
+ */ /**
+ * Generate navigation from configuration
+ */ export function generateNavigation(config, docsDir) {
+    const nav = config.navigation;
+    const navigation = {};
+    // Handle tabbed navigation
+    if (nav.tabs && nav.tabs.length > 0) {
+        navigation.tabs = nav.tabs.map((tab)=>buildNavTab(tab, docsDir));
+    }
+    // Handle single-page navigation (no tabs)
+    if (nav.groups && nav.groups.length > 0) {
+        navigation.groups = nav.groups.map((group)=>buildNavGroup(group, docsDir));
+    }
+    // Add global anchors
+    if (nav.global?.anchors) {
+        navigation.anchors = nav.global.anchors.map((anchor)=>({
+                title: anchor.anchor,
+                href: anchor.href,
+                icon: anchor.icon,
+                external: anchor.href.startsWith('http')
+            }));
+    }
+    return navigation;
+}
+/**
+ * Build a navigation tab
+ */ function buildNavTab(tab, docsDir) {
+    const slug = tab.tab.toLowerCase().replace(/\s+/g, '-');
+    // Only docs tabs have groups
+    if ('groups' in tab && tab.groups) {
+        const groups = tab.groups.map((group)=>buildNavGroup(group, docsDir));
+        return {
+            title: tab.tab,
+            slug,
+            groups
+        };
+    }
+    // For openapi/changelog tabs, return empty groups
+    return {
+        title: tab.tab,
+        slug,
+        groups: []
+    };
+}
+/**
+ * Build a navigation group
+ */ function buildNavGroup(group, docsDir) {
+    const items = group.pages.map((page)=>buildNavItemOrGroup(page, docsDir)).filter((item)=>item !== null);
+    return {
+        title: group.group,
+        icon: group.icon,
+        items,
+        collapsible: true,
+        defaultCollapsed: false
+    };
+}
+/**
+ * Build a navigation item or nested group from a page reference
+ */ function buildNavItemOrGroup(pageRef, docsDir) {
+    // Handle nested groups
+    if (typeof pageRef === 'object' && 'group' in pageRef) {
+        const nestedItems = pageRef.pages.map((p)=>buildNavItemOrGroup(p, docsDir)).filter((item)=>item !== null);
+        return {
+            title: pageRef.group,
+            items: nestedItems,
+            collapsible: true,
+            defaultCollapsed: false
+        };
+    }
+    return buildNavItem(pageRef, docsDir);
+}
+/**
+ * Build a navigation item from a page reference
+ */ function buildNavItem(pageRef, docsDir) {
+    // Check if it's an external link
+    if (pageRef.startsWith('http://') || pageRef.startsWith('https://')) {
+        return {
+            title: pageRef,
+            href: pageRef,
+            external: true
+        };
+    }
+    // Resolve the page file
+    const filePath = resolvePagePath(docsDir, pageRef);
+    if (!filePath) {
+        console.warn(`Page not found: ${pageRef}`);
+        return {
+            title: pageRef,
+            href: `/${pageRef}`
+        };
+    }
+    // Load and parse frontmatter
+    try {
+        const content = loadPageContent(filePath);
+        const { data } = extractFrontmatter(content);
+        const frontmatter = safeParseFrontmatter(data);
+        // Build URL path
+        const urlPath = pageRef === 'index' ? '/' : `/${pageRef}`;
+        return {
+            title: frontmatter?.sidebarTitle || frontmatter?.title || pageRef,
+            href: urlPath,
+            icon: frontmatter?.icon,
+            deprecated: frontmatter?.deprecated
+        };
+    } catch (error) {
+        console.warn(`Failed to load page metadata: ${pageRef}`, error);
+        return {
+            title: pageRef,
+            href: `/${pageRef}`
+        };
+    }
+}
+/**
+ * Helper to check if an item is a NavItem (has href)
+ */ function isNavItem(item) {
+    return 'href' in item && typeof item.href === 'string';
+}
+/**
+ * Recursively collect all NavItems from items array (handles nested groups)
+ */ function collectNavItems(items) {
+    const result = [];
+    for (const item of items){
+        if (isNavItem(item)) {
+            result.push(item);
+        } else if ('items' in item && Array.isArray(item.items)) {
+            result.push(...collectNavItems(item.items));
+        }
+    }
+    return result;
+}
+/**
+ * Find navigation context for a specific page
+ */ export function findPageNavContext(navigation, currentPath) {
+    const breadcrumbs = [];
+    let prev;
+    let next;
+    let currentTab;
+    let currentGroup;
+    let currentItem;
+    // Normalize path
+    const normalizedPath = currentPath.startsWith('/') ? currentPath : `/${currentPath}`;
+    // Flatten all items for prev/next calculation
+    const allItems = [];
+    // Search in tabs
+    if (navigation.tabs) {
+        for (const tab of navigation.tabs){
+            for (const group of tab.groups){
+                const groupItems = collectNavItems(group.items);
+                allItems.push(...groupItems);
+                for (const item of groupItems){
+                    if (item.href === normalizedPath) {
+                        currentTab = tab;
+                        currentGroup = group;
+                        currentItem = item;
+                        // Build breadcrumbs
+                        breadcrumbs.push({
+                            title: tab.title,
+                            href: `/${tab.slug}`
+                        });
+                        breadcrumbs.push({
+                            title: group.title,
+                            href: '#'
+                        });
+                        breadcrumbs.push({
+                            title: item.title,
+                            href: item.href
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Search in groups (non-tabbed)
+    if (navigation.groups) {
+        for (const group of navigation.groups){
+            const groupItems = collectNavItems(group.items);
+            allItems.push(...groupItems);
+            for (const item of groupItems){
+                if (item.href === normalizedPath) {
+                    currentGroup = group;
+                    currentItem = item;
+                    // Build breadcrumbs
+                    breadcrumbs.push({
+                        title: group.title,
+                        href: '#'
+                    });
+                    breadcrumbs.push({
+                        title: item.title,
+                        href: item.href
+                    });
+                }
+            }
+        }
+    }
+    // Find prev/next
+    const currentIndex = allItems.findIndex((item)=>item.href === normalizedPath);
+    if (currentIndex > 0) {
+        prev = allItems[currentIndex - 1];
+    }
+    if (currentIndex >= 0 && currentIndex < allItems.length - 1) {
+        next = allItems[currentIndex + 1];
+    }
+    return {
+        breadcrumbs,
+        prev,
+        next,
+        currentTab,
+        currentGroup,
+        currentItem
+    };
+}
+/**
+ * Get all page paths from navigation
+ */ export function getAllPagePaths(navigation) {
+    const paths = [];
+    if (navigation.tabs) {
+        for (const tab of navigation.tabs){
+            for (const group of tab.groups){
+                const items = collectNavItems(group.items);
+                for (const item of items){
+                    if (!item.external) {
+                        paths.push(item.href);
+                    }
+                }
+            }
+        }
+    }
+    if (navigation.groups) {
+        for (const group of navigation.groups){
+            const items = collectNavItems(group.items);
+            for (const item of items){
+                if (!item.external) {
+                    paths.push(item.href);
+                }
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Load page metadata from file
+ */ export function loadPageMeta(filePath, docsDir) {
+    try {
+        const content = loadPageContent(filePath);
+        const { data } = extractFrontmatter(content);
+        const frontmatter = safeParseFrontmatter(data);
+        // Calculate URL path from file path
+        const relativePath = relative(docsDir, filePath);
+        const urlPath = '/' + relativePath.replace(/\.(mdx?|md)$/, '').replace(/\/index$/, '').replace(/^index$/, '');
+        return {
+            filePath: relativePath,
+            urlPath: urlPath || '/',
+            title: frontmatter?.title || basename(filePath, extname(filePath)),
+            description: frontmatter?.description,
+            sidebarTitle: frontmatter?.sidebarTitle,
+            icon: frontmatter?.icon,
+            hidden: frontmatter?.hidden
+        };
+    } catch  {
+        return null;
+    }
+}

package/renderer/lib/docs/navigation/index.js

@@ -0,0 +1,4 @@
+/**
+ * Navigation Module Exports
+ */ export * from './types';
+export { generateNavigation, findPageNavContext, getAllPagePaths, loadPageMeta } from './generator';

package/renderer/lib/docs/navigation/types.js

@@ -0,0 +1,9 @@
+/**
+ * Navigation Types
+ * 
+ * Types for the documentation navigation system
+ */ /**
+ * A navigation item representing a single page
+ */ /**
+ * Page metadata for navigation
+ */ export { };

package/renderer/lib/docs-navigation-context.js

@@ -0,0 +1,40 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useCallback } from 'react';
+const DocsNavigationContext = /*#__PURE__*/ createContext(null);
+export function DocsNavigationProvider({ children, onNavigateToPage, onNavigateToEndpoint, onSwitchTab, activeTab }) {
+    const navigateToPage = useCallback((slug)=>{
+        if (onNavigateToPage) {
+            onNavigateToPage(slug);
+        }
+    }, [
+        onNavigateToPage
+    ]);
+    const navigateToEndpoint = useCallback((endpointId)=>{
+        if (onNavigateToEndpoint) {
+            onNavigateToEndpoint(endpointId);
+        }
+    }, [
+        onNavigateToEndpoint
+    ]);
+    const switchToTab = useCallback((tabId)=>{
+        if (onSwitchTab) {
+            onSwitchTab(tabId);
+        }
+    }, [
+        onSwitchTab
+    ]);
+    return /*#__PURE__*/ _jsx(DocsNavigationContext.Provider, {
+        value: {
+            navigateToPage,
+            navigateToEndpoint,
+            switchToTab,
+            isApiDocsView: !!onNavigateToPage,
+            activeTab
+        },
+        children: children
+    });
+}
+export function useDocsNavigation() {
+    return useContext(DocsNavigationContext);
+}

package/renderer/lib/multi-tenant/context.js

@@ -0,0 +1,80 @@
+/**
+ * Multi-tenant project context utilities
+ * Handles extracting project slug from hostname and managing project context
+ */ /**
+ * Known hostnames that should use local file system (not multi-tenant)
+ */ const LOCAL_HOSTNAMES = [
+    'localhost',
+    '127.0.0.1',
+    '0.0.0.0'
+];
+/**
+ * The main platform domain
+ */ const PLATFORM_DOMAIN = process.env.DEVDOC_PLATFORM_DOMAIN || 'devdoc.sh';
+/**
+ * Extract project context from hostname
+ * 
+ * Examples:
+ * - my-docs.devdoc.sh -> { slug: 'my-docs', isMultiTenant: true }
+ * - localhost:3000 -> { slug: null, isMultiTenant: false }
+ * - docs.company.com -> { slug: lookup from custom domains, isMultiTenant: true }
+ */ export function extractProjectContext(hostname) {
+    // Remove port if present
+    const host = hostname.split(':')[0];
+    // Check if it's a local development hostname
+    if (LOCAL_HOSTNAMES.includes(host)) {
+        return {
+            slug: '',
+            isMultiTenant: false,
+            hostname: host
+        };
+    }
+    // Check if it's a subdomain of the platform domain
+    if (host.endsWith(`.${PLATFORM_DOMAIN}`)) {
+        const slug = host.replace(`.${PLATFORM_DOMAIN}`, '');
+        return {
+            slug,
+            isMultiTenant: true,
+            hostname: host
+        };
+    }
+    // Check if it's the main platform domain
+    if (host === PLATFORM_DOMAIN || host === `www.${PLATFORM_DOMAIN}`) {
+        return {
+            slug: '',
+            isMultiTenant: false,
+            hostname: host
+        };
+    }
+    // Custom domain - need to lookup in database
+    // For now, return the full hostname as slug placeholder
+    // This will be resolved via the domains API
+    return {
+        slug: host,
+        isMultiTenant: true,
+        hostname: host
+    };
+}
+/**
+ * Check if running in multi-tenant mode
+ */ export function isMultiTenantMode() {
+    return process.env.MULTI_TENANT_MODE === 'true';
+}
+/**
+ * Get the current project slug from environment or context
+ */ export function getCurrentProjectSlug() {
+    return process.env.DEVDOC_PROJECT_SLUG || null;
+}
+/**
+ * Build the URL for a project's docs
+ */ export function getProjectUrl(slug) {
+    const protocol = process.env.NODE_ENV === 'production' ? 'https' : 'http';
+    return `${protocol}://${slug}.${PLATFORM_DOMAIN}`;
+}
+/**
+ * Validate a project slug format
+ */ export function isValidSlug(slug) {
+    // Must be lowercase alphanumeric with hyphens, 3-50 chars
+    const slugRegex = /^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/;
+    return slugRegex.test(slug);
+}