claude-flow-novice 2.15.3 → 2.15.4

package/claude-assets/skills/cfn-file-operations/SKILL.md

@@ -0,0 +1,290 @@
+# File Operations Skill
+
+Centralized file locking and atomic write operations for bash scripts.
+
+**Part of Task 4.2: Centralized File Locking & Atomic Operations**
+
+## Overview
+
+This skill provides:
+- **File Locking**: Acquire, release, and renew locks with queuing
+- **Atomic Writes**: Write-then-move pattern with SHA256 verification
+- **Safety**: Backup creation, rollback, permission preservation
+- **Performance**: <100ms lock acquisition target, efficient retry logic
+
+## Features
+
+### File Locking
+- Lock acquisition with configurable timeout (default: 300s)
+- Waiting queue for blocked processes
+- Lock renewal for long-running operations
+- Force release for stuck locks
+- Owner tracking (process ID, agent ID, hostname)
+- Stale lock detection and automatic cleanup
+
+### Atomic Writes
+- Write-then-move pattern (atomic operation)
+- SHA256 checksum verification
+- Automatic backup creation
+- Rollback on failure
+- Permission and ownership preservation
+- Integration with file locking
+
+## Usage
+
+### Acquire Lock
+
+```bash
+# Basic usage
+./.claude/skills/cfn-file-operations/execute.sh acquire-lock /path/to/file.txt
+
+# With agent ID tracking
+./.claude/skills/cfn-file-operations/execute.sh acquire-lock /path/to/file.txt --agent-id agent-001
+
+# With custom timeout (30 seconds)
+./.claude/skills/cfn-file-operations/execute.sh acquire-lock /path/to/file.txt --timeout 30000
+
+# Output: LOCK_ID:LOCK_PATH (e.g., "lock-1234567890-999:/tmp/cfn-locks/abc123.lock")
+```
+
+### Release Lock
+
+```bash
+# Release lock using lock info from acquire
+LOCK_INFO=$(./execute.sh acquire-lock /path/to/file.txt)
+# ... perform operations ...
+./execute.sh release-lock "$LOCK_INFO"
+```
+
+### Renew Lock
+
+```bash
+# Renew lock with 5-minute extension (default)
+./execute.sh renew-lock "$LOCK_INFO"
+
+# Custom extension (10 minutes)
+./execute.sh renew-lock "$LOCK_INFO" --extension 600000
+```
+
+### Force Release
+
+```bash
+# Force release a stuck lock
+./execute.sh force-release /tmp/cfn-locks/abc123.lock
+```
+
+### Atomic Write
+
+```bash
+# Basic write
+./execute.sh atomic-write /path/to/file.txt "Content here"
+
+# With checksum verification
+./execute.sh atomic-write /path/to/file.txt "Content" --checksum
+
+# With backup creation
+./execute.sh atomic-write /path/to/file.txt "Content" --backup
+
+# With lock (auto-acquire and release)
+./execute.sh atomic-write /path/to/file.txt "Content" --lock
+
+# All features combined
+./execute.sh atomic-write /path/to/file.txt "Content" --checksum --backup --lock
+```
+
+### Atomic Read
+
+```bash
+# Read with checksum
+./execute.sh atomic-read /path/to/file.txt
+
+# Verify expected checksum
+./execute.sh atomic-read /path/to/file.txt --expected-checksum abc123...
+```
+
+### Verify Checksum
+
+```bash
+./execute.sh verify-checksum /path/to/file.txt expected_sha256_hash
+```
+
+### Get Metrics
+
+```bash
+./execute.sh get-metrics
+
+# Output (JSON):
+# {
+#   "activeLocks": 3,
+#   "staleLocks": 0,
+#   "lockDirectory": "/tmp/cfn-locks"
+# }
+```
+
+## Complete Workflow Example
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+SKILL_PATH="./.claude/skills/cfn-file-operations/execute.sh"
+FILE_PATH="/path/to/important-file.txt"
+AGENT_ID="backend-dev-001"
+
+# Acquire lock
+echo "Acquiring lock..."
+LOCK_INFO=$($SKILL_PATH acquire-lock "$FILE_PATH" --agent-id "$AGENT_ID" --timeout 60000)
+
+if [ $? -ne 0 ]; then
+  echo "Failed to acquire lock"
+  exit 1
+fi
+
+echo "Lock acquired: $LOCK_INFO"
+
+# Perform operations with atomic write
+echo "Writing file..."
+RESULT=$($SKILL_PATH atomic-write "$FILE_PATH" "New content here" --checksum --backup)
+
+if [ $? -ne 0 ]; then
+  echo "Write failed, releasing lock"
+  $SKILL_PATH release-lock "$LOCK_INFO"
+  exit 1
+fi
+
+echo "Write successful: $RESULT"
+
+# Renew lock for extended operation
+echo "Renewing lock for extended operation..."
+$SKILL_PATH renew-lock "$LOCK_INFO" --extension 300000
+
+# Release lock
+echo "Releasing lock..."
+$SKILL_PATH release-lock "$LOCK_INFO"
+
+echo "Complete!"
+```
+
+## Lock File Format
+
+Locks are stored in `/tmp/cfn-locks/` (configurable via `CFN_LOCK_DIR`).
+
+Lock file naming: `${SHA256_HASH_OF_TARGET_PATH}.lock`
+
+Lock metadata (JSON):
+```json
+{
+  "lockId": "lock-1234567890-999",
+  "filePath": "/absolute/path/to/file.txt",
+  "owner": {
+    "pid": 12345,
+    "agentId": "backend-dev-001",
+    "hostname": "server01"
+  },
+  "acquiredAt": "2025-11-16T04:00:00.123Z",
+  "expiresAt": "2025-11-16T04:05:00.123Z",
+  "timeoutMs": 300000,
+  "renewalCount": 0,
+  "lastRenewedAt": null
+}
+```
+
+## Write Result Format
+
+Atomic write operations return JSON:
+```json
+{
+  "success": true,
+  "filePath": "/absolute/path/to/file.txt",
+  "checksum": "abc123def456...",
+  "bytesWritten": 1024,
+  "durationMs": 45,
+  "backupPath": "/absolute/path/to/file.txt.2025-11-16T04-00-00.backup"
+}
+```
+
+## Integration with TypeScript
+
+This skill integrates with the TypeScript file operations:
+
+```typescript
+import { FileLockManager } from './lib/file-lock-manager';
+import { AtomicFileWriter } from './lib/atomic-file-writer';
+
+// Use TypeScript API
+const manager = new FileLockManager();
+const lock = await manager.acquireLock('/path/to/file.txt', {
+  agentId: 'agent-001',
+  timeout: 30000
+});
+
+try {
+  const writer = new AtomicFileWriter();
+  await writer.writeFile('/path/to/file.txt', content, {
+    verifyChecksum: true,
+    createBackup: true
+  });
+} finally {
+  await manager.releaseLock(lock.id);
+}
+```
+
+## Configuration
+
+Environment variables:
+- `CFN_LOCK_DIR`: Lock directory (default: `/tmp/cfn-locks`)
+
+Default timeouts:
+- Lock acquisition: 300000ms (5 minutes)
+- Retry interval: 100ms
+- Stale lock detection: 300000ms (5 minutes)
+
+## Error Handling
+
+The skill uses exit codes for error signaling:
+- `0`: Success
+- `1`: General error (invalid arguments, operation failed)
+
+Error messages are written to stderr.
+
+## Performance
+
+Target metrics:
+- Lock acquisition: <100ms (when lock available)
+- Atomic write: <50ms (small files)
+- Checksum calculation: O(file size)
+
+## Stale Lock Cleanup
+
+Stale locks are automatically cleaned up:
+- Locks past expiration time are considered stale
+- Cleanup occurs during lock acquisition attempts
+- Manual cleanup via `force-release` command
+
+## Security Considerations
+
+- Locks are process-scoped (not system-wide semaphores)
+- Lock files are world-readable by default (chmod 644)
+- Force release should be used with caution
+- Ownership verification prevents unauthorized release
+
+## Testing
+
+See `test.sh` for comprehensive test suite covering:
+- Lock acquisition and release
+- Timeout scenarios
+- Concurrent access
+- Atomic writes with verification
+- Stale lock detection
+- Error handling
+
+## See Also
+
+- TypeScript API: `src/lib/file-lock-manager.ts`
+- Atomic Writer: `src/lib/atomic-file-writer.ts`
+- Usage Guide: `docs/FILE_OPERATIONS_GUIDE.md`
+- Tests: `.claude/skills/cfn-file-operations/test.sh`
+
+## Version
+
+1.0.0 (Task 4.2 - November 2025)

package/claude-assets/skills/cfn-file-operations/execute.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+#
+# File Operations Skill - Main Entry Point
+#
+# Provides file locking and atomic write operations for bash scripts.
+# Part of Task 4.2: Centralized File Locking & Atomic Operations
+#
+# Usage:
+#   # Acquire lock
+#   ./.claude/skills/cfn-file-operations/execute.sh acquire-lock /path/to/file.txt --agent-id agent-001
+#
+#   # Write atomically
+#   ./.claude/skills/cfn-file-operations/execute.sh atomic-write /path/to/file.txt "content" --checksum
+#
+#   # Release lock
+#   ./.claude/skills/cfn-file-operations/execute.sh release-lock LOCK_ID
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/lock.sh"
+source "${SCRIPT_DIR}/lib/atomic-write.sh"
+
+# Command dispatcher
+COMMAND="${1:-help}"
+shift || true
+
+case "$COMMAND" in
+  acquire-lock)
+    file_path="${1:-}"
+    shift || true
+    acquire_file_lock "$file_path" "$@"
+    ;;
+
+  release-lock)
+    lock_id="${1:-}"
+    shift || true
+    release_file_lock "$lock_id" "$@"
+    ;;
+
+  renew-lock)
+    lock_id="${1:-}"
+    shift || true
+    renew_file_lock "$lock_id" "$@"
+    ;;
+
+  force-release)
+    lock_path="${1:-}"
+    shift || true
+    force_release_lock "$lock_path" "$@"
+    ;;
+
+  atomic-write)
+    file_path="${1:-}"
+    content="${2:-}"
+    shift 2 || true
+    atomic_write_file "$file_path" "$content" "$@"
+    ;;
+
+  atomic-read)
+    file_path="${1:-}"
+    shift || true
+    atomic_read_file "$file_path" "$@"
+    ;;
+
+  verify-checksum)
+    file_path="${1:-}"
+    expected_checksum="${2:-}"
+    shift 2 || true
+    verify_file_checksum "$file_path" "$expected_checksum" "$@"
+    ;;
+
+  get-metrics)
+    get_lock_metrics
+    ;;
+
+  help|--help|-h)
+    cat <<EOF
+File Operations Skill - Usage
+
+Commands:
+  acquire-lock <file-path> [--agent-id ID] [--timeout MS]
+    Acquire a file lock
+
+  release-lock <lock-id>
+    Release a file lock
+
+  renew-lock <lock-id> [--extension MS]
+    Renew a file lock (extend expiration)
+
+  force-release <lock-path>
+    Force release a stuck lock
+
+  atomic-write <file-path> <content> [--checksum] [--backup]
+    Write file atomically with optional checksum verification
+
+  atomic-read <file-path> [--expected-checksum HASH]
+    Read file with optional checksum verification
+
+  verify-checksum <file-path> <expected-checksum>
+    Verify file SHA256 checksum
+
+  get-metrics
+    Get lock manager metrics
+
+  help
+    Show this help message
+
+Examples:
+  # Acquire lock
+  ./execute.sh acquire-lock /tmp/test.txt --agent-id agent-001
+
+  # Write atomically
+  ./execute.sh atomic-write /tmp/test.txt "Hello World" --checksum --backup
+
+  # Release lock
+  ./execute.sh release-lock abc123-lock-id
+
+For more information, see SKILL.md
+EOF
+    ;;
+
+  *)
+    echo "Error: Unknown command: $COMMAND" >&2
+    echo "Run '$0 help' for usage information" >&2
+    exit 1
+    ;;
+esac

package/claude-assets/skills/cfn-file-operations/lib/atomic-write.sh

@@ -0,0 +1,294 @@
+#!/bin/bash
+#
+# Atomic Write Operations Library
+#
+# Provides atomic file write functions with SHA256 verification.
+# Part of Task 4.2: Centralized File Locking & Atomic Operations
+#
+
+#
+# Calculate SHA256 checksum of content
+#
+# Usage: calculate_checksum <content>
+#
+calculate_checksum() {
+  local content="$1"
+  echo -n "$content" | sha256sum | awk '{print $1}'
+}
+
+#
+# Calculate SHA256 checksum of file
+#
+# Usage: calculate_file_checksum <file-path>
+#
+calculate_file_checksum() {
+  local file_path="$1"
+
+  if [ ! -f "$file_path" ]; then
+    echo "Error: File not found: $file_path" >&2
+    return 1
+  fi
+
+  sha256sum "$file_path" | awk '{print $1}'
+}
+
+#
+# Write file atomically
+#
+# Usage: atomic_write_file <file-path> <content> [--checksum] [--backup] [--lock]
+#
+atomic_write_file() {
+  local file_path="$1"
+  local content="$2"
+  shift 2
+
+  if [ -z "$file_path" ]; then
+    echo "Error: file-path required" >&2
+    return 1
+  fi
+
+  local verify_checksum=0
+  local create_backup=0
+  local use_lock=0
+  local lock_info=""
+
+  # Parse options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --checksum)
+        verify_checksum=1
+        shift
+        ;;
+      --backup)
+        create_backup=1
+        shift
+        ;;
+      --lock)
+        use_lock=1
+        shift
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  local start_time
+  start_time=$(date +%s%3N)
+
+  # Acquire lock if requested
+  if [ "$use_lock" -eq 1 ]; then
+    lock_info=$(acquire_file_lock "$file_path" --timeout 30000)
+    if [ $? -ne 0 ]; then
+      echo "Error: Failed to acquire lock for $file_path" >&2
+      return 1
+    fi
+  fi
+
+  local dir
+  dir=$(dirname "$file_path")
+
+  local temp_path
+  temp_path="${dir}/.$(basename "$file_path").$(date +%s%N).tmp"
+
+  local backup_path=""
+  local success=0
+
+  # Calculate expected checksum
+  local expected_checksum
+  expected_checksum=$(calculate_checksum "$content")
+
+  # Create backup if requested and file exists
+  if [ "$create_backup" -eq 1 ] && [ -f "$file_path" ]; then
+    local timestamp
+    timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S")
+    backup_path="${file_path}.${timestamp}.backup"
+
+    cp "$file_path" "$backup_path" 2>/dev/null || {
+      echo "Error: Failed to create backup" >&2
+      [ -n "$lock_info" ] && release_file_lock "$lock_info"
+      return 1
+    }
+
+    echo "Backup created: $backup_path" >&2
+  fi
+
+  # Write to temporary file
+  echo -n "$content" > "$temp_path" || {
+    echo "Error: Failed to write temporary file" >&2
+    [ -n "$lock_info" ] && release_file_lock "$lock_info"
+    return 1
+  }
+
+  # Verify checksum if requested
+  if [ "$verify_checksum" -eq 1 ]; then
+    local actual_checksum
+    actual_checksum=$(calculate_file_checksum "$temp_path")
+
+    if [ "$actual_checksum" != "$expected_checksum" ]; then
+      echo "Error: Checksum verification failed" >&2
+      echo "  Expected: $expected_checksum" >&2
+      echo "  Actual:   $actual_checksum" >&2
+      rm -f "$temp_path"
+      [ -n "$lock_info" ] && release_file_lock "$lock_info"
+      return 1
+    fi
+
+    echo "Checksum verified: $actual_checksum" >&2
+  fi
+
+  # Preserve permissions if file exists
+  if [ -f "$file_path" ]; then
+    chmod --reference="$file_path" "$temp_path" 2>/dev/null || true
+  fi
+
+  # Atomic move
+  if mv "$temp_path" "$file_path" 2>/dev/null; then
+    success=1
+  else
+    echo "Error: Failed to move temporary file to target" >&2
+
+    # Rollback from backup if available
+    if [ -n "$backup_path" ] && [ -f "$backup_path" ]; then
+      cp "$backup_path" "$file_path" 2>/dev/null && {
+        echo "Restored from backup after failed write" >&2
+      }
+    fi
+
+    rm -f "$temp_path"
+    [ -n "$lock_info" ] && release_file_lock "$lock_info"
+    return 1
+  fi
+
+  # Get file size
+  local bytes_written
+  bytes_written=$(stat -f%z "$file_path" 2>/dev/null || stat -c%s "$file_path" 2>/dev/null || echo "0")
+
+  local end_time
+  end_time=$(date +%s%3N)
+  local duration=$((end_time - start_time))
+
+  # Release lock if acquired
+  if [ -n "$lock_info" ]; then
+    release_file_lock "$lock_info"
+  fi
+
+  # Output result as JSON
+  jq -n \
+    --argjson success "$success" \
+    --arg filePath "$file_path" \
+    --arg checksum "$expected_checksum" \
+    --argjson bytesWritten "$bytes_written" \
+    --argjson durationMs "$duration" \
+    --arg backupPath "$backup_path" \
+    '{
+      success: $success,
+      filePath: $filePath,
+      checksum: $checksum,
+      bytesWritten: $bytesWritten,
+      durationMs: $durationMs,
+      backupPath: $backupPath
+    }'
+}
+
+#
+# Read file atomically
+#
+# Usage: atomic_read_file <file-path> [--expected-checksum HASH]
+#
+atomic_read_file() {
+  local file_path="$1"
+  shift
+
+  if [ -z "$file_path" ]; then
+    echo "Error: file-path required" >&2
+    return 1
+  fi
+
+  if [ ! -f "$file_path" ]; then
+    echo "Error: File not found: $file_path" >&2
+    return 1
+  fi
+
+  local expected_checksum=""
+
+  # Parse options
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --expected-checksum)
+        expected_checksum="$2"
+        shift 2
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  # Read content
+  local content
+  content=$(cat "$file_path")
+
+  # Calculate checksum
+  local actual_checksum
+  actual_checksum=$(calculate_checksum "$content")
+
+  # Verify if expected checksum provided
+  if [ -n "$expected_checksum" ]; then
+    if [ "$actual_checksum" != "$expected_checksum" ]; then
+      echo "Error: Checksum verification failed" >&2
+      echo "  Expected: $expected_checksum" >&2
+      echo "  Actual:   $actual_checksum" >&2
+      return 1
+    fi
+  fi
+
+  # Output result as JSON
+  jq -n \
+    --arg content "$content" \
+    --arg checksum "$actual_checksum" \
+    '{
+      content: $content,
+      checksum: $checksum
+    }'
+}
+
+#
+# Verify file checksum
+#
+# Usage: verify_file_checksum <file-path> <expected-checksum>
+#
+verify_file_checksum() {
+  local file_path="$1"
+  local expected_checksum="$2"
+
+  if [ -z "$file_path" ] || [ -z "$expected_checksum" ]; then
+    echo "Error: file-path and expected-checksum required" >&2
+    return 1
+  fi
+
+  if [ ! -f "$file_path" ]; then
+    echo "Error: File not found: $file_path" >&2
+    return 1
+  fi
+
+  local actual_checksum
+  actual_checksum=$(calculate_file_checksum "$file_path")
+
+  local matches=0
+  if [ "$actual_checksum" = "$expected_checksum" ]; then
+    matches=1
+  fi
+
+  jq -n \
+    --arg filePath "$file_path" \
+    --arg expected "$expected_checksum" \
+    --arg actual "$actual_checksum" \
+    --argjson matches "$matches" \
+    '{
+      filePath: $filePath,
+      expectedChecksum: $expected,
+      actualChecksum: $actual,
+      matches: $matches
+    }'
+}