@avi770/testteam 1.2.0

package/core/ci-output.ts

@@ -0,0 +1,240 @@
+import type { RunState, AgentResult, PhaseGateResult } from './types';
+import * as fs from 'fs';
+
+/** Exit codes for CI integration. */
+export const EXIT_CODE = {
+  /** All phase gates passed, no issues. */
+  SUCCESS: 0,
+  /** One or more blocking agent failures. */
+  BLOCKING_FAILURE: 1,
+  /** All blocking agents passed, but advisory agents found issues. */
+  ADVISORY_WARNINGS: 2,
+} as const;
+
+export type ExitCode = typeof EXIT_CODE[keyof typeof EXIT_CODE];
+
+/** Detected CI environment. */
+export type CIEnvironment = 'github' | 'azure' | 'gitlab' | 'none';
+
+/** Detect which CI environment is running. */
+export function detectCIEnvironment(): CIEnvironment {
+  if (process.env['GITHUB_ACTIONS'] === 'true') {
+    return 'github';
+  }
+  if (process.env['TF_BUILD'] === 'True') {
+    return 'azure';
+  }
+  if (process.env['GITLAB_CI'] === 'true') {
+    return 'gitlab';
+  }
+  return 'none';
+}
+
+/**
+ * Determine the appropriate exit code from run state.
+ * - 0: All gates passed, no advisory failures
+ * - 1: Blocking agent failures
+ * - 2: Advisory warnings only (all blocking passed)
+ */
+export function determineExitCode(gateResults: PhaseGateResult[]): ExitCode {
+  const hasBlockingFailures = gateResults.some(
+    gate => gate.failedBlockingAgents.length > 0,
+  );
+
+  if (hasBlockingFailures) {
+    return EXIT_CODE.BLOCKING_FAILURE;
+  }
+
+  const hasAdvisoryFailures = gateResults.some(gate =>
+    gate.advisoryResults.some(result => result.status === 'failed'),
+  );
+
+  if (hasAdvisoryFailures) {
+    return EXIT_CODE.ADVISORY_WARNINGS;
+  }
+
+  return EXIT_CODE.SUCCESS;
+}
+
+/** Format duration in human-readable form. */
+function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) {
+    return `${seconds}s`;
+  }
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+/** Get a status icon for an agent result. */
+function statusIcon(status: AgentResult['status']): string {
+  switch (status) {
+    case 'passed':
+      return '✅';
+    case 'failed':
+      return '❌';
+    case 'skipped':
+      return '⏭️';
+    case 'running':
+      return '🔄';
+    case 'pending':
+      return '⏳';
+    default:
+      return '❓';
+  }
+}
+
+/** Generate markdown summary for GitHub Actions GITHUB_STEP_SUMMARY. */
+export function generateGitHubSummary(results: RunState): string {
+  const lines: string[] = [];
+
+  const overallExitCode = determineExitCode(results.gateResults);
+  const overallStatus = overallExitCode === EXIT_CODE.SUCCESS
+    ? '✅ All Gates Passed'
+    : overallExitCode === EXIT_CODE.ADVISORY_WARNINGS
+      ? '⚠️ Advisory Warnings'
+      : '❌ Blocking Failures';
+
+  lines.push(`## TestTeam — ${overallStatus}`);
+  lines.push('');
+  lines.push(`| Detail | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Run ID | \`${results.runId}\` |`);
+  lines.push(`| Started | ${results.startedAt} |`);
+  lines.push(`| Total Cost | $${results.totalCost.toFixed(4)} |`);
+  lines.push('');
+
+  for (const gate of results.gateResults) {
+    const gateIcon = gate.passed ? '✅' : '❌';
+    lines.push(`### ${gateIcon} Phase: \`${gate.phase}\``);
+    lines.push('');
+
+    if (gate.failedBlockingAgents.length > 0) {
+      lines.push(`**Failed blocking agents:** ${gate.failedBlockingAgents.join(', ')}`);
+      lines.push('');
+    }
+
+    // Agent results table
+    const allResults = [...gate.blockingResults, ...gate.advisoryResults];
+    if (allResults.length > 0) {
+      lines.push(`| Agent | Status | Duration | Findings |`);
+      lines.push(`|-------|--------|----------|----------|`);
+
+      for (const result of allResults) {
+        const icon = statusIcon(result.status);
+        const duration = formatDuration(result.durationMs);
+        const findingCount = result.findings.length;
+        lines.push(
+          `| ${icon} ${result.agentName} (#${result.agentId}) | ${result.status} | ${duration} | ${findingCount} |`,
+        );
+      }
+      lines.push('');
+    }
+  }
+
+  // Findings summary
+  const allFindings = Array.from(results.agentResults.values())
+    .flatMap(r => r.findings);
+
+  if (allFindings.length > 0) {
+    lines.push(`### Findings Summary`);
+    lines.push('');
+
+    const bySeverity = new Map<string, number>();
+    for (const finding of allFindings) {
+      bySeverity.set(finding.severity, (bySeverity.get(finding.severity) ?? 0) + 1);
+    }
+
+    lines.push(`| Severity | Count |`);
+    lines.push(`|----------|-------|`);
+    for (const [severity, count] of bySeverity) {
+      lines.push(`| ${severity} | ${count} |`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/** Generate Azure Pipelines build tags from run results. */
+export function generateAzureTags(results: RunState): string[] {
+  const tags: string[] = [];
+
+  const exitCode = determineExitCode(results.gateResults);
+
+  if (exitCode === EXIT_CODE.SUCCESS) {
+    tags.push('testteam:passed');
+  } else if (exitCode === EXIT_CODE.ADVISORY_WARNINGS) {
+    tags.push('testteam:warnings');
+  } else {
+    tags.push('testteam:failed');
+  }
+
+  for (const gate of results.gateResults) {
+    tags.push(`testteam:phase:${gate.phase}`);
+    tags.push(`testteam:phase:${gate.phase}:${gate.passed ? 'passed' : 'failed'}`);
+  }
+
+  const allFindings = Array.from(results.agentResults.values())
+    .flatMap(r => r.findings);
+
+  const severities = new Set(allFindings.map(f => f.severity));
+  for (const severity of severities) {
+    tags.push(`testteam:severity:${severity}`);
+  }
+
+  return tags;
+}
+
+/** Injectable IO operations for testability in ESM. */
+export interface CIOutputIO {
+  appendFile: (path: string, data: string) => void;
+  writeFile: (path: string, data: string) => void;
+  log: (message: string) => void;
+}
+
+const defaultIO: CIOutputIO = {
+  appendFile: (filePath, data) => fs.appendFileSync(filePath, data),
+  writeFile: (filePath, data) => fs.writeFileSync(filePath, data),
+  log: (message) => console.log(message),
+};
+
+/** Write CI summary to the appropriate CI environment output. */
+export function writeCISummary(results: RunState, io: CIOutputIO = defaultIO): void {
+  const env = detectCIEnvironment();
+
+  switch (env) {
+    case 'github': {
+      const summaryPath = process.env['GITHUB_STEP_SUMMARY'];
+      if (summaryPath) {
+        const markdown = generateGitHubSummary(results);
+        io.appendFile(summaryPath, markdown + '\n');
+      }
+      break;
+    }
+    case 'azure': {
+      const tags = generateAzureTags(results);
+      for (const tag of tags) {
+        io.log(`##vso[build.addbuildtag]${tag}`);
+      }
+      // Also output markdown to the task log
+      const markdown = generateGitHubSummary(results);
+      io.log(markdown);
+      break;
+    }
+    case 'gitlab': {
+      // GitLab CI doesn't have a native summary mechanism,
+      // so write to a file that can be picked up as an artifact
+      const markdown = generateGitHubSummary(results);
+      io.writeFile('.run/testteam-summary.md', markdown);
+      break;
+    }
+    case 'none':
+      // Not in CI; no summary written
+      break;
+  }
+}

package/core/cli.ts

@@ -0,0 +1,232 @@
+import type { Phase, PhaseGateResult, AgentResult } from './types';
+import type { TestTeamConfig } from './config';
+import { validateConfig } from './config';
+import { Orchestrator } from './orchestrator';
+import { registerAllAgents } from '../agents/registry';
+import { runInitWizard } from './init';
+import { determineExitCode, writeCISummary, detectCIEnvironment } from './ci-output';
+import type { ExitCode } from './ci-output';
+import * as path from 'path';
+
+const PHASES: readonly Phase[] = ['alpha', 'beta', 'uat', 'release'];
+
+interface ParsedArgs {
+  phase: Phase | 'all' | null;
+  dryRun: boolean;
+  agent: number | null;
+  configPath: string;
+}
+
+function printUsage(): void {
+  console.log(`
+Usage: testteam [options]
+
+Options:
+  init                                   Initialize TestTeam in current directory
+  --phase <alpha|beta|uat|release|all>   Phase to run (required unless --dry-run)
+  --dry-run                              Show dispatch plan without executing
+  --agent <id>                           Run a single agent by ID
+  --config <path>                        Path to config file (default: testteam.config.ts)
+  --help                                 Show this help message
+`.trim());
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const args = argv.slice(2); // skip node + script path
+  let phase: Phase | 'all' | null = null;
+  let dryRun = false;
+  let agent: number | null = null;
+  let configPath = 'testteam.config.ts';
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case '--phase': {
+        const value = args[++i];
+        if (!value || (!PHASES.includes(value as Phase) && value !== 'all')) {
+          throw new Error(`Invalid phase: ${value}. Must be one of: ${PHASES.join(', ')}, all`);
+        }
+        phase = value as Phase | 'all';
+        break;
+      }
+      case '--dry-run':
+        dryRun = true;
+        break;
+      case '--agent': {
+        const value = args[++i];
+        const parsed = Number(value);
+        if (!value || isNaN(parsed) || parsed < 1) {
+          throw new Error(`Invalid agent ID: ${value}. Must be a positive integer.`);
+        }
+        agent = parsed;
+        break;
+      }
+      case '--config':
+        configPath = args[++i];
+        if (!configPath) {
+          throw new Error('--config requires a path argument');
+        }
+        break;
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return { phase, dryRun, agent, configPath };
+}
+
+async function loadConfig(configPath: string): Promise<TestTeamConfig> {
+  const absolutePath = path.resolve(configPath);
+  // On Windows, dynamic import requires file:// URLs
+  const fileUrl = new URL(`file:///${absolutePath.replace(/\\/g, '/')}`).href;
+  const module = await import(fileUrl) as { default?: TestTeamConfig; config?: TestTeamConfig };
+  const raw = module.default ?? module.config;
+  if (!raw) {
+    throw new Error(`Config file does not export a default or named 'config': ${absolutePath}`);
+  }
+  return raw;
+}
+
+export async function main(argv: string[] = process.argv): Promise<number> {
+  // Handle init command before normal arg parsing
+  const rawArgs = argv.slice(2);
+  if (rawArgs.includes('init') || rawArgs.includes('--init')) {
+    return runInitWizard();
+  }
+
+  if (argv.length <= 2) {
+    printUsage();
+    return 1;
+  }
+
+  let parsed: ParsedArgs;
+  try {
+    parsed = parseArgs(argv);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    printUsage();
+    return 1;
+  }
+
+  const { phase, dryRun, configPath } = parsed;
+
+  if (!dryRun && !phase) {
+    console.error('--phase is required unless using --dry-run');
+    printUsage();
+    return 1;
+  }
+
+  // Load and validate config
+  let rawConfig: TestTeamConfig;
+  try {
+    rawConfig = await loadConfig(configPath);
+  } catch (error) {
+    console.error(`Failed to load config: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+
+  const config = validateConfig(rawConfig);
+
+  // Shared run directory so all phases write results to the same location.
+  // This ensures the Reporter (Agent 10, release phase) can read results
+  // from prior phases (alpha, beta, uat).
+  const sharedRunDir = path.join(process.cwd(), '.run', `run-${Date.now()}`);
+
+  if (dryRun) {
+    const targetPhases: Phase[] = phase === 'all' || !phase
+      ? [...PHASES]
+      : [phase];
+
+    for (const p of targetPhases) {
+      const phaseOrchestrator = new Orchestrator(config, sharedRunDir);
+      registerAllAgents(phaseOrchestrator, config, p, sharedRunDir);
+      const plan = phaseOrchestrator.dryRun(p);
+      console.log(`\nPhase: ${p}`);
+      for (const entry of plan) {
+        console.log(`  Agent ${entry.agentId}: ${entry.status}`);
+      }
+    }
+    return 0;
+  }
+
+  // Run mode — create a fresh orchestrator per phase to avoid agent instance
+  // conflicts (GAP-023: registerAgent uses Map.set which overwrites).
+  const targetPhases: Phase[] = phase === 'all'
+    ? [...PHASES]
+    : [phase as Phase];
+
+  const collectedGates: PhaseGateResult[] = [];
+  const collectedResults = new Map<number, AgentResult>();
+  let hadError = false;
+
+  for (const p of targetPhases) {
+    console.log(`\nRunning phase: ${p}`);
+    try {
+      const phaseOrchestrator = new Orchestrator(config, sharedRunDir);
+      registerAllAgents(phaseOrchestrator, config, p, sharedRunDir);
+      const result = await phaseOrchestrator.runPhase(p);
+
+      if (result.skippedAgents.length > 0) {
+        console.log(`  Skipped agents: ${result.skippedAgents.join(', ')}`);
+      }
+
+      const resultCount = Object.keys(result.agentResults).length;
+      console.log(`  Completed ${resultCount} agent(s)`);
+
+      if (result.gate.passed) {
+        console.log(`  Gate: PASSED`);
+      } else {
+        console.log(`  Gate: FAILED (blocking agents: ${result.gate.failedBlockingAgents.join(', ')})`);
+      }
+
+      collectedGates.push(result.gate);
+
+      // Merge agent results for CI summary
+      for (const [agentId, agentResult] of Object.entries(result.agentResults)) {
+        collectedResults.set(Number(agentId), agentResult);
+      }
+    } catch (error) {
+      console.error(`  Phase ${p} error: ${error instanceof Error ? error.message : String(error)}`);
+      hadError = true;
+    }
+  }
+
+  // Determine structured exit code:
+  // - 0: All gates passed, no advisory failures
+  // - 1: Blocking agent failures (or runtime errors)
+  // - 2: Advisory warnings only
+  const exitCode: ExitCode = hadError
+    ? 1
+    : determineExitCode(collectedGates);
+
+  // Write CI summary if running in a CI environment
+  const ciEnv = detectCIEnvironment();
+  if (ciEnv !== 'none') {
+    const runState: import('./types').RunState = {
+      runId: path.basename(sharedRunDir),
+      startedAt: new Date().toISOString(),
+      currentPhase: targetPhases[targetPhases.length - 1],
+      phaseAttempt: 1,
+      agentResults: collectedResults,
+      gateResults: collectedGates,
+      totalCost: 0,
+    };
+    writeCISummary(runState);
+  }
+
+  return exitCode;
+}
+
+// Direct execution — works with both tsx and node
+const isDirectExecution =
+  typeof process !== 'undefined' &&
+  process.argv[1] &&
+  (process.argv[1].includes('cli.ts') || process.argv[1].includes('cli.js'));
+
+if (isDirectExecution) {
+  main().then((code) => process.exit(code));
+}

package/core/config.ts

@@ -0,0 +1,178 @@
+export interface WorkflowStep {
+  action: 'navigate' | 'click' | 'fill-form' | 'wait' | 'verify';
+  target: string;
+  verify?: string;
+  data?: string;
+  timeout?: number;
+  contains?: string;
+}
+
+export interface ModuleConfig {
+  id: string;
+  route: string;
+  sidebarIcon: boolean;
+}
+
+export interface CredentialEntry {
+  email: string;
+  password: string;
+}
+
+export interface RoleEntry {
+  name: string;
+  email: string;
+}
+
+export interface AuthConfig {
+  loginUrl?: string;
+  credentials?: Record<string, CredentialEntry>;
+  roles?: RoleEntry[];
+}
+
+export interface EnvironmentConfig {
+  baseUrl: string;
+  seed?: boolean;
+}
+
+export interface PortalConfig {
+  name: string;
+  queryParam: string | null;
+}
+
+export interface IntegrationConfig {
+  name: string;
+  [key: string]: unknown;
+}
+
+export interface WorkerConfig {
+  name: string;
+  [key: string]: unknown;
+}
+
+export interface WorkflowConfig {
+  name: string;
+  steps: WorkflowStep[];
+}
+
+export interface AccuracyConfig {
+  enabled: boolean;
+  decimalPrecision: number;
+  currencySymbol: string;
+  timezone: string;
+}
+
+export interface TenancyConfig {
+  enabled: boolean;
+  isolationField: string;
+  testFirms: string[];
+}
+
+export interface CostBudgetConfig {
+  maxPerRun: number;
+  maxPerAgent: number;
+  alertThreshold: number;
+  onExceeded: 'abort' | 'alert-continue' | 'skip-remaining';
+}
+
+export interface AgentClassificationConfig {
+  blocking: number[];
+  advisory: number[];
+}
+
+export interface CoverageThresholds {
+  lines: number;
+  functions: number;
+  branches: number;
+  statements: number;
+}
+
+export interface LighthouseThresholds {
+  accessibility: number;
+  performance: number;
+  bestPractices: number;
+  seo: number;
+}
+
+export interface ThresholdsConfig {
+  unitCoverage: CoverageThresholds;
+  lighthouse: LighthouseThresholds;
+  apiResponseTime: number;
+  bundleSizeLimit: number;
+  maxConsoleErrors: number;
+}
+
+export interface TestTeamConfig {
+  schemaVersion: number;
+  name: string;
+  /** Absolute path to the target project root (where package.json, prisma/, apps/ live) */
+  projectRoot?: string;
+  auth: AuthConfig;
+  modules: ModuleConfig[];
+  environments: Record<string, EnvironmentConfig>;
+  portals: PortalConfig[];
+  breakpoints: number[];
+  integrations: IntegrationConfig[];
+  workers: WorkerConfig[];
+  workflows: WorkflowConfig[];
+  accuracy: AccuracyConfig;
+  tenancy: TenancyConfig;
+  costBudget: CostBudgetConfig;
+  agentClassification: AgentClassificationConfig;
+  thresholds: ThresholdsConfig;
+  disabledAgents: number[];
+}
+
+export interface ValidatedConfig extends TestTeamConfig {
+  disabledAgentSet: Set<number>;
+}
+
+export function validateConfig(raw: TestTeamConfig): ValidatedConfig {
+  if (raw.schemaVersion === undefined || raw.schemaVersion === null) {
+    throw new Error('schemaVersion is required');
+  }
+
+  if (!raw.name) {
+    throw new Error('name is required');
+  }
+
+  if (raw.modules !== undefined && !Array.isArray(raw.modules)) {
+    throw new Error('modules must be an array');
+  }
+
+  if (raw.modules !== undefined && Array.isArray(raw.modules) && raw.modules.length === 0) {
+    throw new Error('modules must contain at least one module');
+  }
+
+  if (!raw.auth) {
+    throw new Error('auth is required');
+  }
+
+  const disabledAgentSet = new Set<number>(raw.disabledAgents ?? []);
+
+  // Warn on empty credential passwords and empty emails
+  if (raw.auth.credentials) {
+    const entries = Object.entries(raw.auth.credentials);
+    let allPasswordsEmpty = entries.length > 0;
+
+    for (const [role, entry] of entries) {
+      if (entry.password === '') {
+        console.warn(`[TestTeam] Warning: credential "${role}" has an empty password. Set a real password in your config.`);
+      } else {
+        allPasswordsEmpty = false;
+      }
+
+      if (entry.email === '') {
+        console.warn(`[TestTeam] Warning: credential "${role}" has an empty email. Set TF_${role.toUpperCase()}_EMAIL in your environment.`);
+      }
+    }
+
+    if (allPasswordsEmpty && entries.length > 0) {
+      throw new Error('All credentials have empty passwords. At least one credential must have a non-empty password.');
+    }
+  }
+
+  return {
+    ...raw,
+    disabledAgentSet,
+  };
+}

package/core/cost-tracker.ts

@@ -0,0 +1,59 @@
+export interface CostBudget {
+  maxPerRun: number;
+  maxPerAgent: number;
+  alertThreshold: number;
+  onExceeded: 'abort' | 'alert-continue' | 'skip-remaining';
+}
+
+export interface BudgetCheckResult {
+  status: 'ok' | 'alert' | 'exceeded';
+  totalCost: number;
+  budgetRemaining: number;
+}
+
+export class CostTracker {
+  private readonly budget: CostBudget;
+  private readonly agentCosts: Map<string, number> = new Map();
+
+  constructor(budget: CostBudget) {
+    this.budget = budget;
+  }
+
+  trackCost(agentId: string, amount: number): void {
+    const current = this.agentCosts.get(agentId) ?? 0;
+    this.agentCosts.set(agentId, current + amount);
+  }
+
+  getTotalCost(): number {
+    let total = 0;
+    for (const cost of this.agentCosts.values()) {
+      total += cost;
+    }
+    return total;
+  }
+
+  getAgentCost(agentId: string): number {
+    return this.agentCosts.get(agentId) ?? 0;
+  }
+
+  checkBudget(): BudgetCheckResult {
+    const totalCost = this.getTotalCost();
+    const budgetRemaining = this.budget.maxPerRun - totalCost;
+    const alertLimit = this.budget.maxPerRun * this.budget.alertThreshold;
+
+    let status: 'ok' | 'alert' | 'exceeded';
+    if (totalCost >= this.budget.maxPerRun) {
+      status = 'exceeded';
+    } else if (totalCost >= alertLimit) {
+      status = 'alert';
+    } else {
+      status = 'ok';
+    }
+
+    return { status, totalCost, budgetRemaining };
+  }
+
+  isAgentOverBudget(agentId: string): boolean {
+    return this.getAgentCost(agentId) >= this.budget.maxPerAgent;
+  }
+}