@cerbur/clutch-dsh-worktree 0.1.0

package/lib/manage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/manage/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,YAAY,EACb,MAAM,sBAAsB,CAAC;AAE9B;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5D"}

package/lib/manage/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/manage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/manage/types.ts"],"names":[],"mappings":""}

package/lib/provider/git.d.ts

@@ -0,0 +1,42 @@
+import type { GitWorktreeAdapter, GitWorktreeInfo } from './types.js';
+/**
+ * 本地 Git worktree adapter：所有命令都以 DSH Workspace 根目录为 cwd，并仅使用固定的
+ * 本地子命令；不使用 `--force`，也不访问 remote。
+ *
+ * Local Git worktree adapter: every command runs with the DSH Workspace root as
+ * cwd and uses a fixed local-only subcommand; it never uses `--force` or accesses
+ * remotes.
+ */
+export declare class LocalGitAdapter implements GitWorktreeAdapter {
+    /**
+     * 分开验证“位于非 bare working tree”和“已有可解析的首个 commit”，以返回不同修复语义。
+     * Separately verifies “inside a non-bare working tree” and “has a resolvable
+     * initial commit” so callers receive distinct repair semantics.
+     */
+    validateRepository(workspaceRoot: string): Promise<void>;
+    /**
+     * 仅列出 `refs/heads/` 下的本地分支；NUL 分隔避免依赖面向人的展示格式或空白切分。
+     * Lists local branches under `refs/heads/` only; NUL delimiting avoids
+     * depending on human-facing formatting or whitespace tokenization.
+     */
+    listBranches(workspaceRoot: string): Promise<readonly string[]>;
+    /**
+     * 使用 porcelain 输出枚举已注册 Worktree；无法映射到本地 branch 的条目不会被丢弃。
+     * Enumerates registered Worktrees through porcelain output; entries that do
+     * not map to a local branch are not discarded.
+     */
+    listWorktrees(workspaceRoot: string): Promise<readonly GitWorktreeInfo[]>;
+    /**
+     * 执行 `git worktree add`；传入 newBranch 时使用 `-b` 从 base branch 创建本地分支。
+     * Executes `git worktree add`; when newBranch is supplied, `-b` creates a local
+     * branch from the selected base branch.
+     */
+    createWorktree(workspaceRoot: string, targetPath: string, branch: string, newBranch?: string): Promise<void>;
+    /**
+     * 仅执行非强制 `git worktree remove <targetPath>`；Git 的安全拒绝会原样升级为显式错误。
+     * Executes non-forced `git worktree remove <targetPath>` only; Git safety
+     * refusals are surfaced as explicit errors.
+     */
+    removeWorktree(workspaceRoot: string, targetPath: string): Promise<void>;
+}
+//# sourceMappingURL=git.d.ts.map

package/lib/provider/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/provider/git.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA8JtE;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,kBAAkB;IACxD;;;;OAIG;IACG,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC9D;;;;OAIG;IACG,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IAerE;;;;OAIG;IACG,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC;IAS/E;;;;OAIG;IACG,cAAc,CAClB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;OAIG;IACG,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO/E"}

package/lib/provider/git.js

