seshions 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seshions contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# Seshions
+
+Terminal session orchestrator for running multiple coding agents in parallel.
+
+## What It Does
+
+- Launch and track multiple AI coding sessions in one dashboard
+- Attach/detach quickly with keyboard-first controls
+- Group sessions by workflow
+- Optional git worktree isolation per session
+- Persist session state across restarts via tmux
+
+## Requirements
+
+- Node.js 18+
+- tmux
+- At least one coding tool installed (`claude`, `codex`, `gemini`, `opencode`, or custom shell command)
+
+## Install (One Command)
+
+Run immediately (no global install):
+
+```bash
+npx seshions@latest
+```
+
+Install globally:
+
+```bash
+npm install -g seshions
+seshions
+```
+
+The npm launcher downloads the matching native runtime automatically and caches it in `~/.seshions/runtime`.
+
+## Local Development
+
+```bash
+bun install
+bun run build
+bun run typecheck
+bun test
+```
+
+## Run
+
+```bash
+bun run dist/index.js
+```
+
+## Build Binary
+
+```bash
+bun run compile
+```
+
+## Install Script
+
+Alternative manual installer:
+
+```bash
+export SESHIONS_REPO="danhergir/seshions"
+curl -fsSL "https://raw.githubusercontent.com/${SESHIONS_REPO}/main/install.sh" | bash
+```
+
+## Uninstall
+
+If installed with npm:
+
+```bash
+npm uninstall -g seshions
+```
+
+Remove cached runtime + state data:
+
+```bash
+rm -rf ~/.seshions
+```
+
+If installed with the manual installer:
+
+```bash
+export SESHIONS_REPO="danhergir/seshions"
+curl -fsSL "https://raw.githubusercontent.com/${SESHIONS_REPO}/main/uninstall.sh" | bash
+```
+
+Optional full cleanup (manual installer):
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/${SESHIONS_REPO}/main/uninstall.sh" | bash -s -- --purge-data
+```

package/install.sh

@@ -0,0 +1,312 @@
+#!/usr/bin/env bash
+#
+# Seshions Installer
+# Usage: SESHIONS_REPO=danhergir/seshions curl -fsSL "https://raw.githubusercontent.com/${SESHIONS_REPO}/main/install.sh" | bash
+#
+
+set -euo pipefail
+
+APP=seshions
+REPO="${SESHIONS_REPO:-danhergir/seshions}"
+
+# Colors
+MUTED='\033[0;2m'
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+INSTALL_DIR="${SESHIONS_INSTALL_DIR:-$HOME/.seshions/bin}"
+
+usage() {
+    cat <<EOF
+Seshions Installer
+
+Usage: install.sh [options]
+
+Options:
+    -h, --help              Display this help message
+    -v, --version <version> Install a specific version (e.g., 1.0.0)
+    -b, --binary <path>     Install from a local binary instead of downloading
+        --no-modify-path    Don't modify shell config files
+
+Examples:
+    SESHIONS_REPO=danhergir/seshions curl -fsSL "https://raw.githubusercontent.com/\$SESHIONS_REPO/main/install.sh" | bash
+    SESHIONS_REPO=danhergir/seshions curl -fsSL "https://raw.githubusercontent.com/\$SESHIONS_REPO/main/install.sh" | bash -s -- --version 1.0.0
+    ./install.sh --binary /path/to/seshions
+EOF
+}
+
+requested_version=""
+no_modify_path=false
+binary_path=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        -v|--version)
+            if [[ -n "${2:-}" ]]; then
+                requested_version="$2"
+                shift 2
+            else
+                echo -e "${RED}Error: --version requires a version argument${NC}"
+                exit 1
+            fi
+            ;;
+        -b|--binary)
+            if [[ -n "${2:-}" ]]; then
+                binary_path="$2"
+                shift 2
+            else
+                echo -e "${RED}Error: --binary requires a path argument${NC}"
+                exit 1
+            fi
+            ;;
+        --no-modify-path)
+            no_modify_path=true
+            shift
+            ;;
+        *)
+            echo -e "${RED}Warning: Unknown option '$1'${NC}" >&2
+            shift
+            ;;
+    esac
+done
+
+mkdir -p "$INSTALL_DIR"
+
+# Detect platform
+detect_platform() {
+    local os arch
+
+    case "$(uname -s)" in
+        Darwin) os="darwin" ;;
+        Linux) os="linux" ;;
+        *) echo -e "${RED}Unsupported OS: $(uname -s)${NC}"; exit 1 ;;
+    esac
+
+    case "$(uname -m)" in
+        x86_64|amd64) arch="x64" ;;
+        arm64|aarch64) arch="arm64" ;;
+        *) echo -e "${RED}Unsupported architecture: $(uname -m)${NC}"; exit 1 ;;
+    esac
+
+    echo "${os}-${arch}"
+}
+
+# Check for tmux and offer to install
+check_tmux() {
+    if command -v tmux &> /dev/null; then
+        return 0
+    fi
+
+    echo -e "${MUTED}tmux is not installed.${NC}"
+    echo "Seshions requires tmux to function."
+    echo ""
+
+    local os_type="$(uname -s)"
+
+    if [[ "$os_type" == "Darwin" ]]; then
+        if command -v brew &> /dev/null; then
+            read -p "Install tmux via Homebrew? [Y/n] " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+                echo -e "Installing tmux..."
+                brew install tmux
+            fi
+        else
+            echo "Install tmux with: brew install tmux"
+            echo "(Install Homebrew first: https://brew.sh)"
+        fi
+    else
+        if command -v apt-get &> /dev/null; then
+            read -p "Install tmux via apt? [Y/n] " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+                echo -e "Installing tmux..."
+                sudo apt-get update && sudo apt-get install -y tmux
+            fi
+        elif command -v dnf &> /dev/null; then
+            read -p "Install tmux via dnf? [Y/n] " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+                echo -e "Installing tmux..."
+                sudo dnf install -y tmux
+            fi
+        elif command -v pacman &> /dev/null; then
+            read -p "Install tmux via pacman? [Y/n] " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+                echo -e "Installing tmux..."
+                sudo pacman -S --noconfirm tmux
+            fi
+        else
+            echo "Please install tmux manually:"
+            echo "  sudo apt install tmux    # Debian/Ubuntu"
+            echo "  sudo dnf install tmux    # Fedora"
+            echo "  sudo pacman -S tmux      # Arch"
+        fi
+    fi
+
+    if ! command -v tmux &> /dev/null; then
+        echo ""
+        read -p "tmux not found. Continue anyway? [y/N] " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            exit 1
+        fi
+    else
+        echo -e "${GREEN}tmux installed successfully!${NC}"
+    fi
+}
+
+check_tmux
+
+if [ -n "$binary_path" ]; then
+    if [ ! -f "$binary_path" ]; then
+        echo -e "${RED}Error: Binary not found at ${binary_path}${NC}"
+        exit 1
+    fi
+    specific_version="local"
+else
+    platform=$(detect_platform)
+    filename="$APP-$platform.tar.gz"
+
+    if [ -z "$requested_version" ]; then
+        url="https://github.com/$REPO/releases/latest/download/$filename"
+        specific_version=$(curl -sI "https://github.com/$REPO/releases/latest" | grep -i "location:" | sed -n 's/.*tag\/v\([^[:space:]]*\).*/\1/p' | tr -d '\r')
+
+        if [[ -z "$specific_version" ]]; then
+            # Fallback to API
+            specific_version=$(curl -s "https://api.github.com/repos/$REPO/releases/latest" | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
+        fi
+
+        if [[ -z "$specific_version" ]]; then
+            echo -e "${RED}Failed to fetch version information${NC}"
+            exit 1
+        fi
+    else
+        requested_version="${requested_version#v}"
+        url="https://github.com/$REPO/releases/download/v${requested_version}/$filename"
+        specific_version=$requested_version
+
+        # Verify release exists
+        http_status=$(curl -sI -o /dev/null -w "%{http_code}" "https://github.com/$REPO/releases/tag/v${requested_version}")
+        if [ "$http_status" = "404" ]; then
+            echo -e "${RED}Error: Release v${requested_version} not found${NC}"
+            echo -e "${MUTED}Available releases: https://github.com/$REPO/releases${NC}"
+            exit 1
+        fi
+    fi
+fi
+
+check_version() {
+    if command -v seshions >/dev/null 2>&1; then
+        installed_version=$(seshions --version 2>/dev/null || echo "")
+        if [[ "$installed_version" == "$specific_version" ]]; then
+            echo -e "${MUTED}Version ${NC}$specific_version${MUTED} already installed${NC}"
+            exit 0
+        else
+            echo -e "${MUTED}Installed version: ${NC}$installed_version"
+        fi
+    fi
+}
+
+download_and_install() {
+    echo -e "\n${MUTED}Installing ${NC}$APP ${MUTED}version: ${NC}$specific_version"
+    echo -e "${MUTED}Platform: ${NC}$platform"
+
+    local tmp_dir="${TMPDIR:-/tmp}/$APP-$$"
+    mkdir -p "$tmp_dir"
+
+    echo -e "${MUTED}Downloading...${NC}"
+    if ! curl -#fL -o "$tmp_dir/$filename" "$url"; then
+        echo -e "${RED}Download failed. The release may not have binaries for your platform.${NC}"
+        echo -e "${MUTED}You can install from source instead:${NC}"
+        echo -e "  git clone https://github.com/$REPO.git"
+        echo -e "  cd seshions && bun install && bun run build"
+        rm -rf "$tmp_dir"
+        exit 1
+    fi
+
+    # Extract tarball
+    tar -xzf "$tmp_dir/$filename" -C "$tmp_dir"
+
+    # Find the binary (could be in subdirectory)
+    local binary_path
+    if [ -f "$tmp_dir/$APP" ]; then
+        binary_path="$tmp_dir/$APP"
+    elif [ -f "$tmp_dir/$APP-$platform/$APP" ]; then
+        binary_path="$tmp_dir/$APP-$platform/$APP"
+    else
+        echo -e "${RED}Binary not found in archive${NC}"
+        rm -rf "$tmp_dir"
+        exit 1
+    fi
+
+    mv "$binary_path" "$INSTALL_DIR/$APP"
+    chmod 755 "$INSTALL_DIR/$APP"
+    rm -rf "$tmp_dir"
+
+}
+
+install_from_binary() {
+    echo -e "\n${MUTED}Installing ${NC}$APP ${MUTED}from: ${NC}$binary_path"
+    cp "$binary_path" "$INSTALL_DIR/$APP"
+    chmod 755 "$INSTALL_DIR/$APP"
+}
+
+if [ -n "$binary_path" ]; then
+    install_from_binary
+else
+    check_version
+    download_and_install
+fi
+
+# Add to PATH
+add_to_path() {
+    local config_file=$1
+    local command=$2
+
+    if grep -Fxq "$command" "$config_file" 2>/dev/null; then
+        return 0
+    elif [[ -w $config_file ]]; then
+        echo -e "\n# seshions" >> "$config_file"
+        echo "$command" >> "$config_file"
+        echo -e "${MUTED}Added to PATH in ${NC}$config_file"
+    fi
+}
+
+if [[ "$no_modify_path" != "true" ]]; then
+    if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
+        current_shell=$(basename "$SHELL")
+        case $current_shell in
+            fish)
+                config_file="$HOME/.config/fish/config.fish"
+                [[ -f "$config_file" ]] && add_to_path "$config_file" "fish_add_path $INSTALL_DIR"
+                ;;
+            zsh)
+                config_file="${ZDOTDIR:-$HOME}/.zshrc"
+                [[ -f "$config_file" ]] && add_to_path "$config_file" "export PATH=\"$INSTALL_DIR:\$PATH\""
+                ;;
+            *)
+                config_file="$HOME/.bashrc"
+                [[ -f "$config_file" ]] && add_to_path "$config_file" "export PATH=\"$INSTALL_DIR:\$PATH\""
+                ;;
+        esac
+    fi
+fi
+
+echo ""
+echo -e "${GREEN}Installation complete!${NC}"
+echo ""
+echo -e "  Run ${GREEN}seshions${NC} to open Seshions"
+echo ""
+echo -e "  ${MUTED}Binary: ${NC}$INSTALL_DIR/$APP"
+echo ""
+echo -e "  ${MUTED}Restart your shell or run:${NC}"
+echo -e "  export PATH=\"$INSTALL_DIR:\$PATH\""
+echo ""

package/launcher/seshions.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process"
+import { readFile } from "node:fs/promises"
+import { ensureRuntime } from "../scripts/runtime/resolve-runtime.mjs"
+
+async function readPackageVersion() {
+  const packagePath = new URL("../package.json", import.meta.url)
+  const pkg = JSON.parse(await readFile(packagePath, "utf8"))
+  return String(pkg.version || "").replace(/^v/, "")
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(await readPackageVersion())
+    return
+  }
+
+  const desiredVersion = process.env.SESHIONS_RUNTIME_VERSION || await readPackageVersion()
+  const runtime = await ensureRuntime({
+    version: desiredVersion,
+    allowLatestFallback: true
+  })
+
+  const child = spawn(runtime.binaryPath, args, {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      NODE_PTY_PREBUILDS: runtime.prebuildsPath
+    }
+  })
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal)
+      return
+    }
+    process.exit(code ?? 0)
+  })
+
+  child.on("error", (error) => {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(`[seshions] Failed to launch runtime: ${message}`)
+    process.exit(1)
+  })
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`[seshions] ${message}`)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "seshions",
+  "version": "0.2.1",
+  "description": "OpenTUI-based Agent Management",
+  "type": "module",
+  "main": "launcher/seshions.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "launcher",
+    "scripts/runtime",
+    "README.md",
+    "LICENSE",
+    "install.sh",
+    "uninstall.sh"
+  ],
+  "bin": {
+    "seshions": "launcher/seshions.js"
+  },
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "compile": "bun run scripts/compile.ts",
+    "compile:all": "bun run scripts/compile.ts --all",
+    "release": "bun run scripts/release.ts",
+    "postinstall": "node scripts/runtime/postinstall.mjs",
+    "dev": "bun run scripts/build.ts && bun run dist/index.js",
+    "start": "bun run dist/index.js",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.79",
+    "@opentui/solid": "^0.1.79",
+    "fuzzysort": "^3.0.0",
+    "node-pty": "1.0.0",
+    "remeda": "^2.0.0",
+    "solid-js": "^1.9.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "@tsconfig/bun": "^1.0.0",
+    "@types/bun": "latest",
+    "babel-preset-solid": "^1.8.0",
+    "typescript": "^5.3.0"
+  }
+}

package/scripts/runtime/postinstall.mjs

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises"
+import { ensureRuntime, getRuntimeInfo } from "./resolve-runtime.mjs"
+
+async function readPackageVersion() {
+  const packagePath = new URL("../../package.json", import.meta.url)
+  const pkg = JSON.parse(await readFile(packagePath, "utf8"))
+  return String(pkg.version || "").replace(/^v/, "")
+}
+
+async function main() {
+  const skip = process.env.SESHIONS_SKIP_POSTINSTALL === "1" || process.env.CI === "true"
+  if (skip) {
+    return
+  }
+
+  const globalInstall = process.env.npm_config_global === "true"
+  const force = process.env.SESHIONS_POSTINSTALL_FORCE === "1"
+
+  if (!globalInstall && !force) {
+    console.log("[seshions] Runtime download deferred. It will install on first run.")
+    return
+  }
+
+  try {
+    const version = await readPackageVersion()
+    const runtime = await ensureRuntime({ version, allowLatestFallback: true })
+    console.log(`[seshions] Runtime ready: v${runtime.version} (${runtime.platform})`)
+  } catch (error) {
+    const { platform, repo, runtimeRoot } = getRuntimeInfo()
+    const message = error instanceof Error ? error.message : String(error)
+    console.warn(`[seshions] Runtime prefetch skipped: ${message}`)
+    console.warn(`[seshions] Platform: ${platform} | Repo: ${repo} | Cache: ${runtimeRoot}`)
+    console.warn("[seshions] First run will retry download automatically.")
+  }
+}
+
+main()

package/scripts/runtime/resolve-runtime.mjs

@@ -0,0 +1,216 @@
+import { spawnSync } from "node:child_process"
+import { Readable } from "node:stream"
+import { pipeline } from "node:stream/promises"
+import { createWriteStream } from "node:fs"
+import { access, chmod, mkdir, readFile, rename, rm } from "node:fs/promises"
+import { constants as fsConstants } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+const APP = "seshions"
+const DEFAULT_REPO = "danhergir/seshions"
+const USER_AGENT = "seshions-runtime-installer"
+
+function normalizeVersion(version) {
+  return String(version).replace(/^v/, "")
+}
+
+function detectPlatform() {
+  const osName = process.platform
+  const arch = process.arch
+
+  if (osName !== "darwin" && osName !== "linux") {
+    throw new Error(`Unsupported OS: ${osName}. Seshions runtime supports macOS and Linux.`)
+  }
+
+  if (arch !== "arm64" && arch !== "x64") {
+    throw new Error(`Unsupported architecture: ${arch}. Supported architectures: arm64, x64.`)
+  }
+
+  return `${osName}-${arch}`
+}
+
+function getRepo() {
+  return process.env.SESHIONS_REPO || DEFAULT_REPO
+}
+
+function getRuntimeRoot() {
+  return process.env.SESHIONS_RUNTIME_DIR || path.join(os.homedir(), ".seshions", "runtime")
+}
+
+function getArchiveName(platform) {
+  return `${APP}-${platform}.tar.gz`
+}
+
+function getReleaseAssetUrl(repo, version, platform) {
+  return `https://github.com/${repo}/releases/download/v${version}/${getArchiveName(platform)}`
+}
+
+function getRuntimeDir(runtimeRoot, version, platform) {
+  return path.join(runtimeRoot, version, platform)
+}
+
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function isExecutable(filePath) {
+  try {
+    await access(filePath, fsConstants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function fetchLatestVersion(repo) {
+  const response = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {
+    headers: {
+      "User-Agent": USER_AGENT,
+      "Accept": "application/vnd.github+json"
+    }
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to resolve latest release for ${repo} (HTTP ${response.status})`)
+  }
+
+  const data = await response.json()
+  if (!data?.tag_name) {
+    throw new Error(`Latest release response for ${repo} did not include tag_name`)
+  }
+
+  return normalizeVersion(data.tag_name)
+}
+
+async function downloadFile(url, destination) {
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": USER_AGENT,
+      "Accept": "application/octet-stream"
+    }
+  })
+
+  if (!response.ok || !response.body) {
+    const error = new Error(`Download failed (${response.status}) for ${url}`)
+    error.statusCode = response.status
+    throw error
+  }
+
+  const writable = createWriteStream(destination, { mode: 0o600 })
+  await pipeline(Readable.fromWeb(response.body), writable)
+}
+
+async function extractArchive(archivePath, destinationDir) {
+  const result = spawnSync(
+    "tar",
+    ["-xzf", archivePath, "-C", destinationDir, "--strip-components=1"],
+    { stdio: "pipe" }
+  )
+
+  if (result.error) {
+    throw new Error(`Failed to run tar: ${result.error.message}`)
+  }
+
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").toString().trim()
+    throw new Error(`Failed to extract runtime archive${stderr ? `: ${stderr}` : ""}`)
+  }
+}
+
+async function installRuntimeVersion({ repo, version, platform, runtimeRoot }) {
+  const runtimeDir = getRuntimeDir(runtimeRoot, version, platform)
+  const binaryPath = path.join(runtimeDir, APP)
+
+  if (await isExecutable(binaryPath)) {
+    return {
+      binaryPath,
+      prebuildsPath: path.join(runtimeDir, "prebuilds"),
+      runtimeDir,
+      version,
+      platform,
+      repo
+    }
+  }
+
+  const tmpDir = `${runtimeDir}.tmp-${process.pid}`
+  const archivePath = path.join(tmpDir, getArchiveName(platform))
+  const url = getReleaseAssetUrl(repo, version, platform)
+
+  await rm(tmpDir, { recursive: true, force: true })
+  await mkdir(tmpDir, { recursive: true })
+
+  try {
+    await downloadFile(url, archivePath)
+    await extractArchive(archivePath, tmpDir)
+
+    const extractedBinaryPath = path.join(tmpDir, APP)
+    if (!(await pathExists(extractedBinaryPath))) {
+      throw new Error(`Runtime archive was missing '${APP}' binary`)
+    }
+
+    await chmod(extractedBinaryPath, 0o755)
+    await mkdir(path.dirname(runtimeDir), { recursive: true })
+    await rm(runtimeDir, { recursive: true, force: true })
+    await rename(tmpDir, runtimeDir)
+
+    return {
+      binaryPath: path.join(runtimeDir, APP),
+      prebuildsPath: path.join(runtimeDir, "prebuilds"),
+      runtimeDir,
+      version,
+      platform,
+      repo
+    }
+  } catch (error) {
+    await rm(tmpDir, { recursive: true, force: true })
+    throw error
+  }
+}
+
+async function readPackageVersion() {
+  const packagePath = new URL("../../package.json", import.meta.url)
+  const pkg = JSON.parse(await readFile(packagePath, "utf8"))
+  return normalizeVersion(pkg.version)
+}
+
+export async function ensureRuntime(options = {}) {
+  const repo = options.repo || getRepo()
+  const platform = options.platform || detectPlatform()
+  const runtimeRoot = options.runtimeRoot || getRuntimeRoot()
+  const allowLatestFallback = options.allowLatestFallback !== false
+
+  let version = options.version ? normalizeVersion(options.version) : normalizeVersion(process.env.SESHIONS_RUNTIME_VERSION || "")
+  if (!version) {
+    version = await readPackageVersion()
+  }
+
+  try {
+    return await installRuntimeVersion({ repo, version, platform, runtimeRoot })
+  } catch (error) {
+    const statusCode = typeof error?.statusCode === "number" ? error.statusCode : undefined
+    if (!allowLatestFallback || (statusCode !== 404 && statusCode !== 403)) {
+      throw error
+    }
+
+    const latestVersion = await fetchLatestVersion(repo)
+    if (latestVersion === version) {
+      throw error
+    }
+
+    return installRuntimeVersion({ repo, version: latestVersion, platform, runtimeRoot })
+  }
+}
+
+export function getRuntimeInfo() {
+  return {
+    platform: detectPlatform(),
+    repo: getRepo(),
+    runtimeRoot: getRuntimeRoot()
+  }
+}

package/uninstall.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+#
+# Seshions Uninstaller
+# Usage: SESHIONS_REPO=danhergir/seshions curl -fsSL "https://raw.githubusercontent.com/${SESHIONS_REPO}/main/uninstall.sh" | bash
+#
+
+set -euo pipefail
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+INSTALL_DIR="${SESHIONS_INSTALL_DIR:-$HOME/.seshions/bin}"
+BIN_DIR="${SESHIONS_BIN_DIR:-$HOME/.local/bin}"
+DATA_DIR="${SESHIONS_DATA_DIR:-$HOME/.seshions}"
+
+purge_data=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --purge-data)
+      purge_data=true
+      shift
+      ;;
+    -h|--help)
+      cat <<EOF
+Seshions Uninstaller
+
+Usage:
+  uninstall.sh [--purge-data]
+
+Options:
+  --purge-data         Remove ~/.seshions data (state.db, config.json, logs)
+EOF
+      exit 0
+      ;;
+    *)
+      echo -e "${YELLOW}[seshions]${NC} Unknown option: $1"
+      shift
+      ;;
+  esac
+done
+
+log() {
+  echo -e "${BLUE}[seshions]${NC} $1"
+}
+
+success() {
+  echo -e "${GREEN}[seshions]${NC} $1"
+}
+
+warn() {
+  echo -e "${YELLOW}[seshions]${NC} $1"
+}
+
+main() {
+  echo ""
+  echo -e "${BLUE}╭───────────────────────────────────╮${NC}"
+  echo -e "${BLUE}│      ${RED}Seshions Uninstaller${BLUE}       │${NC}"
+  echo -e "${BLUE}╰───────────────────────────────────╯${NC}"
+  echo ""
+
+  for cmd in seshions; do
+    if [ -f "$INSTALL_DIR/$cmd" ]; then
+      log "Removing $INSTALL_DIR/$cmd..."
+      rm -f "$INSTALL_DIR/$cmd"
+    fi
+  done
+
+  for cmd in seshions; do
+    if [ -L "$BIN_DIR/$cmd" ] || [ -f "$BIN_DIR/$cmd" ]; then
+      log "Removing $BIN_DIR/$cmd..."
+      rm -f "$BIN_DIR/$cmd"
+    fi
+  done
+
+  if [ -d "$INSTALL_DIR" ] && [ -z "$(ls -A "$INSTALL_DIR" 2>/dev/null)" ]; then
+    log "Removing empty install directory $INSTALL_DIR..."
+    rmdir "$INSTALL_DIR" || true
+  fi
+
+  if [ "$purge_data" = true ] && [ -d "$DATA_DIR" ]; then
+    log "Purging data directory $DATA_DIR..."
+    rm -rf "$DATA_DIR"
+  fi
+
+  echo ""
+  success "Seshions has been uninstalled"
+  echo ""
+  warn "Note: PATH entries in shell config files were not removed"
+  warn "User data is preserved by default. Use --purge-data to remove ~/.seshions data."
+  echo ""
+}
+
+main "$@"