suite-timesheet-mcp 1.0.0

package/lib/ferramentas.js

@@ -0,0 +1,188 @@
+// Puro (cliente injetado). As seis tools do MCP e a sua execução.
+
+import { validarProposta } from './validar.js';
+
+const AVISO = 'Opera só no mês que a Folha de Horas mostra no Chrome. Nunca submete o mês, nunca muda o mês.';
+const WAIT_MAX_S = 290;
+// O cliente por defeito do SDK do MCP corta a chamada aos 60 s; 50 dá margem para a
+// tool responder antes disso. timeout_s continua a poder ser pedido até WAIT_MAX_S (o
+// Claude Code permite subir o timeout do cliente MCP quando isso for preciso).
+const TIMEOUT_TOOL_S = 50;
+// aplicar escreve linha a linha no Suite: pode demorar bem mais do que as outras tools.
+const TIMEOUT_APLICAR_S = 120;
+
+export const FERRAMENTAS = [
+  {
+    name: 'estado',
+    description: `Estado da ponte com o Chrome: se a Folha de Horas está aberta, que mês mostra, quantos projetos tem e se há um lote a correr. ${AVISO}`,
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'projetos',
+    description: `Projetos do dropdown da Folha de Horas, com option_id, nome e se a linha está trancada (aprovada). ${AVISO}`,
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'ler_mes',
+    description: `Lê as horas já lançadas no mês visível: uma linha por projeto com os dias preenchidos, o status e os totais por dia. ${AVISO}`,
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'propor',
+    description: `Propõe lançamentos para o mês visível. A extensão calcula o plano (criar/atualizar/apagar), abre o painel com a pré-visualização e devolve-a aqui; nada é escrito até o utilizador clicar Aplicar no painel. Depois chama "resultado" com o id. Com espelho: true, as linhas do Suite que não vierem na proposta são apagadas. ${AVISO}`,
+    inputSchema: {
+      type: 'object',
+      required: ['linhas'],
+      additionalProperties: false,
+      properties: {
+        linhas: {
+          type: 'array',
+          description: 'Uma entrada por projeto e dia. Várias entradas do mesmo projeto no mesmo dia são somadas.',
+          items: {
+            type: 'object',
+            required: ['date', 'hours'],
+            additionalProperties: false,
+            properties: {
+              option_id: { type: 'integer', description: 'id do projeto no dropdown (usa "projetos"). Exclusivo com project.' },
+              project: { type: 'string', description: 'nome do projeto como aparece no dropdown. Exclusivo com option_id.' },
+              date: { type: 'string', description: 'YYYY-MM-DD, dentro do mês visível' },
+              hours: { type: 'number', description: 'de 0,5 a 23,5 em passo de 0,5' },
+            },
+          },
+        },
+        espelho: { type: 'boolean', description: 'apaga do Suite o que não vier nas linhas (defeito: false)' },
+        nome: { type: 'string', description: 'rótulo que aparece no painel (ex.: "sprint 12")' },
+      },
+    },
+  },
+  {
+    name: 'aplicar',
+    description: `Escreve a proposta "id" no Suite através da extensão, sem esperar pelo clique em Aplicar no painel. Só chama esta tool depois de mostrares a pré-visualização ao utilizador e ele dar OK explícito no chat: essa aprovação, mais a aprovação desta tool no cliente MCP, é que substitui o clique no painel. Linhas trancadas e propostas bloqueadas são recusadas. ${AVISO}`,
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      additionalProperties: false,
+      properties: {
+        id: { type: 'string', description: 'id devolvido por "propor"' },
+        timeout_s: {
+          type: 'integer',
+          minimum: 1,
+          maximum: WAIT_MAX_S,
+          description: `segundos a esperar (defeito ${TIMEOUT_APLICAR_S}, máximo ${WAIT_MAX_S}); a escrita é linha a linha e pode ser lenta`,
+        },
+      },
+    },
+  },
+  {
+    name: 'resultado',
+    description: `Espera pela decisão do utilizador no painel para uma proposta: aplicado (com o relatório), cancelado (com o motivo), erro, ou pendente se o tempo esgotar (podes voltar a chamar). ${AVISO}`,
+    inputSchema: {
+      type: 'object',
+      required: ['id'],
+      additionalProperties: false,
+      properties: {
+        id: { type: 'string', description: 'id devolvido por "propor"' },
+        timeout_s: { type: 'integer', minimum: 1, maximum: WAIT_MAX_S, description: `segundos a esperar (defeito ${TIMEOUT_TOOL_S}, máximo ${WAIT_MAX_S})` },
+        fase: {
+          type: 'string',
+          enum: ['previa', 'final'],
+          description: 'que fase esperar (defeito "final"). Usa "previa" para recuperar a pré-visualização de um "propor" que ficou pendente.',
+        },
+      },
+    },
+  },
+];
+
+const erro = (code, message) => Object.assign(new Error(message), { code });
+
+// Um comando síncrono do ponto de vista da tool: ou há dados, ou é erro.
+async function dadosDe(cliente, corpo) {
+  const r = await cliente.comando(corpo);
+  if (!r.resultado) throw erro('ERR_PENDENTE', `O Chrome não respondeu a tempo ao comando ${r.id}. Confirma que a Folha de Horas está aberta e tenta de novo.`);
+  if (!r.resultado.ok) throw erro(r.resultado.erro.code, r.resultado.erro.message);
+  return { id: r.id, dados: r.resultado.dados };
+}
+
+// Forma de um resultado final (dados.fase === 'final'), partilhada por "propor" (quando a
+// previa se perdeu e o que chega já é o final) e por "resultado".
+const finalDe = (id, dados) => {
+  const { estado, report, motivo, erro: erroFinal } = dados;
+  if (estado === 'erro') return { id, estado: 'erro', erro: erroFinal };
+  return { id, estado, report, motivo };
+};
+
+export async function executar(nome, args = {}, cliente, { estadoServe } = {}) {
+  switch (nome) {
+    case 'estado': {
+      let e;
+      try {
+        e = await cliente.estado();
+      } catch (err) {
+        // O auto-arranque do mcp.js (ver lib/autoarranque.js) já tentou pôr o serve a
+        // responder antes disto. Se não conseguiu, por a porta estar ocupada por outro
+        // programa ou por o arranque ter falhado, esta tool não deve lançar: devolve o
+        // porquê para o Claude poder explicar ao utilizador em vez de um erro seco.
+        if (err.code === 'ERR_SERVE_EM_BAIXO' && (estadoServe?.estado === 'porta-ocupada' || estadoServe?.estado === 'falhou')) {
+          return { ponte: 'sem-serve', serve: estadoServe.estado, detalhe: estadoServe.detalhe };
+        }
+        throw err;
+      }
+      const base = {
+        ponte: e.ponte,
+        ano: e.contexto?.ano ?? null,
+        mes: e.contexto?.mes ?? null,
+        projetos: e.contexto?.projetos?.length ?? 0,
+        ultimo_mcp: e.ultimoMcp ?? null,
+      };
+      if (e.ponte !== 'ligada') return { ...base, lote_em_curso: null };
+      if (!e.contexto) {
+        // O serve reiniciou depois de a página ter carregado: a ponte está viva (o worker
+        // continua a fazer long-poll) mas perdeu o contexto. Um comando 'estado' ia dar
+        // ERR_SEM_CONTEXTO — não vale a pena tentar, e esta tool nunca deve lançar por isto.
+        return { ...base, lote_em_curso: null, aviso: 'sem contexto: recarrega a Folha de Horas' };
+      }
+      const { dados } = await dadosDe(cliente, { tipo: 'estado', timeout_s: 10 });
+      return { ...base, lote_em_curso: dados.loteEmCurso ?? null };
+    }
+    case 'projetos': return (await dadosDe(cliente, { tipo: 'projetos', timeout_s: 30 })).dados;
+    case 'ler_mes': return (await dadosDe(cliente, { tipo: 'ler', timeout_s: TIMEOUT_TOOL_S })).dados;
+    case 'propor': {
+      const proposta = validarProposta(args); // erro imediato e legível; o serve valida com o mês
+      const r = await cliente.comando({ tipo: 'propor', ...proposta, timeout_s: TIMEOUT_TOOL_S });
+      if (!r.resultado) return { id: r.id, estado: 'pendente' };
+      if (!r.resultado.ok) throw erro(r.resultado.erro.code, r.resultado.erro.message);
+      const { dados } = r.resultado;
+      // Normalmente chega logo a previa; se a previa se perdeu (ex.: o worker publicou logo o
+      // final) dados.fase já vem 'final' — devolve o estado final em vez de fingir "previa".
+      if (dados.fase !== 'previa') return finalDe(r.id, dados);
+      const { previa } = dados;
+      return { id: r.id, estado: 'previa', previa, bloqueio: previa?.bloqueio ?? null };
+    }
+    case 'aplicar': {
+      const id = String(args.id);
+      const timeoutS = Math.min(Number(args.timeout_s) || TIMEOUT_APLICAR_S, WAIT_MAX_S);
+      const r = await cliente.comando({ tipo: 'aplicar', proposta: id, timeout_s: timeoutS });
+      // "id" devolvido é sempre o da proposta (args.id), não o do comando aplicar em si: quem
+      // chamou não conhece nem precisa de conhecer o id interno deste comando de escrita.
+      if (!r.resultado) return { id, estado: 'pendente' };
+      if (!r.resultado.ok) throw erro(r.resultado.erro.code, r.resultado.erro.message);
+      const { dados } = r.resultado;
+      if (dados.estado === 'erro') return { id, estado: 'erro', erro: dados.erro };
+      return { id, estado: dados.estado, report: dados.report };
+    }
+    case 'resultado': {
+      const waitS = Math.min(Number(args.timeout_s) || TIMEOUT_TOOL_S, WAIT_MAX_S);
+      const fase = args.fase === 'previa' ? 'previa' : 'final';
+      const r = await cliente.resultado(String(args.id), waitS, fase);
+      if (!r.resultado) return { id: r.id, estado: 'pendente' };
+      if (!r.resultado.ok) return { id: r.id, estado: 'erro', erro: r.resultado.erro };
+      const { dados } = r.resultado;
+      if (fase === 'previa' && dados.fase === 'previa') {
+        return { id: r.id, estado: 'previa', previa: dados.previa, bloqueio: dados.previa?.bloqueio ?? null };
+      }
+      return finalDe(r.id, dados);
+    }
+    default:
+      throw erro('ERR_TOOL', `Tool desconhecida: ${nome}.`);
+  }
+}

