feat(nix) :: add a development shell

Adds an optional dev shell with all of the tools needed to build SQLPage at the same versions the CI uses.

If you have nix installed or use NixOS you can now run ::
(1) `nix develop` :: assumes the dev shell
(2) `nix fmt` :: runs rustfmt, biome, and nixfmt
(3) `nix run .#test-rust`
(4) `nix run .#test-browser`
(5) `nix run .#test-examples`
(6) `nix flake check`

Author: 81reap

.envrc

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

.gitignore

@@ -15,3 +15,5 @@ sqlpage/sqlpage.db
 tests_uploads/
 /test-results/
 /playwright-report/
+/result
+.direnv/

flake.lock

@@ -0,0 +1,251 @@
+{
+  description = "Optional development environment for SQLPage";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    # Ships the official rustup binaries, so the toolchain in this shell is
+    # the same build CI and the release use, down to the bundled LLVM.
+    rust-overlay.url = "github:oxalica/rust-overlay";
+    rust-overlay.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      rust-overlay,
+    }:
+    let
+      inherit (nixpkgs) lib;
+
+      systems = [
+        "aarch64-darwin"
+        "aarch64-linux"
+        "x86_64-linux"
+      ];
+
+      # Oracle governs its own client library by licence, so nixpkgs marks it
+      # unfree. Naming it here keeps every other package in this flake free.
+      unfreePackages = [ "oracle-instantclient" ];
+
+      forEachSystem =
+        build:
+        lib.genAttrs systems (
+          system:
+          build (
+            import nixpkgs {
+              inherit system;
+              config.allowUnfreePredicate = package: builtins.elem (lib.getName package) unfreePackages;
+              overlays = [ rust-overlay.overlays.default ];
+            }
+          )
+        );
+
+      cargoEdition = (lib.importTOML ./Cargo.toml).package.edition;
+
+      lockedPlaywrightVersion =
+        (lib.importJSON ./package-lock.json).packages."node_modules/playwright-core".version;
+
+      formatterFor =
+        pkgs:
+        pkgs.treefmt.withConfig {
+          runtimeInputs = [
+            pkgs.biome
+            pkgs.nixfmt
+            pkgs.rustfmt
+          ];
+          settings = {
+            on-unmatched = "info";
+            formatter = {
+              nixfmt = {
+                command = "nixfmt";
+                includes = [ "*.nix" ];
+              };
+              rustfmt = {
+                command = "rustfmt";
+                options = [
+                  "--edition"
+                  cargoEdition
+                ];
+                includes = [ "*.rs" ];
+              };
+              biome = {
+                command = "biome";
+                options = [
+                  "format"
+                  "--write"
+                  "--no-errors-on-unmatched"
+                ];
+                includes = [
+                  "*.css"
+                  "*.js"
+                  "*.json"
+                  "*.jsonc"
+                  "*.mjs"
+                  "*.ts"
+                ];
+              };
+            };
+          };
+        };
+
+      rustToolchainFor = pkgs: pkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml;
+
+      # odbc-sys links against a driver manager, and the C sources vendored by
+      # aws-lc-sys, libsqlite3-sys and zstd-sys need a compiler. Nothing here
+      # reaches for OpenSSL: SQLPage speaks TLS through rustls.
+      cargoRuntime = pkgs: [
+        (rustToolchainFor pkgs)
+        pkgs.stdenv.cc
+        pkgs.unixodbc
+      ];
+      # The database matrix runs prebuilt test binaries that link the unixODBC
+      # driver manager statically. It still reads ODBCSYSINI at run time and
+      # dlopens whatever absolute path this file names, so pointing that one
+      # variable at the store replaces every driver install step.
+      odbcDriversFor =
+        pkgs:
+        pkgs.runCommand "sqlpage-odbc-drivers" { } ''
+          mkdir -p "$out"
+          oracleDriver=(${lib.getLib pkgs.oracle-instantclient}/lib/libsqora.so.*)
+          cat > "$out/odbcinst.ini" <<INI
+          [PostgreSQL Unicode]
+          Driver = ${pkgs.unixodbcDrivers.psql}/${pkgs.unixodbcDrivers.psql.driver}
+
+          [Oracle 21 ODBC driver]
+          Driver = ''${oracleDriver[0]}
+          INI
+        '';
+
+      cargoEnv = pkgs: {
+        LIBRARY_PATH = "${pkgs.unixodbc}/lib";
+      };
+
+      # Playwright is installed via npm, we we need to set the browser paths.
+      playwrightEnv = pkgs: {
+        PLAYWRIGHT_BROWSERS_PATH = "${pkgs.playwright-driver.browsers}";
+        PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = "1";
+        PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS = "true";
+      };
+
+      gatesFor =
+        pkgs:
+        lib.mapAttrs
+          (
+            name:
+            {
+              description,
+              packages ? [ ],
+              env ? { },
+              script,
+            }:
+            pkgs.writeShellApplication {
+              inherit name;
+              runtimeInputs = [ pkgs.git ] ++ packages;
+              runtimeEnv = env;
+              meta = { inherit description; };
+              text = ''
+                cd "$(git rev-parse --show-toplevel)"
+              ''
+              + script;
+            }
+          )
+          {
+            lint-rust = {
+              description = "Check Rust formatting and deny every clippy warning";
+              packages = cargoRuntime pkgs;
+              env = cargoEnv pkgs;
+              script = ''
+                cargo fmt --all -- --check
+                cargo clippy --all-targets --all-features -- -D warnings
+              '';
+            };
+
+            test-rust = {
+              description = "Run the Rust test suites against DATABASE_URL, or SQLite when it is unset";
+              packages = cargoRuntime pkgs;
+              env = cargoEnv pkgs;
+              script = ''
+                cargo test "$@"
+              '';
+            };
+
+            test-browser = {
+              description = "Drive the components in a browser with Playwright";
+              packages = [ pkgs.nodejs_26 ] ++ cargoRuntime pkgs;
+              env = cargoEnv pkgs // playwrightEnv pkgs;
+              script = ''
+                npm ci --ignore-scripts
+                npm run build
+                cd tests/end-to-end
+                npx playwright test "$@"
+              '';
+            };
+
+            test-examples = {
+              description = "Run the Hurl suite of an example against its own containers";
+              packages = [ pkgs.hurl ];
+              script = ''
+                scripts/test-examples-hurl.sh "$@"
+              '';
+            };
+          };
+    in
+    {
+      packages = forEachSystem (pkgs: {
+        odbc-drivers = odbcDriversFor pkgs;
+      });
+
+      formatter = forEachSystem formatterFor;
+
+      checks = forEachSystem (pkgs: {
+        formatting = (formatterFor pkgs).check self;
+      });
+
+      apps = forEachSystem (
+        pkgs:
+        lib.mapAttrs (_: gate: {
+          type = "app";
+          program = lib.getExe gate;
+          inherit (gate) meta;
+        }) (gatesFor pkgs)
+      );
+
+      devShells = forEachSystem (
+        pkgs:
+        assert lib.assertMsg (lockedPlaywrightVersion == pkgs.playwright-driver.version)
+          "package-lock.json pins Playwright ${lockedPlaywrightVersion}, but nixpkgs ships ${pkgs.playwright-driver.version}. Playwright only drives the browsers its own release shipped with, so run `nix flake update` or realign package-lock.json.";
+        {
+          default = pkgs.mkShell {
+            name = "sqlpage";
+
+            packages =
+              (with pkgs; [
+                biome
+                hurl
+                nodejs_26
+                pkg-config
+                sqlite
+              ])
+              ++ cargoRuntime pkgs
+              ++ [ (formatterFor pkgs) ]
+              ++ lib.attrValues (gatesFor pkgs);
+
+            buildInputs = with pkgs; [
+              unixodbc
+              zstd
+            ];
+
+            # DATABASE_URL and LISTEN_ON stay unset on purpose. SQLPage reads
+            # both from the environment, so exporting them here would override
+            # every example and test fixture that ships its own configuration.
+            env = {
+              RUST_SRC_PATH = "${rustToolchainFor pkgs}/lib/rustlib/src/rust/library";
+              ZSTD_SYS_USE_PKG_CONFIG = "1";
+            }
+            // playwrightEnv pkgs;
+          };
+        }
+      );
+    };
+}