memtrace-skills 0.7.10

package/dist/commands/doctor.d.ts

@@ -0,0 +1,16 @@
+export interface AgentReport {
+    agent: string;
+    skillsFound: number;
+    skillsDir: string;
+    mcpRegistered: boolean;
+    mcpConfigPath: string;
+}
+export interface DoctorReport {
+    binaryOk: boolean;
+    binaryPath?: string;
+    binaryVersion?: string;
+    agents: AgentReport[];
+}
+export declare function runDoctorChecks(): Promise<DoctorReport>;
+export declare function formatReport(r: DoctorReport): string;
+export declare function runDoctor(): Promise<number>;

package/dist/commands/doctor.js

@@ -0,0 +1,199 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { commandExists, execCommand } from '../utils.js';
+import { safeReadJson } from '../fs-safe.js';
+import { ALL_TRANSFORMERS } from '../transformers/index.js';
+async function checkBinary() {
+    if (!(await commandExists('memtrace')))
+        return { binaryOk: false };
+    try {
+        const which = process.platform === 'win32' ? 'where memtrace' : 'which memtrace';
+        const binaryPath = (await execCommand(which, { timeoutMs: 3_000 })).split('\n')[0].trim();
+        let binaryVersion;
+        try {
+            binaryVersion = await execCommand('memtrace --version', { timeoutMs: 3_000 });
+        }
+        catch { /* optional */ }
+        return { binaryOk: true, binaryPath, binaryVersion };
+    }
+    catch {
+        return { binaryOk: false };
+    }
+}
+function countMemtraceSkills(dir) {
+    if (!fs.existsSync(dir))
+        return 0;
+    return fs.readdirSync(dir)
+        .filter(e => e.startsWith('memtrace-'))
+        .filter(e => fs.existsSync(path.join(dir, e, 'SKILL.md')))
+        .length;
+}
+function countMemtraceMarkdown(dir) {
+    if (!fs.existsSync(dir))
+        return 0;
+    return fs.readdirSync(dir)
+        .filter(e => e.startsWith('memtrace-') && e.endsWith('.md'))
+        .length;
+}
+function mcpHasMemtrace(file) {
+    const { value } = safeReadJson(file);
+    if (!value)
+        return false;
+    return Boolean(value.mcpServers && value.mcpServers['memtrace']);
+}
+function vscodeMcpHasMemtrace(file) {
+    const { value } = safeReadJson(file);
+    if (!value)
+        return false;
+    return Boolean(value.servers && value.servers['memtrace']);
+}
+function opencodeMcpHasMemtrace(file) {
+    const { value } = safeReadJson(file);
+    if (!value)
+        return false;
+    return Boolean(value.mcp && value.mcp['memtrace']);
+}
+function codexMcpHasMemtrace(file) {
+    if (!fs.existsSync(file))
+        return false;
+    const raw = fs.readFileSync(file, 'utf-8');
+    return /^\s*\[mcp_servers\.(?:"memtrace"|memtrace)\]\s*$/m.test(raw);
+}
+function hermesMcpHasMemtrace(file) {
+    if (!fs.existsSync(file))
+        return false;
+    const raw = fs.readFileSync(file, 'utf-8');
+    return /^mcp_servers:\s*$(?:[\s\S]*?)^\s{2}memtrace:\s*$/m.test(raw);
+}
+function opencodeConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'opencode');
+}
+function vscodeUserMcpPath() {
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'Code', 'User', 'mcp.json');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'Code', 'User', 'mcp.json');
+}
+function checkAgent(agent) {
+    if (agent === 'claude') {
+        const skillsDir = path.join(os.homedir(), '.claude', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.claude', 'settings.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'codex') {
+        const skillsDir = path.join(os.homedir(), '.agents', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.codex', 'config.toml');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: codexMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'windsurf') {
+        const skillsDir = path.join(os.homedir(), '.codeium', 'windsurf', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'vscode') {
+        const skillsDir = path.join(os.homedir(), '.copilot', 'skills');
+        const mcpConfigPath = vscodeUserMcpPath();
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: vscodeMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'hermes') {
+        const skillsDir = path.join(os.homedir(), '.hermes', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.hermes', 'config.yaml');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: hermesMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'opencode') {
+        const skillsDir = path.join(opencodeConfigDir(), 'skills');
+        const mcpConfigPath = path.join(opencodeConfigDir(), 'opencode.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: opencodeMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'kiro') {
+        const skillsDir = path.join(os.homedir(), '.kiro', 'steering');
+        const mcpConfigPath = path.join(os.homedir(), '.kiro', 'settings', 'mcp.json');
+        return {
+            agent,
+            skillsFound: countMemtraceMarkdown(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
+    const mcpConfigPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    return {
+        agent,
+        skillsFound: countMemtraceSkills(skillsDir),
+        skillsDir,
+        mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+        mcpConfigPath,
+    };
+}
+export async function runDoctorChecks() {
+    const binary = await checkBinary();
+    return {
+        ...binary,
+        agents: ALL_TRANSFORMERS.map(t => checkAgent(t.name)),
+    };
+}
+export function formatReport(r) {
+    const lines = [];
+    const check = (ok) => (ok ? '✓' : '✗');
+    lines.push('memtrace doctor');
+    lines.push('───────────────');
+    lines.push(`${check(r.binaryOk)} memtrace binary${r.binaryPath ? '   ' + r.binaryPath : ''}`);
+    if (r.binaryVersion)
+        lines.push(`  version: ${r.binaryVersion}`);
+    for (const a of r.agents) {
+        lines.push(`${check(a.skillsFound > 0)} ${a.agent} skills installed   ${a.skillsFound} in ${a.skillsDir}`);
+        lines.push(`${check(a.mcpRegistered)} ${a.agent} MCP registered      ${a.mcpConfigPath}`);
+    }
+    return lines.join('\n');
+}
+export async function runDoctor() {
+    const report = await runDoctorChecks();
+    console.log(formatReport(report));
+    const healthy = report.binaryOk
+        && report.agents.every(a => a.skillsFound > 0 && a.mcpRegistered);
+    return healthy ? 0 : 1;
+}

package/dist/commands/enterprise-install.d.ts

@@ -0,0 +1,7 @@
+export interface EnterpriseInstallOptions {
+    seedPath: string;
+    scope?: 'global' | 'local';
+    binary?: string;
+    yes?: boolean;
+}
+export declare function runEnterpriseInstall(opts: EnterpriseInstallOptions): Promise<void>;

package/dist/commands/enterprise-install.js

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+import { resolveMemtraceBinary } from './install.js';
+import { registerCursorMcpAt } from '../transformers/cursor.js';
+function loadSeed(seedPath) {
+    const raw = fs.readFileSync(seedPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed.memdb?.database) {
+        throw new Error('seed JSON must include memdb.database');
+    }
+    return parsed;
+}
+function loadWriterToken(seedDir) {
+    const tokPath = path.join(seedDir, 'tokens.plaintext.json');
+    if (!fs.existsSync(tokPath)) {
+        throw new Error(`Missing ${tokPath} — generate bundle via enterprise admin first`);
+    }
+    const tokens = JSON.parse(fs.readFileSync(tokPath, 'utf8'));
+    if (!tokens.writer)
+        throw new Error('tokens.plaintext.json must include writer token');
+    return tokens.writer;
+}
+function resolveLicenseKey(seed, seedDir) {
+    if (seed.license?.key)
+        return seed.license.key;
+    const seedJson = path.join(seedDir, 'seed.json');
+    if (fs.existsSync(seedJson)) {
+        const full = JSON.parse(fs.readFileSync(seedJson, 'utf8'));
+        if (full.license?.key)
+            return full.license.key;
+    }
+    const env = process.env.MEMTRACE_LICENSE_KEY;
+    if (env)
+        return env;
+    throw new Error('License key not found in seed; set MEMTRACE_LICENSE_KEY or include license.key');
+}
+const DEFAULT_AUTH_URL = 'https://www.memtrace.io';
+async function verifySubscriptionWithApi(organizationId, licenseKey) {
+    const base = (process.env.MEMTRACE_AUTH_URL ?? DEFAULT_AUTH_URL).replace(/\/$/, '');
+    const resp = await fetch(`${base}/api/enterprise/install/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ organizationId, licenseKey }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!resp.ok) {
+        const payload = await resp.json().catch(() => ({}));
+        throw new Error(payload.error ?? `Enterprise install blocked (${resp.status})`);
+    }
+    const payload = await resp.json();
+    if (!payload.ok) {
+        throw new Error('Enterprise subscription verification failed');
+    }
+}
+async function validateRemoteEndpoint(endpoint, token) {
+    const url = endpoint.replace(/\/$/, '');
+    // gRPC health is not available from Node without deps; ping via HTTP metrics if exposed.
+    const metricsUrl = url.replace(/:50051$/, ':9090');
+    try {
+        const resp = await fetch(`${metricsUrl}/metrics`, {
+            headers: token ? { Authorization: `Bearer ${token}` } : {},
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!resp.ok) {
+            console.warn(`  ⚠ MemDB metrics at ${metricsUrl} returned ${resp.status} (gRPC may still work)`);
+        }
+        else {
+            console.log(`  ✓ MemDB metrics reachable at ${metricsUrl}`);
+        }
+    }
+    catch (e) {
+        console.warn(`  ⚠ Could not reach MemDB at ${endpoint}: ${e.message}`);
+        console.warn('    Continuing — verify VPN/firewall if remote mode fails at runtime.');
+    }
+}
+function mcpPath(scope) {
+    const base = scope === 'global' ? os.homedir() : process.cwd();
+    return path.join(base, '.cursor', 'mcp.json');
+}
+export async function runEnterpriseInstall(opts) {
+    const seedPath = path.resolve(opts.seedPath);
+    const seedDir = path.dirname(seedPath);
+    const seed = loadSeed(seedPath);
+    const scope = opts.scope ?? 'global';
+    const endpoint = seed.memdb.endpoint ?? process.env.MEMTRACE_MEMDB_ENDPOINT;
+    if (!endpoint) {
+        throw new Error('memdb.endpoint required in seed or MEMTRACE_MEMDB_ENDPOINT env');
+    }
+    const writerToken = loadWriterToken(seedDir);
+    const licenseKey = resolveLicenseKey(seed, seedDir);
+    const binary = opts.binary ?? (await resolveMemtraceBinary()) ?? 'memtrace';
+    console.log('\n  Memtrace Enterprise Installer\n');
+    console.log(`  Org:      ${seed.orgId}`);
+    console.log(`  MemDB:    ${endpoint}`);
+    console.log(`  Database: ${seed.memdb.database}`);
+    console.log(`  Scope:    ${scope}\n`);
+    console.log('  Verifying enterprise subscription…');
+    await verifySubscriptionWithApi(seed.orgId, licenseKey);
+    console.log('  ✓ Subscription active');
+    await validateRemoteEndpoint(endpoint, writerToken);
+    const mcpFile = mcpPath(scope);
+    const { value, corrupted, backupPath } = safeReadJson(mcpFile);
+    if (corrupted) {
+        console.warn(`  ⚠ ${mcpFile} malformed; backed up to ${backupPath}`);
+    }
+    const cfg = (value ?? {});
+    cfg.mcpServers = cfg.mcpServers ?? {};
+    cfg.mcpServers.memtrace = {
+        command: binary,
+        args: ['mcp'],
+        env: {
+            MEMTRACE_LICENSE_KEY: licenseKey,
+            MEMTRACE_MEMDB_MODE: 'external',
+            MEMTRACE_MEMDB_ENDPOINT: endpoint,
+            MEMTRACE_MEMDB_AUTH_TOKEN: writerToken,
+            MEMTRACE_MEMDB_DB: seed.memdb.database,
+            MEMTRACE_WORKSPACE_ROOT: '${workspaceFolder}',
+        },
+    };
+    writeJsonAtomic(mcpFile, cfg);
+    console.log(`  ✓ Wrote enterprise MCP config → ${mcpFile}`);
+    // Also register via cursor helper when file is the standard cursor path
+    if (mcpFile.endsWith('.cursor/mcp.json')) {
+        registerCursorMcpAt(mcpFile, binary);
+    }
+    console.log('\n  Done. Restart Cursor and run `memtrace auth login` if needed.\n');
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,9 @@
+export interface InstallOptions {
+    scope: 'global' | 'local';
+    only?: string[];
+    skipMcp?: boolean;
+    yes?: boolean;
+}
+export declare function resolveMemtraceBinary(): Promise<string | null>;
+export declare function runInstall(options: InstallOptions): Promise<void>;
+export declare function runUninstall(options: InstallOptions): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,104 @@
+import path from 'path';
+import fs from 'fs';
+import { loadSkills } from '../skills.js';
+import { ALL_TRANSFORMERS, findTransformer } from '../transformers/index.js';
+import { commandExists, execCommand } from '../utils.js';
+import { canPrompt, promptForChoices } from './picker.js';
+export async function resolveMemtraceBinary() {
+    if (await commandExists('memtrace'))
+        return 'memtrace';
+    try {
+        const npmBin = await execCommand('npm bin -g', { timeoutMs: 5_000 });
+        const ext = process.platform === 'win32' ? '.exe' : '';
+        const abs = path.join(npmBin.trim(), `memtrace${ext}`);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    catch { /* fall through */ }
+    return null;
+}
+function selectTransformers(options) {
+    if (!options.only || options.only.length === 0)
+        return ALL_TRANSFORMERS;
+    const picks = [];
+    for (const name of options.only) {
+        const t = findTransformer(name);
+        if (!t) {
+            throw new Error(`Unknown agent: ${name}. Known: ${ALL_TRANSFORMERS.map(x => x.name).join(', ')}`);
+        }
+        picks.push(t);
+    }
+    return picks;
+}
+export async function runInstall(options) {
+    console.log('\n  Memtrace Skills Installer\n');
+    // Interactive prompt only when TTY is available and user didn't pre-specify
+    if (!options.yes && (!options.only || options.only.length === 0) && canPrompt()) {
+        const choice = await promptForChoices({ agents: [], scope: options.scope });
+        options.only = choice.agents;
+        options.scope = choice.scope;
+    }
+    const skillsDir = path.resolve(import.meta.dirname, '..', '..', 'skills');
+    const skills = loadSkills(skillsDir);
+    if (skills.length === 0) {
+        console.error('  Error: No skills found. Ensure skills/ directory exists.\n');
+        process.exit(1);
+    }
+    const memtraceBin = await resolveMemtraceBinary();
+    if (memtraceBin === null) {
+        console.warn('  ⚠ memtrace binary not found on PATH.');
+        console.warn('    MCP registration will be skipped for every agent.\n');
+    }
+    const transformers = selectTransformers(options);
+    const ctx = {
+        scope: options.scope,
+        cwd: process.cwd(),
+        memtraceBinary: memtraceBin ?? '',
+        skipMcp: options.skipMcp || memtraceBin === null,
+    };
+    for (const t of transformers) {
+        console.log(`  [${t.name}] installing...`);
+        try {
+            const r = await t.install(skills, ctx);
+            console.log(`  [${t.name}] ✓ ${r.skillsWritten} skills → ${r.skillsDir}`);
+            if (r.mcpRegistered)
+                console.log(`  [${t.name}] ✓ MCP registered`);
+            else if (ctx.skipMcp)
+                console.log(`  [${t.name}] (MCP skipped)`);
+            else
+                console.log(`  [${t.name}] ⚠ MCP registration failed`);
+            for (const w of r.warnings)
+                console.warn(`  [${t.name}] warn: ${w}`);
+        }
+        catch (e) {
+            console.error(`  [${t.name}] ✗ install failed: ${e.message}`);
+        }
+    }
+    // Auto health check — never affects install exit code
+    try {
+        const { runDoctorChecks, formatReport } = await import('./doctor.js');
+        const report = await runDoctorChecks();
+        console.log('\n' + formatReport(report));
+    }
+    catch { /* doctor failures never break install */ }
+    console.log('\n  Done.\n');
+}
+export async function runUninstall(options) {
+    console.log('\n  Removing Memtrace skills...\n');
+    const transformers = selectTransformers(options);
+    const ctx = {
+        scope: options.scope,
+        cwd: process.cwd(),
+        memtraceBinary: '',
+    };
+    for (const t of transformers) {
+        try {
+            await t.uninstall(ctx);
+            console.log(`  [${t.name}] removed`);
+        }
+        catch (e) {
+            console.warn(`  [${t.name}] uninstall failed: ${e.message}`);
+        }
+    }
+    console.log('\n  Done.\n');
+}

package/dist/commands/picker.d.ts

@@ -0,0 +1,6 @@
+export interface PickerResult {
+    agents: string[];
+    scope: 'global' | 'local';
+}
+export declare function canPrompt(): boolean;
+export declare function promptForChoices(defaults: PickerResult): Promise<PickerResult>;

package/dist/commands/picker.js

@@ -0,0 +1,22 @@
+import readline from 'readline';
+import { ALL_TRANSFORMERS } from '../transformers/index.js';
+export function canPrompt() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+export async function promptForChoices(defaults) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+    console.log('\n  Agents available:');
+    for (const t of ALL_TRANSFORMERS)
+        console.log(`    - ${t.name}`);
+    const agentsInput = await ask(`\n  Install for which agents? (comma-separated, default: all) `);
+    const agents = agentsInput.trim()
+        ? agentsInput.split(',').map(s => s.trim()).filter(Boolean)
+        : ALL_TRANSFORMERS.map(t => t.name);
+    const defaultScope = defaults.scope;
+    const scopeInput = await ask(`  Scope? [global/local] (default: ${defaultScope}) `);
+    const typed = scopeInput.trim().toLowerCase();
+    const scope = typed === 'local' ? 'local' : typed === 'global' ? 'global' : defaultScope;
+    rl.close();
+    return { agents, scope };
+}

package/dist/commands/rail-install.d.ts

@@ -0,0 +1,7 @@
+export interface RailInstallOptions {
+    /** Explicit memtrace binary (from `memtrace rail enable`); wins over PATH lookup. */
+    binary?: string;
+    scope?: 'global' | 'local';
+}
+export declare function runInstallRail(options?: RailInstallOptions): Promise<void>;
+export declare function runUninstallRail(options?: RailInstallOptions): Promise<void>;

package/dist/commands/rail-install.js

@@ -0,0 +1,37 @@
+import { resolveMemtraceBinary } from './install.js';
+import { installRailHooks, printRailInstallSummary, uninstallRailHooks, } from '../rail-install.js';
+export async function runInstallRail(options = {}) {
+    const memtraceBin = options.binary?.trim() ||
+        (await resolveMemtraceBinary()) ||
+        '';
+    if (!memtraceBin) {
+        console.error('  Error: memtrace binary not found. Pass --binary or ensure memtrace is on PATH.\n');
+        process.exit(1);
+    }
+    const ctx = {
+        scope: options.scope ?? 'global',
+        cwd: process.cwd(),
+        memtraceBinary: memtraceBin,
+        skipMcp: true,
+    };
+    const results = installRailHooks(ctx);
+    printRailInstallSummary(results, 'installed');
+    const wired = results.filter((r) => r.registered).map((r) => r.host);
+    if (wired.length > 0) {
+        console.log('  Next steps:');
+        console.log('    1. memtrace start          (daemon for find_code)');
+        console.log('    2. Reload your IDE         (Cursor: reload window; Claude: new session)');
+        console.log('    3. Shell-based search      (Cursor native Grep is not hooked)\n');
+    }
+}
+export async function runUninstallRail(options = {}) {
+    const ctx = {
+        scope: options.scope ?? 'global',
+        cwd: process.cwd(),
+        memtraceBinary: options.binary?.trim() ?? '',
+        skipMcp: true,
+    };
+    const results = uninstallRailHooks(ctx);
+    printRailInstallSummary(results, 'removed');
+    console.log('');
+}

package/dist/fs-safe.d.ts

@@ -0,0 +1,21 @@
+export interface SafeReadResult<T> {
+    /** Parsed value, or null if file missing or corrupt. */
+    value: T | null;
+    /** True if the file existed but failed to parse. */
+    corrupted: boolean;
+    /** Path to the backup copy, if we made one. */
+    backupPath?: string;
+}
+/**
+ * Read and JSON-parse a file without ever silently losing data.
+ * On parse failure, copies the file to <path>.corrupt-<ISO-timestamp>
+ * and returns { value: null, corrupted: true, backupPath }.
+ * Caller is responsible for deciding whether to proceed with writes.
+ */
+export declare function safeReadJson<T = unknown>(filePath: string): SafeReadResult<T>;
+/**
+ * Write JSON atomically: write to a sibling .tmp file, then rename.
+ * Rename is atomic on POSIX and good enough on Windows for config files.
+ * Creates parent directories as needed.
+ */
+export declare function writeJsonAtomic(filePath: string, data: unknown): void;

package/dist/fs-safe.js

@@ -0,0 +1,35 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Read and JSON-parse a file without ever silently losing data.
+ * On parse failure, copies the file to <path>.corrupt-<ISO-timestamp>
+ * and returns { value: null, corrupted: true, backupPath }.
+ * Caller is responsible for deciding whether to proceed with writes.
+ */
+export function safeReadJson(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return { value: null, corrupted: false };
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    try {
+        return { value: JSON.parse(raw), corrupted: false };
+    }
+    catch {
+        const iso = new Date().toISOString().replace(/[:.]/g, '-');
+        const backupPath = `${filePath}.corrupt-${iso}`;
+        fs.copyFileSync(filePath, backupPath);
+        return { value: null, corrupted: true, backupPath };
+    }
+}
+/**
+ * Write JSON atomically: write to a sibling .tmp file, then rename.
+ * Rename is atomic on POSIX and good enough on Windows for config files.
+ * Creates parent directories as needed.
+ */
+export function writeJsonAtomic(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    const payload = JSON.stringify(data, null, 2) + '\n';
+    fs.writeFileSync(tmpPath, payload);
+    fs.renameSync(tmpPath, filePath);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};