@fprad0/skill-master-mcp 1.0.0 → 1.0.1

package/docs/planning/mcp-1.0.0/03_PLANO_COMPATIBILIDADE_WINDOWS_LINUX_MACOS.md

@@ -0,0 +1,167 @@
+# MCP 1.0.0 - Plano de Compatibilidade Windows, Linux e macOS
+
+## Problemas Encontrados
+
+O comando:
+
+```powershell
+node bin\skill-master-menu.mjs --run check
+```
+
+falhou em Windows com 2 testes.
+
+### Falha 1
+
+Arquivo:
+
+```text
+src/client-config.test.ts
+```
+
+Erro:
+
+```text
+expected /opt/skill-master/bin/skill-master.mjs
+received \opt\skill-master\bin\skill-master.mjs
+```
+
+### Falha 2
+
+Arquivo:
+
+```text
+src/project-skills.test.ts
+```
+
+Erro:
+
+```text
+expected /tmp/app/.agents/skills
+received C:\tmp\app\.agents\skills
+```
+
+## Causa Provavel
+
+Os testes usam caminhos POSIX como fixtures, mas o codigo usa APIs de path do sistema operacional atual. No Windows, `path.join` e `path.resolve` convertem para backslash ou prefixam drive.
+
+Isso cria falsos negativos em Windows.
+
+## Objetivo
+
+Garantir que:
+
+- testes passem em Windows, Linux e macOS
+- configs MCP usem o formato correto para cada cliente
+- caminhos de comando sejam robustos
+- caminhos serializados em TOML/JSON nao quebrem por escape
+- fixtures POSIX continuem testaveis no Windows quando necessario
+
+## Plano Tecnico
+
+### 1. Separar path operacional de path serializado
+
+Criar helpers claros:
+
+```ts
+toNativePath(value)
+toPosixPath(value)
+toJsonPath(value)
+toTomlPath(value)
+normalizePathForComparison(value)
+```
+
+Uso:
+
+- execucao local: native path
+- JSON/TOML de clientes: string absoluta segura
+- testes cross-platform: normalizacao explicita
+- fixtures POSIX: `path.posix`
+
+### 2. Corrigir teste Claude Code
+
+O teste que espera:
+
+```text
+/opt/skill-master/bin/skill-master.mjs
+```
+
+deve montar o server com path POSIX preservado ou comparar via normalizacao.
+
+Opcoes:
+
+1. Usar `path.posix.join` dentro do fixture.
+2. Comparar `normalizeSlashes(args[7])`.
+3. Ajustar `buildClaudeCodeAddArgs` para nao converter path que ja e POSIX absoluto.
+
+Recomendacao: preservar POSIX absoluto quando entrada comeca com `/`.
+
+### 3. Corrigir teste de roots do projeto
+
+O teste que usa `/tmp/app` deve:
+
+- rodar com `path.posix` se o objetivo e POSIX
+- ou aceitar resultado nativo se o objetivo e plataforma atual
+
+Recomendacao: dividir em dois testes:
+
+- `normalizes native project skill roots`
+- `preserves explicit POSIX roots when requested`
+
+### 4. Adicionar matriz de CI local
+
+Scripts sugeridos:
+
+```json
+{
+  "test:windows-paths": "vitest run src/client-config.test.ts src/project-skills.test.ts",
+  "test:menu": "node scripts/verify-menu-actions.mjs",
+  "test:activation-cli": "vitest run src/success-learning.test.ts src/menu-core.test.ts"
+}
+```
+
+### 5. Validar instalacao global 1.0.0
+
+Comandos:
+
+```powershell
+npm install -g @fprad0/skill-master-mcp@1.0.0 --registry=https://registry.npmjs.org
+where skill-master-menu
+skill-master-menu --status
+skill-master-doctor
+```
+
+No Linux/macOS:
+
+```bash
+npm install -g @fprad0/skill-master-mcp@1.0.0 --registry=https://registry.npmjs.org
+command -v skill-master-menu
+skill-master-menu --status
+skill-master-doctor
+```
+
+## Melhorias no Doctor
+
+Hoje o doctor retorna `partial` quando Claude Code esta ausente. Isso pode assustar quando o usuario nao usa Claude Code.
+
+Melhoria:
+
+- separar clientes obrigatorios de opcionais
+- exibir `ready-with-optional-warnings`
+- retornar exit code 0 quando apenas cliente opcional estiver ausente
+
+Estados sugeridos:
+
+```text
+ready
+ready_with_optional_warnings
+partial
+blocked
+```
+
+## Definition of Done
+
+- `npm run check` passa no Windows
+- testes continuam passando em Linux/macOS
+- doctor distingue cliente opcional ausente de falha real
+- registro Codex, Claude Desktop, Gemini e Antigravity permanece com node absoluto
+- nenhum teste usa expectativa POSIX acidental em Windows

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