@fprad0/skill-master-mcp 0.0.12 → 1.0.1

package/docs/planning/mcp-1.0.0/04_PLANO_UI_CYBERPUNK_PIXEL_ART_E_PERFORMANCE.md

@@ -0,0 +1,165 @@
+# MCP 1.0.0 - Plano UI Cyberpunk Pixel Art e Performance
+
+## Estado Atual
+
+O menu renderiza frames estilo cyberpunk no modo `--run`, com:
+
+- moldura textual forte
+- bloco de status visual
+- resultado OK/ERROR em frame dedicado
+- linguagem coerente com `skill_master`
+
+O visual ja esta melhor que um CLI comum, mas ainda pode ficar mais proximo do DNA pixel art desejado.
+
+## Problemas e Oportunidades
+
+### 1. Acoes interativas parecem executaveis em automacao
+
+No `--help`, acoes como `promptRecommendation`, `markLearnedStudy`, `activateLearnedLocal` e `activateLearnedGlobal` aparecem como se fossem equivalentes a acoes diretas.
+
+Melhoria: mostrar badges.
+
+```text
+[SAFE]
+[WRITES]
+[CONFIRM]
+[TTY]
+[GLOBAL]
+[DRAFT]
+```
+
+### 2. `approvalPackage` e classificado como read-only no verificador
+
+Ele cria arquivo local. Deve ser tratado como `writes-local-safe`, nao `read-only`.
+
+### 3. `doctor` usa linguagem de falha para cliente opcional
+
+Quando Claude Code esta ausente, o usuario recebe `Readiness global - partial`, mesmo com Codex, Claude Desktop, Gemini e Antigravity OK.
+
+Melhoria visual:
+
+```text
+READY / optional warning
+```
+
+### 4. Prompt router e ativacao aprendida precisam modo nao interativo
+
+Quando chamados via `--run`, falham por TTY. A UI deve mostrar antes:
+
+```text
+Esta acao requer TTY ou --manifest/--prompt.
+```
+
+### 5. Frames podem informar risco melhor
+
+Para acoes globais, o frame deve ter sinal visual diferente:
+
+- workspace: cyan
+- global: amber
+- destrutivo/rejeicao: rose
+- diagnostico: white/gray
+
+## Melhorias Visuais Propostas
+
+### Cyberpunk Command Frame 2.0
+
+Adicionar uma linha superior com chips:
+
+```text
+[MCP 1.0.0] [GLOBAL] [CONFIRM] [TTY] [RISK:MED]
+```
+
+### Painel de Acao
+
+Para cada item:
+
+```text
+acao: activateLearnedGlobal
+tipo: escreve em CODEX_HOME skills
+entrada: draft manifest
+saida: SKILL.md + skill-master-approval.json
+risco: afeta todos os workspaces
+modo seguro: --manifest <path> --yes
+```
+
+### Preview Antes de Executar
+
+Antes de rodar mutacao:
+
+```text
+Destino: C:\Users\CDT\.codex\skills\<skill>
+Origem: manifest.json
+Hash: sha256...
+Registro: skill-master-approval.json
+```
+
+### Animacao sem Flicker
+
+Manter:
+
+- alternate screen
+- cursor restore em `finally`
+- redraw em origem fixa
+- `clearToEnd`, nao clear total repetido
+
+Adicionar:
+
+- throttle padrao 180ms a 240ms
+- reduzir `getMenuStatus` a cada frame; cachear por 1 segundo
+- recalcular catalogo apenas quando acao terminar ou usuario pedir refresh
+
+## Performance
+
+### Problema Potencial
+
+`renderCyberMenu` chama `getMenuStatus(rootDir)` a cada frame. Esse status le arquivos, conta manifests e checa readiness. Em terminais lentos ou repos grandes, isso pode gerar travamentos.
+
+### Plano
+
+1. Criar `createMenuStatusCache({ ttlMs: 1000 })`.
+2. Atualizar cache ao entrar no menu.
+3. Reusar cache em frames.
+4. Invalidar cache apos acao executada.
+5. Mostrar indicador `status cached` quando estiver renderizando sem recarregar.
+
+### Testes
+
+- medir tempo medio de 100 renders
+- testar terminal pequeno `80x24`
+- testar terminal grande `160x50`
+- testar `TERM=dumb`
+- testar `SKILL_MASTER_NO_VISUAL=1`
+
+## Layout
+
+### Regras
+
+- texto nunca deve ultrapassar largura do frame
+- labels longos devem truncar com `...`
+- a lista de acoes deve preservar selecao visivel
+- detalhe deve mostrar comando real e risco
+- modo compact deve priorizar acao selecionada, risco e resultado esperado
+
+### Smoke Visual
+
+Criar script:
+
+```text
+scripts/render-menu-smoke.mjs
+```
+
+Saidas:
+
+- `MCP 1.0.0/menu-frame-120x32.txt`
+- `MCP 1.0.0/menu-frame-80x24.txt`
+- `MCP 1.0.0/menu-running-action.txt`
+- `MCP 1.0.0/menu-confirm-global.txt`
+
+## Definition of Done
+
+- `--run` continua sem escape raw em ambiente nao TTY
+- menu interativo nao deixa cursor oculto apos erro
+- acoes globais ficam visualmente diferenciadas
+- acoes TTY-only ficam marcadas
+- cache reduz leituras por frame
+- screenshots/text frames documentados em `MCP 1.0.0`

