@miller-tech/uap 1.165.0 → 1.168.0

package/dist/cli/merge-queue.d.ts

@@ -0,0 +1,53 @@
+import { type OwnershipMap } from '../coordination/ownership.js';
+export interface QueueOptions {
+    dryRun?: boolean;
+    limit?: number;
+    /** Land PRs even when their checks are not green (never the default). */
+    force?: boolean;
+    /** Required to actually merge. Without it the queue only prints its plan. */
+    yes?: boolean;
+}
+/**
+ * Landing is irreversible and unattended, so the default must not merge.
+ * `uap merge queue` with no flags prints the plan; `--yes` commits to it.
+ */
+export declare const DEFAULT_QUEUE_LIMIT = 10;
+export interface PullRequest {
+    number: number;
+    title: string;
+    headRefName: string;
+    isDraft: boolean;
+    updatedAt: string;
+    labels: string[];
+    files: string[];
+}
+/** Open, non-draft PRs with their changed-file lists. */
+export declare function fetchOpenPrs(cwd?: string): PullRequest[];
+/** Files touched by both PRs — the direct textual-conflict surface. */
+export declare function overlappingFiles(a: PullRequest, b: PullRequest): string[];
+/**
+ * Landing order. Mirrors TaskCoordinator.getMergeOrderSuggestion's intent —
+ * urgent and small first — but operates on PRs, which is where merges actually
+ * happen. Ordering is deterministic so a dry-run plan matches the real run.
+ */
+export declare function orderQueue(prs: PullRequest[]): PullRequest[];
+/**
+ * PRs that will need a re-sync once `landed` is on the base branch.
+ *
+ * Shared FILES are the certain case. Shared LANES (per .uap/ownership.json) catch
+ * the semantic case that file overlap misses entirely: two PRs editing different
+ * files in the same module, each green alone, broken together. That is exactly how
+ * PR #577 turned master red — it touched infra while a test asserting the opposite
+ * lived in a file it never opened.
+ */
+export declare function impactedBy(landed: PullRequest, remaining: PullRequest[], map?: OwnershipMap): PullRequest[];
+export type ChecksVerdict = 'green' | 'red' | 'pending' | 'none';
+/**
+ * Classify `gh pr checks` output. Collapsing everything non-zero into "red" was
+ * wrong in two ways that both stop the queue dead: a repo with NO CI (exit 8)
+ * could never land anything, and a PR whose checks are still running after the
+ * previous merge's re-sync got reported as failing rather than waited on.
+ */
+export declare function checksVerdict(exitCode: number, output: string): ChecksVerdict;
+export declare function mergeQueueCommand(options?: QueueOptions): Promise<void>;
+//# sourceMappingURL=merge-queue.d.ts.map

package/dist/cli/merge-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-queue.d.ts","sourceRoot":"","sources":["../../src/cli/merge-queue.ts"],"names":[],"mappings":"AAeA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEnG,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAmBD,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAwBxD;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,MAAM,EAAE,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAqB5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,WAAW,EAAE,EACxB,GAAG,CAAC,EAAE,YAAY,GACjB,WAAW,EAAE,CAGf;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAK7E;AAgCD,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuGjF"}

package/dist/cli/merge-queue.js

