Migrate the development shell to a locked Nix flake

.envrc

@@ -1,9 +1,19 @@
-# Preserve the caller's TMPDIR state because some nix shells replace it with
-# a temp directory path that no longer exists after activation.
+use_flake_subdir() {
+  # Keep direnv's cache in sync with every tracked Nix input.
+  for file in $(git ls-files nix); do
+    watch_file "$file"
+  done
+  mkdir -p "$(direnv_layout_dir)"
+  eval "$(nix --extra-experimental-features "nix-command flakes" print-dev-env \
+    --profile "$(direnv_layout_dir)/flake-profile" "path:nix" "$@")"
+}
+
+# Preserve the caller's TMPDIR state because Nix development shells may replace
+# it with a temporary directory path that no longer exists after activation.
 old_tmpdir="${TMPDIR-}"
 old_tmpdir_was_set="${TMPDIR+x}"
 
-use nix
+use flake_subdir
 
 if [ -n "${old_tmpdir_was_set}" ]; then
   export TMPDIR="$old_tmpdir"

.github/workflows/mintlify-validate.yml

@@ -13,6 +13,9 @@ concurrency:
   group: mintlify-validate-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  NIX_CONFIG: "extra-experimental-features = nix-command flakes"
+
 jobs:
   mintlify-validate:
     name: mintlify validate
@@ -25,23 +28,23 @@ jobs:
         uses: cachix/install-nix-action@v31
 
       - name: Validate external snippet wrapper
-        run: nix-shell --run 'npm run test:external-snippets'
+        run: nix develop path:nix --command npm run test:external-snippets
 
       - name: Validate generated-reference history output
         run: >-
-          nix-shell --run 'python3 -m pytest
+          nix develop path:nix --command python3 -m pytest
           tests/test_history_contract.py
           tests/test_reference_page_history.py
           tests/test_openapi_manual_render.py
-          tests/test_json_api_openapi.py'
+          tests/test_json_api_openapi.py
 
       - name: Check JSON Ledger OpenAPI generated output
-        run: >-
-          nix-shell --run 'python3 scripts/generate_json_api_reference.py &&
-          git diff --exit-code --
-          docs-main/docs.json
-          docs-main/openapi/json-ledger-api/openapi.yaml
-          docs-main/reference/json-api-reference'
+        run: |
+          nix develop path:nix --command python3 scripts/generate_json_api_reference.py
+          git diff --exit-code -- \
+          docs-main/docs.json \
+          docs-main/openapi/json-ledger-api/openapi.yaml \
+          docs-main/reference/json-api-reference
 
       - name: Run Mintlify validation
-        run: nix-shell --run 'cd docs-main && npx mint validate'
+        run: nix develop path:nix --command bash -c 'cd docs-main && npx mint validate'

.github/workflows/update-version-dashboard.yml

@@ -24,6 +24,9 @@ concurrency:
   group: update-generated-docs
   cancel-in-progress: false
 
+env:
+  NIX_CONFIG: "extra-experimental-features = nix-command flakes"
+
 # The canton-network-cf-docs runner contract provides Nix through a shared store and daemon.
 jobs:
   select-targets:
@@ -41,7 +44,7 @@ jobs:
         env:
           GENERATED_DOCS_TARGETS: ${{ inputs.targets || 'all' }}
         run: |
-          target_matrix="$(SKIP_NPM_INSTALL=1 nix-shell --run 'python3 scripts/update_generated_reference_prs.py --targets $GENERATED_DOCS_TARGETS --print-target-matrix-json')"
+          target_matrix="$(SKIP_NPM_INSTALL=1 nix develop path:nix --command bash -c 'python3 scripts/update_generated_reference_prs.py --targets $GENERATED_DOCS_TARGETS --print-target-matrix-json')"
           echo "target_matrix=$target_matrix" >> "$GITHUB_OUTPUT"
 
   update-generated-docs:
@@ -63,19 +66,19 @@ jobs:
         run: SKIP_NPM_INSTALL=1 direnv allow . && SKIP_NPM_INSTALL=1 direnv exec . true
 
       - name: Install npm dependencies
