@fprad0/skill-master-mcp 0.0.10 → 0.0.11

package/bin/skill-master-doctor.mjs

@@ -4,6 +4,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  assessCodexConfigContent,
+  assessMcpServerConfig,
+  defaultClientConfigPaths,
+} from './lib/client-config.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(here, '..');
@@ -19,6 +24,9 @@ Uso:
 
 Valida pacote, binarios, skills globais e registro MCP em Codex, Claude,
 Gemini e Antigravity. Nao publica versoes e nao altera configuracoes.
+
+O registro recomendado usa Node absoluto + bin/skill-master.mjs absoluto para
+evitar falhas de PATH em apps desktop no Windows, Linux e macOS.
 `);
   process.exit(0);
 }
@@ -49,25 +57,13 @@ const REQUIRED_BINS = [
   'skill-master-doctor',
 ];
 
-function defaultClaudeConfigPath() {
-  if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
-  }
-
-  if (process.platform === 'darwin') {
-    return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-  }
-
-  return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
-}
-
 function readJson(filePath) {
-  if (!existsSync(filePath)) return null;
+  if (!existsSync(filePath)) return { present: false, invalid: false, value: null };
   try {
     const raw = readFileSync(filePath, 'utf8').trim();
-    return raw ? JSON.parse(raw) : {};
+    return { present: true, invalid: false, value: raw ? JSON.parse(raw) : {} };
   } catch {
-    return null;
+    return { present: true, invalid: true, value: null };
   }
 }
 
@@ -80,26 +76,40 @@ function commandExists(command) {
 
 function jsonClientState(filePath) {
   const parsed = readJson(filePath);
-  const server = parsed?.mcpServers?.skill_master;
+  if (parsed.invalid) {
+    return {
+      filePath,
+      present: true,
+      configured: false,
+      mode: 'invalid-json',
+      command: null,
+    };
+  }
+
+  const server = parsed.value?.mcpServers?.skill_master;
+  const assessment = assessMcpServerConfig(server);
   return {
     filePath,
-    present: Boolean(parsed),
-    configured: server?.command === 'skill-master-mcp',
-    command: server?.command ?? null,
+    present: parsed.present,
+    configured: assessment.robust,
+    mode: assessment.mode,
+    command: assessment.command,
   };
 }
 
 function codexState(filePath) {
   if (!existsSync(filePath)) {
-    return { filePath, present: false, configured: false, command: null };
+    return { filePath, present: false, configured: false, mode: 'missing', command: null };
   }
 
   const content = readFileSync(filePath, 'utf8');
+  const assessment = assessCodexConfigContent(content);
   return {
     filePath,
     present: true,
-    configured: content.includes('[mcp_servers.skill_master]') && content.includes('command = "skill-master-mcp"'),
-    command: content.includes('skill-master-mcp') ? 'skill-master-mcp' : null,
+    configured: assessment.robust,
+    mode: assessment.mode,
+    command: assessment.command,
   };
 }
 
@@ -108,16 +118,18 @@ function resultLine(ok, label, detail) {
   return `[${marker}] ${label}${detail ? ` - ${detail}` : ''}`;
 }
 
-const packageJson = readJson(path.join(rootDir, 'package.json'));
+const packageJsonState = readJson(path.join(rootDir, 'package.json'));
+const packageJson = packageJsonState.value;
 const globalSkillsRoot = path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'), 'skills');
 const installedSkills = REQUIRED_GLOBAL_SKILLS.filter((skill) => existsSync(path.join(globalSkillsRoot, skill, 'SKILL.md')));
 const missingSkills = REQUIRED_GLOBAL_SKILLS.filter((skill) => !installedSkills.includes(skill));
 
+const clientPaths = defaultClientConfigPaths();
 const clients = [
-  ['Codex', codexState(path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'), 'config.toml'))],
-  ['Claude Desktop', jsonClientState(defaultClaudeConfigPath())],
-  ['Gemini CLI', jsonClientState(path.join(os.homedir(), '.gemini', 'settings.json'))],
-  ['Antigravity', jsonClientState(path.join(os.homedir(), '.gemini', 'config', 'mcp_config.json'))],
+  ['Codex', codexState(clientPaths.codex)],
+  ['Claude Desktop', jsonClientState(clientPaths.claude)],
+  ['Gemini CLI', jsonClientState(clientPaths.gemini)],
+  ['Antigravity', jsonClientState(clientPaths.antigravity)],
 ];
 
 const binResults = REQUIRED_BINS.map((bin) => [bin, commandExists(bin)]);
@@ -144,9 +156,9 @@ console.log(`- Skills root: ${globalSkillsRoot}`);
 console.log('');
 for (const [name, state] of clients) {
   const detail = state.configured
-    ? state.filePath
+    ? `${state.mode} em ${state.filePath}`
     : state.present
-      ? `presente, mas command=${state.command ?? 'nao encontrado'} em ${state.filePath}`
+      ? `presente, mas mode=${state.mode} command=${state.command ?? 'nao encontrado'} em ${state.filePath}`
       : `ausente em ${state.filePath}`;
   console.log(resultLine(state.configured, `${name} configurado`, detail));
 }
@@ -158,6 +170,7 @@ console.log(resultLine(ready, 'Readiness global', ready ? 'pronto' : 'requer aca
 if (!ready) {
   console.log('');
   console.log('Proximo comando recomendado:');
+  console.log('  skill-master-register-clients --apply-all --force');
   console.log('  skill-master-menu --run bootstrap-global --yes');
   console.log('');
   console.log('Depois reinicie Codex, Claude, Gemini e Antigravity.');

package/bin/skill-master-install-global-skills.mjs

@@ -24,7 +24,7 @@ Uso:
   skill-master-install-global-skills --overwrite
   skill-master-install-global-skills --dry-run
   skill-master-install-global-skills --target ~/.codex/skills
-  skill-master-install-global-skills --source ./docs/skill-candidates/v0.0.10
+  skill-master-install-global-skills --source ./docs/skill-candidates/v0.0.11
 
 Instala as skills globais embutidas em CODEX_HOME/skills ou ~/.codex/skills.
 Quando --source aponta para docs/skill-candidates, todas as pastas versionadas v*

package/bin/skill-master-register-clients.mjs

@@ -1,7 +1,17 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
+import path, { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  appendCodexServer,
+  buildCodexBlock,
+  buildJsonMcpSnippet,
+  buildSkillMasterServerConfig,
+  defaultClientConfigPaths,
+  mergeMcpServer,
+  writeJson,
+} from './lib/client-config.mjs';
 
 const args = process.argv.slice(2);
 const has = (flag) => args.includes(flag);
@@ -10,6 +20,9 @@ const readValue = (flag, fallback) => {
   return index >= 0 ? args[index + 1] : fallback;
 };
 
+const here = dirname(fileURLToPath(import.meta.url));
+const rootDir = dirname(here);
+
 if (has('--help')) {
   console.log(`Skill Master client registration
 
