bmad-fh 6.0.0-alpha.23

package/tools/cli/scripts/migrate-workflows.js

@@ -0,0 +1,281 @@
+
+/**
+ * Workflow Migration Script
+ * 
+ * Updates workflow.yaml files to support the multi-scope system.
+ * Primarily updates test_dir and other path variables to use scope-aware paths.
+ * 
+ * Usage:
+ *   node migrate-workflows.js [--dry-run] [--verbose]
+ * 
+ * Options:
+ *   --dry-run   Show what would be changed without making changes
+ *   --verbose   Show detailed output
+ */
+
+const fs = require('fs-extra');
+const path = require('node:path');
+const yaml = require('yaml');
+const chalk = require('chalk');
+
+// Configuration
+const SRC_PATH = path.resolve(__dirname, '../../../src');
+const WORKFLOW_PATTERN = '**/workflow.yaml';
+
+// Path mappings for migration
+const PATH_MIGRATIONS = [
+  // Test directory migrations
+  {
+    pattern: /\{output_folder\}\/tests/g,
+    replacement: '{scope_tests}',
+    description: 'test directory to scope_tests'
+  },
+  {
+    pattern: /\{config_source:implementation_artifacts\}\/tests/g,
+    replacement: '{config_source:scope_tests}',
+    description: 'implementation_artifacts tests to scope_tests'
+  },
+  // Planning artifacts
+  {
+    pattern: /\{output_folder\}\/planning-artifacts/g,
+    replacement: '{config_source:planning_artifacts}',
+    description: 'output_folder planning to config_source'
+  },
+  // Implementation artifacts  
+  {
+    pattern: /\{output_folder\}\/implementation-artifacts/g,
+    replacement: '{config_source:implementation_artifacts}',
+    description: 'output_folder implementation to config_source'
+  }
+];
+
+// Variables that indicate scope requirement
+const SCOPE_INDICATORS = [
+  '{scope}',
+  '{scope_path}',
+  '{scope_tests}',
+  '{scope_planning}',
+  '{scope_implementation}'
+];
+
+/**
+ * Find all workflow.yaml files
+ */
+async function findWorkflowFiles(basePath) {
+  const files = [];
+  
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      
+      if (entry.isDirectory()) {
+        // Skip node_modules and hidden directories
+        if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          await walk(fullPath);
+        }
+      } else if (entry.name === 'workflow.yaml') {
+        files.push(fullPath);
+      }
+    }
+  }
+  
+  await walk(basePath);
+  return files;
+}
+
+/**
+ * Check if a workflow already uses scope variables
+ */
+function usesScope(content) {
+  return SCOPE_INDICATORS.some(indicator => content.includes(indicator));
+}
+
+/**
+ * Analyze a workflow file and suggest migrations
+ */
+function analyzeWorkflow(content, filePath) {
+  const analysis = {
+    filePath,
+    needsMigration: false,
+    alreadyScoped: false,
+    suggestions: [],
+    currentVariables: []
+  };
+  
+  // Check if already uses scope
+  if (usesScope(content)) {
+    analysis.alreadyScoped = true;
+    return analysis;
+  }
+  
+  // Find variables that might need migration
+  const variablePattern = /\{[^}]+\}/g;
+  const matches = content.match(variablePattern) || [];
+  analysis.currentVariables = [...new Set(matches)];
+  
+  // Check each migration pattern
+  for (const migration of PATH_MIGRATIONS) {
+    if (migration.pattern.test(content)) {
+      analysis.needsMigration = true;
+      analysis.suggestions.push({
+        description: migration.description,
+        pattern: migration.pattern.toString(),
+        replacement: migration.replacement
+      });
+    }
+  }
+  
+  // Check for test_dir variable
+  if (content.includes('test_dir:') || content.includes('test_dir:')) {
+    analysis.needsMigration = true;
+    analysis.suggestions.push({
+      description: 'Has test_dir variable - may need scope_tests',
+      pattern: 'test_dir',
+      replacement: 'scope_tests via config_source'
+    });
+  }
+  
+  return analysis;
+}
+
+/**
+ * Apply migrations to workflow content
+ */
+function migrateWorkflow(content) {
+  let migrated = content;
+  let changes = [];
+  
+  for (const migration of PATH_MIGRATIONS) {
+    if (migration.pattern.test(migrated)) {
+      migrated = migrated.replace(migration.pattern, migration.replacement);
+      changes.push(migration.description);
+    }
+  }
+  
+  return { content: migrated, changes };
+}
+
+/**
+ * Add scope_required marker to workflow
+ */
+function addScopeMarker(content) {
+  try {
+    const parsed = yaml.parse(content);
+    
+    // Add scope_required if not present
+    if (!parsed.scope_required) {
+      parsed.scope_required = false; // Default to false for backward compatibility
+    }
+    
+    return yaml.stringify(parsed, { lineWidth: 120 });
+  } catch {
+    // If YAML parsing fails, return original
+    return content;
+  }
+}
+
+/**
+ * Main migration function
+ */
+async function main() {
+  const args = new Set(process.argv.slice(2));
+  const dryRun = args.has('--dry-run');
+  const verbose = args.has('--verbose');
+  
+  console.log(chalk.bold('\nWorkflow Migration Script'));
+  console.log(chalk.dim('Updating workflow.yaml files for multi-scope support\n'));
+  
+  if (dryRun) {
+    console.log(chalk.yellow('DRY RUN MODE - No changes will be made\n'));
+  }
+  
+  // Find all workflow files
+  console.log(chalk.blue('Scanning for workflow.yaml files...'));
+  const files = await findWorkflowFiles(SRC_PATH);
+  console.log(chalk.green(`Found ${files.length} workflow.yaml files\n`));
+  
+  // Analysis results
+  const results = {
+    analyzed: 0,
+    alreadyScoped: 0,
+    migrated: 0,
+    noChanges: 0,
+    errors: []
+  };
+  
+  // Process each file
+  for (const filePath of files) {
+    const relativePath = path.relative(SRC_PATH, filePath);
+    results.analyzed++;
+    
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      const analysis = analyzeWorkflow(content, filePath);
+      
+      if (analysis.alreadyScoped) {
+        results.alreadyScoped++;
+        if (verbose) {
+          console.log(chalk.dim(`  ○ ${relativePath} - already scope-aware`));
+        }
+        continue;
+      }
+      
+      if (!analysis.needsMigration) {
+        results.noChanges++;
+        if (verbose) {
+          console.log(chalk.dim(`  ○ ${relativePath} - no changes needed`));
+        }
+        continue;
+      }
+      
+      // Apply migration
+      const { content: migrated, changes } = migrateWorkflow(content);
+      
+      if (changes.length > 0) {
+        console.log(chalk.cyan(`  ● ${relativePath}`));
+        for (const change of changes) {
+          console.log(chalk.dim(`      → ${change}`));
+        }
+        
+        if (!dryRun) {
+          await fs.writeFile(filePath, migrated, 'utf8');
+        }
+        results.migrated++;
+      } else {
+        results.noChanges++;
+      }
+      
+    } catch (error) {
+      results.errors.push({ file: relativePath, error: error.message });
+      console.log(chalk.red(`  ✗ ${relativePath} - Error: ${error.message}`));
+    }
+  }
+  
+  // Print summary
+  console.log(chalk.bold('\n─────────────────────────────────────'));
+  console.log(chalk.bold('Summary'));
+  console.log(chalk.dim('─────────────────────────────────────'));
+  console.log(`  Files analyzed:     ${results.analyzed}`);
+  console.log(`  Already scope-aware: ${results.alreadyScoped}`);
+  console.log(`  Migrated:           ${results.migrated}`);
+  console.log(`  No changes needed:  ${results.noChanges}`);
+  if (results.errors.length > 0) {
+    console.log(chalk.red(`  Errors:             ${results.errors.length}`));
+  }
+  console.log();
+  
+  if (dryRun && results.migrated > 0) {
+    console.log(chalk.yellow('Run without --dry-run to apply changes\n'));
+  }
+  
+  // Exit with error code if there were errors
+  process.exit(results.errors.length > 0 ? 1 : 0);
+}
+
+// Run
+main().catch(error => {
+  console.error(chalk.red('Fatal error:'), error.message);
+  process.exit(1);
+});

