feat(issue): add subcommand to list group and project issues

The pkgctl issue list command is used to list issues associated with a specific
packaging project or the entire packaging subgroup in Arch Linux. This command
facilitates efficient issue management by allowing users to list and filter
issues based on various criteria.

Results can also be displayed directly in a web browser for easier navigation
and review.

Component: pkgctl issue list
Signed-off-by: Levente Polyak <anthraxx@archlinux.org>

README.md

@@ -74,7 +74,9 @@ Component: pkgctl db remove
 - expac
 - fakeroot
 - findutils
+- glow
 - grep
+- gum
 - jq
 - ncurses
 - openssh

contrib/completion/bash/devtools.in

@@ -15,6 +15,8 @@ source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-inspect.sh
 source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-search.sh
 # shellcheck source=src/lib/valid-version.sh
 source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-version.sh
+# shellcheck source=src/lib/valid-issue.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-issue.sh
 
 _colors=(never always auto)
 
@@ -147,6 +149,7 @@ _pkgctl_cmds=(
 	build
 	db
 	diff
+	issue
 	release
 	repo
 	search
@@ -443,6 +446,50 @@ _pkgctl_diff_args__pool_opts() { _filedir -d; }
 _pkgctl_diff_args_P_opts() { _pkgctl_diff_args__pool_opts; }
 _pkgctl_diff_opts() { _devtools_completions_all_packages; }
 
+_pkgctl_issue_cmds=(
+	list
+)
+
+_pkgctl_issue_args=(
+	-h --help
+)
+
+_pkgctl_issue_list_args=(
+	-g --group
+	-w --web
+	-A --all
+	-c --closed
+	-U --unconfirmed
+	--search
+	--in
+	-l --label
+	--confidentiality
+	--priority
+	--resolution
+	--scope
+	--severity
+	--status
+	--assignee
+	--assigned-to-me
+	--author
+	--created-by-me
+	-h --help
+)
+
+_pkgctl_issue_list_opts() { _devtools_completions_all_packages; }
+_pkgctl_issue_list_args__search_opts() { :; }
+_pkgctl_issue_list_args__in_opts() { _devtools_completions_issue_search_location; }
+_pkgctl_issue_list_args__label_opts() { :; }
+_pkgctl_issue_list_args_l_opts() { _pkgctl_issue_list_args__label_opts; }
+_pkgctl_issue_list_args__confidentiality_opts() { _devtools_completions_issue_confidentiality; }
+_pkgctl_issue_list_args__priority_opts() { _devtools_completions_issue_priority; }
+_pkgctl_issue_list_args__resolution_opts() { _devtools_completions_issue_resolution; }
+_pkgctl_issue_list_args__scope_opts() { _devtools_completions_issue_scope; }
+_pkgctl_issue_list_args__severity_opts() { _devtools_completions_issue_severity; }
+_pkgctl_issue_list_args__status_opts() { _devtools_completions_issue_status; }
+_pkgctl_issue_list_args__assignee_opts() { :; }
+_pkgctl_issue_list_args__author_opts() { :; }
+
 
 _pkgctl_version_args=(
 	-h --help
@@ -480,6 +527,27 @@ _devtools_completions_search_format() {
 _devtools_completions_version_output_format() {
 	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_VERSION_OUTPUT_FORMAT[*]}" -- "$cur")
 }
+_devtools_completions_issue_severity() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_SEVERITY[*]}" -- "$cur")
+}
+_devtools_completions_issue_status() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_STATUS[*]}" -- "$cur")
+}
+_devtools_completions_issue_scope() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_SCOPE[*]}" -- "$cur")
+}
+_devtools_completions_issue_search_location() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_SEARCH_LOCATION[*]}" -- "$cur")
+}
+_devtools_completions_issue_resolution() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_RESOLUTION[*]}" -- "$cur")
+}
+_devtools_completions_issue_priority() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_PRIORITY[*]}" -- "$cur")
+}
+_devtools_completions_issue_confidentiality() {
+	mapfile -t COMPREPLY < <(compgen -W "${DEVTOOLS_VALID_ISSUE_CONFIDENTIALITY[*]}" -- "$cur")
+}
 
 __devtools_complete() {
 	local service=$1

contrib/completion/zsh/_devtools.in

@@ -15,6 +15,8 @@ source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-inspect.sh
 source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-search.sh
 # shellcheck source=src/lib/valid-version.sh
 source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-version.sh
+# shellcheck source=src/lib/valid-issue.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-issue.sh
 
 _colors=(never always auto)
 
@@ -92,6 +94,33 @@ _pkgctl_db_update_args=(
 	'(-h --help)'{-h,--help}'[Display usage]'
 )
 
+_pkgctl_issue_cmds=(
+	"pkgctl issue command"
+	"list[List project or group issues]"
+)
+
+_pkgctl_issue_list_args=(
+	'(-g --group)'{-g,--group}'[Get issues from the whole packaging subgroup]'
+	'(-w --web)'{-w,--web}'[View results in a browser]'
+	'(-A --all)'{-A,--all}'[Get all issues including closed]'
+	'(-c --closed)'{-c,--closed}'[Get only closed issues]'
+	'(-U --unconfirmed)'{-U,--unconfirmed}'[Shorthand to filter by unconfirmed status label]'
+	'--search[Search in the fields defined by --in]:search:'
+	"--in[Search in title or description]:location:($DEVTOOLS_VALID_ISSUE_SEARCH_LOCATION[*])"
+	"--confidentiality[Filter by confidentiality]:confidential:($DEVTOOLS_VALID_ISSUE_CONFIDENTIALITY[*])"
+	"--priority[Shorthand to filter by priority label]:priority:($DEVTOOLS_VALID_ISSUE_PRIORITY[*])"
+	"--resolution[Shorthand to filter by resolution label]:resolution:($DEVTOOLS_VALID_ISSUE_RESOLUTION[*])"
+	"--scope[Shorthand to filter by scope label]:scope:($DEVTOOLS_VALID_ISSUE_SCOPE[*])"
+	"--severity[Shorthand to filter by severity label]:severity:($DEVTOOLS_VALID_ISSUE_SEVERITY[*])"
+	"--status[Shorthand to filter by status label]:status:($DEVTOOLS_VALID_ISSUE_STATUS[*])"
+	'--assignee[Filter issues assigned to the given username]:username:'
+	'--assigned-to-me[Shorthand to filter issues assigned to you]'
+	'--author[Filter issues authored by the given username]:username:'
+	'--created-by-me[Shorthand to filter issues created by you]'
+	'(-h --help)'{-h,--help}'[Display usage]'
+	'*:pkgbase:_devtools_completions_all_packages'
+)
+
 _pkgctl_release_args=(
 	'(-m --message=)'{-m,--message=}"[Use the given <msg> as the commit message]:message:"
 	'(-r --repo=)'{-r,--repo=}"[Specify a target repository for new packages]:repo:($DEVTOOLS_VALID_REPOS[*])"
@@ -290,6 +319,7 @@ _pkgctl_cmds=(
 	"build[Build packages inside a clean chroot]"
 	"db[Pacman database modification for package update, move etc]"
 	"diff[Compare package files using different modes]"
+	"issue[Work with GitLab packaging issues]"
 	"release[Release step to commit, tag and upload build artifacts]"
 	"repo[Manage Git packaging repositories and their configuration]"
 	"search[Search for an expression across the GitLab packaging group]"

doc/man/pkgctl-issue-list.1.asciidoc

+pkgctl-issue-list(1)
+====================
+
+Name
+----
+pkgctl-issue-list - List project or group issues
+
+Synopsis
+--------
+pkgctl issue list [OPTIONS] [PKGBASE]
+
+Description
+-----------
+
+The pkgctl issue list command is used to list issues associated with a specific
+packaging project or the entire packaging subgroup in Arch Linux. This command
+facilitates efficient issue management by allowing users to list and filter
+issues based on various criteria.
+
+Results can also be displayed directly in a web browser for easier navigation
+and review.
+
+The command offers filtering options to refine the results. Users can include
+closed issues, filter exclusively for unconfirmed issues, or focus on issues
+with specific labels such as priority, confidentiality, resolution, scope,
+severity, and status.
+
+Additionally, users can search within issue titles or descriptions and filter
+issues by the assignee or author. There are also convenient shortcuts to filter
+issues assigned to or created by the current user.
+
+This command is particularly useful for package maintainers and contributors in
+the Arch Linux community who need to track and manage issues efficiently. It
+provides a comprehensive view of the project's or group's issue landscape,
+enabling maintainers to address and prioritize issues effectively.
+
+Options
+-------
+
+*-g, --group*::
+	Get issues from the whole packaging subgroup
+
+*-w, --web*::
+	View results in a browser
+
+*-h, --help*::
+	Show a help text
+
+Filter Options
+--------------
+
+*-A, --all*::
+	Get all issues including closed
+
+*-c, --closed*::
+	Get only closed issues
+
+*-U, --unconfirmed*::
+	Shorthand to filter by unconfirmed status label
+
+*--search* 'SEARCH'::
+	Search <string> in the fields defined by --in
+
+*--in* 'LOCATION'::
+	Search in title or description (default: all)
+
+*-l, --label* 'NAME'::
+	Filter issue by label <name>
+
+*--confidentiality* 'TYPE'::
+	Filter by confidentiality
+
+*--priority* 'PRIORITY'::
+	Shorthand to filter by priority label
+
+*--resolution* 'REASON'::
+	Shorthand to filter by resolution label
+
+*--scope* 'SCOPE'::
+	Shorthand to filter by scope label
+
+*--severity* 'SEVERITY'::
+	Shorthand to filter by severity label
+
+*--status* 'STATUS'::
+	Shorthand to filter by status label
+
+*--assignee* 'USERNAME'::
+	Filter issues assigned to the given username
+
+*--assigned-to-me*::
+	Shorthand to filter issues assigned to you
+
+*--author* 'USERNAME'::
+	Filter issues authored by the given username
+
+*--created-by-me*::
+	Shorthand to filter issues created by you
+
+include::include/footer.asciidoc[]

doc/man/pkgctl-issue.1.asciidoc

+pkgctl-issue(1)
+===============
+
+Name
+----
+pkgctl-issue - Work with GitLab packaging issues
+
+Synopsis
+--------
+pkgctl issue [SUBCOMMAND] [OPTIONS]
+
+Description
+-----------
+
+Work with GitLab packaging issues.
+
+Options
+-------
+
+*-h, --help*::
+	Show a help text
+
+Subcommands
+-----------
+
+pkgctl issue list::
+	List project or group issues
+
+See Also
+--------
+
+pkgctl-issue-list(1)
+
+include::include/footer.asciidoc[]

doc/man/pkgctl.1.asciidoc

@@ -46,6 +46,9 @@ pkgctl db::
 pkgctl diff::
 	Compare package files using different modes
 
+pkgctl issue::
+	Work with GitLab packaging issues
+
 pkgctl release::
 	Release step to commit, tag and upload build artifacts
 
@@ -66,6 +69,7 @@ pkgctl-auth(1)
 pkgctl-build(1)
 pkgctl-db(1)
 pkgctl-diff(1)
+pkgctl-issue(1)
 pkgctl-release(1)
 pkgctl-repo(1)
 pkgctl-search(1)

src/lib/api/gitlab.sh

@@ -12,6 +12,8 @@ source "${_DEVTOOLS_LIBRARY_DIR}"/lib/common.sh
 source "${_DEVTOOLS_LIBRARY_DIR}"/lib/cache.sh
 # shellcheck source=src/lib/config.sh
 source "${_DEVTOOLS_LIBRARY_DIR}"/lib/config.sh
+# shellcheck source=src/lib/valid-issue.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/valid-issue.sh
 
 set -e
 
@@ -310,6 +312,27 @@ gitlab_lookup_project_names() {
 	lock_close 11
 }
 
+longest_package_name_from_ids() {
+	local project_ids=("$@")
+	local longest=0
+
+	# collect project ids whose name needs to be looked up
+	project_name_cache_file=$(get_cache_file gitlab/project_id_to_name)
+	lock 11 "${project_name_cache_file}" "Locking project name cache"
+
+	# read project_id to name mapping from cache
+	while read -r project_id project_name; do
+		if (( ${#project_name} > longest )) && in_array "${project_id}" "${project_ids[@]}"; then
+			longest="${#project_name}"
+		fi
+	done < "${project_name_cache_file}"
+
+	# close project name cache lock
+	lock_close 11
+
+	printf "%s" "${longest}"
+}
+
 # Convert arbitrary project names to GitLab valid path names.
 #
 # GitLab has several limitations on project and group names and also maintains
@@ -378,3 +401,323 @@ gitlab_api_search() {
 
 	return 0
 }
+
+# TODO: parallelize
+# https://docs.gitlab.com/ee/api/issues.html#list-project-issues
+gitlab_projects_issues_list() {
+	local project=$1
+	local status_file=$2
+	local params=${3:-}
+	local data=${4:-}
+	local outfile
+
+	[[ -z ${WORKDIR:-} ]] && setup_workdir
+	outfile=$(mktemp --tmpdir="${WORKDIR}" pkgctl-gitlab-api.XXXXXXXXXX)
+
+	if ! gitlab_api_call_paged "${outfile}" "${status_file}" GET "/projects/archlinux%2fpackaging%2fpackages%2f${project}/issues?${params}" "${data}"; then
+		return 1
+	fi
+
+	cat "${outfile}"
+
+	return 0
+}
+
+# TODO: parallelize
+# https://docs.gitlab.com/ee/api/issues.html#list-project-issues
+gitlab_group_issue_list() {
+	local group=$1
+	local status_file=$2
+	local params=${3:-}
+	local data=${4:-}
+	local outfile
+
+	[[ -z ${WORKDIR:-} ]] && setup_workdir
+	outfile=$(mktemp --tmpdir="${WORKDIR}" pkgctl-gitlab-api.XXXXXXXXXX)
+
+	group=${group//\//%2f}
+	params=${params//\[/%5B}
+	params=${params//\]/%5D}
+
+	if ! gitlab_api_call_paged "${outfile}" "${status_file}" GET "/groups/${group}/issues?${params}" "${data}"; then
+		return 1
+	fi
+
+	cat "${outfile}"
+
+	return 0
+}
+
+gitlab_severity_from_labels() {
+	local labels=("$@")
+	local severity="unknown"
+	local label
+	for label in "${labels[@]}"; do
+		if [[ ${label} == severity::* ]]; then
+			severity="${label#*-}"
+		fi
+	done
+	printf "%s" "${severity}"
+}
+
+severity_as_gitlab_label() {
+	local severity=$1
+	case "${severity}" in
+		lowest)
+			printf "severity::5-%s" "${severity}" ;;
+		low)
+			printf "severity::4-%s" "${severity}" ;;
+		medium)
+			printf "severity::3-%s" "${severity}" ;;
+		high)
+			printf "severity::2-%s" "${severity}" ;;
+		critical)
+			printf "severity::1-%s" "${severity}" ;;
+		*)
+			return 1 ;;
+	esac
+	return 0
+}
+
+gitlab_priority_from_labels() {
+	local labels=("$@")
+	local priority="normal"
+	local label
+	for label in "${labels[@]}"; do
+		if [[ ${label} == priority::* ]]; then
+			priority="${label#*-}"
+		fi
+	done
+	printf "%s" "${priority}"
+}
+
+priority_as_gitlab_label() {
+	local priority=$1
+	case "${priority}" in
+		low)
+			printf "priority::4-%s" "${priority}" ;;
+		normal)
+			printf "priority::3-%s" "${priority}" ;;
+		high)
+			printf "priority::2-%s" "${priority}" ;;
+		urgent)
+			printf "priority::1-%s" "${priority}" ;;
+		*)
+			return 1 ;;
+	esac
+	return 0
+}
+
+gitlab_scope_from_labels() {
+	local labels=("$@")
+	local scope="unknown"
+	local label
+	for label in "${labels[@]}"; do
+		if [[ ${label} == scope::* ]]; then
+			scope="${label#*::}"
+		fi
+	done
+	printf "%s" "${scope}"
+}
+
+scope_as_gitlab_label() {
+	local scope=$1
+	if ! in_array "${scope}" "${DEVTOOLS_VALID_ISSUE_SCOPE[@]}"; then
+		return 1
+	fi
+	printf "scope::%s" "${scope}"
+}
+
+gitlab_scope_short() {
+	local scope=$1
+	case "${scope}" in
+		regression)
+			scope=regress ;;
+		enhancement)
+			scope=enhance ;;
+		documentation)
+			scope=doc ;;
+		reproducibility)
+			scope=repro ;;
+		out-of-date)
+			scope=ood ;;
+	esac
+	printf "%s" "${scope}"
+}
+
+gitlab_scope_color() {
+	local scope=$1
+	local color="${GRAY}"
+
+	case "${scope}" in
+		bug)
+			color="${DARK_RED}" ;;
+		feature)
+			color="${DARK_BLUE}" ;;
+		security)
+			color="${RED}" ;;
+		question)
+			color="${PURPLE}" ;;
+		regression)
+			color="${DARK_RED}" ;;
+		enhancement)
+			color="${DARK_BLUE}" ;;
+		documentation)
+			color="${ALL_OFF}" ;;
+		reproducibility)
+			color="${DARK_GREEN}" ;;
+		out-of-date)
+			color="${DARK_YELLOW}" ;;
+	esac
+
+	printf "%s" "${color}"
+}
+
+status_as_gitlab_label() {
+	local status=$1
+	if ! in_array "${status}" "${DEVTOOLS_VALID_ISSUE_STATUS[@]}"; then
+		return 1
+	fi
+	printf "status::%s" "${status}"
+	return 0
+}
+
+gitlab_issue_state_display() {
+	local state=$1
+	if [[ ${state} == opened ]]; then
+		state=open
+	fi
+	printf "%s" "${state}"
+}
+
+gitlab_issue_status_from_labels() {
+	local labels=("$@")
+	local status=unconfirmed
+	local label
+	for label in "${labels[@]}"; do
+		if [[ ${label} == status::* ]]; then
+			status="${label#*::}"
+		fi
+	done
+	printf "%s" "${status}"
+}
+
+gitlab_issue_status_short() {
+	local status=$1
+	if [[ ${status} == waiting-* ]]; then
+		status=waiting
+	fi
+	printf "%s" "${status}"
+}
+
+gitlab_issue_status_color() {
+	local status=$1
+	local color="${GRAY}"
+
+	case "${status}" in
+		confirmed)
+			color="${GREEN}" ;;
+		in-progress)
+			color="${YELLOW}" ;;
+		in-review)
+			color="${PURPLE}" ;;
+		on-hold|unconfirmed)
+			color="${GRAY}" ;;
+		waiting-input|waiting-upstream)
+			color="${DARK_BLUE}" ;;
+	esac
+
+	printf "%s" "${color}"
+}
+
+resolution_as_gitlab_label() {
+	local resolution=$1
+	if ! in_array "${resolution}" "${DEVTOOLS_VALID_ISSUE_RESOLUTION[@]}"; then
+		return 1
+	fi
+	printf "resolution::%s" "${resolution}"
+}
+
+gitlab_resolution_from_labels() {
+	local labels=("$@")
+	local label
+	for label in "${labels[@]}"; do
+		if [[ ${label} == resolution::* ]]; then
+			printf "%s" "${label#*::}"
+			return 0
+		fi
+	done
+	return 1
+}
+
+gitlab_resolution_color() {
+	local resolution=$1
+	local color=""
+
+	case "${resolution}" in
+		cant-reproduce)
+			color="${DARK_YELLOW}" ;;
+		completed)
+			color="${GREEN}" ;;
+		duplicate)
+			color="${GRAY}" ;;
+		invalid)
+			color="${DARK_YELLOW}" ;;
+		not-a-bug)
+			color="${GRAY}" ;;
+		upstream)
+			color="${PURPLE}" ;;
+		wont-fix)
+			color="${DARK_BLUE}" ;;
+	esac
+
+	printf "%s" "${color}"
+}
+
+gitlab_severity_color() {
+	local severity=$1
+	local color="${PURPLE}"
+
+	case "${severity}" in
+		lowest)
+			color="${DARK_GREEN}" ;;
+		low)
+			color="${GREEN}" ;;
+		medium)
+			color="${YELLOW}" ;;
+		high)
+			color="${RED}" ;;
+		critical)
+			color="${RED}${UNDERLINE}" ;;
+	esac
+
+	printf "%s" "${color}"
+}
+
+gitlab_priority_color() {
+	local priority=$1
+	local color="${PURPLE}"
+
+	case "${priority}" in
+		low)
+			color="${DARK_GREEN}" ;;
+		normal)
+			color="${GREEN}" ;;
+		high)
+			color="${YELLOW}" ;;
+		urgent)
+			color="${RED}" ;;
+	esac
+
+	printf "%s" "${color}"
+}
+
+gitlab_issue_state_color() {
+	local state=$1
+	local state_color="${DARK_GREEN}"
+
+	if [[ ${state} == closed ]]; then
+		state_color="${DARK_RED}"
+	fi
+	printf "%s" "${state_color}"
+}

