wizz-method 1.0.0

package/tools/installer/modules/version-resolver.js

@@ -0,0 +1,336 @@
+const path = require('node:path');
+const semver = require('semver');
+const yaml = require('yaml');
+const fs = require('../fs-native');
+const { getExternalModuleCachePath, getModulePath, resolveInstalledModuleYaml } = require('../project-root');
+
+const DEFAULT_PARENT_DEPTH = 8;
+
+/**
+ * Resolve a module version from authoritative on-disk metadata.
+ * Preference order:
+ *   1. package.json nearest the module source/cache root
+ *   2. module.yaml in the module source directory
+ *   3. .claude-plugin/marketplace.json
+ *   4. caller-provided fallback version
+ *
+ * @param {string} moduleName - Module code/name
+ * @param {Object} [options]
+ * @param {string} [options.moduleSourcePath] - Directory containing module.yaml
+ * @param {string} [options.fallbackVersion] - Final fallback when no metadata is found
+ * @param {string[]} [options.marketplacePluginNames] - Preferred marketplace plugin names
+ * @returns {Promise<{version: string|null, source: string|null, path: string|null}>}
+ */
+async function resolveModuleVersion(moduleName, options = {}) {
+  const moduleSourcePath = await normalizeDirectoryPath(options.moduleSourcePath);
+  const packageJsonPath = await findPackageJsonPath(moduleName, moduleSourcePath);
+
+  if (packageJsonPath) {
+    const packageVersion = await readPackageJsonVersion(packageJsonPath);
+    if (packageVersion) {
+      return {
+        version: packageVersion,
+        source: 'package.json',
+        path: packageJsonPath,
+      };
+    }
+  }
+
+  const moduleYamlPath = await findModuleYamlPath(moduleName, moduleSourcePath);
+  if (moduleYamlPath) {
+    const moduleVersion = await readModuleYamlVersion(moduleYamlPath);
+    if (moduleVersion) {
+      return {
+        version: moduleVersion,
+        source: 'module.yaml',
+        path: moduleYamlPath,
+      };
+    }
+  }
+
+  const marketplaceVersion = await findMarketplaceVersion(moduleName, moduleSourcePath, options.marketplacePluginNames || []);
+  if (marketplaceVersion) {
+    return marketplaceVersion;
+  }
+
+  const fallbackVersion = normalizeVersion(options.fallbackVersion);
+  if (fallbackVersion) {
+    return {
+      version: fallbackVersion,
+      source: 'fallback',
+      path: null,
+    };
+  }
+
+  return {
+    version: null,
+    source: null,
+    path: null,
+  };
+}
+
+async function findPackageJsonPath(moduleName, moduleSourcePath) {
+  const roots = await buildSearchRoots(moduleName, moduleSourcePath);
+
+  for (const root of roots) {
+    const packageJsonPath = await findNearestUpwardFile(root.searchDir, 'package.json', { boundaryDir: root.boundaryDir });
+    if (packageJsonPath) {
+      return packageJsonPath;
+    }
+  }
+
+  return null;
+}
+
+async function findModuleYamlPath(moduleName, moduleSourcePath) {
+  if (moduleSourcePath) {
+    const directModuleYamlPath = path.join(moduleSourcePath, 'module.yaml');
+    if (await fs.pathExists(directModuleYamlPath)) {
+      return directModuleYamlPath;
+    }
+  }
+
+  return resolveInstalledModuleYaml(moduleName);
+}
+
+async function findMarketplaceVersion(moduleName, moduleSourcePath, marketplacePluginNames) {
+  const roots = await buildSearchRoots(moduleName, moduleSourcePath);
+
+  for (const root of roots) {
+    const marketplacePath = await findNearestUpwardFile(root.searchDir, path.join('.claude-plugin', 'marketplace.json'), {
+      boundaryDir: root.boundaryDir,
+    });
+    if (!marketplacePath) {
+      continue;
+    }
+
+    const data = await readJsonFile(marketplacePath);
+    if (!data) {
+      continue;
+    }
+
+    const version = extractMarketplaceVersion(data, moduleName, marketplacePluginNames);
+    if (version) {
+      return {
+        version,
+        source: 'marketplace.json',
+        path: marketplacePath,
+      };
+    }
+  }
+
+  return null;
+}
+
+async function buildSearchRoots(moduleName, moduleSourcePath) {
+  const roots = [];
+  const seen = new Set();
+
+  const addRoot = async (candidate) => {
+    const normalized = await normalizeExistingDirectory(candidate);
+    if (!normalized || seen.has(normalized)) {
+      return;
+    }
+
+    seen.add(normalized);
+    roots.push({
+      searchDir: normalized,
+      boundaryDir: await findSearchBoundary(normalized),
+    });
+  };
+
+  await addRoot(moduleSourcePath);
+
+  if (moduleName === 'core' || moduleName === 'bmm') {
+    await addRoot(getModulePath(moduleName));
+  } else {
+    await addRoot(getExternalModuleCachePath(moduleName));
+  }
+
+  return roots;
+}
+
+async function findNearestUpwardFile(startDir, relativeFilePath, options = {}) {
+  const normalizedStartDir = await normalizeExistingDirectory(startDir);
+  if (!normalizedStartDir) {
+    return null;
+  }
+
+  const maxDepth = options.maxDepth ?? DEFAULT_PARENT_DEPTH;
+  const normalizedBoundaryDir = await normalizeDirectoryPath(options.boundaryDir);
+  let currentDir = normalizedStartDir;
+  for (let depth = 0; depth <= maxDepth; depth++) {
+    const candidate = path.join(currentDir, relativeFilePath);
+    if (await fs.pathExists(candidate)) {
+      return candidate;
+    }
+
+    if (normalizedBoundaryDir && currentDir === normalizedBoundaryDir) {
+      break;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
+async function findSearchBoundary(startDir) {
+  const normalizedStartDir = await normalizeExistingDirectory(startDir);
+  if (!normalizedStartDir) {
+    return null;
+  }
+
+  let currentDir = normalizedStartDir;
+  for (let depth = 0; depth <= DEFAULT_PARENT_DEPTH; depth++) {
+    if (
+      (await fs.pathExists(path.join(currentDir, 'package.json'))) ||
+      (await fs.pathExists(path.join(currentDir, '.claude-plugin', 'marketplace.json'))) ||
+      (await fs.pathExists(path.join(currentDir, '.git')))
+    ) {
+      return currentDir;
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return normalizedStartDir;
+}
+
+async function normalizeDirectoryPath(candidate) {
+  if (!candidate) {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(candidate);
+  try {
+    const stats = await fs.stat(resolvedPath);
+    return stats.isDirectory() ? resolvedPath : path.dirname(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+async function normalizeExistingDirectory(candidate) {
+  const normalized = await normalizeDirectoryPath(candidate);
+  if (!normalized) {
+    return null;
+  }
+
+  if (!(await fs.pathExists(normalized))) {
+    return null;
+  }
+
+  return normalized;
+}
+
+async function readPackageJsonVersion(packageJsonPath) {
+  const data = await readJsonFile(packageJsonPath);
+  return normalizeVersion(data?.version);
+}
+
+async function readModuleYamlVersion(moduleYamlPath) {
+  try {
+    const content = await fs.readFile(moduleYamlPath, 'utf8');
+    const data = yaml.parse(content);
+    return normalizeVersion(data?.version || data?.module_version || data?.moduleVersion);
+  } catch {
+    return null;
+  }
+}
+
+async function readJsonFile(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function extractMarketplaceVersion(data, moduleName, marketplacePluginNames = []) {
+  const plugins = Array.isArray(data?.plugins) ? data.plugins : [];
+  if (plugins.length === 0) {
+    return null;
+  }
+
+  const preferredNames = new Set(
+    [moduleName, ...marketplacePluginNames]
+      .filter((value) => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter(Boolean),
+  );
+
+  const exactMatches = [];
+  const fallbackVersions = [];
+
+  for (const plugin of plugins) {
+    const version = normalizeVersion(plugin?.version);
+    if (!version) {
+      continue;
+    }
+
+    fallbackVersions.push(version);
+
+    const pluginNames = [plugin?.name, plugin?.code].filter((value) => typeof value === 'string').map((value) => value.trim());
+    if (pluginNames.some((name) => preferredNames.has(name))) {
+      exactMatches.push(version);
+    }
+  }
+
+  return pickBestVersion(exactMatches.length > 0 ? exactMatches : fallbackVersions);
+}
+
+function pickBestVersion(versions) {
+  const candidates = versions.map(normalizeVersion).filter(Boolean);
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  candidates.sort(compareVersionsDescending);
+  return candidates[0];
+}
+
+function compareVersionsDescending(left, right) {
+  const leftSemver = normalizeSemver(left);
+  const rightSemver = normalizeSemver(right);
+
+  if (leftSemver && rightSemver) {
+    return semver.rcompare(leftSemver, rightSemver);
+  }
+
+  if (leftSemver) {
+    return -1;
+  }
+
+  if (rightSemver) {
+    return 1;
+  }
+
+  return right.localeCompare(left, undefined, { numeric: true, sensitivity: 'base' });
+}
+
+function normalizeSemver(version) {
+  return semver.valid(version) || semver.valid(semver.coerce(version));
+}
+
+function normalizeVersion(version) {
+  if (typeof version !== 'string') {
+    return null;
+  }
+
+  const trimmed = version.trim();
+  return trimmed || null;
+}
+
+module.exports = {
+  resolveModuleVersion,
+};

package/tools/installer/project-root.js

@@ -0,0 +1,224 @@
+const path = require('node:path');
+const os = require('node:os');
+const yaml = require('yaml');
+const fs = require('./fs-native');
+
+/**
+ * Find the BMAD project root directory by looking for package.json
+ * or specific BMAD markers
+ */
+function findProjectRoot(startPath = __dirname) {
+  let currentPath = path.resolve(startPath);
+
+  // Keep going up until we find package.json with bmad-method
+  while (currentPath !== path.dirname(currentPath)) {
+    const packagePath = path.join(currentPath, 'package.json');
+
+    if (fs.existsSync(packagePath)) {
+      try {
+        const pkg = fs.readJsonSync(packagePath);
+        // Check if this is the BMAD project
+        if (pkg.name === 'bmad-method' || fs.existsSync(path.join(currentPath, 'src', 'core-skills'))) {
+          return currentPath;
+        }
+      } catch {
+        // Continue searching
+      }
+    }
+
+    // Also check for src/core-skills as a marker
+    if (fs.existsSync(path.join(currentPath, 'src', 'core-skills', 'agents'))) {
+      return currentPath;
+    }
+
+    currentPath = path.dirname(currentPath);
+  }
+
+  // If we can't find it, use process.cwd() as fallback
+  return process.cwd();
+}
+
+// Cache the project root after first calculation
+let cachedRoot = null;
+
+function getProjectRoot() {
+  if (!cachedRoot) {
+    cachedRoot = findProjectRoot();
+  }
+  return cachedRoot;
+}
+
+/**
+ * Get path to source directory
+ */
+function getSourcePath(...segments) {
+  return path.join(getProjectRoot(), 'src', ...segments);
+}
+
+/**
+ * Get path to a module's directory
+ * bmm is a built-in module directly under src/
+ * core is also directly under src/
+ * All other modules are stored remote
+ */
+function getModulePath(moduleName, ...segments) {
+  if (moduleName === 'core') {
+    return getSourcePath('core-skills', ...segments);
+  }
+  if (moduleName === 'bmm') {
+    return getSourcePath('bmm-skills', ...segments);
+  }
+  return getSourcePath('modules', moduleName, ...segments);
+}
+
+/**
+ * Path to the local external-module clone cache.
+ * External official modules (bmb, cis, gds, tea, wds, etc.) are cloned here
+ * by ExternalModuleManager during install and are not copied into <src>/modules/.
+ */
+function getExternalModuleCachePath(moduleName, ...segments) {
+  const base = process.env.BMAD_EXTERNAL_MODULES_CACHE || path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
+  return path.join(base, moduleName, ...segments);
+}
+
+/**
+ * Locate an installed module's `module.yaml` by filesystem lookup only.
+ *
+ * Built-in modules (core, bmm) live under <src>. External official modules are
+ * cloned into ~/.bmad/cache/external-modules/<name>/ with varying internal
+ * layouts (some at src/module.yaml, some at skills/module.yaml, some nested).
+ * Url-source custom modules are cloned into ~/.bmad/cache/custom-modules/<host>/<owner>/<repo>/
+ * and are resolved by walking the cache and matching `code` or `name` from the
+ * discovered module.yaml. Local custom-source modules are not cached; their
+ * path is read from the CustomModuleManager resolution cache set during the
+ * same install run.
+ * This mirrors the candidate-path search in
+ * ExternalModuleManager.findExternalModuleSource but performs no git/network
+ * work, which keeps it safe to call during manifest writing.
+ *
+ * @param {string} moduleName
+ * @returns {Promise<string|null>} Absolute path to module.yaml, or null if not found.
+ */
+async function resolveInstalledModuleYaml(moduleName) {
+  const builtIn = path.join(getModulePath(moduleName), 'module.yaml');
+  if (await fs.pathExists(builtIn)) return builtIn;
+
+  // Collect every module.yaml under a root using the standard candidate paths.
+  // Url-source repos can host multiple plugins (discovery mode), so we need all
+  // matches, not just the first. Returned in priority order.
+  async function searchRootAll(root) {
+    const results = [];
+    for (const dir of ['skills', 'src']) {
+      const direct = path.join(root, dir, 'module.yaml');
+      if (await fs.pathExists(direct)) results.push(direct);
+
+      const dirPath = path.join(root, dir);
+      if (await fs.pathExists(dirPath)) {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          const nested = path.join(dirPath, entry.name, 'module.yaml');
+          if (await fs.pathExists(nested)) results.push(nested);
+        }
+      }
+    }
+
+    // BMB standard: {setup-skill}/assets/module.yaml (setup skill is any *-setup directory).
+    // Check at the repo root, and also under src/skills/ and skills/ since
+    // marketplace plugins commonly nest skills under src/skills/<name>/.
+    const setupSearchRoots = [root, path.join(root, 'src', 'skills'), path.join(root, 'skills')];
+    for (const setupRoot of setupSearchRoots) {
+      if (!(await fs.pathExists(setupRoot))) continue;
+      const entries = await fs.readdir(setupRoot, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.endsWith('-setup')) continue;
+        const setupAssets = path.join(setupRoot, entry.name, 'assets', 'module.yaml');
+        if (await fs.pathExists(setupAssets)) results.push(setupAssets);
+      }
+    }
+
+    const atRoot = path.join(root, 'module.yaml');
+    if (await fs.pathExists(atRoot)) results.push(atRoot);
+    return results;
+  }
+
+  // Backwards-compatible single-result variant for the existing external-cache
+  // and resolution-cache fallbacks (one module per root by construction).
+  async function searchRoot(root) {
+    const all = await searchRootAll(root);
+    return all.length > 0 ? all[0] : null;
+  }
+
+  const cacheRoot = getExternalModuleCachePath(moduleName);
+  if (await fs.pathExists(cacheRoot)) {
+    const found = await searchRoot(cacheRoot);
+    if (found) return found;
+  }
+
+  // Community modules are cloned to ~/.bmad/cache/community-modules/<name>/
+  // (parallel to the external-modules cache used above). Search there too so
+  // collectAgentsFromModuleYaml and writeCentralConfig can locate community
+  // module.yaml files regardless of how nested the layout is.
+  const communityCacheRoot = path.join(os.homedir(), '.bmad', 'cache', 'community-modules', moduleName);
+  if (await fs.pathExists(communityCacheRoot)) {
+    const found = await searchRoot(communityCacheRoot);
+    if (found) return found;
+  }
+
+  // Fallback: local custom-source modules store their source path in the
+  // CustomModuleManager resolution cache populated during the same install run.
+  // Match by code OR name since callers may use either form.
+  try {
+    const { CustomModuleManager } = require('./modules/custom-module-manager');
+    for (const [, mod] of CustomModuleManager._resolutionCache) {
+      if ((mod.code === moduleName || mod.name === moduleName) && mod.localPath) {
+        const found = await searchRoot(mod.localPath);
+        if (found) return found;
+      }
+    }
+  } catch {
+    // Resolution cache unavailable — continue
+  }
+
+  // Fallback: url-source custom modules cloned to ~/.bmad/cache/custom-modules/.
+  // Walk every cached repo, enumerate ALL module.yaml files via searchRootAll
+  // (a single repo can host multiple plugins in discovery mode), and match by
+  // the yaml's `code` or `name` field. This works on re-install runs where
+  // _resolutionCache is empty and covers both discovery-mode (with marketplace.json)
+  // and direct-mode modules, since we identify repo roots by .bmad-source.json
+  // (written by cloneRepo) or .claude-plugin/ rather than by marketplace.json.
+  try {
+    const customCacheDir = path.join(os.homedir(), '.bmad', 'cache', 'custom-modules');
+    if (await fs.pathExists(customCacheDir)) {
+      const { CustomModuleManager } = require('./modules/custom-module-manager');
+      const customMgr = new CustomModuleManager();
+      const repoRoots = await customMgr._findCacheRepoRoots(customCacheDir);
+      for (const { repoPath } of repoRoots) {
+        const candidates = await searchRootAll(repoPath);
+        for (const candidate of candidates) {
+          try {
+            const parsed = yaml.parse(await fs.readFile(candidate, 'utf8'));
+            if (parsed && (parsed.code === moduleName || parsed.name === moduleName)) {
+              return candidate;
+            }
+          } catch {
+            // Malformed yaml — skip
+          }
+        }
+      }
+    }
+  } catch {
+    // Custom-modules cache walk failed — continue
+  }
+
+  return null;
+}
+
+module.exports = {
+  getProjectRoot,
+  getSourcePath,
+  getModulePath,
+  getExternalModuleCachePath,
+  resolveInstalledModuleYaml,
+  findProjectRoot,
+};