@zendero/runctl 0.1.9 → 0.1.11

package/README.md

@@ -110,7 +110,11 @@ pnpm add -g @zendero/runctl@latest
 hash -r
 ```
 
-`--help` on the script prints the same usage summary.
+### `runctl update` and pnpm version messages
+
+If pnpm nags about versions or **`pnpm self-update`** does nothing useful, **`runctl update --help`** explains why and lists concrete fixes (same text is summarized after a successful pnpm-based update unless **`CI`** or **`RUNCTL_UPDATE_SKIP_PNPM_HINT=1`**).
+
+`--help` on the install script prints the same usage summary.
 
 ---
 
@@ -135,23 +139,37 @@ Add scripts to your `package.json`:
 
 **`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.
 
+**Dashboard / API-only (split names):** Avoid `runctl start --script dev` when `dev` is the runctl wrapper — that loops. Use a dedicated script for the real server:
+
+```json
+{
+  "scripts": {
+    "dev": "runctl start --script dev:workbench",
+    "dev:workbench": "node --env-file=.env src/dashboard/server.js",
+    "dev:stop": "runctl stop"
+  }
+}
+```
+
+Listen on `process.env.PORT` (runctl sets it). Optional: `runctl start --script dev:workbench --open` to open the browser after start, or `runctl start … && runctl open .`.
+
 ---
 
 ## Commands
 
 | Command | What it does |
 |---------|-------------|
