bmad-method 6.7.1 → 6.8.1-next.0

package/tools/bundle-web-bundles.js

@@ -0,0 +1,117 @@
+/**
+ * Web Bundle Release Packager
+ *
+ * Zips each bundle under web-bundles/ into dist/web-bundles/{slug}.zip
+ * for attachment to a GitHub Release.
+ *
+ * Usage:
+ *   node tools/bundle-web-bundles.js
+ *
+ * After running, the script prints the exact `gh release create` command
+ * (with the correct tag from bundles.json) for you to copy.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const BUNDLES_DIR = path.join(REPO_ROOT, 'web-bundles');
+const DIST_DIR = path.join(REPO_ROOT, 'dist', 'web-bundles');
+const MANIFEST = path.join(BUNDLES_DIR, 'bundles.json');
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function fail(msg) {
+  console.error(`[ERROR] ${msg}`);
+  process.exit(1);
+}
+
+function requireZipCli() {
+  try {
+    execSync('zip -v', { stdio: 'ignore' });
+  } catch {
+    fail("'zip' CLI not found on PATH. Install zip (macOS: preinstalled; Debian/Ubuntu: apt install zip; Alpine: apk add zip) and re-run.");
+  }
+}
+
+function loadManifest() {
+  if (!fs.existsSync(MANIFEST)) {
+    fail(`bundles.json not found at ${MANIFEST}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(MANIFEST, 'utf-8'));
+  } catch (error) {
+    fail(`bundles.json is not valid JSON: ${error.message}`);
+  }
+  if (!Array.isArray(manifest.bundles) || manifest.bundles.length === 0) {
+    fail('bundles.json is missing a non-empty "bundles" array.');
+  }
+  if (typeof manifest.releaseTag !== 'string' || !manifest.releaseTag) {
+    fail('bundles.json is missing "releaseTag".');
+  }
+  return manifest;
+}
+
+function main() {
+  requireZipCli();
+  const manifest = loadManifest();
+  const releaseTag = manifest.releaseTag;
+
+  fs.mkdirSync(DIST_DIR, { recursive: true });
+
+  console.log(`Packaging ${manifest.bundles.length} bundles for release ${releaseTag}\n`);
+
+  const zipped = [];
+  const missing = [];
+  const invalid = [];
+  for (const bundle of manifest.bundles) {
+    if (!bundle.slug || !SLUG_RE.test(bundle.slug)) {
+      invalid.push(bundle.slug || '(no slug)');
+      console.error(`  [INVALID] slug must match ${SLUG_RE} — got: ${bundle.slug}`);
+      continue;
+    }
+    const src = path.join(BUNDLES_DIR, bundle.slug);
+    if (!fs.existsSync(src)) {
+      missing.push(bundle.slug);
+      console.error(`  [MISSING] ${bundle.slug} — directory not found`);
+      continue;
+    }
+
+    const out = path.join(DIST_DIR, `${bundle.slug}.zip`);
+    if (fs.existsSync(out)) fs.unlinkSync(out);
+
+    try {
+      execFileSync('zip', ['-r', '-X', '-q', out, bundle.slug, '-x', '*.DS_Store'], {
+        cwd: BUNDLES_DIR,
+        stdio: 'inherit',
+      });
+    } catch (error) {
+      fail(`zip failed for ${bundle.slug}: ${error.message}`);
+    }
+
+    const size = (fs.statSync(out).size / 1024).toFixed(1);
+    console.log(`  [OK] ${bundle.slug}.zip (${size} KB)`);
+    zipped.push(bundle.slug);
+  }
+
+  if (invalid.length > 0) {
+    fail(`Refusing to publish: ${invalid.length} bundle(s) have invalid slugs: ${invalid.join(', ')}`);
+  }
+  if (missing.length > 0) {
+    fail(`Refusing to publish an incomplete release: missing directories for ${missing.join(', ')}`);
+  }
+  if (zipped.length === 0) {
+    fail('No bundles were packaged. Check bundles.json against web-bundles/ subdirectories.');
+  }
+
+  console.log(`\nWrote ${zipped.length} bundles to ${path.relative(REPO_ROOT, DIST_DIR)}/`);
+  console.log('\nNext step — create or update the GitHub Release:\n');
+  console.log(`  gh release create ${releaseTag} dist/web-bundles/*.zip \\`);
+  console.log(`    --title "${releaseTag}" \\`);
+  console.log(`    --notes "BMad web bundles for Gemini Gems and ChatGPT Custom GPTs. See https://bmadcode.com/web-bundles/"\n`);
+  console.log('Or, to refresh an existing release:\n');
+  console.log(`  gh release upload ${releaseTag} dist/web-bundles/*.zip --clobber\n`);
+}
+
+main();

package/tools/installer/modules/custom-module-manager.js

@@ -19,6 +19,10 @@ function quoteCustomRef(ref) {
 class CustomModuleManager {
   /** @type {Map<string, Object>} Shared across all instances: module code -> ResolvedModule */
   static _resolutionCache = new Map();
