bmad-plus 0.12.2 → 0.14.0

package/tools/cli/lib/python-health.js

@@ -0,0 +1,233 @@
+/** Opt-in verification of an existing pack environment. Never installs a runtime. */
+const fs = require('node:fs');
+const path = require('node:path');
+const { MIN_PYTHON, venvPython, defaultRunner } = require('./python-provision');
+
+const TIMEOUT_MS = 15_000;
+const MAX_BUFFER = 64 * 1024;
+const MODULE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+// -I excludes project/PYTHONPATH imports; -B avoids bytecode writes. Importing
+// installed dependencies still executes their code, so callers must opt in.
+const PROBE = [
+  'import contextlib, importlib, json, os, sys',
+  'expected, minimum, names = sys.argv[1], json.loads(sys.argv[2]), json.loads(sys.argv[3])',
+  'normalize = lambda value: os.path.normcase(os.path.realpath(value))',
+  'prefix, base = normalize(sys.prefix), normalize(sys.base_prefix)',
+  'version = list(sys.version_info[:3])',
+  'checks = [{"name": name, "status": "not-verified"} for name in names]',
+  'if prefix == normalize(expected) and prefix != base and version >= minimum:',
+  '    with open(os.devnull, "w", encoding="utf-8") as sink:',
+  '        with contextlib.redirect_stdout(sink), contextlib.redirect_stderr(sink):',
+  '            for check in checks:',
+  '                try:',
+  '                    importlib.import_module(check["name"])',
+  '                    check["status"] = "verified"',
+  '                except BaseException:',
+  '                    check["status"] = "failed"',
+  'print(json.dumps({"schemaVersion": 1, "prefix": prefix, "basePrefix": base, "version": version, "modules": checks}))',
+].join('\n');
+
+function minimumParts(minimum) {
+  if (typeof minimum !== 'string' || !/^\d+\.\d+(?:\.\d+)?$/.test(minimum)) return null;
+  const parts = minimum.split('.').map(Number);
+  if (parts.length === 2) parts.push(0);
+  return parts[0] > 0 && parts.every((part) => Number.isSafeInteger(part) && part >= 0)
+    ? parts
+    : null;
+}
+
+function normalizedPath(value) {
+  const resolved = path.resolve(value);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function environmentPaths(projectDir, packId) {
+  const directory = path.join(projectDir, '.bmad', 'venv', packId);
+  const executable = venvPython(directory);
+  const parent = path.dirname(executable);
+  let cursor = path.parse(parent).root;
+  for (const component of parent.slice(cursor.length).split(path.sep)) {
+    cursor = path.join(cursor, component);
+    const stat = fs.lstatSync(cursor);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return null;
+  }
+  const config = fs.lstatSync(path.join(directory, 'pyvenv.cfg'));
+  if (config.isSymbolicLink() || !config.isFile()) return null;
+  const binary = fs.lstatSync(executable);
+  if (binary.isSymbolicLink()) {
+    // A Unix venv normally links bin/python to its base interpreter. Keep that
+    // executable path: resolving it before invocation would lose the venv.
+    if (process.platform === 'win32' || !fs.statSync(executable).isFile()) return null;
+  } else if (!binary.isFile()) return null;
+  return { directory, executable };
+}
+
+/**
+ * Verify the actual prefix, version and declared imports in .bmad/venv/<packId>.
+ * One bounded interpreter invocation; no PATH fallback, repair or provisioning.
+ */
+function probePythonRuntime({
+  projectDir,
+  packId,
+  minimum = `${MIN_PYTHON.major}.${MIN_PYTHON.minor}`,
+  verifyModules = [],
+  runner = defaultRunner,
+} = {}) {
+  const started = Date.now();
+  const floor = minimumParts(minimum);
+  const validNames =
+    Array.isArray(verifyModules) &&
+    verifyModules.length <= 64 &&
+    [...verifyModules].every(
+      (name) => typeof name === 'string' && name.length <= 200 && MODULE_NAME.test(name)
+    );
+  const names = validNames ? [...new Set(verifyModules)] : [];
+  const finish = (
+    status,
+    message,
+    version = null,
+    modules = names.map((name) => ({ name, status: 'not-verified' }))
+  ) => ({
+    status,
+    version,
+    imports: modules.some((entry) => entry.status === 'failed')
+      ? 'failed'
+      : modules.length > 0 && modules.every((entry) => entry.status === 'verified')
+        ? 'verified'
+        : 'not-verified',
+    modules,
+    message,
+  });
+  if (
+    typeof projectDir !== 'string' ||
+    !projectDir ||
+    projectDir.includes('\0') ||
+    typeof packId !== 'string' ||
+    !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(packId) ||
+    !floor ||
+    !validNames ||
+    typeof runner !== 'function'
+  ) {
+    return finish('invalid', 'Python verification options are invalid.');
+  }
+
+  projectDir = path.resolve(projectDir);
+  let environment;
+  try {
+    environment = environmentPaths(projectDir, packId);
+  } catch (error) {
+    return finish(
+      error.code === 'ENOENT' ? 'missing' : 'unavailable',
+      error.code === 'ENOENT'
+        ? 'The pack Python environment is missing or incomplete.'
+        : 'The pack Python environment cannot be inspected.'
+    );
+  }
+  if (!environment)
+    return finish(
+      'invalid',
+      'The pack Python environment contains an unsafe path or invalid file.'
+    );
+
+  const timeout = TIMEOUT_MS - (Date.now() - started);
+  if (timeout <= 0) return finish('unavailable', 'Python verification exceeded its time limit.');
+  let result;
+  try {
+    result = runner(
+      environment.executable,
+      [
+        '-I',
+        '-B',
+        '-c',
+        PROBE,
+        environment.directory,
+        JSON.stringify(floor),
+        JSON.stringify(names),
+      ],
+      {
+        cwd: projectDir,
+        encoding: 'utf8',
+        shell: false,
+        windowsHide: true,
+        timeout,
+        killSignal: 'SIGKILL',
+        maxBuffer: MAX_BUFFER,
+      }
+    );
+  } catch {
+    return finish('unavailable', 'The pack Python interpreter could not complete verification.');
+  }
+  if (Date.now() - started >= TIMEOUT_MS || !result || result.error || result.status !== 0) {
+    return finish(
+      'unavailable',
+      'The pack Python interpreter could not complete verification within its limits.'
+    );
+  }
+  let evidence;
+  try {
+    if (typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout, 'utf8') > MAX_BUFFER)
+      throw new Error();
+    evidence = JSON.parse(result.stdout);
+  } catch {
+    return finish('invalid', 'The Python interpreter returned invalid verification evidence.');
+  }
+  if (
+    !evidence ||
+    evidence.schemaVersion !== 1 ||
+    typeof evidence.prefix !== 'string' ||
+    !path.isAbsolute(evidence.prefix) ||
+    typeof evidence.basePrefix !== 'string' ||
+    !path.isAbsolute(evidence.basePrefix) ||
+    !Array.isArray(evidence.version) ||
+    evidence.version.length !== 3 ||
+    evidence.version.some((part) => !Number.isSafeInteger(part) || part < 0) ||
+    evidence.version[0] === 0 ||
+    !Array.isArray(evidence.modules) ||
+    evidence.modules.length !== names.length ||
+    evidence.modules.some(
+      (entry, index) =>
+        !entry ||
+        entry.name !== names[index] ||
+        !['verified', 'failed', 'not-verified'].includes(entry.status)
+    )
+  ) {
+    return finish('invalid', 'The Python interpreter returned invalid verification evidence.');
+  }
+  if (
+    normalizedPath(evidence.prefix) !== normalizedPath(environment.directory) ||
+    normalizedPath(evidence.prefix) === normalizedPath(evidence.basePrefix)
+  ) {
+    return finish(
+      'invalid',
+      'The interpreter is not running from the expected pack virtual environment.'
+    );
+  }
+  const version = evidence.version.join('.');
+  const difference = evidence.version.findIndex((part, index) => part !== floor[index]);
+  if (difference >= 0 && evidence.version[difference] < floor[difference]) {
+    return finish('unsupported', 'The pack Python version is below the required minimum.', version);
+  }
+  if (evidence.modules.some((entry) => entry.status === 'not-verified')) {
+    return finish('invalid', 'The interpreter did not verify every declared module.', version);
+  }
+  const modules = evidence.modules.map(({ name, status }) => ({ name, status }));
+  if (modules.some((entry) => entry.status === 'failed')) {
+    return finish(
+      'unavailable',
+      'One or more declared modules could not be imported in the pack environment.',
+      version,
+      modules
+    );
+  }
+  return finish(
+    'verified',
+    modules.length
+      ? 'The pack Python version and declared imports are verified.'
+      : 'The pack Python version is verified; no import checks were requested.',
+    version,
+    modules
+  );
+}
+
+module.exports = { probePythonRuntime };

