bmad-plus 0.12.1 → 0.13.0

package/tools/build/check-install-contract.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * Verify that real source and npm-package installs deliver the adapter contract.
+ * Uses existing dependencies, temporary projects and an isolated brain; no
+ * lifecycle scripts, dependency installation or Python provisioning are run.
+ *
+ * Run: node tools/build/check-install-contract.js
+ * Author: Laurent Rochetta
+ */
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const TEMP_PREFIX = 'bmad-install-contract-';
+
+function resolveWithin(root, relative) {
+  assert(typeof relative === 'string' && relative.length > 0, 'Expected a relative file path');
+  assert(
+    !path.win32.isAbsolute(relative) && !path.posix.isAbsolute(relative),
+    `Absolute path: ${relative}`
+  );
+  const target = path.resolve(root, relative);
+  const fromRoot = path.relative(root, target);
+  assert(
+    fromRoot &&
+      !path.isAbsolute(fromRoot) &&
+      !fromRoot.startsWith(`..${path.sep}`) &&
+      fromRoot !== '..',
+    `Path escapes project: ${relative}`
+  );
+  return target;
+}
+
+function sameSelection(actual, expected, label) {
+  assert(Array.isArray(actual), `Manifest ${label} must be an array`);
+  assert.deepEqual(
+    [...actual].sort(),
+    [...expected].sort(),
+    `Manifest ${label} differs from requested selection`
+  );
+}
+
+/** Compare the installed bytes, normalizing only Windows/Unix line endings. */
+function verifyInstallation(projectDir, { packs, tools, derived, ideConfigs, renderFiles, requireInventory = false }) {
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(projectDir, '_bmad', '.bmad-plus-install.json'), 'utf8')
+  );
+  sameSelection(manifest.packs, packs, 'packs');
+  sameSelection(manifest.ides, tools, 'ides');
+  assert(typeof manifest.user === 'string' && manifest.user, 'Manifest user is missing');
+  assert(
+    typeof manifest.language === 'string' && manifest.language,
+    'Manifest language is missing'
+  );
+
+  const files = renderFiles(derived, {
+    packs,
+    userName: manifest.user,
+    language: manifest.language,
+    tools: manifest.ides,
+  });
+  const expectedPaths = new Set(files.map(({ file }) => file));
+  assert.equal(expectedPaths.size, files.length, 'Renderer returned duplicate output paths');
+  assert.equal(
+    derived.targets.spine,
+    'AGENTS.md',
+    'Install contract requires the root AGENTS.md spine'
+  );
+  assert(
+    expectedPaths.has(derived.targets.spine),
+    'Renderer must include the root AGENTS.md spine'
+  );
+  for (const tool of tools) {
+    assert(expectedPaths.has(ideConfigs[tool].configFile), `Renderer omitted the ${tool} adapter`);
+  }
+
+  for (const { file, content } of files) {
+    const target = resolveWithin(projectDir, file);
+    assert(fs.existsSync(target), `Missing installed file: ${file}`);
+    const actual = fs.readFileSync(target, 'utf8').replace(/\r\n/g, '\n');
+    const expected = content.replace(/\r\n/g, '\n');
+    assert(actual === expected, `Installed adapter differs from renderer: ${file}`);
+  }
+  for (const { configFile } of Object.values(ideConfigs)) {
+    assert(
+      expectedPaths.has(configFile) || !fs.existsSync(resolveWithin(projectDir, configFile)),
+      `Unselected adapter was installed: ${configFile}`
+    );
+  }
+  if (requireInventory) {
+    assert.equal(manifest.fileInventory?.schemaVersion, 1, 'Missing file inventory');
+    const { collectManagedFiles } = require('../cli/lib/update-transaction');
+    const managedFiles = collectManagedFiles({ projectDir, packs });
+    assert.deepEqual(Object.keys(manifest.fileInventory.files).sort(), managedFiles.map(entry => entry.file).sort(),
+      'Inventory does not cover exactly the selected framework files');
+    for (const { file } of managedFiles) {
+      const actualHash = crypto.createHash('sha256').update(fs.readFileSync(resolveWithin(projectDir, file))).digest('hex');
+      assert.equal(manifest.fileInventory.files[file], actualHash, `Inventory differs from installed bytes: ${file}`);
+    }
+  }
+  return files.length;
+}
+
+function run(command, args, { cwd, env, timeout = 60000 }) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    timeout,
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error || result.status !== 0) {
+    const reason = result.error
+      ? result.error.message
+      : `exit ${result.status}, signal ${result.signal || 'none'}`;
+    throw new Error(
+      `${path.basename(command)} ${args.join(' ')}: ${reason}\n${result.stdout || ''}${result.stderr || ''}`
+    );
+  }
+  return result.stdout;
+}
+
+/** Invoke npm without a shell, including Windows where npm.cmd is not executable. */
+function npmCommand(env) {
+  const candidates = [
+    env.npm_execpath,
+    path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ...(env.PATH || env.Path || '')
+      .split(path.delimiter)
+      .map((dir) => path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')),
+  ];
+  const cli = candidates.find(
+    (candidate) => candidate && /npm-cli\.js$/i.test(candidate) && fs.existsSync(candidate)
+  );
+  if (cli) return { command: process.execPath, args: [cli] };
+  assert(process.platform !== 'win32', 'Could not locate npm-cli.js beside Node or on PATH');
+  return { command: 'npm', args: [] };
+}
+
+function packAndExtract(tempRoot, env) {
+  const destination = path.join(tempRoot, 'distribution');
+  fs.mkdirSync(destination);
+  const npm = npmCommand(env);
+  const output = run(
+    npm.command,
+    [
+      ...npm.args,
+      'pack',
+      '--ignore-scripts',
+      '--offline',
+      '--json',
+      '--pack-destination',
+      destination,
+      '--cache',
+      path.join(tempRoot, 'npm-cache'),
+    ],
+    { cwd: REPO_ROOT, env, timeout: 120000 }
+  );
+  const packed = JSON.parse(output);
+  assert(Array.isArray(packed) && packed.length === 1, 'npm pack must produce exactly one package');
+  const archive = resolveWithin(destination, packed[0].filename);
+  const entries = run('tar', ['-tzf', archive], { cwd: destination, env }).trim().split(/\r?\n/);
+  for (const entry of entries) {
+    assert(entry.startsWith('package/'), `Unexpected npm archive entry: ${entry}`);
+    resolveWithin(destination, entry);
+  }
+  run('tar', ['-xzf', archive, '-C', destination], { cwd: destination, env });
+  const packageRoot = path.join(destination, 'package');
+  assert(
+    !fs.existsSync(path.join(packageRoot, 'registry.yaml')),
+    'npm contract must work without registry.yaml'
+  );
+  assert(fs.statSync(packageRoot).isDirectory(), 'npm package directory is missing');
+  return packageRoot;
+}
+
+function runMatrix(packageRoot, variant, tempRoot, env, reference) {
+  const allPacks = Object.keys(reference.packDefinitions).filter(
+    (id) => !reference.packDefinitions[id].disabled
+  );
+  const allTools = Object.keys(reference.ideConfigs);
+  assert(allTools.length > 0, 'IDE_CONFIGS must expose at least one target');
+  const selections = [
+    { argument: 'core', packs: ['core'] },
+    { argument: 'core,osint', packs: ['core', 'osint'] },
+    { argument: 'core,memory', packs: ['core', 'memory'] },
+    { argument: 'all', packs: allPacks },
+  ];
+  const toolSelections = [...allTools.map((tool) => [tool]), allTools];
+  let installations = 0;
+  let files = 0;
+  for (const selection of selections) {
+    for (const tools of toolSelections) {
+      const label = `${variant}/${selection.argument}/${tools.join(',')}`;
+      const projectDir = path.join(tempRoot, `${variant}-project-${++installations}`);
+      fs.mkdirSync(projectDir);
+      try {
+        run(
+          process.execPath,
+          [
+            path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
+            'install',
+            '--yes',
+            '--lang',
+            'en',
+            '--directory',
+            projectDir,
+            '--packs',
+            selection.argument,
+            '--tools',
+            tools.join(','),
+          ],
+          { cwd: projectDir, env }
+        );
+        files += verifyInstallation(projectDir, { ...reference, packs: selection.packs, tools });
+        if (tools.length === allTools.length) {
+          const output = run(process.execPath, [
+            path.join(packageRoot, 'tools', 'cli', 'bmad-plus-cli.js'),
+            'update-check', '--offline', '--json', '--directory', projectDir,
+          ], { cwd: projectDir, env });
+          const checked = JSON.parse(output);
+          assert.equal(checked.status, 'unknown', 'Offline check must not claim the latest release');
+          assert.equal(checked.updateAvailable, null);
+          assert.equal(checked.canAutoApply, false);
+        }
+      } catch (error) {
+        throw new Error(`${label}: ${error.message}`, { cause: error });
+      }
+    }
+    console.log(
+      `OK ${variant}: ${selection.argument} across ${toolSelections.length} tool selections`
+    );
+  }
+  return { installations, files };
+}
+
+function main() {
+  const { PACKS, DERIVED } = require('../cli/lib/packs');
+  const { IDE_CONFIGS } = require('../cli/lib/ide-config');
+  const { generateUserFiles } = require('./generate-adapters');
+  assert(
+    DERIVED && typeof generateUserFiles === 'function',
+    'Generated install contract exports are missing'
+  );
+  const reference = {
+    packDefinitions: PACKS,
+    derived: DERIVED,
+    ideConfigs: IDE_CONFIGS,
+    renderFiles: generateUserFiles,
+    requireInventory: true,
+  };
+  const tempParent = fs.realpathSync(os.tmpdir());
+  const tempRoot = fs.mkdtempSync(path.join(tempParent, TEMP_PREFIX));
+  try {
+    const brain = path.join(tempRoot, 'brain');
+    fs.mkdirSync(brain);
+    const env = {
+      ...process.env,
+      BMAD_PLUS_BRAIN: brain,
+      NODE_PATH: path.join(REPO_ROOT, 'node_modules'),
+      NO_COLOR: '1',
+      NPM_CONFIG_UPDATE_NOTIFIER: 'false',
+    };
+    const source = runMatrix(REPO_ROOT, 'source', tempRoot, env, reference);
+    const packageRoot = packAndExtract(tempRoot, env);
+    const packaged = runMatrix(packageRoot, 'npm', tempRoot, env, reference);
+    console.log(
+      `Install contract passed: ${source.installations + packaged.installations} installs, ${source.files + packaged.files} files compared (source + npm without registry.yaml).`
+    );
+    return 0;
+  } finally {
+    // Delete only this mkdtemp-owned direct child of the verified temp directory.
+    assert(
+      path.dirname(tempRoot) === tempParent && path.basename(tempRoot).startsWith(TEMP_PREFIX)
+    );
+    assert(fs.realpathSync(tempRoot) === tempRoot && !fs.lstatSync(tempRoot).isSymbolicLink());
+    fs.rmSync(tempRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = main();
+  } catch (error) {
+    console.error(`Install contract failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { main, resolveWithin, verifyInstallation };