AgentHub/server/lib/cc-discovery.js

/**
 * @file cc-discovery.js
 * @description Read-only discovery of Claude Code configuration surfaces
 * (skills, subagents, slash commands, output styles, plugins, marketplaces,
 * MCP servers, hooks, settings, memory, keybindings, statusline, hook
 * scripts). Powers the Claude Config Explorer page. All operations are pure
 * file reads — never writes.
 *
 * Path containment: every read resolves under getClaudeHome(),
 * getProjectClaudeDir(), or getProjectRoot() (for CLAUDE.md). Reads outside
 * those roots return null. Settings are redacted of secret-like keys before
 * returning.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
const fs = require("node:fs");
const path = require("node:path");
const os = require("node:os");
const { getClaudeHome } = require("./claude-home");

const MAX_FILE_BYTES = 256 * 1024; // skip reads above this; truncate body in details
const REDACT_KEY_RE = /token|secret|password|api[_-]?key|auth/i;

function getProjectRoot(cwd) {
  return path.resolve(cwd || process.cwd());
}

function getProjectClaudeDir(cwd) {
  return path.join(getProjectRoot(cwd), ".claude");
}

function getClaudeJsonPath() {
  // ~/.claude.json sits beside ~/.claude/, NOT inside it. Resolve from $HOME
  // so a CLAUDE_HOME override doesn't accidentally relocate it.
  return path.join(os.homedir(), ".claude.json");
}

/**
 * True if `target` is contained within `root` (after symlink-aware resolve).
 * Defends the /file endpoint against `..` traversal and absolute-path tricks.
 */
function isUnder(root, target) {
  const r = path.resolve(root);
  const t = path.resolve(target);
  if (t === r) return true;
  return t.startsWith(r + path.sep);
}

function readJson(absPath) {
  try {
    const raw = fs.readFileSync(absPath, "utf8");
    return { ok: true, data: JSON.parse(raw), raw };
  } catch (err) {
    if (err && err.code === "ENOENT") return { ok: false, missing: true };
    return { ok: false, error: err.message };
  }
}

function redactSettings(value) {
  if (Array.isArray(value)) return value.map(redactSettings);
  if (value && typeof value === "object") {
    const out = {};
    for (const [k, v] of Object.entries(value)) {
      if (typeof v === "string" && REDACT_KEY_RE.test(k)) {
        out[k] = "<redacted>";
      } else {
        out[k] = redactSettings(v);
      }
    }
    return out;
  }
  return value;
}

/**
 * Minimal YAML-frontmatter parser. Handles `---\n<key>: <value>\n---\n<body>`.
 * Quoted strings (single + double) are stripped; multi-line values are
 * preserved as raw strings. Anything we can't parse is returned as null
 * frontmatter — the body is still readable.
 */
function parseFrontmatter(text) {
  if (typeof text !== "string") return { frontmatter: null, body: "" };
  if (!text.startsWith("---")) return { frontmatter: null, body: text };
  const end = text.indexOf("\n---", 3);
  if (end < 0) return { frontmatter: null, body: text };
  const head = text.slice(3, end).replace(/^\s*\n/, "");
  const body = text.slice(end + 4).replace(/^\s*\n/, "");
  const fm = {};
  let currentKey = null;
  for (const rawLine of head.split("\n")) {
    const line = rawLine.replace(/\s+$/, "");
    if (!line.trim()) continue;
    // continuation of a multiline value
    if (currentKey && /^\s/.test(rawLine)) {
      fm[currentKey] += "\n" + rawLine.trim();
      continue;
    }
    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
    if (!m) {
      currentKey = null;
      continue;
    }
    currentKey = m[1];
    let v = m[2];
    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
      v = v.slice(1, -1);
    }
    fm[currentKey] = v;
  }
  return { frontmatter: fm, body };
}

