claude-flow-novice 2.15.5 → 2.15.7

package/claude-assets/skills/cfn-skill-propagation/src/metadata-parser.ts

@@ -0,0 +1,154 @@
+/**
+ * YAML Frontmatter parser for Skill metadata
+ */
+
+import type { SkillMetadata, ValidationResult, MetadataParser } from './types';
+
+export class SkillMetadataParser implements MetadataParser {
+  /**
+   * Parse YAML frontmatter from skill file content
+   */
+  parse(content: string): SkillMetadata {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+
+    if (!frontmatterMatch) {
+      throw new Error('No frontmatter found in skill file (expected YAML between --- markers)');
+    }
+
+    const frontmatterContent = frontmatterMatch[1];
+    return this.parseYAML(frontmatterContent);
+  }
+
+  /**
+   * Parse YAML content into JavaScript object
+   * Simple YAML parser for our specific use case
+   */
+  private parseYAML(yamlContent: string | undefined): SkillMetadata {
+    if (!yamlContent) {
+      return {} as SkillMetadata;
+    }
+
+    const metadata: Record<string, any> = {};
+
+    const lines = yamlContent.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        continue;
+      }
+
+      const colonIndex = trimmed.indexOf(':');
+      if (colonIndex === -1) {
+        continue;
+      }
+
+      const key = trimmed.substring(0, colonIndex).trim();
+      const valueStr = trimmed.substring(colonIndex + 1).trim();
+
+      const value = this.parseYAMLValue(valueStr);
+      metadata[key] = value;
+    }
+
+    return metadata as SkillMetadata;
+  }
+
+  /**
+   * Parse individual YAML values with type inference
+   */
+  private parseYAMLValue(valueStr: string): any {
+    if (!valueStr) {
+      return null;
+    }
+
+    // Handle quoted strings
+    if ((valueStr.startsWith('"') && valueStr.endsWith('"')) ||
+        (valueStr.startsWith("'") && valueStr.endsWith("'"))) {
+      return valueStr.slice(1, -1);
+    }
+
+    // Handle arrays [tag1, tag2]
+    if (valueStr.startsWith('[') && valueStr.endsWith(']')) {
+      const arrayContent = valueStr.slice(1, -1);
+      return arrayContent
+        .split(',')
+        .map(item => item.trim())
+        .filter(item => item.length > 0);
+    }
+
+    // Handle booleans
+    if (valueStr.toLowerCase() === 'true') {
+      return true;
+    }
+    if (valueStr.toLowerCase() === 'false') {
+      return false;
+    }
+
+    // Handle numbers
+    if (/^\d+$/.test(valueStr)) {
+      return parseInt(valueStr, 10);
+    }
+    if (/^\d+\.\d+$/.test(valueStr)) {
+      return parseFloat(valueStr);
+    }
+
+    // Return as string
+    return valueStr;
+  }
+
+  /**
+   * Validate required metadata fields
+   */
+  validate(metadata: SkillMetadata): ValidationResult {
+    const errors: string[] = [];
+
+    if (!metadata.name) {
+      errors.push('Missing required field: name');
+    }
+
+    if (!metadata.version) {
+      errors.push('Missing required field: version');
+    }
+
+    if (!metadata.description) {
+      errors.push('Missing required field: description');
+    }
+
+    // Validate version format if present
+    if (metadata.version && !/^\d+\.\d+\.\d+$/.test(String(metadata.version))) {
+      errors.push(
+        `Invalid version format: ${metadata.version}. Expected MAJOR.MINOR.PATCH (e.g., 1.0.0)`
+      );
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Extract specific field value or return null
+   */
+  extractField(content: string, fieldName: string): string | null {
+    const match = content.match(new RegExp(`^${fieldName}:\\s*(.*)$`, 'm'));
+    return match && match[1] ? match[1].trim() : null;
+  }
+
+  /**
+   * Extract field with array handling
+   */
+  extractArrayField(content: string, fieldName: string): string[] {
+    const match = content.match(new RegExp(`^${fieldName}:\\s*(\\[.+?\\])$`, 'm'));
+    if (!match || !match[1]) {
+      return [];
+    }
+
+    const arrayStr = match[1];
+    const arrayContent = arrayStr.slice(1, -1);
+    return arrayContent
+      .split(',')
+      .map(item => item.trim())
+      .filter(item => item.length > 0);
+  }
+}

package/claude-assets/skills/cfn-skill-propagation/src/skill-propagator.ts

@@ -0,0 +1,274 @@
+/**
+ * Main Skill Propagator - orchestrates the skill update propagation process
+ */
+
+import type {
+  SkillPropagator as ISkillPropagator,
+  SkillPropagationOptions,
+  PropagationResult,
+  FileSystemAdapter,
+  DatabaseAdapter,
+  Logger,
+} from './types';
+import { SkillValidator } from './skill-validator';
+import { SkillMetadataParser } from './metadata-parser';
+import { VersionManager } from './version-manager';
+
+export class SkillPropagator implements ISkillPropagator {
+  private validator: SkillValidator;
+  private metadataParser: SkillMetadataParser;
+
+  constructor(
+    private fs: FileSystemAdapter,
+    private db: DatabaseAdapter,
+    private logger: Logger
+  ) {
+    this.validator = new SkillValidator(fs, db);
+    this.metadataParser = new SkillMetadataParser();
+  }
+
+  /**
+   * Main propagation workflow
+   */
+  async propagate(options: SkillPropagationOptions): Promise<PropagationResult> {
+    const startTime = new Date().toISOString();
+
+    this.logger.info('========================================');
+    this.logger.info('Propagate Skill Update');
+    this.logger.info('========================================');
+    this.logger.info(`Skill: ${options.skillName}`);
+    this.logger.info(`New Version: ${options.newVersion}`);
+    this.logger.info(`Update Path: ${options.updatePath}`);
+    this.logger.info(`Change Type: ${options.changeType || 'patch'}`);
+    this.logger.info('========================================');
+
+    // Step 1: Validate inputs
+    this.logger.info('Step 1: Validating inputs');
+    const validationResult = await this.validator.validateParameters(options);
+    if (!validationResult.valid) {
+      throw new Error(`Validation failed:\n${validationResult.errors.join('\n')}`);
+    }
+    this.logger.success('Input validation passed');
+
+    // Step 2: Look up existing skill
+    this.logger.info('Step 2: Looking up existing skill');
+    const skillInfo = await this.getSkillInfo(options.skillName);
+    if (!skillInfo) {
+      throw new Error(`Skill not found in database: ${options.skillName}`);
+    }
+    this.logger.info(`Found skill: ID=${skillInfo.id}, Current Version=${skillInfo.version}`);
+
+    // Step 3: Validate version increment
+    this.logger.info('Step 3: Validating version increment');
+    const changeType = options.changeType || 'patch';
+    const versionValidation = await this.validator.validateVersionIncrement(
+      skillInfo.version,
+      options.newVersion,
+      changeType
+    );
+    if (!versionValidation.valid) {
+      throw new Error(`Version validation failed:\n${versionValidation.errors.join('\n')}`);
+    }
+    this.logger.success(`Version increment validated: ${skillInfo.version} → ${options.newVersion} (${changeType})`);
+
+    // Step 4: Calculate new content hash
+    this.logger.info('Step 4: Calculating new content hash');
+    const newHash = await this.fs.calculateHash(options.updatePath);
+    this.logger.debug(`New Hash: ${newHash}`);
+
+    const hashValidation = this.validator.validateContentHashChanged(skillInfo.content_hash, newHash);
+    if (!hashValidation.valid) {
+      throw new Error(`Content validation failed:\n${hashValidation.errors.join('\n')}`);
+    }
+    this.logger.success('Content hash calculated and differs from current');
+
+    // Step 5: Parse frontmatter metadata
+    this.logger.info('Step 5: Parsing frontmatter metadata from updated skill');
+    const updateFileContent = await this.fs.readFile(options.updatePath);
+    const metadata = this.metadataParser.parse(updateFileContent);
+
+    const metadataValidation = this.metadataParser.validate(metadata);
+    if (!metadataValidation.valid) {
+      this.logger.warning(`Metadata validation warnings:\n${metadataValidation.errors.join('\n')}`);
+    }
+
+    // Use new metadata or fall back to existing
+    const newTags = metadata.tags ? JSON.stringify(metadata.tags) : skillInfo.tags;
+    const newCategory = metadata.category || skillInfo.category;
+    const newOwner = metadata.owner || skillInfo.owner;
+    const newApprovalLevel = metadata.approval_level || skillInfo.approval_level;
+
+    // Step 6: Update skill record
+    this.logger.info('Step 6: Updating skill record in database');
+    await this.updateSkillRecord(skillInfo.id, {
+      version: options.newVersion,
+      content_hash: newHash,
+      content_path: options.updatePath,
+      tags: newTags,
+      category: newCategory,
+      owner: newOwner,
+      approval_level: newApprovalLevel,
+    });
+    this.logger.success('Skill record updated with refreshed metadata');
+
+    // Step 7: Record approval history
+    this.logger.info('Step 7: Recording approval history');
+    await this.recordApprovalHistory(skillInfo.id, options.newVersion, changeType);
+    this.logger.success('Approval history recorded');
+
+    // Step 8: Notify affected agents (optional)
+    let affectedAgents: string[] = [];
+    if (options.notifyAgents || options.enableAgentNotifications) {
+      this.logger.info('Step 8: Notifying affected agents');
+      affectedAgents = await this.notifyAffectedAgents(skillInfo.id, options.skillName);
+    } else {
+      this.logger.info('Step 8: Agent notification disabled (skipping)');
+    }
+
+    // Success summary
+    this.logger.info('==========================================');
+    this.logger.success('Skill Update Propagated Successfully');
+    this.logger.info('==========================================');
+    this.logger.info(`Skill Name: ${options.skillName}`);
+    this.logger.info(`Version: ${skillInfo.version} → ${options.newVersion}`);
+    this.logger.info(`Change Type: ${changeType}`);
+    this.logger.info(`Content Hash: ${newHash.substring(0, 16)}...`);
+    this.logger.info(`Update Path: ${options.updatePath}`);
+    this.logger.info('Metadata Refreshed: Yes');
+    this.logger.info(`  Tags: ${newTags}`);
+    this.logger.info(`  Category: ${newCategory}`);
+    this.logger.info(`  Owner: ${newOwner}`);
+    this.logger.info(`  Approval Level: ${newApprovalLevel}`);
+    this.logger.info('==========================================');
+
+    return {
+      success: true,
+      skillName: options.skillName,
+      newVersion: options.newVersion,
+      oldVersion: skillInfo.version,
+      changeType: VersionManager.compareVersions(skillInfo.version, options.newVersion),
+      contentHash: newHash,
+      metadata: {
+        tags: newTags,
+        category: newCategory,
+        owner: newOwner,
+        approval_level: newApprovalLevel,
+      },
+      affectedAgents,
+      timestamp: startTime,
+    };
+  }
+
+  /**
+   * Retrieve skill info from database
+   */
+  private async getSkillInfo(skillName: string) {
+    const result = await this.db.selectOne(
+      'SELECT id, version, content_hash, content_path, tags, category, owner, approval_level FROM skills WHERE name = ?1',
+      [skillName]
+    );
+
+    if (!result) {
+      return null;
+    }
+
+    // Handle different result formats
+    if (Array.isArray(result)) {
+      return {
+        id: result[0],
+        version: result[1],
+        content_hash: result[2],
+        content_path: result[3],
+        tags: result[4],
+        category: result[5],
+        owner: result[6],
+        approval_level: result[7],
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * Update skill record in database
+   */
+  private async updateSkillRecord(
+    skillId: number,
+    updates: Record<string, any>
+  ): Promise<void> {
+    const setClauses = Object.keys(updates)
+      .map((key) => `${key} = ?`)
+      .join(', ');
+
+    const values = Object.values(updates);
+    values.push(skillId);
+
+    const sql = `UPDATE skills SET ${setClauses}, updated_at = datetime('now') WHERE id = ?`;
+
+    await this.db.execute(sql, values);
+  }
+
+  /**
+   * Record approval history entry
+   */
+  private async recordApprovalHistory(
+    skillId: number,
+    newVersion: string,
+    changeType: string
+  ): Promise<void> {
+    const metadata = JSON.stringify({
+      change_type: changeType,
+      source: 'propagate-skill-update',
+      propagated_at: new Date().toISOString(),
+    });
+
+    const sql = `
+      INSERT INTO approval_history (
+        skill_id,
+        version,
+        approval_level,
+        approver,
+        decision,
+        reasoning,
+        approval_criteria_check,
+        timestamp
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?, ?, datetime('now')
+      )
+    `;
+
+    const reasoning = 'Skill update propagated through automated workflow';
+
+    await this.db.execute(sql, [
+      skillId,
+      newVersion,
+      'auto',
+      'propagate-skill-update',
+      'approved',
+      reasoning,
+      metadata,
+    ]);
+  }
+
+  /**
+   * Get and notify affected agents
+   */
+  private async notifyAffectedAgents(skillId: number, skillName: string): Promise<string[]> {
+    const agents = await this.db.getAffectedAgents(skillId);
+
+    if (agents.length === 0) {
+      this.logger.info('No agents using this skill');
+      return [];
+    }
+
+    this.logger.info(`Agents using this skill (${agents.length}):`);
+    for (const agent of agents) {
+      this.logger.info(`  - ${agent}`);
+    }
+
+    this.logger.success(`Notification: Skill '${skillName}' has been updated`);
+    this.logger.info('Affected agents should reload skill content on next invocation');
+
+    return agents;
+  }
+}

package/claude-assets/skills/cfn-skill-propagation/src/skill-validator.ts

@@ -0,0 +1,179 @@
+/**
+ * Skill Validator - validates skill structure, metadata, and parameters
+ */
+
+import type {
+  SkillValidator as ISkillValidator,
+  ValidationResult,
+  SkillPropagationOptions,
+  FileSystemAdapter,
+  DatabaseAdapter,
+} from './types';
+import { VersionManager } from './version-manager';
+
+export class SkillValidator implements ISkillValidator {
+  constructor(
+    private fs: FileSystemAdapter,
+    private db: DatabaseAdapter
+  ) {}
+
+  /**
+   * Validate all input parameters
+   */
+  async validateParameters(options: SkillPropagationOptions): Promise<ValidationResult> {
+    const errors: string[] = [];
+
+    // Validate required fields
+    if (!options.skillName || options.skillName.trim().length === 0) {
+      errors.push('Missing required parameter: skillName');
+    }
+
+    if (!options.newVersion || options.newVersion.trim().length === 0) {
+      errors.push('Missing required parameter: newVersion');
+    }
+
+    if (!options.updatePath || options.updatePath.trim().length === 0) {
+      errors.push('Missing required parameter: updatePath');
+    }
+
+    // Validate skill name format (alphanumeric, hyphens, underscores)
+    if (options.skillName && !/^[a-zA-Z0-9_-]+$/.test(options.skillName)) {
+      errors.push(`Invalid skill name: ${options.skillName}. Use only alphanumeric, hyphens, and underscores.`);
+    }
+
+    // Validate version format
+    if (options.newVersion && !VersionManager.isValidVersion(options.newVersion)) {
+      errors.push(
+        `Invalid version format: ${options.newVersion}. Expected format: MAJOR.MINOR.PATCH (e.g., 1.0.0)`
+      );
+    }
+
+    // Validate change type
+    if (options.changeType && !['patch', 'minor', 'major'].includes(options.changeType)) {
+      errors.push(`Invalid changeType: ${options.changeType}. Must be one of: patch, minor, major`);
+    }
+
+    // Validate file exists and is readable
+    if (options.updatePath) {
+      const exists = await this.fs.fileExists(options.updatePath);
+      if (!exists) {
+        errors.push(`Update file not found: ${options.updatePath}`);
+      }
+
+      const readable = await this.fs.isReadable(options.updatePath);
+      if (!readable) {
+        errors.push(`Update file is not readable: ${options.updatePath}`);
+      }
+    }
+
+    // Validate database exists
+    const dbExists = await this.fs.fileExists(options.databasePath || './.claude/skills-database/skills.db');
+    if (!dbExists) {
+      errors.push(`Skills database not found: ${options.databasePath}`);
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Check if skill exists in database
+   */
+  async validateSkillExists(skillName: string): Promise<boolean> {
+    try {
+      const result = await this.db.selectOne(
+        'SELECT COUNT(*) as count FROM skills WHERE name = ?1',
+        [skillName]
+      );
+
+      return result && (result.count > 0 || result.value > 0);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Validate version increment matches expected change type
+   */
+  async validateVersionIncrement(
+    currentVersion: string,
+    newVersion: string,
+    expectedChangeType: 'patch' | 'minor' | 'major'
+  ): Promise<ValidationResult> {
+    const errors: string[] = [];
+
+    const result = VersionManager.validateVersionIncrement(
+      currentVersion,
+      newVersion,
+      expectedChangeType
+    );
+
+    if (!result.isValid) {
+      const changeType = result.changeType;
+
+      switch (changeType) {
+        case 'same':
+          errors.push(`Version unchanged: ${currentVersion} → ${newVersion}`);
+          break;
+
+        case 'downgrade':
+          errors.push(`Version downgrade not allowed: ${currentVersion} → ${newVersion}`);
+          break;
+
+        case 'major':
+        case 'minor':
+        case 'patch':
+          if (changeType !== expectedChangeType) {
+            errors.push(
+              `Version change type mismatch: detected ${changeType}, but expected ${expectedChangeType} ` +
+              `(version: ${currentVersion} → ${newVersion})`
+            );
+          }
+          break;
+
+        default:
+          errors.push(`Invalid version comparison result: ${changeType}`);
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Validate skill structure (must have SKILL.md)
+   */
+  async validateSkillStructure(skillPath: string): Promise<ValidationResult> {
+    const errors: string[] = [];
+
+    const skillMdExists = await this.fs.fileExists(`${skillPath}/SKILL.md`);
+    if (!skillMdExists) {
+      errors.push(`SKILL.md not found in ${skillPath}`);
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Validate content hash changed
+   */
+  validateContentHashChanged(oldHash: string, newHash: string): ValidationResult {
+    const errors: string[] = [];
+
+    if (oldHash === newHash) {
+      errors.push('Content hash unchanged - no actual content changes detected');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}