@zendero/runctl 0.1.11 → 0.1.13

package/README.md

@@ -196,11 +196,13 @@ Listen on `process.env.PORT` (runctl sets it). Optional: `runctl start --script
 
 **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`**.
 
+**Scaffold `run.sh`:** `runctl run-sh --write` writes that example to `./run.sh` (honors `RUNCTL_PROJECT_ROOT`; use `-C dir` for another directory). Use `--force` to replace an existing file. Equivalent to redirecting `runctl run-sh` to `run.sh`, but also sets the executable bit.
+
 **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))
+**Develop this repo:** `pnpm install` → `./run.sh` (thin runner; default **help**) delegates to **`bin/runctl`**. Maintainer npm flows live in [`scripts/maintain.sh`](scripts/maintain.sh). **`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

@@ -2,6 +2,11 @@
 # Runctl CLI — installed via pnpm/npm (devDependency .bin or global).
 set -euo pipefail
 RUNCTL_PKG_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)"
+# Load optional repo .env / npm token (consumer project: set RUNCTL_PROJECT_ROOT or run from repo root).
+# shellcheck source=../lib/repo-env.sh
+source "$RUNCTL_PKG_ROOT/lib/repo-env.sh"
+runctl_load_repo_env "${RUNCTL_PROJECT_ROOT:-$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
@@ -18,25 +23,17 @@ _runctl_read_pnpm_version_from_package_json() {
   ' "$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).
+# After a successful pnpm global update: short tip (global pnpm vs project pin).
 _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.)
+${_d}┌${_r} ${_g}runctl${_r} ${_b}tip${_r} ${_d}· global pnpm can differ from your repo's packageManager pin.${_r}
+${_d}│${_r}  ${_c}volta install pnpm@${ver}${_r}  ${_d}·${_r}  ${_c}corepack prepare pnpm@${ver} --activate${_r}
+${_d}│${_r}  ${_c}RUNCTL_PNPM_VERSION=${ver} runctl update git${_r}  ${_d}·${_r}  ${_c}runctl update --pm npm${_r}
+${_d}└${_r} ${_d}hide:${_r} ${_c}RUNCTL_UPDATE_SKIP_PNPM_HINT=1${_r}
 EOF
 }
 
@@ -74,6 +71,19 @@ if [[ -t 1 ]]; then
   _c=$'\033[36m' _y=$'\033[33m' _g=$'\033[32m'
 fi
 
+# Semver from this package's package.json (for --version and update banners).
+_runctl_pkg_version() {
+  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' "$ver"
+}
+
+
 usage() {
   cat <<EOF
 ${_b}runctl${_r} — dev-server orchestrator & port manager
@@ -91,12 +101,18 @@ ${_y}Commands${_r}
   ${_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}run-sh${_r} [--print|--write] [opts]   Emit example ${_d}run.sh${_r} ${_d}(see runctl run-sh --help)${_r}
   ${_c}update${_r} [npm|git|auto] [opts]  Update global runctl ${_d}(default: auto; see runctl update --help)${_r}
+  ${_c}install${_r} [args]               Install dependencies ${_d}(pnpm preferred; npm fallback when PM=pnpm)${_r}
+  ${_c}run${_r} <script> [args]          ${_d}package manager run (PM env, default pnpm)${_r}
+  ${_c}exec${_r} [args]                  ${_d}package manager exec${_r}
+  ${_c}test${_r} [args]                  ${_d}package manager test${_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}RUNCTL_PROJECT_ROOT${_r}           Repo root for .env + install/run/test ${_d}(default: cwd)${_r}
+  ${_c}version${_r} | ${_c}--version${_r} | ${_c}-v${_r}     Print version and package install path
   ${_c}--help${_r}, ${_c}-h${_r}                     Show this help
 
 ${_d}Quick start — add to package.json:
@@ -415,9 +431,10 @@ cmd_update() {
   fi
   [[ -n "$MODE" ]] || MODE="auto"
 
-  local pm git_target
+  local pm git_target ver_now
   pm="$(cmd_update_pick_pm "$PM")" || exit 1
   git_target="${GIT_BASE}#${GIT_REF}"
+  ver_now="$(_runctl_pkg_version)"
 
   _remove_conflicting_global_runctl() {
     # A legacy package named "runctl" can own the same binary name and shadow @zendero/runctl.
@@ -450,12 +467,12 @@ cmd_update() {
 
   _update_registry() {
     local spec="${PKG}@latest"
-    echo "runctl update: installing latest from registry ($spec)..."
+    printf '%s\n' "${_c}▶${_r} ${_b}runctl update${_r} ${_d}·${_r} ${_c}v${ver_now}${_r} ${_d}·${_r} registry ${_g}${spec}${_r}" >&2
     _remove_conflicting_global_runctl
     if [[ "$pm" == "pnpm" ]]; then
-      _runctl_pnpm_exec add -g --force "$spec"
+      _runctl_pnpm_exec add -g --force --loglevel error "$spec"
     else
-      npm install -g --force "$spec"
+      npm install -g --force --silent --no-fund --no-audit "$spec"
     fi
   }
 
@@ -463,17 +480,17 @@ cmd_update() {
     local sha spec
     if sha="$(_resolve_git_ref_sha "$GIT_BASE" "$GIT_REF")"; then
       spec="${GIT_BASE}#${sha}"
-      echo "runctl update: installing from Git ref $GIT_REF (resolved to ${sha:0:12})..."
+      printf '%s\n' "${_c}▶${_r} ${_b}runctl update${_r} ${_d}·${_r} ${_c}v${ver_now}${_r} ${_d}·${_r} git ${_g}${GIT_REF}${_r} ${_d}@${sha:0:12}${_r}" >&2
     else
       spec="$git_target"
-      echo "runctl update: installing from Git ($git_target)..."
+      printf '%s\n' "${_c}▶${_r} ${_b}runctl update${_r} ${_d}·${_r} ${_c}v${ver_now}${_r} ${_d}·${_r} git ${_g}${git_target}${_r}" >&2
       echo "runctl update: could not resolve ref to SHA; proceeding with ref directly." >&2
     fi
     _remove_conflicting_global_runctl
     if [[ "$pm" == "pnpm" ]]; then
-      _runctl_pnpm_exec add -g --force "$spec"
+      _runctl_pnpm_exec add -g --force --loglevel error "$spec"
     else
-      npm install -g --force "$spec"
+      npm install -g --force --silent --no-fund --no-audit "$spec"
     fi
   }
 
@@ -496,6 +513,10 @@ cmd_update() {
       ;;
   esac
 
+  local ver_installed
+  ver_installed="$(_runctl_pkg_version)"
+  printf '%s\n' "${_g}✓${_r} ${_b}runctl${_r} ${_c}v${ver_installed}${_r} ${_d}· global install refreshed${_r}" >&2
+
   _runctl_maybe_print_pnpm_update_hint "$pm"
 }
 
@@ -582,15 +603,185 @@ cmd_logs() {
   tail -n "$lines" "$logf"
 }
 
+_runctl_pm() {
+  printf '%s' "${PM:-pnpm}"
+}
+
+cmd_install() {
+  local root="${RUNCTL_PROJECT_ROOT:-$PWD}"
+  if [[ "$(_runctl_pm)" == "pnpm" ]]; then
+    if command -v pnpm >/dev/null 2>&1; then
+      (cd "$root" && exec pnpm install "$@")
+    elif command -v npm >/dev/null 2>&1; then
+      echo "runctl install: pnpm not found; using npm" >&2
+      (cd "$root" && exec npm install "$@")
+    else
+      echo "runctl install: install pnpm (preferred) or npm" >&2
+      exit 1
+    fi
+  else
+    local pm="$(_runctl_pm)"
+    command -v "$pm" >/dev/null 2>&1 || {
+      echo "runctl install: $pm not on PATH" >&2
+      exit 1
+    }
+    (cd "$root" && exec "$pm" install "$@")
+  fi
+}
+
+cmd_run() {
+  local root="${RUNCTL_PROJECT_ROOT:-$PWD}"
+  local pm="$(_runctl_pm)"
+  command -v "$pm" >/dev/null 2>&1 || {
+    echo "runctl run: $pm not on PATH (set PM=…)" >&2
+    exit 1
+  }
+  (cd "$root" && exec "$pm" run "$@")
+}
+
+cmd_exec() {
+  local root="${RUNCTL_PROJECT_ROOT:-$PWD}"
+  local pm="$(_runctl_pm)"
+  command -v "$pm" >/dev/null 2>&1 || {
+    echo "runctl exec: $pm not on PATH (set PM=…)" >&2
+    exit 1
+  }
+  (cd "$root" && exec "$pm" exec "$@")
+}
+
+cmd_test() {
+  local root="${RUNCTL_PROJECT_ROOT:-$PWD}"
+  local pm="$(_runctl_pm)"
+  command -v "$pm" >/dev/null 2>&1 || {
+    echo "runctl test: $pm not on PATH (set PM=…)" >&2
+    exit 1
+  }
+  (cd "$root" && exec "$pm" test "$@")
+}
+
+cmd_run_sh_usage() {
+  cat <<EOF
+${_b}runctl run-sh${_r} — emit the canonical example ${_c}run.sh${_r} (thin wrapper → runctl)
+
+${_y}Usage:${_r}
+  runctl run-sh [--print]
+  runctl run-sh --write [--force] [-C dir]
+
+${_y}Description${_r}
+  Reads ${_c}examples/run.sh.example${_r} from this package (falls back to ${_c}run.sh${_r}).
+
+  ${_c}--print${_r} ${_d}(default)${_r} prints to stdout — redirect into your repo:
+    ${_d}runctl run-sh > run.sh && chmod +x run.sh${_r}
+
+  ${_c}--write${_r} writes ${_c}run.sh${_r} under the target directory (default: ${_c}\$PWD${_r} or ${_c}RUNCTL_PROJECT_ROOT${_r} when set).
+    Refuses to overwrite an existing file unless ${_c}--force${_r}.
+
+${_y}Options${_r}
+  ${_c}--print${_r}              Print to stdout ${_d}(default when --write not used)${_r}
+  ${_c}--write${_r} | ${_c}-w${_r}           Write ${_c}run.sh${_r} in the target directory
+  ${_c}--force${_r} | ${_c}-f${_r}           Overwrite ${_c}run.sh${_r} if it already exists
+  ${_c}-C${_r} ${_c}dir${_r} | ${_c}--dir${_r} ${_c}dir${_r}   Target directory (default: ${_c}RUNCTL_PROJECT_ROOT${_r} or cwd)
+  ${_c}-h${_r} | ${_c}--help${_r}           Show this help
+EOF
+}
+
+_runctl_run_sh_example_path() {
+  local ex="$RUNCTL_PKG_ROOT/examples/run.sh.example"
+  local fb="$RUNCTL_PKG_ROOT/run.sh"
+  if [[ -f "$ex" && -r "$ex" ]]; then
+    printf '%s' "$ex"
+    return 0
+  fi
+  if [[ -f "$fb" && -r "$fb" ]]; then
+    printf '%s' "$fb"
+    return 0
+  fi
+  return 1
+}
+
+cmd_run_sh() {
+  local action=print
+  local force=0
+  local target_dir=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --print)
+        action=print
+        shift
+        ;;
+      --write | -w)
+        action=write
+        shift
+        ;;
+      --force | -f)
+        force=1
+        shift
+        ;;
+      -C | --dir)
+        if [[ $# -lt 2 ]]; then
+          echo "runctl run-sh: $1 requires a directory" >&2
+          exit 1
+        fi
+        target_dir="$(cd "$2" && pwd)" || exit 1
+        shift 2
+        ;;
+      -h | --help)
+        cmd_run_sh_usage
+        return 0
+        ;;
+      -*)
+        echo "runctl run-sh: unknown option: $1" >&2
+        cmd_run_sh_usage >&2
+        exit 1
+        ;;
+      *)
+        echo "runctl run-sh: unexpected argument: $1" >&2
+        cmd_run_sh_usage >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  if [[ -z "$target_dir" ]]; then
+    if [[ -n "${RUNCTL_PROJECT_ROOT:-}" && -d "$RUNCTL_PROJECT_ROOT" ]]; then
+      target_dir="$(cd "$RUNCTL_PROJECT_ROOT" && pwd)"
+    else
+      target_dir="$(pwd)"
+    fi
+  fi
+
+  local path
+  path="$(_runctl_run_sh_example_path)" || {
+    echo "runctl run-sh: example not found under $RUNCTL_PKG_ROOT" >&2
+    exit 1
+  }
+
+  if [[ "$action" == "write" ]]; then
+    local out="$target_dir/run.sh"
+    if [[ -e "$out" && "$force" -ne 1 ]]; then
+      echo "runctl run-sh: $out already exists (use --force to overwrite)" >&2
+      exit 1
+    fi
+    cat "$path" >"$out"
+    chmod +x "$out"
+    echo "runctl run-sh: wrote $out" >&2
+    return 0
+  fi
+
+  cat "$path"
+}
+
 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 "?"
-    )"
+  local ver
+  ver="$(_runctl_pkg_version)"
+  if [[ -t 1 ]]; then
+    printf '%s\n\n' "${_b}runctl${_r} ${_c}v${ver}${_r}"
+  else
+    printf 'runctl %s\n\n' "$ver"
   fi
-  printf '%s\n' "runctl $ver — $RUNCTL_PKG_ROOT"
+  printf '%s\n' "${_d}Install:${_r}"
+  printf '%s\n' "  $RUNCTL_PKG_ROOT"
 }
 
 main() {
@@ -607,6 +798,11 @@ main() {
     env)      cmd_env "$@" ;;
     doctor)   cmd_doctor "$@" ;;
     update)   cmd_update "$@" ;;
+    install)  cmd_install "$@" ;;
+    run)      cmd_run "$@" ;;
+    exec)     cmd_exec "$@" ;;
+    test)     cmd_test "$@" ;;
+    run-sh)   cmd_run_sh "$@" ;;
 
     # Plumbing
     lib-path) printf '%s\n' "$RUNCTL_PKG_ROOT/lib/run-lib.sh" ;;

package/docs/vercel-and-env.md

@@ -13,7 +13,7 @@ Keep a **manifest** (not loaded directly by Next/Vite) that lists each real valu
 
 ```bash
 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
