specra-cli 0.3.0

package/templates/book-docs/public/api-specs/users-api.json

@@ -0,0 +1,264 @@
+{
+  "version": "1.0.0",
+  "title": "Users API",
+  "description": "Complete API reference for managing users in the system",
+  "baseUrl": "https://api.example.com/v1",
+  "env": {
+    "AUTH_TOKEN": "your_api_token_here"
+  },
+  "auth": {
+    "type": "bearer",
+    "description": "All requests require a valid API token in the Authorization header",
+    "tokenPrefix": "Bearer"
+  },
+  "globalHeaders": [
+    {
+      "name": "Authorization",
+      "value": "Bearer {AUTH_TOKEN}",
+      "description": "Your API authentication token"
+    },
+    {
+      "name": "Content-Type",
+      "value": "application/json"
+    }
+  ],
+  "endpoints": [
+    {
+      "title": "Get User by ID",
+      "method": "GET",
+      "path": "/users/:id",
+      "description": "Retrieve detailed information about a specific user",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "The unique identifier of the user",
+          "example": "user_123"
+        }
+      ],
+      "queryParams": [
+        {
+          "name": "fields",
+          "type": "string",
+          "description": "Comma-separated list of fields to include",
+          "example": "name,email,created_at"
+        },
+        {
+          "name": "include_metadata",
+          "type": "boolean",
+          "description": "Include additional metadata in the response",
+          "default": false
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "User retrieved successfully",
+        "example": {
+          "id": "user_123",
+          "name": "John Doe",
+          "email": "john@example.com",
+          "role": "admin",
+          "created_at": "2024-01-15T10:30:00Z",
+          "updated_at": "2024-01-20T14:22:00Z"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "User not found",
+          "example": {
+            "error": "User not found",
+            "code": "USER_NOT_FOUND",
+            "message": "No user exists with the provided ID"
+          }
+        },
+        {
+          "status": 401,
+          "description": "Unauthorized",
+          "example": {
+            "error": "Unauthorized",
+            "code": "UNAUTHORIZED",
+            "message": "Invalid or missing authentication token"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X GET \"https://api.example.com/v1/users/user_123\" \\\n  -H \"Authorization: Bearer your_api_token_here\""
+        },
+        {
+          "title": "JavaScript (fetch)",
+          "language": "javascript",
+          "code": "const response = await fetch('https://api.example.com/v1/users/user_123', {\n  headers: {\n    'Authorization': 'Bearer your_api_token_here'\n  }\n});\nconst user = await response.json();"
+        }
+      ]
+    },
+    {
+      "title": "List All Users",
+      "method": "GET",
+      "path": "/users",
+      "description": "Retrieve a paginated list of all users",
+      "queryParams": [
+        {
+          "name": "page",
+          "type": "number",
+          "description": "Page number for pagination",
+          "default": 1
+        },
+        {
+          "name": "limit",
+          "type": "number",
+          "description": "Number of users per page",
+          "default": 20
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "description": "Filter users by role",
+          "example": "admin"
+        }
+      ],
+      "successResponse": {
+        "status": 200,
+        "description": "List of users retrieved successfully",
+        "example": {
+          "data": [
+            {
+              "id": "user_123",
+              "name": "John Doe",
+              "email": "john@example.com",
+              "role": "admin"
+            },
+            {
+              "id": "user_124",
+              "name": "Jane Smith",
+              "email": "jane@example.com",
+              "role": "user"
+            }
+          ],
+          "pagination": {
+            "page": 1,
+            "limit": 20,
+            "total": 42,
+            "pages": 3
+          }
+        }
+      }
+    },
+    {
+      "title": "Create New User",
+      "method": "POST",
+      "path": "/users",
+      "description": "Create a new user account",
+      "body": {
+        "description": "User data to create",
+        "example": {
+          "name": "Alice Johnson",
+          "email": "alice@example.com",
+          "role": "user",
+          "password": "secure_password_123"
+        }
+      },
+      "successResponse": {
+        "status": 201,
+        "description": "User created successfully",
+        "example": {
+          "id": "user_125",
+          "name": "Alice Johnson",
+          "email": "alice@example.com",
+          "role": "user",
+          "created_at": "2024-01-21T09:15:00Z"
+        }
+      },
+      "errorResponses": [
+        {
+          "status": 400,
+          "description": "Validation error",
+          "example": {
+            "error": "Validation failed",
+            "code": "VALIDATION_ERROR",
+            "details": {
+              "email": "Email address already exists"
+            }
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "cURL",
+          "language": "bash",
+          "code": "curl -X POST \"https://api.example.com/v1/users\" \\\n  -H \"Authorization: Bearer your_api_token_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Alice Johnson\",\n    \"email\": \"alice@example.com\",\n    \"role\": \"user\",\n    \"password\": \"secure_password_123\"\n  }'"
+        }
+      ]
+    },
+    {
+      "title": "Update User",
+      "method": "PATCH",
+      "path": "/users/:id",
+      "description": "Update user information",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "User ID to update"
+        }
+      ],
+      "body": {
+        "description": "Fields to update (all optional)",
+        "example": {
+          "name": "John Updated",
+          "email": "john.updated@example.com",
+          "role": "moderator"
+        }
+      },
+      "successResponse": {
+        "status": 200,
+        "description": "User updated successfully",
+        "example": {
+          "id": "user_123",
+          "name": "John Updated",
+          "email": "john.updated@example.com",
+          "role": "moderator",
+          "updated_at": "2024-01-21T10:00:00Z"
+        }
+      }
+    },
+    {
+      "title": "Delete User",
+      "method": "DELETE",
+      "path": "/users/:id",
+      "description": "Permanently delete a user account",
+      "pathParams": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "User ID to delete"
+        }
+      ],
+      "successResponse": {
+        "status": 204,
+        "description": "User deleted successfully"
+      },
+      "errorResponses": [
+        {
+          "status": 404,
+          "description": "User not found"
+        },
+        {
+          "status": 403,
+          "description": "Forbidden - Cannot delete this user",
+          "example": {
+            "error": "Forbidden",
+            "code": "CANNOT_DELETE_ADMIN",
+            "message": "Cannot delete the primary admin account"
+          }
+        }
+      ]
+    }
+  ]
+}

