jettypod 4.3.0 → 4.4.1

package/lib/chore-classifier.js

@@ -0,0 +1,232 @@
+/**
+ * Chore Classifier
+ *
+ * Classifies chore type from title/description using keyword matching.
+ * Maps to the 4 chore types defined in chore-taxonomy.js
+ */
+
+const { CHORE_TYPES, isValidChoreType } = require('./chore-taxonomy');
+
+// Keywords that indicate each chore type
+const TYPE_KEYWORDS = {
+  [CHORE_TYPES.REFACTOR]: [
+    'refactor',
+    'restructure',
+    'reorganize',
+    'extract',
+    'inline',
+    'rename',
+    'move',
+    'split',
+    'consolidate',
+    'simplify',
+    'decouple',
+    'modularize'
+  ],
+  [CHORE_TYPES.DEPENDENCY]: [
+    'update',
+    'upgrade',
+    'bump',
+    'migrate',
+    'dependency',
+    'dependencies',
+    'package',
+    'library',
+    'framework',
+    'version',
+    'security patch',
+    'vulnerability',
+    'npm',
+    'yarn',
+    'lodash',
+    'react',
+    'node'
+  ],
+  [CHORE_TYPES.CLEANUP]: [
+    'cleanup',
+    'clean up',
+    'remove',
+    'delete',
+    'deprecate',
+    'dead code',
+    'unused',
+    'legacy',
+    'obsolete',
+    'prune',
+    'trim'
+  ],
+  [CHORE_TYPES.TOOLING]: [
+    'tooling',
+    'ci',
+    'cd',
+    'pipeline',
+    'build',
+    'lint',
+    'eslint',
+    'prettier',
+    'config',
+    'configuration',
+    'script',
+    'automation',
+    'github action',
+    'workflow',
+    'jest',
+    'test setup'
+  ]
+};
+
+/**
+ * Normalize and validate input text
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description
+ * @returns {string} - Normalized text for classification
+ * @throws {Error} - If title is invalid
+ */
+function normalizeInput(title, description = '') {
+  // Validate title
+  if (title === null || title === undefined) {
+    throw new Error('Chore title is required for classification');
+  }
+  if (typeof title !== 'string') {
+    throw new Error(`Chore title must be a string, got ${typeof title}`);
+  }
+
+  const trimmedTitle = title.trim();
+  if (trimmedTitle.length === 0) {
+    throw new Error('Chore title cannot be empty or whitespace only');
+  }
+
+  // Normalize description (coerce to string if not)
+  const normalizedDesc = description != null ? String(description).trim() : '';
+
+  return `${trimmedTitle} ${normalizedDesc}`.toLowerCase();
+}
+
+/**
+ * Escape special regex characters in a string
+ * @param {string} str - String to escape
+ * @returns {string} - Escaped string safe for regex
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Calculate scores for all chore types
+ * @param {string} text - Normalized text to analyze
+ * @returns {Object} - Scores for each type
+ */
+function calculateScores(text) {
+  const scores = {};
+  for (const [type, keywords] of Object.entries(TYPE_KEYWORDS)) {
+    scores[type] = 0;
+    for (const keyword of keywords) {
+      if (text.includes(keyword.toLowerCase())) {
+        // Exact word match scores higher (escape special chars for safety)
+        const escapedKeyword = escapeRegex(keyword);
+        const wordBoundaryRegex = new RegExp(`\\b${escapedKeyword}\\b`, 'i');
+        if (wordBoundaryRegex.test(text)) {
+          scores[type] += 2;
+        } else {
+          scores[type] += 1;
+        }
+      }
+    }
+  }
+  return scores;
+}
+
+/**
+ * Find the winning type from scores
+ * @param {Object} scores - Scores for each type
+ * @returns {Object} - { type: string, score: number }
+ */
+function findWinningType(scores) {
+  let maxScore = 0;
+  let classifiedType = CHORE_TYPES.REFACTOR; // Default fallback
+
+  for (const [type, score] of Object.entries(scores)) {
+    if (score > maxScore) {
+      maxScore = score;
+      classifiedType = type;
+    }
+  }
+
+  return { type: classifiedType, score: maxScore };
+}
+
+/**
+ * Classify a chore based on its title (and optionally description)
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description for additional context
+ * @returns {string} - One of the 4 chore types
+ * @throws {Error} - If title is invalid
+ */
+function classifyChoreType(title, description = '') {
+  const text = normalizeInput(title, description);
+  const scores = calculateScores(text);
+  const { type } = findWinningType(scores);
+  return type;
+}
+
+/**
+ * Determine confidence level based on score
+ * @param {number} score - The classification score
+ * @returns {string} - 'high', 'medium', or 'low'
+ */
+function getConfidenceLevel(score) {
+  if (score >= 4) return 'high';
+  if (score >= 2) return 'medium';
+  return 'low';
+}
+
+/**
+ * Get confidence level for a classification
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description
+ * @returns {object} - { type: string, confidence: 'high'|'medium'|'low', score: number }
+ * @throws {Error} - If title is invalid
+ */
+function classifyWithConfidence(title, description = '') {
+  const text = normalizeInput(title, description);
+  const scores = calculateScores(text);
+  const { type, score } = findWinningType(scores);
+  const confidence = getConfidenceLevel(score);
+
+  return { type, confidence, score };
+}
+
+/**
+ * Get detailed classification with all type scores
+ * Useful for debugging or when needing transparency in classification
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description
+ * @returns {object} - { type, confidence, score, allScores }
+ * @throws {Error} - If title is invalid
+ */
+function classifyWithDetails(title, description = '') {
+  const text = normalizeInput(title, description);
+  const scores = calculateScores(text);
+  const { type, score } = findWinningType(scores);
+  const confidence = getConfidenceLevel(score);
+
+  return {
+    type,
+    confidence,
+    score,
+    allScores: scores
+  };
+}
+
+module.exports = {
+  classifyChoreType,
+  classifyWithConfidence,
+  classifyWithDetails,
+  TYPE_KEYWORDS,
+  // Expose helpers for testing
+  normalizeInput,
+  escapeRegex,
+  calculateScores,
+  findWinningType,
+  getConfidenceLevel
+};

