@aksp/opencrew 1.12.0 → 1.14.0

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

@@ -2,24 +2,32 @@
 // Caminho da execução de uma crew: diz onde cada passo grava, de onde lê e se o arquivo gravado
 // está lá. Quem calcula é este script, igual em qualquer sistema — a IA não monta o caminho.
 // Uso (na pasta do projeto): node _opencrew/core/scripts/caminho.mjs <crew> <ação> --run <id> [opções]
-//   pasta    [--run <id>]                     cria crews/<crew>/output/<id>/; sem --run, o id é a
-//                                             data e a hora do computador (AAAA-MM-DD-HHmmss)
+//   pasta    [--run <id>] [--tema "<texto>"] [--passos N]
+//                                             cria crews/<crew>/output/<id>/ e o registro da
+//                                             execução; sem --run, o id é a data e a hora do
+//                                             computador (AAAA-MM-DD-HHmmss)
 //   saida    --run <id> --arquivo <declarado> onde o passo grava (abre a pasta de versão seguinte)
 //   entrada  --run <id> --arquivo <declarado> a saída mais nova desse arquivo
-//   conferir --arquivo <caminho já resolvido> [--secoes N] [--tldr]
+//   conferir --arquivo <caminho já resolvido> [--passo N] [--secoes N] [--tldr]
+//                                             com --passo, o arquivo aprovado entra no registro
 // <crew> é o nome da pasta em `crews/`. <declarado> é o `inputFile` ou `outputFile` do passo.
-// Só cria pastas, e só dentro de crews/<crew>/output/<id>/; nunca cria, altera nem apaga arquivo.
+// Só cria pastas, e só dentro de crews/<crew>/output/<id>/. O único arquivo que grava é o registro
+// da execução (`crews/<crew>/output/<id>/execucao.json`); nunca altera nem apaga outro arquivo.
+// Registro que não pôde ser gravado não muda a linha CAMINHO: — o aviso sai antes dela.
 // Última linha da saída (o runner lê esta linha): CAMINHO:OK <caminho>, CAMINHO:FALTA <caminho>
 // ou CAMINHO:REPROVADO <motivo>; o caminho sai relativo à pasta do projeto, com `/`.
 // Código de saída: 0 sempre que a linha CAMINHO: sai · 1 = erro de uso (ação ou opção faltando,
 // pasta sem `_opencrew/`, crew inexistente ou fora do projeto); com código 1 não há linha
 // CAMINHO: e nada é criado.
-// Spec: fase-r3-runner-em-uso-real.md (repositório do OpenCrew).
+// Specs: fase-r3-runner-em-uso-real.md e fase-u5c-execucao-registrada.md, regras 1 a 5
+// (repositório do OpenCrew).
 import path from 'node:path';
 import { MSG, dentroDoProjeto, ehPrincipal, realDentroDe } from './comum.mjs';
-import { USO, erroDeArgumentos, lerArgs, limpar } from './caminho/argumentos.mjs';
+import { RUN, USO, erroDeArgumentos, lerArgs, limpar } from './caminho/argumentos.mjs';
+import { acharCrew } from './caminho/crew.mjs';
+import { ARQUIVO, anotar, comPasso, limparTema } from './execucao/registro.mjs';
 import { MOTIVO, daMaisNova, motivoDeReprovacao, naExecucao, normalizar, novoRun, proximaVersao } from './caminho/nucleo.mjs';
-import { criarPasta, ehPasta, lerTexto, pastasDe, temConteudo } from './caminho/disco.mjs';
+import { criarPasta, lerTexto, pastasDe, temConteudo } from './caminho/disco.mjs';
 
 const ok = (caminho) => `CAMINHO:OK ${caminho}`;
 const falta = (caminho) => `CAMINHO:FALTA ${caminho}`;
