moltis CLAUDE.md

CLAUDE.md

Rust version of openclaw (docs, code). All code must have tests with high coverage. Always check for security.

Cargo Features

Enable new feature flags by default in crates/cli/Cargo.toml (opt-out, not opt-in):

[features]
default = ["foo", ...]
foo = ["moltis-gateway/foo"]

Workspace Dependencies

Add new crates to [workspace.dependencies] in root Cargo.toml, reference with { workspace = true }. Never add versions directly in crate Cargo.toml. Use latest stable crates.io version.

Config Schema and Validation

When adding/renaming fields in MoltisConfig (crates/config/src/schema.rs), also update build_schema_map() in crates/config/src/validate.rs. New enum variants for string-typed fields need updates in check_semantic_warnings().

Rust Style and Idioms

• File size limit: 1,500 lines. CI enforces this via scripts/check-file-size.sh. Split large files into modules by domain. Existing oversize files are allowlisted for incremental decomposition.
• Do not add implementation code to mod.rs or lib.rs. Keep those files for module wiring, exports, and crate setup, move real logic into dedicated sibling modules.
• Use traits for behaviour boundaries. Prefer generics for hot paths, dyn Trait for heterogeneous/runtime dispatch.
• Derive Default when all fields have sensible defaults.
• Use concrete types (struct/enum) over serde_json::Value wherever shape is known.
• Match on types, never strings. Only convert to strings at serialization/display boundaries.
• Prefer From/Into/TryFrom/TryInto over manual conversions. Ask before adding manual conversion paths.
• DRY cross-crate types: When two crates need the same enum/struct, define it once in the lower-level crate and re-export via pub type Alias = other_crate::Type from the higher-level one. Never duplicate enums across crates or round-trip through strings (parse(&id.to_string())) to convert between mirror types.
• Prefer streaming over non-streaming API calls.
• Run independent async work concurrently (tokio::join!, futures::join_all).
• Never use block_on inside async context.
• Forbidden: Mutex<()> / Arc<Mutex<()>> — mutex must guard actual state.
• Use anyhow::Result for app errors, thiserror for library errors. Propagate with ?.
• Never .unwrap()/.expect() in production. Workspace lints deny these. Use ?, ok_or_else, unwrap_or_default, unwrap_or_else(|e| e.into_inner()) for locks.
• Use time crate (workspace dep) for date/time — no manual epoch math or magic constants like 86400.
• Prefer chrono only if already imported in the crate; default to time for new code.
• Prefer crates over subprocesses (std::process::Command). Use subprocesses only when no mature crate exists.
• Prefer guard clauses (early returns) over nested if blocks.
• Prefer iterators/combinators over manual loops. Use Cow<'_, str> when allocation is conditional.
• Keep public API surfaces small. Use #[must_use] where return values matter.