@fprad0/skill-master-mcp 0.0.11 → 1.0.0

package/bin/lib/operation-result.mjs

@@ -0,0 +1,59 @@
+export const OPERATION_EXIT_CODES = {
+  ok: 0,
+  warning: 10,
+  error: 20,
+  fatal: 30,
+};
+
+export function classifyOperationResult(code) {
+  const numericCode = Number.isFinite(Number(code)) ? Number(code) : 1;
+
+  if (numericCode === OPERATION_EXIT_CODES.ok) {
+    return { kind: 'ok', code: numericCode };
+  }
+
+  if (numericCode === OPERATION_EXIT_CODES.warning) {
+    return { kind: 'warning', code: numericCode };
+  }
+
+  if (numericCode >= OPERATION_EXIT_CODES.fatal) {
+    return { kind: 'fatal', code: numericCode };
+  }
+
+  return { kind: 'error', code: numericCode };
+}
+
+export function buildOperationResultCopy(code) {
+  const result = classifyOperationResult(code);
+
+  if (result.kind === 'ok') {
+    return {
+      kind: result.kind,
+      code: result.code,
+      frameTitle: 'result-ok',
+      heading: 'SUBROUTINE COMPLETE',
+      summary: 'Comando concluido com sucesso.',
+      next: 'workflow liberado para a proxima acao',
+    };
+  }
+
+  if (result.kind === 'warning') {
+    return {
+      kind: result.kind,
+      code: result.code,
+      frameTitle: 'result-warn',
+      heading: 'SUBROUTINE COMPLETE WITH WARNINGS',
+      summary: 'Comando concluido com avisos.',
+      next: 'workflow liberado, mas existe uma acao recomendada',
+    };
+  }
+
+  return {
+    kind: result.kind,
+    code: result.code,
+    frameTitle: 'result-error',
+    heading: 'SUBROUTINE FAILED',
+    summary: `Comando terminou com codigo ${result.code}.`,
+    next: 'verifique o log acima antes de continuar',
+  };
+}

package/bin/lib/register-clients-core.mjs

