From 38a89b0404d2b698de99b19d5c72bd7f1d85adfa Mon Sep 17 00:00:00 2001
From: Agent <ai@blobfish.icu>
Date: Sun, 9 Aug 2026 15:47:41 -0400
Subject: [PATCH] feat(docs-dev): add DocsDev image for the 415-docs review
 environment

Bundles the toolchain that cmput415/415-docs's CI workflows and
.agents/ scaffold expect: Sphinx + latexmk + texlive (deploySite.yml),
lychee (linkcheck.yml), uv (pyproject-managed venv), act (local
workflow replay), plus graphviz and gnupg. Published under
ghcr.io/cmput415/docs-dev via a workflow that mirrors the existing
GazUtils/ANTLR/LLVM/DragonRunner build-and-push pattern.

Requested in review on cmput415/415-docs#110 -- lets the .agents/
scaffold there point at a maintained image instead of a bash
bootstrap script per session.

Assisted-by: Agent (claude) <ai@blobfish.icu>
---
 .github/workflows/docs-dev.yml | 45 ++++++++++++++++++++++++++
 DocsDev/Dockerfile             | 59 ++++++++++++++++++++++++++++++++++
 DocsDev/README.md              | 38 ++++++++++++++++++++++
 3 files changed, 142 insertions(+)
 create mode 100644 .github/workflows/docs-dev.yml
 create mode 100644 DocsDev/Dockerfile
 create mode 100644 DocsDev/README.md

diff --git a/.github/workflows/docs-dev.yml b/.github/workflows/docs-dev.yml
new file mode 100644
index 0000000..93a6d85
--- /dev/null
+++ b/.github/workflows/docs-dev.yml
@@ -0,0 +1,45 @@
+name: DocsDev Image Deployment
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - DocsDev/Dockerfile
+      - DocsDev/README.md
+      - .github/workflows/docs-dev.yml
+
+jobs:
+  build-docs-dev:
+    runs-on: self-hosted
+
+    env:
+      IMAGE_NAME: ghcr.io/cmput415/docs-dev
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set date tag
+        id: date
+        run: echo "tag=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+
+      - name: Build Docker image
+        run: |
+          docker build \
+            -t $IMAGE_NAME:${{ steps.date.outputs.tag }} \
+            -t $IMAGE_NAME:latest \
+            ./DocsDev
+
+      - name: Push Docker image with date tag
+        run: docker push $IMAGE_NAME:${{ steps.date.outputs.tag }}
+
+      - name: Push Docker image with latest tag
+        run: docker push $IMAGE_NAME:latest
diff --git a/DocsDev/Dockerfile b/DocsDev/Dockerfile
new file mode 100644
index 0000000..0750421
--- /dev/null
+++ b/DocsDev/Dockerfile
@@ -0,0 +1,59 @@
+# Docs + spec-review development image for cmput415/415-docs.
+#
+# Bundles the toolchain the docs repo builds and reviews under:
+#   - Sphinx + latexmk + texlive-latex-extra (matches deploySite.yml)
+#   - lychee link checker (matches linkcheck.yml)
+#   - uv (Astral) for the pyproject.toml-managed venv
+#   - act (nektos) for running the repo's GitHub Actions workflows locally
+#   - graphviz + GPG for the .agents/ session tooling
+#
+# The image is intentionally self-contained: an agent (or a human) running
+# a spec-review session should be able to `docker run` it and get every
+# tool the CI workflows and the .agents/ scaffold expect on PATH, without
+# any apt-get on the host.
+
+FROM ubuntu:24.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG LYCHEE_VERSION=0.15.1
+ARG ACT_VERSION=0.2.68
+
+# System deps
+#   - build-essential/git/curl/ca-certificates: fetch and build tools
+#   - python3 + python3-pip + python3-venv: uv-managed venv target
+#   - latexmk + texlive-latex-extra: PDF build (matches deploySite.yml)
+#   - graphviz: Sphinx graphviz directive
+#   - gnupg: opt-in agent commit signing via .agents/
+#   - jq: workflow-file parsing for act invocations
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      build-essential git curl ca-certificates jq \
+      python3 python3-pip python3-venv \
+      latexmk texlive-latex-extra texlive-fonts-recommended \
+      graphviz gnupg \
+    && rm -rf /var/lib/apt/lists/*
+
+# uv (Astral) — pinned python package manager for the repo's pyproject.toml.
+# Install into /usr/local/bin so it is on PATH for every user of the image.
+RUN curl -LsSf https://astral.sh/uv/install.sh \
+      | env UV_INSTALL_DIR=/usr/local/bin sh
+
+# lychee — link checker used by linkcheck.yml. Pinned; upgrade in lockstep
+# with the workflow's lycheeverse/lychee-action version.
+RUN curl -LsSf \
+      "https://github.com/lycheeverse/lychee/releases/download/lychee-v${LYCHEE_VERSION}/lychee-x86_64-unknown-linux-gnu.tar.gz" \
+      | tar -xz -C /usr/local/bin lychee \
+    && lychee --version
+
+# act — run GitHub Actions workflows locally. Lets .agents/skills/spec-review
+# invoke the real workflow definitions instead of re-implementing them in
+# bash. Pinned to a known-good release; upgrade explicitly.
+RUN curl -LsSf \
+      "https://github.com/nektos/act/releases/download/v${ACT_VERSION}/act_Linux_x86_64.tar.gz" \
+      | tar -xz -C /usr/local/bin act \
+    && act --version
+
+WORKDIR /workspace
+
+# Sanity-check the toolchain surface at build time so a regression here
+# fails the image build rather than the first user session.
+RUN uv --version && sphinx-build --version 2>/dev/null || uv run --with sphinx==6.2.1 sphinx-build --version
diff --git a/DocsDev/README.md b/DocsDev/README.md
new file mode 100644
index 0000000..18ff952
--- /dev/null
+++ b/DocsDev/README.md
@@ -0,0 +1,38 @@
+# DocsDev
+
+Docker image bundling the toolchain used by
+[`cmput415/415-docs`](https://github.com/cmput415/415-docs) for local docs
+builds and spec-review sessions.
+
+Includes:
+
+- Sphinx + `latexmk` + `texlive-latex-extra` (matches `deploySite.yml`)
+- [`lychee`](https://github.com/lycheeverse/lychee) (matches `linkcheck.yml`)
+- [`uv`](https://github.com/astral-sh/uv) for the repo's `pyproject.toml` venv
+- [`act`](https://github.com/nektos/act) for running the repo's GitHub
+  Actions workflows locally
+- `graphviz`, `gnupg`, `jq`
+
+## Usage
+
+```sh
+docker run --rm -it \
+  -v "$PWD":/workspace \
+  ghcr.io/cmput415/docs-dev:latest \
+  bash
+```
+
+Inside the container:
+
+```sh
+uv sync
+uv run make -C gazprea html
+act -j build            # replays deploySite.yml locally
+act -j linkcheck        # replays linkcheck.yml locally
+```
+
+## Versions
+
+`LYCHEE_VERSION` and `ACT_VERSION` are pinned in the `Dockerfile`; bump
+them in lockstep with the corresponding action versions in
+`.github/workflows/` under `415-docs`.