function safeReadText(absPath) {
  try {
    const stat = fs.statSync(absPath);
    if (!stat.isFile()) return null;
    if (stat.size > MAX_FILE_BYTES) {
      return {
        truncated: true,
        size: stat.size,
        text: fs.readFileSync(absPath, "utf8").slice(0, MAX_FILE_BYTES),
        mtime: stat.mtimeMs,
      };
    }
    return {
      truncated: false,
      size: stat.size,
      text: fs.readFileSync(absPath, "utf8"),
      mtime: stat.mtimeMs,
    };
  } catch {
    return null;
  }
}

function listDir(absPath) {
  try {
    return fs.readdirSync(absPath, { withFileTypes: true });
  } catch {
    return [];
  }
}

/**
 * True if `ent` is a directory, OR a symlink that resolves to one.
 * Dirent.isDirectory() returns false for symlinks even when they point at a
 * directory (e.g. a skill installed via `ln -s` so it can live in a git
 * repo) — this follows the link with statSync so those aren't skipped.
 * Broken symlinks are treated as non-directories rather than throwing.
 */
function isDirLike(ent, absPath) {
  if (ent.isDirectory()) return true;
  if (!ent.isSymbolicLink()) return false;
  try {
    return fs.statSync(absPath).isDirectory();
  } catch {
    return false;
  }
}

/**
 * File counterpart of {@link isDirLike}: true if `ent` is a regular file, OR a
 * symlink that resolves to one. Same Dirent quirk — `ent.isFile()` returns
 * false for a symlink even when it points at a file, so agents/commands/hook
 * scripts installed via `ln -s` were invisible to the Config Explorer while
 * Claude Code itself resolves and uses them. Broken symlinks are treated as
 * non-files rather than throwing.
 */
function isFileLike(ent, absPath) {
  if (ent.isFile()) return true;
  if (!ent.isSymbolicLink()) return false;
  try {
    return fs.statSync(absPath).isFile();
  } catch {
    return false;
  }
}

// ── Skills ──────────────────────────────────────────────────────────────

function readSkillsAt(scope, claudeDir) {
  const dir = path.join(claudeDir, "skills");
  const entries = listDir(dir);
  const skills = [];
  for (const ent of entries) {
    const skillDir = path.join(dir, ent.name);
    if (!isDirLike(ent, skillDir)) continue;
    const skillFile = path.join(skillDir, "SKILL.md");
    const read = safeReadText(skillFile);
    if (!read) continue;
    const { frontmatter, body } = parseFrontmatter(read.text);
    skills.push({
      scope,
      name: ent.name,
      path: skillDir,
      file: skillFile,
      size: read.size,
      mtime: read.mtime,
      truncated: read.truncated,
      frontmatter: frontmatter || {},
      preview: body.slice(0, 320),
    });
  }
  return skills.sort((a, b) => a.name.localeCompare(b.name));
}

function readSkills(opts = {}) {
  const out = [];
  if (opts.scope !== "project") {
    out.push(...readSkillsAt("user", getClaudeHome()));
  }
  if (opts.scope !== "user") {
    out.push(...readSkillsAt("project", getProjectClaudeDir(opts.cwd)));
  }
  return out;
}

// ── Single-file MD surfaces (agents, commands, output styles) ──────────

function readMdFilesAt(scope, claudeDir, subdir) {
  const dir = path.join(claudeDir, subdir);
  const entries = listDir(dir);
  const out = [];
  for (const ent of entries) {
    if (!ent.name.endsWith(".md")) continue;
    const file = path.join(dir, ent.name);
    if (!isFileLike(ent, file)) continue;
    const read = safeReadText(file);
    if (!read) continue;
    const { frontmatter, body } = parseFrontmatter(read.text);
    out.push({
      scope,
      name: ent.name.replace(/\.md$/, ""),
      file,
      size: read.size,
      mtime: read.mtime,
      truncated: read.truncated,
      frontmatter: frontmatter || {},
      preview: body.slice(0, 320),
    });
  }
  return out.sort((a, b) => a.name.localeCompare(b.name));
}

