feat(issue): add subcommand to create a new issue

The create command is used to create a new issue for an Arch Linux package.
This command is suitable for reporting bugs, regressions, feature requests, or
any other issues related to a package. It provides a flexible way to document
and track new issues within the project's issue tracking system.

By default, the command operates within the current directory, but users can
specify a different package base if needed.

Users can provide a title for the issue directly through the command line.
The command allows setting various labels and attributes for the issue, such as
confidentiality, priority, scope, severity, and status.

In case of a failed run, the command can automatically recover to ensure that
the issue creation process is completed without losing any data.

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

contrib/completion/bash/devtools.in

@@ -449,6 +449,7 @@ _pkgctl_diff_opts() { _devtools_completions_all_packages; }
 _pkgctl_issue_cmds=(
 	close
 	comment
+	create
 	list
 	move
 	reopen
@@ -488,6 +489,32 @@ _pkgctl_issue_comment_args_p_opts() { _pkgctl_issue_comment_args__package_opts;
 _pkgctl_issue_comment_args__message_opts() { :; }
 _pkgctl_issue_comment_args_m_opts() { _pkgctl_issue_comment_args__message_opts; }
 
+_pkgctl_issue_create_args=(
+	-p --package
+	-t --title
+	-F --file
+	-e --edit
+	-w --web
+	--recover
+	--confidentiality
+	--priority
+	--scope
+	--severity
+	--status
+	-h --help
+)
+
+_pkgctl_issue_create_opts() { :; }
+_pkgctl_issue_create_args__package_opts() { _devtools_completions_all_packages; }
+_pkgctl_issue_create_args_p_opts() { _pkgctl_issue_create_args__package_opts; }
+_pkgctl_issue_create_args__title_opts() { :; }
+_pkgctl_issue_create_args_t_opts() { _pkgctl_issue_create_args__title_opts; }
+_pkgctl_issue_create_args__confidentiality_opts() { _devtools_completions_issue_confidentiality; }
+_pkgctl_issue_create_args__priority_opts() { _devtools_completions_issue_priority; }
+_pkgctl_issue_create_args__scope_opts() { _devtools_completions_issue_scope; }
+_pkgctl_issue_create_args__severity_opts() { _devtools_completions_issue_severity; }
+_pkgctl_issue_create_args__status_opts() { _devtools_completions_issue_status; }
+
 _pkgctl_issue_list_args=(
 	-g --group
 	-w --web

contrib/completion/zsh/_devtools.in

@@ -98,6 +98,7 @@ _pkgctl_issue_cmds=(
 	"pkgctl issue command"
 	"close[Close an issue]"
 	"comment[Comment on an issue]"
+	"create[Create a new issue]"
 	"list[List project or group issues]"
 	"move[Move an issue to another project]"
 	"reopen[Reopen a closed issue]"
@@ -121,6 +122,21 @@ _pkgctl_issue_comment_args=(
 	"1:issue_iid:"
 )
 
+_pkgctl_issue_create_args=(
+	'(-p --package)'{-p,--package}'[Interact with <pkgbase> instead of the current directory]:pkgbase:_devtools_completions_all_packages'
+	'(-t --title)'{-t,--title}'[Use the provided title for the issue]:title:'
+	'(-F --file)'{-F,--file}'[Take issue description from <file>]:file:_files'
+	'(-e --edit)'{-e,--edit}'[Edit the issue title and description using an editor]'
+	'(-w --web)'{-w,--web}'[Continue issue creation with the web interface]'
+	"--recover[Automatically recover from a failed run]"
+	"--confidentiality[Set the issue confidentiality]:confidential:($DEVTOOLS_VALID_ISSUE_CONFIDENTIALITY[*])"
+	"--priority[Set the priority label]:priority:($DEVTOOLS_VALID_ISSUE_PRIORITY[*])"
+	"--scope[Set the scope label]:scope:($DEVTOOLS_VALID_ISSUE_SCOPE[*])"
+	"--severity[Set the severity label]:severity:($DEVTOOLS_VALID_ISSUE_SEVERITY[*])"
+	"--status[Set the status label]:status:($DEVTOOLS_VALID_ISSUE_STATUS[*])"
+	'(-h --help)'{-h,--help}'[Display usage]'
+)
+
 _pkgctl_issue_list_args=(
 	'(-g --group)'{-g,--group}'[Get issues from the whole packaging subgroup]'
 	'(-w --web)'{-w,--web}'[View results in a browser]'

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

+pkgctl-issue-create(1)
+======================
+
+Name
+----
+pkgctl-issue-create - Create a new issue
+
+Synopsis
+--------
+pkgctl issue create [OPTIONS]
+
+Description
+-----------
+
+The create command is used to create a new issue for an Arch Linux package.
+This command is suitable for reporting bugs, regressions, feature requests, or
+any other issues related to a package. It provides a flexible way to document
+and track new issues within the project's issue tracking system.
+
+By default, the command operates within the current directory, but users can
+specify a different package base if needed.
+
+Users can provide a title for the issue directly through the command line. The
+issue description can be supplied from a file or edited using a text editor.
+Alternatively, users can opt to continue the issue creation process using the
+web interface for a more interactive experience.
+
+The command allows setting various labels and attributes for the issue, such as
+confidentiality, priority, scope, severity, and status. These options help
+categorize and prioritize the issue appropriately within the tracking system.
+
+In case of a failed run, the command can automatically recover to ensure that
+the issue creation process is completed without losing any data.
+
+This command is essential for maintainers, contributors, and users who need to
+report new issues related to Arch Linux packages.
+
+Options
+-------
+
+*-p, --package* 'PKGBASE'::
+	Interact with `PKGBASE` instead of the current directory
+
+*-t, --title* 'TITLE'::
+	Use the provided title for the issue
+
+*-F, --file* 'FILE'::
+	Take issue description from <file>
+
+*-e, --edit*::
+	Edit the issue description using an editor
+
+*-w, --web*::
+	Continue issue creation with the web interface
+
+*--recover*::
+	Automatically recover from a failed run
+
+*--confidentiality* 'TYPE'::
+	Set the issue confidentiality
+
+*--priority* 'PRIORITY'::
+	Set the priority label
+
+*--scope* 'SCOPE'::
+	Set the scope label
+
+*--severity* 'SEVERITY'::
+	Set the severity label
+
+*--status* 'STATUS'::
+	Set the status label
+
+*-h, --help*::
+	Show a help text
+
+include::include/footer.asciidoc[]

doc/man/pkgctl-issue.1.asciidoc

@@ -29,6 +29,9 @@ pkgctl issue close::
 pkgctl issue comment::
 	Comment on an issue
 
+pkgctl issue create::
+	Create a new issue
+
 pkgctl issue list::
 	List project or group issues
 
@@ -46,6 +49,7 @@ See Also
 
 pkgctl-issue-close(1)
 pkgctl-issue-comment(1)
+pkgctl-issue-create(1)
 pkgctl-issue-list(1)
 pkgctl-issue-move(1)
 pkgctl-issue-reopen(1)

src/lib/api/gitlab.sh

@@ -489,6 +489,39 @@ gitlab_project_issue() {
 	return 0
 }
 
+gitlab_project_issue_create() {
+	local pkgbase=$1
+	local title=$2
+	local description=$3
+	local confidential=$4
+	shift 4
+	local labels=("${@}")
+	local outfile data iid project_path
+
+	[[ -z ${WORKDIR:-} ]] && setup_workdir
+	outfile=$(mktemp --tmpdir="${WORKDIR}" pkgctl-gitlab-api.XXXXXXXXXX)
+
+	project_path=$(gitlab_project_name_to_path "${pkgbase}")
+
+	data=$(jq --null-input \
+		--arg title "${title}" \
+		--arg description "${description}" \
+		--arg confidential "${confidential}" \
+		--arg labels "$(join_by , "${labels[@]}")" \
+		'$ARGS.named')
+	if ! gitlab_api_call "${outfile}" POST "/projects/archlinux%2fpackaging%2fpackages%2f${project_path}/issues" "${data}"; then
+		return 1
+	fi
+
+	if ! iid=$(jq --raw-output --exit-status '.iid' < "${outfile}"); then
+		msg_error "  failed to query note: $(cat "${outfile}")"
+		return 1
+	fi
+
+	cat "${outfile}"
+	return 0
+}
+
 # TODO: parallelize
 # https://docs.gitlab.com/ee/api/notes.html#list-project-issue-notes
 gitlab_project_issue_notes() {

src/lib/issue/create.sh

+#!/hint/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+[[ -z ${DEVTOOLS_INCLUDE_ISSUE_CREATE_SH:-} ]] || return 0
+DEVTOOLS_INCLUDE_ISSUE_CREATE_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_create_usage() {
+	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
+	cat <<- _EOF_
+		Usage: ${COMMAND} [OPTIONS]
+
+		The create command is used to create a new issue for an Arch Linux package.
+		This command is suitable for reporting bugs, regressions, feature requests, or
+		any other issues related to a package. It provides a flexible way to document
+		and track new issues within the project's issue tracking system.
+
+		By default, the command operates within the current directory, but users can
+		specify a different package base if needed.
+
+		Users can provide a title for the issue directly through the command line.
+		The command allows setting various labels and attributes for the issue, such as
+		confidentiality, priority, scope, severity, and status.
+
+		In case of a failed run, the command can automatically recover to ensure that
+		the issue creation process is completed without losing any data.
+
+		OPTIONS
+		    -p, --package PKGBASE    Interact with <pkgbase> instead of the current directory
+		    -t, --title TITLE        Use the provided title for the issue
+		    -F, --file FILE          Take issue description from <file>
+		    -e, --edit               Edit the issue description using an editor
+		    -w, --web                Continue issue creation with the web interface
+		    --recover                Automatically recover from a failed run
+		    --confidentiality TYPE   Set the issue confidentiality
+		    --priority PRIORITY      Set the priority label
+		    --scope SCOPE            Set the scope label
+		    --severity SEVERITY      Set the severity label
+		    --status STATUS          Set the status label
+		    -h, --help               Show this help text
+
+		EXAMPLES
+		    $ ${COMMAND} --package linux --title "some very informative title"
+_EOF_
+}
+
+pkgctl_issue_create() {
+	if (( $# < 1 )); then
+		pkgctl_issue_create_usage
+		exit 0
+	fi
+
+	local pkgbase=""
+	local title_placeholder="PLACEHOLDER"
+	local title="${title_placeholder}"
+	local description=""
+	local labels=()
+	local msgfile=""
+	local edit=0
+	local web=0
+	local recover=0
+	local confidential=0
+
+	local issue_template_url="https://gitlab.archlinux.org/archlinux/packaging/templates/-/raw/master/.gitlab/issue_templates/Default.md"
+	local issue_template
+	local recovery_home=${XDG_DATA_HOME:-$HOME/.local/share}/devtools/recovery
+	local recovery_file
+	local issue_url
+	local project_path
+	local result
+	local iid
+	local message
+	local editor
+
+	# option checking
+	while (( $# )); do
+		case $1 in
+			-h|--help)
+				pkgctl_issue_create_usage
+				exit 0
+				;;
+			-t|--title)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				title=$2
+				shift 2
+				;;
+			-p|--package)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				pkgbase=$2
+				shift 2
+				;;
+			-F|--file)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				msgfile=$2
+				shift 2
+				;;
+			-e|--edit)
+				edit=1
+				shift
+				;;
+			-w|--web)
+				web=1
+				shift
+				;;
+			--recover)
+				recover=1
+				shift
+				;;
+			--confidentiality)
+				(( $# <= 1 )) && die "missing argument for %s" "$1"
+				if ! in_array "$2" "${DEVTOOLS_VALID_ISSUE_CONFIDENTIALITY[@]}"; then
+					die "invalid argument for %s: %s" "$1" "$2"
+				fi
+				if [[ $2 == confidential ]]; then
+					confidential=1
+				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
+				;;
+			--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
+				;;
+			*)
+				die "invalid argument: %s" "$1"
+				;;
+		esac
+	done
+
+	if [[ -z ${pkgbase} ]]; then
+		if ! [[ -f PKGBUILD ]]; then
+			die "missing --package option or PKGBUILD in current directory"
+		fi
+		pkgbase=$(realpath --canonicalize-existing .)
+	fi
+	pkgbase=$(basename "${pkgbase}")
+	project_path=$(gitlab_project_name_to_path "${pkgbase}")
+	recovery_file="${recovery_home}/issue_create_${pkgbase}.md"
+
+	# spawn web browser
+	if (( web )); then
+		if ! command -v xdg-open &>/dev/null; then
+			die "The web option requires 'xdg-open'"
+		fi
+		issue_url="${GIT_PACKAGING_URL_HTTPS}/${project_path}/-/issues/new"
+		echo "Opening ${issue_url} in your browser."
+		xdg-open "${issue_url}"
+		return
+	fi
+
+	# check existence of recovery file
+	if [[ -f ${recovery_file} ]]; then
+		if (( ! recover )); then
+			msg_warn "Recovery file already exists: ${recovery_file}"
+			if prompt "${GREEN}${BOLD}?${ALL_OFF} Do you want to recover?"; then
+				msgfile=${recovery_file}
+				recover=1
+				edit=1
+			fi
+		fi
+	fi
+
+	# check existence of msgfile
+	if [[ -n ${msgfile} ]]; then
+		if [[ ! -f ${msgfile} ]]; then
+			msg_error "File does not exist: ${msgfile}${ALL_OFF}"
+			exit 1
+		fi
+	else
+		# prepare msgfile and fetch the issue template
+		if ! issue_template=$(curl --url "${issue_template_url}" --silent); then
+			msg_error "Failed to fetch issue template${ALL_OFF}"
+			exit 1
+		fi
+		# populate message file
+		msgfile=$(mktemp --tmpdir="${WORKDIR}" pkgctl-issue-create.XXXXXXXXXX.md)
+		edit=1
+		printf "# Title: %s\n\n" "${title}" >> "${msgfile}"
+		printf "%s\n" "${issue_template}" >> "${msgfile}"
+	fi
+
+	# spawn editor
+	if (( edit )); then
+		if [[ -n $VISUAL ]]; then
+			editor=${VISUAL}
+		elif [[ -n $EDITOR ]]; then
+			editor=${EDITOR}
+		else
+			die "No usable editor found (tried \$VISUAL, \$EDITOR)."
+		fi
+
+		if ! ${editor} "${msgfile}"; then
+			message=$(< "${msgfile}")
+			pkgctl_issue_write_recovery_file "${pkgbase}" "${message}" "${recovery_file}" "${recover}"
+		fi
+	fi
+
+	# check if the file contains a title
+	message=$(< "${msgfile}")
+	description=${message}
+	if [[ ${message} == "# Title: "* ]]; then
+		title=$(head --lines 1 <<< "${message}")
+		title=${title//# Title: /}
+		description=$(tail --lines +2 <<< "${message}")
+		if [[ ${description} == $'\n'* ]]; then
+			description=$(tail --lines +3 <<< "${message}")
+		fi
+	fi
+
+	# validate title
+	if [[ ${title} == 'PLACEHOLDER' ]]; then
+		msg_error "Invalid issue title: ${title}${ALL_OFF}"
+		pkgctl_issue_write_recovery_file "${pkgbase}" "${message}" "${recovery_file}" "${recover}"
+		exit 1
+	fi
+
+	# create the issue
+	if ! result=$(gitlab_project_issue_create "${pkgbase}" "${title}" "${description}" "${confidential}" "${labels[@]}"); then
+		msg_error "Failed to create issue in ${BOLD}${pkgbase}${ALL_OFF}"
+		pkgctl_issue_write_recovery_file "${pkgbase}" "${message}" "${recovery_file}" "${recover}"
+		exit 1
+	fi
+
+	# delete old recovery file if we succeeded
+	if [[ -f ${recovery_file} ]]; then
+		rm --force "${recovery_file}"
+	fi
+
+	# read issue iid
+	{ read -r iid; } < <(
+		jq --raw-output ".iid" <<< "${result}"
+	)
+	issue_url="${GIT_PACKAGING_URL_HTTPS}/${project_path}/-/issues/${iid}"
+
+	msg_success "Created new issue ${BOLD}#${iid}${ALL_OFF}"
+	printf "%sView this issue on GitLab: %s%s\n" "${GRAY}" "${issue_url}" "${ALL_OFF}"
+}
+
+pkgctl_issue_write_recovery_file() {
+	local pkgbase=$1
+	local message=$2
+	local recovery_file=$3
+	local recover=$4
+
+	if [[ -f ${recovery_file} ]] && (( ! recover )); then
+		msg_warn "Recovery file already exists: ${recovery_file}"
+		if ! prompt "${YELLOW}${BOLD}?${ALL_OFF} Are you sure you want to overwrite it?"; then
+			return 1
+		fi
+	fi
+
+	mkdir -p "$(dirname "${recovery_file}")"
+	printf "%s\n" "${message}" > "${recovery_file}"
+
+	printf "Created recovery file: %s\n" "${recovery_file}"
+	return 0
+}

src/lib/issue/issue.sh

@@ -20,6 +20,7 @@ pkgctl_issue_usage() {
 		COMMANDS
 		    close     Close an issue
 		    comment   Comment on an issue
+		    create    Create a new issue
 		    list      List project or group issues
 		    move      Move an issue to another project
 		    reopen    Reopen a closed issue
@@ -55,6 +56,14 @@ pkgctl_issue() {
 				pkgctl_issue_close "$@"
 				exit 0
 				;;
+			create)
+				_DEVTOOLS_COMMAND+=" $1"
+				shift
+				# shellcheck source=src/lib/issue/create.sh
+				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/issue/create.sh
+				pkgctl_issue_create "$@"
+				exit 0
+				;;
 			list)
 				_DEVTOOLS_COMMAND+=" $1"
 				shift