ma-agents 3.5.6 → 3.6.0

package/lib/bmad.js

@@ -4,6 +4,7 @@ const os = require('os');
 const { execSync } = require('child_process');
 const chalk = require('chalk');
 const yaml = require('yaml');
+const jsYaml = require('js-yaml');
 const { withExperimentalWarningSuppressed } = require('./warning-filter');
 
 /**
@@ -61,6 +62,166 @@ function isBmadInstalled(projectRoot = process.cwd()) {
     return fs.existsSync(path.join(projectRoot, BMAD_DIR));
 }
 
+/**
+ * Returns true when the operator has explicitly declared offline mode via env.
+ *
+ * Use `MA_AGENTS_OFFLINE=1` (or `true`) on air-gapped hosts so the installer
+ * skips network-dependent diagnostics and emits actionable guidance instead
+ * of bubbling a raw upstream `git fetch` failure.
+ *
+ * @returns {boolean}
+ */
+function isOfflineModeDeclared() {
+    const flag = String(process.env.MA_AGENTS_OFFLINE || '').trim().toLowerCase();
+    return flag === '1' || flag === 'true' || flag === 'yes';
+}
+
+/**
+ * Heuristic: does the caught recompile error look like a network failure?
+ *
+ * bmad-method 6.2.2 always shells out to `git fetch` / `git clone` / `npm install`
+ * against external module repos. On an air-gapped host those commands fail with
+ * recognizable DNS/routing/git errors. We match on common substrings rather than
+ * exit codes because execSync collapses everything into a single Error.message.
+ *
+ * @param {Error} error - The error thrown from runCommand() during recompile
+ * @returns {boolean}
+ */
+function looksLikeOfflineFailure(error) {
+    if (!error || !error.message) {
+        return false;
+    }
+    const haystack = `${error.message} ${error.stderr || ''} ${error.stdout || ''}`.toLowerCase();
+    const needles = [
+        'enotfound',
+        'getaddrinfo',
+        'could not resolve host',
+        'could not resolve',
+        'network is unreachable',
+        'connection refused',
+        'connection timed out',
+        'etimedout',
+        'econnrefused',
+        'econnreset',
+        'unable to access',
+        'failed to connect',
+        'fatal: unable to',
+        'git fetch',
+        'git clone',
+        // Intentionally NOT matching bare 'proxy' / 'ssl' / 'certificate' —
+        // those words appear in benign error messages (e.g. YAML errors that
+        // reference certificate-generation skills) and would cause false
+        // positives that push non-network failures through the offline path.
+    ];
+    return needles.some(n => haystack.includes(n));
+}
+
+/**
+ * Inspect the vendored BMAD cache (post pre-population) and report which
+ * modules are present. Used to classify recompile failures: when the cache is
+ * intact we can safely downgrade an offline-mode failure to a warning.
+ *
+ * @param {string} [cacheRoot] - Override the cache dir (primarily for tests)
+ * @returns {{ present: string[], missing: string[], intact: boolean, cacheDir: string }}
+ */
+function inspectBmadCache(cacheRoot) {
+    const cacheDir = cacheRoot || path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
+    const manifestPath = path.join(__dirname, 'bmad-cache', 'cache-manifest.json');
+
+    let expected = [];
+    try {
+        if (fs.existsSync(manifestPath)) {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            expected = Object.keys(manifest.modules || {});
+        }
+    } catch {
+        // If the manifest is unreadable, treat the cache as not-intact so the
+        // caller surfaces a loud error rather than silently proceeding.
+        expected = [];
+    }
+
+    const present = [];
+    const missing = [];
+    for (const mod of expected) {
+        if (fs.existsSync(path.join(cacheDir, mod))) {
+            present.push(mod);
+        } else {
+            missing.push(mod);
+        }
+    }
+
+    return {
+        present,
+        missing,
+        intact: expected.length > 0 && missing.length === 0,
+        cacheDir,
+    };
+}
+
+/**
+ * Decide what to do when the BMAD recompile step throws.
+ *
+ * Classifies the failure and returns a structured diagnosis so the caller can:
+ *   (a) 'warn'    — downgrade to a yellow diagnostic and proceed
+ *                    (offline + cache intact)
+ *   (b) 'error'   — print an actionable red error listing missing modules
+ *                    and the remediation command (offline + cache incomplete)
+ *   (c) 'rethrow' — the failure does not look offline-related; historically
+ *                    the caller in applyCustomizations() prints red and
+ *                    continues (we preserve that behaviour to avoid breaking
+ *                    the install pipeline when a non-network error happens
+ *                    mid-pipeline). Callers that want harder failure semantics
+ *                    can throw on `action === 'rethrow'` themselves.
+ *
+ * Keeping this pure/sync makes it trivial to unit-test without spawning
+ * subprocesses.
+ *
+ * Note on cache validity: we only verify module *directory presence*, not
+ * structural integrity. prePopulateBmadCache() runs immediately before
+ * recompile and performs structural repair (see its structurallyBroken
+ * check), so by the time this classifier is consulted the cache is either
+ * present-and-repaired or absent.
+ *
+ * @param {Error} error - The error thrown from runCommand()
+ * @param {Object} [opts]
+ * @param {Function} [opts.cacheInspector] - Override for testing
+ * @returns {{ action: 'warn' | 'error' | 'rethrow', message: string, missing?: string[] }}
+ */
+function classifyRecompileFailure(error, opts = {}) {
+    const declaredOffline = isOfflineModeDeclared();
+    const looksOffline = looksLikeOfflineFailure(error);
+    const inspector = opts.cacheInspector || inspectBmadCache;
+
+    if (!declaredOffline && !looksOffline) {
+        return {
+            action: 'rethrow',
+            message: error && error.message ? error.message : 'unknown error',
+        };
+    }
+
+    const cache = inspector();
+
+    if (cache.intact) {
+        return {
+            action: 'warn',
+            message:
+                'BMAD recompile reported a network-related failure, but the vendored cache is intact — ' +
+                `proceeding with cached modules (${cache.present.join(', ')}). ` +
+                'Set MA_AGENTS_OFFLINE=1 on air-gapped hosts to silence this diagnostic.',
+        };
+    }
+
+    return {
+        action: 'error',
+        missing: cache.missing,
+        message:
+            'BMAD recompile failed on an air-gapped host and the vendored cache is incomplete. ' +
+            `Missing modules: ${cache.missing.join(', ') || '(cache manifest unreadable)'}. ` +
+            'Remediation: on a connected host run `npm run build:bmad-cache` then re-run the installer; ' +
+            `or copy a populated cache into ${cache.cacheDir}.`,
+    };
+}
+
 /**
  * Build a complete bmad-method CLI command from an install context object.
  * Replaces ad-hoc string concatenation with a single authoritative builder.
@@ -314,6 +475,112 @@ async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = pr
     }
 }
 
+/**
+ * Strip `phase` and `on_prem_phase_prefix` top-level keys from all deployed
+ * customize.yaml files in `configTargetDir`. Called for EVERY profile so that
+ * standard-profile deployments never contain the extension keys (NFR44).
+ *
+ * @param {string} configTargetDir  Path to _bmad/_config/agents/
+ */
+async function stripOnPremKeys(configTargetDir) {
+    if (!fs.existsSync(configTargetDir)) return;
+    const files = (await fs.readdir(configTargetDir)).filter(f => f.endsWith('.customize.yaml'));
+    for (const file of files) {
+        const filePath = path.join(configTargetDir, file);
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, 'utf8');
+        } catch {
+            continue;
+        }
+        let doc;
+        try {
+            doc = jsYaml.load(raw);
+        } catch {
+            continue;
+        }
+        if (!doc || typeof doc !== 'object') continue;
+        if (!Object.prototype.hasOwnProperty.call(doc, 'phase') &&
+            !Object.prototype.hasOwnProperty.call(doc, 'on_prem_phase_prefix')) {
+            continue; // Nothing to strip — pre-Epic-21 file, leave untouched
+        }
+        delete doc.phase;
+        delete doc.on_prem_phase_prefix;
+        await fs.writeFile(filePath, jsYaml.dump(doc, { lineWidth: -1 }), 'utf8');
+    }
+}
+
+/**
+ * For on-prem profile: inject `on_prem_phase_prefix` as `critical_actions[0]`
+ * into each deployed customize.yaml that carries the extension keys, then strip
+ * those keys from the deployed file. Idempotent: the prefix is inserted once
+ * (the extension keys are removed afterwards so a second run is a no-op on the
+ * deployed file — `stripOnPremKeys` covers the second pass).
+ *
+ * Must be called AFTER the STAGE:CUSTOMIZE copy AND after `stripOnPremKeys`
+ * has already been called (or will be called immediately after on the same
+ * set of files). In practice we call stripOnPremKeys once at the end for all
+ * profiles, and applyOnPremPhasePrefix writes the merged file atomically.
+ *
+ * @param {string} customizeSourceDir  lib/bmad-customize/ (source of truth)
+ * @param {string} configTargetDir     _bmad/_config/agents/ (deployed location)
+ */
+async function applyOnPremPhasePrefix(customizeSourceDir, configTargetDir) {
+    if (!fs.existsSync(configTargetDir)) return;
+    const files = (await fs.readdir(customizeSourceDir)).filter(f => f.endsWith('.customize.yaml'));
+    for (const file of files) {
+        const sourceFile = path.join(customizeSourceDir, file);
+        const targetFile = path.join(configTargetDir, file);
+        if (!fs.existsSync(targetFile)) continue;
+        let sourceDoc;
+        try {
+            sourceDoc = jsYaml.load(await fs.readFile(sourceFile, 'utf8'));
+        } catch {
+            continue;
+        }
+        if (!sourceDoc || typeof sourceDoc !== 'object') continue;
+        const prefix = sourceDoc.on_prem_phase_prefix;
+        if (!prefix || typeof prefix !== 'string' || !prefix.trim()) continue;
+        // Read the deployed file (may already be stripped if stripOnPremKeys ran first,
+        // or may still have the keys if we run in combined mode)
+        let deployedDoc;
+        try {
+            deployedDoc = jsYaml.load(await fs.readFile(targetFile, 'utf8'));
+        } catch {
+            continue;
+        }
+        if (!deployedDoc || typeof deployedDoc !== 'object') continue;
+        // Build final critical_actions: [prefix, ...original entries]
+        const originalActions = Array.isArray(deployedDoc.critical_actions)
+            ? deployedDoc.critical_actions
+            : [];
+        deployedDoc.critical_actions = [prefix, ...originalActions];
+        // Remove extension keys (idempotency: they were in the copy, we strip them now)
+        delete deployedDoc.phase;
+        delete deployedDoc.on_prem_phase_prefix;
+        await fs.writeFile(targetFile, jsYaml.dump(deployedDoc, { lineWidth: -1 }), 'utf8');
+    }
+}
+
+/**
+ * Exported for testing without running the full installer.
+ * Applies post-deploy YAML rewriting for phase-aware persona prefixes.
+ *
+ * - Always strips `phase` and `on_prem_phase_prefix` from deployed files (NFR44).
+ * - When profile === 'on-prem', additionally injects the prefix as critical_actions[0].
+ *
+ * @param {string} customizeSourceDir  lib/bmad-customize/
+ * @param {string} configTargetDir     _bmad/_config/agents/
+ * @param {string} profile             'on-prem' | 'standard' | undefined
+ */
+async function applyPersonaPhasePrefix(customizeSourceDir, configTargetDir, profile) {
+    if (profile === 'on-prem') {
+        await applyOnPremPhasePrefix(customizeSourceDir, configTargetDir);
+    } else {
+        await stripOnPremKeys(configTargetDir);
+    }
+}
+
 async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm', 'bmb'], tools = [], selectedAgentIds = [], force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
     const sourceDir = path.join(__dirname, 'bmad-customizations');
     const workflowSourceDir = path.join(__dirname, 'bmad-workflows');
