@ttctl/core 0.0.0 → 0.1.0-rc.1

package/dist/lib/wire-shape.js

@@ -0,0 +1,376 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+/**
+ * Maximum rendered length of a {@link WireShapeDiffEntry.value} field
+ * (per `docs/wire-validation-error-format.md` § Diff entries).
+ * Truncation appends `…` (a single ellipsis character, not three
+ * dots) to mark overflow.
+ */
+export const MAX_VALUE_LENGTH = 32;
+/**
+ * Verbatim hint string emitted alongside every `WIRE_SHAPE_ERROR`.
+ * Lifted into the CLI envelope's `hint` slot and the MCP error-text
+ * `Hint:` block; identical across all surfaces so an operator pattern-
+ * matches the message regardless of where it's encountered. The text
+ * comes directly from `docs/wire-validation-error-format.md` § Code +
+ * base fields (M2 / #281).
+ */
+export const WIRE_SHAPE_HINT = "wire shape doesn't match expected — this typically means Toptal changed the API; please file an issue at https://github.com/alexey-pelykh/ttctl/issues with the operation name and timestamp.";
+/**
+ * Walk a JSON path against a wire snapshot, returning the value at
+ * that path or {@link MISSING} when any segment doesn't resolve. The
+ * sentinel is distinct from `undefined` so callers can distinguish
+ * "value is undefined on the wire" (data present, field absent) from
+ * "path doesn't resolve" (entire branch missing or wireData omitted).
+ */
+const MISSING = Symbol("wire-shape:missing");
+function walkPath(wireData, path) {
+    let current = wireData;
+    for (const segment of path) {
+        if (current === null || current === undefined)
+            return MISSING;
+        if (typeof segment === "number") {
+            if (!Array.isArray(current))
+                return MISSING;
+            if (segment < 0 || segment >= current.length)
+                return MISSING;
+            current = current[segment];
+        }
+        else if (typeof segment === "string") {
+            if (typeof current !== "object" || Array.isArray(current))
+                return MISSING;
+            const key = segment;
+            const obj = current;
+            if (!(key in obj))
+                return MISSING;
+            current = obj[key];
+        }
+        else {
+            // Symbol — Zod permits in record/map keys though wire payloads
+            // never carry symbol keys. Fail closed: cannot walk a symbol
+            // path against a JSON wire snapshot.
+            return MISSING;
+        }
+    }
+    return current;
+}
+/**
+ * Render an unknown value into a short type tag for the `expected` /
+ * `actual` slots of a {@link WireShapeDiffEntry}. Pre-`typeof` array
+ * branch keeps `[]` from rendering as `"object"`.
+ */
+function typeNameOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * Render an unknown wire value into a string for the
+ * {@link WireShapeDiffEntry.value} slot. Strings round-trip verbatim
+ * (no surrounding quotes — the pretty renderer adds them); primitives
+ * use `String(value)`; arrays/objects use `JSON.stringify`. Output is
+ * truncated to {@link MAX_VALUE_LENGTH} characters with `…` on
+ * overflow.
+ */
+function renderValue(value) {
+    let rendered;
+    if (typeof value === "string") {
+        rendered = value;
+    }
+    else if (value === null || value === undefined || typeof value === "boolean" || typeof value === "number") {
+        rendered = String(value);
+    }
+    else if (typeof value === "bigint") {
+        rendered = `${value.toString()}n`;
+    }
+    else {
+        try {
+            rendered = JSON.stringify(value);
+        }
+        catch {
+            rendered = "[unstringifiable]";
+        }
+    }
+    if (rendered.length <= MAX_VALUE_LENGTH)
+        return rendered;
+    return `${rendered.slice(0, MAX_VALUE_LENGTH - 1)}…`;
+}
+/**
+ * Format a Zod issue path (array of `PropertyKey` segments) into the
+ * JSON path syntax required by {@link WireShapeDiffEntry.path}.
+ * Numeric segments fold into the preceding key as bracket-notation
+ * indices (`["records", 0, "duration"]` → `"records[0].duration"`).
+ *
+ * The empty-path case (top-level / refinement errors) returns the
+ * empty string. Callers handle prepending a base path when applicable
+ * (used by the `unrecognized_keys` branch in {@link issueToDiffEntries}).
+ */
+function formatJsonPath(path) {
+    if (path.length === 0)
+        return "";
+    const parts = [];
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            const head = parts.length === 0 ? "" : (parts[parts.length - 1] ?? "");
+            const next = `${head}[${segment.toString()}]`;
+            if (parts.length === 0) {
+                parts.push(next);
+            }
+            else {
+                parts[parts.length - 1] = next;
+            }
+        }
+        else if (typeof segment === "string") {
+            parts.push(segment);
+        }
+        else {
+            // Symbol — Zod allows it in record/map keys though wire payloads
+            // never carry symbol keys. Render via .toString() so the message
+            // is still readable rather than dropping the segment.
+            parts.push(segment.toString());
+        }
+    }
+    return parts.join(".");
+}
+/**
+ * Parse a path string back into segments for deterministic sorting.
+ * Numeric segments compare numerically (`[2]` before `[10]`); string
+ * segments compare lexicographically. The string `"records[0].duration"`
+ * decomposes into `["records", 0, "duration"]`.
+ */
+function parsePathSegments(path) {
+    if (path.length === 0)
+        return [];
+    const segments = [];
+    for (const chunk of path.split(".")) {
+        const headEnd = chunk.indexOf("[");
+        const head = headEnd === -1 ? chunk : chunk.slice(0, headEnd);
+        if (head.length > 0)
+            segments.push(head);
+        const indexMatcher = /\[(\d+)\]/g;
+        let match;
+        while ((match = indexMatcher.exec(chunk)) !== null) {
+            segments.push(Number(match[1]));
+        }
+    }
+    return segments;
+}
+/**
+ * Compare two diff entries by `path` for deterministic ordering.
+ * Numeric path segments compare numerically (`records[2]` before
+ * `records[10]`); string segments compare lexicographically. When
+ * paths differ only in trailing segments, the shorter path sorts
+ * first. The result is byte-identical output across runs — essential
+ * for snapshot tests and human pattern-matching of repeat failures
+ * across logs.
+ */
+function compareDiffEntries(a, b) {
+    const segA = parsePathSegments(a.path);
+    const segB = parsePathSegments(b.path);
+    const minLen = Math.min(segA.length, segB.length);
+    for (let i = 0; i < minLen; i++) {
+        const sa = segA[i];
+        const sb = segB[i];
+        if (sa === undefined || sb === undefined)
+            break;
+        if (typeof sa === "number" && typeof sb === "number") {
+            if (sa !== sb)
+                return sa - sb;
+        }
+        else {
+            const saStr = String(sa);
+            const sbStr = String(sb);
+            if (saStr !== sbStr)
+                return saStr < sbStr ? -1 : 1;
+        }
+    }
+    if (segA.length !== segB.length)
+        return segA.length - segB.length;
+    // Paths equal — preserve insertion order via tie-break on the diff
+    // entry fields so the comparator is total (required by `Array.sort`
+    // contract for stable cross-engine output).
+    if (a.op !== b.op)
+        return a.op < b.op ? -1 : 1;
+    return 0;
+}
+/**
+ * Extract `received <type>` from a Zod v4 `invalid_type` message
+ * (`"Invalid input: expected number, received string"`). Returns the
+ * received-type string when present, or `null` when the message
+ * doesn't match the expected pattern (locale change, custom error
+ * map). Used as a fallback when the wire snapshot isn't available
+ * via {@link walkPath}.
+ */
+function extractReceivedFromMessage(message) {
+    const m = /received\s+(\S+)/.exec(message);
+    return m ? (m[1] ?? null) : null;
+}
+/**
+ * Project a single Zod issue into one or more {@link WireShapeDiffEntry}
+ * rows. The mapping is per `docs/wire-validation-error-format.md` §
+ * Diff entries:
+ *
+ *   - `invalid_type` where the wire value at the issue path is
+ *     `undefined` (or unresolvable) → `-` (schema-required field
+ *     missing on wire). `value` omitted.
+ *   - `invalid_type` otherwise → `~` (type mismatch). `value` is the
+ *     raw wire value (extracted from the snapshot), truncated.
+ *   - `unrecognized_keys` (strict-mode objects) → one `+` entry per
+ *     unknown key. `value` omitted (Zod surfaces the key list but not
+ *     each key's value).
+ *   - `invalid_value`, `invalid_union`, and other codes → `~` with
+ *     wire snapshot-derived `actual` / `value`.
+ *
+ * Fallback for unrecognized codes is `~` rather than skipping the
+ * issue — a future Zod release adding a new issue code shouldn't drop
+ * the diagnostic.
+ */
+function issueToDiffEntries(issue, wireData) {
+    const basePath = formatJsonPath(issue.path);
+    if (issue.code === "unrecognized_keys") {
+        return issue.keys.map((key) => ({
+            op: "+",
+            path: basePath.length === 0 ? key : `${basePath}.${key}`,
+            expected: "<unset>",
+            actual: "unknown",
+        }));
+    }
+    const resolved = walkPath(wireData, issue.path);
+    if (issue.code === "invalid_type") {
+        // Field absent on wire OR resolved value is undefined → "-".
+        if (resolved === MISSING || resolved === undefined) {
+            const actualFromMessage = extractReceivedFromMessage(issue.message);
+            return [
+                {
+                    op: "-",
+                    path: basePath,
+                    expected: issue.expected,
+                    actual: actualFromMessage ?? "undefined",
+                },
+            ];
+        }
+        return [
+            {
+                op: "~",
+                path: basePath,
+                expected: issue.expected,
+                actual: typeNameOf(resolved),
+                value: renderValue(resolved),
+            },
+        ];
+    }
+    if (issue.code === "invalid_value") {
+        const expected = issue.values.length === 1 ? renderValue(issue.values[0]) : issue.values.map((v) => renderValue(v)).join(" | ");
+        if (resolved === MISSING) {
+            return [
+                {
+                    op: "~",
+                    path: basePath,
+                    expected,
+                    actual: "unknown",
+                },
+            ];
+        }
+        return [
+            {
+                op: "~",
+                path: basePath,
+                expected,
+                actual: typeNameOf(resolved),
+                value: renderValue(resolved),
+            },
+        ];
+    }
+    // invalid_union, invalid_format, too_big, too_small, custom, …
+    // Fall back to a structural diff entry. `actual` reflects the wire
+    // shape when resolvable; `expected` lifts the issue message so the
+    // operator sees the constraint that failed.
+    if (resolved === MISSING) {
+        return [
+            {
+                op: "~",
+                path: basePath,
+                expected: issue.message,
+                actual: "unknown",
+            },
+        ];
+    }
+    return [
+        {
+            op: "~",
+            path: basePath,
+            expected: issue.message,
+            actual: typeNameOf(resolved),
+            value: renderValue(resolved),
+        },
+    ];
+}
+/**
+ * Build the field-level diff from a {@link z.ZodError}. Issues are
+ * projected per {@link issueToDiffEntries} and sorted deterministically
+ * per {@link compareDiffEntries} so two runs against the same drifted
+ * wire response produce byte-identical output (load-bearing for
+ * snapshot tests and CI grep-fu).
+ *
+ * `wireData` is the original `body.data` snapshot that failed
+ * validation — walking it against each issue's `path` recovers the
+ * actual wire value (Zod v4 strips `input` from public issues; see
+ * file header). Pass `undefined` only in tests / migration paths
+ * where the snapshot is unavailable; entries will degrade to path-
+ * only render in that case.
+ *
+ * Exported for unit tests; callers should prefer
+ * {@link buildWireShapeError} which composes the full payload.
+ */
+export function projectZodErrorToDiff(error, wireData) {
+    const entries = [];
+    for (const issue of error.issues) {
+        entries.push(...issueToDiffEntries(issue, wireData));
+    }
+    entries.sort(compareDiffEntries);
+    return entries;
+}
+/**
+ * Compose the `message` line of a `WIRE_SHAPE_ERROR` per
+ * `docs/wire-validation-error-format.md` § Code + base fields. The
+ * pluralisation is wire-stable (`1 field issue` vs `2 field issues`)
+ * so snapshot tests don't need locale-aware matchers.
+ *
+ * Exported for unit tests; callers should prefer
+ * {@link buildWireShapeError} which composes the full payload.
+ */
+export function buildWireShapeMessage(operationName, diffEntryCount) {
+    const noun = diffEntryCount === 1 ? "issue" : "issues";
+    return `Wire shape doesn't match expected schema for operation \`${operationName}\` (${diffEntryCount.toString()} field ${noun}).`;
+}
+/**
+ * Convert a {@link z.ZodError} from a failed `schema.parse(body.data)`
+ * call into the full {@link WireShapeErrorPayload}. The payload is
+ * stable across surfaces (CLI envelope, MCP error text) and round-
+ * trips through JSON without redaction (body.data never carries the
+ * bearer).
+ *
+ * Each service's `callGateway` / `callTalentProfile` helper wraps the
+ * payload's `message` into its own domain-error class with
+ * `code: "WIRE_SHAPE_ERROR"` and `cause: zodError`; the CLI / MCP
+ * layers reconstruct the diff from `cause` when rendering.
+ *
+ * Pass `wireData` (the original `body.data` snapshot) so the diff
+ * can recover actual wire values via path walk — Zod v4 strips the
+ * `input` field from public issues, so the snapshot is the only way
+ * to render `actual` / `value` for non-`unrecognized_keys` entries.
+ *
+ * Z-3 (#286) wires the mechanism; no production op has `schema`
+ * passed in yet (Z-4 / #288 ships the first beachhead).
+ */
+export function buildWireShapeError(operationName, error, wireData) {
+    const diff = projectZodErrorToDiff(error, wireData);
+    return {
+        message: buildWireShapeMessage(operationName, diff.length),
+        hint: WIRE_SHAPE_HINT,
+        diff,
+    };
+}
+//# sourceMappingURL=wire-shape.js.map

