jettypod 4.4.118 → 4.4.121

package/jettypod.js

@@ -496,9 +496,9 @@ Skills auto-activate and MUST complete their full workflow:
 ✅ ALWAYS let skills complete autonomously before taking manual actions
 
 ## Basic Commands (for non-workflow operations)
-jettypod work create epic "<title>"
-jettypod work create feature "<title>" --parent=<id>
-jettypod work create chore "<title>" --parent=<id>
+# To create work items: Write JSON to /tmp/jettypod-create.json, then:
+jettypod work create --from=/tmp/jettypod-create.json
+# JSON format: {"type":"epic|feature|chore|bug","title":"...","description":"...","parent":<id>}
 jettypod work start <id>              # Creates worktree branch
 jettypod work merge                   # Merges worktree back to main
 jettypod work cleanup <id>            # Cleanup worktree after merge
@@ -565,6 +565,39 @@ Be direct and opinionated. Skip hedging, apologies, and excessive politeness. Le
     // Default for missing project name
     const projectName = config.name || 'unknown-project';
 
+    // Design system context injection
+    let designSystemSection = '';
+    const designSystemDir = config.designSystemDir;
+    if (designSystemDir && typeof designSystemDir === 'string' && fs.existsSync(designSystemDir)) {
+      const allowedExts = ['.css', '.scss', '.less', '.ts', '.tsx', '.js', '.jsx', '.json', '.md', '.txt'];
+      const files = fs.readdirSync(designSystemDir).filter(f => {
+        const ext = path.extname(f).toLowerCase();
+        return allowedExts.includes(ext);
+      }).sort();
+
+      if (files.length > 0) {
+        let fileContents = '';
+        for (const file of files) {
+          const filePath = path.join(designSystemDir, file);
+          try {
+            const stat = fs.statSync(filePath);
+            if (stat.isFile()) {
+              const content = fs.readFileSync(filePath, 'utf-8');
+              fileContents += `\n### ${file}\n\`\`\`\n${content}\n\`\`\`\n`;
+            }
+          } catch (e) {
+            // Skip unreadable files
+          }
+        }
+        if (fileContents) {
+          designSystemSection = `
+<design_system>
+## Design System Reference
+${fileContents}</design_system>`;
+        }
+      }
+    }
+
     return `<claude_context project="${projectName}">
 ${currentWorkSection}
 <project_state>
@@ -573,7 +606,7 @@ ${projectState} - ${projectStateDescription}
 <tech_stack>
 ${techStack}
 </tech_stack>${modeTag}
-</claude_context>${jettypodEssentials}
+</claude_context>${designSystemSection}${jettypodEssentials}
 ${communicationStyle}
 ${outputRules}`;
   },
@@ -671,8 +704,58 @@ async function generateClaude(options = {}) {
   }
 }
 
