seer-mcp 0.1.0

package/dist/indexer/symbolhistory.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSymbolHistory = buildSymbolHistory;
+const git_js_1 = require("./git.js");
+const continuity_js_1 = require("./continuity.js");
+async function buildSymbolHistory(repoRoot, store, options = {}) {
+    const start = Date.now();
+    const log = options.log ?? ((m) => process.stderr.write(`[symbol-history] ${m}\n`));
+    if (!(0, git_js_1.isGitRepo)(repoRoot)) {
+        log('not a git repo, skipping');
+        return { filesProcessed: 0, symbolsProcessed: 0, historyRowsInserted: 0, skipped: true, elapsedMs: Date.now() - start };
+    }
+    const head = (0, git_js_1.gitHeadSha)(repoRoot);
+    const state = store.getGitIndexState();
+    // Skip only if symbol-history specifically has already been built against
+    // this HEAD. Reading `lastHistoryHeadSha` instead of the generic
+    // `lastHeadSha` means a previous file-level churn pass (which also stamps
+    // git_index_state) can't trick us into skipping when history was never
+    // actually built.
+    if (options.skipIfHeadUnchanged !== false && state && state.lastHistoryHeadSha === head && head !== null) {
+        log(`HEAD ${head?.slice(0, 8)} unchanged; skipping`);
+        return { filesProcessed: 0, symbolsProcessed: 0, historyRowsInserted: 0, skipped: true, elapsedMs: Date.now() - start };
+    }
+    const remote = (0, git_js_1.gitRemoteUrl)(repoRoot);
+    const maxCommits = options.maxCommitsPerFile ?? 200;
+    const symbols = store.listSymbolsForHistoryIndex();
+    if (symbols.length === 0) {
+        return { filesProcessed: 0, symbolsProcessed: 0, historyRowsInserted: 0, skipped: false, elapsedMs: Date.now() - start };
+    }
+    // Group symbols by file path so we walk `git log` once per file.
+    const byFile = new Map();
+    for (const s of symbols) {
+        let arr = byFile.get(s.filePath);
+        if (!arr) {
+            arr = [];
+            byFile.set(s.filePath, arr);
+        }
+        arr.push(s);
+    }
+    let totalInserts = 0;
+    let processedFiles = 0;
+    for (const [filePath, fileSymbols] of byFile) {
+        processedFiles++;
+        const commits = await (0, git_js_1.commitsForFile)(repoRoot, filePath, { limit: maxCommits, since: options.since });
+        if (commits.length === 0)
+            continue;
+        // For each commit, fetch its diff hunks (in the new-file coordinate
+        // space). A symbol whose [line_start..line_end] range overlaps any hunk
+        // is considered touched.
+        for (let i = 0; i < commits.length; i++) {
+            const c = commits[i];
+            // Use the per-commit path resolved from `git log --follow --name-status`.
+            // If that wasn't available (older git or no rename detected), fall back
+            // to the current path — that's correct for commits where the file
+            // hadn't been renamed.
+            const lookupPath = c.pathAtCommit ?? filePath;
+            const info = await (0, git_js_1.fileDiffInfo)(repoRoot, c.sha, lookupPath);
+            if (info.hunks.length === 0 && !info.isFileAddition)
+                continue;
+            const totalAdded = info.hunks.reduce((acc, h) => acc + h.newLines, 0);
+            const totalRemoved = info.hunks.reduce((acc, h) => acc + h.oldLines, 0);
+            const prNum = (0, git_js_1.extractPrNumber)(c.message);
+            const prUrl = prNum != null ? (0, git_js_1.githubPrUrl)(remote, prNum) : null;
+            for (const sym of fileSymbols) {
+                // The current symbol's line span is in the HEAD file. As commits get
+                // older, line numbers drift — so we accept any overlap in any commit
+                // as "this commit touched the line range that now holds this symbol".
+                // confidence drops with commit age to flag the drift.
+                //
+                // Special case: if this commit added the file (isFileAddition), the
+                // pre-commit state had no symbols at all — every current symbol
+                // got its initial existence from this commit, so attribute all of
+                // them regardless of where the hunk lines up. Match strategy
+                // 'file-addition' so the caller can tell apart "this commit
+                // created the file" from "this commit overlapped the symbol".
+                const symStart = sym.lineStart + 1; // git is 1-indexed
+                const symEnd = sym.lineEnd + 1;
+                let strategy;
+                if (info.isFileAddition) {
+                    strategy = 'file-addition';
+                }
+                else {
+                    const overlaps = info.hunks.some(h => {
+                        const hStart = h.newStart;
+                        const hEnd = h.newStart + Math.max(0, h.newLines - 1);
+                        return hStart <= symEnd && hEnd >= symStart;
+                    });
+                    if (!overlaps)
+                        continue;
+                    strategy = 'overlap';
+                }
+                const ageDays = Math.max(0, (Date.now() / 1000 - c.committedAt) / 86400);
+                // Confidence: 1.0 for HEAD..HEAD~1, decays with age but never below 0.3.
+                const confidence = Math.max(0.3, 1.0 - Math.min(0.7, ageDays / 365 * 0.1));
+                store.insertSymbolHistory(sym.id, sym.symbolKey, c.sha, c.authorName, c.authorEmail, c.committedAt, c.message, totalAdded, totalRemoved, prNum, prUrl, strategy, confidence);
+                totalInserts++;
+            }
+        }
+    }
+    // v10 — run the continuity heuristics for symbols whose recorded history is
+    // shallow. Strictly additive (lives in symbol_history_continuity); never
+    // touches symbol_history rows.
+    try {
+        if (store.hasV10()) {
+            const cont = (0, continuity_js_1.buildContinuity)(store, { historyThreshold: 1 });
+            log(`continuity: considered=${cont.candidatesConsidered}, inserted=${cont.inserted}, skipped=${cont.skipped}`);
+        }
+    }
+    catch (err) {
+        log(`continuity pass failed: ${err.message}`);
+    }
+    // Stamp the history-specific HEAD marker (not the generic one) so a future
+    // run can skip this work without colliding with file-level churn's stamp.
+    store.setHistoryHeadSha(repoRoot, head, remote);
+    log(`done: ${processedFiles} files, ${totalInserts} history rows`);
+    return {
+        filesProcessed: processedFiles,
+        symbolsProcessed: symbols.length,
+        historyRowsInserted: totalInserts,
+        skipped: false,
+        elapsedMs: Date.now() - start,
+    };
+}
+//# sourceMappingURL=symbolhistory.js.map