package/docs/planning/mcp-1.0.0/05_PROMPT_TASK_EXECUCAO_CORRECOES.md

@@ -0,0 +1,151 @@
+# MCP 1.0.0 - Prompt Task de Execucao das Correcoes
+
+## Objetivo
+
+Corrigir o `skill-master-menu` da versao `1.0.0` para que todas as acoes criticas funcionem em modo interativo e nao interativo, com foco especial em ativacao de skill aprendida no workspace e global.
+
+## Contexto
+
+Auditoria real em Windows confirmou:
+
+- `npm run verify:menu` passa
+- `node bin\skill-master-menu.mjs --run build` passa
+- `node bin\skill-master-menu.mjs --run check` falha por 2 testes de path cross-platform
+- `node bin\skill-master-menu.mjs --run activate-learned-local --yes` falha
+- `node bin\skill-master-menu.mjs --run activate-learned-global --yes` falha
+- o core `activateSuccessSkillDraft` funciona
+- o CLI direto `skill-master-success-skills --activate <manifest> --target <path> --yes` funciona
+
+## Escopo
+
+Alterar com cuidado:
+
+- `bin/skill-master-menu.mjs`
+- `bin/lib/menu-core.mjs`
+- `bin/skill-master-success-skills.mjs`
+- `src/success-learning.test.ts`
+- `src/menu-core.test.ts`
+- `src/client-config.test.ts`
+- `src/project-skills.test.ts`
+- docs/help quando necessario
+
+## Tarefa 1 - Corrigir Ativacao Local/Global via Menu
+
+Adicionar suporte a:
+
+```powershell
+skill-master-menu --run activate-learned-local --manifest <manifest.json> --yes
+skill-master-menu --run activate-learned-global --manifest <manifest.json> --yes
+```
+
+Adicionar fallback seguro:
+
+```powershell
+skill-master-menu --run activate-learned-local --yes
+```
+
+Regras:
+
+- 0 drafts prontos: erro claro
+- 1 draft pronto: ativa
+- 2+ drafts prontos: erro pedindo `--manifest`
+- global exige `--yes`
+- sem TTY nunca deve chamar `--activate-interactive`
+
+## Tarefa 2 - Melhorar `skill-master-success-skills`
+
+Adicionar:
+
+```powershell
+skill-master-success-skills --activate-ready --target local|global --yes
+```
+
+Comportamento:
+
+- usa `SKILL_MASTER_SUCCESS_LEARNING_DIR`
+- filtra apenas `ready-for-human-approval`
+- imprime lista quando ambigua
+- cria `SKILL.md`
+- cria `skill-master-approval.json`
+- atualiza manifest para `activated`
+
+## Tarefa 3 - Prompt Router Nao Interativo
+
+Adicionar:
+
+```powershell
+skill-master-menu --run prompt-router --prompt "..."
+```
+
+Deve chamar:
+
+```powershell
+skill-master-activation --route-prompt "..."
+```
+
+Sem `--prompt`, em nao TTY deve falhar com:
+
+```text
+This action requires a TTY or --prompt "..."
+```
+
+## Tarefa 4 - Corrigir Testes Windows
+
+Corrigir:
+
+- `src/client-config.test.ts`
+- `src/project-skills.test.ts`
+
+Nao mascarar bug real. Separar:
+
+- path nativo
+- path POSIX fixture
+- serializacao JSON/TOML
+- comparacao normalizada
+
+## Tarefa 5 - UI e UX
+
+Adicionar metadados de acao:
+
+```ts
+mode: 'read-only' | 'writes-local' | 'writes-global' | 'interactive' | 'dev-only'
+risk: 'low' | 'medium' | 'high'
+requiresTty: boolean
+requiresManifest?: boolean
+```
+
+Renderizar badges no menu e no help:
+
+```text
+[SAFE] [TTY] [GLOBAL] [CONFIRM]
+```
+
+## Validacao Obrigatoria
+
+Rodar:
+
+```powershell
+npm run build
+npm test
+npm run verify:menu
+node bin\skill-master-menu.mjs --status
+node bin\skill-master-menu.mjs --run public-npm
+node bin\skill-master-menu.mjs --run activation-status
+node bin\skill-master-menu.mjs --run notifications
+```
+
+Criar teste temporario:
+
+1. gerar draft com `prepareSuccessSkillDraft`
+2. ativar via menu local com `--manifest --yes`
+3. ativar via menu global com `--manifest --yes`
+4. validar arquivos gravados
+
+## Definition of Done
+
+- `npm run check` passa no Windows
+- ativacao local/global via menu passa em nao TTY
+- menu interativo continua funcionando
+- `--help` mostra opcoes novas
+- docs de `MCP 1.0.0` atualizados com resultado da correcao
+- nenhuma publicacao npm e feita sem autorizacao explicita

