bambox 0.1.0__tar.gz

bambox-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy src/bambox
+
+  changelog:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run towncrier check --compare-with origin/main
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run pytest -v
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run pytest --cov=bambox --cov-report=xml -v
+      - uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false

bambox-0.1.0/.github/workflows/prepare-release.yml

@@ -0,0 +1,128 @@
+name: Prepare Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. 0.2.0)"
+        required: true
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Validate version format
+        run: |
+          VERSION="${{ inputs.version }}"
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Invalid version format: $VERSION (expected X.Y.Z)"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install project dependencies
+        run: uv sync --extra dev
+
+      - name: Check version is newer than current
+        run: |
+          VERSION="${{ inputs.version }}"
+          CURRENT=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "Current version: $CURRENT"
+          echo "Target version:  $VERSION"
+          uv run python -c "
+          from packaging.version import Version
+          current = Version('$CURRENT')
+          target = Version('$VERSION')
+          if target <= current:
+              raise SystemExit(f'Target {target} must be newer than current {current}')
+          print(f'OK: {current} → {target}')
+          "
+
+      - name: Check no existing tag
+        run: |
+          VERSION="${{ inputs.version }}"
+          if git ls-remote --tags origin "refs/tags/v${VERSION}" | grep -q .; then
+            echo "::error::Tag v${VERSION} already exists"
+            exit 1
+          fi
+
+      - name: Create or reset release branch
+        run: |
+          VERSION="${{ inputs.version }}"
+          BRANCH="release/v${VERSION}"
+          if git ls-remote --heads origin "refs/heads/${BRANCH}" | grep -q .; then
+            echo "Branch ${BRANCH} already exists — will overwrite"
+          fi
+          git checkout -b "$BRANCH"
+
+      - name: Bump version in pyproject.toml
+        run: |
+          VERSION="${{ inputs.version }}"
+          sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
+          grep "^version = \"${VERSION}\"" pyproject.toml
+
+      - name: Build changelog with towncrier
+        run: |
+          VERSION="${{ inputs.version }}"
+          echo "=== Changelog preview ==="
+          uv run towncrier build --draft --version "$VERSION"
+          echo "========================="
+          uv run towncrier build --version "$VERSION" --yes
+          echo "--- Updated CHANGELOG.md (first 30 lines) ---"
+          head -30 CHANGELOG.md
+
+      - name: Commit and push
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+        run: |
+          VERSION="${{ inputs.version }}"
+          BRANCH="release/v${VERSION}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml CHANGELOG.md changes/
+          git commit -m "Release v${VERSION}"
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"
+          git push --force origin "$BRANCH"
+
+      - name: Create or update pull request
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+        run: |
+          VERSION="${{ inputs.version }}"
+          BRANCH="release/v${VERSION}"
+
+          CHANGELOG_BODY=$(awk "/^## ${VERSION//./\\.} /{found=1; next} /^## /{if(found) exit} found{print}" CHANGELOG.md)
+
+          PR_BODY="$(cat <<EOF
+          ## Release v${VERSION}
+
+          ${CHANGELOG_BODY}
+
+          ---
+          **Merge this PR to trigger the release pipeline.**
+          The release workflow will auto-tag \`v${VERSION}\`, build all artifacts, validate on TestPyPI, then publish to PyPI.
+          EOF
+          )"
+
+          EXISTING_PR=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null || echo "")
+
+          if [[ -n "$EXISTING_PR" ]]; then
+            echo "Updating existing PR #${EXISTING_PR}"
+            gh pr edit "$EXISTING_PR" \
+              --title "Release v${VERSION}" \
+              --body "$PR_BODY"
+          else
+            gh pr create \
+              --title "Release v${VERSION}" \
+              --body "$PR_BODY" \
+              --base main \
+              --head "$BRANCH"
+          fi

bambox-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,218 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag (e.g. v0.2.0) — use only as fallback"
+        required: true
+
+jobs:
+  # ── Detect release PR merge on push to main ─────────────────────────
+  detect-release:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    outputs:
+      is_release: ${{ steps.check.outputs.is_release }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - name: Check if this is a release PR merge
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          SHA="${{ github.sha }}"
+          echo "Checking commit $SHA for associated release PR..."
+
+          BRANCHES=$(gh api "repos/${{ github.repository }}/commits/${SHA}/pulls" \
+            --jq '.[].head.ref')
+          echo "Associated PR branches: ${BRANCHES:-<none>}"
+
+          VERSION=$(echo "$BRANCHES" \
+            | grep -oP '^release/v\K\d+\.\d+\.\d+$' \
+            | head -1 || true)
+
+          if [[ -n "$VERSION" ]]; then
+            if gh api "repos/${{ github.repository }}/git/refs/tags/v${VERSION}" >/dev/null 2>&1; then
+              echo "::warning::Tag v${VERSION} already exists — skipping"
+              echo "is_release=false" >> "$GITHUB_OUTPUT"
+            else
+              echo "is_release=true" >> "$GITHUB_OUTPUT"
+              echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+              echo "::notice::Detected release PR merge for v${VERSION}"
+            fi
+          else
+            echo "is_release=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  # ── Verify version ──────────────────────────────────────────────────
+  version:
+    needs: detect-release
+    if: |
+      always() &&
+      ((needs.detect-release.outputs.is_release == 'true') ||
+       github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Extract and verify version
+        id: version
+        run: |
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            VERSION="${{ needs.detect-release.outputs.version }}"
+          else
+            TAG="${{ inputs.tag }}"
+            VERSION="${TAG#v}"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+          TOML_VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [[ "$TOML_VERSION" != "$VERSION" ]]; then
+            echo "::error::Version mismatch: pyproject.toml=$TOML_VERSION, release=$VERSION"
+            exit 1
+          fi
+          echo "::notice::Releasing version $VERSION"
+
+  # ── Build package ───────────────────────────────────────────────────
+  build-pypi:
+    needs: version
+    if: always() && needs.version.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build and validate package
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: pypi-dist
+          path: dist/
+          retention-days: 5
+
+  # ── Dry-run: validate on TestPyPI before real publish ───────────────
+  dry-run-publish:
+    needs: [version, build-pypi]
+    if: always() && needs.version.result == 'success' && needs.build-pypi.result == 'success'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to TestPyPI (dry-run gate)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  # ── Create tag only after TestPyPI succeeds ─────────────────────────
+  create-tag:
+    needs: [version, detect-release, dry-run-publish]
+    if: |
+      always() &&
+      needs.version.result == 'success' &&
+      needs.dry-run-publish.result == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Create and push tag (if it doesn't exist)
+        run: |
+          VERSION="${{ needs.version.outputs.version }}"
+          if gh api "repos/${{ github.repository }}/git/refs/tags/v${VERSION}" >/dev/null 2>&1; then
+            echo "::notice::Tag v${VERSION} already exists — skipping"
+          else
+            git tag "v${VERSION}"
+            git push origin "v${VERSION}"
+            echo "::notice::Created tag v${VERSION}"
+          fi
+
+  # ── Publish to PyPI ─────────────────────────────────────────────────
+  publish-pypi:
+    needs: [version, create-tag, dry-run-publish]
+    if: |
+      always() &&
+      needs.dry-run-publish.result == 'success' &&
+      (needs.create-tag.result == 'success' || needs.create-tag.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  # ── Create GitHub Release ───────────────────────────────────────────
+  github-release:
+    needs: [version, publish-pypi]
+    if: |
+      always() &&
+      needs.version.result == 'success' &&
+      needs.publish-pypi.result == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - uses: actions/download-artifact@v7
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION="${{ needs.version.outputs.version }}"
+          BODY=$(awk "/^## ${VERSION//./\\.} /{found=1; next} /^## /{if(found) exit} found{print}" CHANGELOG.md)
+          echo "$BODY" > /tmp/release-body.md
+          echo "Changelog body:"
+          cat /tmp/release-body.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ needs.version.outputs.version }}"
+          WHEEL=$(ls dist/*.whl 2>/dev/null | head -1)
+          ARGS=(gh release create "v${VERSION}" --title "v${VERSION}" --notes-file /tmp/release-body.md)
+          if [[ -n "$WHEEL" ]]; then
+            ARGS+=("$WHEEL")
+          fi
+          "${ARGS[@]}"

bambox-0.1.0/.github/workflows/test-pypi.yml

@@ -0,0 +1,58 @@
+name: Publish to TestPyPI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test-publish:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Skip if this is a release PR merge
+        id: release
+        if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH=$(gh api "repos/${{ github.repository }}/commits/${{ github.sha }}/pulls" \
+            --jq '.[0].head.ref' 2>/dev/null || echo "")
+          if [[ -z "$BRANCH" ]]; then
+            echo "::warning::Could not determine PR branch — proceeding"
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          elif [[ "$BRANCH" =~ ^release/v ]]; then
+            echo "::notice::Release PR merge — skipping (release.yml handles publishing)"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up Python
+        if: steps.release.outputs.skip != 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build dev package for TestPyPI
+        if: steps.release.outputs.skip != 'true'
+        run: |
+          pip install build
+          VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          COMMIT_COUNT=$(git rev-list --count HEAD)
+          DEV_VERSION="${VERSION}.dev${COMMIT_COUNT}"
+          sed -i "s/version = \"$VERSION\"/version = \"$DEV_VERSION\"/" pyproject.toml
+          python -m build
+
+      - name: Publish to TestPyPI
+        if: steps.release.outputs.skip != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true

bambox-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

bambox-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to bambox are documented here.
+This changelog is managed by [towncrier](https://towncrier.readthedocs.io/).
+
+<!-- towncrier release notes start -->
+
+## 0.1.0 — 2026-03-15
+
+Initial release of bambox as a standalone library.
+
+### Features
+
+- Core `.gcode.3mf` archive packaging with Bambu Connect compatibility
+- Template-driven 544-key `project_settings.config` generation from JSON profiles
+- Machine base profile for P1S with filament overlays (PLA, ASA, PETG-CF)
+- Automatic array padding and missing-key fixup for Bambu Connect firmware
+- Cloud printing via Docker bridge (`estampo/cloud-bridge`) with bind-mount and baked fallback
+- AMS tray mapping and printer status querying
+- OrcaSlicer-to-Jinja2 template syntax conversion and rendering
+- G-code component assembly (start + toolpath + end templates)
+- CuraEngine Docker slicer backend prototype
+- Synthetic toolpath generator for testing
+- G-code-to-PNG thumbnail rendering (top-down view with bounding box)
+- CLI with `pack`, `print`, and `status` commands
+- MD5 checksum validation matching Bambu Connect requirements
+- Support for both OrcaSlicer 2.3.1 and BambuStudio 2.5.0.66 format versions

bambox-0.1.0/CLAUDE.md

@@ -0,0 +1,74 @@
+# bambox - Claude Code Instructions
+
+## Working with the maintainer
+The project maintainer is technically experienced and understands the codebase deeply. Trust their judgement. Don't second-guess their observations or explain things they already know.
+
+## Pre-PR Checklist (MANDATORY)
+Before pushing any PR branch, always run locally:
+1. `uv run ruff check src tests` — lint must pass with zero errors
+2. `uv run ruff format --check src tests` — formatting must pass (run `uv run ruff format src tests` to auto-fix)
+3. `uv run mypy src/bambox` — type check must pass with zero errors
+4. `uv run pytest` — all tests must pass
+
+Do NOT push a PR until all four checks pass locally.
+
+## Changelog (MANDATORY)
+Every PR must include a **towncrier fragment file** in the `changes/` directory:
+1. Create a file: `changes/<PR-number>.<type>` where type is `feature`, `bugfix`, or `misc`
+2. Write a single line — concise, user-facing description of the change
+3. If the PR has no number yet, use `+descriptive-name.<type>` (orphan fragment)
+4. Do NOT edit CHANGELOG.md directly — towncrier compiles fragments at release time
+
+## Module Ownership (enforce strictly)
+
+Each module has a defined scope. Do not add logic to the wrong module — even if it seems convenient.
+
+| Module | Owns | Must NOT contain |
+|--------|------|-----------------|
+| `pack.py` | Core .gcode.3mf archive construction, XML metadata, MD5 checksums, Bambu Connect fixup | Settings generation, slicer logic, printer communication |
+| `settings.py` | 544-key project_settings builder, profile loading, filament overlay, array broadcasting | G-code generation, archive packing, printer logic |
+| `bridge.py` | Cloud printing via Docker bridge, credential loading, AMS tray mapping, printer status | Archive construction, settings generation, slicer invocation |
+| `cli.py` | Typer commands (pack, print, status), argument parsing, user-facing output | Business logic — delegate to pack/bridge/settings |
+| `cura.py` | CuraEngine Docker invocation, profile conversion, start/end G-code injection | OrcaSlicer logic, archive packing, printer communication |
+| `templates.py` | OrcaSlicer→Jinja2 syntax conversion, template rendering | G-code generation, settings logic |
+| `toolpath.py` | Synthetic toolpath generation for testing | Production G-code, slicer invocation |
+| `thumbnail.py` | G-code→PNG rendering (top-down view, bounding box) | Archive packing, settings |
+| `assemble.py` | G-code component assembly (start + toolpath + end) | Slicer invocation, template rendering |
+
+## Architecture: Key Decisions
+
+### Template-Driven Settings (544 keys)
+Bambu printers require a `project_settings.config` with ~544 keys in the .gcode.3mf archive. Rather than passing slicer output through, bambox builds this from:
+1. Machine base profile (e.g. `base_p1s.json` — 544 keys)
+2. Filament type profiles (`filament_pla.json`, etc. — per-type overrides)
+3. `_varying_keys.json` — keys that differ per filament slot
+4. `_uniform_array_keys.json` — scalars that must be broadcast to arrays
+
+Do NOT modify `fixup_project_settings()` without understanding the array padding and key fixup logic — it ensures Bambu Connect firmware acceptance.
+
+### Docker Bridge Pattern
+Cloud printing wraps `estampo/cloud-bridge:bambu-*` Docker image. Two modes:
+1. **Bind-mount** (primary) — mounts .gcode.3mf via `-v`
+2. **Baked fallback** — for sandboxed/DinD environments, builds temp image with COPY
+
+### Bambu Connect Compatibility
+The archive format is validated by printer firmware. Key constraints:
+- MD5 checksums must match file contents
+- Per-filament arrays must be padded to exactly 5 slots (P1S)
+- Both OrcaSlicer 2.3.1 and BambuStudio 2.5.0.66 format versions supported
+
+## What bambox is NOT
+
+- **Not a slicer.** It packages G-code produced by slicers. The CuraEngine integration in `cura.py` invokes an external engine — it does not implement slicing.
+- **Not a printer API client.** It wraps the Docker bridge for cloud printing. The actual protocol implementation lives in the bridge binary (C++ today, Rust planned).
+- **Not estampo.** estampo is the pipeline orchestrator. bambox is the Bambu Lab packaging library that estampo depends on. Do not add pipeline, DAG, or orchestration logic here.
+- **Not a profile editor.** It loads and overlays profiles. Do not build profile editing or merging UI.
+
+## Relationship to estampo
+
+bambox is one piece of a three-project architecture:
+- **estampo** — pipeline orchestrator, slicer-agnostic
+- **bambox** — BBL .gcode.3mf packaging + G-code templates + settings generation
+- **bambu-cloud** (planned) — printer communication
+
+Per estampo ADR-005, bambox will absorb printer code from estampo at v0.4.0. See `docs/bridge-migration-plan.md` for the Rust bridge migration plan.

bambox-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to bambox
+
+## Development setup
+
+```bash
+git clone https://github.com/estampo/bambox.git
+cd bambox
+uv sync --extra dev
+```
+
+## Before submitting a PR
+
+Run all four checks locally:
+
+```bash
+uv run ruff check src tests        # lint
+uv run ruff format --check src tests  # formatting
+uv run mypy src/bambox          # type check
+uv run pytest                      # tests
+```
+
+Auto-fix formatting: `uv run ruff format src tests`
+
+## Changelog fragments
+
+Every PR must include a towncrier fragment file in `changes/`:
+
+```bash
+# Format: changes/<PR-number>.<type>
+# Types: feature, bugfix, misc
+echo "Add support for A1 Mini base profile" > changes/42.feature
+```
+
+If you don't have a PR number yet, use an orphan fragment:
+
+```bash
+echo "Fix array padding for single-filament prints" > changes/+fix-padding.bugfix
+```
+
+Do **not** edit `CHANGELOG.md` directly.
+
+## Code style
+
+- Line length: 100 characters (ruff)
+- Type hints on all public functions
+- `from __future__ import annotations` in every module
+- No unnecessary comments or docstrings on private helpers
+
+## Module boundaries
+
+See `CLAUDE.md` for the module ownership table. Each module has a defined scope — don't add logic to the wrong module.
+
+## Tests
+
+- Tests live in `tests/` and mirror source module names
+- Use `tmp_path` fixture for file I/O tests
+- Reference fixtures (`tests/fixtures/`) are Bambu Connect-validated archives