coinhunter-cli/README.md

<!--
  ╔══════════════════════════════════════════════════════════════════════════════╗
  ║                                                                              ║
  ║   ██████╗ ██╗   ██╗██╗███╗   ██╗██╗  ██╗██╗   ██╗███╗   ██╗████████╗███████╗██████╗  ║
  ║  ██╔════╝ ██║   ██║██║████╗  ██║██║  ██║██║   ██║████╗  ██║╚══██╔══╝██╔════╝██╔══██╗ ║
  ║  ██║      ██║   ██║██║██╔██╗ ██║███████║██║   ██║██╔██╗ ██║   ██║   █████╗  ██████╔╝ ║
  ║  ██║      ╚██╗ ██╔╝██║██║╚██╗██║██╔══██║██║   ██║██║╚██╗██║   ██║   ██╔══╝  ██╔══██╗ ║
  ║  ╚██████╗  ╚████╔╝ ██║██║ ╚████║██║  ██║╚██████╔╝██║ ╚████║   ██║   ███████╗██║  ██║ ║
  ║   ╚═════╝   ╚═══╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝  ╚═╝ ║
  ║                                                                              ║
  ║                        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&center=true&vCenter=true&width=435&lines=CoinHunter+CLI;Trade+Smarter+%E2%9A%A1+Execute+Faster" alt="CoinHunter CLI" />
</h1>

<p align="center">
  <strong>Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/coinhunter/"><img src="https://img.shields.io/pypi/v/coinhunter?style=flat-square&color=3776ab" /></a>
  <a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white" /></a>
  <a href="#"><img src="https://img.shields.io/badge/status-active%20development-22c55e?style=flat-square" /></a>
  <a href="#"><img src="https://img.shields.io/badge/architecture-cli%20%2B%20commands%20%2B%20services-8b5cf6?style=flat-square" /></a>
</p>

---

## What is this?

`coinhunter` is the **executable tooling layer** for CoinHunter — an installable Python CLI that handles trading operations, market probes, precheck orchestration, and review workflows.

> **Note:** The old package name `coinhunter-cli` is deprecated. Please install `coinhunter` going forward.

| Layer | Responsibility | Location |
|-------|----------------|----------|
| **CLI** | Top-level command router | `cli.py` |
| **Commands** | Thin argument adapters | `commands/` |
| **Services** | Orchestration & execution logic | `services/` |
| **Runtime** | Paths, env, locks, config | `runtime.py` |
| **User Data** | State, logs, reviews, positions | `~/.coinhunter/` |

> **Separation of concerns:** Code lives in this repo. Your data lives in `~/.coinhunter/`. Strategy and prompting live in Hermes skills.

---

## Project Structure

```text
src/coinhunter/
├── cli.py                    # Unified command router
├── runtime.py                # Runtime paths + env loading
├── logger.py                 # Structured logging utilities
├── commands/                 # CLI adapters (thin, stateless)
│   ├── precheck.py
│   ├── smart_executor.py
│   ├── check_api.py
│   ├── doctor.py
│   ├── 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
│   ├── review_service.py         # review generation logic
│   ├── precheck_constants.py     # thresholds
│   ├── 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
```

---

## Installation

### From PyPI (recommended)

```bash
pip install coinhunter
```

This installs the latest stable release and creates the `coinhunter` console script entry point.

Verify:

```bash
coinhunter --help
coinhunter --version
```

### Development install (editable)

If you're working on this repo locally:

```bash
pip install -e ".[dev]"
```

Or use the convenience script:

```bash
./scripts/install_local.sh
```

A thin wrapper that runs `pip install -e .` and verifies the entrypoint is on your PATH.

---

## Command Reference

### Short aliases (recommended)

```bash
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 exec orders       # list open spot orders
coinhunter exec order-status ENJUSDT 123456  # check specific order
coinhunter exec cancel ENJUSDT 123456        # cancel an open order
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
```

### Legacy long forms (still supported)

