jettypod 4.4.65 → 4.4.67

package/jettypod.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const config = require('./lib/config');
+const wsServer = require('./lib/ws-server');
 // getModeBehaviorContent removed - skills now provide all mode guidance
 
 // CRITICAL: Calculate and cache the REAL git root BEFORE any worktree operations
@@ -1293,18 +1294,26 @@ switch (command) {
       }
     } else if (subcommand === 'cleanup') {
       const workCommands = require('./lib/work-commands/index.js');
-      const dryRun = args[0] === '--dry-run';
+      const dryRun = args.includes('--dry-run');
+      // Find numeric arg for specific work item cleanup
+      const workItemId = args.find(a => /^\d+$/.test(a)) ? parseInt(args.find(a => /^\d+$/.test(a))) : null;
 
       try {
-        const results = await workCommands.cleanupWorktrees({ dryRun });
-
-        if (results.cleaned === 0 && results.failed === 0) {
-          console.log(`\n${results.message || 'No worktrees needed cleanup'}`);
+        if (workItemId) {
+          // Clean up specific work item's worktree
+          await workCommands.cleanupWorkItem(workItemId);
         } else {
-          console.log(`\n✓ Cleanup complete:`);
-          console.log(`  Cleaned: ${results.cleaned}`);
-          if (results.failed > 0) {
-            console.log(`  Failed: ${results.failed}`);
+          // Batch cleanup of all orphaned worktrees
+          const results = await workCommands.cleanupWorktrees({ dryRun });
+
+          if (results.cleaned === 0 && results.failed === 0) {
+            console.log(`\n${results.message || 'No worktrees needed cleanup'}`);
+          } else {
+            console.log(`\n✓ Cleanup complete:`);
+            console.log(`  Cleaned: ${results.cleaned}`);
+            if (results.failed > 0) {
+              console.log(`  Failed: ${results.failed}`);
+            }
           }
         }
       } catch (err) {
@@ -2125,6 +2134,16 @@ switch (command) {
           }
         }
 
+        // Start WebSocket server for real-time updates
+        const WS_PORT = 8080;
+        const { getDbPath } = require('./lib/database');
+        try {
+          await wsServer.start(WS_PORT, { dbPath: getDbPath() });
+        } catch (err) {
+          // WebSocket server failed to start (port in use?) - continue without it
+          console.log('⚠️  WebSocket server unavailable (real-time updates disabled)');
+        }
+
         // Start dashboard in background with project path
         console.log('🚀 Starting dashboard...');
         const dashboardProcess = spawn('npm', ['run', 'start', '--', '-p', String(availablePort)], {
@@ -2133,7 +2152,8 @@ switch (command) {
           stdio: 'ignore',
           env: {
             ...process.env,
-            JETTYPOD_PROJECT_PATH: process.cwd()
+            JETTYPOD_PROJECT_PATH: process.cwd(),
+            JETTYPOD_WS_PORT: String(WS_PORT)
           }
         });
         dashboardProcess.unref();

package/lib/db-watcher.js

@@ -0,0 +1,116 @@
+/**
+ * Database change watcher for triggering WebSocket broadcasts.
+ *
+ * Watches the .jettypod/work.db file and its WAL file for modifications
+ * and calls a callback when changes are detected.
+ *
+ * Usage:
+ *   const dbWatcher = require('./lib/db-watcher');
+ *   dbWatcher.start((changeType) => {
+ *     wsServer.broadcast({ type: 'db_change' });
+ *   });
+ *   dbWatcher.stop();
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let lastMtimes = { db: null, wal: null };
+let pollInterval = null;
+let onChange = null;
+let watchedPath = null;
+
+// Polling interval in milliseconds
+const POLL_MS = 50;
+
+/**
+ * Start watching the database file for changes
+ * @param {Function} callback - Called when database changes detected
+ * @param {string} dbPath - Path to database file (default: .jettypod/work.db)
+ */
+function start(callback, dbPath = null) {
+  if (pollInterval) {
+    return; // Already watching
+  }
+
+  onChange = callback;
+  watchedPath = dbPath || path.join(process.cwd(), '.jettypod', 'work.db');
+
+  // Check if file exists
+  if (!fs.existsSync(watchedPath)) {
+    return;
+  }
+
+  // Get initial mtimes for both db and WAL file
+  try {
+    const dbStats = fs.statSync(watchedPath);
+    lastMtimes.db = dbStats.mtimeMs;
+
+    // Also check WAL file (SQLite in WAL mode writes here first)
+    const walPath = watchedPath + '-wal';
+    if (fs.existsSync(walPath)) {
+      const walStats = fs.statSync(walPath);
+      lastMtimes.wal = walStats.mtimeMs;
+    }
+  } catch {
+    return;
+  }
+
+  // Use polling - most reliable for SQLite files across platforms
+  pollInterval = setInterval(() => {
+    try {
+      let changed = false;
+
+      // Check main db file
+      const dbStats = fs.statSync(watchedPath);
+      if (dbStats.mtimeMs !== lastMtimes.db) {
+        lastMtimes.db = dbStats.mtimeMs;
+        changed = true;
+      }
+
+      // Check WAL file (where SQLite writes first in WAL mode)
+      const walPath = watchedPath + '-wal';
+      if (fs.existsSync(walPath)) {
+        const walStats = fs.statSync(walPath);
+        if (walStats.mtimeMs !== lastMtimes.wal) {
+          lastMtimes.wal = walStats.mtimeMs;
+          changed = true;
+        }
+      }
+
+      if (changed && onChange) {
+        onChange('change');
+      }
+    } catch {
+      // File might be temporarily locked during writes
+    }
+  }, POLL_MS);
+}
+
+/**
+ * Stop watching the database file
+ */
+function stop() {
+  if (pollInterval) {
+    clearInterval(pollInterval);
+    pollInterval = null;
+  }
+
+  onChange = null;
+  lastMtimes = { db: null, wal: null };
+  watchedPath = null;
+}
+
+/**
+ * Check if currently watching
+ * @returns {boolean}
+ */
+function isWatching() {
+  return pollInterval !== null;
+}
+
+module.exports = {
+  start,
+  stop,
+  isWatching,
+};

package/lib/work-commands/index.js

@@ -1130,6 +1130,106 @@ async function cleanupWorktrees(options = {}) {
   return results;
 }
 
+/**
+ * Clean up a specific worktree after merge
+ * Should be run from main repo after cd'ing out of the worktree
+ * @param {number} workItemId - The work item ID to clean up
+ * @returns {Promise<Object>} Result with success status
+ */
+async function cleanupWorkItem(workItemId) {
+  const db = getDb();
+  const gitRoot = getGitRoot();
+
+  // Check we're not inside the worktree being deleted
+  const cwd = process.cwd();
+  if (cwd.includes('.jettypod-work')) {
+    return Promise.reject(new Error(
+      `Cannot cleanup from inside a worktree.\n\n` +
+      `Run this first: cd ${gitRoot}`
+    ));
+  }
+
+  // Find the worktree for this work item
+  const worktree = await new Promise((resolve, reject) => {
+    db.get(
+      `SELECT w.id, w.worktree_path, w.branch_name, w.status, wi.title
+       FROM worktrees w
+       JOIN work_items wi ON w.work_item_id = wi.id
+       WHERE w.work_item_id = ?`,
+      [workItemId],
+      (err, row) => {
+        if (err) return reject(err);
+        resolve(row);
+      }
+    );
+  });
+
+  if (!worktree) {
+    console.log(`No worktree found for work item #${workItemId}`);
+    return { success: true, message: 'No worktree to clean up' };
+  }
+
+  if (worktree.status === 'active') {
+    return Promise.reject(new Error(
+      `Worktree for #${workItemId} is still active.\n` +
+      `Run 'jettypod work merge ${workItemId}' first.`
+    ));
+  }
+
+  console.log(`Cleaning up worktree for #${workItemId}: ${worktree.title}`);
+
+  // Remove git worktree if it exists
+  if (worktree.worktree_path && fs.existsSync(worktree.worktree_path)) {
+    try {
+      execSync(`git worktree remove "${worktree.worktree_path}" --force`, {
+        cwd: gitRoot,
+        stdio: 'pipe'
+      });
+      console.log('✅ Removed worktree directory');
+    } catch (err) {
+      console.log(`⚠️  Failed to remove worktree directory: ${err.message}`);
+    }
+  }
+
+  // Delete the branch if it exists
+  if (worktree.branch_name) {
+    try {
+      execSync(`git branch -d "${worktree.branch_name}"`, {
+        cwd: gitRoot,
+        stdio: 'pipe'
+      });
+      console.log('✅ Deleted branch');
+    } catch (err) {
+      // Branch might not exist or might not be fully merged
+      // Try force delete if regular delete failed
+      try {
+        execSync(`git branch -D "${worktree.branch_name}"`, {
+          cwd: gitRoot,
+          stdio: 'pipe'
+        });
+        console.log('✅ Deleted branch (force)');
+      } catch {
+        console.log(`⚠️  Could not delete branch: ${err.message}`);
+      }
+    }
+  }
+
+  // Delete worktree record from database
+  await new Promise((resolve, reject) => {
+    db.run(
+      `DELETE FROM worktrees WHERE id = ?`,
+      [worktree.id],
+      (err) => {
+        if (err) return reject(err);
+        resolve();
+      }
+    );
+  });
+
+  console.log('✅ Worktree cleaned up');
+  return { success: true };
+}
+
 // Re-export getCurrentWork from shared module for backwards compatibility
 // (used by jettypod.js)
 
@@ -1590,37 +1690,32 @@ async function mergeWork(options = {}) {
       );
     });
 
-    // Clean up worktree if it exists
-    if (worktree && worktree.worktree_path && fs.existsSync(worktree.worktree_path)) {
-      console.log('Cleaning up worktree...');
-      try {
-        // Remove the git worktree
-        execSync(`git worktree remove "${worktree.worktree_path}" --force`, {
-          cwd: gitRoot,
-          stdio: 'pipe'
-        });
-
-        // Delete worktree record from database
-        await new Promise((resolve, reject) => {
-          db.run(
-            `DELETE FROM worktrees WHERE id = ?`,
-            [worktree.id],
-            (err) => {
-              if (err) return reject(err);
-              resolve();
-            }
-          );
-        });
-
-        console.log('✅ Worktree cleaned up');
-      } catch (worktreeErr) {
-        console.warn(`Warning: Failed to clean up worktree: ${worktreeErr.message}`);
-        // Non-fatal - continue with merge success
-      }
+    // Mark worktree as merged but DON'T delete it yet
+    // This prevents shell CWD corruption when merge is run from inside the worktree
+    // User must run `jettypod work cleanup` separately after cd'ing to main repo
+    if (worktree && worktree.worktree_path) {
+      await new Promise((resolve, reject) => {
+        db.run(
+          `UPDATE worktrees SET status = 'merged' WHERE id = ?`,
+          [worktree.id],
+          (err) => {
+            if (err) return reject(err);
+            resolve();
+          }
+        );
+      });
     }
 
     console.log(`✅ Work item #${currentWork.id} marked as done`);
 
+    // Instruct user to cleanup worktree separately
+    if (worktree && worktree.worktree_path && fs.existsSync(worktree.worktree_path)) {
+      console.log('');
+      console.log('📁 Worktree preserved. To clean up:');
+      console.log(`   cd ${gitRoot}`);
+      console.log(`   jettypod work cleanup ${currentWork.id}`);
+    }
+
     if (withTransition) {
       // Hold lock for transition phase (BDD generation)
       // Work is done and worktree is cleaned up, but lock is held so no other merges
@@ -1885,34 +1980,11 @@ async function testsMerge(featureId) {
     console.log('⚠️  Failed to push (non-fatal):', err.message);
   }
 
-  // Clean up the worktree
-  try {
-    execSync(`git worktree remove "${worktreePath}" --force`, {
-      cwd: gitRoot,
-      encoding: 'utf8',
-      stdio: 'pipe'
-    });
-    console.log('✅ Removed worktree directory');
-  } catch (err) {
-    console.log('⚠️  Failed to remove worktree (non-fatal):', err.message);
-  }
-
-  // Delete the test branch
-  try {
-    execSync(`git branch -d ${branchName}`, {
-      cwd: gitRoot,
-      encoding: 'utf8',
-      stdio: 'pipe'
-    });
-    console.log('✅ Deleted test branch');
-  } catch (err) {
-    console.log('⚠️  Failed to delete branch (non-fatal):', err.message);
-  }
-
-  // Delete worktree record from database (cleanup complete)
+  // Mark worktree as merged but DON'T delete it yet
+  // This prevents shell CWD corruption when merge is run from inside the worktree
   await new Promise((resolve, reject) => {
     db.run(
-      `DELETE FROM worktrees WHERE id = ?`,
+      `UPDATE worktrees SET status = 'merged' WHERE id = ?`,
       [worktree.id],
       (err) => {
         if (err) return reject(err);
@@ -1930,6 +2002,14 @@ async function testsMerge(featureId) {
   console.log('');
   console.log(`✅ Test worktree for feature #${featureId} merged successfully`);
 
+  // Instruct user to cleanup worktree separately
+  if (fs.existsSync(worktreePath)) {
+    console.log('');
+    console.log('📁 Worktree preserved. To clean up:');
+    console.log(`   cd ${gitRoot}`);
+    console.log(`   jettypod work cleanup ${featureId}`);
+  }
+
   return Promise.resolve();
 }
 
@@ -1938,6 +2018,7 @@ module.exports = {
   stopWork,
   getCurrentWork,
   cleanupWorktrees,
+  cleanupWorkItem,
   mergeWork,
   testsWork,
   testsMerge

package/lib/ws-server.js

@@ -0,0 +1,126 @@
+/**
+ * WebSocket server for broadcasting database changes to connected dashboard clients.
+ *
+ * Usage:
+ *   const wsServer = require('./lib/ws-server');
+ *   await wsServer.start();  // Start on port 8080 and watch for db changes
+ *   wsServer.broadcast({ type: 'db_change' });  // Manual broadcast to all clients
+ *   await wsServer.stop();  // Graceful shutdown
+ */
+
+const { WebSocketServer } = require('ws');
+const dbWatcher = require('./db-watcher');
+
+const DEFAULT_PORT = 8080;
+
+let wss = null;
+const clients = new Set();
+
+/**
+ * Start the WebSocket server
+ * @param {number} port - Port to listen on (default: 8080)
+ * @param {object} options - Options { dbPath: string }
+ * @returns {Promise<void>}
+ */
+async function start(port = DEFAULT_PORT, options = {}) {
+  if (wss) {
+    return; // Already running
+  }
+
+  return new Promise((resolve, reject) => {
+    wss = new WebSocketServer({ port });
+
+    wss.on('listening', () => {
+      // Start watching database for changes
+      dbWatcher.start(() => {
+        broadcast({ type: 'db_change', timestamp: Date.now() });
+      }, options.dbPath);
+      resolve();
+    });
+
+    wss.on('error', (error) => {
+      wss = null;
+      reject(error);
+    });
+
+    wss.on('connection', (ws) => {
+      clients.add(ws);
+
+      // Send connected confirmation
+      ws.send(JSON.stringify({ type: 'connected', timestamp: Date.now() }));
+
+      ws.on('close', () => {
+        clients.delete(ws);
+      });
+
+      ws.on('error', () => {
+        clients.delete(ws);
+      });
+    });
+  });
+}
+
+/**
+ * Stop the WebSocket server
+ * @returns {Promise<void>}
+ */
+async function stop() {
+  // Stop database watcher
+  dbWatcher.stop();
+
+  if (!wss) {
+    return;
+  }
+
+  return new Promise((resolve) => {
+    // Close all client connections
+    for (const client of clients) {
+      client.close();
+    }
+    clients.clear();
+
+    // Close the server
+    wss.close(() => {
+      wss = null;
+      resolve();
+    });
+  });
+}
+
+/**
+ * Broadcast a message to all connected clients
+ * @param {object} message - Message to broadcast (will be JSON stringified)
+ */
+function broadcast(message) {
+  const data = JSON.stringify(message);
+  for (const client of clients) {
+    if (client.readyState === 1) { // WebSocket.OPEN
+      client.send(data);
+    }
+  }
+}
+
+/**
+ * Get the number of connected clients
+ * @returns {number}
+ */
+function getClientCount() {
+  return clients.size;
+}
+
+/**
+ * Check if the server is running
+ * @returns {boolean}
+ */
+function isRunning() {
+  return wss !== null;
+}
+
+module.exports = {
+  start,
+  stop,
+  broadcast,
+  getClientCount,
+  isRunning,
+  DEFAULT_PORT,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.65",
+  "version": "4.4.67",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {

package/skills-templates/chore-mode/SKILL.md

@@ -373,22 +373,23 @@ git commit -m "chore: [brief description]"
 git push
 ```
 
-**🚨 CRITICAL: Shell CWD Corruption Prevention**
+**Merge and cleanup (3 steps):**
 
-The merge will delete the worktree. You must be in the main repo BEFORE merging.
+```bash
+# Step 1: Merge (can run from worktree - it won't delete it)
+jettypod work merge [chore-id]
+```
 
 ```bash
-# First, cd to the main repo (worktrees are in .jettypod-work/ inside main repo)
+# Step 2: cd to main repo
 cd /path/to/main/repo
-
-# Verify you're in the main repo
-pwd && ls .jettypod
-
-# Then merge (pass the work item ID explicitly)
-jettypod work merge [chore-id]
+pwd && ls .jettypod  # verify
 ```
 
-**Why not `cd $(git rev-parse --show-toplevel)/..`?** Inside a worktree, `--show-toplevel` returns the worktree path, not the main repo. Going `..` from there doesn't reach the main repo.
+```bash
+# Step 3: Clean up the worktree (now safe since shell is in main repo)
+jettypod work cleanup [chore-id]
+```
 
 **Display:**
 

package/skills-templates/feature-planning/SKILL.md

@@ -653,8 +653,10 @@ Write your BDD files to:
   <worktree>/features/email-login.feature
   <worktree>/features/step_definitions/email-login.steps.js
 
-When done, cd to main repo and merge:
-  cd /path/to/main/repo && jettypod work tests merge 42
+When done, merge then cleanup:
+  jettypod work tests merge 42
+  cd /path/to/main/repo
+  jettypod work cleanup 42
 ```
 
 **🛑 STOP AND CHECK:** Verify worktree was created successfully. If you see an error, investigate before continuing.

package/skills-templates/speed-mode/SKILL.md

@@ -613,28 +613,25 @@ More speed mode chores remain. Starting next chore:
 
 **Merge and start next:**
 
-**🚨 CRITICAL: Shell CWD Corruption Prevention**
-
-The merge will delete the worktree. You must be in the main repo BEFORE merging.
-
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of what was implemented]"
 ```
 
 ```bash
-# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
-cd /path/to/main/repo
-
-# Verify you're in the main repo
-pwd && ls .jettypod
-
-# Then merge
+# Step 1: Merge (can run from worktree - it won't delete it)
 jettypod work merge [current-chore-id]
 ```
 
 ```bash
-# Start next chore
+# Step 2: cd to main repo
+cd /path/to/main/repo
+pwd && ls .jettypod  # verify
+```
+
+```bash
+# Step 3: Clean up the worktree, then start next chore
+jettypod work cleanup [current-chore-id]
 jettypod work start [next-chore-id]
 ```
 
@@ -674,29 +671,28 @@ npx cucumber-js <scenario-file-path> --name "User can reach" --format progress
 
 #### Step 7B: Merge Final Speed Chore
 
-**🚨 CRITICAL: Shell CWD Corruption Prevention**
-
-The merge will delete the worktree. You must be in the main repo BEFORE merging.
-
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of what was implemented]"
 ```
 
 ```bash
-# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
-cd /path/to/main/repo
-
-# Verify you're in the main repo
-pwd && ls .jettypod
-
-# Then merge with transition flag
+# Step 1: Merge with transition flag (can run from worktree - it won't delete it)
 jettypod work merge [current-chore-id] --with-transition
 ```
 
-**Why not `cd $(git rev-parse --show-toplevel)/..`?** Inside a worktree, `--show-toplevel` returns the worktree path, not the main repo. Going `..` from there doesn't reach the main repo.
+```bash
+# Step 2: cd to main repo
+cd /path/to/main/repo
+pwd && ls .jettypod  # verify
+```
+
+```bash
+# Step 3: Clean up the worktree
+jettypod work cleanup [current-chore-id]
+```
 
-After merge, you are on main branch. Ready to generate stable mode scenarios.
+After cleanup, you are on main branch. Ready to generate stable mode scenarios.
 
 #### Step 7C: Generate and Propose Stable Mode Chores
 

package/skills-templates/stable-mode/SKILL.md

@@ -572,28 +572,25 @@ More stable mode chores remain. Starting next chore:
 
 **Merge and start next:**
 
-**🚨 CRITICAL: Shell CWD Corruption Prevention**
-
-The merge will delete the worktree. You must be in the main repo BEFORE merging.
-
 ```bash
 # Commit changes in the worktree
 git add . && git commit -m "feat: [brief description of error handling added]"
 ```
 
 ```bash
-# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
-cd /path/to/main/repo
-
-# Verify you're in the main repo
-pwd && ls .jettypod
-
-# Then merge
+# Step 1: Merge (can run from worktree - it won't delete it)
 jettypod work merge [current-chore-id]
 ```
 
 ```bash
-# Start next chore
+# Step 2: cd to main repo
+cd /path/to/main/repo
+pwd && ls .jettypod  # verify
+```
+
+```bash
+# Step 3: Clean up the worktree, then start next chore
+jettypod work cleanup [current-chore-id]
 jettypod work start [next-chore-id]
 ```
 
@@ -613,21 +610,24 @@ If the query returns no remaining chores, proceed to Step 7.
 
 **First, merge the final stable chore:**
 
-**🚨 CRITICAL: Shell CWD Corruption Prevention**
-
 ```bash
 git add . && git commit -m "feat: [brief description of error handling added]"
 ```
 
 ```bash
-# cd to the main repo first (worktrees are in .jettypod-work/ inside main repo)
-cd /path/to/main/repo
+# Step 1: Merge (can run from worktree - it won't delete it)
+jettypod work merge [current-chore-id]
+```
 
-# Verify you're in the main repo
-pwd && ls .jettypod
+```bash
+# Step 2: cd to main repo
+cd /path/to/main/repo
+pwd && ls .jettypod  # verify
+```
 
-# Then merge
-jettypod work merge [current-chore-id]
+```bash
+# Step 3: Clean up the worktree
+jettypod work cleanup [current-chore-id]
 ```
 
 **Then check project state:**