@recombine-ai/bosun 0.16.2 → 0.17.1

package/src/backend/git-mode/repository-write-gate.ts

@@ -0,0 +1,260 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const GATE_VERSION = 1
+const DEFAULT_DRAIN_TIMEOUT_MS = 45_000
+const DRAIN_POLL_MS = 25
+
+interface GateRecord {
+	version: typeof GATE_VERSION
+	leaseId: string
+	launchId: string
+	pid: number
+	createdAt: string
+}
+
+export class RepositoryWritesPausedError extends Error {
+	constructor() {
+		super('Bosun is refreshing the repository. Wait for the refresh to finish before saving.')
+		this.name = 'RepositoryWritesPausedError'
+	}
+}
+
+/**
+ * Coordinates project-file writers in the backend and SvelteKit processes. A writer publishes a
+ * claim and then rechecks the lock. Git mode publishes the lock and then drains claims. Those two
+ * orderings guarantee that either the writer observes the lock or the locker observes the writer.
+ */
+export class RepositoryWriteGate {
+	private readonly lockPath: string
+	private readonly claimsDir: string
+	private lockedByThisProcess = false
+	private ownedLockRecord: GateRecord | null = null
+
+	constructor(
+		private readonly config: {
+			enabled: boolean
+			projectDir: string
+			leaseId: string
+			launchId: string
+		}
+	) {
+		const gitDirectory = path.join(config.projectDir, '.git')
+		this.lockPath = path.join(gitDirectory, 'bosun-write-gate.lock.json')
+		this.claimsDir = path.join(gitDirectory, 'bosun-write-claims')
+	}
+
+	/** Called once by a newly started managed backend, before it accepts browser traffic. */
+	async initializeBackend(): Promise<void> {
+		if (!this.config.enabled) return
+		await mkdir(this.claimsDir, { recursive: true })
+
+		if (await this.hasLock()) {
+			const existing = await this.readRecord(this.lockPath)
+			// A managed backend restart keeps the launcher lease but changes PID. A full restart gets
+			// a new lease. The launcher serializes both cases, so neither record (including a partial
+			// record left by sudden power loss) can still own Git.
+			if (!existing || existing.leaseId !== this.config.leaseId || existing.pid !== process.pid) {
+				await unlink(this.lockPath).catch((error: unknown) => {
+					if (!isNodeError(error, 'ENOENT')) throw error
+				})
+			}
+		}
+
+		await this.removeStaleClaims()
+	}
+
+	async lockAndDrain(timeoutMs = DEFAULT_DRAIN_TIMEOUT_MS): Promise<void> {
+		if (!this.config.enabled) return
+		await mkdir(this.claimsDir, { recursive: true })
+		if (!this.lockedByThisProcess) {
+			const record = this.record()
+			try {
+				await writeFile(this.lockPath, `${JSON.stringify(record)}\n`, {
+					encoding: 'utf8',
+					mode: 0o600,
+					flag: 'wx'
+				})
+				this.lockedByThisProcess = true
+				this.ownedLockRecord = record
+			} catch (error) {
+				if (!isNodeError(error, 'EEXIST')) throw error
+				const existing = await this.readRecord(this.lockPath)
+				if (
+					!existing ||
+					existing.leaseId !== this.config.leaseId ||
+					existing.launchId !== this.config.launchId ||
+					existing.pid !== process.pid
+				) {
+					throw new Error("Another process owns Bosun's repository write gate.")
+				}
+				this.lockedByThisProcess = true
+				this.ownedLockRecord = existing
+			}
+		}
+
+		const deadline = Date.now() + timeoutMs
+		while (true) {
+			await this.removeStaleClaims()
+			const claims = await readdir(this.claimsDir)
+			if (claims.length === 0) return
+			if (Date.now() >= deadline) {
+				throw new Error(
+					`Bosun timed out waiting for ${claims.length} project-file write${claims.length === 1 ? '' : 's'} to finish.`
+				)
+			}
+			await new Promise((resolve) => setTimeout(resolve, DRAIN_POLL_MS))
+		}
+	}
+
+	/** Reopens repository writes after an operation that completed without restarting the backend. */
+	async unlock(): Promise<void> {
+		if (!this.config.enabled || !this.lockedByThisProcess) return
+
+		const existing = await this.readRecord(this.lockPath)
+		if (!existing || !this.ownedLockRecord || !sameGateRecord(existing, this.ownedLockRecord)) {
+			throw new Error('Bosun cannot unlock a repository write gate it no longer owns.')
+		}
+
+		try {
+			await unlink(this.lockPath)
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) {
+				throw new Error('Bosun cannot unlock a repository write gate that is no longer present.', {
+					cause: error
+				})
+			}
+			throw error
+		}
+		this.lockedByThisProcess = false
+		this.ownedLockRecord = null
+	}
+
+	async withWriteAdmission<T>(operation: () => Promise<T>): Promise<T> {
+		if (!this.config.enabled) return operation()
+		await mkdir(this.claimsDir, { recursive: true })
+		if (await this.hasLock()) throw new RepositoryWritesPausedError()
+
+		const claimPath = path.join(this.claimsDir, `${process.pid}-${Date.now()}-${randomUUID()}.json`)
+		await writeFile(claimPath, `${JSON.stringify(this.record())}\n`, {
+			encoding: 'utf8',
+			mode: 0o600,
+			flag: 'wx'
+		})
+
+		try {
+			if (await this.hasLock()) throw new RepositoryWritesPausedError()
+			return await operation()
+		} finally {
+			await unlink(claimPath).catch((error: unknown) => {
+				if (!isNodeError(error, 'ENOENT')) throw error
+			})
+		}
+	}
+
+	private record(): GateRecord {
+		return {
+			version: GATE_VERSION,
+			leaseId: this.config.leaseId,
+			launchId: this.config.launchId,
+			pid: process.pid,
+			createdAt: new Date().toISOString()
+		}
+	}
+
+	private async hasLock(): Promise<boolean> {
+		try {
+			await readFile(this.lockPath)
+			return true
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) return false
+			throw error
+		}
+	}
+
+	private async removeStaleClaims(): Promise<void> {
+		for (const name of await readdir(this.claimsDir)) {
+			const claimPath = path.join(this.claimsDir, name)
+			const claim = await this.readRecord(claimPath)
+			if (
+				claim &&
+				claim.leaseId === this.config.leaseId &&
+				claim.launchId === this.config.launchId &&
+				isProcessAlive(claim.pid)
+			) {
+				continue
+			}
+			await unlink(claimPath).catch((error: unknown) => {
+				if (!isNodeError(error, 'ENOENT')) throw error
+			})
+		}
+	}
+
+	private async readRecord(filePath: string): Promise<GateRecord | null> {
+		try {
+			const value: unknown = JSON.parse(await readFile(filePath, 'utf8'))
+			if (!isGateRecord(value)) return null
+			return value
+		} catch (error) {
+			if (isNodeError(error, 'ENOENT')) return null
+			if (error instanceof SyntaxError) return null
+			throw error
+		}
+	}
+}
+
+export function createRepositoryWriteGateFromEnvironment(
+	env: NodeJS.ProcessEnv = process.env
+): RepositoryWriteGate {
+	const enabled = env.BOSUN_GIT_MODE === 'true'
+	return new RepositoryWriteGate({
+		enabled,
+		projectDir: enabled ? requireEnvironment(env, 'BOSUN_GIT_REPOSITORY_ROOT') : process.cwd(),
+		leaseId: enabled ? requireEnvironment(env, 'BOSUN_GIT_LEASE_ID') : '',
+		launchId: enabled ? requireEnvironment(env, 'BOSUN_GIT_LAUNCH_ID') : ''
+	})
+}
+
+function isGateRecord(value: unknown): value is GateRecord {
+	if (!value || typeof value !== 'object') return false
+	const record = value as Partial<GateRecord>
+	return (
+		record.version === GATE_VERSION &&
+		typeof record.leaseId === 'string' &&
+		typeof record.launchId === 'string' &&
+		typeof record.pid === 'number' &&
+		Number.isSafeInteger(record.pid) &&
+		record.pid > 0 &&
+		typeof record.createdAt === 'string'
+	)
+}
+
+function sameGateRecord(left: GateRecord, right: GateRecord): boolean {
+	return (
+		left.version === right.version &&
+		left.leaseId === right.leaseId &&
+		left.launchId === right.launchId &&
+		left.pid === right.pid &&
+		left.createdAt === right.createdAt
+	)
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch (error) {
+		return isNodeError(error, 'EPERM')
+	}
+}
+
+function requireEnvironment(env: NodeJS.ProcessEnv, name: string): string {
+	const value = env[name]?.trim()
+	if (!value) throw new Error(`${name} is required when BOSUN_GIT_MODE=true`)
+	return value
+}
+
+function isNodeError(error: unknown, code: string): error is NodeJS.ErrnoException {
+	return error instanceof Error && 'code' in error && error.code === code
+}

