Better error messages

PLAN.md

@@ -1,262 +1,81 @@
-# Plan: `wait_for` Feature - DX Design
+# Plan: Better Error Messages & Debuggability
 
-## Overview
-
-A new `wait_for` block that repeatedly polls an endpoint until a condition is satisfied. Designed for async server operations that require time to complete (job processing, webhooks, eventual consistency, etc.).
-
-## DX Design
-
-### Basic Syntax
-
-```yaml
-yapi: v1
-url: ${url}/jobs/${job_id}
-method: GET
-
-wait_for:
-  until:
-    - .status == "completed"
-  period: 2s
-  timeout: 60s
-```
-
-### Fixed Period (Simple)
-
-```yaml
-wait_for:
-  until:
-    - .status == "completed"
-  period: 2s          # Fixed time between attempts
-  timeout: 60s        # Total time limit
-```
-
-### Exponential Backoff
-
-```yaml
-wait_for:
-  until:
-    - .status == "completed"
-  backoff:
-    seed: 1s          # Initial wait time
-    multiplier: 2     # Each attempt waits multiplier * previous
-  timeout: 60s        # Total time limit
-```
-
-Backoff example with `seed: 1s, multiplier: 2`:
-- Attempt 1 → wait 1s
-- Attempt 2 → wait 2s
-- Attempt 3 → wait 4s
-- Attempt 4 → wait 8s
-- ...continues until timeout
-
-### Behavior
-
-1. Execute the request
-2. If `until` conditions pass → success, stop polling
-3. If `until` conditions fail OR request errors (5xx, network) → wait (period or backoff), retry
-4. If `timeout` exceeded → fail with timeout error
-
-**Error handling**: Intermediate failures (5xx, network errors, 4xx) are treated as "not ready yet" and polling continues. Only timeout causes failure.
-
-**Timing**: Either `period` OR `backoff` must be specified (mutually exclusive).
+## Context
+Implementing WISHLIST.md items #1, #2, and #4 (removing #3 since `yapi send` already exists).
 
 ---
 
-## Use Cases
-
-### 1. Single Request - Job Completion
-
-```yaml
-yapi: v1
-url: ${url}/jobs/${job_id}
-method: GET
+## 1. WISHLIST.md cleanup
+Remove item #3 (yapi send) since it's already shipped.
 
-wait_for:
-  until:
-    - .status == "completed" or .status == "failed"
-  period: 2s
-  timeout: 120s
-
-expect:
-  status: 200
-  assert:
-    - .status == "completed"  # Final assertion after wait_for succeeds
-```
-
-### 2. Chain Step - Async Workflow
-
-```yaml
-yapi: v1
-chain:
-  - name: create_job
-    url: ${url}/jobs
-    method: POST
-    body:
-      type: "data_export"
-    expect:
-      status: 202
-      assert:
-        - .job_id != null
-
-  - name: wait_for_job
-    url: ${url}/jobs/${create_job.job_id}
-    method: GET
-    wait_for:
-      until:
-        - .status == "completed"
-      backoff:
-        seed: 1s
-        multiplier: 2
-      timeout: 300s
-    expect:
-      status: 200
-      assert:
-        - .download_url != null
-
-  - name: download_result
-    url: ${wait_for_job.download_url}
-    method: GET
-    output_file: ./export.csv
-```
-
-### 3. Webhook/Callback Waiting
+---
 
-```yaml
-yapi: v1
-chain:
-  - name: trigger_webhook
-    url: ${url}/webhooks/trigger
-    method: POST
+## 2. Warn on bare `$word.word` variable syntax (WISHLIST #1)
 
-  - name: check_received
-    url: ${url}/webhooks/received
-    method: GET
-    wait_for:
-      until:
-        - . | length > 0
-        - .[0].payload.event == "user.created"
-      period: 1s
-      timeout: 30s
-```
+The problem: `$step.field` (no braces) silently passes as a literal string instead of being substituted. Only `${step.field}` works.
 
-### 4. Database Eventual Consistency
+**Changes:**
 
