codepraxis 0.1.0__tar.gz

codepraxis-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

codepraxis-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+## The content boundary
+
+This package is published to PyPI. Anything committed here becomes public.
+
+**Never commit:**
+
+- Challenge packs, questions, or reference solutions
+- Test fixtures derived from real question content
+- API keys, storage connection strings, registry credentials
+- Runner image internals (`koro`, `perry`, proctoring, evaluation logic)
+
+The CLI deliberately contains nothing proprietary: it runs the *author's* tests
+against the *author's* code. Keeping that true is what makes public
+distribution safe. If a change would put platform internals in this repo, the
+change belongs on the server instead.
+
+Test fixtures must be synthetic and written from scratch. The conformance suite
+reads a private corpus through `PRAXIS_CONFORMANCE_PACKS` and skips when unset.
+
+## Architecture
+
+Layers, innermost first. Dependencies point inward only.
+
+| Layer | Responsibility | Must not |
+|---|---|---|
+| `domain/` | Data and the mirrored runner contract | Touch the filesystem, subprocesses, or the network |
+| `packio/` | Filesystem → `Pack` | Import or execute pack code |
+| `validation/` | Static rules over a `Pack` | Execute pack code |
+| `execution/` | Run packs, produce `RunResult` | Print anything |
+| `reporting/` | Render a `RunResult` | Read the filesystem |
+| `commands/` | Orchestrate the above | Instantiate concrete executors or reporters |
+| `cli.py` | Parse args, inject dependencies | Contain logic |
+
+The load-bearing rule: **every executor returns the same `RunResult`.** Local and
+remote tiers are interchangeable, so reporting and exit codes are
+written once.
+
+### Adding things
+
+- **A lint rule** — a new file in `validation/rules/`, registered. No edits elsewhere.
+- **A backend** (`backend.conf`'s `BACKEND`) — a new `BackendAdapter` in
+  `execution/local/backends.py`, registered. Declare honestly whether the local
+  tier can run it; a backend that needs container-only infrastructure should set
+  `locally_supported = False` rather than emit false failures.
+- **An output format** — a new class satisfying `Reporter`.
+- **An execution tier** — a new class satisfying `Executor`.
+
+### Mirroring the runner
+
+`domain/contract.py` mirrors constants and semantics from the runner image and
+records provenance per constant. When you change it:
+
+1. Cite the runner source for the new behaviour.
+2. Add a conformance case that would fail under the old behaviour.
+
+Where the local tier cannot reproduce the runner, emit a
+`Severity.UNVERIFIABLE` diagnostic. Never guess — a false pass locally is worse
+than no local check at all, because it costs an author a full remote cycle to
+discover.

codepraxis-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: codepraxis
+Version: 0.1.0
+Summary: Author and validate CodePraxis challenge packs.
+Project-URL: Documentation, https://docs.codepraxis.com/authoring
+Author: CodePraxis
+License: Proprietary
+Keywords: assessment,authoring,challenge,codepraxis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff==0.16.2; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# codepraxis
+
+Author and validate CodePraxis challenge packs from your own repository.
+
+```bash
+pip install codepraxis
+codepraxis --login
+codepraxis validate --local my-challenge     # fast, advisory
+codepraxis --publish my-challenge            # validates in the runner, then publishes
+```
+
+## What this is
+
+A challenge pack is a directory — starter code, a test module, instructions.
+This CLI lets you keep packs in your own git repository, iterate on them with
+your own editor, and check them before they reach candidates.
+
+Two tiers, one result shape:
+
+| Command | Runs | Speed | Authoritative? |
+|---|---|---|---|
+| `codepraxis validate --local` | Pure-Python harness on your machine | seconds | No — advisory |
+| `codepraxis validate --remote` | The real runner image, on CodePraxis | ~1 min | **Yes — gates publish** |
+
+`--local` reproduces how the runner loads, orders and scores a pack, so it
+catches most authoring mistakes in the inner loop. It is **not** the container:
+it does not run `setup.sh` and does not have the image's package set. Anything
+it cannot check is reported as a `note` rather than silently passing.
+Publishing always requires a remote run.
+
+### Packs that call a model
+
+By default there is no model endpoint locally, so cases that need one are
+reported **unverifiable** rather than failed — a pack is not broken just because
+your laptop has no LLM proxy. Point it at a real endpoint and they run for real:
+
+```bash
+export OPENAI_API_KEY=...              # or --llm-api-key
+export OPENAI_BASE_URL=...             # or --llm-base-url
+codepraxis validate --local my-challenge
+```
+
+Once a key is configured the leniency stops: a model failure is then a real
+failure, because it can be judged.
+
+## The two fixtures
+
+Every pack is validated twice:
+
+- **solution** — `source/` overlaid with `solution/`. Must pass everything.
+- **starter** — `source/` alone. Must *fail*.
+
+The starter run is the one authors forget. A pack whose starter already passes
+has tests that do not discriminate, and every candidate will score full marks.
+
+```
+askgit  (local)
+  solution  18/18 passed
+  starter   0/18 passed
+  PASSED  8.9s
+```
+
+Three verdicts: **PASSED**, **FAILED**, and **INCONCLUSIVE** (this tier lacked
+the infrastructure to judge it — not a failure, and it does not fail the
+command). `--json` always emits a single document with a `packs` array, however
+many packs ran.
+
+## Pack layout
+
+```
+my-challenge/
+├── metadata.json            # {"name": "..."} — becomes the workspace directory
+├── backend.conf             # {"BACKEND": "AI", "LANGUAGE": "PYTHON"}
+├── setup.sh                 # optional; installs dependencies (remote only)
+├── source/                  # what the candidate starts from
+├── ._tests/test_1.py        # a `testCases` class
+└── ._course_data/
+    ├── course_toc.json      # selects the active test module
+    └── feature.md           # the Instructions tab
+solution/                    # sibling, never uploaded — the reference solution
+```
+
+## Authoring with Claude Code
+
+```bash
+codepraxis --install claude-plugin
+```
+
+Writes a local plugin into `.codepraxis/claude-plugin/`, then tells you the two
+commands to enable it. You get:
+
+- **`/codepraxis:new`** — scaffold a pack from a description
+- **`/codepraxis:validate`** — validate and fix what fails, in a loop
+- **`pack-authoring` skill** — loads automatically when Claude touches a pack,
+  so it already knows the `testCases` contract and the two-fixture rule
+
+Re-run with `--force` to overwrite an existing install.
+
+## Authentication
+
+```bash
+codepraxis --login
+```
+
+Prompts for an API key (hidden input), verifies it against the platform, and
+stores it at `~/.config/codepraxis/config.json` with `0600` permissions. It
+prints which company the key publishes as — worth reading, because that is what
+every publish is scoped to.
+
+In CI, skip the prompt:
+
+```bash
+export CODEPRAXIS_TOKEN=...
+export CODEPRAXIS_API_URL=...        # optional; defaults to the production API
+```
+
+## Publishing
+
+```bash
+codepraxis --publish my-challenge            # draft, with confirmation
+codepraxis --publish my-challenge --live     # straight to candidates
+codepraxis --publish my-challenge --yes      # non-interactive, for CI
+```
+
+Publishing is deliberately strict, because a published challenge can be
+assigned to candidates immediately:
+
+- **Remote validation runs first.** Local results never qualify. Reuse an
+  earlier passing run with `--validation-run-id` if you have one.
+- **A reference solution is required.** It is what proves the challenge is
+  solvable.
+- **It publishes as a draft** unless you pass `--live`.
+- **The company comes from your API key.** The CLI never sends a company id —
+  ownership is derived server-side, so a compromised or mistyped client can't
+  publish into someone else's catalog.
+
+You'll be shown the company and asked to confirm before anything is created.
+
+## Development
+
+```bash
+python3.11 -m pip install -e '.[dev]'
+pytest
+ruff check src tests scripts
+```
+
+The package has **no runtime dependencies**. The harness must run on an author's
+machine with nothing but a Python interpreter, so keep it that way — the remote
+tier uses `urllib` from the standard library for the same reason.
+
+### Conformance tests
+
+The harness mirrors the production runner's behaviour (`setupCodeBase.py`,
+`koro/test_loader.py`, `koro/test_runner.py`). Mirrors drift, so
+`tests/conformance/` replays the harness across a corpus of real packs and
+asserts the expected verdicts.
+
+That corpus is **private and lives outside this repository**:
+
+```bash
+PRAXIS_CONFORMANCE_PACKS=/path/to/question-bank pytest tests/conformance
+```
+
+Without the variable the conformance tests skip.
+
+> **Do not vendor packs into this repository.** This package is published
+> publicly. No challenge content, no reference solutions, no fixtures derived
+> from real questions. Scaffold templates must be written from scratch.

