openarchieven 0.1.0__tar.gz

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

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Install cargo-nextest
+        uses: taiki-e/install-action@nextest
+
+      - name: make check
+        run: make check
+
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: make build
+        run: make build

openarchieven-0.1.0/.github/workflows/homebrew.yml

@@ -0,0 +1,78 @@
+name: Homebrew
+
+on:
+  workflow_run:
+    workflows: [Release]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag (e.g. v0.1.0)"
+        required: true
+        type: string
+
+jobs:
+  update-tap:
+    name: Update Homebrew tap
+    # workflow_run fires on every Release run, including failures — gate
+    # on success here. workflow_dispatch always runs.
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve release tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            tag="${{ inputs.tag }}"
+          else
+            # workflow_run fires for tag-triggered Release runs;
+            # head_branch holds the tag name in that case.
+            tag="${{ github.event.workflow_run.head_branch }}"
+          fi
+          if [ -z "$tag" ] || [ "${tag#v}" = "$tag" ]; then
+            echo "could not resolve a v* release tag (got: '$tag')" >&2
+            exit 1
+          fi
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "version=${tag#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Download release sha256 sidecars
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p dist
+          gh release download "${{ steps.tag.outputs.tag }}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --pattern "*.sha256" \
+            --dir dist
+
+      - name: Render formula
+        run: |
+          make homebrew-formula \
+            VERSION=${{ steps.tag.outputs.version }} \
+            TAG=${{ steps.tag.outputs.tag }}
+
+      - name: Push formula to homebrew-tap
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          if [ -z "${GH_TOKEN}" ]; then
+            echo "HOMEBREW_TAP_TOKEN secret is not set; cannot push to tap." >&2
+            exit 1
+          fi
+          tag="${{ steps.tag.outputs.tag }}"
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/rvben/homebrew-tap.git" /tmp/tap
+          mkdir -p /tmp/tap/Formula
+          cp dist/openarchieven.rb /tmp/tap/Formula/openarchieven.rb
+          cd /tmp/tap
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Formula/openarchieven.rb
+          if git diff --cached --quiet; then
+            echo "Formula already up to date for ${tag}; nothing to push."
+          else
+            git commit -m "Update openarchieven to ${tag}"
+            git push
+          fi

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

@@ -0,0 +1,161 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            maturin_args: --compatibility manylinux_2_28 --zig
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+            maturin_args: --compatibility manylinux_2_28 --zig
+          - target: x86_64-apple-darwin
+            os: macos-latest
+            maturin_args: ""
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            maturin_args: ""
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install maturin (with zig for cross-compiled Linux wheels)
+        shell: bash
+        run: |
+          uv venv "${RUNNER_TEMP}/build-venv"
+          uv pip install --python "${RUNNER_TEMP}/build-venv/bin/python" maturin ziglang
+          echo "${RUNNER_TEMP}/build-venv/bin" >> "$GITHUB_PATH"
+
+      - name: Compute version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: make build-wheel
+        run: make build-wheel TARGET=${{ matrix.target }} MATURIN_ARGS="${{ matrix.maturin_args }}"
+
+      - name: make release-archive
+        run: |
+          make release-archive \
+            TARGET=${{ matrix.target }} \
+            VERSION=${{ steps.version.outputs.version }}
+
+      - name: Upload binary archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/*
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.target }}
+          path: target/wheels/*.whl
+
+  sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Install maturin
+        shell: bash
+        run: |
+          uv venv "${RUNNER_TEMP}/build-venv"
+          uv pip install --python "${RUNNER_TEMP}/build-venv/bin/python" maturin
+          echo "${RUNNER_TEMP}/build-venv/bin" >> "$GITHUB_PATH"
+      - name: make build-sdist
+        run: make build-sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: target/wheels/*.tar.gz
+
+  release:
+    name: Publish release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: binary-*
+          path: dist
+          merge-multiple: true
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          notes_file=$(mktemp)
+          if [ -f CHANGELOG.md ]; then
+            awk -v v="$version" '
+              /^## / { if (in_section) exit; if ($2 == v || $2 == "v"v || $2 == "["v"]") in_section = 1; next }
+              in_section
+            ' CHANGELOG.md > "$notes_file"
+          fi
+          if [ ! -s "$notes_file" ]; then
+            echo "Release $version" > "$notes_file"
+          fi
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file "$notes_file" \
+            dist/*
+
+  publish-crates:
+    name: Publish to crates.io
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: make publish-crates
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: make publish-crates
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheel-*
+          path: artifacts/wheels
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: artifacts/sdist
+      - uses: astral-sh/setup-uv@v6
+      - name: make publish-pypi
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: make publish-pypi WHEEL_DIR=artifacts/wheels SDIST_DIR=artifacts/sdist

openarchieven-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+/target
+/.cache
+/dist
+**/*.rs.bk
+Cargo.lock.bak
+.DS_Store
+*.swp
+.idea/
+.vscode/
+*.egg-info/
+__pycache__/
+*.pyc

openarchieven-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-30
+
+Initial release.
+
+### Added
+- All 17 endpoints of the openarchieven.nl API v1.1: `archives`, `search`,
+  `show`, `match`, `births`, `deaths`, `marriages`, `yearsago`, `census`,
+  `weather`, and the seven `stats` subcommands.
+- Three output formats (`json`, `table`, `markdown`) selected automatically by
+  TTY/pipe context, overridable with `--output/-o`.
+- `schema` subcommand emits a byte-stable, machine-readable contract for
+  scripts and AI agents.
+- On-disk response cache with advisory locking and per-endpoint TTLs;
+  `cache info`, `cache prune`, and `cache clear --yes` for management.
+- Built-in rate limiter (4 req/sec default) and retry with jittered backoff
+  that respects `Retry-After`.
+- Structured JSON error contract on stderr with stable `kind` enum.
+- `--fields` projection for list and single-flat responses.
+- Distribution: crates.io, PyPI wheel, and Homebrew tap, all published from
+  one tag-driven release workflow.

openarchieven-0.1.0/CLAUDE.md

@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository.
+
+## Build & Test
+
+```bash
+make check     # lint + test (CI runs this)
+make build     # cargo build --release
+make test      # cargo nextest run (or cargo test fallback)
+make lint      # fmt --check + clippy -D warnings
+make fmt       # auto-format
+make install   # release build → ~/.local/bin/openarchieven
+```
+
+## Architecture
+
+Binary `openarchieven` wraps the openarchieven.nl API per the design spec at
+`docs/superpowers/specs/2026-04-29-openarchieven-cli-design.md`. Core flow:
+`main.rs` parses args → command module → `Client::get()` (cache + rate limit
++ retry) → response shaped into `Renderable` → renderer (json/table/markdown)
+→ stdout. Errors always go to stderr as JSON.
+
+## Modules
+
+- `client.rs`: HTTP, rate limiter, retry/backoff, `Retry-After` parsing.
+- `cache.rs`: on-disk JSON cache with atomic writes and advisory locks.
+- `error.rs`: `ErrorKind` enum and structured stderr emission.
+- `output.rs`: `Renderable` shapes and three renderers.
+- `schema_cmd.rs`: emits the machine-readable schema contract.
+- `commands/<name>.rs`: one module per API endpoint.
+
+## Conventions
+
+- TDD throughout. Test failure paths explicitly.
+- `cargo nextest run` preferred (fast, token-optimized via RTK).
+- No live network in unit/integration tests — `wiremock` stands in.
+- Schema output is byte-stable; `tests/schema.rs` snapshots it.