specweave 0.23.5 → 0.23.8

package/CLAUDE.md

@@ -1129,6 +1129,131 @@ bash scripts/validate-plugin-directories.sh --fix
 - Skills index: `plugins/specweave/skills/SKILLS-INDEX.md`
 - Claude Code Skills docs: `~/CLAUDE.md` (Personal skills reference)
 
+### 16. YAML Frontmatter Validation (CRITICAL!)
+
+**Rule**: ALL spec.md files MUST have valid YAML frontmatter with required fields.
+
+**Required Format**:
+```yaml
+---
+increment: 0001-feature-name  # REQUIRED: 4-digit number + kebab-case
+title: Feature Title           # OPTIONAL: Human-readable title
+feature_id: FS-001            # OPTIONAL: Living docs feature ID
+---
+```
+
+**Common Mistakes**:
+
+```yaml
+# ❌ WRONG: Unclosed bracket
+---
+increment: 0001-test
+data: [unclosed
+---
+
+# ❌ WRONG: Unclosed quote
+---
+increment: 0001-test
+title: "unclosed string
+---
+
+# ❌ WRONG: Invalid YAML object
+---
+increment: 0001-test
+config: {key: value, broken
+---
+
+# ❌ WRONG: Invalid increment ID format
+---
+increment: 1-test  # Missing leading zeros
+---
+
+# ❌ WRONG: Invalid increment ID format (uppercase)
+---
+increment: 0001-Test-Feature  # Uppercase letters not allowed
+---
+
+# ❌ WRONG: Missing required field
+---
+title: Feature Title  # Missing increment field!
+---
+
+# ✅ CORRECT: Minimal valid frontmatter
+---
+increment: 0001-feature-name
+---
+
+# ✅ CORRECT: Full frontmatter
+---
+increment: 0042-bug-fix
+title: Critical Bug Fix
+feature_id: FS-013
+---
+```
+
+**Prevention Layers**:
+
+1. **Pre-commit hook** - Validates YAML before commits (blocks malformed frontmatter)
+   ```bash
+   # Runs automatically on git commit
+   scripts/pre-commit-yaml-validation.sh
+   ```
+
+2. **Spec parser** - Uses `js-yaml` library (detects errors at runtime)
+   - Provides descriptive error messages
+   - Shows line numbers for YAML errors
+   - Suggests common fixes
+
+3. **Command validation** - `/specweave:validate` checks YAML syntax
+   ```bash
+   /specweave:validate 0001
+   ```
+
+**Manual YAML Testing**:
+
+```bash
+# Validate YAML in spec.md (manual check)
+node -e "
+  const yaml = require('js-yaml');
+  const fs = require('fs');
+  const content = fs.readFileSync('.specweave/increments/0001-test/spec.md', 'utf-8');
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatter) throw new Error('No frontmatter found');
+  const parsed = yaml.load(frontmatter[1]);
+  console.log('✅ Valid YAML:', JSON.stringify(parsed, null, 2));
+"
+```
+
+**Error Messages**:
+
+When YAML validation fails, you'll see descriptive errors:
+
+```
+ERROR: Malformed YAML syntax in frontmatter
+DETAILS: Unexpected end of stream
+LOCATION: Lines 2-5
+HINT: Common mistakes:
+  - Unclosed brackets: [unclosed
+  - Unclosed quotes: "unclosed
+  - Invalid YAML object: {key: value, broken
+```
+
+**Why This Matters**:
+- **Silent failures**: Malformed YAML can cause missing/incorrect metadata
+- **Sync issues**: Invalid increment IDs break living docs sync
+- **GitHub sync**: Broken frontmatter prevents issue creation
+- **Validation failures**: Tasks/ACs can't be parsed without valid metadata
+
+**Incident History**:
+- **Test case**: `tests/integration/commands/plan-command.integration.test.ts:626` tests malformed YAML handling
+- **Root cause**: Regex-based parsing was tolerant but unreliable
+- **Solution**: Multi-layered YAML validation with `js-yaml` library
+
+**See Also**:
+- Pre-commit hook: `scripts/pre-commit-yaml-validation.sh`
+- Spec parser: `src/generators/spec/spec-parser.ts` (uses js-yaml)
+- Test suite: `tests/integration/commands/plan-command.integration.test.ts`
+
 ---
 
 ## Project Structure

package/bin/specweave.js

@@ -37,6 +37,7 @@ program
   .option('--tech-stack <language>', 'Technology stack (nodejs, python, etc.)', undefined)
   .option('-l, --language <lang>', 'Language for generated content (en, ru, es, zh, de, fr, ja, ko, pt)', 'en')
   .option('-f, --force', 'Force fresh start (non-interactive, removes existing .specweave)', false)
