Agent harness: AGENTS.md, bin/check, and a type, lint and format gate by bencap · Pull Request #746 · VariantEffect/mavedb-ui

bencap · 2026-10-16T21:37:27Z

Sets the repo up so coding agents (and new contributors) get the facts they can't derive from the code, plus a type, lint and format gate fast enough to run after every edit. The ui counterpart of VariantEffect/mavedb-api#926.

Changes

bin/check runs vue-tsc, ESLint and the Prettier check in about 12 s and reports every failure in one pass. bin/t wraps vitest; the whole suite takes a few seconds.
CI gains a check job that runs bin/check and then vite build. Until now CI ran only the unit tests, so nothing checked types, lint or formatting.
One formatting commit (9adb05d5c) brings the tree in line with the existing .prettierrc.json. It's listed in .git-blame-ignore-revs. .prettierignore now skips the committed mavehgvs and MaveTools Sphinx output in public/docs/.
Type errors:
- All of them outside the heatmap are fixed. The chart libraries' accessor type is now a get/set overload, so chained setters type-check, and that exposed and fixed three real argument mismatches in the histogram.
- The heatmap's 60 errors are marked with @ts-expect-error TODO(#745) on 58 lines; Fix the heatmap's type errors and remove their @ts-expect-error markers #745 tracks fixing them.
ESLint: 12 findings fixed by --fix; the other 117 (89 are no-explicit-any) are recorded in eslint-suppressions.json, so only new violations fail.
AGENTS.md (CLAUDE.md imports it) and .claude/rules/ (components, styling, data, routing) replace the Copilot files in .github/instructions/. Claude Code never loaded those, and two of their claims were wrong: there is a test suite, and the second beforeEach in main.js redirects variant URNs, not legacy hash URLs.
.claude/settings.json holds shared permission rules for Claude Code sessions. It blocks --no-verify and reading ~/.aws, ~/.ssh or ~/.pgpass; sets AWS_PROFILE to the read-only agent role (VariantEffect/mavedb-deployment#54); and asks only before hard-to-undo actions: force pushes, pushes to main, mavedb-main, mavedb-dev or release-*, AWS with an explicit profile, eb, the prod-API dev server, adding a dependency, and edits to settings.json itself. Identical copies live in each repo and the workspace, because Claude Code reads settings only from the folder a session starts in. They catch honest mistakes; they aren't a security boundary.
npm run dev:agent serves the app over plain HTTP on 127.0.0.1:8090 (or PORT) without the docs build, for agents and embedded browser panes that reject the self-signed certificate. ORCID sign-in doesn't work there.

Review notes

Two-statement click handlers in ExperimentEditor and the three dashboard tabs are now comma expressions, in a commit before the formatting commit. Prettier (semi: false) strips the ; that tells Vue to compile a handler as a function body, and the result passes vue-tsc, ESLint and Prettier but fails vite build. That's why CI now builds the app.
import 'vue-router' in composition/auth.ts looks unused but isn't: without it, vue-tsc drops $toast and the other global component properties from about 100 components.
Removed scoreSetHasCalibrationWithEvidenceStrengths. It had no callers and read functionalRanges, which the api renamed.
Dependency changes: adds @types/jquery (dev only) for the histogram's one jquery call. The lockfile also gains the non-macOS builds of lightningcss and @tailwindcss/oxide at the versions already locked; it listed only darwin-arm64, so npm ci on Linux couldn't build the app. The new CI build step is the first thing to build on Linux.
Merge with a merge commit, not a squash, so the formatting commit's hash in .git-blame-ignore-revs stays valid.
Cross-repo rules live in the workspace-level AGENTS.md in VariantEffect/mavedb-workspace, which is private for now.
Once per clone: git config blame.ignoreRevsFile .git-blame-ignore-revs.

Testing

bin/check passes.
533 unit tests pass (bin/t).
vite build --mode=live succeeds.
Not yet checked by hand in a browser. The handler rewrites and the histogram's null-score handling are the changes with runtime effect.

Claude Code doesn't load .github/instructions, and parts had drifted from the code (it still says there's no test suite). AGENTS.md and .claude/rules replace them later on this branch.

