chore: Release v0.2.0

.github/workflows/build-ci-image.yml

@@ -0,0 +1,59 @@
+name: Build CI Environment Image
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'Dockerfile.test'
+      - '.github/workflows/build-ci-image.yml'
+  pull_request:
+    paths:
+      - 'Dockerfile.test'
+      - '.github/workflows/build-ci-image.yml'
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Convert repository owner to lowercase for Docker compatibility
+      - name: Lowercase repository owner
+        id: lowercase_owner
+        run: |
+          echo "owner=${GITHUB_REPOSITORY_OWNER,,}" >> $GITHUB_OUTPUT
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051
+        with:
+          images: ghcr.io/${{ steps.lowercase_owner.outputs.owner }}/newsdom-api/ci-env
+          tags: |
+            type=raw,value=latest
+            type=sha
+
+      - name: Build and push test image
+        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25
+        with:
+          context: .
+          file: ./Dockerfile.test
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/dependency-review.yml

@@ -19,3 +19,5 @@ jobs:
 
       - name: Dependency review
         uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48
+        with:
+          allow-ghsas: "GHSA-69w3-r845-3855"

.github/workflows/tests.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: read
+  packages: read
 
 jobs:
   pytest:
@@ -18,7 +19,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
       - name: Setup Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: '3.10'
 
@@ -27,10 +28,11 @@ jobs:
         with:
           version: '0.11.3'
 
-      - name: Install package
-        run: uv sync --locked --extra dev
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
 
-      - name: Run tests with warnings as errors
+      - name: Run tests with coverage
         env:
           PYTHONWARNINGS: error
-        run: uv run pytest
+          PYTHONPATH: src
+        run: uv run pytest --cov=src/newsdom_api --cov-branch --cov-report=term-missing --cov-fail-under=100

.gitignore

@@ -10,8 +10,8 @@ site/
 *.pyc
 private/
 tmp/
-site/
 registered_agents.json
 task_agent_mapping.json
 content_file_3982.pdf
 page1_300dpi-1.png
+.worktrees/

ARCHITECTURE.md

@@ -13,9 +13,11 @@ orchestration, MinerU process execution, and DOM normalization.
 - `src/newsdom_api/service.py` orchestrates PDF parsing,
   temporary files, and response construction.
 - `src/newsdom_api/mineru_runner.py` shells out to the MinerU CLI,
-  collects JSON outputs, and surfaces process errors.
+  collects JSON outputs, and translates runtime or incomplete-output
+  failures into typed sanitized exceptions.
 - `src/newsdom_api/dom_builder.py` converts MinerU `content_list`
-  blocks into the canonical NewsDOM response model.
+  blocks plus page model metadata into the canonical NewsDOM response
+  model.
 - `src/newsdom_api/schemas.py` defines the public response schema.
 - `src/newsdom_api/synthetic.py` and
   `src/newsdom_api/equivalence.py` support synthetic fixture
@@ -27,9 +29,13 @@ orchestration, MinerU process execution, and DOM normalization.
 2. `src/newsdom_api/service.py` writes the upload to a temporary
    workspace and calls MinerU.
 3. `src/newsdom_api/mineru_runner.py` resolves the executable, runs
-   the OCR pipeline, and loads generated JSON artifacts.
-4. `src/newsdom_api/dom_builder.py` normalizes OCR blocks into the canonical response.
-5. FastAPI returns typed JSON from `src/newsdom_api/schemas.py`.
+   the OCR pipeline, loads generated JSON artifacts, and raises typed
+   sanitized errors for runtime-unavailable or incomplete-output cases.
+4. `src/newsdom_api/dom_builder.py` normalizes OCR blocks into the
+   canonical response while preserving page-aware structure from
+   MinerU model metadata.
+5. FastAPI returns typed JSON from `src/newsdom_api/schemas.py` and
+   maps MinerU runtime failures to 503 and incomplete output to 502.
 
 ## Supporting systems
 

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-24
+
+### Added
+
+- Added `benchmark_ocr.py` tool to measure OCR engine performance and structural accuracy on private datasets.
+- Deployed a GHCR prebuilt CI container image (`ghcr.io/seongho-bae/newsdom-api/ci-env`) to stabilize test environments and resolve timeout/dependency installation issues.
+
+### Changed
+
+- Updated `dom_builder.py` to preserve multi-page MinerU structure instead of collapsing multi-page outputs into a single page.
+- Adjusted the `/parse` endpoint to return specific HTTP error codes (`502` and `503`) mapped to `MineruIncompleteOutputError` and `MineruRuntimeUnavailableError` rather than raw `500` errors.
+
+### Fixed
+
+- Mitigated infinite hang issues when processing specific PDFs by enforcing a strict timeout (300 seconds) in the `mineru` subprocess runner.
+- Resolved permission (`EACCES`) issues in GitHub Actions by running tests locally instead of inside a non-root container context for GitHub's restricted runner environment.
+
 ## [0.1.1] - 2026-04-11
 
 ### Added
@@ -31,6 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Synthetic newspaper fixture generation and structural equivalence checks
 - Protected-branch CI, security gates, release provenance workflow, and Git Flow documentation
 
-[Unreleased]: https://github.com/Seongho-Bae/newsdom-api/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/Seongho-Bae/newsdom-api/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Seongho-Bae/newsdom-api/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Seongho-Bae/newsdom-api/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Seongho-Bae/newsdom-api/releases/tag/v0.1.0

Dockerfile

