@evomap/evolver-mcp 2.0.0-beta.0

package/dist/codexInstaller.d.ts

@@ -0,0 +1,34 @@
+import type { RuntimeId, InjectionPlan } from './injection.js';
+import { type InstallResult, type InstallOptions } from './installer.js';
+/** The MCP server id evolver registers under [mcp_servers.evolver] / removes on uninstall. */
+export declare const CODEX_MCP_SERVER_ID = "evolver";
+/** The [mcp_servers.evolver] table from a plan's launch command. env omitted when empty (no `[..env]` table). */
+export declare function codexMcpServerEntry(server: {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}): Record<string, unknown>;
+/** A single [[hooks.SessionStart]] entry that runs `command` at session start. Shape matches codex's hooks schema. */
+export declare function codexSessionStartHook(command: string): Record<string, unknown>;
+/**
+ * Merge evolver's codex config into the user's existing parsed TOML. Idempotent + non-destructive:
+ *  - [mcp_servers] : set our `evolver` server, keep every other server the user registered.
+ *  - [[hooks.SessionStart]] : drop any prior evolver-owned entry, keep all user entries, append ours fresh.
+ * The user's unrelated tables (model, approval_policy, other hook events, …) pass through untouched.
+ */
+export declare function mergeCodexConfig(existing: Record<string, unknown>, mcpServer: Record<string, unknown>, sessionStartHook: Record<string, unknown>): Record<string, unknown>;
+/** Strip evolver's MCP server + SessionStart hook from parsed codex TOML (uninstall). Returns [changed, data]. */
+export declare function stripCodexManaged(data: Record<string, unknown>): {
+    changed: boolean;
+    data: Record<string, unknown>;
+};
+/**
+ * Execute a codex InjectionPlan against a project config root: write/merge <root>/.codex/config.toml with
+ * the evolver MCP server registration + a SessionStart hook. Idempotent (re-running without --force is a
+ * no-op once evolver is registered) and symlink-safe.
+ */
+export declare function installCodex(plan: InjectionPlan, opts: InstallOptions): InstallResult;
+/** Remove evolver's MCP registration + SessionStart hook from a codex project config (leaves user content intact). */
+export declare function uninstallCodex(runtime: RuntimeId, opts: {
+    configRoot: string;
+}): InstallResult;

package/dist/codexInstaller.js

