expxdev 0.4.0 → 0.5.0

package/dist/watch/terminal/restaurar.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Devolver o terminal ao estado anterior — sempre, por qualquer caminho.
+ *
+ * "Nunca deixa o terminal quebrado" é definição de pronto do usuário. O
+ * precedente do painel (`src/cli/principal.ts`) cobre `SIGINT` e `SIGTERM`,
+ * o que basta para um servidor HTTP; aqui escondemos o cursor, e uma exceção
+ * não capturada deixaria o terminal sem cursor até o próximo `reset`. Daí os
+ * quatro caminhos (decisão D-21).
+ */
+/** Os quatro caminhos pelos quais o watch pode terminar. */
+export declare const CAMINHOS_DE_SAIDA: readonly ["SIGINT", "SIGTERM", "uncaughtException", "exit"];
+export type CaminhoDeSaida = (typeof CAMINHOS_DE_SAIDA)[number];
+export type Ambiente = {
+    escrever: (texto: string) => void;
+    sair: (codigo: number) => void;
+};
+export type Restaurador = {
+    registrar: () => void;
+    desregistrar: () => void;
+    esconderCursor: () => void;
+    /** Executa a restauração. Idempotente. */
+    disparar: (caminho: CaminhoDeSaida) => void;
+};
+export declare function criarRestaurador(amb: Ambiente): Restaurador;

package/dist/watch/terminal/restaurar.js

@@ -0,0 +1,58 @@
+/**
+ * Devolver o terminal ao estado anterior — sempre, por qualquer caminho.
+ *
+ * "Nunca deixa o terminal quebrado" é definição de pronto do usuário. O
+ * precedente do painel (`src/cli/principal.ts`) cobre `SIGINT` e `SIGTERM`,
+ * o que basta para um servidor HTTP; aqui escondemos o cursor, e uma exceção
+ * não capturada deixaria o terminal sem cursor até o próximo `reset`. Daí os
+ * quatro caminhos (decisão D-21).
+ */
+const ESC = "";
+const MOSTRAR_CURSOR = `${ESC}[?25h`;
+const ESCONDER_CURSOR = `${ESC}[?25l`;
+/** Os quatro caminhos pelos quais o watch pode terminar. */
+export const CAMINHOS_DE_SAIDA = [
+    "SIGINT",
+    "SIGTERM",
+    "uncaughtException",
+    "exit",
+];
+export function criarRestaurador(amb) {
+    let restaurado = false;
+    const ouvintes = new Map();
+    function restaurar() {
+        if (restaurado)
+            return; // idempotente: dois sinais não restauram duas vezes
+        restaurado = true;
+        amb.escrever(MOSTRAR_CURSOR + "\n");
+    }
+    function disparar(caminho) {
+        restaurar();
+        // `exit` já está saindo, e em `uncaughtException` quem decide é o Node.
+        // Só os dois sinais precisam encerrar o processo por conta própria.
+        if (caminho === "SIGINT" || caminho === "SIGTERM")
+            amb.sair(0);
+    }
+    return {
+        registrar() {
+            for (const caminho of CAMINHOS_DE_SAIDA) {
+                const ouvinte = () => {
+                    disparar(caminho);
+                };
+                ouvintes.set(caminho, ouvinte);
+                process.on(caminho, ouvinte);
+            }
+        },
+        desregistrar() {
+            for (const [caminho, ouvinte] of ouvintes) {
+                process.off(caminho, ouvinte);
+            }
+            ouvintes.clear();
+        },
+        esconderCursor() {
+            amb.escrever(ESCONDER_CURSOR);
+        },
+        disparar,
+    };
+}
+//# sourceMappingURL=restaurar.js.map

