@basetisia/skill-manager 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# @basetis/skill-manager
+
+CLI para gestionar skills de IA (prompts reutilizables) e instalarlas en múltiples herramientas de coding: Claude Code, Gemini CLI, Codex CLI, Cursor y Windsurf.
+
+Las skills se almacenan en un repositorio GitLab centralizado (`git@git.basetis.com:okr-ia/basetisskills.git`) con un catálogo definido en `manifest.yml`. El CLI descarga las skills desde ese catálogo y las coloca en el formato y ruta correctos para cada herramienta.
+
+## Prerequisitos
+
+- **Node.js >= 24** — verifica con `node --version`
+- **Token de acceso personal de GitLab** con scope `read_package_registry` en `git.basetis.com`
+
+## Setup para developer nuevo
+
+La forma más rápida de instalar es ejecutar el script de setup:
+
+```bash
+bash <(curl -fsSL https://git.basetis.com/okr-ia/basetisskills/-/raw/main/cli/scripts/setup.sh)
+```
+
+El script te pedirá tu token personal de GitLab, configurará npm y instalará el CLI globalmente.
+
+### Generar el token de GitLab
+
+1. Ve a [git.basetis.com → Settings → Access Tokens](https://git.basetis.com/-/user_settings/personal_access_tokens)
+2. Crea un token con el scope: **read_package_registry**
+3. Copia el token (empieza por `glpat-...`)
+
+### Instalación manual
+
+Si prefieres configurarlo a mano, añade a tu `~/.npmrc`:
+
+```ini
+@basetis:registry=https://git.basetis.com/api/v4/packages/npm/
+//git.basetis.com/api/v4/packages/npm/:_authToken=TU_GITLAB_TOKEN
+```
+
+Y luego:
+
+```bash
+npm install -g @basetis/skill-manager
+```
+
+Verifica la instalación:
+
+```bash
+skill-manager --version
+# 0.1.0
+```
+
+## Primeros pasos
+
+### 1. Configurar el repositorio de skills
+
+```bash
+skill-manager init
+```
+
+```
+? Tipo de repositorio de skills: › GitLab
+? URL base del servidor: › https://git.basetis.com
+? Project ID (numérico) o ruta (grupo/repo): › okr-ia/basetisskills
+? Token de acceso personal: › ****
+? Rama del repositorio: › main
+? Herramienta de IA por defecto: › Claude Code
+
+✔ Conexión verificada correctamente.
+✔ Configuración guardada correctamente.
+  → ~/.skill-manager/config.json
+```
+
+### 2. Explorar el catálogo
+
+```bash
+skill-manager list
+```
+
+```
+  User Skills
+  ────────────────────────────────────────
+  user/development/kotlin-jvm    v1.0.0
+  user/development/react         v1.0.0
+
+  Internal Skills
+  ────────────────────────────────────────
+  internal/global                v2.0.0
+
+  External Skills
+  ────────────────────────────────────────
+  external/sector/pharma                    v1.0.0
+  external/client/alexion                   v1.2.0  ← external/sector/pharma
+  external/project/alexion-cockpit          v2.0.0  ← external/client/alexion
+
+  Total: 5 skills
+```
+
+Filtrar por nombre:
+
+```bash
+skill-manager list --filter alexion
+```
+
+### 3. Instalar una skill
+
+```bash
+skill-manager install external/project/alexion-cockpit
+```
+
+```
+✔ Cadena resuelta: 3 skill(s).
+
+  Skills a instalar (en orden):
+  ├─ external/sector/pharma v1.0.0
+  ├─ external/client/alexion v1.2.0
+  └─ external/project/alexion-cockpit v2.0.0
+
+? ¿En qué herramientas quieres instalar? › Claude Code, Cursor
+? ¿Dónde instalar las skills? › Global (solo para ti, en ~/)
+
+✔ Instalada external/sector/pharma
+✔ Instalada external/client/alexion
+✔ Instalada external/project/alexion-cockpit
+
+✔ 3 skill(s) instalada(s) en Claude Code y Cursor (personal)
+```
+
+Instalación directa sin prompts:
+
+```bash
+skill-manager install external/client/alexion --tool claude,windsurf --scope global
+```
+
+### 4. Ver estado de las skills instaladas
+
+```bash
+skill-manager status
+```
+
+```
+  Claude Code
+  ──────────────────────────────────────────────────
+  [Global]
+  external/sector/pharma              1.0.0   ✓ al día
+  external/client/alexion             1.1.0   ⬆ 1.2.0 disponible
+  external/project/alexion-cockpit    2.0.0   ✓ al día
+```
+
+### 5. Detectar skills recomendadas automáticamente
+
+```bash
+cd mi-proyecto-kotlin/
+skill-manager detect
+```
+
+```
+✔ Análisis completo.
+
+  Skills recomendadas:
+
+  internal/global v2.0.0
+    → Skill base recomendada para todos los proyectos.
+  user/development/kotlin-jvm v1.0.0
+    → Detectado: kotlin, jvm, gradle en el proyecto.
+
+? ¿Instalar las skills recomendadas? › Sí
+```
+
+## Referencia de comandos
+
+| Comando | Argumentos | Descripción |
+|---|---|---|
+| `skill-manager init` | — | Configura el repositorio de skills y herramienta por defecto |
+| `skill-manager list` | `--filter <texto>` | Lista skills del catálogo, agrupadas por sección |
+| `skill-manager install <ruta>` | `--tool <herramienta>` `--scope <global\|project>` | Instala una skill y toda su cadena de dependencias |
+| `skill-manager status` | — | Compara versiones instaladas vs catálogo para cada herramienta |
+| `skill-manager detect` | — | Analiza el proyecto actual y recomienda skills relevantes |
+
+### Opciones globales
+
+| Opción | Descripción |
+|---|---|
+| `--version`, `-V` | Muestra la versión del CLI |
+| `--help`, `-h` | Muestra la ayuda general o de un comando |
+
+## Herramientas soportadas
+
+| Herramienta | Personal (global) | Proyecto (local) |
+|---|---|---|
+| Claude Code | `~/.claude/skills/{path}/SKILL.md` | `.claude/skills/{path}/SKILL.md` |
+| Gemini CLI | `~/.gemini/skills/{path}/SKILL.md` | `.agents/skills/{path}/SKILL.md` |
+| Codex CLI | `~/.codex/{name}/SKILL.md` | `.agents/skills/{path}/SKILL.md` |
+| Cursor | `~/.cursor/rules/{name}.mdc` | `.cursor/rules/{name}.mdc` |
+| Windsurf | `~/.windsurf/global_rules.md` (append) | `.windsurf/rules/{name}.md` |
+
+## Cómo añadir soporte para una nueva herramienta
+
+1. Crea un nuevo archivo en `src/adapters/<herramienta>.js` exportando:
+
+```javascript
+export const toolName = "mi-herramienta";
+export const displayName = "Mi Herramienta";
+
+export function getInstallPath(skillPath, scope) {
+  // Devuelve la ruta donde se instalará el SKILL.md
+}
+
+export async function install(skillPath, skillContent, scope) {
+  // Escribe el contenido en la ruta correcta
+  // Transforma el formato si es necesario (como Cursor con .mdc)
+}
+
+export async function getInstalledSkills(scope) {
+  // Devuelve [{ path, version }] leyendo los archivos instalados
+}
+```
+
+2. Regístralo en `src/adapters/index.js`:
+
+```javascript
+import * as miHerramienta from "./mi-herramienta.js";
+
+const adapters = [claude, gemini, codex, cursor, windsurf, miHerramienta];
+```
+
+3. Añade la detección en `detectInstalledTools()` del mismo archivo.
+
+4. Escribe tests en `src/adapters/adapters.test.js` siguiendo el patrón existente.
+
+## Cómo contribuir al catálogo de skills
+
+Las skills se gestionan en el repositorio [okr-ia/basetisskills](https://git.basetis.com/okr-ia/basetisskills).
+
+Consulta el archivo `CONTRIBUTING.md` de ese repositorio para conocer:
+
+- Estructura de carpetas y convenciones de naming
+- Formato del `manifest.yml`
+- Cómo escribir un `SKILL.md` con frontmatter válido
+- Flujo de review y merge para nuevas skills
+- Cómo usar `parent` y `upstream` para cadenas de herencia
+
+## Licencia
+
+Uso interno Basetis.

package/bin/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { init } from "../src/commands/init.js";
+import { list } from "../src/commands/list.js";
+import { install } from "../src/commands/install.js";
+import { status } from "../src/commands/status.js";
+import { detect } from "../src/commands/detect.js";
+import { login } from "../src/commands/login.js";
+import { logout } from "../src/commands/logout.js";
+import { whoami } from "../src/commands/whoami.js";
+
+const program = new Command();
+
+program
+  .name("skill-manager")
+  .description("CLI para gestionar skills de IA en tu editor")
+  .version("0.1.0");
+
+program
+  .command("init")
+  .description("Configura el repositorio de skills y la herramienta por defecto")
+  .action(async () => {
+    try {
+      await init();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("list")
+  .description("Lista todas las skills disponibles en el catálogo")
+  .option("-f, --filter <texto>", "Filtra skills por nombre")
+  .action(async (options) => {
+    try {
+      await list(options);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("install <ruta>")
+  .description("Instala una skill y sus dependencias (cadena de parents)")
+  .option("-t, --tool <herramienta>", "Herramienta(s) destino, separadas por coma (claude,cursor,gemini,codex,windsurf)")
+  .option("-s, --scope <ámbito>", "Ámbito de instalación: global o project")
+  .action(async (ruta, options) => {
+    try {
+      await install(ruta, options);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("status")
+  .description("Muestra el estado de las skills instaladas vs el catálogo")
+  .action(async () => {
+    try {
+      await status();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("detect")
+  .description("Analiza el proyecto actual y recomienda skills relevantes")
+  .action(async () => {
+    try {
+      await detect();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("login")
+  .description("Inicia sesión con tu cuenta de Basetis (Google)")
+  .action(async () => {
+    try {
+      await login();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("logout")
+  .description("Cierra la sesión actual")
+  .action(async () => {
+    try {
+      await logout();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("whoami")
+  .description("Muestra el usuario autenticado")
+  .action(async () => {
+    try {
+      await whoami();
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@basetisia/skill-manager",
+  "version": "0.1.0",
+  "description": "CLI to manage AI coding skills across editors",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "skill-manager": "./bin/index.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/index.js"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5",
+    "commander": "^13",
+    "inquirer": "^12",
+    "js-yaml": "^4",
+    "ora": "^8"
+  }
+}

package/scripts/publish.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Directorio raíz del CLI (un nivel arriba de scripts/)
+CLI_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+echo "📦 @basetis/skill-manager — publish (GitLab Package Registry)"
+echo "───────────────────────────────────────────────────────────────"
+
+# 1. Verificar token de GitLab
+if [[ -z "${GITLAB_TOKEN:-}" ]]; then
+  echo "❌ Error: Define GITLAB_TOKEN antes de publicar."
+  echo "   Ejemplo: export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx"
+  echo ""
+  echo "   Genera uno en: git.basetis.com → Settings → Access Tokens"
+  echo "   Scopes necesarios: api"
+  exit 1
+fi
+echo "✔ GITLAB_TOKEN configurado."
+
+# 2. Ejecutar tests
+echo "⏳ Ejecutando tests..."
+cd "$CLI_DIR"
+npm run test
+echo "✔ Tests pasados."
+
+# 3. Publicar paquete
+echo "⏳ Publicando en GitLab Package Registry..."
+npm publish
+
+# 4. Confirmar publicación
+VERSION=$(node -p "require('./package.json').version")
+echo ""
+echo "───────────────────────────────────────────────────────────────"
+echo "✔ Publicado @basetis/skill-manager@${VERSION}"
+echo "  Registry: https://git.basetis.com/okr-ia/basetisskills/-/packages"
+echo "  Instalar: npm install -g @basetis/skill-manager"

package/scripts/setup.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "🔧 Setup @basetis/skill-manager"
+echo "────────────────────────────────"
+echo ""
+echo "Necesitas un token personal de GitLab con scope read_package_registry."
+echo ""
+echo "  1. Ve a: https://git.basetis.com/-/user_settings/personal_access_tokens"
+echo "  2. Crea un token con el scope: read_package_registry"
+echo "  3. Copia el token (empieza por glpat-...)"
+echo ""
+
+read -rp "Pega tu GitLab token: " GITLAB_TOKEN
+
+if [[ -z "$GITLAB_TOKEN" ]]; then
+  echo "❌ Token vacío. Abortando."
+  exit 1
+fi
+
+# Escribir configuración en ~/.npmrc
+NPMRC="$HOME/.npmrc"
+
+# Eliminar líneas anteriores de @basetis si existen
+if [[ -f "$NPMRC" ]]; then
+  grep -v '@basetis:registry' "$NPMRC" | grep -v '//git.basetis.com/api/v4/packages/npm/:_authToken' > "$NPMRC.tmp" || true
+  mv "$NPMRC.tmp" "$NPMRC"
+fi
+
+echo "@basetis:registry=https://git.basetis.com/api/v4/packages/npm/" >> "$NPMRC"
+echo "//git.basetis.com/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}" >> "$NPMRC"
+
+echo "✔ ~/.npmrc configurado."
+
+# Instalar el CLI globalmente
+echo "⏳ Instalando @basetis/skill-manager..."
+npm install -g @basetis/skill-manager
+
+# Verificar instalación
+echo ""
+if skill-manager --version &>/dev/null; then
+  VERSION=$(skill-manager --version)
+  echo "────────────────────────────────"
+  echo "✔ skill-manager ${VERSION} instalado correctamente."
+  echo "  Ejecuta: skill-manager init"
+else
+  echo "❌ Error: skill-manager no se encontró en el PATH."
+  echo "  Verifica que la carpeta global de npm está en tu PATH."
+  exit 1
+fi

package/src/adapters/adapters.test.js

@@ -0,0 +1,175 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, readFile, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const SKILL_CONTENT = `---
+name: test-skill
+version: "1.0.0"
+description: A test skill
+---
+You are a test skill.
+`;
+
+let tmpHome, tmpCwd, origHome, origCwd;
+
+async function setup() {
+  tmpHome = await realpath(await mkdtemp(join(tmpdir(), "sm-home-")));
+  tmpCwd = await realpath(await mkdtemp(join(tmpdir(), "sm-cwd-")));
+  origHome = process.env.HOME;
+  origCwd = process.cwd();
+  process.env.HOME = tmpHome;
+  process.chdir(tmpCwd);
+}
+
+async function teardown() {
+  process.env.HOME = origHome;
+  process.chdir(origCwd);
+  await rm(tmpHome, { recursive: true, force: true });
+  await rm(tmpCwd, { recursive: true, force: true });
+}
+
+// Re-import adapters fresh so homeDir/cwdDir pick up the new env
+async function loadAdapter(name) {
+  const mod = await import(`./${name}.js?t=${Date.now()}`);
+  return mod;
+}
+
+describe("claude adapter", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs to personal scope at ~/.claude/skills/", async () => {
+    const claude = await loadAdapter("claude");
+    const dest = await claude.install("external/sector/pharma", SKILL_CONTENT, "personal");
+    assert.equal(dest, join(tmpHome, ".claude", "skills", "external", "sector", "pharma", "SKILL.md"));
+    const content = await readFile(dest, "utf-8");
+    assert.ok(content.includes("test skill"));
+  });
+
+  it("installs to project scope at .claude/skills/", async () => {
+    const claude = await loadAdapter("claude");
+    const dest = await claude.install("internal/tooling/eslint", SKILL_CONTENT, "project");
+    assert.equal(dest, join(tmpCwd, ".claude", "skills", "internal", "tooling", "eslint", "SKILL.md"));
+  });
+
+  it("getInstallPath returns correct path", async () => {
+    const claude = await loadAdapter("claude");
+    const p = claude.getInstallPath("a/b/c", "personal");
+    assert.ok(p.endsWith(join(".claude", "skills", "a", "b", "c", "SKILL.md")));
+  });
+
+  it("getInstalledSkills reads back installed skills", async () => {
+    const claude = await loadAdapter("claude");
+    await claude.install("sector/pharma", SKILL_CONTENT, "personal");
+    const skills = await claude.getInstalledSkills("personal");
+    assert.equal(skills.length, 1);
+    assert.equal(skills[0].path, "sector/pharma");
+    assert.equal(skills[0].version, "1.0.0");
+  });
+});
+
+describe("gemini adapter", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs to personal scope at ~/.gemini/skills/", async () => {
+    const gemini = await loadAdapter("gemini");
+    const dest = await gemini.install("sector/pharma", SKILL_CONTENT, "personal");
+    assert.equal(dest, join(tmpHome, ".gemini", "skills", "sector", "pharma", "SKILL.md"));
+  });
+
+  it("installs to project scope at .agents/skills/", async () => {
+    const gemini = await loadAdapter("gemini");
+    const dest = await gemini.install("sector/pharma", SKILL_CONTENT, "project");
+    assert.equal(dest, join(tmpCwd, ".agents", "skills", "sector", "pharma", "SKILL.md"));
+  });
+});
+
+describe("codex adapter", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs to personal scope at ~/.codex/{skillName}/", async () => {
+    const codex = await loadAdapter("codex");
+    const dest = await codex.install("external/sector/pharma", SKILL_CONTENT, "personal");
+    assert.equal(dest, join(tmpHome, ".codex", "pharma", "SKILL.md"));
+  });
+
+  it("installs to project scope at .agents/skills/", async () => {
+    const codex = await loadAdapter("codex");
+    const dest = await codex.install("external/sector/pharma", SKILL_CONTENT, "project");
+    assert.equal(dest, join(tmpCwd, ".agents", "skills", "external", "sector", "pharma", "SKILL.md"));
+  });
+});
+
+describe("cursor adapter", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs to personal scope as .mdc with cursor frontmatter", async () => {
+    const cursor = await loadAdapter("cursor");
+    const dest = await cursor.install("external/sector/pharma", SKILL_CONTENT, "personal");
+    assert.equal(dest, join(tmpHome, ".cursor", "rules", "pharma.mdc"));
+    const content = await readFile(dest, "utf-8");
+    assert.ok(content.startsWith("---\ndescription: A test skill\nalwaysApply: false\n---\n"));
+  });
+
+  it("installs to project scope at .cursor/rules/", async () => {
+    const cursor = await loadAdapter("cursor");
+    const dest = await cursor.install("sector/pharma", SKILL_CONTENT, "project");
+    assert.equal(dest, join(tmpCwd, ".cursor", "rules", "pharma.mdc"));
+  });
+});
+
+describe("windsurf adapter", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs to personal scope by appending to global_rules.md", async () => {
+    const windsurf = await loadAdapter("windsurf");
+    const dest = await windsurf.install("sector/pharma", SKILL_CONTENT, "personal");
+    assert.equal(dest, join(tmpHome, ".windsurf", "global_rules.md"));
+    const content = await readFile(dest, "utf-8");
+    assert.ok(content.includes("## pharma"));
+    assert.ok(content.includes("test skill"));
+  });
+
+  it("appends multiple skills without overwriting", async () => {
+    const windsurf = await loadAdapter("windsurf");
+    await windsurf.install("sector/pharma", SKILL_CONTENT, "personal");
+    await windsurf.install("sector/tech", "---\nname: tech\nversion: \"2.0.0\"\n---\nTech skill.", "personal");
+    const content = await readFile(join(tmpHome, ".windsurf", "global_rules.md"), "utf-8");
+    assert.ok(content.includes("## pharma"));
+    assert.ok(content.includes("## tech"));
+  });
+
+  it("installs to project scope at .windsurf/rules/", async () => {
+    const windsurf = await loadAdapter("windsurf");
+    const dest = await windsurf.install("sector/pharma", SKILL_CONTENT, "project");
+    assert.equal(dest, join(tmpCwd, ".windsurf", "rules", "pharma.md"));
+  });
+});
+
+describe("adapter index", () => {
+  it("getAdapter returns correct adapter", async () => {
+    const { getAdapter } = await import("./index.js");
+    const claude = getAdapter("claude");
+    assert.equal(claude.toolName, "claude");
+    assert.equal(claude.displayName, "Claude Code");
+  });
+
+  it("getAdapter throws for unknown tool", async () => {
+    const { getAdapter } = await import("./index.js");
+    assert.throws(() => getAdapter("unknown"), { message: /no soportada/ });
+  });
+
+  it("getAllAdapters returns 5 adapters", async () => {
+    const { getAllAdapters } = await import("./index.js");
+    const all = getAllAdapters();
+    assert.equal(all.length, 5);
+    const names = all.map((a) => a.toolName);
+    assert.deepEqual(names, ["claude", "gemini", "codex", "cursor", "windsurf"]);
+  });
+});

package/src/adapters/claude.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import { homeDir, cwdDir, writeFile } from "../utils/fs.js";
+import { scanInstalledSkills } from "./shared.js";
+
+export const toolName = "claude";
+export const displayName = "Claude Code";
+
+function basePath(scope) {
+  return scope === "personal"
+    ? join(homeDir(), ".claude", "skills")
+    : join(cwdDir(), ".claude", "skills");
+}
+
+export function getInstallPath(skillPath, scope) {
+  return join(basePath(scope), skillPath, "SKILL.md");
+}
+
+export async function install(skillPath, skillContent, scope) {
+  const dest = getInstallPath(skillPath, scope);
+  await writeFile(dest, skillContent);
+  return dest;
+}
+
+export async function getInstalledSkills(scope) {
+  return scanInstalledSkills(basePath(scope));
+}