Flathub Maintenance

Flathub Maintenance

Manage Mini Diarium's Flatpak packaging end-to-end — from initial submission through release updates, build diagnosis, and long-term runtime maintenance.

Load These Files First

1. docs/FLATPAK_MAINTENANCE.md — file inventory, invariants, failure signatures, validation checklist, runtime docs
2. docs/releasing/RELEASING.md — "Automated Flathub Publishing" section explains the publish workflow
3. .github/workflows/flathub-publish.yml — the actual automation that generates sources and opens the Flathub PR
4. flatpak/rewrite-manifest.py — transforms the local type: dir manifest into a pinned type: git manifest
5. flatpak/io.github.fjrevoredo.mini-diarium.yml — the local Flatpak manifest (source of truth)

If any of these files are missing or unreadable, stop and tell the user.

Multi-Repo Architecture

Mini Diarium's Flatpak presence spans 3 separate systems:

The publish workflow (flathub-publish.yml) bridges main → Flathub:

1. Checkout the tagged release commit via git worktree
2. Generate cargo-sources.json and node-sources.json from lockfiles
3. Run rewrite-manifest.py to convert type: dir → type: git
4. Clone the Flathub repo, copy the 3 files, commit, push branch, open PR

Key insight for diagnosis: failures can originate in any of the 3 systems, and fixes may need to land in one or both repos.

Local Repo Discovery

Before doing any work, locate the local checkouts.

Step 1: Check for .agents/flathub-paths.md. If it exists, read the paths from it:

main_repo: /absolute/path/to/mini-diarium
flathub_repo: /absolute/path/to/flathub-repo

Step 2: If that file doesn't exist, try common locations:

• Windows: D:\Repos\mini-diarium, D:\Repos\io.github.fjrevoredo.mini-diarium
• Linux/WSL: /mnt/d/Repos/mini-diarium, /mnt/d/Repos/io.github.fjrevoredo.mini-diarium
• macOS: ~/Repos/mini-diarium, ~/Repos/io.github.fjrevoredo.mini-diarium

Step 3: If still not found, ask the user for the paths. If the user doesn't have a local Flathub repo clone, clone it:

git clone https://github.com/flathub/io.github.fjrevoredo.mini-diarium.git <path>

After discovery: offer to create .agents/flathub-paths.md so future sessions skip the search.

The Manifest

Local manifest (flatpak/io.github.fjrevoredo.mini-diarium.yml)

Uses type: dir with path: .. for local validation builds. All build command paths are relative to the repo root. For local validation:

flatpak-builder --user --install --force-clean build-dir flatpak/io.github.fjrevoredo.mini-diarium.yml
flatpak run io.github.fjrevoredo.mini-diarium

Flathub manifest (after rewrite)

The workflow replaces the type: dir source block with:

- type: git
  url: https://github.com/fjrevoredo/mini-diarium
  commit: <sha>

The rest of the manifest (build commands, finish-args, runtime) is preserved verbatim. Build command paths must work identically in both source modes.

Critical path rule

All paths in build-commands are relative to the build directory, which is the repo root in both modes. Never use ../ or nested prefixes that only resolve in one context.

Vendored sources (cargo-sources.json, node-sources.json)

These files do not exist in the main repo — they are generated artifacts:

• Generated automatically by the flathub-publish.yml workflow during a release
• Generated manually for local validation using the tools documented in FLATPAK_MAINTENANCE.md
• Never edit them by hand — they must be regenerated from lockfiles

The Flathub repo carries the generated copies alongside the manifest. When diagnosing build failures, treat these files as potentially stale if lockfiles changed without re-generation.

The generate-node-sources.mjs script

Located at flatpak/generate-node-sources.mjs. Generates node-sources.json from package-lock.json and an .npm cache.

Usage:

node flatpak/generate-node-sources.mjs package-lock.json output.json "$HOME/.npm"

How it works:

• Reads every node_modules/ entry from lock.packages that has resolved + integrity.
• For each package, computes the content file path under the npm cache. If the cache file exists, uses its size. Otherwise, makes an HTTP HEAD request to get content-length.
• Critical: many npm registry URLs do not return content-length on HEAD requests. When this happens, the script falls back to a full GET download of the tarball. This can be very slow when many packages are missing from the cache.
• Generates two JSON entries per package: a type: file content entry and a type: inline index entry. Esbuild binaries get special type: archive entries with only-arches constraints.

