@joshuafolkken/kit 1.872.0

package/scripts/git/git-gh-api-path.ts

@@ -0,0 +1,118 @@
+// REST path construction for `gh api`, in one place.
+//
+// Every repository-scoped path starts with the same segment, and the same `repo ?? '{owner}/{repo}'`
+// decision was already being spelled out per call site — in `git-gh-issue-read.ts`, and as a bare
+// string concatenation in `git-gh-pr.ts` and `epic-cross-repo.ts`. All three now build their paths
+// from here. Converting kit's GitHub calls to REST multiplies those call sites, so the decision is
+// made once rather than at each one (joshuafolkken/kit#1023).
+
+// One full page of a listing. REST answers 30 rows by default, and every listing this tooling reads
+// is paged through with `--paginate`, so asking for the largest page turns a long listing into fewer
+// round trips. Named once because three readers append it (joshuafolkken/kit#1028).
+const FULL_PAGE_QUERY = '?per_page=100'
+
+// `gh api` expands `{owner}` and `{repo}` from the current repository, so the unqualified form needs
+// no extra lookup to name a path. An explicit `repo` names another repository — the form a
+// cross-repository reference takes.
+function repo_api_path(repo?: string): string {
+	return `repos/${repo ?? '{owner}/{repo}'}`
+}
+
+// The issue collection — what a listing pages through and what a creation posts to. One segment,
+// named once: the reads, the listing and the writes all build on it (joshuafolkken/kit#1026).
+function issues_api_path(repo?: string): string {
+	return `${repo_api_path(repo)}/issues`
+}
+
+function issue_api_path(issue_number: string, repo?: string): string {
+	return `${issues_api_path(repo)}/${issue_number}`
+}
+
+// The dependency relations, which REST serves from their own endpoint rather than inside the issue.
+// Named here because three call sites address it — the read in `git-gh-issue-read.ts` and both
+// writes in `git-gh-issue-write.ts` (joshuafolkken/kit#1026).
+function blocked_by_api_path(issue_number: string, repo?: string): string {
+	return `${issue_api_path(issue_number, repo)}/dependencies/blocked_by`
+}
+
+// A pull request's *conversation* comments. REST serves them from the issue endpoint rather than the
+// pull one — `pulls/{N}/comments` is the review thread, which is a different listing with a
+// different shape, and reading one where the other was meant is a silent mistake rather than a 404
+// (joshuafolkken/kit#1027).
+function issue_comments_api_path(issue_number: string, repo?: string): string {
+	return `${issue_api_path(issue_number, repo)}/comments`
+}
+
+// The pull request collection — what a branch lookup filters with `?head=<owner>:<branch>`.
+function pulls_api_path(repo?: string): string {
+	return `${repo_api_path(repo)}/pulls`
+}
+
+// One pull request, addressed by number. `gh pr view` accepted a branch name and REST does not, so
+// every read below the branch lookup names the number instead (joshuafolkken/kit#1027).
+function pull_api_path(pr_number: string, repo?: string): string {
+	return `${pulls_api_path(repo)}/${pr_number}`
+}
+
+// The merge of one pull request. `gh pr merge <branch> --merge` is the GraphQL call this replaces,
+// and the method it named is sent as the `merge_method` field of the request body rather than being
+// left to the endpoint's default (joshuafolkken/kit#1029).
+function pull_merge_api_path(pr_number: string, repo?: string): string {
+	return `${pull_api_path(pr_number, repo)}/merge`
+}
+
+// The review thread — the line comments a reviewer left on the diff, which is what the CodeRabbit
+// gate reads and is not the same listing as `issue_comments_api_path`.
+function pull_comments_api_path(pr_number: string, repo?: string): string {
+	return `${pull_api_path(pr_number, repo)}/comments`
+}
+
+// The review history of one pull request. There is no REST counterpart to GraphQL's
+// `reviewDecision`, so the merge gate folds this listing into one instead (joshuafolkken/kit#1028).
+function pull_reviews_api_path(pr_number: string, repo?: string): string {
+	return `${pull_api_path(pr_number, repo)}/reviews`
+}
+
+// One commit, addressed by SHA. The two halves of what `gh` merged into `statusCheckRollup` hang off
+// it, and they are keyed by the pull request's *head* commit rather than by its number.
+function commit_api_path(commit_sha: string, repo?: string): string {
+	return `${repo_api_path(repo)}/commits/${commit_sha}`
+}
+
+// The check runs GitHub Actions and check-run apps post — the `CheckRun` half of the rollup.
+function commit_check_runs_api_path(commit_sha: string, repo?: string): string {
+	return `${commit_api_path(commit_sha, repo)}/check-runs`
+}
+
+// The combined commit status — the `StatusContext` half. A different endpoint with a different
+// element shape (`state` / `context` rather than `status` / `conclusion` / `name`), which is why the
+// two are merged by the caller rather than read as one listing.
+function commit_status_api_path(commit_sha: string, repo?: string): string {
+	return `${commit_api_path(commit_sha, repo)}/status`
+}
+
+// A single tag reference. REST answers 404 when the tag does not exist, which is the whole of the
+// question the release command's tag watch asks (joshuafolkken/kit#1169).
+function tag_reference_api_path(tag: string, repo?: string): string {
+	return `${repo_api_path(repo)}/git/ref/tags/${tag}`
+}
+
+const git_gh_api_path = {
+	FULL_PAGE_QUERY,
+	repo_api_path,
+	tag_ref_api_path: tag_reference_api_path,
+	issues_api_path,
+	issue_api_path,
+	blocked_by_api_path,
+	issue_comments_api_path,
+	pulls_api_path,
+	pull_api_path,
+	pull_merge_api_path,
+	pull_comments_api_path,
+	pull_reviews_api_path,
+	commit_api_path,
+	commit_check_runs_api_path,
+	commit_status_api_path,
+}
+
+export { git_gh_api_path, FULL_PAGE_QUERY }

