Refactor, Added documentation, moved from avj-cli to avj, update script and added tests

source/template/errors.ts

@@ -0,0 +1,64 @@
+/* eslint-disable max-classes-per-file */
+
+import type { $ZodIssue } from 'zod/v4/core';
+
+/**
+ * Formats the Zod validation failures into a single string with one line each: "- <field>: <message>" and top level failures
+ * with no field path show as "(root)" for better readability.
+ *
+ * @param issues The Zod validation failures to format.
+ * @returns A human readable error string for better debugging.
+ */
+export const buildErrorDescription = (issues: $ZodIssue[]): string => {
+    // Initialize an empty array to store the formatted lines.
+    const lines: string[] = [];
+
+    // Iterate over the issues and format them into a string.
+    for (const issue of issues) {
+        // Get the issue path.
+        const issuePath = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+
+        // The prefix that Zod adds to messages.
+        const messagePrefix = 'Invalid input: ';
+
+        // Remove the prefix for better readability.
+        const issueMessage = issue.message.startsWith(messagePrefix) ? issue.message.slice(messagePrefix.length) : issue.message;
+
+        // Add the formatted line to the array.
+        lines.push(`- ${issuePath}: ${issueMessage}`);
+    }
+
+    // Return the formatted string.
+    return `\n${lines.join('\n')}`;
+};
+
+/**
+ * Thrown when the provided template does not satisfy the XOTemplate schema.
+ */
+export class TemplateInvalidError extends Error {
+    constructor(details: string) {
+        const message = `Template invalid: ${details}`;
+        super(message);
+        this.name = 'TemplateInvalidError';
+    }
+}
+
+/**
+ * Thrown when a string passed to `deserializeTemplate` cannot be parsed as JSON.
+ */
+export class TemplateJsonMalformedError extends Error {
+    constructor(reason: string) {
+        super(`Template JSON malformed, expected a valid JSON string: ${reason}`);
+        this.name = 'TemplateJsonMalformedError';
+    }
+}
+
+/**
+ * Thrown when `serializeTemplate` fails to produce a JSON string from the template.
+ */
+export class TemplateSerializationFailedError extends Error {
+    constructor(reason: string) {
+        super(`Template serialization failed: ${reason}`);
+        this.name = 'TemplateSerializationFailedError';
+    }
+}