monday-cli 0.2.0

package/dist/api/item-projection.js

@@ -0,0 +1,235 @@
+/**
+ * Shared item projection helpers (`v0.1-plan.md` §3 M4,
+ * `cli-design.md` §6.2).
+ *
+ * Every M4 read command (`item get` / `list` / `find` / `search` /
+ * `subitems`) emits the same single-resource Item shape. Centralising
+ * here means the projection lives in one file and the per-command
+ * action body stays focused on the GraphQL call + envelope mapping.
+ *
+ * Column-value projection notes:
+ *
+ *   - Each column carries `{id, type, title, text, value}` per §6.2.
+ *     `value` is the *parsed* JSON Monday stored — Monday returns it
+ *     as a JSON-encoded string on the wire and we decode at this
+ *     boundary so JSON consumers can read structured payloads
+ *     without re-parsing.
+ *   - For known-write column types (status / date / people), a
+ *     handful of *typed* fields are surfaced inline (matching the
+ *     §6.2 worked example). Unknown / read-only types only carry
+ *     the base shape; agents inspect `value` for structured access.
+ *   - The richer per-type projection is deferred to M5a's
+ *     `column-values.ts` (the writer needs the same shape and the
+ *     reader can reuse it). Until then, this module hosts the
+ *     read-only inline projection so the v0.1 contract surface is
+ *     stable.
+ */
+import { z } from 'zod';
+export const rawColumnValueSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    text: z.string().nullable(),
+    value: z.string().nullable(),
+    column: z
+        .object({ title: z.string() })
+        .nullable()
+        .optional(),
+})
+    .strict();
+export const rawItemSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    state: z.string().nullable(),
+    url: z.string().nullable(),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+    board: z.object({ id: z.string() }).nullable(),
+    group: z
+        .object({ id: z.string(), title: z.string().nullable() })
+        .nullable()
+        .optional(),
+    parent_item: z
+        .object({ id: z.string() })
+        .nullable()
+        .optional(),
+    creator_id: z.string().nullable().optional(),
+    column_values: z.array(rawColumnValueSchema),
+})
+    .strict();
+/**
+ * Single-column projected shape per §6.2. Carries the base shape
+ * (`id, type, title, text, value`) plus a few typed fields for the
+ * v0.1-writable status / date / people types. Mirror / formula /
+ * dependency columns surface as the base shape — `text` is the
+ * source of truth there because the typed payload isn't writable
+ * and Monday's wire shape varies.
+ */
+export const projectedColumnSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    // §6.3: per-cell title is dropped in same-board collections and
+    // consolidated into `meta.columns`. Single-resource calls keep
+    // it inline per §6.2. The schema therefore makes it optional —
+    // emit-time the projector either includes it or leaves it
+    // undefined.
+    title: z.string().optional(),
+    text: z.string().nullable(),
+    value: z.unknown(),
+    // Typed fields (optional — only set per type)
+    label: z.string().nullable().optional(),
+    index: z.number().int().nullable().optional(),
+    date: z.string().nullable().optional(),
+    time: z.string().nullable().optional(),
+    people: z
+        .array(z.object({
+        id: z.string(),
+        kind: z.string().nullable().optional(),
+    }).loose())
+        .optional(),
+})
+    .loose();
+export const projectedItemSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    board_id: z.string().nullable(),
+    group_id: z.string().nullable(),
+    parent_item_id: z.string().nullable(),
+    state: z.string().nullable(),
+    url: z.string().nullable(),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+    columns: z.record(z.string(), projectedColumnSchema),
+})
+    .strict();
+/**
+ * Parses a Monday `value` string. Monday encodes structured column
+ * values as JSON strings; the projector decodes once at the boundary
+ * so consumers can read the structured field without re-parsing.
+ *
+ * Errors are swallowed: a malformed JSON string surfaces as `null`
+ * (with `text` still carrying the human form). Defensive — Monday
+ * occasionally returns an unparseable string for read-only column
+ * types, and we don't want one weird column to fail the whole emit.
+ */
+export const parseColumnValue = (raw) => {
+    if (raw === null || raw.length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+const projectStatus = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return { label: null, index: null };
+    }
+    const v = value;
+    const label = typeof v.label === 'string' ? v.label : null;
+    const index = typeof v.index === 'number' ? v.index : null;
+    return { label, index };
+};
+const projectDate = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return { date: null, time: null };
+    }
+    const v = value;
+    const date = typeof v.date === 'string' ? v.date : null;
+    const time = typeof v.time === 'string' ? v.time : null;
+    return { date, time };
+};
+const projectPeople = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return { people: [] };
+    }
+    const v = value;
+    const persons = Array.isArray(v.personsAndTeams) ? v.personsAndTeams : [];
+    const people = persons.flatMap((p) => {
+        if (typeof p !== 'object' || p === null)
+            return [];
+        const pp = p;
+        const id = typeof pp.id === 'number' ? String(pp.id) : typeof pp.id === 'string' ? pp.id : '';
+        if (id.length === 0)
+            return [];
+        return [{ id, ...(typeof pp.kind === 'string' ? { kind: pp.kind } : {}) }];
+    });
+    return { people };
+};
+/**
+ * Projects one column-value into the §6.2 shape. Pure — no I/O.
+ * The board-metadata `title` is preferred over the wire-side
+ * `column.title` because the metadata loader's NFC + cache rules
+ * are the canonical source; `column.title` is only the fallback for
+ * cross-board lists where a single board metadata isn't loaded.
+ */
+export const projectColumnValue = (raw, fallbackTitle) => {
+    const value = parseColumnValue(raw.value);
+    const title = fallbackTitle ?? (raw.column?.title ?? raw.id);
+    const base = {
+        id: raw.id,
+        type: raw.type,
+        title,
+        text: raw.text,
+        value,
+    };
+    switch (raw.type) {
+        case 'status':
+            return { ...base, ...projectStatus(value) };
+        case 'date':
+            return { ...base, ...projectDate(value) };
+        case 'people':
+            return { ...base, ...projectPeople(value) };
+        default:
+            return base;
+    }
+};
+/**
+ * Reads `id` off a raw GraphQL item shape — the cursor walker
+ * needs a string for the per-page sort. Production cassettes always
+ * carry a string id (Monday's schema guarantees it); the
+ * structural-typing read keeps the walker honest if a future
+ * fixture drifts.
+ */
+/* c8 ignore next 5 — defensive: Monday returns numeric-string `id`
+   on every item; the malformed branches exist to stop the walker
+   crashing if a fixture / future schema misbehaves. */
+export const idFromRawItem = (item) => {
+    if (typeof item !== 'object' || item === null)
+        return '';
+    const v = item.id;
+    return typeof v === 'string' ? v : '';
+};
+export const projectItem = (inputs) => {
+    const titles = inputs.columnTitles;
+    const omitTitles = inputs.omitColumnTitles === true;
+    const columns = {};
+    for (const cv of inputs.raw.column_values) {
+        const fallback = titles?.get(cv.id);
+        const projected = projectColumnValue(cv, fallback);
+        if (omitTitles) {
+            const { title: _title, ...rest } = projected;
+            columns[cv.id] = rest;
+        }
+        else {
+            columns[cv.id] = projected;
+        }
+    }
+    return {
+        id: inputs.raw.id,
+        name: inputs.raw.name,
+        board_id: inputs.raw.board?.id ?? null,
+        group_id: inputs.raw.group?.id ?? null,
+        parent_item_id: inputs.raw.parent_item?.id ?? null,
+        state: inputs.raw.state,
+        url: inputs.raw.url,
+        created_at: inputs.raw.created_at,
+        updated_at: inputs.raw.updated_at,
+        columns,
+    };
+};
+//# sourceMappingURL=item-projection.js.map