@@ -384,7 +651,20 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
     try {
         runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
     } catch (error) {
-        console.error(chalk.red(`  BMAD recompile failed: ${error.message}`));
+        // Air-gapped / offline classification (bug-bmad-recompile-fails-on-airgapped-network).
+        // bmad-method 6.2.2 unconditionally performs `git fetch` / `git clone` / `npm install`
+        // against external module repos; on a disconnected host those calls throw and we used
+        // to swallow the error with a one-line red banner. Instead: classify the failure,
+        // downgrade to a warning when the vendored cache is intact, or surface an actionable
+        // error listing the missing modules and the remediation command.
+        const diagnosis = classifyRecompileFailure(error);
+        if (diagnosis.action === 'warn') {
+            console.warn(chalk.yellow(`  BMAD recompile warning (offline): ${diagnosis.message}`));
+        } else if (diagnosis.action === 'error') {
+            console.error(chalk.red(`  BMAD recompile failed: ${diagnosis.message}`));
+        } else {
+            console.error(chalk.red(`  BMAD recompile failed: ${diagnosis.message}`));
+        }
     }
 
     // STAGE:EXTENSION — Deploy BMAD extension module (AFTER recompile — extensions/ survives recompile)
@@ -407,6 +687,8 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
     // These add critical_actions to the 8 built-in BMM agents (pm, architect, dev, qa,
     // sm, tech-writer, ux-designer, bmad-master) so they load project skills at startup.
     // Runs AFTER --custom-content (extension module) and BEFORE quick-update.
