@coralai/sps-cli 0.50.24 → 0.51.0

package/dist/core/wiki/frontmatter.js

@@ -0,0 +1,109 @@
+/**
+ * @module        core/wiki/frontmatter
+ * @description   Frontmatter 解析、序列化、校验
+ *
+ * @layer         core
+ *
+ * 输入：raw markdown 文件内容（开头是 YAML 块 + body）。
+ * 输出：分离的 frontmatter（zod 校验过）+ body。
+ *
+ * 关键约束：
+ *   - 扁平 YAML（doc-28 §6 Page Schema）—— Obsidian Properties UI 不支持嵌套
+ *   - 缺 frontmatter / 不合法 → 返 error，**不 silently 接受残缺**
+ *     wiki page 来自 LLM 写入，松散 schema 会让格式漂移失控
+ */
+import YAML from 'yaml';
+import { FrontmatterSchema } from './types.js';
+// ─── 解析 ─────────────────────────────────────────────────────────
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+export class FrontmatterError extends Error {
+    cause;
+    issues;
+    constructor(message, cause, issues) {
+        super(message);
+        this.cause = cause;
+        this.issues = issues;
+        this.name = 'FrontmatterError';
+    }
+}
+/**
+ * 从完整 markdown 文件内容解析 frontmatter + body。
+ * 严格模式：
+ *   - 没 `---\n...\n---\n` 块 → throw
+ *   - YAML 解析失败 → throw
+ *   - zod 校验失败 → throw（issues 字段带详细路径）
+ */
+export function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_RE);
+    if (!match) {
+        throw new FrontmatterError('No frontmatter block found. Page must start with `---\\n<yaml>\\n---\\n`.');
+    }
+    const yamlBlock = match[1] ?? '';
+    const body = (match[2] ?? '').replace(/^\n+/, '');
+    let parsed;
+    try {
+        parsed = YAML.parse(yamlBlock);
+    }
+    catch (err) {
+        throw new FrontmatterError('YAML parse error in frontmatter', err);
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new FrontmatterError('Frontmatter must be a YAML object');
+    }
+    const result = FrontmatterSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new FrontmatterError('Frontmatter schema validation failed', result.error, result.error.issues.map((i) => ({
+            path: i.path.join('.'),
+            message: i.message,
+        })));
+    }
+    return { frontmatter: result.data, body };
+}
+/**
+ * 宽松解析：失败时返 null + 错误，不抛。
+ * 用途：lint 扫描整个 wiki 时，单页坏不该终止整个 lint。
+ */
+export function tryParseFrontmatter(content) {
+    try {
+        return { ok: true, value: parseFrontmatter(content) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof FrontmatterError ? err : new FrontmatterError(String(err), err),
+        };
+    }
+}
+// ─── 序列化 ───────────────────────────────────────────────────────
+/**
+ * Frontmatter + body → 完整 markdown 文件内容。
+ *
+ * - YAML 输出走 yaml lib 默认行为（块式、整齐排版、字符串可选引号）
+ * - body 末尾保证一个换行（POSIX 文件尾约定）
+ * - 校验过 frontmatter 才能进来——这里不再校验，调用方传合法对象
+ */
+export function serializeFrontmatter(frontmatter, body) {
+    // 用 yaml lib 控制输出风格
+    const yamlText = YAML.stringify(frontmatter, {
+        indent: 2,
+        lineWidth: 0, // 不自动折行（避免 wikilink 被切到下一行）
+        defaultStringType: 'PLAIN',
+        defaultKeyType: 'PLAIN',
+    }).replace(/\n$/, ''); // YAML.stringify 末尾会带 \n，去掉留我们自己控
+    const bodyTrimmed = body.replace(/^\n+/, '').replace(/\n+$/, '');
+    return `---\n${yamlText}\n---\n\n${bodyTrimmed}\n`;
+}
+/**
+ * 校验 frontmatter 对象（不需要先序列化）。
+ * 用于：内存里组装 page 后写盘前快速检查。
+ */
+export function validateFrontmatter(fm) {
+    const result = FrontmatterSchema.safeParse(fm);
+    if (result.success)
+        return { ok: true, value: result.data };
+    return {
+        ok: false,
+        error: new FrontmatterError('Frontmatter validation failed', result.error, result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message }))),
+    };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/core/wiki/frontmatter.js.map

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

