chore(ci): make the lefthook pre-push hook installable + documented

Add lefthook as a devDependency (^2.1.10) and a prepare: lefthook install
script (plus a pnpm onlyBuiltDependencies entry) so the hook installs on
pnpm install instead of being a no-op wrapper. Exclude .worktrees from oxfmt
and oxlint so nested worktrees don't false-fail the local run. On a failing
job the hook now prints the fix command (pnpm run format / pnpm run lint:fix).
Document the hook, install, and opt-in/opt-out in CONTRIBUTING.md.

Author: nicktrn

.oxfmtrc.json

@@ -21,6 +21,7 @@
     "**/storybook-static/",
     "**/.changeset/",
     "**/dist/",
+    "**/.worktrees/",
     "internal-packages/tsql/src/grammar/",
     "internal-packages/llm-model-catalog/src/defaultPrices.ts",
     "internal-packages/llm-model-catalog/src/modelCatalog.ts",

.oxlintrc.json

@@ -5,6 +5,7 @@
   "ignorePatterns": [
     "**/dist/**",
     "**/build/**",
+    "**/.worktrees/**",
     "**/*.d.ts",
     "**/seed.js",
     "**/seedCloud.ts",

CONTRIBUTING.md

@@ -214,6 +214,19 @@ pnpm exec trigger dev --log-level debug
 5. Commit the generated migration files as well as the changes to `schema.prisma`.
 6. If you're using VSCode you may need to restart the TypeScript server in the webapp to get updated type inference. Open a TypeScript file, then open the Command Palette (View > Command Palette) and run `TypeScript: Restart TS server`.
 
+## Git hooks (lefthook)
+
+We use [lefthook](https://lefthook.dev) for local git hooks, configured in `lefthook.yml` (the source of truth for what runs and when). Today that's a pre-push hook mirroring the CI `code-quality` checks; the set may grow, so check `lefthook.yml` rather than this guide.
+
+Hooks install automatically on `pnpm install`. A failing hook prints exactly what to run to fix it.
+
+**Opting out**
+
+- GitButler skips hooks on `but push` unless you enable **Run hooks** in the project settings (off by default).
+- Plain git: `LEFTHOOK=0 git push` / `--no-verify` to skip once; `pnpm exec lefthook uninstall` to remove.
+
+This never affects correctness — CI enforces the same checks on every PR; the hooks just give you faster feedback.
+
 ## Making a pull request
 
 **If you get errors, be sure to fix them before committing.**

lefthook.yml

@@ -13,6 +13,26 @@ pre-push:
   parallel: true
   jobs:
     - name: format
-      run: pnpm exec oxfmt --check .
+      run: |
+        pnpm exec oxfmt --check . || {
+          echo ""
+          echo "✖ Formatting issues found. Fix them with:"
+          echo ""
+          echo "    pnpm run format"
+          echo ""
+          echo "  then stage the changes and re-push."
+          echo ""
+          exit 1
+        }
     - name: lint
-      run: pnpm exec oxlint .
+      run: |
+        pnpm exec oxlint . || {
+          echo ""
+          echo "✖ Lint errors found. Auto-fix what's fixable with:"
+          echo ""
+          echo "    pnpm run lint:fix"
+          echo ""
+          echo "  then review, stage, and re-push (some rules need a manual fix)."
+          echo ""
+          exit 1
+        }

package.json

@@ -22,6 +22,7 @@
     "format:prisma": "pnpm --filter @trigger.dev/database run format:prisma && pnpm --filter @internal/run-ops-database run format:prisma",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
+    "prepare": "lefthook install",
     "knip:deps": "knip --production --dependencies",
     "docker": "node scripts/docker.mjs -f docker/docker-compose.yml up -d --build --remove-orphans",
     "docker:stop": "node scripts/docker.mjs -f docker/docker-compose.yml stop",
@@ -62,6 +63,7 @@
     "@vitest/coverage-v8": "4.1.7",
     "autoprefixer": "^10.4.12",
     "knip": "6.25.0",
+    "lefthook": "^2.1.10",
     "oxfmt": "^0.54.0",
     "oxlint": "^1.69.0",
     "pkg-pr-new": "0.0.75",
@@ -150,6 +152,7 @@
       "better-sqlite3",
       "cpu-features",
       "esbuild",
+      "lefthook",
       "prisma",
       "protobufjs",
       "sharp",