package/dist/watch/terminal/restaurar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restaurar.js","sourceRoot":"","sources":["../../../src/watch/terminal/restaurar.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,GAAG,GAAG,GAAG,CAAC;AAChB,MAAM,cAAc,GAAG,GAAG,GAAG,OAAO,CAAC;AACrC,MAAM,eAAe,GAAG,GAAG,GAAG,OAAO,CAAC;AAEtC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ;IACR,SAAS;IACT,mBAAmB;IACnB,MAAM;CACE,CAAC;AAiBX,MAAM,UAAU,gBAAgB,CAAC,GAAa;IAC5C,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA8B,CAAC;IAEvD,SAAS,SAAS;QAChB,IAAI,UAAU;YAAE,OAAO,CAAC,oDAAoD;QAC5E,UAAU,GAAG,IAAI,CAAC;QAClB,GAAG,CAAC,QAAQ,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,SAAS,QAAQ,CAAC,OAAuB;QACvC,SAAS,EAAE,CAAC;QACZ,wEAAwE;QACxE,oEAAoE;QACpE,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,OAAO;QACL,SAAS;YACP,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;gBACxC,MAAM,OAAO,GAAG,GAAS,EAAE;oBACzB,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACpB,CAAC,CAAC;gBACF,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC/B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,YAAY;YACV,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;gBAC1C,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChC,CAAC;YACD,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QAED,cAAc;YACZ,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QAChC,CAAC;QAED,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/watch/terminal/tela.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A tela: redesenho incremental, sem piscar.
+ *
+ * "Redesenho não pode piscar a tela inteira." Limpar tudo e reimprimir produz
+ * exatamente o piscar que a especificação proíbe, e o buffer alternativo do
+ * terminal foi descartado por apagar o que estava na tela quando o watch sai
+ * (decisão D-20).
+ *
+ * A técnica: guardamos as linhas do último desenho, comparamos com as novas e
+ * reescrevemos SÓ as que mudaram, movendo o cursor até cada uma.
+ */
+export type Tela = {
+    desenhar: (linhas: readonly string[]) => void;
+    /** Quantas linhas a tela ocupa agora — para quem precisa arrumar o cursor. */
+    altura: () => number;
+};
+export declare function criarTela(escrever: (texto: string) => void): Tela;

package/dist/watch/terminal/tela.js

@@ -0,0 +1,64 @@
+/**
+ * A tela: redesenho incremental, sem piscar.
+ *
+ * "Redesenho não pode piscar a tela inteira." Limpar tudo e reimprimir produz
+ * exatamente o piscar que a especificação proíbe, e o buffer alternativo do
+ * terminal foi descartado por apagar o que estava na tela quando o watch sai
+ * (decisão D-20).
+ *
+ * A técnica: guardamos as linhas do último desenho, comparamos com as novas e
+ * reescrevemos SÓ as que mudaram, movendo o cursor até cada uma.
+ */
+const ESC = "";
+/** Move o cursor N linhas para cima. */
+const sobe = (n) => (n > 0 ? `${ESC}[${String(n)}A` : "");
+/** Move o cursor N linhas para baixo. */
+const desce = (n) => (n > 0 ? `${ESC}[${String(n)}B` : "");
+/** Começo da linha. */
+const COLUNA_1 = `${ESC}[G`;
+/** Apaga da posição do cursor até o fim da linha. */
+const LIMPA_LINHA = `${ESC}[K`;
+export function criarTela(escrever) {
+    let anteriores = [];
+    // Onde o cursor está, contando do topo do bloco desenhado.
+    let cursor = 0;
+    function irPara(linha) {
+        const delta = linha - cursor;
+        cursor = linha;
+        return delta > 0 ? desce(delta) : sobe(-delta);
+    }
+    return {
+        altura: () => anteriores.length,
+        desenhar(linhas) {
+            const novas = [...linhas];
+            const partes = [];
+            const alturaAnterior = anteriores.length;
+            const total = Math.max(novas.length, alturaAnterior);
+            for (let i = 0; i < total; i++) {
+                const nova = novas[i];
+                const velha = anteriores[i];
+                if (nova === velha)
+                    continue; // não mudou: não reescreve
+                partes.push(irPara(i), COLUNA_1);
+                // A tela encolheu? A linha que sobrou é apagada, não deixada para trás.
+                partes.push(nova === undefined ? LIMPA_LINHA : nova + LIMPA_LINHA);
+            }
+            if (partes.length === 0)
+                return; // nada mudou: nada a escrever
+            // Deixa o cursor logo abaixo do bloco, onde o próximo desenho o espera.
+            const fim = Math.max(0, novas.length - 1);
+            partes.push(irPara(fim));
+            // A primeira renderização precisa das quebras de linha para o bloco
+            // existir; a partir daí é só movimento de cursor.
+            if (alturaAnterior === 0) {
+                escrever(novas.join("\n"));
+                cursor = fim;
+            }
+            else {
+                escrever(partes.join(""));
+            }
+            anteriores = novas;
+        },
+    };
+}
+//# sourceMappingURL=tela.js.map

