ma-agents 3.12.3 → 3.13.1

package/lib/installer.js

@@ -12,6 +12,7 @@ const MANIFEST_VERSION = '1.2.0';
 const MA_AGENTS_SOURCE = 'ma-agents';
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'project-context.template.md');
 const UNIVERSAL_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-universal.template.md');
+const GIT_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-git.template.md');
 const ONPREM_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-onprem.template.md');
 const CLINERULES_TEMPLATE_PATH = path.join(__dirname, 'templates', 'clinerules.template.md');
 const EXTRA_TEMPLATE_DIR = path.join(__dirname, 'templates');
@@ -133,19 +134,44 @@ function composeInstructionBlock({ profile, projectRoot } = {}) {
     );
   }
 
+  // Story 26.1 — the git workflow guardrail block is appended to EVERY profile
+  // (standard and on-prem), so this read must be as robust as the universal
+  // read above. Any failure to load a non-empty git template surfaces as a
+  // clear, path-identifying error — the guardrails must never silently vanish.
+  let git;
+  try {
+    git = fs.readFileSync(GIT_INSTRUCTION_TEMPLATE_PATH, 'utf-8');
+  } catch (err) {
+    throw new Error(
+      `git instruction template not found or unreadable at ${GIT_INSTRUCTION_TEMPLATE_PATH} — ma-agents installation may be corrupted: ${err.message}`
+    );
+  }
+  if (git.trim() === '') {
+    throw new Error(
+      `git instruction template at ${GIT_INSTRUCTION_TEMPLATE_PATH} is empty — ma-agents installation may be corrupted`
+    );
+  }
+
+  // Compose in the exact order universal + git (+ on-prem). Each piece is
+  // trailing-whitespace-normalized and joined by exactly one blank line so that
+  // first-insert and in-place-replace produce byte-identical marker content
+  // (FR176 / NFR46 idempotency).
+  let composed = universal.replace(/\s+$/, '') + '\n\n' + git.replace(/\s+$/, '');
+
   if (profile === 'on-prem') {
     if (!fs.existsSync(ONPREM_INSTRUCTION_TEMPLATE_PATH)) {
       throw new Error('on-prem profile selected but instruction-block-onprem.template.md is missing');
     }
     const onprem = fs.readFileSync(ONPREM_INSTRUCTION_TEMPLATE_PATH, 'utf-8');
-    // Normalize both pieces so the concatenation has exactly one blank line between them
-    // and no trailing whitespace — feeds NFR46 byte-identity.
-    return universal.replace(/\s+$/, '') + '\n\n' + onprem.replace(/\s+$/, '') + '\n';
+    composed += '\n\n' + onprem.replace(/\s+$/, '');
   }
 
