@ltm-alpha/alpha-cs 1.6.0

package/dist/mcp/version.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Resolved package version, computed once at module load.
+ *
+ * The version string is the rendezvous datum between cooperating daemon and
+ * proxy processes: the daemon advertises its version in the hello line, and
+ * the proxy refuses to share IPC across a mismatch (falls back to direct
+ * mode). Keeping the resolution in one place avoids drift between the CLI
+ * `--version` output (which reads `package.json` directly) and the daemon
+ * handshake.
+ *
+ * Resolution strategy: read the bundled `package.json` two levels up from
+ * this file — same relative position whether we're loaded from `src/mcp/` or
+ * the `dist/mcp/` output, since `tsc` preserves the layout. If reading fails
+ * (e.g. the package was unpacked oddly), fall back to "0.0.0-unknown" — a
+ * sentinel that will never match a real version, so the proxy harmlessly
+ * falls back to direct mode.
+ */
+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.AlphaCodeSensePackageVersion = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function readPackageVersion() {
+    try {
+        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+        const raw = fs.readFileSync(pkgPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.version === 'string' && parsed.version.length > 0) {
+            return parsed.version;
+        }
+    }
+    catch {
+        // Fall through to sentinel.
+    }
+    return '0.0.0-unknown';
+}
+exports.AlphaCodeSensePackageVersion = readPackageVersion();
+//# sourceMappingURL=version.js.map

package/dist/mcp/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/mcp/version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,uCAAyB;AACzB,2CAA6B;AAE7B,SAAS,kBAAkB;IACzB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,MAAM,EAAE,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4BAA4B;IAC9B,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAEY,QAAA,4BAA4B,GAAG,kBAAkB,EAAE,CAAC"}

