specweave 0.11.0 → 0.12.1

package/plugins/specweave-docs-preview/commands/preview.md

@@ -0,0 +1,330 @@
+---
+name: specweave-docs-preview:preview
+description: Launch interactive documentation preview server with Docusaurus. Auto-generates sidebar, enables hot reload, and opens browser automatically.
+---
+
+# Documentation Preview Command
+
+Launch an interactive Docusaurus development server to preview your SpecWeave living documentation.
+
+## Your Task
+
+Execute the following workflow to launch the documentation preview server:
+
+### Step 1: Load the Preview Utilities
+
+```typescript
+import { launchPreview, isSetupNeeded, getDocsSitePath } from '../../../src/utils/docs-preview/index.js';
+```
+
+**Note:** These utilities are already implemented in the SpecWeave codebase.
+
+### Step 2: Check Configuration
+
+Read the project configuration from `.specweave/config.json`:
+
+```typescript
+import * as fs from 'fs-extra';
+import * as path from 'path';
+
+const projectRoot = process.cwd();
+const configPath = path.join(projectRoot, '.specweave', 'config.json');
+
+let config: any = {};
+if (fs.existsSync(configPath)) {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+const docsConfig = config.documentation?.preview || {
+  enabled: true,
+  autoInstall: true,
+  port: 3015,
+  openBrowser: true,
+  theme: 'default',
+  excludeFolders: ['legacy', 'node_modules']
+};
+```
+
+### Step 3: Check if Documentation Preview is Enabled
+
+```typescript
+if (!docsConfig.enabled) {
+  console.log('📚 Documentation preview is disabled in config.');
+  console.log('   To enable, set documentation.preview.enabled = true in .specweave/config.json');
+  process.exit(0);
+}
+```
+
+### Step 4: Display Setup Information
+
+```typescript
+console.log('\n📚 Launching Documentation Preview...\n');
+
+const setupNeeded = await isSetupNeeded(projectRoot);
+
+if (setupNeeded) {
+  console.log('ℹ️  First-time setup required');
+  console.log('   • Installing Docusaurus (~30 seconds)');
+  console.log('   • Generating configuration');
+  console.log('   • Creating sidebar from folder structure\n');
+} else {
+  console.log('✓ Docusaurus already installed');
+  console.log('✓ Configuration up-to-date\n');
+}
+```
+
+### Step 5: Launch the Preview Server
+
+```typescript
+try {
+  const options = {
+    port: docsConfig.port || 3015,
+    openBrowser: docsConfig.openBrowser !== false,
+    theme: docsConfig.theme || 'default',
+    excludeFolders: docsConfig.excludeFolders || ['legacy', 'node_modules']
+  };
+
+  const server = await launchPreview(projectRoot, options);
+
+  console.log('\n✅ Documentation server started successfully!\n');
+  console.log(`🌐 URL: ${server.url}`);
+  console.log('🔄 Hot reload enabled - edit markdown files to see changes instantly');
+  console.log('🗂️  Sidebar auto-generated from folder structure');
+  console.log('📊 Mermaid diagrams supported');
+  console.log('\n💡 Press Ctrl+C to stop the server\n');
+
+  // Keep the process running
+  process.on('SIGINT', () => {
+    console.log('\n\n👋 Stopping documentation server...');
+    process.exit(0);
+  });
+
+} catch (error: any) {
+  console.error('\n❌ Failed to launch documentation preview\n');
+  console.error(`Error: ${error.message}\n`);
+
+  if (error.message.includes('Node.js 18+')) {
+    console.log('💡 Solution:');
+    console.log('   • Update Node.js: nvm install 20 (or download from nodejs.org)');
+    console.log('   • Current version: node --version\n');
+  } else if (error.message.includes('port')) {
+    console.log('💡 Solution:');
+    console.log('   • Change port in .specweave/config.json');
+    console.log('   • Or stop the service using port ' + (docsConfig.port || 3015));
+    console.log('   • Check with: lsof -i :' + (docsConfig.port || 3015) + '\n');
+  } else {
+    console.log('💡 Troubleshooting:');
+    console.log('   • Check Node.js version (18+ required): node --version');
+    console.log('   • Clear npm cache: npm cache clean --force');
+    console.log('   • Check .specweave/docs/internal/ exists');
+    console.log('   • Run with DEBUG=* for detailed logs\n');
+  }
+
+  process.exit(1);
+}
+```
+
+## Important Notes
+
+### Configuration
+The command uses settings from `.specweave/config.json`:
+
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "autoInstall": true,
+      "port": 3015,
+      "openBrowser": true,
+      "theme": "default",
+      "excludeFolders": ["legacy", "node_modules"]
+    }
+  }
+}
+```
+
+### First-Time Setup
+On first run, the command will:
+1. Check Node.js version (requires 18+)
+2. Install Docusaurus packages (~30 seconds)
+3. Generate `docusaurus.config.js`
+4. Create sidebar from folder structure
+5. Start development server
+6. Open browser automatically
+
+### Subsequent Runs
+On subsequent runs, the command will:
+1. Check if Docusaurus is installed (instant)
+2. Regenerate sidebar (in case docs changed)
+3. Start server (~2 seconds)
+4. Open browser
+
+### Directory Structure
+```
+.specweave/
+├── docs/
+│   └── internal/              ← Source documentation
+│       ├── strategy/
+│       ├── specs/
+│       ├── architecture/
+│       ├── delivery/
+│       ├── operations/
+│       └── governance/
+└── docs-site-internal/        ← Docusaurus installation (generated)
+    ├── docs/                  ← Symlinked to internal/
+    ├── src/
+    ├── docusaurus.config.js
+    ├── sidebars.js
+    └── package.json
+```
+
+### What Gets Auto-Generated
+1. **Sidebar** (`sidebars.js`):
+   - Recursively scans `.specweave/docs/internal/`
+   - Creates categories from folders
+   - Sorts by priority (strategy first, governance last)
+   - Formats labels (kebab-case → Title Case)
+
+2. **Configuration** (`docusaurus.config.js`):
+   - Site title from project name
+   - Theme settings from config
+   - Mermaid diagram support
+   - Hot reload enabled
+
+3. **Landing Page** (`src/pages/index.js`):
+   - Welcome message
+   - Quick navigation links
+   - Project information
+
+### Hot Reload
+Changes to markdown files in `.specweave/docs/internal/` are detected automatically:
+- Edit file → Save → Browser refreshes instantly
+- No need to restart server
+- Works for all markdown files
+
+### Stopping the Server
+- Press `Ctrl+C` in terminal
+- Or close the terminal window
+- Or kill the process: `pkill -f docusaurus`
+
+## Expected Output
+
+**First Run:**
+```
+📚 Launching Documentation Preview...
+
+ℹ️  First-time setup required
+   • Installing Docusaurus (~30 seconds)
+   • Generating configuration
+   • Creating sidebar from folder structure
+
+📦 Installing Docusaurus packages...
+[============================>] 100%
+
+✓ Packages installed successfully
+✓ Configuration generated
+✓ Sidebar generated (42 documents, 8 categories)
+✓ Server started on http://localhost:3015
+
+✅ Documentation server started successfully!
+
+🌐 URL: http://localhost:3015
+🔄 Hot reload enabled - edit markdown files to see changes instantly
+🗂️  Sidebar auto-generated from folder structure
+📊 Mermaid diagrams supported
+
+💡 Press Ctrl+C to stop the server
+```
+
+**Subsequent Runs:**
+```
+📚 Launching Documentation Preview...
+
+✓ Docusaurus already installed
+✓ Configuration up-to-date
+
+✓ Sidebar generated (42 documents, 8 categories)
+✓ Server started on http://localhost:3015
+
+✅ Documentation server started successfully!
+
+🌐 URL: http://localhost:3015
+🔄 Hot reload enabled - edit markdown files to see changes instantly
+🗂️  Sidebar auto-generated from folder structure
+📊 Mermaid diagrams supported
+
+💡 Press Ctrl+C to stop the server
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Port Already in Use:**
+```
+Error: Port 3015 is already in use
+```
+Solution:
+1. Change port in `.specweave/config.json` → `documentation.preview.port`
+2. Or stop the service: `lsof -i :3015` then `kill -9 <PID>`
+
+**Node.js Version:**
+```
+Error: Node.js 18+ required (current: v16.x.x)
+```
+Solution:
+1. Update Node.js: `nvm install 20` (or download from nodejs.org)
+2. Verify: `node --version`
+
+**Missing Documentation:**
+```
+Error: No documentation found in .specweave/docs/internal/
+```
+Solution:
+1. Check folder exists: `ls .specweave/docs/internal/`
+2. Add at least one markdown file
+3. Or run `/specweave:increment` to create documentation
+
+## Integration with SpecWeave Workflow
+
+### After Creating Increment
+```bash
+/specweave:increment "User Authentication"
+# → Creates spec.md, plan.md, tasks.md
+
+/specweave-docs-preview:preview
+# → Preview shows new spec in sidebar
+```
+
+### After Completing Increment
+```bash
+/specweave:done 0008
+# → Syncs spec.md to .specweave/docs/internal/specs/spec-0008-user-auth.md
+
+# Hot reload automatically shows the new spec!
+# No need to restart preview server
+```
+
+### Viewing Architecture Decisions
+```bash
+# Create ADR
+vim .specweave/docs/internal/architecture/adr/0001-database-choice.md
+
+# Hot reload shows it instantly
+# Navigate to Architecture → ADR → Database Choice
+```
+
+## Best Practices
+
+1. **Keep Server Running**: Start once, leave running during development
+2. **Edit in IDE**: Changes reflect instantly (hot reload)
+3. **Organize Folders**: Good folder structure = good sidebar
+4. **Use Frontmatter**: Add title, position to control order
+5. **Test Search**: Built-in search works after indexing
+
+## See Also
+
+- `/specweave-docs-preview:build` - Build static site for deployment
+- `specweave-docs` plugin - General documentation skills
+- Docusaurus docs: https://docusaurus.io

