@skillstate/opencode 2.2.1 → 3.0.0

package/dist/state-store.js

@@ -0,0 +1,186 @@
+/**
+ * Project state persistence for the OpenCode v2 plugin.
+ *
+ * ONE store, THREE guarantees:
+ *
+ * 1. **Per-project addressing.** The state file is derived from the plugin
+ *    instance's location (`ctx.location.project.canonical`), never from
+ *    `process.cwd()`. The v1 plugin called `process.cwd()` on every hook;
+ *    in v2 a single OpenCode server serves many projects, so the process
+ *    cwd is simply the wrong answer. Two checkouts no longer share state.
+ *
+ * 2. **Per-session isolation.** A root session owns the shared project
+ *    file; a sub-agent session owns `agents/<scope>/skillstate.json` (see
+ *    `stateScopeFor`). Parallel sub-agents therefore never last-writer-win
+ *    over the main session's notes.
+ *
+ * 3. **Never lose a write.** Every mutation runs inside the core
+ *    cross-process lock ({@link withStateLock}) and lands via
+ *    {@link atomicWriteFile} (temp sibling → fsync → rename), so a crash
+ *    mid-write can never leave a truncated or interleaved state file. Reads
+ *    never throw: a missing or corrupt file reads as `{}`.
+ *
+ * The store is deliberately schema-free. It does not validate against a
+ * procedural spec: OpenCode sessions are free-form work, and forcing a
+ * fixed `goal`/`progress`/`next_steps` shape is what made the v1 prompt
+ * rewrite the user's actual task into a state machine.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { atomicWriteFile, isPlainObject, mergePatch, migrate, resolveHostStateForCwd, withStateLock, } from '@skillstate/core';
+/** Top-level diff between two state documents. Pure. */
+export function diffDocuments(before, after) {
+    const added = [];
+    const updated = [];
+    const deleted = [];
+    for (const key of Object.keys(after)) {
+        if (!(key in before)) {
+            added.push(key);
+        }
+        else if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) {
+            updated.push(key);
+        }
+    }
+    for (const key of Object.keys(before)) {
+        if (!(key in after))
+            deleted.push(key);
+    }
+    return { added, updated, deleted };
+}
+/**
+ * The state file for one session scope inside one project.
+ *
+ * `scope === ''` is the shared project file; any other scope is a
+ * sub-agent's isolated copy. Delegates to the core resolver (shared with
+ * the MCP server, the CLI and the other host adapters) so every host agrees
+ * on where a project's state lives.
+ */
+export function statePathFor(directory, scope, home = os.homedir()) {
+    return resolveHostStateForCwd(directory, home, scope);
+}
+/**
+ * Reads and merges the per-project state documents for a plugin instance.
+ *
+ * Stateless between calls apart from the filesystem, so it is safe to keep
+ * one instance per plugin and to construct it in tests without any global
+ * setup.
+ */
+export class ProjectStateStore {
+    directory;
+    home;
+    constructor(options) {
+        this.directory = path.resolve(options.directory);
+        this.home = options.home ?? os.homedir();
+    }
+    /** The project directory this store addresses. */
+    get projectDirectory() {
+        return this.directory;
+    }
+    /** The absolute state file path for a scope (`''` = shared). */
+    pathFor(scope) {
+        return statePathFor(this.directory, scope, this.home);
+    }
+    /**
+     * Whether a state file already exists for this scope. The plugin uses
+     * this to decide whether to inject the system hint at all — an untouched
+     * project must behave exactly like vanilla OpenCode.
+     */
+    exists(scope) {
+        try {
+            return fs.statSync(this.pathFor(scope)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read a scope's state. A missing, unreadable or corrupt file reads as
+     * `{}` — a best-effort read that never breaks the agent loop.
+     */
+    read(scope) {
+        const filePath = this.pathFor(scope);
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            return migrate(JSON.parse(raw)).state;
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Apply a patch to a scope's state and persist it.
+     *
+     * The read, the merge and the write all happen inside the cross-process
+     * lock, so two sub-agents writing disjoint keys both survive — neither
+     * can clobber the other's write by reading a stale snapshot.
+     *
+     * Returns the merged document and the top-level change sets. A `null`
+     * value in the patch deletes that key (paper ⊕).
+     */
+    async patch(scope, patch) {
+        const filePath = this.pathFor(scope);
+        const result = await withStateLock(filePath, async () => {
+            const before = this.read(scope);
+            const after = mergePatch(before, patch);
+            await atomicWriteFile(filePath, `${JSON.stringify({ version: 1, state: after }, null, 2)}\n`);
+            return { state: after, changes: diffDocuments(before, after) };
+        });
+        return result;
+    }
+    /**
+     * Fold a sub-agent's document into this scope's document.
+     *
+     * `keep` decides what happens when both sides set the same scalar:
+     * `'existing'` (default) keeps the receiving document's value, `'source'`
+     * takes the sub-agent's. Keys only present in the sub-agent are always
+     * taken, and `null` in either document is a deletion.
+     *
+     * The source document is left on disk — the merge is not destructive, so
+     * a sub-agent's notes remain inspectable after the fold.
+     */
+    async merge(scope, sourceScope, keep = 'existing') {
+        if (sourceScope === scope) {
+            throw new Error('skillstate_merge: a sub-agent cannot merge its own state');
+        }
+        const source = this.read(sourceScope);
+        if (Object.keys(source).length === 0) {
+            throw new Error(`skillstate_merge: no saved state for sub-agent "${sourceScope}" — nothing to merge`);
+        }
+        const filePath = this.pathFor(scope);
+        return withStateLock(filePath, async () => {
+            const before = this.read(scope);
+            const after = mergeDocuments(before, source, keep);
+            await atomicWriteFile(filePath, `${JSON.stringify({ version: 1, state: after }, null, 2)}\n`);
+            return { state: after, changes: diffDocuments(before, after) };
+        });
+    }
+}
+/**
+ * Fold `source` into `target` under a conflict policy. Pure.
+ *
+ * Nested plain objects recurse. A `null` on either side is a deletion and
+ * wins outright — an explicit "remove this" is not a scalar conflict. Every
+ * other scalar conflict follows `keep`.
+ */
+export function mergeDocuments(target, source, keep) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (value === null) {
+            delete result[key];
+            continue;
+        }
+        if (!(key in result)) {
+            result[key] = value;
+            continue;
+        }
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergeDocuments(result[key], value, keep);
+            continue;
+        }
+        if (keep === 'source')
+            result[key] = value;
+    }
+    return result;
+}
+//# sourceMappingURL=state-store.js.map

package/dist/state-store.js.map

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

package/dist/system-hint.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The system-prompt fragment the plugin contributes to each model request.
+ *
+ * ── Why this module is so small and so careful ───────────────────────────
+ *
+ * The v1 integration rewrote the conversation on every turn: it truncated
+ * history to the last three messages and appended a synthetic `role: "user"`
+ * message whose body was the raw state JSON. The reported symptom was that
+ * the agent stopped doing what it was asked and started emitting state
+ * JSON instead. The cause was structural, not a model quirk:
+ *
+ * - The last `role: "user"` message is what the model treats as the current
+ *   instruction, so the state blob displaced the user's actual request.
+ * - Truncating history deleted the task statement, the tool results, and
+ *   the errors the agent had just been given — it could not reason about
+ *   work it could no longer see.
+ *
+ * The fix is a rule, enforced by `tests/opencode/context-integrity.test.ts`:
+ * **this plugin never mutates `event.messages`.** It contributes one
+ * additive, bounded fragment to `event.system`, states what the tools are
+ * for, and explicitly leaves the task alone.
+ *
+ * The wording below is a product requirement, not prose taste. It must
+ * describe the tools without instructing the model to change how it works.
+ * Imperative framing ("you must", "always", "respond with a JSON block")
+ * is what turns a persistence aid into a prompt override.
+ */
+/** Largest state JSON rendered into the hint before falling back to a key list. */
+export declare const MAX_INLINE_STATE_CHARS = 4000;
+/** The tool names the hint advertises — kept in sync with `tools.ts`. */
+export declare const ADVERTISED_TOOLS: readonly ['skillstate_read', 'skillstate_update', 'skillstate_merge'];
+/**
+ * Render a state document for inclusion in the system prompt.
+ *
+ * Small documents are inlined verbatim (the model sees what is already
+ * saved without a tool round-trip). Documents past
+ * {@link MAX_INLINE_STATE_CHARS} are summarized as a key list plus a byte
+ * count and a pointer to `skillstate_read` — an unbounded state file must
+ * not be able to grow the system prompt without limit.
+ */
+export declare function renderStateForHint(state: Record<string, unknown>): string;
+/** Options for {@link buildStateHint}. */
+export interface StateHintOptions {
+    /** The state document this session has saved. */
+    state: Record<string, unknown>;
+    /** Project-relative state path, for the model's reference. */
+    statePath: string;
+    /**
+     * This session's scope, or `''` when it is a root session. A sub-agent
+     * hint names the merge step so the main session can fold its notes back.
+     */
+    scope?: string;
+}
+/**
+ * Build the system-prompt fragment.
+ *
+ * Returns `''` for an empty document so an untouched project contributes
+ * nothing at all — the plugin is inert until the agent actually saves
+ * something, and an inert plugin is indistinguishable from no plugin.
+ */
+export declare function buildStateHint(options: StateHintOptions): string;
+//# sourceMappingURL=system-hint.d.ts.map

package/dist/system-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-hint.d.ts","sourceRoot":"","sources":["../src/system-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,YAC3B,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,CACV,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAezE;AAED,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAwBhE"}

package/dist/system-hint.js

@@ -0,0 +1,87 @@
+/**
+ * The system-prompt fragment the plugin contributes to each model request.
+ *
+ * ── Why this module is so small and so careful ───────────────────────────
+ *
+ * The v1 integration rewrote the conversation on every turn: it truncated
+ * history to the last three messages and appended a synthetic `role: "user"`
+ * message whose body was the raw state JSON. The reported symptom was that
+ * the agent stopped doing what it was asked and started emitting state
+ * JSON instead. The cause was structural, not a model quirk:
+ *
+ * - The last `role: "user"` message is what the model treats as the current
+ *   instruction, so the state blob displaced the user's actual request.
+ * - Truncating history deleted the task statement, the tool results, and
+ *   the errors the agent had just been given — it could not reason about
+ *   work it could no longer see.
+ *
+ * The fix is a rule, enforced by `tests/opencode/context-integrity.test.ts`:
+ * **this plugin never mutates `event.messages`.** It contributes one
+ * additive, bounded fragment to `event.system`, states what the tools are
+ * for, and explicitly leaves the task alone.
+ *
+ * The wording below is a product requirement, not prose taste. It must
+ * describe the tools without instructing the model to change how it works.
+ * Imperative framing ("you must", "always", "respond with a JSON block")
+ * is what turns a persistence aid into a prompt override.
+ */
+/** Largest state JSON rendered into the hint before falling back to a key list. */
+export const MAX_INLINE_STATE_CHARS = 4000;
+/** The tool names the hint advertises — kept in sync with `tools.ts`. */
+export const ADVERTISED_TOOLS = [
+    'skillstate_read',
+    'skillstate_update',
+    'skillstate_merge',
+];
+/**
+ * Render a state document for inclusion in the system prompt.
+ *
+ * Small documents are inlined verbatim (the model sees what is already
+ * saved without a tool round-trip). Documents past
+ * {@link MAX_INLINE_STATE_CHARS} are summarized as a key list plus a byte
+ * count and a pointer to `skillstate_read` — an unbounded state file must
+ * not be able to grow the system prompt without limit.
+ */
+export function renderStateForHint(state) {
+    const json = JSON.stringify(state, null, 2);
+    if (json.length <= MAX_INLINE_STATE_CHARS)
+        return json;
+    const keys = Object.keys(state).sort();
+    const bytes = Buffer.byteLength(json, 'utf-8');
+    return `${JSON.stringify({
+        _truncated: true,
+        bytes,
+        keys,
+        hint: 'Saved state is large — call skillstate_read to load it.',
+    }, null, 2)}`;
+}
+/**
+ * Build the system-prompt fragment.
+ *
+ * Returns `''` for an empty document so an untouched project contributes
+ * nothing at all — the plugin is inert until the agent actually saves
+ * something, and an inert plugin is indistinguishable from no plugin.
+ */
+export function buildStateHint(options) {
+    const { state, statePath } = options;
+    const scope = options.scope ?? '';
+    if (Object.keys(state).length === 0)
+        return '';
+    // `skillstate_merge` is only meaningful to a sub-agent, which is the one
+    // session that cannot call it — so it is hidden from every other scope.
+    const tools = ADVERTISED_TOOLS.filter((name) => name !== 'skillstate_merge' || scope !== '');
+    const toolLine = `\nTools: ${tools.map((name) => `\`${name}\``).join(', ')}.`;
+    const mergeLine = scope === ''
+        ? ''
+        : '\nThis is a sub-agent session. When you finish, the main session folds your notes back with `skillstate_merge`; write them as if someone else will read them.';
+    return [
+        '<skillstate-project-notes>',
+        `Notes for this project are saved at \`${statePath}\` and survive a context reset or compaction.`,
+        '',
+        renderStateForHint(state),
+        `${toolLine}${mergeLine}`,
+        'Use them only to carry facts across turns — plans already made, decisions already taken, file paths, and what is left to do. The notes are a side channel, not the task: keep doing what the user asked, and skip these tools entirely when the work needs no cross-turn memory.',
+        '</skillstate-project-notes>',
+    ].join('\n');
+}
+//# sourceMappingURL=system-hint.js.map

