copperhead 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,87 @@
+# copperhead
+
+**Cursor for circuit boards.** An AI agent that designs, documents, and validates real PCBs from a prompt, working directly on existing KiCad repositories.
+
+> **Status: early (v0.1).** Phase 1 is implemented and the CLI runs. The [technical specification](openspec/specs/SPEC.md) is the source of truth; expect the surface to move before 1.0.
+
+## What it is
+
+An AI product-development agent for hardware: from a product brief to manufacturable files, firmware, and a build plan.
+
+- **`copperhead create`**: full pipeline from a natural-language brief: spec, architecture, part selection, schematic, first-draft layout, then gerbers, firmware scaffold, and dev plan.
+- **`copperhead do "<change>"`**: operates on an existing KiCad repo the way a coding agent operates on a codebase.
+
+It reads and edits real `.kicad_sch` / `.kicad_pcb` files (s-expression text), maintains markdown design docs as memory, propagates every change across all artifacts that reference it, and verifies its own work by running `kicad-cli` ERC/DRC until the checks pass.
+
+## How it works
+
+It's a loop, and it looks a lot like pair-programming, except the codebase is a circuit board.
+
+1. **Start from the docs.** Every decision lives in the design docs, so the agent reads those first and knows the whole design, not just the part in front of it.
+2. **Talk through the change.** Describe what you want ("add an external key jack", "cut the sleep current"). The agent proposes the parts and circuit; you push back until the reasoning holds up.
+3. **Edit the real files.** The agent writes changes straight into the KiCad schematic and the design docs, using the same part names and net names everywhere so nothing drifts.
+4. **Propagate.** Change one value, like a charge current or a pin, and it carries across every doc and schematic that references it. The boring, easy-to-get-wrong step is the one the agent is best at.
+5. **Check the work.** The agent runs ERC/DRC, reads the errors back, and fixes them. Nothing is "done" until the tools agree.
+6. **Write down why.** Every real decision gets a one-line reason next to it, so the next change doesn't quietly undo it.
+
+Two invariants make this trustworthy:
+
+1. **Nothing starts without a spec.** The agent cannot touch a KiCad file until a validated change proposal exists; the edit tools are structurally unavailable until it does. Every edit is traceable to a documented intent.
+2. **Nothing is "done" until the tools agree.** Every file mutation is followed by an ERC/DRC run before the agent reports success.
+
+Spec-gated in, verification-gated out: the design can't drift from its requirements, because drift is a build failure.
+
+## CLI
+
+```text
+copperhead init [--path hardware/]   # scaffold docs/ from an existing schematic; idempotent
+copperhead do "<change request>"     # the core loop: propose, edit, verify, propagate, commit
+copperhead check                     # ERC + DRC + doc-drift + spec validation; no LLM calls (alias: verify)
+copperhead sync [--dry-run]          # verify the whole design state, resolve drift
+copperhead create --brief brief.md   # brief → full output package
+```
+
+Global flags: `--repo <path>` (default: cwd) and `--json` for machine-readable output. `do` and `create` take `--model` and `--interactive`; `do` also takes `--dry-run`, `--max-turns`, and `--allow-dirty`.
+
+Nothing is a black box: decisions land in an append-only `docs/DECISIONS.md`, every run writes a human-readable summary next to its transcript, and a per-run `docs/CHANGELOG.md` narrates the design history.
+
+## What it is not
+
+- **Not an autorouter.** Routing stays human or delegated; copperhead produces the DRC-clean draft that layout tools optimize from.
+- **Not a new editor.** No walled garden; your KiCad install remains the editor.
+- **Not the engineer of record.** A human signs off; the agent never claims a design is fab-ready beyond "ERC/DRC clean".
+
+## Install
+
+```bash
+npm install -g copperhead   # or: npx copperhead check
+```
+
+### Requirements
+
+- Node.js ≥ 20
+- [KiCad](https://www.kicad.org/) ≥ 8 with `kicad-cli` on PATH
+- An OpenAI or Anthropic API key (env var only), except for `check`, which never calls an LLM
+
+## Maturity
+
+Honest read of where v0.1 stands, so you can calibrate before pointing this at a board you care about:
+
+- **Solid.** `init` and `check`/`verify` are deterministic, LLM-free, and covered by the offline test suite against a real KiCad fixture: scaffolding, ERC/DRC, the s-expression reader, drift detection, and fab export all run green in CI.
+- **Implemented, not yet proven.** The agent loop (`do`, `sync --resolve`, `create`) is complete and structurally gated, but its acceptance tests need a live model and have not been observed passing end to end. Expect rough edges.
+- **Always.** Every mutation runs inside a git snapshot and rolls back if verification fails, so the worst case is a no-op commit, not a mangled schematic. Work on a branch anyway.
+
+## Open source
+
+The entire tool (agent core, prompts, tools) is public under Apache-2.0, built on an open stack (KiCad, kicad-cli, [OpenSpec](https://github.com/Fission-AI/OpenSpec)). Everything it produces is plain markdown and JSON in your own repo: no proprietary formats, no lock-in. This is a Chouhan Industries project, and the same commitment that puts every hardware schematic in public applies to the tool that designs them.
+
+## Project layout
+
+- [`src/`](src/): CLI ([`cli.ts`](src/cli.ts), [`commands/`](src/commands/)), the provider-agnostic agent loop ([`agent/`](src/agent/)), the `kicad-cli` wrapper and s-expression reader ([`kicad/`](src/kicad/)), and doc/constraint memory ([`memory/`](src/memory/))
+- [`test/`](test/): offline suite plus [`fixtures/`](test/fixtures/), a tiny known-good KiCad project
+- [`openspec/specs/SPEC.md`](openspec/specs/SPEC.md): the full technical specification, including binary acceptance criteria
+- [`openspec/changes/build-copperhead-phase-1/`](openspec/changes/build-copperhead-phase-1/): the implementation plan with proposal, design decisions, capability specs, and task checklist
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/agent/filetools.js

@@ -0,0 +1,118 @@
+import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { resolveInRepo, isKicadFile } from '../util/paths.js';
+export async function toolReadFile(repoRoot, p, startLine, endLine) {
+    const abs = resolveInRepo(repoRoot, p);
+    const text = await readFile(abs, 'utf8');
+    if (startLine === undefined)
+        return text;
+    const lines = text.split('\n');
+    const from = Math.max(1, startLine);
+    const to = Math.min(lines.length, endLine ?? lines.length);
+    return lines
+        .slice(from - 1, to)
+        .map((l, i) => `${from + i}: ${l}`)
+        .join('\n');
+}
+/** New files only; refuses to overwrite anything and to create KiCad files (SPEC §4.2). */
+export async function toolWriteFile(repoRoot, p, content) {
+    const abs = resolveInRepo(repoRoot, p);
+    if (isKicadFile(abs)) {
+        throw new Error(`write_file refuses KiCad files (${p}); use edit_file with anchors instead`);
+    }
+    if (existsSync(abs)) {
+        throw new Error(`write_file refuses to overwrite existing file ${p}; use edit_file`);
+    }
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeFile(abs, content, 'utf8');
+    return `wrote ${p}`;
+}
+/**
+ * Exact-match anchored replace; fails with an actionable error unless unique.
+ * `replaceAll` replaces every occurrence (the rename case, AC-3.1) while still
+ * being a surgical text edit on the s-expression source.
+ */
+export async function toolEditFile(repoRoot, p, oldString, newString, replaceAll = false) {
+    const abs = resolveInRepo(repoRoot, p);
+    const text = await readFile(abs, 'utf8');
+    const first = text.indexOf(oldString);
+    if (first === -1) {
+        throw new Error(`edit_file: anchor not found in ${p}; re-read the file and use an exact excerpt`);
+    }
+    const count = text.split(oldString).length - 1;
+    if (replaceAll) {
+        await writeFile(abs, text.split(oldString).join(newString), 'utf8');
+        return `edited ${p} (${count} occurrence(s) replaced)`;
+    }
+    if (count > 1) {
+        throw new Error(`edit_file: anchor matched ${count} times in ${p}; widen the anchor with surrounding lines until it is unique, or pass replace_all: true to replace every occurrence`);
+    }
+    await writeFile(abs, text.slice(0, first) + newString + text.slice(first + oldString.length), 'utf8');
+    return `edited ${p}`;
+}
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', '.copperhead']);
+export function globToRegex(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        if (glob.startsWith('**/', i)) {
+            out += '(?:.*/)?'; // zero or more directories
+            i += 2;
+        }
+        else if (glob.startsWith('**', i)) {
+            out += '.*';
+            i += 1;
+        }
+        else if (glob[i] === '*') {
+            out += '[^/]*';
+        }
+        else if (glob[i] === '?') {
+            out += '.';
+        }
+        else {
+            out += glob[i].replace(/[.+^${}()|[\]\\]/, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/** ripgrep-style regex search implemented natively (no rg dependency). */
+export async function toolSearch(repoRoot, pattern, glob, maxMatches = 200) {
+    const re = new RegExp(pattern);
+    const globRe = glob ? globToRegex(glob) : null;
+    const matches = [];
+    async function walk(dir) {
+        if (matches.length >= maxMatches)
+            return;
+        for (const entry of await readdir(dir)) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const abs = path.join(dir, entry);
+            const rel = path.relative(repoRoot, abs);
+            const st = await stat(abs);
+            if (st.isDirectory()) {
+                await walk(abs);
+            }
+            else if (st.size < 5_000_000 && (!globRe || globRe.test(rel))) {
+                let text;
+                try {
+                    text = await readFile(abs, 'utf8');
+                }
+                catch {
+                    continue;
+                }
+                if (text.includes('\u0000'))
+                    continue; // binary
+                const lines = text.split('\n');
+                for (let i = 0; i < lines.length && matches.length < maxMatches; i++) {
+                    if (re.test(lines[i]))
+                        matches.push({ file: rel, line: i + 1, text: lines[i].trim() });
+                }
+            }
+            if (matches.length >= maxMatches)
+                return;
+        }
+    }
+    await walk(repoRoot);
+    return matches;
+}
+//# sourceMappingURL=filetools.js.map

package/dist/agent/filetools.js.map

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

package/dist/agent/ledger.js

@@ -0,0 +1,43 @@
+export class ObligationsLedger {
+    open = [];
+    add(kind, detail, openedBy) {
+        if (!this.open.some((o) => o.kind === kind && o.detail === detail)) {
+            this.open.push({ kind, detail, openedBy });
+        }
+    }
+    clear(kind, detail) {
+        this.open = this.open.filter((o) => !(o.kind === kind && (detail === undefined || o.detail === detail)));
+    }
+    /** A KiCad edit re-opens verification obligations even if previously cleared. */
+    onKicadEdit(file) {
+        this.add('erc', 'ERC must pass after schematic edits', file);
+        if (file.endsWith('.kicad_pcb'))
+            this.add('drc', 'DRC must pass after board edits', file);
+        this.add('drift', 'check_drift must run clean after KiCad edits', file);
+        this.add('changelog', 'CHANGELOG.md entry for this run', file);
+    }
+    onDocEdit(file) {
+        this.add('drift', 'check_drift must run clean after doc edits', file);
+    }
+    onConstraintChange(constraintKey, affects) {
+        this.add('constraint-dual-write', constraintKey, constraintKey);
+        for (const item of affects) {
+            this.add('affects-revisit', `${constraintKey} affects ${item}`, constraintKey);
+        }
+    }
+    onDecision(summary) {
+        this.add('decision-log', summary, 'decision');
+    }
+    get openObligations() {
+        return this.open;
+    }
+    get isClear() {
+        return this.open.length === 0;
+    }
+    describe() {
+        if (this.isClear)
+            return 'all sync obligations satisfied';
+        return this.open.map((o) => `- [${o.kind}] ${o.detail} (opened by ${o.openedBy})`).join('\n');
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/agent/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/agent/ledger.ts"],"names":[],"mappings":"AAoBA,MAAM,OAAO,iBAAiB;IACpB,IAAI,GAAiB,EAAE,CAAC;IAEhC,GAAG,CAAC,IAAoB,EAAE,MAAc,EAAE,QAAgB;QACxD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAoB,EAAE,MAAe;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAC3E,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,WAAW,CAAC,IAAY;QACtB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,qCAAqC,EAAE,IAAI,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;QAC1F,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,8CAA8C,EAAE,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,iCAAiC,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;IAED,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,4CAA4C,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,kBAAkB,CAAC,aAAqB,EAAE,OAAiB;QACzD,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QAChE,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,GAAG,aAAa,YAAY,IAAI,EAAE,EAAE,aAAa,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,gCAAgC,CAAC;QAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,eAAe,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChG,CAAC;CACF"}