From 1b8d261975a3e7c88815376da36fb5879cf53f5e Mon Sep 17 00:00:00 2001
From: ivndev001 <ivn.cbrdo@gmail.com>
Date: Thu, 17 Sep 2026 06:47:18 +0000
Subject: [PATCH] chore(infra): add bin/setup and bin/check so the fleet can
 install deps and gate changes

The fleet boxes ship bun but not this repo's deps, so a coding task has
never once passed its team_verify gate here: the runner sees bun (mise
already reports ok) but not this project's node_modules, and refuses to
guess an install command. The remedy the platform's own stage hands back
is the repo carrying its own bin/setup.

bin/setup: bun install, plus the dummy/web fixture build (CONTRIBUTING.md
and ci.yml both record that its dist/ must exist before bun test). Guard
the mise activation the way wurk's bin/setup does so a laptop without
mise skips it cleanly. Run from any cwd.

bin/check: typecheck + lint + test, in the order the platform's Bun
stack profile declares and CI runs them, with SKIP_BROWSER_INTEGRATION=1
the way CI does (BrowserAdapter integration flakes on the runner's
2-vCPU load). The && chain + set -e fail on the first red leg so the
captured tail names what broke.

CONTRIBUTING.md names both scripts as the one-command entry points.

Refs #81
---
 CONTRIBUTING.md | 16 +++++++++++++++-
 bin/check       | 23 +++++++++++++++++++++++
 bin/setup       | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 1 deletion(-)
 create mode 100755 bin/check
 create mode 100755 bin/setup

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d0ac0f6..3643316 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,9 +5,13 @@
 ```bash
 git clone <repo>
 cd ui-debugger-mcp
-bun install
+bin/setup
 ```
 
+The one-command entry point is `bin/setup` — installs root + dummy/web deps and
+builds the e2e fixture's `dist/`. `bin/check` is the matching CI gate (typecheck,
+lint, test). Both run from any cwd and are the same commands CI runs.
+
 Boot the server in watch mode (for manual testing with an MCP client):
 
 ```bash
@@ -16,6 +20,16 @@ bun run dev
 
 ## CI gate — all four must pass before commit
 
+`bin/check` runs typecheck + lint + test in one command. For the full four-step
+gate that matches CI exactly:
+
+```bash
+bin/check           # typecheck + lint + test (the script CI runs)
+bun run build       # esbuild / tsc emit
+```
+
+Or step-by-step:
+
 ```bash
 bun run lint        # Biome format + lint
 bun run typecheck   # tsc --noEmit
diff --git a/bin/check b/bin/check
new file mode 100755
index 0000000..d28674e
--- /dev/null
+++ b/bin/check
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# The CI gate as a single command: typecheck, lint, test — in the order the
+# platform's Bun stack profile declares, so the first red leg fails the script
+# with a tail that names what was wrong.
+#
+# Anything this runs, CI runs too — set `SKIP_BROWSER_INTEGRATION=1` the way CI
+# does (`.github/workflows/ci.yml`: the BrowserAdapter integration suite flakes
+# under the runner's 2-vCPU load, so CI skips it; the e2e suite covers the real
+# browser→findings path in CI). Run `bin/setup` first.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# `&&` not `;`: set -e + `&&` fails on the FIRST red leg, so the captured
+# tail names the stage that broke instead of a downstream error masking it.
+echo "==> typecheck"
+bun run typecheck
+
+echo "==> lint"
+bun run lint
+
+echo "==> test"
+SKIP_BROWSER_INTEGRATION=1 bun test
diff --git a/bin/setup b/bin/setup
new file mode 100755
index 0000000..aff9cd3
--- /dev/null
+++ b/bin/setup
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Install this repo's dependencies and build its dummy/web e2e fixture, so
+# `bin/check` can run end-to-end on a fresh checkout.
+#
+# Idempotent: every step is a no-op when its output is already there.
+# Cwd-independent: `cd` to the repo root before running anything, so the
+# script works no matter where it is invoked from.
+#
+# Stages:
+#   1. mise (if installed)  — pin bun + node from .mise.toml / .tool-versions
+#   2. bun install          — root deps, so `bunx tsc` resolves
+#   3. dummy/web fixture    — `bun install --frozen-lockfile && bun run build`
+#                             so the e2e suite's static server can find dist/
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# Guard mise activation the way wurk's bin/setup does: skip cleanly when mise
+# is absent (a laptop without mise still works), activate it when present so a
+# repo-pinned bun version wins over the system one.
+if command -v mise >/dev/null 2>&1; then
+  echo "==> mise install"
+  mise install
+  # `mise env -s bash` emits `export FOO=bar ...` for the current shell; eval
+  # it into THIS shell so the `bun` below is the mise-managed one, not PATH.
+  eval "$(mise env -s bash)"
+fi
+
+command -v bun >/dev/null || { echo "X_BUN_MISSING: install bun — https://bun.sh"; exit 1; }
+
+echo "==> bun install (root)"
+bun install
+
+# dummy/web is a standalone package with its own bun.lock, so the repo-root
+# install never reaches it. Both `bun test` (src/dummy-web.e2e.test.ts:141) and
+# CI (.github/workflows/ci.yml:42) build the fixture's dist/ up front; doing it
+# here too keeps `bin/check` honest when run from a fresh clone.
+echo "==> dummy/web fixture (install + build)"
+(
+  cd dummy/web
+  # --frozen-lockfile under CI only: locally a plain install is fine and lets
+  # `bun install` record any newly added dep. `${CI:+...}` is the form
+  # `set -u` exempts, so an unset CI expands to nothing.
+  bun install ${CI:+--frozen-lockfile}
+  bun run build
+)
+
+echo "==> ready. try: bin/check"