json_array_subset helper

Purpose

/Users/vinny/.openclaw/workspace/scripts/json_array_subset.py is the first saved helper in the local helper library for routine JSON parsing and filtering.

It replaces recurring python3 <<'PY' heredocs used to:

• pull subsets from top-level JSON arrays
• export named company or ID lists
• check for field presence before follow-on work

Supported modes

Exactly one filter mode is allowed per run:

• --match FIELD=VALUE: exact-match filter, with JSON-literal parsing when possible
• --one-of FIELD: membership filter using repeated --value flags and/or --values-file
• --exists FIELD: keep items where the field path exists

Other behavior:

• accepts dot-path fields like company_scale.stage
• reads a top-level JSON array only
• writes to stdout by default, or --output <file>
• fails safely on missing files, invalid JSON, non-array top-level input, and invalid filter combinations

Example commands

python3 /Users/vinny/.openclaw/workspace/scripts/json_array_subset.py \
  /Users/vinny/.openclaw/workspace/data/lantronix-uas-workbench-phase1/docs/pilot-us-source-rows.json \
  --match xpo_tier=premium

python3 /Users/vinny/.openclaw/workspace/scripts/json_array_subset.py \
  /Users/vinny/.openclaw/workspace/data/lantronix-uas-workbench-phase1/docs/pilot-us-source-rows.json \
  --one-of name \
  --value "Silvus Technologies, Inc." \
  --value "Skyfish" \
  --output /Users/vinny/.openclaw/workspace/artifacts/pilot-name-subset.json

python3 /Users/vinny/.openclaw/workspace/scripts/json_array_subset.py \
  /Users/vinny/.openclaw/workspace/data/lantronix-uas-workbench-phase1/docs/pilot-us-source-rows.json \
  --exists year_founded --compact

Replacement value

Instead of embedding ad hoc parsing logic in shell heredocs, the agent can now call one small deterministic script by path. That reduces inline-eval usage, makes filtering behavior reusable, and gives clearer failure messages than one-off heredoc snippets.