package/tools/cli/lib/python-provision.js

@@ -2,7 +2,7 @@
  * BMAD+ Unified Python Provisioning (Pillar 2 — kills split-brain / broken-on-arrival)
  *
  * Provisions the Python runtime a pack declares in the registry
- * (`runtime: [node, python]` → seo, memory). One code path for every pack:
+ * (`runtime: [node, python]`). One code path for every Python pack:
  *   1. detect a Python >= 3.11 interpreter (or a uv that can fetch one)
  *   2. choose a provisioner: uv > pipx > venv+pip
  *   3. create an isolated env under a given dir (e.g. <project>/.bmad/venv)
@@ -386,7 +386,7 @@ function verifyEntry({ envDir, entryPath, entryArgs = ['--help'], runner = defau
 /**
  * Full pipeline: detect → choose provisioner → create env → install → verify.
  * This is the single call site the installer uses for ANY pack whose registry
- * runtime includes "python" (seo, memory, …).
+ * runtime includes "python".
  *
  * Never throws for environmental problems — always returns
  * { ok, tool, messages[] } so the installer can degrade gracefully and print

package/tools/cli/lib/studio.js

@@ -0,0 +1,310 @@
+/** Read-only Dev Studio resource resolution; execution belongs to the host. */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const yaml = require('js-yaml');
+const { safeTarget } = require('../../build/generate-adapters');
+
+const PACK = '.agents/skills/pack-dev-studio';
+const MAX_FILE = 256 * 1024;
+const MAX_CONTEXT = 2 * 1024 * 1024;
+const hash = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+
+function relativePath(file) {
+  if (
+    typeof file !== 'string' ||
+    !file ||
+    /[\\:\0?#{}]/.test(file) ||
+    file.split('/').some((part) => !part || part === '.' || part === '..')
+  ) {
+    throw new Error('Expected a portable relative file path: ' + String(file));
+  }
+  return file;
+}
+
+function target(root, file) {
+  relativePath(file);
+  const result = safeTarget(root, file);
+  let parent = path.resolve(root);
+  for (const part of file.split('/')) {
+    if (!fs.existsSync(parent)) break;
+    const names = fs.readdirSync(parent);
+    if (!names.includes(part) && names.some((name) => name.toLowerCase() === part.toLowerCase())) {
+      throw new Error('Path case mismatch: ' + file);
+    }
+    parent = path.join(parent, part);
+  }
+  return result;
+}
+
+function readText(root, file, limit = MAX_FILE) {
+  const resolved = target(root, file);
+  const stat = fs.statSync(resolved);
+  if (!stat.isFile() || stat.size > limit) throw new Error('Resource is not bounded text: ' + file);
+  const bytes = fs.readFileSync(resolved);
+  if (bytes.includes(0) || bytes.length > limit)
+    throw new Error('Resource is not bounded text: ' + file);
+  const content = bytes.toString('utf8');
+  if (!Buffer.from(content).equals(bytes)) throw new Error('Resource is not UTF-8: ' + file);
+  return { path: file, sha256: hash(bytes), content };
+}
+
+function readJson(root, file) {
+  try {
+    return JSON.parse(readText(root, file).content);
+  } catch (error) {
+    throw new Error(file + ': ' + error.message, { cause: error });
+  }
+}
+
+function loadCatalog(packRoot) {
+  const catalog = readJson(packRoot, 'shared/catalog.json');
+  if (
+    catalog.schemaVersion !== 1 ||
+    !Array.isArray(catalog.agents) ||
+    !Array.isArray(catalog.workflows) ||
+    !Array.isArray(catalog.compatibility) ||
+    !catalog.agents.length ||
+    !catalog.workflows.length
+  ) {
+    throw new Error('Unsupported Dev Studio catalog');
+  }
+  catalog.compatibility.forEach(relativePath);
+  const agents = new Set();
+  const routes = new Set();
+  const entries = new Set();
+  for (const agent of catalog.agents) {
+    if (
+      !agent ||
+      !/^[a-z][a-z0-9-]*$/.test(agent.id) ||
+      agents.has(agent.id) ||
+      typeof agent.persona !== 'string' ||
+      !agent.persona.trim()
+    )
+      throw new Error('Invalid or duplicate persona');
+    relativePath(agent.path);
+    if (entries.has(agent.path)) throw new Error('Duplicate catalog entry: ' + agent.path);
+    entries.add(agent.path);
+    agents.add(agent.id);
+  }
+  for (const workflow of catalog.workflows) {
+    if (
+      !workflow ||
+      !/^[a-z][a-z0-9-]*$/.test(workflow.id) ||
+      !agents.has(workflow.agent) ||
+      !['request', 'artifact', 'project', 'none'].includes(workflow.input) ||
+      !Array.isArray(workflow.aliases) ||
+      !Array.isArray(workflow.resources)
+    ) {
+      throw new Error('Invalid workflow declaration');
+    }
+    relativePath(workflow.path);
+    if (entries.has(workflow.path)) throw new Error('Duplicate catalog entry: ' + workflow.path);
+    entries.add(workflow.path);
+    for (const resource of workflow.resources) relativePath(resource);
+    for (const route of [workflow.id, ...workflow.aliases]) {
+      if (typeof route !== 'string' || !/^[a-z][a-z0-9-]*$/.test(route) || routes.has(route)) {
+        throw new Error('Invalid or duplicate workflow route: ' + route);
+      }
+      routes.add(route);
+    }
+  }
+  return catalog;
+}
+
+/** Inline and reference-style Markdown links are packaged dependencies. */
+function localLinks(content, file) {
+  const destinations = [
+    ...Array.from(
+      content.matchAll(/!?\[[^\]\n]*\]\(<?([^\s)>]+)>?(?:\s+"[^"]*")?\)/g),
+      (m) => m[1]
+    ),
+    ...Array.from(content.matchAll(/^\s{0,3}\[[^\]\n]+\]:\s*<?([^\s>]+)>?/gm), (m) => m[1]),
+  ];
+  return destinations
+    .filter((link) => !/^(?:https?:|mailto:|#)/i.test(link))
+    .map((link) => {
+      const clean = decodeURIComponent(link.split('#')[0]);
+      if (!clean || /[\\:\0?{}]/.test(clean) || path.posix.isAbsolute(clean)) {
+        throw new Error('Unsupported resource link in ' + file + ': ' + link);
+      }
+      return relativePath(path.posix.normalize(path.posix.join(path.posix.dirname(file), clean)));
+    });
+}
+
+function validatePack(packRoot, expected) {
+  const catalog = loadCatalog(packRoot);
+  if (expected) {
+    const workflows = Object.values(expected.categories)
+      .flatMap((category) => category.workflows)
+      .sort();
+    if (
+      JSON.stringify(workflows) !== JSON.stringify(catalog.workflows.map((w) => w.id).sort()) ||
+      JSON.stringify([...expected.sub_agents].sort()) !==
+        JSON.stringify(catalog.agents.map((a) => a.id).sort())
+    ) {
+      throw new Error('Dev Studio catalog disagrees with registry routes');
+    }
+  }
+  const queue = [
+    'SKILL.md',
+    'README.md',
+    'dev-studio-orchestrator.md',
+    'shared/execution.md',
+    ...catalog.compatibility,
+    ...catalog.agents.map((a) => a.path),
+    ...catalog.workflows.flatMap((w) => [w.path, ...w.resources]),
+  ];
+  const visited = new Set();
+  let bytes = 0;
+  while (queue.length) {
+    const file = queue.shift();
+    if (visited.has(file)) continue;
+    if (visited.size >= 256) throw new Error('Too many Dev Studio resources');
+    const resource = readText(packRoot, file);
+    bytes += Buffer.byteLength(resource.content);
+    if (bytes > MAX_CONTEXT) throw new Error('Dev Studio resource graph is too large');
+    visited.add(file);
+    if (file.endsWith('.md')) {
+      if (
+        /\{(?:workflow|agent)\.[^}]+\}|\{(?:project-root|planning_artifacts|communication_language)\}/.test(
+          resource.content
+        )
+      ) {
+        throw new Error('Unresolved runtime declaration: ' + file);
+      }
+      queue.push(...localLinks(resource.content, file));
+    }
+  }
+  return { catalog, resources: [...visited].sort() };
+}
+
+function resolveConfig(projectDir) {
+  const file = '_bmad/config.yaml';
+  const location = target(projectDir, file);
+  let supplied = {};
+  let source = null;
+  if (fs.existsSync(location)) {
+    source = readText(projectDir, file, 64 * 1024);
+    try {
+      supplied = yaml.load(source.content);
+    } catch (error) {
+      throw new Error(file + ': ' + error.message, { cause: error });
+    }
+    if (!supplied || typeof supplied !== 'object' || Array.isArray(supplied)) {
+      throw new Error(file + ' must be a YAML mapping');
+    }
+  }
+  const config = {
+    user_name: 'user',
+    communication_language: 'English',
+    document_output_language: 'English',
+    output_folder: '_bmad-output',
+    project_name: path.basename(projectDir),
+  };
+  const defaultsUsed = [];
+  for (const key of Object.keys(config)) {
+    if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string' || !supplied[key].trim()) {
+        throw new Error(file + ': ' + key + ' must be a nonempty string');
+      }
+      config[key] = supplied[key];
+    } else defaultsUsed.push(key);
+  }
+  relativePath(config.output_folder);
+  return { values: config, defaultsUsed, source };
+}
+
+function installedPack(projectDir) {
+  // Validate ancestors through an entry path before using the pack as a root.
+  target(projectDir, PACK + '/SKILL.md');
+  const packRoot = path.join(projectDir, PACK);
+  if (!fs.existsSync(packRoot))
+    throw new Error('Dev Studio is not installed. Run bmad-plus install --packs core,dev-studio');
+  return packRoot;
+}
+
+function prepare({
+  projectDir = process.cwd(),
+  workflow: route,
+  request = '',
+  inputs = [],
+  packRoot,
+} = {}) {
+  projectDir = path.resolve(projectDir);
+  if (!fs.statSync(projectDir).isDirectory()) throw new Error('Project must be a directory');
+  packRoot = packRoot || installedPack(projectDir);
+  const { catalog } = validatePack(packRoot);
+  const workflow = catalog.workflows.find((w) => w.id === route || w.aliases.includes(route));
+  if (!workflow) throw new Error('Unknown Dev Studio workflow: ' + route);
+  if (
+    typeof request !== 'string' ||
+    Buffer.byteLength(request) > MAX_FILE ||
+    !Array.isArray(inputs) ||
+    inputs.length > 32
+  ) {
+    throw new Error('Invalid or oversized workflow inputs');
+  }
+  const config = resolveConfig(projectDir);
+  const loadedInputs = [...new Set(inputs)].map((file) => readText(projectDir, file));
+  const agent = catalog.agents.find((a) => a.id === workflow.agent);
+  const routes = new Set([
+    ...catalog.agents.map((a) => a.path),
+    ...catalog.workflows.map((w) => w.path),
+    'SKILL.md',
+    'README.md',
+    'dev-studio-orchestrator.md',
+    'shared/catalog.json',
+  ]);
+  const queue = ['shared/execution.md', agent.path, workflow.path, ...workflow.resources];
+  const instructions = [];
+  const loaded = new Set();
+  while (queue.length) {
+    const file = queue.shift();
+    if (loaded.has(file)) continue;
+    loaded.add(file);
+    const resource = readText(packRoot, file);
+    instructions.push(resource);
+    if (file.endsWith('.md'))
+      queue.push(...localLinks(resource.content, file).filter((link) => !routes.has(link)));
+  }
+  const outputPath = `${config.values.output_folder}/dev-studio/${workflow.id}.md`;
+  const outputTarget = target(projectDir, outputPath);
+  const previousReport = fs.existsSync(outputTarget) ? readText(projectDir, outputPath) : null;
+  const size = [
+    ...loadedInputs,
+    ...instructions,
+    ...(previousReport ? [previousReport] : []),
+  ].reduce(
+    (total, item) => total + Buffer.byteLength(item.content),
+    Buffer.byteLength(request) + Buffer.byteLength(config.source?.content || '')
+  );
+  if (size > MAX_CONTEXT) throw new Error('Prepared context exceeds 2 MiB');
+  const missingInputs =
+    workflow.input === 'artifact' && !loadedInputs.length
+      ? ['Supply a project artifact with --input RELATIVE_FILE.']
+      : ['request', 'project'].includes(workflow.input) && !request.trim() && !loadedInputs.length
+        ? ['Supply the task scope with --request TEXT or --input RELATIVE_FILE.']
+        : [];
+  return {
+    schemaVersion: 1,
+    status: missingInputs.length ? 'needs-input' : 'ready',
+    execution: 'host-managed',
+    executed: false,
+    workflow: workflow.id,
+    agent: agent.persona,
+    catalogSha256: readText(packRoot, 'shared/catalog.json').sha256,
+    projectDir,
+    config,
+    request,
+    inputs: loadedInputs,
+    instructions,
+    outputPath,
+    previousReport,
+    missingInputs,
+  };
+}
+
+module.exports = { loadCatalog, localLinks, validatePack, resolveConfig, installedPack, prepare };