Skip to content

Development

Local build, test and lint commands, repository layout, migrations, and the release pipeline.

Local build

The web UI is embedded into the binary at compile time, so it must be built first:

cd webui && npm ci && npm run build && cd ..
cargo build --release -p sumidoku-server

During development, cd webui && npm run dev starts the Vite dev server, proxying API calls to the server on :3000.

Tests and lint

Server (Rust):

cargo nextest run --workspace
cargo clippy --workspace --all-targets -- -D warnings

Web UI:

cd webui && npm ci && npm run check && npm run build

Repository layout

  • crates/server — axum HTTP server: REST /api/v1 and embedded web UI
  • crates/wasm — Aidoku WASM source runtime (wasmi)
  • vendor/aidoku — vendored upstream crate; it tracks upstream, do not restyle or “fix” it locally
  • webui — Vite + React SPA, built to webui/build
  • data/ — local dev database, cover cache and sources; untracked, never commit it

Database migrations

  • Schema changes are new numbered files only; do not edit an applied migration.
  • No SQL triggers or views without a special case: what a write must also do belongs in the store that makes the write, and sync payloads belong in sync/journal.rs. db.rs:migrated_schema_has_no_triggers_or_views enforces it.
  • Keep migration comments in English and files in LF. .gitattributes and db.rs:shipped_migrations_use_ascii_comments_and_lf enforce the encoding.
  • db.rs:shipped_migrations_are_immutable pins canonical checksums. The explicitly listed historical Chinese/English LF/CRLF checksums are a closed compatibility set, not permission for further edits or derived aliases.

Release pipeline

  • The version lives in the workspace Cargo.toml. A push to main that touches it runs the release pipeline: five platform archives, Docker Hub (sumidoku/sumidoku) and ghcr.io (ghcr.io/sumidoku/sumidoku) tags latest/X.Y.Z/<major>.x (e.g. 0.x), and the GitHub release.
  • Never push a tag or create a release by hand; CI does both.
  • A release counts only when the run is green, the release shows its 5 assets, and the 3 tags moved on both registries. Verify before announcing; the checklist is in docs/code-standards.md.

Further reading

The binding development rules — tests, commits and merges, PR review — are in docs/code-standards.md, and AGENTS.md is the entry point for how the project’s agent sessions work. See Contributing for how community PRs are handled.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close