@evomap/evolver-mcp 2.0.0-beta.0

package/dist/injection.js

@@ -0,0 +1,84 @@
+/** Every runtime in the setup matrix (#217), in a stable order — used for usage text and the unsupported reason. */
+export const SETUP_RUNTIMES = [
+    'claude-code', 'codex', 'cursor', 'opencode', 'kiro', 'openclaw', 'mcp-generic', 'http-agent', 'server',
+];
+/** Runtimes v2 can write config/hooks for and verify. */
+const INSTALLED_RUNTIMES = new Set(['claude-code', 'codex', 'cursor']);
+/** Runtimes with no v2 auto-installer but a real manual path. The reason is the short, honest "do it by hand"
+ *  line; the precise wiring text is a separate concern (#217 slice 2), not hard-coded here. */
+const MANUAL_RUNTIMES = new Map([
+    ['opencode', 'opencode is consumed passively today; register the evolver MCP server in its config by hand'],
+    ['kiro', 'kiro is consumed passively today; register the evolver MCP server in its config by hand'],
+    ['openclaw', 'no v2 auto-installer yet; wire the evolver MCP server (or PrivateHub HTTP/A2A) by hand'],
+    ['mcp-generic', 'no config writer for a generic MCP client; register the evolver MCP server by hand'],
+    ['http-agent', 'no config writer for an HTTP/API-only agent; wire it to PrivateHub HTTP/A2A by hand'],
+    ['server', 'v2 does not manage service lifecycle; use the server/service startup guidance by hand'],
+]);
+/**
+ * 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 function runtimeSupport(runtime) {
+    if (INSTALLED_RUNTIMES.has(runtime))
+        return { runtime, outcome: 'installed' };
+    const reason = MANUAL_RUNTIMES.get(runtime);
+    if (reason !== undefined)
+        return { runtime, outcome: 'manual', reason };
+    return { runtime, outcome: 'unsupported', reason: `unknown runtime '${runtime}' (supported: ${SETUP_RUNTIMES.join(', ')})` };
+}
+/**
+ * 按 runtime 规划 MCP 工具注入(M5-5). MVP: CC(hooks)+codex(plugin) 做工具注入,
+ * 其余仅被动会话日志消费(待确认 a / 批注#39). 注入方式差异大, 故每 runtime 一策略.
+ */
+export function planInjection(runtime, server) {
+    switch (runtime) {
+        case 'claude-code':
+            return {
+                runtime, mode: 'mcp-hooks',
+                // CC 成熟: .mcp.json 注册 MCP server, agent 在 tool list 自然发现
+                config: { mcpServers: { evolver: { command: server.command, args: server.args ?? [], ...(server.env ? { env: server.env } : {}) } } },
+                note: 'CC: 写 .mcp.json + SessionStart hook; agent 经 MCP tool list 自然发现 evolver 能力',
+            };
+        case 'codex':
+            return {
+                runtime, mode: 'mcp-plugin',
+                // codex loads TOML (~/.codex or project .codex/config.toml). Real schema: an MCP stdio server under
+                // [mcp_servers.<id>] (command/args/env) — the installer also adds a [[hooks.SessionStart]] hook so
+                // codex gets the same hybrid as CC. Config mirrors the codex [mcp_servers.evolver] table shape.
+                config: { mcp_servers: { evolver: { command: server.command, args: server.args ?? [], ...(server.env ? { env: server.env } : {}) } } },
+                note: 'codex: 写 .codex/config.toml [mcp_servers.evolver] + [[hooks.SessionStart]]; agent 经 MCP tool list 发现 evolver 能力',
+            };
+        case 'cursor':
+            return {
+                runtime, mode: 'cursor-rules',
+                // cursor has no MCP-server-config + SessionStart-hook hybrid; its stable injection point is a project
+                // rules file. The active path renders quiet top-gene hints into .cursor/rules/evolver.mdc
+                // (alwaysApply:true) and a daemon rewrites it on gene-set change. This is gene-memory
+                // injection (NOT MCP tool discovery), so it carries no MCP server config here.
+                config: {},
+                note: 'cursor: 渲染静默 top-gene hints 进 .cursor/rules/evolver.mdc (alwaysApply:true); daemon 在 gene 集变化时重写',
+            };
+        case 'kiro':
+        case 'opencode':
+            return {
+                runtime, mode: 'passive',
+                config: {},
+                note: `${runtime}: MVP 仅被动消费会话日志(无工具注入); 接入方式待补`,
+            };
+        default: {
+            const _exhaustive = runtime;
+            throw new Error(`未知 runtime: ${String(_exhaustive)}`);
+        }
+    }
+}
+/** 哪些 runtime 经 MCP server 注入工具发现(CC+codex). cursor 注入的是 gene 记忆(rules 文件)而非 MCP 工具,
+ *  故不计入此处;passive runtime 也为 false. */
+export function injectsTools(runtime) {
+    const mode = planInjection(runtime, { command: 'x' }).mode;
+    return mode === 'mcp-hooks' || mode === 'mcp-plugin';
+}
+/** 是否为 active 注入(任何把 gene 价值推回 runtime 的方式:MCP 工具发现 或 cursor rules 记忆注入). */
+export function isActiveInjection(runtime) {
+    return planInjection(runtime, { command: 'x' }).mode !== 'passive';
+}

