jettypod 4.3.0 → 4.4.1

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/docs/DECISIONS.md

@@ -6,61 +6,13 @@ This document records key decisions made during project discovery and epic plann
 
 ## Epic-Level Decisions
 
-### Epic #237: Real-time Collaboration
+### Epic #2: Standalone Chore Workflow System
 
-**Architecture:** WebSockets with Socket.io
+**Architecture:** Two-tier skill structure (chore-planning → chore-mode)
 
-*Rationale:* Bidirectional communication needed, Socket.io provides automatic fallbacks and reconnection
+*Rationale:* Two-tier skill structure chosen to mirror existing feature workflow patterns. Separates planning concerns (scope, criteria, impact) from execution concerns (guidance, verification). Type-dependent test analysis balances thoroughness with pragmatism.
 
-*Date:* 10/29/2025
-
-**State Management:** Redux Toolkit
-
-*Rationale:* Need centralized state for connection status across multiple components
-
-*Date:* 10/29/2025
-
-**Error Handling:** Exponential backoff with jitter for reconnection
-
-*Rationale:* Prevents thundering herd when server recovers, jitter distributes reconnection attempts evenly
-
-*Date:* 10/31/2025
-
-**Testing Strategy:** Integration tests with mock Socket.io server
-
-*Rationale:* Allows testing reconnection logic and state synchronization without real server dependency
-
-*Date:* 10/31/2025
-
----
-
-### Epic #238: Real-time System
-
-**Architecture:** WebSockets
-
-*Rationale:* Real-time bidirectional communication required
-
-*Date:* 10/29/2025
-
----
-
-### Epic #242: Epic Needs Discovery
-
-**Architecture:** GraphQL API
-
-*Rationale:* Flexible querying and strong typing needed for complex data requirements
-
-*Date:* 10/29/2025
-
----
-
-### Epic #1840: Multiple AI Coding Assistant Instances
-
-**Concurrent Merge Architecture:** Database-backed merge queue with rebase-first strategy and smart conflict resolution
-
-*Rationale:* Multiple Claude Code instances need coordinated access to main branch. Using database as coordination point provides simple, reliable serialization without complex distributed locking. Rebase-first strategy ensures linear history and makes conflicts easier to reason about. Smart conflict resolution (auto-resolve trivial, LLM-assist complex) enables autonomous operation while escalating truly ambiguous cases. Graceful degradation ensures system never enters unrecoverable state.
-
-*Date:* 11/14/2025
+*Date:* 11/25/2025
 
 ---
 

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');
@@ -1876,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')) {