function readSimpleMdSurface(subdir) {
  return (opts = {}) => {
    const out = [];
    if (opts.scope !== "project") {
      out.push(...readMdFilesAt("user", getClaudeHome(), subdir));
    }
    if (opts.scope !== "user") {
      out.push(...readMdFilesAt("project", getProjectClaudeDir(opts.cwd), subdir));
    }
    return out;
  };
}

const readAgents = readSimpleMdSurface("agents");
const readCommands = readSimpleMdSurface("commands");
const readOutputStyles = readSimpleMdSurface("output-styles");

// ── Plugins ─────────────────────────────────────────────────────────────

/**
 * Absolute `.md` files a plugin contributes for one surface: the conventional
 * `<root>/<subdir>` directory PLUS whatever `plugin.json` points at for that
 * key. Both matter — a manifest entry may be a single file or a directory, and
 * a plugin that declares its commands explicitly (this repo's own `ccam` lists
 * three files under `./plugins/ccam/commands/`) keeps NOTHING in `commands/`,
 * so reading only the conventional directory reported zero for it.
 *
 * A manifest is data from a third-party plugin, so a declared path that escapes
 * the plugin's own install directory is dropped rather than read.
 *
 * @param {string} installPath Plugin root.
 * @param {string} subdir Conventional directory name ("agents", "commands", …).
 * @param {unknown} declared The manifest value for that key, any shape.
 * @returns {string[]} Sorted, de-duplicated absolute file paths.
 */
function pluginSurfaceFiles(installPath, subdir, declared) {
  const files = new Set();
  const addDir = (dir) => {
    for (const ent of listDir(dir)) {
      const abs = path.join(dir, ent.name);
      if (ent.name.endsWith(".md") && isFileLike(ent, abs)) files.add(abs);
    }
  };
  addDir(path.join(installPath, subdir));
  const entries = Array.isArray(declared)
    ? declared
    : typeof declared === "string"
      ? [declared]
      : [];
  for (const rel of entries) {
    if (typeof rel !== "string") continue;
    const abs = path.resolve(installPath, rel);
    if (!isUnder(installPath, abs)) continue;
    try {
      const stat = fs.statSync(abs);
      if (stat.isDirectory()) addDir(abs);
      else if (stat.isFile() && abs.endsWith(".md")) files.add(abs);
    } catch {
      /* declared in the manifest but not on disk — reported by its absence */
    }
  }
  return [...files].sort();
}

/**
 * One surface's items with the names the UI shows. `name` prefers the
 * frontmatter's own name (that is what Claude Code addresses the agent/command
 * by) and falls back to the filename.
 *
 * @returns {{name: string, description: string|null, file: string}[]}
 */
function readPluginMdSurface(installPath, subdir, declared) {
  const out = [];
  for (const file of pluginSurfaceFiles(installPath, subdir, declared)) {
    const read = safeReadText(file);
    const fm = read ? parseFrontmatter(read.text).frontmatter : null;
    out.push({
      name: fm && typeof fm.name === "string" && fm.name ? fm.name : path.basename(file, ".md"),
      description: fm && typeof fm.description === "string" ? fm.description : null,
      file,
    });
  }
  return out.sort((a, b) => a.name.localeCompare(b.name));
}

/**
 * A plugin's skills: every directory holding a `SKILL.md`, under the
 * conventional `<root>/skills` and under any directory the manifest declares.
 * A declared path that IS a skill directory counts as that one skill.
 *
 * @returns {{name: string, description: string|null, file: string}[]}
 */
