@h1dr0n/skill-pool 0.1.0

package/src/adapters/cursor.js

@@ -0,0 +1,161 @@
+import path from 'node:path';
+import {
+  ensureDir,
+  writeFileAtomic,
+  readFileContent,
+  removeFile,
+  fileExists,
+  listDir,
+  copyDir,
+  removeDir,
+  isDirectory,
+} from '../utils/fs.js';
+import { getSkillsDir } from '../core/manifest.js';
+
+const MARKER_PREFIX = '<!-- skill-pool:';
+const MARKER_SUFFIX = ' -->';
+const MARKER_FILE = '.skill-pool-marker';
+
+function makeMarker(packName, version) {
+  return `${MARKER_PREFIX}${packName}:${version}${MARKER_SUFFIX}`;
+}
+
+function parseMarker(content) {
+  const match = content.match(/<!-- skill-pool:([^:]+):([^ ]+) -->/);
+  if (!match) return null;
+  return { pack: match[1], version: match[2] };
+}
+
+function contentHasMarker(content, packName) {
+  const parsed = parseMarker(content);
+  return parsed && parsed.pack === packName;
+}
+
+function buildMdcContent(marker, packName, ruleContent) {
+  const frontmatter = [
+    '---',
+    `description: "skill-pool: ${packName} rules"`,
+    'globs: ""',
+    'alwaysApply: true',
+    '---',
+  ].join('\n');
+  return `${frontmatter}\n${marker}\n\n${ruleContent}`;
+}
+
+export async function detect(projectDir) {
+  return fileExists(path.join(projectDir, '.cursor'));
+}
+
+export async function install(manifest, projectDir) {
+  const installed = [];
+  const skillsDir = getSkillsDir();
+  const marker = makeMarker(manifest.name, manifest.version);
+
+  // Rules -> .cursor/rules/<pack>-<name>.mdc
+  for (const rulePath of manifest.rules) {
+    const srcPath = path.join(skillsDir, manifest.name, rulePath);
+    const content = await readFileContent(srcPath);
+    const basename = path.basename(rulePath, path.extname(rulePath));
+    const rulesDir = path.join(projectDir, '.cursor', 'rules');
+    await ensureDir(rulesDir);
+    const destPath = path.join(rulesDir, `${manifest.name}-${basename}.mdc`);
+    await writeFileAtomic(destPath, buildMdcContent(marker, manifest.name, content));
+    installed.push(destPath);
+  }
+
+  // Skills -> .cursor/skills/<pack>-<name>/
+  for (const skillPath of manifest.skills) {
+    const srcPath = path.join(skillsDir, manifest.name, skillPath);
+    const basename = path.basename(skillPath, path.extname(skillPath));
+    const destDir = path.join(projectDir, '.cursor', 'skills', `${manifest.name}-${basename}`);
+
+    if (await isDirectory(srcPath)) {
+      await copyDir(srcPath, destDir);
+      await writeFileAtomic(path.join(destDir, MARKER_FILE), marker);
+      installed.push(destDir);
+    } else {
+      await ensureDir(destDir);
+      const content = await readFileContent(srcPath);
+      await writeFileAtomic(path.join(destDir, 'SKILL.md'), `${marker}\n\n${content}`);
+      await writeFileAtomic(path.join(destDir, MARKER_FILE), marker);
+      installed.push(destDir);
+    }
+  }
+
+  // Agents -> .cursor/rules/<pack>-agent-<name>.mdc
+  for (const agentPath of manifest.agents) {
+    const srcPath = path.join(skillsDir, manifest.name, agentPath);
+    const content = await readFileContent(srcPath);
+    const basename = path.basename(agentPath, path.extname(agentPath));
+    const rulesDir = path.join(projectDir, '.cursor', 'rules');
+    await ensureDir(rulesDir);
+    const destPath = path.join(rulesDir, `${manifest.name}-agent-${basename}.mdc`);
+    await writeFileAtomic(destPath, buildMdcContent(marker, manifest.name, content));
+    installed.push(destPath);
+  }
+
+  return installed;
+}
+
+export async function remove(packName, projectDir) {
+  const removed = [];
+
+  // Remove rules + agent .mdc files
+  const rulesDir = path.join(projectDir, '.cursor', 'rules');
+  const ruleFiles = await listDir(rulesDir);
+  for (const file of ruleFiles) {
+    const filePath = path.join(rulesDir, file);
+    if (await isDirectory(filePath)) continue;
+    const content = await readFileContent(filePath);
+    if (contentHasMarker(content, packName)) {
+      await removeFile(filePath);
+      removed.push(filePath);
+    }
+  }
+
+  // Remove skills
+  const skillsBase = path.join(projectDir, '.cursor', 'skills');
+  const skillDirs = await listDir(skillsBase);
+  for (const dir of skillDirs) {
+    const markerPath = path.join(skillsBase, dir, MARKER_FILE);
+    if (await fileExists(markerPath)) {
+      const content = await readFileContent(markerPath);
+      if (contentHasMarker(content, packName)) {
+        await removeDir(path.join(skillsBase, dir));
+        removed.push(path.join(skillsBase, dir));
+      }
+    }
+  }
+
+  return removed;
+}
+
+export async function list(projectDir) {
+  const results = [];
+
+  const rulesDir = path.join(projectDir, '.cursor', 'rules');
+  const ruleFiles = await listDir(rulesDir);
+  for (const file of ruleFiles) {
+    const filePath = path.join(rulesDir, file);
+    if (await isDirectory(filePath)) continue;
+    const content = await readFileContent(filePath);
+    const parsed = parseMarker(content);
+    if (parsed) {
+      const type = file.includes('-agent-') ? 'agent' : 'rule';
+      results.push({ ...parsed, file, type });
+    }
+  }
+
+  const skillsBase = path.join(projectDir, '.cursor', 'skills');
+  const skillDirs = await listDir(skillsBase);
+  for (const dir of skillDirs) {
+    const markerPath = path.join(skillsBase, dir, MARKER_FILE);
+    if (await fileExists(markerPath)) {
+      const content = await readFileContent(markerPath);
+      const parsed = parseMarker(content);
+      if (parsed) results.push({ ...parsed, file: dir, type: 'skill' });
+    }
+  }
+
+  return results;
+}

