@intutic/gate 1.10.1

package/dist/client.d.ts

@@ -0,0 +1,94 @@
+/**
+ * HTTP client for the Intutic control plane's gate endpoints.
+ *
+ * Port of `packages/intutic-clawde/intutic_clawde/gate/client.py`.
+ *
+ * Endpoints used:
+ *
+ *   POST /api/v1/hook-gate       synchronous allow/deny  -> {allowed, reason, incidentId?}
+ *   POST /api/v1/hook-events     batched telemetry       -> creates governance_incidents rows
+ *
+ * Two behaviours that must not be "improved":
+ *
+ *   * The hook-gate SERVER fails OPEN on its own error paths — it returns
+ *     `{allowed:true}` on malformed input, schema mismatch, or DB error,
+ *     because blocking a developer over a bad payload teaches people to
+ *     disable the hook. This CLIENT, by contrast, defaults to FAIL-CLOSED
+ *     (`failClosed=true`) for blocking decisions: a transport error or
+ *     non-2xx response means we have no verdict at all to defer to, so
+ *     `hookGate` reports `allowed=false`. Set `failClosed=false` to treat the
+ *     tier as advisory, mirroring the server's own posture.
+ *   * `emit` NEVER throws. Telemetry that can break a run is worse than no
+ *     telemetry.
+ */
+export interface GateResponse {
+    allowed: boolean;
+    reason: string;
+    incidentId?: string | undefined;
+    /** False when the call failed and `failClosed` decided the verdict. */
+    reached: boolean;
+}
+export interface GateClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    workspaceId?: string;
+    sessionId?: string;
+    /**
+     * Attributes incidents to the right adapter. Sent as `harnessType` on every
+     * gate call and event.
+     */
+    harness?: string;
+    failClosed?: boolean;
+    timeoutMs?: number;
+}
+/**
+ * Control-plane client for the pre-execution gate.
+ *
+ * `harness` defaults to `"generic"` and is sent as `harnessType` on every
+ * gate call and event, so incidents attribute to the right adapter. Override
+ * it when wrapping a specific framework (`mastra`, `vercel-ai`,
+ * `langchainjs`, `dsh`, ...).
+ */
+export declare class GateClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly workspaceId: string;
+    readonly sessionId: string;
+    readonly harness: string;
+    readonly failClosed: boolean;
+    readonly timeoutMs: number;
+    constructor(opts?: GateClientOptions);
+    private post;
+    /**
+     * Synchronous allow/deny for one tool call.
+     *
+     * The endpoint matches ~19 DLP regexes against the serialised toolInput,
+     * plus SOP rules. It is defence in depth on top of the local tiers, not a
+     * replacement for them.
+     *
+     * When the call itself fails (transport error, non-2xx), the verdict is
+     * decided by `failClosed`: true (the default) reports BLOCK, because a
+     * client with no verdict has nothing to defer to; false reports allow,
+     * mirroring the server's own fail-open error paths.
+     */
+    hookGate(toolName: string, toolInput: unknown): Promise<GateResponse>;
+    /**
+     * Fire-and-forget telemetry. Never throws.
+     *
+     * A `tool_blocked` event creates a `governance_incidents` row whose
+     * description embeds the reason verbatim.
+     */
+    emit(event: string, toolName: string, reason?: string, toolInput?: unknown, incidentId?: string, filePath?: string): Promise<boolean>;
+    /**
+     * Build a client from the environment, falling back to CLI credentials.
+     *
+     * Reading `~/.intutic/credentials.json` means the gate works with whatever
+     * workspace `intutic login` already bound, instead of duplicating the key.
+     */
+    static fromEnv(opts?: {
+        sessionId?: string;
+        harness?: string;
+        failClosed?: boolean;
+    }): GateClient;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyBH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAEd,IAAI,GAAE,iBAAsB;YAa1B,IAAI;IAsBlB;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IAoC3E;;;;;OAKG;IACG,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAK,EACX,SAAS,CAAC,EAAE,OAAO,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAsBnB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,UAAU;CAoCtG"}

package/dist/client.js

