|
| 1 | +# /add-extension - SE-2 Extension Merger (Hybrid) |
| 2 | + |
| 3 | +Claude Code skill for adding Scaffold-ETH-2 extensions to existing projects post-creation. |
| 4 | + |
| 5 | +Uses a **hybrid approach**: a Node.js script handles deterministic operations (fetch, copy, package.json merge), while Claude handles intelligent file merging (.args.mjs processing). |
| 6 | + |
| 7 | +**Requirements:** SE-2 project root, Git, Yarn |
| 8 | + |
| 9 | +## Quick Start |
| 10 | + |
| 11 | +```bash |
| 12 | +# In SE-2 project root |
| 13 | +/add-extension erc-20 |
| 14 | + |
| 15 | +# Preview changes first |
| 16 | +/add-extension subgraph --dry-run |
| 17 | + |
| 18 | +# Choose framework explicitly |
| 19 | +/add-extension ponder -s hardhat |
| 20 | +``` |
| 21 | + |
| 22 | +## Options |
| 23 | + |
| 24 | +| Flag | Short | Description | |
| 25 | +|------|-------|-------------| |
| 26 | +| `--list` | `-L` | List all available extensions with repo info | |
| 27 | +| `--dry-run` | `-d` | Preview changes without applying | |
| 28 | +| `--verbose` | `-v` | Show detailed error messages | |
| 29 | +| `--local <path>` | `-l` | Use local extension repo path | |
| 30 | +| `--solidity-framework <name>` | `-s` | Choose hardhat/foundry (only if project has neither) | |
| 31 | + |
| 32 | +## Available Extensions |
| 33 | + |
| 34 | +Fetched dynamically from [create-eth](https://github.com/scaffold-eth/create-eth/blob/main/src/extensions/create-eth-extensions.ts). |
| 35 | + |
| 36 | +Run `/add-extension --list` for current list with repository details. |
| 37 | + |
| 38 | +## How It Works |
| 39 | + |
| 40 | +1. **Validate** - Checks for SE-2 project (scaffold.config.ts) |
| 41 | +2. **Registry** - Fetches extension config from create-eth registry |
| 42 | +3. **Fetch** - Clones extension branch via git |
| 43 | +4. **Framework** - Auto-detects hardhat/foundry from project |
| 44 | +5. **Analyze** - Compares extension files vs project, reads .args.mjs as raw text |
| 45 | +6. **Deterministic merge** - Script copies new files, merges package.json, registers workspaces |
| 46 | +7. **AI merge** - Script outputs structured JSON tasks; Claude reads target files and applies .args.mjs exports intelligently |
| 47 | + |
| 48 | +### File Handling |
| 49 | + |
| 50 | +| File Type | Handler | Action | |
| 51 | +|-----------|---------|--------| |
| 52 | +| New files | Script | Copied directly | |
| 53 | +| package.json | Script | Auto-merged (deps, scripts) | |
| 54 | +| Workspaces | Script | Registered in root package.json | |
| 55 | +| `.args.mjs` files | Claude | Reads exports, modifies target files | |
| 56 | +| `.template.mjs` files | Claude | Extracts content, writes/merges target | |
| 57 | +| File conflicts | Claude | Reads both versions, merges intelligently | |
| 58 | + |
| 59 | +## Architecture |
| 60 | + |
| 61 | +``` |
| 62 | +SKILL.md - Skill instructions (comprehensive .args.mjs guide) |
| 63 | +skill.mjs - CLI entry point, orchestration, JSON output |
| 64 | +lib/validator.mjs - SE-2 detection, registry fetching |
| 65 | +lib/fetcher.mjs - Git clone / local path handling |
| 66 | +lib/analyzer.mjs - File categorization, .args.mjs raw reading |
| 67 | +lib/merger.mjs - Deterministic operations (copy, package.json merge) |
| 68 | +lib/constants.mjs - Registry URLs, fallback extensions |
| 69 | +``` |
| 70 | + |
| 71 | +## Development |
| 72 | + |
| 73 | +```bash |
| 74 | +# Test locally with dry-run |
| 75 | +node .claude/skills/add-extension/skill.mjs erc-20 --dry-run |
| 76 | + |
| 77 | +# Test with local extension repo |
| 78 | +/add-extension erc-721 --local ../create-eth-extensions --dry-run |
| 79 | +``` |
| 80 | + |
| 81 | +## Source Repositories |
| 82 | + |
| 83 | +| Repo | Purpose | |
| 84 | +|------|---------| |
| 85 | +| [create-eth](https://github.com/scaffold-eth/create-eth) | SE-2 CLI, extension registry | |
| 86 | +| [create-eth-extensions](https://github.com/scaffold-eth/create-eth-extensions) | Default extension source (each extension = git branch) | |
0 commit comments