feat: add specific error reasons to parseFrontmatter for missing/unclosed cases

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

Author: leocavalcante

src/paths.d.mts

@@ -126,6 +126,8 @@ export function retryOnTransientError<T>(
 export interface ParseFrontmatterResult {
 	/** Whether frontmatter was found in the content */
 	found: boolean
+	/** Reason for failure when found is false: "missing" if content doesn't start with ---, "unclosed" if closing --- not found */
+	reason?: "missing" | "unclosed"
 	/** Parsed key-value pairs from the frontmatter */
 	fields: Record<string, string>
 	/** Character index where the frontmatter ends (after closing ---\n) */

src/paths.mjs

@@ -201,18 +201,18 @@ export async function retryOnTransientError(fn, options = {}) {
  * Expects frontmatter to be delimited by --- at the start of the file.
  *
  * @param {string} content - The file content to parse
- * @returns {{ found: boolean, fields: Record<string, string>, endIndex: number }} Parse result
+ * @returns {{ found: boolean, reason?: "missing" | "unclosed", fields: Record<string, string>, endIndex: number }} Parse result
  */
 export function parseFrontmatter(content) {
 	// Frontmatter must start at the beginning of the file
 	if (!content.startsWith("---")) {
-		return { found: false, fields: {}, endIndex: 0 }
+		return { found: false, reason: "missing", fields: {}, endIndex: 0 }
 	}
 
 	// Find the closing ---
 	const endMatch = content.indexOf("\n---", 3)
 	if (endMatch === -1) {
-		return { found: false, fields: {}, endIndex: 0 }
+		return { found: false, reason: "unclosed", fields: {}, endIndex: 0 }
 	}
 
 	// Extract frontmatter content (between the --- delimiters)
@@ -271,9 +271,13 @@ export function validateAgentContent(content) {
 	// Check for YAML frontmatter
 	const frontmatter = parseFrontmatter(content)
 	if (!frontmatter.found) {
+		const errorMessage =
+			frontmatter.reason === "unclosed"
+				? "Unclosed YAML frontmatter (missing closing ---)"
+				: "File missing YAML frontmatter (must start with ---)"
 		return {
 			valid: false,
-			error: "File missing YAML frontmatter (must start with ---)",
+			error: errorMessage,
 		}
 	}
 

tests/paths.test.ts

@@ -509,16 +509,18 @@ describe("paths.mjs exports", () => {
 	})
 
 	describe("parseFrontmatter", () => {
-		it("should return found: false when content does not start with ---", () => {
+		it("should return found: false with reason 'missing' when content does not start with ---", () => {
 			const result = parseFrontmatter("# No frontmatter")
 			expect(result.found).toBe(false)
+			expect(result.reason).toBe("missing")
 			expect(result.fields).toEqual({})
 			expect(result.endIndex).toBe(0)
 		})
 
-		it("should return found: false when closing --- is missing", () => {
+		it("should return found: false with reason 'unclosed' when closing --- is missing", () => {
 			const result = parseFrontmatter("---\nversion: 1.0\nno closing delimiter")
 			expect(result.found).toBe(false)
+			expect(result.reason).toBe("unclosed")
 			expect(result.fields).toEqual({})
 			expect(result.endIndex).toBe(0)
 		})
@@ -531,6 +533,7 @@ requires: opencode
 # Content`
 			const result = parseFrontmatter(content)
 			expect(result.found).toBe(true)
+			expect(result.reason).toBeUndefined()
 			expect(result.fields.version).toBe("1.0")
 			expect(result.fields.requires).toBe("opencode")
 		})
@@ -641,15 +644,28 @@ The agent can process multiple items efficiently.
 			expect(result.error).toContain(`minimum ${MIN_CONTENT_LENGTH}`)
 		})
 
-		it("should return valid: false when frontmatter is missing", () => {
+		it("should return valid: false with specific error when frontmatter is missing", () => {
 			const content =
 				"# No Frontmatter Agent\n\nThis agent has no frontmatter but is an agent for tasks.".padEnd(
 					MIN_CONTENT_LENGTH + 10,
 					" ",
 				)
 			const result = validateAgentContent(content)
 			expect(result.valid).toBe(false)
-			expect(result.error).toContain("YAML frontmatter")
+			expect(result.error).toBe("File missing YAML frontmatter (must start with ---)")
+		})
+
+		it("should return valid: false with specific error when frontmatter is unclosed", () => {
+			const content = `---
+version: 1.0
+requires: opencode
+This file has no closing frontmatter delimiter.
+# Test Agent
+This is a test agent that handles various tasks.
+`.padEnd(MIN_CONTENT_LENGTH + 50, " ")
+			const result = validateAgentContent(content)
+			expect(result.valid).toBe(false)
+			expect(result.error).toBe("Unclosed YAML frontmatter (missing closing ---)")
 		})
 
 		it("should return valid: false when version field is missing", () => {