spec-and-loop 1.0.6 → 1.0.7

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.7",
   "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,6 +2,27 @@
 
 set -e
 
+# 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 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
+}
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CHANGE_NAME="${1:-auto-detect}"
 
@@ -85,7 +106,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,58 @@ 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
+}
+
 CHANGE_NAME=""
 MAX_ITERATIONS=""
 ERROR_OCCURRED=false
@@ -219,7 +271,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 +375,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 +408,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 +618,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 +633,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 +660,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}}