@shetty4l/core 0.1.3

package/.github/workflows/ci-shared.yml

@@ -0,0 +1,36 @@
+name: CI (shared)
+
+on:
+  workflow_call:
+    inputs:
+      extra-validate-command:
+        description: "Optional extra command to run after validate (e.g. a full test suite)"
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Validate
+        run: bun run validate
+
+      - name: Extra validation
+        if: ${{ inputs.extra-validate-command != '' }}
+        shell: bash
+        run: ${{ inputs.extra-validate-command }}

package/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    uses: ./.github/workflows/ci-shared.yml

package/.github/workflows/release-shared.yml

@@ -0,0 +1,150 @@
+name: Release (shared)
+
+on:
+  workflow_call:
+    inputs:
+      service-name:
+        description: "Service name for tarball prefix and release title (e.g. engram, synapse)"
+        required: true
+        type: string
+      extra-tarball-paths:
+        description: "Space-separated additional paths to include in tarball (e.g. 'opencode/ scripts/install.sh')"
+        required: false
+        type: string
+        default: ""
+      publish-npm:
+        description: "Whether to publish to GitHub Packages via npm publish"
+        required: false
+        type: boolean
+        default: false
+      attach-install-sh:
+        description: "Whether to attach scripts/install.sh as a release asset"
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Compute next version
+        id: version
+        run: |
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.1.0")
+          echo "latest_tag=${LATEST_TAG}" >> "$GITHUB_OUTPUT"
+
+          VERSION="${LATEST_TAG#v}"
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
+
+          COMMITS_SINCE="$(git log "${LATEST_TAG}..HEAD" --format='%s' 2>/dev/null || echo "")"
+          if echo "$COMMITS_SINCE" | grep -q '\[major\]'; then
+            NEXT_VERSION="$((MAJOR + 1)).0.0"
+            BUMP_LEVEL="major"
+          elif echo "$COMMITS_SINCE" | grep -q '\[minor\]'; then
+            NEXT_VERSION="${MAJOR}.$((MINOR + 1)).0"
+            BUMP_LEVEL="minor"
+          else
+            NEXT_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
+            BUMP_LEVEL="patch"
+          fi
+
+          echo "bump_level=${BUMP_LEVEL}" >> "$GITHUB_OUTPUT"
+          echo "next_version=${NEXT_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "next_tag=v${NEXT_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Releasing: v${NEXT_VERSION} (previous: ${LATEST_TAG}, bump: ${BUMP_LEVEL})"
+
+      - name: Write VERSION file
+        run: echo "${{ steps.version.outputs.next_version }}" > VERSION
+
+      - name: Update package.json version
+        run: |
+          jq --arg v "${{ steps.version.outputs.next_version }}" '.version = $v' package.json > tmp.json
+          mv tmp.json package.json
+
+      - name: Write BUILD_META.json
+        run: |
+          SHA="${{ github.event.workflow_run.head_sha }}"
+          SHORT_SHA="${SHA:0:7}"
+          BRANCH="${{ github.event.workflow_run.head_branch }}"
+          TITLE="$(git log -1 --format='%s' "$SHA")"
+          BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          jq -n \
+            --arg sha "$SHA" \
+            --arg shortSha "$SHORT_SHA" \
+            --arg branch "$BRANCH" \
+            --arg title "$TITLE" \
+            --arg buildTime "$BUILD_TIME" \
+            '{
+              gitSha: $sha,
+              gitShortSha: $shortSha,
+              gitBranch: $branch,
+              commitTitle: $title,
+              buildTimeUtc: $buildTime
+            }' > BUILD_META.json
+
+      - name: Publish to GitHub Packages
+        if: ${{ inputs.publish-npm }}
+        run: |
+          echo "//npm.pkg.github.com/:_authToken=${{ github.token }}" > .npmrc
+          echo "@shetty4l:registry=https://npm.pkg.github.com" >> .npmrc
+          npm publish --access public
+
+      - name: Create source tarball
+        run: |
+          TAG="${{ steps.version.outputs.next_tag }}"
+          EXTRA_PATHS="${{ inputs.extra-tarball-paths }}"
+          tar czf "${{ inputs.service-name }}-${TAG}.tar.gz" \
+            --exclude='node_modules' \
+            --exclude='.git' \
+            --exclude='test' \
+            --exclude='.husky' \
+            --exclude='.DS_Store' \
+            --exclude='dist' \
+            src/ \
+            package.json \
+            bun.lock \
+            tsconfig.json \
+            biome.json \
+            VERSION \
+            BUILD_META.json \
+            $EXTRA_PATHS
+
+      - name: Create tag and release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${{ steps.version.outputs.next_tag }}"
+          ASSETS=("${{ inputs.service-name }}-${TAG}.tar.gz")
+
+          if [ "${{ inputs.attach-install-sh }}" = "true" ] && [ -f "scripts/install.sh" ]; then
+            ASSETS+=("scripts/install.sh")
+          fi
+
+          git tag "${TAG}"
+          git push origin "${TAG}"
+
+          gh release create "${TAG}" \
+            --title "Release ${TAG}" \
+            --notes "Automated release ${TAG}" \
+            "${ASSETS[@]}"

