@jaimevalasek/aioson 1.22.0 → 1.23.1

package/src/commands/agent-epilogue.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const path = require('node:path');
+const { runPulseUpdate } = require('./pulse-update');
+const { runDossierAddFinding } = require('./dossier');
+const { runGateApprove } = require('./gate-approve');
+const { runAgentDone } = require('./runtime');
+
+function resolveTargetDir(args) {
+  return path.resolve(process.cwd(), args[0] || '.');
+}
+
+function normalizeAgent(value) {
+  return String(value || '').trim().replace(/^@/, '');
+}
+
+function normalizeList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.map(String).map((item) => item.trim()).filter(Boolean);
+  return String(value).split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function makeSilentLogger() {
+  return { log() {}, error() {}, warn() {} };
+}
+
+function pushStep(steps, name, result) {
+  steps.push({
+    name,
+    ok: Boolean(result && result.ok),
+    skipped: Boolean(result && result.skipped),
+    reason: result && (result.reason || result.error || null)
+  });
+}
+
+function formatAutoAdvance(autoAdvance) {
+  if (!autoAdvance) return null;
+  if (autoAdvance.advanced) {
+    const nextStage = autoAdvance.result && (autoAdvance.result.next || autoAdvance.result.nextStage);
+    return `workflow auto-advanced${nextStage ? ` -> ${nextStage}` : ''}`;
+  }
+  return `workflow skip: ${autoAdvance.skipped || 'not_advanced'}`;
+}
+
+async function runAgentEpilogue({ args, options = {}, logger, t }) {
+  const targetDir = resolveTargetDir(args);
+  const agent = normalizeAgent(options.agent);
+  const summary = String(options.summary || options.message || '').trim();
+  const feature = options.feature ? String(options.feature).trim() : null;
+  const action = options.action ? String(options.action).trim() : summary;
+  const next = options.next ? String(options.next).trim() : null;
+  const gate = options.gate ? String(options.gate).trim() : null;
+  const approveGate = options['approve-gate'] || options.approveGate
+    ? String(options['approve-gate'] || options.approveGate).trim().toUpperCase()
+    : null;
+  const verdict = options.verdict ? String(options.verdict).trim().toUpperCase() : null;
+  const artifacts = normalizeList(options.artifacts);
+  const strict = Boolean(options.strict);
+  const steps = [];
+  const errors = [];
+  const silentLogger = makeSilentLogger();
+
+  if (!agent) {
+    const failure = { ok: false, reason: 'missing_agent' };
+    if (options.json) return failure;
+    logger.error('--agent=<agent> is required.');
+    return failure;
+  }
+
+  if (!summary) {
+    const failure = { ok: false, reason: 'missing_summary' };
+    if (options.json) return failure;
+    logger.error('--summary="<summary>" is required.');
+    return failure;
+  }
+
+  if (approveGate) {
+    const gateResult = await runGateApprove({
+      args: [targetDir],
+      options: {
+        feature,
+        gate: approveGate,
+        agent,
+        json: true
+      },
+      logger: silentLogger
+    });
+    pushStep(steps, 'gate:approve', gateResult);
+    if (!gateResult.ok) {
+      errors.push({ step: 'gate:approve', reason: gateResult.reason || 'gate_failed', result: gateResult });
+      if (strict) {
+        const failure = { ok: false, reason: 'gate_approve_failed', steps, errors };
+        if (options.json) return failure;
+        logger.error(`agent:epilogue blocked: gate ${approveGate} approval failed.`);
+        return failure;
+      }
+    }
+  }
+
+  if (!options['no-pulse'] && !options.noPulse) {
+    const pulseResult = await runPulseUpdate({
+      args: [targetDir],
+      options: {
+        agent,
+        ...(feature ? { feature } : {}),
+        ...(gate || approveGate ? { gate: gate || `Gate ${approveGate}: approved` } : {}),
+        ...(action ? { action } : {}),
+        ...(next ? { next } : {}),
+        ...(verdict ? { verdict } : {}),
+        json: true
+      },
+      logger: silentLogger
+    });
+    pushStep(steps, 'pulse:update', pulseResult);
+    if (!pulseResult.ok) {
+      errors.push({ step: 'pulse:update', reason: pulseResult.reason || 'pulse_failed', result: pulseResult });
+    }
+  } else {
+    pushStep(steps, 'pulse:update', { ok: true, skipped: true, reason: 'disabled' });
+  }
+
+  if (feature && !options['no-dossier'] && !options.noDossier) {
+    const dossierResult = await runDossierAddFinding({
+      args: [targetDir],
+      options: {
+        slug: feature,
+        agent,
+        section: options.section ? String(options.section) : 'Agent Trail',
+        content: options.content ? String(options.content) : summary,
+        json: true
+      },
+      logger: silentLogger
+    });
+    pushStep(steps, 'dossier:add-finding', dossierResult);
+    if (!dossierResult.ok) {
+      errors.push({ step: 'dossier:add-finding', reason: dossierResult.reason || 'dossier_failed', result: dossierResult });
+    }
+  } else {
+    pushStep(steps, 'dossier:add-finding', { ok: true, skipped: true, reason: feature ? 'disabled' : 'missing_feature' });
+  }
+
+  const doneResult = await runAgentDone({
+    args: [targetDir],
+    options: {
+      agent,
+      summary,
+      ...(feature ? { feature } : {}),
+      ...(verdict ? { verdict } : {}),
+      ...(artifacts.length > 0 ? { artifacts: artifacts.join(',') } : {}),
+      json: true
+    },
+    logger: silentLogger,
+    t
+  });
+  pushStep(steps, 'agent:done', doneResult);
+  if (!doneResult.ok) {
+    errors.push({ step: 'agent:done', reason: doneResult.reason || doneResult.error || 'agent_done_failed', result: doneResult });
+  }
+
+  const ok = doneResult.ok && (strict ? errors.length === 0 : !errors.some((error) => error.step === 'agent:done'));
+  const result = {
+    ok,
+    targetDir,
+    agent: `@${agent}`,
+    feature,
+    summary,
+    steps,
+    errors,
+    agent_done: doneResult
+  };
+
+  if (options.json) return result;
+
+  logger.log(`agent:epilogue — @${agent} (${ok ? 'ok' : 'issues'})`);
+  for (const step of steps) {
+    const marker = step.skipped ? 'skip' : step.ok ? 'ok' : 'fail';
+    logger.log(`  ${marker} ${step.name}${step.reason ? ` (${step.reason})` : ''}`);
+  }
+  const autoAdvanceMessage = formatAutoAdvance(doneResult.auto_advance);
+  if (autoAdvanceMessage) logger.log(`  ${autoAdvanceMessage}`);
+  return result;
+}
+
+module.exports = {
+  runAgentEpilogue
+};