package/docs/planning/mcp-1.0.0/06_CHECKLIST_REGRESSAO_PRE_RELEASE.md

@@ -0,0 +1,159 @@
+# MCP 1.0.0 - Checklist de Regressao Pre-Release
+
+Use este checklist antes de publicar a proxima versao depois das correcoes.
+
+## Ambiente
+
+- [ ] Windows testado
+- [ ] Linux testado
+- [ ] macOS testado
+- [ ] Node 18 testado
+- [ ] Node 20 testado
+- [ ] Node 22+ testado
+- [ ] npm registry publico acessivel
+- [ ] sem tokens, senhas ou OTPs em logs/arquivos
+
+## Build e Testes
+
+```powershell
+npm install
+npm run build
+npm test
+npm run verify:menu
+npm run check:manifest
+npm pack --dry-run
+```
+
+- [ ] build passou
+- [ ] testes passaram
+- [ ] verify menu passou
+- [ ] manifestos passaram
+- [ ] pack dry-run passou
+
+## Menu
+
+```powershell
+skill-master-menu --help
+skill-master-menu --status
+skill-master-menu --run public-npm
+skill-master-menu --run activation-status
+skill-master-menu --run notifications
+skill-master-menu --run study-skills
+skill-master-menu --run notion-summary
+```
+
+- [ ] help exibe todas as acoes
+- [ ] status correto
+- [ ] npm publico retorna latest
+- [ ] activation status correto
+- [ ] notifications nao falha com 0 drafts
+- [ ] study skills lista candidatos
+- [ ] notion summary nao escreve em Notion
+
+## Acoes Protegidas
+
+Sem `--yes`, devem bloquear:
+
+```powershell
+skill-master-menu --run update-global
+skill-master-menu --run install-global-skills
+skill-master-menu --run install-project-skills
+skill-master-menu --run bootstrap-global
+skill-master-menu --run register-clients
+skill-master-menu --run reject-skill
+```
+
+- [ ] todas bloqueiam sem TTY
+- [ ] erro explica como continuar
+
+## Skill Aprendida Local
+
+Preparar draft temporario e testar:
+
+```powershell
+skill-master-menu --run activate-learned-local --manifest <manifest.json> --yes
+```
+
+Validar:
+
+- [ ] cria `.codex/skills/<skill>/SKILL.md`
+- [ ] cria `.codex/skills/<skill>/skill-master-approval.json`
+- [ ] atualiza manifest para `activated`
+- [ ] rejeita skill nao pronta
+- [ ] rejeita hash divergente
+- [ ] rejeita duplicidade sem `--overwrite`
+
+## Skill Aprendida Global
+
+Usar `CODEX_HOME` temporario:
+
+```powershell
+$env:CODEX_HOME = "$env:TEMP\skill-master-global-test"
+skill-master-menu --run activate-learned-global --manifest <manifest.json> --yes
+```
+
+Validar:
+
+- [ ] cria `%CODEX_HOME%\skills\<skill>\SKILL.md`
+- [ ] cria `skill-master-approval.json`
+- [ ] nao escreve no global real durante teste
+- [ ] exige `--yes`
+- [ ] mensagem de risco global aparece
+
+## UI Cyberpunk
+
+- [ ] menu interativo abre
+- [ ] intro aparece
+- [ ] setas navegam
+- [ ] Enter executa acao segura
+- [ ] confirmacao aparece em acao global
+- [ ] Esc ou q sai
+- [ ] cursor volta ao normal
+- [ ] terminal nao fica em alternate screen
+- [ ] `TERM=dumb` nao imprime escape cru
+- [ ] `SKILL_MASTER_NO_VISUAL=1` desativa visual
+
+## Performance
+
+- [ ] menu nao trava ao navegar
+- [ ] status cache reduz custo por frame
+- [ ] render 80x24 nao sobrepoe texto
+- [ ] render 120x32 fica legivel
+- [ ] acoes longas mostram estado de execucao
+
+## Instalacao Global
+
+```powershell
+npm install -g @fprad0/skill-master-mcp@<versao> --registry=https://registry.npmjs.org
+where skill-master-menu
+where skill-master-mcp
+skill-master-doctor
+```
+
+- [ ] binarios existem
+- [ ] doctor passa ou mostra apenas warnings opcionais
+- [ ] Codex config robusta
+- [ ] Claude Desktop config robusta
+- [ ] Gemini config robusta
+- [ ] Antigravity config robusta
+
+## Publicacao
+
+Antes de publicar:
+
+- [ ] usuario autorizou explicitamente
+- [ ] versao incrementada
+- [ ] changelog atualizado
+- [ ] `npm pack --dry-run` revisado
+- [ ] pacote nao contem segredo
+- [ ] comandos globais preservados em `npm view <pkg>@<versao> bin --json`
+
+Depois de publicar:
+
+```powershell
+npm view @fprad0/skill-master-mcp version --registry=https://registry.npmjs.org
+npm view @fprad0/skill-master-mcp dist-tags --json --registry=https://registry.npmjs.org
+```
+
+- [ ] latest aponta para nova versao
+- [ ] instalacao global em maquina limpa passa