package/lib/fila.js

@@ -0,0 +1,193 @@
+// Puro (relógio e ids injetáveis). Fila de comandos entre o MCP e o worker da extensão.
+// Um comando de cada vez chega ao worker; um propor só entra quando o anterior tem final.
+
+import { randomUUID } from 'node:crypto';
+
+const erro = (message, extra) => Object.assign(new Error(message), extra);
+
+const TIMEOUT_ENTREGA_DEFEITO_MS = 30 * 1000; // sem timeout_s no pedido, ver CONTRACT.md
+const PRAZO_PREVIA_MS = 120 * 1000; // entregue ao worker mas sem previa a tempo: dá-se como perdido
+
+export function criarFila({
+  agora = () => Date.now(),
+  ttlMs = 60 * 60 * 1000,
+  ponteVivaMs = 40 * 1000,
+  novoId = randomUUID,
+} = {}) {
+  const pendentes = [];              // comandos ainda não entregues
+  const registos = new Map();        // id -> { cmd, criadoEm, entregueEm, previa, final, timeoutMs }
+  const esperasWorker = [];          // { resolve, entregue, timer } à espera de comando
+  const esperasResultado = new Map(); // id -> [{ fase, resolve }]
+  let ultimoPoll = 0;
+
+  const proporAberto = () => {
+    for (const registo of registos.values()) {
+      if (registo.cmd.tipo === 'propor' && !registo.final) return registo.cmd.id;
+    }
+    return null;
+  };
+
+  const resolverEsperas = (id, fases, corpo) => {
+    const lista = esperasResultado.get(id) ?? [];
+    esperasResultado.set(id, lista.filter((espera) => {
+      if (!fases.includes(espera.fase)) return true;
+      espera.resolve(corpo);
+      return false;
+    }));
+  };
+
+  function expirar(id, registo, message) {
+    const final = { ok: false, erro: { code: 'ERR_EXPIRADO', message } };
+    registo.final = final;
+    if (!registo.previa) registo.previa = final;
+    resolverEsperas(id, ['previa', 'final'], final);
+  }
+
+  // Comandos por atraso (nunca entregues, ou entregues mas sem previa) tornam-se finais aqui,
+  // o que também liberta o próximo `propor` (proporAberto só olha a registos sem final). Depois
+  // de expirar, tira o id de `pendentes`: um id evictado ou já expirado ali dentro faria
+  // `proximo()` rebentar com TypeError ao tentar atualizar um registo que já não existe (ou que
+  // já está fechado). Por fim, o TTL apaga o que sobrou de há muito e já está fechado.
+  function limpar() {
+    const agoraMs = agora();
+
+    for (const [id, registo] of registos) {
+      if (registo.final) continue;
+      if (registo.entregueEm === null) {
+        if (agoraMs - registo.criadoEm > registo.timeoutMs) {
+          expirar(id, registo, `O comando ${id} não foi entregue à extensão a tempo (a ponte pode estar em baixo).`);
+        }
+      } else if (registo.cmd.tipo === 'propor' && !registo.previa && agoraMs - registo.entregueEm > PRAZO_PREVIA_MS) {
+        expirar(id, registo, `A extensão recebeu o comando ${id} mas não devolveu a pré-visualização a tempo; a proposta foi perdida.`);
+      }
+    }
+
+    for (let i = pendentes.length - 1; i >= 0; i--) {
+      const registo = registos.get(pendentes[i].id);
+      if (!registo || registo.final) pendentes.splice(i, 1);
+    }
+
+    const limite = agoraMs - ttlMs;
+    for (const [id, registo] of registos) {
+      const fechado = registo.final !== null || registo.cmd.tipo !== 'propor';
+      if (registo.criadoEm < limite && fechado) {
+        registos.delete(id);
+        esperasResultado.delete(id);
+      }
+    }
+  }
+
+  function enfileirar(cmd, { timeoutMs = TIMEOUT_ENTREGA_DEFEITO_MS } = {}) {
+    limpar();
+    if (cmd.tipo === 'propor') {
+      const aberto = proporAberto();
+      if (aberto) {
+        throw erro(`Já há uma proposta à espera de confirmação no painel (${aberto}).`, { code: 'ERR_OCUPADO', id: aberto });
+      }
+    }
+    const id = cmd.id ?? novoId();
+    const completo = { ...cmd, id };
+    registos.set(id, { cmd: completo, criadoEm: agora(), entregueEm: null, previa: null, final: null, timeoutMs });
+    const espera = esperasWorker.shift();
+    if (espera) {
+      clearTimeout(espera.timer);
+      registos.get(id).entregueEm = agora();
+      espera.entregue = completo;
+      espera.resolve(completo);
+    } else {
+      pendentes.push(completo);
+    }
+    return { id };
+  }
+
+  // Devolve { promessa, cancelar } em vez de só a promise: quem faz o long-poll (serve.js) tem
+  // de poder desistir se o socket do lado do worker fechar antes de a promise resolver. Se ainda
+  // não tinha comando, cancelar() só tira a espera da fila. Se já tinha (a promise resolveu mas o
+  // socket morreu antes de o serve conseguir escrever a resposta), cancelar() devolve o comando à
+  // cabeça de `pendentes` para não se perder — e por isso é preciso chamar cancelar() antes de
+  // outro `proximo()` reclamar o mesmo lugar, e só quando a resposta ainda não foi escrita.
+  function proximo(waitMs) {
+    limpar();
+    ultimoPoll = agora();
+    const espera = { resolve: null, entregue: null, timer: null };
+    const promessa = new Promise((resolve) => {
+      espera.resolve = resolve;
+      const cmd = pendentes.shift();
+      if (cmd) {
+        registos.get(cmd.id).entregueEm = agora();
+        espera.entregue = cmd;
+        resolve(cmd);
+        return;
+      }
+      esperasWorker.push(espera);
+      espera.timer = setTimeout(() => {
+        const i = esperasWorker.indexOf(espera);
+        if (i >= 0) {
+          esperasWorker.splice(i, 1);
+          resolve(null);
+        }
+      }, waitMs);
+      // Sem unref: no Node 20 o runner de testes termina com o event loop vazio e cancela
+      // promessas à espera de um timer unref'd. Os timers são curtos e limpos na resolução.
+    });
+    const cancelar = () => {
+      clearTimeout(espera.timer);
+      const i = esperasWorker.indexOf(espera);
+      if (i >= 0) {
+        esperasWorker.splice(i, 1);
+        return;
+      }
+      if (espera.entregue) {
+        const registo = registos.get(espera.entregue.id);
+        if (registo && !registo.final) {
+          registo.entregueEm = null;
+          pendentes.unshift(espera.entregue);
+        }
+        espera.entregue = null;
+      }
+    };
+    return { promessa, cancelar };
+  }
+
+  function publicar(id, corpo) {
+    const registo = registos.get(id);
+    if (!registo) return false;
+    const ehPrevia = corpo?.ok === true && corpo.dados?.fase === 'previa';
+    if (ehPrevia) {
+      registo.previa = corpo;
+      resolverEsperas(id, ['previa'], corpo);
+    } else {
+      registo.final = corpo;
+      // Um final sem previa (ex.: ERR_OCUPADO, ERR_SESSION) também liberta quem esperava pela previa.
+      if (!registo.previa) registo.previa = corpo;
+      resolverEsperas(id, ['previa', 'final'], corpo);
+    }
+    return true;
+  }
+
+  function resultado(id, waitMs, fase = 'final') {
+    limpar();
+    const registo = registos.get(id);
+    if (!registo) {
+      return Promise.reject(erro(`Comando ${id} desconhecido (o serve pode ter reiniciado).`, { code: 'ERR_COMANDO_DESCONHECIDO' }));
+    }
+    if (registo[fase]) return Promise.resolve(registo[fase]);
+    return new Promise((resolve) => {
+      const espera = { fase, resolve };
+      esperasResultado.set(id, [...(esperasResultado.get(id) ?? []), espera]);
+      const timer = setTimeout(() => {
+        const lista = esperasResultado.get(id) ?? [];
+        if (lista.includes(espera)) {
+          esperasResultado.set(id, lista.filter((e) => e !== espera));
+          resolve(null);
+        }
+      }, waitMs);
+    });
+  }
+
+  const ponteViva = () => agora() - ultimoPoll < ponteVivaMs;
+
+  const estado = () => ({ pendentes: pendentes.length, registos: registos.size, ultimoPoll, ponteViva: ponteViva() });
+
+  return { enfileirar, proximo, publicar, resultado, ponteViva, limpar, estado };
+}