@@ -11,12 +11,16 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 
 WORKDIR /app
 
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
 COPY --from=uv-bin /uv /uvx /bin/
 
 COPY pyproject.toml uv.lock README.md ./
 COPY src/ src/
 
-RUN uv sync --frozen --no-dev
+RUN uv sync --frozen --no-dev --extra mineru
 
 FROM ${PYTHON_BASE} AS runtime
 
@@ -27,17 +31,16 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 
 WORKDIR /app
 
-RUN useradd --create-home --home-dir /home/newsdom --shell /usr/sbin/nologin newsdom
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
 
-COPY --from=builder /app /app
+RUN useradd --create-home --home-dir /home/newsdom --shell /usr/sbin/nologin newsdom
 
-RUN chown -R newsdom:newsdom /app
+COPY --from=builder --chown=newsdom:newsdom /app /app
 
 USER newsdom
 
 EXPOSE 8000
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=5 \
-  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health').read()"
-
 CMD ["uvicorn", "newsdom_api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile.test

@@ -0,0 +1,36 @@
+FROM python:3.10-slim
+
+ENV UV_VERSION=0.11.3
+
+# Install system dependencies
+# Note: We do NOT switch to a non-root user (like `USER ciuser`) here.
+# GitHub Actions runs `container` jobs by bind-mounting workspace and runner temp directories.
+# If the container runs as a non-root user by default, it will not have permission to write
+# to the GitHub Actions runner directories (like /__w/_temp/_runner_file_commands/), causing EACCES errors.
+# @coderabbitai ignore
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libgl1 \
+    libglib2.0-0 \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv (pin to match .github/workflows/tests.yml)
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
+
+ENV PATH="/usr/local/bin:${PATH}"
+
+WORKDIR /app
+
+# Pre-warm dependencies only (source is mounted at runtime by Actions)
+COPY pyproject.toml README.md ./
+COPY src/newsdom_api/__init__.py ./src/newsdom_api/__init__.py
+
+# Install dependencies using uv
+# Install to system Python so that it's accessible without activating a venv
+RUN uv pip install --system -e ".[dev,mineru]"
+
+ENV PYTHONPATH=/app/src
+
+CMD ["pytest"]

README.md

@@ -44,14 +44,13 @@ docker build -t newsdom-api .
 docker run -p 8000:8000 newsdom-api
 ```
 
-The default image exposes the REST API on port `8000` as a lean multi-arch
-service image. It is suitable for `linux/amd64` and `linux/arm64`, including
-Apple Silicon hosts running the API service inside Docker.
+The default image exposes the REST API on port `8000` as a multi-arch service
+image. It is suitable for `linux/amd64` and `linux/arm64`, including Apple
+Silicon hosts running the API service inside Docker.
 
-The lean image is intentionally a REST API shell: `/health`, `/docs`, and
-OpenAPI endpoints are available immediately, while real `/parse` execution
-still requires a compatible MinerU runtime to be available inside the
-container image.
+The default image already includes the MinerU runtime and sets
+`NEWSDOM_MINERU_BIN=mineru`, so `/parse` is available without layering an extra
+OCR package into the container at runtime.
 
 For heavier parsing deployments, build the optional NVIDIA-oriented variant:
 
@@ -75,6 +74,12 @@ provide the CUDA user-space/runtime stack required by MinerU.
 curl -F "file=@sample.pdf" http://127.0.0.1:8000/parse
 ```
 
+Each request is written to a request-scoped temporary directory before MinerU
+runs, and those temporary files are removed after the response completes.
+Sanitized parse failures return `503 MinerU runtime unavailable` when the
+runtime cannot be executed and `502 MinerU output was incomplete` when MinerU
+finishes without the required output artifacts.
+
 ### Run tests
 
 ```bash

docs/operations/deploy-runbook.md

@@ -1,8 +1,9 @@
 # Deploy runbook
 
 This repository does not ship a long-lived production cluster
-definition in-tree, so deployment verification focuses on reproducible
-local and GitHub-hosted delivery paths.
+definition in-tree and has no in-tree Kubernetes manifests, so
+deployment verification focuses on reproducible local and GitHub-hosted
+delivery paths.
 
 ## Local API smoke
 
@@ -17,7 +18,15 @@ local and GitHub-hosted delivery paths.
 
 1. `docker build -t newsdom-api .`
 2. `docker run --rm -p 18080:8000 newsdom-api`
-3. `curl -fsS http://127.0.0.1:18080/health`
+3. Verify:
+   - `curl -fsS http://127.0.0.1:18080/health`
+   - `curl -fsS -F "file=@sample.pdf" http://127.0.0.1:18080/parse`
+
+The default image already includes the MinerU runtime and sets
+`NEWSDOM_MINERU_BIN=mineru`, so container smoke should treat `/parse`
+as part of the supported contract instead of a docs-only shell.
+
+`/health` proves the API process is serving but does not validate a full `/parse` round-trip, MinerU execution, or OCR artifact production.
 
 ## Release smoke
 
@@ -30,5 +39,8 @@ local and GitHub-hosted delivery paths.
 ## Failure handling
 
 - Capture sanitized logs outside `tmp/` when a delivery path fails.
+- Expect `/parse` failures to stay sanitized: `503 MinerU runtime
+  unavailable` when the runtime cannot execute, and `502 MinerU output
+  was incomplete` when required OCR artifacts are missing or invalid.
 - Reconcile the failure against `README.md`, `CHANGELOG.md`, and the
   relevant workflow before closing the task.