Setup and maintenance update

.coveragerc

@@ -0,0 +1,13 @@
+[paths]
+source =
+    src/crane_controller
+    */site-packages/crane_controller
+
+[run]
+source = crane_controller
+branch = True
+
+[report]
+fail_under = 10.0
+show_missing = True
+skip_covered = True

.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1,36 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto
+
+# Explicitly declare text files you want to always be normalized and converted
+# to native line endings on checkout.
+*.py text
+*.cpp text
+*.hpp text
+*.c text
+*.h text
+*.json text
+*.xml text
+*.txt text
+*.yml text
+*.yaml text
+*.toml text
+*.rst text
+*.ini text
+
+# Declare files that will always have CRLF line endings on checkout.
+*.vcproj text eol=crlf
+*.sln text eol=crlf
+*.md text eol=crlf
+
+# Declare files that will always have LF line endings on checkout.
+*.sh text eol=lf
+
+# Declare files that will not be normalized regardless of their content.
+*.jpg -text
+*.png -text
+*.gif -text
+*.ico -text
+
+# Denote all files that are truly binary and should not be modified.
+*.onnx binary
+*.fmu binary

.github/copilot-instructions.md

@@ -0,0 +1,98 @@
+# GitHub Copilot – Project Instructions
+
+This repository uses a **hybrid instruction model**:
+
+- **Portable, tool-agnostic rules live in the repository root**
+- **GitHub-specific scoping and activation live under `.github/`**
+
+GitHub Copilot and GitHub Agents must treat the files below as the
+authoritative source of project behavior.
+
+---
+
+## Primary Instruction Sources (Authoritative)
+
+Always load and follow these files first:
+
+- `/.instructions.md`
+  Project-wide engineering rules, quality standards, and constraints.
+
+- `/.prompt.md`
+  Default working style and agent execution discipline.
+
+- `/plans/plan.md` or `/plans/plan-draft.md` (when present)
+  Explicit plan / orchestration artifact for Plan Mode workflows.
+  The presence of `/plans/plan.md` or `/plans/plan-draft.md` indicates that a plan-first workflow is expected.
+  `/plans/.plan.md` serves as a template and should not be modified directly.
+
+These files form the **knowledge contract** for this repository and
+are reviewed and maintained like production code.
+
+---
+
+## GitHub-Scoped Instructions (Additive)
+
+Additional GitHub-specific guidance MAY apply from:
+
+- `.github/instructions/*.instructions.md`
+  Narrow, scoped rules using `applyTo` (must not contradict root rules).
+
+- `.github/prompts/*.prompt.md`
+  Reusable GitHub workflows (feature implementation, reviews, refactors).
+
+- `.github/agents/*.agent.md`
+  Named agent personas, if explicitly activated.
+
+GitHub-scoped files **refine or specialize** behavior.
+They must never redefine or override the intent of `/.instructions.md`.
+
+---
+
+## Precedence & Conflict Resolution
+
+If multiple instructions apply, resolve conflicts in this order:
+
+1. Scoped `.github/instructions/*.instructions.md` (most specific — may only **narrow or refine** root rules, never override or contradict them)
+2. `/.instructions.md`
+3. `/.prompt.md`
+
+When in doubt:
+- Prefer correctness, testability, and clarity over speed
+- Ask for clarification rather than guessing
+
+---
+
+## Safety & Boundaries
+
+- Work only within this repository
+- Do not assume network or internet access unless explicitly stated
+- Do not introduce hidden side effects, hooks, or background behavior
+- Do not change unrelated code opportunistically
+
+All agent output is subject to human review and normal PR processes.
+
+---
+
+## Agent Operating Mode
+
+Use a **plan-first workflow** by default:
+
+1. Restate the task and assumptions
+2. Produce or update `plan.md` (unless instructed otherwise)
+3. Wait for confirmation if scope is ambiguous
+4. Implement incrementally
+5. Verify with tests
+6. Summarize changes and remaining risks
+
+This discipline is mandatory for non-trivial changes.
+
+---
+
+## Intentional Non-Goals
+
+- This file does **not** contain detailed coding rules
+  (those belong in `/.instructions.md`)
+- This file does **not** encode organization policy or governance logic
+- This file avoids duplication by design
+
+Less is intentional. Stability is a feature.

.github/workflows/_build_and_publish_documentation.yml