-```yaml
-yapi: v1
-chain:
-  - name: create_user
-    url: ${url}/users
-    method: POST
-    body:
-      email: "test@example.com"
-    expect:
-      status: 201
+- **`cli/internal/vars/vars.go`**: Add a `BareChainRef` regex that matches `$word.word` patterns that are NOT inside `${...}`.
+- **`cli/internal/vars/vars.go`**: Add `FindBareRefs(s string) []string` that returns the bare refs found.
+- **`cli/internal/validation/analyzer.go`**: In `analyzeParsed()`, call a new `warnBareChainRefs(text)` validation function that scans the raw YAML text for bare `$word.word` patterns and emits `SeverityWarning` diagnostics with line numbers and an actionable message like:
+  `"possible bare variable reference '$step.field' -- did you mean '${step.field}'? Only the ${...} form is substituted."`
 
-  - name: verify_searchable
-    url: ${url}/users/search?email=test@example.com
-    method: GET
-    wait_for:
-      until:
-        - . | length == 1
-      period: 500ms
-      timeout: 10s
-```
+This catches the problem at config analysis time (before execution), so users see the warning immediately -- even in `yapi validate`.
 
 ---
 
-## Interaction with Existing Features
-
-### With `expect`
+## 3. Show resolved request details in verbose chain execution (WISHLIST #2)
 
-`wait_for` runs first. Once `until` conditions pass, `expect` runs on the final response:
+The problem: When a chain step fails, you can't see what values were actually sent because variable substitution is invisible.
 
-```yaml
-wait_for:
-  until:
-    - .status != "pending"  # Wait until not pending
-  period: 1s
-  timeout: 30s
+**Changes:**
 
-expect:
-  status: 200
-  assert:
-    - .status == "completed"  # Then verify it's completed (not failed)
-```
+- **`cli/internal/runner/runner.go`**: Add `Verbose bool` field to `runner.Options`.
+- **`cli/internal/runner/runner.go`**: In `RunChain()`, after `interpolateConfig()` succeeds and before executing, if `opts.Verbose` is true, print the resolved config to stderr:
+  - Resolved URL (with method)
+  - Resolved headers
+  - Resolved body (JSON-serialized if map, or raw if string)
+  - Uses `fmt.Fprintf(os.Stderr, ...)` with `[VERBOSE]` prefix, consistent with the existing Logger pattern.
+- **`cli/cmd/yapi/run.go`**: Set `opts.Verbose = ctx.verbose` when building runner.Options in `executeRunE()`.
 
-### With `timeout`
-
-The existing `timeout` field is per-request. `wait_for.timeout` is total polling time:
-
-```yaml
-timeout: 5s  # Each poll attempt times out after 5s
+---
 
-wait_for:
-  until:
-    - .ready == true
-  period: 2s
-  timeout: 60s  # Total polling time limit
-```
+## 4. Print step responses in verbose chain mode (WISHLIST #4)
 
-### With `delay`
+The problem: In chain execution, you only see the final failing step's output, not intermediate step responses.
 
-`delay` happens before `wait_for` starts:
+**Changes:**
 
-```yaml
-delay: 5s  # Wait 5s before starting to poll
+- **`cli/internal/runner/runner.go`**: In `RunChain()`, after each step executes, if `opts.Verbose` is true, print the step's response details to stderr:
+  - Status code
+  - Response body (truncated at 1000 chars for readability)
+  - Duration
 
-wait_for:
-  until:
-    - .status == "done"
-  period: 2s
-  timeout: 30s
-```
+  This replaces the need for a per-step `debug: true` field -- verbose mode shows everything, which is simpler and avoids new config surface area.
 
 ---
 
-## Output During Polling
+## 5. Example files: `examples/debugging/`
 
-When running with verbose/default output:
+Create example `.yapi.yml` files that demonstrate the improved debugging experience:
 