package/lib/chore-taxonomy.js

@@ -0,0 +1,172 @@
+/**
+ * Chore Type Taxonomy
+ * Defines the 4 chore types and their workflow guidance for the chore-planning and chore-mode skills.
+ */
+
+/**
+ * Chore types
+ * @constant {Object}
+ */
+const CHORE_TYPES = Object.freeze({
+  REFACTOR: 'refactor',
+  DEPENDENCY: 'dependency',
+  CLEANUP: 'cleanup',
+  TOOLING: 'tooling'
+});
+
+/**
+ * Valid chore type values as array
+ * @constant {Array<string>}
+ */
+const VALID_CHORE_TYPES = Object.freeze(Object.values(CHORE_TYPES));
+
+/**
+ * Guidance for each chore type
+ * @constant {Object}
+ */
+const CHORE_TYPE_GUIDANCE = Object.freeze({
+  [CHORE_TYPES.REFACTOR]: {
+    scope: [
+      'Define clear boundaries - what code is being restructured',
+      'Identify all callers/dependents of code being changed',
+      'Ensure behavior remains unchanged (refactor, not rewrite)',
+      'Consider breaking into smaller refactors if scope is large'
+    ],
+    verification: [
+      'All existing tests pass without modification',
+      'No new functionality added (that requires new tests)',
+      'Code review confirms behavior preservation',
+      'Performance is not degraded'
+    ],
+    testHandling: {
+      required: true,
+      approach: 'Run all tests for affected modules before and after. Update test file paths/imports if moved. Do NOT change test assertions - if tests fail, the refactor broke behavior.'
+    }
+  },
+  [CHORE_TYPES.DEPENDENCY]: {
+    scope: [
+      'Identify which packages are being updated',
+      'Check changelogs for breaking changes',
+      'Note any deprecated APIs that need migration',
+      'Consider update strategy: one at a time vs batch'
+    ],
+    verification: [
+      'All tests pass after update',
+      'Application builds successfully',
+      'No new deprecation warnings (or documented)',
+      'Security vulnerabilities addressed (if security update)'
+    ],
+    testHandling: {
+      required: false,
+      approach: 'Run full test suite to catch regressions. No new tests needed unless migrating to new API patterns. Document any test changes needed due to library API changes.'
+    }
+  },
+  [CHORE_TYPES.CLEANUP]: {
+    scope: [
+      'Define what is being cleaned (dead code, unused files, etc.)',
+      'Verify code is actually unused (grep for references)',
+      'Set clear boundaries to avoid scope creep',
+      'Consider impact on git history/blame'
+    ],
+    verification: [
+      'All tests still pass',
+      'No broken imports or references',
+      'Application runs correctly',
+      'Removed code was actually unused'
+    ],
+    testHandling: {
+      required: false,
+      approach: 'Run existing tests to ensure nothing breaks. Remove tests only if they test deleted code. No new tests needed for cleanup work.'
+    }
+  },
+  [CHORE_TYPES.TOOLING]: {
+    scope: [
+      'Define what tooling is being changed (CI, build, dev environment)',
+      'Document current behavior before changes',
+      'Consider impact on team workflows',
+      'Plan rollback strategy if changes cause issues'
+    ],
+    verification: [
+      'CI pipeline passes',
+      'Build completes successfully',
+      'Dev environment works for all team members',
+      'No regression in build times or developer experience'
+    ],
+    testHandling: {
+      required: false,
+      approach: 'Verify tooling changes work via manual testing or CI runs. Add integration tests only if tooling is complex. Focus on verification over unit testing for infrastructure.'
+    }
+  }
+});
+
+/**
+ * Normalize a chore type string (lowercase, trimmed)
+ * @param {string} type - Type to normalize
+ * @returns {string|null} Normalized type or null if input is invalid
+ */
+function normalizeChoreType(type) {
+  if (type === null || type === undefined) {
+    return null;
+  }
+  if (typeof type !== 'string') {
+    return null;
+  }
+  return type.toLowerCase().trim();
+}
+
+/**
+ * Check if a chore type is valid (case-insensitive)
+ * @param {string} type - Type to validate
+ * @returns {boolean} True if type is valid
+ */
+function isValidChoreType(type) {
+  const normalized = normalizeChoreType(type);
+  if (normalized === null) {
+    return false;
+  }
+  return VALID_CHORE_TYPES.includes(normalized);
+}
+
+/**
+ * Get guidance for a chore type
+ * @param {string} type - Chore type (case-insensitive)
+ * @returns {Object} Guidance object with scope, verification, and testHandling
+ * @throws {Error} If type is null, undefined, or invalid
+ */
+function getGuidance(type) {
+  if (type === null || type === undefined) {
+    throw new Error(
+      'Chore type is required. Valid types: refactor, dependency, cleanup, tooling'
+    );
+  }
+
+  const normalized = normalizeChoreType(type);
+
+  if (!normalized || !VALID_CHORE_TYPES.includes(normalized)) {
+    throw new Error(
+      `Invalid chore type: "${type}". Valid types: refactor, dependency, cleanup, tooling`
+    );
+  }
+
+  return CHORE_TYPE_GUIDANCE[normalized];
+}
+
+/**
+ * Get all chore types
+ * @returns {Array<string>} Array of valid chore types
+ */
+function getChoreTypes() {
+  return [...VALID_CHORE_TYPES];
+}
+
+module.exports = {
+  CHORE_TYPES,
+  VALID_CHORE_TYPES,
+  CHORE_TYPE_GUIDANCE,
+  normalizeChoreType,
+  isValidChoreType,
+  getGuidance,
+  getChoreTypes,
+  // Alias for step definitions
+  types: CHORE_TYPES
+};

