patchground 0.1.0__tar.gz

patchground-0.1.0/.githooks/pre-commit

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Blocks commits that contain secrets or personal data. Fails closed.
+# Enable once per clone: git config core.hooksPath .githooks
+set -euo pipefail
+
+fail() { echo "pre-commit: BLOCKED — $*" >&2; exit 1; }
+
+command -v gitleaks >/dev/null 2>&1 \
+  || fail "gitleaks is not installed (brew install gitleaks). Refusing to commit unscanned."
+
+# 1. Commit identity must not expose a personal email.
+email="$(git config user.email || true)"
+[[ "$email" == *@users.noreply.github.com ]] \
+  || fail "user.email is '$email'. Use your GitHub noreply address for this repo."
+
+# 2. Secret scan of the staged changes.
+gitleaks git --config .gitleaks.toml --pre-commit --staged --redact --no-banner -v \
+  || fail "gitleaks found a possible secret in staged changes."
+
+# 3. Forbidden file types, even if .gitignore was bypassed with -f.
+forbidden='(^|/)(\.env(\..*)?|.*\.(pem|key|p12|pfx|keystore|jks|gpg)|id_(rsa|ed25519|ecdsa).*|\.netrc|\.pypirc|\.npmrc|\.mcp\.json|credentials.*\.json|service-account.*\.json)$'
+bad="$(git diff --cached --name-only --diff-filter=ACMR | grep -E "$forbidden" | grep -v '\.env\.example$' || true)"
+[[ -z "$bad" ]] || fail "sensitive file(s) staged: $bad"
+
+# 4. Personal strings kept OUTSIDE the repo (never committed), one per line.
+#    File: .git/info/forbidden-strings
+list="$(git rev-parse --git-dir)/info/forbidden-strings"
+if [[ -s "$list" ]]; then
+  while IFS= read -r s; do
+    [[ -z "$s" || "$s" == \#* ]] && continue
+    if git diff --cached -U0 | grep -E '^\+' | grep -qiF -- "$s"; then
+      fail "staged changes contain a string from .git/info/forbidden-strings."
+    fi
+  done < "$list"
+fi

patchground-0.1.0/.githooks/pre-push

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Last local gate before anything leaves the machine. Fails closed.
+set -euo pipefail
+
+fail() { echo "pre-push: BLOCKED — $*" >&2; exit 1; }
+
+command -v gitleaks >/dev/null 2>&1 \
+  || fail "gitleaks is not installed (brew install gitleaks). Refusing to push unscanned."
+
+zero=0000000000000000000000000000000000000000
+while read -r _local_ref local_sha _remote_ref remote_sha; do
+  [[ "$local_sha" == "$zero" ]] && continue
+  if [[ "$remote_sha" == "$zero" ]]; then range="$local_sha"; else range="$remote_sha..$local_sha"; fi
+
+  # Every pushed commit must use a noreply identity.
+  leaked="$(git log --format='%ae%n%ce' "$range" | sort -u | grep -v '@users.noreply.github.com$' || true)"
+  [[ -z "$leaked" ]] || fail "commits in $range use a non-noreply email. Rewrite them before pushing."
+
+  # Secret scan of every pushed commit.
+  gitleaks git --config .gitleaks.toml --log-opts="$range" --redact --no-banner -v \
+    || fail "gitleaks found a possible secret in $range."
+done

patchground-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to Patchground
+
+Thanks for helping. There are two ways to contribute.
+
+## Improve the CLI
+
+```sh
+git clone https://github.com/franndeli/patchground && cd patchground
+uv sync
+git config core.hooksPath .githooks          # needs gitleaks: brew install gitleaks
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv run pytest                                 # Docker tests are skipped without an engine
+```
+
+- Read the `SPEC.md` of the module you change and the contracts in `docs/contracts/` it implements.
+  A change that alters a boundary or contract updates the owning spec in the same pull request.
+- Challenge commands only ever run in containers. Never print hidden checks or copy `solution/` into
+  a workspace.
+- Use obviously fake values in tests (`sk-test-not-a-real-key`). Never commit secrets or personal
+  data.
+- Keep pull requests small, with tests for new behaviour.
+
+## Write a challenge
+
+See [docs/contributing.md](../docs/contributing.md) and the
+[authoring guide](../docs/authoring.md). `pgnd new` creates a runnable starter, and `pgnd validate`
+proves it in Docker.
+
+## Report a problem
+
+Open an issue using one of the templates. For security problems, follow [SECURITY.md](SECURITY.md)
+instead of opening a public issue.

patchground-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Something in the CLI did not behave as documented.
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: Include the command you ran and its output. Remove any secrets or personal paths.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `pgnd --version`
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Environment
+      description: Output of `pgnd doctor`, plus your OS.

patchground-0.1.0/.github/ISSUE_TEMPLATE/challenge_feedback.yml

@@ -0,0 +1,18 @@
+name: Challenge feedback
+description: A ticket was unclear, a check seemed wrong or the difficulty felt off.
+labels: [challenge]
+body:
+  - type: input
+    id: challenge
+    attributes:
+      label: Challenge ID
+      placeholder: pagination-last-page
+    validations:
+      required: true
+  - type: textarea
+    id: feedback
+    attributes:
+      label: What happened?
+      description: Please don't paste hidden test sources or the reference solution.
+    validations:
+      required: true

patchground-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions and ideas
+    url: https://github.com/franndeli/patchground/discussions
+    about: Ask a question or share an idea for a challenge.
+  - name: Report a security vulnerability
+    url: https://github.com/franndeli/patchground/security/advisories/new
+    about: Please report security issues privately.

patchground-0.1.0/.github/SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+Patchground builds and runs challenge code in Docker. Weaknesses in that boundary matter to us.
+Examples include escaping the sandbox, reaching the network during checks, running pack content
+without consent, leaking hidden checks or reference solutions, and modifying a learner's Git state.
+
+## Reporting a vulnerability
+
+Please report privately through
+[GitHub private vulnerability reporting](https://github.com/franndeli/patchground/security/advisories/new).
+Do not open a public issue. Include the Patchground version (`pgnd --version`), your platform and
+container engine, and the smallest reproduction you can share.
+
+We aim to acknowledge reports within a week. Please allow us to release a fix before you disclose
+the issue publicly.
+
+## Supported versions
+
+Patchground is pre-1.0. Only the latest release receives security fixes.

patchground-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What changes and why. Link the issue: Closes #NNN -->
+
+## Checklist
+
+- [ ] `uv run ruff check . && uv run ruff format --check . && uv run mypy`
+- [ ] `uv run pytest` (and `-m docker` if the sandbox, sessions or verify changed)
+- [ ] The owning `SPEC.md` or contract is updated if a boundary or contract changed
+- [ ] No secrets, personal data or hidden-check content

patchground-0.1.0/.github/workflows/action-smoke.yml

@@ -0,0 +1,68 @@
+name: validation-action-smoke
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  action:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - name: Record checkout Git state
+        env:
+          SNAPSHOT: ${{ runner.temp }}/patchground-git-before.json
+        shell: bash
+        run: |
+          python3 -I - <<'PY'
+          import hashlib
+          import json
+          import os
+          from pathlib import Path
+          state = {
+              p.as_posix(): hashlib.sha256(p.read_bytes()).hexdigest()
+              for p in Path('.git').rglob('*') if p.is_file()
+          }
+          Path(os.environ['SNAPSHOT']).write_text(json.dumps(state))
+          PY
+      - name: Exercise the reusable Action
+        id: validate
+        uses: ./
+        with:
+          challenge-directory: examples
+          # An unavailable base deliberately exercises the conservative validate-all fallback.
+          base-commit: "0000000000000000000000000000000000000000"
+          allow-execution: "true"
+      - name: Check the report and unchanged Git metadata
+        if: always()
+        env:
+          REPORT: ${{ steps.validate.outputs.report-file }}
+          SNAPSHOT: ${{ runner.temp }}/patchground-git-before.json
+        shell: bash
+        run: |
+          python3 -I - <<'PY'
+          import hashlib
+          import json
+          import os
+          from pathlib import Path
+          report = json.loads(Path(os.environ['REPORT']).read_text())
+          print(json.dumps(report, ensure_ascii=True))
+          assert report['exit_code'] == 0
+          assert report['commit'] == os.environ['GITHUB_SHA']
+          expected = {p.name for p in Path('examples').iterdir() if (p / 'challenge.yaml').is_file()}
+          assert {Path(name).name for name in report['selected']} == expected, expected
+          assert report['selection_mode'] == 'fallback_all'
+          after = {
+              p.as_posix(): hashlib.sha256(p.read_bytes()).hexdigest()
+              for p in Path('.git').rglob('*') if p.is_file()
+          }
+          assert after == json.loads(Path(os.environ['SNAPSHOT']).read_text()), 'Git metadata changed'
+          PY

patchground-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: lint, types, unit tests, schema
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest -m "not docker"
+      - name: exported schema is up to date
+        run: |
+          uv run python -m patchground.spec.schema schema
+          test -z "$(git status --porcelain -- schema/)" || { git status --porcelain -- schema/; echo "schema/ is stale: run 'uv run python -m patchground.spec.schema schema'"; exit 1; }
+
+  docker:
+    name: docker integration, validate examples
+    runs-on: ubuntu-latest
+    env:
+      PATCHGROUND_REQUIRE_DOCKER: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run pytest -m docker
+      - name: every example passes pgnd validate
+        run: |
+          set -e
+          for dir in examples/*/; do
+            echo "::group::validate $dir"
+            uv run pgnd validate "$dir"
+            echo "::endgroup::"
+          done

patchground-0.1.0/.github/workflows/oom-stress.yml

@@ -0,0 +1,46 @@
+name: oom-stress
+
+# Manually triggered, bounded repeat of the Docker memory-limit check on fresh GitHub runners.
+# Diagnostic only: it never changes classification semantics or publishes anything.
+on:
+  workflow_dispatch:
+    inputs:
+      repeats:
+        description: "Repeats per runner (1-20)"
+        default: "10"
+
+permissions:
+  contents: read
+
+jobs:
+  memory-limit:
+    name: memory limit repeat ${{ matrix.shard }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+    env:
+      PATCHGROUND_REQUIRE_DOCKER: "1"
+      REPEATS: ${{ inputs.repeats }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - name: repeat the strict memory-limit test
+        run: |
+          set -eu
+          case "$REPEATS" in ''|*[!0-9]*) echo "repeats must be a number"; exit 2;; esac
+          [ "$REPEATS" -ge 1 ] && [ "$REPEATS" -le 20 ] || { echo "repeats must be 1-20"; exit 2; }
+          failures=0
+          for i in $(seq "$REPEATS"); do
+            if ! uv run pytest -q --tb=short -p no:cacheprovider \
+                "tests/integration/test_sandbox_docker.py::test_command_timeout_and_memory_limits"; then
+              failures=$((failures + 1))
+            fi
+          done
+          echo "shard ${{ matrix.shard }}: $failures of $REPEATS repeats failed"
+          [ "$failures" -eq 0 ]

patchground-0.1.0/.github/workflows/registry.yml

@@ -0,0 +1,96 @@
+name: registry
+
+# Discovers community packs (GitHub topic `patchground-pack` + registry/sources.yaml), re-validates
+# every challenge with Patchground's own validator in Docker, and publishes registry/index.json and
+# registry/status.json. See registry/SPEC.md.
+#
+# Two jobs on purpose: `validate` builds and runs untrusted Dockerfiles, so it gets a read-only
+# token and no secrets; `publish` has write access but only commits files produced by `validate`.
+
+on:
+  schedule:
+    - cron: "17 */6 * * *"
+  workflow_dispatch:
+    inputs:
+      source:
+        description: "Process exactly one public https git URL (skips discovery)"
+        required: false
+        default: ""
+
+concurrency:
+  group: registry
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: discover and validate packs (untrusted content, read-only)
+    runs-on: ubuntu-latest
+    timeout-minutes: 300
+    env:
+      PATCHGROUND_REQUIRE_DOCKER: "1"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false   # untrusted packs build here; leave no token in .git/config
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - name: install gitleaks for the pack secret scan
+        run: |
+          curl -sSfL -o gitleaks.tar.gz https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  gitleaks.tar.gz" | sha256sum -c -
+          tar xzf gitleaks.tar.gz gitleaks
+          sudo mv gitleaks /usr/local/bin/gitleaks
+          rm gitleaks.tar.gz
+      - name: crawl
+        env:
+          GITHUB_TOKEN: ${{ github.token }}   # read-only; search rate limit only; never passed to pack tools
+          SOURCE: ${{ inputs.source }}        # via env, never interpolated into the script
+        run: |
+          if [ -n "$SOURCE" ]; then
+            case "$SOURCE" in https://*) ;; *) echo "source must be an https URL"; exit 2;; esac
+            uv run python registry/crawl.py --source "$SOURCE"
+          else
+            uv run python registry/crawl.py
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: registry
+          path: |
+            registry/index.json
+            registry/status.json
+          retention-days: 7
+
+  publish:
+    name: commit index and status if changed
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: registry
+          path: registry
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - name: regenerate the site catalog from the new index
+        run: npm --prefix web run catalog && npm --prefix web test
+      - name: commit
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add registry/index.json registry/status.json web/public
+          if git diff --cached --quiet; then
+            echo "registry unchanged"
+            exit 0
+          fi
+          packs="$(python3 -c "import json;print(len(json.load(open('registry/index.json'))['packs']))")"
+          git commit -m "Update community pack registry (${packs} verified packs)"
+          git push

patchground-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: release
+
+# Publishes a version tag (vX.Y.Z) as a GitHub release and a PyPI package.
+# Nothing here runs on ordinary pushes. Both publishing jobs use protected environments
+# (`release`, `pypi`) that must require a maintainer's approval; see docs/publishing.md.
+# PyPI uses trusted publishing (OIDC): no API token is stored anywhere.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          python-version: "3.12"
+      - name: tag matches the package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          version="$(uv run --no-project python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          [ "$TAG" = "v$version" ] || { echo "tag $TAG does not match pyproject version $version"; exit 1; }
+      - run: uv sync --locked
+      - run: uv run pytest -q -m "not docker"
+      - run: uv build --out-dir dist
+      - name: installed wheel runs, without AI SDKs
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          uv venv --python 3.12 /tmp/verify
+          uv pip install --python /tmp/verify/bin/python dist/*.whl
+          /tmp/verify/bin/pgnd --version | grep -F "${TAG#v}"
+          (cd /tmp && /tmp/verify/bin/pgnd list --builtin --json) | grep -F '"pagination-last-page"'
+          ! /tmp/verify/bin/python -c "import anthropic" 2>/dev/null
+          ! /tmp/verify/bin/python -c "import litellm" 2>/dev/null
+      - name: checksums
+        run: (cd dist && sha256sum -- * > ../SHA256SUMS) && cat SHA256SUMS
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: |
+            dist/
+            SHA256SUMS
+          retention-days: 30
+
+  github-release:
+    name: GitHub release (approval required)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+      - name: create the release from the CHANGELOG section
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          awk -v v="${TAG#v}" '$0 ~ "^## \\[?"v"\\]?" {on=1; next} /^## / && on {exit} on' CHANGELOG.md > notes.md
+          [ -s notes.md ] || { echo "CHANGELOG.md has no section for ${TAG#v}"; exit 1; }
+          gh release create "$TAG" dist/* SHA256SUMS --repo "$GITHUB_REPOSITORY" \
+            --title "Patchground ${TAG#v}" --notes-file notes.md --verify-tag
+
+  pypi:
+    name: PyPI (approval required)
+    needs: github-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/patchground/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          packages-dir: dist/

patchground-0.1.0/.github/workflows/secret-scan.yml

@@ -0,0 +1,25 @@
+name: secret-scan
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Scan full history with gitleaks
+        run: |
+          curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz \
+            | tar xz gitleaks
+          ./gitleaks git . --config .gitleaks.toml --redact --no-banner -v
+      - name: Reject non-noreply commit emails
+        run: |
+          bad="$(git log --format='%ae%n%ce' | sort -u | grep -v '@users.noreply.github.com$' | grep -v '^noreply@github.com$' || true)"
+          if [ -n "$bad" ]; then echo "Commits with non-noreply emails found"; exit 1; fi

patchground-0.1.0/.github/workflows/web.yml

@@ -0,0 +1,26 @@
+name: web
+
+on:
+  push:
+    branches: [main]
+    paths: ["web/**", "examples/*/challenge.yaml", "registry/*.json", ".github/workflows/web.yml"]
+  pull_request:
+    paths: ["web/**", "examples/*/challenge.yaml", "registry/*.json", ".github/workflows/web.yml"]
+
+permissions:
+  contents: read
+
+jobs:
+  static-site:
+    name: public site checks and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - run: npm --prefix web run check
+      - name: catalog is generated from examples/*/challenge.yaml and up to date
+        run: node web/scripts/catalog.mjs --check
+      - run: npm --prefix web test
+      - run: npm --prefix web run build

patchground-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# --- Secrets and credentials: never commit ---
+.pi
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+*.jks
+id_rsa*
+id_ed25519*
+id_ecdsa*
+*.gpg
+.netrc
+.npmrc
+.pypirc
+credentials*.json
+service-account*.json
+secrets.*
+*.secret
+.mcp.json
+.claude/settings.local.json
+
+# --- Local Patchground state (may hold AI payloads, transcripts, config) ---
+.patchground/
+/sessions/
+*.transcript.*
+.session/
+
+# --- Agent / tool working state ---
+.thinkrail/
+.cursor/
+.aider*
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+site/
+
+# --- OS / editors ---
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# --- pgnd validate output: CI re-validates every push; local image ids don't travel ---
+examples/**/verification.json
+tests/fixtures/**/verification.json
+.wrangler/