@vibe-agent-toolkit/resources 0.1.11 → 0.1.13

package/dist/schemas/project-config.js

@@ -7,6 +7,25 @@ import { z } from 'zod';
  */
 export const ValidationModeSchema = z.enum(['strict', 'permissive'])
     .describe('Validation mode for frontmatter schema validation');
+/**
+ * External URL validation configuration.
+ *
+ * Controls how external URLs are validated:
+ * - enabled: Whether to check external URLs
+ * - timeout: Request timeout in milliseconds (default: 15000)
+ * - retryOn429: Whether to retry on rate limit (default: true)
+ * - ignorePatterns: Regex patterns for URLs to skip (e.g., '^https://localhost')
+ */
+export const ExternalUrlValidationSchema = z.object({
+    enabled: z.boolean().optional()
+        .describe('Whether to validate external URLs (default: false)'),
+    timeout: z.number().int().positive().optional()
+        .describe('Request timeout in milliseconds (default: 15000)'),
+    retryOn429: z.boolean().optional()
+        .describe('Whether to retry on rate limit (429) (default: true)'),
+    ignorePatterns: z.array(z.string()).optional()
+        .describe('Regex patterns for URLs to skip validation (e.g., "^https://localhost")'),
+}).describe('External URL validation configuration');
 /**
  * Validation configuration for a collection.
  */
