@fprad0/skill-master-mcp 0.0.12 → 1.0.0

package/docs/operations/GUIA_NPM_PRIVADO.md

@@ -1,294 +1,294 @@
-# Guia de Instalacao via Pacote Privado
-
-## Objetivo
-
-Distribuir o `skill_master` sem expor o codigo-fonte publicamente e sem depender de `git clone` em cada notebook.
-
-O fluxo usa:
-
-- pacote privado no GitHub Packages;
-- autenticacao do `npm` com token;
-- execucao via `npx @fprad0/skill-master-mcp`;
-- configuracao MCP por `stdio`.
-
-## Modelo de seguranca do `.npmrc`
-
-O configurador segue tres regras:
-
-- o token fica escopado ao host do registry, por exemplo `//npm.pkg.github.com/:_authToken=...`;
-- o registry precisa usar HTTPS por padrao;
-- o arquivo `.npmrc` usa referencia de variavel de ambiente por padrao, evitando gravar o token literal.
-
-Conteudo recomendado:
-
-```ini
-@fprad0:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
-```
-
-Se voce precisar persistir o token literal dentro do `.npmrc`, use `--store-token` de forma consciente. Esse modo e menos seguro, mas pode ser necessario em maquinas sem suporte simples a variaveis de ambiente persistentes.
-
-## Pre-requisitos
-
-- Node.js e npm instalados;
-- acesso ao repositorio `FPrad0/skill-master-mcp`;
-- um token do GitHub com permissao de leitura de packages privados.
-
-## Token recomendado
-
-Crie um token com:
-
-- `read:packages`
-
-Se a mesma maquina tambem for publicar o pacote, adicione:
-
-- `write:packages`
-
-Se voce for usar esse token dentro do GitHub Actions para publicar o pacote do proprio repositrio, recomendo:
-
-- `read:packages`
-- `write:packages`
-- `repo` se sua conta exigir permissao mais ampla para repositorios privados
-
-## Secret do GitHub Actions
-
-No repositrio `FPrad0/skill-master-mcp`, crie o secret:
-
-```text
-GH_PACKAGES_TOKEN
-```
-
-Valor:
-
-- um PAT da conta que tenha permissao para publicar packages privados
-
-Local:
-
-```text
-Settings > Secrets and variables > Actions > New repository secret
-```
-
-## Configurar o npm no Windows
-
-### Jeito rapido com script do repositrio
-
-Com o repositrio local disponvel:
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate
-```
-
-O script:
-
-- pede o token de forma segura se ele no estiver em variavel de ambiente;
-- atualiza apenas as linhas necessrias do `%USERPROFILE%\.npmrc`;
-- cria backup com timestamp se o arquivo ja existir;
-- grava o `.npmrc` apontando para `${GITHUB_PACKAGES_TOKEN}` por padrao;
-- valida acesso ao pacote com `npm view`;
-- mostra o comando final de `npx`.
-
-Crie ou atualize o arquivo:
-
-```text
-%USERPROFILE%\.npmrc
-```
-
-Com o conteudo recomendado:
-
-```ini
-@fprad0:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
-```
-
-Se preferir gravar o token literal no `.npmrc`:
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate -StoreToken
-```
-
-### Jeito rapido sem checkout local
-
-Use esta opcao quando a maquina ja consegue resolver o escopo `@fprad0` no GitHub Packages.
-
-```powershell
-$env:GITHUB_PACKAGES_TOKEN='SEU_TOKEN'
-npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
-```
-
-Para ler o token de arquivo, evitando argumento em historico de shell:
-
-```powershell
-npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --token-file .\github-packages-token.txt --validate
-```
-
-## Validar acesso ao pacote
-
-```bat
-npm view @fprad0/skill-master-mcp --registry=https://npm.pkg.github.com
-```
-
-Se esse comando responder sem erro de autenticacao, a maquina ja consegue instalar o pacote.
-
-## Configurar o npm no Linux
-
-### Jeito rapido com script do repositrio
-
-```bash
-bash ./scripts/configure-private-registry.sh --validate
-```
-
-O script:
-
-- pede o token sem eco no terminal quando necessario;
-- atualiza apenas as linhas do escopo `@fprad0`;
-- cria ou reaproveita `${HOME}/.npmrc`;
-- aplica permissao `0600` no `${HOME}/.npmrc`;
-- grava o `.npmrc` apontando para `${GITHUB_PACKAGES_TOKEN}` por padrao;
-- valida acesso ao pacote;
-- mostra o comando final de `npx`.
-
-### Jeito rapido sem checkout local
-
-Use esta opcao quando a maquina ja consegue resolver o escopo `@fprad0` no GitHub Packages.
-
-```bash
-GITHUB_PACKAGES_TOKEN='SEU_TOKEN' npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
-```
-
-Para ler o token via stdin:
-
-```bash
-printf '%s' "$GITHUB_PACKAGES_TOKEN" | npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --token-stdin --validate
-```
-
-Para gravar token literal no `.npmrc` quando necessario:
-
-```bash
-bash ./scripts/configure-private-registry.sh --validate --store-token
-```
-
-## Publicacao pelo workflow
-
-O workflow de release usa:
-
-```text
-secrets.GH_PACKAGES_TOKEN
-```
-
-Entao a publicacao privada depende de:
-
-1. o secret existir no repositrio
-2. o PAT ter permissao de packages
-3. a conta dona do repositrio ter acesso ao namespace `@fprad0`
-
-## Instalar com npx
-
-```bat
-npx @fprad0/skill-master-mcp
-```
-
-Se quiser forcar a versao mais recente:
-
-```bat
-npx -y @fprad0/skill-master-mcp@latest
-```
-
-## Fluxo recomendado para outro notebook Windows
-
-1. criar ou obter um token com `read:packages` e, se o repositrio for privado, `repo`;
-2. abrir PowerShell na pasta local do repositrio `skill-master-mcp`;
-3. rodar:
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate
-```
-
-4. validar manualmente se quiser:
-
-```powershell
-npm view @fprad0/skill-master-mcp --registry=https://npm.pkg.github.com
-```
-
-5. configurar o cliente MCP para usar:
-
-```powershell
-npx -y @fprad0/skill-master-mcp@latest
-```
-
-## Fluxo recomendado para outro notebook Linux
-
-```bash
-bash ./scripts/configure-private-registry.sh --validate
-npm view @fprad0/skill-master-mcp --registry=https://npm.pkg.github.com
-npx -y @fprad0/skill-master-mcp@latest
-```
-
-## Exemplo para Claude Code
-
-Arquivo MCP:
-
-```json
-{
-  "mcpServers": {
-    "skill_master": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@fprad0/skill-master-mcp@latest"],
-      "env": {
-        "SKILL_MASTER_WORKSPACE": "C:\\Projetos\\link-your-biz"
-      }
-    }
-  }
-}
-```
-
-## Exemplo para Codex
-
-Bloco em `config.toml`:
-
-```toml
-[mcp_servers.skill_master]
-command = "C:\\Program Files\\nodejs\\npx.cmd"
-args = ["-y", "@fprad0/skill-master-mcp@latest"]
-startup_timeout_sec = 120
-
-[mcp_servers.skill_master.env]
-SKILL_MASTER_WORKSPACE = "C:\\Projetos\\link-your-biz"
-```
-
-## Atualizacao
-
-Quando o cliente estiver configurado com:
-
-```text
-npx -y @fprad0/skill-master-mcp@latest
-```
-
-ele sempre tenta usar a versao mais recente do pacote publicado.
-
-Se houver cache antigo, rode:
-
-```bat
-npm cache clean --force
-```
-
-e reinicie o cliente MCP.
-
-## Diferenca para o modo git
-
-Modo `git`:
-
-- melhor para desenvolvimento do MCP;
-- permite `git pull`, `npm ci` e `npm run build`.
-
-Modo `npm privado`:
-
-- melhor para distribuir;
-- nao exige repositrio local;
-- nao deve depender de escrita dentro da pasta do pacote.
-
-Por isso o `skill_master` em modo pacote grava cache e contribuicoes em:
-
-```text
-%USERPROFILE%\.skill-master
-```
+# Guia de Instalacao via Pacote Privado
+
+## Objetivo
+
+Distribuir o `skill_master` sem expor o codigo-fonte publicamente e sem depender de `git clone` em cada notebook.
+
+O fluxo usa:
+
+- pacote privado no GitHub Packages;
+- autenticacao do `npm` com token;
+- execucao via `npx @fprad0/skill-master-mcp`;
+- configuracao MCP por `stdio`.
+
+## Modelo de seguranca do `.npmrc`
+
+O configurador segue tres regras:
+
+- o token fica escopado ao host do registry, por exemplo `//npm.pkg.github.com/:_authToken=...`;
+- o registry precisa usar HTTPS por padrao;
+- o arquivo `.npmrc` usa referencia de variavel de ambiente por padrao, evitando gravar o token literal.
+
+Conteudo recomendado:
+
+```ini
+@fprad0:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Se voce precisar persistir o token literal dentro do `.npmrc`, use `--store-token` de forma consciente. Esse modo e menos seguro, mas pode ser necessario em maquinas sem suporte simples a variaveis de ambiente persistentes.
+
+## Pre-requisitos
+
+- Node.js e npm instalados;
+- acesso ao repositorio `FPrad0/skill-master-mcp`;
+- um token do GitHub com permissao de leitura de packages privados.
+
+## Token recomendado
+
+Crie um token com:
+
+- `read:packages`
+
+Se a mesma maquina tambem for publicar o pacote, adicione:
+
+- `write:packages`
+
+Se voce for usar esse token dentro do GitHub Actions para publicar o pacote do proprio repositrio, recomendo:
+
+- `read:packages`
+- `write:packages`
+- `repo` se sua conta exigir permissao mais ampla para repositorios privados
+
+## Secret do GitHub Actions
+
+No repositrio `FPrad0/skill-master-mcp`, crie o secret:
+
+```text
+GH_PACKAGES_TOKEN
+```
+
+Valor:
+
+- um PAT da conta que tenha permissao para publicar packages privados
+
+Local:
+
+```text
+Settings > Secrets and variables > Actions > New repository secret
+```
+
+## Configurar o npm no Windows
+
+### Jeito rapido com script do repositrio
+
+Com o repositrio local disponvel:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate
+```
+
+O script:
+
+- pede o token de forma segura se ele no estiver em variavel de ambiente;
+- atualiza apenas as linhas necessrias do `%USERPROFILE%\.npmrc`;
+- cria backup com timestamp se o arquivo ja existir;
+- grava o `.npmrc` apontando para `${GITHUB_PACKAGES_TOKEN}` por padrao;
+- valida acesso ao pacote com `npm view`;
+- mostra o comando final de `npx`.
+
+Crie ou atualize o arquivo:
+
+```text
+%USERPROFILE%\.npmrc
+```
+
+Com o conteudo recomendado:
+
+```ini
+@fprad0:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Se preferir gravar o token literal no `.npmrc`:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate -StoreToken
+```
+
+### Jeito rapido sem checkout local
+
+Use esta opcao quando a maquina ja consegue resolver o escopo `@fprad0` no GitHub Packages.
+
+```powershell
+$env:GITHUB_PACKAGES_TOKEN='SEU_TOKEN'
+npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
+```
+
+Para ler o token de arquivo, evitando argumento em historico de shell:
+
+```powershell
+npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --token-file .\github-packages-token.txt --validate
+```
+
+## Validar acesso ao pacote
+
+```bat
+npm view @fprad0/skill-master-mcp --registry=https://npm.pkg.github.com
+```
+
+Se esse comando responder sem erro de autenticacao, a maquina ja consegue instalar o pacote.
+
+## Configurar o npm no Linux
+
+### Jeito rapido com script do repositrio
+
+```bash
+bash ./scripts/configure-private-registry.sh --validate
+```
+
+O script:
+
+- pede o token sem eco no terminal quando necessario;
+- atualiza apenas as linhas do escopo `@fprad0`;
+- cria ou reaproveita `${HOME}/.npmrc`;
+- aplica permissao `0600` no `${HOME}/.npmrc`;
+- grava o `.npmrc` apontando para `${GITHUB_PACKAGES_TOKEN}` por padrao;
+- valida acesso ao pacote;
+- mostra o comando final de `npx`.
+
+### Jeito rapido sem checkout local
+
+Use esta opcao quando a maquina ja consegue resolver o escopo `@fprad0` no GitHub Packages.
+
+```bash
+GITHUB_PACKAGES_TOKEN='SEU_TOKEN' npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
+```
+
+Para ler o token via stdin:
+
+```bash
+printf '%s' "$GITHUB_PACKAGES_TOKEN" | npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --token-stdin --validate
+```
+
+Para gravar token literal no `.npmrc` quando necessario:
+
+```bash
+bash ./scripts/configure-private-registry.sh --validate --store-token
+```
+
+## Publicacao pelo workflow
+
+O workflow de release usa:
+
+```text
+secrets.GH_PACKAGES_TOKEN
+```
+
+Entao a publicacao privada depende de:
+
+1. o secret existir no repositrio
+2. o PAT ter permissao de packages
+3. a conta dona do repositrio ter acesso ao namespace `@fprad0`
+
+## Instalar com npx
+
+```bat
+npx @fprad0/skill-master-mcp
+```
+
+Se quiser forcar a versao mais recente:
+
+```bat
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+## Fluxo recomendado para outro notebook Windows
+
+1. criar ou obter um token com `read:packages` e, se o repositrio for privado, `repo`;
+2. abrir PowerShell na pasta local do repositrio `skill-master-mcp`;
+3. rodar:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate
+```
+
+4. validar manualmente se quiser:
+
+```powershell
+npm view @fprad0/skill-master-mcp --registry=https://npm.pkg.github.com
+```
+
+5. configurar o cliente MCP para usar:
+
+```powershell
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+## Fluxo recomendado para outro notebook Linux
+
+```bash
+bash ./scripts/configure-private-registry.sh --validate
+npm view @fprad0/skill-master-mcp --registry=https://npm.pkg.github.com
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+## Exemplo para Claude Code
+
+Arquivo MCP:
+
+```json
+{
+  "mcpServers": {
+    "skill_master": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@fprad0/skill-master-mcp@latest"],
+      "env": {
+        "SKILL_MASTER_WORKSPACE": "C:\\Projetos\\link-your-biz"
+      }
+    }
+  }
+}
+```
+
+## Exemplo para Codex
+
+Bloco em `config.toml`:
+
+```toml
+[mcp_servers.skill_master]
+command = "C:\\Program Files\\nodejs\\npx.cmd"
+args = ["-y", "@fprad0/skill-master-mcp@latest"]
+startup_timeout_sec = 120
+
+[mcp_servers.skill_master.env]
+SKILL_MASTER_WORKSPACE = "C:\\Projetos\\link-your-biz"
+```
+
+## Atualizacao
+
+Quando o cliente estiver configurado com:
+
+```text
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+ele sempre tenta usar a versao mais recente do pacote publicado.
+
+Se houver cache antigo, rode:
+
+```bat
+npm cache clean --force
+```
+
+e reinicie o cliente MCP.
+
+## Diferenca para o modo git
+
+Modo `git`:
+
+- melhor para desenvolvimento do MCP;
+- permite `git pull`, `npm ci` e `npm run build`.
+
+Modo `npm privado`:
+
+- melhor para distribuir;
+- nao exige repositrio local;
+- nao deve depender de escrita dentro da pasta do pacote.
+
+Por isso o `skill_master` em modo pacote grava cache e contribuicoes em:
+
+```text
+%USERPROFILE%\.skill-master
+```