@aksp/opencrew 1.6.3 → 1.7.1

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

@@ -0,0 +1,61 @@
+// Núcleo do `caminho.mjs`: as regras de caminho de uma execução, em funções puras. Não toca em
+// disco nem em processo (quem lê pastas e arquivos é `disco.mjs`).
+// Spec: fase-r3-runner-em-uso-real.md, regras 2 a 5 (repositório do OpenCrew).
+
+export const ACOES = ['pasta', 'saida', 'entrada', 'conferir'];
+
+/** Os motivos de `CAMINHO:REPROVADO`, na ordem em que são conferidos (§6 da spec). */
+export const MOTIVO = {
+  ausente: 'arquivo ausente ou vazio',
+  secoes: (achadas, minimo) => `${achadas} seções, mínimo ${minimo}`,
+  tldr: 'falta a seção TL;DR',
+};
+
+/** Caminho como o script o compara e devolve: com `/`, sem `./` na frente e sem barra dobrada. */
+export const normalizar = (caminho) => String(caminho).replace(/\\/g, '/').replace(/^(?:\.\/+)+/, '').replace(/\/{2,}/g, '/');
+
+/**
+ * Regra 2 — o caminho da execução. Caminho declarado que começa por `crews/<crew>/output/` ganha
+ * `<run>/` logo depois de `output/`.
+ * @returns {{ grupo: string, nome: string } | null} o grupo (a pasta do arquivo, já com o run) e
+ *   o nome do arquivo; `null` quando o caminho não é de `output/` (volta como veio)
+ */
+export function naExecucao(declarado, crew, run) {
+  const saida = `crews/${crew}/output/`;
+  const caminho = normalizar(declarado);
+  if (!caminho.startsWith(saida)) return null;
+  const partes = caminho.slice(saida.length).split('/');
+  const nome = partes.pop();
+  return { grupo: [`${saida}${run}`, ...partes].join('/'), nome };
+}
+
+/** O número de uma pasta de versão (`v` + número), ou `null` para qualquer outro nome. */
+function numero(nome) {
+  const [, digitos] = /^v(\d{1,9})$/.exec(nome) ?? [];
+  return digitos === undefined ? null : Number(digitos);
+}
+
+/** As pastas de versão, da mais nova para a mais antiga, em ordem numérica (`v10` antes de `v9`). */
+export function daMaisNova(nomes) {
+  return nomes.filter((nome) => numero(nome) !== null).sort((a, b) => numero(b) - numero(a));
+}
+
+/** Regra 3 — a versão em que o passo grava: a maior `vN` do grupo mais 1; sem nenhuma, `v1`. */
+export function proximaVersao(nomes) {
+  const [maior] = daMaisNova(nomes);
+  return `v${maior ? numero(maior) + 1 : 1}`;
+}
+
+/**
+ * Regra 5 — o que falta no texto de um arquivo gravado, pelo primeiro motivo da §6.
+ * @param {string} texto o conteúdo do arquivo (que já existe e não está vazio)
+ * @param {{ secoes?: number|null, tldr?: boolean }} pedido
+ * @returns {string|null} o motivo, ou `null` quando o arquivo passa
+ */
+export function motivoDeReprovacao(texto, { secoes = null, tldr = false } = {}) {
+  const linhas = (texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto).split(/\r?\n/);
+  const achadas = linhas.filter((linha) => linha.startsWith('## ')).length;
+  if (secoes !== null && achadas < secoes) return MOTIVO.secoes(achadas, secoes);
+  if (tldr && !linhas.some((linha) => linha.startsWith('## TL;DR'))) return MOTIVO.tldr;
+  return null;
+}

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// 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>/
+//   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]
+// <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.
+// Ú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).
+import path from 'node:path';
+import { MSG, dentroDoProjeto, ehPrincipal, realDentroDe } from './comum.mjs';
+import { USO, erroDeArgumentos, lerArgs, limpar } from './caminho/argumentos.mjs';
+import { MOTIVO, daMaisNova, motivoDeReprovacao, naExecucao, normalizar, proximaVersao } from './caminho/nucleo.mjs';
+import { criarPasta, ehPasta, lerTexto, pastasDe, temConteudo } from './caminho/disco.mjs';
+
+const ok = (caminho) => `CAMINHO:OK ${caminho}`;
+const falta = (caminho) => `CAMINHO:FALTA ${caminho}`;
+const reprovado = (motivo) => `CAMINHO:REPROVADO ${motivo}`;
+
+/**
+ * O arquivo declarado cabe na execução? Dentro de `output/`, depois de ganhar o run, ele tem de
+ * continuar dentro da pasta da execução — pelo texto e pelo lugar real.
+ * @returns {string|null} o erro de uso, ou `null`
+ */
+function erroDoArquivo(raiz, crew, { acao, run, arquivo }) {
+  if (!dentroDoProjeto(raiz, arquivo)) return MSG.foraDoProjeto(limpar(arquivo));
+  const local = acao === 'conferir' ? null : naExecucao(arquivo, crew, run);
+  if (!local) return null;
+  if (!local.nome) return `Falta o nome do arquivo em --arquivo: ${limpar(arquivo)}`;
+  const execucao = path.resolve(raiz, 'crews', crew, 'output', run);
+  const partes = normalizar(arquivo).split('/');
+  const sai = partes.includes('..') || partes.includes('.') || !realDentroDe(execucao, path.resolve(raiz, local.grupo));
+  return sai ? `Caminho fora da pasta da execução: ${limpar(arquivo)}` : null;
+}
+
+/**
+ * Onde fica a crew, ou o erro de uso. A crew é uma pasta direta de `crews/` (`crews/<nome>`
+ * também vale).
+ * @returns {{ erro: string } | { crew: string }}
+ */
+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 };
+}
+
+/** Regras 2 e 3: o caminho em que o passo grava; a pasta dele é criada. */
+function saida(raiz, crew, { run, arquivo }) {
+  const local = naExecucao(arquivo, crew, run);
+  if (!local) return ok(normalizar(arquivo));
+  const pasta = `${local.grupo}/${proximaVersao(pastasDe(path.resolve(raiz, local.grupo)))}`;
+  criarPasta(path.resolve(raiz, pasta));
+  return ok(`${pasta}/${local.nome}`);
+}
+
+/** Regra 4: a versão mais nova que tem o arquivo; depois, o próprio grupo, sem pasta de versão. */
+function entrada(raiz, crew, { run, arquivo }) {
+  const local = naExecucao(arquivo, crew, run);
+  const { grupo, nome } = local ?? { grupo: path.posix.dirname(normalizar(arquivo)), nome: path.posix.basename(normalizar(arquivo)) };
+  const versoes = local ? daMaisNova(pastasDe(path.resolve(raiz, grupo))) : [];
+  const candidatos = [...versoes.map((versao) => `${grupo}/${versao}/${nome}`), local ? `${grupo}/${nome}` : normalizar(arquivo)];
+  const achado = candidatos.find((caminho) => temConteudo(path.resolve(raiz, caminho)));
+  return achado ? ok(achado) : falta(candidatos.at(-1));
+}
+
+/** Regra 5: o arquivo gravado existe, não está vazio e tem o que o contrato do passo pede. */
+function conferir(raiz, { arquivo, secoes, tldr }) {
+  const caminho = normalizar(arquivo);
+  const alvo = path.resolve(raiz, caminho);
+  if (!temConteudo(alvo)) return reprovado(MOTIVO.ausente);
+  const pedido = { secoes: secoes === undefined ? null : Number(secoes), tldr };
+  const motivo = pedido.secoes !== null || tldr ? motivoDeReprovacao(lerTexto(alvo), pedido) : null;
+  return motivo ? reprovado(motivo) : ok(caminho);
+}
+
+function responder(raiz, crew, args) {
+  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 pasta = `crews/${crew}/output/${args.run}`;
+  criarPasta(path.resolve(raiz, pasta));
+  return ok(pasta);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object} [deps] `cwd` (a pasta do projeto) e `escrever`
+ * @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:`)
+ */
+export function main(argv, deps = {}) {
+  const { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = deps;
+  const args = lerArgs(argv);
+  const local = localizar(cwd, args);
+  if (local.erro) {
+    escrever(USO);
+    escrever(local.erro);
+    return 1;
+  }
+  try {
+    escrever(responder(cwd, local.crew, args));
+    return 0;
+  } catch (erro) {
+    escrever(`Não consegui resolver o caminho: ${limpar(erro?.message ?? erro)}`);
+    return 1;
+  }
+}
+
+if (ehPrincipal(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/templates/_opencrew/core/scripts/escritorio/leitura.mjs

@@ -0,0 +1,31 @@
+// O que o `/estado` do escritório devolve: o estado de cada crew, lido do disco a cada pedido.
+// Só lê; quem grava `crews/<crew>/state.json` é o `estado.mjs`.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+const MARCA_DE_ORDEM = 0xfeff; // alguns editores e terminais gravam essa marca no início do arquivo
+
+/** O estado de uma crew, ou null: arquivo ausente, pela metade, inválido ou sem `agents` em lista. */
+async function lerCrew(raiz, crew) {
+  try {
+    const texto = await fs.readFile(path.join(raiz, 'crews', crew, 'state.json'), 'utf8');
+    const estado = JSON.parse(texto.charCodeAt(0) === MARCA_DE_ORDEM ? texto.slice(1) : texto);
+    return Array.isArray(estado?.agents) ? { crew, estado } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** `updatedAt` em milissegundos; ausente ou ilegível vale 0 (a crew vai para o fim). */
+const atualizadaEm = ({ estado }) => Date.parse(estado.updatedAt) || 0;
+
+/**
+ * As crews de `crews/` que têm estado legível, a de `updatedAt` mais recente primeiro. Os nomes
+ * vêm da pasta, nunca do pedido. Sem a pasta `crews/`, ou sem nenhum estado: lista vazia.
+ * @returns {Promise<Array<{ crew: string, estado: object }>>}
+ */
+export async function lerCrews(raiz) {
+  const nomes = await fs.readdir(path.join(raiz, 'crews')).catch(() => []);
+  const lidas = await Promise.all(nomes.sort().map((nome) => lerCrew(raiz, nome)));
+  return lidas.filter(Boolean).sort((a, b) => atualizadaEm(b) - atualizadaEm(a));
+}

package/templates/_opencrew/core/scripts/escritorio/porta.mjs

@@ -0,0 +1,98 @@
+// A porta do escritório: abrir, perguntar quem está numa porta ocupada e procurar a que serve.
+// Spec: fase-e1-escritorio-ao-vivo.md, regra 15 (repositório do OpenCrew).
+import http from 'node:http';
+import net from 'node:net';
+
+const LOCAL = '127.0.0.1';
+const ULTIMA_PORTA = 65535;
+// Quem responde na porta pode ser qualquer serviço: a resposta não é guardada sem limite.
+const TETO_DA_SONDA = 1_000_000;
+
+/**
+ * Alguém aceita conexão em 127.0.0.1:porta? No Windows, o `listen` em 127.0.0.1 abre por cima de
+ * quem escuta a mesma porta em 0.0.0.0 ou `::` e toma o tráfego local dele: só a conexão mostra
+ * que a porta tem dono. Porta livre recusa na hora; sem resposta dentro da espera, conta como livre.
+ */
+function alguemEscuta(porta, esperaMs = 1000) {
+  return new Promise((resolve) => {
+    const conexao = net.connect({ host: LOCAL, port: porta });
+    const fim = (escuta) => { conexao.destroy(); resolve(escuta); };
+    conexao.setTimeout(esperaMs, () => fim(false));
+    conexao.once('connect', () => fim(true)).once('error', () => fim(false));
+  });
+}
+
+/**
+ * Abre o servidor na porta, preso em 127.0.0.1.
+ * @returns {Promise<boolean>} true se subiu; false se a porta não pôde ser aberta (ocupada, por
+ *   quem quer que seja e em qualquer endereço, ou reservada pelo sistema). O mesmo servidor pode
+ *   tentar outra porta em seguida.
+ */
+export async function abrir(servidor, porta) {
+  if (porta !== 0 && await alguemEscuta(porta)) return false;
+  return new Promise((resolve) => {
+    const subiu = () => { servidor.off('error', falhou); resolve(true); };
+    const falhou = () => { servidor.off('listening', subiu); resolve(false); };
+    servidor.once('listening', subiu).once('error', falhou).listen(porta, LOCAL);
+  });
+}
+
+/** O `projeto` de uma resposta do `/estado`, ou null quando a resposta não é a de um escritório. */
+function projetoDaResposta(corpo) {
+  try {
+    const { projeto } = JSON.parse(corpo) ?? {};
+    return typeof projeto === 'string' ? projeto : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Junta o corpo da resposta e o entrega inteiro; cortada no meio ou acima do teto, entrega null. */
+function juntar(res, entregar) {
+  let corpo = '';
+  res.setEncoding('utf8');
+  res.on('data', (parte) => {
+    corpo += parte;
+    if (corpo.length > TETO_DA_SONDA) entregar(null);
+  });
+  res.on('end', () => entregar(corpo));
+  res.on('error', () => entregar(null));
+}
+
+/**
+ * Pergunta quem está na porta: `GET /estado`, com espera de até 1 s.
+ * @returns {Promise<string|null>} o `projeto` do escritório que respondeu; null para qualquer
+ *   outra resposta (outro serviço, erro, resposta grande demais) ou nenhuma dentro da espera
+ */
+export function sondar(porta, esperaMs = 1000) {
+  return new Promise((resolve) => {
+    const pedido = http.get({ host: LOCAL, port: porta, path: '/estado', agent: false }, (res) => juntar(res, fim));
+    const relogio = setTimeout(() => fim(null), esperaMs);
+    pedido.on('error', () => fim(null));
+    function fim(corpo) {
+      clearTimeout(relogio);
+      pedido.destroy();
+      resolve(corpo === null ? null : projetoDaResposta(corpo));
+    }
+  });
+}
+
+/**
+ * Procura a porta do escritório, de `inicial` em diante, em até `tentativas` portas. Porta que
+ * não abre é sondada: se quem responde é o escritório deste projeto, não sobe outro.
+ * @param {object} o
+ * @param {number} o.inicial primeira porta
+ * @param {string} o.projeto id deste projeto
+ * @param {(porta: number) => Promise<boolean>} o.abrir tenta abrir o servidor na porta
+ * @param {(porta: number) => Promise<string|null>} o.sondar o `projeto` de quem está na porta
+ * @returns {Promise<{ tipo: 'aberto'|'ja-aberto'|'sem-porta', porta?: number, ultima: number }>}
+ *   `ultima` é a última porta do intervalo (a que entra na mensagem "sem porta")
+ */
+export async function procurar({ inicial, projeto, abrir: tentar, sondar: perguntar, tentativas = 10 }) {
+  const ultima = Math.min(inicial + tentativas - 1, ULTIMA_PORTA);
+  for (let porta = inicial; porta <= ultima; porta++) {
+    if (await tentar(porta)) return { tipo: 'aberto', porta, ultima };
+    if ((await perguntar(porta)) === projeto) return { tipo: 'ja-aberto', porta, ultima };
+  }
+  return { tipo: 'sem-porta', ultima };
+}

package/templates/_opencrew/core/scripts/escritorio/projeto.mjs

@@ -0,0 +1,29 @@
+// Identidade do projeto para o escritório: diz se o servidor que responde numa porta é o deste
+// projeto, sem expor o caminho da pasta.
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 12 caracteres hexadecimais do SHA-256 do caminho real da raiz. No Windows o caminho vai para
+ * minúsculas antes: lá `D:\Projeto` e `d:\projeto` são a mesma pasta. Função pura.
+ */
+export function idDoProjeto(caminhoReal, plataforma = process.platform) {
+  const texto = plataforma === 'win32' ? caminhoReal.toLowerCase() : caminhoReal;
+  return createHash('sha256').update(texto).digest('hex').slice(0, 12);
+}
+
+/**
+ * Caminho real: o mesmo projeto aberto por um link de pasta dá o mesmo resultado. Onde o sistema
+ * não resolve (alguns discos virtuais), vale o caminho absoluto.
+ */
+function caminhoReal(raiz) {
+  try {
+    return realpathSync.native(raiz);
+  } catch {
+    return path.resolve(raiz);
+  }
+}
+
+/** O id do projeto que mora em `raiz`. */
+export const projetoDe = (raiz) => idDoProjeto(caminhoReal(raiz));

package/templates/_opencrew/core/scripts/escritorio/servidor.mjs

@@ -0,0 +1,78 @@
+// Servidor do escritório: só leitura, só neste computador, com rotas fechadas.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 13 a 15 (repositório do OpenCrew).
+import http from 'node:http';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { lerCrews } from './leitura.mjs';
+import { projetoDe } from './projeto.mjs';
+
+// Vão em TODA resposta. Nenhuma resposta leva `Access-Control-*`: outra origem não lê o estado.
+const CABECALHOS = {
+  'Cache-Control': 'no-store',
+  'X-Content-Type-Options': 'nosniff',
+  'Content-Security-Policy': "default-src 'self'; style-src 'self' 'unsafe-inline'",
+};
+const TEXTO = 'text/plain; charset=utf-8';
+const JSON_UTF8 = 'application/json; charset=utf-8';
+const TIPOS = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8' };
+const SEM_TIPO = 'application/octet-stream';
+
+const MSG_HOST = (porta) => `Abra por http://127.0.0.1:${porta}`;
+
+function responder(res, status, { corpo, tipo = TEXTO, extras = {} }) {
+  res.writeHead(status, { ...CABECALHOS, 'Content-Type': tipo, 'Content-Length': Buffer.byteLength(corpo), ...extras });
+  res.end(corpo);
+}
+
+/**
+ * O pedido veio para este endereço? Uma página de fora que aponte um nome dela para 127.0.0.1
+ * chega com o nome dela no `Host`; só valem `127.0.0.1` e `localhost`, com a porta real.
+ */
+function hostAceito(req) {
+  const porta = req.socket.localPort;
+  const host = String(req.headers.host ?? '').toLowerCase();
+  return host === `127.0.0.1:${porta}` || host === `localhost:${porta}`;
+}
+
+/** Arquivo da página pelo nome da lista; null quando o caminho não é rota ou o arquivo falta. */
+async function lerArquivo(ctx, caminho) {
+  const nome = ctx.rotas.get(caminho);
+  if (!nome) return null;
+  const corpo = await fs.readFile(path.join(ctx.pasta, nome)).catch(() => null);
+  return corpo && { corpo, tipo: TIPOS[path.extname(nome)] ?? SEM_TIPO };
+}
+
+async function atender(req, res, ctx) {
+  if (!hostAceito(req)) return responder(res, 421, { corpo: MSG_HOST(req.socket.localPort) });
+  if (req.method !== 'GET') return responder(res, 405, { corpo: 'Método não permitido', extras: { Allow: 'GET' } });
+  const caminho = req.url.split('?')[0];
+  if (caminho === '/estado') {
+    const corpo = JSON.stringify({ projeto: ctx.projeto, crews: await lerCrews(ctx.raiz) });
+    return responder(res, 200, { corpo, tipo: JSON_UTF8 });
+  }
+  const arquivo = await lerArquivo(ctx, caminho);
+  return arquivo ? responder(res, 200, arquivo) : responder(res, 404, { corpo: 'Não encontrado' });
+}
+
+function falhar(res) {
+  if (res.headersSent) res.destroy();
+  else responder(res, 500, { corpo: 'Erro interno' });
+}
+
+/**
+ * Cria o servidor (sem abrir a porta: quem abre é `abrir`, em `porta.mjs`).
+ * @param {object} o
+ * @param {string} o.raiz pasta do projeto (a que tem `_opencrew/` e `crews/`)
+ * @param {string} o.pasta pasta da página (`_opencrew/core/escritorio/`)
+ * @param {string[]} o.arquivos nomes servidos dessa pasta. É uma lista fixa: o caminho do pedido
+ *   é comparado com ela e nunca é juntado a uma pasta, e a pasta nunca é lida para montar rota
+ * @returns {import('node:http').Server}
+ */
+export function criarServidor({ raiz, pasta, arquivos }) {
+  const rotas = new Map([['/', 'index.html'], ...arquivos.map((nome) => [`/${nome}`, nome])]);
+  const ctx = { raiz, pasta, rotas, projeto: projetoDe(raiz) };
+  // Sem `Host` o pedido também chega aqui e leva o 421 com os cabeçalhos, e não o 400 do Node.
+  return http.createServer({ requireHostHeader: false }, (req, res) => {
+    atender(req, res, ctx).catch(() => falhar(res));
+  });
+}

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Escritório do OpenCrew — servidor local da página que mostra a equipe trabalhando.
+// Uso: node _opencrew/core/scripts/escritorio.mjs [--porta <1024 a 65535>]
+//   Rode na pasta do projeto (a que contém `_opencrew/`). Sem --porta, começa na 4747.
+// Só leitura e só neste computador: escuta em 127.0.0.1, aceita só GET e não escreve em disco.
+// Serve a página (`_opencrew/core/escritorio/`) e `GET /estado`, que lê `crews/*/state.json` a
+// cada pedido.
+// Porta ocupada: se quem responde nela é o escritório deste mesmo projeto, avisa e sai com 0, sem
+// subir outro; senão tenta a seguinte, até 10 portas ao todo.
+// Código de saída: 0 = escritório aberto (o processo segue rodando até Ctrl+C) ou já aberto ·
+// 1 = erro de uso (porta inválida, pasta sem `_opencrew/`) ou nenhuma das 10 portas livre.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 13 a 15 (repositório do OpenCrew).
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ehPrincipal } from './comum.mjs';
+import { criarServidor } from './escritorio/servidor.mjs';
+import { abrir, sondar, procurar } from './escritorio/porta.mjs';
+import { projetoDe } from './escritorio/projeto.mjs';
+
+/**
+ * Os arquivos da página, um a um: é a lista inteira do que o servidor entrega além de `/estado`.
+ * Arquivo novo em `_opencrew/core/escritorio/` só é servido depois de entrar aqui.
+ */
+export const ARQUIVOS = [
+  'index.html', 'app.js', 'painel.js', 'rotulos.js', 'cena.js',
+  'sprites.js', 'sprites-sala.js', 'sprites-mesa.js',
+  'modelo.js', 'modelo-mesas.js', 'modelo-textos.js', 'modelo-estado.js', 'modelo-agentes.js',
+  'modelo-visao.js', 'modelo-pagina.js', 'demo.js',
+  'escala.js', 'rota.js', 'animacao.js', 'quadro.js',
+];
+
+const PORTA_PADRAO = 4747;
+const PORTA_MINIMA = 1024;
+const PORTA_MAXIMA = 65535;
+
+// Instalado, este script fica em `_opencrew/core/scripts/` e a página em `_opencrew/core/escritorio/`.
+const PASTA_DA_PAGINA = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'escritorio');
+
+const endereco = (porta) => `http://127.0.0.1:${porta}`;
+
+const USO = `Uso: node _opencrew/core/scripts/escritorio.mjs [--porta <${PORTA_MINIMA} a ${PORTA_MAXIMA}>]`;
+const MSG = {
+  aberto: (porta) => `Escritório aberto em ${endereco(porta)} — Ctrl+C para fechar`,
+  jaAberto: (porta) => `O escritório já está aberto em ${endereco(porta)}`,
+  semPorta: (a, b) => `Não foi possível abrir o escritório: as portas ${a} a ${b} estão ocupadas. Use --porta.`,
+  foraDaRaiz: 'Rode este comando na pasta do projeto (a que contém _opencrew/).',
+  portaInvalida: `Porta inválida: use --porta com um número de ${PORTA_MINIMA} a ${PORTA_MAXIMA}.`,
+};
+
+const ehPasta = (p) => existsSync(p) && statSync(p).isDirectory();
+
+/**
+ * A porta pedida em `--porta N` ou `--porta=N` (a última vale); sem a opção, a padrão.
+ * @returns {number|null} null quando o valor não é um inteiro de 1024 a 65535
+ */
+function lerPorta(argv) {
+  let porta = PORTA_PADRAO;
+  for (let i = 0; i < argv.length; i++) {
+    const opcao = argv[i].match(/^--porta(?:=(.*))?$/s);
+    if (!opcao) continue;
+    const valor = opcao[1] ?? argv[++i] ?? '';
+    const numero = /^\d{1,5}$/.test(valor) ? Number(valor) : 0;
+    if (numero < PORTA_MINIMA || numero > PORTA_MAXIMA) return null;
+    porta = numero;
+  }
+  return porta;
+}
+
+/**
+ * Erro de uso, na ordem: porta inválida → pasta atual sem `_opencrew/`.
+ * @returns {string[]|null} as linhas em PT-BR, ou null quando está tudo certo
+ */
+function erroDeUso(porta, cwd) {
+  if (porta === null) return [MSG.portaInvalida, USO];
+  if (!ehPasta(path.join(cwd, '_opencrew'))) return [MSG.foraDaRaiz];
+  return null;
+}
+
+/**
+ * Sobe o escritório do projeto que mora em `cwd`, ou reconhece o que já está aberto.
+ * @param {string[]} argv argumentos da linha de comando
+ * @param {object} [o]
+ * @param {string} [o.cwd] pasta do projeto
+ * @param {(linha: string) => void} [o.escrever] recebe cada linha da saída
+ * @param {string} [o.pasta] pasta da página
+ * @param {string[]} [o.arquivos] nomes servidos da pasta da página
+ * @param {(servidor: object, porta: number) => Promise<boolean>} [o.abrir] SÓ PARA TESTE: tenta
+ *   abrir a porta (serve para simular portas ocupadas sem ocupá-las)
+ * @param {(porta: number) => Promise<string|null>} [o.sondar] SÓ PARA TESTE: o `projeto` de quem
+ *   responde na porta
+ * @returns {Promise<{ code: number, porta?: number, servidor?: import('node:http').Server }>}
+ *   `code` 0 com `porta` (escritório aberto ou já aberto) ou 1; `servidor` só quando este
+ *   comando abriu um — é ele que mantém o processo vivo
+ */
+export async function main(argv, o = {}) {
+  const { cwd = process.cwd(), escrever = (linha) => process.stdout.write(`${linha}\n`), pasta = PASTA_DA_PAGINA, arquivos = ARQUIVOS } = o;
+  const inicial = lerPorta(argv);
+  const erro = erroDeUso(inicial, cwd);
+  if (erro) {
+    erro.forEach((linha) => escrever(linha));
+    return { code: 1 };
+  }
+  const servidor = criarServidor({ raiz: cwd, pasta, arquivos });
+  const tentar = (porta) => (o.abrir ?? abrir)(servidor, porta);
+  const r = await procurar({ inicial, projeto: projetoDe(cwd), abrir: tentar, sondar: o.sondar ?? sondar });
+  if (r.tipo === 'sem-porta') {
+    escrever(MSG.semPorta(inicial, r.ultima));
+    return { code: 1 };
+  }
+  escrever(r.tipo === 'aberto' ? MSG.aberto(r.porta) : MSG.jaAberto(r.porta));
+  return r.tipo === 'aberto' ? { code: 0, porta: r.porta, servidor } : { code: 0, porta: r.porta };
+}
+
+if (ehPrincipal(import.meta.url)) {
+  main(process.argv.slice(2)).then(({ code }) => { process.exitCode = code; });
+}

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

