skills-atlas-cli 0.5.0 → 0.6.0

package/README.md

@@ -125,6 +125,23 @@ On top of that, `install` can place a skill straight into `.claude/skills/`:
 The catalog ships inside the package and works offline. `skills-atlas update` pulls
 the latest from the public feed (cached under `~/.cache/skills-atlas/`).
 
+## Private / org catalog sources
+
+Point the CLI at your organization's own catalog — a `data.json` in the same
+schema — so internal skills show up in `search` / `info` / `install` / `kit`
+alongside the public Atlas:
+
+```bash
+skills-atlas registry add https://skills.acme.internal/data.json   # or a local path
+skills-atlas registry list
+skills-atlas registry remove https://skills.acme.internal/data.json
+```
+
+Private skills **merge** with the public catalog (a private source wins a same-name
+clash). Sources are cached locally and merged offline. For a private URL behind
+auth, set `SKILLS_ATLAS_TOKEN` (sent as a Bearer header); in CI,
+`SKILLS_ATLAS_SOURCES=url1,url2` adds sources without touching config.
+
 ## In Claude Code
 
 A thin [Claude Code plugin](./plugin) lets Claude do all of this in-conversation —

package/bin/skills.js

@@ -11,6 +11,7 @@ const outdated = require('../src/commands/outdated');
 const doctor = require('../src/commands/doctor');
 const kit = require('../src/commands/kit');
 const sync = require('../src/commands/sync');
+const registry = require('../src/commands/registry');
 const suggest = require('../src/commands/suggest');
 const hook = require('../src/commands/hook');
 const update = require('../src/commands/update');
@@ -19,7 +20,7 @@ const { categories, list } = require('../src/commands/categories');
 const VERSION = require('../package.json').version;
 // `use` = install + activate inline (emit the SKILL.md so an agent follows it now).
 const use = argv => install([...argv, '--inline']);
-const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, update, categories, list };
+const commands = { search, info, install, use, kit, sync, installed, upgrade, remove, outdated, doctor, suggest, hook, update, categories, list, registry };
 
 const HELP = `skills-atlas — search, install & manage AI agent skills
 
@@ -47,6 +48,7 @@ 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)
+  registry           add/list/remove a private catalog source (org-internal skills)
 
 global flags: --zh (中文 output; English by default), --json (machine output), -h/--help
 docs: https://zita-go.github.io/Skills-Atlas/`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-atlas-cli",
-  "version": "0.5.0",
+  "version": "0.6.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/args.js

@@ -23,6 +23,7 @@ const ALL = {
   inline: { type: 'boolean' },
   archetype: { type: 'string' },
   update: { type: 'boolean' },
+  name: { type: 'string' },
   help: { type: 'boolean', short: 'h' },
 };
 

package/src/commands/registry.js

