From fd0c102d88aa87f59090e2445b0f65a29a121775 Mon Sep 17 00:00:00 2001 From: Claas Date: Thu, 6 Aug 2026 00:57:33 +0200 Subject: [PATCH] Document project conventions in CLAUDE.md Captures the decisions made while planning: Rust-first logic, tokio actors instead of mutexes, pull-based streaming over IPC, rule of least power on the frontend, accessibility as a requirement, the Tauri-webview browser support policy, the dependency approval rule, and the MIT licence constraint that keeps GPL-3.0 gitamine source off limits. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5be4657 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ +# gigit + +A desktop git GUI client. Tauri 2 + Solid, with a colourful commit graph whose layout is +computed in Rust and streamed to the frontend. + +## Stack + +| Layer | Choice | +|---|---| +| Shell | Tauri 2 | +| Frontend | Solid 2 (beta), TypeScript 7, Vite | +| Styling | Tailwind CSS v4 (CSS-first config) + `@claas.dev/material-tailwind` | +| Lint / format | Oxc — `oxlint` and `oxfmt`. **Not** ESLint or Prettier. | +| Git access | `gix` (gitoxide), reads only for now | +| Async | tokio | + +`crates/gigit-git` holds git access and the graph layout engine and knows nothing about +Tauri, so it can be tested and benchmarked with plain `cargo test`. `src-tauri` holds the +actors, commands and channels. + +## Architecture rules + +- **Logic goes in Rust.** The frontend renders and handles input; it does not compute. +- **Actors, not mutexes.** Shared state gets an owning actor (handle + `tokio::sync::mpsc` + + `oneshot`, per ). No `Mutex`/`RwLock` without a + stated reason the actor pattern doesn't fit. A `gix::Repository` is blocking and + thread-affine, so its actor runs on a dedicated `std::thread` draining its receiver with + `blocking_recv()`. +- **Stream anything large.** List-shaped data crosses IPC as pull-based chunks over + `tauri::ipc::Channel`, driven by the frontend asking for more — never one big response. +- **Rule of least power** (): semantic HTML + first, then CSS, then JavaScript. A CSS solution beats a JS one. +- **Accessibility is a requirement.** Keyboard operability and correct AT semantics are part + of the work, not a follow-up. Decorative graphics are `aria-hidden` over content that + already reads correctly without them. + +## Browser support policy + +The only targets are Tauri's webviews: WKWebView (Safari) on macOS, WebView2 (Chromium) on +Windows, WebKitGTK on Linux. Baseline Newly available features are fine where they degrade +gracefully. No polyfills. Hand-written fallbacks only when under ~20 lines and dependency-free. + +Use the `modern-web-guidance` skill before starting frontend work. + +## Dependencies + +**Ask before adding any npm or cargo dependency**, and list notable transitive ones. Prefer a +platform feature over a library. + +## Licence and attribution + +gigit is MIT. Adapted or copied code must carry attribution including its licence, in +`NOTICE.md`. + +Specifically: the commit graph is implemented from the algorithm *described* in +. Its reference +implementation, [gitamine](https://github.com/pvigier/gitamine), is **GPL-3.0** — do not read +or port its source. + +## Commands + +``` +pnpm tauri dev # run the app +pnpm typecheck # tsc --noEmit +pnpm lint # oxlint +pnpm format # oxfmt . +pnpm format:check # oxfmt --check . +cargo test --workspace +cargo clippy --workspace +``` + +## Workflow + +Work ships as stacked PRs using the `gh-stack` skill — small, reviewable layers where +foundational changes sit below dependent ones. -- 2.51.2