create-specra 0.1.0

package/LICENSE.MD

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dalmasonto, arthur-kamau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# create-specra
+
+The fastest way to create a new Specra documentation site. Scaffold a complete documentation project with a single command.
+
+## Usage
+
+### With npx (recommended)
+
+```bash
+npx create-specra my-docs
+```
+
+### With npm
+
+```bash
+npm create specra my-docs
+```
+
+### With yarn
+
+```bash
+yarn create specra my-docs
+```
+
+### With pnpm
+
+```bash
+pnpm create specra my-docs
+```
+
+## Options
+
+```bash
+npx create-specra [project-directory] [options]
+```
+
+### Arguments
+
+- `[project-directory]` - The directory to create the project in (optional, will prompt if not provided)
+
+### Options
+
+- `--template <template>` - Template to use: `minimal` (will prompt if not provided)
+- `--use-npm` - Use npm as the package manager
+- `--use-pnpm` - Use pnpm as the package manager
+- `--use-yarn` - Use yarn as the package manager
+- `--skip-install` - Skip package installation
+
+## Templates
+
+### Minimal (Default)
+
+Minimal setup to get started quickly:
+- Basic documentation structure
+- Essential configuration
+- Clean starting point
+- Ready to customize
+
+## Examples
+
+Create a new project with interactive prompts:
+
+```bash
+npx create-specra
+```
+
+Create a project with the minimal template using npm:
+
+```bash
+npx create-specra my-docs --template minimal --use-npm
+```
+
+Create a project and skip installation:
+
+```bash
+npx create-specra my-docs --skip-install
+```
+
+## What's Created
+
+The CLI creates a new Next.js project with Specra pre-configured:
+
+```
+my-docs/
+├── app/
+│   ├── layout.tsx
+│   ├── page.tsx
+│   └── [...slug]/
+│       └── page.tsx
+├── docs/
+│   └── v1.0.0/
+│       └── index.mdx
+├── public/
+├── specra.config.ts
+├── next.config.js
+├── tailwind.config.ts
+└── package.json
+```
+
+## After Creation
+
+Once your project is created, you can:
+
+1. Start the development server:
+   ```bash
+   cd my-docs
+   npm run dev
+   ```
+
+2. Open [http://localhost:3000](http://localhost:3000) in your browser
+
+3. Edit your documentation in the `docs/` directory
+
+4. Customize your site in `specra.config.ts`
+
+## What is Specra?
+
+Specra is a modern documentation library for Next.js that provides:
+- Multi-version documentation support
+- API reference generation
+- Full-text search
+- MDX-powered content
+- Beautiful UI components
+
+## Learn More
+
+- [Specra on npm](https://www.npmjs.com/package/specra)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [MDX Documentation](https://mdxjs.com)
+
+## License
+
+MIT
+
+## Authors
+
+dalmasonto, arthur-kamau

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-specra",
+  "version": "0.1.0",
+  "description": "CLI tool to scaffold a new Specra documentation site with Next.js",
+  "type": "module",
+  "bin": {
+    "create-specra": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "documentation",
+    "docs",
+    "nextjs",
+    "mdx",
+    "specra",
+    "create-app",
+    "cli"
+  ],
+  "author": "dalmasonto, arthur-kamau",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
+    "validate-npm-package-name": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/prompts": "^2.4.9",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5"
+  }
+}

package/templates/minimal/README.md

