specweave 0.30.13 → 0.30.16

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

@@ -1,489 +0,0 @@
----
-name: specweave-docs-preview:build
-description: Build static documentation site for deployment. Generates production-ready HTML/CSS/JS files optimized for static hosting.
----
-
-# Documentation Build Command
-
-Build a production-ready static documentation site from your SpecWeave living documentation.
-
-## Your Task
-
-Execute the following workflow to build the static documentation site:
-
-### Step 1: Load the Build Utilities
-
-```typescript
-import { buildStaticSite, isSetupNeeded } from '../../../src/utils/docs-preview/index.js';
-import * as fs from 'fs-extra';
-import * as path from 'path';
-```
-
-### Step 2: Check Prerequisites
-
-```typescript
-const projectRoot = process.cwd();
-
-// Check if docs preview is configured
-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 || {};
-
-console.log('\n📦 Building Documentation Site...\n');
-
-// Check if Docusaurus is installed
-const setupNeeded = await isSetupNeeded(projectRoot);
-
-if (setupNeeded) {
-  console.error('❌ Docusaurus not installed\n');
-  console.log('💡 Solution:');
-  console.log('   Run: /specweave-docs-preview:preview');
-  console.log('   This will install Docusaurus first\n');
-  process.exit(1);
-}
-```
-
-### Step 3: Build the Static Site
-
-```typescript
-try {
-  console.log('ℹ️  Building production site...');
-  console.log('   • Compiling React components');
-  console.log('   • Optimizing assets');
-  console.log('   • Generating static HTML\n');
-
-  await buildStaticSite(projectRoot);
-
-  const buildPath = path.join(projectRoot, '.specweave', 'docs-site-internal', 'build');
-  const buildStats = await getBuildStats(buildPath);
-
-  console.log('\n✅ Build Complete!\n');
-  console.log('📊 Build Statistics:');
-  console.log(`   • Pages: ${buildStats.pages} HTML files`);
-  console.log(`   • Size: ${buildStats.totalSize}`);
-  console.log(`   • Location: ${buildPath}\n`);
-
-  console.log('🚀 Deployment Options:\n');
-  console.log('1️⃣  Netlify:');
-  console.log('   cd .specweave/docs-site-internal');
-  console.log('   npx netlify deploy --dir=build --prod\n');
-
-  console.log('2️⃣  Vercel:');
-  console.log('   cd .specweave/docs-site-internal');
-  console.log('   npx vercel --prod\n');
-
-  console.log('3️⃣  GitHub Pages:');
-  console.log('   cp -r build/* docs/');
-  console.log('   git add docs/ && git commit -m "docs: update"');
-  console.log('   git push\n');
-
-  console.log('4️⃣  Static Server (local test):');
-  console.log('   npx serve build/\n');
-
-  console.log('5️⃣  Your own server:');
-  console.log('   scp -r build/* user@server:/var/www/docs/\n');
-
-} catch (error: any) {
-  console.error('\n❌ Build Failed\n');
-  console.error(`Error: ${error.message}\n`);
-
-  console.log('💡 Troubleshooting:');
-  console.log('   • Check all markdown files have valid frontmatter');
-  console.log('   • Ensure no broken internal links');
-  console.log('   • Run preview first to catch errors: /specweave-docs-preview:preview');
-  console.log('   • Check build logs above for specific errors\n');
-
-  process.exit(1);
-}
-```
-
-### Step 4: Helper Function - Get Build Statistics
-
-```typescript
-async function getBuildStats(buildPath: string): Promise<{
-  pages: number;
-  totalSize: string;
-}> {
-  let pages = 0;
-  let totalBytes = 0;
-
-  async function walk(dir: string) {
-    const files = await fs.readdir(dir);
-    for (const file of files) {
-      const filePath = path.join(dir, file);
-      const stats = await fs.stat(filePath);
-      if (stats.isDirectory()) {
-        await walk(filePath);
-      } else {
-        totalBytes += stats.size;
-        if (file.endsWith('.html')) {
-          pages++;
-        }
-      }
-    }
-  }
-
-  await walk(buildPath);
-
-  const totalMB = (totalBytes / 1024 / 1024).toFixed(2);
-  return {
-    pages,
-    totalSize: `${totalMB} MB`
-  };
-}
-```
-
-## What Gets Built
-
-### Output Directory Structure
-```
-.specweave/docs-site-internal/build/
-├── index.html                    ← Landing page
-├── docs/
-│   ├── strategy/
-│   │   ├── prd-001/
-│   │   │   └── index.html
-│   │   └── okrs/
-│   │       └── index.html
-│   ├── specs/
-│   │   ├── spec-001-auth/
-│   │   │   └── index.html
-│   │   └── spec-002-payments/
-│   │       └── index.html
-│   └── architecture/
-│       ├── hld-system/
-│       │   └── index.html
-│       └── adr/
-│           └── 0001-database-choice/
-│               └── index.html
-├── assets/
-│   ├── css/
-│   │   └── styles.[hash].css    ← Optimized CSS
-│   ├── js/
-│   │   └── runtime.[hash].js    ← React runtime
-│   └── images/                  ← Optimized images
-└── sitemap.xml                  ← Search engine sitemap
-```
-
-### Build Optimizations
-1. **Code Splitting**: React chunks loaded on demand
-2. **Asset Optimization**: CSS/JS minified and compressed
-3. **Image Optimization**: Auto-resized and compressed
-4. **Static HTML**: Pre-rendered pages for fast loading
-5. **Search Index**: Pre-generated search index
-6. **Sitemap**: Auto-generated for SEO
-
-## Deployment Examples
-
-### Netlify (Recommended)
-
-**Option 1: CLI**
-```bash
-cd .specweave/docs-site-internal
-npx netlify deploy --dir=build --prod
-```
-
-**Option 2: Drag & Drop**
-1. Go to https://app.netlify.com/drop
-2. Drag `.specweave/docs-site-internal/build/` folder
-3. Done! Get instant URL
-
-**Option 3: Git Integration**
-1. Create `netlify.toml`:
-   ```toml
-   [build]
-     base = ".specweave/docs-site-internal"
-     publish = "build"
-     command = "npm run build"
-   ```
-2. Connect GitHub repo
-3. Auto-deploy on push
-
-### Vercel
-
-```bash
-cd .specweave/docs-site-internal
-npx vercel --prod
-```
-
-### GitHub Pages
-
-**Option 1: docs/ folder**
-```bash
-# 1. Copy build to docs/
-cp -r .specweave/docs-site-internal/build/* docs/
-
-# 2. Enable GitHub Pages
-# Go to Settings → Pages → Source: main branch /docs folder
-
-# 3. Push
-git add docs/
-git commit -m "docs: update documentation site"
-git push
-```
-
-**Option 2: gh-pages branch**
-```bash
-# 1. Install gh-pages
-npm install -g gh-pages
-
-# 2. Deploy
-gh-pages -d .specweave/docs-site-internal/build
-```
-
-### AWS S3 + CloudFront
-
-```bash
-# 1. Sync to S3
-aws s3 sync .specweave/docs-site-internal/build/ s3://your-bucket/ \
-  --delete \
-  --cache-control "max-age=31536000,public"
-
-# 2. Invalidate CloudFront
-aws cloudfront create-invalidation \
-  --distribution-id YOUR_DIST_ID \
-  --paths "/*"
-```
-
-### Docker + Nginx
-
-**Dockerfile:**
-```dockerfile
-FROM nginx:alpine
-COPY .specweave/docs-site-internal/build/ /usr/share/nginx/html/
-EXPOSE 80
-```
-
-**Build and run:**
-```bash
-docker build -t docs .
-docker run -p 80:80 docs
-```
-
-### Your Own Server
-
-**Nginx config:**
-```nginx
-server {
-    listen 80;
-    server_name docs.example.com;
-    root /var/www/docs;
-    index index.html;
-
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-}
-```
-
-**Deploy:**
-```bash
-scp -r .specweave/docs-site-internal/build/* user@server:/var/www/docs/
-```
-
-## Testing Before Deployment
-
-### Local Testing with Serve
-
-```bash
-# 1. Install serve
-npm install -g serve
-
-# 2. Serve build folder
-cd .specweave/docs-site-internal
-serve build/
-
-# 3. Open browser
-# Visit: http://localhost:3000
-```
-
-### Check Lighthouse Scores
-
-```bash
-# 1. Install lighthouse
-npm install -g lighthouse
-
-# 2. Run audit
-lighthouse http://localhost:3000 \
-  --view \
-  --output html
-
-# Expected scores:
-# Performance: 100
-# Accessibility: 100
-# Best Practices: 100
-# SEO: 100
-```
-
-## Expected Output
-
-**Successful Build:**
-```
-📦 Building Documentation Site...
-
-ℹ️  Building production site...
-   • Compiling React components
-   • Optimizing assets
-   • Generating static HTML
-
-[==================================] 100%
-
-✅ Build Complete!
-
-📊 Build Statistics:
-   • Pages: 42 HTML files
-   • Size: 3.2 MB
-   • Location: /project/.specweave/docs-site-internal/build/
-
-🚀 Deployment Options:
-
-1️⃣  Netlify:
-   cd .specweave/docs-site-internal
-   npx netlify deploy --dir=build --prod
-
-2️⃣  Vercel:
-   cd .specweave/docs-site-internal
-   npx vercel --prod
-
-3️⃣  GitHub Pages:
-   cp -r build/* docs/
-   git add docs/ && git commit -m "docs: update"
-   git push
-
-4️⃣  Static Server (local test):
-   npx serve build/
-
-5️⃣  Your own server:
-   scp -r build/* user@server:/var/www/docs/
-```
-
-## Common Build Errors
-
-### Invalid Frontmatter
-```
-Error: Invalid frontmatter in file: spec-001.md
-```
-**Fix:**
-```markdown
----
-title: User Authentication
-sidebar_position: 1
----
-
-Content here...
-```
-
-### Broken Links
-```
-Error: Broken link in file: architecture/hld.md
-Link: ../specs/missing-file.md
-```
-**Fix:** Update or remove broken links
-
-### Missing Dependencies
-```
-Error: Module not found: 'react'
-```
-**Fix:**
-```bash
-cd .specweave/docs-site-internal
-npm install
-```
-
-## Build vs Preview
-
-| Aspect | Preview (`/specweave-docs-preview:preview`) | Build (`/specweave-docs-preview:build`) |
-|--------|---------------------------------------------|----------------------------------------|
-| **Purpose** | Development, hot reload | Production deployment |
-| **Speed** | Instant start | 5-10 seconds build |
-| **Output** | Dev server | Static files |
-| **Hot Reload** | ✅ Yes | ❌ No |
-| **Optimization** | ❌ No | ✅ Yes (minified, compressed) |
-| **Search** | ✅ Works | ✅ Pre-generated index |
-| **Use When** | Editing docs | Deploying to server |
-
-## Best Practices
-
-### 1. Build Before Every Deployment
-Always build fresh before deploying:
-```bash
-/specweave-docs-preview:build
-# Then deploy
-```
-
-### 2. Test Build Locally
-```bash
-/specweave-docs-preview:build
-cd .specweave/docs-site-internal
-npx serve build/
-# Visit http://localhost:3000 and test
-```
-
-### 3. Check All Pages
-- Click through every page
-- Test search functionality
-- Verify all links work
-- Check mobile responsiveness
-
-### 4. Optimize Images
-Before building, optimize images:
-```bash
-# Install sharp-cli
-npm install -g sharp-cli
-
-# Optimize images
-sharp -i docs/images/*.png -o docs/images/optimized/ -q 80
-```
-
-### 5. Update Sitemap
-The sitemap is auto-generated, but verify it:
-```bash
-cat .specweave/docs-site-internal/build/sitemap.xml
-```
-
-## Integration with CI/CD
-
-### GitHub Actions
-
-**.github/workflows/docs.yml:**
-```yaml
-name: Deploy Docs
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - '.specweave/docs/**'
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 20
-
-      - name: Install SpecWeave
-        run: npm install -g specweave
-
-      - name: Build Docs
-        run: specweave docs build
-
-      - name: Deploy to Netlify
-        run: |
-          cd .specweave/docs-site-internal
-          npx netlify deploy --dir=build --prod
-        env:
-          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_TOKEN }}
-```
-
-## See Also
-
-- `/specweave-docs-preview:preview` - Preview docs locally with hot reload
-- `specweave-docs` plugin - Documentation workflow skills
-- Docusaurus docs: https://docusaurus.io/docs/deployment