@generacy-ai/orchestrator 0.0.0-preview-20260304013206

package/dist/worker/phase-loop.js

@@ -0,0 +1,185 @@
+import { PHASE_SEQUENCE, PHASE_TO_COMMAND, PHASE_TO_STAGE } from './types.js';
+/**
+ * Iterates through workflow phases from the starting phase to completion.
+ *
+ * For each phase the loop:
+ * 1. Updates labels to reflect the current phase
+ * 2. Spawns the Claude CLI (or runs the validate command)
+ * 3. Marks the phase as completed
+ * 4. Checks for review gates
+ * 5. Updates the stage comment with progress
+ *
+ * The loop stops on:
+ * - Gate hit (workflow paused for human review)
+ * - Phase failure (error)
+ * - Abort signal
+ * - All phases completed
+ */
+export class PhaseLoop {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Execute the phase loop from the starting phase through to completion.
+     *
+     * @param phaseSequence - Optional workflow-specific phase sequence.
+     *   Defaults to the global PHASE_SEQUENCE for backward compatibility.
+     */
+    async executeLoop(context, config, deps, phaseSequence) {
+        const sequence = phaseSequence ?? PHASE_SEQUENCE;
+        const { labelManager, stageCommentManager, gateChecker, cliSpawner, outputCapture, prManager } = deps;
+        const results = [];
+        // Track session ID across phases for conversation resume.
+        // When a CLI phase completes, its session ID is passed to the next phase
+        // so Claude CLI can reuse the conversation (keeping MCP servers warm and
+        // carrying forward accumulated context).
+        let currentSessionId;
+        // Find the starting index in the phase sequence
+        const startIndex = sequence.indexOf(context.startPhase);
+        if (startIndex === -1) {
+            throw new Error(`Unknown starting phase: ${context.startPhase}`);
+        }
+        this.logger.info({ startPhase: context.startPhase, startIndex, totalPhases: sequence.length }, 'Starting phase loop');
+        for (let i = startIndex; i < sequence.length; i++) {
+            const phase = sequence[i];
+            // Check abort signal before starting each phase
+            if (context.signal.aborted) {
+                this.logger.warn({ phase }, 'Abort signal detected, stopping phase loop');
+                return { results, completed: false, lastPhase: phase, gateHit: false };
+            }
+            this.logger.info({ phase, index: i }, 'Starting phase');
+            // 1. Update labels: mark this phase as active
+            await labelManager.onPhaseStart(phase);
+            // 2. Update stage comment to show phase in progress
+            const stage = PHASE_TO_STAGE[phase];
+            await stageCommentManager.updateStageComment({
+                stage,
+                status: 'in_progress',
+                phases: this.buildPhaseProgress(sequence, startIndex, i),
+                startedAt: new Date().toISOString(),
+            });
+            // 3. Execute the phase
+            let result;
+            try {
+                if (PHASE_TO_COMMAND[phase] === null) {
+                    // Validate phase — run test command
+                    result = await cliSpawner.runValidatePhase(context.checkoutPath, config.validateCommand, context.signal);
+                }
+                else {
+                    // CLI phase — spawn Claude CLI (resume previous session if available)
+                    result = await cliSpawner.spawnPhase(phase, {
+                        prompt: context.issueUrl,
+                        cwd: context.checkoutPath,
+                        env: {},
+                        maxTurns: config.maxTurns,
+                        timeoutMs: config.phaseTimeoutMs,
+                        signal: context.signal,
+                        resumeSessionId: currentSessionId,
+                    }, outputCapture);
+                }
+            }
+            catch (error) {
+                // Unexpected error during spawning
+                this.logger.error({ phase, error: String(error) }, 'Unexpected error during phase execution');
+                await labelManager.onError(phase);
+                await stageCommentManager.updateStageComment({
+                    stage,
+                    status: 'error',
+                    phases: this.buildPhaseProgress(sequence, startIndex, i, 'error'),
+                    startedAt: new Date().toISOString(),
+                });
+                throw error;
+            }
+            results.push(result);
+            // 3b. Capture session ID for resume in subsequent phases
+            if (result.sessionId) {
+                if (!currentSessionId) {
+                    this.logger.info({ sessionId: result.sessionId, phase }, 'Captured initial session ID for conversation reuse');
+                }
+                currentSessionId = result.sessionId;
+            }
+            // 4. Handle phase failure
+            if (!result.success) {
+                this.logger.error({ phase, exitCode: result.exitCode, error: result.error?.message }, 'Phase failed');
+                await labelManager.onError(phase);
+                await stageCommentManager.updateStageComment({
+                    stage,
+                    status: 'error',
+                    phases: this.buildPhaseProgress(sequence, startIndex, i, 'error'),
+                    startedAt: new Date().toISOString(),
+                });
+                return { results, completed: false, lastPhase: phase, gateHit: false };
+            }
+            // 5. Mark phase as completed in labels
+            await labelManager.onPhaseComplete(phase);
+            // 5b. Commit, push, and ensure draft PR exists
+            const prUrl = await prManager.commitPushAndEnsurePr(phase);
+            if (prUrl) {
+                context.prUrl = prUrl;
+            }
+            // 6. Check for review gates
+            const gate = gateChecker.checkGate(phase, context.item.workflowName, config);
+            if (gate && gate.condition === 'always') {
+                this.logger.info({ phase, gateLabel: gate.gateLabel }, 'Gate hit, pausing workflow');
+                await labelManager.onGateHit(phase, gate.gateLabel);
+                // Update the result with gate info
+                result.gateHit = {
+                    gateLabel: gate.gateLabel,
+                    reason: `Review gate "${gate.gateLabel}" activated after phase "${phase}"`,
+                };
+                // Update stage comment showing gate hit
+                await stageCommentManager.updateStageComment({
+                    stage,
+                    status: 'in_progress',
+                    phases: this.buildPhaseProgress(sequence, startIndex, i, 'complete'),
+                    startedAt: new Date().toISOString(),
+                    prUrl: context.prUrl,
+                });
+                return { results, completed: false, lastPhase: phase, gateHit: true };
+            }
+            // 7. Update stage comment showing phase complete
+            const isLastPhaseInStage = i + 1 >= sequence.length || PHASE_TO_STAGE[sequence[i + 1]] !== stage;
+            await stageCommentManager.updateStageComment({
+                stage,
+                status: isLastPhaseInStage ? 'complete' : 'in_progress',
+                phases: this.buildPhaseProgress(sequence, startIndex, i, 'complete'),
+                startedAt: new Date().toISOString(),
+                ...(isLastPhaseInStage ? { completedAt: new Date().toISOString() } : {}),
+                prUrl: context.prUrl,
+            });
+            // Clear output buffer for next phase
+            outputCapture.clear();
+        }
+        this.logger.info('Phase loop completed successfully — all phases done');
+        return {
+            results,
+            completed: true,
+            lastPhase: sequence[sequence.length - 1],
+            gateHit: false,
+        };
+    }
+    /**
+     * Build a phase progress array for stage comment updates.
+     */
+    buildPhaseProgress(sequence, startIndex, currentIndex, currentStatus = 'in_progress') {
+        const now = new Date().toISOString();
+        return sequence.map((phase, idx) => {
+            if (idx < startIndex) {
+                // Before the start — already complete from a prior run
+                return { phase, status: 'complete', completedAt: now };
+            }
+            if (idx < currentIndex) {
+                // Earlier in this run — completed
+                return { phase, status: 'complete', startedAt: now, completedAt: now };
+            }
+            if (idx === currentIndex) {
+                // Current phase
+                return { phase, status: currentStatus, startedAt: now };
+            }
+            // Future phase
+            return { phase, status: 'pending' };
+        });
+    }
+}
+//# sourceMappingURL=phase-loop.js.map

