bmad-method 6.2.2 → 6.2.3-next.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,78 @@
+{
+  "name": "bmad-method",
+  "owner": {
+    "name": "Brian (BMad) Madison"
+  },
+  "description": "Breakthrough Method of Agile AI-driven Development — a full-lifecycle framework with agents and workflows for analysis, planning, architecture, and implementation.",
+  "license": "MIT",
+  "homepage": "https://github.com/bmad-code-org/BMAD-METHOD",
+  "repository": "https://github.com/bmad-code-org/BMAD-METHOD",
+  "keywords": ["bmad", "agile", "ai", "orchestrator", "development", "methodology", "agents"],
+  "plugins": [
+    {
+      "name": "bmad-pro-skills",
+      "source": "./",
+      "description": "Next level skills for power users — advanced prompting techniques, agent management, and more.",
+      "version": "6.3.0",
+      "author": {
+        "name": "Brian (BMad) Madison"
+      },
+      "skills": [
+        "./src/core-skills/bmad-help",
+        "./src/core-skills/bmad-init",
+        "./src/core-skills/bmad-brainstorming",
+        "./src/core-skills/bmad-distillator",
+        "./src/core-skills/bmad-party-mode",
+        "./src/core-skills/bmad-shard-doc",
+        "./src/core-skills/bmad-advanced-elicitation",
+        "./src/core-skills/bmad-editorial-review-prose",
+        "./src/core-skills/bmad-editorial-review-structure",
+        "./src/core-skills/bmad-index-docs",
+        "./src/core-skills/bmad-review-adversarial-general",
+        "./src/core-skills/bmad-review-edge-case-hunter"
+      ]
+    },
+    {
+      "name": "bmad-method-lifecycle",
+      "source": "./",
+      "description": "Full-lifecycle AI development framework — agents and workflows for product analysis, planning, architecture, and implementation.",
+      "version": "6.3.0",
+      "author": {
+        "name": "Brian (BMad) Madison"
+      },
+      "skills": [
+        "./src/bmm-skills/1-analysis/bmad-product-brief",
+        "./src/bmm-skills/1-analysis/bmad-agent-analyst",
+        "./src/bmm-skills/1-analysis/bmad-agent-tech-writer",
+        "./src/bmm-skills/1-analysis/bmad-document-project",
+        "./src/bmm-skills/1-analysis/research/bmad-domain-research",
+        "./src/bmm-skills/1-analysis/research/bmad-market-research",
+        "./src/bmm-skills/1-analysis/research/bmad-technical-research",
+        "./src/bmm-skills/2-plan-workflows/bmad-agent-pm",
+        "./src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer",
+        "./src/bmm-skills/2-plan-workflows/bmad-create-prd",
+        "./src/bmm-skills/2-plan-workflows/bmad-edit-prd",
+        "./src/bmm-skills/2-plan-workflows/bmad-validate-prd",
+        "./src/bmm-skills/2-plan-workflows/bmad-create-ux-design",
+        "./src/bmm-skills/3-solutioning/bmad-agent-architect",
+        "./src/bmm-skills/3-solutioning/bmad-create-architecture",
+        "./src/bmm-skills/3-solutioning/bmad-check-implementation-readiness",
+        "./src/bmm-skills/3-solutioning/bmad-create-epics-and-stories",
+        "./src/bmm-skills/3-solutioning/bmad-generate-project-context",
+        "./src/bmm-skills/4-implementation/bmad-agent-dev",
+        "./src/bmm-skills/4-implementation/bmad-agent-sm",
+        "./src/bmm-skills/4-implementation/bmad-agent-qa",
+        "./src/bmm-skills/4-implementation/bmad-agent-quick-flow-solo-dev",
+        "./src/bmm-skills/4-implementation/bmad-dev-story",
+        "./src/bmm-skills/4-implementation/bmad-quick-dev",
+        "./src/bmm-skills/4-implementation/bmad-sprint-planning",
+        "./src/bmm-skills/4-implementation/bmad-sprint-status",
+        "./src/bmm-skills/4-implementation/bmad-code-review",
+        "./src/bmm-skills/4-implementation/bmad-create-story",
+        "./src/bmm-skills/4-implementation/bmad-correct-course",
+        "./src/bmm-skills/4-implementation/bmad-retrospective",
+        "./src/bmm-skills/4-implementation/bmad-qa-generate-e2e-tests"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.2.2",
+  "version": "6.2.3-next.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -18,14 +18,14 @@
   },
   "license": "MIT",
   "author": "Brian (BMad) Madison",
-  "main": "tools/cli/bmad-cli.js",
+  "main": "tools/installer/bmad-cli.js",
   "bin": {
-    "bmad": "tools/bmad-npx-wrapper.js",
-    "bmad-method": "tools/bmad-npx-wrapper.js"
+    "bmad": "tools/installer/bmad-cli.js",
+    "bmad-method": "tools/installer/bmad-cli.js"
   },
   "scripts": {
-    "bmad:install": "node tools/cli/bmad-cli.js install",
-    "bmad:uninstall": "node tools/cli/bmad-cli.js uninstall",
+    "bmad:install": "node tools/installer/bmad-cli.js install",
+    "bmad:uninstall": "node tools/installer/bmad-cli.js uninstall",
     "docs:build": "node tools/build-docs.mjs",
     "docs:dev": "astro dev --root website",
     "docs:fix-links": "node tools/fix-doc-links.js",
@@ -34,13 +34,13 @@
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
-    "install:bmad": "node tools/cli/bmad-cli.js install",
+    "install:bmad": "node tools/installer/bmad-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run validate:refs && npm run validate:skills",
-    "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
+    "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
     "test": "npm run test:refs && npm run test:install && npm run lint && npm run lint:md && npm run format:check",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",

package/src/core-skills/bmad-distillator/resources/distillate-format-reference.md

@@ -172,7 +172,7 @@ parts: 1
 - Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
 
 ## Current Installer (migration context)
-- Entry: `tools/cli/bmad-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js`
+- Entry: `tools/installer/bmad-cli.js` (Commander.js) → `tools/installer/core/installer.js`
 - Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
 - Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON
 - External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver

package/src/core-skills/bmad-init/scripts/bmad_init.py

@@ -166,9 +166,27 @@ def resolve_project_root_placeholder(value, project_root):
     """Replace {project-root} placeholder with actual path."""
     if not value or not isinstance(value, str):
         return value
-    if '{project-root}' in value:
-        return value.replace('{project-root}', str(project_root))
-    return value
+    if '{project-root}' not in value:
+        return value
+
+    # Strip the {project-root} token to inspect what remains, so we can
+    # correctly handle absolute paths stored as "{project-root}//absolute/path"
+    # (produced by the "{project-root}/{value}" template applied to an absolute value).
+    suffix = value.replace('{project-root}', '', 1)
+
+    # Strip the one path separator that follows the token (if any)
+    if suffix.startswith('/') or suffix.startswith('\\'):
+        remainder = suffix[1:]
+    else:
+        remainder = suffix
+
+    if os.path.isabs(remainder):
+        # The original value was an absolute path stored with a {project-root}/ prefix.
+        # Return the absolute path directly — no joining needed.
+        return remainder
+
+    # Relative path: join with project root and normalize to resolve any .. segments.
+    return os.path.normpath(os.path.join(str(project_root), remainder))
 
 
 def parse_var_specs(vars_string):
@@ -222,9 +240,22 @@ def apply_result_template(var_def, raw_value, context):
     if not result_template:
         return raw_value
 
+    # If the user supplied an absolute path and the template would prefix it with
+    # "{project-root}/", skip the template entirely to avoid producing a broken path
+    # like "/my/project//absolute/path".
+    if isinstance(raw_value, str) and os.path.isabs(raw_value):
+        return raw_value
+
     ctx = dict(context)
     ctx['value'] = raw_value
-    return expand_template(result_template, ctx)
+    result = expand_template(result_template, ctx)
+
+    # Normalize the resulting path to resolve any ".." segments (e.g. when the user
+    # entered a relative path such as "../../outside-dir").
+    if isinstance(result, str) and '{' not in result and os.path.isabs(result):
+        result = os.path.normpath(result)
+
+    return result
 
 
 # =============================================================================

package/src/core-skills/bmad-init/scripts/tests/test_bmad_init.py

@@ -110,6 +110,37 @@ class TestResolveProjectRootPlaceholder(unittest.TestCase):
     def test_non_string(self):
         self.assertEqual(resolve_project_root_placeholder(42, Path('/test')), 42)
 
+    def test_absolute_path_stored_with_prefix(self):
+        """Absolute output_folder entered by user is stored as '{project-root}//abs/path'
+        by the '{project-root}/{value}' template. It must resolve to '/abs/path', not
+        '/project//abs/path'."""
+        result = resolve_project_root_placeholder(
+            '{project-root}//Users/me/outside', Path('/Users/me/myproject')
+        )
+        self.assertEqual(result, '/Users/me/outside')
+
+    def test_relative_path_with_traversal_is_normalized(self):
+        """A relative path like '../../sibling' produces '{project-root}/../../sibling'
+        after the template. It must resolve to the normalized absolute path, not the
+        un-normalized string '/project/../../sibling'."""
+        result = resolve_project_root_placeholder(
+            '{project-root}/../../sibling', Path('/Users/me/myproject')
+        )
+        self.assertEqual(result, '/Users/sibling')
+
+    def test_relative_path_one_level_up(self):
+        result = resolve_project_root_placeholder(
+            '{project-root}/../outside-outputs', Path('/project/root')
+        )
+        self.assertEqual(result, '/project/outside-outputs')
+
+    def test_standard_relative_path_unchanged(self):
+        """Normal in-project relative paths continue to work correctly."""
+        result = resolve_project_root_placeholder(
+            '{project-root}/_bmad-output', Path('/project/root')
+        )
+        self.assertEqual(result, '/project/root/_bmad-output')
+
 
 class TestExpandTemplate(unittest.TestCase):
 
@@ -147,6 +178,39 @@ class TestApplyResultTemplate(unittest.TestCase):
         result = apply_result_template(var_def, 'English', {})
         self.assertEqual(result, 'English')
 
+    def test_absolute_value_skips_project_root_template(self):
+        """When the user enters an absolute path, the '{project-root}/{value}' template
+        must not be applied — doing so would produce '/project//absolute/path'."""
+        var_def = {'result': '{project-root}/{value}'}
+        result = apply_result_template(
+            var_def, '/Users/me/shared-outputs', {'project-root': '/Users/me/myproject'}
+        )
+        self.assertEqual(result, '/Users/me/shared-outputs')
+
+    def test_relative_traversal_value_is_normalized(self):
+        """A relative path like '../../outside' combined with the project-root template
+        must produce a clean normalized absolute path, not '/project/../../outside'."""
+        var_def = {'result': '{project-root}/{value}'}
+        result = apply_result_template(
+            var_def, '../../outside-dir', {'project-root': '/Users/me/myproject'}
+        )
+        self.assertEqual(result, '/Users/outside-dir')
+
+    def test_relative_one_level_up_is_normalized(self):
+        var_def = {'result': '{project-root}/{value}'}
+        result = apply_result_template(
+            var_def, '../sibling-outputs', {'project-root': '/project/root'}
+        )
+        self.assertEqual(result, '/project/sibling-outputs')
+
+    def test_normal_relative_value_unchanged(self):
+        """Standard in-project relative paths still produce the expected joined path."""
+        var_def = {'result': '{project-root}/{value}'}
+        result = apply_result_template(
+            var_def, '_bmad-output', {'project-root': '/project/root'}
+        )
+        self.assertEqual(result, '/project/root/_bmad-output')
+
 
 class TestLoadModuleYaml(unittest.TestCase):
 

package/tools/{cli → installer}/bmad-cli.js

@@ -1,9 +1,11 @@
+#!/usr/bin/env node
+
 const { program } = require('commander');
 const path = require('node:path');
 const fs = require('node:fs');
 const { execSync } = require('node:child_process');
 const semver = require('semver');
-const prompts = require('./lib/prompts');
+const prompts = require('./prompts');
 
 // The installer flow uses many sequential @clack/prompts, each adding keypress
 // listeners to stdin. Raise the limit to avoid spurious EventEmitter warnings.

package/tools/{cli/lib → installer}/cli-utils.js

@@ -8,7 +8,7 @@ const CLIUtils = {
    */
   getVersion() {
     try {
-      const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+      const packageJson = require(path.join(__dirname, '..', '..', 'package.json'));
       return packageJson.version || 'Unknown';
     } catch {
       return 'Unknown';
@@ -16,10 +16,9 @@ const CLIUtils = {
   },
 
   /**
-   * Display BMAD logo using @clack intro + box
-   * @param {boolean} _clearScreen - Deprecated, ignored (no longer clears screen)
+   * Display BMAD logo and version using @clack intro + box
    */
-  async displayLogo(_clearScreen = true) {
+  async displayLogo() {
     const version = this.getVersion();
     const color = await prompts.getColor();
 

package/tools/{cli → installer}/commands/install.js

@@ -1,7 +1,7 @@
 const path = require('node:path');
-const prompts = require('../lib/prompts');
-const { Installer } = require('../installers/lib/core/installer');
-const { UI } = require('../lib/ui');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
+const { UI } = require('../ui');
 
 const installer = new Installer();
 const ui = new UI();

package/tools/{cli → installer}/commands/status.js

@@ -1,8 +1,8 @@
 const path = require('node:path');
-const prompts = require('../lib/prompts');
-const { Installer } = require('../installers/lib/core/installer');
-const { Manifest } = require('../installers/lib/core/manifest');
-const { UI } = require('../lib/ui');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
+const { Manifest } = require('../core/manifest');
+const { UI } = require('../ui');
 
 const installer = new Installer();
 const manifest = new Manifest();

package/tools/{cli → installer}/commands/uninstall.js

@@ -1,7 +1,7 @@
 const path = require('node:path');
 const fs = require('fs-extra');
-const prompts = require('../lib/prompts');
-const { Installer } = require('../installers/lib/core/installer');
+const prompts = require('../prompts');
+const { Installer } = require('../core/installer');
 
 const installer = new Installer();
 
@@ -62,9 +62,9 @@ module.exports = {
       }
 
       const existingInstall = await installer.getStatus(projectDir);
-      const version = existingInstall.version || 'unknown';
-      const modules = (existingInstall.modules || []).map((m) => m.id || m.name).join(', ');
-      const ides = (existingInstall.ides || []).join(', ');
+      const version = existingInstall.installed ? existingInstall.version : 'unknown';
+      const modules = existingInstall.moduleIds.join(', ');
+      const ides = existingInstall.ides.join(', ');
 
       const outputFolder = await installer.getOutputFolder(projectDir);
 

package/tools/installer/core/config.js

@@ -0,0 +1,52 @@
+/**
+ * Clean install configuration built from user input.
+ * User input comes from either UI answers or headless CLI flags.
+ */
+class Config {
+  constructor({ directory, modules, ides, skipPrompts, verbose, actionType, coreConfig, moduleConfigs, quickUpdate }) {
+    this.directory = directory;
+    this.modules = Object.freeze([...modules]);
+    this.ides = Object.freeze([...ides]);
+    this.skipPrompts = skipPrompts;
+    this.verbose = verbose;
+    this.actionType = actionType;
+    this.coreConfig = coreConfig;
+    this.moduleConfigs = moduleConfigs;
+    this._quickUpdate = quickUpdate;
+    Object.freeze(this);
+  }
+
+  /**
+   * Build a clean install config from raw user input.
+   * @param {Object} userInput - UI answers or CLI flags
+   * @returns {Config}
+   */
+  static build(userInput) {
+    const modules = [...(userInput.modules || [])];
+    if (userInput.installCore && !modules.includes('core')) {
+      modules.unshift('core');
+    }
+
+    return new Config({
+      directory: userInput.directory,
+      modules,
+      ides: userInput.skipIde ? [] : [...(userInput.ides || [])],
+      skipPrompts: userInput.skipPrompts || false,
+      verbose: userInput.verbose || false,
+      actionType: userInput.actionType,
+      coreConfig: userInput.coreConfig || {},
+      moduleConfigs: userInput.moduleConfigs || null,
+      quickUpdate: userInput._quickUpdate || false,
+    });
+  }
+
+  hasCoreConfig() {
+    return this.coreConfig && Object.keys(this.coreConfig).length > 0;
+  }
+
+  isQuickUpdate() {
+    return this._quickUpdate;
+  }
+}
+
+module.exports = { Config };

package/tools/{cli/installers/lib → installer}/core/custom-module-cache.js

@@ -7,7 +7,7 @@
 const fs = require('fs-extra');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const prompts = require('../../../lib/prompts');
+const prompts = require('../prompts');
 
 class CustomModuleCache {
   constructor(bmadDir) {

package/tools/installer/core/existing-install.js

@@ -0,0 +1,127 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+const { Manifest } = require('./manifest');
+
+/**
+ * Immutable snapshot of an existing BMAD installation.
+ * Pure query object — no filesystem operations after construction.
+ */
+class ExistingInstall {
+  #version;
+
+  constructor({ installed, version, hasCore, modules, ides, customModules }) {
+    this.installed = installed;
+    this.#version = version;
+    this.hasCore = hasCore;
+    this.modules = Object.freeze(modules.map((m) => Object.freeze({ ...m })));
+    this.moduleIds = Object.freeze(this.modules.map((m) => m.id));
+    this.ides = Object.freeze([...ides]);
+    this.customModules = Object.freeze([...customModules]);
+    Object.freeze(this);
+  }
+
+  get version() {
+    if (!this.installed) {
+      throw new Error('version is not available when nothing is installed');
+    }
+    return this.#version;
+  }
+
+  static empty() {
+    return new ExistingInstall({
+      installed: false,
+      version: null,
+      hasCore: false,
+      modules: [],
+      ides: [],
+      customModules: [],
+    });
+  }
+
+  /**
+   * Scan a bmad directory and return an immutable snapshot of what's installed.
+   * @param {string} bmadDir - Path to bmad directory
+   * @returns {Promise<ExistingInstall>}
+   */
+  static async detect(bmadDir) {
+    if (!(await fs.pathExists(bmadDir))) {
+      return ExistingInstall.empty();
+    }
+
+    let version = null;
+    let hasCore = false;
+    const modules = [];
+    let ides = [];
+    let customModules = [];
+
+    const manifest = new Manifest();
+    const manifestData = await manifest.read(bmadDir);
+    if (manifestData) {
+      version = manifestData.version;
+      if (manifestData.customModules) {
+        customModules = manifestData.customModules;
+      }
+      if (manifestData.ides) {
+        ides = manifestData.ides.filter((ide) => ide && typeof ide === 'string');
+      }
+    }
+
+    const corePath = path.join(bmadDir, 'core');
+    if (await fs.pathExists(corePath)) {
+      hasCore = true;
+
+      if (!version) {
+        const coreConfigPath = path.join(corePath, 'config.yaml');
+        if (await fs.pathExists(coreConfigPath)) {
+          try {
+            const configContent = await fs.readFile(coreConfigPath, 'utf8');
+            const config = yaml.parse(configContent);
+            if (config.version) {
+              version = config.version;
+            }
+          } catch {
+            // Ignore config read errors
+          }
+        }
+      }
+    }
+
+    if (manifestData && manifestData.modules && manifestData.modules.length > 0) {
+      for (const moduleId of manifestData.modules) {
+        const modulePath = path.join(bmadDir, moduleId);
+        const moduleConfigPath = path.join(modulePath, 'config.yaml');
+
+        const moduleInfo = {
+          id: moduleId,
+          path: modulePath,
+          version: 'unknown',
+        };
+
+        if (await fs.pathExists(moduleConfigPath)) {
+          try {
+            const configContent = await fs.readFile(moduleConfigPath, 'utf8');
+            const config = yaml.parse(configContent);
+            moduleInfo.version = config.version || 'unknown';
+            moduleInfo.name = config.name || moduleId;
+            moduleInfo.description = config.description;
+          } catch {
+            // Ignore config read errors
+          }
+        }
+
+        modules.push(moduleInfo);
+      }
+    }
+
+    const installed = hasCore || modules.length > 0 || !!manifestData;
+
+    if (!installed) {
+      return ExistingInstall.empty();
+    }
+
+    return new ExistingInstall({ installed, version, hasCore, modules, ides, customModules });
+  }
+}
+
+module.exports = { ExistingInstall };

package/tools/installer/core/install-paths.js

@@ -0,0 +1,129 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const { getProjectRoot } = require('../project-root');
+const { BMAD_FOLDER_NAME } = require('../ide/shared/path-utils');
+
+class InstallPaths {
+  static async create(config) {
+    const srcDir = getProjectRoot();
+    await assertReadableDir(srcDir, 'BMAD source root');
+
+    const pkgPath = path.join(srcDir, 'package.json');
+    await assertReadableFile(pkgPath, 'package.json');
+    const version = require(pkgPath).version;
+
+    const projectRoot = path.resolve(config.directory);
+    await ensureWritableDir(projectRoot, 'project root');
+
+    const bmadDir = path.join(projectRoot, BMAD_FOLDER_NAME);
+    const isUpdate = await fs.pathExists(bmadDir);
+
+    const configDir = path.join(bmadDir, '_config');
+    const agentsDir = path.join(configDir, 'agents');
+    const customCacheDir = path.join(configDir, 'custom');
+    const coreDir = path.join(bmadDir, 'core');
+
+    for (const [dir, label] of [
+      [bmadDir, 'bmad directory'],
+      [configDir, 'config directory'],
+      [agentsDir, 'agents config directory'],
+      [customCacheDir, 'custom modules cache'],
+      [coreDir, 'core module directory'],
+    ]) {
+      await ensureWritableDir(dir, label);
+    }
+
+    return new InstallPaths({
+      srcDir,
+      version,
+      projectRoot,
+      bmadDir,
+      configDir,
+      agentsDir,
+      customCacheDir,
+      coreDir,
+      isUpdate,
+    });
+  }
+
+  constructor(props) {
+    Object.assign(this, props);
+    Object.freeze(this);
+  }
+
+  manifestFile() {
+    return path.join(this.configDir, 'manifest.yaml');
+  }
+  agentManifest() {
+    return path.join(this.configDir, 'agent-manifest.csv');
+  }
+  filesManifest() {
+    return path.join(this.configDir, 'files-manifest.csv');
+  }
+  helpCatalog() {
+    return path.join(this.configDir, 'bmad-help.csv');
+  }
+  moduleDir(name) {
+    return path.join(this.bmadDir, name);
+  }
+  moduleConfig(name) {
+    return path.join(this.bmadDir, name, 'config.yaml');
+  }
+}
+
+async function assertReadableDir(dirPath, label) {
+  const stat = await fs.stat(dirPath).catch(() => null);
+  if (!stat) {
+    throw new Error(`${label} does not exist: ${dirPath}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`${label} is not a directory: ${dirPath}`);
+  }
+  try {
+    await fs.access(dirPath, fs.constants.R_OK);
+  } catch {
+    throw new Error(`${label} is not readable: ${dirPath}`);
+  }
+}
+
+async function assertReadableFile(filePath, label) {
+  const stat = await fs.stat(filePath).catch(() => null);
+  if (!stat) {
+    throw new Error(`${label} does not exist: ${filePath}`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`${label} is not a file: ${filePath}`);
+  }
+  try {
+    await fs.access(filePath, fs.constants.R_OK);
+  } catch {
+    throw new Error(`${label} is not readable: ${filePath}`);
+  }
+}
+
+async function ensureWritableDir(dirPath, label) {
+  const stat = await fs.stat(dirPath).catch(() => null);
+  if (stat && !stat.isDirectory()) {
+    throw new Error(`${label} exists but is not a directory: ${dirPath}`);
+  }
+
+  try {
+    await fs.ensureDir(dirPath);
+  } catch (error) {
+    if (error.code === 'EACCES') {
+      throw new Error(`${label}: permission denied creating directory: ${dirPath}`);
+    }
+    if (error.code === 'ENOSPC') {
+      throw new Error(`${label}: no space left on device: ${dirPath}`);
+    }
+    throw new Error(`${label}: cannot create directory: ${dirPath} (${error.message})`);
+  }
+
+  try {
+    await fs.access(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+  } catch {
+    throw new Error(`${label} is not writable: ${dirPath}`);
+  }
+}
+
+module.exports = { InstallPaths };