dsh-claude-compat 0.3.0 → 0.6.2

package/src/hooks.js

@@ -0,0 +1,275 @@
+// dsh-claude-compat: Claude Code hooks subset (PreToolUse / PostToolUse /
+// UserPromptSubmit) bridged onto DSH's tools/pre-execute, tools/post-execute,
+// and agent/pre-step waterfalls.
+//
+// Hooks are read from <projectRoot>/.claude/settings.json (and ~/.claude/
+// settings.json; project wins on duplicate command strings). Commands run via
+// /bin/sh -c with a Claude-style JSON payload on stdin. Decisions follow Claude
+// Code semantics (exit code 2 = deny/block, hookSpecificOutput override,
+// timeouts allowed-through with a warning).
+
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import {
+  findProjectRootSync,
+  resolveUserClaudeDir,
+} from './lib.js';
+
+// Compile a Claude Code hook matcher ("Bash", "Bash|Edit", ".*") into a
+// predicate. Exact names match exactly; `*` / `.*` are wildcards; `|`
+// alternates.
+export function compileMatcher(matcher) {
+  if (typeof matcher !== 'string') return () => false;
+  const trimmed = matcher.trim();
+  if (trimmed === '' || trimmed === '*' || trimmed === '.*') return () => true;
+  try {
+    const pattern = trimmed
+      .split('|')
+      .map((part) => part.trim().split('*').join('.*'))
+      .join('|');
+    const re = new RegExp(`^(?:${pattern})$`);
+    return (name) => re.test(name);
+  } catch {
+    return () => false;
+  }
+}
+
+// ----- payloads ---------------------------------------------------------------
+
+function preToolPayload(exec) {
+  return JSON.stringify({
+    session_id: String(exec.callId),
+    tool_name: exec.name,
+    tool_input: exec.arguments ?? {},
+  });
+}
+
+function postToolPayload(exec, result) {
+  return JSON.stringify({
+    tool_name: exec.name,
+    tool_input: exec.arguments ?? {},
+    tool_response: result,
+  });
+}
+
+function promptPayload(agent) {
+  let prompt = '';
+  const events = agent.session?.events ?? {};
+  for (const event of Object.values(events)) {
+    const data = event?.data;
+    if (event?.type?.endsWith('user/message') && typeof data?.content === 'string') {
+      prompt = data.content;
+    }
+  }
+  return JSON.stringify({ prompt });
+}
+
+// ----- decision mapping (pure, exported for tests) -----------------------------
+
+// PreToolUse: exit 0 → allow; exit 2 → deny (stdout reason); other codes →
+// allow with warning. stdout JSON {"hookSpecificOutput": {...permissionDecision}}
+// overrides: "deny" → deny, "ask" → ask (best effort).
+export function mapPreHookOutput(exitCode, stdout, { warn = console.warn } = {}) {
+  if (exitCode === 0) {
+    const specific = tryHookJson(stdout)?.hookSpecificOutput;
+    if (specific?.permissionDecision === 'deny') {
+      return { kind: 'deny', reason: String(specific.permissionDecisionReason ?? fallbackReason(stdout)) };
+    }
+    if (specific?.permissionDecision === 'ask') {
+      return { kind: 'ask', reason: String(specific.permissionDecisionReason ?? 'hook requests approval') };
+    }
+    return { kind: 'allow' };
+  }
+  if (exitCode === 2) {
+    return { kind: 'deny', reason: fallbackReason(stdout) };
+  }
+  warn(`dsh-claude-compat: PreToolUse hook exited with code ${exitCode}, allowing`);
+  return { kind: 'allow' };
+}
+
+// PostToolUse: exit 2 → block (stdout feedback); exit 0 with JSON stdout
+// carrying an "additionalContext" string → accept with that context as an
+// additional user message; anything else → accept, stdout log-only.
+export function mapPostHookOutput(exitCode, stdout, { warn = console.warn } = {}) {
+  if (exitCode === 2) {
+    return { kind: 'block', feedback: [{ type: 'text', text: fallbackReason(stdout) }] };
+  }
+  if (exitCode !== 0) {
+    warn(`dsh-claude-compat: PostToolUse hook exited with code ${exitCode}, accepting`);
+    return { kind: 'accept' };
+  }
+  const trimmed = stdout.trim();
+  if (trimmed === '') return { kind: 'accept' };
+  const additional = tryHookJson(stdout)?.additionalContext;
+  if (typeof additional === 'string' && additional.length > 0) {
+    return {
+      kind: 'accept',
+      additionalContexts: [createUserMessage({
+        content: [{ type: 'text', text: additional }],
+        source: { kind: 'claude-compat', form: 'hook-context' },
+      })],
+    };
+  }
+  console.log(`dsh-claude-compat: PostToolUse hook stdout (logged, not injected): ${trimmed}`);
+  return { kind: 'accept' };
+}
+
+function fallbackReason(stdout) {
+  const trimmed = stdout.trim();
+  return trimmed !== '' ? trimmed : 'blocked by hook';
+}
+
+function tryHookJson(stdout) {
+  const s = stdout.trim();
+  if (s === '') return undefined;
+  try { return JSON.parse(s); } catch { return undefined; }
+}
+
+// ----- runner ---------------------------------------------------------------
+
+function runHookCommand(command, stdin, { timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let settled = false;
+    const child = execFile('/bin/sh', ['-c', command], {
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGKILL');
+      console.warn(`dsh-claude-compat: hook timed out after ${timeoutMs}ms, killed: ${command}`);
+      resolve({ exitCode: 1, stdout }); // treat as non-2, allow-through
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stdout += chunk; }); // surface stderr in feedback
+    child.on('error', () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      console.warn(`dsh-claude-compat: hook command failed to start: ${command}`);
+      resolve({ exitCode: 1, stdout });
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ exitCode: code ?? 1, stdout });
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(stdin);
+  });
+}
+
+// ----- settings loading ------------------------------------------------------
+
+const EVENTS = { PreToolUse: 'pre-tool-use', PostToolUse: 'post-tool-use', UserPromptSubmit: 'user-prompt-submit' };
+
+// Combined hooks map. Project .claude/settings.json is applied LAST so it wins
+// same (event, matcher, command) keys against ~/.claude/settings.json.
+export function loadHookSettings(config) {
+  const combined = {};
+  applySettingsFile(combined, join(resolveUserClaudeDir(config.userClaudeDir), 'settings.json'));
+  const projectRoot = findProjectRootSync(process.cwd(), config.projectRootMarkers);
+  if (projectRoot !== undefined) {
+    applySettingsFile(combined, join(projectRoot, '.claude', 'settings.json'));
+  }
+  return combined;
+}
+
+function applySettingsFile(combined, path) {
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); } catch { return; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch {
+    console.warn(`dsh-claude-compat: unparseable settings.json: ${path}`);
+    return;
+  }
+  const hooks = parsed?.hooks;
+  if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) return;
+  for (const [eventName, entries] of Object.entries(hooks)) {
+    const event = EVENTS[eventName];
+    if (event === undefined || !Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (typeof entry !== 'object' || entry === null) continue;
+      const matcher = typeof entry.matcher === 'string' ? entry.matcher : '.*';
+      const commands = Array.isArray(entry.hooks)
+        ? entry.hooks
+            .filter((h) => typeof h === 'object' && h !== null && typeof h.command === 'string')
+            .map((h) => h.command)
+        : [];
+      for (const command of commands) {
+        combined[`${event}\u0000${matcher}\u0000${command}`] = { event, matcher, command };
+      }
+    }
+  }
+}
+
+// ----- listeners -------------------------------------------------------------
+
+export function registerHooks(ctx, config) {
+  const settings = loadHookSettings(config);
+  const matching = (hooks, name) =>
+    hooks.filter((h) => compileMatcher(h.matcher)(name));
+
+  const pre = Object.values(settings).filter((h) => h.event === 'pre-tool-use');
+  if (pre.length > 0) {
+    ctx.on('tools/pre-execute', async (exec) => {
+      for (const hook of matching(pre, exec.name)) {
+        const payload = preToolPayload(exec);
+        const run = await runHookCommand(hook.command, payload, { timeoutMs: config.hooksTimeoutMs ?? 60_000 });
+        const decision = mapPreHookOutput(run.exitCode, run.stdout);
+        if (decision.kind !== 'allow') return decision;
+      }
+      return { kind: 'allow' };
+    });
+  }
+
+  const post = Object.values(settings).filter((h) => h.event === 'post-tool-use');
+  if (post.length > 0) {
+    ctx.on('tools/post-execute', async (exec, result) => {
+      let accept;
+      for (const hook of matching(post, exec.name)) {
+        const payload = postToolPayload(exec, result);
+        const run = await runHookCommand(hook.command, payload, { timeoutMs: config.hooksTimeoutMs ?? 60_000 });
+        const decision = mapPostHookOutput(run.exitCode, run.stdout);
+        if (decision.kind === 'block') return decision;
+        if (decision.additionalContexts !== undefined) accept = decision;
+      }
+      return accept ?? { kind: 'accept' };
+    });
+  }
+
+  const prompt = Object.values(settings).filter((h) => h.event === 'user-prompt-submit');
+  if (prompt.length > 0) {
+    ctx.on('agent/pre-step', async ({ agent, messages }, next) => {
+      const decision = await next();
+      if (decision.kind !== 'enter') return decision;
+      // First enter of the turn: the DSH loop hands the step the user claims,
+      // which is where Claude Code would have fired UserPromptSubmit. Hook
+      // output becomes an extra user message appended after the claimed ones.
+      const extra = await runPromptHooks(prompt, agent, config);
+      if (extra === undefined) return decision;
+      return { kind: 'enter', messages: decision.messages.concat(extra) };
+    });
+  }
+}
+
+async function runPromptHooks(hooks, agent, config) {
+  const timeoutMs = Math.min(config.hooksTimeoutMs ?? 60_000, 10_000); // never block the loop longer than 10s
+  const payload = promptPayload(agent);
+  const extra = [];
+  for (const hook of hooks) {
+    const run = await runHookCommand(hook.command, payload, { timeoutMs });
+    if (run.exitCode !== 0) continue; // non-zero: skip, never block a prompt
+    const text = run.stdout.trim();
+    if (text === '') continue;
+    extra.push(createUserMessage({
+      content: [{ type: 'text', text }],
+      source: { kind: 'claude-compat', form: 'hook-context' },
+    }));
+  }
+  return extra.length > 0 ? extra : undefined;
+}