package/tools/docs/BUNDLE_DISTRIBUTION_SETUP.md

@@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** BMAD maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create bmad-bundles repo
+gh repo create bmad-code-org/bmad-bundles --public --description "BMAD Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:bmad-code-org/bmad-bundles.git
+cd bmad-bundles
+printf '# bmad-bundles\n\nStatic bundles published from BMAD-METHOD.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/bmad-code-org/bmad-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: bmad-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://bmad-code-org.github.io/bmad-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://bmad-code-org.github.io/bmad-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo bmad-code-org/BMAD-METHOD | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+**Latest:** `https://bmad-code-org.github.io/bmad-bundles/`

package/tools/docs/index.md

@@ -0,0 +1,2 @@
+# Tool and Repo Maintainability Documentation
+

package/tools/fix-doc-links.js

@@ -0,0 +1,288 @@
+/**
+ * Fix Documentation Links
+ *
+ * Converts relative markdown links to repo-relative paths with .md extension.
+ * This ensures links work both in GitHub and on the Astro/Starlight site
+ * (the rehype plugin transforms /docs/path/file.md → /path/file/ at build time).
+ *
+ * - ./file.md → /docs/current/path/file.md
+ * - ../other/file.md → /docs/resolved/path/file.md
+ * - /path/file/ → /docs/path/file.md (or /docs/path/file/index.md if it's a directory)
+ *
+ * Usage:
+ *   node tools/fix-doc-links.js           # Dry run (shows what would change)
+ *   node tools/fix-doc-links.js --write   # Actually write changes
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_ROOT = path.resolve(__dirname, '../docs');
+const DRY_RUN = !process.argv.includes('--write');
+
+// Regex to match markdown links:
+// - [text](path.md) or [text](path.md#anchor) - existing .md links
+// - [text](/path/to/page/) or [text](/path/to/page/#anchor) - site-relative links to convert
+const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]+(?:\.md|\/))(?:#[^)]*)?(?:\?[^)]*)?\)/g;
+// Simpler approach: match all markdown links and filter in the handler
+const ALL_MARKDOWN_LINKS_REGEX = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+/**
+ * Get all markdown files in docs directory, excluding _* directories/files
+ */
+function getMarkdownFiles(dir) {
+  const files = [];
+
+  function walk(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      // Skip underscore-prefixed entries
+      if (entry.name.startsWith('_')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Convert a markdown link href to repo-relative path with .md extension
+ *
+ * @param {string} href - The original href (e.g., "./file.md", "/path/to/page/", "/path/to/page/#anchor")
+ * @param {string} currentFilePath - Absolute path to the file containing this link
+ * @returns {string|null} - Repo-relative path (e.g., "/docs/path/to/file.md"), or null if shouldn't be converted
+ */
+function convertToRepoRelative(href, currentFilePath) {
+  // Skip external links
+  if (href.includes('://') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+    return null;
+  }
+
+  // Skip anchor-only links
+  if (href.startsWith('#')) {
+    return null;
+  }
+
+  // Extract anchor and query string if present
+  let anchor = '';
+  let query = '';
+  let pathPortion = href;
+
+  const hashIndex = href.indexOf('#');
+  const queryIndex = href.indexOf('?');
+
+  if (hashIndex !== -1 || queryIndex !== -1) {
+    const firstDelimiter = Math.min(hashIndex === -1 ? Infinity : hashIndex, queryIndex === -1 ? Infinity : queryIndex);
+    pathPortion = href.slice(0, Math.max(0, firstDelimiter));
+
+    const suffix = href.slice(Math.max(0, firstDelimiter));
+    const anchorInSuffix = suffix.indexOf('#');
+
+    if (suffix.startsWith('?')) {
+      if (anchorInSuffix === -1) {
+        query = suffix;
+      } else {
+        query = suffix.slice(0, Math.max(0, anchorInSuffix));
+        anchor = suffix.slice(Math.max(0, anchorInSuffix));
+      }
+    } else {
+      anchor = suffix;
+    }
+  }
+
+  // Skip non-documentation links (images, external assets, etc.)
+  const ext = path.extname(pathPortion).toLowerCase();
+  if (
+    ext &&
+    ext !== '.md' &&
+    !['.md'].includes(ext) && // Has an extension that's not .md - skip unless it's a trailing slash path
+    !pathPortion.endsWith('/')
+  ) {
+    return null;
+  }
+
+  // Check if original path ends with / (directory reference) BEFORE path.join normalizes it
+  const isDirectoryPath = pathPortion.endsWith('/');
+
+  let absolutePath;
+
+  if (pathPortion.startsWith('/docs/')) {
+    // Already repo-relative with /docs/ prefix
+    absolutePath = path.join(path.dirname(DOCS_ROOT), pathPortion);
+  } else if (pathPortion.startsWith('/')) {
+    // Site-relative (e.g., /tutorials/getting-started/) - resolve from docs root
+    absolutePath = path.join(DOCS_ROOT, pathPortion);
+  } else {
+    // Relative path (./, ../, or bare filename) - resolve from current file's directory
+    const currentDir = path.dirname(currentFilePath);
+    absolutePath = path.resolve(currentDir, pathPortion);
+  }
+
+  // Convert to repo-relative path (with /docs/ prefix)
+  let repoRelative = '/docs/' + path.relative(DOCS_ROOT, absolutePath);
+
+  // Normalize path separators for Windows
+  repoRelative = repoRelative.split(path.sep).join('/');
+
+  // If original path was a directory reference (ended with /), check for index.md or file.md
+  if (isDirectoryPath) {
+    const relativeDir = repoRelative.slice(6); // Remove '/docs/'
+
+    // Handle root path case (relativeDir is empty or just '.')
+    const normalizedDir = relativeDir === '' || relativeDir === '.' ? '' : relativeDir;
+    const indexPath = path.join(DOCS_ROOT, normalizedDir, 'index.md');
+    const filePath = normalizedDir ? path.join(DOCS_ROOT, normalizedDir + '.md') : null;
+
+    if (fs.existsSync(indexPath)) {
+      // Avoid double slash when repoRelative is '/docs/' (root case)
+      repoRelative = repoRelative.endsWith('/') ? repoRelative + 'index.md' : repoRelative + '/index.md';
+    } else if (filePath && fs.existsSync(filePath)) {
+      repoRelative = repoRelative + '.md';
+    } else {
+      // Neither exists - default to index.md and let validation catch it
+      repoRelative = repoRelative.endsWith('/') ? repoRelative + 'index.md' : repoRelative + '/index.md';
+    }
+  } else if (!repoRelative.endsWith('.md')) {
+    // Path doesn't end with .md - add .md
+    repoRelative = repoRelative + '.md';
+  }
+
+  return repoRelative + query + anchor;
+}
+
+/**
+ * Process a single markdown file, skipping links inside fenced code blocks
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {Object} - { changed: boolean, original: string, updated: string, changes: Array }
+ */
+function processFile(filePath) {
+  const original = fs.readFileSync(filePath, 'utf-8');
+  const changes = [];
+
+  // Extract fenced code blocks and replace with placeholders
+  const codeBlocks = [];
+  const CODE_PLACEHOLDER = '\u0000CODE_BLOCK_';
+
+  let contentWithPlaceholders = original.replaceAll(/```[\s\S]*?```/g, (match) => {
+    const index = codeBlocks.length;
+    codeBlocks.push(match);
+    return `${CODE_PLACEHOLDER}${index}\u0000`;
+  });
+
+  // Process links only in non-code-block content
+  contentWithPlaceholders = contentWithPlaceholders.replaceAll(ALL_MARKDOWN_LINKS_REGEX, (match, linkText, href) => {
+    const newHref = convertToRepoRelative(href, filePath);
+
+    // Skip if conversion returned null (external link, anchor, etc.)
+    if (newHref === null) {
+      return match;
+    }
+
+    // Only record as change if actually different
+    if (newHref !== href) {
+      changes.push({ from: href, to: newHref });
+      return `[${linkText}](${newHref})`;
+    }
+
+    return match;
+  });
+
+  // Restore code blocks
+  const updated = contentWithPlaceholders.replaceAll(
+    new RegExp(`${CODE_PLACEHOLDER}(\\d+)\u0000`, 'g'),
+    (match, index) => codeBlocks[parseInt(index, 10)],
+  );
+
+  return {
+    changed: changes.length > 0,
+    original,
+    updated,
+    changes,
+  };
+}
+
+/**
+ * Validate that a repo-relative link points to an existing file
+ */
+function validateLink(repoRelativePath) {
+  // Strip anchor/query
+  const checkPath = repoRelativePath.split('#')[0].split('?')[0];
+
+  // Remove /docs/ prefix to get path relative to DOCS_ROOT
+  const relativePath = checkPath.startsWith('/docs/') ? checkPath.slice(6) : checkPath.slice(1);
+
+  return fs.existsSync(path.join(DOCS_ROOT, relativePath));
+}
+
+// Main execution
+console.log(`\nScanning docs in: ${DOCS_ROOT}`);
+console.log(`Mode: ${DRY_RUN ? 'DRY RUN (use --write to apply changes)' : 'WRITE MODE'}\n`);
+
+const files = getMarkdownFiles(DOCS_ROOT);
+console.log(`Found ${files.length} markdown files (excluding _* paths)\n`);
+
+let totalChanges = 0;
+let filesChanged = 0;
+const brokenLinks = [];
+
+for (const filePath of files) {
+  const relativePath = path.relative(DOCS_ROOT, filePath);
+  const result = processFile(filePath);
+
+  if (result.changed) {
+    filesChanged++;
+    totalChanges += result.changes.length;
+
+    console.log(`\n${relativePath}`);
+    for (const change of result.changes) {
+      const isValid = validateLink(change.to);
+      const status = isValid ? '  ' : '! ';
+
+      console.log(`${status}  ${change.from}`);
+      console.log(`    -> ${change.to}`);
+
+      if (!isValid) {
+        brokenLinks.push({
+          file: relativePath,
+          link: change.to,
+          original: change.from,
+        });
+      }
+    }
+
+    if (!DRY_RUN) {
+      fs.writeFileSync(filePath, result.updated, 'utf-8');
+    }
+  }
+}
+
+console.log(`\n${'─'.repeat(60)}`);
+console.log(`\nSummary:`);
+console.log(`   Files scanned: ${files.length}`);
+console.log(`   Files with changes: ${filesChanged}`);
+console.log(`   Total link updates: ${totalChanges}`);
+
+if (brokenLinks.length > 0) {
+  console.log(`\n!  Potential broken links (${brokenLinks.length}):`);
+  for (const bl of brokenLinks) {
+    console.log(`   ${bl.file}: ${bl.link}`);
+  }
+}
+
+if (DRY_RUN && totalChanges > 0) {
+  console.log(`\nRun with --write to apply these changes`);
+}
+
+console.log('');