@drod915/q9s 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +192 -3
- package/dist/cli.js +3089 -0
- package/dist/index.d.ts +294 -0
- package/dist/index.js +3137 -0
- package/package.json +62 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 flipcyde101
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,192 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# q9s
|
|
2
|
+
|
|
3
|
+
**`k9s` for background job queues.** A zero-dependency Node.js CLI for inspecting BullMQ (Redis), River (Postgres), and pg-boss (Postgres) queues and dead-letter queues (DLQs) safely from your terminal.
|
|
4
|
+
|
|
5
|
+
> [!IMPORTANT]
|
|
6
|
+
> **Read-only by default (`--read-only`).** `q9s` refuses all mutations unless you explicitly pass `--allow-write`. Bulk retries additionally require `--yes`. Passwords in Redis/Postgres URLs and named contexts are always redacted in terminal and JSON output.
|
|
7
|
+
|
|
8
|
+
## 15-second demo
|
|
9
|
+
|
|
10
|
+
[](./docs/media/q9s-scoped-demo.mp4)
|
|
11
|
+
|
|
12
|
+
[Open the demo video (MP4)](./docs/media/q9s-scoped-demo.mp4)
|
|
13
|
+
|
|
14
|
+
## Try it in 1 second
|
|
15
|
+
|
|
16
|
+
Run the self-contained demo (starts a live in-process mock BullMQ Redis TCP server over localhost, talks real RESP2, auto-discovers 3 queues, renders sparklines and the spiking `webhooks` DLQ stack trace, and shuts down cleanly):
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npx @drod915/q9s --demo
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Machine-readable JSON mode:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npx @drod915/q9s --demo --json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Inspect a specific queue:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx @drod915/q9s --demo --inspect billing-sync
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Architecture
|
|
35
|
+
|
|
36
|
+
```mermaid
|
|
37
|
+
flowchart LR
|
|
38
|
+
CLI["q9s CLI<br/>(--demo / URL / --ctx)"] --> Guard["Safety Gate<br/>--read-only default<br/>--allow-write + --yes"]
|
|
39
|
+
Guard --> Bull["BullMqBackend<br/>src/backends/bullmq.ts"]
|
|
40
|
+
Guard --> Pg["PostgresQueueBackend<br/>src/backends/postgres.ts"]
|
|
41
|
+
Bull --> Resp["Pure-TS RESP2 Client<br/>node:net / node:tls"]
|
|
42
|
+
Resp --> Redis[("Redis / Valkey<br/>bull:*:meta, wait, failed")]
|
|
43
|
+
Pg --> Psql["psql CLI (execFileSync)<br/>PGPASSWORD + read-only txn"]
|
|
44
|
+
Psql --> Postgres[("PostgreSQL<br/>river_job / pgboss.job")]
|
|
45
|
+
Bull --> Render["Dashboard & Sparkline Renderer<br/>Terminal UI / --json"]
|
|
46
|
+
Pg --> Render
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Features
|
|
50
|
+
|
|
51
|
+
- **Zero runtime npm dependencies**: pure TypeScript over Node.js 24 built-ins (`node:net`, `node:tls`, `node:child_process`). No native addons, no heavy web frameworks.
|
|
52
|
+
- **BullMQ over raw RESP2**: connects directly over `redis://` or `rediss://`, supports `AUTH` and `SELECT`, auto-discovers `bull:*:meta` queues, reads `LLEN`/`ZCARD` counts and `HGETALL` job payloads, and executes atomic `MULTI`/`EXEC` retries.
|
|
53
|
+
- **River & pg-boss over safe `psql`**: auto-detects `river_job` vs `pgboss.job`, isolates credentials via `PGPASSWORD` env vars (never in process args or logs), enforces `default_transaction_read_only=on` for reads, and validates queue names and job IDs strictly before querying.
|
|
54
|
+
- **DLQ Inspector**: renders pretty-printed JSON job payloads, attempt counters, failure reasons, and stack traces alongside Unicode throughput sparklines (`▁▂▃▄▅▆▇█`).
|
|
55
|
+
- **Named contexts**: switch between environments using `~/.config/q9s/contexts.json` or `~/.config/q9s/contexts.yaml` with automatic credential redaction and per-context `readOnly: true` pinning.
|
|
56
|
+
|
|
57
|
+
## Honest Comparison
|
|
58
|
+
|
|
59
|
+
| Capability | `q9s` (v0.1) | Bull Board | River UI | pg-boss Studio | `redis-cli` / `psql` |
|
|
60
|
+
| --- | --- | --- | --- | --- | --- |
|
|
61
|
+
| Interface | Terminal CLI + `--json` | Self-hosted Web UI | Self-hosted Web UI | Self-hosted Web UI | Raw REPL |
|
|
62
|
+
| Zero app integration required | Yes (point at Redis/PG) | No (mount middleware) | No (run Go server) | No (run web server) | Yes |
|
|
63
|
+
| Multi-backend (BullMQ + River + pg-boss) | Yes | BullMQ only | River only | pg-boss only | Manual queries |
|
|
64
|
+
| Read-only by default | Yes (`--read-only`) | Opt-in config | Opt-in config | Opt-in config | No |
|
|
65
|
+
| Runtime dependencies | 0 npm packages | Express/Fastify + UI | Go binary | Node + web stack | Native client |
|
|
66
|
+
| Interactive fullscreen TUI / live tail | Planned (v0.2+) | Web auto-refresh | Web auto-refresh | Web auto-refresh | Manual `watch` |
|
|
67
|
+
| Job creation / payload editing | Not in v0.1 | Yes | Limited | Yes | Manual |
|
|
68
|
+
|
|
69
|
+
## Installation
|
|
70
|
+
|
|
71
|
+
Requires **Node.js >= 24.0.0**. Postgres backends require `psql` on your `PATH`.
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npm install -g @drod915/q9s
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or run directly with `npx`:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
npx @drod915/q9s redis://localhost:6379
|
|
81
|
+
npx @drod915/q9s postgres://app:secret@localhost:5432/mydb
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Named Contexts
|
|
85
|
+
|
|
86
|
+
Create `~/.config/q9s/contexts.json` (or `~/.config/q9s/contexts.yaml`):
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"contexts": {
|
|
91
|
+
"prod-bull": {
|
|
92
|
+
"url": "rediss://default:supersecret@redis.internal:6379/0",
|
|
93
|
+
"backend": "bullmq",
|
|
94
|
+
"prefix": "bull",
|
|
95
|
+
"readOnly": true
|
|
96
|
+
},
|
|
97
|
+
"staging-river": {
|
|
98
|
+
"url": "postgres://app:supersecret@db.staging.internal:5432/app",
|
|
99
|
+
"backend": "river",
|
|
100
|
+
"schema": "public"
|
|
101
|
+
},
|
|
102
|
+
"staging-pgboss": {
|
|
103
|
+
"url": "postgres://app:supersecret@db.staging.internal:5432/app",
|
|
104
|
+
"backend": "pg-boss",
|
|
105
|
+
"schema": "pgboss"
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Or in simple YAML (`~/.config/q9s/contexts.yaml`):
|
|
112
|
+
|
|
113
|
+
```yaml
|
|
114
|
+
contexts:
|
|
115
|
+
prod-bull:
|
|
116
|
+
url: rediss://default:supersecret@redis.internal:6379/0
|
|
117
|
+
backend: bullmq
|
|
118
|
+
readOnly: true
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Use contexts from the CLI:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
# List contexts (credentials are always redacted)
|
|
125
|
+
q9s --contexts
|
|
126
|
+
|
|
127
|
+
# Inspect a named context
|
|
128
|
+
q9s --ctx prod-bull
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Safe Retry Workflows
|
|
132
|
+
|
|
133
|
+
By default, any mutation flag is refused with exit code `2`:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# Refused in default read-only mode:
|
|
137
|
+
q9s --demo --retry wh-4814 --queue webhooks
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Unlock a single job retry explicitly:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
q9s redis://localhost:6379 --queue webhooks --retry wh-4814 --allow-write
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Unlock a bulk DLQ retry (requires both `--allow-write` and `--yes`):
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
q9s redis://localhost:6379 --retry-failed webhooks --limit 25 --allow-write --yes
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Contexts marked `"readOnly": true` in config refuse `--allow-write` even if passed on the command line.
|
|
153
|
+
|
|
154
|
+
## CLI Reference
|
|
155
|
+
|
|
156
|
+
| Flag | Description |
|
|
157
|
+
| --- | --- |
|
|
158
|
+
| `<url>` | Target `redis://`, `rediss://`, `postgres://`, or `postgresql://` URL |
|
|
159
|
+
| `--demo` | Launch live in-process mock BullMQ Redis TCP server with realistic DLQ data |
|
|
160
|
+
| `--ctx <name>` | Load named context from `~/.config/q9s/contexts.json` or `.yaml` |
|
|
161
|
+
| `--contexts` | Print configured contexts with redacted credentials |
|
|
162
|
+
| `--config <path>` | Explicit contexts file path (or set `Q9S_CONFIG`) |
|
|
163
|
+
| `--backend <kind>` | Override auto-detection: `bullmq`, `river`, or `pg-boss` |
|
|
164
|
+
| `--prefix <prefix>` | BullMQ Redis key prefix (default: `bull`) |
|
|
165
|
+
| `--schema <schema>` | Postgres schema override (default: auto-detected) |
|
|
166
|
+
| `--timeout <ms>` | Connection/query timeout in ms (default: `5000`) |
|
|
167
|
+
| `--inspect <queue>` | Inspect jobs in a specific queue (default: queue with most failed jobs) |
|
|
168
|
+
| `--state <state>` | Job state: `waiting`, `active`, `delayed`, `completed`, `failed` (default: `failed`) |
|
|
169
|
+
| `--limit <n>` | Max jobs to inspect (default: `3`) or bulk-retry (default: `100`) |
|
|
170
|
+
| `--read-only` | Enforce read-only mode (default: `true`) |
|
|
171
|
+
| `--allow-write` | Explicitly allow `--retry` and `--retry-failed` mutations |
|
|
172
|
+
| `--retry <jobId>` | Retry one failed job (requires `--queue`/`--inspect` and `--allow-write`) |
|
|
173
|
+
| `--queue <queue>` | Target queue for `--retry` |
|
|
174
|
+
| `--retry-failed <queue>` | Bulk retry failed jobs in `<queue>` (requires `--allow-write` and `--yes`) |
|
|
175
|
+
| `-y`, `--yes` | Confirm bulk write action |
|
|
176
|
+
| `--json` | Emit structured JSON |
|
|
177
|
+
| `--no-color` | Disable ANSI colors |
|
|
178
|
+
| `-h`, `--help` | Show CLI usage |
|
|
179
|
+
| `-v`, `--version` | Show version |
|
|
180
|
+
|
|
181
|
+
## Development
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
npm install
|
|
185
|
+
npm run typecheck
|
|
186
|
+
npm run build
|
|
187
|
+
npm test
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## License
|
|
191
|
+
|
|
192
|
+
MIT. See [LICENSE](./LICENSE).
|