@@ -0,0 +1,239 @@
+/**
+ * `uap merge queue` — serialized landing of concurrent agent PRs.
+ *
+ * Per-PR gates prove a branch is green against the base it was CUT from. They
+ * cannot see the semantic conflict where two independently-green PRs break each
+ * other once both are on master. That is not hypothetical here: PR #577 landed a
+ * legitimate docker-compose file while a stale hygiene test on master asserted
+ * the file's absence — both sides green in isolation, master CI red on merge,
+ * blocking every version bump in the repo until someone noticed.
+ *
+ * The queue closes that hole: land ONE PR at a time, then re-sync and re-check
+ * every remaining PR against the tip that actually landed, before the next merge.
+ */
+import chalk from 'chalk';
+import { execFileSync } from 'child_process';
+import { loadOwnershipMap, assessConflict } from '../coordination/ownership.js';
+/**
+ * Landing is irreversible and unattended, so the default must not merge.
+ * `uap merge queue` with no flags prints the plan; `--yes` commits to it.
+ */
+export const DEFAULT_QUEUE_LIMIT = 10;
+/** Run `gh` and return stdout. Throws with a readable message on failure. */
+function gh(args, cwd) {
+    try {
+        // maxBuffer: `pr list --json files` over 100 PRs blows the 1 MB default and
+        // surfaces as a bare "gh failed". timeout: an auth prompt otherwise hangs forever.
+        return execFileSync('gh', args, {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 120_000,
+            maxBuffer: 32 * 1024 * 1024,
+        }).trim();
+    }
+    catch (err) {
+        const e = err;
+        throw new Error(`gh ${args.join(' ')} failed: ${e.stderr || e.message || 'unknown error'}`);
+    }
+}
+/** Open, non-draft PRs with their changed-file lists. */
+export function fetchOpenPrs(cwd) {
+    const raw = gh(['pr', 'list', '--state', 'open', '--limit', '100', '--json',
+        'number,title,headRefName,isDraft,updatedAt,labels,files'], cwd);
+    const parsed = JSON.parse(raw);
+    return parsed.map((p) => ({
+        number: p.number,
+        title: p.title,
+        headRefName: p.headRefName,
+        isDraft: p.isDraft,
+        updatedAt: p.updatedAt,
+        labels: (p.labels ?? []).map((l) => l.name),
+        files: (p.files ?? []).map((f) => f.path),
+    }));
+}
+/** Files touched by both PRs — the direct textual-conflict surface. */
+export function overlappingFiles(a, b) {
+    const bSet = new Set(b.files);
+    return a.files.filter((f) => bSet.has(f));
+}
+/**
+ * Landing order. Mirrors TaskCoordinator.getMergeOrderSuggestion's intent —
+ * urgent and small first — but operates on PRs, which is where merges actually
+ * happen. Ordering is deterministic so a dry-run plan matches the real run.
+ */
+export function orderQueue(prs) {
+    const priorityOf = (p) => {
+        const labels = p.labels.map((l) => l.toLowerCase());
+        if (labels.some((l) => l.includes('p0') || l.includes('critical')))
+            return 0;
+        if (labels.some((l) => l.includes('hotfix') || l.includes('security')))
+            return 0;
+        if (labels.some((l) => l.includes('bug') || l.includes('fix')))
+            return 1;
+        if (/^(fix|hotfix)\//.test(p.headRefName))
+            return 1;
+        if (labels.some((l) => l.includes('p1')))
+            return 1;
+        if (/^chore\//.test(p.headRefName) || /^docs\//.test(p.headRefName))
+            return 3;
+        return 2;
+    };
+    return [...prs].sort((a, b) => {
+        const pa = priorityOf(a);
+        const pb = priorityOf(b);
+        if (pa !== pb)
+            return pa - pb;
+        // Smaller diffs land more predictably and unblock others sooner.
+        if (a.files.length !== b.files.length)
+            return a.files.length - b.files.length;
+        // Oldest first — long-lived branches drift most, so stop the bleeding.
+        return a.updatedAt.localeCompare(b.updatedAt);
+    });
+}
+/**
+ * PRs that will need a re-sync once `landed` is on the base branch.
+ *
+ * Shared FILES are the certain case. Shared LANES (per .uap/ownership.json) catch
+ * the semantic case that file overlap misses entirely: two PRs editing different
+ * files in the same module, each green alone, broken together. That is exactly how
+ * PR #577 turned master red — it touched infra while a test asserting the opposite
+ * lived in a file it never opened.
+ */
+export function impactedBy(landed, remaining, map) {
+    const lanes = map ?? { lanes: {} };
+    return remaining.filter((p) => assessConflict(landed.files, p.files, lanes).conflicts);
+}
+/**
+ * Classify `gh pr checks` output. Collapsing everything non-zero into "red" was
+ * wrong in two ways that both stop the queue dead: a repo with NO CI (exit 8)
+ * could never land anything, and a PR whose checks are still running after the
+ * previous merge's re-sync got reported as failing rather than waited on.
+ */
+export function checksVerdict(exitCode, output) {
+    if (exitCode === 0)
+        return 'green';
+    if (exitCode === 8)
+        return 'none';
+    if (/\b(pending|in_progress|queued|waiting|expected)\b/i.test(output))
+        return 'pending';
+    return 'red';
+}
+function inspectChecks(prNumber, cwd) {
+    try {
+        const out = execFileSync('gh', ['pr', 'checks', String(prNumber)], {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 60_000,
+        });
+        return checksVerdict(0, out);
+    }
+    catch (err) {
+        const e = err;
+        return checksVerdict(e.status ?? 1, `${e.stdout ?? ''}${e.stderr ?? ''}`);
+    }
+}
+/**
+ * Re-sync a PR branch onto the freshly-updated base and push.
+ * Returns null on success, or a human-readable reason on failure.
+ */
+function resyncPr(pr, cwd) {
+    try {
+        gh(['pr', 'update-branch', String(pr.number)], cwd);
+        return null;
+    }
+    catch (err) {
+        // update-branch fails on a real conflict — exactly what we want surfaced.
+        return err.message.includes('merge conflict')
+            ? 'merge conflict with the new base — resolve locally'
+            : err.message.slice(0, 160);
+    }
+}
+export async function mergeQueueCommand(options = {}) {
+    const cwd = process.cwd();
+    let prs;
+    try {
+        prs = fetchOpenPrs(cwd);
+    }
+    catch (err) {
+        console.error(chalk.red(String(err)));
+        console.error(chalk.dim('Requires the `gh` CLI, authenticated against this repo.'));
+        process.exitCode = 1;
+        return;
+    }
+    const eligible = prs.filter((p) => !p.isDraft);
+    if (eligible.length === 0) {
+        console.log(chalk.dim('No open, non-draft PRs to land.'));
+        return;
+    }
+    const ownership = loadOwnershipMap(cwd);
+    const ordered = orderQueue(eligible);
+    const limit = Number.isFinite(options.limit) && (options.limit ?? 0) > 0
+        ? options.limit
+        : DEFAULT_QUEUE_LIMIT;
+    const plan = ordered.slice(0, limit);
+    console.log(chalk.bold(`\n🚦 Merge queue — ${plan.length} PR(s)\n`));
+    for (const [i, pr] of plan.entries()) {
+        const others = plan.slice(i + 1);
+        const conflicts = impactedBy(pr, others, ownership);
+        const note = conflicts.length > 0
+            ? chalk.yellow(` → forces re-sync of ${conflicts.map((c) => `#${c.number}`).join(', ')}`)
+            : '';
+        console.log(`  ${i + 1}. #${pr.number} ${pr.title} ${chalk.dim(`(${pr.files.length} files)`)}${note}`);
+    }
+    console.log('');
+    if (ordered.length > plan.length) {
+        console.log(chalk.dim(`  … ${ordered.length - plan.length} more open PR(s) not in this batch (--limit ${limit}).`));
+        console.log('');
+    }
+    if (options.dryRun || !options.yes) {
+        console.log(chalk.dim(options.dryRun
+            ? 'Dry run — nothing merged.'
+            : 'Plan only — nothing merged. Re-run with --yes to land these.'));
+        return;
+    }
+    let landed = 0;
+    const skipped = [];
+    for (const [i, pr] of plan.entries()) {
+        const remaining = plan.slice(i + 1);
+        if (!options.force) {
+            const verdict = inspectChecks(pr.number, cwd);
+            if (verdict === 'red' || verdict === 'pending') {
+                const why = verdict === 'pending' ? 'checks still running' : 'checks failing';
+                console.log(chalk.yellow(`  ⏭  #${pr.number} skipped — ${why}`));
+                skipped.push(`#${pr.number} (${why})`);
+                continue;
+            }
+            // 'none' (repo has no CI) and 'green' both proceed.
+        }
+        try {
+            gh(['pr', 'merge', String(pr.number), '--merge'], cwd);
+            landed++;
+            console.log(chalk.green(`  ✔ #${pr.number} merged`));
+        }
+        catch (err) {
+            console.log(chalk.red(`  ✖ #${pr.number} merge failed: ${err.message.slice(0, 140)}`));
+            skipped.push(`#${pr.number} (merge failed)`);
+            continue;
+        }
+        // THE POINT OF THE QUEUE: every PR that touches what just landed is now
+        // testing against a base that no longer exists. Re-sync before the next merge
+        // so the next PR's checks describe reality.
+        const impacted = impactedBy(pr, remaining, ownership);
+        for (const other of impacted) {
+            const failure = resyncPr(other, cwd);
+            if (failure) {
+                console.log(chalk.red(`     ↳ #${other.number} could not re-sync: ${failure}`));
+            }
+            else {
+                console.log(chalk.dim(`     ↳ #${other.number} re-synced onto the new base`));
+            }
+        }
+    }
+    console.log('');
+    console.log(chalk.bold(`Landed ${landed}/${plan.length}.`));
+    if (skipped.length > 0) {
+        console.log(chalk.yellow(`Skipped: ${skipped.join(', ')}`));
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=merge-queue.js.map

package/dist/cli/merge-queue.js.map

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

package/dist/cli/worktree.d.ts

@@ -1,4 +1,5 @@
-type WorktreeAction = 'create' | 'list' | 'pr' | 'finish' | 'cleanup' | 'ensure' | 'prune';
+import { SimpleGit } from 'simple-git';
+type WorktreeAction = 'create' | 'list' | 'pr' | 'finish' | 'cleanup' | 'ensure' | 'prune' | 'sync' | 'hygiene';
 interface WorktreeOptions {
     slug?: string;
     id?: string;
@@ -9,8 +10,75 @@ interface WorktreeOptions {
     olderThan?: number;
     force?: boolean;
     dryRun?: boolean;
+    /** create: skip the fetch of the base remote (offline / air-gapped). */
+    noFetch?: boolean;
+    /** hygiene: emit a single-line advisory instead of the full table. */
+    brief?: boolean;
+    /** sync/hygiene: operate on every worktree, not just the current one. */
+    all?: boolean;
 }
+/** Commits behind the integration ref at which a worktree reads as abandoned. */
+export declare const STALE_BEHIND_LIMIT = 200;
 export declare function worktreeCommand(action: WorktreeAction, options?: WorktreeOptions): Promise<void>;
+/**
+ * Name of the repo's integration branch, without the remote prefix.
+ * Prefers origin/HEAD (what the remote itself calls default), then the usual
+ * suspects, then the current local branch. Hard-coding "master" broke every
+ * main-branch repo that installed UAP.
+ */
+export declare function resolveDefaultBranch(git: SimpleGit): Promise<string>;
+/** Fully-qualified ref to integrate against: `origin/<default>` when the remote has it. */
+export declare function resolveIntegrationRef(git: SimpleGit): Promise<string>;
+export interface BranchDrift {
+    name: string;
+    path: string;
+    branch: string;
+    /** Commits on the integration ref that this branch does not have. */
+    behind: number;
+    /** Commits on this branch not yet on the integration ref (unmerged work). */
+    ahead: number;
+    /** Count of uncommitted (staged + unstaged + untracked) entries. */
+    dirty: number;
+    /** A live agent is announcing work on this branch right now. */
+    active?: boolean;
+}
+/**
+ * Branches a LIVE agent is currently announcing work on.
+ *
+ * Git metadata alone cannot tell "abandoned" from "someone is working here this
+ * second": both look like an old branch with uncommitted files. That ambiguity is
+ * not academic — a worktree in this repo was read as abandoned WIP and merged
+ * forward while its owning agent was mid-session, because the drift report only
+ * ever consulted git. The coordination DB knows the difference; join against it.
+ *
+ * Liveness uses the same heartbeat window as coordinate-file.sh so "live" means
+ * one thing across the system. Fail-open: an unreadable DB marks nothing active.
+ */
+export declare function liveAgentBranches(mainRoot: string): {
+    branches: Set<string>;
+    /** False when the DB could not be read — callers that DELETE must fail closed. */
+    readable: boolean;
+};
+/**
+ * Measure one worktree's drift against the integration ref. Never throws.
+ *
+ * Kept to ONE git process on the common path. The first version spent four
+ * (`rev-parse`, two `rev-list`, `status`) which, across this repo's 152
+ * worktrees, ran ~600 sequential git invocations — comfortably past the 15s
+ * budget the session banner allows, so the advisory was always killed before it
+ * printed while still costing the full 15 seconds.
+ *
+ * @param branch pre-resolved from `git worktree list --porcelain`, which already
+ *   reports it — re-asking per worktree was a free process we were paying for.
+ * @param withDirty `git status` is by far the most expensive call (it stats the
+ *   whole tree). Only worth it for worktrees that already look interesting.
+ */
+export declare function measureDrift(worktreePath: string, integrationRef: string, branch?: string, withDirty?: boolean): Promise<BranchDrift | null>;
+/**
+ * One-line advisory for session-start. Returns '' when nothing needs attention,
+ * so the caller can stay silent on a healthy repo.
+ */
+export declare function summarizeHygiene(drifts: BranchDrift[], integrationRef: string): string;
 export declare function parseRevListCount(output: string): number;
 export declare function isAlreadyMergedMessage(message: string): boolean;
 /**

package/dist/cli/worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/cli/worktree.ts"],"names":[],"mappings":"AAQA,KAAK,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3F,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+CD,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAsCf;AA6PD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMxD;AAcD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAqKD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU9D"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/cli/worktree.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,SAAS,EAAE,MAAM,YAAY,CAAC;AAIlD,KAAK,cAAc,GACf,QAAQ,GACR,MAAM,GACN,IAAI,GACJ,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,GACN,SAAS,CAAC;AAEd,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAuEtC,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAwRD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB1E;AAED,2FAA2F;AAC3F,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ3E;AA+BD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACnD,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;CACnB,CAkDA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,UAAO,GACf,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA8B7B;AAuND;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CA6BtF;AAcD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMxD;AAcD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAqKD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU9D"}