@booklib/core 2.0.0

package/lib/discovery-engine.js

@@ -0,0 +1,298 @@
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import { resolveBookLibPaths } from './paths.js';
+import { loadConfig } from './config-loader.js';
+
+const DISCOVERED_FILENAME = 'discovered.json';
+const GITHUB_AUTH_HEADER = process.env.GITHUB_TOKEN
+  ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` }
+  : {};
+
+/**
+ * Scans approved sources (GitHub orgs, npm scopes) for available skills.
+ * Results are cached with a TTL to avoid hammering external APIs.
+ */
+export class DiscoveryEngine {
+  constructor(options = {}) {
+    this.paths = resolveBookLibPaths(options.projectCwd);
+    this.config = loadConfig(options.projectCwd);
+    this.cacheFile = path.join(this.paths.cachePath, DISCOVERED_FILENAME);
+  }
+
+  /**
+   * Returns all discoverable skills from approved sources.
+   * Uses cache if fresh; re-scans if stale or missing.
+   *
+   * @returns {Array<object>} List of discovered skill descriptors
+   */
+  async discover() {
+    const cached = this._loadCache();
+    if (cached) return cached;
+
+    const results = [];
+
+    for (const source of this.config.sources) {
+      if (source.type === 'registry') continue; // bundled registry handled separately
+      try {
+        const found = await this._scanSource(source);
+        results.push(...found);
+      } catch {
+        // Non-fatal: skip unreachable sources
+      }
+    }
+
+    this._saveCache(results);
+    return results;
+  }
+
+  /**
+   * Forces a re-scan, ignoring any cached results.
+   */
+  async refresh() {
+    this._clearCache();
+    return this.discover();
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  async _scanSource(source) {
+    if (source.type === 'github-org') {
+      return this._scanGitHubOrg(source);
+    }
+    if (source.type === 'npm-scope') {
+      return this._scanNpmScope(source);
+    }
+    if (source.type === 'manifest') {
+      return this._scanManifest(source);
+    }
+    if (source.type === 'github-skills-dir') {
+      return this._scanGitHubSkillsDir(source);
+    }
+    return [];
+  }
+
+  /**
+   * Scans a specific directory in a GitHub repo for subdirectories containing SKILL.md.
+   * Fetches the frontmatter from each SKILL.md to populate name/description.
+   *
+   * Source format:
+   *   { type: 'github-skills-dir', repo: 'owner/repo', dir: 'skills', branch: 'main', trusted: false }
+   */
+  async _scanGitHubSkillsDir(source) {
+    const { repo, dir = 'skills', branch = 'main', trusted = false } = source;
+    const apiUrl = `https://api.github.com/repos/${repo}/contents/${dir}`;
+
+    let entries;
+    try {
+      entries = await this._fetchJson(apiUrl);
+    } catch {
+      return [];
+    }
+
+    if (!Array.isArray(entries)) return [];
+
+    const skills = [];
+    const subdirs = entries.filter(e => e.type === 'dir');
+
+    for (const subdir of subdirs) {
+      const skillUrl = `https://raw.githubusercontent.com/${repo}/${branch}/${dir}/${subdir.name}/SKILL.md`;
+      const exists = await this._urlExists(skillUrl);
+      if (!exists) continue;
+
+      // Fetch first 25 lines to extract frontmatter name/description without loading full file
+      let name = subdir.name;
+      let description = '';
+      try {
+        const head = await this._fetchHead(skillUrl, 25);
+        const nameMatch = head.match(/^name:\s*(.+)$/m);
+        if (nameMatch) name = nameMatch[1].trim().replace(/^["']|["']$/g, '');
+        description = this._parseFrontmatterDescription(head);
+      } catch { /* use defaults */ }
+
+      skills.push({
+        name,
+        description,
+        source: { type: 'github', url: skillUrl, repo, dir: subdir.name },
+        triggers: { extensions: [], keywords: name.split('-') },
+        trusted,
+      });
+    }
+
+    return skills;
+  }
+
+  /** Fetches just the first N lines of a text file (avoids downloading large files). */
+  _fetchHead(url, lines = 20) {
+    return new Promise((resolve, reject) => {
+      const options = { headers: { 'User-Agent': 'booklib-discovery/1.0', 'Range': 'bytes=0-2000', ...GITHUB_AUTH_HEADER } };
+      https.get(url, options, res => {
+        let data = '';
+        res.on('data', chunk => (data += chunk));
+        res.on('end', () => resolve(data.split('\n').slice(0, lines).join('\n')));
+      }).on('error', reject);
+    });
+  }
+
+  /**
+   * Fetches a JSON manifest file (local path or HTTPS URL) and returns its skill list.
+   * Manifest format: { version: 1, skills: [{ name, description, stars, source, trusted, ... }] }
+   */
+  async _scanManifest(source) {
+    let data;
+    if (source.url.startsWith('http')) {
+      data = await this._fetchJson(source.url);
+    } else {
+      // Local file path (absolute or relative to cwd)
+      const filePath = path.resolve(source.url);
+      if (!fs.existsSync(filePath)) return [];
+      try { data = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return []; }
+    }
+
+    const skills = data?.skills ?? [];
+    // Allow the source entry to override trusted for the whole manifest
+    return skills.map(skill => ({
+      ...skill,
+      trusted: source.trusted ?? skill.trusted ?? false,
+    }));
+  }
+
+  /**
+   * Lists repositories in a GitHub org and checks each for a SKILL.md at the root.
+   */
+  async _scanGitHubOrg(source) {
+    const { org, trusted = false } = source;
+    const reposUrl = `https://api.github.com/orgs/${org}/repos?per_page=100&type=public`;
+
+    let repos;
+    try {
+      const body = await this._fetchJson(reposUrl);
+      repos = Array.isArray(body) ? body : [];
+    } catch {
+      return [];
+    }
+
+    const skills = [];
+    for (const repo of repos) {
+      const skillUrl = `https://raw.githubusercontent.com/${org}/${repo.name}/main/SKILL.md`;
+      const exists = await this._urlExists(skillUrl);
+      if (exists) {
+        skills.push({
+          name: repo.name,
+          description: repo.description ?? '',
+          source: { type: 'github', org, repo: repo.name, url: skillUrl },
+          trusted,
+        });
+      }
+    }
+    return skills;
+  }
+
+  /**
+   * Searches npm for packages in a given scope and checks each for a SKILL.md in their dist.
+   */
+  async _scanNpmScope(source) {
+    const { scope, trusted = false } = source;
+    const searchUrl = `https://registry.npmjs.org/-/v1/search?text=scope:${scope.replace('@', '')}&size=50`;
+
+    let body;
+    try {
+      body = await this._fetchJson(searchUrl);
+    } catch {
+      return [];
+    }
+
+    const packages = body?.objects ?? [];
+    return packages.map(pkg => ({
+      name: pkg.package.name,
+      description: pkg.package.description ?? '',
+      source: { type: 'npm', package: pkg.package.name, version: pkg.package.version },
+      trusted,
+    }));
+  }
+
+  // ── Cache helpers ──────────────────────────────────────────────────────────
+
+  _loadCache() {
+    if (!fs.existsSync(this.cacheFile)) return null;
+    try {
+      const data = JSON.parse(fs.readFileSync(this.cacheFile, 'utf8'));
+      const ttlMs = (this.config.discovery.ttlHours ?? 24) * 60 * 60 * 1000;
+      if (Date.now() - data.timestamp < ttlMs) {
+        return data.skills;
+      }
+    } catch { /* corrupt cache */ }
+    return null;
+  }
+
+  _saveCache(skills) {
+    fs.mkdirSync(path.dirname(this.cacheFile), { recursive: true });
+    fs.writeFileSync(this.cacheFile, JSON.stringify({ timestamp: Date.now(), skills }, null, 2));
+  }
+
+  _clearCache() {
+    if (fs.existsSync(this.cacheFile)) fs.unlinkSync(this.cacheFile);
+  }
+
+  // ── Frontmatter helpers ────────────────────────────────────────────────────
+
+  /**
+   * Extracts description from YAML frontmatter, handling all common formats:
+   *   description: single line value
+   *   description: "quoted value"
+   *   description: |
+   *     block scalar (literal, preserves newlines)
+   *   description: >
+   *     folded scalar (folds newlines to spaces)
+   */
+  _parseFrontmatterDescription(text) {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^description:\s*(.*)/);
+      if (!m) continue;
+      const inline = m[1].trim();
+      // Block/folded scalar — collect indented continuation lines
+      if (inline === '|' || inline === '>') {
+        const parts = [];
+        for (let j = i + 1; j < lines.length; j++) {
+          if (lines[j].match(/^\s+/) || lines[j].trim() === '') {
+            const part = lines[j].trim();
+            if (part) parts.push(part);
+            else break;
+          } else break;
+        }
+        return parts.join(inline === '>' ? ' ' : ' ').trim();
+      }
+      // Strip surrounding quotes
+      return inline.replace(/^["']|["']$/g, '');
+    }
+    return '';
+  }
+
+  // ── HTTP helpers ───────────────────────────────────────────────────────────
+
+  _fetchJson(url) {
+    return new Promise((resolve, reject) => {
+      const options = { headers: { 'User-Agent': 'booklib-discovery/1.0', ...GITHUB_AUTH_HEADER } };
+      https.get(url, options, res => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return resolve(this._fetchJson(res.headers.location));
+        }
+        let data = '';
+        res.on('data', chunk => (data += chunk));
+        res.on('end', () => {
+          try { resolve(JSON.parse(data)); } catch { reject(new Error('Invalid JSON')); }
+        });
+      }).on('error', reject);
+    });
+  }
+
+  _urlExists(url) {
+    return new Promise(resolve => {
+      const options = { method: 'HEAD', headers: { 'User-Agent': 'booklib-discovery/1.0', ...GITHUB_AUTH_HEADER } };
+      https.request(url, options, res => resolve(res.statusCode === 200))
+        .on('error', () => resolve(false))
+        .end();
+    });
+  }
+}

