feat(install): implement --force flag to bypass version compatibility checks

leocavalcante · leocavalcante · commit 677274f4c282 · 2026-01-19T10:28:49.000-03:00
Signed-off-by: leocavalcante &lt;leo@cavalcante.dev&gt;
diff --git a/postinstall.mjs b/postinstall.mjs
@@ -29,6 +29,7 @@ const flags = parseCliFlags(process.argv)
 const DRY_RUN = flags.dryRun
 const VERBOSE = flags.verbose
 const QUIET = flags.quiet
+const FORCE = flags.force
 
 /** Print usage information and exit */
 if (flags.help) {
@@ -92,6 +93,12 @@ async function main() {
 	verbose(`Source directory: ${AGENTS_SOURCE_DIR}`)
 	verbose(`Target directory: ${AGENTS_TARGET_DIR}`)
 	verbose(`Dry run: ${DRY_RUN}`)
+	verbose(`Force: ${FORCE}`)
+
+	// Warn about force mode
+	if (FORCE) {
+		verbose(`Force mode enabled: version compatibility checks will be skipped`)
+	}
 
 	// Create target directory if it doesn't exist
 	if (!existsSync(AGENTS_TARGET_DIR)) {
@@ -150,10 +157,13 @@ async function main() {
 			if (DRY_RUN) {
 				// In dry-run mode, validate source file but don't copy
 				verbose(`  Validating source file (dry-run mode)...`)
-				const validation = validateAgentFile(sourcePath)
+				const validation = validateAgentFile(sourcePath, undefined, FORCE)
 				if (!validation.valid) {
 					throw new Error(`Invalid agent file content: ${validation.error}`)
 				}
+				if (validation.skippedVersionCheck) {
+					verbose(`  Warning: Version compatibility check skipped (--force)`)
+				}
 				verbose(`  Validation passed`)
 				successes.push(file)
 				log(`${prefix}Would install: ${file} -> ${targetPath}`)
@@ -176,10 +186,13 @@ async function main() {
 
 				// Validate content structure
 				verbose(`  Validating content structure...`)
-				const validation = validateAgentFile(targetPath)
+				const validation = validateAgentFile(targetPath, undefined, FORCE)
 				if (!validation.valid) {
 					throw new Error(`Invalid agent file content: ${validation.error}`)
 				}
+				if (validation.skippedVersionCheck) {
+					verbose(`  Warning: Version compatibility check skipped (--force)`)
+				}
 				verbose(`  Validation passed`)
 
 				successes.push(file)
diff --git a/preuninstall.mjs b/preuninstall.mjs
@@ -28,6 +28,7 @@ const flags = parseCliFlags(process.argv)
 const DRY_RUN = flags.dryRun
 const VERBOSE = flags.verbose
 const QUIET = flags.quiet
+const FORCE = flags.force
 
 /** Print usage information and exit */
 if (flags.help) {
@@ -90,6 +91,12 @@ async function main() {
 	verbose(`Source directory: ${AGENTS_SOURCE_DIR}`)
 	verbose(`Target directory: ${AGENTS_TARGET_DIR}`)
 	verbose(`Dry run: ${DRY_RUN}`)
+	verbose(`Force: ${FORCE}`)
+
+	// Note about force mode for uninstall
+	if (FORCE) {
+		verbose(`Force mode enabled: removal will proceed without additional checks`)
+	}
 
 	// Check if target directory exists
 	verbose(`Checking if target directory exists...`)
diff --git a/src/paths.d.mts b/src/paths.d.mts
@@ -397,6 +397,8 @@ export interface ValidateAgentFileResult {
 	valid: boolean
 	/** Error message if validation failed */
 	error?: string
+	/** Whether version compatibility check was skipped (when force=true and version is incompatible) */
+	skippedVersionCheck?: boolean
 }
 
 /**
@@ -405,10 +407,11 @@ export interface ValidateAgentFileResult {
  *
  * Performs the following validations:
  * 1. Content structure validation (frontmatter, headers, keywords)
- * 2. Version compatibility checking against current OpenCode version
+ * 2. Version compatibility checking against current OpenCode version (unless force=true)
  *
  * @param filePath - Path to the agent file to validate
  * @param currentVersion - The current OpenCode version to check against (defaults to OPENCODE_VERSION)
+ * @param force - When true, skip version compatibility checks (default: false)
  * @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)
@@ -434,5 +437,12 @@ export interface ValidateAgentFileResult {
  * @example
  * // Validate against a specific version
  * const result = validateAgentFile('/path/to/agent.md', '1.0.0')
+ *
+ * @example
+ * // Force install, skipping version compatibility check
+ * const result = validateAgentFile('/path/to/agent.md', '1.0.0', true)
+ * if (result.skippedVersionCheck) {
+ *   console.warn('Warning: Version compatibility check was skipped')
+ * }
  */
-export function validateAgentFile(filePath: string, currentVersion?: string): ValidateAgentFileResult
+export function validateAgentFile(filePath: string, currentVersion?: string, force?: boolean): ValidateAgentFileResult
diff --git a/src/paths.mjs b/src/paths.mjs
@@ -557,11 +557,12 @@ export function createLogger(verbose, quiet = false) {
  *
  * Performs the following validations:
  * 1. Content structure validation (frontmatter, headers, keywords)
- * 2. Version compatibility checking against current OpenCode version
+ * 2. Version compatibility checking against current OpenCode version (unless force=true)
  *
  * @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
+ * @param {boolean} [force=false] - When true, skip version compatibility checks
+ * @returns {{ valid: boolean, error?: string, skippedVersionCheck?: boolean }} 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)
@@ -586,8 +587,15 @@ export function createLogger(verbose, quiet = false) {
  * @example
  * // Validate against a specific version
  * const result = validateAgentFile('/path/to/agent.md', '1.0.0')
+ *
+ * @example
+ * // Force install, skipping version compatibility check
+ * const result = validateAgentFile('/path/to/agent.md', '1.0.0', true)
+ * if (result.skippedVersionCheck) {
+ *   console.warn('Warning: Version compatibility check was skipped')
+ * }
  */
-export function validateAgentFile(filePath, currentVersion = OPENCODE_VERSION) {
+export function validateAgentFile(filePath, currentVersion = OPENCODE_VERSION, force = false) {
 	if (typeof filePath !== "string") {
 		throw new TypeError(
 			`validateAgentFile: filePath must be a string, got ${filePath === null ? "null" : typeof filePath}`,
@@ -603,12 +611,16 @@ export function validateAgentFile(filePath, currentVersion = OPENCODE_VERSION) {
 		return contentValidation
 	}
 
-	// Check version compatibility from frontmatter
+	// Check version compatibility from frontmatter (unless force is true)
 	const frontmatter = parseFrontmatter(content)
 	if (frontmatter.found && frontmatter.fields.requires) {
 		const requiresVersion = frontmatter.fields.requires
 		const isCompatible = _checkVersionCompatibility(requiresVersion, currentVersion)
 		if (!isCompatible) {
+			if (force) {
+				// Skip version check when force is enabled, but indicate it was skipped
+				return { valid: true, skippedVersionCheck: true }
+			}
 			return {
 				valid: false,
 				error: `Incompatible OpenCode version: requires ${requiresVersion}, but current version is ${currentVersion}`,
diff --git a/tests/paths.test.ts b/tests/paths.test.ts
@@ -3019,5 +3019,119 @@ This is a test agent that handles various tasks.
 				}
 			})
 		})
+
+		describe("force parameter", () => {
+			it("should skip version compatibility check when force is true", () => {
+				const { writeFileSync, unlinkSync, existsSync: fsExistsSync } = require("node:fs")
+				const tempPath = join(import.meta.dirname, "temp-force-version.md")
+				try {
+					const content = `---
+version: 1.0
+requires: ">=99.0.0"
+---
+# Test Agent
+
+This is a test agent that handles various tasks.
+`.padEnd(MIN_CONTENT_LENGTH + 50, " ")
+					writeFileSync(tempPath, content)
+
+					// Without force, this should fail
+					const resultWithoutForce = validateAgentFile(tempPath, "1.0.0", false)
+					expect(resultWithoutForce.valid).toBe(false)
+					expect(resultWithoutForce.error).toContain("Incompatible OpenCode version")
+
+					// With force, this should succeed and indicate version check was skipped
+					const resultWithForce = validateAgentFile(tempPath, "1.0.0", true)
+					expect(resultWithForce.valid).toBe(true)
+					expect(resultWithForce.skippedVersionCheck).toBe(true)
+				} finally {
+					if (fsExistsSync(tempPath)) {
+						unlinkSync(tempPath)
+					}
+				}
+			})
+
+			it("should not set skippedVersionCheck when version is compatible", () => {
+				const { writeFileSync, unlinkSync, existsSync: fsExistsSync } = require("node:fs")
+				const tempPath = join(import.meta.dirname, "temp-force-compatible.md")
+				try {
+					const content = `---
+version: 1.0
+requires: ">=1.0.0"
+---
+# Test Agent
+
+This is a test agent that handles various tasks.
+`.padEnd(MIN_CONTENT_LENGTH + 50, " ")
+					writeFileSync(tempPath, content)
+
+					// Version is compatible, so skippedVersionCheck should not be set
+					const result = validateAgentFile(tempPath, "1.0.0", true)
+					expect(result.valid).toBe(true)
+					expect(result.skippedVersionCheck).toBeUndefined()
+				} finally {
+					if (fsExistsSync(tempPath)) {
+						unlinkSync(tempPath)
+					}
+				}
+			})
+
+			it("should still validate content structure when force is true", () => {
+				const { writeFileSync, unlinkSync, existsSync: fsExistsSync } = require("node:fs")
+				const tempPath = join(import.meta.dirname, "temp-force-invalid-content.md")
+				try {
+					// Content without frontmatter should still fail even with force
+					writeFileSync(
+						tempPath,
+						"# No Frontmatter\n\nThis agent has no frontmatter but mentions agent and task.".padEnd(
+							MIN_CONTENT_LENGTH + 10,
+							" ",
+						),
+					)
+					const result = validateAgentFile(tempPath, "1.0.0", true)
+					expect(result.valid).toBe(false)
+					expect(result.error).toContain("frontmatter")
+				} finally {
+					if (fsExistsSync(tempPath)) {
+						unlinkSync(tempPath)
+					}
+				}
+			})
+
+			it("should default force to false when not provided", () => {
+				const { writeFileSync, unlinkSync, existsSync: fsExistsSync } = require("node:fs")
+				const tempPath = join(import.meta.dirname, "temp-force-default.md")
+				try {
+					const content = `---
+version: 1.0
+requires: ">=99.0.0"
+---
+# Test Agent
+
+This is a test agent that handles various tasks.
+`.padEnd(MIN_CONTENT_LENGTH + 50, " ")
+					writeFileSync(tempPath, content)
+
+					// Without explicit force parameter, should fail on incompatible version
+					const result = validateAgentFile(tempPath, "1.0.0")
+					expect(result.valid).toBe(false)
+					expect(result.error).toContain("Incompatible OpenCode version")
+				} finally {
+					if (fsExistsSync(tempPath)) {
+						unlinkSync(tempPath)
+					}
+				}
+			})
+
+			it("should work with actual agent files when force is true", () => {
+				const agentsDir = join(import.meta.dirname, "..", "agents")
+				for (const name of AGENT_NAMES) {
+					const filePath = join(agentsDir, `${name}.md`)
+					const result = validateAgentFile(filePath, "0.0.1", true)
+					// With force=true, even incompatible versions should pass
+					expect(result.valid).toBe(true)
+				}
+			})
+		})
 	})
 })
