@spec-wave/cli 0.29.0 → 0.32.0

package/src/lib/qa-lead-backend.mjs

@@ -0,0 +1,213 @@
+// Backends de execução do `qa-lead run` (rfc/spec-qa-lead.md §6.4).
+//
+// Interface única, duas implementações, escolhidas por `qa.lead.backend`:
+//
+//  • `docker` (default desta entrega): um `docker run` por Feature, com rede
+//    isolada, clone próprio do checkout e cleanup garantido — inclusive na
+//    morte do Lead (handler de sinal registrado pelo comando): container órfão
+//    consome recurso do cliente.
+//  • `sandbox`: a interface existe, a implementação é follow-up — a Tarefa Zero
+//    confirmou que o spec-wave-sandbox ainda não expõe API de criação de
+//    sessão. Escolhê-lo recusa orientando, em vez de fingir que roda.
+//
+// O container NÃO compartilha o checkout do host: ele CLONA `/repo` (montado
+// read-only) para um diretório próprio. Dois `qa` paralelos commitando bug.md
+// no MESMO working tree corromperiam o index um do outro; com clones isolados,
+// a contenção fica onde a §3.2 já a resolve — no push, com retry+rebase.
+
+import { spawn, execFileSync } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+function sh(args, opts = {}) {
+  return execFileSync('docker', args, {
+    encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], ...opts,
+  }).trim();
+}
+
+/**
+ * Monta o script executado DENTRO do container (função PURA — testável).
+ *
+ * `qa.setup` roda antes do `qa` (§6.2: "Dentro do container: qa.setup →
+ * qa <feature>"); o endereço real do serviço chega por env injetada (§3.1).
+ *
+ * @param {object} params
+ * @param {number} params.issue
+ * @param {number[]|null} [params.only]
+ * @param {string|null} [params.setup] `qa.setup` do .spec-wave.json
+ * @param {string} params.cliVersion versão fixada da CLI
+ * @param {string|null} [params.originUrl] remoto real (o clone nasce apontando
+ *        para /repo, que é read-only — sem isto o push do bug.md morre)
+ * @returns {string} script bash
+ */
+export function containerScript({ issue, only = null, setup = null, cliVersion, originUrl = null }) {
+  const lines = [
+    'set -euo pipefail',
+    'git clone /repo /spec-wave-work',
+    'cd /spec-wave-work',
+    'git config user.name "spec-wave-qa"',
+    'git config user.email "spec-wave-qa[bot]@users.noreply.github.com"',
+  ];
+  if (originUrl) lines.push(`git remote set-url origin ${JSON.stringify(originUrl)}`);
+  if (setup) lines.push(setup);
+  const onlyFlag = only && only.length > 0 ? ` --only ${only.join(',')}` : '';
+  lines.push(`npx -y @spec-wave/cli@${cliVersion} qa ${issue}${onlyFlag}`);
+  return lines.join('\n');
+}
+
+/** Backend Docker — um container e uma rede por execução. */
+export class DockerBackend {
+  /**
+   * @param {object} params
+   * @param {string} params.image `qa.lead.container.image`
+   * @param {string} params.checkoutDir raiz do clone do host (montada em /repo)
+   */
+  constructor({ image, checkoutDir }) {
+    this.image = image;
+    this.checkoutDir = checkoutDir;
+    /** @type {Set<string>} containers vivos (para o cleanup de sinal) */
+    this.live = new Set();
+    /** @type {Set<string>} redes criadas */
+    this.networks = new Set();
+  }
+
+  /** O docker responde? (best-effort — o preflight consome) */
+  available() {
+    try {
+      sh(['info', '--format', '{{.ServerVersion}}']);
+      return { ok: true, detail: null };
+    } catch (err) {
+      return { ok: false, detail: String(err.stderr || err.message).split('\n')[0] };
+    }
+  }
+
+  /** A imagem existe localmente ou é puxável? (preflight) */
+  imageAvailable() {
+    try {
+      sh(['image', 'inspect', this.image]);
+      return { ok: true, detail: 'imagem presente localmente' };
+    } catch {
+      try {
+        sh(['pull', this.image], { stdio: ['ignore', 'pipe', 'pipe'] });
+        return { ok: true, detail: 'imagem puxada do registry' };
+      } catch (err) {
+        return { ok: false, detail: String(err.stderr || err.message).split('\n')[0] };
+      }
+    }
+  }
+
+  /**
+   * Roda um script num container isolado até terminar ou estourar o timeout.
+   *
+   * @param {object} params
+   * @param {string} params.name sufixo estável (ex.: `qa-318`)
+   * @param {string} params.script bash de containerScript()
+   * @param {Record<string,string>} [params.env]
+   * @param {number} params.timeoutMin
+   * @param {(line: string) => void} [params.onLog]
+   * @returns {Promise<{ ok: boolean, timedOut: boolean, code: number|null, durationSec: number }>}
+   */
+  async run({ name, script, env = {}, timeoutMin, onLog = () => {} }) {
+    const id = `spec-wave-${name}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+    const network = `${id}-net`;
+    const started = Date.now();
+
+    sh(['network', 'create', network]);
+    this.networks.add(network);
+
+    const args = [
+      'run', '--rm', '--name', id, '--network', network,
+      '-v', `${this.checkoutDir}:/repo:ro`,
+      '-w', '/',
+    ];
+    for (const [key, value] of Object.entries(env)) {
+      if (value == null || value === '') continue; // credencial vazia não entra
+      args.push('-e', `${key}=${value}`);
+    }
+    args.push(this.image, 'bash', '-lc', script);
+
+    this.live.add(id);
+    let timedOut = false;
+    const code = await new Promise((resolve) => {
+      const child = spawn('docker', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+      const feed = (chunk) => String(chunk).split('\n').filter(Boolean).forEach(onLog);
+      child.stdout.on('data', feed);
+      child.stderr.on('data', feed);
+      const timer = setTimeout(() => {
+        timedOut = true;
+        try { sh(['rm', '-f', id]); } catch { /* já morreu */ }
+      }, timeoutMin * 60 * 1000);
+      child.on('close', (exitCode) => {
+        clearTimeout(timer);
+        resolve(exitCode);
+      });
+      child.on('error', () => {
+        clearTimeout(timer);
+        resolve(null);
+      });
+    });
+    this.live.delete(id);
+    try { sh(['network', 'rm', network]); this.networks.delete(network); } catch { /* fica para o cleanup */ }
+
+    return {
+      ok: !timedOut && code === 0,
+      timedOut,
+      code,
+      durationSec: Math.round((Date.now() - started) / 1000),
+    };
+  }
+
+  /** Mata containers vivos e remove redes — chamado no fim E no sinal. */
+  async cleanup() {
+    for (const id of [...this.live]) {
+      try { sh(['rm', '-f', id]); } catch { /* já removido */ }
+      this.live.delete(id);
+    }
+    // A rede só desmonta depois que o container solta — uma tentativa tardia.
+    await sleep(200);
+    for (const net of [...this.networks]) {
+      try { sh(['network', 'rm', net]); this.networks.delete(net); } catch { /* melhor esforço */ }
+    }
+  }
+}
+
+/**
+ * Backend do spec-wave-sandbox — INTERFACE pronta, implementação follow-up.
+ *
+ * A Tarefa Zero (item 4) verificou que a API de sessão ainda não existe; até
+ * ela existir, escolher este backend é um erro orientado, não um stub que
+ * finge executar.
+ */
+export class SandboxBackend {
+  constructor() {
+    this.reason =
+      'O backend `sandbox` ainda não está disponível: o spec-wave-sandbox não expõe API de ' +
+      'criação de sessão (Tarefa Zero, rfc/spec-qa-lead.md). Use `qa.lead.backend: "docker"`.';
+  }
+
+  available() {
+    return { ok: false, detail: this.reason };
+  }
+
+  imageAvailable() {
+    return { ok: false, detail: this.reason };
+  }
+
+  async run() {
+    throw new Error(this.reason);
+  }
+
+  async cleanup() { /* nada a limpar */ }
+}
+
+/**
+ * Fabrica o backend configurado.
+ *
+ * @param {object} params
+ * @param {'docker'|'sandbox'} params.backend
+ * @param {string|null} params.image
+ * @param {string} params.checkoutDir
+ */
+export function createExecutionBackend({ backend, image, checkoutDir }) {
+  if (backend === 'sandbox') return new SandboxBackend();
+  return new DockerBackend({ image, checkoutDir });
+}