@withpica/mcp-server 1.3.0

package/dist/tools/auth.js

@@ -0,0 +1,212 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { writeCredentials, clearCredentials, } from "@withpica/mcp-utils";
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 5 * 60 * 1000;
+export class AuthTools {
+    config;
+    reinitialize;
+    signOutCallback;
+    constructor(config, reinitialize, signOutCallback = () => { }) {
+        this.config = config;
+        this.reinitialize = reinitialize;
+        this.signOutCallback = signOutCallback;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_sign_in",
+                    description: "sign in to PICA with your email — sends a magic link to your inbox. " +
+                        "use this to connect your music catalog. no API key needed.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            email: {
+                                type: "string",
+                                description: "your email address",
+                            },
+                        },
+                        required: ["email"],
+                    },
+                },
+                executor: this.signIn.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_sign_out",
+                    description: "sign out of PICA — clears your saved credentials",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.signOut.bind(this),
+            },
+        ];
+    }
+    async signIn(args) {
+        const email = args.email?.trim()?.toLowerCase();
+        if (!email || !email.includes("@") || !email.includes(".")) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "that doesn't look like an email address — please try again",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const apiUrl = this.config.picaApiUrl.replace(/\/api$/, "");
+        const authorizeUrl = `${apiUrl}/api/public/mcp-auth/authorize`;
+        const tokenUrl = `${apiUrl}/api/public/mcp-auth/token`;
+        // Step 1: Request magic link
+        let deviceCode;
+        let interval;
+        try {
+            const res = await fetch(authorizeUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ email }),
+            });
+            if (res.status === 429) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "too many sign-in attempts — try again in an hour",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (!res.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "failed to send magic link — please try again",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const data = (await res.json());
+            deviceCode = data.device_code;
+            interval = (data.interval || 3) * 1000;
+            console.error(`[MCP Auth] Magic link sent to ${email}`);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "couldn't reach PICA — check your internet connection and try again",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Step 2: Poll for token
+        const startTime = Date.now();
+        while (Date.now() - startTime < POLL_TIMEOUT_MS) {
+            await new Promise((resolve) => setTimeout(resolve, interval));
+            try {
+                const res = await fetch(tokenUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        device_code: deviceCode,
+                        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    }),
+                });
+                const data = (await res.json());
+                if (data.error === "authorization_pending") {
+                    continue;
+                }
+                if (data.error === "expired_token") {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "magic link expired — say 'sign me in' to try again",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (data.access_token) {
+                    const credentials = {
+                        api_key: data.access_token,
+                        email,
+                        org_name: data.org_name || "my catalog",
+                        authenticated_at: new Date().toISOString(),
+                    };
+                    writeCredentials(this.config.credentialsPath, credentials);
+                    this.reinitialize(data.access_token);
+                    console.error(`[MCP Auth] Signed in as ${email}`);
+                    if (data.is_new_user) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `welcome to PICA, ${email}. you're all signed in.\n\n` +
+                                        `quick first thing — your workspace is currently named "My Organization" (the boring default). want to give it a real name? it'll appear on exports, share links, and anywhere else your catalog shows up. just tell me what to call it, or say "skip" to set it later.\n\n` +
+                                        `after that, we can:\n` +
+                                        `- add your first song manually\n` +
+                                        `- import an existing catalog from a CSV\n` +
+                                        `- connect Spotify and pull your discography automatically\n\n` +
+                                        `what works for you?`,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `signed in as ${email} (${data.org_name || "my catalog"}).\n\n` +
+                                    `all tools are now available. try "what needs attention?" to see your catalog status.`,
+                            },
+                        ],
+                    };
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "magic link expired — say 'sign me in' to try again",
+                },
+            ],
+            isError: true,
+        };
+    }
+    async signOut(_args) {
+        clearCredentials(this.config.credentialsPath);
+        // Reset the server back to lobby mode: clear PicaClient, rebuild
+        // toolRegistry/resourceRegistry so the next tools/list call returns
+        // only [pica_sign_in, pica_sign_out]. Without this the client keeps
+        // seeing the full authenticated tool surface until the process is
+        // restarted, which would let an "ex-signed-out" client still call
+        // privileged tools (the calls would fail at the API layer, but the
+        // surface area itself shouldn't lie about what's available).
+        this.signOutCallback();
+        console.error("[MCP Auth] Signed out — credentials cleared, lobby restored");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "signed out of PICA. say 'sign me in' to reconnect.",
+                },
+            ],
+        };
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/tools/auth.js.map

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

