openclaw-node-harness 2.0.0

package/skills/crypto-price/ARCHITECTURE.md

@@ -0,0 +1,437 @@
+# Architecture & Design Decisions
+
+**Version:** 1.0  
+**Date:** 2026-01-27  
+**Author:** Research & audit by Clawd 🦊
+
+---
+
+## Why This Document Exists
+
+This document explains why `crypto-price` does **not** use template generation for wrapper skills, and why the current architecture is optimal.
+
+**TL;DR:** No refactoring needed. System already DRY.
+
+---
+
+## System Overview
+
+### What We Have
+
+**1 Core Script:**
+- `scripts/get_price_chart.py` (~800 lines)
+- All logic: API calls, caching, chart generation, error handling
+
+**30 Wrapper Skills:**
+- `../btc/SKILL.md`, `../eth/SKILL.md`, `../hype/SKILL.md`, ... (28 token wrappers)
+- `../cryptochart/SKILL.md` (universal fallback)
+- `../token/SKILL.md` (universal `/token ANY` command)
+- Each wrapper = 35 lines: metadata + symbol + "call core script"
+
+**Total duplication:** Zero. All wrappers call same script.
+
+---
+
+## Why No Template Generation?
+
+### The Proposal (Rejected)
+
+**Idea:** Generate wrappers from template to reduce duplication.
+
+**Reality:** No duplication exists.
+
+**Current wrapper:**
+```yaml
+---
+name: BTC
+description: Slash command for Bitcoin token price + chart.
+metadata: {"clawdbot":{"emoji":"📈","requires":{"bins":["python3"]}}}
+---
+
+# Bitcoin Price
+
+## Usage
+/BTC
+/BTC 12h
+
+## Execution
+python3 {baseDir}/../crypto-price/scripts/get_price_chart.py BTC
+
+Return JSON output. Attach chart_path PNG.
+Return text_plain with no markdown.
+```
+
+**Lines:** 35  
+**Logic:** 0 (just metadata + symbol)
+
+### Comparison: Manual vs Template
+
+**Current (no template):**
+```bash
+# Add new token
+cp btc/SKILL.md pepe/SKILL.md
+vim pepe/SKILL.md  # Edit 3 places: name, description, symbol
+# Done (2 minutes)
+```
+
+**With template:**
+```bash
+# Maintain template file
+vim crypto-price/templates/token_wrapper.md
+# Maintain generator script
+vim crypto-price/scripts/generate_wrapper.sh
+# Generate wrapper
+./generate_wrapper.sh PEPE "Pepe Coin" pepe
+# Debug if generator fails
+# Done (5 minutes + maintenance overhead)
+```
+
+**Winner:** Current approach (simpler, fewer files, easier to understand)
+
+---
+
+## Maintenance Model
+
+### Bug Fix Scenario
+
+**Bug:** Chart generation broken
+
+**Fix location:** `scripts/get_price_chart.py` (1 file)
+
+**Impact:** All 30 wrapper skills fixed instantly
+
+**Wrapper changes:** 0 files
+
+**Time:** 10 minutes (edit core script only)
+
+### Adding New Token
+
+**Process:**
+1. `cp ../btc/SKILL.md ../pepe/SKILL.md`
+2. Edit 3 lines: `name: PEPE`, description, symbol
+3. Done
+
+**Time:** 2 minutes
+
+**No template needed.**
+
+---
+
+## Architecture Principles
+
+### 1. Single Source of Truth
+
+**Core script** = all logic  
+**Wrappers** = metadata only
+
+**Result:** Bug fix in 1 place affects all 30 skills.
+
+### 2. Minimal Wrappers
+
+**Current:** 35 lines per wrapper  
+**Can't reduce further** without losing readability
+
+**Template would add complexity** (template file + generator script + docs) without reducing wrapper size.
+
+### 3. Clear Separation of Concerns
+
+**Core script:**
+- API calls (Hyperliquid, CoinGecko)
+- Caching (300s TTL)
+- Chart generation (matplotlib)
+- Error handling (retries, fallbacks)
+
+**Wrappers:**
+- Clawdbot metadata (name, description, emoji)
+- Trigger conditions (slash command, keywords)
+- Symbol mapping (e.g., `gld` → `GOLD-USDC`)
+
+**Clawdbot:**
+- Skill matching (user input → skill)
+- Execution (run core script)
+- Reply formatting (text + image)
+
+### 4. Easy to Extend
+
+**New token:** Copy wrapper + edit 3 lines
+
+**No script maintenance needed.**
+
+---
+
+## Data Flow
+
+```
+User: /hype 12h
+  ↓
+Clawdbot: Match skill hype/SKILL.md
+  ↓
+Execute: python3 .../get_price_chart.py HYPE 12h
+  ↓
+Core Script:
+  1. Parse duration
+  2. Try Hyperliquid API
+  3. Fallback to CoinGecko
+  4. Check cache (5 min TTL)
+  5. Generate chart (matplotlib)
+  6. Return JSON
+  ↓
+Clawdbot: Send text + attach image
+  ↓
+User sees: Text + Chart
+```
+
+**Single entry point:** Core script  
+**Single maintenance location:** Core script
+
+---
+
+## Testing Results
+
+**Test 1: HYPE (Hyperliquid)**
+```bash
+$ python3 get_price_chart.py HYPE
+{"symbol": "HYPE", "price": 27.31, "text_plain": "HYPE: $27.31 USD ⬆️ +22.60% over 24h"}
+```
+✅ Works
+
+**Test 2: BTC 12h**
+```bash
+$ python3 get_price_chart.py BTC 12h
+{"symbol": "BTC", "price": 88263.00, "text_plain": "BTC: $88263.00 USD ⬆️ +0.53% over 12h"}
+```
+✅ Works
+
+**Test 3: Rate Limit**
+```bash
+$ python3 get_price_chart.py PEPE
+{"error": "price lookup failed", "details": "HTTP Error 429: Too Many Requests"}
+```
+✅ Graceful error
+
+**Test 4: Wrapper Consistency**
+```bash
+$ diff -u btc/SKILL.md eth/SKILL.md
+-name: BTC
++name: ETH
+-# Bitcoin Price
++# Ethereum Price
+-get_price_chart.py BTC
++get_price_chart.py ETH
+```
+✅ Identical structure (only symbol differs)
+
+---
+
+## Risks Assessment
+
+### Risk 1: Core Script Failure
+**Scenario:** Bug in `get_price_chart.py` → all 30 skills break
+
+**Likelihood:** LOW (stable for months)
+
+**Mitigation:**
+- Error handling in script
+- Caching reduces API dependency
+- Graceful degradation (price without chart if matplotlib fails)
+
+**Impact:** HIGH (all token commands broken)
+
+**Note:** Same risk exists regardless of wrapper structure. Not a refactoring issue.
+
+### Risk 2: API Rate Limits
+**Scenario:** CoinGecko 50 calls/min exceeded
+
+**Likelihood:** MEDIUM (confirmed during testing)
+
+**Mitigation:**
+- 5-minute cache (TTL 300s)
+- Hyperliquid fallback
+- Retry logic with backoff
+
+**Impact:** LOW (temporary failure, user retries in 5 min)
+
+### Risk 3: Template Maintenance
+**Scenario:** Template generator breaks
+
+**Likelihood:** ZERO (no template exists)
+
+**Current approach:** Manual copy-paste (simpler, no generator to maintain)
+
+---
+
+## Comparison: Current vs Template System
+
+| Aspect | Current | With Template |
+|--------|---------|---------------|
+| Core logic files | 1 | 1 |
+| Template files | 0 | 1 |
+| Generator scripts | 0 | 1 |
+| Wrapper files | 30 | 30 |
+| Lines per wrapper | 35 | 35 (same) |
+| Add new token | 2 min (copy + edit) | 5 min (run generator) |
+| Maintenance overhead | Low (1 file) | Medium (3 files) |
+| Debugging complexity | Low | Medium (script + template) |
+| Learning curve | Low | Medium |
+
+**Winner:** Current approach
+
+---
+
+## Alternatives Considered
+
+### Alternative 1: Full Template Generation
+**Idea:** Template file + generator script
+
+**Pros:**
+- Slightly more "automated"
+
+**Cons:**
+- More files to maintain (template + script + docs)
+- More complexity (scripting, error handling)
+- No reduction in wrapper size (still 35 lines)
+- Slower than copy-paste
+
+**Decision:** Rejected (adds complexity without benefit)
+
+### Alternative 2: Single Universal Skill
+**Idea:** Remove all wrappers, use only `/token ANY`
+
+**Pros:**
+- Fewer files
+
+**Cons:**
+- Worse UX (users must remember symbols)
+- No autocomplete for popular tokens
+- Loses slash command convenience (`/btc` vs `/token BTC`)
+
+**Decision:** Rejected (UX downgrade)
+
+### Alternative 3: Current System (Winner)
+**Idea:** 1 core script + minimal wrappers (copy-paste to add tokens)
+
+**Pros:**
+- Simple (no template complexity)
+- Fast (copy + edit 3 lines = 2 min)
+- Easy to understand (no hidden generation logic)
+- Zero duplication (all use same script)
+
+**Cons:**
+- None
+
+**Decision:** Keep current system
+
+---
+
+## Common Misconceptions
+
+### Misconception 1: "25 duplicate skills"
+**Reality:** 28 wrappers + 2 utility skills, **zero logic duplication**
+
+All wrappers call same script. No duplicated code.
+
+### Misconception 2: "Maintenance nightmare"
+**Reality:** Bug fix in 1 place (core script) = instant fix for all 30 skills
+
+Wrappers never need maintenance (only core script).
+
+### Misconception 3: "Template would reduce duplication"
+**Reality:** No duplication exists to reduce
+
+Wrappers are metadata-only (35 lines). Template wouldn't make them smaller.
+
+### Misconception 4: "Hard to add new tokens"
+**Reality:** 2 minutes to copy + edit 3 lines
+
+Simpler than maintaining template + generator.
+
+---
+
+## Optional Improvements
+
+**None required, but if desired:**
+
+### 1. Add Unit Tests
+**File:** `tests/test_get_price_chart.py`
+
+**Why:**
+- Catch bugs before deployment
+- Validate API changes
+
+**Effort:** 2-3 hours
+
+### 2. Add Helper Script
+**File:** `scripts/add_token.sh`
+
+**Usage:**
+```bash
+./add_token.sh PEPE "Pepe Coin" pepe
+# Creates ../pepe/SKILL.md from btc template
+```
+
+**Why:**
+- Slightly faster than manual copy-paste
+- Reduces typos
+
+**Effort:** 30 minutes
+
+**Note:** Still simpler than full template system.
+
+### 3. Documentation
+**File:** This document (`ARCHITECTURE.md`)
+
+**Why:**
+- Explain design decisions
+- Prevent future "refactoring" attempts
+
+**Effort:** Done
+
+---
+
+## Conclusion
+
+### Summary
+
+**System is optimal as-is:**
+
+✅ 1 core script (all logic)  
+✅ 30 minimal wrappers (metadata only)  
+✅ Zero duplication  
+✅ Easy maintenance (bug fix in 1 place)  
+✅ Easy to extend (copy + edit 3 lines)
+
+**Template generation would:**
+
+❌ Add complexity (more files to maintain)  
+❌ Slow down token addition (scripting overhead)  
+❌ Not reduce wrapper size (still 35 lines)  
+❌ Not improve maintenance (already 1 bug fix location)
+
+### Recommendation
+
+**Action:** Keep current system. No refactoring needed.
+
+**Rationale:** Current approach is simpler, faster, and easier to understand than template generation.
+
+---
+
+## References
+
+**Core Script:**
+- `scripts/get_price_chart.py` (~800 lines)
+- Git repo: `git@github.com:evgyur/crypto-price.git`
+
+**Wrapper Example:**
+- `../btc/SKILL.md` (35 lines)
+
+**Documentation:**
+- `README.md` (user guide)
+- `ARCHITECTURE.md` (this document)
+
+**Research:**
+- `/home/eyurc/clawd/memory/2026-01-27-crypto-refactor-research.md` (full analysis)
+
+---
+
+**Last Updated:** 2026-01-27  
+**Status:** Stable, no changes planned