package/dist/core/wiki/hot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 读 hot.md。文件不存在或损坏 → 返默认骨架（不阻塞 Worker prompt 注入）。
+ */
+export declare function readHot(repoDir: string): string;
+export interface HotCacheUpdate {
+    /** 时间戳（ISO 8601）；缺省 = now */
+    updatedAt?: string;
+    /** Last Updated 段的描述（一句话："完成卡 #18，加了 race-recovery"） */
+    lastUpdate: string;
+    /** Key Recent Facts 列表（每条一行） */
+    keyFacts?: readonly string[];
+    /** Recent Changes 列表（每条一行，建议带 [[wikilink]]） */
+    recentChanges?: readonly string[];
+    /** Active Threads 列表 */
+    activeThreads?: readonly string[];
+}
+/**
+ * 用结构化数据生成 hot.md 完整内容（覆盖式更新——hot 是 cache，不是 journal）。
+ *
+ * 长度控制：超过 SOFT_LIMIT 在末尾加 truncation 提示；超过 HARD_LIMIT 截断。
+ */
+export declare function renderHot(update: HotCacheUpdate): string;
+/**
+ * 渲染 + 原子写入 hot.md。
+ */
+export declare function writeHot(repoDir: string, update: HotCacheUpdate): void;
+//# sourceMappingURL=hot.d.ts.map

package/dist/core/wiki/hot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/hot.ts"],"names":[],"mappings":"AA+CA;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS/C;AAID,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,+CAA+C;IAC/C,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,wBAAwB;IACxB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA+CxD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAMtE"}

package/dist/core/wiki/hot.js

@@ -0,0 +1,124 @@
+/**
+ * @module        core/wiki/hot
+ * @description   Wiki hot.md 缓存：~500 字最近上下文（per-instance，gitignored）
+ *
+ * @layer         core
+ *
+ * doc-28 §10 / claude-obsidian "hot cache" 机制：每次 ingest / 卡完成后更新
+ * 一份"最近发生了什么"摘要，下次 Worker 启动瞬间 prime。
+ *
+ * 实现要点：
+ *   - 文件位置：`<repo>/wiki/.hot.md`（gitignored，per-instance 飘移）
+ *   - 长度软上限 500 字（hard cap 1000 字截断）
+ *   - 不存在 → 返默认骨架（让 Worker 不会因缺文件就出错）
+ *   - 写入时校验 frontmatter 是 valid meta page
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { wikiHotFile } from '../../shared/wikiPaths.js';
+// ─── Defaults ─────────────────────────────────────────────────────
+const DEFAULT_HOT_TEMPLATE = `---
+type: meta
+title: Hot Cache
+updated: 1970-01-01T00:00:00Z
+---
+
+# Recent Context
+
+## Last Updated
+（尚无活动。第一次 \`sps wiki update\` 或卡片完成后会自动填充。）
+
+## Key Recent Facts
+（none yet）
+
+## Recent Changes
+（none yet）
+
+## Active Threads
+（none yet）
+`;
+const SOFT_LIMIT_CHARS = 4000; // ~500 中文字 / ~1000 英文字
+const HARD_LIMIT_CHARS = 8000;
+// ─── Read ─────────────────────────────────────────────────────────
+/**
+ * 读 hot.md。文件不存在或损坏 → 返默认骨架（不阻塞 Worker prompt 注入）。
+ */
+export function readHot(repoDir) {
+    const path = wikiHotFile(repoDir);
+    if (!existsSync(path))
+        return DEFAULT_HOT_TEMPLATE;
+    try {
+        const content = readFileSync(path, 'utf-8');
+        return content;
+    }
+    catch {
+        return DEFAULT_HOT_TEMPLATE;
+    }
+}
+/**
+ * 用结构化数据生成 hot.md 完整内容（覆盖式更新——hot 是 cache，不是 journal）。
+ *
+ * 长度控制：超过 SOFT_LIMIT 在末尾加 truncation 提示；超过 HARD_LIMIT 截断。
+ */
+export function renderHot(update) {
+    const ts = update.updatedAt ?? new Date().toISOString();
+    const lines = [
+        '---',
+        'type: meta',
+        'title: Hot Cache',
+        `updated: ${ts}`,
+        '---',
+        '',
+        '# Recent Context',
+        '',
+        '## Last Updated',
+        update.lastUpdate.trim(),
+        '',
+        '## Key Recent Facts',
+    ];
+    if (update.keyFacts && update.keyFacts.length > 0) {
+        for (const f of update.keyFacts)
+            lines.push(`- ${f}`);
+    }
+    else {
+        lines.push('（none）');
+    }
+    lines.push('', '## Recent Changes');
+    if (update.recentChanges && update.recentChanges.length > 0) {
+        for (const c of update.recentChanges)
+            lines.push(`- ${c}`);
+    }
+    else {
+        lines.push('（none）');
+    }
+    lines.push('', '## Active Threads');
+    if (update.activeThreads && update.activeThreads.length > 0) {
+        for (const t of update.activeThreads)
+            lines.push(`- ${t}`);
+    }
+    else {
+        lines.push('（none）');
+    }
+    let content = lines.join('\n') + '\n';
+    if (content.length > SOFT_LIMIT_CHARS) {
+        if (content.length > HARD_LIMIT_CHARS) {
+            content = content.slice(0, HARD_LIMIT_CHARS) + '\n…（truncated to hard cap; review hot.md and trim）\n';
+        }
+        else {
+            content += '\n> ⚠ Hot cache exceeds soft limit (~500 字). Trim if needed.\n';
+        }
+    }
+    return content;
+}
+/**
+ * 渲染 + 原子写入 hot.md。
+ */
+export function writeHot(repoDir, update) {
+    const path = wikiHotFile(repoDir);
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const content = renderHot(update);
+    writeFileSync(path, content, { encoding: 'utf-8', mode: 0o644 });
+}
+//# sourceMappingURL=hot.js.map

