@zendero/runctl 0.1.1 → 0.1.3

package/README.md

@@ -10,22 +10,57 @@ Picks a **free port**, runs your **dev server in the background**, and keeps **P
 
 ## Install
 
-**In a project (recommended):**
+The published package on npm is **`@zendero/runctl`**. The CLI binary on your PATH is still **`runctl`**.
+
+**From the npm registry (recommended):**
 
 ```bash
-pnpm add -D runctl          # or npm install -D / yarn add -D
+pnpm add -D @zendero/runctl          # or npm install -D / yarn add -D
 ```
 
 **Global CLI** (`runctl` on your PATH everywhere):
 
 ```bash
-pnpm add -g runctl           # or npm install -g
+pnpm add -g @zendero/runctl           # or npm install -g
+```
+
+**Global install via curl** uses a single script: [`scripts/install-global.sh`](scripts/install-global.sh)
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
+  bash
+```
+
+With no arguments, `install-global.sh` prompts on a TTY; otherwise it defaults to registry install with Git fallback. Pass arguments to force a mode:
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
+  bash -s -- --registry
 ```
 
-**One-liner (from GitHub):**
+```bash
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
+  bash -s -- --auto
+```
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh | bash
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
+  bash -s -- --git --ref main
+```
+
+Optional flags: `--pm pnpm|npm`, `--ref <git-ref>`. Optional env: `RUNCTL_PACKAGE`, `RUNCTL_GIT_BASE`, `RUNCTL_GIT_REF`.
+
+**Without curl:**
+
+```bash
+pnpm add -g @zendero/runctl
+pnpm add -g "github:DoctorKhan/runctl#main"
+```
+
+**Project dependency from GitHub** (not global): dependency resolves to **`@zendero/runctl`**. Reinstall to pull the latest `main`:
+
+```bash
+pnpm add -D "github:DoctorKhan/runctl#main"
 ```
 
 ---
@@ -57,14 +92,16 @@ Add scripts to your `package.json`:
 
 | Command | What it does |
 |---------|-------------|
-| `runctl start [dir] [--script name]` | Start dev server (picks free port, backgrounds) |
+| `runctl start` \| `runctl dev` | Start dev server (same command; picks free port, backgrounds) |
 | `runctl stop [dir]` | Stop daemons & release ports |
 | `runctl status [dir]` | Show `.run` state for this package |
+| `runctl logs [dir] [service]` | Tail `.run/logs/<service>.log` (default service: `web`) |
 | `runctl ports` | List user-wide port registry (`~/.run`) |
 | `runctl ports gc` | Clean up stale port claims |
 | `runctl env expand <manifest> [--out file]` | Generate `.env.local` from manifest |
-| `runctl update` | Update to latest version |
-| `runctl version` | Print install location |
+| `runctl doctor [dir]` | Check Node 18+, `lsof`, package manager, `package.json` |
+| `runctl update` | Update the global `@zendero/runctl` install |
+| `runctl version` | Print package version and install path |
 
 **Monorepo:** `runctl start ./apps/web --script dev:server`
 
@@ -89,4 +126,14 @@ Add scripts to your `package.json`:
 
 [`examples/consumer-package.json`](examples/consumer-package.json) · [`docs/vercel-and-env.md`](docs/vercel-and-env.md) · [`examples/env.manifest.example`](examples/env.manifest.example)
 
-**Develop this repo:** `pnpm install` → `./run.sh ports`
+**Develop this repo:** `pnpm install` → `./run.sh` (default **doctor**, like `elata-bio-sdk/run.sh`) → `./run.sh ports`
+
+**Publish (maintainers)** — workflow similar to elata’s release preflight, scaled for one package:
+
+| Step | Command |
+|------|--------|
+| Preflight | `./run.sh release-check` or `pnpm run release-check` |
+| Publish | `./run.sh release latest` or `pnpm run release` |
+| Promote dist-tag | After publishing under `next`, `./run.sh promote` sets **latest** for the version in `package.json` |
+
+Put `NPM_TOKEN` in `.env`. `release` / `npm-whoami` use a **temporary `NPM_CONFIG_USERCONFIG`** so a stale `~/.npmrc` token does not override `.env` (npm 10+ / pnpm). Token lines can use `NPM_TOKEN=` or `npm_token=`; quoted values are supported without `source`-ing secrets as shell code first.

package/bin/runctl

@@ -16,13 +16,15 @@ ${_b}runctl${_r} — dev-server orchestrator & port manager
 ${_y}Usage:${_r}  runctl <command> [options]
 
 ${_y}Commands${_r}
-  ${_c}start${_r} [dir] [--script name]   Start dev server ${_d}(picks free port, backgrounds)${_r}
+  ${_c}start${_r} | ${_c}dev${_r} [dir] [--script name]  Start dev server ${_d}(alias: dev = start)${_r}
   ${_c}open${_r}  [dir]                   Open running dev server in browser
   ${_c}stop${_r}  [dir]                   Stop daemons & release ports
   ${_c}status${_r} [dir]                  Show running state
+  ${_c}logs${_r} [dir] [service]         Tail .run/logs/<service>.log ${_d}(default service: web)${_r}
   ${_c}ports${_r}                         List user-wide port registry (~/.run)
   ${_c}ports gc${_r}                      Clean up stale port claims
   ${_c}env expand${_r} <manifest> [opts]  Generate .env.local from manifest
+  ${_c}doctor${_r}                        Check Node, tooling, and project basics
   ${_c}update${_r}                        Update runctl to latest version
 
 ${_y}Options${_r}
@@ -80,12 +82,20 @@ cmd_start() {
 cmd_open() {
   local proj
   proj="$(_resolve_proj "$@")"
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  run_project_init "$proj"
   local ports_env="$proj/.run/ports.env"
   if [[ ! -f "$ports_env" ]]; then
     echo "runctl open: no running server found (.run/ports.env missing)" >&2
     echo "Start one first: runctl start" >&2
     exit 1
   fi
+  if ! run_local_has_live_service; then
+    echo "runctl open: no running server found (saved port is stale)" >&2
+    echo "Start one first: runctl start" >&2
+    exit 1
+  fi
   local port="" host=""
   while IFS= read -r line; do
     case "$line" in
@@ -165,32 +175,123 @@ cmd_env() {
 }
 
 cmd_update() {
-  echo "runctl update: installing latest runctl..."
+  echo "runctl update: installing latest @zendero/runctl..."
   if command -v pnpm >/dev/null 2>&1; then
-    pnpm add -g runctl@latest
+    pnpm add -g @zendero/runctl@latest
   elif command -v npm >/dev/null 2>&1; then
-    npm install -g runctl@latest
+    npm install -g @zendero/runctl@latest
   else
     echo "runctl: pnpm or npm required to update." >&2
     exit 1
   fi
 }
 
+cmd_doctor() {
+  local proj
+  proj="$(pwd)"
+  [[ $# -ge 1 && -d "$1" ]] && proj="$(cd "$1" && pwd)"
+  echo "runctl doctor"
+  local ec=0
+  if command -v node >/dev/null 2>&1 && node -e 'process.exit(parseInt(process.versions.node,10)>=18?0:1)' 2>/dev/null; then
+    printf '  %-12s %s\n' "node:" "$(node -v) (ok)"
+  else
+    printf '  %-12s %s\n' "node:" "missing or < 18 (required)" >&2
+    ec=1
+  fi
+  if command -v lsof >/dev/null 2>&1; then
+    printf '  %-12s %s\n' "lsof:" "present (port detection / gc)"
+  else
+    printf '  %-12s %s\n' "lsof:" "missing — install for free-port + ports gc" >&2
+  fi
+  local pm=""
+  if command -v pnpm >/dev/null 2>&1; then pm="pnpm $(pnpm -v 2>/dev/null || echo '')"
+  elif command -v npm >/dev/null 2>&1; then pm="npm $(npm -v 2>/dev/null || echo '')"
+  elif command -v bun >/dev/null 2>&1; then pm="bun $(bun -v 2>/dev/null || echo '')"
+  elif command -v yarn >/dev/null 2>&1; then pm="yarn $(yarn -v 2>/dev/null || echo '')"
+  else
+    pm="none found"
+    ec=1
+  fi
+  printf '  %-12s %s\n' "package mgr:" "$pm"
+  if [[ -f "$proj/package.json" ]]; then
+    printf '  %-12s %s\n' "package.json:" "$proj (ok)"
+  else
+    printf '  %-12s %s\n' "package.json:" "not found in $proj" >&2
+    ec=1
+  fi
+  return "$ec"
+}
+
+cmd_logs() {
+  local proj lines="${RUNCTL_LOG_LINES:-80}"
+  proj="$(pwd)"
+  local -a pos=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -n | --lines)
+        lines="${2:-80}"
+        shift 2
+        ;;
+      -h | --help)
+        echo "Usage: runctl logs [dir] [service]  (default service: web)" >&2
+        echo "       runctl logs [--lines N]" >&2
+        exit 0
+        ;;
+      *)
+        pos+=("$1")
+        shift
+        ;;
+    esac
+  done
+  if [[ ${#pos[@]} -ge 1 && -d "${pos[0]}" ]]; then
+    proj="$(cd "${pos[0]}" && pwd)"
+    pos=("${pos[@]:1}")
+  fi
+  local svc="${pos[0]:-web}"
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  run_project_init "$proj"
+  local logf="$RUN_LOCAL_STATE/logs/${svc}.log"
+  if [[ ! -f "$logf" ]]; then
+    echo "runctl logs: no file at $logf" >&2
+    if [[ -d "$RUN_LOCAL_STATE/logs" ]]; then
+      echo "Available logs:" >&2
+      ls -1 "$RUN_LOCAL_STATE/logs" 2>/dev/null | sed 's/^/  /' >&2 || true
+    fi
+    exit 1
+  fi
+  echo "runctl logs: $logf (last $lines lines)"
+  tail -n "$lines" "$logf"
+}
+
+cmd_version_print() {
+  local ver="?"
+  if command -v node >/dev/null 2>&1; then
+    ver="$(
+      node -e 'const fs=require("fs"); console.log(JSON.parse(fs.readFileSync(process.argv[1],"utf8")).version);' \
+        "$RUNCTL_PKG_ROOT/package.json" 2>/dev/null || echo "?"
+    )"
+  fi
+  printf '%s\n' "runctl $ver — $RUNCTL_PKG_ROOT"
+}
+
 main() {
   local cmd="${1:-help}"
   shift || true
   case "$cmd" in
-    start)    cmd_start "$@" ;;
+    start | dev) cmd_start "$@" ;;
     open)     cmd_open "$@" ;;
     stop)     cmd_stop "$@" ;;
     status)   cmd_status "$@" ;;
+    logs)     cmd_logs "$@" ;;
     ports)    cmd_ports "$@" ;;
     env)      cmd_env "$@" ;;
+    doctor)   cmd_doctor "$@" ;;
     update)   cmd_update ;;
 
     # Plumbing
     lib-path) printf '%s\n' "$RUNCTL_PKG_ROOT/lib/run-lib.sh" ;;
-    version | -v) printf '%s\n' "runctl @ $RUNCTL_PKG_ROOT" ;;
+    version | -v) cmd_version_print ;;
     help | -h | --help) usage ;;
 
     # Hidden backward-compat aliases

package/docs/vercel-and-env.md

@@ -12,8 +12,8 @@ Keep a **manifest** (not loaded directly by Next/Vite) that lists each real valu
 - Expand to a generated file that frameworks **do** load:
 
 ```bash
