Metadata-Version: 2.3
Name: augint-tools
Version: 5.33.0
Summary: CLI for AI-assisted repository and workspace workflows
Author: svange
Requires-Dist: click>=8.1.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: loguru>=0.7.3,<0.8
Requires-Dist: rich>=13.9.4,<15.0
Requires-Dist: pygithub>=2.5.0,<3
Requires-Dist: textual>=1.0.0,<2
Requires-Dist: pytest>=7.4.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8.0 ; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0 ; extra == 'dev'
Requires-Dist: python-semantic-release>=10.3.1 ; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0 ; extra == 'dev'
Requires-Dist: bandit>=1.7.0 ; extra == 'dev'
Requires-Dist: pip-audit>=2.7.0 ; extra == 'dev'
Requires-Dist: pip-licenses>=5.0.0 ; extra == 'dev'
Requires-Dist: pytest-html>=4.0.0 ; extra == 'dev'
Requires-Dist: pdoc>=15.0.0 ; extra == 'dev'
Requires-Dist: types-defusedxml>=0.7.0 ; extra == 'dev'
Requires-Python: >=3.12
Provides-Extra: dev
Description-Content-Type: text/markdown

# augint-tools

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/augint-tools.svg)](https://pypi.org/project/augint-tools/)
[![Tests](https://github.com/svange/augint-tools/actions/workflows/pipeline.yaml/badge.svg)](https://github.com/svange/augint-tools/actions)

CLI orchestration layer for AI-assisted repository workflows.

`augint-tools` provides a stable, machine-parseable command surface for humans and AI agents to coordinate development workflows. It is designed to be called directly by AI skills, replacing ad-hoc shell scripts with reliable, JSON-enabled commands.

## Features

- **AI-first design**: Every command supports `--json` output for agent parsing
- **Repo-type aware**: Understands library and service repository patterns
- **Safe defaults**: No destructive git operations without explicit commands
- **GitHub integration**: Issue management, PR creation, CI status monitoring

## Installation

```bash
pip install augint-tools
```

Or with `uv`:

```bash
uv tool install augint-tools
```

## Quick Start

### Single Repository Workflows

```bash
# Initialize repo metadata
ai-tools init --library

# Check repository status
ai-tools repo status --json

# Search/pick issues
ai-tools repo issues pick "bug"

# Create feature branch
ai-tools repo branch prepare --issue 42 --description "fix the thing"

# Run checks
ai-tools repo check run
ai-tools repo check run --preset full --fix

# Submit work (push + create PR)
ai-tools repo submit
```

## Command Reference

### Top-Level Commands

- `ai-tools init [--library|--service]` - Initialize repository metadata

### Repository Commands (`ai-tools repo`)

- `inspect` - One-call repo snapshot (kind, branch, toolchain, command plan)
- `status` - Show repository status (branch, dirty state, PRs, CI)
- `issues pick [query]` - Issue recommendation and search
- `branch prepare` - Create work branch from correct base
- `check plan` - Resolve validation plan without running
- `check run` - Execute validation plan
- `submit` - Push branch and create PR with automerge
- `ci watch` - Monitor CI run
- `ci triage` - Classify CI failures

## Dashboard Deployment Links

Each repo card can surface clickable shortcuts to its live deployment URLs (plus the repo's PyPI page for Python libraries). Links come from a user-global yaml file so the same config works from any terminal or WSL shell.

### Yaml file

Path: `~/.augint-tools/deployments.yaml` (resolves to `%USERPROFILE%\.augint-tools\deployments.yaml` on Windows).

Schema: a map of `owner/repo` slugs to a flat list of `{label, url}` entries.

```yaml
augmentingintegrations/aillc-web:
  - { label: dev,  url: "https://www.org.aillc.link/" }
  - { label: main, url: "https://www.augmentingintegrations.com/" }
augmentingintegrations/ai-lls-api:
  - { label: dev,  url: "https://lls-api.lls.aillc.link" }
  - { label: main, url: "https://lls-api.landlinescrubber.link" }
augmentingintegrations/woxom-sales-dashboard:
  - { label: dashboard,         url: "https://dashboard.woxom.aillc.link/" }
  - { label: jacksonhealthcare, url: "https://jacksonhealthcare.woxom.aillc.link/" }
```

### Reserved labels

| label  | glyph | treatment |
|--------|-------|-----------|
| `main` | `p`   | prod -- middle-click on card title opens this |
| `dev`  | `s`   | staging -- shift + middle-click on card title opens this |
| `pypi` | `π`   | auto-synthesized for Python libraries (see below); manual entry overrides the auto guess |

Any other label is free-form; the card glyph is the first alphanumeric character of the label (lowercased).

Deployment glyphs are rendered right-aligned on the CI status line of each card (e.g. `dev PASS  main PASS       s p`). Each glyph is an OSC-8 hyperlink clickable in supported terminals.

### Auto-PyPI

If a repo has the `py` tag, is not a service (`looks_like_service=False`), and is not an org repo (`is_org=False`), the card and drawer get an automatic `https://pypi.org/project/<repo-name>/` link rendered in a dim style. If the repo's PyPI name differs from its GitHub name, add a manual `pypi` entry in the yaml -- manual entries always win.

### Interaction model

**Keyboard shortcuts** (work on the selected repo, one-hand cluster):

| Key | Action |
|-----|--------|
| `z` | Open prod/main deployment URL |
| `x` | Open dev/staging deployment URL |
| `c` | Open 1st supplemental link (after main/dev) |
| `v` | Open 2nd supplemental link |
| `b` | Open 3rd supplemental link |
| `f` | Open the "Manage deployment links" modal |

**Mouse** (on the title row; depends on terminal modifier support):

- **Middle-click on the title** -> open prod URL (falls back to the GitHub repo page if no `main` link is configured).
- **Shift + middle-click on the title** -> open dev URL, or toast "no url configured for dev" if none.
- **Ctrl + left-click on the title** -> open the "Manage deployment links" modal for that repo.
- **Left-click on a glyph** (`s` / `p` / `π` / first-letter) -> terminal-native OSC-8 link opens the URL directly.

Note: mouse modifier support (shift+click, ctrl+click) varies by terminal. Windows Terminal may intercept ctrl+click for OSC-8 link handling. The keyboard shortcuts (`p`, `P`, `u`) are the reliable primary interface.

The detail drawer (press `d`) lists every link in a `deployments:` section with the host shown as visible text and the full URL as the OSC-8 target.

### Manage modal

Press `f` or middle-click on the repo name to open a modal scoped to the selected repo. The modal has dedicated fields for Production and Staging URLs at the top (Set/Clear), plus an add row for supplemental links. Existing supplementals are listed inline with Remove buttons (AWS Security Groups style). Every mutation writes the yaml immediately. Auto-PyPI entries are not listed (they aren't stored in the yaml); add a manual `pypi` row to override the guess.

## Development

### Setup

```bash
uv sync --all-extras
```

### Running Tests

```bash
uv run pytest                    # Run all tests
uv run pytest --cov             # With coverage
uv run pytest -k test_name      # Specific test
```

### Code Quality

```bash
uv run ruff check src/ tests/   # Lint
uv run ruff format src/ tests/  # Format
uv run mypy src/               # Type check
uv run pre-commit run --all-files  # All hooks
```

## Design Principles

1. **Human and AI first** - Commands work well for both interactive use and programmatic calls
2. **JSON always available** - Every orchestration command supports stable `--json` output
3. **Safe defaults** - No destructive behavior without explicit confirmation
4. **Repo-type aware** - Different defaults for libraries, services, and workspaces
5. **Skills call tools** - AI skills orchestrate this CLI, not replace it with shell scripts

## License

MIT
