skills-atlas-cli 0.1.0

package/src/format.js

@@ -0,0 +1,104 @@
+// Shared output formatting: colors (TTY only), stars, language-aware text, and
+// the row / info renderers reused across commands.
+'use strict';
+
+const { rowsFor, skillDocPath } = require('./index-build');
+
+const useColor = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const wrap = (code, s) => (useColor() ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const bold = s => wrap('1', s);
+const dim = s => wrap('2', s);
+const green = s => wrap('32', s);
+const cyan = s => wrap('36', s);
+const yellow = s => wrap('33', s);
+
+function stars(n) {
+  if (n == null) return '';
+  if (n >= 10000) return `★${Math.round(n / 1000)}k`;
+  if (n >= 1000) return `★${(n / 1000).toFixed(1)}k`;
+  return `★${n}`;
+}
+
+// Language-aware field: prefer English when `en`, else the primary (Chinese).
+function text(obj, key, en) {
+  if (!obj) return '';
+  return en ? (obj[key + '_en'] || obj[key] || '') : (obj[key] || obj[key + '_en'] || '');
+}
+
+// One search/list result line block.
+function renderRow(r, { en = false } = {}) {
+  const chain = r.chain ? cyan('⛓ ') : '';
+  const cat = en ? (r._catEn || r._cat) : r._cat;
+  const lines = [`\n${chain}${bold(text(r, 'group', en))}   ${dim('[' + cat + ']')}`];
+  const uc = text(r, 'use_case', en);
+  if (uc) lines.push(`  💡 ${uc}`);
+  lines.push(`  ${dim('skills:')} ${green(r.skills.join(', '))}`);
+  const best = [...(r.sources || [])].sort((a, b) => (b.stars || 0) - (a.stars || 0))[0];
+  if (best) {
+    const inst = best.install && best.install.command ? ` — ${best.install.command}` : '';
+    lines.push(`  ${dim('via')} ${best.name} ${yellow(stars(best.stars))}${dim(inst)}`);
+  }
+  return lines.join('\n');
+}
+
+// Structured info for a skill (also used as the machine-readable --json shape).
+function buildInfo(skillName, { skillIndex, vendors }) {
+  const rows = rowsFor(skillIndex, skillName);
+  return {
+    skill: skillName,
+    found: rows.length > 0,
+    groups: rows.map(r => ({
+      group: r.group,
+      group_en: r.group_en,
+      category: r._cat,
+      chain: r.chain,
+      description: r.description,
+      description_en: r.description_en,
+      use_case: r.use_case,
+      when_to_use: r.when_to_use,
+      personas: r.personas || [],
+      sources: (r.sources || []).map(s => {
+        const v = vendors[s.name] || {};
+        const docPath = skillDocPath(v, skillName);
+        return {
+          id: s.name,
+          url: s.url,
+          stars: s.stars,
+          license: (v.skill_licenses && v.skill_licenses[skillName]) || s.license || null,
+          type: s.type,
+          path: docPath || null,
+          install: s.install || v.install || null,
+        };
+      }),
+    })),
+  };
+}
+
+function renderInfo(info, { en = false } = {}) {
+  const out = [];
+  out.push(`\n${bold(green(info.skill))}${info.groups.some(g => g.chain) ? ' ' + cyan('⛓') : ''}`);
+  for (const g of info.groups) {
+    out.push(`  ${dim('group:')} ${en ? (g.group_en || g.group) : g.group}  ${dim('[' + g.category + ']')}`);
+    const desc = en ? (g.description_en || g.description) : (g.description || g.description_en);
+    if (desc) out.push(`  ${desc}`);
+    if (g.use_case) out.push(`  ${dim('use case:')} ${g.use_case}`);
+    if (g.when_to_use) out.push(`  ${dim('when:')} ${g.when_to_use}`);
+    if (g.personas && g.personas.length) out.push(`  ${dim('personas:')} ${g.personas.join(' / ')}`);
+    out.push(`  ${dim('sources:')}`);
+    for (const s of g.sources) {
+      out.push(`    • ${bold(s.id)} ${yellow(stars(s.stars))} ${dim(s.type || '')} ${s.license ? dim('(' + s.license + ')') : ''}`);
+      out.push(`      ${dim(s.url)}`);
+      out.push(`      ${dim('path:')} ${s.path || dim('(whole-repo install — no per-skill folder)')}`);
+      if (s.install && s.install.command) {
+        out.push(`      ${dim('install:')} ${cyan(s.install.command)}`);
+        if (s.install.alt) out.push(`      ${dim('alt:')} ${s.install.alt}`);
+        if (s.install.note) out.push(`      ${dim('note:')} ${s.install.note}`);
+      }
+    }
+  }
+  return out.join('\n');
+}
+
+module.exports = {
+  bold, dim, green, cyan, yellow, stars, text, renderRow, buildInfo, renderInfo,
+};

package/src/fsutil.js

@@ -0,0 +1,52 @@
+// Filesystem helpers for installing skill folders into .claude/skills/.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Where skills get installed. Global => ~/.claude/skills, project => ./.claude/skills.
+function installTargetDir({ global }) {
+  const root = global ? os.homedir() : process.cwd();
+  return path.join(root, '.claude', 'skills');
+}
+
+function dirExists(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function mkdtemp(prefix = 'skills-atlas-') {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function writeFileMkdir(file, buf) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, buf);
+}
+
+function rmrf(p) {
+  fs.rmSync(p, { recursive: true, force: true });
+}
+
+// Atomically move a staged folder into place, replacing any existing dest.
+function swapDir(tmp, dest) {
+  ensureDir(path.dirname(dest));
+  if (dirExists(dest)) rmrf(dest);
+  fs.cpSync(tmp, dest, { recursive: true });
+  rmrf(tmp);
+}
+
+// Pretty path with ~ for the home dir.
+function tildify(p) {
+  const home = os.homedir();
+  return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+module.exports = {
+  installTargetDir, dirExists, ensureDir, mkdtemp,
+  writeFileMkdir, rmrf, swapDir, tildify,
+};

package/src/github.js

@@ -0,0 +1,126 @@
+// GitHub access for installing skills: one tree listing per install, then each
+// file fetched from raw.githubusercontent.com (which does not count against the
+// 60-req/h unauthenticated API budget). Pure Node fetch, no git binary.
+'use strict';
+
+const path = require('path');
+
+const UA = 'skills-atlas-cli';
+const TIMEOUT_MS = Number(process.env.SKILLS_ATLAS_TIMEOUT_MS) || 25000;
+
+function ghHeaders() {
+  const h = { 'User-Agent': UA, Accept: 'application/vnd.github+json' };
+  const tok = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (tok) h.Authorization = `Bearer ${tok}`;
+  return h;
+}
+
+// fetch with a hard timeout so a stalled connection never hangs the CLI.
+async function fetchT(url, opts = {}) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...opts, signal: ac.signal });
+  } catch (e) {
+    if (e.name === 'AbortError') throw new Error(`timed out after ${TIMEOUT_MS}ms: ${url}`);
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const encPath = p => p.split('/').map(encodeURIComponent).join('/');
+
+async function fetchTree(author, repo, branch) {
+  const url = `https://api.github.com/repos/${author}/${repo}/git/trees/${branch}?recursive=1`;
+  let res;
+  try {
+    res = await fetchT(url, { headers: ghHeaders() });
+  } catch (e) {
+    throw new Error(`network error reaching GitHub: ${e.message}`);
+  }
+  if (res.status === 403 || res.status === 429) {
+    if (res.headers.get('x-ratelimit-remaining') === '0') {
+      const reset = Number(res.headers.get('x-ratelimit-reset') || 0) * 1000;
+      const when = reset ? new Date(reset).toLocaleTimeString() : 'soon';
+      const e = new Error(
+        `GitHub API rate limit reached (resets ~${when}). ` +
+        `Set GITHUB_TOKEN to raise the limit to 5000/h.`);
+      e.code = 'RATE_LIMIT';
+      throw e;
+    }
+  }
+  if (res.status === 404) {
+    const e = new Error(`not found: ${author}/${repo}@${branch}`);
+    e.code = 'NOT_FOUND';
+    throw e;
+  }
+  if (!res.ok) throw new Error(`GitHub API HTTP ${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+// Fetch one file's bytes. Primary: raw.githubusercontent.com (no API budget).
+// Fallback: GitHub Contents API with the `raw` media type (works in networks
+// where raw.githubusercontent.com is blocked; counts against the API limit).
+async function fetchRaw(author, repo, branch, p) {
+  const rawUrl = `https://raw.githubusercontent.com/${author}/${repo}/${branch}/${encodeURI(p)}`;
+  try {
+    const res = await fetchT(rawUrl, { headers: { 'User-Agent': UA } });
+    if (res.ok) return Buffer.from(await res.arrayBuffer());
+  } catch { /* fall back to the API */ }
+
+  const apiUrl = `https://api.github.com/repos/${author}/${repo}/contents/${encPath(p)}?ref=${encodeURIComponent(branch)}`;
+  const res2 = await fetchT(apiUrl, { headers: { ...ghHeaders(), Accept: 'application/vnd.github.raw' } });
+  if (!res2.ok) throw new Error(`fetch failed (raw + API, HTTP ${res2.status}) for ${p}`);
+  return Buffer.from(await res2.arrayBuffer());
+}
+
+// Resolve the list of files that make up a skill folder.
+// docPath e.g. "skills/brainstorming/SKILL.md" or "pm-execution/skills/x/SKILL.md".
+// Returns { files: [{ path, rel }], branchUsed, truncated, note }.
+async function listSkillFiles({ author, repo, branch, docPath }) {
+  const folderPath = path.posix.dirname(docPath);
+
+  // Root-level SKILL.md => the "folder" is the repo root; never pull the whole
+  // repo — just take the SKILL.md so install stays a single, safe file.
+  if (folderPath === '.' || folderPath === '') {
+    return {
+      files: [{ path: docPath, rel: path.posix.basename(docPath) }],
+      branchUsed: branch || 'main',
+      truncated: false,
+      note: 'root-level SKILL.md — installed the file only',
+    };
+  }
+
+  let branchUsed = branch || 'main';
+  let tree;
+  try {
+    tree = await fetchTree(author, repo, branchUsed);
+  } catch (e) {
+    if (e.code === 'NOT_FOUND' && branchUsed !== 'master') {
+      branchUsed = 'master';
+      tree = await fetchTree(author, repo, branchUsed); // may throw again
+    } else {
+      throw e;
+    }
+  }
+
+  const prefix = folderPath.endsWith('/') ? folderPath : folderPath + '/';
+  let blobs = (tree.tree || []).filter(
+    t => t.type === 'blob' && (t.path === docPath || t.path.startsWith(prefix)));
+
+  let note = null;
+  if (blobs.length === 0) {
+    // Huge repo with a truncated tree, or the path moved. Fall back to the
+    // single SKILL.md so the install still yields the skill doc.
+    note = tree.truncated
+      ? 'repo tree truncated — installed SKILL.md only, supporting files may be missing'
+      : 'folder not found in tree — installed SKILL.md only';
+    blobs = [{ path: docPath }];
+  }
+
+  const files = blobs.map(b => ({ path: b.path, rel: b.path.slice(prefix.length) }));
+  return { files, branchUsed, truncated: !!tree.truncated, note };
+}
+
+module.exports = { listSkillFiles, fetchRaw, fetchTree };

package/src/index-build.js

@@ -0,0 +1,102 @@
+// Build in-memory indices from the catalog: a flat list of rows (for search /
+// browse) and a skill-name index (for info / install resolution).
+'use strict';
+
+function buildIndices(data) {
+  const flatRows = [];
+  // lowerSkillName -> [{ skill, row, source, vendor }]
+  const skillIndex = new Map();
+
+  for (const s of data.sections) {
+    for (const ss of s.subsections) {
+      for (const row of ss.rows) {
+        const r = { ...row, _cat: s.title, _catEn: s.title_en, _sub: ss.title, _subEn: ss.title_en };
+        flatRows.push(r);
+        for (const skill of row.skills || []) {
+          const key = String(skill).toLowerCase();
+          let arr = skillIndex.get(key);
+          if (!arr) { arr = []; skillIndex.set(key, arr); }
+          for (const source of row.sources || []) {
+            arr.push({ skill, row: r, source, vendor: data.vendors[source.name] || null });
+          }
+        }
+      }
+    }
+  }
+  return { flatRows, skillIndex, vendors: data.vendors, sections: data.sections };
+}
+
+// All entries (one per source) for an exact skill name.
+function entriesFor(skillIndex, skillName) {
+  return skillIndex.get(String(skillName).toLowerCase()) || [];
+}
+
+// The in-repo SKILL.md path for a skill in a vendor, or null. Matches the
+// skill_docs key exactly first, then case-insensitively.
+function skillDocPath(vendor, skillName) {
+  if (!vendor || !vendor.skill_docs) return null;
+  if (vendor.skill_docs[skillName]) return vendor.skill_docs[skillName];
+  const lk = String(skillName).toLowerCase();
+  for (const k of Object.keys(vendor.skill_docs)) {
+    if (k.toLowerCase() === lk) return vendor.skill_docs[k];
+  }
+  return null;
+}
+
+// Distinct vendors that provide a skill. Installable sources (those exposing the
+// skill's own folder) rank first, then by stars — so --yes / the default pick a
+// source that can actually fetch a folder when one exists.
+function vendorsFor(skillIndex, skillName) {
+  const seen = new Map();
+  for (const e of entriesFor(skillIndex, skillName)) {
+    const id = e.source && e.source.name;
+    if (id && !seen.has(id)) seen.set(id, e);
+  }
+  return [...seen.values()].sort((a, b) => {
+    const da = skillDocPath(a.vendor, a.skill) ? 1 : 0;
+    const db = skillDocPath(b.vendor, b.skill) ? 1 : 0;
+    if (da !== db) return db - da;
+    return (b.source.stars || 0) - (a.source.stars || 0);
+  });
+}
+
+// Distinct rows containing a skill (a skill usually belongs to one group).
+function rowsFor(skillIndex, skillName) {
+  const seen = new Map();
+  for (const e of entriesFor(skillIndex, skillName)) {
+    if (!seen.has(e.row)) seen.set(e.row, e.row);
+  }
+  return [...seen.values()];
+}
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  if (!m) return n;
+  if (!n) return m;
+  const dp = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    let prev = dp[0];
+    dp[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const tmp = dp[j];
+      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j], dp[j - 1]);
+      prev = tmp;
+    }
+  }
+  return dp[n];
+}
+
+// Nearest skill names for a not-found query.
+function suggestSkills(skillIndex, query, max = 5) {
+  const q = String(query).toLowerCase();
+  const names = [...skillIndex.keys()];
+  const sub = names.filter(n => n.includes(q) || q.includes(n));
+  if (sub.length) return sub.slice(0, max);
+  return names
+    .map(n => [n, levenshtein(q, n)])
+    .sort((a, b) => a[1] - b[1])
+    .slice(0, max)
+    .map(s => s[0]);
+}
+
+module.exports = { buildIndices, entriesFor, vendorsFor, rowsFor, suggestSkills, skillDocPath };

