specra-cli 0.3.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "specra-cli",
+  "version": "0.3.0",
+  "description": "CLI tool to create, deploy, and manage Specra documentation sites",
+  "type": "module",
+  "bin": {
+    "specra": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "documentation",
+    "docs",
+    "sveltekit",
+    "svelte",
+    "mdx",
+    "specra",
+    "cli"
+  ],
+  "author": "dalmasonto, arthur-kamau",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpecraDocs/specra-cli"
+  },
+  "homepage": "https://github.com/SpecraDocs",
+  "license": "SEE LICENSE IN LICENSE.MD",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "open": "^11.0.0",
+    "ora": "^9.3.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
+    "tar": "^7.5.7",
+    "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/book-docs/.env.sample

@@ -0,0 +1 @@
+SPECTRA_TOKEN=sk_xxx...

package/templates/book-docs/docs/v1.0.0/concepts.mdx

@@ -0,0 +1,89 @@
+---
+title: Core Concepts
+description: Understand the key ideas behind the documentation platform
+sidebar_position: 3
+icon: lightbulb
+---
+
+Before diving into content creation, it helps to understand a few core concepts that shape how the platform works.
+
+## MDX
+
+MDX is Markdown with components. You write standard Markdown and can embed rich, interactive components directly in your content.
+
+```mdx
+# Regular Markdown
+
+This is a paragraph with **bold** and *italic* text.
+
+<Callout type="tip">
+  And this is an interactive component inside Markdown!
+</Callout>
+```
+
+<Callout type="info">
+  All documentation files use the `.mdx` extension, not `.md`.
+</Callout>
+
+## Frontmatter
+
+Every page starts with frontmatter — a YAML block at the top of the file that defines metadata:
+
+```mdx
+---
+title: Page Title
+description: A short description for SEO
+sidebar_position: 1
+icon: book
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Page title shown in sidebar and browser tab |
+| `description` | Recommended | Short description for search engines |
+| `sidebar_position` | No | Controls order in sidebar (lower number = higher up) |
+| `icon` | No | Lucide icon name for the sidebar |
+| `tags` | No | Array of tags for categorization |
+
+## Versioning
+
+Documentation is organized by version. Each version lives in its own folder:
+
+```txt
+docs/
+├── v1.0.0/    # Stable release
+├── v2.0.0/    # Next major release
+└── next/      # Development docs
+```
+
+Users can switch between versions using the version selector in the header.
+
+## Sidebar Navigation
+
+The sidebar is automatically generated from your folder structure. You control the order and appearance using:
+
+- **`sidebar_position`** in frontmatter — sets page order
+- **`_category_.json`** in folders — configures section labels and behavior
+
+```json
+{
+  "label": "Getting Started",
+  "position": 1,
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+## Components
+
+The platform includes a library of built-in components that you can use without any imports:
+
+<CardGrid cols={3}>
+  <Card icon="message-square" title="Callouts" description="Highlight important info" />
+  <Card icon="layers" title="Tabs" description="Tabbed content panels" />
+  <Card icon="list" title="Steps" description="Step-by-step guides" />
+  <Card icon="grid" title="Cards" description="Feature cards with icons" />
+  <Card icon="code" title="Code Blocks" description="Syntax-highlighted code" />
+  <Card icon="chevrons-up-down" title="Accordion" description="Collapsible sections" />
+</CardGrid>

package/templates/book-docs/docs/v1.0.0/content/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Content",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "file-text"
+}

package/templates/book-docs/docs/v1.0.0/content/formatting.mdx

