@fprad0/skill-master-mcp 0.0.11 → 1.0.0

package/VERSION.md

@@ -1,9 +1,9 @@
-# Versão
-
-Versão funcional planejada: `00.05`
-
-Versão técnica para empacotamento semântico: `0.0.11`
-
-## Observação
-
-O nome `00.05` será usado na comunicação e nos documentos. Para ferramentas que exigem SemVer, como npm e alguns fluxos de release, usar `0.0.11`.
+# Versão
+
+Versão funcional planejada: `1.0.0`
+
+Versão técnica para empacotamento semântico: `1.0.0`
+
+## Observação
+
+O nome `1.0.0` será usado na comunicação e nos documentos. Para ferramentas que exigem SemVer, como npm e alguns fluxos de release, usar `1.0.0`.

package/bin/lib/bootstrap-global-core.mjs

@@ -0,0 +1,34 @@
+import { OPERATION_EXIT_CODES } from './operation-result.mjs';
+
+function normalizeStatus(status) {
+  return Number.isInteger(status) ? status : 1;
+}
+
+export function evaluateBootstrapResult(stepResults = []) {
+  let exitCode = OPERATION_EXIT_CODES.ok;
+  let completedWithWarnings = false;
+
+  for (const step of stepResults) {
+    const status = normalizeStatus(step?.status);
+
+    if (status === OPERATION_EXIT_CODES.ok) {
+      continue;
+    }
+
+    if (step?.label === 'register-clients' && status === OPERATION_EXIT_CODES.warning) {
+      exitCode = OPERATION_EXIT_CODES.warning;
+      completedWithWarnings = true;
+      break;
+    }
+
+    exitCode = status;
+    completedWithWarnings = false;
+    break;
+  }
+
+  return {
+    exitCode,
+    completedWithWarnings,
+    completed: exitCode === OPERATION_EXIT_CODES.ok || exitCode === OPERATION_EXIT_CODES.warning,
+  };
+}

package/bin/lib/client-config.mjs

