pixie-lab-dibs 0.1.0__tar.gz

pixie_lab_dibs-0.1.0/.github/workflows/format.yml

@@ -0,0 +1,46 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+name: format
+
+# Only the default branch on push. Every other branch is covered by the pull
+# request event, and running both would check each commit twice.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.x"
+
+      - name: Cache pre-commit environments
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: make format
+        run: make format
+
+      # Most hooks fail when they rewrite a file, so the step above catches
+      # them. This catches the ones that would fix something and exit zero.
+      - name: Verify nothing changed
+        run: git diff --exit-code
+
+      - name: Show what changed
+        if: failure()
+        run: git --no-pager diff

pixie_lab_dibs-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+name: publish
+
+# A version tag publishes that version to PyPI, as pixie-lab-dibs. The upload uses
+# PyPI's trusted publishing, so no token is stored here: PyPI accepts it
+# because it comes from this workflow in this repository.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7.2.1
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: make format
+        run: make format PRECOMMIT="uvx pre-commit"
+
+      - name: make check
+        run: make check
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7.2.1
+        with:
+          python-version: "3.13"
+
+      # Without this, a tag that does not match __version__ would publish
+      # the version in the code under a release named after the tag.
+      - name: Check the tag matches the version
+        run: |
+          version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/dibs/__init__.py)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match __version__ $version" >&2
+            exit 1
+          fi
+
+      - name: make build
+        run: make build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

