@recombine-ai/bosun 0.16.2 → 0.17.1

package/src/lib/git-mode/client-admission.ts

@@ -0,0 +1,343 @@
+import { TRPCClientError, type TRPCLink } from '@trpc/client'
+import type { AnyTRPCRouter } from '@trpc/server'
+import { observable } from '@trpc/server/observable'
+
+import { GIT_MODE_USAGE_BLOCKED_MESSAGE } from './errors'
+
+export const GIT_FLUSH_OPERATION_CONTEXT_KEY = 'bosunGitFlushOperationId'
+
+export type RepositoryClientAdmissionMode = 'unknown' | 'open' | 'quiescing' | 'locked'
+
+export interface RepositoryClientAdmissionState {
+	mode: RepositoryClientAdmissionMode
+	flushOperationId: string | null
+}
+
+export interface GitFlushTransportOptions {
+	gitFlushOperationId: string
+}
+
+type StateListener = (state: RepositoryClientAdmissionState) => void
+type BlockedMutationListener = (path: string) => void
+type ServerBlockedListener = () => void
+
+interface StateWaiter {
+	predicate: (state: RepositoryClientAdmissionState) => boolean
+	resolve: () => void
+	reject: (error: Error) => void
+	onAbort: (() => void) | null
+}
+
+function abortReason(signal: AbortSignal): Error {
+	return signal.reason instanceof Error
+		? signal.reason
+		: new Error(signal.reason === undefined ? 'Request aborted.' : String(signal.reason))
+}
+
+const MUTATION_BLOCKED_MESSAGE =
+	'Bosun is refreshing the project. This change was not applied; wait for the refresh to finish.'
+
+export class GitModeMutationBlockedError extends Error {
+	readonly path: string
+
+	constructor(path: string) {
+		super(MUTATION_BLOCKED_MESSAGE)
+		this.name = 'GitModeMutationBlockedError'
+		this.path = path
+	}
+}
+
+function errorChainIncludes(error: unknown, predicate: (candidate: unknown) => boolean): boolean {
+	const seen = new Set<unknown>()
+	let candidate = error
+	while (candidate && !seen.has(candidate)) {
+		if (predicate(candidate)) return true
+		seen.add(candidate)
+		candidate =
+			typeof candidate === 'object' && candidate !== null && 'cause' in candidate
+				? (candidate as { cause?: unknown }).cause
+				: null
+	}
+	return false
+}
+
+function isFetchTransportError(error: unknown): boolean {
+	return errorChainIncludes(error, (candidate) => {
+		if (typeof candidate !== 'object' || candidate === null) return false
+		const namedError = candidate as { name?: unknown; message?: unknown }
+		if (namedError.name !== 'TypeError' || typeof namedError.message !== 'string') return false
+		return /^(failed to fetch|load failed|networkerror when attempting to fetch resource\.?)$/i.test(
+			namedError.message.trim()
+		)
+	})
+}
+
+export function isGitModeMutationBlockedError(error: unknown): boolean {
+	return errorChainIncludes(
+		error,
+		(candidate) =>
+			candidate instanceof GitModeMutationBlockedError ||
+			(typeof candidate === 'object' &&
+				candidate !== null &&
+				'name' in candidate &&
+				(candidate as { name?: unknown }).name === 'GitModeMutationBlockedError')
+	)
+}
+
+export function isGitModeUsageBlockedError(error: unknown): boolean {
+	return errorChainIncludes(
+		error,
+		(candidate) =>
+			typeof candidate === 'object' &&
+			candidate !== null &&
+			'message' in candidate &&
+			(candidate as { message?: unknown }).message === GIT_MODE_USAGE_BLOCKED_MESSAGE
+	)
+}
+
+export function gitFlushRequestOptions(operationId: string) {
+	return {
+		context: {
+			[GIT_FLUSH_OPERATION_CONTEXT_KEY]: operationId
+		}
+	}
+}
+
+export class RepositoryClientAdmission {
+	private state: RepositoryClientAdmissionState = {
+		mode: 'unknown',
+		flushOperationId: null
+	}
+	private readonly stateListeners = new Set<StateListener>()
+	private readonly blockedMutationListeners = new Set<BlockedMutationListener>()
+	private readonly serverBlockedListeners = new Set<ServerBlockedListener>()
+	private readonly waiters = new Set<StateWaiter>()
+	private tainted = false
+	private lastBlockedMutationPath: string | null = null
+
+	getState(): RepositoryClientAdmissionState {
+		return this.state
+	}
+
+	isTainted(): boolean {
+		return this.tainted
+	}
+
+	isOpen(): boolean {
+		return this.state.mode === 'open'
+	}
+
+	isFlushAuthorized(operationId: string | null | undefined): boolean {
+		return (
+			this.state.mode === 'quiescing' &&
+			Boolean(operationId) &&
+			operationId === this.state.flushOperationId
+		)
+	}
+
+	setState(next: RepositoryClientAdmissionState): void {
+		this.state = {
+			mode: next.mode,
+			flushOperationId: next.mode === 'quiescing' ? next.flushOperationId : null
+		}
+		for (const listener of this.stateListeners) listener(this.state)
+		this.resolveWaiters()
+	}
+
+	forceServerBlocked(): void {
+		this.setState({ mode: 'locked', flushOperationId: null })
+		for (const listener of this.serverBlockedListeners) listener()
+	}
+
+	blockMutation(path: string): GitModeMutationBlockedError {
+		this.tainted = true
+		this.lastBlockedMutationPath = path
+		for (const listener of this.blockedMutationListeners) listener(path)
+		return new GitModeMutationBlockedError(path)
+	}
+
+	onStateChange(listener: StateListener): () => void {
+		this.stateListeners.add(listener)
+		return () => this.stateListeners.delete(listener)
+	}
+
+	onBlockedMutation(listener: BlockedMutationListener): () => void {
+		this.blockedMutationListeners.add(listener)
+		if (this.tainted) listener(this.lastBlockedMutationPath ?? 'repository')
+		return () => this.blockedMutationListeners.delete(listener)
+	}
+
+	onServerBlocked(listener: ServerBlockedListener): () => void {
+		this.serverBlockedListeners.add(listener)
+		return () => this.serverBlockedListeners.delete(listener)
+	}
+
+	waitUntilOpen(signal?: AbortSignal | null): Promise<void> {
+		return this.waitFor((state) => state.mode === 'open', signal)
+	}
+
+	waitUntilKnown(signal?: AbortSignal | null): Promise<void> {
+		return this.waitFor((state) => state.mode !== 'unknown', signal)
+	}
+
+	dispose(): void {
+		const error = new Error('Repository client admission was disposed.')
+		for (const waiter of this.waiters) {
+			waiter.onAbort?.()
+			waiter.reject(error)
+		}
+		this.waiters.clear()
+		this.stateListeners.clear()
+		this.blockedMutationListeners.clear()
+		this.serverBlockedListeners.clear()
+	}
+
+	private waitFor(
+		predicate: (state: RepositoryClientAdmissionState) => boolean,
+		signal?: AbortSignal | null
+	): Promise<void> {
+		if (predicate(this.state)) return Promise.resolve()
+		if (signal?.aborted) return Promise.reject(abortReason(signal))
+
+		return new Promise((resolve, reject) => {
+			const waiter: StateWaiter = {
+				predicate,
+				resolve,
+				reject,
+				onAbort: null
+			}
+			if (signal) {
+				const onAbort = () => {
+					this.waiters.delete(waiter)
+					reject(abortReason(signal))
+				}
+				waiter.onAbort = () => signal.removeEventListener('abort', onAbort)
+				signal.addEventListener('abort', onAbort, { once: true })
+			}
+			this.waiters.add(waiter)
+		})
+	}
+
+	private resolveWaiters(): void {
+		for (const waiter of [...this.waiters]) {
+			if (!waiter.predicate(this.state)) continue
+			this.waiters.delete(waiter)
+			waiter.onAbort?.()
+			waiter.resolve()
+		}
+	}
+}
+
+function isGitControlPath(path: string): boolean {
+	return path === 'gitMode' || path.startsWith('gitMode.')
+}
+
+function flushOperationId(context: Record<string, unknown>): string | null {
+	const value = context[GIT_FLUSH_OPERATION_CONTEXT_KEY]
+	return typeof value === 'string' ? value : null
+}
+
+export function repositoryAdmissionLink<TRouter extends AnyTRPCRouter>(
+	admission: RepositoryClientAdmission
+): TRPCLink<TRouter> {
+	return () =>
+		({ op, next }) =>
+			observable((observer) => {
+				let cancelled = false
+				let downstream: { unsubscribe: () => void } | null = null
+				const waitAbort = new AbortController()
+				const abortWait = () => waitAbort.abort(op.signal?.reason)
+				if (op.signal?.aborted) abortWait()
+				else op.signal?.addEventListener('abort', abortWait, { once: true })
+
+				const reportError = (error: unknown) => {
+					if (cancelled) return
+					observer.error(
+						TRPCClientError.from(error instanceof Error ? error : new Error(String(error)))
+					)
+				}
+
+				const waitForOpenAndSubscribe = async () => {
+					while (!cancelled) {
+						await admission.waitUntilOpen(waitAbort.signal)
+						if (cancelled) return
+						// Resolving a waiter schedules this continuation in a microtask. Admission may
+						// have closed again before it runs, so only dispatch from a still-open state.
+						if (!admission.isOpen()) continue
+						subscribeDownstream()
+						return
+					}
+				}
+
+				const subscribeDownstream = () => {
+					if (cancelled) return
+					downstream = next(op).subscribe({
+						next: (value) => observer.next(value),
+						complete: () => observer.complete(),
+						error: (error) => {
+							if (cancelled) return
+							const serverBlocked = isGitModeUsageBlockedError(error)
+							if (op.type === 'mutation') {
+								if (serverBlocked && !admission.isFlushAuthorized(flushOperationId(op.context))) {
+									admission.forceServerBlocked()
+									reportError(admission.blockMutation(op.path))
+									return
+								}
+								reportError(error)
+								return
+							}
+
+							if (
+								op.type === 'query' &&
+								(serverBlocked || (!admission.isOpen() && isFetchTransportError(error)))
+							) {
+								if (serverBlocked) admission.forceServerBlocked()
+								downstream = null
+								void waitForOpenAndSubscribe().catch(reportError)
+								return
+							}
+
+							reportError(error)
+						}
+					})
+				}
+
+				const start = async () => {
+					if (isGitControlPath(op.path)) {
+						subscribeDownstream()
+						return
+					}
+
+					if (op.type === 'query' || op.type === 'subscription') {
+						await waitForOpenAndSubscribe()
+						return
+					}
+
+					if (admission.getState().mode === 'unknown')
+						await admission.waitUntilKnown(waitAbort.signal)
+					const state = admission.getState()
+					if (state.mode === 'open') {
+						subscribeDownstream()
+						return
+					}
+
+					const operationId = flushOperationId(op.context)
+					if (admission.isFlushAuthorized(operationId)) {
+						subscribeDownstream()
+						return
+					}
+
+					reportError(admission.blockMutation(op.path))
+				}
+
+				void start().catch(reportError)
+				return () => {
+					cancelled = true
+					op.signal?.removeEventListener('abort', abortWait)
+					waitAbort.abort()
+					downstream?.unsubscribe()
+				}
+			})
+}
+
+export const repositoryClientAdmission = new RepositoryClientAdmission()

