# furtka-apps

Apps catalog for [Furtka](https://furtka.org). Each release here ships a
tarball that running Furtka boxes pull via the daily catalog-sync timer
(see `furtka.catalog` in the core repo). Apps update on their own cadence,
independent of Furtka's core OS release schedule.

## Repo layout

```
apps/                  # one folder per app
  <name>/
    manifest.json      # JSON schema — see ./apps/README.md
    docker-compose.yaml
    .env.example       # if the app has user-facing settings
    icon.svg
scripts/
  build-catalog-tarball.sh    # bundle apps/ + VERSION into furtka-apps-<ver>.tar.gz
  publish-catalog-release.sh  # upload tarball + sha256 + release.json to Forgejo
  validate-catalog.py         # CI guardrail — manifest + compose syntax
  vendor/
    furtka_manifest.py        # copy of daniel/furtka furtka/manifest.py
.forgejo/workflows/
  ci.yml             # JSON + manifest + shellcheck on every push/PR
  release.yml        # tag push → build tarball → publish to Forgejo releases
```

## Adding an app

See [apps/README.md](./apps/README.md) for the manifest schema, volume
namespacing rules, `.env.example` guardrails, and the SVG sanitiser
limits the Furtka UI enforces on `icon.svg`.

Shape of a new app PR:

1. Add `apps/<name>/` with all four files.
2. `python3 scripts/validate-catalog.py` locally — must go green.
3. Open a PR. CI runs the same validator + shellcheck.
4. Merged to `main` — next catalog release will include it.

## Cutting a release

Follows the same CalVer + tag-driven pattern as daniel/furtka:

```bash
# Bump CHANGELOG.md [Unreleased] → [<version>] section, commit:
git commit -m "chore: release <version>"
git tag -a <version> -m "Release <version>"
git push origin main
git push origin <version>
```

Tag push fires `.forgejo/workflows/release.yml`. Needs
`FORGEJO_RELEASE_TOKEN` secret (PAT with `write:repository` on this repo).

## Trust model

Releases are unsigned (SHA256 sidecar only). Boxes verify the sidecar
against the downloaded tarball before extracting anything. Same posture
as daniel/furtka core releases — PGP is a deferred cross-repo migration.

## Relationship to daniel/furtka

- The core repo still ships `apps/fileshare/` as a seed inside the
  Furtka release tarball. That's the offline/first-boot fallback.
- When a box has synced the catalog at least once, the resolver
  (`furtka.sources.resolve_app_name`) prefers the catalog copy.
- Already-installed apps don't auto-reinstall on catalog updates — user
  hits "Reinstall" in `/apps` when they want the new version. Settings
  are merge-preserved.