+# or: runctl env expand 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).
@@ -81,6 +81,6 @@ Sometimes two env vars exist for historical reasons. If both client and server c
 
 | Goal | Approach |
 |------|-----------|
-| Same value, many names **locally** | `env.manifest` + `expand-env-manifest.mjs` → `.env.local` |
+| Same value, many names **locally** | `env.manifest` + `runctl env expand` → `.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/run.sh.example

@@ -1,82 +1,91 @@
 #!/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`).
-
+# Thin project runner: sets RUNCTL_PROJECT_ROOT + PM/PORT, then delegates to bin/runctl.
+# Maintainer npm flows: scripts/maintain.sh
 set -euo pipefail
 
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$ROOT"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+export RUNCTL_PROJECT_ROOT="$ROOT"
+export RUNCTL_PKG_ROOT="$ROOT"
+export RUN_SH_TASK="${RUN_SH_TASK:-}"
+
+PM="${PM:-pnpm}"
+export PM
+RUNCTL_DEV_SCRIPT="${RUNCTL_DEV_SCRIPT:-dev}"
+PORT="${PORT:-3000}"
 
-if [[ -z "${RUN_LIB:-}" ]]; then
-  _rp="${RUNCTL_PACKAGE:-@zendero/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
+die() {
+  echo "run.sh${RUN_SH_TASK:+ ($RUN_SH_TASK)}: $*" >&2
   exit 1
 }