package/dist/tools/bulk.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bulk Operations Tools — MCP tools for batch updates.
+ *
+ * ADR-174 Phase 2 item 2 follow-up: `pica_works_bulk_update.updates`
+ * validates against `WORK_WRITE_PROPERTIES` — the same canonical source
+ * of truth that gates `pica_works_update`. Without this, bulk update is
+ * the last surface that still accepts any key (the silent-data-loss
+ * vector the audit flagged at row 25).
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class BulkTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private bulkUpdateWorks;
+    private bulkUpdatePeopleRoles;
+}
+//# sourceMappingURL=bulk.d.ts.map

package/dist/tools/bulk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk.d.ts","sourceRoot":"","sources":["../../src/tools/bulk.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EACL,cAAc,EACd,YAAY,EAGb,MAAM,YAAY,CAAC;AAepB,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA6E3D,eAAe;YAyDf,qBAAqB;CA4CpC"}

package/dist/tools/bulk.js

@@ -0,0 +1,164 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { elicitBulkConfirmation, formatSuccess, formatValidationError, } from "@withpica/mcp-utils";
+import { WORK_WRITE_PROPERTIES } from "./works.js";
+/**
+ * Set of legal keys for the bulk `updates` object. Mirrors the
+ * `pica_works_update` schema exactly — if it's not writable singly,
+ * it's not writable in bulk either.
+ */
+const BULK_UPDATE_ALLOWED_KEYS = new Set(Object.keys(WORK_WRITE_PROPERTIES));
+export class BulkTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_works_bulk_update",
+                    description: "Batch update multiple works at once. The `updates` object validates against the same " +
+                        "schema as `pica_works_update` — only real `works` columns are accepted. " +
+                        "Phantom keys (label, upc, album_name, album_art_url, album_release_date, track_number, " +
+                        "spotify_url) are rejected with the same redirect hints as the single-update tool.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Array of work IDs to update",
+                            },
+                            updates: {
+                                type: "object",
+                                description: "Fields to apply to every work in `work_ids`. Same schema as `pica_works_update` " +
+                                    "minus the `id` field. Every key must be a real `works` column.",
+                                properties: WORK_WRITE_PROPERTIES,
+                            },
+                            dry_run: {
+                                type: "boolean",
+                                description: "When true, returns { dry_run: true, would_affect, sample_changes } without persisting any update. Use to preview the bulk before committing.",
+                            },
+                        },
+                        required: ["work_ids", "updates"],
+                    },
+                    previewMode: "dry_run",
+                },
+                executor: this.bulkUpdateWorks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_people_bulk_update_roles",
+                    description: "Batch update roles for multiple people at once",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            person_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Array of person IDs to update",
+                            },
+                            action: {
+                                type: "string",
+                                enum: ["add", "remove"],
+                                description: "Whether to add or remove the specified roles",
+                            },
+                            roles: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Roles to add/remove (e.g. ['writer', 'composer', 'performer'])",
+                            },
+                            dry_run: {
+                                type: "boolean",
+                                description: "When true, returns { dry_run: true, would_affect, sample_changes } without modifying any person. Preview before committing.",
+                            },
+                        },
+                        required: ["person_ids", "action", "roles"],
+                    },
+                    previewMode: "dry_run",
+                },
+                executor: this.bulkUpdatePeopleRoles.bind(this),
+            },
+        ];
+    }
+    async bulkUpdateWorks(args, ctx) {
+        if (!args.work_ids?.length) {
+            return formatValidationError({ work_ids: "must be a non-empty array" });
+        }
+        if (!args.updates || Object.keys(args.updates).length === 0) {
+            return formatValidationError({
+                updates: "must contain at least one field",
+            });
+        }
+        // ADR-174 Phase 2 — every key must be a real `works` column. Without
+        // this runtime check, an agent could still call the tool with a
+        // phantom key (e.g. upc) and the HTTP backstop would 400 per row —
+        // wasteful and opaque. Fail fast at the tool boundary instead.
+        const invalidKeys = Object.keys(args.updates).filter((k) => !BULK_UPDATE_ALLOWED_KEYS.has(k));
+        if (invalidKeys.length > 0) {
+            return formatValidationError({
+                updates: `unknown field(s): ${invalidKeys.join(", ")}. Allowed fields match pica_works_update: ${[...BULK_UPDATE_ALLOWED_KEYS].sort().join(", ")}`,
+            });
+        }
+        // ADR-199 Stream 5a — dry_run preview. Validation already passed,
+        // so the preview reflects exactly what would be sent.
+        if (args.dry_run === true) {
+            return formatSuccess(`Dry run — would update ${args.work_ids.length} work(s) with ${Object.keys(args.updates).length} field(s)`, {
+                dry_run: true,
+                would_affect: args.work_ids,
+                sample_changes: args.updates,
+                field_count: Object.keys(args.updates).length,
+                target_count: args.work_ids.length,
+            });
+        }
+        // ADR-200 Phase 1 — Class D form-confirmation gate. Returns
+        // `no_gate` for clients without elicitation support (universal
+        // floor), or after the user accepts with confirm=true.
+        const gate = await elicitBulkConfirmation({
+            server: ctx?.server,
+            args,
+            action: "Bulk-update works",
+            impactSummary: `${args.work_ids.length} work(s), ${Object.keys(args.updates).length} field(s)`,
+            warning: "This update is applied to every selected work and cannot be undone in bulk.",
+        });
+        if (gate.kind === "abort")
+            return gate.result;
+        const result = await this.pica.bulk.updateWorks(args.work_ids, args.updates);
+        return formatSuccess(`Bulk updated ${args.work_ids.length} works`, result);
+    }
+    async bulkUpdatePeopleRoles(args, ctx) {
+        if (!args.person_ids?.length) {
+            return formatValidationError({ person_ids: "must be a non-empty array" });
+        }
+        if (!args.roles?.length) {
+            return formatValidationError({ roles: "must be a non-empty array" });
+        }
+        // ADR-199 Stream 5a — dry_run preview before role mutation.
+        if (args.dry_run === true) {
+            const action = args.action || "add";
+            return formatSuccess(`Dry run — would ${action} ${args.roles.length} role(s) on ${args.person_ids.length} person(s)`, {
+                dry_run: true,
+                would_affect: args.person_ids,
+                action,
+                roles: args.roles,
+                target_count: args.person_ids.length,
+            });
+        }
+        // ADR-200 Phase 1 — Class D form-confirmation gate.
+        const action = args.action || "add";
+        const gate = await elicitBulkConfirmation({
+            server: ctx?.server,
+            args,
+            action: `Bulk ${action} roles`,
+            impactSummary: `${args.roles.length} role(s) across ${args.person_ids.length} person(s)`,
+            warning: `Roles to ${action}: ${args.roles.join(", ")}.`,
+        });
+        if (gate.kind === "abort")
+            return gate.result;
+        const result = await this.pica.bulk.updatePeopleRoles(args.person_ids, args.roles, action);
+        return formatSuccess(`Bulk updated roles for ${args.person_ids.length} people`, result);
+    }
+}
+//# sourceMappingURL=bulk.js.map

