@alfe.ai/mcp-bundler 0.0.1 → 0.1.0

package/dist/index.cjs

@@ -1,4 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_os = require("node:os");
+let node_child_process = require("node:child_process");
+let node_util = require("node:util");
 //#region src/tool-naming.ts
 /**
 * Tool name sanitization and collision handling.
@@ -450,11 +455,598 @@ var McpBundler = class {
 	}
 };
 //#endregion
+//#region src/store.ts
+const DEFAULT_STORE_PATH = (0, node_path.join)((0, node_path.join)((0, node_os.homedir)(), ".alfe", "mcp"), "servers.json");
+/** Inter-process lock tunings — exported as constants so tests can override. */
+const LOCK_WAIT_MS = 5e3;
+const LOCK_RETRY_INTERVAL_MS = 25;
+const LOCK_STALE_MS = 1e4;
+/**
+* On-disk source of truth for the bundler's configured servers.
+*
+* Mutations go through `update()` (read-modify-write with atomic
+* temp+rename) so a concurrent writer (e.g. two `alfe mcp add` invocations
+* racing) can't lose data — the second writer reads the first's state.
+*
+* Schema is owner-tagged so `removeServersByOwner` can implement
+* integration uninstall without touching CLI-owned or manual entries.
+*/
+var Store = class {
+	storePath;
+	logger;
+	watcher;
+	watcherListeners = /* @__PURE__ */ new Set();
+	rewatchTimer;
+	constructor(opts = {}) {
+		this.storePath = opts.path ?? DEFAULT_STORE_PATH;
+		this.logger = opts.logger;
+	}
+	get path() {
+		return this.storePath;
+	}
+	read() {
+		if (!(0, node_fs.existsSync)(this.storePath)) return cloneEmpty();
+		try {
+			const raw = (0, node_fs.readFileSync)(this.storePath, "utf8");
+			return normalize(JSON.parse(raw));
+		} catch (err) {
+			this.logger?.warn("[mcp-bundler/store] failed to read store; returning empty", {
+				err: errMsg$1(err),
+				path: this.storePath
+			});
+			return cloneEmpty();
+		}
+	}
+	/**
+	* Read-modify-write with atomic temp+rename, guarded by an
+	* inter-process lock file. Caller passes a pure function that
+	* produces the next state; this serialises the mutation to disk in
+	* one rename, which is atomic on POSIX and on Windows when the
+	* target path is on the same volume.
+	*
+	* The lock guards the read-then-rename window so two processes
+	* (e.g. two `alfe mcp add` shells, or the CLI racing the daemon)
+	* can't drop each other's writes. The lock file is at
+	* `<storePath>.lock`; stale locks (older than `LOCK_STALE_MS`) are
+	* stolen so a crashed writer doesn't wedge the store.
+	*
+	* Pure-function shape (instead of a `read()` then `write(next)`
+	* pair) intentionally — it keeps the read-modify-write contract
+	* local to each caller so two updates back-to-back never see each
+	* other's partial state.
+	*/
+	update(fn) {
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(this.storePath), { recursive: true });
+		const release = this.acquireLock();
+		try {
+			const next = fn(this.read());
+			const tempPath = `${this.storePath}.${String(process.pid)}.${String(Date.now())}.tmp`;
+			(0, node_fs.writeFileSync)(tempPath, JSON.stringify(next, null, 2), {
+				encoding: "utf8",
+				mode: 384
+			});
+			try {
+				(0, node_fs.renameSync)(tempPath, this.storePath);
+			} catch (err) {
+				try {
+					(0, node_fs.unlinkSync)(tempPath);
+				} catch {}
+				throw err;
+			}
+			return next;
+		} finally {
+			release();
+		}
+	}
+	/**
+	* Acquire an inter-process file lock by atomically creating a
+	* sentinel via `openSync(lockPath, 'wx')`. Spins with bounded
+	* backoff up to `LOCK_WAIT_MS`. If the lock file is older than
+	* `LOCK_STALE_MS` it's assumed orphaned (writer crashed mid-update)
+	* and stolen — the write window is sub-second in practice, so
+	* holding the lock for >5s means something went wrong.
+	*
+	* Returns the release function. Single-process callers are
+	* unaffected — re-entering the same process spins briefly while
+	* the prior call's `finally` runs.
+	*/
+	acquireLock() {
+		const lockPath = `${this.storePath}.lock`;
+		const deadline = Date.now() + LOCK_WAIT_MS;
+		let fd = -1;
+		for (;;) try {
+			fd = (0, node_fs.openSync)(lockPath, "wx", 384);
+			break;
+		} catch (err) {
+			if (err.code !== "EEXIST") throw err;
+			if (this.lockIsStale(lockPath)) {
+				try {
+					(0, node_fs.unlinkSync)(lockPath);
+				} catch {}
+				continue;
+			}
+			if (Date.now() >= deadline) throw new Error(`Store.update: timed out waiting for ${lockPath} (held by another writer or stale lock)`);
+			const sleepUntil = Date.now() + LOCK_RETRY_INTERVAL_MS;
+			while (Date.now() < sleepUntil);
+		}
+		const held = fd;
+		return () => {
+			try {
+				(0, node_fs.closeSync)(held);
+			} catch {}
+			try {
+				(0, node_fs.unlinkSync)(lockPath);
+			} catch {}
+		};
+	}
+	lockIsStale(lockPath) {
+		try {
+			const st = (0, node_fs.statSync)(lockPath);
+			return Date.now() - st.mtimeMs > LOCK_STALE_MS;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Watch the store file for external changes (e.g. another `alfe mcp add`
+	* shelling out from a separate process). Returns an unsubscribe fn.
+	*
+	* Coalesces bursts via a 50 ms debounce — editors and atomic-rename
+	* writers commonly fire multiple events per logical save.
+	*/
+	watch(cb) {
+		this.watcherListeners.add(cb);
+		this.ensureWatcher();
+		return () => {
+			this.watcherListeners.delete(cb);
+			if (this.watcherListeners.size === 0) this.disposeWatcher();
+		};
+	}
+	dispose() {
+		this.watcherListeners.clear();
+		this.disposeWatcher();
+	}
+	ensureWatcher() {
+		if (this.watcher) return;
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(this.storePath), { recursive: true });
+		const dir = (0, node_path.dirname)(this.storePath);
+		const basename = this.storePath.slice(dir.length + 1);
+		let pending;
+		const fire = () => {
+			pending = void 0;
+			for (const cb of this.watcherListeners) try {
+				cb();
+			} catch (err) {
+				this.logger?.warn("[mcp-bundler/store] watcher listener threw", { err: errMsg$1(err) });
+			}
+		};
+		try {
+			this.watcher = (0, node_fs.watch)(dir, (_event, fn) => {
+				if (fn !== basename) return;
+				if (pending) clearTimeout(pending);
+				pending = setTimeout(fire, 50);
+			});
+			this.watcher.on("error", (err) => {
+				this.logger?.warn("[mcp-bundler/store] watcher error; retrying in 1s", { err: errMsg$1(err) });
+				this.disposeWatcher();
+				if (!this.rewatchTimer && this.watcherListeners.size > 0) {
+					this.rewatchTimer = setTimeout(() => {
+						this.rewatchTimer = void 0;
+						this.ensureWatcher();
+					}, 1e3);
+					this.rewatchTimer.unref();
+				}
+			});
+		} catch (err) {
+			this.logger?.warn("[mcp-bundler/store] failed to start watcher", { err: errMsg$1(err) });
+		}
+	}
+	disposeWatcher() {
+		if (this.watcher) {
+			try {
+				this.watcher.close();
+			} catch {}
+			this.watcher = void 0;
+		}
+		if (this.rewatchTimer) {
+			clearTimeout(this.rewatchTimer);
+			this.rewatchTimer = void 0;
+		}
+	}
+};
+function defaultStorePath() {
+	return DEFAULT_STORE_PATH;
+}
+/** Pull the runtime config (transport + transport-specific fields) out of a stored entry. */
+function toServerConfig(entry) {
+	if (entry.transport === "stdio") {
+		const { command, args, env, cwd } = entry;
+		const cfg = { command };
+		if (args) cfg.args = args;
+		if (env) cfg.env = env;
+		if (cwd) cfg.cwd = cwd;
+		return cfg;
+	}
+	const { url, transport, headers, connectionTimeoutMs } = entry;
+	const cfg = {
+		url,
+		transport
+	};
+	if (headers) cfg.headers = headers;
+	if (connectionTimeoutMs !== void 0) cfg.connectionTimeoutMs = connectionTimeoutMs;
+	return cfg;
+}
+/** Build a stored entry from a runtime config + ownership metadata. */
+function toStoredEntry(config, meta) {
+	const addedAt = meta.addedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+	if ("command" in config) return {
+		transport: "stdio",
+		owner: meta.owner,
+		addedAt,
+		...meta.version !== void 0 ? { version: meta.version } : {},
+		...config
+	};
+	const transport = meta.transport ?? config.transport ?? "sse";
+	if (transport === "stdio") throw new Error("toStoredEntry: transport=stdio specified but config is remote-shaped");
+	return {
+		transport,
+		owner: meta.owner,
+		addedAt,
+		...meta.version !== void 0 ? { version: meta.version } : {},
+		...config
+	};
+}
+function cloneEmpty() {
+	return {
+		servers: {},
+		config: {},
+		_ownedOpenclawKeys: []
+	};
+}
+function normalize(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return cloneEmpty();
+	const r = raw;
+	return {
+		servers: r.servers && typeof r.servers === "object" ? r.servers : {},
+		config: r.config && typeof r.config === "object" ? r.config : {},
+		_ownedOpenclawKeys: Array.isArray(r._ownedOpenclawKeys) ? r._ownedOpenclawKeys.slice() : []
+	};
+}
+function errMsg$1(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/manager.ts
+const execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
+const defaultOpenclawExecutor = {
+	async setBatch(batch) {
+		if (batch.length === 0) return;
+		await execFileAsync("openclaw", [
+			"config",
+			"set",
+			"--batch-json",
+			JSON.stringify(batch)
+		], { timeout: 1e4 });
+	},
+	async unset(path) {
+		await execFileAsync("openclaw", [
+			"config",
+			"unset",
+			path
+		], { timeout: 1e4 });
+	}
+};
+const DEFAULT_MIRROR_DEBOUNCE_MS = 250;
+/**
+* Bundler manager — owns the alfe store, mirrors it into openclaw.json,
+* and surfaces a small CRUD API the CLI and integration applier both
+* call into.
+*
+* The store is the Alfe-owned source of truth; openclaw.json is a
+* derived mirror so the runtime keeps consuming its existing format.
+*/
+var Manager = class {
+	store;
+	executor;
+	logger;
+	mirrorDebounceMs;
+	mirrorTimer;
+	mirrorPromise = Promise.resolve();
+	mirrorPending;
+	bundler;
+	changeListeners = /* @__PURE__ */ new Set();
+	storeUnsubscribe;
+	constructor(opts = {}) {
+		this.store = opts.store ?? new Store({ logger: opts.logger });
+		this.executor = opts.executor ?? defaultOpenclawExecutor;
+		this.logger = opts.logger;
+		this.mirrorDebounceMs = opts.mirrorDebounceMs ?? DEFAULT_MIRROR_DEBOUNCE_MS;
+	}
+	/** Direct accessor — handy for tests and the CLI's `alfe mcp list`. */
+	getStore() {
+		return this.store;
+	}
+	/**
+	* Register or overwrite a server entry. Resolves as soon as the store
+	* mutation is committed to disk — the openclaw.json mirror runs async
+	* in the background and is debounced so back-to-back calls coalesce
+	* into one runtime restart. Call `flush()` to await the mirror.
+	*/
+	async addServer(config, opts) {
+		if (!opts.id) throw new Error("Manager.addServer: id is required");
+		const owner = opts.owner ?? "manual";
+		this.store.update((cur) => {
+			const previousAddedAt = lookupAddedAt(cur.servers, opts.id);
+			const entry = toStoredEntry(config, {
+				owner,
+				transport: opts.transport,
+				version: opts.version,
+				addedAt: previousAddedAt
+			});
+			return {
+				...cur,
+				servers: {
+					...cur.servers,
+					[opts.id]: entry
+				}
+			};
+		});
+		this.scheduleMirror();
+		this.fireChange();
+		return Promise.resolve();
+	}
+	/**
+	* Remove a single server entry. No-op if the id isn't in the store.
+	* Refuses to remove an entry whose owner doesn't match `expectedOwner`
+	* when supplied — the CLI uses this to guard `alfe mcp remove` from
+	* accidentally clobbering integration- or cli-owned entries.
+	*
+	* Resolves as soon as the store mutation is committed. Mirror runs
+	* async; call `flush()` to await it.
+	*/
+	removeServer(id, opts = {}) {
+		const existing = lookupEntry(this.store.read().servers, id);
+		if (!existing) return Promise.resolve(false);
+		if (opts.expectedOwner && existing.owner !== opts.expectedOwner) return Promise.reject(/* @__PURE__ */ new Error(`Manager.removeServer: server "${id}" is owned by "${existing.owner}", not "${opts.expectedOwner}"`));
+		this.store.update((cur) => ({
+			...cur,
+			servers: Object.fromEntries(Object.entries(cur.servers).filter(([k]) => k !== id))
+		}));
+		this.scheduleMirror();
+		this.fireChange();
+		return Promise.resolve(true);
+	}
+	/** Drop every entry whose owner matches — used by integration uninstall. */
+	async removeServersByOwner(owner) {
+		const removed = [];
+		this.store.update((cur) => {
+			const next = {};
+			for (const [id, entry] of Object.entries(cur.servers)) if (entry.owner === owner) removed.push(id);
+			else next[id] = entry;
+			if (removed.length === 0) return cur;
+			return {
+				...cur,
+				servers: next
+			};
+		});
+		if (removed.length > 0) {
+			this.scheduleMirror();
+			this.fireChange();
+		}
+		return Promise.resolve(removed);
+	}
+	/** Read-only snapshot for `alfe mcp list` and similar UIs. */
+	listServers() {
+		const snap = this.store.read();
+		return Object.entries(snap.servers).map(([id, entry]) => ({
+			id,
+			entry
+		}));
+	}
+	/**
+	* Push the current store contents into a bundler instance (which owns
+	* connections / tools). Wires up a store watcher so external mutations
+	* (e.g. another shell running `alfe mcp add`) re-reconcile.
+	*/
+	async loadIntoBundler(bundler) {
+		this.bundler = bundler;
+		await this.reconcileBundler();
+		this.storeUnsubscribe ??= this.store.watch(() => {
+			this.reconcileBundler().catch((err) => {
+				this.logger?.warn("[mcp-bundler/manager] watcher reconcile failed", { err: errMsg(err) });
+			});
+		});
+	}
+	/** Subscribe to store mutations. Returns an unsubscribe fn. */
+	onChange(cb) {
+		this.changeListeners.add(cb);
+		return () => {
+			this.changeListeners.delete(cb);
+		};
+	}
+	/**
+	* Cancel any pending mirror-write, flush the in-flight one, and stop
+	* watching the store. Safe to call multiple times.
+	*/
+	async dispose() {
+		if (this.mirrorTimer) {
+			clearTimeout(this.mirrorTimer);
+			this.mirrorTimer = void 0;
+			await this.runMirror();
+		}
+		await this.mirrorPromise.catch(() => void 0);
+		if (this.storeUnsubscribe) {
+			this.storeUnsubscribe();
+			this.storeUnsubscribe = void 0;
+		}
+		this.store.dispose();
+		this.changeListeners.clear();
+		this.bundler = void 0;
+	}
+	/**
+	* Force the debounced mirror to run now and wait for it to finish.
+	* Surfaces the executor error if the mirror failed — callers wrap in
+	* try/catch (or .rejects in tests) if they need to handle it.
+	*/
+	async flush() {
+		if (this.mirrorTimer) {
+			clearTimeout(this.mirrorTimer);
+			this.mirrorTimer = void 0;
+			await this.runMirror();
+		}
+		await this.mirrorPromise;
+	}
+	scheduleMirror() {
+		if (this.mirrorPending) return;
+		this.mirrorPromise = new Promise((resolve, reject) => {
+			this.mirrorPending = {
+				resolve,
+				reject
+			};
+		});
+		this.mirrorTimer = setTimeout(() => {
+			this.mirrorTimer = void 0;
+			this.runMirror();
+		}, this.mirrorDebounceMs);
+		this.mirrorTimer.unref();
+	}
+	async runMirror() {
+		const pending = this.mirrorPending;
+		this.mirrorPending = void 0;
+		try {
+			await this.applyMirror();
+			pending?.resolve();
+		} catch (err) {
+			pending?.reject(err);
+			this.logger?.error("[mcp-bundler/manager] mirror write failed", { err: errMsg(err) });
+		}
+	}
+	/**
+	* Compute the diff between this manager's owned set and what the store
+	* declares now, then apply the openclaw config delta. Foreign keys
+	* (entries in openclaw.json#mcp.servers.* not in our store) are
+	* preserved — we only touch the names we previously claimed.
+	*/
+	async applyMirror() {
+		let previousOwned = [];
+		let desiredOwned = [];
+		let batch = [];
+		this.store.update((cur) => {
+			previousOwned = cur._ownedOpenclawKeys.slice();
+			const entries = Object.entries(cur.servers);
+			desiredOwned = entries.map(([id]) => id).sort();
+			batch = entries.flatMap(([id, entry]) => renderEntryToBatch(id, entry));
+			return {
+				...cur,
+				_ownedOpenclawKeys: desiredOwned
+			};
+		});
+		await this.executor.setBatch(batch);
+		const toUnset = previousOwned.filter((k) => !desiredOwned.includes(k));
+		for (const id of toUnset) try {
+			await this.executor.unset(`mcp.servers.${id}`);
+		} catch (err) {
+			this.logger?.warn("[mcp-bundler/manager] mirror unset failed (continuing)", {
+				err: errMsg(err),
+				key: `mcp.servers.${id}`
+			});
+		}
+		if (this.bundler) try {
+			await this.reconcileBundler();
+		} catch (err) {
+			this.logger?.warn("[mcp-bundler/manager] post-mirror reconcile failed", { err: errMsg(err) });
+		}
+	}
+	async reconcileBundler() {
+		if (!this.bundler) return;
+		const snap = this.store.read();
+		const servers = {};
+		for (const [id, entry] of Object.entries(snap.servers)) servers[id] = toServerConfig(entry);
+		await this.bundler.reconcile(servers);
+	}
+	fireChange() {
+		for (const cb of this.changeListeners) try {
+			cb();
+		} catch (err) {
+			this.logger?.warn("[mcp-bundler/manager] onChange listener threw", { err: errMsg(err) });
+		}
+	}
+};
+/**
+* Render one store entry as the set of dotted-path batch entries that
+* `openclaw config set --batch-json` expects.
+*
+* Mirrors the format the integrations applier already emits today so the
+* runtime sees the same shape regardless of which writer produced it.
+*/
+function renderEntryToBatch(id, entry) {
+	const prefix = `mcp.servers.${id}`;
+	const out = [];
+	if (entry.transport === "stdio") {
+		out.push({
+			path: `${prefix}.command`,
+			value: entry.command
+		});
+		if (entry.args && entry.args.length > 0) out.push({
+			path: `${prefix}.args`,
+			value: entry.args
+		});
+		if (entry.env) for (const [k, v] of Object.entries(entry.env)) out.push({
+			path: `${prefix}.env.${k}`,
+			value: v
+		});
+		if (entry.cwd) out.push({
+			path: `${prefix}.cwd`,
+			value: entry.cwd
+		});
+		return out;
+	}
+	out.push({
+		path: `${prefix}.url`,
+		value: entry.url
+	});
+	out.push({
+		path: `${prefix}.transport`,
+		value: entry.transport
+	});
+	if (entry.headers) for (const [k, v] of Object.entries(entry.headers)) out.push({
+		path: `${prefix}.headers.${k}`,
+		value: v
+	});
+	if (entry.connectionTimeoutMs !== void 0) out.push({
+		path: `${prefix}.connectionTimeoutMs`,
+		value: entry.connectionTimeoutMs
+	});
+	return out;
+}
+function errMsg(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Indexed access on `Record<string, T>` returns `T` (not `T | undefined`)
+* unless `noUncheckedIndexedAccess` is set in tsconfig. These helpers
+* make the optional-ness explicit so the lint rules that hate
+* always-truthy conditionals stop firing on real lookups.
+*/
+function lookupEntry(servers, id) {
+	return Object.hasOwn(servers, id) ? servers[id] : void 0;
+}
+function lookupAddedAt(servers, id) {
+	const entry = lookupEntry(servers, id);
+	return entry ? entry.addedAt : void 0;
+}
+//#endregion
 exports.Connection = Connection;
+exports.Manager = Manager;
 exports.McpBundler = McpBundler;
 exports.STDIO_ENV_DENYLIST = STDIO_ENV_DENYLIST;
+exports.Store = Store;
 exports.buildNamespacedToolName = buildNamespacedToolName;
 exports.defaultConnect = defaultConnect;
+exports.defaultOpenclawExecutor = defaultOpenclawExecutor;
+exports.defaultStorePath = defaultStorePath;
 exports.disambiguateAgainst = disambiguateAgainst;
 exports.sanitizeNameSegment = sanitizeNameSegment;
 exports.sanitizeStdioEnv = sanitizeStdioEnv;
+exports.toServerConfig = toServerConfig;
+exports.toStoredEntry = toStoredEntry;