@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/issue/issue-release-cli.ts

@@ -18,16 +18,21 @@ import { session_cite } from './session-cite'
 // --release` calls the same `link` once its Issue exists, so a new and an existing Issue are linked
 // by one body of code.
 //
+// `--wait` points the edge the other way: `<N>` is blocked by the release Issue, so a run that needs
+// the published version records a dependency rather than a `needs-decision` park, and the backlog
+// offers `<N>` again once a person closes the release Issue (joshuafolkken/kit#3824).
+//
 // The relation is written through `issue_add_blocked_by`, which addresses the repository `gh`
 // resolves — the current one, or the target a cross-repository `issue:file` has pointed `GH_REPO` at.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh issue:release <issue-number>'
+const USAGE = 'Usage: josh issue:release <issue-number> [--wait]'
 const NONE = 'none'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote` — check `gh auth status`.'
+const OPTIONS = { wait: { type: 'boolean' } } as const
 
 interface ReleaseIssue {
 	issue_number: number
@@ -35,7 +40,20 @@ interface ReleaseIssue {
 	is_filed: boolean
 }
 
+interface ReleaseRequest {
+	issue_number: number
+	// `<N>` waits on the release Issue, rather than blocking it.
+	is_wait: boolean
+}
+
+// The two ends of one `blocked_by` edge.
+interface Edge {
+	blocked: number
+	blocker: number
+}
+
 // `undefined` when the listing is unreadable, `NONE` when it reads and names no open release Issue.
+// `pnpm josh release` asks the same question to close the Issue it has just published.
 async function find_open(target: string): Promise<number | typeof NONE | undefined> {
 	const outcome = await git_gh_issue_list.issue_list({
 		json_fields: 'number',
@@ -91,41 +109,59 @@ async function release_of(target: string): Promise<ReleaseIssue | undefined> {
 	return filed === undefined ? undefined : { issue_number: filed, is_filed: true }
 }
 
-function linked_line(release: ReleaseIssue, issue_number: number, target: string): string {
+function release_label_of(release: ReleaseIssue, target: string): string {
 	const how = release.is_filed ? 'filed' : 'open'
-	const release_cite = session_cite.issue(release.issue_number, undefined, target)
 
-	return `release: ${release_cite} (${how}) is blocked by ${session_cite.issue(issue_number, undefined, target)}`
+	return `${session_cite.issue(release.issue_number, undefined, target)} (${how})`
 }
 
-function unlinked_line(issue_number: number, blocked: string, target: string): string {
-	const blocker = session_cite.issue(issue_number, undefined, target)
+function linked_line(release: ReleaseIssue, request: ReleaseRequest, target: string): string {
+	const release_label = release_label_of(release, target)
+	const issue_label = session_cite.issue(request.issue_number, undefined, target)
 
-	return `✖ ${blocker} could not be recorded as a blocker of ${session_cite.issue(blocked, undefined, target)}`
+	return request.is_wait
+		? `release: ${issue_label} waits on ${release_label}`
+		: `release: ${release_label} is blocked by ${issue_label}`
 }
 
-// Whether Issue `issue_number` of `target` now blocks the release Issue. Every outcome is printed.
-async function link(issue_number: number, target: string): Promise<boolean> {
+function unlinked_line(edge: Edge, target: string): string {
+	const blocker = session_cite.issue(edge.blocker, undefined, target)
+
+	return `✖ ${blocker} could not be recorded as a blocker of ${session_cite.issue(edge.blocked, undefined, target)}`
+}
+
+function edge_of(release: ReleaseIssue, request: ReleaseRequest): Edge {
+	return request.is_wait
+		? { blocked: request.issue_number, blocker: release.issue_number }
+		: { blocked: release.issue_number, blocker: request.issue_number }
+}
+
+// Whether the edge between Issue `<N>` of `target` and the release Issue is now recorded. Every
+// outcome is printed.
+async function record(request: ReleaseRequest, target: string): Promise<boolean> {
 	const release = await release_of(target)
 
 	if (release === undefined) return false
-	const blocked = String(release.issue_number)
-	const is_linked = await git_gh_issue_write.issue_add_blocked_by(blocked, String(issue_number))
+	const edge = edge_of(release, request)
+	const is_linked = await git_gh_issue_write.issue_add_blocked_by(
+		String(edge.blocked),
+		String(edge.blocker),
+	)
 
-	if (is_linked) console.info(linked_line(release, issue_number, target))
-	else console.error(unlinked_line(issue_number, blocked, target))
+	if (is_linked) console.info(linked_line(release, request, target))
+	else console.error(unlinked_line(edge, target))
 
 	return is_linked
 }
 
-// An unknown flag parses to no positionals, so it refuses the call like a missing number.
-function positionals_of(argv: ReadonlyArray<string>): ReadonlyArray<string> {
-	return cli_flags.arguments_of(argv, {})?.positionals ?? []
+// Whether Issue `issue_number` of `target` now blocks the release Issue.
+async function link(issue_number: number, target: string): Promise<boolean> {
+	return await record({ issue_number, is_wait: false }, target)
 }
 
 // The number is the one positional: a missing, malformed or second one refuses the whole call.
-function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
-	const [issue_number, ...rest] = positionals_of(argv)
+function issue_number_of(positionals: ReadonlyArray<string>): number | undefined {
+	const [issue_number, ...rest] = positionals
 	const is_single = rest.length === 0 && issue_number !== undefined
 
 	return is_single && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
@@ -133,10 +169,20 @@ function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
 		: undefined
 }
 
+// An unknown flag parses to no request at all, so it refuses the call like a missing number.
+function request_of(argv: ReadonlyArray<string>): ReleaseRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	const issue_number = issue_number_of(parsed?.positionals ?? [])
+
+	if (parsed === undefined || issue_number === undefined) return undefined
+
+	return { issue_number, is_wait: parsed.values.wait === true }
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const issue_number = issue_number_of(argv)
+	const request = request_of(argv)
 
-	if (issue_number === undefined) {
+	if (request === undefined) {
 		console.error(USAGE)
 
 		return FAILURE_EXIT_CODE
@@ -150,7 +196,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	return (await link(issue_number, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	return (await record(request, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
 // `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