function readPluginSkills(installPath, declared) {
  const found = new Map();
  const addSkillDir = (dir) => {
    const file = path.join(dir, "SKILL.md");
    const read = safeReadText(file);
    if (!read) return false;
    const fm = parseFrontmatter(read.text).frontmatter;
    found.set(dir, {
      name: fm && typeof fm.name === "string" && fm.name ? fm.name : path.basename(dir),
      description: fm && typeof fm.description === "string" ? fm.description : null,
      file,
    });
    return true;
  };
  const addRoot = (root) => {
    for (const ent of listDir(root)) {
      const dir = path.join(root, ent.name);
      if (isDirLike(ent, dir)) addSkillDir(dir);
    }
  };
  addRoot(path.join(installPath, "skills"));
  const entries = Array.isArray(declared)
    ? declared
    : typeof declared === "string"
      ? [declared]
      : [];
  for (const rel of entries) {
    if (typeof rel !== "string") continue;
    const abs = path.resolve(installPath, rel);
    if (!isUnder(installPath, abs)) continue;
    // Either the path is one skill, or it is a directory holding several.
    if (!addSkillDir(abs)) addRoot(abs);
  }
  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
}

/**
 * What one installed plugin contributes. The `skills`/`agents`/`commands`/
 * `outputStyles` counts are unchanged (existing clients read them), and `items`
 * carries the same three surfaces by name so a card can list WHICH ones a
 * plugin ships instead of only how many.
 */
function readPluginContributions(installPath) {
  if (!installPath) return null;
  let pluginJson = null;
  try {
    const raw = fs.readFileSync(path.join(installPath, ".claude-plugin", "plugin.json"), "utf8");
    pluginJson = JSON.parse(raw);
  } catch {
    pluginJson = null;
  }
  const items = {
    skills: readPluginSkills(installPath, pluginJson?.skills),
    agents: readPluginMdSurface(installPath, "agents", pluginJson?.agents),
    commands: readPluginMdSurface(installPath, "commands", pluginJson?.commands),
    outputStyles: readPluginMdSurface(installPath, "output-styles", pluginJson?.outputStyles),
  };
  return {
    // Counts stay derived from the same lists, so a plugin can never show a
    // chip reading "3 commands" next to a list holding two.
    skills: items.skills.length,
    agents: items.agents.length,
    commands: items.commands.length,
    outputStyles: items.outputStyles.length,
    items,
    hooks: (() => {
      try {
        return fs
          .readdirSync(path.join(installPath, "hooks"), { withFileTypes: true })
          .filter((e) => isFileLike(e, path.join(installPath, "hooks", e.name))).length;
      } catch {
        return 0;
      }
    })(),
    pluginJson,
  };
}

function readEnabledPluginsMap() {
  const userSettings = readJson(path.join(getClaudeHome(), "settings.json"));
  if (!userSettings.ok || !userSettings.data) return {};
  const ep = userSettings.data.enabledPlugins;
  return ep && typeof ep === "object" ? ep : {};
}

function readPlugins() {
  const home = getClaudeHome();
  const manifestPath = path.join(home, "plugins", "installed_plugins.json");
  const manifest = readJson(manifestPath);
  const enabledMap = readEnabledPluginsMap();
  const plugins = [];
  if (manifest.ok && manifest.data && manifest.data.plugins) {
    for (const [pluginKey, instances] of Object.entries(manifest.data.plugins)) {
      const arr = Array.isArray(instances) ? instances : [instances];
      for (const inst of arr) {
        const installPath = inst.installPath;
        let exists = false;
        try {
          exists = installPath ? fs.statSync(installPath).isDirectory() : false;
        } catch {
          exists = false;
        }
        const contributes = exists ? readPluginContributions(installPath) : null;
        // enabledPlugins map keys can be just the plugin name OR "<name>@<marketplace>"
        const enabledByKey = enabledMap[pluginKey];
        const enabledByName = enabledMap[pluginKey.split("@")[0]];
        const enabled =
          enabledByKey === true || enabledByName === true
            ? true
            : enabledByKey === false || enabledByName === false
              ? false
              : null;
        plugins.push({
          key: pluginKey,
          name: pluginKey.split("@")[0],
          marketplace: pluginKey.includes("@") ? pluginKey.split("@")[1] : null,
          scope: inst.scope || "user",
          version: inst.version || null,
          installPath: installPath || null,
          installedAt: inst.installedAt || null,
          lastUpdated: inst.lastUpdated || null,
          gitCommitSha: inst.gitCommitSha || null,
          installPathExists: exists,
          enabled,
          contributes,
        });
      }
    }
  }
  return {
    manifestPath,
    manifestExists: manifest.ok,
    plugins: plugins.sort((a, b) => a.key.localeCompare(b.key)),
  };
}