package/dist/watch/terminal/tela.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tela.js","sourceRoot":"","sources":["../../../src/watch/terminal/tela.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,GAAG,GAAG,GAAG,CAAC;AAChB,wCAAwC;AACxC,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC1E,yCAAyC;AACzC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC3E,uBAAuB;AACvB,MAAM,QAAQ,GAAG,GAAG,GAAG,IAAI,CAAC;AAC5B,qDAAqD;AACrD,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,CAAC;AAQ/B,MAAM,UAAU,SAAS,CAAC,QAAiC;IACzD,IAAI,UAAU,GAAa,EAAE,CAAC;IAC9B,2DAA2D;IAC3D,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,SAAS,MAAM,CAAC,KAAa;QAC3B,MAAM,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;QAC7B,MAAM,GAAG,KAAK,CAAC;QACf,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;IAED,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM;QAE/B,QAAQ,CAAC,MAAM;YACb,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;YAC1B,MAAM,MAAM,GAAa,EAAE,CAAC;YAE5B,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC;YACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YAErD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACtB,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;gBAC5B,IAAI,IAAI,KAAK,KAAK;oBAAE,SAAS,CAAC,2BAA2B;gBAEzD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBACjC,wEAAwE;gBACxE,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC;YACrE,CAAC;YAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,CAAC,8BAA8B;YAE/D,wEAAwE;YACxE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAEzB,oEAAoE;YACpE,kDAAkD;YAClD,IAAI,cAAc,KAAK,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC3B,MAAM,GAAG,GAAG,CAAC;YACf,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAC5B,CAAC;YAED,UAAU,GAAG,KAAK,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/watch/visao/escolher.d.ts

@@ -0,0 +1,18 @@
+import type { TrabalhoMontado } from "../../parser/projeto/montar.js";
+import type { EstadoExpx } from "../fontes/estado-schema.js";
+/**
+ * Qual trabalho o watch segue.
+ *
+ * O `estado.json` responde isso direto, no campo `trabalho`. O problema é o
+ * modo degradado: nenhum campo do plano marca um trabalho como "o atual"
+ * (lacuna L-01). A decisão D-05 fixou a derivação, e ela mora aqui.
+ *
+ * A ordem de precedência é deliberada:
+ *
+ *  1. o id que a pessoa pediu na linha de comando — se ela nomeou, é esse;
+ *  2. o `trabalho` do `estado.json`, quando ele existe e é válido;
+ *  3. a derivação do plano: `em_andamento`, desempatado por `atualizado_em`.
+ */
+/** Trabalho aberto é todo status diferente de `concluido` (decisão D-16). */
+export declare function abertos(trabalhos: readonly TrabalhoMontado[]): TrabalhoMontado[];
+export declare function escolherTrabalho(trabalhos: readonly TrabalhoMontado[], estado: EstadoExpx | null, pedido?: string): TrabalhoMontado | null;

package/dist/watch/visao/escolher.js

