pi-rust-skills 0.1.0

package/skills/rust-refactor-migration/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: rust-refactor-migration
+description: Refactors Rust code safely across modules, crates, editions, dependency upgrades, async conversions, error type migrations, API cleanup, and workspace restructuring. Use for planned Rust codebase modernization.
+license: MIT
+compatibility: Rust stable with cargo recommended.
+---
+
+# Rust Refactor Migration
+
+Use this skill for non-trivial Rust refactors where behavior must stay stable while structure changes.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Establish baseline validation before changes:
+   ```bash
+   cargo fmt --check
+   cargo clippy --workspace --all-targets --all-features -- -D warnings
+   cargo test --workspace --all-features
+   ```
+3. Identify public API and compatibility constraints.
+4. Make refactors in small mechanical steps.
+5. Keep tests passing between steps when possible.
+6. Separate behavior changes from structure changes.
+7. Document migration notes for users or future agents.
+
+## Common refactors
+
+### Split a large module
+
+- Move types first, then functions.
+- Re-export public API from the old module if compatibility matters.
+- Keep visibility narrow: prefer `pub(crate)` over `pub`.
+- Add deprecation notes before removing old public paths unless a breaking change is intended.
+
+### Convert binary logic into library logic
+
+- Move business logic from `main.rs` into `lib.rs` or modules.
+- Keep CLI parsing and process exit behavior in `main.rs`.
+- Add integration tests against library functions and CLI smoke tests.
+
+### Error migration
+
+- Replace string errors with typed errors in libraries.
+- Add context at boundaries.
+- Avoid exposing `anyhow::Error` in reusable library APIs unless intentionally application-facing.
+
+### Edition migration
+
+Use Cargo's migration support:
+
+```bash
+cargo fix --edition
+cargo fmt
+cargo test --all-features
+```
+
+Then manually review changed code for readability.
+
+### Dependency upgrade
+
+```bash
+cargo update -p crate_name
+cargo tree -d
+cargo test --all-features
+```
+
+Review changelog for breaking behavior, not just compiler errors.
+
+## API compatibility
+
+- Use `cargo semver-checks` when installed for public libraries.
+- Compare docs, exported types, trait bounds, feature flags, and re-exports before and after the refactor.
+- Keep compatibility re-exports until downstream users have a migration path.
+- Stage large migrations as mechanical move, compatibility shim, behavior change, then cleanup.
+
+## Refactor safety rules
+
+- Do not rewrite working Rust into clever Rust.
+- Prefer explicit intermediate variables when they clarify ownership.
+- Avoid introducing generics unless reuse is proven.
+- Keep public names stable unless a breaking change is requested.
+- If tests are weak, add characterization tests before refactoring.
+- Review dependency changelogs before changing major versions or feature defaults.
+
+## Output expectations
+
+Summarize baseline status, refactor steps completed, behavior changes if any, validation results, and follow-up cleanup tickets.
+
+## Avoid
+
+- Do not mix mechanical moves with behavior changes in the same step.
+- Do not remove compatibility shims without calling out the breaking change.
+- Do not accept a green narrow test when public API or workspace behavior changed.

