Metadata-Version: 2.4
Name: esysrepo-ctl
Version: 0.2.2
Summary: Control-plane tool for managing the native esysrepo CLI
Author: Project maintainers
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"

# esysrepo-ctl

Control-plane tool for installing, updating, diagnosing, and managing the native
`esysrepo` CLI (distributed via Conan). Distributed as a Python package on PyPI.

Native repository operations use `esysrepo` / `erepo` (from the Conan package).
This tool only manages the lifecycle of that native CLI.

## Install

```bash
pipx install esysrepo-ctl
```

Or from a development checkout:

```bash
python -m pip install -e ".[dev]"
```

Both `esysrepo-ctl` and `erepo-ctl` are equivalent entry points.

Then install the native CLI (first run bootstraps a Python env + Conan 2 per
[ADR-0008](docs/adr/0008-dual-mode-python-venv-isolation.md)):

```bash
# Interactive: detect mode, confirm, persist
esysrepo-ctl install

# Non-interactive installer-like (managed home venv + always-on wrappers)
esysrepo-ctl install --mode managed --yes

# Project-private: activate your venv first, then:
esysrepo-ctl install --mode project --yes
```

| Mode | Conan lives in | Native `esysrepo` / `erepo` wrappers |
|------|----------------|--------------------------------------|
| `project` | Active project venv | That venv’s `bin` / `Scripts` (while activated) |
| `pipx` | Managed home venv | Managed `…/esysrepo-ctl/bin` |
| `managed` | Managed home venv | Managed `…/esysrepo-ctl/bin` |

Overrides: `ESYSREPO_CTL_MODE`, `ESYSREPO_CTL_YES=1`, `--reconfigure` (ignore
persisted mode). Choice is persisted under `ESYSREPO_CTL_HOME` / platform data
dir (`config.json`).

## Commands

| Command | Purpose |
|---------|---------|
| `install` | Install the native `esysrepo` CLI via Conan |
| `update` | Update the native CLI (auto-bootstraps when allowed) |
| `remove` | Remove the native CLI from the Conan cache |
| `doctor` | Diagnose environment, PATH, and compatibility |
| `version` | Print control-plane and native CLI versions |

```bash
esysrepo-ctl --help
esysrepo-ctl version
esysrepo-ctl doctor
esysrepo-ctl install
esysrepo-ctl install --mode managed --yes
esysrepo-ctl install --mode project --yes --reconfigure
esysrepo-ctl install --version 0.2.4
esysrepo-ctl --channel center install   # unnamed Conan Center-style refs
esysrepo-ctl update
esysrepo-ctl remove
```

## Conan channel (ADR-0007)

By default, package refs use LibESys Artifactory identity:

`esysrepo-cli/<version>@libesys/stable`

| Mode | How | Package ref shape |
|------|-----|-------------------|
| `libesys` (default) | `--channel libesys` or unset | `…@libesys/stable` |
| `center` | `--channel center` or `ESYSREPO_CTL_CHANNEL=center` | unnamed (`esysrepo-cli/<ver>`) |

Configure the LibESys Conan remote yourself (or via CI vars `CONAN_REMOTE_URL` /
`CONAN_LOGIN_USERNAME` / `CONAN_PASSWORD`). Install writes VirtualBuildEnv +
VirtualRunEnv under the managed data dir and places wrappers per mode (above);
`doctor` / discovery look at PATH, project `Scripts`/`bin`, and the managed bin.

## Strict mode / no auto-bootstrap

By default, eligible commands (currently `update`) may auto-install the native CLI when
it is missing (ADR-0005). Disable that with:

```bash
esysrepo-ctl --no-bootstrap update
# or
esysrepo-ctl --strict update
```

Auto-bootstrap is also disabled when any of these are set:

- `CI=true` (typical CI environments)
- `ESYSREPO_CTL_NO_BOOTSTRAP=1`
- `ESYSREPO_CTL_STRICT=1`

Explicit `install` / `remove` / `doctor` / `version` never trigger implicit install.

## Exit codes

Stable codes for scripting (ADR-0006):

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad arguments / unknown command) |
| 3 | Native `esysrepo` / `erepo` missing |
| 4 | Auto-bootstrap failure |
| 5 | Conan failure |
| 6 | Environment / compatibility error |

Errors print to stderr as `error: …` with optional `hint: …` remediation lines.

## Troubleshooting

| Symptom | What to try |
|---------|-------------|
| `doctor` reports Conan missing | Install Conan 2 and ensure `conan` is on `PATH` (or re-run `esysrepo-ctl install --mode … --yes` so ctl bootstraps Conan into the chosen venv) |
| `doctor` reports esysrepo missing | `esysrepo-ctl install` then re-check `doctor` / `version` |
| Install/update fails talking to remotes | `conan remote list`, fix auth/network, retry |
| Package installed but CLI not found | Check managed bin (`esysrepo-ctl doctor`) and Conan remotes |
| Wrong package identity / not found | Use default `--channel libesys` for Artifactory; ensure remote is configured |
| CI must not mutate the environment | Use `--no-bootstrap` or rely on `CI=true` |
| `where esysrepo` lists `~/.conan2/…/bin` before the venv wrapper | Shell PATH is polluted (Conan cache bins first), so Windows never runs the `.bat`. **cmd.exe:** `set "PATH=%VIRTUAL_ENV%\\Scripts;%PATH%"` then `where esysrepo` — or `call "%VIRTUAL_ENV%\\Scripts\\_esysrepo_ctl_fix_path.bat"`. **PowerShell:** `$env:PATH = (@("$env:VIRTUAL_ENV\\Scripts") + ($env:PATH -split ';' \| ? { $_ -notmatch '\\.conan2' })) -join ';'`. Or deactivate/reactivate the venv after `esysrepo-ctl install --mode project --yes`. |

```bash
esysrepo-ctl doctor
esysrepo-ctl version
```

## Documentation

- [Architecture overview](docs/architecture/overview.md)
- [CLI specification](docs/architecture/cli-spec.md)
- [Quality requirements](docs/architecture/quality-requirements.md)
- [ADRs](docs/adr/README.md)
- [MVP implementation plan](plans/0001-mvp-implementation.md)

## Development

```bash
python scripts/setup-dev.sh   # or scripts/setup-dev.ps1 on Windows
pytest
pre-commit run --all-files
```