@@ -0,0 +1,57 @@
+/**
+ * Qual trabalho o watch segue.
+ *
+ * O `estado.json` responde isso direto, no campo `trabalho`. O problema é o
+ * modo degradado: nenhum campo do plano marca um trabalho como "o atual"
+ * (lacuna L-01). A decisão D-05 fixou a derivação, e ela mora aqui.
+ *
+ * A ordem de precedência é deliberada:
+ *
+ *  1. o id que a pessoa pediu na linha de comando — se ela nomeou, é esse;
+ *  2. o `trabalho` do `estado.json`, quando ele existe e é válido;
+ *  3. a derivação do plano: `em_andamento`, desempatado por `atualizado_em`.
+ */
+/** Trabalho aberto é todo status diferente de `concluido` (decisão D-16). */
+export function abertos(trabalhos) {
+    return trabalhos.filter((t) => t.status !== "concluido");
+}
+/** O mais recentemente atualizado. Empate de data mantém a ordem recebida. */
+function maisRecente(lista) {
+    let melhor = null;
+    for (const t of lista) {
+        // `atualizado_em` é AAAA-MM-DD (R4): comparação lexicográfica é cronológica
+        if (melhor === null || t.atualizado_em > melhor.atualizado_em)
+            melhor = t;
+    }
+    return melhor;
+}
+export function escolherTrabalho(trabalhos, estado, pedido) {
+    const por = (id) => trabalhos.find((t) => t.trabalho_id === id) ?? null;
+    // 1. `expx watch <trabalho_id>`: a pessoa mandou, acabou a discussão.
+    if (pedido !== undefined && pedido !== "")
+        return por(pedido);
+    // 2. O estado.json, quando pôde ser lido.
+    if (estado?.trabalho != null) {
+        const doEstado = por(estado.trabalho);
+        // O estado pode apontar um trabalho que não está no disco observado
+        // (pasta apagada, outro repositório). Nesse caso a derivação assume.
+        if (doEstado !== null)
+            return doEstado;
+    }
+    // 3. Derivação do plano (D-05): entre os em andamento, o mais recente.
+    const emAndamento = trabalhos.filter((t) => t.status === "em_andamento");
+    if (emAndamento.length > 0)
+        return maisRecente(emAndamento);
+    // Nenhum em andamento: o mais recente entre os abertos ainda é melhor
+    // resposta que nada — um trabalho bloqueado é exatamente o que a pessoa
+    // precisa ver.
+    const aberto = maisRecente(abertos(trabalhos));
+    if (aberto !== null)
+        return aberto;
+    // Nada aberto, mas existe trabalho concluído? Mostramos o mais recente.
+    // "Nenhum trabalho aberto" (D-19) é sobre a LISTA de acompanhamento; abrir o
+    // watch num projeto cujo único trabalho acabou de fechar e ver a tela vazia
+    // seria esconder justamente o que a pessoa quer conferir.
+    return maisRecente(trabalhos);
+}
+//# sourceMappingURL=escolher.js.map

package/dist/watch/visao/escolher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escolher.js","sourceRoot":"","sources":["../../../src/watch/visao/escolher.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CAAC,SAAqC;IAC3D,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC;AAC3D,CAAC;AAED,8EAA8E;AAC9E,SAAS,WAAW,CAAC,KAAiC;IACpD,IAAI,MAAM,GAA2B,IAAI,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,4EAA4E;QAC5E,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa;YAAE,MAAM,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAqC,EACrC,MAAyB,EACzB,MAAe;IAEf,MAAM,GAAG,GAAG,CAAC,EAAU,EAA0B,EAAE,CACjD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;IAEtD,sEAAsE;IACtE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC;IAE9D,0CAA0C;IAC1C,IAAI,MAAM,EAAE,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACtC,oEAAoE;QACpE,qEAAqE;QACrE,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,QAAQ,CAAC;IACzC,CAAC;IAED,uEAAuE;IACvE,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,cAAc,CAAC,CAAC;IACzE,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;IAE5D,sEAAsE;IACtE,wEAAwE;IACxE,eAAe;IACf,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/C,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAEnC,wEAAwE;IACxE,6EAA6E;IAC7E,4EAA4E;IAC5E,0DAA0D;IAC1D,OAAO,WAAW,CAAC,SAAS,CAAC,CAAC;AAChC,CAAC"}

package/dist/watch/visao/projetar.d.ts

