Skip to content
Skills Library
Programming · Building & coding

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.

Repository
archestra ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. Default posture: boring Rust
  2. Architecture
  3. Types and data modeling
  4. Ownership defaults
  5. Control flow and style
  6. Abstractions
  7. Macros and code generation
  8. Errors and safety
  9. Rust footprint discipline
  10. Cleanliness
Original SKILL.md headings · 148 lines, 1,408 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.