Metadata-Version: 2.4
Name: fecreator
Version: 0.1.0
Summary: Local-first Fire Emblem portrait creation workbench
Author: laqieer
License: MIT
Requires-Python: <3.14,>=3.11
Requires-Dist: fastapi<0.140,>=0.115
Requires-Dist: mcp<2,>=1.10
Requires-Dist: numpy<3,>=2.1
Requires-Dist: opencv-python-headless<5.1,>=4.10
Requires-Dist: pillow<13,>=11.0
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: python-multipart<1,>=0.0.20
Requires-Dist: uvicorn[standard]<0.52,>=0.30
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: ggshield<2,>=1.52; extra == 'dev'
Requires-Dist: hatchling<2,>=1.25; extra == 'dev'
Requires-Dist: httpx<0.29,>=0.27; extra == 'dev'
Requires-Dist: mypy<3,>=1.13; extra == 'dev'
Requires-Dist: numpy<2.5,>=2.1; extra == 'dev'
Requires-Dist: pre-commit<5,>=4; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=8.2; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

# FECreator

Local-first, agent-neutral, provider-neutral Fire Emblem **portrait** creation
workbench with deterministic imaging, immutable jobs/lineage, human review, and a
`fe-gba-portrait-standard` export compatible with FEBuilderGBA (file-based, ROM-free).

See `docs/product-statement.md` for scope and `docs/architecture.md` for the module map.
The frozen v1 public surface — contracts, HTTP routes, CLI commands, MCP tools,
capability semantics, and the compatibility policy — is in
[`docs/v1-contract.md`](docs/v1-contract.md).
FEBuilderGBA compatibility evidence levels (mandatory deterministic proof, optional
CLI validation, opt-in local ROM checks) are documented in
[`docs/febuilder-interop.md`](docs/febuilder-interop.md).

## Getting started

Supported runtimes are Python 3.11-3.13 and Node.js 20.19-24. Run everything from
the repository root.

```powershell
python -m pip install -e ".[dev]"
npm ci
pre-commit install
```

Build the web bundle before packaging or serving; the generated
`src/fecreator/_web` directory is ignored and must never be committed.

```powershell
# Local app: root-relative assets, written into src/fecreator/_web
npm run -w @laqieer/fecreator-web build
python -m build

# GitHub Pages demo: assets use the /FECreator/ base path
npm run -w @laqieer/fecreator-web build:demo
```

Run the local workbench (loopback only, `FECREATOR_DATA_ROOT` required):

```powershell
$env:FECREATOR_DATA_ROOT = "$PWD\data"
fecreator serve
```

## Checks

```powershell
# Python
ruff check .
ruff format --check .
mypy src
pytest -q

# Web
npm run -w @laqieer/fecreator-web typecheck
npm run -w @laqieer/fecreator-web lint
npm run -w @laqieer/fecreator-web test

# Browser end-to-end flows (builds the local and demo bundles first)
npx playwright install chromium
npm run -w @laqieer/fecreator-web test:e2e
```

Set `FECREATOR_PYTHON` when the interpreter that has FECreator installed is not
`python`; a path containing spaces is quoted automatically, and an already quoted
value is accepted as-is.

CI runs `python`, `web`, `browser`, `package`, `febuilder-interop`, and
`secret-scan` on every push and pull request. The GitHub Pages deployment is
limited to successful `main` pushes and depends on all six. The optional external
FEBuilder-compatible check runs only when the `FEBUILDER_CLI` repository variable
is set; no gate ever requires a ROM.

## Releasing

Releases go to PyPI through Trusted Publishing (OIDC); no PyPI API token exists
in this repository. Pushing a `v*.*.*` tag builds the distributions in an
unprivileged job that checks out `refs/tags/<tag>`, then publishes them from a
separate `pypi` environment job that a required reviewer must approve and that
only `v*.*.*` tags may deploy to. A manual re-run is dispatched on the tag
itself (`gh workflow run publish.yml --ref v0.1.0`).
See [`docs/pypi-publishing.md`](docs/pypi-publishing.md) for the trust boundary,
the exact pending-publisher fields, and the required environment protection.

## Live demo

A static, sample-data demo is published to GitHub Pages:

**<https://laqieer.github.io/FECreator/>**

The demo runs entirely in the browser with built-in synthetic data. It **cannot**
generate, validate, upload, or save real assets, makes no HTTP or WebSocket calls,
and resets whenever the page is reloaded. See
[`docs/github-pages-demo.md`](docs/github-pages-demo.md) for build modes and
limitations.

## Security

Secrets are guarded by layered scanning: a local
[`ggshield`](https://github.com/GitGuardian/ggshield) pre-commit hook, a
`secret-scan` CI job on pushes and internal PRs, and the GitGuardian GitHub App
for fork PRs and full history. Test fixtures that need credential *shapes* are
assembled at runtime (never stored as literals), and a regression test blocks
any literal JWT/AWS-key from re-entering the tree.

See [`docs/security.md`](docs/security.md) for the incident classification, the
required dashboard action, fork-PR limitations, and setup commands
(`gh secret set GITGUARDIAN_API_KEY --repo laqieer/FECreator`, `pre-commit
install`).