package/lib/doctor/hook-installer.js

@@ -0,0 +1,83 @@
+// lib/doctor/hook-installer.js
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const TRACK_USAGE_CONTENT = `#!/usr/bin/env node
+// track-usage.mjs — installed by: booklib doctor --install-hook
+// Appends { skill, timestamp } to ~/.booklib/usage.json on every Skill tool invocation.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const raw = process.argv[2] ?? '{}';
+let input;
+try { input = JSON.parse(raw); } catch { process.exit(0); }
+
+const skill = input?.skill ?? input?.name ?? input?.args?.skill;
+if (!skill || typeof skill !== 'string') process.exit(0);
+
+const dir  = path.join(os.homedir(), '.booklib');
+const file = path.join(dir, 'usage.json');
+
+try {
+  fs.mkdirSync(dir, { recursive: true });
+  let entries = [];
+  try {
+    entries = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') process.exit(0);
+  }
+  entries.push({ skill: skill.trim(), timestamp: new Date().toISOString() });
+  fs.writeFileSync(file, JSON.stringify(entries, null, 2));
+} catch {
+  process.exit(0);
+}
+`;
+
+const HOOK_COMMAND = `node ~/.booklib/track-usage.mjs "$TOOL_INPUT"`;
+
+/**
+ * Installs the usage-tracking hook into Claude Code settings.
+ *
+ * @param {string} [home]
+ * @returns {{ scriptPath: string, settingsPath: string, alreadyInstalled: boolean }}
+ */
+export function installTrackingHook(home = os.homedir()) {
+  const booklibDir   = path.join(home, '.booklib');
+  const claudeDir    = path.join(home, '.claude');
+  const scriptPath   = path.join(booklibDir, 'track-usage.mjs');
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  fs.mkdirSync(booklibDir, { recursive: true });
+  fs.writeFileSync(scriptPath, TRACK_USAGE_CONTENT);
+
+  fs.mkdirSync(claudeDir, { recursive: true });
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+
+  const newEntry = {
+    matcher: 'Skill',
+    hooks: [{ type: 'command', command: HOOK_COMMAND }],
+  };
+
+  const existingIdx = settings.hooks.PreToolUse.findIndex(e => e.matcher === 'Skill');
+  const alreadyInstalled = existingIdx !== -1 &&
+    settings.hooks.PreToolUse[existingIdx]?.hooks?.[0]?.command === HOOK_COMMAND;
+
+  if (existingIdx !== -1) {
+    settings.hooks.PreToolUse[existingIdx] = newEntry;
+  } else {
+    settings.hooks.PreToolUse.push(newEntry);
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  return { scriptPath, settingsPath, alreadyInstalled };
+}

package/lib/doctor/usage-tracker.js

@@ -0,0 +1,87 @@
+// lib/doctor/usage-tracker.js
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_USAGE_PATH = path.join(os.homedir(), '.booklib', 'usage.json');
+
+/**
+ * Appends a single usage entry to the usage log.
+ * Creates the file (and parent dirs) if absent.
+ */
+export function appendUsage(skillName, usagePath = DEFAULT_USAGE_PATH) {
+  fs.mkdirSync(path.dirname(usagePath), { recursive: true });
+  let entries = [];
+  try {
+    entries = JSON.parse(fs.readFileSync(usagePath, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  entries.push({ skill: skillName, timestamp: new Date().toISOString() });
+  fs.writeFileSync(usagePath, JSON.stringify(entries, null, 2));
+}
+
+/**
+ * Reads and parses the usage log. Returns [] if file does not exist.
+ */
+export function readUsage(usagePath = DEFAULT_USAGE_PATH) {
+  if (!fs.existsSync(usagePath)) return [];
+  try {
+    return JSON.parse(fs.readFileSync(usagePath, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Derives per-skill health summaries from raw usage data.
+ *
+ * @param {{ skill: string, timestamp: string }[]} usageData
+ * @param {string[]} installedNames
+ * @param {Object.<string, Date>} [installDates]
+ */
+export function summarize(usageData, installedNames, installDates = {}) {
+  const NOW    = Date.now();
+  const MS_1D  = 24 * 60 * 60 * 1000;
+  const MS_60D = 60 * MS_1D;
+  const MS_30D = 30 * MS_1D;
+
+  const countMap   = new Map();
+  const lastMap    = new Map();
+  const recent60Map = new Map();
+  const cutoff60   = new Date(NOW - MS_60D);
+
+  for (const { skill, timestamp } of usageData) {
+    countMap.set(skill, (countMap.get(skill) ?? 0) + 1);
+    const ts = new Date(timestamp);
+    if (!lastMap.has(skill) || ts > lastMap.get(skill)) lastMap.set(skill, ts);
+    if (ts >= cutoff60) recent60Map.set(skill, (recent60Map.get(skill) ?? 0) + 1);
+  }
+
+  const results = installedNames.map(name => {
+    const uses       = countMap.get(name) ?? 0;
+    const lastUsed   = lastMap.get(name) ?? null;
+    const daysSince  = lastUsed ? Math.floor((NOW - lastUsed.getTime()) / MS_1D) : null;
+    const recent60   = recent60Map.get(name) ?? 0;
+    const installDate = installDates[name] ?? null;
+
+    const isEstablished = uses > 0 || (installDate && (NOW - installDate.getTime()) > 14 * MS_1D);
+
+    let suggestion = null;
+    if (uses === 0 && installDate && (NOW - installDate.getTime()) > MS_30D) {
+      suggestion = 'remove';
+    } else if (isEstablished && recent60 < 2) {
+      suggestion = 'low-activity';
+    }
+
+    return { name, uses, lastUsed, daysSinceLastUse: daysSince, suggestion };
+  });
+
+  results.sort((a, b) => {
+    if (a.suggestion === null && b.suggestion !== null) return -1;
+    if (a.suggestion !== null && b.suggestion === null) return 1;
+    return b.uses - a.uses;
+  });
+
+  return results;
+}