package/dist/installer.d.ts

@@ -0,0 +1,106 @@
+import { type RuntimeId, type McpServerCmd, type InjectionPlan } from './injection.js';
+import { type CursorGene } from './cursorRulesInstaller.js';
+/** Marks a config file as containing evolver-managed entries, so uninstall only removes what we added. */
+export declare const MANAGED_MARKER = "_evolver_managed";
+/** Default command the SessionStart hook runs to render + print the memory injection. The `--hook-stdin` flag opts
+ *  the entrypoint into reading the runtime's SessionStart JSON from stdin (to capture session_id, #205); only the
+ *  installed hook sets it, so a manual `evolver inject session-start` never reads stdin. */
+export declare const DEFAULT_HOOK_COMMAND = "evolver inject session-start --hook-stdin";
+/**
+ * Where a claude-code install registers the evolver MCP server. This is the fix for "global install doesn't
+ * actually globalize" (#290): Claude Code's MCP scopes are local / user / project, and a `.mcp.json` is the
+ * PROJECT-scoped file — it only loads when that directory is the launch cwd. So writing `~/.mcp.json` does NOT
+ * make evolver available from other projects. The real user (device-wide) scope is the top-level `mcpServers`
+ * in `~/.claude.json`.
+ *  - 'project' (default): register in <configRoot>/.mcp.json (cwd-scoped) — unchanged legacy behavior.
+ *  - 'user': register in ~/.claude.json's top-level mcpServers so EVERY project's sessions discover evolver.
+ * The SessionStart hook always lands in the matching .claude/settings.json (project: <configRoot>/.claude;
+ * user: ~/.claude — which is already user-level). codex/cursor ignore this (codex's ~/.codex/config.toml is a
+ * genuine global config, so its global path stays configRoot-driven).
+ */
+export type InstallScope = 'user' | 'project';
+export interface InstallOptions {
+    /** Runtime config root — the CC adapter writes <configRoot>/.mcp.json and <configRoot>/.claude/settings.json
+     *  for PROJECT scope. For USER scope the MCP registration goes to ~/.claude.json instead (see `scope`). */
+    configRoot: string;
+    /** claude-code only: 'project' (default) writes <configRoot>/.mcp.json; 'user' registers the MCP in
+     *  ~/.claude.json so it loads in every project (Claude Code's real user scope). Ignored by codex/cursor. */
+    scope?: InstallScope;
+    /** The MCP server launch command registered in .mcp.json (how the runtime starts the evolver MCP server). */
+    server: McpServerCmd;
+    /** Command the SessionStart hook runs to inject memory. Default 'evolver inject session-start'. */
+    hookCommand?: string;
+    /** Reinstall even if an evolver install is already present. */
+    force?: boolean;
+    /** Cursor only: the top genes to render into .cursor/rules/evolver.mdc. The daemon refreshes these on change;
+     *  a one-shot `setup-hooks --runtime=cursor` install seeds the file (empty ⇒ a placeholder the daemon fills). */
+    genes?: readonly CursorGene[];
+    /** Cursor only: cap on genes rendered into the always-on rules body (token-tax bound). */
+    maxGenes?: number;
+}
+export interface InstallResult {
+    ok: boolean;
+    runtime: RuntimeId;
+    mode: string;
+    /** Absolute paths written (install) or cleaned (uninstall). */
+    files: string[];
+    alreadyInstalled?: boolean;
+    error?: string;
+}
+export declare class SymlinkRefusedError extends Error {
+    constructor(label: string, path: string);
+}
+/**
+ * Thrown when a SHARED user config (~/.claude.json or ~/.claude/settings.json) exists but does not parse as JSON.
+ * These files are Claude Code's own state (projects/oauthAccount/userID/history/settings),
+ * and user-scope install merges into them via a full-file atomic replace. The lenient readJson() returns {} on
+ * a parse failure, which would make the merge emit ONLY evolver's entry and silently WIPE the whole file — a
+ * realistic data-loss path because Claude Code writes these files non-atomically (a concurrent session can leave
+ * one truncated). For the shared-config read we therefore refuse instead of clobbering. Project-scoped
+ * .mcp.json/.claude/settings.json are evolver-owned, so their lenient fresh-start behavior stays unchanged.
+ */
+export declare class UnparseableConfigError extends Error {
+    constructor(label: string, path: string);
+}
+/**
+ * Thrown when a SHARED user config exists but is empty or whitespace-only. Claude Code writes these files with a
+ * truncating write, so present-empty can be a concurrent-write window rather than a fresh config.
+ */
+export declare class EmptySharedConfigError extends Error {
+    constructor(label: string, path: string);
+}
+type SharedConfigRaceHook = (path: string, attempt: number) => void;
+export declare function _setSharedConfigRaceHookForTest(hook?: SharedConfigRaceHook): void;
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/**
+ * deepMerge, but for `hooks.<event>` arrays keep the user's existing entries and only replace evolver-owned
+ * ones — so reinstalling refreshes evolver's hook without clobbering a user's own SessionStart/Stop hooks.
+ */
+export declare function mergeHooksUnion(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+/** Strip evolver-owned hook entries + the marker from a parsed config (uninstall). Returns [changed, data]. */
+export declare function stripManaged(data: Record<string, unknown>): {
+    changed: boolean;
+    data: Record<string, unknown>;
+};
+/**
+ * Execute an InjectionPlan against a runtime config root. Active runtimes:
+ *  - claude-code (mcp-hooks): scope 'project' (default) writes/merges <root>/.mcp.json + <root>/.claude/settings.json;
+ *    scope 'user' registers the MCP in ~/.claude.json (real user scope) + the SessionStart hook in ~/.claude/settings.json.
+ *  - codex (mcp-plugin): writes/merges <root>/.codex/config.toml — [mcp_servers.evolver] + [[hooks.SessionStart]]
+ *    (delegated to codexInstaller; TOML, not JSON). Same hybrid value (tool discovery + session-start injection).
+ *  - cursor (cursor-rules): renders top genes into <root>/.cursor/rules/evolver.mdc (alwaysApply:true) — gene
+ *    memory injection, not MCP tool discovery (delegated to cursorRulesInstaller). The daemon keeps it fresh.
+ * Idempotent + symlink-safe; passive runtimes (kiro/opencode) return ok:false (nothing to inject).
+ */
+export declare function installInjection(plan: InjectionPlan, opts: InstallOptions): InstallResult;
+/** Remove evolver's MCP registration + SessionStart hook from a CC config root (leaves user content intact).
+ *  Pass the SAME scope used at install: 'user' cleans ~/.claude.json + ~/.claude/settings.json; 'project'
+ *  (default) cleans <configRoot>/.mcp.json + <configRoot>/.claude/settings.json. stripManaged only removes
+ *  the mcpServers.evolver entry (and any evolver-owned hooks/marker), so it is safe on the shared ~/.claude.json. */
+export declare function uninstallInjection(runtime: RuntimeId, opts: {
+    configRoot: string;
+    scope?: InstallScope;
+}): InstallResult;
+/** Convenience: plan + install in one call for a runtime. */
+export declare function setupRuntime(runtime: RuntimeId, opts: InstallOptions): InstallResult;
+export {};