package/src/adapters/index.js

@@ -0,0 +1,67 @@
+import * as claude from './claude.js';
+import * as cursor from './cursor.js';
+import * as windsurf from './windsurf.js';
+import * as antigravity from './antigravity.js';
+import { loadPlugins } from '../core/plugins.js';
+
+const adapters = {
+  claude,
+  cursor,
+  windsurf,
+  antigravity,
+};
+
+export function getAdapter(name) {
+  const adapter = adapters[name];
+  if (!adapter) {
+    throw new Error(`Unknown target: "${name}". Available: ${Object.keys(adapters).join(', ')}`);
+  }
+  return adapter;
+}
+
+/**
+ * Load custom adapters from project config and merge into the registry.
+ * Custom adapters do not overwrite built-in adapters.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @returns {Promise<Record<string, object>>} merged adapter map (built-in + custom)
+ */
+export async function loadCustomAdapters(projectDir) {
+  const custom = await loadPlugins(projectDir);
+  return { ...custom, ...adapters };
+}
+
+/**
+ * Get an adapter by name, checking built-in adapters first, then plugins.
+ *
+ * @param {string} name - adapter name
+ * @param {string} projectDir - absolute path to the project root
+ * @returns {Promise<object>} the adapter module
+ */
+export async function getAdapterWithPlugins(name, projectDir) {
+  if (adapters[name]) {
+    return adapters[name];
+  }
+
+  const custom = await loadPlugins(projectDir);
+  if (custom[name]) {
+    return custom[name];
+  }
+
+  const allNames = [...Object.keys(adapters), ...Object.keys(custom)];
+  throw new Error(`Unknown target: "${name}". Available: ${allNames.join(', ')}`);
+}
+
+export async function detectTargets(projectDir) {
+  const detected = [];
+  for (const [name, adapter] of Object.entries(adapters)) {
+    if (await adapter.detect(projectDir)) {
+      detected.push(name);
+    }
+  }
+  return detected;
+}
+
+export function getAllTargetNames() {
+  return Object.keys(adapters);
+}

package/src/adapters/windsurf.js