@@ -0,0 +1,107 @@
+name: Build and publish documentation
+
+on: workflow_call
+
+env:
+  DEFAULT_BRANCH: 'release'
+  #SPHINXOPTS: '-W --keep-going -T'
+  # ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings
+
+jobs:
+  build-and-publish-docs:
+    name: Build and publish documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout active branch
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+      - name: Install the project
+        run: uv sync --frozen
+      - name: Print debugging information
+        run: |
+          echo "github.ref:" ${{github.ref}}
+          echo "github.event_name:" ${{github.event_name}}
+          echo "github.head_ref:" ${{github.head_ref}}
+          echo "github.base_ref:" ${{github.base_ref}}
+          set -x
+          git rev-parse --abbrev-ref HEAD
+          git branch
+          git branch -a
+          git remote -v
+          uv run python -V
+          uv pip list
+
+      # Build documentation
+      - uses: sphinx-doc/github-problem-matcher@master
+      - name: Build documentation
+        run: |
+          cd docs
+          uv run make html
+
+      - name: Clone and cleanup gh-pages branch
+        run: |
+          set -x
+          git fetch
+          ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
+          rm -rf _gh-pages/.git/
+          mkdir -p _gh-pages/branch/
+
+      # Delete orphaned branch-folders:
+      # Go through each subfolder in _gh-pages/branch/
+      # If it relates to an orphaned branch, delete it.
+      - name: Delete orphaned branch-folders
+        run: |
+          set -x
+          for brdir in `ls _gh-pages/branch/` ; do
+              brname=${brdir//--/\/}   # replace '--' with '/'
+              if ! git show-ref remotes/origin/$brname ; then
+                  echo "Removing $brdir"
+                  rm -r _gh-pages/branch/$brdir/
+              fi
+          done
+
+      # Copy documentation to _gh-pages/  (if push happened on release branch)
+      - name: Copy documentation to _gh-pages/
+        if: |
+          contains(github.ref, env.DEFAULT_BRANCH)
+        run: |
+          set -x
+          # Delete everything under _gh-pages/ that is from the
+          # primary branch deployment.  Excludes the other branches
+          # _gh-pages/branch-* paths, and not including
+          # _gh-pages itself.
+          find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
+          rsync -a docs/build/html/ _gh-pages/
+
+      # Copy documentation to _gh-pages/branch/$brname  (if push happened on any other branch)
+      # ('/' gets replaced by '--')
+      - name: Copy documentation to _gh-pages/branch/${{github.ref}}
+        if: |
+          !contains(github.ref, env.DEFAULT_BRANCH)
+        run: |
+          set -x
+          #brname=$(git rev-parse --abbrev-ref HEAD)
+          brname="${{github.ref}}"
+          brname="${brname##refs/heads/}"
+          brdir=${brname//\//--}   # replace '/' with '--'
+          rm -rf   _gh-pages/branch/${brdir}
+          rsync -a docs/build/html/ _gh-pages/branch/${brdir}
+
+      # Add .nojekyll file
+      - name: Add .nojekyll file
+        run: touch _gh-pages/.nojekyll
+
+      # Publish: Commit gh-pages branch and publish it to GitHub Pages
+      - name: Publish documentation
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _gh-pages/
+          force_orphan: true

.github/workflows/_build_package.yml

@@ -0,0 +1,29 @@
+name: Build Package
+
+on: workflow_call
+
+jobs:
+  build:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+      - name: Build source distribution and wheels
+        run: uv build
+      - name: Check build artifacts
+        run: uvx twine check --strict dist/*
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: |
+            dist/*.tar.gz
+            dist/*.whl

.github/workflows/_code_quality.yml

@@ -0,0 +1,68 @@
+name: Code Quality
+
+on: workflow_call
+
+jobs:
+  ruff_format:
+    runs-on: ubuntu-latest
+    name: ruff format
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+      - name: Install the project
+        run: uv sync -U
+      - name: Run ruff format
+        run: uv run ruff format --diff
+
+  ruff_check:
+    runs-on: ubuntu-latest
+    name: ruff check
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+      - name: Install the project
+        run: uv sync -U
+      - name: Run ruff check
+        run: uv run ruff check --diff
+
+  pyright:
+    runs-on: ubuntu-latest
+    name: pyright
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+      - name: Install the project
+        run: uv sync -U
+      - name: Run pyright
+        run: uv run pyright
+
+  mypy:
+    runs-on: ubuntu-latest
+    name: mypy
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: 'uv.lock'
+      - name: Install the project
+        run: uv sync -U
+      - name: Run mypy
+        run: uv run mypy

.github/workflows/_merge_into_release.yml

@@ -0,0 +1,26 @@
+name: Merge into release
+
+on:
+  workflow_call:
+    secrets:
+      RELEASE_TOKEN:
+        required: true
+
+jobs:
+  merge_into_release:
+    name: Merge ${{ github.event.ref }} -> release branch
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          # Fetch the whole history to prevent unrelated history errors
+          fetch-depth: 0
+          # The branch you want to checkout (usually equal to `branchtomerge`)
+          # ref: ${{ github.event.ref }}
+      - uses: devmasx/merge-branch@v1.4.0
+        with:
+          type: now
+          target_branch: release
+          github_token: ${{ secrets.RELEASE_TOKEN }}