package/src/lib/git-mode/errors.ts

@@ -0,0 +1,2 @@
+export const GIT_MODE_USAGE_BLOCKED_MESSAGE =
+	'Bosun is refreshing or blocked by Git mode. Use the open Git dialog to continue.'

package/src/lib/git-mode/git-mode-context.ts

@@ -0,0 +1,70 @@
+import { createContext } from 'svelte'
+
+export type GitModePhase =
+	| 'idle'
+	| 'preparing'
+	| 'flushing'
+	| 'refreshing'
+	| 'awaiting-changes'
+	| 'processing'
+	| 'restarting'
+	| 'fatal'
+
+export interface GitModeFatal {
+	title: string
+	message: string
+	prUrl?: string | null
+}
+
+export interface GitModeStatus {
+	enabled: boolean
+	phase: GitModePhase
+	operationId: string | null
+	tabNeedsFlush?: boolean
+	hasChanges: boolean
+	canPrepareRelease: boolean
+	fatal: GitModeFatal | null
+	reloadToken: string | null
+	deferredReason: string | null
+	preparationStage: GitModePreparationStage | null
+}
+
+export type GitModeManualAction = 'save' | 'discard' | 'prepare-release'
+export type GitModePreparationStage = 'preflight' | 'browser-writes'
+export interface GitModeFlushContext {
+	operationId: string
+}
+export type GitModeFlusher = (context: GitModeFlushContext) => void | Promise<void>
+export type GitModeBlocker = () => string | null
+
+export interface GitModeController {
+	state: GitModeStatus
+	openSaveDialog: () => void
+	openDiscardDialog: () => void
+	prepareRelease: () => void
+	manualAction: () => GitModeManualAction | null
+	registerFlusher: (
+		name: string,
+		flusher: GitModeFlusher,
+		options?: { final?: boolean }
+	) => () => void
+	registerBlocker: (name: string, blocker: GitModeBlocker) => () => void
+	isWritePaused: () => boolean
+	isActivationStarting: () => boolean
+	requestBlockedOperationNotice: () => void
+}
+
+export const [getGitModeContext, setGitModeContext] = createContext<GitModeController>()
+
+export const disabledGitModeStatus = (): GitModeStatus => ({
+	enabled: false,
+	phase: 'idle',
+	operationId: null,
+	tabNeedsFlush: false,
+	hasChanges: false,
+	canPrepareRelease: false,
+	fatal: null,
+	reloadToken: null,
+	deferredReason: null,
+	preparationStage: null
+})

