Metadata-Version: 2.4
Name: moonbear-app-launcher
Version: 1.0.0
Summary: Shared startup layer for local FastAPI and Uvicorn applications.
Author: MoonBlack87
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/MoonBlack87/moonbear-app-launcher
Project-URL: Repository, https://github.com/MoonBlack87/moonbear-app-launcher
Project-URL: Documentation, https://github.com/MoonBlack87/moonbear-app-launcher/tree/main/docs
Project-URL: Issues, https://github.com/MoonBlack87/moonbear-app-launcher/issues
Project-URL: Security, https://github.com/MoonBlack87/moonbear-app-launcher/security/policy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: uvicorn>=0.23
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: demo
Requires-Dist: fastapi>=0.100; extra == "demo"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Dynamic: license-file

# 🐻 Moonbear App Launcher

Shared startup layer for local Moonbear FastAPI/Uvicorn applications.

It keeps application CLIs small by centralizing:

- the Moonbear startup card;
- Uvicorn startup;
- quiet default logging and `--log` diagnostics;
- browser opening;
- common serve flags;
- project metadata loaded from `pyproject.toml`.

## Installation

Published package:

```bash
pip install moonbear-app-launcher
# or
uv add moonbear-app-launcher
```

For local development with a neighboring checkout:

```toml
[project]
dependencies = ["moonbear-app-launcher"]

[tool.uv.sources]
moonbear-app-launcher = { path = "../moonbear-app-launcher", editable = true }
```

## Project configuration

```toml
[project]
name = "example-app"
version = "1.0.0"
description = "Short public project description."

[project.urls]
Repository = "https://github.com/example/example-app"
Documentation = "https://example.github.io/example-app/"
Issues = "https://github.com/example/example-app/issues"

[tool.moonbear-app-launcher]
display-name = "Example App"
tagline = "A short product tagline."
app = "backend.main:app"
host = "127.0.0.1"
port = 8000
open-browser = true
log-dir = "logs"
activity-ignore-paths = ["/api/jobs/active"]
accent = "#2dd4bf"
```

Only `project.name`, `project.version`, and `tool.moonbear-app-launcher.app` are
required. Other launcher values have sensible defaults.

## CLI integration

```python
from moonbear_app_launcher import add_serve_arguments, serve_project

serve = sub.add_parser("serve", help="Start the server")
add_serve_arguments(serve, project_root=config.project_root())


def _serve(args: argparse.Namespace) -> int:
    return serve_project(
        args,
        project_root=config.project_root(),
        runtime_info={"Data": config.data_dir()},
    )
```

The launcher provides `--host`, `--port`, `--no-browser`, `--log`, and
`--reload`.

Application-specific checks should stay in the application. For example, a
project may perform its own network-exposure warning before calling
`serve_project(...)`.

## Runtime behavior

Normal mode prints one static card after the server is ready. Uvicorn access
logging is disabled, the file log stores errors only, and browser-launch
failures are silent.

```text
╭──────────────────────────────────────────────────────────────────────────╮
│                 🐻  MOONBEAR APPS · EXAMPLE APP  v1.0.0                 │
│                       A short product tagline.                            │
│                                                                          │
│  ● running                                                               │
│  http://127.0.0.1:8000                                                   │
│                                                                          │
│  Runtime                                                                 │
│  Data           <data directory>                                         │
│  Log file       <project>/logs/Example-App.log                           │
│                                                                          │
│  Project                                                                 │
│  Repository     https://github.com/example/example-app                   │
│                                                                          │
│  Ctrl+C to stop  ·  restart with --log for diagnostics                   │
╰──────────────────────────────────────────────────────────────────────────╯
```

`--log` enables the live diagnostics card, request count, recent activity, and
INFO/access logging. Query strings are removed from access-log entries before
they are displayed or written.

Project URLs are plain text: no OSC-8 terminal links and no underline styling.

## Development

```bash
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
python -m build
python -m twine check dist/*
```

CI runs the full verification on Python 3.12 and the tests once more on the
minimum supported version, Python 3.10.

## Documentation

- [Configuration reference](docs/configuration.md)
- [Integration example](docs/integration.md)
- [Security policy](SECURITY.md)

## Release

The package version is defined in `pyproject.toml`. Release tags must match it,
for example `v1.1.0`. The publish workflow uses PyPI Trusted Publishing.