package/dist/api/item-projection.js.map

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

package/dist/api/item-source-read.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Source-item dry-run reader — the M10 lifecycle verbs (`archive` /
+ * `delete` / `duplicate`) all share the same `--dry-run` preflight: a
+ * single-item read against `ITEM_FIELDS_FRAGMENT`, a null-result throw
+ * with `details.item_id`, then `parseRawItem + projectItem` to surface
+ * the §6.4 dry-run envelope's `item: <projected snapshot>` slot.
+ *
+ * Lifted from three sites — see v0.2-plan §14 R27:
+ *   - `commands/item/archive.ts` action — dry-run path
+ *   - `commands/item/delete.ts` action — dry-run path
+ *   - `commands/item/duplicate.ts` action — dry-run path
+ *
+ * The query body is byte-identical across the three M10 verbs (just
+ * `items(ids:) { ${ITEM_FIELDS_FRAGMENT} }`); only the operation name
+ * differs (`ItemArchiveRead` / `ItemDeleteRead` / `ItemDuplicateRead`).
+ * The op-name divergence exists for fixture cassettes + Monday's
+ * request-log telemetry (so wire calls are distinguishable per verb),
+ * so the helper takes it as a required parameter rather than
+ * collapsing it. M11's `item move` will pass `ItemMoveRead` and
+ * inherit the helper rather than copying the pattern.
+ *
+ * **Why not also for the live-mutation null-handling.** The live
+ * mutation returns the post-mutation item directly; the parsing +
+ * projection shape is shared with R28's
+ * `projectMutationItem`, but the error semantics diverge (live
+ * mutations throw `not_found` with a mutation-name-bearing message
+ * while this helper throws `not_found` with the read-side phrasing).
+ * Two helpers, one per concern.
+ */
+import { type ProjectedItem } from './item-projection.js';
+import type { MondayClient } from './client.js';
+/**
+ * Reads the source item for an M10 lifecycle dry-run preview, returns
+ * the §6.2 / §6.3 projected snapshot. Null/missing → typed
+ * `not_found` with `details.item_id` so agents key off the stable
+ * code per cli-design §6.5 (mirrors the live-path null-handling so
+ * the error shape stays identical regardless of which path the agent
+ * took).
+ */
+export declare const readSourceItemForDryRun: ({ client, itemId, operationName, }: {
+    readonly client: MondayClient;
+    readonly itemId: string;
+    readonly operationName: string;
+}) => Promise<ProjectedItem>;
+//# sourceMappingURL=item-source-read.d.ts.map

