@dahch/muninn 0.0.0-stage → 0.1.0

package/dist/db/client.js

@@ -0,0 +1,264 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import Database from "better-sqlite3";
+import { assertDocPath } from "../util/path-safety.js";
+export const SCHEMA_SQL = `-- Muninn Engine Database Schema
+-- Version 1.0.0
+
+-- Projects table
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  git_remote TEXT,
+  root_path TEXT NOT NULL UNIQUE,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_projects_root_path ON projects(root_path);
+
+-- Observations table
+CREATE TABLE IF NOT EXISTS observations (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  category TEXT CHECK(category IN ('decision', 'convention', 'discovery', 'bugfix', 'architecture')) NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  topic_key TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_observations_project_id ON observations(project_id);
+CREATE INDEX IF NOT EXISTS idx_observations_updated_at ON observations(updated_at);
+CREATE INDEX IF NOT EXISTS idx_observations_project_updated ON observations(project_id, updated_at DESC, created_at DESC);
+
+-- Observations FTS5 virtual table
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  title,
+  content,
+  topic_key,
+  content='observations',
+  content_rowid='rowid'
+);
+
+-- Triggers for automatic FTS5 synchronization
+CREATE TRIGGER IF NOT EXISTS obs_ai AFTER INSERT ON observations BEGIN
+  INSERT INTO observations_fts(rowid, title, content, topic_key)
+  VALUES (new.rowid, new.title, new.content, new.topic_key);
+END;
+
+CREATE TRIGGER IF NOT EXISTS obs_ad AFTER DELETE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content, topic_key)
+  VALUES ('delete', old.rowid, old.title, old.content, old.topic_key);
+END;
+
+CREATE TRIGGER IF NOT EXISTS obs_au AFTER UPDATE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content, topic_key)
+  VALUES ('delete', old.rowid, old.title, old.content, old.topic_key);
+  INSERT INTO observations_fts(rowid, title, content, topic_key)
+  VALUES (new.rowid, new.title, new.content, new.topic_key);
+END;
+
+-- Entities table
+CREATE TABLE IF NOT EXISTS entities (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  entity_type TEXT CHECK(entity_type IN ('file', 'function', 'class', 'interface', 'module')) NOT NULL,
+  identifier TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_entities_project_id ON entities(project_id);
+CREATE INDEX IF NOT EXISTS idx_entities_identifier ON entities(identifier);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entities_project_identifier ON entities(project_id, identifier);
+
+-- Observation Entities join table
+CREATE TABLE IF NOT EXISTS observation_entities (
+  observation_id TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  PRIMARY KEY(observation_id, entity_id),
+  FOREIGN KEY(observation_id) REFERENCES observations(id) ON DELETE CASCADE,
+  FOREIGN KEY(entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_observation_entities_entity_id ON observation_entities(entity_id);
+
+-- Entity Dependencies table
+-- Relaciones topológicas entre símbolos (A llama/importa a B, o A implementa a B)
+CREATE TABLE IF NOT EXISTS entity_dependencies (
+  source_entity_id TEXT NOT NULL,
+  target_entity_id TEXT NOT NULL,
+  relation_type TEXT CHECK(relation_type IN ('imports', 'calls', 'implements', 'extends', 'references')) NOT NULL,
+  PRIMARY KEY(source_entity_id, target_entity_id, relation_type),
+  FOREIGN KEY(source_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  FOREIGN KEY(target_entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_deps_source ON entity_dependencies(source_entity_id);
+CREATE INDEX IF NOT EXISTS idx_entity_deps_target ON entity_dependencies(target_entity_id);
+`;
+/**
+ * Robustly load schema SQL from disk if available, otherwise fallback to embedded SCHEMA_SQL.
+ */
+export function loadSchemaSql() {
+    try {
+        const currentDir = typeof __dirname !== "undefined"
+            ? __dirname
+            : path.dirname(fileURLToPath(import.meta.url));
+        const schemaFile = path.join(currentDir, "schema.sql");
+        if (fs.existsSync(schemaFile)) {
+            return fs.readFileSync(schemaFile, "utf-8");
+        }
+    }
+    catch {
+        // Ignore and fallback to embedded schema
+    }
+    return SCHEMA_SQL;
+}
+/**
+ * Strips embedded basic auth credentials (e.g. https://user:pass@host/... -> https://host/...)
+ * from a git remote URL before saving git_remote.
+ */
+export function sanitizeGitRemote(rawUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        if (parsed.username || parsed.password) {
+            if (parsed.protocol === "ssh:" && !parsed.password) {
+                return rawUrl;
+            }
+            parsed.username = "";
+            parsed.password = "";
+            return parsed.toString();
+        }
+        return rawUrl;
+    }
+    catch {
+        // Regex fallback for non-standard URLs or git SCP-like syntax
+        return rawUrl.replace(/^([a-zA-Z+-]+:\/\/)[^/@]+@/, "$1");
+    }
+}
+/**
+ * Searches upward from startDir for the nearest directory or parent containing a .git folder or file.
+ */
+export function findGitRoot(startDir = process.cwd()) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const gitPath = path.join(current, ".git");
+        if (fs.existsSync(gitPath)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Inspects a git repository root to extract the default origin remote URL if present.
+ */
+export function tryGetGitRemote(gitRoot) {
+    try {
+        const configPath = path.join(gitRoot, ".git", "config");
+        if (fs.existsSync(configPath)) {
+            const content = fs.readFileSync(configPath, "utf-8");
+            const match = content.match(/\[remote "origin"\][^\[]*url\s*=\s*([^\n\r]+)/);
+            if (match && match[1]) {
+                return sanitizeGitRemote(match[1].trim());
+            }
+        }
+    }
+    catch {
+        // Ignore error
+    }
+    return null;
+}
+/**
+ * Resolves the database path for Muninn.
+ * - If customPath is given, return it (e.g. ':memory:' or specific path).
+ * - Check if cwd (or startDir) or any parent directory has .git. If so, resolve to `<git_root>/.huginn/muninn.db`.
+ * - Fallback to `join(homedir(), '.huginn', 'muninn.db')`.
+ */
+export function resolveDatabasePath(customPath, startDir = process.cwd()) {
+    if (customPath !== undefined && customPath !== "") {
+        return customPath;
+    }
+    const gitRoot = findGitRoot(startDir);
+    if (gitRoot) {
+        return path.join(gitRoot, ".huginn", "muninn.db");
+    }
+    return path.join(os.homedir(), ".huginn", "muninn.db");
+}
+/**
+ * Initializes and returns a SQLite database instance using better-sqlite3.
+ * Configures foreign_keys = ON, journal_mode = WAL, busy_timeout = 5000, recursive_triggers = ON, and executes schema.sql DDL.
+ */
+export function getDatabase(dbPath, startDir) {
+    // The database and the project record must come from ONE root (ADR-49): the
+    // caller passes the same directory it hands to `ensureProject`.
+    const resolvedPath = resolveDatabasePath(dbPath, startDir);
+    if (resolvedPath !== ":memory:") {
+        // A cloned repository can ship `.huginn` — or the database file itself — as a
+        // symlink and redirect the SQLite write outside the project (SEC-005). The
+        // path is screened exactly like the harness state, the receipts and the
+        // promotion backup; the lexical path is kept for the open so callers see the
+        // path they named.
+        assertDocPath(resolvedPath, {
+            projectPath: findGitRoot(startDir ?? process.cwd()) ?? undefined,
+            label: "the Muninn database",
+            action: "write",
+        });
+        const dir = path.dirname(resolvedPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+    }
+    const db = new Database(resolvedPath, { timeout: 5000 });
+    try {
+        db.pragma("foreign_keys = ON");
+        db.pragma("journal_mode = WAL");
+        db.pragma("busy_timeout = 5000");
+        db.pragma("recursive_triggers = ON");
+        const schema = loadSchemaSql();
+        db.exec(schema);
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
+    return db;
+}
+/**
+ * Finds an existing project by root_path or creates a new project record idempotently.
+ */
+export function ensureProject(db, options) {
+    // Same fallback root as the database resolution (ADR-49): when no explicit
+    // root is given, both derive from `startDir` (or the process cwd).
+    const base = options?.startDir ? path.resolve(options.startDir) : process.cwd();
+    const rootPath = options?.rootPath ? path.resolve(options.rootPath) : (findGitRoot(base) ?? base);
+    const existing = db
+        .prepare("SELECT id, name, git_remote, root_path, created_at FROM projects WHERE root_path = ?")
+        .get(rootPath);
+    if (existing) {
+        return existing;
+    }
+    const name = options?.name ?? (path.basename(rootPath) || "project");
+    const rawRemote = options?.gitRemote ?? tryGetGitRemote(rootPath) ?? null;
+    const gitRemote = rawRemote ? sanitizeGitRemote(rawRemote) : null;
+    const id = crypto.randomUUID();
+    db.prepare("INSERT INTO projects (id, name, git_remote, root_path) VALUES (?, ?, ?, ?)").run(id, name, gitRemote, rootPath);
+    const created = db
+        .prepare("SELECT id, name, git_remote, root_path, created_at FROM projects WHERE id = ?")
+        .get(id);
+    if (!created) {
+        throw new Error(`Failed to create project record for rootPath: ${rootPath}`);
+    }
+    return created;
+}
+//# sourceMappingURL=client.js.map

package/dist/db/client.js.map

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

package/dist/db/schema.sql

@@ -0,0 +1,97 @@
+-- Muninn Engine Database Schema
+-- Version 1.0.0
+
+-- Projects table
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  git_remote TEXT,
+  root_path TEXT NOT NULL UNIQUE,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_projects_root_path ON projects(root_path);
+
+-- Observations table
+CREATE TABLE IF NOT EXISTS observations (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  category TEXT CHECK(category IN ('decision', 'convention', 'discovery', 'bugfix', 'architecture')) NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  topic_key TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_observations_project_id ON observations(project_id);
+CREATE INDEX IF NOT EXISTS idx_observations_updated_at ON observations(updated_at);
+CREATE INDEX IF NOT EXISTS idx_observations_project_updated ON observations(project_id, updated_at DESC, created_at DESC);
+
+-- Observations FTS5 virtual table
+CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+  title,
+  content,
+  topic_key,
+  content='observations',
+  content_rowid='rowid'
+);
+
+-- Triggers for automatic FTS5 synchronization
+CREATE TRIGGER IF NOT EXISTS obs_ai AFTER INSERT ON observations BEGIN
+  INSERT INTO observations_fts(rowid, title, content, topic_key)
+  VALUES (new.rowid, new.title, new.content, new.topic_key);
+END;
+
+CREATE TRIGGER IF NOT EXISTS obs_ad AFTER DELETE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content, topic_key)
+  VALUES ('delete', old.rowid, old.title, old.content, old.topic_key);
+END;
+
+CREATE TRIGGER IF NOT EXISTS obs_au AFTER UPDATE ON observations BEGIN
+  INSERT INTO observations_fts(observations_fts, rowid, title, content, topic_key)
+  VALUES ('delete', old.rowid, old.title, old.content, old.topic_key);
+  INSERT INTO observations_fts(rowid, title, content, topic_key)
+  VALUES (new.rowid, new.title, new.content, new.topic_key);
+END;
+
+-- Entities table
+CREATE TABLE IF NOT EXISTS entities (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  entity_type TEXT CHECK(entity_type IN ('file', 'function', 'class', 'interface', 'module')) NOT NULL,
+  identifier TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_entities_project_id ON entities(project_id);
+CREATE INDEX IF NOT EXISTS idx_entities_identifier ON entities(identifier);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entities_project_identifier ON entities(project_id, identifier);
+
+-- Observation Entities join table
+CREATE TABLE IF NOT EXISTS observation_entities (
+  observation_id TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  PRIMARY KEY(observation_id, entity_id),
+  FOREIGN KEY(observation_id) REFERENCES observations(id) ON DELETE CASCADE,
+  FOREIGN KEY(entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_observation_entities_entity_id ON observation_entities(entity_id);
+
+-- Entity Dependencies table
+-- Relaciones topológicas entre símbolos (A llama/importa a B, o A implementa a B)
+CREATE TABLE IF NOT EXISTS entity_dependencies (
+  source_entity_id TEXT NOT NULL,
+  target_entity_id TEXT NOT NULL,
+  relation_type TEXT CHECK(relation_type IN ('imports', 'calls', 'implements', 'extends', 'references')) NOT NULL,
+  PRIMARY KEY(source_entity_id, target_entity_id, relation_type),
+  FOREIGN KEY(source_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  FOREIGN KEY(target_entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_deps_source ON entity_dependencies(source_entity_id);
+CREATE INDEX IF NOT EXISTS idx_entity_deps_target ON entity_dependencies(target_entity_id);
+

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API of the Muninn memory engine.
+ *
+ * Everything below is safe to import from a Node or Bun process:
+ *
+ * ```ts
+ * import { MemoryService, indexFilesIntoMuninn } from "@dahch/muninn";
+ *
+ * const memory = new MemoryService({ projectRoot: process.cwd() });
+ * indexFilesIntoMuninn(memory, ["src/app.ts"], { projectRoot: process.cwd() });
+ * console.log(memory.search({ query: "auth", limit: 5 }));
+ * ```
+ *
+ * Subpath entry points (`@dahch/muninn/db`, `/service`, `/indexer`, `/mcp`,
+ * `/contracts`, `/util`) expose the same modules without the barrel.
+ */
+export * from "./db/client.js";
+export * from "./service/index.js";
+export * from "./indexer/index.js";
+export * from "./mcp/index.js";
+export * from "./contracts/index.js";
+export * from "./util/text.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Public API of the Muninn memory engine.
+ *
+ * Everything below is safe to import from a Node or Bun process:
+ *
+ * ```ts
+ * import { MemoryService, indexFilesIntoMuninn } from "@dahch/muninn";
+ *
+ * const memory = new MemoryService({ projectRoot: process.cwd() });
+ * indexFilesIntoMuninn(memory, ["src/app.ts"], { projectRoot: process.cwd() });
+ * console.log(memory.search({ query: "auth", limit: 5 }));
+ * ```
+ *
+ * Subpath entry points (`@dahch/muninn/db`, `/service`, `/indexer`, `/mcp`,
+ * `/contracts`, `/util`) expose the same modules without the barrel.
+ */
+export * from "./db/client.js";
+export * from "./service/index.js";
+export * from "./indexer/index.js";
+export * from "./mcp/index.js";
+export * from "./contracts/index.js";
+export * from "./util/text.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/indexer/ast-indexer.d.ts

@@ -0,0 +1,55 @@
+import type { EntityType, DependencyRelationType } from "../db/client.js";
+import type { IMemoryService } from "../service/memory-service.js";
+export interface ExtractedDependency {
+    sourceIdentifier: string;
+    targetIdentifier: string;
+    relationType: DependencyRelationType;
+}
+export interface ExtractedSymbol {
+    name: string;
+    identifier: string;
+    filePath: string;
+    entityType: EntityType;
+    startLine: number;
+    endLine: number;
+    isExported: boolean;
+    dependencies?: ExtractedDependency[];
+}
+export interface AstExtractionResult {
+    filePath: string;
+    symbols: ExtractedSymbol[];
+    dependencies: ExtractedDependency[];
+}
+export interface IndexSummary {
+    indexedFiles: number;
+    indexedSymbols: number;
+    indexedDependencies: number;
+}
+/**
+ * Normalizes file path to forward slashes.
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * Normalizes relative module specifiers against the importing file's directory.
+ * Maps .js, .mjs, .cjs to .ts, and .jsx to .tsx, while keeping extensionless specifiers bare.
+ */
+export declare function normalizeModuleSpecifier(filePath: string, specifier: string): string;
+/**
+ * Extracts symbols and dependencies from TypeScript / JavaScript source code.
+ */
+export declare function extractSymbolsFromSource(filePath: string, sourceText: string): ExtractedSymbol[];
+/**
+ * Comprehensive AST traversal returning both symbols and inter-symbol dependencies.
+ */
+export declare function extractAstData(filePath: string, sourceText: string): AstExtractionResult;
+/**
+ * Indexes a collection of files into Muninn's entities and entity_dependencies tables.
+ *
+ * Execution is cleanly separated into two stages (REV-001):
+ * 1. Synchronous file reading, filtering, validation, and AST parsing are performed in-memory outside any database transaction.
+ * 2. SQLite batch operations are executed inside a short-lived transaction with zombie entity pruning (REV-003, SEC-003).
+ */
+export declare function indexFilesIntoMuninn(memoryService: IMemoryService, filePaths: string[], options?: {
+    projectRoot?: string;
+}): IndexSummary;
+//# sourceMappingURL=ast-indexer.d.ts.map

package/dist/indexer/ast-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-indexer.d.ts","sourceRoot":"","sources":["../../src/indexer/ast-indexer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EACV,sBAAsB,EAEvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,sBAAsB,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,YAAY,EAAE,mBAAmB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,eAAe,EAAE,CAGnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,mBAAmB,CAyQrB;AAmBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,cAAc,EAC7B,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC,YAAY,CAwOd"}