@bharanidev/bhgraph-darwin-arm64 1.0.0

package/lib/dist/mcp/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAYtC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAwB;IAClC,OAAO,CAAC,WAAW,CAAc;IAIjC,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,MAAM,CAAS;IAGvB,OAAO,CAAC,SAAS,CAA0B;gBAE/B,IAAI,GAAE,gBAAqB;IAKvC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK7C,0EAA0E;IAC1E,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,yEAAyE;IACzE,cAAc,IAAI,WAAW;IAI7B,qDAAqD;IACrD,iBAAiB,IAAI,OAAO;IAI5B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAuB7C;;;OAGG;IACH,IAAI,IAAI,IAAI;YAiBE,YAAY;IAuB1B;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAuDrB;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E"}

package/lib/dist/mcp/engine.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link BHGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+exports.parseDebounceEnv = parseDebounceEnv;
+const os = __importStar(require("os"));
+const directory_1 = require("../directory");
+const sync_1 = require("../sync");
+const tools_1 = require("./tools");
+const query_pool_1 = require("./query-pool");
+// Lazy-load the heavy BHGraph chain (sqlite + query/graph/context layers) OFF
+// the MCP startup path. It's only needed once a tool actually opens a project —
+// not to answer initialize/tools-list — so deferring it lets `serve --mcp` (and
+// the daemon it spawns) bind + register tools in ~Node-startup time instead of
+// ~800ms, closing the "No such tool available" cold-start race that made headless
+// agents flounder. require() is sync + cached on the CommonJS build.
+const loadBHGraph = () => require('../index').default;
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+class MCPEngine {
+    cg = null;
+    toolHandler;
+    // Project root we resolved to. Null until `ensureInitialized` succeeds
+    // (or null forever if no .bhgraph/ ever turned up — that's a valid
+    // state for the engine, since cross-project queries still work).
+    projectPath = null;
+    // Set on first `ensureInitialized` so subsequent sessions don't redo work.
+    initPromise = null;
+    watcherStarted = false;
+    opts;
+    closed = false;
+    // Off-loop read-tool pool (daemon mode only). Created lazily once the default
+    // project is open — workers each hold their own WAL read connection.
+    queryPool = null;
+    constructor(opts = {}) {
+        this.opts = { watch: opts.watch ?? true, queryPool: opts.queryPool ?? false };
+        this.toolHandler = new tools_1.ToolHandler(null);
+    }
+    /**
+     * Start the worker-thread query pool once a default project is open (daemon
+     * mode only; honors `BHGRAPH_QUERY_POOL_SIZE`). Idempotent and best-effort:
+     * if workers can't spawn on this platform the ToolHandler keeps serving reads
+     * in-process, so the pool can only help, never break, tool calls.
+     */
+    maybeStartPool(root) {
+        if (!this.opts.queryPool || this.queryPool || this.closed)
+            return;
+        const size = (0, query_pool_1.resolvePoolSize)(process.env.BHGRAPH_QUERY_POOL_SIZE, os.cpus().length);
+        if (size <= 0) {
+            process.stderr.write('[BHGraph MCP] Query pool disabled (BHGRAPH_QUERY_POOL_SIZE=0); serving reads in-process.\n');
+            return;
+        }
+        try {
+            this.queryPool = new query_pool_1.QueryPool({ root, size });
+            this.toolHandler.setQueryPool(this.queryPool);
+            process.stderr.write(`[BHGraph MCP] Query pool: up to ${size} worker thread(s) for concurrent reads.\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[BHGraph MCP] Query pool unavailable (${msg}); serving reads in-process.\n`);
+            this.queryPool = null;
+        }
+    }
+    /**
+     * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+     * project path (from the `--path` CLI flag) without yet opening it. This
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath) {
+        this.projectPath = projectPath;
+        this.toolHandler.setDefaultProjectHint(projectPath);
+    }
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath() {
+        return this.projectPath;
+    }
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler() {
+        return this.toolHandler;
+    }
+    /** Whether the default project's BHGraph is open. */
+    hasDefaultBHGraph() {
+        return this.toolHandler.hasDefaultBHGraph();
+    }
+    /**
+     * Walk up from `searchFrom` to find the nearest `.bhgraph/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    async ensureInitialized(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultBHGraph())
+            return;
+        if (this.initPromise) {
+            try {
+                await this.initPromise;
+            }
+            catch { /* let caller retry */ }
+            return;
+        }
+        this.initPromise = this.doInitialize(searchFrom).finally(() => {
+            this.initPromise = null;
+        });
+        try {
+            await this.initPromise;
+        }
+        catch {
+            // Init errors are logged inside `doInitialize`; falling through here
+            // matches MCPServer's previous "retry on next tool call" behavior.
+        }
+    }
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom) {
+        if (this.closed)
+            return;
+        if (this.toolHandler.hasDefaultBHGraph())
+            return;
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestBHGraphRoot)(searchFrom);
+        if (!resolvedRoot)
+            return;
+        try {
+            // Close any previously failed instance to avoid leaking resources.
+            if (this.cg) {
+                try {
+                    this.cg.close();
+                }
+                catch { /* ignore */ }
+                this.cg = null;
+            }
+            this.cg = loadBHGraph().openSync(resolvedRoot);
+            this.projectPath = resolvedRoot;
+            this.toolHandler.setDefaultBHGraph(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+            this.maybeStartPool(resolvedRoot);
+        }
+        catch {
+            // Still failing — caller will try again on the next tool call.
+        }
+    }
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Detach + terminate the worker pool first so no tool call routes to a
+        // worker mid-teardown; outstanding pool calls resolve with graceful guidance.
+        this.toolHandler.setQueryPool(null);
+        if (this.queryPool) {
+            void this.queryPool.destroy();
+            this.queryPool = null;
+        }
+        this.toolHandler.closeAll();
+        if (this.cg) {
+            try {
+                this.cg.close();
+            }
+            catch { /* ignore */ }
+            this.cg = null;
+        }
+    }
+    async doInitialize(searchFrom) {
+        this.toolHandler.setDefaultProjectHint(searchFrom);
+        const resolvedRoot = (0, directory_1.findNearestBHGraphRoot)(searchFrom);
+        if (!resolvedRoot) {
+            // No .bhgraph/ above searchFrom. Sessions may still discover one later via roots/list
+            this.projectPath = searchFrom;
+            return;
+        }
+        this.projectPath = resolvedRoot;
+        try {
+            this.cg = await loadBHGraph().open(resolvedRoot);
+            this.toolHandler.setDefaultBHGraph(this.cg);
+            this.startWatching();
+            this.catchUpSync();
+            this.maybeStartPool(resolvedRoot);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[BHGraph MCP] Failed to open project at ${resolvedRoot}: ${msg}\n`);
+        }
+    }
+    /**
+     * Start file watching on the active BHGraph instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    startWatching() {
+        if (!this.cg || this.watcherStarted || !this.opts.watch)
+            return;
+        const disabledReason = (0, sync_1.watchDisabledReason)(this.projectPath ?? process.cwd());
+        if (disabledReason) {
+            process.stderr.write(`[BHGraph MCP] File watcher disabled — ${disabledReason}. ` +
+                `The graph will not auto-update; run \`bhgraph sync\` (or install the git sync hooks via \`bhgraph init\`) to refresh.\n`);
+            this.watcherStarted = true;
+            return;
+        }
+        // Optional override for the debounce window via env var (issue #403).
+        // Useful for workspaces with bursty writes (formatter-on-save chains,
+        // large generated outputs) where the 2s default fires too often. Clamped
+        // to [100ms, 60s]; out-of-range / non-numeric values fall back to the
+        // FileWatcher default. We log the active value so it's discoverable.
+        const debounceMs = parseDebounceEnv(process.env.BHGRAPH_WATCH_DEBOUNCE_MS);
+        if (debounceMs !== undefined) {
+            process.stderr.write(`[BHGraph MCP] File watcher debounce: ${debounceMs}ms (BHGRAPH_WATCH_DEBOUNCE_MS)\n`);
+        }
+        const started = this.cg.watch({
+            debounceMs,
+            onSyncComplete: (result) => {
+                if (result.filesChanged > 0) {
+                    process.stderr.write(`[BHGraph MCP] Auto-synced ${result.filesChanged} file(s) in ${result.durationMs}ms\n`);
+                }
+            },
+            onSyncError: (err) => {
+                process.stderr.write(`[BHGraph MCP] Auto-sync error: ${err.message}\n`);
+            },
+            onDegraded: (reason) => {
+                // Live watching gave up permanently (watch-resource exhaustion or a
+                // write lock held past the retry budget). Say so loudly and ONCE — the
+                // graph will no longer auto-update, so a long-running MCP session must
+                // not keep assuming it's fresh. The reason already names the remedy
+                // (`bhgraph sync` / git sync hooks).
+                process.stderr.write(`[BHGraph MCP] File watcher degraded — ${reason}\n`);
+            },
+        });
+        this.watcherStarted = true;
+        if (started) {
+            process.stderr.write('[BHGraph MCP] File watcher active — graph will auto-sync on changes\n');
+        }
+        else {
+            process.stderr.write('[BHGraph MCP] File watcher unavailable on this platform — run `bhgraph sync` to refresh the graph after changes.\n');
+        }
+    }
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    catchUpSync() {
+        const cg = this.cg;
+        if (!cg)
+            return;
+        const p = cg
+            .sync()
+            .then((result) => {
+            const changed = result.filesAdded + result.filesModified + result.filesRemoved;
+            if (changed > 0) {
+                process.stderr.write(`[BHGraph MCP] Caught up ${changed} file(s) changed since last run\n`);
+            }
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[BHGraph MCP] Catch-up sync failed: ${msg}\n`);
+        });
+        this.toolHandler.setCatchUpGate(p);
+    }
+}
+exports.MCPEngine = MCPEngine;
+/**
+ * Parse and clamp the BHGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+function parseDebounceEnv(raw) {
+    if (!raw || !raw.trim())
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return undefined;
+    if (n < 100 || n > 60000)
+        return undefined;
+    return n;
+}
+//# sourceMappingURL=engine.js.map

package/lib/dist/mcp/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"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"}

package/lib/dist/mcp/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * BHGraph MCP Server
+ *
+ * Model Context Protocol server that exposes BHGraph functionality
+ * as tools for AI assistants like Claude.
+ *
+ * @module mcp
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer } from 'bhgraph';
+ *
+ * const server = new MCPServer('/path/to/project');
+ * await server.start();
+ * ```
+ *
+ * Runtime modes (decided in {@link MCPServer.start}):
+ *
+ * - **Direct** — one process serves one MCP client over stdio. The pre-#411
+ *   behavior; used when the user opts out (`BHGRAPH_NO_DAEMON=1`), no
+ *   `.bhgraph/` is reachable, or the daemon machinery fails for any reason.
+ * - **Proxy** — what an MCP host actually talks to when sharing is on: a thin
+ *   stdio↔socket pipe to the shared daemon. The proxy carries the #277 PPID
+ *   watchdog, so a SIGKILL'd host reaps its proxy promptly. See {@link ./proxy.ts}.
+ * - **Daemon** — a *detached* background process (its own session/process
+ *   group) that serves N proxies over a Unix-domain socket / named pipe,
+ *   sharing one BHGraph + watcher + SQLite handle. Spawned on demand; never a
+ *   child of any host, so it survives individual sessions and is reaped by
+ *   client-refcount + idle timeout. See {@link ./daemon.ts} and issue #411.
+ *
+ * The detached-daemon + always-proxy split is the fix for the review finding
+ * that the original in-process daemon (a) was the first host's child, so closing
+ * that terminal severed every other client, and (b) disabled the PPID watchdog,
+ * regressing #277 (orphaned daemons on host SIGKILL).
+ */
+/**
+ * MCP Server for BHGraph
+ *
+ * Implements the Model Context Protocol to expose BHGraph
+ * functionality as tools that can be called by AI assistants.
+ *
+ * Backwards-compatible constructor and `start()` signature with the
+ * pre-issue-#411 implementation: callers continue to do
+ * `new MCPServer(path).start()`. Internally we now pick from direct / proxy /
+ * daemon at start time.
+ */
+export declare class MCPServer {
+    private projectPath;
+    private session;
+    private engine;
+    private daemon;
+    private ppidWatchdog;
+    private livenessWatchdog;
+    private originalPpid;
+    private hostPpid;
+    private stopped;
+    private mode;
+    constructor(projectPath?: string);
+    /**
+     * Start the MCP server.
+     *
+     * Decision order:
+     *   1. `BHGRAPH_NO_DAEMON=1` → direct mode (unchanged pre-#411 behavior).
+     *   2. `BHGRAPH_DAEMON_INTERNAL=1` → we ARE the detached daemon; listen.
+     *   3. No `.bhgraph/` reachable → direct mode (the daemon's lockfile and
+     *      socket both live under `.bhgraph/`).
+     *   4. Otherwise connect to (or spawn) the shared daemon and proxy to it.
+     *
+     * On any unexpected failure in step 4 we transparently fall back to direct
+     * mode — a misbehaving daemon must never block a session from starting.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server. In daemon mode this triggers graceful shutdown of every
+     * connected session; in direct mode it mirrors the pre-#411 behavior (close
+     * cg, exit). Proxy mode never routes through here — the proxy exits itself.
+     */
+    stop(): void;
+    /** Single-process stdio MCP session — the pre-issue-#411 code path. */
+    private startDirect;
+    /**
+     * Run as the detached shared daemon (process spawned with
+     * `BHGRAPH_DAEMON_INTERNAL=1`). Arbitrate the O_EXCL lock, then either
+     * become the daemon (bind the socket, serve forever) or — if a live daemon
+     * already holds the lock — exit so we don't leak a redundant process.
+     *
+     * No PPID watchdog and no stdin handlers: the daemon is detached on purpose
+     * and reaps itself via client-refcount + idle timeout (see {@link Daemon}).
+     */
+    private startDaemonProcess;
+    /**
+     * Proxy mode (the common case). Serve the MCP handshake LOCALLY for instant
+     * tool registration, forwarding tool calls to the shared daemon — which is
+     * connected in the background (probed, then spawned + polled if absent) so the
+     * handshake never waits ~600ms on it. Runs until the host disconnects; the
+     * proxy falls back to an in-process engine if the daemon never binds, so this
+     * never wedges a session.
+     */
+    private runProxyWithLocalHandshake;
+    /** Standard SIGINT/SIGTERM handlers that route to our `stop()` (direct mode). */
+    private installSignalHandlers;
+    /**
+     * PPID watchdog (#277) — direct mode only. Daemon mode is detached on purpose
+     * and reaps via idle timeout; proxy mode installs its own watchdog inside
+     * {@link runProxy}. So this only ever runs for an in-process direct session.
+     */
+    private installPpidWatchdog;
+}
+export { StdioTransport } from './transport';
+export { tools, ToolHandler } from './tools';
+export { Daemon } from './daemon';
+export { BHGraphPackageVersion } from './version';
+//# sourceMappingURL=index.d.ts.map

package/lib/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA8IH;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,WAAW,CAAgB;IAGnC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAA+C;IAGnE,OAAO,CAAC,gBAAgB,CAA+B;IAIvD,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAA4D;IAE5E,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAA4D;gBAE5D,WAAW,CAAC,EAAE,MAAM;IAIhC;;;;;;;;;;;;OAYG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C5B;;;;OAIG;IACH,IAAI,IAAI,IAAI;IA2BZ,uEAAuE;YACzD,WAAW;IA0CzB;;;;;;;;OAQG;YACW,kBAAkB;IAqChC;;;;;;;OAOG;YACW,0BAA0B;IAqCxC,iFAAiF;IACjF,OAAO,CAAC,qBAAqB;IAK7B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAoB5B;AAWD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC"}