@nanonets/graft 0.16.0 → 0.19.0

package/dist/brain/link.js

@@ -0,0 +1,146 @@
+/**
+ * The link between a repo's graft graph and a Trail brain.
+ *
+ * A brain holds the rules mined out of this repository's history — what the
+ * team decided and why, which the code graph cannot see. Graft holds the code
+ * and can say which symbols an answer touches. This module is the join: the
+ * token identifying the brain, and the rules cached beside it so `ask` never
+ * waits on the network.
+ *
+ * The link lives in the per-repo, git-ignored `.graft/config.json`, next to the
+ * other persisted build choices. Not in `~/.graft/`: a brain belongs to one
+ * repository, and two checkouts of different repos on one machine must not
+ * share one.
+ */
+import { readBuildConfig, patchBuildConfig, cacheDir, readJson, writeJsonAtomic } from '../util/state.js';
+import { join } from 'node:path';
+import { ensureGitignored, LINK_NOTE } from '../context/node-file.js';
+import { BUILD_CONFIG_DIR } from '../util/state.js';
+/** Default API host. Overridden by GRAFT_BRAIN_URL, for staging and self-hosted. */
+const DEFAULT_BRAIN_BASE_URL = 'https://agents.nanonets.com';
+/** How long a cached rule set is served before upkeep refreshes it. */
+export const RULES_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
+/**
+ * The TTL used while the cache holds NO rules.
+ *
+ * A brain is connected during onboarding while it is still being mined, so the
+ * first pull legitimately returns nothing. Six hours of that is the difference
+ * between the feature working and the user concluding it does not: they wired
+ * graft up, got an empty rulebook, and nothing would go back for the real one
+ * until tomorrow. Two minutes costs one cheap request per session until the
+ * rules land, and then the normal TTL takes over.
+ */
+export const EMPTY_RULES_TTL_MS = 2 * 60 * 1000;
+/**
+ * The link for repo `dir`, or null when it has none.
+ *
+ * `GRAFT_BRAIN_TOKEN` / `GRAFT_BRAIN_ID` override the stored pair, so CI can
+ * attach a brain without writing to the checkout.
+ */
+export function readLink(dir) {
+    const envToken = process.env.GRAFT_BRAIN_TOKEN;
+    const envBrain = process.env.GRAFT_BRAIN_ID;
+    if (envToken && envBrain) {
+        return { brainId: envBrain, token: envToken, baseUrl: process.env.GRAFT_BRAIN_URL };
+    }
+    const stored = readBuildConfig(dir)?.brain;
+    if (!stored?.brainId || !stored?.token)
+        return null;
+    return stored;
+}
+/** Persist the link for repo `dir`, merging into any existing build config.
+ *
+ * The write is what creates `.graft/config.json`, and that file holds the read
+ * token — which is exactly why this is also where it gets ignored. The comment
+ * on {@link BrainLink} has claimed `.graft/` was "git-ignored" since the day it
+ * was written, and nothing ever made it true: `ensureGitignored` only ever ran
+ * for the graph cache. Every repository anyone ran `graft brain connect` in was
+ * therefore one `git add -A` away from publishing a credential. */
+export function writeLink(dir, link) {
+    patchBuildConfig(dir, { brain: link });
+    ensureGitignored(dir, join(dir, BUILD_CONFIG_DIR), LINK_NOTE);
+}
+/** Forget the link for repo `dir`. Leaves the cached rules for `uninstall` to remove. */
+export function clearLink(dir) {
+    patchBuildConfig(dir, { brain: undefined });
+}
+/** Where the rule cache lives: beside the graph, since it is derived data. */
+export function rulesCachePath(dir) {
+    return join(cacheDir(dir), 'brain-rules.json');
+}
+export function readRulesCache(dir) {
+    return readJson(rulesCachePath(dir));
+}
+export function writeRulesCache(dir, cache) {
+    writeJsonAtomic(rulesCachePath(dir), cache, true);
+}
+/**
+ * Whether a cached set is old enough to refetch.
+ *
+ * Keyed off the last ATTEMPT, not the last success, and with a much shorter
+ * window while the cache is empty — see EMPTY_RULES_TTL_MS for why that case
+ * is the one that matters.
+ */
+export function cacheIsStale(cache, now = Date.now()) {
+    if (!cache)
+        return true;
+    const ttl = cache.rules.length === 0 ? EMPTY_RULES_TTL_MS : RULES_TTL_MS;
+    return now - (cache.checkedAt ?? cache.fetchedAt) > ttl;
+}
+/** Record that a refresh was attempted, without claiming rules arrived. */
+export function markRulesChecked(dir, now = Date.now()) {
+    const cache = readRulesCache(dir);
+    if (!cache)
+        return;
+    writeRulesCache(dir, { ...cache, checkedAt: now });
+}
+/**
+ * The base URL for a link, honouring the env override first so a misconfigured
+ * stored value can always be corrected without editing a file.
+ */
+export function baseUrlFor(link) {
+    return (process.env.GRAFT_BRAIN_URL || link.baseUrl || DEFAULT_BRAIN_BASE_URL).replace(/\/+$/, '');
+}
+/** Timeout for one rules fetch. Short: `ask` must never block on this. */
+const FETCH_TIMEOUT_MS = 5000;
+/**
+ * Fetch the brain's symbol-anchored rules.
+ *
+ * Returns null on any failure — an unreachable brain, a revoked token, a
+ * malformed body. Never throws: `ask` degrades to the code-only answer it gave
+ * before a brain was attached, which is the whole reason the cache exists.
+ */
+export async function fetchRules(link, fetchImpl = fetch) {
+    // The PUBLIC, token-authenticated route: graft runs on a laptop with no
+    // session, and the token it holds is scoped to this one brain rather than the
+    // workspace. The protected route is for the app itself.
+    const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/rules/anchors`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${link.token}`, accept: 'application/json' },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!Array.isArray(body.anchors))
+            return null;
+        const out = [];
+        for (const a of body.anchors) {
+            if (!a?.symbol || !a?.rule)
+                continue;
+            out.push({
+                ruleId: String(a.rule_id ?? ''),
+                symbol: a.symbol,
+                fingerprint: String(a.fingerprint ?? ''),
+                rule: a.rule,
+                sourceUrl: a.source_url || undefined,
+            });
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=link.js.map

package/dist/brain/link.js.map

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

package/dist/brain/push.d.ts

@@ -0,0 +1,72 @@
+import { type RepoDigest } from "../app/history.js";
+import type { GraphV1 } from "../graph/types.js";
+import { type BrainLink } from "./link.js";
+/** What a local ingest read, for the caller to print. */
+export interface PushResult {
+    jobId: string;
+    repo: string;
+    commits: number;
+    threads: number;
+    symbols: number;
+    sources: number;
+    /** Set when discussion could not be read; the ingest still went ahead. */
+    warning?: string;
+}
+/**
+ * owner/name for this checkout, from its origin remote.
+ *
+ * Only GitHub, because the discussion reader and the forge links are
+ * GitHub-shaped; another forge would need its own reader, not a looser regex
+ * here that produces links to nowhere.
+ */
+export declare function repoSlugFromGit(root: string): {
+    owner: string;
+    name: string;
+} | null;
+/**
+ * A GitHub token from wherever the user already keeps one.
+ *
+ * `gh auth token` first, because anyone who works with private repositories on
+ * the command line has it and it needs no setup at all. The env vars are the
+ * CI path. Absent, the ingest still runs on commits alone — pull-request
+ * discussion is the richest source, not a required one.
+ */
+export declare function githubToken(): string | null;
+/** What the brain is waiting for, when it is waiting for something. */
+export interface ExpectedRepo {
+    slug: string;
+    status: string;
+    brainName: string;
+}
+/**
+ * The repository this brain expects, or null when it expects none.
+ *
+ * The website records it when the user chooses the local route, so this is how
+ * the CLI knows whether the directory it is standing in is the one they asked
+ * for. Mining the wrong repo into a brain is silent and very hard to notice
+ * afterwards — the rules simply describe someone else's codebase — so the round
+ * trip is worth it.
+ *
+ * Null on any failure, which keeps an older brain (or an unreachable one)
+ * working exactly as it did before this check existed.
+ */
+export declare function fetchExpectedRepo(link: BrainLink, fetchImpl?: typeof fetch): Promise<ExpectedRepo | null>;
+/** Whether two repo slugs name the same repository. GitHub is case-insensitive. */
+export declare function sameRepo(a: string, b: string): boolean;
+/** Build the digest for the checkout at `root`. Reads nothing but text. */
+export declare function buildLocalDigest(root: string, graph: GraphV1 | null, opts?: {
+    autoApprove?: boolean;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    digest: RepoDigest;
+    warning?: string;
+} | {
+    error: string;
+}>;
+/** Send a digest to the brain and return the job to poll. */
+export declare function pushDigest(link: BrainLink, digest: RepoDigest, fetchImpl?: typeof fetch): Promise<{
+    jobId: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=push.d.ts.map

package/dist/brain/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../src/brain/push.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAEvD,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAYD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMpF;AAQD;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,GAAG,IAAI,CAM3C;AAgBD,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAatH;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,2EAA2E;AAC3E,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GAAG,IAAI,EACrB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAC7D,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoDvE;AAED,6DAA6D;AAC7D,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,EAClB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBhD"}

package/dist/brain/push.js

@@ -0,0 +1,191 @@
+/**
+ * Building a brain from the repository already on this machine.
+ *
+ * The server path needs graft's GitHub App installed on the repo, which is an
+ * admin action on someone else's org and the first thing asked of a person who
+ * has not seen a single rule yet. For a private repository it is often simply
+ * unavailable.
+ *
+ * This is the way round that: the clone is already here, and the user is
+ * already authenticated to GitHub for their own work. So read it locally and
+ * send up the same digest the server would have built.
+ *
+ * What leaves the machine is what people wrote — commit messages, pull-request
+ * comments, the docs and config already in the tree — plus symbol ids and
+ * hashes. No file contents, no diffs, no source.
+ */
+import { spawnSync } from "node:child_process";
+import { buildDigest, readCommits, readSymbols, readThreads, } from "../app/history.js";
+import { budgetSources, readAgentInstructions, readBranchProtection, readCodeowners, readCodifiedRules, readDecisionDocs, readDeclinedIssues, readReverts, readTestNames, } from "../app/sources.js";
+import { baseUrlFor } from "./link.js";
+function git(root, args) {
+    const res = spawnSync("git", ["-c", "core.quotePath=false", ...args], {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (res.error || res.status !== 0 || typeof res.stdout !== "string")
+        return null;
+    return res.stdout.trim();
+}
+/**
+ * owner/name for this checkout, from its origin remote.
+ *
+ * Only GitHub, because the discussion reader and the forge links are
+ * GitHub-shaped; another forge would need its own reader, not a looser regex
+ * here that produces links to nowhere.
+ */
+export function repoSlugFromGit(root) {
+    const url = git(root, ["remote", "get-url", "origin"]);
+    if (!url)
+        return null;
+    const m = url.match(/github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/i);
+    if (!m)
+        return null;
+    return { owner: m[1], name: m[2] };
+}
+/** The branch to attribute the ingest to. */
+function currentBranch(root) {
+    const head = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    return head && head !== "HEAD" ? head : "";
+}
+/**
+ * A GitHub token from wherever the user already keeps one.
+ *
+ * `gh auth token` first, because anyone who works with private repositories on
+ * the command line has it and it needs no setup at all. The env vars are the
+ * CI path. Absent, the ingest still runs on commits alone — pull-request
+ * discussion is the richest source, not a required one.
+ */
+export function githubToken() {
+    const env = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+    if (env)
+        return env;
+    const res = spawnSync("gh", ["auth", "token"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const out = typeof res.stdout === "string" ? res.stdout.trim() : "";
+    return res.status === 0 && out ? out : null;
+}
+/** Whether the repository is private, so the digest records it honestly. */
+async function isPrivate(owner, name, token, fetchImpl) {
+    if (!token)
+        return true; // unknown counts as private
+    try {
+        const res = await fetchImpl(`https://api.github.com/repos/${owner}/${name}`, {
+            headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+        });
+        if (!res.ok)
+            return true;
+        return (await res.json()).private !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * The repository this brain expects, or null when it expects none.
+ *
+ * The website records it when the user chooses the local route, so this is how
+ * the CLI knows whether the directory it is standing in is the one they asked
+ * for. Mining the wrong repo into a brain is silent and very hard to notice
+ * afterwards — the rules simply describe someone else's codebase — so the round
+ * trip is worth it.
+ *
+ * Null on any failure, which keeps an older brain (or an unreachable one)
+ * working exactly as it did before this check existed.
+ */
+export async function fetchExpectedRepo(link, fetchImpl = fetch) {
+    try {
+        const res = await fetchImpl(`${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`, {
+            headers: { authorization: `Bearer ${link.token}`, accept: "application/json" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body.repo?.slug)
+            return null;
+        return { slug: body.repo.slug, status: String(body.repo.status ?? ""), brainName: String(body.brain_name ?? "") };
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether two repo slugs name the same repository. GitHub is case-insensitive. */
+export function sameRepo(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+/** Build the digest for the checkout at `root`. Reads nothing but text. */
+export async function buildLocalDigest(root, graph, opts = {}) {
+    const slug = repoSlugFromGit(root);
+    if (!slug) {
+        return { error: "this directory has no GitHub `origin` remote — graft can only push a GitHub repository today" };
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const token = githubToken();
+    const commits = readCommits(root);
+    if (commits.length === 0) {
+        return { error: "no commits found here — is this a shallow clone with no history?" };
+    }
+    const symbols = readSymbols(graph);
+    let threads = [];
+    let warning;
+    if (token) {
+        try {
+            threads = await readThreads(slug.owner, slug.name, token, fetchImpl);
+        }
+        catch {
+            warning = "could not read pull-request discussion; mining commits and repo files only";
+        }
+    }
+    else {
+        warning =
+            "no GitHub token found (`gh auth login`, or GH_TOKEN) — mining commits and repo files only, without pull-request discussion";
+    }
+    const branch = currentBranch(root);
+    const sources = budgetSources([
+        ...readAgentInstructions(root),
+        ...readDecisionDocs(root),
+        ...readCodeowners(root),
+        ...readCodifiedRules(root),
+        ...readReverts(root),
+        ...readTestNames(symbols.map((s) => ({ name: s.name, path: s.path }))),
+        ...(token ? await readBranchProtection(slug.owner, slug.name, branch, token, fetchImpl) : []),
+        ...(token ? await readDeclinedIssues(slug.owner, slug.name, token, fetchImpl) : []),
+    ]);
+    const digest = buildDigest({
+        owner: slug.owner,
+        name: slug.name,
+        headSha: git(root, ["rev-parse", "HEAD"]) ?? "",
+        defaultBranch: branch,
+        isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),
+        commits,
+        threads,
+        symbols,
+        sources,
+        autoApprove: opts.autoApprove ?? true,
+    });
+    return { digest, warning };
+}
+/** Send a digest to the brain and return the job to poll. */
+export async function pushDigest(link, digest, fetchImpl = fetch) {
+    const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo`;
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${link.token}`,
+                "content-type": "application/json",
+                accept: "application/json",
+            },
+            body: JSON.stringify(digest),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            return { error: `the brain refused the ingest: ${res.status} ${text.slice(0, 200)}` };
+        return { jobId: String(JSON.parse(text).job_id ?? "") };
+    }
+    catch (e) {
+        return { error: `could not reach the brain: ${e instanceof Error ? e.message : e}` };
+    }
+}
+//# sourceMappingURL=push.js.map

package/dist/brain/push.js.map

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

package/dist/brain/signup.d.ts

@@ -0,0 +1,73 @@
+import type { BrainLink } from "./link.js";
+/** How long the listener waits for the browser before giving up. A signup can
+ * involve reading an email, so this is minutes rather than seconds. */
+export declare const HANDOFF_TIMEOUT_MS: number;
+/** The one path the listener answers on. */
+export declare const CALLBACK_PATH = "/graft/callback";
+/**
+ * What the browser sends back, or why it could not be accepted.
+ *
+ * `error` is the sentence printed to the user and `reason` is the same fact as a
+ * category. They are separate because the sentence names the repo and the link,
+ * so it can never be the thing telemetry reports — and matching on its text to
+ * recover the category would put a user-facing string in a position where
+ * rewording it silently changes what gets counted.
+ */
+export type HandoffFailure = "timed_out" | "bad_callback";
+export type HandoffResult = {
+    link: BrainLink;
+} | {
+    error: string;
+    reason: HandoffFailure;
+};
+export interface Handoff {
+    /** The loopback port Trail must redirect to. */
+    port: number;
+    /** The nonce Trail must echo back. */
+    state: string;
+    /** Resolves once the browser answers, or when `timeoutMs` passes. */
+    wait(timeoutMs?: number): Promise<HandoffResult>;
+    /** Stop listening. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * Start listening for the browser's handoff.
+ *
+ * Port 0 so the OS picks a free one: a fixed port would collide with whatever
+ * else the developer is running, and a second graft in another terminal.
+ */
+export declare function startHandoff(): Promise<Handoff>;
+/** The Trail front end this machine is pointed at, without a trailing slash.
+ *
+ * Read at the moment it is needed rather than captured once, matching the rest
+ * of the brain code: GRAFT_BRAIN_URL is free to move between calls. */
+export declare function webBaseUrl(baseUrl?: string): string;
+/** Where the browser is sent once the handoff has been accepted.
+ *
+ * Back into Trail, at the screen that shows the brain being built. The
+ * alternative — leaving the person on a local page that says "go back to your
+ * terminal" — ends the flow on a blank throwaway served by a port that is about
+ * to close, at exactly the moment there is something to watch.
+ *
+ * NOT `/brain/<id>`, which is where this pointed first. That route redirects to
+ * the brain's graph, and the redirect fires the instant the row exists — which
+ * is minutes before it has any rules in it. Every terminal signup therefore
+ * landed on an empty visualisation of a brain that was, at that moment, being
+ * built perfectly well. The build screen is the same wait the browser-first
+ * flow shows, and it leads to the graph once there is a graph. */
+export declare function brainUrl(brainId: string, baseUrl?: string): string;
+/** Where to send the browser for a repo's brain. */
+export declare function signupUrl(opts: {
+    repo: string;
+    port: number;
+    state: string;
+    baseUrl?: string;
+}): string;
+/** Open the user's browser, best effort. A machine with no opener is not an
+ * error: the URL is printed too, and that is the fallback everywhere.
+ *
+ * GRAFT_NO_BROWSER leaves the printed URL as the only route, which is what a
+ * test wants, and what someone on a machine whose `open` does something
+ * surprising wants too. */
+export declare function openBrowser(url: string): void;
+//# sourceMappingURL=signup.d.ts.map

package/dist/brain/signup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signup.d.ts","sourceRoot":"","sources":["../../src/brain/signup.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAU3C;uEACuE;AACvE,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD,4CAA4C;AAC5C,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC;AAE5F,MAAM,WAAW,OAAO;IACtB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjD,mDAAmD;IACnD,KAAK,IAAI,IAAI,CAAC;CACf;AAoBD;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAkFrD;AAED;;;uEAGuE;AACvE,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;kEAYkE;AAClE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,oDAAoD;AACpD,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CASvG;AAED;;;;;2BAK2B;AAC3B,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAQ7C"}