archestra-dev-rust-napi
/archestra-dev-rust-napi
Use when editing Rust in this repo — the NAPI crates under platform/archestra-rs (app-runtime, image, and sandbox core/-rs crate pairs plus napi-loader, with their generated TypeScript bindings) or the standalone ai-labs Rust workspace (core/runner/cli/analyzer/dashboard) — including Rust build/test checks.
- Author
- archestra-ai ↗
- Repository
- archestra ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when editing Rust in this repo — the NAPI crates under platform/archestra-rs (app-runtime, image, and sandbox core/-rs crate pairs plus napi-loader, with their generated TypeScript bindings) or the standalone ai-labs Rust workspace (core/runner/cli/analyzer/dashboard) — including Rust build/test checks.
Original author description
Use when editing Rust in this repo — the NAPI crates under platform/archestra-rs (app-runtime, image, and sandbox core/-rs crate pairs plus napi-loader, with their generated TypeScript bindings) or the standalone ai-labs Rust workspace (core/runner/cli/analyzer/dashboard) — including Rust build/test checks.
How it works
- Default posture: boring Rust
- Architecture
- Types and data modeling
- Ownership defaults
- Control flow and style
- Abstractions
- Macros and code generation
- Errors and safety
- Rust footprint discipline
- Cleanliness
SKILL.md preview
--- name: archestra-dev-rust-napi description: Use when editing Rust in this repo — the NAPI crates under platform/archestra-rs (app-runtime, image, and sandbox core/-rs crate pairs plus napi-loader, with their generated TypeScript bindings) or the standalone ai-labs Rust workspace (core/runner/cli/analyzer/dashboard) — including Rust build/test checks. --- # Archestra Rust Coding Style This covers all Rust in the repo: - `platform/archestra-rs/*` — embedded in Node via NAPI. - `ai-labs/*` — a standalone pure-Rust workspace (core/runner/cli/analyzer/dashboard), no NAPI. The library-quality rules below apply everywhere. Rules tagged **(NAPI only)** apply only to Rust embedded via NAPI. Write Rust as a reusable library first. For NAPI crates the binding is a thin adapter around a Node-free core — deleting or replacing the NAPI layer should not delete or rewrite the product logic. The bench crates are already standalone Rust, so the same core-quality bar applies to them directly. ## Default posture: boring Rust Rust is a normal product language here, not a type-system puzzle. The first correct version should be boring and explicit. Prefer plain functions, concrete structs, enums for closed states, newtypes for domain identifiers, `Option<T>`/`Result<T, E>`, owned data at public boundaries and borrowed data inside small internal functions, and small modules named after domain concepts. Avoid by default: custom macros, actor frameworks, hidden global registries, smart-pointer graphs, runtime type erasure, and clever lifetime-heavy public APIs. (See Abstractions for trait-object and generics rules.) Do not make Rust code look like Java, TypeScript DI, or Haskell cosplay. ## Architecture Applies to all Rust: - Minimize the public API surface. Prefer a few coarse operations over many tiny exported helpers. - Keep observability in the core as `tracing` spans and events only. - OTLP/exporter wiring belongs in a single feature-gated module, never scattered through the logic. - Propagate trace context, such as W3C `traceparent`, explicitly across detached tasks and actor boundaries. It does not flow implicitly. **(NAPI only)** boundary rules: - Keep core Rust logic independent from Node, JavaScript, and NAPI. No `#[napi]`, `napi::Result`, JS types, or Node-specific assumptions in core modules. - NAPI functions should only receive JS input, validate and convert it into Rust domain types, call the Rust core, and convert the result or error back to JS. - Do not expose internal implementation details through the NAPI API. - Generated TypeScript definitions are part of the public API and should stay clean, stable, and intentional. ## Types and data modeling - Prefer structs, enums, and newtypes over primitive-heavy signatures, tuples, raw strings, boolean flags, and long positional argument lists. - Use enums for closed sets of states or modes. - Make invalid states unrepresentable where practical. - Treat all external input as untrusted (JS input at the NAPI boundary; argv, files, and network/process output in the bench). - Validate untrusted input at the public entry points and convert it immediately into Rust-native types, not deep in the call graph. - Data validated when first accepted, such as persisted or replayed history, is trusted on reuse. Document that trust boundary wherever it is not obvious. - Keep boundary-facing DTOs separate from richer internal domain types when that improves clarity. ## Ownership defaults Start with values, references, and clear ownership. - Public domain structs should usually own their data. - Avoid public structs with lifetime parameters unless there is a clear performance or API reason. - Cloning small strings, IDs, config values, and DTO fields is acceptable when it keeps ownership simple. - Do not clone large buffers, request bodies, process output, or hot-path data without a reason. - Do not use `Box<T>` unless the type is recursive, very large, or must be behind a stable pointer. - Do not use `Rc<T>` or `RefCell<T>` in product logic unless modeling a local graph/tree where ownership is inherently shared. - Do not use `Arc<T>` unless data must cross task or thread boundaries. - Do not use `Arc<Mutex<T>>` as a default escape hatch. If used, document what is shared, who locks it, and why message passing or single ownership is worse. - Never hold a lock across `.await`. - Do not use `Pin`, self-referential structs, or unsafe lifetime tricks unless explicitly requested and reviewed. - Do not add indirection to avoid understanding ownership. Fix the ownership model instead. ## Control flow and style - Prefer `match` for enums, variants, and meaningful branching. - Prefer early returns for validation and error paths. - Avoid deeply nested control flow. - Prefer functional style where it reads better, but do not force iterator chains when a simple loop is clearer. ## Abstractions Abstractions must pay rent immediately. - Do not introduce a trait unless there are at least two real implementations today, or it represents a real boundary such as storage, process execution, clock/time, network I/O, or NAPI adapter isolation. - Do not create `FooService`, `FooManager`, `FooProvider`, or `FooFactory` traits just to make testing easier. Prefer passing concrete input data, small pure functions, or explicit test fixtures. - Avoid `dyn Trait`. Use concrete types first, an enum when the set of implementations is closed, and generics only when the caller truly needs static polymorphism. `dyn Trait` requires a written justification in the PR summary: why runtime polymorphism is needed, what the concrete implementations are, and why an enum or concrete type is worse. - Avoid `async_trait` unless integrating with an existing async trait API. Prefer concrete async functions. - Do not add generic type parameters unless there are multiple real call sites with different concrete types, or the generic is a standard Rust convenience such as accepting a path-like input. - Keep modules small and named around domain concepts, not patterns. ## Macros and code generation Macros are not a product architecture tool. - Do not introduce custom `macro_rules!` macros for normal product logic, and do not introduce proc macros. - Existing framework derives already used by the crate, such as NAPI/serde-style derives, are fine. - Do not hide validation, I/O, error mapping, authorization, tracing, or control flow behind macros. - Generated TypeScript bindings are public API. Keep generated names boring and stable. ## Errors and safety - Use `Result<T, E>` consistently in library code. - Prefer domain-specific error enums over generic strings. - Preserve useful error context. - Avoid `unwrap`, `expect`, and `panic!` in library code. Pragmatic `unwrap`/`expect` is acceptable only in CLI entrypoints, build scripts, and tests. - `expect` is acceptable on provably-infallible static initializers (e.g. `LazyLock<Regex>` over a literal pattern), where the message documents the invariant. This carve-out applies everywhere, including NAPI-reachable code. - No `unsafe` unless isolated, documented, and clearly justified. - **(NAPI only)** No `unwrap`, `expect`, or `panic!` in code reachable from the NAPI boundary, except the static-initializer carve-out above. Convert Rust errors into JS/NAPI errors only at the boundary. Assume dependencies can still panic despite that rule: wrap every future that enters the core from the NAPI boundary in `catch_unwind` and convert the payload into a domain error. The host process must never abort on a Rust panic. ## Rust footprint discipline Do not expand the Rust footprint opportunistically. Reach for Rust when the task has at least one of: - A crisp input/output boundary. - Security, validation, sandboxing, parsing, or escaping logic. - Performance-sensitive code. - Logic that benefits from explicit domain states. - Code that should be reusable outside Node later. **(NAPI only):** - Do not move TypeScript code to Rust just because Rust is available. - Do not add a new NAPI export for every helper function. - A Rust change should leave the TypeScript-facing API smaller or equally simple. ## Cleanliness - Zero dead code: no commented-out code, unused exports, unused dependencies, or placeholder modules for later. - Keep dependencies minimal and justified; avoid crates for trivial functionality. ## Tests and checks - Test core logic directly in Rust. Add tests for validation, parsing, edge cases, and error handling. - Use JS/NAPI integration tests only for actual boundary behavior. - Keep every `cfg` or feature gate as narrow as its actual use. Code compiled only because a gate is wider than its callers is dead code and will trip `-D warnings`. - **(NAPI only)** Run checks under the default feature set and the binding's feature set, such as `napi` and `telemetry`, not only `--all-features`. - `platform/archestra-rs` and `ai-labs` are separate workspaces. Run the checks below in each workspace you touched. - Always run `cargo check` after finishing Rust work. - Required before merge: `cargo fmt`, `cargo check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test`. ## Design target For NAPI crates the desired shape is: ```text JS/Node -> thin NAPI adapter -> reusable Rust core ``` Not: ```text JS-flavored business logic written in Rust ``` The bench is the same idea without the adapter: keep `core`/`analyzer` reusable, and let `cli`/`runner`/`dashboard` stay thin.
Versions
The database has no other skills named archestra-dev-rust-napi.
Database snapshot: 13.11.2026 · package version 60b7466e6969 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100archestra-dev-e2e
Use when writing, debugging, or running Archestra Playwright e2e tests, API/UI fixtures, WireMock-backed tests, local/CI e2e setup, or test selectors. - 100archestra-dev-backend
Use when adding or changing Archestra backend routes, models, services, API request/response schemas, endpoint permissions, or OpenAPI/codegen for the generated API client. - 100rs-ecosystem
Use when integrating crates or ecosystem questions. Keywords: E0425, E0433, E0603, crate, cargo, dependency, feature flag, workspace, which crate to use, using external C libraries, creating Python extensions, PyO3, wasm, WebAssembly, bindgen, cbindgen, napi-rs, cannot find,… - 100exploring-rust-crates
Generate Rust documentation to understand crate APIs, structure, and usage. Use when exploring Rust code, understanding crate organization, finding functions/types/traits, or needing context about a Rust package in the HASH workspace. - 95port-from-typescript
Port TypeScript or JavaScript into Rust — construct mapping against runtime semantics, the traps (every number is an f64, two kinds of absent, structural typing, regex feature gaps), and the napi-rs and wasm-bindgen boundaries. Use when porting, rewriting, or migrating… - 100qwik-optimizer-development
Use when modifying or reviewing the Qwik optimizer under packages/optimizer, Rust transform code, WASM/NAPI bindings, optimizer snapshots, or optimizer-facing runtime behavior.