skillhelper 0.4.2

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

@@ -0,0 +1,239 @@
+// directory-skill adapter — scan SKILL.md files from custom directories.
+//
+// This adapter scans user-specified directories (via directorySkillPaths in
+// sources.yaml) for SKILL.md files. Each matched file is parsed as a skill
+// and tagged with tier='directory' and dirName={parent directory name}.
+//
+// Usage:
+//   import { scanDirectorySkills } from './adapters/directory-skill.mjs';
+//   const result = await scanDirectorySkills({
+//     paths: ['~/Project/SkillsHelper/packages/skills', '~/Work/custom-skills'],
+//     limits,
+//   });
+
+import path from 'node:path';
+import fg from 'fast-glob';
+import {
+  expandRoots,
+  classifyRoot,
+  readFileSafe,
+  parseFrontmatter,
+  inferBrand,
+  deriveDescription,
+  makePreview,
+  sha1Id,
+} from '../utils.mjs';
+
+/**
+ * Scan custom directory paths for SKILL.md files.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.paths - base dirs to scan (with ~ expansion)
+ * @param {string[]} [opts.globs] - optional glob patterns (default: glob matching SKILL.md)
+ * @param {object} [opts.limits] - { maxFiles, maxFileBytes }
+ * @returns {Promise}
+ */
+export async function scanDirectorySkills(opts) {
+  const {
+    paths = [],
+    globs = ['**/SKILL.md'],
+    limits = { maxFiles: 5000, maxFileBytes: 1024 * 1024 },
+  } = opts;
+
+  if (!paths || !paths.length) {
+    return { items: [], stats: { source: 'directory', available: false, files: 0 } };
+  }
+
+  const expanded = await expandRoots(paths);
+  if (!expanded.length) {
+    return { items: [], stats: { source: 'directory', available: false, files: 0 } };
+  }
+
+  // Collect file paths from all directories and globs
+  const files = [];
+  for (const root of expanded) {
+    for (const globPattern of globs) {
+      const found = await fg(globPattern, {
+        cwd: root,
+        absolute: true,
+        onlyFiles: true,
+        dot: true,
+        followSymbolicLinks: true,
+        deep: 10,
+        ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+      });
+
+      for (const f of found) {
+        // Avoid duplicates
+        if (!files.some(file => file.abs === f)) {
+          files.push({ abs: f, root });
+        }
+        if (files.length >= limits.maxFiles) break;
+      }
+      if (files.length >= limits.maxFiles) break;
+    }
+    if (files.length >= limits.maxFiles) break;
+  }
+
+  // Parse each SKILL.md file
+  const items = files.map(({ abs, root }) =>
+    parseDirectorySkill({ abs, root, limits })
+  );
+
+  return {
+    items,
+    stats: {
+      source: 'directory',
+      available: true,
+      files: items.length,
+      roots: expanded,
+    },
+  };
+}
+
+/**
+ * Parse a single SKILL.md file from a custom directory.
+ */
+function parseDirectorySkill({ abs, root, limits }) {
+  const { text, truncated, mtime, error } = readFileSafe(abs, limits.maxFileBytes);
+  const id = sha1Id(abs);
+  const rel = path.relative(root, abs);
+
+  // Directory name: the parent directory of SKILL.md
+  // e.g. ~/Project/skills/auth-flow/SKILL.md → dirName = 'auth-flow'
+  const dirName = path.basename(path.dirname(abs));
+
+  // Category from path: if the structure is /root/category/skill-name/SKILL.md,
+  // extract category from the first level above root.
+  const relDir = path.dirname(rel);
+  const category = relDir && relDir !== '.' ? relDir.split('/')[0] : undefined;
+
+  if (error) {
+    return baseDirectoryItem({
+      abs,
+      id,
+      dirName,
+      category,
+      mtime,
+      raw: '',
+      parseError: error,
+    });
+  }
+
+  if (truncated) {
+    return baseDirectoryItem({
+      abs,
+      id,
+      dirName,
+      category,
+      mtime,
+      raw: '',
+      parseError: `file > ${limits.maxFileBytes} bytes, skipped`,
+    });
+  }
+
+  const { data: fm, body, parseError } = parseFrontmatter(text);
+
+  const name = (fm.name || dirName).toString().trim();
+  const title = (fm.title || fm.name || dirName).toString().trim();
+  const description = deriveDescription(fm, body);
+
+  const triggers = collectTriggers(fm);
+  const tags = collectTags(fm);
+  const links = collectLinks(fm);
+
+  const item = {
+    id,
+    kind: 'skill',
+    source: 'directory',
+    editor: 'Custom Skills',
+    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(),
+    // Tier 2: Directory-based skills
+    tier: 'directory',
+    dirName,
+  };
+
+  // Brand inference from content
+  item.brand = inferBrand({
+    name: item.name,
+    description: item.description,
+    category: item.category,
+    raw: body,
+  });
+
+  if (parseError) item.parseError = parseError;
+  return item;
+}
+
+function baseDirectoryItem({ abs, id, dirName, category, mtime, raw, parseError }) {
+  return {
+    id,
+    kind: 'skill',
+    source: 'directory',
+    editor: 'Custom Skills',
+    name: dirName,
+    description: undefined,
+    category,
+    paths: {
+      abs,
+      rootKind: classifyRoot(abs),
+    },
+    preview: '',
+    raw,
+    updatedAt: new Date(mtime).toISOString(),
+    tier: 'directory',
+    dirName,
+    parseError,
+  };
+}
+
+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') {
+      out.push(c.trim());
+    }
+  }
+  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/file-docs.mjs

