jettypod 4.2.11 → 4.4.0

package/SECURITY-AUDIT-CATASTROPHIC-DELETE.md

@@ -0,0 +1,196 @@
+# Security Audit: Catastrophic Codebase Deletion
+
+**Date**: 2025-11-25
+**Context**: Codebase was deleted while working on "chores not requiring a parent" feature
+**Symptom**: Shell became stuck, entire codebase was deleted
+
+---
+
+## Executive Summary
+
+The JettyPod codebase contains multiple unsafe deletion patterns that, when combined with incorrect path resolution, can cause catastrophic data loss. The root cause is **79 instances of `fs.rmSync()` with `{ recursive: true, force: true }` that lack path validation**.
+
+---
+
+## Phase 1: Immediate Fixes (Critical)
+
+### 1.1 Add Safe Delete Wrapper
+
+- [x] Create `lib/safe-delete.js` with path validation
+- [x] Validate target path is within expected boundaries
+- [x] Reject deletion of repository root, home directory, or system paths
+- [x] Log all deletion operations for forensic analysis
+- [x] Never use `force: true` - let errors surface
+
+### 1.2 Fix `removeDirectoryResilient()`
+
+Location: `lib/worktree-manager.js:477-536`
+
+- [x] Add path validation before any deletion stage
+- [x] Ensure `dirPath` starts with `.jettypod-work/`
+- [x] Add explicit check that `dirPath !== gitRoot`
+- [x] Replace direct `fs.rmSync()` with safe wrapper
+
+### 1.3 Fix Test Cleanup Script
+
+Location: `scripts/test-cleanup.js`
+
+- [x] Only delete worktrees/branches that match test naming patterns
+- [x] Add dry-run mode that logs what would be deleted
+- [x] Add protected branches list (main, master, develop, staging, production)
+
+---
+
+## Phase 2: Path Resolution Hardening (High Priority)
+
+### 2.1 Eliminate Dangerous `process.cwd()` Usage
+
+- [ ] Audit all 94 instances of `process.cwd()` for deletion contexts
+- [ ] Pass explicit `repoPath` to all functions
+- [ ] Add safety checks that reject operations if `cwd` is inside `.jettypod-work/`
+- [ ] Cache and validate the main repo path at startup
+
+### 2.2 Add Worktree Detection Guard
+
+- [x] Create `ensureNotInWorktree()` helper function (in safe-delete.js)
+- [x] Add guard to createWorktree() in `worktree-manager.js`
+- [x] cleanupWorktree() intentionally DOES NOT have this guard - the merge workflow runs from within worktrees. Safety comes from explicit repoPath requirement + path validation in removeDirectoryResilient()
+
+---
+
+## Phase 3: Deletion Audit Trail (Medium Priority)
+
+### 3.1 Create Deletion Logger
+
+- [x] Add logging to `lib/safe-delete.js`
+- [x] Log timestamp, path, caller stack trace, success/failure
+- [x] Write to `.jettypod/deletion-log.json`
+
+### 3.2 Add Pre-Delete Snapshot
+
+- [x] Count files/directories before recursive delete (countContents in safe-delete.js)
+- [x] If count exceeds threshold (default: 100), require force flag
+- [x] Log manifest of what will be deleted (count logged in deletion log)
+
+---
+
+## Phase 4: Test Infrastructure Safety (Medium Priority)
+
+### 4.1 Isolate Test Deletions to `/tmp/`
+
+- [ ] Validate all test cleanup paths match `/tmp/jettypod-test-*`
+- [ ] Update `lib/test-helpers.js` to enforce boundary
+- [ ] Update all step definition files to use safe patterns
+
+### 4.2 Add Test Environment Validation
+
+- [ ] Verify `NODE_ENV === 'test'` before test cleanup
+- [ ] Verify current directory is a test directory
+- [ ] Verify no production database exists in path
+
+### 4.3 Fix Cucumber After Hooks
+
+Location: `test-templates.hidden/hooks.js`
+
+- [ ] Validate all tracked paths are within `/tmp/`
+- [ ] Clear tracking on test failure to prevent partial cleanup
+
+---
+
+## Phase 5: Backup & Recovery (Low Priority)
+
+### 5.1 Enhance Automatic Backups
+
+- [x] Create backup before ANY destructive operation (existing behavior preserved)
+- [x] Store backups outside the repository (new `options.global` flag stores in `~/.jettypod-backups/`)
+- [x] Enhanced listBackups to show both local and global backups
+
+### 5.2 Add Deletion Undo
+
+- [x] Implement `.jettypod-trash/` directory
+- [x] Move deleted files to trash instead of immediate delete (`moveToTrash()` in safe-delete.js)
+- [x] Auto-purge after 24 hours (`purgeOldTrash()` with configurable hours)
+- [x] Add `jettypod undelete` command
+- [x] Add `jettypod trash` command (list, empty, purge subcommands)
+
+---
+
+## Files Requiring Changes
+
+| Status | File | Risk Level | Changes Needed |
+|--------|------|------------|----------------|
+| [x] | `lib/safe-delete.js` | NEW | Create safe deletion wrapper |
+| [x] | `lib/worktree-manager.js` | CRITICAL | Add path validation to all delete operations |
+| [x] | `scripts/test-cleanup.js` | CRITICAL | Restrict to test-pattern paths only |
+| [x] | `lib/jettypod-backup.js` | HIGH | Validate paths before delete |
+| [x] | `lib/test-helpers.js` | HIGH | Ensure cleanup only targets `/tmp/` |
+| [x] | `jettypod.js` (line 908) | HIGH | Validate `skillsDestDir` before delete |
+| [x] | `test-templates.hidden/hooks.js` | MEDIUM | Validate tracked paths |
+
+---
+
+## Dangerous Code Patterns Found
+
+### Pattern 1: Unvalidated Recursive Delete
+```javascript
+// DANGEROUS - no path validation
+fs.rmSync(dirPath, { recursive: true, force: true });
+```
+
+### Pattern 2: Force Flag Suppresses Errors
+```javascript
+// DANGEROUS - errors are silently ignored
+fs.rmSync(path, { force: true });
+```
+
+### Pattern 3: Path from Untrusted Source
+```javascript
+// DANGEROUS - process.cwd() can be manipulated
+const targetPath = path.join(process.cwd(), 'some-dir');
+fs.rmSync(targetPath, { recursive: true });
+```
+
+### Pattern 4: Cleanup Without Boundaries
+```javascript
+// DANGEROUS - deletes ALL worktrees, not just test ones
+for (const worktree of worktrees) {
+  execSync(`git worktree remove --force "${worktree}"`);
+}
+```
+
+---
+
+## Root Cause Analysis
+
+The catastrophic deletion likely occurred through this sequence:
+
+1. User was modifying chore validation in `features/work-tracking/index.js`
+2. A test run or command was executed
+3. Path resolution returned unexpected value (possibly due to worktree context)
+4. `fs.rmSync()` with `{ recursive: true, force: true }` executed on wrong path
+5. `force: true` suppressed all warnings
+6. Shell appeared "stuck" while deleting thousands of files
+7. By the time the operation completed, codebase was gone
+
+---
+
+## Implementation Order
+
+- [x] **Step 1**: Create `lib/safe-delete.js` wrapper
+- [x] **Step 2**: Patch `removeDirectoryResilient()` with path validation
+- [x] **Step 3**: Fix `scripts/test-cleanup.js`
+- [x] **Step 4**: Add worktree detection guard to destructive operations
+- [x] **Step 5**: Implement deletion audit trail
+- [x] **Step 6**: Fix remaining unsafe `fs.rmSync()` instances (production code fixed; safeTestCleanup helper created for test files)
+- [x] **Step 7**: Enhanced backup system (global backups in ~/.jettypod-backups/)
+- [x] **Step 8**: Deletion undo/trash functionality (`.jettypod-trash/`, `jettypod trash`, `jettypod undelete`)
+
+---
+
+## Testing the Fixes
+
+- [ ] Attempt to delete repository root - should be blocked
+- [ ] Attempt to delete from within worktree - should be blocked
+- [ ] Attempt to delete path outside repo - should be blocked
+- [ ] Run test suite - should only clean up `/tmp/` paths
+- [ ] Check deletion log after operations - should show audit trail

