chore(release): v2.0.0

feat: add randomized testing
chore(release): v1.0.7
2026-03-06 17:20:32 +01:00 · 2026-03-06 17:20:20 +01:00 · 2026-03-05 01:04:48 +01:00 · 2026-03-05 01:04:34 +01:00 · 2026-03-04 18:46:15 +01:00 · 2026-03-04 18:45:55 +01:00
10 changed files with 1434 additions and 399 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 .pre-commit-config.yaml
 .direnv
 result
+template/flake.lock
--- a/README.md
+++ b/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=v2.0.0#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=v2.0.0";
+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`).
--- a/2
+++ b/2
@@ -1,3 +1,3 @@
-0.0.2
+2.0.0
 stable
 0
--- a/flake.nix
+++ b/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
-              ''
-                mkdir -p "$(dirname "${f.path}")"
-                cat > "${f.path}" << 'NIXEOF'
-                ${renderedContent}
-                NIXEOF
-                log "Generated version file: ${f.path}"
-              ''
-            ) versionFiles;
+            releaseStepsScript = 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__"
+                  "__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
-        {
-          # Expose a no-op release package for the lib repo itself (dogfood)
-          release = self.lib.mkRelease {
-            inherit system;
-          };
-        }
-      );
+      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"
+              '';
        }
      );

--- a/packages/release/release.nix
+++ b/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 {
--- a/packages/release/release.sh
+++ b/packages/release/release.sh
@@ -12,161 +12,167 @@ CREATED_TAG=""
 log() { echo "[release] $*" >&2; }

 usage() {
-  local cmd
-  cmd="$(basename "$0")"
-  printf '%s\n' \
-    "Usage:" \
-    "  ${cmd} [major|minor|patch] [stable|__CHANNEL_LIST__]" \
-    "  ${cmd} set <version>" \
-    "" \
-    "Bump types:" \
-    "  (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)" \
-    "" \
-    "Examples:" \
-    "  ${cmd}                 # patch bump on current channel" \
-    "  ${cmd} minor           # minor bump on current channel" \
-    "  ${cmd} patch beta      # patch bump, switch to beta channel" \
-    "  ${cmd} rc              # switch to rc channel" \
-    "  ${cmd} stable          # promote to stable release" \
-    "  ${cmd} set 1.2.3" \
-    "  ${cmd} set 1.2.3-beta.1"
+	local cmd
+	cmd="$(basename "$0")"
+	printf '%s\n' \
+		"Usage:" \
+		"  ${cmd} [major|minor|patch] [stable|__CHANNEL_LIST__]" \
+		"  ${cmd} set <version>" \
+		"" \
+		"Bump types:" \
+		"  (none)            bump patch, keep current channel" \
+		"  major/minor/patch bump the given part, keep current channel" \
+		"  stable / full     remove prerelease suffix (only opt-in path to promote prerelease -> stable)" \
+		"  __CHANNEL_LIST__    switch channel (from stable, auto-bumps patch unless bump is specified)" \
+		"" \
+		"Safety rule:" \
+		"  If current version is prerelease (e.g. x.y.z-beta.N), promotion to stable is allowed only via 'stable' or 'full'." \
+		"  Commands like '${cmd} set x.y.z' or '${cmd} patch stable' are blocked from prerelease channels." \
+		"" \
+		"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 prerelease to stable (opt-in)" \
+		"  ${cmd} set 1.2.3" \
+		"  ${cmd} set 1.2.3-beta.1"
 }

 # ── git ────────────────────────────────────────────────────────────────────

 require_clean_git() {
-  if ! git diff --quiet || ! git diff --cached --quiet; then
-    echo "Error: git working tree is not clean. Commit or stash changes first." >&2
-    exit 1
-  fi
+	if ! git diff --quiet || ! git diff --cached --quiet; then
+		echo "Error: git working tree is not clean. Commit or stash changes first." >&2
+		exit 1
+	fi
 }

 revert_on_failure() {
-  local status=$?
-  if [[ -n $START_HEAD ]]; then
-    log "Release failed — reverting to $START_HEAD"
-    git reset --hard "$START_HEAD"
-  fi
-  if [[ -n $CREATED_TAG ]]; then
-    git tag -d "$CREATED_TAG" >/dev/null 2>&1 || true
-  fi
-  exit $status
+	local status=$?
+	if [[ -n $START_HEAD ]]; then
+		log "Release failed — reverting to $START_HEAD"
+		git reset --hard "$START_HEAD"
+	fi
+	if [[ -n $CREATED_TAG ]]; then
+		git tag -d "$CREATED_TAG" >/dev/null 2>&1 || true
+	fi
+	exit $status
 }

 # ── version parsing ────────────────────────────────────────────────────────

 parse_base_version() {
-  local v="$1"
-  if [[ ! $v =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
-    echo "Error: invalid base version '$v' (expected x.y.z)" >&2
-    exit 1
-  fi
-  MAJOR="${BASH_REMATCH[1]}"
-  MINOR="${BASH_REMATCH[2]}"
-  PATCH="${BASH_REMATCH[3]}"
+	local v="$1"
+	if [[ ! $v =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+		echo "Error: invalid base version '$v' (expected x.y.z)" >&2
+		exit 1
+	fi
+	MAJOR="${BASH_REMATCH[1]}"
+	MINOR="${BASH_REMATCH[2]}"
+	PATCH="${BASH_REMATCH[3]}"
 }

 parse_full_version() {
-  local v="$1"
-  CHANNEL="stable"
-  PRERELEASE_NUM=""
+	local v="$1"
+	CHANNEL="stable"
+	PRERELEASE_NUM=""

-  if [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)-([a-zA-Z]+)\.([0-9]+)$ ]]; then
-    BASE_VERSION="${BASH_REMATCH[1]}"
-    CHANNEL="${BASH_REMATCH[2]}"
-    PRERELEASE_NUM="${BASH_REMATCH[3]}"
-  elif [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
-    BASE_VERSION="${BASH_REMATCH[1]}"
-  else
-    echo "Error: invalid version '$v' (expected x.y.z or x.y.z-channel.N)" >&2
-    exit 1
-  fi
-  parse_base_version "$BASE_VERSION"
+	if [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)-([a-zA-Z]+)\.([0-9]+)$ ]]; then
+		BASE_VERSION="${BASH_REMATCH[1]}"
+		CHANNEL="${BASH_REMATCH[2]}"
+		PRERELEASE_NUM="${BASH_REMATCH[3]}"
+	elif [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+		BASE_VERSION="${BASH_REMATCH[1]}"
+	else
+		echo "Error: invalid version '$v' (expected x.y.z or x.y.z-channel.N)" >&2
+		exit 1
+	fi
+	parse_base_version "$BASE_VERSION"
 }

 validate_channel() {
-  local ch="$1"
-  [[ $ch == "stable" ]] && return 0
-  local valid_channels="__CHANNEL_LIST__"
-  for c in $valid_channels; do
-    [[ $ch == "$c" ]] && return 0
-  done
-  echo "Error: unknown channel '$ch'. Valid channels: stable $valid_channels" >&2
-  exit 1
+	local ch="$1"
+	[[ $ch == "stable" ]] && return 0
+	local valid_channels="__CHANNEL_LIST__"
+	for c in $valid_channels; do
+		[[ $ch == "$c" ]] && return 0
+	done
+	echo "Error: unknown channel '$ch'. Valid channels: stable $valid_channels" >&2
+	exit 1
 }

 version_cmp() {
-  # Returns: 0 if equal, 1 if v1 > v2, 2 if v1 < v2
-  # Stable > prerelease for same base version
-  local v1="$1" v2="$2"
-  [[ $v1 == "$v2" ]] && return 0
+	# Returns: 0 if equal, 1 if v1 > v2, 2 if v1 < v2
+	# Stable > prerelease for same base version
+	local v1="$1" v2="$2"
+	[[ $v1 == "$v2" ]] && return 0

-  local base1="" pre1="" base2="" pre2=""
-  if [[ $v1 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
-    base1="${BASH_REMATCH[1]}"
-    pre1="${BASH_REMATCH[2]}"
-  else
-    base1="$v1"
-  fi
-  if [[ $v2 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
-    base2="${BASH_REMATCH[1]}"
-    pre2="${BASH_REMATCH[2]}"
-  else
-    base2="$v2"
-  fi
+	local base1="" pre1="" base2="" pre2=""
+	if [[ $v1 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
+		base1="${BASH_REMATCH[1]}"
+		pre1="${BASH_REMATCH[2]}"
+	else
+		base1="$v1"
+	fi
+	if [[ $v2 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
+		base2="${BASH_REMATCH[1]}"
+		pre2="${BASH_REMATCH[2]}"
+	else
+		base2="$v2"
+	fi

-  if [[ $base1 != "$base2" ]]; then
-    local highest_base
-    highest_base=$(printf '%s\n%s\n' "$base1" "$base2" | sort -V | tail -n1)
-    [[ $highest_base == "$base1" ]] && return 1 || return 2
-  fi
+	if [[ $base1 != "$base2" ]]; then
+		local highest_base
+		highest_base=$(printf '%s\n%s\n' "$base1" "$base2" | sort -V | tail -n1)
+		[[ $highest_base == "$base1" ]] && return 1 || return 2
+	fi

-  [[ -z $pre1 && -n $pre2 ]] && return 1 # stable > prerelease
-  [[ -n $pre1 && -z $pre2 ]] && return 2 # prerelease < stable
-  [[ -z $pre1 && -z $pre2 ]] && return 0 # both stable
+	[[ -z $pre1 && -n $pre2 ]] && return 1 # stable > prerelease
+	[[ -n $pre1 && -z $pre2 ]] && return 2 # prerelease < stable
+	[[ -z $pre1 && -z $pre2 ]] && return 0 # both stable

-  local highest_pre
-  highest_pre=$(printf '%s\n%s\n' "$pre1" "$pre2" | sort -V | tail -n1)
-  [[ $highest_pre == "$pre1" ]] && return 1 || return 2
+	local highest_pre
+	highest_pre=$(printf '%s\n%s\n' "$pre1" "$pre2" | sort -V | tail -n1)
+	[[ $highest_pre == "$pre1" ]] && return 1 || return 2
 }

 bump_base_version() {
-  case "$1" in
-  major)
-    MAJOR=$((MAJOR + 1))
-    MINOR=0
-    PATCH=0
-    ;;
-  minor)
-    MINOR=$((MINOR + 1))
-    PATCH=0
-    ;;
-  patch) PATCH=$((PATCH + 1)) ;;
-  *)
-    echo "Error: unknown bump part '$1'" >&2
-    exit 1
-    ;;
-  esac
-  BASE_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+	case "$1" in
+	major)
+		MAJOR=$((MAJOR + 1))
+		MINOR=0
+		PATCH=0
+		;;
+	minor)
+		MINOR=$((MINOR + 1))
+		PATCH=0
+		;;
+	patch) PATCH=$((PATCH + 1)) ;;
+	*)
+		echo "Error: unknown bump part '$1'" >&2
+		exit 1
+		;;
+	esac
+	BASE_VERSION="${MAJOR}.${MINOR}.${PATCH}"
 }

 compute_full_version() {
-  if [[ $CHANNEL == "stable" || -z $CHANNEL ]]; then
-    FULL_VERSION="$BASE_VERSION"
-  else
-    FULL_VERSION="${BASE_VERSION}-${CHANNEL}.${PRERELEASE_NUM:-1}"
-  fi
-  export BASE_VERSION CHANNEL PRERELEASE_NUM FULL_VERSION
+	if [[ $CHANNEL == "stable" || -z $CHANNEL ]]; then
+		FULL_VERSION="$BASE_VERSION"
+	else
+		FULL_VERSION="${BASE_VERSION}-${CHANNEL}.${PRERELEASE_NUM:-1}"
+	fi
+	FULL_TAG="v$FULL_VERSION"
+	export BASE_VERSION CHANNEL PRERELEASE_NUM FULL_VERSION FULL_TAG
 }

 # ── gitlint ────────────────────────────────────────────────────────────────

 get_gitlint_title_regex() {
-  [[ ! -f $GITLINT_FILE ]] && return 0
-  awk '
+	[[ ! -f $GITLINT_FILE ]] && return 0
+	awk '
    /^\[title-match-regex\]$/ { in_section=1; next }
    /^\[/ { in_section=0 }
    in_section && /^regex=/ { sub(/^regex=/, ""); print; exit }
@@ -174,22 +180,22 @@ get_gitlint_title_regex() {
 }

 validate_commit_message() {
-  local msg="$1"
-  local regex
-  regex="$(get_gitlint_title_regex)"
-  if [[ -n $regex && ! $msg =~ $regex ]]; then
-    echo "Error: commit message does not match .gitlint title-match-regex" >&2
-    echo "Regex:   $regex" >&2
-    echo "Message: $msg" >&2
-    exit 1
-  fi
+	local msg="$1"
+	local regex
+	regex="$(get_gitlint_title_regex)"
+	if [[ -n $regex && ! $msg =~ $regex ]]; then
+		echo "Error: commit message does not match .gitlint title-match-regex" >&2
+		echo "Regex:   $regex" >&2
+		echo "Message: $msg" >&2
+		exit 1
+	fi
 }

 # ── version file generation ────────────────────────────────────────────────

-generate_version_files() {
-  :
-  __VERSION_FILES__
+run_release_steps() {
+	:
+	__RELEASE_STEPS__
 }

 # ── version source (built-in) ──────────────────────────────────────────────
@@ -198,195 +204,214 @@ generate_version_files() {
 # Must be called outside of any subshell so log output stays on stderr
 # and never contaminates the stdout of do_read_version.
 init_version_file() {
-  if [[ -f "$ROOT_DIR/VERSION" ]]; then
-    return 0
-  fi
+	if [[ -f "$ROOT_DIR/VERSION" ]]; then
+		return 0
+	fi

-  local highest_tag=""
-  while IFS= read -r raw_tag; do
-    local tag="${raw_tag#v}"
-    [[ $tag =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+\.[0-9]+)?$ ]] || continue
+	local highest_tag=""
+	while IFS= read -r raw_tag; do
+		local tag="${raw_tag#v}"
+		[[ $tag =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+\.[0-9]+)?$ ]] || continue

-    if [[ -z $highest_tag ]]; then
-      highest_tag="$tag"
-      continue
-    fi
+		if [[ -z $highest_tag ]]; then
+			highest_tag="$tag"
+			continue
+		fi

-    local cmp_status=0
-    version_cmp "$tag" "$highest_tag" || cmp_status=$?
-    [[ $cmp_status -eq 1 ]] && highest_tag="$tag"
-  done < <(git tag --list)
+		local cmp_status=0
+		version_cmp "$tag" "$highest_tag" || cmp_status=$?
+		[[ $cmp_status -eq 1 ]] && highest_tag="$tag"
+	done < <(git tag --list)

-  [[ -z $highest_tag ]] && highest_tag="0.0.1"
+	[[ -z $highest_tag ]] && highest_tag="0.0.1"

-  parse_full_version "$highest_tag"
-  local channel_to_write="$CHANNEL"
-  local n_to_write="${PRERELEASE_NUM:-1}"
-  if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
-    channel_to_write="stable"
-    n_to_write="0"
-  fi
+	parse_full_version "$highest_tag"
+	local channel_to_write="$CHANNEL"
+	local n_to_write="${PRERELEASE_NUM:-1}"
+	if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
+		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"
-  log "Initialized $ROOT_DIR/VERSION from highest tag: v$highest_tag"
+	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"
 }

 do_read_version() {
-  local base_line channel_line n_line
-  base_line="$(sed -n '1p' "$ROOT_DIR/VERSION" | tr -d '\r')"
-  channel_line="$(sed -n '2p' "$ROOT_DIR/VERSION" | tr -d '\r')"
-  n_line="$(sed -n '3p' "$ROOT_DIR/VERSION" | tr -d '\r')"
+	local base_line channel_line n_line
+	base_line="$(sed -n '1p' "$ROOT_DIR/VERSION" | tr -d '\r')"
+	channel_line="$(sed -n '2p' "$ROOT_DIR/VERSION" | tr -d '\r')"
+	n_line="$(sed -n '3p' "$ROOT_DIR/VERSION" | tr -d '\r')"

-  if [[ -z $channel_line || $channel_line == "stable" ]]; then
-    printf '%s\n' "$base_line"
-  else
-    printf '%s-%s.%s\n' "$base_line" "$channel_line" "$n_line"
-  fi
+	if [[ -z $channel_line || $channel_line == "stable" ]]; then
+		printf '%s\n' "$base_line"
+	else
+		printf '%s-%s.%s\n' "$base_line" "$channel_line" "$n_line"
+	fi
 }

 do_write_version() {
-  local channel_to_write="$CHANNEL"
-  local n_to_write="${PRERELEASE_NUM:-1}"
-  if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
-    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"
+	local channel_to_write="$CHANNEL"
+	local n_to_write="${PRERELEASE_NUM:-1}"
+	if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
+		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"
 }

 # ── user-provided hook ─────────────────────────────────────────────────────

 do_post_version() {
-  :
-  __POST_VERSION__
+	:
+	__POST_VERSION__
 }

 # ── main ───────────────────────────────────────────────────────────────────

 main() {
-  [[ ${1-} == "-h" || ${1-} == "--help" ]] && usage && exit 0
+	[[ ${1-} == "-h" || ${1-} == "--help" ]] && usage && exit 0

-  require_clean_git
-  START_HEAD="$(git rev-parse HEAD)"
-  trap revert_on_failure ERR
+	require_clean_git
+	START_HEAD="$(git rev-parse HEAD)"
+	trap revert_on_failure ERR

-  # Initialize VERSION file outside any subshell so log lines never
-  # bleed into the stdout capture below.
-  init_version_file
+	# Initialize VERSION file outside any subshell so log lines never
+	# bleed into the stdout capture below.
+	init_version_file

-  local raw_version
-  raw_version="$(do_read_version | grep -E '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+\.[0-9]+)?$' | tail -n1)"
-  if [[ -z $raw_version ]]; then
-    echo "Error: could not determine current version from VERSION source" >&2
-    exit 1
-  fi
-  parse_full_version "$raw_version"
+	local raw_version
+	raw_version="$(do_read_version | grep -E '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+\.[0-9]+)?$' | tail -n1)"
+	if [[ -z $raw_version ]]; then
+		echo "Error: could not determine current version from VERSION source" >&2
+		exit 1
+	fi
+	parse_full_version "$raw_version"
+	compute_full_version
+	local current_full="$FULL_VERSION"

-  log "Current: base=$BASE_VERSION channel=$CHANNEL pre=${PRERELEASE_NUM:-}"
+	log "Current: base=$BASE_VERSION channel=$CHANNEL pre=${PRERELEASE_NUM:-}"

-  local action="${1-}"
-  shift || true
+	local action="${1-}"
+	shift || true

-  if [[ $action == "set" ]]; then
-    local newv="${1-}"
-    [[ -z $newv ]] && echo "Error: 'set' requires a version argument" >&2 && exit 1
-    compute_full_version
-    local current_full="$FULL_VERSION"
-    parse_full_version "$newv"
-    validate_channel "$CHANNEL"
-    compute_full_version
-    local cmp_status=0
-    version_cmp "$FULL_VERSION" "$current_full" || cmp_status=$?
-    case $cmp_status in
-    0)
-      echo "Version $FULL_VERSION is already current; nothing to do." >&2
-      exit 1
-      ;;
-    2)
-      echo "Error: $FULL_VERSION is lower than current $current_full" >&2
-      exit 1
-      ;;
-    esac
+	if [[ $action == "set" ]]; then
+		local newv="${1-}"
+		local current_channel="$CHANNEL"
+		[[ -z $newv ]] && echo "Error: 'set' requires a version argument" >&2 && exit 1
+		parse_full_version "$newv"
+		validate_channel "$CHANNEL"
+		if [[ $current_channel != "stable" && $CHANNEL == "stable" ]]; then
+			echo "Error: from prerelease channel '$current_channel', promote using 'stable' or 'full' only" >&2
+			exit 1
+		fi
+		compute_full_version
+		local cmp_status=0
+		version_cmp "$FULL_VERSION" "$current_full" || cmp_status=$?
+		case $cmp_status in
+		0)
+			echo "Version $FULL_VERSION is already current; nothing to do." >&2
+			exit 1
+			;;
+		2)
+			echo "Error: $FULL_VERSION is lower than current $current_full" >&2
+			exit 1
+			;;
+		esac

-  else
-    local part="" target_channel=""
+	else
+		local part="" target_channel="" was_channel_only=0

-    case "$action" in
-    "") part="patch" ;;
-    major | minor | patch)
-      part="$action"
-      target_channel="${1-}"
-      ;;
-    stable | full)
-      [[ -n ${1-} ]] && echo "Error: '$action' takes no second argument" >&2 && usage && exit 1
-      target_channel="stable"
-      ;;
-    *)
-      # check if action is a valid channel
-      local is_channel=0
-      for c in __CHANNEL_LIST__; do
-        [[ $action == "$c" ]] && is_channel=1 && break
-      done
-      if [[ $is_channel == 1 ]]; then
-        [[ -n ${1-} ]] && echo "Error: channel-only bump takes no second argument" >&2 && usage && exit 1
-        target_channel="$action"
-      else
-        echo "Error: unknown argument '$action'" >&2
-        usage
-        exit 1
-      fi
-      ;;
-    esac
+		case "$action" in
+		"") part="patch" ;;
+		major | minor | patch)
+			part="$action"
+			target_channel="${1-}"
+			;;
+		stable | full)
+			[[ -n ${1-} ]] && echo "Error: '$action' takes no second argument" >&2 && usage && exit 1
+			target_channel="stable"
+			;;
+		*)
+			# check if action is a valid channel
+			local is_channel=0
+			for c in __CHANNEL_LIST__; do
+				[[ $action == "$c" ]] && is_channel=1 && break
+			done
+			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
+				exit 1
+			fi
+			;;
+		esac

-    [[ -z $target_channel ]] && target_channel="$CHANNEL"
-    [[ $target_channel == "full" ]] && target_channel="stable"
-    validate_channel "$target_channel"
+		[[ -z $target_channel ]] && target_channel="$CHANNEL"
+		[[ $target_channel == "full" ]] && target_channel="stable"
+		validate_channel "$target_channel"
+		if [[ $CHANNEL != "stable" && $target_channel == "stable" && $action != "stable" && $action != "full" ]]; then
+			echo "Error: from prerelease channel '$CHANNEL', promote using 'stable' or 'full' only" >&2
+			exit 1
+		fi

-    local old_base="$BASE_VERSION" old_channel="$CHANNEL" old_pre="$PRERELEASE_NUM"
-    [[ -n $part ]] && bump_base_version "$part"
+		if [[ -z $part && $was_channel_only -eq 1 && $CHANNEL == "stable" && $target_channel != "stable" ]]; then
+			part="patch"
+		fi

-    if [[ $target_channel == "stable" ]]; then
-      CHANNEL="stable"
-      PRERELEASE_NUM=""
-    else
-      if [[ $BASE_VERSION == "$old_base" && $target_channel == "$old_channel" && -n $old_pre ]]; then
-        PRERELEASE_NUM=$((old_pre + 1))
-      else
-        PRERELEASE_NUM=1
-      fi
-      CHANNEL="$target_channel"
-    fi
-  fi
+		local old_base="$BASE_VERSION" old_channel="$CHANNEL" old_pre="$PRERELEASE_NUM"
+		[[ -n $part ]] && bump_base_version "$part"

-  compute_full_version
-  log "Releasing $FULL_VERSION"
+		if [[ $target_channel == "stable" ]]; then
+			CHANNEL="stable"
+			PRERELEASE_NUM=""
+		else
+			if [[ $BASE_VERSION == "$old_base" && $target_channel == "$old_channel" && -n $old_pre ]]; then
+				PRERELEASE_NUM=$((old_pre + 1))
+			else
+				PRERELEASE_NUM=1
+			fi
+			CHANNEL="$target_channel"
+		fi
+	fi

-  do_write_version
-  log "Updated version source"
+	compute_full_version
+	if [[ $FULL_VERSION == "$current_full" ]]; then
+		echo "Version $FULL_VERSION is already current; nothing to do." >&2
+		exit 1
+	fi
+	log "Releasing $FULL_VERSION"

-  generate_version_files
+	do_write_version
+	log "Updated version source"

-  do_post_version
-  log "Post-version hook done"
+	run_release_steps
+	log "Release steps done"

-  (cd "$ROOT_DIR" && nix fmt)
-  log "Formatted files"
+	do_post_version
+	log "Post-version hook done"

-  git add -A
-  local commit_msg="chore(release): v$FULL_VERSION"
-  validate_commit_message "$commit_msg"
-  git commit -m "$commit_msg"
-  log "Created commit"
+	(cd "$ROOT_DIR" && nix fmt)
+	log "Formatted files"

-  git tag "v$FULL_VERSION"
-  CREATED_TAG="v$FULL_VERSION"
-  log "Tagged v$FULL_VERSION"
+	git add -A
+	local commit_msg="chore(release): v$FULL_VERSION"
+	validate_commit_message "$commit_msg"
+	git commit -m "$commit_msg"
+	log "Created commit"

-  git push
-  git push --tags
-  log "Done — released v$FULL_VERSION"
+	git tag "$FULL_TAG"
+	CREATED_TAG="$FULL_TAG"
+	log "Tagged $FULL_TAG"

-  trap - ERR
+	git push
+	git push --tags
+	log "Done — released $FULL_TAG"
+
+	trap - ERR
 }

 main "$@"
--- a/template/.vscode/settings.json
+++ b/template/.vscode/settings.json
@@ -0,0 +1,10 @@
+{
+  "files.exclude": {
+    "**/.git": true,
+    "**/.svn": true,
+    "**/.hg": true,
+    "**/.DS_Store": true,
+    "**/Thumbs.db": true,
+    "VERSION": true
+  }
+}
--- a/template/flake.lock
+++ b/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
+}
--- a/template/flake.nix
+++ b/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=v2.0.0";
    devshell-lib.inputs.nixpkgs.follows = "nixpkgs";
  };

@@ -23,78 +23,145 @@
        "aarch64-darwin"
      ];
      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
+
+      mkDevShellConfig = pkgs: {
+        # includeStandardPackages = false; # opt out of nixfmt/gitlint/gitleaks/shfmt defaults
+
+        extraPackages = with pkgs; [
+          # add your tools here, e.g.:
+          # go
+          # bun
+          # rustc
+        ];
+
+        features = {
+          # oxfmt = true;  # enables oxfmt + oxlint from nixpkgs
+        };
+
+        formatters = {
+          # shfmt.enable = true;
+          # gofmt.enable = true;
+        };
+
+        formatterSettings = {
+          # shfmt.options = [ "-i" "2" "-s" "-w" ];
+          # oxfmt.includes = [ "*.ts" "*.tsx" "*.js" "*.json" ];
+        };
+
+        additionalHooks = {
+          tests = {
+            enable = true;
+            entry = "echo 'No tests defined yet.'"; # replace with your test command
+            pass_filenames = false;
+            stages = [ "pre-push" ];
+          };
+          # my-hook = {
+          #   enable = true;
+          #   entry = "${pkgs.some-tool}/bin/some-tool";
+          #   pass_filenames = false;
+          # };
+        };
+
+        tools = [
+          # { name = "Bun";   bin = "${pkgs.bun}/bin/bun";    versionCmd = "--version"; color = "YELLOW"; }
+          # { name = "Go";    bin = "${pkgs.go}/bin/go";       versionCmd = "version";   color = "CYAN";   }
+          # { name = "Rust";  bin = "${pkgs.rustc}/bin/rustc"; versionCmd = "--version"; color = "YELLOW"; }
+        ];
+
+        extraShellHook = ''
+          # any repo-specific shell setup here
+        '';
+      };
    in
    {
      devShells = forAllSystems (
        system:
        let
          pkgs = import nixpkgs { inherit system; };
-          env = devshell-lib.lib.mkDevShell {
-            inherit system;
-
-            # includeStandardPackages = false; # opt out of nixfmt/gitlint/gitleaks/shfmt defaults
-
-            extraPackages = with pkgs; [
-              # add your tools here, e.g.:
-              # go
-              # bun
-              # rustc
-            ];
-
-            features = {
-              # oxfmt = true;  # enables oxfmt + oxlint from nixpkgs
-            };
-
-            formatters = {
-              # shfmt.enable = true;
-              # gofmt.enable = true;
-            };
-
-            formatterSettings = {
-              # shfmt.options = [ "-i" "2" "-s" "-w" ];
-              # oxfmt.includes = [ "*.ts" "*.tsx" "*.js" "*.json" ];
-            };
-
-            additionalHooks = {
-              tests = {
-                enable = true;
-                entry = "echo 'No tests defined yet.'"; # replace with your test command
-                pass_filenames = false;
-                stages = [ "pre-push" ];
-              };
-              # my-hook = {
-              #   enable = true;
-              #   entry = "${pkgs.some-tool}/bin/some-tool";
-              #   pass_filenames = false;
-              # };
-            };
-
-            tools = [
-              # { name = "Bun";   bin = "${pkgs.bun}/bin/bun";    versionCmd = "--version"; color = "YELLOW"; }
-              # { name = "Go";    bin = "${pkgs.go}/bin/go";       versionCmd = "version";   color = "CYAN";   }
-              # { name = "Rust";  bin = "${pkgs.rustc}/bin/rustc"; versionCmd = "--version"; color = "YELLOW"; }
-            ];
-
-            extraShellHook = ''
-              # any repo-specific shell setup here
-            '';
-          };
+          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"
+      #       '';
+      #     };
+      #   }
+      # );
    };
 }
--- a/tests/release.sh
+++ b/tests/release.sh
@@ -0,0 +1,657 @@
+#!/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"
+CURRENT_LOG=""
+
+fail() {
+	echo "[test] FAIL: $*" >&2
+	if [[ -n "$CURRENT_LOG" && -f "$CURRENT_LOG" ]]; then
+		echo "[test] ---- captured output ----" >&2
+		cat "$CURRENT_LOG" >&2
+		echo "[test] -------------------------" >&2
+	fi
+	exit 1
+}
+
+assert_eq() {
+	local expected="$1"
+	local actual="$2"
+	local message="$3"
+	if [[ "$expected" != "$actual" ]]; then
+		fail "$message (expected '$expected', got '$actual')"
+	fi
+}
+
+assert_contains() {
+	local needle="$1"
+	local haystack_file="$2"
+	local message="$3"
+	if ! grep -Fq "$needle" "$haystack_file"; then
+		fail "$message (missing '$needle')"
+	fi
+}
+
+run_capture_ok() {
+	local description="$1"
+	shift
+	if ! "$@" >>"$CURRENT_LOG" 2>&1; then
+		fail "$description"
+	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"
+	run_capture_ok "setup_repo: git init failed" git -C "$repo_dir" init
+	run_capture_ok "setup_repo: git config user.name failed" git -C "$repo_dir" config user.name "Release Test"
+	run_capture_ok "setup_repo: git config user.email failed" 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"
+	run_capture_ok "setup_repo: git add failed" git -C "$repo_dir" add -A
+	run_capture_ok "setup_repo: git commit failed" git -C "$repo_dir" commit -m "init"
+
+	run_capture_ok "setup_repo: git init --bare failed" git init --bare "$remote_dir"
+	run_capture_ok "setup_repo: git remote add failed" git -C "$repo_dir" remote add origin "$remote_dir"
+	run_capture_ok "setup_repo: initial push failed" git -C "$repo_dir" push -u origin HEAD
+}
+
+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
+}
+
+prepare_case_repo() {
+	local repo_dir="$1"
+	local remote_dir="$2"
+
+	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"
+}
+
+run_release() {
+	local repo_dir="$1"
+	shift
+	(
+		cd "$repo_dir"
+		PATH="$repo_dir/bin:$PATH" ./release "$@"
+	)
+}
+
+qc_version_cmp() {
+	# Returns: 0 if equal, 1 if v1 > v2, 2 if v1 < v2
+	local v1="$1" v2="$2"
+	[[ $v1 == "$v2" ]] && return 0
+
+	local base1="" pre1="" base2="" pre2=""
+	if [[ $v1 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
+		base1="${BASH_REMATCH[1]}"
+		pre1="${BASH_REMATCH[2]}"
+	else
+		base1="$v1"
+	fi
+	if [[ $v2 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
+		base2="${BASH_REMATCH[1]}"
+		pre2="${BASH_REMATCH[2]}"
+	else
+		base2="$v2"
+	fi
+
+	if [[ $base1 != "$base2" ]]; then
+		local highest_base
+		highest_base=$(printf '%s\n%s\n' "$base1" "$base2" | sort -V | tail -n1)
+		[[ $highest_base == "$base1" ]] && return 1 || return 2
+	fi
+
+	[[ -z $pre1 && -n $pre2 ]] && return 1
+	[[ -n $pre1 && -z $pre2 ]] && return 2
+	[[ -z $pre1 && -z $pre2 ]] && return 0
+
+	local highest_pre
+	highest_pre=$(printf '%s\n%s\n' "$pre1" "$pre2" | sort -V | tail -n1)
+	[[ $highest_pre == "$pre1" ]] && return 1 || return 2
+}
+
+qc_parse_base_version() {
+	local v="$1"
+	if [[ ! $v =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+		return 1
+	fi
+	QC_MAJOR="${BASH_REMATCH[1]}"
+	QC_MINOR="${BASH_REMATCH[2]}"
+	QC_PATCH="${BASH_REMATCH[3]}"
+	return 0
+}
+
+qc_parse_full_version() {
+	local v="$1"
+	QC_CHANNEL="stable"
+	QC_PRERELEASE_NUM=""
+
+	if [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)-([a-zA-Z]+)\.([0-9]+)$ ]]; then
+		QC_BASE_VERSION="${BASH_REMATCH[1]}"
+		QC_CHANNEL="${BASH_REMATCH[2]}"
+		QC_PRERELEASE_NUM="${BASH_REMATCH[3]}"
+	elif [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+		QC_BASE_VERSION="${BASH_REMATCH[1]}"
+	else
+		return 1
+	fi
+
+	qc_parse_base_version "$QC_BASE_VERSION"
+}
+
+qc_validate_channel() {
+	local channel="$1"
+	[[ $channel == "stable" || $channel == "alpha" || $channel == "beta" || $channel == "rc" || $channel == "internal" ]]
+}
+
+qc_compute_full_version() {
+	if [[ $QC_CHANNEL == "stable" || -z $QC_CHANNEL ]]; then
+		QC_FULL_VERSION="$QC_BASE_VERSION"
+	else
+		QC_FULL_VERSION="$QC_BASE_VERSION-$QC_CHANNEL.${QC_PRERELEASE_NUM:-1}"
+	fi
+}
+
+qc_bump_base_version() {
+	qc_parse_base_version "$QC_BASE_VERSION"
+	case "$1" in
+	major)
+		QC_MAJOR=$((QC_MAJOR + 1))
+		QC_MINOR=0
+		QC_PATCH=0
+		;;
+	minor)
+		QC_MINOR=$((QC_MINOR + 1))
+		QC_PATCH=0
+		;;
+	patch)
+		QC_PATCH=$((QC_PATCH + 1))
+		;;
+	esac
+	QC_BASE_VERSION="$QC_MAJOR.$QC_MINOR.$QC_PATCH"
+}
+
+qc_oracle_init() {
+	QC_STATE_BASE="1.0.0"
+	QC_STATE_CHANNEL="stable"
+	QC_STATE_PRE=""
+}
+
+qc_oracle_current_full() {
+	QC_BASE_VERSION="$QC_STATE_BASE"
+	QC_CHANNEL="$QC_STATE_CHANNEL"
+	QC_PRERELEASE_NUM="$QC_STATE_PRE"
+	qc_compute_full_version
+	echo "$QC_FULL_VERSION"
+}
+
+qc_pick_channel() {
+	local channels=(alpha beta rc internal)
+	echo "${channels[RANDOM % ${#channels[@]}]}"
+}
+
+qc_build_random_command() {
+	local current_full="$1"
+	QC_CMD_ARGS=()
+
+	local mode=$((RANDOM % 7))
+	case "$mode" in
+	0)
+		QC_CMD_ARGS=(patch)
+		;;
+	1)
+		local bumps=(major minor patch)
+		QC_CMD_ARGS=("${bumps[RANDOM % ${#bumps[@]}]}")
+		;;
+	2)
+		local bumps=(major minor patch)
+		QC_CMD_ARGS=("${bumps[RANDOM % ${#bumps[@]}]}" "$(qc_pick_channel)")
+		;;
+	3)
+		QC_CMD_ARGS=("$(qc_pick_channel)")
+		;;
+	4)
+		if (( RANDOM % 2 == 0 )); then
+			QC_CMD_ARGS=(stable)
+		else
+			QC_CMD_ARGS=(full)
+		fi
+		;;
+	5)
+		QC_CMD_ARGS=(set "$current_full")
+		;;
+	6)
+		qc_parse_base_version "$QC_STATE_BASE"
+		if (( RANDOM % 2 == 0 )); then
+			QC_CMD_ARGS=(set "$((QC_MAJOR + 1)).0.0")
+		else
+			QC_CMD_ARGS=(set "$QC_STATE_BASE-$(qc_pick_channel).1")
+		fi
+		;;
+	esac
+}
+
+qc_oracle_apply() {
+	local current_full
+	current_full="$(qc_oracle_current_full)"
+
+	QC_EXPECT_SUCCESS=0
+	QC_EXPECT_VERSION="$current_full"
+
+	local action="${1-}"
+	shift || true
+
+	if [[ $action == "set" ]]; then
+		local newv="${1-}"
+		[[ -z $newv ]] && return 0
+		qc_parse_full_version "$newv" || return 0
+		qc_validate_channel "$QC_CHANNEL" || return 0
+		if [[ $QC_STATE_CHANNEL != "stable" && $QC_CHANNEL == "stable" ]]; then
+			return 0
+		fi
+		qc_compute_full_version
+		local cmp_status=0
+		qc_version_cmp "$QC_FULL_VERSION" "$current_full" || cmp_status=$?
+		if [[ $cmp_status -eq 0 || $cmp_status -eq 2 ]]; then
+			return 0
+		fi
+
+		QC_STATE_BASE="$QC_BASE_VERSION"
+		QC_STATE_CHANNEL="$QC_CHANNEL"
+		QC_STATE_PRE="$QC_PRERELEASE_NUM"
+		QC_EXPECT_SUCCESS=1
+		QC_EXPECT_VERSION="$QC_FULL_VERSION"
+		return 0
+	fi
+
+	local part="" target_channel="" was_channel_only=0
+	case "$action" in
+	"")
+		part="patch"
+		;;
+	major | minor | patch)
+		part="$action"
+		target_channel="${1-}"
+		if [[ -n ${1-} ]]; then
+			shift || true
+			[[ -n ${1-} ]] && return 0
+		fi
+		;;
+	stable | full)
+		[[ -n ${1-} ]] && return 0
+		target_channel="stable"
+		;;
+	alpha | beta | rc | internal)
+		[[ -n ${1-} ]] && return 0
+		target_channel="$action"
+		was_channel_only=1
+		;;
+	*)
+		return 0
+		;;
+	esac
+
+	[[ -z $target_channel ]] && target_channel="$QC_STATE_CHANNEL"
+	[[ $target_channel == "full" ]] && target_channel="stable"
+	qc_validate_channel "$target_channel" || return 0
+	if [[ $QC_STATE_CHANNEL != "stable" && $target_channel == "stable" && $action != "stable" && $action != "full" ]]; then
+		return 0
+	fi
+
+	if [[ -z $part && $was_channel_only -eq 1 && $QC_STATE_CHANNEL == "stable" && $target_channel != "stable" ]]; then
+		part="patch"
+	fi
+
+	QC_BASE_VERSION="$QC_STATE_BASE"
+	QC_CHANNEL="$QC_STATE_CHANNEL"
+	QC_PRERELEASE_NUM="$QC_STATE_PRE"
+
+	local old_base="$QC_BASE_VERSION"
+	local old_channel="$QC_CHANNEL"
+	local old_pre="$QC_PRERELEASE_NUM"
+
+	[[ -n $part ]] && qc_bump_base_version "$part"
+
+	if [[ $target_channel == "stable" ]]; then
+		QC_CHANNEL="stable"
+		QC_PRERELEASE_NUM=""
+	else
+		if [[ $QC_BASE_VERSION == "$old_base" && $target_channel == "$old_channel" && -n $old_pre ]]; then
+			QC_PRERELEASE_NUM=$((old_pre + 1))
+		else
+			QC_PRERELEASE_NUM=1
+		fi
+		QC_CHANNEL="$target_channel"
+	fi
+
+	qc_compute_full_version
+	if [[ $QC_FULL_VERSION == "$current_full" ]]; then
+		return 0
+	fi
+
+	QC_STATE_BASE="$QC_BASE_VERSION"
+	QC_STATE_CHANNEL="$QC_CHANNEL"
+	QC_STATE_PRE="$QC_PRERELEASE_NUM"
+	QC_EXPECT_SUCCESS=1
+	QC_EXPECT_VERSION="$QC_FULL_VERSION"
+}
+
+run_randomized_quickcheck_cases() {
+	local case_name="randomized quickcheck transitions"
+	local trials="${QUICKCHECK_TRIALS:-20}"
+	local max_steps="${QUICKCHECK_MAX_STEPS:-7}"
+
+	local trial
+	for ((trial = 1; trial <= trials; trial++)); do
+		local workdir
+		workdir="$(mktemp -d)"
+		local repo_dir="$workdir/repo"
+		local remote_dir="$workdir/remote.git"
+		local setup_log="$workdir/setup.log"
+		CURRENT_LOG="$setup_log"
+
+		prepare_case_repo "$repo_dir" "$remote_dir"
+		qc_oracle_init
+
+		local steps=$((1 + RANDOM % max_steps))
+		local step
+		for ((step = 1; step <= steps; step++)); do
+			local step_log="$workdir/trial-${trial}-step-${step}.log"
+			local before_version
+			before_version="$(version_from_file "$repo_dir")"
+			local cmd_display=""
+			local step_result=""
+			local before_head
+			before_head="$(git -C "$repo_dir" rev-parse HEAD)"
+
+			local oracle_before
+			oracle_before="$(qc_oracle_current_full)"
+			qc_build_random_command "$oracle_before"
+			qc_oracle_apply "${QC_CMD_ARGS[@]}"
+			cmd_display="${QC_CMD_ARGS[*]}"
+
+			{
+				echo "[test] randomized trial=$trial/$trials step=$step/$steps"
+				echo "[test] command: ${QC_CMD_ARGS[*]}"
+				echo "[test] expect_success=$QC_EXPECT_SUCCESS expect_version=$QC_EXPECT_VERSION"
+			} >"$step_log"
+			CURRENT_LOG="$step_log"
+
+			set +e
+			run_release "$repo_dir" "${QC_CMD_ARGS[@]}" >>"$step_log" 2>&1
+			local status=$?
+			set -e
+
+			if [[ $QC_EXPECT_SUCCESS -eq 1 ]]; then
+				if [[ $status -ne 0 ]]; then
+					fail "$case_name: trial $trial step $step expected success for '${QC_CMD_ARGS[*]}'"
+				fi
+
+				local got_version
+				got_version="$(version_from_file "$repo_dir")"
+				assert_eq "$QC_EXPECT_VERSION" "$got_version" "$case_name: trial $trial step $step VERSION mismatch for '${QC_CMD_ARGS[*]}'"
+				step_result="$got_version"
+
+				if ! git -C "$repo_dir" tag --list | grep -qx "v$QC_EXPECT_VERSION"; then
+					fail "$case_name: trial $trial step $step expected tag v$QC_EXPECT_VERSION for '${QC_CMD_ARGS[*]}'"
+				fi
+			else
+				if [[ $status -eq 0 ]]; then
+					fail "$case_name: trial $trial step $step expected failure for '${QC_CMD_ARGS[*]}'"
+				fi
+
+				local got_version
+				got_version="$(version_from_file "$repo_dir")"
+				assert_eq "$before_version" "$got_version" "$case_name: trial $trial step $step VERSION changed on failure for '${QC_CMD_ARGS[*]}'"
+				step_result="fail (unchanged: $got_version)"
+
+				local after_head
+				after_head="$(git -C "$repo_dir" rev-parse HEAD)"
+				assert_eq "$before_head" "$after_head" "$case_name: trial $trial step $step HEAD changed on failure for '${QC_CMD_ARGS[*]}'"
+			fi
+
+			echo "[test] PASS: randomized quickcheck trial $trial/$trials step $step/$steps from $before_version run '$cmd_display' -> $step_result" >&2
+		done
+
+		echo "[test] PASS: randomized quickcheck trial $trial/$trials" >&2
+
+		rm -rf "$workdir"
+		CURRENT_LOG=""
+	done
+
+	echo "[test] PASS: $case_name ($trials trials)" >&2
+}
+
+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"
+	CURRENT_LOG="$workdir/case.log"
+
+	prepare_case_repo "$repo_dir" "$remote_dir"
+
+	run_capture_ok "$case_name: release command failed ($command_args)" run_release "$repo_dir" $command_args
+
+	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"
+	CURRENT_LOG=""
+	echo "[test] PASS: $case_name" >&2
+}
+
+run_set_prerelease_then_full_case() {
+	local case_name="set prerelease then full promotes to stable"
+
+	local workdir
+	workdir="$(mktemp -d)"
+	local repo_dir="$workdir/repo"
+	local remote_dir="$workdir/remote.git"
+	CURRENT_LOG="$workdir/case.log"
+
+	prepare_case_repo "$repo_dir" "$remote_dir"
+
+	run_capture_ok "$case_name: release set failed" run_release "$repo_dir" set 1.1.5-beta.1
+	run_capture_ok "$case_name: release full failed" run_release "$repo_dir" full
+
+	local got_version
+	got_version="$(version_from_file "$repo_dir")"
+	assert_eq "1.1.5" "$got_version" "$case_name: VERSION mismatch"
+
+	if ! git -C "$repo_dir" tag --list | grep -qx "v1.1.5"; then
+		fail "$case_name: expected tag v1.1.5 was not created"
+	fi
+
+	rm -rf "$workdir"
+	CURRENT_LOG=""
+	echo "[test] PASS: $case_name" >&2
+}
+
+run_set_stable_then_full_noop_case() {
+	local case_name="set stable then full fails with no-op"
+
+	local workdir
+	workdir="$(mktemp -d)"
+	local repo_dir="$workdir/repo"
+	local remote_dir="$workdir/remote.git"
+	CURRENT_LOG="$workdir/case.log"
+
+	prepare_case_repo "$repo_dir" "$remote_dir"
+
+	run_capture_ok "$case_name: release set failed" run_release "$repo_dir" set 1.1.5
+
+	local before_head
+	before_head="$(git -C "$repo_dir" rev-parse HEAD)"
+
+	local err_file="$workdir/full.err"
+	set +e
+	run_release "$repo_dir" full >"$err_file" 2>&1
+	local status=$?
+	set -e
+	cat "$err_file" >>"$CURRENT_LOG"
+
+	if [[ $status -eq 0 ]]; then
+		fail "$case_name: expected release full to fail on no-op version"
+	fi
+
+	assert_contains "Version 1.1.5 is already current; nothing to do." "$err_file" "$case_name: missing no-op message"
+
+	local after_head
+	after_head="$(git -C "$repo_dir" rev-parse HEAD)"
+	assert_eq "$before_head" "$after_head" "$case_name: HEAD changed despite no-op failure"
+
+	local got_version
+	got_version="$(version_from_file "$repo_dir")"
+	assert_eq "1.1.5" "$got_version" "$case_name: VERSION changed after no-op failure"
+
+	rm -rf "$workdir"
+	CURRENT_LOG=""
+	echo "[test] PASS: $case_name" >&2
+}
+
+run_set_stable_from_prerelease_requires_full_case() {
+	local case_name="set stable from prerelease requires full"
+
+	local workdir
+	workdir="$(mktemp -d)"
+	local repo_dir="$workdir/repo"
+	local remote_dir="$workdir/remote.git"
+	CURRENT_LOG="$workdir/case.log"
+
+	prepare_case_repo "$repo_dir" "$remote_dir"
+
+	run_capture_ok "$case_name: release set prerelease failed" run_release "$repo_dir" set 1.1.5-beta.1
+
+	local before_head
+	before_head="$(git -C "$repo_dir" rev-parse HEAD)"
+
+	local err_file="$workdir/set-stable.err"
+	set +e
+	run_release "$repo_dir" set 1.1.5 >"$err_file" 2>&1
+	local status=$?
+	set -e
+	cat "$err_file" >>"$CURRENT_LOG"
+
+	if [[ $status -eq 0 ]]; then
+		fail "$case_name: expected release set stable to fail from prerelease"
+	fi
+
+	assert_contains "promote using 'stable' or 'full' only" "$err_file" "$case_name: missing guardrail message"
+
+	local after_head
+	after_head="$(git -C "$repo_dir" rev-parse HEAD)"
+	assert_eq "$before_head" "$after_head" "$case_name: HEAD changed despite guardrail failure"
+
+	local got_version
+	got_version="$(version_from_file "$repo_dir")"
+	assert_eq "1.1.5-beta.1" "$got_version" "$case_name: VERSION changed after guardrail failure"
+
+	rm -rf "$workdir"
+	CURRENT_LOG=""
+	echo "[test] PASS: $case_name" >&2
+}
+
+run_patch_stable_from_prerelease_requires_full_case() {
+	local case_name="patch stable from prerelease requires full"
+
+	local workdir
+	workdir="$(mktemp -d)"
+	local repo_dir="$workdir/repo"
+	local remote_dir="$workdir/remote.git"
+	CURRENT_LOG="$workdir/case.log"
+
+	prepare_case_repo "$repo_dir" "$remote_dir"
+
+	run_capture_ok "$case_name: release set prerelease failed" run_release "$repo_dir" set 1.1.5-beta.1
+
+	local before_head
+	before_head="$(git -C "$repo_dir" rev-parse HEAD)"
+
+	local err_file="$workdir/patch-stable.err"
+	set +e
+	run_release "$repo_dir" patch stable >"$err_file" 2>&1
+	local status=$?
+	set -e
+	cat "$err_file" >>"$CURRENT_LOG"
+
+	if [[ $status -eq 0 ]]; then
+		fail "$case_name: expected release patch stable to fail from prerelease"
+	fi
+
+	assert_contains "promote using 'stable' or 'full' only" "$err_file" "$case_name: missing guardrail message"
+
+	local after_head
+	after_head="$(git -C "$repo_dir" rev-parse HEAD)"
+	assert_eq "$before_head" "$after_head" "$case_name: HEAD changed despite guardrail failure"
+
+	local got_version
+	got_version="$(version_from_file "$repo_dir")"
+	assert_eq "1.1.5-beta.1" "$got_version" "$case_name: VERSION changed after guardrail failure"
+
+	rm -rf "$workdir"
+	CURRENT_LOG=""
+	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"
+run_set_prerelease_then_full_case
+run_set_stable_then_full_noop_case
+run_set_stable_from_prerelease_requires_full_case
+run_patch_stable_from_prerelease_requires_full_case
+run_randomized_quickcheck_cases
+
+echo "[test] All release tests passed" >&2
Author	SHA1	Message	Date
eric	1399862dec	chore(release): v2.0.0	2026-03-06 17:20:32 +01:00
eric	ba4a992474	feat: add randomized testing	2026-03-06 17:20:20 +01:00
eric	aa4a050390	chore(release): v1.0.7	2026-03-05 01:04:48 +01:00
eric	b7558a4218	fix: run treefmt in ci mode	2026-03-05 01:04:34 +01:00
eric	f7dce637d5	chore(release): v1.0.6	2026-03-04 18:46:15 +01:00
eric	250882da1f	test: ensure versions are consistent	2026-03-04 18:45:55 +01:00
eric	e445e49baf	chore(release): v1.0.5	2026-03-04 09:35:15 +01:00
eric	ef3cf30a34	fix: expose releases as well	2026-03-04 09:35:05 +01:00
eric	86a0792b6e	chore(release): v1.0.4	2026-03-04 08:48:24 +01:00
eric	d1aea76dd9	fix: formatting	2026-03-04 08:48:16 +01:00
eric	cdc9e18035	chore(release): v1.0.3	2026-03-04 08:25:29 +01:00
eric	374ba596ab	fix: spacing	2026-03-04 08:25:21 +01:00
eric	ffeede1dca	chore(release): v1.0.2	2026-03-04 08:21:29 +01:00
eric	a7c17bc738	feat: add more colors	2026-03-04 08:21:20 +01:00
eric	7e93c5267a	chore(release): v1.0.1	2026-03-04 07:57:14 +01:00
eric	fd7a2ca07d	fix: sed issue with parsing	2026-03-04 07:56:34 +01:00
eric	d7d6a42d48	feat: add tag ref to install commands	2026-03-04 07:55:03 +01:00
eric	3a5cdb5900	chore(release): v1.0.0	2026-03-04 07:47:46 +01:00
eric	d8f92486c3	feat: add VERSION to exclude list in vscode	2026-03-04 07:47:34 +01:00
eric	f6c6e97707	chore(release): v0.0.5	2026-03-04 07:36:13 +01:00
eric	c976621357	chore: re-release to test 2	2026-03-04 07:36:05 +01:00
eric	919b328e93	chore(release): v0.0.4	2026-03-04 07:32:16 +01:00
eric	7641622e8d	chore: re-release to test	2026-03-04 07:32:09 +01:00
eric	3c7bf1489a	chore(release): v0.0.3	2026-03-04 07:26:06 +01:00
eric	40d0464f61	feat: unify release steps	2026-03-04 07:25:54 +01:00
eric	9f2e1b512b	feat: unify release steps	2026-03-04 07:25:31 +01:00