From bfd602de62e0cb29bdbd7711b491079e382e7c9d Mon Sep 17 00:00:00 2001 From: Jerome Revillard Date: Mon, 27 Apr 2026 15:53:10 +0200 Subject: [PATCH] feat(config): add per-user global config layer at ~/.bmad/config/ Users working across multiple worktrees or repos no longer need to re-enter personal settings (user_name, communication_language, user_skill_level) in every project. A global user layer at ~/.bmad/config/config.user.toml is merged as the lowest-priority fallback in both resolve_config.py (5-layer) and resolve_customization.py (4-layer). Project-level overrides always win. Missing global dir is fully backward-compatible. Closes #2338 --- src/scripts/resolve_config.py | 18 +- src/scripts/resolve_customization.py | 11 +- test/test-config-resolution.js | 338 +++++++++++++++++++++++++++ 3 files changed, 357 insertions(+), 10 deletions(-) create mode 100644 test/test-config-resolution.js diff --git a/src/scripts/resolve_config.py b/src/scripts/resolve_config.py index eb9e20288..ee6d509fe 100644 --- a/src/scripts/resolve_config.py +++ b/src/scripts/resolve_config.py @@ -1,12 +1,13 @@ #!/usr/bin/env python3 """ -Resolve BMad's central config using four-layer TOML merge. +Resolve BMad's central config using five-layer TOML merge. -Reads from four layers (highest priority last): - 1. {project-root}/_bmad/config.toml (installer-owned team) - 2. {project-root}/_bmad/config.user.toml (installer-owned user) - 3. {project-root}/_bmad/custom/config.toml (human-authored team, committed) - 4. {project-root}/_bmad/custom/config.user.toml (human-authored user, gitignored) +Reads from five layers (highest priority last): + 1. ~/.bmad/config/config.user.toml (global user defaults) + 2. {project-root}/_bmad/config.toml (installer-owned team) + 3. {project-root}/_bmad/config.user.toml (installer-owned user) + 4. {project-root}/_bmad/custom/config.toml (human-authored team, committed) + 5. {project-root}/_bmad/custom/config.user.toml (human-authored user, gitignored) Outputs merged JSON to stdout. Errors go to stderr. @@ -40,6 +41,7 @@ except ImportError: _MISSING = object() _KEYED_MERGE_FIELDS = ("code", "id") +GLOBAL_DIR = Path.home() / ".bmad" / "config" def load_toml(file_path: Path, required: bool = False) -> dict: @@ -151,12 +153,14 @@ def main(): project_root = Path(args.project_root).resolve() bmad_dir = project_root / "_bmad" + global_user = load_toml(GLOBAL_DIR / "config.user.toml") base_team = load_toml(bmad_dir / "config.toml", required=True) base_user = load_toml(bmad_dir / "config.user.toml") custom_team = load_toml(bmad_dir / "custom" / "config.toml") custom_user = load_toml(bmad_dir / "custom" / "config.user.toml") - merged = deep_merge(base_team, base_user) + merged = deep_merge(global_user, base_team) + merged = deep_merge(merged, base_user) merged = deep_merge(merged, custom_team) merged = deep_merge(merged, custom_user) diff --git a/src/scripts/resolve_customization.py b/src/scripts/resolve_customization.py index 28901ed0f..d2d6b3326 100755 --- a/src/scripts/resolve_customization.py +++ b/src/scripts/resolve_customization.py @@ -1,11 +1,12 @@ #!/usr/bin/env python3 """ -Resolve customization for a BMad skill using three-layer TOML merge. +Resolve customization for a BMad skill using four-layer TOML merge. -Reads customization from three layers (highest priority first): +Reads customization from four layers (highest priority first): 1. {project-root}/_bmad/custom/{name}.user.toml (personal, gitignored) 2. {project-root}/_bmad/custom/{name}.toml (team/org, committed) 3. {skill-root}/customize.toml (skill defaults) + 4. ~/.bmad/config/{name}.user.toml (global user defaults) Skill name is derived from the basename of the skill directory. @@ -51,6 +52,7 @@ except ImportError: _MISSING = object() _KEYED_MERGE_FIELDS = ("code", "id") +GLOBAL_DIR = Path.home() / ".bmad" / "config" def find_project_root(start: Path): @@ -211,7 +213,10 @@ def main(): team = load_toml(custom_dir / f"{skill_name}.toml") user = load_toml(custom_dir / f"{skill_name}.user.toml") - merged = deep_merge(defaults, team) + global_user = load_toml(GLOBAL_DIR / f"{skill_name}.user.toml") + + merged = deep_merge(global_user, defaults) + merged = deep_merge(merged, team) merged = deep_merge(merged, user) if args.key: diff --git a/test/test-config-resolution.js b/test/test-config-resolution.js new file mode 100644 index 000000000..5db486a46 --- /dev/null +++ b/test/test-config-resolution.js @@ -0,0 +1,338 @@ +/** + * Config Resolution Tests + * + * Tests the Python config resolution scripts by invoking them as subprocesses + * with temporary TOML fixtures. Validates: + * - Global user layer is loaded and merged with correct priority + * - Project layers override global layers + * - Missing global dir doesn't break anything (backward compat) + * - resolve_customization.py global skill layer + * + * Usage: node test/test-config-resolution.js + */ + +const path = require('node:path'); +const os = require('node:os'); +const fs = require('node:fs/promises'); +const { execSync } = require('node:child_process'); + +const SCRIPTS_DIR = path.resolve(__dirname, '..', 'src', 'scripts'); + +const colors = { + reset: '', + green: '', + red: '', + dim: '', +}; + +let passed = 0; +let failed = 0; + +function assert(condition, testName, errorMessage = '') { + if (condition) { + console.log(`${colors.green}✓${colors.reset} ${testName}`); + passed++; + } else { + console.log(`${colors.red}✗${colors.reset} ${testName}`); + if (errorMessage) { + console.log(` ${colors.dim}${errorMessage}${colors.reset}`); + } + failed++; + } +} + +function writeToml(filePath, data) { + const lines = []; + for (const [key, val] of Object.entries(data)) { + if (typeof val === 'string') { + lines.push(`${key} = "${val}"`); + } else if (typeof val === 'number' || typeof val === 'boolean') { + lines.push(`${key} = ${val}`); + } + } + return fs.writeFile(filePath, lines.join('\n') + '\n'); +} + +async function withTempDir(fn) { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-config-test-')); + try { + return await fn(dir); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } +} + +async function testResolveConfig() { + console.log('\n--- resolve_config.py ---\n'); + + // Test 1: global user layer is loaded + await withTempDir(async (tmpDir) => { + const globalDir = path.join(tmpDir, '.bmad', 'config'); + await fs.mkdir(globalDir, { recursive: true }); + await writeToml(path.join(globalDir, 'config.user.toml'), { + user_name: 'GlobalAlice', + communication_language: 'en', + }); + + const projectDir = path.join(tmpDir, 'project'); + const bmadDir = path.join(projectDir, '_bmad'); + await fs.mkdir(path.join(bmadDir, 'custom'), { recursive: true }); + await writeToml(path.join(bmadDir, 'config.toml'), { + project_name: 'TestProject', + user_name: 'ProjectAlice', + }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_config.py --project-root ${projectDir}`, { encoding: 'utf-8' })); + + assert( + result.user_name === 'ProjectAlice', + 'project config.user overrides global user_name', + `Expected "ProjectAlice", got "${result.user_name}"`, + ); + assert( + result.communication_language === 'en', + 'global communication_language preserved when project has no override', + `Expected "en", got "${result.communication_language}"`, + ); + assert( + result.project_name === 'TestProject', + 'project config values preserved', + `Expected "TestProject", got "${result.project_name}"`, + ); + } finally { + process.env.HOME = origHome; + } + }); + + // Test 2: missing global dir — backward compat + await withTempDir(async (tmpDir) => { + const projectDir = path.join(tmpDir, 'project'); + const bmadDir = path.join(projectDir, '_bmad'); + await fs.mkdir(path.join(bmadDir, 'custom'), { recursive: true }); + await writeToml(path.join(bmadDir, 'config.toml'), { + project_name: 'NoGlobalProject', + }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_config.py --project-root ${projectDir}`, { encoding: 'utf-8' })); + + assert( + result.project_name === 'NoGlobalProject', + 'works fine without global config dir', + `Expected "NoGlobalProject", got "${result.project_name}"`, + ); + } finally { + process.env.HOME = origHome; + } + }); + + // Test 3: full priority chain — global < base_team < base_user < custom_team < custom_user + await withTempDir(async (tmpDir) => { + const globalDir = path.join(tmpDir, '.bmad', 'config'); + await fs.mkdir(globalDir, { recursive: true }); + await writeToml(path.join(globalDir, 'config.user.toml'), { + user_name: 'L0-Global', + }); + + const projectDir = path.join(tmpDir, 'project'); + const bmadDir = path.join(projectDir, '_bmad'); + await fs.mkdir(path.join(bmadDir, 'custom'), { recursive: true }); + await writeToml(path.join(bmadDir, 'config.toml'), { user_name: 'L1-BaseTeam' }); + await writeToml(path.join(bmadDir, 'config.user.toml'), { user_name: 'L2-BaseUser' }); + await writeToml(path.join(bmadDir, 'custom', 'config.toml'), { user_name: 'L3-CustomTeam' }); + await writeToml(path.join(bmadDir, 'custom', 'config.user.toml'), { user_name: 'L4-CustomUser' }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_config.py --project-root ${projectDir}`, { encoding: 'utf-8' })); + + assert( + result.user_name === 'L4-CustomUser', + 'highest priority layer (custom user) wins', + `Expected "L4-CustomUser", got "${result.user_name}"`, + ); + } finally { + process.env.HOME = origHome; + } + }); + + // Test 4: --key flag works with global layer + await withTempDir(async (tmpDir) => { + const globalDir = path.join(tmpDir, '.bmad', 'config'); + await fs.mkdir(globalDir, { recursive: true }); + await writeToml(path.join(globalDir, 'config.user.toml'), { + user_name: 'KeyTestGlobal', + communication_language: 'fr', + }); + + const projectDir = path.join(tmpDir, 'project'); + const bmadDir = path.join(projectDir, '_bmad'); + await fs.mkdir(path.join(bmadDir, 'custom'), { recursive: true }); + await writeToml(path.join(bmadDir, 'config.toml'), { + project_name: 'KeyTestProject', + }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse( + execSync(`python3 ${SCRIPTS_DIR}/resolve_config.py --project-root ${projectDir} --key user_name --key communication_language`, { + encoding: 'utf-8', + }), + ); + + assert( + Object.keys(result).length === 2, + '--key returns only requested keys', + `Expected 2 keys, got ${Object.keys(result).length}: ${JSON.stringify(Object.keys(result))}`, + ); + assert( + result.user_name === 'KeyTestGlobal', + '--key user_name returns global value', + `Expected "KeyTestGlobal", got "${result.user_name}"`, + ); + assert( + result.communication_language === 'fr', + '--key communication_language returns global value', + `Expected "fr", got "${result.communication_language}"`, + ); + } finally { + process.env.HOME = origHome; + } + }); +} + +async function testResolveCustomization() { + console.log('\n--- resolve_customization.py ---\n'); + + // Test 1: global skill user layer is loaded + await withTempDir(async (tmpDir) => { + const globalDir = path.join(tmpDir, '.bmad', 'config'); + await fs.mkdir(globalDir, { recursive: true }); + await writeToml(path.join(globalDir, 'test-skill.user.toml'), { + agent: 'global-agent-prompt', + }); + + const skillDir = path.join(tmpDir, 'skill', 'test-skill'); + await fs.mkdir(skillDir, { recursive: true }); + await writeToml(path.join(skillDir, 'customize.toml'), { + agent: 'default-agent-prompt', + version: '1.0.0', + }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_customization.py --skill ${skillDir}`, { encoding: 'utf-8' })); + + assert( + result.agent === 'default-agent-prompt', + 'skill defaults override global user layer', + `Expected "default-agent-prompt", got "${result.agent}"`, + ); + assert(result.version === '1.0.0', 'skill default values preserved', `Expected "1.0.0", got "${result.version}"`); + } finally { + process.env.HOME = origHome; + } + }); + + // Test 2: global skill layer provides value not in defaults + await withTempDir(async (tmpDir) => { + const globalDir = path.join(tmpDir, '.bmad', 'config'); + await fs.mkdir(globalDir, { recursive: true }); + await writeToml(path.join(globalDir, 'test-skill.user.toml'), { + extra_global_key: 'from-global', + }); + + const skillDir = path.join(tmpDir, 'skill', 'test-skill'); + await fs.mkdir(skillDir, { recursive: true }); + await writeToml(path.join(skillDir, 'customize.toml'), { + version: '2.0.0', + }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_customization.py --skill ${skillDir}`, { encoding: 'utf-8' })); + + assert( + result.extra_global_key === 'from-global', + 'global key not in defaults is preserved', + `Expected "from-global", got "${result.extra_global_key}"`, + ); + assert(result.version === '2.0.0', 'skill defaults still present', `Expected "2.0.0", got "${result.version}"`); + } finally { + process.env.HOME = origHome; + } + }); + + // Test 3: missing global dir — backward compat + await withTempDir(async (tmpDir) => { + const skillDir = path.join(tmpDir, 'skill', 'test-skill'); + await fs.mkdir(skillDir, { recursive: true }); + await writeToml(path.join(skillDir, 'customize.toml'), { + version: '3.0.0', + }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_customization.py --skill ${skillDir}`, { encoding: 'utf-8' })); + + assert(result.version === '3.0.0', 'works without global config dir', `Expected "3.0.0", got "${result.version}"`); + } finally { + process.env.HOME = origHome; + } + }); + + // Test 4: full priority chain — global < defaults < team < user + await withTempDir(async (tmpDir) => { + const globalDir = path.join(tmpDir, '.bmad', 'config'); + await fs.mkdir(globalDir, { recursive: true }); + await writeToml(path.join(globalDir, 'test-skill.user.toml'), { + agent: 'L0-Global', + }); + + const skillDir = path.join(tmpDir, 'project', '_bmad', 'skills', 'test-skill'); + await fs.mkdir(skillDir, { recursive: true }); + await writeToml(path.join(skillDir, 'customize.toml'), { agent: 'L1-Defaults' }); + + const customDir = path.join(tmpDir, 'project', '_bmad', 'custom'); + await fs.mkdir(customDir, { recursive: true }); + await writeToml(path.join(customDir, 'test-skill.toml'), { agent: 'L2-Team' }); + await writeToml(path.join(customDir, 'test-skill.user.toml'), { agent: 'L3-User' }); + + const origHome = process.env.HOME; + process.env.HOME = tmpDir; + try { + const result = JSON.parse(execSync(`python3 ${SCRIPTS_DIR}/resolve_customization.py --skill ${skillDir}`, { encoding: 'utf-8' })); + + assert(result.agent === 'L3-User', 'highest priority layer (project user) wins', `Expected "L3-User", got "${result.agent}"`); + } finally { + process.env.HOME = origHome; + } + }); +} + +async function main() { + console.log('Config Resolution Tests\n'); + + try { + await testResolveConfig(); + await testResolveCustomization(); + } catch (error) { + console.error(`${colors.red}Fatal error: ${error.message}${colors.reset}`); + process.exit(1); + } + + console.log(`\n${colors.green}${passed} passed${colors.reset}, ${colors.red}${failed} failed${colors.reset}`); + process.exit(failed > 0 ? 1 : 0); +} + +main();