@@ -0,0 +1,61 @@
+// Linha de comando do `estado.mjs`: a crew, o evento, as opções e a linha de uso.
+// Spec: fase-e1-escritorio-ao-vivo.md, §3 e regra 7 (repositório do OpenCrew).
+
+export const USO = 'Uso: node _opencrew/core/scripts/estado.mjs <crew> <evento> [opções]';
+
+/** Teto, em caracteres visíveis, de `--rotulo`, `--mensagem` e `--motivo`. */
+export const TETO = 120;
+
+const OPCAO = /^--(passos|n|agente|rotulo|mensagem|motivo)(?:=(.*))?$/s;
+const QUEBRA = /[\r\n\v\f\u0085\u2028\u2029]+/g;
+const segmentador = new Intl.Segmenter('pt', { granularity: 'grapheme' });
+
+/**
+ * Texto recebido é dado: fica numa linha (quebra de linha vira espaço) e com até 120 caracteres.
+ * O corte conta caracteres visíveis, por isso nunca parte um emoji ao meio. O laço para no 121º
+ * segmento: no Node 20 cada segmento guarda uma cópia da entrada, e guardar todos custaria caro.
+ */
+export function limparTexto(valor) {
+  const linha = String(valor).replace(QUEBRA, ' ').trim();
+  let fim = 0;
+  let visiveis = 0;
+  for (const { index, segment } of segmentador.segment(linha)) {
+    if (visiveis++ === TETO) break;
+    fim = index + segment.length;
+  }
+  return linha.slice(0, fim);
+}
+
+/** Inteiro a partir de 1; qualquer outra coisa é `null` (a opção não vale). */
+const inteiro = (valor) => (/^\d{1,9}$/.test(valor ?? '') && Number(valor) >= 1 ? Number(valor) : null);
+
+/** As opções como o núcleo as recebe: ausente ou inválida é `null` (número, agente) ou vazio (texto). */
+function converter(cru) {
+  return {
+    passos: inteiro(cru.passos),
+    n: inteiro(cru.n),
+    agente: limparTexto(cru.agente ?? '') || null,
+    rotulo: limparTexto(cru.rotulo ?? ''),
+    mensagem: limparTexto(cru.mensagem ?? ''),
+    motivo: limparTexto(cru.motivo ?? ''),
+  };
+}
+
+/**
+ * `argv` → `{ crew, evento, opcoes: { passos, n, agente, rotulo, mensagem, motivo } }`. Os dois
+ * primeiros argumentos soltos são a crew e o evento (indefinidos, se faltam). Opção vale como
+ * `--nome valor` e `--nome=valor`; opção sem valor (a última, ou seguida de outra opção) não
+ * consome o argumento seguinte.
+ */
+export function lerArgs(argv) {
+  const soltos = [];
+  const cru = {};
+  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) cru[nome] = colado;
+    else if (i + 1 < argv.length && !OPCAO.test(argv[i + 1])) cru[nome] = argv[++i];
+  }
+  const [crew, evento] = soltos.filter((s) => !s.startsWith('--'));
+  return { crew, evento, opcoes: converter(cru) };
+}

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

