memtrace-skills 0.7.10

package/dist/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { runInstall, runUninstall } from './commands/install.js';
+import { runDoctor } from './commands/doctor.js';
+import { runInstallRail, runUninstallRail } from './commands/rail-install.js';
+import { runEnterpriseInstall } from './commands/enterprise-install.js';
+const program = new Command();
+program
+    .name('memtrace-skills')
+    .description('Install Memtrace skills and MCP for AI coding agents')
+    .version('0.1.0');
+function parseOnly(val) {
+    return val.split(',').map(s => s.trim()).filter(Boolean);
+}
+program
+    .command('install')
+    .description('Install memtrace skills and register MCP for selected agents')
+    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,gemini,windsurf,vscode,hermes,opencode,kiro)', parseOnly)
+    .option('--local', 'install into the current project where the selected agent supports project scope', false)
+    .option('--global', 'install globally (~/.claude/, ~/.cursor/, ~/.agents/) [default]', false)
+    .option('--skip-mcp', 'write skills only, skip MCP server registration', false)
+    .option('--repair', 'alias for install — run after fixing a corrupt settings file')
+    .option('-y, --yes', 'non-interactive, accept defaults')
+    .action(async (opts) => {
+    const options = {
+        scope: opts.local ? 'local' : 'global',
+        only: opts.only,
+        skipMcp: opts.skipMcp,
+        yes: opts.yes,
+    };
+    await runInstall(options);
+});
+program
+    .command('doctor')
+    .description('Check memtrace install health across all agents')
+    .action(async () => {
+    process.exit(await runDoctor());
+});
+program
+    .command('uninstall')
+    .description('Remove memtrace skills and MCP registrations')
+    .option('--only <agents>', 'comma-separated agent names', parseOnly)
+    .option('--local', 'uninstall from the current project', false)
+    .action(async (opts) => {
+    await runUninstall({
+        scope: opts.local ? 'local' : 'global',
+        only: opts.only,
+    });
+});
+program
+    .command('install-enterprise')
+    .description('Configure Memtrace MCP for self-hosted enterprise MemDB (remote mode)')
+    .requiredOption('--seed <path>', 'path to enterprise seed.json from your admin bundle')
+    .option('--local', 'write MCP config to the current project', false)
+    .option('--binary <path>', 'memtrace executable (default: on PATH)')
+    .option('-y, --yes', 'non-interactive')
+    .action(async (opts) => {
+    await runEnterpriseInstall({
+        seedPath: opts.seed,
+        scope: opts.local ? 'local' : 'global',
+        binary: opts.binary,
+        yes: opts.yes,
+    });
+});
+program
+    .command('install-rail')
+    .description('Wire Memtrace Rail discovery hooks for Claude, Cursor, Codex, Gemini, OpenCode')
+    .option('--binary <path>', 'memtrace executable (default: on PATH)')
+    .option('--local', 'project-scoped paths where supported', false)
+    .action(async (opts) => {
+    await runInstallRail({
+        binary: opts.binary,
+        scope: opts.local ? 'local' : 'global',
+    });
+});
+program
+    .command('uninstall-rail')
+    .description('Remove Memtrace Rail hooks only (not skills/MCP)')
+    .option('--local', 'project-scoped paths where supported', false)
+    .action(async (opts) => {
+    await runUninstallRail({ scope: opts.local ? 'local' : 'global' });
+});
+// Default: `memtrace-skills` with no subcommand → install with defaults (global, all agents)
+program.action(async () => {
+    await runInstall({ scope: 'global' });
+});
+program.parse();

package/dist/rail-install.d.ts

@@ -0,0 +1,20 @@
+import type { InstallContext } from './transformers/types.js';
+export interface RailHostResult {
+    host: string;
+    registered: boolean;
+    path?: string;
+    skipped?: string;
+}
+/** Hosts with no Rail hook surface yet (MCP/skills only). */
+export declare const RAIL_UNSUPPORTED: ReadonlyArray<{
+    host: string;
+    reason: string;
+}>;
+/**
+ * Wire Rail discovery hooks for Claude, Cursor, Codex, Gemini, and OpenCode.
+ * Idempotent. Does not install skills or MCP — hooks only.
+ */
+export declare function installRailHooks(ctx: InstallContext): RailHostResult[];
+/** Remove only Memtrace-owned Rail hook entries (not skills/MCP). */
+export declare function uninstallRailHooks(ctx: InstallContext): RailHostResult[];
+export declare function printRailInstallSummary(results: RailHostResult[], action: 'installed' | 'removed'): void;

