@blxzer/cursor-trellis 0.1.0

package/dist/migrations/index.js

@@ -0,0 +1,187 @@
+/**
+ * Migration manifests for Trellis versions
+ *
+ * Each version's migrations are stored in separate JSON files under manifests/
+ * Format: manifests/{version}.json (e.g., manifests/0.1.9.json)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { compareVersions } from "../utils/compare-versions.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MANIFESTS_DIR = path.join(__dirname, "manifests");
+/**
+ * Cache for loaded manifests
+ */
+let manifestCache = null;
+/**
+ * Load all migration manifests from JSON files
+ */
+function loadManifests() {
+    if (manifestCache) {
+        return manifestCache;
+    }
+    const manifests = {};
+    // Check if manifests directory exists
+    if (!fs.existsSync(MANIFESTS_DIR)) {
+        manifestCache = manifests;
+        return manifests;
+    }
+    // Load all JSON files from manifests directory
+    const files = fs
+        .readdirSync(MANIFESTS_DIR)
+        .filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+        try {
+            const filePath = path.join(MANIFESTS_DIR, file);
+            const content = fs.readFileSync(filePath, "utf-8");
+            const manifest = JSON.parse(content);
+            // Use version from manifest as key
+            if (manifest.version) {
+                manifests[manifest.version] = manifest;
+            }
+        }
+        catch {
+            // Skip invalid manifest files
+            console.warn(`Warning: Failed to load migration manifest ${file}`);
+        }
+    }
+    manifestCache = manifests;
+    return manifests;
+}
+/**
+ * Get all migrations needed to upgrade from one version to another
+ *
+ * @param fromVersion - Current installed version
+ * @param toVersion - Target version to upgrade to
+ * @returns Array of migration items to apply, in version order
+ */
+export function getMigrationsForVersion(fromVersion, toVersion) {
+    const manifests = loadManifests();
+    // Get all versions that have migrations
+    const versions = Object.keys(manifests).sort(compareVersions);
+    // Filter to versions > fromVersion and <= toVersion
+    const applicableVersions = versions.filter((v) => {
+        const afterFrom = compareVersions(v, fromVersion) > 0;
+        const atOrBeforeTo = compareVersions(v, toVersion) <= 0;
+        return afterFrom && atOrBeforeTo;
+    });
+    // Collect all migrations from applicable versions
+    const allMigrations = [];
+    for (const version of applicableVersions) {
+        const manifest = manifests[version];
+        if (manifest) {
+            allMigrations.push(...manifest.migrations);
+        }
+    }
+    return allMigrations;
+}
+/**
+ * Check if there are any pending migrations between versions
+ */
+export function hasPendingMigrations(fromVersion, toVersion) {
+    return getMigrationsForVersion(fromVersion, toVersion).length > 0;
+}
+/**
+ * Get human-readable summary of pending migrations
+ */
+export function getMigrationSummary(fromVersion, toVersion) {
+    const migrations = getMigrationsForVersion(fromVersion, toVersion);
+    return {
+        renames: migrations.filter((m) => m.type === "rename").length,
+        deletes: migrations.filter((m) => m.type === "delete").length,
+        safeFileDeletes: migrations.filter((m) => m.type === "safe-file-delete")
+            .length,
+    };
+}
+/**
+ * Get all registered migration versions
+ */
+export function getAllMigrationVersions() {
+    const manifests = loadManifests();
+    return Object.keys(manifests).sort(compareVersions);
+}
+/**
+ * Get ALL migrations from all manifests (regardless of version)
+ * Used for detecting orphaned migrations that should have been applied
+ */
+export function getAllMigrations() {
+    const manifests = loadManifests();
+    const allMigrations = [];
+    for (const manifest of Object.values(manifests)) {
+        allMigrations.push(...manifest.migrations);
+    }
+    return allMigrations;
+}
+/**
+ * Clear the manifest cache (useful for testing)
+ */
+export function clearManifestCache() {
+    manifestCache = null;
+}
+/**
+ * Collect every `configSectionsAdded` entry from manifests strictly between
+ * `fromVersion` (exclusive) and `toVersion` (inclusive). Used by `update.ts`
+ * to apply additive config.yaml sections that were introduced after the
+ * user's installed version.
+ */
+export function getConfigSectionsAddedBetween(fromVersion, toVersion) {
+    const manifests = loadManifests();
+    const versions = Object.keys(manifests).sort(compareVersions);
+    const applicableVersions = versions.filter((v) => {
+        const afterFrom = compareVersions(v, fromVersion) > 0;
+        const atOrBeforeTo = compareVersions(v, toVersion) <= 0;
+        return afterFrom && atOrBeforeTo;
+    });
+    const collected = [];
+    for (const version of applicableVersions) {
+        const manifest = manifests[version];
+        if (manifest && Array.isArray(manifest.configSectionsAdded)) {
+            collected.push(...manifest.configSectionsAdded);
+        }
+    }
+    return collected;
+}
+/**
+ * Get aggregated metadata for migrations between versions
+ * Returns combined changelog, breaking status, migrate recommendation, and migration guides
+ */
+export function getMigrationMetadata(fromVersion, toVersion) {
+    const manifests = loadManifests();
+    const versions = Object.keys(manifests).sort(compareVersions);
+    // Filter to versions > fromVersion and <= toVersion
+    const applicableVersions = versions.filter((v) => {
+        const afterFrom = compareVersions(v, fromVersion) > 0;
+        const atOrBeforeTo = compareVersions(v, toVersion) <= 0;
+        return afterFrom && atOrBeforeTo;
+    });
+    const result = {
+        changelog: [],
+        breaking: false,
+        recommendMigrate: false,
+        migrationGuides: [],
+    };
+    for (const version of applicableVersions) {
+        const manifest = manifests[version];
+        if (manifest) {
+            if (manifest.changelog) {
+                result.changelog.push(`v${version}: ${manifest.changelog}`);
+            }
+            if (manifest.breaking) {
+                result.breaking = true;
+            }
+            if (manifest.recommendMigrate) {
+                result.recommendMigrate = true;
+            }
+            if (manifest.migrationGuide) {
+                result.migrationGuides.push({
+                    version,
+                    guide: manifest.migrationGuide,
+                    aiInstructions: manifest.aiInstructions,
+                });
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

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

package/dist/migrations/manifests/0.1.0.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1.0",
+  "description": "v0.1.0 — first public release of @blxzer/cursor-trellis on npm. New package identity (successor to internal @blxzer/trellis test line). Ships Cursor-first workflow templates, router v2 retrieval, trellis-triage rules, and bundled smart-search.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**First public cursor-trellis release.**\n\n- npm packages: `@blxzer/cursor-trellis` + `@blxzer/cursor-trellis-core` at `0.1.0`.\n- Repository: [blxzer77/cursor-trellis](https://github.com/blxzer77/cursor-trellis) (public).\n- Includes router v2 retrieval, Cursor `.cursor/rules` Triage gate, commands-only Cursor surface, session-start hook fixes, and smart-search vendor bundle.\n- Migration manifests from the legacy `@blxzer/trellis` line are archived; this package starts a fresh semver line.\n\n**From legacy `@blxzer/trellis`:** `npm uninstall -g @blxzer/trellis && npm install -g @blxzer/cursor-trellis`, then `trellis update` in each project.",
+  "migrations": [],
+  "notes": "Fresh install: `npm install -g @blxzer/cursor-trellis`. CLI binaries remain `trellis` / `tl`. Users on the old `@blxzer/trellis` npm line should switch package names; there is no in-place semver downgrade on npm."
+}

package/dist/templates/claude/agents/trellis-check.md

@@ -0,0 +1,124 @@
+---
+name: trellis-check
+description: |
+  Code quality check expert. Reviews code changes against specs and self-fixes issues.
+tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: task artifacts, spec, and research files have already been auto-loaded for you above. Proceed with the check work directly.
+- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the selected task path from your dispatch prompt's first line `Selected task: <path>`, then Read `<task-path>/check.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.
+
+## Context
+
+Before checking, read:
+- `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
+- Pre-commit checklist for quality standards
+
+## Core Responsibilities
+
+1. **Get code changes** - Use git diff to get uncommitted code
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
+
+## Quality Gate Adapter
+
+- Reviewer id: `claude-code`.
+- When `implement.md` quality_gates requires a reviewer gate for the current transition, write human-readable evidence in `verify.md` before recording the machine-checkable gate result. Parent/Child integration evidence may also belong in Parent `task-map.md`.
+- Record non-baseline gates with `python ./.trellis/scripts/task.py record-gate <task> --transition <transition> --gate <gate> --result PASS --reviewer claude-code --evidence verify.md`.
+- For FAIL, add `--root-cause implementation-defect|contract-changing-defect|validation-environment-blocker` and `--issue-fingerprint <short-stable-id>`. Route implementation defects back to Execution, contract-changing defects to Planning, and validation blockers to Verification / Review.
+- For SKIPPED, use only explicit user approval: `--skip-approved-by user --skip-reason <reason>`.
+- Never record `baseline-check`; the CLI owns it. Do not pass review bodies, logs, screenshots, or long issue lists through `record-gate` arguments.
+
+## Important
+
+**Fix issues yourself**, don't just report them.
+
+You have write and edit tools, you can modify code directly.
+
+---
+
+## Workflow
+
+### Step 1: Get Changes
+
+```bash
+git diff --name-only  # List changed files
+git diff              # View specific changes
+```
+
+### Step 2: Check Against Specs and Task Artifacts
+
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
+
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
+- Does it follow directory structure conventions
+- Does it follow naming conventions
+- Does it follow code patterns
+- Are there missing types
+- Are there potential bugs
+
+### Step 3: Self-Fix
+
+After finding issues:
+
+1. Fix the issue directly (use edit tool)
+2. Record what was fixed
+3. Continue checking other issues
+
+### Step 4: Run Verification
+
+Run project's lint and typecheck commands to verify changes.
+
+If failed, fix issues and re-run.
+
+---
+
+## Report Format
+
+```markdown
+## Self-Check Complete
+
+### Files Checked
+
+- src/components/Feature.tsx
+- src/hooks/useFeature.ts
+
+### Issues Found and Fixed
+
+1. `<file>:<line>` - <what was fixed>
+2. `<file>:<line>` - <what was fixed>
+
+### Issues Not Fixed
+
+(If there are issues that cannot be self-fixed, list them here with reasons)
+
+### Verification Results
+
+- TypeCheck: Passed
+- Lint: Passed
+
+### Summary
+
+Checked X files, found Y issues, all fixed.
+```

package/dist/templates/claude/agents/trellis-implement.md

@@ -0,0 +1,110 @@
+---
+name: trellis-implement
+description: |
+  Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.
+tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
+## Trellis Context Loading Protocol
+
+Look for the `<!-- trellis-hook-injected -->` marker in your input above.
+
+- **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly.
+- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the selected task path from your dispatch prompt's first line `Selected task: <path>`, then Read `<task-path>/implement.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.
+
+## Context
+
+Before implementing, read:
+- `.trellis/workflow.md` - Project workflow
+- `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
+
+## Core Responsibilities
+
+1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
+2. **Understand task artifacts** - Read prd.md, design.md if present, and implement.md if present
+3. **Implement features** - Write code following specs and task artifacts
+4. **Self-check** - Ensure code quality
+5. **Report results** - Report completion status
+
+## Forbidden Operations
+
+**Do NOT execute these git commands:**
+
+- `git commit`
+- `git push`
+- `git merge`
+
+---
+
+## Workflow
+
+### 1. Understand Specs
+
+Read relevant specs based on task type:
+
+- Spec layers: `.trellis/spec/<package>/<layer>/`
+- Shared guides: `.trellis/spec/guides/`
+
+### 2. Understand Requirements
+
+Read the task's prd.md, design.md if present, and implement.md if present:
+
+- What are the core requirements
+- Key points of technical design
+- Implementation order, validation commands, and rollback points
+
+### 3. Implement Features
+
+- Write code following specs and task artifacts
+- Follow existing code patterns
+- Only do what's required, no over-engineering
+
+### 4. Verify
+
+Run project's lint and typecheck commands to verify changes.
+
+---
+
+## Report Format
+
+```markdown
+## Implementation Complete
+
+### Files Modified
+
+- `src/components/Feature.tsx` - New component
+- `src/hooks/useFeature.ts` - New hook
+
+### Implementation Summary
+
+1. Created Feature component...
+2. Added useFeature hook...
+
+### Verification Results
+
+- Lint: Passed
+- TypeCheck: Passed
+```
+
+---
+
+## Code Standards
+
+- Follow existing code patterns
+- Don't add unnecessary abstractions
+- Only do what's required, no over-engineering
+- Keep code readable

package/dist/templates/claude/agents/trellis-research.md

@@ -0,0 +1,137 @@
+---
+name: trellis-research
+description: |
+  Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the selected task's research/ directory. No code modifications outside that directory.
+tools: Read, Write, Glob, Grep, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session.
+
+---
+
+## Core Responsibilities
+
+1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read)
+2. **External Search** — library docs, API references, best practices (web search)
+3. **Persist** — write each research topic to `{TASK_DIR}/research/<topic>.md`
+4. **Report** — return file paths + one-line summaries to the main agent (not full content)
+
+---
+
+## Workflow
+
+### Step 1: Resolve Selected Task
+
+Run `python3 ./.trellis/scripts/task.py selected --source` → selected task path. If no task is selected, ask the user where to write output; do NOT guess.
+
+Ensure `{TASK_DIR}/research/` exists:
+
+```bash
+mkdir -p <TASK_DIR>/research
+```
+
+### Step 2: Understand Search Request
+
+Classify: internal / external / mixed. Determine scope (global / specific directory) and expected shape (file list / pattern notes / tech comparison).
+
+### Step 3: Execute Search
+
+Run independent searches in parallel (Glob + Grep + web) for efficiency.
+
+### Step 4: Persist Each Topic
+
+For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.
+
+### Step 5: Report to Main Agent
+
+Reply with ONLY:
+
+- List of files written (paths relative to repo root)
+- One-line summary per file
+- Any critical caveats that the main agent needs to know right now
+
+Do NOT paste full research content into the reply. The files are the contract.
+
+---
+
+## Scope Limits (Strict)
+
+### Write ALLOWED
+
+- `{TASK_DIR}/research/*.md` — your own output
+- Creating `{TASK_DIR}/research/` if it doesn't exist (via `mkdir -p`)
+
+### Write FORBIDDEN
+
+- Code files (`src/`, `lib/`, …)
+- Spec files (`.trellis/spec/`) — main agent should use `update-spec` skill instead
+- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.claude/`, `.cursor/`, etc.)
+- Other task directories
+- Any git operation (commit / push / branch / merge)
+
+If the user asks you to edit code, decline and suggest spawning `implement` instead.
+
+---
+
+## File Format
+
+Each `{TASK_DIR}/research/<topic>.md` should follow:
+
+```markdown
+# Research: <topic>
+
+- **Query**: <original query>
+- **Scope**: <internal / external / mixed>
+- **Date**: <YYYY-MM-DD>
+
+## Findings
+
+### Files Found
+
+| File Path | Description |
+|---|---|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Patterns
+
+<describe patterns, cite file:line>
+
+### External References
+
+- [Library X docs](url) — <why relevant, version constraints>
+
+### Related Specs
+
+- `.trellis/spec/xxx.md` — <description>
+
+## Caveats / Not Found
+
+<anything incomplete or uncertain>
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets
+- Persist every topic to its own file
+- Return file paths in your reply, not the full content
+- Mark "not found" explicitly when searches come up empty
+
+### DON'T
+
+- Don't write code or modify files outside `{TASK_DIR}/research/`
+- Don't guess uncertain info
+- Don't paste full research text into the reply (files are the deliverable)
+- Don't propose improvements or critique implementation (that's not your role)

package/dist/templates/claude/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Claude Code templates
+ *
+ * Directory structure:
+ *   claude/
+ *   ├── agents/         # Sub-agent definitions
+ *   └── settings.json   # Settings configuration
+ *
+ * Hooks come from shared-hooks/ (unified with other platforms).
+ */
+export declare const settingsTemplate: string;
+export interface AgentTemplate {
+    name: string;
+    content: string;
+}
+export interface SettingsTemplate {
+    targetPath: string;
+    content: string;
+}
+export declare function getAllAgents(): AgentTemplate[];
+export declare function getSettingsTemplate(): SettingsTemplate;
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/claude/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAa9C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD"}

package/dist/templates/claude/index.js

@@ -0,0 +1,46 @@
+/**
+ * Claude Code templates
+ *
+ * Directory structure:
+ *   claude/
+ *   ├── agents/         # Sub-agent definitions
+ *   └── settings.json   # Settings configuration
+ *
+ * Hooks come from shared-hooks/ (unified with other platforms).
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function readTemplate(relativePath) {
+    return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+function listFiles(dir) {
+    try {
+        return readdirSync(join(__dirname, dir));
+    }
+    catch {
+        return [];
+    }
+}
+export const settingsTemplate = readTemplate("settings.json");
+export function getAllAgents() {
+    const agents = [];
+    const files = listFiles("agents");
+    for (const file of files) {
+        if (file.endsWith(".md")) {
+            const name = file.replace(".md", "");
+            const content = readTemplate(`agents/${file}`);
+            agents.push({ name, content });
+        }
+    }
+    return agents;
+}
+export function getSettingsTemplate() {
+    return {
+        targetPath: "settings.json",
+        content: settingsTemplate,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/claude/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAY9D,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrC,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,UAAU,EAAE,eAAe;QAC3B,OAAO,EAAE,gBAAgB;KAC1B,CAAC;AACJ,CAAC"}