Vue compiles a handler as a function body only when it contains a semicolon, and Prettier (semi: false) removes it, which breaks the build. A comma expression survives formatting.

Mechanical: prettier --write . with the existing .prettierrc.json. No behavior change; the unit tests and the production build pass.

- Chart accessors are now typed as get/set overloads, so chained setters type-check and the line chart and histogram chains no longer error. - Add @types/jquery for the histogram's one jquery call. - Keep auth.ts's vue-router import as a side-effect import; removing it drops the global component properties from about 100 components. - Remove scoreSetHasCalibrationWithEvidenceStrengths, which had no callers and read the renamed functionalRanges field. - Smaller fixes: null props passed as undefined so their defaults apply, the calibration suggestions prop takes external publications, a missing histogram score is NaN, SimpleDnaVariation no longer redeclares an inherited field with a wider type, and a typed mock parameter in a test.

58 lines in lib/heatmap.ts and ScoreSetHeatmap.vue, mostly d3 selection generics and possibly-null SVG handles. Each marker fails the type check once its line is fixed, so they come out one at a time.

Attribute order and prefer-const, from eslint src --fix.

eslint --suppress-all wrote eslint-suppressions.json with the 117 findings left after the autofixes (89 are no-explicit-any). New violations fail; after fixing old ones, run npx eslint src --prune-suppressions to shrink the file.

bin/check runs vue-tsc, ESLint and the Prettier check in about 12 s and reports every failure in one pass. bin/t wraps vitest. CI gains a check job; until now it ran only the unit tests.

AGENTS.md (CLAUDE.md imports it) holds setup, commands and the rules that apply in every session. .claude/rules/ holds components, styling, data and routing guidance, loaded only for matching paths. Both replace the removed Copilot files, cut to what the code doesn't show, with two corrections: there is a test suite, and the second beforeEach in main.js redirects variant URNs, not legacy hash URLs. The README gains a checks section.

Prettier (semi: false) can turn a two-statement inline handler into a template that vue-tsc, ESLint and Prettier accept and only the Vue build rejects, as with the handlers fixed earlier on this branch.

coveralls · 2026-10-16T21:40:12Z

coverage: 23.781% (+0.05%) from 23.731% — feature/bencap/agent-harness into release-2026.4.0

Deny --no-verify and reads of ~/.aws and ~/.pgpass. Ask before pushes, AWS and Elastic Beanstalk commands, the prod-API dev server and dependency changes. The same file lives in the workspace and in each repo, because Claude Code reads settings only from the folder a session starts in. These are guardrails, not a security boundary: a rewritten command can get past them.

Serves on 127.0.0.1:8090 (or PORT) without the self-signed certificate, which embedded browser panes reject, and skips the MkDocs build so it starts without Python. ORCID sign-in does not work on that port.

Sessions get AWS_PROFILE=mavedb-agent-readonly, so aws commands use the read-only role (see deployment/environments/aws/agent-access.md) and fail rather than fall back to full credentials where the profile is missing. Choosing another profile asks first, replacing the blanket prompt on aws. Reading ~/.ssh is now blocked, alongside ~/.aws and ~/.pgpass.

Edits to AGENTS.md, CLAUDE.md and anything under .claude/ now ask first. Those files shape every later session, and settings.json holds the guardrails. The rules cover Edit and Write; a shell redirect into one of these files is not caught.

Prompts now cover force pushes, pushes to main, mavedb-main, mavedb-dev or release-*, AWS with an explicit profile, eb, adding a dependency and edits to settings.json itself. Ordinary feature-branch pushes, dependency updates and edits to AGENTS.md, CLAUDE.md and .claude/rules no longer ask; the never rule in the workspace AGENTS.md still covers those edits, and PR review sees the diffs.

The ui checks it with Prettier, so every copy uses that layout.

