@h0tp/shucky 0.1.0 → 0.4.5

package/lib/find.js

@@ -0,0 +1,162 @@
+'use strict';
+
+// shucky find — discover skills across the public registry (skills.sh) and the user's registered
+// sources/lists, every hit annotated with source-trust. Selecting one just hands off to
+// `shucky install <source>` — which re-fetches and SCANS before anything lands. find never installs.
+
+const { safeGet } = require('./fetch');
+const { loadConfig } = require('./config');
+const registry = require('./registry');
+
+const SKILLS_SH_SEARCH = 'https://skills.sh/api/search?q=';
+
+async function searchSkillsSh(query, opts) {
+  try {
+    const buf = await safeGet(SKILLS_SH_SEARCH + encodeURIComponent(query || ''), { accept: 'application/json', timeout: (opts && opts.timeout) || 12000 });
+    const data = JSON.parse(buf.toString('utf8'));
+    const skills = Array.isArray(data.skills) ? data.skills : [];
+    return skills.map(function (s) {
+      const source = s.source || (s.id ? String(s.id).split('/').slice(0, 2).join('/') : null);
+      const skill = s.skillId || s.name;
+      return {
+        name: s.name || skill, source: source, skill: skill, installs: s.installs || 0,
+        registry: 'skills.sh', install: source ? source + (skill && skill !== source ? '@' + skill : '') : (s.id || '')
+      };
+    }).filter(function (r) { return r.install; });
+  } catch (e) { return { error: 'skills.sh: ' + e.message }; }
+}
+
+async function searchListSource(src, query, opts) {
+  try {
+    const members = await registry.resolveList(src.spec, opts && opts.cwd);
+    const q = (query || '').toLowerCase();
+    return members.filter(function (m) { return !q || m.toLowerCase().indexOf(q) !== -1; }).map(function (m) {
+      const parts = m.split('@');
+      return { name: m, source: parts[0], skill: parts[1] || null, installs: 0, registry: src.name, install: m, trust: src.trust };
+    });
+  } catch (e) { return { error: 'list ' + src.name + ': ' + e.message }; }
+}
+
+async function searchWellKnown(src, query, opts) {
+  try {
+    const origin = new URL(src.spec).origin;
+    const buf = await safeGet(origin + '/.well-known/agent-skills/index.json', { accept: 'application/json', timeout: (opts && opts.timeout) || 12000 });
+    const data = JSON.parse(buf.toString('utf8'));
+    const skills = Array.isArray(data.skills) ? data.skills : [];
+    const q = (query || '').toLowerCase();
+    return skills.filter(function (s) {
+      return s && s.name && (!q || (s.name + ' ' + (s.description || '')).toLowerCase().indexOf(q) !== -1);
+    }).map(function (s) {
+      return { name: s.name, source: src.spec, skill: s.name, installs: 0, registry: src.name, install: src.spec, trust: src.trust };
+    });
+  } catch (e) { return { error: 'registry ' + src.name + ': ' + e.message }; }
+}
+
+// GitHub search — code search for SKILL.md when a token is present (precise), else unauthenticated
+// repo search (works for everyone, lower rate limit). Opt-in: --github flag or GITHUB_TOKEN.
+async function searchGitHub(query, opts) {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  const headers = token ? { authorization: 'Bearer ' + token } : {};
+  const timeout = (opts && opts.timeout) || 12000;
+  try {
+    if (token) {
+      const q = encodeURIComponent((query || '') + ' filename:SKILL.md');
+      const buf = await safeGet('https://api.github.com/search/code?q=' + q + '&per_page=20', { accept: 'application/vnd.github+json', headers: headers, timeout: timeout });
+      const data = JSON.parse(buf.toString('utf8'));
+      return (data.items || []).map(function (it) {
+        const repo = it.repository ? it.repository.full_name : null;
+        const dir = it.path ? it.path.replace(/\/?SKILL\.md$/i, '') : '';
+        const src = repo ? (dir ? repo + '/' + dir : repo) : null;
+        return { name: dir ? dir.split('/').pop() : repo, source: repo, skill: null, installs: 0, registry: 'github', install: src };
+      }).filter(function (r) { return r.install; });
+    }
+    const q = encodeURIComponent((query || 'skill') + ' skill in:name,description,readme');
+    const buf = await safeGet('https://api.github.com/search/repositories?q=' + q + '&per_page=15&sort=stars', { accept: 'application/vnd.github+json', headers: headers, timeout: timeout });
+    const data = JSON.parse(buf.toString('utf8'));
+    // Unauthenticated repo search is broad — keep only repos that actually look skill-related.
+    return (data.items || []).filter(function (r) {
+      const hay = (r.full_name + ' ' + (r.description || '')).toLowerCase();
+      return hay.indexOf('skill') !== -1 || hay.indexOf('agent') !== -1;
+    }).map(function (r) {
+      return { name: r.full_name, source: r.full_name, skill: null, installs: r.stargazers_count || 0, stars: true, registry: 'github', install: r.full_name };
+    });
+  } catch (e) { return { error: 'github: ' + e.message }; }
+}
+
+async function findSkills(query, opts) {
+  opts = opts || {};
+  const cwd = opts.cwd;
+  const results = [];
+  const searched = [];
+  const errors = [];
+
+  if (!opts.localOnly) {
+    searched.push('skills.sh');
+    const r = await searchSkillsSh(query, opts);
+    if (Array.isArray(r)) results.push.apply(results, r);
+    else if (r && r.error) errors.push(r.error);
+  }
+
+  const ghToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (!opts.localOnly && (opts.github || ghToken)) {
+    searched.push('github');
+    const r = await searchGitHub(query, opts);
+    if (Array.isArray(r)) {
+      results.push.apply(results, r);
+      if (!ghToken) errors.push('github: showing repo matches — set GITHUB_TOKEN for precise SKILL.md code search');
+    } else if (r && r.error) errors.push(r.error);
+  }
+
+  for (const src of registry.listSources(cwd)) {
+    if (src.type === 'list') {
+      searched.push(src.name);
+      const r = await searchListSource(src, query, opts);
+      if (Array.isArray(r)) results.push.apply(results, r); else if (r && r.error) errors.push(r.error);
+    } else if (src.type === 'registry') {
+      searched.push(src.name);
+      const r = await searchWellKnown(src, query, opts);
+      if (Array.isArray(r)) results.push.apply(results, r); else if (r && r.error) errors.push(r.error);
+    }
+  }
+
+  // Annotate trust from the built-in trustedSources + any registered `trusted` owners.
+  const trusted = new Set();
+  (loadConfig(null, {}).trustedSources || []).concat(registry.trustedOwners(cwd)).forEach(function (t) { trusted.add(String(t).toLowerCase()); });
+  for (const r of results) {
+    if (r.trust) continue;
+    const owner = r.source ? String(r.source).toLowerCase().split('/')[0] : '';
+    if (owner && (trusted.has(owner) || trusted.has(String(r.source).toLowerCase()))) r.trust = 'trusted';
+  }
+
+  results.sort(function (a, b) { return (b.installs || 0) - (a.installs || 0) || String(a.name).localeCompare(String(b.name)); });
+  return { results: results, searched: searched, errors: errors };
+}
+
+async function cmdFind(args) {
+  const query = args._.slice(1).join(' ').trim();
+  const cwd = process.cwd();
+  let out;
+  try { out = await findSkills(query, { cwd: cwd, localOnly: args.flags.local, github: args.flags.github }); }
+  catch (e) { console.error('find: ' + e.message); return 3; }
+
+  if (args.flags.json) { console.log(JSON.stringify(Object.assign({ query: query }, out), null, 2)); return 0; }
+
+  for (const e of out.errors) console.error('  (note) ' + e);
+  if (!out.results.length) {
+    console.log('no skills found' + (query ? ' for "' + query + '"' : '') + '. searched: ' + (out.searched.join(', ') || 'nothing'));
+    return 0;
+  }
+  const limit = Number(args.flags.limit) || 25;
+  console.log('found ' + out.results.length + ' skill(s)' + (query ? ' for "' + query + '"' : '') + ' — searched ' + out.searched.join(', ') + ':\n');
+  for (const r of out.results.slice(0, limit)) {
+    const trust = r.trust === 'trusted' ? '  ✓trusted' : '';
+    const metric = r.installs ? (r.stars ? '  (' + r.installs + ' ⭐)' : '  (' + r.installs + ' installs)') : '';
+    console.log('  ' + r.name + '   ← ' + r.registry + trust + metric);
+    console.log('      shucky install ' + r.install);
+  }
+  if (out.results.length > limit) console.log('\n  … ' + (out.results.length - limit) + ' more (use --limit <n> or --json)');
+  console.log('\nEvery install is scanned before it lands.');
+  return 0;
+}
+
+module.exports = { findSkills, cmdFind, searchSkillsSh };

