@joshuafolkken/kit 1.872.0

package/scripts/git/git-gh-issue-rest.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod'
+import type { IssueReference } from './git-epic-reference'
+import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
+import { parse_json_array_or_undefined, parse_json_object_safe } from './parse-json-array'
+import { blocking_issue_schema } from './schemas'
+
+// The translation between one REST issue (`repos/{owner}/{repo}/issues/{N}`) and the JSON shape
+// `gh issue view --json <fields>` used to answer with.
+//
+// `gh issue view` goes through GraphQL, which a cloud session is answered 403 for while the REST
+// endpoint is served normally (joshuafolkken/kit#1022). The reads in `git-gh-issue-read.ts` are what
+// every epic command goes through, so they move to REST — and every caller downstream keeps reading
+// the field names it already reads. The mapping lives here rather than beside the requests because
+// it is pure: given the two responses, it decides the answer with nothing else to know
+// (joshuafolkken/kit#1024).
+
+// Only the fields the mapping itself reads are named; every other key passes through untouched,
+// which is what lets a caller ask for a field this file has never heard of.
+//
+// `number` is required so that a 200 carrying something other than an issue — a proxy's HTML error
+// page, an API message object — fails the parse rather than passing as an issue whose every field is
+// missing. `git-epic-close` would turn that into `is_closed: false` for every child and report it as
+// fact. The dependency summary is absent on a pull request, which the issue endpoint serves as
+// readily as an issue, so it stays optional and tolerates an explicit null.
+const rest_issue_schema = z.looseObject({
+	number: z.number(),
+	issue_dependencies_summary: z.looseObject({ total_blocked_by: z.number().optional() }).nullish(),
+	// Present only on a pull request, which this endpoint serves as readily as an issue.
+	pull_request: z.looseObject({ merged_at: z.string().nullish() }).nullish(),
+})
+
+type RestIssue = z.infer<typeof rest_issue_schema>
+type BlockingIssue = z.infer<typeof blocking_issue_schema>
+
+// The `blockedBy` connection as `gh` reported it: `nodes` is a page, `totalCount` is exact.
+interface BlockedBy {
+	nodes: Array<BlockingIssue>
+	totalCount: number
+}
+
+// `https://api.github.com/repos/<owner>/<repo>` — the only shape REST writes, matched at the end so
+// a host or an api prefix that changes does not break the read.
+const REPOSITORY_URL = /\/repos\/([\w.-]+\/[\w.-]+)$/u
+const REPOSITORY_URL_GROUP = 1
+
+const BLOCKED_BY_FIELD = 'blockedBy'
+
+// The one field name here that `gh --json` never had, and it is spelled unlike the names beside it on
+// purpose: `blockedBy` is a connection `gh` served inside the issue, while this is the exact count
+// GitHub already puts in the listing's own `issue_dependencies_summary`. A caller that asks for it
+// learns whether an issue has blockers **without** the per-issue request that reading `blockedBy`
+// costs — which is what lets `epic:bundle` stop re-reading every open issue (joshuafolkken/kit#1736).
+//
+// It is `undefined` rather than `0` where the summary is absent — a pull request, which this
+// endpoint serves as readily as an issue, carries none. Reading that as "no blockers" is the one
+// misreading this field can cause, so the absence is preserved all the way to the caller.
+const BLOCKED_BY_COUNT_FIELD = 'blocked_by_count'
+const STATE_FIELD = 'state'
+const BODY_FIELD = 'body'
+const FIELD_SEPARATOR = ','
+const EMPTY_BODY = ''
+
+// The two field names REST and `gh --json` disagree on. `url` is the one that bites: REST's `url` is
+// the API endpoint, while `gh` answers the browser URL — and `epic_issue.is_pull_request` decides
+// from `/pull/` appearing in it, which the API endpoint never carries.
+//
+// A Map rather than an object literal so a camelCase key needs no naming-convention exemption.
+const REST_FIELD_NAMES = new Map<string, string>([
+	['url', 'html_url'],
+	['createdAt', 'created_at'],
+])
+
+const NOT_AN_ISSUE_MESSAGE = 'gh api answered something other than an issue object'
+const NOT_AN_ISSUE_LISTING_MESSAGE = 'gh api answered something other than an issue listing'
+const NOT_A_BLOCKER_LISTING_MESSAGE = 'gh api answered something other than a blocked-by listing'
+
+function rest_field_name(field: string): string {
+	return REST_FIELD_NAMES.get(field) ?? field
+}
+
+// `number,state,labels,blockedBy` — the argument every caller already passes, unchanged so that the
+// call sites keep naming the fields `gh` named.
+function split_fields(fields: string): Array<string> {
+	return fields
+		.split(FIELD_SEPARATOR)
+		.map((field) => field.trim())
+		.filter((field) => field.length > 0)
+}
+
+// `gh issue view` served a pull request as readily as an issue, and reported a merged one as
+// `MERGED`. REST answers `closed`, and the difference is not cosmetic: `epic_issue.normalize_state`
+// maps everything that is not `CLOSED` to `OPEN`, so `MERGED` is what keeps a pull request pasted
+// into an epic's task list from letting the auto-close run, and what keeps `epic:audit`'s
+// "both closed" check on its loud side. Mapping it to `CLOSED` would flip both guards in silence.
+function to_issue_state(rest: RestIssue, value: unknown): unknown {
+	if (typeof rest.pull_request?.merged_at === 'string') return MERGED_STATE
+
+	return typeof value === 'string' ? to_gh_state(value) : value
+}
+
+// The exact blocker count GitHub reports on the issue itself. `nodes` is one page, so this is what
+// keeps `totalCount` meaning what it meant under GraphQL rather than collapsing to the page size.
+function total_blocked_by(rest: RestIssue): number | undefined {
+	return rest.issue_dependencies_summary?.total_blocked_by
+}
+
+function to_gh_field_value(field: string, rest: RestIssue): unknown {
+	if (field === BLOCKED_BY_COUNT_FIELD) return total_blocked_by(rest)
+
+	const value = rest[rest_field_name(field)]
+
+	if (field === STATE_FIELD) return to_issue_state(rest, value)
+
+	// REST answers JSON null for an issue with no body, where `gh --json body` answers an empty
+	// string — and `issue_get_body` hands its result straight to callers that expect text.
+	return field === BODY_FIELD ? (value ?? EMPTY_BODY) : value
+}
+
+// A response that is not an issue object throws rather than degrading to an empty read: the callers
+// catch it into `undefined`, which is the same "the read failed" every other failure produces, while
+// a partial object would be reported as an issue whose fields are all missing.
+function parse_rest_issue(rest_json: string): RestIssue {
+	const parsed = parse_json_object_safe(rest_json, rest_issue_schema)
+	if (parsed === undefined) throw new Error(NOT_AN_ISSUE_MESSAGE)
+
+	return parsed
+}
+
+// `repos/{owner}/{repo}/issues` serves pull requests alongside issues; `gh issue list` never did,
+// and its six callers all read the answer as issues. The key is present on a pull request and
+// absent on an issue, which is the same signal `to_issue_state` already reads
+// (joshuafolkken/kit#1025).
+function is_pull_request(rest: RestIssue): boolean {
+	return rest.pull_request !== undefined && rest.pull_request !== null
+}
+
+// One page of the listing endpoint, whose elements are the same objects `parse_rest_issue` reads one
+// of. It throws for the reason that one does: a response that is not a listing — `gh` answering
+// `{"message":"API rate limit exceeded"}` — must not degrade into an empty listing, which every
+// caller here reads as "there is nothing" (joshuafolkken/kit#950).
+function parse_rest_issues(rest_json: string): Array<RestIssue> {
+	const parsed = parse_json_array_or_undefined(rest_json, rest_issue_schema)
+	if (parsed === undefined) throw new Error(NOT_AN_ISSUE_LISTING_MESSAGE)
+
+	return parsed
+}
+
+// The connection for an issue GitHub itself says has no blockers, answered without a request. `gh`
+// sent `blockedBy` inside the issue response, so a second request per issue would double
+// `epic:bundle`'s pass over the whole open backlog — and the issue's own summary settles the common
+// case, which is an issue with no blockers at all (joshuafolkken/kit#1024).
+function empty_blocked_by(): BlockedBy {
+	return { nodes: [], totalCount: 0 }
+}
+
+// The `owner/repo` a REST `repository_url` names — `https://api.github.com/repos/<owner>/<repo>`.
+//
+// A blocker relation may cross a repository, and the number alone cannot say which one it is: issue
+// numbers are unique per repository, so a blocker read bare resolves against the blocked child's own
+// repository and names a different issue there (joshuafolkken/kit#1126). Undefined when the field is
+// absent or shaped otherwise; the caller then falls back to the repository it is reading in, which is
+// what an unqualified relation has always meant.
+function repo_of_url(repository_url: string | undefined): string | undefined {
+	const match = REPOSITORY_URL.exec(repository_url ?? '')
+
+	return match?.[REPOSITORY_URL_GROUP]
+}
+
+// `repos/{owner}/{repo}/issues/{N}/dependencies/blocked_by` answers a bare array of issues, which is
+// mapped into the connection `blocked_by_schema` expects.
+//
+// A listing that will not parse throws instead of answering an empty connection. That direction is
+// the point: an empty `nodes` reads as "this child has no blockers", and `epic:next` would then hand
+// a dependent to an unattended run before its prerequisite (joshuafolkken/kit#1005).
+function to_blocked_by(blockers_json: string, exact_total?: number): BlockedBy {
+	const parsed = parse_json_array_or_undefined(blockers_json, blocking_issue_schema)
+	if (parsed === undefined) throw new Error(NOT_A_BLOCKER_LISTING_MESSAGE)
+
+	const nodes = parsed.map((blocker) => ({ ...blocker, state: to_gh_state(blocker.state) }))
+
+	return { nodes, totalCount: exact_total ?? nodes.length }
+}
+
+// The requested fields, under the names `gh` gave them. A field REST does not carry is left out
+// rather than filled in, exactly as an unknown `--json` field produced nothing before.
+function to_gh_issue(
+	rest: RestIssue,
+	fields: ReadonlyArray<string>,
+	blocked_by?: BlockedBy,
+): Record<string, unknown> {
+	return Object.fromEntries(
+		fields.map((field) => [
+			field,
+			field === BLOCKED_BY_FIELD ? blocked_by : to_gh_field_value(field, rest),
+		]),
+	)
+}
+
+// One field as `--jq .<field>` printed it: a string bare, anything else as JSON, an absent value as
+// the empty answer that already meant "there is nothing to show".
+function to_field_text(value: unknown): string {
+	if (typeof value === 'string') return value
+
+	return value === undefined || value === null ? EMPTY_BODY : JSON.stringify(value)
+}
+
+const CLOSED = 'CLOSED'
+
+// One blocker node as a reference, keeping the state the relation response carried
+// (joshuafolkken/kit#1943). Single-sourced here because the snapshot read and the candidate re-read
+// both unwrap the same node, and the state is omitted rather than guessed when REST did not send it.
+function reference_of_blocker(
+	node: z.infer<typeof blocking_issue_schema>,
+	fallback_repo: string,
+): IssueReference {
+	const repo = repo_of_url(node.repository_url) ?? fallback_repo
+
+	if (node.state === undefined) return { repo, number: node.number }
+
+	return { repo, number: node.number, state: node.state.toUpperCase() === CLOSED ? CLOSED : 'OPEN' }
+}
+
+const git_gh_issue_rest = {
+	empty_blocked_by,
+	repo_of_url,
+	reference_of_blocker,
+	split_fields,
+	is_pull_request,
+	parse_rest_issue,
+	parse_rest_issues,
+	total_blocked_by,
+	to_blocked_by,
+	to_gh_issue,
+	to_field_text,
+}
+
+export type { BlockedBy, RestIssue }
+export { git_gh_issue_rest, BLOCKED_BY_FIELD, BLOCKED_BY_COUNT_FIELD }

