Metadata-Version: 2.4
Name: esys-gitlog
Version: 0.3.0
Summary: Python implementation of git elog
Author: Project maintainers
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: standalone
Requires-Dist: pyinstaller>=6.0; extra == "standalone"
Dynamic: license-file

# esys-gitlog

Python implementation of `git elog`. The distribution name is `esys-gitlog`. The import package is `esys_gitlog`. Installed commands: `git-elog` (so Git can run `git elog`) and the shorter alias `elog`. Prefer `elog --help` — `git elog --help` is handled by Git's own help path, not the Typer CLI.

The shared contract lives in `esys-gitlog-spec`. This repository carries that contract in Python. It does not define a second one.

## Smoke

```bash
pip install .
elog --help
elog --json
```

`--json` writes one QA report document to stdout. The first skeleton returns an empty `commits` array.

## Release / publish

Tag-driven CI publishes to GitLab Package Registry, TestPyPI, then PyPI (Deckicorn-style ADR-0009 flow). See [docs/release-pipeline.md](docs/release-pipeline.md).

```bash
python scripts/publish_release.py --dry-run --bump patch
python scripts/build_package.py
python scripts/smoke_install_package.py --dist dist --expected-version 0.1.0
```

## Preferences and profiles

Layered tool preferences (user → `.tools/esys/esys-gitlog/` → `.tools_local/…`)
and named profiles follow root SADR-0009 / SADR-0010 and contract CADR-0012.

```bash
elog --preferences path.json   # preference overlay
elog --profile acme            # built-in or profiles/acme.json
elog --config path/profile.json  # one-off profile file
elog preferences detect        # probe jira-cli/acli + git remote; write missing user keys
elog preferences detect --json --no-write   # machine-readable candidates (extension setup)
elog preferences set-link jira-id 'https://host/browse/{id}'
elog preferences clear-link jira-id
elog preferences set-tool jira 'C:\tools\jira.exe'   # optional absolute path
elog preferences set-tool acli /usr/local/bin/acli
```

Jira browse bases come from local **jira-cli** config and/or **Atlassian acli**
(`acli jira config get site`), never from per-commit HTTP (SADR-0010). Detection
only fills unset user keys unless you use `set-link`. Absolute paths live under
`detection.jiraExecutable` / `detection.acliExecutable` when the tools are not
on `PATH`.

### Live Jira fixture (SCRUM)

The free site [libesys.atlassian.net](https://libesys.atlassian.net/browse/SCRUM-1)
uses project key **`SCRUM`** only (do not invent other project keys).

1. Configure acli or jira-cli against that site (optional absolute paths via
   `elog preferences set-tool`).
2. Seed once (creates 10 new issues, writes the pin — not part of every CI run):

```bash
python scripts/seed_jira_live_fixture.py --project SCRUM --count 10
```

3. Commit `tests/integration/jira_live.pin.json`.
4. Materialize a durable Git repo for the VS Code extension / manual checks:

```bash
python scripts/materialize_jira_live_repo.py
```

   Output: `tests/integration/jira_live_repo/` (gitignored except a placeholder
   README). Open that folder, store the browse template, refresh the commit browser.
5. Run the live test locally or enable GitLab variable `ESYS_GITLOG_JIRA_LIVE=1`
   for job `test:jira-live`:

```bash
ESYS_GITLOG_JIRA_LIVE=1 pytest -m jira_live -o addopts= --no-cov
```

Default `pytest` excludes `@pytest.mark.jira_live` so coverage stays offline.

## Standalone binary (optional)

The primary install remains the wheel + `git-elog` / `elog` console scripts. For a
frozen one-file binary (for example Cursor `esysGitlog.executablePath` without
a Python env on PATH):

```bash
python scripts/build_standalone.py
```

Output: `dist/git-elog.exe` (Windows) or `dist/git-elog` (Linux/macOS). Build on
the OS you need — this does not cross-compile.

- [Architecture](docs/architecture/overview.md)
- [ADRs](docs/adr/INDEX.md)
- [ASRs](docs/asr/INDEX.md)
- [Implementation plan](plans/implementation.md)
