ci: add lint and format check job, update CONTRIBUTING.md

.github/workflows/ci.yml

@@ -49,6 +49,23 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
 
+  lint-and-format:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm format:check
+
   typecheck:
     name: Typecheck
     needs: changes

CONTRIBUTING.md

@@ -16,6 +16,8 @@ pnpm install        # Install all dependencies
 pnpm dev            # Run the studio (composition editor)
 pnpm build          # Build all packages
 pnpm -r typecheck   # Type-check all packages
+pnpm lint           # Lint all packages
+pnpm format:check   # Check formatting
 ```
 
 ### Running Tests
@@ -26,9 +28,20 @@ pnpm --filter @hyperframes/engine test        # Engine unit tests (vitest)
 pnpm --filter @hyperframes/core test:hyperframe-runtime-ci  # Runtime contract tests
 ```
 
+### Linting & Formatting
+
+```bash
+pnpm lint            # Run oxlint
+pnpm lint:fix        # Run oxlint with auto-fix
+pnpm format          # Format all files with oxfmt
+pnpm format:check    # Check formatting without writing
+```
+
+Git hooks (via [lefthook](https://github.com/evilmartians/lefthook)) run automatically after `pnpm install` and enforce linting + formatting on staged files before each commit.
+
 ## Pull Requests
 
-- Use [conventional commit](https://www.conventionalcommits.org/) format for PR titles (e.g., `feat: add timeline export`, `fix: resolve seek overflow`)
+- Use [conventional commit](https://www.conventionalcommits.org/) format for **all commits** (e.g., `feat: add timeline export`, `fix: resolve seek overflow`). Enforced by a git hook.
 - CI must pass before merge (build, typecheck, tests, semantic PR title)
 - PRs require at least 1 approval
 

lefthook.yml

@@ -3,12 +3,12 @@ pre-commit:
   commands:
     lint:
       glob: "*.{js,jsx,ts,tsx}"
-      run: oxlint {staged_files}
+      run: npx oxlint {staged_files}
     format:
       glob: "*.{js,jsx,ts,tsx,json,css,md,yaml,yml}"
-      run: oxfmt --check {staged_files}
+      run: npx oxfmt --check {staged_files}
 
 commit-msg:
   commands:
     commitlint:
-      run: commitlint --edit "{1}"
+      run: npx commitlint --edit "{1}"