burhan-mop 0.1.0

package/.claude/helpers/daemon-manager.sh

@@ -0,0 +1,252 @@
+#!/bin/bash
+# Claude Flow V3 - Daemon Manager
+# Manages background services for real-time statusline updates
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PID_DIR="$PROJECT_ROOT/.claude-flow/pids"
+LOG_DIR="$PROJECT_ROOT/.claude-flow/logs"
+METRICS_DIR="$PROJECT_ROOT/.claude-flow/metrics"
+
+# Ensure directories exist
+mkdir -p "$PID_DIR" "$LOG_DIR" "$METRICS_DIR"
+
+# PID files
+SWARM_MONITOR_PID="$PID_DIR/swarm-monitor.pid"
+METRICS_DAEMON_PID="$PID_DIR/metrics-daemon.pid"
+
+# Log files
+DAEMON_LOG="$LOG_DIR/daemon.log"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+CYAN='\033[0;36m'
+RESET='\033[0m'
+
+log() {
+    local msg="[$(date '+%Y-%m-%d %H:%M:%S')] $1"
+    echo -e "${CYAN}$msg${RESET}"
+    echo "$msg" >> "$DAEMON_LOG"
+}
+
+success() {
+    local msg="[$(date '+%Y-%m-%d %H:%M:%S')] SUCCESS: $1"
+    echo -e "${GREEN}$msg${RESET}"
+    echo "$msg" >> "$DAEMON_LOG"
+}
+
+error() {
+    local msg="[$(date '+%Y-%m-%d %H:%M:%S')] ERROR: $1"
+    echo -e "${RED}$msg${RESET}"
+    echo "$msg" >> "$DAEMON_LOG"
+}
+
+# Check if a process is running
+is_running() {
+    local pid_file="$1"
+    if [ -f "$pid_file" ]; then
+        local pid=$(cat "$pid_file")
+        if ps -p "$pid" > /dev/null 2>&1; then
+            return 0
+        fi
+    fi
+    return 1
+}
+
+# Start the swarm monitor daemon
+start_swarm_monitor() {
+    local interval="${1:-30}"
+
+    if is_running "$SWARM_MONITOR_PID"; then
+        log "Swarm monitor already running (PID: $(cat "$SWARM_MONITOR_PID"))"
+        return 0
+    fi
+
+    log "Starting swarm monitor daemon (interval: ${interval}s)..."
+
+    # Run the monitor in background
+    nohup "$SCRIPT_DIR/swarm-monitor.sh" monitor "$interval" >> "$LOG_DIR/swarm-monitor.log" 2>&1 &
+    local pid=$!
+
+    echo "$pid" > "$SWARM_MONITOR_PID"
+    success "Swarm monitor started (PID: $pid)"
+
+    return 0
+}
+
+# Start the metrics update daemon
+start_metrics_daemon() {
+    local interval="${1:-60}"  # Default 60 seconds - less frequent updates
+
+    if is_running "$METRICS_DAEMON_PID"; then
+        log "Metrics daemon already running (PID: $(cat "$METRICS_DAEMON_PID"))"
+        return 0
+    fi
+
+    log "Starting metrics daemon (interval: ${interval}s, using SQLite)..."
+
+    # Use SQLite-based metrics (10.5x faster than bash/JSON)
+    # Run as Node.js daemon process
+    nohup node "$SCRIPT_DIR/metrics-db.mjs" daemon "$interval" >> "$LOG_DIR/metrics-daemon.log" 2>&1 &
+    local pid=$!
+
+    echo "$pid" > "$METRICS_DAEMON_PID"
+    success "Metrics daemon started (PID: $pid) - SQLite backend"
+
+    return 0
+}
+
+# Stop a daemon by PID file
+stop_daemon() {
+    local pid_file="$1"
+    local name="$2"
+
+    if [ -f "$pid_file" ]; then
+        local pid=$(cat "$pid_file")
+        if ps -p "$pid" > /dev/null 2>&1; then
+            log "Stopping $name (PID: $pid)..."
+            kill "$pid" 2>/dev/null
+            sleep 1
+
+            # Force kill if still running
+            if ps -p "$pid" > /dev/null 2>&1; then
+                kill -9 "$pid" 2>/dev/null
+            fi
+
+            success "$name stopped"
+        fi
+        rm -f "$pid_file"
+    else
+        log "$name not running"
+    fi
+}
+
+# Start all daemons
+start_all() {
+    log "Starting all Claude Flow daemons..."
+    start_swarm_monitor "${1:-30}"
+    start_metrics_daemon "${2:-60}"
+
+    # Initial metrics update
+    "$SCRIPT_DIR/swarm-monitor.sh" check > /dev/null 2>&1
+
+    success "All daemons started"
+    show_status
+}
+
+# Stop all daemons
+stop_all() {
+    log "Stopping all Claude Flow daemons..."
+    stop_daemon "$SWARM_MONITOR_PID" "Swarm monitor"
+    stop_daemon "$METRICS_DAEMON_PID" "Metrics daemon"
+    success "All daemons stopped"
+}
+
+# Restart all daemons
+restart_all() {
+    stop_all
+    sleep 1
+    start_all "$@"
+}
+
+# Show daemon status
+show_status() {
+    echo ""
+    echo -e "${CYAN}═══════════════════════════════════════════════════${RESET}"
+    echo -e "${CYAN}       Claude Flow V3 Daemon Status${RESET}"
+    echo -e "${CYAN}═══════════════════════════════════════════════════${RESET}"
+    echo ""
+
+    # Swarm Monitor
+    if is_running "$SWARM_MONITOR_PID"; then
+        echo -e "  ${GREEN}●${RESET} Swarm Monitor    ${GREEN}RUNNING${RESET} (PID: $(cat "$SWARM_MONITOR_PID"))"
+    else
+        echo -e "  ${RED}○${RESET} Swarm Monitor    ${RED}STOPPED${RESET}"
+    fi
+
+    # Metrics Daemon
+    if is_running "$METRICS_DAEMON_PID"; then
+        echo -e "  ${GREEN}●${RESET} Metrics Daemon   ${GREEN}RUNNING${RESET} (PID: $(cat "$METRICS_DAEMON_PID"))"
+    else
+        echo -e "  ${RED}○${RESET} Metrics Daemon   ${RED}STOPPED${RESET}"
+    fi
+
+    # MCP Server
+    local mcp_count=$(ps aux 2>/dev/null | grep -E "mcp.*start" | grep -v grep | wc -l)
+    if [ "$mcp_count" -gt 0 ]; then
+        echo -e "  ${GREEN}●${RESET} MCP Server       ${GREEN}RUNNING${RESET}"
+    else
+        echo -e "  ${YELLOW}○${RESET} MCP Server       ${YELLOW}NOT DETECTED${RESET}"
+    fi
+
+    # Agentic Flow
+    local af_count=$(ps aux 2>/dev/null | grep -E "agentic-flow" | grep -v grep | grep -v "daemon-manager" | wc -l)
+    if [ "$af_count" -gt 0 ]; then
+        echo -e "  ${GREEN}●${RESET} Agentic Flow     ${GREEN}ACTIVE${RESET} ($af_count processes)"
+    else
+        echo -e "  ${YELLOW}○${RESET} Agentic Flow     ${YELLOW}IDLE${RESET}"
+    fi
+
+    echo ""
+    echo -e "${CYAN}───────────────────────────────────────────────────${RESET}"
+
+    # Show latest metrics
+    if [ -f "$METRICS_DIR/swarm-activity.json" ]; then
+        local last_update=$(jq -r '.timestamp // "unknown"' "$METRICS_DIR/swarm-activity.json" 2>/dev/null)
+        local agent_count=$(jq -r '.swarm.agent_count // 0' "$METRICS_DIR/swarm-activity.json" 2>/dev/null)
+        echo -e "  Last Update: ${last_update}"
+        echo -e "  Active Agents: ${agent_count}"
+    fi
+
+    echo -e "${CYAN}═══════════════════════════════════════════════════${RESET}"
+    echo ""
+}
+
+# Main command handling
+case "${1:-status}" in
+    "start")
+        start_all "${2:-30}" "${3:-60}"
+        ;;
+    "stop")
+        stop_all
+        ;;
+    "restart")
+        restart_all "${2:-30}" "${3:-60}"
+        ;;
+    "status")
+        show_status
+        ;;
+    "start-swarm")
+        start_swarm_monitor "${2:-30}"
+        ;;
+    "start-metrics")
+        start_metrics_daemon "${2:-60}"
+        ;;
+    "help"|"-h"|"--help")
+        echo "Claude Flow V3 Daemon Manager"
+        echo ""
+        echo "Usage: $0 [command] [options]"
+        echo ""
+        echo "Commands:"
+        echo "  start [swarm_interval] [metrics_interval]  Start all daemons"
+        echo "  stop                                       Stop all daemons"
+        echo "  restart [swarm_interval] [metrics_interval] Restart all daemons"
+        echo "  status                                     Show daemon status"
+        echo "  start-swarm [interval]                     Start swarm monitor only"
+        echo "  start-metrics [interval]                   Start metrics daemon only"
+        echo "  help                                       Show this help"
+        echo ""
+        echo "Examples:"
+        echo "  $0 start           # Start with defaults (30s swarm, 60s metrics)"
+        echo "  $0 start 10 30     # Start with 10s swarm, 30s metrics intervals"
+        echo "  $0 status          # Show current status"
+        echo "  $0 stop            # Stop all daemons"
+        ;;
+    *)
+        error "Unknown command: $1"
+        echo "Use '$0 help' for usage information"
+        exit 1
+        ;;
+esac