package/src/index.js

@@ -1,13 +1,15 @@
 // dsh-claude-compat — bridge Claude Code's .claude/ into DSH.
 //
-// Two contributions to the live runtime:
-//   1. Skill provider on ctx.skills — scans <projectRoot>/.claude/skills/**/SKILL.md
-//      and <projectRoot>/.claude/commands/*.md (plus the user-level
-//      ~/.claude/skills and ~/.claude/commands), surfaces them as DSH skills so
-//      the `/skill-name` slash trigger, the `skill` tool, and the model-visible
-//      catalog pick them up natively. Only name+description load at discovery;
-//      the body loads on demand — same contract as the shipped filesystem
-//      provider.
+// Contributions to the live runtime:
+//   1. Skill provider on ctx.skills — scans <projectRoot>/.claude/skills/**/SKILL.md,
+//      <projectRoot>/.claude/commands/*.md and <projectRoot>/.claude/agents/*.md
+//      (plus the user-level ~/.claude equivalents), surfaces them as DSH skills
+//      so the `/skill-name` slash trigger, the `skill` tool, and the
+//      model-visible catalog pick them up natively. Only name+description load
+//      at discovery; the body loads on demand — same contract as the shipped
+//      filesystem provider. Agents are a delegation shim: DSH has no markdown
+//      subagent format, so each agent file becomes a skill whose body leads
+//      with an explicit "delegate with this persona" instruction.
 //   2. Rules message-stream injection — injects <projectRoot>/.claude/rules/*.md
 //      and ~/.claude/rules/*.md as ONE user-role <system-reminder> message
 //      prepended at the front of the message array, once per session
