Metadata-Version: 2.3
Name: augint-tools
Version: 4.2.0
Summary: CLI for AI-assisted repository and workspace workflows
Author: svange
Requires-Dist: click>=8.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
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-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 and workspace workflows.

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

## Features

- **Dual-mode operation**: Commands for both single repos (`ai-tools repo`) and workspaces (`ai-tools workspace`)
- **AI-first design**: Every command supports `--json` output for agent parsing
- **Repo-type aware**: Understands library, service, and workspace 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
```

### Workspace Workflows

```bash
# Initialize workspace
ai-tools init --workspace

# Sync all child repositories
ai-tools workspace sync --json

# Check status across all repos
ai-tools workspace status

# Create coordinated branches
ai-tools workspace branch --name feat/multi-repo-change

# Run tests and lint across all repos
ai-tools workspace test
ai-tools workspace lint

# Run command in all repos
ai-tools workspace foreach -- git status

# Submit PRs for all modified repos
ai-tools workspace submit
```

## Command Reference

### Top-Level Commands

- `ai-tools init [--library|--service|--workspace]` - 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

### Workspace Commands (`ai-tools workspace`)

- `inspect` - Workspace snapshot
- `status` - Status across all child repositories
- `sync` - Clone missing repos and update existing
- `issues [query]` - Aggregate issues from all repos
- `branch` - Create coordinated branches
- `check` - Grouped validation across repos
- `test` - Alias for check --phase tests
- `lint` - Alias for check --phase quality
- `foreach <command>` - Execute command in all repos
- `submit` - Push and create PRs for modified repos

## Configuration

### Repository Classification

`ai-shell.toml`:

```toml
[project]
repo_type = "library"        # or "service", "workspace"
branch_strategy = "main"     # or "dev"
dev_branch = "dev"           # when branch_strategy = "dev"
```

### Workspace Manifest

`workspace.yaml` (for workspace repos):

```yaml
workspace:
  name: my-workspace
  repos_dir: repos

repos:
  - name: my-lib
    path: repos/my-lib
    url: https://github.com/org/my-lib.git
    repo_type: library
    base_branch: main
    pr_target_branch: main
    install: uv sync --all-extras
    test: uv run pytest -v
    lint: uv run pre-commit run --all-files
    depends_on: []
```

## 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