package/scripts/git/git-gh-check.ts

@@ -0,0 +1,21 @@
+import { execa } from 'execa'
+
+const GH_NOT_INSTALLED_MSG = 'gh CLI is not installed. Install it from https://cli.github.com/'
+
+const gh_check: { promise?: Promise<void> } = {}
+
+async function run_gh_check(): Promise<void> {
+	try {
+		await execa('gh', ['--version'])
+	} catch {
+		delete gh_check.promise
+		throw new Error(GH_NOT_INSTALLED_MSG)
+	}
+}
+
+async function check_gh_installed(): Promise<void> {
+	gh_check.promise ??= run_gh_check()
+	await gh_check.promise
+}
+
+export { check_gh_installed, GH_NOT_INSTALLED_MSG }

package/scripts/git/git-gh-command.ts

@@ -0,0 +1,17 @@
+import { git_gh_issue } from './git-gh-issue'
+import { git_gh_pr } from './git-gh-pr'
+import { git_gh_pr_auto_merge } from './git-gh-pr-auto-merge'
+import { git_gh_repo } from './git-gh-repo'
+import { git_pr_checks_watch } from './git-pr-checks-watch'
+
+const git_gh_command = {
+	...git_gh_pr,
+	...git_gh_pr_auto_merge,
+	pr_checks_watch: git_pr_checks_watch.pr_checks_watch,
+	...git_gh_issue,
+	...git_gh_repo,
+}
+
+export { git_gh_command }
+export { parse_pr_state_string } from './git-gh-helpers'
+export { PR_CHECKS_WATCH_TIMEOUT_MS } from './git-pr-checks-watch'

package/scripts/git/git-gh-exec.ts

