@brainfish-ai/devdoc 0.1.42 → 0.1.43

package/renderer/lib/docs/config/domain-schema.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+/**
+ * Domain Configuration Schema (domain.json)
+ * 
+ * Configuration for custom domains on DevDoc projects.
+ * Each project can have ONE custom domain for free.
+ */ // ============================================================================
+// Domain Validation Helpers
+// ============================================================================
+/**
+ * Valid domain pattern - allows subdomains like docs.example.com
+ * Does NOT allow:
+ * - IP addresses
+ * - Ports
+ * - Paths
+ * - Protocol prefixes
+ */ const domainRegex = /^(?!-)[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*\.[a-zA-Z]{2,}$/;
+/**
+ * Reserved domains that cannot be used as custom domains
+ */ const RESERVED_DOMAINS = [
+    'devdoc.sh',
+    'devdoc.io',
+    'devdoc.com',
+    'localhost'
+];
+// ============================================================================
+// SEO Schema
+// ============================================================================
+const domainSeoSchema = z.object({
+    /**
+   * Canonical URL for SEO - tells search engines this is the primary URL
+   * Should match your custom domain with https://
+   */ canonical: z.string().url().optional()
+});
+// ============================================================================
+// Settings Schema
+// ============================================================================
+const domainSettingsSchema = z.object({
+    /**
+   * Force HTTPS redirects (recommended, default: true)
+   */ forceHttps: z.boolean().default(true),
+    /**
+   * WWW redirect preference
+   * - "www": Redirect non-www to www (example.com → www.example.com)
+   * - "non-www": Redirect www to non-www (www.example.com → example.com)
+   * - "none": No redirect, accept both
+   */ wwwRedirect: z.enum([
+        'www',
+        'non-www',
+        'none'
+    ]).default('none')
+});
+// ============================================================================
+// Main Domain Configuration Schema
+// ============================================================================
+export const domainConfigSchema = z.object({
+    /**
+   * JSON Schema reference (optional)
+   */ $schema: z.string().optional(),
+    /**
+   * The custom domain for this project
+   * Example: "docs.example.com" or "developer.mycompany.io"
+   * 
+   * Rules:
+   * - Must be a valid domain name
+   * - Cannot be a DevDoc domain (*.devdoc.sh)
+   * - One custom domain per project (free)
+   */ customDomain: z.string().min(4, 'Domain must be at least 4 characters').max(253, 'Domain must be 253 characters or less').regex(domainRegex, 'Invalid domain format. Example: docs.example.com').refine((domain)=>!RESERVED_DOMAINS.some((reserved)=>domain === reserved || domain.endsWith(`.${reserved}`)), 'Cannot use a reserved DevDoc domain'),
+    /**
+   * SEO configuration for the custom domain
+   */ seo: domainSeoSchema.optional(),
+    /**
+   * Domain behavior settings
+   */ settings: domainSettingsSchema.optional()
+});
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Parse and validate domain configuration
+ */ export function parseDomainConfig(data) {
+    const result = domainConfigSchema.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 domain.json configuration:\n${errors}`);
+    }
+    return result.data;
+}
+/**
+ * Safe parse that returns null on failure
+ */ export function safeParseDomainConfig(data) {
+    const result = domainConfigSchema.safeParse(data);
+    return result.success ? result.data : null;
+}
+/**
+ * Validate a domain string format
+ */ export function isValidDomain(domain) {
+    if (!domain) {
+        return {
+            valid: false,
+            error: 'Domain is required'
+        };
+    }
+    if (domain.length < 4) {
+        return {
+            valid: false,
+            error: 'Domain must be at least 4 characters'
+        };
+    }
+    if (domain.length > 253) {
+        return {
+            valid: false,
+            error: 'Domain must be 253 characters or less'
+        };
+    }
+    if (!domainRegex.test(domain)) {
+        return {
+            valid: false,
+            error: 'Invalid domain format. Example: docs.example.com'
+        };
+    }
+    // Check reserved domains
+    if (RESERVED_DOMAINS.some((reserved)=>domain === reserved || domain.endsWith(`.${reserved}`))) {
+        return {
+            valid: false,
+            error: 'Cannot use a reserved DevDoc domain'
+        };
+    }
+    return {
+        valid: true
+    };
+}
+/**
+ * Normalize a domain (lowercase, trim, remove protocol/path)
+ */ export function normalizeDomain(domain) {
+    let normalized = domain.toLowerCase().trim();
+    // Remove protocol if present
+    normalized = normalized.replace(/^https?:\/\//, '');
+    // Remove path if present
+    normalized = normalized.split('/')[0];
+    // Remove port if present
+    normalized = normalized.split(':')[0];
+    return normalized;
+}
+/**
+ * Get DNS instructions for a custom domain
+ */ export function getDnsInstructions(customDomain) {
+    const parts = customDomain.split('.');
+    const subdomain = parts.length > 2 ? parts[0] : '@';
+    return {
+        cname: {
+            name: subdomain === '@' ? customDomain : subdomain,
+            value: 'cname.devdoc-dns.com'
+        },
+        txt: {
+            name: `_devdoc-verify.${customDomain}`,
+            value: ''
+        }
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Configuration Module Exports
+ */ export { docsConfigSchema, parseDocsConfig, safeParseDocsConfig, getDefaultDocsConfig } from './schema';
+export { domainConfigSchema, parseDomainConfig, safeParseDomainConfig, isValidDomain, normalizeDomain, getDnsInstructions } from './domain-schema';
+export { loadDocsConfig, safeLoadDocsConfig, clearConfigCache, hasDocsConfig, getContentDir, resolvePagePath, loadPageContent, listMdxFiles } from './loader';

package/renderer/lib/docs/config/loader.js

@@ -0,0 +1,113 @@
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { parseDocsConfig } from './schema';
+/**
+ * Configuration Loader
+ * 
+ * Utilities for loading and caching docs.json configuration
+ * Uses synchronous fs operations for compatibility with Next.js Turbopack
+ */ // Cache for loaded configuration
+let configCache = null;
+let configCachePath = null;
+/**
+ * Load docs.json configuration from a directory
+ */ export function loadDocsConfig(docsDir) {
+    const configFilePath = join(docsDir, 'docs.json');
+    // Return cached config if path matches
+    if (configCache && configCachePath === configFilePath) {
+        return configCache;
+    }
+    try {
+        if (!existsSync(configFilePath)) {
+            throw new Error(`docs.json not found at ${configFilePath}`);
+        }
+        const configContent = readFileSync(configFilePath, 'utf-8');
+        const rawConfig = JSON.parse(configContent);
+        const config = parseDocsConfig(rawConfig);
+        // Cache the result
+        configCache = config;
+        configCachePath = configFilePath;
+        return config;
+    } catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to load docs.json: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Load configuration without throwing (returns null on failure)
+ */ export function safeLoadDocsConfig(docsDir) {
+    try {
+        return loadDocsConfig(docsDir);
+    } catch  {
+        return null;
+    }
+}
+/**
+ * Clear the configuration cache
+ */ export function clearConfigCache() {
+    configCache = null;
+    configCachePath = null;
+}
+/**
+ * Check if a docs.json file exists in a directory
+ */ export function hasDocsConfig(docsDir) {
+    return existsSync(join(docsDir, 'docs.json'));
+}
+/**
+ * Get the content directory path from configuration
+ */ export function getContentDir(docsDir) {
+    return docsDir;
+}
+/**
+ * Resolve a page path to a file path
+ */ export function resolvePagePath(docsDir, pagePath) {
+    const contentDir = getContentDir(docsDir);
+    const extensions = [
+        '.mdx',
+        '.md'
+    ];
+    // Try different extensions
+    for (const ext of extensions){
+        const filePath = join(contentDir, `${pagePath}${ext}`);
+        if (existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    // Try as directory with index file
+    for (const ext of extensions){
+        const indexPath = join(contentDir, pagePath, `index${ext}`);
+        if (existsSync(indexPath)) {
+            return indexPath;
+        }
+    }
+    return null;
+}
+/**
+ * Load page content from a resolved path
+ */ export function loadPageContent(filePath) {
+    return readFileSync(filePath, 'utf-8');
+}
+/**
+ * List all MDX files in a directory recursively
+ */ export function listMdxFiles(dir) {
+    const files = [];
+    function walk(currentDir) {
+        const entries = readdirSync(currentDir, {
+            withFileTypes: true
+        });
+        for (const entry of entries){
+            const fullPath = join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                    walk(fullPath);
+                }
+            } else if (entry.isFile() && (entry.name.endsWith('.mdx') || entry.name.endsWith('.md'))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}

package/renderer/lib/docs/config/schema.js

@@ -0,0 +1,269 @@
+import { z } from 'zod';
+/**
+ * Documentation Configuration Schema (docs.json)
+ * 
+ * Mintlify-compatible configuration schema for documentation sites.
+ */ // ============================================================================
+// Navigation Schemas
+// ============================================================================
+const anchorSchema = z.object({
+    anchor: z.string(),
+    href: z.string(),
+    icon: z.string().optional()
+});
+const navLinkSchema = z.object({
+    label: z.string(),
+    href: z.string()
+});
+// Page can be a string or a nested group
+const pageRefSchema = z.lazy(()=>z.union([
+        z.string(),
+        z.object({
+            group: z.string(),
+            pages: z.array(z.union([
+                z.string(),
+                z.lazy(()=>pageRefSchema)
+            ]))
+        })
+    ]));
+const groupSchema = z.object({
+    group: z.string(),
+    pages: z.array(pageRefSchema),
+    icon: z.string().optional()
+});
+// OpenAPI version schema
+const openapiVersionSchema = z.object({
+    version: z.string(),
+    spec: z.string(),
+    default: z.boolean().optional()
+});
+// Different tab types
+const docsTabSchema = z.object({
+    tab: z.string(),
+    type: z.literal('docs').optional(),
+    groups: z.array(groupSchema)
+});
+const openapiTabSchema = z.object({
+    tab: z.string(),
+    type: z.literal('openapi'),
+    path: z.string().optional(),
+    versions: z.array(openapiVersionSchema).optional(),
+    spec: z.string().optional(),
+    groups: z.array(groupSchema).optional()
+});
+const graphqlTabSchema = z.object({
+    tab: z.string(),
+    type: z.literal('graphql'),
+    path: z.string().optional(),
+    schema: z.string(),
+    endpoint: z.string().optional(),
+    groups: z.array(groupSchema).optional()
+});
+const changelogTabSchema = z.object({
+    tab: z.string(),
+    type: z.literal('changelog'),
+    path: z.string().optional()
+});
+const tabSchema = z.union([
+    docsTabSchema,
+    openapiTabSchema,
+    graphqlTabSchema,
+    changelogTabSchema
+]);
+const navigationSchema = z.object({
+    tabs: z.array(tabSchema).optional(),
+    groups: z.array(groupSchema).optional(),
+    global: z.object({
+        anchors: z.array(anchorSchema).optional()
+    }).optional()
+});
+// ============================================================================
+// Theme & Branding Schemas
+// ============================================================================
+const colorSchema = z.object({
+    primary: z.string(),
+    light: z.string().optional(),
+    dark: z.string().optional(),
+    background: z.object({
+        light: z.string().optional(),
+        dark: z.string().optional()
+    }).optional()
+});
+const logoSchema = z.object({
+    light: z.string(),
+    dark: z.string(),
+    href: z.string().optional()
+});
+const faviconSchema = z.string();
+// ============================================================================
+// Navbar Schema
+// ============================================================================
+const navbarPrimarySchema = z.object({
+    type: z.enum([
+        'button',
+        'github',
+        'link'
+    ]),
+    label: z.string().optional(),
+    href: z.string()
+});
+const navbarSchema = z.object({
+    links: z.array(navLinkSchema).optional(),
+    primary: navbarPrimarySchema.optional()
+});
+// ============================================================================
+// Footer Schema
+// ============================================================================
+const footerLinkSchema = z.object({
+    label: z.string(),
+    href: z.string()
+});
+const footerGroupSchema = z.object({
+    title: z.string(),
+    links: z.array(footerLinkSchema)
+});
+const footerSchema = z.object({
+    socials: z.record(z.string(), z.string()).optional(),
+    links: z.array(footerGroupSchema).optional()
+});
+// ============================================================================
+// API Configuration Schema
+// ============================================================================
+const apiAuthSchema = z.object({
+    method: z.enum([
+        'bearer',
+        'basic',
+        'api-key',
+        'none'
+    ]),
+    name: z.string().optional()
+});
+const apiPlaygroundSchema = z.object({
+    mode: z.enum([
+        'show',
+        'simple',
+        'hide'
+    ]).optional()
+});
+const apiConfigSchema = z.object({
+    baseUrl: z.string().optional(),
+    auth: apiAuthSchema.optional(),
+    playground: apiPlaygroundSchema.optional()
+});
+// ============================================================================
+// SEO Schema
+// ============================================================================
+const seoSchema = z.object({
+    indexHiddenPages: z.boolean().optional(),
+    titleTemplate: z.string().optional()
+});
+// ============================================================================
+// Integrations Schema
+// ============================================================================
+const analyticsSchema = z.object({
+    posthog: z.object({
+        apiKey: z.string()
+    }).optional(),
+    googleAnalytics: z.object({
+        measurementId: z.string()
+    }).optional(),
+    plausible: z.object({
+        domain: z.string()
+    }).optional()
+});
+const integrationsSchema = z.object({
+    analytics: analyticsSchema.optional()
+});
+// ============================================================================
+// Contextual Menu Schema
+// ============================================================================
+const contextualOptionsEnum = z.enum([
+    'copy',
+    'view',
+    'chatgpt',
+    'claude',
+    'perplexity',
+    'mcp',
+    'cursor',
+    'vscode'
+]);
+const contextualSchema = z.object({
+    options: z.array(contextualOptionsEnum).optional()
+});
+// ============================================================================
+// Main Configuration Schema
+// ============================================================================
+export const docsConfigSchema = z.object({
+    // Schema reference (optional)
+    $schema: z.string().optional(),
+    // Core identity
+    name: z.string(),
+    // Theme
+    theme: z.enum([
+        'default',
+        'mint',
+        'quill',
+        'venus'
+    ]).optional(),
+    colors: colorSchema.optional(),
+    // Branding
+    favicon: faviconSchema.optional(),
+    logo: logoSchema.optional(),
+    // Navigation
+    navigation: navigationSchema,
+    // Navbar
+    navbar: navbarSchema.optional(),
+    // Footer
+    footer: footerSchema.optional(),
+    // API Configuration
+    api: apiConfigSchema.optional(),
+    openapi: z.union([
+        z.string(),
+        z.array(z.string())
+    ]).optional(),
+    // SEO
+    seo: seoSchema.optional(),
+    // Integrations
+    integrations: integrationsSchema.optional(),
+    // Contextual menu
+    contextual: contextualSchema.optional(),
+    // Topbar style
+    topbar: z.object({
+        style: z.enum([
+            'default',
+            'gradient'
+        ]).optional()
+    }).optional(),
+    // Versioning
+    versions: z.array(z.string()).optional()
+});
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Parse and validate docs configuration
+ */ export function parseDocsConfig(data) {
+    const result = docsConfigSchema.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 docs.json configuration:\n${errors}`);
+    }
+    return result.data;
+}
+/**
+ * Safe parse that returns null on failure
+ */ export function safeParseDocsConfig(data) {
+    const result = docsConfigSchema.safeParse(data);
+    return result.success ? result.data : null;
+}
+/**
+ * Get default configuration
+ */ export function getDefaultDocsConfig() {
+    return {
+        theme: 'default',
+        navigation: {
+            groups: []
+        }
+    };
+}

