aiden-runtime 4.8.1 → 4.9.1

package/dist/core/v4/mcp/install/clients.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/install/clients.ts — v4.9.0 Slice 2a.
+ *
+ * Single per-client adapter exposing read / write / install /
+ * uninstall helpers above the path + JSONC primitives. Claude Desktop
+ * and Cursor share most of the install flow; only the on-disk format
+ * (`json` vs `jsonc`) and the per-OS path differ — both already
+ * captured in `clientPaths.ts`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readClient = readClient;
+exports.planInstall = planInstall;
+exports.installClient = installClient;
+exports.uninstallClient = uninstallClient;
+exports.planUninstall = planUninstall;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const clientPaths_1 = require("./clientPaths");
+const jsoncMerge_1 = require("./jsoncMerge");
+const backup_1 = require("./backup");
+/**
+ * Read the current Aiden entry from a client's config. Returns null
+ * when the file doesn't exist OR the entry is absent.
+ */
+function readClient(clientId, override) {
+    const resolution = override ?? (0, clientPaths_1.resolveClientPath)(clientId);
+    if (!(0, node_fs_1.existsSync)(resolution.configPath)) {
+        return { resolution, entry: null, exists: false, text: null };
+    }
+    const text = (0, node_fs_1.readFileSync)(resolution.configPath, 'utf8');
+    return { resolution, entry: (0, jsoncMerge_1.readAidenEntry)(text, resolution.schema), exists: true, text };
+}
+/**
+ * Compute the new file content without writing. Used by `--dry-run`.
+ * Returns null when the parent directory doesn't exist (client not
+ * installed); caller surfaces this as a user-facing error.
+ */
+function planInstall(clientId, opts) {
+    const resolution = opts.pathOverride ?? (0, clientPaths_1.resolveClientPath)(clientId);
+    if (!(0, node_fs_1.existsSync)(resolution.parentDir)) {
+        return { resolution, newText: '', parentMissing: true };
+    }
+    const existingText = (0, node_fs_1.existsSync)(resolution.configPath)
+        ? (0, node_fs_1.readFileSync)(resolution.configPath, 'utf8')
+        : (0, jsoncMerge_1.emptyConfig)(resolution.format, resolution.schema);
+    const entry = (0, jsoncMerge_1.buildAidenEntryObject)({
+        command: opts.command,
+        args: opts.args,
+        envKeys: opts.envKeys,
+        profile: opts.profile,
+        schema: resolution.schema,
+    });
+    const newText = (0, jsoncMerge_1.mergeAidenEntry)(existingText, entry, resolution.format, resolution.schema);
+    return { resolution, newText, parentMissing: false };
+}
+/**
+ * Atomic write: tmp file → rename. Caller has already backed up the
+ * original via `backupConfig`.
+ */
+function atomicWrite(filepath, content) {
+    const dir = node_path_1.default.dirname(filepath);
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const tmp = `${filepath}.tmp-${process.pid}-${Date.now()}`;
+    (0, node_fs_1.writeFileSync)(tmp, content, 'utf8');
+    (0, node_fs_1.renameSync)(tmp, filepath);
+}
+/**
+ * Full install flow: backup → merge → atomic write. Skips the write
+ * (and skips creating a backup) when the existing entry already
+ * matches the canonical form.
+ */
+function installClient(clientId, opts) {
+    const planned = planInstall(clientId, opts);
+    if (!planned) {
+        return {
+            outcome: 'error',
+            configPath: '',
+            backupPath: null,
+            error: `Could not resolve config path for ${clientId}`,
+        };
+    }
+    if (planned.parentMissing) {
+        return {
+            outcome: 'error',
+            configPath: planned.resolution.configPath,
+            backupPath: null,
+            error: `${planned.resolution.displayName} not installed (parent dir ${planned.resolution.parentDir} missing).`,
+        };
+    }
+    // Idempotency: if the file already exists and its content is byte-
+    // identical to what we'd write, skip with no backup churn.
+    if ((0, node_fs_1.existsSync)(planned.resolution.configPath)) {
+        const currentText = (0, node_fs_1.readFileSync)(planned.resolution.configPath, 'utf8');
+        if (currentText === planned.newText) {
+            return {
+                outcome: 'noop',
+                configPath: planned.resolution.configPath,
+                backupPath: null,
+            };
+        }
+    }
+    let backupPath = null;
+    try {
+        backupPath = (0, backup_1.backupConfig)(planned.resolution.configPath);
+        atomicWrite(planned.resolution.configPath, planned.newText);
+        return {
+            outcome: 'written',
+            configPath: planned.resolution.configPath,
+            backupPath,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            configPath: planned.resolution.configPath,
+            backupPath,
+            error: err.message,
+        };
+    }
+}
+/**
+ * v4.9.0 Slice 2b — surgical removal of `<topKey>.aiden` from a
+ * client's config. Preserves every other server entry + every other
+ * top-level key. Creates a timestamped backup before writing.
+ *
+ * Returns `outcome: 'noop'` when the config file is missing or the
+ * entry isn't present — uninstall is idempotent.
+ */
+function uninstallClient(clientId, override) {
+    const resolution = override ?? (0, clientPaths_1.resolveClientPath)(clientId);
+    if (!(0, node_fs_1.existsSync)(resolution.configPath)) {
+        return {
+            outcome: 'noop',
+            configPath: resolution.configPath,
+            backupPath: null,
+            wasManaged: false,
+        };
+    }
+    const existingText = (0, node_fs_1.readFileSync)(resolution.configPath, 'utf8');
+    const existingEntry = (0, jsoncMerge_1.readAidenEntry)(existingText, resolution.schema);
+    if (!existingEntry) {
+        return {
+            outcome: 'noop',
+            configPath: resolution.configPath,
+            backupPath: null,
+            wasManaged: false,
+        };
+    }
+    const { text: newText, removed } = (0, jsoncMerge_1.removeAidenEntry)(existingText, resolution.format, resolution.schema);
+    if (!removed) {
+        return {
+            outcome: 'noop',
+            configPath: resolution.configPath,
+            backupPath: null,
+            wasManaged: existingEntry._aiden?.managed === true,
+        };
+    }
+    let backupPath = null;
+    try {
+        backupPath = (0, backup_1.backupConfig)(resolution.configPath);
+        atomicWrite(resolution.configPath, newText);
+        return {
+            outcome: 'removed',
+            configPath: resolution.configPath,
+            backupPath,
+            wasManaged: existingEntry._aiden?.managed === true,
+        };
+    }
+    catch (err) {
+        return {
+            outcome: 'error',
+            configPath: resolution.configPath,
+            backupPath,
+            wasManaged: existingEntry._aiden?.managed === true,
+            error: err.message,
+        };
+    }
+}
+/** Preview uninstall without writing. */
+function planUninstall(clientId, override) {
+    const resolution = override ?? (0, clientPaths_1.resolveClientPath)(clientId);
+    if (!(0, node_fs_1.existsSync)(resolution.configPath)) {
+        return { resolution, entry: null, newText: '', willRemove: false };
+    }
+    const existingText = (0, node_fs_1.readFileSync)(resolution.configPath, 'utf8');
+    const entry = (0, jsoncMerge_1.readAidenEntry)(existingText, resolution.schema);
+    if (!entry) {
+        return { resolution, entry: null, newText: existingText, willRemove: false };
+    }
+    const { text, removed } = (0, jsoncMerge_1.removeAidenEntry)(existingText, resolution.format, resolution.schema);
+    return { resolution, entry, newText: text, willRemove: removed };
+}

