From 72bbb4c8a0b738c51dc314a80e96079de92cc7bc Mon Sep 17 00:00:00 2001
From: Fendy <xingfen.fendy@outlook.com>
Date: Tue, 28 Jul 2026 23:52:23 +0800
Subject: [PATCH] docs: verbose/debug mode design spec

---
 docs/spec/2026-07-28-verbose-debug-design.md | 70 ++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 docs/spec/2026-07-28-verbose-debug-design.md

diff --git a/docs/spec/2026-07-28-verbose-debug-design.md b/docs/spec/2026-07-28-verbose-debug-design.md
new file mode 100644
index 0000000..650025a
--- /dev/null
+++ b/docs/spec/2026-07-28-verbose-debug-design.md
@@ -0,0 +1,70 @@
+# Verbose/Debug Mode Design
+
+**Date:** 2026-07-28
+**Status:** Approved
+
+## Goal
+
+Wire up the existing `--debug` flag (currently unused) and add `--verbose` as an alias. When enabled, print detailed runtime and HTTP request information to stderr.
+
+## Scope
+
+4 files modified, 0 new files.
+
+## Changes
+
+### 1. `internal/provider/provider.go` — ProviderConfig
+
+Add `Debug bool` field to `ProviderConfig`:
+
+```go
+type ProviderConfig struct {
+    APIKey          string
+    AccessKeyID     string
+    AccessKeySecret string
+    Endpoint        string
+    Debug           bool
+}
+```
+
+### 2. `cmd/cli/root.go` — Flag + Runtime Info
+
+- Register `--verbose` as alias for `--debug` (both set `flagDebug`)
+- In `PersistentPreRunE`, when debug is on, print to stderr:
+  - Provider name
+  - Config file path
+  - Output format
+
+### 3. `internal/provider/rainyun/client.go` — HTTP Logging
+
+- Add `debug bool` field to `client` struct
+- Update `newClient(endpoint, apiKey string, debug bool)` signature
+- In `do()`, when `c.debug` is true, print to `os.Stderr`:
+  - Request: `> METHOD /path` + request body (if any)
+  - Response: `< StatusCode StatusText Duration` + response body
+
+### 4. `internal/provider/rainyun/rainyun.go` — Pass Debug
+
+- `New()` passes `cfg.Debug` to `newClient()`
+
+## Output Format
+
+All debug output goes to **stderr** to avoid polluting stdout data pipeline.
+
+```
+[debug] provider: rainyun
+[debug] config: /Users/user/.config/ry/config.json
+[debug] output: table
+[debug] > GET /api/v2/servers
+[debug] < 200 OK 123ms
+[debug] {"code":200,"data":[...]}
+```
+
+## Files
+
+| File | Change |
+|------|--------|
+| `internal/provider/provider.go` | Add `Debug` to `ProviderConfig` |
+| `cmd/cli/root.go` | Wire `--verbose`, print runtime info |
+| `internal/provider/rainyun/client.go` | HTTP request/response logging |
+| `internal/provider/rainyun/rainyun.go` | Pass `cfg.Debug` to client |