@lumenflow/core 3.2.0 → 3.2.2

package/dist/dependency-guard.js

@@ -0,0 +1,145 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Dependency Guard (WU-1783)
+ *
+ * Detects dependency-mutating pnpm commands and provides blocking/guidance
+ * for worktree discipline enforcement.
+ *
+ * Used by:
+ * - pre-tool-use-hook.sh to block dependency mutations on main
+ * - deps:add and deps:remove wrapper commands
+ *
+ * @see {@link .claude/hooks/pre-tool-use-hook.sh} - PreToolUse hook
+ * @see {@link packages/@lumenflow/cli/src/deps-add.ts} - Safe wrapper for pnpm add
+ * @see {@link packages/@lumenflow/cli/src/deps-remove.ts} - Safe wrapper for pnpm remove
+ */
+import { EMOJI } from './wu-constants.js';
+/**
+ * pnpm subcommands that mutate dependencies.
+ *
+ * These commands modify package.json, pnpm-lock.yaml, and/or node_modules.
+ * Running them on main checkout violates worktree isolation.
+ *
+ * Includes both full names and shorthand aliases:
+ * - add: Add packages to dependencies
+ * - install/i: Install packages from lockfile
+ * - remove/rm/uninstall: Remove packages from dependencies
+ * - update/up: Update packages to latest
+ */
+export const DEPENDENCY_MUTATING_COMMANDS = [
+    'add',
+    'install',
+    'i', // shorthand for install
+    'remove',
+    'rm', // shorthand for remove
+    'uninstall', // alias for remove
+    'update',
+    'up', // shorthand for update
+];
+/**
+ * Check if a command is a dependency-mutating pnpm command.
+ *
+ * @param {string|null|undefined} command - Command string to check
+ * @returns {boolean} True if the command mutates dependencies
+ *
+ * @example
+ * isDependencyMutatingCommand('pnpm add react'); // true
+ * isDependencyMutatingCommand('pnpm run test'); // false
+ * isDependencyMutatingCommand('npm install'); // false (not pnpm)
+ */
+export function isDependencyMutatingCommand(command) {
+    // Handle null/undefined/empty
+    if (!command) {
+        return false;
+    }
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return false;
+    }
+    // Only check pnpm commands
+    if (!trimmed.startsWith('pnpm ') && trimmed !== 'pnpm') {
+        return false;
+    }
+    // Extract the subcommand (first argument after 'pnpm')
+    // Handle: pnpm add, pnpm --filter web add, etc.
+    const parts = trimmed.split(/\s+/);
+    // Find the first non-flag argument after 'pnpm'
+    for (let i = 1; i < parts.length; i++) {
+        const part = parts[i];
+        // Skip flags (start with -)
+        if (part.startsWith('-')) {
+            // Handle --filter=value format
+            if (part.includes('=')) {
+                continue;
+            }
+            // Handle --filter value format (skip next part too)
+            if (part === '--filter' || part === '-F') {
+                i++; // Skip the filter value
+                continue;
+            }
+            continue;
+        }
+        // This is the subcommand
+        return DEPENDENCY_MUTATING_COMMANDS.includes(part);
+    }
+    return false;
+}
+/**
+ * Build a blocking message for dependency-mutating commands on main.
+ *
+ * @param {string} command - The blocked command
+ * @returns {string} Formatted error message with guidance
+ *
+ * @example
+ * const message = buildDependencyBlockMessage('pnpm add react');
+ * // Returns multi-line message with guidance
+ */
+export function buildDependencyBlockMessage(command) {
+    // Extract the pnpm subcommand for targeted guidance
+    const parts = command.trim().split(/\s+/);
+    let subcommand = '';
+    for (let i = 1; i < parts.length; i++) {
+        if (!parts[i].startsWith('-')) {
+            subcommand = parts[i];
+            break;
+        }
+    }
+    const wrapperCommand = subcommand === 'add' || subcommand === 'i' || subcommand === 'install'
+        ? 'pnpm deps:add'
+        : subcommand === 'remove' || subcommand === 'rm' || subcommand === 'uninstall'
+            ? 'pnpm deps:remove'
+            : 'the corresponding deps:* wrapper';
+    return `
+${EMOJI.BLOCKED} BLOCKED: Dependency mutation on main checkout
+
+Command: ${command}
+
+REASON: Running ${subcommand || 'dependency'} commands on main bypasses worktree isolation.
+This can cause:
+  - Dirty lockfile diffs that block other agents
+  - pnpm virtual-store mismatches
+  - Wedged wu:done workflows
+
+TO FIX:
+  1. Claim a WU first (if not already claimed):
+     pnpm wu:claim --id WU-XXXX --lane "Your Lane"
+
+  2. Navigate to the worktree:
+     cd worktrees/<lane>-wu-<id>/
+
+  3. Run your command there, or use the safe wrapper:
+     ${wrapperCommand}
+
+The safe wrapper (${wrapperCommand}) enforces worktree context
+and runs the underlying pnpm command with proper isolation.
+
+See: CLAUDE.md section 2 'Daily Operating Loop'
+See: https://lumenflow.dev/reference/lumenflow-complete/
+`;
+}
+/**
+ * Log prefix for dependency guard output
+ */
+export const DEPS_LOG_PREFIX = '[deps-guard]';
+//# sourceMappingURL=dependency-guard.js.map