package/renderer/lib/docs/index.js

@@ -0,0 +1,8 @@
+/**
+ * Documentation Library Exports
+ */ // MDX
+export * from './mdx';
+// Configuration
+export * from './config';
+// Navigation
+export * from './navigation';

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

@@ -0,0 +1,128 @@
+import { compileMDX } from 'next-mdx-remote/rsc';
+import matter from 'gray-matter';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import remarkGfm from 'remark-gfm';
+import { parseFrontmatter, safeParseFrontmatter } from './frontmatter';
+/**
+ * Extract frontmatter from raw MDX content
+ */ export function extractFrontmatter(source) {
+    const { content, data } = matter(source);
+    return {
+        content,
+        data
+    };
+}
+/**
+ * Extract headings from MDX content for table of contents
+ */ export function extractHeadings(content) {
+    const headingRegex = /^(#{1,6})\s+(.+)$/gm;
+    const headings = [];
+    let match;
+    while((match = headingRegex.exec(content)) !== null){
+        const level = match[1].length;
+        const title = match[2].trim();
+        // Generate slug from title (same logic as rehype-slug)
+        const id = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+        headings.push({
+            id,
+            title,
+            level
+        });
+    }
+    return headings;
+}
+/**
+ * Compile MDX content with components and plugins
+ */ export async function compileMDXContent(source, options = {}) {
+    const { components = {}, scope = {}, validateFrontmatter = true } = options;
+    // Extract frontmatter first
+    const { content: mdxContent, data: rawFrontmatter } = extractFrontmatter(source);
+    // Validate frontmatter if requested
+    const frontmatter = validateFrontmatter ? parseFrontmatter(rawFrontmatter) : rawFrontmatter;
+    // Extract headings for ToC
+    const headings = extractHeadings(mdxContent);
+    // Compile MDX
+    const { content } = await compileMDX({
+        source: mdxContent,
+        components,
+        options: {
+            parseFrontmatter: false,
+            mdxOptions: {
+                remarkPlugins: [
+                    remarkGfm
+                ],
+                rehypePlugins: [
+                    rehypeSlug,
+                    [
+                        rehypeAutolinkHeadings,
+                        {
+                            behavior: 'wrap'
+                        }
+                    ]
+                ]
+            },
+            scope: {
+                ...scope,
+                frontmatter
+            }
+        }
+    });
+    return {
+        content,
+        frontmatter,
+        headings
+    };
+}
+/**
+ * Quick compile for previews (less validation)
+ */ export async function quickCompileMDX(source, components = {}) {
+    const { content: mdxContent, data: frontmatter } = extractFrontmatter(source);
+    const { content } = await compileMDX({
+        source: mdxContent,
+        components,
+        options: {
+            parseFrontmatter: false,
+            mdxOptions: {
+                remarkPlugins: [
+                    remarkGfm
+                ],
+                rehypePlugins: [
+                    rehypeSlug
+                ]
+            }
+        }
+    });
+    return {
+        content,
+        frontmatter
+    };
+}
+/**
+ * Validate MDX content without compiling (for linting)
+ */ export function validateMDXContent(source) {
+    const errors = [];
+    const warnings = [];
+    try {
+        const { data } = extractFrontmatter(source);
+        // Check frontmatter
+        const frontmatterResult = safeParseFrontmatter(data);
+        if (!frontmatterResult) {
+            errors.push('Invalid frontmatter format');
+        }
+        // Check for common issues
+        if (!data.title) {
+            warnings.push('Missing title in frontmatter');
+        }
+        if (!data.description) {
+            warnings.push('Missing description in frontmatter (recommended for SEO)');
+        }
+    } catch (error) {
+        errors.push(`Parse error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}