package/dist/worker/phase-loop.js.map

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

package/dist/worker/phase-resolver.d.ts

@@ -0,0 +1,62 @@
+import { type WorkflowPhase } from './types.js';
+/**
+ * Unified mapping from gate names to their owning phase and the phase to resume from.
+ *
+ * - `phase`: the workflow phase this gate belongs to (used to normalize gate names in resolveFromProcess)
+ * - `resumeFrom`: the phase to start from when the gate is satisfied (used in resolveFromContinue)
+ */
+export declare const GATE_MAPPING: Record<string, {
+    phase: WorkflowPhase;
+    resumeFrom: WorkflowPhase;
+}>;
+/**
+ * Workflow-specific gate mappings that override the global GATE_MAPPING.
+ *
+ * For epic workflows, certain gates have different resume behavior:
+ * - `tasks-review`: resumes to 'tasks' (triggers post-tasks/child creation, not implement)
+ * - `children-complete`: dedicated handling (routes to epic-complete command)
+ * - `epic-approval`: dedicated handling (routes to epic-close)
+ */
+export declare const WORKFLOW_GATE_MAPPING: Record<string, Record<string, {
+    phase: WorkflowPhase;
+    resumeFrom: WorkflowPhase;
+}>>;
+/**
+ * Resolve the starting phase based on issue labels and command type.
+ */
+export declare class PhaseResolver {
+    /**
+     * Determine the starting phase for a queue item.
+     *
+     * - 'process' command: inspects completed/phase labels to find the next uncompleted phase.
+     * - 'continue' command: matches completed gate labels via GATE_MAPPING to determine resume phase.
+     *
+     * @param workflowName - Optional workflow name for workflow-specific gate resolution.
+     *   When provided, uses the workflow's phase sequence and gate mappings.
+     */
+    resolveStartPhase(labels: string[], command: 'process' | 'continue', workflowName?: string): WorkflowPhase;
+    /**
+     * For 'process' command: find the starting phase from labels.
+     *
+     * Priority:
+     * 1. If a `phase:*` label exists, resume from that phase
+     * 2. If `completed:*` labels exist, start from next uncompleted phase
+     *    (gate names like 'clarification' are normalized to phase names via GATE_MAPPING)
+     * 3. If no phase labels, start from 'specify'
+     */
+    private resolveFromProcess;
+    /**
+     * For 'continue' command: find which gate was just satisfied and resume from the next phase.
+     *
+     * Does not depend on `waiting-for:*` labels (those are removed by the worker on resume).
+     * Matches `completed:*` labels against the effective gate mapping (workflow-specific first,
+     * then global GATE_MAPPING) and returns the most advanced gate's resumeFrom phase.
+     */
+    private resolveFromContinue;
+    /**
+     * Build the effective gate mapping for a workflow.
+     * Workflow-specific mappings in WORKFLOW_GATE_MAPPING override entries in the global GATE_MAPPING.
+     */
+    private getEffectiveGateMapping;
+}
+//# sourceMappingURL=phase-resolver.d.ts.map

