@spec-wave/cli 0.30.0 → 0.33.0

package/src/lib/git-retry.mjs

@@ -0,0 +1,82 @@
+// Push com `pull --rebase` + retry — spec-qa-lead §3.2.
+//
+// O `qa` commita o bug.md no checkout e PUBLICA: com o `qa-lead` despachando N
+// containers em paralelo, um commit que fica só no container morre com ele — e
+// dois containers reprovando ao mesmo tempo fazem o segundo push ser rejeitado.
+// O retry cobre exatamente a rejeição de corrida (`non-fast-forward`,
+// `cannot lock ref`); recusa DELIBERADA do remoto (GH006/branch protegida,
+// auth) falha na primeira, porque repetir uma recusa de política só multiplica
+// o custo — a mesma divisão do isTransientProviderError do lado da IA.
+
+import { execFileSync } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+/** Tentativas de pull+push antes de desistir (teto da spec: 5). */
+export const PUSH_MAX_ATTEMPTS = 5;
+
+// Rejeições que significam "outro push chegou antes" — repetir resolve.
+const TRANSIENT_RE = /non-fast-forward|cannot lock ref|fetch first|failed to push some refs|cannot rebase onto multiple branches|shallow update not allowed/i;
+
+// Recusas de política/credencial — repetir NUNCA resolve.
+const PERMANENT_RE = /GH006|protected branch|permission denied|authentication|403|could not read Username|denied to|no upstream branch|not a git repository|could not resolve host|unable to access/i;
+
+/**
+ * A rejeição de push parece uma corrida perdida? (função PURA)
+ *
+ * Na dúvida (mensagem que não casa com nenhum padrão), transitória: o custo de
+ * uma tentativa a mais é segundos; o de desistir cedo é perder um Bug cujo
+ * cenário já foi pago.
+ *
+ * @param {string} stderr saída de erro do git
+ * @returns {boolean}
+ */
+export function isTransientPushRejection(stderr) {
+  const text = String(stderr || '');
+  if (PERMANENT_RE.test(text)) return false;
+  if (TRANSIENT_RE.test(text)) return true;
+  return true;
+}
+
+function git(cwd, args) {
+  // stderr capturado de propósito: a classificação transitória/permanente
+  // depende de LER a rejeição — `stdio: 'inherit'` a jogaria no terminal.
+  return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/**
+ * `pull --rebase` + `push`, repetindo enquanto a rejeição for de corrida.
+ *
+ * Backoff linear com jitter (1s, 2s, 3s…): os perdedores da corrida se
+ * espalham em vez de colidirem de novo no mesmo instante.
+ *
+ * @param {object} params
+ * @param {string} params.cwd raiz do checkout
+ * @param {number} [params.attempts]
+ * @param {(ms: number) => Promise<void>} [params.delay] injetável nos testes
+ * @returns {Promise<{ ok: boolean, attempts: number, error: string|null }>}
+ */
+export async function pushWithRebase({ cwd, attempts = PUSH_MAX_ATTEMPTS, delay = sleep } = {}) {
+  let lastError = null;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      try {
+        git(cwd, ['pull', '--rebase', '--autostash']);
+      } catch (err) {
+        // Sem upstream configurado o pull falha, mas o push ainda pode passar
+        // (primeiro push da branch) — deixa o push decidir.
+        lastError = String(err.stderr || err.message || err);
+      }
+      git(cwd, ['push']);
+      return { ok: true, attempts: attempt, error: null };
+    } catch (err) {
+      lastError = String(err.stderr || err.message || err);
+      if (!isTransientPushRejection(lastError)) {
+        return { ok: false, attempts: attempt, error: lastError.trim() };
+      }
+      if (attempt < attempts) {
+        await delay(attempt * 1000 + Math.floor(Math.random() * 500));
+      }
+    }
+  }
+  return { ok: false, attempts, error: (lastError || 'push rejeitado').trim() };
+}

package/src/lib/net-cache.mjs