@@ -0,0 +1,132 @@
+# Specra Documentation Site
+
+Welcome to your new Specra documentation site! This project was created with `create-specra`.
+
+## Getting Started
+
+First, install dependencies and run the development server:
+
+```bash
+npm install
+npm run dev
+# or
+yarn install
+yarn dev
+# or
+pnpm install
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see your documentation site.
+
+## Project Structure
+
+```
+├── app/              # Next.js app directory
+│   ├── layout.tsx    # Root layout
+│   ├── page.tsx      # Home page
+│   └── docs/         # Documentation pages
+├── components/       # Reusable components
+│   ├── docs/        # Documentation-specific components
+│   └── ui/          # UI components
+├── docs/            # Your MDX documentation files
+│   └── v1.0.0/     # Version 1.0.0 docs
+├── lib/             # Utility functions
+│   ├── mdx.ts      # MDX processing
+│   ├── config.ts   # Configuration
+│   └── parsers/    # API parsers
+├── public/          # Static assets
+└── specra.config.json  # Specra configuration
+```
+
+## Writing Documentation
+
+Add your MDX files in the `docs/v1.0.0/` directory:
+
+```mdx
+---
+title: My Page
+description: This is my documentation page
+---
+
+# My Page
+
+Your content here...
+```
+
+### Using Components
+
+Import and use components in your MDX:
+
+```mdx
+import { Callout } from '@/components/docs/callout'
+import { CodeBlock } from '@/components/docs/code-block'
+import { Tabs, Tab } from '@/components/docs/tabs'
+
+<Callout type="info">
+  This is an info callout!
+</Callout>
+
+<Tabs>
+  <Tab title="JavaScript">
+    ```js
+    console.log('Hello World')
+    ```
+  </Tab>
+  <Tab title="TypeScript">
+    ```ts
+    console.log('Hello World')
+    ```
+  </Tab>
+</Tabs>
+```
+
+## Configuration
+
+Edit `specra.config.json` to customize your site:
+
+```json
+{
+  "site": {
+    "title": "Your Docs",
+    "description": "Your documentation site",
+    "url": "https://yourdocs.com"
+  },
+  "navigation": {
+    "links": [
+      { "title": "Home", "href": "/" },
+      { "title": "Docs", "href": "/docs" }
+    ]
+  }
+}
+```
+
+## Building for Production
+
+```bash
+npm run build
+npm run start
+```
+
+## Learn More
+
+- [Specra Documentation](https://specra.dev/docs)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [MDX Documentation](https://mdxjs.com)
+
+## Deployment
+
+Deploy your Specra documentation site to Vercel, Netlify, or any hosting platform that supports Next.js.
+
+### Vercel
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new)
+
+### Netlify
+
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start)
+
+## Need Help?
+
+- Check the [documentation](https://specra.dev/docs)
+- Report issues on [GitHub](https://github.com/yourusername/specra/issues)

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

@@ -0,0 +1,80 @@
+import { NextRequest } from 'next/server'
+import { watch } from 'fs'
+import { join } from 'path'
+
+export const dynamic = 'force-static'
+
+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)
+            }
+          }
+        }
+      )
+
+      // Handle client disconnect
+      request.signal.addEventListener('abort', () => {
+        console.log('[MDX Watch] Client disconnected')
+        watcher.close()
+        try {
+          controller.close()
+        } catch (error) {
+          // Controller might already be closed
+        }
+      })
+
+      // Handle errors
+      watcher.on('error', (error) => {
+        console.error('[MDX Watch] Watcher error:', error)
+        watcher.close()
+        try {
+          controller.close()
+        } catch (e) {
+          // Controller might already be closed
+        }
+      })
+    }
+  })
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+    },
+  })
+}

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

@@ -0,0 +1,7 @@
+export default function Loading() {
+    return (
+        <div className="flex items-center justify-center min-h-screen">
+            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-gray-900" />
+        </div>
+    )
+}

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

@@ -0,0 +1,212 @@
+import type { Metadata } from "next"
+import { Suspense } from "react"
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedVersions,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getConfig,
+  SpecraConfig,
+} from "specra/lib"
+import {
+  DocLayout,
+  TableOfContents,
+  Header,
+  DocLayoutWrapper,
+  HotReloadIndicator,
+  DevModeBadge,
+  MdxHotReload,
+  CategoryIndex,
+  NotFoundContent,
+  DocLoading,
+} from "specra/components"
+
+import specraConfig from "./../../../../specra.config.json"
+
+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) {
+      // Add the custom slug path
+      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)
+
+  // 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
+          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}
+        />
+        <MdxHotReload />
+        <HotReloadIndicator />
+        <DevModeBadge />
+      </>
+    )
+  }
+
+  // If no doc found, render 404 content within the layout (keeps sidebar visible)
+  if (!doc) {
+    return (
+      <>
+        <Suspense fallback={<DocLoading />}>
+          <DocLayoutWrapper
+            header={<Header currentVersion={version} versions={versions} config={config} />}
+            docs={allDocs}
+            version={version}
+            content={<NotFoundContent version={version} />}
+            toc={<div />}
+            config={config}
+            currentPageTabGroup={undefined}
+          />
+          <MdxHotReload />
+          <HotReloadIndicator />
+          <DevModeBadge />
+        </Suspense>
+      </>
+    )
+  }
+
+  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 (
+    <>
+      <Suspense fallback={<DocLoading />}>
+        <DocLayoutWrapper
+          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
+                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 items={toc} config={config} />}
+          config={config}
+          currentPageTabGroup={currentPageTabGroup}
+        />
+        <MdxHotReload />
+        <HotReloadIndicator />
+        <DevModeBadge />
+      </Suspense>
+    </>
+  )
+}

package/templates/minimal/app/docs/[version]/not-found.tsx

@@ -0,0 +1,10 @@
+
+import { VersionNotFound } from "specra/components"
+
+export default function NotFound() {
+  return (
+    <>
+      <VersionNotFound />
+    </>
+  )
+}

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

@@ -0,0 +1,27 @@
+import { redirect } from "next/navigation"
+import { getCachedVersions, getCachedAllDocs } from "specra/lib"
+
+interface PageProps {
+  params: Promise<{
+    version: string
+  }>
+}
+
+export async function generateStaticParams() {
+  const versions = getCachedVersions()
+  return versions.map((version) => ({
+    version,
+  }))
+}
+
+export default async function VersionIndexPage({ params }: PageProps) {
+  const { version } = await params
+  const docs = await getCachedAllDocs(version)
+
+  if (docs.length === 0) {
+    redirect("/docs/v1.0.0")
+  }
+
+  // Redirect to first doc
+  redirect(`/docs/${version}/${docs[0].slug}`)
+}

package/templates/minimal/app/globals.css

@@ -0,0 +1 @@
+@import "specra/styles";