specweave 0.17.6 → 0.17.8

package/plugins/specweave-github/lib/github-spec-content-sync.ts

@@ -25,12 +25,54 @@ import fs from 'fs/promises';
 
 export interface GitHubContentSyncOptions {
   specPath: string;
-  owner: string;
-  repo: string;
+  owner?: string; // Optional: will be auto-detected from project config
+  repo?: string; // Optional: will be auto-detected from project config
   dryRun?: boolean;
   verbose?: boolean;
 }
 
+/**
+ * Get GitHub owner/repo from project config
+ */
+async function getGitHubRepoForProject(
+  project: string,
+  specPath: string
+): Promise<{ owner: string; repo: string } | null> {
+  try {
+    // Find project root
+    let currentDir = path.dirname(specPath);
+    let configPath = path.join(currentDir, '.specweave', 'config.json');
+
+    // Search upward for .specweave/config.json
+    while (!await fs.access(configPath).then(() => true).catch(() => false)) {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        return null; // Reached root
+      }
+      currentDir = parentDir;
+      configPath = path.join(currentDir, '.specweave', 'config.json');
+    }
+
+    // Read config
+    const configContent = await fs.readFile(configPath, 'utf-8');
+    const config = JSON.parse(configContent);
+
+    // Get project config
+    const projectConfig = config.specs?.projects?.[project];
+
+    if (!projectConfig?.github) {
+      return null;
+    }
+
+    return {
+      owner: projectConfig.github.owner,
+      repo: projectConfig.github.repo
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Sync spec content to GitHub issue
  * Creates issue if it doesn't exist, updates if it does
@@ -38,7 +80,7 @@ export interface GitHubContentSyncOptions {
 export async function syncSpecContentToGitHub(
   options: GitHubContentSyncOptions
 ): Promise<ContentSyncResult> {
-  const { specPath, owner, repo, dryRun = false, verbose = false } = options;
+  let { specPath, owner, repo, dryRun = false, verbose = false } = options;
 
   try {
     // 1. Parse spec content
@@ -52,12 +94,33 @@ export async function syncSpecContentToGitHub(
     }
 
     if (verbose) {
-      console.log(`📄 Parsed spec: ${spec.id}`);
+      console.log(`📄 Parsed spec: ${spec.identifier.compact}`);
+      console.log(`   Project: ${spec.project}`);
       console.log(`   Title: ${spec.title}`);
       console.log(`   User Stories: ${spec.userStories.length}`);
     }
 
-    // 2. Check if issue already exists
+    // 2. Auto-detect owner/repo from project config if not provided
+    if (!owner || !repo) {
+      const repoConfig = await getGitHubRepoForProject(spec.project, specPath);
+
+      if (!repoConfig) {
+        return {
+          success: false,
+          action: 'error',
+          error: `No GitHub repository configured for project "${spec.project}". Add specs.projects.${spec.project}.github in config.json`,
+        };
+      }
+
+      owner = repoConfig.owner;
+      repo = repoConfig.repo;
+
+      if (verbose) {
+        console.log(`   Auto-detected repo: ${owner}/${repo}`);
+      }
+    }
+
+    // 3. Check if issue already exists
     const existingIssueNumber = await hasExternalLink(specPath, 'github');
 
     const client = GitHubClientV2.fromRepo(owner, repo);
@@ -89,8 +152,9 @@ async function createGitHubIssue(
   const { specPath, dryRun, verbose } = options;
 
   try {
-    // Build issue title and body
-    const title = `[${spec.id.toUpperCase()}] ${spec.title}`;
+    // Build issue title and body using compact format
+    // Examples: [BE-JIRA-AUTH-123] User Authentication, [FE-user-login-ui] Login UI
+    const title = `[${spec.identifier.compact}] ${spec.title}`;
     const body = buildExternalDescription(spec);
 
     if (verbose) {
@@ -112,8 +176,13 @@ async function createGitHubIssue(
       };
     }
 
-    // Create issue
-    const labels = ['specweave', 'spec', spec.metadata.priority || 'P2'].filter(Boolean);
+    // Create issue with project-specific labels
+    const labels = [
+      'specweave',
+      'spec',
+      spec.project, // backend, frontend, mobile, etc.
+      spec.metadata.priority || 'P2'
+    ].filter(Boolean);
     const issue = await client.createEpicIssue(title, body, undefined, labels);
 
     if (verbose) {
@@ -164,8 +233,11 @@ async function updateGitHubIssue(
     }
 
     // Detect changes
+    // Strip any ID prefix from title (flexible format: [BE-JIRA-123], [FE-login-ui], etc.)
+    const cleanTitle = issue.title.replace(/^\[[A-Z]{2,4}-[A-Z0-9-]+\]\s*/, '');
+
     const changes = detectContentChanges(spec, {
-      title: issue.title.replace(/^\[SPEC-\d+\]\s*/, ''),
+      title: cleanTitle,
       description: issue.body || '',
       userStoryCount: countUserStoriesInBody(issue.body || ''),
     });
@@ -190,8 +262,8 @@ async function updateGitHubIssue(
       }
     }
 
-    // Build updated content
-    const newTitle = `[${spec.id.toUpperCase()}] ${spec.title}`;
+    // Build updated content using compact format
+    const newTitle = `[${spec.identifier.compact}] ${spec.title}`;
     const newBody = buildExternalDescription(spec);
 
     if (dryRun) {

package/plugins/specweave-jira/.claude-plugin/plugin.json

@@ -17,5 +17,5 @@
     "specweave",
     "project-management"
   ],
-  "hooks": "hooks/hooks.json"
+  "hooks": "./hooks/hooks.json"
 }

package/plugins/specweave-mobile/.claude-plugin/plugin.json

@@ -17,9 +17,6 @@
     "metro",
     "mobile-development"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/anton-abyzov/specweave"
-  },
+  "repository": "https://github.com/anton-abyzov/specweave",
   "license": "MIT"
 }

package/plugins/specweave-release/.claude-plugin/plugin.json

@@ -24,19 +24,7 @@
     "independent-release",
     "brownfield-release"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/anton-abyzov/specweave",
-    "directory": "plugins/specweave-release"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "specweave": ">=0.14.0"
-  },
-  "skills": "skills",
-  "agents": "agents",
-  "commands": "commands",
-  "hooks": "hooks/hooks.json"
+  "repository": "https://github.com/anton-abyzov/specweave",
+  "license": "MIT",
+  "hooks": "./hooks/hooks.json"
 }

package/src/templates/AGENTS.md.template

@@ -985,6 +985,303 @@ cat plugins/specweave-github/commands/github-sync.md
 
 ---
 
+## 📖 Documentation Preview with Docusaurus (Port 3016)
+
+**IMPORTANT**: SpecWeave supports beautiful documentation preview using Docusaurus. This is NOT just for Claude Code - it works for ALL tools!
+
+### Overview
+
+The `/specweave-docs-preview:preview` command launches an interactive Docusaurus development server to preview your living documentation at **http://localhost:3016** (NOT port 3000!).
+
+**Why Port 3016?**
+- Port 3000 is commonly used by other development servers (React, Next.js, etc.)
+- Port 3016 avoids conflicts with client projects
+- This is the default for ALL SpecWeave documentation preview
+
+### Quick Start
+
+**For Claude Code** (slash command):
+```bash
+/specweave-docs-preview:preview
+```
+
+**For Other Tools** (manual execution):
+```bash
+# 1. Read the command file
+cat plugins/specweave-docs-preview/commands/preview.md
+
+# 2. Execute the workflow manually (follow the instructions in preview.md)
+# The command will:
+# - Install Docusaurus (~30 seconds first time)
+# - Generate configuration
+# - Create sidebar from folder structure
+# - Start server on http://localhost:3016
+# - Open browser automatically
+
+# 3. Access the documentation
+# Open browser to: http://localhost:3016
+```
+
+### Common MDX Compilation Errors (MUST READ!)
+
+**Problem**: Docusaurus uses MDX (Markdown + JSX) which has stricter parsing rules than regular Markdown. Files with certain patterns may cause compilation errors like:
+
+```
+Error: MDX compilation failed for file ".../adr-001-signalr-vs-websockets.md"
+Cause: Unexpected character `1` (U+0031) before name
+```
+
+**Solutions** (in order of preference):
+
+#### Solution 1: Use Frontmatter for Problematic Files
+
+Add YAML frontmatter to files with numeric prefixes or special characters:
+
+```markdown
+---
+id: adr-001-signalr-vs-websockets
+title: ADR 001: SignalR vs WebSockets
+sidebar_label: SignalR vs WebSockets
+---
+
+# ADR 001: SignalR vs WebSockets
+
+[Rest of content...]
+```
+
+#### Solution 2: Exclude Problematic Files
+
+If certain files can't be fixed, exclude them from the build:
+
+**Edit `.specweave/config.json`:**
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "port": 3016,
+      "excludeFolders": ["legacy", "node_modules", "problematic-folder"]
+    }
+  }
+}
+```
+
+#### Solution 3: Use MDX1 Compatibility Mode
+
+The config generator already adds MDX1 compatibility mode to handle most common issues:
+
+```javascript
+// This is already in the generated docusaurus.config.js
+markdown: {
+  mermaid: true,
+  format: 'mdx',
+  mdx1Compat: {
+    comments: true,
+    admonitions: true,
+    headingIds: true,
+  },
+}
+```
+
+#### Solution 4: Fix Special Characters in Content
+
+MDX interprets `<`, `>`, `{`, `}` as JSX. Escape them in your markdown:
+
+**Bad** (causes MDX errors):
+```markdown
+Use <Component> to render the UI
+Configure {apiKey} in the settings
+```
+
+**Good** (works):
+```markdown
+Use `<Component>` to render the UI
+Configure `{apiKey}` in the settings
+```
+
+Or use code blocks:
+```markdown
+```
+Use <Component> to render the UI
+```
+
+### Configuration Reference
+
+**Default Configuration** (`.specweave/config.json`):
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "autoInstall": true,
+      "port": 3016,
+      "openBrowser": true,
+      "theme": "default",
+      "excludeFolders": ["legacy", "node_modules"]
+    }
+  }
+}
+```
+
+**Configuration Options**:
+- `enabled`: Enable/disable docs preview (default: true)
+- `autoInstall`: Auto-install Docusaurus on first run (default: true)
+- `port`: Port for dev server (default: 3016, NEVER use 3000!)
+- `openBrowser`: Auto-open browser (default: true)
+- `theme`: Theme variant ("default", "classic", "dark")
+- `excludeFolders`: Folders to exclude from build (array)
+
+### Features
+
+**What 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
+
+**Hot Reload**:
+- Edit any file in `.specweave/docs/internal/`
+- Save the file
+- Browser refreshes automatically
+- No need to restart server!
+
+### Troubleshooting
+
+**Port Already in Use:**
+```bash
+# Error: Port 3016 is already in use
+# Solution 1: Change port in config
+vim .specweave/config.json
+# Change "port": 3016 to "port": 3017
+
+# Solution 2: Stop the service
+lsof -i :3016  # Find PID
+kill -9 <PID>  # Kill the process
+```
+
+**Build Fails with MDX Errors:**
+```bash
+# Check which files are causing errors
+# Look for files with:
+# - Numeric prefixes (adr-001-, spec-123-)
+# - Special characters in content (<, >, {, })
+# - JSX-like syntax
+
+# Fix using Solution 1-4 above (add frontmatter, exclude files, etc.)
+```
+
+**Node.js Version:**
+```bash
+# Error: Node.js 18+ required
+# Solution: Update Node.js
+nvm install 20  # Using nvm
+# Or download from nodejs.org
+node --version  # Verify
+```
+
+### Best Practices
+
+**1. Always Use Port 3016** (NOT 3000):
+```json
+// ✅ CORRECT
+{"documentation": {"preview": {"port": 3016}}}
+
+// ❌ WRONG
+{"documentation": {"preview": {"port": 3000}}}
+```
+
+**2. Add Frontmatter to ADRs/Specs:**
+```markdown
+---
+id: unique-identifier
+title: Human-Readable Title
+sidebar_label: Short Label
+---
+
+# Your content here
+```
+
+**3. Escape Special Characters:**
+```markdown
+Use backticks: `<Component>`, `{variable}`
+Or code blocks for multiline
+```
+
+**4. Test Before Committing:**
+```bash
+# Start preview locally
+/specweave-docs-preview:preview
+
+# Check for errors in console
+# Fix any MDX compilation errors
+# Then commit
+```
+
+### 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/
+
+# Hot reload automatically shows the new spec!
+# No need to restart preview server
+```
+
+### For Non-Claude Tools: Manual Execution
+
+**Step-by-Step Workflow:**
+
+```bash
+# 1. Load the command
+cat plugins/specweave-docs-preview/commands/preview.md
+
+# 2. Create or verify config
+vim .specweave/config.json
+# Ensure "documentation.preview.enabled" is true
+# Ensure "documentation.preview.port" is 3016
+
+# 3. Run the preview (follow instructions from preview.md)
+# The command will guide you through:
+# - Installing Docusaurus (first time only)
+# - Generating config and sidebar
+# - Starting server on port 3016
+# - Opening browser
+
+# 4. Access documentation
+# Open: http://localhost:3016
+
+# 5. Edit docs and see changes live
+# Edit any file in .specweave/docs/internal/
+# Browser refreshes automatically!
+
+# 6. Stop server when done
+# Press Ctrl+C in terminal
+```
+
+### Summary
+
+- 🌐 **Default Port**: 3016 (NOT 3000!)
+- 📁 **Source**: `.specweave/docs/internal/`
+- 🔧 **Config**: `.specweave/config.json`
+- 🔄 **Hot Reload**: Automatic
+- ⚠️ **MDX Errors**: Add frontmatter or escape special chars
+- ✅ **Works for ALL tools** (Claude Code, Cursor, Copilot, etc.)
+
+---
+
 ## Build & Test Commands
 
 ```bash

package/dist/locales/de/cli.json

@@ -1,108 +0,0 @@
-{
-  "init": {
-    "welcome": "🚀 SpecWeave Initialization",
-    "projectName": "Project name:",
-    "projectNamePrompt": "Project name (for templates):",
-    "projectNameDefault": "my-saas",
-    "detectingTool": "Detecting AI tool...",
-    "foundClaude": "✅ Found Claude Code",
-    "foundCursor": "✅ Found Cursor",
-    "foundCopilot": "✅ Found GitHub Copilot",
-    "noToolDetected": "No AI tool detected, using Generic adapter",
-    "complete": "✨ Initialization complete!",
-    "claudeNativeComplete": "✨ Claude Code native installation complete!",
-    "claudeNativeBenefits": "✅ Native skills, agents, hooks work out of the box",
-    "projectSuccess": "SpecWeave project created successfully!",
-    "readyToBuild": "🚀 Ready to build with SpecWeave!",
-    "errors": {
-      "invalidName": "Project name must contain only lowercase letters, numbers, and hyphens",
-      "alreadyExists": ".specweave directory already exists",
-      "cancelled": "❌ Initialization cancelled",
-      "invalidLanguage": "❌ Invalid language: {{language}}",
-      "supportedLanguages": "Supported languages: {{languages}}",
-      "nestedNotSupported": "❌ Nested .specweave/ folders are NOT supported!",
-      "parentFound": "Found parent .specweave/ at:",
-      "projectCreationFailed": "Failed to create project",
-      "commandsCopyFailed": "❌ Commands copy failed: {{error}}",
-      "agentsCopyFailed": "❌ Agents copy failed: {{error}}",
-      "skillsCopyFailed": "❌ Skills copy failed: {{error}}",
-      "hooksCopyFailed": "❌ Hooks copy failed: {{error}}"
-    },
-    "warnings": {
-      "invalidDirName": "⚠️  Current directory name '{{dirName}}' contains invalid characters.",
-      "directoryNotEmpty": "⚠️  Current directory contains {{count}} file{{plural}}.",
-      "skillsIndexWarning": "⚠️  Warning: Could not generate skills index: {{error}}",
-      "skillsIndexNote": "Skills will still work, but manual indexing may be needed."
-    },
-    "prompts": {
-      "confirmInitInCurrent": "Initialize SpecWeave in current directory?",
-      "overwriteSpecweave": ".specweave directory already exists. Overwrite?",
-      "overwriteDirectory": "Directory {{projectName}} already exists. Overwrite?",
-      "enablePlugins": "Enable suggested plugins now?"
-    },
-    "info": {
-      "nestedEnforcement": "SpecWeave enforces a single source of truth:",
-      "nestedBullet1": "• Use the parent folder for all increments",
-      "nestedBullet2": "• Increments can span multiple subdirectories",
-      "nestedBullet3": "• See CLAUDE.md section \"Root-Level .specweave/ Folder\"",
-      "nestedToFix": "To fix:",
-      "suggestedPlugins": "💡 Suggested Plugins:",
-      "copiedFiles": "✓ Copied {{count}} command files",
-      "copiedAgents": "✓ Copied {{count}} agent directories",
-      "copiedSkills": "✓ Copied {{count}} skill directories",
-      "copiedHooks": "✓ Copied {{count}} hook files"
-    },
-    "progress": {
-      "creatingProject": "Creating SpecWeave project...",
-      "detected": "Detected {{tool}}...",
-      "usingTool": "Using {{tool}}...",
-      "directoryCreated": "Directory structure created...",
-      "templatesCopied": "Base templates copied...",
-      "installingComponents": "Installing Claude Code components...",
-      "commandsInstalled": "Slash commands installed...",
-      "agentsInstalled": "Agents installed...",
-      "skillsInstalled": "Skills installed...",
-      "hooksInstalled": "Hooks installed...",
-      "generatingIndex": "Generating skills index...",
-      "indexGenerated": "Skills index generated...",
-      "installingAdapter": "Installing {{tool}} adapter...",
-      "projectSuccess": "SpecWeave project created successfully!",
-      "detectingPlugins": "Detecting plugins...",
-      "detectedPlugins": "Detected {{count}} suggested plugins",
-      "enablingPlugins": "Enabling plugins...",
-      "enabledPlugin": "Enabled {{plugin}}",
-      "pluginsEnabled": "Plugins enabled"
-    },
-    "nextSteps": {
-      "header": "🎯 Next steps:",
-      "cd": "cd {{projectName}}",
-      "footer": "🚀 Ready to build with SpecWeave!",
-      "docsLink": "Documentation: https://spec-weave.com",
-      "githubLink": "GitHub: https://github.com/anton-abyzov/specweave"
-    }
-  },
-  "increment": {
-    "creating": "📝 Creating increment: {name}",
-    "created": "✅ Increment {id} created successfully!",
-    "nextStepDo": "Next: Run /specweave.do to start implementation",
-    "errors": {
-      "incompleteFound": "Cannot create new increment! Previous increments incomplete"
-    }
-  },
-  "progress": {
-    "currentIncrement": "Current Increment: {id}",
-    "status": "Status: {status}",
-    "completion": "Completion: {percent}%"
-  },
-  "translate": {
-    "translating": "🌐 Translating content to {language}...",
-    "complete": "✅ Translation complete!"
-  },
-  "version": {
-    "current": "SpecWeave version: {version}"
-  },
-  "errors": {
-    "fileNotFound": "❌ File not found: {path}",
-    "invalidConfig": "❌ Invalid configuration: {error}"
-  }
-}