@joshuafolkken/kit 1.887.0 → 1.921.0

package/scripts/josh/__snapshots__/josh-command-map.test.ts.snap

@@ -77,10 +77,12 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
     "obf": "observations:flush",
     "ol": "oracle:list",
     "ov": "overrides",
+    "pf": "profile",
     "pg": "propagate",
     "pks": "pkg:scout",
     "pm": "prevent-main-commit",
     "ppu": "pre-push-unit",
+    "prc": "pr:classification",
     "pt": "port",
     "ptc": "pre-commit-type-check",
     "ptg": "pretool:guard",
@@ -131,6 +133,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
     "sl": "session:lang",
     "sp": "stash:pop",
     "ss": "secretlint-scan",
+    "st": "start",
     "sy": "sync",
     "sys": "sync:scope",
     "t": "test",
@@ -445,7 +448,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "init": [
-      "",
+      "[--profile static|node]",
       "developer",
       [
         "files",
@@ -717,6 +720,13 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
         "network",
       ],
     ],
+    "pr:classification": [
+      "",
+      "automation",
+      [
+        "none",
+      ],
+    ],
     "pre-commit-type-check": [
       "",
       "automation",
@@ -745,6 +755,13 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
         "none",
       ],
     ],
+    "profile": [
+      "[--profile static|node]",
+      "developer",
+      [
+        "files",
+      ],
+    ],
     "propagate": [
       "[--dry-run] [--skip-publish-wait]",
       "maintainer",
@@ -1075,6 +1092,15 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
         "none",
       ],
     ],