package/lib/rotas.js

@@ -0,0 +1,148 @@
+// Puro (fila e contexto injetados). Um router sem http: recebe {metodo, caminho, query, corpo}
+// e devolve {status, corpo}. serve.js é a cola HTTP à volta disto.
+
+import { validarProposta } from './validar.js';
+
+const TIPOS = ['estado', 'projetos', 'ler', 'propor', 'aplicar'];
+// O Chrome mata um service worker MV3 cujo fetch demora mais de ~30 s: 25 é o wait que o
+// CONTRACT.md promete (worker pede wait=25) e o máximo que este serve aceita.
+const WAIT_BRIDGE_MAX_S = 25;
+const WAIT_MCP_MAX_S = 290; // o fetch do Node corta cabeçalhos aos 300 s
+const TIMEOUT_COMANDO_S = 30;
+// aplicar escreve linha a linha no Suite: pode demorar bem mais do que um comando normal.
+const TIMEOUT_APLICAR_DEFEITO_S = 120;
+
+const erro = (status, code, message) => ({ status, corpo: { erro: { code, message } } });
+const mesTexto = (ano, mes) => `${ano}-${String(mes).padStart(2, '0')}`;
+const inteiro = (v, defeito) => (Number.isFinite(Number(v)) ? Number(v) : defeito);
+const limitar = (v, max) => Math.max(0, Math.min(inteiro(v, max), max));
+
+export function criarRotas({ fila, contexto, log = () => {}, versao, agora = Date.now }) {
+  // Timestamp ISO do último pedido a qualquer rota /mcp/*, ou null se ainda não houve nenhum
+  // desde que este `serve` arrancou. É o que /health e /mcp/estado mostram como "ultimoMcp",
+  // para a extensão (painel) saber se o Claude ainda está a falar com o serviço.
+  let ultimoMcp = null;
+  const marcarMcp = () => { ultimoMcp = new Date(agora()).toISOString(); };
+
+  async function comando(corpo) {
+    if (!corpo || !TIPOS.includes(corpo.tipo)) return erro(400, 'ERR_COMANDO', `tipo tem de ser um de ${TIPOS.join(', ')}.`);
+    if (!fila.ponteViva()) {
+      return erro(409, 'ERR_SEM_CHROME', 'Abre a Folha de Horas do Suite no Chrome e espera uns segundos.');
+    }
+    const visivel = contexto.mesVisivel();
+    if (!visivel) {
+      // A ponte está viva (o worker está a fazer long-poll), mas o serve reiniciou depois de a
+      // página ter carregado: perdeu o contexto e ainda não houve recarregamento para o repor.
+      return erro(409, 'ERR_SEM_CONTEXTO', 'A ponte está ligada mas ainda não recebi o mês da página. Recarrega a Folha de Horas no Chrome.');
+    }
+    const ano = inteiro(corpo.ano, visivel.ano);
+    const mes = inteiro(corpo.mes, visivel.mes);
+    if (ano !== visivel.ano || mes !== visivel.mes) {
+      return erro(409, 'ERR_MES_DIFERENTE',
+        `A página mostra ${mesTexto(visivel.ano, visivel.mes)} e pediste ${mesTexto(ano, mes)}. Muda o mês na página do Suite.`);
+    }
+    let cmd = { tipo: corpo.tipo, ano, mes };
+    let proposta = null;
+    if (corpo.tipo === 'propor') {
+      try {
+        proposta = validarProposta(corpo, visivel);
+      } catch (e) {
+        return erro(400, e.code ?? 'ERR_PROPOSTA', e.message);
+      }
+      cmd = { ...cmd, ...proposta };
+    }
+    if (corpo.tipo === 'aplicar') {
+      // aplicar resolve um propor já enfileirado (pelo id da proposta), não cria um novo à
+      // espera de confirmação — por isso não passa por validarProposta nem por proporAberto.
+      if (typeof corpo.proposta !== 'string' || corpo.proposta.trim() === '') {
+        return erro(400, 'ERR_COMANDO', 'proposta tem de ser o id de uma proposta pendente (devolvido por "propor").');
+      }
+      cmd = { ...cmd, proposta: corpo.proposta };
+    }
+    // Quanto tempo este pedido HTTP espera sincronamente pelo resultado (0 é válido: "não
+    // bloqueies, dá-me pendente"). É distinto do prazo de entrega guardado na fila: um
+    // timeout_s pequeno (ou 0) não pode fazer o comando expirar antes de chegar a um worker —
+    // por isso o prazo de entrega tem sempre um mínimo de TIMEOUT_COMANDO_S. aplicar escreve
+    // linha a linha, por isso o seu defeito (sem timeout_s no pedido) é maior que o dos outros.
+    const defeitoTimeoutS = corpo.tipo === 'aplicar' ? TIMEOUT_APLICAR_DEFEITO_S : TIMEOUT_COMANDO_S;
+    const waitResultadoMs = limitar(corpo.timeout_s ?? defeitoTimeoutS, WAIT_MCP_MAX_S) * 1000;
+    const timeoutEntregaMs = Math.max(waitResultadoMs, TIMEOUT_COMANDO_S * 1000);
+    let id;
+    try {
+      ({ id } = fila.enfileirar(cmd, { timeoutMs: timeoutEntregaMs }));
+    } catch (e) {
+      return erro(409, e.code ?? 'ERR_OCUPADO', e.message);
+    }
+    // Só grava a proposta depois do enfileirar aceitar: se der ERR_OCUPADO, a proposta
+    // rejeitada não pode substituir a que já estava guardada para o /timesheet.
+    if (proposta) contexto.guardarProposta(ano, mes, proposta.linhas);
+    log(`comando ${id} ${cmd.tipo} ${mesTexto(ano, mes)}`);
+    const fase = cmd.tipo === 'propor' ? 'previa' : 'final';
+    const resultado = await fila.resultado(id, waitResultadoMs, fase);
+    return { status: 200, corpo: { id, estado: resultado ? 'concluido' : 'pendente', resultado } };
+  }
+
+  return async function despachar({ metodo, caminho, query = {}, corpo = null, aoFechar = () => {} }) {
+    if (metodo === 'GET' && caminho === '/health') {
+      // JSON (não texto) desde sempre: a extensão usa "nome" para distinguir este serve de
+      // qualquer outro programa na mesma porta — um corpo de texto passa a contar como isso.
+      return {
+        status: 200,
+        corpo: { nome: 'suite-timesheet-serve', versao, ultimoMcp, ponte: fila.ponteViva() ? 'ligada' : 'sem-chrome' },
+      };
+    }
+
+    if (metodo === 'GET' && caminho === '/timesheet') {
+      const year = inteiro(query.year, 0);
+      const month = inteiro(query.month, 0);
+      return { status: 200, corpo: { year, month, generated_at: new Date().toISOString(), rows: contexto.proposta(year, month) } };
+    }
+
+    if (metodo === 'POST' && caminho === '/bridge/contexto') {
+      if (!corpo || !Number.isInteger(corpo.ano) || !Number.isInteger(corpo.mes)) return erro(400, 'ERR_COMANDO', 'contexto sem ano/mes.');
+      contexto.guardar(corpo);
+      return { status: 204 };
+    }
+
+    if (metodo === 'GET' && caminho === '/bridge/next') {
+      const { promessa, cancelar } = fila.proximo(limitar(query.wait ?? WAIT_BRIDGE_MAX_S, WAIT_BRIDGE_MAX_S) * 1000);
+      // Dá ao serve.js uma forma de desistir se o socket do worker morrer antes desta promise
+      // resolver, para o comando (se já lhe tiver sido atribuído) não se perder (ver fila.js).
+      aoFechar(cancelar);
+      const cmd = await promessa;
+      return cmd ? { status: 200, corpo: cmd } : { status: 204 };
+    }
+
+    const resultadoDe = /^\/bridge\/result\/([^/]+)$/.exec(caminho);
+    if (metodo === 'POST' && resultadoDe) {
+      const id = decodeURIComponent(resultadoDe[1]);
+      const aceite = fila.publicar(id, corpo);
+      log(`resultado ${id} ${corpo?.ok ? 'ok' : corpo?.erro?.code ?? '?'}${corpo?.dados?.fase ? ` ${corpo.dados.fase}` : ''}`);
+      return aceite ? { status: 204 } : erro(404, 'ERR_COMANDO_DESCONHECIDO', `Comando ${id} desconhecido.`);
+    }
+
+    if (metodo === 'GET' && caminho === '/mcp/estado') {
+      marcarMcp();
+      return { status: 200, corpo: { ponte: fila.ponteViva() ? 'ligada' : 'sem-chrome', contexto: contexto.atual(), ultimoMcp } };
+    }
+
+    if (metodo === 'POST' && caminho === '/mcp/comando') {
+      marcarMcp();
+      return comando(corpo);
+    }
+
+    const comandoDe = /^\/mcp\/comando\/([^/]+)$/.exec(caminho);
+    if (metodo === 'GET' && comandoDe) {
+      marcarMcp();
+      const id = decodeURIComponent(comandoDe[1]);
+      try {
+        const resultado = await fila.resultado(id, limitar(query.wait ?? 0, WAIT_MCP_MAX_S) * 1000, query.fase === 'previa' ? 'previa' : 'final');
+        return { status: 200, corpo: { id, estado: resultado ? 'concluido' : 'pendente', resultado } };
+      } catch (e) {
+        return erro(404, e.code ?? 'ERR_COMANDO_DESCONHECIDO', e.message);
+      }
+    }
+
+    return erro(404, 'ERR_ROTA', `Não existe ${metodo} ${caminho}.`);
+  };
+}

