patchground 0.1.0__py3-none-any.whl

patchground/__init__.py

@@ -0,0 +1,10 @@
+"""Patchground: real code, real problems, your tools."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("patchground")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

patchground/__main__.py

@@ -0,0 +1,3 @@
+from patchground.cli.app import main
+
+main()

patchground/authoring/__init__.py

@@ -0,0 +1,5 @@
+"""Safe local challenge scaffolding; never builds or runs authored code."""
+
+from patchground.authoring.create import AuthoringError, CreatedChallenge, create_challenge
+
+__all__ = ["AuthoringError", "CreatedChallenge", "create_challenge"]

patchground/authoring/create.py

@@ -0,0 +1,179 @@
+"""Create a runnable challenge from bundled, non-executable template resources."""
+
+from __future__ import annotations
+
+import os
+import re
+from contextlib import ExitStack, suppress
+from importlib.resources import files
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from patchground import runner_assets
+from patchground.spec import ManifestError, load_challenge
+from patchground.spec.models import SLUG_PATTERN
+
+TEMPLATE_FILES = (
+    "challenge.yaml",
+    "TICKET.md",
+    "workspace/pyproject.toml",
+    "workspace/src/starter.py",
+    "checks/visible/tests/test_starter.py",
+    "checks/hidden/tests/test_starter_hidden.py",
+    "environment/Dockerfile",
+    "solution/reference.patch",
+)
+
+
+_TYPESCRIPT_FILES = (
+    "challenge.yaml",
+    "TICKET.md",
+    "workspace/package.json",
+    "workspace/src/starter.ts",
+    "checks/visible/tests/starter.test.ts",
+    "checks/hidden/tests/starter-hidden.test.ts",
+    "solution/reference.patch",
+)
+# (type, language) -> bundled template folder and its template-backed relative files. TypeScript
+# starters additionally receive the canonical runner environment from `runner_assets`.
+_STARTERS = {
+    ("debug", "python"): ("python-debug", TEMPLATE_FILES),
+    ("feature", "python"): ("python-feature", TEMPLATE_FILES),
+    ("debug", "typescript"): ("typescript-debug", _TYPESCRIPT_FILES),
+    ("feature", "typescript"): ("typescript-feature", _TYPESCRIPT_FILES),
+}
+
+
+class AuthoringError(Exception):
+    """Invalid scaffold input, an occupied destination or unavailable local storage."""
+
+
+class CreatedChallenge(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    path: Path
+    type: Literal["debug", "feature"] = "debug"
+    language: Literal["python", "typescript"] = "python"
+    files: tuple[str, ...] = TEMPLATE_FILES
+
+
+def _identity(parent: int, name: str) -> tuple[int, int]:
+    info = os.stat(name, dir_fd=parent, follow_symlinks=False)
+    return info.st_dev, info.st_ino
+
+
+def _runner_environment() -> dict[str, bytes]:
+    """Canonical TypeScript environment files, verbatim and keyed by path under environment/."""
+    try:
+        assets = runner_assets.vitest_assets()
+    except Exception as exc:
+        raise AuthoringError("TypeScript runner assets are unavailable") from exc
+    if "Dockerfile" not in assets:
+        raise AuthoringError("TypeScript runner assets are incomplete")
+    names = set(assets)
+    for name, content in assets.items():
+        path = PurePosixPath(name)
+        if (
+            not isinstance(content, bytes)
+            or path.is_absolute()
+            or str(path) != name
+            or ".." in path.parts
+            or "\\" in name
+            or any(str(parent) in names for parent in path.parents)
+        ):
+            raise AuthoringError("TypeScript runner assets are invalid")
+    return {f"environment/{name}": content for name, content in assets.items()}
+
+
+def create_challenge(
+    challenge_id: str, *, type_: str = "debug", language: str = "python"
+) -> CreatedChallenge:
+    """Reserve cwd/id exclusively; never overwrite, run a challenge or initialize Git."""
+    if re.fullmatch(SLUG_PATTERN, challenge_id) is None:
+        raise AuthoringError("id must use lowercase letters, digits and single hyphens")
+    if (type_, language) not in _STARTERS:
+        raise AuthoringError("supported templates: --type debug|feature --lang python|typescript")
+    folder, names = _STARTERS[(type_, language)]
+    template = files("patchground.authoring").joinpath("templates", folder)
+    contents = {
+        name: template.joinpath(name + ".tmpl")
+        .read_bytes()
+        .replace(b"__CHALLENGE_ID__", challenge_id.encode("ascii"))
+        for name in names
+    }
+    if language == "typescript":
+        contents.update(_runner_environment())
+    created: list[tuple[int, str, tuple[int, int], bool]] = []
+    with ExitStack() as handles:
+        try:
+            parent = os.open(".", os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+            handles.callback(os.close, parent)
+            try:
+                os.mkdir(challenge_id, mode=0o700, dir_fd=parent)
+            except FileExistsError as exc:
+                raise AuthoringError(
+                    "destination already exists; choose a new challenge id"
+                ) from exc
+            root_identity = _identity(parent, challenge_id)
+            created.append((parent, challenge_id, root_identity, True))
+            root = os.open(
+                challenge_id, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent
+            )
+            handles.callback(os.close, root)
+            directories: dict[tuple[str, ...], int] = {(): root}
+            for relative, content in contents.items():
+                parts = Path(relative).parts
+                for length in range(1, len(parts)):
+                    key = parts[:length]
+                    if key in directories:
+                        continue
+                    directory = directories[key[:-1]]
+                    os.mkdir(key[-1], mode=0o700, dir_fd=directory)
+                    created.append((directory, key[-1], _identity(directory, key[-1]), True))
+                    descriptor = os.open(
+                        key[-1], os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=directory
+                    )
+                    handles.callback(os.close, descriptor)
+                    directories[key] = descriptor
+                directory = directories[parts[:-1]]
+                descriptor = os.open(
+                    parts[-1],
+                    os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                    0o600,
+                    dir_fd=directory,
+                )
+                with os.fdopen(descriptor, "wb") as stream:
+                    info = os.fstat(stream.fileno())
+                    created.append((directory, parts[-1], (info.st_dev, info.st_ino), False))
+                    stream.write(content)
+                    stream.flush()
+                    os.fsync(stream.fileno())
+            for directory, name, identity, _is_directory in created:
+                if _identity(directory, name) != identity:
+                    raise AuthoringError("scaffold destination changed during creation")
+            load_challenge(Path(challenge_id))
+        except BaseException as exc:
+            for directory, name, identity, is_directory in reversed(created):
+                with suppress(OSError):
+                    if _identity(directory, name) == identity:
+                        if is_directory:
+                            os.rmdir(name, dir_fd=directory)
+                        else:
+                            os.unlink(name, dir_fd=directory)
+            if isinstance(exc, OSError | ManifestError):
+                raise AuthoringError(
+                    "could not create the scaffold; check disk space and directory access"
+                ) from exc
+            raise
+    return CreatedChallenge.model_validate(
+        {
+            "id": challenge_id,
+            "path": Path(challenge_id),
+            "type": type_,
+            "language": language,
+            "files": tuple(contents),
+        }
+    )

patchground/authoring/templates/python-debug/TICKET.md.tmpl

@@ -0,0 +1,11 @@
+# Line-item totals are sometimes too small
+
+The total displayed for a list of integer amounts is sometimes smaller than expected.
+An empty list should total zero, and every supplied amount should contribute exactly once.
+
+Investigate `total` in `src/starter.py`. Keep its public API and add a regression test.
+Run `pgnd check` from a session workspace to verify the fix in Docker.
+
+This is a tiny teaching starter for challenge authors, not a curated realistic exercise.
+Authors should replace its story, application, tests and reference together, then run
+`pgnd validate` before sharing it.

patchground/authoring/templates/python-debug/challenge.yaml.tmpl

@@ -0,0 +1,21 @@
+spec_version: "0.1"
+id: __CHALLENGE_ID__
+version: 0.1.0
+title: The last line item is missing from the total
+type: debug
+summary: Investigate incorrect totals without changing the public API.
+languages: [python]
+tags: [starter]
+difficulty: beginner
+timebox_minutes: 15
+ai_policy: allowed
+environment:
+  dockerfile: environment/Dockerfile
+  services: []
+  test_command: pytest -q -p no:cacheprovider --junitxml=$PG_RESULTS/junit.xml
+checks:
+  visible: checks/visible
+  hidden: checks/hidden
+solution: solution/reference.patch
+author: {name: Challenge author}
+content_license: CC-BY-4.0

patchground/authoring/templates/python-debug/checks/hidden/tests/test_starter_hidden.py.tmpl

@@ -0,0 +1,13 @@
+from starter import total
+
+
+def test_final_amount_contributes():
+    assert total([3, 2]) == 5
+
+
+def test_single_amount():
+    assert total([7]) == 7
+
+
+def test_negative_amounts():
+    assert total([4, -2]) == 2

patchground/authoring/templates/python-debug/checks/visible/tests/test_starter.py.tmpl

@@ -0,0 +1,9 @@
+from starter import total
+
+
+def test_empty_total():
+    assert total([]) == 0
+
+
+def test_zero_final_amount():
+    assert total([4, 5, 0]) == 9

patchground/authoring/templates/python-debug/environment/Dockerfile.tmpl

@@ -0,0 +1,3 @@
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1
+RUN pip install --no-cache-dir pytest==8.3.5

patchground/authoring/templates/python-debug/solution/reference.patch.tmpl

@@ -0,0 +1,8 @@
+diff --git a/src/starter.py b/src/starter.py
+--- a/src/starter.py
++++ b/src/starter.py
+@@ -1,3 +1,3 @@
+ def total(items: list[int]) -> int:
+     """Return the sum of the supplied integer amounts."""
+-    return sum(items[:-1])
++    return sum(items)

patchground/authoring/templates/python-debug/workspace/pyproject.toml.tmpl

@@ -0,0 +1,8 @@
+[project]
+name = "patchground-starter"
+version = "0.1.0"
+requires-python = ">=3.12"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

patchground/authoring/templates/python-debug/workspace/src/starter.py.tmpl

@@ -0,0 +1,3 @@
+def total(items: list[int]) -> int:
+    """Return the sum of the supplied integer amounts."""
+    return sum(items[:-1])

patchground/authoring/templates/python-feature/TICKET.md.tmpl

@@ -0,0 +1,13 @@
+# Add an average of the line-item amounts
+
+Reports need the mean of a list of integer amounts. Implement `average` in `src/starter.py`:
+
+- `average(items)` returns the arithmetic mean of the amounts as a `float`.
+- An empty list averages `0.0` instead of raising an error.
+- `total` and the public signatures stay as they are.
+
+Add tests for your implementation. Run `pgnd check` from a session workspace to verify it in Docker.
+
+This is a tiny teaching starter for challenge authors, not a curated realistic exercise.
+Authors should replace its story, application, tests and reference together, then run
+`pgnd validate` before sharing it.

patchground/authoring/templates/python-feature/challenge.yaml.tmpl

@@ -0,0 +1,22 @@
+spec_version: "0.1"
+id: __CHALLENGE_ID__
+version: 0.1.0
+title: Add an average to the line-item helpers
+type: feature
+summary: Add the missing average helper without changing the existing total.
+languages: [python]
+tags: [starter]
+difficulty: beginner
+timebox_minutes: 15
+ai_policy: allowed
+environment:
+  dockerfile: environment/Dockerfile
+  services: []
+  test_command: pytest -q -p no:cacheprovider --junitxml=$PG_RESULTS/junit.xml
+checks:
+  visible: checks/visible
+  hidden: checks/hidden
+solution: solution/reference.patch
+expected_paths: [src/, tests/]
+author: {name: Challenge author}
+content_license: CC-BY-4.0

patchground/authoring/templates/python-feature/checks/hidden/tests/test_starter_hidden.py.tmpl

@@ -0,0 +1,13 @@
+from starter import average
+
+
+def test_average_of_amounts():
+    assert average([2, 4]) == 3.0
+
+
+def test_average_of_one_amount():
+    assert average([7]) == 7.0
+
+
+def test_average_of_empty_list_is_zero():
+    assert average([]) == 0.0

patchground/authoring/templates/python-feature/checks/visible/tests/test_starter.py.tmpl

@@ -0,0 +1,9 @@
+from starter import average, total
+
+
+def test_total_of_amounts():
+    assert total([4, 5, 0]) == 9
+
+
+def test_average_is_exported():
+    assert callable(average)

patchground/authoring/templates/python-feature/environment/Dockerfile.tmpl

@@ -0,0 +1,3 @@
+FROM python:3.12-slim
+ENV PYTHONDONTWRITEBYTECODE=1
+RUN pip install --no-cache-dir pytest==8.3.5

patchground/authoring/templates/python-feature/solution/reference.patch.tmpl

@@ -0,0 +1,9 @@
+diff --git a/src/starter.py b/src/starter.py
+--- a/src/starter.py
++++ b/src/starter.py
+@@ -4,4 +4,4 @@
+
+ def average(items: list[int]) -> float:
+     """Return the mean of the amounts, or 0.0 for an empty list."""
+-    raise NotImplementedError
++    return sum(items) / len(items) if items else 0.0

patchground/authoring/templates/python-feature/workspace/pyproject.toml.tmpl

@@ -0,0 +1,8 @@
+[project]
+name = "patchground-starter"
+version = "0.1.0"
+requires-python = ">=3.12"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

patchground/authoring/templates/python-feature/workspace/src/starter.py.tmpl

@@ -0,0 +1,8 @@
+def total(items: list[int]) -> int:
+    """Return the sum of the supplied integer amounts."""
+    return sum(items)
+
+
+def average(items: list[int]) -> float:
+    """Return the mean of the amounts, or 0.0 for an empty list."""
+    raise NotImplementedError

patchground/authoring/templates/typescript-debug/TICKET.md.tmpl

@@ -0,0 +1,11 @@
+# Line-item totals are sometimes too small
+
+The total displayed for a list of integer amounts is sometimes smaller than expected.
+An empty list should total zero, and every supplied amount should contribute exactly once.
+
+Investigate `total` in `src/starter.ts`. Keep its public API and add a regression test.
+Run `pgnd check` from a session workspace to verify the fix in Docker.
+
+This is a tiny teaching starter for challenge authors, not a curated realistic exercise.
+Authors should replace its story, application, tests and reference together, then run
+`pgnd validate` before sharing it.

patchground/authoring/templates/typescript-debug/challenge.yaml.tmpl

@@ -0,0 +1,21 @@
+spec_version: "0.1"
+id: __CHALLENGE_ID__
+version: 0.1.0
+title: The last line item is missing from the total
+type: debug
+summary: Investigate incorrect totals without changing the public API.
+languages: [typescript]
+tags: [starter]
+difficulty: beginner
+timebox_minutes: 15
+ai_policy: allowed
+environment:
+  dockerfile: environment/Dockerfile
+  services: []
+  test_command: node /opt/patchground/vitest-runner.mjs
+checks:
+  visible: checks/visible
+  hidden: checks/hidden
+solution: solution/reference.patch
+author: {name: Challenge author}
+content_license: CC-BY-4.0

patchground/authoring/templates/typescript-debug/checks/hidden/tests/starter-hidden.test.ts.tmpl

@@ -0,0 +1,14 @@
+import { expect, test } from "vitest";
+import { total } from "../src/starter";
+
+test("total includes the final amount", () => {
+  expect(total([3, 2])).toBe(5);
+});
+
+test("total of a single amount", () => {
+  expect(total([7])).toBe(7);
+});
+
+test("total handles negative amounts", () => {
+  expect(total([4, -2])).toBe(2);
+});

patchground/authoring/templates/typescript-debug/checks/visible/tests/starter.test.ts.tmpl

@@ -0,0 +1,10 @@
+import { expect, test } from "vitest";
+import { total } from "../src/starter";
+
+test("total of an empty list is zero", () => {
+  expect(total([])).toBe(0);
+});
+
+test("total ignores a zero final amount", () => {
+  expect(total([4, 5, 0])).toBe(9);
+});

patchground/authoring/templates/typescript-debug/solution/reference.patch.tmpl

@@ -0,0 +1,9 @@
+diff --git a/src/starter.ts b/src/starter.ts
+--- a/src/starter.ts
++++ b/src/starter.ts
+@@ -1,4 +1,4 @@
+ /** Return the sum of the supplied integer amounts. */
+ export function total(items: number[]): number {
+-  return items.slice(0, -1).reduce((sum, amount) => sum + amount, 0);
++  return items.reduce((sum, amount) => sum + amount, 0);
+ }

patchground/authoring/templates/typescript-debug/workspace/package.json.tmpl

@@ -0,0 +1,6 @@
+{
+  "name": "patchground-starter",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module"
+}

patchground/authoring/templates/typescript-debug/workspace/src/starter.ts.tmpl

@@ -0,0 +1,4 @@
+/** Return the sum of the supplied integer amounts. */
+export function total(items: number[]): number {
+  return items.slice(0, -1).reduce((sum, amount) => sum + amount, 0);
+}

patchground/authoring/templates/typescript-feature/TICKET.md.tmpl

@@ -0,0 +1,13 @@
+# Add an average of the line-item amounts
+
+Reports need the mean of a list of integer amounts. Implement `average` in `src/starter.ts`:
+
+- `average(items)` returns the arithmetic mean of the amounts as a `float`.
+- An empty list averages `0.0` instead of raising an error.
+- `total` and the public signatures stay as they are.
+
+Add tests for your implementation. Run `pgnd check` from a session workspace to verify it in Docker.
+
+This is a tiny teaching starter for challenge authors, not a curated realistic exercise.
+Authors should replace its story, application, tests and reference together, then run
+`pgnd validate` before sharing it.

patchground/authoring/templates/typescript-feature/challenge.yaml.tmpl

@@ -0,0 +1,22 @@
+spec_version: "0.1"
+id: __CHALLENGE_ID__
+version: 0.1.0
+title: Add an average to the line-item helpers
+type: feature
+summary: Add the missing average helper without changing the existing total.
+languages: [typescript]
+tags: [starter]
+difficulty: beginner
+timebox_minutes: 15
+ai_policy: allowed
+environment:
+  dockerfile: environment/Dockerfile
+  services: []
+  test_command: node /opt/patchground/vitest-runner.mjs
+checks:
+  visible: checks/visible
+  hidden: checks/hidden
+solution: solution/reference.patch
+expected_paths: [src/, tests/]
+author: {name: Challenge author}
+content_license: CC-BY-4.0

patchground/authoring/templates/typescript-feature/checks/hidden/tests/starter-hidden.test.ts.tmpl

@@ -0,0 +1,14 @@
+import { expect, test } from "vitest";
+import { average } from "../src/starter";
+
+test("average of the amounts", () => {
+  expect(average([2, 4])).toBe(3);
+});
+
+test("average of one amount", () => {
+  expect(average([7])).toBe(7);
+});
+
+test("average of an empty list is zero", () => {
+  expect(average([])).toBe(0);
+});

patchground/authoring/templates/typescript-feature/checks/visible/tests/starter.test.ts.tmpl

@@ -0,0 +1,10 @@
+import { expect, test } from "vitest";
+import { average, total } from "../src/starter";
+
+test("total of the amounts", () => {
+  expect(total([4, 5, 0])).toBe(9);
+});
+
+test("average is exported", () => {
+  expect(typeof average).toBe("function");
+});

patchground/authoring/templates/typescript-feature/solution/reference.patch.tmpl

@@ -0,0 +1,10 @@
+diff --git a/src/starter.ts b/src/starter.ts
+--- a/src/starter.ts
++++ b/src/starter.ts
+@@ -5,5 +5,5 @@
+
+ /** Return the mean of the amounts, or 0 for an empty list. */
+ export function average(items: number[]): number {
+-  throw new Error("not implemented");
++  return items.length === 0 ? 0 : total(items) / items.length;
+ }

patchground/authoring/templates/typescript-feature/workspace/package.json.tmpl

@@ -0,0 +1,6 @@
+{
+  "name": "patchground-starter",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module"
+}

patchground/authoring/templates/typescript-feature/workspace/src/starter.ts.tmpl

@@ -0,0 +1,9 @@
+/** Return the sum of the supplied integer amounts. */
+export function total(items: number[]): number {
+  return items.reduce((sum, amount) => sum + amount, 0);
+}
+
+/** Return the mean of the amounts, or 0 for an empty list. */
+export function average(items: number[]): number {
+  throw new Error("not implemented");
+}

patchground/automation/__init__.py

@@ -0,0 +1,5 @@
+"""Committed-input validation automation; never executes checkout code on the host."""
+
+from patchground.automation.workflow import AutomationResult, validate_changes
+
+__all__ = ["AutomationResult", "validate_changes"]