Verify Your Work

Verify Your Work

Every commit and every branch you open for review passes four checks. None of the four is advisory. One command runs them all:

pnpm verify     # build -> test -> lint -> format:check

Check	Command	Covers
Build	pnpm build	Runs tsc first, which covers the types
Tests	pnpm test	Vitest for the workspace, cargo test --workspace for Rust
Lint	pnpm lint	ESLint, clippy, comment density, version, branding
Format	pnpm format:check	Prettier and rustfmt; pnpm format applies both

The inner loop

pnpm verify:fast    # near 17 seconds, against 33 for the full run

verify:fast swaps pnpm build for pnpm typecheck. It builds the three workspace packages and runs tsc, and it skips vite build and generate:icons.

Run the full pnpm verify before you commit. Skipping the bundle skips the one check that catches:

• a new app with no entry in vite.config.ts, which builds nothing and mounts a 404;
• assets named from CSS or HTML that fail to resolve;
• code that compiles under tsc and fails to bundle, such as a bad dynamic import.

None of those three is a typing mistake. A green tsc proves nothing here.

Two rules on tests

A failing test is never fixed by deleting or skipping the test. If a test is wrong, name the reason in the commit message.

A bug fix arrives with the test that catches the bug. STANDARDS.md §8 names this as the one test rule that holds without exception.

Do not regenerate the lint baselines

Three files grandfather violations that predate the linters: eslint-suppressions.json, clippy-baseline.json, and comment-baseline.json. They are ratchets. They shrink, and they do not grow.

pnpm baseline regenerates all three and absorbs your new violation, which is the exact outcome the baselines exist to prevent. Fix the code instead.

Running the app

Port 1420 belongs to pnpm app, which is tauri dev. Tauri starts Vite itself and points the webview at a fixed URL. That port cannot move and cannot be shared, and anything else holding it fails the whole run.

pnpm app          # the desktop app, on 1420
pnpm dev:agent    # the same frontend in a plain browser, from 1430 up

pnpm dev:agent turns strictPort off. A second and a third instance then step up to 1431 and 1432 instead of colliding. Read the port that Vite prints.

Two failure modes cost hours, and both repeat:

• pnpm dev takes 1420, and the next pnpm app dies with EADDRINUSE.
• tauri dev exits without reaping its Vite child, which orphans a node process on 1420. Stopping the task kills the wrapper, and not the child. Kill it by pid.

A browser has no Rust under it. pnpm dev:agent serves the same files, and the shell mounts, which is enough to measure its layout. Every call into Rust fails: no stack, no apps, no terminals, no project. Your app renders its failure path, which makes that path worth writing.

Asking a running HELVE what it does

pnpm probe                    # list the tools
pnpm probe shell_snapshot     # windows, clusters, pane trees, instances, terminals
pnpm probe recent_errors      # failures since launch, backend and webview
pnpm probe boot_status        # how far startup got

pnpm probe talks to the helve-debug MCP server the orchestrator hosts. It works from any terminal, and it needs no relaunch.

Two limits shape how you read a result:

• Every tool on that server reads. Nothing in helve-debug opens, closes or moves anything.
• Errors inside an app's iframe are not captured, only the shell's and the backend's. An empty recent_errors means nothing failed in those two places. Each answer repeats this in its covers field. Quote the qualifier.

Seeing and clicking the UI

A second MCP server, helve-ui, drives the window: screenshots, the DOM, and mouse and keyboard input. It stays hidden until a developer switches on developer.mode and then switches on the server as a second step. This is the one server that writes.

pnpm ui:build                                    # once
pnpm ui launch                                   # developer mode and the server on
pnpm probe --agent --server ui screenshot        # writes helve-shot.png
pnpm probe --agent --server ui snapshot          # clickable elements, with refs
pnpm probe --agent --server ui click '{"target":"e12"}'
pnpm ui close                                    # by pid

--agent points the probe at the instance pnpm ui launch started, instead of at a working window another developer is using. Keep the flag.

snapshot walks into app iframes, which makes e19 app button New Project Home's own content. Every snapshot renumbers the refs. Take a fresh one before each click.

Avoid anything that opens a native dialog. A folder picker blocks the webview, and every tool then times out after 20 seconds until a person dismisses it. On Home, that means New Project, Open Project and Clone Project.

What "done" means

STANDARDS.md §9 holds the full definition. The short form: a build that compiles is not a change that works.