AGENTS.md

1# AGENTS.md - Spacedrive Core v2
2 
3## Build/Test Commands
4 
5- `cargo build` - Build the project
6- `cargo test` - Run all tests
7- `cargo test <test_name>` - Run specific test (e.g., `cargo test library_test`)
8- `cargo clippy` - Lint code
9- `cargo fmt` - Format code
10- `cargo run --bin sd-cli -- <command>` - Run CLI (note: binary is `sd-cli`, not `spacedrive`)
11 
12## Code Style
13 
14- **Imports**: Group std, external crates, then local modules with blank lines between
15- **Formatting**: Use `cargo fmt` - tabs for indentation, snake_case for variables/functions. DO NOT use emojis at all.
16- **Types**: Explicit types preferred, use `Result<T, E>` for error handling with `thiserror`
17- **Naming**: snake_case for functions/variables, PascalCase for types, SCREAMING_SNAKE_CASE for constants
18- **Error Handling**: Use `Result` types, `thiserror` for custom errors, `anyhow` for application errors
19- **Async**: Use `async/await`, prefer `tokio` primitives, avoid blocking operations
20- **Resumable Jobs**: For long-running jobs that need to be resumable, store the job's state within the job's struct itself. Use `#[serde(skip)]` for fields that should not be persisted. For example, in a file copy job, the list of already copied files can be stored to allow the job to resume from where it left off.
21- **Documentation**: Use `//!` for module docs, `///` for public items, include examples
22- **Architecture**: Follow a Command Query Responsibility Segregation (CQRS) and Domain-Driven Design (DDD) pattern.
23  - **Domain**: Core data structures and business logic are located in `src/domain/`. These are the "nouns" of your system.
24  - **Operations**: State-changing commands (actions) and data-retrieving queries are located in `src/ops/`. These are the "verbs" of your system.
25  - **Actions**: Operations that modify the state of the application. They should be self-contained and transactional.
26  - **Queries**: Operations that retrieve data without modifying state. They should be efficient and optimized for reading.
27- **Feature Modules**: Each new feature should be implemented in its own module within the `src/ops/` directory. For example, a new "share" feature would live in `src/ops/files/share`. Each feature module should contain the following files where applicable:
28  - `action.rs`: The main logic for the state-changing operation.
29  - `input.rs`: Data structures for the action's input.
30  - `output.rs`: Data structures for the action's output.
31  - `job.rs`: If the action is long-running, the job implementation.
32- **Database**: Use SeaORM entities, async queries, proper error propagation
33- **Comments**: Minimal inline comments, focus on why not what, no TODO comments in production code
34 
35## Daemon Architecture
36 
37Spacedrive uses a **daemon-client architecture** where a single daemon process manages the core functionality and multiple client applications (CLI, GraphQL server, desktop app) connect to it via Unix domain sockets.
38 
39> **For detailed daemon architecture documentation, see [/docs/core/daemon.md](/docs/core/daemon.md)**
40 
41### **The `Wire` Trait**
42 
43All actions and queries must implement the `Wire` trait to enable type-safe client-daemon communication:
44 
45```rust
46pub trait Wire {
47    const METHOD: &'static str;
48}
49```
50 
51### **Registration Macros**
52 
53Instead of manually implementing `Wire`, use these registration macros that automatically:
54 
551. Implement the `Wire` trait with the correct method string
562. Register the operation in the global registry using the `inventory` crate
57 
58**For Queries:**
59 
60```rust
61crate::register_query!(NetworkStatusQuery, "network.status");
62// Generates method: "query:network.status"
63```
64 
65**For Library Actions:**
66 
67```rust
68crate::register_library_action!(FileCopyAction, "files.copy");
69// Generates method: "action:files.copy.input"
70```
71 
72**For Core Actions:**
73 
74```rust
75crate::register_core_action!(LibraryCreateAction, "libraries.create");
76// Generates method: "action:libraries.create.input"
77```
78 
79### **Registry System**
80 
81- **Location**: `core/src/ops/registry.rs`
82- **Mechanism**: Uses the `inventory` crate for compile-time registration
83- **Global Maps**: `QUERIES` and `ACTIONS` hashmaps populated at startup
84- **Handler Functions**: Generic handlers that decode payloads, execute operations, and encode results
85 
86## Logging Standards
87 
88- **Setup**: Use `tracing_subscriber::fmt()` with env filter for structured logging
89- **Macros**: Use `info!`, `warn!`, `error!`, `debug!` from `tracing` crate, not `println!`
90- **Job Context**: Use `ctx.log()` in jobs for job-specific logging with automatic job_id tagging
91- **Structured**: Include relevant context fields: `debug!(job_id = %self.id, "message")`
92- **Levels**: debug for detailed flow, info for user-relevant events, warn for recoverable issues, error for failures
93- **Format**: `tracing_subscriber::fmt().with_env_filter(env_filter).init()` in main/examples
94- **Environment**: Respect `RUST_LOG` env var, fallback to module-specific filters like `sd_core=info`
95 
96## Documentation
97 
98- **Core level docs**: Live in `/docs/core` - comprehensive architecture and implementation guides
99- **Core design docs**: Live in `/docs/core/design` - planning documents, RFCs, and design decisions
100- **Application level docs**: Live in `/docs`
101- **Code docs**: Use `///` for public APIs, `//!` for module overviews, include examples
102 
103## Debug Instructions
104 
105- You can view the logs of a job in the job_logs directory in the root of the data folder
106- When testing the CLI, after compiling you must first use the `restart` command to ensure the Spacedrive daemon is using the latest build.
107