Metadata-Version: 2.4
Name: luxforge
Version: 0.2.0
Summary: Shared foundation library for LuxForge software
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: postgres
Requires-Dist: psycopg2-binary<3,>=2.9.10; extra == "postgres"
Provides-Extra: runtime
Requires-Dist: fastapi>=0.110; extra == "runtime"
Requires-Dist: uvicorn[standard]>=0.29; extra == "runtime"
Requires-Dist: psutil>=5.9; extra == "runtime"
Requires-Dist: pyyaml>=6.0; extra == "runtime"

# LuxForge Foundry

**Foundry** is the shared Python foundation for LuxForge applications.

It provides reusable capabilities that would otherwise be reimplemented across projects — logging, file handling, database utilities, terminal components, shared helpers, and other common application infrastructure.

The package is distributed publicly as **`luxforge`** while exposing the **`foundry`** Python namespace.

**Documentation:** see [`docs/`](docs/) — how to use Foundry, how to use
`@luxforge/framework`, and the LuxFilm demo app both are proven against.

## Installation

Install the latest public release from PyPI:

```bash
pip install luxforge
```

Install the supported PostgreSQL and database-lifecycle facilities with:

```bash
pip install "luxforge[postgres]"
```

Then import only the capabilities you need:

```python
from foundry.logger import logger
```

For local Foundry development:

```bash
git clone <repository-url>
cd Foundry
pip install -e .
```

## What Foundry Provides

Foundry is intended to be a collection of independently reusable capabilities rather than a framework that applications must adopt wholesale.

Current areas include:

* **Logging** — shared structured logging through `foundry.logger`
* **Files** — common file reading, writing, and discovery utilities
* **PostgreSQL** — connections, transactions, COPY, introspection, managers, durable SQL resources, dependency ordering, managed imports, checksums, validation, and guarded lifecycle operations
* **Colours** — shared colour and terminal presentation utilities
* **Menu** — reusable terminal menu and input handling
* **Utilities** — common helpers used across LuxForge software

Applications can use a single Foundry capability without needing to initialise or depend on the rest of the library.

For example:

```python
from foundry.logger import logger

logger.info("Application started")
```

## Package Structure

Foundry uses a standard `src`-based Python package layout:

```text
src/
└── foundry/
    ├── colours/
    ├── files/
    ├── logger/
    ├── menu/
    ├── postgres/
    │   └── lifecycle/
    └── utils/
```

See [`docs/builtin/foundry/postgres.md`](docs/builtin/foundry/postgres.md)
for the supported PostgreSQL API and complete lifecycle model.

The public import namespace is deliberately kept separate from the distribution name:

```text
PyPI distribution:  luxforge
Python namespace:    foundry
```

This means consumers install:

```bash
pip install luxforge
```

and use:

```python
from foundry.logger import logger
```

## Development

Run the Foundry health check:

```powershell
pwsh .\tooling\build\check.ps1
```

A successful check reports:

```text
BUILD STATUS: GREEN
```

Build the package with:

```powershell
pwsh .\tooling\build\build.ps1
```

The build process produces both a wheel and source distribution under `dist/`.

Release builds are verified by installing the generated wheel into a clean environment and testing the public Foundry imports before publication.

### Running LuxFilm with Docker

LuxFilm (`packages/framework/demo`) — Foundry's own `@luxforge/framework` proving ground — can run as two containers: the Foundry Runtime API and the built frontend, served by nginx.

```bash
docker compose -f docker/compose.yaml build
docker compose -f docker/compose.yaml up -d
docker compose -f docker/compose.yaml down
```

* Frontend: http://localhost:8080
* API: http://localhost:8420 (`/foundry/*`)

Environment variables (set in `docker/compose.yaml`, or override via `docker compose -f docker/compose.yaml run -e ...` / a `.env` file compose picks up automatically):

* `FOUNDRY_RUNTIME_HOST` / `FOUNDRY_RUNTIME_PORT` — what the API binds to inside its container. Defaults to `0.0.0.0:8420`; a container needs this bind (unlike a bare-metal dev machine) since the port mapping, not the app's own bind address, is what controls real exposure.
* `FOUNDRY_ALLOWED_ORIGINS` — CORS origins the API accepts, since the browser calls it directly from the frontend's own origin (a different port). Defaults to `http://localhost:8080`.
* `VITE_API_URL` — a frontend **build** argument (`docker/compose.yaml`'s `frontend.build.args`), baked into the static output at build time. Where the browser reaches the API; defaults to `http://localhost:8420`.

If you change host ports in `docker/compose.yaml`, update `FOUNDRY_ALLOWED_ORIGINS` and `VITE_API_URL` to match — otherwise the frontend and API can't talk to each other.

This is local/demo tooling, not a production deployment topology — see `foundry.runtime`'s own docs for why Foundry Runtime is normally mounted into a host application rather than run as its own public service.

## Releases

Foundry has a guided release process:

```powershell
pwsh .\tooling\release.ps1
```

The release tooling validates the repository, version, package, tests, Git state, built artifacts, and installed wheel before creating and publishing a release.

Releases are distributed to:

* **PyPI** — public distribution as `luxforge`
* **Azure Artifacts** — LuxForge package feed

Public installation therefore requires no LuxForge-specific package configuration:

```bash
pip install luxforge
```

## Direction

Foundry exists to make common LuxForge capabilities something that is **built once, tested once, and reused everywhere**.

As shared functionality matures, it belongs in Foundry rather than being independently recreated inside each application.