package/.claude/helpers/ddd-tracker.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# Claude Flow V3 - DDD Progress Tracker Worker
+# Tracks Domain-Driven Design implementation progress
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+METRICS_DIR="$PROJECT_ROOT/.claude-flow/metrics"
+DDD_FILE="$METRICS_DIR/ddd-progress.json"
+V3_PROGRESS="$METRICS_DIR/v3-progress.json"
+LAST_RUN_FILE="$METRICS_DIR/.ddd-last-run"
+
+mkdir -p "$METRICS_DIR"
+
+# V3 Target Domains
+DOMAINS=("agent-lifecycle" "task-execution" "memory-management" "coordination" "shared-kernel")
+
+should_run() {
+  if [ ! -f "$LAST_RUN_FILE" ]; then return 0; fi
+  local last_run=$(cat "$LAST_RUN_FILE" 2>/dev/null || echo "0")
+  local now=$(date +%s)
+  [ $((now - last_run)) -ge 600 ]  # 10 minutes
+}
+
+check_domain() {
+  local domain="$1"
+  local domain_path="$PROJECT_ROOT/v3/@claude-flow/$domain"
+  local alt_path="$PROJECT_ROOT/src/domains/$domain"
+
+  local score=0
+  local max_score=100
+
+  # Check if domain directory exists (20 points)
+  if [ -d "$domain_path" ] || [ -d "$alt_path" ]; then
+    score=$((score + 20))
+    local path="${domain_path:-$alt_path}"
+    [ -d "$domain_path" ] && path="$domain_path" || path="$alt_path"
+
+    # Check for domain layer (15 points)
+    [ -d "$path/domain" ] || [ -d "$path/src/domain" ] && score=$((score + 15))
+
+    # Check for application layer (15 points)
+    [ -d "$path/application" ] || [ -d "$path/src/application" ] && score=$((score + 15))
+
+    # Check for infrastructure layer (15 points)
+    [ -d "$path/infrastructure" ] || [ -d "$path/src/infrastructure" ] && score=$((score + 15))
+
+    # Check for API/interface layer (10 points)
+    [ -d "$path/api" ] || [ -d "$path/src/api" ] && score=$((score + 10))
+
+    # Check for tests (15 points)
+    local test_count=$(find "$path" -name "*.test.ts" -o -name "*.spec.ts" 2>/dev/null | wc -l)
+    [ "$test_count" -gt 0 ] && score=$((score + 15))
+
+    # Check for index/exports (10 points)
+    [ -f "$path/index.ts" ] || [ -f "$path/src/index.ts" ] && score=$((score + 10))
+  fi
+
+  echo "$score"
+}
+
+count_entities() {
+  local type="$1"
+  local pattern="$2"
+
+  find "$PROJECT_ROOT/v3" "$PROJECT_ROOT/src" -name "*.ts" 2>/dev/null | \
+    xargs grep -l "$pattern" 2>/dev/null | \
+    grep -v node_modules | grep -v ".test." | wc -l || echo "0"
+}
+
+track_ddd() {
+  echo "[$(date +%H:%M:%S)] Tracking DDD progress..."
+
+  local total_score=0
+  local domain_scores=""
+  local completed_domains=0
+
+  for domain in "${DOMAINS[@]}"; do
+    local score=$(check_domain "$domain")
+    total_score=$((total_score + score))
+    domain_scores="$domain_scores\"$domain\": $score, "
+
+    [ "$score" -ge 50 ] && completed_domains=$((completed_domains + 1))
+  done
+
+  # Calculate overall progress
+  local max_total=$((${#DOMAINS[@]} * 100))
+  local progress=$((total_score * 100 / max_total))
+
+  # Count DDD artifacts
+  local entities=$(count_entities "entities" "class.*Entity\|interface.*Entity")
+  local value_objects=$(count_entities "value-objects" "class.*VO\|ValueObject")
+  local aggregates=$(count_entities "aggregates" "class.*Aggregate\|AggregateRoot")
+  local repositories=$(count_entities "repositories" "interface.*Repository\|Repository")
+  local services=$(count_entities "services" "class.*Service\|Service")
+  local events=$(count_entities "events" "class.*Event\|DomainEvent")
+
+  # Write DDD metrics
+  cat > "$DDD_FILE" << EOF
+{
+  "timestamp": "$(date -Iseconds)",
+  "progress": $progress,
+  "domains": {
+    ${domain_scores%,*}
+  },
+  "completed": $completed_domains,
+  "total": ${#DOMAINS[@]},
+  "artifacts": {
+    "entities": $entities,
+    "valueObjects": $value_objects,
+    "aggregates": $aggregates,
+    "repositories": $repositories,
+    "services": $services,
+    "domainEvents": $events
+  }
+}
+EOF
+
+  # Update v3-progress.json
+  if [ -f "$V3_PROGRESS" ] && command -v jq &>/dev/null; then
+    jq --argjson progress "$progress" --argjson completed "$completed_domains" \
+      '.ddd.progress = $progress | .domains.completed = $completed' \
+      "$V3_PROGRESS" > "$V3_PROGRESS.tmp" && mv "$V3_PROGRESS.tmp" "$V3_PROGRESS"
+  fi
+
+  echo "[$(date +%H:%M:%S)] ✓ DDD: ${progress}% | Domains: $completed_domains/${#DOMAINS[@]} | Entities: $entities | Services: $services"
+
+  date +%s > "$LAST_RUN_FILE"
+}
+
+case "${1:-check}" in
+  "run"|"track") track_ddd ;;
+  "check") should_run && track_ddd || echo "[$(date +%H:%M:%S)] Skipping (throttled)" ;;
+  "force") rm -f "$LAST_RUN_FILE"; track_ddd ;;
+  "status")
+    if [ -f "$DDD_FILE" ]; then
+      jq -r '"Progress: \(.progress)% | Domains: \(.completed)/\(.total) | Entities: \(.artifacts.entities) | Services: \(.artifacts.services)"' "$DDD_FILE"
+    else
+      echo "No DDD data available"
+    fi
+    ;;
+  *) echo "Usage: $0 [run|check|force|status]" ;;
+esac