package/src/commands/context-select.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const path = require('node:path');
+const { selectContext } = require('../context-selector');
+
+async function runContextSelect({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const result = await selectContext(targetDir, {
+    agent: options.agent || options.a || 'dev',
+    mode: options.mode || 'planning',
+    task: options.task || options.goal || '',
+    paths: options.paths || options.path || '',
+    feature: options.feature || options.slug || ''
+  });
+
+  if (options.json) return result;
+
+  logger.log(`Context selection for @${result.agent} (${result.mode})`);
+  if (result.task) logger.log(`Task: ${result.task}`);
+  if (result.paths.length > 0) logger.log(`Paths: ${result.paths.join(', ')}`);
+  if (result.selected.length === 0) {
+    logger.log('No context files selected.');
+    return result;
+  }
+
+  for (const item of result.selected) {
+    logger.log(`- ${item.path} [${item.surface}; ${item.load_tier}] ${item.reason}`);
+  }
+
+  return result;
+}
+
+module.exports = { runContextSelect };

package/src/commands/harness-preview.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * `aioson harness:preview <file> [--max-bytes=8192] [--json]` (requirements §5.2).
+ *
+ * Wrapper fino e read-only de `previewArtifact` sobre um arquivo já persistido
+ * (ex.: `npm test > test.log`). Devolve preview + ponteiro para o agente de teste
+ * consumir sem despejar o log integral no contexto. Tema 2 (should-have).
+ *
+ * Exit codes: 0 sucesso; 12 input inválido (arquivo ausente/ilegível).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { previewArtifact, DEFAULT_MAX_BYTES } = require('../harness/preview-artifact');
+
+const EXIT_OK = 0;
+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;
+}
+
+async function runHarnessPreview({ args, options = {}, logger, t } = {}) {
+  const log = logger || { log() {}, error() {} };
+  const file = args && args[0];
+
+  if (!file || typeof file !== 'string') {
+    log.error(tr(t, 'cli.harnessPreview.file_required', null, 'harness:preview requires a <file> path argument.'));
+    process.exitCode = EXIT_INPUT;
+    return { ok: false, exitCode: EXIT_INPUT, error: 'file_required' };
+  }
+
+  // SF-02 (decisão de design, não bug): leitor read-only operador-local. Lê
+  // qualquer path legível por design — o caso de uso é previewar logs de teste
+  // (ex.: `npm test > test.log`) que podem viver fora do cwd. Sem cruzamento de
+  // fronteira de confiança (o operador já tem acesso ao FS); por isso não há
+  // contenção de workspace aqui. Mantém-se intencionalmente irrestrito.
+  const abs = path.resolve(process.cwd(), file);
+  let content;
+  try {
+    content = fs.readFileSync(abs, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      log.error(tr(t, 'cli.harnessPreview.not_found', { path: file }, `File not found: ${file}`));
+      process.exitCode = EXIT_INPUT;
+      return { ok: false, exitCode: EXIT_INPUT, error: 'not_found' };
+    }
+    log.error(tr(t, 'cli.harnessPreview.read_error', { path: file, error: err.message }, `Could not read file: ${file} (${err.message})`));
+    process.exitCode = EXIT_INPUT;
+    return { ok: false, exitCode: EXIT_INPUT, error: 'read_error' };
+  }
+
+  let maxBytes = Number(options['max-bytes'] ?? options.maxBytes ?? DEFAULT_MAX_BYTES);
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) maxBytes = DEFAULT_MAX_BYTES;
+
+  // Modo leitura: o arquivo já está persistido — não reescrever (persist:false).
+  const result = previewArtifact(content, { maxBytes, artifactPath: abs, persist: false });
+  log.log(result.preview);
+
+  return {
+    ok: true,
+    exitCode: EXIT_OK,
+    file: file.replaceAll('\\', '/'),
+    totalBytes: result.totalBytes,
+    truncated: result.truncated,
+    preview: result.preview
+  };
+}
+
+module.exports = { runHarnessPreview };

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/preflight-context.js