package/src/prompt.js

@@ -0,0 +1,37 @@
+// Minimal interactive prompts (no dependencies). Degrades gracefully when not
+// attached to a TTY.
+'use strict';
+
+const readline = require('readline');
+
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function ask(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, answer => { rl.close(); resolve(answer); });
+  });
+}
+
+// y/N confirm. Non-interactive returns `def`.
+async function confirm(question, def = false) {
+  if (!isInteractive()) return def;
+  const ans = (await ask(`${question} ${def ? '[Y/n]' : '[y/N]'} `)).trim().toLowerCase();
+  if (!ans) return def;
+  return ans === 'y' || ans === 'yes';
+}
+
+// Numbered choice. Returns selected index, or -1 if non-interactive / invalid.
+async function choose(title, labels) {
+  if (!isInteractive()) return -1;
+  process.stdout.write(title + '\n');
+  labels.forEach((l, i) => process.stdout.write(`  ${i + 1}) ${l}\n`));
+  const ans = (await ask(`select [1-${labels.length}] (default 1): `)).trim();
+  if (!ans) return 0;
+  const n = parseInt(ans, 10);
+  return Number.isInteger(n) && n >= 1 && n <= labels.length ? n - 1 : -1;
+}
+
+module.exports = { isInteractive, confirm, choose };

