chore(release): v1.0.7

.gitignore

@@ -1,3 +1,4 @@
 .pre-commit-config.yaml
 .direnv
 result
+template/flake.lock

README.md

@@ -0,0 +1,74 @@
+# repo-lib
+
+Simple Nix flake library for:
+
+- a shared development shell (`mkDevShell`)
+- an optional release command (`mkRelease`)
+- a starter template (`template/`)
+
+## Prerequisites
+
+- [Nix](https://nixos.org/download/) with flakes enabled
+- [`direnv`](https://direnv.net/) (recommended)
+
+## Use the template (new repo)
+
+From your new project folder:
+
+```bash
+nix flake new myapp -t 'git+https://git.dgren.dev/eric/nix-flake-lib?ref=v1.0.7#default' --refresh
+```
+
+## Use the library (existing repo)
+
+Add this flake input:
+
+```nix
+inputs.devshell-lib.url = "git+https://git.dgren.dev/eric/nix-flake-lib?ref=v1.0.7";
+inputs.devshell-lib.inputs.nixpkgs.follows = "nixpkgs";
+```
+
+Create your shell from `mkDevShell`:
+
+```nix
+env = devshell-lib.lib.mkDevShell {
+  inherit system;
+  extraPackages = [ ];
+  tools = [ ];
+  additionalHooks = { };
+};
+```
+
+Expose it in `devShells` as `default` and run:
+
+```bash
+nix develop
+```
+
+## Common commands
+
+```bash
+nix fmt           # format files
+```
+
+## Optional: release command
+
+If your flake defines:
+
+```nix
+packages.${system}.release = devshell-lib.lib.mkRelease { inherit system; };
+```
+
+Run releases with:
+
+```bash
+release
+release patch
+release beta
+release minor beta
+release stable
+release set 1.2.3
+```
+
+The release script uses `./VERSION` as the source of truth and creates tags like `v1.2.3`.
+When switching from stable to a prerelease channel without an explicit bump (for example, `release beta`), it applies a patch bump automatically (for example, `1.0.0` -> `1.0.1-beta.1`).

VERSION

@@ -1,3 +1,3 @@
-0.0.2
+1.0.7
 stable
 0

flake.nix

@@ -82,7 +82,7 @@
               hooks = {
                 treefmt = {
                   enable = true;
-                  entry = "${treefmtEval.config.build.wrapper}/bin/treefmt";
+                  entry = "${treefmtEval.config.build.wrapper}/bin/treefmt --ci";
                   pass_filenames = true;
                 };
                 gitlint.enable = true;
@@ -95,6 +95,11 @@
               // additionalHooks;
             };
 
+            toolNameWidth = builtins.foldl' (
+              maxWidth: t: pkgs.lib.max maxWidth (builtins.stringLength t.name)
+            ) 0 tools;
+            toolLabelWidth = toolNameWidth + 1;
+
             toolBannerScript = pkgs.lib.concatMapStrings (
               t:
               let
@@ -102,7 +107,8 @@
               in
               ''
                 if command -v ${t.bin} >/dev/null 2>&1; then
-                  printf "  $CYAN ${t.name}:$RESET\t${colorVar}%s$RESET\n" "$(${t.bin} ${t.versionCmd})"
+                  version="$(${t.bin} ${t.versionCmd} 2>/dev/null | head -n 1 | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
+                  printf "  $CYAN %-${toString toolLabelWidth}s$RESET ${colorVar}%s$RESET\n" "${t.name}:" "$version"
                 fi
               ''
             ) tools;
@@ -122,14 +128,19 @@
                 ${pre-commit-check.shellHook}
 
                 if [ -t 1 ]; then
-                  :
-                  # command -v tput >/dev/null 2>&1 && tput clear || printf '\033c'
+                  command -v tput >/dev/null 2>&1 && tput clear || printf '\033c'
                 fi
 
                 GREEN='\033[1;32m'
                 CYAN='\033[1;36m'
                 YELLOW='\033[1;33m'
                 BLUE='\033[1;34m'
+                RED='\033[1;31m'
+                MAGENTA='\033[1;35m'
+                WHITE='\033[1;37m'
+                GRAY='\033[0;90m'
+                BOLD='\033[1m'
+                UNDERLINE='\033[4m'
                 RESET='\033[0m'
 
                 printf "\n$GREEN 🚀 Dev shell ready$RESET\n\n"
@@ -151,27 +162,33 @@
             #   line 2: CHANNEL (stable|alpha|beta|rc|internal|...)
             #   line 3: N (prerelease number, 0 for stable)
             postVersion ? "",
-            # Shell string — runs after VERSION + versionFiles are written, before git add.
+            # Shell string — runs after VERSION + release steps are written/run, before git add.
             # Same env vars available.
-            versionFiles ? [ ],
-            # List of { path, template } attrsets.
-            # template is a Nix function: version -> string
-            # The content is fully rendered by Nix at eval time — no shell interpolation needed.
+            release ? [ ],
+            # Unified list processed in declaration order:
+            #   { file = "path/to/file"; content = ''...$FULL_VERSION...''; }  # write file
+            #   { run = ''...shell snippet...''; }                               # run script
             # Example:
-            #   versionFiles = [
+            #   release = [
             #     {
-            #       path = "src/version.ts";
-            #       template = version: ''export const APP_VERSION = "${version}" as const;'';
+            #       file = "src/version.ts";
+            #       content = ''export const APP_VERSION = "$FULL_VERSION" as const;'';
             #     }
             #     {
-            #       path = "internal/version/version.go";
-            #       template = version: ''
+            #       file = "internal/version/version.go";
+            #       content = ''
             #         package version
             #
-            #         const Version = "${version}"
+            #         const Version = "$FULL_VERSION"
+            #       '';
+            #     }
+            #     {
+            #       run = ''
+            #         sed -E -i "s#^([[:space:]]*my-lib\\.url = \")github:org/my-lib[^"]*(\";)#\\1github:org/my-lib?ref=$FULL_TAG\\2#" "$ROOT_DIR/flake.nix"
             #       '';
             #     }
             #   ];
+            # Runtime env includes: BASE_VERSION, CHANNEL, PRERELEASE_NUM, FULL_VERSION, FULL_TAG.
             channels ? [
               "alpha"
               "beta"
@@ -186,35 +203,34 @@
             pkgs = import nixpkgs { inherit system; };
             channelList = pkgs.lib.concatStringsSep " " channels;
 
-            # Version files are fully rendered by Nix at eval time.
-            # The shell only writes the pre-computed strings — no shell interpolation in templates.
-            versionFilesScript = pkgs.lib.concatMapStrings (
-              f:
-              let
-                # We can't call f.template here since FULL_VERSION is a runtime value.
-                # Instead we pass the path and use a shell heredoc with the template
-                # rendered at runtime via the VERSION env vars.
-                renderedContent = f.template "$FULL_VERSION";
-              in
+            releaseStepsScript = pkgs.lib.concatMapStrings (
+              entry:
+              if entry ? file then
                 ''
-                mkdir -p "$(dirname "${f.path}")"
-                cat > "${f.path}" << 'NIXEOF'
-                ${renderedContent}
+                  mkdir -p "$(dirname "${entry.file}")"
+                  cat > "${entry.file}" << NIXEOF
+                  ${entry.content}
                   NIXEOF
-                log "Generated version file: ${f.path}"
+                  log "Generated version file: ${entry.file}"
                 ''
-            ) versionFiles;
+              else if entry ? run then
+                ''
+                  ${entry.run}
+                ''
+              else
+                builtins.throw "release entry must have either 'file' or 'run'"
+            ) release;
 
             script =
               builtins.replaceStrings
                 [
                   "__CHANNEL_LIST__"
-                  "__VERSION_FILES__"
+                  "__RELEASE_STEPS__"
                   "__POST_VERSION__"
                 ]
                 [
                   channelList
-                  versionFilesScript
+                  releaseStepsScript
                   postVersion
                 ]
                 (builtins.readFile ./packages/release/release.sh);
@@ -237,18 +253,24 @@
       };
 
       # ── packages ────────────────────────────────────────────────────────────
-      packages = forAllSystems (
-        system:
-        let
-          pkgs = import nixpkgs { inherit system; };
-        in
-        {
+      packages = forAllSystems (system: {
         # Expose a no-op release package for the lib repo itself (dogfood)
         release = self.lib.mkRelease {
           inherit system;
-          };
+          release = [
+            {
+              run = ''
+                sed -E -i "s#^([[:space:]]*devshell-lib\\.url = \")git\\+https://git\\.dgren\\.dev/eric/nix-flake-lib[^\"]*(\";)#\\1git+https://git.dgren.dev/eric/nix-flake-lib?ref=$FULL_TAG\\2#" "$ROOT_DIR/template/flake.nix"
+                log "Updated template/flake.nix devshell-lib ref to $FULL_TAG"
+
+                sed -E -i "s|(nix flake new myapp -t ')git\\+https://git\\.dgren\\.dev/eric/nix-flake-lib[^']*(#default' --refresh)|\\1git+https://git.dgren.dev/eric/nix-flake-lib?ref=$FULL_TAG\\2|" "$ROOT_DIR/README.md"
+                sed -E -i "s#^([[:space:]]*inputs\\.devshell-lib\\.url = \")git\\+https://git\\.dgren\\.dev/eric/nix-flake-lib[^\"]*(\";)#\\1git+https://git.dgren.dev/eric/nix-flake-lib?ref=$FULL_TAG\\2#" "$ROOT_DIR/README.md"
+                log "Updated README.md devshell-lib refs to $FULL_TAG"
+              '';
             }
-      );
+          ];
+        };
+      });
 
       # ── devShells ───────────────────────────────────────────────────────────
       devShells = forAllSystems (
@@ -279,10 +301,28 @@
       checks = forAllSystems (
         system:
         let
+          pkgs = import nixpkgs { inherit system; };
           env = self.lib.mkDevShell { inherit system; };
         in
         {
           inherit (env) pre-commit-check;
+          release-tests =
+            pkgs.runCommand "release-tests"
+              {
+                nativeBuildInputs = with pkgs; [
+                  bash
+                  git
+                  gnused
+                  coreutils
+                  gnugrep
+                ];
+              }
+              ''
+                export REPO_LIB_ROOT=${./.}
+                export HOME="$TMPDIR"
+                ${pkgs.bash}/bin/bash ${./tests/release.sh}
+                touch "$out"
+              '';
         }
       );
 

packages/release/release.nix

@@ -1,13 +1,11 @@
 # release.nix
 {
   pkgs,
-  # Source of truth is always $ROOT_DIR/VERSION.
-  # Format:
-  #   line 1: X.Y.Z
-  #   line 2: CHANNEL (stable|alpha|beta|rc|internal|...)
-  #   line 3: N (prerelease number, 0 for stable)
   postVersion ? "",
-  versionFiles ? [ ],
+  release ? [ ],
+  # Unified list, processed in declaration order:
+  #   { file = "path/to/file"; content = "..."; }   — write file
+  #   { run = "shell snippet..."; }                  — run script
   channels ? [
     "alpha"
     "beta"
@@ -19,24 +17,28 @@
 let
   channelList = pkgs.lib.concatStringsSep " " channels;
 
-  versionFilesScript = pkgs.lib.concatMapStrings (f: ''
-    mkdir -p "$(dirname "${f.path}")"
-    ${f.content} > "${f.path}"
-    log "Generated version file: ${f.path}"
-  '') versionFiles;
+  releaseScript = pkgs.lib.concatMapStrings (
+    entry:
+    if entry ? file then
+      ''
+        mkdir -p "$(dirname "${entry.file}")"
+        cat > "${entry.file}" << NIXEOF
+        ${entry.content}
+        NIXEOF
+        log "Generated version file: ${entry.file}"
+      ''
+    else if entry ? run then
+      ''
+        ${entry.run}
+      ''
+    else
+      builtins.throw "release entry must have either 'file' or 'run'"
+  ) release;
 
   script =
     builtins.replaceStrings
-      [
-        "__CHANNEL_LIST__"
-        "__VERSION_FILES__"
-        "__POST_VERSION__"
-      ]
-      [
-        channelList
-        versionFilesScript
-        postVersion
-      ]
+      [ "__CHANNEL_LIST__" "__RELEASE_STEPS__" "__POST_VERSION__" ]
+      [ channelList releaseScript postVersion ]
       (builtins.readFile ./release.sh);
 in
 pkgs.writeShellApplication {

packages/release/release.sh

@@ -23,11 +23,12 @@ usage() {
 		"  (none)            bump patch, keep current channel" \
 		"  major/minor/patch bump the given part, keep current channel" \
 		"  stable / full     remove prerelease suffix" \
-    "  __CHANNEL_LIST__    switch channel (bumps prerelease number if same base+channel)" \
+		"  __CHANNEL_LIST__    switch channel (from stable, auto-bumps patch unless bump is specified)" \
 		"" \
 		"Examples:" \
 		"  ${cmd}                 # patch bump on current channel" \
 		"  ${cmd} minor           # minor bump on current channel" \
+		"  ${cmd} beta            # from stable: patch bump + beta.1" \
 		"  ${cmd} patch beta      # patch bump, switch to beta channel" \
 		"  ${cmd} rc              # switch to rc channel" \
 		"  ${cmd} stable          # promote to stable release" \
@@ -159,7 +160,8 @@ compute_full_version() {
 	else
 		FULL_VERSION="${BASE_VERSION}-${CHANNEL}.${PRERELEASE_NUM:-1}"
 	fi
-  export BASE_VERSION CHANNEL PRERELEASE_NUM FULL_VERSION
+	FULL_TAG="v$FULL_VERSION"
+	export BASE_VERSION CHANNEL PRERELEASE_NUM FULL_VERSION FULL_TAG
 }
 
 # ── gitlint ────────────────────────────────────────────────────────────────
@@ -187,9 +189,9 @@ validate_commit_message() {
 
 # ── version file generation ────────────────────────────────────────────────
 
-generate_version_files() {
+run_release_steps() {
 	:
-  __VERSION_FILES__
+	__RELEASE_STEPS__
 }
 
 # ── version source (built-in) ──────────────────────────────────────────────
@@ -227,7 +229,7 @@ init_version_file() {
 		n_to_write="0"
 	fi
 
-  printf '%s\n%s\n%s\n' "$BASE_VERSION" "$channel_to_write" "$n_to_write" > "$ROOT_DIR/VERSION"
+	printf '%s\n%s\n%s\n' "$BASE_VERSION" "$channel_to_write" "$n_to_write" >"$ROOT_DIR/VERSION"
 	log "Initialized $ROOT_DIR/VERSION from highest tag: v$highest_tag"
 }
 
@@ -251,7 +253,7 @@ do_write_version() {
 		channel_to_write="stable"
 		n_to_write="0"
 	fi
-  printf '%s\n%s\n%s\n' "$BASE_VERSION" "$channel_to_write" "$n_to_write" > "$ROOT_DIR/VERSION"
+	printf '%s\n%s\n%s\n' "$BASE_VERSION" "$channel_to_write" "$n_to_write" >"$ROOT_DIR/VERSION"
 }
 
 # ── user-provided hook ─────────────────────────────────────────────────────
@@ -309,7 +311,7 @@ main() {
 		esac
 
 	else
-    local part="" target_channel=""
+		local part="" target_channel="" was_channel_only=0
 
 		case "$action" in
 		"") part="patch" ;;
@@ -330,6 +332,7 @@ main() {
 			if [[ $is_channel == 1 ]]; then
 				[[ -n ${1-} ]] && echo "Error: channel-only bump takes no second argument" >&2 && usage && exit 1
 				target_channel="$action"
+				was_channel_only=1
 			else
 				echo "Error: unknown argument '$action'" >&2
 				usage
@@ -342,6 +345,10 @@ main() {
 		[[ $target_channel == "full" ]] && target_channel="stable"
 		validate_channel "$target_channel"
 
+		if [[ -z $part && $was_channel_only -eq 1 && $CHANNEL == "stable" && $target_channel != "stable" ]]; then
+			part="patch"
+		fi
+
 		local old_base="$BASE_VERSION" old_channel="$CHANNEL" old_pre="$PRERELEASE_NUM"
 		[[ -n $part ]] && bump_base_version "$part"
 
@@ -364,7 +371,8 @@ main() {
 	do_write_version
 	log "Updated version source"
 
-  generate_version_files
+	run_release_steps
+	log "Release steps done"
 
 	do_post_version
 	log "Post-version hook done"
@@ -378,13 +386,13 @@ main() {
 	git commit -m "$commit_msg"
 	log "Created commit"
 
-  git tag "v$FULL_VERSION"
-  CREATED_TAG="v$FULL_VERSION"
-  log "Tagged v$FULL_VERSION"
+	git tag "$FULL_TAG"
+	CREATED_TAG="$FULL_TAG"
+	log "Tagged $FULL_TAG"
 
 	git push
 	git push --tags
-  log "Done — released v$FULL_VERSION"
+	log "Done — released $FULL_TAG"
 
 	trap - ERR
 }

template/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "files.exclude": {
+    "**/.git": true,
+    "**/.svn": true,
+    "**/.hg": true,
+    "**/.DS_Store": true,
+    "**/Thumbs.db": true,
+    "VERSION": true
+  }
+}

template/flake.lock

@@ -0,0 +1,159 @@
+{
+  "nodes": {
+    "devshell-lib": {
+      "inputs": {
+        "git-hooks": "git-hooks",
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "treefmt-nix": "treefmt-nix"
+      },
+      "locked": {
+        "lastModified": 1772603902,
+        "narHash": "sha256-GN5EC9m0flWDuc6qaB6QoIBD73yFnhl2PBIYXzSTGeQ=",
+        "ref": "v0.0.2",
+        "rev": "db4ed150e01e2f9245e668077245447d0089163f",
+        "revCount": 15,
+        "type": "git",
+        "url": "https://git.dgren.dev/eric/nix-flake-lib"
+      },
+      "original": {
+        "ref": "v0.0.2",
+        "type": "git",
+        "url": "https://git.dgren.dev/eric/nix-flake-lib"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1767039857,
+        "narHash": "sha256-vNpUSpF5Nuw8xvDLj2KCwwksIbjua2LZCqhV1LNRDns=",
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "gitignore": "gitignore",
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1772024342,
+        "narHash": "sha256-+eXlIc4/7dE6EcPs9a2DaSY3fTA9AE526hGqkNID3Wg=",
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "6e34e97ed9788b17796ee43ccdbaf871a5c2b476",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "devshell-lib",
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "narHash": "sha256-HG2cCnktfHsKV0s4XW83gU3F57gaTljL9KNSuG6bnQs=",
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1770073757,
+        "narHash": "sha256-Vy+G+F+3E/Tl+GMNgiHl9Pah2DgShmIUBJXmbiQPHbI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "47472570b1e607482890801aeaf29bfb749884f6",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1770107345,
+        "narHash": "sha256-tbS0Ebx2PiA1FRW8mt8oejR0qMXmziJmPaU1d4kYY9g=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "4533d9293756b63904b7238acb84ac8fe4c8c2c4",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
+      "locked": {
+        "lastModified": 1772542754,
+        "narHash": "sha256-WGV2hy+VIeQsYXpsLjdr4GvHv5eECMISX1zKLTedhdg=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "8c809a146a140c5c8806f13399592dbcb1bb5dc4",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devshell-lib": "devshell-lib",
+        "nixpkgs": "nixpkgs_3"
+      }
+    },
+    "treefmt-nix": {
+      "inputs": {
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1770228511,
+        "narHash": "sha256-wQ6NJSuFqAEmIg2VMnLdCnUc0b7vslUohqqGGD+Fyxk=",
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "rev": "337a4fe074be1042a35086f15481d763b8ddc0e7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

template/flake.nix

@@ -4,7 +4,7 @@
 
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
-    devshell-lib.url = "git+https://git.dgren.dev/eric/nix-flake-lib";
+    devshell-lib.url = "git+https://git.dgren.dev/eric/nix-flake-lib?ref=v1.0.7";
     devshell-lib.inputs.nixpkgs.follows = "nixpkgs";
   };
 
@@ -23,15 +23,8 @@
         "aarch64-darwin"
       ];
       forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
-    in
-    {
-      devShells = forAllSystems (
-        system:
-        let
-          pkgs = import nixpkgs { inherit system; };
-          env = devshell-lib.lib.mkDevShell {
-            inherit system;
 
+      mkDevShellConfig = pkgs: {
         # includeStandardPackages = false; # opt out of nixfmt/gitlint/gitleaks/shfmt defaults
 
         extraPackages = with pkgs; [
@@ -80,21 +73,95 @@
         '';
       };
     in
+    {
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          config = mkDevShellConfig pkgs;
+          env = devshell-lib.lib.mkDevShell (
+            ({ inherit system; } // config)
+            // {
+              extraPackages = config.extraPackages ++ [ self.packages.${system}.release ];
+            }
+          );
+        in
         {
           default = env.shell;
         }
       );
 
+      packages = forAllSystems (system: {
+        release = devshell-lib.lib.mkRelease {
+          inherit system;
+        };
+      });
+
       checks = forAllSystems (
         system:
         let
-          env = devshell-lib.lib.mkDevShell { inherit system; };
+          pkgs = import nixpkgs { inherit system; };
+          config = mkDevShellConfig pkgs;
+          env = devshell-lib.lib.mkDevShell ({ inherit system; } // config);
         in
         {
           inherit (env) pre-commit-check;
         }
       );
 
-      formatter = forAllSystems (system: (devshell-lib.lib.mkDevShell { inherit system; }).formatter);
+      formatter = forAllSystems (
+        system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          config = mkDevShellConfig pkgs;
+        in
+        (devshell-lib.lib.mkDevShell ({ inherit system; } // config)).formatter
+      );
+
+      # Release command (`release`)
+      #
+      # The release script always updates VERSION first, then:
+      #   1) runs release steps in order (file writes and scripts)
+      #   2) runs postVersion hook
+      #   3) formats, stages, commits, tags, and pushes
+      #
+      # Runtime env vars available in release.run/postVersion:
+      #   BASE_VERSION, CHANNEL, PRERELEASE_NUM, FULL_VERSION, FULL_TAG
+      #
+      # To customize release behavior in your repo, edit:
+      # packages = forAllSystems (
+      #   system:
+      #   {
+      #     release = devshell-lib.lib.mkRelease {
+      #       inherit system;
+      #
+      #       release = [
+      #         {
+      #           file = "src/version.ts";
+      #           content = ''
+      #             export const APP_VERSION = "$FULL_VERSION" as const;
+      #           '';
+      #         }
+      #         {
+      #           file = "internal/version/version.go";
+      #           content = ''
+      #             package version
+      #
+      #             const Version = "$FULL_VERSION"
+      #           '';
+      #         }
+      #         {
+      #           run = ''
+      #             sed -E -i "s#^([[:space:]]*my-lib\\.url = \")github:org/my-lib[^"]*(\";)#\\1github:org/my-lib?ref=$FULL_TAG\\2#" "$ROOT_DIR/flake.nix"
+      #           '';
+      #         }
+      #       ];
+      #
+      #       postVersion = ''
+      #         echo "Released $FULL_TAG"
+      #       '';
+      #     };
+      #   }
+      # );
     };
 }

tests/release.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="${REPO_LIB_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+RELEASE_TEMPLATE="$ROOT_DIR/packages/release/release.sh"
+
+fail() {
+	echo "[test] FAIL: $*" >&2
+	exit 1
+}
+
+assert_eq() {
+	local expected="$1"
+	local actual="$2"
+	local message="$3"
+	if [[ "$expected" != "$actual" ]]; then
+		fail "$message (expected '$expected', got '$actual')"
+	fi
+}
+
+make_release_script() {
+	local target="$1"
+	sed \
+		-e 's/__CHANNEL_LIST__/alpha beta rc internal/g' \
+		-e 's/__RELEASE_STEPS__/:/' \
+		-e 's/__POST_VERSION__/:/' \
+		"$RELEASE_TEMPLATE" >"$target"
+	chmod +x "$target"
+}
+
+setup_repo() {
+	local repo_dir="$1"
+	local remote_dir="$2"
+
+	mkdir -p "$repo_dir"
+	git -C "$repo_dir" init >/dev/null
+	git -C "$repo_dir" config user.name "Release Test"
+	git -C "$repo_dir" config user.email "release-test@example.com"
+
+	cat >"$repo_dir/flake.nix" <<'EOF'
+{
+  description = "release test";
+  outputs = { self }: { };
+}
+EOF
+
+	printf '1.0.0\nstable\n0\n' >"$repo_dir/VERSION"
+	git -C "$repo_dir" add -A
+	git -C "$repo_dir" commit -m "init" >/dev/null
+
+	git init --bare "$remote_dir" >/dev/null
+	git -C "$repo_dir" remote add origin "$remote_dir"
+	git -C "$repo_dir" push -u origin HEAD >/dev/null
+}
+
+version_from_file() {
+	local repo_dir="$1"
+	local base channel n
+	base="$(sed -n '1p' "$repo_dir/VERSION" | tr -d '\r')"
+	channel="$(sed -n '2p' "$repo_dir/VERSION" | tr -d '\r')"
+	n="$(sed -n '3p' "$repo_dir/VERSION" | tr -d '\r')"
+
+	if [[ -z "$channel" || "$channel" == "stable" ]]; then
+		echo "$base"
+	else
+		echo "$base-$channel.$n"
+	fi
+}
+
+run_case() {
+	local case_name="$1"
+	local command_args="$2"
+	local expected_version="$3"
+
+	local workdir
+	workdir="$(mktemp -d)"
+	local repo_dir="$workdir/repo"
+	local remote_dir="$workdir/remote.git"
+
+	setup_repo "$repo_dir" "$remote_dir"
+	make_release_script "$repo_dir/release"
+
+	mkdir -p "$repo_dir/bin"
+	cat >"$repo_dir/bin/nix" <<'EOF'
+#!/usr/bin/env bash
+if [[ "${1-}" == "fmt" ]]; then
+	exit 0
+fi
+echo "unexpected nix invocation: $*" >&2
+exit 1
+EOF
+	chmod +x "$repo_dir/bin/nix"
+
+	(
+		cd "$repo_dir"
+		PATH="$repo_dir/bin:$PATH" ./release $command_args >/dev/null
+	)
+
+	local got_version
+	got_version="$(version_from_file "$repo_dir")"
+	assert_eq "$expected_version" "$got_version" "$case_name: VERSION mismatch"
+
+	if ! git -C "$repo_dir" tag --list | grep -qx "v$expected_version"; then
+		fail "$case_name: expected tag v$expected_version was not created"
+	fi
+
+	rm -rf "$workdir"
+	echo "[test] PASS: $case_name" >&2
+}
+
+run_case "channel-only from stable bumps patch" "beta" "1.0.1-beta.1"
+run_case "explicit minor bump keeps requested bump" "minor beta" "1.1.0-beta.1"
+
+echo "[test] All release tests passed" >&2