create-specra 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-specra",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CLI tool to scaffold a new Specra documentation site with Next.js",
   "type": "module",
   "bin": {

package/templates/minimal/app/api/mdx-watch/route.ts

@@ -1,113 +1,6 @@
-import { NextRequest } from 'next/server'
-import { watch, type FSWatcher } from 'fs'
-import { join } from 'path'
-
-// Mark route as incompatible with static export (since it's dev-only SSE endpoint)
+// Next.js requires dynamic to be statically analyzable, so we can't re-export it
 export const dynamic = 'error'
 export const runtime = 'nodejs'
 
-// Store active watchers globally to clean up on process exit
-const activeWatchers = new Set<FSWatcher>()
-
-// Clean up all watchers on process termination
-if (process.env.NODE_ENV === 'development') {
-  const cleanup = () => {
-    if (activeWatchers.size > 0) {
-      console.log('[MDX Watch] Cleaning up watchers...')
-      activeWatchers.forEach((watcher) => {
-        try {
-          watcher.close()
-        } catch (error) {
-          // Ignore errors during cleanup
-        }
-      })
-      activeWatchers.clear()
-      console.log('[MDX Watch] Cleanup complete')
-    }
-  }
-
-  // Use regular event listeners instead of 'once' to ensure cleanup happens
-  process.on('SIGINT', cleanup)
-  process.on('SIGTERM', cleanup)
-  process.on('beforeExit', cleanup)
-}
-
-export async function GET(request: NextRequest) {
-  // Only allow in development mode
-  if (process.env.NODE_ENV !== 'development') {
-    return new Response('Not available in production', { status: 404 })
-  }
-
-  const encoder = new TextEncoder()
-
-  const stream = new ReadableStream({
-    start(controller) {
-      // Send initial connection message
-      const connectMsg = `data: ${JSON.stringify({ type: 'connected' })}\n\n`
-      controller.enqueue(encoder.encode(connectMsg))
-
-      const docsPath = join(process.cwd(), 'docs')
-
-      // Watch the docs directory recursively
-      const watcher = watch(
-        docsPath,
-        { recursive: true },
-        (eventType, filename) => {
-          if (!filename) return
-
-          // Only watch for .mdx and .json files (MDX files and category configs)
-          if (filename.endsWith('.mdx') || filename.endsWith('.json')) {
-            console.log(`[MDX Watch] ${eventType}: ${filename}`)
-
-            const message = `data: ${JSON.stringify({
-              type: 'change',
-              file: filename,
-              eventType
-            })}\n\n`
-
-            try {
-              controller.enqueue(encoder.encode(message))
-            } catch (error) {
-              console.error('[MDX Watch] Error sending message:', error)
-            }
-          }
-        }
-      )
-
-      // Add to active watchers for cleanup on process exit
-      activeWatchers.add(watcher)
-
-      // Handle cleanup
-      const cleanupWatcher = () => {
-        console.log('[MDX Watch] Closing watcher')
-        activeWatchers.delete(watcher)
-        watcher.close()
-        try {
-          controller.close()
-        } catch (error) {
-          // Controller might already be closed
-        }
-      }
-
-      // Handle client disconnect
-      request.signal.addEventListener('abort', () => {
-        console.log('[MDX Watch] Client disconnected')
-        cleanupWatcher()
-      })
-
-      // Handle errors
-      watcher.on('error', (error) => {
-        console.error('[MDX Watch] Watcher error:', error)
-        cleanupWatcher()
-      })
-    }
-  })
-
-  return new Response(stream, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache, no-transform',
-      'Connection': 'keep-alive',
-    },
-  })
-}
+// Re-export the GET handler from SDK
+export { GET } from "specra/app/api/mdx-watch"

package/templates/minimal/app/api/search/route.ts

@@ -0,0 +1,75 @@
+import { NextRequest, NextResponse } from "next/server"
+import { MeiliSearch } from "meilisearch"
+import { SpecraConfig } from "specra"
+import specraConfig from "../../../specra.config.json"
+
+export async function POST(request: NextRequest) {
+  try {
+    const config: SpecraConfig = specraConfig as any
+    const searchConfig = config.search
+
+    // Check if search is enabled and Meilisearch is configured
+    if (!searchConfig?.enabled || searchConfig.provider !== "meilisearch") {
+      return NextResponse.json(
+        { error: "Search is not enabled" },
+        { status: 400 }
+      )
+    }
+
+    const meilisearchConfig = searchConfig.meilisearch
+    if (!meilisearchConfig) {
+      return NextResponse.json(
+        { error: "Meilisearch is not configured" },
+        { status: 400 }
+      )
+    }
+
+    const { query } = await request.json()
+
+    if (!query || typeof query !== "string") {
+      return NextResponse.json(
+        { error: "Invalid query" },
+        { status: 400 }
+      )
+    }
+
+    // Initialize Meilisearch client with API key
+    const client = new MeiliSearch({
+      host: meilisearchConfig.host,
+      apiKey: meilisearchConfig.apiKey || "",
+    })
+
+    // Search the index
+    const index = client.index(meilisearchConfig.indexName)
+    const searchResults = await index.search(query, {
+      limit: 50, // Get more results before deduplication
+      attributesToHighlight: ["title", "content"],
+      attributesToCrop: ["content"],
+      cropLength: 100,
+    })
+
+    // Deduplicate results by slug and version on the server side
+    const seenDocs = new Set<string>()
+    const uniqueHits = searchResults.hits.filter((hit: any) => {
+      const key = `${hit.version}-${hit.slug}`
+      if (seenDocs.has(key)) {
+        return false
+      }
+      seenDocs.add(key)
+      return true
+    }).slice(0, 20) // Return only top 20 unique results
+
+    return NextResponse.json({
+      hits: uniqueHits,
+      query: query,
+      processingTimeMs: searchResults.processingTimeMs,
+      estimatedTotalHits: uniqueHits.length,
+    })
+  } catch (error) {
+    console.error("Search API error:", error)
+    return NextResponse.json(
+      { error: "Search failed", details: error instanceof Error ? error.message : "Unknown error" },
+      { status: 500 }
+    )
+  }
+}

package/templates/minimal/app/docs/[version]/[...slug]/page.tsx

@@ -8,22 +8,21 @@ import {
   getCachedAllDocs,
   getCachedDocBySlug,
   getConfig,
-  SpecraConfig,
 } from "specra/lib"
 import {
-  DocLayout,
   TableOfContents,
   Header,
   DocLayoutWrapper,
   HotReloadIndicator,
   DevModeBadge,
   MdxHotReload,
-  CategoryIndex,
   NotFoundContent,
   DocLoading,
+  SearchHighlight,
 } from "specra/components"