package/dist/api/item-source-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-source-read.d.ts","sourceRoot":"","sources":["../../src/api/item-source-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAU,oCAI3C;IACD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,KAAG,OAAO,CAAC,aAAa,CAuBxB,CAAC"}

package/dist/api/item-source-read.js

@@ -0,0 +1,57 @@
+/**
+ * Source-item dry-run reader — the M10 lifecycle verbs (`archive` /
+ * `delete` / `duplicate`) all share the same `--dry-run` preflight: a
+ * single-item read against `ITEM_FIELDS_FRAGMENT`, a null-result throw
+ * with `details.item_id`, then `parseRawItem + projectItem` to surface
+ * the §6.4 dry-run envelope's `item: <projected snapshot>` slot.
+ *
+ * Lifted from three sites — see v0.2-plan §14 R27:
+ *   - `commands/item/archive.ts` action — dry-run path
+ *   - `commands/item/delete.ts` action — dry-run path
+ *   - `commands/item/duplicate.ts` action — dry-run path
+ *
+ * The query body is byte-identical across the three M10 verbs (just
+ * `items(ids:) { ${ITEM_FIELDS_FRAGMENT} }`); only the operation name
+ * differs (`ItemArchiveRead` / `ItemDeleteRead` / `ItemDuplicateRead`).
+ * The op-name divergence exists for fixture cassettes + Monday's
+ * request-log telemetry (so wire calls are distinguishable per verb),
+ * so the helper takes it as a required parameter rather than
+ * collapsing it. M11's `item move` will pass `ItemMoveRead` and
+ * inherit the helper rather than copying the pattern.
+ *
+ * **Why not also for the live-mutation null-handling.** The live
+ * mutation returns the post-mutation item directly; the parsing +
+ * projection shape is shared with R28's
+ * `projectMutationItem`, but the error semantics diverge (live
+ * mutations throw `not_found` with a mutation-name-bearing message
+ * while this helper throws `not_found` with the read-side phrasing).
+ * Two helpers, one per concern.
+ */
+import { ApiError } from '../utils/errors.js';
+import { ITEM_FIELDS_FRAGMENT, parseRawItem, } from './item-helpers.js';
+import { projectItem, } from './item-projection.js';
+/**
+ * Reads the source item for an M10 lifecycle dry-run preview, returns
+ * the §6.2 / §6.3 projected snapshot. Null/missing → typed
+ * `not_found` with `details.item_id` so agents key off the stable
+ * code per cli-design §6.5 (mirrors the live-path null-handling so
+ * the error shape stays identical regardless of which path the agent
+ * took).
+ */
+export const readSourceItemForDryRun = async ({ client, itemId, operationName, }) => {
+    const query = `
+    query ${operationName}($ids: [ID!]!) {
+      items(ids: $ids) {
+        ${ITEM_FIELDS_FRAGMENT}
+      }
+    }
+  `;
+    const response = await client.raw(query, { ids: [itemId] }, { operationName });
+    const items = response.data.items;
+    const first = Array.isArray(items) ? items[0] : undefined;
+    if (first === undefined || first === null) {
+        throw new ApiError('not_found', `Monday returned no item for id ${itemId}`, { details: { item_id: itemId } });
+    }
+    return projectItem({ raw: parseRawItem(first, { item_id: itemId }) });
+};
+//# sourceMappingURL=item-source-read.js.map

