aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
230 lines • 7.75 kB
TypeScript
/**
* Plugin Metadata Validator
*
* Validates plugin manifest YAML files for schema correctness, required fields,
* version compatibility, and file reference validation.
*
* @module src/plugin/metadata-validator
*/
/**
* Severity levels for validation errors and warnings
*/
export type Severity = 'error' | 'warning';
/**
* Validation error with path and severity
*/
export interface ValidationError {
path?: string;
field?: string;
message: string;
severity: Severity;
line?: number;
}
/**
* Validation warning (non-blocking)
*/
export interface ValidationWarning {
path?: string;
field?: string;
message: string;
line?: number;
}
/**
* Plugin manifest structure
*/
export interface PluginManifest {
name: string;
version: string;
type: 'agent' | 'command' | 'template' | 'flow' | 'behavior';
description: string;
files: string[];
dependencies?: Record<string, string>;
metadata?: Record<string, unknown>;
model?: string;
tools?: string | string[];
framework?: string;
}
/**
* Validation result for a single manifest
*/
export interface ValidationResult {
valid: boolean;
errors: ValidationError[];
warnings: ValidationWarning[];
manifest?: PluginManifest;
}
/**
* Options for validation behavior
*/
export interface ValidationOptions {
/** Check that referenced files exist on filesystem */
checkFileReferences?: boolean;
/** Treat warnings as errors */
strict?: boolean;
/** Auto-fix common issues (e.g., version format) */
autoFix?: boolean;
}
/**
* Batch validation result for multiple manifests
*/
export type BatchValidationResult = Map<string, ValidationResult>;
/**
* Report format options
*/
export type ReportFormat = 'text' | 'json';
/**
* MetadataValidator validates plugin manifest files
*/
export declare class MetadataValidator {
private options;
constructor(options?: ValidationOptions);
/**
* Validate a manifest file from the filesystem
*
* @param manifestPath - Absolute path to manifest.md or BEHAVIOR.md file
* @returns Validation result with errors and warnings
*/
validateFile(manifestPath: string): Promise<ValidationResult>;
/**
* Validate manifest content from string
*
* @param content - Manifest file content
* @param basePath - Optional base path for file reference validation
* @param filename - Optional filename to infer type (e.g., 'BEHAVIOR.md')
* @returns Validation result
*/
validateManifest(content: string, basePath?: string, filename?: string): Promise<ValidationResult>;
/**
* Validate a SKILL.md frontmatter file.
*
* SKILL.md is a separate artifact type from manifest.md/BEHAVIOR.md and
* has its own schema ({@link SkillFrontmatterSchema} in
* `src/extensions/validation.ts`). It does NOT carry `version`, `type`,
* `dependencies`, or `files` fields, so we route it through a dedicated
* validator instead of branching inside {@link validateManifest}.
*
* Adding a new artifact type? Add a sibling method here, then dispatch
* to it from {@link validateFile} based on filename.
*
* @param content - Full SKILL.md file contents (frontmatter + body)
* @param _basePath - Reserved for future cross-file checks
* @param filename - File basename, used in error.path for diagnostics
* @returns Validation result
*/
validateSkillManifest(content: string, _basePath?: string, filename?: string): Promise<ValidationResult>;
/**
* Validate manifest schema structure
*
* @param manifest - Parsed manifest object
* @returns Validation result
*/
validateSchema(manifest: unknown): ValidationResult;
/**
* Validate BEHAVIOR.md schema structure
*
* BEHAVIOR.md files use a different schema than manifest.md:
* - Required: name, version, description, platforms
* - Optional: triggers, inputs, hooks, scripts, manifest, scope, tone, routing, memory
*
* @param manifest - Parsed frontmatter object
* @returns Validation result
*/
validateBehaviorSchema(manifest: unknown): ValidationResult;
/**
* Validate required fields are present and non-empty
*
* @param manifest - Validated manifest object
* @returns Array of validation errors
*/
validateRequiredFields(manifest: PluginManifest): ValidationError[];
/**
* Validate version string is valid semver
*
* @param version - Version string to validate
* @returns Array of validation errors
*/
validateVersion(version: string): ValidationError[];
/**
* Validate file references exist on filesystem
*
* @param manifest - Validated manifest object
* @param basePath - Base directory path for resolving relative file paths
* @returns Array of validation errors
*/
validateFileReferences(manifest: PluginManifest, basePath: string): Promise<ValidationError[]>;
/**
* Validate dependency version ranges
*
* @param dependencies - Dependency map with version ranges
* @returns Array of validation errors
*/
validateDependencies(dependencies: Record<string, string>): ValidationError[];
/**
* Check metadata completeness and provide warnings
*
* @param manifest - Validated manifest object
* @returns Array of warnings
*/
checkMetadataCompleteness(manifest: PluginManifest): ValidationWarning[];
/**
* Validate memory.topology contract if declared
*
* Checks that declared paths follow .aiwg/ convention and required fields
* are present when topology is declared.
*
* @see ADR-021 — Semantic memory kernel architecture
*/
validateMemoryTopology(manifest: PluginManifest): ValidationWarning[];
/**
* Validate all manifests in a directory
*
* @param dirPath - Directory path to scan
* @param recursive - Whether to scan subdirectories recursively
* @returns Map of file paths to validation results
*/
validateDirectory(dirPath: string, recursive?: boolean): Promise<BatchValidationResult>;
/**
* Generate validation report in specified format
*
* @param results - Batch validation results
* @param format - Report format (text or json)
* @returns Formatted report string
*/
generateReport(results: BatchValidationResult, format?: ReportFormat): string;
/**
* Parse YAML frontmatter from manifest content
*
* @param content - File content
* @param result - Validation result to populate with errors
* @returns Parsed manifest or null if parsing failed
*/
private parseFrontmatter;
/**
* Find all manifest.md, BEHAVIOR.md, and SKILL.md files in a directory.
*
* Each filename routes to a different schema in {@link validateManifest}:
* - manifest.md — plugin manifest schema (requires version, type)
* - BEHAVIOR.md — behavior schema (triggers/hooks)
* - SKILL.md — skill frontmatter schema (name, description, …)
*
* @param dirPath - Directory to search
* @param recursive - Whether to search subdirectories
* @returns Array of absolute artifact file paths
*/
private findManifestFiles;
/**
* Generate text format report
*
* @param results - Batch validation results
* @returns Formatted text report
*/
private generateTextReport;
/**
* Generate JSON format report
*
* @param results - Batch validation results
* @returns JSON string
*/
private generateJsonReport;
}
//# sourceMappingURL=metadata-validator.d.ts.map