@aksp/opencrew 1.12.0 → 1.14.0

package/templates/_opencrew/core/scripts/execucao/registro.mjs

@@ -0,0 +1,115 @@
+// O registro de uma execução: `crews/<crew>/output/<run>/execucao.json`. Só os scripts o gravam
+// (`caminho.mjs` e `execucao.mjs`); a gravação é inteira ou nenhuma, e um registro ilegível vale
+// como ausente.
+// Spec: fase-u5c-execucao-registrada.md, §4 e regras 1 a 5 e 8 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { gravarTexto } from '../estado/arquivo.mjs';
+
+export const ARQUIVO = 'execucao.json';
+/** O `--resultado` do `fechar` → o `status` do registro. */
+export const STATUS = { aprovado: 'aprovada', rejeitado: 'rejeitada', abortado: 'abortada', publicado: 'publicada' };
+
+const RECUSA = { EACCES: 'a pasta está protegida contra gravação', EPERM: 'a pasta está protegida ou o arquivo está em uso', EBUSY: 'o arquivo está em uso por outro programa', EISDIR: 'há uma pasta no lugar do arquivo', ENOSPC: 'o disco está cheio', EROFS: 'o disco é só de leitura' };
+/** O motivo de uma falha de gravação, em PT-BR. */
+export const motivoDe = (erro) => RECUSA[erro?.code] ?? `erro ${erro?.code ?? String(erro?.message ?? erro).replace(/\s+/g, ' ').trim()}`;
+export const AVISO = (motivo) => `Não consegui gravar o registro desta execução: ${motivo}`;
+
+/** Uma linha só, cortada por caractere inteiro (um emoji não fica pela metade). */
+const umaLinha = (texto, maximo) => Array.from(String(texto ?? '').replace(/\s+/g, ' ').trim()).slice(0, maximo).join('').trim();
+/** Tema e descrição da saída: uma linha, sem `|` (é coluna do `runs.md`), até 160 caracteres. */
+export const limparTema = (texto) => umaLinha(String(texto ?? '').replace(/\|/g, '/'), 160);
+/** A correção pedida ou o motivo da rejeição: uma linha, até 300 caracteres. */
+export const limparNota = (texto) => umaLinha(texto, 300);
+
+const lista = (valor) => (Array.isArray(valor) ? valor.filter((i) => i && typeof i === 'object') : []);
+const inteiro = (valor) => Number.isInteger(valor) && valor > 0;
+
+/** O que veio do disco é dado: cada campo que vai para a tela vira uma linha, e passo sem número sai. */
+function conferido(lido) {
+  if (!lido || typeof lido !== 'object' || Array.isArray(lido)) return null;
+  const passos = lista(lido.passos).filter((p) => inteiro(p.n)).map((p) => ({ ...p, arquivo: umaLinha(p.arquivo, 500), em: umaLinha(p.em, 40) }));
+  const marcos = lista(lido.marcos).filter((m) => inteiro(m.passo)).map((m) => ({ ...m, evento: umaLinha(m.evento, 20), resultado: umaLinha(m.resultado, 20), nota: limparNota(m.nota), em: umaLinha(m.em, 40) }));
+  return { ...lido, tema: limparTema(lido.tema), saida: limparTema(lido.saida), status: umaLinha(lido.status, 20), passos, marcos };
+}
+
+/**
+ * O registro gravado, para quem vai regravá-lo: `null` quando falta ou está ilegível (cortado, sem
+ * ser um objeto); qualquer outra falha de leitura (arquivo em uso, sem permissão) sobe — um
+ * registro que existe e não pôde ser lido não é trocado por um vazio.
+ */
+async function lerParaGravar(pasta) {
+  try {
+    const texto = await fs.readFile(path.join(pasta, ARQUIVO), 'utf8');
+    return conferido(JSON.parse(texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto));
+  } catch (erro) {
+    if (erro?.code === 'ENOENT' || erro instanceof SyntaxError) return null;
+    throw erro;
+  }
+}
+
+/**
+ * O registro gravado, para quem só lê: `null` quando falta, está ilegível ou não pôde ser lido.
+ * @param {string} pasta a pasta da execução
+ */
+export const lerRegistro = (pasta) => lerParaGravar(pasta).catch(() => null);
+
+/** Um registro novo, aberto. @param {{ crew, run, tema?, passos?, em }} base `em`: a hora, em ISO */
+export function novoRegistro({ crew, run, tema = '', passos = null, em }) {
+  return { versao: 1, crew, run, tema, status: 'aberta', iniciadaEm: em, passosPrevistos: passos, passos: [], marcos: [], saida: '' };
+}
+
+/** Os campos na ordem da spec (`fechadaEm` só existe depois do fecho). */
+function ordenado(r) {
+  const { versao, crew, run, tema, status, iniciadaEm, fechadaEm, passosPrevistos, passos, marcos, saida, ...resto } = r;
+  const fecho = fechadaEm === undefined ? {} : { fechadaEm };
+  return { versao, crew, run, tema, status, iniciadaEm, ...fecho, passosPrevistos, passos, marcos, saida, ...resto };
+}
+
+/** O passo conferido: troca a entrada do mesmo número (fica a última saída). */
+export function comPasso(registro, { n, arquivo, em }) {
+  const outros = registro.passos.filter((p) => p.n !== n);
+  return { ...registro, passos: [...outros, { n, arquivo, em }].sort((a, b) => a.n - b.n) };
+}
+
+/** Os marcos só acumulam, na ordem em que chegam. */
+export const comMarco = (registro, marco) => ({ ...registro, marcos: [...registro.marcos, marco] });
+
+/** O tema, quando o comando trouxe um; senão, o que já estava. */
+export const comTema = (registro, tema) => (limparTema(tema) ? { ...registro, tema: limparTema(tema) } : registro);
+
+export function fechado(registro, { resultado, saida, em }) {
+  return { ...registro, status: STATUS[resultado], fechadaEm: em, saida: limparTema(saida) || String(registro.saida ?? '') };
+}
+
+/** Regra 8: checkpoints aprovados sem correção ÷ checkpoints respondidos (os pulados não contam). */
+export function score(registro) {
+  const respostas = (registro?.marcos ?? []).filter((m) => m.evento === 'checkpoint').map((m) => m.resultado);
+  const aprovados = respostas.filter((r) => r === 'aprovado').length;
+  const total = aprovados + respostas.filter((r) => r === 'corrigido').length;
+  return total ? `${aprovados}/${total}` : '—';
+}
+
+/** Grava o registro. @returns {Promise<string|null>} o aviso para o usuário, ou `null` */
+export async function gravarRegistro(pasta, registro) {
+  try {
+    await gravarTexto(path.join(pasta, ARQUIVO), `${JSON.stringify(ordenado(registro), null, 2)}\n`);
+    return null;
+  } catch (erro) {
+    return AVISO(motivoDe(erro));
+  }
+}
+
+/**
+ * Lê o registro (ou começa um, com `base`), aplica a mudança e grava.
+ * @param {string} pasta a pasta da execução · @param {object} base ver `novoRegistro`
+ * @param {(registro: object) => object} mudar
+ * @returns {Promise<string|null>} o aviso de que não gravou, ou `null`
+ */
+export async function anotar(pasta, base, mudar) {
+  try {
+    return await gravarRegistro(pasta, mudar((await lerParaGravar(pasta)) ?? novoRegistro(base)));
+  } catch (erro) {
+    return AVISO(motivoDe(erro));
+  }
+}