package/dist/tools/bulk.js.map

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

package/dist/tools/calendar.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Calendar Tools — view upcoming events, deadlines, and scheduled sessions
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class CalendarTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private getEvents;
+}
+//# sourceMappingURL=calendar.d.ts.map

package/dist/tools/calendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/tools/calendar.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA6C3D,SAAS;CAqBxB"}

package/dist/tools/calendar.js

@@ -0,0 +1,68 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatStructuredList } from "@withpica/mcp-utils";
+export class CalendarTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_calendar_events",
+                    description: "Get upcoming calendar events — sessions, agreement deadlines, release dates, " +
+                        "invoice due dates, and Google Calendar events. Defaults to the next 30 days.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            start_date: {
+                                type: "string",
+                                description: "Start date (YYYY-MM-DD). Defaults to today.",
+                            },
+                            end_date: {
+                                type: "string",
+                                description: "End date (YYYY-MM-DD). Defaults to 30 days from start.",
+                            },
+                            types: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Filter by event type: session, invoice_due, invoice_sent, " +
+                                    "payment_received, agreement_expiry, agreement_signing, " +
+                                    "work_release, google_calendar",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Filter events linked to a specific work",
+                            },
+                            search: {
+                                type: "string",
+                                description: "Search events by title",
+                            },
+                        },
+                    },
+                },
+                executor: this.getEvents.bind(this),
+            },
+        ];
+    }
+    async getEvents(args) {
+        const today = new Date().toISOString().split("T")[0];
+        const thirtyDays = new Date(Date.now() + 30 * 86400000)
+            .toISOString()
+            .split("T")[0];
+        const result = await this.pica.calendar.getEvents({
+            startDate: args.start_date || today,
+            endDate: args.end_date || thirtyDays,
+            types: args.types,
+            workId: args.work_id,
+            search: args.search,
+        });
+        const events = Array.isArray(result) ? result : result?.events || [];
+        return formatStructuredList(events, "event", {
+            startDate: args.start_date || today,
+            endDate: args.end_date || thirtyDays,
+        });
+    }
+}
+//# sourceMappingURL=calendar.js.map