package/dist/lib/wire-shape.js.map

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

package/dist/onepassword.d.ts

@@ -0,0 +1,29 @@
+import type { Credentials } from "./types.js";
+export declare class OnePasswordError extends Error {
+    readonly name = "OnePasswordError";
+}
+/**
+ * Resolve credentials from a 1Password item reference.
+ *
+ * Accepted forms:
+ *   - `op://VAULT/ITEM` (2-segment) — `op` CLI uses its default account or
+ *     `OP_ACCOUNT` env.
+ *   - `op://ACCOUNT/VAULT/ITEM` (3-segment) — `--account ACCOUNT` is forwarded
+ *     to `op item get` so users with multiple configured accounts can select
+ *     one explicitly. ACCOUNT may be a UUID, shorthand, or sign-in email; `op`
+ *     itself validates the value.
+ *
+ * Mechanism: shells out to `op item get ITEM --vault VAULT [--account ACCOUNT]
+ * --format json`, then matches credential fields by `purpose` (`USERNAME` /
+ * `PASSWORD`) — the canonical semantic identifier 1Password sets automatically
+ * for LOGIN-category items. The 1Password Desktop app brokers authentication
+ * (typically via biometric prompt) — no service-account token is required.
+ *
+ * Field-matching by `purpose` rather than `label` is necessary because
+ * browser-autosaved items inherit their `label` from the HTML form input name
+ * (e.g. `user[email]`, `user[password]`) — only `purpose` is canonical. The
+ * item must be a LOGIN-category item (any item with both USERNAME and PASSWORD
+ * purposes set).
+ */
+export declare function resolveOnePasswordReference(ref: string): Credentials;
+//# sourceMappingURL=onepassword.d.ts.map