codepraxis-0.1.0/README.md

@@ -0,0 +1,168 @@
+# codepraxis
+
+Author and validate CodePraxis challenge packs from your own repository.
+
+```bash
+pip install codepraxis
+codepraxis --login
+codepraxis validate --local my-challenge     # fast, advisory
+codepraxis --publish my-challenge            # validates in the runner, then publishes
+```
+
+## What this is
+
+A challenge pack is a directory — starter code, a test module, instructions.
+This CLI lets you keep packs in your own git repository, iterate on them with
+your own editor, and check them before they reach candidates.
+
+Two tiers, one result shape:
+
+| Command | Runs | Speed | Authoritative? |
+|---|---|---|---|
+| `codepraxis validate --local` | Pure-Python harness on your machine | seconds | No — advisory |
+| `codepraxis validate --remote` | The real runner image, on CodePraxis | ~1 min | **Yes — gates publish** |
+
+`--local` reproduces how the runner loads, orders and scores a pack, so it
+catches most authoring mistakes in the inner loop. It is **not** the container:
+it does not run `setup.sh` and does not have the image's package set. Anything
+it cannot check is reported as a `note` rather than silently passing.
+Publishing always requires a remote run.
+
+### Packs that call a model
+
+By default there is no model endpoint locally, so cases that need one are
+reported **unverifiable** rather than failed — a pack is not broken just because
+your laptop has no LLM proxy. Point it at a real endpoint and they run for real:
+
+```bash
+export OPENAI_API_KEY=...              # or --llm-api-key
+export OPENAI_BASE_URL=...             # or --llm-base-url
+codepraxis validate --local my-challenge
+```
+
+Once a key is configured the leniency stops: a model failure is then a real
+failure, because it can be judged.
+
+## The two fixtures
+
+Every pack is validated twice:
+
+- **solution** — `source/` overlaid with `solution/`. Must pass everything.
+- **starter** — `source/` alone. Must *fail*.
+
+The starter run is the one authors forget. A pack whose starter already passes
+has tests that do not discriminate, and every candidate will score full marks.
+
+```
+askgit  (local)
+  solution  18/18 passed
+  starter   0/18 passed
+  PASSED  8.9s
+```
+
+Three verdicts: **PASSED**, **FAILED**, and **INCONCLUSIVE** (this tier lacked
+the infrastructure to judge it — not a failure, and it does not fail the
+command). `--json` always emits a single document with a `packs` array, however
+many packs ran.
+
+## Pack layout
+
+```
+my-challenge/
+├── metadata.json            # {"name": "..."} — becomes the workspace directory
+├── backend.conf             # {"BACKEND": "AI", "LANGUAGE": "PYTHON"}
+├── setup.sh                 # optional; installs dependencies (remote only)
+├── source/                  # what the candidate starts from
+├── ._tests/test_1.py        # a `testCases` class
+└── ._course_data/
+    ├── course_toc.json      # selects the active test module
+    └── feature.md           # the Instructions tab
+solution/                    # sibling, never uploaded — the reference solution
+```
+
+## Authoring with Claude Code
+
+```bash
+codepraxis --install claude-plugin
+```
+
+Writes a local plugin into `.codepraxis/claude-plugin/`, then tells you the two
+commands to enable it. You get:
+
+- **`/codepraxis:new`** — scaffold a pack from a description
+- **`/codepraxis:validate`** — validate and fix what fails, in a loop
+- **`pack-authoring` skill** — loads automatically when Claude touches a pack,
+  so it already knows the `testCases` contract and the two-fixture rule
+
+Re-run with `--force` to overwrite an existing install.
+
+## Authentication
+
+```bash
+codepraxis --login
+```
+
+Prompts for an API key (hidden input), verifies it against the platform, and
+stores it at `~/.config/codepraxis/config.json` with `0600` permissions. It
+prints which company the key publishes as — worth reading, because that is what
+every publish is scoped to.
+
+In CI, skip the prompt:
+
+```bash
+export CODEPRAXIS_TOKEN=...
+export CODEPRAXIS_API_URL=...        # optional; defaults to the production API
+```
+
+## Publishing
+
+```bash
+codepraxis --publish my-challenge            # draft, with confirmation
+codepraxis --publish my-challenge --live     # straight to candidates
+codepraxis --publish my-challenge --yes      # non-interactive, for CI
+```
+
+Publishing is deliberately strict, because a published challenge can be
+assigned to candidates immediately:
+
+- **Remote validation runs first.** Local results never qualify. Reuse an
+  earlier passing run with `--validation-run-id` if you have one.
+- **A reference solution is required.** It is what proves the challenge is
+  solvable.
+- **It publishes as a draft** unless you pass `--live`.
+- **The company comes from your API key.** The CLI never sends a company id —
+  ownership is derived server-side, so a compromised or mistyped client can't
+  publish into someone else's catalog.
+
+You'll be shown the company and asked to confirm before anything is created.
+
+## Development
+
+```bash
+python3.11 -m pip install -e '.[dev]'
+pytest
+ruff check src tests scripts
+```
+
+The package has **no runtime dependencies**. The harness must run on an author's
+machine with nothing but a Python interpreter, so keep it that way — the remote
+tier uses `urllib` from the standard library for the same reason.
+
+### Conformance tests
+
+The harness mirrors the production runner's behaviour (`setupCodeBase.py`,
+`koro/test_loader.py`, `koro/test_runner.py`). Mirrors drift, so
+`tests/conformance/` replays the harness across a corpus of real packs and
+asserts the expected verdicts.
+
+That corpus is **private and lives outside this repository**:
+
+```bash
+PRAXIS_CONFORMANCE_PACKS=/path/to/question-bank pytest tests/conformance
+```
+
+Without the variable the conformance tests skip.
+
+> **Do not vendor packs into this repository.** This package is published
+> publicly. No challenge content, no reference solutions, no fixtures derived
+> from real questions. Scaffold templates must be written from scratch.