package/.github/workflows/release.yml

@@ -0,0 +1,19 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    uses: ./.github/workflows/release-shared.yml
+    with:
+      service-name: core
+      publish-npm: true

package/.husky/pre-commit

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+bun run validate || exit 1

package/README.md

@@ -0,0 +1,88 @@
+# @shetty4l/core
+
+Shared infrastructure primitives for Bun/TypeScript services. Zero external dependencies.
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `result` | `Result<T, E>` type, `ok`/`err` constructors, `Port` branded type |
+| `version` | Read VERSION file from project root with fallback |
+| `config` | XDG directory resolution, path expansion, env var interpolation, JSON config loading |
+| `cli` | Argument parsing, command dispatch, uptime formatting |
+| `daemon` | PID-file daemon management (start/stop/restart/status) |
+| `http` | Bun.serve wrapper with CORS, health endpoint, JSON response helpers |
+| `signals` | Graceful shutdown handler (SIGINT/SIGTERM) |
+
+## Install
+
+Configure GitHub Packages registry:
+
+```toml
+# bunfig.toml
+[install.scopes]
+"@shetty4l" = "https://npm.pkg.github.com"
+```
+
+Then:
+
+```bash
+bun add @shetty4l/core
+```
+
+## Usage
+
+### Namespace imports (recommended)
+
+```typescript
+import { config, http, cli, daemon, readVersion, onShutdown } from "@shetty4l/core";
+
+const version = readVersion(import.meta.dir);
+const port = config.parsePort(process.env.PORT!, "PORT");
+const cfg = config.loadJsonConfig({ name: "myservice", defaults: { port: 3000 } });
+
+const server = http.createServer({
+  port: 3000,
+  version,
+  onRequest: (req, url) => {
+    if (url.pathname === "/echo") return http.jsonOk({ ok: true });
+    return null; // 404
+  },
+});
+
+onShutdown(() => server.stop());
+```
+
+### Sub-path imports
+
+```typescript
+import { parsePort, loadJsonConfig } from "@shetty4l/core/config";
+import { createServer, jsonOk } from "@shetty4l/core/http";
+import { createDaemonManager } from "@shetty4l/core/daemon";
+```
+
+## Result type
+
+Functions that can fail with expected errors return `Result<T, E>` instead of throwing:
+
+```typescript
+import { config } from "@shetty4l/core";
+
+const result = config.parsePort("abc", "PORT");
+if (!result.ok) {
+  console.error(result.error);
+  process.exit(1);
+}
+// result.value is a branded Port type — validated once, trusted downstream
+```
+
+**Convention:** `Result` for expected failures (invalid input, missing files). `throw` for programmer errors (bugs, invariant violations).
+
+## Development
+
+```bash
+bun install
+bun run validate    # typecheck + lint + format:check + test
+bun run format      # auto-fix formatting
+bun test            # run tests only
+```

package/biome.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": false
+  },
+  "assist": { "actions": { "source": { "organizeImports": "on" } } }
+}

package/bun.lock