package/skills/rust-security-audit/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: rust-security-audit
+description: Audits Rust projects for unsafe code, dependency vulnerabilities, secret handling, injection risks, path traversal, deserialization hazards, cryptography misuse, supply-chain risk, and cargo-audit/cargo-deny findings. Use for Rust security reviews.
+license: MIT
+compatibility: Rust stable. Optional tools include cargo-audit, cargo-deny, cargo-geiger, and cargo-vet.
+---
+
+# Rust Security Audit
+
+Use this skill for Rust security reviews, dependency audits, unsafe-code reviews, and hardening tasks.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Define the trust boundary: inputs, files, network, environment variables, subprocesses, database queries, and external services.
+3. Inspect `Cargo.lock`, features, build scripts, unsafe code, and parsing/deserialization paths.
+4. Run available security tools.
+5. Review risky code manually; do not rely only on scanners.
+6. Produce findings with severity, exploitability, evidence, and fix.
+
+## Commands
+
+Use what is available; do not fail the task only because optional tools are missing.
+
+```bash
+cargo audit
+cargo deny check
+cargo geiger
+cargo tree -e features
+cargo update -p vulnerable_crate
+```
+
+Always run core validation after changes:
+
+```bash
+cargo fmt --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --all-features
+```
+
+For package-specific audits, narrow to the affected crate with `-p crate_name` after workspace context is understood.
+
+## Threat model
+
+| Boundary | Review focus |
+|---|---|
+| Files and paths | Traversal, symlink handling, overwrite rules, temp file safety |
+| Network and HTTP | SSRF, TLS settings, redirects, request size, timeout policy |
+| Environment and config | Secret leakage, unsafe defaults, untrusted config parsing |
+| Subprocesses | Shell injection, inherited environment, argument escaping |
+| Dependencies and build scripts | Vulnerabilities, native code, scripts, maintainer and license risk |
+
+## Checklist
+
+### Unsafe code
+
+- Every unsafe block has a precise safety comment.
+- No unsound aliasing, lifetime extension, or invalid initialization.
+- FFI boundaries validate null pointers and buffer lengths.
+- Unsafe abstractions expose safe APIs that enforce invariants.
+
+### Input handling
+
+- Validate paths to prevent traversal and unintended overwrite.
+- Treat environment variables and config files as untrusted.
+- Avoid shell injection; prefer `Command::new(program).arg(value)` over shell strings.
+- Bound input size for parsers and decompression.
+
+### Secrets
+
+- Do not log secrets, tokens, cookies, private keys, or passwords.
+- Use secret-specific types or redaction wrappers when possible.
+- Avoid storing secrets in panic messages, errors, or snapshots.
+- Search for committed secrets and generated fixtures that may contain credentials.
+
+### Deserialization
+
+- Avoid deserializing untrusted data into overly permissive types.
+- Validate semantic constraints after parsing.
+- Watch for YAML, regex, XML, archive, and compression edge cases.
+
+### Crypto
+
+- Prefer well-reviewed high-level crates.
+- Avoid custom crypto.
+- Use constant-time comparison for secrets when relevant.
+- Validate randomness source and nonce uniqueness.
+
+### Supply chain
+
+- Review `build.rs`, proc macros, git dependencies, path dependencies, and broad feature flags.
+- Prefer `cargo-deny` policies for advisories, duplicate versions, licenses, and banned crates.
+- Generate SBOM or dependency inventory when the project or release process requires it.
+
+## Finding format
+
+```markdown
+### Severity: High - Path traversal allows overwrite outside output directory
+
+- Location: `src/archive.rs:42`
+- Evidence: user-controlled archive path is joined without normalization checks
+- Impact: attacker can overwrite arbitrary writable files
+- Fix: reject absolute paths and components containing `..`; canonicalize destination
+- Validation: added regression test and ran `cargo test --all-features`
+```
+
+## Avoid
+
+- Do not treat scanner output as complete coverage.
+- Do not silence advisories without documenting exploitability and compensation.
+- Do not add secret values to tests, logs, snapshots, or issue reports.

package/skills/rust-testing/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: rust-testing
+description: Designs and implements Rust unit tests, integration tests, doc tests, property tests, snapshot tests, test fixtures, cargo-nextest workflows, and CI validation. Use when adding or improving Rust test coverage.
+license: MIT
+compatibility: Rust stable toolchain with cargo recommended. Optional tools include cargo-nextest, insta, proptest, and tarpaulin.
+---
+
+# Rust Testing
+
+Use this skill when writing tests, improving test structure, reproducing bugs, or creating a validation plan for a Rust project.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Identify the behavior contract before writing tests.
+3. Choose the right test type:
+   - Unit tests inside modules for small pure logic.
+   - Integration tests under `tests/` for public behavior.
+   - Doc tests for public APIs and examples.
+   - Property tests for parser, serializer, state machine, or invariant-heavy code.
+   - Snapshot tests for stable text or structured output.
+   - Compile-fail tests for macros, trait errors, and public API guarantees.
+   - Concurrency model tests for lock-free or synchronization-heavy code.
+4. Write at least one failing test before fixing a bug when practical.
+5. Keep test data small, explicit, and local to the test.
+6. Validate with all relevant feature flags.
+
+## Commands
+
+```bash
+cargo test
+cargo test --all-features
+cargo test --workspace --all-targets
+cargo test -p crate_name --all-features
+cargo test test_name -- --nocapture
+cargo test --doc
+```
+
+If `cargo-nextest` is installed:
+
+```bash
+cargo nextest run --all-features
+```
+
+## Test design rules
+
+- Tests should explain behavior, not implementation details.
+- Prefer descriptive test names like `returns_error_when_config_file_is_missing`.
+- Avoid sleeps in async tests; use controlled clocks, channels, or timeouts.
+- Avoid tests that depend on the user's machine, network, current date, or global state.
+- Use temporary directories for filesystem tests.
+- Keep fixtures minimal and local. Store large reusable fixtures under `tests/fixtures/` with names that explain the scenario.
+- Assert exact errors when the error is part of the contract; otherwise assert stable categories.
+- For snapshots, review diffs before accepting updates and never bless unrelated churn.
+
+## Specialized tools
+
+- Use `trybuild` for proc macro and compile-fail API tests.
+- Use `loom` for synchronization code where interleavings matter.
+- Use `miri` for unsafe code, aliasing-sensitive logic, and UB checks when it is available.
+- Use `insta` snapshots for stable structured output, not volatile logs.
+
+## Async tests
+
+For Tokio projects:
+
+```rust
+#[tokio::test]
+async fn handles_timeout() {
+    // test body
+}
+```
+
+Use `#[tokio::test(flavor = "multi_thread")]` only when concurrency behavior needs it. Prefer `current_thread` for deterministic tests.
+
+Use `tokio::time::pause` and explicit time advancement when timer behavior must be deterministic.
+
+## Property tests
+
+Use property tests when input space matters more than examples:
+
+```rust
+proptest! {
+    #[test]
+    fn round_trips(value in any::<u32>()) {
+        let encoded = encode(value);
+        prop_assert_eq!(decode(&encoded).unwrap(), value);
+    }
+}
+```
+
+## Output expectations
+
+When finished, report:
+
+- Test cases added.
+- Bug or behavior each test protects.
+- Commands run and pass/fail status.
+- Coverage gaps that remain.
+
+## Avoid
+
+- Do not add sleeps, real network calls, or machine-dependent paths unless the behavior under test requires them.
+- Do not broaden assertions until failures stop being useful.
+- Do not update snapshots without explaining the intended behavior change.

