autonomous-coding-toolkit 1.0.0

package/scripts/tests/test-validate-prd.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Test validate-prd.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+VALIDATOR="$SCRIPT_DIR/../validate-prd.sh"
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Helper: create a PRD file
+create_prd() {
+    local name="$1" content="$2"
+    mkdir -p "$WORK/tasks"
+    printf '%s\n' "$content" > "$WORK/tasks/$name"
+}
+
+# Helper: run validator against a temp PRD file
+run_validator() {
+    local exit_code=0
+    PRD_FILE="$WORK/tasks/prd.json" bash "$VALIDATOR" "$@" 2>&1 || exit_code=$?
+    echo "EXIT:$exit_code"
+}
+
+# === Test: Valid PRD passes ===
+create_prd "prd.json" '[
+  {
+    "id": 1,
+    "title": "First task",
+    "acceptance_criteria": ["test -f foo.txt"],
+    "passes": false,
+    "blocked_by": []
+  },
+  {
+    "id": 2,
+    "title": "Second task",
+    "acceptance_criteria": ["test -f bar.txt"],
+    "passes": false,
+    "blocked_by": [1]
+  }
+]'
+
+output=$(run_validator)
+assert_contains "valid PRD: PASS" "validate-prd: PASS" "$output"
+assert_contains "valid PRD: exit 0" "EXIT:0" "$output"
+
+# === Test: Invalid JSON fails ===
+create_prd "prd.json" 'this is not json at all {'
+
+output=$(run_validator)
+assert_contains "invalid JSON: reports violation" "Invalid JSON" "$output"
+assert_contains "invalid JSON: exit 1" "EXIT:1" "$output"
+
+# === Test: Not an array fails ===
+create_prd "prd.json" '{"id": 1, "title": "Not an array"}'
+
+output=$(run_validator)
+assert_contains "not array: reports violation" "must be a JSON array" "$output"
+assert_contains "not array: exit 1" "EXIT:1" "$output"
+
+# === Test: Missing id field fails ===
+create_prd "prd.json" '[
+  {
+    "title": "No ID",
+    "acceptance_criteria": ["test -f foo.txt"],
+    "blocked_by": []
+  }
+]'
+
+output=$(run_validator)
+assert_contains "missing id: reports violation" "missing or non-numeric 'id'" "$output"
+assert_contains "missing id: exit 1" "EXIT:1" "$output"
+
+# === Test: Missing title field fails ===
+create_prd "prd.json" '[
+  {
+    "id": 1,
+    "acceptance_criteria": ["test -f foo.txt"],
+    "blocked_by": []
+  }
+]'
+
+output=$(run_validator)
+assert_contains "missing title: reports violation" "missing or empty 'title'" "$output"
+assert_contains "missing title: exit 1" "EXIT:1" "$output"
+
+# === Test: Missing acceptance_criteria fails ===
+create_prd "prd.json" '[
+  {
+    "id": 1,
+    "title": "No criteria",
+    "blocked_by": []
+  }
+]'
+
+output=$(run_validator)
+assert_contains "missing criteria: reports violation" "missing or empty 'acceptance_criteria'" "$output"
+assert_contains "missing criteria: exit 1" "EXIT:1" "$output"
+
+# === Test: Empty acceptance_criteria fails ===
+create_prd "prd.json" '[
+  {
+    "id": 1,
+    "title": "Empty criteria",
+    "acceptance_criteria": [],
+    "blocked_by": []
+  }
+]'
+
+output=$(run_validator)
+assert_contains "empty criteria: reports violation" "missing or empty 'acceptance_criteria'" "$output"
+assert_contains "empty criteria: exit 1" "EXIT:1" "$output"
+
+# === Test: blocked_by references non-existent ID fails ===
+create_prd "prd.json" '[
+  {
+    "id": 1,
+    "title": "First",
+    "acceptance_criteria": ["true"],
+    "blocked_by": []
+  },
+  {
+    "id": 2,
+    "title": "Second",
+    "acceptance_criteria": ["true"],
+    "blocked_by": [99]
+  }
+]'
+
+output=$(run_validator)
+assert_contains "bad blocked_by: reports violation" "references non-existent ID 99" "$output"
+assert_contains "bad blocked_by: exit 1" "EXIT:1" "$output"
+
+# === Test: Self-referencing blocked_by fails ===
+create_prd "prd.json" '[
+  {
+    "id": 1,
+    "title": "Self-blocking",
+    "acceptance_criteria": ["true"],
+    "blocked_by": [1]
+  }
+]'
+
+output=$(run_validator)
+assert_contains "self-ref: reports violation" "blocks itself" "$output"
+assert_contains "self-ref: exit 1" "EXIT:1" "$output"
+
+# === Test: Single file argument ===
+create_prd "custom.json" '[
+  {
+    "id": 1,
+    "title": "Custom file",
+    "acceptance_criteria": ["true"],
+    "blocked_by": []
+  }
+]'
+
+exit_code=0
+output=$(bash "$VALIDATOR" "$WORK/tasks/custom.json" 2>&1) || exit_code=$?
+output="${output}
+EXIT:${exit_code}"
+assert_contains "single file arg: PASS" "validate-prd: PASS" "$output"
+assert_contains "single file arg: exit 0" "EXIT:0" "$output"
+
+# === Test: --warn exits 0 even with violations ===
+create_prd "prd.json" 'not json'
+
+output=$(run_validator --warn)
+assert_contains "--warn: still reports violation" "Invalid JSON" "$output"
+assert_contains "--warn: exits 0" "EXIT:0" "$output"
+
+# === Test: --help exits 0 ===
+output=$(run_validator --help)
+assert_contains "--help: shows usage" "Usage:" "$output"
+assert_contains "--help: exits 0" "EXIT:0" "$output"
+
+# === Test: Missing PRD file fails ===
+rm -f "$WORK/tasks/prd.json"
+output=$(PRD_FILE="$WORK/tasks/nonexistent.json" bash "$VALIDATOR" 2>&1 || echo "EXIT:$?")
+assert_contains "missing file: error message" "PRD file not found" "$output"
+assert_contains "missing file: exit 1" "EXIT:1" "$output"
+
+report_results

