@forumone/throughline 0.0.0 → 1.0.0-next.0

package/dist/audit/jobs/audit-event-echo.js

@@ -0,0 +1,61 @@
+import { failureOptions } from '../../jobs/workflow-types.js';
+import { defineJob } from '../../jobs/define.js';
+const APPROVAL_DECISION_ACTIONS = new Set([
+    'approval.granted',
+    'approval.declined',
+    'approval.changes_requested',
+]);
+/**
+ * Subscribes to `audit/event.recorded` and fans out to notification
+ * workflows. The built-in handlers cover the approval lifecycle (which
+ * the email package in C11 subscribes to); custom handlers in
+ * `options.handlers` add other fan-outs (e.g. "post integration.failed
+ * to a #alerts Slack channel").
+ *
+ * Each handler runs in its own `step.run` so a failure in one fan-out
+ * does not affect the others.
+ */
+export function auditEventEchoJob(options) {
+    return defineJob({
+        id: options.id ?? 'audit-event-echo',
+        /*
+        No default cap. One audit row is one event, and the echo only fans it out
+        to notification events — so runs are independent by construction and
+        serialising them would put a queue in front of every audited write.
+        */
+        ...failureOptions(options),
+        on: { event: 'audit/event.recorded' },
+    }, async ({ event, step, logger, emit }) => {
+        const data = (event.data ?? {});
+        logger.info('Audit event echoed', { action: data.action });
+        await step.run('handle-approval-requested', async () => {
+            if (data.action === 'approval.requested' && data.approvalRequestId) {
+                await emit({
+                    name: 'notification/send-approval-request',
+                    data: { approvalId: data.approvalRequestId },
+                });
+            }
+        });
+        await step.run('handle-approval-decided', async () => {
+            if (APPROVAL_DECISION_ACTIONS.has(data.action) && data.approvalRequestId) {
+                await emit({
+                    name: 'notification/send-approval-decision',
+                    data: { approvalId: data.approvalRequestId, decision: data.action },
+                });
+            }
+        });
+        const handlers = options.handlers ?? [];
+        for (let index = 0; index < handlers.length; index += 1) {
+            const handler = handlers[index];
+            await step.run(`custom-handler-${index}`, async () => {
+                if (handler.match({ action: data.action })) {
+                    await handler.handle({
+                        action: data.action,
+                        data: data,
+                    });
+                }
+            });
+        }
+    });
+}
+//# sourceMappingURL=audit-event-echo.js.map

package/dist/audit/jobs/audit-event-echo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-event-echo.js","sourceRoot":"","sources":["../../../src/audit/jobs/audit-event-echo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAahD,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;IACxC,kBAAkB;IAClB,mBAAmB;IACnB,4BAA4B;CAC7B,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA8B;IAC9D,OAAO,SAAS,CACd;QACE,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,kBAAkB;QACpC;;;;UAIE;QACF,GAAG,cAAc,CAAC,OAAO,CAAC;QAC1B,EAAE,EAAE,EAAE,KAAK,EAAE,sBAAsB,EAAE;KACtC,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE;QACtC,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAsB,CAAA;QACpD,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;QAE1D,MAAM,IAAI,CAAC,GAAG,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;YACrD,IAAI,IAAI,CAAC,MAAM,KAAK,oBAAoB,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACnE,MAAM,IAAI,CAAC;oBACT,IAAI,EAAE,oCAAoC;oBAC1C,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE;iBAC7C,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,MAAM,IAAI,CAAC,GAAG,CAAC,yBAAyB,EAAE,KAAK,IAAI,EAAE;YACnD,IAAI,yBAAyB,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACzE,MAAM,IAAI,CAAC;oBACT,IAAI,EAAE,qCAAqC;oBAC3C,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;iBACpE,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAA;QACvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACxD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAE,CAAA;YAChC,MAAM,IAAI,CAAC,GAAG,CAAC,kBAAkB,KAAK,EAAE,EAAE,KAAK,IAAI,EAAE;gBACnD,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;oBAC3C,MAAM,OAAO,CAAC,MAAM,CAAC;wBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;wBACnB,IAAI,EAAE,IAA0C;qBACjD,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/audit/plugin.d.ts