package/dist/dependency-guard.js.map

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

package/dist/dependency-validator.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Map of tools to their required npm packages.
+ *
+ * Each tool lists the packages it needs to function correctly.
+ * These are checked before tool execution to prevent silent failures.
+ *
+ * @type {Record<string, string[]>}
+ */
+export declare const TOOL_DEPENDENCIES: Readonly<{
+    'wu:spawn': string[];
+    'wu:claim': string[];
+    'wu:done': string[];
+    'wu:block': string[];
+    'wu:unblock': string[];
+    'mem:inbox': string[];
+    'mem:signal': string[];
+    'mem:ready': string[];
+    'mem:checkpoint': string[];
+}>;
+/**
+ * Validate that required dependencies are available.
+ *
+ * @param {string[]} packages - List of package names to check
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ *
+ * @example
+ * const result = await validateDependencies(['yaml', 'ms']);
+ * if (!result.valid) {
+ *   console.error(`Missing: ${result.missing.join(', ')}`);
+ * }
+ */
+export declare function validateDependencies(packages: UnsafeAny): Promise<{
+    valid: boolean;
+    missing: any;
+}>;
+/**
+ * Format an error message for missing dependencies.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn')
+ * @param {string[]} missing - List of missing package names
+ * @returns {string} Formatted error message with fix instructions
+ *
+ * @example
+ * const msg = formatDependencyError('wu:spawn', ['yaml']);
+ * console.error(msg);
+ */
+export declare function formatDependencyError(toolName: UnsafeAny, missing: UnsafeAny): string;
+/**
+ * Validate dependencies for wu:spawn.
+ *
+ * Convenience function that validates wu:spawn's required packages.
+ * Called before lane lock check to prevent false positives.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export declare function validateSpawnDependencies(): Promise<{
+    valid: boolean;
+    missing: any;
+}>;
+/**
+ * Validate dependencies for mem:inbox.
+ *
+ * Convenience function that validates mem:inbox's required packages.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export declare function validateInboxDependencies(): Promise<{
+    valid: boolean;
+    missing: any;
+}>;
+/**
+ * Validate dependencies for a specific tool.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn', 'mem:inbox')
+ * @returns {Promise<{valid: boolean, missing: string[], toolName: string}>} Validation result
+ *
+ * @example
+ * const result = await validateToolDependencies('wu:spawn');
+ * if (!result.valid) {
+ *   console.error(formatDependencyError(result.toolName, result.missing));
+ *   process.exit(1);
+ * }
+ */
+export declare function validateToolDependencies(toolName: string): Promise<{
+    toolName: string;
+    valid: boolean;
+    missing: any;
+}>;
+//# sourceMappingURL=dependency-validator.d.ts.map

