@jaimevalasek/aioson 1.21.8 → 1.23.0

package/src/commands/harness-retro.js

@@ -0,0 +1,221 @@
+'use strict';
+
+/**
+ * `aioson harness:retro [path] --feature=<slug> | --last=<N> [--json] [--locale=<l>]`
+ *
+ * Minera deterministicamente a trilha de falhas já coletada e materializa um
+ * dossiê retrospectivo em `.aioson/context/retro/{slug}.md` (ou
+ * `window-last-{N}.md`). Leitura-apenas sobre as fontes; única escrita: o dossiê.
+ * Sem LLM, sem rede (requirements §5.1, RHO-lite).
+ *
+ * Exit codes (D4 — devolvidos em `result.exitCode`, propagados por cli.js:1649
+ * em --json e por process.exitCode no modo texto; mesmo caminho de código para
+ * fechar a classe recorrente exit-code-collapsed-in-json-mode):
+ *   0  sucesso (inclusive dossiê vazio)
+ *   1  erro de I/O inesperado
+ *   12 erro de input (slug inválido, flags conflitantes, feature inexistente)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  collectSources, resolvePassDate, resolveFeatureExists, enumerateClosedFeatures, relPath
+} = require('../lib/retro/retro-sources');
+const { aggregate } = require('../lib/retro/retro-aggregate');
+const { renderDossier } = require('../lib/retro/retro-render');
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const EXIT_OK = 0;
+const EXIT_IO = 1;
+const EXIT_INPUT = 12;
+
+function tr(t, key, params, fallback) {
+  if (typeof t !== 'function') return fallback;
+  const msg = t(key, params);
+  return msg && msg !== key ? msg : fallback;
+}
+
+/** Encerra em erro de input: registra mensagem + devolve resultado com exitCode. */
+function inputError(logger, message, error) {
+  if (logger && typeof logger.error === 'function') logger.error(message);
+  process.exitCode = EXIT_INPUT;
+  return { ok: false, exitCode: EXIT_INPUT, error, message };
+}
+
+/** Datas `completed` do MANIFEST de arquivadas (fallback de ordenação). */
+function readManifestDates(targetDir) {
+  const map = {};
+  try {
+    const text = fs.readFileSync(path.join(targetDir, '.aioson', 'context', 'done', 'MANIFEST.md'), 'utf8');
+    for (const line of text.split(/\r?\n/)) {
+      const m = line.match(/^\|\s*([a-z0-9][a-z0-9-]*)\s*\|\s*([0-9-]{8,10})\s*\|/i);
+      if (m) map[m[1]] = m[2].trim();
+    }
+  } catch { /* best-effort */ }
+  return map;
+}
+
+/**
+ * Ordena uma lista de slugs por data de PASS desc (trail vence → QA → MANIFEST).
+ * Undatáveis são excluídos com aviso, salvo se marcados como âncora obrigatória.
+ */
+function rankByPassDate(targetDir, slugs, { anchor = null } = {}) {
+  const manifest = readManifestDates(targetDir);
+  const dated = [];
+  const undated = [];
+  for (const slug of slugs) {
+    const d = resolvePassDate(targetDir, slug) || manifest[slug] || null;
+    if (d) dated.push({ slug, date: d });
+    else if (slug === anchor) dated.push({ slug, date: '' }); // âncora entra mesmo sem data
+    else undated.push(slug);
+  }
+  dated.sort((a, b) => {
+    if (a.slug === anchor) return -1;
+    if (b.slug === anchor) return 1;
+    if (a.date !== b.date) return a.date < b.date ? 1 : -1; // desc
+    return a.slug < b.slug ? -1 : 1;
+  });
+  return { ordered: dated.map((x) => x.slug), undated };
+}
+
+async function runHarnessRetro({ args, options = {}, logger, t } = {}) {
+  const log = logger || { log() {}, error() {} };
+  const targetDir = path.resolve(process.cwd(), (args && args[0]) || '.');
+
+  const hasFeature = options.feature !== undefined && options.feature !== null
+    && options.feature !== true && String(options.feature).length > 0;
+  const hasLast = options.last !== undefined && options.last !== null && options.last !== true;
+
+  // --- Validação de input (antes de qualquer toque no filesystem — REQ-8) ---
+  if (!hasFeature && !hasLast) {
+    return inputError(log,
+      tr(t, 'cli.harnessRetro.need_target', null, 'harness:retro requer --feature=<slug> ou --last=<N>'),
+      'missing_target');
+  }
+
+  let slug = null;
+  if (hasFeature) {
+    slug = String(options.feature).trim();
+    if (!SLUG_RE.test(slug)) {
+      return inputError(log,
+        tr(t, 'cli.harnessRetro.invalid_slug', { slug }, `Slug inválido: ${slug} (deve casar ^[a-z0-9][a-z0-9-]*$)`),
+        'invalid_slug');
+    }
+  }
+
+  let lastN = null;
+  if (hasLast) {
+    lastN = Number(options.last);
+    if (!Number.isInteger(lastN) || lastN < 1) {
+      return inputError(log,
+        tr(t, 'cli.harnessRetro.invalid_last', { value: String(options.last) }, `Valor inválido para --last: ${options.last} (use inteiro ≥ 1)`),
+        'invalid_last');
+    }
+  }
+
+  // --- Resolve modo, janela e arquivo de saída -----------------------------
+  let mode;
+  let slugs;
+  let outRel;
+  const warnings = [];
+
+  if (hasFeature && !hasLast) {
+    if (!resolveFeatureExists(targetDir, slug)) {
+      return inputError(log,
+        tr(t, 'cli.harnessRetro.feature_not_found', { slug },
+          `Feature não encontrada: ${slug} (procurado em .aioson/context/, .aioson/plans/${slug}/, .aioson/context/features/${slug}/, .aioson/context/done/${slug}/)`),
+        'feature_not_found');
+    }
+    mode = 'feature';
+    slugs = [slug];
+    outRel = path.join('.aioson', 'context', 'retro', `${slug}.md`);
+  } else {
+    // Qualquer uso de --last produz window-last-{N}.md (D6, modo combinado incluído).
+    mode = 'window';
+    if (hasFeature && !resolveFeatureExists(targetDir, slug)) {
+      return inputError(log,
+        tr(t, 'cli.harnessRetro.feature_not_found', { slug },
+          `Feature não encontrada: ${slug}`),
+        'feature_not_found');
+    }
+    const closed = enumerateClosedFeatures(targetDir);
+    const pool = hasFeature ? [slug, ...closed.filter((s) => s !== slug)] : closed;
+    if (pool.length === 0) {
+      return inputError(log,
+        tr(t, 'cli.harnessRetro.no_closed_features', null, 'Nenhuma feature fechada em .aioson/context/done/ para minerar'),
+        'no_closed_features');
+    }
+    const { ordered, undated } = rankByPassDate(targetDir, pool, { anchor: hasFeature ? slug : null });
+    if (undated.length > 0) {
+      warnings.push(tr(t, 'cli.harnessRetro.undatable_excluded', { count: undated.length, slugs: undated.join(', ') },
+        `${undated.length} feature(s) sem data de PASS determinável excluída(s) da janela: ${undated.join(', ')}`));
+    }
+    if (lastN > ordered.length) {
+      warnings.push(tr(t, 'cli.harnessRetro.window_truncated', { n: lastN, available: ordered.length },
+        `--last=${lastN} excede features disponíveis (${ordered.length}); minerando todas`));
+    }
+    slugs = ordered.slice(0, lastN);
+    outRel = path.join('.aioson', 'context', 'retro', `window-last-${lastN}.md`);
+  }
+
+  // --- Mineração + agregação + render --------------------------------------
+  const sources = collectSources(targetDir, slugs);
+  const allWarnings = warnings.concat(sources.warnings);
+  const { candidates, observations } = aggregate(sources);
+
+  const outRelPosix = outRel.replaceAll('\\', '/');
+  const generatedAt = new Date().toISOString();
+  const markdown = renderDossier({
+    mode,
+    slug: mode === 'feature' ? slug : undefined,
+    windowN: mode === 'window' ? lastN : undefined,
+    featuresMined: sources.features_mined,
+    counts: sources.counts,
+    candidates,
+    observations,
+    minedPaths: sources.minedPaths,
+    warnings: allWarnings,
+    dossierRelPath: outRelPosix,
+    generatedAt
+  });
+
+  // --- Escrita (única do comando) ------------------------------------------
+  const outAbs = path.join(targetDir, outRel);
+  try {
+    fs.mkdirSync(path.dirname(outAbs), { recursive: true }); // edge 7
+    fs.writeFileSync(outAbs, markdown, 'utf8'); // edge 8 (idempotente, sobrescreve)
+  } catch (err) {
+    log.error(tr(t, 'cli.harnessRetro.io_error', { error: err.message }, `Erro de I/O ao escrever o dossiê: ${err.message}`));
+    process.exitCode = EXIT_IO;
+    return { ok: false, exitCode: EXIT_IO, error: 'io_error', message: err.message };
+  }
+
+  const report = {
+    ok: true,
+    exitCode: EXIT_OK,
+    mode,
+    feature: mode === 'feature' ? slug : null,
+    window: mode === 'window' ? `last-${lastN}` : null,
+    features_mined: sources.features_mined,
+    output: outRelPosix,
+    candidates: candidates.length,
+    observations: observations.length,
+    sources: sources.counts,
+    warnings: allWarnings
+  };
+
+  if (candidates.length === 0 && observations.length === 0) {
+    log.log(tr(t, 'cli.harnessRetro.empty', { path: outRelPosix },
+      `Dossiê gerado sem propostas: ${outRelPosix} (fontes sem trilha minerável)`));
+  } else {
+    log.log(tr(t, 'cli.harnessRetro.written',
+      { path: outRelPosix, candidates: candidates.length, observations: observations.length },
+      `Dossiê retrospectivo gerado: ${outRelPosix} (${candidates.length} candidatos, ${observations.length} observações)`));
+  }
+  for (const w of allWarnings) log.log(`  ⚠ ${w}`);
+
+  return report;
+}
+
+module.exports = { runHarnessRetro };