// ── MCP servers ────────────────────────────────────────────────────────

function readMcpServers(opts = {}) {
  const out = { user: [], projectScoped: [] };
  // ~/.claude.json is the primary CLI state file; mcpServers can live at the
  // top level (legacy) or inside projects[<cwd>].mcpServers (per-project).
  const claudeJson = readJson(getClaudeJsonPath());
  if (claudeJson.ok && claudeJson.data) {
    const top = claudeJson.data.mcpServers;
    if (top && typeof top === "object") {
      for (const [name, def] of Object.entries(top)) {
        out.user.push({
          name,
          source: "~/.claude.json (top-level)",
          ...summarizeMcpDef(def),
        });
      }
    }
    const projects = claudeJson.data.projects;
    if (projects && typeof projects === "object") {
      const projectRoot = getProjectRoot(opts.cwd);
      const projectEntry = projects[projectRoot];
      if (projectEntry && projectEntry.mcpServers) {
        for (const [name, def] of Object.entries(projectEntry.mcpServers)) {
          out.projectScoped.push({
            name,
            source: `~/.claude.json (projects[${projectRoot}])`,
            ...summarizeMcpDef(def),
          });
        }
      }
    }
  }
  // Also sniff settings.json for an mcpServers key (rare but supported).
  const userSettings = readJson(path.join(getClaudeHome(), "settings.json"));
  if (userSettings.ok && userSettings.data && userSettings.data.mcpServers) {
    for (const [name, def] of Object.entries(userSettings.data.mcpServers)) {
      out.user.push({
        name,
        source: "~/.claude/settings.json",
        ...summarizeMcpDef(def),
      });
    }
  }
  return out;
}

function summarizeMcpDef(def) {
  if (!def || typeof def !== "object") return { kind: "unknown" };
  if (def.url)
    return { kind: "http", url: def.url, headers: def.headers ? Object.keys(def.headers) : [] };
  if (def.command) {
    return {
      kind: "stdio",
      command: def.command,
      args: Array.isArray(def.args) ? def.args : [],
      envNames: def.env && typeof def.env === "object" ? Object.keys(def.env) : [],
    };
  }
  return { kind: "unknown" };
}

// ── Hooks (read across user + project + project-local) ─────────────────

const HOOK_EVENT_TYPES = [
  "SessionStart",
  "SessionEnd",
  "UserPromptSubmit",
  "PreToolUse",
  "PostToolUse",
  "Stop",
  "SubagentStop",
  "Notification",
  "PreCompact",
];

function readHooks(opts = {}) {
  const sources = [
    { scope: "user", file: path.join(getClaudeHome(), "settings.json") },
    {
      scope: "project",
      file: path.join(getProjectClaudeDir(opts.cwd), "settings.json"),
    },
    {
      scope: "project-local",
      file: path.join(getProjectClaudeDir(opts.cwd), "settings.local.json"),
    },
  ];
  const result = [];
  for (const { scope, file } of sources) {
    const j = readJson(file);
    const entry = { scope, file, exists: j.ok, hooks: {} };
    if (j.ok && j.data && j.data.hooks && typeof j.data.hooks === "object") {
      for (const event of HOOK_EVENT_TYPES) {
        const matchers = j.data.hooks[event];
        if (!Array.isArray(matchers)) continue;
        const flat = [];
        for (const m of matchers) {
          const matcher = m.matcher || "*";
          const list = Array.isArray(m.hooks) ? m.hooks : [];
          for (const h of list) {
            flat.push({
              matcher,
              type: h.type || "command",
              command: h.command || null,
              timeout: h.timeout || null,
            });
          }
        }
        if (flat.length) entry.hooks[event] = flat;
      }
      // Also surface unknown events the user wrote
      for (const [event, matchers] of Object.entries(j.data.hooks)) {
        if (HOOK_EVENT_TYPES.includes(event)) continue;
        if (!Array.isArray(matchers)) continue;
        entry.hooks[event] = matchers;
      }
    }
    result.push(entry);
  }
  return result;
}

