Phase 0 — Containerize the CLI

Status: ✅ DONE (2026-06-17). step-parser:dev builds for linux/amd64 and all three sample assemblies (MR16/MR27/MR28) pass the full pipeline — load, BOM .xlsx, 6-view OSMesa thumbnails, geometry query, and dimensional-diagram SVG. Validated on a Mac (arm64) via QEMU emulation; image arch confirmed x86_64. Deps frozen in requirements.lock.txt. Two fixes were required (see Fixes applied below).

Goal: prove the heavy native stack runs on linux/amd64 (the Unraid target) before any web code is written. This is the highest-risk part of the step-parser roadmap; everything after it is conventional React-on-FastAPI.

What's being de-risked:

Path	Library	Container concern
STEP load + geometry	build123d → cadquery-ocp (OpenCASCADE)	manylinux x86_64 wheels; OCC needs GL/X11/OpenMP runtime libs
6-view thumbnails	trimesh + pyrender	offscreen GL with no GPU → forced onto OSMesa software rasterizer
Dimensional diagram	cairosvg	cairo / pango / gdk-pixbuf system libs
BOM	pandas + openpyxl	none
Translation	anthropic (Claude API)	network + `ANTHROPIC_API_KEY` (skipped in this phase)

Files (all in repo root, `skill.src/` untouched)

Dockerfile — python:3.11-slim-bookworm, amd64-pinned, OSMesa + cairo system libs
requirements.txt — Python deps (floor pins; freeze to a lockfile after first green build)
.dockerignore — keeps .step samples, drops caches and pre-generated outputs
.env.example — ANTHROPIC_API_KEY (translation only)
build.sh — buildx build for linux/amd64 (+ registry push hints)
smoke-test.sh — runs MR16/MR27/MR28 through BOM + query + diagram; checks artifacts

Run it (on a Docker host)

Docker is not installed on the dev Mac this was authored on, and it's arm64. The build runs anywhere with Docker + buildx: Unraid itself, or a Mac/PC with Docker Desktop. From arm64 the amd64 build uses QEMU emulation (slow first time; the OpenCASCADE wheel is large).

./build.sh          # → step-parser:dev (linux/amd64)
./smoke-test.sh     # → _phase0_out/ with xlsx, pngs, svg per sample

Ad-hoc single file:

docker run --rm -v "$PWD/_phase0_out:/data" step-parser:dev "/data/MyPart.step" --no-translate

Pass criteria

For each of the three samples the smoke test must produce, with a clean exit:

*_bom.xlsx (kernel loaded + assembly traversed + Excel written)
at least one *_<view>.png (pyrender succeeded under OSMesa — the riskiest item)
*__external-diagram.svg (cairosvg succeeded)

All three green ⇒ Phase 0 done. Freeze the lockfile and move to Phase 1 (FastAPI wrapper).

Fixes applied during Phase 0

PyOpenGL / OSMesa version clash (packaging). pyrender 0.1.45 hard-pins PyOpenGL==3.1.0, but the OSMesa offscreen backend needs OSMesaCreateContextAttribs (added in PyOpenGL ≥3.1.5). The Dockerfile installs pyrender's pin, then force-upgrades with pip install --no-deps --upgrade "PyOpenGL==3.1.7" (leaves pyrender untouched, avoids the resolver conflict). Without this, all 6 renders fail with an ImportError.
external_diagram.py line 318 KeyError: 'position' (source bug). _arrange_views() returns view dicts keyed ox/oy, but the layout map read a non-existent position key — crashed the diagram on any platform. Fixed to {v["name"]: (v["ox"], v["oy"]) ...}.

Known follow-ups (deferred, out of Phase 0 scope)

Active-area detection is a no-op on Linux. external_diagram.py imports OCC.Core.* (pythonocc-core) for active-area detection, but the loader uses build123d's OCP kernel. The import fails and is caught (logged as a warning) — the diagram still renders, just without the auto-detected active-area dimension. Porting OCC → OCP is a Phase 1 task.
Pin to the lockfile for reproducible Unraid builds. requirements.lock.txt is frozen; switch the Dockerfile's COPY requirements.txt / install line to it when convenient.
FreeCAD fallback is macOS-only right now. skill.src/modules/loader.py hardcodes /Applications/FreeCAD.app/..., so on Linux the fallback no-ops and returns None. build123d is the primary path and should handle the samples; wiring a Linux freecadcmd fallback means editing loader.py and is left for later.
Lockfile. Replace the floor pins with requirements.lock.txt once the build is green.
OSMesa is CPU rendering. Fine for correctness validation; thumbnail speed on the ~25 MB sample assemblies is a Phase 1+ concern. The roadmap's recommended pivot — export GLB and render client-side with three.js — sidesteps server GL for the live viewer.

4.7 KiB Raw Blame History