@@ -0,0 +1,65 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@shetty4l/core",
+      "devDependencies": {
+        "@biomejs/biome": "^2.3.13",
+        "@types/bun": "latest",
+        "husky": "^9.0.0",
+        "oxlint": "^0.12.0",
+        "typescript": "^5.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.4.2", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.2", "@biomejs/cli-darwin-x64": "2.4.2", "@biomejs/cli-linux-arm64": "2.4.2", "@biomejs/cli-linux-arm64-musl": "2.4.2", "@biomejs/cli-linux-x64": "2.4.2", "@biomejs/cli-linux-x64-musl": "2.4.2", "@biomejs/cli-win32-arm64": "2.4.2", "@biomejs/cli-win32-x64": "2.4.2" }, "bin": { "biome": "bin/biome" } }, "sha512-vVE/FqLxNLbvYnFDYg3Xfrh1UdFhmPT5i+yPT9GE2nTUgI4rkqo5krw5wK19YHBd7aE7J6r91RRmb8RWwkjy6w=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-3pEcKCP/1POKyaZZhXcxFl3+d9njmeAihZ17k8lL/1vk+6e0Cbf0yPzKItFiT+5Yh6TQA4uKvnlqe0oVZwRxCA=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-P7hK1jLVny+0R9UwyGcECxO6sjETxfPyBm/1dmFjnDOHgdDPjPqozByunrwh4xPKld8sxOr5eAsSqal5uKgeBg=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-DI3Mi7GT2zYNgUTDEbSjl3e1KhoP76OjQdm8JpvZYZWtVDRyLd3w8llSr2TWk1z+U3P44kUBWY3X7H9MD1/DGQ=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-/x04YK9+7erw6tYEcJv9WXoBHcULI/wMOvNdAyE9S3JStZZ9yJyV67sWAI+90UHuDo/BDhq0d96LDqGlSVv7WA=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.2", "", { "os": "linux", "cpu": "x64" }, "sha512-GK2ErnrKpWFigYP68cXiCHK4RTL4IUWhK92AFS3U28X/nuAL5+hTuy6hyobc8JZRSt+upXt1nXChK+tuHHx4mA=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.2", "", { "os": "linux", "cpu": "x64" }, "sha512-wbBmTkeAoAYbOQ33f6sfKG7pcRSydQiF+dTYOBjJsnXO2mWEOQHllKlC2YVnedqZFERp2WZhFUoO7TNRwnwEHQ=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-k2uqwLYrNNxnaoiW3RJxoMGnbKda8FuCmtYG3cOtVljs3CzWxaTR+AoXwKGHscC9thax9R4kOrtWqWN0+KdPTw=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.2", "", { "os": "win32", "cpu": "x64" }, "sha512-9ma7C4g8Sq3cBlRJD2yrsHXB1mnnEBdpy7PhvFrylQWQb4PoyCmPucdX7frvsSBQuFtIiKCrolPl/8tCZrKvgQ=="],
+
+    "@oxlint/darwin-arm64": ["@oxlint/darwin-arm64@0.12.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-UydkjcAImpmBn8JYaMPg0zJrwgWJMGvJagvCnyPfyiBRWAN83Kq+BDgJZgIq+2Te6kvlnoiHWNJKVJmpy0f0BA=="],
+
+    "@oxlint/darwin-x64": ["@oxlint/darwin-x64@0.12.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-bxLyiAiHzXB56w7cf50YNPpZlK+PMxA8GgHutRSoNK/Z/BR/xsibNLs/9YNUnjHB+PF19+EbIRtJxoHjmbRr8g=="],
+
+    "@oxlint/linux-arm64-gnu": ["@oxlint/linux-arm64-gnu@0.12.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-jVkmfoMjPKFDIZySmpykwrCmx5xhpLJdMpUAR8ycEkFRJFp5qKLWZd6cEjiMb7gxmWN6qcCvDVTF/zEs3aRpyQ=="],
+
+    "@oxlint/linux-arm64-musl": ["@oxlint/linux-arm64-musl@0.12.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-8VdV1nKYDj7AFaw1a03Ih43/+pUS/hhMZbTFLRMpvlVp1cPtdB77c+bl/OdiJ/BwNTzLIzr/GrospwCoEJkQKg=="],
+
+    "@oxlint/linux-x64-gnu": ["@oxlint/linux-x64-gnu@0.12.0", "", { "os": "linux", "cpu": "x64" }, "sha512-MacAt8N4XU5DeoHcseXLom/z+B0seecCz8vGAH4ppF2EH49o7NbN7VvFsw2nZ2QNO/4vw+pdS1BHXLTr9lY6zQ=="],
+
+    "@oxlint/linux-x64-musl": ["@oxlint/linux-x64-musl@0.12.0", "", { "os": "linux", "cpu": "x64" }, "sha512-/ZBDJ9wpUE6bB05nniQl29kD5vJUMg6n75LdHD8F6ThXfsHGI/n7Je3gzggnXokgf9UQpTUPWrWlfEuWVCBMag=="],
+
+    "@oxlint/win32-arm64": ["@oxlint/win32-arm64@0.12.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-hY1ya9dv8VY8113YSSDfMs/989aFmoA2fIZco8uxTxIEVl9nGY6tDtpgKZqUIiGrrMbDO8BBb1G5jsekmfexbA=="],
+
+    "@oxlint/win32-x64": ["@oxlint/win32-x64@0.12.0", "", { "os": "win32", "cpu": "x64" }, "sha512-NHLJolo4sZk3nu/bPNuaJ+6p5DdHoRuZAjyuSO6CnLgpmZcYqx7LgngA/x2oB/bLgi4Hv9twjHjODc5Ce5o14g=="],
+
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "husky": ["husky@9.1.7", "", { "bin": { "husky": "bin.js" } }, "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA=="],
+
+    "oxlint": ["oxlint@0.12.0", "", { "optionalDependencies": { "@oxlint/darwin-arm64": "0.12.0", "@oxlint/darwin-x64": "0.12.0", "@oxlint/linux-arm64-gnu": "0.12.0", "@oxlint/linux-arm64-musl": "0.12.0", "@oxlint/linux-x64-gnu": "0.12.0", "@oxlint/linux-x64-musl": "0.12.0", "@oxlint/win32-arm64": "0.12.0", "@oxlint/win32-x64": "0.12.0" }, "bin": { "oxlint": "bin/oxlint", "oxc_language_server": "bin/oxc_language_server" } }, "sha512-M0vWq8KYtp4vpweRxcdCiVO8QFwzoRyp5bWTMrEL/0Z+GDKCMJltac7H3T3T09FIiktOZLvID733d7OcKk/caw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@shetty4l/core",
+  "version": "0.1.3",
+  "description": "Shared infrastructure primitives for Bun/TypeScript services",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./result": "./src/result.ts",
+    "./version": "./src/version.ts",
+    "./config": "./src/config.ts",
+    "./signals": "./src/signals.ts",
+    "./cli": "./src/cli.ts",
+    "./daemon": "./src/daemon.ts",
+    "./http": "./src/http.ts"
+  },
+  "bin": {
+    "version-bump": "./src/scripts/version-bump.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src/",
+    "format": "biome check --write src/ test/",
+    "format:check": "biome check src/ test/",
+    "test": "bun test",
+    "validate": "bun run typecheck && bun run lint && bun run format:check && bun run test",
+    "version:bump": "bun run src/scripts/version-bump.ts",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/bun": "latest",
+    "husky": "^9.0.0",
+    "oxlint": "^0.12.0",
+    "typescript": "^5.0.0"
+  }
+}

