@shgroup/opencode-serenity-plugin 0.2.0

package/dist/util/ready-state.js

@@ -0,0 +1,104 @@
+/**
+ * ReadyStateMachine — 两阶段 init 的状态机
+ *
+ * 参考 skillful 的 ReadyStateMachine.ts（91 行）。
+ *
+ * 阶段 1（同步）：plugin 入口立即返回 hooks；tools 立即可调用
+ * 阶段 2（异步）：后台做 IO 验证（RR1+RR2）；验证完成前 tool execute 阻塞等待
+ *
+ * 状态流转：
+ *   idle → loading → ready     (成功)
+ *                  → error     (IO 失败)
+ *                  → disabled  (条件不满足)
+ *
+ * 一次性 Promise：`whenReady()` 多次调用返回同一 Promise（不重复创建）。
+ */
+export class ReadyStateMachine {
+    current = "idle";
+    promise = null;
+    resolveFn = null;
+    rejectFn = null;
+    errorValue = null;
+    /** 当前状态（同步读）*/
+    get state() {
+        return this.current;
+    }
+    /** 状态对应的 reason（error/disabled 时）*/
+    get reason() {
+        return this.errorValue;
+    }
+    /**
+     * 启动后台验证。
+     * 多次调用安全：只有第一次会真正启动（之后的调用复用同一 Promise）。
+     */
+    start(loader) {
+        if (this.current === "loading") {
+            return this.promise;
+        }
+        if (this.current !== "idle") {
+            // 已 settled，直接 resolve 或 reject
+            return this.current === "ready"
+                ? Promise.resolve()
+                : Promise.reject(this.errorValue ?? new Error("unknown"));
+        }
+        this.current = "loading";
+        this.promise = new Promise((resolve, reject) => {
+            this.resolveFn = resolve;
+            this.rejectFn = reject;
+        });
+        loader()
+            .then(() => {
+            this.current = "ready";
+            this.resolveFn?.();
+        })
+            .catch((err) => {
+            this.current = "error";
+            this.errorValue =
+                err instanceof Error ? err : new Error(String(err));
+            this.rejectFn?.(this.errorValue);
+        });
+        return this.promise;
+    }
+    /** 工具执行前的阻塞等待 */
+    whenReady() {
+        if (this.current === "ready") {
+            return Promise.resolve();
+        }
+        if (this.current === "error" || this.current === "disabled") {
+            return Promise.reject(this.errorValue ?? new Error(`Serenity not active: ${this.current}`));
+        }
+        if (this.current === "loading" && this.promise) {
+            return this.promise;
+        }
+        // idle（未 start）— 视为 disabled
+        return Promise.reject(new Error("Serenity plugin not initialized: state=idle"));
+    }
+    /** 同步状态查询（不阻塞） */
+    isReady() {
+        return this.current === "ready";
+    }
+    /** 强制标记 disabled（不依赖 loader 完成；用于 plugin 入口短路 RR6 失败场景） */
+    markDisabled(reason) {
+        if (this.current !== "idle")
+            return; // 已 settled 不变
+        this.current = "disabled";
+        this.errorValue = new Error(reason);
+        // 不会 resolve 任何 promise（p1 用户可能永远不调用 whenReady）
+    }
+    /** 外部显式标记 ready（v0 同步激活完成后用；保留 start() 的 Promise 兼容性） */
+    markAsReady() {
+        if (this.current !== "loading" && this.current !== "idle")
+            return;
+        this.current = "ready";
+        this.resolveFn?.();
+    }
+    /** 重置（仅测试用） */
+    reset() {
+        this.current = "idle";
+        this.promise = null;
+        this.resolveFn = null;
+        this.rejectFn = null;
+        this.errorValue = null;
+    }
+}
+//# sourceMappingURL=ready-state.js.map

package/dist/util/ready-state.js.map

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

package/dist/util/serenity-file.d.ts