@@ -19,6 +38,8 @@ export const CollectionValidationSchema = z.object({
         .describe('Whether to validate external URL links (default: false)'),
     checkGitIgnored: z.boolean().optional()
         .describe('Whether to check if non-ignored files link to git-ignored files (default: true)'),
+    externalUrls: ExternalUrlValidationSchema.optional()
+        .describe('External URL validation configuration'),
 }).describe('Validation configuration for a collection');
 /**
  * Configuration for a named collection of resources.

package/dist/schemas/project-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../../src/schemas/project-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;KACjE,QAAQ,CAAC,mDAAmD,CAAC,CAAC;AAIjE;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACrC,QAAQ,CAAC,mJAAmJ,CAAC;IAChK,IAAI,EAAE,oBAAoB,CAAC,QAAQ,EAAE;SAClC,QAAQ,CAAC,mCAAmC,CAAC;IAChD,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SAClC,QAAQ,CAAC,yDAAyD,CAAC;IACtE,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SACpC,QAAQ,CAAC,iFAAiF,CAAC;CAC/F,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC,CAAC;AAIzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;SAChC,QAAQ,CAAC,qDAAqD,CAAC;IAClE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;SACpC,QAAQ,CAAC,0BAA0B,CAAC;IACvC,UAAU,EAAE,0BAA0B,CAAC,QAAQ,EAAE;SAC9C,QAAQ,CAAC,8CAA8C,CAAC;CAC5D,CAAC,CAAC,QAAQ,CAAC,mDAAmD,CAAC,CAAC;AAIjE;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;SACpC,QAAQ,CAAC,sEAAsE,CAAC;IACnF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;SACpC,QAAQ,CAAC,sEAAsE,CAAC;IACnF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,sBAAsB,CAAC;SACtD,QAAQ,CAAC,gCAAgC,CAAC;CAC9C,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC,CAAC;AAI1D;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;SAClB,QAAQ,CAAC,iCAAiC,CAAC;IAC9C,SAAS,EAAE,qBAAqB,CAAC,QAAQ,EAAE;SACxC,QAAQ,CAAC,yBAAyB,CAAC;CACvC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC,CAAC"}
+{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../../src/schemas/project-config.ts"],"names":[],"mappings":"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"}

package/dist/schemas/validation-result.d.ts

@@ -8,6 +8,9 @@ import { z } from 'zod';
  * - frontmatter_missing: Schema requires frontmatter, file has none
  * - frontmatter_invalid_yaml: YAML syntax error in frontmatter
  * - frontmatter_schema_error: Frontmatter fails JSON Schema validation
+ * - external_url_dead: External URL returned error status (4xx, 5xx)
+ * - external_url_timeout: External URL request timed out
+ * - external_url_error: External URL validation failed (DNS, network, etc.)
  * - unknown_link: Unknown link type
  *
  * Includes details about what went wrong, where it occurred, and optionally

package/dist/schemas/validation-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-result.d.ts","sourceRoot":"","sources":["../../src/schemas/validation-result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;EAOmC,CAAC;AAEtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASsC,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"validation-result.d.ts","sourceRoot":"","sources":["../../src/schemas/validation-result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;EAOmC,CAAC;AAEtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASsC,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/schemas/validation-result.js

@@ -8,6 +8,9 @@ import { z } from 'zod';
  * - frontmatter_missing: Schema requires frontmatter, file has none
  * - frontmatter_invalid_yaml: YAML syntax error in frontmatter
  * - frontmatter_schema_error: Frontmatter fails JSON Schema validation
+ * - external_url_dead: External URL returned error status (4xx, 5xx)
+ * - external_url_timeout: External URL request timed out
+ * - external_url_error: External URL validation failed (DNS, network, etc.)
  * - unknown_link: Unknown link type
  *
  * Includes details about what went wrong, where it occurred, and optionally

package/dist/schemas/validation-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-result.js","sourceRoot":"","sources":["../../src/schemas/validation-result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;IACvF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAC3F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0GAA0G,CAAC;IACrI,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACjD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IACvE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CACvF,CAAC,CAAC,QAAQ,CAAC,wDAAwD,CAAC,CAAC;AAItE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IAC9F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IACvG,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,kEAAkE,CAAC;IAC9I,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC9E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAC7E,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAC/E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IACpF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;CAC9D,CAAC,CAAC,QAAQ,CAAC,4DAA4D,CAAC,CAAC"}
+{"version":3,"file":"validation-result.js","sourceRoot":"","sources":["../../src/schemas/validation-result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;IACvF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;IAC3F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0GAA0G,CAAC;IACrI,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACjD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IACvE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;CACvF,CAAC,CAAC,QAAQ,CAAC,wDAAwD,CAAC,CAAC;AAItE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IAC9F,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IACvG,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,kEAAkE,CAAC;IAC9I,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC9E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAC7E,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAC/E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IACpF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;CAC9D,CAAC,CAAC,QAAQ,CAAC,4DAA4D,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/resources",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Markdown resource parsing, validation, and link integrity checking",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,9 +33,10 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "dependencies": {
-    "@vibe-agent-toolkit/utils": "0.1.11",
+    "@vibe-agent-toolkit/utils": "0.1.13",
     "ajv": "^8.17.1",
     "js-yaml": "^4.1.1",
+    "markdown-link-check": "^3.14.2",
     "picomatch": "^4.0.3",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",

package/src/external-link-cache.ts

@@ -0,0 +1,215 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Cache entry for external link validation results
+ */
+interface CacheEntry {
+	statusCode: number;
+	statusMessage: string;
+	timestamp: number;
+}
+
+/**
+ * Cache storage format
+ */
+interface CacheData {
+	[url: string]: CacheEntry;
+}
+
+/**
+ * External link validation cache
+ *
+ * Stores results of external URL checks to minimize redundant network requests.
+ * Uses file-based storage for persistence across runs.
+ *
+ * Cache keys are SHA-256 hashes of normalized URLs to handle long URLs and
+ * special characters safely in filenames.
+ *
+ * Example:
+ * ```typescript
+ * const cache = new ExternalLinkCache('/tmp/cache', 24);
+ *
+ * // Store a result
+ * await cache.set('https://example.com', 200, 'OK');
+ *
+ * // Retrieve a result
+ * const result = await cache.get('https://example.com');
+ * if (result) {
+ *   console.log(`Status: ${result.statusCode}`);
+ * }
+ * ```
+ */
+export class ExternalLinkCache {
+	private readonly cacheDir: string;
+	private readonly ttlHours: number;
+	private readonly cacheFile: string;
+	private cache: CacheData | null = null;
+
+	/**
+	 * Create a new external link cache
+	 *
+	 * @param cacheDir - Directory to store cache files
+	 * @param ttlHours - Time-to-live in hours (default: 24)
+	 */
+	constructor(cacheDir: string, ttlHours = 24) {
+		this.cacheDir = cacheDir;
+		this.ttlHours = ttlHours;
+		this.cacheFile = path.join(cacheDir, 'external-links.json');
+	}
+
+	/**
+	 * Load cache from disk
+	 */
+	private async loadCache(): Promise<CacheData> {
+		if (this.cache !== null) {
+			return this.cache;
+		}
+
+		try {
+			// eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheDir is constructor parameter, controlled by caller
+			await fs.mkdir(this.cacheDir, { recursive: true });
+			// eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheFile is derived from cacheDir
+			const data = await fs.readFile(this.cacheFile, 'utf-8');
+			this.cache = JSON.parse(data) as CacheData;
+			return this.cache;
+		} catch (error) {
+			// Handle missing file or corrupted JSON - start with empty cache
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT' || error instanceof SyntaxError) {
+				this.cache = {};
+				return this.cache;
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Save cache to disk
+	 */
+	private async saveCache(): Promise<void> {
+		if (this.cache === null) {
+			return;
+		}
+
+		// eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheDir is constructor parameter, controlled by caller
+		await fs.mkdir(this.cacheDir, { recursive: true });
+		// eslint-disable-next-line security/detect-non-literal-fs-filename -- cacheFile is derived from cacheDir
+		await fs.writeFile(this.cacheFile, JSON.stringify(this.cache, null, 2), 'utf-8');
+	}
+
+	/**
+	 * Normalize URL for caching
+	 *
+	 * Removes trailing slashes and anchors to treat variations as the same URL.
+	 */
+	private normalizeUrl(url: string): string {
+		try {
+			const parsed = new URL(url);
+			// Remove hash/anchor
+			parsed.hash = '';
+			// Remove trailing slash
+			let normalized = parsed.toString();
+			if (normalized.endsWith('/')) {
+				normalized = normalized.slice(0, -1);
+			}
+			return normalized;
+		} catch {
+			// If URL parsing fails, use as-is
+			return url;
+		}
+	}
+
+	/**
+	 * Generate cache key for URL
+	 *
+	 * Uses SHA-256 hash to handle long URLs and special characters.
+	 */
+	private getCacheKey(url: string): string {
+		const normalized = this.normalizeUrl(url);
+		return createHash('sha256').update(normalized).digest('hex');
+	}
+
+	/**
+	 * Check if cache entry is expired
+	 */
+	private isExpired(entry: CacheEntry): boolean {
+		const now = Date.now();
+		const age = now - entry.timestamp;
+		const ttlMs = this.ttlHours * 60 * 60 * 1000;
+		return age > ttlMs;
+	}
+
+	/**
+	 * Get cached result for URL
+	 *
+	 * @param url - URL to look up
+	 * @returns Cache entry or null if not found/expired
+	 */
+	async get(url: string): Promise<CacheEntry | null> {
+		const cache = await this.loadCache();
+		const key = this.getCacheKey(url);
+		const entry = cache[key];
+
+		if (!entry) {
+			return null;
+		}
+
+		if (this.isExpired(entry)) {
+			delete cache[key];
+			await this.saveCache();
+			return null;
+		}
+
+		return entry;
+	}
+
+	/**
+	 * Store validation result in cache
+	 *
+	 * @param url - URL to cache
+	 * @param statusCode - HTTP status code
+	 * @param statusMessage - HTTP status message
+	 */
+	async set(url: string, statusCode: number, statusMessage: string): Promise<void> {
+		const cache = await this.loadCache();
+		const key = this.getCacheKey(url);
+
+		cache[key] = {
+			statusCode,
+			statusMessage,
+			timestamp: Date.now(),
+		};
+
+		await this.saveCache();
+	}
+
+	/**
+	 * Clear all cache entries
+	 */
+	async clear(): Promise<void> {
+		this.cache = {};
+		await this.saveCache();
+	}
+
+	/**
+	 * Get cache statistics
+	 */
+	async getStats(): Promise<{ total: number; expired: number }> {
+		const cache = await this.loadCache();
+		const keys = Object.keys(cache);
+		const expired = keys.filter((key) => {
+			const entry = cache[key];
+			// Type guard: ensure entry exists before checking expiration
+			if (entry === undefined) {
+				return false;
+			}
+			return this.isExpired(entry);
+		}).length;
+
+		return {
+			total: keys.length,
+			expired,
+		};
+	}
+}

package/src/external-link-validator.ts

@@ -0,0 +1,250 @@
+import markdownLinkCheck from 'markdown-link-check';
+
+import { ExternalLinkCache } from './external-link-cache.js';
+
+/**
+ * Safely serialize an error to a string, preventing [object Object] issues.
+ * Handles Error objects, strings, objects, and edge cases.
+ */
+function safeSerializeError(err: unknown): string | undefined {
+	if (!err) {
+		return undefined;
+	}
+
+	if (typeof err === 'string') {
+		// Return undefined for empty strings so fallback message is used
+		return err.trim() || undefined;
+	}
+
+	if (err instanceof Error) {
+		// Return undefined for empty messages so fallback is used
+		return err.message.trim() || undefined;
+	}
+
+	// For objects, try JSON.stringify with fallback
+	try {
+		const serialized = JSON.stringify(err);
+		// Avoid returning literal "{}" which isn't helpful
+		if (serialized === '{}') {
+			// Try to extract something useful from the object
+			const msg = (err as { message?: unknown }).message;
+			return typeof msg === 'string' && msg.trim() ? msg : 'Unknown error';
+		}
+		return serialized;
+	} catch {
+		// JSON.stringify can fail on circular references
+		// Try to extract message property if it exists
+		const msg = (err as { message?: unknown }).message;
+		return typeof msg === 'string' && msg.trim() ? msg : 'Error (unserializable)';
+	}
+}
+
+/**
+ * Configuration options for external link validation
+ */
+export interface ExternalLinkValidatorOptions {
+	/** Time-to-live for cache entries in hours (default: 24) */
+	cacheTtlHours?: number;
+	/** Request timeout in milliseconds (default: 5000) */
+	timeout?: number;
+	/** Number of retries for failed requests (default: 2) */
+	retries?: number;
+	/** User agent string for requests (default: generic) */
+	userAgent?: string;
+}
+
+/**
+ * Result of validating a single external link
+ */
+export interface LinkValidationResult {
+	/** The URL that was validated */
+	url: string;
+	/** Validation status: 'ok' = working, 'error' = broken */
+	status: 'ok' | 'error';
+	/** HTTP status code (e.g., 200, 404) */
+	statusCode: number;
+	/** Error message if validation failed */
+	error?: string;
+	/** Whether result came from cache */
+	cached: boolean;
+}
+
+/**
+ * Validates external URLs in markdown content
+ *
+ * Uses markdown-link-check library with caching to efficiently validate
+ * external links. Respects cache TTL and provides detailed error information.
+ *
+ * Example:
+ * ```typescript
+ * const validator = new ExternalLinkValidator('/tmp/cache', {
+ *   cacheTtlHours: 24,
+ *   timeout: 5000,
+ * });
+ *
+ * const result = await validator.validateLink('https://example.com');
+ * if (result.status === 'error') {
+ *   console.error(`Broken link: ${result.url} - ${result.error}`);
+ * }
+ * ```
+ */
+export class ExternalLinkValidator {
+	private readonly cache: ExternalLinkCache;
+	private readonly options: Required<ExternalLinkValidatorOptions>;
+
+	/**
+	 * Create a new external link validator
+	 *
+	 * @param cacheDir - Directory for storing cache
+	 * @param options - Validation options
+	 */
+	constructor(cacheDir: string, options: ExternalLinkValidatorOptions = {}) {
+		this.options = {
+			cacheTtlHours: options.cacheTtlHours ?? 24,
+			timeout: options.timeout ?? 5000,
+			retries: options.retries ?? 2,
+			userAgent:
+				options.userAgent ??
+				'Mozilla/5.0 (compatible; VAT-LinkChecker/1.0; +https://github.com/jdutton/vibe-agent-toolkit)',
+		};
+
+		this.cache = new ExternalLinkCache(cacheDir, this.options.cacheTtlHours);
+	}
+
+	/**
+	 * Validate a single external link
+	 *
+	 * @param url - URL to validate
+	 * @returns Validation result
+	 */
+	async validateLink(url: string): Promise<LinkValidationResult> {
+		// Check cache first
+		const cached = await this.cache.get(url);
+		if (cached) {
+			const isOk = cached.statusCode >= 200 && cached.statusCode < 400;
+
+			// Return success result without error property (exactOptionalPropertyTypes)
+			if (isOk) {
+				return {
+					url,
+					status: 'ok' as const,
+					statusCode: cached.statusCode,
+					cached: true,
+				};
+			}
+
+			// Return error result with error property
+			return {
+				url,
+				status: 'error' as const,
+				statusCode: cached.statusCode,
+				cached: true,
+				error: cached.statusMessage,
+			};
+		}
+
+		// Validate using markdown-link-check
+		const result = await this.checkLink(url);
+
+		// Store in cache
+		await this.cache.set(url, result.statusCode, result.error ?? 'OK');
+
+		return {
+			...result,
+			cached: false,
+		};
+	}
+
+	/**
+	 * Validate multiple links
+	 *
+	 * @param urls - URLs to validate
+	 * @returns Array of validation results
+	 */
+	async validateLinks(urls: string[]): Promise<LinkValidationResult[]> {
+		return Promise.all(urls.map((url) => this.validateLink(url)));
+	}
+
+	/**
+	 * Check a link using markdown-link-check
+	 */
+	private async checkLink(
+		url: string,
+	): Promise<Pick<LinkValidationResult, 'url' | 'status' | 'statusCode' | 'error'>> {
+		return new Promise((resolve) => {
+			const markdown = `[link](${url})`;
+
+			markdownLinkCheck(
+				markdown,
+				{
+					timeout: `${this.options.timeout}ms`,
+					retryOn429: true,
+					retryCount: this.options.retries,
+					aliveStatusCodes: [200, 206, 301, 302, 307, 308],
+					ignorePatterns: [],
+					httpHeaders: [
+						{
+							urls: [url],
+							headers: {
+								'User-Agent': this.options.userAgent,
+							},
+						},
+					],
+				},
+				(error: Error | null, results: Array<{ link: string; status: string; statusCode: number; err?: string | Error | object }>) => {
+					if (error) {
+						resolve({
+							url,
+							status: 'error',
+							statusCode: 0,
+							error: error.message,
+						});
+						return;
+					}
+
+					const result = results[0];
+					if (!result) {
+						resolve({
+							url,
+							status: 'error',
+							statusCode: 0,
+							error: 'No result from markdown-link-check',
+						});
+						return;
+					}
+
+					if (result.status === 'alive') {
+						resolve({
+							url,
+							status: 'ok',
+							statusCode: result.statusCode,
+						});
+					} else {
+						const errorMessage = safeSerializeError(result.err) ?? `Link status: ${result.status}`;
+
+						resolve({
+							url,
+							status: 'error',
+							statusCode: result.statusCode,
+							error: errorMessage,
+						});
+					}
+				},
+			);
+		});
+	}
+
+	/**
+	 * Clear the validation cache
+	 */
+	async clearCache(): Promise<void> {
+		await this.cache.clear();
+	}
+
+	/**
+	 * Get cache statistics
+	 */
+	async getCacheStats(): Promise<{ total: number; expired: number }> {
+		return this.cache.getStats();
+	}
+}

package/src/link-parser.ts

@@ -12,7 +12,7 @@
 import { readFile, stat } from 'node:fs/promises';
 
 import * as yaml from 'js-yaml';
-import type { Heading, Link, LinkReference, Root } from 'mdast';
+import type { Definition, Heading, Link, LinkReference, Root } from 'mdast';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
@@ -130,6 +130,18 @@ function extractLinks(tree: Root): ResourceLink[] {
     links.push(link);
   });
 
+  // Visit definition nodes (reference-style link definitions: [ref]: url)
+  // These provide the actual URLs for linkReference nodes
+  visit(tree, 'definition', (node: Definition) => {
+    const link: ResourceLink = {
+      text: node.identifier,
+      href: node.url,
+      type: classifyLink(node.url),
+      line: node.position?.start.line,
+    };
+    links.push(link);
+  });
+
   return links;
 }