package/dist/tools/calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.js","sourceRoot":"","sources":["../../src/tools/calendar.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAQ7D,OAAO,EAAiB,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE1E,MAAM,OAAO,aAAa;IAChB,IAAI,CAAa;IAEzB,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,QAAQ;QACN,OAAO;YACL;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,sBAAsB;oBAC5B,WAAW,EACT,+EAA+E;wBAC/E,8EAA8E;oBAChF,SAAS,EAAE,gBAAgB;oBAC3B,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,UAAU,EAAE;gCACV,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,6CAA6C;6BAC3D;4BACD,QAAQ,EAAE;gCACR,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,wDAAwD;6BAC3D;4BACD,KAAK,EAAE;gCACL,IAAI,EAAE,OAAO;gCACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gCACzB,WAAW,EACT,4DAA4D;oCAC5D,yDAAyD;oCACzD,+BAA+B;6BAClC;4BACD,OAAO,EAAE;gCACP,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,yCAAyC;6BACvD;4BACD,MAAM,EAAE;gCACN,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,wBAAwB;6BACtC;yBACF;qBACF;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;aACpC;SACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAAyB;QAC/C,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC;aACpD,WAAW,EAAE;aACb,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;YAChD,SAAS,EAAE,IAAI,CAAC,UAAU,IAAI,KAAK;YACnC,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,UAAU;YACpC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC;QAErE,OAAO,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE;YAC3C,SAAS,EAAE,IAAI,CAAC,UAAU,IAAI,KAAK;YACnC,OAAO,EAAE,IAAI,CAAC,QAAQ,IAAI,UAAU;SACrC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/tools/collaborators.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Collaborator Tools - MCP tools for inviting and managing collaborators
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class CollaboratorsTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private inviteCollaborator;
+    private listInvites;
+    private resendInvite;
+    private listIncoming;
+    private acceptInvite;
+    private disputeInvite;
+    private inviteBulk;
+}
+//# sourceMappingURL=collaborators.d.ts.map

package/dist/tools/collaborators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collaborators.d.ts","sourceRoot":"","sources":["../../src/tools/collaborators.ts"],"names":[],"mappings":"AAeA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EACL,cAAc,EACd,YAAY,EAGb,MAAM,YAAY,CAAC;AAQpB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAqP3D,kBAAkB;YAgClB,WAAW;YAmCX,YAAY;YAQZ,YAAY;YAoBZ,YAAY;YAiBZ,aAAa;YAWb,UAAU;CA+DzB"}