@@ -16,6 +18,11 @@
 //      project .claude winning over ~/.claude.
 //      CLAUDE.md / AGENTS.md are already handled by dsh-agent-instructions,
 //      so we do NOT re-inject them here.
+//   3. Hooks (Claude Code subset PreToolUse/PostToolUse/UserPromptSubmit) from
+//      .claude/settings.json — bridged onto tools/pre-execute,
+//      tools/post-execute and agent/pre-step (see src/hooks.js).
+//   4. MCP servers from <projectRoot>/.mcp.json — mounted as dsh-mcp-client
+//      plugin instances at startup from the launch workspace (see src/mcp.js).
 //
 // Skill name flattening: .claude/skills/gitnexus/gitnexus-guide/SKILL.md →
 // "gitnexus-gitnexus-guide" (DSH skill names must be kebab-case; the shipped
@@ -36,14 +43,25 @@
 // launched from anywhere). Editing a rule mid-session takes effect in the
 // next session.
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, dirname, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { parse } from 'yaml';
 import { isSkillName } from '@deepseek-ai/dsh-skill';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { discoverAgents, renderAgentContent } from './agents.js';
+import { registerHooks } from './hooks.js';
+import { mountMcpServers, mountMcpConfigs } from './mcp.js';
+import { discoverPluginContent, readInstalledClaudePlugins, translatePluginMcp } from './plugins.js';
+import {
+  findProjectRoot,
+  findProjectRootSync,
+  listMdFilesSync,
+  parseFrontmatter,
+  readTextSafe,
+  resolveUserClaudeDir,
+  stringField,
+} from './lib.js';
 
 export const name = 'claude-compat';
 export const inject = ['skills'];
