@zendero/runctl 0.1.3 → 0.1.5

package/README.md

@@ -10,59 +10,100 @@ Picks a **free port**, runs your **dev server in the background**, and keeps **P
 
 ## Install
 
-The published package on npm is **`@zendero/runctl`**. The CLI binary on your PATH is still **`runctl`**.
+Published name on npm is **`@zendero/runctl`**; the CLI on your PATH is **`runctl`**.
 
-**From the npm registry (recommended):**
+| Goal | What to run |
+|------|-------------|
+| Use runctl **inside one repo** (recommended) | `pnpm add -D @zendero/runctl` — also `npm install -D` / `yarn add -D` |
+| **`runctl` everywhere** (global) | `pnpm add -g @zendero/runctl` or the curl installer below |
+| Track **main from GitHub** as a dev dependency | `pnpm add -D "github:DoctorKhan/runctl#main"` (still resolves as `@zendero/runctl`; reinstall to update) |
+
+### Global install: package manager vs script
+
+**Package manager** is the straightforward choice if you already use pnpm or npm:
 
 ```bash
-pnpm add -D @zendero/runctl          # or npm install -D / yarn add -D
+pnpm add -g @zendero/runctl
 ```
 
-**Global CLI** (`runctl` on your PATH everywhere):
+From Git only:
 
 ```bash
-pnpm add -g @zendero/runctl           # or npm install -g
+pnpm add -g "github:DoctorKhan/runctl#main"
 ```
 
-**Global install via curl** uses a single script: [`scripts/install-global.sh`](scripts/install-global.sh)
+**[`scripts/install-global.sh`](scripts/install-global.sh)** is for “one command” setup, **CI**, or when you want **npm first, then Git** without writing two install lines yourself. It requires **bash**, **pnpm or npm** on `PATH`, and network access.
+
+One-liner (same URL the script header documents):
 
 ```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
 ```
 
-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:
+Pass script arguments after `bash` (stdin pipe has no argv). To pick a **mode** explicitly:
 
 ```bash
-curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
-  bash -s -- --registry
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" | bash -s -- --registry
 ```
 
+### `install-global.sh` reference
+
+If you do **not** pass **`--registry`**, **`--git`**, **`--auto`**, or **`--interactive`**: on an **interactive TTY** with **`CI` not `1`**, the script **prompts** for install source (and related choices). Otherwise it behaves like **`--auto`**: **global install from the npm registry** first; if that fails, **retry from Git** (same URL/ref as `--git`).
+
+**Modes** — each mode picks *where* the global install comes from. Under the hood the script runs **`pnpm add -g …`** or **`npm install -g …`** once per successful path (auto can run **twice**: registry attempt, then Git if the first fails).
+
+| Mode | What it does | When to use it |
+|------|----------------|----------------|
+| **`--registry`** | **Only** installs `RUNCTL_PACKAGE` (default `@zendero/runctl`) from the npm registry. **No** Git fallback. | You want the published package only—e.g. CI that must not clone Git, or you know npm is enough. |
+| **`--git`** | **Only** installs from Git: `RUNCTL_GIT_BASE` + `#` + ref (default ref `main`, overridable with `--ref`). **No** registry attempt first. | You want `main`/a branch/tag from the repo, or the registry is unreachable. |
+| **`--auto`** | Tries **`--registry`** first; on **failure**, runs the same Git install as **`--git`**. | Headless installs, pipes, CI: resilient default when you’re fine with either source. |
+| **`--interactive`** | Prompts for **registry / git / auto**, optional **Git ref** when git/auto applies, and **pnpm vs npm** if both exist—**only** when a TTY is available. | You want to choose at install time instead of memorizing flags. |
+
+If **`--interactive`** is requested but there is **no usable TTY** (or `CI=1`), the script **falls back to `--auto`** and prints a short notice.
+
+**Flags**
+
+| Flag | Meaning |
+|------|---------|
+| `--pm pnpm` \| `--pm npm` | Use that package manager (must exist on `PATH`) |
+| `--ref <ref>` | Git ref for `--git` or for the Git step of `--auto` (default: `main`) |
+
+**Environment variables** (optional)
+
+| Variable | Purpose |
+|----------|---------|
+| `RUNCTL_PACKAGE` | npm package name (default: `@zendero/runctl`) |
+| `RUNCTL_GIT_BASE` | Git URL without fragment (default: `git+https://github.com/DoctorKhan/runctl.git`) |
+| `RUNCTL_GIT_REF` | Default ref when not overridden by `--ref` (default: `main`) |
+
+**Examples**
+
+Registry only (good for locked-down CI that should not hit Git):
+
 ```bash
-curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
-  bash -s -- --auto
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" | bash -s -- --registry
 ```
 