package/dist/indexer/symbolhistory.js.map

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

package/dist/indexer/watcher.d.ts

@@ -0,0 +1,68 @@
+import { Store } from '../db/store.js';
+import { Indexer } from './index.js';
+export interface WatcherOptions {
+    /** Debounce window in ms before triggering a reindex pass. Default 250ms. */
+    debounceMs?: number;
+    /** Logger; default writes to stderr (so stdio MCP isn't polluted). */
+    log?: (msg: string) => void;
+    /**
+     * Skip these paths. Defaults match the indexer's ignore list — we don't
+     * want chokidar to fire on `node_modules/` updates that the index would
+     * skip anyway. The list is intentionally narrower than the full glob; the
+     * indexer's `discoverFiles()` re-applies all rules at reindex time.
+     */
+    ignored?: (string | RegExp)[];
+}
+export declare class SeerWatcher {
+    private repoRoot;
+    private store;
+    private indexer;
+    private watcher;
+    private dirty;
+    private debounceTimer;
+    private indexing;
+    private indexingQueue;
+    private lastSyncMs;
+    private lastSyncResult;
+    private logFn;
+    private debounceMs;
+    constructor(repoRoot: string, store: Store, indexer: Indexer, options?: WatcherOptions);
+    /**
+     * Start watching. Idempotent: calling twice is a no-op.
+     */
+    start(): void;
+    stop(): Promise<void>;
+    /** Whether anything is currently waiting to be reindexed. */
+    isDirty(): boolean;
+    dirtyCount(): number;
+    /**
+     * Snapshot for `seer_health`: when did we last reconcile, how many files,
+     * how long did it take. Lets agents tell whether the index they're querying
+     * is "this happened just now" vs "we haven't run in 10 minutes."
+     */
+    syncStatus(): {
+        watching: boolean;
+        dirtyCount: number;
+        indexing: boolean;
+        lastSyncMs: number;
+        lastSync: {
+            dirtyReindexed: number;
+            added: number;
+            removed: number;
+            elapsedMs: number;
+        } | null;
+    };
+    /**
+     * Force an immediate sync, bypassing the debounce. Used by `seer_reindex`
+     * and JIT — both need the dirty set drained NOW, not when a timer fires.
+     */
+    syncNow(): Promise<void>;
+    private scheduleSync;
+    /**
+     * Reindex the workspace. Serialized — if a sync is already running, we
+     * queue at most one follow-up and coalesce further requests into it. This
+     * matches the indexer's contract that only one writer can be active.
+     */
+    private runSync;
+}
+//# sourceMappingURL=watcher.d.ts.map

