docs: refresh README with current architecture and beautified title
This commit is contained in:
378
README.md
378
README.md
@@ -1,161 +1,149 @@
|
|||||||
# coinhunter-cli
|
<!--
|
||||||
|
╔══════════════════════════════════════════════════════════════════════════════╗
|
||||||
|
║ ║
|
||||||
|
║ ██████╗ ██╗ ██╗██╗███╗ ██╗██╗ ██╗██╗ ██╗███╗ ██╗████████╗███████╗██████╗ ║
|
||||||
|
║ ██╔════╝ ██║ ██║██║████╗ ██║██║ ██║██║ ██║████╗ ██║╚══██╔══╝██╔════╝██╔══██╗ ║
|
||||||
|
║ ██║ ██║ ██║██║██╔██╗ ██║███████║██║ ██║██╔██╗ ██║ ██║ █████╗ ██████╔╝ ║
|
||||||
|
║ ██║ ╚██╗ ██╔╝██║██║╚██╗██║██╔══██║██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██╔══██╗ ║
|
||||||
|
║ ╚██████╗ ╚████╔╝ ██║██║ ╚████║██║ ██║╚██████╔╝██║ ╚████║ ██║ ███████╗██║ ██║ ║
|
||||||
|
║ ╚═════╝ ╚═══╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ║
|
||||||
|
║ ║
|
||||||
|
║ The Executable CLI Layer for CoinHunter ║
|
||||||
|
║ ║
|
||||||
|
╚══════════════════════════════════════════════════════════════════════════════╝
|
||||||
|
-->
|
||||||
|
|
||||||
|
<h1 align="center">
|
||||||
|
<br>
|
||||||
|
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=28&duration=3000&pause=1000&color=F7B93E¢er=true&vCenter=true&width=435&lines=CoinHunter+CLI;Trade+Smarter+%E2%9A%A1+Execute+Faster" alt="CoinHunter CLI" />
|
||||||
|
</h1>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<strong>The executable CLI layer for CoinHunter.</strong><br/>
|
<strong>Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.</strong>
|
||||||
Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
|
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue" />
|
<a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white" /></a>
|
||||||
<img alt="Status" src="https://img.shields.io/badge/status-active%20development-orange" />
|
<a href="#"><img src="https://img.shields.io/badge/status-active%20development-22c55e?style=flat-square" /></a>
|
||||||
<img alt="Architecture" src="https://img.shields.io/badge/architecture-runtime%20%2B%20commands%20%2B%20services-6f42c1" />
|
<a href="#"><img src="https://img.shields.io/badge/architecture-cli%20%2B%20commands%20%2B%20services-8b5cf6?style=flat-square" /></a>
|
||||||
|
<a href="#"><img src="https://img.shields.io/badge/tests-needed-ef4444?style=flat-square" /></a>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
## Why this repo exists
|
---
|
||||||
|
|
||||||
CoinHunter is evolving from a loose bundle of automation scripts into a proper installable command-line tool.
|
## What is this?
|
||||||
|
|
||||||
This repository is the tooling layer:
|
`coinhunter-cli` is the **executable tooling layer** for CoinHunter — an installable Python CLI that handles trading operations, market probes, precheck orchestration, and review workflows.
|
||||||
|
|
||||||
- Code and executable behavior live here.
|
| Layer | Responsibility | Location |
|
||||||
- User runtime state lives in `~/.coinhunter/` by default.
|
|-------|----------------|----------|
|
||||||
- Hermes skills can call this CLI instead of embedding large script collections.
|
| **CLI** | Top-level command router | `cli.py` |
|
||||||
- Runtime paths can be overridden with `COINHUNTER_HOME`, `HERMES_HOME`, `COINHUNTER_ENV_FILE`, and `HERMES_BIN`.
|
| **Commands** | Thin argument adapters | `commands/` |
|
||||||
|
| **Services** | Orchestration & execution logic | `services/` |
|
||||||
|
| **Runtime** | Paths, env, locks, config | `runtime.py` |
|
||||||
|
| **User Data** | State, logs, reviews, positions | `~/.coinhunter/` |
|
||||||
|
|
||||||
In short:
|
> **Separation of concerns:** Code lives in this repo. Your data lives in `~/.coinhunter/`. Strategy and prompting live in Hermes skills.
|
||||||
|
|
||||||
- `coinhunter-cli` = tool
|
---
|
||||||
- CoinHunter skill = strategy / workflow / prompting layer
|
|
||||||
- `~/.coinhunter` = user data, logs, state, reviews
|
|
||||||
|
|
||||||
## Current architecture
|
## Project Structure
|
||||||
|
|
||||||
```text
|
```text
|
||||||
coinhunter-cli/
|
src/coinhunter/
|
||||||
├── src/coinhunter/
|
├── cli.py # Unified command router
|
||||||
│ ├── cli.py # top-level command router
|
├── runtime.py # Runtime paths + env loading
|
||||||
│ ├── runtime.py # runtime paths + env loading
|
├── logger.py # Structured logging utilities
|
||||||
│ ├── doctor.py # diagnostics
|
├── commands/ # CLI adapters (thin, stateless)
|
||||||
│ ├── paths.py # runtime path inspection
|
│ ├── precheck.py
|
||||||
│ ├── commands/ # thin CLI adapters
|
│ ├── smart_executor.py
|
||||||
│ ├── services/ # orchestration / application services
|
│ ├── check_api.py
|
||||||
│ └── *.py # compatibility modules + legacy logic under extraction
|
│ ├── doctor.py
|
||||||
└── README.md
|
│ ├── external_gate.py
|
||||||
|
│ ├── init_user_state.py
|
||||||
|
│ ├── market_probe.py
|
||||||
|
│ ├── paths.py
|
||||||
|
│ ├── review_context.py
|
||||||
|
│ ├── review_engine.py
|
||||||
|
│ └── rotate_external_gate_log.py
|
||||||
|
├── services/ # Orchestration & domain logic
|
||||||
|
│ ├── exchange_service.py
|
||||||
|
│ ├── portfolio_service.py
|
||||||
|
│ ├── trade_execution.py
|
||||||
|
│ ├── smart_executor_service.py
|
||||||
|
│ ├── smart_executor_parser.py
|
||||||
|
│ ├── execution_state.py
|
||||||
|
│ ├── precheck_service.py
|
||||||
|
│ ├── precheck_constants.py # thresholds & paths
|
||||||
|
│ ├── time_utils.py # UTC/local time helpers
|
||||||
|
│ ├── data_utils.py # json, hash, float, symbol norm
|
||||||
|
│ ├── state_manager.py # state load/save/sanitize
|
||||||
|
│ ├── market_data.py # exchange, OHLCV, metrics
|
||||||
|
│ ├── candidate_scoring.py # coin selection & scoring
|
||||||
|
│ ├── snapshot_builder.py # precheck snapshot construction
|
||||||
|
│ ├── adaptive_profile.py # trigger profile builder
|
||||||
|
│ ├── trigger_analyzer.py # trigger analysis core
|
||||||
|
│ ├── precheck_analysis.py # failure payloads
|
||||||
|
│ ├── precheck_snapshot.py # snapshot facade
|
||||||
|
│ ├── precheck_state.py # state facade
|
||||||
|
│ └── precheck_core.py # backward-compat export facade
|
||||||
|
├── precheck.py # Backward-compat root facade
|
||||||
|
├── smart_executor.py # Backward-compat root facade
|
||||||
|
└── *.py # Other compat / utility modules
|
||||||
```
|
```
|
||||||
|
|
||||||
The repo is actively being refactored toward a cleaner split:
|
---
|
||||||
|
|
||||||
- `commands/` → argument / CLI adapters
|
|
||||||
- `services/` → orchestration and application workflows
|
|
||||||
- `runtime/` → paths, env, files, locks, config
|
|
||||||
- future `domain/` → trading and precheck core logic
|
|
||||||
|
|
||||||
## Implemented command/service splits
|
|
||||||
|
|
||||||
The first extraction pass is already live:
|
|
||||||
|
|
||||||
- `smart-executor` → `commands.smart_executor` + `services.smart_executor_service`
|
|
||||||
- `precheck` → `commands.precheck` + `services.precheck_service`
|
|
||||||
- root modules are compatibility facades only:
|
|
||||||
- `src/coinhunter/precheck.py`
|
|
||||||
- `src/coinhunter/smart_executor.py`
|
|
||||||
- `precheck` internals now live in dedicated service modules:
|
|
||||||
- `services.precheck_core`
|
|
||||||
- `services.precheck_state`
|
|
||||||
- `services.precheck_snapshot`
|
|
||||||
- `services.precheck_analysis`
|
|
||||||
|
|
||||||
This keeps behavior stable while giving the codebase a cleaner landing zone for deeper refactors.
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
Dedicated user-local install:
|
### Quick user install
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./scripts/install_local.sh
|
./scripts/install_local.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
This creates:
|
Creates:
|
||||||
|
- Virtualenv: `~/.local/share/coinhunter-cli/venv`
|
||||||
|
- Launcher: `~/.local/bin/coinhunter`
|
||||||
|
|
||||||
- app environment: `~/.local/share/coinhunter-cli/venv`
|
### Editable dev install
|
||||||
- launcher: `~/.local/bin/coinhunter`
|
|
||||||
|
|
||||||
The launcher behaves like a normal installed CLI and simply forwards into the dedicated virtualenv.
|
|
||||||
|
|
||||||
Editable install for development:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install -e .
|
pip install -e .
|
||||||
```
|
```
|
||||||
|
|
||||||
Run directly after install:
|
Verify:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
coinhunter --help
|
coinhunter --help
|
||||||
coinhunter --version
|
coinhunter --version
|
||||||
```
|
```
|
||||||
|
|
||||||
Short aliases are available for the most common commands. The original long-form command names remain supported for backward compatibility.
|
---
|
||||||
|
|
||||||
## Quickstart
|
## Command Reference
|
||||||
|
|
||||||
Initialize user state:
|
### Short aliases (recommended)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
coinhunter init
|
coinhunter diag # runtime diagnostics
|
||||||
|
coinhunter paths # print resolved paths
|
||||||
|
coinhunter api-check # validate exchange credentials
|
||||||
|
coinhunter precheck # run precheck snapshot + trigger analysis
|
||||||
|
coinhunter exec bal # print balances as JSON
|
||||||
|
coinhunter exec overview # account overview as JSON
|
||||||
|
coinhunter exec hold # record a HOLD decision
|
||||||
|
coinhunter exec buy ENJUSDT 50 # buy $50 of ENJUSDT
|
||||||
|
coinhunter exec flat ENJUSDT # sell entire ENJUSDT position
|
||||||
|
coinhunter exec rotate PEPEUSDT ETHUSDT # rotate exposure
|
||||||
|
coinhunter gate # external gate orchestration
|
||||||
|
coinhunter review 12 # generate review context (last 12h)
|
||||||
|
coinhunter recap 12 # generate review report (last 12h)
|
||||||
|
coinhunter probe bybit-ticker BTCUSDT # market probe
|
||||||
|
coinhunter rotate-log # rotate external gate logs
|
||||||
```
|
```
|
||||||
|
|
||||||
Inspect runtime wiring:
|
### Legacy long forms (still supported)
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter paths
|
|
||||||
coinhunter diag
|
|
||||||
```
|
|
||||||
|
|
||||||
Validate exchange credentials:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter api-check
|
|
||||||
```
|
|
||||||
|
|
||||||
Run precheck / gate plumbing:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter precheck
|
|
||||||
coinhunter precheck --mark-run-requested "external-gate queued cron run"
|
|
||||||
coinhunter precheck --ack "analysis finished"
|
|
||||||
coinhunter gate
|
|
||||||
```
|
|
||||||
|
|
||||||
Inspect balances or execute trading actions:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter exec bal
|
|
||||||
coinhunter exec overview
|
|
||||||
coinhunter exec hold
|
|
||||||
coinhunter exec buy ENJUSDT 50
|
|
||||||
coinhunter exec flat ENJUSDT
|
|
||||||
coinhunter exec rotate PEPEUSDT ETHUSDT
|
|
||||||
```
|
|
||||||
|
|
||||||
Preferred `exec` verbs are `bal`, `overview`, `hold`, `buy`, `flat`, and `rotate`.
|
|
||||||
Legacy forms remain supported for backward compatibility: `balances`, `balance`, `acct`, `status`, `sell-all`, `sell_all`, and `rebalance`.
|
|
||||||
|
|
||||||
Generate review data:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter review 12
|
|
||||||
coinhunter recap 12
|
|
||||||
```
|
|
||||||
|
|
||||||
Probe external market data:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter probe bybit-ticker BTCUSDT
|
|
||||||
coinhunter probe bybit-klines BTCUSDT 60 20
|
|
||||||
```
|
|
||||||
|
|
||||||
Long-form equivalents still work:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
coinhunter doctor
|
coinhunter doctor
|
||||||
@@ -168,109 +156,117 @@ coinhunter external-gate
|
|||||||
coinhunter rotate-external-gate-log
|
coinhunter rotate-external-gate-log
|
||||||
```
|
```
|
||||||
|
|
||||||
Supported top-level commands and aliases remain:
|
### All supported commands
|
||||||
|
|
||||||
- `check-api` / `api-check`
|
| Canonical | Aliases |
|
||||||
- `doctor` / `diag`
|
|-----------|---------|
|
||||||
- `external-gate` / `gate`
|
| `check-api` | `api-check` |
|
||||||
- `init`
|
| `doctor` | `diag` |
|
||||||
- `market-probe` / `probe`
|
| `external-gate` | `gate` |
|
||||||
- `paths`
|
| `init` | — |
|
||||||
- `precheck`
|
| `market-probe` | `probe` |
|
||||||
- `review-context` / `review`
|
| `paths` | — |
|
||||||
- `review-engine` / `recap`
|
| `precheck` | — |
|
||||||
- `rotate-external-gate-log` / `rotate-gate-log` / `rotate-log`
|
| `review-context` | `review` |
|
||||||
- `smart-executor` / `exec`
|
| `review-engine` | `recap` |
|
||||||
|
| `rotate-external-gate-log` | `rotate-gate-log`, `rotate-log` |
|
||||||
|
| `smart-executor` | `exec` |
|
||||||
|
|
||||||
## Runtime model
|
---
|
||||||
|
|
||||||
Default layout:
|
## Quickstart
|
||||||
|
|
||||||
```text
|
Initialize runtime state:
|
||||||
~/.coinhunter/
|
|
||||||
├── accounts.json
|
```bash
|
||||||
├── config.json
|
coinhunter init
|
||||||
├── executions.json
|
```
|
||||||
├── notes.json
|
|
||||||
├── positions.json
|
Inspect the environment:
|
||||||
├── watchlist.json
|
|
||||||
├── logs/
|
|
||||||
├── reviews/
|
|
||||||
└── state/
|
|
||||||
```
|
|
||||||
|
|
||||||
Credential loading:
|
|
||||||
|
|
||||||
- Binance credentials are read from `~/.hermes/.env` by default.
|
|
||||||
- `COINHUNTER_ENV_FILE` can point to a different env file.
|
|
||||||
- `hermes` is resolved from `PATH` first, then `~/.local/bin/hermes`, unless `HERMES_BIN` overrides it.
|
|
||||||
|
|
||||||
## Useful commands
|
|
||||||
|
|
||||||
### Diagnostics
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
coinhunter diag
|
|
||||||
coinhunter paths
|
coinhunter paths
|
||||||
|
coinhunter diag
|
||||||
|
```
|
||||||
|
|
||||||
|
Validate API keys:
|
||||||
|
|
||||||
|
```bash
|
||||||
coinhunter api-check
|
coinhunter api-check
|
||||||
```
|
```
|
||||||
|
|
||||||
### Trading and execution
|
Run the precheck workflow:
|
||||||
|
|
||||||
```bash
|
|
||||||
coinhunter exec bal
|
|
||||||
coinhunter exec overview
|
|
||||||
coinhunter exec hold
|
|
||||||
coinhunter exec buy ENJUSDT 50
|
|
||||||
coinhunter exec flat ENJUSDT
|
|
||||||
coinhunter exec rotate FROMUSDT TOUSDT
|
|
||||||
```
|
|
||||||
|
|
||||||
### Precheck and orchestration
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
coinhunter precheck
|
coinhunter precheck
|
||||||
coinhunter gate
|
coinhunter precheck --ack "analysis completed"
|
||||||
coinhunter rotate-gate-log
|
|
||||||
coinhunter rotate-log
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Review and market research
|
Run the external gate:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
coinhunter review 12
|
coinhunter gate
|
||||||
coinhunter recap 12
|
|
||||||
coinhunter probe bybit-ticker BTCUSDT
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development notes
|
---
|
||||||
|
|
||||||
This project is intentionally moving in small, safe refactor steps:
|
## Runtime Model
|
||||||
|
|
||||||
1. Separate runtime concerns from hardcoded paths.
|
Default data layout:
|
||||||
2. Move command dispatch into thin adapters.
|
|
||||||
3. Introduce orchestration services.
|
|
||||||
4. Extract reusable domain logic from large compatibility modules.
|
|
||||||
5. Keep cron / Hermes integration stable during migration.
|
|
||||||
|
|
||||||
That means some compatibility modules still exist, but the direction is deliberate.
|
```text
|
||||||
|
~/.coinhunter/
|
||||||
|
├── config.json
|
||||||
|
├── positions.json
|
||||||
|
├── accounts.json
|
||||||
|
├── watchlist.json
|
||||||
|
├── notes.json
|
||||||
|
├── executions.json
|
||||||
|
├── logs/
|
||||||
|
├── reviews/
|
||||||
|
├── cache/
|
||||||
|
└── state/
|
||||||
|
├── precheck_state.json
|
||||||
|
└── external_gate.lock
|
||||||
|
```
|
||||||
|
|
||||||
## Near-term roadmap
|
Credential resolution:
|
||||||
|
|
||||||
- Extract more logic from `smart_executor.py` into dedicated execution / portfolio services.
|
- Binance API keys are read from `~/.hermes/.env` by default.
|
||||||
- Continue shrinking `precheck.py` by moving snapshot and analysis internals into reusable modules.
|
- Override with `COINHUNTER_ENV_FILE`.
|
||||||
- Add `domain/` models for positions, signals, and trigger analysis.
|
- Override home with `COINHUNTER_HOME` or `HERMES_HOME`.
|
||||||
- Add tests for runtime paths, precheck service behavior, and CLI stability.
|
- `hermes` binary is resolved from `PATH`, then `~/.local/bin/hermes`, unless `HERMES_BIN` is set.
|
||||||
- Evolve toward a more polished installable CLI workflow.
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Status
|
||||||
|
|
||||||
|
The codebase is actively maintained and refactored in small, safe steps.
|
||||||
|
|
||||||
|
**Recently completed:**
|
||||||
|
- ✅ Unified CLI entrypoint with short aliases
|
||||||
|
- ✅ Extracted `smart-executor` into `commands/` + `services/`
|
||||||
|
- ✅ Extracted `precheck` into 9 focused service modules
|
||||||
|
- ✅ Migrated all active command modules into `commands/`
|
||||||
|
- ✅ Removed dead `auto-trader` command
|
||||||
|
- ✅ Backward-compatible root facades preserved
|
||||||
|
|
||||||
|
**Next priorities:**
|
||||||
|
- 🧪 Add pytest coverage for runtime paths, state manager, and trigger analyzer
|
||||||
|
- 🔧 Extract `review_engine.py` core logic into `services/`
|
||||||
|
- 🔧 Unify output contract (JSON-first with `--pretty` option)
|
||||||
|
- 🔧 Add basic CI (lint + compileall + pytest)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Philosophy
|
## Philosophy
|
||||||
|
|
||||||
CoinHunter should become:
|
CoinHunter is evolving toward:
|
||||||
|
|
||||||
- more professional
|
- **Professional execution** — scientific position sizing, not moonshot gambling
|
||||||
- more maintainable
|
- **Maintainable architecture** — clear boundaries between CLI, services, and domain logic
|
||||||
- safer to operate
|
- **Safer operations** — dry-run, validation gates, and explicit decision logging
|
||||||
- easier for humans and agents to call
|
- **Agent-friendly interfaces** — stable JSON outputs and predictable command contracts
|
||||||
- less dependent on prompt-only correctness
|
- **Less dependence on prompt-only correctness** — logic belongs in code, not just in system prompts
|
||||||
|
|
||||||
This repo is where that evolution happens.
|
This repo is where that evolution happens.
|
||||||
|
|||||||
Reference in New Issue
Block a user