making-with-code-cli 5.4.0__tar.gz → 5.6.0__tar.gz

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: making-with-code-cli
-Version: 5.4.0
+Version: 5.6.0
 Summary: Courseware for Making With Code
 Author: Chris Proctor
 Author-email: Chris Proctor <chris@chrisproctor.net>

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "making-with-code-cli"
-version = "5.4.0"
+version = "5.6.0"
 description = "Courseware for Making With Code"
 authors = [{ name = "Chris Proctor", email = "chris@chrisproctor.net" }]
 requires-python = ">=3.11,<4.0"
@@ -33,7 +33,7 @@ issues = "https://github.com/cproctor/making-with-code-courseware/issues"
 mwc = "making_with_code_cli.cli:cli"
 
 [build-system]
-requires = ["uv_build>=0.9.0,<0.10.0"]
+requires = ["uv_build>=0.11.0,<0.12.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -41,5 +41,11 @@ docs = [
     "sphinx>=8.2.3,<9",
     "sphinx-rtd-theme>=3.0.2,<4",
 ]
+test = [
+    "pytest>=8.0.0,<9",
+]
 [tool.uv]
 check-url = "https://pypi.org/simple/"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

making_with_code_cli-5.6.0/src/making_with_code_cli/assessment.py

@@ -0,0 +1,173 @@
+"""Shared spec and validation for assessment.md.
+
+A student module repo may contain `assessment.md`, written by a teacher (by hand or
+with a script -- assessment *tooling* is being designed and built separately from this
+spec) to record how the module was assessed. The file has TOML front matter (delimited
+with `+++`, matching the convention MWC's own site uses for module front matter)
+holding the *current* assessment -- evergreen, not a history. Re-assessment overwrites
+the front matter in place; the running history of what changed and why is written by
+the teacher as prose in the file's body (a letter to the student, in the style of the
+assessment-rubric skill), not as structured data.
+
+This module is the single place that knows the shape of that front matter, so that
+every reader and writer of `assessment.md` -- `mwc status` (student-facing),
+`mwc teach status` (teacher-facing), any future assessment tooling -- agrees on it and
+validates against the same rules, rather than each parsing it their own way.
+
+The front matter always has all four keys:
+- `assessment_type`: `"completion"` or `"score"`
+- `timestamp`: when the current assessment happened (authoritative for "how recent is
+  this assessment" -- deliberately the TOML value, not any git commit metadata, so
+  everything relevant stays in-band in the file itself)
+- `score`: an integer, `0 <= score <= points_possible`
+- `points_possible`: an integer; always `1` for `"completion"` (so score is `0` or `1`)
+
+Rubric-based assessment doesn't get its own structured type -- the rubric detail
+(per-criterion feedback) lives in the prose body, and the front matter just records
+a summary `"score"` that downstream consumers can turn into a grade.
+
+    +++
+    assessment_type = "score"
+    timestamp = 2026-03-15T09:30:00Z
+    score = 8
+    points_possible = 10
+    +++
+
+    Dear student, ...
+"""
+from dataclasses import dataclass
+from datetime import datetime
+from numbers import Real
+
+import tomlkit
+from tomlkit.exceptions import TOMLKitError
+
+from making_with_code_cli.errors import MWCError
+
+FRONT_MATTER_DELIMITER = "+++"
+ASSESSMENT_TYPES = ("completion", "score")
+
+
+class AssessmentValidationError(MWCError):
+    """Raised when assessment.md front matter doesn't conform to the spec."""
+
+
+@dataclass(frozen=True)
+class Assessment:
+    "A module's current assessment, evergreen (overwritten on re-assessment)."
+    assessment_type: str  # "completion" | "score"
+    timestamp: datetime
+    score: int
+    points_possible: int
+
+
+def extract_front_matter(markdown_text):
+    """Splits a +++...+++-delimited file into (front_matter_toml, body_markdown).
+    Returns ("", markdown_text) if there's no front matter at all -- a module that
+    hasn't been assessed yet may have no assessment.md, or an assessment.md with no
+    front matter yet, and that should parse as "not assessed," not an error.
+    """
+    lines = markdown_text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != FRONT_MATTER_DELIMITER:
+        return "", markdown_text
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == FRONT_MATTER_DELIMITER:
+            return "".join(lines[1:i]), "".join(lines[i + 1:])
+    # Opening delimiter with no closing delimiter -- treat as malformed, not fatal;
+    # callers just get "not assessed" back rather than a crash.
+    return "", markdown_text
+
+
+def parse_assessment(toml_text):
+    """Parses assessment.md's front matter into an Assessment, or None if it's
+    empty/missing `assessment_type` (not assessed yet -- a valid, unremarkable
+    state, not an error). Raises AssessmentValidationError if `assessment_type`
+    is present but the rest of the data doesn't conform to the spec.
+    """
+    if not toml_text.strip():
+        return None
+    try:
+        doc = tomlkit.parse(toml_text)
+    except TOMLKitError as e:
+        raise AssessmentValidationError(f"assessment.md front matter is not valid TOML: {e}")
+
+    if "assessment_type" not in doc:
+        return None
+    return _parse_assessment_table(doc)
+
+
+def parse_assessment_file(markdown_text):
+    """extract_front_matter + parse_assessment, for reading a whole assessment.md
+    file (its text content, not a path -- callers decide whether that text comes
+    from the working tree or `git show <ref>:assessment.md`)."""
+    front_matter, _ = extract_front_matter(markdown_text)
+    return parse_assessment(front_matter)
+
+
+def format_score(assessment):
+    """Compact single-line rendering of an assessment's score, for table display.
+    ASCII only (no unicode symbols), matching mwc teach status's convention.
+    """
+    if assessment.assessment_type == "completion":
+        return "Y" if assessment.score else "N"
+    return f"{assessment.score}/{assessment.points_possible}"
+
+
+def set_assessment(markdown_text, assessment):
+    """Returns markdown_text with its front matter replaced by `assessment`
+    (creating the front matter if markdown_text has none). The body is left
+    untouched -- the teacher writes their own log of the (re-)assessment there;
+    this function only ever owns the evergreen front matter, never the prose.
+    Uses tomlkit so any other keys already in the front matter are preserved.
+    """
+    front_matter, body = extract_front_matter(markdown_text)
+    doc = tomlkit.parse(front_matter) if front_matter.strip() else tomlkit.document()
+    doc["assessment_type"] = assessment.assessment_type
+    doc["timestamp"] = assessment.timestamp
+    doc["score"] = assessment.score
+    doc["points_possible"] = assessment.points_possible
+    new_front_matter = tomlkit.dumps(doc)
+    return f"{FRONT_MATTER_DELIMITER}\n{new_front_matter}{FRONT_MATTER_DELIMITER}\n{body}"
+
+
+def _parse_assessment_table(raw):
+    "Validates and converts a raw TOML mapping into an Assessment."
+    assessment_type = raw.get("assessment_type")
+    if assessment_type not in ASSESSMENT_TYPES:
+        raise AssessmentValidationError(
+            f"assessment_type must be one of {ASSESSMENT_TYPES}, got {assessment_type!r}"
+        )
+
+    timestamp = raw.get("timestamp")
+    if not isinstance(timestamp, datetime):
+        raise AssessmentValidationError("timestamp is required and must be a date/time")
+
+    if "score" not in raw:
+        raise AssessmentValidationError("score is required")
+    score = raw["score"]
+    if isinstance(score, bool) or not isinstance(score, Real):
+        raise AssessmentValidationError(f"score must be a number, got {score!r}")
+
+    if "points_possible" not in raw:
+        raise AssessmentValidationError("points_possible is required")
+    points_possible = raw["points_possible"]
+    if isinstance(points_possible, bool) or not isinstance(points_possible, Real):
+        raise AssessmentValidationError(f"points_possible must be a number, got {points_possible!r}")
+    if points_possible <= 0:
+        raise AssessmentValidationError("points_possible must be positive")
+
+    if assessment_type == "completion" and points_possible != 1:
+        raise AssessmentValidationError(
+            f"points_possible must be 1 for a completion assessment, got {points_possible!r}"
+        )
+    if not (0 <= score <= points_possible):
+        raise AssessmentValidationError(
+            f"score ({score}) must be between 0 and points_possible ({points_possible})"
+        )
+
+    return Assessment(
+        assessment_type=assessment_type,
+        timestamp=timestamp,
+        score=score,
+        points_possible=points_possible,
+    )

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/src/making_with_code_cli/cli.py

