# pipelines/songs

Publishes lyric pages from `mikkeli/ncmr-songs` to `https://wiki.novoyuuparosk.org`.

For the source-file contract (frontmatter and body conventions), see [SCHEMA.md](SCHEMA.md). This README covers the pipeline implementation and its runtime.

## v1 scope

Implemented:

- YAML frontmatter parsing per [SCHEMA.md](SCHEMA.md)
- Pandoc-based markdown → wikitext body rendering
- First-line h1 stripping
- Auto-generated banner + album category injection
- MediaWiki bot API write with idempotency (no-op edits skipped)

Deferred (schema reserves the fields; renderer doesn't yet act on them):

- LRC parsing and embedding
- Inter-page sibling placeholder resolution
- Multi-language metadata (the body conveys what languages exist; renderer doesn't introspect)
- Auto-generated album index pages (intentionally NOT done — user writes album category-page descriptions freeform)

## Invocation

The pipeline is invoked via a reusable Gitea Actions workflow (`/.gitea/workflows/publish-songs.yml` in this repo). The `ncmr-songs` repo holds a thin stub workflow that calls into this one on push to `master`.

Required environment at runtime:

| Variable | Source | Purpose |
|---|---|---|
| `WIKI_API_URL` | Gitea variable | MediaWiki action API endpoint |
| `WIKI_BASE_URL` | Gitea variable | Wiki base URL (used in the banner link) |
| `WIKI_BOT_USER` | Gitea secret | Bot login (`Dubrowski@giteaAutomaton`) |
| `WIKI_BOT_PASSWORD` | Gitea secret | BotPasswords value |
| `SOURCE_DIR` | workflow input | Path to checked-out `ncmr-songs` working tree |
| `SOURCE_REF` | workflow input | The pushed-to commit SHA |
| `SOURCE_BASE_REF` | workflow input | The SHA prior to the push (for diff-based change detection) |

## Dependencies

- Python 3.12+
- Pandoc 2.x or newer (apt-installable in the runner container)
- `mwclient` or `requests` for the MediaWiki API
- `PyYAML` for frontmatter parsing
- `python-frontmatter` (convenience wrapper around PyYAML for markdown frontmatter)

`requirements.txt` will be added when the implementation lands.

## One-off wiki setup

Before the first run, two things must exist on the wiki:

1. **`Template:Auto-generated`** — the banner injected at the top of every auto-published page. Wikitext for this template is included in the implementation step (not yet written).
2. **The bot user has edit rights** for the namespace(s) the pipeline writes to. The default main namespace is fine; verify by attempting a manual edit via the bot account before relying on the pipeline.

## Modes

The pipeline supports two invocation modes via the entry point:

- **Incremental** (default, triggered by push): publishes only files changed between `SOURCE_BASE_REF` and `SOURCE_REF`.
- **Full** (`--all` flag, triggered by `workflow_dispatch`): re-publishes every publishable file in the source tree. Use after template or renderer changes.

## Not yet implemented

This README will grow as the pipeline does. Current commit ships only the schema and this overview — no executable code yet.