-  // Normalize trailing whitespace so first-insert and in-place-replace both
-  // produce byte-identical content inside the markers (NFR46, AC #6).
-  return universal.replace(/\s+$/, '') + '\n';
+  // Bug 27.10 — the source templates are authored with CRLF line endings, but the
+  // segment seams and terminator above are hand-written LF. That mix yields a block
+  // whose body lines are CRLF while the joins are LF. Normalize to pure LF once here
+  // so the composed block is EOL-consistent regardless of how templates were checked
+  // out on Windows, and so downstream marker-merge (which assumes LF) stays stable.
+  return composed.replace(/\r\n/g, '\n') + '\n';
 }
 
 /**
@@ -224,6 +250,17 @@ function resolveBmadOutputDirs(projectRoot) {
 const CLAUDE_CODE_HOOK_ID = 'ma-agents-verify-manifest';
 const CLAUDE_CODE_SETTINGS_FILE = '.claude/settings.json';
 
+// Bug 27.8 — the SessionStart hook must point at a path that exists in a real
+// (npx/node_modules) install, not at the package's own `lib/` which is never
+// copied into the target. The dependency-free hook script is copied into the
+// target's `.claude/hooks/` and the command resolves it via $CLAUDE_PROJECT_DIR
+// (the target project root). The legacy `lib/hooks/...` command string is kept
+// here only so existing installs get it removed/migrated on the next run.
+const CLAUDE_CODE_HOOK_SOURCE = path.join(__dirname, 'hooks', 'claude-code', 'verify-manifest.js');
+const CLAUDE_CODE_HOOK_TARGET_REL = '.claude/hooks/verify-manifest.js';
+const CLAUDE_CODE_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/${CLAUDE_CODE_HOOK_TARGET_REL}"`;
+const CLAUDE_CODE_HOOK_LEGACY_COMMAND = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+
 function getPackageVersion() {
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
   return pkg.version;
@@ -376,13 +413,91 @@ function ensurePluginStageIgnored(projectRoot) {
   );
 }
 
+// Bug 27.11 — the installer writes the `_bmad/` module tree which is
+// "Installer-managed. Regenerated on every install — treat as read-only."
+// Leaving it tracked guarantees churn and merge conflicts on every reinstall.
+// This sister-policy to PLUGIN_STAGE_PATTERNS ensures `_bmad/` is gitignored.
+//
+// IMPORTANT: this targets ONLY the regenerated `_bmad/` tree. The
+// `_bmad-output/` directory holds tracked project knowledge and is
+// deliberately kept OUT of .gitignore (see ensureBmadOutputTracked) — the
+// patterns below never match it because git treats `_bmad/` (trailing-slash
+// anchored) and `_bmad-output` as distinct entries.
+const BMAD_DIR_NAME = '_bmad';
+const BMAD_DIR_PATTERNS = [
+  BMAD_DIR_NAME,            // _bmad
+  `${BMAD_DIR_NAME}/`,      // _bmad/
+  `/${BMAD_DIR_NAME}`,      // /_bmad
+  `/${BMAD_DIR_NAME}/`,     // /_bmad/
+];
+const BMAD_DIR_CANONICAL_ENTRY = `${BMAD_DIR_NAME}/`;
+
+/**
+ * Ensure `_bmad/` is present in the target project's `.gitignore`. Mirrors the
+ * append-only, idempotent, EOL-preserving contract of `ensurePluginStageIgnored`.
+ *
+ *  - If `.gitignore` is absent, create it with the single canonical entry.
+ *  - If any active (non-comment) line already matches any BMAD_DIR_PATTERNS
+ *    variant, do nothing.
+ *  - Otherwise, append `BMAD_DIR_CANONICAL_ENTRY` preserving existing EOL style.
+ *
+ * Defensive: no-op on falsy/non-string projectRoot, matching the sister helper.
+ *
+ * @param {string} projectRoot - Absolute path to the target project root.
+ */
+function ensureBmadDirIgnored(projectRoot) {
+  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 BMAD_DIR_PATTERNS.includes(line);
+    });
+    if (alreadyPresent) return; // idempotent no-op
+  }
+
+  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 += BMAD_DIR_CANONICAL_ENTRY + eol;
+
+  fs.writeFileSync(gitignorePath, next, 'utf-8');
+  console.log(
+    chalk.green(
+      `${BMAD_DIR_CANONICAL_ENTRY} added to .gitignore (installer-managed BMAD tree — regenerated on every install)`
+    )
+  );
+}
+
 function ensureManifest(installPath, agentId, scope) {
   let manifest = readManifest(installPath);
   if (!manifest) {
+    // Bug 27.9 — when bootstrapped before any agent is known (e.g. profile
+    // bootstrap via setProfile → ensureManifest(root, null, 'project')), agentId
+    // is null. Mirror the migrate-branch guard so we never write the malformed
+    // `agent: null` / `agents: [null]` shape; an empty agents array is valid.
     manifest = {
       manifestVersion: MANIFEST_VERSION,
-      agent: agentId,
-      agents: [agentId],
+      agent: agentId || null,
+      agents: agentId ? [agentId] : [],
       scope: scope,
       skills: {}
     };
@@ -1244,6 +1359,116 @@ async function performInstall(skillId, skill, agent, installPath) {
   return true;
 }
 
+// --- Bug 27.16 — .agents/skills pipeline-consistency reconciliation ----------
+//
+// Two pipelines write skills: ma-agents' own standalone loop (installSkill →
+// performInstall + generateSkillsManifest — the ONLY writer of MANIFEST.yaml),
+// and bmad-method's PluginResolver (via --custom-source) which routes
+// copilot/roo/kilo to the shared `.agents/skills/` dir. The standalone loop only
+// targets `.agents/skills` when a copilot/kilocode/roo-code agent is selected.
+//
+// When the user selects only claude-code/cline/opencode, BMAD still writes the
+// BMAD-family skills into `.agents/skills` (175 of them in the Workshop repro)
+// but the standalone catalog and MANIFEST.yaml are never written there — leaving
+// a dir that looks installed but is silently partial AND missing the
+// MANIFEST.yaml the stamped instruction block points agents at.
+//
+// This pass makes `.agents/skills` pipeline-consistent: if BMAD populated it but
+// no `.agents`-targeting agent was selected (so the standalone loop skipped it),
+// install the full standalone catalog there and generate MANIFEST.yaml. The set
+// of `.agents`-targeting agent ids is derived from agents whose project skills
+// dir resolves to `.agents/skills`.
+
+const AGENTS_SHARED_SKILLS_DIRNAME = '.agents';
+
+/**
+ * Return the list of agent ids whose project-level skills dir is the shared
+ * `.agents/skills/` directory (copilot, kilocode, roo-code). Derived from the
+ * agent registry's `skillsDir` so a future registry change surfaces here.
+ */
+function getAgentsSharedSkillAgentIds() {
+  return listAgents()
+    .filter(a => a.skillsDir === path.join(AGENTS_SHARED_SKILLS_DIRNAME, 'skills') ||
+                 a.skillsDir === `${AGENTS_SHARED_SKILLS_DIRNAME}/skills`)
+    .map(a => a.id);
+}
+
+/**
+ * Bug 27.16 — reconcile a BMAD-populated `.agents/skills` directory that the
+ * standalone loop never targeted. No-op unless ALL of:
+ *   - scope === 'project'
+ *   - `<projectRoot>/.agents/skills` exists on disk (BMAD created it)
+ *   - no `.agents`-targeting agent was among the selected agents
+ *   - the dir has no MANIFEST.yaml (the standalone-loop signature)
+ *
+ * When triggered, installs the full standalone catalog into `.agents/skills`
+ * (using a representative `.agents`-targeting agent for template resolution),
+ * records the skills into that dir's `.ma-agents.json`, and generates
+ * MANIFEST.yaml — so the dir is never BMAD-only without a manifest.
+ *
+ * Idempotent: once MANIFEST.yaml exists the early-return fires.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} selectedAgentIds - agent ids the user selected this run
+ * @param {string} scope - 'project' | 'global'
+ * @returns {Promise<{reconciled: boolean, installed: number}>}
+ */
+async function reconcileAgentsSharedSkills(projectRoot, selectedAgentIds = [], scope = 'project') {
+  const result = { reconciled: false, installed: 0 };
+  if (scope !== 'project') return result;
+  if (typeof projectRoot !== 'string' || !projectRoot) return result;
+
+  const sharedDir = path.join(projectRoot, AGENTS_SHARED_SKILLS_DIRNAME, 'skills');
+  if (!fs.existsSync(sharedDir)) return result; // BMAD never populated it
+
+  const sharedAgentIds = getAgentsSharedSkillAgentIds();
+  const selectedSet = new Set(selectedAgentIds || []);
+  const anySharedSelected = sharedAgentIds.some(id => selectedSet.has(id));
+  if (anySharedSelected) return result; // standalone loop already targeted it
+
+  // If a MANIFEST.yaml already exists, the dir is not standalone-orphaned.
+  if (fs.existsSync(path.join(sharedDir, 'MANIFEST.yaml'))) return result;
+
+  // Pick a representative `.agents`-targeting agent for template resolution.
+  const repAgent = sharedAgentIds.map(id => getAgent(id)).find(Boolean);
+  if (!repAgent) return result; // registry has no such agent — nothing to do
+
+  console.log(chalk.yellow(
+    `  Note: ${sharedDir} was populated by BMAD but carries no MANIFEST.yaml ` +
+    `(no .agents-targeting agent selected) — backfilling the standalone catalog (bug 27.16).`
+  ));
+
+  const skills = listSkills();
+  const manifest = ensureManifest(sharedDir, repAgent.id, scope);
+  const now = new Date().toISOString();
+
+  for (const skill of skills) {
+    try {
+      const ok = await performInstall(skill.id, skill, repAgent, sharedDir);
+      if (!ok) continue;
+      const existing = manifest.skills[skill.id];
+      manifest.skills[skill.id] = {
+        version: skill.version,
+        installedAt: existing ? existing.installedAt : now,
+        updatedAt: now,
+        installerVersion: getPackageVersion(),
+        agentVersion: repAgent.version
+      };
+      result.installed++;
+    } catch (err) {
+      console.log(chalk.yellow(`    x ${skill.id} skipped in .agents/skills backfill: ${err.message}`));
+    }
+  }
+
+  writeManifest(sharedDir, manifest);
+  await generateSkillsManifest(sharedDir);
+  result.reconciled = true;
+  console.log(chalk.green(
+    `  Backfilled ${result.installed} standalone skill(s) + MANIFEST.yaml into ${sharedDir}`
+  ));
+  return result;
+}
+
 // --- Install with upgrade detection ---
 
 async function installSkill(skillId, agentIds, customPath = '', scope = 'project', options = {}) {
@@ -1861,7 +2086,12 @@ function getStatus(agentIds, customPath = '', scope = 'project') {
 
     for (const { path: checkPath, scope: checkScope } of pathsToCheck) {
       const manifest = readManifest(checkPath);
-      if (!manifest || !manifest.skills || Object.keys(manifest.skills).length === 0) {
+      // Bug 27.12 — never treat the PROFILE-ONLY project-root manifest as a
+      // skill inventory. The per-agent skills manifests are authoritative; a
+      // manifest carrying the `project-root` scope discriminator is a
+      // profile/settings store and must be skipped here.
+      if (!manifest || manifest.scope === 'project-root' ||
+          !manifest.skills || Object.keys(manifest.skills).length === 0) {
         continue;
       }
 
@@ -1903,27 +2133,49 @@ async function deployClaudeCodeHook(projectRoot) {
     settings.hooks.SessionStart = [];
   }
 
-  // Check if our hook is already present
-  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  // Bug 27.8 — copy the self-contained hook into the target so the command
+  // resolves in any install (npx/node_modules/dev-repo). The legacy command
+  // string (which pointed at the never-copied package `lib/`) is migrated to
+  // the new command on every run.
+  const hookTargetPath = path.join(projectRoot, CLAUDE_CODE_HOOK_TARGET_REL);
+  await fs.ensureDir(path.dirname(hookTargetPath));
+  await fs.copy(CLAUDE_CODE_HOOK_SOURCE, hookTargetPath, { overwrite: true });
+
+  const hookCommand = CLAUDE_CODE_HOOK_COMMAND;
+  let migrated = false;
+  for (const group of settings.hooks.SessionStart) {
+    if (!group.hooks) continue;
+    for (const h of group.hooks) {
+      if (h.command === CLAUDE_CODE_HOOK_LEGACY_COMMAND || h._id === CLAUDE_CODE_HOOK_ID) {
+        h.command = hookCommand;
+        h._id = CLAUDE_CODE_HOOK_ID;
+        migrated = true;
+      }
+    }
+  }
+
   const alreadyInstalled = settings.hooks.SessionStart.some(group =>
     group.hooks && group.hooks.some(h => h.command === hookCommand)
   );
 
-  if (alreadyInstalled) {
-    return; // Already deployed
+  if (!alreadyInstalled) {
+    settings.hooks.SessionStart.push({
+      matcher: 'startup',
+      hooks: [
+        {
+          type: 'command',
+          command: hookCommand,
+          _id: CLAUDE_CODE_HOOK_ID
+        }
+      ]
+    });
+  } else if (!migrated) {
+    // Hook entry already current and file copied — still ensure settings exist.
+    await fs.ensureDir(path.dirname(settingsPath));
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    return;
   }
 
-  settings.hooks.SessionStart.push({
-    matcher: 'startup',
-    hooks: [
-      {
-        type: 'command',
-        command: hookCommand,
-        _id: CLAUDE_CODE_HOOK_ID
-      }
-    ]
-  });
-
   await fs.ensureDir(path.dirname(settingsPath));
   await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
   console.log(chalk.cyan('    + Deployed Claude Code verify-manifest hook'));
@@ -1935,6 +2187,15 @@ async function deployClaudeCodeHook(projectRoot) {
 async function removeClaudeCodeHook(projectRoot) {
   const settingsPath = path.join(projectRoot, CLAUDE_CODE_SETTINGS_FILE);
 
+  // Bug 27.8 — remove the copied hook file first, before any settings.json
+  // early-return, so a missing/corrupt settings.json never orphans the file.
+  const hookTargetPath = path.join(projectRoot, CLAUDE_CODE_HOOK_TARGET_REL);
+  try {
+    await fs.remove(hookTargetPath);
+  } catch {
+    // best-effort cleanup — never fail uninstall over a missing file
+  }
+
   if (!fs.existsSync(settingsPath)) return;
 
   let settings;
@@ -1946,10 +2207,15 @@ async function removeClaudeCodeHook(projectRoot) {
 
   if (!settings.hooks || !settings.hooks.SessionStart) return;
 
-  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  // Match both the current command and the legacy package-relative command so
+  // older installs get cleaned up too.
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(group => {
     if (!group.hooks) return true;
-    group.hooks = group.hooks.filter(h => h.command !== hookCommand && h._id !== CLAUDE_CODE_HOOK_ID);
+    group.hooks = group.hooks.filter(h =>
+      h.command !== CLAUDE_CODE_HOOK_COMMAND &&
+      h.command !== CLAUDE_CODE_HOOK_LEGACY_COMMAND &&
+      h._id !== CLAUDE_CODE_HOOK_ID
+    );
     return group.hooks.length > 0;
   });
 
@@ -1988,6 +2254,9 @@ module.exports = {
   removeClaudeCodeHook,
   ensureBmadOutputTracked,
   ensurePluginStageIgnored,
+  ensureBmadDirIgnored,
+  reconcileAgentsSharedSkills,
+  getAgentsSharedSkillAgentIds,
   generateSkillsManifest,
   generateProjectContext,
   generateRepoLayoutSection,
@@ -2000,6 +2269,7 @@ module.exports = {
   buildBackupFilename,
   formatBackupTimestamp,
   UNIVERSAL_INSTRUCTION_TEMPLATE_PATH,
+  GIT_INSTRUCTION_TEMPLATE_PATH,
   ONPREM_INSTRUCTION_TEMPLATE_PATH,
   // Story 21.4 — AGENTS.md template, markdown-markers merger, extraInstructionTemplates processor.
   // Story 21.3 (rebased) — yaml-customModes merger dispatch is integrated into stampExtraInstructionTemplates.