@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/knowledge/prompt.js

@@ -0,0 +1,404 @@
+/**
+ * @file prompt.ts
+ * AI prompt engineering layer for the KB system (Phase 1D).
+ *
+ * Provides two prompt builders:
+ *  - buildModulePrompt  → per-module knowledge page generation
+ *  - buildOverviewPrompt → cross-module overview / architecture page
+ *
+ * And one response parser:
+ *  - parseAIResponse → extracts `content` + `refs` from raw AI output
+ *
+ * Defence lines 1–2 (of 5):
+ *  1. System prompt rules that forbid hallucination
+ *  2. Source truncation ceiling (≤ 30K tokens ≈ 90K chars)
+ *
+ * No AI calls are made in this file — it only produces prompt strings.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Maximum total characters of source code fed to the AI per module.
+ * Approximates the KB_MAX_TOKENS_PER_MODULE (30K tokens) ceiling at 3 chars/token.
+ */
+const MAX_CHARS_PER_MODULE = 90_000;
+// ─────────────────────────────────────────────────────────────────────────────
+// System prompt — module page
+// ─────────────────────────────────────────────────────────────────────────────
+const MODULE_SYSTEM_PROMPT = (projectName) => `你是 ${projectName} 项目知识库编译专家。基于提供的代码生成模块知识页。
+
+**严格规则**（违反即丢弃输出）：
+1. 只写代码中明确存在的事实，禁止推测
+2. 每个声明必须在末尾附 \`[file:L行号](路径)\` 引用
+3. 不确定时写 "TODO: verify (file)"
+4. 禁止"我推测"、"通常"、"一般来说"等主观词
+5. 引用必须从 repo-map 中选取，不要自造行号
+6. 所有 ref 路径必须以 \`src/\` 开头（含正文内联和 References 段），不可写 \`cli/index.ts:22\`
+7. lineEnd 必须 ≤ 文件实际行数；不确定范围结尾时只用 lineStart（即省略 -L<n> 后缀）
+8. 严格按 schema 输出 JSON（content + refs 数组）
+
+**输出 schema**：
+\`\`\`json
+{
+  "content": "<markdown 字符串>",
+  "refs": [
+    { "file": "src/daemon/server.ts", "lineStart": 51, "lineEnd": 65, "symbol": "SocketServer" }
+  ]
+}
+\`\`\`
+
+**markdown 章节结构**（按这个顺序）：
+## 概述
+（2-3 句话）
+
+## 核心组件
+（列出主要 class/function + 一行说明）
+
+## 内部数据流
+（这个模块内部如何工作）
+
+## 与其他模块的交互
+（导出什么，依赖谁）
+
+## 关键设计决策
+（如有）
+
+每段 ≤ 5 行，整页 ≤ 200 行 markdown。`;
+// ─────────────────────────────────────────────────────────────────────────────
+// System prompt — overview page
+// ─────────────────────────────────────────────────────────────────────────────
+const OVERVIEW_SYSTEM_PROMPT = (projectName) => `你是 ${projectName} 项目架构提炼专家。基于各模块摘要生成项目顶层 overview 页。
+
+**严格规则**：
+1. 不引入模块摘要中不存在的事实
+2. 引用模块名（如 modules/daemon.md）和符号，不写具体 file:line
+3. 章节：## 项目定位 / ## 顶层架构 / ## 模块组合 / ## 关键决策
+4. 整页 ≤ 100 行
+
+**输出**：纯 markdown（不要 JSON 包装）`;
+// ─────────────────────────────────────────────────────────────────────────────
+// buildModulePrompt
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Constructs the AI prompt for compiling a single module knowledge page.
+ *
+ * Defence line 1 — system prompt rules forbid hallucination.
+ * Defence line 2 — source content truncated to ≤ 90K chars (≈ 30K tokens).
+ *
+ * @param input  Module name, repo-map subset, and source file contents.
+ * @returns      A fully-formed `AIPrompt` ready to send to the AI.
+ */
+export function buildModulePrompt(input) {
+    // Build the repo-map JSON section (only the fields the AI needs).
+    const repoMapPayload = {
+        module: input.moduleName,
+        symbols: input.repoMapSubset.map((s) => ({
+            file: s.file,
+            line: s.line,
+            kind: s.kind,
+            name: s.name,
+            signature: s.signature,
+        })),
+    };
+    const repoMapJson = JSON.stringify(repoMapPayload, null, 2);
+    // Defence line 2: truncate fileContents so the total never exceeds the cap.
+    let totalChars = 0;
+    const truncatedFiles = [];
+    for (const f of input.fileContents) {
+        const remaining = MAX_CHARS_PER_MODULE - totalChars;
+        if (remaining <= 0)
+            break;
+        if (f.content.length > remaining) {
+            truncatedFiles.push({
+                path: f.path,
+                content: f.content.slice(0, remaining) + '\n// ... (truncated)',
+            });
+            totalChars = MAX_CHARS_PER_MODULE;
+            break;
+        }
+        truncatedFiles.push(f);
+        totalChars += f.content.length;
+    }
+    const filesSection = truncatedFiles
+        .map((f) => `// ${f.path}\n${f.content}`)
+        .join('\n\n');
+    const user = `模块：${input.moduleName}\n\n` +
+        `## repo-map（该模块所有符号）\n` +
+        '```json\n' +
+        repoMapJson +
+        '\n```\n\n' +
+        `## 源代码（截断到 30K tokens 内）\n` +
+        filesSection +
+        `\n\n请生成 modules/${input.moduleName}.md，严格按 schema 返回 JSON。`;
+    return { system: MODULE_SYSTEM_PROMPT(input.projectName), user, expectedSchema: 'module-page' };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// buildOverviewPrompt
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Constructs the AI prompt for compiling the cross-module overview page.
+ *
+ * Input is an array of `{ name, summary }` objects — one per module.
+ * The AI is instructed to produce **plain markdown** (not JSON-wrapped).
+ *
+ * @param allModuleSummaries  Summaries extracted from each compiled module page.
+ * @returns                   A fully-formed `AIPrompt`.
+ */
+export function buildOverviewPrompt(allModuleSummaries, projectName) {
+    const summarySection = allModuleSummaries
+        .map((s) => `### ${s.name}\n${s.summary}`)
+        .join('\n\n');
+    const user = `各模块摘要：\n\n` +
+        summarySection +
+        `\n\n请生成 overview.md。`;
+    return { system: OVERVIEW_SYSTEM_PROMPT(projectName), user, expectedSchema: 'plain-markdown' };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Markdown fence stripping utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Strip outer markdown code fences from AI-generated content.
+ *
+ * Handles common fence patterns:
+ *  - ` ```markdown\n...\n``` `
+ *  - ` ```md\n...\n``` `
+ *  - ` ```\n...\n``` `
+ *
+ * Used by cross-module page compilation to unwrap plain-markdown responses.
+ *
+ * @param content  Raw AI response text.
+ * @returns        Content with outer fences removed, or original if no fence detected.
+ */
+export function stripMarkdownFence(content) {
+    const trimmed = content.trim();
+    // Match ```markdown or ```md or just ``` at the start, and ``` at the end
+    const fenceStart = /^```(?:markdown|md)?\s*\n/;
+    const fenceEnd = /\n```\s*$/;
+    if (fenceStart.test(trimmed) && fenceEnd.test(trimmed)) {
+        return trimmed.replace(fenceStart, '').replace(fenceEnd, '').trim();
+    }
+    return content;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// parseAIResponse
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Parses the raw string returned by the AI into an `AIResponse`.
+ *
+ * Handles three common wrapping styles produced by different AI models:
+ *  1. Plain JSON object `{ "content": ..., "refs": [...] }`
+ *  2. Markdown fenced block `` ```json\n{...}\n``` ``
+ *  3. Markdown fenced block without language tag `` ```\n{...}\n``` ``
+ *
+ * Validation rules applied to `refs`:
+ *  - Each element must have `file` (string) and `lineStart` (number).
+ *  - Elements failing these checks are **silently dropped** (other valid refs
+ *    are preserved).
+ *
+ * @param raw  Raw string returned by the AI.
+ * @returns    Parsed `AIResponse`, or `null` when parsing fails or the
+ *             top-level schema is invalid.  Callers should treat `null` as
+ *             "AI returned non-conforming output" and handle accordingly.
+ */
+export function parseAIResponse(raw) {
+    // Strip markdown code fences that many AI models insert unconditionally.
+    let cleaned = raw.trim();
+    if (cleaned.startsWith('```')) {
+        cleaned = cleaned
+            .replace(/^```(?:json)?\n?/, '')
+            .replace(/\n?```$/, '');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch {
+        // AI returned plain markdown or unparseable text — caller walks the
+        // "AI non-conforming" branch.
+        return null;
+    }
+    // Top-level schema check.
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.content !== 'string' ||
+        !Array.isArray(parsed.refs)) {
+        return null;
+    }
+    const raw_obj = parsed;
+    // Filter refs: keep only items that have the required fields.
+    const refs = raw_obj.refs.filter((r) => typeof r === 'object' &&
+        r !== null &&
+        typeof r.file === 'string' &&
+        typeof r.lineStart === 'number');
+    return {
+        content: raw_obj.content,
+        refs,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Cross-module system prompts (v9.2)
+// ─────────────────────────────────────────────────────────────────────────────
+const ARCHITECTURE_SYSTEM_PROMPT = (projectName) => `你是 ${projectName} 项目架构提炼专家。基于模块摘要 + 精简 repo-map 生成 architecture.md。
+
+**严格规则**：
+1. 不引入输入中不存在的事实；如不确定写"TODO: verify"
+2. 引用模块名（modules/<name>.md）和导出符号名，不写具体 file:line
+3. 章节固定：## 分层 / ## 数据流 / ## 关键接口 / ## 扩展点 / ## 部署形态
+4. "## 关键接口"段每个接口用 \`符号名 (modules/X.md)\` 格式列出
+5. "## 数据流"用 1 段文字 + 1 个 mermaid 或 ASCII 流程图（≤ 10 节点）
+6. 整页 ≤ 150 行
+7. 禁止"通常"、"一般来说"、"我推测"等主观词
+
+**输出**：纯 markdown（不要 JSON 包装）`;
+const DECISIONS_SYSTEM_PROMPT = (projectName) => `你是 ${projectName} 项目技术决策提炼专家。基于各模块"关键设计决策"段 + 最近 git 提交，生成 ADR-lite 风格的 decisions.md。
+
+**严格规则**：
+1. 你的目标不是复述 git log，而是从中抽象出**项目级技术决策**
+2. 每条决策格式固定：
+   ### Decision N: <标题>
+   **Why**: <为什么这么做（1-2 句）>
+   **Trade-off**: <代价是什么（1 句）>
+   **Alternative**: <还可以怎么做（1 句）>
+3. 只列出输入中能明确支撑的决策；不确定时跳过
+4. 决策数量 5-15 条，按"重要性递减"排序
+5. 引用模块名（modules/<name>.md），不写 file:line
+6. 整页 ≤ 200 行
+
+**输出**：纯 markdown`;
+const GLOSSARY_SYSTEM_PROMPT = (projectName) => `你是 ${projectName} 项目术语提炼专家。基于各模块知识页 + 项目根 CLAUDE.md，生成 glossary.md。
+
+**严格规则**：
+1. 只列出在输入中真实出现的术语（**不要**列出通用编程术语）
+2. 每条格式固定：
+   **<Term>** — <定义，≤ 2 句>。出处：modules/X.md
+3. 按字母（中文/英文混合）排序
+4. 同一术语在多个 module 出现 → 出处列举所有，逗号分隔
+5. 不超过 50 条；超出时按"出现次数"裁剪
+6. 整页 ≤ 300 行
+7. 禁止"通常指"、"一般来说"等泛化定义
+
+**输出**：纯 markdown`;
+const TECH_STACK_SYSTEM_PROMPT = (projectName) => `你是 ${projectName} 项目技术栈提炼专家。基于 package.json / tsconfig.json / vitest.config.ts 生成 tech-stack.md。
+
+**严格规则**：
+1. 列表来源**只能**是 package.json 的 dependencies / devDependencies
+2. 章节固定：## 运行时 / ## 框架 / ## 数据库 / ## 测试 / ## 工具链 / ## TypeScript 配置
+3. 每个包格式：- **<包名>@<版本>** — <一句话说明为什么选它，基于包功能推断>
+4. 包归类规则（模糊归类即可）：
+   - 运行时：node 内置、@anthropic-ai/sdk
+   - 框架：express、commander
+   - 数据库：better-sqlite3
+   - 测试：vitest、supertest
+   - 工具链：typescript、chalk、gray-matter、js-yaml、zod
+5. ## TypeScript 配置段总结 strict / target / module 三项关键设置
+6. 整页 ≤ 150 行
+
+**输出**：纯 markdown`;
+// ─────────────────────────────────────────────────────────────────────────────
+// Cross-module prompt builders (v9.2)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Build the AI prompt for `architecture.md`.
+ *
+ * Input is module summaries + a flattened mini repo-map (one row per exported
+ * top-level symbol). The AI is instructed to emit plain markdown — the caller
+ * does NOT run `parseAIResponse` on the result.
+ */
+export function buildArchitecturePrompt(input) {
+    const summarySection = input.moduleSummaries
+        .map((s) => `### ${s.name}\n${s.summary}`)
+        .join('\n\n');
+    const symbolsByModule = new Map();
+    for (const r of input.repoMapMini) {
+        if (!symbolsByModule.has(r.module))
+            symbolsByModule.set(r.module, []);
+        symbolsByModule.get(r.module).push({ symbol: r.symbol, kind: r.kind });
+    }
+    const repoMapSection = [...symbolsByModule.entries()]
+        .map(([mod, syms]) => `### ${mod}\n` + syms.map((s) => `- ${s.kind} \`${s.symbol}\``).join('\n'))
+        .join('\n\n');
+    const user = `## 各模块摘要\n\n` +
+        summarySection +
+        `\n\n## 精简 repo-map（仅导出顶层符号）\n\n` +
+        repoMapSection +
+        `\n\n请生成 architecture.md，严格遵守 system prompt 中的章节结构与行数上限。`;
+    return { system: ARCHITECTURE_SYSTEM_PROMPT(input.projectName), user, expectedSchema: 'plain-markdown' };
+}
+/**
+ * Build the AI prompt for `decisions.md`.
+ *
+ * Combines the "关键设计决策" sections from every module page with the latest
+ * git log (one-line). The AI should abstract project-level decisions, NOT
+ * paraphrase git commits.
+ */
+export function buildDecisionsPrompt(input) {
+    const decisionsSection = input.moduleDecisions
+        .filter((d) => d.decisions.trim().length > 0)
+        .map((d) => `### ${d.name} 的决策\n${d.decisions}`)
+        .join('\n\n');
+    const commitsSection = input.recentCommits.length > 0
+        ? input.recentCommits.map((c) => `- ${c}`).join('\n')
+        : '（无 git 提交记录）';
+    const user = `## 各模块决策段\n\n` +
+        (decisionsSection || '（暂无显式决策段）') +
+        `\n\n## 最近 git 提交（--oneline -30）\n\n` +
+        commitsSection +
+        `\n\n请生成 decisions.md，严格遵守 ADR-lite 格式。`;
+    return { system: DECISIONS_SYSTEM_PROMPT(input.projectName), user, expectedSchema: 'plain-markdown' };
+}
+/**
+ * Build the AI prompt for `glossary.md`.
+ *
+ * Input is the full content of every module page plus the project-root
+ * CLAUDE.md (if present). The AI extracts proper-noun terms only (never
+ * generic programming jargon).
+ */
+export function buildGlossaryPrompt(input) {
+    const contentsSection = input.moduleContents
+        .map((m) => `### ${m.name}\n${m.content}`)
+        .join('\n\n---\n\n');
+    const claudeMdSection = input.claudeMdContent !== null && input.claudeMdContent.trim().length > 0
+        ? `## CLAUDE.md（项目根）\n\n${input.claudeMdContent}`
+        : '## CLAUDE.md\n\n（项目无 CLAUDE.md）';
+    const user = `## 各模块知识页内容\n\n` +
+        contentsSection +
+        `\n\n${claudeMdSection}\n\n` +
+        `请生成 glossary.md，只列输入中真实出现的术语，每条注明出处。`;
+    return { system: GLOSSARY_SYSTEM_PROMPT(input.projectName), user, expectedSchema: 'plain-markdown' };
+}
+/**
+ * Build the AI prompt for `tech-stack.md`.
+ *
+ * Inputs are the raw text of `package.json`, `tsconfig.json` and
+ * `vitest.config.ts`. tsconfig / vitest are optional (null when missing).
+ */
+export function buildTechStackPrompt(input) {
+    const lines = [];
+    lines.push('## package.json');
+    lines.push('```json');
+    lines.push(input.packageJson);
+    lines.push('```');
+    if (input.tsconfig) {
+        lines.push('');
+        lines.push('## tsconfig.json');
+        lines.push('```json');
+        lines.push(input.tsconfig);
+        lines.push('```');
+    }
+    if (input.vitestConfig) {
+        lines.push('');
+        lines.push('## vitest.config.ts');
+        lines.push('```ts');
+        lines.push(input.vitestConfig);
+        lines.push('```');
+    }
+    lines.push('');
+    lines.push('请生成 tech-stack.md，严格按 system prompt 中的章节顺序与归类规则；只列 package.json 实际存在的包。');
+    return {
+        system: TECH_STACK_SYSTEM_PROMPT(input.projectName),
+        user: lines.join('\n'),
+        expectedSchema: 'plain-markdown',
+    };
+}
+//# sourceMappingURL=prompt.js.map

package/dist/knowledge/prompt.js.map

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

package/dist/knowledge/query.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file query.ts
+ * KB Phase 3A — Retrieval layer.
+ *
+ * v9.0 strategy: keyword-only search across KB pages + optional repo-map
+ * symbol matching.  No AI calls, no vector index.
+ *
+ * Public API:
+ *   queryKnowledge  – keyword search returning scored hits
+ *   listKnowledge   – enumerate all KB pages
+ *   getPage         – fetch a single page by name
+ *   isKnowledgeBuilt – check whether .forge-knowledge/ is initialised
+ */
+import type { KBPage } from './types.js';
+import type { RepoMapSymbol } from './repo-map.js';
+import type { SQLiteStorage } from '../core/storage/sqlite.js';
+/** Test-only hook — flush the cache between isolated tmpdir test runs. */
+export declare function _clearPageCacheForTests(): void;
+/** Test-only hook — inspect cache size without exposing the cache itself. */
+export declare function _pageCacheSizeForTests(): number;
+export interface QueryOptions {
+    /** Absolute project root. Defaults to `process.cwd()`. */
+    projectRoot?: string;
+    /** Maximum number of pages to return. Defaults to 3. */
+    maxResults?: number;
+    /**
+     * When `true` (default), also search the repo-map for symbols whose name
+     * contains any of the query keywords.
+     */
+    includeRepoMap?: boolean;
+    /**
+     * @deprecated v9.0 alias kept for one minor cycle; KB query is keyword-only.
+     * Will be removed in v10.0.
+     */
+    mode?: 'keyword';
+    /**
+     * Optional storage handle for telemetry (v9.5+).
+     *
+     * When supplied, every queryKnowledge call appends a row to `kb_query_log`.
+     * Failures swallowed (fail-silent) — telemetry MUST NEVER break the query.
+     *
+     * CLI omits this option (no daemon, no storage instance).
+     */
+    storage?: SQLiteStorage;
+}
+export interface QueryHit {
+    /** The matched KB page. */
+    page: KBPage;
+    /** Relevance score 0-100 (higher is better). */
+    score: number;
+    /** Keywords from the query that matched content in this page. */
+    matched_keywords: string[];
+    /** Which content fields had at least one keyword match. */
+    matched_in: ('title' | 'content' | 'refs')[];
+}
+export interface QueryResultExtended {
+    /** The original query string. */
+    query: string;
+    /** Matched pages sorted by score descending. */
+    pages: QueryHit[];
+    /**
+     * Repo-map symbols whose name contains a query keyword.
+     * Only populated when `includeRepoMap !== false`.
+     */
+    repo_map_hits?: RepoMapSymbol[];
+    /** Total number of KB pages examined (for diagnostics). */
+    total_pages_scanned: number;
+}
+/**
+ * Keyword search over all KB pages.
+ *
+ * Algorithm:
+ *   1. Load all pages from `.forge-knowledge/` (top-level + modules/).
+ *   2. Tokenise the query string.
+ *   3. Score every page against the token list.
+ *   4. Return the top `maxResults` pages sorted by score descending.
+ *   5. Optionally include repo-map symbol hits for the same tokens.
+ *
+ * When the KB directory does not exist, returns an empty result without
+ * throwing so callers do not need to guard.
+ */
+export declare function queryKnowledge(query: string, options?: QueryOptions): Promise<QueryResultExtended>;
+/**
+ * List every KB page under `<projectRoot>/.forge-knowledge/`.
+ *
+ * Scans:
+ *   - Top-level `*.md` files (e.g. `overview.md`, `architecture.md`)
+ *   - `modules/*.md` files
+ *
+ * Pages that cannot be parsed are silently skipped.
+ */
+export declare function listKnowledge(projectRoot?: string): Promise<KBPage[]>;
+/**
+ * Retrieve a single KB page by its `name` field (relative path within
+ * `.forge-knowledge/`, e.g. `"modules/daemon.md"`).
+ *
+ * Returns `null` when the page file does not exist.
+ */
+export declare function getPage(name: string, projectRoot?: string): Promise<KBPage | null>;
+/**
+ * Return `true` when the KB has been initialised in `projectRoot`
+ * (i.e. the `.meta.json` sentinel file is present inside `.forge-knowledge/`).
+ */
+export declare function isKnowledgeBuilt(projectRoot?: string): boolean;
+//# sourceMappingURL=query.d.ts.map

package/dist/knowledge/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/knowledge/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAS,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAqB/D,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAMD,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IAEd,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAE3B,2DAA2D;IAC3D,UAAU,EAAE,CAAC,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,gDAAgD;IAChD,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC;IAEhC,2DAA2D;IAC3D,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAwLD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAgF9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,WAAW,SAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA2ClF;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,WAAW,SAAgB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,SAAgB,GAAG,OAAO,CAErE"}