+    "start": [
+      "[--profile static|node]",
+      "developer",
+      [
+        "files",
+        "git",
+        "network",
+      ],
+    ],
     "stash:pop": [
       "<message>",
       "automation",

package/scripts/josh/josh-command-map.ts

@@ -53,11 +53,14 @@ const ALIASES: Record<string, string> = {
 	c: 'check',
 	pt: 'port',
 	i: 'init',
+	pf: 'profile',
+	st: 'start',
 	sy: 'sync',
 	rmi: 'registry:migrate',
 	sys: 'sync:scope',
 	g: 'git',
 	gp: 'pr',
+	prc: 'pr:classification',
 	fu: 'followup',
 	nf: 'notify',
 	obf: 'observations:flush',

package/scripts/josh/josh-commands-development.ts

@@ -14,6 +14,12 @@ const PATH_ARGUMENTS = '<path...>'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const DEV_COMMANDS: Record<string, CommandEntry> = {
+	'pr:classification': {
+		script: 'scripts/ci/pr-classification.ts',
+		description: 'Require one release classification on a pull request',
+		category: 'Development',
+		reference: ['', 'automation', ['none']],
+	},
 	[GATE_COMMAND]: {
 		script: 'scripts/gate/verification-gate.ts',
 		description: 'Run lint, type check, spell check and unit tests concurrently',

package/scripts/josh/josh-commands-project.ts

@@ -4,12 +4,25 @@ import type { CommandEntry } from './josh-command-types'
 // no identifier format allows. The same disable sits at the top of `josh-commands-maintenance.ts`
 // for the same reason.
 /* eslint-disable @typescript-eslint/naming-convention */
+const PROFILE_ARGUMENTS = '[--profile static|node]'
 const PROJECT_COMMANDS: Record<string, CommandEntry> = {
+	profile: {
+		script: 'scripts/init/project-profile-cli.ts',
+		description: 'Show the project profile and the reason for it',
+		category: 'Project',
+		reference: [PROFILE_ARGUMENTS, 'developer', ['files']],
+	},
+	start: {
+		script: 'scripts/init/start.ts',
+		description: 'Initialize a project for the GitHub Issue workflow',
+		category: 'Project',
+		reference: [PROFILE_ARGUMENTS, 'developer', ['files', 'git', 'network']],
+	},
 	init: {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',
 		category: 'Project',
-		reference: ['', 'developer', ['files', 'processes']],
+		reference: [PROFILE_ARGUMENTS, 'developer', ['files', 'processes']],
 	},
 	sync: {
 		script: 'scripts/sync/sync.ts',

package/scripts/josh/josh-logic.ts

@@ -16,6 +16,7 @@ import {
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 import { josh_in_process } from './josh-in-process'
 import { kit_only } from './kit-only'
+import { run_github_prerequisite } from './run-github-prerequisite'
 
 const COLUMN_WIDTH = 26
 const ALIAS_PAD_WIDTH = 2
@@ -235,6 +236,15 @@ async function run_script_entry(
 	return spawn_script_entry(entry, script_path, script_arguments)
 }
 
+function github_prerequisite_exit(resolved: string, is_consumer: boolean): number | undefined {
+	if (!is_consumer) return undefined
+	const prerequisite = run_github_prerequisite.explanation(process.cwd(), resolved)
+	if (prerequisite === undefined) return undefined
+	console.error(prerequisite)
+
+	return USAGE_ERROR_EXIT_CODE
+}
+
 // The exit a command answers with before it runs, or `undefined` to go ahead: a consumer is refused a
 // kit-only command with guidance, and a composite command rejects extra arguments
 // (joshuafolkken/kit#1988).
@@ -250,6 +260,9 @@ function pre_dispatch_exit(
 		return USAGE_ERROR_EXIT_CODE
 	}
 
+	const prerequisite_exit = github_prerequisite_exit(resolved, is_consumer)
+	if (prerequisite_exit !== undefined) return prerequisite_exit
+
 	const rejection = composite_arguments.reject_extra_arguments(
 		resolved,
 		entry,

package/scripts/josh/run-github-prerequisite.ts

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { repo_origin } from '#scripts/discovery/repo-origin'
+import { execaSync } from 'execa'
+
+const GITHUB_RUN_COMMANDS = new Set([
+	'run:entry',
+	'run:prep',
+	'run:next',
+	'run:step',
+	'run:merge',
+	'run:tail',
+])
+
+function explanation(root: string, command: string): string | undefined {
+	if (!GITHUB_RUN_COMMANDS.has(command)) return undefined
+
+	if (!existsSync(path.join(root, '.git'))) {
+		return `${command} requires Git and a GitHub origin. Run git init and add a GitHub origin first.`
+	}
+
+	const result = execaSync('git', ['config', '--get', 'remote.origin.url'], {
+		cwd: root,
+		reject: false,
+	})
+	if (result.exitCode === 0 && repo_origin.parse_origin_url(result.stdout)) return undefined
+
+	return `${command} requires a GitHub origin. Add an origin pointing to GitHub first.`
+}
+
+const run_github_prerequisite = { explanation }
+export { run_github_prerequisite }

package/scripts/lane/lane-await.ts

@@ -1,5 +1,7 @@
 import { spawnSync } from 'node:child_process'
 import { setTimeout as sleep } from 'node:timers/promises'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_ship_detach } from '#scripts/run/run-ship-detach'
 import { lane_child_invocation } from './lane-child-invocation'
 
 // Detached lane children are not harness-tracked processes, so their completion fires no
@@ -49,7 +51,12 @@ function is_process_running_default(issue: string): boolean {
 	const pattern = lane_child_invocation.process_pattern(issue)
 	const result = spawnSync('pgrep', ['-f', pattern], { encoding: 'utf8' })
 
-	return result.status === PROCESS_FOUND
+	if (result.status === PROCESS_FOUND) return true
+	const repository = git_common_directory.repository(process.cwd())
+
+	return (
+		repository !== undefined && run_ship_detach.read_result(repository, issue)?.result === 'running'
+	)
 }
 
 function make_initial_state(): AwaitState {

package/scripts/lane/openai-lane-ship.ts

@@ -0,0 +1,30 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { run_ship_probe } from '#scripts/run/run-ship-probe'
+
+const POLL_MS = 250
+type ShipEnding = 'none' | 'success' | 'failed' | 'abnormal'
+type ShipReading = NonNullable<ReturnType<typeof run_ship_detach.read_result>>
+
+async function current(issue: string): Promise<ShipReading | undefined> {
+	const repository = await run_ship_probe.repository_directory()
+
+	return repository === undefined ? undefined : run_ship_detach.read_result(repository, issue)
+}
+
+async function wait_for_ship(issue: string, prior_launch: string | undefined): Promise<ShipEnding> {
+	let read = await current(issue)
+	if (read === undefined || read.launch_id === prior_launch) return 'none'
+
+	while (read.result === 'running') {
+		await sleep(POLL_MS)
+		read = await current(issue)
+		if (read === undefined) return 'abnormal'
+	}
+
+	return read.result
+}
+
+const openai_lane_ship = { current, wait_for_ship }
+
+export { openai_lane_ship }

package/scripts/lane/openai-lane-supervisor.ts

@@ -12,7 +12,9 @@ import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
+import { openai_lane_ship } from './openai-lane-ship'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
+import { openai_review_broker } from './openai-review-broker'
 
 const OWNER_PREFIX = 'josh-openai-lane-supervisor-'
 const STATE_PREFIX = 'josh-openai-lane-supervisor-state-'
@@ -187,10 +189,17 @@ async function standing_cut(issue: string): Promise<RunCut | undefined> {
 	return read_cut.kind === 'carried' && handed_off(read_cut.cut, issue) ? read_cut.cut : undefined
 }
 
-function child_argv(lane: LaneInfo, profile: AgentProfile, is_resume: boolean): LaunchArgv {
-	const invocation = is_resume
-		? lane_child_invocation.resume_invocation(lane.issue)
-		: lane_child_invocation.child_invocation(lane.issue)
+function child_argv(
+	lane: LaneInfo,
+	profile: AgentProfile,
+	is_resume: boolean,
+	override?: string,
+): LaunchArgv {
+	const invocation =
+		override ??
+		(is_resume
+			? lane_child_invocation.resume_invocation(lane.issue)
+			: lane_child_invocation.child_invocation(lane.issue))
 	const built = agent_argv.with_profile_in(invocation, profile, lane.directory)
 	if (built.kind === 'rejected') throw new Error(built.note)
 
@@ -209,6 +218,11 @@ interface Generation {
 	lane: LaneInfo
 	owner: SupervisorOwner
 	profile: AgentProfile
+	invocation?: string
+}
+
+function completion_code(result: ChildResult, ship: string): number {
+	return ship === 'abnormal' || result.kind === 'abnormal' ? 1 : 0
 }
 
 function record_child(generation: Generation, child_pid: number): void {
@@ -239,7 +253,7 @@ async function run_child(generation: Generation): Promise<ChildResult> {
 	const { lane, profile, is_resume } = generation
 	const result = await detached_launch.launch_attached(
 		{
-			argv: child_argv(lane, profile, is_resume),
+			argv: child_argv(lane, profile, is_resume, generation.invocation),
 			cwd: lane.directory,
 			log_path: lane_dispatch_log.default_log_path(lane),
 			profile,
@@ -257,6 +271,7 @@ async function run_child(generation: Generation): Promise<ChildResult> {
 }
 
 async function run_generations(generation: Generation): Promise<number> {
+	const prior = await openai_lane_ship.current(generation.lane.issue)
 	const result = await run_child(generation)
 	if (result.kind === LAUNCH_FAILED_KIND) return 1
 
@@ -264,9 +279,18 @@ async function run_generations(generation: Generation): Promise<number> {
 		return await run_generations({ ...generation, epoch: generation.epoch + 1, is_resume: true })
 	}
 
-	if (result.kind === 'abnormal') return 1
+	const ship = await openai_lane_ship.wait_for_ship(generation.lane.issue, prior?.launch_id)
+
+	if (ship === 'failed') {
+		return await run_generations({
+			...generation,
+			epoch: generation.epoch + 1,
+			is_resume: false,
+			invocation: lane_child_invocation.ship_stop_invocation(generation.lane.issue),
+		})
+	}
 
-	return 0
+	return completion_code(result, ship)
 }
 
 async function wait_for_inherited_child(
@@ -308,7 +332,10 @@ async function supervise(lane: LaneInfo, profile: AgentProfile, nonce: string):
 	try {
 		if (!(await openai_lane_supervisor_decision.is_approved(lane.directory, nonce))) return 0
 
-		return await run_claimed(lane, profile, owner)
+		return await openai_review_broker.with_server(
+			lane,
+			async () => await run_claimed(lane, profile, owner),
+		)
 	} finally {
 		release(lane.directory, nonce)
 	}

package/scripts/lane/openai-review-broker.ts

@@ -0,0 +1,260 @@
+import { randomUUID } from 'node:crypto'
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch } from '#scripts/run/detached-launch'
+import { run_ship_review } from '#scripts/run/run-ship-review'
+import { z } from 'zod'
+import type { LaneInfo } from './lane-registry'
+
+const REQUEST_PREFIX = '.josh-review-request-'
+const RESPONSE_PREFIX = '.josh-review-response-'
+const BRIEF_PREFIX = 'josh-ship-review-brief-'
+const FINDINGS_PREFIX = 'josh-ship-review-findings-'
+const LOG_PREFIX = 'josh-ship-review-log-'
+const CACHE_DIRECTORY = ['node_modules', '.cache']
+const POLL_MS = 100
+const HEARTBEAT_MS = 500
+const HEARTBEAT_LIMIT_MS = 3000
+const MINUTE_MS = 60_000
+const REQUEST_LIMIT_MINUTES = 30
+const REQUEST_LIMIT_MS = REQUEST_LIMIT_MINUTES * MINUTE_MS
+const request_schema = z
+	.object({ session: z.uuid(), nonce: z.uuid(), round: z.enum(['1', '2']) })
+	.strict()
+const response_schema = z
+	.object({
+		session: z.uuid(),
+		nonce: z.string(),
+		is_success: z.boolean(),
+		heartbeat_at: z.number().int().positive(),
+	})
+	.strict()
+type ReviewRequest = z.infer<typeof request_schema>
+type ReviewResponse = z.infer<typeof response_schema>
+type ReviewRound = ReviewRequest['round']
+
+function review_paths(directory: string): { brief: string; findings: string; log: string } {
+	return {
+		brief: stamp_file.stamp_path(BRIEF_PREFIX, directory, '.md'),
+		findings: stamp_file.stamp_path(FINDINGS_PREFIX, directory, '.txt'),
+		log: stamp_file.stamp_path(LOG_PREFIX, directory, '.log'),
+	}
+}
+
+function request_path(directory: string, issue: string): string {
+	return path.join(directory, ...CACHE_DIRECTORY, `${REQUEST_PREFIX}${issue}.json`)
+}
+
+function response_path(directory: string, issue: string): string | undefined {
+	const common = git_common_directory.resolve(directory)
+	if (common === undefined || path.basename(common) !== '.git') return undefined
+
+	return path.join(path.dirname(common), ...CACHE_DIRECTORY, `${RESPONSE_PREFIX}${issue}.json`)
+}
+
+function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
+	try {
+		const content: unknown = JSON.parse(readFileSync(target, 'utf8'))
+		const parsed = schema.safeParse(content)
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return undefined
+	}
+}
+
+async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
+	const target = review_paths(lane.directory)
+	const prompt_of =
+		round === '1' ? run_ship_review.reviewer_prompt : run_ship_review.verification_prompt
+	const built = agent_argv.resolve_in(
+		prompt_of(target.brief, target.findings),
+		agent_role_profile.REVIEWER,
+		lane.directory,
+	)
+	if (built.kind === 'rejected' || built.profile.provider !== 'openai') return false
+
+	const result = await detached_launch.launch_attached(
+		{
+			argv: built.argv,
+			cwd: lane.directory,
+			log_path: target.log,
+			profile: built.profile,
+		},
+		console.error,
+	)
+
+	return result.kind === 'completed' && result.exit_code === 0
+}
+
+function write_response(target: string, body: z.infer<typeof response_schema>): void {
+	const temporary = `${target}.${String(process.pid)}.tmp`
+
+	writeFileSync(temporary, JSON.stringify(body))
+	renameSync(temporary, target)
+}
+
+async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
+	try {
+		return await launch_review(lane, round)
+	} catch {
+		return false
+	}
+}
+
+async function process_request(
+	lane: LaneInfo,
+	response: string,
+	received: ReviewRequest,
+	state: { current: ReviewResponse },
+): Promise<void> {
+	const is_success = await launched(lane, received.round)
+
+	state.current = {
+		session: received.session,
+		nonce: received.nonce,
+		is_success,
+		heartbeat_at: Date.now(),
+	}
+	write_response(response, state.current)
+}
+
+async function serve(
+	lane: LaneInfo,
+	session: string,
+	response: string,
+	state: { is_running: boolean; current: ReviewResponse },
+): Promise<void> {
+	let last_nonce = ''
+	const target = request_path(lane.directory, lane.issue)
+
+	while (state.is_running) {
+		const received = read_record(target, request_schema)
+
+		if (received?.session === session && received.nonce !== last_nonce) {
+			last_nonce = received.nonce
+			await process_request(lane, response, received, state)
+		}
+
+		await sleep(POLL_MS)
+	}
+}
+
+function prepare(lane: LaneInfo): { response: string; current: ReviewResponse } {
+	const response = response_path(lane.directory, lane.issue)
+	if (response === undefined) throw new Error('review broker has no trusted response location')
+
+	const session = randomUUID()
+
+	mkdirSync(path.dirname(response), { recursive: true })
+	mkdirSync(path.dirname(request_path(lane.directory, lane.issue)), { recursive: true })
+	const current: ReviewResponse = {
+		session,
+		nonce: '',
+		is_success: false,
+		heartbeat_at: Date.now(),
+	}
+
+	write_response(response, current)
+
+	return { response, current }
+}
+
+function start_heartbeat(state: { current: ReviewResponse }, response: string): NodeJS.Timeout {
+	const heartbeat = setInterval(() => {
+		state.current = { ...state.current, heartbeat_at: Date.now() }
+		write_response(response, state.current)
+	}, HEARTBEAT_MS)
+
+	heartbeat.unref()
+
+	return heartbeat
+}
+
+async function stop_server(
+	state: { is_running: boolean },
+	heartbeat: NodeJS.Timeout,
+	serving: Promise<void>,
+	response: string,
+): Promise<void> {
+	clearInterval(heartbeat)
+	state.is_running = false
+	await serving
+	unlinkSync(response)
+}
+
+async function with_server<T>(lane: LaneInfo, run: () => Promise<T>): Promise<T> {
+	const { response, current } = prepare(lane)
+	const state = { is_running: true, current }
+	const heartbeat = start_heartbeat(state, response)
+	const serving = serve(lane, current.session, response, state)
+
+	try {
+		return await run()
+	} finally {
+		await stop_server(state, heartbeat, serving, response)
+	}
+}
+
+function is_live_response(
+	response: ReviewResponse | undefined,
+	session: string,
+): response is ReviewResponse {
+	const now = Date.now()
+
+	return (
+		response?.session === session &&
+		response.heartbeat_at <= now &&
+		response.heartbeat_at >= now - HEARTBEAT_LIMIT_MS
+	)
+}
+
+function response_verdict(
+	response: ReviewResponse | undefined,
+	session: string,
+	nonce: string,
+): 'wait' | 'success' | 'failure' {
+	if (!is_live_response(response, session)) return 'failure'
+	if (response.nonce !== nonce) return 'wait'
+
+	return response.is_success ? 'success' : 'failure'
+}
+
+async function wait_response(target: string, session: string, nonce: string): Promise<boolean> {
+	const deadline = Date.now() + REQUEST_LIMIT_MS
+
+	while (Date.now() < deadline) {
+		const verdict = response_verdict(read_record(target, response_schema), session, nonce)
+		if (verdict !== 'wait') return verdict === 'success'
+
+		await sleep(POLL_MS)
+	}
+
+	return false
+}
+
+async function request(directory: string, issue: string, round: ReviewRound): Promise<boolean> {
+	const target = response_path(directory, issue)
+	if (target === undefined) return false
+	const response = read_record(target, response_schema)
+
+	if (response === undefined || !is_live_response(response, response.session)) {
+		return false
+	}
+
+	const nonce = randomUUID()
+	const body: ReviewRequest = { session: response.session, nonce, round }
+
+	stamp_file.replace_stamp(request_path(directory, issue), body)
+
+	return await wait_response(target, response.session, nonce)
+}
+
+const openai_review_broker = { request, request_path, response_path, review_paths, with_server }
+
+export { openai_review_broker }

package/scripts/lint/cspell-cached.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { project_checks } from '#scripts/gate/project-checks'
 import { CSPELL_CACHE_FILE, CSPELL_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
 import { lane_cache_run } from '#scripts/lane/lane-cache-run'
 import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
@@ -22,7 +23,27 @@ const CSPELL_ARGS = [
 
 // The wrapper puts cache transfer directly around cspell rather than around the whole gate (#2060),
 // so a later failing check cannot prevent a completed cache from reaching the primary checkout.
+function static_skip_reason(directory: string): string | undefined {
+	if (!project_checks.is_static(directory)) return undefined
+
+	if (!project_checks.has_config(directory, project_checks.CSPELL_CONFIGS)) {
+		return 'no cspell configuration was found'
+	}
+
+	if (!project_checks.has_bin(directory, 'cspell')) return 'cspell is not installed'
+
+	return undefined
+}
+
 async function run(extra_arguments: ReadonlyArray<string> = []): Promise<number> {
+	const reason = static_skip_reason(process.cwd())
+
+	if (reason !== undefined) {
+		console.info(project_checks.skip_notice('cspell', reason))
+
+		return 0
+	}
+
 	const result = await lane_cache_run.run(
 		CSPELL_CACHE_FILE,
 		async () => await buffered_process.run_buffered_process([...CSPELL_ARGS, ...extra_arguments]),