package/scripts/tests/test-validate-skills.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Test validate-skills.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+VALIDATOR="$SCRIPT_DIR/../validate-skills.sh"
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Helper: create a skill directory with SKILL.md
+create_skill() {
+    local name="$1" content="$2"
+    mkdir -p "$WORK/skills/$name"
+    echo "$content" > "$WORK/skills/$name/SKILL.md"
+}
+
+# Helper: create a companion file in a skill directory
+create_companion() {
+    local skill="$1" file="$2"
+    echo "# Companion" > "$WORK/skills/$skill/$file"
+}
+
+# Helper: run validator against temp skills dir
+run_validator() {
+    local exit_code=0
+    SKILLS_DIR="$WORK/skills" bash "$VALIDATOR" "$@" 2>&1 || exit_code=$?
+    echo "EXIT:$exit_code"
+}
+
+# === Test: Valid skill passes ===
+rm -rf "$WORK/skills"
+create_skill "my-skill" '---
+name: my-skill
+description: "A test skill"
+---
+Body text here.'
+
+output=$(run_validator)
+assert_contains "valid skill: PASS" "validate-skills: PASS" "$output"
+assert_contains "valid skill: exit 0" "EXIT:0" "$output"
+
+# === Test: Missing name field fails ===
+rm -rf "$WORK/skills"
+create_skill "no-name" '---
+description: "Missing name"
+---
+Body.'
+
+output=$(run_validator)
+assert_contains "missing name: reports violation" "Missing required field: name" "$output"
+assert_contains "missing name: exit 1" "EXIT:1" "$output"
+
+# === Test: Missing description field fails ===
+rm -rf "$WORK/skills"
+create_skill "no-desc" '---
+name: no-desc
+---
+Body.'
+
+output=$(run_validator)
+assert_contains "missing description: reports violation" "Missing required field: description" "$output"
+assert_contains "missing description: exit 1" "EXIT:1" "$output"
+
+# === Test: Name mismatch with directory fails ===
+rm -rf "$WORK/skills"
+create_skill "actual-dir" '---
+name: wrong-name
+description: "Name does not match directory"
+---
+Body.'
+
+output=$(run_validator)
+assert_contains "name mismatch: reports violation" "name 'wrong-name' does not match directory 'actual-dir'" "$output"
+assert_contains "name mismatch: exit 1" "EXIT:1" "$output"
+
+# === Test: Referenced .md file missing fails ===
+rm -rf "$WORK/skills"
+create_skill "has-ref" '---
+name: has-ref
+description: "References a companion file"
+---
+See details in companion-doc.md for more.'
+
+output=$(run_validator)
+assert_contains "missing ref: reports violation" "Referenced file not found: companion-doc.md" "$output"
+assert_contains "missing ref: exit 1" "EXIT:1" "$output"
+
+# === Test: Referenced .md file exists passes ===
+rm -rf "$WORK/skills"
+create_skill "has-ref-ok" '---
+name: has-ref-ok
+description: "References a companion file that exists"
+---
+See details in companion-doc.md for more.'
+create_companion "has-ref-ok" "companion-doc.md"
+
+output=$(run_validator)
+assert_contains "existing ref: PASS" "validate-skills: PASS" "$output"
+assert_contains "existing ref: exit 0" "EXIT:0" "$output"
+
+# === Test: Missing frontmatter start fails ===
+rm -rf "$WORK/skills"
+create_skill "no-front" 'name: no-front
+description: "No frontmatter markers"'
+
+output=$(run_validator)
+assert_contains "missing ---: reports violation" "First line must be '---'" "$output"
+assert_contains "missing ---: exit 1" "EXIT:1" "$output"
+
+# === Test: --warn exits 0 even with violations ===
+rm -rf "$WORK/skills"
+create_skill "warn-test" '---
+description: "Missing name"
+---
+Body.'
+
+output=$(run_validator --warn)
+assert_contains "--warn: still reports violation" "Missing required field: name" "$output"
+assert_contains "--warn: exits 0" "EXIT:0" "$output"
+
+# === Test: --help exits 0 ===
+output=$(run_validator --help)
+assert_contains "--help: shows usage" "Usage:" "$output"
+assert_contains "--help: exits 0" "EXIT:0" "$output"
+
+# === Test: Missing skills directory fails ===
+rm -rf "$WORK/skills"
+output=$(SKILLS_DIR="$WORK/nonexistent" bash "$VALIDATOR" 2>&1 || echo "EXIT:$?")
+assert_contains "missing dir: error message" "skills directory not found" "$output"
+assert_contains "missing dir: exit 1" "EXIT:1" "$output"
+
+report_results

