dorfl 0.0.0 → 0.1.0

package/dist/git.d.ts

@@ -0,0 +1,75 @@
+/** Result of running a git (or any) command. */
+export interface RunResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Run a command synchronously in `cwd`, capturing output. A non-zero exit is NOT
+ * thrown here — callers inspect `status` (claim.sh's exit codes are meaningful).
+ */
+export declare function run(command: string, args: string[], cwd: string, options?: {
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+}): RunResult;
+/**
+ * Async variant of {@link run}: spawns the command WITHOUT blocking the event
+ * loop, so two awaited calls genuinely run concurrently. Used to verify the
+ * claim race the way claim.sh's own verification does (truly simultaneous).
+ */
+export declare function runAsync(command: string, args: string[], cwd: string, options?: {
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunResult>;
+/** Run `git <args>` in `cwd`; throws on non-zero exit (use `run` for soft checks). */
+export declare function git(args: string[], cwd: string, options?: {
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/**
+ * Move a tracked file with `git mv`, creating the destination directory first
+ * (`mkdir -p`). The `work/` contract requires this: git does not track empty
+ * dirs, so `work/done/` (or `work/in-progress/`) may not exist yet. No
+ * `.gitkeep` placeholders — the mover owns dir creation.
+ */
+export declare function gitMv(from: string, to: string, cwd: string): void;
+/**
+ * The pre-flight DIVERGENCE check for the in-place ff paths (`do` /
+ * `complete --merge`): how many commits local `main` is AHEAD of
+ * `<arbiter>/main` (`git rev-list --count <arbiter>/main..main`). A non-zero
+ * count means local `main` carries UNPUSHED commits the arbiter lacks — the task
+ * builds off `<arbiter>/main`, so its merge-back ff cannot apply, exactly the
+ * "checkout state that breaks the in-place flow" class the dirty-tree refusal
+ * guards. Returns 0 when local `main` is at/behind the arbiter (safe).
+ *
+ * Best-effort / SAFE-direction: if either ref cannot be resolved (no local
+ * `main`, an unreachable arbiter that left `<arbiter>/main` absent) the count
+ * cannot be computed, so we read it as 0 (do NOT block on an unknown) — the
+ * caller is expected to have fetched first, and a genuinely diverged main is the
+ * case we DO catch. Read-only.
+ */
+export declare function localMainAheadCount(cwd: string, arbiter: string, env: NodeJS.ProcessEnv | undefined): Promise<number>;
+/** How far local `main` has diverged from `<arbiter>/main`, both directions. */
+export interface LocalMainDivergence {
+    /** Commits on local `main` the arbiter lacks (UNPUSHED — `main-divergence-guard`). */
+    ahead: number;
+    /** Commits on `<arbiter>/main` the local `main` lacks (behind — needs a pull/rebase). */
+    behind: number;
+}
+/**
+ * Read the DIVERGENCE of local `main` vs `<arbiter>/main` in BOTH directions
+ * (`git rev-list --left-right --count <arbiter>/main...main`): `ahead` =
+ * unpushed local commits the arbiter lacks (the `main-divergence-guard`
+ * framing), `behind` = arbiter commits the local tree lacks. This is the honest
+ * expression of the LOCAL working tree's staleness relative to the arbiter — the
+ * source of truth — for the cwd-local section of `scan`/`status` (it labels the
+ * section as possibly ahead of / behind the fetched arbiter `main`).
+ *
+ * Best-effort / SAFE: if either ref cannot be resolved (no local `main`, an
+ * unreachable arbiter so `<arbiter>/main` is absent) the divergence cannot be
+ * computed, so it reads as `{ahead: 0, behind: 0}` (in sync) — never throws. The
+ * caller is expected to have fetched the arbiter first; a genuinely diverged
+ * `main` is the case we DO catch. Read-only.
+ */
+export declare function localMainDivergence(cwd: string, arbiter: string, env: NodeJS.ProcessEnv | undefined): Promise<LocalMainDivergence>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAIA,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAM,GACrD,SAAS,CAgBX;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAM,GACrD,OAAO,CAAC,SAAS,CAAC,CA0BpB;AAED,sFAAsF;AACtF,wBAAgB,GAAG,CAClB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAM,GACrD,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAGjE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,GAChC,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IACnC,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAmB9B"}

package/dist/git.js

@@ -0,0 +1,130 @@
+import { spawnSync, spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Run a command synchronously in `cwd`, capturing output. A non-zero exit is NOT
+ * thrown here — callers inspect `status` (claim.sh's exit codes are meaningful).
+ */
+export function run(command, args, cwd, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: 'utf8',
+        input: options.input,
+        env: options.env ?? process.env,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.error) {
+        throw new Error(`failed to spawn '${command}': ${result.error.message}`);
+    }
+    return {
+        status: result.status ?? -1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+/**
+ * Async variant of {@link run}: spawns the command WITHOUT blocking the event
+ * loop, so two awaited calls genuinely run concurrently. Used to verify the
+ * claim race the way claim.sh's own verification does (truly simultaneous).
+ */
+export function runAsync(command, args, cwd, options = {}) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            env: options.env ?? process.env,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => reject(new Error(`failed to spawn '${command}': ${err.message}`)));
+        child.on('close', (code) => {
+            resolvePromise({ status: code ?? -1, stdout, stderr });
+        });
+        if (options.input !== undefined) {
+            child.stdin.end(options.input);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+/** Run `git <args>` in `cwd`; throws on non-zero exit (use `run` for soft checks). */
+export function git(args, cwd, options = {}) {
+    const result = run('git', args, cwd, options);
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result.stdout;
+}
+/**
+ * Move a tracked file with `git mv`, creating the destination directory first
+ * (`mkdir -p`). The `work/` contract requires this: git does not track empty
+ * dirs, so `work/done/` (or `work/in-progress/`) may not exist yet. No
+ * `.gitkeep` placeholders — the mover owns dir creation.
+ */
+export function gitMv(from, to, cwd) {
+    mkdirSync(dirname(toAbsolute(cwd, to)), { recursive: true });
+    git(['mv', from, to], cwd);
+}
+function toAbsolute(cwd, p) {
+    return p.startsWith('/') ? p : `${cwd}/${p}`;
+}
+/**
+ * The pre-flight DIVERGENCE check for the in-place ff paths (`do` /
+ * `complete --merge`): how many commits local `main` is AHEAD of
+ * `<arbiter>/main` (`git rev-list --count <arbiter>/main..main`). A non-zero
+ * count means local `main` carries UNPUSHED commits the arbiter lacks — the task
+ * builds off `<arbiter>/main`, so its merge-back ff cannot apply, exactly the
+ * "checkout state that breaks the in-place flow" class the dirty-tree refusal
+ * guards. Returns 0 when local `main` is at/behind the arbiter (safe).
+ *
+ * Best-effort / SAFE-direction: if either ref cannot be resolved (no local
+ * `main`, an unreachable arbiter that left `<arbiter>/main` absent) the count
+ * cannot be computed, so we read it as 0 (do NOT block on an unknown) — the
+ * caller is expected to have fetched first, and a genuinely diverged main is the
+ * case we DO catch. Read-only.
+ */
+export async function localMainAheadCount(cwd, arbiter, env) {
+    const res = await runAsync('git', ['rev-list', '--count', `${arbiter}/main..main`], cwd, { env });
+    if (res.status !== 0) {
+        return 0; // a ref did not resolve — cannot compute; do not block (safe).
+    }
+    const n = Number.parseInt(res.stdout.trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * Read the DIVERGENCE of local `main` vs `<arbiter>/main` in BOTH directions
+ * (`git rev-list --left-right --count <arbiter>/main...main`): `ahead` =
+ * unpushed local commits the arbiter lacks (the `main-divergence-guard`
+ * framing), `behind` = arbiter commits the local tree lacks. This is the honest
+ * expression of the LOCAL working tree's staleness relative to the arbiter — the
+ * source of truth — for the cwd-local section of `scan`/`status` (it labels the
+ * section as possibly ahead of / behind the fetched arbiter `main`).
+ *
+ * Best-effort / SAFE: if either ref cannot be resolved (no local `main`, an
+ * unreachable arbiter so `<arbiter>/main` is absent) the divergence cannot be
+ * computed, so it reads as `{ahead: 0, behind: 0}` (in sync) — never throws. The
+ * caller is expected to have fetched the arbiter first; a genuinely diverged
+ * `main` is the case we DO catch. Read-only.
+ */
+export async function localMainDivergence(cwd, arbiter, env) {
+    const res = await runAsync('git', ['rev-list', '--left-right', '--count', `${arbiter}/main...main`], cwd, { env });
+    if (res.status !== 0) {
+        return { ahead: 0, behind: 0 }; // a ref did not resolve — read as in sync (safe).
+    }
+    // `--left-right --count A...B` prints `<behind>\t<ahead>` (left = A=arbiter
+    // commits B lacks = behind; right = B=local commits A lacks = ahead).
+    const parts = res.stdout.trim().split(/\s+/);
+    const behind = Number.parseInt(parts[0] ?? '', 10);
+    const ahead = Number.parseInt(parts[1] ?? '', 10);
+    return {
+        ahead: Number.isFinite(ahead) ? ahead : 0,
+        behind: Number.isFinite(behind) ? behind : 0,
+    };
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

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

package/dist/github.d.ts

@@ -0,0 +1,187 @@
+import { type ReviewProvider, type OpenRequestInput, type OpenRequestResult, type PostPRCommentInput, type PostPRCommentOnBranchInput, type PostPRCommentResult } from './integrator.js';
+/**
+ * The **GitHub** integration provider (ADR §6 in
+ * `docs/adr/execution-substrate-decisions.md`): the concrete `propose`-mode
+ * review-request step, implemented by shelling out to the `gh` CLI.
+ *
+ * It fulfils the provider seam introduced by `agent-workspaces`
+ * (`./integrator.ts`, with its `none` provider). The contract that seam encodes
+ * is load-bearing here:
+ *
+ *  - The **universal, safety-bearing action is `git push`** — done by the seam
+ *    BEFORE the provider is asked to open a request (`Integrator.integrate`).
+ *    So by the time `openRequest` runs the branch is already on the arbiter and
+ *    the work is SAFE regardless of what `gh` does (ADR §4/§6).
+ *  - Therefore this provider **NEVER hard-fails**: if `gh` is missing or
+ *    unauthenticated it degrades to the `none` behaviour (branch pushed + print
+ *    manual-PR instructions) rather than throwing — a provider failure must
+ *    leave a safe, pushed branch, not lost work.
+ *  - It **NEVER `--force`s** anything (the only force in the system is the claim
+ *    micro-commit's `--force-with-lease` inside claim.sh).
+ *
+ * Selection is driven PURELY by the ARBITER URL: a GitHub remote auto-selects
+ * this provider; any other arbiter (local `--bare`, a non-GitHub host) defaults
+ * to `none` (see {@link selectProvider}). There is NO `provider` override axis —
+ * the provider is fully determined by the arbiter; whether `gh` can actually open
+ * a PR is the IDENTITY's `providers.github` auth (or ambient `gh` auth), checked
+ * by {@link GitHubProvider.available}. The separate "suppress the PR" intent is
+ * the `noPR` config axis, layered ON TOP of this arbiter-derived provider (it
+ * does NOT pick a provider).
+ *
+ * The core never imports `gh`; ONLY this adapter shells out to it (the `gh`
+ * invocation lives entirely behind the `ReviewProvider` seam). Tests stub `gh`
+ * via the injectable `ghBin` (no network, no real GitHub).
+ */
+/**
+ * The review-request providers dorfl knows about. This is the RETURN type
+ * of {@link selectProvider} (which provider the arbiter resolves to) — NOT a
+ * config OVERRIDE axis (there is none; the provider is purely arbiter-derived).
+ */
+export type ProviderName = 'none' | 'github';
+/** The default `gh` CLI binary name (resolved on `PATH`). */
+export declare const DEFAULT_GH_BIN = "gh";
+/**
+ * True iff `url` is a GitHub arbiter remote, recognised across the URL shapes
+ * the arbiter can take (scp-like ssh `git@github.com:o/r.git`, `ssh://`,
+ * `https://`/`http://`). We match on the HOST being exactly `github.com` (or a
+ * `github.com` subdomain — GitHub Enterprise installs are out of scope and read
+ * as not-GitHub, the safe `none` default). A mere substring match is rejected so
+ * a lookalike host (`notgithub.com.evil`) never selects the GitHub provider.
+ */
+export declare function isGitHubArbiterUrl(url: string): boolean;
+export interface SelectProviderOptions {
+    /**
+     * The arbiter remote URL (the SOLE determinant of the provider). `undefined`
+     * when it cannot be resolved — detection then yields `none` (the safe default).
+     */
+    arbiterUrl?: string;
+    /** The `gh` CLI binary the GitHub provider invokes (tests inject a stub). */
+    ghBin?: string;
+}
+/**
+ * Resolve the review-request provider for an integration (ADR §6), PURELY from
+ * the arbiter URL — there is NO override axis:
+ *
+ *   - a `github.com` arbiter URL ⇒ the GitHub provider, else
+ *   - the `none` provider (the safe default for unknown / local `--bare`
+ *     arbiters, which have no review concept).
+ *
+ * The GitHub provider degrades to `none` behaviour at RUNTIME when `gh` is
+ * absent/unauthenticated (so it is safe to select it on URL alone — the work is
+ * already pushed by the seam, ADR §6); this keeps SELECTION a pure, testable
+ * function of the arbiter URL. The orthogonal "do not open a PR" INTENT is the
+ * `noPR` config axis (handled by the caller, layered on top — it does NOT pick a
+ * provider here), and whether `gh` is authed to actually open the PR is the
+ * identity's `providers.github` / ambient `gh` auth.
+ */
+export declare function selectProvider(options: SelectProviderOptions): ReviewProvider;
+export interface GitHubProviderOptions {
+    /**
+     * The `gh` CLI binary (default `gh` on `PATH`). Tests inject a stub script so
+     * the seam is exercised without a real model / network / GitHub.
+     */
+    ghBin?: string;
+    /** The base branch PRs target. Default `main`. */
+    base?: string;
+}
+/**
+ * The GitHub provider: opens a PR for an already-pushed `work/<slug>` branch via
+ * `gh pr create`. It NEVER hard-fails — a missing/unauthenticated `gh` degrades
+ * to the `none` behaviour (the branch is already pushed; print manual-PR
+ * instructions) — and NEVER `--force`s anything. The created PR URL is parsed
+ * from `gh`'s stdout and returned so the caller can record it.
+ */
+export declare class GitHubProvider implements ReviewProvider {
+    readonly name = "github";
+    private readonly ghBin;
+    private readonly base;
+    constructor(options?: GitHubProviderOptions);
+    /**
+     * Open a PR for `input.branch` via `gh pr create --base main --head <branch>`,
+     * passing an explicit `--title`/`--body` when the caller supplied them (the
+     * synthesised single-line title + the agent's summary body) and falling back to
+     * `--fill` ONLY when BOTH are absent (today's behaviour — no regression). A
+     * partial set (one present) still drops `--fill`: `--fill` and an explicit
+     * `--title`/`--body` are mutually exclusive to `gh`, so once we override either
+     * field we must supply both explicitly (the other defaults to the slug-derived
+     * title / an empty body rather than re-deriving a run-on subject). The branch
+     * is GUARANTEED to be on the arbiter already (the push is the seam's safety-
+     * bearing step), so any `gh` failure is non-fatal: we fall back to the same
+     * manual-instructions result the `none` provider returns. On success we parse
+     * the PR URL `gh` prints and surface it (recorded by the caller into the job
+     * record / `status`).
+     */
+    openRequest(input: OpenRequestInput): Promise<OpenRequestResult>;
+    /** Map a successful `gh pr create` RunResult to an OpenRequestResult. */
+    private parseOpened;
+    /**
+     * Post a follow-up COMMENT on an already-opened PR via
+     * `gh pr comment <url> --body <text>` (task `review-gate-pr-comment`),
+     * threading the PR by the `url` {@link openRequest} returned. The PR already
+     * exists (this runs AFTER the propose integrate), so any `gh` failure is
+     * non-fatal: a missing/unauthenticated `gh` DEGRADES to the same surface-the-
+     * text result the `none` provider returns — NEVER throws (ADR §6). The comment
+     * is ADVISORY: it changes no gate/verdict/merge logic. NEVER `--force`s.
+     */
+    postPRComment(input: PostPRCommentInput): PostPRCommentResult;
+    /**
+     * Post the review comment by RESOLVING the PR from the pushed `work/<slug>`
+     * BRANCH (task `review-comment-fallback-on-unparsed-pr-url`), the FALLBACK for
+     * when `gh pr create` opened a PR (exit 0) but its stdout url was unparseable so
+     * {@link openRequest} returned `{opened: true}` with NO `url`. We first RESOLVE
+     * the open PR's url from the branch (`gh pr view <branch> --json url --jq .url`):
+     *
+     *  - a url comes back ⇒ a PR genuinely exists — post the comment on it via the
+     *    url-keyed {@link postPRComment} (the audit trail is preserved);
+     *  - nothing resolvable (no PR for the branch, or `gh` missing/unauthenticated)
+     *    ⇒ an HONEST clean no-op (`posted: false`) — but only AFTER trying. The
+     *    "no PR ⇒ no comment" rule holds; what changes is we no longer drop the
+     *    comment when a PR DID open.
+     *
+     * Resolving the url first (rather than commenting on the branch directly) keeps
+     * the no-PR case a deterministic no-op and reuses the exact same comment
+     * mechanics as the url path. NEVER throws, NEVER `--force`s (ADR §6).
+     */
+    postPRCommentOnBranch(input: PostPRCommentOnBranchInput): PostPRCommentResult;
+    /**
+     * Resolve the open PR's url for `branch` via `gh pr view <branch> --json url
+     * --jq .url`, or `undefined` when no PR is found / `gh` is missing or
+     * unauthenticated (a non-zero exit or a spawn failure). Read-only; mutates
+     * nothing. The result is parsed for a PR url (any surrounding chatter ignored)
+     * so a stray warning line never defeats the resolution.
+     */
+    private resolvePrUrlForBranch;
+    /**
+     * Is `gh` available AND authenticated (so a PR can actually be opened)?
+     * `gh auth status` exits 0 when authenticated. A missing `gh` (spawn failure)
+     * or a non-zero exit both read as unavailable. Read-only; mutates nothing.
+     */
+    available(cwd: string, env?: NodeJS.ProcessEnv): boolean;
+    /**
+     * Run `gh <args>` in `cwd`, returning the result, or `undefined` when `gh`
+     * cannot even be spawned (binary missing). `run` throws on a spawn error; we
+     * catch it here so a missing `gh` degrades rather than crashing the runner.
+     */
+    private runGh;
+    /**
+     * The graceful-degradation result (identical SHAPE to the `none` provider's):
+     * the branch is already pushed (safe), only the PR is missing. The `reason`
+     * distinguishes the two LOW-severity degrade causes so the operator knows what
+     * to do: `unavailable` (`gh` missing/unauth — fix `gh`/auth) vs `outage`
+     * (transient network/API failure that survived the bounded retry — just re-run
+     * / open it manually). Both print the SAME manual `gh pr create` suggestion.
+     */
+    private degrade;
+}
+/**
+ * The CONTENT args for `gh pr create`: an explicit `--title`/`--body` when the
+ * caller supplied either (a partial set is completed so `--fill` is never mixed
+ * with an explicit field — `gh` forbids that), else the lone `--fill` (today's
+ * behaviour, no regression). Returned as a flat arg array so both the live
+ * invocation and the degraded suggestion build from one source of truth.
+ */
+export declare function prCreateContentArgs(input: {
+    title?: string;
+    body?: string;
+}): string[];
+//# sourceMappingURL=github.d.ts.map

package/dist/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAGA,OAAO,EAGN,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C,6DAA6D;AAC7D,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMvD;AAuCD,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAK7E;AAED,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,cAAc;IACpD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,OAAO,GAAE,qBAA0B;IAK/C;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA8DtE,yEAAyE;IACzE,OAAO,CAAC,WAAW;IAoBnB;;;;;;;;OAQG;IACH,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB;IA2B7D;;;;;;;;;;;;;;;;;OAiBG;IACH,qBAAqB,CACpB,KAAK,EAAE,0BAA0B,GAC/B,mBAAmB;IAsBtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAKxD;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAYb;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;CAmCf;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,MAAM,EAAE,CAKX"}