Add Vitest test suite with CI and testability refactors

.env.example

@@ -1,2 +1,6 @@
 GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
 GOOGLE_CLIENT_SECRET=your-client-secret
+
+# Test / CI (optional)
+# COMMIT_TOOLS_HOME=/tmp/commit-tools-test
+# NO_UPDATE_NOTIFIER=true

.github/workflows/pr-validate.yml

@@ -4,12 +4,21 @@ on:
   pull_request:
     types: [opened, synchronize, reopened]
 
+concurrency:
+  group: pr-validate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   checks:
-    name: Typecheck, format, and build
+    name: Validate (typecheck, format, build, test)
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      GOOGLE_CLIENT_ID: test-client-id
+      GOOGLE_CLIENT_SECRET: test-client-secret
+      NO_UPDATE_NOTIFIER: "true"
+      CI: "true"
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -32,11 +41,11 @@ jobs:
         run: pnpm exec prettier . --check
 
       - name: Build project
-        env:
-          GOOGLE_CLIENT_ID: pr-validation-not-a-real-client-id
-          GOOGLE_CLIENT_SECRET: pr-validation-not-a-real-secret
         run: pnpm run build
 
+      - name: Test
+        run: pnpm test
+
   lint:
     name: Cognitive complexity
     runs-on: ubuntu-latest

README.md

@@ -192,3 +192,26 @@ Contributions and feedback are welcome!
 ## Contributing
 
 We welcome contributions! Feel free to report bugs, suggest features, or submit pull requests.
+
+### Pull request checks
+
+Every pull request runs the **PR Validate** workflow (`.github/workflows/pr-validate.yml`):
+
+- **Validate (typecheck, format, build, test)** — typecheck, Prettier, production build, then the full Vitest suite (unit, integration, and CLI smoke tests against `dist/`)
+- **Cognitive complexity** — ESLint SonarJS rules
+- **Publish preview** — semver / npm publish preview (informational)
+
+Run locally before opening a PR:
+
+```bash
+pnpm typecheck
+pnpm exec prettier . --check
+pnpm build   # requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in the environment
+pnpm test
+pnpm lint
+```
+
+To block merges when checks fail, enable branch protection on `main` and require these status checks:
+
+- `Validate (typecheck, format, build, test)`
+- `Cognitive complexity`

package.json

@@ -15,7 +15,9 @@
     "format": "npx prettier . --write",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "lint:ci": "eslint ."
+    "lint:ci": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "repository": {
     "type": "git",
@@ -33,14 +35,16 @@
     "@types/luxon": "^3.7.1",
     "@types/node": "^22",
     "@types/react": "^19.2.14",
+    "@vitest/coverage-v8": "^4.1.6",
     "eslint": "^9.39.4",
     "eslint-plugin-sonarjs": "^4.0.3",
     "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "react-devtools-core": "^7.0.1",
     "tsup": "^8",
     "tsx": "^4",
-    "typescript-eslint": "^8.59.0"
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
     "typescript": "^5"