@@ -0,0 +1,158 @@
+// Generic Markdown file adapter for Codex AGENTS.md, Cursor rules, and project runbooks.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import {
+  classifyRoot,
+  deriveDescription,
+  expandRoots,
+  expandTilde,
+  inferBrand,
+  inferProduct,
+  makePreview,
+  parseFrontmatter,
+  readFileSafe,
+  sha1Id,
+} from '../utils.mjs';
+
+export async function scanFileDocs(opts) {
+  const {
+    source,
+    editor,
+    kind = 'doc',
+    files = [],
+    roots = [],
+    globs = [],
+    limits = { maxFiles: 5000, maxFileBytes: 1024 * 1024 },
+  } = opts;
+
+  const discovered = [];
+  for (const f of files || []) {
+    const abs = path.resolve(expandTilde(f));
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) discovered.push({ abs, root: path.dirname(abs) });
+  }
+
+  const expandedRoots = await expandRoots(roots || []);
+  const patterns = globs?.length ? globs : [];
+  for (const root of expandedRoots) {
+    for (const pattern of patterns) {
+      const found = await fg(pattern, {
+        cwd: root,
+        absolute: true,
+        onlyFiles: true,
+        dot: true,
+        followSymbolicLinks: false,
+        deep: 8,
+        ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/.venv/**', '**/vendor_imports/**'],
+      });
+      for (const abs of found) {
+        discovered.push({ abs, root });
+        if (discovered.length >= limits.maxFiles) break;
+      }
+      if (discovered.length >= limits.maxFiles) break;
+    }
+    if (discovered.length >= limits.maxFiles) break;
+  }
+
+  const byAbs = new Map();
+  for (const x of discovered) if (!byAbs.has(x.abs)) byAbs.set(x.abs, x);
+  const items = [...byAbs.values()].map(x => parseDoc({ ...x, source, editor, kind, limits }));
+  return { items, stats: { source, available: true, files: items.length, roots: expandedRoots } };
+}
+
+function parseDoc({ abs, root, source, editor, kind, limits }) {
+  const { text, truncated, mtime, error } = readFileSafe(abs, limits.maxFileBytes);
+  const rel = path.relative(root, abs);
+  const id = sha1Id(abs);
+  const base = path.basename(abs);
+  const project = inferProjectName(abs, root);
+  const name = inferName(abs, base, project);
+  const category = inferCategory(abs, root, base);
+
+  if (error || truncated) {
+    return {
+      id,
+      kind,
+      source,
+      editor,
+      name,
+      description: error || `file > ${limits.maxFileBytes} bytes, skipped`,
+      category,
+      product: project || inferProduct({ name, category }),
+      paths: { abs, rel, rootKind: classifyRoot(abs) },
+      preview: '',
+      raw: '',
+      updatedAt: new Date(mtime).toISOString(),
+      parseError: error || 'file too large',
+    };
+  }
+
+  const { data: fm, body, parseError } = parseFrontmatter(text);
+  const title = (fm.title || fm.name || name).toString().trim();
+  const description = deriveDescription(fm, body);
+  const item = {
+    id,
+    kind,
+    source,
+    editor,
+    name: title,
+    description,
+    category,
+    product: project || inferProduct({ name: title, category }),
+    tags: collectTags(fm),
+    triggers: collectTriggers(fm),
+    paths: { abs, rel, rootKind: classifyRoot(abs) },
+    preview: makePreview(body || text),
+    raw: text,
+    updatedAt: new Date(mtime).toISOString(),
+  };
+  item.brand = inferBrand({ name: item.name, description: item.description, category: item.category, raw: body });
+  if (!item.tags?.length) delete item.tags;
+  if (!item.triggers?.length) delete item.triggers;
+  if (parseError) item.parseError = parseError;
+  return item;
+}
+
+function inferProjectName(abs, root) {
+  const homeProject = `${process.env.HOME}/Project/`;
+  if (abs.startsWith(homeProject)) return abs.slice(homeProject.length).split('/')[0];
+  const parts = root.split('/').filter(Boolean);
+  return parts.at(-1);
+}
+
+function inferName(abs, base, project) {
+  if (base === 'AGENTS.md') return `${project || 'project'} / AGENTS.md`;
+  if (base === 'CLAUDE.md') return `${project || 'project'} / CLAUDE.md`;
+  if (base === '.cursorrules') return `${project || 'project'} / .cursorrules`;
+  if (base.startsWith('RUNBOOK-')) return base.replace(/\.md$/i, '');
+  return base.replace(/\.mdc?$/i, '');
+}
+
+function inferCategory(abs, root, base) {
+  if (base === 'AGENTS.md') return 'codex';
+  if (base === 'CLAUDE.md') return 'claude-code';
+  if (base === '.cursorrules' || abs.includes('/.cursor/rules/')) return 'cursor';
+  if (base.startsWith('RUNBOOK-')) return 'runbook';
+  const relDir = path.dirname(path.relative(root, abs));
+  if (!relDir || relDir === '.') return 'project';
+  return relDir.split('/')[0];
+}
+
+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 collectTriggers(fm) {
+  const out = [];
+  for (const v of [fm.triggers, fm.aliases, fm.when_to_use]) {
+    if (!v) continue;
+    if (Array.isArray(v)) out.push(...v.filter(x => typeof x === 'string').map(x => x.trim()));
+    else if (typeof v === 'string') out.push(v.trim());
+  }
+  return [...new Set(out)];
+}

package/packages/scanner/src/adapters/hermes-plugin.mjs

@@ -0,0 +1,149 @@
+// Hermes plugin adapter — catalogs local plugin manifests and READMEs.
+// It never imports or executes plugin code.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+import YAML from 'yaml';
+import {
+  classifyRoot,
+  deriveDescription,
+  expandRoots,
+  inferBrand,
+  inferProduct,
+  makePreview,
+  readFileSafe,
+  sha1Id,
+} from '../utils.mjs';
+
+const MANIFEST_NAMES = ['plugin.yaml', 'plugin.yml', 'plugin.json', 'manifest.json', 'package.json'];
+const README_NAMES = ['README.md', 'readme.md'];
+
+export async function scanHermesPlugins(opts) {
+  const {
+    source = 'hermes-plugin',
+    editor = 'Hermes Agent',
+    roots = [],
+    limits = { maxFiles: 5000, maxFileBytes: 1024 * 1024 },
+  } = opts;
+
+  const expanded = await expandRoots(roots || []);
+  const pluginDirs = new Set();
+  for (const root of expanded) {
+    if (!fs.existsSync(root)) continue;
+    const found = await fg(['*/plugin.{yaml,yml,json}', '*/manifest.json', '*/package.json', '*/README.md', '*/readme.md'], {
+      cwd: root,
+      absolute: true,
+      onlyFiles: true,
+      dot: true,
+      followSymbolicLinks: false,
+      deep: 2,
+      ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
+    });
+    for (const f of found) pluginDirs.add(path.dirname(f));
+  }
+
+  const items = [];
+  for (const dir of pluginDirs) {
+    items.push(parsePluginDir({ dir, source, editor, limits }));
+    if (items.length >= limits.maxFiles) break;
+  }
+  return { items, stats: { source, available: true, files: items.length, roots: expanded } };
+}
+
+function parsePluginDir({ dir, source, editor, limits }) {
+  const manifestPath = firstExisting(dir, MANIFEST_NAMES);
+  const readmePath = firstExisting(dir, README_NAMES);
+  const rawParts = [];
+  let manifest = {};
+  let parseError;
+  let mtime = new Date(0);
+
+  if (manifestPath) {
+    const r = readFileSafe(manifestPath, limits.maxFileBytes);
+    mtime = r.mtime || mtime;
+    if (!r.error && !r.truncated) {
+      rawParts.push(`# ${path.basename(manifestPath)}\n\n${r.text}`);
+      const parsed = parseManifest(manifestPath, r.text);
+      if (parsed.ok) manifest = parsed.value;
+      else parseError = parsed.error;
+    } else {
+      parseError = r.error || 'manifest too large';
+    }
+  }
+
+  let readmeBody = '';
+  if (readmePath) {
+    const r = readFileSafe(readmePath, limits.maxFileBytes);
+    if (r.mtime > mtime) mtime = r.mtime;
+    if (!r.error && !r.truncated) {
+      readmeBody = r.text;
+      rawParts.push(`# ${path.basename(readmePath)}\n\n${r.text}`);
+    }
+  }
+
+  const dirName = path.basename(dir);
+  const name = String(manifest.name || manifest.title || dirName).trim();
+  const description = typeof manifest.description === 'string'
+    ? manifest.description.trim()
+    : deriveDescription({}, readmeBody || rawParts.join('\n\n'));
+  const raw = rawParts.join('\n\n---\n\n');
+  const item = {
+    id: sha1Id(dir),
+    kind: 'plugin',
+    source,
+    editor,
+    name,
+    title: manifest.title && manifest.title !== name ? manifest.title : undefined,
+    description,
+    category: 'plugin',
+    product: inferProduct({ name, category: 'plugin' }),
+    tags: collectTags(manifest),
+    paths: { abs: dir, rel: dirName, rootKind: classifyRoot(dir) },
+    preview: makePreview(raw || description || '', 600),
+    raw,
+    links: collectLinks(manifest),
+    updatedAt: new Date(mtime).toISOString(),
+  };
+  item.brand = inferBrand({ name: item.name, description: item.description, category: item.category, raw });
+  if (!item.tags?.length) delete item.tags;
+  if (!item.links?.length) delete item.links;
+  if (parseError) item.parseError = parseError;
+  return item;
+}
+
+function firstExisting(dir, names) {
+  for (const name of names) {
+    const f = path.join(dir, name);
+    if (fs.existsSync(f) && fs.statSync(f).isFile()) return f;
+  }
+  return undefined;
+}
+
+function parseManifest(abs, text) {
+  try {
+    if (/\.json$/i.test(abs)) return { ok: true, value: JSON.parse(text) || {} };
+    return { ok: true, value: YAML.parse(text) || {} };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function collectTags(obj) {
+  const candidates = [obj.tags, obj.keywords, obj.categories];
+  const out = [];
+  for (const v of candidates) {
+    if (Array.isArray(v)) out.push(...v.filter(x => typeof x === 'string'));
+    else if (typeof v === 'string') out.push(...v.split(',').map(x => x.trim()).filter(Boolean));
+  }
+  return [...new Set(out)];
+}
+
+function collectLinks(obj) {
+  const out = [];
+  for (const [label, value] of Object.entries({ homepage: obj.homepage, repository: obj.repository, url: obj.url })) {
+    if (typeof value === 'string') out.push({ label, url: value });
+    else if (value && typeof value.url === 'string') out.push({ label, url: value.url });
+  }
+  return out;
+}