@jango-blockchained/hoox-cli 0.7.4 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +170 -59
- package/dist/index.js +7725 -7371
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,27 +1,32 @@
|
|
|
1
1
|
# @jango-blockchained/hoox-cli
|
|
2
2
|
|
|
3
|
-
> **See also:** [Hoox User Guide](../docs/home.md) · [CLI Command Reference](../docs/reference/cli-commands.
|
|
3
|
+
> **See also:** [Hoox User Guide](../docs/home.md) · [CLI Command Reference](../docs/reference/cli-commands.mdx)
|
|
4
4
|
|
|
5
5
|
> Hoox CLI — manage Cloudflare Workers, infrastructure, secrets, and deployments.
|
|
6
6
|
|
|
7
7
|
> **Runtime requirement:** Bun ≥ 1.2. The bin shebang and bundle target are Bun-only; `npm install -g` will install the package but the CLI will not run under Node.js.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
**v0.9.0** — 411 unit tests, 25 command groups, 60+ subcommands. Modern-minimal visual refresh, completion footer, did-you-mean suggestions, custom help.
|
|
10
10
|
|
|
11
11
|
## Features
|
|
12
12
|
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
22
|
-
- **
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
13
|
+
- **One-shot Onboarding** (`hoox onboard`): Full bootstrap from a fresh clone — collects credentials, configures workers, provisions D1/KV, generates keys, pushes secrets, deploys dashboard. The recommended entry point for new users.
|
|
14
|
+
- **Config & Setup Wizards** (`hoox init`, `hoox setup`): Split into two steps — `init` writes `wrangler.jsonc` and collects integration secrets; `setup` generates keys, applies D1 schema, and pushes secrets to Cloudflare. Run separately when you need fine-grained control.
|
|
15
|
+
- **Infrastructure as Code**: Manage D1, KV, R2, Queues, Vectorize, and Analytics via `hoox infra`.
|
|
16
|
+
- **Environment Management**: Declarative 27-key env matrix via `hoox config env`.
|
|
17
|
+
- **KV Config Sync**: 16-key manifest with `apply-manifest` for CONFIG_KV.
|
|
18
|
+
- **Database Operations**: Schema apply, migrations, query, export, reset via `hoox db`.
|
|
19
|
+
- **Deploy Automation**: Workers + dashboard + telegram webhook + KV config in one flow.
|
|
20
|
+
- **Performance Measurement** (`hoox perf`): `fastpath` subcommand sends synthetic probes and reports p50/p95/p99 per-hop latency.
|
|
21
|
+
- **Observability** (`hoox trace`): Query Cloudflare Workers Observability REST API for events, metrics, and traces.
|
|
22
|
+
- **Health Checks** (`hoox check health`): The single source of truth for worker health probes. Run after deployments or in CI.
|
|
23
|
+
- **Operational Monitoring** (`hoox monitor`): Recent trades, kill switch, queue depth, backup, system logs.
|
|
24
|
+
- **Repair & Recovery** (`hoox repair`): Comprehensive system check, guided rebuild, per-component repair.
|
|
25
|
+
- **Top-level Secrets & Keys**: `hoox secrets` and `hoox keys` for Cloudflare Worker secrets and internal auth keys.
|
|
26
|
+
- **Unified Dashboard** (`hoox dashboard dev | deploy`): Start the dev server or build & deploy the Next.js dashboard.
|
|
27
|
+
- **Interactive TUI**: Launch an interactive terminal UI when running `hoox` with no arguments.
|
|
28
|
+
- **Modern-minimal output polish (v0.9.0)**: Refined zinc/indigo palette, completion footer with "next step" suggestions after every command, "did you mean …" for typos, custom help formatter, `--no-color` flag, `NO_COLOR` / `TERM=dumb` honored, `formatNumber` and `formatBytes` for compact tables. All available to plugin authors via the shared `format*` exports.
|
|
29
|
+
- **Shell Completions**: bash, zsh, and fish completion scripts via `hoox completion <shell>`.
|
|
25
30
|
|
|
26
31
|
## Installation
|
|
27
32
|
|
|
@@ -45,43 +50,55 @@ bun run build
|
|
|
45
50
|
## Quick Start
|
|
46
51
|
|
|
47
52
|
```bash
|
|
48
|
-
#
|
|
49
|
-
hoox
|
|
53
|
+
# One-shot onboarding (collects credentials, provisions, deploys)
|
|
54
|
+
hoox onboard
|
|
50
55
|
|
|
51
|
-
# Or
|
|
52
|
-
hoox --help
|
|
56
|
+
# Or step-by-step: write config first, then provision
|
|
53
57
|
hoox init
|
|
54
|
-
hoox
|
|
55
|
-
|
|
56
|
-
|
|
58
|
+
hoox setup
|
|
59
|
+
|
|
60
|
+
# Verify the system
|
|
61
|
+
hoox check setup
|
|
62
|
+
hoox check health
|
|
63
|
+
|
|
64
|
+
# Deploy to Cloudflare
|
|
65
|
+
hoox deploy all --auto
|
|
66
|
+
|
|
67
|
+
# Measure fast-path latency
|
|
68
|
+
hoox perf fastpath run --n 50
|
|
57
69
|
```
|
|
58
70
|
|
|
59
71
|
## Available Commands
|
|
60
72
|
|
|
61
|
-
| Command | Description
|
|
62
|
-
| ----------------- |
|
|
63
|
-
| `hoox
|
|
64
|
-
| `hoox
|
|
65
|
-
| `hoox
|
|
66
|
-
| `hoox
|
|
67
|
-
| `hoox
|
|
68
|
-
| `hoox
|
|
69
|
-
| `hoox
|
|
70
|
-
| `hoox
|
|
71
|
-
| `hoox
|
|
72
|
-
| `hoox
|
|
73
|
-
| `hoox
|
|
74
|
-
| `hoox
|
|
75
|
-
| `hoox
|
|
76
|
-
| `hoox
|
|
77
|
-
| `hoox
|
|
78
|
-
| `hoox
|
|
79
|
-
| `hoox
|
|
80
|
-
| `hoox
|
|
81
|
-
| `hoox
|
|
82
|
-
| `hoox
|
|
83
|
-
| `hoox
|
|
84
|
-
| `hoox
|
|
73
|
+
| Command | Description |
|
|
74
|
+
| ----------------- | -------------------------------------------------------------------- |
|
|
75
|
+
| `hoox onboard` | **Recommended entry point.** One-shot full bootstrap (init + setup) |
|
|
76
|
+
| `hoox init` | Interactive setup wizard (writes `wrangler.jsonc`, collects secrets) |
|
|
77
|
+
| `hoox setup` | Auto-bootstrap infrastructure (auth, keys, D1, secrets, dashboard) |
|
|
78
|
+
| `hoox clone` | Clone worker repositories as git submodules |
|
|
79
|
+
| `hoox dev` | Start local development environment for all workers |
|
|
80
|
+
| `hoox deploy` | Deploy workers, dashboard, telegram webhook, and KV config |
|
|
81
|
+
| `hoox infra` | Manage infrastructure (D1, KV, R2, Queues, Vectorize, Analytics) |
|
|
82
|
+
| `hoox config` | Manage `wrangler.jsonc` configuration |
|
|
83
|
+
| `hoox secrets` | Manage Cloudflare Worker secrets |
|
|
84
|
+
| `hoox keys` | Manage internal auth keys |
|
|
85
|
+
| `hoox check` | Validate setup, prerequisites, and worker health |
|
|
86
|
+
| `hoox db` | Manage D1 databases (apply, migrate, query, export, reset) |
|
|
87
|
+
| `hoox monitor` | Monitor trades, logs, kill switch, queue, backup |
|
|
88
|
+
| `hoox workers` | Per-worker operations (list, dev, logs) |
|
|
89
|
+
| `hoox repair` | Diagnose and repair the system (check, rebuild, per-component) |
|
|
90
|
+
| `hoox schema` | Manage D1 schema and migrations |
|
|
91
|
+
| `hoox update` | Self-update the CLI and check wrangler versions |
|
|
92
|
+
| `hoox logs` | Stream and filter Cloudflare Worker logs |
|
|
93
|
+
| `hoox test` | Run tests and CI pipeline |
|
|
94
|
+
| `hoox waf` | Manage Cloudflare WAF rules and policies |
|
|
95
|
+
| `hoox dashboard` | Dashboard operations (`dev`, `deploy`) |
|
|
96
|
+
| `hoox tui` | Launch the OpenTUI terminal dashboard |
|
|
97
|
+
| `hoox agent` | AI agent operations (health probe) |
|
|
98
|
+
| `hoox trace` | Query Cloudflare Workers Observability (events, metrics, traces) |
|
|
99
|
+
| `hoox perf` | Performance measurement tools (`fastpath` probe-based latency) |
|
|
100
|
+
| `hoox disclaimer` | Display legal disclaimer |
|
|
101
|
+
| `hoox completion` | Generate shell completion script (bash, zsh, fish) |
|
|
85
102
|
|
|
86
103
|
### Global Options
|
|
87
104
|
|
|
@@ -94,13 +111,27 @@ All commands support these global options:
|
|
|
94
111
|
|
|
95
112
|
## Usage Examples
|
|
96
113
|
|
|
97
|
-
###
|
|
114
|
+
### Onboard a New Project
|
|
98
115
|
|
|
99
116
|
```bash
|
|
100
|
-
|
|
117
|
+
# One-shot (recommended) — fully automatic, no separate setup step
|
|
118
|
+
hoox onboard --token cfut_xxx --account xxx --preset full
|
|
119
|
+
|
|
120
|
+
# Interactive
|
|
121
|
+
hoox onboard
|
|
101
122
|
```
|
|
102
123
|
|
|
103
|
-
Interactive prompts
|
|
124
|
+
Interactive prompts collect your Cloudflare Account ID, API Token, and subdomain prefix; then it writes the config and provisions infrastructure end-to-end.
|
|
125
|
+
|
|
126
|
+
### Step-by-Step Onboarding
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
# 1. Write workspace config (wrangler.jsonc, secrets)
|
|
130
|
+
hoox init
|
|
131
|
+
|
|
132
|
+
# 2. Provision infrastructure (keys, D1 schema, push secrets, deploy dashboard)
|
|
133
|
+
hoox setup
|
|
134
|
+
```
|
|
104
135
|
|
|
105
136
|
### Check Prerequisites
|
|
106
137
|
|
|
@@ -114,6 +145,32 @@ hoox check prerequisites --tool bun
|
|
|
114
145
|
|
|
115
146
|
Validates bun ≥1.2, git ≥2.40, wrangler, Docker, Cloudflare auth, and repository integrity.
|
|
116
147
|
|
|
148
|
+
### Manage Secrets
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
# List secrets for a worker
|
|
152
|
+
hoox secrets list trade-worker
|
|
153
|
+
|
|
154
|
+
# Set a secret
|
|
155
|
+
hoox secrets set trade-worker BINANCE_KEY_BINDING
|
|
156
|
+
|
|
157
|
+
# Delete a secret
|
|
158
|
+
hoox secrets delete trade-worker BINANCE_KEY_BINDING
|
|
159
|
+
|
|
160
|
+
# Sync local .dev.vars to Cloudflare
|
|
161
|
+
hoox secrets sync
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Manage Internal Keys
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
# Generate new internal keys (writes to .keys/)
|
|
168
|
+
hoox keys generate
|
|
169
|
+
|
|
170
|
+
# List existing keys
|
|
171
|
+
hoox keys list
|
|
172
|
+
```
|
|
173
|
+
|
|
117
174
|
### Configure Environment
|
|
118
175
|
|
|
119
176
|
```bash
|
|
@@ -130,6 +187,16 @@ hoox config env validate
|
|
|
130
187
|
hoox config env generate-dev-vars
|
|
131
188
|
```
|
|
132
189
|
|
|
190
|
+
### Manage wrangler.jsonc
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
# Display current configuration
|
|
194
|
+
hoox config show
|
|
195
|
+
|
|
196
|
+
# Update a config value
|
|
197
|
+
hoox config set workers.agent-worker.enabled false
|
|
198
|
+
```
|
|
199
|
+
|
|
133
200
|
### Manage KV Keys
|
|
134
201
|
|
|
135
202
|
```bash
|
|
@@ -171,7 +238,35 @@ hoox deploy kv-config
|
|
|
171
238
|
hoox deploy worker trade-worker
|
|
172
239
|
```
|
|
173
240
|
|
|
174
|
-
###
|
|
241
|
+
### Dashboard Operations
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
# Start dashboard dev server
|
|
245
|
+
hoox dashboard dev
|
|
246
|
+
# equivalent to: hoox dev dashboard
|
|
247
|
+
|
|
248
|
+
# Build and deploy the dashboard
|
|
249
|
+
hoox dashboard deploy
|
|
250
|
+
# equivalent to: hoox deploy dashboard
|
|
251
|
+
|
|
252
|
+
# Force rebuild before deploy
|
|
253
|
+
hoox dashboard deploy --rebuild
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Health Checks
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
# Check all worker health endpoints (the single source of truth)
|
|
260
|
+
hoox check health
|
|
261
|
+
|
|
262
|
+
# Try to auto-fix any issues found
|
|
263
|
+
hoox check health --fix
|
|
264
|
+
|
|
265
|
+
# Full system validation (config, infra, secrets, database)
|
|
266
|
+
hoox check setup
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Database Operations
|
|
175
270
|
|
|
176
271
|
```bash
|
|
177
272
|
# Apply schema to local or remote
|
|
@@ -213,9 +308,6 @@ hoox infra analytics list
|
|
|
213
308
|
### Monitor Operations
|
|
214
309
|
|
|
215
310
|
```bash
|
|
216
|
-
# Check all worker health endpoints
|
|
217
|
-
hoox monitor status
|
|
218
|
-
|
|
219
311
|
# Show recent trades
|
|
220
312
|
hoox monitor trades 20
|
|
221
313
|
|
|
@@ -235,6 +327,19 @@ hoox monitor queue-depth
|
|
|
235
327
|
hoox monitor backup
|
|
236
328
|
```
|
|
237
329
|
|
|
330
|
+
### Performance Measurement
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
# Send 50 synthetic probes and report p50/p95/p99 latency
|
|
334
|
+
hoox perf fastpath run --n 50
|
|
335
|
+
|
|
336
|
+
# Continuous probing for 60 seconds
|
|
337
|
+
hoox perf fastpath tail --duration 60
|
|
338
|
+
|
|
339
|
+
# Query past probe events
|
|
340
|
+
hoox perf fastpath report --from 1h
|
|
341
|
+
```
|
|
342
|
+
|
|
238
343
|
### Repair and Recovery
|
|
239
344
|
|
|
240
345
|
```bash
|
|
@@ -263,8 +368,8 @@ hoox repair rebuild
|
|
|
263
368
|
### JSON Output for Scripting
|
|
264
369
|
|
|
265
370
|
```bash
|
|
371
|
+
hoox check health --json
|
|
266
372
|
hoox check prerequisites --json
|
|
267
|
-
hoox monitor status --json
|
|
268
373
|
hoox infra d1 list --json
|
|
269
374
|
```
|
|
270
375
|
|
|
@@ -330,16 +435,20 @@ packages/cli/
|
|
|
330
435
|
├── src/
|
|
331
436
|
│ ├── index.ts # Main entry point
|
|
332
437
|
│ ├── commands/
|
|
333
|
-
│ │ ├── init/ # Interactive setup wizard
|
|
438
|
+
│ │ ├── init/ # Interactive setup wizard (config)
|
|
334
439
|
│ │ ├── setup/ # Auto-bootstrap infrastructure
|
|
440
|
+
│ │ ├── onboard/ # One-shot init + setup
|
|
441
|
+
│ │ ├── secrets/ # Top-level secrets management
|
|
442
|
+
│ │ ├── keys/ # Top-level internal keys management
|
|
335
443
|
│ │ ├── dev/ # Local development
|
|
336
444
|
│ │ ├── deploy/ # Deploy, telegram-webhook, update-internal-urls
|
|
445
|
+
│ │ ├── dashboard/ # Dashboard dev/deploy
|
|
337
446
|
│ │ ├── infra/ # D1, KV, R2, Queues, Vectorize, Analytics
|
|
338
|
-
│ │ ├── config/ #
|
|
339
|
-
│ │ ├── check/ # Prerequisites, setup, health
|
|
447
|
+
│ │ ├── config/ # wrangler.jsonc, env, kv
|
|
448
|
+
│ │ ├── check/ # Prerequisites, setup, health, fix
|
|
340
449
|
│ │ ├── db/ # Database operations
|
|
341
|
-
│ │ ├── monitor/ #
|
|
342
|
-
│ │ ├── workers/ #
|
|
450
|
+
│ │ ├── monitor/ # Trades, logs, kill-switch, backup
|
|
451
|
+
│ │ ├── workers/ # List, dev, logs
|
|
343
452
|
│ │ ├── repair/ # Check, worker, infra, secrets, rebuild
|
|
344
453
|
│ │ ├── schema/ # Schema management
|
|
345
454
|
│ │ ├── update/ # Self-update
|
|
@@ -347,9 +456,10 @@ packages/cli/
|
|
|
347
456
|
│ │ ├── test/ # CI pipeline
|
|
348
457
|
│ │ ├── waf/ # WAF management
|
|
349
458
|
│ │ ├── clone/ # Submodule cloning
|
|
350
|
-
│ │ ├── dashboard/ # Dashboard operations
|
|
351
459
|
│ │ ├── tui/ # TUI launcher
|
|
352
460
|
│ │ ├── agent/ # AI agent operations
|
|
461
|
+
│ │ ├── trace/ # Cloudflare Observability queries
|
|
462
|
+
│ │ ├── perf/ # Performance measurement
|
|
353
463
|
│ │ └── disclaimer/ # Legal disclaimer
|
|
354
464
|
│ ├── services/
|
|
355
465
|
│ │ ├── cloudflare/ # Wrangler CLI wrapper
|
|
@@ -358,6 +468,7 @@ packages/cli/
|
|
|
358
468
|
│ │ ├── docker/ # Docker compose wrapper
|
|
359
469
|
│ │ ├── env/ # Environment definitions
|
|
360
470
|
│ │ ├── kv/ # KV key management
|
|
471
|
+
│ │ ├── perf/ # Percentile, probe-sender, observability-reader
|
|
361
472
|
│ │ ├── prerequisites/ # Tool version checks
|
|
362
473
|
│ │ └── secrets/ # Secret management
|
|
363
474
|
│ ├── ui/ # Interactive TUI
|