@zendero/runctl 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# Runctl
+
+Picks a **free port**, runs your **dev server in the background**, and keeps **PID + port** state in **`.run/`** and **`~/.run`** so projects don't collide.
+
+**Needs Node.js 18+**, **bash**, and **`lsof`** (for free-port detection and `gc`; common on macOS, often `apt install lsof` on Linux).
+
+**Platforms:** macOS / Linux / **WSL**. Not aimed at native Windows shells.
+
+---
+
+## Install
+
+**In a project (recommended):**
+
+```bash
+pnpm add -D runctl          # or npm install -D / yarn add -D
+```
+
+**Global CLI** (`runctl` on your PATH everywhere):
+
+```bash
+pnpm add -g runctl           # or npm install -g
+```
+
+**One-liner (from GitHub, pre-publish):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DoctorKhan/devport-kit/main/scripts/install-global.sh | bash
+```
+
+---
+
+## Quick start
+
+Add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "runctl start --script dev:server",
+    "dev:server": "next dev",
+    "dev:stop": "runctl stop"
+  }
+}
+```
+
+- **`pnpm dev`** — start (port in `.run/ports.env`, logs in `.run/logs/`).
+- **`pnpm dev:stop`** — stop and release ports.
+
+**Why two scripts?** `runctl start` runs `pnpm run <name>` under the hood. If `dev` called itself, it would loop. The real server lives on `dev:server`; `--script` tells runctl which one to run. Without `--script`, it defaults to running `dev`.
+
+**`predev`:** If you define `predev` next to `dev` (e.g. a doctor step) and your script name is `dev:*` or `dev_*` without its own `pre<script>`, runctl runs `predev` once before starting. Set `RUNCTL_SKIP_PREDEV=1` to skip.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `runctl start [dir] [--script name]` | Start dev server (picks free port, backgrounds) |
+| `runctl stop [dir]` | Stop daemons & release ports |
+| `runctl status [dir]` | Show `.run` state for this package |
+| `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 |
+
+**Monorepo:** `runctl start ./apps/web --script dev:server`
+
+**Vite:** if `--port` isn't forwarded, set `server.port` from `process.env.PORT` in `vite.config`.
+
+---
+
+## Fits / doesn't fit
+
+| Kind of repo | Runctl |
+|--------------|--------|
+| Next.js, Vite, SvelteKit, Nuxt, Astro, Remix | **Good fit** — port flags wired for common stacks. |
+| **pnpm**, **npm**, **yarn**, **bun** lockfiles | **Supported** for `run <script>`. |
+| **`predev`** + split `dev` / `dev:server` | **Supported** — see above. |
+| Monorepo app in a subfolder | Use `runctl start ./apps/web`. |
+| **No `package.json`** (Python, Go, etc.) | **Not a fit** — this tool is for Node package scripts. |
+| Custom Node entry (gateways, CLIs) | **Weak fit** — `PORT`/`HOST` are set, but no framework CLI flags. |
+
+---
+
+## Docs & examples
+
+[`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 list`

package/bin/runctl

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# Runctl CLI — installed via pnpm/npm (devDependency .bin or global).
+set -euo pipefail
+RUNCTL_PKG_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)"
+
+_b="" _d="" _r="" _c="" _y="" _g=""
+if [[ -t 1 ]]; then
+  _b=$'\033[1m' _d=$'\033[2m' _r=$'\033[0m'
+  _c=$'\033[36m' _y=$'\033[33m' _g=$'\033[32m'
+fi
+
+usage() {
+  cat <<EOF
+${_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}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}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}update${_r}                        Update runctl to latest version
+
+${_y}Options${_r}
+  ${_c}--script${_r} <name>               Package script to run ${_d}(default: dev)${_r}
+  ${_c}--help${_r}, ${_c}-h${_r}                     Show this help
+
+${_d}Quick start — add to package.json:
+  "dev": "runctl start --script dev:server",
+  "dev:server": "next dev",
+  "dev:stop": "runctl stop"${_r}
+EOF
+}
+
+_resolve_proj() {
+  if [[ $# -ge 1 && -d "$1" ]]; then
+    (cd "$1" && pwd)
+  else
+    pwd
+  fi
+}
+
+cmd_start() {
+  local proj script="" args=()
+  proj="$(pwd)"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --script) script="${2:-}"; shift 2 ;;
+      --) shift; args+=("$@"); break ;;
+      -h | --help) usage; exit 0 ;;
+      -*)
+        echo "runctl start: unknown flag: $1" >&2
+        exit 1
+        ;;
+      *)
+        if [[ -d "$1" ]]; then
+          proj="$(cd "$1" && pwd)"
+          shift
+        else
+          args+=("$1")
+          shift
+        fi
+        ;;
+    esac
+  done
+
+  [[ -n "$script" ]] && export RUNCTL_PM_RUN_SCRIPT="$script"
+
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  run_project_init "$proj"
+  run_with_lock run_start_package_dev "${args[@]+"${args[@]}"}"
+}
+
+cmd_open() {
+  local proj
+  proj="$(_resolve_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
+  local port="" host=""
+  while IFS= read -r line; do
+    case "$line" in
+      PORT=*) port="${line#PORT=}" ;;
+      HOST=*) host="${line#HOST=}" ;;
+    esac
+  done <"$ports_env"
+  if [[ -z "$port" ]]; then
+    echo "runctl open: PORT not found in $ports_env" >&2
+    exit 1
+  fi
+  [[ -z "$host" || "$host" == "0.0.0.0" || "$host" == "127.0.0.1" ]] && host="localhost"
+  local url="http://${host}:${port}"
+  echo "runctl open: opening ${url}"
+  if command -v open >/dev/null 2>&1; then
+    open "$url"
+  elif command -v xdg-open >/dev/null 2>&1; then
+    xdg-open "$url"
+  elif command -v wslview >/dev/null 2>&1; then
+    wslview "$url"
+  else
+    echo "runctl open: no browser opener found (tried open, xdg-open, wslview)" >&2
+    echo "Visit: $url" >&2
+    exit 1
+  fi
+}
+
+cmd_stop() {
+  local proj
+  proj="$(_resolve_proj "$@")"
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  run_project_init "$proj"
+  run_stop_all
+  echo "runctl stop: stopped local services and released claimed ports for $proj"
+}
+
+cmd_status() {
+  local proj
+  proj="$(_resolve_proj "$@")"
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  run_project_init "$proj"
+  run_local_status
+}
+
+cmd_ports() {
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  local sub="${1:-list}"
+  case "$sub" in
+    list | "") run_global_list_ports ;;
+    gc) run_global_gc ;;
+    *)
+      echo "runctl ports: unknown subcommand: $sub (try: ports, ports gc)" >&2
+      exit 1
+      ;;
+  esac
+}
+
+cmd_env() {
+  local sub="${1:-}"
+  shift || true
+  case "$sub" in
+    expand)
+      command -v node >/dev/null 2>&1 || {
+        echo "runctl: Node.js >= 18 is required for env expand." >&2
+        exit 1
+      }
+      exec node "$RUNCTL_PKG_ROOT/scripts/expand-env-manifest.mjs" "$@"
+      ;;
+    *)
+      echo "runctl env: unknown subcommand: ${sub:-<none>} (try: env expand)" >&2
+      exit 1
+      ;;
+  esac
+}
+
+cmd_update() {
+  echo "runctl update: installing latest runctl..."
+  if command -v pnpm >/dev/null 2>&1; then
+    pnpm add -g runctl@latest
+  elif command -v npm >/dev/null 2>&1; then
+    npm install -g runctl@latest
+  else
+    echo "runctl: pnpm or npm required to update." >&2
+    exit 1
+  fi
+}
+
+main() {
+  local cmd="${1:-help}"
+  shift || true
+  case "$cmd" in
+    start)    cmd_start "$@" ;;
+    open)     cmd_open "$@" ;;
+    stop)     cmd_stop "$@" ;;
+    status)   cmd_status "$@" ;;
+    ports)    cmd_ports "$@" ;;
+    env)      cmd_env "$@" ;;
+    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" ;;
+    help | -h | --help) usage ;;
+
+    # Hidden backward-compat aliases
+    start-dev) cmd_start "$@" ;;
+    stop-dev)  cmd_stop "$@" ;;
+    status-dev) cmd_status "$@" ;;
+    list)      cmd_ports list ;;
+    gc)        cmd_ports gc ;;
+    expand-env) cmd_env expand "$@" ;;
+
+    *)
+      echo "runctl: unknown command: $cmd" >&2
+      echo ""
+      usage
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"

package/docs/vercel-and-env.md

@@ -0,0 +1,86 @@
+# Environment variables, shared values, and Vercel
+
+Vercel’s dashboard stores **flat** name → value pairs per environment. It does **not** offer “alias this key to that key” or `${VAR}` interpolation in the UI. If three keys must hold the same URL, you either **duplicate the value** in the dashboard or **manage one source of truth** outside Vercel and sync.
+
+Below is a practical split: **local + CI** use a manifest; **Vercel** uses duplication or a secrets sync product.
+
+## 1. Single source of truth in the repo (recommended baseline)
+
+Keep a **manifest** (not loaded directly by Next/Vite) that lists each real value once and expresses aliases with `${…}`:
+
+- Example: [`examples/env.manifest.example`](../examples/env.manifest.example)
+- 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
+```
+
+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).
+
+**Workflow**
+
+1. Edit `env.manifest` (gitignored) with real secrets.
+2. Regenerate `.env.local` before dev: same command as above.
+3. Commit only **`env.manifest.example`** (no secrets) so others know which keys exist.
+
+For **multiple keys, same value**, define one canonical key (`APP_ORIGIN`) and set:
+
+```text
+NEXT_PUBLIC_APP_URL=${APP_ORIGIN}
+VITE_PUBLIC_APP_URL=${APP_ORIGIN}
+```
+
+## 2. Vercel: pulling remote env into local files
+
+To align local dev with what is already on Vercel:
+
+```bash
+vercel env pull .env.vercel.local
+```
+
+Merge strategy (typical):
+
+- **Generated** `.env.local` from your manifest for **shared-value consistency**.
+- **Vercel-only** keys (e.g. `VERCEL_*`, analytics tokens) via `vercel env pull` into `.env.vercel.local` and load **both** (Next loads multiple `.env*` in priority order—see Next docs).
+
+If the same logical value must exist under two names **on Vercel**, the dashboard still needs **two entries** with the same string unless you use option 3 or 4.
+
+## 3. Pushing manifest-derived values to Vercel (scripted duplication)
+
+There is still **no native “link”** between keys on Vercel. A script can read the **expanded** map once and run the CLI for each name:
+
+```bash
+# Example pattern (run from app linked to Vercel):
+set -a && source .env.local && set +a
+echo -n "$NEXT_PUBLIC_APP_URL" | vercel env add NEXT_PUBLIC_APP_URL production
+echo -n "$VITE_PUBLIC_APP_URL" | vercel env add VITE_PUBLIC_APP_URL production
+```
+
+Use a **non-interactive token** (`VERCEL_TOKEN`) in CI only; avoid committing tokens. Prefer **Preview** vs **Production** environments explicitly.
+
+This is **intentional duplication in the cloud**, but **one edit** locally (manifest → expand → script loop).
+
+## 4. External secret managers (teams)
+
+If many projects and environments need DRY + audit:
+
+- **Doppler**, **Infisical**, **1Password Secrets Automation**, etc. can sync to Vercel and inject the **same** secret into multiple Vercel variable names (product-specific feature).
+
+Use this when shell scripts are not enough.
+
+## 5. Reduce duplication in *code*
+
+Sometimes two env vars exist for historical reasons. If both client and server can read the **same** name (e.g. only `NEXT_PUBLIC_*` where acceptable), prefer **one** variable in Vercel and one line in the manifest.
+
+## 6. Relation to Runctl’s `.run/ports.env`
+
+[`.run/ports.env`](../README.md) is for **dev server `PORT` / `HOST`**, not for Vercel deployment. Keep deployment secrets in `.env.local` / Vercel / a manifest as above.
+
+## Summary
+
+| Goal | Approach |
+|------|-----------|
+| Same value, many names **locally** | `env.manifest` + `expand-env-manifest.mjs` → `.env.local` |
+| Match Vercel → laptop | `vercel env pull` + merge with generated `.env.local` |
+| Same value, many names **on Vercel** | Duplicate in UI, or scripted `vercel env add`, or a secrets manager with Vercel sync |

