autosnippet 3.2.10 → 3.2.12

package/dist/lib/shared/schemas/mcp-tools.js

@@ -0,0 +1,327 @@
+/**
+ * mcp-tools.ts — MCP 工具输入 Zod Schema
+ *
+ * 每个 MCP 工具的输入参数定义为 Zod Schema，既做运行时校验，
+ * 又可通过 zodToJsonSchema() 自动生成 inputSchema 声明（消除双重维护）。
+ *
+ * 命名约定：`{ToolSuffix}Input`，如 `SearchInput` 对应 `autosnippet_search`。
+ *
+ * @module shared/schemas/mcp-tools
+ */
+import { z } from 'zod';
+import { ComplexityEnum, ContentSchema, IdField, KindEnum, LanguageField, ReasoningSchema, ScopeEnum, StrictKindEnum, TitleField, } from './common.js';
+// ══════════════════════════════════════════════════════
+//  1. autosnippet_health — 无参数
+// ══════════════════════════════════════════════════════
+export const HealthInput = z.object({});
+// ══════════════════════════════════════════════════════
+//  2. autosnippet_search
+// ══════════════════════════════════════════════════════
+export const SearchInput = z.object({
+    query: z.string().min(1, 'query is required'),
+    mode: z.enum(['auto', 'keyword', 'bm25', 'semantic', 'context']).default('auto'),
+    kind: KindEnum.default('all'),
+    limit: z.number().int().min(1).max(100).default(10),
+    language: z.string().optional(),
+    sessionId: z.string().optional(),
+    sessionHistory: z.array(z.record(z.string(), z.unknown())).optional(),
+});
+// ══════════════════════════════════════════════════════
+//  3. autosnippet_knowledge
+// ══════════════════════════════════════════════════════
+export const KnowledgeInput = z
+    .object({
+    operation: z.enum(['list', 'get', 'insights', 'confirm_usage']).default('list'),
+    id: z.string().optional(),
+    kind: KindEnum.optional(),
+    language: z.string().optional(),
+    category: z.string().optional(),
+    knowledgeType: z.string().optional(),
+    status: z.string().optional(),
+    complexity: z.string().optional(),
+    limit: z.number().int().min(1).max(200).default(20),
+    usageType: z.enum(['adoption', 'application']).optional(),
+    feedback: z.string().optional(),
+})
+    .refine((d) => {
+    if (['get', 'insights', 'confirm_usage'].includes(d.operation) && !d.id) {
+        return false;
+    }
+    return true;
+}, { message: 'id is required for get/insights/confirm_usage operations' });
+// ══════════════════════════════════════════════════════
+//  4. autosnippet_structure
+// ══════════════════════════════════════════════════════
+export const StructureInput = z.object({
+    operation: z.enum(['targets', 'files', 'metadata']).default('targets'),
+    targetName: z.string().optional(),
+    includeSummary: z.boolean().default(true),
+    includeContent: z.boolean().default(false),
+    contentMaxLines: z.number().int().min(1).default(100),
+    maxFiles: z.number().int().min(1).max(5000).default(500),
+});
+// ══════════════════════════════════════════════════════
+//  5. autosnippet_graph
+// ══════════════════════════════════════════════════════
+export const GraphInput = z.object({
+    operation: z.enum(['query', 'impact', 'path', 'stats']),
+    nodeId: z.string().optional(),
+    nodeType: z.string().default('recipe'),
+    fromId: z.string().optional(),
+    toId: z.string().optional(),
+    direction: z.enum(['out', 'in', 'both']).default('both'),
+    maxDepth: z.number().int().min(1).max(10).default(3),
+    relation: z.string().optional(),
+});
+// ══════════════════════════════════════════════════════
+//  6. autosnippet_call_context
+// ══════════════════════════════════════════════════════
+export const CallContextInput = z.object({
+    methodName: z.string().min(1, 'methodName is required'),
+    direction: z.enum(['callers', 'callees', 'both', 'impact']).default('both'),
+    maxDepth: z.number().int().min(1).max(5).default(2),
+});
+// ══════════════════════════════════════════════════════
+//  7. autosnippet_guard
+// ══════════════════════════════════════════════════════
+export const GuardInput = z.object({
+    files: z.array(z.string()).optional(),
+    code: z.string().optional(),
+    language: z.string().optional(),
+    filePath: z.string().optional(),
+});
+// ══════════════════════════════════════════════════════
+//  7b. autosnippet_submit_knowledge
+// ══════════════════════════════════════════════════════
+export const SubmitKnowledgeInput = z.object({
+    // ── 必填字段 ──
+    title: TitleField,
+    language: LanguageField,
+    content: ContentSchema,
+    kind: StrictKindEnum,
+    doClause: z.string().min(1, 'doClause is required'),
+    dontClause: z.string().min(1, 'dontClause is required'),
+    whenClause: z.string().min(1, 'whenClause is required'),
+    coreCode: z.string().min(1, 'coreCode is required'),
+    category: z.string().min(1, 'category is required'),
+    trigger: z.string().min(1, 'trigger is required'),
+    description: z.string().min(1, 'description is required'),
+    headers: z.array(z.string()),
+    usageGuide: z.string().min(1, 'usageGuide is required'),
+    knowledgeType: z.string().min(1, 'knowledgeType is required'),
+    reasoning: ReasoningSchema,
+    // ── 可选字段 ──
+    topicHint: z.string().optional(),
+    complexity: ComplexityEnum.optional(),
+    scope: ScopeEnum.optional(),
+    difficulty: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    constraints: z.record(z.string(), z.unknown()).optional(),
+    relations: z.record(z.string(), z.unknown()).optional(),
+    headerPaths: z.array(z.string()).optional(),
+    moduleName: z.string().optional(),
+    includeHeaders: z.boolean().optional(),
+    source: z.string().optional(),
+    client_id: z.string().optional(),
+    skipDuplicateCheck: z.boolean().default(false),
+    dimensionId: z.string().optional(),
+});
+// ══════════════════════════════════════════════════════
+//  8. autosnippet_submit_knowledge_batch
+// ══════════════════════════════════════════════════════
+export const SubmitKnowledgeBatchInput = z.object({
+    target_name: z.string().min(1, 'target_name is required'),
+    items: z.array(z.record(z.string(), z.unknown())).min(1, 'items array must not be empty'),
+    source: z.string().default('cursor-scan'),
+    deduplicate: z.boolean().default(true),
+    client_id: z.string().optional(),
+    dimensionId: z.string().optional(),
+});
+// ══════════════════════════════════════════════════════
+//  9. autosnippet_save_document
+// ══════════════════════════════════════════════════════
+export const SaveDocumentInput = z.object({
+    title: TitleField,
+    markdown: z.string().min(1, 'markdown content is required'),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    scope: z.enum(['universal', 'project-specific']).default('project-specific'),
+    source: z.string().optional(),
+});
+// ══════════════════════════════════════════════════════
+//  10. autosnippet_skill
+// ══════════════════════════════════════════════════════
+export const SkillInput = z.object({
+    operation: z.enum(['list', 'load', 'create', 'update', 'delete', 'suggest']),
+    name: z.string().optional(),
+    skillName: z.string().optional(),
+    section: z.string().optional(),
+    description: z.string().optional(),
+    content: z.string().optional(),
+    overwrite: z.boolean().default(false),
+    createdBy: z.enum(['manual', 'user-ai', 'system-ai', 'external-ai']).default('external-ai'),
+});
+// ══════════════════════════════════════════════════════
+//  11. autosnippet_bootstrap — 无参数
+// ══════════════════════════════════════════════════════
+export const BootstrapInput = z.object({});
+// ══════════════════════════════════════════════════════
+//  11b. autosnippet_dimension_complete
+// ══════════════════════════════════════════════════════
+export const DimensionCompleteInput = z.object({
+    sessionId: z.string().optional(),
+    dimensionId: z.string().min(1, 'dimensionId is required'),
+    submittedRecipeIds: z.array(z.string()).optional(),
+    analysisText: z.string().min(1, 'analysisText is required'),
+    referencedFiles: z.array(z.string()).optional(),
+    keyFindings: z.array(z.string()).optional(),
+    candidateCount: z.number().int().min(0).optional(),
+    crossDimensionHints: z.record(z.string(), z.string()).optional(),
+});
+// ══════════════════════════════════════════════════════
+//  11c. autosnippet_wiki_plan
+// ══════════════════════════════════════════════════════
+export const WikiPlanInput = z.object({
+    language: z.enum(['zh', 'en']).default('zh'),
+    sessionId: z.string().optional(),
+});
+// ══════════════════════════════════════════════════════
+//  11d. autosnippet_wiki_finalize
+// ══════════════════════════════════════════════════════
+export const WikiFinalizeInput = z.object({
+    articlesWritten: z.array(z.string()).min(1, 'articlesWritten must not be empty'),
+});
+// ══════════════════════════════════════════════════════
+//  12. autosnippet_capabilities — 无参数
+// ══════════════════════════════════════════════════════
+export const CapabilitiesInput = z.object({});
+// ══════════════════════════════════════════════════════
+//  13. autosnippet_task
+// ══════════════════════════════════════════════════════
+export const TaskInput = z.object({
+    operation: z.enum([
+        'prime',
+        'ready',
+        'create',
+        'claim',
+        'close',
+        'fail',
+        'defer',
+        'progress',
+        'show',
+        'list',
+        'stats',
+        'blocked',
+        'decompose',
+        'dep_add',
+        'dep_tree',
+        'record_decision',
+        'revise_decision',
+        'unpin_decision',
+        'list_decisions',
+    ]),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    design: z.string().optional(),
+    acceptance: z.string().optional(),
+    priority: z.number().int().min(0).max(4).optional(),
+    taskType: z.enum(['epic', 'task', 'bug', 'chore']).optional(),
+    parentId: z.string().optional(),
+    id: z.string().optional(),
+    reason: z.string().optional(),
+    rationale: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    relatedTaskId: z.string().optional(),
+    dependsOn: z.string().optional(),
+    depType: z
+        .enum([
+        'blocks',
+        'parent-child',
+        'waits-for',
+        'discovered-from',
+        'related',
+        'knowledge-ref',
+        'supersedes',
+    ])
+        .default('blocks'),
+    limit: z.number().int().min(1).max(200).default(10),
+    status: z.enum(['open', 'in_progress', 'deferred', 'closed', 'pinned']).optional(),
+    withKnowledge: z.boolean().default(true),
+    subtasks: z
+        .array(z.object({
+        title: z.string().min(1),
+        description: z.string().optional(),
+        priority: z.number().int().min(0).max(4).optional(),
+        taskType: z.string().optional(),
+        blockedByIndex: z.number().int().min(0).optional(),
+    }))
+        .optional(),
+});
+// ══════════════════════════════════════════════════════
+//  Admin Tools
+// ══════════════════════════════════════════════════════
+// 14. autosnippet_enrich_candidates
+export const EnrichCandidatesInput = z.object({
+    candidateIds: z
+        .array(z.string())
+        .min(1, 'at least one candidate ID required')
+        .max(20, 'max 20 candidates per call'),
+});
+// 15. autosnippet_knowledge_lifecycle
+export const KnowledgeLifecycleInput = z.object({
+    id: IdField,
+    action: z.enum([
+        'submit',
+        'approve',
+        'reject',
+        'publish',
+        'deprecate',
+        'reactivate',
+        'to_draft',
+        'fast_track',
+    ]),
+    reason: z.string().optional(),
+});
+// 16. autosnippet_validate_candidate
+export const ValidateCandidateInput = z.object({
+    candidate: z.record(z.string(), z.unknown()),
+    strict: z.boolean().default(false),
+});
+// 17. autosnippet_check_duplicate
+export const CheckDuplicateInput = z.object({
+    candidate: z.object({
+        title: z.string().optional(),
+        summary: z.string().optional(),
+        usageGuide: z.string().optional(),
+        code: z.string().optional(),
+    }),
+    threshold: z.number().min(0).max(1).default(0.7),
+    topK: z.number().int().min(1).max(50).default(5),
+});
+// ══════════════════════════════════════════════════════
+//  工具名 → Schema 映射表（用于 wrapHandler 自动注入校验）
+// ══════════════════════════════════════════════════════
+export const TOOL_SCHEMAS = {
+    autosnippet_health: HealthInput,
+    autosnippet_search: SearchInput,
+    autosnippet_knowledge: KnowledgeInput,
+    autosnippet_structure: StructureInput,
+    autosnippet_graph: GraphInput,
+    autosnippet_call_context: CallContextInput,
+    autosnippet_guard: GuardInput,
+    autosnippet_submit_knowledge: SubmitKnowledgeInput,
+    autosnippet_submit_knowledge_batch: SubmitKnowledgeBatchInput,
+    autosnippet_save_document: SaveDocumentInput,
+    autosnippet_skill: SkillInput,
+    autosnippet_bootstrap: BootstrapInput,
+    autosnippet_dimension_complete: DimensionCompleteInput,
+    autosnippet_wiki_plan: WikiPlanInput,
+    autosnippet_wiki_finalize: WikiFinalizeInput,
+    autosnippet_capabilities: CapabilitiesInput,
+    autosnippet_task: TaskInput,
+    autosnippet_enrich_candidates: EnrichCandidatesInput,
+    autosnippet_knowledge_lifecycle: KnowledgeLifecycleInput,
+    autosnippet_validate_candidate: ValidateCandidateInput,
+    autosnippet_check_duplicate: CheckDuplicateInput,
+};
+//# sourceMappingURL=mcp-tools.js.map

