1# Contributing to lofi-node23## Prerequisites45- Deno 2.9+ (the only global runtime requirement for the TS side)6- Rust stable (only when touching `native/iroh-js/`; `deno task native` builds the addon)78## The gate910```sh11deno task check && deno task test12```1314`check` runs fmt --check, lint, and typecheck. `test` runs the full fixture suite; iroh/jazz15integration tests auto-skip (with a visible marker) when the native addon isn't built, so the fast16path never needs Rust.1718## Branches & PRs1920Prefix branches by intent (`fix/`, `feat/`, `docs/`, `chore/`), keep a PR to one concern, and state21the evidence for behavior claims (test name or command output) in the description.2223## Hard boundaries2425- **Vendoring contract**: everything under `native/iroh-js/` except `src/lofi_ext.rs` is upstream26 code. Never edit vendored files beyond `// lofi-node:` marked lines; follow the update procedure27 in `native/iroh-js/UPSTREAM.md`. `deno fmt`/`lint` exclude the directory — keep it that way.28- **Version pins are decisions**: `jazz-tools`/`jazz-napi` are pinned to the exact alpha the lofi29 framework pins. Bumps are coordinated changes with the full suite as evidence, never drive-by.30- **No silent degradation**: a missing capability (native addon, platform) must surface as a typed31 reason in `status()`, never as quietly reduced behavior.32- **Secrets**: nothing under `lofi-node-data/`, `data/`, or generated `config.json` files may be33 committed; test secrets are obviously-fake fixed strings.34- **Never call the upstream watch APIs** from the TS layer — at iroh-ffi v1.1.0 they abort the35 process under Deno (see UPSTREAM.md known issues).3637## Releasing3839Published to JSR as `@nzip/lofi-node`. The package ships TypeScript only; native addons are40GitHub-release assets that the loader downloads and sha256-verifies against digests committed in41`src/native/artifacts.ts` (regenerate with `deno task release:artifacts` — CI fails if stale).4243Procedure (tags on `main`, no dev branch):44451. Bump `version` in `deno.json`; run `deno task release:artifacts`.462. `deno task check && deno task test`, then inspect the artifact: `deno task publish:dry`.473. Commit, push, wait for ci green.484. `git tag v<version> && git push origin v<version>` — publish.yml verifies the tag matches49 `deno.json`, publishes to JSR via OIDC, compiles the release binaries (darwin-arm64 and50 linux-x64; linux-arm64 is withheld until jazz-napi publishes a linux-arm64-gnu package), creates51 the GitHub release with binaries + raw addon assets + `SHA256SUMS`, smokes the fresh publish from52 the registry, and builds, smokes, and pushes the container image to53 `ghcr.io/felinestatemachine/lofi-node` (`<version>` and `latest` tags).545. JSR versions are immutable — mistakes fix forward as the next patch version.