package/examples/consumer-package.json

@@ -0,0 +1,11 @@
+{
+  "scripts": {
+    "dev": "runctl start --script dev:server",
+    "dev:server": "next dev",
+    "dev:stop": "runctl stop",
+    "dev:status": "runctl status",
+    "ports": "runctl ports",
+    "ports:gc": "runctl ports gc",
+    "env:expand": "runctl env expand env.manifest --out .env.local"
+  }
+}

package/examples/env.manifest.example

@@ -0,0 +1,13 @@
+# Canonical keys first, then aliases that share the same underlying value.
+# Use ${NAME} or ${NAME:-default}. Lines starting with # are comments.
+
+APP_ORIGIN=https://my-app.vercel.app
+API_BASE=https://api.example.com
+
+# Framework-specific names pointing at the same logical value:
+NEXT_PUBLIC_APP_URL=${APP_ORIGIN}
+VITE_PUBLIC_APP_URL=${APP_ORIGIN}
+PUBLIC_APP_URL=${APP_ORIGIN}
+
+NEXT_PUBLIC_API_URL=${API_BASE}
+VITE_API_URL=${API_BASE}

package/examples/run.sh.example

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Optional shell entrypoint — most projects only need package.json scripts.
+# Prerequisite: pnpm add -D runctl   (Node >= 18)
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT"
+
+if [[ -z "${RUN_LIB:-}" ]]; then
+  _rp="${RUNCTL_PACKAGE:-runctl}"
+  RUN_LIB="$(
+    cd "$ROOT" && RUNCTL_PACKAGE="$_rp" node -e "
+      const p = require('path');
+      const n = process.env.RUNCTL_PACKAGE;
+      console.log(p.join(p.dirname(require.resolve(n + '/package.json')), 'lib', 'run-lib.sh'));
+    "
+  )" || {
+    echo "run.sh: add runctl — pnpm add -D ${_rp}" >&2
+    exit 1
+  }
+fi
+[[ -f "$RUN_LIB" ]] || {
+  echo "run.sh: RUN_LIB missing: $RUN_LIB" >&2
+  exit 1
+}
+# shellcheck source=/dev/null
+source "$RUN_LIB"
+run_project_init "$ROOT"
+
+usage() {
+  cat <<'EOF'
+Usage: ./run.sh <command>
+
+  dev [name] [auto|PORT] [-- extra args]
+  stop              Stop daemons + release port claims
+  status            Local .run state + ports.env
+  install           pnpm install
+
+Examples:
+  ./run.sh dev
+  ./run.sh dev web auto -- --turbo
+EOF
+}
+
+cmd="${1:-dev}"
+shift || true
+
+case "$cmd" in
+  dev)
+    run_with_lock run_start_package_dev "$@"
+    ;;
+  stop)
+    run_stop_all
+    ;;
+  status)
+    run_local_status
+    ;;
+  install)
+    if command -v pnpm >/dev/null 2>&1; then
+      (cd "$ROOT" && pnpm install)
+    elif command -v npm >/dev/null 2>&1; then
+      (cd "$ROOT" && npm install)
+    else
+      echo "Install pnpm or npm" >&2
+      exit 1
+    fi
+    ;;
+  help | -h | --help)
+    usage
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac

