chore(release): v1.0.2

.gitignore

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

README.md

@@ -0,0 +1,72 @@
+# 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.2#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.2";
+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 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`.

VERSION

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

flake.nix

@@ -95,6 +95,11 @@
               // additionalHooks;
             };
 
+            toolNameWidth = builtins.foldl' (
+              maxWidth: t: builtins.max maxWidth (builtins.stringLength t.name)
+            ) 0 tools;
+            toolLabelWidth = toolNameWidth + 1;
+
             toolBannerScript = pkgs.lib.concatMapStrings (
               t:
               let
@@ -102,7 +107,7 @@
               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})"
+                  printf "  $CYAN %-${toString toolLabelWidth}s$RESET ${colorVar}%s$RESET\n" "${t.name}:" "$(${t.bin} ${t.versionCmd})"
                 fi
               ''
             ) tools;
@@ -122,14 +127,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 +161,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 ? [ ],
+            release ? [ ],
-            # List of { path, template } attrsets.
+            # Unified list processed in declaration order:
-            # template is a Nix function: version -> string
+            #   { file = "path/to/file"; content = ''...$FULL_VERSION...''; }  # write file
-            # The content is fully rendered by Nix at eval time — no shell interpolation needed.
+            #   { run = ''...shell snippet...''; }                               # run script
             # Example:
-            #   versionFiles = [
+            #   release = [
             #     {
-            #       path = "src/version.ts";
+            #       file = "src/version.ts";
-            #       template = version: ''export const APP_VERSION = "${version}" as const;'';
+            #       content = ''export const APP_VERSION = "$FULL_VERSION" as const;'';
             #     }
             #     {
-            #       path = "internal/version/version.go";
+            #       file = "internal/version/version.go";
-            #       template = version: ''
+            #       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 +202,34 @@
             pkgs = import nixpkgs { inherit system; };
             channelList = pkgs.lib.concatStringsSep " " channels;
 
-            # Version files are fully rendered by Nix at eval time.
+            releaseStepsScript = pkgs.lib.concatMapStrings (
-            # The shell only writes the pre-computed strings — no shell interpolation in templates.
+              entry:
-            versionFilesScript = pkgs.lib.concatMapStrings (
+              if entry ? file then
-              f:
+                ''
-              let
+                  mkdir -p "$(dirname "${entry.file}")"
-                # We can't call f.template here since FULL_VERSION is a runtime value.
+                  cat > "${entry.file}" << NIXEOF
-                # Instead we pass the path and use a shell heredoc with the template
+                  ${entry.content}
-                # rendered at runtime via the VERSION env vars.
+                  NIXEOF
-                renderedContent = f.template "$FULL_VERSION";
+                  log "Generated version file: ${entry.file}"
-              in
+                ''
-              ''
+              else if entry ? run then
-                mkdir -p "$(dirname "${f.path}")"
+                ''
-                cat > "${f.path}" << 'NIXEOF'
+                  ${entry.run}
-                ${renderedContent}
+                ''
-                NIXEOF
+              else
-                log "Generated version file: ${f.path}"
+                builtins.throw "release entry must have either 'file' or 'run'"
-              ''
+            ) release;
-            ) versionFiles;
 
             script =
               builtins.replaceStrings
                 [
                   "__CHANNEL_LIST__"
-                  "__VERSION_FILES__"
+                  "__RELEASE_STEPS__"
                   "__POST_VERSION__"
                 ]
                 [
                   channelList
-                  versionFilesScript
+                  releaseStepsScript
                   postVersion
                 ]
                 (builtins.readFile ./packages/release/release.sh);
@@ -237,18 +252,24 @@
       };
 
       # ── packages ────────────────────────────────────────────────────────────
-      packages = forAllSystems (
+      packages = forAllSystems (system: {
-        system:
+        # Expose a no-op release package for the lib repo itself (dogfood)
-        let
+        release = self.lib.mkRelease {
-          pkgs = import nixpkgs { inherit system; };
+          inherit system;
-        in
+          release = [
-        {
+            {
-          # Expose a no-op release package for the lib repo itself (dogfood)
+              run = ''
-          release = self.lib.mkRelease {
+                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"
-            inherit system;
+                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 (

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: ''
+  releaseScript = pkgs.lib.concatMapStrings (
-    mkdir -p "$(dirname "${f.path}")"
+    entry:
-    ${f.content} > "${f.path}"
+    if entry ? file then
-    log "Generated version file: ${f.path}"
+      ''
-  '') versionFiles;
+        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__" "__RELEASE_STEPS__" "__POST_VERSION__" ]
-        "__CHANNEL_LIST__"
+      [ channelList releaseScript postVersion ]
-        "__VERSION_FILES__"
-        "__POST_VERSION__"
-      ]
-      [
-        channelList
-        versionFilesScript
-        postVersion
-      ]
       (builtins.readFile ./release.sh);
 in
 pkgs.writeShellApplication {

packages/release/release.sh

@@ -12,161 +12,162 @@ CREATED_TAG=""
 log() { echo "[release] $*" >&2; }
 
 usage() {
-  local cmd
+	local cmd
-  cmd="$(basename "$0")"
+	cmd="$(basename "$0")"
-  printf '%s\n' \
+	printf '%s\n' \
-    "Usage:" \
+		"Usage:" \
-    "  ${cmd} [major|minor|patch] [stable|__CHANNEL_LIST__]" \
+		"  ${cmd} [major|minor|patch] [stable|__CHANNEL_LIST__]" \
-    "  ${cmd} set <version>" \
+		"  ${cmd} set <version>" \
-    "" \
+		"" \
-    "Bump types:" \
+		"Bump types:" \
-    "  (none)            bump patch, keep current channel" \
+		"  (none)            bump patch, keep current channel" \
-    "  major/minor/patch bump the given part, keep current channel" \
+		"  major/minor/patch bump the given part, keep current channel" \
-    "  stable / full     remove prerelease suffix" \
+		"  stable / full     remove prerelease suffix" \
-    "  __CHANNEL_LIST__    switch channel (bumps prerelease number if same base+channel)" \
+		"  __CHANNEL_LIST__    switch channel (bumps prerelease number if same base+channel)" \
-    "" \
+		"" \
-    "Examples:" \
+		"Examples:" \
-    "  ${cmd}                 # patch bump on current channel" \
+		"  ${cmd}                 # patch bump on current channel" \
-    "  ${cmd} minor           # minor bump on current channel" \
+		"  ${cmd} minor           # minor bump on current channel" \
-    "  ${cmd} patch beta      # patch bump, switch to beta channel" \
+		"  ${cmd} patch beta      # patch bump, switch to beta channel" \
-    "  ${cmd} rc              # switch to rc channel" \
+		"  ${cmd} rc              # switch to rc channel" \
-    "  ${cmd} stable          # promote to stable release" \
+		"  ${cmd} stable          # promote to stable release" \
-    "  ${cmd} set 1.2.3" \
+		"  ${cmd} set 1.2.3" \
-    "  ${cmd} set 1.2.3-beta.1"
+		"  ${cmd} set 1.2.3-beta.1"
 }
 
 # ── git ────────────────────────────────────────────────────────────────────
 
 require_clean_git() {
-  if ! git diff --quiet || ! git diff --cached --quiet; then
+	if ! git diff --quiet || ! git diff --cached --quiet; then
-    echo "Error: git working tree is not clean. Commit or stash changes first." >&2
+		echo "Error: git working tree is not clean. Commit or stash changes first." >&2
-    exit 1
+		exit 1
-  fi
+	fi
 }
 
 revert_on_failure() {
-  local status=$?
+	local status=$?
-  if [[ -n $START_HEAD ]]; then
+	if [[ -n $START_HEAD ]]; then
-    log "Release failed — reverting to $START_HEAD"
+		log "Release failed — reverting to $START_HEAD"
-    git reset --hard "$START_HEAD"
+		git reset --hard "$START_HEAD"
-  fi
+	fi
-  if [[ -n $CREATED_TAG ]]; then
+	if [[ -n $CREATED_TAG ]]; then
-    git tag -d "$CREATED_TAG" >/dev/null 2>&1 || true
+		git tag -d "$CREATED_TAG" >/dev/null 2>&1 || true
-  fi
+	fi
-  exit $status
+	exit $status
 }
 
 # ── version parsing ────────────────────────────────────────────────────────
 
 parse_base_version() {
-  local v="$1"
+	local v="$1"
-  if [[ ! $v =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+	if [[ ! $v =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
-    echo "Error: invalid base version '$v' (expected x.y.z)" >&2
+		echo "Error: invalid base version '$v' (expected x.y.z)" >&2
-    exit 1
+		exit 1
-  fi
+	fi
-  MAJOR="${BASH_REMATCH[1]}"
+	MAJOR="${BASH_REMATCH[1]}"
-  MINOR="${BASH_REMATCH[2]}"
+	MINOR="${BASH_REMATCH[2]}"
-  PATCH="${BASH_REMATCH[3]}"
+	PATCH="${BASH_REMATCH[3]}"
 }
 
 parse_full_version() {
-  local v="$1"
+	local v="$1"
-  CHANNEL="stable"
+	CHANNEL="stable"
-  PRERELEASE_NUM=""
+	PRERELEASE_NUM=""
 
-  if [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)-([a-zA-Z]+)\.([0-9]+)$ ]]; then
+	if [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)-([a-zA-Z]+)\.([0-9]+)$ ]]; then
-    BASE_VERSION="${BASH_REMATCH[1]}"
+		BASE_VERSION="${BASH_REMATCH[1]}"
-    CHANNEL="${BASH_REMATCH[2]}"
+		CHANNEL="${BASH_REMATCH[2]}"
-    PRERELEASE_NUM="${BASH_REMATCH[3]}"
+		PRERELEASE_NUM="${BASH_REMATCH[3]}"
-  elif [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+	elif [[ $v =~ ^([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
-    BASE_VERSION="${BASH_REMATCH[1]}"
+		BASE_VERSION="${BASH_REMATCH[1]}"
-  else
+	else
-    echo "Error: invalid version '$v' (expected x.y.z or x.y.z-channel.N)" >&2
+		echo "Error: invalid version '$v' (expected x.y.z or x.y.z-channel.N)" >&2
-    exit 1
+		exit 1
-  fi
+	fi
-  parse_base_version "$BASE_VERSION"
+	parse_base_version "$BASE_VERSION"
 }
 
 validate_channel() {
-  local ch="$1"
+	local ch="$1"
-  [[ $ch == "stable" ]] && return 0
+	[[ $ch == "stable" ]] && return 0
-  local valid_channels="__CHANNEL_LIST__"
+	local valid_channels="__CHANNEL_LIST__"
-  for c in $valid_channels; do
+	for c in $valid_channels; do
-    [[ $ch == "$c" ]] && return 0
+		[[ $ch == "$c" ]] && return 0
-  done
+	done
-  echo "Error: unknown channel '$ch'. Valid channels: stable $valid_channels" >&2
+	echo "Error: unknown channel '$ch'. Valid channels: stable $valid_channels" >&2
-  exit 1
+	exit 1
 }
 
 version_cmp() {
-  # Returns: 0 if equal, 1 if v1 > v2, 2 if v1 < v2
+	# Returns: 0 if equal, 1 if v1 > v2, 2 if v1 < v2
-  # Stable > prerelease for same base version
+	# Stable > prerelease for same base version
-  local v1="$1" v2="$2"
+	local v1="$1" v2="$2"
-  [[ $v1 == "$v2" ]] && return 0
+	[[ $v1 == "$v2" ]] && return 0
 
-  local base1="" pre1="" base2="" pre2=""
+	local base1="" pre1="" base2="" pre2=""
-  if [[ $v1 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
+	if [[ $v1 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
-    base1="${BASH_REMATCH[1]}"
+		base1="${BASH_REMATCH[1]}"
-    pre1="${BASH_REMATCH[2]}"
+		pre1="${BASH_REMATCH[2]}"
-  else
+	else
-    base1="$v1"
+		base1="$v1"
-  fi
+	fi
-  if [[ $v2 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
+	if [[ $v2 =~ ^([0-9]+\.[0-9]+\.[0-9]+)-(.+)$ ]]; then
-    base2="${BASH_REMATCH[1]}"
+		base2="${BASH_REMATCH[1]}"
-    pre2="${BASH_REMATCH[2]}"
+		pre2="${BASH_REMATCH[2]}"
-  else
+	else
-    base2="$v2"
+		base2="$v2"
-  fi
+	fi
 
-  if [[ $base1 != "$base2" ]]; then
+	if [[ $base1 != "$base2" ]]; then
-    local highest_base
+		local highest_base
-    highest_base=$(printf '%s\n%s\n' "$base1" "$base2" | sort -V | tail -n1)
+		highest_base=$(printf '%s\n%s\n' "$base1" "$base2" | sort -V | tail -n1)
-    [[ $highest_base == "$base1" ]] && return 1 || return 2
+		[[ $highest_base == "$base1" ]] && return 1 || return 2
-  fi
+	fi
 
-  [[ -z $pre1 && -n $pre2 ]] && return 1 # stable > prerelease
+	[[ -z $pre1 && -n $pre2 ]] && return 1 # stable > prerelease
-  [[ -n $pre1 && -z $pre2 ]] && return 2 # prerelease < stable
+	[[ -n $pre1 && -z $pre2 ]] && return 2 # prerelease < stable
-  [[ -z $pre1 && -z $pre2 ]] && return 0 # both stable
+	[[ -z $pre1 && -z $pre2 ]] && return 0 # both stable
 
-  local highest_pre
+	local highest_pre
-  highest_pre=$(printf '%s\n%s\n' "$pre1" "$pre2" | sort -V | tail -n1)
+	highest_pre=$(printf '%s\n%s\n' "$pre1" "$pre2" | sort -V | tail -n1)
-  [[ $highest_pre == "$pre1" ]] && return 1 || return 2
+	[[ $highest_pre == "$pre1" ]] && return 1 || return 2
 }
 
 bump_base_version() {
-  case "$1" in
+	case "$1" in
-  major)
+	major)
-    MAJOR=$((MAJOR + 1))
+		MAJOR=$((MAJOR + 1))
-    MINOR=0
+		MINOR=0
-    PATCH=0
+		PATCH=0
-    ;;
+		;;
-  minor)
+	minor)
-    MINOR=$((MINOR + 1))
+		MINOR=$((MINOR + 1))
-    PATCH=0
+		PATCH=0
-    ;;
+		;;
-  patch) PATCH=$((PATCH + 1)) ;;
+	patch) PATCH=$((PATCH + 1)) ;;
-  *)
+	*)
-    echo "Error: unknown bump part '$1'" >&2
+		echo "Error: unknown bump part '$1'" >&2
-    exit 1
+		exit 1
-    ;;
+		;;
-  esac
+	esac
-  BASE_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+	BASE_VERSION="${MAJOR}.${MINOR}.${PATCH}"
 }
 
 compute_full_version() {
-  if [[ $CHANNEL == "stable" || -z $CHANNEL ]]; then
+	if [[ $CHANNEL == "stable" || -z $CHANNEL ]]; then
-    FULL_VERSION="$BASE_VERSION"
+		FULL_VERSION="$BASE_VERSION"
-  else
+	else
-    FULL_VERSION="${BASE_VERSION}-${CHANNEL}.${PRERELEASE_NUM:-1}"
+		FULL_VERSION="${BASE_VERSION}-${CHANNEL}.${PRERELEASE_NUM:-1}"
-  fi
+	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 ────────────────────────────────────────────────────────────────
 
 get_gitlint_title_regex() {
-  [[ ! -f $GITLINT_FILE ]] && return 0
+	[[ ! -f $GITLINT_FILE ]] && return 0
-  awk '
+	awk '
     /^\[title-match-regex\]$/ { in_section=1; next }
     /^\[/ { in_section=0 }
     in_section && /^regex=/ { sub(/^regex=/, ""); print; exit }
@@ -174,22 +175,22 @@ get_gitlint_title_regex() {
 }
 
 validate_commit_message() {
-  local msg="$1"
+	local msg="$1"
-  local regex
+	local regex
-  regex="$(get_gitlint_title_regex)"
+	regex="$(get_gitlint_title_regex)"
-  if [[ -n $regex && ! $msg =~ $regex ]]; then
+	if [[ -n $regex && ! $msg =~ $regex ]]; then
-    echo "Error: commit message does not match .gitlint title-match-regex" >&2
+		echo "Error: commit message does not match .gitlint title-match-regex" >&2
-    echo "Regex:   $regex" >&2
+		echo "Regex:   $regex" >&2
-    echo "Message: $msg" >&2
+		echo "Message: $msg" >&2
-    exit 1
+		exit 1
-  fi
+	fi
 }
 
 # ── version file generation ────────────────────────────────────────────────
 
-generate_version_files() {
+run_release_steps() {
-  :
+	:
-  __VERSION_FILES__
+	__RELEASE_STEPS__
 }
 
 # ── version source (built-in) ──────────────────────────────────────────────
@@ -198,195 +199,196 @@ 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
+	if [[ -f "$ROOT_DIR/VERSION" ]]; then
-    return 0
+		return 0
-  fi
+	fi
 
-  local highest_tag=""
+	local highest_tag=""
-  while IFS= read -r raw_tag; do
+	while IFS= read -r raw_tag; do
-    local tag="${raw_tag#v}"
+		local tag="${raw_tag#v}"
-    [[ $tag =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+\.[0-9]+)?$ ]] || continue
+		[[ $tag =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+\.[0-9]+)?$ ]] || continue
 
-    if [[ -z $highest_tag ]]; then
+		if [[ -z $highest_tag ]]; then
-      highest_tag="$tag"
+			highest_tag="$tag"
-      continue
+			continue
-    fi
+		fi
 
-    local cmp_status=0
+		local cmp_status=0
-    version_cmp "$tag" "$highest_tag" || cmp_status=$?
+		version_cmp "$tag" "$highest_tag" || cmp_status=$?
-    [[ $cmp_status -eq 1 ]] && highest_tag="$tag"
+		[[ $cmp_status -eq 1 ]] && highest_tag="$tag"
-  done < <(git tag --list)
+	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"
+	parse_full_version "$highest_tag"
-  local channel_to_write="$CHANNEL"
+	local channel_to_write="$CHANNEL"
-  local n_to_write="${PRERELEASE_NUM:-1}"
+	local n_to_write="${PRERELEASE_NUM:-1}"
-  if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
+	if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
-    channel_to_write="stable"
+		channel_to_write="stable"
-    n_to_write="0"
+		n_to_write="0"
-  fi
+	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"
+	log "Initialized $ROOT_DIR/VERSION from highest tag: v$highest_tag"
 }
 
 do_read_version() {
-  local base_line channel_line n_line
+	local base_line channel_line n_line
-  base_line="$(sed -n '1p' "$ROOT_DIR/VERSION" | tr -d '\r')"
+	base_line="$(sed -n '1p' "$ROOT_DIR/VERSION" | tr -d '\r')"
-  channel_line="$(sed -n '2p' "$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')"
+	n_line="$(sed -n '3p' "$ROOT_DIR/VERSION" | tr -d '\r')"
 
-  if [[ -z $channel_line || $channel_line == "stable" ]]; then
+	if [[ -z $channel_line || $channel_line == "stable" ]]; then
-    printf '%s\n' "$base_line"
+		printf '%s\n' "$base_line"
-  else
+	else
-    printf '%s-%s.%s\n' "$base_line" "$channel_line" "$n_line"
+		printf '%s-%s.%s\n' "$base_line" "$channel_line" "$n_line"
-  fi
+	fi
 }
 
 do_write_version() {
-  local channel_to_write="$CHANNEL"
+	local channel_to_write="$CHANNEL"
-  local n_to_write="${PRERELEASE_NUM:-1}"
+	local n_to_write="${PRERELEASE_NUM:-1}"
-  if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
+	if [[ $channel_to_write == "stable" || -z $channel_to_write ]]; then
-    channel_to_write="stable"
+		channel_to_write="stable"
-    n_to_write="0"
+		n_to_write="0"
-  fi
+	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 ─────────────────────────────────────────────────────
 
 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
+	require_clean_git
-  START_HEAD="$(git rev-parse HEAD)"
+	START_HEAD="$(git rev-parse HEAD)"
-  trap revert_on_failure ERR
+	trap revert_on_failure ERR
 
-  # Initialize VERSION file outside any subshell so log lines never
+	# Initialize VERSION file outside any subshell so log lines never
-  # bleed into the stdout capture below.
+	# bleed into the stdout capture below.
-  init_version_file
+	init_version_file
 
-  local 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)"
+	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
+	if [[ -z $raw_version ]]; then
-    echo "Error: could not determine current version from VERSION source" >&2
+		echo "Error: could not determine current version from VERSION source" >&2
-    exit 1
+		exit 1
-  fi
+	fi
-  parse_full_version "$raw_version"
+	parse_full_version "$raw_version"
 
-  log "Current: base=$BASE_VERSION channel=$CHANNEL pre=${PRERELEASE_NUM:-}"
+	log "Current: base=$BASE_VERSION channel=$CHANNEL pre=${PRERELEASE_NUM:-}"
 
-  local action="${1-}"
+	local action="${1-}"
-  shift || true
+	shift || true
 
-  if [[ $action == "set" ]]; then
+	if [[ $action == "set" ]]; then
-    local newv="${1-}"
+		local newv="${1-}"
-    [[ -z $newv ]] && echo "Error: 'set' requires a version argument" >&2 && exit 1
+		[[ -z $newv ]] && echo "Error: 'set' requires a version argument" >&2 && exit 1
-    compute_full_version
+		compute_full_version
-    local current_full="$FULL_VERSION"
+		local current_full="$FULL_VERSION"
-    parse_full_version "$newv"
+		parse_full_version "$newv"
-    validate_channel "$CHANNEL"
+		validate_channel "$CHANNEL"
-    compute_full_version
+		compute_full_version
-    local cmp_status=0
+		local cmp_status=0
-    version_cmp "$FULL_VERSION" "$current_full" || cmp_status=$?
+		version_cmp "$FULL_VERSION" "$current_full" || cmp_status=$?
-    case $cmp_status in
+		case $cmp_status in
-    0)
+		0)
-      echo "Version $FULL_VERSION is already current; nothing to do." >&2
+			echo "Version $FULL_VERSION is already current; nothing to do." >&2
-      exit 1
+			exit 1
-      ;;
+			;;
-    2)
+		2)
-      echo "Error: $FULL_VERSION is lower than current $current_full" >&2
+			echo "Error: $FULL_VERSION is lower than current $current_full" >&2
-      exit 1
+			exit 1
-      ;;
+			;;
-    esac
+		esac
 
-  else
+	else
-    local part="" target_channel=""
+		local part="" target_channel=""
 
-    case "$action" in
+		case "$action" in
-    "") part="patch" ;;
+		"") part="patch" ;;
-    major | minor | patch)
+		major | minor | patch)
-      part="$action"
+			part="$action"
-      target_channel="${1-}"
+			target_channel="${1-}"
-      ;;
+			;;
-    stable | full)
+		stable | full)
-      [[ -n ${1-} ]] && echo "Error: '$action' takes no second argument" >&2 && usage && exit 1
+			[[ -n ${1-} ]] && echo "Error: '$action' takes no second argument" >&2 && usage && exit 1
-      target_channel="stable"
+			target_channel="stable"
-      ;;
+			;;
-    *)
+		*)
-      # check if action is a valid channel
+			# check if action is a valid channel
-      local is_channel=0
+			local is_channel=0
-      for c in __CHANNEL_LIST__; do
+			for c in __CHANNEL_LIST__; do
-        [[ $action == "$c" ]] && is_channel=1 && break
+				[[ $action == "$c" ]] && is_channel=1 && break
-      done
+			done
-      if [[ $is_channel == 1 ]]; then
+			if [[ $is_channel == 1 ]]; then
-        [[ -n ${1-} ]] && echo "Error: channel-only bump takes no second argument" >&2 && usage && exit 1
+				[[ -n ${1-} ]] && echo "Error: channel-only bump takes no second argument" >&2 && usage && exit 1
-        target_channel="$action"
+				target_channel="$action"
-      else
+			else
-        echo "Error: unknown argument '$action'" >&2
+				echo "Error: unknown argument '$action'" >&2
-        usage
+				usage
-        exit 1
+				exit 1
-      fi
+			fi
-      ;;
+			;;
-    esac
+		esac
 
-    [[ -z $target_channel ]] && target_channel="$CHANNEL"
+		[[ -z $target_channel ]] && target_channel="$CHANNEL"
-    [[ $target_channel == "full" ]] && target_channel="stable"
+		[[ $target_channel == "full" ]] && target_channel="stable"
-    validate_channel "$target_channel"
+		validate_channel "$target_channel"
 
-    local old_base="$BASE_VERSION" old_channel="$CHANNEL" old_pre="$PRERELEASE_NUM"
+		local old_base="$BASE_VERSION" old_channel="$CHANNEL" old_pre="$PRERELEASE_NUM"
-    [[ -n $part ]] && bump_base_version "$part"
+		[[ -n $part ]] && bump_base_version "$part"
 
-    if [[ $target_channel == "stable" ]]; then
+		if [[ $target_channel == "stable" ]]; then
-      CHANNEL="stable"
+			CHANNEL="stable"
-      PRERELEASE_NUM=""
+			PRERELEASE_NUM=""
-    else
+		else
-      if [[ $BASE_VERSION == "$old_base" && $target_channel == "$old_channel" && -n $old_pre ]]; then
+			if [[ $BASE_VERSION == "$old_base" && $target_channel == "$old_channel" && -n $old_pre ]]; then
-        PRERELEASE_NUM=$((old_pre + 1))
+				PRERELEASE_NUM=$((old_pre + 1))
-      else
+			else
-        PRERELEASE_NUM=1
+				PRERELEASE_NUM=1
-      fi
+			fi
-      CHANNEL="$target_channel"
+			CHANNEL="$target_channel"
-    fi
+		fi
-  fi
+	fi
 
-  compute_full_version
+	compute_full_version
-  log "Releasing $FULL_VERSION"
+	log "Releasing $FULL_VERSION"
 
-  do_write_version
+	do_write_version
-  log "Updated version source"
+	log "Updated version source"
 
-  generate_version_files
+	run_release_steps
+	log "Release steps done"
 
-  do_post_version
+	do_post_version
-  log "Post-version hook done"
+	log "Post-version hook done"
 
-  (cd "$ROOT_DIR" && nix fmt)
+	(cd "$ROOT_DIR" && nix fmt)
-  log "Formatted files"
+	log "Formatted files"
 
-  git add -A
+	git add -A
-  local commit_msg="chore(release): v$FULL_VERSION"
+	local commit_msg="chore(release): v$FULL_VERSION"
-  validate_commit_message "$commit_msg"
+	validate_commit_message "$commit_msg"
-  git commit -m "$commit_msg"
+	git commit -m "$commit_msg"
-  log "Created commit"
+	log "Created commit"
 
-  git tag "v$FULL_VERSION"
+	git tag "$FULL_TAG"
-  CREATED_TAG="v$FULL_VERSION"
+	CREATED_TAG="$FULL_TAG"
-  log "Tagged v$FULL_VERSION"
+	log "Tagged $FULL_TAG"
 
-  git push
+	git push
-  git push --tags
+	git push --tags
-  log "Done — released v$FULL_VERSION"
+	log "Done — released $FULL_TAG"
 
-  trap - ERR
+	trap - ERR
 }
 
 main "$@"

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.2";
     devshell-lib.inputs.nixpkgs.follows = "nixpkgs";
   };
 
@@ -96,5 +96,50 @@
       );
 
       formatter = forAllSystems (system: (devshell-lib.lib.mkDevShell { inherit system; }).formatter);
+
+      # Optional: 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
+      #
+      # 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"
+      #       '';
+      #     };
+      #   }
+      # );
     };
 }