ma-agents 3.12.3 → 3.13.1

package/lib/bmad.js

@@ -1,7 +1,8 @@
 const fs = require('fs-extra');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
+const { pathToFileURL } = require('url');
 const chalk = require('chalk');
 const yaml = require('yaml');
 const jsYaml = require('js-yaml');
@@ -277,17 +278,34 @@ function ensurePluginStageGitignoredForProject(projectRoot) {
         console.warn(chalk.yellow(`  Warning: could not load installer for gitignore policy: ${err.message}`));
         return;
     }
-    if (typeof installer.ensurePluginStageIgnored !== 'function') return;
-    try {
-        installer.ensurePluginStageIgnored(projectRoot);
-    } catch (err) {
-        // EACCES on read-only `.gitignore`, EROFS on read-only filesystem, etc.
-        // Logged so the operator can fix it manually; never fatal to the install.
-        console.warn(
-            chalk.yellow(
-                `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with plugin-stage entry: ${err.message}`
-            )
-        );
+    if (typeof installer.ensurePluginStageIgnored === 'function') {
+        try {
+            installer.ensurePluginStageIgnored(projectRoot);
+        } catch (err) {
+            // EACCES on read-only `.gitignore`, EROFS on read-only filesystem, etc.
+            // Logged so the operator can fix it manually; never fatal to the install.
+            console.warn(
+                chalk.yellow(
+                    `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with plugin-stage entry: ${err.message}`
+                )
+            );
+        }
+    }
+
+    // Bug 27.11 — also ensure the regenerated, installer-managed `_bmad/` tree is
+    // gitignored. Same project-root contract and same non-fatal failure policy as
+    // the plugin-stage entry above. `_bmad-output/` is intentionally left tracked
+    // (see ensureBmadOutputTracked) and is not matched by these patterns.
+    if (typeof installer.ensureBmadDirIgnored === 'function') {
+        try {
+            installer.ensureBmadDirIgnored(projectRoot);
+        } catch (err) {
+            console.warn(
+                chalk.yellow(
+                    `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with _bmad/ entry: ${err.message}`
+                )
+            );
+        }
     }
 }
 
