spec-and-loop 1.0.6 → 1.0.8

package/QUICKSTART.md

@@ -213,12 +213,49 @@ openspec new another-feature
 | **Auto-Resume** | Interrupted? Run again—picks up where left off |
 | **Context Injection** | Inject custom instructions during execution |
 
+## Testing
+
+Spec-and-loop includes a comprehensive test suite to ensure reliability and cross-platform compatibility.
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests only
+npm run test:integration
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run shellcheck linting
+npm run lint
+```
+
+### Test Requirements
+
+To run tests, you'll need:
+- **Node.js** (>= 24.0.0)
+- **Bats** (Bash testing framework): `apt install bats-core` or `brew install bats-core`
+- **Shellcheck** (Bash linting): `apt install shellcheck` or `brew install shellcheck`
+
+### CI/CD
+
+Tests run automatically on every push and pull request via GitHub Actions on both Linux and macOS.
+
+**For more details, see [TESTING.md](./TESTING.md)**
+
 ## Next Steps
 
 1. **Read the full README.md** for detailed documentation
 2. **Try a real feature** in your project
 3. **Explore the .ralph/** directory to see internal state
 4. **Check out .hidden/** directory for advanced guides
+5. **Review TESTING.md** for testing guidelines
 
 ## Resources
 

package/README.md

@@ -2,6 +2,10 @@
 
 OpenSpec + Ralph Loop integration for iterative development with opencode.
 
+![CI Status](https://img.shields.io/github/actions/workflow/status/ncheaz/spec-and-loop/test.yml)
+![Coverage](https://img.shields.io/badge/coverage-0%25-red)
+[![npm version](https://badge.fury.io/js/spec-and-loop.svg)](https://badge.fury.io/js/spec-and-loop)
+
 **[🚀 Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
 
 ## Why This Exists
@@ -56,6 +60,114 @@ For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
 <!-- Duplicate Quick Start removed; see QUICKSTART.md for full instructions -->
 
+## Testing
+
+Spec-and-loop includes a comprehensive test suite to ensure reliability and cross-platform compatibility.
+
+**[📋 Testing Guide](./TESTING.md)** - Detailed instructions for running tests
+
+### Quick Test Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests only
+npm run test:integration
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run shellcheck linting
+npm run lint
+```
+
+### CI/CD Status
+
+- **Linux**: Tests run on Ubuntu (latest)
+- **macOS**: Tests run on macOS (latest)
+- **Node.js**: Tested on Node.js 24
+
+All tests are run automatically via GitHub Actions on every push and pull request.
+
+### CI/CD Workflow
+
+The CI/CD pipeline is defined in `.github/workflows/test.yml` and performs the following steps:
+
+1. **Checkout Code**: Pulls the latest code from the repository
+2. **Setup Node.js**: Installs Node.js version 24 with npm caching
+3. **Install System Dependencies**:
+   - Linux: `apt-get install bats-core jq shellcheck`
+   - macOS: `brew install bats-core jq shellcheck`
+4. **Install npm Dependencies**: Runs `npm ci` to install dependencies
+5. **Install Global CLIs**: Installs openspec, ralph, and opencode globally
+6. **Run Shellcheck Linting**: Checks bash scripts for errors and best practices
+7. **Run Unit Tests**: Executes bash and JavaScript unit tests
+8. **Run Integration Tests**: Validates full workflow end-to-end
+9. **Upload Artifacts**: Uploads test logs and coverage reports
+
+### Triggering CI/CD
+
+The workflow runs automatically on:
+- Push to `main` or `develop` branches
+- Pull requests to `main` or `develop` branches
+- Manual trigger via GitHub Actions UI
+
+To manually trigger:
+1. Go to Actions tab in GitHub
+2. Select "Test Suite" workflow
+3. Click "Run workflow"
+4. Select branch and test suite (all/unit/integration)
+
+### Troubleshooting CI/CD
+
+**Tests Failing on One Platform**
+
+If tests pass on Linux but fail on macOS (or vice versa):
+- Check for platform-specific command differences (GNU vs BSD tools)
+- Review platform-specific tests in `test-symlink-linux.bats`, `test-symlink-macos.bats`, etc.
+- Verify stat, md5sum/md5, and other commands use correct flags
+
+**Coverage Below Threshold**
+
+If coverage drops below 80%:
+- Review coverage reports uploaded as artifacts
+- Identify which functions lost coverage
+- Add tests to cover the missing code paths
+
+**Linting Failures**
+
+If shellcheck finds issues:
+- Review the warnings in the CI logs
+- Fix the issues locally: `npm run lint`
+- Commit the fixes
+
+**Timeout Issues**
+
+If tests timeout:
+- Integration tests may take longer than expected
+- Check for infinite loops or hanging processes
+- Review test fixture setup/teardown
+
+**Artifact Access**
+
+Download test logs and coverage reports:
+1. Go to the failed workflow run
+2. Scroll to "Artifacts" section
+3. Download relevant artifacts (test logs, coverage reports)
+4. Analyze locally to identify issues
+
+### Test Coverage
+
+Critical functions have >80% test coverage. View detailed coverage reports:
+```bash
+npm run test:coverage
+open coverage/index.html
+```
+
 ## Prerequisites
 
 Before using spec-and-loop, ensure you have:

