skills-atlas-cli 0.2.0 → 0.3.0

package/README.md

@@ -49,8 +49,14 @@ skills-atlas install brainstorming --project   # → ./.claude/skills/   (this p
 skills-atlas install brainstorming --chain     # install the whole ⛓ workflow it belongs to
 skills-atlas install brainstorming --dry-run   # preview the files, write nothing
 
-# 🗂️ Manage & browse
-skills-atlas installed                         # what you've installed (global + project)
+# 🗂️ Manage what you've installed   (like a package manager)
+skills-atlas installed                         # list installed (global + project)
+skills-atlas outdated                          # which have a newer upstream version
+skills-atlas upgrade brainstorming             # re-fetch to latest (--all; won't clobber local edits)
+skills-atlas remove brainstorming              # delete it
+skills-atlas doctor                            # health check: orphans, drift, license/script risks
+
+# 🌐 Catalog
 skills-atlas categories                        # the 20 top-level categories
 skills-atlas list marketing                    # skill groups within a category
 skills-atlas update                            # pull the latest catalog

package/bin/skills.js

@@ -5,21 +5,33 @@ const search = require('../src/commands/search');
 const info = require('../src/commands/info');
 const install = require('../src/commands/install');
 const installed = require('../src/commands/installed');
+const upgrade = require('../src/commands/upgrade');
+const remove = require('../src/commands/remove');
+const outdated = require('../src/commands/outdated');
+const doctor = require('../src/commands/doctor');
 const update = require('../src/commands/update');
 const { categories, list } = require('../src/commands/categories');
 
 const VERSION = require('../package.json').version;
-const commands = { search, info, install, installed, update, categories, list };
+const commands = { search, info, install, installed, upgrade, remove, outdated, doctor, update, categories, list };
 
-const HELP = `skills-atlas — search, install & learn AI agent skills
+const HELP = `skills-atlas — search, install & manage AI agent skills
 
 usage: skills-atlas <command> [args]
 
-commands:
+find & install:
   search <query>     find skills (filters: -c category, -p persona, -t type, --chain)
   info <skill>       show description, usage guidance, sources & install command
-  install <skill>    download the skill into .claude/skills/ (--chain for the whole workflow)
-  installed          list skills you've installed (global + project)
+  install <skill>    download into .claude/skills/ (--chain for the whole workflow)
+
+manage what you've installed:
+  installed          list installed skills (global + project)
+  outdated           show which installed skills have a newer upstream version
+  upgrade [skill]    re-fetch to the latest (--all; refuses to clobber local edits)
+  remove <skill>     delete an installed skill
+  doctor             health check: orphans, drift, missing SKILL.md, license/script risks
+
+catalog:
   update             refresh the catalog from the public data feed
   categories         list the top-level categories
   list [category]    list skill groups (optionally within one category)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Search, install and learn AI agent skills from the terminal — powered by the Skills Atlas catalog.",
   "bin": {
     "skills-atlas": "bin/skills.js",

package/src/commands/doctor.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, rowsFor } = require('../index-build');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { dim, yellow, green } = require('../format');
+
+const RISKY_LICENSE = /\bNC\b|GPL|AGPL|Commons[- ]?Clause/i;
+
+module.exports = async function doctor(argv) {
+  const { values } = parse(argv, ['global', 'project', 'json']);
+  if (values.help) { console.log('usage: skills-atlas doctor [--global|--project] [--json]'); return; }
+
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const findings = [];
+  const seen = {}; // skill -> [scopes]
+
+  for (const s of fsu.scopesFor(values)) {
+    const root = s.root;
+    const m = manifest.read(root);
+
+    let folders = [];
+    try {
+      folders = fs.readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+    } catch { /* no skills dir yet */ }
+
+    for (const [skill, e] of Object.entries(m.skills)) {
+      seen[skill] = (seen[skill] || []).concat(s.name);
+      const dir = path.join(root, skill);
+      if (!fsu.dirExists(dir)) { findings.push({ scope: s.name, skill, level: 'warn', msg: 'recorded but folder missing on disk' }); continue; }
+      if (!fs.existsSync(path.join(dir, 'SKILL.md'))) findings.push({ scope: s.name, skill, level: 'error', msg: 'no SKILL.md in folder' });
+      if (!data.vendors[e.source] || !rowsFor(idx.skillIndex, skill).length) findings.push({ scope: s.name, skill, level: 'info', msg: 'no longer in the catalog' });
+      if (e.scripts) findings.push({ scope: s.name, skill, level: 'info', msg: `ships ${e.scripts} script file(s) — review` });
+      const vendor = data.vendors[e.source];
+      if (vendor && vendor.license && RISKY_LICENSE.test(vendor.license)) findings.push({ scope: s.name, skill, level: 'warn', msg: `license: ${vendor.license}` });
+    }
+
+    for (const f of folders) {
+      if (!m.skills[f]) findings.push({ scope: s.name, skill: f, level: 'info', msg: 'folder not tracked by skills-atlas' });
+    }
+  }
+
+  for (const [skill, scopes] of Object.entries(seen)) {
+    if (scopes.length > 1) findings.push({ scope: scopes.join('+'), skill, level: 'warn', msg: 'installed in both scopes (project shadows global)' });
+  }
+
+  if (values.json) { console.log(JSON.stringify(findings, null, 2)); return; }
+  if (!findings.length) { console.log(`${green('✓')} all good — no issues found.`); return; }
+
+  const order = { error: 0, warn: 1, info: 2 };
+  findings.sort((a, b) => order[a.level] - order[b.level]);
+  for (const f of findings) {
+    const tag = f.level === 'error' ? '✗' : f.level === 'warn' ? yellow('!') : dim('·');
+    console.log(`  ${tag} ${f.skill} ${dim(`[${f.scope}]`)}  ${f.msg}`);
+  }
+  const e = findings.filter(f => f.level === 'error').length;
+  const w = findings.filter(f => f.level === 'warn').length;
+  console.log(`\n${e} error(s), ${w} warning(s), ${findings.length - e - w} note(s).`);
+};

