memtrace-skills 0.7.10

package/dist/transformers/claude.js

@@ -0,0 +1,702 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { execCommand, commandExists } from '../utils.js';
+import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+import { MEMTRACE_MCP_ENV } from './shared.js';
+const PLUGIN_NAME = 'memtrace-skills';
+const MARKETPLACE_NAME = 'memtrace';
+const MARKETPLACE_REPO = 'syncable-dev/memtrace-public';
+const MARKETPLACE_GIT_URL = `https://github.com/${MARKETPLACE_REPO}.git`;
+const PLUGIN_KEY = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+const MARKETPLACE_SETTING_KEYS = [
+    MARKETPLACE_NAME,
+    'syncable-dev-memtrace',
+    'syncable-dev-memtrace-public',
+];
+const MARKETPLACE_SETTING_CONTAINERS = [
+    'extraKnownMarketplaces',
+    'marketplaces',
+    'pluginMarketplaces',
+    'knownMarketplaces',
+];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read the existing env block (if any) for the memtrace MCP entry in a Claude
+ * settings/mcp.json file. Returns an empty object if the file or entry is
+ * missing/malformed. Used to deep-merge user-set env keys
+ * (e.g. MEMTRACE_LICENSE_KEY) so they survive `memtrace install`
+ * re-registration. Mirrors the codex transformer's env-preservation contract.
+ */
+function readExistingMemtraceEnv(filePath, serverKey = 'mcpServers') {
+    if (!fs.existsSync(filePath))
+        return {};
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value)
+        return {};
+    const servers = value[serverKey];
+    if (!isRecord(servers))
+        return {};
+    const entry = servers['memtrace'];
+    if (!isRecord(entry))
+        return {};
+    const env = entry.env;
+    if (!isRecord(env))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Try to register the memtrace MCP server via `claude mcp add-json`.
+ * Returns true on success, false on timeout/error/missing CLI.
+ * 5-second timeout — we fall back to direct JSON merge fast.
+ *
+ * The env block deep-merges any user-set env keys discovered in the existing
+ * settings.json on top of MEMTRACE_MCP_ENV defaults so that a re-install never
+ * stomps user-added keys like MEMTRACE_LICENSE_KEY.
+ */
+async function tryMcpAddJson(memtraceBinary) {
+    if (!(await commandExists('claude')))
+        return false;
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    const existingEnv = readExistingMemtraceEnv(settingsFile);
+    const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
+    const config = JSON.stringify({
+        command: memtraceBinary,
+        args: ['mcp'],
+        env: mergedEnv,
+    });
+    // Shell-quote the JSON. Use single quotes; escape any embedded single quote.
+    const escaped = config.replace(/'/g, `'\\''`);
+    try {
+        await execCommand(`claude mcp add-json --scope user memtrace '${escaped}'`, { timeoutMs: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Transform a skill into Claude Code plugin format.
+ * Each skill becomes a directory with SKILL.md inside skills/<skill-name>/
+ */
+export function transformForClaude(skill) {
+    const skillName = skill.filename.replace(/\.md$/, '');
+    const safeDesc = skill.frontmatter.description
+        .replace(/"/g, '\\"')
+        .trim();
+    const content = `---\nname: ${skillName}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
+    return [{ relativePath: `skills/${skillName}/SKILL.md`, content }];
+}
+/**
+ * Root directory for all cached versions of this plugin.
+ */
+function getPluginCacheRoot() {
+    return path.join(os.homedir(), '.claude', 'plugins', 'cache', MARKETPLACE_NAME, PLUGIN_NAME);
+}
+/**
+ * Find the cache directory that Claude Code's CLI created (from `claude plugin install`).
+ */
+function findCliInstalledCacheDir() {
+    const root = getPluginCacheRoot();
+    if (!fs.existsSync(root))
+        return null;
+    for (const entry of fs.readdirSync(root)) {
+        const dir = path.join(root, entry);
+        if (!fs.statSync(dir).isDirectory())
+            continue;
+        return dir;
+    }
+    return null;
+}
+/**
+ * Fallback cache directory when the CLI install didn't create one.
+ */
+export function getClaudePluginCacheDir() {
+    return path.join(getPluginCacheRoot(), '0.0.0');
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Installation strategy (in priority order):
+//
+//   1. `claude plugin marketplace add` + `claude plugin install`
+//      The official flow. Registers the marketplace, clones the plugin,
+//      caches it, AND auto-enables it in settings.
+//
+//   2. Manual write: cache files + enabledPlugins in settings.json
+//      If the CLI is unavailable, write plugin files directly to the
+//      cache directory AND register in ~/.claude/settings.json.
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Try to install the plugin via the Claude Code CLI.
+ */
+async function tryClaudeCliInstall() {
+    const hasClaude = await commandExists('claude');
+    if (!hasClaude)
+        return false;
+    try {
+        await execCommand(`claude plugin marketplace add --scope user ${MARKETPLACE_GIT_URL}`);
+    }
+    catch {
+        // Marketplace may already exist
+    }
+    try {
+        await execCommand(`claude plugin install ${PLUGIN_NAME}@${MARKETPLACE_NAME} --scope user`);
+        return true;
+    }
+    catch {
+        try {
+            const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+            if (fs.existsSync(settingsPath)) {
+                const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+                if (settings.enabledPlugins?.[PLUGIN_KEY] === true) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // Fall through to manual
+        }
+        return false;
+    }
+}
+/**
+ * Write the plugin.json manifest inside the cache directory.
+ */
+function writePluginManifest(cacheDir) {
+    const manifestDir = path.join(cacheDir, '.claude-plugin');
+    fs.mkdirSync(manifestDir, { recursive: true });
+    const version = path.basename(cacheDir);
+    const manifest = {
+        name: PLUGIN_NAME,
+        description: 'Memtrace skills for codebase exploration, code search, relationship analysis, temporal evolution, blast radius impact, code quality, graph algorithms, API topology, and multi-step workflows.',
+        version,
+        author: {
+            name: 'Syncable',
+            email: 'support@memtrace.io',
+        },
+        homepage: 'https://memtrace.io',
+        repository: `https://github.com/${MARKETPLACE_REPO}`,
+        license: 'SEE LICENSE IN LICENSE',
+        keywords: ['memtrace', 'code-intelligence', 'knowledge-graph', 'mcp', 'temporal-analysis'],
+    };
+    fs.writeFileSync(path.join(manifestDir, 'plugin.json'), JSON.stringify(manifest, null, 2));
+}
+/**
+ * Merge-add the memtrace MCP server into a Claude settings.json file.
+ * Never overwrites a malformed file — backs it up and returns registered=false.
+ */
+export function registerMcpInSettingsAt(settingsPath, memtraceBinary) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped MCP registration for Claude.`);
+        console.warn(`memtrace: fix the file and run 'memtrace install --repair'.`);
+        return { registered: false, backupPath };
+    }
+    const settings = (value ?? {});
+    settings.mcpServers = settings.mcpServers ?? {};
+    // Deep-merge env so user-set keys (e.g. MEMTRACE_LICENSE_KEY) survive
+    // re-registration. memtrace-owned keys (MEMTRACE_MCP_ENV) override on
+    // conflict so installer-managed values stay authoritative.
+    const existing = settings.mcpServers['memtrace'];
+    const existingEnv = (isRecord(existing) && isRecord(existing.env))
+        ? existing.env
+        : {};
+    const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
+    settings.mcpServers['memtrace'] = {
+        command: memtraceBinary,
+        args: ['mcp'],
+        env: mergedEnv,
+    };
+    writeJsonAtomic(settingsPath, settings);
+    return { registered: true };
+}
+/**
+ * The tool surfaces Rail intercepts. Native `Grep`/`Glob` are the high-volume
+ * offenders; `Bash` catches rg/grep/find/fd commands.
+ */
+const RAIL_HOOK_MATCHER = 'Grep|Glob|Bash';
+/** Substring that identifies a memtrace-owned Rail hook entry (for idempotent
+ * re-register + clean removal). */
+const RAIL_HOOK_MARKER = 'route --hook';
+const LEGACY_HOOK_SCRIPT_BASENAMES = [
+    'userprompt-claude.sh',
+    'posttool-mcp-telemetry.sh',
+];
+/**
+ * Register the Memtrace Rail PreToolUse hook in a Claude settings.json.
+ *
+ * This is what makes Rail "part of memtrace" rather than a manual install:
+ * `memtrace install` wires a PreToolUse hook that pipes every Grep/Glob/Bash
+ * attempt through `memtrace route --hook`. The hook defaults to **observe**
+ * (zero behavior change) — `MEMTRACE_RAIL=nudge|rail|strict` opts into more.
+ * Mode is intentionally NOT baked into the command so the user can change it
+ * via env without re-installing.
+ *
+ * Idempotent: any prior Rail entry (identified by {@link RAIL_HOOK_MARKER}) is
+ * replaced, and unrelated PreToolUse hooks are preserved. Never overwrites a
+ * malformed file.
+ */
+export function registerRailHookInSettingsAt(settingsPath, memtraceBinary) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook registration.`);
+        return { registered: false, backupPath };
+    }
+    const settings = (value ?? {});
+    settings.hooks = isRecord(settings.hooks) ? settings.hooks : {};
+    pruneMemtraceOwnedHookEntries(settings.hooks);
+    const existing = Array.isArray(settings.hooks.PreToolUse)
+        ? settings.hooks.PreToolUse
+        : [];
+    // Drop any prior memtrace Rail entry so re-install doesn't duplicate it.
+    const preserved = existing.filter((entry) => !isMemtraceOwnedHookEntry(entry));
+    preserved.push({
+        matcher: RAIL_HOOK_MATCHER,
+        hooks: [
+            {
+                type: 'command',
+                command: `${memtraceBinary} route --hook`,
+            },
+        ],
+    });
+    settings.hooks.PreToolUse = preserved;
+    writeJsonAtomic(settingsPath, settings);
+    return { registered: true };
+}
+/** True when a PreToolUse entry is a memtrace-owned Rail hook. */
+function isRailHookEntry(entry) {
+    return hookCommands(entry).some((command) => command.includes(RAIL_HOOK_MARKER));
+}
+function isLegacyMemtraceHookEntry(entry) {
+    return hookCommands(entry).some((command) => (LEGACY_HOOK_SCRIPT_BASENAMES.some((basename) => command.includes(basename))));
+}
+function isMemtraceOwnedHookEntry(entry) {
+    return isRailHookEntry(entry) || isLegacyMemtraceHookEntry(entry);
+}
+function hookCommands(entry) {
+    if (!isRecord(entry))
+        return [];
+    const commands = [];
+    if (typeof entry.command === 'string') {
+        commands.push(entry.command);
+    }
+    if (Array.isArray(entry.hooks)) {
+        for (const hook of entry.hooks) {
+            if (isRecord(hook) && typeof hook.command === 'string') {
+                commands.push(hook.command);
+            }
+        }
+    }
+    return commands;
+}
+function pruneMemtraceOwnedHookEntries(hooks) {
+    let changed = false;
+    for (const key of Object.keys(hooks)) {
+        const entries = hooks[key];
+        if (!Array.isArray(entries))
+            continue;
+        const preserved = entries.filter((entry) => !isMemtraceOwnedHookEntry(entry));
+        if (preserved.length === entries.length)
+            continue;
+        changed = true;
+        hooks[key] = preserved.length === 0 ? undefined : preserved;
+    }
+    return changed;
+}
+function hasHookSettings(hooks) {
+    return Object.values(hooks).some((entries) => (entries !== undefined && (!Array.isArray(entries) || entries.length > 0)));
+}
+/**
+ * Remove the Memtrace Rail PreToolUse hook from a Claude settings.json.
+ * Preserves unrelated hooks; prunes empty containers. Never touches a
+ * malformed file.
+ */
+export function removeRailHookFromSettingsAt(settingsPath) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook cleanup.`);
+        return { changed: false, backupPath };
+    }
+    if (!value)
+        return { changed: false };
+    const settings = value;
+    if (!isRecord(settings.hooks) || !Array.isArray(settings.hooks.PreToolUse)) {
+        return { changed: false };
+    }
+    const before = settings.hooks.PreToolUse;
+    const after = before.filter((entry) => !isRailHookEntry(entry));
+    if (after.length === before.length)
+        return { changed: false };
+    if (after.length === 0) {
+        delete settings.hooks.PreToolUse;
+    }
+    else {
+        settings.hooks.PreToolUse = after;
+    }
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    writeJsonAtomic(settingsPath, settings);
+    return { changed: true };
+}
+/**
+ * Merge-add plugin + marketplace entries into a Claude settings.json file.
+ * Never overwrites a malformed file.
+ */
+export function enablePluginInSettingsAt(settingsPath) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}.`);
+        return { registered: false, backupPath };
+    }
+    const settings = (value ?? {});
+    settings.enabledPlugins = settings.enabledPlugins ?? {};
+    settings.enabledPlugins[PLUGIN_KEY] = true;
+    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces ?? {};
+    settings.extraKnownMarketplaces[MARKETPLACE_NAME] = {
+        source: { source: 'git', url: MARKETPLACE_GIT_URL },
+    };
+    writeJsonAtomic(settingsPath, settings);
+    return { registered: true };
+}
+/**
+ * Enable the plugin in ~/.claude/settings.json.
+ */
+function enablePluginInSettings() {
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    enablePluginInSettingsAt(settingsFile);
+}
+/**
+ * Remove every Claude settings entry Memtrace may have written across
+ * installer versions and Claude marketplace schema changes.
+ */
+export function removeClaudeSettingsEntriesAt(settingsPath) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Claude settings cleanup.`);
+        return { changed: false, backupPath };
+    }
+    if (!value)
+        return { changed: false };
+    const settings = value;
+    let changed = false;
+    const enabledPlugins = settings.enabledPlugins;
+    if (isRecord(enabledPlugins)) {
+        for (const key of Object.keys(enabledPlugins)) {
+            if (key === PLUGIN_KEY || (key.startsWith(`${PLUGIN_NAME}@`) && key.includes('memtrace'))) {
+                delete enabledPlugins[key];
+                changed = true;
+            }
+        }
+        if (Object.keys(enabledPlugins).length === 0)
+            delete settings.enabledPlugins;
+    }
+    const mcpServers = settings.mcpServers;
+    if (isRecord(mcpServers) && Object.hasOwn(mcpServers, 'memtrace')) {
+        delete mcpServers.memtrace;
+        changed = true;
+        if (Object.keys(mcpServers).length === 0)
+            delete settings.mcpServers;
+    }
+    // ─── memtrace-rail ─── Remove current Rail and legacy telemetry hooks on uninstall.
+    if (isRecord(settings.hooks)) {
+        changed = pruneMemtraceOwnedHookEntries(settings.hooks) || changed;
+        if (!hasHookSettings(settings.hooks))
+            settings.hooks = undefined;
+    }
+    for (const containerName of MARKETPLACE_SETTING_CONTAINERS) {
+        const container = settings[containerName];
+        if (!isRecord(container))
+            continue;
+        for (const key of MARKETPLACE_SETTING_KEYS) {
+            if (Object.hasOwn(container, key)) {
+                delete container[key];
+                changed = true;
+            }
+        }
+        if (Object.keys(container).length === 0)
+            delete settings[containerName];
+    }
+    if (changed)
+        writeJsonAtomic(settingsPath, settings);
+    return { changed };
+}
+function removeClaudeMarketplaceCacheDirs() {
+    const marketplacesRoot = path.join(os.homedir(), '.claude', 'plugins', 'marketplaces');
+    for (const entry of MARKETPLACE_SETTING_KEYS) {
+        const dir = path.join(marketplacesRoot, entry);
+        if (fs.existsSync(dir)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+function removeClaudeInstalledPluginMetadata() {
+    const installedPluginsFile = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    const { value, corrupted } = safeReadJson(installedPluginsFile);
+    if (corrupted || !value || !isRecord(value.plugins))
+        return;
+    let changed = false;
+    for (const key of Object.keys(value.plugins)) {
+        if (key === PLUGIN_KEY || (key.startsWith(`${PLUGIN_NAME}@`) && key.includes('memtrace'))) {
+            delete value.plugins[key];
+            changed = true;
+        }
+    }
+    if (changed)
+        writeJsonAtomic(installedPluginsFile, value);
+}
+/**
+ * Register the memtrace MCP server in Claude Code's settings.
+ * This adds the MCP server config so Claude Code can connect to memtrace tools.
+ */
+async function registerMcpServer(memtraceBinaryPath) {
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    // ─── memtrace-rail ─── Always wire the Memtrace-first discovery hook so it
+    // ships as part of `memtrace install` (not a manual step). Hooks live in
+    // settings.json regardless of which MCP-registration strategy wins, and the
+    // hook defaults to observe mode (zero behavior change) until the user opts
+    // into MEMTRACE_RAIL=nudge|rail|strict. Failure here must not block MCP
+    // registration.
+    // `memtrace install --no-hooks` (memtrace-public #25) propagates here via
+    // MEMTRACE_INSTALL_NO_HOOKS=1 — skip ALL settings.json hook registration.
+    if (process.env.MEMTRACE_INSTALL_NO_HOOKS !== '1') {
+        try {
+            registerRailHookInSettingsAt(settingsFile, memtraceBinaryPath);
+        }
+        catch (e) {
+            console.warn(`memtrace: failed to register Rail hook: ${e.message}`);
+        }
+    }
+    // Strategy 1 (preferred): claude CLI's own add-json path
+    const viaCli = await tryMcpAddJson(memtraceBinaryPath);
+    if (viaCli)
+        return;
+    // Strategy 2 (fallback): direct settings.json merge (safe + atomic)
+    registerMcpInSettingsAt(settingsFile, memtraceBinaryPath);
+}
+/**
+ * Full Claude Code plugin installation.
+ *
+ *  1. Try `claude plugin marketplace add` + `claude plugin install`
+ *  2. Fall back to manual: write cache files + update settings.json
+ *  3. Register MCP server for memtrace tools
+ */
+export async function installClaudePlugin(skills, memtraceBinaryPath) {
+    // Step 1: make sure Claude sees the public HTTPS marketplace source before
+    // the CLI attempts to clone/update it.
+    enablePluginInSettings();
+    removeClaudeMarketplaceCacheDirs();
+    // Step 2: Try CLI install
+    await tryClaudeCliInstall();
+    // Step 3: Find or create cache dir
+    let cacheDir = findCliInstalledCacheDir();
+    if (cacheDir) {
+        const orphanedFile = path.join(cacheDir, '.orphaned_at');
+        if (fs.existsSync(orphanedFile))
+            fs.unlinkSync(orphanedFile);
+    }
+    else {
+        cacheDir = getClaudePluginCacheDir();
+    }
+    // Step 4: Clean up old versions
+    const pluginRoot = getPluginCacheRoot();
+    if (fs.existsSync(pluginRoot)) {
+        const activeDirName = path.basename(cacheDir);
+        for (const entry of fs.readdirSync(pluginRoot)) {
+            if (entry !== activeDirName && entry !== '.DS_Store') {
+                fs.rmSync(path.join(pluginRoot, entry), { recursive: true, force: true });
+            }
+        }
+    }
+    // Step 5: Write skills
+    const skillsDir = path.join(cacheDir, 'skills');
+    if (fs.existsSync(skillsDir)) {
+        fs.rmSync(skillsDir, { recursive: true });
+    }
+    for (const skill of skills) {
+        const results = transformForClaude(skill);
+        for (const { relativePath, content } of results) {
+            const fullPath = path.join(cacheDir, relativePath);
+            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+            fs.writeFileSync(fullPath, content);
+        }
+    }
+    writePluginManifest(cacheDir);
+    enablePluginInSettings();
+    // Step 6: Register MCP server
+    await registerMcpServer(memtraceBinaryPath);
+    // Skills ship via the memtrace-skills@memtrace plugin only. Writing
+    // bare copies to ~/.claude/skills/memtrace-* duplicates every skill
+    // in Claude Code when the plugin is also enabled (issue #11).
+    return { cacheDir, skillCount: skills.length };
+}
+/**
+ * Write skills to ~/.claude/skills/ for SDK-based integrations.
+ */
+function writeUserLevelSkills(skills) {
+    const userSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+    if (fs.existsSync(userSkillsDir)) {
+        for (const entry of fs.readdirSync(userSkillsDir)) {
+            if (entry.startsWith('memtrace-')) {
+                fs.rmSync(path.join(userSkillsDir, entry), { recursive: true, force: true });
+            }
+        }
+    }
+    for (const skill of skills) {
+        const skillName = skill.filename.replace(/\.md$/, '');
+        const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+        const content = `---\nname: ${skillName}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
+        const outDir = path.join(userSkillsDir, skillName);
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+    }
+}
+/**
+ * Remove the Claude Code plugin and MCP server registration.
+ */
+export async function uninstallClaudePlugin() {
+    const hasClaude = await commandExists('claude');
+    if (hasClaude) {
+        try {
+            await execCommand(`claude plugin uninstall ${PLUGIN_NAME}@${MARKETPLACE_NAME} --scope user`);
+        }
+        catch { /* fall through */ }
+    }
+    // Manual cleanup
+    const cacheRoot = getPluginCacheRoot();
+    if (fs.existsSync(cacheRoot)) {
+        fs.rmSync(cacheRoot, { recursive: true });
+    }
+    // Remove from settings.json
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    if (fs.existsSync(settingsFile)) {
+        try {
+            removeClaudeSettingsEntriesAt(settingsFile);
+        }
+        catch { /* */ }
+    }
+    removeClaudeMarketplaceCacheDirs();
+    removeClaudeInstalledPluginMetadata();
+    // Clean up user-level skills
+    const userSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+    if (fs.existsSync(userSkillsDir)) {
+        for (const entry of fs.readdirSync(userSkillsDir)) {
+            if (entry.startsWith('memtrace-')) {
+                const entryPath = path.join(userSkillsDir, entry);
+                const stat = fs.statSync(entryPath);
+                if (stat.isDirectory()) {
+                    fs.rmSync(entryPath, { recursive: true });
+                }
+                else if (entry.endsWith('.md')) {
+                    fs.unlinkSync(entryPath);
+                }
+            }
+        }
+    }
+}
+/**
+ * Write/merge the memtrace MCP server entry into a project-local .mcp.json.
+ * Safe-reads existing config; never overwrites a malformed file.
+ */
+function writeClaudeLocalMcp(mcpPath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(mcpPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${mcpPath} is malformed; backed up to ${backupPath}. Skipped MCP registration.`);
+        return false;
+    }
+    const cfg = (value ?? {});
+    cfg.mcpServers = cfg.mcpServers ?? {};
+    // Deep-merge env: preserve user-set keys, memtrace defaults win on conflict.
+    const existing = cfg.mcpServers['memtrace'];
+    const existingEnv = (isRecord(existing) && isRecord(existing.env))
+        ? existing.env
+        : {};
+    const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
+    cfg.mcpServers['memtrace'] = {
+        command: binary,
+        args: ['mcp'],
+        env: mergedEnv,
+    };
+    writeJsonAtomic(mcpPath, cfg);
+    return true;
+}
+export const claudeTransformer = {
+    name: 'claude',
+    async install(skills, ctx) {
+        if (ctx.scope === 'global') {
+            const { skillCount } = await installClaudePlugin(skills, ctx.memtraceBinary);
+            return {
+                agent: 'claude',
+                skillsWritten: skillCount,
+                skillsDir: path.join(os.homedir(), '.claude', 'skills'),
+                mcpConfigPath: path.join(os.homedir(), '.claude', 'settings.json'),
+                mcpRegistered: !ctx.skipMcp,
+                warnings: [],
+            };
+        }
+        // Local scope: write skills into <cwd>/.claude/skills/
+        const skillsDir = path.join(ctx.cwd, '.claude', 'skills');
+        if (fs.existsSync(skillsDir)) {
+            for (const entry of fs.readdirSync(skillsDir)) {
+                if (entry.startsWith('memtrace-')) {
+                    fs.rmSync(path.join(skillsDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
+        let count = 0;
+        for (const skill of skills) {
+            const skillName = skill.filename.replace(/\.md$/, '');
+            const outDir = path.join(skillsDir, skillName);
+            fs.mkdirSync(outDir, { recursive: true });
+            const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+            const content = `---\nname: ${skillName}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
+            fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+            count++;
+        }
+        // MCP for local scope: .mcp.json at project root (Claude's project-level convention)
+        const mcpConfigPath = path.join(ctx.cwd, '.mcp.json');
+        let mcpRegistered = false;
+        if (!ctx.skipMcp) {
+            mcpRegistered = writeClaudeLocalMcp(mcpConfigPath, ctx.memtraceBinary);
+        }
+        return {
+            agent: 'claude',
+            skillsWritten: count,
+            skillsDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings: [],
+        };
+    },
+    async uninstall(ctx) {
+        if (ctx.scope === 'global') {
+            await uninstallClaudePlugin();
+            return;
+        }
+        // Local: remove <cwd>/.claude/skills/memtrace-* and the memtrace entry from <cwd>/.mcp.json
+        const skillsDir = path.join(ctx.cwd, '.claude', 'skills');
+        if (fs.existsSync(skillsDir)) {
+            for (const entry of fs.readdirSync(skillsDir)) {
+                if (entry.startsWith('memtrace-')) {
+                    fs.rmSync(path.join(skillsDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
+        const mcpPath = path.join(ctx.cwd, '.mcp.json');
+        const { value, corrupted } = safeReadJson(mcpPath);
+        if (!corrupted && value?.mcpServers?.['memtrace']) {
+            delete value.mcpServers['memtrace'];
+            if (Object.keys(value.mcpServers).length === 0)
+                delete value.mcpServers;
+            if (Object.keys(value).length === 0)
+                fs.unlinkSync(mcpPath);
+            else
+                writeJsonAtomic(mcpPath, value);
+        }
+    },
+};