package/lib/validar.js

@@ -0,0 +1,57 @@
+// Puro. Primeira validação de uma proposta, para o Claude ter um erro imediato e legível.
+// A extensão volta a validar (normalize/match): esta é a rede, aquela é a verdade.
+
+const DATA_ISO = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+const erroProposta = (problemas) => Object.assign(
+  new Error(`Proposta inválida:\n${problemas.join('\n')}`),
+  { code: 'ERR_PROPOSTA', problemas },
+);
+
+function dataValida(texto) {
+  const m = DATA_ISO.exec(String(texto ?? ''));
+  if (!m) return null;
+  const [ano, mes, dia] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const data = new Date(Date.UTC(ano, mes - 1, dia));
+  if (data.getUTCFullYear() !== ano || data.getUTCMonth() !== mes - 1 || data.getUTCDate() !== dia) return null;
+  return { ano, mes, dia };
+}
+
+export function validarProposta({ linhas, espelho = false, nome } = {}, mesVisivel = null) {
+  const problemas = [];
+  const lista = Array.isArray(linhas) ? linhas : [];
+  if (!Array.isArray(linhas)) problemas.push('"linhas" tem de ser um array.');
+  else if (linhas.length === 0 && espelho !== true) problemas.push('Sem linhas. Para limpar o mês usa espelho: true.');
+
+  const normalizadas = lista.map((linha, i) => {
+    const n = i + 1;
+    const temId = linha?.option_id !== undefined && linha.option_id !== null && linha.option_id !== '';
+    const temNome = typeof linha?.project === 'string' && linha.project.trim() !== '';
+    if (temId === temNome) problemas.push(`linha ${n}: indica exatamente um de option_id ou project.`);
+    if (temId && !(Number.isInteger(Number(linha.option_id)) && Number(linha.option_id) > 0)) {
+      problemas.push(`linha ${n}: option_id tem de ser um inteiro positivo.`);
+    }
+    const data = dataValida(linha?.date);
+    if (!data) problemas.push(`linha ${n}: date tem de ser YYYY-MM-DD e uma data real.`);
+    else if (mesVisivel && (data.ano !== mesVisivel.ano || data.mes !== mesVisivel.mes)) {
+      problemas.push(`linha ${n}: ${linha.date} está fora do mês visível ${mesVisivel.ano}-${String(mesVisivel.mes).padStart(2, '0')}.`);
+    }
+    const horas = Number(linha?.hours);
+    if (!Number.isFinite(horas) || horas <= 0 || horas > 23.5 || Math.round(horas * 2) !== horas * 2) {
+      problemas.push(`linha ${n}: hours tem de estar entre 0,5 e 23,5 em passo de 0,5.`);
+    }
+    return {
+      option_id: temId ? Number(linha.option_id) : '',
+      project: temNome ? linha.project.trim() : '',
+      date: String(linha?.date ?? ''),
+      hours: horas,
+    };
+  });
+
+  if (problemas.length > 0) throw erroProposta(problemas);
+  return {
+    linhas: normalizadas,
+    espelho: espelho === true,
+    nome: typeof nome === 'string' && nome.trim() ? nome.trim() : 'proposta do Claude',
+  };
+}