@@ -0,0 +1,53 @@
+// Leitura e gravação de `crews/<crew>/state.json`: inteira ou nenhuma.
+// Spec: fase-e1-escritorio-ao-vivo.md, regras 3 e 6 (repositório do OpenCrew).
+import { promises as fs } from 'node:fs';
+
+/** O Windows recusa a troca de nome com um destes códigos enquanto outro processo lê o arquivo. */
+const RECUSAS = ['EPERM', 'EBUSY', 'EACCES'];
+/** Depois da primeira tentativa: até 3 repetições, uma a cada 100 ms (cerca de 300 ms ao todo). */
+const REPETICOES = 3;
+const INTERVALO_MS = 100;
+
+const pausa = (ms) => new Promise((seguir) => { setTimeout(seguir, ms); });
+
+/** O estado gravado, ou `null` quando o arquivo falta ou está ilegível (pela metade, sem `agents` em lista). */
+export async function lerEstado(arquivo) {
+  try {
+    const estado = JSON.parse((await fs.readFile(arquivo, 'utf8')).replace(/^\uFEFF/, ''));
+    return Array.isArray(estado?.agents) ? estado : null;
+  } catch {
+    return null;
+  }
+}
+
+async function trocarNome(de, para, { renomear = fs.rename, esperar = pausa }) {
+  for (let repeticao = 0; ; repeticao++) {
+    try {
+      return await renomear(de, para);
+    } catch (erro) {
+      if (!RECUSAS.includes(erro?.code) || repeticao === REPETICOES) throw erro;
+      await esperar(INTERVALO_MS);
+    }
+  }
+}
+
+/**
+ * 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
+ * @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 = {}) {
+  const temporario = `${arquivo}.${process.pid}.tmp`;
+  try {
+    await fs.writeFile(temporario, `${JSON.stringify(estado, null, 2)}\n`);
+    await trocarNome(temporario, arquivo, deps);
+    return true;
+  } catch {
+    await fs.rm(temporario, { force: true }).catch(() => {});
+    return false;
+  }
+}