@@ -63,6 +81,20 @@ export const Config = z.object({
   userRulesMaxBytes: z.number().default(65536),
   enableRules: z.boolean().default(true),
   enableSkills: z.boolean().default(true),
+  enableMcp: z.boolean().default(true),
+  mcpFailOnStartupError: z.boolean().default(false),
+  enableHooks: z.boolean().default(true),
+  hooksTimeoutMs: z.number().default(60000),
+  enableAgents: z.boolean().default(true),
+  // Claude Code plugin-marketplace installs (~/.claude/plugins). Skills,
+  // commands and agents surface at pluginSkillRank (750: the long tail —
+  // everything else wins collisions). Plugin MCP servers are opt-in via
+  // enablePluginMcp (mounting third-party MCP is a bigger trust step).
+  enablePlugins: z.boolean().default(true),
+  pluginSkillRank: z.number().default(750),
+  pluginSkillSource: z.string().default('claude-plugin'),
+  pluginsRoot: z.string().default('~/.claude/plugins'),
+  enablePluginMcp: z.boolean().default(false),
 });
 
 export function apply(ctx, config = {}) {
@@ -73,6 +105,36 @@ export function apply(ctx, config = {}) {
   if (config.enableRules !== false) {
     registerRulesSection(ctx, config);
   }
+  if (config.enableHooks !== false) {
+    registerHooks(ctx, config);
+  }
+  if (config.enableMcp !== false) {
+    // Process-lifetime mount — deliberately NOT session-scoped (see src/mcp.js).
+    mountMcpServers(ctx, config).catch((error) => {
+      console.warn('dsh-claude-compat: MCP mount failed:', error?.message ?? error);
+    });
+    if (config.enablePlugins !== false && config.enablePluginMcp === true) {
+      mountPluginMcp(ctx, config).catch((error) => {
+        console.warn('dsh-claude-compat: plugin MCP mount failed:', error?.message ?? error);
+      });
+    }
+  }
+}
+
+// Opt-in: translate every installed plugin's MCP config and mount alongside
+// the project .mcp.json servers (see src/mcp.js mountMcpConfigs).
+async function mountPluginMcp(ctx, config) {
+  for (const plugin of readInstalledClaudePlugins(config.pluginsRoot)) {
+    const raw = await readTextSafe(join(plugin.installPath, '.claude-plugin', 'plugin.json'));
+    if (raw === undefined) continue;
+    let manifest;
+    try { manifest = JSON.parse(raw); } catch { continue; }
+    const { servers, warns } = translatePluginMcp(manifest, plugin.installPath, {
+      failOnStartupError: config.mcpFailOnStartupError ?? false,
+    });
+    warns.forEach((w) => console.warn(`dsh-claude-compat: plugin ${plugin.key}: ${w}`));
+    if (servers.length > 0) await mountMcpConfigs(ctx, servers);
+  }
 }
 
 // ─── skill provider ──────────────────────────────────────────────────────────
@@ -87,6 +149,7 @@ class ClaudeCompatSkillProvider {
     this.userSkillRank = config.userSkillRank ?? 700;
     this.userSkillSource = config.userSkillSource ?? 'user-claude';
     this.userClaudeDir = resolveUserClaudeDir(config.userClaudeDir);
+    this.control = control;
     control.signal.addEventListener('abort', () => {}, { once: true });
   }
 
@@ -103,17 +166,82 @@ class ClaudeCompatSkillProvider {
       }
     }
     await this.addRootCandidates(candidates, this.userClaudeDir, this.userSkillSource, this.userSkillRank);