+  /** @type {Set<string>} Repo roots refreshed in the current process (dedupe quick-update fetches). */
+  static _refreshedRepoPaths = new Set();
+  /** @type {Map<string, Promise<void>>} In-flight refresh operations keyed by repo path. */
+  static _refreshInFlight = new Map();
 
   // ─── Source Parsing ───────────────────────────────────────────────────────
 
@@ -111,7 +115,7 @@ class CustomModuleManager {
     }
 
     // SSH URL: git@host:owner/repo.git
-    const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    const sshMatch = trimmed.match(/^git@([^:]+):(.+?)\/([^/.]+?)(?:\.git)?$/);
     if (sshMatch) {
       const [, host, owner, repo] = sshMatch;
       return {
@@ -424,15 +428,39 @@ class CustomModuleManager {
             stdio: ['ignore', 'pipe', 'pipe'],
           });
         } else {
-          execSync('git reset --hard origin/HEAD', {
+          // Resolve the default branch (origin/HEAD) and fetch it explicitly.
+          // With shallow clones, `origin/HEAD` is stale and `git reset --hard
+          // origin/HEAD` never picks up new commits on the default branch.
+          let defaultBranch = 'main';
+          try {
+            defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD --short', {
+              cwd: repoCacheDir,
+              stdio: 'pipe',
+            })
+              .toString()
+              .trim()
+              .replace('origin/', '');
+          } catch {
+            // Fallback if origin/HEAD is not set
+          }
+          execSync(`git fetch --depth 1 origin ${quoteCustomRef(defaultBranch)}`, {
+            cwd: repoCacheDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          });
+          execSync(`git reset --hard origin/${quoteCustomRef(defaultBranch)}`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
           });
         }
         fetchSpinner.stop(`Updated ${displayName}`);
       } catch {
-        fetchSpinner.error(`Update failed, re-downloading ${displayName}`);
-        await fs.remove(repoCacheDir);
+        // Fetch failed against an existing cache — most often the remote is
+        // unreachable (network down, repo deleted/moved, auth revoked).
+        // Preserve the previous clone so re-deploy still works from cached
+        // content; surface a warning so the user knows the cache is stale.
+        fetchSpinner.error(`Could not refresh ${displayName} — keeping cached copy`);
+        await prompts.log.warn(`Custom module ${displayName} was not refreshed (remote unreachable). Using cached copy.`);
       }
     }
 
@@ -466,6 +494,32 @@ class CustomModuleManager {
     } catch {
       // swallow — a non-git repo (local path) wouldn't reach here anyway
     }
+    // Best-effort: capture the remote default branch name so channel marker
+    // metadata for "next" reflects the actual tracked ref (not always "main").
+    let defaultRef = 'main';
+    if (!effectiveVersion) {
+      try {
+        const symbolic = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+          cwd: repoCacheDir,
+          stdio: 'pipe',
+        })
+          .toString()
+          .trim();
+        if (symbolic.startsWith('origin/')) {
+          defaultRef = symbolic.slice('origin/'.length) || defaultRef;
+        }
+      } catch {
+        // Fallback to previous marker value when symbolic ref is unavailable.
+        try {
+          const existingMarker = await fs.readJson(path.join(repoCacheDir, '.bmad-channel.json'));
+          if (existingMarker?.channel === 'next' && typeof existingMarker.version === 'string' && existingMarker.version.trim()) {
+            defaultRef = existingMarker.version.trim();
+          }
+        } catch {
+          // Keep default fallback.
+        }
+      }
+    }
 
     // Write source metadata for later URL reconstruction
     const metadataPath = path.join(repoCacheDir, '.bmad-source.json');
@@ -478,6 +532,15 @@ class CustomModuleManager {
       sha: resolvedSha,
       clonedAt: new Date().toISOString(),
     });