+  .option('--force-refresh', 'Force marketplace refresh (skip cache, always pull latest)', false)
   .action(async (projectName, options) => {
     const { initCommand } = await import('../dist/src/cli/commands/init.js');
     await initCommand(projectName, options);

package/dist/src/cli/commands/init.d.ts

@@ -5,6 +5,7 @@ interface InitOptions {
     techStack?: string;
     language?: string;
     force?: boolean;
+    forceRefresh?: boolean;
     logger?: Logger;
 }
 export declare function initCommand(projectName?: string, options?: InitOptions): Promise<void>;

package/dist/src/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAgB9D,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8ID,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAwyCf"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAgB9D,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8ID,wBAAsB,WAAW,CAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA80Cf"}

package/dist/src/cli/commands/init.js

@@ -914,81 +914,66 @@ export async function initCommand(projectName, options = {}) {
             else {
                 // Claude CLI available → install ALL plugins from marketplace
                 try {
-                    // Step 1: Remove existing marketplace to force update (REQUIRED for updates!)
-                    // This ensures users get the latest plugins when new ones are added
-                    spinner.start('Refreshing SpecWeave marketplace...');
-                    const listResult = execFileNoThrowSync('claude', [
-                        'plugin',
-                        'marketplace',
-                        'list'
-                    ]);
-                    const marketplaceExists = listResult.success &&
-                        (listResult.stdout || '').toLowerCase().includes('specweave');
-                    if (marketplaceExists) {
-                        execFileNoThrowSync('claude', [
-                            'plugin',
-                            'marketplace',
-                            'remove',
-                            'specweave'
-                        ]);
-                        console.log(chalk.blue('   🔄 Removed existing marketplace for update'));
-                    }
-                    // Step 2: Add marketplace from GitHub (always fresh)
-                    const addResult = execFileNoThrowSync('claude', [
-                        'plugin',
-                        'marketplace',
-                        'add',
-                        'anton-abyzov/specweave'
-                    ]);
-                    if (!addResult.success) {
-                        throw new Error('Failed to add marketplace from GitHub');
-                    }
-                    console.log(chalk.green('   ✔ Marketplace registered from GitHub'));
-                    // CRITICAL: Wait for marketplace cache to be FULLY ready
-                    // Problem: Fixed delays (2s, 5s) are unreliable - cache initialization time varies
-                    // Solution: Poll until marketplace.json exists and is readable in cache
-                    spinner.text = 'Waiting for marketplace cache to initialize...';
                     const marketplaceCachePath = path.join(os.homedir(), '.claude/plugins/marketplaces/specweave/.claude-plugin/marketplace.json');
-                    const maxWaitTime = 30000; // 30 seconds max
-                    const pollInterval = 500; // Check every 500ms
-                    const startTime = Date.now();
-                    let cacheReady = false;
-                    while (!cacheReady && (Date.now() - startTime) < maxWaitTime) {
-                        try {
-                            // Check if marketplace.json exists and is readable
-                            if (fs.existsSync(marketplaceCachePath)) {
+                    // ULTRAFAST: Check if cache is fresh (< 5 min old) and valid
+                    let needsRefresh = true;
+                    let cacheAlreadyValid = false;
+                    // Skip cache if forceRefresh flag is set
+                    if (!options.forceRefresh && fs.existsSync(marketplaceCachePath)) {
+                        const cacheStats = fs.statSync(marketplaceCachePath);
+                        const cacheAge = Date.now() - cacheStats.mtimeMs;
+                        const fiveMinutes = 5 * 60 * 1000;
+                        if (cacheAge < fiveMinutes) {
+                            try {
                                 const cacheData = JSON.parse(fs.readFileSync(marketplaceCachePath, 'utf-8'));
-                                // CRITICAL: Verify plugins array is FULLY populated with metadata
-                                // Not just present, but each plugin has required fields (name, version, etc.)
-                                if (cacheData.plugins && cacheData.plugins.length >= 25) {
-                                    // Additional validation: check if plugins have required metadata
-                                    const hasMetadata = cacheData.plugins.every((p) => p.name && p.version && p.description);
-                                    if (hasMetadata) {
-                                        cacheReady = true;
-                                        const waitedMs = Date.now() - startTime;
-                                        console.log(chalk.gray(`   ⏱  Cache ready in ${Math.round(waitedMs / 1000)}s`));
-                                        break;
-                                    }
-                                    else {
-                                        // Plugins exist but metadata incomplete - keep waiting
-                                        spinner.text = `Waiting for plugin metadata... (${Math.round((Date.now() - startTime) / 1000)}s)`;
-                                    }
+                                const hasValidPlugins = cacheData.plugins &&
+                                    cacheData.plugins.length >= 25 &&
+                                    cacheData.plugins.every((p) => p.name && p.version && p.description);
+                                if (hasValidPlugins) {
+                                    needsRefresh = false;
+                                    cacheAlreadyValid = true;
+                                    console.log(chalk.green('   ⚡ Using cached marketplace (fresh)'));
                                 }
                             }
+                            catch {
+                                // Cache exists but invalid, needs refresh
+                            }
                         }
-                        catch (e) {
-                            // File exists but not readable yet (still being written)
-                        }
-                        // Wait before next poll
-                        await new Promise(resolve => setTimeout(resolve, pollInterval));
-                        // Update spinner to show we're still waiting
-                        const elapsed = Math.round((Date.now() - startTime) / 1000);
-                        spinner.text = `Waiting for marketplace cache... (${elapsed}s)`;
                     }
-                    if (!cacheReady) {
-                        console.log(chalk.yellow('   ⚠ Cache initialization timeout, proceeding anyway...'));
+                    if (needsRefresh) {
+                        // Step 1: Remove existing marketplace to force update
+                        spinner.start('Refreshing SpecWeave marketplace...');
+                        const listResult = execFileNoThrowSync('claude', [
+                            'plugin',
+                            'marketplace',
+                            'list'
+                        ]);
+                        const marketplaceExists = listResult.success &&
+                            (listResult.stdout || '').toLowerCase().includes('specweave');
+                        if (marketplaceExists) {
+                            execFileNoThrowSync('claude', [
+                                'plugin',
+                                'marketplace',
+                                'remove',
+                                'specweave'
+                            ]);
+                            console.log(chalk.blue('   🔄 Removed existing marketplace for update'));
+                        }
+                        // Step 2: Add marketplace from GitHub (always fresh)
+                        const addResult = execFileNoThrowSync('claude', [
+                            'plugin',
+                            'marketplace',
+                            'add',
+                            'anton-abyzov/specweave'
+                        ]);
+                        if (!addResult.success) {
+                            throw new Error('Failed to add marketplace from GitHub');
+                        }
+                        console.log(chalk.green('   ✔ Marketplace registered from GitHub'));
+                        // NO WAIT NEEDED: We load from source (npm package), not cache
+                        // The cache is populated asynchronously by Claude Code and isn't used during init
+                        spinner.succeed('SpecWeave marketplace ready');
                     }
-                    spinner.succeed('SpecWeave marketplace ready');
                     // Step 2: Load marketplace.json to get ALL available plugins
                     spinner.start('Loading available plugins...');
                     const marketplaceJsonPath = findSourceDir('.claude-plugin/marketplace.json');
@@ -1088,6 +1073,59 @@ export async function initCommand(projectName, options = {}) {
                     autoInstallSucceeded = false;
                 }
             }
+            // 10.4 Repository Hosting Setup (FUNDAMENTAL!)
+            // Ask about repository hosting BEFORE issue tracker
+            // This determines what issue tracker options are available
+            console.log('');
+            console.log(chalk.cyan.bold('📦 Repository Hosting'));
+            console.log('');
+            // Detect existing git remote
+            const gitRemoteDetection = detectGitHubRemote(targetDir);
+            let repositoryHosting = 'local';
+            if (!isCI) {
+                const { hosting } = await inquirer.prompt([{
+                        type: 'list',
+                        name: 'hosting',
+                        message: 'How do you host your repository?',
+                        choices: [
+                            {
+                                name: `🐙 GitHub ${gitRemoteDetection ? '(detected)' : '(recommended)'}`,
+                                value: 'github'
+                            },
+                            {
+                                name: '💻 Local git only (no remote sync)',
+                                value: 'local'
+                            },
+                            {
+                                name: '🔧 Other (GitLab, Bitbucket, etc.)',
+                                value: 'other'
+                            }
+                        ],
+                        default: gitRemoteDetection ? 'github' : 'local'
+                    }]);
+                repositoryHosting = hosting;
+                // Show info for non-GitHub choices
+                if (hosting === 'other') {
+                    console.log('');
+                    console.log(chalk.yellow('⚠️  Note: SpecWeave currently has best integration with GitHub'));
+                    console.log(chalk.gray('   • GitHub: Full sync support (issues, milestones, labels)'));
+                    console.log(chalk.gray('   • GitLab/Bitbucket: Limited support (manual sync)'));
+                    console.log(chalk.gray('   • You can still use SpecWeave locally and sync manually'));
+                    console.log('');
+                }
+                else if (hosting === 'local') {
+                    console.log('');
+                    console.log(chalk.gray('✓ Local-only mode'));
+                    console.log(chalk.gray('   • All work tracked locally in .specweave/'));
+                    console.log(chalk.gray('   • No remote sync (you can add GitHub later)'));
+                    console.log('');
+                }
+            }
+            else {
+                // CI mode: auto-detect
+                repositoryHosting = gitRemoteDetection ? 'github' : 'local';
+                console.log(chalk.gray(`   → CI mode: Auto-detected ${repositoryHosting} hosting\n`));
+            }
             // 10.5 Issue Tracker Integration (CRITICAL!)
             // MUST happen AFTER plugin installation is complete
             // Asks user: Which tracker? (GitHub/Jira/ADO/None)
@@ -1135,7 +1173,8 @@ export async function initCommand(projectName, options = {}) {
                                 projectPath: targetDir,
                                 language: language,
                                 maxRetries: 3,
-                                isFrameworkRepo
+                                isFrameworkRepo,
+                                repositoryHosting
                             });
                         }
                     }
@@ -1151,7 +1190,8 @@ export async function initCommand(projectName, options = {}) {
                         projectPath: targetDir,
                         language: language,
                         maxRetries: 3,
-                        isFrameworkRepo
+                        isFrameworkRepo,
+                        repositoryHosting
                     });
                 }
             }