package/src/backend/git-mode/router.ts

@@ -0,0 +1,59 @@
+import type { TRPCRootObject } from '@trpc/server/unstable-core-do-not-import'
+import { z } from 'zod'
+
+import type { TrpcContext } from '../lib/trpc-context'
+import type { GitModeService } from './types'
+
+const TabId = z.string().trim().min(1).max(128)
+const OperationId = z.string().trim().min(1).max(128)
+const Choice = z
+	.object({
+		action: z.enum(['save', 'discard']),
+		description: z.string().max(500).optional()
+	})
+	.superRefine((choice, context) => {
+		if (choice.action !== 'save') return
+		if (!choice.description?.trim()) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['description'],
+				message: 'Describe your changes before saving.'
+			})
+		}
+	})
+
+export function createGitModeRouter(
+	t: TRPCRootObject<TrpcContext, any, any>,
+	service: GitModeService
+) {
+	return t.router({
+		status: t.procedure
+			.input(z.object({ tabId: TabId }))
+			.mutation(({ input }) => service.status(input)),
+		unregister: t.procedure
+			.input(z.object({ tabId: TabId }))
+			.mutation(({ input }) => service.unregister(input)),
+		activate: t.procedure
+			.input(z.object({ tabId: TabId, reason: z.enum(['page-open', 'focus']) }))
+			.mutation(({ input }) => service.activate(input)),
+		flushAck: t.procedure
+			.input(
+				z.object({
+					tabId: TabId,
+					operationId: OperationId,
+					stage: z.enum(['preflight', 'browser-writes']),
+					blockedReason: z.string().trim().min(1).max(1_000).optional()
+				})
+			)
+			.mutation(({ input }) => service.flushAck(input)),
+		startManual: t.procedure
+			.input(z.object({ tabId: TabId }).and(Choice))
+			.mutation(({ input }) => service.startManual(input)),
+		prepareRelease: t.procedure
+			.input(z.object({ tabId: TabId }))
+			.mutation(({ input }) => service.prepareRelease(input)),
+		resolveChanges: t.procedure
+			.input(z.object({ tabId: TabId, operationId: OperationId }).and(Choice))
+			.mutation(({ input }) => service.resolveChanges(input))
+	})
+}