package/plugins/specweave-docs-preview/skills/docs-preview/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: docs-preview
+description: Documentation preview expert for Docusaurus integration. Launches interactive preview server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
+---
+
+# Documentation Preview Skill
+
+Expert in launching and managing Docusaurus documentation preview for SpecWeave projects.
+
+## What I Do
+
+I help you preview and build your SpecWeave living documentation with Docusaurus:
+
+### 1. Interactive Preview
+- Launch local development server (default port: 3015)
+- Auto-generate sidebar from folder structure
+- Hot reload - edit markdown, see changes instantly
+- Mermaid diagram rendering
+- Mobile-responsive UI
+- Search functionality
+
+### 2. Static Site Building
+- Build production-ready static site
+- Output to `.specweave/docs-site-internal/build/`
+- Ready for deployment to any static host
+- Optimized for performance
+
+### 3. Smart Setup
+- Lazy installation (only installs when first used)
+- Checks Node.js version (18+ required)
+- Installs Docusaurus dependencies automatically
+- Configures from `.specweave/config.json` settings
+
+## Available Commands
+
+### Preview Documentation
+```bash
+/specweave-docs-preview:preview
+```
+
+**What it does:**
+1. Checks if Docusaurus is installed (installs if needed)
+2. Generates sidebar from `.specweave/docs/internal/` structure
+3. Starts development server on port 3015 (configurable)
+4. Opens browser automatically
+5. Enables hot reload
+
+**Configuration** (`.specweave/config.json`):
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "autoInstall": false,
+      "port": 3015,
+      "openBrowser": true,
+      "theme": "default",
+      "excludeFolders": ["legacy", "node_modules"]
+    }
+  }
+}
+```
+
+**Example session:**
+```
+User: "Can I preview my documentation?"
+You: "Yes! I'll launch the Docusaurus preview server for you."
+     [Run: /specweave-docs-preview:preview]
+
+Output:
+📚 Setting up documentation preview...
+✓ Node.js version check passed (v20.0.0)
+✓ Docusaurus already installed
+✓ Sidebar generated (42 documents, 8 categories)
+✓ Server started on http://localhost:3015
+
+🌐 Documentation available at: http://localhost:3015
+🔄 Hot reload enabled - edit docs and see changes instantly
+💡 Press Ctrl+C to stop the server
+```
+
+### Build Static Site
+```bash
+/specweave-docs-preview:build
+```
+
+**What it does:**
+1. Checks if Docusaurus is installed
+2. Runs production build
+3. Outputs to `.specweave/docs-site-internal/build/`
+4. Shows build stats and output path
+
+**Example session:**
+```
+User: "Build my docs for deployment"
+You: "I'll build the static documentation site."
+     [Run: /specweave-docs-preview:build]
+
+Output:
+📦 Building static documentation site...
+✓ Build complete!
+📁 Output: /project/.specweave/docs-site-internal/build/
+
+To deploy:
+1. Copy build/ folder to your static host
+2. Or use: npx serve build/
+```
+
+## When to Use This Skill
+
+### Activate for questions like:
+- "How do I preview my documentation?"
+- "Show me my docs in a UI"
+- "Launch Docusaurus server"
+- "View my living documentation"
+- "Start docs preview"
+- "Build static docs site"
+- "Hot reload documentation"
+- "Documentation website"
+
+### Common workflows:
+
+**1. First-time preview:**
+```
+User: "I want to preview my docs"
+You: "I'll set up the documentation preview with Docusaurus.
+      This will install dependencies (takes ~30 seconds first time)."
+     [Run: /specweave-docs-preview:preview]
+```
+
+**2. Already running:**
+```
+User: "Preview my docs"
+You: "Checking if Docusaurus is running..."
+     [If running: "Documentation server already running at http://localhost:3015"]
+     [If not: Run /specweave-docs-preview:preview]
+```
+
+**3. Build for deployment:**
+```
+User: "I need to deploy my docs"
+You: "I'll build the static site for deployment."
+     [Run: /specweave-docs-preview:build]
+     "Once built, you can deploy the build/ folder to:"
+     "• Netlify, Vercel, GitHub Pages"
+     "• Any static host (Nginx, Apache, S3)"
+     "• Or test locally with: npx serve build/"
+```
+
+## Architecture
+
+### Folder Structure
+```
+.specweave/
+├── docs/
+│   └── internal/           ← Source documentation
+│       ├── strategy/
+│       ├── specs/
+│       ├── architecture/
+│       └── ...
+└── docs-site-internal/     ← Docusaurus installation
+    ├── docs/               ← Symlinked to internal/
+    ├── src/
+    ├── build/              ← Static output
+    ├── docusaurus.config.js
+    ├── sidebars.js         ← Auto-generated
+    └── package.json
+```
+
+### Sidebar Auto-Generation
+
+The sidebar is generated from your folder structure:
+
+**Input** (`.specweave/docs/internal/`):
+```
+internal/
+├── strategy/
+│   ├── prd-001.md
+│   └── okrs.md
+├── specs/
+│   ├── spec-001-auth.md
+│   └── spec-002-payments.md
+└── architecture/
+    ├── hld-system.md
+    └── adr/
+        └── 0001-database-choice.md
+```
+
+**Output** (`sidebars.js`):
+```javascript
+{
+  docs: [
+    {
+      type: 'category',
+      label: 'Strategy',
+      items: ['strategy/prd-001', 'strategy/okrs']
+    },
+    {
+      type: 'category',
+      label: 'Specs',
+      items: ['specs/spec-001-auth', 'specs/spec-002-payments']
+    },
+    {
+      type: 'category',
+      label: 'Architecture',
+      items: [
+        'architecture/hld-system',
+        {
+          type: 'category',
+          label: 'ADR',
+          items: ['architecture/adr/0001-database-choice']
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Configuration Options
+
+### Port Selection
+```json
+{
+  "documentation": {
+    "preview": {
+      "port": 3015
+    }
+  }
+}
+```
+
+**Why 3015?**
+- Port 3000 = React/Next.js/Vite dev servers (conflict!)
+- Port 3015 = Internal docs (SpecWeave default)
+- Port 3016 = Reserved for public docs (future)
+
+### Theme Selection
+```json
+{
+  "documentation": {
+    "preview": {
+      "theme": "default"
+    }
+  }
+}
+```
+
+**Available themes:**
+- `default` - SpecWeave blue theme
+- `classic` - Docusaurus default theme
+- `dark` - Dark mode theme
+
+### Exclude Folders
+```json
+{
+  "documentation": {
+    "preview": {
+      "excludeFolders": ["legacy", "node_modules", "archive"]
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Port already in use
+```
+Error: Port 3015 is already in use
+Solution: Change port in config or stop other service
+```
+
+### Node.js version
+```
+Error: Node.js 18+ required
+Solution: Update Node.js (nvm install 20)
+```
+
+### Mermaid diagrams not rendering
+```
+Issue: Diagrams show as code blocks
+Solution: Use ```mermaid code fences (built-in support)
+```
+
+### Build fails
+```
+Error: Build failed
+Check:
+1. All markdown files have valid frontmatter
+2. No broken internal links
+3. Run preview first to catch errors early
+```
+
+## Best Practices
+
+### 1. Use Preview During Development
+- Start preview server: `/specweave-docs-preview:preview`
+- Edit markdown files in `.specweave/docs/internal/`
+- See changes instantly (hot reload)
+- No need to rebuild
+
+### 2. Build Before Deployment
+- Always build before deploying
+- Test build output locally: `npx serve build/`
+- Check all pages render correctly
+- Verify search works
+
+### 3. Keep Docs Organized
+- Follow SpecWeave folder structure
+- Use meaningful file names
+- Add frontmatter to markdown files:
+  ```markdown
+  ---
+  title: User Authentication
+  sidebar_position: 1
+  ---
+  ```
+
+### 4. Optimize for Search
+- Use descriptive headings
+- Include keywords naturally
+- Add alt text to images
+- Keep URL structure clean
+
+## Example: Complete Workflow
+
+```bash
+# 1. Preview docs locally
+/specweave-docs-preview:preview
+# → Opens http://localhost:3015
+# → Edit files, see changes instantly
+
+# 2. Build for production
+/specweave-docs-preview:build
+# → Outputs to .specweave/docs-site-internal/build/
+
+# 3. Deploy (example with Netlify)
+cd .specweave/docs-site-internal
+npx netlify deploy --dir=build --prod
+```
+
+## Integration with SpecWeave
+
+### Living Documentation Sync
+Documentation preview integrates with SpecWeave's living docs:
+
+1. **After increment completion:**
+   - `spec.md` synced to `.specweave/docs/internal/specs/`
+   - Preview updates automatically (hot reload)
+
+2. **Architecture decisions:**
+   - ADRs created in `.specweave/docs/internal/architecture/adr/`
+   - Instantly visible in preview
+
+3. **Multi-project support:**
+   - Each project gets its own docs folder
+   - Preview shows all projects in sidebar
+
+## Commands Summary
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/specweave-docs-preview:preview` | Launch dev server | During development, hot reload |
+| `/specweave-docs-preview:build` | Build static site | Before deployment, production |
+
+## Technical Details
+
+### Under the Hood
+- **Framework:** Docusaurus 3.0
+- **React version:** 18+
+- **Build tool:** Webpack 5
+- **Markdown:** MDX support
+- **Diagrams:** Mermaid.js
+- **Search:** Algolia DocSearch (optional)
+
+### Performance
+- **Install time:** ~30 seconds (first time only)
+- **Build time:** ~5-10 seconds (small docs)
+- **Hot reload:** <1 second
+- **Static site:** Fully optimized, lighthouse 100
+
+## See Also
+
+- **specweave-docs** skill - General documentation workflows
+- **spec-generator** skill - Generate living docs specs
+- **sync-docs** skill - Sync docs after increments
+- **Docusaurus docs:** https://docusaurus.io