@@ -158,8 +204,8 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_release_cli = { link, run }
+const issue_release_cli = { find_open, link, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
-export { issue_release_cli }
+export { issue_release_cli, NONE }

package/scripts/issue/issue-release.ts

@@ -42,7 +42,9 @@ function body_of(repo: string): string {
 		'',
 		'Every Issue this one is blocked by changes something a consumer can use only once it is published. Once they have merged, a person runs `pnpm josh release` in the primary checkout.',
 		'',
-		'Close this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'`pnpm josh release` closes this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'',
+		'Every Issue this one blocks needs the published version (`pnpm josh issue:release <N> --wait`); closing this Issue hands each of them back to the backlog.',
 		'',
 		'`auto-ok` is never applied to this Issue by a run; a person may apply it.',
 		'',

package/scripts/issue/issue-state-cli.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { IssueReadReason } from '#scripts/gh/git-gh-issue-read'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
+import { issue_report_failures } from './issue-report-failures'
 import { issue_state, type IssueState } from './issue-state'
 
 // `josh issue:state <N> [<N> ...]` — print each issue's state and labels, in the spelling the
@@ -50,7 +51,14 @@ interface StateRequest {
 // One issue's state, or the failure kind. Named for export because `run:prep` reads the state beside
 // the body and the dependency-update scope, reusing this read rather than a
 // second one that would drift from the `human_review` decision `parse_issue_state` owns.
-type StateRead = { kind: 'state'; state: IssueState } | { kind: ReadFailureKind }
+//
+// **Why a read failed rides along where the request said it**: `backlog:drive` names the reason when it
+// hands an unreadable named issue back. Both are optional, so a caller that only separates the kinds
+// needs no edit.
+type StateRead =
+	| { kind: 'state'; state: IssueState }
+	| { kind: 'missing' }
+	| { kind: 'unreadable'; reason?: IssueReadReason | undefined; status?: number | undefined }
 
 interface IssueReport {
 	issue_number: string
@@ -102,11 +110,13 @@ function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
 async function read_issue(issue_number: string, repo?: string): Promise<StateRead> {
 	const read = await git_gh_command.issue_view_json_classified(issue_number, STATE_FIELDS, repo)
 
-	if (read.kind !== 'read') return { kind: read.kind }
+	if (read.kind !== 'read') return read
 
 	const parsed = issue_state.parse_issue_state(read.json)
 
-	return parsed === undefined ? { kind: 'unreadable' } : { kind: 'state', state: parsed }
+	return parsed === undefined
+		? { kind: 'unreadable', reason: 'malformed' }
+		: { kind: 'state', state: parsed }
 }
 
 // Through the shared pool rather than a raw `Promise.all`: each read spawns a `gh` process, and a

package/scripts/issue/issue-watch-diff.ts

@@ -0,0 +1,152 @@
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// What a person changed on an issue since a run last read it, as the one pure answer the hook, the
+// review attestation, `josh issue:ack` and `josh followup` all print. Kept free of I/O so the four
+// callers cannot each draw the line between "a person's update" and "noise" differently.
+//
+// **A person's update is a body edit or a comment nobody automated.** A bot's comment (`type: Bot`,
+// or a `[bot]` login) is not one. A run's own comment is posted under the person's own `gh` login,
+// so the login cannot tell the two apart; `git-gh-issue-write.ts` stamps every comment josh posts
+// with `RUN_MARKER`, and a marked comment is not one either. An unmarked comment written by hand
+// through a raw `gh api` counts as a person's — the direction that costs one `josh issue:ack`, never a
+// missed correction.
+//
+// **Comment edits are out of scope.** A new comment carries an id above the baseline's; an edited
+// one keeps its id and is not seen. The body is compared whole, so its edits are.
+
+const RUN_MARKER = '<!-- josh:run -->'
+const BOT_TYPE = 'Bot'
+const BOT_SUFFIX = '[bot]'
+const NO_COMMENT_ID = 0
+const UNKNOWN_AUTHOR = '(unknown)'
+const UNKNOWN_TIME = '(undated)'
+
+const BODY_HEADING = 'Body edited:'
+const REMOVED_PREFIX = '- '
+const ADDED_PREFIX = '+ '
+const COMMENT_HEADING = 'New comment by '
+const AT = ' at '
+const SECTION_SEPARATOR = '\n\n'
+const LINE_SEPARATOR = '\n'
+const CRLF = '\r\n'
+
+const comment_schema = z.looseObject({
+	id: z.number(),
+	user: z.looseObject({ login: z.string(), type: z.string().optional() }).nullish(),
+	created_at: z.string().optional(),
+	body: z.string().nullish(),
+})
+
+interface WatchComment {
+	id: number
+	author: string
+	is_automated: boolean
+	created_at: string
+	body: string
+}
+
+interface WatchSnapshot {
+	body: string
+	comments: ReadonlyArray<WatchComment>
+}
+
+interface WatchBaseline {
+	body: string
+	last_comment_id: number
+}
+
+function is_bot(user: z.infer<typeof comment_schema>['user']): boolean {
+	return user?.type === BOT_TYPE || (user?.login.endsWith(BOT_SUFFIX) ?? false)
+}
+
+function is_automated(user: z.infer<typeof comment_schema>['user'], body: string): boolean {
+	return is_bot(user) || body.includes(RUN_MARKER)
+}
+
+function to_comment(raw: z.infer<typeof comment_schema>): WatchComment {
+	const body = raw.body ?? ''
+	const author = raw.user?.login ?? UNKNOWN_AUTHOR
+	const created_at = raw.created_at ?? UNKNOWN_TIME
+
+	return { id: raw.id, author, is_automated: is_automated(raw.user, body), created_at, body }
+}
+
+// `undefined` — never `[]` — for a listing that could not be read, so a failed read is never taken
+// for "nobody commented".
+function parse_comments(json: string | undefined): ReadonlyArray<WatchComment> | undefined {
+	if (json === undefined) return undefined
+
+	const listing = read_json_listing(json, comment_schema)
+
+	return listing.kind === 'read' ? listing.rows.map((row) => to_comment(row)) : undefined
+}
+
+function last_comment_id(comments: ReadonlyArray<WatchComment>): number {
+	return Math.max(NO_COMMENT_ID, ...comments.map((comment) => comment.id))
+}
+
+function baseline_of(snapshot: WatchSnapshot): WatchBaseline {
+	return { body: snapshot.body, last_comment_id: last_comment_id(snapshot.comments) }
+}
+
+function lines_missing_from(source: string, other: string): Array<string> {
+	const present = new Set(other.split(LINE_SEPARATOR))
+
+	return source.split(LINE_SEPARATOR).filter((line) => line.trim() !== '' && !present.has(line))
+}
+
+// GitHub stores a body saved in its web editor with CRLF line endings, so one edited line to a body
+// josh wrote over the API with LF would otherwise read as every line removed and added.
+function to_lf(body: string): string {
+	return body.split(CRLF).join(LINE_SEPARATOR)
+}
+
+// The lines that left and the lines that arrived — not a positional diff, which would need a
+// dependency in a hook that runs on every tool call, and a reader comparing a spec only needs which
+// sentences changed.
+function body_section(previous_raw: string, current_raw: string): string | undefined {
+	const previous = to_lf(previous_raw)
+	const current = to_lf(current_raw)
+
+	if (previous === current) return undefined
+
+	const removed = lines_missing_from(previous, current).map((line) => `${REMOVED_PREFIX}${line}`)
+	const added = lines_missing_from(current, previous).map((line) => `${ADDED_PREFIX}${line}`)
+
+	return [BODY_HEADING, ...removed, ...added].join(LINE_SEPARATOR)
+}
+
+function comment_section(comment: WatchComment): string {
+	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${comment.body}`
+}
+
+function new_person_comments(
+	baseline: WatchBaseline,
+	snapshot: WatchSnapshot,
+): ReadonlyArray<WatchComment> {
+	return snapshot.comments.filter(
+		(comment) => comment.id > baseline.last_comment_id && !comment.is_automated,
+	)
+}
+
+// The unread update as the text a run is shown, or `undefined` when a person changed nothing.
+function unread_diff(baseline: WatchBaseline, snapshot: WatchSnapshot): string | undefined {
+	const body = body_section(baseline.body, snapshot.body)
+	const comments = new_person_comments(baseline, snapshot).map((comment) =>
+		comment_section(comment),
+	)
+	const sections = [...(body === undefined ? [] : [body]), ...comments]
+
+	return sections.length === 0 ? undefined : sections.join(SECTION_SEPARATOR)
+}
+
+const issue_watch_diff = {
+	RUN_MARKER,
+	baseline_of,
+	parse_comments,
+	unread_diff,
+}
+
+export type { WatchBaseline, WatchComment, WatchSnapshot }
+export { issue_watch_diff }

package/scripts/issue/issue-watch-gate.ts

@@ -0,0 +1,81 @@
+import { git_command } from '#scripts/git/git-command'
+import { session_cite } from '#scripts/issue/session-cite'
+import { review_attest } from '#scripts/review/review-attest'
+import { issue_watch, type WatchRecord } from './issue-watch'
+
+// The refusals a person's unread issue update raises, composed once so the hook, `josh review:attest
+// --check` and `josh followup` say the same thing about the same state.
+//
+// **The gates poll on every call** (`interval_ms: 0`): they run a handful of times per run, and the
+// poll is a conditional request that a 304 answers for free. Only the hook, which runs on every tool
+// call, spaces its polls out.
+
+const EVERY_CALL_MS = 0
+
+function ack_command(issue: string): string {
+	return `pnpm josh issue:ack ${issue}`
+}
+
+function unread_message(record: Pick<WatchRecord, 'issue' | 'pending'>): string {
+	return [
+		`A person updated issue ${session_cite.issue(record.issue)} after this run read it, and the run has not taken the update in:`,
+		record.pending ?? '',
+		`Read it, compare it with the acceptance criteria, fix what it changes, then run \`${ack_command(record.issue)}\` to record that it was read.`,
+	].join('\n\n')
+}
+
+function review_message(record: WatchRecord, briefed_at: string): string {
+	return [
+		`Issue ${session_cite.issue(record.issue)} was updated after the review was briefed (taken in at ${record.acknowledged_at}, briefed at ${briefed_at}), so the review read the earlier specification.`,
+		'Re-run `/code-review` with a fresh `pnpm josh review:brief`, so the review reads the change against the updated issue.',
+	].join('\n')
+}
+
+async function polled(root: string): Promise<WatchRecord | undefined> {
+	return await issue_watch.poll({ interval_ms: EVERY_CALL_MS }, root)
+}
+
+// The merge-time refusal: a person's update the run has not acknowledged. `undefined` when there is
+// none, when no run recorded a baseline in this checkout, or when the issue could not be read — an
+// unreachable GitHub does not hold a merge `josh followup` would otherwise make.
+async function unread_refusal(root: string): Promise<string | undefined> {
+	const record = await polled(root)
+
+	return record?.pending === undefined ? undefined : unread_message(record)
+}
+
+// The review-time refusal: an unread update, or one taken in after the review was briefed — the fix
+// it led to is then a change the review never saw.
+async function review_refusal(root: string): Promise<string | undefined> {
+	const record = await polled(root)
+
+	if (record === undefined) return undefined
+	if (record.pending !== undefined) return unread_message(record)
+
+	const pointer = review_attest.read_pointer(root)
+
+	if (pointer === undefined || record.acknowledged_at <= pointer.taken_at) return undefined
+
+	return review_message(record, pointer.taken_at)
+}
+
+async function review_refusal_here(): Promise<string | undefined> {
+	return await review_refusal(await git_command.repository_root())
+}
+
+// Throws the refusal, for the `josh followup` seams that stop by throwing.
+async function assert_read_here(): Promise<void> {
+	const refusal = await unread_refusal(await git_command.repository_root())
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+const issue_watch_gate = {
+	assert_read_here,
+	review_refusal,
+	review_refusal_here,
+	unread_message,
+	unread_refusal,
+}
+
+export { issue_watch_gate }

package/scripts/issue/issue-watch-hook.ts

@@ -0,0 +1,54 @@
+import { error_text } from '#scripts/lib/error-message'
+import { issue_watch, type WatchRecord } from './issue-watch'
+import { issue_watch_gate } from './issue-watch-gate'
+
+// The `PreToolUse` adapter that shows a run a person's update to its issue on the next tool call,
+// composed into `pretool-guard.ts` — the one PreToolUse hook — rather than added as a second
+// `.claude/settings.json` entry.
+//
+// **It polls at most once per interval.** Every tool call reads the checkout's record from disk; only
+// one whose last poll is older than `POLL_INTERVAL_MS` asks GitHub, with the ETag of the previous
+// answer, so an unchanged issue costs a 304. The request is bounded well under the hook's own timeout.
+//
+// **It refuses once per update.** The refusal is what puts the update in front of the run; repeating
+// it on every call would wedge the run before it could act. A further update changes the pending text
+// and is shown again. `josh issue:ack` clears it, and the review attestation and `josh followup` keep
+// refusing until it does — the hook is the early warning, not the enforcement.
+//
+// **It fails open.** No record, an unreadable issue or a thrown error allows the call: a hook that
+// stalls every tool call over a network blip would cost more than the update it watches for.
+
+const POLL_INTERVAL_MS = 180_000
+const POLL_TIMEOUT_MS = 5000
+
+function is_new_to_run(record: WatchRecord | undefined): record is WatchRecord {
+	return record?.pending !== undefined && record.pending !== record.shown
+}
+
+async function new_update_reason(now: Date): Promise<string | undefined> {
+	const record = await issue_watch.poll({
+		interval_ms: POLL_INTERVAL_MS,
+		timeout_ms: POLL_TIMEOUT_MS,
+		now,
+	})
+
+	if (!is_new_to_run(record)) return undefined
+
+	issue_watch.mark_shown(record)
+
+	return issue_watch_gate.unread_message(record)
+}
+
+async function watch_reason(now: Date = new Date()): Promise<string | undefined> {
+	try {
+		return await new_update_reason(now)
+	} catch (error) {
+		error_text.trace_swallowed('issue_watch_hook.watch_reason', error)
+
+		return undefined
+	}
+}
+
+const issue_watch_hook = { POLL_INTERVAL_MS, watch_reason }
+
+export { issue_watch_hook }