refactor: extract validateAgentFile to shared paths.mjs module

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

Author: leocavalcante

postinstall.mjs

@@ -12,16 +12,13 @@ import { join } from "node:path"
 
 import {
 	AGENTS_TARGET_DIR,
-	checkVersionCompatibility,
 	createLogger,
 	getAgentsSourceDir,
 	getErrorMessage,
 	getPackageRoot,
-	OPENCODE_VERSION,
 	parseCliFlags,
-	parseFrontmatter,
 	retryOnTransientError,
-	validateAgentContent,
+	validateAgentFile,
 } from "./src/paths.mjs"
 
 const packageRoot = getPackageRoot(import.meta.url)
@@ -54,59 +51,6 @@ Examples:
 const logger = createLogger(VERBOSE)
 const verbose = logger.verbose
 
-/**
- * Validates an agent file by reading and validating its content,
- * including version compatibility checking.
- *
- * Performs the following validations:
- * 1. Content structure validation (frontmatter, headers, keywords)
- * 2. Version compatibility checking against current OpenCode version
- *
- * @param {string} filePath - Path to the agent file to validate
- * @returns {{ valid: boolean, error?: string }} Validation result with optional error message
- * @throws {Error} If the file does not exist (ENOENT)
- * @throws {Error} If permission is denied reading the file (EACCES)
- * @throws {Error} If the file is a directory (EISDIR)
- *
- * @example
- * // Validate an agent file
- * const result = validateAgentFile('/path/to/agent.md')
- * if (!result.valid) {
- *   console.error(`Validation failed: ${result.error}`)
- * }
- *
- * @example
- * // Use in a file copy loop
- * for (const file of agentFiles) {
- *   const validation = validateAgentFile(join(sourceDir, file))
- *   if (validation.valid) {
- *     copyFileSync(join(sourceDir, file), join(targetDir, file))
- *   }
- * }
- */
-function validateAgentFile(filePath) {
-	const content = readFileSync(filePath, "utf-8")
-	const contentValidation = validateAgentContent(content)
-	if (!contentValidation.valid) {
-		return contentValidation
-	}
-
-	// Check version compatibility from frontmatter
-	const frontmatter = parseFrontmatter(content)
-	if (frontmatter.found && frontmatter.fields.requires) {
-		const requiresVersion = frontmatter.fields.requires
-		const isCompatible = checkVersionCompatibility(requiresVersion, OPENCODE_VERSION)
-		if (!isCompatible) {
-			return {
-				valid: false,
-				error: `Incompatible OpenCode version: requires ${requiresVersion}, but current version is ${OPENCODE_VERSION}`,
-			}
-		}
-	}
-
-	return { valid: true }
-}
-
 /**
  * Main entry point for the postinstall script.
  *

src/paths.d.mts

@@ -365,3 +365,51 @@ export interface Logger {
  * logger.verbose("Source: /path/to/src") // Does nothing (verbose disabled)
  */
 export function createLogger(verbose: boolean): Logger
+
+/**
+ * Result of validating an agent file.
+ */
+export interface ValidateAgentFileResult {
+	/** Whether the file is valid */
+	valid: boolean
+	/** Error message if validation failed */
+	error?: string
+}
+
+/**
+ * Validates an agent file by reading and validating its content,
+ * including version compatibility checking.
+ *
+ * Performs the following validations:
+ * 1. Content structure validation (frontmatter, headers, keywords)
+ * 2. Version compatibility checking against current OpenCode version
+ *
+ * @param filePath - Path to the agent file to validate
+ * @param currentVersion - The current OpenCode version to check against (defaults to OPENCODE_VERSION)
+ * @returns Validation result with valid status and optional error message
+ * @throws {Error} If the file does not exist (ENOENT)
+ * @throws {Error} If permission is denied reading the file (EACCES)
+ * @throws {Error} If the file is a directory (EISDIR)
+ * @throws {TypeError} If filePath is not a non-empty string
+ *
+ * @example
+ * // Validate an agent file
+ * const result = validateAgentFile('/path/to/agent.md')
+ * if (!result.valid) {
+ *   console.error(`Validation failed: ${result.error}`)
+ * }
+ *
+ * @example
+ * // Use in a file copy loop
+ * for (const file of agentFiles) {
+ *   const validation = validateAgentFile(join(sourceDir, file))
+ *   if (validation.valid) {
+ *     copyFileSync(join(sourceDir, file), join(targetDir, file))
+ *   }
+ * }
+ *
+ * @example
+ * // Validate against a specific version
+ * const result = validateAgentFile('/path/to/agent.md', '1.0.0')
+ */
+export function validateAgentFile(filePath: string, currentVersion?: string): ValidateAgentFileResult