@@ -3,6 +3,7 @@ from making_with_code_cli.version import version
 from making_with_code_cli.setup import setup
 from making_with_code_cli.update import update
 from making_with_code_cli.submit import submit
+from making_with_code_cli.status import status
 from making_with_code_cli.teach import teach
 
 @click.group()
@@ -13,4 +14,5 @@ cli.add_command(version)
 cli.add_command(setup)
 cli.add_command(update)
 cli.add_command(submit)
+cli.add_command(status)
 cli.add_command(teach)

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/src/making_with_code_cli/git_backend/mwc_backend.py

@@ -1,5 +1,6 @@
 from .base_backend import GitBackend
 from subprocess import run, CalledProcessError
+import re
 import traceback
 from pathlib import Path
 from urllib.parse import urlparse
@@ -111,13 +112,22 @@ class MWCBackend(GitBackend):
         run(["git", "config", "--local", "user.name", name], check=True, cwd=modpath)
         run(["git", "config", "--local", "user.email", "nobody@makingwithcode.org"],
             check=True, cwd=modpath)
+        # EDITOR_COMMANDS covers the GUI editors that need an explicit "wait for
+        # the tab to close" flag. Anything else the student typed at setup was
+        # already verified to resolve on $PATH (see choose_editor), so pass it
+        # through as-is -- students should be able to use editors we don't know
+        # about by name. Only fall back to nano if editor is somehow unset.
         editor = self.settings.get('editor')