-# shellcheck source=/dev/null
-source "$RUN_LIB"
-run_project_init "$ROOT"
+
+runctl_cmd() {
+  if [[ -x "$ROOT/bin/runctl" ]]; then
+    exec "$ROOT/bin/runctl" "$@"
+  elif [[ -x "$ROOT/node_modules/.bin/runctl" ]]; then
+    exec "$ROOT/node_modules/.bin/runctl" "$@"
+  elif command -v pnpm >/dev/null 2>&1 && pnpm exec runctl version >/dev/null 2>&1; then
+    exec pnpm exec runctl "$@"
+  elif command -v runctl >/dev/null 2>&1; then
+    exec runctl "$@"
+  else
+    die "runctl not found — install deps or add @zendero/runctl"
+  fi
+}
 
 usage() {
   cat <<'EOF'
-Usage: ./run.sh <command>
+Usage: ./run.sh <command> [args]
 
-  dev [name] [auto|PORT] [-- extra args]
-  stop              Stop daemons + release port claims
-  status            Local .run state + ports.env
-  install           pnpm install
+  install | run | exec | test   → runctl (same as: runctl install|run|exec|test)
+  dev | start                   → runctl start this repo (--script RUNCTL_DEV_SCRIPT)
+  open | stop | status | doctor | ports | ps | logs | env | update | …
+  env-expand | lib-path
+  release-check | publish | release | promote | npm-whoami → scripts/maintain.sh
 
-Examples:
-  ./run.sh dev
-  ./run.sh dev web auto -- --turbo
+Environment:
+  RUNCTL_PROJECT_ROOT  Set automatically to this script’s directory
+  RUNCTL_DEV_SCRIPT    npm script for dev/start (default: dev)
+  PORT                 Passed to dev/start
+  PM                   package manager (default: pnpm)
 EOF
+  echo ""
+  runctl_cmd help
 }
 