package/templates/book-docs/specra.config.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "./node_modules/specra/config/specra.config.schema.json",
+  "site": {
+    "title": "My Docs",
+    "description": "Documentation for my project",
+    "url": "http://localhost:5173",
+    "baseUrl": "/",
+    "language": "en",
+    "organizationName": "my-org",
+    "projectName": "my-project",
+    "activeVersion": "v1.0.0"
+  },
+  "theme": {
+    "defaultMode": "dark",
+    "respectPrefersColorScheme": true
+  },
+  "navigation": {
+    "showSidebar": true,
+    "collapsibleSidebar": true,
+    "sidebarStyle": "flush",
+    "showBreadcrumbs": true,
+    "showTableOfContents": true,
+    "tocPosition": "right",
+    "tocMaxDepth": 3
+  },
+  "social": {
+    "github": "https://github.com/your-org/your-repo"
+  },
+  "search": {
+    "enabled": false
+  },
+  "banner": {
+    "enabled": true,
+    "message": "Welcome to our docs — we're actively improving them!",
+    "type": "info",
+    "dismissible": true
+  },
+  "footer": {
+    "copyright": "Copyright © 2025 My Project. All rights reserved.",
+    "branding": {
+      "showBranding": true
+    },
+    "links": [
+      {
+        "title": "Documentation",
+        "items": [
+          {
+            "label": "Introduction",
+            "href": "/docs/v1.0.0/introduction"
+          },
+          {
+            "label": "Quick Start",
+            "href": "/docs/v1.0.0/quickstart"
+          }
+        ]
+      },
+      {
+        "title": "Community",
+        "items": [
+          {
+            "label": "GitHub",
+            "href": "https://github.com/your-org/your-repo"
+          }
+        ]
+      }
+    ]
+  },
+  "features": {
+    "showLastUpdated": true,
+    "showReadingTime": true,
+    "showAuthors": false,
+    "showTags": true,
+    "versioning": true,
+    "showVersionBadge": true,
+    "i18n": false
+  }
+}

package/templates/book-docs/src/app.css

@@ -0,0 +1,86 @@
+@import "specra/styles";
+@source "./**/*.{js,ts,svelte}";
+
+@theme inline {
+    --font-sans: "Geist", "Geist Fallback", system-ui, sans-serif;
+    --font-mono: "Geist Mono", "Geist Mono Fallback", monospace;
+}
+
+/* =============================================
+   THEME OVERRIDES
+   Uncomment a :root block for light theme and/or
+   a .dark block for dark theme. Mix and match!
+   ============================================= */
+
+/* ─── Mint Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 162);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 162);
+} */
+
+/* ─── Ocean Light ─── */
+/* :root {
+  --primary: oklch(0.45 0.18 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.45 0.18 240);
+} */
+
+/* ─── Rose Light ─── */
+/* :root {
+  --primary: oklch(0.50 0.20 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.50 0.20 350);
+} */
+
+/* ─── Amber Light ─── */
+/* :root {
+  --primary: oklch(0.55 0.16 70);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.55 0.16 70);
+} */
+
+/* ─── Violet Light ─── */
+/* :root {
+  --primary: oklch(0.48 0.22 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.48 0.22 290);
+} */
+
+/* ─── Mint Dark ─── */
+/* .dark {
+  --primary: oklch(0.72 0.18 162);
+  --primary-foreground: oklch(0.10 0.03 160);
+  --ring: oklch(0.72 0.18 162);
+} */
+
+/* ─── Ocean Dark ─── */
+/* .dark {
+  --primary: oklch(0.68 0.16 240);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.68 0.16 240);
+} */
+
+/* ─── Rose Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.18 350);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.18 350);
+} */
+
+/* ─── Amber Dark ─── */
+/* .dark {
+  --primary: oklch(0.75 0.16 70);
+  --primary-foreground: oklch(0.10 0.03 70);
+  --ring: oklch(0.75 0.16 70);
+} */
+
+/* ─── Violet Dark ─── */
+/* .dark {
+  --primary: oklch(0.70 0.20 290);
+  --primary-foreground: oklch(0.98 0 0);
+  --ring: oklch(0.70 0.20 290);
+} */
+
+/* For full theme customization (backgrounds, borders, sidebar, etc.)
+   see: https://specra-docs.com/docs/v1.0.0/configuration/theming */

