huhaa-myskills 0.1.5

package/service/bin/huhaa-myskills.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// huhaa-myskills CLI
+//
+// Subcommands:
+//   start   — scan + start server + open browser
+//   scan    — scan only, dump IR JSON to stdout
+//   init    — write default sources.yaml to ~/.config/huhaa-myskills/
+//   purge   — delete ~/.config/huhaa-myskills/ (zero-residue uninstall helper)
+//   dev     — dev mode (P3+ wires Vite + nodemon)
+//
+// All user-side state lives under HUHAA_HOME (defaults to ~/.config/huhaa-myskills).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+import {
+  homeDir,
+  configFile,
+  cacheFile,
+  stateFile,
+  ensureHomeDir,
+  writeJson,
+} from './lib/paths.mjs';
+import { pickPort } from './lib/port.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// bin/ -> service/ -> repo root
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SERVICE_ROOT = path.resolve(__dirname, '..');
+
+const cmd = process.argv[2] || 'start';
+
+const handlers = {
+  start: cmdStart,
+  scan: cmdScan,
+  stats: cmdStats,
+  duplicates: cmdDuplicates,
+  init: cmdInit,
+  purge: cmdPurge,
+  dev: cmdDev,
+  help: cmdHelp,
+  '--help': cmdHelp,
+  '-h': cmdHelp,
+};
+
+const fn = handlers[cmd] || cmdHelp;
+fn().catch(err => {
+  console.error('[huhaa-myskills] error:', err && err.stack || err);
+  process.exit(1);
+});
+
+// ---------------- handlers ----------------
+
+async function cmdHelp() {
+  console.log(`huhaa-myskills — local skill / plugin / MCP aggregation hub
+
+Usage:
+  huhaa-myskills <command>
+
+Commands:
+  start     Scan + start server + open browser (default)
+  scan      Scan only, dump IR JSON to stdout
+  stats     Scan + print human-readable summary (counts / brands / errors / samples)
+  duplicates Scan + print duplicate diagnostics by name/content/path
+  init      Write default sources.yaml to ~/.config/huhaa-myskills/
+  purge     Remove all user data under ~/.config/huhaa-myskills/
+  dev       Dev mode (Vite + nodemon)
+  help      Show this message
+
+Env:
+  HUHAA_HOME      override user data dir (default: ~/.config/huhaa-myskills)
+  PORT            override preferred port (default: 11520, falls back +10)
+
+Paths:
+  config   ${configFile()}
+  cache    ${cacheFile()}
+  state    ${stateFile()}
+`);
+}
+
+async function cmdInit() {
+  ensureHomeDir();
+  const dst = configFile();
+  if (fs.existsSync(dst)) {
+    console.log(`[init] sources.yaml already exists: ${dst}`);
+    console.log('[init] not overwriting. delete it first if you want to reset.');
+    return;
+  }
+  const tpl = path.join(SERVICE_ROOT, 'config', 'sources.example.yaml');
+  fs.copyFileSync(tpl, dst);
+  console.log(`[init] wrote ${dst}`);
+  console.log('[init] edit it to add / remove sources, then run: huhaa-myskills start');
+}
+
+async function cmdPurge() {
+  const dir = homeDir();
+  if (!fs.existsSync(dir)) {
+    console.log(`[purge] nothing to remove — ${dir} does not exist`);
+    return;
+  }
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log(`[purge] removed ${dir}`);
+  console.log('[purge] code dir is untouched. delete the repo manually if needed.');
+}
+
+async function cmdScan() {
+  // P0 placeholder. P1 wires real adapters.
+  const { scan } = await import('@huhaa/scanner');
+  await ensureConfigOrInit();
+  const items = await scan();
+  process.stdout.write(JSON.stringify(items, null, 2) + '\n');
+  console.error(`[scan] ${items.length} item(s)`);
+}
+
+async function cmdStats() {
+  const { scan } = await import('@huhaa/scanner');
+  await ensureConfigOrInit();
+  const items = await scan();
+
+  const bySource = {};
+  const byEditor = {};
+  const byCategory = {};
+  const byBrand = {};
+  const byKind = {};
+  const errors = [];
+  const noDescription = [];
+  const noTriggers = [];
+
+  for (const it of items) {
+    bySource[it.source] = (bySource[it.source] || 0) + 1;
+    const editor = it.editor || it.source || '(none)';
+    byEditor[editor] = (byEditor[editor] || 0) + 1;
+    byKind[it.kind] = (byKind[it.kind] || 0) + 1;
+    const cat = it.category || '(none)';
+    byCategory[cat] = (byCategory[cat] || 0) + 1;
+    const brand = it.brand || '(none)';
+    byBrand[brand] = (byBrand[brand] || 0) + 1;
+    if (it.parseError) errors.push(it);
+    if (!it.description) noDescription.push(it);
+    if (!it.triggers || !it.triggers.length) noTriggers.push(it);
+  }
+
+  const sortDesc = (obj) => Object.entries(obj).sort((a, b) => b[1] - a[1]);
+
+  console.log(`\nHuHaa-MySkills scan stats`);
+  console.log(`==========================`);
+  console.log(`total items:        ${items.length}`);
+  console.log(`parse errors:       ${errors.length}`);
+  console.log(`missing description: ${noDescription.length}`);
+  console.log(`missing triggers:   ${noTriggers.length}`);
+
+  console.log(`\nby source:`);
+  for (const [k, v] of sortDesc(bySource)) console.log(`  ${k.padEnd(20)} ${v}`);
+
+  console.log(`\nby editor:`);
+  for (const [k, v] of sortDesc(byEditor)) console.log(`  ${k.padEnd(20)} ${v}`);
+
+  console.log(`\nby kind:`);
+  for (const [k, v] of sortDesc(byKind)) console.log(`  ${k.padEnd(20)} ${v}`);
+
+  console.log(`\nby category (top 15):`);
+  for (const [k, v] of sortDesc(byCategory).slice(0, 15)) {
+    console.log(`  ${k.padEnd(30)} ${v}`);
+  }
+
+  console.log(`\nby brand (top 15):`);
+  for (const [k, v] of sortDesc(byBrand).slice(0, 15)) {
+    console.log(`  ${k.padEnd(20)} ${v}`);
+  }
+
+  if (errors.length) {
+    console.log(`\nparse errors (first 5):`);
+    for (const e of errors.slice(0, 5)) {
+      console.log(`  - [${e.source}] ${e.name}: ${e.parseError}`);
+      console.log(`      ${e.paths.abs}`);
+    }
+  }
+
+  // deterministic-ish sample: every Nth item so coverage spans both sources
+  const sampleN = Math.min(8, items.length);
+  if (sampleN > 0) {
+    const step = Math.max(1, Math.floor(items.length / sampleN));
+    console.log(`\nsample (every ${step}-th item, ${sampleN} shown):`);
+    for (let i = 0; i < sampleN; i++) {
+      const it = items[i * step];
+      if (!it) break;
+      const desc = (it.description || '(no description)').slice(0, 70);
+      const trigCount = (it.triggers || []).length;
+      console.log(
+        `  [${it.source.padEnd(11)}] ${(it.category || '-').padEnd(20)} ` +
+        `${it.name.padEnd(38)} brand=${(it.brand || '-').padEnd(14)} t=${trigCount}`
+      );
+      console.log(`      ${desc}`);
+    }
+  }
+
+  console.log('');
+}
+
+async function cmdDuplicates() {
+  const { scan } = await import('@huhaa/scanner');
+  await ensureConfigOrInit();
+  const items = await scan();
+  const byName = groupBy(items, it => `${it.source}:${it.name}`);
+  const byContent = groupBy(items, it => `${it.source}:${hashShort(it.raw || it.preview || '')}`);
+  const byAbs = groupBy(items, it => it.paths?.abs || '');
+
+  const nameDups = [...byName.entries()].filter(([, arr]) => arr.length > 1);
+  const contentDups = [...byContent.entries()].filter(([k, arr]) => !k.endsWith(':00000000') && arr.length > 1);
+  const pathDups = [...byAbs.entries()].filter(([k, arr]) => k && arr.length > 1);
+
+  console.log('\nHuHaa-MySkills duplicate diagnostics');
+  console.log('====================================');
+  console.log(`total items:          ${items.length}`);
+  console.log(`duplicate names:      ${nameDups.length} groups`);
+  console.log(`duplicate contents:   ${contentDups.length} groups`);
+  console.log(`duplicate abs paths:  ${pathDups.length} groups`);
+
+  printDupGroup('duplicate names (first 20)', nameDups, 20);
+  printDupGroup('duplicate contents (first 20)', contentDups, 20);
+  printDupGroup('duplicate paths (first 20)', pathDups, 20);
+  console.log('');
+}
+
+function groupBy(items, keyFn) {
+  const m = new Map();
+  for (const it of items) {
+    const k = keyFn(it);
+    if (!m.has(k)) m.set(k, []);
+    m.get(k).push(it);
+  }
+  return m;
+}
+
+function hashShort(text) {
+  let h = 0;
+  for (let i = 0; i < text.length; i++) h = Math.imul(31, h) + text.charCodeAt(i) | 0;
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+function printDupGroup(title, groups, limit) {
+  if (!groups.length) return;
+  console.log(`\n${title}:`);
+  for (const [key, arr] of groups.slice(0, limit)) {
+    console.log(`- ${key} (${arr.length})`);
+    for (const it of arr.slice(0, 6)) {
+      console.log(`    [${it.source}] ${it.name} :: ${it.paths?.abs}`);
+    }
+  }
+}
+
+async function cmdStart() {
+  await ensureConfigOrInit();
+  const preferred = parseInt(process.env.PORT || '11520', 10);
+  const port = await pickPort(preferred, 10);
+  if (!port) {
+    console.error(`[start] no free port in ${preferred}..${preferred + 10}, abort.`);
+    process.exit(1);
+  }
+  if (port !== preferred) {
+    console.error(`[start] port ${preferred} busy, using ${port} instead.`);
+  }
+
+  // Persist actual port for any tooling that wants to know.
+  writeJson(stateFile(), { port, pid: process.pid, startedAt: new Date().toISOString() });
+
+  const { startServer } = await import('@huhaa/server');
+  await startServer({ port });
+
+  console.log(`\n  HuHaa-MySkills running:  http://localhost:${port}\n`);
+  console.log(`  data dir: ${homeDir()}`);
+  console.log(`  Ctrl+C to stop.\n`);
+
+  // Auto-open browser on macOS / linux / win
+  openBrowser(`http://localhost:${port}`);
+
+  // Cleanup state file on exit so a stale port number doesn't linger.
+  const cleanup = () => {
+    try { fs.unlinkSync(stateFile()); } catch {}
+    process.exit(0);
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}
+
+async function cmdDev() {
+  // P3+ wires Vite + nodemon. For now alias to start.
+  console.log('[dev] dev mode comes in P3. running start for now.');
+  await cmdStart();
+}
+
+// ---------------- helpers ----------------
+
+async function ensureConfigOrInit() {
+  if (!fs.existsSync(configFile())) {
+    console.error(`[boot] no config yet, writing defaults to ${configFile()}`);
+    await cmdInit();
+  }
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  let cmd, args;
+  if (platform === 'darwin') { cmd = 'open'; args = [url]; }
+  else if (platform === 'win32') { cmd = 'cmd'; args = ['/c', 'start', '', url]; }
+  else { cmd = 'xdg-open'; args = [url]; }
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    // best-effort; user can copy-paste the URL
+  }
+}

package/service/bin/lib/paths.mjs

@@ -0,0 +1,57 @@
+// XDG-style paths for huhaa-myskills.
+// All user-side state lives under HUHAA_HOME (default: ~/.config/huhaa-myskills).
+// Nothing is written outside this dir, so `purge` cleans everything.
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export function homeDir() {
+  if (process.env.HUHAA_HOME && process.env.HUHAA_HOME.trim()) {
+    return path.resolve(expandTilde(process.env.HUHAA_HOME));
+  }
+  // XDG_CONFIG_HOME respected if set, else ~/.config
+  const xdg = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim()
+    ? path.resolve(expandTilde(process.env.XDG_CONFIG_HOME))
+    : path.join(os.homedir(), '.config');
+  return path.join(xdg, 'huhaa-myskills');
+}
+
+export function configFile() {
+  return path.join(homeDir(), 'sources.yaml');
+}
+
+export function cacheFile() {
+  return path.join(homeDir(), 'cache.json');
+}
+
+export function stateFile() {
+  return path.join(homeDir(), 'state.json');
+}
+
+export function ensureHomeDir() {
+  const dir = homeDir();
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function expandTilde(p) {
+  if (!p) return p;
+  if (p === '~' || p.startsWith('~/')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+export function writeJson(file, obj) {
+  ensureHomeDir();
+  fs.writeFileSync(file, JSON.stringify(obj, null, 2));
+}
+
+export function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}

package/service/bin/lib/port.mjs

@@ -0,0 +1,23 @@
+// Pick a free port starting from `preferred`, walking up to `preferred + range`.
+// Returns the port that successfully bound (we then close immediately so the
+// real server can claim it). On any error or full exhaustion, returns null.
+
+import net from 'node:net';
+
+export async function pickPort(preferred = 11520, range = 10) {
+  for (let p = preferred; p <= preferred + range; p++) {
+    if (await isFree(p)) return p;
+  }
+  return null;
+}
+
+function isFree(port) {
+  return new Promise(resolve => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.once('error', () => resolve(false));
+    srv.listen({ port, host: '127.0.0.1' }, () => {
+      srv.close(() => resolve(true));
+    });
+  });
+}

package/service/config/sources.example.yaml

@@ -0,0 +1,121 @@
+# HuHaa-MySkills sources.yaml
+#
+# This file is copied to ~/.config/huhaa-myskills/sources.yaml by `npm run init`.
+# Paths support ~ expansion and simple glob expansion in roots.
+#
+# Environment overrides:
+# - HUHAA_HOME: user data directory
+# - PORT: preferred HTTP port
+#
+# Safety:
+# - adapters only read files; they do not execute tools or commands
+# - MCP configs are redacted before entering raw/preview
+# - copy/open API calls only operate on scanned item ids, not arbitrary paths
+
+sources:
+  hermes:
+    enabled: true
+    roots:
+      - ~/.hermes/skills
+      - ~/.hermes/profiles/*/skills
+
+  claude-code:
+    enabled: true
+    roots:
+      - ~/.claude/skills
+
+  codex:
+    enabled: true
+    files:
+      - ~/.codex/AGENTS.md
+    roots: []
+    globs:
+      - AGENTS.md
+
+  cursor:
+    enabled: true
+    files: []
+    roots:
+      - ~/.cursor
+    globs:
+      - rules/**/*.{md,mdc}
+      - .cursorrules
+
+  mcp-config:
+    enabled: true
+    files:
+      - ~/.cursor/mcp.json
+      - ~/.codex/config.toml
+      - ~/Library/Application Support/Claude/claude_desktop_config.json
+      - ~/.hermes/config.yaml
+
+  hermes-plugin:
+    enabled: true
+    roots:
+      - ~/.hermes/plugins
+      - ~/.hermes/profiles/*/plugins
+
+  project-runbook:
+    enabled: true
+    # Add your project roots here. The default scans ~/Project/*.
+    # Each root scans docs/RUNBOOK-*.md plus common AI-agent instruction files.
+    roots:
+      - ~/Project/*
+    globs:
+      - docs/RUNBOOK-*.md
+      - AGENTS.md
+      - CLAUDE.md
+      - .cursorrules
+      - .cursor/rules/**/*.{md,mdc}
+
+  skills:
+    enabled: true
+    roots:
+      - ~/skills
+      - ~/Skills
+    globs:
+      - '*.md'
+      - '*/SKILL.md'
+      - '**/SKILL.md'
+
+  mcp:
+    enabled: true
+    roots:
+      - ~/mcp
+      - ~/MCP
+    globs:
+      - '*.md'
+      - '*.json'
+      - '*.yaml'
+      - '*.yml'
+      - '**/manifest.*'
+
+  skill:
+    enabled: true
+    roots:
+      - ~/skill
+    globs:
+      - '*.md'
+      - '*/SKILL.md'
+      - '**/SKILL.md'
+
+  obsidian:
+    enabled: false
+    roots: []
+    tagFilter: '#skill'
+
+ui:
+  port: 11520
+  autoOpen: true
+  defaultEditor: cursor
+  groupBy: [editor, category, product]
+
+limits:
+  maxFiles: 5000
+  maxFileBytes: 1048576
+
+exclude:
+  - '**/node_modules/**'
+  - '**/.git/**'
+  - '**/dist/**'
+  - '**/.venv/**'

package/service/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)];
+}