package/scripts/git/git-gh-issue-write.ts

@@ -0,0 +1,285 @@
+import { git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec, type GhApiRequest } from './git-gh-exec'
+
+// Writing issues and labels through REST, in the return-value contracts the `gh <noun> <verb>`
+// wrappers had.
+//
+// `gh issue edit` / `comment` / `create` / `close` and `gh label create` all go through GraphQL,
+// which a cloud session is answered 403 for while the REST endpoints are served normally
+// (joshuafolkken/kit#1022). Split out of `git-gh-issue.ts` rather than added to it: that file was
+// already at 215 of the 300 lines a file may hold, and the reads had been split out for the same
+// reason (joshuafolkken/kit#957, joshuafolkken/kit#1026).
+//
+// **Every path here was measured against the live API before it was written.**
+// joshuafolkken/kit#1022 deliberately measured only the reads, because a write has side effects, and
+// left the write side as candidates to confirm one at a time. They were confirmed on a pair of
+// throwaway issues, and one of them did not behave as its name suggests — see `read_issue_id`.
+//
+// The bodies still travel over stdin: `exec_gh_api` hands `body` to gh as `--input -`, so multi-line
+// markdown depends on no shell quoting, exactly as `--body-file -` did before.
+
+// `gh api` promotes a request carrying `--input` to POST, so a creation names no method; the two
+// verbs that are not implied by a body do.
+const PATCH_METHOD = 'PATCH'
+const DELETE_METHOD = 'DELETE'
+
+// `gh issue edit`, `gh issue comment` and `gh issue create` each printed one URL, and the callers
+// read it — `git-epic-run.ts` parses the epic's number back out of it. REST answers the whole
+// object, so the same value is unwrapped out of it rather than the shape being changed.
+const HTML_URL_FILTER = '.html_url'
+const ID_FILTER = '.id'
+
+const LABELS_SEGMENT = '/labels'
+const COMMENTS_SEGMENT = '/comments'
+const CLOSED_STATE = 'closed'
+const COLOR_HASH = '#'
+
+// The four writers below answered `boolean` under `gh`, and their callers read it: `git-epic-run.ts`
+// only reports the epic label when it was applied, `git-epic-relations.ts` counts the relations it
+// could not apply, and `git-epic-close.ts` prints "close it manually" on a false. One try/catch
+// rather than four copies of it (`CLAUDE.md` → "No clones").
+async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean> {
+	try {
+		await write()
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+async function issue_edit_body(issue_number: string, body: string): Promise<string> {
+	return await git_gh_exec.exec_gh_api({
+		path: git_gh_api_path.issue_api_path(issue_number),
+		method: PATCH_METHOD,
+		body: JSON.stringify({ body }),
+		jq_filter: HTML_URL_FILTER,
+	})
+}
+
+async function issue_comment(issue_number: string, body: string): Promise<string> {
+	return await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.issue_api_path(issue_number)}${COMMENTS_SEGMENT}`,
+		body: JSON.stringify({ body }),
+		jq_filter: HTML_URL_FILTER,
+	})
+}
+
+// The same comment, counted rather than thrown. `josh epic --add --decision-file` posts one per child
+// **after** the epic body already carries the record, so a refused comment costs that child's copy and
+// nothing else — an exception there would leave the caller unable to tell a landed insertion from one
+// that wrote nothing (joshuafolkken/kit#1350).
+async function issue_try_comment(issue_number: string, body: string): Promise<boolean> {
+	return await did_write_succeed(async () => await issue_comment(issue_number, body))
+}
+
+// `gh issue close --comment` posted the comment and closed the issue in one call; REST splits them.
+// **The comment goes first**, which is what keeps the return value meaning what it meant: a `false`
+// then says "the issue is still open" in *both* failure branches, because the state change is the
+// last thing attempted. Closing first would answer `false` for an issue that is in fact closed, and
+// `git-epic-close.ts` prints "close it manually" on that answer.
+//
+// **`comment: undefined` closes without commenting**, and it is what the ordering above costs: a run
+// whose comment landed and whose close was refused leaves the issue open carrying the comment, so
+// the next run must close it without posting a second copy (joshuafolkken/kit#1039). The return
+// value keeps meaning what it meant — with no comment to post, the state change is not merely the
+// last thing attempted but the only one.
+//
+// It is a required parameter that may be `undefined` rather than an optional one: skipping the
+// announcement is a decision the caller makes from what it read, never something a call site can
+// fall into by leaving an argument off.
+async function issue_close(issue_number: string, comment: string | undefined): Promise<boolean> {
+	return await did_write_succeed(async () => {
+		if (comment !== undefined) await issue_comment(issue_number, comment)
+		await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.issue_api_path(issue_number),
+			method: PATCH_METHOD,
+			body: JSON.stringify({ state: CLOSED_STATE }),
+		})
+	})
+}
+
+// `gh label create` accepted `#5319e7` and stripped the `#` itself; REST answers 422
+// `{"resource":"Label","code":"invalid","field":"color"}` for the same value. The one caller passes
+// the hash form (`EPIC_LABEL_COLOR`), so dropping it here is what keeps that call site unchanged.
+function to_label_color(color: string): string {
+	return color.startsWith(COLOR_HASH) ? color.slice(COLOR_HASH.length) : color
+}
+
+// `|| true` semantics, unchanged: an existing label answers 422 `already_exists`, which is not an
+// error here.
+//
+// **What swallowing it costs did change, and in the safe direction.** Under `gh`, a label this call
+// failed to create surfaced later — `gh issue create --label epic` could not resolve it and failed
+// there. REST does not fail: `POST /issues` with `labels: [...]`, and `POST /issues/{N}/labels`,
+// both **create** a label the repository does not have, with a generated color and no description
+// (measured on joshuafolkken/kit#1026). So a swallowed failure here costs the label's color and
+// description, never the label itself — `epic:next` and the auto-close filter on the name, and the
+// name is applied either way.
+async function label_ensure(input: {
+	name: string
+	color: string
+	description: string
+}): Promise<void> {
+	try {
+		await git_gh_exec.exec_gh_api({
+			path: `${git_gh_api_path.repo_api_path()}${LABELS_SEGMENT}`,
+			body: JSON.stringify({
+				name: input.name,
+				color: to_label_color(input.color),
+				description: input.description,
+			}),
+		})
+	} catch {
+		/* the label already exists */
+	}
+}
+
+// What creating an issue over REST means, as one value both execution paths build from: the
+// collection to post to, the JSON body, and the `.html_url` unwrap that answers the browser URL
+// `gh issue create` used to print.
+//
+// It exists as a request rather than only as the writer below because `josh propagate` opens its
+// consumer's issue **synchronously** and cannot await (joshuafolkken/kit#1042). Spelling the same
+// three decisions out again at that call site would be a second definition of the same write
+// (`CLAUDE.md` → "No clones"), so the request is shared and only the spawn differs.
+//
+// `repo` names another repository, which is what propagation needs — the issue belongs to the
+// consumer, not to the repository the command runs in. `labels` is left off the body entirely when
+// there is none, rather than sent as an empty array: an issue with no label is what omitting the
+// field means to the endpoint, and it keeps the labelled form the only one that creates a label.
+function issue_create_request(input: {
+	title: string
+	body: string
+	labels?: ReadonlyArray<string>
+	repo?: string
+}): GhApiRequest {
+	const { labels } = input
+
+	return {
+		path: git_gh_api_path.issues_api_path(input.repo),
+		body: JSON.stringify({
+			title: input.title,
+			...(labels !== undefined && { labels }),
+			body: input.body,
+		}),
+		jq_filter: HTML_URL_FILTER,
+	}
+}
+
+// The browser URL of the created issue, which is what `gh issue create` printed and what
+// `git-epic-run.ts` parses the epic's number out of.
+async function issue_create_with_label(input: {
+	title: string
+	label: string
+	body: string
+}): Promise<string> {
+	return await git_gh_exec.exec_gh_api(
+		issue_create_request({ title: input.title, body: input.body, labels: [input.label] }),
+	)
+}
+
+// Applied after the body edit so a failure leaves an issue with the epic sections and no label,
+// which `epic:check` reports — rather than a labelled issue with nothing to track. The caller checks
+// the return: the label is what the auto-close filters on (joshuafolkken/kit#865).
+async function issue_add_label(issue_number: string, label: string): Promise<boolean> {
+	return await did_write_succeed(
+		async () =>
+			await git_gh_exec.exec_gh_api({
+				path: `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`,
+				body: JSON.stringify({ labels: [label] }),
+			}),
+	)
+}
+
+// The counterpart to the addition above, for a run taking its own marker back off
+// (joshuafolkken/kit#1794). **The name travels in the path, so it is encoded**: a label is free to
+// contain a `/` or a `#`, and an unencoded one would address a path that is not this label's.
+//
+// **It throws rather than answering `boolean`**, which is the one place it departs from
+// `issue_add_label`. Its caller is a post-merge cleanup step, and the guard there
+// (`git-followup-cleanup.ts`) reports a failure by name with the command that finishes it by hand —
+// a `false` swallowed here would reach that guard as a success and the step would be reported as
+// done.
+async function issue_remove_label(issue_number: string, label: string): Promise<void> {
+	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
+
+	await git_gh_exec.exec_gh_api({
+		path: `${labels_path}/${encodeURIComponent(label)}`,
+		method: DELETE_METHOD,
+	})
+}
+
+// The blocker's **database id**, which is the only thing the dependencies endpoint accepts — and the
+// reason this resolution exists rather than the issue number being sent straight through.
+//
+// The endpoint takes `{"issue_id": <n>}` and does not check that `<n>` is an issue in this
+// repository, or that it is the number the caller meant. Posting `{"issue_id":1036}` to a scratch
+// issue in this repository recorded an issue in a completely unrelated repository — the one whose
+// database id happens to be 1036 — as a blocker, with a 200 and no warning (measured on
+// joshuafolkken/kit#1026, which names it). Every caller here names a blocker by its issue number, so
+// sending that number would silently record an arbitrary issue from anywhere on GitHub.
+//
+// A resolution that does not produce a usable id throws rather than returning something to send:
+// `jq` prints an empty line for a field it cannot reach, and `Number('')` is `0`, which is a value
+// the endpoint would happily be given.
+async function read_issue_id(issue_number: string): Promise<number> {
+	const raw = await git_gh_exec.exec_gh_api({
+		path: git_gh_api_path.issue_api_path(issue_number),
+		jq_filter: ID_FILTER,
+	})
+	const issue_id = Number(raw.trim())
+
+	if (!Number.isSafeInteger(issue_id) || issue_id <= 0) {
+		throw new Error(`gh api answered no database id for issue #${issue_number}`)
+	}
+
+	return issue_id
+}
+
+// Applied after creation, never as part of it: the relation is a nicety and the Issue is not, so a
+// failure here costs only the relation. It no longer depends on the gh CLI's version — the
+// dependencies endpoint is REST, and `gh api` has proxied REST since long before `--add-blocked-by`
+// existed (joshuafolkken/kit#1026).
+async function issue_add_blocked_by(issue_number: string, blocker: string): Promise<boolean> {
+	return await did_write_succeed(async () => {
+		const issue_id = await read_issue_id(blocker)
+
+		await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.blocked_by_api_path(issue_number),
+			body: JSON.stringify({ issue_id }),
+		})
+	})
+}
+
+// The counterpart, for an insertion that re-points an existing chain: inserting `#N` between `#B`
+// and `#M` has to drop `#B -> #M`, or the epic would declare one order and record two
+// (joshuafolkken/kit#890). The id goes in the path here rather than in a body, and the endpoint is
+// idempotent — deleting a relation that is not there answers 200.
+async function issue_remove_blocked_by(issue_number: string, blocker: string): Promise<boolean> {
+	return await did_write_succeed(async () => {
+		const issue_id = await read_issue_id(blocker)
+		const relations_path = git_gh_api_path.blocked_by_api_path(issue_number)
+
+		await git_gh_exec.exec_gh_api({
+			path: `${relations_path}/${String(issue_id)}`,
+			method: DELETE_METHOD,
+		})
+	})
+}
+
+const git_gh_issue_write = {
+	issue_edit_body,
+	issue_comment,
+	issue_try_comment,
+	issue_close,
+	label_ensure,
+	issue_create_request,
+	issue_create_with_label,
+	issue_add_label,
+	issue_remove_label,
+	issue_add_blocked_by,
+	issue_remove_blocked_by,
+}
+
+export { git_gh_issue_write }