-        run: SKIP_NPM_INSTALL=1 nix-shell --run 'npm ci'
+        run: SKIP_NPM_INSTALL=1 nix develop path:nix --command npm ci
 
       - name: Set up Daml tooling
         if: ${{ matrix.requires_daml_tooling }}
         run: |
-          SKIP_NPM_INSTALL=1 nix-shell --run 'bash scripts/install_daml_tooling.sh'
+          SKIP_NPM_INSTALL=1 nix develop path:nix --command bash scripts/install_daml_tooling.sh
           echo "$HOME/.dpm/bin" >> "$GITHUB_PATH"
           echo "$HOME/.daml/bin" >> "$GITHUB_PATH"
 
       - name: Verify generated-doc dependencies
         env:
           GENERATED_DOCS_DEPENDENCY_ARGS: ${{ matrix.requires_daml_tooling && '--require-daml' || '' }}
-        run: SKIP_NPM_INSTALL=1 nix-shell --run "python3 scripts/check_generated_docs_dependencies.py $GENERATED_DOCS_DEPENDENCY_ARGS"
+        run: SKIP_NPM_INSTALL=1 nix develop path:nix --command bash -c "python3 scripts/check_generated_docs_dependencies.py $GENERATED_DOCS_DEPENDENCY_ARGS"
 
       - name: Check generated-docs merger app configuration
         id: merger-app
@@ -100,7 +103,7 @@ jobs:
       - name: Configure generated-docs PR authentication
         env:
           GH_TOKEN: ${{ steps.merger-token.outputs.token || github.token }}
-        run: SKIP_NPM_INSTALL=1 nix-shell --run 'gh auth setup-git'
+        run: SKIP_NPM_INSTALL=1 nix develop path:nix --command gh auth setup-git
 
       - name: Generate update pull requests
         env:
@@ -113,5 +116,4 @@ jobs:
           if [[ "${{ inputs.dry_run || false }}" == "true" ]]; then
             args+=(--dry-run)
           fi
-          printf -v generated_docs_command '%q ' "${args[@]}"
-          SKIP_NPM_INSTALL=1 nix-shell --run "$generated_docs_command"
+          SKIP_NPM_INSTALL=1 nix develop path:nix --command "${args[@]}"

CONTRIBUTING.md

@@ -58,7 +58,7 @@ For new pages, restructuring, or anything touching multiple files, set up a loca
 Either:
 
 - [`direnv`](https://direnv.net/)
-- [`nix`](https://nixos.org/download/)
+- [`nix`](https://nixos.org/download/) with `nix-command` and flakes support
 
 OR:
 

README.md

@@ -42,7 +42,7 @@ Use this to report a problem or request new content without editing the source y
 Either:
 
 - [`direnv`](https://direnv.net/)
-- [`nix`](https://nixos.org/download/)
+- [`nix`](https://nixos.org/download/) with `nix-command` and flakes support
 
 OR:
 

nix/flake.nix

@@ -0,0 +1,18 @@
+{
+  description = "cf-docs development environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem
+      (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+        in
+        {
+          devShells.default = import ./shell.nix { inherit pkgs; };
+        });
+}

shell.nix → nix/shell.nix

@@ -1,14 +1,6 @@
-let
-  # To get the sha256:
-  # nix-prefetch-url --unpack https://github.com/NixOS/nixpkgs/archive/<the rev>.tar.gz
-  rev = "ec942ba042dad5ef097e2ef3a3effc034241f011";
-  sha256 = "sha256:01i5lznyfxyb5r7llscybv17nhbnb58p0wi62rag9jdagjwxm6a7";
-
-  pkgs = (import (builtins.fetchTarball {
-    url = "https://github.com/NixOS/nixpkgs/archive/${rev}.tar.gz";
-    inherit sha256;
-  }) {});
+{ pkgs }:
 
+let
   pythonBase = pkgs.python314;
   python = pythonBase.withPackages (ps: [
     ps.grpcio-tools
@@ -23,6 +15,7 @@ let
 in
 pkgs.mkShell {
   packages = [
+    pkgs.bash
     pkgs.curl
     pkgs.gh
     pkgs.git