@@ -0,0 +1,158 @@
+import path from 'node:path';
+import {
+  ensureDir,
+  writeFileAtomic,
+  readFileContent,
+  removeFile,
+  fileExists,
+  listDir,
+  copyDir,
+  removeDir,
+  isDirectory,
+} from '../utils/fs.js';
+import { getSkillsDir } from '../core/manifest.js';
+
+const MARKER_PREFIX = '<!-- skill-pool:';
+const MARKER_SUFFIX = ' -->';
+const MARKER_FILE = '.skill-pool-marker';
+
+function makeMarker(packName, version) {
+  return `${MARKER_PREFIX}${packName}:${version}${MARKER_SUFFIX}`;
+}
+
+function parseMarker(line) {
+  if (!line.startsWith(MARKER_PREFIX)) return null;
+  const inner = line.slice(MARKER_PREFIX.length, line.indexOf(MARKER_SUFFIX));
+  const [pack, version] = inner.split(':');
+  return { pack, version };
+}
+
+function contentHasMarker(content, packName) {
+  const firstLine = content.split('\n')[0];
+  const parsed = parseMarker(firstLine);
+  return parsed && parsed.pack === packName;
+}
+
+export async function detect(projectDir) {
+  return fileExists(path.join(projectDir, '.windsurf'));
+}
+
+export async function install(manifest, projectDir) {
+  const installed = [];
+  const skillsDir = getSkillsDir();
+  const marker = makeMarker(manifest.name, manifest.version);
+
+  // Rules -> .windsurf/rules/<pack>-<name>.md
+  for (const rulePath of manifest.rules) {
+    const srcPath = path.join(skillsDir, manifest.name, rulePath);
+    const content = await readFileContent(srcPath);
+    const basename = path.basename(rulePath, path.extname(rulePath));
+    const rulesDir = path.join(projectDir, '.windsurf', 'rules');
+    await ensureDir(rulesDir);
+    const destPath = path.join(rulesDir, `${manifest.name}-${basename}.md`);
+    await writeFileAtomic(destPath, `${marker}\n\n${content}`);
+    installed.push(destPath);
+  }
+
+  // Skills -> .windsurf/skills/<pack>-<name>/
+  for (const skillPath of manifest.skills) {
+    const srcPath = path.join(skillsDir, manifest.name, skillPath);
+    const basename = path.basename(skillPath, path.extname(skillPath));
+    const destDir = path.join(projectDir, '.windsurf', 'skills', `${manifest.name}-${basename}`);
+
+    if (await isDirectory(srcPath)) {
+      await copyDir(srcPath, destDir);
+      await writeFileAtomic(path.join(destDir, MARKER_FILE), marker);
+      installed.push(destDir);
+    } else {
+      await ensureDir(destDir);
+      const content = await readFileContent(srcPath);
+      await writeFileAtomic(path.join(destDir, 'SKILL.md'), `${marker}\n\n${content}`);
+      await writeFileAtomic(path.join(destDir, MARKER_FILE), marker);
+      installed.push(destDir);
+    }
+  }
+
+  // Agents -> .windsurf/rules/<pack>-agent-<name>.md (Windsurf uses rules for agents)
+  for (const agentPath of manifest.agents) {
+    const srcPath = path.join(skillsDir, manifest.name, agentPath);
+    const content = await readFileContent(srcPath);
+    const basename = path.basename(agentPath, path.extname(agentPath));
+    const rulesDir = path.join(projectDir, '.windsurf', 'rules');
+    await ensureDir(rulesDir);
+    const destPath = path.join(rulesDir, `${manifest.name}-agent-${basename}.md`);
+    await writeFileAtomic(destPath, `${marker}\n\n${content}`);
+    installed.push(destPath);
+  }
+
+  return installed;
+}
+
+export async function remove(packName, projectDir) {
+  const removed = [];
+
+  // Remove rules + agent files
+  await removeMarkedFiles(path.join(projectDir, '.windsurf', 'rules'), packName, removed);
+
+  // Remove skills
+  const skillsBase = path.join(projectDir, '.windsurf', 'skills');
+  const skillDirs = await listDir(skillsBase);
+  for (const dir of skillDirs) {
+    const markerPath = path.join(skillsBase, dir, MARKER_FILE);
+    if (await fileExists(markerPath)) {
+      const content = await readFileContent(markerPath);
+      if (contentHasMarker(content, packName)) {
+        await removeDir(path.join(skillsBase, dir));
+        removed.push(path.join(skillsBase, dir));
+      }
+    }
+  }
+
+  return removed;
+}
+
+async function removeMarkedFiles(dirPath, packName, removed) {
+  const files = await listDir(dirPath);
+  for (const file of files) {
+    const filePath = path.join(dirPath, file);
+    if (await isDirectory(filePath)) continue;
+    const content = await readFileContent(filePath);
+    if (contentHasMarker(content, packName)) {
+      await removeFile(filePath);
+      removed.push(filePath);
+    }
+  }
+}
+
+export async function list(projectDir) {
+  const results = [];
+
+  // List rules + agents
+  const rulesDir = path.join(projectDir, '.windsurf', 'rules');
+  const ruleFiles = await listDir(rulesDir);
+  for (const file of ruleFiles) {
+    const filePath = path.join(rulesDir, file);
+    if (await isDirectory(filePath)) continue;
+    const content = await readFileContent(filePath);
+    const firstLine = content.split('\n')[0];
+    const parsed = parseMarker(firstLine);
+    if (parsed) {
+      const type = file.includes('-agent-') ? 'agent' : 'rule';
+      results.push({ ...parsed, file, type });
+    }
+  }
+
+  // List skills
+  const skillsBase = path.join(projectDir, '.windsurf', 'skills');
+  const skillDirs = await listDir(skillsBase);
+  for (const dir of skillDirs) {
+    const markerPath = path.join(skillsBase, dir, MARKER_FILE);
+    if (await fileExists(markerPath)) {
+      const content = await readFileContent(markerPath);
+      const parsed = parseMarker(content);
+      if (parsed) results.push({ ...parsed, file: dir, type: 'skill' });
+    }
+  }
+
+  return results;
+}