package/dist/rail-install.js

@@ -0,0 +1,183 @@
+/**
+ * Memtrace Rail hook wiring for every host that supports discovery interception.
+ * Called from `memtrace rail enable` (via `install-rail` CLI) and from full
+ * `memtrace install` (per-transformer, same helpers).
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { registerRailHookInSettingsAt, removeRailHookFromSettingsAt, } from './transformers/claude.js';
+import { geminiSettingsPath } from './transformers/gemini.js';
+import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodePluginSource, } from './transformers/rail-hooks.js';
+/** Hosts with no Rail hook surface yet (MCP/skills only). */
+export const RAIL_UNSUPPORTED = [
+    { host: 'hermes', reason: 'Hermes pre_tool_call adapter not wired yet' },
+    { host: 'kiro', reason: 'Kiro IDE hooks omit tool stdin (CLI-only for now)' },
+];
+function codexHooksPath(ctx) {
+    const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
+    return path.join(base, 'hooks.json');
+}
+function cursorHooksPath(ctx) {
+    const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
+    return path.join(base, '.cursor', 'hooks.json');
+}
+function opencodeConfigDir(ctx) {
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return ctx.scope === 'global' ? path.join(xdg, 'opencode') : path.join(ctx.cwd, '.opencode');
+}
+function opencodeRailPluginPaths(ctx) {
+    const base = opencodeConfigDir(ctx);
+    return [
+        path.join(base, 'plugin', 'memtrace-rail.js'),
+        path.join(base, 'plugins', 'memtrace-rail.js'),
+    ];
+}
+/**
+ * Wire Rail discovery hooks for Claude, Cursor, Codex, Gemini, and OpenCode.
+ * Idempotent. Does not install skills or MCP — hooks only.
+ */
+export function installRailHooks(ctx) {
+    const bin = ctx.memtraceBinary?.trim() ?? '';
+    if (!bin) {
+        throw new Error('memtrace binary path is required to install Rail hooks');
+    }
+    const results = [];
+    const claudePath = path.join(os.homedir(), '.claude', 'settings.json');
+    const claude = registerRailHookInSettingsAt(claudePath, bin);
+    results.push({
+        host: 'claude',
+        registered: claude.registered,
+        path: claudePath,
+        skipped: claude.registered ? undefined : 'settings.json malformed or unreadable',
+    });
+    const cursorPath = cursorHooksPath(ctx);
+    const cursor = registerCursorRailHook(cursorPath, bin);
+    results.push({
+        host: 'cursor',
+        registered: cursor.registered,
+        path: cursorPath,
+        skipped: cursor.registered ? undefined : 'hooks.json malformed or unreadable',
+    });
+    const codexPath = codexHooksPath(ctx);
+    const codex = registerSettingsHook(codexPath, bin, 'codex', 'PreToolUse', CODEX_MATCHER);
+    results.push({
+        host: 'codex',
+        registered: codex.registered,
+        path: codexPath,
+        skipped: codex.registered ? undefined : 'hooks.json malformed or unreadable',
+    });
+    const geminiPath = geminiSettingsPath(ctx);
+    const gemini = registerSettingsHook(geminiPath, bin, 'gemini', 'BeforeTool', GEMINI_MATCHER, {
+        enableHooks: true,
+        enableMessageBusIntegration: true,
+    });
+    results.push({
+        host: 'gemini',
+        registered: gemini.registered,
+        path: geminiPath,
+        skipped: gemini.registered ? undefined : 'settings.json malformed or unreadable',
+    });
+    try {
+        const src = openCodePluginSource(bin);
+        for (const pluginPath of opencodeRailPluginPaths(ctx)) {
+            fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+            fs.writeFileSync(pluginPath, src);
+        }
+        results.push({
+            host: 'opencode',
+            registered: true,
+            path: opencodeRailPluginPaths(ctx)[0],
+        });
+    }
+    catch (e) {
+        results.push({
+            host: 'opencode',
+            registered: false,
+            skipped: e.message,
+        });
+    }
+    const windsurfPath = windsurfHooksPath();
+    fs.mkdirSync(path.dirname(windsurfPath), { recursive: true });
+    const windsurf = registerWindsurfRailHook(windsurfPath, bin);
+    results.push({
+        host: 'windsurf',
+        registered: windsurf.registered,
+        path: windsurfPath,
+        skipped: windsurf.registered ? undefined : 'hooks.json malformed or unreadable',
+    });
+    const vscodePath = vscodeCopilotRailHookPath();
+    fs.mkdirSync(path.dirname(vscodePath), { recursive: true });
+    const vscode = registerVsCodeRailHook(vscodePath, bin);
+    results.push({
+        host: 'vscode',
+        registered: vscode.registered,
+        path: vscodePath,
+        skipped: vscode.registered ? undefined : 'hook file malformed or unreadable',
+    });
+    for (const { host, reason } of RAIL_UNSUPPORTED) {
+        results.push({ host, registered: false, skipped: reason });
+    }
+    return results;
+}
+/** Remove only Memtrace-owned Rail hook entries (not skills/MCP). */
+export function uninstallRailHooks(ctx) {
+    const results = [];
+    const claudePath = path.join(os.homedir(), '.claude', 'settings.json');
+    const claude = removeRailHookFromSettingsAt(claudePath);
+    results.push({ host: 'claude', registered: false, path: claudePath, skipped: claude.changed ? undefined : 'no rail hook' });
+    const cursorPath = cursorHooksPath(ctx);
+    const cursor = removeCursorRailHook(cursorPath);
+    results.push({ host: 'cursor', registered: false, path: cursorPath, skipped: cursor.changed ? undefined : 'no rail hook' });
+    const codexPath = codexHooksPath(ctx);
+    const codex = removeSettingsHook(codexPath, 'PreToolUse');
+    results.push({ host: 'codex', registered: false, path: codexPath, skipped: codex.changed ? undefined : 'no rail hook' });
+    const geminiPath = geminiSettingsPath(ctx);
+    const gemini = removeSettingsHook(geminiPath, 'BeforeTool');
+    results.push({ host: 'gemini', registered: false, path: geminiPath, skipped: gemini.changed ? undefined : 'no rail hook' });
+    for (const p of opencodeRailPluginPaths(ctx)) {
+        try {
+            fs.rmSync(p, { force: true });
+        }
+        catch { /* best effort */ }
+    }
+    results.push({ host: 'opencode', registered: false });
+    const windsurfPath = windsurfHooksPath();
+    const windsurf = removeWindsurfRailHook(windsurfPath);
+    results.push({
+        host: 'windsurf',
+        registered: false,
+        path: windsurfPath,
+        skipped: windsurf.changed ? undefined : 'no rail hook',
+    });
+    const vscodePath = vscodeCopilotRailHookPath();
+    const vscode = removeVsCodeRailHook(vscodePath);
+    results.push({
+        host: 'vscode',
+        registered: false,
+        path: vscodePath,
+        skipped: vscode.changed ? undefined : 'no rail hook',
+    });
+    for (const { host, reason } of RAIL_UNSUPPORTED) {
+        results.push({ host, registered: false, skipped: reason });
+    }
+    return results;
+}
+export function printRailInstallSummary(results, action) {
+    console.log(`\n  Memtrace Rail hooks ${action}:\n`);
+    for (const r of results) {
+        if (r.registered && action === 'installed') {
+            console.log(`    \x1b[32m✓\x1b[0m ${r.host}${r.path ? ` → ${r.path}` : ''}`);
+        }
+        else if (action === 'removed' && r.skipped === undefined) {
+            console.log(`    \x1b[32m✓\x1b[0m ${r.host} (removed)`);
+        }
+        else if (r.skipped) {
+            console.log(`    \x1b[2m–\x1b[0m ${r.host}: ${r.skipped}`);
+        }
+        else {
+            console.log(`    \x1b[33m!\x1b[0m ${r.host}: not ${action}${r.path ? ` (${r.path})` : ''}`);
+        }
+    }
+    console.log('');
+}