```bash
coinhunter doctor
coinhunter check-api
coinhunter smart-executor bal
coinhunter review-context 12
coinhunter review-engine 12
coinhunter market-probe bybit-ticker BTCUSDT
coinhunter external-gate
coinhunter rotate-external-gate-log
```

### All supported commands

| Canonical | Aliases |
|-----------|---------|
| `check-api` | `api-check` |
| `doctor` | `diag` |
| `external-gate` | `gate` |
| `init` | — |
| `market-probe` | `probe` |
| `paths` | — |
| `precheck` | — |
| `review-context` | `review` |
| `review-engine` | `recap` |
| `rotate-external-gate-log` | `rotate-gate-log`, `rotate-log` |
| `smart-executor` | `exec` |

---

## Quickstart

Initialize runtime state:

```bash
coinhunter init
```

Inspect the environment:

```bash
coinhunter paths
coinhunter diag
```

Validate API keys:

```bash
coinhunter api-check
```

Run the precheck workflow:

```bash
coinhunter precheck
coinhunter precheck --ack "analysis completed"
```

Run the external gate:

```bash
coinhunter gate
```

The gate reads `trigger_command` from `~/.coinhunter/config.json` under `external_gate`.
- By default, no external trigger is configured — gate runs precheck and marks state, then exits cleanly.
- Set `trigger_command` to a command list to integrate with your own scheduler:

```json
{
  "external_gate": {
    "trigger_command": ["hermes", "cron", "run", "JOB_ID"]
  }
}
```

- Set to `null` or `[]` to explicitly disable the external trigger.

### Dynamic tuning via `config.json`

You can override internal defaults without editing code by adding keys to `~/.coinhunter/config.json`:

```json
{
  "external_gate": {
    "trigger_command": ["hermes", "cron", "run", "JOB_ID"]
  },
  "exchange": {
    "min_quote_volume": 200000,
    "cache_ttl_seconds": 3600
  },
  "logging": {
    "schema_version": 2
  }
}
```

| Key | Default | Effect |
|-----|---------|--------|
| `exchange.min_quote_volume` | `200000` | Minimum 24h quote volume for a symbol to appear in market snapshots |
| `exchange.cache_ttl_seconds` | `3600` | How long the ccxt exchange instance (and `load_markets()` result) is cached |
| `logging.schema_version` | `2` | Schema version stamped on every JSONL log entry |

---

## Runtime Model

Default data layout:

```text
~/.coinhunter/
├── config.json
├── positions.json
├── accounts.json
├── watchlist.json
├── notes.json
├── executions.json
├── logs/
├── reviews/
├── cache/
└── state/
    ├── precheck_state.json
    └── external_gate.lock
```

Credential resolution:

- Binance API keys are read from `~/.hermes/.env` by default.
- Override with `COINHUNTER_ENV_FILE`.
- Override home with `COINHUNTER_HOME` or `HERMES_HOME`.
- `hermes` binary is resolved from `PATH`, then `~/.local/bin/hermes`, unless `HERMES_BIN` is set.

---

## 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/`
- ✅ Extracted `review_engine.py` core logic into `services/review_service.py`
- ✅ Removed eager `PATHS` instantiation across services and commands
- ✅ Fixed `smart_executor.py` lazy-loading facade
- ✅ Standardized install to use `pip install -e .`
- ✅ Made `external_gate` trigger_command configurable (no longer hardcodes hermes)
- ✅ Removed dead `auto-trader` command
- ✅ Backward-compatible root facades preserved

**Next priorities:**
- 🔧 Add basic CI (lint + compileall + pytest)
- 🔧 Unify output contract (JSON-first with `--pretty` option)

---

## Philosophy

CoinHunter is evolving toward:

- **Professional execution** — scientific position sizing, not moonshot gambling
- **Maintainable architecture** — clear boundaries between CLI, services, and domain logic
- **Safer operations** — dry-run, validation gates, and explicit decision logging
- **Agent-friendly interfaces** — stable JSON outputs and predictable command contracts
- **Less dependence on prompt-only correctness** — logic belongs in code, not just in system prompts

This repo is where that evolution happens.