specweave 0.32.0 → 0.32.2

package/plugins/specweave/scripts/README.md

@@ -0,0 +1,166 @@
+# SpecWeave Instant Scripts
+
+**Blazingly fast status commands that bypass LLM processing.**
+
+These scripts provide instant (<100ms) output for status queries that don't require AI reasoning.
+
+## Why These Exist
+
+Status commands (`/specweave:status`, `/specweave:progress`, `/specweave:jobs`) were taking 3+ minutes because they expanded as prompts requiring LLM processing. These commands need NO reasoning - they just read JSON and format output.
+
+**Performance comparison:**
+
+| Command | Before | After |
+|---------|--------|-------|
+| `/specweave:status` | 3+ min | <100ms |
+| `/specweave:progress` | 2+ min | <100ms |
+| `/specweave:jobs` | 3+ min | <100ms |
+
+## Scripts
+
+### Bash Scripts (v0.32.0+ - Recommended)
+
+These read from the pre-computed dashboard cache for <10ms response time.
+
+#### read-status.sh - Increment Status Overview
+
+```bash
+bash plugins/specweave/scripts/read-status.sh
+bash plugins/specweave/scripts/read-status.sh 0045  # Specific increment
+```
+
+#### read-progress.sh - Task Completion Progress
+
+```bash
+bash plugins/specweave/scripts/read-progress.sh
+bash plugins/specweave/scripts/read-progress.sh 0045  # Specific increment
+```
+
+#### read-jobs.sh - Background Job Status
+
+```bash
+bash plugins/specweave/scripts/read-jobs.sh
+bash plugins/specweave/scripts/read-jobs.sh --all     # Include completed
+```
+
+### Node.js Scripts (Legacy - Fallback)
+
+These are used when jq is not available or cache doesn't exist.
+
+```bash
+node plugins/specweave/scripts/status.js
+node plugins/specweave/scripts/progress.js
+node plugins/specweave/scripts/jobs.js
+```
+
+## Three Execution Paths
+
+These scripts work across all contexts through a layered architecture:
+
+| Layer | Context | Speed | How It Works |
+|-------|---------|-------|--------------|
+| **Hook** | Claude Code | <100ms | `UserPromptSubmit` intercepts `/specweave:*`, runs script, blocks prompt |
+| **Skill** | Any LLM | ~2s | Skill instructs LLM to run script via Bash |
+| **CLI** | Terminal | ~500ms | `specweave status` / direct `node scripts/*.js` |
+
+### 1. Claude Code (Hook - Fastest)
+
+In Claude Code, the `UserPromptSubmit` hook automatically intercepts status commands:
+
+```
+User types: /specweave:status
+Hook runs: bash plugins/specweave/scripts/read-status.sh
+Output appears instantly (<10ms)
+LLM never processes the prompt
+```
+
+### 2. Other LLMs (Skill - Fast)
+
+In Cursor, Windsurf, Copilot, or API usage, the `instant-status` skill provides instructions:
+
+```
+User types: /specweave:status
+Skill activates and instructs LLM to run the script
+LLM executes: bash plugins/specweave/scripts/read-status.sh
+Output appears (~2s)
+```
+
+### 3. Terminal (CLI - Direct)
+
+Users can run scripts directly without any LLM:
+
+```bash
+# Full CLI command
+specweave status
+specweave jobs
+
+# Direct script execution (bash preferred)
+bash plugins/specweave/scripts/read-status.sh
+bash plugins/specweave/scripts/read-progress.sh 0045
+```
+
+## When to Use Which
+
+| Situation | Recommended Path |
+|-----------|------------------|
+| Quick status check in Claude Code | Just type `/specweave:status` |
+| Using Cursor/Windsurf/Copilot | Let skill guide execution |
+| Terminal/scripting | `specweave status` or `node scripts/*.js` |
+| CI/CD pipelines | Direct `node scripts/*.js` |
+
+## Adding New Instant Commands
+
+To add a new instant command:
+
+1. Create script in `plugins/specweave/scripts/newcmd.js`
+2. Add `--help` handling (required)
+3. Add to hook dispatcher in `plugins/specweave/hooks/user-prompt-submit.sh`
+4. Update `skills/instant-status/SKILL.md` with new command
+5. Test all three paths (hook, skill, CLI)
+
+### Script Template
+
+```javascript
+#!/usr/bin/env node
+/**
+ * Description of what this script does
+ * Usage: node newcmd.js [options] [--help]
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Handle --help (REQUIRED)
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+SpecWeave Instant NewCmd
+
+USAGE
+  node plugins/specweave/scripts/newcmd.js [options]
+
+OPTIONS
+  --help, -h     Show this help message
+
+DESCRIPTION
+  What this command does...
+
+EXECUTION PATHS
+  1. Claude Code:  /specweave:newcmd  (hook intercepts)
+  2. Any LLM:      Skill instructs to run this script
+  3. Terminal:     specweave newcmd
+`);
+  process.exit(0);
+}
+
+// Your implementation here
+const cwd = process.cwd();
+// ...
+```
+
+## Design Principles
+
+1. **Zero LLM tokens**: Pure filesystem reads, no AI reasoning needed
+2. **Single source of truth**: Hook, skill, and CLI all use these same scripts
+3. **Universal compatibility**: Works in Claude Code, Cursor, Copilot, terminal
+4. **Fast feedback**: <100ms response time for status queries
+5. **Self-documenting**: All scripts support `--help`

package/plugins/specweave/scripts/cleanup-state.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# cleanup-state.sh - Emergency state cleanup for stuck sessions
+#
+# Usage: bash cleanup-state.sh [--all]
+#
+# Cleans:
+# - Lock files (.lock, .lock.d, .pid)
+# - Dedup cache files
+# - Stale event queue files (older than 5 minutes)
+#
+# With --all:
+# - Also cleans circuit breaker state
+# - Resets status line cache
+#
+# IMPORTANT: Run this if Claude Code is stuck or hangs
+
+set -e
+
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  echo "❌ No .specweave directory found. Are you in a SpecWeave project?"
+  exit 1
+fi
+
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+
+echo "🧹 SpecWeave State Cleanup"
+echo "=========================="
+echo "Project: $PROJECT_ROOT"
+echo ""
+
+# Kill any zombie processor processes
+echo "→ Killing zombie processes..."
+pkill -f "processor\.sh.*daemon" 2>/dev/null || true
+pkill -f "processor\.js.*daemon" 2>/dev/null || true
+echo "  ✓ Done"
+
+# Kill heredoc zombie processes (CRITICAL - prevents infinite hangs)
+echo "→ Killing heredoc zombies..."
+pkill -f "cat.*EOF" 2>/dev/null || true
+pkill -f "bash.*heredoc" 2>/dev/null || true
+pkill -9 -f "bash.*specweave.*>" 2>/dev/null || true
+echo "  ✓ Done"
+
+# Clean lock files
+echo "→ Cleaning lock files..."
+rm -f "$STATE_DIR"/.processor.pid 2>/dev/null || true
+rm -rf "$STATE_DIR"/.processor.lock.d 2>/dev/null || true
+rm -rf "$STATE_DIR"/.processor.lock 2>/dev/null || true
+echo "  ✓ Done"
+
+# Clean dedup cache
+echo "→ Cleaning dedup cache..."
+rm -rf "$STATE_DIR"/.dedup-cache/*.lock 2>/dev/null || true
+find "$STATE_DIR"/.dedup-cache -type f -mmin +5 -delete 2>/dev/null || true
+echo "  ✓ Done"
+
+# Clean stale event queue files
+echo "→ Cleaning stale event queue..."
+EVENT_QUEUE="$STATE_DIR/event-queue"
+if [[ -d "$EVENT_QUEUE" ]]; then
+  STALE_COUNT=$(find "$EVENT_QUEUE" -name "*.event" -mmin +5 2>/dev/null | wc -l | tr -d ' ')
+  if [[ "$STALE_COUNT" -gt 0 ]]; then
+    find "$EVENT_QUEUE" -name "*.event" -mmin +5 -delete 2>/dev/null
+    echo "  ✓ Removed $STALE_COUNT stale events"
+  else
+    echo "  ✓ No stale events"
+  fi
+else
+  echo "  ✓ No event queue"
+fi
+
+# Full cleanup with --all flag
+if [[ "$1" == "--all" ]]; then
+  echo ""
+  echo "→ Full cleanup (--all)..."
+
+  # Reset circuit breakers
+  echo "  → Resetting circuit breakers..."
+  echo "0" > "$STATE_DIR/.hook-circuit-breaker" 2>/dev/null || true
+  echo "0" > "$STATE_DIR/.hook-circuit-breaker-pre" 2>/dev/null || true
+  echo "  ✓ Done"
+
+  # Reset status line cache
+  echo "  → Resetting status line cache..."
+  rm -f "$STATE_DIR/status-line.json" 2>/dev/null || true
+  echo "  ✓ Done"
+
+  # Clean all US completion state
+  echo "  → Cleaning US completion state..."
+  rm -f "$STATE_DIR"/.us-completion-* 2>/dev/null || true
+  rm -f "$STATE_DIR"/.prev-status-* 2>/dev/null || true
+  echo "  ✓ Done"
+
+  # Clean logs (keep last 10 lines for debugging)
+  echo "  → Trimming logs..."
+  for log in "$LOGS_DIR"/*.log; do
+    if [[ -f "$log" ]]; then
+      tail -10 "$log" > "$log.tmp" 2>/dev/null && mv "$log.tmp" "$log" || rm -f "$log.tmp"
+    fi
+  done
+  echo "  ✓ Done"
+fi
+
+# Check MCP connection issues
+echo "→ Checking MCP connection health..."
+CLAUDE_DEBUG="$HOME/.claude/debug/latest"
+if [[ -f "$CLAUDE_DEBUG" ]]; then
+  MCP_DROPS=$(grep -c "WS-IDE connection dropped" "$CLAUDE_DEBUG" 2>/dev/null | head -1 || echo "0")
+  MCP_DROPS="${MCP_DROPS//[^0-9]/}"  # Strip non-numeric chars
+  MCP_DROPS="${MCP_DROPS:-0}"
+  if [[ "$MCP_DROPS" -gt 0 ]]; then
+    echo "  ⚠️  Found $MCP_DROPS MCP connection drops in latest session"
+    echo ""
+    echo "  MCP FIX OPTIONS:"
+    echo "  1. In VS Code: Cmd+Shift+P → 'Developer: Restart Extension Host'"
+    echo "  2. Close extra files/tabs (reduces diagnostics payload)"
+    echo "  3. Run Claude Code in plain terminal instead"
+    echo ""
+  else
+    echo "  ✓ No MCP drops detected"
+  fi
+else
+  echo "  ✓ No debug log to check"
+fi
+
+echo ""
+echo "✅ Cleanup complete!"
+echo ""
+echo "Next steps:"
+echo "  1. Restart Claude Code"
+echo "  2. Run /specweave:progress to check status"
+echo ""
+echo "If MCP issues persist:"
+echo "  • Update Claude Code VS Code extension"
+echo "  • Use terminal mode: cd project && claude"
+echo ""

package/plugins/specweave/scripts/force-kill.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# force-kill.sh - AGGRESSIVE process killer for stuck Claude Code sessions
+#
+# This script KILLS processes, not just warns about them.
+# Use when Claude Code is stuck and won't respond.
+#
+# Usage:
+#   bash force-kill.sh           # Kill all stuck processes
+#   bash force-kill.sh --dry-run # Show what would be killed
+#
+# What gets killed:
+#   - Heredoc processes (cat.*EOF)
+#   - Stuck node processes from hooks
+#   - Background SpecWeave processors
+#   - Zombie bash processes
+
+set -euo pipefail
+
+DRY_RUN=false
+VERBOSE=false
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+for arg in "$@"; do
+  case $arg in
+    --dry-run|-n)
+      DRY_RUN=true
+      ;;
+    --verbose|-v)
+      VERBOSE=true
+      ;;
+  esac
+done
+
+log() {
+  echo -e "$1"
+}
+
+kill_processes() {
+  local pattern="$1"
+  local desc="$2"
+  local signal="${3:--9}"  # Default to SIGKILL
+
+  local pids
+  pids=$(pgrep -f "$pattern" 2>/dev/null || true)
+
+  if [[ -n "$pids" ]]; then
+    local count
+    count=$(echo "$pids" | wc -l | tr -d ' ')
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+      log "${YELLOW}[DRY-RUN]${NC} Would kill $count $desc process(es):"
+      echo "$pids" | while read -r pid; do
+        ps -p "$pid" -o pid,command 2>/dev/null | tail -1 || true
+      done
+    else
+      log "${RED}Killing${NC} $count $desc process(es)..."
+      echo "$pids" | xargs kill $signal 2>/dev/null || true
+      sleep 0.5
+      # Double-tap with SIGKILL if still alive
+      for pid in $pids; do
+        if kill -0 "$pid" 2>/dev/null; then
+          kill -9 "$pid" 2>/dev/null || true
+        fi
+      done
+    fi
+    return 0
+  fi
+  return 1
+}
+
+# === Main execution ===
+log "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+log "${RED}FORCE KILL - Aggressive Process Termination${NC}"
+log "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+[[ "$DRY_RUN" == "true" ]] && log "${YELLOW}DRY RUN MODE - No processes will be killed${NC}"
+echo
+
+KILLED_ANY=false
+
+# 1. Kill heredoc zombies (most common cause of hangs)
+if kill_processes "cat.*EOF" "heredoc zombie"; then
+  KILLED_ANY=true
+fi
+
+# 2. Kill stuck hook node processes
+if kill_processes "node.*specweave.*hook" "hook node"; then
+  KILLED_ANY=true
+fi
+
+# 3. Kill stuck dispatcher processes
+if kill_processes "dispatcher.mjs" "dispatcher"; then
+  KILLED_ANY=true
+fi
+
+# 4. Kill background processors
+if kill_processes "processor.sh" "background processor"; then
+  KILLED_ANY=true
+fi
+
+# 5. Kill stuck sync processes
+if kill_processes "node.*sync.*specweave" "sync node"; then
+  KILLED_ANY=true
+fi
+
+# 6. Kill any bash processes with specweave in command (older than 60s)
+# This is more aggressive - use pattern carefully
+if kill_processes "bash.*specweave.*hooks" "specweave bash"; then
+  KILLED_ANY=true
+fi
+
+# 7. Clean up lock files
+if [[ "$DRY_RUN" != "true" ]]; then
+  log "\n${GREEN}Cleaning lock files...${NC}"
+  rm -f .specweave/state/.processor.lock 2>/dev/null || true
+  rm -f .specweave/state/.processor.pid 2>/dev/null || true
+  rm -f .specweave/state/.hook-* 2>/dev/null || true
+  rm -rf .specweave/state/.dedup-cache/*.lock 2>/dev/null || true
+  log "  ✓ Lock files cleaned"
+fi
+
+echo
+if [[ "$KILLED_ANY" == "true" ]]; then
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "${YELLOW}Run without --dry-run to kill these processes${NC}"
+  else
+    log "${GREEN}✓ Stuck processes killed${NC}"
+    log ""
+    log "Next steps:"
+    log "  1. Close any stuck Claude Code terminals"
+    log "  2. Start a fresh Claude Code session"
+  fi
+else
+  log "${GREEN}✓ No stuck processes found${NC}"
+fi
+
+log ""
+log "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

package/plugins/specweave/scripts/jobs.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Instant Background Jobs Status
+ *
+ * Executed by UserPromptSubmit hook for /specweave:jobs
+ * Bypasses LLM entirely - output shown directly to user
+ *
+ * Usage: node jobs.js [--all] [--id <jobId>] [--help]
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Handle --help
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+SpecWeave Instant Jobs
+
+USAGE
+  node plugins/specweave/scripts/jobs.js [options]
+  specweave jobs [options]
+
+OPTIONS
+  --help, -h     Show this help message
+  --all          Show all jobs including completed
+  --id <jobId>   Show details for specific job
+
+DESCRIPTION
+  Shows background job status (imports, cloning, sync operations).
+  This script bypasses LLM processing for instant results (<100ms).
+
+EXECUTION PATHS
+  1. Claude Code:  /specweave:jobs  (hook intercepts, <100ms)
+  2. Any LLM:      Skill instructs to run this script (~2s)
+  3. Terminal:     specweave jobs (~500ms)
+
+EXAMPLES
+  node plugins/specweave/scripts/jobs.js
+  node plugins/specweave/scripts/jobs.js --all
+  node plugins/specweave/scripts/jobs.js --id abc123
+  specweave jobs --all
+`);
+  process.exit(0);
+}
+
+const cwd = process.cwd();
+const stateFile = path.join(cwd, '.specweave/state/background-jobs.json');
+const args = process.argv.slice(2);
+
+// Parse arguments
+const showAll = args.includes('--all');
+const idIndex = args.indexOf('--id');
+const specificId = idIndex !== -1 ? args[idIndex + 1] : null;
+
+// Check if state file exists
+if (!fs.existsSync(stateFile)) {
+  console.log('No background jobs found.');
+  console.log('Jobs are created during `specweave init` when importing large datasets.');
+  process.exit(0);
+}
+
+// Read and parse state
+let state;
+try {
+  state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+} catch (e) {
+  console.log('Error reading jobs state:', e.message);
+  process.exit(1);
+}
+
+const jobs = state.jobs || [];
+
+if (jobs.length === 0) {
+  console.log('No background jobs found.');
+  process.exit(0);
+}
+
+// If specific job requested
+if (specificId) {
+  const job = jobs.find(j => j.id === specificId || j.id.startsWith(specificId));
+  if (!job) {
+    console.log(`Job not found: ${specificId}`);
+    process.exit(1);
+  }
+  
+  console.log(`\n📦 Job Details: ${job.id}\n`);
+  console.log(`Type: ${job.type}`);
+  console.log(`Status: ${job.status}`);
+  console.log(`Started: ${job.startedAt}`);
+  console.log(`Updated: ${job.updatedAt}`);
+  
+  const p = job.progress;
+  const pct = p.total > 0 ? Math.round((p.current / p.total) * 100) : 0;
+  console.log(`Progress: ${p.current}/${p.total} (${pct}%)`);
+  
+  if (job.error) {
+    console.log(`Error: ${job.error}`);
+  }
+  process.exit(0);
+}
+
+// Group by status
+const running = jobs.filter(j => j.status === 'running');
+const paused = jobs.filter(j => j.status === 'paused');
+const failed = jobs.filter(j => j.status === 'failed');
+const completed = jobs.filter(j => j.status === 'completed');
+
+console.log('\n📋 Background Jobs\n');
+
+// Running
+if (running.length > 0) {
+  console.log(`🔄 Running (${running.length}):`);
+  for (const job of running) {
+    const p = job.progress;
+    const pct = p.total > 0 ? Math.round((p.current / p.total) * 100) : 0;
+    const elapsed = (Date.now() - new Date(job.startedAt).getTime()) / 1000;
+    const rate = elapsed > 0 ? (p.current / elapsed).toFixed(1) : '0';
+    console.log(`  [${job.id.slice(0,8)}] ${job.type}`);
+    console.log(`     Progress: ${p.current}/${p.total} (${pct}%) | Rate: ${rate}/s`);
+  }
+  console.log('');
+}
+
+// Paused
+if (paused.length > 0) {
+  console.log(`⏸️  Paused (${paused.length}):`);
+  for (const job of paused) {
+    const p = job.progress;
+    const pct = p.total > 0 ? Math.round((p.current / p.total) * 100) : 0;
+    console.log(`  [${job.id.slice(0,8)}] ${job.type} - ${pct}%`);
+  }
+  console.log('');
+}
+
+// Failed
+if (failed.length > 0) {
+  console.log(`❌ Failed (${failed.length}):`);
+  for (const job of failed) {
+    console.log(`  [${job.id.slice(0,8)}] ${job.type}`);
+    if (job.error) {
+      console.log(`     Error: ${job.error}`);
+    }
+  }
+  console.log('');
+}
+
+// Completed (only if --all)
+if (showAll && completed.length > 0) {
+  console.log(`✅ Completed (${completed.length}):`);
+  for (const job of completed.slice(0, 10)) {
+    console.log(`  [${job.id.slice(0,8)}] ${job.type} - ${job.progress.current} items`);
+  }
+  if (completed.length > 10) {
+    console.log(`  ... and ${completed.length - 10} more`);
+  }
+  console.log('');
+}
+
+// Summary if no active jobs
+if (running.length === 0 && paused.length === 0 && failed.length === 0) {
+  if (completed.length > 0) {
+    console.log(`No active jobs. ${completed.length} completed (use --all to see).`);
+  } else {
+    console.log('No jobs found.');
+  }
+}
+
+// Help
+console.log('💡 Commands:');
+console.log('   specweave jobs --id <id>   View job details');
+console.log('   specweave jobs --all       Show completed jobs');