cortex-agents 2.3.1 → 4.0.0

package/dist/utils/change-scope.js

@@ -0,0 +1,198 @@
+/**
+ * Change Scope Detection
+ *
+ * Categorizes changed files by risk level to determine which sub-agents
+ * should be triggered during the quality gate. Avoids wasting tokens on
+ * trivial changes while ensuring high-risk changes get full coverage.
+ */
+// ─── File Pattern Matchers ───────────────────────────────────────────────────
+/** Patterns that indicate trivial changes — docs, comments, formatting only */
+const TRIVIAL_PATTERNS = [
+    /\.md$/i,
+    /\.txt$/i,
+    /\.mdx$/i,
+    /LICENSE/i,
+    /CHANGELOG/i,
+    /\.prettierrc/,
+    /\.editorconfig/,
+    /\.vscode\//,
+    /\.idea\//,
+];
+/** Patterns that indicate test/config-only changes — low risk */
+const LOW_RISK_PATTERNS = [
+    /\.test\.[jt]sx?$/,
+    /\.spec\.[jt]sx?$/,
+    /__tests__\//,
+    /test\//,
+    /tests\//,
+    /\.eslintrc/,
+    /\.prettierrc/,
+    /tsconfig.*\.json$/,
+    /jest\.config/,
+    /vitest\.config/,
+    /\.gitignore$/,
+];
+/** Patterns that indicate high-risk changes — auth, payments, infra, security */
+const HIGH_RISK_PATTERNS = [
+    // Auth & security
+    /auth/i,
+    /login/i,
+    /session/i,
+    /password/i,
+    /token/i,
+    /crypto/i,
+    /encrypt/i,
+    /permission/i,
+    /rbac/i,
+    /oauth/i,
+    /jwt/i,
+    /middleware\/auth/i,
+    // Payment & sensitive data
+    /payment/i,
+    /billing/i,
+    /stripe/i,
+    /checkout/i,
+    // Infrastructure & deployment
+    /Dockerfile/i,
+    /docker-compose/i,
+    /\.github\/workflows\//,
+    /\.gitlab-ci/,
+    /Jenkinsfile/i,
+    /\.circleci\//,
+    /terraform\//,
+    /pulumi\//,
+    /k8s\//,
+    /deploy\//,
+    /infra\//,
+    /nginx\.conf/i,
+    /Caddyfile/i,
+    /Procfile/i,
+    /fly\.toml/i,
+];
+/** Patterns that indicate DevOps file changes */
+const DEVOPS_PATTERNS = [
+    /Dockerfile/i,
+    /docker-compose/i,
+    /\.dockerignore/i,
+    /\.github\/workflows\//,
+    /\.gitlab-ci/,
+    /Jenkinsfile/i,
+    /\.circleci\//,
+    /terraform\//,
+    /pulumi\//,
+    /cdk\//,
+    /k8s\//,
+    /deploy\//,
+    /infra\//,
+    /nginx\.conf/i,
+    /Caddyfile/i,
+    /Procfile/i,
+    /fly\.toml/i,
+    /railway\.json/i,
+    /render\.yaml/i,
+];
+/** Patterns that indicate performance-sensitive changes */
+const PERF_PATTERNS = [
+    /query/i,
+    /database/i,
+    /migration/i,
+    /\.sql$/i,
+    /prisma/i,
+    /drizzle/i,
+    /repository/i,
+    /cache/i,
+    /render/i,
+    /component/i,
+    /hook/i,
+    /algorithm/i,
+    /sort/i,
+    /search/i,
+    /index/i,
+    /worker/i,
+    /stream/i,
+    /batch/i,
+    /queue/i,
+];
+// ─── Classification ──────────────────────────────────────────────────────────
+/**
+ * Classify a set of changed files into a risk scope and determine
+ * which sub-agents should be triggered.
+ *
+ * @param changedFiles - Array of file paths that were created or modified
+ * @returns Classification result with scope, rationale, and agent triggers
+ */
+export function classifyChangeScope(changedFiles) {
+    if (changedFiles.length === 0) {
+        return {
+            scope: "trivial",
+            rationale: "No files changed",
+            agents: noAgents(),
+        };
+    }
+    const hasHighRisk = changedFiles.some((f) => HIGH_RISK_PATTERNS.some((p) => p.test(f)));
+    const hasDevOps = changedFiles.some((f) => DEVOPS_PATTERNS.some((p) => p.test(f)));
+    const hasPerf = changedFiles.some((f) => PERF_PATTERNS.some((p) => p.test(f)));
+    const allTrivial = changedFiles.every((f) => TRIVIAL_PATTERNS.some((p) => p.test(f)));
+    const allLowRisk = changedFiles.every((f) => LOW_RISK_PATTERNS.some((p) => p.test(f)) || TRIVIAL_PATTERNS.some((p) => p.test(f)));
+    // Trivial — docs/comments only
+    if (allTrivial) {
+        return {
+            scope: "trivial",
+            rationale: "Documentation/formatting changes only — no quality gate needed",
+            agents: {
+                ...noAgents(),
+                docsWriter: true,
+            },
+        };
+    }
+    // Low risk — tests/config only
+    if (allLowRisk) {
+        return {
+            scope: "low",
+            rationale: "Test/config changes only — minimal quality gate",
+            agents: {
+                ...noAgents(),
+                testing: true,
+            },
+        };
+    }
+    // High risk — auth, payments, infra
+    if (hasHighRisk) {
+        return {
+            scope: "high",
+            rationale: "High-risk changes detected (auth/security/payments/infra) — full quality gate",
+            agents: {
+                testing: true,
+                security: true,
+                audit: true,
+                devops: hasDevOps,
+                perf: hasPerf,
+                docsWriter: true,
+            },
+        };
+    }
+    // Standard — everything else
+    return {
+        scope: "standard",
+        rationale: "Standard code changes — normal quality gate",
+        agents: {
+            testing: true,
+            security: true,
+            audit: true,
+            devops: hasDevOps,
+            perf: hasPerf,
+            docsWriter: true,
+        },
+    };
+}
+/** Helper: no agents triggered */
+function noAgents() {
+    return {
+        testing: false,
+        security: false,
+        audit: false,
+        devops: false,
+        perf: false,
+        docsWriter: false,
+    };
+}

