Bug: `--rule-filter-headers` stores JSON as escaped string instead of parsing it

[leggetter]

Description

When using --rule-filter-headers with JSON format, the CLI stores the headers value as an escaped JSON string instead of parsing it as a JSON object. This results in double-escaping and makes the filter rule difficult to read and potentially incorrect.

IMPORTANT NOTE: Other flags that take JSON may have the same behavior.

Expected Behavior

When passing JSON to --rule-filter-headers, the CLI should parse the JSON and store it as a proper JSON object in the connection rules, matching the behavior when using the --rules flag with a properly structured rules array.

Actual Behavior

The headers value is stored as a stringified/escaped JSON string when using --rule-filter-headers, requiring manual unescaping to read the actual filter criteria.

Steps to Reproduce

Method 1: Using --rule-filter-headers flag (demonstrates the bug)

hookdeck connection upsert test-connection \
  --source-name test-source \
  --source-type WEBHOOK \
  --destination-name test-dest \
  --destination-type HTTP \
  --destination-url https://example.com/webhook \
  --rule-filter-headers '{"x-shopify-topic":{"$startsWith":"order/"}}' \
  --output json > output.json

Check the generated connection rules:

cat output.json | jq '.rules'

Observed output (incorrect):

[
  {
    "type": "filter",
    "headers": "{\"x-shopify-topic\":{\"$startsWith\":\"order/\"}}"
  }
]

Method 2: Using --rules flag (works correctly)

RULES_JSON='[{"type":"filter","headers":{"x-shopify-topic":{"$startsWith":"order/"}}}]'

hookdeck connection upsert test-connection \
  --source-name test-source \
  --source-type WEBHOOK \
  --destination-name test-dest \
  --destination-type HTTP \
  --destination-url https://example.com/webhook \
  --rules "$RULES_JSON" \
  --output json > output.json

Check the generated connection rules:

cat output.json | jq '.rules'

Observed output (correct):

[
  {
    "type": "filter",
    "headers": {
      "x-shopify-topic": {
        "$startsWith": "order/"
      }
    }
  }
]

Expected Output

Both methods should produce the same result - headers stored as a JSON object:

[
  {
    "type": "filter",
    "headers": {
      "x-shopify-topic": {
        "$startsWith": "order/"
      }
    }
  }
]

Workaround

Use the --rules flag with a full rules array instead of individual rule flags:

RULES_JSON='[{"type":"filter","headers":{"x-shopify-topic":{"$startsWith":"order/"}}}]'

hookdeck connection upsert test-connection \
  --source-name test-source \
  --source-type WEBHOOK \
  --destination-name test-dest \
  --destination-type HTTP \
  --destination-url https://example.com/webhook \
  --rules "$RULES_JSON" \
  --output json

Impact

This issue makes it difficult to:

• Read and verify filter rules in the connection output
• Understand what filters are actually applied
• Use the convenient --rule-filter-headers flag for header-based filtering
• Potentially causes issues with filter rule evaluation (needs verification)

Environment

• Hookdeck CLI version: [run hookdeck version to get your version]
• OS: [your OS]
• Shell: [your shell]

Additional Context

The --rule-filter-headers flag documentation mentions it accepts a "JQ expression", but when using JSON format (as shown in examples), the escaping behavior is unexpected. The --rules flag correctly handles JSON objects, suggesting this is a parsing issue specific to the --rule-filter-headers flag implementation.

[leggetter]

Same class of bug: --rule-retry-response-status-codes

While building automated verification tooling for our documentation code examples, we discovered that --rule-retry-response-status-codes has the same JSON serialization issue.

The flag accepts a value like "500-599" or "429,500,502", but sends it to the API as a string instead of an array. The API expects response_status_codes to be an array (e.g., ["429", "500", "502"]), so the request fails with a 422 UNPROCESSABLE_ENTITY.

Steps to reproduce

hookdeck connection upsert my-connection \
  --source-name my-source --source-type WEBHOOK \
  --destination-name my-dest --destination-type HTTP \
  --destination-url https://example.com/webhook \
  --rule-retry-strategy linear \
  --rule-retry-interval 60000 \
  --rule-retry-count 5 \
  --rule-retry-response-status-codes "500,502,503"

This fails with 422 because the CLI sends "response_status_codes": "500,502,503" (string) instead of "response_status_codes": ["500", "502", "503"] (array).

Workaround

Use --rules with a full JSON array:

hookdeck connection upsert my-connection \
  --source-name my-source --source-type WEBHOOK \
  --destination-name my-dest --destination-type HTTP \
  --destination-url https://example.com/webhook \
  --rules '[{"type": "retry", "strategy": "linear", "interval": 60000, "count": 5, "response_status_codes": ["500", "502", "503"]}]'

Broader pattern

This confirms the note in the original issue: other flags that take JSON or structured values likely have the same behavior. The individual --rule-* convenience flags appear to pass their values as raw strings rather than parsing them into the correct types expected by the API.

Our documentation has been updated to use --rules with full JSON as the workaround for both cases.