specra-cli 0.3.0

package/templates/jbrains-docs/docs/v1.0.0/getting-started.mdx

@@ -0,0 +1,111 @@
+---
+title: Getting Started
+description: Set up your environment and create your first project
+sidebar_position: 2
+icon: rocket
+---
+
+This guide walks you through setting up your development environment and writing your first program.
+
+## Prerequisites
+
+- **Node.js 18+** installed on your machine
+- A code editor (VS Code recommended)
+- A terminal or command line
+
+## Create a Project
+
+<Steps>
+  <Step title="Scaffold the Project">
+    Use the CLI to create a new project:
+
+    ```bash
+    npx create-specra my-project
+    ```
+  </Step>
+
+  <Step title="Install Dependencies">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+cd my-project && npm install
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+cd my-project && yarn install
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+cd my-project && pnpm install
+```
+      </Tab>
+    </Tabs>
+  </Step>
+
+  <Step title="Run the Project">
+    <Tabs defaultValue="npm">
+      <Tab label="npm">
+```bash
+npm run dev
+```
+      </Tab>
+      <Tab label="yarn">
+```bash
+yarn dev
+```
+      </Tab>
+      <Tab label="pnpm">
+```bash
+pnpm dev
+```
+      </Tab>
+    </Tabs>
+
+    Open `http://localhost:5173` in your browser.
+  </Step>
+</Steps>
+
+## Project Structure
+
+A newly scaffolded project has this structure:
+
+```txt
+my-project/
+├── docs/
+│   ├── v1.0.0/          # Documentation content
+│   └── v2.0.0/          # Another version
+├── src/                  # Application source
+├── specra.config.json    # Configuration
+└── package.json
+```
+
+## Hello World
+
+Create a new file `docs/v1.0.0/hello.mdx`:
+
+```mdx
+---
+title: Hello World
+sidebar_position: 99
+---
+
+# Hello World
+
+This is your first documentation page!
+
+```
+
+<Callout type="tip">
+  Files are automatically picked up by the sidebar. Use `sidebar_position` to control ordering.
+</Callout>
+
+## What's Next
+
+Now that you have a running project, explore the language fundamentals:
+
+<CardGrid cols={2}>
+  <Card icon="code" title="Basic Syntax" description="Learn the fundamental building blocks" href="/docs/v1.0.0/basics/syntax" />
+  <Card icon="layers" title="Types & Variables" description="Understand the type system" href="/docs/v1.0.0/basics/types" />
+</CardGrid>

package/templates/jbrains-docs/docs/v1.0.0/home.mdx

@@ -0,0 +1,37 @@
+---
+title: Home
+description: Welcome to the language documentation
+sidebar_position: 1
+icon: home
+---
+
+Welcome to the documentation. Learn the language from basics to advanced topics, and explore multiplatform tooling.
+
+## Get Started
+
+<CardGrid cols={2}>
+  <Card icon="book-open" title="Get Started" description="Set up your environment and write your first program" href="/docs/v1.0.0/getting-started" />
+  <Card icon="code" title="Basic Syntax" description="Learn the fundamental syntax and structure" href="/docs/v1.0.0/basics/syntax" />
+  <Card icon="layers" title="Types & Variables" description="Understand the type system and variable declarations" href="/docs/v1.0.0/basics/types" />
+  <Card icon="wrench" title="Build Tools" description="Configure and use build tools for your projects" href="/docs/v1.0.0/tools/build-tools" />
+</CardGrid>
+
+## Language
+
+The **Language** section covers everything from basic syntax to advanced features like generics and async programming.
+
+<Callout type="info">
+  If you're new, start with the [Getting Started](/docs/v1.0.0/getting-started) guide, then work through the Basics section.
+</Callout>
+
+## Multiplatform
+
+The **Multiplatform** section covers tooling, build systems, and testing across different platforms and environments.
+
+## What's in This Documentation
+
+| Section | Description |
+|---------|-------------|
+| **Basics** | Syntax, types, variables, and control flow |
+| **Advanced** | Generics, async programming, and advanced patterns |
+| **Tools** | Build tools, testing frameworks, and project setup |