package/src/lib/git-mode/refresh-policy.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import { disabledGitModeStatus, type GitModeStatus } from './git-mode-context'
+import {
+	gitClientAdmissionState,
+	gitStatusPausesWrites,
+	isBackgroundGitRefresh,
+	shouldPauseWritesForGitTabResume
+} from './refresh-policy'
+
+function status(overrides: Partial<GitModeStatus>): GitModeStatus {
+	return { ...disabledGitModeStatus(), enabled: true, ...overrides }
+}
+
+describe('isBackgroundGitRefresh', () => {
+	it('keeps preflight non-blocking until browser writes are being flushed', () => {
+		expect(
+			isBackgroundGitRefresh(status({ phase: 'preparing', preparationStage: 'preflight' }))
+		).toBe(false)
+		expect(
+			isBackgroundGitRefresh(status({ phase: 'preparing', preparationStage: 'browser-writes' }))
+		).toBe(true)
+	})
+
+	it.each(['flushing', 'refreshing', 'processing', 'restarting'] as const)(
+		'treats %s as a background refresh',
+		(phase) => {
+			expect(isBackgroundGitRefresh(status({ phase }))).toBe(true)
+		}
+	)
+
+	it('does not classify action-required states as background refreshes', () => {
+		expect(isBackgroundGitRefresh(status({ phase: 'awaiting-changes' }))).toBe(false)
+		expect(isBackgroundGitRefresh(status({ phase: 'fatal' }))).toBe(false)
+	})
+})
+
+describe('gitStatusPausesWrites', () => {
+	it('pauses writes for background and action-required states', () => {
+		expect(gitStatusPausesWrites(status({ phase: 'refreshing' }))).toBe(true)
+		expect(gitStatusPausesWrites(status({ phase: 'awaiting-changes' }))).toBe(true)
+		expect(gitStatusPausesWrites(status({ phase: 'fatal' }))).toBe(true)
+	})
+
+	it('leaves idle and preflight writes available', () => {
+		expect(gitStatusPausesWrites(status({ phase: 'idle' }))).toBe(false)
+		expect(
+			gitStatusPausesWrites(status({ phase: 'preparing', preparationStage: 'preflight' }))
+		).toBe(false)
+	})
+})
+
+describe('shouldPauseWritesForGitTabResume', () => {
+	it('does not pause an already-active tab for an ordinary window focus event', () => {
+		expect(shouldPauseWritesForGitTabResume(true)).toBe(false)
+	})
+
+	it('keeps a suspended tab paused until its resume status refresh succeeds', () => {
+		expect(shouldPauseWritesForGitTabResume(false)).toBe(true)
+	})
+})
+
+describe('gitClientAdmissionState', () => {
+	it('keeps ordinary requests pending until the first authoritative status', () => {
+		expect(gitClientAdmissionState(status({ phase: 'idle' }), false, true)).toEqual({
+			mode: 'unknown',
+			flushOperationId: null
+		})
+	})
+
+	it('opens after a disabled or enabled idle status', () => {
+		expect(gitClientAdmissionState(disabledGitModeStatus(), true, false).mode).toBe('open')
+		expect(gitClientAdmissionState(disabledGitModeStatus(), true, true).mode).toBe('open')
+		expect(gitClientAdmissionState(status({ phase: 'idle' }), true, false).mode).toBe('open')
+	})
+
+	it('quiesces browser writes with only the active operation authorized', () => {
+		expect(
+			gitClientAdmissionState(
+				status({
+					phase: 'preparing',
+					preparationStage: 'browser-writes',
+					operationId: 'operation-1'
+				}),
+				true,
+				true
+			)
+		).toEqual({ mode: 'quiescing', flushOperationId: 'operation-1' })
+	})
+
+	it('locks requests for backend phases and local suspension', () => {
+		expect(gitClientAdmissionState(status({ phase: 'refreshing' }), true, true).mode).toBe('locked')
+		expect(gitClientAdmissionState(status({ phase: 'idle' }), true, true).mode).toBe('locked')
+	})
+})

