@collage-dam/mcp-server 0.1.0

package/dist/tools/audit/types.js

@@ -0,0 +1,188 @@
+// ── Shared Audit Report Types (T1) ──────────────────────────────────
+//
+// All Phase 1 / Phase 1.5 audit tools (`audit_tagging_hygiene`, and later
+// `audit_folder_structure`, `audit_naming_conventions`, `detect_duplicates`)
+// produce a uniform `AuditReport<TFindingMeta>` envelope so consumers can
+// render a consistent UI and route findings through the same fix-suggestion
+// pipeline.
+//
+// Design notes:
+//   - Score is an integer 0–100, deterministic (no LLM, no randomness),
+//     computed by each audit's own scoring function. The shape lives here
+//     so result envelopes stay uniform.
+//   - Findings carry only structured fields. Human-readable copy lives in
+//     `message`, but downstream code MUST be able to act on findings using
+//     `id` / `category` / `severity` / `count` / `sample_asset_ids` alone.
+//   - Next-step hints are STRUCTURED, not prose. They point at concrete
+//     mutating tools (e.g. `bulk_set_tags`) plus the exact arguments that
+//     the caller should preview-confirm. This keeps the audit→fix loop
+//     deterministic and machine-routable.
+//   - The envelope is generic over a per-audit `TFindingMeta` type (defaults
+//     to `unknown`) so each audit can attach its own typed `meta` to a
+//     finding without polluting the shared shape. Phase 1.5 audits reuse
+//     this file unchanged — only the meta type parameter differs.
+import { z } from 'zod';
+// ── Score ────────────────────────────────────────────────────────────
+/**
+ * Audit score. Always 0–100 inclusive, integer, deterministic.
+ *
+ * Each audit MUST document its scoring formula in code comments. A score
+ * of 100 means "no findings"; lower scores reflect penalties summed across
+ * findings, weighted by severity. Scores are clamped at 0 — they never go
+ * negative even if penalties exceed 100.
+ */
+export const AuditScoreSchema = z.number().int().min(0).max(100);
+// ── Severity ─────────────────────────────────────────────────────────
+export const AuditSeveritySchema = z.enum(['info', 'warning', 'critical']);
+// ── Finding ──────────────────────────────────────────────────────────
+/**
+ * A single structured finding.
+ *
+ *   id                 — stable identifier within this report; used by
+ *                        downstream code to correlate next-step hints
+ *                        back to the finding that produced them.
+ *   category           — bucket name (e.g. `untagged_assets`,
+ *                        `inconsistent_casing`). Stable across runs so
+ *                        clients can group / dedupe across reports.
+ *   severity           — `info` | `warning` | `critical`. Drives both UI
+ *                        styling and score penalty weight.
+ *   count              — total number of items in this category. Always
+ *                        equals the *underlying* count, even if
+ *                        `sample_asset_ids` is truncated.
+ *   sample_asset_ids   — bounded sample (caller decides bound; default
+ *                        suggestion is 10) of asset IDs for spot-checks.
+ *   message            — human-readable summary. Treat as display copy,
+ *                        not data — never parse it.
+ */
+export function auditFindingSchema(metaSchema) {
+    return z.object({
+        id: z.string().min(1),
+        category: z.string().min(1),
+        severity: AuditSeveritySchema,
+        count: z.number().int().nonnegative(),
+        sample_asset_ids: z.array(z.string()),
+        message: z.string(),
+        meta: metaSchema.optional(),
+    });
+}
+export const BaseAuditFindingSchema = auditFindingSchema(z.unknown());
+// ── Next-Step Hint ───────────────────────────────────────────────────
+/**
+ * Structured next-step hint pointing at an existing mutating tool.
+ *
+ * Phase 1 only emits `add_tags` / `remove_tags` / `set_tags` actions and
+ * targets `bulk_add_tags` / `bulk_remove_tags` / `bulk_set_tags`. The
+ * `action` enum is intentionally extensible — Phase 1.5 will add
+ * `rename_assets`, `move_assets`, `normalize_filenames` without breaking
+ * the schema (additive only).
+ *
+ * The shape carries the exact argument set the caller would pass to the
+ * mutating tool, so a router can dispatch directly without re-interpreting
+ * the finding.
+ */
+export const AuditNextStepActionSchema = z.enum([
+    'add_tags',
+    'remove_tags',
+    'set_tags',
+]);
+export const AuditNextStepSchema = z.object({
+    action: AuditNextStepActionSchema,
+    /**
+     * Name of the mutating tool that should be invoked to apply this hint.
+     * Stored as a string (not enum) so Phase 1.5 can introduce new tools
+     * without bumping the schema major version.
+     */
+    tool: z.string().min(1),
+    /** Asset IDs the caller should target. Always a non-empty list. */
+    target_asset_ids: z.array(z.string().min(1)).min(1),
+    /** Tags to add / remove / set, when `action` is tag-related. */
+    suggested_tags: z.array(z.string().min(1)).optional(),
+    /** Short rationale linking the hint back to its originating finding. */
+    reason: z.string().min(1),
+    /** ID of the finding this hint addresses (optional but encouraged). */
+    finding_id: z.string().optional(),
+});
+// ── Summary Counts ───────────────────────────────────────────────────
+export const AuditSummaryCountsSchema = z.object({
+    total_assets_scanned: z.number().int().nonnegative(),
+    total_findings: z.number().int().nonnegative(),
+    by_severity: z.object({
+        info: z.number().int().nonnegative(),
+        warning: z.number().int().nonnegative(),
+        critical: z.number().int().nonnegative(),
+    }),
+});
+// ── Report Envelope ──────────────────────────────────────────────────
+/**
+ * Top-level envelope returned by every audit tool.
+ *
+ *   score              — 0–100 (see {@link AuditScoreSchema})
+ *   summary_counts     — quick-glance roll-up
+ *   findings           — every detected issue, structured
+ *   next_steps         — structured fix suggestions pointing at existing
+ *                        mutating tools
+ *   truncated          — true when findings or next_steps were trimmed to
+ *                        stay under the response budget. When true, the
+ *                        report is *partial* and the caller should re-run
+ *                        with a tighter scope or paginated input.
+ *   truncation_reason  — populated when `truncated` is true.
+ */
+export function auditReportSchema(metaSchema) {
+    return z.object({
+        score: AuditScoreSchema,
+        summary_counts: AuditSummaryCountsSchema,
+        findings: z.array(auditFindingSchema(metaSchema)),
+        next_steps: z.array(AuditNextStepSchema),
+        truncated: z.boolean(),
+        truncation_reason: z.string().optional(),
+    });
+}
+export const BaseAuditReportSchema = auditReportSchema(z.unknown());
+// ── Severity weights (shared default) ────────────────────────────────
+/**
+ * Default penalty weights per severity level. Individual audits MAY override
+ * but the shared default keeps cross-audit scores comparable.
+ */
+export const DEFAULT_SEVERITY_WEIGHTS = {
+    info: 1,
+    warning: 5,
+    critical: 15,
+};
+/**
+ * Compute an `AuditScore` from a list of findings using the shared severity
+ * weight table (or a caller-supplied one). The score is `100 - sum(weights)`,
+ * clamped to `[0, 100]`. With no findings the score is 100.
+ *
+ * The formula is intentionally simple, deterministic, and easy to defend:
+ *   - one weight per finding (NOT per affected asset) — keeps a single
+ *     widespread issue from collapsing the score to 0
+ *   - severity drives the weight; counts surface in the finding itself
+ *   - clamped at 0; never negative
+ */
+export function computeAuditScore(findings, weights = DEFAULT_SEVERITY_WEIGHTS) {
+    let penalty = 0;
+    for (const f of findings) {
+        penalty += weights[f.severity];
+    }
+    const raw = 100 - penalty;
+    if (raw < 0)
+        return 0;
+    if (raw > 100)
+        return 100;
+    return Math.trunc(raw);
+}
+/**
+ * Roll up findings into the summary-counts shape.
+ */
+export function summarizeFindings(findings, totalAssetsScanned) {
+    const by_severity = { info: 0, warning: 0, critical: 0 };
+    for (const f of findings) {
+        by_severity[f.severity]++;
+    }
+    return {
+        total_assets_scanned: totalAssetsScanned,
+        total_findings: findings.length,
+        by_severity,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/audit/types.js.map

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

package/dist/tools/bulk-move-assets.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { MutatingTool, type ApplyFn, type MutatingToolDeps, type PlanResult } from '../conventions/dry-run/index.js';
+import type { DryRunPlan } from '../conventions/dry-run/index.js';
+import { type McpToolError } from '../conventions/errors.js';
+export declare const BulkMoveItemSchema: z.ZodObject<{
+    asset_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+    destination_category_id: z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+    /** Optional current folder id for diff display. */
+    current_category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+}, "strip", z.ZodTypeAny, {
+    asset_id: string | number;
+    destination_category_id: string | number | null;
+    current_category_id?: string | number | null | undefined;
+}, {
+    asset_id: string | number;
+    destination_category_id: string | number | null;
+    current_category_id?: string | number | null | undefined;
+}>;
+export type BulkMoveItem = z.infer<typeof BulkMoveItemSchema>;
+export declare const BulkMoveAssetsInputSchema: z.ZodObject<{
+    moves: z.ZodArray<z.ZodObject<{
+        asset_id: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        destination_category_id: z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>;
+        /** Optional current folder id for diff display. */
+        current_category_id: z.ZodOptional<z.ZodNullable<z.ZodUnion<[z.ZodNumber, z.ZodString]>>>;
+    }, "strip", z.ZodTypeAny, {
+        asset_id: string | number;
+        destination_category_id: string | number | null;
+        current_category_id?: string | number | null | undefined;
+    }, {
+        asset_id: string | number;
+        destination_category_id: string | number | null;
+        current_category_id?: string | number | null | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    moves: {
+        asset_id: string | number;
+        destination_category_id: string | number | null;
+        current_category_id?: string | number | null | undefined;
+    }[];
+}, {
+    moves: {
+        asset_id: string | number;
+        destination_category_id: string | number | null;
+        current_category_id?: string | number | null | undefined;
+    }[];
+}>;
+export type BulkMoveAssetsInput = z.infer<typeof BulkMoveAssetsInputSchema>;
+export declare const BULK_MOVE_ASSETS_DESCRIPTION: string;
+export interface BulkMoveItemResult {
+    asset_id: string;
+    destination_category_id: string | null;
+}
+export interface BulkMoveClient {
+    moveAsset(input: {
+        asset_id: string;
+        destination_category_id: string | null;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+export interface BulkMoveAssetsDeps extends MutatingToolDeps<BulkMoveAssetsInput> {
+    client: BulkMoveClient;
+}
+export declare class BulkMoveAssetsTool extends MutatingTool<BulkMoveAssetsInput, BulkMoveItemResult> {
+    readonly name = "bulk_move_assets";
+    protected readonly chunkSize = 50;
+    private readonly client;
+    constructor(deps: BulkMoveAssetsDeps);
+    protected plan(input: BulkMoveAssetsInput): PlanResult;
+    protected apply: ApplyFn<BulkMoveItemResult>;
+}
+export declare function buildBulkMoveAssetsTool(deps: BulkMoveAssetsDeps): BulkMoveAssetsTool;
+export type BulkMoveAssetsPlan = DryRunPlan<BulkMoveAssetsInput>;
+//# sourceMappingURL=bulk-move-assets.d.ts.map

package/dist/tools/bulk-move-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-move-assets.d.ts","sourceRoot":"","sources":["../../src/tools/bulk-move-assets.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAK9E,eAAO,MAAM,kBAAkB;;;IAG7B,mDAAmD;;;;;;;;;;EAEnD,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,yBAAyB;;;;QALpC,mDAAmD;;;;;;;;;;;;;;;;;;;;;;;EAOnD,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,4BAA4B,QAIyB,CAAC;AAInE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAID,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,KAAK,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;KACxC,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CAChE;AAID,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB,CAAC,mBAAmB,CAAC;IAC/E,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,qBAAa,kBAAmB,SAAQ,YAAY,CAClD,mBAAmB,EACnB,kBAAkB,CACnB;IACC,QAAQ,CAAC,IAAI,sBAAsB;IACnC,mBAA4B,SAAS,MAAM;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,IAAI,EAAE,kBAAkB;IAKpC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,UAAU;IA+DtD,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAwB1C;CACH;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,kBAAkB,GACvB,kBAAkB,CAEpB;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC"}

package/dist/tools/bulk-move-assets.js

@@ -0,0 +1,122 @@
+// ── bulk_move_assets (T7, Phase 1.5) ─────────────────────────────────
+//
+// Mutating tool. Moves many assets to a destination folder in a single
+// confirmed call. Built on the shared `MutatingTool` base.
+//
+// Input shape:
+//   { moves: [{ asset_id, destination_category_id, current_category_id? }] }
+//
+// `destination_category_id: null` moves the asset to the workspace root
+// (uncategorised) — same semantic as `move_asset`. We allow per-item
+// destinations because a common bulk-move case is "re-home a batch of
+// orphaned assets into their correct folders" rather than "shove
+// everything into one folder".
+//
+// Risk flags emitted in the plan phase:
+//   - `noop_move`     (info)     — destination matches the current folder
+//   - `empty_input`   (warning)  — zero moves in input
+import { z } from 'zod';
+import { MutatingTool, } from '../conventions/dry-run/index.js';
+import { createToolError } from '../conventions/errors.js';
+import { IdSchema } from '../types.js';
+// ── Input ────────────────────────────────────────────────────────────
+export const BulkMoveItemSchema = z.object({
+    asset_id: IdSchema,
+    destination_category_id: IdSchema.nullable(),
+    /** Optional current folder id for diff display. */
+    current_category_id: IdSchema.nullable().optional(),
+});
+export const BulkMoveAssetsInputSchema = z.object({
+    moves: z.array(BulkMoveItemSchema).min(1).max(1000),
+});
+export const BULK_MOVE_ASSETS_DESCRIPTION = 'Move many Collage assets to destination folders in a single confirmed ' +
+    'call. Each entry is `{ asset_id, destination_category_id, ' +
+    'current_category_id? }`. Pass `destination_category_id: null` to move ' +
+    'an asset to the workspace root. Two-step preview/confirm flow.';
+export class BulkMoveAssetsTool extends MutatingTool {
+    name = 'bulk_move_assets';
+    chunkSize = 50;
+    client;
+    constructor(deps) {
+        super(deps);
+        this.client = deps.client;
+    }
+    plan(input) {
+        const changes = [];
+        let noopCount = 0;
+        for (const item of input.moves) {
+            const id = String(item.asset_id);
+            const dest = item.destination_category_id === null
+                ? null
+                : String(item.destination_category_id);
+            const before = item.current_category_id === undefined
+                ? '(unknown)'
+                : item.current_category_id === null
+                    ? null
+                    : String(item.current_category_id);
+            if (item.current_category_id !== undefined &&
+                item.current_category_id !== null &&
+                String(item.current_category_id) === dest) {
+                noopCount++;
+            }
+            else if (item.current_category_id !== undefined &&
+                item.current_category_id === null &&
+                dest === null) {
+                noopCount++;
+            }
+            changes.push({
+                id,
+                operation: 'update',
+                before: { category_id: before },
+                after: { category_id: dest },
+                metadata: { asset_id: id, destination_category_id: dest },
+            });
+        }
+        const riskFlags = [];
+        if (input.moves.length === 0) {
+            riskFlags.push({
+                code: 'empty_input',
+                severity: 'warning',
+                message: 'bulk_move_assets received zero move entries',
+                count: 0,
+            });
+        }
+        if (noopCount > 0) {
+            riskFlags.push({
+                code: 'noop_move',
+                severity: 'info',
+                message: 'destination is the asset\'s current folder (no-op)',
+                count: noopCount,
+            });
+        }
+        return {
+            changes,
+            riskFlags,
+            extraAggregates: { moves: input.moves.length, noops: noopCount },
+        };
+    }
+    apply = async (change) => {
+        const meta = (change.metadata ?? {});
+        if (typeof meta.asset_id !== 'string' || meta.asset_id.length === 0) {
+            return {
+                ok: false,
+                error: createToolError('VALIDATION', `change ${change.id} missing asset_id`),
+            };
+        }
+        const dest = meta.destination_category_id ?? null;
+        const result = await this.client.moveAsset({
+            asset_id: meta.asset_id,
+            destination_category_id: dest,
+        });
+        if (!result.ok)
+            return { ok: false, error: result.error };
+        return {
+            ok: true,
+            result: { asset_id: meta.asset_id, destination_category_id: dest },
+        };
+    };
+}
+export function buildBulkMoveAssetsTool(deps) {
+    return new BulkMoveAssetsTool(deps);
+}
+//# sourceMappingURL=bulk-move-assets.js.map

package/dist/tools/bulk-move-assets.js.map

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

package/dist/tools/bulk-normalize-filenames.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { MutatingTool, type ApplyFn, type MutatingToolDeps, type PlanResult } from '../conventions/dry-run/index.js';
+import type { DryRunPlan } from '../conventions/dry-run/index.js';
+import { type McpToolError } from '../conventions/errors.js';
+export declare const NormalizeStyleSchema: z.ZodEnum<["kebab-case", "snake_case", "lowercase", "no_spaces", "PascalCase", "camelCase"]>;
+export type NormalizeStyle = z.infer<typeof NormalizeStyleSchema>;
+export declare const BulkNormalizeFilenamesInputSchema: z.ZodObject<{
+    asset_ids: z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodString]>, "many">;
+    style: z.ZodEnum<["kebab-case", "snake_case", "lowercase", "no_spaces", "PascalCase", "camelCase"]>;
+}, "strip", z.ZodTypeAny, {
+    asset_ids: (string | number)[];
+    style: "kebab-case" | "snake_case" | "camelCase" | "PascalCase" | "lowercase" | "no_spaces";
+}, {
+    asset_ids: (string | number)[];
+    style: "kebab-case" | "snake_case" | "camelCase" | "PascalCase" | "lowercase" | "no_spaces";
+}>;
+export type BulkNormalizeFilenamesInput = z.infer<typeof BulkNormalizeFilenamesInputSchema>;
+export declare const BULK_NORMALIZE_FILENAMES_DESCRIPTION: string;
+export interface BulkNormalizeItemResult {
+    asset_id: string;
+    before_name: string;
+    after_name: string;
+}
+export interface BulkNormalizeClient {
+    /** Read the current display_file_name. Null if unavailable. */
+    getCurrentName(assetId: string): Promise<string | null>;
+    /** Apply the rename. */
+    renameAsset(assetId: string, newName: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: McpToolError;
+    }>;
+}
+export interface BulkNormalizeFilenamesDeps extends MutatingToolDeps<BulkNormalizeFilenamesInput> {
+    client: BulkNormalizeClient;
+}
+export declare class BulkNormalizeFilenamesTool extends MutatingTool<BulkNormalizeFilenamesInput, BulkNormalizeItemResult> {
+    readonly name = "bulk_normalize_filenames";
+    protected readonly chunkSize = 50;
+    private readonly client;
+    constructor(deps: BulkNormalizeFilenamesDeps);
+    protected plan(input: BulkNormalizeFilenamesInput): Promise<PlanResult>;
+    protected apply: ApplyFn<BulkNormalizeItemResult>;
+}
+export declare function buildBulkNormalizeFilenamesTool(deps: BulkNormalizeFilenamesDeps): BulkNormalizeFilenamesTool;
+export type BulkNormalizeFilenamesPlan = DryRunPlan<BulkNormalizeFilenamesInput>;
+interface StripResult {
+    stem: string;
+    extension: string;
+}
+export declare function stripExtension(name: string): StripResult;
+/**
+ * Normalise a single filename. Pure function; the file extension (the
+ * portion after the final `.`) is preserved verbatim, only the stem is
+ * normalised. If the resulting stem would be empty, the original name is
+ * returned unchanged (a `would_clear_name` flag is surfaced by the plan
+ * phase so the caller is informed).
+ */
+export declare function normalizeFilename(name: string, style: NormalizeStyle): string;
+export {};
+//# sourceMappingURL=bulk-normalize-filenames.d.ts.map

package/dist/tools/bulk-normalize-filenames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-normalize-filenames.d.ts","sourceRoot":"","sources":["../../src/tools/bulk-normalize-filenames.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAK9E,eAAO,MAAM,oBAAoB,8FAO/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,iCAAiC;;;;;;;;;EAG5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AAEF,eAAO,MAAM,oCAAoC,QAIK,CAAC;AAIvD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,wBAAwB;IACxB,WAAW,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CAC/D;AAID,MAAM,WAAW,0BACf,SAAQ,gBAAgB,CAAC,2BAA2B,CAAC;IACrD,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,qBAAa,0BAA2B,SAAQ,YAAY,CAC1D,2BAA2B,EAC3B,uBAAuB,CACxB;IACC,QAAQ,CAAC,IAAI,8BAA8B;IAC3C,mBAA4B,SAAS,MAAM;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAEjC,IAAI,EAAE,0BAA0B;cAK5B,IAAI,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,UAAU,CAAC;IA0F7E,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CA6B/C;CACH;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,0BAA0B,GAC/B,0BAA0B,CAE5B;AAED,MAAM,MAAM,0BAA0B,GAAG,UAAU,CAAC,2BAA2B,CAAC,CAAC;AAIjF,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAIxD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAiC7E"}