package/dist/lib/shared/schemas/mcp-tools.js.map

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

package/dist/lib/shared/shutdown.d.ts

@@ -0,0 +1,63 @@
+/**
+ * shutdown.ts — 统一 Graceful Shutdown 协调器
+ *
+ * 所有入口（mcp-server / api-server / cli）共用同一个 shutdown 协调器，
+ * 避免各入口重复编写 signal handler 并确保：
+ *   1. 防重入 — 多次信号只执行一轮 shutdown
+ *   2. 倒序执行 — 后注册的 hook 先关闭（类似栈 LIFO）
+ *   3. 强制超时 — 超过 TIMEOUT 强杀进程（默认 10 秒）
+ *   4. WAL checkpoint — DB 关闭前刷盘
+ *   5. hook 隔离 — 单个 hook 失败不阻断后续 hook 执行
+ *
+ * @module shared/shutdown
+ *
+ * @example
+ *   import { shutdown } from '#shared/shutdown.js';
+ *
+ *   shutdown.install();
+ *   shutdown.register(() => db.close());
+ *   shutdown.register(async () => await server.drain());
+ */
+/** Async or sync cleanup function */
+type ShutdownHook = () => Promise<void> | void;
+declare class ShutdownCoordinator {
+    #private;
+    /**
+     * Register a shutdown hook.
+     *
+     * Hooks execute in **reverse** registration order (LIFO):
+     * last registered = first executed.
+     *
+     * @param fn   Cleanup function (sync or async)
+     * @param label  Human-readable label for logging (e.g. 'database', 'http-server')
+     */
+    register(fn: ShutdownHook, label?: string): void;
+    /**
+     * Set the forced-exit timeout.
+     * @default 10_000 (10 seconds)
+     */
+    setTimeout(ms: number): void;
+    /**
+     * Execute all registered hooks in reverse order, then exit.
+     * Safe to call multiple times — only the first invocation runs.
+     *
+     * @param signal The signal or reason string (for logging)
+     */
+    execute(signal: string): Promise<void>;
+    /**
+     * Install SIGTERM + SIGINT handlers on the current process.
+     * Call this once, early in the entry's lifecycle.
+     */
+    install(): void;
+    /** Whether a shutdown is currently in progress */
+    get isShuttingDown(): boolean;
+    /** Number of registered hooks (for testing / diagnostics) */
+    get hookCount(): number;
+}
+/**
+ * Singleton shutdown coordinator.
+ * Import and use across all entry points and modules.
+ */
+export declare const shutdown: ShutdownCoordinator;
+export {};
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/lib/shared/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../lib/shared/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qCAAqC;AACrC,KAAK,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAI/C,cAAM,mBAAmB;;IAUvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,EAAE,KAAK,SAAc;IAI9C;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM;IAIrB;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM;IAkC5B;;;OAGG;IACH,OAAO;IAUP,kDAAkD;IAClD,IAAI,cAAc,YAEjB;IAED,6DAA6D;IAC7D,IAAI,SAAS,WAEZ;CACF;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,qBAA4B,CAAC"}