package/.claude/helpers/github-safe.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Safe GitHub CLI Helper — v1.0.0
+ *
+ * Prevents injection issues when using `gh` commands with untrusted content
+ * (PR bodies, issue bodies, comment bodies) by routing the body through a
+ * temp file and using `--body-file` rather than interpolating into shell args.
+ *
+ * ADR-127 Phase 2 hardening:
+ *   - GITHUB_SAFE_VERSION exported for smoke assertions.
+ *   - Explicit 256KB body cap: rejects oversized bodies before any temp-file
+ *     write, matching the GitHub API `body` field limit.
+ *   - Strict error handling: all execSync calls inside try/catch; cleanup in
+ *     finally; non-zero exit on any error.
+ *   - GITHUB_SAFE_DRY_RUN=1 env-var skips the actual `gh` exec for testing.
+ *
+ * Usage:
+ *   ./github-safe.js issue comment 123 "Message with \`backticks\`"
+ *   ./github-safe.js pr create --title "Title" --body "Complex body"
+ */
+
+import { execSync, execFileSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+
+// Version constant — asserted by smoke-github-safe-injection.mjs.
+export const GITHUB_SAFE_VERSION = '1.0.0';
+
+// Maximum body size allowed (bytes).  The GitHub API enforces 65536 chars for
+// issue/PR bodies; the CLI is more lenient but the 256KB limit is a
+// conservative safety cap that prevents accidental oversized writes.
+const MAX_BODY_BYTES = 256 * 1024;
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.log(`
+Safe GitHub CLI Helper v${GITHUB_SAFE_VERSION}
+
+Usage:
+  ./github-safe.js issue comment <number> <body>
+  ./github-safe.js pr comment <number> <body>
+  ./github-safe.js issue create --title <title> --body <body>
+  ./github-safe.js pr create --title <title> --body <body>
+
+This helper prevents injection issues with special characters:
+- Backticks in code examples
+- Command substitution $(...)
+- Semicolons and other shell metacharacters
+- Oversized bodies (> 256 KB rejected)
+`);
+  process.exit(1);
+}
+
+const [command, subcommand, ...restArgs] = args;
+
+// Handle commands that need body content
+if ((command === 'issue' || command === 'pr') &&
+    (subcommand === 'comment' || subcommand === 'create')) {
+
+  let bodyIndex = -1;
+  let body = '';
+
+  if (subcommand === 'comment' && restArgs.length >= 2) {
+    // Simple format: github-safe.js issue comment 123 "body"
+    body = restArgs[1];
+    bodyIndex = 1;
+  } else {
+    // Flag format: --body "content"
+    bodyIndex = restArgs.indexOf('--body');
+    if (bodyIndex !== -1 && bodyIndex < restArgs.length - 1) {
+      body = restArgs[bodyIndex + 1];
+    }
+  }
+
+  if (body) {
+    // Enforce 256KB cap before any file I/O.
+    const bodyBytes = Buffer.byteLength(body, 'utf8');
+    if (bodyBytes > MAX_BODY_BYTES) {
+      console.error(
+        `[ERROR] Body exceeds maximum allowed size (${bodyBytes} bytes > ${MAX_BODY_BYTES} bytes). ` +
+        'GitHub API body fields are capped at 256KB. Truncate the body before passing it to github-safe.js.'
+      );
+      process.exit(1);
+    }
+
+    // Use temporary file for body content — never interpolate into argv.
+    const tmpFile = join(tmpdir(), `gh-body-${randomBytes(8).toString('hex')}.tmp`);
+
+    try {
+      writeFileSync(tmpFile, body, 'utf8');
+
+      // Build new command with --body-file
+      const newArgs = [...restArgs];
+      if (subcommand === 'comment' && bodyIndex === 1) {
+        // Replace positional body arg with --body-file
+        newArgs[1] = '--body-file';
+        newArgs.push(tmpFile);
+      } else if (bodyIndex !== -1) {
+        // Replace --body flag pair with --body-file
+        newArgs[bodyIndex] = '--body-file';
+        newArgs[bodyIndex + 1] = tmpFile;
+      }
+
+      // Skip actual gh exec in dry-run mode (used by smoke tests).
+      if (process.env.GITHUB_SAFE_DRY_RUN === '1') {
+        const ghArgs = [command, subcommand, ...newArgs];
+        console.log(`[DRY-RUN] gh ${ghArgs.join(' ')}`);
+        process.exit(0);
+      }
+
+      const ghArgv = [command, subcommand, ...newArgs];
+      console.log(`Executing: gh ${ghArgv.join(' ')}`);
+
+      // Use execFileSync to avoid shell interpolation — args are passed as an
+      // array so shell metacharacters in tmpFile path cannot be exploited.
+      execFileSync('gh', ghArgv, {
+        stdio: 'inherit',
+        timeout: 30000,
+      });
+
+    } catch (error) {
+      console.error('[ERROR]', error.message);
+      process.exit(1);
+    } finally {
+      // Always clean up the temp file.
+      try { unlinkSync(tmpFile); } catch (_) { /* ignore cleanup errors */ }
+    }
+  } else {
+    // No body content — execute normally (no injection risk for args).
+    if (process.env.GITHUB_SAFE_DRY_RUN === '1') {
+      console.log(`[DRY-RUN] gh ${args.join(' ')}`);
+      process.exit(0);
+    }
+    try {
+      execFileSync('gh', args, { stdio: 'inherit' });
+    } catch (error) {
+      console.error('[ERROR]', error.message);
+      process.exit(1);
+    }
+  }
+} else {
+  // Non-body commands — execute normally.
+  if (process.env.GITHUB_SAFE_DRY_RUN === '1') {
+    console.log(`[DRY-RUN] gh ${args.join(' ')}`);
+    process.exit(0);
+  }
+  try {
+    execFileSync('gh', args, { stdio: 'inherit' });
+  } catch (error) {
+    console.error('[ERROR]', error.message);
+    process.exit(1);
+  }
+}