@@ -0,0 +1,128 @@
+---
+title: Formatting
+description: Format your content with Markdown and components
+sidebar_position: 1
+---
+
+This guide covers the formatting options available for your documentation pages.
+
+## Text Formatting
+
+Standard Markdown formatting is fully supported:
+
+| Syntax | Output |
+|--------|--------|
+| `**bold**` | **bold** |
+| `*italic*` | *italic* |
+| `` `code` `` | `code` |
+| `~~strikethrough~~` | ~~strikethrough~~ |
+
+## Headings
+
+Use headings to structure your content. The table of contents on the right is generated from your headings.
+
+```markdown
+## Second Level
+### Third Level
+#### Fourth Level
+```
+
+<Callout type="tip">
+  Start with `##` (H2) in your content. The page title from frontmatter is rendered as H1 automatically.
+</Callout>
+
+## Lists
+
+### Unordered Lists
+
+```markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+```
+
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+- Third item
+
+### Ordered Lists
+
+1. First step
+2. Second step
+3. Third step
+
+## Code Blocks
+
+Use fenced code blocks with a language identifier for syntax highlighting:
+
+```typescript
+interface Config {
+  title: string;
+  theme: 'light' | 'dark' | 'system';
+  version: string;
+}
+
+function loadConfig(path: string): Config {
+  const raw = readFileSync(path, 'utf-8');
+  return JSON.parse(raw);
+}
+```
+
+## Tables
+
+```markdown
+| Feature | Status |
+|---------|--------|
+| Dark Mode | Supported |
+| Search | Supported |
+| i18n | Coming Soon |
+```
+
+| Feature | Status |
+|---------|--------|
+| Dark Mode | Supported |
+| Search | Supported |
+| i18n | Coming Soon |
+
+## Callouts
+
+Use callouts to draw attention to important information:
+
+<Callout type="info">
+  Informational callouts provide additional context.
+</Callout>
+
+<Callout type="warning">
+  Warning callouts alert readers to potential issues.
+</Callout>
+
+<Callout type="tip">
+  Tip callouts suggest best practices or shortcuts.
+</Callout>
+
+## Tabs
+
+Use tabs to show alternative content side by side:
+
+<Tabs defaultValue="JavaScript">
+  <Tab label="JavaScript">
+```javascript
+console.log("Hello, world!");
+```
+  </Tab>
+  <Tab label="Python">
+```python
+print("Hello, world!")
+```
+  </Tab>
+</Tabs>
+
+## Links
+
+- **Internal links**: `[Getting Started](/docs/v1.0.0/quickstart)`
+- **External links**: `[GitHub](https://github.com)`
+- **Anchor links**: `[See below](#callouts)`

package/templates/book-docs/docs/v1.0.0/content/reusable-content.mdx