@@ -0,0 +1,222 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { providerError } from './types.js';
+const execFile = promisify(execFileCallback);
+// Git 的原始进程证据只在本模块内流转；对外统一转换为稳定的 Provider 错误词汇。
+// Raw Git process evidence stays inside this module and is normalized to the
+// stable Provider error vocabulary at the public boundary.
+class GitCommandError extends Error {
+    args;
+    cwd;
+    stdout;
+    stderr;
+    exitCode;
+    constructor(args, cwd, stdout, stderr, exitCode) {
+        super(stderr || stdout || `git exited with ${String(exitCode)}`);
+        this.name = 'GitCommandError';
+        this.args = args;
+        this.cwd = cwd;
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.exitCode = exitCode;
+    }
+}
+/*
+ * 所有 Git 调用都使用参数数组和固定 executable，不经过 shell；因此路径或分支中的 shell
+ * 元字符不会被解释。参数的业务合法性仍由上层 Manage 校验。
+ *
+ * Every Git call uses an argument vector and a fixed executable without a
+ * shell, so shell metacharacters in paths or branches are never evaluated.
+ * Semantic validation of those values remains the responsibility of Manage.
+ */
+async function runGit(args, cwd) {
+    try {
+        const result = await execFile('git', [...args], {
+            cwd,
+            encoding: 'utf8',
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    catch (error) {
+        const commandError = error;
+        throw new GitCommandError(args, cwd, commandError.stdout ?? '', commandError.stderr ?? '', commandError.code ?? null);
+    }
+}
+// 保留 cwd、参数、stdout、stderr 和退出码，避免稳定错误 code 丢失现场诊断信息。
+// Preserve cwd, arguments, stdout, stderr, and exit code so a stable error code
+// does not discard the evidence needed for diagnosis.
+function gitDetails(error) {
+    return {
+        workspaceRoot: error.cwd,
+        gitArgs: error.args,
+        gitStdout: error.stdout,
+        gitStderr: error.stderr,
+        gitExitCode: typeof error.exitCode === 'number' ? error.exitCode : String(error.exitCode),
+    };
+}
+/*
+ * 普通 Git 子命令失败统一归一化为 `GIT_OPERATION_FAILED`；仓库无效和缺少首个 commit
+ * 则由 `validateRepository` 使用更具体、可操作的错误 code。
+ *
+ * Ordinary Git subcommand failures normalize to `GIT_OPERATION_FAILED`;
+ * `validateRepository` reserves more actionable codes for an invalid
+ * repository and a missing initial commit.
+ */
+function operationError(operation, workspaceRoot, targetPath, branch, error) {
+    if (!(error instanceof GitCommandError)) {
+        return providerError('GIT_OPERATION_FAILED', `Git ${operation} failed: ${String(error)}`, {
+            workspaceRoot,
+            ...(targetPath ? { targetPath } : {}),
+            ...(branch ? { branch } : {}),
+        });
+    }
+    const message = error.stderr.trim() || error.stdout.trim() || error.message;
+    return providerError('GIT_OPERATION_FAILED', `Git ${operation} failed for ${workspaceRoot}${targetPath ? ` -> ${targetPath}` : ''}: ${message}`, {
+        ...gitDetails(error),
+        ...(targetPath ? { targetPath } : {}),
+        ...(branch ? { branch } : {}),
+        operation,
+    });
+}
+/*
+ * 只解析 Git 保证稳定的 porcelain 字段。没有 `branch refs/heads/` 的条目仍被保留，
+ * 其 branch 为 undefined，以正确表示 detached HEAD 等状态。
+ *
+ * Parse only Git's stable porcelain fields. Entries without
+ * `branch refs/heads/` are retained with an undefined branch so states such as
+ * detached HEAD remain visible.
+ */
+function parseWorktrees(output) {
+    const worktrees = [];
+    let current = {};
+    const flush = () => {
+        if (current.absolutePath) {
+            worktrees.push({
+                absolutePath: current.absolutePath,
+                ...(current.branch ? { branch: current.branch } : {}),
+            });
+        }
+        current = {};
+    };
+    for (const line of output.split('\n')) {
+        if (line.length === 0) {
+            flush();
+            continue;
+        }
+        if (line.startsWith('worktree ')) {
+            flush();
+            current.absolutePath = line.slice('worktree '.length);
+            continue;
+        }
+        if (line.startsWith('branch refs/heads/')) {
+            current.branch = line.slice('branch refs/heads/'.length);
+        }
+    }
+    flush();
+    return worktrees;
+}
+/**
+ * 本地 Git worktree adapter：所有命令都以 DSH Workspace 根目录为 cwd，并仅使用固定的
+ * 本地子命令；不使用 `--force`，也不访问 remote。
+ *
+ * Local Git worktree adapter: every command runs with the DSH Workspace root as
+ * cwd and uses a fixed local-only subcommand; it never uses `--force` or accesses
+ * remotes.
+ */
+export class LocalGitAdapter {
+    /**
+     * 分开验证“位于非 bare working tree”和“已有可解析的首个 commit”，以返回不同修复语义。
+     * Separately verifies “inside a non-bare working tree” and “has a resolvable
+     * initial commit” so callers receive distinct repair semantics.
+     */
+    async validateRepository(workspaceRoot) {
+        let result;
+        try {
+            result = await runGit(['rev-parse', '--is-inside-work-tree'], workspaceRoot);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError) {
+                throw providerError('WORKSPACE_NOT_GIT_REPOSITORY', `Workspace is not a Git repository: ${workspaceRoot}`, {
+                    ...gitDetails(error),
+                });
+            }
+            throw error;
+        }
+        if (result.stdout.trim() !== 'true') {
+            throw providerError('WORKSPACE_NOT_GIT_REPOSITORY', `Workspace is not a Git work tree: ${workspaceRoot}`, {
+                workspaceRoot,
+            });
+        }
+        try {
+            await runGit(['rev-parse', '--verify', 'HEAD^{commit}'], workspaceRoot);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError) {
+                throw providerError('WORKTREE_REQUIRES_INITIAL_COMMIT', `Workspace has no initial commit: ${workspaceRoot}`, { ...gitDetails(error) });
+            }
+            throw error;
+        }
+    }
+    /**
+     * 仅列出 `refs/heads/` 下的本地分支；NUL 分隔避免依赖面向人的展示格式或空白切分。
+     * Lists local branches under `refs/heads/` only; NUL delimiting avoids
+     * depending on human-facing formatting or whitespace tokenization.
+     */
+    async listBranches(workspaceRoot) {
+        try {
+            const result = await runGit(['for-each-ref', '--format=%(refname:short)%00', 'refs/heads/'], workspaceRoot);
+            return result.stdout
+                .split('\0')
+                .map((branch) => branch.replace(/^\r?\n/, '').replace(/\r?\n$/, ''))
+                .filter((branch) => branch.length > 0);
+        }
+        catch (error) {
+            throw operationError('list branches', workspaceRoot, undefined, undefined, error);
+        }
+    }
+    /**
+     * 使用 porcelain 输出枚举已注册 Worktree；无法映射到本地 branch 的条目不会被丢弃。
+     * Enumerates registered Worktrees through porcelain output; entries that do
+     * not map to a local branch are not discarded.
+     */
+    async listWorktrees(workspaceRoot) {
+        try {
+            const result = await runGit(['worktree', 'list', '--porcelain'], workspaceRoot);
+            return parseWorktrees(result.stdout);
+        }
+        catch (error) {
+            throw operationError('list worktrees', workspaceRoot, undefined, undefined, error);
+        }
+    }
+    /**
+     * 执行 `git worktree add`；传入 newBranch 时使用 `-b` 从 base branch 创建本地分支。
+     * Executes `git worktree add`; when newBranch is supplied, `-b` creates a local
+     * branch from the selected base branch.
+     */
+    async createWorktree(workspaceRoot, targetPath, branch, newBranch) {
+        try {
+            const args = newBranch
+                ? ['worktree', 'add', '-b', newBranch, targetPath, branch]
+                : ['worktree', 'add', targetPath, branch];
+            await runGit(args, workspaceRoot);
+        }
+        catch (error) {
+            throw operationError('create worktree', workspaceRoot, targetPath, newBranch ?? branch, error);
+        }
+    }
+    /**
+     * 仅执行非强制 `git worktree remove <targetPath>`；Git 的安全拒绝会原样升级为显式错误。
+     * Executes non-forced `git worktree remove <targetPath>` only; Git safety
+     * refusals are surfaced as explicit errors.
+     */
+    async removeWorktree(workspaceRoot, targetPath) {
+        try {
+            await runGit(['worktree', 'remove', targetPath], workspaceRoot);
+        }
+        catch (error) {
+            throw operationError('remove worktree', workspaceRoot, targetPath, undefined, error);
+        }
+    }
+}
+//# sourceMappingURL=git.js.map

package/lib/provider/git.js.map

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

package/lib/provider/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider 层公共入口：仅暴露底层 Git、sidecar、DSH 只读端口及统一错误词汇；
+ * Worktree/Session 生命周期编排和业务冲突判断仍属于 Manage 层。
+ *
+ * Provider public surface: only low-level Git, sidecar, read-only DSH ports, and
+ * the shared error vocabulary are exported here; Worktree/Session lifecycle
+ * orchestration and policy conflicts remain the responsibility of Manage.
+ */
+export { LocalGitAdapter } from './git.js';
+export { WorkspaceShardedSidecarRepository, validateSidecarSnapshot, } from './sidecar.js';
+export { SIDECAR_SCHEMA_VERSION, WorktreeProviderError, isWorktreeProviderError, providerError, } from './types.js';
+export type { DshReadAdapter, DshSessionSummary, DshWorkspaceSummary, GitWorktreeAdapter, GitWorktreeInfo, SidecarMutation, SidecarSnapshot, SidecarStore, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/provider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EACL,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC"}

package/lib/provider/index.js

@@ -0,0 +1,12 @@
+/**
+ * Provider 层公共入口：仅暴露底层 Git、sidecar、DSH 只读端口及统一错误词汇；
+ * Worktree/Session 生命周期编排和业务冲突判断仍属于 Manage 层。
+ *
+ * Provider public surface: only low-level Git, sidecar, read-only DSH ports, and
+ * the shared error vocabulary are exported here; Worktree/Session lifecycle
+ * orchestration and policy conflicts remain the responsibility of Manage.
+ */
+export { LocalGitAdapter } from './git.js';
+export { WorkspaceShardedSidecarRepository, validateSidecarSnapshot, } from './sidecar.js';
+export { SIDECAR_SCHEMA_VERSION, WorktreeProviderError, isWorktreeProviderError, providerError, } from './types.js';
+//# sourceMappingURL=index.js.map

package/lib/provider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EACL,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/lib/provider/sidecar.d.ts

@@ -0,0 +1,85 @@
+import type { SessionBinding, WorktreeRecord } from '../contract/index.js';
+import { type SidecarMutation, type SidecarSnapshot, type SidecarStore } from './types.js';
+/**
+ * 校验完整 sidecar 快照及跨记录不变量：shard Workspace 身份一致、Worktree ID 唯一、
+ * 每个 Session 至多一个 active binding，且 active binding 必须指向 active Worktree。
+ *
+ * Validates a complete sidecar snapshot and its cross-record invariants: one
+ * Workspace identity per shard, unique Worktree IDs, at most one active binding
+ * per Session, and every active binding targeting an active Worktree.
+ *
+ * 提供 `generatedWorktreeRoot` 时，还要求 Provider 生成的 ID 合法且路径精确等于
+ * `<generatedWorktreeRoot>/<worktreeId>`。detached binding 可继续指向 removed 记录，
+ * 以保留删除后的关系历史。
+ *
+ * When `generatedWorktreeRoot` is supplied, Provider-generated IDs must be
+ * valid and paths must equal `<generatedWorktreeRoot>/<worktreeId>` exactly.
+ * Detached bindings may continue to reference removed records so relationships
+ * survive Worktree removal.
+ */
+export declare function validateSidecarSnapshot(value: unknown, pathname: string, generatedWorktreeRoot?: string): SidecarSnapshot;
+/**
+ * 位于 DSH Home 下、按 Workspace 分 shard 的 sidecar repository；它只持久化外部
+ * Worktree/Session 关系，不读取或写入 DSH 原始数据及 Workspace 业务文件。
+ *
+ * Workspace-sharded sidecar repository under DSH Home; it persists only the
+ * external Worktree/Session relationship and never reads or writes DSH-owned
+ * data or Workspace business files.
+ *
+ * 同一实例内的 mutation 按 Workspace 串行化，并通过同目录临时文件加 rename 提供完整旧版或
+ * 完整新版的原子可见性；这不等同于跨进程锁，也不承诺 fsync 级崩溃持久性。
+ *
+ * Mutations are serialized per Workspace within one instance, and a temporary
+ * file plus same-directory rename provides complete-old-or-complete-new atomic
+ * visibility. This is neither a cross-process lock nor an fsync-level crash
+ * durability guarantee.
+ */
+export declare class WorkspaceShardedSidecarRepository implements SidecarStore {
+    readonly pluginRoot: string;
+    readonly worktreeRoot: string;
+    readonly workspaceRoot: string;
+    private readonly dshHome;
+    private readonly mutex;
+    constructor({ dshHome }: {
+        readonly dshHome: string;
+    });
+    /**
+     * 将 Workspace ID 编码为单个稳定文件名，所有 shard 都限定在 Provider 自有目录中。
+     * Encodes a Workspace ID into one stable filename, keeping every shard under
+     * the Provider-owned directory.
+     */
+    getShardPath(workspaceId: string): string;
+    /**
+     * 读取并完整校验 shard；文件不存在表示尚无关系并返回空快照，损坏内容绝不自动修复。
+     * Reads and fully validates a shard; a missing file means no relationships yet
+     * and returns an empty snapshot, while corrupt content is never auto-repaired.
+     */
+    read(workspaceId: string): Promise<SidecarSnapshot>;
+    /**
+     * 在 Workspace 互斥区内重新读取最新快照、应用转换、复验全部不变量，再决定是否原子写入。
+     * Re-reads the latest snapshot inside the Workspace mutex, applies the
+     * transition, revalidates every invariant, and only then decides whether to
+     * write atomically.
+     *
+     * mutation 抛错、返回非法快照或改变 Workspace 身份时，已有 shard 不会被本方法替换。
+     * If the mutation throws, returns an invalid snapshot, or changes Workspace
+     * identity, this method does not replace the existing shard.
+     */
+    mutate<T>(workspaceId: string, mutation: (snapshot: SidecarSnapshot) => SidecarMutation<T> | Promise<SidecarMutation<T>>): Promise<T>;
+    /**
+     * 按 Worktree ID 幂等插入；完全相同的记录直接复用，同一 ID 的不同 metadata 被视为损坏。
+     * Idempotently inserts by Worktree ID; an identical record is reused, while
+     * different metadata under the same ID is treated as corruption.
+     */
+    upsertWorktree(record: WorktreeRecord): Promise<WorktreeRecord>;
+    /**
+     * 按 Session ID 幂等插入 binding；完全相同的关系直接复用，任何既有不同关系都返回冲突。
+     * Idempotently inserts a binding by Session ID; an identical relationship is
+     * reused, while any different existing relationship returns a conflict.
+     */
+    upsertBinding(binding: SessionBinding): Promise<SessionBinding>;
+    private readFromDisk;
+    private writeToDisk;
+    private assertStorageBoundary;
+}
+//# sourceMappingURL=sidecar.d.ts.map

package/lib/provider/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../src/provider/sidecar.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EAGlB,MAAM,YAAY,CAAC;AAyDpB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,qBAAqB,CAAC,EAAE,MAAM,GAC7B,eAAe,CAqEjB;AA4DD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iCAAkC,YAAW,YAAY;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAE9B,EAAE,OAAO,EAAE,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAUrD;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIzC;;;;OAIG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIzD;;;;;;;;;OASG;IACG,MAAM,CAAC,CAAC,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GACxF,OAAO,CAAC,CAAC,CAAC;IAab;;;;OAIG;IACG,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAsBrE;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;YAmBvD,YAAY;YAiCZ,WAAW;YA8CX,qBAAqB;CAuBpC"}