+Explicit auto (same as non-interactive default, but spelled out):
+
 ```bash
-curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" |
-  bash -s -- --git --ref main
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" | bash -s -- --auto
 ```
 
-Optional flags: `--pm pnpm|npm`, `--ref <git-ref>`. Optional env: `RUNCTL_PACKAGE`, `RUNCTL_GIT_BASE`, `RUNCTL_GIT_REF`.
-
-**Without curl:**
+Git only, specific ref:
 
 ```bash
-pnpm add -g @zendero/runctl
-pnpm add -g "github:DoctorKhan/runctl#main"
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" | bash -s -- --git --ref main
 ```
 
-**Project dependency from GitHub** (not global): dependency resolves to **`@zendero/runctl`**. Reinstall to pull the latest `main`:
+Use npm explicitly (e.g. no pnpm on the machine):
 
 ```bash
-pnpm add -D "github:DoctorKhan/runctl#main"
+curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" | bash -s -- --pm npm --registry
 ```
 
+`--help` on the script prints the same usage summary.
+
 ---
 
 ## Quick start
@@ -95,12 +136,13 @@ Add scripts to your `package.json`:
 | `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 ps` | List running programs with PID, port, service, project |
 | `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 doctor [dir]` | Check Node 18+, `lsof`, package manager, `package.json` |
-| `runctl update` | Update the global `@zendero/runctl` install |
+| `runctl update` | Refresh global CLI: default **`auto`** (npm `@latest`, then Git). **`runctl update npm`** / **`git`** / **`auto`** or flags **`--registry`** / **`--git`** / **`--auto`**; **`runctl update --help`**; env `RUNCTL_PACKAGE`, `RUNCTL_GIT_BASE`, `RUNCTL_GIT_REF` (aligned with [`install-global.sh`](scripts/install-global.sh)) |
 | `runctl version` | Print package version and install path |
 
 **Monorepo:** `runctl start ./apps/web --script dev:server`

package/bin/runctl