@@ -0,0 +1,20 @@
+import type { Inngest } from 'inngest';
+import { type BaseCorePluginOptions, type CorePlugin } from '../plugin-contract/index.js';
+import { type AuditCollectionOptions } from './collection.js';
+import { type AuditWriter } from './writer.js';
+export interface AuditPluginOptions extends BaseCorePluginOptions, AuditCollectionOptions {
+    /**
+     * Inngest client used to fire `audit/event.recorded` events. If omitted,
+     * audit writes still persist; downstream subscribers simply won't receive
+     * events.
+     */
+    inngest?: Inngest;
+}
+export declare const auditPlugin: CorePlugin<AuditPluginOptions>;
+/**
+ * Retrieves the audit writer attached to a Payload instance by `auditPlugin`.
+ * Plugins that depend on auditing call this in their own `onInit` to record
+ * events without importing this package's writer factory directly.
+ */
+export declare function getAuditWriter(payload: object): AuditWriter;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/audit/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/audit/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAEhB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAyB,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACpF,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAOjE,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB,EAAE,sBAAsB;IACvF;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,kBAAkB,CA8BtD,CAAA;AAWD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAQ3D"}

package/dist/audit/plugin.js

@@ -0,0 +1,55 @@
+import { getPluginRegistry, } from '../plugin-contract/index.js';
+import { createAuditCollection } from './collection.js';
+import { createAuditWriter } from './writer.js';
+import { defaultLogger } from '../logger/index.js';
+const AUDIT_PLUGIN_ID = '@forumone/throughline/audit';
+const AUDIT_PLUGIN_VERSION = '0.1.0';
+const AUDIT_WRITER_SYMBOL = Symbol.for('@forumone/throughline/audit-writer');
+export const auditPlugin = (options) => (incomingConfig) => {
+    if (options.enabled === false)
+        return incomingConfig;
+    const auditCollection = createAuditCollection(options);
+    return {
+        ...incomingConfig,
+        collections: [...(incomingConfig.collections ?? []), auditCollection],
+        onInit: async (payload) => {
+            if (incomingConfig.onInit) {
+                await incomingConfig.onInit(payload);
+            }
+            const writer = createAuditWriter({
+                payload,
+                inngest: options.inngest,
+                collectionSlug: options.slug,
+                logger: options.logger ?? defaultLogger,
+            });
+            attachAuditWriter(payload, writer);
+            const registry = getPluginRegistry(payload);
+            registry.register({
+                id: AUDIT_PLUGIN_ID,
+                version: AUDIT_PLUGIN_VERSION,
+                capabilities: ['audit-log', 'audit-write'],
+            });
+        },
+    };
+};
+function attachAuditWriter(target, writer) {
+    Object.defineProperty(target, AUDIT_WRITER_SYMBOL, {
+        value: writer,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+}
+/**
+ * Retrieves the audit writer attached to a Payload instance by `auditPlugin`.
+ * Plugins that depend on auditing call this in their own `onInit` to record
+ * events without importing this package's writer factory directly.
+ */
+export function getAuditWriter(payload) {
+    const writer = payload[AUDIT_WRITER_SYMBOL];
+    if (!writer) {
+        throw new Error('Audit writer not found. Ensure `auditPlugin` is registered in your Payload config before any plugin that depends on it.');
+    }
+    return writer;
+}
+//# sourceMappingURL=plugin.js.map

package/dist/audit/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/audit/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,iBAAiB,GAClB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,qBAAqB,EAA+B,MAAM,iBAAiB,CAAA;AACpF,OAAO,EAAE,iBAAiB,EAAoB,MAAM,aAAa,CAAA;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,MAAM,eAAe,GAAG,6BAA6B,CAAA;AACrD,MAAM,oBAAoB,GAAG,OAAO,CAAA;AACpC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAA;AAW5E,MAAM,CAAC,MAAM,WAAW,GAAmC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE,EAAE;IACzF,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,cAAc,CAAA;IAEpD,MAAM,eAAe,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;IAEtD,OAAO;QACL,GAAG,cAAc;QACjB,WAAW,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,eAAe,CAAC;QACrE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACxB,IAAI,cAAc,CAAC,MAAM,EAAE,CAAC;gBAC1B,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YACtC,CAAC;YAED,MAAM,MAAM,GAAG,iBAAiB,CAAC;gBAC/B,OAAO;gBACP,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,cAAc,EAAE,OAAO,CAAC,IAAI;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,aAAa;aACxC,CAAC,CAAA;YAEF,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YAElC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;YAC3C,QAAQ,CAAC,QAAQ,CAAC;gBAChB,EAAE,EAAE,eAAe;gBACnB,OAAO,EAAE,oBAAoB;gBAC7B,YAAY,EAAE,CAAC,WAAW,EAAE,aAAa,CAAC;aAC3C,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,SAAS,iBAAiB,CAAC,MAAc,EAAE,MAAmB;IAC5D,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE;QACjD,KAAK,EAAE,MAAM;QACb,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACpB,CAAC,CAAA;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,MAAM,GAAI,OAAmC,CAAC,mBAAmB,CAAC,CAAA;IACxE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,yHAAyH,CAC1H,CAAA;IACH,CAAC;IACD,OAAO,MAAqB,CAAA;AAC9B,CAAC"}

package/dist/audit/query/formatting/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Conversational-output helpers for audit records. The query tools return
+ * objects shaped via `formatAuditEvent` so Claude can relay them to users
+ * without reformatting raw collection JSON.
+ */
+export interface FormattedAuditEvent {
+    when: string;
+    whenIso: string;
+    who: string;
+    what: string;
+    why?: string;
+    prompt?: string;
+    changesSummary?: string;
+    diff?: Record<string, {
+        before: unknown;
+        after: unknown;
+    }>;
+    success: boolean;
+    errorMessage?: string;
+    action: string;
+    mcpServer: string;
+    mcpTool: string;
+    targetCollection?: string;
+    targetId?: string;
+    targetTitle?: string;
+}
+/**
+ * Formats an ISO timestamp as a relative time string. Crude but
+ * conversational: "just now", "5 minutes ago", "3 hours ago", "2 days ago",
+ * or an `YYYY-MM-DD` for anything older than a week.
+ */
+export declare function formatRelativeTime(iso: string, now?: number): string;
+/**
+ * Maps a raw audit-collection record to the conversational shape the query
+ * tools return. Internal-only fields (`consumedTokens`, `notifiedApprovers`)
+ * are dropped; ISO timestamps are kept alongside the relative form so the
+ * caller can sort or render at their preference.
+ */
+export declare function formatAuditEvent(raw: Record<string, unknown>, now?: number): FormattedAuditEvent;
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/query/formatting/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/audit/query/formatting/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC1D,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,MAAM,CAcxE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,SAAa,GACf,mBAAmB,CAgCrB"}

package/dist/audit/query/formatting/index.js

@@ -0,0 +1,73 @@
+/**
+ * Conversational-output helpers for audit records. The query tools return
+ * objects shaped via `formatAuditEvent` so Claude can relay them to users
+ * without reformatting raw collection JSON.
+ */
+const DAY_IN_MS = 24 * 60 * 60 * 1000;
+/**
+ * Formats an ISO timestamp as a relative time string. Crude but
+ * conversational: "just now", "5 minutes ago", "3 hours ago", "2 days ago",
+ * or an `YYYY-MM-DD` for anything older than a week.
+ */
+export function formatRelativeTime(iso, now = Date.now()) {
+    const then = new Date(iso).getTime();
+    if (Number.isNaN(then))
+        return iso;
+    const diffMs = Math.max(0, now - then);
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (seconds < 60)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    if (diffMs < 7 * DAY_IN_MS)
+        return `${days} day${days === 1 ? '' : 's'} ago`;
+    return iso.slice(0, 10);
+}
+/**
+ * Maps a raw audit-collection record to the conversational shape the query
+ * tools return. Internal-only fields (`consumedTokens`, `notifiedApprovers`)
+ * are dropped; ISO timestamps are kept alongside the relative form so the
+ * caller can sort or render at their preference.
+ */
+export function formatAuditEvent(raw, now = Date.now()) {
+    const actor = (raw['actor'] ?? {});
+    const userName = typeof actor['userName'] === 'string' ? actor['userName'] : null;
+    const apiKeyName = typeof actor['apiKeyName'] === 'string' ? actor['apiKeyName'] : null;
+    const actorType = typeof actor['type'] === 'string' ? actor['type'] : 'unknown';
+    const who = userName ?? apiKeyName ?? (actorType === 'system' ? 'system' : 'unknown');
+    const createdAt = typeof raw['createdAt'] === 'string' ? raw['createdAt'] : '';
+    const formatted = {
+        when: createdAt ? formatRelativeTime(createdAt, now) : 'unknown',
+        whenIso: createdAt,
+        who,
+        what: typeof raw['summary'] === 'string' ? raw['summary'] : String(raw['action'] ?? ''),
+        success: raw['success'] !== false,
+        action: typeof raw['action'] === 'string' ? raw['action'] : 'unknown',
+        mcpServer: typeof raw['mcpServer'] === 'string' ? raw['mcpServer'] : 'unknown',
+        mcpTool: typeof raw['mcpTool'] === 'string' ? raw['mcpTool'] : 'unknown',
+    };
+    if (typeof raw['reasoning'] === 'string')
+        formatted.why = raw['reasoning'];
+    if (typeof raw['prompt'] === 'string')
+        formatted.prompt = raw['prompt'];
+    if (typeof raw['changesSummary'] === 'string')
+        formatted.changesSummary = raw['changesSummary'];
+    if (raw['diff'] && typeof raw['diff'] === 'object') {
+        formatted.diff = raw['diff'];
+    }
+    if (typeof raw['errorMessage'] === 'string')
+        formatted.errorMessage = raw['errorMessage'];
+    if (typeof raw['targetCollection'] === 'string')
+        formatted.targetCollection = raw['targetCollection'];
+    if (typeof raw['targetId'] === 'string')
+        formatted.targetId = raw['targetId'];
+    if (typeof raw['targetTitle'] === 'string')
+        formatted.targetTitle = raw['targetTitle'];
+    return formatted;
+}
+//# sourceMappingURL=index.js.map

package/dist/audit/query/formatting/index.js.map

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

package/dist/audit/query/options.d.ts

@@ -0,0 +1,34 @@
+import type { McpToolCollector } from '../../mcp/collector.js';
+import type { PayloadRequest } from 'payload';
+import type { BaseCorePluginOptions } from '../../plugin-contract/index.js';
+export interface AuditQueryPluginOptions extends Omit<BaseCorePluginOptions, 'routePrefix'> {
+    /**
+     * Override the audit collection slug. Must match the slug `auditPlugin`
+     * (in `@forumone/throughline/audit`) writes to. Default: `'audit-events'`.
+     */
+    collectionSlug?: string;
+    /**
+     * Custom access-control function for read operations. Returns true to
+     * allow reads. Defaults to admin and editor roles.
+     */
+    readAccess?: (req: PayloadRequest) => boolean;
+    /**
+     * Where to put this server's MCP tools so Payload's own MCP plugin can serve
+     * them.
+     *
+     * `createMcpToolCollector()` from `@forumone/throughline`. The host hands
+     * its array to `@payloadcms/plugin-mcp` at config time and this plugin fills
+     * it at `onInit` — which is the first moment the tools can exist, since they
+     * close over `payload`, and still before any request reads the array.
+     *
+     * Omit it and nothing changes: this server keeps its own `/mcp` endpoint,
+     * which is what lets a host move one server at a time.
+     */
+    mcpTools?: McpToolCollector;
+}
+/**
+ * Validates options at load time. Currently a passthrough; reserved for
+ * future option-shape additions so callers always go through the same gate.
+ */
+export declare function validateOptions(options: AuditQueryPluginOptions): AuditQueryPluginOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/audit/query/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/audit/query/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AAQ3E,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,qBAAqB,EAAE,aAAa,CAAC;IACzF;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAA;IAE7C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC5B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAEzF"}

package/dist/audit/query/options.js

@@ -0,0 +1,8 @@
+/**
+ * Validates options at load time. Currently a passthrough; reserved for
+ * future option-shape additions so callers always go through the same gate.
+ */
+export function validateOptions(options) {
+    return options;
+}
+//# sourceMappingURL=options.js.map

package/dist/audit/query/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/audit/query/options.ts"],"names":[],"mappings":"AAqCA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgC;IAC9D,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/audit/query/plugin.d.ts

@@ -0,0 +1,11 @@
+import type { CorePlugin } from '../../plugin-contract/index.js';
+import { type AuditQueryPluginOptions } from './options.js';
+/**
+ * Read-only MCP server over the audit log. Pairs with `auditPlugin` from
+ * `@forumone/throughline/audit` (which writes records). The query plugin
+ * requires the `audit-log` capability and refuses to initialize without it.
+ *
+ * Exported as `auditQueryPlugin` to disambiguate from core's `auditPlugin`.
+ */
+export declare const auditQueryPlugin: CorePlugin<AuditQueryPluginOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/audit/query/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/audit/query/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAMhE,OAAO,EAAE,KAAK,uBAAuB,EAAmB,MAAM,cAAc,CAAA;AAY5E;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAU,CAAC,uBAAuB,CA0D9D,CAAA"}

package/dist/audit/query/plugin.js

@@ -0,0 +1,68 @@
+import { getPluginRegistry } from '../../plugin-contract/registry.js';
+import { createNamedLogger, defaultLogger } from '../../logger/index.js';
+import { getAuditWriter } from '../plugin.js';
+import { DEFAULT_AUDIT_SLUG } from '../collection.js';
+import { validateOptions } from './options.js';
+import { AUDIT_TOOL_DESCRIPTORS, createGetChangeHistoryTool, createGetRecentFailuresTool, createQueryAuditTool, createWhatChangedInRangeTool, createWhoChangedWhatTool, } from './tools/index.js';
+const PLUGIN_ID = '@forumone/throughline/audit-query';
+const PLUGIN_VERSION = '0.1.0';
+/**
+ * Read-only MCP server over the audit log. Pairs with `auditPlugin` from
+ * `@forumone/throughline/audit` (which writes records). The query plugin
+ * requires the `audit-log` capability and refuses to initialize without it.
+ *
+ * Exported as `auditQueryPlugin` to disambiguate from core's `auditPlugin`.
+ */
+export const auditQueryPlugin = (rawOptions) => (incomingConfig) => {
+    if (rawOptions.enabled === false)
+        return incomingConfig;
+    const options = validateOptions(rawOptions);
+    const collectionSlug = options.collectionSlug ?? DEFAULT_AUDIT_SLUG;
+    const logger = createNamedLogger('audit-query', options.logger ?? defaultLogger);
+    /*
+    Declared here, bound at `onInit` — `mcpPlugin` generates its per-key
+    checkboxes from these names and descriptions while the config is built, and
+    denies any tool it has no checkbox for. This plugin must therefore come
+    before `mcpPlugin` in the host's array.
+    */
+    options.mcpTools?.declare(AUDIT_TOOL_DESCRIPTORS, { serverName: 'audit' });
+    return {
+        ...incomingConfig,
+        onInit: async (payload) => {
+            if (incomingConfig.onInit)
+                await incomingConfig.onInit(payload);
+            const registry = getPluginRegistry(payload);
+            registry.requireCapability('audit-log', PLUGIN_ID);
+            /*
+            The audit server audits its own crashes. That reads circular and is
+            not: these five tools only read, so a `system.error` row from one of
+            them records that reading the log failed — which is precisely the
+            outage you would otherwise have no record of, because the place you
+            would look is the thing that broke.
+            */
+            const auditWriter = getAuditWriter(payload);
+            const deps = { payload, collectionSlug };
+            const tools = [
+                createQueryAuditTool(deps),
+                createGetChangeHistoryTool(deps),
+                createWhoChangedWhatTool(deps),
+                createWhatChangedInRangeTool(deps),
+                createGetRecentFailuresTool(deps),
+            ];
+            // Payload's own MCP plugin, and the only transport these tools have.
+            // `onInit` is both the earliest they can exist and still early enough
+            // that `mcpPlugin` reads the array populated.
+            options.mcpTools?.add(tools, { serverName: 'audit', logger, audit: auditWriter });
+            registry.register({
+                id: PLUGIN_ID,
+                version: PLUGIN_VERSION,
+                capabilities: ['audit-query'],
+            });
+            logger.info('Audit query server ready', {
+                collectionSlug,
+                toolCount: tools.length,
+            });
+        },
+    };
+};
+//# sourceMappingURL=plugin.js.map

package/dist/audit/query/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/audit/query/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AACrE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,EAAgC,eAAe,EAAE,MAAM,cAAc,CAAA;AAC5E,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,kBAAkB,CAAA;AAEzB,MAAM,SAAS,GAAG,mCAAmC,CAAA;AACrD,MAAM,cAAc,GAAG,OAAO,CAAA;AAC9B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE,EAAE;IACjC,IAAI,UAAU,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,cAAc,CAAA;IAEvD,MAAM,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,CAAA;IAC3C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,kBAAkB,CAAA;IACnE,MAAM,MAAM,GAAG,iBAAiB,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC,CAAA;IAEhF;;;;;MAKE;IACF,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,sBAAsB,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAA;IAE1E,OAAO;QACL,GAAG,cAAc;QACjB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACxB,IAAI,cAAc,CAAC,MAAM;gBAAE,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YAE/D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;YAC3C,QAAQ,CAAC,iBAAiB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;YAElD;;;;;;cAME;YACF,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;YAC3C,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,CAAA;YACxC,MAAM,KAAK,GAAG;gBACZ,oBAAoB,CAAC,IAAI,CAAC;gBAC1B,0BAA0B,CAAC,IAAI,CAAC;gBAChC,wBAAwB,CAAC,IAAI,CAAC;gBAC9B,4BAA4B,CAAC,IAAI,CAAC;gBAClC,2BAA2B,CAAC,IAAI,CAAC;aACA,CAAA;YAEnC,qEAAqE;YACrE,sEAAsE;YACtE,8CAA8C;YAC9C,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAA;YAEjF,QAAQ,CAAC,QAAQ,CAAC;gBAChB,EAAE,EAAE,SAAS;gBACb,OAAO,EAAE,cAAc;gBACvB,YAAY,EAAE,CAAC,aAAa,CAAC;aAC9B,CAAC,CAAA;YAEF,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE;gBACtC,cAAc;gBACd,SAAS,EAAE,KAAK,CAAC,MAAM;aACxB,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/audit/query/tools/access.d.ts

@@ -0,0 +1,9 @@
+import type { McpToolContext } from '../../../plugin-contract/mcp.js';
+/**
+ * Default read-access predicate. Admins and editors can read everything;
+ * anyone else is treated as scoped to their own actions and gets a
+ * "permission-denied" envelope from broad-scope tools.
+ */
+export declare function isAuditReader(ctx: McpToolContext): boolean;
+export { deniedEnvelope } from '../../../mcp/envelope.js';
+//# sourceMappingURL=access.d.ts.map

package/dist/audit/query/tools/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../../../src/audit/query/tools/access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAI1D;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/audit/query/tools/access.js

@@ -0,0 +1,14 @@
+/**
+ * Default read-access predicate. Admins and editors can read everything;
+ * anyone else is treated as scoped to their own actions and gets a
+ * "permission-denied" envelope from broad-scope tools.
+ */
+export function isAuditReader(ctx) {
+    if (!ctx.user)
+        return false;
+    const roles = ctx.user.roles;
+    return roles.includes('admin') || roles.includes('editor');
+}
+// `deniedEnvelope` lives in core: three servers had identical copies.
+export { deniedEnvelope } from '../../../mcp/envelope.js';
+//# sourceMappingURL=access.js.map

package/dist/audit/query/tools/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../../../../src/audit/query/tools/access.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,GAAmB;IAC/C,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,KAAK,CAAA;IAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAA;IAC5B,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;AAC5D,CAAC;AAED,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/audit/query/tools/descriptors.d.ts

@@ -0,0 +1,26 @@
+import type { McpToolDescriptor } from '../../../mcp/collector.js';
+export declare const AUDIT_TOOLS: {
+    readonly queryAudit: {
+        readonly name: "query_audit";
+        readonly description: "General-purpose audit log query. Filter by collection, document, actor, action, server, date range, or failure-only. Returns chronologically ordered results, most recent first. Use when you need a custom view of system activity that doesn't fit the more specific tools.";
+    };
+    readonly getChangeHistory: {
+        readonly name: "get_change_history";
+        readonly description: "Returns the complete chronological history of actions on a single document, including diffs. Use to answer \"what has happened to this page?\" or \"who changed X?\". Most-recent first.";
+    };
+    readonly whoChangedWhat: {
+        readonly name: "who_changed_what";
+        readonly description: "A user's recent activity. Use when someone asks 'what has Sarah been working on?' or 'show me my changes today'. If actorId is omitted, defaults to the authenticated caller — so users can ask about themselves without knowing their ID. Other users' activity requires admin/editor.";
+    };
+    readonly whatChangedInRange: {
+        readonly name: "what_changed_in_range";
+        readonly description: "Summarized activity over a time range, grouped by action type, actor, and target collection. Use for \"what happened last week?\" or weekly review questions. Returns counts and top contributors rather than individual events. Caps the scan at 1000 events by default — for wider sweeps, raise scanLimit or use query_audit with paging.";
+    };
+    readonly getRecentFailures: {
+        readonly name: "get_recent_failures";
+        readonly description: "Recent failed operations across all MCP servers. Use for \"what broke recently?\" or when diagnosing issues. Returns actions with success=false and their error messages, most recent first.";
+    };
+};
+/** Every tool this server contributes, for the collector. */
+export declare const AUDIT_TOOL_DESCRIPTORS: readonly McpToolDescriptor[];
+//# sourceMappingURL=descriptors.d.ts.map

package/dist/audit/query/tools/descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.d.ts","sourceRoot":"","sources":["../../../../src/audit/query/tools/descriptors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAYlE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;CA0B8B,CAAA;AAEtD,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,EAAE,SAAS,iBAAiB,EAA+B,CAAA"}

package/dist/audit/query/tools/descriptors.js

@@ -0,0 +1,35 @@
+/*
+This server's tools, by name and description, knowable without a Payload.
+
+`@payloadcms/plugin-mcp` reads exactly these two fields while the host's config
+is being built, to generate one per-key checkbox per tool, and denies any tool it
+has no checkbox for. The handlers close over `payload`, so they cannot exist that
+early — the names never needed to wait for them.
+
+The factories below spread these, so the two cannot drift.
+*/
+export const AUDIT_TOOLS = {
+    queryAudit: {
+        name: 'query_audit',
+        description: "General-purpose audit log query. Filter by collection, document, actor, action, server, date range, or failure-only. Returns chronologically ordered results, most recent first. Use when you need a custom view of system activity that doesn't fit the more specific tools.",
+    },
+    getChangeHistory: {
+        name: 'get_change_history',
+        description: 'Returns the complete chronological history of actions on a single document, including diffs. Use to answer "what has happened to this page?" or "who changed X?". Most-recent first.',
+    },
+    whoChangedWhat: {
+        name: 'who_changed_what',
+        description: "A user's recent activity. Use when someone asks 'what has Sarah been working on?' or 'show me my changes today'. If actorId is omitted, defaults to the authenticated caller — so users can ask about themselves without knowing their ID. Other users' activity requires admin/editor.",
+    },
+    whatChangedInRange: {
+        name: 'what_changed_in_range',
+        description: 'Summarized activity over a time range, grouped by action type, actor, and target collection. Use for "what happened last week?" or weekly review questions. Returns counts and top contributors rather than individual events. Caps the scan at 1000 events by default — for wider sweeps, raise scanLimit or use query_audit with paging.',
+    },
+    getRecentFailures: {
+        name: 'get_recent_failures',
+        description: 'Recent failed operations across all MCP servers. Use for "what broke recently?" or when diagnosing issues. Returns actions with success=false and their error messages, most recent first.',
+    },
+};
+/** Every tool this server contributes, for the collector. */
+export const AUDIT_TOOL_DESCRIPTORS = Object.values(AUDIT_TOOLS);
+//# sourceMappingURL=descriptors.js.map

package/dist/audit/query/tools/descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.js","sourceRoot":"","sources":["../../../../src/audit/query/tools/descriptors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;EASE;AACF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE;QACV,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,+QAA+Q;KAClR;IACD,gBAAgB,EAAE;QAChB,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,sLAAsL;KACzL;IACD,cAAc,EAAE;QACd,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,yRAAyR;KAC5R;IACD,kBAAkB,EAAE;QAClB,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EACT,4UAA4U;KAC/U;IACD,iBAAiB,EAAE;QACjB,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,4LAA4L;KAC/L;CACmD,CAAA;AAEtD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,sBAAsB,GAAiC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA"}

package/dist/audit/query/tools/get-change-history.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { Payload } from 'payload';
+import type { McpToolDefinition } from '../../../plugin-contract/mcp.js';
+export interface GetChangeHistoryDeps {
+    payload: Payload;
+    collectionSlug: string;
+}
+declare const inputSchema: z.ZodObject<{
+    targetCollection: z.ZodString;
+    targetId: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    targetCollection: string;
+    targetId: string;
+    limit?: number | undefined;
+}, {
+    targetCollection: string;
+    targetId: string;
+    limit?: number | undefined;
+}>;
+export declare function createGetChangeHistoryTool(deps: GetChangeHistoryDeps): McpToolDefinition<typeof inputSchema>;
+export {};
+//# sourceMappingURL=get-change-history.d.ts.map

package/dist/audit/query/tools/get-change-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-change-history.d.ts","sourceRoot":"","sources":["../../../../src/audit/query/tools/get-change-history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AAKxE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,QAAA,MAAM,WAAW;;;;;;;;;;;;EAUf,CAAA;AAEF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,oBAAoB,GACzB,iBAAiB,CAAC,OAAO,WAAW,CAAC,CA6BvC"}

package/dist/audit/query/tools/get-change-history.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { formatAuditEvent } from '../formatting/index.js';
+import { deniedEnvelope, isAuditReader } from './access.js';
+import { AUDIT_TOOLS } from './descriptors.js';
+const inputSchema = z.object({
+    targetCollection: z.string().describe('Collection slug (e.g. "pages").'),
+    targetId: z.string().describe('Document ID within the collection.'),
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .describe('Max events to return. Default: 50.'),
+});
+export function createGetChangeHistoryTool(deps) {
+    return {
+        ...AUDIT_TOOLS.getChangeHistory,
+        inputSchema,
+        handler: async (input, ctx) => {
+            if (!isAuditReader(ctx)) {
+                return deniedEnvelope('Only admins and editors can read a document\'s change history.');
+            }
+            const result = await deps.payload.find({
+                collection: deps.collectionSlug,
+                where: {
+                    and: [
+                        { targetCollection: { equals: input.targetCollection } },
+                        { targetId: { equals: input.targetId } },
+                    ],
+                },
+                sort: '-createdAt',
+                limit: input.limit ?? 50,
+            });
+            return {
+                targetCollection: input.targetCollection,
+                targetId: input.targetId,
+                eventCount: result.totalDocs,
+                history: result.docs.map((doc) => formatAuditEvent(doc)),
+            };
+        },
+    };
+}
+//# sourceMappingURL=get-change-history.js.map

package/dist/audit/query/tools/get-change-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-change-history.js","sourceRoot":"","sources":["../../../../src/audit/query/tools/get-change-history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAO9C,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IACxE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IACnE,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,oCAAoC,CAAC;CAClD,CAAC,CAAA;AAEF,MAAM,UAAU,0BAA0B,CACxC,IAA0B;IAE1B,OAAO;QACL,GAAG,WAAW,CAAC,gBAAgB;QAC/B,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC5B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,OAAO,cAAc,CAAC,gEAAgE,CAAC,CAAA;YACzF,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;gBACrC,UAAU,EAAE,IAAI,CAAC,cAAc;gBAC/B,KAAK,EAAE;oBACL,GAAG,EAAE;wBACH,EAAE,gBAAgB,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,gBAAgB,EAAE,EAAE;wBACxD,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE;qBACzC;iBACF;gBACD,IAAI,EAAE,YAAY;gBAClB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;aACzB,CAAC,CAAA;YAEF,OAAO;gBACL,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;gBACxC,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,UAAU,EAAE,MAAM,CAAC,SAAS;gBAC5B,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAA8B,CAAC,CAAC;aACpF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}