package/templates/jbrains-docs/docs/v1.0.0/tools/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Tools",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "wrench",
+  "tab_group": "multiplatform"
+}

package/templates/jbrains-docs/docs/v1.0.0/tools/build-tools.mdx

@@ -0,0 +1,165 @@
+---
+title: Build Tools
+description: Configure and use build tools for your documentation project
+sidebar_position: 1
+---
+
+This page covers the build tools used to develop, build, and deploy your documentation site.
+
+## Development Server
+
+Start the development server with hot reload:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run dev
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn dev
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm dev
+```
+  </Tab>
+</Tabs>
+
+The dev server runs on `http://localhost:5173` by default with:
+- **Hot Module Replacement (HMR)** — instant updates when you edit MDX files
+- **Error overlay** — displays build errors in the browser
+- **Fast startup** — powered by Vite
+
+## Production Build
+
+Build the site for production:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run build
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn build
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm build
+```
+  </Tab>
+</Tabs>
+
+This outputs a static site to the `build/` directory.
+
+<Callout type="info">
+  The production build pre-renders all pages for optimal performance and SEO.
+</Callout>
+
+## Preview
+
+Preview the production build locally:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run preview
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn preview
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm preview
+```
+  </Tab>
+</Tabs>
+
+## Vite Configuration
+
+The documentation platform uses Vite as its build tool. The default configuration is in `vite.config.ts`:
+
+```typescript
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [sveltekit()]
+});
+```
+
+## SvelteKit Configuration
+
+SvelteKit is configured in `svelte.config.js`:
+
+```javascript
+import { specraConfig } from 'specra/svelte-config';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+const config = specraConfig({
+  vitePreprocess: { vitePreprocess }
+});
+
+export default config;
+```
+
+## PostCSS & Tailwind
+
+Styling is handled by Tailwind CSS via PostCSS. Configuration is in `postcss.config.mjs`:
+
+```javascript
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;
+```
+
+## TypeScript
+
+TypeScript is configured in `tsconfig.json` with strict mode enabled:
+
+```json
+{
+  "extends": "./.svelte-kit/tsconfig.json",
+  "compilerOptions": {
+    "strict": true,
+    "allowJs": true,
+    "checkJs": true
+  }
+}
+```
+
+## Type Checking
+
+Run the type checker:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run check
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn check
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm check
+```
+  </Tab>
+</Tabs>
+
+This runs `svelte-kit sync` followed by `svelte-check` to verify your TypeScript types.

package/templates/jbrains-docs/docs/v1.0.0/tools/testing.mdx

@@ -0,0 +1,112 @@
+---
+title: Testing
+description: Verify your documentation builds and renders correctly
+sidebar_position: 2
+---
+
+This page covers strategies for testing your documentation site to ensure content renders correctly and the build succeeds.
+
+## Build Verification
+
+The simplest test is to run a production build and check for errors:
+
+<Tabs defaultValue="npm">
+  <Tab label="npm">
+```bash
+npm run build
+```
+  </Tab>
+  <Tab label="yarn">
+```bash
+yarn build
+```
+  </Tab>
+  <Tab label="pnpm">
+```bash
+pnpm build
+```
+  </Tab>
+</Tabs>
+
+The build will fail if:
+- MDX files have syntax errors
+- Frontmatter is malformed
+- Required fields are missing
+
+<Callout type="tip">
+  Run `npm run build` in your CI pipeline to catch documentation errors before they reach production.
+</Callout>
+
+## Type Checking
+
+Verify TypeScript types are correct:
+
+```bash
+npm run check
+```
+
+This catches type errors in your SvelteKit configuration and any custom components.
+
+## Content Checklist
+
+When reviewing documentation changes, verify:
+
+| Check | Description |
+|-------|-------------|
+| **Frontmatter** | All pages have `title`, and key pages have `description` |
+| **Links** | Internal links point to existing pages |
+| **Versions** | Content exists in all active version directories |
+| **Sidebar Order** | `sidebar_position` values create a logical reading flow |
+| **Categories** | Each folder has a `_category_.json` with `label` and `position` |
+
+## Visual Testing
+
+Preview the site locally and check:
+
+<Steps>
+  <Step title="Start Dev Server">
+    Run `npm run dev` and open the site in your browser.
+  </Step>
+
+  <Step title="Check Navigation">
+    Verify sidebar links work, breadcrumbs are correct, and previous/next navigation follows the expected order.
+  </Step>
+
+  <Step title="Check Themes">
+    Toggle between light and dark themes. Ensure all content is readable in both modes.
+  </Step>
+
+  <Step title="Check Responsive">
+    Test on different viewport sizes. The mobile sidebar should collapse into a menu.
+  </Step>
+</Steps>
+
+## Common Issues
+
+### Frontmatter Parsing Errors
+
+```
+Error: Invalid frontmatter in docs/v1.0.0/page.mdx
+```
+
+Ensure your frontmatter uses valid YAML syntax and is enclosed by `---` delimiters.
+
+### Missing Pages
+
+If a page doesn't appear in the sidebar:
+
+1. Check the file has the `.mdx` extension (not `.md`)
+2. Verify the file is in the correct version directory
+3. Check if `draft: true` is set in frontmatter
+
+### Broken Links
+
+If internal links return 404:
+
+1. Check the path matches the file structure
+2. Include the version prefix: `/docs/v1.0.0/page-name`
+3. Use the file's slug (filename without `.mdx`), not the title
+
+<Callout type="info">
+  The dev server shows detailed error messages in the browser overlay. Check the terminal output for build-time errors.
+</Callout>

package/templates/jbrains-docs/docs/v2.0.0/advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Advanced",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "graduation-cap",
+  "tab_group": "language"
+}

package/templates/jbrains-docs/docs/v2.0.0/advanced/async.mdx

@@ -0,0 +1,95 @@
+---
+title: Async Programming
+description: Asynchronous data loading and dynamic content
+sidebar_position: 2
+---
+
+This page covers how the documentation platform handles asynchronous operations like data loading, content processing, and dynamic rendering.
+
+## How Content Loading Works
+
+Documentation pages are loaded asynchronously at build time and on navigation. The platform uses SvelteKit's server-side loading to fetch and process MDX content:
+
+```typescript
+export const load: PageServerLoad = async ({ params }) => {
+  const { version, slug } = params;
+  const doc = await getCachedDocBySlug(slug, version);
+  const allDocs = await getCachedAllDocs(version);
+  return { doc, allDocs, version, slug };
+};
+```
+
+<Callout type="info">
+  Content is cached after the first load, so subsequent navigations are nearly instant.
+</Callout>
+
+## Server-Side Data Flow
+
+The data loading follows this pipeline:
+
+<Steps>
+  <Step title="Route Matching">
+    SvelteKit matches the URL to a route pattern like `/docs/[version]/[...slug]`.
+  </Step>
+
+  <Step title="Data Loading">
+    The `+page.server.ts` load function runs, fetching the document and sidebar data.
+  </Step>
+
+  <Step title="MDX Processing">
+    The MDX content is parsed, components are resolved, and the content tree is built.
+  </Step>
+
+  <Step title="Rendering">
+    The Svelte component renders the processed content with all interactive components.
+  </Step>
+</Steps>
+
+## Configuration Loading
+
+Configuration is loaded once at application startup and cached:
+
+```typescript
+import { initConfig, getConfig } from 'specra';
+import specraConfig from '../../specra.config.json';
+
+initConfig(specraConfig);
+
+const config = getConfig(); // Cached after first call
+```
+
+## Version Resolution
+
+When a user navigates to the root URL, the system resolves the active version and redirects:
+
+```typescript
+export const load: PageServerLoad = async () => {
+  const config = getConfig();
+  const activeVersion = config.site?.activeVersion || 'v1.0.0';
+  redirect(302, `/docs/${activeVersion}/home`);
+};
+```
+
+## Adjacent Document Resolution
+
+Previous and next links are computed asynchronously from the full document list:
+
+```typescript
+const { previous, next } = getAdjacentDocs(slug, allDocs);
+```
+
+This enables linear navigation through the documentation in sidebar order.
+
+## Table of Contents Extraction
+
+The table of contents is extracted from heading elements in the content:
+
+```typescript
+const toc = extractTableOfContents(doc.content);
+```
+
+This returns a structured list of headings with their depths and anchor IDs.
+
+<Callout type="tip">
+  All these async operations are handled by the platform automatically. You only need to write MDX content — the data loading pipeline is built in.
+</Callout>

package/templates/jbrains-docs/docs/v2.0.0/advanced/generics.mdx

@@ -0,0 +1,126 @@
+---
+title: Generics
+description: Create reusable, type-safe documentation patterns
+sidebar_position: 1
+---
+
+Generics in the context of this documentation platform refer to creating reusable, parameterized content patterns that work across different contexts.
+
+## Reusable Component Patterns
+
+The built-in component library provides generic patterns that adapt to your content:
+
+### Cards
+
+Cards accept different props to serve different purposes:
+
+<CardGrid cols={3}>
+  <Card icon="zap" title="Feature Card" description="Showcase a feature" />
+  <Card icon="book" title="Guide Card" description="Link to a guide" href="/docs/v2.0.0/getting-started" />
+  <Card icon="code" title="Code Card" description="Reference a code concept" />
+</CardGrid>
+
+### Tabs
+
+Tabs provide generic containers for alternative content:
+
+<Tabs defaultValue="Pattern A">
+  <Tab label="Pattern A">
+    Use tabs for installation instructions across different package managers.
+
+    ```bash
+    npm install my-package
+    ```
+  </Tab>
+  <Tab label="Pattern B">
+    Use tabs for code examples across different languages.
+
+    ```python
+    pip install my-package
+    ```
+  </Tab>
+  <Tab label="Pattern C">
+    Use tabs for platform-specific instructions.
+
+    ```bash
+    brew install my-package
+    ```
+  </Tab>
+</Tabs>
+
+## Generic Page Templates
+
+### Landing Pages
+
+Landing pages use CardGrid to create navigation hubs:
+
+```mdx
+---
+title: Section Landing
+---
+
+<CardGrid cols={2}>
+  <Card title="Topic A" description="Description" href="/path" />
+  <Card title="Topic B" description="Description" href="/path" />
+</CardGrid>
+```
+
+### Reference Pages
+
+Reference pages use tables and code blocks:
+
+```mdx
+---
+title: API Reference
+---
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The item name |
+| `value` | `number` | The item value |
+```
+
+### Tutorial Pages
+
+Tutorial pages use Steps for structured guidance:
+
+```mdx
+---
+title: Tutorial
+---
+
+<Steps>
+  <Step title="Step 1">Instructions here</Step>
+  <Step title="Step 2">More instructions</Step>
+</Steps>
+```
+
+## Callout Types as Generic Patterns
+
+Each callout type serves a specific semantic purpose:
+
+<Callout type="info">
+  **Info** — Supplementary context that enriches understanding.
+</Callout>
+
+<Callout type="tip">
+  **Tip** — Practical advice that improves the reader's workflow.
+</Callout>
+
+<Callout type="warning">
+  **Warning** — Important caveats or potential issues to be aware of.
+</Callout>
+
+<Callout type="error">
+  **Error** — Critical mistakes to avoid or known issues.
+</Callout>
+
+## Best Practices
+
+| Pattern | When to Use |
+|---------|-------------|
+| CardGrid | Hub pages, feature showcases, navigation |
+| Tabs | Alternative content (languages, platforms, package managers) |
+| Steps | Sequential instructions, tutorials |
+| Callouts | Inline annotations (tips, warnings, notes) |
+| Tables | Reference data, comparisons, specifications |

package/templates/jbrains-docs/docs/v2.0.0/basics/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Basics",
+  "position": 3,
+  "collapsible": true,
+  "collapsed": false,
+  "icon": "book",
+  "tab_group": "language"
+}