package/dist/core/wiki/hot.js.map

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

package/dist/core/wiki/index-builder.d.ts

@@ -0,0 +1,37 @@
+import type { Page } from './types.js';
+/**
+ * 从 page 列表渲染 index.md 完整内容。
+ *
+ * 输出形如：
+ * ```md
+ * ---
+ * type: meta
+ * title: Wiki Index
+ * updated: 2026-04-27
+ * ---
+ *
+ * # Wiki Index
+ *
+ * Pages: 12 · Updated 2026-04-27
+ *
+ * ## Modules (3)
+ * - [[modules/PipelineService]]: TL;DR 摘要短句...
+ * - ...
+ *
+ * ## Lessons (4)
+ * - [[lessons/Stop Hook Race]]: ...
+ * ```
+ */
+export declare function renderIndex(pages: readonly Page[], opts?: {
+    updatedAt?: string;
+}): string;
+/**
+ * 写 index.md（全量重建）。
+ */
+export declare function writeIndex(repoDir: string, pages: readonly Page[]): void;
+/**
+ * 取 index.md 节选 top-N 行（不含 frontmatter）。
+ * 给 reader.ts 的 Layer 2 用——总是注入这一段。
+ */
+export declare function readIndexSummary(repoDir: string, maxLines?: number): string;
+//# sourceMappingURL=index-builder.d.ts.map

package/dist/core/wiki/index-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/index-builder.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,IAAI,EAAY,MAAM,YAAY,CAAC;AAYjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAuC7F;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,IAAI,CAMxE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAgBvE"}

package/dist/core/wiki/index-builder.js