package/lib/run-lib.sh

@@ -0,0 +1,514 @@
+#!/usr/bin/env bash
+# run-lib.sh — npm package `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.
+
+if [[ -z "${BASH_VERSION:-}" ]]; then
+  echo "run-lib.sh: must be sourced or executed with bash (not zsh)" >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+run_lib_dir() {
+  local _src="${BASH_SOURCE[0]:-$0}"
+  cd "$(dirname "$_src")" && pwd
+}
+
+# Override with RUN_GLOBAL_STATE=... if needed.
+: "${RUN_GLOBAL_STATE:=$HOME/.run}"
+
+run_slug() {
+  # Short stable id from absolute project path (no raw path in filenames).
+  local h=""
+  if command -v shasum >/dev/null 2>&1; then
+    h="$(printf '%s' "$1" | shasum -a 256 2>/dev/null | cut -c1-16)"
+  fi
+  if [[ -z "$h" ]] && command -v sha256sum >/dev/null 2>&1; then
+    h="$(printf '%s' "$1" | sha256sum 2>/dev/null | cut -c1-16)"
+  fi
+  if [[ -z "$h" ]] && command -v openssl >/dev/null 2>&1; then
+    h="$(printf '%s' "$1" | openssl dgst -sha256 2>/dev/null | awk '{print $2}' | cut -c1-16)"
+  fi
+  if [[ -z "$h" ]]; then
+    h="$(printf '%s' "${1//\//_}" | cksum 2>/dev/null | awk '{print $1}')"
+  fi
+  printf '%s' "${h:-unknown}"
+}
+
+run_project_init() {
+  RUN_PROJECT_ROOT="$(cd "${1:-.}" && pwd)"
+  export RUN_PROJECT_ROOT
+  RUN_LOCAL_STATE="$RUN_PROJECT_ROOT/.run"
+  RUN_PROJECT_SLUG="$(run_slug "$RUN_PROJECT_ROOT")"
+  export RUN_LOCAL_STATE RUN_PROJECT_SLUG RUN_GLOBAL_STATE
+  mkdir -p "$RUN_LOCAL_STATE/pids" "$RUN_LOCAL_STATE/logs" \
+    "$RUN_GLOBAL_STATE/ports" "$RUN_GLOBAL_STATE/projects"
+  [[ -f "$RUN_LOCAL_STATE/claimed-ports" ]] || : >"$RUN_LOCAL_STATE/claimed-ports"
+  _run_ensure_gitignore
+}
+
+_run_ensure_gitignore() {
+  local gi="$RUN_PROJECT_ROOT/.gitignore"
+  [[ -d "$RUN_PROJECT_ROOT/.git" ]] || return 0
+  if [[ ! -f "$gi" ]]; then
+    printf '# Runtime state (runctl)\n.run/\n' >"$gi"
+    return 0
+  fi
+  if ! grep -qxF '.run/' "$gi" && ! grep -qxF '.run' "$gi"; then
+    printf '\n# Runtime state (runctl)\n.run/\n' >>"$gi"
+  fi
+}
+
+run_lock_acquire() {
+  local lock="$RUN_LOCAL_STATE/lock"
+  local wait="${1:-50}"
+  local i=0
+  while ! mkdir "$lock" 2>/dev/null; do
+    sleep 0.05
+    i=$((i + 1))
+    if (( i > wait * 20 )); then
+      echo "run-lib: could not acquire lock: $lock" >&2
+      return 1
+    fi
+  done
+}
+
+run_lock_release() {
+  rmdir "$RUN_LOCAL_STATE/lock" 2>/dev/null || true
+}
+
+run_with_lock() {
+  run_lock_acquire 50
+  trap 'run_lock_release' EXIT
+  "$@"
+  local _ec=$?
+  trap - EXIT
+  run_lock_release
+  return "$_ec"
+}
+
+run_pid_alive() {
+  kill -0 "$1" 2>/dev/null
+}
+
+run_port_listening() {
+  local port="$1"
+  command -v lsof >/dev/null 2>&1 || return 1
+  lsof -iTCP:"$port" -sTCP:LISTEN -n -P >/dev/null 2>&1
+}
+
+run_find_free_port() {
+  local p="${1:-3000}"
+  local max="${2:-200}"
+  local i=0
+  while run_port_listening "$p" && (( i < max )); do
+    p=$((p + 1))
+    i=$((i + 1))
+  done
+  if run_port_listening "$p"; then
+    echo "run-lib: no free port from base ${1:-3000} after $max tries" >&2
+    return 1
+  fi
+  printf '%s' "$p"
+}
+
+# --- JS / Node dev servers (Vite, Next, Nuxt, Astro, etc.) -----------------
+
+run_require_node() {
+  command -v node >/dev/null 2>&1 || {
+    echo "runctl: Node.js is required (install Node >= 18; see runctl package engines)." >&2
+    return 1
+  }
+  node -e 'process.exit(parseInt(process.versions.node,10)>=18?0:1)' 2>/dev/null || {
+    echo "runctl: Node.js >= 18 is required (got $(node -v 2>/dev/null || echo none))." >&2
+    return 1
+  }
+}
+
+# True if package.json defines scripts.<name> (Node required).
+run_package_has_script() {
+  local name="$1"
+  [[ -f "$RUN_PROJECT_ROOT/package.json" ]] || return 1
+  node -e '
+    const fs = require("fs");
+    const path = require("path");
+    const root = process.argv[1];
+    const s = process.argv[2];
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    process.exit(pkg.scripts && Object.prototype.hasOwnProperty.call(pkg.scripts, s) ? 0 : 1);
+  ' "$RUN_PROJECT_ROOT" "$name" 2>/dev/null
+}
+
+run_detect_package_manager() {
+  local dir="${1:-$RUN_PROJECT_ROOT}"
+  [[ -d "$dir" ]] || {
+    echo "run_detect_package_manager: bad directory: $dir" >&2
+    return 1
+  }
+  if [[ -f "$dir/pnpm-lock.yaml" ]] && command -v pnpm >/dev/null 2>&1; then
+    printf '%s\n' pnpm
+    return 0
+  fi
+  if [[ -f "$dir/bun.lock" || -f "$dir/bun.lockb" ]] && command -v bun >/dev/null 2>&1; then
+    printf '%s\n' bun
+    return 0
+  fi
+  if [[ -f "$dir/yarn.lock" ]] && command -v yarn >/dev/null 2>&1; then
+    printf '%s\n' yarn
+    return 0
+  fi
+  if command -v npm >/dev/null 2>&1; then
+    printf '%s\n' npm
+    return 0
+  fi
+  echo "run-lib: install pnpm, yarn, or npm (prefer pnpm per repo lockfile)" >&2
+  return 1
+}
+
+# Prints one of: next | nuxt | astro | vite | remix | generic
+run_js_framework_kind() {
+  local pkg="$RUN_PROJECT_ROOT/package.json"
+  [[ -f "$pkg" ]] || {
+    printf '%s\n' generic
+    return 0
+  }
+  run_require_node || return 1
+  node -e "
+    const fs = require('fs');
+    const f = process.argv[1];
+    let pkg = {};
+    try { pkg = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { console.log('generic'); process.exit(0); }
+    const d = { ...pkg.dependencies, ...pkg.devDependencies };
+    const h = (n) => !!d[n];
+    if (h('next')) console.log('next');
+    else if (h('nuxt')) console.log('nuxt');
+    else if (h('astro')) console.log('astro');
+    else if (h('vite') || h('@vitejs/plugin-react') || h('@vitejs/plugin-vue') || h('@vitejs/plugin-svelte') || h('@sveltejs/vite-plugin-svelte'))
+      console.log('vite');
+    else if (h('@remix-run/dev')) console.log('remix');
+    else console.log('generic');
+  " "$pkg"
+}
+
+run_infer_dev_base_port() {
+  local k
+  k="$(run_js_framework_kind)" || return 1
+  case "$k" in
+    vite) printf '%s\n' 5173 ;;
+    astro) printf '%s\n' 4321 ;;
+    next | nuxt | remix | generic) printf '%s\n' 3000 ;;
+    *) printf '%s\n' 3000 ;;
+  esac
+}
+
+# Writes .run/ports.env for tooling and humans: source from repo root after start.
+run_write_ports_env() {
+  local port="$1"
+  local svc="${2:-web}"
+  mkdir -p "$RUN_LOCAL_STATE"
+  local host="${HOST:-127.0.0.1}"
+  umask 077
+  cat >"$RUN_LOCAL_STATE/ports.env" <<EOF
+# Generated by run-lib.sh — do not commit .run/
+# From repo root: set -a; source .run/ports.env; set +a
+PORT=$port
+RUN_DEV_PORT=$port
+RUN_DEV_SERVICE=$svc
+HOST=$host
+EOF
+  umask 022
+}
+
+# Start \`pnpm|yarn|npm run <script>\` in the background with a free port and register it.
+# Script name defaults to \`dev\`; set RUNCTL_PM_RUN_SCRIPT (e.g. dev:server) when \`dev\` is the runctl wrapper.
+# Usage: run_start_package_dev [service_name=web] [base_port|auto=auto] [extra args after script --]
+run_start_package_dev() {
+  run_require_node || return 1
+  [[ -f "$RUN_PROJECT_ROOT/package.json" ]] || {
+    echo "run_start_package_dev: no package.json in $RUN_PROJECT_ROOT" >&2
+    return 1
+  }
+  local svc="web"
+  local base_raw="auto"
+  if [[ $# -ge 1 ]]; then svc="$1"; shift; fi
+  if [[ $# -ge 1 ]]; then base_raw="$1"; shift; fi
+
+  local base_port
+  if [[ "$base_raw" == "auto" ]]; then
+    base_port="$(run_infer_dev_base_port)"
+  else
+    base_port="$base_raw"
+  fi
+
+  local port
+  port="$(run_find_free_port "$base_port")" || return 1
+
+  local pm kind
+  pm="$(run_detect_package_manager)" || return 1
+  kind="$(run_js_framework_kind)"
+
+  local -a dev_extra=()
+  case "$kind" in
+    next) dev_extra=(-p "$port") ;;
+    nuxt) dev_extra=(--port "$port") ;;
+    astro) dev_extra=(--port "$port") ;;
+    vite) dev_extra=(--port "$port" --strictPort) ;;
+    remix) dev_extra=(--port "$port") ;;
+    *) dev_extra=() ;;
+  esac
+
+  run_write_ports_env "$port" "$svc"
+
+  local host="${HOST:-127.0.0.1}"
+  local pm_script="${RUNCTL_PM_RUN_SCRIPT:-dev}"
+  # Many repos pair "predev" with script "dev". Using dev:server skips predev because only
+  # predev:server would run automatically. If predev exists but pre<pm_script> does not, run predev once.
+  if [[ "${RUNCTL_SKIP_PREDEV:-}" != "1" && "$pm_script" != "dev" ]]; then
+    if [[ "$pm_script" == dev:* || "$pm_script" == dev_* ]]; then
+      local pre_for_script="pre${pm_script}"
+      if ! run_package_has_script "$pre_for_script" && run_package_has_script "predev"; then
+        echo "run-lib: running predev before $pm_script ($pre_for_script not defined)"
+        (cd "$RUN_PROJECT_ROOT" && "$pm" run predev) || return 1
+      fi
+    fi
+  fi
+  echo "run-lib: [$kind] starting pm run $pm_script on PORT=$port (service=$svc, pm=$pm)"
+  local pid
+  pid="$(
+    run_daemon_start "$svc" \
+      bash -c 'cd "$1" && export PORT="$2" HOST="$3" && shift 3 && exec "$@"' \
+      _ "$RUN_PROJECT_ROOT" "$port" "$host" \
+      "$pm" run "$pm_script" -- "${dev_extra[@]}" "$@"
+  )" || return 1
+
+  run_port_register "$port" "$svc" "$pid"
+  printf '%s\n' "$port"
+}
+
+# Start a background service: name, then command + args.
+run_daemon_start() {
+  local name="$1"
+  shift
+  [[ $# -ge 1 ]] || {
+    echo "run_daemon_start: need name and command" >&2
+    return 1
+  }
+  mkdir -p "$RUN_LOCAL_STATE/pids" "$RUN_LOCAL_STATE/logs"
+  local pidf="$RUN_LOCAL_STATE/pids/${name}.pid"
+  local logf="$RUN_LOCAL_STATE/logs/${name}.log"
+  if [[ -f "$pidf" ]]; then
+    local oldpid
+    oldpid="$(cat "$pidf")"
+    if run_pid_alive "$oldpid"; then
+      echo "run_daemon_start: ${name} already running (pid $oldpid)" >&2
+      return 1
+    fi
+    rm -f "$pidf"
+    echo "run_daemon_start: cleared stale pid for ${name} (was $oldpid)" >&2
+  fi
+  nohup "$@" >>"$logf" 2>&1 &
+  local pid=$!
+  printf '%s\n' "$pid" >"$pidf"
+  printf '%s\n' "$pid"
+}
+
+run_daemon_stop() {
+  local name="$1"
+  local pidf="$RUN_LOCAL_STATE/pids/${name}.pid"
+  [[ -f "$pidf" ]] || return 0
+  local pid
+  pid="$(cat "$pidf")"
+  if run_pid_alive "$pid"; then
+    kill "$pid" 2>/dev/null || true
+    local n=0
+    while run_pid_alive "$pid" && (( n < 50 )); do
+      sleep 0.1
+      n=$((n + 1))
+    done
+    if run_pid_alive "$pid"; then
+      kill -9 "$pid" 2>/dev/null || true
+    fi
+  fi
+  rm -f "$pidf"
+}
+
+run_stop_all_daemons() {
+  local f base
+  shopt -s nullglob
+  for f in "$RUN_LOCAL_STATE/pids"/*.pid; do
+    base="$(basename "$f" .pid)"
+    run_daemon_stop "$base"
+  done
+  shopt -u nullglob
+}
+
+# Stop every local daemon and drop this project's port claims under ~/.run/ports/.
+run_stop_all() {
+  run_stop_all_daemons
+  run_unregister_project_ports
+}
+
+# Register a TCP port in the user-wide registry (~/.run/ports/<port>).
+run_port_register() {
+  local port="$1"
+  local service="${2:-app}"
+  local pid="${3:-}"
+  [[ -n "$port" ]] || return 1
+  local reg="$RUN_GLOBAL_STATE/ports/$port"
+  mkdir -p "$RUN_GLOBAL_STATE/ports"
+  {
+    echo "project_root=$RUN_PROJECT_ROOT"
+    echo "slug=$RUN_PROJECT_SLUG"
+    echo "service=$service"
+    echo "pid=$pid"
+    echo "started=$(date +%s)"
+  } >"$reg"
+  mkdir -p "$RUN_GLOBAL_STATE/projects/$RUN_PROJECT_SLUG"
+  printf '%s %s %s\n' "$port" "$service" "${pid:-}" >>"$RUN_GLOBAL_STATE/projects/$RUN_PROJECT_SLUG/ports.log"
+  # De-dup claimed-ports for this project
+  if ! grep -qx "$port" "$RUN_LOCAL_STATE/claimed-ports" 2>/dev/null; then
+    printf '%s\n' "$port" >>"$RUN_LOCAL_STATE/claimed-ports"
+  fi
+}
+
+run_port_unregister() {
+  local port="$1"
+  local reg="$RUN_GLOBAL_STATE/ports/$port"
+  [[ -f "$reg" ]] || return 0
+  # Only remove if it still points at this project
+  if grep -q "^project_root=$RUN_PROJECT_ROOT\$" "$reg" 2>/dev/null; then
+    rm -f "$reg"
+  fi
+}
+
+run_unregister_project_ports() {
+  local port
+  while IFS= read -r port; do
+    [[ -z "$port" ]] && continue
+    run_port_unregister "$port"
+  done <"$RUN_LOCAL_STATE/claimed-ports"
+  : >"$RUN_LOCAL_STATE/claimed-ports"
+}
+
+# Remove stale entries under ~/.run/ports (dead pid or wrong listener).
+run_global_gc() {
+  mkdir -p "$RUN_GLOBAL_STATE/ports"
+  local f port pid proot _line _k _v stale
+  shopt -s nullglob
+  for f in "$RUN_GLOBAL_STATE/ports"/*; do
+    [[ -f "$f" ]] || continue
+    port="$(basename "$f")"
+    [[ "$port" =~ ^[0-9]+$ ]] || continue
+    pid=""
+    proot=""
+    while IFS= read -r _line; do
+      [[ -z "$_line" ]] && continue
+      _k="${_line%%=*}"
+      _v="${_line#*=}"
+      case "$_k" in
+        pid) pid="$_v" ;;
+        project_root) proot="$_v" ;;
+      esac
+    done <"$f"
+    stale=0
+    if [[ -n "$pid" ]] && ! run_pid_alive "$pid"; then
+      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
+        stale=1
+      fi
+    fi
+    if [[ "$stale" -eq 1 ]]; then
+      rm -f "$f"
+      echo "run_global_gc: removed stale ~/.run/ports/$port"
+    fi
+  done
+  shopt -u nullglob
+}
+
+run_global_list_ports() {
+  mkdir -p "$RUN_GLOBAL_STATE/ports"
+  local f port tmp pid svc proot _line _k _v
+  tmp="$(mktemp "${TMPDIR:-/tmp}/runlib.XXXXXX")"
+  shopt -s nullglob
+  for f in "$RUN_GLOBAL_STATE/ports"/*; do
+    [[ -f "$f" ]] || continue
+    port="$(basename "$f")"
+    [[ "$port" =~ ^[0-9]+$ ]] || continue
+    pid="" svc="" proot=""
+    while IFS= read -r _line; do
+      [[ -z "$_line" ]] && continue
+      _k="${_line%%=*}"
+      _v="${_line#*=}"
+      case "$_k" in
+        pid) pid="$_v" ;;
+        service) svc="$_v" ;;
+        project_root) proot="$_v" ;;
+      esac
+    done <"$f"
+    printf '%s\t%s\t%s\t%s\n' "${port}" "${pid:--}" "${svc:--}" "${proot:--}" >>"$tmp"
+  done
+  shopt -u nullglob
+  printf '%-6s %-8s %-10s %s\n' "PORT" "PID" "SERVICE" "PROJECT"
+  printf '%-6s %-8s %-10s %s\n' "------" "--------" "----------" "-------"
+  if [[ -s "$tmp" ]]; then
+    sort -n "$tmp" | while IFS=$'\t' read -r port pid svc proot; do
+      printf '%-6s %-8s %-10s %s\n' "$port" "$pid" "$svc" "$proot"
+    done
+  else
+    printf '%s\n' "(no claimed ports)"
+  fi
+  rm -f "$tmp"
+}
+
+run_local_status() {
+  printf 'runctl status\n'
+  printf '  %-10s %s\n' "project:" "$RUN_PROJECT_ROOT"
+  printf '  %-10s %s\n' "slug:" "$RUN_PROJECT_SLUG"
+  printf '  %-10s %s\n' "state-dir:" "$RUN_LOCAL_STATE"
+  printf '\n'
+
+  local f base pid state
+  local has_services=0
+  printf 'services\n'
+  printf '  %-14s %-8s %-8s %s\n' "name" "pid" "state" "log"
+  printf '  %-14s %-8s %-8s %s\n' "--------------" "--------" "--------" "---"
+  shopt -s nullglob
+  for f in "$RUN_LOCAL_STATE/pids"/*.pid; do
+    has_services=1
+    base="$(basename "$f" .pid)"
+    pid="$(cat "$f")"
+    if run_pid_alive "$pid"; then
+      state="running"
+    else
+      state="stale"
+    fi
+    printf '  %-14s %-8s %-8s %s\n' "$base" "$pid" "$state" "$RUN_LOCAL_STATE/logs/${base}.log"
+  done
+  shopt -u nullglob
+  if [[ "$has_services" -eq 0 ]]; then
+    printf '  %s\n' "(none)"
+  fi
+
+  if [[ -s "$RUN_LOCAL_STATE/claimed-ports" ]]; then
+    printf '\n'
+    printf 'claimed ports\n'
+    sed 's/^/  - /' "$RUN_LOCAL_STATE/claimed-ports"
+  fi
+  if [[ -f "$RUN_LOCAL_STATE/ports.env" ]]; then
+    local env_port="" env_host="" env_service=""
+    while IFS= read -r line; do
+      case "$line" in
+        PORT=*) env_port="${line#PORT=}" ;;
+        HOST=*) env_host="${line#HOST=}" ;;
+        RUN_DEV_SERVICE=*) env_service="${line#RUN_DEV_SERVICE=}" ;;
+      esac
+    done <"$RUN_LOCAL_STATE/ports.env"
+    printf '\n'
+    printf 'last dev allocation\n'
+    [[ -n "$env_service" ]] && printf '  %-10s %s\n' "service:" "$env_service"
+    [[ -n "$env_port" ]] && printf '  %-10s %s\n' "port:" "$env_port"
+    [[ -n "$env_host" ]] && printf '  %-10s %s\n' "host:" "$env_host"
+    printf '  %-10s %s\n' "env-file:" "$RUN_LOCAL_STATE/ports.env"
+  fi
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zendero/runctl",
+  "version": "0.1.0",
+  "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/devport-kit#readme",
+  "bugs": "https://github.com/DoctorKhan/devport-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DoctorKhan/devport-kit.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "runctl",
+    "dev",
+    "dev-server",
+    "ports",
+    "pid",
+    "vercel",
+    "dotenv",
+    "vite",
+    "next"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "runctl": "bin/runctl"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "examples",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "run": "bash ./run.sh",
+    "env:expand": "node ./scripts/expand-env-manifest.mjs",
+    "link-global": "pnpm link --global"
+  }
+}

package/scripts/expand-env-manifest.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Expand a manifest of KEY=value lines where values may reference ${OTHER} or ${OTHER:-default}.
+ * Single source of truth for values shared across NEXT_PUBLIC_*, VITE_*, etc.
+ *
+ * Usage:
+ *   node scripts/expand-env-manifest.mjs path/to/env.manifest [--out .env.local] [--check]
+ *
+ * --check: verify all placeholders resolve (exit 1 if not); no write.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const re = /\$\{([^}:]+)(:-([^}]*))?\}/g;
+
+function parse(content) {
+  const raw = {};
+  for (const line of content.split("\n")) {
+    const t = line.replace(/\r$/, "").trimEnd();
+    const trimmed = t.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const k = trimmed.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) continue;
+    let v = trimmed.slice(eq + 1);
+    if (
+      (v.startsWith('"') && v.endsWith('"')) ||
+      (v.startsWith("'") && v.endsWith("'"))
+    ) {
+      v = v.slice(1, -1);
+    }
+    raw[k] = v;
+  }
+  return raw;
+}
+
+function expand(raw) {
+  const out = { ...raw };
+  const max = 64;
+  for (let pass = 0; pass < max; pass++) {
+    let changed = false;
+    for (const k of Object.keys(out)) {
+      const next = out[k].replace(re, (_, name, __, def) => {
+        if (Object.prototype.hasOwnProperty.call(out, name))
+          return String(out[name]);
+        if (def !== undefined) return def;
+        throw new Error(`Unresolved \${${name}} while expanding ${k}`);
+      });
+      if (next !== out[k]) {
+        out[k] = next;
+        changed = true;
+      }
+    }
+    if (!changed) {
+      for (const k of Object.keys(out)) {
+        re.lastIndex = 0;
+        if (re.test(out[k])) {
+          throw new Error(
+            `Unresolved or circular interpolation in ${k}: ${out[k]}`,
+          );
+        }
+      }
+      return out;
+    }
+  }
+  throw new Error("Circular or too-deep variable references in manifest");
+}
+
+function quoteForDotenv(val) {
+  if (/[\r\n#"'\\]/.test(val) || /\s/.test(val)) {
+    const esc = val.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return `"${esc}"`;
+  }
+  return val;
+}
+
+function formatEnv(out) {
+  const lines = [];
+  lines.push("# Generated by expand-env-manifest.mjs — do not edit by hand");
+  for (const k of Object.keys(out).sort()) {
+    lines.push(`${k}=${quoteForDotenv(out[k])}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function main() {
+  const major = Number.parseInt(process.versions.node.split(".")[0], 10);
+  if (major < 18) {
+    console.error("runctl: Node.js >= 18 is required (expand-env).");
+    process.exit(2);
+  }
+  const args = process.argv.slice(2);
+  let outPath = null;
+  let checkOnly = false;
+  const files = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--out") {
+      outPath = args[++i];
+      continue;
+    }
+    if (args[i] === "--check") {
+      checkOnly = true;
+      continue;
+    }
+    files.push(args[i]);
+  }
+  if (files.length !== 1) {
+    console.error(
+      "Usage: node expand-env-manifest.mjs <manifest> [--out <file>] [--check]",
+    );
+    process.exit(2);
+  }
+  const manifestPath = path.resolve(files[0]);
+  const text = fs.readFileSync(manifestPath, "utf8");
+  const raw = parse(text);
+  let out;
+  try {
+    out = expand(raw);
+  } catch (e) {
+    console.error(String(e.message || e));
+    process.exit(1);
+  }
+  re.lastIndex = 0;
+  if (checkOnly) {
+    console.log("OK — all references resolved.");
+    return;
+  }
+  const body = formatEnv(out);
+  if (outPath) {
+    fs.writeFileSync(path.resolve(outPath), body, "utf8");
+    console.error(`Wrote ${outPath}`);
+  } else {
+    process.stdout.write(body);
+  }
+}
+
+main();

package/scripts/install-global.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+# Install runctl globally (needs Node 18+ and npm or pnpm).
+#   curl -fsSL https://raw.githubusercontent.com/DoctorKhan/devport-kit/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"