@@ -0,0 +1,116 @@
+---
+title: Reusable Content
+description: Create reusable content blocks for consistent documentation
+sidebar_position: 3
+---
+
+Reusable content helps you maintain consistency across your documentation by defining content once and using it in multiple places.
+
+## Components as Reusable Blocks
+
+The built-in component library provides reusable patterns for common documentation needs.
+
+### Card Grids
+
+Use card grids to create consistent navigation sections across pages:
+
+<CardGrid cols={3}>
+  <Card icon="zap" title="Fast" description="Optimized for speed" />
+  <Card icon="shield" title="Secure" description="Built with security in mind" />
+  <Card icon="code" title="Developer First" description="Great developer experience" />
+</CardGrid>
+
+### Step-by-Step Patterns
+
+Use the Steps component for consistent instructional content:
+
+<Steps>
+  <Step title="Define the Content">
+    Write your content in MDX format with clear, concise language.
+  </Step>
+
+  <Step title="Add Components">
+    Enhance your content with interactive components like callouts, tabs, and cards.
+  </Step>
+
+  <Step title="Review and Publish">
+    Preview your changes locally, then commit and deploy.
+  </Step>
+</Steps>
+
+## Consistent Callout Patterns
+
+Use standardized callout types across your docs for a consistent reading experience:
+
+<Callout type="info">
+  **Info callouts** provide supplementary context that helps readers understand a topic better.
+</Callout>
+
+<Callout type="warning">
+  **Warning callouts** alert readers about potential pitfalls or breaking changes.
+</Callout>
+
+<Callout type="tip">
+  **Tip callouts** share best practices and shortcuts that improve the reader's workflow.
+</Callout>
+
+## Tabbed Content Patterns
+
+Use tabs to provide content variations. Common patterns include:
+
+### Installation Instructions
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm install my-package
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn add my-package
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm add my-package
+```
+  </Tab>
+</Tabs>
+
+### Language Examples
+
+<Tabs defaultValue="TypeScript">
+  <Tab label="TypeScript">
+```typescript
+const greeting: string = "Hello, world!";
+console.log(greeting);
+```
+  </Tab>
+  <Tab label="Python">
+```python
+greeting = "Hello, world!"
+print(greeting)
+```
+  </Tab>
+  <Tab label="Go">
+```go
+package main
+
+import "fmt"
+
+func main() {
+    fmt.Println("Hello, world!")
+}
+```
+  </Tab>
+</Tabs>
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Use consistent types** | Always use the same callout type for the same kind of information |
+| **Keep cards brief** | Card descriptions should be one short sentence |
+| **Limit tab count** | Use 2-4 tabs per group for readability |
+| **Name tabs clearly** | Tab labels should be short and descriptive |

package/templates/book-docs/docs/v1.0.0/content/structure.mdx

@@ -0,0 +1,92 @@
+---
+title: Content Structure
+description: Organize your documentation with folders and categories
+sidebar_position: 2
+---
+
+Learn how to organize your documentation into a clear, navigable structure.
+
+## File Organization
+
+Documentation files live in the `docs/` directory, grouped by version:
+
+```txt
+docs/
+├── v1.0.0/
+│   ├── introduction.mdx
+│   ├── quickstart.mdx
+│   ├── guides/
+│   │   ├── _category_.json
+│   │   ├── installation.mdx
+│   │   └── deployment.mdx
+│   └── reference/
+│       ├── _category_.json
+│       └── api.mdx
+└── v2.0.0/
+    └── ...
+```
+
+## Categories
+
+Folders become sidebar sections. Add a `_category_.json` file to configure each section:
+
+```json
+{
+  "label": "Guides",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "book-open"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `label` | Display name in the sidebar |
+| `position` | Order relative to other sections |
+| `collapsible` | Whether the section can be collapsed |
+| `collapsed` | Whether the section starts collapsed |
+| `icon` | Lucide icon name |
+
+## Page Ordering
+
+Pages within a section are ordered by their `sidebar_position` frontmatter value:
+
+```mdx
+---
+title: First Page
+sidebar_position: 1
+---
+```
+
+<Callout type="info">
+  Pages without a `sidebar_position` are sorted alphabetically after positioned pages.
+</Callout>
+
+## Index Pages
+
+Create an `index.mdx` in a folder to provide a landing page for that section. When users click the section header in the sidebar, they'll see this page.
+
+```txt
+guides/
+├── _category_.json
+├── index.mdx          # Landing page for "Guides"
+├── installation.mdx
+└── deployment.mdx
+```
+
+## Best Practices
+
+<Steps>
+  <Step title="Keep It Flat">
+    Avoid deeply nested folders. Two levels of nesting is usually enough for most documentation sites.
+  </Step>
+
+  <Step title="Use Descriptive Names">
+    File names become URL slugs. Use lowercase, hyphenated names like `getting-started.mdx`.
+  </Step>
+
+  <Step title="Group Related Content">
+    Put related pages in the same folder. This makes the sidebar intuitive and keeps URLs predictable.
+  </Step>
+</Steps>

package/templates/book-docs/docs/v1.0.0/customization/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Customization",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "palette"
+}

package/templates/book-docs/docs/v1.0.0/customization/branding.mdx

