Metadata-Version: 2.4
Name: wetlands-launcher
Version: 0.3.9
Summary: Auto-updating application launcher with Python environment management
Requires-Python: >=3.10
Requires-Dist: cryptography>=42.0
Requires-Dist: keyring>=24.0
Requires-Dist: packaging>=24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: toml>=0.10
Requires-Dist: typing-extensions>=4.0
Requires-Dist: wetlands>=2.4.0
Provides-Extra: qt
Requires-Dist: pyside6>=6.0; extra == 'qt'
Provides-Extra: textual
Requires-Dist: textual>=0.40; extra == 'textual'
Description-Content-Type: text/markdown

# Launcher

Launcher is a small stable executable that starts and updates a Python desktop app.

You package and sign Launcher when the executable, bundled config, icon, or launcher tooling changes.
Your app code ships separately as signed GitHub or GitLab release assets.

That split keeps normal app releases small:

- the launcher executable is the durable file users install;
- the app release archive is the versioned source bundle Launcher downloads, verifies, installs, and runs;
- the signed manifest tells Launcher which archive belongs to each app release.

## Minimal Workflow

Initialize an app repository:

```bash
uv add --dev wetlands-launcher
uv run launcher init --name MyApp --repository https://github.com/my-org/myapp.git
uv run launcher config check
uv run launcher release keygen
```

Release commands read the static `[project].version` from the TOML file named by `configuration` and use that exact value as the release tag.
Set `release.tag_template: "v{version}"` only when the repository deliberately uses prefixed tags.
Explicit version arguments remain available for dynamic or non-TOML projects and must match inferred values when both are present.

Build the launcher executable when it changes:

```bash
uv run --with pyinstaller launcher build
# sign/notarize the built launcher here
uv run launcher build package
uv run launcher release create --tag --push --notes-text "Release 1.2.3"
uv run launcher release archive
uv run launcher release sign
uv run launcher release verify
uv run launcher release upload
uv run launcher build upload
```

Supply PyInstaller through the same `uv run` invocation so it can import the installed `launcher` package.
The build command rejects a `pyinstaller` executable that is present only on `PATH` because it may belong to another Python environment and produce an incomplete launcher.

Use one provider release per version and upload each macOS, Windows, or Linux launcher package as a separate platform-named asset.
Each successful `launcher build upload` updates `packaging/launcher/distribution.yml`; commit and push that file before building on the next machine.
After the final platform upload, update the existing release with links for every recorded platform:

```bash
uv run launcher release update-notes --notes-text "Release 1.2.3"
```

Publish a normal app-only release:

```bash
uv run launcher release create --tag --push --notes-text "Release 1.2.3"
uv run launcher release archive
uv run launcher release sign
uv run launcher release verify
uv run launcher release upload
```

Only run `launcher build package` and `launcher build upload` for releases where the launcher executable changed.
For ordinary app changes, publish the app archive, manifest, and signature.

## Learn More

- [Packaging guide](docs/packaging.md)
- [Configuration guide](docs/configuration.md)
- [Security guide](docs/security.md)

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
```
