@floh-solutions/pharos-cli 0.23.0 → 0.25.0

package/dist/output.js

@@ -1,4 +1,5 @@
 import { AdoAuthError, AdoConcurrencyError, AdoConfigError, AdoError, AdoNetworkError, AdoNotFoundError, AdoRateLimitError, adviceFor, deletionAdvice, namesAResourcePermission, } from "@floh-solutions/ado-core";
+import { GhUnavailableError, GitHubAccountError, GitHubAuthError, GitHubConfigError, GitHubError, GitHubGraphQLError, GitHubIdentityMismatchError, GitHubNetworkError, GitHubNotFoundError, GitHubRateLimitError, GitHubValidationError, IssueEditConflictError, PullRequestNotAnIssueError, UnknownLabelError, } from "@floh-solutions/gh-core";
 /**
  * The output contract.
  *
@@ -99,6 +100,20 @@ export function reportError(io, error) {
     io.stderr(JSON.stringify({ error: body }, undefined, 2));
     return code;
 }
+/**
+ * The same classification `reportError` uses, without emitting anything.
+ *
+ * For the one shape that needs it: a verb that has **already written one half of
+ * something** when the second half fails. `pharos issue adopt` creates the work
+ * item and then comments on the issue, so a failure at the second step must
+ * report the first step's result rather than only the error — otherwise the work
+ * item exists and nothing anywhere names it. Re-classifying by hand there would
+ * be a second, drifting copy of this table.
+ */
+export function failureOf(error) {
+    const { body, code } = describe(error);
+    return { kind: body["kind"] ?? "internal", code, body };
+}
 function describe(error) {
     if (error instanceof CliError) {
         return {
@@ -114,6 +129,9 @@ function describe(error) {
             code: error.exitCode,
         };
     }
+    const github = describeGitHub(error);
+    if (github !== undefined)
+        return github;
     if (error instanceof AdoConcurrencyError) {
         return {
             body: {
@@ -206,6 +224,281 @@ function describe(error) {
         code: EXIT_FAILED,
     };
 }
+/**
+ * The GitHub half of the same table, and the reason it is not optional.
+ *
+ * Without it every failure from `gh-core` falls through to `kind: "internal"`
+ * with exit 1 — so "this repository is not in repos.json" (fix the file, never
+ * retry), "`gh` is not installed" (fix the machine), and "you are over the
+ * hourly budget" (wait exactly this long and repeat) all arrive looking like one
+ * unexplained crash. Exit 1 additionally *invites* a retry, which is wrong for
+ * two of those three.
+ *
+ * Every body here carries `platform: "github"`, because on this bridge a verb
+ * touches two platforms in one invocation and "which side said no" is the first
+ * thing an agent needs. Its absence means Azure DevOps or this CLI, which is
+ * what it already meant.
+ *
+ * `undefined` when the error is not GitHub's, so the caller falls through.
+ */
+function describeGitHub(error) {
+    /**
+     * The lost-update guard said no, and this is the one GitHub failure an agent
+     * should treat exactly as it treats {@link AdoConcurrencyError}: the work is
+     * still good, re-read and re-apply.
+     *
+     * `kind: "conflict"` is deliberate and it is the same word the Azure DevOps
+     * side uses, because the skill teaches branching on it. What differs is the
+     * `hint`: on Azure DevOps a rev mismatch is not proof of an edit collision, so
+     * the advice is "diff the fields you changed". Here it **is** proof — the
+     * guard compares the field's own value and nothing else moves it — so the
+     * advice is simply to take the newer text into account.
+     */
+    if (error instanceof IssueEditConflictError) {
+        return {
+            body: {
+                kind: "conflict",
+                platform: "github",
+                message: error.message,
+                repo: error.repo,
+                number: error.number,
+                conflicts: error.conflicts,
+                attribution: error.attribution,
+                hint: "Somebody changed the exact field you were overwriting. Re-read the issue, fold their "
+                    + "change into yours, and edit again — passing --if-title/--if-body so the next attempt "
+                    + "is guarded against what you just read. This is NOT the Azure DevOps rev case: a "
+                    + "comment cannot cause it, so it is a real collision.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    /**
+     * A label the repository does not have. Exit 3, with the rest of the
+     * refusals, because it is cleared by asking again more explicitly —
+     * `--create-label` — which is exactly what that exit code means here.
+     */
+    if (error instanceof UnknownLabelError) {
+        return {
+            body: {
+                kind: "refused",
+                platform: "github",
+                message: error.message,
+                repo: error.repo,
+                unknown: error.unknown,
+                suggestions: error.suggestions,
+                hint: "Fix the spelling, or pass --create-label if you really mean to add a new label to the "
+                    + "repository. It is off by default because GitHub creates one silently.",
+            },
+            code: EXIT_REFUSED,
+        };
+    }
+    // A repo that is not in repos.json, an account `gh` has no token for, a
+    // missing `gh`: all configuration, all exit 2. Retrying is pure noise, and the
+    // messages `gh-core` raises already name the file or the command to run.
+    if (error instanceof GitHubConfigError) {
+        return { body: { kind: "config", platform: "github", message: error.message }, code: EXIT_USAGE };
+    }
+    if (error instanceof GitHubAccountError) {
+        return {
+            body: {
+                kind: "auth",
+                platform: "github",
+                message: error.message,
+                account: error.account,
+                hint: `gh holds no usable token for "${error.account}". Sign that account in with `
+                    + `\`gh auth login\`, or fix the binding with \`pharos setup --repo <owner/name> `
+                    + "--gh-account <login>`. `pharos doctor` reports both.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof GhUnavailableError) {
+        return {
+            body: {
+                kind: "config",
+                platform: "github",
+                message: error.message,
+                hint: "Install it with `pharos setup --install gh`, then `pharos doctor`.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    // **A 200 from the wrong identity** — plan §2's whole reason for existing. Not
+    // a transport failure and not retryable: the configuration says one thing and
+    // the credential answered as somebody else.
+    if (error instanceof GitHubIdentityMismatchError) {
+        return {
+            body: {
+                kind: "config",
+                platform: "github",
+                message: error.message,
+                account: error.account,
+                expected: error.expected,
+                actual: error.actual,
+                hint: "The account this repository is bound to is not the one that answered. Check repos.json "
+                    + "and confirm with `pharos doctor --verify`.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof PullRequestNotAnIssueError) {
+        return {
+            body: {
+                kind: "usage",
+                platform: "github",
+                message: error.message,
+                repo: error.repo,
+                number: error.number,
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof GitHubRateLimitError) {
+        return {
+            body: {
+                kind: "rateLimit",
+                platform: "github",
+                message: error.message,
+                status: error.status,
+                retryAfterMs: error.retryAfterMs,
+                // A primary limit is the hourly 5,000 and can be most of an hour out; a
+                // secondary one is a burst and clears in seconds. Same advice, wildly
+                // different wait, so the caller is told which it is.
+                primary: error.primary,
+                requestId: error.requestId,
+                hint: "Wait retryAfterMs and repeat the identical call.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof GitHubAuthError) {
+        return { body: githubBody("auth", error), code: EXIT_USAGE };
+    }
+    if (error instanceof GitHubNotFoundError) {
+        return {
+            body: {
+                ...githubBody("notFound", error),
+                // GitHub answers 404 rather than 403 for a private repository you may
+                // not see — confirming it existed would be the leak. So "no such issue"
+                // and "wrong account" are one status code, and the account is the first
+                // thing to check rather than the last.
+                hint: "On GitHub a 404 is also how \"not visible to this account\" is spelled. Check the "
+                    + "binding with `pharos doctor --verify` before concluding the issue does not exist.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof GitHubValidationError) {
+        return {
+            // 422: understood and refused. Repeating it unchanged cannot work, which
+            // is exactly what exit 2 means here.
+            body: { ...githubBody("github", error), errors: error.errors },
+            code: EXIT_USAGE,
+        };
+    }
+    /**
+     * **A GraphQL refusal, which arrives as an HTTP 200 and so has no status to
+     * classify by.**
+     *
+     * `GitHubGraphQLError` is deliberately not a {@link GitHubError} (see its own
+     * doc), so without this arm it fell through to `kind: "internal"` — measured
+     * live on #827 against a bad node id. That label is actively wrong: `internal`
+     * means *this tool* broke, so an agent reading it goes looking for a defect
+     * here while GitHub is simply saying no.
+     *
+     * The split below is by **who has to act**, which is the only distinction
+     * worth drawing:
+     *
+     * - GitHub's own classifiers (`NOT_FOUND`, `FORBIDDEN`, `RATE_LIMITED`) are
+     *   answers about the request, and map onto the same kinds their REST
+     *   equivalents get. The caller acts.
+     * - A **query-validation** code (`undefinedField`, `argumentLiteralsIncompatible`,
+     *   `variableMismatch` …) carries no `type` at all — GitHub puts it in
+     *   `extensions.code`. Those mean the query this package sent is malformed,
+     *   which is a defect in `gh-core` and not something the caller did. `internal`
+     *   is the honest label for exactly those, and it stays.
+     */
+    if (error instanceof GitHubGraphQLError) {
+        const kind = GRAPHQL_KINDS[error.type ?? ""];
+        return {
+            body: {
+                kind: kind?.kind ?? "internal",
+                platform: "github",
+                message: error.message,
+                operation: error.operation,
+                account: error.account,
+                // GitHub's classifier, verbatim, so a caller can branch on something
+                // finer than our kinds without us having to predict which.
+                graphQLType: error.type ?? null,
+                ...(kind === undefined
+                    ? {
+                        hint: "GitHub accepted the request and refused the operation, and gave no classifier — "
+                            + "which is what a malformed query looks like. This is a defect in gh-core rather "
+                            + "than something to retry.",
+                    }
+                    : { hint: kind.hint }),
+            },
+            code: kind?.code ?? EXIT_FAILED,
+        };
+    }
+    if (error instanceof GitHubError) {
+        return { body: githubBody("github", error), code: EXIT_FAILED };
+    }
+    if (error instanceof GitHubNetworkError) {
+        return {
+            body: {
+                kind: "network",
+                platform: "github",
+                message: error.message,
+                method: error.method,
+                url: error.url,
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    return undefined;
+}
+/**
+ * GitHub's GraphQL classifiers, mapped onto the kinds an agent already branches
+ * on. Anything absent from here is a query-validation code and stays
+ * `internal` — see the call site.
+ */
+const GRAPHQL_KINDS = {
+    NOT_FOUND: {
+        kind: "notFound",
+        code: EXIT_FAILED,
+        hint: "The node id names nothing this account can see. On GitHub that is also how \"not visible "
+            + "to you\" is spelled, so check the binding before concluding it is gone. "
+            + "`pharos comment list <owner/name#n>` prints the current ids.",
+    },
+    FORBIDDEN: {
+        kind: "auth",
+        code: EXIT_USAGE,
+        hint: "The account is authenticated and not permitted to do this. Hiding and pinning need write "
+            + "access to the repository; `pharos comment list` reports what each comment permits in "
+            + "its `may` object, which is cheaper than finding out this way.",
+    },
+    RATE_LIMITED: {
+        kind: "rateLimit",
+        code: EXIT_FAILED,
+        hint: "GraphQL has its own hourly budget, separate from REST's 5,000. Wait and repeat the "
+            + "identical call.",
+    },
+};
+function githubBody(kind, error) {
+    return {
+        kind,
+        platform: "github",
+        message: error.message,
+        status: error.status,
+        method: error.method,
+        url: error.url,
+        // GitHub's handle for a request, and the only one their support accepts —
+        // the same role `activityId` plays on the Azure DevOps side.
+        requestId: error.requestId,
+        ...(error.documentationUrl === undefined ? {} : { documentationUrl: error.documentationUrl }),
+    };
+}
 /**
  * An Azure DevOps failure, with **what to do about it** where that is known.
  *

package/dist/output.js.map

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

package/dist/session.d.ts

@@ -1,5 +1,7 @@
 import { AdoClient, WikiApi } from "@floh-solutions/ado-core";
+import type { GitHubClient } from "@floh-solutions/gh-core";
 import { WriteBudget } from "./budget.js";
+import { HalfLinkJournal } from "./half-link.js";
 import { type ExitCode, type Io } from "./output.js";
 /**
  * One invocation's world: the client, the budget it spends against, the wiki it
@@ -19,16 +21,87 @@ export interface SessionOptions {
     pretty: boolean;
     /** Injected by tests; production passes nothing and gets a real client. */
     client?: AdoClient | undefined;
+    /** Injected by tests; production passes nothing and gets one from `repos.json`. */
+    github?: GitHubClient | undefined;
 }
 export declare class Session {
     #private;
-    readonly client: AdoClient;
-    readonly wiki: WikiApi;
     readonly budget: WriteBudget;
     readonly apply: boolean;
     readonly previewOnly: boolean;
     readonly pretty: boolean;
+    /**
+     * Adoptions this machine started and did not finish — see `half-link.ts`.
+     *
+     * Built from the invocation's environment rather than reached for inside the
+     * command, so a run whose env names no `HOME` has no journal instead of
+     * quietly writing into whichever home directory the process happens to have.
+     */
+    readonly halfLinks: HalfLinkJournal;
     constructor(options: SessionOptions);
+    /**
+     * The Azure DevOps client — **resolved on first use, not in the constructor.**
+     *
+     * It was built eagerly, and that made `ADO_PAT` the price of entry to the
+     * whole CLI: `pharos comment list contoso/widgets#45` reads a GitHub issue
+     * through `gh-core` with the `gh` credential and never touches Azure DevOps,
+     * and it answered `{"kind":"config","message":"ADO_PAT is not set…"}` (#839).
+     * Somebody with `gh` signed in and no Azure DevOps PAT — a state
+     * `pharos doctor` reports as fine, and which the separate Keychain entries
+     * exist to make possible — could not use a single GitHub verb.
+     *
+     * {@link github} was made lazy for exactly this reason (#782) and this half
+     * was not. The fix belongs here rather than in the `comment` dispatch: any
+     * verb family that grows a GitHub target inherits it, and a special case in
+     * one command is a special case the next one has to remember.
+     *
+     * **Resolution failure is deferred, never softened.** The `AdoConfigError`
+     * still names the missing variable and still exits 2 — it arrives when
+     * something actually needs Azure DevOps, which is where it is an answer
+     * rather than an obstacle. See {@link approve} for the one place that
+     * ordering has to be forced.
+     */
+    get client(): AdoClient;
+    /** The wiki API, over {@link client}'s transport — and lazy for its sake. */
+    get wiki(): WikiApi;
+    /**
+     * The GitHub client, resolved once, from `~/.config/pharos/repos.json`.
+     *
+     * Three things about this are deliberate.
+     *
+     * **Its fetch is wrapped by the same {@link WriteBudget} the Azure DevOps
+     * client uses.** `--max-writes 0` promises that an invocation cannot change
+     * anything, and that promise is worthless if it covers one platform of a
+     * two-platform verb: `pharos issue adopt` posts a comment on GitHub, and a cap
+     * that let that through would be a cap in name only. `gh-core`'s transport
+     * already recognises a refusal thrown by a fetch wrapper and rethrows it
+     * unretried rather than reporting it as a dead socket.
+     *
+     * **It is loaded lazily, and imported dynamically.** Twenty-seven of the
+     * twenty-eight verbs here never touch GitHub, and `gh-core` reaches for
+     * `node:child_process` at import time to talk to `gh`. `doctor` does the same
+     * thing for the same reason.
+     *
+     * **There is no repository default.** `GitHubClient` has no current repo and
+     * no current account by construction (plan §2) — every call names both, and an
+     * unbound repository is an error naming `repos.json` rather than a guess at
+     * whichever `gh` account happens to be active.
+     */
+    github(): Promise<GitHubClient>;
+    /**
+     * The web address of a work item — what a person clicks, not what the API
+     * reads.
+     *
+     * `WorkItem.url` is the REST url and opening it in a browser gives JSON, so a
+     * comment on a public GitHub issue carrying it would be worse than carrying
+     * nothing. `_links.html.href` is what Azure DevOps itself calls the human
+     * address; it is only present when the read asked for links, so the composed
+     * form is the fallback rather than the other way round.
+     */
+    workItemUrl(item: {
+        id: number;
+        _links?: Record<string, unknown>;
+    }): string;
     /**
      * The wiki to act on, resolved once.
      *
@@ -53,6 +126,16 @@ export interface DestructiveAction {
     what: string;
     /** The structured version, emitted either way so a preview is machine-readable. */
     would: Record<string, unknown>;
+    /**
+     * Which platform is about to be written to. Defaults to `"ado"`.
+     *
+     * It exists so {@link approve} can put the two refusals in the right order —
+     * see its doc. Azure DevOps is the default because it is what all but one of
+     * the destructive verbs here write to, and because the failure mode of
+     * forgetting the flag is loud (a GitHub-only verb starts demanding a PAT,
+     * which is #839 and has a test) rather than silent.
+     */
+    platform?: "ado" | "github" | undefined;
 }
 /**
  * The gate in front of anything that destroys or overwrites.
@@ -71,6 +154,22 @@ export interface DestructiveAction {
  * is how a half-finished job gets reported as done (`docs/pharos-cli-plan.md`
  * §2.5). `--dry-run` exits 0 because there the preview IS the deliverable.
  *
+ * ## The credential is checked before the gate, and that ordering is the point
+ *
+ * {@link Session.client} resolves on first use (#839), and every arm below
+ * runs *before* the verb touches it. So on a machine with no `ADO_PAT`,
+ * `pharos comment delete 210 5` would answer "Refusing to delete comment 5 on
+ * #210 without --yes" — a refusal that invites a retry with `--yes` which then
+ * fails on the credential anyway. Two refusals, the useful one second.
+ *
+ * Touching the client here puts the credential failure back in front, exactly
+ * where it was when the client was eager. A `--dry-run` preview of an Azure
+ * DevOps write is refused for the same reason: a preview of something this
+ * machine cannot do is a preview of nothing.
+ *
+ * A GitHub action says so and is exempt — that is the whole bug this ordering
+ * has to avoid recreating.
+ *
  * @returns `undefined` to proceed with the write, or the exit code to return.
  */
 export declare function approve(io: Io, session: Session, action: DestructiveAction): ExitCode | undefined;

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAgB,MAAM,0BAA0B,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzF;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAKb,OAAO,EAAE,cAAc;IAkBnC;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,wEAAwE;IAClE,cAAc,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAiDrF;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAYjG"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAgB,MAAM,0BAA0B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzF;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,mFAAmF;IACnF,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACnC;AAED,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;gBAWxB,OAAO,EAAE,cAAc;IAcnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAI,MAAM,IAAI,SAAS,CAQtB;IAED,6EAA6E;IAC7E,IAAI,IAAI,IAAI,OAAO,CAGlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAerC;;;;;;;;;OASG;IACH,WAAW,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;IAQ3E;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,wEAAwE;IAClE,cAAc,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAiDrF;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAejG"}