@@ -0,0 +1,142 @@
+// Cache local de leituras do GitHub (I/O fino — as decisões de frescor são
+// puras, em lib/dependency-map.mjs).
+//
+// Vive em `<root>/.spec-wave/cache/` — o diretório de scratch já gitignored:
+// cache é POR CLONE, nunca commitado (o que é commitável é o
+// dependency-map.json, que não expira). Regras que não se negociam:
+//
+//  • best-effort nos dois sentidos: ler cache corrompido devolve null (e
+//    apaga), gravar NUNCA lança — cache indisponível vira refetch, não erro;
+//  • só SUCESSO entra: um `.catch(() => [])` de rede não pode virar uma lista
+//    vazia cacheada por 10 minutos — o dado errado com cara de fresco é pior
+//    que a chamada repetida que o cache existe para evitar;
+//  • entrada de outro owner/repo (worktree, config trocado) é ignorada;
+//  • mutação nunca lê cache e sempre INVALIDA o que tocou.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const CACHE_VERSION = 1;
+
+/** Default do TTL: 10 minutos — cobre um encadeamento order → implement → merge. */
+export const DEFAULT_CACHE_TTL_SEC = 600;
+
+const CACHE_DIR = ['.spec-wave', 'cache'];
+
+/** Caminho absoluto de uma entrada. */
+export function cachePath(root, key) {
+  return path.join(root || process.cwd(), ...CACHE_DIR, `${sanitizeKey(key)}.json`);
+}
+
+// A chave vira nome de arquivo: nada de separadores de caminho.
+function sanitizeKey(key) {
+  return String(key).replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+/**
+ * TTL efetivo do cache (função PURA).
+ *
+ * Precedência: env `SPEC_WAVE_CACHE_TTL` (segundos; `0` desliga) →
+ * `cache.ttlSec` do .spec-wave.json → 600.
+ *
+ * @param {object|null} config o .spec-wave.json
+ * @param {object} [env]
+ * @returns {number} segundos (0 = desligado)
+ */
+export function resolveCacheTtl(config, env = process.env) {
+  const fromEnv = env?.SPEC_WAVE_CACHE_TTL;
+  if (fromEnv !== undefined && fromEnv !== '') {
+    const n = Number(fromEnv);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  const fromConfig = config?.cache?.ttlSec;
+  if (Number.isFinite(fromConfig) && fromConfig >= 0) return fromConfig;
+  return DEFAULT_CACHE_TTL_SEC;
+}
+
+/**
+ * Lê uma entrada do cache. `null` em qualquer defeito: ausente, JSON inválido,
+ * versão desconhecida, owner/repo (ou extra, ex.: projectId) divergentes.
+ *
+ * @param {string} root raiz do projeto
+ * @param {string} key
+ * @param {{owner?:string, repo?:string, [k:string]: *}} [expect] campos que a
+ *        entrada precisa bater para valer neste contexto
+ * @returns {{ kind:string, fetchedAt:string, data:* }|null}
+ */
+export function readCacheEntry(root, key, expect = {}) {
+  const file = cachePath(root, key);
+  let entry;
+  try {
+    entry = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    // Corrompida não volta a atrapalhar: apaga best-effort.
+    try { rmSync(file, { force: true }); } catch { /* melhor esforço */ }
+    return null;
+  }
+  if (entry?.v !== CACHE_VERSION || typeof entry.fetchedAt !== 'string') return null;
+  for (const [field, expected] of Object.entries(expect)) {
+    if (expected != null && entry[field] !== expected) return null;
+  }
+  return entry;
+}
+
+/**
+ * Grava uma entrada. NUNCA lança — disco cheio/sem permissão vira no-op.
+ *
+ * @param {string} root
+ * @param {string} key
+ * @param {string} kind ex.: 'board-items'
+ * @param {*} data resultado de uma chamada BEM-SUCEDIDA
+ * @param {object} [extra] campos de contexto (owner, repo, projectId…)
+ * @returns {boolean} true se gravou
+ */
+export function writeCacheEntry(root, key, kind, data, extra = {}) {
+  try {
+    const dir = path.join(root || process.cwd(), ...CACHE_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(cachePath(root, key), `${JSON.stringify({
+      v: CACHE_VERSION,
+      kind,
+      key: sanitizeKey(key),
+      fetchedAt: new Date().toISOString(),
+      ...extra,
+      data,
+    })}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove entradas por chave exata ou prefixo (`'blockedby-*'`). Best-effort.
+ *
+ * Chamada após qualquer ESCRITA que invalide a leitura cacheada — mover board,
+ * mergear, criar issues.
+ *
+ * @param {string} root
+ * @param {...string} keysOrPrefixes
+ */
+export function invalidateCache(root, ...keysOrPrefixes) {
+  const dir = path.join(root || process.cwd(), ...CACHE_DIR);
+  if (!existsSync(dir)) return;
+  let files;
+  try {
+    files = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const spec of keysOrPrefixes) {
+    const raw = String(spec);
+    const isPrefix = raw.endsWith('*');
+    const base = sanitizeKey(isPrefix ? raw.slice(0, -1) : raw);
+    for (const file of files) {
+      const name = file.replace(/\.json$/, '');
+      const hit = isPrefix ? name.startsWith(base) : name === base;
+      if (hit) {
+        try { rmSync(path.join(dir, file), { force: true }); } catch { /* melhor esforço */ }
+      }
+    }
+  }
+}

package/src/lib/qa-exec.mjs

@@ -200,6 +200,23 @@ export function renderQaCommand(template, vars) {
   return String(template).replace(/\{(\w+)\}/g, (m, key) => (key in vars ? vars[key] : m));
 }
 
+/**
+ * Ambiente entregue ao executor (função PURA) — spec-qa-lead §3.1.
+ *
+ * A env do PROCESSO tem precedência sobre `qa.env`, chave a chave. O motivo é o
+ * paralelismo do `qa-lead`: `qa.env` é versionado com o valor da execução
+ * manual (`BASE_URL: http://localhost:3000`), e N containers simultâneos
+ * precisam cada um do SEU endereço — o Lead injeta o valor real na sessão, sem
+ * placeholder no arquivo (a variação é de runtime, não de configuração).
+ *
+ * @param {Record<string,string>} [configEnv] bloco `qa.env` do .spec-wave.json
+ * @param {Record<string,string>} [processEnv] env do processo (vence)
+ * @returns {Record<string,string>}
+ */
+export function qaProcessEnv(configEnv = {}, processEnv = {}) {
+  return { ...(configEnv || {}), ...(processEnv || {}) };
+}
+
 /**
  * Monta o contexto entregue ao executor (função PURA).
  *
@@ -238,7 +255,8 @@ export function buildQaContext({
   lines.push('- Execute **um cenário por vez**, na ordem em que aparecem abaixo.');
   lines.push('- Registre a **evidência bruta** de cada cenário (comando executado, saída, código de status).');
   lines.push('- **NÃO corrija código.** QA não conserta: cenário reprovado vira Bug. Alterar o código durante a execução **invalida o veredito**.');
-  lines.push('- Cenário que **não pôde ser executado** (ambiente quebrado, seed que falhou, dependência fora do ar) é `blocked`, **nunca** `fail`.');
+  lines.push('- Cenário que **não pôde ser executado** (ambiente quebrado, seed que falhou, dependência fora do ar) é `blocked`, **nunca** `fail` — `fail` falso cria um Bug falso e custa investigação de dev.');
+  lines.push('- **NÃO escreva no GitHub** (comentar, abrir issue, mover card) — o veredito volta pelo arquivo de resultados; quem escreve no GitHub é a CLI.');
   lines.push('');
   lines.push('### Como registrar o veredito');
   lines.push('');
@@ -252,7 +270,10 @@ export function buildQaContext({
   }, null, 2));
   lines.push('```');
   lines.push('');
-  lines.push('Um objeto por cenário-alvo, com o número POSICIONAL do cenário. Nenhum pode ser omitido.');
+  lines.push('Um objeto por cenário-alvo, com o número POSICIONAL do cenário. Nenhum pode ser omitido — se abortar no meio, os cenários não alcançados entram como `blocked` (resultado parcial honesto vale mais que ausência de resultado). Regras duras (a CLI recusa o arquivo fora delas):');
+  lines.push('');
+  lines.push('- `fail` exige `evidencia` não vazia (ela vira o bug.md do Bug aberto);');
+  lines.push('- `blocked` exige `blockedReason`, um de: `ambiente` · `setup-falhou` · `massa-de-dados` · `dependencia-nao-entregue` · `bloqueado-por-bug` · `credencial` · `outro` (este exige `evidencia` com o motivo).');
 
   if (setup) {
     lines.push('');

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 });
+}