Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (70 loc) · 4.27 KB

AGENTS.md

File metadata and controls

98 lines (70 loc) · 4.27 KB
Raw

Worth — agent guide

Worth is a balance tracking desktop app built with Tauri 2 (Rust) + Nuxt 4 (Vue 3, TypeScript).

App scope

  • Designed to track a daily balance for each account, entered manually by the user
  • A missing day means the balance is unchanged since the previous stored value
  • All data is stored locally only (not saved in the cloud)

Tech stack

  • Frontend: Nuxt 4, Nuxt UI 4, TailwindCSS 4, TypeScript, TanStack Vue Query, ECharts
  • Desktop: Tauri 2 (@tauri-apps/api, @tauri-apps/cli)
  • Backend: Rust 2024, tokio, sqlx (SQLite)
  • Type sharing:
    • specta / tauri-specta generates app/generated/bindings.ts via src-tauri/src/bin/export_bindings.rs
    • schemars / garde generates app/generated/schemas/*.schema.json via src-tauri/src/bin/export_schemas.rs
    • json-schema-to-zod generates app/generated/zod/*.ts via app/scripts/generate-zod.mjs

Repo layout (high level)

  • app/: Nuxt app (pages/components/composables/plugins)
  • nuxt.config.ts: Nuxt config (SSR off; static nuxt generate output)
  • src-tauri/: Tauri/Rust app + config
    • src-tauri/src/api/: Tauri commands + DTOs (#[tauri::command])
    • src-tauri/src/db/: Rust DB helpers/queries
    • src-tauri/db/: SQL migrations + seed scripts
    • src-tauri/src/bin/db.rs: DB dev CLI (seed/backup/restore/clear)
    • src-tauri/src/bin/export_bindings.rs: exports TS bindings

Documentation

  • Start with docs/README.md and read the relevant document before changing a documented subsystem.

Common commands

# install dependencies (repo enforces bun)
bun install

# desktop dev (Nuxt dev server + Tauri)
bun run tauri:dev

# build desktop bundle
bun run tauri:build

# typecheck
bun run check:<ts|rust|all>

# lint and format
bun run lint:<ts|rust|all>[:fix]

# database operations
bun run db <backup|restore|seed|clear|clean|help>

# export Rust contract types to app/generated/*.ts
bun run contracts:gen
  • Prereqs: install the OS toolchain per Tauri prerequisites.
  • Node version: .nvmrc (currently 24); Bun is the supported package manager (package.json preinstall guard).

Problems running cargo commands ("rustup could not choose a version of cargo to run, because one wasn't specified explicitly, and no default is configured")? Try this:

  • Set CARGO_HOME = %USERPROFILE%\.cargo
  • Set RUSTUP_HOME = %USERPROFILE%\.rustup
  • Add %USERPROFILE%\.cargo\bin to PATH prefix

Dependency pinning

  • Default to pinning dependencies to the major version only.
  • Tauri and its frontend counterparts must be pinned to the same minor version.
  • Tauri plugins must be pinned to the same exact version across Rust and frontend packages.

Database (SQLite)

  • Engine: SQLite via sqlx.
  • DB file location (runtime): AppLocalData/db/worth.sqlite (on Windows this is under %LOCALAPPDATA%/<bundle id>/db/).
  • Migrations: src-tauri/db/migrations (run on app startup in src-tauri/src/lib.rs).
  • Seed/backup/restore CLI (operates on the same app-local DB, bun run db --help)

DB operations + models

  • Database queries: src-tauri/src/db/mod.rs

  • Models returned from queries: src-tauri/src/db/mod.rs (query/aggregate/join result structs)

  • Database table models: src-tauri/src/db/rows.rs (every table must have an up-to-date sqlx::FromRow model here)

  • API response models (DTOs): src-tauri/src/api/mod.rs (types returned over IPC; map DB models to DTOs)

  • Frontend API wrapper: app/composables/useApi.ts wraps commands from bindings.ts and automatically unwraps Result<T, ApiError> to T.

Preferences

  • Avoid writing helper functions that are only used once; prefer to inline the code (including in Vue templates, where appropriate).
  • TanStack Query must be used for all data fetching.
  • In Rust, prefer iterators over loops.
  • In Vue, prefer existing Nuxt UI components over custom elements (where possible). View the available components and a link to their docs at https://ui.nuxt.com/llms.txt.
  • This is a greenfield project, so there is no need to maintain backwards compatibility.
  • Avoid compatibility markers or schema versions for artifacts where the producer and consumer ship together.