From a857953a80471f321c231ba2777e3db3a12c9913 Mon Sep 17 00:00:00 2001
From: Jay <wisehodl@pm.me>
Date: Wed, 9 Sep 2026 09:22:48 -0400
Subject: [PATCH] Added docker-based testing environment for neo4j integration
 testing.

---
 AGENTS.md    |  6 +-----
 compose.yaml | 37 +++++++++++++++++++++++++++++++++++++
 test         | 18 ++++++++++++++++++
 3 files changed, 56 insertions(+), 5 deletions(-)
 create mode 100644 compose.yaml
 create mode 100755 test

diff --git a/AGENTS.md b/AGENTS.md
index 880c3ff..7d380e8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,9 +1,5 @@
 # go-heartwood
 
-## Agent Skills
-- Skills are located in `~/.pi/agent/skills/`
-- Skill scripts are located in their respective skill directories under `scripts/` -- look for them there, not in this repository.
-
 ## Testing
-- Baseline: `go test -race -gcflags "all=-d=checkptr=0" ./...`
+- Baseline: `./test dev -race -gcflags "all=-d=checkptr=0" ./...`
 - `boltdb/bolt@v1.3.1` triggers a `checkptr` panic under race instrumentation; this is an upstream bug, not a project defect.
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 0000000..fa99226
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,37 @@
+services:
+  test:
+    image: golang:1.26
+    environment:
+      CGO_ENABLED: 1
+      NEO4J_USER: neo4j
+      NEO4J_PASS: heartwood
+      NEO4J_URI: bolt://neo4j:7687
+    working_dir: /app
+    volumes:
+      - ".:/app"
+      - go-mod-cache:/go/pkg/mod
+      - go-build-cache:/root/.cache/go-build
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    restart: always
+    command: "tail -f /dev/null"
+    healthcheck:
+      test: ["CMD-SHELL", "go version | grep -q 'go version'"]
+      start_period: 20s
+  neo4j:
+    image: neo4j:5
+    environment:
+      - NEO4J_AUTH=neo4j/heartwood
+    restart: always
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "cypher-shell -u neo4j -p heartwood 'RETURN 1;' 2>/dev/null | grep -q '1'",
+        ]
+      start_period: 20s
+
+volumes:
+  go-mod-cache:
+  go-build-cache:
diff --git a/test b/test
new file mode 100755
index 0000000..9dfeab1
--- /dev/null
+++ b/test
@@ -0,0 +1,18 @@
+#!/bin/bash
+set -eou pipefail
+case "${1:-dev}" in
+dev) docker compose up -d --wait && docker compose exec test go test "${@:2}" ;;
+ci) docker compose run --rm test go test "${@:2}" ;;
+*)
+  echo "Usage: $0 [dev|ci] [go test arguments...]"
+  echo
+  echo "Commands:"
+  echo "    dev    Start services and run tests in the existing test container (default)."
+  echo "    ci     Execute tests in a new, one-off container and clean up."
+  echo
+  echo "Examples:"
+  echo "    $0 dev ./... -v"
+  echo "    $0 ci -run TestSpecificFunction"
+  exit 1
+  ;;
+esac