@@ -50,15 +58,10 @@ function erroDoArquivo(raiz, crew, { acao, run, arquivo }) {
 function localizar(raiz, args) {
   const erro = erroDeArgumentos(args);
   if (erro) return { erro };
-  if (!ehPasta(path.join(raiz, '_opencrew'))) return { erro: MSG.semRaiz };
-  const base = path.resolve(raiz, 'crews');
-  const nome = args.crew.replace(/^crews[\\/]+/, '');
-  if (!dentroDoProjeto(base, nome)) return { erro: MSG.foraDoProjeto(limpar(args.crew)) };
-  const pasta = path.resolve(base, nome);
-  if (path.dirname(pasta) !== base || !ehPasta(pasta)) return { erro: MSG.crewNaoEncontrada(limpar(args.crew)) };
-  const crew = path.basename(pasta);
-  const doArquivo = args.arquivo ? erroDoArquivo(raiz, crew, args) : null;
-  return doArquivo ? { erro: doArquivo } : { crew };
+  const achada = acharCrew(raiz, args.crew);
+  if (achada.erro) return achada;
+  const doArquivo = args.arquivo ? erroDoArquivo(raiz, achada.crew, args) : null;
+  return doArquivo ? { erro: doArquivo } : achada;
 }
 
 /** Regras 2 e 3: o caminho em que o passo grava; a pasta dele é criada. */
@@ -90,23 +93,53 @@ function conferir(raiz, { arquivo, secoes, tldr }) {
   return motivo ? reprovado(motivo) : ok(caminho);
 }
 
-function responder(raiz, crew, args, agora) {
-  if (args.acao === 'saida') return saida(raiz, crew, args);
-  if (args.acao === 'entrada') return entrada(raiz, crew, args);
-  if (args.acao === 'conferir') return conferir(raiz, args);
-  const run = args.run || novoRun(agora(), pastasDe(path.resolve(raiz, 'crews', crew, 'output')));
-  const pasta = `crews/${crew}/output/${run}`;
-  criarPasta(path.resolve(raiz, pasta));
-  return ok(pasta);
+/**
+ * A execução de um arquivo conferido: a pasta logo depois de `crews/<crew>/output/`, se ela é de
+ * execução (tem registro, ou o nome começa por data) e fica mesmo dentro de `output/` — uma pasta
+ * qualquer do usuário, ou um atalho que leva para fora, não ganha registro.
+ */
+function execucaoDe(raiz, caminho, crew) {
+  const saida = `crews/${crew}/output/`;
+  const [run, ...resto] = caminho.startsWith(saida) ? caminho.slice(saida.length).split('/') : [];
+  if (!resto.length || !RUN.test(run) || resto.includes('..')) return null;
+  const pasta = path.resolve(raiz, saida, run);
+  const ehExecucao = /^\d{4}-\d{2}-\d{2}/.test(run) || temConteudo(path.join(pasta, ARQUIVO));
+  return ehExecucao && realDentroDe(path.resolve(raiz, saida), pasta) ? run : null;
+}
+
+/** Regra 2 da U5c: o arquivo que passou na conferência entra no registro, como a saída do passo. */
+async function conferirERegistrar(raiz, crew, args, em) {
+  const linha = conferir(raiz, args);
+  const [, caminho] = /^CAMINHO:OK (.*)$/.exec(linha) ?? [];
+  const run = caminho && args.passo ? execucaoDe(raiz, caminho, crew) : null;
+  if (!run) return [linha];
+  const pasta = path.resolve(raiz, 'crews', crew, 'output', run);
+  return [await anotar(pasta, { crew, run, em }, (registro) => comPasso(registro, { n: Number(args.passo), arquivo: caminho, em })), linha];
+}
+
+/** A pasta da execução; a que nasce agora ganha o registro (regras 1 e 3 da U5c: a que já existia fica como está). */
+async function pasta(raiz, crew, args, agora) {
+  const run = args.run || novoRun(agora, pastasDe(path.resolve(raiz, 'crews', crew, 'output')));
+  const rel = `crews/${crew}/output/${run}`;
+  const nova = criarPasta(path.resolve(raiz, rel));
+  const base = { crew, run, tema: limparTema(args.tema), passos: args.passos ? Number(args.passos) : null, em: agora.toISOString() };
+  return [nova ? await anotar(path.resolve(raiz, rel), base, (registro) => registro) : null, ok(rel)];
+}
+
+async function responder(raiz, crew, args, agora) {
+  if (args.acao === 'saida') return [saida(raiz, crew, args)];
+  if (args.acao === 'entrada') return [entrada(raiz, crew, args)];
+  if (args.acao === 'conferir') return conferirERegistrar(raiz, crew, args, agora.toISOString());
+  return pasta(raiz, crew, args, agora);
 }
 
 /**
  * @param {string[]} argv
  * @param {object} [deps] `cwd` (a pasta do projeto), `escrever` e `agora` (o relógio, para o id da execução)
- * @returns {number} 0 = a linha `CAMINHO:` saiu · 1 = erro de uso, ou falha ao ler ou criar pasta
- *   (a linha de uso e o motivo, ou só o erro; sem linha `CAMINHO:`)
+ * @returns {Promise<number>} 0 = a linha `CAMINHO:` saiu · 1 = erro de uso, ou falha ao ler ou
+ *   criar pasta (a linha de uso e o motivo, ou só o erro; sem linha `CAMINHO:`)
  */
-export function main(argv, deps = {}) {
+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);
@@ -116,7 +149,7 @@ export function main(argv, deps = {}) {
     return 1;
   }
   try {
-    escrever(responder(cwd, local.crew, args, agora));
+    (await responder(cwd, local.crew, args, agora())).filter(Boolean).forEach((linha) => escrever(linha));
     return 0;
   } catch (erro) {
     escrever(`Não consegui resolver o caminho: ${limpar(erro?.message ?? erro)}`);
@@ -124,4 +157,4 @@ export function main(argv, deps = {}) {
   }
 }
 
-if (ehPrincipal(import.meta.url)) process.exitCode = main(process.argv.slice(2));
+if (ehPrincipal(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/templates/_opencrew/core/scripts/conserto/achados.mjs

@@ -6,6 +6,7 @@ import { lerFrontmatter, semBom } from '../verificar/leitura.mjs';
 import { itensDeProibicao } from '../verificar/proibicoes.mjs';
 import { idDoAgente, lerBruto, listaDe } from './crew.mjs';
 import { lerCsv } from './edicoes.mjs';
+import { achadoDoHistorico } from './historico.mjs';
 
 const EXPORTACAO = new Set(['pdf', 'csv', 'formatted-post']);
 const plural = (n, um, varios) => (n === 1 ? um : varios);
@@ -146,6 +147,7 @@ const CONFERENCIAS = [
   ['nome-de-agente', nomeDeAgente], ['manifesto', manifesto], ['formato', formato], ['fontes', fontes],
   ['proibicao', proibicao], ['irreversivel', semMarca], ['sem-revisao', semRevisao],
   ['sem-aprovacao-final', semAprovacaoFinal], ['publica-antes', publicaAntes], ['passo-faltando', passoFaltando],
+  ['historico', achadoDoHistorico],
 ];
 
 /**

package/templates/_opencrew/core/scripts/conserto/aplicar.mjs

@@ -8,6 +8,7 @@ import { lerFrontmatter, semAcento, semBom } from '../verificar/leitura.mjs';
 import { ehRevisaoHumana, itensDeProibicao, lerLinha } from '../verificar/proibicoes.mjs';
 import { comChave, comFonte, comSufixo, comTitulo, montarCsv } from './edicoes.mjs';
 import { erroAntesDeGravar } from './gravar.mjs';
+import { historico } from './historico.mjs';
 
 const MSG = {
   semValor: (item) => `Sobra ou falta valor em --aplicar "${item.escrito}". Veja os itens com --ajuda.`,
@@ -134,7 +135,7 @@ function proibicao(crew, item, plano) {
   return plano.trocar(memoria, crew.memoria, novo);
 }
 
-const ACOES = { manifesto, nome, formato, fonte, proibicao, irreversivel };
+const ACOES = { manifesto, nome, formato, fonte, proibicao, irreversivel, historico };
 
 /**
  * Valida os itens e monta as mudanças, sem gravar.

package/templates/_opencrew/core/scripts/conserto/argumentos.mjs

@@ -13,9 +13,10 @@ export const AJUDA = [
   '  proibicao:<n>=<trecho>           o trecho do item n vira trava do verificador',
   '  proibicao:<n>=revisao-humana     o item n fica para o revisor',
   '  irreversivel:<passo>             marca o passo que publica ou envia',
+  '  historico:<execução>=<tema>      põe no histórico a execução que ficou sem linha',
 ];
 
-export const TIPOS = ['manifesto', 'nome', 'formato', 'fonte', 'proibicao', 'irreversivel'];
+export const TIPOS = ['manifesto', 'nome', 'formato', 'fonte', 'proibicao', 'irreversivel', 'historico'];
 const OPCAO = /^--(crew|aplicar|ajuda)(?:=(.*))?$/s;
 const ITEM = /^([a-z-]+)(?::([^=]*))?(?:=(.*))?$/s;
 

package/templates/_opencrew/core/scripts/conserto/crew.mjs

@@ -1,5 +1,5 @@
-// Leitura de uma crew para o conserto: `crew.yaml`, os passos do pipeline, os agentes, o manifesto
-// e a memória. A leitura é tolerante (aceita as formas que versões antigas gravaram) e nunca grava.
+// Leitura de uma crew para o conserto: `crew.yaml`, os passos do pipeline, os agentes, o manifesto,
+// a memória e o histórico (`runs.md`). A leitura é tolerante (aceita as formas que versões antigas gravaram) e nunca grava.
 // Spec: fase-u4a-conserto-de-crews.md, regra 5 (repositório do OpenCrew).
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
@@ -121,6 +121,7 @@ export function lerCrew(raiz, crew) {
     agentes: agentesDe(pasta),
     csv: lerBruto(arquivo('crew-party.csv')),
     memoria: lerBruto(arquivo('_memory', 'memories.md')),
-    arquivos: { yaml: arquivo('crew.yaml'), csv: arquivo('crew-party.csv'), memoria: arquivo('_memory', 'memories.md') },
+    runs: lerBruto(arquivo('_memory', 'runs.md')),
+    arquivos: { yaml: arquivo('crew.yaml'), csv: arquivo('crew-party.csv'), memoria: arquivo('_memory', 'memories.md'), runs: arquivo('_memory', 'runs.md') },
   };
 }

package/templates/_opencrew/core/scripts/conserto/historico.mjs

@@ -0,0 +1,102 @@
+// O histórico no conserto: pastas de execução sem linha no `runs.md` (achado), pasta vazia e linha
+// sem pasta (só apontadas), e o item que grava a linha "Registrada depois". Nunca apaga nem cria
+// registro de execução.
+// Spec: fase-u5c-execucao-registrada.md, regras 12 e 13 (repositório do OpenCrew).
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { REGISTRADA_DEPOIS, comLinha, dataDe, linhaDe, runsDoHistorico } from '../execucao/historico.mjs';
+import { RUN } from '../caminho/argumentos.mjs';
+import { ARQUIVO, limparTema } from '../execucao/registro.mjs';
+
+const MSG = {
+  semLinha: (n) => `${n} ${n === 1 ? 'execução' : 'execuções'} sem linha no histórico.`,
+  vazias: (runs) => `${runs.length} ${runs.length === 1 ? 'execução abandonada (pasta vazia)' : 'execuções abandonadas (pasta vazia)'}: ${runs.join(', ')}`,
+  semPasta: (runs) => `${runs.length} ${runs.length === 1 ? 'linha' : 'linhas'} do histórico sem a pasta da execução: ${runs.join(', ')} (só aponto: nada é apagado)`,
+  interrompida: (crew) => ` (interrompida: /opencrew retomar ${crew} continua de onde parou)`,
+  comoRegistrar: 'Para registrar: --aplicar "historico:<execução>=<tema>"',
+  semValor: (item) => `Sobra ou falta valor em --aplicar "${item.escrito}". Veja os itens com --ajuda.`,
+  semExecucao: (item) => `Pasta de execução não encontrada em --aplicar "${item.escrito}".`,
+  jaTemLinha: (run) => `A execução ${run} já tem linha no histórico.`,
+};
+
+const COM_DATA = /^\d{4}-\d{2}-\d{2}/;
+const MAXIMO_DE_NOMES = 8;
+
+const entradas = (pasta) => (existsSync(pasta) ? readdirSync(pasta, { withFileTypes: true }) : []);
+const saidaDe = (crew) => path.join(crew.pasta, 'output');
+
+/** O `status` do registro da pasta, ou `null` (sem registro, ou ilegível). */
+function statusDe(pasta) {
+  try {
+    return JSON.parse(readFileSync(path.join(pasta, ARQUIVO), 'utf8')).status ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Uma pasta da execução, como o usuário a reconhece: pelos arquivos dela (`v1/ata.md`); sem arquivo direto, `v1/`. */
+function daPasta(execucao, nome) {
+  const arquivos = entradas(path.join(execucao, nome)).filter((e) => e.isFile()).map((e) => `${nome}/${e.name}`);
+  return arquivos.length ? arquivos : [`${nome}/`];
+}
+
+/** As pastas de `output/` que são de execução: o nome começa por uma data, ou a pasta tem registro. */
+function execucoes(crew) {
+  const pastas = entradas(saidaDe(crew)).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  return pastas.map((run) => {
+    const pasta = path.join(saidaDe(crew), run);
+    // O registro (e um temporário dele) não conta como arquivo da execução: a pasta que só tem isso é abandonada.
+    const doRegistro = (nome) => nome === ARQUIVO || (nome.startsWith(`${ARQUIVO}.`) && nome.endsWith('.tmp'));
+    const topo = entradas(pasta).filter((e) => !doRegistro(e.name)).flatMap((e) => (e.isDirectory() ? daPasta(pasta, e.name) : [e.name])).sort();
+    return { run, topo, status: statusDe(pasta), ehExecucao: COM_DATA.test(run) || existsSync(path.join(pasta, ARQUIVO)) };
+  }).filter((e) => e.ehExecucao);
+}
+
+/** O que não bate entre as pastas e o `runs.md`. */
+function situacao(crew) {
+  const comLinhaNoHistorico = runsDoHistorico(crew.runs);
+  const pastas = execucoes(crew);
+  const semLinha = pastas.filter((e) => !comLinhaNoHistorico.includes(e.run));
+  return {
+    semLinha: semLinha.filter((e) => e.topo.length),
+    vazias: semLinha.filter((e) => !e.topo.length).map((e) => e.run),
+    semPasta: comLinhaNoHistorico.filter((run) => !existsSync(path.join(saidaDe(crew), run))),
+  };
+}
+
+/** O que é só apontado: a pasta vazia e a linha sem pasta. */
+function apontados({ vazias, semPasta }) {
+  return [...(vazias.length ? [MSG.vazias(vazias)] : []), ...(semPasta.length ? [MSG.semPasta(semPasta)] : [])];
+}
+
+function linhaDaPasta(crew, { run, topo, status }) {
+  const nomes = topo.length > MAXIMO_DE_NOMES ? [...topo.slice(0, MAXIMO_DE_NOMES), '…'] : topo;
+  return `${run}: ${nomes.join(', ')}${status === 'aberta' ? MSG.interrompida(crew.nome) : ''}`;
+}
+
+/** O achado `historico`: só existe quando há pasta com arquivos e sem linha. @returns {string[]|null} */
+export function achadoDoHistorico(crew) {
+  const s = situacao(crew);
+  if (!s.semLinha.length) return null;
+  return [MSG.semLinha(s.semLinha.length), ...s.semLinha.map((e) => linhaDaPasta(crew, e)), ...apontados(s), MSG.comoRegistrar];
+}
+
+/** Sem o achado, o que é só apontado sai como nota: não deixa a crew pendente. @returns {string[]} */
+export function notasDoHistorico(crew) {
+  const s = situacao(crew);
+  return s.semLinha.length ? [] : apontados(s).map((linha) => `Nota: ${linha}`);
+}
+
+/** O item `historico:<execução>=<tema>`: a linha "Registrada depois", na posição da data dela. */
+export function historico(crew, item, plano) {
+  const run = item.alvo;
+  const pasta = path.join(saidaDe(crew), run);
+  if (!RUN.test(run) || !entradas(saidaDe(crew)).some((e) => e.isDirectory() && e.name === run)) return MSG.semExecucao(item);
+  const { runs } = crew.arquivos;
+  const texto = plano.texto(runs, crew.runs);
+  if (runsDoHistorico(texto).includes(run)) return MSG.jaTemLinha(run);
+  if (!limparTema(item.valor)) return MSG.semValor(item);
+  const data = dataDe(run, statSync(pasta).mtime); // id sem data: o dia em que a pasta mudou pela última vez
+  const linha = linhaDe({ data, run, tema: limparTema(item.valor), saida: '', score: '', resultado: REGISTRADA_DEPOIS });
+  return plano.trocar(runs, crew.runs, comLinha(texto, { crew: crew.nome, run, linha, porData: true }));
+}

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

@@ -6,14 +6,15 @@
 //   node _opencrew/core/scripts/conserto.mjs --crew "crews/<crew>" --aplicar "<item>"   grava
 // Itens de --aplicar: manifesto · nome:<agente>=<Nome Sobrenome> · formato:<passo>=<formato> ·
 //   fonte:<caminho>=<para que> · proibicao:<n>=<trecho> · proibicao:<n>=revisao-humana ·
-//   irreversivel:<passo> (ver --ajuda).
-// Só grava `crew.yaml`, `crew-party.csv`, `agents/*.agent.md`, `pipeline/steps/*.md` e
-// `_memory/memories.md` da crew, e a cópia `<arquivo>.bak` de cada um (a cópia que já existe
-// não é sobrescrita). Nunca apaga.
+//   irreversivel:<passo> · historico:<execução>=<tema> (ver --ajuda).
+// Só grava `crew.yaml`, `crew-party.csv`, `agents/*.agent.md`, `pipeline/steps/*.md`,
+// `_memory/memories.md` e `_memory/runs.md` da crew, e a cópia `<arquivo>.bak` de cada um (a
+// cópia que já existe não é sobrescrita). Nunca apaga.
 // Última linha da saída: CONSERTO:OK (nada a consertar) · CONSERTO:PENDENTE (há achados) ·
 // CONSERTO:APLICADO (tudo o que foi pedido está gravado) · CONSERTO:ERRO (nada foi gravado).
 // Código de saída: 0, menos com CONSERTO:ERRO (1).
-// Spec: fase-u4a-conserto-de-crews.md (repositório do OpenCrew).
+// Specs: fase-u4a-conserto-de-crews.md e fase-u5c-execucao-registrada.md, regras 12 e 13
+// (repositório do OpenCrew).
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { ehPrincipal, erroDeUso } from './comum.mjs';
@@ -22,6 +23,7 @@ import { planejar } from './conserto/aplicar.mjs';
 import { AJUDA, lerArgs, lerItem, limpar } from './conserto/argumentos.mjs';
 import { lerCrew } from './conserto/crew.mjs';
 import { gravar } from './conserto/gravar.mjs';
+import { notasDoHistorico } from './conserto/historico.mjs';
 
 const MSG = {
   estranho: (arg) => `Argumento desconhecido: ${limpar(arg)}. Veja as opções com --ajuda.`,
@@ -46,9 +48,9 @@ function erroDaChamada(raiz, args) {
 /** As linhas do diagnóstico: um bloco por achado e a linha de situação. */
 function relatorio(crew) {
   const achados = diagnosticar(crew);
-  if (!achados.length) return [MSG.emDia(crew.nome), 'CONSERTO:OK'];
+  if (!achados.length) return [MSG.emDia(crew.nome), ...notasDoHistorico(crew), 'CONSERTO:OK'];
   const blocos = achados.flatMap(({ codigo, linhas: [titulo, ...resto] }) => ['', `[${codigo}] ${titulo}`, ...resto.map((l) => `  ${l}`)]);
-  return [MSG.titulo(crew.nome, achados.length), ...blocos, '', 'CONSERTO:PENDENTE'];
+  return [MSG.titulo(crew.nome, achados.length), ...blocos, '', ...notasDoHistorico(crew), 'CONSERTO:PENDENTE'];
 }
 
 /** As linhas de um `--aplicar`: o que foi gravado, as cópias e a linha de situação. */

package/templates/_opencrew/core/scripts/entrega/leiame.mjs

@@ -2,7 +2,8 @@
 // aparece. Arquivo da entrega é citado com caminho relativo à pasta do LEIA-ME; o de origem,
 // relativo ao projeto. Sem hora: as mesmas entradas geram os mesmos bytes. PT-BR fixo.
 // Specs: fase-u3a1-pasta-de-entrega.md, §4 e §6, e fase-u3a2-entrega-no-projeto.md, §4 e §6
-// (ressalvas, a cópia e "Sobre esta pasta"), no repositório do OpenCrew.
+// (ressalvas, a cópia e "Sobre esta pasta"), e fase-u5c-execucao-registrada.md, regra 10 (o tema
+// no título), no repositório do OpenCrew.
 import { CANAIS, EDITAVEIS, OUTROS } from './canais.mjs';
 import { frasesDePendencia } from './pendencias.mjs';
 import { NAO_EDITE_O_WORD, passosDe } from './passos.mjs';
@@ -97,6 +98,7 @@ function sobre(d) {
 /**
  * @param {object} d
  * @param {string} d.crew nome da crew · @param {string} d.run id da execução
+ * @param {string} [d.tema] o tema do registro da execução; com ele, o título é `{tema} ({run})`
  * @param {string[]} d.pastas os canais presentes, na ordem das seções
  * @param {object[]} d.arquivos `{ pasta, nome, tipo, origem, titulo, numerado }` — no LEIA-ME da
  *   cópia, só os que foram copiados
@@ -113,7 +115,7 @@ function sobre(d) {
 export function montarLeiame(d) {
   const temMd = d.arquivos.some((a) => a.nome.toLowerCase().endsWith('.md'));
   const partes = [
-    `# Entrega — ${d.crew} — ${d.run}${d.reentrega > 1 ? ` (reentrega ${d.reentrega})` : ''}`,
+    `# Entrega — ${d.crew} — ${d.tema ? `${d.tema} (${d.run})` : d.run}${d.reentrega > 1 ? ` (reentrega ${d.reentrega})` : ''}`,
     ...antesDeUsar(d),
     ...d.pastas.flatMap((pasta) => secaoDoCanal(d, pasta)),
     ...secaoDaPasta(d, OUTROS, 'Outros arquivos'),

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

@@ -35,6 +35,7 @@ import { DOCUMENTOS, converterDocumentos, naoConferidoDoWord } from './entrega/d
 import { MSG as COPIA, guardar } from './entrega/guardar.mjs';
 import { gravarEntrega } from './entrega/gravar.mjs';
 import { montarLeiame } from './entrega/leiame.mjs';
+import { lerRegistro } from './execucao/registro.mjs';
 import { lembrarDestino } from './entrega/lembrar.mjs';
 import { nomear } from './entrega/nomes.mjs';
 import { alertasDeTamanho, naoConferido, pendenciasPorPasta } from './entrega/pendencias.mjs';
@@ -95,6 +96,7 @@ async function montar(raiz, args, itens, aceitas) {
   const presentes = new Set([...arquivos.map((a) => a.pasta), ...todas.keys()]);
   const dados = {
     crew: path.basename(path.resolve(raiz, args.crew)), run: args.run, arquivos, avisos,
+    tema: (await lerRegistro(path.resolve(raiz, args.crew, 'output', args.run)))?.tema ?? '',
     ...separarPendencias(todas, aceitas, args.aceitar),
     pastas: Object.keys(CANAIS).filter((c) => presentes.has(c)),
     alertas: await alertasDeTamanho(raiz, itens, arquivos, verificacao),

package/templates/_opencrew/core/scripts/estado/arquivo.mjs

@@ -32,22 +32,29 @@ async function trocarNome(de, para, { renomear = fs.rename, esperar = pausa }) {
 }
 
 /**
- * Grava o estado num temporário da mesma pasta (`state.json.<pid>.tmp`) e troca o nome: quem lê
- * vê o arquivo antigo ou o novo, nunca um pela metade.
- * @param {string} arquivo caminho do `state.json`
- * @param {object} estado
+ * Grava o texto num temporário da mesma pasta (`<arquivo>.<pid>.tmp`) e troca o nome: quem lê vê
+ * o arquivo antigo ou o novo, nunca um pela metade. Quando desiste, o arquivo fica como estava, o
+ * temporário é apagado e o erro sobe.
  * @param {{ renomear?: Function, esperar?: Function }} [deps] SÓ PARA TESTE: a troca de nome
  *   (`(de, para) => Promise`) e a espera entre as tentativas (`(ms) => Promise`)
- * @returns {Promise<boolean>} `false` quando desistiu: o arquivo fica como estava e o temporário é apagado
  */
-export async function gravarEstado(arquivo, estado, deps = {}) {
+export async function gravarTexto(arquivo, texto, deps = {}) {
   const temporario = `${arquivo}.${process.pid}.tmp`;
   try {
-    await fs.writeFile(temporario, `${JSON.stringify(estado, null, 2)}\n`);
+    await fs.writeFile(temporario, texto);
     await trocarNome(temporario, arquivo, deps);
-    return true;
-  } catch {
+  } catch (erro) {
     await fs.rm(temporario, { force: true }).catch(() => {});
-    return false;
+    throw erro;
   }
 }
+
+/**
+ * Grava o `state.json`, inteiro ou nada (ver `gravarTexto`).
+ * @param {string} arquivo caminho do `state.json`
+ * @param {object} estado
+ * @returns {Promise<boolean>} `false` quando desistiu
+ */
+export async function gravarEstado(arquivo, estado, deps = {}) {
+  return gravarTexto(arquivo, `${JSON.stringify(estado, null, 2)}\n`, deps).then(() => true, () => false);
+}

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

@@ -0,0 +1,62 @@
+// Linha de comando do `execucao.mjs`: a crew, a ação, as opções e a linha de uso.
+// Spec: fase-u5c-execucao-registrada.md, §3 (repositório do OpenCrew).
+import { MSG } from '../comum.mjs';
+import { RUN, limpar } from '../caminho/argumentos.mjs';
+
+export const USO = 'Uso: node _opencrew/core/scripts/execucao.mjs <crew> <marcar|fechar|retomar> [opções]';
+export const ACOES = ['marcar', 'fechar', 'retomar'];
+/** Os resultados que cada evento do `marcar` aceita. */
+export const RESULTADOS = { checkpoint: ['aprovado', 'corrigido', 'pulado'], revisao: ['aprovado', 'rejeitado'] };
+export const FECHOS = ['aprovado', 'rejeitado', 'abortado', 'publicado'];
+
+const OPCAO = /^--(run|passo|evento|resultado|nota|saida|tema)(?:=(.*))?$/s;
+const INTEIRO = /^[1-9]\d{0,8}$/;
+const lista = (itens) => `${itens.slice(0, -1).join(', ')} ou ${itens.at(-1)}`;
+
+/**
+ * `argv` → `{ crew, acao, run, passo, evento, resultado, nota, saida, tema }`. Os dois primeiros
+ * argumentos soltos são a crew e a ação. Opção vale como `--nome valor` e `--nome=valor`; opção
+ * ausente fica `undefined`.
+ */
+export function lerArgs(argv) {
+  const soltos = [];
+  const opcoes = {};
+  for (let i = 0; i < argv.length; i++) {
+    const [, nome, colado] = argv[i].match(OPCAO) ?? [];
+    if (!nome) soltos.push(argv[i]);
+    else if (colado !== undefined) opcoes[nome] = colado;
+    else opcoes[nome] = i + 1 < argv.length && !OPCAO.test(argv[i + 1]) ? argv[++i] : '';
+  }
+  const [crew, acao] = soltos.filter((s) => !s.startsWith('--'));
+  return { crew, acao, ...opcoes };
+}
+
+function erroDoMarcar({ passo, evento, resultado }) {
+  if (!passo) return MSG.faltaOpcao('--passo');
+  if (!INTEIRO.test(passo)) return 'O --passo é um número inteiro a partir de 1.';
+  if (!evento) return MSG.faltaOpcao('--evento');
+  if (!RESULTADOS[evento]) return 'O --evento é checkpoint ou revisao.';
+  if (!resultado) return MSG.faltaOpcao('--resultado');
+  return RESULTADOS[evento].includes(resultado) ? null : `O --resultado de ${evento} é ${lista(RESULTADOS[evento])}.`;
+}
+
+function erroDoFechar({ resultado }) {
+  if (!resultado) return MSG.faltaOpcao('--resultado');
+  return FECHOS.includes(resultado) ? null : `O --resultado de fechar é ${lista(FECHOS)}.`;
+}
+
+/**
+ * O que falta ou está errado na linha de comando, antes de olhar o disco. Só o `retomar` dispensa
+ * o `--run` (sem ele, vale a execução aberta mais recente).
+ * @returns {string|null} o motivo em PT-BR, ou `null`
+ */
+export function erroDeArgumentos(args) {
+  const { crew, acao, run } = args;
+  if (!crew) return 'Falta o nome da crew.';
+  if (!acao) return `Falta a ação. Ações: ${ACOES.join(', ')}.`;
+  if (!ACOES.includes(acao)) return `Ação desconhecida: ${limpar(acao)}. Ações: ${ACOES.join(', ')}.`;
+  if (run === '' || (acao !== 'retomar' && !run)) return MSG.faltaOpcao('--run');
+  if (run !== undefined && !RUN.test(run)) return 'O --run só aceita letras, dígitos, ponto, sublinhado e hífen.';
+  if (acao === 'marcar') return erroDoMarcar(args);
+  return acao === 'fechar' ? erroDoFechar(args) : null;
+}

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

@@ -0,0 +1,76 @@
+// A tabela do `runs.md` de uma crew, em funções puras: a linha de uma execução e o texto do
+// arquivo com essa linha posta ou trocada. Nenhuma outra linha muda, byte a byte (fim de linha
+// incluído). Usado pelo `execucao.mjs fechar` e pelo conserto do histórico.
+// Spec: fase-u5c-execucao-registrada.md, §4 e regras 7 e 13 (repositório do OpenCrew).
+
+const COLUNAS = '| Data | Run ID | Tema | Output | Score | Resultado |';
+const TRACOS = '|------|--------|------|--------|-------|-----------|';
+/** O `runs.md` que nasce quando a crew ainda não tem um. */
+export const cabecalho = (crew) => `# Run History: ${crew}\n\n${COLUNAS}\n${TRACOS}\n`;
+
+/** O `--resultado` do `fechar` como aparece na coluna Resultado. */
+export const ROTULO = { aprovado: 'Aprovado', rejeitado: 'Rejeitado', abortado: 'Abortado', publicado: 'Publicado' };
+export const REGISTRADA_DEPOIS = 'Registrada depois';
+
+const celula = (texto) => String(texto ?? '').replace(/\|/g, '/').replace(/\s+/g, ' ').trim() || '—';
+/** @param {{ data, run, tema, saida, score, resultado }} execucao célula vazia sai como `—` */
+export const linhaDe = ({ data, run, tema, saida, score, resultado }) => `| ${[data, run, tema, saida, score, resultado].map(celula).join(' | ')} |`;
+
+const dois = (n) => String(n).padStart(2, '0');
+/** A data de uma execução: os 10 primeiros caracteres do `run_id`; id sem data, o dia de `quando`. */
+export function dataDe(run, quando) {
+  const [doRun] = /^\d{4}-\d{2}-\d{2}/.exec(run) ?? [];
+  return doRun ?? `${quando.getFullYear()}-${dois(quando.getMonth() + 1)}-${dois(quando.getDate())}`;
+}
+
+const celulas = (linha) => (linha.trim().startsWith('|') ? linha.trim().replace(/\|$/, '').split('|').slice(1).map((c) => c.trim()) : null);
+const ehTracos = (linha) => /^\s*\|[\s:|-]*-[\s:|-]*$/.test(linha);
+
+/** Onde está a tabela: o índice da linha de traços e o da última linha de execução (ou o dos traços). */
+function tabela(pedacos) {
+  const comRunId = (i) => i > 0 && (celulas(pedacos[i - 1]) ?? []).some((c) => /^run\s*id$/i.test(c));
+  let tracos = pedacos.findIndex((p, i) => ehTracos(p) && comRunId(i));
+  if (tracos < 0) tracos = pedacos.findIndex((p, i) => ehTracos(p) && i > 0 && celulas(pedacos[i - 1]));
+  if (tracos < 0) return null;
+  // Linha em branco no meio não encerra a tabela, se depois dela ainda há linha de execução.
+  let fim = tracos;
+  for (let i = tracos + 1; i < pedacos.length && (celulas(pedacos[i]) || !pedacos[i].trim()); i++) if (celulas(pedacos[i])) fim = i;
+  return { tracos, fim };
+}
+
+/** Os `run_id` que já têm linha no histórico. */
+export function runsDoHistorico(texto) {
+  const pedacos = String(texto ?? '').split(/(?<=\n)/);
+  const t = tabela(pedacos);
+  return t ? pedacos.slice(t.tracos + 1, t.fim + 1).map((p) => celulas(p)?.[1]).filter(Boolean) : [];
+}
+
+/** Onde a linha entra: logo abaixo dos traços, ou (`porData`) antes da primeira execução mais antiga. */
+function posicao(pedacos, { tracos, fim }, data) {
+  if (data === null) return tracos + 1;
+  for (let i = tracos + 1; i <= fim; i++) if (celulas(pedacos[i]) && (celulas(pedacos[i])[0] ?? '') < data) return i;
+  return fim + 1;
+}
+
+/**
+ * O texto do `runs.md` com a linha da execução: trocada, se o `run` já tem linha; senão, posta.
+ * @param {string|null} texto o arquivo como está no disco (`null`: não existe)
+ * @param {{ crew: string, run: string, linha: string, porData?: boolean }} dados `porData`: a linha
+ *   entra na posição da data dela (conserto); sem isso, logo abaixo do cabeçalho (a mais nova em cima)
+ */
+export function comLinha(texto, { crew, run, linha, porData = false }) {
+  if (texto === null || texto === '') return `${cabecalho(crew)}${linha}\n`;
+  const fimDeLinha = /\r\n/.test(texto) ? '\r\n' : '\n';
+  const pedacos = texto.split(/(?<=\n)/);
+  const t = tabela(pedacos);
+  if (!t) return `${texto}${texto.endsWith('\n') ? '' : fimDeLinha}${fimDeLinha}${[COLUNAS, TRACOS, linha].join(fimDeLinha)}${fimDeLinha}`;
+  const igual = pedacos.findIndex((p, i) => i > t.tracos && i <= t.fim && celulas(p)?.[1] === run);
+  if (igual >= 0) pedacos[igual] = `${linha}${/\r?\n$/.exec(pedacos[igual])?.[0] ?? ''}`;
+  else {
+    const i = posicao(pedacos, t, porData ? linha.split('|')[1].trim() : null);
+    // Depois de uma linha sem quebra no fim (a última do arquivo), a quebra vem antes da linha nova.
+    const semQuebra = i > 0 && !pedacos[i - 1].endsWith('\n');
+    pedacos.splice(i, 0, semQuebra ? `${fimDeLinha}${linha}` : `${linha}${fimDeLinha}`);
+  }
+  return pedacos.join('');
+}