@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/scripts/deprecate-skill.js

@@ -0,0 +1,610 @@
+#!/usr/bin/env node
+/**
+ * Skill Deprecation Script
+ *
+ * Safely deprecates skills with full lifecycle management.
+ * Updates versions.json, creates migration guide template, and updates CHANGELOG.
+ *
+ * Usage:
+ *   npm run skill:deprecate <skill-name>
+ *   npm run skill:deprecate <skill-name> --superseded-by <replacement>
+ *   npm run skill:deprecate <skill-name> --removal-target 2.0.0 --reason "Low effectiveness"
+ *   npm run skill:deprecate <skill-name> --dry-run
+ *
+ * Options:
+ *   --superseded-by   Replacement skill name
+ *   --removal-target  Version when skill will be removed (required)
+ *   --reason          Reason for deprecation
+ *   --dry-run         Show what would be done without making changes
+ *   --force           Skip confirmation prompts
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Paths
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
+const VERSIONS_FILE = path.join(PLUGIN_ROOT, 'config', 'versions.json');
+const CHANGELOG_FILE = path.join(PLUGIN_ROOT, 'CHANGELOG.md');
+const SKILLS_DIR = path.join(PLUGIN_ROOT, 'skills');
+
+/**
+ * Parse command line arguments.
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    skillName: null,
+    supersededBy: null,
+    removalTarget: null,
+    reason: null,
+    dryRun: false,
+    force: false,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--force') {
+      options.force = true;
+    } else if (arg === '--superseded-by' && args[i + 1]) {
+      options.supersededBy = args[++i];
+    } else if (arg.startsWith('--superseded-by=')) {
+      options.supersededBy = arg.split('=')[1];
+    } else if (arg === '--removal-target' && args[i + 1]) {
+      options.removalTarget = args[++i];
+    } else if (arg.startsWith('--removal-target=')) {
+      options.removalTarget = arg.split('=')[1];
+    } else if (arg === '--reason' && args[i + 1]) {
+      options.reason = args[++i];
+    } else if (arg.startsWith('--reason=')) {
+      options.reason = arg.split('=')[1];
+    } else if (!arg.startsWith('-') && !options.skillName) {
+      options.skillName = arg;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Show help message.
+ */
+function showHelp() {
+  console.log(`
+Skill Deprecation Tool
+
+Usage:
+  npm run skill:deprecate <skill-name> [options]
+
+Options:
+  --superseded-by <skill>   Replacement skill name
+  --removal-target <ver>    Version when skill will be removed (e.g., 2.0.0)
+  --reason <text>           Reason for deprecation
+  --dry-run                 Show what would be done without making changes
+  --force                   Skip confirmation prompts
+
+Examples:
+  npm run skill:deprecate old-patterns
+  npm run skill:deprecate old-patterns --superseded-by new-patterns
+  npm run skill:deprecate old-patterns --removal-target 2.0.0 --reason "Low effectiveness"
+  npm run skill:deprecate old-patterns --dry-run
+`);
+}
+
+/**
+ * Load version registry.
+ */
+function loadVersionRegistry() {
+  try {
+    if (fs.existsSync(VERSIONS_FILE)) {
+      return JSON.parse(fs.readFileSync(VERSIONS_FILE, 'utf8'));
+    }
+  } catch (err) {
+    console.error(`[Deprecate] Error loading versions.json: ${err.message}`);
+  }
+  return null;
+}
+
+/**
+ * Save version registry.
+ */
+function saveVersionRegistry(registry) {
+  fs.writeFileSync(VERSIONS_FILE, JSON.stringify(registry, null, 2) + '\n');
+}
+
+/**
+ * Validate skill exists.
+ */
+function validateSkill(skillName, registry) {
+  const errors = [];
+
+  // Check if skill exists in registry
+  if (!registry.skills[skillName]) {
+    errors.push(`Skill "${skillName}" not found in versions.json`);
+    return { valid: false, errors };
+  }
+
+  const skillInfo = registry.skills[skillName];
+
+  // Check if already deprecated
+  if (skillInfo.status === 'deprecated') {
+    errors.push(`Skill "${skillName}" is already deprecated`);
+    return { valid: false, errors };
+  }
+
+  // Check if archived
+  if (skillInfo.status === 'archived') {
+    errors.push(`Skill "${skillName}" is already archived`);
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [], skillInfo };
+}
+
+/**
+ * Validate replacement skill exists.
+ */
+function validateReplacement(replacementName, registry) {
+  if (!replacementName) return { valid: true };
+
+  if (!registry.skills[replacementName]) {
+    return { valid: false, error: `Replacement skill "${replacementName}" not found` };
+  }
+
+  const replacement = registry.skills[replacementName];
+  if (replacement.status === 'deprecated' || replacement.status === 'archived') {
+    return {
+      valid: false,
+      error: `Replacement skill "${replacementName}" is ${replacement.status}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate semver version.
+ */
+function validateVersion(version, currentVersion) {
+  if (!version) return { valid: false, error: 'Removal target version is required' };
+
+  const semverPattern = /^\d+\.\d+\.\d+$/;
+  if (!semverPattern.test(version)) {
+    return {
+      valid: false,
+      error: `Invalid version format: "${version}". Use semver (e.g., 2.0.0)`,
+    };
+  }
+
+  // Compare versions (simple comparison)
+  const current = currentVersion.split('.').map(Number);
+  const target = version.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    if (target[i] > current[i]) return { valid: true };
+    if (target[i] < current[i]) {
+      return {
+        valid: false,
+        error: `Removal target ${version} must be greater than current version ${currentVersion}`,
+      };
+    }
+  }
+
+  return {
+    valid: false,
+    error: `Removal target ${version} must be greater than current version ${currentVersion}`,
+  };
+}
+
+/**
+ * Check for dependencies on this skill.
+ */
+function checkDependencies(skillName, registry) {
+  const dependents = [];
+
+  // Check if any other skills reference this skill
+  // This is a simple check - in production you might parse skill files
+  for (const [name, info] of Object.entries(registry.skills)) {
+    if (name === skillName) continue;
+    if (info.status === 'deprecated' || info.status === 'archived') continue;
+
+    // Check if skill file references the deprecated skill
+    const skillDir = path.join(SKILLS_DIR, name);
+    const skillFile = path.join(skillDir, 'SKILL.md');
+
+    if (fs.existsSync(skillFile)) {
+      try {
+        const content = fs.readFileSync(skillFile, 'utf8');
+        if (content.includes(skillName)) {
+          dependents.push(name);
+        }
+      } catch (e) {
+        // Ignore read errors
+      }
+    }
+  }
+
+  return dependents;
+}
+
+/**
+ * Update versions.json with deprecation info.
+ */
+function updateVersionRegistry(skillName, deprecationInfo, registry) {
+  const skill = registry.skills[skillName];
+
+  skill.status = 'deprecated';
+  skill.deprecationInfo = {
+    deprecated: true,
+    deprecatedIn: registry.version,
+    deprecatedAt: new Date().toISOString().split('T')[0],
+    removalTarget: deprecationInfo.removalTarget,
+    supersededBy: deprecationInfo.supersededBy || null,
+    reason: deprecationInfo.reason || 'No longer recommended',
+    migrationGuide: deprecationInfo.migrationGuide || null,
+  };
+  skill.lastUpdated = new Date().toISOString().split('T')[0];
+
+  return registry;
+}
+
+/**
+ * Create migration guide template.
+ */
+function createMigrationGuide(skillName, deprecationInfo) {
+  const skillDir = path.join(SKILLS_DIR, skillName);
+  const migrationFile = path.join(skillDir, 'MIGRATION.md');
+
+  // Check if skill directory exists
+  if (!fs.existsSync(skillDir)) {
+    return null;
+  }
+
+  const template = `# Migration Guide: ${skillName}
+
+## Deprecation Notice
+
+**Status:** Deprecated
+**Deprecated In:** v${deprecationInfo.deprecatedIn}
+**Removal Target:** v${deprecationInfo.removalTarget}
+${deprecationInfo.supersededBy ? `**Replacement:** ${deprecationInfo.supersededBy}` : ''}
+${deprecationInfo.reason ? `**Reason:** ${deprecationInfo.reason}` : ''}
+
+---
+
+## Migration Steps
+
+${
+  deprecationInfo.supersededBy
+    ? `
+### 1. Identify Usage
+
+Search your codebase for references to \`${skillName}\`:
+
+\`\`\`bash
+grep -r "${skillName}" ~/.claude/
+\`\`\`
+
+### 2. Update References
+
+Replace \`${skillName}\` with \`${deprecationInfo.supersededBy}\` in your configuration.
+
+### 3. Review Differences
+
+Key differences between ${skillName} and ${deprecationInfo.supersededBy}:
+
+- [ ] Document difference 1
+- [ ] Document difference 2
+- [ ] Document difference 3
+
+### 4. Test
+
+Verify that the replacement skill works correctly in your environment.
+`
+    : `
+### 1. Identify Usage
+
+Search your codebase for references to \`${skillName}\`:
+
+\`\`\`bash
+grep -r "${skillName}" ~/.claude/
+\`\`\`
+
+### 2. Alternative Approaches
+
+No direct replacement is available. Consider these alternatives:
+
+- [ ] Alternative approach 1
+- [ ] Alternative approach 2
+- [ ] Manual implementation
+`
+}
+
+---
+
+## Timeline
+
+| Milestone | Date | Action |
+|-----------|------|--------|
+| Deprecation | ${new Date().toISOString().split('T')[0]} | Deprecation warnings begin |
+| Migration Period | 6 months | Users migrate to ${deprecationInfo.supersededBy || 'alternatives'} |
+| Removal | v${deprecationInfo.removalTarget} | Skill removed from system |
+
+---
+
+## Support
+
+If you need help with migration:
+
+1. Check the ${deprecationInfo.supersededBy ? `${deprecationInfo.supersededBy} skill documentation` : 'quarterly review documentation'}
+2. Run \`/skill-gaps\` to identify alternative patterns
+3. Contact the CloudStream team for assistance
+
+---
+
+*Generated by CloudStream Claude Code Deprecation Tool*
+`;
+
+  fs.writeFileSync(migrationFile, template);
+  return migrationFile;
+}
+
+/**
+ * Update CHANGELOG.md with deprecation entry.
+ */
+function updateChangelog(skillName, deprecationInfo) {
+  if (!fs.existsSync(CHANGELOG_FILE)) {
+    console.log('[Deprecate] Warning: CHANGELOG.md not found');
+    return null;
+  }
+
+  const content = fs.readFileSync(CHANGELOG_FILE, 'utf8');
+  const lines = content.split('\n');
+
+  // Find the first version section
+  let insertIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith('## [')) {
+      insertIndex = i + 1;
+      break;
+    }
+  }
+
+  if (insertIndex === -1) {
+    console.log('[Deprecate] Warning: Could not find version section in CHANGELOG.md');
+    return null;
+  }
+
+  // Find or create Deprecated section
+  let deprecatedIndex = -1;
+  for (let i = insertIndex; i < lines.length; i++) {
+    if (lines[i].startsWith('## [')) break; // Next version section
+    if (lines[i].startsWith('### Deprecated')) {
+      deprecatedIndex = i;
+      break;
+    }
+  }
+
+  const deprecationEntry = `- \`${skillName}\` deprecated - ${deprecationInfo.supersededBy ? `use \`${deprecationInfo.supersededBy}\` instead` : deprecationInfo.reason || 'no longer recommended'}. Removal target: v${deprecationInfo.removalTarget}`;
+
+  if (deprecatedIndex !== -1) {
+    // Add to existing Deprecated section
+    lines.splice(deprecatedIndex + 2, 0, deprecationEntry);
+  } else {
+    // Create new Deprecated section after existing sections
+    let lastSectionEnd = insertIndex;
+    for (let i = insertIndex; i < lines.length; i++) {
+      if (lines[i].startsWith('## [')) break;
+      if (lines[i].startsWith('### ')) lastSectionEnd = i;
+    }
+
+    // Find end of last section
+    for (let i = lastSectionEnd + 1; i < lines.length; i++) {
+      if (lines[i].startsWith('## [') || lines[i].startsWith('### ')) break;
+      lastSectionEnd = i;
+    }
+
+    const newSection = ['', '### Deprecated', '', deprecationEntry];
+    lines.splice(lastSectionEnd + 1, 0, ...newSection);
+  }
+
+  fs.writeFileSync(CHANGELOG_FILE, lines.join('\n'));
+  return CHANGELOG_FILE;
+}
+
+/**
+ * Prompt for confirmation.
+ */
+async function confirm(message) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N): `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Output deprecation checklist.
+ */
+function outputChecklist(skillName, deprecationInfo, results) {
+  console.log('');
+  console.log('='.repeat(50));
+  console.log('  DEPRECATION CHECKLIST');
+  console.log('='.repeat(50));
+  console.log('');
+  console.log(`Skill: ${skillName}`);
+  console.log(`Status: DEPRECATED`);
+  console.log(`Removal Target: v${deprecationInfo.removalTarget}`);
+  if (deprecationInfo.supersededBy) {
+    console.log(`Replacement: ${deprecationInfo.supersededBy}`);
+  }
+  console.log('');
+  console.log('Completed Actions:');
+  console.log(`  [x] Updated versions.json`);
+  console.log(`  [${results.migrationGuide ? 'x' : ' '}] Created migration guide`);
+  console.log(`  [${results.changelog ? 'x' : ' '}] Updated CHANGELOG.md`);
+  console.log('');
+  console.log('Manual Steps Required:');
+  console.log('  [ ] Review and complete migration guide');
+  console.log('  [ ] Test deprecation warnings appear');
+  console.log('  [ ] Notify team of deprecation');
+  console.log('  [ ] Update onboarding materials if needed');
+  console.log('');
+  if (results.migrationGuide) {
+    console.log(`Migration guide: ${results.migrationGuide}`);
+  }
+  console.log('');
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  const options = parseArgs();
+
+  if (options.help) {
+    showHelp();
+    return;
+  }
+
+  if (!options.skillName) {
+    console.error('[Deprecate] Error: Skill name is required');
+    console.log('Run with --help for usage information');
+    process.exit(1);
+  }
+
+  // Load registry
+  const registry = loadVersionRegistry();
+  if (!registry) {
+    console.error('[Deprecate] Error: Could not load versions.json');
+    process.exit(1);
+  }
+
+  // Validate skill
+  const validation = validateSkill(options.skillName, registry);
+  if (!validation.valid) {
+    console.error(`[Deprecate] Error: ${validation.errors.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Validate replacement if provided
+  if (options.supersededBy) {
+    const replacementValidation = validateReplacement(options.supersededBy, registry);
+    if (!replacementValidation.valid) {
+      console.error(`[Deprecate] Error: ${replacementValidation.error}`);
+      process.exit(1);
+    }
+  }
+
+  // Default removal target if not provided
+  if (!options.removalTarget) {
+    // Increment major version
+    const parts = registry.version.split('.');
+    options.removalTarget = `${parseInt(parts[0], 10) + 1}.0.0`;
+    console.log(`[Deprecate] Using default removal target: v${options.removalTarget}`);
+  }
+
+  // Validate version
+  const versionValidation = validateVersion(options.removalTarget, registry.version);
+  if (!versionValidation.valid) {
+    console.error(`[Deprecate] Error: ${versionValidation.error}`);
+    process.exit(1);
+  }
+
+  // Check dependencies
+  const dependents = checkDependencies(options.skillName, registry);
+  if (dependents.length > 0) {
+    console.log('');
+    console.log('[Deprecate] Warning: The following skills reference this skill:');
+    for (const dep of dependents) {
+      console.log(`  - ${dep}`);
+    }
+    console.log('');
+  }
+
+  // Show what will be done
+  console.log('');
+  console.log('[Deprecate] Deprecation Summary:');
+  console.log(`  Skill:          ${options.skillName}`);
+  console.log(`  Current Status: ${validation.skillInfo.status}`);
+  console.log(`  New Status:     deprecated`);
+  console.log(`  Removal Target: v${options.removalTarget}`);
+  if (options.supersededBy) {
+    console.log(`  Replacement:    ${options.supersededBy}`);
+  }
+  if (options.reason) {
+    console.log(`  Reason:         ${options.reason}`);
+  }
+  console.log('');
+
+  // Dry run check
+  if (options.dryRun) {
+    console.log('[Deprecate] Dry run - no changes made');
+    return;
+  }
+
+  // Confirm unless forced
+  if (!options.force) {
+    const confirmed = await confirm('Proceed with deprecation?');
+    if (!confirmed) {
+      console.log('[Deprecate] Cancelled');
+      return;
+    }
+  }
+
+  // Execute deprecation
+  const deprecationInfo = {
+    deprecatedIn: registry.version,
+    removalTarget: options.removalTarget,
+    supersededBy: options.supersededBy,
+    reason: options.reason,
+  };
+
+  const results = {
+    versionsUpdated: false,
+    migrationGuide: null,
+    changelog: null,
+  };
+
+  // Update versions.json
+  const updatedRegistry = updateVersionRegistry(options.skillName, deprecationInfo, registry);
+  saveVersionRegistry(updatedRegistry);
+  results.versionsUpdated = true;
+  console.log('[Deprecate] Updated versions.json');
+
+  // Create migration guide
+  const migrationPath = `skills/${options.skillName}/MIGRATION.md`;
+  deprecationInfo.migrationGuide = migrationPath;
+  results.migrationGuide = createMigrationGuide(options.skillName, deprecationInfo);
+  if (results.migrationGuide) {
+    console.log(`[Deprecate] Created migration guide: ${results.migrationGuide}`);
+  }
+
+  // Update CHANGELOG
+  results.changelog = updateChangelog(options.skillName, deprecationInfo);
+  if (results.changelog) {
+    console.log('[Deprecate] Updated CHANGELOG.md');
+  }
+
+  // Output checklist
+  outputChecklist(options.skillName, deprecationInfo, results);
+}
+
+// Run
+main().catch((err) => {
+  console.error('[Deprecate] Error:', err.message);
+  process.exit(1);
+});