@@ -0,0 +1,115 @@
+---
+title: Branding
+description: Customize logos, site title, and brand identity
+sidebar_position: 2
+---
+
+Make the documentation site match your brand by customizing the title, description, social links, and footer.
+
+## Site Identity
+
+Configure basic site information in `specra.config.json`:
+
+```json
+{
+  "site": {
+    "title": "My Project Docs",
+    "description": "Official documentation for My Project",
+    "url": "https://docs.myproject.com",
+    "organizationName": "My Organization",
+    "projectName": "my-project"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `title` | Displayed in the header and browser tab |
+| `description` | Used for SEO meta tags |
+| `url` | Full URL where docs are hosted |
+| `organizationName` | Your company or organization name |
+| `projectName` | Project identifier |
+
+## Social Links
+
+Add links to your social profiles and repositories:
+
+```json
+{
+  "social": {
+    "github": "https://github.com/your-org/your-repo",
+    "twitter": "https://twitter.com/yourhandle",
+    "discord": "https://discord.gg/yourserver"
+  }
+}
+```
+
+Social links appear as icons in the site header.
+
+## Footer
+
+Customize the footer with copyright text and link columns:
+
+```json
+{
+  "footer": {
+    "copyright": "Copyright © 2025 My Organization. All rights reserved.",
+    "branding": {
+      "showBranding": true
+    },
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          { "label": "Getting Started", "href": "/docs/v1.0.0/quickstart" },
+          { "label": "Concepts", "href": "/docs/v1.0.0/concepts" }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          { "label": "GitHub", "href": "https://github.com/your-org" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+<Callout type="info">
+  The footer supports multiple link columns. Each column has a title and a list of labeled links.
+</Callout>
+
+## Banner
+
+Display a site-wide announcement banner:
+
+```json
+{
+  "banner": {
+    "enabled": true,
+    "message": "We just launched v2.0 — check out what's new!",
+    "type": "info",
+    "dismissible": true
+  }
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Show or hide the banner |
+| `message` | `string` | Banner text content |
+| `type` | `"info" \| "warning" \| "error"` | Visual style |
+| `dismissible` | `boolean` | Allow users to close the banner |
+
+## Favicon
+
+Place your favicon file in the `public/` directory and reference it in `src/app.html`:
+
+```html
+<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+```
+
+<Callout type="tip">
+  Use SVG favicons for crisp rendering at any size and automatic dark mode support.
+</Callout>

package/templates/book-docs/docs/v1.0.0/customization/themes.mdx

@@ -0,0 +1,81 @@
+---
+title: Themes
+description: Configure the look and feel of your documentation site
+sidebar_position: 1
+---
+
+The platform supports light and dark themes out of the box, with full control over which mode is used by default.
+
+## Theme Modes
+
+Three theme modes are available:
+
+| Mode | Description |
+|------|-------------|
+| `light` | Always use the light theme |
+| `dark` | Always use the dark theme |
+| `system` | Follow the user's operating system preference |
+
+## Configuration
+
+Set the default theme in `specra.config.json`:
+
+```json
+{
+  "theme": {
+    "defaultMode": "dark",
+    "respectPrefersColorScheme": true
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultMode` | `"light" \| "dark" \| "system"` | `"system"` | Initial theme mode |
+| `respectPrefersColorScheme` | `boolean` | `true` | Whether to detect and follow OS preference |
+
+<Callout type="info">
+  When `respectPrefersColorScheme` is `true` and `defaultMode` is `"system"`, the site automatically switches themes when the user changes their OS appearance settings.
+</Callout>
+
+## Theme Toggle
+
+Users can switch themes using the toggle button in the site header. Their preference is saved in local storage and persists across visits.
+
+## Customizing Colors
+
+All colors are defined as CSS custom properties, making them easy to override:
+
+```css
+:root {
+  --primary: oklch(0.55 0.22 264.376);
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+}
+
+.dark {
+  --primary: oklch(0.65 0.22 264.376);
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.95 0 0);
+}
+```
+
+<Callout type="tip">
+  Use the OKLCH color space for perceptually uniform color adjustments. This ensures colors look consistent across light and dark themes.
+</Callout>
+
+## Best Practices
+
+<Steps>
+  <Step title="Choose a Default">
+    Pick a default theme that matches your brand. For developer documentation, dark mode is often preferred.
+  </Step>
+
+  <Step title="Test Both Themes">
+    Always preview your content in both light and dark modes. Ensure images, diagrams, and code blocks are readable in both.
+  </Step>
+
+  <Step title="Respect User Preference">
+    Keep `respectPrefersColorScheme` enabled so users get the theme they expect.
+  </Step>
+</Steps>