@@ -0,0 +1,51 @@
+import { type BloqueioSituado, type TrabalhoMontado } from "../../parser/projeto/montar.js";
+import type { LinhaEvento } from "../../parser/esquema/evento.js";
+import type { EstadoExpx } from "../fontes/estado-schema.js";
+/**
+ * A visão que o desenho consome — as três fontes reunidas numa estrutura só.
+ *
+ * O parser do painel é reaproveitado inteiro, sem refatoração: `montarProjeto`
+ * é função pura de sistema de arquivos, sem acoplamento a HTTP ou websocket
+ * (base/parser-de-artefatos.md, decisão D-02). O que se acrescenta aqui é o
+ * que ele não sabe: o `estado.json` e o rastro.
+ */
+export type Visao = {
+    /** O trabalho que o watch está seguindo, ou `null` se não há nenhum. */
+    trabalho: TrabalhoMontado | null;
+    /** Os trabalhos abertos, para `--todos` e para a tela de "nenhum trabalho". */
+    abertos: TrabalhoMontado[];
+    /** O `estado.json`, ou `null` quando ausente, inválido ou de versão futura. */
+    estado: EstadoExpx | null;
+    /**
+     * Estamos sem o `estado.json`?
+     *
+     * NÃO é "o arquivo não existe": a decisão D-12 trata versão ≠ 1 e JSON
+     * inválido do mesmo jeito. No modo degradado, `raio`, `orcamento_*`, `branch`
+     * e `pr_estado` não têm fonte alguma e não podem ser exibidos — nenhum kind
+     * do `expx-schema` os declara (base/estado-json.md, risco 2).
+     */
+    degradado: boolean;
+    /** Tasks concluídas e total, do estado quando há, do plano quando não há. */
+    concluidas: number;
+    total: number;
+    /** Só os bloqueios abertos, que são os que sobem ao topo. */
+    bloqueiosAbertos: BloqueioSituado[];
+    /** As últimas linhas do rastro, da mais recente para a mais antiga. */
+    eventos: LinhaEvento[];
+    /** Violações em modo aviso desde que o watch subiu (decisão D-07). */
+    violacoesAviso: number;
+    /** Instante da leitura, para o rodapé calcular "tempo desde o último evento". */
+    lidoEm: Date;
+};
+export type OpcoesVisao = {
+    /** Id pedido em `expx watch <trabalho_id>`. */
+    trabalhoPedido?: string;
+    /**
+     * Quando o watch subiu. É a fronteira da "sessão" no rodapé: o rastro é
+     * append-only e não marca sessão nenhuma (lacuna L-03, decisão D-07).
+     */
+    subiuEm?: Date;
+    /** Quantas linhas do rastro exibir. */
+    linhasRastro?: number;
+};
+export declare function projetarVisao(raizProjeto: string, op?: OpcoesVisao, agora?: Date): Visao;

package/dist/watch/visao/projetar.js

@@ -0,0 +1,38 @@
+import { montarProjeto } from "../../parser/projeto/montar.js";
+import { lerEstadoExpx } from "../fontes/estado.js";
+import { lerRastro } from "../fontes/rastro.js";
+import { abertos, escolherTrabalho } from "./escolher.js";
+export function projetarVisao(raizProjeto, op = {}, agora = new Date()) {
+    const projeto = montarProjeto(raizProjeto, agora);
+    const estado = lerEstadoExpx(raizProjeto);
+    const trabalho = escolherTrabalho(projeto.trabalhos, estado, op.trabalhoPedido);
+    const tasks = trabalho?.sprints.flatMap((s) => s.tasks) ?? [];
+    // O par concluídas/total tem duas fontes: o estado.json traz os inteiros
+    // prontos, e o plano exige contagem — `progresso` do parser é fração 0..1,
+    // não o par (base/parser-de-artefatos.md, risco 4).
+    const doEstado = estado !== null && trabalho !== null;
+    const concluidas = doEstado
+        ? estado.tasks_concluidas
+        : tasks.filter((t) => t.status === "concluida").length;
+    const total = doEstado ? estado.tasks_total : tasks.length;
+    const eventos = trabalho === null ? [] : lerRastro(raizProjeto, trabalho.trabalho_id, op.linhasRastro);
+    // "Modo aviso" é vocabulário de hook e só existe no rastro: `regra_violada` é
+    // gravado por hook em modo aviso, `acao_bloqueada` em modo bloqueio. Não
+    // confundir com as `Violacao` da conformidade, que são defeitos do método nos
+    // arquivos do plano (lacuna L-03).
+    const fronteira = op.subiuEm?.toISOString().replace(/\.\d{3}Z$/, "Z");
+    const violacoesAviso = eventos.filter((e) => e.evento === "regra_violada" && (fronteira === undefined || e.ts >= fronteira)).length;
+    return {
+        trabalho,
+        abertos: abertos(projeto.trabalhos),
+        estado,
+        degradado: estado === null,
+        concluidas,
+        total,
+        bloqueiosAbertos: (trabalho?.bloqueios ?? []).filter((b) => b.aberto),
+        eventos,
+        violacoesAviso,
+        lidoEm: agora,
+    };
+}
+//# sourceMappingURL=projetar.js.map

