fix(explore): handle single -F flag as array to prevent TypeError

[sentry]

This PR addresses CLI-28C, a TypeError occurring in the explore command.

Root Cause:
The flags.field argument in src/commands/explore.ts is defined as variadic: true. However, when a user supplies only a single -F flag, the CLI parser assigns a string to flags.field instead of a single-element array. The command function then blindly assigns fieldList = flags.field, making fieldList a string. Subsequent calls to .find() on fieldList (e.g., in resolveDatasetConfig or findFirstAggregate) then fail with TypeError: e.find is not a function because strings do not have a .find() method.

Fix:
To resolve this, flags.field is now explicitly coerced to an array before being assigned to fieldList. This ensures that fieldList is always an array, regardless of whether one or multiple -F flags were provided, thus preventing the TypeError.

Fixes CLI-28C

_{Comment @sentry <feedback> on this PR to have Autofix iterate on the changes.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1218/
Built to branch gh-pages at 2026-07-09 23:09 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[sentry-warden]

Single -F flag still causes TypeError in appendFieldHints via appendFlagHints

The fix normalizes flags.field into fieldList but leaves the raw flags.field string un-normalized. appendFlagHints is called with hintFlags = { ...flags, dataset }, so hintFlags.field remains the bare string, which is passed to appendFieldHints. There the string reaches fields.filter(...) (when --metric is active) or fieldList.join(",") (the common non-metric case) — both throw TypeError because strings lack those array methods, reproducing the same crash the PR set out to fix.

Evidence

• flags.field is typed string[] | undefined but the CLI parser emits a string for a single -F flag (the PR's root cause).
• The fix at line 716 coerces flags.field into a local fieldList, but never mutates or re-binds flags.field itself.
• hintFlags = { ...flags, dataset } (line ~803) spreads the original flags, so hintFlags.field stays the raw string.
• Both prevHint/nextHint are evaluated eagerly as arguments to paginationHint, so appendFlagHints runs on every invocation regardless of pagination state.
• In appendFieldHints, const fields = rawFields ?? [] keeps the string; non-metric path hits fieldList.join(",") and metric path hits fields.filter(...), both throwing on a string.

_{Identified by Warden find-bugs · PQ4-HKP}

[sentry]

Bug: The appendFieldHints function crashes with a TypeError because it receives a string for flags.field when a single -F flag is used.
_{Severity: HIGH}

Suggested Fix

Ensure that flags.field is always an array before it is used by the hint generation functions. Similar to how fieldList is created, the flags.field property on the hintFlags object should be normalized to an array if it is a string. This will prevent the TypeError when .filter() is called within appendFieldHints.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/commands/explore.ts#L716

Potential issue: When a user provides a single `-F` flag to the `explore` command, the
CLI parser sets `flags.field` to a string. While the main query logic correctly handles
this by converting it to an array, the pagination hint generation logic does not. It
uses a shallow copy of the original `flags` object, passing the string value of
`flags.field` to the `appendFlagHints` function, and subsequently to `appendFieldHints`.
The `appendFieldHints` function expects an array and attempts to call `.filter()` on the
string, which results in a `TypeError` and causes the command to crash after a
successful query.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 487dba7. Configure here.}

[cursor]

Incomplete field array coercion

High Severity

The single -F coercion only updates fieldList, while pagination hint building still passes the raw flags.field into appendFieldHints. With one -F, that value remains a string, so .join or .filter still throws after the query succeeds and the command never returns results.

Additional Locations (2)

• src/commands/explore.ts#L373-L374
• src/commands/explore.ts#L802-L814

 

^{Reviewed by Cursor Bugbot for commit 487dba7. Configure here.}

[github-actions]

Codecov Results 📊

✅ Patch coverage is 100.00%. Project has 5318 uncovered lines.
✅ Project coverage is 81.88%. Comparing base (base) to head (head).

Files with missing lines (1)

File	Patch %	Lines
src/commands/explore.ts	100.00%	⚠️ 1 partials

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.83%    81.88%    +0.05%
==========================================
  Files          423       423         —
  Lines        29343     29343         —
  Branches     19117     19119        +2
==========================================
+ Hits         24009     24025       +16
- Misses        5334      5318       -16
- Partials      1988      1995        +7

---

Generated by Codecov Action