esysrepo-ctl 0.2.0__tar.gz

esysrepo_ctl-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: esysrepo-ctl
+Version: 0.2.0
+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
+```

esysrepo_ctl-0.2.0/README.md

@@ -0,0 +1,152 @@
+# 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
+```

esysrepo_ctl-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "esysrepo-ctl"
+version = "0.2.0"
+description = "Control-plane tool for managing the native esysrepo CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Project maintainers" }]
+dependencies = [
+  "typer>=0.12",
+]
+
+[project.scripts]
+esysrepo-ctl = "esysrepo_ctl.cli:app"
+erepo-ctl = "esysrepo_ctl.cli:app"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.8",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+  "integration: live Conan/Artifactory tests (require ESYSREPO_CTL_INTEGRATION=1)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

esysrepo_ctl-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

esysrepo_ctl-0.2.0/src/esysrepo_ctl/__init__.py

@@ -0,0 +1,3 @@
+"""esysrepo-ctl — installable package."""
+
+__version__ = "0.2.0"

esysrepo_ctl-0.2.0/src/esysrepo_ctl/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m esysrepo_ctl``."""
+
+from esysrepo_ctl.cli import main
+
+if __name__ == "__main__":
+    main()

esysrepo_ctl-0.2.0/src/esysrepo_ctl/bootstrap.py

@@ -0,0 +1,156 @@
+"""Auto-bootstrap of the native esysrepo CLI (ADR-0005, ADR-0008)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from esysrepo_ctl import conan as conan_ops
+from esysrepo_ctl.compat import CompatPolicy
+from esysrepo_ctl.conan import ConanOpResult
+from esysrepo_ctl.discovery import ToolInfo, find_native_cli
+from esysrepo_ctl.exit_codes import ExitCode
+from esysrepo_ctl.python_env import wrapper_bin_dir_for_mode
+from esysrepo_ctl.toolchain import bootstrap_for_lifecycle
+
+# Subcommands that may auto-bootstrap when the native CLI is missing.
+AUTO_BOOTSTRAP_COMMANDS = frozenset({"update"})
+
+# Subcommands that never trigger implicit install.
+EXEMPT_FROM_AUTO_BOOTSTRAP = frozenset({"install", "remove", "version", "doctor"})
+
+
+@dataclass(frozen=True)
+class EnsureResult:
+    """Outcome of ensuring the native CLI is available."""
+
+    native: ToolInfo | None
+    bootstrapped: bool
+    exit_code: ExitCode
+    message: str | None = None
+    remediation: str | None = None
+    bootstrap_outcome: ConanOpResult | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code is ExitCode.SUCCESS and self.native is not None
+
+
+def bootstrap_permitted(
+    *,
+    cli_no_bootstrap: bool = False,
+    environ: Mapping[str, str] | None = None,
+) -> bool:
+    """Return whether auto-bootstrap is allowed for this invocation."""
+    env = environ if environ is not None else os.environ
+    if cli_no_bootstrap:
+        return False
+    if _truthy(env.get("ESYSREPO_CTL_NO_BOOTSTRAP")):
+        return False
+    if _truthy(env.get("ESYSREPO_CTL_STRICT")):
+        return False
+    # CI and similar non-interactive contexts default to strict (no implicit install).
+    if _truthy(env.get("CI")):
+        return False
+    return True
+
+
+def should_auto_bootstrap(command: str | None) -> bool:
+    """Return whether ``command`` is eligible for first-use auto-bootstrap."""
+    if command is None:
+        return False
+    if command in EXEMPT_FROM_AUTO_BOOTSTRAP:
+        return False
+    return command in AUTO_BOOTSTRAP_COMMANDS
+
+
+def ensure_native_cli(
+    *,
+    allow_bootstrap: bool,
+    policy: CompatPolicy | None = None,
+) -> EnsureResult:
+    """Detect the native CLI and optionally install it when missing.
+
+    When ``allow_bootstrap`` is false (strict / ``--no-bootstrap`` / CI), a missing
+    native CLI yields :attr:`ExitCode.MISSING_NATIVE_CLI` without changing the
+    environment.
+    """
+    native = find_native_cli()
+    if native is not None:
+        return EnsureResult(
+            native=native,
+            bootstrapped=False,
+            exit_code=ExitCode.SUCCESS,
+        )
+
+    if not allow_bootstrap:
+        return EnsureResult(
+            native=None,
+            bootstrapped=False,
+            exit_code=ExitCode.MISSING_NATIVE_CLI,
+            message="native esysrepo CLI is not installed",
+            remediation=(
+                "Install explicitly with `esysrepo-ctl install`, or re-run without "
+                "`--no-bootstrap` / strict mode to allow auto-bootstrap."
+            ),
+        )
+
+    try:
+        # Auto-bootstrap already implies consent; skip interactive mode confirm.
+        info, conan = bootstrap_for_lifecycle(yes=True)
+    except RuntimeError as exc:
+        return EnsureResult(
+            native=None,
+            bootstrapped=False,
+            exit_code=ExitCode.ENVIRONMENT_ERROR,
+            message=str(exc),
+            remediation=(
+                "Set `--mode project|pipx|managed --yes` or ESYSREPO_CTL_MODE / "
+                "ESYSREPO_CTL_YES, then re-run."
+            ),
+        )
+
+    wrapper_bin = wrapper_bin_dir_for_mode(info.mode)
+    outcome = conan_ops.install(policy=policy, conan=conan, wrapper_bin=wrapper_bin)
+    if not outcome.ok:
+        return EnsureResult(
+            native=None,
+            bootstrapped=False,
+            exit_code=ExitCode.BOOTSTRAP_FAILURE
+            if outcome.exit_code is ExitCode.CONAN_FAILURE
+            else outcome.exit_code,
+            message=f"auto-bootstrap failed for {outcome.package_ref}",
+            remediation=outcome.remediation
+            or "Fix the Conan error above, then re-run or use `esysrepo-ctl install`.",
+            bootstrap_outcome=outcome,
+        )
+
+    native = find_native_cli()
+    if native is None:
+        return EnsureResult(
+            native=None,
+            bootstrapped=True,
+            exit_code=ExitCode.BOOTSTRAP_FAILURE,
+            message=("auto-bootstrap finished but esysrepo/erepo is still not discoverable"),
+            remediation=(
+                "Conan installed the package, but the native CLI was not found in PATH "
+                "or the mode-local wrapper directory. Re-run `esysrepo-ctl install` or "
+                "check doctor output."
+            ),
+            bootstrap_outcome=outcome,
+        )
+
+    return EnsureResult(
+        native=native,
+        bootstrapped=True,
+        exit_code=ExitCode.SUCCESS,
+        message=f"auto-bootstrapped native CLI ({outcome.package_ref})",
+        bootstrap_outcome=outcome,
+    )
+
+
+def _truthy(value: str | None) -> bool:
+    if value is None:
+        return False
+    return value.strip().lower() in {"1", "true", "yes", "on"}