package/lib/jettypod-backup.js

@@ -8,16 +8,41 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const safeDelete = require('./safe-delete');
+
+/**
+ * Get the global backup directory path (in home directory)
+ * @returns {string} Path to global backup directory
+ */
+function getGlobalBackupDir() {
+  const os = require('os');
+  return path.join(os.homedir(), '.jettypod-backups');
+}
+
+/**
+ * Get project-specific identifier for global backups
+ * @param {string} gitRoot - Path to git repository root
+ * @returns {string} Project identifier
+ */
+function getProjectId(gitRoot) {
+  // Use the directory name and a hash of the full path for uniqueness
+  const dirname = path.basename(gitRoot);
+  const hash = require('crypto').createHash('md5').update(gitRoot).digest('hex').slice(0, 8);
+  return `${dirname}-${hash}`;
+}
 
 /**
  * Create a backup of the .jettypod directory
  *
  * @param {string} gitRoot - Absolute path to git repository root
  * @param {string} reason - Human-readable reason for backup (e.g., "cleanup-worktree-1234")
+ * @param {Object} options - Backup options
+ * @param {boolean} options.global - Store backup in home directory (default: false)
  * @returns {Promise<Object>} Result with success status and backup path
  */
-async function createBackup(gitRoot, reason = 'unknown') {
+async function createBackup(gitRoot, reason = 'unknown', options = {}) {
   const jettypodPath = path.join(gitRoot, '.jettypod');
+  const useGlobal = options.global || false;
 
   // Verify .jettypod exists
   if (!fs.existsSync(jettypodPath)) {
@@ -28,8 +53,17 @@ async function createBackup(gitRoot, reason = 'unknown') {
     };
   }
 
+  // Determine backup location
+  let backupBaseDir;
+  if (useGlobal) {
+    const globalDir = getGlobalBackupDir();
+    const projectId = getProjectId(gitRoot);
+    backupBaseDir = path.join(globalDir, projectId);
+  } else {
+    backupBaseDir = path.join(gitRoot, '.git', 'jettypod-backups');
+  }
+
   // Create backup directory if it doesn't exist
-  const backupBaseDir = path.join(gitRoot, '.git', 'jettypod-backups');
   if (!fs.existsSync(backupBaseDir)) {
     fs.mkdirSync(backupBaseDir, { recursive: true });
   }
@@ -89,7 +123,16 @@ async function cleanupOldBackups(backupDir, keepCount = 10) {
     // Delete old backups
     const toDelete = backups.slice(keepCount);
     for (const backup of toDelete) {
-      fs.rmSync(backup.path, { recursive: true, force: true });
+      // SAFETY: Validate backup path before deletion
+      const resolvedPath = path.resolve(backup.path);
+      const isValidBackupPath = (resolvedPath.includes('.git/jettypod-backups') ||
+                                  resolvedPath.includes('.jettypod-backups')) &&
+                                 backup.name.startsWith('jettypod-');
+      if (!isValidBackupPath) {
+        console.warn(`Warning: Skipping suspicious backup path: ${backup.path}`);
+        continue;
+      }
+      fs.rmSync(backup.path, { recursive: true });
     }
   } catch (err) {
     // Non-fatal - just log warning
@@ -98,12 +141,77 @@ async function cleanupOldBackups(backupDir, keepCount = 10) {
 }
 
 /**
- * List available backups
+ * List available backups from both local and global locations
  *
  * @param {string} gitRoot - Absolute path to git repository root
- * @returns {Array} List of backup objects with name, path, timestamp
+ * @param {Object} options - Options
+ * @param {boolean} options.includeGlobal - Include global backups (default: true)
+ * @returns {Array} List of backup objects with name, path, timestamp, location
  */
-function listBackups(gitRoot) {
+function listBackups(gitRoot, options = {}) {
+  const includeGlobal = options.includeGlobal !== false;
+  const allBackups = [];
+
+  // Local backups
+  const localDir = path.join(gitRoot, '.git', 'jettypod-backups');
+  if (fs.existsSync(localDir)) {
+    try {
+      const localBackups = fs.readdirSync(localDir)
+        .filter(name => name.startsWith('jettypod-'))
+        .map(name => {
+          const backupPath = path.join(localDir, name);
+          const stat = fs.statSync(backupPath);
+          return {
+            name: name,
+            path: backupPath,
+            created: stat.mtime,
+            size: getDirectorySize(backupPath),
+            location: 'local'
+          };
+        });
+      allBackups.push(...localBackups);
+    } catch (err) {
+      console.error(`Error reading local backups: ${err.message}`);
+    }
+  }
+
+  // Global backups
+  if (includeGlobal) {
+    const globalDir = getGlobalBackupDir();
+    const projectId = getProjectId(gitRoot);
+    const projectBackupDir = path.join(globalDir, projectId);
+
+    if (fs.existsSync(projectBackupDir)) {
+      try {
+        const globalBackups = fs.readdirSync(projectBackupDir)
+          .filter(name => name.startsWith('jettypod-'))
+          .map(name => {
+            const backupPath = path.join(projectBackupDir, name);
+            const stat = fs.statSync(backupPath);
+            return {
+              name: name,
+              path: backupPath,
+              created: stat.mtime,
+              size: getDirectorySize(backupPath),
+              location: 'global'
+            };
+          });
+        allBackups.push(...globalBackups);
+      } catch (err) {
+        console.error(`Error reading global backups: ${err.message}`);
+      }
+    }
+  }
+
+  // Sort all backups by date, newest first
+  return allBackups.sort((a, b) => b.created - a.created);
+}
+
+/**
+ * List available backups (legacy function for backwards compatibility)
+ * @deprecated Use listBackups with options instead
+ */
+function listBackupsLegacy(gitRoot) {
   const backupBaseDir = path.join(gitRoot, '.git', 'jettypod-backups');
 
   if (!fs.existsSync(backupBaseDir)) {
@@ -182,7 +290,13 @@ async function restoreBackup(gitRoot, backupName = 'latest') {
 
     // Remove current .jettypod
     if (fs.existsSync(jettypodPath)) {
-      fs.rmSync(jettypodPath, { recursive: true, force: true });
+      // SAFETY: Validate jettypod path before deletion
+      const resolvedPath = path.resolve(jettypodPath);
+      const resolvedGitRoot = path.resolve(gitRoot);
+      if (!resolvedPath.startsWith(resolvedGitRoot) || !resolvedPath.endsWith('.jettypod')) {
+        throw new Error(`SAFETY: Refusing to delete ${jettypodPath} - not a valid .jettypod directory`);
+      }
+      fs.rmSync(jettypodPath, { recursive: true });
     }
 
     // Copy backup to .jettypod
@@ -234,5 +348,7 @@ function getDirectorySize(dirPath) {
 module.exports = {
   createBackup,
   listBackups,
-  restoreBackup
+  restoreBackup,
+  getGlobalBackupDir,
+  getProjectId
 };