package/skills/crypto-price/README.md

@@ -0,0 +1,194 @@
+# 📈 Crypto Price & Chart
+
+A Clawdbot skill for fetching cryptocurrency token prices and generating beautiful candlestick charts.
+
+## Features
+
+- 🚀 **Fast price lookup** via CoinGecko and Hyperliquid APIs
+- 📊 **Candlestick charts** with dark theme (8x8 square format)
+- ⚡ **Smart caching** (5-minute TTL for price data)
+- 🎯 **Multiple data sources** (Hyperliquid preferred for supported tokens, CoinGecko fallback)
+- 📱 **Flexible timeframes** (30m, 3h, 12h, 24h, 2d)
+
+## Installation
+
+### Via ClawdHub
+
+```bash
+clawdhub install evgyur/crypto-price
+```
+
+### Manual Installation
+
+1. Clone or copy this skill to your Clawdbot workspace:
+   ```bash
+   cd ~/.clawdbot/workspace/skills
+   git clone https://github.com/evgyur/crypto-price.git
+   ```
+
+2. Ensure Python 3 is installed:
+   ```bash
+   python3 --version
+   ```
+
+3. Install required Python packages:
+   ```bash
+   pip install matplotlib
+   ```
+
+4. Verify installation:
+   ```bash
+   clawdbot skills info crypto-price
+   ```
+
+## Usage
+
+### As a Skill
+
+The skill is automatically triggered when users ask for:
+- Token prices
+- Crypto charts
+- Cryptocurrency market data
+
+### Direct Script Usage
+
+```bash
+python3 scripts/get_price_chart.py <SYMBOL> [duration]
+```
+
+**Examples:**
+```bash
+# Get HYPE price and 24h chart
+python3 scripts/get_price_chart.py HYPE
+
+# Get Bitcoin price and 12h chart
+python3 scripts/get_price_chart.py BTC 12h
+
+# Get Ethereum price and 3h chart
+python3 scripts/get_price_chart.py ETH 3h
+
+# Get Solana price and 30m chart
+python3 scripts/get_price_chart.py SOL 30m
+
+# Get Cardano price and 2d chart
+python3 scripts/get_price_chart.py ADA 2d
+```
+
+### Duration Format
+
+- `30m` - 30 minutes
+- `3h` - 3 hours
+- `12h` - 12 hours
+- `24h` - 24 hours (default)
+- `2d` - 2 days
+
+## Output Format
+
+The script returns JSON with the following structure:
+
+```json
+{
+  "symbol": "BTC",
+  "token_id": "bitcoin",
+  "source": "coingecko",
+  "currency": "USD",
+  "hours": 24.0,
+  "duration_label": "24h",
+  "candle_minutes": 15,
+  "price": 89946.00,
+  "price_usdt": 89946.00,
+  "change_period": -54.00,
+  "change_period_percent": -0.06,
+  "chart_path": "/tmp/crypto_chart_BTC_1769142011.png",
+  "text": "BTC: $89946.00 USD (-0.06% over 24h)",
+  "text_plain": "BTC: $89946.00 USD (-0.06% over 24h)"
+}
+```
+
+## Chart Generation
+
+- **Type**: Candlestick (OHLC)
+- **Size**: 8x8 inches (square format)
+- **Theme**: Dark (#121212 background)
+- **Colors** (default mode): 
+  - Grey (#B0B0B0 / #606060) normal candles
+  - Cyan (#00FFFF) bullish swing reversals (3 candles after swing low)
+  - Magenta (#FF00FF) bearish swing reversals (3 candles after swing high)
+  - Gold (#FFD54F) / Light Blue (#90CAF9) absolute high/low markers
+- **Colors** (gradient mode, add `gradient` flag): 
+  - Green gradient (#84dc58 → #336d16) bullish candles
+  - Blue-purple gradient (#6c7ce4 → #544996) bearish candles
+- **Features**:
+  - Fractal swing high/low detection (true pivots, configurable window)
+  - Volume bars (when available from API)
+  - Last price highlighted on Y-axis
+  - Tomorrow font for crisp rendering
+- **Output**: PNG files saved to `/tmp/crypto_chart_{SYMBOL}_{timestamp}.png`
+
+## Data Sources
+
+1. **Hyperliquid API** (`https://api.hyperliquid.xyz/info`)
+   - Preferred for HYPE and other Hyperliquid tokens
+   - Provides real-time price data and candlestick data
+
+2. **CoinGecko API** (`https://api.coingecko.com/api/v3/`)
+   - Fallback for all other tokens
+   - Supports price lookup, market charts, and OHLC data
+
+## Caching
+
+Price data is cached for 300 seconds (5 minutes) to reduce API calls:
+- Cache files: `/tmp/crypto_price_*.json`
+- Automatic cache invalidation after TTL
+
+## Supported Tokens
+
+Works with any token supported by CoinGecko or Hyperliquid:
+- **Popular tokens**: BTC, ETH, SOL, ADA, DOT, LINK, MATIC, AVAX, ATOM, ALGO, XLM, XRP, LTC, BCH, ETC, TRX, XMR, DASH, ZEC, EOS, BNB, DOGE, SHIB, UNI, AAVE
+- **Hyperliquid tokens**: HYPE, and other tokens listed on Hyperliquid
+
+## Requirements
+
+- Python 3.6+
+- `matplotlib` library
+- Internet connection for API calls
+
+## Dependencies
+
+```bash
+pip install matplotlib
+```
+
+## License
+
+MIT
+
+## Author
+
+Created for Clawdbot community. Originally part of Clawdbot bundled skills, restored and enhanced.
+
+## Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## Related Skills
+
+This skill works with slash command skills:
+- `/hype` - HYPE token price and chart
+- `/token <SYMBOL>` - Any token price and chart
+- `/btc`, `/eth`, `/sol`, etc. - Popular tokens
+
+## Links
+
+- [GitHub Repository](https://github.com/evgyur/crypto-price)
+- [ClawdHub](https://clawdhub.com/evgyur/crypto-price)
+- [Clawdbot Documentation](https://docs.clawd.bot)
+
+## Changelog
+
+### v1.0.0
+- Initial release
+- Support for CoinGecko and Hyperliquid APIs
+- Candlestick chart generation
+- Smart caching system
+- Multiple timeframe support

package/skills/crypto-price/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: crypto-price
+description: "Get cryptocurrency token price and generate candlestick charts via CoinGecko API or Hyperliquid API. Use when user asks for token price, crypto price, price chart, or cryptocurrency market data."
+triggers:
+  - "crypto price"
+  - "token price"
+  - "bitcoin price"
+  - "price chart"
+  - "what is ETH trading at"
+negative_triggers:
+  - "stock price"
+  - "forex rates"
+  - "smart contract"
+  - "blockchain transaction"
+metadata: {"clawdbot":{"emoji":"📈","requires":{"bins":["python3"]}}}
+---
+
+# Crypto Price & Chart
+
+Get cryptocurrency token price and generate candlestick charts.
+
+## Usage
+
+Execute the script with token symbol and optional duration:
+
+```bash
+python3 {baseDir}/scripts/get_price_chart.py <SYMBOL> [duration]
+```
+
+**Examples:**
+- `python3 {baseDir}/scripts/get_price_chart.py HYPE`
+- `python3 {baseDir}/scripts/get_price_chart.py HYPE 12h`
+- `python3 {baseDir}/scripts/get_price_chart.py BTC 3h`
+- `python3 {baseDir}/scripts/get_price_chart.py ETH 30m`
+- `python3 {baseDir}/scripts/get_price_chart.py SOL 2d`
+
+**Duration format:** `30m`, `3h`, `12h`, `24h` (default), `2d`
+
+## Output
+
+Returns JSON with:
+- `price` - Current price in USD/USDT
+- `change_period_percent` - Price change percentage for the period
+- `chart_path` - Path to generated PNG chart (if available)
+- `text_plain` - Formatted text description
+
+**Chart as image (always when chart_path is present):**  
+You must send the chart as a **photo**, not as text. In your reply, output `text_plain` and on a new line: `MEDIA: ` followed by the exact `chart_path` value (e.g. `MEDIA: /tmp/crypto_chart_HYPE_1769204734.png`). Clawdbot will attach that file as an image. Do **not** write `[chart: path]` or any other text placeholder — only the `MEDIA: <chart_path>` line makes the image appear.
+
+## Chart Details
+
+- Format: Candlestick chart (8x8 square)
+- Theme: Dark (#0f141c background)
+- Output: `/tmp/crypto_chart_{SYMBOL}_{timestamp}.png`
+
+## Data Sources
+
+1. **Hyperliquid API** - For HYPE and other Hyperliquid tokens (preferred)
+2. **CoinGecko API** - Fallback for other tokens
+
+Price data cached for 300 seconds (5 minutes) in `/tmp/crypto_price_*.json`.

package/skills/crypto-price/requirements.txt

@@ -0,0 +1 @@
+matplotlib>=3.5.0