pnpm scripts#

PacketBench ships no command-line binary. The scripts block in package.json is the closest thing it has to a CLI surface: 48 entries covering the dev loop, five quality gates, thirteen sidecar smoke tests, the Node-runtime fetch, the release gate and two macOS build workarounds. There is no CI, so every one of them runs on a developer's machine or it does not run at all.

This page lists every script in package.json, what each one actually executes, and when to reach for it. It also owns the "match the gate to the change" table, which decides how far up the ladder a given change has to climb.

Ordering. The table below is in source order — the order the scripts are declared in package.json — not alphabetical, so it reads the way the file reads. Composites are unpacked in the sections that follow.

Every script#

The three rungs#

The gates form a ladder. Each rung contains the one below it, so you never need to run both.

pnpm preflight          format:check → lint:src → test → build
       │
pnpm check              preflight → e2e → sidecar:check → check:tauri-schema
       │                         → rust:check → rust:test
       │
pnpm release:readiness  those nine, executed, plus the distribution report

release-readiness.mjs declares the nine gates it executes explicitly (scripts/release-readiness.mjs:32-42) and reports check as a row derived from those results rather than executed. Running it as a tenth gate would run everything a second time. The script re-derives that relationship from package.json on every run and refuses to claim the composite if the scripts have drifted (scripts/release-readiness.mjs:22-31).

Match the gate to the change#

pnpm preflight is the floor. Climb from there according to what you touched.

Release-facing work climbs the whole ladder and then runs pnpm release:readiness. dev/local-quality-gates.md is the canonical ladder document in the repository — and it is itself covered by format:check, so editing it with the wrong Prettier formatting breaks preflight.

What the composites expand to#

Every chain uses &&, so the first non-zero exit stops the run. There is no --continue-on-error anywhere in the block.

Scripts you do not type#

Sharp edges#

These bite, and they are documented rather than fixed.

format and format:check cover disjoint file sets. format writes src/**/*.{ts,tsx,css}. format:check reads package.json, eslint.config.js, dev/local-quality-gates.md and e2e/**/*.{ts,tsx}. There is no overlap at all, so running pnpm format cannot fix a format:check failure, and a format:check pass says nothing about src/. Fix the four checked targets by hand, or point Prettier at them directly.

pnpm sidecar:build fails after a production build. prune-sidecar.js runs pnpm -C agent-sidecar install --prod --ignore-scripts, which removes typescript and @types/node from the sidecar's node_modules. Re-run pnpm sidecar:install to restore them. The script header says so at scripts/prune-sidecar.js:14-24, and it catches everyone once.

Run the bare pnpm test, not vitest src. Scoping to a directory silently skips the repository fences, which are pulled in by the scripts/** glob in vitest.config.ts:15. Those fences walk the whole source tree, which is why pnpm test can fail with no test file anywhere near your change.

pnpm dev and pnpm e2e both want port 1420. Vite is configured with strictPort (vite.config.ts:76-77) and Playwright starts its own server on the same port, with reuseExistingServer on outside CI (playwright.config.ts:34-40). Locally the e2e run attaches to a dev server you already have up; set PLAYWRIGHT_PORT to separate them.

lint:strict gates nothing. preflight runs lint:src, which tolerates warnings. The 0.13.1 release recorded pnpm lint as green with nine pre-existing warnings — see Testing & gates.

build:macos, not pnpm tauri build, on macOS. bundle_dmg.sh runs a cosmetic Finder AppleScript that fails on roughly half of first attempts and abandons a mounted scratch image when it does. The wrapper builds once, detaches the leaked image and retries just the DMG step; the Rust artifacts are cached, so the retry is cheap (scripts/build-macos.mjs:5-15).

Related#

• Testing & gates — what each gate proves, and what was green at the last release
• Build & release — the toolchain, the bundle chain and the release checklist
• Contributing — commit conventions and the review bar these gates enforce
• Agent orientation — the machine-readable briefing that points agents at this ladder
• Environment variables — PACKETBENCH_RELEASE_GATE_TIMEOUT_MS and the other knobs these scripts read
• Troubleshooting — when a gate fails for a reason that is not your change