bmad-method-test-architecture-enterprise 2.0.4-next.1 → 2.0.4-next.3

package/.claude-plugin/marketplace.json

@@ -31,7 +31,7 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test generation in red and expand modes with automatic run-and-heal, combined framework and CI setup, CI/CD quality gates, and structured testing education. The CI and ATDD commands remain available with existing customizations. Part of the BMad Method ecosystem.",
-      "version": "2.0.4-next.1",
+      "version": "2.0.4-next.3",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/README.md

@@ -114,6 +114,7 @@ npm install --save-dev bmad-method-test-architecture-enterprise
 ```
 
 - [`tea-test-review`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-test-review-cli/) runs the review skill against changed tests and returns a gate verdict.
+- [`tea-framework`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-framework-cli/) creates, resumes, validates, and edits test framework and CI setup with retained run evidence.
 - [`tea-trace`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-trace-cli/) maps requirements to existing evidence and returns a coverage gate.
 - [`tea-evaluate`](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/tea-evaluate-cli/) checks, runs, scores, and compares behavioral evaluations.
 

package/cli/framework.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/** tea-framework drives the packaged framework and CI skill with durable run evidence. */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Command } = require('commander');
+const { resolveModel } = require('./lib/agent-adapters');
+const { agentOptions, WorkflowError } = require('./lib/workflow-cli');
+const { resolveTeaConfig } = require('./lib/resolve-tea-config');
+const { addAgentOptions, resolveWorkflowSkill, runWithEvidence } = require('./lib/workflow-cli');
+const {
+  SKILL_NAME,
+  SCOPES,
+  OPERATIONS,
+  projectPath,
+  readJournal,
+  prepareSetup,
+  setupPrompt,
+  inspectCompletion,
+  protectResultPath,
+  saveRequestSnapshot,
+} = require('./lib/framework-setup');
+
+function collect(value, previous) {
+  return [...previous, value];
+}
+
+function resultReport(result) {
+  return [
+    '# Framework and CI setup result',
+    '',
+    `Operation: ${result.operation}. Scope: ${result.scope}.`,
+    `Completed: ${result.completed ? 'yes' : 'no'}.`,
+    `Agent: ${result.agent}. Model: ${result.model ?? 'unspecified'}.`,
+    '',
+    '## Completion evidence',
+    '',
+    ...result.artifacts.map((file) => `- ${file}`),
+    '',
+    ...(result.issues.length > 0 ? ['## Unresolved work', '', ...result.issues.map((issue) => `- ${issue}`), ''] : []),
+    `Retained agent evidence: ${result.runDirectory}.`,
+    '',
+    'Create completion verifies the skill journal and referenced outputs, then reruns the frozen test commands. Native verification logs and agent transcripts are retained. Validate findings remain report outcomes.',
+    '',
+  ].join('\n');
+}
+
+function main(argv = process.argv) {
+  const program = new Command();
+  program
+    .name('tea-framework')
+    .description('Create, resume, validate or edit test framework and CI setup using the packaged TEA skill.')
+    .option('--project-root <dir>', 'project whose framework and CI are being set up', process.cwd())
+    .option('--scope <scope>', `requested phases (${SCOPES.join('|')})`, 'framework')
+    .option('--operation <operation>', `requested operation (${OPERATIONS.join('|')})`, 'create')
+    .option('--input <path>', 'exact project artifact to edit or validate (repeatable)', collect, [])
+    .option('--instructions <path>', 'project file containing the setup request or requested edit')
+    .option('--skill-root <dir>', 'explicit skill copy; defaults to the packaged framework skill')
+    .option('--output <dir>', 'project directory for retained CLI reports and agent evidence')
+    .option('--json <path>', 'additional project-relative machine-readable result path')
+    .option('--allow-network', 'allow unrestricted outbound network access in the Codex workspace sandbox')
+    .option('--use-playwright-utils', 'enable Playwright utilities when applicable')
+    .option('--no-use-playwright-utils', 'disable Playwright utilities')
+    .option('--use-pactjs-utils', 'enable Pact utilities when applicable')
+    .option('--no-use-pactjs-utils', 'disable Pact utilities')
+    .exitOverride()
+    .configureOutput({ writeErr: () => {} });
+  addAgentOptions(program);
+  program.setOptionValueWithSource('retries', '0', 'default');
+  try {
+    program.parse(argv);
+  } catch (error) {
+    if (error.exitCode === 0) return 0;
+    process.stderr.write(`tea-framework: ${error.message}\n`);
+    return 2;
+  }
+  const options = program.opts();
+  let request;
+  let jsonPath;
+  try {
+    if (options.allowNetwork && options.agent !== 'codex') throw new Error('--allow-network requires --agent codex');
+    if (options.allowNetwork) options.agentArg = ['-c', 'sandbox_workspace_write.network_access=true', ...options.agentArg];
+    const projectRoot = fs.realpathSync(path.resolve(options.projectRoot));
+    agentOptions(options, projectRoot);
+    if (!fs.statSync(projectRoot).isDirectory()) throw new Error('--project-root must be a directory');
+    const skillRoot = resolveWorkflowSkill({ projectRoot, skillName: SKILL_NAME, skillRoot: options.skillRoot });
+    const config = resolveTeaConfig({ projectRoot, skillRoot, skillName: SKILL_NAME, flags: options });
+    request = prepareSetup({ projectRoot, skillRoot, config, options });
+    const evidenceRoot = projectPath(projectRoot, options.output ?? path.join(request.artifactsRoot, 'framework', 'cli-runs'));
+    jsonPath = options.json ? projectPath(projectRoot, options.json) : null;
+    if (
+      jsonPath &&
+      (path.extname(jsonPath) !== '.json' ||
+        jsonPath === request.journalPath ||
+        request.inputs.includes(jsonPath) ||
+        jsonPath === request.instructionsPath)
+    ) {
+      throw new Error('--json must name a .json result file separate from setup inputs and journal');
+    }
+    protectResultPath(request, jsonPath);
+    if (options.agent === 'none') {
+      process.stdout.write(`${setupPrompt(request)}\n`);
+      return 0;
+    }
+    const execution = runWithEvidence({
+      name: 'tea-framework',
+      projectRoot,
+      evidenceRoot,
+      options,
+      capabilities: ['command-execution'],
+      prepare: ({ attempt }) => ({ prompt: setupPrompt(request, { retry: attempt > 1 }), request }),
+      validate: ({ attemptDir }) => {
+        saveRequestSnapshot(request);
+        try {
+          protectResultPath(request, jsonPath, readJournal(projectPath(projectRoot, request.journalPath))?.data);
+        } catch (error) {
+          jsonPath = null;
+          throw new WorkflowError('usage', error.message, { cause: error });
+        }
+        return inspectCompletion(request, { evidenceDir: attemptDir, timeoutMs: Number(options.timeoutMs) });
+      },
+    });
+    const outcome = execution.value;
+    const result = {
+      schema_version: '0.1.0',
+      completed: outcome.completed,
+      scope: request.scope,
+      operation: request.savedOperation,
+      agent: options.agent,
+      model: resolveModel(options.agent, options.model, options.agentArg),
+      runDirectory: execution.runDir,
+      journal: request.journalPath,
+      artifacts: outcome.artifacts,
+      issues: outcome.issues,
+      verification: outcome.executions,
+    };
+    const serialized = `${JSON.stringify(result, null, 2)}\n`;
+    fs.writeFileSync(path.join(execution.runDir, 'result.json'), serialized);
+    fs.writeFileSync(path.join(execution.runDir, 'report.md'), resultReport(result));
+    if (jsonPath) {
+      protectResultPath(request, jsonPath, readJournal(projectPath(projectRoot, request.journalPath))?.data);
+      fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+      fs.writeFileSync(jsonPath, serialized);
+    }
+    process.stdout.write(serialized);
+    return result.completed ? 0 : 1;
+  } catch (error) {
+    if (request) {
+      try {
+        saveRequestSnapshot(request);
+      } catch (snapshotError) {
+        process.stderr.write(`tea-framework: could not retain setup request: ${snapshotError.message}\n`);
+      }
+    }
+    if (error.runDir) {
+      const failureResult = {
+        schema_version: '0.1.0',
+        completed: false,
+        scope: request?.scope ?? options.scope,
+        operation: request?.savedOperation ?? options.operation,
+        agent: options.agent,
+        model: null,
+        runDirectory: error.runDir,
+        journal: request?.journalPath ?? null,
+        artifacts: [],
+        issues: [error.message],
+        failureClass: error.failureClass,
+      };
+      const serialized = `${JSON.stringify(failureResult, null, 2)}\n`;
+      fs.writeFileSync(path.join(error.runDir, 'result.json'), serialized);
+      fs.writeFileSync(path.join(error.runDir, 'report.md'), resultReport(failureResult));
+      if (jsonPath) {
+        try {
+          protectResultPath(request, jsonPath, readJournal(projectPath(request.projectRoot, request.journalPath))?.data);
+          fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+          fs.writeFileSync(jsonPath, serialized);
+        } catch (publicationError) {
+          process.stderr.write(`tea-framework: result publication refused: ${publicationError.message}\n`);
+        }
+      }
+      process.stdout.write(serialized);
+    }
+    process.stderr.write(`tea-framework: ${error.message}${error.runDir ? `\nRetained evidence: ${error.runDir}` : ''}\n`);
+    return ['environment-transport', 'environment-timeout', 'environment-parser'].includes(error.failureClass) ? 3 : 2;
+  }
+}
+
+if (require.main === module) process.exitCode = main();
+module.exports = { main, resultReport };

package/cli/lib/evaluate/http-target.js

@@ -699,19 +699,38 @@ async function deploymentAccess({
   return { origins, authorizations };
 }
 
-/** A port the system gives out now, free on every address, released for the server to take. */
-function freePort() {
+/** Tries a port on one address, then releases it for the target; a busy candidate returns null. */
+function availablePort(port, address, createServer) {
   return new Promise((resolve, reject) => {
-    const server = net.createServer();
+    const server = createServer();
     server.unref();
-    server.once('error', reject);
-    server.listen(0, () => {
-      const { port } = server.address();
-      server.close(() => resolve(port));
+    server.once('error', (error) => (error.code === 'EADDRINUSE' ? resolve(null) : reject(error)));
+    server.listen(port, address, () => {
+      const selected = server.address().port;
+      server.close(() => resolve(selected));
     });
   });
 }
 
+/** A port available on every address the policy may select, released for the server to take. */
+async function freePort(addresses, createServer = () => net.createServer()) {
+  const distinct = [...new Set(addresses.map((address) => canonicalAddress(address) ?? address))];
+  if (distinct.length === 0) throw new Error('a started server has no authorized address');
+  for (let attempt = 0; attempt < 32; attempt += 1) {
+    const candidate = await availablePort(0, distinct[0], createServer);
+    if (candidate === null) continue;
+    let available = true;
+    for (const address of distinct.slice(1)) {
+      if ((await availablePort(candidate, address, createServer)) === null) {
+        available = false;
+        break;
+      }
+    }
+    if (available) return candidate;
+  }
+  throw new Error(`could not find a free port on ${distinct.join(', ')}`);
+}
+
 /**
  * Whether `address:port` accepts a connection now: `true`, or why the attempt
  * failed (the socket error's code, `ECONNREFUSED` while nothing listens, or
@@ -1207,7 +1226,7 @@ function createApiPort({ entries, httpPort, cwd, targetOf, readEnvironment, mech
         // A server behind a bridge gets a private directory for the Unix socket its shim serves, which only that call's
         // server may write; it joins the scratch list like the port directory.
         if (launched !== null && mechanism.bridges === true) bridgeDirectory = makeBridgeDirectory(scratch);
-        const launchedPort = launched === null || reports ? null : await freePort();
+        const launchedPort = launched === null || reports ? null : await freePort(launched.addresses);
         const configurationAt = (port) =>
           portConfiguration({
             entries,
@@ -1397,6 +1416,7 @@ module.exports = {
   defaultPortOf,
   deploymentAccess,
   deploymentAuthorizations,
+  freePort,
   httpPortFile,
   isApiEntry,
   makeBridgeDirectory,