@@ -22,27 +35,19 @@ Uso:
   skill-master-register-clients --apply-all
   skill-master-register-clients --apply-codex --force
 
-Registra o servidor MCP skill_master como stdio usando o binario global:
-  skill-master-mcp
+Registra o servidor MCP skill_master como stdio usando Node absoluto e o
+entrypoint absoluto do pacote. Isso evita falhas de PATH em Windows, Linux,
+macOS e apps desktop que nao herdam o terminal.
 `);
   process.exit(0);
 }
 
-const home = os.homedir();
-const snippetsDir = readValue('--snippets-dir', path.join(home, '.skill-master', 'client-configs'));
-const codexConfig = readValue('--codex-config', path.join(process.env.CODEX_HOME ?? path.join(home, '.codex'), 'config.toml'));
-const defaultClaudeConfig = () => {
-  if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
-  }
-  if (process.platform === 'darwin') {
-    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-  }
-  return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
-};
-const claudeConfig = readValue('--claude-config', defaultClaudeConfig());
-const geminiConfig = readValue('--gemini-config', path.join(home, '.gemini', 'settings.json'));
-const antigravityConfig = readValue('--antigravity-config', path.join(home, '.gemini', 'config', 'mcp_config.json'));
+const clientPaths = defaultClientConfigPaths();
+const snippetsDir = readValue('--snippets-dir', path.join(process.env.SKILL_MASTER_HOME ?? path.join(os.homedir(), '.skill-master'), 'client-configs'));
+const codexConfig = readValue('--codex-config', clientPaths.codex);
+const claudeConfig = readValue('--claude-config', clientPaths.claude);
+const geminiConfig = readValue('--gemini-config', clientPaths.gemini);
+const antigravityConfig = readValue('--antigravity-config', clientPaths.antigravity);
 
 const applyAll = has('--apply-all');
 const applyCodex = applyAll || has('--apply-codex');
@@ -51,102 +56,16 @@ const applyGemini = applyAll || has('--apply-gemini');
 const applyAntigravity = applyAll || has('--apply-antigravity');
 const writeSnippets = applyAll || has('--write-snippets') || !(applyCodex || applyClaude || applyGemini || applyAntigravity);
 const force = has('--force');
-
-const mcpServer = {
-  command: 'skill-master-mcp',
-  args: [],
-  env: {
-    SKILL_MASTER_UPDATE_CHANNEL: 'stable',
-  },
-};
-
-const codexBlock = `
-[mcp_servers.skill_master]
-command = "skill-master-mcp"
-startup_timeout_sec = 120
-
-[mcp_servers.skill_master.env]
-SKILL_MASTER_UPDATE_CHANNEL = "stable"
-`;
-
-const claudeSnippet = {
-  mcpServers: {
-    skill_master: mcpServer,
-  },
-};
-
-const geminiSnippet = {
-  mcpServers: {
-    skill_master: mcpServer,
-  },
-};
-
-const antigravitySnippet = {
-  mcpServers: {
-    skill_master: mcpServer,
-  },
-};
-
-const ensureParent = (filePath) => mkdirSync(path.dirname(filePath), { recursive: true });
-
-const readJsonOrEmpty = (filePath) => {
-  if (!existsSync(filePath)) return {};
-  const raw = readFileSync(filePath, 'utf8').trim();
-  return raw ? JSON.parse(raw) : {};
-};
-
-const writeJson = (filePath, value) => {
-  ensureParent(filePath);
-  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-};
-
-const mergeMcpServer = (filePath) => {
-  const current = readJsonOrEmpty(filePath);
-  const next = {
-    ...current,
-    mcpServers: {
-      ...(current.mcpServers ?? {}),
-      skill_master: mcpServer,
-    },
-  };
-  writeJson(filePath, next);
-};
+const serverConfig = buildSkillMasterServerConfig({ rootDir });
+const codexBlock = buildCodexBlock(serverConfig);
+const jsonSnippet = buildJsonMcpSnippet(serverConfig);
 
 const writeSnippetsFiles = () => {
   mkdirSync(snippetsDir, { recursive: true });
   writeFileSync(path.join(snippetsDir, 'codex.config.toml'), codexBlock.trimStart(), 'utf8');
-  writeJson(path.join(snippetsDir, 'claude_desktop_config.skill_master.json'), claudeSnippet);
-  writeJson(path.join(snippetsDir, 'gemini.settings.skill_master.json'), geminiSnippet);
-  writeJson(path.join(snippetsDir, 'antigravity.mcp_config.skill_master.json'), antigravitySnippet);
-};
-
-const removeCodexBlock = (content) => {
-  const lines = content.split('\n');
-  const kept = [];
-  let skipping = false;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === '[mcp_servers.skill_master]') {
-      skipping = true;
-      continue;
-    }
-    if (skipping && trimmed.startsWith('[') && !trimmed.startsWith('[mcp_servers.skill_master')) {
-      skipping = false;
-    }
-    if (!skipping) kept.push(line);
-  }
-  return kept.join('\n').trimEnd();
-};
-
-const appendCodex = () => {
-  ensureParent(codexConfig);
-  const current = existsSync(codexConfig) ? readFileSync(codexConfig, 'utf8') : '';
-  if (current.includes('[mcp_servers.skill_master]') && !force) {
-    return false;
-  }
-  const base = force ? removeCodexBlock(current) : current.trimEnd();
-  writeFileSync(codexConfig, `${base}\n${codexBlock}`, 'utf8');
-  return true;
+  writeJson(path.join(snippetsDir, 'claude_desktop_config.skill_master.json'), jsonSnippet);
+  writeJson(path.join(snippetsDir, 'gemini.settings.skill_master.json'), jsonSnippet);
+  writeJson(path.join(snippetsDir, 'antigravity.mcp_config.skill_master.json'), jsonSnippet);
 };
 
 const actions = [];
@@ -155,22 +74,24 @@ if (writeSnippets) {
   actions.push(`snippets written to ${snippetsDir}`);
 }
 if (applyCodex) {
-  actions.push(appendCodex() ? `Codex registered at ${codexConfig}` : `Codex already had skill_master at ${codexConfig}`);
+  actions.push(appendCodexServer(codexConfig, serverConfig, { force }) ? `Codex registered at ${codexConfig}` : `Codex already had skill_master at ${codexConfig}`);
 }
 if (applyClaude) {
-  mergeMcpServer(claudeConfig);
+  mergeMcpServer(claudeConfig, serverConfig, { recoverInvalidJson: force });
   actions.push(`Claude config merged at ${claudeConfig}`);
 }
 if (applyGemini) {
-  mergeMcpServer(geminiConfig);
+  mergeMcpServer(geminiConfig, serverConfig, { recoverInvalidJson: force });
   actions.push(`Gemini config merged at ${geminiConfig}`);
 }
 if (applyAntigravity) {
-  mergeMcpServer(antigravityConfig);
+  mergeMcpServer(antigravityConfig, serverConfig, { recoverInvalidJson: force });
   actions.push(`Antigravity config merged at ${antigravityConfig}`);
 }
 
 console.log('[skill_master] Client registration');
+console.log(`- Command: ${serverConfig.command}`);
+console.log(`- Args: ${serverConfig.args.join(' ')}`);
 for (const action of actions) {
   console.log(`- ${action}`);
 }

package/docs/operations/GUIA_MULTI_COMPUTADOR.md

@@ -0,0 +1,255 @@
+# Guia Multi-Computador - Skill Master MCP
+
+## 1. Cenario
+
+Voce quer usar o mesmo MCP `skill_master` em varios computadores, mantendo todos atualizados e escolhendo o canal de distribuicao mais adequado para cada caso.
+
+## 2. Modelos recomendados
+
+Hoje existem dois caminhos validos.
+
+### Modelo A - npm publico
+
+Melhor para:
+
+- notebooks novos
+- instalacao rapida
+- ambientes onde o usuario nao deve clonar o repositorio
+- Claude, Codex, Gemini e clientes MCP que aceitam `npx`
+
+Base:
+
+```bash
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+### Modelo B - clone + launcher com auto-update
+
+Melhor para:
+
+- desenvolvimento do MCP
+- testes de `stable` e `beta`
+- controle maior sobre manifests e atualizacao por `git pull --ff-only`
+- ambiente com repo privado
+
+Cada computador tera:
+
+- clone local do repositorio
+- `git`
+- `node` 18+
+- launcher configurado no cliente MCP
+- configuracao local em `%USERPROFILE%/.skill-master/config.json` no Windows ou `~/.skill-master/config.json` no Linux/macOS
+
+Quando o menu detectar que o computador ainda nao esta globalmente pronto, ele vai mostrar o caminho de bootstrap e o atalho unico:
+
+```bash
+skill-master-bootstrap-global
+```
+
+Esse atalho instala as skills globais embutidas e registra Codex, Claude, Gemini e Antigravity para reconhecer `skill_master` como parte do sistema no cliente local.
+
+A partir da correcao multi-OS, o registro recomendado nao depende mais de `PATH`. O registrador grava o Node.js absoluto como `command` e o `bin/skill-master.mjs` absoluto como `args`, o que evita falhas comuns em Windows, Linux, macOS e apps desktop que nao herdam o ambiente do terminal.
+
+A partir da preparacao `0.0.11`, use o doctor para validar notebooks novos:
+
+```bash
+skill-master-menu --run doctor
+skill-master-menu --run bootstrap-global --yes
+```
+
+O bootstrap registra Codex, Claude Desktop, Gemini CLI e Antigravity. Depois, reinicie os clientes.
+
+## 3. Instalacao em um novo computador
+
+### 3.1 Opcao rapida - npm publico
+
+#### Windows
+
+```powershell
+npm install -g @fprad0/skill-master-mcp
+```
+
+ou:
+
+```powershell
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+#### Linux / macOS
+
+```bash
+npm install -g @fprad0/skill-master-mcp
+```
+
+ou:
+
+```bash
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+### 3.2 Opcao controlada - clone local
+
+Pre-requisitos:
+
+- Git instalado
+- Node.js 18+
+- acesso ao GitHub
+- token read-only se o repositorio for privado
+
+Clone:
+
+```powershell
+cd C:\Users\CDT\Documents
+git clone https://github.com/FPrad0/skill-master-mcp.git
+cd skill-master-mcp
+npm ci
+npm run build
+```
+
+### 3.3 Configuracao local
+
+Criar:
+
+```text
+C:\Users\<USER>\.skill-master\config.json
+```
+
+Modelo:
+
+```json
+{
+  "channel": "stable",
+  "autoUpdate": true,
+  "updateMode": "on-start",
+  "manifestUrl": "https://raw.githubusercontent.com/FPrad0/skill-master-mcp/main/manifests/channels/stable.json",
+  "localSkillRoots": [
+    "%USERPROFILE%/.codex/skills",
+    "%USERPROFILE%/.agents/skills"
+  ],
+  "allowWebSources": false
+}
+```
+
+## 4. Configuracao do cliente MCP
+
+No modelo npm global, prefira sempre o registro gerado por `skill-master-register-clients`, porque ele usa caminhos absolutos.
+
+No modelo clone + launcher, o launcher ainda e valido para desenvolvimento, mas o doctor vai classificar esse modo como `launcher`, nao como o modo robusto de pacote global.
+
+Exemplo robusto para Codex:
+
+```toml
+[mcp_servers.skill_master]
+command = "C:\\Program Files\\nodejs\\node.exe"
+args = ["C:\\Users\\CDT\\AppData\\Roaming\\npm\\node_modules\\@fprad0\\skill-master-mcp\\bin\\skill-master.mjs"]
+startup_timeout_sec = 120
+
+[mcp_servers.skill_master.env]
+SKILL_MASTER_UPDATE_CHANNEL = "stable"
+```
+
+Para migrar clientes antigos que ainda usam `skill-master-mcp` via PATH, `npx` ou launcher local:
+
+```bash
+skill-master-register-clients --apply-all --force
+skill-master-menu --run doctor
+```
+
+No modelo clone + launcher, o cliente deve chamar o launcher, nao o `dist/index.js` diretamente.
+
+Exemplo conceitual:
+
+```json
+{
+  "mcpServers": {
+    "skill_master": {
+      "command": "powershell",
+      "args": [
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "C:/Users/CDT/Documents/skill-master-mcp/scripts/skill-master-launcher.ps1"
+      ]
+    }
+  }
+}
+```
+
+## 5. Como as atualizacoes chegam automaticamente
+
+### No modelo npm publico
+
+1. voce publica uma nova versao no npm publico
+2. a maquina cliente usa `@latest`
+3. no proximo `npx` ou reinstalacao, a nova versao e resolvida
+
+### No modelo clone + launcher
+
+1. voce faz push no GitHub
+2. voce atualiza o manifesto `stable.json`
+3. o usuario abre o MCP
+4. o launcher verifica o manifesto
+5. se houver versao nova e o clone local estiver limpo, o launcher atualiza
+6. o MCP inicia ja atualizado
+
+## 6. Como publicar uma atualizacao
+
+### Caminho publico
+
+1. subir a nova versao para `main`
+2. publicar pelo workflow `Publish Skill Master to npmjs` somente com autorizacao explicita
+3. validar com `npm view` e `npx`
+
+### Caminho clone + launcher
+
+1. subir a nova versao para `main`
+2. atualizar `manifests/channels/stable.json`
+3. criar release/tag quando fizer sentido
+4. deixar o launcher puxar com `git pull --ff-only`
+
+## 7. Estrategia para varios usuarios
+
+### Poucos usuarios tecnicos
+
+Use clone privado + launcher. E a rota com mais controle.
+
+### Varios usuarios sem perfil tecnico
+
+Use npm publico.
+
+Se for necessario restringir distribuicao, evolua para:
+
+- pacote npm privado
+- instalador/bundle
+- MCP remoto
+
+### Equipe ou empresa
+
+Evoluir para:
+
+- GitHub Packages com permissoes
+- workflow de release
+- canais `stable` e `beta`
+- logs e telemetria minima opcional
+
+## 8. Manutencao
+
+Recomendacoes:
+
+- manter changelog curto
+- nunca quebrar configuracao sem migracao
+- testar update em uma maquina secundaria antes de mover `stable`
+- manter `beta` para validacao
+- documentar breaking changes
+
+## 9. Quando nao atualizar automaticamente
+
+No modelo clone + launcher, o updater deve recusar atualizacao automatica quando:
+
+- houver arquivos locais modificados
+- o GitHub estiver inacessivel
+- o manifesto estiver invalido
+- houver mudanca de versao de Node nao atendida
+- `npm ci` ou build falhar
+
+Nesses casos, ele deve iniciar a versao local e mostrar o status pela ferramenta `skill_master_sync_status`.