abb-opencode-local-rag 0.1.0

package/dist/server-main.js

@@ -0,0 +1,242 @@
+// MCP Server entry point
+import { resolveDevice, resolveDtype } from './cli/options.js';
+import { RAGServer } from './server/index.js';
+import { BaseDirsConfigError, parseBaseDirsEnv, resolveBaseDirs } from './utils/base-dirs.js';
+import { DEFAULT_MAX_FILE_SIZE, MAX_CHUNK_MIN_LENGTH } from './utils/limits.js';
+import { checkSensitivePath } from './utils/sensitive-path.js';
+/**
+ * Parse grouping mode from environment variable
+ */
+export function parseGroupingMode(value) {
+    if (!value)
+        return { value: undefined };
+    const normalized = value.toLowerCase().trim();
+    if (normalized === 'similar' || normalized === 'related') {
+        return { value: normalized };
+    }
+    const warning = `Invalid RAG_GROUPING value: "${value.slice(0, 100)}". Expected "similar" or "related". Ignoring.`;
+    return { value: undefined, warning };
+}
+/**
+ * Parse max distance from environment variable
+ */
+export function parseMaxDistance(value) {
+    if (!value)
+        return { value: undefined };
+    const parsed = Number.parseFloat(value);
+    if (Number.isNaN(parsed) || parsed <= 0 || !Number.isFinite(parsed)) {
+        const warning = `Invalid RAG_MAX_DISTANCE value: "${value.slice(0, 100)}". Expected positive number. Ignoring.`;
+        return { value: undefined, warning };
+    }
+    return { value: parsed };
+}
+/**
+ * Parse max files from environment variable
+ */
+export function parseMaxFiles(value) {
+    if (!value)
+        return { value: undefined };
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 1) {
+        const warning = `Invalid RAG_MAX_FILES value: "${value.slice(0, 100)}". Expected positive integer (>= 1). Ignoring.`;
+        return { value: undefined, warning };
+    }
+    return { value: parsed };
+}
+/**
+ * Parse hybrid weight from environment variable
+ */
+export function parseHybridWeight(value) {
+    if (!value)
+        return { value: undefined };
+    const parsed = Number.parseFloat(value);
+    if (Number.isNaN(parsed) || parsed < 0 || parsed > 1) {
+        const warning = `Invalid RAG_HYBRID_WEIGHT value: "${value.slice(0, 100)}". Expected 0.0-1.0. Using default (0.6).`;
+        return { value: undefined, warning };
+    }
+    return { value: parsed };
+}
+/**
+ * Parse chunk minimum length from environment variable
+ */
+export function parseChunkMinLength(value) {
+    if (!value)
+        return { value: undefined };
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 1 || parsed > MAX_CHUNK_MIN_LENGTH) {
+        const warning = `Invalid CHUNK_MIN_LENGTH value: "${value.slice(0, 100)}". Expected integer between 1 and ${MAX_CHUNK_MIN_LENGTH}. Ignoring.`;
+        return { value: undefined, warning };
+    }
+    return { value: parsed };
+}
+/** Parse the independent PDF image-storage toggle. */
+export function parseStoreImages(value) {
+    const normalized = value?.trim().toLowerCase() ?? '';
+    if (normalized.length === 0)
+        return { value: false };
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return { value: true };
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return { value: false };
+    return {
+        value: false,
+        warning: `Invalid STORE_IMAGES value: "${value?.slice(0, 100)}". Expected one of 1, true, yes, on, 0, false, no, or off. Using false.`,
+    };
+}
+// ============================================
+// Server Startup
+// ============================================
+/**
+ * Resolve the full RAGServer configuration from environment variables.
+ *
+ * Pure (no process.exit, no transport): `env` and `cwd` are passed in so the
+ * entry-point wiring can be exercised directly in tests instead of via a copy.
+ * Single source of truth for BASE_DIRS / BASE_DIR / cwd precedence, the
+ * sensitive-path policy on both raw and realpath-normalized roots, and the
+ * never-fall-back-to-cwd-on-error rule.
+ */
+export async function resolveServerConfig(env, cwd) {
+    const device = resolveDevice(env['RAG_DEVICE']);
+    // Undefined when RAG_DTYPE is unset — threaded into config only when defined
+    // (see below), preserving the unset signal for the embedder's fp32 default.
+    const dtype = resolveDtype(env['RAG_DTYPE']);
+    const configWarnings = [];
+    // Sensitive-path pre-check on the RAW user-supplied paths, before the
+    // resolver realpath-normalizes them (on macOS `/etc` → `/private/etc`, which
+    // a post-realpath-only check would miss).
+    const rawSensitiveErrors = [];
+    if (env['BASE_DIRS'] !== undefined && env['BASE_DIRS'].length > 0) {
+        const parsed = parseBaseDirsEnv(env['BASE_DIRS']);
+        if (parsed.ok) {
+            for (const raw of parsed.value) {
+                const sensitive = checkSensitivePath(raw, 'BASE_DIRS');
+                if (sensitive)
+                    rawSensitiveErrors.push(sensitive);
+            }
+        }
+    }
+    else if (env['BASE_DIR'] !== undefined && env['BASE_DIR'].trim().length > 0) {
+        const sensitive = checkSensitivePath(env['BASE_DIR'], 'BASE_DIR');
+        if (sensitive)
+            rawSensitiveErrors.push(sensitive);
+    }
+    const baseDirsResult = await resolveBaseDirs({
+        envBaseDirs: env['BASE_DIRS'],
+        envBaseDir: env['BASE_DIR'],
+        cwd,
+    });
+    let baseDirsForServer;
+    // Normal-path roots, index-aligned with baseDirsForServer, for list_files
+    // scan/display (see BaseDirsConfig for the path policy).
+    let rawBaseDirsForServer;
+    let configError;
+    // Raw sensitive-path matches take precedence over resolver errors.
+    if (rawSensitiveErrors.length > 0) {
+        baseDirsForServer = [];
+        rawBaseDirsForServer = [];
+        configError = new BaseDirsConfigError([...new Set(rawSensitiveErrors)].join('; '));
+        configWarnings.push(configError.message);
+    }
+    else if (baseDirsResult.ok) {
+        const sourceFlag = env['BASE_DIRS'] !== undefined && env['BASE_DIRS'].length > 0 ? 'BASE_DIRS' : 'BASE_DIR';
+        const sensitiveErrors = [];
+        for (const root of baseDirsResult.config.baseDirs) {
+            const sensitive = checkSensitivePath(root, sourceFlag);
+            if (sensitive)
+                sensitiveErrors.push(sensitive);
+        }
+        if (sensitiveErrors.length > 0) {
+            baseDirsForServer = [];
+            rawBaseDirsForServer = [];
+            configError = new BaseDirsConfigError([...new Set(sensitiveErrors)].join('; '));
+            configWarnings.push(configError.message);
+        }
+        else {
+            baseDirsForServer = baseDirsResult.config.baseDirs;
+            rawBaseDirsForServer = baseDirsResult.config.rawBaseDirs;
+            for (const warning of baseDirsResult.warnings) {
+                configWarnings.push(warning.message);
+            }
+        }
+    }
+    else {
+        baseDirsForServer = [];
+        rawBaseDirsForServer = [];
+        configError = baseDirsResult.error;
+        configWarnings.push(baseDirsResult.error.message);
+    }
+    const config = {
+        dbPath: env['DB_PATH'] || './lancedb/',
+        modelName: env['MODEL_NAME'] || 'Xenova/all-MiniLM-L6-v2',
+        cacheDir: env['CACHE_DIR'] || './models/',
+        baseDirs: baseDirsForServer,
+        rawBaseDirs: rawBaseDirsForServer,
+        maxFileSize: Number.parseInt(env['MAX_FILE_SIZE'] || String(DEFAULT_MAX_FILE_SIZE), 10),
+        device,
+        storeImages: false,
+    };
+    // Quality-filter settings: applied only when defined; invalid values warn.
+    const maxDistance = parseMaxDistance(env['RAG_MAX_DISTANCE']);
+    const grouping = parseGroupingMode(env['RAG_GROUPING']);
+    const maxFiles = parseMaxFiles(env['RAG_MAX_FILES']);
+    const hybridWeight = parseHybridWeight(env['RAG_HYBRID_WEIGHT']);
+    const chunkMinLength = parseChunkMinLength(env['CHUNK_MIN_LENGTH']);
+    const storeImages = parseStoreImages(env['STORE_IMAGES']);
+    if (maxDistance.value !== undefined)
+        config.maxDistance = maxDistance.value;
+    if (maxDistance.warning)
+        configWarnings.push(maxDistance.warning);
+    if (grouping.value !== undefined)
+        config.grouping = grouping.value;
+    if (grouping.warning)
+        configWarnings.push(grouping.warning);
+    if (maxFiles.value !== undefined)
+        config.maxFiles = maxFiles.value;
+    if (maxFiles.warning)
+        configWarnings.push(maxFiles.warning);
+    if (hybridWeight.value !== undefined)
+        config.hybridWeight = hybridWeight.value;
+    if (hybridWeight.warning)
+        configWarnings.push(hybridWeight.warning);
+    if (chunkMinLength.value !== undefined)
+        config.chunkMinLength = chunkMinLength.value;
+    if (chunkMinLength.warning)
+        configWarnings.push(chunkMinLength.warning);
+    config.storeImages = storeImages.value ?? false;
+    if (storeImages.warning)
+        configWarnings.push(storeImages.warning);
+    // Set dtype only when defined, so config.dtype === undefined keeps meaning
+    // "RAG_DTYPE unset" (the embedder then applies its fp32 default).
+    if (dtype !== undefined)
+        config.dtype = dtype;
+    if (configWarnings.length > 0)
+        config.configWarnings = configWarnings;
+    if (configError !== undefined)
+        config.configError = configError;
+    return config;
+}
+/**
+ * Start the RAG MCP Server
+ * Configuration is read from environment variables only (no CLI flags).
+ * This ensures the bare `mcp-local-rag` launch is suitable for MCP clients.
+ */
+export async function startServer() {
+    try {
+        const config = await resolveServerConfig(process.env, process.cwd());
+        if (config.configWarnings && config.configWarnings.length > 0) {
+            console.error('Configuration warnings:', config.configWarnings.join(' | '));
+        }
+        console.error('Starting RAG MCP Server...');
+        console.error('Configuration:', config);
+        // Start RAGServer
+        const server = new RAGServer(config);
+        await server.initialize();
+        await server.run();
+        console.error('RAG MCP Server started successfully');
+    }
+    catch (error) {
+        console.error('Failed to start RAG MCP Server:', error);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=server-main.js.map

package/dist/server-main.js.map

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

package/dist/utils/base-dirs.d.ts

@@ -0,0 +1,212 @@
+import { AppError } from './errors.js';
+/**
+ * Effective document roots, in two index-aligned forms.
+ *
+ * Path policy (the canonical statement; other sites just reference it):
+ * realpath is used ONLY for the security boundary; everything user-facing uses
+ * resolve() (normal) paths.
+ * - `baseDirs`: realpath-resolved, deduped, nested-pruned — the containment
+ *   boundary passed to `DocumentParser`. Input order preserved (first = legacy
+ *   single-root accessor; see {@link legacyBaseDir}).
+ * - `rawBaseDirs`: the SAME roots, same order, resolve()-only. The normal path
+ *   space `list`/`list_files` scan + display, so paths match the
+ *   resolve()-stored DB keys; otherwise a symlinked prefix (e.g. macOS
+ *   /tmp → /private/tmp) would make ingested files show as not-ingested.
+ */
+export interface BaseDirsConfig {
+    baseDirs: string[];
+    rawBaseDirs: string[];
+}
+/**
+ * Discriminated union of configuration warnings surfaced by helpers in this
+ * module. Both CLI (stderr) and MCP (tool response content block) paths
+ * consume these — the consumer decides how to render them.
+ */
+export type BaseDirsConfigWarning = {
+    kind: 'nested-root-pruned';
+    message: string;
+    parent: string;
+    pruned: string;
+} | {
+    kind: 'base-dirs-overrides-base-dir';
+    message: string;
+};
+/**
+ * Configuration error raised by parsers and the realpath helper. Modeled as
+ * a dedicated subclass so consumers can distinguish configuration problems
+ * from other I/O errors (e.g. `ValidationError` from `DocumentParser`).
+ */
+export declare class BaseDirsConfigError extends AppError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Result of {@link parseBaseDirsEnv}. A discriminated union avoids forcing
+ * callers to use `try/catch` for what is a routine configuration-validation
+ * branch (invalid input → structured error → user-facing message).
+ */
+export type ParseBaseDirsResult = {
+    ok: true;
+    value: string[];
+} | {
+    ok: false;
+    error: BaseDirsConfigError;
+};
+/**
+ * Render an absolute path for inclusion in user-visible error/warning
+ * messages, substituting the current `$HOME` prefix with `~`. The substitution
+ * keeps the message useful for debugging while avoiding leaking the operating
+ * username when warnings/errors flow out through MCP responses to clients.
+ *
+ * `$HOME` resolution is read once at call time, so processes that mutate
+ * `HOME` between invocations still see the current value (no caching).
+ *
+ * Exact-match on the home directory itself (`/Users/me` → `~`) and prefix
+ * match with a trailing separator (`/Users/me/work` → `~/work`) are both
+ * supported; other paths pass through unchanged.
+ */
+export declare function displayPath(path: string): string;
+/**
+ * Parse the `BASE_DIRS` environment variable.
+ *
+ * Accepts only a JSON array of one or more non-empty, non-whitespace-only
+ * strings — e.g. `'["/Users/me/work","/Users/me/specs"]'`. Anything else
+ * (delimiter syntax such as `'/a:/b'`, an empty array, an array containing
+ * empty strings, non-string elements, JSON scalars, JSON objects, ...)
+ * produces a {@link BaseDirsConfigError}.
+ *
+ * This helper performs only syntactic validation. It does not resolve
+ * realpaths or check that the directories exist — that is the job of
+ * {@link normalizeRealpath} after the resolver picks a source.
+ */
+export declare function parseBaseDirsEnv(raw: string): ParseBaseDirsResult;
+/**
+ * Append a trailing path separator if the input does not already end with
+ * one. This is the prefix-safety pattern used throughout the parser
+ * (`/foo/bar` must not match `/foo/barista`).
+ */
+export declare function withTrailingSeparator(path: string): string;
+/**
+ * Resolve a directory to its realpath form and append a trailing separator
+ * so the result can be used directly as a prefix in security checks.
+ *
+ * realpath here is the security boundary (see {@link BaseDirsConfig} for the
+ * path policy); user-facing surfaces use the resolve()-only `rawBaseDirs`.
+ *
+ * Throws {@link BaseDirsConfigError} when the directory does not exist or
+ * is not a directory — root configuration must point at real directories
+ * the process is allowed to read.
+ */
+export declare function normalizeRealpath(path: string): Promise<string>;
+/**
+ * Output of {@link dedupAndPruneRoots}.
+ */
+export interface DedupAndPruneResult {
+    /** Effective roots in input order, after exact dedup and nested pruning. */
+    roots: string[];
+    /** Warnings describing pruned nested roots, in pruning order. */
+    warnings: BaseDirsConfigWarning[];
+}
+/**
+ * Reduce a list of realpath-normalized roots to the effective set.
+ *
+ * Behavior:
+ *  - Exact duplicates (`A === B` after realpath normalization) are silently
+ *    deduplicated. This is treated as user convenience rather than a
+ *    configuration mistake, so no warning is emitted.
+ *  - Nested roots (`B` lives under `A` after realpath normalization) are
+ *    pruned: the parent `A` is kept, the child `B` is dropped, and a
+ *    `nested-root-pruned` warning describes both paths. This avoids
+ *    duplicate `list_files` / CLI scan output without widening the security
+ *    boundary beyond the parent root the user already configured.
+ *
+ * Input order is preserved for the surviving roots so the first element
+ * remains a meaningful legacy `baseDir` (see {@link legacyBaseDir}).
+ *
+ * All inputs MUST already have a trailing separator (see
+ * {@link normalizeRealpath}) — that is what makes the `startsWith`-based
+ * nested check safe against sibling-prefix paths like `/foo/barista`.
+ */
+export declare function dedupAndPruneRoots(inputs: string[]): DedupAndPruneResult;
+/**
+ * Input to {@link resolveBaseDirs}. Each axis maps directly to one of the
+ * configuration sources defined in the multi-base-dirs plan:
+ *
+ *  - `cliRoots` — collected `--base-dir` flag occurrences (highest precedence)
+ *  - `envBaseDirs` — raw `BASE_DIRS` env value (JSON array)
+ *  - `envBaseDir` — raw `BASE_DIR` env value (single path string)
+ *  - `cwd` — `process.cwd()` snapshot (lowest precedence, always required)
+ *
+ * The resolver is pure with respect to its inputs (no `process.env` reads,
+ * no `process.cwd()` calls) so it can be exercised under deterministic tests
+ * and reused from both the CLI entry and the MCP server entry without
+ * implicitly depending on process state.
+ */
+export interface ResolveBaseDirsInput {
+    cliRoots?: string[] | undefined;
+    envBaseDirs?: string | undefined;
+    envBaseDir?: string | undefined;
+    cwd: string;
+}
+/**
+ * Result of {@link resolveBaseDirs}. Discriminated by `ok` so callers can
+ * branch on configuration validity without try/catch — invalid `BASE_DIRS`
+ * is a routine user-facing error path, not an exceptional condition.
+ *
+ * On success, `warnings` aggregates every warning surfaced during resolution
+ * in display order:
+ *  1. `base-dirs-overrides-base-dir` (when applicable) — shown first so the
+ *     precedence note is visible before per-root pruning notes.
+ *  2. `nested-root-pruned` — one warning per pruned child, in pruning order.
+ */
+export type ResolveBaseDirsResult = {
+    ok: true;
+    config: BaseDirsConfig;
+    warnings: BaseDirsConfigWarning[];
+} | {
+    ok: false;
+    error: BaseDirsConfigError;
+};
+/**
+ * Resolve effective base directories from CLI / env / cwd inputs.
+ *
+ * Resolution order (per the multi-base-dirs plan):
+ *   1. `cliRoots` (one or more `--base-dir` flags) — when non-empty, replaces
+ *      env roots. CLI and env are never merged.
+ *   2. `envBaseDirs` (JSON array) — when CLI roots are absent.
+ *   3. `envBaseDir` (single path) — when CLI and `BASE_DIRS` are absent.
+ *   4. `cwd` — when none of the above are set.
+ *
+ * Warning rules:
+ *  - `BASE_DIRS > BASE_DIR` precedence warning fires only when CLI roots are
+ *    absent AND both `BASE_DIRS` and `BASE_DIR` are set. CLI-driven runs do
+ *    not produce this warning even if both env vars are also set.
+ *  - Nested-root pruning warnings always fire when applicable, regardless
+ *    of which source provided the roots.
+ *
+ * Error rules:
+ *  - Invalid `BASE_DIRS` (malformed JSON, non-array, empty array, empty
+ *    string element, ...) returns `{ ok: false, error }`. The resolver does
+ *    NOT fall back to `BASE_DIR` or `cwd` — callers surface the error per
+ *    their UI contract (CLI exit code, MCP tool error, `status` diagnostic).
+ *  - A path that fails realpath resolution (does not exist, not a directory,
+ *    permission denied) also returns `{ ok: false, error }`. Roots must
+ *    point at real directories the process is allowed to read.
+ *
+ * Post-resolution normalization:
+ *  - Every selected path is realpath-normalized and gets a trailing path
+ *    separator (see {@link normalizeRealpath}) so it can be used as a prefix
+ *    in security checks.
+ *  - Exact duplicates are silently deduplicated.
+ *  - Nested roots are pruned with a warning (see {@link dedupAndPruneRoots}).
+ */
+export declare function resolveBaseDirs(input: ResolveBaseDirsInput): Promise<ResolveBaseDirsResult>;
+/**
+ * Return the legacy single-root `baseDir` value for a {@link BaseDirsConfig}.
+ *
+ * Used for backward compatibility with consumers (and response fields) that
+ * pre-date the multi-root model. The contract is "first effective root after
+ * normalization and nested-root pruning"; callers must build the config via
+ * {@link dedupAndPruneRoots} for this to hold.
+ */
+export declare function legacyBaseDir(config: BaseDirsConfig): string;
+//# sourceMappingURL=base-dirs.d.ts.map

package/dist/utils/base-dirs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-dirs.d.ts","sourceRoot":"","sources":["../../src/utils/base-dirs.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAMtC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,oBAAoB,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IACE,IAAI,EAAE,8BAA8B,CAAA;IACpC,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAEL;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,YAAY,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAGzC;CACF;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAM7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYhD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA+DjE;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BrE;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,iEAAiE;IACjE,QAAQ,EAAE,qBAAqB,EAAE,CAAA;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAwDxE;AA2BD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,qBAAqB,EAAE,CAAA;CAAE,GACvE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAiDjG;AAqED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAM5D"}