@@ -4,10 +4,11 @@
  * aioson preflight:context — Estimate context budget before a session
  *
  * Usage:
- *   aioson preflight:context . --agent=dev
- *   aioson preflight:context . --agent=orchestrator --squad=content-team
- *   aioson preflight:context . --agent=dev --verbose
- *   aioson preflight:context . --agent=dev --json
+ *   aioson preflight:context . --agent=dev
+ *   aioson preflight:context . --agent=orchestrator --squad=content-team
+ *   aioson preflight:context . --agent=dev --mode=executing --task="create command" --paths=src/commands/foo.js
+ *   aioson preflight:context . --agent=dev --verbose
+ *   aioson preflight:context . --agent=dev --json
  */
 
 const path = require('node:path');
@@ -15,11 +16,14 @@ const { estimateContext, formatReport } = require('../squad/preflight-context');
 
 async function runPreflightContext({ args, options = {}, logger }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
-  const agent = String(options.agent || options.a || 'dev').trim();
-  const squad = options.squad ? String(options.squad).trim() : undefined;
-  const verbose = Boolean(options.verbose || options.v);
-
-  const result = await estimateContext(targetDir, { agent, squad, verbose });
+  const agent = String(options.agent || options.a || 'dev').trim();
+  const squad = options.squad ? String(options.squad).trim() : undefined;
+  const verbose = Boolean(options.verbose || options.v);
+  const mode = String(options.mode || 'planning').trim();
+  const task = String(options.task || options.goal || '').trim();
+  const paths = String(options.paths || options.path || '').trim();
+
+  const result = await estimateContext(targetDir, { agent, squad, verbose, mode, task, paths });
 
   if (options.json) return result;