@@ -0,0 +1,344 @@
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { execa, execaSync } from 'execa'
+import { has_timed_out } from './git-execa-error'
+import { check_gh_installed } from './git-gh-check'
+import { gh_failure } from './git-gh-failure'
+
+const BODY_FROM_STDIN = '-'
+
+// The budget for **one** request through this layer, and the reason nothing here waits forever
+// (joshuafolkken/kit#1065). Every GitHub access kit makes funnels through the four entries below, so
+// until this existed a single hung `gh` held the caller open with no upper bound — most visibly in
+// `josh propagate`, whose runner is single-threaded and processed no further consumer at all.
+//
+// **It is a request's budget, not a step's.** `STEP_TIMEOUT_MS` (30 minutes, `propagate-steps.ts`)
+// covers a consumer's whole unit suite and a `pnpm add`; one REST call has no business borrowing
+// that number. The value is read off what the callers actually do instead:
+//
+// - `CHECK_WAIT_INTERVAL_MS` is 10 seconds — the merge gate's poll cadence. A request still in
+//   flight six polls later is not slow, it is stuck.
+// - `PR_CHECKS_WATCH_TIMEOUT_MS` is 120 seconds: `followup`'s look-ahead, which bounds its own
+//   *sleeps* rather than the wall clock, so each poll's requests sit on top of it. A request allowed
+//   to outlast that whole window would make the budget meaningless; half of it keeps one request
+//   from dominating the look-ahead.
+// - kit's other `gh` spawns already sit at 5 seconds (`repo-setting.ts`) and 20
+//   (`propagate-publish.ts`, `epic-cross-repo.ts`). Sixty is deliberately the most generous of them,
+//   because this entry also serves `--paginate` requests — several HTTP round trips inside one
+//   spawn — which a 5-second budget would break.
+//
+// The aggregate is not what this bounds and must not be read as one: `followup` makes roughly 573
+// requests across a 32-minute wait, and what caps that wait is its own attempt count. All this
+// guarantees is that no single request holds it forever.
+//
+// **What a timed-out read costs its caller is decided by that caller, and two are worth naming.**
+// In the merge gate's poll loop (`wait_for_pr_success`) it is one unreadable poll: the loop retries
+// on its next interval and gives up on the third consecutive failure (joshuafolkken/kit#1077), so a
+// timeout, a 403, a rate limit and a dropped connection all end the wait loudly rather than hanging
+// or reading as a verdict, and re-running `followup` resumes it. In `followup`'s look-ahead it costs
+// a log line: `handle_watch_failure` absorbs the error and falls through to the polling.
+//
+// **A timed-out *write* is not proof the write did not land.** The request may have reached GitHub
+// before the spawn was killed, so a caller that retries one can duplicate it — `josh propagate`'s
+// consumer issue is the case, and it reports the step as failed rather than retrying for exactly
+// that reason. This is not new with the budget (a dropped connection has always had the property),
+// but the budget makes it reachable on a healthy network, so it is written down here.
+const GH_REQUEST_TIMEOUT_MS = 60_000
+
+// **The override is a field on the request, not a second argument.** Every other knob on this layer
+// — `method`, `body`, `should_paginate`, `should_slurp`, `jq_filter` — is already a field of
+// `GhApiRequest`, and a budget is one more property of the request rather than of the call; putting
+// it in a positional slot would be the only property of a request described somewhere else, and both
+// `exec_gh_api` and `exec_gh_api_sync` would have to thread it separately. None of the ~27 REST call
+// sites overrides it today, so a positional argument would buy no ergonomics it could spend.
+//
+// The two `gh`-command entries take it as a plain forwarded parameter instead: they have no call
+// site outside this module — they exist as `exec_gh_api`'s transport — so there is no calling
+// convention out there for them to keep consistent with.
+function to_timeout_option(timeout_ms?: number): { timeout: number } {
+	return { timeout: timeout_ms ?? GH_REQUEST_TIMEOUT_MS }
+}
+
+// **`gh` dials GitHub directly, never through a proxy this machine stood up on loopback**
+// (joshuafolkken/kit#2436). A package-manager wrapper writes one into the environment of everything
+// its invocation spawns, and it exists to inspect package downloads — api.github.com crosses it
+// without inspection, so the hop buys nothing and can fail on its own: measured on
+// joshuafolkken/kit#2422, one 30-second stall made the wrapper refuse every later GitHub connection
+// of that `followup`, and the retries in the poll loop could only ever fail. The loopback test and
+// the list of spellings are the agent-session launcher's (joshuafolkken/kit#1760), shared rather than
+// restated. Only the scanner's proxy goes — recognized by its CA — because any other loopback proxy
+// may be this machine's only route out; a proxy naming a real host is somebody's network and stays.
+// Nothing is spread when there is nothing to remove, so a spawn outside such a wrapper keeps its
+// options exactly as they were.
+//
+// **It is exported because this file is not the only place `gh` is spawned.** The synchronous
+// readers that spell their own `gh api` (`gh-spawn.ts`, `repo-setting.ts`, `epic-cross-repo.ts`,
+// `version-remote.ts`, `propagate-publish.ts`) spread it too, and `git-gh-exec-proxy.test.ts` refuses
+// a new `gh api` spawn anywhere under `scripts/` that does not.
+interface DirectEnvironment {
+	env?: Record<string, undefined>
+}
+
+function direct_environment(): DirectEnvironment {
+	const removed = agent_session_environment.removed_proxy_environment()
+
+	return Object.keys(removed).length > 0 ? { env: removed } : {}
+}
+
+function to_spawn_options(timeout_ms?: number): { timeout: number } & DirectEnvironment {
+	return { ...to_timeout_option(timeout_ms), ...direct_environment() }
+}
+
+// What a request that ran out of time is labelled with, ahead of whatever gh managed to write.
+//
+// The distinction is joshuafolkken/kit#1048's, on a new failure: "the server said no" and "nobody
+// ever got an answer" are different diagnoses, and a timeout is the second. execa names it on the
+// error it throws, and without the prefix a hang that had written a line to stderr first would
+// arrive as that line — reported as whatever it happened to say instead of as a timeout.
+const GH_REQUEST_TIMEOUT_MESSAGE = 'gh request timed out'
+
+function has_stderr_field(error: unknown): error is Error & { stderr: string } {
+	return error instanceof Error && 'stderr' in error && typeof error.stderr === 'string'
+}
+
+// execa attaches the captured output to the error it throws, which is where the status line lands
+// when `gh api` exits non-zero — the case the whole probe exists for.
+function has_stdout_field(error: unknown): error is Error & { stdout: string } {
+	return error instanceof Error && 'stdout' in error && typeof error.stdout === 'string'
+}
+
+// `has_timed_out` is shared with the push transport rather than restated here: execa marks a spawn
+// it killed the same way whichever binary was spawned, and `git push` gained a budget of its own in
+// joshuafolkken/kit#1251.
+function to_timeout_prefix(error: unknown): string {
+	return has_timed_out(error) ? `${GH_REQUEST_TIMEOUT_MESSAGE}: ` : ''
+}
+
+function to_error_message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+// Surface the gh CLI's stderr as the thrown message when present (matching the previous spawn
+// behavior), otherwise fall back to execa's own message — **and append what gh wrote to stdout**.
+//
+// The append is not cosmetic. `gh api` splits a failed request across both streams: stderr carries
+// one summary line (`gh: Validation Failed (HTTP 422)`) and **stdout carries the JSON error body**,
+// which is the only place the reason is written. Every caller here is now a REST request, so
+// dropping stdout dropped the diagnosis from every REST failure — and `handle_pr_create_error`
+// reads the reason: a duplicate pull request is `A pull request already exists for <owner>:<branch>.`
+// inside that body, and matching it against stderr alone answers no (measured on
+// joshuafolkken/kit#1029).
+//
+// The same stdout is what carries the request's own failure nature, so the classification is
+// attached here rather than reconstructed by a later probe: GitHub's error document names its status
+// and a request that never arrived wrote no document at all (joshuafolkken/kit#1690).
+function to_gh_error(error: unknown): Error {
+	const stderr = has_stderr_field(error) ? error.stderr.trim() : ''
+	const stdout = has_stdout_field(error) ? error.stdout.trim() : ''
+	const summary = stderr.length > 0 ? stderr : to_error_message(error)
+	const detail = stdout.length > 0 ? `${summary}\n${stdout}` : summary
+
+	return gh_failure.attach(
+		new Error(`${to_timeout_prefix(error)}${detail}`, { cause: error }),
+		gh_failure.classify_stdout(stdout),
+	)
+}
+
+async function exec_gh_command(arguments_: Array<string>, timeout_ms?: number): Promise<string> {
+	await check_gh_installed()
+
+	try {
+		const { stdout } = await execa('gh', arguments_, to_spawn_options(timeout_ms)) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+		return stdout.trimEnd()
+	} catch (error) {
+		throw to_gh_error(error)
+	}
+}
+
+async function exec_gh_command_with_stdin(input: {
+	args: Array<string>
+	stdin_body: string
+	// `number | undefined` rather than plain optional: `exec_gh_api` forwards its own optional field,
+	// which `exactOptionalPropertyTypes` will not narrow for it.
+	timeout_ms?: number | undefined
+}): Promise<string> {
+	await check_gh_installed()
+
+	// Built ahead of the call so the spawn itself stays on one line: `// NOSONAR` suppresses the rule
+	// only on the line it sits on, and a wrapped call moves that line away from the reported one.
+	const options = { input: input.stdin_body, ...to_spawn_options(input.timeout_ms) }
+
+	try {
+		const { stdout } = await execa('gh', input.args, options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+		return stdout.trimEnd()
+	} catch (error) {
+		throw to_gh_error(error)
+	}
+}
+
+// The status line `gh api --include` prints before the headers, e.g. `HTTP/2.0 404 Not Found`.
+const STATUS_LINE_PATTERN = /^HTTP\/[\d.]+ (?<status>\d{3})\b/u
+
+function parse_status_line(output: string): number | undefined {
+	const { status } = STATUS_LINE_PATTERN.exec(output)?.groups ?? {}
+
+	return status === undefined ? undefined : Number(status)
+}
+
+// The HTTP status of one `gh api` request, read from the status line rather than from `gh`'s error
+// text. A message is prose that can be reworded between releases; the status code is the protocol,
+// so a caller distinguishing "there is nothing at that number" (404) from "the read failed" (403,
+// 429, 5xx) is matching a contract instead of a string (joshuafolkken/kit#957).
+//
+// `--silent` drops the response body, so only the headers are parsed; `--include` keeps them even
+// when the request failed, and execa carries that output on the error it throws. `undefined` means
+// no status was reached at all — gh missing, a dropped connection — which is itself a failed read.
+//
+// **The fifth spawn in this file, and guarded like the other four** (joshuafolkken/kit#1065). It is
+// not one of the entries joshuafolkken/kit#1065 enumerated, and that is exactly why it is included:
+// leaving one unbounded `gh` spawn beside four bounded ones is the inconsistency that Issue argues
+// against, in the same file. Its contract is unchanged — a timeout reaches the `catch` and answers
+// `undefined`, which already means "no status was reached", which its one caller already reads as a
+// failed read rather than as a 404.
+async function exec_gh_api_status(path: string, timeout_ms?: number): Promise<number | undefined> {
+	// Hoisted so the spawn below fits on one line, which `// NOSONAR` requires — it suppresses only
+	// the line it sits on. The **argument list** stays an inline literal for the opposite reason:
+	// `gh-subcommand-guard.ts` resolves the subcommand from it, and hoisting that into a `const`
+	// makes the scan report `<dynamic>` instead of `api`, leaving a future edit to
+	// `['issue', 'view', …]` uncaught (joshuafolkken/kit#1063).
+	const options = to_spawn_options(timeout_ms)
+
+	try {
+		await check_gh_installed()
+		const { stdout } = await execa('gh', ['api', '--include', '--silent', path], options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+		return parse_status_line(stdout)
+	} catch (error) {
+		return has_stdout_field(error) ? parse_status_line(error.stdout) : undefined
+	}
+}
+
+const METHOD_FLAG = '--method'
+const INPUT_FLAG = '--input'
+const PAGINATE_FLAG = '--paginate'
+const SLURP_FLAG = '--slurp'
+const JQ_FLAG = '--jq'
+
+// One REST request through `gh api`. `path` is the only required field: a read names nothing else,
+// because `gh api` sends GET when neither `--method` nor a request body is given. **A `body` alone
+// is not a read** — gh promotes a request carrying `--input` to POST — so a caller that means to
+// send a body under another verb has to say `method` as well.
+//
+// `body` is handed to gh on stdin (`--input -`) rather than as a file or as repeated `-f key=value`
+// pairs — a JSON body then needs no temporary file and no per-field escaping. `jq_filter` unwraps
+// one value out of the response, so a caller wanting a single field gets the value rather than an
+// object to parse.
+//
+// `should_slurp` goes with `should_paginate`, and **which endpoints need it is the whole point**:
+// gh merges the pages of an endpoint that answers a bare JSON *array* into one array, so a paged
+// comment listing arrives already parseable and must NOT slurp — `--slurp` would wrap it as
+// `[[…],[…]]`, which every array schema then rejects. An endpoint answering an *object* is the case
+// this field exists for: `--paginate` alone emits one document per page, so a two-page response
+// arrives as `{…}{…}`, which `JSON.parse` rejects, and `--slurp` wraps those pages in one outer
+// array instead. It is a separate field rather than implied by `should_paginate` for that reason,
+// and because gh refuses it alongside `--jq` (joshuafolkken/kit#1027).
+interface GhApiRequest {
+	path: string
+	method?: string
+	body?: string
+	should_paginate?: boolean
+	should_slurp?: boolean
+	jq_filter?: string
+	// The budget for this one request, overriding `GH_REQUEST_TIMEOUT_MS`. A field rather than a
+	// second argument for the reason recorded beside that constant (joshuafolkken/kit#1065).
+	timeout_ms?: number
+}
+
+function optional_flag(flag: string, value?: string): Array<string> {
+	return value === undefined ? [] : [flag, value]
+}
+
+function to_gh_api_args(request: GhApiRequest): Array<string> {
+	const body_args = request.body === undefined ? [] : [INPUT_FLAG, BODY_FROM_STDIN]
+	const paginate_args = request.should_paginate === true ? [PAGINATE_FLAG] : []
+	const slurp_args = request.should_slurp === true ? [SLURP_FLAG] : []
+
+	return [
+		'api',
+		request.path,
+		...optional_flag(METHOD_FLAG, request.method),
+		...body_args,
+		...paginate_args,
+		...slurp_args,
+		...optional_flag(JQ_FLAG, request.jq_filter),
+	]
+}
+
+// The response body of one `gh api` request, as text. Every REST caller that can await one goes
+// through it, so the verb, the body and the paging stop being spelled out per call site
+// (joshuafolkken/kit#1023). The synchronous readers that cannot — `gh-spawn.ts`, `epic-cross-repo.ts`
+// — still share its path builder.
+//
+// Failure handling funnels through `to_gh_error` on both paths below, so a failed request throws
+// with gh's stderr summary *and* the JSON error body it wrote to stdout.
+async function exec_gh_api(request: GhApiRequest): Promise<string> {
+	const args = to_gh_api_args(request)
+
+	if (request.body === undefined) return await exec_gh_command(args, request.timeout_ms)
+
+	return await exec_gh_command_with_stdin({
+		args,
+		stdin_body: request.body,
+		timeout_ms: request.timeout_ms,
+	})
+}
+
+// The synchronous twin of `exec_gh_api`, for a caller that cannot await. `josh propagate` runs each
+// consumer's steps as a sequential chain of `execaSync` spawns with inherited stdio, and that shape
+// reaches from `open_issue` up through `RunStep`, `run_target` and `run_targets` — so the issue it
+// opens in the consumer is created here rather than by turning the whole runner asynchronous for
+// one request (joshuafolkken/kit#1042).
+//
+// It is the **write** side's synchronous entry, and the only one so far. The synchronous *readers*
+// named above `exec_gh_api` — `gh-spawn.ts`, `epic-cross-repo.ts`, `repo-setting.ts`,
+// `propagate-publish.ts`, `version-remote.ts` — each spell their own `['api', path, '--jq', …]` out
+// and share only the path builder; a read has no body and no verb to get wrong, which is why they
+// were left as they are rather than migrated here in passing.
+//
+// **It is the same layer, not a second one.** The argument builder and the error translation are
+// shared with the asynchronous path above, so `--input -` for the body, `--jq` for the unwrap, and
+// the failure text that carries the JSON reason REST writes to stdout are each defined once.
+//
+// The body travels over stdin here too: `execaSync` accepts `input`, so multi-line markdown depends
+// on no shell quoting — the same property `exec_gh_command_with_stdin` gives the asynchronous path.
+//
+// `check_gh_installed` is the one thing it cannot share, because it awaits. A missing gh surfaces as
+// the spawn's own failure and is reported like any other, which is what the direct spawn this
+// replaced already did.
+function exec_gh_api_sync(request: GhApiRequest): string {
+	const body_option = request.body === undefined ? {} : { input: request.body }
+	const options = { ...body_option, ...to_spawn_options(request.timeout_ms) }
+
+	try {
+		const { stdout } = execaSync('gh', to_gh_api_args(request), options) // NOSONAR S8705: execa array args (no shell), trusted dev CLI tooling
+
+		return stdout.trimEnd()
+	} catch (error) {
+		throw to_gh_error(error)
+	}
+}
+
+const git_gh_exec = {
+	direct_environment,
+	exec_gh_command,
+	exec_gh_command_with_stdin,
+	exec_gh_api,
+	exec_gh_api_sync,
+	exec_gh_api_status,
+	parse_status_line,
+}
+
+export type { GhApiRequest }
+export { git_gh_exec, has_stderr_field, has_stdout_field }
+export { BODY_FROM_STDIN, GH_REQUEST_TIMEOUT_MESSAGE, GH_REQUEST_TIMEOUT_MS }

package/scripts/git/git-gh-failure.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod'
+import { parse_json } from './parse-json-array'
+
+// Why one `gh api` request failed, taken from **that request** rather than from a later probe
+// (joshuafolkken/kit#1690).
+//
+// joshuafolkken/kit#957 asked the same question by issuing a second request — `exec_gh_api_status`
+// against the same path — and joshuafolkken/kit#1663 asked it again with a reachability probe fired
+// after the answer was otherwise final. Both are inferences about a request that is already over: a
+// connection that dropped for three hundred milliseconds fails the read and answers the probe
+// `reachable`, so the failure keeps the meaning the probe gave it and not the one it had.
+//
+// The nature is available on the failed request itself, and structurally rather than by wording:
+// `gh api` writes the **response body** to stdout, and GitHub's REST error document carries its own
+// status — `{"message":"Not Found","documentation_url":…,"status":"404"}`. A request that never
+// reached GitHub has no response body at all, so stdout is empty. That is the whole classification,
+// and neither half reads gh's stderr prose, which is what joshuafolkken/kit#1024 refused to key on.
+
+// GitHub's REST error document. Only the status is read: `message` and `documentation_url` are prose
+// for a person, and every other field varies by endpoint.
+//
+// The status arrives as a string (`"404"`), and a number is accepted beside it so that a future
+// serialization of the same field is read rather than dropped.
+//
+// `.catch({})` because anything at all can arrive on this path — an HTML error page from a proxy, a
+// JSON array, a bare `null`. A schema that threw there would turn "the response was not GitHub's
+// error document" into an exception the caller has to catch a second time, when the honest answer is
+// simply that no status was reported.
+const error_document_schema = z
+	.object({ status: z.union([z.string(), z.number()]).optional() })
+	.catch({})
+
+// What a failed `gh api` request said about itself.
+interface GhFailure {
+	// The HTTP status GitHub reported in the error document it wrote. `undefined` is the transport
+	// case: nothing answered, so there is no status to report — deliberately the same shape
+	// `exec_gh_api_status` already answers `undefined` for, so `gh_reachability.classify_status` reads
+	// this without a second spelling of the rule.
+	status: number | undefined
+	// Whether the request that failed came *after* one that had already succeeded — a second endpoint
+	// for a related resource, reached only because the first answered. Such a request fails about
+	// itself, so its 404 says nothing about whether the subject exists: an issue read whose blocker
+	// relations then 404 on a host without that endpoint is a readable issue, not a missing one. Only
+	// the caller knows which of its requests was which, so it is the caller that sets this
+	// (joshuafolkken/kit#1690).
+	is_followup?: boolean
+}
+
+// Attached to the thrown `Error` rather than expressed as an `Error` subclass, matching
+// `has_stderr_field` / `has_stdout_field` in `git-gh-exec.ts`: every failure in `scripts/` is a bare
+// `Error` distinguished by a field, and one subclass among them would be a second convention.
+const GH_FAILURE_FIELD = 'gh_failure'
+
+function has_gh_failure(error: unknown): error is Error & { gh_failure: GhFailure } {
+	return error instanceof Error && Object.hasOwn(error, GH_FAILURE_FIELD)
+}
+
+// The status GitHub itself reported, or `undefined` when the request produced no response body.
+//
+// A body that is not GitHub's error document — an HTML error page from a proxy, a truncated
+// response — answers `undefined` as well. That is the honest answer: something came back, but
+// nothing in it says what the status was, and guessing one would be the inference this module
+// exists to remove.
+function parse_response_status(stdout: string): number | undefined {
+	const document = parse_json.parse_json_object_safe(stdout, error_document_schema)
+	if (document?.status === undefined) return undefined
+	const status = Number(document.status)
+
+	return Number.isSafeInteger(status) ? status : undefined
+}
+
+// The classification, from the failed request's own stdout.
+function classify_stdout(stdout: string): GhFailure {
+	return { status: parse_response_status(stdout) }
+}
+
+// Put the classification on the error the caller will catch, so the nature travels with the throw
+// instead of being reconstructed from it.
+//
+// **Non-enumerable deliberately.** An error is compared, logged and serialized all over this project
+// — `expect(...).rejects.toThrow(new Error(text))` compares own enumerable properties — and an
+// annotation nobody asked for must not change what any of those see. `in` finds it regardless.
+function attach<T extends Error>(error: T, failure: GhFailure): T {
+	Object.defineProperty(error, GH_FAILURE_FIELD, {
+		value: failure,
+		enumerable: false,
+		configurable: true,
+	})
+
+	return error
+}
+
+// What a caught error said about the request that produced it, or `undefined` when it did not come
+// from a `gh api` request at all — a parse or a schema rejection, which is a read that arrived and
+// could not be used.
+function failure_of(error: unknown): GhFailure | undefined {
+	return has_gh_failure(error) ? error.gh_failure : undefined
+}
+
+const gh_failure = { attach, classify_stdout, failure_of, parse_response_status }
+
+export type { GhFailure }
+export { gh_failure, GH_FAILURE_FIELD }

package/scripts/git/git-gh-helpers.ts

@@ -0,0 +1,44 @@
+import { has_stderr_field } from './git-gh-exec'
+
+// One optional string answer from `gh`. Every caller asks with `--jq`, which unwraps the JSON
+// string itself, so the value arrives raw and there is nothing to unquote — this used to strip a
+// leading and trailing `"` anyway, which ate real characters from any answer that legitimately
+// carried them. A title of `"queue" should stop at the first failure` reached Telegram as
+// `queue" should stop at the first failure` (joshuafolkken/kit#993). Trimming and the empty answer
+// are the whole contract.
+function parse_pr_state_string(result: string): string | undefined {
+	const trimmed = result.trim()
+
+	return trimmed.length > 0 ? trimmed : undefined
+}
+
+function is_pr_already_exists_message(error_message: string): boolean {
+	return error_message.toLowerCase().includes('already exists')
+}
+
+function get_error_message_with_stderr(error: unknown): string {
+	if (!(error instanceof Error)) return String(error)
+
+	if (has_stderr_field(error) && error.stderr.length > 0) return `${error.message}\n${error.stderr}`
+
+	return error.message
+}
+
+function handle_pr_create_error(error: unknown): never {
+	const error_message = get_error_message_with_stderr(error)
+
+	if (is_pr_already_exists_message(error_message)) {
+		throw new Error('PR_ALREADY_EXISTS')
+	}
+
+	throw error
+}
+
+const git_gh_helpers = {
+	parse_pr_state_string,
+	is_pr_already_exists_message,
+	get_error_message_with_stderr,
+	handle_pr_create_error,
+}
+
+export { git_gh_helpers, parse_pr_state_string }