package/dist/dependency-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-validator.d.ts","sourceRoot":"","sources":["../src/dependency-validator.ts"],"names":[],"mappings":"AAuBA;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;EAU5B,CAAC;AAoBH;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,SAAS;;;GAe7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,UAkB5E;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB;;;GAE9C;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB;;;GAE9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM;;;;GAQ9D"}

package/dist/dependency-validator.js

@@ -0,0 +1,155 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Dependency Validator (WU-2202)
+ *
+ * Validates that required dependencies are available before tool execution.
+ * Prevents silent failures when node_modules is corrupted or incomplete.
+ *
+ * Background: During INIT-038 orchestration, wu:spawn incorrectly reported
+ * lanes as occupied when the yaml package was missing from node_modules.
+ * The tool read lock files but failed silently and reported wrong data.
+ *
+ * This module provides:
+ * - validateDependencies(): Check if packages can be imported
+ * - formatDependencyError(): Generate clear error messages
+ * - TOOL_DEPENDENCIES: Map of tools to their required packages
+ *
+ * @see WU-2202 - Fix false lane occupancy when deps broken
+ */
+import { EMOJI, LOG_PREFIX } from './wu-constants.js';
+/**
+ * Map of tools to their required npm packages.
+ *
+ * Each tool lists the packages it needs to function correctly.
+ * These are checked before tool execution to prevent silent failures.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const TOOL_DEPENDENCIES = Object.freeze({
+    'wu:spawn': ['yaml', 'minimatch', 'commander'],
+    'wu:claim': ['yaml', 'commander'],
+    'wu:done': ['yaml', 'commander'],
+    'wu:block': ['yaml', 'commander'],
+    'wu:unblock': ['yaml', 'commander'],
+    'mem:inbox': ['ms', 'commander'],
+    'mem:signal': ['commander'],
+    'mem:ready': ['commander'],
+    'mem:checkpoint': ['commander'],
+});
+/**
+ * Check if a package can be imported.
+ *
+ * Uses dynamic import to test package availability.
+ * Returns false if the package cannot be loaded.
+ *
+ * @param {string} packageName - Name of the package to check
+ * @returns {Promise<boolean>} True if package is available
+ */
+async function canImport(packageName) {
+    try {
+        await import(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate that required dependencies are available.
+ *
+ * @param {string[]} packages - List of package names to check
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ *
+ * @example
+ * const result = await validateDependencies(['yaml', 'ms']);
+ * if (!result.valid) {
+ *   console.error(`Missing: ${result.missing.join(', ')}`);
+ * }
+ */
+export async function validateDependencies(packages) {
+    if (!packages || packages.length === 0) {
+        return { valid: true, missing: [] };
+    }
+    // WU-1231: Validate packages in parallel using Promise.all
+    // Previously sequential (for...of await) caused 5+ minute delays
+    const results = await Promise.all(packages.map((pkg) => canImport(pkg)));
+    const missing = packages.filter((_, index) => !results[index]);
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+/**
+ * Format an error message for missing dependencies.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn')
+ * @param {string[]} missing - List of missing package names
+ * @returns {string} Formatted error message with fix instructions
+ *
+ * @example
+ * const msg = formatDependencyError('wu:spawn', ['yaml']);
+ * console.error(msg);
+ */
+export function formatDependencyError(toolName, missing) {
+    const packageList = missing.map((p) => `  - ${p}`).join('\n');
+    return `${EMOJI.FAILURE} ${toolName} cannot run: missing dependencies
+
+The following packages are required but not available:
+${packageList}
+
+This usually means node_modules is corrupted or incomplete.
+
+TO FIX:
+  1. Run: pnpm install
+  2. If that fails, try: rm -rf node_modules && pnpm install
+
+If the issue persists, check that the packages are listed in package.json
+and that there are no pnpm virtual-store errors.
+
+${LOG_PREFIX} Missing packages: ${missing.join(', ')}`;
+}
+/**
+ * Validate dependencies for wu:spawn.
+ *
+ * Convenience function that validates wu:spawn's required packages.
+ * Called before lane lock check to prevent false positives.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export async function validateSpawnDependencies() {
+    return validateDependencies(TOOL_DEPENDENCIES['wu:spawn']);
+}
+/**
+ * Validate dependencies for mem:inbox.
+ *
+ * Convenience function that validates mem:inbox's required packages.
+ *
+ * @returns {Promise<{valid: boolean, missing: string[]}>} Validation result
+ */
+export async function validateInboxDependencies() {
+    return validateDependencies(TOOL_DEPENDENCIES['mem:inbox']);
+}
+/**
+ * Validate dependencies for a specific tool.
+ *
+ * @param {string} toolName - Name of the tool (e.g., 'wu:spawn', 'mem:inbox')
+ * @returns {Promise<{valid: boolean, missing: string[], toolName: string}>} Validation result
+ *
+ * @example
+ * const result = await validateToolDependencies('wu:spawn');
+ * if (!result.valid) {
+ *   console.error(formatDependencyError(result.toolName, result.missing));
+ *   process.exit(1);
+ * }
+ */
+export async function validateToolDependencies(toolName) {
+    const dependencyKey = toolName;
+    const deps = dependencyKey in TOOL_DEPENDENCIES ? TOOL_DEPENDENCIES[dependencyKey] : [];
+    const result = await validateDependencies(deps);
+    return {
+        ...result,
+        toolName,
+    };
+}
+//# sourceMappingURL=dependency-validator.js.map

package/dist/dependency-validator.js.map

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

package/dist/docs-path-validator.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Validate a list of staged files for docs-only WU
+ * @param {string[]} stagedFiles - Array of file paths
+ * @returns {{valid: boolean, violations: string[]}} - Validation result
+ */
+export declare function validateDocsOnly(stagedFiles: UnsafeAny): {
+    valid: boolean;
+    violations: any[];
+};
+/**
+ * Get a human-readable description of allowed paths
+ * @returns {string} - Description of allowed paths
+ */
+export declare function getAllowedPathsDescription(): string;
+//# sourceMappingURL=docs-path-validator.d.ts.map

package/dist/docs-path-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-path-validator.d.ts","sourceRoot":"","sources":["../src/docs-path-validator.ts"],"names":[],"mappings":";AAwEA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,SAAS;;;EAWtD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,WAWzC"}

package/dist/docs-path-validator.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Docs Path Validator
+ *
+ * Validates that files staged for commit in a docs-only WU
+ * are restricted to documentation paths only.
+ *
+ * Allowed paths:
+ * - memory-bank/**
+ * - docs/**
+ * - ai/**
+ * - .claude/**
+ * - *.md (markdown files anywhere)
+ * - .lumenflow/stamps/**
+ * - .lumenflow/state/wu-events.jsonl (tooling-managed metadata)
+ *
+ * Forbidden paths:
+ * - apps/**
+ * - packages/** (except test files)
+ * - supabase/**
+ * - tools/** (except test files)
+ */
+import path from 'node:path';
+import { WU_EVENTS_FILE_NAME } from './wu-state-store.js';
+import { LUMENFLOW_PATHS, DIRECTORIES, FILE_EXTENSIONS, STRING_LITERALS } from './wu-constants.js';
+const POSIX = path.posix;
+const DOCS_ONLY_PREFIXES = Object.freeze([
+    DIRECTORIES.DOCS,
+    DIRECTORIES.AI,
+    DIRECTORIES.CLAUDE,
+    DIRECTORIES.MEMORY_BANK,
+]);
+const TOOLS_TESTS_PREFIX = `${POSIX.join(DIRECTORIES.TOOLS, '__tests__')}${STRING_LITERALS.SLASH}`;
+const STAMPS_PREFIX = `${LUMENFLOW_PATHS.STAMPS_DIR}${STRING_LITERALS.SLASH}`;
+const WU_EVENTS_PATH = POSIX.join(LUMENFLOW_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME);
+/**
+ * Check if a file path is allowed for docs-only WUs
+ * @param {string} filePath - The file path to validate
+ * @returns {boolean} - True if the path is allowed
+ */
+function isAllowedPath(filePath) {
+    if (!filePath)
+        return false;
+    if (filePath === WU_EVENTS_PATH)
+        return true;
+    if (filePath.startsWith(STAMPS_PREFIX))
+        return true;
+    if (filePath.startsWith(TOOLS_TESTS_PREFIX))
+        return true;
+    if (filePath.startsWith(DIRECTORIES.PACKAGES)) {
+        const testsSegment = `${STRING_LITERALS.SLASH}__tests__${STRING_LITERALS.SLASH}`;
+        return filePath.includes(testsSegment);
+    }
+    if (filePath.endsWith(FILE_EXTENSIONS.MARKDOWN))
+        return true;
+    for (const prefix of DOCS_ONLY_PREFIXES) {
+        if (filePath.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate a list of staged files for docs-only WU
+ * @param {string[]} stagedFiles - Array of file paths
+ * @returns {{valid: boolean, violations: string[]}} - Validation result
+ */
+export function validateDocsOnly(stagedFiles) {
+    const violations = [];
+    for (const file of stagedFiles) {
+        if (!isAllowedPath(file)) {
+            violations.push(file);
+        }
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+    };
+}
+/**
+ * Get a human-readable description of allowed paths
+ * @returns {string} - Description of allowed paths
+ */
+export function getAllowedPathsDescription() {
+    return `Docs-only WUs can only modify:
+  - memory-bank/** (task definitions, workflow docs)
+  - ai/** (agent documentation, onboarding)
+  - .claude/** (agent configuration and skills)
+  - docs/** (technical documentation)
+  - *.md (markdown files)
+  - .lumenflow/stamps/** (completion stamps)
+  - .lumenflow/state/${WU_EVENTS_FILE_NAME} (WU lifecycle event log)
+  - tools/__tests__/** (test files only)
+  - packages/**/__tests__/** (test files only)`;
+}
+//# sourceMappingURL=docs-path-validator.js.map

package/dist/docs-path-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-path-validator.js","sourceRoot":"","sources":["../src/docs-path-validator.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEnG,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;AAEzB,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,WAAW,CAAC,IAAI;IAChB,WAAW,CAAC,EAAE;IACd,WAAW,CAAC,MAAM;IAClB,WAAW,CAAC,WAAW;CACxB,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,eAAe,CAAC,KAAK,EAAE,CAAC;AACnG,MAAM,aAAa,GAAG,GAAG,eAAe,CAAC,UAAU,GAAG,eAAe,CAAC,KAAK,EAAE,CAAC;AAC9E,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;AAElF;;;;GAIG;AACH,SAAS,aAAa,CAAC,QAAmB;IACxC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5B,IAAI,QAAQ,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IAE7C,IAAI,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,QAAQ,CAAC,UAAU,CAAC,kBAAkB,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzD,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,MAAM,YAAY,GAAG,GAAG,eAAe,CAAC,KAAK,YAAY,eAAe,CAAC,KAAK,EAAE,CAAC;QACjF,OAAO,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7D,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAsB;IACrD,MAAM,UAAU,GAAG,EAAE,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC;QAC9B,UAAU;KACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO;;;;;;;uBAOc,mBAAmB;;+CAEK,CAAC;AAChD,CAAC"}