package/TEST_HOOK.md

@@ -0,0 +1 @@
+# Test commit to verify post-merge hook

package/hooks/post-checkout

@@ -1,13 +1,88 @@
 #!/usr/bin/env node
 
+/**
+ * Post-Checkout Hook
+ *
+ * 1. Prevents checking out default branch in JettyPod worktrees
+ * 2. Imports database snapshots after checkout
+ */
+
 const { importAll } = require('../lib/db-import');
+const { execSync } = require('child_process');
 
 (async () => {
+  const cwd = process.cwd();
+
+  // FIRST: Check if we're in a JettyPod worktree and prevent default branch checkout
+  if (cwd.includes('.jettypod-work')) {
+    try {
+      // Get the branch we just checked out
+      const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+
+      // Detect default branch
+      let defaultBranch;
+      try {
+        // Try to get the default branch from git config
+        defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe']
+        }).trim().replace('refs/remotes/origin/', '');
+      } catch {
+        // Fallback: check which common branch names exist
+        try {
+          execSync('git rev-parse --verify main', { stdio: ['pipe', 'pipe', 'pipe'] });
+          defaultBranch = 'main';
+        } catch {
+          try {
+            execSync('git rev-parse --verify master', { stdio: ['pipe', 'pipe', 'pipe'] });
+            defaultBranch = 'master';
+          } catch {
+            // Can't determine default branch - skip check
+            defaultBranch = null;
+          }
+        }
+      }
+
+      // Check if we checked out the default branch
+      if (defaultBranch && currentBranch === defaultBranch) {
+        console.error('');
+        console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.error('❌ ERROR: Cannot checkout default branch in worktree');
+        console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.error('');
+        console.error(`You are in a JettyPod worktree for isolated work.`);
+        console.error(`Checking out ${defaultBranch} in a worktree bypasses the merge workflow.`);
+        console.error('');
+        console.error('To merge your changes:');
+        console.error('  1. Commit your changes: git add . && git commit -m "..."');
+        console.error('  2. Use JettyPod merge:  jettypod work merge');
+        console.error('');
+        console.error('This ensures proper worktree cleanup and database updates.');
+        console.error('');
+        console.error('Reverting checkout...');
+        console.error('');
+
+        // Revert to previous branch
+        try {
+          execSync('git checkout -', { stdio: 'inherit' });
+        } catch (revertErr) {
+          console.error('Failed to revert checkout. You may need to manually switch branches.');
+        }
+
+        process.exit(1);
+      }
+    } catch (err) {
+      // If we can't determine the branch, allow the checkout
+      // (better to be permissive than block legitimate operations)
+    }
+  }
+
+  // SECOND: Import database snapshots
   try {
-    // Import JSON snapshots into databases after checkout
     await importAll();
-
-    // Exit successfully - checkout should not be blocked
     process.exit(0);
   } catch (err) {
     // Log error but don't block checkout

package/hooks/pre-push

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-Push Hook
+ *
+ * Prevents pushing directly from JettyPod worktrees.
+ * Forces use of `jettypod work merge` to ensure proper cleanup.
+ */
+
+const cwd = process.cwd();
+
+// Check if we're in a JettyPod worktree
+if (cwd.includes('.jettypod-work')) {
+  console.error('');
+  console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.error('❌ ERROR: Cannot push directly from worktree');
+  console.error('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.error('');
+  console.error('You are in a JettyPod worktree for isolated work.');
+  console.error('Pushing directly bypasses the merge workflow.');
+  console.error('');
+  console.error('To merge and push your changes:');
+  console.error('  1. Commit your changes: git add . && git commit -m "..."');
+  console.error('  2. Use JettyPod merge:  jettypod work merge');
+  console.error('');
+  console.error('This ensures proper worktree cleanup and database updates.');
+  console.error('');
+
+  process.exit(1);
+}
+
+// Allow pushes from main repo
+process.exit(0);

package/jettypod.js

@@ -8,6 +8,7 @@ const config = require('./lib/config');
 // CRITICAL: Calculate and cache the REAL git root BEFORE any worktree operations
 // This prevents catastrophic bugs where process.cwd() returns a worktree path
 const { getGitRoot } = require('./lib/git-root');
+const safeDelete = require('./lib/safe-delete');
 let GIT_ROOT;
 try {
   GIT_ROOT = getGitRoot();
@@ -16,6 +17,66 @@ try {
   GIT_ROOT = process.cwd();
 }
 
+/**
+ * Format bytes to human-readable string
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}
+
+/**
+ * Detect if project has existing code (mid-project adoption)
+ * Checks for common code directories and package.json dependencies
+ */
+function hasExistingCode() {
+  // Check for common code directories with actual code files
+  const codeDirectories = ['src', 'lib', 'app'];
+  const hasCodeDir = codeDirectories.some(dir => {
+    if (!fs.existsSync(dir)) {
+      return false;
+    }
+
+    // Check if directory contains any code files (not just .gitkeep)
+    try {
+      const files = fs.readdirSync(dir, { recursive: true, withFileTypes: true });
+      const codeFiles = files.filter(file => {
+        if (file.isDirectory()) return false;
+        // Exclude .gitkeep and other dotfiles
+        if (file.name.startsWith('.')) return false;
+        return true;
+      });
+      return codeFiles.length > 0;
+    } catch (e) {
+      // Permission denied or other error - treat as no code
+      return false;
+    }
+  });
+
+  if (hasCodeDir) {
+    return true;
+  }
+
+  // Check for package.json with dependencies
+  if (fs.existsSync('package.json')) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+      const hasDeps = (pkg.dependencies && Object.keys(pkg.dependencies).length > 0) ||
+                     (pkg.devDependencies && Object.keys(pkg.devDependencies).length > 0);
+      if (hasDeps) {
+        return true;
+      }
+    } catch (e) {
+      // Invalid package.json - treat as no code
+    }
+  }
+
+  return false;
+}
+
 /**
  * Ensure jettypod-specific paths are gitignored and untracked
  * Called during init and update to fix existing projects
@@ -24,7 +85,8 @@ function ensureJettypodGitignores() {
   const gitignorePath = path.join(process.cwd(), '.gitignore');
   const entriesToIgnore = [
     '.claude/session.md',
-    '.jettypod-work/'
+    '.jettypod-work/',
+    '.jettypod-trash/'
   ];
 
   // Add entries to .gitignore if not present
@@ -525,29 +587,33 @@ ${communicationStyle}`;
   
   detectTechStack() {
     const stacks = [];
-    
+
     if (fs.existsSync('package.json')) {
-      const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      
-      // Detect major frameworks
-      if (deps.react) stacks.push('React');
-      if (deps.vue) stacks.push('Vue');
-      if (deps.angular) stacks.push('Angular');
-      if (deps.svelte) stacks.push('Svelte');
-      if (deps.next) stacks.push('Next.js');
-      if (deps.express) stacks.push('Express');
-      if (deps.fastify) stacks.push('Fastify');
-      if (deps.nestjs) stacks.push('NestJS');
-      
-      // Testing frameworks
-      if (deps.jest) stacks.push('Jest');
-      if (deps.mocha) stacks.push('Mocha');
-      if (deps.vitest) stacks.push('Vitest');
-      if (deps.cucumber) stacks.push('Cucumber');
-      
-      // Node.js is implied
-      stacks.unshift('Node.js');
+      try {
+        const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+        // Detect major frameworks
+        if (deps.react) stacks.push('React');
+        if (deps.vue) stacks.push('Vue');
+        if (deps.angular) stacks.push('Angular');
+        if (deps.svelte) stacks.push('Svelte');
+        if (deps.next) stacks.push('Next.js');
+        if (deps.express) stacks.push('Express');
+        if (deps.fastify) stacks.push('Fastify');
+        if (deps.nestjs) stacks.push('NestJS');
+
+        // Testing frameworks
+        if (deps.jest) stacks.push('Jest');
+        if (deps.mocha) stacks.push('Mocha');
+        if (deps.vitest) stacks.push('Vitest');
+        if (deps.cucumber) stacks.push('Cucumber');
+
+        // Node.js is implied
+        stacks.unshift('Node.js');
+      } catch (e) {
+        // Invalid or malformed package.json - ignore and continue with other detection
+      }
     }
     
     if (fs.existsSync('Cargo.toml')) stacks.push('Rust');
@@ -639,6 +705,14 @@ async function initializeProject() {
       name: projectName,
       project_state: 'internal'
     };
+
+    // Auto-detect mid-project adoption and skip discovery
+    if (hasExistingCode()) {
+      initialConfig.project_discovery = {
+        status: 'completed'
+      };
+    }
+
     config.write(initialConfig);
   }
 
@@ -844,7 +918,13 @@ async function initializeProject() {
           try {
             // Remove partial copy if it exists
             if (fs.existsSync(skillsDestDir)) {
-              fs.rmSync(skillsDestDir, { recursive: true, force: true });
+              // SAFETY: Validate path before deletion
+              const resolvedSkillsDir = path.resolve(skillsDestDir);
+              const resolvedCwd = path.resolve(process.cwd());
+              if (!resolvedSkillsDir.startsWith(resolvedCwd) || !resolvedSkillsDir.includes('.claude')) {
+                throw new Error(`SAFETY: Refusing to delete ${skillsDestDir} - not within .claude directory`);
+              }
+              fs.rmSync(skillsDestDir, { recursive: true });
             }
             fs.renameSync(backupDir, skillsDestDir);
             console.log('✅ Previous skills restored successfully');
@@ -1153,7 +1233,11 @@ switch (command) {
     } else if (subcommand === 'merge') {
       const workCommands = require('./features/work-commands/index.js');
       try {
-        await workCommands.mergeWork();
+        // Parse merge flags from args
+        const withTransition = args.includes('--with-transition');
+        const releaseLock = args.includes('--release-lock');
+
+        await workCommands.mergeWork({ withTransition, releaseLock });
       } catch (err) {
         console.error(`Error: ${err.message}`);
         process.exit(1);
@@ -1872,6 +1956,112 @@ Quick commands:
     }
     break;
 
+  case 'trash': {
+    // Trash management commands
+    const trashSubcommand = args[0];
+    const gitRoot = process.cwd();
+
+    if (trashSubcommand === 'list' || !trashSubcommand) {
+      // List items in trash
+      const trashItems = safeDelete.listTrash(gitRoot);
+
+      if (trashItems.length === 0) {
+        console.log('🗑️  Trash is empty');
+      } else {
+        console.log('🗑️  Trash contents:');
+        console.log('');
+        trashItems.forEach((item, index) => {
+          const age = Math.round((Date.now() - item.trashedAt.getTime()) / (60 * 60 * 1000));
+          const ageStr = age < 1 ? 'just now' : age < 24 ? `${age}h ago` : `${Math.round(age / 24)}d ago`;
+          const typeIcon = item.isDirectory ? '📁' : '📄';
+          console.log(`  ${index + 1}. ${typeIcon} ${item.relativePath}`);
+          console.log(`     Deleted: ${ageStr} | Size: ${item.isDirectory ? item.size + ' items' : formatBytes(item.size)}`);
+        });
+        console.log('');
+        console.log(`Total: ${trashItems.length} item(s)`);
+        console.log('');
+        console.log('Use "jettypod undelete" to restore the most recent item');
+        console.log('Use "jettypod undelete <path>" to restore a specific item');
+      }
+    } else if (trashSubcommand === 'empty') {
+      // Empty the trash
+      const result = safeDelete.emptyTrash(gitRoot);
+      if (result.success) {
+        console.log(`🗑️  Trash emptied (${result.count} items removed)`);
+      } else {
+        console.error(`❌ Failed to empty trash: ${result.error}`);
+        process.exit(1);
+      }
+    } else if (trashSubcommand === 'purge') {
+      // Purge old items (older than 24 hours by default)
+      const hoursArg = args[1];
+      const maxAgeHours = hoursArg ? parseInt(hoursArg, 10) : 24;
+      const dryRun = args.includes('--dry-run');
+
+      if (dryRun) {
+        console.log(`🔍 Dry run: Would purge items older than ${maxAgeHours} hours`);
+      }
+
+      const result = safeDelete.purgeOldTrash(gitRoot, { maxAgeHours, dryRun });
+
+      if (result.purged.length === 0) {
+        console.log(`✅ No items older than ${maxAgeHours} hours to purge`);
+      } else {
+        console.log(`🗑️  ${dryRun ? 'Would purge' : 'Purged'} ${result.purged.length} item(s):`);
+        result.purged.forEach(item => {
+          console.log(`   - ${item.originalPath}`);
+        });
+      }
+
+      if (result.errors.length > 0) {
+        console.error('');
+        console.error('Errors:');
+        result.errors.forEach(err => {
+          console.error(`   - ${err.name}: ${err.error}`);
+        });
+      }
+
+      console.log(`\nRemaining in trash: ${result.remaining} item(s)`);
+    } else {
+      console.log('Usage: jettypod trash [list|empty|purge]');
+      console.log('');
+      console.log('Commands:');
+      console.log('  list           List items in trash (default)');
+      console.log('  empty          Permanently delete all items in trash');
+      console.log('  purge [hours]  Delete items older than N hours (default: 24)');
+      console.log('                 Add --dry-run to preview what would be deleted');
+    }
+    break;
+  }
+
+  case 'undelete': {
+    // Restore from trash
+    const gitRoot = process.cwd();
+    const itemName = args[0] || 'latest';
+
+    const trashItems = safeDelete.listTrash(gitRoot);
+    if (trashItems.length === 0) {
+      console.log('🗑️  Trash is empty - nothing to restore');
+      process.exit(0);
+    }
+
+    const result = safeDelete.restoreFromTrash(gitRoot, itemName);
+
+    if (result.success) {
+      console.log(`✅ Restored: ${result.restoredTo}`);
+    } else {
+      console.error(`❌ Failed to restore: ${result.error}`);
+
+      if (result.error.includes('path already exists')) {
+        console.log('');
+        console.log('The original location already has a file/directory.');
+        console.log('Delete it first or use a different restore location.');
+      }
+      process.exit(1);
+    }
+    break;
+  }
+
   default:
     // Smart mode: auto-initialize if needed, otherwise show guidance
     if (!fs.existsSync('.jettypod')) {

package/lib/claudemd.js

@@ -65,11 +65,19 @@ function updateCurrentWork(currentWork, mode) {
 
   // Write to session file (gitignored) instead of CLAUDE.md
   // This prevents merge conflicts and stale context on main branch
+  // Only write session file if we're in a worktree (not root directory)
   if (currentMode !== null) {
-    writeSessionFile(currentWork, currentMode, {
-      epicId: currentWork.epic_id,
-      epicTitle: currentWork.epic_title
-    });
+    try {
+      writeSessionFile(currentWork, currentMode, {
+        epicId: currentWork.epic_id,
+        epicTitle: currentWork.epic_title
+      });
+    } catch (err) {
+      // Skip if not in worktree - validation will throw error
+      if (!err.message.includes('Cannot create session.md in root directory')) {
+        throw err; // Re-throw unexpected errors
+      }
+    }
   }
 }