@stoneforge/quarry 1.12.0 → 1.13.0

package/dist/external-sync/providers/linear/linear-api.js

@@ -0,0 +1,522 @@
+/**
+ * Linear GraphQL API Client
+ *
+ * Pure fetch-based client for Linear issue operations via GraphQL.
+ * Supports API key authentication, rate limit handling, cursor pagination,
+ * and typed error responses.
+ *
+ * No external dependencies — uses only the standard fetch API.
+ *
+ * @see https://developers.linear.app/docs/graphql/working-with-the-graphql-api
+ */
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * Typed error for Linear API failures.
+ * Wraps fetch errors with status code, GraphQL errors, and rate limit info.
+ */
+export class LinearApiError extends Error {
+    /** HTTP status code from Linear's response */
+    status;
+    /** GraphQL errors from the response (if any) */
+    graphqlErrors;
+    /** Rate limit information at the time of the error */
+    rateLimit;
+    constructor(message, status, graphqlErrors = [], rateLimit = null, cause) {
+        super(message);
+        this.name = 'LinearApiError';
+        this.status = status;
+        this.graphqlErrors = graphqlErrors;
+        this.rateLimit = rateLimit;
+        this.cause = cause;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, LinearApiError);
+        }
+    }
+    /**
+     * Whether this error is due to rate limiting.
+     */
+    get isRateLimited() {
+        return this.status === 429 || (this.rateLimit !== null && this.rateLimit.remaining === 0);
+    }
+    /**
+     * Whether this error is due to authentication failure.
+     */
+    get isAuthError() {
+        return this.status === 401;
+    }
+    /**
+     * Returns a JSON-serializable representation of the error.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            status: this.status,
+            graphqlErrors: this.graphqlErrors,
+            rateLimit: this.rateLimit,
+        };
+    }
+}
+/**
+ * Type guard for LinearApiError.
+ */
+export function isLinearApiError(error) {
+    return error instanceof LinearApiError;
+}
+// ============================================================================
+// Constants
+// ============================================================================
+/** Linear GraphQL API endpoint */
+const LINEAR_API_URL = 'https://api.linear.app/graphql';
+/** Default threshold of remaining requests before logging a warning */
+const DEFAULT_RATE_LIMIT_WARNING_THRESHOLD = 100;
+/** Common issue fields fragment for GraphQL queries */
+const ISSUE_FIELDS = `
+  id
+  identifier
+  title
+  description
+  priority
+  url
+  state {
+    id
+    name
+    type
+  }
+  assignee {
+    id
+    name
+    email
+  }
+  team {
+    id
+    key
+    name
+  }
+  labels {
+    nodes {
+      id
+      name
+    }
+  }
+  createdAt
+  updatedAt
+  archivedAt
+`;
+// ============================================================================
+// Client Implementation
+// ============================================================================
+/**
+ * Fetch-based Linear GraphQL API client for issue operations.
+ *
+ * Features:
+ * - API key authentication (no Bearer prefix)
+ * - Rate limit tracking with warnings when approaching limit
+ * - Typed errors with GraphQL error details
+ * - Relay-style cursor pagination
+ * - Partial error handling (data + errors)
+ *
+ * @example
+ * ```typescript
+ * const client = new LinearApiClient({ apiKey: 'lin_api_...' });
+ * const viewer = await client.getViewer();
+ * const issues = await client.listIssuesSince('ENG', '2024-01-01T00:00:00Z');
+ * ```
+ */
+export class LinearApiClient {
+    apiKey;
+    rateLimitWarningThreshold;
+    /** Most recently observed rate limit info (updated after each request) */
+    lastRateLimit = null;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('Linear API key is required');
+        }
+        this.apiKey = options.apiKey;
+        this.rateLimitWarningThreshold =
+            options.rateLimitWarningThreshold ?? DEFAULT_RATE_LIMIT_WARNING_THRESHOLD;
+    }
+    /**
+     * Returns the most recently observed rate limit info, or null if no requests have been made.
+     */
+    getRateLimit() {
+        return this.lastRateLimit;
+    }
+    // --------------------------------------------------------------------------
+    // Core GraphQL Method
+    // --------------------------------------------------------------------------
+    /**
+     * Performs a GraphQL request to the Linear API.
+     *
+     * Handles authentication, rate limit parsing, and error responses.
+     * For 200 responses that include both `data` and `errors`, it logs warnings
+     * for partial errors but returns the data.
+     *
+     * @throws {LinearApiError} On network errors, non-200 responses, or responses with only errors.
+     */
+    async graphql(query, variables) {
+        let response;
+        try {
+            response = await fetch(LINEAR_API_URL, {
+                method: 'POST',
+                headers: {
+                    Authorization: this.apiKey,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ query, variables }),
+            });
+        }
+        catch (err) {
+            throw new LinearApiError(`Network error requesting Linear API: ${err instanceof Error ? err.message : String(err)}`, 0, [], null, err instanceof Error ? err : undefined);
+        }
+        // Parse rate limit headers from every response
+        const rateLimit = parseRateLimitHeaders(response.headers);
+        if (rateLimit) {
+            this.lastRateLimit = rateLimit;
+            this.checkRateLimitWarning(rateLimit);
+        }
+        // Handle non-200 HTTP responses
+        if (!response.ok) {
+            let errorMessage;
+            let graphqlErrors = [];
+            try {
+                const body = (await response.json());
+                graphqlErrors = body.errors ?? [];
+                errorMessage =
+                    graphqlErrors.length > 0
+                        ? graphqlErrors.map((e) => e.message).join('; ')
+                        : body.message ?? `Linear API error: ${response.status} ${response.statusText}`;
+            }
+            catch {
+                errorMessage = `Linear API error: ${response.status} ${response.statusText}`;
+            }
+            // Special messaging for rate limit exhaustion
+            if (response.status === 429 || (rateLimit && rateLimit.remaining === 0)) {
+                const resetDate = rateLimit ? new Date(rateLimit.reset * 1000).toISOString() : 'unknown';
+                errorMessage = `Linear API rate limit exhausted. Resets at ${resetDate}. ${errorMessage}`;
+            }
+            throw new LinearApiError(`Linear GraphQL request failed: ${errorMessage}`, response.status, graphqlErrors, rateLimit);
+        }
+        // Parse JSON response
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch (err) {
+            throw new LinearApiError(`Failed to parse Linear API response as JSON: ${err instanceof Error ? err.message : String(err)}`, response.status, [], rateLimit, err instanceof Error ? err : undefined);
+        }
+        // Handle GraphQL errors
+        if (body.errors && body.errors.length > 0) {
+            if (!body.data) {
+                // Complete failure — no data returned
+                throw new LinearApiError(`Linear GraphQL errors: ${body.errors.map((e) => e.message).join('; ')}`, response.status, body.errors, rateLimit);
+            }
+            // Partial errors — data exists alongside errors. Log warning but return data.
+            console.warn(`[LinearApiClient] Partial GraphQL errors: ${body.errors.map((e) => e.message).join('; ')}`);
+        }
+        if (!body.data) {
+            throw new LinearApiError('Linear API returned a response with no data', response.status, body.errors ?? [], rateLimit);
+        }
+        return body.data;
+    }
+    // --------------------------------------------------------------------------
+    // Public API Methods
+    // --------------------------------------------------------------------------
+    /**
+     * Fetch the authenticated user's identity.
+     * Useful for testing the API connection.
+     *
+     * @returns Viewer info with id, name, and email.
+     */
+    async getViewer() {
+        const query = `
+      query Viewer {
+        viewer {
+          id
+          name
+          email
+        }
+      }
+    `;
+        const data = await this.graphql(query);
+        return data.viewer;
+    }
+    /**
+     * List all teams accessible to the authenticated user.
+     *
+     * @returns Array of teams with id, key, and name.
+     */
+    async getTeams() {
+        const query = `
+      query Teams {
+        teams {
+          nodes {
+            id
+            key
+            name
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(query);
+        return data.teams.nodes;
+    }
+    /**
+     * Fetch all workflow states for a specific team.
+     * Needed for mapping between Linear state types and Stoneforge statuses.
+     *
+     * @param teamId - UUID of the team.
+     * @returns Array of workflow states.
+     */
+    async getTeamWorkflowStates(teamId) {
+        const query = `
+      query TeamWorkflowStates($teamId: String!) {
+        team(id: $teamId) {
+          states {
+            nodes {
+              id
+              name
+              type
+            }
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(query, { teamId });
+        return data.team.states.nodes;
+    }
+    /**
+     * Fetch all labels (issue labels) in the workspace.
+     * Labels in Linear are workspace-scoped and can be filtered by team.
+     *
+     * @returns Array of all labels with id and name.
+     */
+    async getLabels() {
+        const query = `
+      query IssueLabels {
+        issueLabels {
+          nodes {
+            id
+            name
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(query);
+        return data.issueLabels.nodes;
+    }
+    /**
+     * Create a new label in the workspace, optionally associated with a team.
+     *
+     * @param name - Label name (e.g., "blocked")
+     * @param teamId - Optional team ID to associate the label with
+     * @returns The created label with id and name.
+     */
+    async createLabel(name, teamId) {
+        const query = `
+      mutation CreateLabel($input: IssueLabelCreateInput!) {
+        issueLabelCreate(input: $input) {
+          success
+          issueLabel {
+            id
+            name
+          }
+        }
+      }
+    `;
+        const input = { name };
+        if (teamId) {
+            input.teamId = teamId;
+        }
+        const data = await this.graphql(query, { input });
+        if (!data.issueLabelCreate.success) {
+            throw new LinearApiError(`Linear issueLabelCreate mutation returned success: false for label "${name}"`, 200, [], this.lastRateLimit);
+        }
+        return data.issueLabelCreate.issueLabel;
+    }
+    /**
+     * Fetch a single issue by UUID or identifier (e.g., "ENG-123").
+     *
+     * @param issueId - UUID or human-readable identifier.
+     * @returns The issue, or null if not found.
+     */
+    async getIssue(issueId) {
+        const query = `
+      query Issue($issueId: String!) {
+        issue(id: $issueId) {
+          ${ISSUE_FIELDS}
+        }
+      }
+    `;
+        try {
+            const data = await this.graphql(query, { issueId });
+            return data.issue;
+        }
+        catch (err) {
+            // Linear returns errors for not-found issues rather than null
+            if (err instanceof LinearApiError && err.graphqlErrors.length > 0) {
+                const notFound = err.graphqlErrors.some((e) => e.message.toLowerCase().includes('not found') ||
+                    e.extensions?.code === 'RESOURCE_NOT_FOUND');
+                if (notFound) {
+                    return null;
+                }
+            }
+            throw err;
+        }
+    }
+    /**
+     * List issues for a team updated since a given timestamp.
+     * Automatically paginates through all results using cursor pagination.
+     *
+     * @param teamKey - Team key (e.g., "ENG").
+     * @param since - ISO 8601 timestamp. Only issues updated at or after this time are returned.
+     * @returns Array of all matching issues.
+     */
+    async listIssuesSince(teamKey, since) {
+        const query = `
+      query ListIssues($teamKey: String!, $since: DateTimeOrDuration!, $after: String) {
+        issues(
+          filter: {
+            team: { key: { eq: $teamKey } }
+            updatedAt: { gte: $since }
+          }
+          first: 50
+          after: $after
+        ) {
+          nodes {
+            ${ISSUE_FIELDS}
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `;
+        const allIssues = [];
+        let after = null;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const variables = { teamKey, since };
+            if (after) {
+                variables.after = after;
+            }
+            const data = await this.graphql(query, variables);
+            allIssues.push(...data.issues.nodes);
+            if (!data.issues.pageInfo.hasNextPage) {
+                break;
+            }
+            after = data.issues.pageInfo.endCursor;
+        }
+        return allIssues;
+    }
+    /**
+     * Create a new issue in Linear.
+     *
+     * @param input - Issue creation input (teamId and title required).
+     * @returns The created issue.
+     */
+    async createIssue(input) {
+        const query = `
+      mutation CreateIssue($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+          success
+          issue {
+            ${ISSUE_FIELDS}
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(query, { input });
+        if (!data.issueCreate.success) {
+            throw new LinearApiError('Linear issueCreate mutation returned success: false', 200, [], this.lastRateLimit);
+        }
+        return data.issueCreate.issue;
+    }
+    /**
+     * Update an existing issue in Linear.
+     *
+     * @param issueId - UUID of the issue to update.
+     * @param input - Fields to update.
+     * @returns The updated issue.
+     */
+    async updateIssue(issueId, input) {
+        const query = `
+      mutation UpdateIssue($issueId: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $issueId, input: $input) {
+          success
+          issue {
+            ${ISSUE_FIELDS}
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(query, { issueId, input });
+        if (!data.issueUpdate.success) {
+            throw new LinearApiError('Linear issueUpdate mutation returned success: false', 200, [], this.lastRateLimit);
+        }
+        return data.issueUpdate.issue;
+    }
+    // --------------------------------------------------------------------------
+    // Internal: Rate Limit Handling
+    // --------------------------------------------------------------------------
+    /**
+     * Logs a warning when rate limit is approaching exhaustion.
+     */
+    checkRateLimitWarning(rateLimit) {
+        if (rateLimit.remaining <= this.rateLimitWarningThreshold && rateLimit.remaining > 0) {
+            const resetDate = new Date(rateLimit.reset * 1000);
+            console.warn(`[LinearApiClient] Rate limit warning: ${rateLimit.remaining}/${rateLimit.limit} requests remaining. ` +
+                `Resets at ${resetDate.toISOString()}.`);
+        }
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Parses rate limit information from Linear response headers.
+ *
+ * Linear uses these headers:
+ * - X-RateLimit-Requests-Limit
+ * - X-RateLimit-Requests-Remaining
+ * - X-RateLimit-Requests-Reset (epoch seconds)
+ *
+ * Also checks standard headers as fallback:
+ * - X-RateLimit-Limit
+ * - X-RateLimit-Remaining
+ * - X-RateLimit-Reset
+ *
+ * @returns Parsed rate limit info, or null if headers are not present.
+ */
+function parseRateLimitHeaders(headers) {
+    // Try Linear-specific headers first
+    let limit = headers.get('X-RateLimit-Requests-Limit');
+    let remaining = headers.get('X-RateLimit-Requests-Remaining');
+    let reset = headers.get('X-RateLimit-Requests-Reset');
+    // Fall back to standard headers
+    if (limit === null || remaining === null || reset === null) {
+        limit = headers.get('X-RateLimit-Limit');
+        remaining = headers.get('X-RateLimit-Remaining');
+        reset = headers.get('X-RateLimit-Reset');
+    }
+    if (limit === null || remaining === null || reset === null) {
+        return null;
+    }
+    const parsedLimit = parseInt(limit, 10);
+    const parsedRemaining = parseInt(remaining, 10);
+    const parsedReset = parseInt(reset, 10);
+    if (isNaN(parsedLimit) || isNaN(parsedRemaining) || isNaN(parsedReset)) {
+        return null;
+    }
+    return {
+        limit: parsedLimit,
+        remaining: parsedRemaining,
+        reset: parsedReset,
+    };
+}
+// Export utility function for testing
+export { parseRateLimitHeaders };
+//# sourceMappingURL=linear-api.js.map

package/dist/external-sync/providers/linear/linear-api.js.map

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

package/dist/external-sync/providers/linear/linear-field-map.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Linear Field Mapping Configuration
+ *
+ * Defines how Stoneforge task fields map to Linear issue fields.
+ *
+ * Key differences from GitHub:
+ * - Linear has native priority (0-4) — no label-based priority convention needed
+ * - Linear has workflow state types — status mapping uses state types, not labels
+ * - Task types use the same label convention as GitHub (type:bug, etc.)
+ *
+ * Priority mapping (Linear 0-4 ↔ Stoneforge 1-5):
+ *   Linear 1 (Urgent)      ↔ Stoneforge 1 (critical)
+ *   Linear 2 (High)        ↔ Stoneforge 2 (high)
+ *   Linear 3 (Medium)      ↔ Stoneforge 3 (medium)
+ *   Linear 4 (Low)         ↔ Stoneforge 4 (low)
+ *   Linear 0 (No priority) ↔ Stoneforge 5 (minimal)
+ *
+ * Status mapping via workflow state TYPE (not name):
+ *   Pull: triage/backlog → backlog, unstarted → open, started → in_progress,
+ *         completed → closed, canceled → closed (closeReason: "canceled")
+ *   Push: open → unstarted, in_progress/review → started,
+ *         blocked → started (add "blocked" label), deferred/backlog → backlog,
+ *         closed → completed
+ */
+import type { TaskStatus, Priority } from '@stoneforge/core';
+import type { TaskFieldMapConfig } from '@stoneforge/core';
+import type { TaskSyncFieldMapConfig } from '../../adapters/task-sync-adapter.js';
+import type { LinearWorkflowState } from './linear-types.js';
+/**
+ * Maps Stoneforge TaskStatus values to label strings.
+ * Linear doesn't natively use label-based status, but the adapter injects
+ * sf:status:* labels into ExternalTask.labels to communicate granular workflow
+ * state types through the generic field mapping system.
+ *
+ * This keeps the sync engine provider-agnostic — it reads status from labels
+ * the same way for both GitHub (user-managed labels) and Linear (adapter-injected).
+ */
+export declare const LINEAR_STATUS_LABELS: Record<string, string>;
+/**
+ * Maps Stoneforge priority (1-5) to Linear priority (0-4).
+ *
+ * Stoneforge 1 (critical) → Linear 1 (Urgent)
+ * Stoneforge 2 (high)     → Linear 2 (High)
+ * Stoneforge 3 (medium)   → Linear 3 (Medium)
+ * Stoneforge 4 (low)      → Linear 4 (Low)
+ * Stoneforge 5 (minimal)  → Linear 0 (No priority)
+ */
+export declare function stoneforgePriorityToLinear(priority: Priority): number;
+/**
+ * Maps Linear priority (0-4) to Stoneforge priority (1-5).
+ *
+ * Linear 1 (Urgent)      → Stoneforge 1 (critical)
+ * Linear 2 (High)        → Stoneforge 2 (high)
+ * Linear 3 (Medium)      → Stoneforge 3 (medium)
+ * Linear 4 (Low)         → Stoneforge 4 (low)
+ * Linear 0 (No priority) → Stoneforge 5 (minimal)
+ */
+export declare function linearPriorityToStoneforge(priority: number): Priority;
+/**
+ * Linear workflow state type as used in the API.
+ */
+export type LinearStateType = LinearWorkflowState['type'];
+/**
+ * Maps a Linear workflow state type to a Stoneforge TaskStatus.
+ *
+ * Pull direction:
+ *   triage    → backlog
+ *   backlog   → backlog
+ *   unstarted → open
+ *   started   → in_progress
+ *   completed → closed
+ *   canceled  → closed
+ */
+export declare function linearStateTypeToStatus(stateType: LinearStateType): {
+    status: TaskStatus;
+    closeReason?: string;
+};
+/**
+ * Maps a Stoneforge TaskStatus to a Linear workflow state type.
+ *
+ * Push direction:
+ *   open        → unstarted
+ *   in_progress → started
+ *   review      → started
+ *   blocked     → started (caller should add "blocked" label)
+ *   deferred    → backlog
+ *   backlog     → backlog
+ *   closed      → completed
+ *   tombstone   → completed (treat as done)
+ */
+export declare function statusToLinearStateType(status: TaskStatus): LinearStateType;
+/**
+ * Returns true if the given Stoneforge status should add a "blocked" label
+ * in Linear (since Linear has no native blocked state).
+ */
+export declare function shouldAddBlockedLabel(status: TaskStatus): boolean;
+/**
+ * Maps a Linear workflow state type to a sync label string (sf:status:*).
+ *
+ * The Linear adapter injects this label into ExternalTask.labels so the
+ * generic field mapping system (stateToStatus) can extract granular statuses
+ * without the sync engine needing to know about Linear-specific state types.
+ *
+ * Mapping:
+ *   triage    → sf:status:backlog
+ *   backlog   → sf:status:backlog
+ *   unstarted → sf:status:open
+ *   started   → sf:status:in-progress
+ *   completed → sf:status:closed
+ *   canceled  → sf:status:closed
+ */
+export declare function linearStateTypeToStatusLabel(stateType: LinearStateType): string;
+/**
+ * Creates the Linear-specific TaskFieldMapConfig.
+ *
+ * This config describes the field mapping at the type level. The actual
+ * runtime mapping logic lives in the adapter and the priority/status
+ * functions above.
+ */
+export declare function createLinearFieldMapConfig(): TaskFieldMapConfig;
+/**
+ * Creates the Linear-specific TaskSyncFieldMapConfig used by the shared
+ * task-sync-adapter utilities (taskToExternalTask, externalTaskToTaskUpdates).
+ *
+ * Priority labels are emitted alongside Linear's native priority field for
+ * lossless round-tripping. This ensures the exact Stoneforge priority value
+ * is preserved (e.g., P5 "minimal" is distinct from Linear's "No priority").
+ *
+ * Status mapping uses adapter-injected sf:status:* labels. The Linear adapter
+ * injects these labels based on the workflow state type (e.g., started →
+ * sf:status:in-progress), allowing the generic stateToStatus function to
+ * extract granular statuses without coupling the sync engine to Linear.
+ */
+export declare function createLinearSyncFieldMapConfig(): TaskSyncFieldMapConfig;
+//# sourceMappingURL=linear-field-map.d.ts.map

package/dist/external-sync/providers/linear/linear-field-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear-field-map.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/linear/linear-field-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAM7D;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASvD,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAerE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAerE;AAMD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,eAAe,GAAG;IACnE,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAiBA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,eAAe,CAqB3E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAiB/E;AAMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,kBAAkB,CAiD/D;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,IAAI,sBAAsB,CAgEvE"}