ma-agents 3.6.1 → 3.8.0

package/lib/installer.js

@@ -3,6 +3,9 @@ const path = require('path');
 const chalk = require('chalk');
 const prompts = require('prompts');
 const { getAgent, getAllAgents } = require('./agents');
+// Story 22.8 — reuse the canonical stage-directory name so the gitignore policy
+// stays in lock-step with lib/bmad.js#stagePlugin / cleanupStage.
+const { PLUGIN_STAGE_DIR_NAME } = require('./bmad');
 
 const MANIFEST_FILE = '.ma-agents.json';
 const MANIFEST_VERSION = '1.2.0';
@@ -145,6 +148,7 @@ function composeInstructionBlock({ profile, projectRoot } = {}) {
 
 /**
  * Story 21.4 AC #10 — resolve BMAD output directories once per install.
+ * Story 22.7 — reads the canonical v6.3.0 config at `_bmad/bmm/config.yaml`.
  *
  * Precedence:
  *   a) If `_bmad/bmm/config.yaml` exists AND has explicit `planning_artifacts`,
@@ -154,6 +158,12 @@ function composeInstructionBlock({ profile, projectRoot } = {}) {
  *        architecture:   _bmad-output/planning-artifacts (co-located default)
  *        stories:        _bmad-output/implementation-artifacts
  *
+ * This resolver NEVER consults the legacy `_bmad/_config/manifest.yaml`.
+ * If a legacy install is present without the canonical file, the defaults
+ * are used; the install flow (`lib/bmad.js::installBmad`) invokes
+ * `ensureCanonicalConfigLocation()` earlier so bmad-method regenerates the
+ * canonical layout during the install that triggered this call.
+ *
  * YAML parsing is intentionally minimal — we only need a handful of
  * top-level scalar keys. Adding a full YAML dependency just for this is
  * overkill and would widen the supply chain for one helper.
@@ -269,6 +279,101 @@ function ensureBmadOutputTracked(projectRoot) {
   console.log(chalk.green('_bmad-output is now tracked as project knowledge (not gitignored)'));
 }
 
+// Story 22.8 — plugin-stage directory gitignore policy.
+//
+// Sister-policy to BMAD_OUTPUT_PATTERNS above. `_bmad-output/` is intentionally
+// NOT gitignored (it holds tracked project knowledge); by contrast the
+// project-local plugin stage (`<projectRoot>/.ma-agents-plugin-stage/`, see
+// lib/bmad.js#stagePlugin) is a transient install artifact that should NEVER
+// be committed. Both forms (trailing / or not) match the directory per git's
+// pathspec rules, and the leading-slash variants anchor to the project root.
+const PLUGIN_STAGE_PATTERNS = [
+  PLUGIN_STAGE_DIR_NAME,                  // .ma-agents-plugin-stage
+  `${PLUGIN_STAGE_DIR_NAME}/`,            // .ma-agents-plugin-stage/
+  `/${PLUGIN_STAGE_DIR_NAME}`,            // /.ma-agents-plugin-stage
+  `/${PLUGIN_STAGE_DIR_NAME}/`,           // /.ma-agents-plugin-stage/
+];
+
+// Canonical entry we write when the pattern is absent — trailing slash makes
+// the "directory-only" intent explicit for human readers.
+const PLUGIN_STAGE_CANONICAL_ENTRY = `${PLUGIN_STAGE_DIR_NAME}/`;
+
+/**
+ * Ensure `.ma-agents-plugin-stage/` is present in the target project's
+ * `.gitignore`. Append-only and idempotent:
+ *
+ *  - If `.gitignore` is absent, create it with the single canonical entry.
+ *  - If any active (non-comment) line already matches any PLUGIN_STAGE_PATTERNS
+ *    variant, do nothing.
+ *  - Otherwise, append `PLUGIN_STAGE_CANONICAL_ENTRY` preserving the file's
+ *    existing line endings (CRLF vs LF) and guaranteeing a trailing newline
+ *    so the new entry is not concatenated to the previous line.
+ *
+ * Unrelated lines are never modified — this is strictly additive. Commented
+ * variants (lines starting with `#`) are ignored for the "already present"
+ * check, matching git's own semantics.
+ *
+ * F2a contract — the caller MUST pass the **project root** (the directory
+ * that contains the target project's top-level `.gitignore`), NOT a per-agent
+ * skills install path (e.g., `.claude/skills/`). Earlier (pre-F2a) the call
+ * site in `installSkill()` passed `installPath`, which produced per-skill-dir
+ * `.gitignore` files instead of one project-root file. The fix moved the
+ * single invocation next to `stagePlugin(projectRoot)` in `lib/bmad.js`.
+ *
+ * Defensive behavior — if `projectRoot` is falsy or not a string, this
+ * function is a no-op. The `ensurePluginStageGitignoredForProject()` helper
+ * in `lib/bmad.js` is the canonical caller; this guard exists so a stray
+ * call from misconfigured tests or third-party code cannot accidentally write
+ * to `cwd`.
+ *
+ * @param {string} projectRoot - Absolute path to the target project.
+ */
+function ensurePluginStageIgnored(projectRoot) {
+  // F2a — defensive guard: reject undefined/null/non-string input rather than
+  // silently writing to `path.join(undefined, '.gitignore')` (which throws on
+  // older Node) or to whatever `path.join('')` resolves to (cwd).
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return;
+  }
+
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  let content = '';
+  let fileExists = true;
+  try {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    fileExists = false;
+  }
+
+  if (fileExists) {
+    const alreadyPresent = content.split(/\r?\n/).some(rawLine => {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) return false; // skip blanks & comments
+      return PLUGIN_STAGE_PATTERNS.includes(line);
+    });
+    if (alreadyPresent) return; // idempotent no-op
+  }
+
+  // Preserve the file's existing line-ending style; default to LF for new files.
+  const usesCrlf = fileExists && /\r\n/.test(content);
+  const eol = usesCrlf ? '\r\n' : '\n';
+
+  let next = content;
+  if (next && !next.endsWith('\n') && !next.endsWith('\r\n')) {
+    next += eol; // ensure the append lands on its own line
+  }
+  next += PLUGIN_STAGE_CANONICAL_ENTRY + eol;
+
+  fs.writeFileSync(gitignorePath, next, 'utf-8');
+  console.log(
+    chalk.green(
+      `${PLUGIN_STAGE_CANONICAL_ENTRY} added to .gitignore (transient plugin stage — safe to ignore)`
+    )
+  );
+}
+
 function ensureManifest(installPath, agentId, scope) {
   let manifest = readManifest(installPath);
   if (!manifest) {
@@ -1335,6 +1440,14 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
         };
         writeManifest(installPath, manifest);
         ensureBmadOutputTracked(installPath);
+        // F2a — the plugin-stage gitignore policy was previously applied here
+        // with `installPath` (the per-agent skills directory), which produced
+        // per-skill-dir `.gitignore` files instead of one project-root file.
+        // The single invocation now lives next to `stagePlugin(projectRoot)` in
+        // `lib/bmad.js` (see `ensurePluginStageGitignoredForProject` callers in
+        // installBmad / runMigration / updateBmad). Story 22.8 AC #1 / AC #5
+        // are satisfied at the project-root level; the per-agent path here
+        // would never have been the correct write target.
 
         // Generate MANIFEST.yaml and update instruction files for ALL agents
         await generateSkillsManifest(installPath);
@@ -1352,10 +1465,17 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
             await deployClaudeCodeHook(process.cwd());
           }
           // Generate project-context.md on first install; update manifest paths on subsequent installs.
