@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 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
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ [![Q9S inspects a failed webhook job in read-only mode](./docs/media/q9s-scoped-poster.png)](./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).