codepraxis-0.1.0/RELEASING.md

@@ -0,0 +1,133 @@
+# Releasing
+
+`codepraxis` is published to PyPI. **A version number can never be reused** —
+even a deleted release permanently burns its version. Treat every publish as
+irreversible.
+
+## One-time setup
+
+The GitHub side is done: `codepraxis-org/codepraxis-cli` is private, and the
+`pypi` and `testpypi` environments exist. What remains can only be done from a
+browser signed in to PyPI — there is no API for creating a Trusted Publisher.
+
+### 1. TestPyPI — https://test.pypi.org
+
+Do this one first; it is the rehearsal target and mistakes there are cheap.
+
+Account settings → **Publishing** → *Add a new pending publisher*:
+
+| Field | Value |
+|---|---|
+| PyPI Project Name | `codepraxis` |
+| Owner | `codepraxis-org` |
+| Repository name | `codepraxis-cli` |
+| Workflow name | `release.yml` |
+| Environment name | `testpypi` |
+
+### 2. PyPI — https://pypi.org
+
+Same form, one field different:
+
+| Field | Value |
+|---|---|
+| PyPI Project Name | `codepraxis` |
+| Owner | `codepraxis-org` |
+| Repository name | `codepraxis-cli` |
+| Workflow name | `release.yml` |
+| Environment name | **`pypi`** |
+
+A *pending* publisher claims the name `codepraxis` and creates the project on
+first upload, so registering a placeholder release is unnecessary — but do add
+it before someone else takes the name.
+
+### 3. Enable 2FA
+
+On both accounts, for every maintainer.
+
+No API tokens are stored anywhere. Trusted Publishing exchanges a short-lived
+GitHub OIDC token for an upload credential, so there is no long-lived secret to
+leak, rotate, or print into a log.
+
+## The human gate
+
+`codepraxis-org` is on **GitHub Free**, where private repositories cannot have
+environment protection rules — required reviewers are rejected with HTTP 422.
+So the gate is structural instead:
+
+- **A tag only ever publishes to TestPyPI.** There is no path from
+  `git push --tags` to a permanent PyPI release.
+- **PyPI requires a deliberate manual dispatch**: Actions → release → *Run
+  workflow* → `target: pypi`.
+
+If the org moves to GitHub Team, add required reviewers to the `pypi`
+environment, and the `pypi` job's `if:` condition can be relaxed to allow tags
+through directly.
+
+## Cutting a release
+
+Version lives in exactly one place: `src/codepraxis/__init__.py`. Hatchling reads it
+from there, so there is nothing to keep in sync.
+
+```bash
+# 1. Bump the version
+vim src/codepraxis/__init__.py          # __version__ = "0.2.0"
+
+# 2. Verify locally, exactly as CI will
+python -m build
+python scripts/check_artifact.py dist
+python -m twine check --strict dist/*
+
+# 3. Smoke-test the built wheel in a clean environment
+python -m venv /tmp/smoke && /tmp/smoke/bin/pip install dist/*.whl
+/tmp/smoke/bin/codepraxis --version
+
+# 4. Tag — runs every gate and publishes to TestPyPI
+git tag v0.2.0 && git push origin v0.2.0
+pip install --index-url https://test.pypi.org/simple/ codepraxis==0.2.0
+
+# 5. Promote to PyPI, deliberately
+gh workflow run release.yml -f target=pypi
+```
+
+Step 5 is the only thing that writes to PyPI, and it cannot happen by accident.
+The build re-runs every gate before uploading, including a check that the tag
+matches `__version__`.
+
+## What the gates check
+
+| Gate | Catches |
+|---|---|
+| `check_artifact.py` | Challenge packs, solutions, or credentials swept into a public artifact |
+| `twine check --strict` | Metadata that renders wrong on the project page |
+| Clean-venv smoke test | A module that imports from the source tree but is missing from the wheel |
+| CI matrix | A syntax or stdlib feature newer than the `requires-python` floor |
+
+The artifact check is the important one. This package is public and the
+question bank is not; see CONTRIBUTING.md.
+
+## Versioning
+
+Semantic versioning, where the public contract is **the CLI surface and the pack
+format** — not the Python API. `codepraxis.*` modules are internal and may change in
+any release.
+
+- **patch** — bug fixes, better diagnostics
+- **minor** — new commands, new lint rules, new pack fields
+- **major** — a pack that validated before now fails, or a command changes shape
+
+Because the CLI talks to the platform, every request carries
+`X-Praxis-CLI-Version`. When the server drops support for a pack contract, it
+returns a clear upgrade error rather than failing obscurely — so shipping a
+breaking pack-format change means updating the server's minimum supported
+version in the same release.
+
+## Yanking
+
+If a release is broken, `yank` rather than delete:
+
+```bash
+# PyPI → Manage → Releases → Yank
+```
+
+Yanking hides it from new resolutions while leaving pinned installs working.
+Deleting breaks anyone who pinned it and still does not free the version.

