ma-agents 2.20.3 → 2.22.0

package/lib/installer.js

@@ -6,6 +6,12 @@ const { getAgent, getAllAgents } = require('./agents');
 
 const MANIFEST_FILE = '.ma-agents.json';
 const MANIFEST_VERSION = '1.1.0';
+const MA_AGENTS_SOURCE = 'ma-agents';
+const TEMPLATE_PATH = path.join(__dirname, 'templates', 'project-context.template.md');
+
+// Claude Code hook configuration for MANIFEST verification
+const CLAUDE_CODE_HOOK_ID = 'ma-agents-verify-manifest';
+const CLAUDE_CODE_SETTINGS_FILE = '.claude/settings.json';
 
 function getPackageVersion() {
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -31,6 +37,27 @@ function writeManifest(installPath, manifest) {
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
 }
 
+const BMAD_OUTPUT_PATTERNS = ['_bmad-output', '_bmad-output/', '/_bmad-output', '/_bmad-output/'];
+
+function ensureBmadOutputTracked(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  let content;
+  try {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // no .gitignore — nothing to do
+    throw err;
+  }
+
+  const lines = content.split(/\r?\n/);
+  const filtered = lines.filter(line => !BMAD_OUTPUT_PATTERNS.includes(line.trim()));
+
+  if (filtered.length === lines.length) return; // nothing removed — do not write
+
+  fs.writeFileSync(gitignorePath, filtered.join('\n'), 'utf-8');
+  console.log(chalk.green('_bmad-output is now tracked as project knowledge (not gitignored)'));
+}
+
 function ensureManifest(installPath, agentId, scope) {
   let manifest = readManifest(installPath);
   if (!manifest) {
@@ -107,6 +134,72 @@ async function generateSkillsManifest(installPath) {
   console.log(chalk.cyan(`    + Generated ${manifestYamlPath}`));
 }
 
+/**
+ * Generate project-context.md content by stamping the template with installed agent MANIFEST paths.
+ * @param {string} projectRoot - Absolute path to project root (unused for path generation but part of API)
+ * @param {Array<{skillsDir: string}>} installedAgents - Agent objects with skillsDir property
+ * @returns {Promise<string>} Stamped template content string (does NOT write any file)
+ */
+async function generateProjectContext(projectRoot, installedAgents) {
+  let template;
+  try {
+    template = await fs.readFile(TEMPLATE_PATH, 'utf8');
+  } catch (err) {
+    throw new Error(`project-context template not found at ${TEMPLATE_PATH} — ma-agents installation may be corrupted: ${err.message}`);
+  }
+
+  const validAgents = installedAgents ? installedAgents.filter(a => a && a.skillsDir) : [];
+  let manifestList;
+  if (validAgents.length === 0) {
+    manifestList = '  - (no agents installed — run ma-agents to install skills)';
+  } else {
+    manifestList = validAgents
+      .map(a => `  - \`${a.skillsDir}/MANIFEST.yaml\``)
+      .join('\n');
+  }
+
+  return template.replace('{{MANIFEST_PATHS_LIST}}', manifestList);
+}
+
+/**
+ * Update the MANIFEST paths section in an existing project-context.md.
+ * Locates content between <!-- ma-agents:manifest-paths-start --> and
+ * <!-- ma-agents:manifest-paths-end --> markers and replaces it with the
+ * current agent list. Returns true if the file was updated, false if
+ * markers were not found (old-format file — backward compatible) or if
+ * the content was already up to date.
+ * @param {string} outputPath - Absolute path to the existing project-context.md
+ * @param {Array<{skillsDir: string}>} installedAgents - Agent objects with skillsDir property
+ * @returns {Promise<boolean>} true if file was written, false otherwise
+ */
+async function updateProjectContextManifestPaths(outputPath, installedAgents) {
+  const content = await fs.readFile(outputPath, 'utf8');
+  const validAgents = installedAgents ? installedAgents.filter(a => a && a.skillsDir) : [];
+  const newList = validAgents.length === 0
+    ? '  - (no agents installed — run ma-agents to install skills)'
+    : validAgents.map(a => `  - \`${a.skillsDir}/MANIFEST.yaml\``).join('\n');
+
+  const START = '<!-- ma-agents:manifest-paths-start -->';
+  const END = '<!-- ma-agents:manifest-paths-end -->';
+  const startIdx = content.indexOf(START);
+  const endIdx = content.indexOf(END);
+
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return false; // no markers — old-format file, skip silently (backward compatible)
+  }
+
+  const before = content.slice(0, startIdx + START.length);
+  const after = content.slice(endIdx);
+  const newContent = `${before}\n${newList}\n${after}`;
+
+  if (newContent === content) {
+    return false; // already up to date, no write needed
+  }
+
+  await fs.writeFile(outputPath, newContent, 'utf8');
+  return true;
+}
+
 /**
  * Find the insertion point in content after all skipped headers.
  * For '---' pattern, skips YAML frontmatter block (opening --- on first line through closing ---).
@@ -160,6 +253,48 @@ function findInsertionPoint(content, skipPatterns) {
 async function updateAgentInstructions(agent, projectRoot) {
   if (!agent.instructionFiles || agent.instructionFiles.length === 0) return;
 
+  // JSON merge strategy (e.g., OpenCode)
+  if (agent.injectionStrategy?.position === 'json-merge') {
+    const targetKey = agent.injectionStrategy.targetKey || 'instructions';
+    const filePath = path.join(projectRoot, agent.instructionFiles[0]);
+    const agentProjectPath = agent.getProjectPath();
+    const relManifestPath = path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/');
+    const instructionText = `# AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at ${relManifestPath}\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task.`;
+
+    if (!fs.existsSync(filePath)) {
+      // File absent: create fresh (atomic write)
+      const data = { [targetKey]: [] };
+      data[targetKey].push({ _source: MA_AGENTS_SOURCE, text: instructionText });
+      const tmpPath = filePath + '.tmp';
+      await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+      await fs.rename(tmpPath, filePath);
+      console.log(chalk.cyan(`    + Created ${agent.instructionFiles[0]}`));
+      return;
+    }
+    // File present: read and merge
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const data = JSON.parse(content);
+      if (!Array.isArray(data[targetKey])) {
+        data[targetKey] = [];
+      }
+      // Filter out stale ma-agents entries, keep user entries (null-safe)
+      const userEntries = data[targetKey].filter(entry => entry != null && entry._source !== MA_AGENTS_SOURCE);
+      // Append fresh ma-agents entries
+      const freshEntries = [{ _source: MA_AGENTS_SOURCE, text: instructionText }];
+      data[targetKey] = [...userEntries, ...freshEntries];
+      // Atomic write: temp file then rename
+      const tmpPath = filePath + '.tmp';
+      await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+      await fs.rename(tmpPath, filePath);
+      console.log(chalk.cyan(`    + Updated ${agent.instructionFiles[0]}`));
+    } catch (err) {
+      console.error(`[${MA_AGENTS_SOURCE}] ERROR: Could not parse ${filePath} — ${err.message}. File not modified.`);
+      return; // non-fatal: do NOT re-throw
+    }
+    return;
+  }
+
   const agentProjectPath = agent.getProjectPath();
   const relManifestPath = path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/');
 
@@ -362,6 +497,11 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
     pathGroups.get(installPath).push({ agentId, agent });
   }
 
+  // Guard: project-context generation runs at most once per installSkill() call.
+  // pathGroups can have multiple entries when agents share paths; without this flag
+  // the generation would fire once per path group, producing redundant file I/O.
+  let projectContextHandled = false;
+
   for (const [installPath, agentEntries] of pathGroups) {
     const primaryAgent = agentEntries[0].agent;
     const agentNames = agentEntries.map(e => e.agent.name).join(', ');
@@ -516,6 +656,7 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
           agentVersion: primaryAgent.version
         };
         writeManifest(installPath, manifest);
+        ensureBmadOutputTracked(installPath);
 
         // Generate MANIFEST.yaml and update instruction files for ALL agents
         await generateSkillsManifest(installPath);
@@ -523,6 +664,36 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
           for (const entry of agentEntries) {
             await updateAgentInstructions(entry.agent, process.cwd());
           }
+          // Deploy Claude Code hook when skills are installed for claude-code
+          if (includesClaudeCode(agentEntries)) {
+            await deployClaudeCodeHook(process.cwd());
+          }
+          // Generate project-context.md on first install; update manifest paths on subsequent installs.
+          // 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.
+          if (!projectContextHandled) {
+            projectContextHandled = true;
+            const projectRoot = process.cwd();
+            const outputPath = path.join(projectRoot, '_bmad-output', 'project-context.md');
+            const allAgents = getManifestAgents(manifest).map(id => getAgent(id)).filter(Boolean);
+            try {
+              await fs.ensureDir(path.join(projectRoot, '_bmad-output'));
+              if (await fs.pathExists(outputPath)) {
+                const updated = await updateProjectContextManifestPaths(outputPath, allAgents);
+                if (updated) {
+                  console.log(chalk.green('✓ project-context.md manifest paths updated'));
+                } else {
+                  console.log(chalk.blue('ℹ project-context.md already up to date'));
+                }
+              } else {
+                const content = await generateProjectContext(projectRoot, allAgents);
+                await fs.writeFile(outputPath, content, 'utf8');
+                console.log(chalk.green('✓ project-context.md generated at _bmad-output/project-context.md'));
+              }
+            } catch (err) {
+              console.log(chalk.yellow(`⚠ project-context generation failed: ${err.message} — continuing install`));
+            }
+          }
         }
       }
     } catch (error) {
@@ -602,6 +773,14 @@ async function uninstallSkill(skillId, agentIds, customPath = '', scope = 'proje
         for (const entry of agentEntries) {
           await updateAgentInstructions(entry.agent, process.cwd());
         }
+        // Remove Claude Code hook when no skills remain for claude-code
+        if (includesClaudeCode(agentEntries)) {
+          const currentManifest = readManifest(installPath);
+          const hasRemainingSkills = currentManifest && currentManifest.skills && Object.keys(currentManifest.skills).length > 0;
+          if (!hasRemainingSkills) {
+            await removeClaudeCodeHook(process.cwd());
+          }
+        }
       }
     } catch (error) {
       console.log(chalk.red(`    x Failed: ${error.message}`));
@@ -655,6 +834,101 @@ function getStatus(agentIds, customPath = '', scope = 'project') {
   return results;
 }
 
+// --- Claude Code Hook Management ---
+
+/**
+ * Deploy the verify-manifest SessionStart hook into .claude/settings.json.
+ * Performs a JSON merge — preserves existing settings and hooks.
+ */
+async function deployClaudeCodeHook(projectRoot) {
+  const settingsPath = path.join(projectRoot, CLAUDE_CODE_SETTINGS_FILE);
+  let settings = {};
+
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
+    } catch {
+      console.log(chalk.yellow('    Warning: Could not parse .claude/settings.json, skipping hook deployment'));
+      return;
+    }
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+  if (!settings.hooks.SessionStart) {
+    settings.hooks.SessionStart = [];
+  }
+
+  // Check if our hook is already present
+  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  const alreadyInstalled = settings.hooks.SessionStart.some(group =>
+    group.hooks && group.hooks.some(h => h.command === hookCommand)
+  );
+
+  if (alreadyInstalled) {
+    return; // Already deployed
+  }
+
+  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'));
+}
+
+/**
+ * Remove the verify-manifest hook from .claude/settings.json.
+ */
+async function removeClaudeCodeHook(projectRoot) {
+  const settingsPath = path.join(projectRoot, CLAUDE_CODE_SETTINGS_FILE);
+
+  if (!fs.existsSync(settingsPath)) return;
+
+  let settings;
+  try {
+    settings = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
+  } catch {
+    return;
+  }
+
+  if (!settings.hooks || !settings.hooks.SessionStart) return;
+
+  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  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);
+    return group.hooks.length > 0;
+  });
+
+  // Clean up empty arrays
+  if (settings.hooks.SessionStart.length === 0) {
+    delete settings.hooks.SessionStart;
+  }
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  console.log(chalk.cyan('    - Removed Claude Code verify-manifest hook'));
+}
+
+/**
+ * Check if any agents in the list include claude-code.
+ */
+function includesClaudeCode(agentEntries) {
+  return agentEntries.some(e => e.agentId === 'claude-code');
+}
+
 module.exports = {
   listSkills,
   listAgents,
@@ -666,5 +940,12 @@ module.exports = {
   getManifestAgents,
   compareSemver,
   findInsertionPoint,
-  _testUpdateAgentInstructions: updateAgentInstructions
+  deployClaudeCodeHook,
+  removeClaudeCodeHook,
+  ensureBmadOutputTracked,
+  generateSkillsManifest,
+  generateProjectContext,
+  _updateProjectContextManifestPaths: updateProjectContextManifestPaths,
+  _testUpdateAgentInstructions: updateAgentInstructions,
+  _MA_AGENTS_SOURCE: MA_AGENTS_SOURCE
 };

package/lib/methodology/version.json

@@ -0,0 +1,7 @@
+{
+  "version": "1.0.0",
+  "description": "BMAD-METHOD AI Development Training Presentation",
+  "files": [
+    "BMAD_AI_Development_Training.pptx"
+  ]
+}