package/dist/api/item-source-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-source-read.js","sourceRoot":"","sources":["../../src/api/item-source-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EACL,oBAAoB,EACpB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,GAEZ,MAAM,sBAAsB,CAAC;AAO9B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,EAAE,EAC5C,MAAM,EACN,MAAM,EACN,aAAa,GAKd,EAA0B,EAAE;IAC3B,MAAM,KAAK,GAAG;YACJ,aAAa;;UAEf,oBAAoB;;;GAG3B,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAC/B,KAAK,EACL,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,EACjB,EAAE,aAAa,EAAE,CAClB,CAAC;IACF,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;IAClC,MAAM,KAAK,GAAY,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,QAAQ,CAChB,WAAW,EACX,kCAAkC,MAAM,EAAE,EAC1C,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CACjC,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC,CAAC"}

package/dist/api/items-page-walker.d.ts

@@ -0,0 +1,126 @@
+/**
+ * `items_page` GraphQL helper — single-page fetcher pair
+ * (`v0.2-plan.md` §18 R34).
+ *
+ * Lifted from five sites that all hand-rolled the same
+ * `query Foo($boardId: ID!, $limit: Int!, $queryParams: ItemsQuery)
+ * { boards(ids: [$boardId]) { items_page(...) { cursor items {...} } } }`
+ * shape with per-site item-field projection + per-site
+ * `unwrapOrThrow`-wrapped malformed-response handling. The shared
+ * surface is:
+ *
+ *   - GraphQL string assembly (operation name + optional group-filter
+ *     wrapper + caller-supplied item-fields fragment).
+ *   - Response parse boundary — `boards[0]` (and `groups[0]` for the
+ *     group-filtered variant) → `items_page.{cursor, items[]}` with
+ *     the matching malformed-response context message.
+ *
+ * **Operation name as a parameter**, not a constant. The SDK threads
+ * `operationName` to Monday's request-log telemetry so a `bulk item
+ * update --where` walk is distinguishable from a `bulk item clear
+ * --where` walk in Monday's logs. Same reason §18 R33 stays deferred:
+ * collapsing operations under one name breaks attribution.
+ *
+ * **Item-fields fragment as a string**, not a typed projection. Three
+ * projections in scope today: `id` (clear / update bulk walkers),
+ * `id\n          name` (upsert lookup), `${ITEM_FIELDS_FRAGMENT}`
+ * (item list). Projections are inlined verbatim into the query
+ * source — the per-call response zod schema validates that the rows
+ * Monday returned actually match.
+ *
+ * **Group-filter variant** (`item list --group <gid>`) wraps an extra
+ * `groups(ids: [$groupId])` selection between `boards` and
+ * `items_page`. The helper switches the query shape and the response
+ * schema based on the optional `groupId` input — both the wire shape
+ * and Monday's accepted variable set diverge between the two queries
+ * (the top-level `items_page` doesn't accept `group_id` inside
+ * `query_params`, so the group-aware path is structurally distinct).
+ *
+ * **The cursor walker stays in `pagination.ts`.** All bulk consumers
+ * (item list, item update --where, item clear --where) thread these
+ * single-page fetchers through `paginate.ts`'s `fetchInitial` /
+ * `fetchNext` closures. That preserves the §3.1 #8 per-page
+ * ascending-by-ID sort and the §5.6 `stale_cursor` enrichment
+ * (`cursor_age_seconds` / `items_returned_so_far` / `last_item_id`)
+ * across every site post-lift. Codex round-1 F1 + F2 caught the
+ * variant where a thin generator dropped both — pure refactor must
+ * match pre-lift behavior, not just pre-lift error code.
+ *
+ * **stale_cursor fail-fast.** `cli-design.md` §5.6 — Monday's cursor
+ * lifetime is 60 min, expired cursors return `INVALID_CURSOR_EXCEPTION`
+ * which `api/errors.ts` maps to `error.code === 'stale_cursor'`. The
+ * helper bubbles the error unchanged so `paginate.ts` can layer its
+ * §5.6 details enrichment on top.
+ */
+import { z } from 'zod';
+import type { MondayClient, MondayResponse } from './client.js';
+/**
+ * Inputs for a single `items_page(query_params:)` call. The `groupId`
+ * slot switches the query shape to the `boards.groups.items_page`
+ * variant; absent it the top-level `boards.items_page` is used.
+ */
+export interface ItemsPageInputs<T> {
+    readonly client: MondayClient;
+    /**
+     * Operation name threaded to Monday for telemetry / error
+     * attribution (e.g. `'ItemsPage'`, `'ItemsPageByGroup'`,
+     * `'ItemUpsertLookup'`). Per-call-site naming preserves Monday's
+     * request-log triage even when the underlying GraphQL is identical.
+     */
+    readonly operationName: string;
+    readonly boardId: string;
+    /** Group-filter variant when defined; top-level `items_page` otherwise. */
+    readonly groupId?: string;
+    readonly limit: number;
+    readonly queryParams: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Inner-fragment GraphQL string for the per-row projection — e.g.
+     * `'id'`, `'id\n          name'`, or `${ITEM_FIELDS_FRAGMENT}`.
+     * Inlined verbatim into the query source.
+     */
+    readonly itemFields: string;
+    /** Per-row zod schema. The helper wraps it in the items_page envelope. */
+    readonly itemSchema: z.ZodType<T>;
+}
+/**
+ * Inputs for a single `next_items_page(cursor:)` continuation call.
+ * No `boardId` / `groupId` / `queryParams` — the cursor encodes the
+ * server-side filter state.
+ */
+export interface NextItemsPageInputs<T> {
+    readonly client: MondayClient;
+    readonly operationName: string;
+    readonly cursor: string;
+    readonly limit: number;
+    readonly itemFields: string;
+    readonly itemSchema: z.ZodType<T>;
+}
+/**
+ * Single-page response payload after parse — `MondayResponse.data`
+ * is re-typed to the parsed `{items, cursor}` shape. The wider
+ * response (complexity, stats) passes through unchanged so callers
+ * driving `paginate.ts`'s rich walker can lift `complexity` /
+ * request id off the same envelope they get today.
+ */
+export interface ItemsPagePayload<T> {
+    readonly items: readonly T[];
+    readonly cursor: string | null;
+}
+/**
+ * Fires one `items_page(query_params:)` query and returns the parsed
+ * `{items, cursor}` payload as `MondayResponse.data`. The wider
+ * `MondayResponse` shape (complexity, stats) passes through untouched
+ * so callers can spread it into `toEmit(response)` for `meta`.
+ *
+ * Malformed responses surface as typed `internal_error` carrying
+ * `details.issues` (per-field zod failure path) — same parse-boundary
+ * contract as the standalone `unwrapOrThrow` helper.
+ */
+export declare const fetchItemsPage: <T>(inputs: ItemsPageInputs<T>) => Promise<MondayResponse<ItemsPagePayload<T>>>;
+/**
+ * Fires one `next_items_page(cursor:)` continuation and returns the
+ * parsed `{items, cursor}` payload. Same parse-boundary contract as
+ * {@link fetchItemsPage}.
+ */
+export declare const fetchNextItemsPage: <T>(inputs: NextItemsPageInputs<T>) => Promise<MondayResponse<ItemsPagePayload<T>>>;
+//# sourceMappingURL=items-page-walker.d.ts.map

package/dist/api/items-page-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"items-page-walker.d.ts","sourceRoot":"","sources":["../../src/api/items-page-walker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AA+DD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EACpC,QAAQ,eAAe,CAAC,CAAC,CAAC,KACzB,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAuC7C,CAAC;AAkGF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAU,CAAC,EACxC,QAAQ,mBAAmB,CAAC,CAAC,CAAC,KAC7B,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CA6B7C,CAAC"}