+    // Post-deploy: phase:/on_prem_phase_prefix: keys are stripped for standard profile;
+    // for on-prem profile the prefix is injected as critical_actions[0] instead.
     const customizeSource = path.join(__dirname, 'bmad-customize');
     if (fs.existsSync(customizeSource)) {
         await fs.ensureDir(configTargetDir);
@@ -415,6 +697,8 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
             await fs.copy(path.join(customizeSource, file), path.join(configTargetDir, file));
             console.log(chalk.cyan(`    + Applied built-in customization: ${file}`));
         }
+        const profile = require('./profile').getProfile(projectRoot) ?? 'standard';
+        await applyPersonaPhasePrefix(customizeSource, configTargetDir, profile);
     }
 
     // STAGE:WORKFLOWS — Apply workflows (AFTER recompile so they persist)
@@ -1203,4 +1487,12 @@ module.exports = {
     cleanupLegacyArtifacts,
     parseCustomizeYaml,
     registerMlWorkflows,
+    // Story 21.7 — phase-aware persona prefix (exported for testing)
+    applyPersonaPhasePrefix,
+    // Offline-safe recompile helpers (exported for testing — see bug
+    // bug-bmad-recompile-fails-on-airgapped-network)
+    isOfflineModeDeclared,
+    looksLikeOfflineFailure,
+    inspectBmadCache,
+    classifyRecompileFailure,
 };