specweave 0.30.12 → 0.30.14

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

@@ -1,355 +0,0 @@
----
-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.
-
-## 🎨 Beautiful Docusaurus Experience
-
-**This command ALWAYS uses Docusaurus** - not basic file serving! You get:
-- ✅ Auto-generated navigation from folder structure
-- ✅ Search functionality (instant local search)
-- ✅ Beautiful theming (light/dark mode)
-- ✅ Mermaid diagram rendering
-- ✅ Hot reload (edit markdown, see changes instantly)
-- ✅ Professional typography and layout
-- ✅ Mobile responsive design
-
-**Never settle for basic markdown rendering when you can have this!**
-
-## 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: 3016,
-  openBrowser: true,
-  theme: 'default',
-  excludeFolders: ['legacy', 'node_modules']
-};
-```
-
-### Step 3: Check if Documentation Preview is Enabled (Auto-Enable if Needed)
-
-```typescript
-if (!docsConfig.enabled) {
-  console.log('📚 Documentation preview is currently disabled.');
-  console.log('   Enabling it now for beautiful Docusaurus experience...\n');
-
-  // Auto-enable the feature
-  config.documentation = config.documentation || {};
-  config.documentation.preview = {
-    ...docsConfig,
-    enabled: true,
-    autoInstall: true
-  };
-
-  // Save updated config
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-
-  console.log('✅ Documentation preview enabled!\n');
-}
-```
-
-### 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 || 3016,
-    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 || 3016));
-    console.log('   • Check with: lsof -i :' + (docsConfig.port || 3016) + '\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": 3016,
-      "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:3016
-
-✅ Documentation server started successfully!
-
-🌐 URL: http://localhost:3016
-🔄 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:3016
-
-✅ Documentation server started successfully!
-
-🌐 URL: http://localhost:3016
-🔄 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 3016 is already in use
-```
-Solution:
-1. Change port in `.specweave/config.json` → `documentation.preview.port`
-2. Or stop the service: `lsof -i :3016` 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