// ── Settings ───────────────────────────────────────────────────────────

function readSettings(opts = {}) {
  const sources = [
    { scope: "user", file: path.join(getClaudeHome(), "settings.json") },
    {
      scope: "project",
      file: path.join(getProjectClaudeDir(opts.cwd), "settings.json"),
    },
    {
      scope: "project-local",
      file: path.join(getProjectClaudeDir(opts.cwd), "settings.local.json"),
    },
  ];
  return sources.map(({ scope, file }) => {
    const j = readJson(file);
    if (!j.ok) return { scope, file, exists: false };
    return {
      scope,
      file,
      exists: true,
      data: redactSettings(j.data),
      raw_size: j.raw.length,
    };
  });
}

// ── Marketplaces ───────────────────────────────────────────────────────

function readMarketplaces() {
  const home = getClaudeHome();
  const knownPath = path.join(home, "plugins", "known_marketplaces.json");
  const known = readJson(knownPath);
  const out = [];
  if (known.ok && known.data && typeof known.data === "object") {
    for (const [name, def] of Object.entries(known.data)) {
      const installLocation = def && def.installLocation;
      const sourceDef = def && def.source;
      let pluginCount = null;
      let marketplaceJson = null;
      if (installLocation) {
        try {
          const mfPath = path.join(installLocation, ".claude-plugin", "marketplace.json");
          const raw = fs.readFileSync(mfPath, "utf8");
          marketplaceJson = JSON.parse(raw);
          pluginCount = Array.isArray(marketplaceJson.plugins)
            ? marketplaceJson.plugins.length
            : null;
        } catch {
          /* not all marketplaces have a manifest */
        }
      }
      out.push({
        name,
        source: sourceDef && typeof sourceDef === "object" ? sourceDef : null,
        installLocation: installLocation || null,
        lastUpdated: def && def.lastUpdated ? def.lastUpdated : null,
        pluginCount,
        marketplaceName: marketplaceJson?.name || null,
        marketplaceDescription: marketplaceJson?.description || null,
        marketplaceOwner: marketplaceJson?.owner || null,
      });
    }
  }
  return {
    knownPath,
    knownExists: known.ok,
    items: out.sort((a, b) => a.name.localeCompare(b.name)),
  };
}

// ── Keybindings ────────────────────────────────────────────────────────

function readKeybindings() {
  const file = path.join(getClaudeHome(), "keybindings.json");
  const j = readJson(file);
  if (!j.ok) return { file, exists: false };
  const data = j.data && typeof j.data === "object" ? j.data : {};
  const groups = Array.isArray(data.bindings) ? data.bindings : [];
  return {
    file,
    exists: true,
    schema: data.$schema || null,
    docs: data.$docs || null,
    groups: groups.map((g) => ({
      context: g.context || "",
      bindings:
        g.bindings && typeof g.bindings === "object"
          ? Object.entries(g.bindings).map(([key, action]) => ({ key, action: String(action) }))
          : [],
    })),
  };
}

// ── Statusline (config + script content) ──────────────────────────────

