furtka-apps/CHANGELOG.md

# Changelog

All notable changes to the Furtka apps catalog will be documented here.
Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
Versioning: CalVer (`YY.N`) — same scheme as the core Furtka repo.

## [Unreleased]

### Added

- **Mosquitto** (v1.0.0, image `eclipse-mosquitto:2.0`). MQTT broker, the
  first *dependency provider* in the catalog. Auth is mandatory
  (`allow_anonymous false`); the broker ships no hand-managed accounts.
  Instead it carries two hook scripts (`scripts/provision-client.sh`,
  `scripts/ensure-client.sh`) that any consumer app references from its
  `requires` block — they run inside the mosquitto container, create a
  per-consumer `mosquitto_passwd` account, and hand the credentials back to
  the consumer. One Docker volume (`data`) for persistence + the password
  file + a provider-side password stash so `on_start` can restore an account
  after a volume wipe. The `ensure-client.sh` hook prefers the consumer
  password that post-26.17 core injects as `FURTKA_CONSUMER_ENV_MQTT_PASS` and
  falls back to the stash on 26.17, so it works on both. Publishes 1883 on the
  host so consumers in separate compose projects can reach it via
  `host.docker.internal`.
- **Zigbee2MQTT** (v1.0.0, image `koenkk/zigbee2mqtt:1.42.0`). First
  *dependency consumer*: `requires` mosquitto, so installing it pulls the
  broker in automatically and wires up MQTT credentials with no manual config.
  MQTT settings are injected via `ZIGBEE2MQTT_CONFIG_*` env from the hook
  output; the Zigbee USB coordinator path is a `text` setting
  (`ZIGBEE_SERIAL_PORT`) mapped through `devices:`. Frontend on host port 8084
  (8080 is taken by it-tools). Needs a physical Zigbee coordinator to fully
  start; the MQTT-credential handshake is observable without one.
- These two are the catalog's first real exercise of core 26.17's app-to-app
  dependency feature — until now every catalog app was standalone. Building
  them surfaced three framework limitations now documented in
  [apps/README.md](apps/README.md#gotchas-learned-building-mosquitto--zigbee2mqtt):
  `on_start` can't talk back to the consumer, there is no shared app network,
  and there is no device/serial setting type.

### Changed

- **Bumped the vendored `scripts/vendor/furtka_manifest.py`** from the
  26.10-era copy to core 26.17, so the catalog validator actually understands
  and validates the `requires` / `on_install` / `on_start` schema instead of
  silently ignoring it.
- **CI now shellchecks app hook scripts** (`apps/*/scripts/*.sh`), not just
  the repo-root `scripts/`.

## [26.12-alpha] - 2026-04-28

### Added

- **Home Assistant** (v1.0.0, image `homeassistant/home-assistant:stable`,
  daniel/furtka-apps#1). Smart-home hub for lights, sensors, and locally
  controlled devices. Bridge-mode networking with explicit `8123:8123`
  port mapping for v1 — Cloud integrations (Hue Cloud, Tado, Sonos via
  account) work, mDNS/Bluetooth/Zigbee-stick discovery deferred until a
  manifest `network_mode` knob lands. One Docker volume (`config`),
  no manifest settings — onboarding (admin user, home location, units)
  happens in the browser on first visit to `:8123`.

## [26.11-alpha] - 2026-04-21

### Fixed

- **Jellyfin compose default-substitution.** Without an `.env` in the
  jellyfin app dir the CI validator's `docker compose config` step
  substituted an empty `${MEDIA_PATH}` into `:/media:ro` — which
  compose rejects as `empty section between colons`. Changed the
  spec to `${MEDIA_PATH:-/nonexistent}:/media:ro` so the CI syntax
  check always sees a valid volume even with no env file. Real
  install flow (form fill → .env with user path) is unchanged; a
  broken install that reaches `docker compose up` with no
  MEDIA_PATH now fails loudly on a nonexistent bind target instead
  of silently mounting something random.

## [26.10-alpha] - 2026-04-21

### Added

- **Jellyfin** (v1.0.0, image `jellyfin/jellyfin:latest`). Media
  server for movies, shows, music on the LAN. First app to use the new
  `path`-type setting (core ≥ 26.10-alpha): the user picks their
  existing media folder in the install form (`MEDIA_PATH=/mnt/media`),
  the installer validates the path server-side, and docker-compose
  mounts it read-only at `/media`. Docker-managed volumes handle
  `/config` and `/cache`. Admin account bootstraps from the first
  browser visit to port 8096. Ports: 8096. No HW transcoding yet —
  that's a later schema extension.

### Changed

- Vendored manifest schema (`scripts/vendor/furtka_manifest.py`)
  caught up to core 26.10-alpha: adds the `open_url` field (missing
  since 26.6-alpha cut) and the new `path` setting type. `validate-
  catalog.py` now accepts path-type settings without changes.

## [26.9-alpha] - 2026-04-21

### Added

- **IT-Tools** (v1.0.0, image `corentinth/it-tools:latest`). A browser
  toolbox: password/UUID/QR generators, hash and HMAC, Base64 / URL /
  JWT decoders, JSON/YAML/SQL formatters, regex tester, cron parser,
  subnet calculator, and the usual long tail. Runs fully client-side —
  no state, no volumes, no settings. Serves on port 8080.

## [26.8-alpha] - 2026-04-21

### Changed

- **fileshare** bumped to v0.1.2: adds `open_url` (`smb://{host}/files`)
  so the core UI can render an Open button that deep-links to the share.
- **Uptime Kuma** bumped to v1.0.1: adds `open_url`
  (`http://{host}:3001/`) for the same UI Open button. No image or
  compose changes.

## [26.7-alpha] - 2026-04-20

### Added

- **Uptime Kuma** (v1.0.0, image `louislam/uptime-kuma:1`). Self-hosted
  status monitor — pings hosts, checks HTTPS endpoints, watches Docker
  containers, and screams on Telegram/webhook when something breaks.
  No manifest settings: the admin account is created on the first
  browser visit to port 3001. Persists history + config via one
  namespaced volume `furtka_uptime-kuma_data`.

## [26.6-alpha] - 2026-04-20

### Added

- Initial catalog release. Carries one app: **fileshare** (v0.1.1, SMB
  share over `dperson/samba`). Copied from the `daniel/furtka` seed so
  boxes on 26.6 see the same fileshare bits whether they pull the
  catalog or fall back to the bundled seed.
- Release pipeline + CI parity with the core repo:
  `scripts/build-catalog-tarball.sh`, `scripts/publish-catalog-release.sh`,
  `scripts/validate-catalog.py` (CI guardrail — loads every manifest via
  the vendored `furtka.manifest.load_manifest` + cross-checks compose
  volume references).

[Unreleased]: https://forgejo.sourcegate.online/daniel/furtka-apps/compare/26.12-alpha...HEAD
[26.12-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.12-alpha
[26.11-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.11-alpha
[26.10-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.10-alpha
[26.9-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.9-alpha
[26.8-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.8-alpha
[26.7-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.7-alpha
[26.6-alpha]: https://forgejo.sourcegate.online/daniel/furtka-apps/releases/tag/26.6-alpha