chore: migrate to Nix-based development and CI workflows [ENG-11657] (#43)

* chore(nix): add flake

* chore(ci): migrate to Nix-based CI workflows

Migrate all CI workflows to use Nix for consistent, reproducible builds
following the pattern from stackone-ai-node repository.

Changes:
- Add .github/actions/setup-nix for reusable Nix setup
- Create unified ci.yml workflow (replaces test.yml and lint.yml)
- Add nix-flake.yml for flake validation
- Update docs.yml and release.yml to use Nix
- Enhance flake.nix shellHook to auto-install dependencies
- Remove separate test.yml and lint.yml workflows

Benefits:
- Consistent environment between local dev and CI
- Faster builds with Cachix caching
- Single unified CI workflow
- Automatic dependency installation via shellHook

* chore(nix): migrate to git-hooks.nix and treefmt

Replace pre-commit with Nix-native git-hooks.nix and treefmt for better
integration with the Nix development environment.

Changes:
- Add git-hooks.nix and treefmt-nix flake inputs
- Configure treefmt with ruff (check + format) and nixfmt
- Set up git-hooks with treefmt and mypy pre-commit hooks
- Remove .pre-commit-config.yaml
- Remove pre-commit from dev dependencies
- Update Makefile to remove pre-commit install step
- Format code with treefmt (ruff)

Benefits:
- Consistent formatting via `nix fmt`
- Automatic git hook installation in nix develop
- No Python-based pre-commit dependency
- Faster hook execution
- Better Nix ecosystem integration

* docs: add Nix installation and development setup to README

Add Nix as the recommended development setup with instructions for
entering the dev environment, formatting, and running checks.

Benefits of using Nix:
- Automatic dependency installation
- Git hooks auto-configured
- Consistent environment across platforms

* chore: add .pre-commit-config.yaml to .gitignore

This file is auto-generated by git-hooks.nix and should not be tracked.

* fix(nix): disable pre-commit check in flake check, keep mypy hook

Configure git-hooks to skip the check during 'nix flake check' because
mypy requires the Python environment which isn't available in the Nix
sandbox.

The mypy hook still works locally in 'nix develop' where the Python
environment is available. Mypy is also run in CI via ci.yml.

Changes:
- Set pre-commit.check.enable = false to skip flake check
- Keep mypy hook enabled for local development
- Treefmt check still runs in flake check

* chore: migrate from Makefile to justfile

Replace Makefile with justfile for better command runner experience.
Add just to Nix devShell for development environment.

* chore: enable prettier for markdown/json

* chore: format with treefmt

Apply consistent formatting across the repository using nix fmt:
- YAML files: standardise string quoting to double quotes
- Markdown files: add blank lines before lists for proper rendering
- Remove trailing whitespace in CLAUDE.md

Author: ryoppippi

.envrc

@@ -0,0 +1 @@
+use flake

.github/actions/setup-nix/action.yaml

@@ -0,0 +1,19 @@
+name: "Setup Nix"
+description: "Install Nix and configure Cachix"
+runs:
+  using: "composite"
+  steps:
+    - name: Install Nix
+      uses: cachix/install-nix-action@0b0e072294b088b73964f1d72dfdac0951439dbd # v31.8.4
+      with:
+        github_access_token: ${{ github.token }}
+
+    - name: Setup Cachix (numtide)
+      uses: cachix/cachix-action@0fc020193b5a1fa3ac4575aa3a7d3aa6a35435ad # v16
+      with:
+        name: numtide
+        authToken: ""
+
+    - name: Load Nix development environment
+      shell: bash
+      run: nix develop --command true

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.13"]
+        include:
+          - python-version: "3.9"
+            sync-extras: "--all-extras --no-extra mcp"
+          - python-version: "3.10"
+            sync-extras: "--all-extras"
+          - python-version: "3.13"
+            sync-extras: "--all-extras"
+    env:
+      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
+
+      - name: Install dependencies
+        run: nix develop --command uv sync ${{ matrix.sync-extras }}
+
+      - name: Run Lint
+        run: nix develop --command uv run ruff check .
+
+      - name: Run Mypy
+        run: |
+          if [[ "${{ matrix.python-version }}" == "3.9" ]]; then
+            nix develop --command uv run mypy stackone_ai --exclude stackone_ai/server.py
+          else
+            nix develop --command uv run mypy stackone_ai
+          fi
+
+      - name: Run Tests
+        run: nix develop --command uv run pytest

.github/workflows/docs.yml

@@ -12,21 +12,19 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6.6.1
-        with:
-          python-version: "3.11"
-          enable-cache: true
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
 
       - name: Install all dependencies
-        run: uv sync --all-extras
+        run: nix develop --command uv sync --all-extras
 
       - name: Build documentation
         run: |
-          uv run scripts/build_docs.py
-          uv run mkdocs build
+          nix develop --command uv run scripts/build_docs.py
+          nix develop --command uv run mkdocs build
 
       - name: Deploy to GitHub Pages
         if: github.ref == 'refs/heads/main'

.github/workflows/lint.yml

@@ -0,0 +1,33 @@
+name: "CI: Flake check"
+
+on:
+  push:
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - ".github/workflows/nix-flake.yml"
+      - ".github/actions/setup-nix/**"
+  pull_request:
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - ".github/workflows/nix-flake.yml"
+      - ".github/actions/setup-nix/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Check flake syntax and structure
+  flake-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
+
+      - name: Check flake
+        run: nix flake check --all-systems --show-trace

.github/workflows/nix-flake.yml

@@ -20,25 +20,22 @@ jobs:
           manifest-file: .release-please-manifest.json
 
       # Only release to PyPI when a new release is created
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         if: ${{ steps.release.outputs.release_created }}
 
-      - name: Install uv
+      - name: Setup Nix
         if: ${{ steps.release.outputs.release_created }}
-        uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6.6.1
-        with:
-          python-version: "3.11"
-          enable-cache: true
+        uses: ./.github/actions/setup-nix
 
       - name: Update version in __init__.py
         if: ${{ steps.release.outputs.release_created }}
-        run: |
-          uv run scripts/update_version.py
+        run: nix develop --command uv run scripts/update_version.py
 
       - name: Build and publish package
         if: ${{ steps.release.outputs.release_created }}
         env:
           UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
         run: |
-          uv build
-          uv publish
+          nix develop --command uv build
+          nix develop --command uv publish

.github/workflows/release.yml

@@ -15,3 +15,6 @@ site/
 *.egg-info
 dist/
 build/
+
+# Git hooks (managed by Nix)
+.pre-commit-config.yaml