@aksp/opencrew 1.6.2 → 1.7.0

package/templates/_opencrew/core/scripts/conferir-fontes.mjs

@@ -6,27 +6,32 @@
 // Rode a partir da pasta do projeto (a que tem `_opencrew/`); a crew fica dentro dela.
 // Última linha da saída: FONTES:OK ou FONTES:PENDENTE (o runner lê esta linha).
 // Código de saída: 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso (opção faltando, pasta sem
-// `_opencrew/`, crew fora do projeto ou inexistente), sem linha FONTES: e sem escrever nada.
-// Specs: specs/fase-u2-crew-que-conhece-o-projeto.md e specs/fase-r1-reparos-1-6-1.md
-// (repositório do OpenCrew). Módulos em conferir-fontes/: coleta, busca e relatório.
+// `_opencrew/`, crew fora do projeto ou inexistente) ou arquivo da crew que não dá para ler
+// ("Não consegui conferir: …"); com código 1 não há linha FONTES:.
+// Caminho de rede e endereço de site citados não são testados (alerta "não conferi"); o script
+// nunca acessa a rede, e o --corrigir nunca grava fora da pasta real da crew.
+// Specs: specs/fase-u2-crew-que-conhece-o-projeto.md, specs/fase-r1-reparos-1-6-1.md e
+// specs/fase-r2-update-e-envio-seguros.md, regras 23 a 26 (repositório do OpenCrew).
+// Módulos em conferir-fontes/: coleta, busca e relatório.
 import { readFile, writeFile, copyFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { erroDeUso, dentroDoProjeto, ehPrincipal } from './comum.mjs';
+import { erroDeUso, dentroDoProjeto, relativoAoProjeto, realDentroDe, ehPrincipal } from './comum.mjs';
 import { coletar, trocarCitacao } from './conferir-fontes/coleta.mjs';
 import {
-  LIMITE_DA_BUSCA, barra, ehAbsoluto, temBarraFinal, resolver, indexar, candidatosPorNome, nomesDaPastaEsperada,
+  LIMITE_DA_BUSCA, ehAbsoluto, ehRedeOuSite, pareceSite, temBarraFinal, resolver, indexar, candidatosPorNome, nomesDaPastaEsperada,
 } from './conferir-fontes/busca.mjs';
 import { formatar, MSG } from './conferir-fontes/relatorio.mjs';
 
 export { formatar };
 
 /**
- * Caminho absoluto que existe dentro do projeto: o mesmo caminho, relativo à raiz. A própria raiz
- * não tem caminho relativo a sugerir.
+ * Caminho absoluto que existe dentro do projeto: o mesmo caminho, relativo à raiz — pelo lugar
+ * real, quando foi escrito por um link que leva ao projeto. A própria raiz não tem caminho
+ * relativo a sugerir.
  */
 function sugestaoRelativa(raiz, ref, achado) {
-  const relativo = dentroDoProjeto(raiz, achado) ? barra(path.relative(raiz, achado)) : '';
+  const relativo = dentroDoProjeto(raiz, achado) ? relativoAoProjeto(raiz, achado) : '';
   return relativo ? relativo + (temBarraFinal(ref) ? '/' : '') : null;
 }
 
@@ -43,27 +48,43 @@ async function procurar(item, { raiz, crew, indice, destino }) {
   if (!item.candidatos.length) item.pasta = await nomesDaPastaEsperada(raiz, crew, item.ref);
 }
 
+/**
+ * Estado de uma citação. Caminho de rede ou endereço de site não é testado: vira o alerta
+ * "não conferido" (regra 25). O resto é procurado no disco: o que falta é pendência, e o caminho
+ * absoluto que existe, o alerta de não portátil. `ctx.indice` é montado só na primeira falta.
+ */
+async function classificar(item, destino, ctx) {
+  const { raiz, crew } = ctx;
+  if (ehRedeOuSite(item.ref)) {
+    item.estado = 'nao-conferido';
+    return;
+  }
+  const achado = resolver(raiz, crew, item.ref, item.citadoEm);
+  if (!achado) {
+    ctx.indice ??= await indexar(raiz, ctx.limite);
+    if (pareceSite(ctx, item) && !candidatosPorNome(ctx.indice, item.ref).length) item.estado = 'nao-conferido';
+    else await procurar(item, { raiz, crew, indice: ctx.indice, destino });
+  } else if (ehAbsoluto(item.ref)) {
+    item.estado = 'nao-portatil';
+    item.sugestao = sugestaoRelativa(raiz, item.ref, achado);
+  }
+}
+
 /**
  * Confere os caminhos que a crew cita. `limite` é o máximo de itens do projeto vistos na busca
- * por nome; quando a busca para nele, `buscaParcial` é true.
+ * por nome; quando a busca para nele, `buscaParcial` é true. Estados: ok · faltando (pendência) ·
+ * nao-portatil e nao-conferido (alertas; não mudam o status).
  */
 export async function conferir({ raiz, crew, limite = LIMITE_DA_BUSCA }) {
-  let indice = null;
+  const ctx = { raiz, crew, limite, indice: null };
   const refs = [];
   for (const [ref, { arquivos, destino }] of await coletar(raiz, crew)) {
     const item = { ref, citadoEm: [...arquivos], estado: 'ok', sugestao: null, candidatos: [], pasta: [] };
-    const achado = resolver(raiz, crew, ref, item.citadoEm);
-    if (!achado) {
-      indice ??= await indexar(raiz, limite);
-      await procurar(item, { raiz, crew, indice, destino });
-    } else if (ehAbsoluto(ref)) {
-      item.estado = 'nao-portatil';
-      item.sugestao = sugestaoRelativa(raiz, ref, achado);
-    }
+    await classificar(item, destino, ctx);
     refs.push(item);
   }
   const status = refs.some((i) => i.estado === 'faltando') ? 'PENDENTE' : 'OK';
-  return { crew, raiz, refs, status, buscaParcial: Boolean(indice?.parcial), limite };
+  return { crew, raiz, refs, status, buscaParcial: Boolean(ctx.indice?.parcial), limite };
 }
 
 async function copiaDeSeguranca(arquivo) {
@@ -71,38 +92,69 @@ async function copiaDeSeguranca(arquivo) {
   await copyFile(arquivo, bak);
 }
 
+/** Regrava a citação num arquivo; a cópia .bak é feita uma vez por arquivo. */
+async function regravar(arquivo, item, tocados) {
+  const texto = await readFile(arquivo, 'utf8');
+  if (!tocados.has(arquivo)) {
+    await copiaDeSeguranca(arquivo);
+    tocados.add(arquivo);
+  }
+  await writeFile(arquivo, trocarCitacao(texto, item, path.basename(arquivo) === 'crew.yaml'));
+}
+
+/**
+ * Guarda de escrita do --corrigir (regra 24): só se grava em arquivo cujo lugar real fica dentro
+ * da pasta real da crew, e só se ela fica dentro do projeto. A pasta do arquivo passa pela mesma
+ * prova: é nela que a cópia .bak é gravada. Link físico não é reconhecido.
+ * @returns {((arquivo: string) => boolean)|null} null: a crew inteira é um link para fora do projeto
+ */
+function guardaDeEscrita(raiz, crew) {
+  const pasta = path.resolve(raiz, crew);
+  if (!realDentroDe(raiz, pasta)) return null;
+  return (arquivo) => [arquivo, path.dirname(arquivo)].every((lugar) => realDentroDe(pasta, lugar));
+}
+
 /**
  * Troca, nos arquivos da crew, cada caminho com sugestão única — só a citação que a coleta leu,
- * nunca um pedaço de outro texto. @returns quantos caminhos
+ * nunca um pedaço de outro texto. O que a guarda de escrita barra não muda: `avisar` recebe uma
+ * linha por arquivo pulado, ou uma só quando a crew inteira é um link para fora do projeto.
+ * @returns quantos caminhos foram gravados, em ao menos um arquivo
  */
-export async function corrigir({ resultado }) {
+export async function corrigir({ resultado, avisar = () => {} }) {
+  const { raiz, crew } = resultado;
   const comSugestao = resultado.refs.filter((i) => i.sugestao && i.estado !== 'ok');
+  const podeGravar = comSugestao.length ? guardaDeEscrita(raiz, crew) : null;
+  if (!podeGravar) {
+    if (comSugestao.length) avisar(MSG.crewLigadaParaFora(crew));
+    return 0;
+  }
   const tocados = new Set();
+  const pulados = new Set();
+  let gravados = 0;
   for (const item of comSugestao) {
-    for (const arquivo of item.citadoEm) {
-      const texto = await readFile(arquivo, 'utf8');
-      if (!tocados.has(arquivo)) {
-        await copiaDeSeguranca(arquivo);
-        tocados.add(arquivo);
-      }
-      await writeFile(arquivo, trocarCitacao(texto, item, path.basename(arquivo) === 'crew.yaml'));
-    }
+    const dentro = item.citadoEm.filter((arquivo) => podeGravar(arquivo));
+    for (const arquivo of item.citadoEm) if (!dentro.includes(arquivo)) pulados.add(arquivo);
+    for (const arquivo of dentro) await regravar(arquivo, item, tocados);
+    if (dentro.length) gravados += 1;
   }
-  return comSugestao.length;
+  for (const arquivo of pulados) avisar(MSG.linkParaFora(relativoAoProjeto(raiz, arquivo)));
+  return gravados;
 }
 
-/** --corrigir: troca o que tem sugestão única e diz quantas pendências ficam sem correção. */
+/** --corrigir: troca o que tem sugestão única, diz o que pulou e quantas pendências ficam sem correção. */
 async function corrigirEAvisar(r, escrever) {
-  const n = await corrigir({ resultado: r });
+  const pulados = [];
+  const n = await corrigir({ resultado: r, avisar: (linha) => pulados.push(linha) });
   let atual = r;
   if (n) {
     escrever(MSG.corrigidos(n));
     atual = await conferir({ raiz: r.raiz, crew: r.crew });
     escrever(formatar(atual));
   }
+  for (const linha of pulados) escrever(linha);
   const semSugestao = atual.refs.filter((i) => i.estado === 'faltando' && !i.sugestao).length;
   if (semSugestao) escrever(MSG.semCorrecaoAutomatica(semSugestao));
-  else if (!n) escrever(MSG.nadaACorrigir);
+  else if (!n && !pulados.length) escrever(MSG.nadaACorrigir);
   return atual;
 }
 
@@ -114,7 +166,7 @@ function lerCrew(argv) {
   return valor && !valor.startsWith('--') ? valor : null;
 }
 
-/** @returns {Promise<number>} 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso */
+/** @returns {Promise<number>} 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso, ou arquivo da crew que não dá para ler */
 export async function main(argv, { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = {}) {
   const crew = lerCrew(argv);
   const erro = erroDeUso({ raiz: cwd, faltando: crew ? [] : ['--crew'], crew });
@@ -123,11 +175,17 @@ export async function main(argv, { cwd = process.cwd(), escrever = (s) => proces
     if (!crew) escrever(USO);
     return 1;
   }
-  let r = await conferir({ raiz: cwd, crew });
-  escrever(formatar(r));
-  if (argv.includes('--corrigir')) r = await corrigirEAvisar(r, escrever);
-  escrever(`FONTES:${r.status}`);
-  return 0;
+  try {
+    let r = await conferir({ raiz: cwd, crew });
+    escrever(formatar(r));
+    if (argv.includes('--corrigir')) r = await corrigirEAvisar(r, escrever);
+    escrever(`FONTES:${r.status}`);
+    return 0;
+  } catch (erroDeLeitura) {
+    // Link quebrado, pasta com nome de arquivo, arquivo sem permissão: uma linha, sem linha FONTES:.
+    escrever(MSG.naoConferi(erroDeLeitura.message));
+    return 1;
+  }
 }
 
 if (ehPrincipal(import.meta.url)) {

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) };
+}