@evomap/evolver-mcp 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/installerShared.d.ts

@@ -0,0 +1,103 @@
+import type { McpServerCmd, RuntimeId } from './injection.js';
+/** Minimal gene projection consumed by the Cursor rules renderer. */
+export interface CursorGene {
+    id: string;
+    category?: string;
+    hint?: string;
+}
+/** Default command used by runtimes that support a SessionStart hook. The flag enables session-id capture. */
+export declare const DEFAULT_HOOK_COMMAND = "evolver inject session-start --hook-stdin";
+export declare const DEFAULT_PROMPT_RECALL_HOOK_COMMAND = "evolver inject prompt-recall --hook-stdin";
+export declare const EVOLVER_HOOK_STATUS = "evolver-managed-hook";
+/** Bind custom-command ownership to that exact command without adding undocumented hook-schema fields. */
+export declare function evolverManagedHookStatus(command: string): string;
+/** Remove only Evolver-owned handlers, retaining user handlers that share the same matcher group. */
+export declare function stripEvolverHookEntries(entries: readonly unknown[], trustManagedStatus?: boolean, managedCommands?: ReadonlySet<string>): {
+    changed: boolean;
+    entries: unknown[];
+};
+/** Runtime configuration scope. Project is the default when omitted. */
+export type InstallScope = 'user' | 'project';
+export interface InstallOptions {
+    /** Runtime config root. Runtime-specific user scopes may resolve their own home-anchored paths. */
+    configRoot: string;
+    /** Claude Code scope. Other runtimes may also use this to select project or user configuration. */
+    scope?: InstallScope;
+    /** The MCP server launch command registered in the runtime configuration. */
+    server: McpServerCmd;
+    /** Command the SessionStart hook runs to inject memory. */
+    hookCommand?: string;
+    /** Command the UserPromptSubmit hook runs. Default is local-only, default-off prompt recall. */
+    promptRecallHookCommand?: string;
+    /** Reinstall even if an Evolver install is already present. */
+    force?: boolean;
+    /** Plan and validate without writing config or backup files. */
+    dryRun?: boolean;
+    /** Cursor only: genes rendered into the managed project rules file. */
+    genes?: readonly CursorGene[];
+    /** Cursor only: cap on genes rendered into the always-on rules body. */
+    maxGenes?: number;
+    /** Antigravity only: override the user home used to resolve ~/.gemini config roots. */
+    homeDir?: string;
+    /** Kiro user scope only: direct replacement for ~/.kiro, matching KIRO_HOME semantics. */
+    kiroHome?: string;
+    /** OpenCode user scope only: explicit XDG_CONFIG_HOME used to resolve the global config. */
+    xdgConfigHome?: string;
+    /** OpenCode user scope only: explicit OPENCODE_CONFIG file override. */
+    opencodeConfig?: string;
+    /** OpenCode user scope only: explicit OPENCODE_CONFIG_DIR override. */
+    opencodeConfigDir?: string;
+    /** OpenCode only: inline config loaded after project/custom-directory config. */
+    opencodeConfigContent?: string;
+    /** OpenCode only: mirrors truthy OPENCODE_DISABLE_PROJECT_CONFIG handling. */
+    opencodeDisableProjectConfig?: boolean;
+    /** OpenCode only: injectable managed-config directory for hermetic tests. */
+    opencodeManagedConfigDir?: string;
+    /** OpenCode only: injectable macOS managed-preference paths for hermetic tests. */
+    opencodeManagedPreferencePaths?: readonly string[];
+    /** OpenCode only: injectable platform used to resolve system managed paths. */
+    opencodePlatform?: NodeJS.Platform;
+    /** OpenCode only: injectable ProgramData used to resolve the Windows managed path. */
+    opencodeProgramData?: string;
+    /** OpenCode only: injectable username used to resolve macOS managed preferences. */
+    opencodeUsername?: string;
+}
+export interface UninstallOptions {
+    configRoot: string;
+    scope?: InstallScope;
+    /** Antigravity only: override the user home used to resolve ~/.gemini config roots. */
+    homeDir?: string;
+    /** Kiro user scope only: direct replacement for ~/.kiro, matching KIRO_HOME semantics. */
+    kiroHome?: string;
+    /** Validate and report the uninstall without changing config or backup files. */
+    dryRun?: boolean;
+    /** OpenCode user scope only: explicit XDG_CONFIG_HOME used to resolve the global config. */
+    xdgConfigHome?: string;
+    /** OpenCode user scope only: explicit OPENCODE_CONFIG file override. */
+    opencodeConfig?: string;
+    /** OpenCode user scope only: explicit OPENCODE_CONFIG_DIR override. */
+    opencodeConfigDir?: string;
+}
+export interface InstallResult {
+    ok: boolean;
+    runtime: RuntimeId;
+    mode: string;
+    /** Absolute paths written (install) or cleaned (uninstall). */
+    files: string[];
+    alreadyInstalled?: boolean;
+    dryRun?: boolean;
+    verified?: boolean;
+    backups?: string[];
+    error?: string;
+}
+export declare class SymlinkRefusedError extends Error {
+    constructor(label: string, path: string);
+}
+export declare class UnparseableConfigError extends Error {
+    constructor(label: string, path: string, owner?: string);
+}
+export declare class EmptySharedConfigError extends Error {
+    constructor(label: string, path: string, owner?: string);
+}
+/** Refuse to read or write through a symlink at an adapter-owned path. */
+export declare function assertNotSymlink(path: string, label: string): void;