package/templates/book-docs/src/app.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<link rel="preconnect" href="https://fonts.googleapis.com">
+		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+		<link
+			href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@100..900&family=Geist:wght@100..900&display=swap"
+			rel="stylesheet">
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover" class="font-sans antialiased">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/templates/book-docs/src/params/product.ts

@@ -0,0 +1,7 @@
+/**
+ * SvelteKit param matcher for product slugs.
+ * Matches any string that does NOT look like a version (e.g., v1.0.0).
+ */
+export function match(param: string): boolean {
+  return !/^v\d/.test(param);
+}

package/templates/book-docs/src/routes/+layout.server.ts

@@ -0,0 +1,14 @@
+import { getConfig, initConfig } from 'specra';
+import specraConfig from '../../specra.config.json';
+import type { LayoutServerLoad } from './$types';
+import type { SpecraConfig } from 'specra';
+
+initConfig(specraConfig as unknown as Partial<SpecraConfig>);
+
+export const prerender = true;
+export const trailingSlash = 'never';
+
+export const load: LayoutServerLoad = async () => {
+  const config = getConfig();
+  return { config };
+};

package/templates/book-docs/src/routes/+layout.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import '../app.css';
+  import { LayoutProviders } from 'specra/components';
+  import type { Snippet } from 'svelte';
+  import type { LayoutData } from './$types';
+
+  let { data, children }: { data: LayoutData; children: Snippet } = $props();
+</script>
+
+<svelte:head>
+  <title>{data?.config?.site?.title || 'Documentation'}</title>
+  <meta name="description" content={data?.config?.site?.description || 'Modern documentation platform'} />
+</svelte:head>
+
+{#if data?.config}
+  <LayoutProviders config={data.config}>
+    {@render children?.()}
+  </LayoutProviders>
+{:else}
+  {@render children?.()}
+{/if}

package/templates/book-docs/src/routes/+page.server.ts

@@ -0,0 +1,9 @@
+import { redirect } from '@sveltejs/kit';
+import { getConfig } from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async () => {
+  const config = getConfig();
+  const activeVersion = config.site?.activeVersion || 'v1.0.0';
+  redirect(302, `/docs/${activeVersion}/introduction`);
+};

package/templates/book-docs/src/routes/docs/[product=product]/[version]/+layout.server.ts

@@ -0,0 +1,40 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, getProducts, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { product, version } = params;
+
+  // Verify this is a valid product — if not, fall through to 404
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {};
+  }
+
+  const i18nConfig = getI18nConfig();
+  const defaultLocale = i18nConfig?.defaultLocale || 'en';
+
+  // Block access to hidden versions — redirect to product's active version
+  const currentVersionConfig = loadVersionConfig(version, product);
+  if (currentVersionConfig?.hidden) {
+    const config = getEffectiveConfig(version, product);
+    const activeVersion = matchedProduct.config.activeVersion || config.site?.activeVersion || 'v1.0.0';
+    throw redirect(302, `/docs/${product}/${activeVersion}`);
+  }
+
+  const allDocs = await getCachedAllDocs(version, defaultLocale, product);
+  const versions = getCachedVersions(product);
+  const config = getEffectiveConfig(version, product);
+  const versionsMeta = getVersionsMeta(versions, product);
+
+  return {
+    allDocs,
+    versions,
+    versionsMeta,
+    config,
+    product,
+    products,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

package/templates/book-docs/src/routes/docs/[product=product]/[version]/+page.server.ts

@@ -0,0 +1,24 @@
+import { redirect } from '@sveltejs/kit';
+import { getCachedAllDocs, getProducts } from 'specra';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ params }) => {
+  const { product, version } = params;
+
+  // Verify product exists
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {};
+  }
+
+  const docs = await getCachedAllDocs(version, undefined, product);
+
+  if (docs.length === 0) {
+    const activeVersion = matchedProduct.config.activeVersion || 'v1.0.0';
+    redirect(302, `/docs/${product}/${activeVersion}`);
+  }
+
+  // Redirect to first doc in this product's version
+  redirect(302, `/docs/${product}/${version}/${docs[0].slug}`);
+};