+    if (this.config.enablePluginManager !== false) {
+      candidates.push(this.managerSkillCandidate('cc-plugin',
+        'Manage Claude Code plugins and marketplaces: list, install, uninstall, enable, disable, update, search.',
+        'User wants to install, list, enable/disable, update, or uninstall Claude Code plugins, or manage plugin marketplaces. Usage: /cc-plugin, /cc-plugin <name>[@marketplace], /cc-plugin install|uninstall|enable|disable|update|search ..., /cc-plugin marketplace list|add|remove|update.',
+        (await import('./plugin-manager.js')).PLUGIN_SKILL_BODY));
+      candidates.push(this.reloadSkillDef('reload-cc-plugins',
+        'Hot-reload the skill catalog: pick up newly installed/removed Claude Code plugin skills without a new session.'));
+      candidates.push(this.reloadSkillDef('reload-skills',
+        'Hot-reload the skill catalog (alias of /reload-cc-plugins).'));
+    }
+    if (this.config.enablePlugins !== false) {
+      const pluginCandidates = await discoverPluginContent(
+        this.config.pluginsRoot, this.name, this.config.pluginSkillSource ?? 'claude-plugin',
+        this.config.pluginSkillRank ?? 750, { enableAgents: this.config.enableAgents });
+      candidates.push(...pluginCandidates);
+    }
     return candidates;
   }
 