-pnpm exec runctl expand-env env.manifest --out .env.local
-# or: node node_modules/runctl/scripts/expand-env-manifest.mjs env.manifest --out .env.local
+pnpm exec runctl env expand env.manifest --out .env.local
+# or: node node_modules/@zendero/runctl/scripts/expand-env-manifest.mjs env.manifest --out .env.local
 ```
 
 Add **`.env.local`** (and optionally `.env.manifest` if it contains no secrets—usually it *does*, so keep the manifest **gitignored** or use a **`.env.manifest.example`** without real values).

package/examples/consumer-package.json

@@ -4,6 +4,8 @@
     "dev:server": "next dev",
     "dev:stop": "runctl stop",
     "dev:status": "runctl status",
+    "dev:logs": "runctl logs",
+    "doctor": "runctl doctor",
     "ports": "runctl ports",
     "ports:gc": "runctl ports gc",
     "env:expand": "runctl env expand env.manifest --out .env.local"

package/examples/run.sh.example

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Optional shell entrypoint — most projects only need package.json scripts.
-# Prerequisite: pnpm add -D runctl   (Node >= 18)
+# Prerequisite: pnpm add -D @zendero/runctl   (Node >= 18)
 
 set -euo pipefail
 
@@ -8,7 +8,7 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$ROOT"
 
 if [[ -z "${RUN_LIB:-}" ]]; then
-  _rp="${RUNCTL_PACKAGE:-runctl}"
+  _rp="${RUNCTL_PACKAGE:-@zendero/runctl}"
   RUN_LIB="$(
     cd "$ROOT" && RUNCTL_PACKAGE="$_rp" node -e "
       const p = require('path');

package/lib/run-lib.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# run-lib.sh — npm package `runctl`: project .run/ + user ~/.run registry.
+# run-lib.sh — npm package `@zendero/runctl`: project .run/ + user ~/.run registry.
 # Requires bash. Port/dev automation requires Node.js >= 18 (see package.json engines).
 # Intentionally no global `set -e` — this file is usually sourced.
 
@@ -90,6 +90,28 @@ run_pid_alive() {
   kill -0 "$1" 2>/dev/null
 }
 
+run_pid_listens_on_port() {
+  local pid="$1"
+  local port="$2"
+  [[ -n "$pid" && -n "$port" ]] || return 1
+  command -v lsof >/dev/null 2>&1 || return 1
+  lsof -iTCP:"$port" -sTCP:LISTEN -n -P 2>/dev/null | awk 'NR>1 {print $2}' | sort -u | grep -qx "$pid"
+}
+
+run_local_has_live_service() {
+  local f pid
+  shopt -s nullglob
+  for f in "$RUN_LOCAL_STATE/pids"/*.pid; do
+    pid="$(cat "$f" 2>/dev/null || true)"
+    if [[ -n "$pid" ]] && run_pid_alive "$pid"; then
+      shopt -u nullglob
+      return 0
+    fi
+  done
+  shopt -u nullglob
+  return 1
+}
+
 run_port_listening() {
   local port="$1"
   command -v lsof >/dev/null 2>&1 || return 1
@@ -297,13 +319,31 @@ run_daemon_start() {
   local logf="$RUN_LOCAL_STATE/logs/${name}.log"
   if [[ -f "$pidf" ]]; then
     local oldpid
+    local port=""
+    local port_service=""
     oldpid="$(cat "$pidf")"
+    if [[ -f "$RUN_LOCAL_STATE/ports.env" ]]; then
+      while IFS='=' read -r k v; do
+        case "$k" in
+          PORT) port="$v" ;;
+          RUN_DEV_SERVICE) port_service="$v" ;;
+        esac
+      done <"$RUN_LOCAL_STATE/ports.env"
+    fi
     if run_pid_alive "$oldpid"; then
-      echo "run_daemon_start: ${name} already running (pid $oldpid)" >&2
-      return 1
+      if [[ -n "$port" ]] && [[ -z "$port_service" || "$port_service" == "$name" ]] && run_pid_listens_on_port "$oldpid" "$port"; then
+        echo "run_daemon_start: ${name} already running (pid $oldpid)" >&2
+        return 1
+      fi
+      if [[ -z "$port" ]]; then
+        echo "run_daemon_start: ${name} already running (pid $oldpid)" >&2
+        return 1
+      fi
+      echo "run_daemon_start: cleared stale pid for ${name} (pid $oldpid not listening on port $port)" >&2
+    else
+      echo "run_daemon_start: cleared stale pid for ${name} (was $oldpid)" >&2
     fi
     rm -f "$pidf"
-    echo "run_daemon_start: cleared stale pid for ${name} (was $oldpid)" >&2
   fi
   nohup "$@" >>"$logf" 2>&1 &
   local pid=$!
@@ -414,7 +454,7 @@ run_global_gc() {
       stale=1
     fi
     if [[ "$stale" -eq 0 ]] && [[ -n "$pid" ]] && command -v lsof >/dev/null 2>&1; then
-      if ! lsof -iTCP:"$port" -sTCP:LISTEN -n -P 2>/dev/null | awk 'NR>1 {print $2}' | sort -u | grep -qx "$pid"; then
+      if ! run_pid_listens_on_port "$pid" "$port"; then
         stale=1
       fi
     fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendero/runctl",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Picks a free port, runs your dev server in the background, and keeps PID + port state in .run/ so projects don't collide.",
   "author": "DoctorKhan",
   "homepage": "https://github.com/DoctorKhan/runctl#readme",
@@ -37,6 +37,10 @@
   ],
   "scripts": {
     "run": "bash ./run.sh",
+    "doctor": "bash ./run.sh doctor",
+    "release-check": "bash ./run.sh release-check",
+    "promote": "bash ./run.sh promote",
+    "release": "bash ./run.sh release latest",
     "env:expand": "node ./scripts/expand-env-manifest.mjs",
     "link-global": "pnpm link --global"
   }

package/scripts/install-global.sh

@@ -1,13 +1,248 @@
-#!/usr/bin/env sh
-# Install runctl globally (needs Node 18+ and npm or pnpm).
+#!/usr/bin/env bash
+# Global installer for @zendero/runctl.
+#
 #   curl -fsSL https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh | bash
-# Registry: RUNCTL_PACKAGE=runctl curl -fsSL … | bash
-# Scoped: RUNCTL_PACKAGE=@your-org/runctl curl -fsSL … | bash
-set -eu
-PKG="${RUNCTL_PACKAGE:-runctl}"
-if command -v pnpm >/dev/null 2>&1; then
-  pnpm add -g "$PKG"
-else
-  npm install -g "$PKG"
-fi
-printf '\nInstalled %s — run: runctl help\n' "$PKG"
+#
+# Modes:
+#   --interactive  prompt for package manager + install source
+#   --registry     install from npm only
+#   --git          install from Git only
+#   --auto         install from npm, then fall back to Git
+#
+# Flags:
+#   --pm <pnpm|npm>
+#   --ref <git-ref>
+#   --help
+#
+# Optional env:
+#   RUNCTL_PACKAGE   npm package name (default: @zendero/runctl)
+#   RUNCTL_GIT_BASE  git URL without ref (default: git+https://github.com/DoctorKhan/runctl.git)
+#   RUNCTL_GIT_REF   git ref for Git installs (default: main)
+set -euo pipefail
+
+PKG="${RUNCTL_PACKAGE:-@zendero/runctl}"
+GIT_BASE="${RUNCTL_GIT_BASE:-git+https://github.com/DoctorKhan/runctl.git}"
+DEFAULT_GIT_REF="${RUNCTL_GIT_REF:-main}"
+
+MODE=""
+PM=""
+GIT_REF="$DEFAULT_GIT_REF"
+
+say() {
+  printf '%s\n' "$*"
+}
+
+usage() {
+  cat <<'EOF'
+Usage: install-global.sh [mode] [flags]
+
+Modes:
+  --interactive  Prompt for install options when a TTY is available.
+  --registry     Install from the npm registry only.
+  --git          Install from Git only.
+  --auto         Install from the npm registry, then fall back to Git.
+
+Flags:
+  --pm <pnpm|npm>  Force a package manager.
+  --ref <git-ref>  Git ref to use with --git or --auto fallback.
+  --help           Show this help.
+
+Default behavior:
+  If no mode is provided, use --interactive when a TTY is available.
+  Otherwise default to --auto.
+EOF
+}
+
+has_tty() {
+  [[ -t 1 ]] && [[ -r /dev/tty ]]
+}
+
+prompt_choice() {
+  local prompt="$1"
+  local default_value="$2"
+  shift 2
+  local options=("$@")
+  local answer
+
+  while true; do
+    printf '%s ' "$prompt" > /dev/tty
+    IFS= read -r answer < /dev/tty || answer=""
+    answer="${answer:-$default_value}"
+
+    for option in "${options[@]}"; do
+      if [[ "$answer" == "$option" ]]; then
+        printf '%s' "$answer"
+        return 0
+      fi
+    done
+
+    say "Please choose one of: ${options[*]}" > /dev/tty
+  done
+}
+
+prompt_text() {
+  local prompt="$1"
+  local default_value="$2"
+  local answer
+
+  printf '%s ' "$prompt" > /dev/tty
+  IFS= read -r answer < /dev/tty || answer=""
+  printf '%s' "${answer:-$default_value}"
+}
+
+pick_package_manager() {
+  if [[ -n "$PM" ]]; then
+    if [[ "$PM" != "pnpm" && "$PM" != "npm" ]]; then
+      say "runctl: unsupported package manager: $PM" >&2
+      exit 1
+    fi
+    if ! command -v "$PM" >/dev/null 2>&1; then
+      say "runctl: requested package manager not found on PATH: $PM" >&2
+      exit 1
+    fi
+    printf '%s' "$PM"
+    return 0
+  fi
+
+  if command -v pnpm >/dev/null 2>&1 && command -v npm >/dev/null 2>&1; then
+    if [[ "$MODE" == "interactive" ]]; then
+      prompt_choice "Package manager? [pnpm/npm] (default: pnpm)" "pnpm" "pnpm" "npm"
+    else
+      printf 'pnpm'
+    fi
+    return 0
+  fi
+
+  if command -v pnpm >/dev/null 2>&1; then
+    printf 'pnpm'
+    return 0
+  fi
+
+  if command -v npm >/dev/null 2>&1; then
+    printf 'npm'
+    return 0
+  fi
+
+  say "runctl: neither pnpm nor npm was found on PATH." >&2
+  exit 1
+}
+
+run_install() {
+  local manager="$1"
+  local source_kind="$2"
+  local target="$3"
+
+  if [[ "$manager" == "pnpm" ]]; then
+    pnpm add -g "$target"
+  else
+    npm install -g "$target"
+  fi
+
+  say
+  if [[ "$source_kind" == "git" ]]; then
+    say "Installed @zendero/runctl from Git — run: runctl help"
+  else
+    say "Installed $PKG — run: runctl help"
+  fi
+}
+
+fallback_install() {
+  local manager="$1"
+  local git_target="$2"
+
+  say "runctl: registry install failed; trying Git ($git_target)..." >&2
+  run_install "$manager" "git" "$git_target"
+}
+
+parse_args() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --interactive)
+        MODE="interactive"
+        ;;
+      --registry)
+        MODE="registry"
+        ;;
+      --git)
+        MODE="git"
+        ;;
+      --auto)
+        MODE="auto"
+        ;;
+      --pm)
+        [[ $# -ge 2 ]] || { say "runctl: --pm requires a value" >&2; exit 1; }
+        PM="$2"
+        shift
+        ;;
+      --ref)
+        [[ $# -ge 2 ]] || { say "runctl: --ref requires a value" >&2; exit 1; }
+        GIT_REF="$2"
+        shift
+        ;;
+      --help|-h)
+        usage
+        exit 0
+        ;;
+      *)
+        say "runctl: unknown argument: $1" >&2
+        usage >&2
+        exit 1
+        ;;
+    esac
+    shift
+  done
+}
+
+main() {
+  local manager git_target
+
+  parse_args "$@"
+
+  if [[ -z "$MODE" ]]; then
+    if has_tty && [[ "${CI:-}" != "1" ]]; then
+      MODE="interactive"
+    else
+      MODE="auto"
+    fi
+  fi
+
+  manager="$(pick_package_manager)"
+  git_target="${GIT_BASE}#${GIT_REF}"
+
+  if [[ "$MODE" == "interactive" ]] && (! has_tty || [[ "${CI:-}" == "1" ]]); then
+    say "runctl: no interactive TTY detected; defaulting to --auto." >&2
+    MODE="auto"
+  fi
+
+  case "$MODE" in
+    interactive)
+      say "runctl interactive installer"
+      say
+      say "This will install the global \`runctl\` CLI."
+      say
+      MODE="$(prompt_choice "Install source? [registry/git/auto] (default: auto)" "auto" "registry" "git" "auto")"
+      if [[ "$MODE" == "git" || "$MODE" == "auto" ]]; then
+        GIT_REF="$(prompt_text "Git ref to use? (default: ${GIT_REF})" "$GIT_REF")"
+        git_target="${GIT_BASE}#${GIT_REF}"
+      fi
+      ;;
+  esac
+
+  case "$MODE" in
+    registry)
+      run_install "$manager" "registry" "$PKG"
+      ;;
+    git)
+      say "runctl: installing from Git ($git_target)..." >&2
+      run_install "$manager" "git" "$git_target"
+      ;;
+    auto)
+      if run_install "$manager" "registry" "$PKG"; then
+        return 0
+      fi
+      fallback_install "$manager" "$git_target"
+      ;;
+  esac
+}
+
+main "$@"