src/paths.mjs

@@ -5,10 +5,14 @@
  * and preuninstall.mjs to locate agent files.
  */
 
+import { readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 
+// Import checkVersionCompatibility for internal use
+import { checkVersionCompatibility as _checkVersionCompatibility } from "./semver.mjs"
+
 // Re-export semver utilities for backwards compatibility
 export {
 	checkVersionCompatibility,
@@ -507,3 +511,71 @@ export function createLogger(verbose) {
 		},
 	}
 }
+
+/**
+ * Validates an agent file by reading and validating its content,
+ * including version compatibility checking.
+ *
+ * Performs the following validations:
+ * 1. Content structure validation (frontmatter, headers, keywords)
+ * 2. Version compatibility checking against current OpenCode version
+ *
+ * @param {string} filePath - Path to the agent file to validate
+ * @param {string} [currentVersion] - The current OpenCode version to check against (defaults to OPENCODE_VERSION)
+ * @returns {{ valid: boolean, error?: string }} Validation result with optional error message
+ * @throws {Error} If the file does not exist (ENOENT)
+ * @throws {Error} If permission is denied reading the file (EACCES)
+ * @throws {Error} If the file is a directory (EISDIR)
+ * @throws {TypeError} If filePath is not a non-empty string
+ *
+ * @example
+ * // Validate an agent file
+ * const result = validateAgentFile('/path/to/agent.md')
+ * if (!result.valid) {
+ *   console.error(`Validation failed: ${result.error}`)
+ * }
+ *
+ * @example
+ * // Use in a file copy loop
+ * for (const file of agentFiles) {
+ *   const validation = validateAgentFile(join(sourceDir, file))
+ *   if (validation.valid) {
+ *     copyFileSync(join(sourceDir, file), join(targetDir, file))
+ *   }
+ * }
+ *
+ * @example
+ * // Validate against a specific version
+ * const result = validateAgentFile('/path/to/agent.md', '1.0.0')
+ */
+export function validateAgentFile(filePath, currentVersion = OPENCODE_VERSION) {
+	if (typeof filePath !== "string") {
+		throw new TypeError(
+			`validateAgentFile: filePath must be a string, got ${filePath === null ? "null" : typeof filePath}`,
+		)
+	}
+	if (filePath.trim() === "") {
+		throw new TypeError("validateAgentFile: filePath must not be empty")
+	}
+
+	const content = readFileSync(filePath, "utf-8")
+	const contentValidation = validateAgentContent(content)
+	if (!contentValidation.valid) {
+		return contentValidation
+	}
+
+	// Check version compatibility from frontmatter
+	const frontmatter = parseFrontmatter(content)
+	if (frontmatter.found && frontmatter.fields.requires) {
+		const requiresVersion = frontmatter.fields.requires
+		const isCompatible = _checkVersionCompatibility(requiresVersion, currentVersion)
+		if (!isCompatible) {
+			return {
+				valid: false,
+				error: `Incompatible OpenCode version: requires ${requiresVersion}, but current version is ${currentVersion}`,
+			}
+		}
+	}
+
+	return { valid: true }
+}