package/skills/rust-toolchain-ci/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: rust-toolchain-ci
+description: Configures Rust toolchains, rust-toolchain.toml, cargo aliases, rustfmt, clippy lint policy, GitHub Actions, caching, cross-platform CI, MSRV checks, and release validation. Use for Rust project automation and CI setup.
+license: MIT
+compatibility: Rust stable with cargo. CI examples target GitHub Actions but can be adapted.
+---
+
+# Rust Toolchain CI
+
+Use this skill when setting up Rust automation, linting policy, formatting, MSRV checks, and CI workflows.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Inspect the project's supported Rust version, edition, targets, and workspace shape.
+3. Decide whether to pin Rust with `rust-toolchain.toml`.
+4. Add consistent local commands via docs or Cargo aliases.
+5. Add CI that matches local validation.
+6. Keep CI fast enough that developers will trust it.
+
+## rust-toolchain.toml
+
+```toml
+[toolchain]
+channel = "stable"
+components = ["rustfmt", "clippy"]
+```
+
+Use a specific version only when MSRV or reproducibility matters:
+
+```toml
+[toolchain]
+channel = "1.85.0"
+components = ["rustfmt", "clippy"]
+```
+
+## Cargo aliases
+
+`.cargo/config.toml`:
+
+```toml
+[alias]
+xtask = "run --package xtask --"
+ci-check = "check --workspace --all-targets --all-features"
+ci-test = "test --workspace --all-features"
+```
+
+## GitHub Actions baseline
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  rust:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy --workspace --all-targets --all-features -- -D warnings
+      - run: cargo test --workspace --all-features
+```
+
+For cross-platform projects, add a matrix for `ubuntu-latest`, `windows-latest`, and `macos-latest`.
+
+For Pi packages or mixed Node/Rust repositories, include package validation such as `npm test`, `npm run list`, or `npm pack --dry-run` in a separate Node job.
+
+## CI policy
+
+- Set minimal permissions, usually `contents: read`.
+- Cache Cargo dependencies with keys that include OS, toolchain, and lockfile.
+- Add a docs job with `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace --all-features` for libraries.
+- Add optional audit jobs with `cargo audit` or `cargo deny check` when the project has the tool config.
+- Keep MSRV checks focused on `cargo check` unless old clippy behavior is part of the policy.
+
+## MSRV
+
+If the crate declares `rust-version`, add a separate MSRV job. Keep MSRV checks focused; do not require clippy on old compilers unless necessary.
+
+## Output expectations
+
+Explain local commands, CI jobs, caching choices, MSRV policy, and any follow-up release automation.
+
+## Avoid
+
+- Do not make CI stricter than documented local commands without explaining the policy.
+- Do not run privileged tokens or write permissions on pull request checks unless required.
+- Do not hide flaky tests by allowing failures in the required validation path.

package/skills/rust-wasm/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rust-wasm
+description: Builds Rust WebAssembly projects with wasm-pack, wasm-bindgen, web-sys, js-sys, browser or Node targets, bundler integration, size optimization, and wasm tests. Use for Rust code compiled to WebAssembly.
+license: MIT
+compatibility: Rust stable with wasm32 target. Optional tools include wasm-pack, wasm-bindgen-cli, trunk, and wasm-opt.
+---
+
+# Rust WASM
+
+Use this skill for Rust projects targeting WebAssembly for browser apps, Node packages, plugin sandboxes, or shared computational modules.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Confirm target environment: browser, Node, bundler, no-bundler, WASI, or embedded runtime.
+3. Add the correct crate type:
+   ```toml
+   [lib]
+   crate-type = ["cdylib", "rlib"]
+   ```
+4. Keep the core logic platform-neutral. Put browser bindings behind a thin `wasm-bindgen` layer.
+5. Minimize boundary crossings between JavaScript and Rust.
+6. Validate both native tests for core logic and wasm-specific tests for bindings.
+
+## Common setup
+
+```toml
+[dependencies]
+wasm-bindgen = "0.2"
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+js-sys = "0.3"
+web-sys = { version = "0.3", features = ["console"] }
+```
+
+Add target:
+
+```bash
+rustup target add wasm32-unknown-unknown
+```
+
+Build with wasm-pack:
+
+```bash
+wasm-pack build --target web
+wasm-pack build --target bundler
+wasm-pack build --target nodejs
+```
+
+Choose `web` for browser-native loading, `bundler` for Vite/Webpack/Rollup packages, and `nodejs` for Node consumers and CI tests.
+
+## Design rules
+
+- Avoid exposing complex Rust lifetimes across the wasm boundary.
+- Prefer simple structs, strings, numbers, typed arrays, and serialized data at the boundary.
+- Keep panics visible during development with `console_error_panic_hook` when appropriate.
+- Watch binary size. Review dependencies, feature flags, and `wee_alloc` only if justified.
+- Avoid assuming browser APIs exist in Node or test environments.
+- Generate TypeScript declarations when publishing JS-facing packages.
+- Keep feature gates clear for native-only and wasm-only dependencies.
+
+## Testing
+
+Native core tests:
+
+```bash
+cargo test
+```
+
+WASM tests with wasm-pack:
+
+```bash
+wasm-pack test --node
+wasm-pack test --headless --firefox
+```
+
+Use `wasm-bindgen-test` for binding behavior and native `cargo test` for platform-neutral logic.
+
+## Optimization
+
+For release builds:
+
+```toml
+[profile.release]
+opt-level = "z"
+lto = true
+codegen-units = 1
+panic = "abort"
+```
+
+Use `wasm-opt` only after confirming it is installed and appropriate for the pipeline.
+
+Set a size budget when package size matters, and compare the generated `.wasm` artifact before and after dependency or profile changes.
+
+## Output expectations
+
+State the selected wasm target, JS integration path, files changed, build/test commands, and any size or compatibility tradeoffs.
+
+## Avoid
+
+- Do not expose complex lifetimes or Rust-only types across the JS boundary.
+- Do not assume browser APIs in Node targets or CI.
+- Do not add wasm size optimizations before measuring the artifact.

package/skills/rust-web-api/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rust-web-api
+description: Builds and reviews Rust web APIs with Axum, Actix Web, Hyper, routing, extractors, middleware, request validation, auth boundaries, OpenAPI, graceful shutdown, and HTTP integration tests. Use for Rust server and web service work.
+license: MIT
+compatibility: Rust stable. Common stacks include Axum, Actix Web, Hyper, Tower, Tokio, Serde, and utoipa.
+---
+
+# Rust Web API
+
+Use this skill when creating, changing, testing, or reviewing Rust HTTP APIs and services.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Identify the API contract: routes, methods, request and response schemas, auth, errors, and compatibility expectations.
+3. Keep transport concerns near the router and business logic in testable modules.
+4. Add integration tests for happy paths, validation errors, auth failures, and shutdown behavior.
+5. Validate with workspace-aware cargo commands and any service-specific tests.
+
+## Design rules
+
+- Prefer explicit typed extractors and response types over ad hoc JSON maps.
+- Validate request size, content type, path/query parameters, and semantic constraints.
+- Keep auth and authorization boundaries visible in middleware or extractors.
+- Use structured errors that map predictably to HTTP status codes and response bodies.
+- Add tracing spans for request IDs, route names, latency, and error classification.
+- Document public APIs with OpenAPI only when consumers need a stable contract.
+- Implement graceful shutdown for long-running services and background tasks.
+
+## Testing
+
+```bash
+cargo test --workspace --all-features
+cargo test -p crate_name --test api
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Test handlers through the router when possible. Use real HTTP only when socket behavior, TLS, middleware layers, or deployment wiring matters.
+
+## Avoid
+
+- Do not put database, auth, and business logic directly in route handlers.
+- Do not return inconsistent error shapes for the same API.
+- Do not log tokens, cookies, request bodies with secrets, or authorization headers.
+
+## Output expectations
+
+Report the API contract changed, routes affected, validation commands, and any compatibility or auth implications.