function readStatusline() {
  const userSettingsPath = path.join(getClaudeHome(), "settings.json");
  const j = readJson(userSettingsPath);
  const config = j.ok && j.data && j.data.statusLine ? j.data.statusLine : null;
  const candidates = [
    path.join(getClaudeHome(), "statusline.py"),
    path.join(getClaudeHome(), "statusline-command.sh"),
  ];
  const scripts = [];
  for (const file of candidates) {
    const r = safeReadText(file);
    if (r) {
      scripts.push({
        file,
        size: r.size,
        mtime: r.mtime,
        truncated: r.truncated,
        preview: r.text.slice(0, 4000),
      });
    }
  }
  return { config, scripts };
}

// ── Hook handler scripts dir (~/.claude/hooks/) ───────────────────────

function readHookScripts() {
  const dir = path.join(getClaudeHome(), "hooks");
  const entries = listDir(dir);
  return {
    dir,
    items: entries
      .filter((e) => isFileLike(e, path.join(dir, e.name)))
      .map((e) => {
        const file = path.join(dir, e.name);
        let stat;
        try {
          stat = fs.statSync(file);
        } catch {
          return null;
        }
        return { name: e.name, file, size: stat.size, mtime: stat.mtimeMs };
      })
      .filter(Boolean)
      .sort((a, b) => a.name.localeCompare(b.name)),
  };
}

// ── Memory (CLAUDE.md + per-project file-based memory) ─────────────────

// Index/manifest files inside a memory dir (MEMORY.md, INDEX-*.md) sort
// before the per-fact files so the table-of-contents shows up first.
const MEMORY_INDEX_RE = /^(MEMORY|INDEX)\b/i;

/**
 * Read the two primary CLAUDE.md memory files (user + project) PLUS every
 * markdown file under ~/.claude/projects/<slug>/memory/ — the common
 * community pattern of a file-based agent memory store (a MEMORY.md index
 * plus one file per remembered fact). The latter are emitted with
 * scope "auto-memory" and carry `project` (the projects/<slug> dir name)
 * and `name` (the filename) so the UI can group + label them. They are
 * mutable via cc-mutate's "auto-memory" type (create/edit/delete + backup).
 */
function readMemory(opts = {}) {
  const sources = [
    { scope: "user", file: path.join(getClaudeHome(), "CLAUDE.md") },
    { scope: "project", file: path.join(getProjectRoot(opts.cwd), "CLAUDE.md") },
  ];
  const result = [];
  for (const { scope, file } of sources) {
    const r = safeReadText(file);
    if (!r) continue;
    result.push({
      scope,
      file,
      size: r.size,
      mtime: r.mtime,
      truncated: r.truncated,
      preview: r.text.slice(0, 480),
    });
  }

  // Per-project file-based memory dirs. Best-effort: a missing projects
  // root, an unreadable memory dir, or a single bad file must never break
  // the memory tab — every layer is wrapped so we degrade to "fewer files".
  try {
    const projectsRoot = path.join(getClaudeHome(), "projects");
    for (const proj of fs.readdirSync(projectsRoot)) {
      const memDir = path.join(projectsRoot, proj, "memory");
      let files;
      try {
        files = fs.readdirSync(memDir);
      } catch {
        continue;
      }
      files = files
        .filter((f) => f.endsWith(".md"))
        .sort((a, b) => {
          const rank = (f) => (MEMORY_INDEX_RE.test(f) ? 0 : 1);
          return rank(a) - rank(b) || a.localeCompare(b);
        });
      for (const f of files) {
        const file = path.join(memDir, f);
        const r = safeReadText(file);
        if (!r) continue;
        // Per-fact memory files commonly carry YAML frontmatter (name,
        // description, metadata.type) — parse it like the other MD surfaces
        // so the UI can show a clean title + description instead of raw text.
        const { frontmatter, body } = parseFrontmatter(r.text);
        result.push({
          scope: "auto-memory",
          project: proj,
          name: f,
          isIndex: MEMORY_INDEX_RE.test(f),
          file,
          size: r.size,
          mtime: r.mtime,
          truncated: r.truncated,
          frontmatter: frontmatter || {},
          preview: (body || r.text).slice(0, 480),
        });
      }
    }
  } catch {
    /* best-effort: never break the memory tab */
  }

  return result;
}