package/dist/watch/visao/projetar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projetar.js","sourceRoot":"","sources":["../../../src/watch/visao/projetar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA8C,MAAM,gCAAgC,CAAC;AAG3G,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoD1D,MAAM,UAAU,aAAa,CAC3B,WAAmB,EACnB,KAAkB,EAAE,EACpB,QAAc,IAAI,IAAI,EAAE;IAExB,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC;IAEhF,MAAM,KAAK,GAAG,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAE9D,yEAAyE;IACzE,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,QAAQ,GAAG,MAAM,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,CAAC;IACtD,MAAM,UAAU,GAAG,QAAQ;QACzB,CAAC,CAAC,MAAM,CAAC,gBAAgB;QACzB,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC;IACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IAE3D,MAAM,OAAO,GACX,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC;IAEzF,8EAA8E;IAC9E,yEAAyE;IACzE,8EAA8E;IAC9E,mCAAmC;IACnC,MAAM,SAAS,GAAG,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACtE,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CACnC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,EAAE,IAAI,SAAS,CAAC,CACtF,CAAC,MAAM,CAAC;IAET,OAAO;QACL,QAAQ;QACR,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QACnC,MAAM;QACN,SAAS,EAAE,MAAM,KAAK,IAAI;QAC1B,UAAU;QACV,KAAK;QACL,gBAAgB,EAAE,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QACrE,OAAO;QACP,cAAc;QACd,MAAM,EAAE,KAAK;KACd,CAAC;AACJ,CAAC"}

package/dist/watch/watch.d.ts

@@ -0,0 +1,26 @@
+import type { Opcoes } from "./opcoes.js";
+/**
+ * O loop do watch: lê, desenha, observa, redesenha.
+ *
+ * A promessa que este arquivo existe para cumprir: "a árvore completa vem dos
+ * arquivos do plano, relida apenas quando eles mudam — não a cada redesenho".
+ * Por isso a visão é guardada e só o gatilho de plano a reconstrói; o gatilho
+ * de estado atualiza o barato e redesenha com a árvore que já estava em mãos.
+ */
+export type SessaoWatch = {
+    parar: () => Promise<void>;
+    /** Código de saída, quando o watch terminou sozinho. */
+    codigo: number;
+    /** O watch encerrou por conta própria (projeto sem Expx)? */
+    encerrou: boolean;
+};
+export type OpcoesExecucao = {
+    raiz: string;
+    opcoes: Opcoes;
+    escrever: (texto: string) => void;
+    cor: boolean;
+    debounceMs?: number;
+    /** Gancho de teste: chamado toda vez que o PLANO é relido do disco. */
+    aoLerPlano?: () => void;
+};
+export declare function executarWatch(op: OpcoesExecucao): Promise<SessaoWatch>;

package/dist/watch/watch.js