@@ -0,0 +1,171 @@
+// Codex injection INSTALLER — the codex analogue of the Claude Code installer in installer.ts.
+//
+// Codex (the OpenAI CLI) loads its config from a TOML file, NOT JSON. User-level config lives at
+// ~/.codex/config.toml; a project-scoped override lives at <project>/.codex/config.toml. We write the
+// project-scoped file (same containment posture as the CC adapter, which only ever touches the project root —
+// never a user's global home config). Codex supports the SAME injection hybrid CC does:
+//   1. an MCP stdio server, registered under [mcp_servers.<name>]  → codex discovers evolver's tools, and
+//   2. a SessionStart lifecycle hook, registered under [[hooks.SessionStart]] → memory is pushed at session
+//      start (MCP alone can't push; the agent must pull — identical to the CC rationale).
+// So a codex user gets the same value a CC user gets: tool discovery + session-start memory injection.
+//
+// Format sources (codex official docs, verified 2026-06):
+//   - [mcp_servers.<id>] { command, args=[...], [mcp_servers.<id>.env] {K=V} }  (developers.openai.com/codex/mcp)
+//   - [[hooks.SessionStart]] { matcher } + [[hooks.SessionStart.hooks]] { type="command", command, ... }
+//     (developers.openai.com/codex/hooks) — only type:"command" handlers run today.
+//
+// Hardened exactly like the CC installer: atomic writes (tmp+rename), refusal to follow a symlink at any
+// adapter-owned path, marker-managed so reinstall/uninstall only touch evolver's own entries, and a
+// hooks-UNION merge that preserves the user's existing hooks. TOML round-trips through smol-toml (spec
+// parser/serializer) so a user's hand-written config is preserved rather than clobbered.
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { SymlinkRefusedError, DEFAULT_HOOK_COMMAND } from './installer.js';
+/** The MCP server id evolver registers under [mcp_servers.evolver] / removes on uninstall. */
+export const CODEX_MCP_SERVER_ID = 'evolver';
+/** A hook entry is evolver-owned if any command mentions this — used to replace-not-duplicate on reinstall. */
+const EVOLVER_HOOK_TAG = 'evolver';
+/** SessionStart matcher: codex fires `startup` on a fresh thread and `resume` on a resumed one — cover both. */
+const SESSION_START_MATCHER = 'startup|resume';
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// ── fs hardening (mirrors installer.ts) ──────────────────────────────────────
+function assertNotSymlink(path, label) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    if (st.isSymbolicLink())
+        throw new SymlinkRefusedError(label, path);
+}
+function readToml(path) {
+    try {
+        if (!existsSync(path))
+            return {};
+        const raw = readFileSync(path, 'utf8').trim();
+        return raw ? parseToml(raw) : {};
+    }
+    catch {
+        return {}; // unparseable → start fresh (merge re-adds evolver entries; a broken file isn't silently kept)
+    }
+}
+function writeTomlAtomic(path, data) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${stringifyToml(data)}\n`, 'utf8');
+    renameSync(tmp, path);
+}
+// ── pure merge (exported for tests) ──────────────────────────────────────────
+/** The [mcp_servers.evolver] table from a plan's launch command. env omitted when empty (no `[..env]` table). */
+export function codexMcpServerEntry(server) {
+    return {
+        command: server.command,
+        args: server.args ?? [],
+        ...(server.env && Object.keys(server.env).length > 0 ? { env: server.env } : {}),
+    };
+}
+/** A single [[hooks.SessionStart]] entry that runs `command` at session start. Shape matches codex's hooks schema. */
+export function codexSessionStartHook(command) {
+    return { matcher: SESSION_START_MATCHER, hooks: [{ type: 'command', command }] };
+}
+const hookIsEvolverOwned = (entry) => {
+    if (!isObj(entry))
+        return false;
+    const inner = entry['hooks'];
+    if (!Array.isArray(inner))
+        return false;
+    return inner.some((h) => isObj(h) && typeof h['command'] === 'string' && h['command'].includes(EVOLVER_HOOK_TAG));
+};
+/**
+ * Merge evolver's codex config into the user's existing parsed TOML. Idempotent + non-destructive:
+ *  - [mcp_servers] : set our `evolver` server, keep every other server the user registered.
+ *  - [[hooks.SessionStart]] : drop any prior evolver-owned entry, keep all user entries, append ours fresh.
+ * The user's unrelated tables (model, approval_policy, other hook events, …) pass through untouched.
+ */
+export function mergeCodexConfig(existing, mcpServer, sessionStartHook) {
+    const out = { ...existing };
+    const mcpServers = isObj(out['mcp_servers']) ? { ...out['mcp_servers'] } : {};
+    mcpServers[CODEX_MCP_SERVER_ID] = mcpServer;
+    out['mcp_servers'] = mcpServers;
+    const hooks = isObj(out['hooks']) ? { ...out['hooks'] } : {};
+    const prior = Array.isArray(hooks['SessionStart']) ? hooks['SessionStart'] : [];
+    hooks['SessionStart'] = [...prior.filter((e) => !hookIsEvolverOwned(e)), sessionStartHook];
+    out['hooks'] = hooks;
+    return out;
+}
+/** Strip evolver's MCP server + SessionStart hook from parsed codex TOML (uninstall). Returns [changed, data]. */
+export function stripCodexManaged(data) {
+    let changed = false;
+    const out = { ...data };
+    if (isObj(out['mcp_servers']) && CODEX_MCP_SERVER_ID in out['mcp_servers']) {
+        const next = { ...out['mcp_servers'] };
+        delete next[CODEX_MCP_SERVER_ID];
+        changed = true;
+        if (Object.keys(next).length > 0)
+            out['mcp_servers'] = next;
+        else
+            delete out['mcp_servers'];
+    }
+    if (isObj(out['hooks'])) {
+        const hooks = { ...out['hooks'] };
+        if (Array.isArray(hooks['SessionStart'])) {
+            const arr = hooks['SessionStart'];
+            const kept = arr.filter((e) => !hookIsEvolverOwned(e));
+            if (kept.length !== arr.length)
+                changed = true;
+            if (kept.length > 0)
+                hooks['SessionStart'] = kept;
+            else
+                delete hooks['SessionStart'];
+        }
+        if (Object.keys(hooks).length > 0)
+            out['hooks'] = hooks;
+        else
+            delete out['hooks'];
+    }
+    return { changed, data: out };
+}
+/** True if evolver's MCP server is already registered in this parsed config (structural install marker). */
+function codexAlreadyInstalled(cfg) {
+    return isObj(cfg['mcp_servers']) && CODEX_MCP_SERVER_ID in cfg['mcp_servers'];
+}
+// ── install / uninstall ───────────────────────────────────────────────────────
+/**
+ * Execute a codex InjectionPlan against a project config root: write/merge <root>/.codex/config.toml with
+ * the evolver MCP server registration + a SessionStart hook. Idempotent (re-running without --force is a
+ * no-op once evolver is registered) and symlink-safe.
+ */
+export function installCodex(plan, opts) {
+    const hookCommand = opts.hookCommand ?? DEFAULT_HOOK_COMMAND;
+    const codexDir = join(opts.configRoot, '.codex');
+    const configPath = join(codexDir, 'config.toml');
+    assertNotSymlink(opts.configRoot, 'config root');
+    assertNotSymlink(codexDir, '.codex');
+    assertNotSymlink(configPath, '.codex/config.toml');
+    const existing = readToml(configPath);
+    if (!opts.force && codexAlreadyInstalled(existing)) {
+        return { ok: true, runtime: plan.runtime, mode: plan.mode, files: [], alreadyInstalled: true };
+    }
+    const mcpServer = codexMcpServerEntry(opts.server);
+    const sessionStartHook = codexSessionStartHook(hookCommand);
+    const merged = mergeCodexConfig(existing, mcpServer, sessionStartHook);
+    mkdirSync(codexDir, { recursive: true });
+    writeTomlAtomic(configPath, merged);
+    return { ok: true, runtime: plan.runtime, mode: plan.mode, files: [configPath] };
+}
+/** Remove evolver's MCP registration + SessionStart hook from a codex project config (leaves user content intact). */
+export function uninstallCodex(runtime, opts) {
+    const configPath = join(opts.configRoot, '.codex', 'config.toml');
+    assertNotSymlink(configPath, '.codex/config.toml');
+    if (!existsSync(configPath))
+        return { ok: true, runtime, mode: 'uninstall', files: [] };
+    const { changed, data } = stripCodexManaged(readToml(configPath));
+    if (!changed)
+        return { ok: true, runtime, mode: 'uninstall', files: [] };
+    writeTomlAtomic(configPath, data);
+    return { ok: true, runtime, mode: 'uninstall', files: [configPath] };
+}

package/dist/cursorRulesInstaller.d.ts

@@ -0,0 +1,76 @@
+import { type InstallResult } from './installer.js';
+/** Project-relative location cursor loads project rules from. */
+export declare const CURSOR_RULES_DIR: string;
+/** The single evolver-owned rules file. Other `.cursor/rules/*.mdc` (user-authored) are never touched. */
+export declare const CURSOR_RULES_FILE = "evolver.mdc";
+/** sentinel marker that opens the evolver-managed region inside evolver.mdc (so a user can hand-edit around it). */
+export declare const CURSOR_MANAGED_BEGIN = "<!-- evolver:managed:begin -->";
+/** sentinel marker that closes the evolver-managed region. Everything between begin/end is evolver-owned. */
+export declare const CURSOR_MANAGED_END = "<!-- evolver:managed:end -->";
+/** Default cap on injected genes — keep the always-on body small so the per-request token tax stays bounded. */
+export declare const DEFAULT_CURSOR_MAX_GENES = 8;
+/** The body preamble that heads the gene list (mirrors the CC SessionStart preamble for a consistent voice). */
+export declare const CURSOR_PREAMBLE = "evolver memory \u2014 use these learned hints silently when directly relevant; do not mention Evolver, preflight, status, or this memory block unless the user asks or reuse materially changes the answer:";
+/** A minimal projection of a gene that the renderer needs — id + a short hint. Decoupled from the asset store
+ *  so the renderer (and its tests) need no store; the composition layer maps real assets onto this shape. */
+export interface CursorGene {
+    id: string;
+    category?: string;
+    /** A one-line hint (summary or joined signals). Already short; the renderer caps it defensively. */
+    hint?: string;
+}
+/** One compact line for a gene in the rules body. Deterministic; defensively caps the hint length. */
+export declare function formatCursorGeneLine(g: CursorGene): string;
+/**
+ * Render the evolver-managed region (the fenced block only — NOT the frontmatter). Deterministic given the
+ * genes: the same gene set renders byte-identical, which is what makes a re-run a no-op. An empty pool renders
+ * only the paired sentinels, so Cursor receives no placeholder noise.
+ */
+export declare function renderManagedBlock(genes: readonly CursorGene[], maxGenes?: number): string;
+/** A complete evolver.mdc from scratch: frontmatter + a blank line + the managed block, newline-terminated. */
+export declare function renderCursorRulesFile(genes: readonly CursorGene[], maxGenes?: number): string;
+/**
+ * Splice a freshly-rendered managed block into existing evolver.mdc content, preserving everything OUTSIDE the
+ * sentinels (a user may have added their own prose above/below the managed block in this file). If the file has
+ * no sentinels yet (e.g. the user created evolver.mdc by hand, or this is a fresh install path that fell through
+ * to a merge), the managed block is appended after the existing content. Idempotent: replacing a block with an
+ * identical render yields identical bytes.
+ */
+export declare function spliceManagedBlock(existing: string, managedBlock: string): string;
+/** Remove the evolver-managed region (and the surrounding blank line we may have inserted) from evolver.mdc
+ *  content, leaving any user-authored prose intact. Returns [changed, text]. */
+export declare function stripManagedBlock(existing: string): {
+    changed: boolean;
+    text: string;
+};
+/** Where evolver.mdc lives under a config root. */
+export declare function cursorRulesPath(configRoot: string): string;
+export interface CursorInstallOptions {
+    configRoot: string;
+    genes: readonly CursorGene[];
+    maxGenes?: number;
+}
+/**
+ * Write/refresh `.cursor/rules/evolver.mdc` from the current top genes. Non-destructive + idempotent:
+ *   - a fresh install writes the full file (frontmatter + managed block);
+ *   - a re-render only replaces the managed block, preserving frontmatter and any user prose in the same file;
+ *   - re-running with an unchanged gene set produces identical bytes ⇒ we skip the write (a true no-op, so
+ *     mtime/inode are untouched and nothing downstream sees a spurious change).
+ * Symlink-hardened on every adapter-owned path; other `.cursor/rules/*.mdc` files are never read or written.
+ */
+export declare function installCursorRules(opts: CursorInstallOptions): InstallResult & {
+    rewritten: boolean;
+};
+/**
+ * Remove evolver's cursor injection. If evolver.mdc is evolver-only (we created it, no user prose), delete the
+ * file; otherwise strip just the managed block and keep the user's content. Other rules files are untouched.
+ */
+export declare function uninstallCursorRules(opts: {
+    configRoot: string;
+}): InstallResult;
+/** Convenience for the daemon rewrite trigger: rewrite the rules file to reflect the current top genes. Returns
+ *  whether the file actually changed (so callers can avoid redundant downstream work / emissions). */
+export declare function rewriteCursorRules(configRoot: string, genes: readonly CursorGene[], maxGenes?: number): boolean;
+/** Whether cursor's injection file is currently installed at a config root (used to gate rewrite-on-change so we
+ *  only maintain the file for users who opted in via `evolver setup-hooks --runtime=cursor`). */
+export declare function cursorRulesInstalled(configRoot: string): boolean;