@@ -0,0 +1,30 @@
+/**
+ * /.serenity 文件工具 — RR1 验证 + 实例名读写
+ *
+ * 文件格式：纯文本，单行，内容 = 实例名
+ * 例：文件内容 "home-serenity" → 实例名 = "home-serenity"
+ *
+ * v1.10：新增 write/remove（RR7 init 用）
+ */
+export declare const SERENITY_FILENAME = ".serenity";
+/**
+ * 从 git root 读取 /.serenity 文件，trim 后返回实例名
+ * @throws SerenityFileNotFoundError 文件不存在
+ * @throws SerenityFileEmptyError 文件内容为空
+ */
+export declare function readSerenityFile(cwdRoot: string): string;
+/** 判断文件是否存在（不抛错版本，用于 chat.message hook 探测） */
+export declare function serenityFileExists(cwdRoot: string): boolean;
+/**
+ * 写 `/.serenity`（创建或覆盖）。
+ * 内容 = instanceName + '\n'（保持文件以换行结尾）。
+ * v1.10：RR7 init 主路径使用。
+ * @throws 如果 cwdRoot 不可写则透传 fs 错误
+ */
+export declare function writeSerenityFile(cwdRoot: string, instanceName: string): void;
+/**
+ * 删 `/.serenity`（v1.10：RR7 init rollback 用）。
+ * 文件不存在（ENOENT）静默忽略；其他错误透传。
+ */
+export declare function removeSerenityFile(cwdRoot: string): void;
+//# sourceMappingURL=serenity-file.d.ts.map

package/dist/util/serenity-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serenity-file.d.ts","sourceRoot":"","sources":["../../src/util/serenity-file.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAG7E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAMxD"}

package/dist/util/serenity-file.js