@@ -0,0 +1,207 @@
+/**
+ * HTTP client for the Intutic control plane's gate endpoints.
+ *
+ * Port of `packages/intutic-clawde/intutic_clawde/gate/client.py`.
+ *
+ * Endpoints used:
+ *
+ *   POST /api/v1/hook-gate       synchronous allow/deny  -> {allowed, reason, incidentId?}
+ *   POST /api/v1/hook-events     batched telemetry       -> creates governance_incidents rows
+ *
+ * Two behaviours that must not be "improved":
+ *
+ *   * The hook-gate SERVER fails OPEN on its own error paths — it returns
+ *     `{allowed:true}` on malformed input, schema mismatch, or DB error,
+ *     because blocking a developer over a bad payload teaches people to
+ *     disable the hook. This CLIENT, by contrast, defaults to FAIL-CLOSED
+ *     (`failClosed=true`) for blocking decisions: a transport error or
+ *     non-2xx response means we have no verdict at all to defer to, so
+ *     `hookGate` reports `allowed=false`. Set `failClosed=false` to treat the
+ *     tier as advisory, mirroring the server's own posture.
+ *   * `emit` NEVER throws. Telemetry that can break a run is worse than no
+ *     telemetry.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_TIMEOUT_MS = 2_000;
+const EVENT_TIMEOUT_MS = 2_000;
+const REASON_MAX = 512; // control plane truncates at 512; do it here so logs match
+// Mirrors HookEventSchema in services/control-plane/src/routes/hookEvents.ts.
+const VALID_EVENTS = new Set([
+    'tool_blocked',
+    'tool_allowed',
+    'tool_flagged',
+    'tool_would_block',
+    'config_tamper',
+    'network_bypass',
+    'guards_disabled',
+    'snapshot_absent',
+    'snapshot_stale',
+    'snapshot_invalid',
+    'snapshot_empty',
+]);
+/**
+ * Control-plane client for the pre-execution gate.
+ *
+ * `harness` defaults to `"generic"` and is sent as `harnessType` on every
+ * gate call and event, so incidents attribute to the right adapter. Override
+ * it when wrapping a specific framework (`mastra`, `vercel-ai`,
+ * `langchainjs`, `dsh`, ...).
+ */
+export class GateClient {
+    baseUrl;
+    apiKey;
+    workspaceId;
+    sessionId;
+    harness;
+    failClosed;
+    timeoutMs;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl || process.env.INTUTIC_CONTROL_PLANE_URL || 'https://api.intutic.ai').replace(/\/$/, '');
+        this.apiKey = opts.apiKey ?? '';
+        this.workspaceId = opts.workspaceId ?? '';
+        this.sessionId = opts.sessionId ?? '';
+        this.harness = opts.harness ?? 'generic';
+        this.failClosed = opts.failClosed ?? true;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async post(path, body, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(this.baseUrl + path, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'X-Workspace-Id': this.workspaceId,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} from ${path}`);
+            const text = await res.text();
+            return text ? JSON.parse(text) : {};
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Synchronous allow/deny for one tool call.
+     *
+     * The endpoint matches ~19 DLP regexes against the serialised toolInput,
+     * plus SOP rules. It is defence in depth on top of the local tiers, not a
+     * replacement for them.
+     *
+     * When the call itself fails (transport error, non-2xx), the verdict is
+     * decided by `failClosed`: true (the default) reports BLOCK, because a
+     * client with no verdict has nothing to defer to; false reports allow,
+     * mirroring the server's own fail-open error paths.
+     */
+    async hookGate(toolName, toolInput) {
+        try {
+            const d = await this.post('/api/v1/hook-gate', {
+                toolName,
+                toolInput,
+                workspaceId: this.workspaceId,
+                sessionId: this.sessionId,
+                harnessType: this.harness,
+            }, this.timeoutMs);
+            return {
+                allowed: Boolean(d.allowed ?? true),
+                reason: String(d.reason ?? ''),
+                incidentId: typeof d.incidentId === 'string' ? d.incidentId : undefined,
+                reached: true,
+            };
+        }
+        catch (exc) {
+            const name = exc instanceof Error ? exc.constructor.name : 'Error';
+            if (this.failClosed) {
+                return {
+                    allowed: false,
+                    reason: `hook-gate unreachable (${name}) — failing closed (failClosed=true)`,
+                    reached: false,
+                };
+            }
+            return {
+                allowed: true,
+                reason: `hook-gate unreachable (${name}) — failing open (failClosed=false)`,
+                reached: false,
+            };
+        }
+    }
+    /**
+     * Fire-and-forget telemetry. Never throws.
+     *
+     * A `tool_blocked` event creates a `governance_incidents` row whose
+     * description embeds the reason verbatim.
+     */
+    async emit(event, toolName, reason = '', toolInput, incidentId, filePath) {
+        if (!VALID_EVENTS.has(event))
+            return false;
+        const ev = {
+            event,
+            toolName,
+            reason: (reason || '').slice(0, REASON_MAX),
+            workspaceId: this.workspaceId,
+            sessionId: this.sessionId,
+            harnessType: this.harness,
+            timestamp: new Date().toISOString(),
+        };
+        if (toolInput !== undefined)
+            ev.toolInput = toolInput;
+        if (incidentId)
+            ev.incidentId = incidentId;
+        if (filePath)
+            ev.filePath = filePath.slice(0, 512);
+        try {
+            await this.post('/api/v1/hook-events', { events: [ev] }, EVENT_TIMEOUT_MS);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Build a client from the environment, falling back to CLI credentials.
+     *
+     * Reading `~/.intutic/credentials.json` means the gate works with whatever
+     * workspace `intutic login` already bound, instead of duplicating the key.
+     */
+    static fromEnv(opts = {}) {
+        const base = process.env.INTUTIC_CONTROL_PLANE_URL || 'https://api.intutic.ai';
+        let key = process.env.INTUTIC_API_KEY || '';
+        let ws = process.env.INTUTIC_WORKSPACE_ID || '';
+        if (!key || !ws) {
+            try {
+                const credPath = join(homedir(), '.intutic', 'credentials.json');
+                const c = JSON.parse(readFileSync(credPath, 'utf-8'));
+                key = key || String(c.apiKey ?? '');
+                ws = ws || String(c.workspaceId ?? '');
+            }
+            catch {
+                // No credentials file — fall through with whatever env supplied.
+            }
+        }
+        const sess = opts.sessionId || process.env.INTUTIC_SESSION_ID || '';
+        if (!sess) {
+            // The proxy defaults an unset x-session-id to the literal "unknown",
+            // which collapses every run onto one dashboard row. Refuse instead.
+            throw new Error('No session id. Set INTUTIC_SESSION_ID or pass sessionId — an unset x-session-id ' +
+                "becomes the literal 'unknown' in the proxy and merges every run into a single " +
+                'dashboard session.');
+        }
+        return new GateClient({
+            baseUrl: base,
+            apiKey: key,
+            workspaceId: ws,
+            sessionId: sess,
+            harness: opts.harness ?? 'generic',
+            failClosed: opts.failClosed ?? true,
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/dsh.d.ts

@@ -0,0 +1,162 @@
+/**
+ * dsh.ts — Cordis plugin adapter for DeepSeek's "dsh" harness.
+ *
+ * Published as the `@intutic/gate/dsh` subpath (see README.md's "Subpath
+ * convention for later phases"). `services/sync-daemon/src/harness/dshHooks.ts`
+ * merge-writes a row naming this module (`name: '@intutic/gate/dsh'`) into a
+ * dsh profile's `cordis.patch.yml`; dsh's own Cordis loader resolves that name
+ * with a plain dynamic `import()` and mounts the exported plugin
+ * (`{ name, inject, apply }`) the same way it mounts every other bundle row.
+ *
+ * ## The veto mechanism — CONFIRMED against a real install, not assumed
+ *
+ * dsh is a developer preview (`@deepseek-ai/dsh`, first published 2026-08-13)
+ * built on DeepSeek's own "Cordis" plugin framework (`@deepseek-ai/cordis`,
+ * `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-app-boot`, ...). Both are public
+ * on the npm registry, and this module was authored against a real
+ * `npm pack`/inspection of them (see the TD entry this phase filed for exactly
+ * what was checked and what still had to be assumed) — NOT solely from the
+ * phase brief's prior guess, which named a different event (`agent/pre-step`)
+ * and a different decision shape (`{kind:'reject',...}`). Both turned out to
+ * be close but not exact:
+ *
+ *   - The real per-tool veto point is `tools/pre-execute` (declared by
+ *     `@deepseek-ai/dsh-tools`), not `agent/pre-step` (`@deepseek-ai/dsh-agent`'s
+ *     per-turn/step event — a coarser boundary that batches a driver step
+ *     rather than one tool call, and the wrong extension point for a
+ *     per-tool-call gate).
+ *   - It is a genuine Cordis `waterfall`: `(exec: ToolExecution, next: () =>
+ *     Promise<PreToolDecision>) => Promise<PreToolDecision>`. Cordis's own
+ *     waterfall contract (confirmed by reading `@deepseek-ai/cordis`'s
+ *     `events.d.ts`) composes listeners around a `next()` continuation —
+ *     "a listener that does not call next() vetoes the rest of the chain,
+ *     including the built-in behavior" — so this listener calls `next()` on
+ *     ALLOW (to preserve whatever later listener or built-in behaviour — e.g.
+ *     dsh's own `ask`/approval flow — would otherwise run) and returns its own
+ *     `{kind:'deny',...}` WITHOUT calling `next()` to veto.
+ *   - The decision shape is `PreToolDecision = {kind:'allow'} | {kind:'deny',
+ *     reason} | {kind:'ask', reason?}` (confirmed from
+ *     `@deepseek-ai/dsh-tools`'s shipped `.d.ts`) — `'deny'`, not the phase
+ *     brief's guessed `'reject'`.
+ *
+ * `ctx.tools.guard()` (a separate, monotonic, explicitly SYNCHRONOUS
+ * mechanism dsh also exposes) was considered and rejected: `@intutic/gate`'s
+ * `Gate.guard()` is async (network-backed SOP-rule fetch and `/hook-gate`
+ * POST — see gate.ts's module doc), and a synchronous `ToolGuard` cannot
+ * `await` it. `tools/pre-execute` is the only one of dsh's two extension
+ * points this package's async contract fits.
+ *
+ * ## What this module does NOT import
+ *
+ * Deliberately no dependency on `@deepseek-ai/cordis` or `@deepseek-ai/dsh-tools`
+ * at runtime — `CordisLikeContext`/`DshToolExecution`/`DshPreToolDecision`
+ * below are narrow structural types capturing only the shape this plugin
+ * actually touches, matching Cordis's own duck-typed plugin contract (a
+ * plain `{ name?, inject?, apply(ctx, config) }` object — confirmed against
+ * both `@deepseek-ai/cordis`'s README quick-start and dsh's own in-product
+ * "cordis-plugin-development" skill doc, which returns `{ apply(ctx) {...} }`
+ * with no import of anything). Adding a hard dependency on a fast-moving
+ * preview product's framework package to `@intutic/gate`'s dsh subpath would
+ * make every OTHER subpath's install pull it in too (or need a peerDependency
+ * carve-out) for a shape simple enough to describe locally. The real
+ * `@deepseek-ai/cordis` package is used only as a devDependency, in this
+ * module's own test file, to exercise the real waterfall dispatch mechanics
+ * against the genuine `Context` class rather than a hand-rolled stand-in.
+ *
+ * @module
+ */
+import { Gate } from './gate.js';
+import type { GateConfig } from './gate.js';
+/** The Cordis Plugin id this module registers as. Shown in dsh's own plugin
+ *  diagnostics/`--dump-config` output. */
+export declare const PLUGIN_NAME = "intutic-governance";
+/**
+ * The slice of dsh's real `tools/pre-execute` payload (`ToolExecution`, from
+ * `@deepseek-ai/dsh-tools`) this plugin reads. `arguments` is documented as
+ * "losslessly JSON-serializable parsed arguments (tools validate their own
+ * schema)" — an `unknown`, not necessarily an object, hence
+ * {@link renderDshToolInput} below.
+ */
+export interface DshToolExecution {
+    readonly name: string;
+    readonly arguments: unknown;
+}
+/** The confirmed real `PreToolDecision` union from `@deepseek-ai/dsh-tools`. */
+export type DshPreToolDecision = {
+    kind: 'allow';
+} | {
+    kind: 'deny';
+    reason: string;
+} | {
+    kind: 'ask';
+    reason?: string;
+};
+/**
+ * Structural stand-in for the Cordis `Context` this plugin needs — see the
+ * module doc for why the real `@deepseek-ai/cordis` package is not imported.
+ */
+export interface CordisLikeContext {
+    on(event: 'tools/pre-execute', listener: (exec: DshToolExecution, next: () => Promise<DshPreToolDecision>) => Promise<DshPreToolDecision>): () => boolean;
+}
+/** `cordis.patch.yml` row config for this plugin. Extends the core
+ *  {@link GateConfig} with the one dsh-specific knob: an explicit session id,
+ *  since dsh has no single "the session" this plugin can read off `exec` (a
+ *  `ToolExecution` carries an `agent?`, not a raw session/conversation id) —
+ *  see {@link resolveSessionId}. */
+export interface DshGateConfig extends GateConfig {
+    /** Overrides the generated-per-process session id. Mirrors
+     *  `INTUTIC_SESSION_ID` for callers that already have one to hand. */
+    sessionId?: string;
+}
+/** Cordis Plugins declare their hard dependencies here; the loader defers
+ *  activation until every named service exists and reactivates on restart.
+ *  `tools` is `@deepseek-ai/dsh-tools`'s `ToolRegistry` service — the thing
+ *  that actually dispatches `tools/pre-execute`. */
+export declare const inject: string[];
+/**
+ * Build the `tools/pre-execute` listener for a given {@link Gate}.
+ *
+ * Factored out of {@link apply} so a test can exercise the exact listener
+ * `apply()` registers — event extraction, the refusal-to-decision mapping,
+ * the fail-closed default, and the waterfall `next()`-calling on allow —
+ * against a controllable fake `Gate`, without needing a real dsh install or
+ * network access to construct a `GateClient`.
+ *
+ * Never throws: every path returns a {@link DshPreToolDecision}. A crash
+ * inside `gate.guard()` that is not an {@link IntuticGateRefusal} — a bug in
+ * this gate, or an unexpected throw from a tier it calls into — is treated
+ * as "cannot evaluate" and denied rather than allowed to escape the
+ * waterfall or fall through to an allow; see gate.ts's own module doc for why
+ * every tier in this package takes that direction on failure.
+ */
+export declare function createPreExecuteListener(gate: Gate): (exec: DshToolExecution, next: () => Promise<DshPreToolDecision>) => Promise<DshPreToolDecision>;
+/**
+ * Mount the Intutic governance gate on a dsh profile.
+ *
+ * Builds one {@link Gate} for the lifetime of this plugin instance (not per
+ * call — Tier A1/A2/A3 all cache within a `Gate`, see gate.ts) and installs it
+ * as the process-wide default too (`install()`), so a hand-authored
+ * `wrapTool`/`wrapTools` call elsewhere in the same dsh process picks up the
+ * identical instance rather than constructing a second one with independent
+ * caches.
+ *
+ * Never throws out of `apply()` itself: a `GateClient.fromEnv` failure (e.g.
+ * credentials genuinely unreadable) degrades to a client-less `Gate` — Tier B
+ * and Tier A3 inactive, Tier A1/A2 (local, load-bearing) unaffected — rather
+ * than taking down the whole dsh profile boot over a governance layer that is
+ * additive by design.
+ */
+export declare function apply(ctx: CordisLikeContext, config?: DshGateConfig): void;
+/** Default export — the whole Plugin object, for `name: '@intutic/gate/dsh'`
+ *  cordis.patch.yml rows that resolve this module and pass it directly to
+ *  `ctx.plugin()` (dsh's loader unwraps a default export the same way it
+ *  unwraps a named one — see `dsh-app-boot`'s `unwrapExports`). Named exports
+ *  (`apply`, `inject`, `PLUGIN_NAME`) are also available for a caller that
+ *  imports this subpath directly rather than through the loader. */
+declare const _default: {
+    name: string;
+    inject: string[];
+    apply: typeof apply;
+};
+export default _default;
+//# sourceMappingURL=dsh.d.ts.map

package/dist/dsh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh.d.ts","sourceRoot":"","sources":["../src/dsh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,EAAE,IAAI,EAAW,MAAM,WAAW,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,WAAW,CAAA;AAItD;0CAC0C;AAC1C,eAAO,MAAM,WAAW,uBAAuB,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,gFAAgF;AAChF,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAExH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,CACA,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,KAAK,OAAO,CAAC,kBAAkB,CAAC,GACzG,MAAM,OAAO,CAAA;CACjB;AAED;;;;oCAIoC;AACpC,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C;0EACsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;oDAGoD;AACpD,eAAO,MAAM,MAAM,UAAY,CAAA;AAwC/B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,GACT,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAoBlG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,GAAE,aAAkB,GAAG,IAAI,CAY9E;AAED;;;;;oEAKoE;;;;;;AACpE,wBAAmD"}