@bevel-software/platform-core-backend 0.20.0 → 0.22.0

package/dist/modules/plugins/join-requests.service.js

@@ -1,52 +1,171 @@
-import { DEFAULT_BRANCH, isJoinBranchFor, } from '@bevel-software/platform-shared';
+import { isJoinBranchFor, } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 const log = logger('plugins');
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { rulesFileFor, } from '../access/access-requests.contract.js';
 import { pendingProposals } from './join-proposals.js';
 /**
- * Join requests as PROPOSALS, and the reconciliation that retires them.
+ * Access requests as PROPOSALS, and the reconciliation that retires them.
  *
  * The lifecycle has no state of its own — it is derived, every time, from two
- * copies of one file:
+ * copies of one file (a folder's `access.md`, or a file's own frontmatter):
  *
- *   open        the branch's `access.md` grants something the default's does not
+ *   open        the branch proposes something the person does not already hold
  *   settled     it does not
  *
- * so "approve" is not an operation on the request at all. A manager grants a
+ * so "approve" is not an operation on the request at all. An editor grants a
  * principal through the ordinary access path (the same lock + commit every
  * other access edit uses, gated the same way), the default branch gains that
- * entry, and the proposal stops being pending because the diff no longer
- * contains it. When the last one goes, the change request has nothing left to
- * say and is rejected, its branch deleted.
+ * entry, and the proposal stops being pending.
  *
- * That reconciliation runs LAZILY on every listing as well as on demand, so a
- * grant made anywhere — this banner, the Manage-access dialog, a hand edit —
- * settles the request that asked for it. Nothing has to remember to.
+ * "Does not already hold" is stronger than "is not in the file", and
+ * deliberately so: Owner covers Can edit, a parent folder's grant covers this
+ * one, and a role or group carries access without naming anybody. Each of
+ * those would leave a proposal nobody can usefully accept — accepting writes
+ * a grant that changes nothing — and the request would sit open forever. See
+ * {@link JoinRequestsService.unmetProposals}.
+ *
+ * That reconciliation runs LAZILY on every listing as well as on demand, so
+ * access gained anywhere — this banner, the Manage access dialog, a hand
+ * edit, a role someone joined — settles the request that asked for it.
+ * Nothing has to remember to.
  */
 export class JoinRequestsService {
     workspaceService;
     workflow;
-    constructor(workspaceService, workflow) {
+    kb;
+    accessControl;
+    constructor(workspaceService, workflow, kb, 
+    /**
+     * Read-only, and asked one question only: does this person already hold
+     * this verb on the item, on the DEFAULT branch? See {@link unmetProposals}.
+     */
+    accessControl) {
         this.workspaceService = workspaceService;
         this.workflow = workflow;
+        this.kb = kb;
+        this.accessControl = accessControl;
+    }
+    /**
+     * What `branch` still proposes for `target`, minus everything the person it
+     * names already holds — or NULL when the branch's own copy could not be read
+     * at all.
+     *
+     * That distinction is the whole point of the return type. "The branch says
+     * nothing" is NOT "the branch proposes nothing", and the two arrive as the
+     * same empty diff: `pendingProposals` reads an unreadable file as carrying
+     * no grants (fail-closed, which is right for deciding what to SHOW). Used as
+     * the settle test it is fail-open in the one direction that cannot be taken
+     * back — it closes a request nobody answered.
+     *
+     * And unreadable is the normal case for a few seconds. These reads go
+     * through `origin/<branch>` in the DEFAULT branch's clone, whose fetch is
+     * throttled; a request opened moments ago names a ref that clone has not
+     * heard of. So a miss is retried behind a FORCED fetch before it is believed,
+     * and if it still misses the caller is told nothing rather than something
+     * false.
+     */
+    async proposalsOn(branch, target, opts = {}) {
+        const rulesPath = rulesFileFor(target);
+        await this.refresh({ force: opts.fresh });
+        let branchText = await this.readAt(branch, rulesPath);
+        if (branchText === null && !opts.fresh) {
+            await this.refresh({ force: true });
+            branchText = await this.readAt(branch, rulesPath);
+        }
+        if (branchText === null)
+            return null;
+        // `kind` picks the grammar: a folder's rules are block lists in an
+        // access.md body, a file's are its own frontmatter, where one grant is
+        // written as a scalar. Reading one with the other's grammar yields no
+        // grants, which reads as a finished request.
+        const proposals = pendingProposals(branchText, await this.readAt(this.kb.defaultBranch, rulesPath), rulesPath, target.kind);
+        // Unreadable rules on the branch: say nothing rather than "nothing left".
+        if (proposals === null)
+            return null;
+        return this.unmetProposals(proposals, target);
     }
     /**
-     * Open join requests for `plugin`, each carrying only its still-pending
-     * proposals. Requests with none left are reconciled away (rejected, branch
-     * deleted) and omitted.
+     * Drop every proposal the live workspace has already ANSWERED, however it
+     * was answered.
+     *
+     * The file diff alone cannot see this. A request asking for `write` is
+     * satisfied by an `owner:` line, by a grant on a parent folder, or by a role
+     * or group the person has since joined — none of which put their email into
+     * this file, so the diff keeps reporting a proposal nobody can usefully
+     * accept (accepting writes a grant that changes nothing, and the request
+     * never retires). Asking the resolver the question the dialog's own grant
+     * would have to satisfy closes those requests instead of stranding them.
      *
-     * `actor` is who the reconciliation acts as — a manager of the plugin, since
+     * A proposal naming a ROLE keeps the literal rule: "does this role hold the
+     * verb here" is not a question the per-person resolver answers, and a role
+     * proposal is answered by the live rules carrying it.
+     */
+    async unmetProposals(proposals, target) {
+        const out = [];
+        for (const proposal of proposals) {
+            if (proposal.principal.kind !== 'user') {
+                out.push(proposal);
+                continue;
+            }
+            if (await this.holds(proposal.principal.email, proposal.verb, target.path))
+                continue;
+            out.push(proposal);
+        }
+        return out;
+    }
+    /**
+     * Does `email` hold `verb` on the ITEM, on the default branch? The verb
+     * folds are the resolver's own (owner covers write, write covers read), so
+     * this asks exactly what an accepted grant would have to achieve.
+     *
+     * Best-effort in ONE direction: a resolver that fails answers "no", which
+     * leaves the request open. A failure must never close somebody's request for
+     * them.
+     */
+    async holds(email, verb, itemPath) {
+        const wsId = this.kb.defaultWorkspaceId();
+        try {
+            switch (verb) {
+                case 'owner':
+                    return await this.accessControl.canOwner(wsId, email, itemPath);
+                case 'write':
+                    return await this.accessControl.canWrite(wsId, email, itemPath);
+                case 'download':
+                    return await this.accessControl.canDownload(wsId, email, itemPath);
+                default:
+                    return await this.accessControl.canRead(wsId, email, itemPath);
+            }
+        }
+        catch (err) {
+            log.warn(`could not resolve ${verb} on "${itemPath}" for a request: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    /**
+     * Open requests for one item, each carrying only what it still proposes.
+     * Requests with nothing left are reconciled away (rejected, branch deleted)
+     * and omitted.
+     *
+     * `key` is what named the branch (`joinBranchFor`) — a plugin's name for a
+     * Subscribe request, the item's own path for everything the Manage access
+     * dialog opens. `target` is the item whose rules those proposals edit; the
+     * two differ only for plugins, whose folder is not their name.
+     *
+     * `actor` is who the reconciliation acts as — an editor of the item, since
      * rejecting a change request requires write on everything it touches.
      */
-    async list(plugin, folder, crs, actor) {
-        await this.refresh();
-        const accessPath = `${folder}/access.md`;
-        const baseText = await this.readAt(DEFAULT_BRANCH, accessPath);
+    async list(key, target, crs, actor) {
         const out = [];
         for (const cr of crs) {
-            if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin))
+            if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, key))
+                continue;
+            const proposals = await this.confirmedProposals(cr.branch, target);
+            // Unreadable: leave it exactly as it is. There is nothing to offer an
+            // editor and nothing that says it is finished, and closing it on a read
+            // that failed would end somebody's request for them. It stays in Change
+            // requests for you, where it can still be answered by hand.
+            if (proposals === null)
                 continue;
-            const proposals = pendingProposals(await this.readAt(cr.branch, accessPath), baseText, accessPath);
             if (proposals.length === 0) {
                 await this.settle(cr, actor);
                 continue;
@@ -66,17 +185,40 @@ export class JoinRequestsService {
      * it was settled. Called right after a grant so the banner updates in the
      * same round-trip instead of waiting for the next listing.
      */
-    async reconcile(plugin, folder, cr, actor) {
-        if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, plugin))
+    async reconcile(key, target, cr, actor) {
+        if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, key))
             return false;
-        await this.refresh();
-        const accessPath = `${folder}/access.md`;
-        const proposals = pendingProposals(await this.readAt(cr.branch, accessPath), await this.readAt(DEFAULT_BRANCH, accessPath), accessPath);
-        if (proposals.length > 0)
+        const proposals = await this.confirmedProposals(cr.branch, target);
+        // Same rule as the listing: only a branch that was READ and, on a fresh
+        // read, proposes nothing is finished.
+        if (proposals === null || proposals.length > 0)
             return false;
         await this.settle(cr, actor);
         return true;
     }
+    /**
+     * What the branch proposes, with an EMPTY answer confirmed against freshly
+     * fetched refs before anyone acts on it. Null keeps its meaning: nothing
+     * could be read, so nothing can be said.
+     *
+     * The confirmation is there because an empty answer is the terminal one.
+     * These reads go through `origin/<branch>` in the default branch's clone,
+     * and that clone's fetch is throttled — so a branch whose remote-tracking
+     * ref is a few seconds old answers with the commit BEFORE the proposal was
+     * pushed. That is a file identical to live, which is an empty diff, which
+     * reads as "every grant has landed". A request nobody answered is then
+     * closed, its branch deleted, and the person told it was not accepted.
+     *
+     * One extra fetch, on the one path that cannot be undone — and when that
+     * fetch turns up a proposal after all, it is the answer, not a discarded
+     * second opinion.
+     */
+    async confirmedProposals(branch, target) {
+        const first = await this.proposalsOn(branch, target);
+        if (first === null || first.length > 0)
+            return first;
+        return this.proposalsOn(branch, target, { fresh: true });
+    }
     /**
      * Close a request whose proposals have all landed, and delete its branch.
      *
@@ -90,7 +232,7 @@ export class JoinRequestsService {
      * next pass tries again.
      */
     async settle(cr, actor) {
-        const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+        const wsId = this.kb.defaultWorkspaceId();
         try {
             await this.workflow.rejectChangeRequest(cr.number, actor, cr.state, cr.authorId ?? null, cr.base, wsId);
         }
@@ -117,7 +259,7 @@ export class JoinRequestsService {
      */
     async readAt(branch, repoRelPath) {
         try {
-            return await this.workspaceService.readFileAtRef(workspaceIdForBranch(DEFAULT_BRANCH), `origin/${branch}`, repoRelPath);
+            return await this.workspaceService.readFileAtRef(this.kb.defaultWorkspaceId(), `origin/${branch}`, repoRelPath);
         }
         catch {
             return null;
@@ -127,10 +269,13 @@ export class JoinRequestsService {
      * Refresh remote-tracking refs before reading them. Throttled inside, and
      * best-effort: a request pushed seconds ago is worth one fetch, but a fetch
      * failure must degrade to "read what we have" rather than empty the list.
+     *
+     * `force` skips the throttle — for the one caller that has already missed
+     * and must not mistake a stale ref list for an answer.
      */
-    async refresh() {
+    async refresh(opts = {}) {
         await this.workspaceService
-            .ensureRemotesFetched(workspaceIdForBranch(DEFAULT_BRANCH))
+            .ensureRemotesFetched(this.kb.defaultWorkspaceId(), opts)
             .catch(() => undefined);
     }
 }

package/dist/modules/plugins/join-requests.service.js.map

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

package/dist/modules/plugins/plugin-links.d.ts

@@ -1,4 +1,5 @@
 import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import type { ISkillService } from '../skills/skills.contract.js';
 import type { PluginMembership } from './plugins.contract.js';
@@ -15,9 +16,32 @@ export interface PluginLinks {
     linkedSkills: string[];
     /** Roots that resolve to no released skill — a typo, or a skill not yet merged. */
     unresolvedRoots: string[];
+    /**
+     * The declared roots whose OWN access file does not carry this plugin's two
+     * grant lines, each with the linked skills its members cannot read through
+     * it — the automatic repair's work list, and the only thing that says WHICH
+     * file to write (`brokenLinks` counts skills, and a root holding twenty of
+     * them is still one file). Empty for an unmanaged (dialect) plugin, whose
+     * links grant nothing, and for a plugin whose links are all healthy.
+     */
+    ungrantedRoots: UngrantedRoot[];
     /** Whether hexis writes these links and checks their grants — see `DiscoveredPlugin`. */
     linksAreManaged: boolean;
 }
+/** One declared root missing its grants, with the skills that go without. */
+export interface UngrantedRoot {
+    /** Repo-relative root, exactly as the manifest declares it. */
+    root: string;
+    /** The released skill folders under it the plugin's members cannot read. */
+    skills: string[];
+}
+/**
+ * The two verbs a link grants — the pair `PluginLinksService.grantTokens`
+ * writes and this index looks for. `owner` is deliberately not one of them: a
+ * link shares a skill and lets the plugin's managers edit it; it never hands
+ * over who validates it.
+ */
+export declare const LINK_GRANT_VERBS: readonly ["read", "write"];
 export interface LinkMembership {
     /** skill path → every plugin that holds it, inline or by link. */
     bySkill: Map<string, PluginMembership[]>;
@@ -36,10 +60,15 @@ export interface LinkMembership {
  * and the global-name dedup, and a second walk here would be a second
  * opinion about what a skill is.
  *
- * `granted` is the consistency check the amber dot renders: a linked skill
- * whose own access rules DO grant the plugin's `plugin/<Name>/read`
- * principal (directly or from a scope above it). The link service writes
- * that grant with the link; only a hand edit takes it away.
+ * `granted` is the consistency check the amber dot renders, and it is a
+ * question about the FILE, not about who happens to be able to read the skill
+ * today: a link is granted when the declared ROOT's own access file carries
+ * both `plugin/<Name>/read` and `plugin/<Name>/write`, and neither is denied
+ * at that root or between it and the skill. A root that is readable by
+ * everyone, or that inherits a plugin grant from a folder above, is NOT
+ * granted — the grant is the link's contract, and a public root merely hides
+ * its absence until the day someone restricts the tree. The link service
+ * writes those two lines with the link; only a hand edit takes them away.
  *
  * Cached briefly, dropped by `invalidate()` from the same file-change
  * subscriber that drops the plugin index, so a link committed on the default
@@ -49,21 +78,47 @@ export declare class PluginLinkIndex {
     private readonly workspaceService;
     private readonly skillService;
     private readonly accessControl;
-    private readonly kbDirName;
+    private readonly kb;
     /** Where plugins come from — the one discovery every catalog shares. */
     private readonly source;
     private readonly cache;
-    constructor(workspaceService: WorkspaceService, skillService: ISkillService, accessControl: IAccessControl, kbDirName: string, 
+    constructor(workspaceService: WorkspaceService, skillService: ISkillService, accessControl: IAccessControl, kb: KbContext, 
     /** Where plugins come from — the one discovery every catalog shares. */
     source: PluginSource, now?: () => number);
+    private get kbDirName();
     invalidate(): void;
     membership(): Promise<LinkMembership>;
     /** Convenience: the memberships of one skill (empty when it is in no plugin). */
     pluginsOf(skillPath: string): Promise<PluginMembership[]>;
     private build;
-    /** Whether the skill folder's effective readers include the plugin's read principal. */
-    private isGranted;
+    /**
+     * Whether the ROOT's own access file carries both of the link's grant lines.
+     *
+     * "Its own" is the whole rule: `grantSources` reports every scope that
+     * grants the principal, closest-first, so `[0].kind === 'direct'` is
+     * "granted by the file this root's link writes" — a grant inherited from a
+     * folder above is an `ancestor` source and does not count, and a root that
+     * is simply public names the principal nowhere and yields no source at all.
+     * `tokenMatch: 'exact'` pins the comparison to the canonical token the
+     * grant is written as, the same spelling `grantTokens` splices.
+     *
+     * A `deny` of either token in that same file is not granted either, whatever
+     * the resolver makes of a grant beside it: the deny is the operator's, the
+     * repair never removes it, and reporting the link as healthy would hide the
+     * one thing the banner exists to say. `locallyDeniedPrincipals` is what sees
+     * it — the per-verb denial walk cannot, since a grant in the same scope wins
+     * there and ends the walk.
+     */
+    private rootCarriesGrants;
+    /**
+     * Whether either grant is DENIED below the root — at the skill's own folder
+     * or at anything between it and the root.
+     *
+     * The denial walk stops at a closer grant, and the root's grant is what
+     * brought us here, so what this reports is exactly the scopes under the
+     * root: a `deny` above the root is dead under closeness-first and is not
+     * this link's problem.
+     */
+    private deniedBetween;
 }
-/** The default-branch workspace id every link resolution runs against. */
-export declare function linksWorkspaceId(): string;
 //# sourceMappingURL=plugin-links.d.ts.map

package/dist/modules/plugins/plugin-links.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-links.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugin-links.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAIjE,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mFAAmF;IACnF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;gBAG9B,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,EAC3B,aAAa,EAAE,cAAc,EAC7B,SAAS,EAAE,MAAM;IAClC,wEAAwE;IACvD,MAAM,EAAE,YAAY,EACrC,GAAG,GAAE,MAAM,MAAiB;IAK9B,UAAU,IAAI,IAAI;IAIZ,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC;IAgB3C,iFAAiF;IAC3E,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAMjD,KAAK;IAoEnB,wFAAwF;YAC1E,SAAS;CAUxB;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}
+{"version":3,"file":"plugin-links.d.ts","sourceRoot":"","sources":["../../../src/modules/plugins/plugin-links.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAIjE,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mFAAmF;IACnF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;OAOG;IACH,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,4BAA6B,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;gBAG9B,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,EAC3B,aAAa,EAAE,cAAc,EAC7B,EAAE,EAAE,SAAS;IAC9B,wEAAwE;IACvD,MAAM,EAAE,YAAY,EACrC,GAAG,GAAE,MAAM,MAAiB;IAK9B,OAAO,KAAK,SAAS,GAEpB;IAED,UAAU,IAAI,IAAI;IAIZ,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC;IAgB3C,iFAAiF;IAC3E,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAMjD,KAAK;IA8GnB;;;;;;;;;;;;;;;;;OAiBG;YACW,iBAAiB;IAkB/B;;;;;;;;OAQG;YACW,aAAa;CAe5B"}