package/dist/skills.d.ts

@@ -0,0 +1,17 @@
+export interface SkillFrontmatter {
+    name?: string;
+    description: string;
+    'allowed-tools'?: string[];
+    'user-invocable'?: boolean;
+}
+export interface Skill {
+    filename: string;
+    category: 'commands' | 'workflows';
+    frontmatter: SkillFrontmatter;
+    body: string;
+    raw: string;
+}
+/**
+ * Load all skills from a skills directory (expects commands/ and workflows/ subdirs).
+ */
+export declare function loadSkills(skillsDir: string): Skill[];

package/dist/skills.js

@@ -0,0 +1,64 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Parse YAML-ish frontmatter from a skill markdown file.
+ * Handles the subset of YAML used in skill files (no nested objects).
+ */
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match)
+        return null;
+    const frontmatterRaw = match[1];
+    const body = match[2];
+    const frontmatter = {};
+    // Parse description
+    const descMatch = frontmatterRaw.match(/^description:\s*"?(.*?)"?\s*$/m);
+    if (descMatch)
+        frontmatter.description = descMatch[1];
+    // Parse name
+    const nameMatch = frontmatterRaw.match(/^name:\s*(.+)$/m);
+    if (nameMatch)
+        frontmatter.name = nameMatch[1].trim();
+    // Parse user-invocable
+    const invocableMatch = frontmatterRaw.match(/^user-invocable:\s*(.+)$/m);
+    if (invocableMatch)
+        frontmatter['user-invocable'] = invocableMatch[1].trim() === 'true';
+    // Parse allowed-tools (YAML list)
+    const toolsMatch = frontmatterRaw.match(/^allowed-tools:\n((?:\s+-\s+.+\n?)+)/m);
+    if (toolsMatch) {
+        frontmatter['allowed-tools'] = toolsMatch[1]
+            .split('\n')
+            .map(line => line.replace(/^\s+-\s+/, '').trim())
+            .filter(Boolean);
+    }
+    return { frontmatter, body };
+}
+/**
+ * Load all skills from a skills directory (expects commands/ and workflows/ subdirs).
+ */
+export function loadSkills(skillsDir) {
+    const skills = [];
+    for (const category of ['commands', 'workflows']) {
+        const categoryDir = path.join(skillsDir, category);
+        if (!fs.existsSync(categoryDir))
+            continue;
+        for (const file of fs.readdirSync(categoryDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            const raw = fs.readFileSync(path.join(categoryDir, file), 'utf-8');
+            const parsed = parseFrontmatter(raw);
+            if (!parsed || !parsed.frontmatter.description) {
+                console.warn(`Warning: could not parse frontmatter for ${file}, skipping`);
+                continue;
+            }
+            skills.push({
+                filename: file,
+                category,
+                frontmatter: parsed.frontmatter,
+                body: parsed.body,
+                raw,
+            });
+        }
+    }
+    return skills;
+}

package/dist/transformers/claude.d.ts

@@ -0,0 +1,71 @@
+import { Skill } from '../skills.js';
+import { Transformer, TransformResult } from './types.js';
+/**
+ * Transform a skill into Claude Code plugin format.
+ * Each skill becomes a directory with SKILL.md inside skills/<skill-name>/
+ */
+export declare function transformForClaude(skill: Skill): TransformResult[];
+/**
+ * Fallback cache directory when the CLI install didn't create one.
+ */
+export declare function getClaudePluginCacheDir(): string;
+export interface SettingsMutationResult {
+    registered: boolean;
+    backupPath?: string;
+}
+/**
+ * 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 declare function registerMcpInSettingsAt(settingsPath: string, memtraceBinary: string): SettingsMutationResult;
+/**
+ * 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 declare function registerRailHookInSettingsAt(settingsPath: string, memtraceBinary: string): SettingsMutationResult;
+/**
+ * Remove the Memtrace Rail PreToolUse hook from a Claude settings.json.
+ * Preserves unrelated hooks; prunes empty containers. Never touches a
+ * malformed file.
+ */
+export declare function removeRailHookFromSettingsAt(settingsPath: string): SettingsCleanupResult;
+/**
+ * Merge-add plugin + marketplace entries into a Claude settings.json file.
+ * Never overwrites a malformed file.
+ */
+export declare function enablePluginInSettingsAt(settingsPath: string): SettingsMutationResult;
+export interface SettingsCleanupResult {
+    changed: boolean;
+    backupPath?: string;
+}
+/**
+ * Remove every Claude settings entry Memtrace may have written across
+ * installer versions and Claude marketplace schema changes.
+ */
+export declare function removeClaudeSettingsEntriesAt(settingsPath: string): SettingsCleanupResult;
+/**
+ * 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 declare function installClaudePlugin(skills: Skill[], memtraceBinaryPath: string): Promise<{
+    cacheDir: string;
+    skillCount: number;
+}>;
+/**
+ * Remove the Claude Code plugin and MCP server registration.
+ */
+export declare function uninstallClaudePlugin(): Promise<void>;
+export declare const claudeTransformer: Transformer;