+  // Invalidate fires when the definition is actually loaded (get()), not at
+  // list() time — loading the reload skill IS the reload.
+  reloadSkillDef(name, description) {
+    return {
+      name,
+      description,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'claude-compat',
+      source: 'claude-compat-manager',
+      rank: this.config.pluginManagerRank ?? 40,
+      locator: { kind: 'inline', path: import.meta.url },
+      get: async () => {
+        try { this.control?.invalidate?.(); } catch { /* best-effort */ }
+        return {
+          name,
+          description,
+          body: `# Catalog reloaded ✅
+
+The DSH skill catalog cache was just dropped and observers notified.
+Freshly installed/removed skills are now visible in this session (the skill
+picker refreshes automatically on the next catalog read).
+
+Notes:
+- New skills from \`/plugin install\` or edits under \`.claude\` are live now.
+- MCP servers shipped by plugins still require a DSH restart (process-lifetime mount).
+- \`/reload-cc-plugins\` and \`/reload-skills\` are aliases.`,
+        };
+      },
+    };
+  }
+
+  managerSkillCandidate(name, description, whenToUse, body) {
+    return {
+      name,
+      description,
+      whenToUse,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'claude-compat',
+      source: 'claude-compat-manager',
+      rank: this.config.pluginManagerRank ?? 40,
+      locator: { kind: 'inline', path: import.meta.url },
+      get: async () => ({ name, description, body }),
+    };
+  }
+
   async addRootCandidates(candidates, claudeDir, source, rank) {
-    if (!(await pathExists(claudeDir))) return;
-    for (const c of await discoverSkills(join(claudeDir, 'skills'), this.name, source, rank)) {
-      candidates.push(c);
-    }
-    for (const c of await discoverCommands(join(claudeDir, 'commands'), this.name, source, rank)) {
-      candidates.push(c);
+    const provider = this.name;
+    const tasks = [discoverSkills(join(claudeDir, 'skills'), provider, source, rank)];
+    for (const [dir, fn] of [
+      ['commands', discoverCommands],
+      ['agents', discoverAgents],
+    ]) {
+      if (dir === 'agents' && this.config.enableAgents === false) continue;
+      tasks.push(fn(join(claudeDir, dir), provider, source, rank));
     }
+    const batches = await Promise.all(tasks);
+    for (const batch of batches) candidates.push(...batch);
   }
 
   async get(candidate) {
@@ -121,7 +249,13 @@ class ClaudeCompatSkillProvider {
     const raw = await readTextSafe(locator.path);
     if (raw === undefined) return undefined;
     const parsed = parseFrontmatter(raw);
-    const content = parsed === undefined ? raw.trim() : parsed.body.trim();
+    let content;
+    if (candidate.agentTools !== undefined) {
+      // Agent-backed candidate: lead the body with the delegation instruction.
+      content = renderAgentContent(candidate, (parsed?.body ?? raw).trim());
+    } else {
+      content = parsed === undefined ? raw.trim() : parsed.body.trim();
+    }
     return {
       name: candidate.name,
       description: candidate.description,
@@ -138,9 +272,10 @@ class ClaudeCompatSkillProvider {
 
 // ─── discovery: <root>/.claude/skills (recursive, ≤3 levels) ─────────────────
 
-async function discoverSkills(rootDir, providerName, source, rank) {
+export async function discoverSkills(rootDir, providerName, source, rank) {
+  const { readdir } = await import('node:fs/promises');
   const out = [];
-  if (!(await pathExists(rootDir))) return out;
+  if (!(await pathExistsSafe(rootDir))) return out;
   await walk(rootDir, '', 0);
   return out;
 
@@ -167,9 +302,10 @@ async function discoverSkills(rootDir, providerName, source, rank) {
 
 // ─── discovery: <root>/.claude/commands (flat) ───────────────────────────────
 
-async function discoverCommands(rootDir, providerName, source, rank) {
+export async function discoverCommands(rootDir, providerName, source, rank) {
+  const { readdir } = await import('node:fs/promises');
   const out = [];
-  if (!(await pathExists(rootDir))) return out;
+  if (!(await pathExistsSafe(rootDir))) return out;
   let entries;
   try {
     entries = await readdir(rootDir, { withFileTypes: true, encoding: 'utf8' });
@@ -307,106 +443,12 @@ ${parts.join('\n')}
       </system-reminder>`;
 }
 
-function findProjectRootSync(cwd, markers = ['.git']) {
-  let current = resolve(cwd);
-  while (true) {
-    for (const marker of markers) {
-      if (existsSync(join(current, marker))) return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return undefined;
-    current = parent;
-  }
-}
-
-function listMdFilesSync(dir) {
-  let entries;
-  try { entries = readdirSync(dir); } catch { return []; }
-  const files = [];
-  for (const name of entries) {
-    if (!name.endsWith('.md')) continue;
-    const p = join(dir, name);
-    try { if (statSync(p).isFile()) files.push(p); } catch {}
-  }
-  files.sort();
-  return files;
-}
-
 // ─── helpers ─────────────────────────────────────────────────────────────────
 
-function resolveUserClaudeDir(dir) {
-  if (dir === undefined || dir === null || dir === '') return join(homedir(), '.claude');
-  if (dir === '~') return homedir();
-  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2));
-  return resolve(dir);
-}
-
-async function findProjectRoot(cwd, markers = ['.git']) {
-  let current = resolve(cwd);
-  while (true) {
-    for (const marker of markers) {
-      if (await pathExists(join(current, marker))) return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return undefined;
-    current = parent;
-  }
-}
-
-async function pathExists(path) {
+async function pathExistsSafe(path) {
   try { await stat(path); return true; } catch { return false; }
 }
 
-async function readTextSafe(path) {
-  try { return await readFile(path, { encoding: 'utf8' }); }
-  catch { return undefined; }
-}
-
-async function listMdFiles(dir) {
-  let entries;
-  try { entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' }); }
-  catch { return []; }
-  const files = [];
-  for (const e of entries) {
-    if (e.isFile() && e.name.endsWith('.md')) files.push(join(dir, e.name));
-  }
-  files.sort();
-  return files;
-}
-
-function parseFrontmatter(raw) {
-  const firstLineEnd = raw.indexOf('\n');
-  if (firstLineEnd < 0) return undefined;
-  if (raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return undefined;
-  const start = firstLineEnd + 1;
-  const closing = findClosingFrontmatter(raw, start);
-  if (closing === undefined) return undefined;
-  let parsed;
-  try { parsed = parse(raw.slice(start, closing.start)); }
-  catch { return undefined; }
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
-  return { data: parsed, body: raw.slice(closing.bodyStart) };
-}
-
-function findClosingFrontmatter(raw, start) {
-  let lineStart = start;
-  while (lineStart <= raw.length) {
-    const nextNewline = raw.indexOf('\n', lineStart);
-    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
-    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
-      return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 };
-    }
-    if (nextNewline < 0) return undefined;
-    lineStart = nextNewline + 1;
-  }
-  return undefined;
-}
-
-function stringField(data, key) {
-  const v = data[key];
-  return typeof v === 'string' && v.length > 0 ? v : undefined;
-}
-
 function parseInvocationPolicy(data) {
   const miv = data['disable-model-invocation'];
   const uiv = data['user-invocable'];
@@ -424,4 +466,4 @@ function truthy(v) {
   }
   if (typeof v === 'number') return v !== 0;
   return false;
-}
+}