@@ -1,268 +1,293 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath } from 'node:url';
-
-export const DEFAULT_SERVER_ENV = {
-  SKILL_MASTER_UPDATE_CHANNEL: 'stable',
-};
-
-export function defaultClaudeConfigPath(home = os.homedir(), platform = process.platform) {
-  if (platform === 'win32') {
-    return path.join(process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
-  }
-
-  if (platform === 'darwin') {
-    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-  }
-
-  return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
-}
-
-export function defaultClientConfigPaths({
-  home = os.homedir(),
-  env = process.env,
-  platform = process.platform,
-} = {}) {
-  return {
-    codex: path.join(env.CODEX_HOME ?? path.join(home, '.codex'), 'config.toml'),
-    claude: defaultClaudeConfigPath(home, platform),
-    gemini: path.join(home, '.gemini', 'settings.json'),
-    antigravity: path.join(home, '.gemini', 'config', 'mcp_config.json'),
-  };
-}
-
-export function buildSkillMasterServerConfig({
-  rootDir,
-  nodeExecPath = process.execPath,
-  env = DEFAULT_SERVER_ENV,
-} = {}) {
-  const packageRoot = rootDir ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-  const serverEntry = path.join(packageRoot, 'bin', 'skill-master.mjs');
-
-  return {
-    command: nodeExecPath,
-    args: [serverEntry],
-    env: { ...env },
-    metadata: {
-      mode: 'absolute-node',
-      packageRoot,
-      serverEntry,
-    },
-  };
-}
-
-function tomlString(value) {
-  return JSON.stringify(String(value));
-}
-
-function tomlStringArray(values) {
-  return `[${values.map((value) => tomlString(value)).join(', ')}]`;
-}
-
-export function buildCodexBlock(serverConfig) {
-  const envEntries = Object.entries(serverConfig.env ?? {});
-  const envBlock = envEntries.length
-    ? `\n[mcp_servers.skill_master.env]\n${envEntries.map(([key, value]) => `${key} = ${tomlString(value)}`).join('\n')}\n`
-    : '';
-
-  return `
-[mcp_servers.skill_master]
-command = ${tomlString(serverConfig.command)}
-args = ${tomlStringArray(serverConfig.args ?? [])}
-startup_timeout_sec = 120
-${envBlock}`;
-}
-
-export function buildJsonMcpSnippet(serverConfig) {
-  return {
-    mcpServers: {
-      skill_master: {
-        command: serverConfig.command,
-        args: serverConfig.args ?? [],
-        env: serverConfig.env ?? {},
-      },
-    },
-  };
-}
-
-export function ensureParent(filePath) {
-  mkdirSync(path.dirname(filePath), { recursive: true });
-}
-
-function backupPath(filePath) {
-  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  return `${filePath}.invalid-${stamp}.bak`;
-}
-
-export function readJsonOrEmpty(filePath, { recoverInvalidJson = false } = {}) {
-  if (!existsSync(filePath)) return {};
-  const raw = readFileSync(filePath, 'utf8').trim();
-  if (!raw) return {};
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    if (recoverInvalidJson) {
-      copyFileSync(filePath, backupPath(filePath));
-      return {};
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Invalid JSON at ${filePath}: ${message}`);
-  }
-}
-
-export function writeJson(filePath, value) {
-  ensureParent(filePath);
-  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-}
-
-export function mergeMcpServer(filePath, serverConfig, options = {}) {
-  const current = readJsonOrEmpty(filePath, options);
-  const next = {
-    ...current,
-    mcpServers: {
-      ...(current.mcpServers ?? {}),
-      skill_master: buildJsonMcpSnippet(serverConfig).mcpServers.skill_master,
-    },
-  };
-  writeJson(filePath, next);
-}
-
-export function removeCodexSkillMasterBlock(content) {
-  const lines = String(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();
-}
-
-export function appendCodexServer(filePath, serverConfig, { force = false } = {}) {
-  ensureParent(filePath);
-  const current = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
-  if (current.includes('[mcp_servers.skill_master]') && !force) {
-    return false;
-  }
-  const base = force ? removeCodexSkillMasterBlock(current) : current.trimEnd();
-  writeFileSync(filePath, `${base}\n${buildCodexBlock(serverConfig)}`, 'utf8');
-  return true;
-}
-
-function normalizeSlashes(value) {
-  return String(value ?? '').replace(/\\/g, '/').toLowerCase();
-}
-
-function basename(value) {
-  const normalized = normalizeSlashes(value);
-  return normalized.split('/').pop() ?? '';
-}
-
-function isNodeCommand(command) {
-  const name = basename(command);
-  return name === 'node' || name === 'node.exe';
-}
-
-function hasSkillMasterEntryArg(args = []) {
-  return args.some((arg) => normalizeSlashes(arg).endsWith('/bin/skill-master.mjs'));
-}
-
-function hasLauncherArg(args = []) {
-  return args.some((arg) => {
-    const normalized = normalizeSlashes(arg);
-    return normalized.endsWith('/scripts/skill-master-launcher.ps1')
-      || normalized.endsWith('/scripts/skill-master-launcher.sh');
-  });
-}
-
-export function assessMcpServerConfig(server) {
-  if (!server?.command) {
-    return {
-      present: Boolean(server),
-      robust: false,
-      mode: server ? 'missing-command' : 'missing',
-      command: server?.command ?? null,
-    };
-  }
-
-  const command = String(server.command);
-  const args = Array.isArray(server.args) ? server.args : [];
-  const commandName = basename(command);
-  const normalizedCommand = normalizeSlashes(command);
-
-  if (isNodeCommand(command) && hasSkillMasterEntryArg(args)) {
-    return { present: true, robust: true, mode: 'absolute-node', command };
-  }
-
-  if (commandName === 'skill-master-mcp' || commandName === 'skill-master-mcp.cmd') {
-    return { present: true, robust: false, mode: 'path-bin', command };
-  }
-
-  if ((normalizedCommand.includes('powershell') || commandName === 'bash' || commandName === 'env') && hasLauncherArg(args)) {
-    return { present: true, robust: false, mode: 'launcher', command };
-  }
-
-  return { present: true, robust: false, mode: 'custom', command };
-}
-
-function parseTomlStringToken(token) {
-  const value = String(token ?? '').trim();
-  if (!value) return '';
-  if (value.startsWith('"')) {
-    try {
-      return JSON.parse(value);
-    } catch {
-      return value.slice(1, -1);
-    }
-  }
-  if (value.startsWith("'")) {
-    return value.slice(1, -1);
-  }
-  return value;
-}
-
-function parseTomlStringArray(value) {
-  const matches = [...String(value ?? '').matchAll(/"(?:\\.|[^"])*"|'[^']*'/g)];
-  return matches.map((match) => parseTomlStringToken(match[0]));
-}
-
-export function extractCodexSkillMasterServer(content) {
-  const lines = String(content ?? '').split('\n');
-  const block = [];
-  let collecting = false;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === '[mcp_servers.skill_master]') {
-      collecting = true;
-      continue;
-    }
-    if (collecting && trimmed.startsWith('[')) {
-      break;
-    }
-    if (collecting) block.push(line);
-  }
-
-  if (!block.length) return null;
-
-  const commandLine = block.find((line) => line.trim().startsWith('command'));
-  const argsLine = block.find((line) => line.trim().startsWith('args'));
-  const commandToken = commandLine?.match(/=\s*("(?:\\.|[^"])*"|'[^']*')/)?.[1] ?? null;
-  const command = commandToken ? parseTomlStringToken(commandToken) : null;
-  const args = argsLine ? parseTomlStringArray(argsLine.split('=').slice(1).join('=')) : [];
-
-  return command ? { command, args } : null;
-}
-
-export function assessCodexConfigContent(content) {
-  return assessMcpServerConfig(extractCodexSkillMasterServer(content));
-}
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_SERVER_ENV = {
+  SKILL_MASTER_UPDATE_CHANNEL: 'stable',
+};
+
+export function defaultClaudeConfigPath(home = os.homedir(), platform = process.platform) {
+  if (platform === 'win32') {
+    return path.join(process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+  }
+
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+
+  return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
+}
+
+export function defaultClientConfigPaths({
+  home = os.homedir(),
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  return {
+    codex: path.join(env.CODEX_HOME ?? path.join(home, '.codex'), 'config.toml'),
+    claude: defaultClaudeConfigPath(home, platform),
+    gemini: path.join(home, '.gemini', 'settings.json'),
+    antigravity: path.join(home, '.gemini', 'config', 'mcp_config.json'),
+  };
+}
+
+export function buildSkillMasterServerConfig({
+  rootDir,
+  nodeExecPath = process.execPath,
+  env = DEFAULT_SERVER_ENV,
+} = {}) {
+  const packageRoot = rootDir ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const serverEntry = path.join(packageRoot, 'bin', 'skill-master.mjs');
+
+  return {
+    command: nodeExecPath,
+    args: [serverEntry],
+    env: { ...env },
+    metadata: {
+      mode: 'absolute-node',
+      packageRoot,
+      serverEntry,
+    },
+  };
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function tomlStringArray(values) {
+  return `[${values.map((value) => tomlString(value)).join(', ')}]`;
+}
+
+export function buildCodexBlock(serverConfig) {
+  const envEntries = Object.entries(serverConfig.env ?? {});
+  const envBlock = envEntries.length
+    ? `\n[mcp_servers.skill_master.env]\n${envEntries.map(([key, value]) => `${key} = ${tomlString(value)}`).join('\n')}\n`
+    : '';
+
+  return `
+[mcp_servers.skill_master]
+command = ${tomlString(serverConfig.command)}
+args = ${tomlStringArray(serverConfig.args ?? [])}
+startup_timeout_sec = 120
+${envBlock}`;
+}
+
+export function buildJsonMcpSnippet(serverConfig) {
+  return {
+    mcpServers: {
+      skill_master: {
+        command: serverConfig.command,
+        args: serverConfig.args ?? [],
+        env: serverConfig.env ?? {},
+      },
+    },
+  };
+}
+
+export function buildClaudeCodeAddArgs(serverConfig, {
+  scope = 'user',
+  serverName = 'skill_master',
+} = {}) {
+  return [
+    'mcp',
+    'add',
+    serverName,
+    '--scope',
+    scope,
+    '--',
+    serverConfig.command,
+    ...(serverConfig.args ?? []),
+  ];
+}
+
+export function formatShellCommand(command, args = []) {
+  const quote = (value) => {
+    const text = String(value ?? '');
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) return text;
+    return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  };
+  return [command, ...args].map(quote).join(' ');
+}
+
+export function ensureParent(filePath) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function backupPath(filePath) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return `${filePath}.invalid-${stamp}.bak`;
+}
+
+export function readJsonOrEmpty(filePath, { recoverInvalidJson = false } = {}) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, 'utf8').trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    if (recoverInvalidJson) {
+      copyFileSync(filePath, backupPath(filePath));
+      return {};
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON at ${filePath}: ${message}`);
+  }
+}
+
+export function writeJson(filePath, value) {
+  ensureParent(filePath);
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export function mergeMcpServer(filePath, serverConfig, options = {}) {
+  const current = readJsonOrEmpty(filePath, options);
+  const next = {
+    ...current,
+    mcpServers: {
+      ...(current.mcpServers ?? {}),
+      skill_master: buildJsonMcpSnippet(serverConfig).mcpServers.skill_master,
+    },
+  };
+  writeJson(filePath, next);
+}
+
+export function removeCodexSkillMasterBlock(content) {
+  const lines = String(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();
+}
+
+export function appendCodexServer(filePath, serverConfig, { force = false } = {}) {
+  ensureParent(filePath);
+  const current = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+  if (current.includes('[mcp_servers.skill_master]') && !force) {
+    return false;
+  }
+  const base = force ? removeCodexSkillMasterBlock(current) : current.trimEnd();
+  writeFileSync(filePath, `${base}\n${buildCodexBlock(serverConfig)}`, 'utf8');
+  return true;
+}
+
+function normalizeSlashes(value) {
+  return String(value ?? '').replace(/\\/g, '/').toLowerCase();
+}
+
+function basename(value) {
+  const normalized = normalizeSlashes(value);
+  return normalized.split('/').pop() ?? '';
+}
+
+function isNodeCommand(command) {
+  const name = basename(command);
+  return name === 'node' || name === 'node.exe';
+}
+
+function hasSkillMasterEntryArg(args = []) {
+  return args.some((arg) => normalizeSlashes(arg).endsWith('/bin/skill-master.mjs'));
+}
+
+function hasLauncherArg(args = []) {
+  return args.some((arg) => {
+    const normalized = normalizeSlashes(arg);
+    return normalized.endsWith('/scripts/skill-master-launcher.ps1')
+      || normalized.endsWith('/scripts/skill-master-launcher.sh');
+  });
+}
+
+export function assessMcpServerConfig(server) {
+  if (!server?.command) {
+    return {
+      present: Boolean(server),
+      robust: false,
+      mode: server ? 'missing-command' : 'missing',
+      command: server?.command ?? null,
+    };
+  }
+
+  const command = String(server.command);
+  const args = Array.isArray(server.args) ? server.args : [];
+  const commandName = basename(command);
+  const normalizedCommand = normalizeSlashes(command);
+
+  if (isNodeCommand(command) && hasSkillMasterEntryArg(args)) {
+    return { present: true, robust: true, mode: 'absolute-node', command };
+  }
+
+  if (commandName === 'skill-master-mcp' || commandName === 'skill-master-mcp.cmd') {
+    return { present: true, robust: false, mode: 'path-bin', command };
+  }
+
+  if ((normalizedCommand.includes('powershell') || commandName === 'bash' || commandName === 'env') && hasLauncherArg(args)) {
+    return { present: true, robust: false, mode: 'launcher', command };
+  }
+
+  return { present: true, robust: false, mode: 'custom', command };
+}
+
+function parseTomlStringToken(token) {
+  const value = String(token ?? '').trim();
+  if (!value) return '';
+  if (value.startsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function parseTomlStringArray(value) {
+  const matches = [...String(value ?? '').matchAll(/"(?:\\.|[^"])*"|'[^']*'/g)];
+  return matches.map((match) => parseTomlStringToken(match[0]));
+}
+
+export function extractCodexSkillMasterServer(content) {
+  const lines = String(content ?? '').split('\n');
+  const block = [];
+  let collecting = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '[mcp_servers.skill_master]') {
+      collecting = true;
+      continue;
+    }
+    if (collecting && trimmed.startsWith('[')) {
+      break;
+    }
+    if (collecting) block.push(line);
+  }
+
+  if (!block.length) return null;
+
+  const commandLine = block.find((line) => line.trim().startsWith('command'));
+  const argsLine = block.find((line) => line.trim().startsWith('args'));
+  const commandToken = commandLine?.match(/=\s*("(?:\\.|[^"])*"|'[^']*')/)?.[1] ?? null;
+  const command = commandToken ? parseTomlStringToken(commandToken) : null;
+  const args = argsLine ? parseTomlStringArray(argsLine.split('=').slice(1).join('=')) : [];
+
+  return command ? { command, args } : null;
+}
+
+export function assessCodexConfigContent(content) {
+  return assessMcpServerConfig(extractCodexSkillMasterServer(content));
+}