agileflow 3.4.3 → 4.0.0-alpha.1

package/scripts/lib/skill-recommender.js

@@ -1,311 +0,0 @@
-#!/usr/bin/env node
-/**
- * skill-recommender.js
- *
- * Tech stack detector + recommendation engine for skills.
- * Reads package.json (or other project files) to detect the framework,
- * styling, testing, database, and language. Maps detected stack to
- * curated skills from skills.sh.
- *
- * Follows the signal-detectors.js pattern (detector functions returning recommendations).
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { getAllCuratedSkills } = require('./skill-catalog');
-
-// =============================================================================
-// Tech Stack Detection
-// =============================================================================
-
-/**
- * Detect project tech stack from package.json and project files.
- * @param {string} projectRoot - Project root directory
- * @returns {Object} Detected stack with categories
- */
-function detectTechStack(projectRoot) {
-  const stack = {
-    frameworks: [],
-    styling: [],
-    testing: [],
-    databases: [],
-    languages: [],
-    devops: [],
-    security: [],
-  };
-
-  // Read package.json
-  const pkgPath = path.join(projectRoot, 'package.json');
-  let pkg = null;
-  if (fs.existsSync(pkgPath)) {
-    try {
-      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    } catch {
-      // Ignore parse errors
-    }
-  }
-
-  if (pkg) {
-    const allDeps = {
-      ...pkg.dependencies,
-      ...pkg.devDependencies,
-    };
-
-    // Framework detection
-    if (allDeps.next) stack.frameworks.push('next', 'react');
-    else if (allDeps.react) stack.frameworks.push('react');
-    if (allDeps.vue || allDeps['vue-router']) stack.frameworks.push('vue');
-    if (allDeps.svelte || allDeps['@sveltejs/kit']) stack.frameworks.push('svelte', 'sveltekit');
-    if (allDeps['@angular/core']) stack.frameworks.push('angular');
-    if (allDeps.express) stack.frameworks.push('express', 'node');
-    if (allDeps.fastify) stack.frameworks.push('fastify', 'node');
-    if (allDeps.hono) stack.frameworks.push('hono', 'node');
-    if (allDeps['react-native'] || allDeps.expo) stack.frameworks.push('react-native', 'mobile');
-    if (allDeps.nuxt) stack.frameworks.push('nuxt', 'vue');
-    if (allDeps.astro) stack.frameworks.push('astro');
-    if (allDeps.remix || allDeps['@remix-run/react']) stack.frameworks.push('remix', 'react');
-
-    // Styling detection
-    if (allDeps.tailwindcss) stack.styling.push('tailwind', 'tailwindcss');
-    if (allDeps['styled-components']) stack.styling.push('styled-components');
-    if (allDeps['@emotion/react']) stack.styling.push('emotion');
-    if (allDeps.sass) stack.styling.push('sass');
-
-    // Testing detection
-    if (allDeps.jest) stack.testing.push('jest');
-    if (allDeps.vitest) stack.testing.push('vitest', 'vite');
-    if (allDeps.playwright || allDeps['@playwright/test']) stack.testing.push('playwright', 'e2e');
-    if (allDeps.cypress) stack.testing.push('cypress', 'e2e');
-    if (allDeps.mocha) stack.testing.push('mocha');
-
-    // Database detection
-    if (allDeps.prisma || allDeps['@prisma/client']) stack.databases.push('prisma', 'orm');
-    if (allDeps['@supabase/supabase-js']) stack.databases.push('supabase', 'postgres');
-    if (allDeps.mongoose || allDeps.mongodb) stack.databases.push('mongodb', 'nosql');
-    if (allDeps.pg || allDeps.postgres) stack.databases.push('postgresql', 'postgres');
-    if (allDeps.redis || allDeps.ioredis) stack.databases.push('redis', 'cache');
-    if (allDeps.drizzle || allDeps['drizzle-orm']) stack.databases.push('drizzle', 'orm');
-    if (allDeps.knex) stack.databases.push('knex', 'sql');
-    if (allDeps.sequelize) stack.databases.push('sequelize', 'orm');
-    if (allDeps.typeorm) stack.databases.push('typeorm', 'orm');
-
-    // Language detection
-    if (allDeps.typescript) stack.languages.push('typescript', 'ts');
-    if (allDeps['@apollo/server'] || allDeps['@apollo/client'] || allDeps.graphql) {
-      stack.frameworks.push('graphql', 'apollo');
-    }
-
-    // DevOps detection
-    if (allDeps.docker || fs.existsSync(path.join(projectRoot, 'Dockerfile'))) {
-      stack.devops.push('docker', 'containers');
-    }
-    if (fs.existsSync(path.join(projectRoot, '.github', 'workflows'))) {
-      stack.devops.push('github-actions', 'ci');
-    }
-    if (allDeps['socket.io'] || allDeps.ws) stack.frameworks.push('websocket', 'real-time');
-  }
-
-  // Python detection
-  const pyFiles = ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'];
-  for (const f of pyFiles) {
-    if (fs.existsSync(path.join(projectRoot, f))) {
-      stack.languages.push('python');
-
-      // Check for specific Python frameworks
-      try {
-        const content = fs.readFileSync(path.join(projectRoot, f), 'utf8');
-        if (content.includes('fastapi')) stack.frameworks.push('fastapi', 'python');
-        if (content.includes('django')) stack.frameworks.push('django', 'python');
-        if (content.includes('flask')) stack.frameworks.push('flask', 'python');
-        if (content.includes('pytest')) stack.testing.push('pytest');
-        if (content.includes('pydantic')) stack.frameworks.push('pydantic');
-      } catch {
-        // Ignore read errors
-      }
-      break;
-    }
-  }
-
-  // Go detection
-  if (fs.existsSync(path.join(projectRoot, 'go.mod'))) {
-    stack.languages.push('go', 'golang');
-    stack.frameworks.push('go-backend');
-  }
-
-  // PHP detection
-  if (fs.existsSync(path.join(projectRoot, 'composer.json'))) {
-    stack.languages.push('php');
-  }
-
-  // Docker/K8s detection
-  if (fs.existsSync(path.join(projectRoot, 'Dockerfile'))) {
-    stack.devops.push('docker');
-  }
-  if (
-    fs.existsSync(path.join(projectRoot, 'k8s')) ||
-    fs.existsSync(path.join(projectRoot, 'kubernetes'))
-  ) {
-    stack.devops.push('kubernetes', 'k8s');
-  }
-  if (
-    fs.existsSync(path.join(projectRoot, 'terraform')) ||
-    fs.existsSync(path.join(projectRoot, 'main.tf'))
-  ) {
-    stack.devops.push('terraform', 'iac');
-  }
-  if (fs.existsSync(path.join(projectRoot, 'vercel.json'))) {
-    stack.devops.push('vercel', 'deployment');
-  }
-
-  // Deduplicate all arrays
-  for (const key of Object.keys(stack)) {
-    stack[key] = [...new Set(stack[key])];
-  }
-
-  return stack;
-}
-
-// =============================================================================
-// Recommendation Engine
-// =============================================================================
-
-/**
- * Score a skill against detected tech stack.
- * @param {Object} skill - Curated skill entry
- * @param {Object} stack - Detected tech stack
- * @returns {number} Relevance score (0-100)
- */
-function scoreSkill(skill, stack) {
-  const allTags = [
-    ...stack.frameworks,
-    ...stack.styling,
-    ...stack.testing,
-    ...stack.databases,
-    ...stack.languages,
-    ...stack.devops,
-    ...stack.security,
-  ];
-
-  if (allTags.length === 0) return 0;
-
-  let matchCount = 0;
-  for (const tag of skill.tags) {
-    if (allTags.includes(tag)) {
-      matchCount++;
-    }
-  }
-
-  if (matchCount === 0) return 0;
-
-  // Score: percentage of skill tags that match, weighted by total matches
-  const tagCoverage = matchCount / skill.tags.length;
-  return Math.round(tagCoverage * 100);
-}
-
-/**
- * Get skill recommendations based on detected tech stack.
- * @param {string} projectRoot - Project root directory
- * @param {Object} [options] - Options
- * @param {string[]} [options.installedSkills] - Names of already-installed skills to filter out
- * @param {number} [options.minScore] - Minimum relevance score (default: 20)
- * @param {number} [options.maxResults] - Maximum results per category (default: 5)
- * @returns {Object} Recommendations with stack info and ranked skills
- */
-function getRecommendations(projectRoot, options = {}) {
-  const { installedSkills = [], minScore = 20, maxResults = 5 } = options;
-
-  const stack = detectTechStack(projectRoot);
-  const allSkills = getAllCuratedSkills();
-  const installedSet = new Set(installedSkills.map(n => n.toLowerCase()));
-
-  // Score all skills
-  const scored = allSkills
-    .map(skill => ({
-      ...skill,
-      score: scoreSkill(skill, stack),
-      installed: installedSet.has(skill.name.toLowerCase()),
-    }))
-    .filter(s => s.score >= minScore && !s.installed)
-    .sort((a, b) => b.score - a.score);
-
-  // Group by category with limits
-  const byCategory = {};
-  for (const skill of scored) {
-    if (!byCategory[skill.category]) {
-      byCategory[skill.category] = [];
-    }
-    if (byCategory[skill.category].length < maxResults) {
-      byCategory[skill.category].push(skill);
-    }
-  }
-
-  return {
-    stack,
-    recommendations: byCategory,
-    totalMatches: scored.length,
-  };
-}
-
-/**
- * Format recommendations as a display string.
- * @param {Object} result - Result from getRecommendations
- * @returns {string} Formatted display text
- */
-function formatRecommendations(result) {
-  const { stack, recommendations, totalMatches } = result;
-
-  const lines = [];
-
-  // Show detected stack
-  const detected = [];
-  if (stack.frameworks.length) detected.push(`Frameworks: ${stack.frameworks.join(', ')}`);
-  if (stack.languages.length) detected.push(`Languages: ${stack.languages.join(', ')}`);
-  if (stack.databases.length) detected.push(`Databases: ${stack.databases.join(', ')}`);
-  if (stack.testing.length) detected.push(`Testing: ${stack.testing.join(', ')}`);
-  if (stack.styling.length) detected.push(`Styling: ${stack.styling.join(', ')}`);
-  if (stack.devops.length) detected.push(`DevOps: ${stack.devops.join(', ')}`);
-
-  if (detected.length > 0) {
-    lines.push('**Detected Tech Stack:**');
-    for (const d of detected) {
-      lines.push(`- ${d}`);
-    }
-    lines.push('');
-  }
-
-  // Show recommendations by category
-  const categories = Object.keys(recommendations);
-  if (categories.length === 0) {
-    lines.push('No matching skills found for your tech stack.');
-    lines.push('Browse the full marketplace: `npx skills find`');
-    return lines.join('\n');
-  }
-
-  lines.push(`**Recommended Skills (${totalMatches} matches):**`);
-  lines.push('');
-
-  for (const category of categories) {
-    const skills = recommendations[category];
-    lines.push(`### ${category}`);
-    lines.push('');
-    for (const s of skills) {
-      lines.push(`- **${s.name}** (${s.score}% match) - ${s.description}`);
-      lines.push(`  Install: \`${s.installCmd}\``);
-    }
-    lines.push('');
-  }
-
-  lines.push('---');
-  lines.push('Browse more: `npx skills find`');
-
-  return lines.join('\n');
-}
-
-module.exports = {
-  detectTechStack,
-  scoreSkill,
-  getRecommendations,
-  formatRecommendations,
-};