package/package.json

@@ -1,17 +1,51 @@
 {
   "name": "spec-and-loop",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {
     "ralph-run": "bin/ralph-run"
   },
   "scripts": {
-    "postinstall": "node scripts/setup.js"
+    "postinstall": "node scripts/setup.js",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "bats tests/unit/bash/*.bats && npm run test:js",
+    "test:js": "jest tests/unit/javascript",
+    "test:integration": "bats tests/integration/*.bats",
+    "test:watch": "npm run test:js -- --watch",
+    "test:coverage": "npm run test:unit -- --coverage",
+    "lint": "shellcheck scripts/*.sh"
   },
   "dependencies": {
-    "@fission-ai/openspec": "latest",
-    "@th0rgal/ralph-wiggum": "latest"
+    "@fission-ai/openspec": "1.2.0",
+    "@th0rgal/ralph-wiggum": "1.2.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "bats": "^1.13.0",
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "collectCoverage": true,
+    "coverageDirectory": "coverage",
+    "coverageReporters": [
+      "text",
+      "lcov",
+      "html",
+      "json"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    },
+    "testMatch": [
+      "**/tests/unit/javascript/**/*.test.js"
+    ]
   },
   "keywords": [
     "openspec",

package/scripts/ralph-monitor.sh

@@ -2,20 +2,88 @@
 
 set -e
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Detect OS for cross-platform compatibility
+detect_os() {
+    case "$(uname -s)" in
+        Linux*)     OS="Linux";;
+        Darwin*)    OS="macOS";;
+        *)          OS="Unknown";;
+    esac
+}
+
+detect_os
+
+# Cross-platform file modification time
+get_file_mtime() {
+    local file="$1"
+    if [[ "$OS" == "macOS" ]]; then
+        stat -f %m "$file" 2>/dev/null || echo 0
+    else
+        stat -c %Y "$file" 2>/dev/null || echo 0
+    fi
+}
+
+# Cross-platform file modification time display
+get_file_mtime_display() {
+    local file="$1"
+    if [[ "$OS" == "macOS" ]]; then
+        stat -f "%Sm" -t "%Y-%m-%d %H:%M:%S" "$file" 2>/dev/null || echo "Unknown"
+    else
+        stat -c "%y" "$file" 2>/dev/null | cut -d'.' -f1 || echo "Unknown"
+    fi
+}
+
+resolve_project_root() {
+    local git_root=""
+    git_root=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+
+    if [[ -n "$git_root" ]]; then
+        printf "%s" "$git_root"
+    else
+        pwd
+    fi
+}
+
+auto_detect_change() {
+    local project_root="$1"
+    local changes_dir="$project_root/openspec/changes"
+
+    if [[ ! -d "$changes_dir" ]]; then
+        echo ""
+        return 1
+    fi
+
+    local latest_change=""
+    local latest_time=0
+
+    for change_dir in "$changes_dir"/*; do
+        if [[ -d "$change_dir" && -f "$change_dir/tasks.md" ]]; then
+            local mod_time
+            mod_time=$(get_file_mtime "$change_dir/tasks.md")
+
+            if [[ "$mod_time" -gt "$latest_time" ]]; then
+                latest_time="$mod_time"
+                latest_change=$(basename "$change_dir")
+            fi
+        fi
+    done
+
+    printf "%s" "$latest_change"
+}
+
+PROJECT_ROOT="$(resolve_project_root)"
 CHANGE_NAME="${1:-auto-detect}"
 
 if [[ "$CHANGE_NAME" == "auto-detect" ]]; then
-    # Auto-detect most recent change
-    CHANGE_NAME=$(ls -t openspec/changes/ 2>/dev/null | head -1)
+    CHANGE_NAME=$(auto_detect_change "$PROJECT_ROOT")
     if [[ -z "$CHANGE_NAME" ]]; then
-        echo "No changes found in openspec/changes/"
+        echo "No changes found in $PROJECT_ROOT/openspec/changes/"
         exit 1
     fi
 fi
 
-TASKS_FILE="$SCRIPT_DIR/../openspec/changes/$CHANGE_NAME/tasks.md"
-RALPH_STATE="$SCRIPT_DIR/../.ralph/ralph-loop.state.json"
+TASKS_FILE="$PROJECT_ROOT/openspec/changes/$CHANGE_NAME/tasks.md"
+RALPH_STATE="$PROJECT_ROOT/.ralph/ralph-loop.state.json"
 
 if [[ ! -f "$TASKS_FILE" ]]; then
     echo "Tasks file not found: $TASKS_FILE"
@@ -85,7 +153,7 @@ while true; do
     echo ""
     
     # File status
-    echo " Last Updated: $(stat -c "%y" "$TASKS_FILE" 2>/dev/null | cut -d'.' -f1)"
+    echo " Last Updated: $(get_file_mtime_display "$TASKS_FILE")"
     echo ""
     
     echo "======================================================================="

package/scripts/ralph-run.sh

@@ -9,6 +9,116 @@ if [[ -d "$HOME/.bun/bin" ]]; then
     export PATH="$HOME/.bun/bin:$PATH"
 fi
 
+# Detect OS for cross-platform compatibility
+detect_os() {
+    case "$(uname -s)" in
+        Linux*)     OS="Linux";;
+        Darwin*)    OS="macOS";;
+        *)          OS="Unknown";;
+    esac
+}
+
+detect_os
+
+# Cross-platform file modification time
+get_file_mtime() {
+    local file="$1"
+    if [[ "$OS" == "macOS" ]]; then
+        stat -f %m "$file" 2>/dev/null || echo 0
+    else
+        stat -c %Y "$file" 2>/dev/null || echo 0
+    fi
+}
+
+# Cross-platform MD5 hash
+get_file_md5() {
+    local file="$1"
+    if command -v md5sum >/dev/null 2>&1; then
+        md5sum "$file" | cut -d' ' -f1
+    elif command -v md5 >/dev/null 2>&1; then
+        md5 -q "$file"
+    else
+        echo "0"
+    fi
+}
+
+# Cross-platform realpath with fallback
+get_realpath() {
+    local path="$1"
+    if command -v realpath >/dev/null 2>&1; then
+        realpath "$path" 2>/dev/null || echo ""
+    elif readlink -f / >/dev/null 2>&1; then
+        readlink -f "$path" 2>/dev/null || echo ""
+    else
+        # Fallback for systems without realpath
+        local dir
+        dir=$(cd "$(dirname "$path")" 2>/dev/null && pwd -P || echo "")
+        if [[ -n "$dir" ]]; then
+            echo "$dir/$(basename "$path")"
+        else
+            echo ""
+        fi
+    fi
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOCAL_NODE_BIN="$SCRIPT_DIR/../node_modules/.bin"
+BUNDLED_RALPH_JS="$SCRIPT_DIR/../node_modules/@th0rgal/ralph-wiggum/bin/ralph.js"
+RALPH_CMD=()
+
+if [[ -d "$LOCAL_NODE_BIN" ]]; then
+    case ":$PATH:" in
+        *":$LOCAL_NODE_BIN:"*) ;;
+        *) export PATH="$LOCAL_NODE_BIN:$PATH" ;;
+    esac
+fi
+
+get_temp_root() {
+    local temp_root="${TMPDIR:-/tmp}"
+    temp_root="${temp_root%/}"
+
+    if [[ -z "$temp_root" ]]; then
+        temp_root="/tmp"
+    fi
+
+    printf "%s" "$temp_root"
+}
+
+make_temp_dir() {
+    local prefix="${1:-ralph-run}"
+    local temp_root
+    temp_root=$(get_temp_root)
+
+    local temp_dir=""
+    temp_dir=$(mktemp -d "${temp_root}/${prefix}-XXXXXX" 2>/dev/null) || \
+        temp_dir=$(mktemp -d -t "$prefix" 2>/dev/null) || \
+        temp_dir=""
+
+    if [[ -n "$temp_dir" ]]; then
+        printf "%s" "$temp_dir"
+        return 0
+    fi
+
+    local fallback_dir="${temp_root}/${prefix}-$(date +"%Y%m%d_%H%M%S")-$$"
+    mkdir -p "$fallback_dir"
+    printf "%s" "$fallback_dir"
+}
+
+resolve_ralph_command() {
+    if command -v ralph >/dev/null 2>&1; then
+        RALPH_CMD=("ralph")
+        return 0
+    fi
+
+    if [[ -f "$BUNDLED_RALPH_JS" ]] && command -v node >/dev/null 2>&1; then
+        RALPH_CMD=("node" "$BUNDLED_RALPH_JS")
+        return 0
+    fi
+
+    RALPH_CMD=()
+    return 1
+}
+
 CHANGE_NAME=""
 MAX_ITERATIONS=""
 ERROR_OCCURRED=false
@@ -74,7 +184,7 @@ PREREQUISITES:
     - Git repository (git init)
     - OpenSpec artifacts created (openspec init, opsx-new, opsx-ff)
     - ralph CLI installed (npm install -g @th0rgal/ralph-wiggum)
-    - opencode CLI installed (npm install -g opencode)
+    - opencode CLI installed (npm install -g opencode-ai)
 
 EOF
 }
@@ -141,21 +251,29 @@ validate_git_repository() {
 validate_dependencies() {
     log_verbose "Validating dependencies..."
     
-    # Check for ralph
-    if ! command -v ralph &> /dev/null; then
+    if ! resolve_ralph_command; then
         log_error "ralph CLI not found."
         log_error "Please install open-ralph-wiggum: npm install -g @th0rgal/ralph-wiggum"
+        log_error "If spec-and-loop is globally installed, reinstalling it should also restore the bundled Ralph dependency."
         exit 1
     fi
-    log_verbose "Found: ralph"
+    log_verbose "Found Ralph command: ${RALPH_CMD[*]}"
     
     # Check for opencode
     if ! command -v opencode &> /dev/null; then
         log_error "opencode CLI not found."
-        log_error "Please install opencode: npm install -g opencode"
+        log_error "Please install opencode: npm install -g opencode-ai"
         exit 1
     fi
     log_verbose "Found: opencode"
+
+    # Check for jq
+    if ! command -v jq &> /dev/null; then
+        log_error "jq CLI not found."
+        log_error "Please install jq: brew install jq / apt-get install jq"
+        exit 1
+    fi
+    log_verbose "Found: jq"
     
     log_verbose "All dependencies validated"
 }
@@ -219,7 +337,7 @@ auto_detect_change() {
         if [[ -d "$change_dir" ]]; then
             local tasks_file="$change_dir/tasks.md"
             if [[ -f "$tasks_file" ]]; then
-                local mod_time=$(stat -c %Y "$tasks_file" 2>/dev/null || echo 0)
+                local mod_time=$(get_file_mtime "$tasks_file")
                 if [[ $mod_time -gt $latest_time ]]; then
                     latest_time=$mod_time
                     latest_change=$(basename "$change_dir")
@@ -323,7 +441,7 @@ parse_tasks() {
     TASKS_MD5=""
     
     if [[ -f "$tasks_file" ]]; then
-        TASKS_MD5=$(md5sum "$tasks_file" | cut -d' ' -f1)
+        TASKS_MD5=$(get_file_md5 "$tasks_file")
     fi
     
     log_verbose "Parsing tasks from tasks.md..."
@@ -356,7 +474,7 @@ check_tasks_modified() {
     fi
     
     local current_md5
-    current_md5=$(md5sum "$tasks_file" | cut -d' ' -f1)
+    current_md5=$(get_file_md5 "$tasks_file")
     
     if [[ "$current_md5" != "$original_md5" ]]; then
         return 0
@@ -566,15 +684,7 @@ sync_tasks_to_ralph() {
 
     # Resolve absolute path to tasks file (portable across Linux/macOS)
     local abs_tasks_file=""
-    if command -v realpath >/dev/null 2>&1; then
-        abs_tasks_file=$(realpath "$tasks_file" 2>/dev/null || true)
-    elif readlink -f / >/dev/null 2>&1; then
-        abs_tasks_file=$(readlink -f "$tasks_file" 2>/dev/null || true)
-    else
-        local _tdir
-        _tdir=$(cd "$(dirname "$tasks_file")" 2>/dev/null && pwd -P || echo "")
-        abs_tasks_file="$_tdir/$(basename "$tasks_file")"
-    fi
+    abs_tasks_file=$(get_realpath "$tasks_file")
     
     # Clean up old Ralph tasks file in change directory if exists
     if [[ -f "$old_ralph_tasks_file" ]]; then
@@ -589,16 +699,7 @@ sync_tasks_to_ralph() {
     if [[ -L "$ralph_tasks_file" ]]; then
         log_verbose "Symlink exists, ensuring it points to correct location"
         local current_target=""
-        if command -v realpath >/dev/null 2>&1; then
-            current_target=$(realpath "$ralph_tasks_file" 2>/dev/null || echo "")
-        elif readlink -f / >/dev/null 2>&1; then
-            current_target=$(readlink -f "$ralph_tasks_file" 2>/dev/null || echo "")
-        else
-            current_target=$(readlink "$ralph_tasks_file" 2>/dev/null || echo "")
-            if [[ -n "$current_target" && "$current_target" != /* ]]; then
-                current_target="$(cd "$(dirname "$ralph_tasks_file")" && pwd -P)/$current_target"
-            fi
-        fi
+        current_target=$(get_realpath "$ralph_tasks_file")
 
         if [[ "$current_target" != "$abs_tasks_file" ]]; then
             log_verbose "Updating symlink to point to new change directory"
@@ -625,7 +726,7 @@ create_prompt_template() {
     log_verbose "Creating custom prompt template..."
     
     local abs_change_dir
-    abs_change_dir=$(realpath "$change_dir" 2>/dev/null)
+    abs_change_dir=$(get_realpath "$change_dir")
     
     cat > "$template_file" << 'EOF'
 # Ralph Wiggum Task Execution - Iteration {{iteration}} / {{max_iterations}}
@@ -819,11 +920,9 @@ setup_output_capture() {
     
     log_verbose "Setting up output capture..."
     
-    # Create timestamped output directory in /tmp
-    local timestamp=$(date +"%Y%m%d_%H%M%S")
-    local output_dir="/tmp/ralph-run-$timestamp"
-    
-    mkdir -p "$output_dir"
+    # Use the system temp directory so macOS and Linux both work naturally.
+    local output_dir
+    output_dir=$(make_temp_dir "ralph-run")
     log_info "Output directory: $output_dir"
     
     # Store output directory path in Ralph directory for reference
@@ -835,8 +934,11 @@ setup_output_capture() {
 cleanup_old_output() {
     log_verbose "Cleaning up old Ralph output directories..."
     
+    local temp_root
+    temp_root=$(get_temp_root)
+    
     # Keep last 3 Ralph output directories, delete older ones
-    find /tmp -type d -name "ralph-run-*" -mtime +7d 2>/dev/null | while read old_dir; do
+    find "$temp_root" -type d -name "ralph-run*" -mtime +7 2>/dev/null | while IFS= read -r old_dir; do
         log_verbose "Removing old output directory: $old_dir"
         rm -rf "$old_dir"
     done
@@ -851,7 +953,7 @@ execute_ralph_loop() {
     log_info "Max iterations: $max_iterations"
     log_info "Change directory: $change_dir"
     
-    if ! command -v ralph &> /dev/null; then
+    if ! resolve_ralph_command; then
         log_error "ralph CLI not found."
         log_error "Please install open-ralph-wiggum: npm install -g @th0rgal/ralph-wiggum"
         return 1
@@ -897,7 +999,7 @@ execute_ralph_loop() {
     
     # Run Ralph and capture output to both console and files
     {
-        ralph --prompt-file "$ralph_dir/PRD.md" \
+        "${RALPH_CMD[@]}" --prompt-file "$ralph_dir/PRD.md" \
             --agent opencode \
             --tasks \
             --max-iterations "$max_iterations" \

package/scripts/setup.js

@@ -38,6 +38,6 @@ console.log('  ralph-run                       # Auto-detect change');
 console.log('');
 console.log('Prerequisites:');
 console.log('  - openspec CLI: npm install -g openspec');
-console.log('  - opencode CLI: npm install -g opencode');
+console.log('  - opencode CLI: npm install -g opencode-ai');
 console.log('  - jq CLI: apt install jq / brew install jq');
 console.log('  - git: git init');