-        if editor in EDITOR_COMMANDS:
-            run(["git", "config", "--local", "core.editor", EDITOR_COMMANDS[editor]],
-                check=True, cwd=modpath)
+        editor_command = EDITOR_COMMANDS.get(editor, editor) or "nano"
+        run(["git", "config", "--local", "core.editor", editor_command],
+            check=True, cwd=modpath)
 
     def update(self, module, modpath, install=True):
         if (modpath / ".git").is_dir():
+            # Idempotent -- re-applies user/editor config so repos created
+            # before this config existed (or with a stale editor choice)
+            # still get it.
+            self.configure_git(modpath)
             relpath = self.relative_path(modpath)
             click.echo(address(f"Checking {relpath} for updates.", preformatted=True))
             pull_output = self.safe_pull(modpath)
@@ -144,44 +154,57 @@ class MWCBackend(GitBackend):
                 f"Cleared an incomplete git {aborted} — this shouldn't affect your work."
             ))
 
-        branch = recover_detached_head(modpath)
-        if branch:
+        recovered = recover_detached_head(modpath)
+        if recovered:
+            branch, stash_unresolved = recovered
             click.echo(confirm(
                 f"Your repo was not on any branch. Switched back to '{branch}'."
             ))
+            if stash_unresolved:
+                click.echo(error(
+                    "Some of your uncommitted work couldn't be automatically restored "
+                    "and is saved in a git stash instead of your files. "
+                    "Ask your teacher for help recovering it."
+                ))
 
         clear_stale_index_lock(modpath)
 
-        # U1: uncommitted changes that would be overwritten — auto-commit first
+        run("git fetch origin", shell=True, capture_output=True, cwd=modpath)
+
+        # Detect (without applying) any genuine content conflicts between
+        # FETCH_HEAD and the repo's current state -- both the working tree
+        # (if dirty) and the student's committed history. -X ours/-X theirs
+        # auto-resolve conflicts silently, so this is the only way to know
+        # when that's about to happen.
+        conflicted = self._conflicting_files(modpath, "FETCH_HEAD")
+
+        # U1: uncommitted changes that would genuinely conflict with the
+        # update — cancel and have the student save their own work first,
+        # rather than guessing at a commit message on their behalf. Handling
+        # one thing at a time (submit, then update) is clearer for students
+        # than a merge that silently combines both, and avoids a commit
+        # showing up in their history that they didn't write.
         status = run(
             "git status --porcelain",
             shell=True, capture_output=True, text=True, cwd=modpath
         )