Fallback when generation fails:

1. Run node flatpak/check-node-sources.mjs package-lock.json node-sources.json to find all missing packages.
2. Critical: always use integrity values from package-lock.json, never from bun.lock. The two lockfiles can have different sha512 hashes for the same package@version (bun and npm may resolve different tarball contents). Using bun.lock integrity will cause "Wrong sha512 checksum" errors in vorarbeiter. Verify with: node -e "const l=JSON.parse(require('fs').readFileSync('package-lock.json','utf8')); console.log(l.packages['node_modules/<name>'].integrity)"
3. For each missing package, manually construct two entries and insert them into node-sources.json in URL-sorted order:

Content entry format:

{
  "type": "file",
  "url": "<resolved tarball URL>",
  "sha512": "<integrity hex (base64 decoded)>",
  "dest-filename": "<hex chars after position 4>",
  "dest": "flatpak-node/npm-cache/_cacache/content-v2/sha512/<hex[0:2]>/<hex[2:4]>"
}

Index entry format:

{
  "type": "inline",
  "contents": "<sha1-of-index-json>\t<index-json>",
  "dest-filename": "<sha1-of-key chars after position 4>",
  "dest": "flatpak-node/npm-cache/_cacache/index-v5/<sha1-of-key[0:2]>/<sha1-of-key[2:4]>"
}

The index JSON object is: {"key":"make-fetch-happen:request-cache:<url>","integrity":"<integrity>","time":0,"size":<tarball-size>,"metadata":{"url":"<url>","reqHeaders":{},"resHeaders":{}}}. Compute the SHA1 of the full JSON string for the contents prefix, and the SHA1 of the key string for the index path.

Critical ordering rule: When inserting entries or re-sorting, shell and script entries must always appear after ALL archive entries. flatpak-builder processes node-sources.json sequentially — a cp in a shell command that runs before its archive is extracted will fail. Only sort URL-bearing entries (type file, archive); leave shell and script entries at the end. Run node flatpak/check-node-sources.mjs after any modification to verify both coverage and ordering.

See flatpak/check-node-sources.mjs for the companion gap-detection script.

Patches in the Flathub repo

The Flathub repo may contain a patches/ directory with .patch files. These are temporary Flathub-only patches applied during the build to fix issues that haven't been fixed upstream yet. Common patch scenarios: missing metainfo fields (e.g., <url type="vcs-browser">), developer ID format fixes, AppStream compliance.

Rule: Remove patches as soon as the upstream fix is merged and the manifest can point at a commit that includes the fix. Do not carry permanent Flathub-only patches.

Common Failures → Diagnosis → Fix

1. Font install fails (files/fonts or ../fonts not found)

Symptom: install: cannot stat 'files/fonts/*.ttf': No such file or directory

Diagnosis: The manifest references a font path that doesn't exist in the source checkout. Fonts live at fonts/*.ttf in the repo root (10 .ttf files + LICENSES.md).

Fix location: BOTH repos need the fix.