@@ -0,0 +1,66 @@
+// `skills-atlas registry add|list|remove` — manage private catalog sources.
+'use strict';
+
+const { parse } = require('../args');
+const { fetchSource, counts, PUBLIC_URL } = require('../data');
+const registry = require('../registry');
+const { green, dim, cyan, bold } = require('../format');
+
+const HELP = `usage: skills-atlas registry <add|list|remove> [url|path]
+
+Manage private catalog sources (a data.json in the same schema). Their skills
+merge into search / info / install / kit; a private source wins a name clash.
+
+  add <url|path>     add a source (--name <label>); fetches + caches it now
+  list               show the public default + your private sources
+  remove <url|path>  drop a source
+
+A source can be an https URL or a local file path. For a private URL behind auth,
+set SKILLS_ATLAS_TOKEN (sent as a Bearer header). CI: SKILLS_ATLAS_SOURCES=url1,url2`;
+
+module.exports = async function registryCmd(argv) {
+  const { values, positionals } = parse(argv, ['json', 'name']);
+  if (values.help) { console.log(HELP); return; }
+  const sub = positionals[0] || 'list';
+  const url = positionals[1];
+
+  if (sub === 'list') {
+    const srcs = registry.effectiveSources();
+    if (values.json) { console.log(JSON.stringify(srcs, null, 2)); return; }
+    console.log(`${bold('public')}  ${PUBLIC_URL}  ${dim('(default)')}`);
+    if (!srcs.length) { console.log(dim('no private sources. add one: skills-atlas registry add <url|path>')); return; }
+    for (const s of srcs) {
+      const cached = registry.readCachedSource(s.url);
+      const n = cached ? Object.keys(cached.vendors || {}).length : 0;
+      console.log(`${green('•')} ${s.name ? bold(s.name) + '  ' : ''}${s.url}  ${dim(cached ? n + ' vendors' : 'not fetched — run skills-atlas update')}`);
+    }
+    return;
+  }
+
+  if (sub === 'add') {
+    if (!url) { console.error('usage: skills-atlas registry add <url|path>'); process.exitCode = 1; return; }
+    try {
+      const d = await fetchSource(url);
+      registry.cacheSource(url, d);
+      registry.addSource(url, { name: values.name });
+      const c = counts(d);
+      if (values.json) { console.log(JSON.stringify({ added: url, counts: c })); return; }
+      console.log(`${green('✓')} added private source ${cyan(url)}  ${dim(`(${c.vendors} vendors, ${c.groups} groups)`)}`);
+      console.log(dim('its skills now appear in search / info / install / kit.'));
+    } catch (e) { console.error(`failed to add ${url}: ${e.message}`); process.exitCode = 1; }
+    return;
+  }
+
+  if (sub === 'remove') {
+    if (!url) { console.error('usage: skills-atlas registry remove <url|path>'); process.exitCode = 1; return; }
+    const removed = registry.removeSource(url);
+    registry.removeCachedSource(url);
+    if (values.json) { console.log(JSON.stringify({ removed: removed ? url : null })); if (!removed) process.exitCode = 1; return; }
+    if (removed) console.log(`${green('✓')} removed ${url}`);
+    else { console.error(`not a configured source: ${url}`); process.exitCode = 1; }
+    return;
+  }
+
+  console.error(`unknown registry subcommand '${sub}'. use: add | list | remove`);
+  process.exitCode = 1;
+};