package/.claude/helpers/github-setup.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Security rationale: set -euo pipefail ensures that:
+#   -e  — exit immediately if any command fails (no silent failures)
+#   -u  — treat unset variables as errors (prevents empty-string expansion bugs)
+#   -o pipefail — pipeline fails if any command in it fails (not just last)
+# This matches the ADR-127 Phase 2 requirement for github-setup.sh hardening.
+set -euo pipefail
+
+# Setup GitHub integration for Claude Flow
+
+echo "Setting up GitHub integration..."
+
+# Check for gh CLI
+if ! command -v gh &> /dev/null; then
+    echo "WARNING: GitHub CLI (gh) not found"
+    echo "Install from: https://cli.github.com/"
+    echo "Continuing without GitHub features..."
+else
+    echo "OK: GitHub CLI found"
+
+    # Check auth status and scope sufficiency.
+    # `gh auth status` exits non-zero when not authenticated.
+    # We additionally parse for "Token scopes" to verify we have at least
+    # 'repo' scope, which is required for PR/issue operations.
+    if gh auth status 2>&1 | grep -q "Logged in"; then
+        echo "OK: GitHub authentication active"
+        # Verify repo scope is present for PR/issue operations.
+        if gh auth status 2>&1 | grep -q "repo"; then
+            echo "OK: 'repo' scope available"
+        else
+            echo "WARNING: 'repo' scope not confirmed — PR/issue operations may fail"
+            echo "Run: gh auth login --scopes repo,read:org"
+        fi
+    else
+        echo "WARNING: Not authenticated with GitHub"
+        echo "Run: gh auth login"
+    fi
+fi
+
+echo ""
+echo "GitHub swarm commands available:"
+echo "  - npx claude-flow github swarm"
+echo "  - npx claude-flow repo analyze"
+echo "  - npx claude-flow pr enhance"
+echo "  - npx claude-flow issue triage"

package/.claude/helpers/guidance-hook.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Capture hook guidance for Claude visibility
+GUIDANCE_FILE=".claude-flow/last-guidance.txt"
+mkdir -p .claude-flow
+
+case "$1" in
+  "route")
+    npx agentic-flow@alpha hooks route "$2" 2>&1 | tee "$GUIDANCE_FILE"
+    ;;
+  "pre-edit")
+    npx agentic-flow@alpha hooks pre-edit "$2" 2>&1 | tee "$GUIDANCE_FILE"
+    ;;
+esac