package/src/search-core.js

@@ -0,0 +1,114 @@
+// Tokenized search ranking for the catalog. Pure functions (no I/O) so they can
+// be unit-tested directly.
+//
+// Why tokenized: the query is split into terms (ASCII words + CJK bigram
+// shingles), a row matches if it contains ANY term, and rows are ranked by how
+// many terms hit and where. This makes multi-keyword and loose natural-language
+// queries work ("pdf 翻译", "translate a whole pdf") instead of requiring the
+// whole string to appear as one contiguous substring.
+'use strict';
+
+// Function words / fillers that only add noise. ASCII words + single CJK chars.
+const STOP = new Set([
+  // English
+  'i', 'me', 'my', 'we', 'our', 'us', 'you', 'your', 'a', 'an', 'the', 'to', 'of',
+  'for', 'on', 'in', 'at', 'and', 'or', 'with', 'is', 'am', 'are', 'be', 'can',
+  'do', 'does', 'how', 'what', 'which', 'want', 'wanna', 'need', 'please', 'help',
+  'using', 'use', 'via', 'that', 'this', 'these', 'those', 'it', 'its', 'make',
+  'get', 'find', 'some', 'any', 'about', 'into', 'from', 'as', 'by', 'so',
+  // Chinese
+  '我', '你', '您', '他', '她', '它', '们', '的', '地', '得', '了', '着', '吗', '呢',
+  '吧', '啊', '把', '被', '给', '帮', '想', '要', '请', '怎', '么', '如', '何', '一',
+  '个', '些', '这', '那', '可', '以', '能', '会', '用', '做', '有', '和', '与', '或',
+  '在', '是', '就', '也', '都', '还', '让', '跟', '对', '向', '我们', '帮我', '我想',
+]);
+
+// Split a (lowercased) query into search terms.
+function tokenize(query) {
+  const out = new Set();
+  const re = /[a-z0-9]+|[一-鿿]+/g;
+  let m;
+  while ((m = re.exec(query)) !== null) {
+    const chunk = m[0];
+    if (chunk.charCodeAt(0) < 0x4e00) {
+      // ASCII run: keep words of length >= 2 that aren't stopwords
+      if (chunk.length >= 2 && !STOP.has(chunk)) out.add(chunk);
+    } else {
+      const chars = [...chunk];
+      if (chars.length === 1) {
+        if (!STOP.has(chars[0])) out.add(chars[0]);
+      } else {
+        // CJK run: bigram shingles (handles run-on text with no spaces);
+        // drop bigrams made entirely of stopword chars.
+        for (let i = 0; i < chars.length - 1; i++) {
+          const a = chars[i], b = chars[i + 1];
+          if (STOP.has(a) && STOP.has(b)) continue;
+          out.add(a + b);
+        }
+      }
+    }
+  }
+  return [...out];
+}
+
+const lc = s => String(s || '').toLowerCase();
+const joinLc = (...xs) => xs.filter(Boolean).join(' ').toLowerCase();
+
+function buildFields(r) {
+  const name = joinLc(...(r.skills || []));
+  const group = joinLc(r.group, r.group_en);
+  const use = joinLc(r.use_case, r.use_case_en, r.when_to_use, r.when_to_use_en);
+  const desc = joinLc(r.description, r.description_en);
+  return { name, group, use, desc, all: [name, group, use, desc].join(' ') };
+}
+
+const maxStars = r => Math.max(0, ...(r.sources || []).map(s => s.stars || 0));
+
+// Relevance score for one row against the tokens. 0 = no match.
+function scoreRow(r, tokens, fullQuery) {
+  const f = buildFields(r);
+  let score = 0, hits = 0;
+  for (const t of tokens) {
+    let w = 0;
+    if (f.name.includes(t)) w = 10;        // matches a skill name
+    else if (f.group.includes(t)) w = 6;   // matches the group title
+    else if (f.use.includes(t)) w = 4;     // matches use_case / when_to_use
+    else if (f.desc.includes(t)) w = 2;    // matches the long description
+    if (w) { score += w; hits++; }
+  }
+  if (!hits) return 0;
+  const skillSet = new Set((r.skills || []).map(lc));
+  for (const t of tokens) if (skillSet.has(t)) score += 50;   // exact skill-name term
+  if (fullQuery && f.all.includes(fullQuery)) score += 30;    // whole phrase appears verbatim
+  score += hits * 3;                                          // coverage: more terms matched ranks higher
+  return score;
+}
+
+const loose = (hay, needle) => lc(hay).includes(lc(needle));
+
+// Filter + rank rows. opts: { query, category, persona, type, chain }.
+function searchRows(rows, opts = {}) {
+  let out = rows;
+  if (opts.category) out = out.filter(r => loose(r._cat, opts.category) || loose(r._catEn, opts.category));
+  if (opts.persona) out = out.filter(r => (r.personas || []).some(p => loose(p, opts.persona)));
+  if (opts.type) out = out.filter(r => (r.sources || []).some(s => loose(s.type, opts.type)));
+  if (opts.chain) out = out.filter(r => r.chain);
+
+  const query = lc(opts.query).trim();
+  if (!query) {
+    return out.slice().sort((a, b) => maxStars(b) - maxStars(a));
+  }
+
+  const tokens = tokenize(query);
+  if (!tokens.length) {
+    // query was all stopwords/punctuation — fall back to a plain substring match
+    return out.filter(r => buildFields(r).all.includes(query));
+  }
+  return out
+    .map(r => ({ r, s: scoreRow(r, tokens, query) }))
+    .filter(x => x.s > 0)
+    .sort((a, b) => (b.s - a.s) || (maxStars(b.r) - maxStars(a.r)))
+    .map(x => x.r);
+}
+
+module.exports = { tokenize, searchRows, scoreRow, buildFields, maxStars };