Add built-in --jq flag via gojq

[robzolkos]

Summary

• Adds a --jq persistent flag powered by gojq (pure Go jq implementation) that compiles into the binary — no external jq required
• Users and agents can filter/extract JSON inline: basecamp todos list --jq '.data[].title'
• --jq implies --json, works with --agent/--quiet, and string results print as plain text
• Updates the agent skill to prefer --jq over piping to external jq

Addresses QA feedback about agents reaching for external jq when users don't have it installed. With this change, the CLI is self-sufficient for JSON filtering.

Examples

# Extract todo titles
basecamp todos list --in <project> --jq '.data[].title'

# Count results
basecamp todos list --in <project> --jq '.data | length'

# Filter completed items
basecamp todos list --in <project> --jq '[.data[] | select(.completed == true)]'

# Pick specific fields
basecamp people list --jq '[.data[] | {name, email: .email_address}]'

---

Summary by cubic

Adds a built-in --jq flag powered by gojq to filter JSON directly in the CLI; it implies --json and works with --agent/--quiet. Includes early validation, clear usage errors, compact output, and safer error handling for jq filtering.

• New Features

  • Persistent --jq '<expr>' (built-in via gojq); implies --json.
  • Early validation: parse/compile before run; conflicts with --ids-only/--count are rejected.
  • Works with --agent/--quiet: filter runs on data-only; otherwise on the full envelope with normalized data.
  • Output: strings print as plain text; objects/arrays as compact single-line JSON; supports env access (env.VAR, $ENV.VAR).
  • Robust errors: jq validation/runtime/unsupported return usage errors; error rendering bypasses jq when needed; --jq counts as machine output.
  • Commands without structured output reject --jq with usage errors (version, login/setup, completion scripts, non-interactive skill); upgrade progress goes to stderr in machine mode; help lists --jq; Basecamp skill docs prefer --jq.

• Dependencies

  • Added github.com/itchyny/gojq v0.12.18.
  • Added indirect github.com/itchyny/timefmt-go v0.1.7.

^{Written for commit 5e4ee59. Summary will update on new commits.}

[Copilot]

Pull request overview

This PR adds a built-in --jq global flag (powered by gojq) so the Basecamp CLI can filter/extract JSON output without requiring an external jq binary, and updates agent-facing documentation and metadata accordingly.

Changes:

• Add a persistent --jq <expr> flag wired through global flags/app context into the output writer.
• Implement jq filtering in the output layer, including plain-text printing for string results.
• Update tests, agent skill docs, and .surface metadata; add gojq dependency.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
internal/output/envelope.go	Adds Options.JQFilter and writeJQ() to apply gojq filtering during output.
internal/appctx/context.go	Threads JQFilter through GlobalFlags and ensures it triggers machine-output behavior and JSON output selection.
internal/cli/root.go	Registers the new persistent --jq flag on the root command.
internal/output/output_test.go	Adds coverage for jq filtering behavior (field extraction, string output, errors, etc.).
skills/basecamp/SKILL.md	Updates agent guidance to prefer --jq and documents the new output mode.
go.mod / go.sum	Adds github.com/itchyny/gojq (and indirect deps).
.surface	Adds --jq to the surfaced flag inventory across commands.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[cubic-dev-ai]

2 issues found across 8 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/appctx/context.go">

<violation number="1" location="internal/appctx/context.go:173">
P2: `Resolve()` doesn't propagate `--jq` as a machine-output signal. When `--jq` is used without `--json`, the resolver's `IsInteractive()` still returns true, so interactive prompts (project/account pickers) can fire even though output is JSON-filtered. Set `JSON: true` when a JQ filter is present to keep the resolver in sync with `ApplyFlags` (which already treats `--jq` as implying `--json`).</violation>
</file>

<file name="internal/output/envelope.go">

<violation number="1" location="internal/output/envelope.go:214">
P1: Missing `NormalizeData` call before marshaling. Every other output path normalizes `Response.Data` (to decode `json.RawMessage` etc.) before encoding, but `writeJQ` skips this step. This means jq filters will operate on a different data shape than `--json` output, breaking expressions users tested against `--json`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 13 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/commands/skill.go">

<violation number="1" location="internal/commands/skill.go:53">
P2: Misleading error message and inconsistent `ErrJQNotSupported` argument. All other callers pass a short command description (e.g. `"the version command"`), but this embeds a parenthetical hint in the `command` string. More importantly, suggesting `basecamp skill install --jq` is unhelpful — `skill install` writes files and returns metadata, not skill content.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Copilot]

Pull request overview

Copilot reviewed 16 out of 18 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.