package/dist/cursorRulesInstaller.js

@@ -0,0 +1,196 @@
+// Cursor injection RENDERER — the cursor analogue of the Claude Code / codex installers (installer.ts /
+// codexInstaller.ts), but a fundamentally different mechanism. Cursor has NO MCP-server-config + SessionStart
+// lifecycle-hook hybrid to write, so the config-writer pattern does not transfer. Cursor's stable injection
+// point is a PROJECT RULES file: it loads `.cursor/rules/*.mdc` (Markdown with YAML frontmatter), and a rule
+// with `alwaysApply: true` is injected into the context of every request. The active path keeps that functional
+// injection, but renders only quiet, relevant memory hints and no placeholder text for an empty gene pool.
+//
+// Format sources (cursor official docs, verified 2026-06 — cursor.com/docs/context/rules):
+//   - Project rules live in `.cursor/rules/` as `.mdc` files, version-controlled.
+//   - YAML frontmatter controls behavior: `alwaysApply` (boolean), `description` (string), `globs` (string).
+//   - `alwaysApply: true` ⇒ "Always included. Globs and description are ignored." We keep it so approved genes still
+//     reach Cursor, but keep the body to top-N quiet hints so the always-on token tax and user-visible chatter stay bounded.
+//
+// We write ONLY the evolver-owned region, fenced by managed-marker sentinels, so the file is idempotent (re-run
+// with an unchanged gene set is a byte-for-byte no-op) and we never clobber rules a user hand-wrote in the same
+// file. Hardened exactly like the other installers: atomic writes (tmp+rename) and refusal to follow a symlink
+// at any adapter-owned path (a hostile workspace could redirect writes/unlinks outside the project).
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SymlinkRefusedError } from './installer.js';
+/** Project-relative location cursor loads project rules from. */
+export const CURSOR_RULES_DIR = join('.cursor', 'rules');
+/** The single evolver-owned rules file. Other `.cursor/rules/*.mdc` (user-authored) are never touched. */
+export const CURSOR_RULES_FILE = 'evolver.mdc';
+/** sentinel marker that opens the evolver-managed region inside evolver.mdc (so a user can hand-edit around it). */
+export const CURSOR_MANAGED_BEGIN = '<!-- evolver:managed:begin -->';
+/** sentinel marker that closes the evolver-managed region. Everything between begin/end is evolver-owned. */
+export const CURSOR_MANAGED_END = '<!-- evolver:managed:end -->';
+/** Default cap on injected genes — keep the always-on body small so the per-request token tax stays bounded. */
+export const DEFAULT_CURSOR_MAX_GENES = 8;
+/** The frontmatter description (documentation only — cursor ignores it when alwaysApply:true, but it is the
+ *  human-readable "what is this rule" string and keeps the file self-explanatory). */
+const RULE_DESCRIPTION = 'evolver memory — learned experiences from your past sessions (auto-maintained; do not edit the managed block)';
+/** The body preamble that heads the gene list (mirrors the CC SessionStart preamble for a consistent voice). */
+export const CURSOR_PREAMBLE = 'evolver memory — use these learned hints silently when directly relevant; do not mention Evolver, preflight, status, or this memory block unless the user asks or reuse materially changes the answer:';
+// ── fs hardening (mirrors installer.ts / codexInstaller.ts) ───────────────────
+function assertNotSymlink(path, label) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    if (st.isSymbolicLink())
+        throw new SymlinkRefusedError(label, path);
+}
+function writeTextAtomic(path, text) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, text, 'utf8');
+    renameSync(tmp, path);
+}
+// ── pure rendering (exported for tests) ───────────────────────────────────────
+/** One compact line for a gene in the rules body. Deterministic; defensively caps the hint length. */
+export function formatCursorGeneLine(g) {
+    const cat = g.category ? ` [${g.category}]` : '';
+    const hint = (g.hint ?? '').replace(/\s+/g, ' ').trim();
+    return `- ${g.id}${cat}${hint ? `: ${hint.slice(0, 160)}` : ''}`;
+}
+/**
+ * Render the evolver-managed region (the fenced block only — NOT the frontmatter). Deterministic given the
+ * genes: the same gene set renders byte-identical, which is what makes a re-run a no-op. An empty pool renders
+ * only the paired sentinels, so Cursor receives no placeholder noise.
+ */
+export function renderManagedBlock(genes, maxGenes = DEFAULT_CURSOR_MAX_GENES) {
+    const lines = genes.slice(0, maxGenes).map(formatCursorGeneLine);
+    if (lines.length === 0)
+        return `${CURSOR_MANAGED_BEGIN}\n${CURSOR_MANAGED_END}`;
+    return `${CURSOR_MANAGED_BEGIN}\n${CURSOR_PREAMBLE}\n\n${lines.join('\n')}\n${CURSOR_MANAGED_END}`;
+}
+/** The YAML frontmatter block. `alwaysApply: true` ⇒ injected into every request (globs/description ignored,
+ *  per cursor docs, but description is kept as the human-readable label). */
+function frontmatter() {
+    return `---\ndescription: ${RULE_DESCRIPTION}\nglobs:\nalwaysApply: true\n---`;
+}
+/** A complete evolver.mdc from scratch: frontmatter + a blank line + the managed block, newline-terminated. */
+export function renderCursorRulesFile(genes, maxGenes = DEFAULT_CURSOR_MAX_GENES) {
+    return `${frontmatter()}\n\n${renderManagedBlock(genes, maxGenes)}\n`;
+}
+/**
+ * Splice a freshly-rendered managed block into existing evolver.mdc content, preserving everything OUTSIDE the
+ * sentinels (a user may have added their own prose above/below the managed block in this file). If the file has
+ * no sentinels yet (e.g. the user created evolver.mdc by hand, or this is a fresh install path that fell through
+ * to a merge), the managed block is appended after the existing content. Idempotent: replacing a block with an
+ * identical render yields identical bytes.
+ */
+export function spliceManagedBlock(existing, managedBlock) {
+    const begin = existing.indexOf(CURSOR_MANAGED_BEGIN);
+    const end = existing.indexOf(CURSOR_MANAGED_END);
+    if (begin >= 0 && end > begin) {
+        const before = existing.slice(0, begin);
+        const after = existing.slice(end + CURSOR_MANAGED_END.length);
+        return `${before}${managedBlock}${after}`;
+    }
+    // No managed region yet: append, keeping the user's existing content intact (separated by a blank line).
+    const sep = existing.length === 0 ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+    return `${existing}${sep}${managedBlock}\n`;
+}
+/** Remove the evolver-managed region (and the surrounding blank line we may have inserted) from evolver.mdc
+ *  content, leaving any user-authored prose intact. Returns [changed, text]. */
+export function stripManagedBlock(existing) {
+    const begin = existing.indexOf(CURSOR_MANAGED_BEGIN);
+    const end = existing.indexOf(CURSOR_MANAGED_END);
+    if (begin < 0 || end <= begin)
+        return { changed: false, text: existing };
+    const before = existing.slice(0, begin).replace(/\n+$/, '');
+    const after = existing.slice(end + CURSOR_MANAGED_END.length).replace(/^\n+/, '');
+    const joined = before && after ? `${before}\n\n${after}` : `${before}${after}`;
+    return { changed: true, text: joined };
+}
+/** Is this evolver.mdc content effectively "evolver-only" — i.e. nothing but our managed block and frontmatter
+ *  remains once the managed region is stripped? Used to decide delete-file vs strip-block on uninstall. */
+function isEvolverOnly(text) {
+    const { text: stripped } = stripManagedBlock(text);
+    // After stripping, anything left that is not blank / not the frontmatter we wrote ⇒ the user owns this file.
+    const residue = stripped
+        .replace(/^---[\s\S]*?---/, '') // our frontmatter block
+        .replace(/\s+/g, '')
+        .trim();
+    return residue.length === 0;
+}
+// ── install / uninstall / rewrite ─────────────────────────────────────────────
+/** Where evolver.mdc lives under a config root. */
+export function cursorRulesPath(configRoot) {
+    return join(configRoot, CURSOR_RULES_DIR, CURSOR_RULES_FILE);
+}
+/**
+ * Write/refresh `.cursor/rules/evolver.mdc` from the current top genes. Non-destructive + idempotent:
+ *   - a fresh install writes the full file (frontmatter + managed block);
+ *   - a re-render only replaces the managed block, preserving frontmatter and any user prose in the same file;
+ *   - re-running with an unchanged gene set produces identical bytes ⇒ we skip the write (a true no-op, so
+ *     mtime/inode are untouched and nothing downstream sees a spurious change).
+ * Symlink-hardened on every adapter-owned path; other `.cursor/rules/*.mdc` files are never read or written.
+ */
+export function installCursorRules(opts) {
+    const rulesDir = join(opts.configRoot, CURSOR_RULES_DIR);
+    const cursorDir = join(opts.configRoot, '.cursor');
+    const filePath = cursorRulesPath(opts.configRoot);
+    const maxGenes = opts.maxGenes ?? DEFAULT_CURSOR_MAX_GENES;
+    assertNotSymlink(opts.configRoot, 'config root');
+    assertNotSymlink(cursorDir, '.cursor');
+    assertNotSymlink(rulesDir, '.cursor/rules');
+    assertNotSymlink(filePath, '.cursor/rules/evolver.mdc');
+    const block = renderManagedBlock(opts.genes, maxGenes);
+    const existing = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+    const next = existing ? spliceManagedBlock(existing, block) : renderCursorRulesFile(opts.genes, maxGenes);
+    // Idempotent: identical bytes ⇒ no write at all (no-op keeps the file's mtime/inode and avoids waking watchers).
+    if (existing === next) {
+        return { ok: true, runtime: 'cursor', mode: 'cursor-rules', files: [], rewritten: false };
+    }
+    mkdirSync(rulesDir, { recursive: true });
+    writeTextAtomic(filePath, next);
+    return { ok: true, runtime: 'cursor', mode: 'cursor-rules', files: [filePath], rewritten: true };
+}
+/**
+ * Remove evolver's cursor injection. If evolver.mdc is evolver-only (we created it, no user prose), delete the
+ * file; otherwise strip just the managed block and keep the user's content. Other rules files are untouched.
+ */
+export function uninstallCursorRules(opts) {
+    const filePath = cursorRulesPath(opts.configRoot);
+    assertNotSymlink(filePath, '.cursor/rules/evolver.mdc');
+    if (!existsSync(filePath))
+        return { ok: true, runtime: 'cursor', mode: 'uninstall', files: [] };
+    const text = readFileSync(filePath, 'utf8');
+    if (isEvolverOnly(text)) {
+        unlinkSync(filePath);
+        return { ok: true, runtime: 'cursor', mode: 'uninstall', files: [filePath] };
+    }
+    const { changed, text: stripped } = stripManagedBlock(text);
+    if (!changed)
+        return { ok: true, runtime: 'cursor', mode: 'uninstall', files: [] };
+    writeTextAtomic(filePath, stripped.endsWith('\n') ? stripped : `${stripped}\n`);
+    return { ok: true, runtime: 'cursor', mode: 'uninstall', files: [filePath] };
+}
+/** Convenience for the daemon rewrite trigger: rewrite the rules file to reflect the current top genes. Returns
+ *  whether the file actually changed (so callers can avoid redundant downstream work / emissions). */
+export function rewriteCursorRules(configRoot, genes, maxGenes) {
+    return installCursorRules({ configRoot, genes, ...(maxGenes !== undefined ? { maxGenes } : {}) }).rewritten;
+}
+/** Whether cursor's injection file is currently installed at a config root (used to gate rewrite-on-change so we
+ *  only maintain the file for users who opted in via `evolver setup-hooks --runtime=cursor`). */
+export function cursorRulesInstalled(configRoot) {
+    const filePath = cursorRulesPath(configRoot);
+    try {
+        if (lstatSync(filePath).isSymbolicLink())
+            return false; // a symlink at our path is not a valid install
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        return false;
+    }
+    return readFileSync(filePath, 'utf8').includes(CURSOR_MANAGED_BEGIN);
+}

