9.3 KiB
OPS116 — Painel/TUI: aceitar -ui-design.html com retrocompat -ui-draft.html
Status: rascunho Atualizado em: 2026-09-15 Issue: #1059 Priority: P2 Impeccable: A — N/A (tooling de terminal; não toca UI de produto) Rascunho UI: N/A — sem UI Appetite: ~0,5 dia eng; um outcome verificável Responsável: —
Intenção
O OPS114 renomeou o artefato de validação visual do planejamento de "rascunho UI" para "design UI", com arquivo docs/plans/<slug>-ui-design.html. O painel de issues (pnpm issues:tui, OPS109) ficou para trás: continua procurando só -ui-draft.html e chamando a ação de "rascunho UI". Depois do OPS114, uma Issue nova com design no gate aparece no painel como se não tivesse o arquivo — a tecla w diz "não tem" mesmo tendo — e o operador perde o atalho de abrir o design no browser antes de decidir sobre a Issue. Quero que o painel reconheça os dois nomes — preferindo o novo — e fale "design UI", sem tocar nos planos antigos.
Persona e fluxo
- Persona / contexto: o mantenedor (fsolla) operando issues pelo terminal, na mesa ou via SSH, olhando uma Issue antes de aprovar o plano ou entrar no run.
- Job principal: ver que a Issue tem design UI e abri-lo no browser com uma tecla, sem caçar o caminho no GitHub ou no disco.
- Fluxo desejado: lista → seleciona a Issue → no detalhe vê
w design UI · <caminho>(ou "não tem (classe A)") → apertawe o.htmlabre no browser padrão (ou imprime o caminho, quando não há display). - Anti-goals de produto: não vira renderizador de imagem nem preview embutido; não migra o acervo legado de planos; não muda a UI de produto do
/campanhanem o site; não adiciona ações novas ao painel.
Objetivo e aceite (outcome)
- Issue cujo plano tem só
<base>-ui-design.htmlaparece com o design disponível no detalhe e a teclawabre/entrega o caminho certo. - Issue legada, com só
<base>-ui-draft.html, continua funcionando igual a hoje (retrocompat; planos antigos são imutáveis). - Quando os dois arquivos existem, o painel usa o
-ui-design.html. - O painel (detalhe, ajuda e mensagens) fala "design UI"; "rascunho UI" some das superfícies do painel.
- O contrato
--jsonsegue legível pelo consumidor atual sem quebra silenciosa: a linha da Issue carrega o caminho real do arquivo encontrado e a informação de existência. - Nada de PNG: só HTML (a decisão "HTML-only, no PNG rendering" continua).
Dados (intenção)
- Vou apresentar dados? Não — é ferramenta de operação; a "superfície" é a própria TUI, sem métrica de produto.
- Decisões desbloqueadas: N/A — não há decisão de negócio; é continuidade de leitura do acervo de planos.
- Forma: N/A.
Dados da decisão (literais)
- Decisão de dados de produto: N/A — nada de eleitoral/contato/consentimento neste item.
- Nomes literais: preferir
docs/plans/<base>-ui-design.html; cair paradocs/plans/<base>-ui-draft.htmlquando o primeiro não existir, na mesma base do plano de intenção já usada para-impl.md. - Nomenclatura recomendada (menor churn): manter a chave
uiDraftno view model e notoJsonPayload(version: 1), porém compath= arquivo realmente encontrado; quem quiser saber o nome concreto lê o sufixo do caminho. Campo novo (variant) ou rename fica fora. - Strings exatas (substituindo as atuais em
scripts/issues-tui.mjs:19,339,340,359,637):w design UI·w abrir design UI no browser·w design UI: não tem (classe A). - Sem mudança de schema → sem migration (
pnpm migrate:createnão é usado neste item).
Escopo
scripts/lib/issues-panel.mjs: derivar os dois nomes irmãos (<base>-ui-design.htmlpreferido,<base>-ui-draft.htmlfallback) e devolver no view model/JSON o caminho real do que existe — mantendo a chave atualuiDraft.scripts/issues-tui.mjs: sondar existência na ordem design → draft; strings "rascunho UI" → "design UI" (ajuda:19, linha de ação:339-340, rodapé:359e mensagem do handlerw:637).- Testes unit dos dois specs do painel: atualizar expectativas de nome e cobrir design-only, draft-only, ambos (design vence) e nenhum.
- Entrada de changelog da entrega (
docs/changelog/2026-09-15-ops116.md), conforme convenção do repo.
Direção no codebase (hipótese)
- Áreas prováveis:
scripts/lib/issues-panel.mjs(derivação pura:siblingPlanPaths,buildIssueRow,buildPanelViewModel,toJsonPayload) escripts/issues-tui.mjs(I/O:readPlans, render do detalhe, handlerw). - Precedente a olhar: OPS109 (
docs/plans/ops109-painel-issues-no-terminal.md+ impl), que estabeleceu o painel, a chaveuiDrafte os 28-ui-draft.htmllegados; OPS114 para o contrato do nome novo. - Risco de acoplamento: a existência do arquivo é checada no CLI (o lib é puro e não toca disco) — manter essa divisão.
--jsoné consumido por teste/script: tratar a chave como superfície pública (mudança silenciosa é regressão).
Dependências
- OPS114 (dura, declarada no registro) — dono do rename
-ui-design.html/"design UI" nos planos e na skill. No código, este item é seguro mesmo antes: sem arquivo novo, o fallback legado mantém tudo como está.
Fora de escopo
- Migrar/renomear os
*-ui-draft.htmle PNGs existentes emdocs/plans/(~28 HTMLs e ~45 PNGs) — acervo legado é imutável. - Recriar renderizador de PNG/
scripts/render-ui-draft.mjs(removido em 2026-08-21; HTML-only segue). - Renomear a chave
uiDraftdo view model/JSON ou subir a versão do payload (churn sem consumidor novo). - Tocar na skill
plan-issue/template (dono do rename é o OPS114) ou em UI de produto. - Qualquer mudança em claim/registro/sessões, guards de CI, ou no fluxo
--jsonalém do necessário.
Rabbit holes de produto
- "Já que achou o caminho, deixar o painel renderizar o HTML/imagem." Vira viewer embutido, segundo dono de preview. Corte: só abrir no browser/imprimir caminho, como hoje.
- "Aproveitar e renomear tudo para
-ui-design." Puxa migração de acervo imutável e PR de planos antigos. Corte: retrocompat de leitura. - "Limpar o vocabulário no repo inteiro." Renomeia docs/changelog/skill (dono é OPS114) e explode o diff. Corte: só as superfícies do painel.
Questões em aberto (produto)
- A mensagem de ausência mantém "(classe A)"? Opções: A) uniforme (
design UI: não tem (classe A)) | B) sem "design UI". Recomendação: A — uma palavra por superfície; o "(classe A)" já explica. (assumido — validar no gate) - Caminho exibido quando nenhum arquivo existe: Opções: A) candidato novo (
-ui-design.html) comexists: false| B) manter o antigo. Recomendação: A — ensina o nome novo; o fallback real continua valendo quando o legado existir. (assumido) - Dependência do OPS114 é dura? Opções: A) dura (bloqueia claim até o rename estar em main) | B) suave (o item só lê nomes). Recomendação: A no registro, como pedido pelo gate; a entrega é segura de qualquer forma. (assumido)
Fases (ordem sugerida)
- Camada pura — dois candidatos de design no
siblingPlanPaths+ caminho real no view model; escrever primeiro os unit tests (design-only, draft-only, ambos, nenhum) e fazer passar. - CLI —
readPlanssonda design → draft; render/ajuda/mensagens para "design UI"; smoke manualpnpm issues:tui --json(com token) conferindo o caminho real numa issue com draft legado. - Fechamento — specs existentes atualizados, changelog da entrega e verificação abaixo.
Verificação
- Unit focado nos dois specs do painel (rápido, sem DB):
pnpm test:unit -- tests/unit/issuesPanel.unit.spec.ts tests/unit/issuesPanelRegression.unit.spec.ts - Gate local (lint + typecheck + unit completo):
pnpm gate:fast - Guarda de localização de testes (nenhum spec novo fora de
tests/unit):node scripts/check-test-locations.mjs - Smoke manual (não-gate, exige
GITHUB_TOKEN):pnpm issues:tui --jsone conferir que uma Issue com-ui-draft.htmltraz o caminho real eexists: true; abrirpnpm issues:tuie conferir "design UI" no detalhe.
Riscos
- Regressão silenciosa do
--json: manterversion: 1e o shape{ path, exists }; campo a mais seria contrato novo sem pedido. - Confusão de nomes no código: a chave
uiDraftpassa a significar "design UI (novo ou legado)" — comentar no owner em vez de duplicar campos. - Teste que fixa o nome antigo: os dois specs citados têm expectativas literais de
-ui-draft.html; atualizar junto (senão o gate fica vermelho). - Acervo legado: não tocar nos arquivos existentes; a retrocompat é de leitura, não de migração.
Referências
- GitHub Issue #OPS116 (a registrar; placeholder)
- Design UI (gate): N/A — classe A (sem UI de produto)
- Plano pai (imutável):
docs/plans/ops109-painel-issues-no-terminal.mdedocs/plans/ops109-painel-issues-no-terminal-impl.md - Arquivos owner:
scripts/lib/issues-panel.mjs:5,89-101,180-254,359-391;scripts/issues-tui.mjs:19,104-120,335-341,354-363,633-639 - Testes:
tests/unit/issuesPanel.unit.spec.ts:91-105,153-156,265,290;tests/unit/issuesPanelRegression.unit.spec.ts:152 - Guards/CI citados:
scripts/check-test-locations.mjs,scripts/check-plans-only-pr-closes.mjs; gate localpnpm gate:fast(lint && typecheck && test:unit)