package/scripts/lib/state-migrator.js

@@ -1,353 +0,0 @@
-/**
- * AgileFlow CLI - State Schema Migrator
- *
- * Handles schema versioning and automatic migrations for status.json.
- * Ensures backwards compatibility as the schema evolves.
- *
- * Schema Version History:
- * - 1.0.0: Original schema (no version field)
- * - 2.0.0: Added schema_version field, normalized story structure
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// Import status constants from single source of truth
-const { VALID_STATUSES } = require('./story-state-machine');
-
-// Current schema version
-const CURRENT_SCHEMA_VERSION = '2.0.0';
-
-// Migration log
-let migrationLog = [];
-
-/**
- * Parse semantic version string into components
- * @param {string} version - Version string (e.g., "1.2.3")
- * @returns {{ major: number, minor: number, patch: number }}
- */
-function parseVersion(version) {
-  if (!version || version === 'unknown') {
-    return { major: 1, minor: 0, patch: 0 };
-  }
-  const parts = version.split('.').map(Number);
-  return {
-    major: parts[0] !== undefined && !isNaN(parts[0]) ? parts[0] : 1,
-    minor: parts[1] !== undefined && !isNaN(parts[1]) ? parts[1] : 0,
-    patch: parts[2] !== undefined && !isNaN(parts[2]) ? parts[2] : 0,
-  };
-}
-
-/**
- * Compare two version strings
- * @param {string} v1 - First version
- * @param {string} v2 - Second version
- * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
- */
-function compareVersions(v1, v2) {
-  const p1 = parseVersion(v1);
-  const p2 = parseVersion(v2);
-
-  if (p1.major !== p2.major) return p1.major < p2.major ? -1 : 1;
-  if (p1.minor !== p2.minor) return p1.minor < p2.minor ? -1 : 1;
-  if (p1.patch !== p2.patch) return p1.patch < p2.patch ? -1 : 1;
-  return 0;
-}
-
-/**
- * Detect the schema version of a status.json object
- * @param {Object} data - Parsed status.json data
- * @returns {string} Detected schema version
- */
-function detectSchemaVersion(data) {
-  // Explicit version field
-  if (data.schema_version) {
-    return data.schema_version;
-  }
-
-  // No version field = v1.0.0 (original schema)
-  return '1.0.0';
-}
-
-/**
- * Log a migration action
- * @param {string} message - Migration log message
- */
-function logMigration(message) {
-  const entry = {
-    timestamp: new Date().toISOString(),
-    message,
-  };
-  migrationLog.push(entry);
-}
-
-/**
- * Clear migration log
- */
-function clearMigrationLog() {
-  migrationLog = [];
-}
-
-/**
- * Get migration log
- * @returns {Array} Migration log entries
- */
-function getMigrationLog() {
-  return [...migrationLog];
-}
-
-/**
- * Migration: 1.0.0 -> 2.0.0
- * - Adds schema_version field
- * - Normalizes story status values
- * - Adds migrated_at timestamp
- *
- * @param {Object} data - Status data at v1.0.0
- * @returns {Object} Migrated data at v2.0.0
- */
-function migrate_1_0_0_to_2_0_0(data) {
-  logMigration('Starting migration from 1.0.0 to 2.0.0');
-
-  const migrated = {
-    schema_version: '2.0.0',
-    ...data,
-  };
-
-  // Normalize story status values
-  const statusNormalization = {
-    todo: 'ready',
-    new: 'ready',
-    pending: 'ready',
-    open: 'ready',
-    wip: 'in_progress',
-    working: 'in_progress',
-    in_review: 'in_progress',
-    closed: 'completed',
-    done: 'completed',
-    finished: 'completed',
-    resolved: 'completed',
-  };
-
-  let normalizedCount = 0;
-  if (migrated.stories) {
-    for (const [storyId, story] of Object.entries(migrated.stories)) {
-      if (story.status && statusNormalization[story.status.toLowerCase()]) {
-        const oldStatus = story.status;
-        story.status = statusNormalization[story.status.toLowerCase()];
-        normalizedCount++;
-        logMigration(`Normalized ${storyId} status: ${oldStatus} -> ${story.status}`);
-      }
-    }
-  }
-
-  // Add migration metadata
-  migrated.migrated_at = new Date().toISOString();
-  migrated.migrated_from = '1.0.0';
-
-  logMigration(`Migration to 2.0.0 complete. Normalized ${normalizedCount} story statuses.`);
-
-  return migrated;
-}
-
-/**
- * Registry of migration functions
- * Key: "fromVersion->toVersion"
- */
-const MIGRATIONS = {
-  '1.0.0->2.0.0': migrate_1_0_0_to_2_0_0,
-};
-
-/**
- * Get the migration path from one version to another
- * @param {string} fromVersion - Starting version
- * @param {string} toVersion - Target version
- * @returns {Array<string>} Array of version steps
- */
-function getMigrationPath(fromVersion, toVersion) {
-  // For now, simple direct path
-  // Future: implement graph traversal for multi-step migrations
-  const path = [];
-
-  if (compareVersions(fromVersion, '2.0.0') < 0 && compareVersions(toVersion, '2.0.0') >= 0) {
-    path.push('1.0.0->2.0.0');
-  }
-
-  return path;
-}
-
-/**
- * Migrate status.json data to the current schema version
- * @param {Object} data - Parsed status.json data
- * @param {Object} [options] - Migration options
- * @param {boolean} [options.dryRun=false] - If true, don't modify data
- * @returns {{ data: Object, migrated: boolean, fromVersion: string, toVersion: string, log: Array }}
- */
-function migrate(data, options = {}) {
-  const { dryRun = false } = options;
-
-  clearMigrationLog();
-
-  const fromVersion = detectSchemaVersion(data);
-  const toVersion = CURRENT_SCHEMA_VERSION;
-
-  // Already at current version
-  if (compareVersions(fromVersion, toVersion) >= 0) {
-    return {
-      data,
-      migrated: false,
-      fromVersion,
-      toVersion,
-      log: getMigrationLog(),
-    };
-  }
-
-  logMigration(`Detected schema version: ${fromVersion}`);
-  logMigration(`Target schema version: ${toVersion}`);
-
-  // Get migration path
-  const migrationPath = getMigrationPath(fromVersion, toVersion);
-
-  if (migrationPath.length === 0) {
-    logMigration('No migration path found');
-    return {
-      data,
-      migrated: false,
-      fromVersion,
-      toVersion,
-      log: getMigrationLog(),
-    };
-  }
-
-  let migratedData = dryRun ? JSON.parse(JSON.stringify(data)) : data;
-
-  // Apply each migration in sequence
-  for (const step of migrationPath) {
-    const migrationFn = MIGRATIONS[step];
-    if (!migrationFn) {
-      throw new Error(`Missing migration function for: ${step}`);
-    }
-    logMigration(`Applying migration: ${step}`);
-    migratedData = migrationFn(migratedData);
-  }
-
-  return {
-    data: migratedData,
-    migrated: true,
-    fromVersion,
-    toVersion,
-    log: getMigrationLog(),
-  };
-}
-
-/**
- * Load status.json with automatic migration
- * @param {string} filePath - Path to status.json
- * @param {Object} [options] - Options
- * @param {boolean} [options.autoSave=true] - Automatically save migrated data
- * @returns {{ data: Object, migrated: boolean, fromVersion: string, toVersion: string, log: Array }}
- */
-function loadWithMigration(filePath, options = {}) {
-  const { autoSave = true } = options;
-
-  if (!fs.existsSync(filePath)) {
-    throw new Error(`File not found: ${filePath}`);
-  }
-
-  const content = fs.readFileSync(filePath, 'utf8');
-  let data;
-  try {
-    data = JSON.parse(content);
-  } catch (e) {
-    throw new Error(`Invalid JSON in ${filePath}: ${e.message}`);
-  }
-
-  const result = migrate(data);
-
-  // Auto-save if migration occurred
-  if (result.migrated && autoSave) {
-    const backupPath = `${filePath}.backup.${Date.now()}`;
-    fs.writeFileSync(backupPath, content);
-    logMigration(`Created backup: ${backupPath}`);
-
-    fs.writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
-    logMigration(`Saved migrated data to: ${filePath}`);
-
-    result.log = getMigrationLog();
-  }
-
-  return result;
-}
-
-/**
- * Check if data needs migration
- * @param {Object} data - Parsed status.json data
- * @returns {{ needsMigration: boolean, currentVersion: string, targetVersion: string }}
- */
-function needsMigration(data) {
-  const currentVersion = detectSchemaVersion(data);
-  return {
-    needsMigration: compareVersions(currentVersion, CURRENT_SCHEMA_VERSION) < 0,
-    currentVersion,
-    targetVersion: CURRENT_SCHEMA_VERSION,
-  };
-}
-
-/**
- * Validate migrated data against expected schema
- * @param {Object} data - Data to validate
- * @returns {{ valid: boolean, errors: Array<string> }}
- */
-function validateSchema(data) {
-  const errors = [];
-
-  // Check required fields for v2.0.0
-  if (!data.schema_version) {
-    errors.push('Missing required field: schema_version');
-  }
-
-  // Check stories structure
-  if (data.stories) {
-    for (const [storyId, story] of Object.entries(data.stories)) {
-      if (!story.title) {
-        errors.push(`Story ${storyId} missing required field: title`);
-      }
-      if (!story.status) {
-        errors.push(`Story ${storyId} missing required field: status`);
-      }
-      // Use VALID_STATUSES from story-state-machine.js (single source of truth)
-      if (story.status && !VALID_STATUSES.includes(story.status)) {
-        errors.push(`Story ${storyId} has invalid status: ${story.status}`);
-      }
-    }
-  }
-
-  // Check epics structure
-  if (data.epics) {
-    for (const [epicId, epic] of Object.entries(data.epics)) {
-      if (!epic.title) {
-        errors.push(`Epic ${epicId} missing required field: title`);
-      }
-    }
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-  };
-}
-
-module.exports = {
-  CURRENT_SCHEMA_VERSION,
-  parseVersion,
-  compareVersions,
-  detectSchemaVersion,
-  migrate,
-  loadWithMigration,
-  needsMigration,
-  validateSchema,
-  getMigrationLog,
-  clearMigrationLog,
-  // For testing
-  migrate_1_0_0_to_2_0_0,
-  getMigrationPath,
-};