// ── Single-file body endpoint (with strict path containment) ───────────

function readFileSafe(absPath, opts = {}) {
  const allowedRoots = [
    getClaudeHome(),
    getProjectClaudeDir(opts.cwd),
    getProjectRoot(opts.cwd), // for CLAUDE.md only — caller must pass exact name
  ];
  const resolved = path.resolve(absPath);
  const inside = allowedRoots.some((root) => isUnder(root, resolved));
  if (!inside) return { error: "path is outside allowed roots" };
  // Extra guard: under project root we only allow CLAUDE.md (avoid leaking
  // arbitrary repo files via this endpoint).
  if (
    isUnder(getProjectRoot(opts.cwd), resolved) &&
    !isUnder(getProjectClaudeDir(opts.cwd), resolved) &&
    path.basename(resolved) !== "CLAUDE.md"
  ) {
    return { error: "only CLAUDE.md is readable from project root" };
  }
  const r = safeReadText(resolved);
  if (!r) return { error: "file not readable" };
  return { ok: true, file: resolved, ...r };
}

// ── Overview (counts + roots) ──────────────────────────────────────────

function readOverview(opts = {}) {
  const skills = readSkills(opts);
  const agents = readAgents(opts);
  const commands = readCommands(opts);
  const outputStyles = readOutputStyles(opts);
  const plugins = readPlugins();
  const mcp = readMcpServers(opts);
  const hooks = readHooks(opts);
  const settings = readSettings(opts);
  const memory = readMemory(opts);
  const marketplaces = readMarketplaces();
  const keybindings = readKeybindings();

  const countByScope = (arr) => ({
    user: arr.filter((x) => x.scope === "user").length,
    project: arr.filter((x) => x.scope === "project").length,
  });

  const enabledPlugins = plugins.plugins.filter((p) => p.enabled === true).length;
  const disabledPlugins = plugins.plugins.filter((p) => p.enabled === false).length;
  const keybindingTotal = keybindings.exists
    ? keybindings.groups.reduce((n, g) => n + g.bindings.length, 0)
    : 0;

  return {
    roots: {
      claudeHome: getClaudeHome(),
      projectClaudeDir: getProjectClaudeDir(opts.cwd),
      projectRoot: getProjectRoot(opts.cwd),
      claudeJson: getClaudeJsonPath(),
    },
    counts: {
      skills: countByScope(skills),
      agents: countByScope(agents),
      commands: countByScope(commands),
      outputStyles: countByScope(outputStyles),
      plugins: plugins.plugins.length,
      pluginsEnabled: enabledPlugins,
      pluginsDisabled: disabledPlugins,
      marketplaces: marketplaces.items.length,
      keybindings: keybindingTotal,
      mcpServers: { user: mcp.user.length, project: mcp.projectScoped.length },
      hooks: hooks.reduce(
        (acc, src) => {
          acc[src.scope] = Object.values(src.hooks).reduce(
            (n, arr) => n + (Array.isArray(arr) ? arr.length : 0),
            0
          );
          return acc;
        },
        { user: 0, project: 0, "project-local": 0 }
      ),
      memory: memory.length,
      settingsFiles: settings.filter((s) => s.exists).length,
    },
  };
}

module.exports = {
  // surface readers
  readSkills,
  readAgents,
  readCommands,
  readOutputStyles,
  readPlugins,
  readMcpServers,
  readHooks,
  readSettings,
  readMemory,
  readMarketplaces,
  readKeybindings,
  readStatusline,
  readHookScripts,
  readOverview,
  readFileSafe,
  // helpers exported for tests
  readPluginContributions,
  parseFrontmatter,
  redactSettings,
  isUnder,
  isFileLike,
  MAX_FILE_BYTES,
  HOOK_EVENT_TYPES,
};