-```
-[POLL] Attempt 1 - conditions not met, retrying in 2s...
-[POLL] Attempt 2 - conditions not met, retrying in 2s...
-[POLL] Attempt 3 - request failed (503), retrying in 2s...
-[POLL] Attempt 4 - conditions met!
-```
+- **`bare-variable-warning.yapi.yml`**: A chain that uses `$step.field` (bare) to trigger the new warning.
+- **`chain-verbose-demo.yapi.yml`**: A multi-step chain against jsonplaceholder with variables that shows how `--verbose` reveals resolved values.
+- **`assertion-failure-demo.yapi.yml`**: A request with an `expect:` block that will fail, showing the detailed assertion error output.
+- **`missing-key-demo.yapi.yml`**: A chain that references a nonexistent JSON key, showing the precise error path.
 
 ---
 
-## Config Schema
-
-```go
-type Backoff struct {
-    Seed       string  `yaml:"seed"`       // Initial wait, e.g., "1s"
-    Multiplier float64 `yaml:"multiplier"` // e.g., 2
-}
-
-type WaitFor struct {
-    Until   []string `yaml:"until"`             // Required: JQ assertions
-    Period  string   `yaml:"period,omitempty"`  // Fixed interval, e.g., "2s"
-    Backoff *Backoff `yaml:"backoff,omitempty"` // Exponential backoff
-    Timeout string   `yaml:"timeout"`           // Required: total time limit
-}
-```
-
-Added to `ConfigV1`:
-```go
-type ConfigV1 struct {
-    // ... existing fields ...
-    WaitFor *WaitFor `yaml:"wait_for,omitempty"`
-}
-```
-
----
+## Files changed
 
-## Validation Rules
+| File | Change |
+|------|--------|
+| `WISHLIST.md` | Remove item #3 |
+| `cli/internal/vars/vars.go` | Add `BareChainRef` regex + `FindBareRefs()` function |
+| `cli/internal/validation/analyzer.go` | Add `warnBareChainRefs()`, call from `analyzeParsed()` |
+| `cli/internal/runner/runner.go` | Add `Verbose` to `Options`, add verbose logging in `RunChain()` |
+| `cli/cmd/yapi/run.go` | Thread `verbose` into `runner.Options` |
+| `examples/debugging/*.yapi.yml` | 4 new example files |
 
-1. `until` is required and must have at least one assertion
-2. `timeout` is required and must be valid Go duration
-3. Exactly one of `period` OR `backoff` must be specified (mutually exclusive)
-4. If `period`: must be valid Go duration
-5. If `backoff`: `seed` must be valid Go duration, `multiplier` must be > 1
-6. All `until` expressions must be valid JQ
+**No new dependencies. No config schema changes. No breaking changes.**

WISHLIST.md

@@ -0,0 +1,21 @@
+# YAPI Wishlist
+
+Issues encountered while writing MIDI clip note tests against the Ableton Live Remote Script.
+
+## 1. Chain variable syntax not documented clearly
+
+YAPI uses `${step.result.field}` (curly braces required), but the old docs and some examples show `$step.result.field` (bare dollar sign). The bare form is silently passed as a literal string rather than substituted, which makes debugging painful — the Remote Script receives the string `"$create_track.result.index"` instead of `3`.
+
+**Wish:** Either support both forms, or emit a clear warning when a string matching `$word.word` is found without braces.
+
+## 2. No way to inspect resolved variable values
+
+When a chain step fails, the output shows the raw response but not the resolved parameter values that were sent. If variable substitution silently fails (e.g., wrong syntax), you can't tell from the output.
+
+**Wish:** Show the resolved request body in verbose/debug mode so you can verify what was actually sent over the wire.
+
+## 3. No way to print step results mid-chain for debugging
+
+When a chain step fails, you get the response for the failing step but not intermediate steps (unless you scroll through the full output). Being able to mark a step as `debug: true` to print its full response would help.
+
+**Wish:** `debug: true` on chain steps to always print the full response body, or a `--verbose` flag that prints all step responses.

cli/cmd/yapi/run.go

@@ -206,6 +206,7 @@ func (app *rootCommand) executeRunE(ctx runContext) error {
 		NoColor:        app.noColor,
 		BinaryOutput:   app.binaryOutput,
 		Insecure:       app.insecure,
+		Verbose:        ctx.verbose,
 		ConfigFilePath: ctx.path,
 		StrictEnv:      ctx.strictEnv,
 	}