package/dist/core/v4/mcp/install/healthCheck.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/install/healthCheck.ts — v4.9.0 Slice 2a.
+ *
+ * Spawn `aiden mcp serve --health-check` (or whatever command the
+ * caller writes into the third-party config) as a subprocess and
+ * parse the JSON status line from stdout. Used by `init` after a
+ * successful write to surface "tools exposed: N, version: X" as
+ * immediate confirmation that the wired entry actually launches.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHealthCheck = runHealthCheck;
+const node_child_process_1 = require("node:child_process");
+const DEFAULT_TIMEOUT_MS = 5000;
+function runHealthCheck(opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const spawnFn = opts.spawnImpl ?? node_child_process_1.spawn;
+    return new Promise((resolve) => {
+        let child;
+        try {
+            // Append --health-check so the spawned `aiden mcp serve`
+            // emits a single JSON line + exits cleanly instead of
+            // running the stdio MCP loop.
+            child = spawnFn(opts.command, [...opts.args, '--health-check'], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            resolve({ ok: false, error: `Could not spawn ${opts.command}: ${err.message}` });
+            return;
+        }
+        let stdoutBuf = '';
+        let stderrBuf = '';
+        child.stdout?.on('data', (chunk) => {
+            stdoutBuf += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderrBuf += chunk.toString();
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* noop */ }
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, error: `Spawn failed: ${err.message}` });
+        });
+        child.on('close', () => {
+            clearTimeout(timer);
+            if (timedOut) {
+                resolve({ ok: false, error: `Health check timed out after ${timeoutMs}ms` });
+                return;
+            }
+            try {
+                const trimmed = stdoutBuf.trim();
+                const line = trimmed.split('\n').find((l) => l.startsWith('{')) ?? trimmed;
+                const parsed = JSON.parse(line);
+                if (parsed.status === 'ok') {
+                    resolve({ ok: true, status: 'ok', tools: parsed.tools, version: parsed.version });
+                }
+                else {
+                    resolve({ ok: false, error: `status=${parsed.status ?? '<missing>'}` });
+                }
+            }
+            catch (err) {
+                resolve({
+                    ok: false,
+                    error: `Could not parse health-check output: ${err.message}. stderr: ${stderrBuf.trim().slice(0, 200)}`,
+                });
+            }
+        });
+    });
+}