package/dist/lib/shared/shutdown.js

@@ -0,0 +1,111 @@
+/**
+ * shutdown.ts — 统一 Graceful Shutdown 协调器
+ *
+ * 所有入口（mcp-server / api-server / cli）共用同一个 shutdown 协调器，
+ * 避免各入口重复编写 signal handler 并确保：
+ *   1. 防重入 — 多次信号只执行一轮 shutdown
+ *   2. 倒序执行 — 后注册的 hook 先关闭（类似栈 LIFO）
+ *   3. 强制超时 — 超过 TIMEOUT 强杀进程（默认 10 秒）
+ *   4. WAL checkpoint — DB 关闭前刷盘
+ *   5. hook 隔离 — 单个 hook 失败不阻断后续 hook 执行
+ *
+ * @module shared/shutdown
+ *
+ * @example
+ *   import { shutdown } from '#shared/shutdown.js';
+ *
+ *   shutdown.install();
+ *   shutdown.register(() => db.close());
+ *   shutdown.register(async () => await server.drain());
+ */
+const DEFAULT_TIMEOUT_MS = 10_000;
+class ShutdownCoordinator {
+    /** Registered hooks executed in LIFO order */
+    #hooks = [];
+    /** Guard against re-entrant execution */
+    #shutting = false;
+    /** Configurable timeout (milliseconds) */
+    #timeoutMs = DEFAULT_TIMEOUT_MS;
+    /**
+     * Register a shutdown hook.
+     *
+     * Hooks execute in **reverse** registration order (LIFO):
+     * last registered = first executed.
+     *
+     * @param fn   Cleanup function (sync or async)
+     * @param label  Human-readable label for logging (e.g. 'database', 'http-server')
+     */
+    register(fn, label = 'anonymous') {
+        this.#hooks.push({ label, fn });
+    }
+    /**
+     * Set the forced-exit timeout.
+     * @default 10_000 (10 seconds)
+     */
+    setTimeout(ms) {
+        this.#timeoutMs = ms;
+    }
+    /**
+     * Execute all registered hooks in reverse order, then exit.
+     * Safe to call multiple times — only the first invocation runs.
+     *
+     * @param signal The signal or reason string (for logging)
+     */
+    async execute(signal) {
+        if (this.#shutting) {
+            return;
+        }
+        this.#shutting = true;
+        process.stderr.write(`[shutdown] ${signal} received, draining…\n`);
+        // Hard timeout safeguard
+        const timer = setTimeout(() => {
+            process.stderr.write('[shutdown] Timeout reached, forcing exit\n');
+            process.exit(1);
+        }, this.#timeoutMs);
+        timer.unref(); // Don't keep the event loop alive
+        // Execute hooks in reverse order (LIFO)
+        const reversed = [...this.#hooks].reverse();
+        let hasFailure = false;
+        for (const { label, fn } of reversed) {
+            try {
+                await fn();
+                process.stderr.write(`[shutdown] ✓ ${label}\n`);
+            }
+            catch (err) {
+                hasFailure = true;
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[shutdown] ✗ ${label}: ${msg}\n`);
+            }
+        }
+        clearTimeout(timer);
+        process.stderr.write(`[shutdown] Complete, exiting (code=${hasFailure ? 1 : 0})\n`);
+        process.exit(hasFailure ? 1 : 0);
+    }
+    /**
+     * Install SIGTERM + SIGINT handlers on the current process.
+     * Call this once, early in the entry's lifecycle.
+     */
+    install() {
+        const handler = (signal) => {
+            // Use void to suppress unhandled promise warning —
+            // the execute() method self-terminates with process.exit()
+            void this.execute(signal);
+        };
+        process.on('SIGTERM', () => handler('SIGTERM'));
+        process.on('SIGINT', () => handler('SIGINT'));
+    }
+    /** Whether a shutdown is currently in progress */
+    get isShuttingDown() {
+        return this.#shutting;
+    }
+    /** Number of registered hooks (for testing / diagnostics) */
+    get hookCount() {
+        return this.#hooks.length;
+    }
+}
+/**
+ * Singleton shutdown coordinator.
+ * Import and use across all entry points and modules.
+ */
+export const shutdown = new ShutdownCoordinator();
+//# sourceMappingURL=shutdown.js.map

package/dist/lib/shared/shutdown.js.map

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

package/dist/lib/shared/similarity.d.ts

@@ -0,0 +1,53 @@
+/**
+ * similarity — 统一相似度计算工具
+ *
+ * 项目内所有文本/向量相似度计算统一使用此模块：
+ *   - jaccardSimilarity: 基于 token 集合的 Jaccard 系数
+ *   - cosineSimilarity:  向量余弦相似度
+ *   - textSimilarity:    高层文本相似度（Jaccard + 可选子串加分）
+ *   - tokenizeForSimilarity: 通用 bigram 分词（面向相似度场景）
+ *
+ * @module shared/similarity
+ */
+/**
+ * 通用 bigram 分词 — 面向相似度计算
+ *
+ * 将文本小写化、去标点后，生成 word + character n-gram 集合。
+ * 同时支持 CJK（单字 + bigram）和英文（整词 + bigram）。
+ *
+ * @param {string} text 原始文本
+ * @param {number} [n=2] - n-gram 长度
+ * @returns {Set<string>} token 集合
+ */
+export declare function tokenizeForSimilarity(text: string, n?: number): Set<string>;
+/**
+ * Jaccard 相似度 — |A ∩ B| / |A ∪ B|
+ *
+ * @param {Set<string>} a - token 集合 A
+ * @param {Set<string>} b - token 集合 B
+ * @returns {number} 0.0 - 1.0
+ */
+export declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
+/**
+ * 余弦相似度 — 向量点积 / (||a|| * ||b||)
+ *
+ * @param {number[]} a 向量 A
+ * @param {number[]} b 向量 B
+ * @returns {number} 0.0 - 1.0（输入均为正值时）
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * 高层文本相似度 — Jaccard + 可选子串包含加分
+ *
+ * @param {string} textA 文本 A
+ * @param {string} textB 文本 B
+ * @param {object} [opts]
+ * @param {number} [opts.n=2] - n-gram 长度
+ * @param {boolean} [opts.substringBonus=false] 是否启用子串包含加分 (+0.3)
+ * @returns {number} 0.0 - 1.0
+ */
+export declare function textSimilarity(textA: string, textB: string, opts?: {
+    n?: number;
+    substringBonus?: boolean;
+}): number;
+//# sourceMappingURL=similarity.d.ts.map

package/dist/lib/shared/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../../lib/shared/similarity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,SAAI,eAmBxD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,UAiB/D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,UAcxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,UAgBpD"}