labtrail 0.1.0__tar.gz

labtrail-0.1.0/.forgejo/workflows/ci.yml

@@ -0,0 +1,385 @@
+# fvutils/labtrail -- Forgejo Actions.
+#
+# COPY THIS AS A PAIR. Its counterpart is .github/workflows/ci.yml. Derived
+# from dvkit/forgejo-ops templates/ci.forgejo.yml; see that repo's
+# templates/README.md.
+#
+# The two files differ in the `authority ==` comparison, in the Forgejo runner
+# constraints below, and in nothing else. If you are changing anything else,
+# they are drifting.
+#
+# ---------------------------------------------------------------------------
+# DECISION, 2026-08-30 (inherited from the estate template): publish jobs FAIL
+# CLOSED on an unreachable switch.
+#
+# If https://dvkit.org/.well-known/release-authority.json cannot be fetched ON A
+# TAG, the gate fails and nothing publishes. A release blocked by an outage is
+# recoverable; a release published twice from two forges is not.
+# ---------------------------------------------------------------------------
+#
+# FORGEJO RUNNER CONSTRAINTS -- all measured on this instance, not assumed.
+# `runs-on: ubuntu-latest` maps to catthehacker/ubuntu:act-22.04.
+#
+#   * Python is 3.10, and pip is 22.0.2 -- which PREDATES PEP 660, so
+#     `pip install -e .` fails outright on a pyproject-only project. Every job
+#     here opens with a venv whose pip has been upgraded, put on PATH so the
+#     steps below are textually identical to the GitHub side.
+#   * `python` unqualified DOES NOT EXIST. Use python3 (before the venv is on
+#     PATH; after it, `python` is the venv's).
+#   * NO THIRD-PARTY ACTIONS. A bare `uses:` resolves against code.forgejo.org,
+#     not github.com -- so actions/setup-python and pypa/gh-action-pypi-publish
+#     are unavailable. actions/checkout and forgejo/upload-artifact DO resolve.
+#     Publishing is plain twine, which also keeps GitHub off the critical path
+#     of a release.
+#   * 3.10 is labtrail's declared floor, so the single runner Python is the
+#     more interesting half of the GitHub matrix rather than a compromise.
+#
+# Trial-run any step you add before landing it:
+#   docker run --rm -v "$PWD:/w" -w /w catthehacker/ubuntu:act-22.04 bash -c '<steps>'
+#
+# LABTRAIL-SPECIFIC DIVERGENCE FROM THE TEMPLATE: the template stamps a version
+# by `sed`-ing a `SUFFIX = ""` line in a version file. labtrail has no such
+# file -- setuptools-scm derives the version from git. See "Stamp the build
+# version" below, which diverges in the safer direction.
+
+name: CI
+
+on:
+  push:
+    branches: ['**']
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 5 * * *'
+
+jobs:
+  # ---------------------------------------------------------------- gate ----
+  gate:
+    # Release master switch. Identical to the GitHub side except for what the
+    # publish job compares the answer against. `if:` on a job cannot reference
+    # a step in its own job, so the switch is resolved here and consumed
+    # through needs.gate.outputs.authority.
+    name: Release authority
+    runs-on: ubuntu-latest
+    outputs:
+      authority: ${{ steps.resolve.outputs.authority }}
+    steps:
+      - id: resolve
+        # One line on purpose: a multi-line `python3 -c` has to start at column
+        # 0, which terminates the YAML block scalar and silently corrupts the
+        # workflow.
+        run: |
+          url=https://dvkit.org/.well-known/release-authority.json
+          if ! body=$(curl -fsS --max-time 10 "$url"); then
+            case "$GITHUB_REF" in
+              refs/tags/v*)
+                echo "::error::release-authority switch unreachable; refusing to publish"
+                exit 1 ;;
+              *)
+                echo "authority=none" >> "$GITHUB_OUTPUT"
+                echo "switch unreachable on a non-tag ref; nothing to release"
+                exit 0 ;;
+            esac
+          fi
+          auth=$(printf '%s' "$body" | python3 -c 'import json,os,sys; d=json.load(sys.stdin); r=os.environ["GITHUB_REPOSITORY"]; print(d["repos"].get(r) or d["orgs"].get(r.split("/")[0]) or d["default"])')
+          echo "release authority for $GITHUB_REPOSITORY: $auth"
+          echo "authority=$auth" >> "$GITHUB_OUTPUT"
+
+  # ---------------------------------------------------------------- test ----
+  test:
+    name: Test
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm needs the history, and so does the suite: every
+          # fixture builds a real repository.
+          fetch-depth: 0
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+      - name: Install
+        run: pip install -e '.[dev]'
+      - name: doctor
+        # R6.2: doctor runs first so an environment failure is distinguishable
+        # from a content failure at a glance.
+        run: labtrail doctor
+      - name: Unit and integration tests
+        run: pytest tests/unit tests/integration -m 'not slow and not external' -q
+      - name: Acceptance tests
+        run: pytest tests/acceptance -m 'not external' -q
+      - uses: forgejo/upload-artifact@v4
+        if: always()
+        with:
+          name: ctrf
+          path: build/ctrf/
+          if-no-files-found: ignore
+
+  # --------------------------------------------------------- skill-sync ----
+  skill-sync:
+    # R3.3/D-7: the four agent skills are generated from the prose in docs/.
+    # Two copies of a convention drift, and the drift is invisible until an
+    # agent confidently follows the stale one. Regenerate and diff.
+    name: Skills match the prose
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+      - run: pip install -e '.[dev]'
+      - run: labtrail-dev gen-skill
+      - run: git diff --exit-code -- src/labtrail/share/skills/
+
+  # ---------------------------------------------------- docs-conventions ----
+  docs-conventions:
+    # R2.22.1/R2.22.3: every documented start-point fully qualified, every
+    # worktree add carrying -b. Cheap grep; the failure mode is silent -- a
+    # documented command that quietly puts a learner on a published branch.
+    name: Documented git spellings
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+      - run: pip install -e '.[dev]'
+      - run: pytest tests/unit/test_doc_conventions.py -q
+
+  # ---------------------------------------------------------------- docs ----
+  docs:
+    name: Documentation
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+      - run: pip install -e '.[dev]' sphinx myst-parser
+      # -W so a broken reference fails the build. graphviz is *configured* in
+      # conf.py for sphinx-labtrail (M9) but no page in this repo uses a
+      # directive, so the binary is not installed here.
+      - run: sphinx-build -W -b html docs docs/_build/html
+      - uses: forgejo/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/_build/html
+
+  # --------------------------------------------------------------- build ----
+  build:
+    name: Build and check the distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for internal identifiers in tracked files
+        # This repo is published to git.dvkit.org, so anything committed here
+        # is public. Internal host names, tailnet addresses and CGNAT-range IPs
+        # must not appear in tracked files -- if a build ever needs one, it
+        # belongs in a repository secret, which is masked in logs. This applies
+        # to documentation and comments, not just code.
+        run: |
+          pattern='perch-char\.ts\.net|\.ts\.net|a9550|100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\.[0-9]+\.[0-9]+'
+          if git grep -nIE "$pattern" -- . ':!.forgejo/workflows/ci.yml' ; then
+            echo "::error::internal identifier found in a tracked file (see matches above)"
+            exit 1
+          fi
+          echo "OK: no internal identifiers in tracked files"
+
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+
+      - name: Stamp the build version
+        # Tag builds keep the clean number. EVERYTHING ELSE gets a PEP 440
+        # local version segment, which PyPI rejects outright -- so an
+        # accidental upload of a CI artifact fails at the tool rather than
+        # succeeding quietly.
+        #
+        #   0.1.dev4+fj.r12.g7775f37
+        #            └─ WHICH FORGE. $GITHUB_RUN_ID is not unique across them:
+        #               GitHub's is an 11-digit global counter, Forgejo's a
+        #               per-repo index that restarts if the instance is
+        #               rebuilt. The run id alone collides.
+        #
+        # DIVERGENCE FROM THE TEMPLATE: there is no version file to sed.
+        # setuptools-scm computes the public version from the tag history, and
+        # we append only the local segment. That is the safer direction --
+        # the base cannot disagree with the tag, because it is derived from it.
+        run: |
+          pip install --upgrade build twine setuptools-scm
+          case "$GITHUB_REF" in
+            refs/tags/*)
+              echo "tag build -- setuptools-scm will use the tag verbatim"
+              ;;
+            *)
+              # `python -m setuptools_scm` reads THIS project's configuration,
+              # so the base agrees with what the build itself will compute.
+              # A hand-rolled get_version() call does not: without pyproject's
+              # fallback_version it answers 0.1.dev1 where the build answers
+              # 0.0.1.dev1. Everything from '+' is the local segment setuptools-scm
+              # would have added; we replace it with ours.
+              public=$(python -m setuptools_scm | sed 's/+.*//')
+              stamp="${public}+fj.r${GITHUB_RUN_ID}.g$(git rev-parse --short=7 HEAD)"
+              echo "stamping $stamp"
+              echo "SETUPTOOLS_SCM_PRETEND_VERSION=$stamp" >> "$GITHUB_ENV"
+              ;;
+          esac
+
+      - name: Build sdist and wheel
+        run: |
+          rm -rf dist/
+          python -m build
+          twine check dist/*
+          ls -la dist/
+
+      - name: Smoke-test the wheel
+        # Against the built wheel in a clean venv, not the source tree: the
+        # repo suite puts src/ on sys.path, so it can never tell you whether
+        # what SHIPS works. R8.5 (the entry points) and R3.6 (the skills are
+        # inside the package) are exactly the things a packaging mistake
+        # breaks and no source-tree test would notice.
+        run: |
+          python3 -m venv /tmp/wheelenv
+          /tmp/wheelenv/bin/pip install -q --upgrade pip
+          /tmp/wheelenv/bin/pip install -q "$(ls dist/*.whl)"
+          cd /tmp        # out of the source tree, so nothing shadows the wheel
+          /tmp/wheelenv/bin/labtrail --version
+          /tmp/wheelenv/bin/labtrail --help > /dev/null
+          /tmp/wheelenv/bin/labtrail-dev --help > /dev/null
+          /tmp/wheelenv/bin/python -c '
+          import os
+          from importlib.metadata import entry_points
+          eps = {e.name: e for e in entry_points(group="agent.skills")}
+          assert eps, "no agent.skills entry points in the installed wheel"
+          for name, ep in sorted(eps.items()):
+              (d,) = ep.load()()
+              assert os.path.basename(d) == name, (name, d)
+              assert os.path.isfile(os.path.join(d, "SKILL.md")), d
+              print("skill ok:", name)
+          '
+
+      - uses: forgejo/upload-artifact@v4
+        with:
+          name: dist-labtrail
+          path: dist/*
+          if-no-files-found: error
+
+  # -------------------------------------------------- forward-integration ----
+  forward-integration:
+    # R4.25: subtree propagation on a proposed change. A revision can rebase
+    # through every descendant with no conflict at all and leave one of them no
+    # longer testing anything; only re-running the invariant at each hop finds
+    # it.
+    name: Forward integration
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+      - run: pip install -e '.[dev]'
+      - run: pytest tests/integration/test_propagate.py -q
+
+  # ------------------------------------------------------------- nightly ----
+  nightly:
+    name: Nightly
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q --upgrade pip
+          echo "/tmp/venv/bin" >> "$GITHUB_PATH"
+      - run: pip install -e '.[dev]'
+      - run: pytest -q -m 'slow or external or not slow'
+
+  # ------------------------------------------------------------- publish ----
+  publish:
+    name: Publish to PyPI
+    # A TAG, and the switch naming THIS forge. A push to a branch never
+    # releases anything -- that is what makes the 5-minute sync safe.
+    #
+    # SKIPS -- does not fail -- when the switch names GitHub.
+    if: startsWith(github.ref, 'refs/tags/v') && needs.gate.outputs.authority == 'forgejo'
+    needs: [gate, build, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: forgejo/download-artifact@v4
+        with:
+          name: dist-labtrail
+          path: dist
+
+      - name: Check the tag IS the version
+        # The template checks the tag against a version file and then the
+        # artifacts against that file. setuptools-scm removes the first half:
+        # the source version IS the tag, by construction, so there is no file
+        # that can disagree with it.
+        #
+        # The second half is not automatic and is what this step keeps. An
+        # artifact built from a shallow clone, from a dirty tree, or left over
+        # in dist/ from an earlier build carries a different version -- and a
+        # dirty tree in particular produces a LOCAL segment (`+d20260913`),
+        # which is precisely what must never reach PyPI.
+        run: |
+          tag="${GITHUB_REF#refs/tags/v}"
+          echo "tag=$tag"
+          for f in dist/*; do
+            case "$(basename "$f")" in
+              labtrail-${tag}-py3-none-any.whl|labtrail-${tag}.tar.gz) ;;
+              *) echo "::error::artifact $(basename "$f") is not version ${tag}"; exit 1 ;;
+            esac
+          done
+          echo "OK: the tag and every artifact agree on ${tag}"
+
+      - name: Publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "$TWINE_PASSWORD" ]; then
+            echo "::error::PYPI_API_TOKEN is not visible to this repository"
+            exit 1
+          fi
+          python3 -m venv /tmp/twineenv
+          /tmp/twineenv/bin/pip install -q --upgrade pip twine
+          /tmp/twineenv/bin/twine check dist/*
+          # Idempotence net: with one switch and two possible publishers, a
+          # double-fire must be a no-op rather than a failure or a corruption.
+          /tmp/twineenv/bin/twine upload --non-interactive --skip-existing dist/*