pixie_lab_dibs-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+name: test
+
+# Only the default branch on push. Every other branch is covered by the pull
+# request event, and running both would check each commit twice.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # The oldest and newest Python dibs supports.
+        python: ["3.11", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7.2.1
+        with:
+          python-version: ${{ matrix.python }}
+
+      # The login tests sign and verify with ssh-keygen, which the runner
+      # image ships; they skip rather than pass if it is ever missing, so
+      # fail here instead.
+      - name: Check ssh-keygen is present
+        run: ssh-keygen -Y 2>&1 | grep -q sign
+
+      - name: make check
+        run: make check
+
+      - name: make build
+        run: make build

pixie_lab_dibs-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

pixie_lab_dibs-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+# The license texts under LICENSES/ are kept away from the hooks that rewrite
+# files. Editing a license to suit a formatter is the one thing that must never
+# happen to one, whatever the formatter thinks of its whitespace.
+exclude: ^LICENSES/
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.2
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        # Pinned because `pre-commit autoupdate` does not touch these, so an
+        # unpinned release would change formatting on an unrelated commit and
+        # fail CI there.
+        additional_dependencies:
+          - mdformat-gfm==1.0.0
+
+  - repo: https://github.com/fsfe/reuse-tool
+    rev: v6.2.0
+    hooks:
+      - id: reuse
+
+  - repo: local
+    hooks:
+      # Alternation, not a character class: pygrep matches on bytes, so a class
+      # of multi-byte characters becomes a class of their individual bytes and
+      # then flags unrelated letters. "æ" shares a byte with "…".
+      - id: ascii-punctuation
+        name: ASCII punctuation only
+        language: pygrep
+        entry: '(—|–|‘|’|“|”|…|→|←|•)'
+        types: [text]
+        exclude: ^\.pre-commit-config\.yaml$

pixie_lab_dibs-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+<!--
+SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# Changelog
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-27
+
+### Added
+
+- The first version: things to claim, fed from a config file and from
+  pixie servers; claims that are all or nothing, never expire unless
+  asked to, and say when an agent made them; users who register an SSH
+  public key, are approved by the admin, and log in by signing a
+  one-time challenge; a login hook that shows a machine's claim; and
+  one `dibs` command for the server, its systemd service, the admin, and
+  everyone claiming.

pixie_lab_dibs-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Simon A. F. Lund
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pixie_lab_dibs-0.1.0/LICENSES/BSD-3-Clause.txt

@@ -0,0 +1,11 @@
+Copyright (c) Simon A. F. Lund <os@safl.dk>
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pixie_lab_dibs-0.1.0/Makefile

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Common tasks, and the home of the CI logic: the workflows call these
+# targets, so everything CI does can be run locally. Run "make" for the list.
+
+UV ?= uv
+PRECOMMIT ?= pre-commit
+
+.DEFAULT_GOAL := help
+.PHONY: help format lint typecheck test build check
+
+help: ## Show this help
+	@grep -hE '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  %-10s %s\n", $$1, $$2}'
+
+format: ## Run every pre-commit hook: ruff, mdformat, reuse, ASCII punctuation
+	$(PRECOMMIT) run --all-files
+
+lint: ## ruff check
+	$(UV) run ruff check .
+
+typecheck: ## mypy --strict over src
+	$(UV) run mypy
+
+test: ## pytest
+	$(UV) run pytest -q
+
+build: ## Build the sdist and wheel, and check every command the wheel installs runs
+	rm -rf dist
+	$(UV) build
+	for cmd in $$(unzip -p dist/*.whl '*/entry_points.txt' | sed -n 's/ *=.*//p' | grep -v '^\['); do \
+		$(UV) tool run --from "$$(ls dist/*.whl)" "$$cmd" --help >/dev/null || exit 1; \
+	done
+
+check: lint typecheck test ## Everything but format

pixie_lab_dibs-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: pixie-lab-dibs
+Version: 0.1.0
+Summary: Call dibs on shared lab machines: see who is using what, claim it, release it
+Project-URL: Homepage, https://github.com/safl/pixie-lab-dibs
+Author-email: "Simon A. F. Lund" <os@safl.dk>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: claims,coordination,lab,pixie,reservation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6
+Requires-Dist: tomlkit>=0.12
+Requires-Dist: uvicorn[standard]>=0.30
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# dibs
+
+[![test](https://github.com/safl/pixie-lab-dibs/actions/workflows/test.yml/badge.svg)](https://github.com/safl/pixie-lab-dibs/actions/workflows/test.yml)
+[![format](https://github.com/safl/pixie-lab-dibs/actions/workflows/format.yml/badge.svg)](https://github.com/safl/pixie-lab-dibs/actions/workflows/format.yml)
+[![PyPI](https://img.shields.io/pypi/v/pixie-lab-dibs)](https://pypi.org/project/pixie-lab-dibs/)
+[![Python](https://img.shields.io/pypi/pyversions/pixie-lab-dibs)](https://pypi.org/project/pixie-lab-dibs/)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+[![REUSE status](https://api.reuse.software/badge/github.com/safl/pixie-lab-dibs)](https://api.reuse.software/info/github.com/safl/pixie-lab-dibs)
+
+Call dibs on shared lab machines.
+
+A lab machine is shared with people, ai-agents and automation-runners.
+dibs lets each of them see who is on a machine before touching it, by
+claiming it. A claim is a note, not a lock: SSH and the console stay
+open to everyone. Everywhere a claim shows up, it reads as one sentence:
+
+```
+'alice' has claimed 'node-01' for 'xnvme' expires in: 'never'
+```
+
+dibs keeps a list of **things** to claim, mostly machines. It fills the
+list from **sources**: a config file, and any number of
+[pixie](https://github.com/safl/pixie) servers, whose machines show up
+on their own, with their hardware inventory.
+
+## Install
+
+```
+uv tool install pixie-lab-dibs
+```
+
+That gives you the `dibs` command, for both the server and the client.
+Signing in uses `ssh-keygen` from OpenSSH 8.1 or newer.
+
+## Run the server
+
+On the host that will run it, list the things in `/etc/dibs/dibs.toml`:
+
+```toml
+[[pixie]]
+url = "http://pixie:8080"   # every machine pixie knows becomes a thing
+
+[[thing]]
+name = "ryzen-01"           # a machine pixie does not boot
+mac = "aa:bb:cc:dd:ee:ff"   # any other key is kept as an attribute
+```
+
+Then make it a service and start it:
+
+```
+sudo dibs server install
+```
+
+The command writes a systemd unit for the `dibs` you ran, enables it
+and starts it. `dibs server start`, `stop`, `restart`, `status` and
+`logs` manage it from then on. The service runs as a throwaway system
+user that owns only `/var/lib/dibs`. Without root, `dibs server install --user` installs a per-user service instead. For a quick try,
+`dibs serve` runs the server in the foreground.
+
+The system service can only run a `dibs` installed outside your home
+directory, for example with
+`sudo UV_TOOL_DIR=/opt/uv UV_TOOL_BIN_DIR=/usr/local/bin uv tool install pixie-lab-dibs`.
+
+## Sign in
+
+Claiming needs a user. Register a name with your SSH public key:
+
+```
+export DIBS_URL=http://dibs:8090
+dibs register alice
+```
+
+The admin approves it on the server host:
+
+```
+sudo dibs admin approve alice
+```
+
+Then you log in once. `dibs` signs a one-time challenge with your key,
+through your ssh-agent if the key lives there, and keeps the token it
+gets back:
+
+```
+dibs login
+```
+
+The token does not expire; `dibs logout` drops it, and
+`dibs admin revoke alice` ends every login alice has. `-i` picks a key
+other than `~/.ssh/id_ed25519.pub`.
+
+Over plain HTTP, a token can be read off the network. dibs gives claims
+an identity among people who share a lab in good faith; it is not
+protection against someone on that network. Put HTTPS in front of it if
+the network is not trusted.
+
+## Claim
+
+```
+dibs list [--mine]
+dibs info <thing>
+dibs claim <thing>... --for <purpose> [--expires 2h] [--force]
+dibs release <thing>... | --mine
+```
+
+A claim never expires unless given `--expires`, and an expired claim
+counts as free. Claiming several things is all or nothing: if any of
+them is claimed by someone else, you get none, and the refusal says who
+holds it. `--force` takes or releases someone else's claim, and the
+server's log records that it did.
+
+`list` and `info` print for people. Add `--json`, `--yaml` or `--toml`
+to get the answer as data instead; an agent or script should use one of
+those rather than parse the text.
+
+The exit status is 0 when done, 1 when refused because someone else
+holds a thing, and 2 for anything else.
+
+### AI-agents
+
+Point your agent at this section. An agent claims as its human, and
+names itself the way an `Assisted-by:` trailer does:
+
+```
+export DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5"
+```
+
+The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' has claimed ...`.
+
+If you are an agent reading this: before you run anything on a lab
+machine, run `dibs list` and claim the machine with
+`dibs claim <machine> --for <purpose>`. Never use a machine someone else
+has claimed, and never pass `--force`; ask your human instead. Release
+what you claimed with `dibs release --mine` when the work is done, and
+also when it fails or is abandoned. That releases only what you claimed,
+not your human's own claims.
+
+### Automation-runners
+
+Give the runner a user of its own: register it with a key made for it,
+approve it, log in once, and store the token as the runner's
+`DIBS_TOKEN` secret. A refused claim exits 1, which a runner can wait
+out; anything else exits 2 and should fail the job. In GitHub Actions:
+
+```yaml
+env:
+  DIBS_URL: http://dibs:8090
+  DIBS_TOKEN: ${{ secrets.DIBS_TOKEN }}
+steps:
+  - name: Claim the machine
+    run: |
+      until dibs claim node-01 --for "${{ github.workflow }}" --expires 3h; do
+        [ $? -eq 1 ] || exit 1
+        sleep 60
+      done
+  - name: Test
+    run: ...
+  - name: Release the machine
+    if: always()
+    run: dibs release --mine
+```
+
+The `--expires` is a safety net for a runner that dies before its
+release step.
+
+## See the claim when you log in
+
+Install the login hook on each machine. At every interactive login it
+asks dibs for the machine's claim and prints it. It stays silent when
+dibs is unreachable, and does nothing for non-interactive SSH such as
+`scp`. It finds the machine by its MAC addresses, or else its hostname.
+
+```
+curl -fsS http://dibs:8090/login.sh | sudo tee /etc/profile.d/dibs.sh
+```
+
+## Shell completion
+
+```
+eval "$(dibs completion bash)"
+```
+
+Add that line to `~/.bashrc`, or write the script to
+`/etc/bash_completion.d/dibs`. It completes commands and options, and
+thing names from the server.
+
+## HTTP
+
+Anything that can send JSON can use dibs without the client. Reads need
+no login; claim and release take `Authorization: Bearer <token>`.
+
+| Route                      |                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| `GET /things`              | every thing, with its `sentence` and, while claimed, its `claim`                             |
+| `GET /things/<name>`       | one thing, plus `pixie` when a pixie server knows it                                         |
+| `GET /things/<name>/claim` | the sentence as one line of text                                                             |
+| `POST /claims`             | `{"things": [...], "purpose": "...", "assisted_by": "", "expires_in": null, "force": false}` |
+| `POST /claims/release`     | `{"things": [...], "force": false}`, or `{"mine": true, "assisted_by": ""}`                  |
+| `POST /auth/register`      | `{"user": "...", "pubkey": "ssh-ed25519 ..."}`                                               |
+| `POST /auth/challenge`     | `{"user": "..."}` gives a nonce and the message to sign                                      |
+| `POST /auth/login`         | `{"user", "nonce", "signature"}` gives a token                                               |
+| `GET /login.sh`            | the login hook                                                                               |
+
+A claim or release blocked by someone else's claim answers 409 with
+the blocking claims' sentences in `detail.claimed`.
+
+## Releasing
+
+Set the version in `src/dibs/__init__.py`, move the changelog's
+`Unreleased` entries under that version, commit, and push a tag named
+after it:
+
+```
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The tag runs the publish workflow, which checks the tag matches the
+version, runs the checks, and uploads `pixie-lab-dibs` to PyPI through trusted
+publishing.
+
+## License
+
+BSD-3-Clause. The repository follows [REUSE](https://reuse.software):
+every file states its copyright and license, `LICENSES/` holds the
+license text, and `REUSE.toml` covers the files that cannot carry a
+header.