package/scripts/validate-all.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# validate-all.sh — Run all repo-level validators and report summary
+# Exit 0 if all pass, exit 1 if any fail. Use --warn to pass through to validators.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS_ARGS=()
+
+usage() {
+    echo "Usage: validate-all.sh [--warn] [--help]"
+    echo "  Runs all repo-level validators (lessons, skills, commands, plugin, hooks, policies)"
+    echo "  --warn   Pass --warn to all validators (print violations but exit 0)"
+    exit 0
+}
+
+[[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && usage
+[[ "${1:-}" == "--warn" ]] && PASS_ARGS=("--warn")
+
+validators=(
+    validate-lessons
+    validate-skills
+    validate-commands
+    validate-plugin
+    validate-hooks
+    validate-policies
+)
+
+total=${#validators[@]}
+passed=0
+failed_names=()
+
+for name in "${validators[@]}"; do
+    script="$SCRIPT_DIR/${name}.sh"
+    if [[ ! -f "$script" ]]; then
+        echo "  $name: SKIP (not found)"
+        continue
+    fi
+
+    exit_code=0
+    bash "$script" ${PASS_ARGS[@]+"${PASS_ARGS[@]}"} >/dev/null 2>&1 || exit_code=$?
+
+    if [[ $exit_code -eq 0 ]]; then
+        echo "  $name: PASS"
+        ((passed++)) || true
+    else
+        echo "  $name: FAIL"
+        failed_names+=("$name")
+    fi
+done
+
+echo ""
+echo "$passed/$total validators passed"
+
+if [[ ${#failed_names[@]} -gt 0 ]]; then
+    echo "Failed: ${failed_names[*]}"
+    exit 1
+fi

package/scripts/validate-commands.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# validate-commands.sh — Validate command file frontmatter
+# Exit 0 if clean, exit 1 if violations found. Use --warn to print but exit 0.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMMANDS_DIR="${COMMANDS_DIR:-$SCRIPT_DIR/../commands}"
+WARN_ONLY=false
+violations=0
+
+usage() {
+    echo "Usage: validate-commands.sh [--warn] [--help]"
+    echo "  Validates all commands/*.md files"
+    echo "  --warn   Print violations but exit 0"
+    exit 0
+}
+
+report_violation() {
+    local file="$1" line="$2" msg="$3"
+    echo "${file}:${line}: ${msg}"
+    ((violations++)) || true
+}
+
+[[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && usage
+[[ "${1:-}" == "--warn" ]] && WARN_ONLY=true
+
+if [[ ! -d "$COMMANDS_DIR" ]]; then
+    echo "validate-commands: commands directory not found: $COMMANDS_DIR" >&2
+    exit 1
+fi
+
+for cmd_file in "$COMMANDS_DIR"/*.md; do
+    [[ -f "$cmd_file" ]] || continue
+    fname="$(basename "$cmd_file")"
+
+    # Check 1: First line must be ---
+    first_line=$(head -1 "$cmd_file")
+    if [[ "$first_line" != "---" ]]; then
+        report_violation "$fname" 1 "First line must be '---', got '$first_line'"
+        continue
+    fi
+
+    # Check 2: Second --- delimiter must exist (frontmatter is closed)
+    closing_line=$(sed -n '2,$ { /^---$/= }' "$cmd_file" | head -1)
+    if [[ -z "$closing_line" ]]; then
+        report_violation "$fname" 0 "Frontmatter not closed (missing second '---')"
+        continue
+    fi
+
+    # Extract frontmatter (between first two --- lines)
+    frontmatter=$(sed -n '2,/^---$/{ /^---$/d; p; }' "$cmd_file")
+
+    # Check 3: Required fields
+    if ! echo "$frontmatter" | grep -q "^description:"; then
+        report_violation "$fname" 0 "Missing required field: description"
+    fi
+done
+
+if [[ $violations -gt 0 ]]; then
+    echo ""
+    echo "validate-commands: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+else
+    echo "validate-commands: PASS"
+    exit 0
+fi

package/scripts/validate-hooks.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# validate-hooks.sh — Validate hooks/hooks.json and referenced scripts
+# Exit 0 if clean, exit 1 if violations found. Use --warn to print but exit 0.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOKS_DIR="${HOOKS_DIR:-$SCRIPT_DIR/../hooks}"
+TOOLKIT_ROOT="${TOOLKIT_ROOT:-$SCRIPT_DIR/..}"
+WARN_ONLY=false
+violations=0
+
+usage() {
+    echo "Usage: validate-hooks.sh [--warn] [--help]"
+    echo "  Validates hooks/hooks.json and referenced scripts"
+    echo "  --warn   Print violations but exit 0"
+    exit 0
+}
+
+report_violation() {
+    local file="$1" msg="$2"
+    echo "${file}: ${msg}"
+    ((violations++)) || true
+}
+
+[[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && usage
+[[ "${1:-}" == "--warn" ]] && WARN_ONLY=true
+
+if [[ ! -d "$HOOKS_DIR" ]]; then
+    echo "validate-hooks: hooks directory not found: $HOOKS_DIR" >&2
+    exit 1
+fi
+
+hooks_file="$HOOKS_DIR/hooks.json"
+if [[ ! -f "$hooks_file" ]]; then
+    report_violation "hooks.json" "hooks.json not found"
+    echo ""
+    echo "validate-hooks: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+fi
+
+# Validate JSON
+if ! jq empty "$hooks_file" 2>/dev/null; then
+    report_violation "hooks.json" "hooks.json is not valid JSON"
+    echo ""
+    echo "validate-hooks: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+fi
+
+# Extract all command paths from hooks — walks the entire JSON tree for "command" keys
+commands=$(jq -r '.. | objects | select(.type == "command") | .command' "$hooks_file" 2>/dev/null || true)
+
+while IFS= read -r cmd; do
+    [[ -z "$cmd" ]] && continue
+    # Resolve ${CLAUDE_PLUGIN_ROOT} to toolkit root
+    resolved="${cmd//\$\{CLAUDE_PLUGIN_ROOT\}/$TOOLKIT_ROOT}"
+
+    # Extract the script path (last token that looks like a file path)
+    # Handles "bash /path/to/script.sh" and "/path/to/script.sh" alike
+    script_path="$resolved"
+    for token in $resolved; do
+        if [[ "$token" == /* || "$token" == \$* ]]; then
+            script_path="$token"
+            break
+        fi
+    done
+
+    # Skip if the resolved path is just a bare command (e.g., "bash" — not a file check target)
+    if [[ "$script_path" != */* ]]; then
+        continue
+    fi
+
+    if [[ ! -f "$script_path" ]]; then
+        report_violation "hooks.json" "script not found: $cmd (resolved: $script_path)"
+    elif [[ ! -x "$script_path" ]]; then
+        report_violation "hooks.json" "script not executable: $cmd (resolved: $script_path)"
+    fi
+done <<< "$commands"
+
+if [[ $violations -gt 0 ]]; then
+    echo ""
+    echo "validate-hooks: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+else
+    echo "validate-hooks: PASS"
+    exit 0
+fi

package/scripts/validate-lessons.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# validate-lessons.sh — Validate lesson file format and frontmatter
+# Exit 0 if clean, exit 1 if violations found. Use --warn to print but exit 0.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LESSONS_DIR="${LESSONS_DIR:-$SCRIPT_DIR/../docs/lessons}"
+WARN_ONLY=false
+violations=0
+
+usage() {
+    echo "Usage: validate-lessons.sh [--warn] [--help]"
+    echo "  Validates all lesson files in docs/lessons/"
+    echo "  --warn   Print violations but exit 0"
+    exit 0
+}
+
+report_violation() {
+    local file="$1" line="$2" msg="$3"
+    echo "${file}:${line}: ${msg}"
+    ((violations++)) || true
+}
+
+[[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && usage
+[[ "${1:-}" == "--warn" ]] && WARN_ONLY=true
+
+if [[ ! -d "$LESSONS_DIR" ]]; then
+    echo "validate-lessons: lessons directory not found: $LESSONS_DIR" >&2
+    exit 1
+fi
+
+seen_ids=()
+
+for lesson in "$LESSONS_DIR"/[0-9]*.md; do
+    [[ -f "$lesson" ]] || continue
+    fname="$(basename "$lesson")"
+
+    # Check 1: First line must be ---
+    first_line=$(head -1 "$lesson")
+    if [[ "$first_line" != "---" ]]; then
+        report_violation "$fname" 1 "First line must be '---', got '$first_line' (code block wrapping?)"
+        continue  # Can't parse frontmatter if start is wrong
+    fi
+
+    # Extract frontmatter (between first two --- lines)
+    frontmatter=$(sed -n '2,/^---$/{ /^---$/d; p; }' "$lesson")
+
+    # Check 2: Required fields
+    for field in id title severity languages; do
+        if ! echo "$frontmatter" | grep -q "^${field}:"; then
+            report_violation "$fname" 0 "Missing required field: $field"
+        fi
+    done
+
+    # Check 3: pattern.type must exist
+    if ! echo "$frontmatter" | grep -q "type:"; then
+        report_violation "$fname" 0 "Missing pattern.type field"
+    fi
+
+    # Check 4: Extract and validate ID
+    lesson_id=$(echo "$frontmatter" | sed -n 's/^id:[[:space:]]*\(.*\)/\1/p' | tr -d ' "'"'"'')
+    if [[ -n "$lesson_id" ]]; then
+        # Check for duplicate IDs
+        for seen in "${seen_ids[@]+"${seen_ids[@]}"}"; do
+            if [[ "$seen" == "$lesson_id" ]]; then
+                report_violation "$fname" 0 "Duplicate lesson ID: $lesson_id"
+            fi
+        done
+        seen_ids+=("$lesson_id")
+    fi
+
+    # Check 5: Severity must be valid
+    severity=$(echo "$frontmatter" | sed -n 's/^severity:[[:space:]]*\(.*\)/\1/p' | tr -d ' ')
+    if [[ -n "$severity" ]]; then
+        case "$severity" in
+            blocker|should-fix|nice-to-have) ;;
+            *) report_violation "$fname" 0 "Invalid severity '$severity' (must be blocker|should-fix|nice-to-have)" ;;
+        esac
+    fi
+
+    # Check 6: Syntactic lessons must have regex
+    pattern_type=$(echo "$frontmatter" | grep "type:" | tail -1 | sed 's/.*type:[[:space:]]*//' | tr -d ' ')
+    if [[ "$pattern_type" == "syntactic" ]]; then
+        if ! echo "$frontmatter" | grep -q "regex:"; then
+            report_violation "$fname" 0 "Syntactic lesson missing regex field"
+        fi
+    fi
+done
+
+if [[ $violations -gt 0 ]]; then
+    echo ""
+    echo "validate-lessons: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+else
+    echo "validate-lessons: PASS"
+    exit 0
+fi