kitfly 0.1.2

package/scripts/generate-checksums.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Generate SHA256SUMS and SHA512SUMS for release artifacts
+#
+# Usage: generate-checksums.sh [dir] <binary_name>
+#
+# Checksums:
+# - npm tarball (if present)
+# - source archives (if present)
+# - platform binaries (bun build --compile output)
+
+DIR=${1:-dist/release}
+BINARY_NAME=${2:-}
+
+if [ -z "${BINARY_NAME}" ]; then
+    echo "usage: $0 [dir] <binary_name>" >&2
+    exit 1
+fi
+
+if [ ! -d "${DIR}" ]; then
+    echo "error: directory ${DIR} not found" >&2
+    exit 1
+fi
+
+cd "${DIR}"
+
+rm -f SHA256SUMS SHA256SUMS.* SHA512SUMS SHA512SUMS.*
+
+# Find release artifacts
+artifacts=()
+
+# npm tarball pattern
+for f in "${BINARY_NAME}-"*.tgz; do
+    [ -f "$f" ] && artifacts+=("$f")
+done
+
+# Source archive patterns
+for f in "${BINARY_NAME}-"*.tar.gz "${BINARY_NAME}-"*.zip; do
+    [ -f "$f" ] && artifacts+=("$f")
+done
+
+# Platform binary patterns (bun build --compile output)
+for f in "${BINARY_NAME}-"*; do
+    # Skip archives already handled above
+    case "$f" in *.tgz|*.tar.gz|*.zip) continue ;; esac
+    # Skip checksum/signature files
+    case "$f" in SHA*|*.sig|*.minisig|*.asc) continue ;; esac
+    [ -f "$f" ] && artifacts+=("$f")
+done
+
+if [ ${#artifacts[@]} -eq 0 ]; then
+    echo "error: no artifacts found matching ${BINARY_NAME}-* in ${DIR}" >&2
+    echo "Expected: npm tarball (*.tgz), source archive (*.tar.gz, *.zip), or platform bundles" >&2
+    exit 1
+fi
+
+echo "Generating checksums for ${#artifacts[@]} artifact(s)..."
+
+if command -v sha256sum > /dev/null 2>&1; then
+    sha256sum "${artifacts[@]}" > SHA256SUMS
+else
+    shasum -a 256 "${artifacts[@]}" > SHA256SUMS
+fi
+
+if command -v sha512sum > /dev/null 2>&1; then
+    sha512sum "${artifacts[@]}" > SHA512SUMS
+else
+    shasum -a 512 "${artifacts[@]}" > SHA512SUMS
+fi
+
+echo "Wrote SHA256SUMS and SHA512SUMS"
+echo ""
+echo "Artifacts checksummed:"
+for f in "${artifacts[@]}"; do
+    echo "  - $f"
+done

package/scripts/release/export-release-key.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Export PGP public key for release signing verification
+#
+# Usage: export-release-key.sh <key-id> [dest_dir]
+#
+# Environment variables:
+#   KITFLY_GPG_HOMEDIR - Custom GPG homedir (optional, defaults to ~/.gnupg)
+
+KEY_ID=${1:?"usage: export-release-key.sh <key-id> [dest_dir]"}
+DIR=${2:-dist/release}
+KITFLY_GPG_HOMEDIR=${KITFLY_GPG_HOMEDIR:-}
+
+if ! command -v gpg >/dev/null 2>&1; then
+    echo "gpg is required" >&2
+    exit 1
+fi
+mkdir -p "$DIR"
+OUTPUT="$DIR/kitfly-release-signing-key.asc"
+
+if [ -n "$KITFLY_GPG_HOMEDIR" ]; then
+    env GNUPGHOME="$KITFLY_GPG_HOMEDIR" gpg --armor --export "$KEY_ID" >"$OUTPUT"
+else
+    gpg --armor --export "$KEY_ID" >"$OUTPUT"
+fi
+
+echo "[ok] Exported $KEY_ID to $OUTPUT"

package/scripts/release/release-guard-tag-version.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Release guard: ensure git tag matches VERSION file
+#
+# Environment variables:
+#   KITFLY_RELEASE_TAG  - Override tag to check (e.g., v0.1.2)
+#   KITFLY_REQUIRE_TAG  - Set to 1 to enforce tag presence in CI
+#
+# Usage:
+#   ./scripts/release/release-guard-tag-version.sh
+#   KITFLY_RELEASE_TAG=v0.1.2 ./scripts/release/release-guard-tag-version.sh
+#   KITFLY_REQUIRE_TAG=1 ./scripts/release/release-guard-tag-version.sh
+
+repo_root() {
+	git rev-parse --show-toplevel
+}
+
+read_version() {
+	if [ ! -f VERSION ]; then
+		echo "error: VERSION file not found" >&2
+		exit 1
+	fi
+	tr -d ' \t\r\n' <VERSION
+}
+
+normalize_tag() {
+	local raw="${1:-}"
+	if [ -z "$raw" ]; then
+		printf '%s' ""
+		return 0
+	fi
+	if [[ "$raw" == v* ]]; then
+		printf '%s' "$raw"
+	else
+		printf 'v%s' "$raw"
+	fi
+}
+
+detect_tag() {
+	if [ -n "${KITFLY_RELEASE_TAG:-}" ]; then
+		normalize_tag "${KITFLY_RELEASE_TAG}"
+		return 0
+	fi
+	git describe --tags --exact-match 2>/dev/null || true
+}
+
+main() {
+	local root
+	root="$(repo_root)"
+	cd "$root"
+
+	local version
+	version="$(read_version)"
+
+	local expected="v${version}"
+	local tag
+	tag="$(detect_tag)"
+
+	if [ -z "$tag" ]; then
+		if [ "${KITFLY_REQUIRE_TAG:-}" = "1" ]; then
+			echo "error: no exact tag found for HEAD and no KITFLY_RELEASE_TAG provided" >&2
+			exit 1
+		fi
+		echo "→ release guard: no tag detected (set KITFLY_REQUIRE_TAG=1 to enforce in CI)"
+		exit 0
+	fi
+
+	if [ "$tag" != "$expected" ]; then
+		echo "error: release tag/version mismatch" >&2
+		echo "  tag:     $tag" >&2
+		echo "  VERSION: $version (expected tag: $expected)" >&2
+		exit 1
+	fi
+
+	echo "✅ release guard: tag matches VERSION ($tag)"
+}
+
+main "$@"

package/scripts/release/sign-release-assets.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Dual-format release signing: minisign (.minisig) + PGP (.asc)
+#
+# Usage: sign-release-assets.sh <tag> [dir]
+#
+# Environment variables:
+#   KITFLY_MINISIGN_KEY - Path to minisign secret key file. Primary format.
+#   KITFLY_PGP_KEY_ID   - GPG key ID for PGP signing. Optional secondary format.
+#   KITFLY_GPG_HOMEDIR  - Custom GPG homedir (optional, defaults to ~/.gnupg)
+#
+# Minisign was chosen over raw ed25519 because:
+# - Created by Frank Denis (libsodium author), well-audited
+# - Trusted comments provide signed metadata (version, timestamp)
+# - Password-protected keys by default
+# - Compatible with OpenBSD signify
+#
+# Only SHA256SUMS is signed (not individual files). This is the standard pattern:
+# verify signature on checksum file, then verify file checksums against that.
+# This means one password prompt instead of N.
+
+TAG=${1:?"usage: sign-release-assets.sh <tag> [dir]"}
+DIR=${2:-dist/release}
+
+KITFLY_MINISIGN_KEY=${KITFLY_MINISIGN_KEY:-}
+KITFLY_PGP_KEY_ID=${KITFLY_PGP_KEY_ID:-}
+KITFLY_GPG_HOMEDIR=${KITFLY_GPG_HOMEDIR:-}
+
+# Validation
+if [ ! -d "$DIR" ]; then
+    echo "error: directory $DIR not found" >&2
+    exit 1
+fi
+
+checksum_files=()
+for file in SHA256SUMS SHA512SUMS; do
+    if [ -f "$DIR/$file" ]; then
+        checksum_files+=("$file")
+    fi
+done
+
+if [ ${#checksum_files[@]} -eq 0 ]; then
+    echo "error: no checksum files found (run make release-checksums first)" >&2
+    exit 1
+fi
+
+has_minisign=false
+has_pgp=false
+
+if [ -n "$KITFLY_MINISIGN_KEY" ]; then
+    if [ ! -f "$KITFLY_MINISIGN_KEY" ]; then
+        echo "error: KITFLY_MINISIGN_KEY=$KITFLY_MINISIGN_KEY not found" >&2
+        exit 1
+    fi
+    if ! command -v minisign >/dev/null 2>&1; then
+        echo "error: minisign not found in PATH" >&2
+        echo "  Install: brew install minisign (macOS) or see https://jedisct1.github.io/minisign/" >&2
+        exit 1
+    fi
+    has_minisign=true
+    echo "minisign signing enabled (key: $KITFLY_MINISIGN_KEY)"
+fi
+
+# Only enable PGP if explicitly requested via KITFLY_PGP_KEY_ID
+if [ -n "$KITFLY_PGP_KEY_ID" ]; then
+    if ! command -v gpg >/dev/null 2>&1; then
+        echo "error: KITFLY_PGP_KEY_ID set but gpg not found in PATH" >&2
+        exit 1
+    fi
+    has_pgp=true
+    echo "PGP signing enabled (key: $KITFLY_PGP_KEY_ID)"
+    if [ -n "$KITFLY_GPG_HOMEDIR" ]; then
+        echo "GPG homedir: $KITFLY_GPG_HOMEDIR"
+    fi
+fi
+
+if [ "$has_minisign" = false ] && [ "$has_pgp" = false ]; then
+    echo "error: no signing method available" >&2
+    echo "  Set KITFLY_MINISIGN_KEY for minisign signing" >&2
+    echo "  Set KITFLY_PGP_KEY_ID for PGP signing" >&2
+    exit 1
+fi
+
+# Sign checksum manifests (preferred workflow)
+# Users verify: 1) signature on checksum file, 2) file checksums against it
+#
+# Signing is grouped by tool (all minisign first, then all PGP) to minimize
+# password prompt switching during manual signing workflows.
+
+if [ "$has_minisign" = true ]; then
+    echo ""
+    echo "=== Minisign signatures ==="
+    for file in "${checksum_files[@]}"; do
+        echo "[minisign] Signing $file"
+        rm -f "$DIR/$file.minisig"
+        minisign -S -s "$KITFLY_MINISIGN_KEY" -t "kitfly $TAG $(date -u +%Y-%m-%dT%H:%M:%SZ)" -m "$DIR/$file"
+    done
+fi
+
+if [ "$has_pgp" = true ]; then
+    echo ""
+    echo "=== PGP signatures ==="
+    for file in "${checksum_files[@]}"; do
+        echo "[PGP] Signing $file"
+        if [ -n "$KITFLY_GPG_HOMEDIR" ]; then
+            env GNUPGHOME="$KITFLY_GPG_HOMEDIR" gpg --batch --yes --armor --local-user "$KITFLY_PGP_KEY_ID" --detach-sign -o "$DIR/$file.asc" "$DIR/$file"
+        else
+            gpg --batch --yes --armor --local-user "$KITFLY_PGP_KEY_ID" --detach-sign -o "$DIR/$file.asc" "$DIR/$file"
+        fi
+    done
+fi
+
+echo ""
+echo "[ok] Signing complete for $TAG"
+for file in "${checksum_files[@]}"; do
+    if [ "$has_minisign" = true ]; then
+        echo "   $file.minisig"
+    fi
+    if [ "$has_pgp" = true ]; then
+        echo "   $file.asc"
+    fi
+done

package/scripts/release/upload-release-assets.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Upload ALL release assets (binaries, tarballs, and provenance) to GitHub.
+#
+# CAUTION: Only use when a release was built locally and all assets need
+# transfer. Each file is a separate API call — uploading many assets in
+# rapid succession can trigger GitHub's secondary rate limits (HTTP 429).
+#
+# For the normal workflow use upload-release-provenance.sh instead — CI
+# uploads binaries and tarballs, provenance-only upload keeps API calls minimal.
+#
+# Usage: upload-release-assets.sh <tag> [dir]
+
+TAG=${1:?"usage: upload-release-assets.sh <tag> [dir]"}
+DIR=${2:-dist/release}
+
+if ! command -v gh >/dev/null 2>&1; then
+    echo "gh CLI is required" >&2
+    exit 1
+fi
+
+if [ ! -d "$DIR" ]; then
+    echo "directory $DIR not found" >&2
+    exit 1
+fi
+
+# Collect all release assets into a single upload
+shopt -s nullglob
+
+assets=()
+
+# Platform binaries (kitfly-linux-amd64, kitfly-windows-amd64.exe, etc.)
+for f in "$DIR"/kitfly-*; do
+    # Skip npm tarballs, checksums, signatures, keys — handled below
+    case "$f" in *.tgz|SHA*|*.sig|*.minisig|*.asc|*.pub|*.md) continue ;; esac
+    [ -f "$f" ] && assets+=("$f")
+done
+
+# Tarballs and checksums
+assets+=("$DIR"/*.tgz)
+assets+=("$DIR"/SHA256SUMS "$DIR"/SHA512SUMS)
+
+# Signatures
+assets+=("$DIR"/SHA256SUMS.* "$DIR"/SHA512SUMS.*)
+
+# Public keys
+assets+=("$DIR"/*-minisign.pub "$DIR"/*-signing-key.asc)
+
+# Release notes
+assets+=("$DIR"/release-notes-*.md)
+
+# Filter to existing files
+final_assets=()
+for f in "${assets[@]}"; do
+    if [ -f "$f" ]; then
+        final_assets+=("$f")
+    fi
+done
+
+if [ ${#final_assets[@]} -eq 0 ]; then
+    echo "no assets found to upload from $DIR" >&2
+    exit 1
+fi
+
+echo "[..] Uploading ${#final_assets[@]} asset(s) to ${TAG} (clobber)"
+gh release upload "$TAG" "${final_assets[@]}" --clobber
+
+# Update release body with notes if present
+NOTES_FILE="$DIR/release-notes-${TAG}.md"
+if [ -f "$NOTES_FILE" ]; then
+    echo "[..] Updating release body from $NOTES_FILE"
+    gh release edit "$TAG" --notes-file "$NOTES_FILE"
+fi
+
+echo "[ok] Release assets uploaded for $TAG"

package/scripts/release/upload-release-provenance.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Upload only provenance assets (checksums, signatures, keys, notes) to a
+# GitHub release. Does NOT upload binaries or tarballs — CI handles those.
+#
+# Usage: upload-release-provenance.sh <tag> [dir]
+
+TAG="${1:?"usage: upload-release-provenance.sh <tag> [dir]"}"
+DIR="${2:-dist/release}"
+
+if ! command -v gh >/dev/null 2>&1; then
+    echo "gh CLI is required" >&2
+    exit 1
+fi
+
+if [ ! -d "$DIR" ]; then
+    echo "directory $DIR not found" >&2
+    exit 1
+fi
+
+shopt -s nullglob
+
+assets=()
+assets+=("$DIR"/SHA256SUMS "$DIR"/SHA512SUMS)
+assets+=("$DIR"/SHA256SUMS.* "$DIR"/SHA512SUMS.*)
+assets+=("$DIR"/*-minisign.pub "$DIR"/*-signing-key.asc)
+assets+=("$DIR"/release-notes-*.md)
+
+final_assets=()
+for f in "${assets[@]}"; do
+    if [ -f "$f" ]; then
+        final_assets+=("$f")
+    fi
+done
+
+if [ ${#final_assets[@]} -eq 0 ]; then
+    echo "no provenance assets found to upload from $DIR" >&2
+    exit 1
+fi
+
+echo "[..] Uploading ${#final_assets[@]} provenance asset(s) to ${TAG} (clobber)"
+gh release upload "$TAG" "${final_assets[@]}" --clobber
+
+# Update release body with notes if present
+NOTES_FILE="$DIR/release-notes-${TAG}.md"
+if [ -f "$NOTES_FILE" ]; then
+    echo "[..] Updating release body from $NOTES_FILE"
+    gh release edit "$TAG" --notes-file "$NOTES_FILE"
+fi
+
+echo "[ok] Provenance assets uploaded for $TAG"

package/scripts/release/verify-public-key.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Verify that an exported GPG key file contains only public key material
+#
+# Usage: verify-public-key.sh <keyfile>
+#
+# This is a safety check before uploading keys to ensure we never
+# accidentally publish secret key material.
+
+KEY_FILE=${1:?"usage: verify-public-key.sh <keyfile>"}
+
+if [ ! -f "$KEY_FILE" ]; then
+    echo "error: file $KEY_FILE not found" >&2
+    exit 1
+fi
+
+if ! command -v gpg >/dev/null 2>&1; then
+    echo "gpg is required" >&2
+    exit 1
+fi
+
+# Check if file contains "BEGIN PGP PRIVATE KEY" or similar
+if grep -q "PRIVATE KEY" "$KEY_FILE"; then
+    echo "[!!] DANGER: $KEY_FILE appears to contain private key material!" >&2
+    echo "[!!] DO NOT upload this file!" >&2
+    exit 1
+fi
+
+# Verify it's a valid public key
+if ! gpg --show-keys "$KEY_FILE" >/dev/null 2>&1; then
+    echo "[!!] $KEY_FILE is not a valid GPG key file" >&2
+    exit 1
+fi
+
+# Check that gpg reports it as public only
+KEY_INFO=$(gpg --show-keys --with-colons "$KEY_FILE" 2>/dev/null)
+if echo "$KEY_INFO" | grep -q "^sec:"; then
+    echo "[!!] DANGER: $KEY_FILE contains secret key material!" >&2
+    exit 1
+fi
+
+if ! echo "$KEY_INFO" | grep -q "^pub:"; then
+    echo "[!!] $KEY_FILE does not contain a public key" >&2
+    exit 1
+fi
+
+echo "[ok] $KEY_FILE is a valid public-only GPG key"

package/scripts/release/verify-signatures.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Verify release signatures (minisign and optional PGP) on checksum manifests.
+#
+# Usage: verify-signatures.sh [dir]
+#
+# Environment variables:
+#   KITFLY_MINISIGN_PUB - path to minisign public key (required for minisign)
+#   KITFLY_GPG_HOMEDIR  - isolated gpg homedir for PGP verification (optional)
+
+DIR=${1:-dist/release}
+
+if [ ! -d "$DIR" ]; then
+    echo "error: directory $DIR not found" >&2
+    exit 1
+fi
+
+KITFLY_MINISIGN_PUB=${KITFLY_MINISIGN_PUB:-}
+KITFLY_GPG_HOMEDIR=${KITFLY_GPG_HOMEDIR:-}
+
+verified=0
+failed=0
+
+verify_minisign() {
+    local manifest="$1"
+    local base="${DIR}/${manifest}"
+    local sig="${base}.minisig"
+
+    if [ ! -f "${sig}" ]; then
+        echo "[--] No minisign signature for ${manifest} (skipping)"
+        return 0
+    fi
+
+    if [ -z "${KITFLY_MINISIGN_PUB}" ]; then
+        echo "[!!] KITFLY_MINISIGN_PUB not set, cannot verify ${manifest}.minisig"
+        failed=$((failed + 1))
+        return 1
+    fi
+
+    if [ ! -f "${KITFLY_MINISIGN_PUB}" ]; then
+        echo "error: KITFLY_MINISIGN_PUB=${KITFLY_MINISIGN_PUB} not found" >&2
+        failed=$((failed + 1))
+        return 1
+    fi
+
+    if ! command -v minisign >/dev/null 2>&1; then
+        echo "error: minisign not found in PATH" >&2
+        failed=$((failed + 1))
+        return 1
+    fi
+
+    echo "[..] [minisign] Verifying ${manifest}"
+    if minisign -V -p "${KITFLY_MINISIGN_PUB}" -m "${base}"; then
+        echo "[ok] ${manifest}.minisig verified"
+        verified=$((verified + 1))
+    else
+        echo "[!!] ${manifest}.minisig verification FAILED"
+        failed=$((failed + 1))
+    fi
+}
+
+verify_pgp() {
+    local manifest="$1"
+    local base="${DIR}/${manifest}"
+    local sig="${base}.asc"
+
+    if [ ! -f "${sig}" ]; then
+        echo "[--] No PGP signature for ${manifest} (skipping)"
+        return 0
+    fi
+
+    if ! command -v gpg >/dev/null 2>&1; then
+        echo "[!!] gpg not found, cannot verify ${manifest}.asc"
+        failed=$((failed + 1))
+        return 1
+    fi
+
+    echo "[..] [PGP] Verifying ${manifest}"
+    local rc=0
+    if [ -n "${KITFLY_GPG_HOMEDIR}" ] && [ -d "${KITFLY_GPG_HOMEDIR}" ]; then
+        env GNUPGHOME="${KITFLY_GPG_HOMEDIR}" gpg --verify "${sig}" "${base}" 2>&1 || rc=$?
+    else
+        gpg --verify "${sig}" "${base}" 2>&1 || rc=$?
+    fi
+
+    if [ $rc -eq 0 ]; then
+        echo "[ok] ${manifest}.asc verified"
+        verified=$((verified + 1))
+    else
+        echo "[!!] ${manifest}.asc verification FAILED"
+        failed=$((failed + 1))
+    fi
+}
+
+echo "Verifying release signatures in ${DIR}..."
+echo ""
+
+verify_minisign "SHA256SUMS"
+verify_minisign "SHA512SUMS"
+
+echo ""
+
+verify_pgp "SHA256SUMS"
+verify_pgp "SHA512SUMS"
+
+echo ""
+echo "----------------------------------------------------------------------"
+if [ $failed -gt 0 ]; then
+    echo "[!!] Signature verification: ${verified} passed, ${failed} FAILED"
+    exit 1
+elif [ $verified -eq 0 ]; then
+    echo "[!!] No signatures found to verify"
+    exit 1
+else
+    echo "[ok] Signature verification: ${verified} passed"
+fi

package/scripts/version-sync.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+/**
+ * version-sync.ts - Sync VERSION file to package.json
+ *
+ * VERSION file is the Single Source of Truth (SSOT) for kitfly versioning.
+ * This script propagates the version to package.json.
+ *
+ * Usage:
+ *   bun run scripts/version-sync.ts           # Sync and display result
+ *   bun run scripts/version-sync.ts --check   # Verify they match (CI)
+ *   bun run scripts/version-sync.ts --set X.Y.Z  # Set VERSION and sync
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dir, "..");
+const VERSION_PATH = join(ROOT, "VERSION");
+const PACKAGE_PATH = join(ROOT, "package.json");
+
+function getVersionFromFile(): string {
+	return readFileSync(VERSION_PATH, "utf-8").trim();
+}
+
+function getPackageVersion(): string {
+	const pkg = JSON.parse(readFileSync(PACKAGE_PATH, "utf-8"));
+	return pkg.version;
+}
+
+function setVersionFile(version: string): void {
+	writeFileSync(VERSION_PATH, `${version}\n`);
+}
+
+function syncPackageJson(version: string): void {
+	const pkg = JSON.parse(readFileSync(PACKAGE_PATH, "utf-8"));
+	pkg.version = version;
+	writeFileSync(PACKAGE_PATH, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+function main() {
+	const args = process.argv.slice(2);
+
+	// --check: Verify versions match (for CI)
+	if (args.includes("--check")) {
+		const fileVersion = getVersionFromFile();
+		const pkgVersion = getPackageVersion();
+		if (fileVersion !== pkgVersion) {
+			console.error(`Version mismatch: VERSION=${fileVersion}, package.json=${pkgVersion}`);
+			console.error("Run: bun run scripts/version-sync.ts");
+			process.exit(1);
+		}
+		console.log(`Versions match: ${fileVersion}`);
+		process.exit(0);
+	}
+
+	// --set X.Y.Z: Set VERSION file and sync
+	const setIndex = args.indexOf("--set");
+	if (setIndex !== -1) {
+		const newVersion = args[setIndex + 1];
+		if (!newVersion || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(newVersion)) {
+			console.error("Usage: bun run scripts/version-sync.ts --set X.Y.Z");
+			process.exit(1);
+		}
+		setVersionFile(newVersion);
+		syncPackageJson(newVersion);
+		console.log(`Version set to ${newVersion}`);
+		process.exit(0);
+	}
+
+	// Default: Sync VERSION → package.json
+	const version = getVersionFromFile();
+	const pkgVersion = getPackageVersion();
+
+	if (version === pkgVersion) {
+		console.log(`Already in sync: ${version}`);
+	} else {
+		syncPackageJson(version);
+		console.log(`Synced package.json: ${pkgVersion} → ${version}`);
+	}
+}
+
+main();