@zendero/runctl 0.1.8 → 0.1.10

package/README.md

@@ -102,6 +102,14 @@ Use npm explicitly (e.g. no pnpm on the machine):
 curl -fsSL "https://raw.githubusercontent.com/DoctorKhan/runctl/main/scripts/install-global.sh" | bash -s -- --pm npm --registry
 ```
 
+If `runctl --help` still looks old after install/update, remove the legacy package that can shadow this CLI and reinstall:
+
+```bash
+pnpm remove -g runctl
+pnpm add -g @zendero/runctl@latest
+hash -r
+```
+
 `--help` on the script prints the same usage summary.
 
 ---
@@ -127,23 +135,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`
 
@@ -160,7 +182,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`). |
 
 ---
 
@@ -168,7 +190,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

@@ -16,12 +16,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 +30,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 +50,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 +80,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() {
@@ -330,6 +338,19 @@ cmd_update() {
   pm="$(cmd_update_pick_pm "$PM")" || exit 1
   git_target="${GIT_BASE}#${GIT_REF}"
 
+  _remove_conflicting_global_runctl() {
+    # A legacy package named "runctl" can own the same binary name and shadow @zendero/runctl.
+    # Best-effort remove before reinstalling the intended package.
+    if [[ "$PKG" != "@zendero/runctl" ]]; then
+      return 0
+    fi
+    if [[ "$pm" == "pnpm" ]]; then
+      pnpm remove -g runctl >/dev/null 2>&1 || true
+    else
+      npm uninstall -g runctl >/dev/null 2>&1 || true
+    fi
+  }
+
   _git_base_for_ls_remote() {
     local base="$1"
     printf '%s' "${base#git+}"
@@ -349,6 +370,7 @@ cmd_update() {
   _update_registry() {
     local spec="${PKG}@latest"
     echo "runctl update: installing latest from registry ($spec)..."
+    _remove_conflicting_global_runctl
     if [[ "$pm" == "pnpm" ]]; then
       pnpm add -g --force "$spec"
     else
@@ -366,6 +388,7 @@ cmd_update() {
       echo "runctl update: installing from Git ($git_target)..."
       echo "runctl update: could not resolve ref to SHA; proceeding with ref directly." >&2
     fi
+    _remove_conflicting_global_runctl
     if [[ "$pm" == "pnpm" ]]; then
       pnpm add -g --force "$spec"
     else
@@ -427,6 +450,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"
 }
 
@@ -441,7 +465,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
         ;;
@@ -455,10 +480,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
@@ -500,7 +528,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.8",
+  "version": "0.1.10",
   "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",

package/scripts/install-global.sh

@@ -132,10 +132,20 @@ run_install() {
   local source_kind="$2"
   local target="$3"
 
+  # A legacy package named "runctl" can shadow the same CLI binary.
+  # Remove it before installing @zendero/runctl.
+  if [[ "$PKG" == "@zendero/runctl" ]]; then
+    if [[ "$manager" == "pnpm" ]]; then
+      pnpm remove -g runctl >/dev/null 2>&1 || true
+    else
+      npm uninstall -g runctl >/dev/null 2>&1 || true
+    fi
+  fi
+
   if [[ "$manager" == "pnpm" ]]; then
-    pnpm add -g "$target"
+    pnpm add -g --force "$target"
   else
-    npm install -g "$target"
+    npm install -g --force "$target"
   fi
 
   say