@opencodehub/mcp 0.1.0

package/dist/tools/pack-codebase.js

@@ -0,0 +1,289 @@
+/**
+ * `pack_codebase` — produce a snapshot of a registered repo for an LLM
+ * to consume.
+ *
+ * Two engines are supported via the `engine` input field:
+ *   - `pack` (DEFAULT) — `@opencodehub/pack`'s deterministic 9-item BOM
+ *     written to `<repo>/.codehub/packs/<packHash>/`. The BOM is what
+ *     downstream agents should consume — it carries skeleton + file-tree
+ *     + deps + ast-chunks + xrefs + findings + licenses + readme +
+ *     optional embeddings.parquet, all bound by a manifest with a
+ *     content-addressed `pack_hash`.
+ *   - `repomix` — the legacy single-file XML/Markdown snapshot under
+ *     `<repo>/.codehub/pack/repo.<ext>`. Retained as an opt-in for one
+ *     milestone (drop deferred to M7 per spec 005 Q-DELTA-6). Operators
+ *     who relied on repomix for raw repo packing keep a stable path.
+ *
+ * For relational/structural questions about the repo, prefer
+ * `query`/`context`/`impact` — those are backed by the SCIP graph and
+ * give graph-aware answers without consuming context window.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { generatePack as defaultGeneratePack } from "@opencodehub/pack";
+import { z } from "zod";
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { resolveRepo } from "../repo-resolver.js";
+import { fromToolResult, toToolResult } from "./shared.js";
+const DEFAULT_REPOMIX_VERSION = "1.14.0";
+/** Default token budget passed to the pack engine when `budget` is omitted. */
+export const DEFAULT_PACK_BUDGET = 100_000;
+/** Default tokenizer identifier when `tokenizer` is omitted. */
+export const DEFAULT_PACK_TOKENIZER = "openai:o200k_base@tiktoken-0.8.0";
+const PackInput = z.object({
+    repo: z
+        .string()
+        .optional()
+        .describe("Registered repo name (see list_repos). Provide `repo` or `repo_uri`; required when ≥ 2 repos are registered."),
+    repo_uri: z
+        .string()
+        .optional()
+        .describe("Sourcegraph-style repo URI (e.g. `github.com/org/repo`). Accepted as an alias for `repo`; wins when both are provided."),
+    engine: z
+        .enum(["pack", "repomix"])
+        .optional()
+        .default("pack")
+        .describe("Engine: `pack` (default) writes the 9-item BOM via @opencodehub/pack. " +
+        "`repomix` is the legacy single-file snapshot, retained as an opt-in."),
+    budget: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(DEFAULT_PACK_BUDGET)
+        .describe("Token budget for the AST chunker. Pack engine only. Default 100000."),
+    tokenizer: z
+        .string()
+        .optional()
+        .default(DEFAULT_PACK_TOKENIZER)
+        .describe('Tokenizer pin "<vendor>:<name>@<pin>". Pack engine only. Default openai:o200k_base@tiktoken-0.8.0.'),
+    // Legacy repomix-only fields. Honored when engine === "repomix"; ignored
+    // for the pack engine.
+    style: z
+        .enum(["xml", "markdown", "json", "plain"])
+        .optional()
+        .default("xml")
+        .describe("Repomix output style. Repomix engine only."),
+    compress: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Repomix tree-sitter signature compression. Repomix engine only."),
+    removeComments: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Repomix --remove-comments. Repomix engine only."),
+});
+export async function runPackCodebase(ctx, input, deps = {}) {
+    try {
+        const entry = await resolveRepo({
+            ...(input.repo !== undefined ? { repo: input.repo } : {}),
+            ...(input.repo_uri !== undefined ? { repo_uri: input.repo_uri } : {}),
+        }, {
+            ...(ctx.home !== undefined ? { home: ctx.home } : {}),
+            skipMeta: true,
+        });
+        if (input.engine === "repomix") {
+            return await runRepomixPath(entry, input, deps);
+        }
+        return await runPackPath(entry, input, deps);
+    }
+    catch (err) {
+        return toToolResult(toolErrorFromUnknown(err));
+    }
+}
+async function runPackPath(entry, input, deps) {
+    const start = Date.now();
+    const result = deps._runPackEngine !== undefined
+        ? await deps._runPackEngine({
+            repo: entry.repoPath,
+            budget: input.budget,
+            tokenizer: input.tokenizer,
+        })
+        : await callRealPackEngine({
+            repo: entry.repoPath,
+            budget: input.budget,
+            tokenizer: input.tokenizer,
+        });
+    const durationMs = Date.now() - start;
+    const body = [
+        `Packed ${entry.name} via @opencodehub/pack to ${result.outDir}`,
+        `  bomItemCount: ${result.bomItemCount}`,
+        `  packHash:     ${result.packHash}`,
+        `  budget:       ${input.budget}`,
+        `  tokenizer:    ${input.tokenizer}`,
+        `  duration:     ${durationMs}ms`,
+    ].join("\n");
+    return toToolResult(withNextSteps(body, {
+        engine: "pack",
+        outDir: result.outDir,
+        packHash: result.packHash,
+        bomItemCount: result.bomItemCount,
+        budget: input.budget,
+        tokenizer: input.tokenizer,
+        durationMs,
+    }, [
+        "load .codehub/packs/<hash>/manifest.json to inspect the BOM, then read the per-BOM-item files (skeleton, file-tree, ast-chunks, xrefs, findings, licenses).",
+        "structural questions go to `query`/`context`/`impact` — those answer without consuming context window.",
+    ]));
+}
+async function runRepomixPath(entry, input, deps) {
+    const result = deps._runRepomixEngine !== undefined
+        ? await deps._runRepomixEngine({
+            repoPath: entry.repoPath,
+            style: input.style,
+            compress: input.compress,
+            removeComments: input.removeComments,
+        })
+        : await callRealRepomixEngine({
+            repoPath: entry.repoPath,
+            style: input.style,
+            compress: input.compress,
+            removeComments: input.removeComments,
+        });
+    const body = [
+        `Packed ${entry.name} via repomix to ${result.outputPath}`,
+        `  bytes:    ${result.bytes}`,
+        `  style:    ${input.style}`,
+        `  compress: ${input.compress}`,
+        `  duration: ${result.durationMs}ms`,
+    ].join("\n");
+    // Mark the engine in `_meta.engine` so callers can detect the legacy path
+    // and migrate; `next_steps` flags the M7 deprecation explicitly.
+    return toToolResult(withNextSteps(body, {
+        engine: "repomix",
+        outputPath: result.outputPath,
+        bytes: result.bytes,
+        style: input.style,
+        durationMs: result.durationMs,
+        _meta: { engine: "repomix" },
+    }, [
+        "repomix engine is opt-in and slated for removal in M7 — prefer engine='pack' (default) for new callers.",
+        "load the output file into your context; structural questions go to `query`/`context`/`impact`.",
+    ]));
+}
+/**
+ * Real-world implementation of the pack engine. Imports the CLI's
+ * `runCodePack` lazily so MCP servers without `@opencodehub/cli`
+ * installed (e.g. embed-only deployments) still type-check; the import
+ * happens only on engine=pack invocations.
+ */
+async function callRealPackEngine(args) {
+    // Inline the same wiring as `runCodePack` rather than importing
+    // `@opencodehub/cli` (which would create a cycle, MCP <- CLI <- MCP).
+    // Open the DuckStore directly, call generatePack, rename into place.
+    const { mkdtemp, rename, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join, resolve } = await import("node:path");
+    const { openStore, resolveDbPath } = await import("@opencodehub/storage");
+    const dbPath = resolveDbPath(args.repo);
+    if (!existsSync(dbPath)) {
+        throw new Error(`pack_codebase: no graph index at ${dbPath}. ` +
+            "Run `codehub analyze` first to populate the store.");
+    }
+    const store = await openStore({ path: dbPath, backend: "duck", readOnly: true });
+    const stagingDir = await mkdtemp(join(tmpdir(), "codehub-pack-mcp-"));
+    try {
+        const manifest = await defaultGeneratePack({
+            repoPath: args.repo,
+            outDir: stagingDir,
+            budgetTokens: args.budget,
+            tokenizerId: args.tokenizer,
+        }, { store });
+        const finalOutDir = resolve(args.repo, ".codehub", "packs", manifest.packHash);
+        await mkdir(dirname(finalOutDir), { recursive: true });
+        if (existsSync(finalOutDir)) {
+            await rm(finalOutDir, { recursive: true, force: true });
+        }
+        await rename(stagingDir, finalOutDir);
+        return {
+            outDir: finalOutDir,
+            packHash: manifest.packHash,
+            bomItemCount: manifest.files.length + 1,
+        };
+    }
+    finally {
+        await store.close();
+        await rm(stagingDir, { recursive: true, force: true });
+    }
+}
+/** Real-world repomix shell-out. */
+async function callRealRepomixEngine(args) {
+    const outputPath = join(args.repoPath, ".codehub", "pack", `repo.${extForStyle(args.style)}`);
+    await mkdir(dirname(outputPath), { recursive: true });
+    const cmdArgs = [
+        `repomix@${DEFAULT_REPOMIX_VERSION}`,
+        "--style",
+        args.style,
+        "--output",
+        outputPath,
+    ];
+    if (args.compress)
+        cmdArgs.push("--compress");
+    if (args.removeComments)
+        cmdArgs.push("--remove-comments");
+    const start = Date.now();
+    await new Promise((res, rej) => {
+        const child = spawn("npx", cmdArgs, {
+            cwd: args.repoPath,
+            env: { ...process.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stderr = "";
+        child.stderr?.on("data", (d) => {
+            stderr += d.toString();
+        });
+        child.on("error", (err) => {
+            rej(err.code === "ENOENT"
+                ? new Error("pack_codebase: `npx` not found on PATH. Install Node.js 20+.")
+                : err);
+        });
+        child.on("exit", (code) => {
+            if (code === 0)
+                res();
+            else
+                rej(new Error(`pack_codebase: repomix exited ${code}. ${stderr.slice(-400)}`));
+        });
+    });
+    const durationMs = Date.now() - start;
+    if (!existsSync(outputPath)) {
+        throw new Error(`pack_codebase: repomix did not produce ${outputPath}`);
+    }
+    const bytes = statSync(outputPath).size;
+    return { outputPath, bytes, durationMs };
+}
+export function registerPackCodebaseTool(server, ctx) {
+    server.registerTool("pack_codebase", {
+        title: "Pack a repo into an LLM-ready snapshot",
+        description: "Produce a snapshot of a registered repo. The default `pack` engine writes the deterministic " +
+            "9-item BOM (manifest + skeleton + file-tree + deps + ast-chunks + xrefs + findings + " +
+            "licenses + readme + optional embeddings.parquet) under <repo>/.codehub/packs/<packHash>/. " +
+            "The legacy `repomix` engine is retained as an opt-in single-file snapshot (drop deferred to M7). " +
+            "For relational/structural questions about the repo, prefer query/context/impact — those are " +
+            "backed by the SCIP graph and give graph-aware answers without consuming context window.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: PackInput.shape,
+    }, async (input) => fromToolResult(await runPackCodebase(ctx, input)));
+}
+function extForStyle(style) {
+    switch (style) {
+        case "xml":
+            return "xml";
+        case "markdown":
+            return "md";
+        case "json":
+            return "json";
+        case "plain":
+            return "txt";
+    }
+}
+//# sourceMappingURL=pack-codebase.js.map

package/dist/tools/pack-codebase.js.map

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

package/dist/tools/project-profile.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `project_profile` — return the ProjectProfile node for a repo.
+ *
+ * Profile is a singleton per repo, emitted by the ingestion `profile` phase.
+ * Each array field is stored in DuckDB as a JSON-encoded TEXT column
+ * (`languages_json`, `frameworks_json`, etc.) so we decode every column
+ * back into a `string[]` before returning. If the repo was indexed before
+ * the profile phase shipped (or the phase failed to write the node), we
+ * return empty arrays and a hint nudging the caller toward `codehub
+ * analyze --force`.
+ *
+ * `frameworks_json` is polymorphic across two generations:
+ *   - v1.0 (legacy) → a flat `string[]` of framework names.
+ *   - v2.0 (post-P05) → `{ flat: string[], detected: FrameworkDetection[] }`
+ *     so variant / version / confidence / parent metadata survives the
+ *     round-trip. Both are read transparently; callers receive both a
+ *     flat form (backward-compat) and the structured form in the payload.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface ProjectProfileArgs {
+    readonly repo?: string | undefined;
+    readonly repo_uri?: string | undefined;
+}
+export declare function runProjectProfile(ctx: ToolContext, args: ProjectProfileArgs): Promise<ToolResult>;
+export declare function registerProjectProfileTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=project-profile.d.ts.map

package/dist/tools/project-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-profile.d.ts","sourceRoot":"","sources":["../../src/tools/project-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKzE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAkBrB,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,UAAU,CAAC,CAoFrB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAiBpF"}

package/dist/tools/project-profile.js

@@ -0,0 +1,109 @@
+/**
+ * `project_profile` — return the ProjectProfile node for a repo.
+ *
+ * Profile is a singleton per repo, emitted by the ingestion `profile` phase.
+ * Each array field is stored in DuckDB as a JSON-encoded TEXT column
+ * (`languages_json`, `frameworks_json`, etc.) so we decode every column
+ * back into a `string[]` before returning. If the repo was indexed before
+ * the profile phase shipped (or the phase failed to write the node), we
+ * return empty arrays and a hint nudging the caller toward `codehub
+ * analyze --force`.
+ *
+ * `frameworks_json` is polymorphic across two generations:
+ *   - v1.0 (legacy) → a flat `string[]` of framework names.
+ *   - v2.0 (post-P05) → `{ flat: string[], detected: FrameworkDetection[] }`
+ *     so variant / version / confidence / parent metadata survives the
+ *     round-trip. Both are read transparently; callers receive both a
+ *     flat form (backward-compat) and the structured form in the payload.
+ */
+// biome-ignore-all lint/complexity/useLiteralKeys: dot-access disallowed on Record index signatures
+import { toolErrorFromUnknown } from "../error-envelope.js";
+import { withNextSteps } from "../next-step-hints.js";
+import { stalenessFromMeta } from "../staleness.js";
+import { fromToolResult, repoArgShape, toToolResult, withStore, } from "./shared.js";
+const ProjectProfileInput = {
+    ...repoArgShape,
+};
+export async function runProjectProfile(ctx, args) {
+    const call = await withStore(ctx, args, async (store, resolved) => {
+        try {
+            const nodes = await store.graph.listNodesByKind("ProjectProfile", { limit: 1 });
+            const profile = nodes[0];
+            const payload = {
+                languages: profile?.languages ? [...profile.languages] : [],
+                frameworks: profile?.frameworks ? [...profile.frameworks] : [],
+                frameworksDetected: profile?.frameworksDetected ? [...profile.frameworksDetected] : [],
+                iacTypes: profile?.iacTypes ? [...profile.iacTypes] : [],
+                apiContracts: profile?.apiContracts ? [...profile.apiContracts] : [],
+                manifests: profile?.manifests ? [...profile.manifests] : [],
+                srcDirs: profile?.srcDirs ? [...profile.srcDirs] : [],
+            };
+            const profileExists = profile !== undefined;
+            const header = profileExists
+                ? `Project profile for ${resolved.name}:`
+                : `No ProjectProfile node in ${resolved.name}. Re-index with \`codehub analyze --force\` to populate.`;
+            const lines = [header];
+            if (payload.languages.length > 0) {
+                lines.push(`  languages     (${payload.languages.length}): ${payload.languages.join(", ")}`);
+            }
+            if (payload.frameworks.length > 0) {
+                // Prefer the structured form for display when available — render
+                // each framework with its variant so operators see "nextjs:app-router"
+                // rather than a bare "nextjs". Fall back to flat names.
+                const display = payload.frameworksDetected.length > 0
+                    ? payload.frameworksDetected.map((d) => (d.variant ? `${d.name}:${d.variant}` : d.name))
+                    : payload.frameworks;
+                lines.push(`  frameworks    (${display.length}): ${display.join(", ")}`);
+            }
+            if (payload.iacTypes.length > 0) {
+                lines.push(`  iacTypes      (${payload.iacTypes.length}): ${payload.iacTypes.join(", ")}`);
+            }
+            if (payload.apiContracts.length > 0) {
+                lines.push(`  apiContracts  (${payload.apiContracts.length}): ${payload.apiContracts.join(", ")}`);
+            }
+            if (payload.manifests.length > 0) {
+                lines.push(`  manifests     (${payload.manifests.length}): ${payload.manifests.join(", ")}`);
+            }
+            if (payload.srcDirs.length > 0) {
+                lines.push(`  srcDirs       (${payload.srcDirs.length}): ${payload.srcDirs.join(", ")}`);
+            }
+            const next = [];
+            if (!profileExists) {
+                next.push("run `codehub analyze --force` to emit the ProjectProfile node");
+            }
+            else {
+                if (payload.frameworks.length > 0) {
+                    next.push(`call \`query\` with the framework name (e.g. "${payload.frameworks[0] ?? ""}") to find entry points`);
+                }
+                if (payload.apiContracts.includes("openapi")) {
+                    next.push("call `query` with kinds=['Operation'] to list OpenAPI operations");
+                }
+                if (payload.iacTypes.includes("terraform")) {
+                    next.push("call `list_findings` (once scanners are wired) for tfsec/checkov results");
+                }
+                if (next.length === 0) {
+                    next.push("call `list_repos` to pick a different repo");
+                }
+            }
+            return withNextSteps(lines.join("\n"), { profile: payload }, next, stalenessFromMeta(resolved.meta));
+        }
+        catch (err) {
+            return toolErrorFromUnknown(err);
+        }
+    });
+    return toToolResult(call);
+}
+export function registerProjectProfileTool(server, ctx) {
+    server.registerTool("project_profile", {
+        title: "Project Profile",
+        description: "Returns the detected project profile: languages, frameworks (flat + structured), IaC types, API contracts, manifests, source directories.",
+        inputSchema: ProjectProfileInput,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => fromToolResult(await runProjectProfile(ctx, args)));
+}
+//# sourceMappingURL=project-profile.js.map

package/dist/tools/project-profile.js.map

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

package/dist/tools/query.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `query` — true hybrid retrieval over the indexed graph.
+ *
+ * Two ranked runs, fused with Reciprocal Rank Fusion (k=60):
+ *   1. BM25 (DuckDB FTS) over `nodes.name` + `nodes.signature` +
+ *      `nodes.description`. If a `symbol_summaries` table is present the
+ *      corpus extends transparently (see {@link bm25CorpusHasSummaries}) so
+ *      summarized prose participates as soon as the ingestion phase lands.
+ *   2. HNSW vector search over the `embeddings` table. The query text is
+ *      embedded with the same gte-modernbert-base ONNX model the ingestion
+ *      pipeline uses, so the vectors live in the same space.
+ *
+ * Graceful fallback:
+ *   - If the `embeddings` table is empty, skip the vector leg entirely.
+ *   - If the embedder weights are missing (EMBEDDER_NOT_SETUP) or any other
+ *     failure blocks the embedder from opening, warn once to stderr and fall
+ *     back to BM25-only. We never abort the query — the invariant is that a
+ *     fresh-cloned repo still answers `query` before `codehub setup
+ *     --embeddings` has been run.
+ *
+ * The response shape is stable across BM25-only and hybrid paths:
+ *   `{ results, definitions, processes, process_symbols, mode }`.
+ * `results` is the primary ranked list; `definitions` mirrors it one-to-one
+ * (preserved for agents that learned the legacy shape). `processes` +
+ * `process_symbols` hold the process-grouped view: after fusion we walk
+ * PROCESS_STEP edges backwards from each top-K hit to locate the containing
+ * Process nodes, then walk PROCESS_STEP edges forward from each matched
+ * Process's entry point to enumerate its ordered member steps. Both walks
+ * happen in ONE consolidated SQL query (two CTEs + a join) so the enrichment
+ * pass is a single round-trip. When no Process touches a top-K hit, or the
+ * repo has no PROCESS_STEP edges yet, the arrays stay empty — the flat
+ * `results` ranking still covers the query.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolContext, type ToolResult } from "./shared.js";
+interface QueryArgs {
+    readonly query: string;
+    readonly repo?: string;
+    readonly repo_uri?: string;
+    readonly limit?: number;
+    readonly kinds?: readonly string[];
+    readonly task_context?: string;
+    readonly goal?: string;
+    readonly include_content?: boolean;
+    readonly max_symbols?: number;
+    /** Hierarchical tier filter (P03). Defaults to "symbol". */
+    readonly granularity?: "symbol" | "file" | "community";
+    /** "flat" (default) or "zoom" coarse-to-fine retrieval. */
+    readonly mode?: "flat" | "zoom";
+    /** Coarse file-tier fanout when mode=zoom. */
+    readonly zoom_fanout?: number;
+    /**
+     * Bypass the embedder fingerprint refusal. When `true`, the query
+     * proceeds against an `embeddings` table populated by a different
+     * embedder than the one currently active. Vectors may be stale;
+     * results may misrank. Default `false`.
+     */
+    readonly force_backend_mismatch?: boolean;
+}
+export declare function runQuery(ctx: ToolContext, args: QueryArgs): Promise<ToolResult>;
+export declare function registerQueryTool(server: McpServer, ctx: ToolContext): void;
+export {};
+//# sourceMappingURL=query.d.ts.map

package/dist/tools/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoBzE,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAkhBrB,UAAU,SAAS;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACvD,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CA2LrF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAuD3E"}