@dungle-scrubs/tallow 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kevin Frilot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+<p align="center">
+  <img src="assets/logo.jpg" width="200" alt="Tallow logo" />
+</p>
+
+<h1 align="center">Tallow</h1>
+
+<p align="center">
+  An opinionated coding agent. Built on <a href="https://github.com/nicobrinkkemper/pi-coding-agent">pi</a>.
+</p>
+
+<p align="center">
+  <a href="https://tallow.dungle-scrubs.com">Docs</a> · <a href="https://github.com/dungle-scrubs/tallow">GitHub</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/dungle-scrubs/tallow/actions/workflows/ci.yml"><img src="https://github.com/dungle-scrubs/tallow/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/tallow"><img src="https://img.shields.io/npm/v/tallow" alt="npm version" /></a>
+  <a href="https://img.shields.io/badge/Bun-%E2%89%A51.3.9-f9f1e1?logo=bun"><img src="https://img.shields.io/badge/Bun-%E2%89%A51.3.9-f9f1e1?logo=bun" alt="Bun ≥1.3.9" /></a>
+  <a href="https://tallow.dungle-scrubs.com"><img src="https://img.shields.io/badge/docs-tallow-blue" alt="Docs" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/screenshot.jpg" alt="Tallow multi-agent team coordinating a docs audit" />
+</p>
+
+49 extensions, 34 themes, 8 slash commands, and 10 specialized agents.
+Install only what you need — the interactive installer lets you pick.
+
+## Features
+
+- **49 bundled extensions** — enhanced tools, hooks, tasks, teams, LSP, themes, permissions, context usage, and more
+- **34 terminal themes** — Tokyo Night, Catppuccin, Gruvbox, Rose Pine, Nord, and many others
+- **8 slash commands** — `/implement`, `/implement-and-review`, `/review`, `/fix`, `/test`, `/scout-and-plan`, `/scaffold`, `/question`
+- **9 specialized agents** — architect, debug, explore, planner, refactor, reviewer, scout, worker, tallow-expert
+- **Multi-agent teams** — coordinate multiple agents with task boards, messaging, and archive/resume
+- **Session naming** — auto-generated descriptive names for each session, shown in footer and `--list`
+- **Context fork** — run skills and commands in isolated subprocesses via `context: fork` frontmatter
+- **Debug mode** — structured JSONL diagnostic logging with `/diag` command
+- **Claude Code compatible** — `.claude/` directory bridging for seamless use of Tallow skills, agents, and commands in Claude Code
+- **SDK** — embed Tallow in your own scripts and orchestrators
+- **User-owned config** — agents and commands are installed to `~/.tallow/` where you can edit, remove, or add your own
+
+Read the full [documentation](https://tallow.dungle-scrubs.com).
+
+## Requirements
+
+- Node.js ≥ 22
+- An API key for at least one supported LLM provider (Anthropic, OpenAI, Google, etc.)
+
+## Installation
+
+### Global install
+
+```bash
+bun install -g tallow
+tallow install
+```
+
+Or without global install:
+
+```bash
+bunx tallow install
+```
+
+### From source
+
+```bash
+git clone https://github.com/dungle-scrubs/tallow.git
+cd tallow
+bun install
+bun run build
+node dist/install.js
+```
+
+The installer walks you through selecting extensions, themes, and agents,
+then links the `tallow` binary globally.
+
+## Usage
+
+```bash
+# Interactive mode
+tallow
+
+# Single-shot prompt
+tallow -p "Fix the failing tests"
+
+# Pipe input from stdin
+echo "Explain this error" | tallow
+cat README.md | tallow -p "Summarize this"
+git diff | tallow -p "Review these changes"
+
+# Continue most recent session
+tallow --continue
+
+# Use a specific model
+tallow -m anthropic/claude-sonnet-4-20250514
+
+# Set thinking level
+tallow --thinking high
+
+# Run without persisting session
+tallow --no-session
+
+# Load additional extensions
+tallow -e ./my-extension
+
+# List saved sessions (shows auto-generated names)
+tallow --list
+
+# Runtime auth via environment (not persisted)
+TALLOW_API_KEY=sk-ant-... tallow --provider anthropic
+
+# Runtime auth via reference (resolved at runtime)
+TALLOW_API_KEY_REF=op://Services/Anthropic/api-key tallow --provider anthropic
+
+# Run in RPC or JSON mode
+tallow --mode rpc
+
+# Restrict available tools
+tallow --tools read,grep,find      # Only read, grep, find
+tallow --tools readonly            # Preset: read, grep, find, ls
+tallow --tools none                # Chat only, no tools
+
+# Disable all extensions
+tallow --no-extensions
+
+# Print tallow home directory
+tallow --home
+```
+
+`--api-key` was removed to avoid leaking secrets in process arguments.
+Use `TALLOW_API_KEY` or `TALLOW_API_KEY_REF` instead.
+
+### Piped input
+
+Pipe file contents or command output directly into Tallow:
+
+```bash
+# Stdin becomes the prompt
+echo "What is 2+2?" | tallow
+
+# Stdin as context + explicit prompt
+cat src/main.ts | tallow -p "Find bugs in this code"
+
+# Pipe command output
+git log --oneline -20 | tallow -p "Summarize recent changes"
+```
+
+When stdin is piped, Tallow automatically enters print mode (single-shot).
+If both stdin and `-p` are provided, stdin is prepended as context before the
+prompt. Piped input is capped at 10 MB. JSON mode (`--mode json`) also
+accepts piped stdin.
+
+### Shell interpolation
+
+Expand shell commands inline with `` !`command` `` syntax:
+
+```
+!`ls -la`
+!`git status`
+!`git branch --show-current`
+```
+
+**Disabled by default.** Enable explicitly with either:
+
+- `TALLOW_ENABLE_SHELL_INTERPOLATION=1` (or `TALLOW_SHELL_INTERPOLATION=1`)
+- `"shellInterpolation": true` in `.tallow/settings.json` or `~/.tallow/settings.json`
+
+When enabled, only allowlisted implicit commands run. The command output
+replaces the pattern before reaching the agent. 5-second timeout, 1 MB
+max output, non-recursive. High-risk explicit shell commands require
+confirmation (`TALLOW_ALLOW_UNSAFE_SHELL=1` bypasses confirmation in
+non-interactive environments).
+
+### Slash commands
+
+Inside an interactive session, type `/` to see available commands:
+
+| Command | Description |
+|---------|-------------|
+| `/implement` | Implement a feature from a description |
+| `/implement-and-review` | Implement then self-review |
+| `/review` | Review recent changes |
+| `/fix` | Fix a bug from a description |
+| `/test` | Write or fix tests |
+| `/scout-and-plan` | Explore the codebase and create a plan |
+| `/scaffold` | Scaffold a new project |
+| `/question` | Introspect on agent reasoning without triggering actions |
+
+## SDK
+
+Use Tallow programmatically in your own tools:
+
+```typescript
+import { createTallowSession } from "tallow";
+
+const { session } = await createTallowSession({
+  provider: "anthropic",
+  modelId: "claude-sonnet-4-20250514",
+});
+
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt("What files are in this directory?");
+session.dispose();
+```
+
+### SDK options
+
+```typescript
+const tallow = await createTallowSession({
+  cwd: "/path/to/project",
+  provider: "anthropic",
+  modelId: "claude-sonnet-4-20250514",
+  thinkingLevel: "high",
+  session: { type: "memory" },        // Don't persist
+  noBundledExtensions: true,           // Start clean
+  additionalExtensions: ["./my-ext"],   // Add your own
+  systemPrompt: "You are a test bot.",  // Override system prompt
+  apiKey: process.env.ANTHROPIC_API_KEY, // Runtime only, not persisted
+});
+```
+
+## Configuration
+
+Tallow stores its configuration in `~/.tallow/`:
+
+| Path | Purpose |
+|------|---------|
+| `~/.tallow/settings.json` | Global settings |
+| `~/.tallow/.env` | Environment variables loaded at startup (supports `op://` refs) |
+| `~/.tallow/auth.json` | Provider auth references (see [SECURITY.md](SECURITY.md)) |
+| `~/.tallow/models.json` | Model configuration |
+| `~/.tallow/keybindings.json` | Keybinding overrides |
+| `~/.tallow/agents/` | Agent profiles (installed from templates, yours to edit) |
+| `~/.tallow/commands/` | Slash commands (installed from templates, yours to edit) |
+| `~/.tallow/extensions/` | User extensions (override bundled ones by name) |
+| `~/.tallow/sessions/` | Persisted conversation sessions |
+
+Project-level configuration lives in `.tallow/` within your project directory.
+
+## Icons
+
+Override any TUI glyph in `~/.tallow/settings.json`:
+
+```json
+{
+  "icons": {
+    "success": "✔",
+    "error": "✘",
+    "spinner": ["⠋", "⠙", "⠹", "⠸"]
+  }
+}
+```
+
+Only keys you set are overridden — everything else keeps its default.
+See the [icon reference](https://tallow.dungle-scrubs.com/getting-started/icons/) for all available keys.
+
+## Themes
+
+Switch themes inside an interactive session with the `/theme` command,
+or set one in `~/.tallow/settings.json`:
+
+```json
+{
+  "theme": "tokyo-night"
+}
+```
+
+## Writing extensions
+
+Extensions are TypeScript files that receive the pi `ExtensionAPI`:
+
+```typescript
+import type { ExtensionAPI } from "tallow";
+
+export default function myExtension(api: ExtensionAPI): void {
+  api.registerCommand("greet", {
+    description: "Say hello",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify("Hello from my extension!", "info");
+    },
+  });
+}
+```
+
+Place your extension in `~/.tallow/extensions/my-extension/index.ts`.
+If it shares a name with a bundled extension, yours takes precedence.
+
+## Known limitations
+
+- Requires Node.js 22+ (uses modern ESM features)
+- Session persistence is local — no cloud sync
+- The `web_fetch` extension works best with a [Firecrawl](https://firecrawl.dev) API key for JS-heavy pages
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[MIT](LICENSE) © Kevin Frilot

package/dist/atomic-write.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Options for atomic file writes.
+ */
+interface AtomicWriteOptions {
+    /** File encoding (defaults to "utf-8"). */
+    encoding?: BufferEncoding;
+    /** File permission mode (e.g., 0o600 for restricted access). */
+    mode?: number;
+    /** Whether to fsync the temp file before rename for durability. */
+    fsync?: boolean;
+    /** Whether to create a `.bak` backup of the existing file before overwriting. */
+    backup?: boolean;
+}
+/**
+ * Atomically write data to a file using write-tmp-then-rename.
+ *
+ * Creates a temp file in the same directory as the target (ensuring same
+ * filesystem for atomic rename), writes data to it, optionally fsyncs,
+ * then renames over the target. If anything fails, the temp file is
+ * cleaned up and the original file is untouched.
+ *
+ * @param filePath - Target file path
+ * @param data - Content to write
+ * @param options - Encoding, mode, fsync, and backup options
+ * @throws {Error} When the write or rename fails (after cleanup)
+ */
+export declare function atomicWriteFileSync(filePath: string, data: string | Buffer, options?: AtomicWriteOptions): void;
+/**
+ * Attempt to restore a file from its `.bak` backup.
+ *
+ * Call this on startup when a config file is missing or corrupt.
+ * Returns true if restoration succeeded, false if no backup existed
+ * or the backup was also corrupt.
+ *
+ * @param filePath - Target file path to restore
+ * @param validate - Optional validator (e.g., JSON.parse) to verify backup integrity
+ * @returns Whether the file was successfully restored
+ */
+export declare function restoreFromBackup(filePath: string, validate?: (content: string) => void): boolean;
+export {};
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,UAAU,kBAAkB;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,CAAC,EAAE,kBAAkB,GAC1B,IAAI,CAiCN;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAmBjG"}

package/dist/atomic-write.js

@@ -0,0 +1,109 @@
+import { closeSync, copyFileSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * Generate a short random suffix for temp file names.
+ *
+ * @returns 8-character hex string
+ */
+function randomSuffix() {
+    return Math.random().toString(16).slice(2, 10);
+}
+/**
+ * Atomically write data to a file using write-tmp-then-rename.
+ *
+ * Creates a temp file in the same directory as the target (ensuring same
+ * filesystem for atomic rename), writes data to it, optionally fsyncs,
+ * then renames over the target. If anything fails, the temp file is
+ * cleaned up and the original file is untouched.
+ *
+ * @param filePath - Target file path
+ * @param data - Content to write
+ * @param options - Encoding, mode, fsync, and backup options
+ * @throws {Error} When the write or rename fails (after cleanup)
+ */
+export function atomicWriteFileSync(filePath, data, options) {
+    const dir = dirname(filePath);
+    const base = basename(filePath);
+    const tmpPath = join(dir, `.${base}.${randomSuffix()}.tmp`);
+    const encoding = options?.encoding ?? "utf-8";
+    // Backup existing file before overwriting
+    if (options?.backup && existsSync(filePath)) {
+        backupFileSync(filePath);
+    }
+    try {
+        writeFileSync(tmpPath, data, { encoding, mode: options?.mode });
+        if (options?.fsync) {
+            const fd = openSync(tmpPath, "r");
+            try {
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        renameSync(tmpPath, filePath);
+    }
+    catch (err) {
+        // Clean up temp file on failure
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // Temp file may not exist if writeFileSync failed before creating it
+        }
+        throw err;
+    }
+}
+/**
+ * Create a `.bak` copy of a file. Overwrites any existing backup.
+ * The backup itself is written atomically.
+ *
+ * @param filePath - File to back up
+ */
+function backupFileSync(filePath) {
+    const bakPath = `${filePath}.bak`;
+    const tmpBak = `${bakPath}.${randomSuffix()}.tmp`;
+    try {
+        copyFileSync(filePath, tmpBak);
+        renameSync(tmpBak, bakPath);
+    }
+    catch {
+        try {
+            unlinkSync(tmpBak);
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        // Don't fail the main write if backup fails
+    }
+}
+/**
+ * Attempt to restore a file from its `.bak` backup.
+ *
+ * Call this on startup when a config file is missing or corrupt.
+ * Returns true if restoration succeeded, false if no backup existed
+ * or the backup was also corrupt.
+ *
+ * @param filePath - Target file path to restore
+ * @param validate - Optional validator (e.g., JSON.parse) to verify backup integrity
+ * @returns Whether the file was successfully restored
+ */
+export function restoreFromBackup(filePath, validate) {
+    const bakPath = `${filePath}.bak`;
+    if (!existsSync(bakPath))
+        return false;
+    try {
+        const content = readFileSync(bakPath, "utf-8");
+        // If a validator is provided, verify the backup is valid
+        if (validate) {
+            validate(content);
+        }
+        // Atomically restore (no backup of the backup)
+        atomicWriteFileSync(filePath, content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

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

package/dist/auth-hardening.d.ts

@@ -0,0 +1,86 @@
+import { type AuthCredential, AuthStorage } from "@mariozechner/pi-coding-agent";
+/** Result of the plaintext migration run. */
+export interface MigrationResult {
+    /** Providers migrated from plaintext/op:// to secure references. */
+    readonly migratedProviders: readonly string[];
+}
+/** Storage outcome for persisted provider credentials. */
+export type PersistedKeyMode = "keychain" | "reference";
+/**
+ * Dependency boundary for storing raw API keys outside auth.json.
+ */
+export interface ApiKeySecretStore {
+    /**
+     * Store a raw API key and return a safe reference string for auth.json.
+     *
+     * @param provider - Provider ID
+     * @param apiKey - Raw provider API key
+     * @returns Reference string to persist in auth.json
+     */
+    store(provider: string, apiKey: string): string;
+}
+export interface SecureAuthStorageOptions {
+    readonly secretStore?: ApiKeySecretStore;
+}
+/**
+ * AuthStorage wrapper that guarantees api_key credentials are persisted as
+ * references only (keychain/opchain/env/shell), never as raw values.
+ */
+export declare class SecureAuthStorage extends AuthStorage {
+    readonly migration: MigrationResult;
+    private readonly authPathValue;
+    private readonly secretStore;
+    /**
+     * Create a secure auth storage instance and run one-time migration.
+     *
+     * @param authPath - Absolute auth.json path
+     * @param options - Optional testing dependencies
+     */
+    constructor(authPath: string, options?: SecureAuthStorageOptions);
+    /**
+     * Persist a provider credential.
+     * API keys are converted to secure references before writing to disk.
+     *
+     * @param provider - Provider ID
+     * @param credential - Credential payload
+     */
+    set(provider: string, credential: AuthCredential): void;
+}
+/**
+ * Fail when auth.json permissions are insecure.
+ *
+ * @param authPath - Absolute auth.json path
+ * @returns void
+ * @throws {Error} When mode is not 0600 on non-Windows platforms
+ */
+export declare function assertSecureAuthFilePermissions(authPath: string): void;
+/**
+ * Persist a provider API key input (raw key or reference) into auth.json.
+ *
+ * @param authPath - Absolute auth.json path
+ * @param provider - Provider ID
+ * @param apiKeyInput - Raw key or secure reference string
+ * @param secretStore - Optional storage backend for raw keys
+ * @returns How the key was persisted (keychain or reference)
+ */
+export declare function persistProviderApiKey(authPath: string, provider: string, apiKeyInput: string, secretStore?: ApiKeySecretStore): PersistedKeyMode;
+/**
+ * One-time migration from plaintext keys to secure references.
+ *
+ * @param authPath - Absolute auth.json path
+ * @param secretStore - Optional storage backend for raw keys
+ * @returns Providers whose key entries changed
+ */
+export declare function migratePlaintextApiKeys(authPath: string, secretStore?: ApiKeySecretStore): MigrationResult;
+/**
+ * Resolve runtime API key overrides from environment variables.
+ *
+ * Supported inputs:
+ * - TALLOW_API_KEY (raw key)
+ * - TALLOW_API_KEY_REF (op:// ref, !command ref, or ENV_VAR_NAME)
+ *
+ * @returns Resolved runtime API key if present
+ * @throws {Error} When both TALLOW_API_KEY and TALLOW_API_KEY_REF are set
+ */
+export declare function resolveRuntimeApiKeyFromEnv(): string | undefined;
+//# sourceMappingURL=auth-hardening.d.ts.map

package/dist/auth-hardening.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-hardening.d.ts","sourceRoot":"","sources":["../src/auth-hardening.ts"],"names":[],"mappings":"AAIA,OAAO,EAEN,KAAK,cAAc,EACnB,WAAW,EACX,MAAM,+BAA+B,CAAC;AASvC,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,0DAA0D;AAC1D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACzC;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IACjD,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;IAYpE;;;;;;OAMG;IACM,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI;CAehE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,iBAA6C,GACxD,gBAAgB,CAMlB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,iBAA6C,GACxD,eAAe,CA0BjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAUhE"}