src/lib/common.sh

@@ -64,15 +64,23 @@ if [[ -t 2 && "$TERM" != dumb ]] || [[ ${DEVTOOLS_COLOR} == always ]]; then
 	if tput setaf 0 &>/dev/null; then
 		PURPLE="$(tput setaf 5)"
 		DARK_GREEN="$(tput setaf 2)"
+		DARK_RED="$(tput setaf 1)"
+		DARK_BLUE="$(tput setaf 4)"
+		DARK_YELLOW="$(tput setaf 3)"
 		UNDERLINE="$(tput smul)"
+		GRAY=$(tput setaf 242)
 	else
 		PURPLE="\e[35m"
 		DARK_GREEN="\e[32m"
+		DARK_RED="\e[31m"
+		DARK_BLUE="\e[34m"
+		DARK_YELLOW="\e[33m"
 		UNDERLINE="\e[4m"
+		GRAY=""
 	fi
 else
 	# shellcheck disable=2034
-	declare -gr ALL_OFF='' BOLD='' BLUE='' GREEN='' RED='' YELLOW='' PURPLE='' DARK_GREEN='' UNDERLINE=''
+	declare -gr ALL_OFF='' BOLD='' BLUE='' GREEN='' RED='' YELLOW='' PURPLE='' DARK_RED='' DARK_GREEN='' DARK_BLUE='' DARK_YELLOW='' UNDERLINE='' GRAY=''
 fi
 
 stat_busy() {
@@ -378,7 +386,55 @@ is_globfile() {
 }
 
 join_by() {
-	local IFS="$1"
+	local IFS="	"
+	local sep=$1
+	local split
 	shift
-	echo "$*"
+	split=$(printf "%s" "$*")
+	echo "${split//${IFS}/"${sep}"}"
+}
+
+trim_string() {
+	local max_length=$1
+	local string=$2
+
+	if (( ${#string} > max_length )); then
+		# Subtract 3 from max_length to accommodate "..."
+		max_length=$((max_length - 3))
+		string="${string:0:max_length}..."
+	fi
+
+	printf "%s" "${string}"
+}
+
+relative_date_unit() {
+	local target_date=$1
+	local now diff value units unit names
+
+	target_date=$(date -d "$1" +%s)
+	now=$(date +%s)
+	diff=$((now - target_date))
+
+	local names=(year month week day hour minute second)
+	declare -A units=(
+		[year]=$((60 * 60 * 24 * 365))
+		[month]=$((60 * 60 * 24 * 30))
+		[week]=$((60 * 60 * 24 * 7))
+		[day]=$((60 * 60 * 24))
+		[hour]=$((60 * 60))
+		[minute]=60
+		[second]=1
+	)
+
+	for unit in "${names[@]}"; do
+		local value=$((diff / ${units[${unit}]}))
+		if (( value > 1 )); then
+			printf "%s %ss" "${value}" "${unit}"
+			return
+		elif (( value == 1 )); then
+			printf "%s %s" "${value}" "${unit}"
+			return
+		fi
+	done
+	printf "1 second"
 }

src/lib/issue/issue.sh

+#!/hint/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+[[ -z ${DEVTOOLS_INCLUDE_ISSUE_SH:-} ]] || return 0
+DEVTOOLS_INCLUDE_ISSUE_SH=1
+
+_DEVTOOLS_LIBRARY_DIR=${_DEVTOOLS_LIBRARY_DIR:-@pkgdatadir@}
+
+set -e
+
+
+pkgctl_issue_usage() {
+	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
+	cat <<- _EOF_
+		Usage: ${COMMAND} [COMMAND] [OPTIONS]
+
+		Work with GitLab packaging issues.
+
+		COMMANDS
+		    list      List project or group issues
+
+		OPTIONS
+		    -h, --help    Show this help text
+
+		EXAMPLES
+		    $ ${COMMAND} list libfoo libbar
+_EOF_
+}
+
+pkgctl_issue() {
+	if (( $# < 1 )); then
+		pkgctl_issue_usage
+		exit 0
+	fi
+
+	# option checking
+	while (( $# )); do
+		case $1 in
+			-h|--help)
+				pkgctl_issue_usage
+				exit 0
+				;;
+			list)
+				_DEVTOOLS_COMMAND+=" $1"
+				shift
+				# shellcheck source=src/lib/issue/list.sh
+				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/issue/list.sh
+				pkgctl_issue_list "$@"
+				exit 0
+				;;
+			-*)
+				die "invalid argument: %s" "$1"
+				;;
+			*)
+				die "invalid command: %s" "$1"
+				;;
+		esac
+	done
+}

src/lib/issue/list.sh

+#!/hint/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+[[ -z ${DEVTOOLS_INCLUDE_ISSUE_LIST_SH:-} ]] || return 0
+DEVTOOLS_INCLUDE_ISSUE_LIST_SH=1
+
+_DEVTOOLS_LIBRARY_DIR=${_DEVTOOLS_LIBRARY_DIR:-@pkgdatadir@}
+
+# shellcheck source=src/lib/common.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/common.sh
+# shellcheck source=src/lib/api/gitlab.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/api/gitlab.sh
+# shellcheck source=src/lib/util/term.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/util/term.sh
+
+set -eo pipefail
+
+
+pkgctl_issue_list_usage() {
+	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
+	cat <<- _EOF_
+		Usage: ${COMMAND} [OPTIONS] [PKGBASE]
+
+		The pkgctl issue list command is used to list issues associated with a specific
+		packaging project or the entire packaging subgroup in Arch Linux. This command
+		facilitates efficient issue management by allowing users to list and filter
+		issues based on various criteria.
+
+		Results can also be displayed directly in a web browser for easier navigation
+		and review.
+
+		OPTIONS
+		    -g, --group             Get issues from the whole packaging subgroup
+		    -w, --web               View results in a browser
+		    -h, --help              Show this help text
+
+		FILTER
+		    -A, --all               Get all issues including closed
+		    -c, --closed            Get only closed issues
+		    -U, --unconfirmed       Shorthand to filter by unconfirmed status label
+		    --search SEARCH         Search <string> in the fields defined by --in
+		    --in LOCATION           Search in title or description (default: all)
+		    -l, --label NAME        Filter issue by label <name>
+		    --confidentiality TYPE  Filter by confidentiality
+		    --priority PRIORITY     Shorthand to filter by priority label
+		    --resolution REASON     Shorthand to filter by resolution label
+		    --scope SCOPE           Shorthand to filter by scope label
+		    --severity SEVERITY     Shorthand to filter by severity label
+		    --status STATUS         Shorthand to filter by status label
+		    --assignee USERNAME     Filter issues assigned to the given username
+		    --assigned-to-me        Shorthand to filter issues assigned to you
+		    --author USERNAME       Filter issues authored by the given username
+		    --created-by-me         Shorthand to filter issues created by you
+
+		EXAMPLES
+		    $ ${COMMAND} libfoo libbar
+		    $ ${COMMAND} --group --unconfirmed
+_EOF_
+}
+
+pkgctl_issue_list() {
+	if (( $# < 1 )) && [[ ! -f PKGBUILD ]]; then
+		pkgctl_issue_list_usage
+		exit 0
+	fi
+
+	local paths path project_path params web_params label username issue_url
+
+	local group=0
+	local web=0
+	local confidential=0
+	local state=opened
+	local request_data=""
+	local search_in="all"
+	local labels=()
+	local assignee=
+	local author=
+	local scope=all
+	local confidentiality=
+
+	# option checking
+	while (( $# )); do
+		case $1 in
+			-h|--help)
+				pkgctl_issue_list_usage
+				exit 0
+				;;
+			-A|--all)
+				state=all
+				shift
+				;;
+			-c|--closed)
+				state=closed
+				shift
+				;;
+			-U|--unconfirmed)
+				labels+=("$(status_as_gitlab_label unconfirmed)")
+				shift
+				;;
+			-g|--group)
+				group=1
+				shift
+				;;
+			-w|--web)
+				web=1
+				shift
+				;;
+			--in)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				search_in=$2
+				shift 2
+				;;
+			--search)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				request_data="search=$2"
+				web_params+="&search=$2"
+				shift 2
+				;;
+			-l|--label)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				labels+=("$2")
+				shift 2
+				;;
+			--confidentiality)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				confidentiality=$2
+				if ! in_array "${confidentiality}" "${DEVTOOLS_VALID_ISSUE_CONFIDENTIALITY[@]}"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				shift 2
+				;;
+			--priority)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				if ! label="$(priority_as_gitlab_label "$2")"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				labels+=("$label")
+				shift 2
+				;;
+			--resolution)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				if ! label="$(resolution_as_gitlab_label "$2")"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				labels+=("$label")
+				shift 2
+				;;
+			--scope)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				if ! label="$(scope_as_gitlab_label "$2")"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				labels+=("$label")
+				shift 2
+				;;
+			--severity)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				if ! label="$(severity_as_gitlab_label "$2")"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				labels+=("$label")
+				shift 2
+				;;
+			--status)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				if ! label="$(status_as_gitlab_label "$2")"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				labels+=("$label")
+				shift 2
+				;;
+			--assignee)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				assignee="$2"
+				shift 2
+				;;
+			--assigned-to-me)
+				scope=assigned_to_me
+				shift
+				;;
+			--author)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				author="$2"
+				shift 2
+				;;
+			--created-by-me)
+				scope=created_by_me
+				shift
+				;;
+			-*)
+				die "invalid argument: %s" "$1"
+				;;
+			*)
+				paths=("$@")
+				break
+				;;
+		esac
+	done
+
+	if [[ ${search_in} == all ]]; then
+		search_in="title,description"
+	else
+		web_params+="&in=${search_in^^}"
+	fi
+	params+="&in=${search_in}"
+
+	if [[ ${state} != all ]]; then
+		params+="&state=${state}"
+	fi
+	web_params+="&state=${state}"
+
+	if (( ${#labels} )); then
+		params+="&labels=$(join_by , "${labels[@]}")"
+		web_params+="&label_name[]=$(join_by "&label_name[]=" "${labels[@]}")"
+	fi
+
+	if [[ -n ${scope} ]]; then
+		params+="&scope=${scope}"
+		if (( web )); then
+			if ! username=$(gitlab_api_get_user); then
+				exit 1
+			fi
+			case "${scope}" in
+				created_by_me) author=${username} ;;
+				assigned_to_me) assignee=${username} ;;
+			esac
+		fi
+	fi
+
+	if [[ -n ${assignee} ]]; then
+		params+="&assignee_username=${assignee}"
+		web_params+="&assignee_username=${assignee}"
+	fi
+
+	if [[ -n ${author} ]]; then
+		params+="&author_username=${author}"
+		web_params+="&author_username=${author}"
+	fi
+
+	if [[ -n ${confidentiality} ]]; then
+		if [[ ${confidentiality} == confidential ]]; then
+			params+="&confidential=true"
+			web_params+="&confidential=yes"
+		else
+			params+="&confidential=false"
+			web_params+="&confidential=no"
+		fi
+	fi
+
+	# check if invoked without any path from within a packaging repo
+	if (( ${#paths[@]} == 0 )); then
+		if [[ -f PKGBUILD ]] && (( ! group )); then
+			paths=("$(realpath --canonicalize-existing .)")
+		elif (( ! group )); then
+			pkgctl_issue_list_usage
+			exit 1
+		fi
+	fi
+
+	if (( web )) && ! command -v xdg-open &>/dev/null; then
+		die "The web option requires 'xdg-open'"
+	fi
+
+	local separator="	"
+
+	for path in "${paths[@]}"; do
+		# skip paths from a glob that aren't directories
+		if [[ -e "${path}" ]] && [[ ! -d "${path}" ]]; then
+			continue
+		fi
+
+		pkgbase=$(basename "${path}")
+		project_path=$(gitlab_project_name_to_path "${pkgbase}")
+
+		echo "${UNDERLINE}${pkgbase}${ALL_OFF}"
+
+		if (( web )); then
+			issue_url="${GIT_PACKAGING_URL_HTTPS}/${project_path}/-/issues/?${web_params}"
+			echo "Opening ${issue_url} in your browser."
+			xdg-open "${issue_url}"
+			continue
+		fi
+
+		status_dir=$(mktemp --tmpdir="${WORKDIR}" --directory pkgctl-gitlab-api.XXXXXXXXXX)
+		printf "📡 Querying GitLab issues API..." > "${status_dir}/status"
+		term_spinner_start "${status_dir}"
+		if ! output=$(gitlab_projects_issues_list "${project_path}" "${status_dir}/status" "${params}" "${request_data}"); then
+			term_spinner_stop "${status_dir}"
+			echo
+			continue
+		fi
+		term_spinner_stop "${status_dir}"
+
+		issue_count=$(jq --compact-output 'length' <<< "${output}")
+		if (( issue_count == 0 )); then
+			echo "No open issues match your search"
+			echo
+			continue
+		else
+			echo "Showing ${issue_count} issues that match your search"
+		fi
+
+		print_issue_list "${output}"
+	done
+
+	if (( group )); then
+		if (( web )); then
+			issue_url="https://${GITLAB_HOST}/groups/${GIT_PACKAGING_NAMESPACE}/-/issues/?${web_params}"
+			echo "Opening ${issue_url} in your browser."
+			xdg-open "${issue_url}"
+			return
+		fi
+
+		status_dir=$(mktemp --tmpdir="${WORKDIR}" --directory pkgctl-gitlab-api.XXXXXXXXXX)
+		printf "📡 Querying GitLab issues API..." > "${status_dir}/status"
+		term_spinner_start "${status_dir}"
+		if ! output=$(gitlab_group_issue_list "${GIT_PACKAGING_NAMESPACE_ID}" "${status_dir}/status" "${params}" "${request_data}"); then
+			term_spinner_stop "${status_dir}"
+			exit 1
+		fi
+		term_spinner_stop "${status_dir}"
+
+		print_issue_list "${output}"
+	fi
+}
+
+print_issue_list() {
+	local output=$1
+	local limit=${2:-100}
+	local i=0
+	local status_dir
+	local longest_pkgname
+
+	# limit results
+	output=$(jq ".[:${limit}]" <<< "${output}")
+
+	mapfile -t project_ids < <(
+		jq --raw-output '[.[].project_id] | unique[]' <<< "${output}")
+
+	status_dir=$(mktemp --tmpdir="${WORKDIR}" --directory pkgctl-gitlab-api.XXXXXXXXXX)
+	printf "📡 Querying GitLab project names..." > "${status_dir}/status"
+	term_spinner_start "${status_dir}"
+
+	# read project_id to name mapping from cache
+	declare -A project_name_lookup=()
+	while read -r project_id project_name; do
+		project_name_lookup[${project_id}]=${project_name}
+	done < <(gitlab_lookup_project_names "${status_dir}/status" "${project_ids[@]}")
+	longest_pkgname=$(longest_package_name_from_ids "${project_ids[@]}")
+
+	term_spinner_stop "${status_dir}"
+
+	result_file=$(mktemp --tmpdir="${WORKDIR}" pkgctl-issue-list.XXXXXXXXXX)
+	printf "📡 Collecting issue information %%spinner%%" > "${status_dir}/status"
+	term_spinner_start "${status_dir}"
+
+	local columns="ID,Title,Scope,Status,Severity,Age"
+	if (( group )); then
+		columns="ID,Package,Title,Scope,Status,Severity,Age"
+	fi
+
+	# pretty print each result
+	while read -r result; do
+		if (( i > limit )); then
+			break
+		fi
+		i=$(( ++i ))
+
+		{ read -r project_id; read -r iid; read -r title; read -r state; read -r created_at; read -r confidential; } < <(
+			jq --raw-output ".project_id, .iid, .title, .state, .created_at, .confidential" <<< "${result}"
+		)
+		mapfile -t labels < <(
+			jq --raw-output ".labels[]" <<< "${result}"
+		)
+
+		pkgbase=${project_name_lookup[${project_id}]}
+		created_at=$(relative_date_unit "${created_at}")
+		severity="$(gitlab_severity_from_labels "${labels[@]}")"
+		severity_color="$(gitlab_severity_color "${severity}")"
+		state_color="$(gitlab_issue_state_color "${state}")"
+		state="$(gitlab_issue_state_display "${state}")"
+		status="$(gitlab_issue_status_from_labels "${labels[@]}")"
+		status_color="$(gitlab_issue_status_color "${status}")"
+		status="$(gitlab_issue_status_short "${status}")"
+		scope="$(gitlab_scope_from_labels "${labels[@]}")"
+		scope_color="$(gitlab_scope_color "${scope}")"
+		scope="$(gitlab_scope_short "${scope}")"
+
+		title_space=$(( COLUMNS - 7 - 10 - 15 - 12 - 10 ))
+		if (( group )); then
+			title_space=$(( title_space - longest_pkgname ))
+		fi
+		if [[ ${confidential} == true ]]; then
+			title_space=$(( title_space - 2 ))
+		fi
+		title=$(trim_string "${title_space}" "${title}")
+		# gum is silly and doesn't allow double quotes
+		title=${title//\"/}
+		if [[ ${confidential} == true ]]; then
+			title="${YELLOW}${PKGCTL_TERM_ICON_CONFIDENTIAL} ${title}${ALL_OFF}"
+		fi
+
+		if (( group )); then
+			printf "%s\n" "${state_color}#$iid${ALL_OFF}${separator}${BOLD}${pkgbase}${separator}${ALL_OFF}${title}${separator}${scope_color}${scope}${ALL_OFF}${separator}${status_color}${status}${separator}${severity_color}${severity}${ALL_OFF}${separator}${GRAY}${created_at}${ALL_OFF}" \
+				>> "${result_file}"
+		else
+			printf "%s\n" "${state_color}#$iid${ALL_OFF}${separator}${title}${separator}${scope_color}${scope}${ALL_OFF}${separator}${status_color}${status}${separator}${severity_color}${severity}${ALL_OFF}${separator}${GRAY}${created_at}${ALL_OFF}" \
+				>> "${result_file}"
+		fi
+	done < <(jq --compact-output '.[]' <<< "${output}")
+
+	term_spinner_stop "${status_dir}"
+
+	gum table --print --border="none" --columns="${columns}" \
+		--separator="${separator}" --file "${result_file}"
+}

src/lib/util/term.sh

@@ -7,6 +7,8 @@ DEVTOOLS_INCLUDE_UTIL_TERM_SH=1
 
 set -eo pipefail
 
+readonly PKGCTL_TERM_ICON_CONFIDENTIAL=⛔
+export PKGCTL_TERM_ICON_CONFIDENTIAL
 
 readonly PKGCTL_TERM_SPINNER_DOTS=Dots
 export PKGCTL_TERM_SPINNER_DOTS

src/lib/valid-issue.sh

+#!/hint/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_SEVERITY=(
+	lowest
+	low
+	medium
+	high
+	critical
+)
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_PRIORITY=(
+	low
+	normal
+	high
+	urgent
+)
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_STATUS=(
+	confirmed
+	in-progress
+	in-review
+	on-hold
+	unconfirmed
+	waiting-input
+	waiting-upstream
+)
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_SCOPE=(
+	bug
+	feature
+	security
+	question
+	regression
+	enhancement
+	documentation
+	reproducibility
+	out-of-date
+)
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_SEARCH_LOCATION=(
+	title
+	description
+	all
+)
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_RESOLUTION=(
+	cant-reproduce
+	completed
+	duplicate
+	invalid
+	not-a-bug
+	upstream
+	wont-fix
+)
+
+# shellcheck disable=2034
+DEVTOOLS_VALID_ISSUE_CONFIDENTIALITY=(
+	confidential
+	public
+)

src/pkgctl.in

@@ -24,6 +24,7 @@ usage() {
 		    build   Build packages inside a clean chroot
 		    db      Pacman database modification for package update, move etc
 		    diff    Compare package files using different modes
+		    issue   Work with GitLab packaging issues
 		    release Release step to commit, tag and upload build artifacts
 		    repo    Manage Git packaging repositories and their configuration
 		    search  Search for an expression across the GitLab packaging group
@@ -104,6 +105,14 @@ while (( $# )); do
 			diffpkg "$@"
 			exit 0
 			;;
+		issue)
+			_DEVTOOLS_COMMAND+=" $1"
+			shift
+			# shellcheck source=src/lib/issue/issue.sh
+			source "${_DEVTOOLS_LIBRARY_DIR}"/lib/issue/issue.sh
+			pkgctl_issue "$@"
+			exit 0
+			;;
 		release)
 			_DEVTOOLS_COMMAND+=" $1"
 			shift