@@ -20,12 +20,13 @@ ${_y}Commands${_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}ps${_r}                            List running programs with ports/projects
   ${_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
+  ${_c}update${_r} [npm|git|auto] [opts]  Update global runctl ${_d}(default: auto; see runctl update --help)${_r}
 
 ${_y}Options${_r}
   ${_c}--script${_r} <name>               Package script to run ${_d}(default: dev)${_r}
@@ -156,6 +157,23 @@ cmd_ports() {
   esac
 }
 
+cmd_ps() {
+  # shellcheck source=../lib/run-lib.sh
+  source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
+  run_global_list_running
+  local stale="${RUN_LAST_STALE_COUNT:-0}"
+  if [[ "$stale" =~ ^[0-9]+$ ]] && (( stale > 0 )); then
+    echo ""
+    echo "runctl ps: found $stale stale registry entr$( (( stale == 1 )) && echo "y" || echo "ies" ); cleaning..."
+    (run_global_gc >/dev/null 2>&1) &
+    local gc_pid=$!
+    wait "$gc_pid" || true
+    echo "runctl ps: refreshed"
+    echo ""
+    run_global_list_running
+  fi
+}
+
 cmd_env() {
   local sub="${1:-}"
   shift || true
@@ -174,16 +192,182 @@ cmd_env() {
   esac
 }
 
-cmd_update() {
-  echo "runctl update: installing latest @zendero/runctl..."
+cmd_update_usage() {
+  cat <<EOF
+${_b}runctl update${_r} — refresh the global CLI (pnpm/npm global install)
+
+${_y}Usage:${_r}  runctl update [npm|git|auto] [options]
+
+${_y}Source${_r} ${_d}(pick one; default when omitted: ${_c}auto${_r})${_r}
+  ${_c}npm${_r} | ${_c}--registry${_r}   Latest from npm only (${_d}${RUNCTL_PACKAGE:-@zendero/runctl}@latest${_r})
+  ${_c}git${_r} | ${_c}--git${_r}         From Git only (${_d}RUNCTL_GIT_BASE + ref${_r})
+  ${_c}auto${_r} | ${_c}--auto${_r}      Try npm @latest, then Git if that fails
+
+${_y}Options${_r}
+  ${_c}--pm${_r} ${_d}pnpm|npm${_r}     Package manager ${_d}(default: pnpm if on PATH, else npm)${_r}
+  ${_c}--ref${_r} ${_d}<ref>${_r}      Git ref for --git / Git fallback ${_d}(default: RUNCTL_GIT_REF or main)${_r}
+  ${_c}-h${_r}, ${_c}--help${_r}              This help
+
+${_y}Environment${_r} ${_d}(optional; same as install-global.sh)${_r}
+  RUNCTL_PACKAGE   npm name ${_d}(default: @zendero/runctl)${_r}
+  RUNCTL_GIT_BASE  Git URL without fragment ${_d}(default: git+https://github.com/DoctorKhan/runctl.git)${_r}
+  RUNCTL_GIT_REF   default Git ref ${_d}(default: main)${_r}
+EOF
+}
+
+cmd_update_pick_pm() {
+  if [[ -n "$1" ]]; then
+    case "$1" in
+      pnpm | npm) ;;
+      *)
+        echo "runctl update: unsupported --pm: $1 (use pnpm or npm)" >&2
+        return 1
+        ;;
+    esac
+    if ! command -v "$1" >/dev/null 2>&1; then
+      echo "runctl update: package manager not on PATH: $1" >&2
+      return 1
+    fi
+    printf '%s' "$1"
+    return 0
+  fi
   if command -v pnpm >/dev/null 2>&1; then
-    pnpm add -g @zendero/runctl@latest
-  elif command -v npm >/dev/null 2>&1; then
-    npm install -g @zendero/runctl@latest
-  else
-    echo "runctl: pnpm or npm required to update." >&2
+    printf 'pnpm'
+    return 0
+  fi
+  if command -v npm >/dev/null 2>&1; then
+    printf 'npm'
+    return 0
+  fi
+  echo "runctl update: pnpm or npm required on PATH." >&2
+  return 1
+}
+
+cmd_update() {
+  local MODE="" PM="" GIT_REF="${RUNCTL_GIT_REF:-main}"
+  local PKG="${RUNCTL_PACKAGE:-@zendero/runctl}"
+  local GIT_BASE="${RUNCTL_GIT_BASE:-git+https://github.com/DoctorKhan/runctl.git}"
+  local -a POS=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --registry)
+        MODE="registry"
+        shift
+        ;;
+      --git)
+        MODE="git"
+        shift
+        ;;
+      --auto)
+        MODE="auto"
+        shift
+        ;;
+      --pm)
+        [[ $# -ge 2 ]] || {
+          echo "runctl update: --pm requires a value" >&2
+          exit 1
+        }
+        PM="$2"
+        shift 2
+        ;;
+      --ref)
+        [[ $# -ge 2 ]] || {
+          echo "runctl update: --ref requires a value" >&2
+          exit 1
+        }
+        GIT_REF="$2"
+        shift 2
+        ;;
+      -h | --help)
+        cmd_update_usage
+        exit 0
+        ;;
+      -*)
+        echo "runctl update: unknown option: $1" >&2
+        cmd_update_usage >&2
+        exit 1
+        ;;
+      *)
+        POS+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  local POS_MODE=""
+  if [[ ${#POS[@]} -gt 1 ]]; then
+    echo "runctl update: too many arguments (${POS[*]}). Use at most one of: npm, git, auto" >&2
+    exit 1
+  fi
+  if [[ ${#POS[@]} -eq 1 ]]; then
+    case "${POS[0]}" in
+      npm)
+        POS_MODE="registry"
+        ;;
+      git)
+        POS_MODE="git"
+        ;;
+      auto)
+        POS_MODE="auto"
+        ;;
+      *)
+        echo "runctl update: unknown argument: ${POS[0]} (expected: npm, git, auto — runctl update --help)" >&2
+        exit 1
+        ;;
+    esac
+  fi
+  if [[ -n "$MODE" && -n "$POS_MODE" && "$MODE" != "$POS_MODE" ]]; then
+    echo "runctl update: conflicting source (npm/git/auto vs --registry/--git/--auto)" >&2
     exit 1
   fi
+  if [[ -n "$POS_MODE" ]]; then
+    MODE="$POS_MODE"
+  fi
+  [[ -n "$MODE" ]] || MODE="auto"
+
+  local pm git_target
+  pm="$(cmd_update_pick_pm "$PM")" || exit 1
+  git_target="${GIT_BASE}#${GIT_REF}"
+
+  _update_registry() {
+    local spec="${PKG}@latest"
+    echo "runctl update: installing latest from registry ($spec)..."
+    if [[ "$pm" == "pnpm" ]]; then
+      pnpm add -g "$spec"
+    else
+      npm install -g "$spec"
+    fi
+  }
+
+  _update_git() {
+    echo "runctl update: installing from Git ($git_target)..."
+    if [[ "$pm" == "pnpm" ]]; then
+      pnpm add -g "$git_target"
+    else
+      npm install -g "$git_target"
+    fi
+  }
+
+  case "$MODE" in
+    registry)
+      _update_registry
+      ;;
+    git)
+      _update_git
+      ;;
+    auto)
+      if _update_registry; then
+        return 0
+      fi
+      echo "runctl update: registry install failed; trying Git..." >&2
+      _update_git
+      ;;
+    *)
+      echo "runctl update: internal error: unknown mode $MODE" >&2
+      exit 1
+      ;;
+  esac
 }
 
 cmd_doctor() {
@@ -283,11 +467,12 @@ main() {
     open)     cmd_open "$@" ;;
     stop)     cmd_stop "$@" ;;
     status)   cmd_status "$@" ;;