+/**
+ * Sync Claude hook files from claude-hooks/ source templates to .jettypod/hooks/
+ * Uses content hashing — only copies when source differs from installed.
+ * Called on every CLI invocation via ensureClaudeHooks().
+ */
+function syncClaudeHookFiles() {
+  const sourceDir = path.join(__dirname, 'claude-hooks');
+  const destDir = path.join('.jettypod', 'hooks');
+
+  if (!fs.existsSync(sourceDir) || !fs.existsSync('.jettypod')) {
+    return; // No source hooks or no jettypod project
+  }
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  // Only sync the 3 hooks that are installed by init
+  const hooksToSync = [
+    'global-guardrails.js',
+    'protect-claude-md.js',
+    'enforce-skill-activation.js'
+  ];
+
+  const crypto = require('crypto');
+  const hash = (content) => crypto.createHash('md5').update(content).digest('hex');
+
+  for (const hookFile of hooksToSync) {
+    const sourcePath = path.join(sourceDir, hookFile);
+    const destPath = path.join(destDir, hookFile);
+
+    if (!fs.existsSync(sourcePath)) continue;
+
+    const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
+
+    // Skip if installed hook is already up to date
+    if (fs.existsSync(destPath)) {
+      const destContent = fs.readFileSync(destPath, 'utf-8');
+      if (hash(sourceContent) === hash(destContent)) continue;
+    }
+
+    fs.copyFileSync(sourcePath, destPath);
+    fs.chmodSync(destPath, 0o755);
+  }
+}
+
 // Ensure Claude Code hooks are up to date (called on every jettypod launch)
 function ensureClaudeHooks() {
+  // Sync hook FILES from claude-hooks/ source templates to .jettypod/hooks/
+  // Uses content hashing — only copies when source differs from installed
+  syncClaudeHookFiles();
+
   // Create .claude directory if needed
   if (!fs.existsSync('.claude')) {
     fs.mkdirSync('.claude', { recursive: true });
@@ -1233,6 +1316,15 @@ if (fs.existsSync('.git')) {
 // Runs independently of .git check since subdirectories don't have .git files
 ensureJettypodSymlink();
 
+// Sync Claude Code hook files and settings on every CLI invocation
+if (fs.existsSync('.jettypod')) {
+  try {
+    ensureClaudeHooks();
+  } catch (err) {
+    // Don't fail CLI if hook sync fails
+  }
+}
+
 if (!commandsWithoutDb.includes(command) && fs.existsSync('.jettypod')) {
   try {
     const { validateOnStartup } = require('./lib/database');
@@ -1250,7 +1342,8 @@ if (!commandsWithoutDb.includes(command) && fs.existsSync('.jettypod')) {
         console.log(`🧹 Cleaned ${cleaned} stale merge lock(s) from previous session`);
       }
     } catch (lockCleanupErr) {
-      // Non-fatal: don't block CLI startup if cleanup fails
+      // Non-fatal: don't block CLI startup, but log so failures are visible
+      console.warn(`Warning: Merge lock cleanup failed: ${lockCleanupErr.message}`);
     }
   } catch (err) {
     console.error('');
@@ -1264,110 +1357,10 @@ if (!commandsWithoutDb.includes(command) && fs.existsSync('.jettypod')) {
 
 switch (command) {
   case 'update': {
-    // Update jettypod to latest version
+    // CLI is bundled with the app — no independent update mechanism
     const updateCommand = require('./lib/update-command');
-    const success = await updateCommand.runUpdate();
-
-    // Always refresh skills and hooks in current project after update attempt
-    if (fs.existsSync('.jettypod')) {
-      // Update Claude Code hooks first
-      ensureClaudeHooks();
-
-      console.log('');
-      console.log('🔄 Refreshing skills in current project...');
-
-      // Use the existing skills update logic from initializeProject
-      // Allow tests to override skills source directory
-      const skillsSourceDir = process.env.JETTYPOD_SKILLS_SOURCE_DIR ||
-                              path.join(__dirname, 'skills-templates');
-      const skillsDestDir = path.join('.claude', 'skills');
-      let backupDir = null;
-
-      // Backup existing skills before updating
-      if (fs.existsSync(skillsDestDir)) {
-        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-        backupDir = path.join('.claude', `skills.backup-${timestamp}`);
-
-        let counter = 1;
-        while (fs.existsSync(backupDir)) {
-          backupDir = path.join('.claude', `skills.backup-${timestamp}-${counter}`);
-          counter++;
-        }
-
-        try {
-          fs.renameSync(skillsDestDir, backupDir);
-
-          if (!fs.existsSync(backupDir)) {
-            throw new Error('Backup directory was not created');
-          }
-
-          const backupContents = fs.readdirSync(backupDir);
-          if (backupContents.length === 0) {
-            throw new Error('Backup directory is empty');
-          }
-
-          console.log(`💾 Backed up existing skills to ${backupDir}`);
-        } catch (err) {
-          console.error(`❌ Could not backup skills: ${err.message}`);
-          throw new Error(`Could not backup existing skills: ${err.message}`);
-        }
-      }
-
-      // Copy skills from jettypod to project
-      if (!fs.existsSync(skillsSourceDir)) {
-        console.warn('⚠️  Skills source directory not found');
-      } else {
-        try {
-          const copyRecursive = (src, dest) => {
-            if (!fs.existsSync(dest)) {
-              fs.mkdirSync(dest, { recursive: true });
-            }
-            const entries = fs.readdirSync(src, { withFileTypes: true });
-            for (const entry of entries) {
-              const srcPath = path.join(src, entry.name);
-              const destPath = path.join(dest, entry.name);
-              if (entry.isDirectory()) {
-                copyRecursive(srcPath, destPath);
-              } else {
-                fs.copyFileSync(srcPath, destPath);
-              }
-            }
-          };
-
-          copyRecursive(skillsSourceDir, skillsDestDir);
-          console.log('✅ Skills refreshed');
-        } catch (err) {
-          console.error(`❌ Could not refresh skills: ${err.message}`);
-        }
-      }
-
-      // Ensure session.md is gitignored (fixes existing projects)
-      ensureJettypodGitignores();
-
-      // Auto-commit any changes made by update (skills, hooks, gitignore, etc.)
-      // This prevents untracked changes from breaking worktree merges
-      try {
-        const { execSync } = require('child_process');
-        // Check if there are any changes to commit
-        const status = execSync('git status --porcelain', { encoding: 'utf-8' });
-        if (status.trim()) {
-          execSync('git add -A');
-          // Use --no-verify to bypass pre-commit hooks - this is an automated system update
-          execSync('git commit --no-verify -m "chore: jettypod update - refresh skills and hooks"');
-          console.log('✅ Update changes committed');
-        }
-      } catch (err) {
-        // Log the error so users know what happened
-        console.log('');
-        console.log('⚠️  Could not auto-commit skill updates');
-        console.log('   Reason:', err.message.split('\n')[0]);
-        console.log('');
-        console.log('   You may have untracked changes in .claude/skills/');
-        console.log('   Run: git add .claude && git commit -m "chore: update skills"');
-      }
-    }
-
-    process.exit(success ? 0 : 1);
+    await updateCommand.runUpdate();
+    process.exit(0);
     break;
   }
 
@@ -1454,13 +1447,14 @@ switch (command) {
     } else if (subcommand === 'cleanup') {
       const workCommands = require('./lib/work-commands/index.js');
       const dryRun = args.includes('--dry-run');
+      const force = args.includes('--force');
       // 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 {
         if (workItemId) {
           // Clean up specific work item's worktree
-          await workCommands.cleanupWorkItem(workItemId);
+          await workCommands.cleanupWorkItem(workItemId, { force });
         } else {
           // Batch cleanup of all orphaned worktrees
           const results = await workCommands.cleanupWorktrees({ dryRun });
@@ -1483,12 +1477,11 @@ switch (command) {
       const workCommands = require('./lib/work-commands/index.js');
       try {
         // Parse merge flags and optional work item ID from args
-        const withTransition = args.includes('--with-transition');
         const releaseLock = args.includes('--release-lock');
         // Find numeric arg that isn't a flag
         const workItemId = args.find(a => /^\d+$/.test(a)) ? parseInt(args.find(a => /^\d+$/.test(a))) : null;
 
-        await workCommands.mergeWork({ withTransition, releaseLock, workItemId });
+        await workCommands.mergeWork({ releaseLock, workItemId });
       } catch (err) {
         console.error(`Error: ${err.message}`);
         process.exit(1);
@@ -2353,7 +2346,33 @@ switch (command) {
     break;
   }
 
-  case undefined:
+  case undefined: {
+    // Auto-update: if running from a stale global install, reinstall from source
+    // Skip in worktrees - worktree copies always differ from source and updating
+    // the global install won't change the worktree file, causing infinite recursion
+    const devLinkPath = path.join(require('os').homedir(), '.jettypod-dev.json');
+    if (fs.existsSync(devLinkPath) && !__dirname.includes('.jettypod-work')) {
+      try {
+        const devInfo = JSON.parse(fs.readFileSync(devLinkPath, 'utf-8'));
+        const sourceDir = devInfo.sourceDir;
+        if (sourceDir && fs.existsSync(path.join(sourceDir, 'jettypod.js'))) {
+          const sourceContent = fs.readFileSync(path.join(sourceDir, 'jettypod.js'));
+          const installedContent = fs.readFileSync(path.join(__dirname, 'jettypod.js'));
+          if (!sourceContent.equals(installedContent)) {
+            console.log('🔄 Source has changed, updating jettypod...');
+            const { execSync: execSyncUpdate } = require('child_process');
+            execSyncUpdate('npm install -g .', { cwd: sourceDir, stdio: 'inherit' });
+            console.log('✅ Updated. Relaunching...');
+            const { execFileSync } = require('child_process');
+            execFileSync(process.argv[0], process.argv.slice(1), { stdio: 'inherit', cwd: process.cwd() });
+            process.exit(0);
+          }
+        }
+      } catch (e) {
+        // Auto-update check failed — continue with current version
+      }
+    }
+
     // Smart detection when no command provided
     if (!fs.existsSync('.jettypod/config.json')) {
       // New project - auto-initialize
@@ -2457,12 +2476,13 @@ switch (command) {
 
         // Start dashboard in dev mode for live reload
         console.log('🚀 Starting dashboard (dev mode)...');
-        const dashboardProcess = spawn('npm', ['run', 'dev', '--', '-p', String(availablePort)], {
+        const dashboardProcess = spawn('npm', ['run', 'dev'], {
           cwd: dashboardPath,
           detached: true,
           stdio: 'ignore',
           env: {
             ...process.env,
+            PORT: String(availablePort),
             JETTYPOD_PROJECT_PATH: process.cwd(),
             JETTYPOD_WS_PORT: String(WS_PORT)
           }
@@ -2520,6 +2540,7 @@ Quick commands:
       }
     }
     break;
+  }
 
   case 'trash': {
     // Trash management commands
@@ -2652,9 +2673,17 @@ Quick commands:
       const impact = graph.getImpact(targetFile);
 
       if (impact.error) {
-        console.error(`\n❌ ${impact.error}`);
-        console.log('');
-        console.log('Make sure the file path is relative to the project root.');
+        console.log(`\n❌ ${impact.error}`);
+        if (impact.suggestions && impact.suggestions.length > 0) {
+          console.log('');
+          console.log('Did you mean one of these?');
+          for (const s of impact.suggestions) {
+            console.log(`  ${s}`);
+          }
+        } else {
+          console.log('');
+          console.log('Make sure the file path is relative to the project root.');
+        }
         process.exit(1);
       }
 

package/lib/bdd-preflight.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function checkCucumberInstalled(projectRoot) {
+  const cucumberPath = path.join(projectRoot, 'node_modules', '@cucumber', 'cucumber');
+  const exists = fs.existsSync(cucumberPath);
+  return {
+    id: 'cucumber-installed',
+    label: '@cucumber/cucumber installed',
+    passed: exists,
+    error: exists ? null : '@cucumber/cucumber is not installed. Run: npm install --save-dev @cucumber/cucumber',
+  };
+}
+
+function checkTestBddScript(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  let hasScript = false;
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      hasScript = !!(pkg.scripts && pkg.scripts['test:bdd']);
+    } catch (_) {
+      // Corrupt or unreadable package.json — treat as missing script
+    }
+  }
+  return {
+    id: 'test-bdd-script',
+    label: 'test:bdd script in package.json',
+    passed: hasScript,
+    error: hasScript ? null : 'Missing "test:bdd" script in package.json. Add: "test:bdd": "NODE_ENV=test cucumber-js"',
+  };
+}
+
+function checkCucumberConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'cucumber.js');
+  const exists = fs.existsSync(configPath);
+  return {
+    id: 'cucumber-config',
+    label: 'cucumber.js config file',
+    passed: exists,
+    error: exists ? null : 'Missing cucumber.js configuration file in project root',
+  };
+}
+
+function checkFeaturesDirectory(projectRoot) {
+  const featuresDir = path.join(projectRoot, 'features');
+  const stepDefsDir = path.join(projectRoot, 'features', 'step_definitions');
+  const exists = fs.existsSync(featuresDir) && fs.existsSync(stepDefsDir);
+  return {
+    id: 'features-directory',
+    label: 'features/ directory with step_definitions/',
+    passed: exists,
+    error: exists ? null : 'Missing features/ directory or features/step_definitions/ subdirectory',
+  };
+}
+
+function checkSupportDirectory(projectRoot) {
+  const supportDir = path.join(projectRoot, 'features', 'support');
+  const hooksFile = path.join(supportDir, 'hooks.js');
+  const exists = fs.existsSync(supportDir) && fs.existsSync(hooksFile);
+  return {
+    id: 'support-hooks',
+    label: 'features/support/hooks.js',
+    passed: exists,
+    error: exists ? null : 'Missing features/support/hooks.js file',
+  };
+}
+
+function buildSetupPrompt(projectRoot, failedChecks) {
+  const missing = failedChecks.map(c => `- ${c.label}: ${c.error}`).join('\n');
+  return `The following BDD test infrastructure is missing in this project:\n\n${missing}\n\nPlease set up the missing BDD test infrastructure so tests can run.`;
+}
+
+function checkBddPrerequisites(projectRoot) {
+  const checks = [
+    checkCucumberInstalled(projectRoot),
+    checkTestBddScript(projectRoot),
+    checkCucumberConfig(projectRoot),
+    checkFeaturesDirectory(projectRoot),
+    checkSupportDirectory(projectRoot),
+  ];
+
+  const ready = checks.every(c => c.passed);
+  const failed = checks.filter(c => !c.passed);
+
+  const result = { ready, checks };
+  if (!ready) {
+    result.setupPrompt = buildSetupPrompt(projectRoot, failed);
+  }
+
+  return result;
+}
+
+module.exports = { checkBddPrerequisites };

package/lib/chore-taxonomy.js

@@ -1,6 +1,10 @@
 /**
  * Chore Type Taxonomy
- * Defines the 4 chore types and their workflow guidance for the chore-planning and chore-mode skills.
+ * Defines the 5 chore types and their workflow guidance for the chore-planning and chore-mode skills.
+ *
+ * Types fall into two categories:
+ * - Behavior-preserving (refactor, dependency, cleanup, tooling): Run existing affected tests, never write new tests
+ * - Behavior-adding (enhancement): TDD with red-green-refactor cycle, writes new tests first
  */
 
 /**
@@ -11,7 +15,8 @@ const CHORE_TYPES = Object.freeze({
   REFACTOR: 'refactor',
   DEPENDENCY: 'dependency',
   CLEANUP: 'cleanup',
-  TOOLING: 'tooling'
+  TOOLING: 'tooling',
+  ENHANCEMENT: 'enhancement'
 });
 
 /**
@@ -33,14 +38,14 @@ const CHORE_TYPE_GUIDANCE = Object.freeze({
       'Consider breaking into smaller refactors if scope is large'
     ],
     verification: [
-      'All existing tests pass without modification',
+      'Affected 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.'
+      approach: 'Run tests for affected and potentially impacted modules. Update test file paths/imports if moved. Do NOT change test assertions - if tests fail, the refactor broke behavior.'
     }
   },
   [CHORE_TYPES.DEPENDENCY]: {
@@ -51,14 +56,14 @@ const CHORE_TYPE_GUIDANCE = Object.freeze({
       'Consider update strategy: one at a time vs batch'
     ],
     verification: [
-      'All tests pass after update',
+      'Affected and potentially impacted 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.'
+      approach: 'Run tests for affected and potentially impacted modules 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]: {
@@ -69,14 +74,14 @@ const CHORE_TYPE_GUIDANCE = Object.freeze({
       'Consider impact on git history/blame'
     ],
     verification: [
-      'All tests still pass',
+      'Affected 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.'
+      approach: 'Run tests for affected modules to ensure nothing breaks. Remove tests only if they test deleted code. No new tests needed for cleanup work.'
     }
   },
   [CHORE_TYPES.TOOLING]: {
@@ -96,6 +101,24 @@ const CHORE_TYPE_GUIDANCE = Object.freeze({
       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.'
     }
+  },
+  [CHORE_TYPES.ENHANCEMENT]: {
+    scope: [
+      'Define what new behavior is being added',
+      'Identify where the behavior integrates with existing code',
+      'Plan test cases BEFORE writing implementation (TDD)',
+      'Keep scope focused - one behavior per chore'
+    ],
+    verification: [
+      'New tests written BEFORE implementation (TDD red phase)',
+      'All new tests pass (TDD green phase)',
+      'Code is clean and well-structured (TDD refactor phase)',
+      'Existing affected tests still pass'
+    ],
+    testHandling: {
+      required: true,
+      approach: 'TDD red-green-refactor: Write failing tests first that define the new behavior, then implement minimum code to pass, then refactor. Run affected tests to ensure no regressions.'
+    }
   }
 });
 
@@ -136,7 +159,7 @@ function isValidChoreType(type) {
 function getGuidance(type) {
   if (type === null || type === undefined) {
     throw new Error(
-      'Chore type is required. Valid types: refactor, dependency, cleanup, tooling'
+      'Chore type is required. Valid types: refactor, dependency, cleanup, tooling, enhancement'
     );
   }
 
@@ -144,7 +167,7 @@ function getGuidance(type) {
 
   if (!normalized || !VALID_CHORE_TYPES.includes(normalized)) {
     throw new Error(
-      `Invalid chore type: "${type}". Valid types: refactor, dependency, cleanup, tooling`
+      `Invalid chore type: "${type}". Valid types: refactor, dependency, cleanup, tooling, enhancement`
     );
   }