skillhelper 0.4.2

package/packages/scanner/src/adapters/markdown-skill.mjs

@@ -0,0 +1,229 @@
+// markdown-skill adapter — shared logic for any source whose items are
+// SKILL.md files with YAML frontmatter (Hermes, Claude Code, gstack, …).
+//
+// Usage:
+//   import { scanMarkdownSkills } from './adapters/markdown-skill.mjs';
+//   const items = await scanMarkdownSkills({
+//     source: 'hermes',
+//     roots: ['~/.hermes/skills'],
+//     fileGlob: 'SKILL.md',
+//     limits,
+//   });
+
+import path from 'node:path';
+import fg from 'fast-glob';
+import {
+  expandRoots,
+  classifyRoot,
+  readFileSafe,
+  parseFrontmatter,
+  inferBrand,
+  inferProduct,
+  deriveDescription,
+  makePreview,
+  sha1Id,
+} from '../utils.mjs';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.source                — IR source tag
+ * @param {string[]} opts.roots               — base dirs (with ~ / globs)
+ * @param {string} [opts.fileGlob='SKILL.md'] — relative glob from each root
+ * @param {object} [opts.limits]              — { maxFiles, maxFileBytes }
+ * @returns {Promise<{items:import('../types').SkillItem[], stats:object}>}
+ */
+export async function scanMarkdownSkills(opts) {
+  const {
+    source,
+    roots,
+    fileGlob = '**/SKILL.md',
+    limits = { maxFiles: 5000, maxFileBytes: 1024 * 1024 },
+  } = opts;
+
+  const expanded = await expandRoots(roots);
+  if (!expanded.length) {
+    return { items: [], stats: { source, available: false, files: 0 } };
+  }
+
+  // collect file paths first
+  const files = [];
+  for (const root of expanded) {
+    const found = await fg(fileGlob, {
+      cwd: root,
+      absolute: true,
+      onlyFiles: true,
+      // gstack and similar plugins stash skills under hidden dirs like
+      // `.agents/skills/...`, `.cursor/skills/...`. Default dot:false dropped
+      // ~80% of claude-code skills. We let dotfiles in but still nuke noise
+      // dirs (`.git`, `node_modules`, `dist`) via the ignore list.
+      dot: true,
+      followSymbolicLinks: true,
+      deep: 10,
+      ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+    });
+    for (const f of found) {
+      files.push({ abs: f, root });
+      if (files.length >= limits.maxFiles) break;
+    }
+    if (files.length >= limits.maxFiles) break;
+  }
+
+  // parse each
+  const items = files.map(({ abs, root }) => parseSkillFile({ abs, root, source, limits }));
+  return {
+    items,
+    stats: { source, available: true, files: items.length, roots: expanded },
+  };
+}
+
+function parseSkillFile({ abs, root, source, limits }) {
+  const { text, truncated, mtime, error } = readFileSafe(abs, limits.maxFileBytes);
+  const id = sha1Id(abs);
+  const rel = path.relative(root, abs);
+
+  // category from the directory chain between root and the file
+  // e.g. ~/.hermes/skills/devops/new-api-deployment/SKILL.md
+  //      → relDir = "devops/new-api-deployment"
+  //      → category = "devops"
+  const relDir = path.dirname(rel);
+  const category = relDir && relDir !== '.' ? relDir.split('/')[0] : undefined;
+
+  // The skill's machine-name is the parent directory (Hermes / Claude Code
+  // convention is one SKILL.md per dir).
+  const dirName = path.basename(path.dirname(abs));
+
+  if (error) {
+    return baseItem({ abs, id, source, dirName, category, mtime, raw: '', parseError: error });
+  }
+  if (truncated) {
+    return baseItem({
+      abs, id, source, dirName, category, mtime, raw: '',
+      parseError: `file > ${limits.maxFileBytes} bytes, skipped`,
+    });
+  }
+
+  const { data: fm, body, i18n, parseError } = parseFrontmatter(text);
+
+  const name = (fm.name || dirName).toString().trim();
+  const title = (fm.title || fm.name || dirName).toString().trim();
+  const description = deriveDescription(fm, body);
+
+  // triggers — accept several field names used in the wild
+  const triggers = collectTriggers(fm);
+
+  // tags — accept array or comma-separated string
+  const tags = collectTags(fm);
+
+  // links — fm.links: [{label, url}] or fm.url: string
+  const links = collectLinks(fm);
+
+  const product = inferProduct({ name, category });
+  const item = {
+    id,
+    kind: 'skill',
+    source,
+    editor: editorForSource(source),
+    name,
+    title: title !== name ? title : undefined,
+    description,
+    category,
+    triggers: triggers.length ? triggers : undefined,
+    tags: tags.length ? tags : undefined,
+    paths: {
+      abs,
+      rel,
+      rootKind: classifyRoot(abs),
+    },
+    preview: makePreview(body),
+    raw: text,
+    links: links.length ? links : undefined,
+    updatedAt: new Date(mtime).toISOString(),
+    product,
+  };
+
+  // Include i18n translations if present
+  if (i18n) {
+    item.i18n = {
+      ...i18n,
+      translatedAt: new Date().toISOString(),
+      translationModel: 'frontmatter',
+    };
+  }
+
+  item.brand = inferBrand({
+    name: item.name,
+    description: item.description,
+    category: item.category,
+    raw: body,
+  });
+  if (parseError) item.parseError = parseError;
+  return item;
+}
+
+function baseItem({ abs, id, source, dirName, category, mtime, raw, parseError }) {
+  return {
+    id,
+    kind: 'skill',
+    source,
+    editor: editorForSource(source),
+    name: dirName,
+    description: undefined,
+    category,
+    paths: { abs, rootKind: classifyRoot(abs) },
+    preview: '',
+    raw,
+    updatedAt: new Date(mtime).toISOString(),
+    parseError,
+  };
+}
+
+function editorForSource(source) {
+  const map = {
+    hermes: 'Hermes Agent',
+    'claude-code': 'Claude Code',
+    codex: 'Codex',
+    cursor: 'Cursor',
+    'mcp-config': 'MCP',
+    project: 'Project Docs',
+  };
+  return map[source] || source;
+}
+
+function collectTriggers(fm) {
+  const out = [];
+  const candidates = [fm.triggers, fm.aliases, fm.when_to_use];
+  for (const c of candidates) {
+    if (!c) continue;
+    if (Array.isArray(c)) {
+      out.push(...c.filter(x => typeof x === 'string').map(x => x.trim()));
+    } else if (typeof c === 'string') {
+      // when_to_use is usually a long sentence — keep it as a single trigger
+      out.push(c.trim());
+    }
+  }
+  // dedup, preserve order
+  return [...new Set(out)];
+}
+
+function collectTags(fm) {
+  const v = fm.tags;
+  if (!v) return [];
+  if (Array.isArray(v)) return v.filter(x => typeof x === 'string');
+  if (typeof v === 'string') return v.split(',').map(s => s.trim()).filter(Boolean);
+  return [];
+}
+
+function collectLinks(fm) {
+  const out = [];
+  if (Array.isArray(fm.links)) {
+    for (const l of fm.links) {
+      if (l && typeof l === 'object' && l.url) {
+        out.push({ label: l.label || l.url, url: l.url });
+      }
+    }
+  }
+  if (typeof fm.url === 'string') {
+    out.push({ label: 'docs', url: fm.url });
+  }
+  return out;
+}