package/dist/indexer/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/indexer/watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AA0BrC,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC/B;AAED,qBAAa,WAAW;IAYpB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,OAAO;IAbjB,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,cAAc,CAA8F;IACpH,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,UAAU,CAAS;gBAGjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EACxB,OAAO,GAAE,cAAmB;IAM9B;;OAEG;IACH,KAAK,IAAI,IAAI;IAyCP,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,6DAA6D;IAC7D,OAAO,IAAI,OAAO;IAIlB,UAAU,IAAI,MAAM;IAEpB;;;;OAIG;IACH,UAAU,IAAI;QACZ,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE;YAAE,cAAc,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;KAChG;IAUD;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,YAAY;IAUpB;;;;OAIG;YACW,OAAO;CAgCtB"}

package/dist/indexer/watcher.js

@@ -0,0 +1,179 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeerWatcher = void 0;
+const path_1 = __importDefault(require("path"));
+/**
+ * Background file watcher that keeps the index warm.
+ *
+ * Design split:
+ *   - Watcher (this module) reacts to file events and marks files dirty in a
+ *     shared in-memory set. Debounces bursts so a `git checkout` doesn't
+ *     hammer the indexer.
+ *   - JIT sync ([./freshness.ts]) does the actual correctness work — when an
+ *     MCP query comes in, it consults the dirty set + on-disk hashes and
+ *     reindexes just what needs it.
+ *
+ * Why both? The watcher alone is racy (filesystem events on Windows arrive
+ * out of order, can be missed under load) and the JIT alone is slow on
+ * burst-y workloads (every query re-walks the workspace). Together the
+ * watcher absorbs steady-state edits so most JIT runs are no-ops, while JIT
+ * provides the per-query correctness guarantee.
+ *
+ * We use chokidar because it abstracts the OS-level oddities (FSEvents on
+ * macOS, ReadDirectoryChangesW on Windows, inotify on Linux) and provides
+ * a uniform API. It's the same library Aider uses for its watch mode.
+ */
+const chokidar_1 = __importDefault(require("chokidar"));
+class SeerWatcher {
+    repoRoot;
+    store;
+    indexer;
+    watcher = null;
+    dirty = new Set();
+    debounceTimer = null;
+    indexing = false;
+    indexingQueue = false;
+    lastSyncMs = 0;
+    lastSyncResult = null;
+    logFn;
+    debounceMs;
+    constructor(repoRoot, store, indexer, options = {}) {
+        this.repoRoot = repoRoot;
+        this.store = store;
+        this.indexer = indexer;
+        this.debounceMs = options.debounceMs ?? 250;
+        this.logFn = options.log ?? ((m) => process.stderr.write(`[watcher] ${m}\n`));
+    }
+    /**
+     * Start watching. Idempotent: calling twice is a no-op.
+     */
+    start() {
+        if (this.watcher)
+            return;
+        const abs = path_1.default.resolve(this.repoRoot);
+        this.watcher = chokidar_1.default.watch(abs, {
+            ignored: [
+                // chokidar accepts globs and functions. We use simple substring tests
+                // because the chokidar glob engine is finicky on Windows paths.
+                (p) => {
+                    const norm = p.replace(/\\/g, '/');
+                    return (norm.includes('/node_modules/') ||
+                        norm.includes('/.git/') ||
+                        norm.includes('/dist/') ||
+                        norm.includes('/build/') ||
+                        norm.includes('/.seer/') ||
+                        norm.includes('/target/') ||
+                        norm.includes('/obj/'));
+                },
+            ],
+            persistent: true,
+            ignoreInitial: true, // Don't fire for files that already exist
+            awaitWriteFinish: {
+                // Some editors write through a tmp + rename dance. Wait for the file
+                // to stop growing before considering it changed.
+                stabilityThreshold: 100,
+                pollInterval: 50,
+            },
+        });
+        const onChange = (filePath) => {
+            this.dirty.add(filePath);
+            this.scheduleSync();
+        };
+        this.watcher.on('add', onChange);
+        this.watcher.on('change', onChange);
+        this.watcher.on('unlink', onChange);
+        this.watcher.on('error', (err) => this.logFn(`error: ${err}`));
+        this.logFn(`watching ${abs}`);
+    }
+    async stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    /** Whether anything is currently waiting to be reindexed. */
+    isDirty() {
+        return this.dirty.size > 0 || this.indexing || this.indexingQueue;
+    }
+    dirtyCount() { return this.dirty.size; }
+    /**
+     * Snapshot for `seer_health`: when did we last reconcile, how many files,
+     * how long did it take. Lets agents tell whether the index they're querying
+     * is "this happened just now" vs "we haven't run in 10 minutes."
+     */
+    syncStatus() {
+        return {
+            watching: this.watcher !== null,
+            dirtyCount: this.dirty.size,
+            indexing: this.indexing,
+            lastSyncMs: this.lastSyncMs,
+            lastSync: this.lastSyncResult,
+        };
+    }
+    /**
+     * Force an immediate sync, bypassing the debounce. Used by `seer_reindex`
+     * and JIT — both need the dirty set drained NOW, not when a timer fires.
+     */
+    async syncNow() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        await this.runSync();
+    }
+    scheduleSync() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            // Fire-and-forget — uncaught rejection would just kill the process.
+            // Errors are reported through the log function.
+            this.runSync().catch(err => this.logFn(`sync failed: ${err.message ?? err}`));
+        }, this.debounceMs);
+    }
+    /**
+     * Reindex the workspace. Serialized — if a sync is already running, we
+     * queue at most one follow-up and coalesce further requests into it. This
+     * matches the indexer's contract that only one writer can be active.
+     */
+    async runSync() {
+        if (this.indexing) {
+            this.indexingQueue = true;
+            return;
+        }
+        this.indexing = true;
+        try {
+            const dirtyCount = this.dirty.size;
+            // Clear the dirty set BEFORE running the index so any events arriving
+            // during the index are caught for the next pass instead of being lost.
+            this.dirty.clear();
+            const start = Date.now();
+            const result = await this.indexer.indexDirectory(this.repoRoot, { quiet: true });
+            this.lastSyncMs = Date.now();
+            this.lastSyncResult = {
+                dirtyReindexed: dirtyCount,
+                added: result.filesIndexed,
+                removed: 0, // indexer doesn't expose pruned count; OK for now
+                elapsedMs: result.elapsedMs,
+            };
+            this.logFn(`sync: ${dirtyCount} dirty event(s), ${result.filesIndexed} reindexed, ` +
+                `${result.filesReusedFromCache} reused, ${result.elapsedMs}ms`);
+        }
+        finally {
+            this.indexing = false;
+            if (this.indexingQueue) {
+                this.indexingQueue = false;
+                this.runSync().catch(err => this.logFn(`requeued sync failed: ${err.message ?? err}`));
+            }
+        }
+    }
+}
+exports.SeerWatcher = SeerWatcher;
+//# sourceMappingURL=watcher.js.map

