#!/usr/bin/env bash
# require-jq.sh  -  one place to refuse when `jq` is missing.
#
# 78 shell files in this repo call `jq`. 46 of them called it with no check at
# all, and the README described that as helpers which "skip in silence" - which
# is the defect stated as if it were the design. A bare `jq` on a machine
# without it does not skip. It writes "command not found" to stderr, produces
# an empty string on stdout, and the caller carries on with that empty string
# as if it were the answer.
#
# The nine production paths are where that matters:
#
#   autopilot-state.sh   an unreadable queue reads as an EMPTY queue, so the
#                        runner concludes there is no work and goes quiet
#   jira-publish.sh      posts a comment built from empty fields
#   post-pr-review.sh    publishes a review whose findings did not parse
#   update-issue-progress.sh  same, on an issue
#   _jira-auth.sh        no credential, and the failure surfaces later as 401
#   figma-mcp-refresh.sh / figma-screenshot.sh   silent no-op on a design fetch
#   plan-todos.sh        an empty plan looks like a plan with no work in it
#   search-logs.sh       "no results" instead of "could not search"
#
# Every one of those is the same shape: absence of a tool rendered as absence
# of data. Refusing is the only honest answer, and the exit code is distinct
# so a caller can tell "jq missing" from "the work failed".
#
# Usage:
#   . "$(dirname "$0")/require-jq.sh"
#   ma_require_jq "read the autopilot queue" || exit 3
#
# It returns rather than exits: this file is SOURCED, and a sourced file that
# exits kills the caller's shell in ways the caller did not write down.

# shellcheck disable=SC2329  # sourced by other scripts, not called here
ma_require_jq() {
  command -v jq >/dev/null 2>&1 && return 0
  printf 'jq not found - cannot %s.\n' "${1:-continue}" >&2
  printf '  install it: brew install jq\n' >&2
  return 1
}