-        if status.stdout.strip():
-            probe = run(
-                "git fetch origin",
-                shell=True, capture_output=True, text=True, cwd=modpath
+        if status.stdout.strip() and conflicted:
+            raise GitError(
+                "You have unsaved changes here that would conflict with an "
+                "update. Run `mwc submit` to save your work, then run "
+                "`mwc update` again."
             )
-            merge_check = run(
-                "git merge --no-commit --no-ff FETCH_HEAD",
-                shell=True, capture_output=True, text=True, cwd=modpath
-            )
-            # Always abort the probe merge so we start clean
-            run("git merge --abort", shell=True, capture_output=True, cwd=modpath)
-            if "CONFLICT" in merge_check.stdout or "CONFLICT" in merge_check.stderr:
-                run(["git", "add", "--all"], capture_output=True, cwd=modpath)
-                run(
-                    ["git", "commit", "-m", "[auto-saved before update]"],
-                    capture_output=True, cwd=modpath
-                )
-                click.echo(confirm(
-                    "Your unsaved changes were auto-saved in git history "
-                    "before applying the update."
-                ))
 
         result = self._run_pull(modpath)
 
         if result.returncode == 0:
+            if conflicted:
+                files = ", ".join(f"`{f}`" for f in conflicted)
+                click.echo(error(
+                    f"Your changes to {files} conflicted with an update — the "
+                    "update's version was kept for the conflicting lines. Ask "
+                    "your teacher if you're not sure that's right."
+                ))
             return result.stdout
 
         combined = result.stderr + result.stdout
@@ -209,6 +232,43 @@ class MWCBackend(GitBackend):
             shell=True, capture_output=True, text=True, cwd=modpath
         )
 
+    def _conflicting_files(self, modpath, ref):
+        """Returns the list of files that can't be cleanly auto-merged when
+        merging `ref` into HEAD, without actually applying or committing
+        anything. -X ours/-X theirs auto-resolve conflicts and don't report
+        them, so this is the only way to tell whether an automatic merge is
+        about to silently pick a side on real conflicting content (as opposed
+        to just cleanly combining separate, non-overlapping changes).
+
+        Covers two distinct git failure modes: real textual conflicts
+        (reported as "CONFLICT", with the files showing up in
+        `git diff --diff-filter=U`), and a dirty working tree touching the
+        same file as the incoming change (git refuses outright with "local
+        changes ... would be overwritten by merge" and never starts a merge
+        at all, so there's nothing in the index to look up -- the filenames
+        have to be parsed out of that message instead).
+        """
+        merge_check = run(
+            f"git merge --no-commit --no-ff {ref}",
+            shell=True, capture_output=True, text=True, cwd=modpath
+        )
+        conflicts = []
+        if merge_check.returncode != 0:
+            diff = run(
+                "git diff --name-only --diff-filter=U",
+                shell=True, capture_output=True, text=True, cwd=modpath
+            )
+            conflicts = [f for f in diff.stdout.splitlines() if f.strip()]
+            if not conflicts:
+                combined = merge_check.stdout + merge_check.stderr
+                conflicts = re.findall(r"^\t(.+)$", combined, re.MULTILINE)
+        # Always abort the probe merge so we start clean. This is a no-op
+        # (and prints a harmless "no merge to abort" to stderr, which we
+        # discard) in the "would be overwritten" case, since no merge ever
+        # started there.
+        run("git merge --abort", shell=True, capture_output=True, cwd=modpath)
+        return conflicts
+
     def _raise_pull_error(self, stderr):
         if any(p in stderr for p in _NETWORK_PHRASES):
             raise GitNetworkError(
@@ -233,7 +293,15 @@ class MWCBackend(GitBackend):
     def init_direnv(self, modpath):
         if not (modpath / ".envrc").exists():
             (modpath / ".envrc").write_text("source .venv/bin/activate")
-        run("direnv allow", shell=True, check=True, cwd=modpath)
+        try:
+            run("direnv allow", shell=True, check=True, cwd=modpath, capture_output=True)
+        except CalledProcessError:
+            raise GitError(
+                "Could not run `direnv allow` -- direnv doesn't seem to be installed "
+                "or isn't on your PATH. Try closing and reopening your terminal (so it "
+                "picks up changes from setup), then run `mwc update` again. If that "
+                "doesn't help, run `mwc setup` again or ask your teacher for help."
+            )
 
     def user_has_repo(self, repo_name, username=None):
         """Checks to see whether a user already has the named repo."""

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/src/making_with_code_cli/git_wrapper.py

@@ -1,7 +1,12 @@
+from datetime import datetime
 from pathlib import Path
 from subprocess import run, CalledProcessError
 from making_with_code_cli.helpers import cd
 
+# Field separator for git log --format parsing below -- chosen because it can't
+# appear in an author name/email, unlike "|" or ",".
+_FIELD_SEP = "\x1f"
+
 
 def in_repo():
     """Checks whether currently in repo"""
@@ -12,14 +17,14 @@ def in_repo():
         return False
 
 
-def repo_has_changes():
-    return len(changed_files()) > 0
+def repo_has_changes(cwd=None):
+    return len(changed_files(cwd=cwd)) > 0
 
 
-def changed_files():
+def changed_files(cwd=None):
     "Returns a list of (status, filename) tuples for changed files"
     cmd = "git status --porcelain"
-    result = run(cmd, shell=True, capture_output=True, text=True).stdout
+    result = run(cmd, shell=True, capture_output=True, text=True, cwd=cwd).stdout
     files = []
     if result:
         for line in result.split('\n'):
@@ -76,7 +81,13 @@ def abort_in_progress_operation(cwd=None):
 
 def recover_detached_head(cwd=None):
     """If in detached HEAD, checks out the default branch and returns its name.
-    Returns None if no action was needed.
+    Returns None if no action was needed, otherwise (branch, stash_unresolved),
+    where stash_unresolved is True if uncommitted work couldn't be automatically
+    restored and was left in the stash rather than being discarded. Detached HEAD
+    is never something a student does on purpose (they never use branches) --
+    it comes from pasting a git command found online, or a GUI tool's "checkout
+    this commit" action, so there's no real "their branch" to speak of, just the
+    one branch every student repo has.
     """
     if get_repo_state(cwd) != "detached":
         return None
@@ -87,14 +98,22 @@ def recover_detached_head(cwd=None):
     )
     had_stash = "No local changes to save" not in stash_result.stdout
     run(["git", "checkout", branch], capture_output=True, cwd=cwd)