• Main repo: flatpak/io.github.fjrevoredo.mini-diarium.yml — change to fonts/*.ttf (this fixes future releases via the publish workflow)
• Flathub repo: io.github.fjrevoredo.mini-diarium.yml — same change (this fixes the current PR so it can pass vorarbeiter)

Push to Flathub repo:

cd <flathub-repo>
git checkout update-<x.y.z>    # the PR branch
# edit io.github.fjrevoredo.mini-diarium.yml
git add io.github.fjrevoredo.mini-diarium.yml
git commit -m "fix: correct font install path"
git push origin update-<x.y.z>

Then comment bot, build on the Flathub PR to trigger a new vorarbeiter build.

2. npm ENOTCACHED — vendored node sources incomplete

Symptom: npm ERR! ENOTCACHED during npm ci --offline, e.g. request to https://registry.npmjs.org/<pkg> failed: cache mode is 'only-if-cached' but no cached response is available.

Diagnosis: node-sources.json is missing one or more packages declared in package-lock.json. The vendored sources are generated from the lockfile — if the lockfile is stale or the generation was incomplete, npm ci --offline fails because it cannot reach the network.

Root cause chain: package-lock.json → node-sources.json (generated by the publish workflow) → vorarbeiter npm ci --offline. A break at any link causes ENOTCACHED.

Hidden root cause — --package-lock-only with --legacy-peer-deps: The canonical npm command from CLAUDE.md (npm install --package-lock-only --legacy-peer-deps) can produce lockfile entries without resolved and integrity fields for some packages (e.g. peer dep aggregators like @tiptap/extensions). Since generate-node-sources.mjs skips entries without these fields (line 152), the vendored sources are silently incomplete. Running a full npm install --legacy-peer-deps (without --package-lock-only) forces npm to download and resolve all packages, producing complete entries.

First diagnostic step: Run node flatpak/check-node-sources.mjs <package-lock.json> <node-sources.json> to discover ALL missing packages at once. The npm ci error only reports the first failure — there may be more.

Second diagnostic step: If check-node-sources.mjs reports missing packages, check whether package-lock.json itself is the source of the gap — search for the missing package in the lockfile and verify its entry has both resolved and integrity fields.

Fix — two repos, two actions:

1. Main repo (prevent recurrence): Regenerate the lockfile with real npm so future releases ship a healthy one:

   npm install --package-lock-only --ignore-scripts --legacy-peer-deps

   Verify with check-node-sources.mjs afterward. Commit and push.

2. Flathub repo (fix current PR): Either re-run the publish workflow (if the lockfile fix is committed and the workflow can regenerate from it), or manually patch node-sources.json with the missing entries and force-push to the PR branch:

   cd <flathub-repo>
   git checkout update-<x.y.z>
   node flatpak/check-node-sources.mjs ../mini-diarium/package-lock.json node-sources.json
   # Add missing entries (see generate-node-sources.mjs docs for format)
   git add node-sources.json
   git commit -m "fix: add missing npm packages to node-sources.json"
   git push --force-with-lease origin update-<x.y.z>

   Then comment bot, build on the Flathub PR to trigger a new vorarbeiter build.

2a. Stale or incomplete package-lock.json — lockfile integrity gap

Symptom: The app builds and works locally (bun resolves everything from bun.lock), but vorarbeiter fails with ENOTCACHED because the publish workflow only reads package-lock.json.

Diagnosis: Two possible causes:

• Divergence: bun.lock is current but package-lock.json was never regenerated with real npm after a package.json change. Run node flatpak/check-node-sources.mjs and compare.
• Incomplete entries: package-lock.json was regenerated with npm install --package-lock-only --legacy-peer-deps, but some entries lack resolved/integrity (see Failure 2 "Hidden root cause" above). Search: Select-String -Path package-lock.json -Pattern '"node_modules/zip-stream"' -Context 0,5 and check for resolved field.

Fix — when regenerating the lockfile:

npm install --package-lock-only --ignore-scripts --legacy-peer-deps

npm may say "up to date" but still modify the file if packages were added since the last generation.

Fix — when lockfile entries are missing resolved/integrity: Delete node_modules/ and run a full install:

npm install --legacy-peer-deps

Then run bun install to sync bun.lock. Verify with check-node-sources.mjs.

3. cargo-sources.json stale

Symptom: perhaps a crate was updated and forgotten to be re-vendored?

Diagnosis: Cargo.lock changed but cargo-sources.json wasn't regenerated.

Fix location: The publish workflow regenerates it automatically from the tagged tree. If the workflow failed before generation, re-running it should work. If it was generated but wrong, check that the tagged commit has the correct Cargo.lock.

4. Missing arch-specific npm packages

Symptom: Cannot find module '@rolldown/binding-linux-arm64-gnu' or similar

Diagnosis: node-sources.json is missing arch-specific optional native packages (@esbuild/linux-*, @rolldown/binding-linux-*, lightningcss-linux-*, etc.).

Fix: The generate-node-sources.mjs script must be run with the correct .npm cache. Check that the workflow's "Generate node-sources.json" step is using the tagged tree's package-lock.json, not the checkout's.