package/docs/planning/mcp-1.0.0/07_RELATORIO_APLICACAO_CORRECOES_MENU_SKILL_MASTER.md

@@ -0,0 +1,136 @@
+# Relatorio de aplicacao das correcoes do skill-master-menu
+
+Data: 2026-06-30
+Repositorio aplicado: `C:\Users\CDT\Documents\F.Prado\skill-master-mcp-release-publish`
+Versao alvo: `@fprad0/skill-master-mcp@1.0.0`
+
+## Resumo executivo
+
+As correcoes dos planejamentos da pasta `MCP 1.0.0` foram aplicadas com prioridade maxima no fluxo funcional do `skill-master-menu`.
+
+O bug principal foi confirmado e corrigido: as acoes `activate-learned-local` e `activate-learned-global` chamavam sempre `skill-master-success-skills --activate-interactive`, entao falhavam em ambientes sem TTY mesmo com `--yes`.
+
+Agora o menu suporta execucao nao interativa com manifesto explicito:
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-local --manifest "C:\caminho\manifest.json" --yes
+node bin\skill-master-menu.mjs --run activate-learned-global --manifest "C:\caminho\manifest.json" --yes
+```
+
+Tambem foi criado um modo deterministico para ativar automaticamente quando existe exatamente um draft pronto:
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-local --yes
+node bin\skill-master-menu.mjs --run activate-learned-global --yes
+```
+
+Esse modo falha fechado quando ha zero ou mais de um draft pronto, exigindo `--manifest`.
+
+## Arquivos alterados
+
+- `bin/skill-master-menu.mjs`
+  - adiciona `--manifest`, `--prompt` e `--overwrite`;
+  - transforma `activate-learned-local/global` em comandos nao interativos quando `--manifest` ou `--yes` sao usados;
+  - valida mensagens claras quando a acao ainda exige TTY;
+  - permite `prompt-router` sem TTY via `--prompt`.
+
+- `bin/skill-master-success-skills.mjs`
+  - adiciona `--activate-ready`;
+  - lista drafts prontos usando o mesmo gate de revisao;
+  - ativa automaticamente apenas quando existe exatamente um draft pronto;
+  - falha com instrucao acionavel quando ha zero ou varios drafts.
+
+- `bin/lib/menu-core.mjs`
+  - adiciona metadados visuais de efeito, risco, confirmacao e TTY;
+  - documenta no help os fluxos automatizaveis;
+  - mantem o estilo cyberpunk pixel art e melhora legibilidade de acoes globais/interativas;
+  - corrige `cwd` da ativacao local/global para o workspace onde o menu foi chamado.
+
+- `bin/lib/client-config.mjs`
+  - preserva caminhos POSIX quando a raiz do pacote e POSIX, mesmo durante testes no Windows.
+
+- `scripts/verify-menu-actions.mjs`
+  - remove `approvalPackage` da lista read-only, pois ele cria arquivo local;
+  - registra acoes de escrita local separadamente.
+
+- `src/menu-core.test.ts`
+  - cobre metadados, help e caminhos automatizaveis do menu.
+
+- `src/success-learning.test.ts`
+  - adiciona regressao real chamando o binario do menu sem TTY;
+  - cobre ativacao local com `--manifest --yes`;
+  - cobre ativacao global com `--manifest --yes`;
+  - cobre `--activate-ready --yes` quando ha exatamente um draft pronto.
+
+- `src/project-skills.test.ts`
+  - ajusta expectativa cross-platform para raizes POSIX explicitas preservadas.
+
+## Descobertas importantes
+
+1. O fluxo local tinha dois problemas:
+   - dependencia indevida de TTY;
+   - `cwd` padrao do pacote, nao do workspace de invocacao.
+
+2. O fluxo global tambem dependia de TTY quando usado pelo menu com `--yes`.
+
+3. `approvalPackage` nao e read-only. Ele escreve um pacote local de aprovacao e agora esta classificado como escrita local.
+
+4. O teste de configuracao de clientes revelou risco real: uma raiz POSIX como `/opt/skill-master` podia virar `\opt\skill-master` quando testada no Windows.
+
+5. A arvore ja tinha `package-lock.json` modificado antes desta aplicacao. Nao foi revertido para preservar mudancas preexistentes.
+
+## Validacoes executadas
+
+Todas passaram.
+
+```powershell
+npm run build
+npm test
+npm run verify:menu
+npm run check
+node bin\skill-master-menu.mjs --help
+node bin\skill-master-menu.mjs --run prompt-router --prompt "corrigir menu skill-master sem TTY"
+npm pack --dry-run
+```
+
+Resultados principais:
+
+- `npm run check`: passou.
+- Testes: 17 arquivos, 96 testes, todos passaram.
+- `verify:menu`: 23 acoes requeridas, matriz OK.
+- `check:manifest`: stable `1.0.0`, beta `1.0.0-beta`, manifestos validos.
+- `npm pack --dry-run`: pacote `fprad0-skill-master-mcp-1.0.0.tgz` gerado em dry-run com sucesso.
+
+## Como testar no outro computador
+
+Depois de transferir ou puxar o repositorio com estas alteracoes:
+
+```powershell
+npm install
+npm run check
+npm pack --dry-run
+```
+
+Para testar ativacao local com manifesto:
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-local --manifest "C:\caminho\manifest.json" --yes
+```
+
+Para testar ativacao global com manifesto:
+
+```powershell
+node bin\skill-master-menu.mjs --run activate-learned-global --manifest "C:\caminho\manifest.json" --yes
+```
+
+Para testar prompt-router sem TTY:
+
+```powershell
+node bin\skill-master-menu.mjs --run prompt-router --prompt "seu prompt"
+```
+
+## Pendencias
+
+- Publicacao npm nao foi executada, conforme regra obrigatoria de nao publicar sem autorizacao explicita nesta etapa.
+- Validacao visual manual em terminal real ainda e recomendada para conferir o HUD cyberpunk em Windows Terminal, macOS Terminal/iTerm e terminais Linux.
+- O `package-lock.json` aparece modificado na arvore de trabalho, mas essa alteracao ja existia antes desta rodada e precisa de decisao separada antes de commit/release.