+    stash_unresolved = False
     if had_stash:
         pop_result = run(
             "git stash pop", shell=True, capture_output=True, text=True, cwd=cwd
         )
-        # If pop conflicts (extreme edge case), drop the stash
+        # If pop conflicts, leave the stash in place rather than dropping it --
+        # dropping it would silently and permanently destroy the student's
+        # uncommitted work with no way to recover it. A failed pop also
+        # leaves raw conflict markers in the working tree (git leaking
+        # through as confusing, not just destructive), so reset the tree back
+        # to a clean state; the stash is still intact and is the record of
+        # what didn't come back automatically.
         if pop_result.returncode != 0:
-            run("git stash drop", shell=True, capture_output=True, cwd=cwd)
-    return branch
+            stash_unresolved = True
+            run(["git", "reset", "--hard"], capture_output=True, cwd=cwd)
+    return (branch, stash_unresolved)
 
 
 def clear_stale_index_lock(cwd=None):
@@ -106,6 +125,29 @@ def clear_stale_index_lock(cwd=None):
     return False
 
 
+def commits_since(since, author_name, author_email, ref="HEAD", cwd=None):
+    """Returns True if there's a commit on `ref`, authored by exactly
+    (author_name, author_email), with an author date after `since` (a
+    timezone-aware datetime). Used to detect work submitted by a specific
+    student after a given cutoff -- e.g. "has anything been pushed since this
+    was last assessed" -- without caring about commits from anyone else
+    (a teacher, a co-author, etc.) that might also be on the same ref.
+    """
+    result = run(
+        f"git log {ref} --format=%an{_FIELD_SEP}%ae{_FIELD_SEP}%aI",
+        shell=True, capture_output=True, text=True, cwd=cwd
+    )
+    if result.returncode != 0:
+        return False
+    for line in result.stdout.strip().splitlines():
+        name, _, rest = line.partition(_FIELD_SEP)
+        email, _, when = rest.partition(_FIELD_SEP)
+        if name == author_name and email == author_email:
+            if datetime.fromisoformat(when) > since:
+                return True
+    return False
+
+
 def _get_default_branch(cwd=None):
     """Returns the remote default branch name, falling back to 'main'."""
     result = run(

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/src/making_with_code_cli/setup/__init__.py

@@ -39,9 +39,11 @@ from making_with_code_cli.setup.tasks import (
     InstallImageMagick,
     InstallHttpie,
     InstallScipy,
+    InstallZstd,
     InstallOllama,
     InstallPandoc,
     InstallPoppler,
+    InstallPythonBuildDeps,
 )
 
 @click.command()
@@ -109,9 +111,11 @@ def setup(ctx, config, debug, mwc_accounts_url):
         InstallVSCode,
         InstallImageMagick,
         InstallHttpie,
+        InstallZstd,
         InstallOllama,
         InstallPandoc,
         InstallPoppler,
+        InstallPythonBuildDeps,
     ]
     errors = []
     for task_class in task_classes:

{making_with_code_cli-5.4.0 → making_with_code_cli-5.6.0}/src/making_with_code_cli/setup/tasks.py

@@ -84,7 +84,7 @@ class Platform(Flag):
             else:
                 return "brew install "
         elif p in (cls.UBUNTU, cls.WSL):
-            return "sudo apt install "
+            return "sudo apt install -y "
         else:
             raise PlatformNotSupported()
 
@@ -262,8 +262,10 @@ class WriteMWCShellConfig(SetupTask):
         "Generates the shell configuration file contents"
         f = ""
         shell = get_shell_name()
-        f += "# Making With Code RC File\n" 
+        f += "# Making With Code RC File\n"
         f += f"# See {self.docs_url}\n\n"
+        f += "## Make sure user-local installs (e.g. direnv) are on $PATH\n"
+        f += 'export PATH="$HOME/.local/bin:$PATH"\n\n'
         f += "## Hook direnv into shell\n"
         f += f'eval "$(direnv hook {shell})"\n\n'
 
@@ -388,7 +390,15 @@ class InstallPackageFromInstaller(InstallPackage):
 
 class InstallDirenv(InstallPackageFromInstaller):
     executable_name = "direnv"
-    install_command = "curl -sfL https://direnv.net/install.sh | bash"
+    # direnv's installer defaults to dropping the binary in "./bin", relative
+    # to whatever directory this happens to be run from, which usually isn't
+    # on $PATH. Pin bin_dir to ~/.local/bin, which WriteMWCShellConfig adds
+    # to $PATH, so the installed binary is reliably found afterward.
+    install_command = 'curl -sfL https://direnv.net/install.sh | bin_dir="$HOME/.local/bin" bash'
+
+    def run_task(self):
+        Path.home().joinpath(".local", "bin").mkdir(parents=True, exist_ok=True)
+        super().run_task()
 
 class InstallGit(InstallPackage):
     platform = Platform.MAC | Platform.UBUNTU
@@ -444,6 +454,14 @@ class InstallScipy(InstallPackage):
     def is_complete(self):
         return find_spec("scipy") is not None
 
+class InstallZstd(InstallPackage):
+    """zstd is a prerequisite for ollama's Linux install script, which
+    extracts a .tar.zst bundle. Not needed on Mac (ollama ships as a .zip
+    there, and the curl|sh installer isn't used).
+    """
+    platform = Platform.UBUNTU | Platform.WSL
+    executable_name = apt_name = "zstd"
+
 class InstallOllama(InstallPackage):
     executable_name = "ollama"
     brew_name = "ollama"
@@ -463,5 +481,23 @@ class InstallPoppler(InstallPackage):
     brew_name = "poppler"
     apt_name = "poppler-utils"
 
+class InstallPythonBuildDeps(InstallPackage):
+    """Installs system packages needed to compile Python C-extension
+    dependencies (lxml, Levenshtein) from source.
+
+    On Mac, prebuilt wheels are normally available, so this is a no-op there.
+    On Ubuntu/WSL, if no prebuilt wheel matches the student's Python version,
+    `uv`/`pip` falls back to building from source, which needs headers, a
+    compiler, and (for Levenshtein's rapidfuzz-cpp backend) cmake/ninja.
+    """
+    platform = Platform.UBUNTU | Platform.WSL
+    description = "Install build dependencies for lxml and Levenshtein"
+    apt_name = "libxml2-dev libxslt1-dev python3-dev build-essential cmake ninja-build"
+
+    def is_complete(self):
+        return all(
+            run(["dpkg", "-s", package], capture_output=True).returncode == 0
+            for package in self.apt_name.split()
+        )