package/dist/worker/phase-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-resolver.d.ts","sourceRoot":"","sources":["../../src/worker/phase-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,aAAa,CAAA;CAAE,CAQ5F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,aAAa,CAAA;CAAE,CAAC,CAMrH,CAAC;AAEF;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;;;;OAQG;IACH,iBAAiB,CACf,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,SAAS,GAAG,UAAU,EAC/B,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa;IAOhB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IA2C1B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;CAYhC"}

package/dist/worker/phase-resolver.js

@@ -0,0 +1,144 @@
+import { PHASE_SEQUENCE, getPhaseSequence } from './types.js';
+/**
+ * Unified mapping from gate names to their owning phase and the phase to resume from.
+ *
+ * - `phase`: the workflow phase this gate belongs to (used to normalize gate names in resolveFromProcess)
+ * - `resumeFrom`: the phase to start from when the gate is satisfied (used in resolveFromContinue)
+ */
+export const GATE_MAPPING = {
+    'clarification': { phase: 'clarify', resumeFrom: 'plan' },
+    'spec-review': { phase: 'specify', resumeFrom: 'clarify' },
+    'clarification-review': { phase: 'clarify', resumeFrom: 'plan' },
+    'plan-review': { phase: 'plan', resumeFrom: 'tasks' },
+    'tasks-review': { phase: 'tasks', resumeFrom: 'implement' },
+    'implementation-review': { phase: 'implement', resumeFrom: 'validate' },
+    'manual-validation': { phase: 'validate', resumeFrom: 'validate' },
+};
+/**
+ * Workflow-specific gate mappings that override the global GATE_MAPPING.
+ *
+ * For epic workflows, certain gates have different resume behavior:
+ * - `tasks-review`: resumes to 'tasks' (triggers post-tasks/child creation, not implement)
+ * - `children-complete`: dedicated handling (routes to epic-complete command)
+ * - `epic-approval`: dedicated handling (routes to epic-close)
+ */
+export const WORKFLOW_GATE_MAPPING = {
+    'speckit-epic': {
+        'tasks-review': { phase: 'tasks', resumeFrom: 'tasks' },
+        'children-complete': { phase: 'tasks', resumeFrom: 'tasks' },
+        'epic-approval': { phase: 'tasks', resumeFrom: 'tasks' },
+    },
+};
+/**
+ * Resolve the starting phase based on issue labels and command type.
+ */
+export class PhaseResolver {
+    /**
+     * Determine the starting phase for a queue item.
+     *
+     * - 'process' command: inspects completed/phase labels to find the next uncompleted phase.
+     * - 'continue' command: matches completed gate labels via GATE_MAPPING to determine resume phase.
+     *
+     * @param workflowName - Optional workflow name for workflow-specific gate resolution.
+     *   When provided, uses the workflow's phase sequence and gate mappings.
+     */
+    resolveStartPhase(labels, command, workflowName) {
+        if (command === 'continue') {
+            return this.resolveFromContinue(labels, workflowName);
+        }
+        return this.resolveFromProcess(labels, workflowName);
+    }
+    /**
+     * For 'process' command: find the starting phase from labels.
+     *
+     * Priority:
+     * 1. If a `phase:*` label exists, resume from that phase
+     * 2. If `completed:*` labels exist, start from next uncompleted phase
+     *    (gate names like 'clarification' are normalized to phase names via GATE_MAPPING)
+     * 3. If no phase labels, start from 'specify'
+     */
+    resolveFromProcess(labels, workflowName) {
+        const sequence = workflowName ? getPhaseSequence(workflowName) : PHASE_SEQUENCE;
+        const effectiveGateMapping = this.getEffectiveGateMapping(workflowName);
+        // Check for an active phase label
+        for (const label of labels) {
+            if (label.startsWith('phase:')) {
+                const phase = label.slice('phase:'.length);
+                if (sequence.includes(phase)) {
+                    return phase;
+                }
+            }
+        }
+        // Find the last completed phase and return the next one.
+        // Normalize gate names (e.g., 'clarification') to phase names (e.g., 'clarify')
+        // so phase sequence iteration matches correctly.
+        const completedPhases = new Set();
+        for (const label of labels) {
+            if (label.startsWith('completed:')) {
+                const name = label.slice('completed:'.length);
+                completedPhases.add(name);
+                const gateEntry = effectiveGateMapping[name];
+                if (gateEntry) {
+                    completedPhases.add(gateEntry.phase);
+                }
+            }
+        }
+        if (completedPhases.size > 0) {
+            for (const phase of sequence) {
+                if (!completedPhases.has(phase)) {
+                    return phase;
+                }
+            }
+            // All phases completed — return the last phase in the sequence as the terminal phase
+            return sequence[sequence.length - 1];
+        }
+        // No phase labels at all — start from beginning
+        return 'specify';
+    }
+    /**
+     * For 'continue' command: find which gate was just satisfied and resume from the next phase.
+     *
+     * Does not depend on `waiting-for:*` labels (those are removed by the worker on resume).
+     * Matches `completed:*` labels against the effective gate mapping (workflow-specific first,
+     * then global GATE_MAPPING) and returns the most advanced gate's resumeFrom phase.
+     */
+    resolveFromContinue(labels, workflowName) {
+        const sequence = workflowName ? getPhaseSequence(workflowName) : PHASE_SEQUENCE;
+        const effectiveGateMapping = this.getEffectiveGateMapping(workflowName);
+        const completedGates = new Set();
+        for (const label of labels) {
+            if (label.startsWith('completed:')) {
+                const name = label.slice('completed:'.length);
+                if (effectiveGateMapping[name]) {
+                    completedGates.add(name);
+                }
+            }
+        }
+        // Iterate phases latest-to-earliest — most advanced gate wins
+        for (let i = sequence.length - 1; i >= 0; i--) {
+            const phase = sequence[i];
+            for (const gateName of completedGates) {
+                const mapping = effectiveGateMapping[gateName];
+                if (mapping && mapping.phase === phase) {
+                    return mapping.resumeFrom;
+                }
+            }
+        }
+        // Fallback: use the process resolver
+        return this.resolveFromProcess(labels, workflowName);
+    }
+    /**
+     * Build the effective gate mapping for a workflow.
+     * Workflow-specific mappings in WORKFLOW_GATE_MAPPING override entries in the global GATE_MAPPING.
+     */
+    getEffectiveGateMapping(workflowName) {
+        if (!workflowName || !WORKFLOW_GATE_MAPPING[workflowName]) {
+            return GATE_MAPPING;
+        }
+        return {
+            ...GATE_MAPPING,
+            ...WORKFLOW_GATE_MAPPING[workflowName],
+        };
+    }
+}
+//# sourceMappingURL=phase-resolver.js.map