package/src/lib/git-mode/refresh-policy.ts

@@ -0,0 +1,39 @@
+import type { GitModeStatus } from './git-mode-context'
+import type { RepositoryClientAdmissionState } from './client-admission'
+
+export function isBackgroundGitRefresh(status: GitModeStatus): boolean {
+	if (!status.enabled) return false
+	if (status.phase === 'preparing') return status.preparationStage === 'browser-writes'
+	return ['flushing', 'refreshing', 'processing', 'restarting'].includes(status.phase)
+}
+
+export function gitStatusPausesWrites(status: GitModeStatus): boolean {
+	return (
+		isBackgroundGitRefresh(status) ||
+		(status.enabled && ['awaiting-changes', 'fatal'].includes(status.phase))
+	)
+}
+
+export function shouldPauseWritesForGitTabResume(tabWasActive: boolean): boolean {
+	return !tabWasActive
+}
+
+export function gitClientAdmissionState(
+	status: GitModeStatus,
+	statusSeen: boolean,
+	locallyPaused: boolean
+): RepositoryClientAdmissionState {
+	if (!statusSeen) return { mode: 'unknown', flushOperationId: null }
+	if (!status.enabled) return { mode: 'open', flushOperationId: null }
+	if (
+		status.phase === 'preparing' &&
+		status.preparationStage === 'browser-writes' &&
+		status.operationId
+	) {
+		return { mode: 'quiescing', flushOperationId: status.operationId }
+	}
+	if (locallyPaused || gitStatusPausesWrites(status)) {
+		return { mode: 'locked', flushOperationId: null }
+	}
+	return { mode: 'open', flushOperationId: null }
+}