@@ -0,0 +1,130 @@
+/**
+ * @module        core/wiki/index-builder
+ * @description   渲染 wiki/index.md：全部 page 的 catalog，按类型分组
+ *
+ * @layer         core
+ *
+ * doc-28 §10：reader 5 层注入策略里"index 节选 top-30 行"是 Worker prompt
+ * 知识地图来源——所以 index.md 必须**密集且 LLM-friendly**：
+ *   - 每条一行：`- [[type/Title]]: TL;DR 摘要`
+ *   - 按类型分组（### Modules / ### Concepts / ### Lessons / ...）
+ *   - 不写废话头（无引子、无 stats 表格之类）
+ *
+ * 重建时机：每次 ingest / write 后调用一次（cheap，纯函数+1 次 writeFile）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { wikiIndexFile } from '../../shared/wikiPaths.js';
+import { extractTLDR } from './searcher.js';
+// ─── Render ───────────────────────────────────────────────────────
+const SECTIONS = [
+    { type: 'module', label: 'Modules' },
+    { type: 'concept', label: 'Concepts' },
+    { type: 'decision', label: 'Decisions' },
+    { type: 'lesson', label: 'Lessons' },
+    { type: 'source', label: 'Sources' },
+];
+/**
+ * 从 page 列表渲染 index.md 完整内容。
+ *
+ * 输出形如：
+ * ```md
+ * ---
+ * type: meta
+ * title: Wiki Index
+ * updated: 2026-04-27
+ * ---
+ *
+ * # Wiki Index
+ *
+ * Pages: 12 · Updated 2026-04-27
+ *
+ * ## Modules (3)
+ * - [[modules/PipelineService]]: TL;DR 摘要短句...
+ * - ...
+ *
+ * ## Lessons (4)
+ * - [[lessons/Stop Hook Race]]: ...
+ * ```
+ */
+export function renderIndex(pages, opts = {}) {
+    const ts = opts.updatedAt ?? new Date().toISOString().slice(0, 10);
+    const total = pages.length;
+    const lines = [
+        '---',
+        'type: meta',
+        'title: Wiki Index',
+        `updated: ${ts}`,
+        '---',
+        '',
+        '# Wiki Index',
+        '',
+        `Pages: ${total} · Updated ${ts}`,
+        '',
+    ];
+    for (const section of SECTIONS) {
+        const inSection = pages.filter((p) => p.frontmatter.type === section.type);
+        if (inSection.length === 0)
+            continue;
+        lines.push(`## ${section.label} (${inSection.length})`);
+        // 按 title 字典序排
+        const sorted = inSection.slice().sort((a, b) => a.frontmatter.title.localeCompare(b.frontmatter.title, 'en'));
+        for (const page of sorted) {
+            const tldr = extractTLDR(page.body);
+            const oneliner = squashToOneLine(tldr, 120);
+            lines.push(`- [[${page.pageId}]]: ${oneliner}`);
+        }
+        lines.push('');
+    }
+    if (total === 0) {
+        lines.push('（empty—— run `sps wiki update` to populate）');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * 写 index.md（全量重建）。
+ */
+export function writeIndex(repoDir, pages) {
+    const path = wikiIndexFile(repoDir);
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const content = renderIndex(pages);
+    writeFileSync(path, content, { encoding: 'utf-8', mode: 0o644 });
+}
+/**
+ * 取 index.md 节选 top-N 行（不含 frontmatter）。
+ * 给 reader.ts 的 Layer 2 用——总是注入这一段。
+ */
+export function readIndexSummary(repoDir, maxLines = 30) {
+    const path = wikiIndexFile(repoDir);
+    if (!existsSync(path))
+        return '';
+    let content;
+    try {
+        content = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+    // strip frontmatter
+    const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
+    const lines = body.split('\n');
+    // 跳过 # Wiki Index 标题 + 空行
+    const start = lines.findIndex((l) => l.startsWith('## '));
+    if (start === -1)
+        return body.split('\n').slice(0, maxLines).join('\n');
+    return lines.slice(start, start + maxLines).join('\n');
+}
+// ─── helpers ──────────────────────────────────────────────────────
+/**
+ * 把 TL;DR 拍扁成一行 + 截短。给 Worker prompt 注入用——不能多行。
+ */
+function squashToOneLine(text, maxLen) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (flat.length <= maxLen)
+        return flat;
+    return flat.slice(0, maxLen - 1) + '…';
+}
+//# sourceMappingURL=index-builder.js.map

package/dist/core/wiki/index-builder.js.map

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

package/dist/core/wiki/linter.d.ts

@@ -0,0 +1,76 @@
+import type { Manifest, Page } from './types.js';
+export type IssueKind = 'orphan' | 'dead-link' | 'fm-gap' | 'stale';
+export type IssueSeverity = 'warn' | 'error';
+export interface LintIssue {
+    readonly kind: IssueKind;
+    readonly severity: IssueSeverity;
+    /** Page id where issue was found; null when issue is repo-level (e.g. stale source) */
+    readonly pageId: string | null;
+    /** One-line message */
+    readonly message: string;
+    /** Optional context: target page id / source path / field name */
+    readonly target?: string;
+}
+export interface LintReport {
+    readonly issues: readonly LintIssue[];
+    /** Counts grouped by kind for fast summary */
+    readonly counts: Record<IssueKind, number>;
+    readonly errorCount: number;
+    readonly warnCount: number;
+}
+export interface LintInput {
+    readonly pages: readonly Page[];
+    readonly manifest: Manifest;
+    readonly repoDir: string;
+}
+export declare function lintWiki(input: LintInput): LintReport;
+/**
+ * Orphan = page that nobody links to (via frontmatter related[] OR body wikilink).
+ *
+ * A solo page can still be valuable (e.g. just-written lesson) — orphan is **warn**,
+ * not error.
+ */
+export declare function checkOrphans(pages: readonly Page[]): LintIssue[];
+/**
+ * Dead link = wikilink "[[X]]" where X (resolved) is not in the page set.
+ *
+ * Errors for related[] (frontmatter); warnings for body links (in-flight writing).
+ */
+export declare function checkDeadLinks(pages: readonly Page[]): LintIssue[];
+/**
+ * Catches missing soft-required fields the zod schema can't enforce
+ * (e.g. empty title, empty TL;DR, all default tags). Schema-level errors
+ * are caught at parse time — this is a content sniff.
+ */
+export declare function checkFrontmatterGaps(pages: readonly Page[]): LintIssue[];
+/**
+ * Compare manifest's stored sha256 against current file hash on disk.
+ * Mismatch = source has drifted since last ingest → its derived pages may be stale.
+ *
+ * Files that don't exist on disk anymore are flagged as 'stale' too (they should
+ * be removed from manifest via finalize).
+ */
+export declare function checkStaleSources(manifest: Manifest, repoDir: string): LintIssue[];
+/**
+ * Resolve a "[[X]]" or "[[type/X]]" wikilink against the known pageId set.
+ *
+ * Strategy:
+ *   - "[[type/X]]" → look up exact pageId
+ *   - "[[X]]" → look up any pageId ending with "/X" (any type matches)
+ *
+ * Returns the resolved pageId, or null if unresolvable.
+ */
+export declare function resolveLinkToId(wikilink: string, ids: ReadonlySet<string>): string | null;
+export declare function extractBodyWikilinks(body: string): string[];
+/**
+ * Compare source mtime vs page mtime. Returns paths whose source is newer.
+ *
+ * Best-effort — file mtime precision varies (ext4 ns vs HFS+ 1s); we use a
+ * 60s threshold to avoid false positives.
+ */
+export declare function findOutdatedPages(manifest: Manifest, pages: readonly Page[], repoDir: string, thresholdMs?: number): {
+    sourcePath: string;
+    pageIds: string[];
+    sourceMtime: Date;
+}[];
+//# sourceMappingURL=linter.d.ts.map

package/dist/core/wiki/linter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linter.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/linter.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIjD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uBAAuB;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAID,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAOrD;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,EAAE,CA+BhE;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,EAAE,CA4BlE;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,EAAE,CAiCxE;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CA4BlF;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,GACvB,MAAM,GAAG,IAAI,CAaf;AAID,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM3D;AA0BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,OAAO,EAAE,MAAM,EACf,WAAW,SAAS,GACnB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,IAAI,CAAA;CAAE,EAAE,CA4BhE"}