gearu 0.1.1__tar.gz

gearu-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Documentation
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref containing the documentation site files"
+        required: true
+        default: main
+        type: string
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    # Keep stable documentation on the stable release when an RC is published.
+    if: github.event_name == 'workflow_dispatch' || !github.event.release.prerelease
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the documentation source
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name || inputs.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs-requirements.txt
+      - name: Install documentation dependencies
+        run: pip install -r docs-requirements.txt
+      - name: Check generated CLI reference
+        run: python scripts/generate_cli_reference.py --check
+      - name: Build documentation
+        run: mkdocs build --strict
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

gearu-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,122 @@
+# Publish Gearu only after a GitHub Release is published. PyPI Trusted
+# Publishing provides short-lived OIDC authentication and package attestations;
+# this repository stores no PyPI API token.
+
+name: Publish gearu
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.release.tag_name }}
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Run tests
+        run: |
+          python -m pip install --upgrade pytest setuptools-scm
+          PYTHONPATH=src python -m pytest src/tests -q
+
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.release.tag_name }}
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Validate release identity
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m pip install --upgrade setuptools-scm
+          python - <<'PY'
+          import os
+          import re
+
+          from setuptools_scm import get_version
+
+          tag = os.environ["RELEASE_TAG"]
+          if re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+(?:-rc\.[1-9][0-9]*)?", tag) is None:
+              raise SystemExit(
+                  "release tag must be vMAJOR.MINOR.PATCH or "
+                  f"vMAJOR.MINOR.PATCH-rc.N, got {tag!r}"
+              )
+
+          version = get_version()
+          expected = re.sub(r"-rc\.([1-9][0-9]*)$", r"rc\1", tag.removeprefix("v"))
+          if version != expected:
+              raise SystemExit(
+                  f"release tag {tag!r} resolves to version {version!r}, expected {expected!r}"
+              )
+
+          print(f"building gearu {version}")
+          PY
+
+      - name: Build and check distributions
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Smoke-test wheel
+        run: |
+          python -m pip install dist/*.whl
+          python -c "import gearu; print(f'import gearu {gearu.__version__} OK')"
+          gearu --version
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - test
+      - build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gearu
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish release distributions
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

gearu-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.coverage
+htmlcov/
+*.pyc
+build/
+dist/
+/site/
+*.egg-info/

gearu-0.1.1/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS
+
+These rules apply to work in this repository.
+
+- Work TDD-first for behavior changes: failing test, implementation, green
+  tests, then refactor.
+- Preserve target manifest formatting and comments when updating versions or
+  dependency pins.
+- Keep ecosystem-specific behavior behind narrow adapters. Shared release
+  orchestration must not contain Cargo-, Python-, or npm-specific branching.
+
+<!-- gearu:agents:start -->
+## Releases
+
+- This repository uses [Gearu](https://owebeeone.github.io/gearu/) for release
+  preparation.
+- Read `RELEASE.md` before planning or performing a release.
+- `gearu plan VERSION` and `gearu plan --bump LEVEL` are read-only. Do not run
+  `gearu release`, push a release tag, or create a GitHub Release unless the
+  user explicitly requests it.
+- Never move or reuse a release tag. Correct released content with a new version.
+- Never publish directly to PyPI, crates.io, or npm from a local checkout.
+  Registry publication belongs in the repository's release workflow.
+<!-- gearu:agents:end -->

gearu-0.1.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Gianni Mariani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

gearu-0.1.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: gearu
+Version: 0.1.1
+Summary: Make repositories ready for release.
+Author-email: Gianni Mariani <gianni@mariani.ws>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/owebeeone/gearu
+Project-URL: Repository, https://github.com/owebeeone/gearu
+Keywords: release,versioning,automation,git,packaging
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Gearu
+
+**Make repositories ready for release.**
+
+Gearu is a small, explicit release-preparation tool for Python, Rust, and npm
+projects. Its name comes from Old English *gearu*: ready, prepared, or equipped.
+
+Documentation: <https://owebeeone.github.io/gearu/>
+
+Gearu takes an intended version and makes the repository mechanically ready to
+release:
+
+```sh
+gearu plan 0.1.0
+gearu release 0.1.0
+```
+
+Or select the next semantic version from configured package versions and valid
+local and remote release tags:
+
+```sh
+gearu plan --bump minor
+gearu release --bump minor
+```
+
+`plan` verifies and reports without changing tracked files or remote state.
+`release` builds and tests a candidate in a temporary worktree, then creates the
+local release commit and immutable tag. External actions are always explicit:
+
+```sh
+gearu release 0.1.0 --push
+gearu release 0.1.0 --push --github-release
+```
+
+## Boundaries
+
+Gearu is responsible for:
+
+- verifying repository, branch, commit, remote tag, and dependency-tag state;
+- updating versions, lockfiles, and configured dependency pins;
+- running project-specific release checks;
+- creating a release commit and immutable tag;
+- atomically pushing the commit and tag to one repository; and
+- creating the GitHub Release that starts that repository's publish workflow.
+
+Gearu does not publish packages directly to PyPI, crates.io, or npm. Registry
+credentials and publication remain in GitHub Actions, triggered by the
+`release.published` event.
+
+Cross-repository release trains are ordered and verified, but cannot be atomic:
+Git only provides atomic pushes within a single remote.
+
+## Install
+
+Once the first release is published:
+
+```sh
+uv tool install gearu
+```
+
+For development:
+
+```sh
+uv sync
+uv run python run_tests.py
+```
+
+## Bootstrap release guidance
+
+From any Git repository, run:
+
+```sh
+gearu init
+```
+
+This creates or updates managed Gearu sections in `AGENTS.md` and `RELEASE.md`.
+The short agent rule points to the full repository release instructions, which
+cover installation, documentation, planning, local preparation, pushing,
+GitHub Release creation, and recovery. Existing repository-specific content is
+preserved, and repeated runs produce no changes.
+
+`init` does not require `gearu.toml`; it can be the first Gearu setup step.
+
+## Configure
+
+Add `gearu.toml` to the target repository:
+
+```toml
+[project]
+name = "example"
+branch = "main"
+remote = "origin"
+tag_prefix = "v"
+github_repo = "owner/example"
+# Optional for repositories that cut releases from a maintained release branch:
+# source_branch = "main"
+
+[python]
+manifest = "pyproject.toml"
+version = "static"
+
+[release]
+checks = [["python", "-m", "pytest", "-q"]]
+```
+
+Use `[python]` with `version = "scm"` for tag-derived versions. Rust projects
+use `[rust]` with `manifests = ["Cargo.toml"]`; npm projects use `[npm]` with
+`manifest = "package.json"`. Lockfile refresh commands are configurable and run
+only when their ecosystem manifest changes.
+
+Cross-repository release dependencies can verify a remote tag and update an
+inline TOML pin:
+
+```toml
+[[dependencies]]
+name = "example-core"
+url = "https://github.com/owner/example-core"
+tag = "{tag}"
+pin_file = "Cargo.toml"
+pin_key = "dependencies.example-core"
+pin_field = "tag"
+# Optional: prove Cargo.lock pins this package to the resolved tag commit.
+lock_package = "example-core"
+```
+
+Override a same-version dependency deliberately with
+`--dependency-tag example-core=v1.1.0`.
+
+See [Configuration](docs/Configuration.md) for the complete schema and
+[Release Process](docs/ReleaseProcess.md) for the end-to-end operator flow and
+recovery rules.
+
+## Release model
+
+Gearu itself is published only by
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) after a GitHub
+Release is published. PyPI authentication uses Trusted Publishing; no PyPI API
+token is stored in the repository.
+
+## License
+
+[MIT](LICENSE)

gearu-0.1.1/README.md

@@ -0,0 +1,142 @@
+# Gearu
+
+**Make repositories ready for release.**
+
+Gearu is a small, explicit release-preparation tool for Python, Rust, and npm
+projects. Its name comes from Old English *gearu*: ready, prepared, or equipped.
+
+Documentation: <https://owebeeone.github.io/gearu/>
+
+Gearu takes an intended version and makes the repository mechanically ready to
+release:
+
+```sh
+gearu plan 0.1.0
+gearu release 0.1.0
+```
+
+Or select the next semantic version from configured package versions and valid
+local and remote release tags:
+
+```sh
+gearu plan --bump minor
+gearu release --bump minor
+```
+
+`plan` verifies and reports without changing tracked files or remote state.
+`release` builds and tests a candidate in a temporary worktree, then creates the
+local release commit and immutable tag. External actions are always explicit:
+
+```sh
+gearu release 0.1.0 --push
+gearu release 0.1.0 --push --github-release
+```
+
+## Boundaries
+
+Gearu is responsible for:
+
+- verifying repository, branch, commit, remote tag, and dependency-tag state;
+- updating versions, lockfiles, and configured dependency pins;
+- running project-specific release checks;
+- creating a release commit and immutable tag;
+- atomically pushing the commit and tag to one repository; and
+- creating the GitHub Release that starts that repository's publish workflow.
+
+Gearu does not publish packages directly to PyPI, crates.io, or npm. Registry
+credentials and publication remain in GitHub Actions, triggered by the
+`release.published` event.
+
+Cross-repository release trains are ordered and verified, but cannot be atomic:
+Git only provides atomic pushes within a single remote.
+
+## Install
+
+Once the first release is published:
+
+```sh
+uv tool install gearu
+```
+
+For development:
+
+```sh
+uv sync
+uv run python run_tests.py
+```
+
+## Bootstrap release guidance
+
+From any Git repository, run:
+
+```sh
+gearu init
+```
+
+This creates or updates managed Gearu sections in `AGENTS.md` and `RELEASE.md`.
+The short agent rule points to the full repository release instructions, which
+cover installation, documentation, planning, local preparation, pushing,
+GitHub Release creation, and recovery. Existing repository-specific content is
+preserved, and repeated runs produce no changes.
+
+`init` does not require `gearu.toml`; it can be the first Gearu setup step.
+
+## Configure
+
+Add `gearu.toml` to the target repository:
+
+```toml
+[project]
+name = "example"
+branch = "main"
+remote = "origin"
+tag_prefix = "v"
+github_repo = "owner/example"
+# Optional for repositories that cut releases from a maintained release branch:
+# source_branch = "main"
+
+[python]
+manifest = "pyproject.toml"
+version = "static"
+
+[release]
+checks = [["python", "-m", "pytest", "-q"]]
+```
+
+Use `[python]` with `version = "scm"` for tag-derived versions. Rust projects
+use `[rust]` with `manifests = ["Cargo.toml"]`; npm projects use `[npm]` with
+`manifest = "package.json"`. Lockfile refresh commands are configurable and run
+only when their ecosystem manifest changes.
+
+Cross-repository release dependencies can verify a remote tag and update an
+inline TOML pin:
+
+```toml
+[[dependencies]]
+name = "example-core"
+url = "https://github.com/owner/example-core"
+tag = "{tag}"
+pin_file = "Cargo.toml"
+pin_key = "dependencies.example-core"
+pin_field = "tag"
+# Optional: prove Cargo.lock pins this package to the resolved tag commit.
+lock_package = "example-core"
+```
+
+Override a same-version dependency deliberately with
+`--dependency-tag example-core=v1.1.0`.
+
+See [Configuration](docs/Configuration.md) for the complete schema and
+[Release Process](docs/ReleaseProcess.md) for the end-to-end operator flow and
+recovery rules.
+
+## Release model
+
+Gearu itself is published only by
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) after a GitHub
+Release is published. PyPI authentication uses Trusted Publishing; no PyPI API
+token is stored in the repository.
+
+## License
+
+[MIT](LICENSE)

gearu-0.1.1/RELEASE.md

@@ -0,0 +1,122 @@
+# Release Process
+
+<!-- gearu:release:start -->
+## Gearu Release Process
+
+Gearu prepares and verifies the repository, creates an immutable tag, and can
+create the GitHub Release that starts this repository's publication workflow.
+It does not publish directly to package registries.
+
+Full documentation: <https://owebeeone.github.io/gearu/>
+
+### Install
+
+Install the released tool with:
+
+```sh
+uv tool install gearu
+```
+
+Upgrade an existing installation with:
+
+```sh
+uv tool upgrade gearu
+```
+
+To test the unreleased `main` branch, install it directly from its repository:
+
+```sh
+uv tool install git+https://github.com/owebeeone/gearu.git
+```
+
+Verify the installation with `gearu --version`.
+
+### Preconditions
+
+- Read `gearu.toml` and this repository's release workflow.
+- Choose an explicit release version or an explicit major, minor, or patch bump.
+  Gearu does not infer release intent from commits.
+- Use a clean checkout on the branch configured by `project.branch`.
+- Synchronize configured release and source branches with their remote.
+- Release required cross-repository dependencies first.
+- Install and authenticate `gh` before requesting GitHub Release creation.
+
+### Plan
+
+Always inspect the read-only plan first:
+
+```sh
+gearu plan VERSION
+```
+
+Or ask Gearu to select the next version:
+
+```sh
+gearu plan --bump patch
+gearu plan --bump minor
+gearu plan --bump major
+```
+
+Gearu compares configured package versions with valid local and remote release
+tags, then bumps the highest version. It reads remote tags directly and does not
+fetch or create local tags while planning.
+
+For a release candidate, use a numbered version such as `1.2.3-rc.1`.
+
+Override a configured dependency tag only when the release intentionally uses a
+different version:
+
+```sh
+gearu plan VERSION --dependency-tag DEPENDENCY=TAG
+```
+
+### Prepare the Local Release
+
+After reviewing the plan:
+
+```sh
+gearu release VERSION
+```
+
+The release command can select the version itself:
+
+```sh
+gearu release --bump minor
+```
+
+This recalculates the next version at release time. To lock the version reviewed
+in a prior bump plan, pass that plan's reported `VERSION` explicitly.
+
+Gearu builds and tests in a temporary worktree. Only a successful candidate is
+applied to the local release branch and tagged. This step does not change a
+remote repository.
+
+### Push and Create the GitHub Release
+
+Push the exact release commit and tag atomically:
+
+```sh
+gearu release VERSION --push
+```
+
+Create the GitHub Release after that push:
+
+```sh
+gearu release VERSION --push --github-release
+```
+
+The final command starts workflows listening for `release.published`, including
+package publication and documentation deployment where configured.
+
+### Recovery
+
+- If candidate checks fail, fix the problem and rerun; the normal checkout is
+  left unchanged.
+- If local preparation succeeds, rerun the same version with `--push`.
+- If the push succeeds but GitHub Release creation fails, rerun with
+  `--push --github-release`.
+- If released contents must change, use a new patch or release-candidate version.
+  Never move or replace the existing tag.
+- If only a publication workflow fails, repair and rerun that workflow for the
+  same GitHub Release.
+<!-- gearu:release:end -->