package/src/commands/install.js

@@ -4,9 +4,9 @@ const path = require('path');
 const { parse } = require('../args');
 const { loadData } = require('../data');
 const { buildIndices, vendorsFor, suggestSkills, skillDocPath } = require('../index-build');
-const { listSkillFiles, getSkillFolder } = require('../github');
+const { listSkillFiles } = require('../github');
 const fsu = require('../fsutil');
-const manifest = require('../manifest');
+const { installFolder } = require('../installer');
 const { confirm, choose } = require('../prompt');
 const { buildInfo, infoForRow, renderInfo, bold, dim, cyan, green, stars, safeAlt } = require('../format');
 
@@ -32,34 +32,6 @@ function resolveGlobal(values) {
   return true; // default: global
 }
 
-const hasSkillMd = rels => rels.some(r => {
-  const x = r.toLowerCase();
-  return x === 'skill.md' || x.endsWith('/skill.md');
-});
-
-// Download one skill's folder and atomically install it; records the manifest.
-// Returns { dest, fileCount, scripts, branchUsed, note }. Throws on failure.
-async function installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName, src, row }) {
-  const folder = await getSkillFolder({ author, repo, branch, docPath });
-  const tmp = fsu.mkdtemp();
-  try {
-    for (const f of folder.files) fsu.writeFileMkdir(path.join(tmp, f.rel), f.data);
-    const rels = folder.files.map(f => f.rel);
-    if (!hasSkillMd(rels)) throw new Error('no SKILL.md found in downloaded folder');
-    fsu.swapDir(tmp, dest);
-    const scripts = fsu.scriptFiles(rels);
-    manifest.record(targetRoot, {
-      skill: skillName, source: src.name, repo, branch: folder.branchUsed,
-      group: row && row.group, category: row && row._cat,
-      files: rels.length, scripts: scripts.length, installedAt: new Date().toISOString(),
-    });
-    return { dest, fileCount: rels.length, scripts, branchUsed: folder.branchUsed, note: folder.note };
-  } catch (e) {
-    fsu.rmrf(tmp);
-    throw e;
-  }
-}
-
 // Install every installable skill in a chain (workflow). One archive download
 // serves them all (github archive cache).
 async function installChain({ row, vendor, src, targetRoot, values }) {
@@ -88,7 +60,7 @@ async function installChain({ row, vendor, src, targetRoot, values }) {
       continue;
     }
     try {
-      const r = await installFolder({ author, repo, branch, docPath: it.docPath, dest, targetRoot, skillName: it.name, src, row });
+      const r = await installFolder({ author, repo, branch, docPath: it.docPath, dest, targetRoot, skillName: it.name, source: src.name, group: row && row.group, category: row && row._cat });
       if (!values.json) console.log(`  ${green('✓')} ${it.name}  ${dim(`(${r.fileCount} files)`)}`);
       installed.push(it.name);
     } catch (e) {
@@ -261,7 +233,7 @@ module.exports = async function install(argv) {
   // --- single skill: download (archive → API fallback), record, report ---
   let result;
   try {
-    result = await installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName: skill, src, row: chosen.row });
+    result = await installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName: skill, source: src.name, group: chosen.row && chosen.row.group, category: chosen.row && chosen.row._cat });
   } catch (e) {
     console.error(`install failed: ${e.message}`);
     process.exitCode = 1;

package/src/commands/outdated.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { cyan, dim, yellow } = require('../format');
+
+const day = s => (s ? String(s).slice(0, 10) : null);
+
+module.exports = async function outdated(argv) {
+  const { values } = parse(argv, ['global', 'project', 'json']);
+  if (values.help) { console.log('usage: skills-atlas outdated [--global|--project] [--json]'); return; }
+
+  const { data } = loadData({ quiet: values.json });
+  const report = [];
+  for (const s of fsu.scopesFor(values)) {
+    for (const e of manifest.list(s.root)) {
+      const vendor = data.vendors[e.source];
+      let status, latest = null;
+      if (!vendor) {
+        status = 'not-in-catalog';
+      } else {
+        latest = vendor.last_commit || null;
+        const inst = day(e.installedAt);
+        status = (latest && inst && day(latest) > inst) ? 'outdated' : 'up-to-date';
+      }
+      report.push({ scope: s.name, skill: e.skill, source: e.source, installed: day(e.installedAt), latest, status });
+    }
+  }
+
+  if (values.json) { console.log(JSON.stringify(report, null, 2)); return; }
+  if (!report.length) { console.log('no skills installed by skills-atlas.'); return; }
+
+  for (const r of report) {
+    const tag = r.status === 'outdated' ? yellow('outdated')
+      : r.status === 'not-in-catalog' ? dim('not in catalog') : dim('up to date');
+    console.log(`  ${cyan(r.skill)} ${dim(`[${r.scope}]`)}  inst ${r.installed || '?'} · ${r.source || '?'}@${r.latest || '?'}  ${tag}`);
+  }
+  const n = report.filter(r => r.status === 'outdated').length;
+  const orphan = report.filter(r => r.status === 'not-in-catalog').length;
+  console.log(`\n${n} outdated${orphan ? `, ${orphan} not in catalog` : ''}.`);
+  if (n) console.log(dim('upgrade: skills-atlas upgrade --all   (or upgrade <skill>)'));
+};

package/src/commands/remove.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+const { parse } = require('../args');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { confirm } = require('../prompt');
+const { green, dim } = require('../format');
+
+module.exports = async function remove(argv) {
+  const { values, positionals } = parse(argv, ['global', 'project', 'yes', 'json']);
+  if (values.help) { console.log('usage: skills-atlas remove <skill> [--global|--project] [--yes]'); return; }
+
+  const name = positionals[0];
+  if (!name) { console.error('usage: skills-atlas remove <skill>'); process.exitCode = 1; return; }
+
+  const global = !values.project;
+  const root = fsu.installTargetDir({ global });
+  const dest = path.join(root, name);
+  const tracked = manifest.read(root).skills[name];
+
+  if (!fsu.dirExists(dest) && !tracked) {
+    console.error(`'${name}' is not installed (${global ? 'global' : 'project'}).`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!values.yes && !values.json) {
+    const ok = await confirm(`remove ${fsu.tildify(dest)}?`, false);
+    if (!ok) { console.log('aborted.'); return; }
+  }
+
+  if (fsu.dirExists(dest)) fsu.rmrf(dest);
+  manifest.remove(root, name);
+
+  if (values.json) { console.log(JSON.stringify({ removed: name, dest })); return; }
+  console.log(`${green('✓')} removed ${name}  ${dim(fsu.tildify(dest))}`);
+};

package/src/commands/upgrade.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const path = require('path');
+const { parse } = require('../args');
+const { loadData } = require('../data');
+const { buildIndices, vendorsFor, skillDocPath } = require('../index-build');
+const { installFolder } = require('../installer');
+const fsu = require('../fsutil');
+const manifest = require('../manifest');
+const { green, dim } = require('../format');
+
+module.exports = async function upgrade(argv) {
+  const { values, positionals } = parse(argv, ['global', 'project', 'all', 'force', 'json']);
+  if (values.help) {
+    console.log('usage: skills-atlas upgrade [<skill> | --all] [--global|--project] [--force]\n\n' +
+      'Re-fetch installed skills to the latest. Refuses to overwrite a folder you\n' +
+      'have edited locally (or one installed before change-tracking) unless --force.');
+    return;
+  }
+  if (!values.all && !positionals[0]) {
+    console.error('usage: skills-atlas upgrade <skill> | --all');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Collect (scope, skill) targets across the selected scopes (default: both),
+  // so `outdated` (both scopes) → `upgrade --all` covers the same skills.
+  const targets = [];
+  for (const s of fsu.scopesFor(values)) {
+    const m = manifest.read(s.root);
+    const names = values.all ? Object.keys(m.skills) : (m.skills[positionals[0]] ? [positionals[0]] : []);
+    for (const n of names) targets.push({ scope: s, name: n, entry: m.skills[n] });
+  }
+  if (!targets.length) {
+    if (values.json) { console.log('[]'); return; }
+    console.log(positionals[0] ? `'${positionals[0]}' is not installed by skills-atlas.` : 'nothing installed to upgrade.');
+    return;
+  }
+
+  const { data } = loadData({ quiet: values.json });
+  const idx = buildIndices(data);
+  const results = [];
+
+  for (const { scope, name, entry } of targets) {
+    const root = scope.root;
+    const rec = { skill: name, scope: scope.name };
+
+    const chosen = vendorsFor(idx.skillIndex, name).find(c => c.source.name === entry.source)
+      || vendorsFor(idx.skillIndex, name)[0];
+    if (!chosen) { results.push({ ...rec, status: 'not-in-catalog' }); continue; }
+
+    const v = chosen.vendor, src = chosen.source;
+    const docPath = skillDocPath(v, name);
+    if (!docPath) { results.push({ ...rec, status: 'no-folder' }); continue; }
+
+    const dest = path.join(root, name);
+    // drift guard — never clobber edits, and never clobber a folder of unknown
+    // provenance (installed before hashes existed) without --force.
+    if (fsu.dirExists(dest) && !values.force) {
+      if (!entry.hash) { results.push({ ...rec, status: 'no-baseline' }); continue; }
+      let cur = null;
+      try { cur = fsu.hashDir(dest); } catch { /* unreadable → fall through */ }
+      if (cur && cur !== entry.hash) { results.push({ ...rec, status: 'local-changes' }); continue; }
+    }
+
+    try {
+      const r = await installFolder({
+        author: v.author || src.author, repo: v.repo || src.repo,
+        branch: v.default_branch || src.default_branch || 'main',
+        docPath, dest, targetRoot: root, skillName: name,
+        source: src.name, group: chosen.row && chosen.row.group, category: chosen.row && chosen.row._cat,
+      });
+      results.push({ ...rec, status: (entry.hash && r.hash === entry.hash) ? 'up-to-date' : 'upgraded', files: r.fileCount });
+    } catch (e) {
+      results.push({ ...rec, status: 'failed', error: e.message });
+    }
+  }
+
+  if (values.json) { console.log(JSON.stringify(results, null, 2)); return; }
+  for (const r of results) {
+    const sym = r.status === 'upgraded' ? green('✓')
+      : r.status === 'up-to-date' ? dim('=')
+        : (r.status === 'local-changes' || r.status === 'no-baseline') ? '✋' : '✗';
+    console.log(`  ${sym} ${r.skill} ${dim(`[${r.scope}]`)}  ${dim(r.status + (r.error ? ': ' + r.error : ''))}`);
+  }
+  const up = results.filter(r => r.status === 'upgraded').length;
+  console.log(`\n${up} upgraded.`);
+  if (results.some(r => r.status === 'local-changes' || r.status === 'no-baseline')) {
+    console.log(dim('skipped some (local edits, or installed before change-tracking) — re-run with --force.'));
+  }
+};

package/src/fsutil.js

@@ -4,6 +4,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 
 // Where skills get installed. Global => ~/.claude/skills, project => ./.claude/skills.
 function installTargetDir({ global }) {
@@ -11,6 +12,15 @@ function installTargetDir({ global }) {
   return path.join(root, '.claude', 'skills');
 }
 
+// Scopes to act on from --global / --project flags (default: both).
+function scopesFor(values) {
+  const g = { name: 'global', root: installTargetDir({ global: true }) };
+  const p = { name: 'project', root: installTargetDir({ global: false }) };
+  if (values.project && !values.global) return [p];
+  if (values.global && !values.project) return [g];
+  return [g, p];
+}
+
 function dirExists(p) {
   try { return fs.statSync(p).isDirectory(); } catch { return false; }
 }
@@ -54,7 +64,31 @@ function scriptFiles(rels) {
   return (rels || []).filter(r => SCRIPT_RE.test(r));
 }
 
+// Stable content hash of a folder, for drift detection on upgrade.
+function hashFiles(files) {
+  const h = crypto.createHash('sha256');
+  for (const f of [...files].sort((a, b) => (a.rel < b.rel ? -1 : 1))) {
+    h.update(f.rel); h.update('\0'); h.update(f.data); h.update('\0');
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+// Same hash, read from an installed directory on disk.
+function hashDir(dir) {
+  const files = [];
+  const walk = (d, base) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const rel = base ? `${base}/${e.name}` : e.name;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p, rel);
+      else files.push({ rel, data: fs.readFileSync(p) });
+    }
+  };
+  walk(dir, '');
+  return hashFiles(files);
+}
+
 module.exports = {
-  installTargetDir, dirExists, ensureDir, mkdtemp,
-  writeFileMkdir, rmrf, swapDir, tildify, scriptFiles,
+  installTargetDir, scopesFor, dirExists, ensureDir, mkdtemp,
+  writeFileMkdir, rmrf, swapDir, tildify, scriptFiles, hashFiles, hashDir,
 };

package/src/installer.js

@@ -0,0 +1,39 @@
+// Shared install primitive used by both `install` (single + chain) and `upgrade`.
+'use strict';
+
+const path = require('path');
+const { getSkillFolder } = require('./github');
+const fsu = require('./fsutil');
+const manifest = require('./manifest');
+
+const hasSkillMd = rels => rels.some(r => {
+  const x = r.toLowerCase();
+  return x === 'skill.md' || x.endsWith('/skill.md');
+});
+
+// Download a skill's folder, atomically install into dest, and record the
+// manifest (with a content hash for drift detection on upgrade).
+// Returns { dest, fileCount, scripts, branchUsed, note, hash }. Throws on failure.
+async function installFolder({ author, repo, branch, docPath, dest, targetRoot, skillName, source, group, category }) {
+  const folder = await getSkillFolder({ author, repo, branch, docPath });
+  const tmp = fsu.mkdtemp();
+  try {
+    for (const f of folder.files) fsu.writeFileMkdir(path.join(tmp, f.rel), f.data);
+    const rels = folder.files.map(f => f.rel);
+    if (!hasSkillMd(rels)) throw new Error('no SKILL.md found in downloaded folder');
+    fsu.swapDir(tmp, dest);
+    const scripts = fsu.scriptFiles(rels);
+    const hash = fsu.hashFiles(folder.files);
+    manifest.record(targetRoot, {
+      skill: skillName, source, repo, branch: folder.branchUsed,
+      group, category, files: rels.length, scripts: scripts.length, hash,
+      installedAt: new Date().toISOString(),
+    });
+    return { dest, fileCount: rels.length, scripts, branchUsed: folder.branchUsed, note: folder.note, hash };
+  } catch (e) {
+    fsu.rmrf(tmp);
+    throw e;
+  }
+}
+
+module.exports = { installFolder, hasSkillMd };

package/src/manifest.js

@@ -37,6 +37,7 @@ function record(root, entry) {
     category: entry.category || null,
     files: entry.files ?? null,
     scripts: entry.scripts ?? 0,
+    hash: entry.hash || null,
     installedAt: entry.installedAt || null,
   };
   write(root, m);