package/templates/_opencrew/core/scripts/execucao/retomar.mjs

@@ -0,0 +1,123 @@
+// O que os registros de uma crew dizem: qual execução ficou aberta e de que passo ela continua
+// (`retomar`), e as correções das últimas execuções fechadas (lista do `fechar`). Só leitura.
+// Spec: fase-u5c-execucao-registrada.md, regras 9 e 11 (repositório do OpenCrew).
+import path from 'node:path';
+import { pastasDe, temConteudo } from '../caminho/disco.mjs';
+import { lerCrew } from '../conserto/crew.mjs';
+import { lerRegistro } from './registro.mjs';
+
+const MSG = {
+  abertas: 'Execuções abertas (a mais recente primeiro):',
+  naoAberta: (run) => `A execução ${run} não está aberta.`,
+  sumiu: ' (o arquivo não está mais lá)',
+  tudoFeito: 'Todos os passos já foram feitos: falta só encerrar a execução.',
+  refeitos: 'Já gravados, mas serão feitos de novo:',
+  voltaIncerta: (revisao, n) => `Não consegui ler na crew para qual passo a revisão do passo ${revisao} volta: recomeço do passo ${n}. Confira antes de continuar.`,
+  correcoes: 'Correções das últimas execuções:',
+};
+
+/** Os registros legíveis das execuções da crew: `{ run, ...registro }`. */
+async function registrosDe(raiz, crew) {
+  const saida = path.resolve(raiz, 'crews', crew, 'output');
+  const lidos = await Promise.all(pastasDe(saida).map(async (run) => ({ run, registro: await lerRegistro(path.join(saida, run)) })));
+  return lidos.filter((l) => l.registro).map((l) => ({ ...l.registro, run: l.run }));
+}
+
+const maisNova = (campo) => (a, b) => String(b[campo] ?? '').localeCompare(String(a[campo] ?? '')) || b.run.localeCompare(a.run);
+
+/**
+ * Regra 9: as notas dos marcos `corrigido` e `rejeitado` das 10 execuções fechadas mais recentes.
+ * @returns {Promise<string[]>} o título e uma linha por correção, a mais recente primeiro; `[]` sem nenhuma
+ */
+export async function correcoesRecentes(raiz, crew) {
+  const fechadas = (await registrosDe(raiz, crew)).filter((r) => r.status !== 'aberta').sort(maisNova('fechadaEm')).slice(0, 10);
+  const corrigiu = (m) => (m.resultado === 'corrigido' || m.resultado === 'rejeitado') && m.nota;
+  const linhas = fechadas.flatMap((r) => r.marcos.filter(corrigiu).map((m) => `- ${r.run} · passo ${m.passo} · ${m.nota}`));
+  return linhas.length ? [MSG.correcoes, ...linhas] : [];
+}
+
+/** Os passos da crew (o número e, na revisão, o passo para onde a rejeição volta); `[]` se a crew não pôde ser lida. */
+function passosDaCrew(raiz, crew) {
+  try {
+    return lerCrew(raiz, path.join('crews', crew)).passos;
+  } catch {
+    return [];
+  }
+}
+
+/** O que foi feito por último: o passo conferido ou o marco mais recente (no empate, o do passo maior; depois, o marco). */
+function ultimoFeito(registro) {
+  const feitos = [
+    ...registro.passos.map((p) => ({ em: String(p.em ?? ''), passo: p.n, peso: 0 })),
+    ...registro.marcos.map((m) => ({ em: String(m.em ?? ''), passo: m.passo, peso: 1, marco: m })),
+  ];
+  return feitos.sort((a, b) => a.em.localeCompare(b.em) || a.passo - b.passo || a.peso - b.peso).at(-1) ?? null;
+}
+
+/**
+ * Para onde volta a revisão rejeitada no passo `revisao`: o passo do `on_reject`; se a crew não
+ * diz (pipeline ilegível, alvo que não é número), o primeiro passo gravado antes da revisão —
+ * refazer a mais é mais seguro que mandar o revisor ler de novo o texto que ele rejeitou.
+ * @returns {{ n: number, incerto: boolean }}
+ */
+function voltaDe(registro, passos, revisao) {
+  const declarado = passos.find((p) => p.numero === revisao)?.volta ?? null;
+  if (declarado !== null) return { n: declarado, incerto: false };
+  const antes = registro.passos.map((p) => p.n).filter((n) => n < revisao);
+  return { n: antes.length ? Math.min(...antes) : revisao, incerto: true };
+}
+
+/**
+ * Regra 11 (decisão 5 da spec): continua do passo seguinte ao último feito; revisão rejeitada
+ * volta ao passo do `on_reject`; passo cujo arquivo sumiu é refeito.
+ * @returns {{ feito: number|null, n: number, fim: boolean, incerto: boolean }} `fim`: não há passo
+ *   depois do último feito · `incerto`: o passo de volta da revisão foi deduzido
+ */
+function proximoPasso(registro, passos, existe) {
+  const numeros = passos.map((p) => p.numero).sort((a, b) => a - b);
+  const ultimo = ultimoFeito(registro);
+  const seguinte = (k) => numeros.find((n) => n > k) ?? k + 1;
+  const rejeitou = ultimo?.marco?.evento === 'revisao' && ultimo.marco.resultado === 'rejeitado';
+  const volta = rejeitou ? voltaDe(registro, passos, ultimo.passo) : null;
+  const pelaOrdem = ultimo ? volta?.n ?? seguinte(ultimo.passo) : numeros[0] ?? 1;
+  const sumidos = registro.passos.filter((p) => p.n < pelaOrdem && !existe(p.arquivo)).map((p) => p.n);
+  const fim = numeros.length > 0 && pelaOrdem > numeros.at(-1);
+  return { feito: ultimo?.passo ?? null, n: Math.min(pelaOrdem, ...sumidos), fim, incerto: volta?.incerto ?? false };
+}
+
+const comNota = (m) => `- passo ${m.passo}: ${m.resultado}${m.nota ? ` — ${m.nota}` : ''}`;
+const grupo = (titulo, linhas) => (linhas.length ? [titulo, ...linhas] : []);
+
+/** As linhas que descrevem uma execução aberta e a linha `EXECUCAO:RETOMAR`. */
+function descrever(raiz, crew, registro) {
+  const existe = (arquivo) => temConteudo(path.resolve(raiz, String(arquivo)));
+  const { feito, n, fim, incerto } = proximoPasso(registro, passosDaCrew(raiz, crew), existe);
+  const linha = (p) => `- passo ${p.n}: ${p.arquivo}${existe(p.arquivo) ? '' : MSG.sumiu}`;
+  // Pronto é só o que fica antes do passo de onde a execução continua; o resto será feito de novo.
+  const prontos = registro.passos.filter((p) => p.n < n).map(linha);
+  const doEvento = (evento) => registro.marcos.filter((m) => m.evento === evento).map(comNota);
+  return [
+    `Execução: ${registro.run}`,
+    `Tema: ${registro.tema || '(sem tema)'}`,
+    ...(prontos.length ? ['Passos conferidos:', ...prontos] : ['Passos conferidos: nenhum']),
+    ...grupo(MSG.refeitos, registro.passos.filter((p) => p.n >= n).map(linha)),
+    ...grupo('Checkpoints respondidos:', doEvento('checkpoint')),
+    ...grupo('Revisões:', doEvento('revisao')),
+    ...(feito === null ? [] : [`Parou depois do passo ${feito}.`]),
+    ...(incerto ? [MSG.voltaIncerta(feito, n)] : []),
+    ...(fim && n > feito ? [MSG.tudoFeito] : []),
+    `EXECUCAO:RETOMAR ${registro.run} ${n}`,
+  ];
+}
+
+/**
+ * Regra 11: a execução aberta mais recente da crew (ou a de `run`) e o passo de onde ela continua.
+ * @returns {Promise<string[]>} as linhas da resposta; a última é `EXECUCAO:RETOMAR <run> <passo>` ou `EXECUCAO:NADA`
+ */
+export async function retomar(raiz, crew, run) {
+  const abertas = (await registrosDe(raiz, crew)).filter((r) => r.status === 'aberta').sort(maisNova('iniciadaEm'));
+  if (!abertas.length) return [...(run ? [MSG.naoAberta(run)] : []), 'EXECUCAO:NADA'];
+  const lista = abertas.length > 1 ? [MSG.abertas, ...abertas.map((r) => `- ${r.run} — ${r.tema || 'sem tema'}`)] : [];
+  const alvo = run ? abertas.find((r) => r.run === run) : abertas[0];
+  return alvo ? [...lista, ...descrever(raiz, crew, alvo)] : [...lista, MSG.naoAberta(run), 'EXECUCAO:NADA'];
+}

