Add JSON CLI bridge and Python/Java wrappers (#4)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Follow-up (latest)

- **Strict stdin JSON:** `parseRequest` now rejects multiple JSON values
or trailing garbage after the first object (single-request protocol).
- **Python `GIT_HARNESS_CLI`:** Bare names (e.g. `git-harness-cli`) are
resolved with `shutil.which` before falling back to a path under the
repo root, matching Java `ProcessBuilder` PATH behavior.
- **Tests:** Added coverage for trailing JSON rejection and PATH-based
`_cli_cmd` resolution.

All inline review threads on this PR are resolved as of the latest push.
<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-b5ff7da1-12de-491e-87e3-bdb30815a92e"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-b5ff7da1-12de-491e-87e3-bdb30815a92e"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* JSON CLI bridge plus Python and Java client libraries with runnable
smoke samples for both languages; CLI can be prebuilt and configured via
an environment variable.

* **Documentation**
* New polyglot spec, plan, checklist, and testkit READMEs describing
layout, usage, validation, and quality criteria.

* **Tests**
* Added Python pytest and Java JUnit smoke/integration tests exercising
end-to-end bridge behavior.

* **Chores**
* CI updated to validate spec-kit artifacts, build the CLI once, and run
wrapper tests across Linux/macOS/Windows; updated ignore rules.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Ben Schellenberger <bschellenberger2600@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: CodeRabbit <noreply@coderabbit.ai>

Author: 4 people

.github/workflows/ci.yml

@@ -10,6 +10,23 @@ permissions:
   contents: read
 
 jobs:
+  spec-kit-conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate spec-kit artifact set
+        run: |
+          test -f testkit/.specify/memory/constitution.md
+          test -f testkit/.specify/specs/001-polyglot-harness/spec.md
+          test -f testkit/.specify/specs/001-polyglot-harness/plan.md
+          test -f testkit/.specify/specs/001-polyglot-harness/tasks.md
+          test -f testkit/.specify/specs/001-polyglot-harness/contracts/cli-protocol.json
+          test -f testkit/.specify/specs/001-polyglot-harness/checklists/quality.md
+
+      - name: Validate spec-kit scaffold and status
+        run: ./testkit/.specify/scripts/validate_specify.sh
+
   test:
     runs-on: ubuntu-latest
     steps:
@@ -21,7 +38,7 @@ jobs:
           cache: true
 
       - name: Check gofmt
-        run: test -z "$(gofmt -l git safety)"
+        run: test -z "$(gofmt -l git safety cmd)"
 
       - name: Build
         run: go build ./...
@@ -31,3 +48,129 @@ jobs:
 
       - name: Test
         run: go test -race -count=1 ./...
+
+  testkit:
+    runs-on: ubuntu-latest
+    needs: [spec-kit-conformance, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Build git-harness CLI binary once
+        run: |
+          mkdir -p bin
+          go build -o ./bin/git-harness-cli ./cmd/git-harness-cli
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+
+      - name: Run Python wrapper tests
+        env:
+          GIT_HARNESS_CLI: ./bin/git-harness-cli
+        run: |
+          cd testkit/python
+          python -m pip install -e ".[dev]"
+          python -m pytest tests/ -v
+
+      - name: Run Python sample smoke implementations
+        env:
+          GIT_HARNESS_CLI: ./bin/git-harness-cli
+        run: |
+          cd testkit/python
+          python -m samples.smoke_repo_flow
+          python -m samples.smoke_safety_flow
+
+      - name: Run Java wrapper tests
+        env:
+          GIT_HARNESS_CLI: ./bin/git-harness-cli
+        run: |
+          cd testkit/java
+          mvn test
+
+      - name: Run Java sample smoke implementations
+        env:
+          GIT_HARNESS_CLI: ./bin/git-harness-cli
+        run: |
+          cd testkit/java
+          mvn -Dtest=SampleRepoFlowSmoke,SampleSafetyFlowSmoke test
+
+  wrapper-cross-platform:
+    runs-on: ${{ matrix.os }}
+    needs: [spec-kit-conformance, test]
+    strategy:
+      fail-fast: false
+      matrix:
+        # Linux wrapper path is covered by the `testkit` job; matrix only cross-checks macOS + Windows.
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Build git-harness CLI binary once
+        shell: bash
+        run: |
+          mkdir -p bin
+          if [[ "${{ matrix.os }}" == "windows-latest" ]]; then
+            go build -o ./bin/git-harness-cli.exe ./cmd/git-harness-cli
+          else
+            go build -o ./bin/git-harness-cli ./cmd/git-harness-cli
+          fi
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+          cache: maven
+
+      - name: Run Python wrapper smoke tests
+        shell: bash
+        env:
+          GIT_HARNESS_CLI: ${{ matrix.os == 'windows-latest' && './bin/git-harness-cli.exe' || './bin/git-harness-cli' }}
+        run: |
+          cd testkit/python
+          python -m pip install -e ".[dev]"
+          python -m pytest tests/ -v
+
+      - name: Run Python sample smoke implementations
+        shell: bash
+        env:
+          GIT_HARNESS_CLI: ${{ matrix.os == 'windows-latest' && './bin/git-harness-cli.exe' || './bin/git-harness-cli' }}
+        run: |
+          cd testkit/python
+          python -m samples.smoke_repo_flow
+          python -m samples.smoke_safety_flow
+
+      - name: Run Java wrapper smoke tests
+        shell: bash
+        env:
+          GIT_HARNESS_CLI: ${{ matrix.os == 'windows-latest' && './bin/git-harness-cli.exe' || './bin/git-harness-cli' }}
+        run: |
+          cd testkit/java
+          mvn test
+
+      - name: Run Java sample smoke implementations
+        shell: bash
+        env:
+          GIT_HARNESS_CLI: ${{ matrix.os == 'windows-latest' && './bin/git-harness-cli.exe' || './bin/git-harness-cli' }}
+        run: |
+          cd testkit/java
+          mvn -Dtest=SampleRepoFlowSmoke,SampleSafetyFlowSmoke test

.gitignore

@@ -1,2 +1,8 @@
 # Local reference clones (not part of this module)
 /mnt/
+
+# testkit (polyglot) build artifacts
+testkit/python/**/__pycache__/
+testkit/python/**/*.egg-info/
+testkit/python/.pytest_cache/
+testkit/java/target/

CURSOR_ULTRA_PLAN.md

@@ -113,11 +113,10 @@ git-harness/
   .github/
     workflows/
       ci.yml          # Go build + test + vet
-  wrappers/           # placeholder dirs for Phase 5 & 6
+  testkit/            # polyglot layout (mirror git-testkit)
     python/
-      .gitkeep
     java/
-      .gitkeep
+    .specify/
 ```
 
 > **Local wiring (temporary):** Add `replace github.com/git-fire/git-harness => ../git-harness`
@@ -170,11 +169,11 @@ Commit: `refactor(git-harness): remove extracted internals from companion CLI`
 > Follow git-testkit's Python wrapper structure exactly. Read it before writing anything here.
 
 ### 5.1 Scaffold
-Mirror whatever structure git-testkit uses under `wrappers/python/`. This likely means:
-- A Python package under `wrappers/python/git_harness/`
+Mirror whatever structure git-testkit uses under `testkit/python/`. This likely means:
+- A Python package under `testkit/python/git_harness/`
 - Build tooling (cffi, ctypes, subprocess bridge, or whatever git-testkit uses)
 - `pyproject.toml` / `setup.py`
-- `wrappers/python/README.md`
+- `testkit/python/README.md`
 
 ### 5.2 Implement
 Expose the same surface area as the Go module — subprocess runner, safety/sanitize, repo introspection.
@@ -198,10 +197,10 @@ Commit: `feat(git-harness): Python wrapper`
 > Follow git-testkit's Java wrapper structure exactly. Read it before writing anything here.
 
 ### 6.1 Scaffold
-Mirror whatever structure git-testkit uses under `wrappers/java/`. Likely:
-- Maven or Gradle project under `wrappers/java/`
+Mirror whatever structure git-testkit uses under `testkit/java/`. Likely:
+- Maven or Gradle project under `testkit/java/`
 - `src/main/java/io/gitfire/harness/`
-- `wrappers/java/README.md`
+- `testkit/java/README.md`
 
 ### 6.2 Implement
 Expose the same surface area as the Go module.

README.md

@@ -9,6 +9,10 @@ Go library extracted from [git-fire](https://github.com/git-fire/git-fire): subp
 - **`git`** — repository scanning, status, commits, pushes, worktrees, and related helpers.
 - **`safety`** — redaction and secret-pattern scanning helpers used by git error paths.
 
+## Polyglot wrappers
+
+Python and Java clients use the same layout as [git-testkit](https://github.com/git-fire/git-testkit) under **`testkit/`**: build `cmd/git-harness-cli`, set **`GIT_HARNESS_CLI`** to that binary (or rely on `go run ./cmd/git-harness-cli` from the repo root). Code lives in `testkit/python` and `testkit/java`; runnable samples are `testkit/python/samples/` and the Java `Sample*Smoke` tests.
+
 ## Requirements
 
 - Go **1.24**+ (see `go.mod`).