-
-import specraConfig from "./../../../../specra.config.json"
+import { CategoryIndex, DocLayout } from "specra/layouts"
+import { mdxComponents } from "specra/mdx-components"
+// import { mdxComponents } from "specra/mdx-components"
 
 interface PageProps {
   params: Promise<{
@@ -35,7 +34,6 @@ interface PageProps {
 export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
   const { version, slug: slugArray } = await params
   const slug = slugArray.join("/")
-
   const doc = await getCachedDocBySlug(slug, version)
 
   if (!doc) {
@@ -78,7 +76,6 @@ export async function generateStaticParams() {
   for (const version of versions) {
     const docs = await getCachedAllDocs(version)
     for (const doc of docs) {
-      // Add the custom slug path
       params.push({
         version,
         slug: doc.slug.split("/").filter(Boolean),
@@ -97,36 +94,33 @@ export default async function DocPage({ params }: PageProps) {
   const versions = getCachedVersions()
   const config = getConfig()
   const isCategory = isCategoryPage(slug, allDocs)
-
-  // Try to get the doc (might be index.mdx or regular .mdx)
   const doc = await getCachedDocBySlug(slug, version)
 
-  // If no doc found and it's a category, show category index
   if (!doc && isCategory) {
-    // Find a doc in this category to get the tab group
     const categoryDoc = allDocs.find((d) => d.slug.startsWith(slug + "/"))
     const categoryTabGroup = categoryDoc?.meta?.tab_group || categoryDoc?.categoryTabGroup
 
     return (
       <>
         <DocLayoutWrapper
+        key={'doc-layout'}
           header={<Header currentVersion={version} versions={versions} config={config} />}
           docs={allDocs}
           version={version}
-          content={
-            <CategoryIndex
-              categoryPath={slug}
-              version={version}
-              allDocs={allDocs}
-              title={slug.split("/").pop()?.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase()) || "Category"}
-              description="Browse the documentation in this section."
-              config={config}
-            />
-          }
           toc={<div />}
           config={config}
           currentPageTabGroup={categoryTabGroup}
-        />
+        >
+          <CategoryIndex
+            categoryPath={slug}
+            version={version}
+            allDocs={allDocs}
+            title={slug.split("/").pop()?.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase()) || "Category"}
+            description="Browse the documentation in this section."
+            config={config}
+            mdxComponents={mdxComponents}
+          />
+        </DocLayoutWrapper>
         <MdxHotReload />
         <HotReloadIndicator />
         <DevModeBadge />
@@ -134,7 +128,6 @@ export default async function DocPage({ params }: PageProps) {
     )
   }
 
-  // If no doc found, render 404 content within the layout (keeps sidebar visible)
   if (!doc) {
     return (
       <>
@@ -143,11 +136,12 @@ export default async function DocPage({ params }: PageProps) {
             header={<Header currentVersion={version} versions={versions} config={config} />}
             docs={allDocs}
             version={version}
-            content={<NotFoundContent version={version} />}
             toc={<div />}
             config={config}
             currentPageTabGroup={undefined}
-          />
+          >
+            <NotFoundContent version={version} />
+          </DocLayoutWrapper>
           <MdxHotReload />
           <HotReloadIndicator />
           <DevModeBadge />
@@ -158,15 +152,7 @@ export default async function DocPage({ params }: PageProps) {
 
   const toc = extractTableOfContents(doc.content)
   const { previous, next } = getAdjacentDocs(slug, allDocs)
-
-  // console.log("[v0] Extracted ToC:", toc)
-
-  // If doc exists but is also a category, show both content and children
   const showCategoryIndex = isCategory && doc
-
-  // console.log("showCategoryIndex: ", showCategoryIndex)
-
-  // Get current page's tab group from doc metadata or category
   const currentPageTabGroup = doc.meta?.tab_group || doc.categoryTabGroup
 
   return (
@@ -176,34 +162,39 @@ export default async function DocPage({ params }: PageProps) {
           header={<Header currentVersion={version} versions={versions} config={config} />}
           docs={allDocs}
           version={version}
-          content={
-            showCategoryIndex ? (
-              <CategoryIndex
-                categoryPath={slug}
-                version={version}
-                allDocs={allDocs}
-                title={doc.meta.title}
-                description={doc.meta.description}
-                content={doc.content}
-                config={config}
-              />
-            ) : (
-              <DocLayout
-                key={`doc-layout`}
-                meta={doc.meta}
-                content={doc.content}
-                previousDoc={previous ? { title: previous.meta.title, slug: previous.slug } : undefined}
-                nextDoc={next ? { title: next.meta.title, slug: next.slug } : undefined}
-                version={version}
-                slug={slug}
-                config={config}
-              />
-            )
-          }
-          toc={showCategoryIndex ? <div /> : <TableOfContents key={'table-of-contents'} items={toc} config={config} />}
+          toc={showCategoryIndex ? <div /> : <TableOfContents key={'toc'} items={toc} config={config} />}
           config={config}
           currentPageTabGroup={currentPageTabGroup}
-        />
+        >
+          {showCategoryIndex ? (
+            <CategoryIndex
+              key="category-index"
+              categoryPath={slug}
+              version={version}
+              allDocs={allDocs}
+              title={doc.meta.title}
+              description={doc.meta.description}
+              content={doc.content}
+              config={config}
+              mdxComponents={mdxComponents}
+            />
+          ) : (
+            <>
+            <SearchHighlight />
+            <DocLayout
+              key="doc-layout"
+              meta={doc.meta}
+              content={doc.content}
+              previousDoc={previous ? { title: previous.meta.title, slug: previous.slug } : undefined}
+              nextDoc={next ? { title: next.meta.title, slug: next.slug } : undefined}
+              version={version}
+              slug={slug}
+              config={config}
+              mdxComponents={mdxComponents}
+            />
+            </>
+          )}
+        </DocLayoutWrapper>
         <MdxHotReload />
         <HotReloadIndicator />
         <DevModeBadge />
@@ -211,3 +202,4 @@ export default async function DocPage({ params }: PageProps) {
     </>
   )
 }
+

package/templates/minimal/app/docs/[version]/[...slug]/page.tsx.bak

@@ -0,0 +1,203 @@
+import type { Metadata } from "next"
+import { Suspense } from "react"
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedVersions,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getConfig,
+} from "specra/lib"
+import {
+  TableOfContents,
+  Header,
+  DocLayoutWrapper,
+  HotReloadIndicator,
+  DevModeBadge,
+  MdxHotReload,
+  NotFoundContent,
+  DocLoading,
+} from "specra/components"
+import { CategoryIndex, DocLayout } from "specra/layouts"
+import { mdxComponents } from "specra/mdx-components"
+// import { mdxComponents } from "specra/mdx-components"
+
+interface PageProps {
+  params: Promise<{
+    version: string
+    slug: string[]
+  }>
+}
+
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { version, slug: slugArray } = await params
+  const slug = slugArray.join("/")
+  const doc = await getCachedDocBySlug(slug, version)
+
+  if (!doc) {
+    return {
+      title: "Page Not Found",
+      description: "The requested documentation page could not be found.",
+    }
+  }
+
+  const title = doc.meta.title || doc.title
+  const description = doc.meta.description || `Documentation for ${title}`
+  const url = `/docs/${version}/${slug}`
+
+  return {
+    title: `${title}`,
+    description,
+    openGraph: {
+      title,
+      description,
+      url,
+      siteName: "Documentation Platform",
+      type: "article",
+      locale: "en_US",
+    },
+    twitter: {
+      card: "summary_large_image",
+      title,
+      description,
+    },
+    alternates: {
+      canonical: url,
+    },
+  }
+}
+
+export async function generateStaticParams() {
+  const versions = getCachedVersions()
+  const params = []
+
+  for (const version of versions) {
+    const docs = await getCachedAllDocs(version)
+    for (const doc of docs) {
+      params.push({
+        version,
+        slug: doc.slug.split("/").filter(Boolean),
+      })
+    }
+  }
+
+  return params
+}
+
+export default async function DocPage({ params }: PageProps) {
+  const { version, slug: slugArray } = await params
+  const slug = slugArray.join("/")
+
+  const allDocs = await getCachedAllDocs(version)
+  const versions = getCachedVersions()
+  const config = getConfig()
+  const isCategory = isCategoryPage(slug, allDocs)
+  const doc = await getCachedDocBySlug(slug, version)
+
+  if (!doc && isCategory) {
+    const categoryDoc = allDocs.find((d) => d.slug.startsWith(slug + "/"))
+    const categoryTabGroup = categoryDoc?.meta?.tab_group || categoryDoc?.categoryTabGroup
+
+    return (
+      <>
+        <DocLayoutWrapper
+        key={'doc-layout'}
+          header={<Header currentVersion={version} versions={versions} config={config} />}
+          docs={allDocs}
+          version={version}
+          toc={<div />}
+          config={config}
+          currentPageTabGroup={categoryTabGroup}
+        >
+          <CategoryIndex
+            categoryPath={slug}
+            version={version}
+            allDocs={allDocs}
+            title={slug.split("/").pop()?.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase()) || "Category"}
+            description="Browse the documentation in this section."
+            config={config}
+            mdxComponents={mdxComponents}
+          />
+        </DocLayoutWrapper>
+        <MdxHotReload />
+        <HotReloadIndicator />
+        <DevModeBadge />
+      </>
+    )
+  }
+
+  if (!doc) {
+    return (
+      <>
+        <Suspense fallback={<DocLoading />}>
+          <DocLayoutWrapper
+            header={<Header currentVersion={version} versions={versions} config={config} />}
+            docs={allDocs}
+            version={version}
+            toc={<div />}
+            config={config}
+            currentPageTabGroup={undefined}
+          >
+            <NotFoundContent version={version} />
+          </DocLayoutWrapper>
+          <MdxHotReload />
+          <HotReloadIndicator />
+          <DevModeBadge />
+        </Suspense>
+      </>
+    )
+  }
+
+  const toc = extractTableOfContents(doc.content)
+  const { previous, next } = getAdjacentDocs(slug, allDocs)
+  const showCategoryIndex = isCategory && doc
+  const currentPageTabGroup = doc.meta?.tab_group || doc.categoryTabGroup
+
+  console.log(mdxComponents)
+
+  return (
+    <>
+      <Suspense fallback={<DocLoading />}>
+        <DocLayoutWrapper
+          header={<Header currentVersion={version} versions={versions} config={config} />}
+          docs={allDocs}
+          version={version}
+          toc={showCategoryIndex ? <div /> : <TableOfContents key={'toc'} items={toc} config={config} />}
+          config={config}
+          currentPageTabGroup={currentPageTabGroup}
+        >
+          {showCategoryIndex ? (
+            <CategoryIndex
+              key="category-index"
+              categoryPath={slug}
+              version={version}
+              allDocs={allDocs}
+              title={doc.meta.title}
+              description={doc.meta.description}
+              content={doc.content}
+              config={config}
+              mdxComponents={mdxComponents}
+            />
+          ) : (
+            <DocLayout
+              key="doc-layout"
+              meta={doc.meta}
+              content={doc.content}
+              previousDoc={previous ? { title: previous.meta.title, slug: previous.slug } : undefined}
+              nextDoc={next ? { title: next.meta.title, slug: next.slug } : undefined}
+              version={version}
+              slug={slug}
+              config={config}
+              mdxComponents={mdxComponents}
+            />
+          )}
+        </DocLayoutWrapper>
+        <MdxHotReload />
+        <HotReloadIndicator />
+        <DevModeBadge />
+      </Suspense>
+    </>
+  )
+}
+

package/templates/minimal/app/globals.css

@@ -1 +1,9 @@
-@import "specra/styles";
+@import "specra/styles";
+
+/* Scan app files for Tailwind utilities */
+@source "./**/*.{js,ts,jsx,tsx,mdx}";
+
+@theme inline {
+    --font-sans: "Geist", "Geist Fallback";
+    --font-mono: "Geist Mono", "Geist Mono Fallback";
+}

package/templates/minimal/app/layout.tsx

@@ -1,33 +1,16 @@
-import "server-only"
-
-import type React from "react"
 import type { Metadata } from "next"
 import { Geist, Geist_Mono } from "next/font/google"
-
 import { getConfig, getAssetPath, SpecraConfig, initConfig } from "specra/lib"
-import { TabProvider, ConfigProvider } from "specra/components"
-
+import { ConfigProvider, TabProvider } from "specra/components"
 import specraConfig from "../specra.config.json"
 import "./globals.css"
 
-/* -----------------------------
-   Fonts
------------------------------- */
-const geist = Geist({ subsets: ["latin"] })
-const geistMono = Geist_Mono({ subsets: ["latin"] })
-
-// const sans = Geist({ subsets: ["latin"] })
-// const geistMono = Geist_Mono({ subsets: ["latin"] })
+const _geist = Geist({ subsets: ["latin"] })
+const _geistMono = Geist_Mono({ subsets: ["latin"] })
 
-/* -----------------------------
-   Initialize Specra config ONCE
-   (module scope, server-only)
------------------------------- */
+// Initialize Specra config
 initConfig(specraConfig as unknown as Partial<SpecraConfig>)
 
-/* -----------------------------
-   Runtime Metadata (REQUIRED)
------------------------------- */
 export async function generateMetadata(): Promise<Metadata> {
   const config = getConfig()
 
@@ -37,13 +20,9 @@ export async function generateMetadata(): Promise<Metadata> {
       template: `%s | ${config.site.title}`,
     },
     description: config.site.description || "Modern documentation platform",
-    metadataBase: config.site.url
-      ? new URL(config.site.url)
-      : undefined,
+    metadataBase: config.site.url ? new URL(config.site.url) : undefined,
     icons: {
-      icon: config.site.favicon
-        ? [{ url: getAssetPath(config.site.favicon) }]
-        : [],
+      icon: config.site.favicon ? [{ url: getAssetPath(config.site.favicon) }] : [],
       apple: getAssetPath("/apple-icon.png"),
     },
     openGraph: {
@@ -62,22 +41,14 @@ export async function generateMetadata(): Promise<Metadata> {
   }
 }
 
-/* -----------------------------
-   Root Layout
------------------------------- */
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   const config = getConfig()
-  const defaultTab =
-    config.navigation?.tabGroups?.[0]?.id ?? ""
+  const defaultTab = config.navigation?.tabGroups?.[0]?.id ?? ""
 
   return (
     <html lang={config.site.language || "en"}>
       <body
-        // className={`${geist.className} ${geistMono.className} antialiased`}
+        // className={`${geist.className} ${geist.style.fontFamily} font-sans antialiased`}
         className={`font-sans antialiased`}
       >
         <ConfigProvider config={config}>