-cmd="${1:-dev}"
-shift || true
+main() {
+  [[ $# -eq 0 ]] && set -- help
+  local cmd="${1:-}"
+  shift || true
+
+  case "$cmd" in
+    install | run | exec | test)
+      RUN_SH_TASK="$cmd"
+      export RUN_SH_TASK
+      runctl_cmd "$cmd" "$@"
+      ;;
+    dev | start)
+      export PORT
+      runctl_cmd start "$ROOT" --script "$RUNCTL_DEV_SCRIPT" "$@"
+      ;;
+    release-check | publish | release | promote | npm-whoami)
+      exec "$ROOT/scripts/maintain.sh" "$cmd" "$@"
+      ;;
+    ports-gc | gc)
+      runctl_cmd ports gc "$@"
+      ;;
+    lib-path)
+      runctl_cmd lib-path
+      ;;
+    env-expand | expand-env)
+      runctl_cmd env expand "$@"
+      ;;
+    help | -h | --help)
+      usage
+      ;;
+    *)
+      runctl_cmd "$cmd" "$@"
+      ;;
+  esac
+}
 
-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
+main "$@"

package/lib/repo-env.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Optional repo-root env for npm auth — sourced by bin/runctl and scripts/maintain.sh.
+# Resolves root as: $1, else RUNCTL_PROJECT_ROOT, else PWD.
+# Idempotent per shell (RUNCTL_REPO_ENV_LOADED).
+
+runctl_load_repo_env() {
+  [[ -n "${RUNCTL_REPO_ENV_LOADED:-}" ]] && return 0
+  local root="${1:-${RUNCTL_PROJECT_ROOT:-$PWD}}"
+
+  if [[ -z "${NPM_TOKEN:-}" ]] && [[ -f "$root/.env" ]]; then
+    local line key val
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      line="${line#"${line%%[![:space:]]*}"}"
+      line="${line%"${line##*[![:space:]]}"}"
+      [[ -z "$line" || "$line" == \#* ]] && continue
+      if [[ "$line" == export\ * ]]; then
+        line="${line#export }"
+      fi
+      [[ "$line" == *"="* ]] || continue
+      key="${line%%=*}"
+      val="${line#*=}"
+      if [[ "$key" != "NPM_TOKEN" && "$key" != "npm_token" ]]; then
+        continue
+      fi
+      val="${val%$'\r'}"
+      if [[ "$val" == \"*\" ]]; then
+        val="${val#\"}"
+        val="${val%\"}"
+      elif [[ "$val" == \'*\' ]]; then
+        val="${val#\'}"
+        val="${val%\'}"
+      fi
+      export NPM_TOKEN="$val"
+      break
+    done <"$root/.env"
+  fi
+
+  if [[ -f "$root/.env" ]]; then
+    set -a
+    # shellcheck source=/dev/null
+    source "$root/.env"
+    set +a
+  fi
+
+  if [[ -z "${NODE_AUTH_TOKEN:-}" ]]; then
+    if [[ -n "${NPM_TOKEN:-}" ]]; then
+      export NODE_AUTH_TOKEN="$NPM_TOKEN"
+    elif [[ -n "${npm_token:-}" ]]; then
+      export NODE_AUTH_TOKEN="$npm_token"
+    fi
+  fi
+
+  export RUNCTL_REPO_ENV_LOADED=1
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zendero/runctl",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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",
@@ -29,6 +29,7 @@
   },
   "files": [
     "bin",
+    "run.sh",
     "lib",
     "scripts",
     "examples",
@@ -42,7 +43,7 @@
     "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",
+    "env:expand": "bash ./run.sh env-expand",
     "link-global": "pnpm link --global"
   }
 }

package/run.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Thin project runner: sets RUNCTL_PROJECT_ROOT + PM/PORT, then delegates to bin/runctl.
+# Maintainer npm flows: scripts/maintain.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+export RUNCTL_PROJECT_ROOT="$ROOT"
+export RUNCTL_PKG_ROOT="$ROOT"
+export RUN_SH_TASK="${RUN_SH_TASK:-}"
+
+PM="${PM:-pnpm}"
+export PM
+RUNCTL_DEV_SCRIPT="${RUNCTL_DEV_SCRIPT:-dev}"
+PORT="${PORT:-3000}"
+
+die() {
+  echo "run.sh${RUN_SH_TASK:+ ($RUN_SH_TASK)}: $*" >&2
+  exit 1
+}
+
+runctl_cmd() {
+  if [[ -x "$ROOT/bin/runctl" ]]; then
+    exec "$ROOT/bin/runctl" "$@"
+  elif [[ -x "$ROOT/node_modules/.bin/runctl" ]]; then
+    exec "$ROOT/node_modules/.bin/runctl" "$@"
+  elif command -v pnpm >/dev/null 2>&1 && pnpm exec runctl version >/dev/null 2>&1; then
+    exec pnpm exec runctl "$@"
+  elif command -v runctl >/dev/null 2>&1; then
+    exec runctl "$@"
+  else
+    die "runctl not found — install deps or add @zendero/runctl"
+  fi
+}
+
+usage() {
+  cat <<'EOF'
+Usage: ./run.sh <command> [args]
+
+  install | run | exec | test   → runctl (same as: runctl install|run|exec|test)
+  dev | start                   → runctl start this repo (--script RUNCTL_DEV_SCRIPT)
+  open | stop | status | doctor | ports | ps | logs | env | update | …
+  env-expand | lib-path
+  release-check | publish | release | promote | npm-whoami → scripts/maintain.sh
+
+Environment:
+  RUNCTL_PROJECT_ROOT  Set automatically to this script’s directory
+  RUNCTL_DEV_SCRIPT    npm script for dev/start (default: dev)
+  PORT                 Passed to dev/start
+  PM                   package manager (default: pnpm)
+EOF
+  echo ""
+  runctl_cmd help
+}
+
+main() {
+  [[ $# -eq 0 ]] && set -- help
+  local cmd="${1:-}"
+  shift || true
+
+  case "$cmd" in
+    install | run | exec | test)
+      RUN_SH_TASK="$cmd"
+      export RUN_SH_TASK
+      runctl_cmd "$cmd" "$@"
+      ;;
+    dev | start)
+      export PORT
+      runctl_cmd start "$ROOT" --script "$RUNCTL_DEV_SCRIPT" "$@"
+      ;;
+    release-check | publish | release | promote | npm-whoami)
+      exec "$ROOT/scripts/maintain.sh" "$cmd" "$@"
+      ;;
+    ports-gc | gc)
+      runctl_cmd ports gc "$@"
+      ;;
+    lib-path)
+      runctl_cmd lib-path
+      ;;
+    env-expand | expand-env)
+      runctl_cmd env expand "$@"
+      ;;
+    help | -h | --help)
+      usage
+      ;;
+    *)
+      runctl_cmd "$cmd" "$@"
+      ;;
+  esac
+}
+
+main "$@"