@@ -0,0 +1,247 @@
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { formatShellCommand } from './client-config.mjs';
+import { OPERATION_EXIT_CODES } from './operation-result.mjs';
+
+function trimOutput(value) {
+  return String(value ?? '').trim();
+}
+
+function normalizeProcessResult(result = {}) {
+  return {
+    status: Number.isInteger(result.status) ? result.status : null,
+    signal: result.signal ?? null,
+    stdout: trimOutput(result.stdout),
+    stderr: trimOutput(result.stderr),
+    error: result.error
+      ? {
+          code: result.error.code ?? null,
+          message: result.error.message ?? String(result.error),
+        }
+      : null,
+  };
+}
+
+function firstNonEmpty(values) {
+  return values.map((value) => trimOutput(value)).find(Boolean) ?? '';
+}
+
+function quoteDetail(label, value) {
+  return value ? `${label}: ${value}` : null;
+}
+
+function looksLikePath(command) {
+  return /[\\/]/.test(command) || path.isAbsolute(command);
+}
+
+function dedupe(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+export function buildClaudeCodeCommandCandidates(command = 'claude', { platform = process.platform } = {}) {
+  const candidates = [command];
+  if (platform === 'win32' && !looksLikePath(command) && !command.toLowerCase().endsWith('.cmd')) {
+    candidates.push(`${command}.cmd`);
+  }
+  return dedupe(candidates);
+}
+
+export function runCapturedCommand(command, args, {
+  spawnSyncImpl = spawnSync,
+  env = process.env,
+} = {}) {
+  return normalizeProcessResult(spawnSyncImpl(command, args, {
+    encoding: 'utf8',
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }));
+}
+
+export function resolveClaudeCodeCommand(command = 'claude', {
+  platform = process.platform,
+  spawnSyncImpl = spawnSync,
+  env = process.env,
+} = {}) {
+  const candidates = buildClaudeCodeCommandCandidates(command, { platform });
+
+  for (const candidate of candidates) {
+    if (looksLikePath(candidate)) {
+      return {
+        found: true,
+        command: candidate,
+        source: 'explicit',
+        tried: candidates,
+      };
+    }
+
+    const lookupCommand = platform === 'win32' ? 'where' : 'which';
+    const lookupResult = runCapturedCommand(lookupCommand, [candidate], {
+      spawnSyncImpl,
+      env,
+    });
+
+    if (lookupResult.status === 0) {
+      const resolvedPath = firstNonEmpty(lookupResult.stdout.split(/\r?\n/));
+      return {
+        found: true,
+        command: resolvedPath || candidate,
+        source: lookupCommand,
+        tried: candidates,
+      };
+    }
+  }
+
+  return {
+    found: false,
+    command: null,
+    source: null,
+    tried: candidates,
+  };
+}
+
+function detectClaudeCodeFailureKind({ versionProbe, listProbe, addResult }) {
+  const errorCode = addResult.error?.code ?? listProbe.error?.code ?? versionProbe.error?.code ?? null;
+  const combinedOutput = [
+    versionProbe.stderr,
+    listProbe.stderr,
+    listProbe.stdout,
+    addResult.stderr,
+    addResult.stdout,
+  ].join('\n').toLowerCase();
+
+  if (errorCode === 'ENOENT') {
+    return 'cli-missing';
+  }
+
+  if (versionProbe.status !== 0) {
+    return 'cli-not-runnable';
+  }
+
+  if (
+    combinedOutput.includes('unknown command')
+    || combinedOutput.includes('command not found')
+    || combinedOutput.includes('invalid choice')
+    || combinedOutput.includes('no such command')
+  ) {
+    return 'mcp-subcommand-missing';
+  }
+
+  if (listProbe.status !== 0) {
+    return 'mcp-list-failed';
+  }
+
+  return 'registration-failed';
+}
+
+export function classifyClaudeCodeResult({
+  attemptedCommand,
+  addArgs,
+  versionProbe,
+  listProbe,
+  addResult,
+}) {
+  const manualCommand = formatShellCommand(attemptedCommand, addArgs);
+
+  if (addResult.status === 0) {
+    return {
+      key: 'claude-code',
+      client: 'Claude Code',
+      status: 'ok',
+      message: `Claude Code registered via ${manualCommand}`,
+      next: null,
+    };
+  }
+
+  const kind = detectClaudeCodeFailureKind({ versionProbe, listProbe, addResult });
+  const summaryOutput = firstNonEmpty([
+    addResult.stderr,
+    addResult.stdout,
+    listProbe.stderr,
+    listProbe.stdout,
+    versionProbe.stderr,
+    versionProbe.stdout,
+  ]);
+  const details = [
+    versionProbe.status === 0
+      ? quoteDetail('CLI', firstNonEmpty([versionProbe.stdout, 'ok']))
+      : quoteDetail('CLI probe', versionProbe.error?.message ?? `codigo ${versionProbe.status ?? 'unknown'}`),
+    listProbe.status === 0
+      ? quoteDetail('MCP list', 'ok')
+      : quoteDetail('MCP list', listProbe.error?.message ?? `codigo ${listProbe.status ?? 'unknown'}`),
+    addResult.error
+      ? quoteDetail('Add error', addResult.error.message)
+      : quoteDetail('Add exit', String(addResult.status ?? 'unknown')),
+    summaryOutput ? quoteDetail('Detalhe', summaryOutput) : null,
+  ].filter(Boolean);
+
+  let message;
+  if (kind === 'cli-missing') {
+    message = `Claude Code CLI nao encontrado. Registro manual pendente: ${manualCommand}`;
+  } else if (kind === 'cli-not-runnable') {
+    message = `Claude Code CLI encontrado, mas nao executou corretamente. ${details.join(' | ')}`;
+  } else if (kind === 'mcp-subcommand-missing') {
+    message = `Claude Code CLI encontrado, mas o subcomando MCP nao respondeu como esperado. ${details.join(' | ')}`;
+  } else if (kind === 'mcp-list-failed') {
+    message = `Claude Code CLI encontrado, mas 'claude mcp list' falhou antes do registro. ${details.join(' | ')}`;
+  } else {
+    message = `Claude Code CLI encontrado, mas o registro falhou. ${details.join(' | ')}`;
+  }
+
+  return {
+    key: 'claude-code',
+    client: 'Claude Code',
+    status: 'warning',
+    message,
+    next: `Execute manualmente: ${manualCommand}`,
+    diagnostic: kind,
+  };
+}
+
+export function determineRegistrationExitCode(results, {
+  applyAll = false,
+  selectedClients = [],
+} = {}) {
+  if (results.some((result) => result.status === 'fatal')) {
+    return OPERATION_EXIT_CODES.fatal;
+  }
+
+  if (results.some((result) => result.status === 'error')) {
+    return OPERATION_EXIT_CODES.error;
+  }
+
+  const warnings = results.filter((result) => result.status === 'warning');
+  if (!warnings.length) {
+    return OPERATION_EXIT_CODES.ok;
+  }
+
+  const onlyClaudeCodeSelected = selectedClients.length === 1 && selectedClients[0] === 'claude-code';
+  if (onlyClaudeCodeSelected) {
+    return OPERATION_EXIT_CODES.error;
+  }
+
+  const warningKeys = new Set(warnings.map((result) => result.key));
+  const successCount = results.filter((result) => result.status === 'ok').length;
+
+  if (applyAll && successCount > 0 && warningKeys.size === 1 && warningKeys.has('claude-code')) {
+    return OPERATION_EXIT_CODES.warning;
+  }
+
+  return OPERATION_EXIT_CODES.error;
+}
+
+export function summarizeRegistrationResults(results, exitCode) {
+  const next = results.map((result) => result.next).find(Boolean) ?? 'reinicie os clientes MCP apos o registro';
+
+  return {
+    result: exitCode === OPERATION_EXIT_CODES.ok
+      ? 'ok'
+      : exitCode === OPERATION_EXIT_CODES.warning
+        ? 'warning'
+        : 'error',
+    applied: results.filter((result) => result.status === 'ok').length,
+    warnings: results.filter((result) => result.status === 'warning').length,
+    failed: results.filter((result) => result.status === 'error' || result.status === 'fatal').length,
+    next,
+  };
+}

package/bin/lib/skill-installation.mjs

@@ -0,0 +1,215 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_PROJECT_SKILL_ROOTS = [
+  '.agents/skills',
+  '.codex/skills',
+  '.claude/skills',
+  '.gemini/skills',
+];
+
+export function listSkillSources(sourcePath) {
+  const entries = readdirSync(sourcePath, { withFileTypes: true });
+  const directSkills = entries
+    .filter((entry) => entry.isDirectory() && existsSync(path.join(sourcePath, entry.name, 'SKILL.md')))
+    .map((entry) => ({ name: entry.name, path: path.join(sourcePath, entry.name) }));
+
+  if (directSkills.length) {
+    return directSkills.sort((left, right) => left.name.localeCompare(right.name));
+  }
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .flatMap((entry) => {
+      const versionPath = path.join(sourcePath, entry.name);
+      return readdirSync(versionPath, { withFileTypes: true })
+        .filter((skillEntry) => skillEntry.isDirectory() && existsSync(path.join(versionPath, skillEntry.name, 'SKILL.md')))
+        .map((skillEntry) => ({ name: skillEntry.name, path: path.join(versionPath, skillEntry.name) }));
+    })
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function parseRootList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function normalizeProjectSkillRoots(projectRoot, roots = DEFAULT_PROJECT_SKILL_ROOTS) {
+  const uniqueRoots = Array.from(new Set(roots.map((root) => {
+    const normalized = root.replace(/\\/g, '/');
+    return path.isAbsolute(normalized) ? normalized : normalized.replace(/^\.\//, '');
+  })));
+  return uniqueRoots.map((root) => ({
+    relative: root,
+    absolute: path.isAbsolute(root) ? root : path.resolve(projectRoot, root),
+  }));
+}
+
+export function installSkillsToTarget({ skills, target, overwrite = false, dryRun = false }) {
+  if (!dryRun) {
+    mkdirSync(target, { recursive: true });
+  }
+
+  const installed = [];
+  const skipped = [];
+
+  for (const skill of skills) {
+    const destination = path.join(target, skill.name);
+    if (existsSync(destination) && !overwrite) {
+      skipped.push(skill.name);
+      continue;
+    }
+
+    if (!dryRun) {
+      cpSync(skill.path, destination, { recursive: true, force: overwrite });
+    }
+    installed.push(skill.name);
+  }
+
+  return { target, installed, skipped };
+}
+
+export function buildProjectSkillCatalog({
+  projectRoot,
+  skillRoots,
+  skills,
+  packageName,
+  packageVersion,
+}) {
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    packageName,
+    packageVersion,
+    projectRoot,
+    skillRoots: skillRoots.map((root) => root.relative),
+    skillCount: Array.from(new Set(skills.map((skill) => skill.name))).length,
+    skills: Array.from(new Set(skills.map((skill) => skill.name))).sort(),
+  };
+}
+
+export function writeProjectSkillCatalog({ projectRoot, catalog, catalogPath = '.skill-master/catalog.json', dryRun = false }) {
+  const absolutePath = path.isAbsolute(catalogPath)
+    ? catalogPath
+    : path.resolve(projectRoot, catalogPath);
+
+  if (!dryRun) {
+    mkdirSync(path.dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, `${JSON.stringify(catalog, null, 2)}\n`, 'utf8');
+  }
+
+  return absolutePath;
+}
+
+export function syncProjectPackageJson({
+  projectRoot,
+  skillRoots,
+  catalogPath = '.skill-master/catalog.json',
+  packageName,
+  packageVersion,
+  createIfMissing = false,
+  dryRun = false,
+}) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const packageJsonExists = existsSync(packageJsonPath);
+
+  if (!packageJsonExists && !createIfMissing) {
+    return { path: packageJsonPath, status: 'missing' };
+  }
+
+  const current = packageJsonExists
+    ? JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    : { private: true };
+
+  const scripts = current.scripts && typeof current.scripts === 'object' ? current.scripts : {};
+  const installScript = 'skill-master-install-project-skills --sync-package-json';
+
+  const next = {
+    ...current,
+    scripts: {
+      ...scripts,
+      'skill-master:install-project-skills': scripts['skill-master:install-project-skills'] ?? installScript,
+    },
+    skillMaster: {
+      ...(current.skillMaster && typeof current.skillMaster === 'object' ? current.skillMaster : {}),
+      package: packageName,
+      packageVersion,
+      projectSkillRoots: skillRoots.map((root) => root.relative),
+      projectSkillCatalog: catalogPath,
+      installCommand: installScript,
+    },
+  };
+
+  if (!dryRun) {
+    writeFileSync(packageJsonPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  }
+
+  if (dryRun) {
+    return { path: packageJsonPath, status: packageJsonExists ? 'would-update' : 'would-create' };
+  }
+
+  return { path: packageJsonPath, status: packageJsonExists ? 'updated' : 'created' };
+}
+
+export function installProjectSkills({
+  source,
+  projectRoot,
+  roots = DEFAULT_PROJECT_SKILL_ROOTS,
+  overwrite = false,
+  dryRun = false,
+  writeCatalog = true,
+  syncPackageJson = true,
+  createPackageJson = false,
+  catalogPath = '.skill-master/catalog.json',
+  packageName,
+  packageVersion,
+}) {
+  const skills = listSkillSources(source);
+  const skillRoots = normalizeProjectSkillRoots(projectRoot, roots);
+  const targets = skillRoots.map((root) => installSkillsToTarget({
+    skills,
+    target: root.absolute,
+    overwrite,
+    dryRun,
+  }));
+  const catalog = buildProjectSkillCatalog({
+    projectRoot,
+    skillRoots,
+    skills,
+    packageName,
+    packageVersion,
+  });
+  const writtenCatalogPath = writeCatalog
+    ? writeProjectSkillCatalog({ projectRoot, catalog, catalogPath, dryRun })
+    : null;
+  const packageJson = syncPackageJson
+    ? syncProjectPackageJson({
+      projectRoot,
+      skillRoots,
+      catalogPath,
+      packageName,
+      packageVersion,
+      createIfMissing: createPackageJson,
+      dryRun,
+    })
+    : { path: path.join(projectRoot, 'package.json'), status: 'skipped' };
+
+  return {
+    source,
+    projectRoot,
+    roots: skillRoots,
+    skills,
+    targets,
+    catalogPath: writtenCatalogPath,
+    packageJson,
+  };
+}

package/bin/lib/update-cli-core.mjs

@@ -0,0 +1,117 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { formatShellCommand } from './client-config.mjs';
+import { OPERATION_EXIT_CODES } from './operation-result.mjs';
+
+export const DEFAULT_UPDATE_PACKAGE = '@fprad0/skill-master-mcp@latest';
+export const DEFAULT_UPDATE_REGISTRY = 'https://registry.npmjs.org';
+
+export function readOption(args, name, fallback) {
+  const index = args.indexOf(name);
+  if (index === -1) {
+    return fallback;
+  }
+
+  return args[index + 1] || fallback;
+}
+
+export function buildInstallArgs(args) {
+  const packageName = readOption(args, '--package', DEFAULT_UPDATE_PACKAGE);
+  const registry = readOption(args, '--registry', DEFAULT_UPDATE_REGISTRY);
+  return ['install', '-g', packageName, `--registry=${registry}`];
+}
+
+export function resolveNpmExecutable({
+  platform = process.platform,
+  nodeExecPath = process.execPath,
+  env = process.env,
+  existsSyncImpl = existsSync,
+} = {}) {
+  if (platform !== 'win32') {
+    return {
+      command: 'npm',
+      argsPrefix: [],
+      displayCommand: 'npm',
+      source: 'path',
+    };
+  }
+
+  const envNpmExecPath = env.npm_execpath;
+  if (envNpmExecPath && existsSyncImpl(envNpmExecPath)) {
+    return {
+      command: nodeExecPath,
+      argsPrefix: [envNpmExecPath],
+      displayCommand: 'npm',
+      source: 'npm_execpath',
+    };
+  }
+
+  const siblingNpmCli = path.join(path.dirname(nodeExecPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  if (existsSyncImpl(siblingNpmCli)) {
+    return {
+      command: nodeExecPath,
+      argsPrefix: [siblingNpmCli],
+      displayCommand: 'npm',
+      source: 'bundled-cli',
+    };
+  }
+
+  return {
+    command: 'cmd.exe',
+    argsPrefix: ['/d', '/s', '/c', 'npm.cmd'],
+    displayCommand: 'npm',
+    source: 'cmd-wrapper',
+  };
+}
+
+export function isInstalledGlobalPackageExecution(scriptPath, {
+  platform = process.platform,
+} = {}) {
+  if (platform !== 'win32') {
+    return false;
+  }
+
+  const normalized = String(scriptPath ?? '').replace(/\\/g, '/').toLowerCase();
+  return normalized.includes('/node_modules/@fprad0/skill-master-mcp/');
+}
+
+export function buildUpdateCommandPreview(commandInfo, installArgs) {
+  return formatShellCommand(commandInfo.displayCommand ?? commandInfo.command, installArgs);
+}
+
+export function shouldBlockDirectUpdate({
+  platform = process.platform,
+  scriptPath,
+  forceDirect = false,
+} = {}) {
+  if (forceDirect) {
+    return false;
+  }
+
+  return platform === 'win32' && isInstalledGlobalPackageExecution(scriptPath, { platform });
+}
+
+export function buildBlockedUpdateMessage(commandPreview) {
+  return [
+    'A atualizacao exige que o processo atual seja encerrado antes da troca do pacote.',
+    'O pacote global parece estar em uso nesta execucao do Windows.',
+    `Execute fora do menu: ${commandPreview}`,
+    'Feche o menu e reinicie os clientes MCP depois da atualizacao.',
+  ].join('\n');
+}
+
+export function classifyUpdateFailure(output, exitCode) {
+  const normalized = String(output ?? '').toLowerCase();
+  if (normalized.includes('ebusy') || normalized.includes('resource busy or locked')) {
+    return {
+      exitCode: OPERATION_EXIT_CODES.error,
+      message: 'O pacote esta em uso neste momento. Feche o menu ou o cliente MCP e rode o update fora desta execucao.',
+    };
+  }
+
+  return {
+    exitCode: Number.isInteger(exitCode) ? exitCode : 1,
+    message: null,
+  };
+}