package/dist/utils/github.d.ts

@@ -0,0 +1,104 @@
+export interface GhStatus {
+    installed: boolean;
+    authenticated: boolean;
+    hasRemote: boolean;
+    repoOwner?: string;
+    repoName?: string;
+    projects: {
+        id: string;
+        number: number;
+        title: string;
+    }[];
+}
+export interface GitHubIssue {
+    number: number;
+    title: string;
+    state: string;
+    labels: string[];
+    assignees: string[];
+    milestone?: string;
+    body: string;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GitHubProjectItem {
+    id: string;
+    title: string;
+    type: "ISSUE" | "PULL_REQUEST" | "DRAFT_ISSUE";
+    status?: string;
+    assignees: string[];
+    labels: string[];
+    issueNumber?: number;
+    url?: string;
+    body?: string;
+}
+/**
+ * Check full GitHub CLI availability and repo context.
+ * Returns a status object with installation, authentication, and repo info.
+ */
+export declare function checkGhAvailability(cwd: string): Promise<GhStatus>;
+/**
+ * Parse a git remote URL to extract owner and repo name.
+ * Handles HTTPS, SSH, and GitHub CLI formats.
+ * Supports both github.com and GitHub Enterprise Server URLs (e.g., github.mycompany.com).
+ *
+ * The regex requires "github" to appear at a hostname boundary (after `//` or `@`)
+ * to prevent false positives like "notgithub.com" or "fakegithub.evil.com".
+ */
+export declare function parseRepoUrl(url: string): {
+    owner: string;
+    name: string;
+} | null;
+/**
+ * Truncate a string to the given length, appending "..." if truncated.
+ */
+export declare function truncate(str: string, maxLen: number): string;
+/**
+ * Format a single GitHub issue into a compact list entry.
+ * Used when presenting multiple issues for selection.
+ */
+export declare function formatIssueListEntry(issue: GitHubIssue): string;
+/**
+ * Format multiple issues into a numbered selection list.
+ */
+export declare function formatIssueList(issues: GitHubIssue[]): string;
+/**
+ * Format a GitHub issue into a planning-friendly markdown block.
+ * Used by the architect agent to seed plan content from selected issues.
+ */
+export declare function formatIssueForPlan(issue: GitHubIssue): string;
+/**
+ * Format a single GitHub Project item into a compact list entry.
+ */
+export declare function formatProjectItemEntry(item: GitHubProjectItem): string;
+/**
+ * Format multiple project items into a list.
+ */
+export declare function formatProjectItemList(items: GitHubProjectItem[]): string;
+/**
+ * Fetch GitHub projects associated with the repo owner.
+ */
+export declare function fetchProjects(cwd: string, owner: string): Promise<{
+    id: string;
+    number: number;
+    title: string;
+}[]>;
+/**
+ * Fetch issues from the current repository using gh CLI.
+ */
+export declare function fetchIssues(cwd: string, options?: {
+    state?: string;
+    labels?: string;
+    milestone?: string;
+    assignee?: string;
+    limit?: number;
+}): Promise<GitHubIssue[]>;
+/**
+ * Fetch project items from a specific GitHub Project.
+ */
+export declare function fetchProjectItems(cwd: string, owner: string, projectNumber: number, options?: {
+    status?: string;
+    limit?: number;
+}): Promise<GitHubProjectItem[]>;
+//# sourceMappingURL=github.d.ts.map

package/dist/utils/github.d.ts.map

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

package/dist/utils/github.js

@@ -0,0 +1,243 @@
+import { gh, which, git } from "./shell.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Maximum character length for issue body in list views to avoid overwhelming context. */
+const BODY_TRUNCATE_LENGTH = 200;
+/** Maximum character length for issue body in detail views (plan formatting). */
+const BODY_DETAIL_LENGTH = 2000;
+// ─── GitHub CLI Availability ─────────────────────────────────────────────────
+/**
+ * Check full GitHub CLI availability and repo context.
+ * Returns a status object with installation, authentication, and repo info.
+ */
+export async function checkGhAvailability(cwd) {
+    const status = {
+        installed: false,
+        authenticated: false,
+        hasRemote: false,
+        projects: [],
+    };
+    // 1. Check if gh is installed
+    const ghPath = await which("gh");
+    if (!ghPath)
+        return status;
+    status.installed = true;
+    // 2. Check if authenticated
+    try {
+        await gh(cwd, "auth", "status");
+        status.authenticated = true;
+    }
+    catch {
+        return status;
+    }
+    // 3. Extract repo owner/name from remote
+    try {
+        const { stdout } = await git(cwd, "remote", "get-url", "origin");
+        const parsed = parseRepoUrl(stdout.trim());
+        if (parsed) {
+            status.hasRemote = true;
+            status.repoOwner = parsed.owner;
+            status.repoName = parsed.name;
+        }
+    }
+    catch {
+        // No remote configured — hasRemote stays false
+    }
+    return status;
+}
+/**
+ * Parse a git remote URL to extract owner and repo name.
+ * Handles HTTPS, SSH, and GitHub CLI formats.
+ * Supports both github.com and GitHub Enterprise Server URLs (e.g., github.mycompany.com).
+ *
+ * The regex requires "github" to appear at a hostname boundary (after `//` or `@`)
+ * to prevent false positives like "notgithub.com" or "fakegithub.evil.com".
+ */
+export function parseRepoUrl(url) {
+    // HTTPS: https://github.com/owner/repo.git  OR  https://github.mycompany.com/owner/repo.git
+    // The `//` anchor ensures "github" is at the start of the hostname, not mid-word.
+    const httpsMatch = url.match(/\/\/github[^/]*\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], name: httpsMatch[2] };
+    }
+    // SSH: git@github.com:owner/repo.git  OR  git@github.mycompany.com:owner/repo.git
+    // The `git@` prefix already anchors to the hostname start.
+    const sshMatch = url.match(/git@github[^:]*:([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (sshMatch) {
+        return { owner: sshMatch[1], name: sshMatch[2] };
+    }
+    return null;
+}
+// ─── Issue Formatting ────────────────────────────────────────────────────────
+/**
+ * Truncate a string to the given length, appending "..." if truncated.
+ */
+export function truncate(str, maxLen) {
+    if (!str)
+        return "";
+    if (str.length <= maxLen)
+        return str;
+    return str.substring(0, maxLen).trimEnd() + "...";
+}
+/**
+ * Format a single GitHub issue into a compact list entry.
+ * Used when presenting multiple issues for selection.
+ */
+export function formatIssueListEntry(issue) {
+    const labels = issue.labels.length > 0 ? ` [${issue.labels.join(", ")}]` : "";
+    const assignees = issue.assignees.length > 0 ? ` → ${issue.assignees.join(", ")}` : "";
+    const body = issue.body ? `\n   ${truncate(issue.body.replace(/\n/g, " "), BODY_TRUNCATE_LENGTH)}` : "";
+    return `#${issue.number}: ${issue.title}${labels}${assignees}${body}`;
+}
+/**
+ * Format multiple issues into a numbered selection list.
+ */
+export function formatIssueList(issues) {
+    if (issues.length === 0)
+        return "No issues found.";
+    return issues.map((issue) => formatIssueListEntry(issue)).join("\n\n");
+}
+/**
+ * Format a GitHub issue into a planning-friendly markdown block.
+ * Used by the architect agent to seed plan content from selected issues.
+ */
+export function formatIssueForPlan(issue) {
+    const parts = [];
+    parts.push(`### Issue #${issue.number}: ${issue.title}`);
+    parts.push("");
+    if (issue.labels.length > 0) {
+        parts.push(`**Labels:** ${issue.labels.join(", ")}`);
+    }
+    if (issue.assignees.length > 0) {
+        parts.push(`**Assignees:** ${issue.assignees.join(", ")}`);
+    }
+    if (issue.milestone) {
+        parts.push(`**Milestone:** ${issue.milestone}`);
+    }
+    parts.push(`**URL:** ${issue.url}`);
+    parts.push("");
+    if (issue.body) {
+        parts.push("**Description:**");
+        parts.push("");
+        parts.push(truncate(issue.body, BODY_DETAIL_LENGTH));
+    }
+    return parts.join("\n");
+}
+// ─── Project Item Formatting ─────────────────────────────────────────────────
+/**
+ * Format a single GitHub Project item into a compact list entry.
+ */
+export function formatProjectItemEntry(item) {
+    const status = item.status ? ` (${item.status})` : "";
+    const type = item.type === "DRAFT_ISSUE" ? " [Draft]" : item.type === "PULL_REQUEST" ? " [PR]" : "";
+    const labels = item.labels.length > 0 ? ` [${item.labels.join(", ")}]` : "";
+    const assignees = item.assignees.length > 0 ? ` → ${item.assignees.join(", ")}` : "";
+    const ref = item.issueNumber ? `#${item.issueNumber}: ` : "";
+    return `${ref}${item.title}${type}${status}${labels}${assignees}`;
+}
+/**
+ * Format multiple project items into a list.
+ */
+export function formatProjectItemList(items) {
+    if (items.length === 0)
+        return "No project items found.";
+    return items.map((item) => formatProjectItemEntry(item)).join("\n");
+}
+// ─── GitHub CLI Data Fetching ────────────────────────────────────────────────
+/**
+ * Fetch GitHub projects associated with the repo owner.
+ */
+export async function fetchProjects(cwd, owner) {
+    try {
+        const { stdout } = await gh(cwd, "project", "list", "--owner", owner, "--format", "json");
+        const parsed = JSON.parse(stdout);
+        // gh project list --format json returns { projects: [...] }
+        const projects = parsed.projects ?? parsed ?? [];
+        return projects.map((p) => ({
+            id: String(p.id ?? ""),
+            number: Number(p.number ?? 0),
+            title: String(p.title ?? "Untitled"),
+        }));
+    }
+    catch (error) {
+        // Surface auth errors — these are actionable for the user.
+        // Other errors (no projects, API format changes) are non-critical.
+        const msg = error?.message ?? String(error);
+        if (msg.includes("auth") || msg.includes("401") || msg.includes("403")) {
+            throw new Error(`GitHub authentication error while fetching projects: ${msg}`);
+        }
+        return [];
+    }
+}
+/**
+ * Fetch issues from the current repository using gh CLI.
+ */
+export async function fetchIssues(cwd, options = {}) {
+    const args = [
+        "issue", "list",
+        "--json", "number,title,state,labels,assignees,milestone,body,url,createdAt,updatedAt",
+        "--limit", String(options.limit ?? 20),
+    ];
+    if (options.state)
+        args.push("--state", options.state);
+    if (options.labels)
+        args.push("--label", options.labels);
+    if (options.milestone)
+        args.push("--milestone", options.milestone);
+    if (options.assignee)
+        args.push("--assignee", options.assignee);
+    const { stdout } = await gh(cwd, ...args);
+    const raw = JSON.parse(stdout);
+    return raw.map((item) => ({
+        number: item.number,
+        title: item.title ?? "",
+        state: item.state ?? "open",
+        labels: (item.labels ?? []).map((l) => (typeof l === "string" ? l : l.name ?? "")),
+        assignees: (item.assignees ?? []).map((a) => (typeof a === "string" ? a : a.login ?? "")),
+        milestone: item.milestone?.title ?? undefined,
+        body: item.body ?? "",
+        url: item.url ?? "",
+        createdAt: item.createdAt ?? "",
+        updatedAt: item.updatedAt ?? "",
+    }));
+}
+/**
+ * Fetch project items from a specific GitHub Project.
+ */
+export async function fetchProjectItems(cwd, owner, projectNumber, options = {}) {
+    const { stdout } = await gh(cwd, "project", "item-list", String(projectNumber), "--owner", owner, "--format", "json", "--limit", String(options.limit ?? 30));
+    const parsed = JSON.parse(stdout);
+    // gh project item-list --format json returns { items: [...] }
+    const raw = parsed.items ?? parsed ?? [];
+    const items = raw.map((item) => ({
+        id: String(item.id ?? ""),
+        title: item.title ?? "",
+        type: normalizeItemType(item.type),
+        status: item.status ?? undefined,
+        assignees: Array.isArray(item.assignees)
+            ? item.assignees.map((a) => (typeof a === "string" ? a : a.login ?? ""))
+            : [],
+        labels: Array.isArray(item.labels)
+            ? item.labels.map((l) => (typeof l === "string" ? l : l.name ?? ""))
+            : [],
+        issueNumber: item.content?.number ?? undefined,
+        url: item.content?.url ?? undefined,
+        body: item.content?.body ?? undefined,
+    }));
+    // Apply status filter client-side if provided
+    if (options.status) {
+        const filterStatus = options.status.toLowerCase();
+        return items.filter((item) => item.status?.toLowerCase().includes(filterStatus));
+    }
+    return items;
+}
+/**
+ * Normalize the item type string from GitHub's API into our union type.
+ */
+function normalizeItemType(type) {
+    const t = String(type ?? "").toUpperCase();
+    if (t.includes("PULL") || t === "PULL_REQUEST")
+        return "PULL_REQUEST";
+    if (t.includes("DRAFT") || t === "DRAFT_ISSUE")
+        return "DRAFT_ISSUE";
+    return "ISSUE";
+}

package/dist/utils/ide.d.ts

@@ -0,0 +1,76 @@
+/**
+ * IDE Detection System
+ *
+ * Detects the current Integrated Development Environment or editor context.
+ * This is used to offer appropriate worktree launch options that match
+ * the user's current workflow.
+ *
+ * Detection is based on environment variables set by various IDEs when
+ * running terminal sessions within them.
+ */
+export type IDEType = "vscode" | "cursor" | "windsurf" | "jetbrains" | "zed" | "terminal" | "unknown";
+export interface IDEDetection {
+    type: IDEType;
+    name: string;
+    version?: string;
+    hasIntegratedTerminal: boolean;
+    canOpenInTerminal: boolean;
+    canOpenInWindow: boolean;
+    cliAvailable?: boolean;
+    cliBinary?: string;
+    cliInstallHint?: string;
+    detectionSource: string;
+}
+export interface EnvironmentRecommendation {
+    option: string;
+    priority: "high" | "medium" | "low";
+    reason: string;
+    mode?: "ide" | "terminal" | "pty" | "background" | "stay";
+}
+/**
+ * Detect the current IDE/editor environment.
+ * Checks environment variables, process hierarchy, and context clues.
+ */
+export declare function detectIDE(): IDEDetection;
+/**
+ * Get the command to open a worktree in the IDE's integrated terminal.
+ * Returns null if the IDE doesn't support CLI-based opening.
+ *
+ * Note: This function is currently unused but kept for future use.
+ * All inputs are escaped to prevent command injection.
+ */
+export declare function getIDEOpenCommand(ide: IDEDetection, worktreePath: string): string | null;
+/**
+ * Get the name of the CLI binary for the detected IDE.
+ * Returns null if no CLI is available or known.
+ */
+export declare function getIDECliBinary(ide: IDEDetection): string | null;
+/**
+ * Get a human-readable hint for installing an IDE's CLI binary.
+ * Each IDE has a different installation method.
+ */
+export declare function getInstallHint(type: IDEType, binary: string): string;
+/**
+ * Async version of detectIDE() that also checks whether the IDE's CLI binary
+ * is actually available in PATH. Use this in tools where you need to verify
+ * runtime availability before offering IDE launch options.
+ *
+ * The sync detectIDE() is preserved for non-async contexts.
+ */
+export declare function detectIDEWithCLICheck(): Promise<IDEDetection>;
+/**
+ * Check if we're already inside an IDE terminal.
+ * This helps determine if we should offer "stay here" as primary option.
+ */
+export declare function isInIDETerminal(): boolean;
+/**
+ * Generate contextual recommendations based on detected environment.
+ * Used by agents to offer appropriate launch options to users.
+ */
+export declare function generateEnvironmentRecommendations(ide: IDEDetection): EnvironmentRecommendation[];
+/**
+ * Format environment detection as a human-readable report.
+ * Used by the detect_environment tool.
+ */
+export declare function formatEnvironmentReport(ide: IDEDetection, terminalName: string): string;
+//# sourceMappingURL=ide.d.ts.map

package/dist/utils/ide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../src/utils/ide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,WAAW,GACX,KAAK,GACL,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAoGxC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6BxF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAahE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAapE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,YAAY,CAAC,CAgBnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,YAAY,GAAG,yBAAyB,EAAE,CAkDjG;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAgDvF"}