@windyroad/tdd 0.1.2 → 0.1.4-preview.26

package/README.md

@@ -0,0 +1,71 @@
+# @windyroad/tdd
+
+**TDD state machine enforcement for Claude Code.** Forces the Red-Green-Refactor cycle so your AI agent writes tests before implementation -- every time.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+AI agents love to jump straight to implementation. This plugin stops that. It enforces a strict TDD state machine:
+
+```
+IDLE ──> RED ──> GREEN ──> RED (next test)
+                   │
+                   └──> Refactor (staying GREEN)
+```
+
+- **IDLE** -- No test written yet. Implementation file edits are blocked.
+- **RED** -- A failing test exists. Implementation edits are allowed.
+- **GREEN** -- Tests pass. You can refactor or write a new failing test.
+- **BLOCKED** -- Test runner error or timeout. Fix the setup before continuing.
+
+The agent must write a failing test first. There are no shortcuts.
+
+## Install
+
+```bash
+npx @windyroad/tdd
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+The plugin activates automatically. On first use in a project without a test framework, it directs you to set one up:
+
+```
+/wr-tdd:setup-tests
+```
+
+This examines your codebase, recommends a test runner, configures `package.json`, and creates an example test.
+
+Once active, the workflow is enforced on every edit:
+
+1. Write a test file (`*.test.ts`, `*.spec.ts`, etc.) that describes the desired behaviour
+2. The test must fail (RED state) -- proving the test is meaningful
+3. Write the minimum implementation to make it pass (GREEN state)
+4. Refactor while keeping tests green
+5. Repeat
+
+Test files and config/doc files are always writable regardless of state.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `tdd-inject.sh` | Every prompt | Injects the current TDD state into the prompt |
+| `tdd-enforce-edit.sh` | Edit or Write | Blocks implementation edits in IDLE or BLOCKED state |
+| `tdd-post-write.sh` | After edit | Runs tests and transitions the state machine |
+| `tdd-setup-marker.sh` | Skill completes | Marks test setup as done |
+| `tdd-reset.sh` | Session end | Resets the TDD state |
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/tdd --update
+npx @windyroad/tdd --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/hooks/hooks.json

@@ -7,7 +7,8 @@
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-enforce-edit.sh" }] }
     ],
     "PostToolUse": [
-      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-post-write.sh" }] }
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-post-write.sh" }] },
+      { "matcher": "Skill", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-setup-marker.sh" }] }
     ],
     "Stop": [
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-reset.sh" }] }

package/hooks/lib/tdd-gate.sh

@@ -27,8 +27,8 @@ tdd_classify_file() {
 
   # Exempt files (not gated)
   case "$FILE_PATH" in
-    # Config files
-    *.config.*|*.json|*.yml|*.yaml) echo "exempt"; return ;;
+    # Config and setup files (test infrastructure)
+    *.config.*|*.setup.*|*.json|*.yml|*.yaml) echo "exempt"; return ;;
     # Module configs (*.mjs, *.cjs are config when at root or named as config)
     *.mjs|*.cjs) echo "exempt"; return ;;
     # Styles
@@ -158,6 +158,7 @@ tdd_cleanup() {
   rm -f "$(_tdd_state_file "$SESSION_ID")"
   rm -f "$(_tdd_test_files_file "$SESSION_ID")"
   rm -f "$(_tdd_test_stdout_file "$SESSION_ID")"
+  rm -f "/tmp/tdd-setup-active-${SESSION_ID}"
 }
 
 # --- Deny Helper ---

package/hooks/tdd-enforce-edit.sh

@@ -21,10 +21,14 @@ if [ "$FILE_TYPE" != "impl" ]; then
   exit 0
 fi
 
-# If no test script configured, block and direct to create skill
+# If no test script configured, check if setup skill is running
 if ! tdd_has_test_script; then
+  # Allow edits if the setup skill is actively running (chicken-and-egg bypass)
+  if [ -n "$SESSION_ID" ] && [ -f "/tmp/tdd-setup-active-${SESSION_ID}" ]; then
+    exit 0
+  fi
   BASENAME=$(basename "$FILE_PATH")
-  tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' because no test script is configured in package.json. Run /wr-tdd:create to set up a test framework for this project. TDD enforcement requires a working test runner before implementation code can be written."
+  tdd_deny_json "BLOCKED: Cannot edit '${BASENAME}' because no test script is configured in package.json. Run /wr-tdd:setup-tests to set up a test framework for this project. TDD enforcement requires a working test runner before implementation code can be written."
   exit 0
 fi
 

package/hooks/tdd-inject.sh

@@ -18,7 +18,7 @@ This project has NO test script configured in package.json. Implementation file
 edits (.ts, .tsx, .js, .jsx) are BLOCKED until testing is set up.
 
 If the user's task involves writing or editing implementation code, you MUST
-run /wr-tdd:create first to configure a test framework for this project.
+run /wr-tdd:setup-tests first to configure a test framework for this project.
 
 Test files, config files, docs, and styles are still writable.
 HOOK_OUTPUT

package/hooks/tdd-setup-marker.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# PostToolUse:Skill hook — sets a marker when /wr-tdd:setup-tests is invoked.
+# This marker allows tdd-enforce-edit.sh to permit edits during test setup,
+# avoiding the chicken-and-egg problem where the setup skill needs to write
+# .ts/.js files but the enforce hook blocks them.
+
+INPUT=$(cat)
+
+SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ] || [ -z "$SKILL_NAME" ]; then
+  exit 0
+fi
+
+# Match the TDD setup skill (handles both full and short names)
+case "$SKILL_NAME" in
+  *tdd*setup*|*setup*test*)
+    touch "/tmp/tdd-setup-active-${SESSION_ID}"
+    ;;
+esac
+
+exit 0

package/hooks/test/tdd-gate.bats

@@ -0,0 +1,133 @@
+#!/usr/bin/env bats
+
+# Tests for tdd-gate.sh shared library functions
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  source "$SCRIPT_DIR/lib/tdd-gate.sh"
+  TEST_SESSION="test-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  tdd_cleanup "$TEST_SESSION" 2>/dev/null || true
+  rm -f "/tmp/tdd-setup-active-${TEST_SESSION}"
+}
+
+# --- tdd_classify_file ---
+
+@test "classify_file: .test.ts is test" {
+  result=$(tdd_classify_file "src/utils.test.ts")
+  [ "$result" = "test" ]
+}
+
+@test "classify_file: .spec.jsx is test" {
+  result=$(tdd_classify_file "src/App.spec.jsx")
+  [ "$result" = "test" ]
+}
+
+@test "classify_file: __tests__ directory is test" {
+  result=$(tdd_classify_file "src/__tests__/utils.ts")
+  [ "$result" = "test" ]
+}
+
+@test "classify_file: .config.ts is exempt" {
+  result=$(tdd_classify_file "vitest.config.ts")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .setup.ts is exempt" {
+  result=$(tdd_classify_file "vitest.setup.ts")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .json is exempt" {
+  result=$(tdd_classify_file "package.json")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .css is exempt" {
+  result=$(tdd_classify_file "src/styles.css")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .md is exempt" {
+  result=$(tdd_classify_file "README.md")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .sh is exempt" {
+  result=$(tdd_classify_file "scripts/build.sh")
+  [ "$result" = "exempt" ]
+}
+
+@test "classify_file: .ts is impl" {
+  result=$(tdd_classify_file "src/utils.ts")
+  [ "$result" = "impl" ]
+}
+
+@test "classify_file: .tsx is impl" {
+  result=$(tdd_classify_file "src/App.tsx")
+  [ "$result" = "impl" ]
+}
+
+@test "classify_file: .js is impl" {
+  result=$(tdd_classify_file "src/index.js")
+  [ "$result" = "impl" ]
+}
+
+@test "classify_file: unknown extension is exempt" {
+  result=$(tdd_classify_file "Dockerfile")
+  [ "$result" = "exempt" ]
+}
+
+# --- tdd_has_test_script ---
+
+@test "has_test_script: returns false when no package.json" {
+  cd "$(mktemp -d)"
+  run tdd_has_test_script
+  [ "$status" -ne 0 ]
+}
+
+@test "has_test_script: returns false for default npm test script" {
+  local tmpdir=$(mktemp -d)
+  echo '{"scripts":{"test":"echo \"Error: no test specified\" && exit 1"}}' > "$tmpdir/package.json"
+  cd "$tmpdir"
+  run tdd_has_test_script
+  [ "$status" -ne 0 ]
+  rm -rf "$tmpdir"
+}
+
+@test "has_test_script: returns true for real test script" {
+  local tmpdir=$(mktemp -d)
+  echo '{"scripts":{"test":"vitest"}}' > "$tmpdir/package.json"
+  cd "$tmpdir"
+  run tdd_has_test_script
+  [ "$status" -eq 0 ]
+  rm -rf "$tmpdir"
+}
+
+# --- tdd state ---
+
+@test "read_state: returns IDLE when no state file" {
+  result=$(tdd_read_state "$TEST_SESSION")
+  [ "$result" = "IDLE" ]
+}
+
+@test "write_state and read_state roundtrip" {
+  tdd_write_state "$TEST_SESSION" "RED"
+  result=$(tdd_read_state "$TEST_SESSION")
+  [ "$result" = "RED" ]
+}
+
+@test "cleanup removes state files" {
+  tdd_write_state "$TEST_SESSION" "GREEN"
+  tdd_cleanup "$TEST_SESSION"
+  result=$(tdd_read_state "$TEST_SESSION")
+  [ "$result" = "IDLE" ]
+}
+
+@test "cleanup removes setup marker" {
+  touch "/tmp/tdd-setup-active-${TEST_SESSION}"
+  tdd_cleanup "$TEST_SESSION"
+  [ ! -f "/tmp/tdd-setup-active-${TEST_SESSION}" ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/tdd",
-  "version": "0.1.2",
+  "version": "0.1.4-preview.26",
   "description": "TDD state machine enforcement (Red-Green-Refactor cycle)",
   "bin": {
     "windyroad-tdd": "./bin/install.mjs"

package/skills/{wr:tdd → setup-tests}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:tdd
+name: wr-tdd:setup-tests
 description: Set up a test framework for the project. Examines the codebase, recommends a test runner, configures package.json, and creates an example test.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---