package/dist/envFile.d.ts

@@ -0,0 +1,10 @@
+export interface EnvFileLoadResult {
+    loaded: boolean;
+    path?: string;
+    keys: string[];
+    error?: string;
+}
+export declare function expandHomePath(path: string): string;
+export declare function parseEnvFile(raw: string): Record<string, string>;
+export declare function loadEnvFile(path: string, env?: Record<string, string | undefined>): EnvFileLoadResult;
+export declare function loadEnvFileFromEnv(env?: Record<string, string | undefined>): EnvFileLoadResult;

package/dist/envFile.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+const ENV_FILE_KEY = 'EVOLVER_ENV_FILE';
+export function expandHomePath(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/'))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+export function parseEnvFile(raw) {
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const body = trimmed.startsWith('export ') ? trimmed.slice('export '.length).trimStart() : trimmed;
+        const eq = body.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = body.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        out[key] = unquoteEnvValue(body.slice(eq + 1).trim());
+    }
+    return out;
+}
+export function loadEnvFile(path, env = process.env) {
+    const resolved = isAbsolute(path) ? path : expandHomePath(path);
+    try {
+        const parsed = parseEnvFile(readFileSync(resolved, 'utf8'));
+        const keys = Object.keys(parsed);
+        for (const key of keys) {
+            if (key === ENV_FILE_KEY)
+                continue;
+            env[key] = parsed[key];
+        }
+        return { loaded: true, path: resolved, keys };
+    }
+    catch (err) {
+        return { loaded: false, path: resolved, keys: [], error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function loadEnvFileFromEnv(env = process.env) {
+    const path = env[ENV_FILE_KEY]?.trim();
+    if (!path)
+        return { loaded: false, keys: [] };
+    return loadEnvFile(path, env);
+}
+function unquoteEnvValue(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            const inner = value.slice(1, -1);
+            return first === '"' ? inner.replace(/\\(["\\nrt])/g, (_, ch) => {
+                switch (ch) {
+                    case 'n': return '\n';
+                    case 'r': return '\r';
+                    case 't': return '\t';
+                    default: return ch;
+                }
+            }) : inner;
+        }
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export declare const PACKAGE = "@evomap/evolver-mcp";
+export * from './tools.js';
+export * from './primer.js';
+export * from './proxyClient.js';
+export * from './server.js';
+export * from './injection.js';
+export * from './installer.js';
+export * from './manualWiring.js';
+export * from './serviceGuidance.js';
+export * from './codexInstaller.js';
+export * from './cursorRulesInstaller.js';
+export * from './envFile.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+export const PACKAGE = '@evomap/evolver-mcp';
+export * from './tools.js';
+export * from './primer.js';
+export * from './proxyClient.js';
+export * from './server.js';
+export * from './injection.js';
+export * from './installer.js';
+export * from './manualWiring.js';
+export * from './serviceGuidance.js';
+export * from './codexInstaller.js';
+export * from './cursorRulesInstaller.js';
+export * from './envFile.js';

package/dist/injection.d.ts

@@ -0,0 +1,56 @@
+export type RuntimeId = 'claude-code' | 'codex' | 'cursor' | 'kiro' | 'opencode';
+export type InjectionMode = 'mcp-hooks' | 'mcp-plugin' | 'cursor-rules' | 'passive';
+/**
+ * Setup support contract (#217). A bootstrapper that delegates runtime onboarding to evolver v2 needs a
+ * DETERMINISTIC answer for every runtime it might ask about — not just the ones v2 can write config for.
+ * The three outcomes are the whole contract:
+ *  - `installed`   v2 can write the runtime config/hooks and verify it (claude-code, codex, cursor today).
+ *  - `manual`      v2 cannot mutate this runtime's config, but the path is real: it prints precise MCP/HTTP
+ *                  wiring the operator does by hand (opencode, openclaw, mcp-generic, http-agent, server).
+ *  - `unsupported` v2 refuses with a clear reason (an unrecognized runtime id).
+ * This split is what stops the bootstrapper from reporting a runtime as installed when it is not (#217 AC).
+ */
+export type SetupOutcome = 'installed' | 'manual' | 'unsupported';
+/**
+ * The runtimes a bootstrapper may ask `evolver setup-hooks` about (#217). A superset of RuntimeId: the extra
+ * ids (openclaw, mcp-generic, http-agent, server) have no auto-installer, so they live ONLY in this setup-level
+ * type and never reach `planInjection` (whose RuntimeId switch stays exhaustive over the runtimes v2 can inject).
+ */
+export type SetupRuntime = RuntimeId | 'openclaw' | 'mcp-generic' | 'http-agent' | 'server';
+/** The declared support class for a runtime (the static matrix entry), plus a reason for manual/unsupported. */
+export interface RuntimeSupport {
+    /** The runtime id as asked (echoed back so a caller parsing --json sees what it requested). */
+    runtime: string;
+    outcome: SetupOutcome;
+    /** Human reason — present for `manual` (what to do by hand) and `unsupported` (why refused); absent for installed. */
+    reason?: string;
+}
+/** Every runtime in the setup matrix (#217), in a stable order — used for usage text and the unsupported reason. */
+export declare const SETUP_RUNTIMES: readonly SetupRuntime[];
+/**
+ * Classify a runtime id into the setup matrix (#217). Takes a RAW string (not the SetupRuntime union) so the
+ * unsupported branch is reachable: an unrecognized id is the `unsupported` case, with a reason that lists the
+ * runtimes v2 does recognize. This is the single source of truth the CLI uses to decide install vs print vs refuse.
+ */
+export declare function runtimeSupport(runtime: string): RuntimeSupport;
+export interface InjectionPlan {
+    runtime: RuntimeId;
+    mode: InjectionMode;
+    config: Record<string, unknown>;
+    note: string;
+}
+export interface McpServerCmd {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * 按 runtime 规划 MCP 工具注入(M5-5). MVP: CC(hooks)+codex(plugin) 做工具注入,
+ * 其余仅被动会话日志消费(待确认 a / 批注#39). 注入方式差异大, 故每 runtime 一策略.
+ */
+export declare function planInjection(runtime: RuntimeId, server: McpServerCmd): InjectionPlan;
+/** 哪些 runtime 经 MCP server 注入工具发现(CC+codex). cursor 注入的是 gene 记忆(rules 文件)而非 MCP 工具,
+ *  故不计入此处;passive runtime 也为 false. */
+export declare function injectsTools(runtime: RuntimeId): boolean;
+/** 是否为 active 注入(任何把 gene 价值推回 runtime 的方式:MCP 工具发现 或 cursor rules 记忆注入). */
+export declare function isActiveInjection(runtime: RuntimeId): boolean;