codepraxis-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codepraxis"
+description = "Author and validate CodePraxis challenge packs."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "CodePraxis" }]
+keywords = ["codepraxis", "assessment", "challenge", "authoring"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+# The local harness is deliberately dependency-free: it must run on an author's
+# machine with nothing but a Python interpreter. Network commands (push/publish)
+# may add an HTTP client behind an extra; the harness may not.
+dependencies = []
+
+# Single source of truth: praxis.__version__. Keeping a literal here as well
+# guarantees the two drift.
+dynamic = ["version"]
+
+[project.optional-dependencies]
+# ruff is pinned exactly: its default rule set changes between releases, so a
+# floating version means lint passes locally and fails in CI (or vice versa).
+dev = ["pytest>=7", "ruff==0.16.2", "build>=1", "twine>=5"]
+
+[project.urls]
+Documentation = "https://docs.codepraxis.com/authoring"
+
+[project.scripts]
+codepraxis = "codepraxis.cli:main"
+
+[tool.hatch.version]
+path = "src/codepraxis/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codepraxis"]
+
+# Explicit allow-list rather than exclusions. This package is published
+# publicly, so a new top-level directory must be opted in deliberately —
+# never swept into a release because nobody updated an ignore list.
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/codepraxis",
+    "tests",
+    "README.md",
+    "CONTRIBUTING.md",
+    "RELEASING.md",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+# Declared explicitly rather than inherited from ruff's defaults, which shift
+# between releases. Adding a rule should be a deliberate commit, not a side
+# effect of an upgrade.
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

codepraxis-0.1.0/src/codepraxis/__init__.py

@@ -0,0 +1,3 @@
+"""Author and validate CodePraxis challenge packs."""
+
+__version__ = "0.1.0"

codepraxis-0.1.0/src/codepraxis/__main__.py

@@ -0,0 +1,8 @@
+"""Allows ``python -m praxis``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())