@@ -471,7 +489,7 @@ const BMAD_MODULE_DESCRIPTIONS = Object.freeze({
     cis: 'Creative Intelligence Suite — innovation and ideation toolkit',
     gds: 'Game Dev Studio — game development workflows',
     tea: 'Test Architecture Enterprise — Test Architect (Murat) + 9 testarch workflows',
-    wds: 'Web Dev Studio — retired upstream',
+    wds: 'Whiteport Design Studio — strategic UX and design-first planning',
 });
 
 /**
@@ -481,7 +499,9 @@ const BMAD_MODULE_DESCRIPTIONS = Object.freeze({
  * the optional external modules (bmb, cis, gds, tea, wds, ...).
  *
  * Each entry carries a `retired` flag so the caller can hide modules that
- * have been retired upstream (e.g. wds).
+ * have been retired upstream (driven by the manifest's `retiredUpstream`
+ * marker; at v6.8.0 the bundled set — tea, bmb, cis, gds, wds — are all
+ * active `type: bmad-org` clones, so none are flagged).
  *
  * If the cache manifest is missing or unreadable, falls back to a list
  * containing only `bmm` — that's the minimum a successful install needs.
@@ -844,6 +864,11 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
     try {
         runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
         bmadInvokeSucceeded = true;
+        // Bug 27.14 — repair any module artifact path that upstream's
+        // suffix-match output-folder resolution contaminated (e.g. gds paths
+        // pinned to bmb's "skills" instead of the chosen output folder). Runs
+        // after bmad-method writes the config and before downstream consumers.
+        normalizeModuleOutputFolders(projectRoot);
         // F1a — on-prem persona phase-prefix pass. Runs BEFORE
         // deployMethodology so a methodology-deploy failure doesn't prevent
         // the prefix from being applied (they are independent concerns).
@@ -950,6 +975,10 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
         return false;
     }
 
+    // Bug 27.14 — repair contaminated module artifact paths on the migration
+    // path too (same upstream suffix-match resolution applies to updates).
+    normalizeModuleOutputFolders(projectRoot);
+
     // Step 3: Merge user customizations
     if (backedUpFiles.length > 0) {
         console.log(chalk.cyan('  Step 3/4: Merging user customizations...'));
@@ -1472,10 +1501,42 @@ async function deployMethodology(projectRoot = process.cwd(), force = false) {
     console.log(chalk.gray('  Tip: Use /open-presentation to open the slides (install via npx ma-agents install open-presentation)'));
 }
 
+/**
+ * Detect whether a `.clinerules/workflows/*.md` file is a ma-agents-generated
+ * Cline workflow wrapper (as opposed to a user-authored file that happens to
+ * live in the same directory).
+ *
+ * Reconciliation (Story 27.4) deletes stale wrappers, so the matcher must be
+ * conservative: it returns `true` ONLY for the exact shape this function emits.
+ * Every generated wrapper contains a line that points the reader back into the
+ * backing skill via a `.cline/skills/<name>/` reference (either `SKILL.md` or
+ * `workflow.md`). User files under `.clinerules/` will not carry that marker,
+ * so they are never mistaken for wrappers and never deleted.
+ *
+ * @param {string} content - Raw UTF-8 contents of the candidate `.md` file.
+ * @returns {boolean} `true` if the content matches the generated-wrapper shape.
+ */
+function isGeneratedClineWrapper(content) {
+    if (typeof content !== 'string' || content.length === 0) return false;
+    // The generated-wrapper fingerprint: a body line that instructs the reader
+    // to read a file under `.cline/skills/<name>/` (SKILL.md or workflow.md).
+    // Matches forward-slashed paths only — that is exactly what we emit.
+    return /\.cline\/skills\/[^/\s`]+\/(?:SKILL|workflow)\.md/.test(content);
+}
+
 /**
  * Generate Cline workflow wrappers for all BMAD skills installed to .cline/skills/.
  * Creates .clinerules/workflows/<skill-name>.md for each installed skill so they
  * can be invoked via / commands in Cline chat.
+ *
+ * Reconciliation (Story 27.4): after (re)generating wrappers for all current
+ * skills, any stale wrapper under `.clinerules/workflows/` whose backing
+ * `.cline/skills/<name>/` directory no longer exists is removed. This keeps
+ * `/`-invocation in Cline from offering workflows for skills BMAD renamed away
+ * or retired. Deletion is scoped strictly to ma-agents-generated wrapper files
+ * (see {@link isGeneratedClineWrapper}); user-authored files elsewhere under
+ * `.clinerules/` are never touched, and the operation is idempotent.
+ *
  * No-op when 'cline' is not in the selected tools list.
  */
 async function deployClineWorkflows(projectRoot, tools = []) {
@@ -1502,6 +1563,10 @@ async function deployClineWorkflows(projectRoot, tools = []) {
     const entries = await fs.readdir(clineSkillsDir, { withFileTypes: true });
     const skillDirs = entries.filter(e => e.isDirectory());
 
+    // Live skill-name set: every `.cline/skills/<name>/` that backs a wrapper
+    // (i.e. contains a SKILL.md). Used below to reconcile stale wrappers.
+    const liveSkillNames = new Set();
+
     let generated = 0;
     for (const entry of skillDirs) {
         const skillName = entry.name;
@@ -1510,6 +1575,7 @@ async function deployClineWorkflows(projectRoot, tools = []) {
         const workflowMdPath = path.join(skillDir, 'workflow.md');
 
         if (!(await fs.pathExists(skillMdPath))) continue;
+        liveSkillNames.add(skillName);
 
         const skillMdContent = await fs.readFile(skillMdPath, 'utf8');
         let displayName = skillName.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
@@ -1546,10 +1612,47 @@ async function deployClineWorkflows(projectRoot, tools = []) {
         generated++;
     }
 
+    // Reconciliation (Story 27.4): remove stale wrappers whose backing skill
+    // dir no longer exists. Scope is strictly the generated-wrapper `.md` files
+    // directly inside `workflows/` — subdirectories and non-wrapper user files
+    // are left untouched.
+    let removed = 0;
+    const workflowEntries = await fs.readdir(workflowsDir, { withFileTypes: true });
+    for (const wf of workflowEntries) {
+        // Only top-level `.md` files are candidate wrappers. Skip directories
+        // and any non-markdown file outright.
+        if (!wf.isFile()) continue;
+        if (!wf.name.endsWith('.md')) continue;
+
+        const wrapperName = wf.name.slice(0, -'.md'.length);
+        // A wrapper whose name is still in the live set is current — keep it.
+        // (It was just (re)written above.)
+        if (liveSkillNames.has(wrapperName)) continue;
+
+        // Name is not backed by a live skill. Before deleting, confirm the file
+        // actually matches the ma-agents generated-wrapper shape so we never
+        // remove a user-authored `.md` that happens to share a stale name.
+        const wrapperPath = path.join(workflowsDir, wf.name);
+        let wrapperContent;
+        try {
+            wrapperContent = await fs.readFile(wrapperPath, 'utf8');
+        } catch {
+            // Unreadable (e.g. vanished mid-run) — nothing to reconcile.
+            continue;
+        }
+        if (!isGeneratedClineWrapper(wrapperContent)) continue;
+
+        await fs.remove(wrapperPath);
+        removed++;
+    }
+
     if (generated > 0) {
         console.log(chalk.green(`  ✓ Generated ${generated} Cline workflow wrappers in .clinerules/workflows/`));
         console.log(chalk.gray('  Tip: In Cline, type / to browse and invoke BMAD skills'));
     }
+    if (removed > 0) {
+        console.log(chalk.green(`  ✓ Removed ${removed} stale Cline workflow wrapper${removed === 1 ? '' : 's'} (backing skill no longer present)`));
+    }
 }
 
 /**
@@ -1731,6 +1834,237 @@ function readCanonicalBmadConfig(projectRoot) {
     }
 }
 
+// ── Bug 27.14 — output-folder propagation normalization ──────────────────────
+//
+// Upstream bmad-method's resolveConfigValue (official-modules.js) resolves the
+// `{output_folder}` token via a `endsWith('_output_folder')` suffix match over
+// all collected answers. When bmb (answer key `bmb_..._output_folder` = "skills")
+// and gds are co-installed, gds's `{output_folder}` resolves alphabetically to
+// bmb's "skills" value, so gds artifact paths become `{project-root}/skills/...`
+// instead of `{project-root}/_bmad-output/...`.
+//
+// ma-agents owns no part of that resolution (it lives in vendored node_modules),
+// so this is a post-install WORK-AROUND: after bmad-method writes the config,
+// re-read `[core] output_folder` and rewrite any contaminated module artifact
+// path back onto the canonical output folder. We deliberately scope the rewrite
+// to the well-known core artifact keys so we never touch a module's INTENTIONAL
+// own-folder values (e.g. bmb's `bmad_builder_output_folder = ".../skills"` or
+// wds's `design_artifacts = ".../design-artifacts"`).
+//
+// Upstream follow-up (do NOT edit node_modules here): patch resolveConfigValue
+// to require an exact `output_folder` / `core_output_folder` key instead of the
+// `endsWith` suffix match. Tracked as an upstream follow-up.
+
+// Artifact keys that must always live under `[core] output_folder`. These are
+// the canonical bmm/gds planning+implementation+architecture artifact keys plus
+// tea's test_artifacts. Module-specific own-folder keys (bmb_*_output_folder,
+// design_artifacts, project_knowledge, *_output sub-paths) are intentionally
+// excluded.
+const OUTPUT_FOLDER_ARTIFACT_KEYS = [
+    'planning_artifacts',
+    'architecture_artifacts',
+    'implementation_artifacts',
+    'test_artifacts',
+];
+
+/**
+ * Given an artifact path value and the canonical output folder, return a
+ * corrected value if the path's output-folder segment differs from the
+ * canonical one, or `null` if no change is needed.
+ *
+ * Handles both conventions:
+ *   - `{project-root}/<seg>/<suffix...>`  (config.toml style)
+ *   - `<seg>/<suffix...>`                 (config.yaml stripped style)
+ *
+ * The leading `<seg>` (the first path segment after an optional `{project-root}/`
+ * prefix) is the resolved output folder; if it !== `outputFolder` it is rewritten.
+ * Only single-segment output folders are handled (the bmad default), which covers
+ * the observed `skills` vs `_bmad-output` contamination.
+ */
+function correctArtifactPath(value, outputFolder) {
+    if (typeof value !== 'string' || !value) return null;
+    const ROOT = '{project-root}/';
+    let prefix = '';
+    let rest = value;
+    if (rest.startsWith(ROOT)) {
+        prefix = ROOT;
+        rest = rest.slice(ROOT.length);
+    }
+    const slash = rest.indexOf('/');
+    if (slash === -1) return null; // no segment/suffix split — leave as-is
+    const seg = rest.slice(0, slash);
+    const suffix = rest.slice(slash); // includes leading '/'
+    if (seg === outputFolder) return null; // already canonical
+    return `${prefix}${outputFolder}${suffix}`;
+}
+
+/**
+ * Rewrite contaminated artifact paths inside `_bmad/config.toml`. Returns the
+ * number of lines changed. Uses line-based editing (no TOML dependency) so we
+ * preserve comments, ordering, and formatting exactly.
+ */
+function normalizeTomlOutputFolders(tomlPath, outputFolder) {
+    if (!fs.existsSync(tomlPath)) return 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(tomlPath, 'utf-8');
+    } catch {
+        return 0;
+    }
+    const usesCrlf = /\r\n/.test(raw);
+    const eol = usesCrlf ? '\r\n' : '\n';
+    const lines = raw.split(/\r?\n/);
+    let changed = 0;
+    let inModuleSection = false;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
+        if (sectionMatch) {
+            const section = sectionMatch[1].trim();
+            inModuleSection = section.startsWith('modules.');
+            continue;
+        }
+        if (!inModuleSection) continue;
+
+        // key = "value"  (only quoted string values are artifact paths)
+        const kvMatch = line.match(/^(\s*)([A-Za-z0-9_]+)(\s*=\s*)"([^"]*)"(\s*(?:#.*)?)$/);
+        if (!kvMatch) continue;
+        const [, indent, key, eq, val, trailer] = kvMatch;
+        if (!OUTPUT_FOLDER_ARTIFACT_KEYS.includes(key)) continue;
+        const corrected = correctArtifactPath(val, outputFolder);
+        if (corrected === null) continue;
+        lines[i] = `${indent}${key}${eq}"${corrected}"${trailer}`;
+        changed++;
+    }
+
+    if (changed > 0) {
+        fs.writeFileSync(tomlPath, lines.join(eol), 'utf-8');
+    }
+    return changed;
+}
+
+/**
+ * Rewrite contaminated artifact paths inside a per-module `_bmad/<mod>/config.yaml`.
+ * Returns the number of keys changed. Uses js-yaml so we keep schema fidelity.
+ */
+function normalizeYamlOutputFolders(yamlPath, outputFolder) {
+    if (!fs.existsSync(yamlPath)) return 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(yamlPath, 'utf-8');
+    } catch {
+        return 0;
+    }
+    let doc;
+    try {
+        doc = yaml.parse(raw);
+    } catch {
+        return 0;
+    }
+    if (!doc || typeof doc !== 'object') return 0;
+
+    let changed = 0;
+    for (const key of OUTPUT_FOLDER_ARTIFACT_KEYS) {
+        if (typeof doc[key] !== 'string') continue;
+        const corrected = correctArtifactPath(doc[key], outputFolder);
+        if (corrected === null) continue;
+        doc[key] = corrected;
+        changed++;
+    }
+
+    if (changed > 0) {
+        // Preserve the leading comment header (everything up to the first
+        // non-comment, non-blank line) so the "Generated by BMAD installer"
+        // banner survives the rewrite.
+        const headerLines = [];
+        for (const l of raw.split(/\r?\n/)) {
+            if (l.trim() === '' || l.trimStart().startsWith('#')) {
+                headerLines.push(l);
+            } else {
+                break;
+            }
+        }
+        const header = headerLines.length > 0 ? headerLines.join('\n') + '\n' : '';
+        fs.writeFileSync(yamlPath, header + yaml.stringify(doc), 'utf-8');
+    }
+    return changed;
+}
+
+/**
+ * Bug 27.14 — post-install pass that re-points any contaminated module artifact
+ * path at the canonical `[core] output_folder`. Reads the output folder from
+ * `_bmad/config.toml` (the install-owned source of truth), then normalizes both
+ * `_bmad/config.toml` and every `_bmad/<mod>/config.yaml`.
+ *
+ * Idempotent and non-fatal: a second run finds nothing to change, and any I/O
+ * error is logged and swallowed (config normalization must never abort an
+ * otherwise-green install).
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {number} Total number of artifact paths rewritten (for tests/logging).
+ */
+function normalizeModuleOutputFolders(projectRoot) {
+    if (typeof projectRoot !== 'string' || !projectRoot) return 0;
+    const tomlPath = path.join(projectRoot, BMAD_DIR, 'config.toml');
+    if (!fs.existsSync(tomlPath)) return 0;
+
+    let tomlRaw;
+    try {
+        tomlRaw = fs.readFileSync(tomlPath, 'utf-8');
+    } catch {
+        return 0;
+    }
+
+    // Extract `[core] output_folder = "..."`. Only the value inside the [core]
+    // section counts; module sections may carry their own output_folder-like keys.
+    let outputFolder = null;
+    let inCore = false;
+    for (const line of tomlRaw.split(/\r?\n/)) {
+        const section = line.match(/^\s*\[([^\]]+)\]\s*$/);
+        if (section) {
+            inCore = section[1].trim() === 'core';
+            continue;
+        }
+        if (!inCore) continue;
+        const kv = line.match(/^\s*output_folder\s*=\s*"([^"]*)"/);
+        if (kv) {
+            outputFolder = kv[1].trim();
+            break;
+        }
+    }
+    if (!outputFolder) return 0; // nothing canonical to normalize against
+
+    let total = 0;
+    try {
+        total += normalizeTomlOutputFolders(tomlPath, outputFolder);
+
+        // Walk each `_bmad/<mod>/config.yaml`.
+        const bmadDir = path.join(projectRoot, BMAD_DIR);
+        let entries = [];
+        try {
+            entries = fs.readdirSync(bmadDir, { withFileTypes: true });
+        } catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const cfg = path.join(bmadDir, entry.name, 'config.yaml');
+            total += normalizeYamlOutputFolders(cfg, outputFolder);
+        }
+    } catch (err) {
+        console.warn(chalk.yellow(`  Warning: output-folder normalization skipped: ${err.message}`));
+        return total;
+    }
+
+    if (total > 0) {
+        console.log(chalk.green(
+            `  Normalized ${total} module artifact path(s) to output folder "${outputFolder}/" (bug 27.14 work-around)`
+        ));
+    }
+    return total;
+}
+
 /**
  * Migration shim: normalize the project layout so that canonical config lives
  * at `_bmad/bmm/config.yaml` (v6.3.0) instead of `_bmad/_config/manifest.yaml`
@@ -1793,7 +2127,7 @@ function ensureCanonicalConfigLocation(projectRoot) {
 
 // ── Migration constants ─────────────────────────────────────────────────────
 
-const BMAD_TARGET_VERSION = '6.6.0';
+const BMAD_TARGET_VERSION = '6.8.0';
 const BMAD_MIGRATION_THRESHOLD = '6.2.0'; // versions below this need migration
 const BACKUP_DIR_NAME = '.backup-pre-migration';
 
@@ -2733,10 +3067,15 @@ function restoreGitDir(moduleDir) {
     }
     fs.renameSync(preserved, gitDir);
 
-    // Point origin at the local directory so `git fetch origin` succeeds offline
+    // Point origin at the local directory so `git fetch origin` succeeds offline.
+    // Use pathToFileURL so a Windows absolute path becomes a well-formed
+    // `file:///C:/...` URL (three slashes) rather than `file://C:/...`, and so
+    // paths containing spaces or other reserved characters are percent-encoded.
+    // execFileSync (arg array) avoids shell interpolation — matching the rest of
+    // the codebase's git calls (see scripts/build-bmad-cache.js).
     try {
-        const localUrl = 'file://' + moduleDir.replace(/\\/g, '/');
-        execSync(`git remote set-url origin "${localUrl}"`, {
+        const localUrl = pathToFileURL(moduleDir).href;
+        execFileSync('git', ['remote', 'set-url', 'origin', localUrl], {
             cwd: moduleDir,
             stdio: 'pipe'
         });
@@ -2754,8 +3093,12 @@ module.exports = {
     prePopulateBmadCache,
     deployMethodology,
     deployClineWorkflows,
+    // Story 27.4 — exported for unit tests of stale-wrapper reconciliation
+    isGeneratedClineWrapper,
     // Story 22.7 — canonical config (_bmad/bmm/config.yaml) helpers
     readCanonicalBmadConfig,
+    normalizeModuleOutputFolders,
+    correctArtifactPath,
     ensureCanonicalConfigLocation,
     CANONICAL_CONFIG_REL,
     LEGACY_MANIFEST_REL,