+          // Bug B2 — also run obsolete-tool-dir cleanup on the first successful path-group iteration.
           // Guard: runs at most once per installSkill() call — pathGroups may have multiple entries
-          // when agents share install paths, so without this flag generation would fire redundantly.
+          // when agents share install paths, so without this flag these would fire redundantly.
           if (!projectContextHandled) {
             projectContextHandled = true;
+            // Bug B2 — clean up stale tool-level skill directories left by earlier routing migrations.
+            try {
+              await migrateObsoleteToolDirs(process.cwd());
+            } catch (err) {
+              console.log(chalk.yellow(`⚠ obsolete-tool-dir cleanup failed: ${err.message} — continuing install`));
+            }
             const projectRoot = process.cwd();
             const outputPath = path.join(projectRoot, '_bmad-output', 'project-context.md');
             const allAgents = getManifestAgents(manifest).map(id => getAgent(id)).filter(Boolean);
@@ -1394,6 +1514,235 @@ async function performUninstall(skillId, installPath) {
   }
 }
 
+/**
+ * Story 22.3 / 22.2 — Legacy skill retirement + rename migration (AC 7).
+ *
+ * BMAD v6.3.0 retired four upstream skills:
+ *   - bmad-init                         (upstream PR #2159 — agents read _bmad/bmm/config.yaml directly)
+ *   - bmad-agent-qa                     (Quinn — merged into Amelia in PR #2186)
+ *   - bmad-agent-sm                     (Bob   — merged into Amelia in PR #2179)
+ *   - bmad-agent-quick-flow-solo-dev    (Barry — merged into Amelia in PR #2177)
+ *
+ * Story 22.2 additionally renamed the five ma-agents custom-agent skills out of
+ * the upstream-reserved `bmad-*` prefix:
+ *   - bmad-ma-agent-cyber   → ma-agent-cyber
+ *   - bmad-ma-agent-devops  → ma-agent-devops
+ *   - bmad-ma-agent-sre     → ma-agent-sre
+ *   - bmad-ma-agent-ml      → ma-agent-ml
+ *   - bmad-ma-agent-sqa     → ma-agent-sqa
+ *
+ * Both retirements and renames produce the same stale-artifact problem: existing
+ * ma-agents installs may still carry the old IDs in `.ma-agents.json` and still
+ * have the old folders deployed under each agent's skill root. This helper sweeps
+ * every agent install path and, for every obsolete ID (retired or renamed):
+ *   1. removes the ID from the manifest's `skills` map
+ *   2. deletes the installed skill directory under the agent's skill root
+ *   3. regenerates MANIFEST.yaml so the deployed manifest drops the obsolete IDs
+ *
+ * The follow-up install step re-adds the renamed skills under their new IDs, so
+ * users effectively see a one-shot upgrade — no manual cleanup, no dangling
+ * duplicates. The migration is idempotent — running it again on a clean install
+ * is a no-op.
+ *
+ * Returns the list of per-path migration actions (for testability and logging).
+ */
+const RETIRED_SKILL_IDS = Object.freeze([
+  'bmad-init',
+  'bmad-agent-qa',
+  'bmad-agent-sm',
+  'bmad-agent-quick-flow-solo-dev'
+]);
+
+// Skills that were renamed (not retired). The new ID is installed fresh by
+// the regular install flow after migration clears the old ID.
+const RENAMED_SKILL_IDS = Object.freeze([
+  'bmad-ma-agent-cyber',
+  'bmad-ma-agent-devops',
+  'bmad-ma-agent-sre',
+  'bmad-ma-agent-ml',
+  'bmad-ma-agent-sqa'
+]);
+
+// Union of every obsolete ID the sweep must purge from existing installs.
+// Kept as a frozen array so accidental mutation is surfaced at test time.
+const OBSOLETE_SKILL_IDS = Object.freeze([...RETIRED_SKILL_IDS, ...RENAMED_SKILL_IDS]);
+
+// Registry of old tool-level skill directories that earlier ma-agents versions
+// wrote to but no longer use. Each entry describes one migration:
+//   obsolete     — the legacy path (relative to project root)
+//   replacedBy   — the current path that skills are now written to
+//   sinceVersion — the ma-agents release that made the change (informational)
+//
+// Story 24.11 (AC5) will add additional entries to this list when .agents/skills/
+// cross-tool routing is assessed. Define new entries here; `migrateObsoleteToolDirs`
+// iterates the registry automatically.
+//
+// Kept frozen so accidental mutation is surfaced at test time.
+const OBSOLETE_TOOL_SKILL_DIRS = Object.freeze([
+  // Pre-F2b (PR #70) copilot wrote skills to .github/copilot/skills;
+  // F2b realigned the target to .github/skills to match the BMAD upstream path.
+  { obsolete: '.github/copilot/skills', replacedBy: '.github/skills', sinceVersion: '3.7.0' }
+]);
+
+async function migrateRetiredSkills(options = {}) {
+  const { scope = 'project', customPath = '' } = options;
+  const results = [];
+
+  // Build the list of install paths to sweep. We consider every registered
+  // agent for the requested scope — the retirement/rename is agent-agnostic.
+  const pathsSeen = new Set();
+  const targetPaths = [];
+
+  if (customPath) {
+    targetPaths.push(customPath);
+  } else {
+    for (const agent of getAllAgents()) {
+      const p = scope === 'global' ? agent.getGlobalPath() : agent.getProjectPath();
+      if (p && !pathsSeen.has(p)) {
+        pathsSeen.add(p);
+        targetPaths.push(p);
+      }
+    }
+  }
+
+  for (const installPath of targetPaths) {
+    let manifestMutated = false;
+    let filesRemoved = 0;
+    const removedIds = [];
+    let pathError = null;
+
+    try {
+      // Read manifest (if any). Missing manifest is fine — we still check for
+      // orphaned skill directories left behind by a partial uninstall.
+      const manifest = readManifest(installPath);
+
+      for (const obsoleteId of OBSOLETE_SKILL_IDS) {
+        // 1. Manifest entry cleanup
+        if (manifest && manifest.skills && Object.prototype.hasOwnProperty.call(manifest.skills, obsoleteId)) {
+          delete manifest.skills[obsoleteId];
+          manifestMutated = true;
+          removedIds.push(obsoleteId);
+        }
+
+        // 2. Installed-directory cleanup — guard against ENOENT (idempotency)
+        const skillDir = path.join(installPath, obsoleteId);
+        if (fs.existsSync(skillDir)) {
+          try {
+            await fs.remove(skillDir);
+            filesRemoved++;
+            if (!removedIds.includes(obsoleteId)) {
+              removedIds.push(obsoleteId);
+            }
+          } catch (err) {
+            // Non-fatal — surface the path so the user can clean up manually.
+            console.log(chalk.yellow(`    ! Could not remove ${skillDir}: ${err.message}`));
+          }
+        }
+      }
+
+      if (manifestMutated) {
+        writeManifest(installPath, manifest);
+      }
+
+      if (manifestMutated || filesRemoved > 0) {
+        // Regenerate the deployed MANIFEST.yaml so AC 1 is satisfied for
+        // existing installs — the file is derived from `.ma-agents.json::skills`.
+        if (manifest && manifest.skills) {
+          try {
+            await generateSkillsManifest(installPath);
+          } catch (err) {
+            console.log(chalk.yellow(`    ! MANIFEST.yaml regeneration skipped for ${installPath}: ${err.message}`));
+          }
+        }
+        console.log(chalk.green(
+          `  - Cleaned ${removedIds.length} obsolete skill(s) at ${installPath}: ${removedIds.join(', ')}`
+        ));
+      }
+    } catch (err) {
+      // Isolate per-path failures so one broken install path does not
+      // abort the sweep across all other agents.
+      pathError = err;
+      console.log(chalk.yellow(
+        `    ! Obsolete-skill migration failed for ${installPath}: ${err.message}`
+      ));
+    }
+
+    results.push({ installPath, removedIds, filesRemoved, manifestMutated, error: pathError });
+  }
+
+  return results;
+}
+
+/**
+ * Bug B2 — Stale copilot skills dir cleanup (and future obsolete tool-dir migrations).
+ *
+ * Iterates `OBSOLETE_TOOL_SKILL_DIRS` and, for each entry, checks whether the
+ * legacy directory exists under `projectRoot`. Behaviour per entry:
+ *
+ *   - Obsolete dir absent          → no-op (idempotent)
+ *   - Obsolete dir present AND
+ *     replacedBy dir has content   → remove obsolete dir, log info message
+ *   - Obsolete dir present BUT
+ *     replacedBy dir is empty/gone → preserve obsolete dir, log warning
+ *                                    (user may have local edits; safer to keep)
+ *
+ * @param {string} projectRoot — absolute path to the project root (process.cwd() in production)
+ * @returns {Promise<Array<{entry, action, obsoletePath, replacedByPath, error}>>}
+ */
+async function migrateObsoleteToolDirs(projectRoot) {
+  const results = [];
+
+  for (const entry of OBSOLETE_TOOL_SKILL_DIRS) {
+    const obsoletePath = path.join(projectRoot, entry.obsolete);
+    const replacedByPath = path.join(projectRoot, entry.replacedBy);
+    let action = 'noop';
+    let error = null;
+
+    try {
+      if (!fs.existsSync(obsoletePath)) {
+        // Nothing to do — already clean.
+        action = 'noop';
+      } else {
+        // Check whether the replacement directory has any content.
+        let replacedByHasContent = false;
+        if (fs.existsSync(replacedByPath)) {
+          const entries = fs.readdirSync(replacedByPath);
+          replacedByHasContent = entries.length > 0;
+        }
+
+        if (replacedByHasContent) {
+          // Safe to remove — skills have been migrated to the new location.
+          await fs.remove(obsoletePath);
+          action = 'removed';
+          console.log(chalk.green(
+            `  - Removed legacy tool skills directory ${entry.obsolete} ` +
+            `(moved to ${entry.replacedBy} in v${entry.sinceVersion})`
+          ));
+        } else {
+          // Replacement is absent or empty — do not silently destroy user content.
+          action = 'preserved';
+          console.log(chalk.yellow(
+            `  ! Legacy tool skills directory ${entry.obsolete} was not removed ` +
+            `because ${entry.replacedBy} is empty or absent. ` +
+            `Remove it manually once you have confirmed there is nothing to keep: ` +
+            `rm -rf ${entry.obsolete}`
+          ));
+        }
+      }
+    } catch (err) {
+      action = 'error';
+      error = err;
+      console.log(chalk.yellow(
+        `  ! Could not migrate obsolete tool dir ${entry.obsolete}: ${err.message}`
+      ));
+    }
+
+    results.push({ entry, action, obsoletePath, replacedByPath, error });
+  }
+
+  return results;
+}
+
 async function uninstallSkill(skillId, agentIds, customPath = '', scope = 'project') {
   console.log(chalk.cyan(`\nUninstalling skill: ${skillId}`));
 
@@ -1631,6 +1980,7 @@ module.exports = {
   deployClaudeCodeHook,
   removeClaudeCodeHook,
   ensureBmadOutputTracked,
+  ensurePluginStageIgnored,
   generateSkillsManifest,
   generateProjectContext,
   generateRepoLayoutSection,
@@ -1653,5 +2003,15 @@ module.exports = {
   // Story 21.5 — Cline dual-file drift detection + framing template path.
   CLINERULES_TEMPLATE_PATH,
   ClinerulesDualFileDriftError,
-  checkClinerulesDualFileDrift
+  checkClinerulesDualFileDrift,
+  // Story 22.3 — legacy skill retirement migration (AC 7)
+  // Story 22.2 — extended to also sweep renamed skill IDs (bmad-ma-agent-*)
+  migrateRetiredSkills,
+  RETIRED_SKILL_IDS,
+  RENAMED_SKILL_IDS,
+  OBSOLETE_SKILL_IDS,
+  // Bug B2 — stale copilot skills dir cleanup + future tool-dir migrations.
+  // Story 24.11 (AC5) will extend OBSOLETE_TOOL_SKILL_DIRS with additional entries.
+  OBSOLETE_TOOL_SKILL_DIRS,
+  migrateObsoleteToolDirs
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.6.1",
+  "version": "3.8.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,8 +8,10 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/bmad-version-bump.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/agents-md.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js",
-    "build:bmad-cache": "node scripts/build-bmad-cache.js"
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/bmad-version-bump.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js",
+    "build:bmad-cache": "node scripts/build-bmad-cache.js",
+    "build:plugin": "node scripts/build-plugin.js",
+    "prepare": "node scripts/build-plugin.js"
   },
   "keywords": [
     "ai",
@@ -27,12 +29,28 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "bmad-method": "6.2.2",
+    "bmad-method": "6.5.0",
     "prompts": "^2.4.2",
     "chalk": "^4.1.2",
     "fs-extra": "^11.1.1",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "^4.1.1",
+    "yaml": "^2.8.2"
   },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "skills/",
+    "docs/",
+    "examples/",
+    "mil498/",
+    "index.js",
+    "README.md",
+    "SKILLS_STRUCTURE.md",
+    "CONTRIBUTING.md",
+    "QUICK_START.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=16.0.0"
   }