Metadata-Version: 2.4
Name: lx-tooling
Version: 0.3.0
Summary: Labinetix workflow CLI for humans and AI agents
Project-URL: Homepage, https://github.com/labinetix/lx-tooling
Project-URL: Repository, https://github.com/labinetix/lx-tooling
Project-URL: Documentation, https://github.com/labinetix/lx-tooling/blob/main/docs/design/lx-tooling.md
Author-email: Fabian Müller <fabianmueller100295@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: typer>=0.26.8
Description-Content-Type: text/markdown

# lx-tooling

**Tag:** Org and orchestration

**Labinetix workflow CLI** for humans and AI agents. `lx-tooling` orchestrates GitHub issues, branches, pull requests, releases, local verification, and repository policy checks without owning domain logic.

**Non-goals:** model semantics, ABI schema ownership, runtime algorithms, or protocol implementations.

## Stability

Milestone 2 — release planning (`lx release plan`, `lx release create` validation). Branch creation and `gh pr create` require `--yes`. Tagging and publishing remain manual.

## Quickstart

Prerequisites:

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)
- [`gh`](https://cli.github.com/) authenticated (`gh auth login`)

Local development:

```bash
git clone git@github.com:labinetix/lx-tooling.git
cd lx-tooling
uv sync --all-groups
uv run lx --version
```

Local checks (same as CI):

```bash
just check
```

Or explicitly:

```bash
uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
```

## Install

From PyPI:

```bash
uv tool install lx-tooling
lx --version
```

Upgrade:

```bash
uv tool upgrade lx-tooling
```

From a checkout:

```bash
uv sync --all-groups
uv run lx --help
```

## Commands

Inspect the current repository:

```bash
lx repo inspect
lx repo inspect --json
```

Run conservative pre-PR checks:

```bash
lx workflow check
```

Read a GitHub issue with Labinetix readiness hints:

```bash
lx issue view 123
```

Start work from an issue (dry-run by default):

```bash
lx issue start 123
lx issue start 123 --yes
lx issue start 123 --yes --comment
```

Prepare a pull request (dry-run by default):

```bash
lx pr prepare
lx pr prepare --yes
```

Plan a release (dry-run by default):

```bash
lx release plan
lx release create 0.3.0
lx release create 0.3.0 --yes
```

Examples:

- [`docs/examples/repo-inspect.md`](docs/examples/repo-inspect.md)
- [`docs/examples/issue-start.md`](docs/examples/issue-start.md)
- [`docs/examples/pr-prepare.md`](docs/examples/pr-prepare.md)
- [`docs/examples/release-plan.md`](docs/examples/release-plan.md)

## Development workflow with `lx`

This is the intended day-to-day loop for a new feature or bugfix in any Labinetix repository once `lx` is installed. `lx` wraps `git` and `gh`; risky steps stay behind `--yes`.

```mermaid
flowchart LR
  issue["Issue or bug report"]
  view["lx issue view"]
  start["lx issue start --yes"]
  work["Code tests docs"]
  check["just check + lx workflow check"]
  prepare["lx pr prepare"]
  pr["lx pr prepare --yes"]
  merge["Review + merge main"]
  release["Tag + release notes"]
  issue --> view --> start --> work --> check --> prepare --> pr --> merge --> release
```

### 1. Start from an issue

Create a scoped GitHub issue (or use an existing one). The body should include **Scope**, **Tests**, and **Release impact** when possible.

```bash
gh issue create --title "fix: ..." --body "## Scope\n..."
lx issue view 123
```

### 2. Start the branch

From an up-to-date `main`:

```bash
git checkout main && git pull
lx issue start 123          # preview branch name and readiness
lx issue start 123 --yes --comment
```

If you prefer a manual branch name, use the Labinetix convention (`feat/`, `fix/`, `docs/`, etc.) and skip `--yes`.

### 3. Implement one coherent slice

- Update code, tests, docs, and examples together
- Reference the issue in commits: `feat(cli): ... (#123)` or `Refs #123`
- Run the same checks as CI:

```bash
just check
lx workflow check
```

### 4. Open a pull request

```bash
git push -u origin HEAD
lx pr prepare               # preview generated PR body
lx pr prepare --yes         # gh pr create when ready
```

Review and merge through GitHub as usual. CI and branch protection remain authoritative.

### 5. Release (maintainers)

After merging to `main`:

1. Bump `version` in `pyproject.toml` and `src/lx_tooling/__init__.py`
2. Add `docs/release-notes/vX.Y.Z.md` (see below)
3. Merge the version/release-notes PR
4. Tag on `main` and push the tag — CI publishes to PyPI and GitHub Releases

```bash
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0
```

### Bugfixes vs features

| Kind | Branch prefix | Typical release |
|------|---------------|-----------------|
| Feature | `feat/` | minor `0.y.0` |
| Bugfix | `fix/` | patch `0.y.z` |
| Docs only | `docs/` | patch or none |
| CI/tooling | `ci/` | patch |

Use `lx workflow check` before every PR; it warns on wrong branch names, missing `AGENTS.md` / `README.md`, and `src/` changes without `tests/` updates.

### What comes later

- Optional `lx pr prepare --body-file` for manual PR body edits
- Guarded tag creation and publish automation in a later milestone
- More automation does **not** replace CI, reviews, or protected environments

## Design and Agent Rules

- Design: [`docs/design/lx-tooling.md`](docs/design/lx-tooling.md)
- Agent rules: [`AGENTS.md`](AGENTS.md)

## Releases and release notes

- Package name on PyPI: `lx-tooling`
- CLI command: `lx`
- Latest release: [GitHub Releases](https://github.com/labinetix/lx-tooling/releases)
- Artifacts: wheel + sdist built by CI on protected SemVer tags (`v*`), published to PyPI via trusted publishing (`pypi.yml`, environment `pypi`)

### Release notes practice

**Store release notes in the repository**, not only on GitHub:

```text
docs/release-notes/vX.Y.Z.md
```

Each file should include:

- User-facing summary and command changes
- Breaking changes (if any)
- Linked issues and PRs
- **Session notes** when AI agents helped — goal, approach, verification, follow-ups

See [`docs/release-notes/README.md`](docs/release-notes/README.md) for the full template and policy.

The PyPI workflow uses the matching file as the GitHub Release body when you push a tag.

### Maintainer checklist

1. Merge feature/fix PRs to `main`; keep CI green
2. Open a small PR (or commit on `main` if policy allows) that bumps version + adds `docs/release-notes/vX.Y.Z.md`
3. Merge to `main`
4. Tag `vX.Y.Z` on `main` and push the tag
5. Confirm PyPI workflow succeeded; verify `uv tool install lx-tooling` picks up the new version
