bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

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('');

package/tools/schema/agent.js

@@ -229,6 +229,7 @@ function buildMetadataSchema(expectedModule) {
     title: createNonEmptyString('agent.metadata.title'),
     icon: createNonEmptyString('agent.metadata.icon'),
     module: createNonEmptyString('agent.metadata.module').optional(),
+    hasSidecar: z.boolean(),
   };
 
   return z.object(schemaShape).strict();

package/tools/validate-doc-links.js

@@ -0,0 +1,363 @@
+/**
+ * Documentation Link Validator
+ *
+ * Validates site-relative links in markdown files and attempts to fix broken ones.
+ *
+ * What it checks:
+ * - All site-relative links (starting with /) point to existing .md files
+ * - Anchor links (#section) point to valid headings
+ *
+ * What it fixes:
+ * - Broken links where the target file can be found elsewhere in /docs
+ *
+ * Usage:
+ *   node tools/validate-doc-links.js           # Dry run (validate and show issues)
+ *   node tools/validate-doc-links.js --write   # Fix auto-fixable issues
+ */
+
+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 with site-relative paths
+const LINK_REGEX = /\[([^\]]*)\]\((\/[^)]+)\)/g;
+
+// File extensions that are static assets, not markdown docs
+const STATIC_ASSET_EXTENSIONS = ['.zip', '.txt', '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
+
+// Regex to extract headings for anchor validation
+const HEADING_PATTERN = /^#{1,6}\s+(.+)$/gm;
+
+/**
+ * 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);
+
+      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;
+}
+
+/**
+ * Strip fenced code blocks from content
+ */
+function stripCodeBlocks(content) {
+  return content.replaceAll(/```[\s\S]*?```/g, '');
+}
+
+/**
+ * Convert a heading to its anchor slug
+ */
+function headingToAnchor(heading) {
+  return heading
+    .toLowerCase()
+    .replaceAll(/[\u{1F300}-\u{1F9FF}]/gu, '') // Remove emojis
+    .replaceAll(/[^\w\s-]/g, '') // Remove special chars
+    .replaceAll(/\s+/g, '-') // Spaces to hyphens
+    .replaceAll(/-+/g, '-') // Collapse hyphens
+    .replaceAll(/^-+|-+$/g, ''); // Trim hyphens
+}
+
+/**
+ * Extract anchor slugs from a markdown file
+ */
+function extractAnchors(content) {
+  const anchors = new Set();
+  let match;
+
+  HEADING_PATTERN.lastIndex = 0;
+  while ((match = HEADING_PATTERN.exec(content)) !== null) {
+    const headingText = match[1]
+      .trim()
+      .replaceAll(/`[^`]+`/g, '')
+      .replaceAll(/\*\*([^*]+)\*\*/g, '$1')
+      .replaceAll(/\*([^*]+)\*/g, '$1')
+      .replaceAll(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+      .trim();
+    anchors.add(headingToAnchor(headingText));
+  }
+
+  return anchors;
+}
+
+/**
+ * Resolve a site-relative link to a file path
+ * /docs/how-to/installation/install-bmad.md -> docs/how-to/installation/install-bmad.md
+ * /how-to/installation/install-bmad/ -> docs/how-to/installation/install-bmad.md or .../index.md
+ */
+function resolveLink(siteRelativePath) {
+  // Strip anchor and query
+  let checkPath = siteRelativePath.split('#')[0].split('?')[0];
+
+  // Strip /docs/ prefix if present (repo-relative links)
+  if (checkPath.startsWith('/docs/')) {
+    checkPath = checkPath.slice(5); // Remove '/docs' but keep leading '/'
+  }
+
+  if (checkPath.endsWith('/')) {
+    // Could be file.md or directory/index.md
+    const asFile = path.join(DOCS_ROOT, checkPath.slice(0, -1) + '.md');
+    const asIndex = path.join(DOCS_ROOT, checkPath, 'index.md');
+
+    if (fs.existsSync(asFile)) return asFile;
+    if (fs.existsSync(asIndex)) return asIndex;
+    return null;
+  }
+
+  // Direct path (e.g., /path/file.md)
+  const direct = path.join(DOCS_ROOT, checkPath);
+  if (fs.existsSync(direct)) return direct;
+
+  // Try with .md extension
+  const withMd = direct + '.md';
+  if (fs.existsSync(withMd)) return withMd;
+
+  return null;
+}
+
+/**
+ * Search for a file with directory context
+ */
+function findFileWithContext(brokenPath) {
+  // Extract filename and parent directory from the broken path
+  // e.g., /tutorials/getting-started/foo/ -> parent: getting-started, file: foo.md
+  const cleanPath = brokenPath.replace(/\/$/, '').replace(/^\//, '');
+  const parts = cleanPath.split('/');
+  const fileName = parts.at(-1) + '.md';
+  const parentDir = parts.length > 1 ? parts.at(-2) : null;
+
+  const allFiles = getMarkdownFiles(DOCS_ROOT);
+  const matches = [];
+
+  for (const file of allFiles) {
+    const fileBaseName = path.basename(file);
+    const fileParentDir = path.basename(path.dirname(file));
+
+    // Exact filename match with parent directory context
+    if (fileBaseName === fileName) {
+      if (parentDir && fileParentDir === parentDir) {
+        // Strong match: both filename and parent dir match
+        return [file];
+      }
+      matches.push(file);
+    }
+
+    // Also check for index.md in a matching directory
+    if (fileBaseName === 'index.md' && fileParentDir === fileName.replace('.md', '')) {
+      matches.push(file);
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Convert absolute file path to site-relative URL
+ */
+function fileToSiteRelative(filePath) {
+  let relative = '/' + path.relative(DOCS_ROOT, filePath);
+  relative = relative.split(path.sep).join('/');
+
+  if (relative.endsWith('/index.md')) {
+    return relative.replace(/\/index\.md$/, '/');
+  }
+  return relative.replace(/\.md$/, '/');
+}
+
+/**
+ * Process a single file and find issues
+ */
+function processFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const strippedContent = stripCodeBlocks(content);
+  const issues = [];
+
+  let match;
+  LINK_REGEX.lastIndex = 0;
+
+  while ((match = LINK_REGEX.exec(strippedContent)) !== null) {
+    const linkText = match[1];
+    const href = match[2];
+
+    // Extract path and anchor
+    const hashIndex = href.indexOf('#');
+    const linkPath = hashIndex === -1 ? href : href.slice(0, hashIndex);
+    const anchor = hashIndex === -1 ? null : href.slice(hashIndex + 1);
+
+    // Skip static asset links (zip, txt, images, etc.)
+    const linkLower = linkPath.toLowerCase();
+    if (STATIC_ASSET_EXTENSIONS.some((ext) => linkLower.endsWith(ext))) {
+      continue;
+    }
+
+    // Validate the link target exists
+    const targetFile = resolveLink(linkPath);
+
+    if (!targetFile) {
+      // Link is broken - try to find the file
+      const candidates = findFileWithContext(linkPath);
+
+      const issue = {
+        type: 'broken-link',
+        linkText,
+        href,
+        linkPath,
+        fullMatch: match[0],
+      };
+
+      if (candidates.length === 1) {
+        issue.status = 'auto-fixable';
+        issue.suggestedFix = fileToSiteRelative(candidates[0]) + (anchor ? '#' + anchor : '');
+        issue.foundAt = path.relative(DOCS_ROOT, candidates[0]);
+      } else if (candidates.length > 1) {
+        issue.status = 'needs-review';
+        issue.candidates = candidates.map((c) => path.relative(DOCS_ROOT, c));
+      } else {
+        issue.status = 'manual-check';
+      }
+
+      issues.push(issue);
+      continue;
+    }
+
+    // Validate anchor if present
+    if (anchor) {
+      const targetContent = fs.readFileSync(targetFile, 'utf-8');
+      const anchors = extractAnchors(targetContent);
+
+      if (!anchors.has(anchor)) {
+        issues.push({
+          type: 'broken-anchor',
+          linkText,
+          href,
+          anchor,
+          status: 'manual-check',
+          message: `Anchor "#${anchor}" not found`,
+        });
+      }
+    }
+  }
+
+  return { content, issues };
+}
+
+/**
+ * Apply fixes to file content
+ */
+function applyFixes(content, issues) {
+  let updated = content;
+
+  for (const issue of issues) {
+    if (issue.status === 'auto-fixable' && issue.suggestedFix) {
+      const oldLink = `[${issue.linkText}](${issue.href})`;
+      const newLink = `[${issue.linkText}](${issue.suggestedFix})`;
+      updated = updated.replace(oldLink, newLink);
+    }
+  }
+
+  return updated;
+}
+
+// Main execution
+console.log(`\nValidating docs in: ${DOCS_ROOT}`);
+console.log(`Mode: ${DRY_RUN ? 'DRY RUN (use --write to fix)' : 'WRITE MODE'}\n`);
+
+const files = getMarkdownFiles(DOCS_ROOT);
+console.log(`Found ${files.length} markdown files\n`);
+
+let totalIssues = 0;
+let autoFixable = 0;
+let needsReview = 0;
+let manualCheck = 0;
+let filesWithIssues = 0;
+
+const allIssues = [];
+
+for (const filePath of files) {
+  const relativePath = path.relative(DOCS_ROOT, filePath);
+  const { content, issues } = processFile(filePath);
+
+  if (issues.length > 0) {
+    filesWithIssues++;
+    totalIssues += issues.length;
+
+    console.log(`\n${relativePath}`);
+
+    for (const issue of issues) {
+      if (issue.status === 'auto-fixable') {
+        autoFixable++;
+        console.log(`  [FIX] ${issue.href}`);
+        console.log(`     -> ${issue.suggestedFix}`);
+      } else if (issue.status === 'needs-review') {
+        needsReview++;
+        console.log(`  [REVIEW] ${issue.href}`);
+        console.log(`     Multiple matches found:`);
+        for (const candidate of issue.candidates) {
+          console.log(`       - ${candidate}`);
+        }
+      } else if (issue.type === 'broken-anchor') {
+        manualCheck++;
+        console.log(`  [MANUAL] ${issue.href}`);
+        console.log(`     ${issue.message}`);
+      } else {
+        manualCheck++;
+        console.log(`  [MANUAL] ${issue.href}`);
+        console.log(`     File not found anywhere - may need to remove link`);
+      }
+
+      allIssues.push({ file: relativePath, ...issue });
+    }
+
+    // Apply fixes if not dry run
+    if (!DRY_RUN) {
+      const fixableIssues = issues.filter((i) => i.status === 'auto-fixable');
+      if (fixableIssues.length > 0) {
+        const updated = applyFixes(content, fixableIssues);
+        fs.writeFileSync(filePath, updated, 'utf-8');
+      }
+    }
+  }
+}
+
+console.log(`\n${'─'.repeat(60)}`);
+console.log(`\nSummary:`);
+console.log(`   Files scanned: ${files.length}`);
+console.log(`   Files with issues: ${filesWithIssues}`);
+console.log(`   Total issues: ${totalIssues}`);
+
+if (totalIssues > 0) {
+  console.log(`\n   Breakdown:`);
+  console.log(`     Auto-fixable:  ${autoFixable}`);
+  console.log(`     Needs review:  ${needsReview}`);
+  console.log(`     Manual check:  ${manualCheck}`);
+}
+
+if (totalIssues === 0) {
+  console.log(`\n   All links valid!`);
+} else if (DRY_RUN && autoFixable > 0) {
+  console.log(`\nRun with --write to auto-fix ${autoFixable} issue(s)`);
+}
+
+console.log('');
+
+process.exit(totalIssues > 0 ? 1 : 0);