fix(cli): preserve nested params in handler/settings JSON fields

[chubes4]

Summary

wp datamachine flow update <flow_id> --step=<step_id> --handler-config=<json> was corrupting nested-array values in any handler/settings field declared with type: 'json' (today: the SystemTask params field). The corruption stored params == "" (empty string) in flow_step_settings, which FlowStepConfig::getPrimaryHandlerConfig() reads preferentially over handler_config, breaking every subsequent flow run with array_merge(): Argument #1 must be of type array, string given at SystemTaskStep.php:211.

Closes #2059

Root cause

SettingsHandler::sanitizeField() (inc/Core/Steps/Settings/SettingsHandler.php) had no case 'json': branch. json-typed fields fell through to default: sanitizeText(), which calls sanitize_text_field( wp_unslash( $value ) ). WordPress's sanitize_text_field() coerces array/object input to an empty string, so any nested-array params payload was silently zeroed out before storage.

Live proof of the coercion (run against data-machine@main):

$ wp eval '
require_once "inc/Core/Steps/Settings/SettingsHandler.php";
require_once "inc/Core/Steps/SystemTask/SystemTaskSettings.php";
var_dump(\DataMachine\Core\Steps\SystemTask\SystemTaskSettings::sanitize([
  "task" => "dispatch_message",
  "params" => ["channel"=>"x","recipient"=>"y","message"=>"z"]
]));
'
array(2) {
  ["task"]   => string(16) "dispatch_message"
  ["params"] => string(0) ""              ← BUG
}

After the fix, the same input returns params as the expected nested array verbatim.

File list

• inc/Core/Steps/Settings/SettingsHandler.php — add case 'json': to the type switch and a new sanitizeJson() method that preserves nested arrays, decodes JSON-string payloads, and never returns a scalar string.
• tests/flow-update-handler-config-params-smoke.php — pure-PHP smoke test pinning the contract across six input shapes.

Reproduction (main fails, branch passes)

Smoke test results, same file, two checkouts of the same branch — one with the SettingsHandler.php fix stashed away (== main), one with it in place:

# stashed (== main):  0 / 17 passed
$ git stash push -- inc/Core/Steps/Settings/SettingsHandler.php
$ php tests/flow-update-handler-config-params-smoke.php
[1] nested-array params is preserved verbatim:
  ✗ params remains an array after sanitize
  ✗ params is not coerced to empty string
  ✗ nested params keys round-trip verbatim
    expected: array(channel/recipient/message)
    actual:   ''
[2] JSON-string params is decoded into a nested array:
  ✗ JSON-string params decodes to array
  ✗ JSON-string params decodes to the same nested shape
[3] params is never a scalar string (regression guard for SystemTaskStep array_merge):
  ✗ array_merge(params, [...]) succeeds (case: nested array)
    — array_merge(): Argument #1 must be of type array, string given
  ✗ array_merge(params, [...]) succeeds (case: JSON string)
    — array_merge(): Argument #1 must be of type array, string given
  ... (all 6 cases fail the same way)

0 / 17 passed

# with fix:  17 / 17 passed
$ git stash pop
$ php tests/flow-update-handler-config-params-smoke.php
[1] nested-array params is preserved verbatim:
  ✓ params remains an array after sanitize
  ✓ params is not coerced to empty string
  ✓ nested params keys round-trip verbatim
[2] JSON-string params is decoded into a nested array:
  ✓ JSON-string params decodes to array
  ✓ JSON-string params decodes to the same nested shape
[3] params is never a scalar string (regression guard for SystemTaskStep array_merge):
  ✓ params is an array + array_merge succeeds (6 cases × 2 asserts each)

17 / 17 passed

Regression sweep

Ran every smoke that touches SystemTask, FlowStep config, or the flow-update CLI path:

• tests/dispatch-message-task-smoke.php — 46/46 pass
• tests/flow-update-set-user-message-smoke.php — 35/35 pass
• tests/systemtask-passthrough-smoke.php — 29/29 pass
• tests/system-task-config-passthrough-smoke.php — 36/36 pass
• tests/system-run-task-params-smoke.php — 28/28 pass
• tests/flow-step-config-factory-smoke.php — 6/13 pass (pre-existing, fails identically on main; unrelated to this change)

phpcs clean on both changed files.

Scope discipline

• No CHANGELOG.md edits, no version bumps — homeboy owns those.
• No homeboy release, no homeboy deploy — PR only.
• The fix lives in the base SettingsHandler (right layer) instead of patching SystemTaskSettings, so every future handler that declares a json field gets the same correct behaviour for free.

cc <@532385681268408341>

[homeboy-ci]

Homeboy Results — data-machine

Lint

✅ lint — passed

ℹ️ Full options: homeboy docs commands/lint
Deep dive: homeboy lint data-machine --changed-since 6251ed9

Test

✅ test — passed

ℹ️ Auto-fix lint issues: homeboy refactor data-machine --from lint --write
ℹ️ Collect coverage: homeboy test data-machine --coverage
ℹ️ Pass args to test runner: homeboy test -- [args]
ℹ️ Full options: homeboy docs commands/test
Deep dive: homeboy test data-machine --changed-since 6251ed9

Audit

✅ audit — passed

• dead_code — 2 finding(s)
• requested_detectors — 1 finding(s)
• Total: 3 finding(s)

Deep dive: homeboy audit data-machine --changed-since 6251ed9

Tooling versions

• Homeboy CLI: homeboy 0.182.0+59845940
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: dd47f26a
• Action: unknown@unknown