package/dist/installerShared.js

@@ -0,0 +1,99 @@
+import { lstatSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+/** Default command used by runtimes that support a SessionStart hook. The flag enables session-id capture. */
+export const DEFAULT_HOOK_COMMAND = 'evolver inject session-start --hook-stdin';
+export const DEFAULT_PROMPT_RECALL_HOOK_COMMAND = 'evolver inject prompt-recall --hook-stdin';
+export const EVOLVER_HOOK_STATUS = 'evolver-managed-hook';
+const LEGACY_EVOLVER_HOOK_STATUS = 'Loading Evolver memory';
+function isObj(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const LEGACY_NODE_COMMAND = /^"?node(?:\.exe)?"?\s+/i;
+const LEGACY_EVOLVER_SCRIPT_BASENAME = /(?:^|[\\/'"\s])(?:evolver-session-start|evolver-session-end|evolver-signal-detect|evolver-task-recall|evolver-daemon-start)\.js(?=$|[\\/'"\s])/i;
+const LEGACY_V2_CLI_HOOK_COMMAND = /^"?evolver(?:\.cmd|\.exe)?"?\s+inject\s+(?:session-start|prompt-recall)(?:\s|$)/i;
+function isKnownEvolverHookCommand(command) {
+    const trimmed = command.trim();
+    return LEGACY_V2_CLI_HOOK_COMMAND.test(trimmed)
+        || (LEGACY_NODE_COMMAND.test(trimmed) && LEGACY_EVOLVER_SCRIPT_BASENAME.test(trimmed));
+}
+/** Bind custom-command ownership to that exact command without adding undocumented hook-schema fields. */
+export function evolverManagedHookStatus(command) {
+    if (isKnownEvolverHookCommand(command))
+        return EVOLVER_HOOK_STATUS;
+    const commandTag = createHash('sha256').update(command, 'utf8').digest('hex').slice(0, 16);
+    return `${EVOLVER_HOOK_STATUS} [evolver:${commandTag}]`;
+}
+function legacyEvolverManagedHookStatus(command) {
+    const currentStatus = evolverManagedHookStatus(command);
+    return `${LEGACY_EVOLVER_HOOK_STATUS}${currentStatus.slice(EVOLVER_HOOK_STATUS.length)}`;
+}
+const NO_MANAGED_HOOK_COMMANDS = new Set();
+const isEvolverHandler = (handler, trustManagedStatus, managedCommands) => {
+    if (!isObj(handler) || typeof handler['command'] !== 'string')
+        return false;
+    const command = handler['command'];
+    return isKnownEvolverHookCommand(command)
+        || (trustManagedStatus && (managedCommands.has(command)
+            || handler['statusMessage'] === evolverManagedHookStatus(command)
+            || handler['statusMessage'] === legacyEvolverManagedHookStatus(command)));
+};
+/** Remove only Evolver-owned handlers, retaining user handlers that share the same matcher group. */
+export function stripEvolverHookEntries(entries, trustManagedStatus = false, managedCommands = NO_MANAGED_HOOK_COMMANDS) {
+    let changed = false;
+    const keptEntries = [];
+    for (const entry of entries) {
+        if (!isObj(entry)) {
+            keptEntries.push(entry);
+            continue;
+        }
+        const handlers = entry['hooks'];
+        if (!Array.isArray(handlers)) {
+            if (isEvolverHandler(entry, trustManagedStatus, managedCommands))
+                changed = true;
+            else
+                keptEntries.push(entry);
+            continue;
+        }
+        const keptHandlers = handlers.filter((handler) => !isEvolverHandler(handler, trustManagedStatus, managedCommands));
+        if (keptHandlers.length === handlers.length) {
+            keptEntries.push(entry);
+            continue;
+        }
+        changed = true;
+        if (keptHandlers.length > 0)
+            keptEntries.push({ ...entry, hooks: keptHandlers });
+    }
+    return { changed, entries: keptEntries };
+}
+export class SymlinkRefusedError extends Error {
+    constructor(label, path) {
+        super(`[setup-hooks] refusing to operate: ${label} ${path} is a symbolic link — evolver will not follow symlinks for adapter-owned paths (a hostile workspace could redirect writes/unlinks outside the project). Replace it with a real directory/file and rerun.`);
+        this.name = 'SymlinkRefusedError';
+    }
+}
+export class UnparseableConfigError extends Error {
+    constructor(label, path, owner = 'Claude Code') {
+        super(`[setup-hooks] refusing to overwrite ${label} (${path}): the file exists and is non-empty but is not valid JSON. This is ${owner}'s own shared config; merging into it would replace the whole file and could wipe its contents. Fix or remove the corrupt file, then rerun.`);
+        this.name = 'UnparseableConfigError';
+    }
+}
+export class EmptySharedConfigError extends Error {
+    constructor(label, path, owner = 'Claude Code') {
+        super(`[setup-hooks] refusing to overwrite ${label} (${path}): the file exists but is empty or contains only whitespace. ${owner} may be in the middle of a truncating write, and treating it as fresh config could wipe shared config data. Fix the empty file or retry after ${owner} finishes writing it.`);
+        this.name = 'EmptySharedConfigError';
+    }
+}
+/** Refuse to read or write through a symlink at an adapter-owned path. */
+export function assertNotSymlink(path, label) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (stat.isSymbolicLink())
+        throw new SymlinkRefusedError(label, path);
+}

package/dist/jsonMcpInstaller.d.ts

@@ -0,0 +1,79 @@
+import type { InjectionPlan, McpServerCmd, RuntimeId } from './injection.js';
+import { type InstallOptions, type InstallResult, type UninstallOptions } from './installerShared.js';
+type BeforeReplaceHook = (path: string) => void;
+export declare function _setJsonMcpBeforeReplaceHookForTest(hook?: BeforeReplaceHook): void;
+export declare function _setJsonMcpAfterReplaceHookForTest(hook?: BeforeReplaceHook): void;
+export declare function _setJsonMcpAfterSharedFileValidateHookForTest(hook?: BeforeReplaceHook): void;
+export declare function _setJsonMcpBeforeBackupRemoveHookForTest(hook?: BeforeReplaceHook): void;
+export declare function _setJsonMcpBeforeSharedFileCommitHookForTest(hook?: BeforeReplaceHook): void;
+export interface JsonMcpRuntimeSpec {
+    runtime: 'opencode' | 'kiro';
+    configPath(opts: JsonMcpPathOptions): string;
+    resolveConfig?(opts: JsonMcpPathOptions): JsonMcpRuntimeResolution;
+    safeRoot?(opts: JsonMcpPathOptions): string;
+    conflictingPaths?(opts: JsonMcpPathOptions): string[];
+    containerKey: 'mcp' | 'mcpServers';
+    entry(server: McpServerCmd): Record<string, unknown>;
+    installPreflight?(resolution: JsonMcpRuntimeResolution, opts: InstallOptions, expected: Record<string, unknown>): JsonMcpInstallPreflight | undefined;
+}
+export interface JsonMcpInstallPreflight {
+    alreadyInstalled?: boolean;
+    assertUnchanged(): void;
+}
+type JsonMcpPathOptions = Pick<InstallOptions, 'configRoot' | 'scope' | 'homeDir' | 'kiroHome' | 'xdgConfigHome' | 'opencodeConfig' | 'opencodeConfigDir'>;
+export interface JsonMcpRuntimeResolution {
+    configPath: string;
+    safeRoot: string;
+    conflictingPaths: string[];
+    /** An active sibling at the same precedence slot that must remain user-owned and read-only. */
+    activePrecedencePath?: string;
+    /** The writable target was retargeted to a uniquely managed config discovered outside the active path. */
+    managedRetarget?: true;
+    /** Runtime config candidates ordered from lowest to highest precedence; the first path is the default target. */
+    topologyCandidatePaths?: string[];
+    evidencePaths?: string[];
+    /** Config locations that may contain a managed backup from an earlier active-precedence decision. */
+    uninstallCandidatePaths?: string[];
+    /** Broader locations used to reuse a managed target selected from an ancestor project directory. */
+    installDiscoveryPaths?: string[];
+    /** Safe root for install discovery and a selected managed target; does not affect default install writes. */
+    installSafeRoot?: string;
+    /** Broader read-only locations used only to discover managed backups during uninstall. */
+    uninstallDiscoveryPaths?: string[];
+    /** Safe root for uninstall discovery and a selected managed target; does not affect install writes. */
+    uninstallSafeRoot?: string;
+    /** Candidate-local conflicts that must be re-evaluated after uninstall retargeting. */
+    uninstallConflictingPaths?: (configPath: string) => string[];
+}
+export declare class McpConfigConflictError extends Error {
+    readonly diff: {
+        path: string;
+        expected: unknown;
+        actual: unknown;
+    };
+    constructor(runtime: string, path: string, expected: unknown, actual: unknown);
+}
+export declare class McpConfigShapeError extends Error {
+    constructor(runtime: string, path: string, detail: string);
+}
+export declare class McpConfigOwnershipError extends Error {
+    constructor(runtime: string, detail: string);
+}
+export declare class McpConfigVerificationError extends Error {
+    private readonly runtime;
+    private readonly path;
+    restored: boolean;
+    constructor(runtime: string, path: string);
+    markRestored(): void;
+}
+export declare class McpConfigChangedError extends Error {
+    constructor(runtime: string, path: string);
+}
+export declare class McpServerValidationError extends Error {
+    constructor(message: string);
+}
+declare function retrySharedConfigTransaction<T>(operation: () => T): T;
+export declare const _retrySharedConfigTransactionForTest: typeof retrySharedConfigTransaction;
+export declare function installJsonMcpRuntime(spec: JsonMcpRuntimeSpec, plan: InjectionPlan, opts: InstallOptions): InstallResult;
+export declare function uninstallJsonMcpRuntime(spec: JsonMcpRuntimeSpec, runtime: RuntimeId, opts: UninstallOptions): InstallResult;
+export {};