@vurb/core 3.2.0

package/dist/core/builder/defineTool.d.ts

@@ -0,0 +1,180 @@
+/**
+ * defineTool() — High-Level Tool Definition (Vercel/Stripe Style)
+ *
+ * The recommended entry point for building MCP tools. Write a plain
+ * JSON-like config object — zero Zod imports, zero builder patterns.
+ * The framework converts everything to Zod schemas internally.
+ *
+ * @example
+ * ```typescript
+ * import { defineTool, success } from 'vurb';
+ *
+ * export const projects = defineTool('projects', {
+ *     description: 'Manage workspace projects',
+ *     shared: { workspace_id: 'string' },
+ *     actions: {
+ *         list:   { readOnly: true, handler: async (ctx, args) => success([]) },
+ *         create: { params: { name: 'string' }, handler: async (ctx, args) => success(args.name) },
+ *     },
+ * });
+ * ```
+ *
+ * @see {@link createTool} for the power-user builder API
+ * @see {@link ToolRegistry} for registering tools
+ *
+ * @module
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { GroupedToolBuilder } from './GroupedToolBuilder.js';
+import { type ToolResponse, type MiddlewareFn } from '../types.js';
+import { type MiddlewareDefinition } from '../middleware/ContextDerivation.js';
+import { type Presenter } from '../../presenter/Presenter.js';
+import { type ParamsMap, type InferParams } from './ParamDescriptors.js';
+/**
+ * Action definition within a `defineTool()` config.
+ *
+ * When `params` is provided as a `ParamsMap`, the handler's `args` are
+ * automatically typed as `InferParams<TParams> & TSharedArgs`.
+ * When `params` is a ZodObject, use `z.infer<typeof schema>` for manual typing.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TSharedArgs - Shared args inherited from ToolConfig.shared
+ * @typeParam TParams - Action-specific params (inferred from the params field)
+ */
+export interface ActionDef<TContext, TSharedArgs = Record<string, never>, TParams extends ParamsMap = ParamsMap> {
+    /** Human-readable description for the LLM */
+    description?: string;
+    /** Parameter definitions (JSON descriptors or Zod schema) */
+    params?: TParams | ZodObject<ZodRawShape>;
+    /** Mark as read-only (no side effects) */
+    readOnly?: boolean;
+    /** Mark as destructive (irreversible) */
+    destructive?: boolean;
+    /** Mark as idempotent (safe to retry) */
+    idempotent?: boolean;
+    /** Common schema fields to omit for this action */
+    omitCommon?: string[];
+    /** MVA Presenter — when set, handler returns raw data instead of ToolResponse */
+    returns?: Presenter<unknown>;
+    /** The handler function — args are fully typed when params is specified */
+    handler: (ctx: TContext, args: TParams extends ParamsMap ? (keyof TParams extends never ? TSharedArgs & Record<string, unknown> : InferParams<TParams> & TSharedArgs) : TSharedArgs & Record<string, unknown>) => Promise<ToolResponse>;
+}
+/**
+ * Group definition within a `defineTool()` config.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TSharedArgs - Inferred shared args type
+ */
+export interface GroupDef<TContext, TSharedArgs = Record<string, never>> {
+    /** Human-readable group description */
+    description?: string;
+    /** Common schema fields to omit for all actions in this group */
+    omitCommon?: string[];
+    /** Group-scoped middleware (accepts both MiddlewareFn and MiddlewareDefinition) */
+    middleware?: (MiddlewareFn<TContext> | MiddlewareDefinition<TContext, Record<string, unknown>>)[];
+    /** Actions within this group — each action's params are inferred independently */
+    actions: {
+        [K in string]: ActionDef<TContext, TSharedArgs>;
+    };
+}
+/**
+ * Full `defineTool()` configuration.
+ *
+ * @typeParam TContext - Application context type
+ * @typeParam TShared - Shared params map type
+ */
+export interface ToolConfig<TContext, TShared extends ParamsMap = ParamsMap> {
+    /** Tool description for the LLM */
+    description?: string;
+    /** Capability tags for filtering */
+    tags?: string[];
+    /** Discriminator field name (default: 'action') */
+    discriminator?: string;
+    /** Use TOON-formatted descriptions */
+    toonDescription?: boolean;
+    /** Parameters shared across all actions */
+    shared?: TShared | ZodObject<ZodRawShape>;
+    /** Global middleware applied to all actions (accepts both MiddlewareFn and MiddlewareDefinition) */
+    middleware?: (MiddlewareFn<TContext> | MiddlewareDefinition<TContext, Record<string, unknown>>)[];
+    /** MCP tool annotations (e.g. `{ readOnlyHint: true, openWorldHint: true }`) */
+    annotations?: Record<string, unknown>;
+    /** Flat actions — each action's params are inferred independently */
+    actions?: {
+        [K in string]: ActionDef<TContext, InferParams<TShared>>;
+    };
+    /** Hierarchical groups (mutually exclusive with `actions`) */
+    groups?: {
+        [K in string]: GroupDef<TContext, InferParams<TShared>>;
+    };
+}
+/** Expected return type for handlers */
+export type ExpectedHandlerReturnType = Promise<ToolResponse> | AsyncGenerator<unknown, ToolResponse, unknown>;
+/**
+ * Utility type to force a readable, localized TypeScript error if a handler
+ * does not return exactly `ToolResponse` or `AsyncGenerator<..., ToolResponse, ...>`.
+ */
+export type ValidateActionDef<TAction> = TAction extends {
+    handler: (...args: unknown[]) => infer R;
+} ? [R] extends [ExpectedHandlerReturnType] ? TAction : Omit<TAction, 'handler'> & {
+    handler: "❌ Type Error: handler must return ToolResponse. Use return success(data) or return error(msg).";
+} : TAction;
+/**
+ * Deep validation of the tool config to intercept handler return types
+ * and provide readable errors without causing 50-line RecursiveBuilder issues.
+ */
+export type ValidateConfig<C> = C extends ToolConfig<infer _TContext, infer _TShared> ? {
+    [K in keyof C]: K extends 'actions' ? {
+        [A in keyof C['actions']]: ValidateActionDef<C['actions'][A]>;
+    } : K extends 'groups' ? {
+        [G in keyof C['groups']]: {
+            [GK in keyof C['groups'][G]]: GK extends 'actions' ? {
+                [A in keyof NonNullable<C['groups']>[G]['actions']]: ValidateActionDef<NonNullable<C['groups']>[G]['actions'][A]>;
+            } : NonNullable<C['groups']>[G][GK];
+        };
+    } : C[K];
+} : C;
+/**
+ * Define a tool using a high-level JSON-like config.
+ *
+ * This is the recommended entry point for most developers.
+ * The framework handles all Zod schema creation, validation,
+ * and MCP protocol details internally.
+ *
+ * @example
+ * ```typescript
+ * const echo = defineTool('echo', {
+ *     actions: {
+ *         say: {
+ *             params: { message: 'string' },
+ *             handler: async (ctx, args) => success(args.message),
+ *         },
+ *     },
+ * });
+ *
+ * // Tool with shared params + groups + middleware
+ * const platform = defineTool<AppContext>('platform', {
+ *     description: 'Platform management',
+ *     tags: ['admin'],
+ *     shared: { workspace_id: { type: 'string', description: 'Workspace ID' } },
+ *     middleware: [requireAuth],
+ *     groups: {
+ *         users: {
+ *             description: 'User management',
+ *             actions: {
+ *                 list: { readOnly: true, handler: listUsers },
+ *                 ban:  { destructive: true, params: { user_id: 'string' }, handler: banUser },
+ *             },
+ *         },
+ *     },
+ * });
+ *
+ * // Register normally
+ * const registry = new ToolRegistry<AppContext>();
+ * registry.register(platform);
+ * ```
+ *
+ * @see {@link createTool} for the power-user builder API
+ * @see {@link ToolRegistry.register} for registration
+ */
+export declare function defineTool<TContext = void>(name: string, config: ToolConfig<TContext>): GroupedToolBuilder<TContext>;
+//# sourceMappingURL=defineTool.d.ts.map

package/dist/core/builder/defineTool.d.ts.map

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

package/dist/core/builder/defineTool.js

@@ -0,0 +1,164 @@
+/**
+ * defineTool() — High-Level Tool Definition (Vercel/Stripe Style)
+ *
+ * The recommended entry point for building MCP tools. Write a plain
+ * JSON-like config object — zero Zod imports, zero builder patterns.
+ * The framework converts everything to Zod schemas internally.
+ *
+ * @example
+ * ```typescript
+ * import { defineTool, success } from 'vurb';
+ *
+ * export const projects = defineTool('projects', {
+ *     description: 'Manage workspace projects',
+ *     shared: { workspace_id: 'string' },
+ *     actions: {
+ *         list:   { readOnly: true, handler: async (ctx, args) => success([]) },
+ *         create: { params: { name: 'string' }, handler: async (ctx, args) => success(args.name) },
+ *     },
+ * });
+ * ```
+ *
+ * @see {@link createTool} for the power-user builder API
+ * @see {@link ToolRegistry} for registering tools
+ *
+ * @module
+ */
+import {} from 'zod';
+import { GroupedToolBuilder } from './GroupedToolBuilder.js';
+import {} from '../types.js';
+import { resolveMiddleware } from '../middleware/ContextDerivation.js';
+import {} from '../../presenter/Presenter.js';
+import { convertParamsToZod, } from './ParamDescriptors.js';
+import { isZodSchema } from '../schema/SchemaUtils.js';
+// ============================================================================
+// defineTool()
+// ============================================================================
+/**
+ * Resolve params: if ParamsMap → convertParamsToZod, if ZodObject → passthrough.
+ * @internal
+ */
+function resolveSchema(params) {
+    if (!params)
+        return undefined;
+    if (isZodSchema(params))
+        return params;
+    return convertParamsToZod(params);
+}
+/**
+ * Define a tool using a high-level JSON-like config.
+ *
+ * This is the recommended entry point for most developers.
+ * The framework handles all Zod schema creation, validation,
+ * and MCP protocol details internally.
+ *
+ * @example
+ * ```typescript
+ * const echo = defineTool('echo', {
+ *     actions: {
+ *         say: {
+ *             params: { message: 'string' },
+ *             handler: async (ctx, args) => success(args.message),
+ *         },
+ *     },
+ * });
+ *
+ * // Tool with shared params + groups + middleware
+ * const platform = defineTool<AppContext>('platform', {
+ *     description: 'Platform management',
+ *     tags: ['admin'],
+ *     shared: { workspace_id: { type: 'string', description: 'Workspace ID' } },
+ *     middleware: [requireAuth],
+ *     groups: {
+ *         users: {
+ *             description: 'User management',
+ *             actions: {
+ *                 list: { readOnly: true, handler: listUsers },
+ *                 ban:  { destructive: true, params: { user_id: 'string' }, handler: banUser },
+ *             },
+ *         },
+ *     },
+ * });
+ *
+ * // Register normally
+ * const registry = new ToolRegistry<AppContext>();
+ * registry.register(platform);
+ * ```
+ *
+ * @see {@link createTool} for the power-user builder API
+ * @see {@link ToolRegistry.register} for registration
+ */
+export function defineTool(name, config) {
+    const { description, tags, discriminator, toonDescription, annotations, shared, middleware, actions, groups } = config;
+    // ── Guard: actions and groups are mutually exclusive ──
+    if (actions && groups) {
+        throw new Error(`defineTool("${name}"): "actions" and "groups" are mutually exclusive. ` +
+            `Use "actions" for flat tools OR "groups" for hierarchical tools, not both.`);
+    }
+    const builder = new GroupedToolBuilder(name);
+    // ── Builder configuration (declarative) ──
+    if (description)
+        builder.description(description);
+    if (tags != null && tags.length > 0)
+        builder.tags(...tags);
+    if (discriminator)
+        builder.discriminator(discriminator);
+    if (toonDescription)
+        builder.toonDescription();
+    if (annotations)
+        builder.annotations(annotations);
+    const sharedSchema = resolveSchema(shared);
+    if (sharedSchema)
+        builder.commonSchema(sharedSchema);
+    middleware?.forEach(mw => builder.use(resolveMiddleware(mw)));
+    // ── Register actions/groups ──
+    if (actions) {
+        for (const [actionName, actionDef] of Object.entries(actions)) {
+            builder.action(buildActionConfig(actionName, actionDef));
+        }
+    }
+    if (groups) {
+        for (const [groupName, groupDef] of Object.entries(groups)) {
+            registerGroup(builder, groupName, groupDef);
+        }
+    }
+    return builder;
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Build an ActionConfig from an ActionDef — single source of truth
+ * for translating high-level descriptors to builder config.
+ * @internal
+ */
+function buildActionConfig(actionName, def) {
+    const schema = resolveSchema(def.params);
+    return {
+        name: actionName,
+        handler: def.handler,
+        ...(def.description && { description: def.description }),
+        ...(schema && { schema }),
+        ...(def.readOnly !== undefined && { readOnly: def.readOnly }),
+        ...(def.destructive !== undefined && { destructive: def.destructive }),
+        ...(def.idempotent !== undefined && { idempotent: def.idempotent }),
+        ...((def.omitCommon?.length ?? 0) > 0 && { omitCommon: def.omitCommon }),
+        ...(def.returns && { returns: def.returns }),
+    };
+}
+/**
+ * Register a group with its actions on a builder.
+ * @internal
+ */
+function registerGroup(builder, groupName, def) {
+    builder.group(groupName, def.description ?? '', g => {
+        if (def.omitCommon != null && def.omitCommon.length > 0) {
+            g.omitCommon(...def.omitCommon);
+        }
+        def.middleware?.forEach(mw => g.use(resolveMiddleware(mw)));
+        for (const [actionName, actionDef] of Object.entries(def.actions)) {
+            g.action(buildActionConfig(actionName, actionDef));
+        }
+    });
+}
+//# sourceMappingURL=defineTool.js.map

package/dist/core/builder/defineTool.js.map

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

package/dist/core/builder/index.d.ts

@@ -0,0 +1,13 @@
+/** Builder Bounded Context — Barrel Export */
+export { GroupedToolBuilder, ActionGroupBuilder, createTool } from './GroupedToolBuilder.js';
+export type { GroupConfigurator } from './ActionGroupBuilder.js';
+export { compileToolDefinition } from './ToolDefinitionCompiler.js';
+export { defineTool } from './defineTool.js';
+export type { ToolConfig, ActionDef, GroupDef } from './defineTool.js';
+export { convertParamsToZod } from './ParamDescriptors.js';
+export type { ParamDef, ParamsMap, InferParams, StringParamDef, NumberParamDef, BooleanParamDef, EnumParamDef, ArrayParamDef, } from './ParamDescriptors.js';
+export { FluentToolBuilder } from './FluentToolBuilder.js';
+export type { SemanticDefaults } from './FluentToolBuilder.js';
+export { FluentRouter } from './FluentRouter.js';
+export { ErrorBuilder } from './ErrorBuilder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/builder/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC7F,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACR,QAAQ,EAAE,SAAS,EAAE,WAAW,EAChC,cAAc,EAAE,cAAc,EAAE,eAAe,EAC/C,YAAY,EAAE,aAAa,GAC9B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/core/builder/index.js

@@ -0,0 +1,13 @@
+/** Builder Bounded Context — Barrel Export */
+export { GroupedToolBuilder, ActionGroupBuilder, createTool } from './GroupedToolBuilder.js';
+export { compileToolDefinition } from './ToolDefinitionCompiler.js';
+export { defineTool } from './defineTool.js';
+export { convertParamsToZod } from './ParamDescriptors.js';
+// ── Fluent API ───────────────────────────────────────────
+export { FluentToolBuilder } from './FluentToolBuilder.js';
+export { FluentRouter } from './FluentRouter.js';
+export { ErrorBuilder } from './ErrorBuilder.js';
+// ── Internal Schema Helpers (not public API) ─────────────
+// FluentSchemaHelpers remain for internal use by other modules
+// but are NOT re-exported to consumers.
+//# sourceMappingURL=index.js.map

package/dist/core/builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/builder/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAO3D,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,4DAA4D;AAC5D,+DAA+D;AAC/D,wCAAwC"}

package/dist/core/createGroup.d.ts

@@ -0,0 +1,140 @@
+/**
+ * createGroup() — Functional Tool Group Compiler
+ *
+ * A lightweight, closure-based alternative to the class-heavy
+ * `GroupedToolBuilder`. Instead of maintaining internal state via `this._x`,
+ * it compiles a group config into a frozen object with pre-composed
+ * middleware and an O(1) dispatch function.
+ *
+ * **Why Functional?**
+ * - Closures minify 30-40% better than class methods (Terser can rename local vars)
+ * - No prototype chain overhead — zero `this` binding issues
+ * - Frozen return type prevents accidental mutation
+ * - Compatible with Edge Runtimes (Cloudflare Workers, Deno Deploy)
+ *
+ * @example
+ * ```typescript
+ * import { createGroup, success } from 'vurb';
+ *
+ * const billing = createGroup({
+ *   name: 'billing',
+ *   description: 'Invoice management',
+ *   middleware: [requireAuth],
+ *   actions: {
+ *     get_invoice: {
+ *       schema: z.object({ id: z.string() }),
+ *       readOnly: true,
+ *       handler: async (ctx, args) => success(await ctx.db.invoices.get(args.id)),
+ *     },
+ *     pay: {
+ *       schema: z.object({ invoice_id: z.string(), amount: z.number() }),
+ *       destructive: true,
+ *       handler: async (ctx, args) => success(await ctx.db.payments.create(args)),
+ *     },
+ *   },
+ * });
+ *
+ * // billing.execute(ctx, 'get_invoice', { id: '123' })
+ * // billing.name === 'billing'
+ * // billing.actionNames === ['get_invoice', 'pay']
+ * ```
+ *
+ * @module
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type ToolResponse } from '../core/response.js';
+import { type MiddlewareFn } from '../core/types.js';
+/**
+ * A single action definition within a group.
+ */
+export interface GroupAction<TContext> {
+    /** Human-readable description for the LLM */
+    readonly description?: string;
+    /** Zod schema for input validation */
+    readonly schema?: ZodObject<ZodRawShape>;
+    /** Mark as read-only */
+    readonly readOnly?: boolean;
+    /** Mark as destructive */
+    readonly destructive?: boolean;
+    /** Mark as idempotent */
+    readonly idempotent?: boolean;
+    /** Per-action middleware */
+    readonly middleware?: MiddlewareFn<TContext>[];
+    /** Handler function */
+    readonly handler: (ctx: TContext, args: Record<string, unknown>) => Promise<ToolResponse>;
+}
+/**
+ * Full configuration for `createGroup()`.
+ */
+export interface GroupConfig<TContext> {
+    /** Group/tool name */
+    readonly name: string;
+    /** Description for the LLM */
+    readonly description?: string;
+    /** Capability tags */
+    readonly tags?: string[];
+    /** Shared middleware applied to ALL actions (outermost layer) */
+    readonly middleware?: MiddlewareFn<TContext>[];
+    /** Action definitions keyed by action name */
+    readonly actions: Record<string, GroupAction<TContext>>;
+}
+/**
+ * A compiled, frozen group ready for execution.
+ */
+export interface CompiledGroup<TContext> {
+    /** Group/tool name */
+    readonly name: string;
+    /** Description */
+    readonly description: string | undefined;
+    /** Tags */
+    readonly tags: readonly string[];
+    /** List of action names */
+    readonly actionNames: readonly string[];
+    /**
+     * Execute an action by name.
+     *
+     * @param ctx - Application context
+     * @param action - Action name
+     * @param args - Input arguments
+     * @returns Tool response
+     * @throws If action name is unknown
+     */
+    readonly execute: (ctx: TContext, action: string, args: Record<string, unknown>) => Promise<ToolResponse>;
+    /**
+     * Get metadata for a specific action.
+     */
+    readonly getAction: (name: string) => Readonly<GroupAction<TContext>> | undefined;
+}
+/**
+ * Create a compiled, frozen tool group from a declarative config.
+ *
+ * The returned object has O(1) action dispatch via a pre-built Map.
+ * All middleware chains are pre-composed at creation time — zero
+ * runtime overhead on each call.
+ *
+ * @typeParam TContext - Application context type
+ * @param config - Group configuration with actions
+ * @returns A frozen {@link CompiledGroup} ready for execution
+ *
+ * @example
+ * ```typescript
+ * const tasks = createGroup({
+ *   name: 'tasks',
+ *   middleware: [logMiddleware],
+ *   actions: {
+ *     list: {
+ *       readOnly: true,
+ *       handler: async (ctx) => success(await ctx.db.tasks.findMany()),
+ *     },
+ *     create: {
+ *       schema: z.object({ title: z.string() }),
+ *       handler: async (ctx, args) => success(await ctx.db.tasks.create(args)),
+ *     },
+ *   },
+ * });
+ *
+ * const result = await tasks.execute(ctx, 'create', { title: 'Buy milk' });
+ * ```
+ */
+export declare function createGroup<TContext = void>(config: GroupConfig<TContext>): CompiledGroup<TContext>;
+//# sourceMappingURL=createGroup.d.ts.map

package/dist/core/createGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createGroup.d.ts","sourceRoot":"","sources":["../../src/core/createGroup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AACvD,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IACzC,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC/C,uBAAuB;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ;IACjC,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC/C,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ;IACnC,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1G;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,CAAC;CACrF;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,WAAW,CAAC,QAAQ,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,CAoEnG"}