package/dist/indexer/watcher.js.map

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

package/dist/mcp/server.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Seer MCP server.
+ *
+ * Tool surface (Track-B baseline + Track-C/D additions):
+ *   - seer_health         freshness + schema state
+ *   - seer_stats          counts (files/symbols/edges + role + Track-C totals)
+ *   - seer_symbols        symbol search (BM25 / LIKE)
+ *   - seer_definition     exact symbol definition lookup
+ *   - seer_file_symbols   list symbols in a file
+ *   - seer_callers        direct callers, bounded with true total
+ *   - seer_callees        direct callees, bounded
+ *   - seer_search         combined symbol + file path BM25 search,
+ *                           enriched with containing-symbol context
+ *   - seer_reindex        explicit reindex
+ *
+ *   v4 additions:
+ *   - seer_routes         list HTTP routes detected in source
+ *   - seer_dependencies   list external dependencies from manifests
+ *   - seer_config         list config / env reads
+ *   - seer_complexity     rank symbols by cyclomatic/cognitive complexity
+ *   - seer_behavior       tests that exercise a given symbol
+ *   - seer_trace_path     bounded BFS shortest call path A → B
+ *   - seer_architecture   one-page codebase snapshot
+ *   - seer_detect_changes blast-radius for current diff
+ *   - seer_churn          file-level git churn pass (opt-in)
+ *   - seer_history        per-symbol git history
+ *   - seer_symbol_history (action) build symbol history index
+ */
+export interface McpServerOptions {
+    workspace: string;
+    dbPath?: string;
+    watch?: boolean;
+    jit?: boolean;
+}
+export declare class SeerMcpServer {
+    private store;
+    private indexer;
+    private watcher;
+    private mcp;
+    private startedAt;
+    private workspace;
+    private dbPath;
+    private jitEnabled;
+    private watchEnabled;
+    private jitPromise;
+    constructor(options: McpServerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private ensureFresh;
+    private text;
+    /**
+     * Registry of every tool handler, keyed by name. Mirrors the MCP registration
+     * so seer_batch can dispatch internally without a second round-trip. The
+     * wrapper stores the raw handler and forwards to the SDK unchanged.
+     */
+    private handlers;
+    private registerTool;
+    /**
+     * Up to 5 deterministic fuzzy suggestions (BM25 over the camel/snake-split
+     * FTS index) for a name that resolved to nothing. SUGGESTION-ONLY: callers
+     * surface these under a `didYouMean` key, never substitute them for a real
+     * lookup. Returning a guessed symbol as if exact would be exactly the
+     * "misleading information" Seer's contract forbids.
+     */
+    private suggestSymbols;
+    /**
+     * Emit a list response under a deterministic token budget. Items are assumed
+     * pre-sorted by relevance, so we prefix-trim: keep appending until the
+     * serialized payload would exceed `tokenBudget * 4` chars (~4 chars/token).
+     * Without a budget the output is byte-identical to the previous behavior.
+     */
+    private budgetedText;
+    private autoBuilt;
+    private ensureModules;
+    private ensureShapeHashes;
+    private ensureSymbolHistory;
+    private registerTools;
+}
+export declare function runMcp(options: McpServerOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,UAAU,CAA8B;gBAEpC,OAAO,EAAE,gBAAgB;IAU/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAKb,WAAW;IAWzB,OAAO,CAAC,IAAI;IAIZ;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAkD;IAElE,OAAO,CAAC,YAAY;IASpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,SAAS,CAAqD;IAEtE,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,iBAAiB;YAWX,mBAAmB;IAejC,OAAO,CAAC,aAAa;CA83CtB;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASrE"}