Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
build(flatpak): build and run the Flathub recipe locally
Elian Doran19e9ed49d33b
diff --git a/.claude/skills/packaging-for-flathub/SKILL.md b/.claude/skills/packaging-for-flathub/SKILL.mdindex 28d98821ff..9b15535825 100644--- a/.claude/skills/packaging-for-flathub/SKILL.md+++ b/.claude/skills/packaging-for-flathub/SKILL.md@@ -55,6 +55,31 @@ pnpm exec tsx scripts/flatpak/generate-sources.mts ../org.triliumnotes.Triliumcommit. The pinned commit must be **pushed** — Flathub clones `TriliumNext/Trilium` atthat SHA.+To build and run the Flathub recipe locally, without touching the packaging repo:++```sh+pnpm desktop:flathub-build # scripts/flatpak/build-local.mts+pnpm desktop:flathub-start+```++`build-local.mts` renders the same manifest into `apps/desktop/out/flathub/` with the git+source swapped for a `type: dir` source over the working tree, so uncommitted changes are+built and nothing needs committing or pushing. `skip` matches exact relative paths, not+patterns, so the script lists every path `git ls-files --others --ignored --directory`+reports (~200: each `node_modules`, `dist`, …). `.git` stays in: the manifest's+`chore:update-build-info --from-commit` reads `git log`, and the local build keeps+Flathub's build commands unchanged. It regenerates `generated-sources.json` only when the+working tree's lockfile changes, and installs through `org.flatpak.Builder` as branch `local`, beside the Flathub install. An+install becomes flatpak's `current` branch, which the desktop launcher runs, so the script+puts the previous one back (`flatpak info` cannot report it once several are installed;+the script reads the `app/<id>/current` link).+`flathub:start` runs that branch on its own `trilium-data-local` and Electron data dirs+under `~/.var/app/org.triliumnotes.Trilium`, so a dev build never migrates the real+sandboxed database. Without `flatpak-node-generator` on PATH it runs the generator on the+Builder's Python from `~/.cache/flatpak-builder-tools` (cloned at the CI pin), raising+aiohttp 3.10's 8190-byte header limit, which GitHub's release responses exceed. A full+build takes about ten minutes.+## Settled decisions and why (do not relitigate without new facts)- **From source, not repackaged.** The AppImage-extract fallback (Zettlr-style) existsdiff --git a/apps/desktop/package.json b/apps/desktop/package.jsonindex 4cd6dc2b7d..2da0b2514b 100644--- a/apps/desktop/package.json+++ b/apps/desktop/package.json@@ -21,6 +21,8 @@"electron-forge:package": "pnpm build && electron-forge package dist","electron-forge:test-packaged": "pnpm electron-forge:package && tsx scripts/test-packaged.ts","electron-forge:start":"pnpm build && electron-forge start dist",+ "flathub:build": "tsx ../../scripts/flatpak/build-local.mts",+ "flathub:start": "flatpak run --branch=local --env=TRILIUM_DATA_DIR=$HOME/.var/app/org.triliumnotes.Trilium/data/trilium-data-local --env=TRILIUM_ELECTRON_DATA_DIR=$HOME/.var/app/org.triliumnotes.Trilium/config/trilium-electron-local org.triliumnotes.Trilium","e2e": "pnpm build && cross-env TRILIUM_INTEGRATION_TEST=memory-no-store TRILIUM_PORT=8082 TRILIUM_DATA_DIR=data-e2e TRILIUM_ELECTRON_DATA_DIR=data-e2e-electron-8082 ELECTRON_IS_DEV=0 playwright test","generate-setup-banners": "tsx electron-forge/setup-icon/generate/generate.mts","generate-dmg-background": "tsx electron-forge/dmg-background/generate.mts",diff --git a/package.json b/package.jsonindex 0c77f61af0..574d692eac 100644--- a/package.json+++ b/package.json@@ -19,6 +19,8 @@"desktop:start": "pnpm run --filter desktop dev","desktop:build": "pnpm run --filter desktop build","desktop:start-prod": "pnpm run --filter desktop start-prod",+ "desktop:flathub-build": "pnpm run --filter desktop flathub:build",+ "desktop:flathub-start": "pnpm run --filter desktop flathub:start","standalone:start": "pnpm run --filter standalone dev","standalone:build": "pnpm run --filter standalone build","standalone:test": "pnpm run --filter standalone test",diff --git a/scripts/flatpak/build-local.mts b/scripts/flatpak/build-local.mtsnew file mode 100644index 0000000000..23b9a8aed3--- /dev/null+++ b/scripts/flatpak/build-local.mts@@ -0,0 +1,182 @@+/**+ * Builds the Flathub flatpak from this checkout's working tree and installs it for the+ * current user as the `local` branch of org.triliumnotes.Trilium, next to any install+ * from Flathub.+ *+ * The manifest is the one ./scripts/flatpak/update-repo.mts writes for Flathub, except+ * that its git source becomes a `dir` source over this checkout: the build sees the files+ * on disk, uncommitted changes included, minus everything git ignores. `.git` stays in,+ * because the manifest stamps the build info from `git log`.+ * `generated-sources.json` is regenerated only when the lockfile changes.+ *+ * Usage:+ *+ * pnpm exec tsx ./scripts/flatpak/build-local.mts+ *+ * Then run it with `flatpak run --branch=local org.triliumnotes.Trilium`.+ *+ * Builds through the org.flatpak.Builder flatpak. Without `flatpak-node-generator` on+ * PATH, the generator runs on that flatpak's Python from a flatpak-builder-tools+ * checkout under ~/.cache, cloned on first use.+ */++import { execFileSync } from "node:child_process";+import { createHash } from "node:crypto";+import { existsSync, mkdirSync, readFileSync, readlinkSync, writeFileSync } from "node:fs";+import { homedir } from "node:os";+import { basename, join, resolve } from "node:path";++import { main as generateSources } from "./generate-sources.mjs";+import { MANIFEST_NAME, renderManifest, writePackagingFiles } from "./update-repo.mjs";++const REPO_ROOT = resolve(import.meta.dirname, "../..");+const OUT_DIR = join(REPO_ROOT, "apps/desktop/out/flathub");+const SOURCES_LOCKFILE_STAMP = join(OUT_DIR, "generated-sources.lockfile");+const APP_ID = "org.triliumnotes.Trilium";+const LOCAL_BRANCH = "local";+// Must match the commit .github/workflows/release-flathub.yml installs.+const GENERATOR_COMMIT = "41c20aa10819cdb2a4f3ca171758a96d1955c018";+const GENERATOR_REPO = "https://github.com/flatpak/flatpak-builder-tools.git";++export async function main() {+ mkdirSync(OUT_DIR, { recursive: true });++ const { manifest } = await renderManifest("HEAD");+ const ignored = parseIgnoredPaths(+ git("ls-files", "--others", "--ignored", "--exclude-standard", "--directory")+ );+ writePackagingFiles(OUT_DIR, useLocalDirSource(manifest, REPO_ROOT, ignored));+ updateSources();++ const currentBranch = getCurrentBranch();+ // A Nix shell sets SOURCE_DATE_EPOCH to 1980, which would date the export, and flatpak+ // refuses to install a commit older than the installed one.+ const { SOURCE_DATE_EPOCH: _, ...env } = process.env;+ execFileSync("flatpak", [+ "run", "org.flatpak.Builder",+ "--user", "--install", "--force-clean",+ "--install-deps-from=flathub",+ `--default-branch=${LOCAL_BRANCH}`,+ "builddir", MANIFEST_NAME+ ], { cwd: OUT_DIR, env, stdio: "inherit" });+ // An install becomes the default branch, which the desktop launcher runs on the real data.+ if (currentBranch && currentBranch !== LOCAL_BRANCH) {+ execFileSync("flatpak", [ "make-current", "--user", APP_ID, currentBranch ], {+ stdio: "inherit"+ });+ }+ console.log(`Installed the working tree as the "${LOCAL_BRANCH}" branch.`);+}++/**+ * The branch `flatpak run` picks without `--branch`, if the app is installed. `flatpak info`+ * cannot tell: it refuses to pick one once several branches are installed.+ */+function getCurrentBranch(): string | undefined {+ const userDir = process.env.FLATPAK_USER_DIR ?? join(dataDir(), "flatpak");+ try {+ return basename(readlinkSync(join(userDir, "app", APP_ID, "current")));+ } catch {+ return undefined;+ }+}++/**+ * Replaces the manifest's Trilium git source with a `dir` source over a local checkout.+ * flatpak-builder matches `skip` entries as exact relative paths, not patterns, so each+ * ignored path is listed on its own.+ */+export function useLocalDirSource(manifest: string, repoDir: string, skip: string[]): string {+ const gitSource = new RegExp("^([ \\t]*)- type: git\\n"+ + "[ \\t]*url: https://github\\.com/TriliumNext/Trilium\\.git\\n"+ + "(?:[ \\t]*tag: .*\\n)?"+ + "[ \\t]*commit: .*\\n", "m");+ if (!gitSource.test(manifest)) {+ throw new Error("Found no Trilium git source to replace with the local checkout.");+ }+ return manifest.replace(gitSource, (_, indent: string) => [+ `${indent}- type: dir`,+ `${indent} path: ${JSON.stringify(repoDir)}`,+ `${indent} skip:`,+ ...skip.map((path) => `${indent} - ${JSON.stringify(path)}`),+ ""+ ].join("\n"));+}++/** The `git ls-files --ignored --directory` output as paths, without those inside another. */+export function parseIgnoredPaths(lsFilesOutput: string): string[] {+ const paths = lsFilesOutput.split("\n")+ .map((line) => line.trim().replace(/\/$/, ""))+ .filter(Boolean);+ return paths.filter((path) => !paths.some((other) => path.startsWith(`${other}/`)));+}++/** Regenerates the sources from the working tree's lockfile, unless it is unchanged. */+function updateSources() {+ const lockfileHash = createHash("sha256")+ .update(readFileSync(join(REPO_ROOT, "pnpm-lock.yaml")))+ .digest("hex");+ const sourcesPath = join(OUT_DIR, "generated-sources.json");+ if (existsSync(sourcesPath) && readStamp() === lockfileHash) {+ console.log("The lockfile is unchanged; reusing generated-sources.json.");+ return;+ }+ generateSources([ OUT_DIR ], generatorCommand());+ writeFileSync(SOURCES_LOCKFILE_STAMP, lockfileHash);+}++function readStamp() {+ return existsSync(SOURCES_LOCKFILE_STAMP)+ ? readFileSync(SOURCES_LOCKFILE_STAMP, "utf-8")+ : undefined;+}++function generatorCommand(): string[] {+ try {+ execFileSync("flatpak-node-generator", [ "--help" ], { stdio: "ignore" });+ return [ "flatpak-node-generator" ];+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") {+ throw err;+ }+ }++ // org.flatpak.Builder sees the host's home directory but not its /tmp.+ const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");+ const checkout = join(cacheDir, "flatpak-builder-tools");+ if (!existsSync(checkout)) {+ execFileSync("git", [ "clone", "--quiet", GENERATOR_REPO, checkout ], { stdio: "inherit" });+ execFileSync("git", [ "-C", checkout, "checkout", "--quiet", GENERATOR_COMMIT ], {+ stdio: "inherit"+ });+ }+ return [+ "flatpak", "run", "--command=python3", `--env=PYTHONPATH=${join(checkout, "node")}`,+ "org.flatpak.Builder", "-c", GENERATOR_BOOTSTRAP+ ];+}++// The aiohttp in org.flatpak.Builder (3.10) rejects GitHub's release responses, whose+// headers exceed its 8190-byte default, so the generator's sessions get larger limits.+const GENERATOR_BOOTSTRAP = `\+import functools, runpy, aiohttp+aiohttp.ClientSession.__init__ = functools.partialmethod(+ aiohttp.ClientSession.__init__, max_line_size=65536, max_field_size=65536)+runpy.run_module("flatpak_node_generator", run_name="__main__", alter_sys=True)+`;++function dataDir() {+ return process.env.XDG_DATA_HOME || join(homedir(), ".local/share");+}++function git(...args: string[]): string {+ return execFileSync("git", args, { cwd: REPO_ROOT }).toString().trim();+}++// Only when run as a script — the pure helpers above are imported by the spec.+if (process.argv[1] === import.meta.filename) {+ main().catch((err) => {+ console.error(err instanceof Error ? err.message : err);+ process.exit(1);+ });+}diff --git a/scripts/flatpak/build-local.spec.ts b/scripts/flatpak/build-local.spec.tsnew file mode 100644index 0000000000..a769735b4f--- /dev/null+++ b/scripts/flatpak/build-local.spec.ts@@ -0,0 +1,50 @@+import { describe, expect, it } from "vitest";++import { parseIgnoredPaths, useLocalDirSource } from "./build-local.mjs";++const SOURCES = (pin: string) => `\+ sources:+ - type: git+ url: https://github.com/TriliumNext/Trilium.git+${pin} - generated-sources.json+ - type: archive+ url: https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.0.0.tgz+`;++describe("useLocalDirSource", () => {+ it("swaps a pinned git source for a dir source and keeps the others", () => {+ const expected = `\+ sources:+ - type: dir+ path: "/home/user/Trilium"+ skip:+ - "node_modules"+ - "apps/client/dist"+ - generated-sources.json+ - type: archive+ url: https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.0.0.tgz+`;+ const skip = [ "node_modules", "apps/client/dist" ];+ const commit = " commit: 1234567890abcdef1234567890abcdef12345678\n";+ const tagged = ` tag: v0.106.0\n${commit}`;+ for (const pin of [ commit, tagged ]) {+ expect(useLocalDirSource(SOURCES(pin), "/home/user/Trilium", skip)).toBe(expected);+ }+ });++ it("fails on a manifest without the Trilium git source", () => {+ expect(() => useLocalDirSource("sources: []\n", "/repo", []))+ .toThrow(/no Trilium git source/);+ });+});++describe("parseIgnoredPaths", () => {+ it("strips directory slashes and drops paths inside another ignored one", () => {+ const output = ".flatpak-builder/\n.flatpak-builder/ccache/\napps/client/dist/\n"+ + "apps/client/tsconfig.tsbuildinfo\nnode_modules/\nnode_modules_backup/\n";+ expect(parseIgnoredPaths(output)).toEqual([+ ".flatpak-builder", "apps/client/dist", "apps/client/tsconfig.tsbuildinfo",+ "node_modules", "node_modules_backup"+ ]);+ });+});