@@ -0,0 +1,89 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { desenhar } from "./desenho/desenhar.js";
+import { desenharLista } from "./desenho/lista.js";
+import { lerEstadoExpx } from "./fontes/estado.js";
+import { observarFontes } from "./fontes/observar.js";
+import { lerRastro } from "./fontes/rastro.js";
+import { criarTela } from "./terminal/tela.js";
+import { projetarVisao } from "./visao/projetar.js";
+/** Largura de trabalho: a do terminal, o pedido explícito, ou 80. */
+function larguraDe(op) {
+    if (op.opcoes.colunas !== undefined)
+        return op.opcoes.colunas;
+    const cols = process.stdout.columns;
+    // Abaixo de 80 continuamos desenhando: o corte é elegante por construção.
+    return typeof cols === "number" && cols > 0 ? cols : 80;
+}
+export async function executarWatch(op) {
+    // Sem `.expx/`, o projeto não tem o Expx instalado. Mensagem curta e saída
+    // limpa, como manda a tolerância a falha — não é erro, é ausência.
+    if (!existsSync(join(op.raiz, ".expx"))) {
+        op.escrever([
+            "este projeto nao tem o Expx instalado (falta a pasta .expx/).",
+            "",
+            "  npx expxdev init      instala as skills neste projeto",
+            "",
+        ].join("\n"));
+        return { parar: async () => undefined, codigo: 0, encerrou: true };
+    }
+    const subiuEm = new Date();
+    const colunas = larguraDe(op);
+    const tela = criarTela(op.escrever);
+    // A visão fica guardada de propósito: é ela que carrega a árvore, cara de
+    // montar. O gatilho de estado NÃO a reconstrói.
+    let visao = lerTudo();
+    function lerTudo() {
+        op.aoLerPlano?.();
+        return projetarVisao(op.raiz, {
+            ...(op.opcoes.trabalho !== undefined ? { trabalhoPedido: op.opcoes.trabalho } : {}),
+            subiuEm,
+        });
+    }
+    function redesenhar() {
+        const linhas = op.opcoes.todos
+            ? desenharLista(visao, colunas, op.cor)
+            : desenhar(visao, { colunas, cor: op.cor, agora: new Date() });
+        tela.desenhar(linhas);
+    }
+    redesenhar();
+    const observador = await observarFontes(op.raiz, {
+        // O plano mudou: reconstrói tudo. É a releitura cara, e ela só acontece
+        // aqui.
+        aoMudarPlano: () => {
+            visao = lerTudo();
+            redesenhar();
+        },
+        // Só o estado.json mudou: atualiza o barato e redesenha com a árvore
+        // que já estava em mãos.
+        aoMudarEstado: () => {
+            const estado = lerEstadoExpx(op.raiz);
+            visao = { ...visao, estado, degradado: estado === null };
+            redesenhar();
+        },
+        // Só o rastro cresceu: relê os eventos, que é leitura de cauda, e
+        // preserva a árvore. É o caminho mais percorrido durante uma execução
+        // autônoma — cada hook grava uma linha.
+        aoMudarRastro: () => {
+            if (visao.trabalho === null)
+                return;
+            const eventos = lerRastro(op.raiz, visao.trabalho.trabalho_id);
+            const fronteira = subiuEm.toISOString().replace(/\.\d{3}Z$/, "Z");
+            visao = {
+                ...visao,
+                eventos,
+                violacoesAviso: eventos.filter((e) => e.evento === "regra_violada" && e.ts >= fronteira)
+                    .length,
+            };
+            redesenhar();
+        },
+    }, op.debounceMs ?? 150);
+    return {
+        parar: async () => {
+            await observador.parar();
+        },
+        codigo: 0,
+        encerrou: false,
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/watch/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAyB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAa,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAc,MAAM,qBAAqB,CAAC;AA6BhE,qEAAqE;AACrE,SAAS,SAAS,CAAC,EAAkB;IACnC,IAAI,EAAE,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;IAC9D,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;IACpC,0EAA0E;IAC1E,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAkB;IACpD,2EAA2E;IAC3E,mEAAmE;IACnE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;QACxC,EAAE,CAAC,QAAQ,CACT;YACE,+DAA+D;YAC/D,EAAE;YACF,yDAAyD;YACzD,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAS,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAE1C,0EAA0E;IAC1E,gDAAgD;IAChD,IAAI,KAAK,GAAU,OAAO,EAAE,CAAC;IAE7B,SAAS,OAAO;QACd,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC;QAClB,OAAO,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;YAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,SAAS,UAAU;QACjB,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK;YAC5B,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC;YACvC,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,UAAU,EAAE,CAAC;IAEb,MAAM,UAAU,GAAqB,MAAM,cAAc,CACvD,EAAE,CAAC,IAAI,EACP;QACE,wEAAwE;QACxE,QAAQ;QACR,YAAY,EAAE,GAAG,EAAE;YACjB,KAAK,GAAG,OAAO,EAAE,CAAC;YAClB,UAAU,EAAE,CAAC;QACf,CAAC;QACD,qEAAqE;QACrE,yBAAyB;QACzB,aAAa,EAAE,GAAG,EAAE;YAClB,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACtC,KAAK,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC;YACzD,UAAU,EAAE,CAAC;QACf,CAAC;QACD,kEAAkE;QAClE,sEAAsE;QACtE,wCAAwC;QACxC,aAAa,EAAE,GAAG,EAAE;YAClB,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;gBAAE,OAAO;YACpC,MAAM,OAAO,GAAG,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;YAClE,KAAK,GAAG;gBACN,GAAG,KAAK;gBACR,OAAO;gBACP,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,eAAe,IAAI,CAAC,CAAC,EAAE,IAAI,SAAS,CAAC;qBACrF,MAAM;aACV,CAAC;YACF,UAAU,EAAE,CAAC;QACf,CAAC;KACF,EACD,EAAE,CAAC,UAAU,IAAI,GAAG,CACrB,CAAC;IAEF,OAAO;QACL,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,EAAE,CAAC;QACT,QAAQ,EAAE,KAAK;KAChB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expxdev",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI do metodo Expx: instala, atualiza e opera o ecossistema de skills, e sobe o painel de operacao",
   "type": "module",
   "bin": {