package/scripts/install-lib.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# install-lib.sh — Shared install functions for shetty4l services.
+#
+# Source this file from a per-service install.sh, then call the functions.
+# Required variables before sourcing:
+#   SERVICE_NAME  — e.g. "engram"
+#   REPO          — e.g. "shetty4l/engram"
+#   INSTALL_BASE  — e.g. "$HOME/srv/engram"
+#
+# Optional variables:
+#   BIN_DIR       — CLI symlink directory (default: $HOME/.local/bin)
+#   MAX_VERSIONS  — versions to keep (default: 5)
+#
+# After sourcing, these variables are set by fetch_latest_release:
+#   RELEASE_TAG   — e.g. "v0.2.3"
+#   TARBALL_URL   — download URL for the release tarball
+
+set -euo pipefail
+
+BIN_DIR="${BIN_DIR:-${HOME}/.local/bin}"
+MAX_VERSIONS="${MAX_VERSIONS:-5}"
+
+# --- color helpers ---
+
+info()  { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
+ok()    { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
+warn()  { printf '\033[1;33m==>\033[0m %s\n' "$*"; }
+err()   { printf '\033[1;31m==>\033[0m %s\n' "$*" >&2; }
+die()   { err "$@"; exit 1; }
+
+# --- prereqs ---
+
+check_prereqs() {
+  local missing=()
+  for cmd in bun curl tar jq; do
+    if ! command -v "$cmd" &>/dev/null; then
+      missing+=("$cmd")
+    fi
+  done
+  if [ ${#missing[@]} -gt 0 ]; then
+    die "Missing required tools: ${missing[*]}"
+  fi
+}
+
+# --- fetch latest release ---
+
+fetch_latest_release() {
+  info "Fetching latest release from GitHub..."
+  local release_json
+  release_json=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest")
+
+  RELEASE_TAG=$(echo "$release_json" | jq -r '.tag_name')
+  TARBALL_URL=$(echo "$release_json" | jq -r ".assets[] | select(.name | startswith(\"${SERVICE_NAME}-\")) | .browser_download_url")
+
+  if [ -z "$RELEASE_TAG" ] || [ "$RELEASE_TAG" = "null" ]; then
+    die "No releases found for ${REPO}"
+  fi
+  if [ -z "$TARBALL_URL" ] || [ "$TARBALL_URL" = "null" ]; then
+    die "No tarball asset found in release ${RELEASE_TAG}"
+  fi
+
+  info "Latest release: ${RELEASE_TAG}"
+}
+
+# --- download and extract ---
+
+download_and_extract() {
+  local version_dir="${INSTALL_BASE}/${RELEASE_TAG}"
+
+  if [ -d "$version_dir" ]; then
+    warn "Version ${RELEASE_TAG} already exists at ${version_dir}, reinstalling..."
+    rm -rf "$version_dir"
+  fi
+
+  mkdir -p "$version_dir"
+
+  info "Downloading ${RELEASE_TAG}..."
+  local tmpfile
+  tmpfile=$(mktemp)
+  curl -fsSL -o "$tmpfile" "$TARBALL_URL"
+
+  info "Extracting to ${version_dir}..."
+  tar xzf "$tmpfile" -C "$version_dir"
+  rm -f "$tmpfile"
+
+  info "Installing dependencies..."
+  (cd "$version_dir" && bun install --frozen-lockfile)
+
+  info "Creating CLI wrapper..."
+  cat > "$version_dir/${SERVICE_NAME}" <<WRAPPER
+#!/usr/bin/env bash
+SCRIPT_DIR="\$(cd "\$(dirname "\$(readlink "\$0" || echo "\$0")")" && pwd)"
+exec bun run "\$SCRIPT_DIR/src/cli.ts" "\$@"
+WRAPPER
+  chmod +x "$version_dir/${SERVICE_NAME}"
+
+  ok "Installed ${RELEASE_TAG} to ${version_dir}"
+}
+
+# --- symlink management (atomic) ---
+
+update_symlink() {
+  local version_dir="${INSTALL_BASE}/${RELEASE_TAG}"
+  local latest_link="${INSTALL_BASE}/latest"
+
+  ln -sfn "$version_dir" "$latest_link"
+  echo "$RELEASE_TAG" > "${INSTALL_BASE}/current-version"
+
+  ok "Symlinked latest -> ${RELEASE_TAG}"
+}
+
+# --- prune old versions ---
+
+prune_versions() {
+  local versions=()
+  for d in "${INSTALL_BASE}"/v*; do
+    [ -d "$d" ] && versions+=("$(basename "$d")")
+  done
+
+  if [ ${#versions[@]} -eq 0 ]; then
+    return
+  fi
+
+  IFS=$'\n' sorted=($(printf '%s\n' "${versions[@]}" | sed 's/^v//' | sort -t. -k1,1n -k2,2n -k3,3n | sed 's/^/v/'))
+  unset IFS
+
+  local count=${#sorted[@]}
+  if [ "$count" -gt "$MAX_VERSIONS" ]; then
+    local remove_count=$((count - MAX_VERSIONS))
+    for ((i = 0; i < remove_count; i++)); do
+      local old_version="${sorted[$i]}"
+      info "Removing old version: ${old_version}"
+      rm -rf "${INSTALL_BASE}/${old_version}"
+    done
+  fi
+}
+
+# --- CLI binary ---
+
+install_cli() {
+  mkdir -p "$BIN_DIR"
+  ln -sf "${INSTALL_BASE}/latest/${SERVICE_NAME}" "${BIN_DIR}/${SERVICE_NAME}"
+  ok "CLI linked: ${BIN_DIR}/${SERVICE_NAME}"
+
+  if [[ ":$PATH:" != *":${BIN_DIR}:"* ]]; then
+    warn "~/.local/bin is not in your PATH. Add it to your shell profile:"
+    warn "  export PATH=\"\$HOME/.local/bin:\$PATH\""
+  fi
+}