+    ps)       cmd_ps "$@" ;;
     logs)     cmd_logs "$@" ;;
     ports)    cmd_ports "$@" ;;
     env)      cmd_env "$@" ;;
     doctor)   cmd_doctor "$@" ;;
-    update)   cmd_update ;;
+    update)   cmd_update "$@" ;;
 
     # Plumbing
     lib-path) printf '%s\n' "$RUNCTL_PKG_ROOT/lib/run-lib.sh" ;;

package/lib/run-lib.sh

@@ -501,6 +501,64 @@ run_global_list_ports() {
   rm -f "$tmp"
 }
 
+run_pid_program_name() {
+  local pid="$1"
+  [[ -n "$pid" ]] || return 1
+  ps -p "$pid" -o comm= 2>/dev/null | awk '{$1=$1; print}'
+}
+
+run_global_list_running() {
+  mkdir -p "$RUN_GLOBAL_STATE/ports"
+  local f port tmp pid svc proot _line _k _v prog stale_count
+  stale_count=0
+  tmp="$(mktemp "${TMPDIR:-/tmp}/runlib-running.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="" prog=""
+    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"
+    if [[ -z "$pid" ]]; then
+      stale_count=$((stale_count + 1))
+      continue
+    fi
+    if ! run_pid_alive "$pid"; then
+      stale_count=$((stale_count + 1))
+      continue
+    fi
+    if ! run_pid_listens_on_port "$pid" "$port"; then
+      stale_count=$((stale_count + 1))
+      continue
+    fi
+    prog="$(run_pid_program_name "$pid" || true)"
+    [[ -n "$prog" ]] || prog="(unknown)"
+    printf '%s\t%s\t%s\t%s\t%s\n' "$pid" "$prog" "$port" "${svc:--}" "${proot:--}" >>"$tmp"
+  done
+  shopt -u nullglob
+  printf '%-8s %-20s %-6s %-10s %s\n' "PID" "PROGRAM" "PORT" "SERVICE" "PROJECT"
+  printf '%-8s %-20s %-6s %-10s %s\n' "--------" "--------------------" "------" "----------" "-------"
+  if [[ -s "$tmp" ]]; then
+    sort -n -k1,1 "$tmp" | while IFS=$'\t' read -r pid prog port svc proot; do
+      printf '%-8s %-20s %-6s %-10s %s\n' "$pid" "$prog" "$port" "$svc" "$proot"
+    done
+  else
+    printf '%s\n' "(no running programs)"
+  fi
+  rm -f "$tmp"
+  RUN_LAST_STALE_COUNT="$stale_count"
+  export RUN_LAST_STALE_COUNT
+}
+
 run_local_status() {
   printf 'runctl status\n'
   printf '  %-10s %s\n' "project:" "$RUN_PROJECT_ROOT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendero/runctl",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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,7 @@
   ],
   "scripts": {
     "run": "bash ./run.sh",
+    "test": "bash ./tests/runctl-ps.test.sh",
     "doctor": "bash ./run.sh doctor",
     "release-check": "bash ./run.sh release-check",
     "promote": "bash ./run.sh promote",