package/scripts/maintain.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# Maintainer-only: npm publish, release, promote, release-check, whoami.
+# Invoked via ./run.sh <command> or directly: scripts/maintain.sh <command>
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
+
+die() {
+  echo "maintain: $*" >&2
+  exit 1
+}
+
+export RUNCTL_PROJECT_ROOT="$ROOT"
+# shellcheck source=../lib/repo-env.sh
+source "$ROOT/lib/repo-env.sh"
+runctl_load_repo_env "$ROOT"
+
+in_repo() {
+  (cd "$ROOT" && "$@")
+}
+
+npm_publish_token() {
+  printf '%s' "${NPM_TOKEN:-${NODE_AUTH_TOKEN:-${npm_token:-}}}"
+}
+
+runctl_npm_userconfig_from_token() {
+  local tok="$1"
+  local f
+  f="$(mktemp "${TMPDIR:-/tmp}/runctl-npm-auth.XXXXXX")" || return 1
+  chmod 600 "$f" || true
+  printf '//registry.npmjs.org/:_authToken=%s\n' "$tok" >"$f" || {
+    rm -f "$f"
+    return 1
+  }
+  printf '%s' "$f"
+}
+
+validate_dist_tag() {
+  case "${1:-latest}" in
+    latest | next) return 0 ;;
+    *)
+      echo "maintain publish: unsupported dist-tag '$1'. Use: latest or next." >&2
+      return 1
+      ;;
+  esac
+}
+
+release_commit_and_push_if_needed() {
+  local dist_tag="$1"
+  local pkg_name="$2"
+  local pkg_version="$3"
+  if ! command -v git >/dev/null 2>&1; then
+    echo "maintain release: git not found; skipping commit/push step" >&2
+    return 0
+  fi
+  if ! git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "maintain release: not in a git worktree; skipping commit/push step" >&2
+    return 0
+  fi
+  if [[ -n "$(git -C "$ROOT" status --porcelain)" ]]; then
+    local branch
+    branch="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+    [[ -n "$branch" && "$branch" != "HEAD" ]] || die "release commit/push requires a branch checkout (not detached HEAD)"
+    git -C "$ROOT" add -A
+    git -C "$ROOT" commit -m "release: publish ${pkg_name}@${pkg_version} (${dist_tag})"
+    git -C "$ROOT" push -u origin "$branch"
+    echo "maintain release: committed and pushed release changes on $branch"
+  else
+    echo "maintain release: no local git changes; skipping commit/push"
+  fi
+}
+
+package_field() {
+  local field="$1"
+  node -e '
+    const fs = require("fs");
+    const path = require("path");
+    const f = path.join(process.argv[1], "package.json");
+    const pkg = JSON.parse(fs.readFileSync(f, "utf8"));
+    const key = process.argv[2];
+    if (!pkg[key]) process.exit(1);
+    process.stdout.write(String(pkg[key]));
+  ' "$ROOT" "$field"
+}
+
+publish_failed_hint() {
+  local op="$1"
+  echo "maintain ${op}: publish failed." >&2
+  echo "  If ./run.sh npm-whoami works: check scoped write / maintainer on npm." >&2
+  echo "  Run ./run.sh release-check before publish." >&2
+}
+
+maint_release_check() {
+  echo "maintain release-check: runctl doctor..."
+  "$ROOT/bin/runctl" doctor "$ROOT" || die "doctor failed"
+  echo "maintain release-check: pack --dry-run..."
+  if command -v pnpm >/dev/null 2>&1; then
+    in_repo pnpm pack --dry-run >/dev/null || die "pnpm pack --dry-run failed"
+  elif command -v npm >/dev/null 2>&1; then
+    in_repo npm pack --dry-run >/dev/null || die "npm pack --dry-run failed"
+  else
+    die "install pnpm or npm for release-check"
+  fi
+  local tok _rc _ec
+  tok="$(npm_publish_token)"
+  if [[ -n "$tok" ]]; then
+    echo "maintain release-check: npm whoami..."
+    _rc="$(runctl_npm_userconfig_from_token "$tok")" || die "could not write temp npmrc"
+    NPM_CONFIG_USERCONFIG="$_rc" npm whoami || {
+      _ec=$?
+      rm -f "$_rc"
+      die "npm whoami failed (exit $_ec)"
+    }
+    rm -f "$_rc"
+  else
+    echo "maintain release-check: skip npm whoami (no NPM_TOKEN / npm_token in .env)" >&2
+  fi
+  echo "maintain release-check: ok"
+}
+
+maint_publish_or_release() {
+  local cmd="$1"
+  shift
+  if [[ "${1:-}" == "all" ]]; then
+    shift
+  fi
+  local dist_tag="${1:-latest}"
+  validate_dist_tag "$dist_tag" || exit 1
+  if [[ $# -gt 0 ]]; then
+    shift
+  fi
+  local token pkg_name pkg_version remote_version
+  token="$(npm_publish_token)"
+  [[ -n "$token" ]] || die "missing npm token — set NPM_TOKEN in .env (or NODE_AUTH_TOKEN / npm_token)"
+  export NODE_AUTH_TOKEN="$token"
+  export PUBLISH_OK=1
+  pkg_name="$(package_field name)"
+  pkg_version="$(package_field version)"
+  remote_version="$(npm view "${pkg_name}@${pkg_version}" version 2>/dev/null || true)"
+
+  local is_dry_run=0 arg
+  for arg in "$@"; do
+    if [[ "$arg" == "--dry-run" ]]; then
+      is_dry_run=1
+      break
+    fi
+  done
+
+  if [[ -n "$remote_version" && "$is_dry_run" -eq 0 ]]; then
+    echo "maintain ${cmd}: ${pkg_name}@${pkg_version} already exists; bumping patch version..."
+    if command -v pnpm >/dev/null 2>&1; then
+      in_repo pnpm version patch --no-git-tag-version || die "pnpm version patch failed"
+    else
+      in_repo npm version patch --no-git-tag-version || die "npm version patch failed"
+    fi
+    pkg_version="$(package_field version)"
+    echo "maintain ${cmd}: publishing ${pkg_name}@${pkg_version} with dist-tag '${dist_tag}'"
+  elif [[ -n "$remote_version" ]]; then
+    echo "maintain ${cmd}: ${pkg_name}@${pkg_version} already exists; not bumping during --dry-run"
+  fi
+
+  local npmrc _pub_ok=0
+  npmrc="$(runctl_npm_userconfig_from_token "$token")" || exit 1
+
+  if command -v pnpm >/dev/null 2>&1; then
+    (cd "$ROOT" && NPM_CONFIG_USERCONFIG="$npmrc" pnpm publish --access public --tag "$dist_tag" --no-git-checks "$@") && _pub_ok=1
+  elif command -v npm >/dev/null 2>&1; then
+    (cd "$ROOT" && NPM_CONFIG_USERCONFIG="$npmrc" npm publish --access public --tag "$dist_tag" --no-git-checks "$@") && _pub_ok=1
+  else
+    rm -f "$npmrc"
+    die "install pnpm (preferred) or npm"
+  fi
+  rm -f "$npmrc"
+  if [[ "$_pub_ok" -ne 1 ]]; then
+    publish_failed_hint "$cmd"
+    exit 1
+  fi
+  if [[ "$cmd" == "release" && "$is_dry_run" -eq 0 ]]; then
+    release_commit_and_push_if_needed "$dist_tag" "$pkg_name" "$pkg_version"
+  fi
+}
+
+maint_promote() {
+  local tok npmrc name ver
+  tok="$(npm_publish_token)"
+  [[ -n "$tok" ]] || die "set NPM_TOKEN (or npm_token) in .env for promote"
+  name="$(package_field name)"
+  ver="$(package_field version)"
+  npmrc="$(runctl_npm_userconfig_from_token "$tok")" || exit 1
+  echo "maintain promote: npm dist-tag add ${name}@${ver} latest"
+  if NPM_CONFIG_USERCONFIG="$npmrc" npm dist-tag add "${name}@${ver}" latest; then
+    rm -f "$npmrc"
+    echo "maintain promote: ok"
+  else
+    rm -f "$npmrc"
+    die "dist-tag add failed (is ${name}@${ver} published?)"
+  fi
+}
+
+maint_npm_whoami() {
+  local _tok _rc _ec
+  command -v npm >/dev/null 2>&1 || die "npm not found"
+  _tok="$(npm_publish_token)"
+  [[ -n "$_tok" ]] || die "set NPM_TOKEN or NODE_AUTH_TOKEN or npm_token in .env"
+  _rc="$(runctl_npm_userconfig_from_token "$_tok")" || exit 1
+  NPM_CONFIG_USERCONFIG="$_rc" npm whoami
+  _ec=$?
+  rm -f "$_rc"
+  exit "$_ec"
+}
+
+maint_usage() {
+  cat <<'EOF'
+Maintainer commands (scripts/maintain.sh):
+
+  release-check     Preflight: doctor + pack --dry-run + optional npm whoami
+  publish [all] [tag]   Publish package to npm
+  release [all] [tag]   Publish, then commit+push if needed
+  promote            npm dist-tag add <pkg>@<version> latest
+  npm-whoami         npm whoami using token from .env
+
+Also available via: ./run.sh <same command>
+EOF
+}
+
+main() {
+  [[ $# -eq 0 ]] && set -- help
+  local cmd="${1:-}"
+  shift || true
+  case "$cmd" in
+    release-check)
+      maint_release_check
+      ;;
+    publish | release)
+      maint_publish_or_release "$cmd" "$@"
+      ;;
+    promote)
+      maint_promote
+      ;;
+    npm-whoami)
+      maint_npm_whoami
+      ;;
+    help | -h | --help)
+      maint_usage
+      ;;
+    *)
+      echo "maintain: unknown command: $cmd" >&2
+      echo "" >&2
+      maint_usage >&2
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"