refactor: split precheck state snapshot and analysis
This commit is contained in:
214
README.md
214
README.md
@@ -1,13 +1,69 @@
|
||||
# coinhunter-cli
|
||||
|
||||
CoinHunter CLI is the executable tooling layer for CoinHunter.
|
||||
<p align="center">
|
||||
<strong>The executable CLI layer for CoinHunter.</strong><br/>
|
||||
Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
|
||||
</p>
|
||||
|
||||
• Code lives in this repository.
|
||||
• User runtime data lives in ~/.coinhunter/ by default.
|
||||
• Hermes skills can call this CLI instead of embedding large script collections.
|
||||
• Runtime locations can be overridden with COINHUNTER_HOME, HERMES_HOME, COINHUNTER_ENV_FILE, and HERMES_BIN.
|
||||
<p align="center">
|
||||
<img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue" />
|
||||
<img alt="Status" src="https://img.shields.io/badge/status-active%20development-orange" />
|
||||
<img alt="Architecture" src="https://img.shields.io/badge/architecture-runtime%20%2B%20commands%20%2B%20services-6f42c1" />
|
||||
</p>
|
||||
|
||||
## Install
|
||||
## Why this repo exists
|
||||
|
||||
CoinHunter is evolving from a loose bundle of automation scripts into a proper installable command-line tool.
|
||||
|
||||
This repository is the tooling layer:
|
||||
|
||||
- Code and executable behavior live here.
|
||||
- User runtime state lives in `~/.coinhunter/` by default.
|
||||
- Hermes skills can call this CLI instead of embedding large script collections.
|
||||
- Runtime paths can be overridden with `COINHUNTER_HOME`, `HERMES_HOME`, `COINHUNTER_ENV_FILE`, and `HERMES_BIN`.
|
||||
|
||||
In short:
|
||||
|
||||
- `coinhunter-cli` = tool
|
||||
- CoinHunter skill = strategy / workflow / prompting layer
|
||||
- `~/.coinhunter` = user data, logs, state, reviews
|
||||
|
||||
## Current architecture
|
||||
|
||||
```text
|
||||
coinhunter-cli/
|
||||
├── src/coinhunter/
|
||||
│ ├── cli.py # top-level command router
|
||||
│ ├── runtime.py # runtime paths + env loading
|
||||
│ ├── doctor.py # diagnostics
|
||||
│ ├── paths.py # runtime path inspection
|
||||
│ ├── commands/ # thin CLI adapters
|
||||
│ ├── services/ # orchestration / application services
|
||||
│ └── *.py # compatibility modules + legacy logic under extraction
|
||||
└── README.md
|
||||
```
|
||||
|
||||
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`
|
||||
- `precheck` internals now also have dedicated service modules for:
|
||||
- `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
|
||||
|
||||
Editable install:
|
||||
|
||||
@@ -15,38 +71,152 @@ Editable install:
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Core commands
|
||||
Run directly after install:
|
||||
|
||||
```bash
|
||||
coinhunter --help
|
||||
coinhunter --version
|
||||
coinhunter doctor
|
||||
coinhunter paths
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
|
||||
Initialize user state:
|
||||
|
||||
```bash
|
||||
coinhunter init
|
||||
```
|
||||
|
||||
Inspect runtime wiring:
|
||||
|
||||
```bash
|
||||
coinhunter paths
|
||||
coinhunter doctor
|
||||
```
|
||||
|
||||
Validate exchange credentials:
|
||||
|
||||
```bash
|
||||
coinhunter check-api
|
||||
coinhunter smart-executor balances
|
||||
```
|
||||
|
||||
Run precheck / gate plumbing:
|
||||
|
||||
```bash
|
||||
coinhunter precheck
|
||||
coinhunter precheck --mark-run-requested "external-gate queued cron run"
|
||||
coinhunter precheck --ack "analysis finished"
|
||||
```
|
||||
|
||||
Inspect balances or execute trading actions:
|
||||
|
||||
```bash
|
||||
coinhunter smart-executor balances
|
||||
coinhunter smart-executor status
|
||||
coinhunter smart-executor hold
|
||||
coinhunter smart-executor buy ENJUSDT 50
|
||||
coinhunter smart-executor sell-all ENJUSDT
|
||||
```
|
||||
|
||||
Generate review data:
|
||||
|
||||
```bash
|
||||
coinhunter review-context 12
|
||||
coinhunter review-engine 12
|
||||
```
|
||||
|
||||
Probe external market data:
|
||||
|
||||
```bash
|
||||
coinhunter market-probe bybit-ticker BTCUSDT
|
||||
coinhunter market-probe bybit-klines BTCUSDT 60 20
|
||||
```
|
||||
|
||||
## Runtime model
|
||||
|
||||
Default layout:
|
||||
|
||||
• ~/.coinhunter/ stores config, positions, logs, reviews, and state.
|
||||
• ~/.hermes/.env stores exchange credentials unless COINHUNTER_ENV_FILE overrides it.
|
||||
• hermes is discovered from PATH first, then ~/.local/bin/hermes, unless HERMES_BIN overrides it.
|
||||
```text
|
||||
~/.coinhunter/
|
||||
├── accounts.json
|
||||
├── config.json
|
||||
├── executions.json
|
||||
├── notes.json
|
||||
├── positions.json
|
||||
├── watchlist.json
|
||||
├── logs/
|
||||
├── reviews/
|
||||
└── state/
|
||||
```
|
||||
|
||||
## Next refactor direction
|
||||
Credential loading:
|
||||
|
||||
This repository now has a dedicated runtime layer and CLI diagnostics. The next major cleanup is to split command adapters from trading services so the internal architecture becomes:
|
||||
- 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.
|
||||
|
||||
• commands/
|
||||
• services/
|
||||
• runtime/
|
||||
• domain logic
|
||||
## Useful commands
|
||||
|
||||
The first split is already in place for:
|
||||
### Diagnostics
|
||||
|
||||
• smart-executor -> commands.smart_executor + services.smart_executor_service
|
||||
• precheck -> commands.precheck + services.precheck_service
|
||||
```bash
|
||||
coinhunter doctor
|
||||
coinhunter paths
|
||||
coinhunter check-api
|
||||
```
|
||||
|
||||
### Trading and execution
|
||||
|
||||
```bash
|
||||
coinhunter smart-executor balances
|
||||
coinhunter smart-executor status
|
||||
coinhunter smart-executor hold
|
||||
coinhunter smart-executor rebalance FROMUSDT TOUSDT
|
||||
```
|
||||
|
||||
### Precheck and orchestration
|
||||
|
||||
```bash
|
||||
coinhunter precheck
|
||||
coinhunter external-gate
|
||||
coinhunter rotate-external-gate-log
|
||||
```
|
||||
|
||||
### Review and market research
|
||||
|
||||
```bash
|
||||
coinhunter review-context 12
|
||||
coinhunter review-engine 12
|
||||
coinhunter market-probe bybit-ticker BTCUSDT
|
||||
```
|
||||
|
||||
## Development notes
|
||||
|
||||
This project is intentionally moving in small, safe refactor steps:
|
||||
|
||||
1. Separate runtime concerns from hardcoded paths.
|
||||
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.
|
||||
|
||||
## Near-term roadmap
|
||||
|
||||
- Extract more logic from `smart_executor.py` into dedicated execution / portfolio services.
|
||||
- Continue shrinking `precheck.py` by moving snapshot and analysis internals into reusable modules.
|
||||
- Add `domain/` models for positions, signals, and trigger analysis.
|
||||
- Add tests for runtime paths, precheck service behavior, and CLI stability.
|
||||
- Evolve toward a more polished installable CLI workflow.
|
||||
|
||||
## Philosophy
|
||||
|
||||
CoinHunter should become:
|
||||
|
||||
- more professional
|
||||
- more maintainable
|
||||
- safer to operate
|
||||
- easier for humans and agents to call
|
||||
- less dependent on prompt-only correctness
|
||||
|
||||
This repo is where that evolution happens.
|
||||
|
||||
Reference in New Issue
Block a user