package/dist/core/v4/mcp/install/jsoncMerge.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/install/jsoncMerge.ts — v4.9.0 Slice 2a.
+ *
+ * Merge Aiden's `mcpServers.aiden` entry into a third-party client
+ * config file. Two formats:
+ *
+ *   format: 'json'   — Claude Desktop's claude_desktop_config.json,
+ *                      plain JSON. Round-trip via JSON.parse +
+ *                      JSON.stringify with 2-space indent.
+ *
+ *   format: 'jsonc'  — Cursor's mcp.json, JSON-with-comments. Round-
+ *                      tripping through JSON.parse destroys user
+ *                      comments + custom formatting. We use
+ *                      `jsonc-parser`'s `modify()` + `applyEdits()`
+ *                      to make a surgical edit that preserves the
+ *                      rest of the file verbatim.
+ *
+ * Either path is atomic from the caller's POV: this module returns
+ * the NEW file content as a string; the caller is responsible for
+ * tmp-file-then-rename.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAidenEntryObject = buildAidenEntryObject;
+exports.emptyConfig = emptyConfig;
+exports.mergeAidenEntry = mergeAidenEntry;
+exports.removeAidenEntry = removeAidenEntry;
+exports.readAidenEntry = readAidenEntry;
+const jsonc_parser_1 = require("jsonc-parser");
+const DEFAULT_SCHEMA = { topKey: 'mcpServers' };
+/** Produce the canonical Aiden entry. */
+function buildAidenEntryObject(opts) {
+    const entry = {
+        command: opts.command,
+        args: opts.args,
+        _aiden: {
+            managed: true,
+            version: 1,
+            ...(opts.profile ? { profile: opts.profile } : {}),
+        },
+    };
+    if (opts.schema?.requiresType) {
+        entry.type = 'stdio';
+    }
+    if (opts.envKeys && opts.envKeys.length > 0) {
+        entry.env = {};
+        for (const k of opts.envKeys)
+            entry.env[k] = `\${${k}}`;
+    }
+    return entry;
+}
+/**
+ * Build the empty starter content for a brand-new config file. Used
+ * when a client's parent dir exists but the config file doesn't.
+ * The starter mirrors the client's top-level schema so the next
+ * `modify()` call has a stable shape to edit into.
+ */
+function emptyConfig(format, schema = DEFAULT_SCHEMA) {
+    void format;
+    return `{\n  "${schema.topKey}": {}\n}\n`;
+}
+/**
+ * Merge `entry` into the existing JSON / JSONC text under
+ * `<topKey>.aiden` (where `topKey` is `'mcpServers'` for Claude/Cursor
+ * or `'servers'` for VS Code). Returns the new text. Existing
+ * siblings under `<topKey>.*` are preserved untouched; other top-
+ * level keys (Claude Desktop has many) are preserved untouched.
+ *
+ * v4.9.0 Slice 2b — `schema` parameter added (default keeps Slice 2a
+ * mcpServers behaviour). VS Code passes `{ topKey: 'servers' }`.
+ */
+function mergeAidenEntry(existingText, entry, format, schema = DEFAULT_SCHEMA) {
+    const topKey = schema.topKey;
+    if (format === 'json') {
+        let doc;
+        try {
+            doc = JSON.parse(existingText);
+        }
+        catch {
+            doc = {};
+        }
+        if (typeof doc !== 'object' || doc === null)
+            doc = {};
+        const servers = doc[topKey] ?? {};
+        servers.aiden = entry;
+        doc[topKey] = servers;
+        return JSON.stringify(doc, null, 2) + '\n';
+    }
+    // JSONC path: use modify() to produce a minimal edit that preserves
+    // comments + formatting outside the touched key path.
+    const formatOpts = { tabSize: 2, insertSpaces: true };
+    const path = [topKey, 'aiden'];
+    const tree = (0, jsonc_parser_1.parseTree)(existingText);
+    const root = tree;
+    let text = existingText;
+    if (!root || root.type !== 'object') {
+        text = emptyConfig('jsonc', schema);
+    }
+    else {
+        const mcpNode = (0, jsonc_parser_1.findNodeAtLocation)(root, [topKey]);
+        if (!mcpNode || mcpNode.type !== 'object') {
+            const edits = (0, jsonc_parser_1.modify)(text, [topKey], {}, { formattingOptions: formatOpts });
+            text = (0, jsonc_parser_1.applyEdits)(text, edits);
+        }
+    }
+    const edits = (0, jsonc_parser_1.modify)(text, path, entry, {
+        formattingOptions: formatOpts,
+    });
+    return (0, jsonc_parser_1.applyEdits)(text, edits);
+}
+/**
+ * Remove the Aiden entry from the existing text. Returns the new
+ * text + a boolean reporting whether anything was actually removed.
+ * Preserves all other `<topKey>.*` siblings + other top-level keys.
+ */
+function removeAidenEntry(existingText, format, schema = DEFAULT_SCHEMA) {
+    const topKey = schema.topKey;
+    if (format === 'json') {
+        let doc;
+        try {
+            doc = JSON.parse(existingText);
+        }
+        catch {
+            return { text: existingText, removed: false };
+        }
+        if (typeof doc !== 'object' || doc === null) {
+            return { text: existingText, removed: false };
+        }
+        const servers = doc[topKey];
+        if (!servers || typeof servers !== 'object' || !('aiden' in servers)) {
+            return { text: existingText, removed: false };
+        }
+        delete servers.aiden;
+        doc[topKey] = servers;
+        return { text: JSON.stringify(doc, null, 2) + '\n', removed: true };
+    }
+    const tree = (0, jsonc_parser_1.parseTree)(existingText);
+    if (!tree)
+        return { text: existingText, removed: false };
+    const aidenNode = (0, jsonc_parser_1.findNodeAtLocation)(tree, [topKey, 'aiden']);
+    if (!aidenNode)
+        return { text: existingText, removed: false };
+    const edits = (0, jsonc_parser_1.modify)(existingText, [topKey, 'aiden'], undefined, {
+        formattingOptions: { tabSize: 2, insertSpaces: true },
+    });
+    return { text: (0, jsonc_parser_1.applyEdits)(existingText, edits), removed: true };
+}
+/**
+ * Read the current Aiden entry (or null when absent) from text.
+ * Tolerates both formats; jsonc-parser handles plain JSON too.
+ * Pass `schema` for clients whose topKey differs from the default
+ * `mcpServers` (e.g. VS Code's `servers`).
+ */
+function readAidenEntry(existingText, schema = DEFAULT_SCHEMA) {
+    const tree = (0, jsonc_parser_1.parseTree)(existingText);
+    if (!tree)
+        return null;
+    const node = (0, jsonc_parser_1.findNodeAtLocation)(tree, [schema.topKey, 'aiden']);
+    if (!node)
+        return null;
+    try {
+        const segment = existingText.slice(node.offset, node.offset + node.length);
+        return JSON.parse(segment);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/v4/mcp/install/profiles.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/install/profiles.ts — v4.9.0 Slice 2b.
+ *
+ * Five user-facing profile names → three distinct tool allowlists.
+ * `browser` aliases to `general`; `research` aliases to `readonly`.
+ * Aliases reserve the namespace for future divergence without forcing
+ * users to relearn the command surface today.
+ *
+ * Profiles bridge to the existing toolBridge filter: at serve start,
+ * the CLI resolves the profile, then sets `AIDEN_MCP_ALLOW_DESTRUCTIVE`
+ * + `AIDEN_MCP_TOOL_ALLOWLIST` in the runtime env BEFORE
+ * `readToolBridgeEnv()` runs. `--profile <name>` always wins over
+ * inherited env values so the client-config-pinned profile is
+ * authoritative.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROFILE_NAMES = exports.CLIENT_DEFAULT_PROFILE = exports.PROFILES = void 0;
+exports.resolveProfile = resolveProfile;
+exports.applyProfileToEnv = applyProfileToEnv;
+const GENERAL = {
+    name: 'general',
+    description: 'All non-destructive tools (default for chat clients like Claude Desktop).',
+    tools: 'all-default',
+    allowDestructive: false,
+};
+const DEV = {
+    name: 'dev',
+    description: 'Developer tools: file ops, shell, code execution, browser, web.',
+    tools: [
+        'file_read', 'file_list', 'file_write', 'file_patch',
+        'shell_exec', 'execute_code', 'system_info',
+        'browser_navigate', 'browser_extract', 'browser_screenshot',
+        'web_search', 'fetch_url', 'fetch_page',
+        'skills_list', 'skill_view', 'spawn_sub_agent',
+        'session_search', 'recall_session',
+    ],
+    allowDestructive: true,
+};
+const READONLY = {
+    name: 'readonly',
+    description: 'Read-only: web/research/skills/memory inspection, no mutations.',
+    tools: [
+        'web_search', 'fetch_url', 'fetch_page', 'deep_research', 'youtube_search',
+        'file_read', 'file_list',
+        'skills_list', 'skill_view',
+        'session_search', 'recall_session',
+        'system_info',
+    ],
+    allowDestructive: false,
+};
+/** All 5 user-facing names. `browser` / `research` alias for now. */
+exports.PROFILES = {
+    general: GENERAL,
+    dev: DEV,
+    readonly: READONLY,
+    // Aliases — same object reference today; namespace reserved for
+    // future divergence (e.g. browser could drop file_read in v5).
+    browser: GENERAL,
+    research: READONLY,
+};
+/** Client → default profile when --profile is omitted. */
+exports.CLIENT_DEFAULT_PROFILE = {
+    claude: 'general', // chat client
+    cursor: 'dev', // code editor
+    vscode: 'dev', // code editor with workspace context
+};
+exports.PROFILE_NAMES = Object.keys(exports.PROFILES);
+/**
+ * Resolve a profile by explicit name or by client default. Throws
+ * on an unknown name with a clear "Available: ..." hint.
+ */
+function resolveProfile(name, clientId) {
+    if (name) {
+        const p = exports.PROFILES[name];
+        if (!p) {
+            throw new Error(`Unknown profile '${name}'. Available: ${exports.PROFILE_NAMES.join(', ')}`);
+        }
+        return p;
+    }
+    const fallback = exports.CLIENT_DEFAULT_PROFILE[clientId] ?? 'general';
+    return exports.PROFILES[fallback];
+}
+/**
+ * Apply a resolved profile to the env so `readToolBridgeEnv()` picks
+ * it up. Used by `aiden mcp serve --profile <name>` at startup.
+ *
+ * Pure mutation on the passed-in env object (defaults to
+ * `process.env`). Returns the previous values so callers can restore
+ * for tests; production code never restores.
+ */
+function applyProfileToEnv(profile, env = process.env) {
+    const allowlistBefore = env.AIDEN_MCP_TOOL_ALLOWLIST;
+    const destructiveBefore = env.AIDEN_MCP_ALLOW_DESTRUCTIVE;
+    env.AIDEN_MCP_ALLOW_DESTRUCTIVE = profile.allowDestructive ? '1' : '0';
+    if (profile.tools === 'all-default') {
+        delete env.AIDEN_MCP_TOOL_ALLOWLIST;
+    }
+    else {
+        env.AIDEN_MCP_TOOL_ALLOWLIST = profile.tools.join(',');
+    }
+    return { allowlistBefore, destructiveBefore };
+}

package/dist/core/v4/mcp/install/wslDetect.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/install/wslDetect.ts — v4.9.0 Slice 2a.
+ *
+ * Detect whether Aiden is running inside WSL. WSL users targeting a
+ * Windows-host MCP client (Claude Desktop / Cursor for Windows) need
+ * a `wsl.exe -d <distro> -- aiden mcp serve` command in the JSON
+ * entry, NOT a Linux path.
+ *
+ * Detection signals (any match → WSL):
+ *   1. `process.env.WSL_DISTRO_NAME` is set
+ *   2. `process.env.WSL_INTEROP` is set
+ *   3. `/proc/version` content contains "microsoft" or "WSL"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectWsl = detectWsl;
+exports.buildAidenEntry = buildAidenEntry;
+const node_fs_1 = require("node:fs");
+function detectWsl(opts = {}) {
+    const env = opts.env ?? process.env;
+    const readFile = opts.readFile ?? ((p) => (0, node_fs_1.readFileSync)(p, 'utf8'));
+    if (typeof env.WSL_DISTRO_NAME === 'string' && env.WSL_DISTRO_NAME.length > 0) {
+        return { inWsl: true, distro: env.WSL_DISTRO_NAME };
+    }
+    if (typeof env.WSL_INTEROP === 'string' && env.WSL_INTEROP.length > 0) {
+        return { inWsl: true, distro: env.WSL_DISTRO_NAME ?? null };
+    }
+    try {
+        const content = readFile('/proc/version').toLowerCase();
+        if (content.includes('microsoft') || content.includes('wsl')) {
+            return { inWsl: true, distro: env.WSL_DISTRO_NAME ?? null };
+        }
+    }
+    catch {
+        /* /proc/version unreadable — not on Linux, definitely not WSL */
+    }
+    return { inWsl: false, distro: null };
+}
+/**
+ * Build the `command` + `args` shape for the Aiden entry given the
+ * detected environment + target. When targeting a Windows host from
+ * within WSL, wrap the call in `wsl.exe -d <distro> -- aiden mcp serve`
+ * so the host-side Claude Desktop launches `aiden` via the WSL
+ * interop layer.
+ */
+function buildAidenEntry(opts = {}) {
+    const wsl = opts.wsl ?? detectWsl();
+    if (wsl.inWsl && opts.target === 'host') {
+        const distro = wsl.distro ?? 'default';
+        return {
+            command: 'wsl.exe',
+            args: ['-d', distro, '--', 'aiden', 'mcp', 'serve'],
+        };
+    }
+    return { command: 'aiden', args: ['mcp', 'serve'] };
+}