package/src/commands/harness-status.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * aioson harness:status . --slug=X [--json] — visibilidade do estado do loop
+ * (loop-guardrails REQ-18).
+ *
+ * Agrega: circuito, iteração N/M, budget, checks da última tentativa,
+ * última falha, gates pendentes e a próxima ação. Escopo distinto de
+ * `spec:status` (planos+learnings) — referenciado no rodapé.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { resolveContract, validateContract } = require('../harness/contract-schema');
+const { pendingGates } = require('../harness/human-gate');
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Última tentativa = maior diretório numérico em attempts/. */
+function latestAttempt(planDir) {
+  const dir = path.join(planDir, 'attempts');
+  if (!fs.existsSync(dir)) return null;
+  const numbers = fs.readdirSync(dir)
+    .map((name) => Number(name))
+    .filter((n) => Number.isInteger(n) && n > 0);
+  return numbers.length ? Math.max(...numbers) : null;
+}
+
+/** Conta checks pass/fail da tentativa pelos logs `# exit_code:`. */
+function readChecks(planDir, attempt) {
+  const checksDir = path.join(planDir, 'attempts', String(attempt), 'checks');
+  if (!fs.existsSync(checksDir)) return { total: 0, passed: 0, failed: 0, failed_ids: [] };
+  const summary = { total: 0, passed: 0, failed: 0, failed_ids: [] };
+  for (const file of fs.readdirSync(checksDir)) {
+    if (!file.endsWith('.log')) continue;
+    summary.total += 1;
+    try {
+      const content = fs.readFileSync(path.join(checksDir, file), 'utf8');
+      const match = content.match(/^# exit_code: (.+)$/m);
+      if (match && match[1].trim() === '0') {
+        summary.passed += 1;
+      } else {
+        summary.failed += 1;
+        summary.failed_ids.push(file.replace(/\.log$/, ''));
+      }
+    } catch {
+      summary.failed += 1;
+    }
+  }
+  return summary;
+}
+
+function nextAction(progress, pending, slug) {
+  if (pending.length > 0) {
+    return `aioson harness:approve . --slug=${slug} --gate=${pending[0].id} (ou harness:reject --reason="...")`;
+  }
+  const status = progress?.status || 'unknown';
+  if (status === 'circuit_open' || progress?.circuit_state === 'OPEN') {
+    return 'circuito aberto — revisar last_error e corrigir antes de novo run';
+  }
+  if (status === 'waiting_validation') {
+    return `aioson harness:validate . --slug=${slug}`;
+  }
+  if (progress?.ready_for_done_gate) {
+    return `pronto para o done gate — aioson feature:close . --feature=${slug}`;
+  }
+  return `re-executar self:loop para continuar (iteração persiste em progress.json)`;
+}
+
+async function runHarnessStatus({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const slug = String(options.slug || '').trim();
+
+  if (!slug) {
+    logger.error('Error: --slug is required');
+    return { ok: false, error: 'missing_slug' };
+  }
+
+  const planDir = path.join(targetDir, '.aioson', 'plans', slug);
+  const contract = readJson(path.join(planDir, 'harness-contract.json'));
+  if (!contract) {
+    logger.error(`Contract not found for slug: ${slug}`);
+    return { ok: false, error: 'contract_not_found' };
+  }
+
+  const progress = readJson(path.join(planDir, 'progress.json'));
+  const schema = validateContract(contract);
+  const resolved = schema.ok ? resolveContract(contract) : null;
+  const pending = pendingGates(planDir);
+  const attempt = latestAttempt(planDir);
+  const checks = attempt ? readChecks(planDir, attempt) : { total: 0, passed: 0, failed: 0, failed_ids: [] };
+
+  const maxSteps = resolved ? resolved.governor.max_steps : (contract.governor && contract.governor.max_steps) || null;
+  const ceiling = resolved ? (resolved.governor.cost_ceiling_tokens ?? null) : null;
+  const budget = progress?.budget || null;
+
+  const report = {
+    ok: true,
+    slug,
+    contract_mode: contract.contract_mode || 'BALANCED',
+    contract_schema_ok: schema.ok,
+    circuit_state: progress?.circuit_state || 'CLOSED',
+    status: progress?.status || 'unknown',
+    iterations: progress?.iterations ?? 0,
+    max_steps: maxSteps,
+    budget: budget ? {
+      tokens_estimated: budget.tokens_estimated || 0,
+      cost_ceiling_tokens: ceiling,
+      run_id: budget.run_id || null,
+      run_started_at: budget.run_started_at || null
+    } : null,
+    last_attempt: attempt,
+    checks,
+    last_error: progress?.last_error || null,
+    pending_gates: pending.map((g) => ({ id: g.id, theme: g.theme, attempt: g.attempt, requested_at: g.requested_at })),
+    next_action: nextAction(progress, pending, slug)
+  };
+
+  if (options.json) {
+    logger.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  logger.log(`Harness status — ${slug}`);
+  logger.log(`  Mode: ${report.contract_mode}${schema.ok ? '' : '  (⚠ contract schema invalid)'}`);
+  logger.log(`  Circuit: ${report.circuit_state} | status: ${report.status}`);
+  logger.log(`  Iteration: ${report.iterations}${maxSteps ? `/${maxSteps}` : ''}`);
+  if (budget) {
+    logger.log(`  Budget: ${report.budget.tokens_estimated} tokens estimados${ceiling ? ` / ${ceiling} (${Math.round((report.budget.tokens_estimated / ceiling) * 100)}%)` : ' (sem teto)'}`);
+  }
+  if (attempt) {
+    logger.log(`  Last attempt: ${attempt} — checks ${checks.passed}/${checks.total} pass${checks.failed ? ` (failed: ${checks.failed_ids.join(', ')})` : ''}`);
+  }
+  if (report.last_error) logger.log(`  Last error: ${report.last_error}`);
+  if (pending.length > 0) {
+    logger.log(`  ⛔ Pending gates (${pending.length}):`);
+    for (const gate of pending) {
+      logger.log(`    - ${gate.id} [${gate.theme}] attempt ${gate.attempt}`);
+    }
+  }
+  logger.log(`  Next: ${report.next_action}`);
+  logger.log('');
+  logger.log('  Planos e learnings: aioson spec:status');
+
+  return report;
+}
+
+module.exports = {
+  runHarnessStatus
+};

package/src/commands/harness.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { createCircuitBreaker } = require('../harness/circuit-breaker');
+const { validateContract } = require('../harness/contract-schema');
 
 /**
  * aioson harness:init — Inicializa o contrato e progresso da feature.
@@ -36,8 +37,17 @@ async function runHarnessInit({ args, options = {}, logger, t }) {
     governor: {
       max_steps: 50,
       error_streak_limit: 5,
-      cost_ceiling_tokens: null
+      cost_ceiling_tokens: null,
+      max_runtime_minutes: null,
+      max_changed_files: null,
+      max_diff_lines: null
     },
+    // Scope guard (loop-guardrails): allowed_files ausente = sem allowlist;
+    // forbidden_files é SEMPRE mesclado com os defaults embutidos (.env*, *.pem,
+    // *.key, secrets/**, .git/**, node_modules/**, lockfiles) — não-removíveis.
+    forbidden_files: [],
+    // human_gate ausente = nenhum gate (retrocompat). Exemplo:
+    // "human_gate": { "required_for": ["payment_logic_change", "publish"] }
     criteria: [
       {
         id: "C1",
@@ -48,6 +58,13 @@ async function runHarnessInit({ args, options = {}, logger, t }) {
     ]
   };
 
+  const schemaResult = validateContract(contract);
+  if (!schemaResult.ok) {
+    const first = schemaResult.errors[0];
+    logger.error(`Contract schema invalid: ${first.field} — ${first.reason}`);
+    return { ok: false, error: 'contract_schema_invalid', errors: schemaResult.errors };
+  }
+
   const cb = createCircuitBreaker(contractPath, progressPath);
   fs.writeFileSync(contractPath, JSON.stringify(contract, null, 2), 'utf8');
   await cb.load();