feat: add retry logic for transient filesystem errors (EAGAIN/EBUSY)

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

postinstall.mjs

@@ -15,6 +15,7 @@ import {
 	getAgentsSourceDir,
 	getErrorMessage,
 	getPackageRoot,
+	retryOnTransientError,
 	validateAgentContent,
 } from "./src/paths.mjs"
 
@@ -58,7 +59,7 @@ function validateAgentFile(filePath) {
  * The function handles partial failures gracefully, installing as many
  * agents as possible and reporting individual failures.
  *
- * @returns {void}
+ * @returns {Promise<void>}
  *
  * @throws {never} Does not throw - uses process.exit() for error conditions
  *
@@ -67,7 +68,7 @@ function validateAgentFile(filePath) {
  * - 1: Complete failure - source directory missing, no agent files found,
  *      or all file copies failed
  */
-function main() {
+async function main() {
 	const prefix = DRY_RUN ? "[DRY-RUN] " : ""
 	console.log(`${prefix}opencode-plugin-opencoder: Installing agents...`)
 
@@ -131,7 +132,7 @@ function main() {
 				console.log(`${prefix}Would install: ${file} -> ${targetPath}`)
 			} else {
 				verbose(`  Copying file...`)
-				copyFileSync(sourcePath, targetPath)
+				await retryOnTransientError(() => copyFileSync(sourcePath, targetPath))
 
 				// Verify the copy succeeded by comparing file sizes
 				const sourceSize = statSync(sourcePath).size
@@ -195,4 +196,7 @@ function main() {
 	}
 }
 
-main()
+main().catch((err) => {
+	console.error("opencode-plugin-opencoder: Unexpected error:", err.message)
+	process.exit(1)
+})

preuninstall.mjs

@@ -15,6 +15,7 @@ import {
 	getAgentsSourceDir,
 	getErrorMessage,
 	getPackageRoot,
+	retryOnTransientError,
 } from "./src/paths.mjs"
 
 const packageRoot = getPackageRoot(import.meta.url)
@@ -46,15 +47,15 @@ function verbose(message) {
  * The function handles missing directories and files gracefully,
  * continuing to remove remaining agents even if some fail.
  *
- * @returns {void}
+ * @returns {Promise<void>}
  *
  * @throws {never} Does not throw - handles all errors internally
  *
  * Exit codes:
  * - 0: Always exits successfully, even if no agents were removed or
  *      some removals failed. This ensures npm uninstall completes.
  */
-function main() {
+async function main() {
 	const prefix = DRY_RUN ? "[DRY-RUN] " : ""
 	console.log(`${prefix}opencode-plugin-opencoder: Removing agents...`)
 
@@ -105,7 +106,7 @@ function main() {
 					console.log(`${prefix}Would remove: ${targetPath}`)
 					removedCount++
 				} else {
-					unlinkSync(targetPath)
+					await retryOnTransientError(() => unlinkSync(targetPath))
 					console.log(`  Removed: ${file}`)
 					removedCount++
 				}
@@ -129,4 +130,7 @@ function main() {
 	}
 }
 
-main()
+main().catch((err) => {
+	console.error("opencode-plugin-opencoder: Unexpected error:", err.message)
+	// Don't exit with error code - we want uninstall to succeed
+})

src/paths.d.mts

@@ -35,6 +35,35 @@ export function getErrorMessage(
 	targetPath: string,
 ): string
 
+/** Error codes that indicate transient errors that may succeed on retry */
+export declare const TRANSIENT_ERROR_CODES: string[]
+
+/**
+ * Checks if an error is a transient error that may succeed on retry.
+ */
+export function isTransientError(error: Error & { code?: string }): boolean
+
+/**
+ * Options for retryOnTransientError function.
+ */
+export interface RetryOptions {
+	/** Number of retry attempts (default: 3) */
+	retries?: number
+	/** Delay between retries in milliseconds (default: 100) */
+	delayMs?: number
+}
+
+/**
+ * Retries a function on transient filesystem errors.
+ *
+ * If the function throws a transient error (EAGAIN, EBUSY), it will be retried
+ * up to the specified number of times with a delay between attempts.
+ */
+export function retryOnTransientError<T>(
+	fn: () => T | Promise<T>,
+	options?: RetryOptions,
+): Promise<T>
+
 /**
  * Result of parsing YAML frontmatter from markdown content.
  */

src/paths.mjs

@@ -88,11 +88,86 @@ export function getErrorMessage(error, file, targetPath) {
 			return `Target already exists: ${targetPath}`
 		case "EISDIR":
 			return `Expected a file but found a directory: ${targetPath}`
+		case "EAGAIN":
+			return "Resource temporarily unavailable. Try again"
+		case "EBUSY":
+			return "File is busy or locked. Try again later"
 		default:
 			return error.message || "Unknown error"
 	}
 }
 
+/** Error codes that indicate transient errors that may succeed on retry */
+export const TRANSIENT_ERROR_CODES = ["EAGAIN", "EBUSY"]
+
+/**
+ * Checks if an error is a transient error that may succeed on retry.
+ *
+ * @param {Error & {code?: string}} error - The error to check
+ * @returns {boolean} True if the error is transient
+ */
+export function isTransientError(error) {
+	return TRANSIENT_ERROR_CODES.includes(error.code)
+}
+
+/**
+ * Delays execution for the specified number of milliseconds.
+ *
+ * @param {number} ms - Milliseconds to wait
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Retries a function on transient filesystem errors.
+ *
+ * If the function throws a transient error (EAGAIN, EBUSY), it will be retried
+ * up to the specified number of times with a delay between attempts.
+ *
+ * @template T
+ * @param {() => T | Promise<T>} fn - The function to execute
+ * @param {{ retries?: number, delayMs?: number }} [options] - Retry options
+ * @returns {Promise<T>} The result of the function
+ * @throws {Error} The last error if all retries fail
+ *
+ * @example
+ * // Retry a file copy operation
+ * await retryOnTransientError(() => copyFileSync(src, dest))
+ *
+ * @example
+ * // Custom retry options
+ * await retryOnTransientError(
+ *   () => unlinkSync(path),
+ *   { retries: 5, delayMs: 200 }
+ * )
+ */
+export async function retryOnTransientError(fn, options = {}) {
+	const { retries = 3, delayMs = 100 } = options
+	let lastError
+
+	for (let attempt = 0; attempt <= retries; attempt++) {
+		try {
+			return await fn()
+		} catch (err) {
+			lastError = err
+			const isTransient = isTransientError(err)
+
+			// If not a transient error or last attempt, throw immediately
+			if (!isTransient || attempt === retries) {
+				throw err
+			}
+
+			// Wait before retrying
+			await delay(delayMs)
+		}
+	}
+
+	// This should never be reached, but TypeScript needs it
+	throw lastError
+}
+
 /**
  * Parses YAML frontmatter from markdown content.
  *