@lumenflow/core 3.2.0 → 3.2.2

package/dist/ports/core-tools.ports.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Core Tools Ports
+ *
+ * WU-1101: INIT-003 Phase 2a - Migrate tools/lib/core/ to @lumenflow/core
+ *
+ * Port interfaces for core tool modules migrated from ExampleApp tools/lib/core/.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - IToolRunner: Execute tools with validation and guards
+ * - IWorktreeGuard: Detect and enforce worktree context
+ * - IScopeChecker: Validate file paths against WU code_paths
+ *
+ * Current Implementations:
+ * - runTool, ToolRunner (tool-runner.ts)
+ * - getWUContext, assertWorktreeRequired, isInWorktree, isMainBranch (worktree-guard.ts)
+ * - getActiveScope, isPathInScope, assertPathInScope (scope-checker.ts)
+ *
+ * @module ports/core-tools
+ */
+import type { ZodType } from 'zod';
+import type { ToolOutput, ToolError } from '../core/tool.schemas.js';
+import type { PermissionLevel, ToolDomain } from '../core/tool.constants.js';
+/**
+ * Tool metadata interface
+ */
+export interface IToolMetadata {
+    /** Tool name (unique identifier) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Tool domain classification */
+    domain?: ToolDomain;
+    /** Required permission level */
+    permission: PermissionLevel;
+    /** Tool version */
+    version?: string;
+}
+/**
+ * Tool definition interface
+ */
+export interface IToolDefinition {
+    /** Tool metadata */
+    metadata: IToolMetadata;
+    /** Zod schema for input validation */
+    inputSchema?: ZodType;
+    /** Zod schema for output validation */
+    outputSchema?: ZodType;
+    /** Tool execution function */
+    execute: (input: unknown, context?: unknown) => Promise<ToolOutput>;
+}
+/**
+ * Tool configuration options
+ */
+export interface IToolConfigOptions {
+    /** Require worktree context for execution */
+    requiresWorktree?: boolean;
+    /** Require scope validation for file paths */
+    requiresScope?: boolean;
+    /** Enable audit logging */
+    enableAuditLog?: boolean;
+    /** Execution timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Tool execution options
+ */
+export interface IRunToolOptions {
+    /** Injected dependencies (for testing) */
+    dependencies?: Record<string, unknown>;
+    /** Configuration overrides */
+    config?: IToolConfigOptions;
+    /** Execution context (sessionId, userId, etc.) */
+    context?: Record<string, unknown>;
+}
+/**
+ * Tool Executor Port Interface (Slim)
+ *
+ * WU-1549: Segregated from IToolRunner following Interface Segregation Principle.
+ * Gate consumers and simple tool execution only need runTool and run methods,
+ * not the full registry (register, hasTool, listTools).
+ *
+ * @example
+ * // Direct tool execution
+ * const result = await executor.runTool(toolDefinition, { message: 'hello' });
+ *
+ * @example
+ * // Named tool execution
+ * const result = await executor.run('tool:name', { arg: 'value' });
+ */
+export interface IToolExecutor {
+    /**
+     * Execute a tool with full validation and guards.
+     *
+     * @param tool - Tool definition
+     * @param input - Tool input arguments
+     * @param options - Execution options
+     * @returns Tool output (success/failure with data/error)
+     */
+    runTool(tool: IToolDefinition, input: unknown, options?: IRunToolOptions): Promise<ToolOutput>;
+    /**
+     * Run a registered tool by name.
+     *
+     * @param name - Tool name
+     * @param input - Tool input
+     * @param options - Execution options
+     * @returns Tool output
+     */
+    run(name: string, input: unknown, options?: IRunToolOptions): Promise<ToolOutput>;
+}
+/**
+ * Tool Runner Port Interface (Full)
+ *
+ * Extends IToolExecutor with tool registry management (register, hasTool, listTools).
+ * Use IToolExecutor for consumers that only need execution.
+ * Use IToolRunner for consumers that also manage the tool registry.
+ *
+ * @example
+ * // Full registry usage
+ * runner.register(myTool);
+ * const result = await runner.run('tool:name', { arg: 'value' });
+ * const tools = runner.listTools({ domain: 'file' });
+ */
+export interface IToolRunner extends IToolExecutor {
+    /**
+     * Register a tool definition.
+     *
+     * @param tool - Tool definition
+     * @throws Error if tool with same name already registered
+     */
+    register(tool: IToolDefinition): void;
+    /**
+     * Check if a tool is registered.
+     *
+     * @param name - Tool name
+     * @returns True if tool exists
+     */
+    hasTool(name: string): boolean;
+    /**
+     * List all registered tools.
+     *
+     * @param options - Filter options
+     * @returns Array of tool metadata
+     */
+    listTools(options?: {
+        domain?: string;
+    }): IToolMetadata[];
+}
+/**
+ * WU context from worktree detection
+ */
+export interface IWUContext {
+    /** WU identifier (e.g., 'WU-1101') */
+    wuId: string;
+    /** Lane name in kebab-case (e.g., 'framework-core') */
+    lane: string;
+    /** Worktree path relative to repo root, or null if on lane branch */
+    worktreePath: string | null;
+}
+/**
+ * Worktree detection options
+ */
+export interface IWorktreeOptions {
+    /** Current working directory (defaults to process.cwd()) */
+    cwd?: string;
+    /** Git adapter instance (for testing) */
+    git?: {
+        getCurrentBranch(): Promise<string>;
+    };
+    /** Operation name for error messages */
+    operation?: string;
+}
+/**
+ * Worktree Guard Port Interface
+ *
+ * Provides runtime guards to enforce worktree discipline:
+ * - Detect if current directory is inside a worktree
+ * - Extract WU ID and lane from worktree path or git branch
+ * - Block write operations when not in worktree
+ *
+ * @example
+ * // Check worktree context
+ * const context = await guard.getWUContext();
+ * if (context) {
+ *   console.log(`Working on ${context.wuId} in ${context.lane}`);
+ * }
+ *
+ * @example
+ * // Assert worktree for write operation
+ * await guard.assertWorktreeRequired({ operation: 'file:write' });
+ */
+export interface IWorktreeGuard {
+    /**
+     * Check if current directory is inside a worktree.
+     *
+     * @param options - Detection options
+     * @returns True if inside a worktree directory
+     */
+    isInWorktree(options?: IWorktreeOptions): boolean;
+    /**
+     * Check if on main or master branch.
+     *
+     * @param options - Detection options
+     * @returns True if on main/master branch
+     */
+    isMainBranch(options?: IWorktreeOptions): Promise<boolean>;
+    /**
+     * Get WU context from worktree path or git branch.
+     *
+     * @param options - Detection options
+     * @returns WU context or null if not in WU workspace
+     */
+    getWUContext(options?: IWorktreeOptions): Promise<IWUContext | null>;
+    /**
+     * Assert that current context is inside a worktree or on a lane branch.
+     * Throws if on main branch in main checkout.
+     *
+     * @param options - Detection options
+     * @throws Error if not in worktree and on main branch
+     */
+    assertWorktreeRequired(options?: IWorktreeOptions): Promise<void>;
+}
+/**
+ * WU scope with code paths
+ */
+export interface IWUScope {
+    /** WU identifier */
+    wuId: string;
+    /** Allowed file paths/glob patterns */
+    code_paths: string[];
+}
+/**
+ * Scope Checker Port Interface
+ *
+ * Provides runtime validation that file modifications stay within WU code_paths.
+ * Prevents scope creep and ensures agents only modify authorized files.
+ *
+ * @example
+ * // Check if path is in scope
+ * const scope = await checker.getActiveScope();
+ * if (checker.isPathInScope('src/file.ts', scope)) {
+ *   // Safe to modify
+ * }
+ *
+ * @example
+ * // Assert path is in scope (throws if not)
+ * await checker.assertPathInScope('src/file.ts', scope, 'file:write');
+ */
+export interface IScopeChecker {
+    /**
+     * Get active WU scope (WU ID + code_paths).
+     *
+     * @param options - Options for dependency injection
+     * @returns Scope object or null if not in WU workspace
+     */
+    getActiveScope(options?: {
+        getWUContext?: () => Promise<IWUContext | null>;
+        loadWUYaml?: (wuId: string) => {
+            code_paths?: string[];
+        };
+    }): Promise<IWUScope | null>;
+    /**
+     * Check if a file path is within WU scope.
+     *
+     * @param filePath - File path to check
+     * @param scope - Scope object from getActiveScope()
+     * @returns True if path is in scope
+     */
+    isPathInScope(filePath: string, scope: IWUScope | null): boolean;
+    /**
+     * Assert that a file path is within WU scope.
+     * Throws if path is outside scope or no scope available.
+     *
+     * @param filePath - File path to check
+     * @param scope - Scope object from getActiveScope()
+     * @param operation - Operation name for error message
+     * @throws Error if path is outside scope
+     */
+    assertPathInScope(filePath: string, scope: IWUScope | null, operation?: string): void;
+}
+export type { ToolOutput, ToolError };
+//# sourceMappingURL=core-tools.ports.d.ts.map

package/dist/ports/core-tools.ports.d.ts.map

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

package/dist/ports/core-tools.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=core-tools.ports.js.map

package/dist/ports/core-tools.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-tools.ports.js","sourceRoot":"","sources":["../../src/ports/core-tools.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/ports/dashboard-renderer.port.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Dashboard Renderer Port
+ *
+ * Hexagonal Architecture - Output Port
+ * Defines the contract for rendering orchestration dashboard data to UnsafeAny UI.
+ * This abstraction allows the application layer to remain independent of
+ * specific rendering implementations.
+ *
+ * Current Implementations:
+ * - TerminalDashboardRenderer (WU-1322) - ASCII/ANSI terminal output
+ *
+ * Future Implementations:
+ * - WebDashboardRenderer - Browser-based UI
+ * - VSCodeWebviewRenderer - VS Code extension panel
+ *
+ * SOLID Principles:
+ * - Dependency Inversion: Use cases depend on this abstraction, not concrete renderers
+ * - Interface Segregation: Focused on rendering, no data fetching concerns
+ * - Open/Closed: New renderers can be added without modifying existing code
+ *
+ * @module dashboard-renderer.port
+ * @see {@link ../domain/orchestration.types.ts} - Types used in this interface
+ * @see {@link ../../adapters/terminal-renderer.adapter.ts} - Terminal implementation (WU-1322)
+ */
+import type { DashboardData, Suggestion, ExecutionPlan, UserChoice } from '../domain/orchestration.types.js';
+/**
+ * Dashboard Renderer Port Interface
+ *
+ * Implementers must provide methods to render all dashboard sections
+ * and handle user interactions for execution plan approval.
+ *
+ * @example
+ * // Implementing a custom renderer
+ * class CustomRenderer implements IDashboardRenderer {
+ *   render(data: DashboardData): void {
+ *     // Render global status, agent metrics, WU progress, timeline, alerts
+ *   }
+ *
+ *   renderSuggestions(suggestions: Suggestion[]): void {
+ *     // Display prioritised suggestions
+ *   }
+ *
+ *   renderPlan(plan: ExecutionPlan): Promise<UserChoice> {
+ *     // Show plan and get user approval
+ *   }
+ *
+ *   clear(): void {
+ *     // Clear previous output
+ *   }
+ * }
+ *
+ * @example
+ * // Using in a use case
+ * class GetDashboardDataUseCase {
+ *   constructor(
+ *     private readonly renderer: IDashboardRenderer,
+ *     private readonly collector: IMetricsCollector,
+ *   ) {}
+ *
+ *   async execute(): Promise<void> {
+ *     const data = await this.collectData();
+ *     this.renderer.render(data);
+ *   }
+ * }
+ */
+export interface IDashboardRenderer {
+    /**
+     * Render the complete dashboard with all sections.
+     *
+     * Sections to render:
+     * 1. Global Status - Active WUs, completed, blocked, gates failing
+     * 2. Agent Small Multiples - Per-agent metrics comparison
+     * 3. WU Progress - DoD progress bars with agent status
+     * 4. Timeline - Recent orchestration events
+     * 5. Alerts - Items requiring attention
+     *
+     * @param data - Complete dashboard data from metrics collector
+     */
+    render(data: DashboardData): void;
+    /**
+     * Render a list of prioritised suggestions.
+     *
+     * Suggestions should be displayed with:
+     * - Priority indicator (HIGH/MEDIUM/LOW)
+     * - Action description
+     * - Reason for suggestion
+     * - Command to execute
+     *
+     * @param suggestions - Ordered list of suggestions (highest priority first)
+     */
+    renderSuggestions(suggestions: Suggestion[]): void;
+    /**
+     * Render an execution plan and get user approval.
+     *
+     * Should display:
+     * - WU being executed
+     * - Ordered list of steps
+     * - Estimated token cost
+     * - Approval prompt (approve/reject/edit)
+     *
+     * @param plan - Proposed execution plan
+     * @returns User's choice (approve, reject, or edit with modifications)
+     */
+    renderPlan(plan: ExecutionPlan): Promise<UserChoice>;
+    /**
+     * Clear UnsafeAny previous dashboard output.
+     *
+     * Used before re-rendering to prevent stale data display.
+     * Implementation depends on output medium (e.g., clear terminal, DOM update).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=dashboard-renderer.port.d.ts.map

package/dist/ports/dashboard-renderer.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-renderer.port.d.ts","sourceRoot":"","sources":["../../src/ports/dashboard-renderer.port.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,aAAa,EACb,UAAU,EACX,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAElC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAEnD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAErD;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/ports/dashboard-renderer.port.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=dashboard-renderer.port.js.map

package/dist/ports/dashboard-renderer.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-renderer.port.js","sourceRoot":"","sources":["../../src/ports/dashboard-renderer.port.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/ports/git-validator.ports.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Git Validator Ports
+ *
+ * WU-1103: INIT-003 Phase 2c - Add git adapter and validator ports
+ *
+ * Port interfaces for git operations used by WU validation and lifecycle scripts.
+ * These abstractions allow dependency injection and contract-based testing.
+ *
+ * @module ports/git-validator
+ */
+/**
+ * Push command options.
+ */
+export interface PushOptions {
+    /** Set upstream tracking (equivalent to git push -u). */
+    setUpstream?: boolean;
+}
+/**
+ * Merge command options.
+ */
+export interface MergeOptions {
+    /** Require fast-forward-only merge. */
+    ffOnly?: boolean;
+}
+/**
+ * Worktree removal options.
+ */
+export interface WorktreeRemoveOptions {
+    /** Force removal when worktree has uncommitted changes. */
+    force?: boolean;
+}
+/**
+ * Branch deletion options.
+ */
+export interface DeleteBranchOptions {
+    /** Force-delete branch (equivalent to git branch -D). */
+    force?: boolean;
+}
+/**
+ * Reset command options.
+ */
+export interface ResetOptions {
+    /** Perform hard reset (equivalent to git reset --hard). */
+    hard?: boolean;
+}
+/**
+ * Log command options.
+ */
+export interface LogOptions {
+    /** Maximum number of commits to return. */
+    maxCount?: number;
+}
+/**
+ * Minimal merge result contract.
+ */
+export interface MergeResult {
+    /** True when merge completed successfully. */
+    success: boolean;
+}
+/**
+ * Minimal git log entry contract.
+ */
+export interface GitLogEntry {
+    hash: string;
+    message: string;
+}
+/**
+ * Minimal git log result contract.
+ */
+export interface GitLogResult {
+    all: GitLogEntry[];
+    total: number;
+}
+/**
+ * Git adapter contract used by validator and lifecycle workflows.
+ *
+ * Note: Keep this aligned with `GitAdapter` public methods.
+ */
+export interface IGitAdapter {
+    getCurrentBranch(): Promise<string>;
+    getStatus(): Promise<string>;
+    getUnpushedCommits(): Promise<string>;
+    branchExists(branch: string): Promise<boolean>;
+    remoteBranchExists(remote: string, branch: string): Promise<boolean>;
+    fetch(remote?: string, branch?: string): Promise<void>;
+    pull(remote: string, branch: string): Promise<void>;
+    getConfigValue(key: string): Promise<string>;
+    isClean(): Promise<boolean>;
+    add(files: string | string[]): Promise<void>;
+    addWithDeletions(files: string[]): Promise<void>;
+    commit(message: string): Promise<void>;
+    push(remote?: string, branch?: string, options?: PushOptions): Promise<void>;
+    pushRefspec(remote: string, localRef: string, remoteRef: string): Promise<void>;
+    createBranch(branch: string, startPoint?: string): Promise<void>;
+    checkout(branch: string): Promise<void>;
+    getCommitHash(ref?: string): Promise<string>;
+    merge(branch: string, options?: MergeOptions): Promise<MergeResult>;
+    log(options?: LogOptions): Promise<GitLogResult>;
+    mergeBase(ref1: string, ref2: string): Promise<string>;
+    mergeTree(base: string, ref1: string, ref2: string): Promise<string>;
+    revList(args: string[]): Promise<string>;
+    worktreeAdd(path: string, branch: string, startPoint?: string): Promise<void>;
+    worktreeRemove(worktreePath: string, options?: WorktreeRemoveOptions): Promise<void>;
+    worktreeList(): Promise<string>;
+    deleteBranch(branch: string, options?: DeleteBranchOptions): Promise<void>;
+    createBranchNoCheckout(branch: string, startPoint?: string): Promise<void>;
+    worktreeAddExisting(path: string, branch: string): Promise<void>;
+    rebase(onto: string): Promise<void>;
+    reset(ref?: string, options?: ResetOptions): Promise<void>;
+    raw(args: string[]): Promise<string>;
+    addWorktree(path: string, branch: string, startPoint?: string): Promise<void>;
+    removeWorktree(path: string, options?: WorktreeRemoveOptions): Promise<void>;
+}
+//# sourceMappingURL=git-validator.ports.d.ts.map

package/dist/ports/git-validator.ports.d.ts.map

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

package/dist/ports/git-validator.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=git-validator.ports.js.map

package/dist/ports/git-validator.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-validator.ports.js","sourceRoot":"","sources":["../../src/ports/git-validator.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ports Index
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ * WU-1101: INIT-003 Phase 2a - Add core tools ports
+ * WU-1103: INIT-003 Phase 2c - Add git adapter and validator ports
+ *
+ * Re-exports all port interfaces for the context-aware validation system
+ * and core tools (tool-runner, worktree-guard, scope-checker).
+ *
+ * @module ports
+ */
+export * from './context.ports.js';
+export * from './validation.ports.js';
+export * from './recovery.ports.js';
+export * from './metrics-collector.port.js';
+export * from './dashboard-renderer.port.js';
+export * from './core-tools.ports.js';
+export * from './wu-helpers.ports.js';
+export * from './git-validator.ports.js';
+export * from './wu-state.ports.js';
+export * from './config.ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}

package/dist/ports/index.js

@@ -0,0 +1,25 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Ports Index
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ * WU-1101: INIT-003 Phase 2a - Add core tools ports
+ * WU-1103: INIT-003 Phase 2c - Add git adapter and validator ports
+ *
+ * Re-exports all port interfaces for the context-aware validation system
+ * and core tools (tool-runner, worktree-guard, scope-checker).
+ *
+ * @module ports
+ */
+export * from './context.ports.js';
+export * from './validation.ports.js';
+export * from './recovery.ports.js';
+export * from './metrics-collector.port.js';
+export * from './dashboard-renderer.port.js';
+export * from './core-tools.ports.js';
+export * from './wu-helpers.ports.js';
+export * from './git-validator.ports.js';
+export * from './wu-state.ports.js';
+export * from './config.ports.js';
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;GAWG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}