package/dist/system-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-hint.js","sourceRoot":"","sources":["../src/system-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,iBAAiB;IACjB,mBAAmB;IACnB,kBAAkB;CACV,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,IAAI,sBAAsB;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/C,OAAO,GAAG,IAAI,CAAC,SAAS,CACtB;QACE,UAAU,EAAE,IAAI;QAChB,KAAK;QACL,IAAI;QACJ,IAAI,EAAE,yDAAyD;KAChE,EACD,IAAI,EACJ,CAAC,CACF,EAAE,CAAC;AACN,CAAC;AAeD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAyB;IACtD,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE/C,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,kBAAkB,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC;IAC7F,MAAM,QAAQ,GAAG,YAAY,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAE9E,MAAM,SAAS,GACb,KAAK,KAAK,EAAE;QACV,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,+JAA+J,CAAC;IAEtK,OAAO;QACL,4BAA4B;QAC5B,yCAAyC,SAAS,+CAA+C;QACjG,EAAE;QACF,kBAAkB,CAAC,KAAK,CAAC;QACzB,GAAG,QAAQ,GAAG,SAAS,EAAE;QACzB,kRAAkR;QAClR,6BAA6B;KAC9B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Native OpenCode tools for skillstate.
+ *
+ * These are the NATIVE tools: the fast path when the host is opencode v2.
+ * They carry a real JSON Schema and structured output, where the MCP server
+ * (`@skillstate/mcp`, still shipped and still registered) can only offer a
+ * JSON-RPC round-trip and untyped text. Both read the same state file, so
+ * the choice between them is about speed and typing on one side and reach
+ * on the other -- never about which one is correct.
+ *
+ * The MCP server was once the ONLY option: an opencode v1 plugin could not
+ * contribute first-class tools at all.
+ *
+ * Three tools, deliberately:
+ *
+ * - `skillstate_read`   - what this session has already saved.
+ * - `skillstate_update` - merge a patch (the only write path).
+ * - `skillstate_merge`  - fold sub-agent notes back into the root session.
+ *
+ * A fourth "delete everything" tool is intentionally absent: `null` in a
+ * patch already deletes a key, and a tool whose only job is to erase state
+ * is a foot-gun with no upside.
+ *
+ * ── Result shape ──────────────────────────────────────────────────────────
+ *
+ * Every tool returns a DISCRIMINATED result: `{ ok: true, ... }` or
+ * `{ ok: false, error }`. This is not a stylistic choice. A tool that
+ * declares an `output` schema must return a value matching it, so a failure
+ * path that returned only text was rejected by the host with "tool did not
+ * return its declared output" — a rejected tool call is worse for the agent
+ * than a failed one, because it loses the reason. A validation failure is a
+ * normal outcome here, and it is modelled as one.
+ *
+ * SCOPING is automatic. The current session's scope comes from
+ * `ToolContext.sessionID` plus the {@link SessionRegistry}, so the model
+ * never passes a session id and can never write another agent's file by
+ * guessing one.
+ */
+import type { ToolEditor } from '@opencode/plugin/promise/tool';
+import type { StatePatch } from '@skillstate/core';
+import type { SessionRegistry } from './session-registry.js';
+import { stateScopeFor } from './session-registry.js';
+import type { ProjectStateStore, StateChanges } from './state-store.js';
+/**
+ * Largest serialized patch a single `skillstate_update` accepts. The state
+ * file is a side channel for a human to read; a model that tries to dump a
+ * whole file into it should be told, not silently accommodated.
+ */
+export declare const MAX_PATCH_BYTES: number;
+/** A tool call that succeeded. */
+export interface ToolOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/** A tool call that was refused. `error` is written for the model to read. */
+export interface ToolError {
+    readonly ok: false;
+    readonly error: string;
+}
+/** Every tool result is one of these two. */
+export type ToolResult<T> = ToolOk<T> | ToolError;
+/** Payload of a successful `skillstate_read`. */
+export interface ReadValue {
+    readonly state: Record<string, unknown>;
+    readonly path: string;
+    readonly scope: string;
+    readonly empty: boolean;
+}
+/** Payload of a successful `skillstate_update`. */
+export interface UpdateValue {
+    readonly state: Record<string, unknown>;
+    readonly changes: StateChanges;
+    readonly path: string;
+    readonly scope: string;
+}
+/** Payload of a successful `skillstate_merge`. */
+export interface MergeValue {
+    readonly state: Record<string, unknown>;
+    readonly changes: StateChanges;
+    readonly merged: readonly string[];
+    readonly skipped: readonly string[];
+}
+/** Everything the tool definitions need, bound to one plugin instance. */
+export interface ToolDeps {
+    readonly store: ProjectStateStore;
+    readonly sessions: SessionRegistry;
+    /** Resolve a session id to its state scope; `''` is the root session. */
+    scopeFor: (sessionID: string) => string;
+}
+/**
+ * Validate and normalize an incoming patch.
+ *
+ * Returns either the patch or a human-readable reason it was rejected. The
+ * checks protect the file; they do not dictate the model's schema. A state
+ * note is free-form by design, so the only hard rules are "must be an
+ * object", "must be JSON-serializable", and "must fit".
+ */
+export declare function normalizePatch(raw: unknown): {
+    ok: true;
+    patch: StatePatch;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Register the skillstate tools on an editor.
+ *
+ * The callback is synchronous, side-effect-free and replayable: OpenCode
+ * re-runs it on every registry rebuild, so it must not do I/O at
+ * registration time. All filesystem work happens inside `execute`.
+ */
+export declare function registerTools(editor: ToolEditor, deps: ToolDeps): void;
+export { stateScopeFor };
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAe,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,kCAAkC;AAClC,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,6CAA6C;AAC7C,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;AAElD,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,yEAAyE;IACzE,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AA0JD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,GACX;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAoCjE;AAwBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAkItE;AAOD,OAAO,EAAE,aAAa,EAAE,CAAC"}