package/lib/lock.js

@@ -0,0 +1,119 @@
+'use strict';
+
+// shucky install lockfiles — what got installed, from where, at which commit, and what the
+// scan said about it. Two files (mirrors vercel-labs/skills' split, MIT-inspired):
+//   global   ~/.shucky/installed-skills.json   (timestamps; for `list`/`update`)
+//   project  ./shucky-skills.json              (committed, sorted, timestamp-free → clean diffs)
+//
+// Recording the verdict + commit SHA is what lets a future `update` re-fetch, RE-SCAN, and warn
+// if a once-clean skill now blocks.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+function globalDir() {
+  const st = process.env.XDG_STATE_HOME;
+  if (st && path.isAbsolute(st)) return path.join(st, 'shucky');
+  return path.join(os.homedir(), '.shucky');
+}
+
+function getLockPath(scope, cwd) {
+  if (scope === 'global') return path.join(globalDir(), 'installed-skills.json');
+  return path.join(cwd || process.cwd(), 'shucky-skills.json');
+}
+
+function readLock(scope, cwd) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(getLockPath(scope, cwd), 'utf8'));
+    if (raw && raw.skills && typeof raw.skills === 'object') return { version: raw.version || 1, skills: raw.skills };
+  } catch (e) { /* missing/invalid → fresh */ }
+  return { version: 1, skills: {} };
+}
+
+function writeLock(scope, cwd, data) {
+  const p = getLockPath(scope, cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const names = Object.keys(data.skills);
+  if (scope !== 'global') names.sort(); // deterministic order for committed project lock
+  const out = { version: 1, skills: {} };
+  for (const n of names) out.skills[n] = data.skills[n];
+  fs.writeFileSync(p, JSON.stringify(out, null, 2) + '\n');
+  return p;
+}
+
+// entry: { source, sourceType, sourceUrl, ref, skillPath, hash, verdict, rawVerdict,
+//          overriddenByApproval, agents }
+function addSkill(scope, name, entry, cwd) {
+  const data = readLock(scope, cwd);
+  const e = Object.assign({}, entry);
+  if (scope === 'global') {
+    const now = new Date().toISOString();
+    const prior = data.skills[name];
+    e.installedAt = (prior && prior.installedAt) || now;
+    e.updatedAt = now;
+    if (!e.scannedAt) e.scannedAt = now;
+  } else {
+    delete e.installedAt; delete e.updatedAt; delete e.scannedAt; // committed lock stays timestamp-free
+  }
+  data.skills[name] = e;
+  return writeLock(scope, cwd, data);
+}
+
+function removeSkill(scope, name, cwd) {
+  const data = readLock(scope, cwd);
+  if (!data.skills[name]) return false;
+  delete data.skills[name];
+  writeLock(scope, cwd, data);
+  return true;
+}
+
+function getSkill(scope, name, cwd) {
+  return readLock(scope, cwd).skills[name] || null;
+}
+
+function listSkills(scope, cwd) {
+  const skills = readLock(scope, cwd).skills;
+  return Object.keys(skills).sort().map(function (name) {
+    return Object.assign({ name: name }, skills[name]);
+  });
+}
+
+// Stable sha256 over a folder's relative paths + contents (skips .git/node_modules + symlinks).
+// On-disk hash → zero-network, provider-agnostic; used to detect silent content drift.
+function computeFolderHash(dir) {
+  const files = [];
+  (function walk(d, rel) {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch (e) { return; }
+    for (const e of entries) {
+      if (e.name === '.git' || e.name === 'node_modules') continue;
+      const full = path.join(d, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      let st;
+      try { st = fs.lstatSync(full); } catch (er) { continue; }
+      if (st.isSymbolicLink()) continue;
+      if (st.isDirectory()) walk(full, r);
+      else if (st.isFile()) files.push([r, full]);
+    }
+  })(dir, '');
+  files.sort(function (a, b) { return a[0] < b[0] ? -1 : (a[0] > b[0] ? 1 : 0); });
+  const h = crypto.createHash('sha256');
+  for (const pair of files) {
+    h.update(pair[0]); h.update('\0');
+    try { h.update(fs.readFileSync(pair[1])); } catch (e) { /* ignore */ }
+    h.update('\0');
+  }
+  return 'sha256:' + h.digest('hex');
+}
+
+module.exports = {
+  getLockPath: getLockPath,
+  readLock: readLock,
+  addSkill: addSkill,
+  removeSkill: removeSkill,
+  getSkill: getSkill,
+  listSkills: listSkills,
+  computeFolderHash: computeFolderHash
+};

package/lib/place.js

@@ -0,0 +1,247 @@
+'use strict';
+
+// shucky placement — install a VETTED skill directory into the user's agent environments.
+// Ported from vercel-labs/skills `src/installer.ts` (MIT). See NOTICE.
+//
+// One security divergence from upstream: copyTree() DROPS symlinks instead of dereferencing
+// them. scanTarget() skips symlinks when it scans, so dereferencing on copy would smuggle
+// UNSCANNED content (the link target) into the install — a scan bypass. We refuse to copy any
+// symlink out of the fetched tree.
+//
+// placeSkill(skillDir, name, agentList, { scope, copy, cwd, forceCreate })
+//   -> { name, scope, mode, canonicalPath, results: [{ agent, success, path, mode, skipped?, symlinkFailed?, universal?, error? }] }
+
+const fs = require('fs');
+const path = require('path');
+const { agents, isUniversalAgent, getCanonicalSkillsDir, getAgentBaseDir } = require('./agents');
+
+const EXCLUDE_FILES = new Set(['metadata.json']);
+const EXCLUDE_DIRS = new Set(['.git', '__pycache__', '__pypackages__', 'node_modules']);
+
+// kebab-case, path-traversal-safe install name.
+function sanitizeName(name) {
+  const s = String(name).toLowerCase().replace(/[^a-z0-9._]+/g, '-').replace(/^[.\-]+|[.\-]+$/g, '');
+  return s.substring(0, 255) || 'unnamed-skill';
+}
+
+function isPathSafe(base, target) {
+  const nb = path.normalize(path.resolve(base));
+  const nt = path.normalize(path.resolve(target));
+  return nt === nb || nt.indexOf(nb + path.sep) === 0;
+}
+function pathsOverlap(a, b) { return isPathSafe(a, b) || isPathSafe(b, a); }
+
+function cleanAndCreateDirectory(p) {
+  try { fs.rmSync(p, { recursive: true, force: true }); } catch (e) { /* mkdir will surface real errors */ }
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function resolveSymlinkTarget(linkPath, linkTarget) {
+  return path.resolve(path.dirname(linkPath), linkTarget);
+}
+
+// Resolve a path's PARENT through symlinks, keeping the final component. Handles e.g.
+// ~/.claude/skills being a symlink to ~/.agents/skills, so we don't compute broken links.
+function resolveParentSymlinks(p) {
+  const resolved = path.resolve(p);
+  const dir = path.dirname(resolved);
+  const base = path.basename(resolved);
+  try { return path.join(fs.realpathSync(dir), base); } catch (e) { return resolved; }
+}
+
+// Copy a tree, DROPPING symlinks and excluded files/dirs. Returns count of skipped symlinks.
+function copyTree(src, dest, skipped) {
+  skipped = skipped || { links: 0 };
+  fs.mkdirSync(dest, { recursive: true });
+  let entries;
+  try { entries = fs.readdirSync(src, { withFileTypes: true }); } catch (e) { return skipped; }
+  for (const entry of entries) {
+    const name = entry.name;
+    const srcPath = path.join(src, name);
+    const destPath = path.join(dest, name);
+    let st;
+    try { st = fs.lstatSync(srcPath); } catch (e) { continue; }
+    if (st.isSymbolicLink()) { skipped.links++; continue; } // SECURITY: never copy symlinks out
+    if (st.isDirectory()) {
+      if (EXCLUDE_DIRS.has(name)) continue;
+      copyTree(srcPath, destPath, skipped);
+    } else if (st.isFile()) {
+      if (EXCLUDE_FILES.has(name)) continue;
+      fs.copyFileSync(srcPath, destPath);
+    }
+    // ignore fifo/socket/device entries
+  }
+  return skipped;
+}
+
+// Create a symlink (junction on win32), reconciling existing links/dirs. Returns true on success.
+function createSymlink(target, linkPath) {
+  try {
+    const resolvedTarget = path.resolve(target);
+    const resolvedLink = path.resolve(linkPath);
+
+    let realTarget, realLink;
+    try { realTarget = fs.realpathSync(resolvedTarget); } catch (e) { realTarget = resolvedTarget; }
+    try { realLink = fs.realpathSync(resolvedLink); } catch (e) { realLink = resolvedLink; }
+    if (realTarget === realLink) return true;
+    if (resolveParentSymlinks(target) === resolveParentSymlinks(linkPath)) return true;
+
+    try {
+      const st = fs.lstatSync(linkPath);
+      if (st.isSymbolicLink()) {
+        const existing = fs.readlinkSync(linkPath);
+        if (resolveSymlinkTarget(linkPath, existing) === resolvedTarget) return true;
+        fs.rmSync(linkPath, { force: true });
+      } else {
+        fs.rmSync(linkPath, { recursive: true, force: true });
+      }
+    } catch (err) {
+      if (err && err.code === 'ELOOP') { try { fs.rmSync(linkPath, { force: true }); } catch (e) { /* fall through */ } }
+      // ENOENT etc. → proceed to create
+    }
+
+    const linkDir = path.dirname(linkPath);
+    fs.mkdirSync(linkDir, { recursive: true });
+    const realLinkDir = resolveParentSymlinks(linkDir);
+    const isWin = process.platform === 'win32';
+    const symlinkType = isWin ? 'junction' : undefined;
+    const symlinkTarget = isWin ? resolvedTarget : path.relative(realLinkDir, target);
+    fs.symlinkSync(symlinkTarget, linkPath, symlinkType);
+    return true;
+  } catch (e) { return false; }
+}
+
+// ---- per-agent placement --------------------------------------------------
+
+function guardAgent(agentType, isGlobal) {
+  const agent = agents[agentType];
+  if (!agent) return { agent: agentType, success: false, error: 'unknown agent: ' + agentType };
+  if (isGlobal && agent.globalSkillsDir === undefined) {
+    return { agent: agentType, success: false, error: agent.displayName + ' does not support global install' };
+  }
+  return null;
+}
+
+function placeCopy(skillDir, skillName, agentType, isGlobal, cwd) {
+  const bad = guardAgent(agentType, isGlobal);
+  if (bad) return bad;
+  const agentBase = getAgentBaseDir(agentType, isGlobal ? 'global' : 'project', cwd);
+  const agentDir = path.join(agentBase, skillName);
+  if (!isPathSafe(agentBase, agentDir)) return { agent: agentType, success: false, error: 'path traversal in skill name' };
+  if (pathsOverlap(skillDir, agentDir)) return { agent: agentType, success: true, path: agentDir, mode: 'copy', skipped: true };
+  cleanAndCreateDirectory(agentDir);
+  copyTree(skillDir, agentDir);
+  return { agent: agentType, success: true, path: agentDir, mode: 'copy' };
+}
+
+function placeSymlink(skillDir, skillName, agentType, isGlobal, cwd, canonicalDir, forceCreate) {
+  const bad = guardAgent(agentType, isGlobal);
+  if (bad) return bad;
+  const scope = isGlobal ? 'global' : 'project';
+
+  // Universal agents read straight from the canonical dir — already written, no symlink needed.
+  if (isUniversalAgent(agentType)) {
+    return { agent: agentType, success: true, path: canonicalDir, mode: 'symlink', universal: true };
+  }
+
+  const agentBase = getAgentBaseDir(agentType, scope, cwd);
+  const agentDir = path.join(agentBase, skillName);
+  if (!isPathSafe(agentBase, agentDir)) return { agent: agentType, success: false, error: 'path traversal in skill name' };
+
+  // Project installs: don't materialise an agent dir (e.g. .windsurf/) for an agent that isn't
+  // used here — unless the user explicitly asked for it. The skill is already in .agents/skills.
+  if (!isGlobal && !forceCreate) {
+    const agentRootDir = path.join(cwd, agents[agentType].skillsDir.split('/')[0]);
+    if (!fs.existsSync(agentRootDir)) {
+      return { agent: agentType, success: true, path: canonicalDir, mode: 'symlink', skipped: true };
+    }
+  }
+
+  if (pathsOverlap(skillDir, agentDir)) return { agent: agentType, success: true, path: agentDir, mode: 'symlink', skipped: true };
+
+  if (createSymlink(canonicalDir, agentDir)) {
+    return { agent: agentType, success: true, path: agentDir, mode: 'symlink' };
+  }
+  // Symlink unsupported (e.g. Windows w/o privilege) → copy fallback.
+  cleanAndCreateDirectory(agentDir);
+  copyTree(skillDir, agentDir);
+  return { agent: agentType, success: true, path: agentDir, mode: 'symlink', symlinkFailed: true };
+}
+
+// ---- public --------------------------------------------------------------
+
+function placeSkill(skillDir, name, agentList, opts) {
+  opts = opts || {};
+  const scope = opts.scope === 'global' ? 'global' : 'project';
+  const isGlobal = scope === 'global';
+  const copy = !!opts.copy;
+  const cwd = opts.cwd || process.cwd();
+  const forceCreate = !!opts.forceCreate;
+  const skillName = sanitizeName(name);
+  agentList = agentList || [];
+  const results = [];
+
+  if (copy) {
+    for (const agentType of agentList) results.push(placeCopy(skillDir, skillName, agentType, isGlobal, cwd));
+    return { name: skillName, scope: scope, mode: 'copy', canonicalPath: null, results: results };
+  }
+
+  const canonicalBase = getCanonicalSkillsDir(scope, cwd);
+  const canonicalDir = path.join(canonicalBase, skillName);
+  if (!isPathSafe(canonicalBase, canonicalDir)) throw new Error('invalid skill name (path traversal): ' + name);
+
+  // Write the canonical copy ONCE (unless the source already is the canonical dir).
+  if (!pathsOverlap(skillDir, canonicalDir)) {
+    cleanAndCreateDirectory(canonicalDir);
+    copyTree(skillDir, canonicalDir);
+  }
+  for (const agentType of agentList) {
+    results.push(placeSymlink(skillDir, skillName, agentType, isGlobal, cwd, canonicalDir, forceCreate));
+  }
+  return { name: skillName, scope: scope, mode: 'symlink', canonicalPath: canonicalDir, results: results };
+}
+
+function removeEntry(p) {
+  try {
+    const st = fs.lstatSync(p);
+    if (st.isSymbolicLink()) { fs.rmSync(p, { force: true }); return true; }
+    fs.rmSync(p, { recursive: true, force: true });
+    return true;
+  } catch (e) { return false; }
+}
+
+// Remove a skill's canonical copy and its per-agent dirs/symlinks. Path-guarded to <base>/<name>
+// so it can only ever delete the skill's own directory, never a parent.
+function unplaceSkill(name, agentList, opts) {
+  opts = opts || {};
+  const scope = opts.scope === 'global' ? 'global' : 'project';
+  const cwd = opts.cwd || process.cwd();
+  const skillName = sanitizeName(name);
+  const removed = [];
+  const seen = new Set();
+  for (const agentType of (agentList || [])) {
+    const base = getAgentBaseDir(agentType, scope, cwd);
+    if (!base) continue;
+    const dir = path.join(base, skillName);
+    if (!isPathSafe(base, dir) || seen.has(dir)) continue;
+    seen.add(dir);
+    if (removeEntry(dir)) removed.push({ agent: agentType, path: dir });
+  }
+  const canonicalBase = getCanonicalSkillsDir(scope, cwd);
+  const canonicalDir = path.join(canonicalBase, skillName);
+  if (isPathSafe(canonicalBase, canonicalDir) && !seen.has(canonicalDir)) {
+    if (removeEntry(canonicalDir)) removed.push({ agent: 'canonical', path: canonicalDir });
+  }
+  return { name: skillName, scope: scope, removed: removed };
+}
+
+module.exports = {
+  placeSkill,
+  unplaceSkill,
+  sanitizeName,
+  isPathSafe,
+  pathsOverlap,
+  copyTree,
+  createSymlink,
+  cleanAndCreateDirectory
+};

package/lib/registry.js

@@ -0,0 +1,141 @@
+'use strict';
+
+// shucky sources registry — the repos / registries / curated lists a user trusts and searches.
+// Register a source once, then `find` across them and `install --list <name>` a curated bundle.
+// Two files: global ~/.shucky/sources.json + project ./shucky-sources.json (committed).
+//
+//   source entry = { name, type: 'repo' | 'registry' | 'list', spec, trust? }
+//     repo      a git source you install/find within (spec: owner/repo or URL)
+//     registry  a search endpoint (well-known host or skills.sh-style) — for `find`
+//     list      a manifest enumerating skills, installable as a set (spec: URL or local .json)
+//   trust: 'trusted' feeds config.trustedSources (low/medium relax; high/critical still blocks)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { safeGet } = require('./fetch');
+const { parseSource, getOwnerRepo } = require('./sources');
+
+function globalDir() {
+  const cfg = process.env.XDG_CONFIG_HOME;
+  if (cfg && path.isAbsolute(cfg)) return path.join(cfg, 'shucky');
+  return path.join(os.homedir(), '.shucky');
+}
+function sourcesPath(scope, cwd) {
+  return scope === 'global' ? path.join(globalDir(), 'sources.json') : path.join(cwd || process.cwd(), 'shucky-sources.json');
+}
+
+function read(scope, cwd) {
+  try {
+    const r = JSON.parse(fs.readFileSync(sourcesPath(scope, cwd), 'utf8'));
+    if (Array.isArray(r.sources)) return { version: r.version || 1, sources: r.sources };
+  } catch (e) { /* fresh */ }
+  return { version: 1, sources: [] };
+}
+
+function write(scope, cwd, data) {
+  const p = sourcesPath(scope, cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const sources = data.sources.slice().sort(function (a, b) { return a.name < b.name ? -1 : (a.name > b.name ? 1 : 0); });
+  fs.writeFileSync(p, JSON.stringify({ version: 1, sources: sources }, null, 2) + '\n');
+  return p;
+}
+
+function inferType(spec) {
+  if (/\.json(\?.*)?$/i.test(spec)) return 'list'; // a .json manifest (local or remote) is a list
+  const parsed = parseSource(spec);
+  if (parsed.type === 'well-known') return 'registry';
+  return 'repo';
+}
+
+function deriveName(spec) {
+  const parsed = parseSource(spec);
+  const or = getOwnerRepo(parsed);
+  if (or) return or.replace(/\//g, '-');
+  try { return new URL(spec).hostname; } catch (e) { /* fall through */ }
+  return String(spec).replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'source';
+}
+
+function addSource(scope, spec, opts, cwd) {
+  opts = opts || {};
+  const data = read(scope, cwd);
+  const type = opts.type || inferType(spec);
+  const name = opts.name || deriveName(spec);
+  data.sources = data.sources.filter(function (s) { return s.name !== name; });
+  const entry = { name: name, type: type, spec: spec };
+  if (opts.trust) entry.trust = opts.trust;
+  data.sources.push(entry);
+  return { path: write(scope, cwd, data), entry: entry };
+}
+
+function removeSource(scope, name, cwd) {
+  const data = read(scope, cwd);
+  const before = data.sources.length;
+  data.sources = data.sources.filter(function (s) { return s.name !== name; });
+  if (data.sources.length === before) return false;
+  write(scope, cwd, data);
+  return true;
+}
+
+function listSources(cwd) {
+  const out = [];
+  for (const scope of ['project', 'global']) {
+    for (const s of read(scope, cwd).sources) out.push(Object.assign({ scope: scope }, s));
+  }
+  return out;
+}
+
+function getSource(name, cwd) {
+  return listSources(cwd).find(function (s) { return s.name === name; }) || null;
+}
+
+// Resolve a `list` source (by registered name OR a direct manifest spec) → install source strings.
+// Manifest may be `["owner/repo@skill", …]` or `{ "skills": [{ "source": "...", "skill": "..." }] }`.
+async function resolveList(nameOrSpec, cwd) {
+  let spec = nameOrSpec;
+  const registered = getSource(nameOrSpec, cwd);
+  if (registered) {
+    if (registered.type !== 'list') throw new Error('source "' + nameOrSpec + '" is type ' + registered.type + ', not a list');
+    spec = registered.spec;
+  }
+  let text;
+  if (/^https?:\/\//.test(spec)) {
+    const buf = await safeGet(spec, { accept: 'application/json' });
+    text = buf.toString('utf8');
+  } else {
+    text = fs.readFileSync(path.resolve(cwd || process.cwd(), spec), 'utf8');
+  }
+  let data;
+  try { data = JSON.parse(text); } catch (e) { throw new Error('list manifest is not valid JSON: ' + spec); }
+  const arr = Array.isArray(data) ? data : (Array.isArray(data.skills) ? data.skills : []);
+  return arr.map(function (item) {
+    if (typeof item === 'string') return item;
+    if (item && item.source) return item.source + (item.skill ? '@' + item.skill : '');
+    return null;
+  }).filter(Boolean);
+}
+
+// Owner/host prefixes for sources the user marked `trusted` → merged into config.trustedSources.
+function trustedOwners(cwd) {
+  const out = [];
+  for (const s of listSources(cwd)) {
+    if (s.trust !== 'trusted') continue;
+    const or = getOwnerRepo(parseSource(s.spec));
+    if (or) out.push(or.split('/')[0]);
+    else { try { out.push(new URL(s.spec).hostname); } catch (e) { /* skip */ } }
+  }
+  return out;
+}
+
+module.exports = {
+  sourcesPath: sourcesPath,
+  read: read,
+  addSource: addSource,
+  removeSource: removeSource,
+  listSources: listSources,
+  getSource: getSource,
+  resolveList: resolveList,
+  trustedOwners: trustedOwners,
+  inferType: inferType,
+  deriveName: deriveName
+};