package/templates/_opencrew/core/scripts/execucao.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Registro da execução de uma crew: os marcos (resposta de checkpoint, veredito da revisão), o
+// fecho — que grava a linha do histórico (`runs.md`) — e de onde uma execução interrompida continua.
+// Quem grava o registro e o histórico é este script (e o `caminho.mjs`), nunca a IA.
+// Uso (na pasta do projeto): node _opencrew/core/scripts/execucao.mjs <crew> <ação> [opções]
+//   marcar  --run <id> --passo N --evento checkpoint|revisao --resultado <r> [--nota "<texto>"] [--tema "<texto>"]
+//           checkpoint: aprovado, corrigido ou pulado · revisao: aprovado ou rejeitado
+//   fechar  --run <id> --resultado aprovado|rejeitado|abortado|publicado [--saida "<descrição>"] [--tema "<texto>"]
+//   retomar [--run <id>]                      a execução aberta mais recente (ou a de --run)
+// <crew> é o nome da pasta em `crews/`.
+// Só grava `crews/<crew>/output/<id>/execucao.json` e, no `fechar`, uma linha de
+// `crews/<crew>/_memory/runs.md` (posta ou trocada); `retomar` só lê. Nunca apaga.
+// Última linha da saída (o runner lê esta linha): EXECUCAO:OK · EXECUCAO:FECHADA <resultado> <score>
+// · EXECUCAO:RETOMAR <id> <próximo passo> · EXECUCAO:NADA (nenhuma execução aberta).
+// Código de saída: 0 sempre que a linha EXECUCAO: sai — também quando o registro ou o histórico
+// não pôde ser gravado (o aviso vem antes da linha) · 1 = erro de uso; nada é gravado.
+// Spec: fase-u5c-execucao-registrada.md (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ehPrincipal, realDentroDe } from './comum.mjs';
+import { limpar } from './caminho/argumentos.mjs';
+import { acharCrew } from './caminho/crew.mjs';
+import { ehPasta } from './caminho/disco.mjs';
+import { gravarTexto } from './estado/arquivo.mjs';
+import { USO, erroDeArgumentos, lerArgs } from './execucao/argumentos.mjs';
+import { ROTULO, comLinha, dataDe, linhaDe } from './execucao/historico.mjs';
+import { anotar, comMarco, comTema, fechado, gravarRegistro, lerRegistro, limparNota, motivoDe, novoRegistro, score } from './execucao/registro.mjs';
+import { correcoesRecentes, retomar } from './execucao/retomar.mjs';
+
+const MSG = {
+  semExecucao: (run) => `Execução não encontrada: ${limpar(run)}`,
+  semRegistro: 'O registro desta execução não existia ou estava ilegível: a linha do histórico saiu só com o que este comando informou.',
+  semHistorico: (motivo) => `Não consegui gravar o histórico desta execução: ${motivo}`,
+  naoUtf8: 'o arquivo runs.md não está em UTF-8; salve-o em UTF-8 e feche a execução de novo',
+  falha: (motivo) => `Não consegui registrar a execução: ${limpar(motivo)}`,
+};
+
+/** Onde fica a crew e, quando o comando cita uma execução, a pasta dela; ou o erro de uso. */
+function localizar(raiz, args) {
+  const erro = erroDeArgumentos(args);
+  if (erro) return { erro };
+  const achada = acharCrew(raiz, args.crew);
+  if (achada.erro) return achada;
+  const saida = path.resolve(raiz, 'crews', achada.crew, 'output');
+  const pasta = path.join(saida, args.run ?? '');
+  // A pasta tem de existir e ficar mesmo dentro de `output/` (um atalho que leva para fora não vale).
+  const valida = ehPasta(pasta) && realDentroDe(saida, pasta);
+  return args.acao !== 'retomar' && !valida ? { erro: MSG.semExecucao(args.run) } : { crew: achada.crew, pasta };
+}
+
+async function marcar({ pasta, base }, args) {
+  const marco = { passo: Number(args.passo), evento: args.evento, resultado: args.resultado, nota: limparNota(args.nota), em: base.em };
+  const aviso = await anotar(pasta, base, (registro) => comMarco(comTema(registro, args.tema), marco));
+  return [aviso, 'EXECUCAO:OK'];
+}
+
+/** O texto do arquivo, com o BOM se houver; `undefined` quando os bytes não são UTF-8 (o arquivo não é regravado). */
+function emUtf8(bytes) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Regra 7: a linha da execução no `runs.md` da crew. @returns {Promise<string|null>} o aviso, ou `null` */
+async function gravarHistorico({ raiz, crew, base: { run } }, linha) {
+  const arquivo = path.resolve(raiz, 'crews', crew, '_memory', 'runs.md');
+  try {
+    const bytes = await fs.readFile(arquivo).catch((erro) => (erro.code === 'ENOENT' ? null : Promise.reject(erro)));
+    const atual = bytes === null ? null : emUtf8(bytes);
+    if (atual === undefined) return MSG.semHistorico(MSG.naoUtf8);
+    await fs.mkdir(path.dirname(arquivo), { recursive: true });
+    await gravarTexto(arquivo, comLinha(atual, { crew, run, linha }));
+    return null;
+  } catch (erro) {
+    return MSG.semHistorico(motivoDe(erro));
+  }
+}
+
+async function fechar(ctx, args) {
+  const { raiz, crew, pasta, base, agora } = ctx;
+  const lido = await lerRegistro(pasta);
+  const registro = fechado(comTema(lido ?? novoRegistro(base), args.tema), { resultado: args.resultado, saida: args.saida, em: base.em });
+  const avisos = [lido ? null : MSG.semRegistro, await gravarRegistro(pasta, registro)];
+  const pontos = score(registro);
+  const linha = linhaDe({ data: dataDe(base.run, agora), run: base.run, tema: registro.tema, saida: registro.saida, score: pontos, resultado: ROTULO[args.resultado] });
+  const semHistorico = await gravarHistorico(ctx, linha);
+  return [...avisos, semHistorico ?? linha, ...(await correcoesRecentes(raiz, crew)), `EXECUCAO:FECHADA ${args.resultado} ${pontos}`];
+}
+
+async function responder(raiz, crew, pasta, args, agora) {
+  if (args.acao === 'retomar') return retomar(raiz, crew, args.run);
+  const base = { crew, run: args.run, em: agora.toISOString() };
+  const acao = args.acao === 'marcar' ? marcar : fechar;
+  return (await acao({ raiz, crew, pasta, base, agora }, args)).filter(Boolean);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps] `cwd` (a pasta do projeto), `escrever` e `agora` (o relógio)
+ * @returns {Promise<number>} 0 = a linha `EXECUCAO:` saiu · 1 = erro de uso ou falha de leitura
+ *   (a linha de uso e o motivo, ou só o erro; sem linha `EXECUCAO:`)
+ */
+export async function main(argv, deps = {}) {
+  const { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`), agora = () => new Date() } = deps;
+  const args = lerArgs(argv);
+  const local = localizar(cwd, args);
+  if (local.erro) {
+    escrever(USO);
+    escrever(local.erro);
+    return 1;
+  }
+  try {
+    (await responder(cwd, local.crew, local.pasta, args, agora())).forEach((linha) => escrever(linha));
+    return 0;
+  } catch (erro) {
+    escrever(MSG.falha(erro?.message ?? erro));
+    return 1;
+  }
+}
+
+if (ehPrincipal(import.meta.url)) process.exitCode = await main(process.argv.slice(2));