+    // Keep a channel marker in custom cache too so update paths that rely on
+    // channel metadata (same as official-module cache) can treat this clone as
+    // refreshable. URL + no explicit ref => next, explicit ref => pinned.
+    await fs.writeJson(path.join(repoCacheDir, '.bmad-channel.json'), {
+      channel: effectiveVersion ? 'pinned' : 'next',
+      version: effectiveVersion || defaultRef,
+      sha: resolvedSha,
+      writtenAt: new Date().toISOString(),
+    });
 
     // Install dependencies if package.json exists (skip during browsing/analysis)
     const packageJsonPath = path.join(repoCacheDir, 'package.json');
@@ -642,6 +705,13 @@ class CustomModuleManager {
       const repoRoots = await this._findCacheRepoRoots(cacheDir);
 
       for (const { repoPath, metadata } of repoRoots) {
+        // Quick-update path: refresh URL-backed cached repos before reading
+        // files from them so re-deploy uses latest commits for `next` and
+        // the pinned ref for `pinned`.
+        if (options.bmadDir && metadata?.rawInput) {
+          await this._refreshRepoCacheOnce(repoPath, metadata);
+        }
+
         // Check marketplace.json for matching module code
         const marketplacePath = path.join(repoPath, '.claude-plugin', 'marketplace.json');
         if (!(await fs.pathExists(marketplacePath))) continue;
@@ -692,6 +762,45 @@ class CustomModuleManager {
     return this._findLocalSourceFromManifest(moduleCode, options);
   }
 
+  /**
+   * Refresh one cached repo at most once per process with in-flight dedupe.
+   * Prevents concurrent quick-update callers from racing the same cache path.
+   * @param {string} repoPath - Absolute cache repo path
+   * @param {Object} metadata - Parsed .bmad-source.json metadata
+   */
+  async _refreshRepoCacheOnce(repoPath, metadata) {
+    if (CustomModuleManager._refreshedRepoPaths.has(repoPath)) return;
+
+    const existing = CustomModuleManager._refreshInFlight.get(repoPath);
+    if (existing) {
+      await existing;
+      return;
+    }
+
+    const refreshPromise = (async () => {
+      try {
+        await this.cloneRepo(metadata.rawInput, {
+          silent: true,
+          pinOverride: metadata.version || undefined,
+        });
+        CustomModuleManager._refreshedRepoPaths.add(repoPath);
+      } catch (error_) {
+        // cloneRepo only throws here for unrecoverable cases (no cache present
+        // and a fresh clone failed, or an unexpected internal error). The
+        // common "remote unreachable but cache exists" case is handled inside
+        // cloneRepo, which preserves the clone and returns normally. Reaching
+        // this catch means we have no usable cache — surface a warning so the
+        // failure isn't silent.
+        await prompts.log.warn(`Refresh of cached custom module at ${path.basename(repoPath)} failed: ${error_?.message || error_}`);
+      } finally {
+        CustomModuleManager._refreshInFlight.delete(repoPath);
+      }
+    })();
+
+    CustomModuleManager._refreshInFlight.set(repoPath, refreshPromise);
+    await refreshPromise;
+  }
+
   /**
    * Check the installation manifest for a localPath entry for this module.
    * Used as fallback when the module was installed from a local source (no cache entry).

package/tools/installer/modules/official-modules.js

@@ -846,11 +846,35 @@ class OfficialModules {
       return false;
     }
 
-    // Dynamically discover all installed modules by scanning bmad directory
-    // A directory is a module ONLY if it contains a config.yaml file
+    // Primary source: installer-written config.toml + config.user.toml (v6+).
+    // Both files together hold all install answers; config.user.toml carries
+    // user-scoped keys like user_name that would otherwise be re-prompted on
+    // every reinstall.
     let foundAny = false;
-    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
+    for (const fileName of ['config.toml', 'config.user.toml']) {
+      const tomlPath = path.join(bmadDir, fileName);
+      if (!(await fs.pathExists(tomlPath))) continue;
+      try {
+        const content = await fs.readFile(tomlPath, 'utf8');
+        const parsed = parseCentralToml(content);
+        for (const [section, values] of Object.entries(parsed)) {
+          if (values && typeof values === 'object' && !Array.isArray(values)) {
+            if (!this._existingConfig[section]) this._existingConfig[section] = {};
+            Object.assign(this._existingConfig[section], values);
+            foundAny = true;
+          }
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    }
 
+    if (foundAny) {
+      return true;
+    }
+
+    // Fallback: legacy per-module config.yaml files (pre-v6 installations).
+    const entries = await fs.readdir(bmadDir, { withFileTypes: true });
     const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
     for (const entry of entries) {
       if (entry.isDirectory()) {
@@ -2127,4 +2151,60 @@ class OfficialModules {
   }
 }
 
+/**
+ * Parse a config.toml or config.user.toml written by writeCentralConfig.
+ * Only handles the subset of TOML the installer produces: [core],
+ * [modules.<code>], string/bool/number scalar values. [agents.*] and other
+ * sections are ignored. Returns a plain object keyed by section name where
+ * module sections use the bare code (e.g. "bmm"), not the full "modules.bmm".
+ */
+function parseCentralToml(content) {
+  const result = {};
+  let currentSection = null;
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    const sectionMatch = line.match(/^\[([^\]]+)\]\s*$/);
+    if (sectionMatch) {
+      const name = sectionMatch[1];
+      if (name === 'core') {
+        currentSection = 'core';
+      } else if (name.startsWith('modules.')) {
+        currentSection = name.slice('modules.'.length);
+      } else {
+        currentSection = null;
+      }
+      if (currentSection && !result[currentSection]) {
+        result[currentSection] = {};
+      }
+      continue;
+    }
+
+    if (!currentSection) continue;
+
+    const kvMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(.+)$/);
+    if (!kvMatch) continue;
+
+    const key = kvMatch[1];
+    const raw = kvMatch[2].trim();
+    let value;
+    if (raw.startsWith('"') && raw.endsWith('"')) {
+      value = raw.slice(1, -1).replaceAll(/\\(["\\nrbt])/g, (_, c) => ({ '"': '"', '\\': '\\', n: '\n', r: '\r', b: '\b', t: '\t' })[c]);
+    } else if (raw === 'true') {
+      value = true;
+    } else if (raw === 'false') {
+      value = false;
+    } else if (raw !== '' && !isNaN(raw)) {
+      value = Number(raw);
+    } else {
+      value = raw;
+    }
+    result[currentSection][key] = value;
+  }
+
+  return result;
+}
+
 module.exports = { OfficialModules };

package/tools/skill-validator.md

@@ -10,7 +10,7 @@ Before running inference-based validation, run the deterministic validator:
 node tools/validate-skills.js --json path/to/skill-dir
 ```
 
-This checks 14 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, WF-01, WF-02, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
+This checks 12 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
 
 Review its JSON output. For any rule that produced **zero findings** in the first pass, **skip it** during inference-based validation below — it has already been verified. If a rule produced any findings, the inference validator should still review that rule (some rules like SKILL-04 and SKILL-06 have sub-checks that benefit from judgment). Focus your inference effort on the remaining rules that require judgment (PATH-01, PATH-03, PATH-04, PATH-05, WF-03, STEP-02, STEP-03, STEP-04, STEP-05, SEQ-01, REF-01, REF-02, REF-03).
 
@@ -98,24 +98,6 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
-### WF-01 — Only SKILL.md May Have `name` in Frontmatter
-
-- **Severity:** HIGH
-- **Applies to:** all `.md` files except `SKILL.md`
-- **Rule:** The `name` field belongs only in `SKILL.md`. No other markdown file in the skill directory may have `name:` in its frontmatter.
-- **Detection:** Parse frontmatter of every non-SKILL.md markdown file and check for `name:` key.
-- **Fix:** Remove the `name:` line from the file's frontmatter.
-- **Exception:** `bmad-agent-tech-writer` — has sub-skill files with intentional `name` fields (to be revisited).
-
-### WF-02 — Only SKILL.md May Have `description` in Frontmatter
-
-- **Severity:** HIGH
-- **Applies to:** all `.md` files except `SKILL.md`
-- **Rule:** The `description` field belongs only in `SKILL.md`. No other markdown file in the skill directory may have `description:` in its frontmatter.
-- **Detection:** Parse frontmatter of every non-SKILL.md markdown file and check for `description:` key.
-- **Fix:** Remove the `description:` line from the file's frontmatter.
-- **Exception:** `bmad-agent-tech-writer` — has sub-skill files with intentional `description` fields (to be revisited).
-
 ### WF-03 — workflow.md Frontmatter Variables Must Be Config or Runtime Only
 
 - **Severity:** HIGH