package/mcp.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Servidor MCP por stdio: cliente fino do serve. Nunca fala com o Suite.
+
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { FERRAMENTAS, executar } from './lib/ferramentas.js';
+import { criarCliente } from './lib/cliente.js';
+import { garantirServe } from './lib/autoarranque.js';
+
+const base = process.env.SUITE_TIMESHEET_BASE ?? 'http://127.0.0.1:18765';
+// Caminho absoluto do serve.js (irmão deste ficheiro): a mensagem de ERR_SERVE_EM_BAIXO diz
+// exatamente o que correr, sem o utilizador ter de adivinhar onde este pacote está instalado.
+const comandoArranque = `node ${fileURLToPath(new URL('./serve.js', import.meta.url))}`;
+const cliente = criarCliente({ base, comandoArranque });
+
+// Arranca o serve sozinho, salvo pedido em contrário (SUITE_TIMESHEET_SEM_AUTOARRANQUE=1):
+// no máximo ~3 s (garantirServe faz 15 tentativas de 200 ms) antes da ligação por stdio, para
+// nunca deixar o handshake do MCP pendurado à espera disto. Guarda-se o resultado para a tool
+// "estado" poder explicar um "porta-ocupada"/"falhou" em vez de só lançar ERR_SERVE_EM_BAIXO
+// (ver lib/ferramentas.js).
+let estadoServe;
+if (process.env.SUITE_TIMESHEET_SEM_AUTOARRANQUE !== '1') {
+  estadoServe = await garantirServe({ base });
+  console.error(`[suite-timesheet] serve: ${estadoServe.estado} em ${base}`);
+}
+
+const server = new Server(
+  { name: 'suite-timesheet', version: '1.0.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: FERRAMENTAS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (pedido) => {
+  try {
+    const r = await executar(pedido.params.name, pedido.params.arguments ?? {}, cliente, { estadoServe });
+    return { content: [{ type: 'text', text: JSON.stringify(r, null, 2) }] };
+  } catch (e) {
+    return { isError: true, content: [{ type: 'text', text: `${e.code ?? 'ERR'}: ${e.message}` }] };
+  }
+});
+
+await server.connect(new StdioServerTransport());