-| `runctl start` \| `runctl dev` | Start dev server (same command; picks free port, backgrounds) |
+| `runctl start` \| `runctl dev` | Start dev server (same command; picks free port, backgrounds). Flags: `--script`, `--open` (open browser after a successful start) |
 | `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 logs [dir] [service]` | Tail `.run/logs/<service>.log` (default service: **`RUNCTL_SERVICE`**, else `package.json` `name` basename, else `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 doctor [dir]` | Check Node 18+, `lsof`, package manager, `package.json`; reminds that child scripts get **`PORT`** / **`HOST`** (custom servers should `listen` on `process.env.PORT`) |
 | `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 |
+| `runctl version` \| `runctl --version` \| `runctl -v` | Print package version and install path (supported interchangeably) |
 
 **Monorepo:** `runctl start ./apps/web --script dev:server`
 
@@ -168,7 +186,7 @@ Add scripts to your `package.json`:
 | **`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. |
+| Custom Node entry (gateways, CLIs) | **Weak fit** — `PORT`/`HOST` are injected; bind with `server.listen(process.env.PORT)` (see `runctl doctor`). |
 
 ---
 
@@ -176,7 +194,13 @@ 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` (default **doctor**, like `elata-bio-sdk/run.sh`) → `./run.sh ports`
+**CLI vs `run-lib.sh`:** Most apps only need the **`runctl`** binary and `package.json` scripts. For shell-heavy repos, [`examples/run.sh.example`](examples/run.sh.example) shows sourcing **`lib/run-lib.sh`** (same library the CLI uses). Resolve the installed path with **`runctl lib-path`**.
+
+**CI:** Prefer **`pnpm add -D @zendero/runctl`** (or a global install) so `runctl` is on `PATH` with a stable version. **`pnpm dlx @zendero/runctl`** is fine for one-off recovery; avoid relying on it for every CI job (cold cache / latency).
+
+**Roadmap (ideas):** `runctl exec` (one-off commands with the same port / `.run` contract as `start`); optional HTTP health gate before “ready”.
+
+**Develop this repo:** `pnpm install` → `./run.sh` (default **doctor**, like `elata-bio-sdk/run.sh`) → `./run.sh ports` · **`pnpm test`** runs [`tests/run-all.sh`](tests/run-all.sh) (Jest-style output: suites, ✓/✗, `PASS`/`FAIL` per file, shared helpers in [`tests/lib/test-runner.sh`](tests/lib/test-runner.sh))
 
 **Publish (maintainers)** — workflow similar to elata’s release preflight, scaled for one package:
 

package/bin/runctl

@@ -3,6 +3,71 @@
 set -euo pipefail
 RUNCTL_PKG_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)"
 
+# Volta resolves pnpm from the *current* project's packageManager for `pnpm -v`, but
+# `pnpm add -g` uses the default global pnpm (often older). Run pnpm as this package
+# defines it: Corepack reads packageManager from $RUNCTL_PKG_ROOT/package.json (no
+# duplicated version in shell). If Corepack is missing, fall back to npm exec with
+# the same field, then plain pnpm on PATH.
+_runctl_read_pnpm_version_from_package_json() {
+  node -e '
+    const fs = require("fs");
+    const p = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    const pm = p.packageManager || "";
+    const m = /^pnpm@([0-9]+(?:\.[0-9]+){0,2})/.exec(pm);
+    process.stdout.write(m ? m[1] : "");
+  ' "$RUNCTL_PKG_ROOT/package.json" 2>/dev/null || true
+}
+
+# Shown after runctl update (pnpm) and in --help. pnpm often suggests "pnpm self-update" but that
+# updates a different notion of "current" than the pnpm used for global -g installs (Volta/Corepack).
+_runctl_print_pnpm_version_fixup_hint() {
+  local ver
+  ver="$(_runctl_read_pnpm_version_from_package_json)"
+  [[ -n "$ver" ]] || ver="X.Y.Z"
+  cat >&2 <<EOF
+
+runctl update: pnpm may show "Update available" or tell you to run pnpm self-update; self-update
+often does nothing useful here: it follows your project packageManager, while global installs use a
+separate default pnpm. If the footer still shows an older pnpm than you expect, fix that default — do
+not rely on pnpm self-update alone. Replace ${ver} with the version you want (match package.json).
+
+  volta install pnpm@${ver}
+  corepack enable && corepack prepare pnpm@${ver} --activate
+  RUNCTL_PNPM_VERSION=${ver} runctl update git
+  runctl update --pm npm
+
+Hide this hint: RUNCTL_UPDATE_SKIP_PNPM_HINT=1  (also suppressed when CI is set.)
+EOF
+}
+
+_runctl_maybe_print_pnpm_update_hint() {
+  local pm="$1"
+  [[ "$pm" == "pnpm" ]] || return 0
+  [[ -z "${RUNCTL_UPDATE_SKIP_PNPM_HINT:-}" ]] || return 0
+  [[ -z "${CI:-}" ]] || return 0
+  _runctl_print_pnpm_version_fixup_hint
+}
+
+_runctl_pnpm_exec() {
+  if command -v corepack >/dev/null 2>&1; then
+    if (cd "$RUNCTL_PKG_ROOT" && corepack pnpm "$@"); then
+      return 0
+    fi
+    echo "runctl update: warning: corepack pnpm failed; trying npm exec / PATH pnpm" >&2
+  fi
+  local ver="${RUNCTL_PNPM_VERSION:-}"
+  if [[ -z "$ver" ]]; then
+    ver="$(_runctl_read_pnpm_version_from_package_json)"
+  fi
+  if [[ -n "$ver" ]] && command -v npm >/dev/null 2>&1; then
+    if npm exec -y "pnpm@${ver}" -- "$@"; then
+      return 0
+    fi
+    echo "runctl update: warning: npm exec pnpm@${ver} failed; falling back to pnpm on PATH" >&2
+  fi
+  command pnpm "$@"
+}
+
 _b="" _d="" _r="" _c="" _y="" _g=""
 if [[ -t 1 ]]; then
   _b=$'\033[1m' _d=$'\033[2m' _r=$'\033[0m'
@@ -16,12 +81,12 @@ ${_b}runctl${_r} — dev-server orchestrator & port manager
 ${_y}Usage:${_r}  runctl <command> [options]
 
 ${_y}Commands${_r}
-  ${_c}start${_r} | ${_c}dev${_r} [dir] [--script name]  Start dev server ${_d}(alias: dev = start)${_r}
+  ${_c}start${_r} | ${_c}dev${_r} [dir] [--script name] [--open]  Start dev server ${_d}(alias: dev = start; ${_c}--open${_r} = browser after 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}ps${_r}                            List running programs with ports/projects
-  ${_c}logs${_r} [dir] [service]         Tail .run/logs/<service>.log ${_d}(default service: web)${_r}
+  ${_c}logs${_r} [dir] [service]         Tail .run/logs/<service>.log ${_d}(default: ${_c}RUNCTL_SERVICE${_r} or package name, else 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
@@ -30,6 +95,8 @@ ${_y}Commands${_r}
 
 ${_y}Options${_r}
   ${_c}--script${_r} <name>               Package script to run ${_d}(default: dev)${_r}
+  ${_c}--open${_r}                        After a successful start, open the app URL ${_d}(same as ${_c}runctl open${_r})${_r}
+  ${_c}version${_r} | ${_c}--version${_r} | ${_c}-v${_r}     Print version and install path
   ${_c}--help${_r}, ${_c}-h${_r}                     Show this help
 
 ${_d}Quick start — add to package.json:
@@ -48,12 +115,13 @@ _resolve_proj() {
 }
 
 cmd_start() {
-  local proj script="" args=()
+  local proj script="" args=() open_after=0
   proj="$(pwd)"
 
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --script) script="${2:-}"; shift 2 ;;
+      --open) open_after=1; shift ;;
       --) shift; args+=("$@"); break ;;
       -h | --help) usage; exit 0 ;;
       -*)
@@ -77,7 +145,12 @@ cmd_start() {
   # 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[@]}"}"
+  if ! run_with_lock run_start_package_dev "${args[@]+"${args[@]}"}"; then
+    return 1
+  fi
+  if [[ "$open_after" -eq 1 ]]; then
+    cmd_open "$proj"
+  fi
 }
 
 cmd_open() {
@@ -212,6 +285,22 @@ ${_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}
+  RUNCTL_PNPM_VERSION  Force pnpm version for npm-exec fallback ${_d}(e.g. 10.33.0)${_r}
+  RUNCTL_UPDATE_SKIP_PNPM_HINT  Set to ${_c}1${_r} to hide the post-update pnpm version hint ${_d}(CI also hides)${_r}
+
+${_y}pnpm version / “pnpm self-update” does nothing${_r}
+  pnpm often prints an upgrade banner or suggests ${_c}pnpm self-update${_r}. That advice targets the
+  project ${_c}packageManager${_r} pin; ${_c}pnpm add -g${_r} uses a ${_b}different${_r} default pnpm
+  (e.g. Volta’s global toolchain). So self-update may say you are already on 10.33.0 while the footer
+  still shows 10.27.0 — both can be “true.” Fix the ${_b}global${_r} default, not self-update alone:
+
+  ${_c}volta install pnpm@<version>${_r}   ${_d}match your repo / Volta default${_r}
+  ${_c}corepack enable && corepack prepare pnpm@<version> --activate${_r}
+  ${_c}RUNCTL_PNPM_VERSION=<version> runctl update git${_r}
+  ${_c}runctl update --pm npm${_r}   ${_d}use npm for this install instead${_r}
+
+  A short hint is printed after a successful ${_c}runctl update${_r} with pnpm unless ${_c}CI${_r} is set
+  or ${_c}RUNCTL_UPDATE_SKIP_PNPM_HINT=1${_r}.
 EOF
 }
 
@@ -337,7 +426,7 @@ cmd_update() {
       return 0
     fi
     if [[ "$pm" == "pnpm" ]]; then
-      pnpm remove -g runctl >/dev/null 2>&1 || true
+      _runctl_pnpm_exec remove -g runctl >/dev/null 2>&1 || true
     else
       npm uninstall -g runctl >/dev/null 2>&1 || true
     fi
@@ -364,7 +453,7 @@ cmd_update() {
     echo "runctl update: installing latest from registry ($spec)..."
     _remove_conflicting_global_runctl
     if [[ "$pm" == "pnpm" ]]; then
-      pnpm add -g --force "$spec"
+      _runctl_pnpm_exec add -g --force "$spec"
     else
       npm install -g --force "$spec"
     fi
@@ -382,7 +471,7 @@ cmd_update() {
     fi
     _remove_conflicting_global_runctl
     if [[ "$pm" == "pnpm" ]]; then
-      pnpm add -g --force "$spec"
+      _runctl_pnpm_exec add -g --force "$spec"
     else
       npm install -g --force "$spec"
     fi
@@ -396,17 +485,18 @@ cmd_update() {
       _update_git
       ;;
     auto)
-      if _update_registry; then
-        return 0
+      if ! _update_registry; then
+        echo "runctl update: registry install failed; trying Git..." >&2
+        _update_git
       fi
-      echo "runctl update: registry install failed; trying Git..." >&2
-      _update_git
       ;;
     *)
       echo "runctl update: internal error: unknown mode $MODE" >&2
       exit 1
       ;;
   esac
+
+  _runctl_maybe_print_pnpm_update_hint "$pm"
 }
 
 cmd_doctor() {
@@ -442,6 +532,7 @@ cmd_doctor() {
     printf '  %-12s %s\n' "package.json:" "not found in $proj" >&2
     ec=1
   fi
+  printf '  %-12s %s\n' "child env:" "PORT and HOST are set for package scripts; custom Node servers should listen on process.env.PORT (and bind HOST if needed)."
   return "$ec"
 }
 
@@ -456,7 +547,8 @@ cmd_logs() {
         shift 2
         ;;
       -h | --help)
-        echo "Usage: runctl logs [dir] [service]  (default service: web)" >&2
+        echo "Usage: runctl logs [dir] [service]" >&2
+        echo "       Default service: RUNCTL_SERVICE, else package.json name, else web." >&2
         echo "       runctl logs [--lines N]" >&2
         exit 0
         ;;
@@ -470,10 +562,13 @@ cmd_logs() {
     proj="$(cd "${pos[0]}" && pwd)"
     pos=("${pos[@]:1}")
   fi
-  local svc="${pos[0]:-web}"
+  local svc="${pos[0]:-}"
   # shellcheck source=../lib/run-lib.sh
   source "$RUNCTL_PKG_ROOT/lib/run-lib.sh"
   run_project_init "$proj"
+  if [[ -z "$svc" ]]; then
+    svc="$(run_default_service_name)"
+  fi
   local logf="$RUN_LOCAL_STATE/logs/${svc}.log"
   if [[ ! -f "$logf" ]]; then
     echo "runctl logs: no file at $logf" >&2
@@ -515,7 +610,7 @@ main() {
 
     # Plumbing
     lib-path) printf '%s\n' "$RUNCTL_PKG_ROOT/lib/run-lib.sh" ;;
-    version | -v) cmd_version_print ;;
+    version | -v | --version) cmd_version_print ;;
     help | -h | --help) usage ;;
 
     # Hidden backward-compat aliases

package/examples/run.sh.example

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # Optional shell entrypoint — most projects only need package.json scripts.
 # Prerequisite: pnpm add -D @zendero/runctl   (Node >= 18)
+#
+# When to use this vs the runctl CLI:
+#   - Prefer `runctl start` / package.json scripts (see README) for normal dev.
+#   - Source lib/run-lib.sh (this file) for advanced shell integration: custom
+#     wrappers, CI, or repos that already drive everything through ./run.sh.
+#   Shipped path: package `lib/run-lib.sh` (see `runctl lib-path`).
 
 set -euo pipefail
 

package/lib/run-lib.sh

@@ -2,6 +2,7 @@
 # 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.
+# Consumer shell example: examples/run.sh.example (most projects use the `runctl` CLI instead).
 
 if [[ -z "${BASH_VERSION:-}" ]]; then
   echo "run-lib.sh: must be sourced or executed with bash (not zsh)" >&2
@@ -146,6 +147,50 @@ run_require_node() {
   }
 }
 
+# Basename for .run/logs/<name>.log and RUN_DEV_SERVICE — override with RUNCTL_SERVICE.
+run_sanitize_service_name() {
+  local s="${1:-web}"
+  s="${s//[^a-zA-Z0-9._-]/-}"
+  s="$(printf '%s' "$s" | sed 's/^-*//;s/-*$//')"
+  [[ -z "$s" ]] && s="web"
+  printf '%s\n' "$s"
+}
+
+run_default_service_name() {
+  if [[ -n "${RUNCTL_SERVICE:-}" ]]; then
+    run_sanitize_service_name "${RUNCTL_SERVICE}"
+    return 0
+  fi
+  [[ -f "$RUN_PROJECT_ROOT/package.json" ]] || {
+    printf '%s\n' web
+    return 0
+  }
+  command -v node >/dev/null 2>&1 || {
+    printf '%s\n' web
+    return 0
+  }
+  node -e '
+    const fs = require("fs");
+    const path = require("path");
+    const root = process.argv[1];
+    let pkg = {};
+    try {
+      pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    } catch {
+      process.stdout.write("web" + "\n");
+      process.exit(0);
+    }
+    const n = pkg.name;
+    if (typeof n !== "string" || !n) {
+      process.stdout.write("web" + "\n");
+      process.exit(0);
+    }
+    const base = n.includes("/") ? n.split("/").pop() : n;
+    const safe = String(base).replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "web";
+    process.stdout.write(safe + "\n");
+  ' "$RUN_PROJECT_ROOT" 2>/dev/null || printf '%s\n' web
+}
+
 # True if package.json defines scripts.<name> (Node required).
 run_package_has_script() {
   local name="$1"
@@ -242,14 +287,16 @@ EOF
 
 # 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 --]
+# Default service name: RUNCTL_SERVICE, else package.json name (basename), else web — see run_default_service_name.
+# Usage: run_start_package_dev [service_name] [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 svc
+  svc="$(run_default_service_name)"
   local base_raw="auto"
   if [[ $# -ge 1 ]]; then svc="$1"; shift; fi
   if [[ $# -ge 1 ]]; then base_raw="$1"; shift; fi

package/package.json

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