wizz-method 1.0.0

package/tools/installer/core/manifest.js

@@ -0,0 +1,433 @@
+const path = require('node:path');
+const https = require('node:https');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const fs = require('../fs-native');
+const crypto = require('node:crypto');
+const { resolveModuleVersion } = require('../modules/version-resolver');
+const prompts = require('../prompts');
+
+const execFileAsync = promisify(execFile);
+const NPM_LOOKUP_TIMEOUT_MS = 10_000;
+const NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+
+function isValidNpmPackageName(packageName) {
+  return typeof packageName === 'string' && NPM_PACKAGE_NAME_PATTERN.test(packageName);
+}
+
+class Manifest {
+  /**
+   * Create a new manifest
+   * @param {string} bmadDir - Path to bmad directory
+   * @param {Object} data - Manifest data
+   * @param {Array} installedFiles - List of installed files (no longer used, files tracked in files-manifest.csv)
+   */
+  async create(bmadDir, data, installedFiles = []) {
+    const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+    const yaml = require('yaml');
+
+    // Ensure _config directory exists
+    await fs.ensureDir(path.dirname(manifestPath));
+
+    // Get the BMad version from package.json
+    const bmadVersion = data.version || require(path.join(process.cwd(), 'package.json')).version;
+
+    // Convert module list to new detailed format
+    const moduleDetails = [];
+    if (data.modules && Array.isArray(data.modules)) {
+      for (const moduleName of data.modules) {
+        // Core and BMM modules use the BMad version
+        const moduleVersion = moduleName === 'core' || moduleName === 'bmm' ? bmadVersion : null;
+        const now = data.installDate || new Date().toISOString();
+
+        moduleDetails.push({
+          name: moduleName,
+          version: moduleVersion,
+          installDate: now,
+          lastUpdated: now,
+          source: moduleName === 'core' || moduleName === 'bmm' ? 'built-in' : 'unknown',
+        });
+      }
+    }
+
+    // Structure the manifest data
+    const manifestData = {
+      installation: {
+        version: bmadVersion,
+        installDate: data.installDate || new Date().toISOString(),
+        lastUpdated: data.lastUpdated || new Date().toISOString(),
+      },
+      modules: moduleDetails,
+      ides: data.ides || [],
+    };
+
+    // Write YAML manifest
+    // Clean the manifest data to remove any non-serializable values
+    const cleanManifestData = structuredClone(manifestData);
+
+    const yamlContent = yaml.stringify(cleanManifestData, {
+      indent: 2,
+      lineWidth: 0,
+      sortKeys: false,
+    });
+
+    // Ensure POSIX-compliant final newline
+    const content = yamlContent.endsWith('\n') ? yamlContent : yamlContent + '\n';
+    await fs.writeFile(manifestPath, content, 'utf8');
+    return { success: true, path: manifestPath, filesTracked: 0 };
+  }
+
+  /**
+   * Read existing manifest
+   * @param {string} bmadDir - Path to bmad directory
+   * @returns {Object|null} Manifest data or null if not found
+   */
+  async read(bmadDir) {
+    const yamlPath = path.join(bmadDir, '_config', 'manifest.yaml');
+    const yaml = require('yaml');
+
+    if (await fs.pathExists(yamlPath)) {
+      try {
+        const content = await fs.readFile(yamlPath, 'utf8');
+        const manifestData = yaml.parse(content);
+
+        // Handle new detailed module format
+        const modules = manifestData.modules || [];
+
+        // For backward compatibility: if modules is an array of strings (old format),
+        // the calling code may need the array of names
+        const moduleNames = modules.map((m) => (typeof m === 'string' ? m : m.name));
+
+        // Check if we have the new detailed format
+        const hasDetailedModules = modules.length > 0 && typeof modules[0] === 'object';
+
+        // Flatten the structure for compatibility with existing code
+        return {
+          version: manifestData.installation?.version,
+          installDate: manifestData.installation?.installDate,
+          lastUpdated: manifestData.installation?.lastUpdated,
+          modules: moduleNames, // Simple array of module names for backward compatibility
+          modulesDetailed: hasDetailedModules ? modules : null, // New detailed format
+          ides: manifestData.ides || [],
+        };
+      } catch (error) {
+        await prompts.log.error(`Failed to read YAML manifest: ${error.message}`);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Read raw manifest data without flattening
+   * @param {string} bmadDir - Path to bmad directory
+   * @returns {Object|null} Raw manifest data or null if not found
+   */
+  async _readRaw(bmadDir) {
+    const yamlPath = path.join(bmadDir, '_config', 'manifest.yaml');
+    const yaml = require('yaml');
+
+    if (await fs.pathExists(yamlPath)) {
+      try {
+        const content = await fs.readFile(yamlPath, 'utf8');
+        return yaml.parse(content);
+      } catch (error) {
+        await prompts.log.error(`Failed to read YAML manifest: ${error.message}`);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Flatten manifest for backward compatibility
+   * @param {Object} manifest - Raw manifest data
+   * @returns {Object} Flattened manifest
+   */
+  _flattenManifest(manifest) {
+    const modules = manifest.modules || [];
+    const moduleNames = modules.map((m) => (typeof m === 'string' ? m : m.name));
+    const hasDetailedModules = modules.length > 0 && typeof modules[0] === 'object';
+
+    return {
+      version: manifest.installation?.version,
+      installDate: manifest.installation?.installDate,
+      lastUpdated: manifest.installation?.lastUpdated,
+      modules: moduleNames,
+      modulesDetailed: hasDetailedModules ? modules : null,
+      ides: manifest.ides || [],
+    };
+  }
+
+  /**
+   * Add a module to the manifest with optional version info
+   * If module already exists, update its version info
+   * @param {string} bmadDir - Path to bmad directory
+   * @param {string} moduleName - Module name to add
+   * @param {Object} options - Optional version info
+   */
+  async addModule(bmadDir, moduleName, options = {}) {
+    let manifest = await this._readRaw(bmadDir);
+    if (!manifest) {
+      // Bootstrap a minimal manifest if it doesn't exist yet
+      // (e.g., skill-only modules with no agents to compile)
+      manifest = { modules: [] };
+    }
+
+    if (!manifest.modules) {
+      manifest.modules = [];
+    }
+
+    const existingIndex = manifest.modules.findIndex((m) => m.name === moduleName);
+
+    if (existingIndex === -1) {
+      // Module doesn't exist, add it
+      const entry = {
+        name: moduleName,
+        version: options.version || null,
+        installDate: new Date().toISOString(),
+        lastUpdated: new Date().toISOString(),
+        source: options.source || 'unknown',
+        npmPackage: options.npmPackage || null,
+        repoUrl: options.repoUrl || null,
+      };
+      if (options.channel) entry.channel = options.channel;
+      if (options.sha) entry.sha = options.sha;
+      if (options.localPath) entry.localPath = options.localPath;
+      if (options.rawSource) entry.rawSource = options.rawSource;
+      if (options.registryApprovedTag) entry.registryApprovedTag = options.registryApprovedTag;
+      if (options.registryApprovedSha) entry.registryApprovedSha = options.registryApprovedSha;
+      manifest.modules.push(entry);
+    } else {
+      // Module exists, update its version info
+      const existing = manifest.modules[existingIndex];
+      manifest.modules[existingIndex] = {
+        ...existing,
+        version: options.version === undefined ? existing.version : options.version,
+        source: options.source || existing.source,
+        npmPackage: options.npmPackage === undefined ? existing.npmPackage : options.npmPackage,
+        repoUrl: options.repoUrl === undefined ? existing.repoUrl : options.repoUrl,
+        localPath: options.localPath === undefined ? existing.localPath : options.localPath,
+        channel: options.channel === undefined ? existing.channel : options.channel,
+        sha: options.sha === undefined ? existing.sha : options.sha,
+        rawSource: options.rawSource === undefined ? existing.rawSource : options.rawSource,
+        registryApprovedTag: options.registryApprovedTag === undefined ? existing.registryApprovedTag : options.registryApprovedTag,
+        registryApprovedSha: options.registryApprovedSha === undefined ? existing.registryApprovedSha : options.registryApprovedSha,
+        lastUpdated: new Date().toISOString(),
+      };
+    }
+
+    await this._writeRaw(bmadDir, manifest);
+  }
+
+  /**
+   * Get all modules with their version info
+   * @param {string} bmadDir - Path to bmad directory
+   * @returns {Array} Array of module info objects
+   */
+  async getAllModuleVersions(bmadDir) {
+    const manifest = await this._readRaw(bmadDir);
+    if (!manifest || !manifest.modules) {
+      return [];
+    }
+
+    return manifest.modules;
+  }
+
+  /**
+   * Write raw manifest data to file
+   * @param {string} bmadDir - Path to bmad directory
+   * @param {Object} manifestData - Raw manifest data to write
+   */
+  async _writeRaw(bmadDir, manifestData) {
+    const yaml = require('yaml');
+    const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+
+    await fs.ensureDir(path.dirname(manifestPath));
+
+    const cleanManifestData = structuredClone(manifestData);
+
+    const yamlContent = yaml.stringify(cleanManifestData, {
+      indent: 2,
+      lineWidth: 0,
+      sortKeys: false,
+    });
+
+    const content = yamlContent.endsWith('\n') ? yamlContent : yamlContent + '\n';
+    await fs.writeFile(manifestPath, content, 'utf8');
+  }
+
+  /**
+   * Calculate SHA256 hash of a file
+   * @param {string} filePath - Path to file
+   * @returns {string} SHA256 hash
+   */
+  async calculateFileHash(filePath) {
+    try {
+      const content = await fs.readFile(filePath);
+      return crypto.createHash('sha256').update(content).digest('hex');
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get module version info from source
+   * @param {string} moduleName - Module name/code
+   * @param {string} bmadDir - Path to bmad directory
+   * @param {string} moduleSourcePath - Optional source path for custom modules
+   * @returns {Object} Version info object with version, source, npmPackage, repoUrl
+   */
+  async getModuleVersionInfo(moduleName, bmadDir, moduleSourcePath = null) {
+    // Resolve source type first, then read version with the correct path context
+    if (['core', 'bmm'].includes(moduleName)) {
+      const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
+      return {
+        version: versionInfo.version,
+        source: 'built-in',
+        npmPackage: null,
+        repoUrl: null,
+      };
+    }
+
+    // Check if this is an external official module
+    const { ExternalModuleManager } = require('../modules/external-manager');
+    const extMgr = new ExternalModuleManager();
+    const moduleInfo = await extMgr.getModuleByCode(moduleName);
+
+    if (moduleInfo) {
+      const externalResolution = extMgr.getResolution(moduleName);
+      const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
+      return {
+        // Git tag recorded during install trumps the on-disk package.json
+        // version, so the manifest carries "v1.7.0" instead of "1.7.0".
+        version: externalResolution?.version || versionInfo.version,
+        source: 'external',
+        npmPackage: moduleInfo.npmPackage || null,
+        repoUrl: moduleInfo.url || null,
+        channel: externalResolution?.channel || null,
+        sha: externalResolution?.sha || null,
+      };
+    }
+
+    // Check if this is a custom module (from user-provided URL or local path)
+    const { CustomModuleManager } = require('../modules/custom-module-manager');
+    const customMgr = new CustomModuleManager();
+    const resolved = customMgr.getResolution(moduleName);
+    const customSource = await customMgr.findModuleSourceByCode(moduleName, { bmadDir });
+    if (customSource || resolved) {
+      const versionInfo = await resolveModuleVersion(moduleName, {
+        moduleSourcePath: moduleSourcePath || customSource,
+        fallbackVersion: resolved?.version,
+        marketplacePluginNames: resolved?.pluginName ? [resolved.pluginName] : [],
+      });
+      const hasGitClone = !!resolved?.repoUrl;
+      return {
+        // Prefer the git ref we actually cloned over the package.json version.
+        version: resolved?.cloneRef || (hasGitClone ? 'main' : versionInfo.version),
+        source: 'custom',
+        npmPackage: null,
+        repoUrl: resolved?.repoUrl || null,
+        localPath: resolved?.localPath || null,
+        channel: hasGitClone ? (resolved?.cloneRef ? 'pinned' : 'next') : null,
+        sha: resolved?.cloneSha || null,
+        rawSource: resolved?.rawInput || null,
+      };
+    }
+
+    // Unknown module
+    const versionInfo = await resolveModuleVersion(moduleName, { moduleSourcePath });
+    return {
+      version: versionInfo.version,
+      source: 'unknown',
+      npmPackage: null,
+      repoUrl: null,
+    };
+  }
+
+  /**
+   * Fetch latest version from npm for a package
+   * @param {string} packageName - npm package name
+   * @returns {string|null} Latest version or null
+   */
+  async fetchNpmVersion(packageName) {
+    if (!isValidNpmPackageName(packageName)) {
+      return null;
+    }
+
+    try {
+      // Try using npm view first (more reliable)
+      try {
+        const { stdout } = await execFileAsync('npm', ['view', packageName, 'version'], {
+          encoding: 'utf8',
+          timeout: NPM_LOOKUP_TIMEOUT_MS,
+        });
+        return stdout.trim();
+      } catch {
+        // Fallback to npm registry API
+        return new Promise((resolve) => {
+          const request = https.get(`https://registry.npmjs.org/${encodeURIComponent(packageName)}`, (res) => {
+            let data = '';
+            res.on('data', (chunk) => (data += chunk));
+            res.on('end', () => {
+              try {
+                const pkg = JSON.parse(data);
+                resolve(pkg['dist-tags']?.latest || pkg.version || null);
+              } catch {
+                resolve(null);
+              }
+            });
+          });
+
+          request.setTimeout(NPM_LOOKUP_TIMEOUT_MS, () => {
+            request.destroy();
+            resolve(null);
+          });
+
+          request.on('error', () => resolve(null));
+        });
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check for available updates for installed modules
+   * @param {string} bmadDir - Path to bmad directory
+   * @returns {Array} Array of update info objects
+   */
+  async checkForUpdates(bmadDir) {
+    const semver = require('semver');
+    const modules = await this.getAllModuleVersions(bmadDir);
+    const updates = [];
+
+    for (const module of modules) {
+      if (!module.npmPackage) {
+        continue; // Skip modules without npm package (built-in)
+      }
+
+      const latestVersion = await this.fetchNpmVersion(module.npmPackage);
+      if (!latestVersion) {
+        continue;
+      }
+
+      const installedVersion = semver.valid(module.version) || semver.valid(semver.coerce(module.version || ''));
+      const availableVersion = semver.valid(latestVersion) || semver.valid(semver.coerce(latestVersion));
+
+      if (installedVersion && availableVersion && semver.gt(availableVersion, installedVersion)) {
+        updates.push({
+          name: module.name,
+          installedVersion: module.version,
+          latestVersion: latestVersion,
+          npmPackage: module.npmPackage,
+          updateAvailable: true,
+        });
+      }
+    }
+
+    return updates;
+  }
+}
+
+module.exports = { Manifest };

package/tools/installer/core/python-check.js

@@ -0,0 +1,199 @@
+const { spawnSync } = require('node:child_process');
+const prompts = require('../prompts');
+
+// Python 3.11 added stdlib `tomllib` (PEP 680), which the shared scripts in
+// src/scripts/ (resolve_config.py, resolve_customization.py) require to read
+// BMAD's TOML config files. memlog.py is more lenient and runs on 3.8+.
+const PYTHON_FULL_SUPPORT = { major: 3, minor: 11 };
+const PYTHON_PARTIAL_SUPPORT = { major: 3, minor: 8 };
+
+// Every runtime call site (skill steps, on_complete hooks) invokes a literal
+// `python3`, so only that command's version vouches for BMAD features. The
+// fallback probes exist to tell the user "Python is installed, but not under
+// the name BMAD uses" instead of a misleading "No Python found".
+const RUNTIME_COMMAND = 'python3';
+const PROBE_CANDIDATES =
+  process.platform === 'win32'
+    ? [
+        { command: 'python3', args: ['--version'] },
+        { command: 'py', args: ['-3', '--version'] },
+        { command: 'python', args: ['--version'] },
+      ]
+    : [
+        { command: 'python3', args: ['--version'] },
+        { command: 'python', args: ['--version'] },
+      ];
+
+/**
+ * Parse a `python --version` output line into version parts.
+ * Python 3 prints to stdout; Python 2 printed to stderr — callers pass both.
+ * @param {string} output - Combined stdout/stderr from `python --version`
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
+ */
+function parsePythonVersion(output) {
+  if (!output) return null;
+  const match = output.match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] || 0),
+    raw: `${match[1]}.${match[2]}.${match[3] || 0}`,
+  };
+}
+
+/**
+ * Classify a detected Python version against BMAD's feature requirements.
+ * @param {{major: number, minor: number}|null} version
+ * @returns {'full'|'partial'|'unsupported'|'none'}
+ */
+function classifyPython(version) {
+  if (!version) return 'none';
+  const { major, minor } = version;
+  if (major > PYTHON_FULL_SUPPORT.major || (major === PYTHON_FULL_SUPPORT.major && minor >= PYTHON_FULL_SUPPORT.minor)) {
+    return 'full';
+  }
+  if (major === PYTHON_PARTIAL_SUPPORT.major && minor >= PYTHON_PARTIAL_SUPPORT.minor) {
+    return 'partial';
+  }
+  return 'unsupported';
+}
+
+/**
+ * Run one probe candidate and return its parsed version, or null.
+ * @param {{command: string, args: string[]}} candidate
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
+ */
+function probeVersion(candidate) {
+  const run = (extra = {}) =>
+    spawnSync(candidate.command, candidate.args, {
+      encoding: 'utf8',
+      timeout: 5000,
+      windowsHide: true,
+      ...extra,
+    });
+  let result = run();
+  // Node >=18.20/20.12 refuses to spawn .bat/.cmd without a shell
+  // (CVE-2024-27980 hardening) and reports EINVAL — pyenv-win ships its
+  // python shims as .bat. Args here are static literals, so a shell retry
+  // is injection-safe.
+  if (result.error && result.error.code === 'EINVAL' && process.platform === 'win32') {
+    result = run({ shell: true });
+  }
+  if (result.error) return null;
+  return parsePythonVersion(`${result.stdout || ''}\n${result.stderr || ''}`);
+}
+
+/**
+ * Probe the local environment for a Python interpreter.
+ * Tries each candidate command and returns the first that reports a version.
+ * `isRuntimeCommand` is true only when the match is `python3` — the command
+ * BMAD scripts actually invoke.
+ * @returns {{command: string, version: {major: number, minor: number, patch: number, raw: string}, isRuntimeCommand: boolean}|null}
+ */
+function detectPython() {
+  for (const candidate of PROBE_CANDIDATES) {
+    try {
+      const version = probeVersion(candidate);
+      if (version) {
+        const display = candidate.args.length > 1 ? `${candidate.command} ${candidate.args.slice(0, -1).join(' ')}` : candidate.command;
+        return { command: display, version, isRuntimeCommand: candidate.command === RUNTIME_COMMAND };
+      }
+    } catch {
+      // Candidate not runnable — try the next one.
+    }
+  }
+  return null;
+}
+
+function upgradeHints() {
+  return [
+    'How to get Python 3.11+ (as `python3`):',
+    '  macOS:        brew install python3',
+    '  Windows:      winget install Python.Python.3.12  (then ensure `python3` resolves, e.g. enable the python3 alias)',
+    '  Linux/WSL:    sudo apt install python3  (Ubuntu 24.04+ ships 3.12; older distros: use pyenv or deadsnakes)',
+    '  Docker:       add python3 to your image (e.g. apk add python3 / apt-get install -y python3)',
+  ].join('\n');
+}
+
+/**
+ * Check the local Python environment and warn about degraded BMAD features.
+ *
+ * Warn-don't-block: most of BMAD works without Python, so the install always
+ * may proceed — but the user must explicitly acknowledge the warning so it
+ * can't scroll past unseen. In non-interactive runs (--yes, or stdin is not
+ * a TTY) the warning is logged and the install continues without a prompt.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.nonInteractive=false] - Skip the ack prompt (--yes, or no TTY)
+ * @returns {Promise<{status: string, detected: Object|null}>}
+ */
+async function checkPythonEnvironment({ nonInteractive = false } = {}) {
+  // Called via module.exports so tests can stub detection.
+  const detected = module.exports.detectPython();
+  const status = classifyPython(detected ? detected.version : null);
+
+  if (status === 'full' && detected.isRuntimeCommand) {
+    await prompts.log.success(`Python ${detected.version.raw} detected (${detected.command}) — all BMAD features supported.`);
+    return { status, detected };
+  }
+
+  if (detected && !detected.isRuntimeCommand) {
+    await prompts.log.warn(
+      `Python ${detected.version.raw} found via \`${detected.command}\`, but BMAD scripts invoke \`python3\`, which is not on PATH.\n` +
+        `Python-powered features (memlog session memory, TOML config resolution) won't run until \`python3\` resolves —\n` +
+        `add a python3 alias/shim, or reinstall Python with the python3 launcher enabled.`,
+    );
+  } else if (status === 'partial') {
+    await prompts.log.warn(
+      `Python ${detected.version.raw} detected (${detected.command}) — BMAD's TOML config tools need Python 3.11+ (stdlib tomllib).\n` +
+        `Works: memlog session memory. Won't work: config/customization resolution scripts.`,
+    );
+  } else {
+    const found =
+      status === 'unsupported' ? `Python ${detected.version.raw} detected (${detected.command}) — too old.` : 'No Python found on PATH.';
+    await prompts.log.warn(
+      `${found} BMAD installs fine without it, but Python-powered features\n` +
+        `(memlog session memory, TOML config resolution) won't run until Python 3.11+ is available.`,
+    );
+  }
+  await prompts.note(upgradeHints(), 'Python 3.11+ recommended');
+
+  if (nonInteractive) {
+    await prompts.log.info('Continuing anyway (non-interactive run). You can fix Python later — no reinstall needed.');
+    return { status, detected };
+  }
+
+  const choice = await prompts.select({
+    message: "BMAD's Python-powered features won't work yet. How do you want to proceed?",
+    choices: [
+      {
+        name: 'Continue install',
+        value: 'continue',
+        hint: 'BMAD works without Python — you can fix Python later, no reinstall needed',
+      },
+      {
+        name: 'Quit and fix Python first',
+        value: 'quit',
+        hint: 'make Python 3.11+ available as python3, then re-run the installer',
+      },
+    ],
+    default: 'continue',
+  });
+
+  if (choice === 'quit') {
+    await prompts.cancel('Make Python 3.11+ available as `python3` (see hints above), then re-run the installer.');
+    process.exit(0);
+  }
+
+  return { status, detected };
+}
+
+module.exports = {
+  checkPythonEnvironment,
+  detectPython,
+  parsePythonVersion,
+  classifyPython,
+  PYTHON_FULL_SUPPORT,
+  PYTHON_PARTIAL_SUPPORT,
+};