package/dist/worker/phase-resolver.js.map

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

package/dist/worker/pr-feedback-handler.d.ts

@@ -0,0 +1,105 @@
+import type { QueueItem } from '../types/index.js';
+import type { Logger, ProcessFactory } from './types.js';
+import type { WorkerConfig } from './config.js';
+import type { SSEEventEmitter } from './output-capture.js';
+/**
+ * Handles the `address-pr-feedback` command.
+ *
+ * Processing flow:
+ *  1. Extract PR number from queue item metadata
+ *  2. Fetch the PR to get the branch name
+ *  3. Switch to the PR branch (not default branch)
+ *  4. Fetch fresh unresolved review threads
+ *  5. Build a structured prompt with all unresolved comments
+ *  6. Spawn Claude CLI to address the feedback
+ *  7. Stage, commit, and push changes to the PR branch
+ *  8. Reply to each review thread (never resolve)
+ *  9. Remove the `waiting-for:address-pr-feedback` label
+ *
+ * Error handling strategy (T019):
+ *
+ * **FR-013: Timeout handling**
+ * - If CLI times out: push any partial changes that were made
+ * - Keep `waiting-for:address-pr-feedback` label (don't remove)
+ * - Label retention ensures the task will be retried on next detection cycle
+ * - Log timeout warning with structured context
+ *
+ * **FR-007: Reply failure handling**
+ * - If posting replies fails for some threads: still remove label
+ * - Log warnings for each failed reply
+ * - Partial reply success is acceptable (code changes were pushed successfully)
+ * - Handler does not throw on reply failures
+ *
+ * **SC-006: Thread resolution prevention**
+ * - Only use `replyToPRComment()` API — never call any thread-resolve API
+ * - Human reviewer will resolve threads after verifying changes
+ * - Comments in code explicitly reference SC-006 for clarity
+ *
+ * **Structured logging**
+ * - All operations logged with structured context (prNumber, issueNumber, owner, repo)
+ * - Error logs include full error messages and relevant context
+ * - Success/failure states clearly logged for observability
+ * - All FR/SC references included in log messages for traceability
+ *
+ * **Critical operation failures**
+ * - PR fetch failure: throw (cannot proceed without PR details)
+ * - Branch switch failure: throw (wrong branch would cause issues)
+ * - Comment fetch failure: throw (cannot address unknown feedback)
+ * - Push failure: log error but don't throw (allows retry via label)
+ *
+ * **Non-critical operation failures**
+ * - No unresolved threads: remove label, early return (success case)
+ * - Reply posting: log warning, continue (FR-007)
+ * - Label removal: log warning, continue (non-fatal)
+ */
+export declare class PrFeedbackHandler {
+    private readonly config;
+    private readonly logger;
+    private readonly processFactory;
+    private readonly sseEmitter?;
+    private readonly repoCheckout;
+    constructor(config: WorkerConfig, logger: Logger, processFactory: ProcessFactory, sseEmitter?: SSEEventEmitter | undefined);
+    /**
+     * Process a PR feedback addressing task.
+     *
+     * @param item - Queue item with `command: 'address-pr-feedback'`
+     * @param checkoutPath - Path to the already-checked-out repository
+     */
+    handle(item: QueueItem, checkoutPath: string): Promise<void>;
+    /**
+     * Build a structured prompt containing all unresolved review comments.
+     *
+     * The prompt instructs Claude to:
+     * - Read each review comment
+     * - Make the necessary code changes
+     * - Commit the changes
+     * - NOT resolve any threads (human reviewer will resolve)
+     */
+    private buildFeedbackPrompt;
+    /**
+     * Spawn Claude CLI to address PR feedback.
+     *
+     * Returns true if the CLI completed successfully, false on timeout or failure.
+     * FR-013: On timeout, partial changes are pushed and label is kept for retry.
+     */
+    private spawnClaudeForFeedback;
+    /**
+     * Stage all changes, commit, and push to the PR branch.
+     *
+     * Returns true if there were changes to commit, false otherwise.
+     */
+    private commitAndPushChanges;
+    /**
+     * Post a reply to each unresolved review thread.
+     *
+     * SC-006: Never resolves threads — that's left to the human reviewer.
+     * FR-007: Partial failure is acceptable: if some replies fail, log warnings but continue.
+     *         The handler will still remove the label even if some replies fail.
+     */
+    private replyToThreads;
+    /**
+     * Remove the `waiting-for:address-pr-feedback` label from the linked issue.
+     */
+    private removeFeedbackLabel;
+}
+//# sourceMappingURL=pr-feedback-handler.d.ts.map

package/dist/worker/pr-feedback-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-feedback-handler.d.ts","sourceRoot":"","sources":["../../src/worker/pr-feedback-handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAsB,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAN9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAGzB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,cAAc,EAC9B,UAAU,CAAC,EAAE,eAAe,YAAA;IAK/C;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmKlE;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IA6B3B;;;;;OAKG;YACW,sBAAsB;IA0HpC;;;;OAIG;YACW,oBAAoB;IA2ElC;;;;;;OAMG;YACW,cAAc;IAsD5B;;OAEG;YACW,mBAAmB;CAgBlC"}