package/dist/onepassword.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onepassword.d.ts","sourceRoot":"","sources":["../src/onepassword.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgB9C,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;CAC7C;AA+BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAqDpE"}

package/dist/onepassword.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { execFileSync } from "node:child_process";
+import { z } from "zod";
+/**
+ * Shape of `op item get --format json` output (subset; only fields we use).
+ */
+const OpItemSchema = z.object({
+    fields: z.array(z.object({
+        id: z.string().optional(),
+        label: z.string().optional(),
+        value: z.string().optional(),
+        purpose: z.string().optional(),
+    })),
+});
+export class OnePasswordError extends Error {
+    name = "OnePasswordError";
+}
+/**
+ * Parse `op://[ACCOUNT/]VAULT/ITEM` into its components. Returns `null` for any
+ * shape outside the 2- or 3-segment grammar (matches `OnePasswordItemRefSchema`
+ * in `config.ts`).
+ *
+ * Splitting on `/` after stripping the `op://` prefix avoids regex capture-group
+ * contortions and produces clear branching on segment count.
+ */
+function parseReference(ref) {
+    if (!ref.startsWith("op://"))
+        return null;
+    const segments = ref.slice("op://".length).split("/");
+    if (segments.some((s) => s.length === 0))
+        return null;
+    if (segments.length === 2) {
+        const [vault, item] = segments;
+        return { vault, item };
+    }
+    if (segments.length === 3) {
+        const [account, vault, item] = segments;
+        return { account, vault, item };
+    }
+    return null;
+}
+/**
+ * Resolve credentials from a 1Password item reference.
+ *
+ * Accepted forms:
+ *   - `op://VAULT/ITEM` (2-segment) — `op` CLI uses its default account or
+ *     `OP_ACCOUNT` env.
+ *   - `op://ACCOUNT/VAULT/ITEM` (3-segment) — `--account ACCOUNT` is forwarded
+ *     to `op item get` so users with multiple configured accounts can select
+ *     one explicitly. ACCOUNT may be a UUID, shorthand, or sign-in email; `op`
+ *     itself validates the value.
+ *
+ * Mechanism: shells out to `op item get ITEM --vault VAULT [--account ACCOUNT]
+ * --format json`, then matches credential fields by `purpose` (`USERNAME` /
+ * `PASSWORD`) — the canonical semantic identifier 1Password sets automatically
+ * for LOGIN-category items. The 1Password Desktop app brokers authentication
+ * (typically via biometric prompt) — no service-account token is required.
+ *
+ * Field-matching by `purpose` rather than `label` is necessary because
+ * browser-autosaved items inherit their `label` from the HTML form input name
+ * (e.g. `user[email]`, `user[password]`) — only `purpose` is canonical. The
+ * item must be a LOGIN-category item (any item with both USERNAME and PASSWORD
+ * purposes set).
+ */
+export function resolveOnePasswordReference(ref) {
+    const parsed = parseReference(ref);
+    if (!parsed) {
+        throw new OnePasswordError(`Invalid reference: ${ref}. Expected op://[account/]vault/item.`);
+    }
+    const { account, vault, item } = parsed;
+    const args = ["item", "get", item, "--vault", vault];
+    if (account !== undefined)
+        args.push("--account", account);
+    args.push("--format", "json");
+    let raw;
+    try {
+        raw = execFileSync("op", args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            throw new OnePasswordError("1Password CLI (`op`) not found. Install: https://developer.1password.com/docs/cli/get-started/");
+        }
+        throw new OnePasswordError(`op item get failed: ${e.message}`);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new OnePasswordError(`op returned non-JSON output: ${err.message}`);
+    }
+    // `op item get --format json` returns the full item object with a `fields`
+    // array. Older `op` CLI versions returned a bare fields array instead;
+    // normalize both shapes into the wrapped form before schema validation.
+    const normalized = Array.isArray(parsedJson) ? { fields: parsedJson } : parsedJson;
+    const result = OpItemSchema.safeParse(normalized);
+    if (!result.success) {
+        throw new OnePasswordError(`Unexpected op output shape: ${result.error.message}`);
+    }
+    const username = result.data.fields.find((f) => f.purpose === "USERNAME")?.value;
+    const password = result.data.fields.find((f) => f.purpose === "PASSWORD")?.value;
+    if (!username || !password) {
+        throw new OnePasswordError(`Item ${vault}/${item} must have fields with USERNAME and PASSWORD purposes (LOGIN-category items have these by default).`);
+    }
+    return { email: username, password };
+}
+//# sourceMappingURL=onepassword.js.map

package/dist/onepassword.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onepassword.js","sourceRoot":"","sources":["../src/onepassword.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;GAEG;AACH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC,KAAK,CACb,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC,CACH;CACF,CAAC,CAAC;AAEH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACvB,IAAI,GAAG,kBAAkB,CAAC;CAC7C;AAQD;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,QAA4B,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,QAAoC,CAAC;QACpE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,gBAAgB,CAAC,sBAAsB,GAAG,uCAAuC,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IAExC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACrD,IAAI,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAE9B,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE;YAC7B,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAA4B,CAAC;QACvC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,IAAI,gBAAgB,CACxB,gGAAgG,CACjG,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,uBAAuB,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,gBAAgB,CAAC,gCAAiC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,2EAA2E;IAC3E,uEAAuE;IACvE,wEAAwE;IACxE,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;IACnF,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,gBAAgB,CAAC,+BAA+B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,EAAE,KAAK,CAAC;IACjF,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,EAAE,KAAK,CAAC;IAEjF,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,gBAAgB,CACxB,QAAQ,KAAK,IAAI,IAAI,qGAAqG,CAC3H,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AACvC,CAAC"}