AGENTS.md · AnInsomniacy/rayburst

Sections

1. A. Project Architecture
2. B. Version Management
3. C. Adding a New Config Key
4. C′. Current configuration
5. C″. Native Database Ownership
6. D. i18n / Locale Operations
7. E. Release & Update Channels
8. F. CI/CD Structure
9. G. Code Conventions
10. H. Verification Commands
11. I. Testing Constraints
12. Brand and delivery
13. Documentation editing

First lines (shown under the repo's MIT license)

# AGENTS.md — Rayburst

> This file provides context and instructions for AI coding agents.
> For human contributors, see [README.md](README.md) and [CONTRIBUTING.md](docs/CONTRIBUTING.md).

> [!IMPORTANT]
> **All changes must meet industrial-grade quality.** Enforce DRY (extract composables/utilities over duplication), strict TypeScript (no `any`, justify every `as` cast), structured error handling, and verification proportional to the changed behavior.

---

## A. Project Architecture

| Layer               | Stack                                                              |
| ------------------- | ------------------------------------------------------------------ |
| **Frontend**        | Vue 3 Composition API + Pinia + Naive UI + TypeScript              |
| **Backend**         | Rust (Tauri 2) + aria2 sidecar                                     |
| **Build**           | Vite (frontend) + Cargo (backend)                                  |
| **Package Manager** | pnpm (version pinned via `packageManager` field in `package.json`) |
| **Testing**         | Vitest (frontend), cargo test (backend)                            |

### Key File Paths

```
src/
├── api/                        # Aria2 JSON-RPC client (frontend wrapper)
├── components/preference/      # Settings UI (Basic.vue, Advanced.vue, UpdateDialog.vue)
├── composables/                # Vue composables — business logic extracted from components
├── layouts/                    # Page-level layouts (MainLayout.vue)
├── shared/
│   ├── types.ts                # All TypeScript interfaces (AppConfig, TauriUpdate, etc.)
│   ├── constants.ts            # DEFAULT_APP_CONFIG, proxy scopes, tracker URLs, timing constants
│   ├── configKeys.ts           # needRestartKeys + re-exports of aria2Options.json lists
│   ├── aria2Options.json       # SINGLE SOURCE for engine option lists (TS + Rust both consume)
│   ├── logger.ts               # Structured logging (console + webview bridge)
│   ├── timing.ts               # Timing constants (polling intervals, debounce delays)
│   ├── guards.ts               # Type guard utilities
│   ├── locales/                # 27 locale directories (see Section D)
│   └── utils/
│       ├── configHydration.ts  # Current config defaults, nested merge, and validation
│       ├── config.ts           # Config key-value transform utilities
│       ├── tracker.ts          # BT tracker fetching with proxy support
│       ├── geoip.ts            # GeoIP peer lookup (country code → flag)
│       ├── fileCategory.ts     # Category editing and native preview requests
│       ├── format.ts           # Number/date/speed formatting (bytesToSize, localeDateTimeFormat)
│       ├── task.ts             # Task status helpers (checkTaskIsBT, getTaskName)
│       ├── peer.ts             # Peer ID parsing and client identification
│       └── proxy.ts            # Proxy policy, URL building/validation, engine option assembly
├── stores/                     # Pinia stores (app.ts, preference.ts, history.ts, task/)
├── views/                      # Page-level route views
└── main.ts                     # App entry, auto-update check

src-tauri/
├── src/
│   ├── lib.rs                  # Tauri builder, plugin registration, invoke_handler
│   ├── main.rs                 # Tauri entry point
│   ├── aria2/                  # Native Rust aria2 JSON-RPC client
│   │   ├── mod.rs              # Module re-exports
│   │   ├── rpc.rs              # HTTP JSON-RPC transport, authentication and structured errors
│   │   └── types.rs            # Aria2 response types (Aria2Task, Aria2File, Aria2BtInfo, etc.)
│   ├── commands/
│   │   ├── mod.rs              # Command module re-exports
│   │   ├── aria2.rs            # aria2 JSON-RPC forwarding (tell_active, global_stat, etc.)
│   │   ├── autostart.rs        # Start at login (quoted Run value, LaunchAgent, XDG entry)
│   │   ├── config.rs           # Config CRUD, session, factory reset commands
│   │   ├── engine.rs           # Engine start/stop/restart commands
│   │   ├── fs.rs               # File system ops, diagnostics, platform code
│   │   ├── geoip.rs            # GeoIP database loading and peer IP lookup
│   │   ├── history.rs          # History DB read/write commands
│   │   ├── http_api.rs         # Local extension HTTP API auth and status commands
│   │   ├── remote_file.rs      # Remote torrent download and metainfo inspection
│   │   ├── notification.rs     # Native notification permission and test commands
│   │   ├── power.rs            # System power action commands
│   │   ├── protocol.rs         # Default protocol handler detection and registration
│   │   ├── proxy.rs            # System proxy detection (PAC, WPAD, env)
│   │   ├── runtime_config.rs   # RuntimeConfig refresh command
│   │   ├── tracker.rs          # Tracker probing and protocol classification
│   │   ├── ui.rs               # Tray, menu, dock, progress bar commands
│   │   ├── updater.rs          # check_for_update, download_update, apply_update, cancel_update
│   │   └── upnp.rs             # UPnP port mapping commands
│   ├── engine/
│   │   ├── mod.rs              # Module re-exports
│   │   ├── lifecycle.rs        # aria2 sidecar start/stop/restart
│   │   ├── config.rs           # Managed runtime aria2.conf generation
│   │   ├── cleanup.rs          # Engine cleanup utilities
│   │   └── state.rs            # Engine state management
│   ├── services/
│   │   ├── mod.rs              # Runtime services orchestration (on_engine_ready)
│   │   ├── config.rs           # RuntimeConfig cache (refreshed per engine cycle)
│   │   ├── deep_link.rs        # Deep-link and startup URL dispatch service
│   │   ├── external_input.rs   # External extension/API input queue service
│   │   ├── frontend_action.rs  # Frontend action event bridge
│   │   ├── http_api.rs         # Local HTTP API server for browser extensions
│   │   ├── monitor.rs          # Task lifecycle monitor, history DB persistence, event emission
│   │   ├── notification.rs     # Native notification dispatch service
│   │   ├── port_guard.rs       # Runtime port conflict detection and recovery
│   │   ├── power.rs            # Sleep prevention and power guard service
│   │   ├── stat.rs             # Global stat polling, Dock badge, Dock progress bar (custom NSProgressIndicator)
│   │   └── speed.rs            # Speed limit scheduler (time-of-day limits)
│   ├── gpu_guard.rs            # Explicit Linux rendering fallback and native diagnostics
│   ├── database/               # Single native SQLite owner: history, credentials, receipts
│   ├── i18n.rs                 # Native locale negotiation and rust-i18n message access
│   ├── error.rs                # AppError enum (Store, Engine, Io, NotFound, Updater, Upnp)
│   ├── menu.rs                 # Native menu builder (macOS only, cfg-gated)
│   ├── tray.rs                 # System tray setup + native event handling (lightweight mode safe)
│   └── upnp.rs                 # UPnP/IGD port mapping with renewal loop
├── locales/                    # Compile-time embedded native JSON translations
├── nsis/
│   ├── hooks.nsh              # Windows installer hooks (Native Messaging registration + icon refresh)
├── Cargo.toml                  # VERSION SOURCE OF TRUTH
└── tauri.conf.json             # Tauri config (no version field — reads from Cargo.toml)

.github/
├── ISSUE_TEMPLATE/             # Bug report (YAML form) + feature request templates
├── PULL_REQUEST_TEMPLATE.md    # PR template with TypeScript + Rust checklist
└── workflows/
    ├── ci.yml                  # Lint + type check + test (frontend & backend parallel jobs)
    └── release.yml             # Build + sign + upload for 6 platforms + updater JSON
```

---

### Libraries and Tools

Fixes and optimizations first look for a mature crate, npm package or tool (Tauri plugins, Naive UI, vitest, cargo test) before writing code. Existing hand-written code may be replaced when a library does the job better. Write it yourself only when nothing suitable exists or the integration would cost more than it saves; never adopt a tool for its own sake.

## B. Version Management

**`src-tauri/Cargo.toml` is the single source of truth.** The `version` field in `package.json` must stay in sync.

### How to Bump

Always use the provided script:

```bash
./scripts/bump-version.sh 1.4.0
```

This atomically updates both `Cargo.toml` and `package.json`.

### Why Two Files?

- `Cargo.toml` — Tauri reads this at build time; the About panel reads it via `getVersion()` at runtime.
- `package.json` — pnpm/action-setup and npm tooling reference this; CI workflows use the `packageManager` field.
- `tauri.conf.json` — intentionally omits `version` so Tauri falls back to `Cargo.toml`.

> **Never manually edit version strings.** Always use `bump-version.sh`.

---

## C. Adding a New Config Key

Follow this exact checklist:

1. **`src/shared/types.ts`** — Add the field to the `AppConfig` interface with proper typing
2. **`src/shared/aria2Options.json`** — ONLY if the key maps to an aria2 engine option: add it to `engineOptions` (and to `nonHotReloadable` if aria2 cannot change it at runtime). Both the frontend and the Rust backend read this file. App-only preference keys need no list entry — the whole config object is persisted as-is
3. **`src/shared/constants.ts`** — Add the default value to `DEFAULT_APP_CONFIG`
4. **`src/shared/utils/configHydration.ts`** — Check whether the key needs validation, repair, or selective nested merge. Top-level keys usually need no code here; nested object keys and enum-like values usually do.
5. **UI binding** — Add the field to the relevant preference composable and component save flow
6. **All 27 locale files** — Add i18n label keys. **Must use batch Python script** (see Section D)
7. **Compatibility** — This product has a fresh storage identity. Do not add import aliases or migrations for another product.