package/src/lib/git-mode/status-recovery.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+
+import { recoverRequiredGitStatus } from './status-recovery'
+
+function deferred() {
+	let resolve!: () => void
+	const promise = new Promise<void>((next) => {
+		resolve = next
+	})
+	return { promise, resolve }
+}
+
+describe('recoverRequiredGitStatus', () => {
+	it('requests another status when invalidated during the recovery request', async () => {
+		let requiredSequence: number | null = 1
+		let successfulSequence = 0
+		let inFlight: Promise<void> | null = null
+		let requestCount = 0
+		const requests = [deferred(), deferred()]
+
+		const recovery = recoverRequiredGitStatus({
+			getRequiredSequence: () => requiredSequence,
+			getSuccessfulSequence: () => successfulSequence,
+			getInFlightRequest: () => inFlight,
+			requestStatus: () => {
+				const sequence = ++requestCount
+				const request = requests[sequence - 1]
+				inFlight = request.promise.then(() => {
+					successfulSequence = sequence
+					if (successfulSequence >= (requiredSequence ?? Infinity)) requiredSequence = null
+					inFlight = null
+				})
+				return inFlight
+			}
+		})
+
+		await Promise.resolve()
+		expect(requestCount).toBe(1)
+
+		requiredSequence = 2
+		requests[0].resolve()
+		await requests[0].promise
+		await Promise.resolve()
+		expect(requestCount).toBe(2)
+
+		requests[1].resolve()
+		await expect(recovery).resolves.toEqual({ status: 'satisfied' })
+		expect(successfulSequence).toBe(2)
+		expect(requiredSequence).toBeNull()
+	})
+
+	it('stops immediate recovery when a fresh request does not complete successfully', async () => {
+		let requestCount = 0
+
+		await expect(
+			recoverRequiredGitStatus({
+				getRequiredSequence: () => 1,
+				getSuccessfulSequence: () => 0,
+				getInFlightRequest: () => null,
+				requestStatus: async () => {
+					requestCount += 1
+				}
+			})
+		).resolves.toEqual({ status: 'request-failed', requiredSequence: 1 })
+		expect(requestCount).toBe(1)
+	})
+
+	it('reports which requirement failed when a newer invalidation arrives in flight', async () => {
+		let requiredSequence = 1
+		const request = deferred()
+		const recovery = recoverRequiredGitStatus({
+			getRequiredSequence: () => requiredSequence,
+			getSuccessfulSequence: () => 0,
+			getInFlightRequest: () => null,
+			requestStatus: () => request.promise
+		})
+
+		requiredSequence = 2
+		request.resolve()
+
+		await expect(recovery).resolves.toEqual({
+			status: 'request-failed',
+			requiredSequence: 1
+		})
+	})
+})

package/src/lib/git-mode/status-recovery.ts

@@ -0,0 +1,33 @@
+export interface GitStatusRecoverySource {
+	getRequiredSequence: () => number | null
+	getSuccessfulSequence: () => number
+	getInFlightRequest: () => Promise<void> | null
+	requestStatus: () => Promise<void>
+}
+
+export type GitStatusRecoveryResult =
+	| { status: 'satisfied' }
+	| { status: 'request-failed'; requiredSequence: number }
+
+export async function recoverRequiredGitStatus(
+	source: GitStatusRecoverySource
+): Promise<GitStatusRecoveryResult> {
+	while (true) {
+		const required = source.getRequiredSequence()
+		if (required === null || source.getSuccessfulSequence() >= required) {
+			return { status: 'satisfied' }
+		}
+
+		const inFlight = source.getInFlightRequest()
+		if (inFlight) {
+			await inFlight
+			continue
+		}
+
+		const successBeforeRequest = source.getSuccessfulSequence()
+		await source.requestStatus()
+		if (source.getSuccessfulSequence() === successBeforeRequest) {
+			return { status: 'request-failed', requiredSequence: required }
+		}
+	}
+}