making-with-code-cli 5.2.1__py3-none-any.whl → 5.6.0__py3-none-any.whl

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/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/curriculum.py

@@ -11,7 +11,7 @@ def get_curriculum(mwc_site_url, course_name=None):
     """Fetches curriculum metadata from the site url specified in settings.
     Returns the curriculum metadata for course_name.
     """
-    url = mwc_site_url + "/manifest"
+    url = mwc_site_url.rstrip("/") + "/manifest"
     try:
         response = requests.get(url, timeout=15)
     except requests.exceptions.RequestException as e:

making_with_code_cli/errors.py

@@ -26,3 +26,15 @@ class SoftwareInstallationError(MWCError):
 
 class NoCurriculaAvailable(MWCError):
     pass
+
+class GitError(MWCError):
+    pass
+
+class GitNetworkError(GitError):
+    pass
+
+class GitAuthError(GitError):
+    pass
+
+class GitCorruptError(GitError):
+    pass

making_with_code_cli/git_backend/base_backend.py

@@ -2,7 +2,6 @@ from pathlib import Path
 from subprocess import run, CalledProcessError
 import click
 from making_with_code_cli.helpers import cd
-from making_with_code_cli.setup.tasks import WORK_DIR_PERMISSIONS
 from making_with_code_cli.styles import (
     address,
     info,

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
@@ -8,6 +9,12 @@ import json
 import os
 import requests
 from making_with_code_cli.helpers import cd
+from making_with_code_cli.git_wrapper import (
+    abort_in_progress_operation,
+    recover_detached_head,
+    clear_stale_index_lock,
+    _get_default_branch,
+)
 from making_with_code_cli.styles import (
     address,
     confirm,
@@ -18,6 +25,10 @@ from making_with_code_cli.styles import (
 from making_with_code_cli.errors import (
     MissingSetting,
     GitServerNotAvailable,
+    GitError,
+    GitNetworkError,
+    GitAuthError,
+    GitCorruptError,
 )
 
 EDITOR_COMMANDS = {
@@ -29,17 +40,55 @@ EDITOR_COMMANDS = {
     "emacs": "emacs",
 }
 
+# Phrases in git stderr that identify each failure mode
+_NETWORK_PHRASES = [
+    "Could not resolve host",
+    "Connection timed out",
+    "unable to connect",
+    "Failed to connect",
+    "network is unreachable",
+    "Connection refused",
+]
+_AUTH_PHRASES = [
+    "Authentication failed",
+    "403",
+    "invalid credentials",
+    "could not read Username",
+    "terminal prompts disabled",
+    "Repository not found",
+]
+_CORRUPT_PHRASES = [
+    "corrupt",
+    "bad object",
+    "loose object",
+    "fatal: bad",
+    "object file is empty",
+]
+_NO_UPSTREAM_PHRASES = [
+    "no tracking information",
+    "has no upstream",
+    "There is no tracking information",
+]
+
+
 class MWCBackend(GitBackend):
-    """A Github backend. Students own their own repos and grant teachers access via token.
-    """
+    """A Github backend. Students own their own repos and grant teachers access via token."""
 
     MWC_GIT_PROTOCOL = "https"
     MWC_GIT_SERVER = "git.makingwithcode.org"
     COMMIT_TEMPLATE = ".commit_template"
 
+    @property
+    def git_server(self):
+        """Returns the git server hostname, respecting git_server_url setting if set."""
+        url = self.settings.get('git_server_url')
+        if url:
+            parsed = urlparse(url)
+            return parsed.netloc
+        return self.MWC_GIT_SERVER
+
     def init_module(self, module, modpath):
-        """Creates the named repo from a template.
-        """
+        """Creates the named repo from a template."""
         self.check_settings()
         server, repo_owner, repo_name = self.parse_repo_url(module["repo_url"])
 
@@ -53,8 +102,9 @@ class MWCBackend(GitBackend):
         if (modpath / self.COMMIT_TEMPLATE).exists():
             run(["git", "config", "--local", "commit.template", self.COMMIT_TEMPLATE],
                     check=True, cwd=modpath)
-        run("uv venv", shell=True, check=True, cwd=modpath, capture_output=True)
-        self.init_direnv(modpath)
+        if self.settings.get('manage_python_environment', True):
+            run("uv venv", shell=True, check=True, cwd=modpath, capture_output=True)
+            self.init_direnv(modpath)
 
     def configure_git(self, modpath):
         """Configures git user settings locally for the repo."""
@@ -62,41 +112,199 @@ 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():
-            with cd(modpath):
-                relpath = self.relative_path(modpath)
-                click.echo(address(f"Checking {relpath} for updates.", preformatted=True))
-                gitresult = run("git pull", shell=True, capture_output=True, text=True)
-                if gitresult.returncode != 0:
-                    click.echo(error(
-                        f"Could not update {relpath}: {gitresult.stderr.strip()}\n"
-                        "You may have local changes that conflict. Ask a teacher for help."
-                    ))
-                    return
-                click.echo(info(gitresult.stdout))
-                if install and Path("pyproject.toml").exists():
-                    result = run("uv sync", shell=True, capture_output=True, text=True, cwd=modpath)
-                    if result.returncode != 0:
-                        click.echo(debug("Error running uv sync:"))
-                        click.echo(debug(result.stderr, preformatted=True))
-                        click.echo(error(f"There was a problem updating {relpath}. Ask a teacher."))
-                    else:
-                        self.init_direnv(modpath)
+            # 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)
+            if pull_output:
+                click.echo(info(pull_output))
+            if install and (modpath / "pyproject.toml").exists() and self.settings.get('manage_python_environment', True):
+                result = run("uv sync", shell=True, capture_output=True, text=True, cwd=modpath)
+                if result.returncode != 0:
+                    click.echo(debug("Error running uv sync:"))
+                    click.echo(debug(result.stderr, preformatted=True))
+                    click.echo(error(f"There was a problem updating {relpath}. Ask a teacher."))
+                else:
+                    self.init_direnv(modpath)
+
+    def safe_pull(self, modpath):
+        """Pulls from origin with robust recovery for common git error states.
+        Returns the git output string on success. Raises GitError subclasses on
+        unrecoverable failures.
+        """
+        # Fix bad repo states before attempting the pull
+        aborted = abort_in_progress_operation(modpath)
+        if aborted:
+            click.echo(confirm(
+                f"Cleared an incomplete git {aborted} — this shouldn't affect your work."
+            ))
+
+        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)
+
+        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() 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."
+            )
+
+        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
+
+        # U8: no upstream tracking branch — set it and retry
+        if any(p in combined for p in _NO_UPSTREAM_PHRASES):
+            default_branch = _get_default_branch(modpath)
+            run(
+                f"git branch --set-upstream-to=origin/{default_branch} {default_branch}",
+                shell=True, capture_output=True, cwd=modpath
+            )
+            result = self._run_pull(modpath)
+            if result.returncode == 0:
+                return result.stdout
+            combined = result.stderr + result.stdout
+
+        click.echo(debug(combined.strip(), preformatted=True))
+        self._raise_pull_error(combined)
+
+    def _run_pull(self, modpath):
+        # -X theirs resolves merge conflicts in favor of incoming (teacher) changes,
+        # and also handles diverged-history cases (U2, U3) without extra configuration.
+        return run(
+            "git pull -X theirs",
+            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(
+                "Could not connect to the MWC server. "
+                "Check your internet connection and try again."
+            )
+        if any(p in stderr for p in _AUTH_PHRASES):
+            raise GitAuthError(
+                "Your login credentials are no longer valid. "
+                "Run `mwc setup` to refresh them, then run `mwc update` again."
+            )
+        if any(p in stderr for p in _CORRUPT_PHRASES):
+            raise GitCorruptError(
+                "Your local copy of this module appears to be damaged. "
+                "Ask your teacher for help."
+            )
+        raise GitError(
+            "Could not update this module. "
+            "The details are shown above. If you're not sure what to do, ask your teacher."
+        )
 
     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.
-        """
+        """Checks to see whether a user already has the named repo."""
         username = username or self.settings['mwc_username']
         url = f"/repos/{username}/{repo_name}"
         response = self.authenticated_mwc_request('get', url)
@@ -115,7 +323,7 @@ class MWCBackend(GitBackend):
     def clone_repo(self, repo_name):
         user = self.settings['mwc_username']
         auth = user + ':' + self.settings['mwc_git_token']
-        url = f"{self.MWC_GIT_PROTOCOL}://{auth}@{self.MWC_GIT_SERVER}/{user}/{repo_name}.git"
+        url = f"{self.MWC_GIT_PROTOCOL}://{auth}@{self.git_server}/{user}/{repo_name}.git"
         run(["git", "clone", url], check=True, capture_output=True)
 
     def check_settings(self):
@@ -135,7 +343,7 @@ class MWCBackend(GitBackend):
         return (server, repo_owner, repo_name)
 
     def authenticated_mwc_request(self, method_name, urlpath, data=None, params=None):
-        server = self.MWC_GIT_PROTOCOL + '://' + self.MWC_GIT_SERVER
+        server = self.MWC_GIT_PROTOCOL + '://' + self.git_server
         args = {
             'url': server + "/api/v1" + urlpath,
             'auth': (self.settings['mwc_username'], self.settings['mwc_git_token']),
@@ -151,8 +359,7 @@ class MWCBackend(GitBackend):
         return response
 
     def relocate_existing_directory(self, path):
-        """Moves an existing directory out of the way.
-        """
+        """Moves an existing directory out of the way."""
         new_path = path.parent / path.name + '_old'
         while new_path.exists():
             new_path = new_path.parent / new_path.name + '_old'