package/src/commands/update.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { parse } = require('../args');
-const { refreshData } = require('../data');
+const { refreshData, refreshSources } = require('../data');
 
 module.exports = async function update(argv) {
   const { values } = parse(argv, ['json']);
@@ -12,14 +12,20 @@ module.exports = async function update(argv) {
 
   try {
     const res = await refreshData();
-    if (values.json) { console.log(JSON.stringify(res, null, 2)); return; }
+    const sources = await refreshSources();
+    if (values.json) { console.log(JSON.stringify({ ...res, sources }, null, 2)); return; }
     if (!res.changed) {
       console.log(`catalog already up to date (${res.counts.vendors} vendors, ${res.counts.groups} groups).`);
-      return;
+    } else {
+      const p = res.prevCounts;
+      const was = p ? `  ${'(was ' + p.vendors + ' vendors / ' + p.groups + ' groups)'}` : '';
+      console.log(`updated: ${res.counts.sections} sections, ${res.counts.groups} groups, ${res.counts.vendors} vendors.${was}`);
+    }
+    if (sources.length) {
+      const ok = sources.filter(s => s.ok).length;
+      const failed = sources.filter(s => !s.ok).map(s => s.url);
+      console.log(`private sources: ${ok}/${sources.length} refreshed${failed.length ? ' (failed: ' + failed.join(', ') + ')' : ''}.`);
     }
-    const p = res.prevCounts;
-    const was = p ? `  ${'(was ' + p.vendors + ' vendors / ' + p.groups + ' groups)'}` : '';
-    console.log(`updated: ${res.counts.sections} sections, ${res.counts.groups} groups, ${res.counts.vendors} vendors.${was}`);
   } catch (e) {
     console.error(`update failed: ${e.message}`);
     process.exitCode = 1;

package/src/data.js

@@ -9,6 +9,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+const registry = require('./registry');
+const { mergeCatalogs } = require('./merge');
+
 const PUBLIC_URL = 'https://zita-go.github.io/Skills-Atlas/data.json';
 const UA = 'skills-atlas-cli';
 const STALE_DAYS = 30;
@@ -75,13 +78,15 @@ function maybeStaleNudge(fromCache) {
 
 function loadData({ quiet = false } = {}) {
   const cached = tryReadJSON(cacheFile());
-  if (isValid(cached)) {
-    if (!quiet) maybeStaleNudge(true);
-    return { data: cached, source: 'cache', fromCache: true };
-  }
-  const b = loadBundled();
-  if (!quiet) maybeStaleNudge(false);
-  return { ...b, fromCache: false };
+  let base, info;
+  if (isValid(cached)) { base = cached; info = { source: 'cache', fromCache: true }; if (!quiet) maybeStaleNudge(true); }
+  else { const b = loadBundled(); base = b.data; info = { source: b.source, fromCache: false }; if (!quiet) maybeStaleNudge(false); }
+
+  const overlays = registry.effectiveSources()
+    .map(s => registry.readCachedSource(s.url))
+    .filter(isValid);
+  if (!overlays.length) return { data: base, ...info };
+  return { data: mergeCatalogs(base, overlays), source: `${info.source}+${overlays.length}private`, fromCache: info.fromCache };
 }
 
 function ensureDir(d) {
@@ -147,4 +152,40 @@ async function refreshData() {
   };
 }
 
-module.exports = { loadData, refreshData, counts, cacheDir, PUBLIC_URL };
+// Fetch (or read, for a local path / file:// URL) a private catalog source and
+// validate it. Honors SKILLS_ATLAS_TOKEN (Bearer) and SKILLS_ATLAS_TIMEOUT_MS.
+async function fetchSource(src) {
+  if (!/^https?:\/\//i.test(src)) {                  // local file path or file:// URL
+    const p = src.replace(/^file:\/\//, '');
+    let d;
+    try { d = JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) { throw new Error(`${src}: ${e.message}`); }
+    if (!isValid(d)) throw new Error(`${src}: not a valid catalog (sections/vendors)`);
+    return d;
+  }
+  const headers = { 'User-Agent': UA, Accept: 'application/json' };
+  if (process.env.SKILLS_ATLAS_TOKEN) headers.Authorization = `Bearer ${process.env.SKILLS_ATLAS_TOKEN}`;
+  const ac = new AbortController();
+  const timeoutMs = Number(process.env.SKILLS_ATLAS_TIMEOUT_MS) || 25000;
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let res;
+  try { res = await fetch(src, { headers, signal: ac.signal }); }
+  catch (e) { throw new Error(e.name === 'AbortError' ? `timed out fetching ${src}` : `network error fetching ${src}: ${e.message}`); }
+  finally { clearTimeout(timer); }
+  if (!res.ok) throw new Error(`fetch failed: HTTP ${res.status} ${res.statusText} (${src})`);
+  let d;
+  try { d = JSON.parse(await res.text()); } catch { throw new Error(`${src}: not valid JSON`); }
+  if (!isValid(d)) throw new Error(`${src}: not a valid catalog (sections/vendors)`);
+  return d;
+}
+
+// Refresh every configured private source into its local cache (best-effort).
+async function refreshSources() {
+  const out = [];
+  for (const s of registry.effectiveSources()) {
+    try { const d = await fetchSource(s.url); registry.cacheSource(s.url, d); out.push({ url: s.url, ok: true, counts: counts(d) }); }
+    catch (e) { out.push({ url: s.url, ok: false, error: e.message }); }
+  }
+  return out;
+}
+
+module.exports = { loadData, refreshData, fetchSource, refreshSources, counts, cacheDir, PUBLIC_URL };

package/src/index-build.js

@@ -53,6 +53,9 @@ function vendorsFor(skillIndex, skillName) {
     if (id && !seen.has(id)) seen.set(id, e);
   }
   return [...seen.values()].sort((a, b) => {
+    const pa = a.vendor && a.vendor._private ? 1 : 0;
+    const pb = b.vendor && b.vendor._private ? 1 : 0;
+    if (pa !== pb) return pb - pa;               // private sources first (registry override)
     const da = skillDocPath(a.vendor, a.skill) ? 1 : 0;
     const db = skillDocPath(b.vendor, b.skill) ? 1 : 0;
     if (da !== db) return db - da;

package/src/merge.js

@@ -0,0 +1,17 @@
+// Merge a base catalog with private overlays. Private vendors are tagged `_private`
+// so `vendorsFor` ranks them first on a same-name clash. Pure — returns a new object,
+// never mutates inputs, and the result lives only in memory (never cached).
+'use strict';
+
+function mergeCatalogs(base, overlays = []) {
+  const vendors = { ...(base.vendors || {}) };
+  const sections = [...(base.sections || [])];
+  for (const ov of overlays) {
+    if (!ov) continue;
+    for (const [id, v] of Object.entries(ov.vendors || {})) vendors[id] = { ...v, _private: true };
+    for (const s of (ov.sections || [])) sections.push(s);
+  }
+  return { sections, vendors };
+}
+
+module.exports = { mergeCatalogs };

package/src/registry.js

@@ -0,0 +1,78 @@
+// Private catalog sources ("registry"): user config + per-source local cache, so
+// an org can point the CLI at its own data.json alongside the public Atlas.
+// Self-contained (own XDG path helpers) to avoid a require cycle with data.js.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'skills-atlas');
+}
+const configFile = () => path.join(configDir(), 'config.json');
+
+function cacheDir() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'skills-atlas');
+}
+const sourcesDir = () => path.join(cacheDir(), 'sources');
+
+function readConfig() {
+  try {
+    const c = JSON.parse(fs.readFileSync(configFile(), 'utf8'));
+    if (!Array.isArray(c.sources)) c.sources = [];
+    return c;
+  } catch { return { version: 1, sources: [] }; }
+}
+function writeConfig(c) {
+  fs.mkdirSync(configDir(), { recursive: true });
+  fs.writeFileSync(configFile(), JSON.stringify(c, null, 2) + '\n');
+}
+function addSource(url, opts = {}) {
+  const c = readConfig();
+  const existing = c.sources.find(s => s.url === url);
+  if (existing) { if (opts.name) existing.name = opts.name; }
+  else c.sources.push({ url, name: opts.name || null, addedAt: new Date().toISOString() });
+  writeConfig(c);
+}
+function removeSource(url) {
+  const c = readConfig();
+  const before = c.sources.length;
+  c.sources = c.sources.filter(s => s.url !== url);
+  writeConfig(c);
+  return c.sources.length < before;
+}
+const listSources = () => readConfig().sources;
+
+const envSources = () => (process.env.SKILLS_ATLAS_SOURCES || '')
+  .split(',').map(s => s.trim()).filter(Boolean);
+
+function effectiveSources() {
+  const out = [], seen = new Set();
+  for (const s of listSources()) if (s.url && !seen.has(s.url)) { seen.add(s.url); out.push({ url: s.url, name: s.name || null }); }
+  for (const u of envSources()) if (!seen.has(u)) { seen.add(u); out.push({ url: u, name: null }); }
+  return out;
+}
+
+function sourceCachePath(url) {
+  const h = crypto.createHash('sha1').update(url).digest('hex').slice(0, 16);
+  return path.join(sourcesDir(), `${h}.json`);
+}
+function cacheSource(url, dataObj) {
+  fs.mkdirSync(sourcesDir(), { recursive: true });
+  fs.writeFileSync(sourceCachePath(url), JSON.stringify(dataObj));
+}
+function readCachedSource(url) {
+  try { return JSON.parse(fs.readFileSync(sourceCachePath(url), 'utf8')); } catch { return null; }
+}
+function removeCachedSource(url) {
+  try { fs.rmSync(sourceCachePath(url), { force: true }); } catch { /* ignore */ }
+}
+
+module.exports = {
+  configDir, configFile, readConfig, writeConfig, addSource, removeSource, listSources,
+  effectiveSources, sourceCachePath, cacheSource, readCachedSource, removeCachedSource,
+};