package/packages/scanner/src/adapters/mcp-config.mjs

@@ -0,0 +1,190 @@
+// MCP config adapter — reads local config files and exposes MCP servers as safe IR.
+// Values that may contain credentials are redacted before entering `raw`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import {
+  classifyRoot,
+  expandTilde,
+  makePreview,
+  readFileSafe,
+  sha1Id,
+} from '../utils.mjs';
+
+const SECRET_KEY_RE = /(token|key|secret|password|passwd|credential|authorization|auth|cookie)/i;
+
+export async function scanMcpConfigs(opts) {
+  const {
+    source = 'mcp-config',
+    editor = 'MCP',
+    files = [],
+    limits = { maxFiles: 5000, maxFileBytes: 1024 * 1024 },
+  } = opts;
+
+  const items = [];
+  for (const f of files || []) {
+    const abs = path.resolve(expandTilde(f));
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+    items.push(...parseConfigFile({ abs, source, editor, limits }));
+    if (items.length >= limits.maxFiles) break;
+  }
+  return { items, stats: { source, available: true, files: items.length } };
+}
+
+function parseConfigFile({ abs, source, editor, limits }) {
+  const { text, truncated, mtime, error } = readFileSafe(abs, limits.maxFileBytes);
+  const rootKind = classifyRoot(abs);
+  const fileName = path.basename(abs);
+  const brand = inferBrandFromPath(abs);
+  if (error || truncated) {
+    return [baseItem({ abs, source, editor, brand, name: fileName, description: error || 'file too large', raw: '', mtime, rootKind })];
+  }
+
+  const parsed = parseAny(abs, text);
+  if (!parsed.ok) {
+    return [baseItem({ abs, source, editor, brand, name: fileName, description: `MCP/config file: ${fileName}`, raw: redactText(text), mtime, rootKind, parseError: parsed.error })];
+  }
+
+  const servers = extractMcpServers(parsed.value);
+  if (!servers.length) {
+    return [baseItem({ abs, source, editor, brand, name: fileName, description: `Config file: ${fileName}`, raw: safeStringify(parsed.value), mtime, rootKind })];
+  }
+
+  return servers.map(([serverName, cfg]) => {
+    const safeCfg = redact(cfg);
+    const command = typeof cfg?.command === 'string' ? cfg.command : undefined;
+    const url = typeof cfg?.url === 'string' ? redactText(cfg.url) : undefined;
+    const description = command
+      ? `MCP server · command: ${command}`
+      : url
+        ? `MCP server · url: ${url}`
+        : 'MCP server';
+    const item = {
+      id: sha1Id(`${abs}#${serverName}`),
+      kind: 'mcp',
+      source,
+      editor,
+      name: serverName,
+      description,
+      category: 'mcp',
+      product: serverName,
+      tags: ['mcp'],
+      paths: { abs, rel: fileName, rootKind },
+      preview: makePreview(safeStringify(safeCfg), 600),
+      raw: safeStringify({ [serverName]: safeCfg }),
+      updatedAt: new Date(mtime).toISOString(),
+    };
+    if (brand) {
+      item.brand = brand;
+      item.editorBrand = brand;
+    }
+    return item;
+  });
+}
+
+function inferBrandFromPath(abs) {
+  const normalized = abs.toLowerCase();
+  if (normalized.includes('/.codex/') || normalized.includes('codex')) return 'codex';
+  if (normalized.includes('/.claude/') || normalized.includes('claude_desktop') || normalized.includes('/claude')) return 'claude';
+  if (normalized.includes('/.hermes/') || normalized.includes('/hermes/')) return 'hermes';
+  if (normalized.includes('/.cursor/') || normalized.includes('cursor')) return 'cursor';
+  return undefined;
+}
+
+function baseItem({ abs, source, editor, brand, name, description, raw, mtime, rootKind, parseError }) {
+  const item = {
+    id: sha1Id(abs),
+    kind: 'config',
+    source,
+    editor,
+    name,
+    description,
+    category: 'config',
+    product: name,
+    paths: { abs, rel: path.basename(abs), rootKind },
+    preview: makePreview(raw, 600),
+    raw,
+    updatedAt: new Date(mtime).toISOString(),
+  };
+  if (brand) {
+    item.brand = brand;
+    item.editorBrand = brand;
+  }
+  if (parseError) item.parseError = parseError;
+  return item;
+}
+
+function parseAny(abs, text) {
+  try {
+    if (/\.json$/i.test(abs)) return { ok: true, value: JSON.parse(text) };
+    if (/\.ya?ml$/i.test(abs)) return { ok: true, value: YAML.parse(text) || {} };
+    if (/\.toml$/i.test(abs)) return { ok: true, value: parseTomlMcpSubset(text) };
+    return { ok: true, value: YAML.parse(text) || {} };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function extractMcpServers(obj) {
+  if (!obj || typeof obj !== 'object') return [];
+  const candidate = obj.mcpServers || obj.mcp_servers || obj.servers || obj.mcp?.servers;
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) return [];
+  return Object.entries(candidate);
+}
+
+function parseTomlMcpSubset(text) {
+  const out = { mcp_servers: {} };
+  let current = null;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const sec = line.match(/^\[mcp_servers\.([^\]]+)\]$/);
+    if (sec) {
+      current = sec[1].replace(/^['"]|['"]$/g, '');
+      out.mcp_servers[current] = {};
+      continue;
+    }
+    if (!current) continue;
+    const kv = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    out.mcp_servers[current][key] = parseTomlValue(kv[2]);
+  }
+  return out;
+}
+
+function parseTomlValue(v) {
+  const s = v.trim();
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) return s.slice(1, -1);
+  if (s.startsWith('[') && s.endsWith(']')) {
+    return s.slice(1, -1).split(',').map(x => parseTomlValue(x.trim())).filter(x => x !== '');
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  return s;
+}
+
+function redact(value, key = '') {
+  if (SECRET_KEY_RE.test(key)) return '[REDACTED]';
+  if (Array.isArray(value)) return value.map(v => redact(v, key));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redact(v, k);
+    return out;
+  }
+  if (typeof value === 'string') return redactText(value);
+  return value;
+}
+
+function redactText(text) {
+  return String(text || '')
+    .replace(/(sk-[A-Za-z0-9_-]{12,})/g, '[REDACTED]')
+    .replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]{12,}/gi, '$1[REDACTED]')
+    .replace(/([?&](?:token|key|secret|password|auth)=)[^&\s]+/gi, '$1[REDACTED]')
+    .replace(/((?:TOKEN|KEY|SECRET|PASSWORD|AUTH)[A-Z0-9_]*\s*[=:]\s*)[^\s"']+/g, '$1[REDACTED]');
+}
+
+function safeStringify(obj) {
+  return JSON.stringify(redact(obj), null, 2);
+}

package/packages/scanner/src/adapters/scan-tier.mjs

@@ -0,0 +1,99 @@
+/**
+ * @file scan-tier.mjs
+ * v4.0 三层优先级扫描器
+ * 集成 Tier 1（编辑器工具）+ Tier 2（用户根目录）+ Tier 3（其他）
+ */
+
+import { scanTier1EditorSkills } from './tier1-editor-skills.mjs';
+import { scanTier2UserSkills } from './tier2-user-skills.mjs';
+import { scanTier3OtherSkills } from './tier3-other-skills.mjs';
+import { pathHashCache } from '../hash/path-hash.mjs';
+
+/**
+ * 三层优先级扫描
+ *
+ * @param {Object} options
+ * @param {boolean} [options.scanTier1=true] - 是否扫描第1层（编辑器工具）
+ * @param {boolean} [options.scanTier2=true] - 是否扫描第2层（用户根目录）
+ * @param {boolean} [options.scanTier3=false] - 是否扫描第3层（其他位置）
+ * @param {string} [options.projectRoot] - 项目根目录（用于扫描 .hermes/skills 等）
+ * @param {Object} [options.limits] - { maxFiles, maxFileBytes }
+ * @returns {Promise<{items: SkillItem[], stats: Object}>}
+ */
+export async function scanTierSkills(options = {}) {
+  const { 
+    scanTier1 = true,
+    scanTier2 = true, 
+    scanTier3 = false, 
+    projectRoot = process.cwd(), 
+    limits = {} 
+  } = options;
+
+  const mergedLimits = {
+    maxFiles: limits.maxFiles ?? 5000,
+    maxFileBytes: limits.maxFileBytes ?? 1024 * 1024,
+  };
+
+  // Step 1: 扫描第1层
+  console.error('[scan] Tier 1: scanning editor tools...');
+  const tier1Result = await scanTier1EditorSkills({ projectRoot, limits: mergedLimits });
+  const tier1Items = tier1Result.items;
+  const tier1PathHashes = tier1Result.pathHashes;
+  console.error(`[scan] Tier 1: found ${tier1Items.length} skills`);
+
+  // Step 2: 扫描第2层（排除第1层已有的）
+  console.error('[scan] Tier 2: scanning user skills library...');
+  const tier2Result = await scanTier2UserSkills({
+    tier1PathHashes,
+    limits: mergedLimits,
+  });
+  const tier2Items = tier2Result.items;
+  const tier2PathHashes = tier2Result.pathHashes;
+  console.error(`[scan] Tier 2: found ${tier2Items.length} skills`);
+
+  // Step 3: 扫描第3层（如果启用，排除第1、2层已有的）
+  let tier3Items = [];
+  if (scanTier3) {
+    console.error('[scan] Tier 3: scanning other locations...');
+    const tier3Result = await scanTier3OtherSkills({
+      tier1PathHashes,
+      tier2PathHashes,
+      limits: mergedLimits,
+    });
+    tier3Items = tier3Result.items;
+    console.error(`[scan] Tier 3: found ${tier3Items.length} skills`);
+  }
+
+  // 合并结果
+  const allItems = [...tier1Items, ...tier2Items, ...tier3Items];
+
+  // 按 tier → category → name 排序
+  allItems.sort((a, b) => {
+    const tierOrder = { 'tier-1': 0, 'tier-2': 1, 'tier-3': 2 };
+    const tierCmp = (tierOrder[a.tierId] ?? 99) - (tierOrder[b.tierId] ?? 99);
+    if (tierCmp !== 0) return tierCmp;
+
+    const catCmp = (a.category || '').localeCompare(b.category || '');
+    if (catCmp !== 0) return catCmp;
+
+    return a.name.localeCompare(b.name);
+  });
+
+  return {
+    items: allItems,
+    stats: {
+      tier1Count: tier1Items.length,
+      tier2Count: tier2Items.length,
+      tier3Count: tier3Items.length,
+      total: allItems.length,
+      pathHashes: {
+        tier1: Array.from(tier1PathHashes),
+        tier2: Array.from(tier2PathHashes),
+      },
+      cacheSize: pathHashCache.size,
+      scannedAt: new Date().toISOString(),
+    },
+  };
+}
+
+export { pathHashCache };