@lumenflow/core 3.2.0 → 3.2.2

package/dist/branch-check.js

@@ -0,0 +1,197 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Branch-aware bypass detection for cloud/automation agents.
+ *
+ * Provides functions to check if a branch is an agent branch that can
+ * bypass worktree requirements, and if headless mode is allowed.
+ *
+ * WU-1089: Updated to use resolveAgentPatterns with merge/override/airgapped support.
+ *
+ * @module branch-check
+ */
+import micromatch from 'micromatch';
+import { getConfig } from './lumenflow-config.js';
+import { resolveAgentPatterns, DEFAULT_AGENT_PATTERNS, } from './agent-patterns-registry.js';
+/** Legacy protected branch (always protected regardless of mainBranch setting) */
+const LEGACY_PROTECTED = 'master';
+/**
+ * Get lane branch pattern from config (or default).
+ * Lane branches always require worktrees - never bypassed.
+ */
+function getLaneBranchPattern() {
+    const config = getConfig();
+    const prefix = config?.git?.laneBranchPrefix ?? 'lane/';
+    // Escape regex special chars in prefix, then anchor to start
+    const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // eslint-disable-next-line security/detect-non-literal-regexp -- prefix from config file, not user input; escaped for safety
+    return new RegExp(`^${escaped}`);
+}
+/**
+ * Get protected branches derived from config.
+ * Returns [mainBranch, 'master'] to avoid config duplication.
+ */
+function getProtectedBranches() {
+    const config = getConfig();
+    const mainBranch = config?.git?.mainBranch ?? 'main';
+    // Deduplicate in case mainBranch is 'master'
+    const protectedSet = new Set([mainBranch, LEGACY_PROTECTED]);
+    return Array.from(protectedSet);
+}
+/**
+ * Check if branch is an agent branch that can bypass worktree requirements.
+ *
+ * WU-1089: Now uses resolveAgentPatterns with proper merge/override/airgapped support:
+ * - Default: Fetches from registry (lumenflow.dev) with 7-day cache
+ * - Config patterns merge with registry patterns (config first)
+ * - Override patterns (agentBranchPatternsOverride) replace everything
+ * - Airgapped mode (disableAgentPatternRegistry) skips network fetch
+ *
+ * @param branch - Branch name to check
+ * @returns Promise<true> if branch matches agent patterns
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export async function isAgentBranch(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch)
+        return false;
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD')
+        return false;
+    // Load config (uses existing loader with caching)
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed (mainBranch + 'master')
+    if (protectedBranches.includes(branch))
+        return false;
+    // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
+    if (getLaneBranchPattern().test(branch))
+        return false;
+    // WU-1089: Use resolveAgentPatterns with full merge/override/airgapped support
+    const result = await resolveAgentPatterns({
+        configPatterns: config?.git?.agentBranchPatterns,
+        overridePatterns: config?.git?.agentBranchPatternsOverride,
+        disableAgentPatternRegistry: config?.git?.disableAgentPatternRegistry,
+    });
+    // Use micromatch for proper glob matching
+    return micromatch.isMatch(branch, result.patterns);
+}
+/**
+ * Check if branch is an agent branch with full result details.
+ *
+ * Same as isAgentBranch but returns the full AgentPatternResult
+ * for observability and debugging.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise with match result and pattern resolution details
+ *
+ * @example
+ * ```typescript
+ * const result = await isAgentBranchWithDetails('claude/session-123');
+ * if (result.isMatch) {
+ *   console.log(`Matched via ${result.patternResult.source}`);
+ *   console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+ * }
+ * ```
+ */
+export async function isAgentBranchWithDetails(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch) {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD') {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // Load config
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed
+    if (protectedBranches.includes(branch)) {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // Lane branches require worktrees
+    if (getLaneBranchPattern().test(branch)) {
+        return {
+            isMatch: false,
+            patternResult: { patterns: [], source: 'defaults', registryFetched: false },
+        };
+    }
+    // Resolve patterns with full details
+    const patternResult = await resolveAgentPatterns({
+        configPatterns: config?.git?.agentBranchPatterns,
+        overridePatterns: config?.git?.agentBranchPatternsOverride,
+        disableAgentPatternRegistry: config?.git?.disableAgentPatternRegistry,
+    });
+    const isMatch = micromatch.isMatch(branch, patternResult.patterns);
+    return { isMatch, patternResult };
+}
+/**
+ * Synchronous version of isAgentBranch for backwards compatibility.
+ *
+ * Uses only local config patterns or defaults - does NOT fetch from registry.
+ * Prefer async isAgentBranch() when possible.
+ *
+ * WU-1089: Updated to respect override and disable flags, but cannot fetch from registry.
+ *
+ * @param branch - Branch name to check
+ * @returns True if branch matches agent patterns
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
+ */
+export function isAgentBranchSync(branch) {
+    // Fail-closed: no branch = protected
+    if (!branch)
+        return false;
+    // Detached HEAD = protected (fail-closed)
+    if (branch === 'HEAD')
+        return false;
+    // Load config (uses existing loader with caching)
+    const config = getConfig();
+    const protectedBranches = getProtectedBranches();
+    // Protected branches are NEVER bypassed (mainBranch + 'master')
+    if (protectedBranches.includes(branch))
+        return false;
+    // LumenFlow lane branches require worktrees (uses config's laneBranchPrefix)
+    if (getLaneBranchPattern().test(branch))
+        return false;
+    // WU-1089: Check override first
+    if (config?.git?.agentBranchPatternsOverride?.length) {
+        return micromatch.isMatch(branch, config.git.agentBranchPatternsOverride);
+    }
+    // Use config patterns if provided, otherwise defaults
+    // Note: sync version cannot fetch from registry
+    const patterns = config?.git?.agentBranchPatterns?.length > 0
+        ? config.git.agentBranchPatterns
+        : DEFAULT_AGENT_PATTERNS;
+    // Use micromatch for proper glob matching
+    return micromatch.isMatch(branch, patterns);
+}
+/**
+ * Check if headless mode is allowed (guarded).
+ * Requires LUMENFLOW_HEADLESS=1 AND (LUMENFLOW_ADMIN=1 OR CI truthy OR GITHUB_ACTIONS truthy)
+ */
+export function isHeadlessAllowed() {
+    if (process.env.LUMENFLOW_HEADLESS !== '1')
+        return false;
+    return (process.env.LUMENFLOW_ADMIN === '1' ||
+        Boolean(process.env.CI) || // Any truthy CI value (true, 1, yes, etc.)
+        Boolean(process.env.GITHUB_ACTIONS) // Any truthy value
+    );
+}
+//# sourceMappingURL=branch-check.js.map

package/dist/branch-check.js.map

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

package/dist/branch-drift.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Drift level constants
+ * Used as return values from getDriftLevel()
+ */
+export declare const DRIFT_LEVELS: {
+    OK: string;
+    INFO: string;
+    WARNING: string;
+    ERROR: string;
+};
+/**
+ * Calculate drift level based on number of commits behind main
+ *
+ * @param {number} commitsBehind - Number of commits behind main (from git rev-list --count)
+ * @returns {'ok' | 'info' | 'warning' | 'error'} Drift severity level
+ *
+ * @example
+ * getDriftLevel(5)   // 'ok' - no warning needed
+ * getDriftLevel(10)  // 'info' - suggest rebasing
+ * getDriftLevel(15)  // 'warning' - recommend rebasing
+ * getDriftLevel(20)  // 'error' - hard block, must rebase
+ */
+export declare function getDriftLevel(commitsBehind: UnsafeAny): string;
+//# sourceMappingURL=branch-drift.d.ts.map

package/dist/branch-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-drift.d.ts","sourceRoot":"","sources":["../src/branch-drift.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;CAKxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,SAAS,UAqBrD"}

package/dist/branch-drift.js

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Branch drift detection and graduated warning system
+ *
+ * WU-1370: Graduated warnings for branch drift
+ * - < 10 commits behind: OK (no message)
+ * - 10-14 commits behind: INFO ("Consider rebasing")
+ * - 15-19 commits behind: WARNING ("Rebase recommended")
+ * - >= 20 commits behind: ERROR (hard block, "Must rebase")
+ *
+ * @see {@link THRESHOLDS} for configurable threshold values
+ */
+import { THRESHOLDS } from './wu-constants.js';
+/**
+ * Drift level constants
+ * Used as return values from getDriftLevel()
+ */
+export const DRIFT_LEVELS = {
+    OK: 'ok',
+    INFO: 'info',
+    WARNING: 'warning',
+    ERROR: 'error',
+};
+/**
+ * Calculate drift level based on number of commits behind main
+ *
+ * @param {number} commitsBehind - Number of commits behind main (from git rev-list --count)
+ * @returns {'ok' | 'info' | 'warning' | 'error'} Drift severity level
+ *
+ * @example
+ * getDriftLevel(5)   // 'ok' - no warning needed
+ * getDriftLevel(10)  // 'info' - suggest rebasing
+ * getDriftLevel(15)  // 'warning' - recommend rebasing
+ * getDriftLevel(20)  // 'error' - hard block, must rebase
+ */
+export function getDriftLevel(commitsBehind) {
+    // Handle edge cases: negative or non-integer values
+    const commits = Math.floor(commitsBehind);
+    if (commits < 0) {
+        return DRIFT_LEVELS.OK;
+    }
+    if (commits >= THRESHOLDS.BRANCH_DRIFT_MAX) {
+        return DRIFT_LEVELS.ERROR;
+    }
+    if (commits >= THRESHOLDS.BRANCH_DRIFT_WARNING) {
+        return DRIFT_LEVELS.WARNING;
+    }
+    if (commits >= THRESHOLDS.BRANCH_DRIFT_INFO) {
+        return DRIFT_LEVELS.INFO;
+    }
+    return DRIFT_LEVELS.OK;
+}
+//# sourceMappingURL=branch-drift.js.map

package/dist/branch-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-drift.js","sourceRoot":"","sources":["../src/branch-drift.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,EAAE,EAAE,IAAI;IACR,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACf,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,aAAwB;IACpD,oDAAoD;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAE1C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,YAAY,CAAC,EAAE,CAAC;IACzB,CAAC;IAED,IAAI,OAAO,IAAI,UAAU,CAAC,gBAAgB,EAAE,CAAC;QAC3C,OAAO,YAAY,CAAC,KAAK,CAAC;IAC5B,CAAC;IAED,IAAI,OAAO,IAAI,UAAU,CAAC,oBAAoB,EAAE,CAAC;QAC/C,OAAO,YAAY,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,IAAI,OAAO,IAAI,UAAU,CAAC,iBAAiB,EAAE,CAAC;QAC5C,OAAO,YAAY,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,OAAO,YAAY,CAAC,EAAE,CAAC;AACzB,CAAC"}

package/dist/cleanup-install-config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Timeout for cleanup install operation (ms)
+ * @constant {number}
+ */
+export declare const CLEANUP_INSTALL_TIMEOUT_MS = 60000;
+/**
+ * Get configuration for cleanup pnpm install
+ *
+ * Returns command and options suitable for execAsync:
+ * - CI=true environment variable for non-interactive mode
+ * - 60 second timeout to prevent hangs
+ * - frozen-lockfile flag to prevent mutations
+ *
+ * @returns {{ command: string, timeout: number, env: object }}
+ */
+export declare function getCleanupInstallConfig(): {
+    command: string;
+    timeout: number;
+    env: {
+        CI: string;
+        TZ?: string | undefined;
+    };
+};
+//# sourceMappingURL=cleanup-install-config.d.ts.map

package/dist/cleanup-install-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-install-config.d.ts","sourceRoot":"","sources":["../src/cleanup-install-config.ts"],"names":[],"mappings":"AAgBA;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB;;;;;;;EAWtC"}

package/dist/cleanup-install-config.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU-2278: Cleanup Install Configuration
+ *
+ * Provides configuration for pnpm install during wu:done cleanup.
+ * - 60 second timeout to prevent indefinite hangs
+ * - CI=true for non-interactive mode
+ * - frozen-lockfile to prevent lockfile mutations
+ *
+ * @module cleanup-install-config
+ */
+import { PKG_MANAGER, PKG_COMMANDS, PKG_FLAGS } from './wu-constants.js';
+/**
+ * Timeout for cleanup install operation (ms)
+ * @constant {number}
+ */
+export const CLEANUP_INSTALL_TIMEOUT_MS = 60000; // 60 seconds
+/**
+ * Get configuration for cleanup pnpm install
+ *
+ * Returns command and options suitable for execAsync:
+ * - CI=true environment variable for non-interactive mode
+ * - 60 second timeout to prevent hangs
+ * - frozen-lockfile flag to prevent mutations
+ *
+ * @returns {{ command: string, timeout: number, env: object }}
+ */
+export function getCleanupInstallConfig() {
+    const command = `${PKG_MANAGER} ${PKG_COMMANDS.INSTALL} ${PKG_FLAGS.FROZEN_LOCKFILE}`;
+    return {
+        command,
+        timeout: CLEANUP_INSTALL_TIMEOUT_MS,
+        env: {
+            ...process.env,
+            CI: 'true', // Non-interactive mode
+        },
+    };
+}
+//# sourceMappingURL=cleanup-install-config.js.map

package/dist/cleanup-install-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-install-config.js","sourceRoot":"","sources":["../src/cleanup-install-config.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC,CAAC,aAAa;AAE9D;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,OAAO,GAAG,GAAG,WAAW,IAAI,YAAY,CAAC,OAAO,IAAI,SAAS,CAAC,eAAe,EAAE,CAAC;IAEtF,OAAO;QACL,OAAO;QACP,OAAO,EAAE,0BAA0B;QACnC,GAAG,EAAE;YACH,GAAG,OAAO,CAAC,GAAG;YACd,EAAE,EAAE,MAAM,EAAE,uBAAuB;SACpC;KACF,CAAC;AACJ,CAAC"}

package/dist/cleanup-lock.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Default timeout for waiting to acquire lock (ms)
+ * After this time, acquisition fails if lock is held
+ */
+export declare const CLEANUP_LOCK_TIMEOUT_MS = 30000;
+/**
+ * Time after which a cleanup lock is considered stale (ms)
+ * Should be greater than expected cleanup operation duration
+ * Cleanup is slower than merge, so longer timeout
+ */
+export declare const CLEANUP_LOCK_STALE_MS: number;
+/**
+ * @typedef {Object} CleanupLockInfo
+ * @property {string} wuId - WU ID that holds the lock
+ * @property {string} lockId - Unique lock identifier
+ * @property {string} createdAt - ISO timestamp when lock was created
+ * @property {number} pid - Process ID of lock holder
+ * @property {string} hostname - Hostname of lock holder
+ * @property {string} [worktreePath] - Path to worktree being cleaned up
+ */
+/**
+ * @typedef {Object} CleanupAcquireResult
+ * @property {boolean} acquired - Whether lock was acquired
+ * @property {string} [lockId] - Lock ID if acquired
+ * @property {string} [heldBy] - WU ID holding the lock if not acquired
+ * @property {string} [heldSince] - ISO timestamp if not acquired
+ */
+/**
+ * Options for lock file operations
+ */
+interface BaseDirOptions {
+    /**
+     * Base directory override (for testing only)
+     *
+     * WU-1174: In production, locks are always stored in LUMENFLOW_PATHS.LOCK_DIR
+     * (a temp directory). This option allows tests to use isolated directories.
+     */
+    baseDir?: string;
+}
+/**
+ * Check if a lock is stale (older than CLEANUP_LOCK_STALE_MS)
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is stale
+ */
+export declare function isCleanupLockStale(lockInfo: UnsafeAny): boolean;
+/**
+ * Check if a lock is a zombie (PID not running)
+ *
+ * @param {CleanupLockInfo} lockInfo - Lock info to check
+ * @returns {boolean} True if lock is a zombie (PID not running)
+ */
+export declare function isCleanupLockZombie(lockInfo: UnsafeAny): boolean;
+/**
+ * Check if cleanup lock is currently held
+ *
+ * @param {BaseDirOptions} [options]
+ * @returns {boolean} True if lock is held (and not stale)
+ */
+export declare function isCleanupLocked(options?: BaseDirOptions): boolean;
+/**
+ * Get information about current cleanup lock
+ *
+ * @param {BaseDirOptions} [options]
+ * @returns {CleanupLockInfo|null} Lock info or null if unlocked
+ */
+export declare function getCleanupLockInfo(options?: BaseDirOptions): any;
+/**
+ * Options for acquiring cleanup lock
+ */
+export interface AcquireCleanupLockOptions extends BaseDirOptions {
+    /** Max time to wait for lock (default: CLEANUP_LOCK_TIMEOUT_MS) */
+    waitMs?: number;
+    /** Path to worktree being cleaned up */
+    worktreePath?: string | null;
+}
+/**
+ * Attempt to acquire the cleanup lock
+ *
+ * Will wait up to waitMs for lock to become available.
+ * If the same WU already holds the lock, re-acquisition succeeds (idempotent).
+ * Stale and zombie locks are automatically cleaned up.
+ *
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {AcquireCleanupLockOptions} [options]
+ * @returns {Promise<CleanupAcquireResult>} Acquisition result
+ */
+export declare function acquireCleanupLock(wuId: UnsafeAny, options?: AcquireCleanupLockOptions): Promise<{
+    acquired: boolean;
+    lockId: any;
+    heldBy?: undefined;
+    heldSince?: undefined;
+} | {
+    acquired: boolean;
+    heldBy: any;
+    heldSince: any;
+    lockId?: undefined;
+}>;
+/**
+ * Release the cleanup lock
+ *
+ * Only releases if the provided lockId matches the current lock.
+ * This prevents accidentally releasing another WU's lock.
+ *
+ * @param {string} lockId - Lock ID to release
+ * @param {BaseDirOptions} [options]
+ * @returns {boolean} True if lock was released
+ */
+export declare function releaseCleanupLock(lockId: UnsafeAny, options?: BaseDirOptions): boolean;
+/**
+ * Execute a function while holding the cleanup lock
+ *
+ * Guarantees the lock is released after function completes,
+ * even if the function throws an error.
+ *
+ * @template T
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {function(): Promise<T>} fn - Async function to execute
+ * @param {AcquireCleanupLockOptions} [options]
+ * @returns {Promise<T>} Result of function execution
+ * @throws {Error} If lock cannot be acquired or function throws
+ */
+export declare function withCleanupLock<T>(wuId: string, fn: () => Promise<T>, options?: AcquireCleanupLockOptions): Promise<T>;
+export {};
+//# sourceMappingURL=cleanup-lock.d.ts.map

package/dist/cleanup-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-lock.d.ts","sourceRoot":"","sources":["../src/cleanup-lock.ts"],"names":[],"mappings":"AA6CA;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAkB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAKtD;;;;;;;;GAQG;AAEH;;;;;;GAMG;AAEH;;GAEG;AACH,UAAU,cAAc;IACtB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAoDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,WAOrD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,WAWtD;AAqBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,cAAmB,WAO3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,cAAmB,OAM9D;AA4DD;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,yBAA8B;;;;;;;;;;GAsDhG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,WAkBjF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,CAAC,CAAC,CAgBZ"}