package/src/commands/add.js

@@ -0,0 +1,266 @@
+import path from 'node:path';
+import os from 'node:os';
+import chalk from 'chalk';
+import yaml from 'js-yaml';
+import { cloneRepo, isGitAvailable } from '../utils/git.js';
+import { fileExists, readFileContent, copyDir, removeDir, ensureDir } from '../utils/fs.js';
+import {
+  loadTracker,
+  saveTracker,
+  getInstalledVersion,
+  recordInstall,
+} from '../core/tracker.js';
+import { getAdapter, detectTargets } from '../adapters/index.js';
+
+/**
+ * Parse a GitHub URL into { url, branch, repoName }.
+ * Accepts:
+ *   https://github.com/user/repo
+ *   github.com/user/repo
+ *   https://github.com/user/repo#branch
+ *   https://github.com/user/repo.git
+ *
+ * @param {string} raw
+ * @returns {{ url: string, branch: string | null, repoName: string }}
+ */
+function parseGithubUrl(raw) {
+  let input = raw.trim();
+
+  // Split off #branch fragment
+  let branch = null;
+  const hashIndex = input.indexOf('#');
+  if (hashIndex !== -1) {
+    branch = input.slice(hashIndex + 1);
+    input = input.slice(0, hashIndex);
+  }
+
+  // Normalise: add https:// if missing
+  if (!input.startsWith('http://') && !input.startsWith('https://')) {
+    input = `https://${input}`;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(input);
+  } catch {
+    throw new Error(`Invalid URL: "${raw}"`);
+  }
+
+  if (!parsed.hostname.includes('github.com')) {
+    throw new Error(
+      `Only GitHub URLs are supported. Got: "${parsed.hostname}"`
+    );
+  }
+
+  // pathname looks like /user/repo or /user/repo.git
+  const segments = parsed.pathname.replace(/\.git$/, '').split('/').filter(Boolean);
+
+  if (segments.length < 2) {
+    throw new Error(
+      `Cannot extract owner/repo from URL: "${raw}". Expected format: github.com/owner/repo`
+    );
+  }
+
+  const repoName = segments[1];
+
+  return { url: input, branch, repoName };
+}
+
+/**
+ * Locate manifest.yaml in a cloned directory.
+ * Checks root first, then skills/ subdirectory.
+ *
+ * @param {string} cloneDir
+ * @returns {Promise<{ manifestPath: string, packRoot: string } | null>}
+ */
+async function findManifest(cloneDir) {
+  // Check root
+  const rootManifest = path.join(cloneDir, 'manifest.yaml');
+  if (await fileExists(rootManifest)) {
+    return { manifestPath: rootManifest, packRoot: cloneDir };
+  }
+
+  // Check skills/ subdirectory
+  const skillsManifest = path.join(cloneDir, 'skills', 'manifest.yaml');
+  if (await fileExists(skillsManifest)) {
+    return { manifestPath: skillsManifest, packRoot: path.join(cloneDir, 'skills') };
+  }
+
+  return null;
+}
+
+/**
+ * Load and validate a manifest from a file path.
+ * @param {string} manifestPath
+ * @returns {Promise<object>}
+ */
+async function loadManifestFromPath(manifestPath) {
+  const content = await readFileContent(manifestPath);
+  const manifest = yaml.load(content);
+
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error('manifest.yaml is empty or invalid');
+  }
+
+  if (!manifest.name) {
+    throw new Error('manifest.yaml is missing required field: name');
+  }
+
+  const hasContent =
+    (manifest.rules && manifest.rules.length > 0) ||
+    (manifest.skills && manifest.skills.length > 0) ||
+    (manifest.agents && manifest.agents.length > 0);
+
+  if (!hasContent) {
+    throw new Error('manifest.yaml must have at least one of: rules, skills, agents');
+  }
+
+  return {
+    name: manifest.name,
+    version: manifest.version || '0.0.0',
+    description: manifest.description || '',
+    depends: manifest.depends || [],
+    tags: manifest.tags || [],
+    rules: manifest.rules || [],
+    skills: manifest.skills || [],
+    agents: manifest.agents || [],
+  };
+}
+
+/**
+ * Resolve target adapters (same logic as install command).
+ * @param {string} projectDir
+ * @param {string | undefined} targetOption
+ * @returns {Promise<string[]>}
+ */
+async function resolveTargets(projectDir, targetOption) {
+  if (targetOption) {
+    const names = targetOption.split(',').map((t) => t.trim());
+    names.forEach((n) => getAdapter(n));
+    return names;
+  }
+
+  const detected = await detectTargets(projectDir);
+  if (detected.length > 0) return detected;
+
+  return ['claude'];
+}
+
+/**
+ * Install a skill pack from a GitHub repository URL.
+ *
+ * @param {string} rawUrl - GitHub repository URL, optionally with #branch
+ * @param {object} [options]
+ * @param {string} [options.target] - Comma-separated target names
+ */
+export async function addCommand(rawUrl, options = {}) {
+  // 1. Verify git is available
+  if (!(await isGitAvailable())) {
+    throw new Error(
+      'git is not installed or not in PATH. Install git and try again.'
+    );
+  }
+
+  // 2. Parse URL
+  const { url, branch, repoName } = parseGithubUrl(rawUrl);
+
+  console.log(
+    chalk.gray(`Repository: ${url}${branch ? ` (branch: ${branch})` : ''}`)
+  );
+
+  // 3. Clone into temp directory
+  const tmpDir = path.join(
+    os.tmpdir(),
+    `sp-clone-${repoName}-${Date.now()}`
+  );
+
+  console.log(chalk.gray('Cloning repository...'));
+
+  try {
+    await cloneRepo(url, tmpDir, branch);
+  } catch (err) {
+    throw new Error(
+      `Failed to clone repository: ${err.message}`
+    );
+  }
+
+  try {
+    // 4. Find manifest.yaml
+    const found = await findManifest(tmpDir);
+
+    if (!found) {
+      throw new Error(
+        `No manifest.yaml found in repository root or skills/ subdirectory`
+      );
+    }
+
+    const { manifestPath, packRoot } = found;
+
+    // 5. Load and validate manifest
+    const manifest = await loadManifestFromPath(manifestPath);
+
+    console.log(
+      chalk.gray(`Found pack: ${manifest.name}@${manifest.version}`)
+    );
+
+    // 6. Copy pack to local cache
+    const projectDir = process.cwd();
+    const cacheDir = path.join(projectDir, '.skill-pool-cache', '_external', repoName);
+
+    await ensureDir(path.dirname(cacheDir));
+    // Remove existing cache for this pack if present
+    await removeDir(cacheDir);
+    await copyDir(packRoot, cacheDir);
+
+    console.log(chalk.gray(`Cached to .skill-pool-cache/_external/${repoName}/`));
+
+    // 7. Resolve targets
+    const targets = await resolveTargets(projectDir, options.target);
+    console.log(chalk.gray(`Targets: ${targets.join(', ')}\n`));
+
+    // 8. Check if already installed at same version
+    let tracker = await loadTracker(projectDir);
+    const currentVersion = getInstalledVersion(tracker, manifest.name);
+
+    if (currentVersion === manifest.version) {
+      console.log(
+        chalk.yellow(`${manifest.name}@${manifest.version} already installed, skipping`)
+      );
+      return;
+    }
+
+    // 9. Run install via adapters
+    let totalFiles = 0;
+    for (const targetName of targets) {
+      const adapter = getAdapter(targetName);
+      const files = await adapter.install(manifest, projectDir);
+      totalFiles += files.length;
+    }
+
+    // 10. Update tracker with github source
+    tracker = recordInstall(tracker, manifest.name, manifest.version, targets);
+
+    // Add source metadata
+    tracker = {
+      ...tracker,
+      installed: {
+        ...tracker.installed,
+        [manifest.name]: {
+          ...tracker.installed[manifest.name],
+          source: `github:${rawUrl}`,
+        },
+      },
+    };
+
+    await saveTracker(projectDir, tracker);
+
+    console.log(
+      chalk.green(`  + ${manifest.name}@${manifest.version}`) +
+        chalk.gray(` (${totalFiles} rules, source: github)`)
+    );
+    console.log(chalk.green(`\nInstalled 1 pack for ${targets.join(', ')}.`));
+  } finally {
+    // 11. Cleanup temp directory
+    await removeDir(tmpDir);
+  }
+}