The lockfile listed only the darwin-arm64 builds of lightningcss and @tailwindcss/oxide, a known npm bug when a lock is updated over an existing node_modules. npm ci on Linux then installs neither, and vite build fails with "Cannot find module ../lightningcss.linux-x64-gnu.node". Re-resolving those two packages adds the missing platform entries at the same versions (1.30.2 and 4.1.16); nothing else in the lockfile changes.

bencap added 13 commits October 16, 2026 13:49

chore: remove the Copilot instruction files

2adfb9f

Claude Code doesn't load .github/instructions, and parts had drifted from the code (it still says there's no test suite). AGENTS.md and .claude/rules replace them later on this branch.

build(prettier): skip the committed mavehgvs and MaveTools docs

a93c8e3

fix: write two-statement click handlers as one expression

60b2cc0

Vue compiles a handler as a function body only when it contains a semicolon, and Prettier (semi: false) removes it, which breaks the build. A comma expression survives formatting.

style: format the tree with Prettier 3.6.2

9adb05d

Mechanical: prettier --write . with the existing .prettierrc.json. No behavior change; the unit tests and the production build pass.

chore: skip the Prettier formatting commit in git blame

f3576a9

chore(types): mark the heatmap's type errors with @ts-expect-error

e6c3310

58 lines in lib/heatmap.ts and ScoreSetHeatmap.vue, mostly d3 selection generics and possibly-null SVG handles. Each marker fails the type check once its line is fixed, so they come out one at a time.

style: apply ESLint's automatic fixes

ed21884

Attribute order and prefer-const, from eslint src --fix.

build(eslint): record existing findings as suppressions

c36342f

eslint --suppress-all wrote eslint-suppressions.json with the 117 findings left after the autofixes (89 are no-explicit-any). New violations fail; after fixing old ones, run npx eslint src --prune-suppressions to shrink the file.

build: add bin/check and bin/t, and run bin/check in CI

7d7885a

bin/check runs vue-tsc, ESLint and the Prettier check in about 12 s and reports every failure in one pass. bin/t wraps vitest. CI gains a check job; until now it ran only the unit tests.

build(ci): build the app in the check job

9e78202

Prettier (semi: false) can turn a two-statement inline handler into a template that vue-tsc, ESLint and Prettier accept and only the Vue build rejects, as with the handlers fixed earlier on this branch.

docs: note the app build and the comma-expression handler rule

d5e6c9c

bencap mentioned this pull request Oct 16, 2026

Agent harness: AGENTS.md, bin/check and bin/t VariantEffect/dcd_mapping2#113

Merged

bencap added 6 commits October 16, 2026 15:11

build: add npm run dev:agent, a plain-HTTP dev server

38740c6

Serves on 127.0.0.1:8090 (or PORT) without the self-signed certificate, which embedded browser panes reject, and skips the MkDocs build so it starts without Python. ORCID sign-in does not work on that port.

style(claude): format settings.json with Prettier

98d4e01

The ui checks it with Prettier, so every copy uses that layout.

bencap marked this pull request as ready for review October 16, 2026 23:33

bencap changed the base branch from release-2026.4.0 to release-2026.3.1 October 19, 2026 17:11

bencap merged commit 056d466 into release-2026.3.1 Oct 19, 2026
2 checks passed

bencap deleted the feature/bencap/agent-harness branch October 19, 2026 17:41

Navigation Menu

Repository navigation

Agent harness: AGENTS.md, bin/check, and a type, lint and format gate - #746

Agent harness: AGENTS.md, bin/check, and a type, lint and format gate#746
bencap merged 20 commits into
release-2026.3.1from
feature/bencap/agent-harness

bencap commented Oct 16, 2026 •

edited

Loading

Uh oh!

coveralls commented Oct 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bencap commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Review notes

Testing

Uh oh!

coveralls commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bencap commented Oct 16, 2026 •

edited

Loading

coveralls commented Oct 16, 2026 •

edited

Loading