@@ -0,0 +1,69 @@
+/**
+ * /.serenity 文件工具 — RR1 验证 + 实例名读写
+ *
+ * 文件格式：纯文本，单行，内容 = 实例名
+ * 例：文件内容 "home-serenity" → 实例名 = "home-serenity"
+ *
+ * v1.10：新增 write/remove（RR7 init 用）
+ */
+import { readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { SerenityFileEmptyError, SerenityFileNotFoundError } from '../errors.js';
+export const SERENITY_FILENAME = '.serenity';
+/**
+ * 从 git root 读取 /.serenity 文件，trim 后返回实例名
+ * @throws SerenityFileNotFoundError 文件不存在
+ * @throws SerenityFileEmptyError 文件内容为空
+ */
+export function readSerenityFile(cwdRoot) {
+    const path = join(cwdRoot, SERENITY_FILENAME);
+    let content;
+    try {
+        content = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new SerenityFileNotFoundError(cwdRoot);
+        }
+        throw err;
+    }
+    const name = content.trim();
+    if (name === '') {
+        throw new SerenityFileEmptyError(path);
+    }
+    return name;
+}
+/** 判断文件是否存在（不抛错版本，用于 chat.message hook 探测） */
+export function serenityFileExists(cwdRoot) {
+    try {
+        readFileSync(join(cwdRoot, SERENITY_FILENAME), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 写 `/.serenity`（创建或覆盖）。
+ * 内容 = instanceName + '\n'（保持文件以换行结尾）。
+ * v1.10：RR7 init 主路径使用。
+ * @throws 如果 cwdRoot 不可写则透传 fs 错误
+ */
+export function writeSerenityFile(cwdRoot, instanceName) {
+    const path = join(cwdRoot, SERENITY_FILENAME);
+    writeFileSync(path, instanceName + '\n', 'utf8');
+}
+/**
+ * 删 `/.serenity`（v1.10：RR7 init rollback 用）。
+ * 文件不存在（ENOENT）静默忽略；其他错误透传。
+ */
+export function removeSerenityFile(cwdRoot) {
+    try {
+        unlinkSync(join(cwdRoot, SERENITY_FILENAME));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}
+//# sourceMappingURL=serenity-file.js.map

package/dist/util/serenity-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serenity-file.js","sourceRoot":"","sources":["../../src/util/serenity-file.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC9C,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,IAAI,yBAAyB,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC;QACH,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,YAAoB;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/util/tui-install.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Global TUI config auto-registration utility (v1.10.1)
+ *
+ * 背景：TUI plugin 只在 tui.json 文件里登记的路径下被加载。默认登记在
+ * 项目 tui.json（`<project-root>/tui.json`），
+ * 这意味着非 serenity 目录下 opencode 找不到 tui.json → plugin 不加载
+ * → `Tui(api)` 永不调 → `/serenity-init` slash command 不出现。
+ *
+ * 修复思路：plugin 在 `Tui(api)` 入口**自检并自安装**到 global TUI config
+ * （`$XDG_CONFIG_HOME/opencode/tui.json` 或 `~/.config/opencode/tui.json`）。
+ * 之后 opencode 在**任何**目录启动都会加载 plugin → slash command 全局可见。
+ *
+ * v1.18 统一：薄包装 install.ts 的 writePluginEntry + getGlobalConfigPath
+ * - install.ts 已是 XDG + Windows APPDATA 兼容（detectGlobalConfigHome）
+ * - install.ts 的 writePluginEntry 原子写、幂等、_plugin_origins 追踪
+ * - tui-install.ts 保留 toPluginSpec / getGlobalTuiConfigPath /
+ *   ensureGlobalTuiPluginRegistration 三个 public 名字（向后兼容 — tests
+ *   依赖这些 export 名）
+ *
+ * 行为差异（v1.18 收口）：
+ * - 之前 tui-install.ts 仅 XDG；现在 Windows 上走 APPDATA
+ * - 这是正确的：tui auto-install 与 bin install 行为对齐
+ * - 写盘时 install.ts 会更新 _plugin_origins（opencode 忽略未知 key）
+ */
+import { type InstallResult } from '../install.js';
+export type { InstallResult };
+export type InstallOptions = {
+    /** Override the config path (for tests). */
+    configPath?: string;
+};
+/** 解析 global TUI config 路径（薄包装到 install.ts#getGlobalConfigPath）
+ *
+ * 优先 `$XDG_CONFIG_HOME/opencode/tui.json`（respects XDG 规范），
+ * 回退到 `~/.config/opencode/tui.json`（或 Windows APPDATA）。
+ */
+export declare function getGlobalTuiConfigPath(): string;
+/**
+ * 把 plugin 文件路径或 `file://` URL 规范化为 `file://` spec。
+ *
+ * - `file://` URL → realpath → 重新编码
+ * - 绝对路径 → realpath → 编码
+ * - 相对路径 → 抛错（global registration 必须用绝对路径）
+ *
+ * 与 opencode `ConfigPlugin.resolvePluginSpec` 对齐，保证两边都把同一个文件
+ * 解析到同一个 `file://` URL。
+ */
+export declare function toPluginSpec(input: string): string;
+/**
+ * 把 plugin path 写入 global tui.json 的 `plugin` 数组（如果尚未存在）。
+ *
+ * 幂等：plugin path 已在 list 中则 no-op。保留 tui.json 其他字段。
+ * 失败返回 `{ changed: false, error }`，**不抛**。
+ *
+ * v1.18 内部：委托给 install.ts#writePluginEntry（原子写、_plugin_origins 追踪、
+ * XDG + APPDATA 兼容），本函数只做 plugin spec 规范化 + 错误包装。
+ *
+ * @param pluginPath  绝对文件路径或 `file://` URL（如 `dist/tui.js`）
+ * @param options     configPath 覆盖（仅测试用）
+ */
+export declare function ensureGlobalTuiPluginRegistration(pluginPath: string, options?: InstallOptions): InstallResult;
+//# sourceMappingURL=tui-install.d.ts.map

package/dist/util/tui-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-install.d.ts","sourceRoot":"","sources":["../../src/util/tui-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,MAAM,MAAM,cAAc,GAAG;IAC3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAuBf"}

package/dist/util/tui-install.js

@@ -0,0 +1,94 @@
+/**
+ * Global TUI config auto-registration utility (v1.10.1)
+ *
+ * 背景：TUI plugin 只在 tui.json 文件里登记的路径下被加载。默认登记在
+ * 项目 tui.json（`<project-root>/tui.json`），
+ * 这意味着非 serenity 目录下 opencode 找不到 tui.json → plugin 不加载
+ * → `Tui(api)` 永不调 → `/serenity-init` slash command 不出现。
+ *
+ * 修复思路：plugin 在 `Tui(api)` 入口**自检并自安装**到 global TUI config
+ * （`$XDG_CONFIG_HOME/opencode/tui.json` 或 `~/.config/opencode/tui.json`）。
+ * 之后 opencode 在**任何**目录启动都会加载 plugin → slash command 全局可见。
+ *
+ * v1.18 统一：薄包装 install.ts 的 writePluginEntry + getGlobalConfigPath
+ * - install.ts 已是 XDG + Windows APPDATA 兼容（detectGlobalConfigHome）
+ * - install.ts 的 writePluginEntry 原子写、幂等、_plugin_origins 追踪
+ * - tui-install.ts 保留 toPluginSpec / getGlobalTuiConfigPath /
+ *   ensureGlobalTuiPluginRegistration 三个 public 名字（向后兼容 — tests
+ *   依赖这些 export 名）
+ *
+ * 行为差异（v1.18 收口）：
+ * - 之前 tui-install.ts 仅 XDG；现在 Windows 上走 APPDATA
+ * - 这是正确的：tui auto-install 与 bin install 行为对齐
+ * - 写盘时 install.ts 会更新 _plugin_origins（opencode 忽略未知 key）
+ */
+import { realpathSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { writePluginEntry, getGlobalConfigPath, PLUGIN_ID, } from '../install.js';
+/** 解析 global TUI config 路径（薄包装到 install.ts#getGlobalConfigPath）
+ *
+ * 优先 `$XDG_CONFIG_HOME/opencode/tui.json`（respects XDG 规范），
+ * 回退到 `~/.config/opencode/tui.json`（或 Windows APPDATA）。
+ */
+export function getGlobalTuiConfigPath() {
+    return getGlobalConfigPath('tui.json');
+}
+/**
+ * 把 plugin 文件路径或 `file://` URL 规范化为 `file://` spec。
+ *
+ * - `file://` URL → realpath → 重新编码
+ * - 绝对路径 → realpath → 编码
+ * - 相对路径 → 抛错（global registration 必须用绝对路径）
+ *
+ * 与 opencode `ConfigPlugin.resolvePluginSpec` 对齐，保证两边都把同一个文件
+ * 解析到同一个 `file://` URL。
+ */
+export function toPluginSpec(input) {
+    let absPath;
+    if (input.startsWith('file://')) {
+        absPath = realpathSync(fileURLToPath(input));
+    }
+    else if (isAbsolute(input)) {
+        absPath = realpathSync(input);
+    }
+    else {
+        throw new Error(`plugin path must be absolute: ${input}`);
+    }
+    return pathToFileURL(absPath).href;
+}
+/**
+ * 把 plugin path 写入 global tui.json 的 `plugin` 数组（如果尚未存在）。
+ *
+ * 幂等：plugin path 已在 list 中则 no-op。保留 tui.json 其他字段。
+ * 失败返回 `{ changed: false, error }`，**不抛**。
+ *
+ * v1.18 内部：委托给 install.ts#writePluginEntry（原子写、_plugin_origins 追踪、
+ * XDG + APPDATA 兼容），本函数只做 plugin spec 规范化 + 错误包装。
+ *
+ * @param pluginPath  绝对文件路径或 `file://` URL（如 `dist/tui.js`）
+ * @param options     configPath 覆盖（仅测试用）
+ */
+export function ensureGlobalTuiPluginRegistration(pluginPath, options = {}) {
+    const configPath = options.configPath ?? getGlobalTuiConfigPath();
+    let spec;
+    try {
+        spec = toPluginSpec(pluginPath);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { changed: false, configPath, error: `bad plugin path: ${reason}` };
+    }
+    const absPath = fileURLToPath(spec);
+    const result = writePluginEntry(configPath, [{
+            id: PLUGIN_ID,
+            path: spec,
+            absPath,
+        }]);
+    return {
+        changed: result.changed,
+        configPath: result.configPath,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+    };
+}
+//# sourceMappingURL=tui-install.js.map

package/dist/util/tui-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tui-install.js","sourceRoot":"","sources":["../../src/util/tui-install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,SAAS,GAEV,MAAM,eAAe,CAAC;AASvB;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,mBAAmB,CAAC,UAAU,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,OAAe,CAAC;IACpB,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,GAAG,YAAY,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,CAAC;SAAM,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iCAAiC,CAC/C,UAAkB,EAClB,UAA0B,EAAE;IAE5B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,sBAAsB,EAAE,CAAC;IAElE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,oBAAoB,MAAM,EAAE,EAAE,CAAC;IAC7E,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,gBAAgB,CAAC,UAAU,EAAE,CAAC;YAC3C,EAAE,EAAE,SAAS;YACb,IAAI,EAAE,IAAI;YACV,OAAO;SACR,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC"}