package/dist/mcp/writer-lock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Project writer lock (#1740).
+ *
+ * At most one long-lived MCP *writer* (shared daemon OR direct-mode /
+ * in-process engine that owns the FileWatcher) may serve a given project.
+ * The shared daemon already multiplexes N stdio proxies onto one writer; this
+ * lock closes the same-OS gap where two direct-mode `serve --mcp` processes
+ * (via `CODEGRAPH_NO_DAEMON=1` or proxy→in-process fallback) each start a
+ * watcher, contend on `codegraph.lock`, and degrade auto-sync.
+ *
+ * Deliberately separate from `daemon.pid`: proxies probe the daemon socket
+ * and may clear a live pid that has no socket. A direct-mode holder must not
+ * look like a daemon. `writer.pid` is only about "who owns live auto-sync".
+ */
+/** Absolute path to the writer pid lockfile for `projectRoot`. */
+export declare function getWriterPidPath(projectRoot: string): string;
+/** Structured contents of the writer pidfile. */
+export interface WriterLockInfo {
+    pid: number;
+    /** `direct` | `daemon` | `fallback` — for actionable error text only. */
+    mode: string;
+    startedAt: number;
+}
+export type WriterAcquireResult = {
+    kind: 'acquired';
+    pidPath: string;
+    info: WriterLockInfo;
+} | {
+    kind: 'taken';
+    existing: WriterLockInfo | null;
+    pidPath: string;
+};
+export declare function decodeWriterLockInfo(raw: string): WriterLockInfo | null;
+/**
+ * Atomically create `writer.pid` (link-into-place, O_EXCL fallback). If held
+ * by a dead PID, clear and retry once. Does not steal from a live holder.
+ */
+export declare function tryAcquireWriterLock(projectRoot: string, mode: string): WriterAcquireResult;
+/** Release if we still own the lock (pid match). */
+export declare function releaseWriterLock(projectRoot: string): void;
+/** Read current lock without acquiring. */
+export declare function readWriterLock(projectRoot: string): WriterLockInfo | null;
+/**
+ * Actionable message when another live process owns the writer lock (#1740).
+ */
+export declare function writerLockHeldMessage(existing: WriterLockInfo | null, pidPath: string): string;
+//# sourceMappingURL=writer-lock.d.ts.map

package/dist/mcp/writer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-lock.d.ts","sourceRoot":"","sources":["../../src/mcp/writer-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkBH,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAMxE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAYvE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,mBAAmB,CAuErB;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAS3D;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAOzE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,OAAO,EAAE,MAAM,GACd,MAAM,CAWR"}

package/dist/mcp/writer-lock.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Project writer lock (#1740).
+ *
+ * At most one long-lived MCP *writer* (shared daemon OR direct-mode /
+ * in-process engine that owns the FileWatcher) may serve a given project.
+ * The shared daemon already multiplexes N stdio proxies onto one writer; this
+ * lock closes the same-OS gap where two direct-mode `serve --mcp` processes
+ * (via `CODEGRAPH_NO_DAEMON=1` or proxy→in-process fallback) each start a
+ * watcher, contend on `codegraph.lock`, and degrade auto-sync.
+ *
+ * Deliberately separate from `daemon.pid`: proxies probe the daemon socket
+ * and may clear a live pid that has no socket. A direct-mode holder must not
+ * look like a daemon. `writer.pid` is only about "who owns live auto-sync".
+ */
+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.getWriterPidPath = getWriterPidPath;
+exports.decodeWriterLockInfo = decodeWriterLockInfo;
+exports.tryAcquireWriterLock = tryAcquireWriterLock;
+exports.releaseWriterLock = releaseWriterLock;
+exports.readWriterLock = readWriterLock;
+exports.writerLockHeldMessage = writerLockHeldMessage;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const directory_1 = require("../directory");
+/** Signal-0 liveness (EPERM ⇒ alive). Local copy to avoid a daemon↔writer cycle. */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+/** Absolute path to the writer pid lockfile for `projectRoot`. */
+function getWriterPidPath(projectRoot) {
+    let root = projectRoot;
+    try {
+        root = fs.realpathSync(projectRoot);
+    }
+    catch { /* keep lexical */ }
+    return path.join((0, directory_1.getAlphaCsDir)(root), 'writer.pid');
+}
+function encode(info) {
+    return JSON.stringify(info) + '\n';
+}
+function decodeWriterLockInfo(raw) {
+    try {
+        const parsed = JSON.parse(raw.trim());
+        if (typeof parsed.pid !== 'number' || typeof parsed.mode !== 'string')
+            return null;
+        return {
+            pid: parsed.pid,
+            mode: parsed.mode,
+            startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomically create `writer.pid` (link-into-place, O_EXCL fallback). If held
+ * by a dead PID, clear and retry once. Does not steal from a live holder.
+ */
+function tryAcquireWriterLock(projectRoot, mode) {
+    const pidPath = getWriterPidPath(projectRoot);
+    fs.mkdirSync(path.dirname(pidPath), { recursive: true });
+    const info = {
+        pid: process.pid,
+        mode,
+        startedAt: Date.now(),
+    };
+    const attempt = () => {
+        const tmp = `${pidPath}.${process.pid}.tmp`;
+        let acquired = false;
+        try {
+            fs.writeFileSync(tmp, encode(info), { mode: 0o600 });
+            try {
+                fs.linkSync(tmp, pidPath);
+                acquired = true;
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    // taken
+                }
+                else {
+                    // No hard links — O_EXCL create.
+                    try {
+                        const fd = fs.openSync(pidPath, 'wx', 0o600);
+                        try {
+                            fs.writeSync(fd, encode(info));
+                            acquired = true;
+                        }
+                        finally {
+                            fs.closeSync(fd);
+                        }
+                    }
+                    catch (e2) {
+                        if (e2.code !== 'EEXIST')
+                            throw e2;
+                    }
+                }
+            }
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+        }
+        if (acquired)
+            return { kind: 'acquired', pidPath, info };
+        let existing = null;
+        try {
+            existing = decodeWriterLockInfo(fs.readFileSync(pidPath, 'utf8'));
+        }
+        catch { /* unreadable */ }
+        return { kind: 'taken', existing, pidPath };
+    };
+    let result = attempt();
+    if (result.kind === 'taken' && result.existing && result.existing.pid === process.pid) {
+        // Same process already holds it (daemon acquired before engine watch).
+        return { kind: 'acquired', pidPath: result.pidPath, info: result.existing };
+    }
+    if (result.kind === 'taken') {
+        const existing = result.existing;
+        if (!existing || existing.pid <= 0 || !isProcessAlive(existing.pid)) {
+            // Stale — clear (pid-verified) and retry once.
+            try {
+                const raw = fs.readFileSync(pidPath, 'utf8');
+                const cur = decodeWriterLockInfo(raw);
+                if (!cur || cur.pid === existing?.pid) {
+                    if (!cur || cur.pid <= 0 || !isProcessAlive(cur.pid)) {
+                        fs.unlinkSync(pidPath);
+                    }
+                }
+            }
+            catch { /* ENOENT ok */ }
+            result = attempt();
+        }
+    }
+    return result;
+}
+/** Release if we still own the lock (pid match). */
+function releaseWriterLock(projectRoot) {
+    const pidPath = getWriterPidPath(projectRoot);
+    try {
+        if (!fs.existsSync(pidPath))
+            return;
+        const info = decodeWriterLockInfo(fs.readFileSync(pidPath, 'utf8'));
+        if (info && info.pid === process.pid) {
+            fs.unlinkSync(pidPath);
+        }
+    }
+    catch { /* best-effort */ }
+}
+/** Read current lock without acquiring. */
+function readWriterLock(projectRoot) {
+    const pidPath = getWriterPidPath(projectRoot);
+    try {
+        return decodeWriterLockInfo(fs.readFileSync(pidPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Actionable message when another live process owns the writer lock (#1740).
+ */
+function writerLockHeldMessage(existing, pidPath) {
+    const who = existing && existing.pid > 0
+        ? `PID ${existing.pid} (${existing.mode || 'unknown'} mode)`
+        : 'another process';
+    return ('Alpha Code Sense writer lock held by ' + who + '. ' +
+        'Only one live MCP writer may serve a project (auto-sync / index). ' +
+        'Stop the other server (codegraph daemon stop if a shared daemon, or end the other MCP session), ' +
+        'or unset CODEGRAPH_NO_DAEMON so additional clients proxy to the shared daemon. ' +
+        'If this is stale, delete ' + pidPath);
+}
+//# sourceMappingURL=writer-lock.js.map

package/dist/mcp/writer-lock.js.map

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

package/dist/project-config.d.ts

@@ -0,0 +1,117 @@
+import { Language } from './types';
+/** Filename of the project-scoped config, resolved relative to the project root. */
+export declare const PROJECT_CONFIG_FILENAME = "alpha-cs.json";
+export interface ProjectConfig {
+    /** Map of custom file extension (`.foo`) to a supported language id. */
+    extensions?: Record<string, string>;
+    /**
+     * Gitignore-style patterns naming gitignored directories whose embedded git
+     * repositories should be indexed anyway — the explicit opt-in to override
+     * `.gitignore` for nested-repo discovery (#622, #699). Absent/empty (the
+     * default) means `.gitignore` is fully respected: gitignored embedded repos
+     * are never discovered or indexed (#970, #976).
+     */
+    includeIgnored?: string[];
+    /**
+     * Gitignore-style patterns for paths to keep OUT of the index — even when
+     * they are git-TRACKED, which `.gitignore` cannot do (#999). The escape hatch
+     * for a committed vendor/theme/SDK directory (e.g. a checked-in Metronic theme
+     * under `static/`) that bloats the graph and slows indexing but isn't really
+     * your code. Matched against project-root-relative paths, so a directory like
+     * `"static/"`, a double-star vendor glob, or `"assets/theme"` all work.
+     * Absent/empty (the default) excludes nothing beyond the built-in defaults
+     * and your `.gitignore`.
+     */
+    exclude?: string[];
+    /**
+     * Gitignore-style patterns for first-party source to force INTO the index even
+     * when `.gitignore` would drop it — the general whitelist `includeIgnored`
+     * never was (that one only revives *embedded git repos* inside ignored dirs).
+     * The case this exists for: a project under a second VCS (SVN, Perforce, …)
+     * deliberately `.gitignore`s its own real source so it never lands in Git, yet
+     * that source must still be indexed. Matched against project-root-relative
+     * paths, so `"Tools/"`, a recursive `"Tools/**"` glob, or `"Local/typescript"`
+     * all work.
+     * Built-in default-ignored dirs (`node_modules`, `dist`, …), `.git`, and
+     * Alpha Code Sense's own data dir are never resurfaced; an explicit `exclude` still
+     * wins. Absent/empty (the default) forces nothing in.
+     */
+    include?: string[];
+    /**
+     * Gitignore-style patterns for paths that should still be INDEXED and
+     * findable, but must not outrank first-party code in search ranking (#982).
+     *
+     * The ranking counterpart to `exclude`: `exclude` is a recall lever (the
+     * content leaves the index entirely), this is a relevance lever (the content
+     * stays, it just stops winning). It generalizes the built-in
+     * example/sample/fixture/benchmark de-prioritization to trees only the
+     * project knows about — an `optional-skills/` or `scripts/` directory whose
+     * helpers share generic symbol names with real code. Matched against
+     * project-root-relative paths, so `"optional-skills/"`, a recursive glob, or
+     * `"tools/gen"` all work. Absent/empty (the default) de-prioritizes nothing
+     * beyond the built-ins.
+     */
+    deprioritize?: string[];
+}
+/**
+ * Load the validated extension overrides for a project, mtime-cached.
+ *
+ * Returns a map of `.ext` → supported language id. The result merges on top of
+ * the built-in extension map at the point of use (see `detectLanguage` /
+ * `isSourceFile`), with these user mappings taking precedence. Returns an empty
+ * map when there is no `codegraph.json` (the zero-config default).
+ */
+export declare function loadExtensionOverrides(rootDir: string): Record<string, Language>;
+/**
+ * Load the validated `includeIgnored` patterns for a project, mtime-cached.
+ *
+ * These name gitignored directories whose embedded git repositories should be
+ * indexed despite `.gitignore` (#622, #699). An empty result — the zero-config
+ * default — means `.gitignore` is fully respected: gitignored embedded repos
+ * are never discovered or indexed (#970, #976).
+ */
+export declare function loadIncludeIgnoredPatterns(rootDir: string): string[];
+/**
+ * Load the validated `exclude` patterns for a project, mtime-cached.
+ *
+ * These name paths to keep OUT of the index even when git-tracked — the escape
+ * hatch for a committed vendor/theme/SDK directory `.gitignore` can't drop
+ * (#999). An empty result — the zero-config default — excludes nothing beyond
+ * the built-in defaults and the project's `.gitignore`.
+ */
+export declare function loadExcludePatterns(rootDir: string): string[];
+/**
+ * Load the validated `deprioritize` patterns for a project, mtime-cached.
+ *
+ * These name indexed paths that must not outrank first-party code (#982) — the
+ * ranking counterpart to `exclude`. An empty result — the zero-config default —
+ * de-prioritizes nothing beyond the built-in example/fixture/benchmark dirs.
+ */
+export declare function loadDeprioritizePatterns(rootDir: string): string[];
+/**
+ * Load the validated `include` patterns for a project, mtime-cached.
+ *
+ * These name first-party source to force INTO the index even when `.gitignore`
+ * would drop it — the whitelist for SVN/Perforce-only source a project
+ * gitignores out of Git. An empty result — the zero-config default — forces
+ * nothing in. Built-in default-ignored dirs, `.git`, and Alpha Code Sense's data dir
+ * are never resurfaced, and an explicit `exclude` still wins.
+ */
+export declare function loadIncludePatterns(rootDir: string): string[];
+/** Test/maintenance hook: forget cached config (e.g. after rewriting it in a test). */
+export declare function clearProjectConfigCache(): void;
+/**
+ * Add gitignore-style patterns to a project's `codegraph.json` `includeIgnored`
+ * list, creating the file if absent and preserving every other key. Used by the
+ * CLI to opt a "super-repo of gitignored child repos" (#1156) into the index on
+ * the user's say-so. Returns the count of patterns actually ADDED (ones already
+ * present are skipped, so a re-run is idempotent).
+ *
+ * A plain-JSON round-trip: a `codegraph.json` carrying comments (not valid JSON)
+ * already fails to load with a warning, so rather than silently clobber such a
+ * file this throws when an existing config won't parse — the caller falls back
+ * to printing the manual snippet. Invalidates the config cache so a subsequent
+ * index in the same process sees the new patterns.
+ */
+export declare function addIncludeIgnoredPatterns(rootDir: string, patterns: string[]): number;
+//# sourceMappingURL=project-config.d.ts.map

package/dist/project-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-config.d.ts","sourceRoot":"","sources":["../src/project-config.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAInC,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAGvD,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AA0PD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7D;AAED,uFAAuF;AACvF,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqCrF"}