Version the sync WIRE PROTOCOL separately from either program's release
version, so a self-hosted server and the desktop app can sit on different
releases and still work out whether they can talk.
Each side declares two numbers — what it speaks, and the oldest counterpart
it accepts. Either side can therefore mark a change breaking without the
other shipping in step, which is the whole point: no app↔server lockstep.
Server advertises on the existing public /api/config (a client must be able
to ask "can I talk to you?" before it holds a device token, or even has an
account): sync_protocol_version, min_client_protocol_version, sync_features.
sync_features exists because a version number can only say newer/older. An
ADDITIVE change earns a capability name instead of a minimum bump, so a
newer client meeting an older server drops that one feature and syncs the
rest, rather than refusing. Raising a minimum is reserved for genuinely
breaking changes — it's the switch that hard-blocks the other side.
Client half is pure decision logic (sync/compat.rs), no I/O, so every branch
is unit-testable — there's no live-server lane in CI. Three outcomes: ok /
degraded{unavailable} / incompatible{reason, client_must_update}. The last
names which side can fix it, so the message is actionable. A server that
predates the handshake sends no protocol fields at all; that reads as
"update the server", deliberately not as a parse error, which would look to
the user like they mistyped the URL.
normalize_base_url defaults a bare host to https://, never http:// —
silently downgrading would put a long-lived device token on the wire in
cleartext because someone omitted five characters. Plain HTTP on a trusted
LAN stays supported; the user types http:// and thereby chooses it.
Transport (the actual fetch) lands next, separately: it needs an HTTP/TLS
stack, and that's a real risk to the Windows cross-compile lane, so it gets
its own CI run to bisect against rather than riding along with this.
No UI here by design — the link/settings surface it feeds is M10.7's, per
this task's own sequencing.
Policy documented in docs/sync.md.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SreJkbxB4gx8pPsu8QbLPi
Adds a `windows` job to desktop.yml on the new ci-tauri-win image, producing a
Windows -setup.exe without any Windows hardware. A Windows container can't run
on a Linux host, so cross-compilation is the only route: --runner cargo-xwin
supplies the MSVC CRT/SDK (pre-warmed into the image) and links with lld-link,
and makensis builds the installer.
NSIS only. .msi needs WiX v3, a Windows program — per Tauri, ".msi installers
can only be created on Windows". It comes back if a Windows node ever exists.
Kept as a separate job so a Windows-side failure can never block the Linux
artifacts, which are the primary product today. publish-release.sh now globs
the windows target root too; nullglob means each job uploads only what its own
workspace contains, and the release is created once and reused via the 409
path, so both jobs can publish to the same release safely.
No app code changes were needed. The AppImage self-integration UI already
gates on is_appimage (AccountView.vue:131, DesktopIntegrationPrompt.vue:22),
and $APPIMAGE is never set on Windows, so the OOBE prompt and Settings toggle
hide themselves.
Recorded plainly in ci-requirements.md that this is the weakest-verified lane
we have: Tauri calls Linux->Windows cross-compilation "not tested as much" and
a last resort, and a Linux runner cannot execute a Windows binary. Green means
it built. A real Windows machine check is mandatory before trusting a release,
and installers are unsigned until a certificate exists.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SreJkbxB4gx8pPsu8QbLPi
The advertised curl URL referenced raw/branch/main, but main has never been
created (creating it is rejected by a branch-protection rule that matches the
name even with no branch behind it), so the one-command install 404'd. dev is
currently the repo's only branch and serves the script fine now that the repo
is public — verified 200, with all three v0.1.0 release assets resolving and
the AppImage downloading in full.
Flagged in the header to move back to main once that branch exists, so the
public install command stops tracking day-to-day work.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SreJkbxB4gx8pPsu8QbLPi
Follow-up to 8a8b2b1, driven by what run 2872's new checks actually printed.
The .deb verification did its job on its first run: tauri already infers
exactly libwebkit2gtk-4.1-0 + libgtk-3-0, so declaring the same two in
tauri.conf.json produced a control file listing each of them twice. Removed
the declaration — verify.sh is the real guard, and it fails the build if
inference ever stops covering what the binary links.
The pacman step revealed ci-tauri carries neither zstd nor bsdtar, so packages
currently ship as .pkg.tar.xz with no .MTREE. Both are working outcomes
(pacman reads xz; only `pacman -Qkk` needs .MTREE), but the docs promised
.zst, so the README, the release notes and ci-requirements.md now describe
what the build actually produces.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SreJkbxB4gx8pPsu8QbLPi
Native packages the installer can actually fetch, before task 2014 wires up
the fetching.
Arch (task 2022, re-scoped): the source PKGBUILD is gone — asking every user
to install rust+node and compile for minutes isn't distribution. Replaced by
desktop/packaging/arch/package-prebuilt.sh, which wraps the binary the Linux
job already built into a .pkg.tar.zst. No second Rust build, no Arch CI image:
the binary bundles nothing and resolves webkit/gtk/soup by soname, identical
on both distros, with SQLite compiled in and glibc used in the safe
built-old/run-new direction. CI is Debian and has no pacman, so the step logs
.PKGINFO plus the full file listing for audit instead of pretending to verify.
Debian (task 2074): install.sh hands the .deb to every Debian/Ubuntu user and
nothing had ever inspected it. tauri.conf.json now declares
libwebkit2gtk-4.1-0 + libgtk-3-0 explicitly rather than trusting inference —
and deliberately declares no appindicator or sqlite dep, since tauri is built
with features=[] and rusqlite is "bundled". desktop/packaging/deb/verify.sh
prints the generated control file, cross-checks it against what the ELF
actually needs via dpkg-shlibdeps, confirms every declared dep exists in apt,
and clean-container installs when a docker CLI is available.
Both artifacts join the run artifact and the tagged release; install.sh grows
a pacman branch so Arch/CachyOS gets a native install instead of the AppImage
fallback. Still no release cut (rule 2).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SreJkbxB4gx8pPsu8QbLPi
Phase A of the desktop Release + install path (M10 / tasks 2014, 1998):
- .forgejo/workflows/desktop.yml: tag-gated "Publish release" step +
contents:write. On a v* tag the build now publishes a Fabled-Git Release
with the de-bundled AppImage + .deb attached — a stable, versioned fetch
target (Actions artifacts are ephemeral/test-only). Dormant on dev/main.
- desktop/packaging/publish-release.sh: creates/reuses the Release via the
Forgejo API using the runner-injected token; idempotent asset replace.
- desktop/packaging/install.sh: curl|sh one-command installer — native .deb
on Debian/Ubuntu, de-bundled AppImage everywhere else (installed to
~/Applications/ThoughtSync.AppImage, matching src/integration.rs so the app
sees itself integrated). AppImage path needs no sudo.
Plumbing only — no release cut (rule 2); activates on the operator's first
v* tag. In-app self-update (tauri-plugin-updater + signed latest.json) is
Phase B, gated on the operator's signing key.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
There was essentially no logging — useless for proving the app renders across
different environments. Add real observability:
- tauri-plugin-log -> stdout (so `2>&1 | tee` captures a run) AND a persistent
file in the app log dir (grabbable after the fact on any machine). Level Info.
- Startup diagnostics: app version, OS/arch, the Linux display/session stack
(XDG_SESSION_TYPE, desktop, Wayland/X11, GDK_BACKEND), the WebKit render-
hardening vars actually in effect, resolved log + data dirs, DB open/migrate
result, and note/label counts.
- log_event command + a frontend logEvent() helper: boot line (data source +
WebKit user-agent) from main.ts, first-route config/session/destination from
the router guard, and — via the bridge invoke() wrapper — every failed Tauri
command named with its error, so a broken basic function is self-identifying.
Task 2040.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
Both chained `stmt.query_map(...)?.collect()?` as the block's tail expression,
so the prepared statement (a block local) was dropped before the borrow held by
the mapped rows ended (E0597). Bind `let rows` first, matching every other query
in the file. rustc error, so this also unblocks test + the release build.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
The on-device core that makes the desktop app work with no server and no login.
- rusqlite (bundled SQLite, so no system libsqlite dependency to vary across
builds); uuid v4 ids; RFC3339/Date.toISOString-compatible timestamps.
- Schema mirroring the note model: notes, labels, note_labels (with via_tag),
checklist_items, attachments, link_previews, note_revisions, saved_filters,
plus per-row sync_revision/dirty + a sync_state row for the M10.7 engine.
user_version-gated migrations.
- derive.rs: pure [[wiki-link]] + #tag scanners (mirror the frontend inline
rules, no regex dep) with unit tests; #tags re-sync via_tag labels on save,
[[links]] drive backlinks at query time (derived, never stored).
- store.rs: the full repository surface (facet/label/date/text list, create,
PATCH-semantics update, pin/archive/color/kind, checklist items, labels CRUD
+ merge, reminders complete/snooze, reorder, trash/restore/delete, revisions
+ restore, titles/search/backlinks/link-search, saved filters).
- commands.rs: ~38 #[tauri::command]s over a Mutex<Connection> in managed state.
- lib.rs: opens the DB in the platform app-data dir on setup; synthetic offline
config/user so the auth-gated router resolves with no login.
Attachment upload / URL unfurl / import are intentionally deferred (network/file
concerns); adapters/local.ts (M10.5) wires all of the above via invoke.
Task 1993.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
Tauri's AppImage bundles the build host's graphics/display stack
(libEGL/libGL/libdrm/libgbm/libwayland-* + Mesa dri drivers) into usr/lib.
On many end-user systems (Arch/CachyOS, NVIDIA, Wayland) those clash with
the running kernel driver + Mesa and abort with EGL_BAD_PARAMETER -> a black
window (issue 2021). They load before any renderer choice, so the runtime
env fallbacks can't rescue it; per the AppImage excludelist they must come
from the host.
Add a CI-only post-build step (desktop/packaging/appimage/debundle-graphics.sh)
that extracts the built AppImage, strips exactly that graphics/display subset
(keeping webkit/gtk bundled for portability), and repackages in place so the
app falls through to the system's graphics libs. Wired into desktop.yml
between the Tauri build and the artifact upload.
Task 2023. Makes the AppImage the zero-install taste-test vehicle.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
Native-first fix for the AppImage black window: a PKGBUILD that builds from source,
linked against SYSTEM graphics libs, so it renders on the host driver.
- desktop/packaging/arch/{PKGBUILD,thoughtsync.desktop,README.md}: `makepkg -si`
installs /usr/bin/thoughtsync + .desktop + icon; deps webkit2gtk-4.1/gtk3/...;
builds the frontend + `cargo build --release` (no tauri-cli). Uses the host
graphics stack -> avoids EGL_BAD_PARAMETER.
- Commit the icon set (desktop/src-tauri/icons/*.png, un-gitignored) so BOTH
`cargo build` (pacman) and `cargo tauri build` (deb/appimage) work without a
generate step; bundle.icon -> the 4 committed PNGs; drop the `cargo tauri icon`
step from desktop.yml.
- Broaden the WebKit software-render hardening (lib.rs) to ALL Linux (was
AppImage-scoped) so the native build also renders if system WebKit is finicky.
Can't CI-test the PKGBUILD (Arch-only; CI is Debian) -- operator builds locally.
desktop.yml re-verifies the deb+AppImage build with the committed icons.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
WebKitGTK's DMA-BUF/EGL renderer fails to init on many Linux GPU/driver/Wayland
setups -> 'EGL_BAD_PARAMETER' -> black window (known WebKitGTK issue, not app code).
Per Tauri's Linux-graphics guidance, set the software-fallback env vars at startup
before the webview is created, scoped to AppImage launches (native installs keep GPU
accel): __NV_DISABLE_EXPLICIT_SYNC / WEBKIT_DISABLE_DMABUF_RENDERER /
WEBKIT_DISABLE_COMPOSITING_MODE, each only if the user already set it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
The Linux AppImage can now install itself into the applications menu, so it behaves
like an installed app instead of a loose file.
- Rust (desktop/src-tauri/src/integration.rs): integration_status / integrate_desktop
/ unintegrate_desktop commands — detect $APPIMAGE, copy the AppImage to
~/Applications, write ~/.local/share/applications/thoughtsync.desktop + embedded
icon, update-desktop-database. Registered in lib.rs.
- Frontend: withGlobalTauri exposes window.__TAURI__.core.invoke; desktop/bridge.ts
(isDesktop + typed invoke, NO @tauri-apps/api dep -> web bundle unaffected);
DesktopIntegrationPrompt (first-run OOBE, remembered) mounted in App.vue;
AccountView "Desktop app" add/remove control. All desktop-guarded -> no-ops on web.
- desktop.yml: upload the .deb + .AppImage as a run artifact (continue-on-error) so
the build is downloadable for hand-testing.
Verified by CI: ci.yml (vue-tsc) for the frontend, desktop.yml (cargo + tauri build)
for the Rust + AppImage.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
Separate workflow (not ci.yml) so the ~20-40min Rust/AppImage build only runs on
desktop/** changes, not every backend/frontend push. Builds on the ci-tauri:1.97
image: frontend build -> `cargo tauri icon app-icon.png` (from a committed 1024px
source PNG, sidestepping SVG-input questions) -> cargo fmt --check -> clippy -D
warnings -> cargo test -> `cargo tauri build` (deb + AppImage).
APPIMAGE_EXTRACT_AND_RUN=1 for FUSE-less CI containers. Verifies the M10.2 scaffold
end-to-end and is the foundation for the integrated-AppImage work (task 2013).
Also updates ci-requirements.md with the desktop lane.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
New desktop/ Tauri v2 project (Linux-first, cross-platform-ready):
- src-tauri: Cargo.toml (lib + thin main.rs shim), build.rs, lib.rs (Builder
entry point), tauri.conf.json (frontendDist -> ../../frontend/dist, devUrl
:5173, deb+appimage bundles), capabilities/default.json (core:default),
.gitignore.
- The shared Vue 3 frontend is the sibling ../frontend; before-commands cd via
"$(git rev-parse --show-toplevel)/frontend" since frontend and src-tauri are
siblings, not nested.
- Icons generated from frontend/public/icon.svg via `cargo tauri icon` in CI
(M10.8), not committed.
Boots the shared UI in a native window. The local data adapter (M10.3/M10.5)
and CI build verification (M10.8) follow. desktop/** is not yet in the CI paths
filter — added with the desktop lane in M10.8.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm
