nterminal 1.2.13 → 1.2.15

package/docs/operations.md

@@ -2,7 +2,7 @@
 
 ## Local Service Management
 
-For production-style local operation from an npm package install, use the `nterminal` command:
+Use the `nterminal` command:
 
 ```bash
 nterminal doctor
@@ -13,69 +13,56 @@ nterminal restart
 nterminal stop
 ```
 
-For source checkouts, use the bundled control script through npm:
-
-```bash
-npm run ctl -- doctor
-npm run ctl -- build
-npm run ctl -- start
-npm run ctl -- status
-npm run ctl -- logs
-npm run ctl -- restart
-npm run ctl -- stop
-```
-
 The script starts the built server in the background, writes a PID file, appends logs, waits for the local health endpoint, and stops the real Node PID so PTY cleanup can run.
 
-Source checkouts keep runtime files in the repository's `.nterminal/` directory by default. npm package installs launched through `nterminal` keep runtime files under `~/.nterminal`.
-
-One-command source checkout deploy:
-
-```bash
-npm run deploy:local
-```
+Runtime files are kept under `~/.nterminal`.
 
 Short aliases:
 
 ```bash
-npm run service:status
-npm run service:start
-npm run service:stop
-npm run service:restart
-npm run service:logs
+nterminal status
+nterminal start
+nterminal stop
+nterminal restart
+nterminal logs
 ```
 
 ## Updates
 
-Each server updates itself with the method used to install it.
+Each server updates itself as an npm package install.
 
 The **updates** panel in the main server sidebar footer can manage the fleet:
 
-- **Check for updates** runs `git fetch` for git checkouts, or checks the npm registry for package installs.
-- **Update** runs `git pull --ff-only` plus rebuild/restart for git checkouts, or `npm install -g nterminal@latest` plus restart for package installs.
+- **Check for updates** checks the npm registry.
+- **Update** runs `npm install -g nterminal@latest` plus restart.
 - **Update all** updates secondary servers in parallel first and the main server last.
 
 Notes:
 
-- `--ff-only` stops and reports an error when a checkout has local commits or a diverged branch.
 - npm package updates run as the same user that owns the running server process. Use a user-writable npm prefix, not a root-owned global install, if you want UI updates to work without sudo.
-- A git checkout with no upstream branch, or an npm registry/permission error, is reported as an explanatory status.
+- An npm registry or permission error is reported as an explanatory status.
 - Update endpoints require the same auth boundary as the rest of NTerminal.
 
-## Clean Local State
+## Clean Uninstall
 
-To clean a local install before reinstalling:
+To remove the local runtime before uninstalling the npm package:
 
 ```bash
-nterminal clean --force --env
+nterminal uninstall --force
+npm uninstall -g nterminal
 ```
 
-This stops the managed server, kills NTerminal tmux sessions, removes runtime state under `~/.nterminal`, and removes `~/.nterminal/.env`.
-In a source checkout, run the same command as `npm run ctl -- clean --force --env`.
+`npm uninstall -g nterminal` cannot run cleanup automatically on modern npm versions. Run `nterminal uninstall --force` first; it stops the managed server, unloads an NTerminal launchd agent when present, kills NTerminal tmux sessions, removes runtime state under `~/.nterminal`, and removes `~/.nterminal/.env`.
+
+If you already removed the package while a server is still running, reinstall or use npx to run the cleanup command, then uninstall again:
+
+```bash
+npx nterminal@latest uninstall --force
+npm uninstall -g nterminal
+```
 
-Options:
+Option:
 
-- omit `--env` to keep `.env`
 - add `--keep-tmux` to preserve live tmux-backed panes
 
 ## Verification
@@ -114,17 +101,11 @@ If native PTY install or startup fails for a package install:
 npm explore -g nterminal -- npm rebuild node-pty --build-from-source
 ```
 
-For source checkouts:
-
-```bash
-npm rebuild node-pty --build-from-source
-```
-
 If the service script will not start:
 
 ```bash
-npm run ctl -- doctor
-npm run ctl -- logs
+nterminal doctor
+nterminal logs
 ```
 
 If you lose the local NTerminal password, stop the server and remove the local state file at `NTERMINAL_STATE_PATH`. The next browser visit will show the first-run password setup screen again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nterminal",
-  "version": "1.2.13",
+  "version": "1.2.15",
   "license": "GPL-3.0-only",
   "type": "module",
   "packageManager": "npm@10.9.7",

package/scripts/nterminalctl

@@ -4,7 +4,8 @@ set -Eeuo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 DEFAULT_APP_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 APP_DIR="${NTERMINAL_APP_DIR:-$DEFAULT_APP_DIR}"
-ENV_FILE="${NTERMINAL_ENV_FILE:-$APP_DIR/.env}"
+DEFAULT_RUNTIME_DIR="${HOME:-$APP_DIR}/.nterminal"
+ENV_FILE="${NTERMINAL_ENV_FILE:-$DEFAULT_RUNTIME_DIR/.env}"
 
 COMMAND="${1:-help}"
 if [[ $# -gt 0 ]]; then
@@ -65,16 +66,9 @@ resolve_path() {
 
 load_env_file
 
-if [[ -f "$APP_DIR/tsconfig.server.json" && -d "$APP_DIR/src" ]]; then
-  DEFAULT_STATE_PATH=".nterminal/state.json"
-  DEFAULT_PID_PATH=".nterminal/nterminal.pid"
-  DEFAULT_LOG_PATH=".nterminal/nterminal.log"
-else
-  DEFAULT_RUNTIME_DIR="${HOME:-$APP_DIR}/.nterminal"
-  DEFAULT_STATE_PATH="$DEFAULT_RUNTIME_DIR/state.json"
-  DEFAULT_PID_PATH="$DEFAULT_RUNTIME_DIR/nterminal.pid"
-  DEFAULT_LOG_PATH="$DEFAULT_RUNTIME_DIR/nterminal.log"
-fi
+DEFAULT_STATE_PATH="$DEFAULT_RUNTIME_DIR/state.json"
+DEFAULT_PID_PATH="$DEFAULT_RUNTIME_DIR/nterminal.pid"
+DEFAULT_LOG_PATH="$DEFAULT_RUNTIME_DIR/nterminal.log"
 
 HOST="${NTERMINAL_HOST:-127.0.0.1}"
 PORT="${NTERMINAL_PORT:-3107}"
@@ -120,16 +114,8 @@ ensure_app_dir() {
   [[ -d "$APP_DIR" ]] || die "app directory not found: $APP_DIR"
 }
 
-is_source_checkout() {
-  [[ -f "$APP_DIR/tsconfig.server.json" && -d "$APP_DIR/src" ]]
-}
-
 missing_env_message() {
-  if is_source_checkout; then
-    printf '.env not found at %s; copy .env.example and run npm run generate:secrets' "$ENV_FILE"
-  else
-    printf '.env not found at %s; run nterminal onboarding' "$ENV_FILE"
-  fi
+  printf '.env not found at %s; run nterminal onboarding' "$ENV_FILE"
 }
 
 ensure_env_file() {
@@ -140,9 +126,6 @@ ensure_runtime() {
   if [[ -f "$RUNTIME_ENTRY" ]]; then
     return 0
   fi
-  if is_source_checkout; then
-    die "dist/server/index.js not found; run scripts/nterminalctl build first"
-  fi
   die "dist/server/index.js not found; reinstall nterminal"
 }
 
@@ -183,10 +166,38 @@ is_running() {
   kill -0 "$pid" 2>/dev/null
 }
 
+pid_controls_app() {
+  local pid="$1"
+  is_running "$pid" || return 1
+
+  local cmdline=""
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    cmdline="$(tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null || true)"
+    local cwd=""
+    cwd="$(readlink "/proc/$pid/cwd" 2>/dev/null || true)"
+    if [[ "$cmdline" == *"$RUNTIME_ENTRY"* ]]; then
+      [[ -z "$cwd" || "$cwd" == "$APP_DIR" ]] || return 1
+      return 0
+    fi
+    if [[ "$cwd" == "$APP_DIR" && "$cmdline" == *"dist/server/index.js"* ]]; then
+      return 0
+    fi
+    return 1
+  fi
+
+  if command -v ps >/dev/null 2>&1; then
+    cmdline="$(ps -p "$pid" -o command= 2>/dev/null || true)"
+    [[ "$cmdline" == *"$RUNTIME_ENTRY"* ]]
+    return
+  fi
+
+  return 1
+}
+
 current_pid() {
   local pid
   pid="$(read_pid || true)"
-  if [[ -n "$pid" && "$(is_running "$pid" && echo yes || echo no)" == yes ]]; then
+  if [[ -n "$pid" && "$(pid_controls_app "$pid" && echo yes || echo no)" == yes ]]; then
     printf '%s' "$pid"
     return 0
   fi
@@ -215,10 +226,35 @@ launchd_controls_app() {
   esac
 }
 
+launchd_agent_plist() {
+  local home_dir="${HOME:-}"
+  [[ -n "$home_dir" ]] || return 1
+  printf '%s/Library/LaunchAgents/%s.plist' "$home_dir" "$LAUNCHD_LABEL"
+}
+
+unload_launchd_if_controlled() {
+  launchd_controls_app || return 0
+  local domain
+  domain="$(launchd_domain)" || return 0
+  launchctl bootout "$domain" >/dev/null 2>&1 || launchctl remove "$LAUNCHD_LABEL" >/dev/null 2>&1 || true
+  rm -f "$PID_PATH"
+  info "NTerminal launchd agent unloaded label=$LAUNCHD_LABEL"
+}
+
+remove_owned_launchd_plist() {
+  local plist
+  plist="$(launchd_agent_plist || true)"
+  [[ -n "$plist" && -f "$plist" ]] || return 0
+  if grep -F "$APP_DIR" "$plist" >/dev/null 2>&1; then
+    rm -f "$plist"
+    info "NTerminal launchd plist removed path=$plist"
+  fi
+}
+
 remove_stale_pid() {
   local pid
   pid="$(read_pid || true)"
-  if [[ -n "$pid" && ! "$(is_running "$pid" && echo yes || echo no)" == yes ]]; then
+  if [[ -n "$pid" && ! "$(pid_controls_app "$pid" && echo yes || echo no)" == yes ]]; then
     rm -f "$PID_PATH"
   fi
 }
@@ -388,37 +424,14 @@ cmd_restart() {
 
 cmd_build() {
   ensure_app_dir
-  if ! is_source_checkout; then
-    ensure_runtime
-    info "Package install uses bundled dist; no build needed."
-    return 0
-  fi
-  (
-    cd "$APP_DIR"
-    "$NPM_BIN" run build
-  )
+  ensure_runtime
+  info "Package install uses bundled dist; no build needed."
 }
 
 cmd_deploy() {
   ensure_app_dir
   ensure_env_file
-  (
-    cd "$APP_DIR"
-    if is_source_checkout && [[ -f package-lock.json ]]; then
-      "$NPM_BIN" ci
-    elif is_source_checkout; then
-      "$NPM_BIN" install
-    fi
-    if is_source_checkout; then
-      "$NPM_BIN" run typecheck
-      # node-pty's install script always compiles from source (no prebuilt
-      # download); ask npm to rebuild it explicitly after dependency updates.
-      "$NPM_BIN" rebuild node-pty --build-from-source
-      "$NPM_BIN" run build
-    else
-      ensure_runtime
-    fi
-  )
+  ensure_runtime
   cmd_restart
 }
 
@@ -451,6 +464,10 @@ stop_pid_file() {
     rm -f "$pid_path"
     return 0
   fi
+  if ! pid_controls_app "$pid"; then
+    rm -f "$pid_path"
+    return 0
+  fi
 
   kill -TERM "$pid" 2>/dev/null || true
   local deadline=$((SECONDS + STOP_TIMEOUT_SECONDS))
@@ -470,16 +487,10 @@ clean_state_paths() {
   local state_path="$1"
   local pid_path="$2"
   local log_path="$3"
-  local default_state_dir="$4"
   local state_dir
   state_dir="$(dirname "$state_path")"
-  if [[ "$state_dir" == "$default_state_dir" ]]; then
-    rm -rf "$state_dir"
-  else
-    rm -f "$state_path" "$pid_path" "$log_path" "$state_dir/update.lock"
-    rm -rf "$state_dir/notification-assets"
-    rm -rf "$default_state_dir"
-  fi
+  rm -f "$state_path" "$pid_path" "$log_path" "$state_dir/update.lock"
+  rm -rf "$state_dir/notification-assets"
 }
 
 cmd_clean() {
@@ -508,7 +519,7 @@ cmd_clean() {
 
   local state_dir
   state_dir="$(dirname "$STATE_PATH")"
-  clean_state_paths "$STATE_PATH" "$PID_PATH" "$LOG_PATH" "$APP_DIR/.nterminal"
+  clean_state_paths "$STATE_PATH" "$PID_PATH" "$LOG_PATH"
   if (( remove_env == 1 )); then
     rm -f "$ENV_FILE"
   fi
@@ -516,13 +527,39 @@ cmd_clean() {
   info "NTerminal cleaned state_dir=$state_dir env_removed=$remove_env tmux_killed=$kill_tmux"
 }
 
+cmd_uninstall() {
+  local force=0
+  local kill_tmux=1
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=1 ;;
+      --keep-tmux) kill_tmux=0 ;;
+      *) die "unknown uninstall option: $1" ;;
+    esac
+    shift
+  done
+
+  if (( force != 1 )); then
+    die "uninstall is destructive; rerun with: $(control_command uninstall) --force [--keep-tmux]"
+  fi
+
+  ensure_app_dir
+  unload_launchd_if_controlled
+  stop_pid_file "$PID_PATH"
+  if (( kill_tmux == 1 )) && command -v tmux >/dev/null 2>&1; then
+    tmux -L nterminal kill-server >/dev/null 2>&1 || true
+  fi
+  clean_state_paths "$STATE_PATH" "$PID_PATH" "$LOG_PATH"
+  rm -f "$ENV_FILE"
+  remove_owned_launchd_plist
+
+  info "NTerminal runtime uninstalled state_dir=$(dirname "$STATE_PATH") env_removed=1 tmux_killed=$kill_tmux"
+  info "Package files are still installed. To remove them, run: npm uninstall -g nterminal"
+}
+
 control_command() {
   local command="$1"
-  if is_source_checkout; then
-    printf 'scripts/nterminalctl %s' "$command"
-  else
-    printf 'nterminal %s' "$command"
-  fi
+  printf 'nterminal %s' "$command"
 }
 
 cmd_pid() {
@@ -595,17 +632,20 @@ cmd_doctor() {
 
 cmd_help() {
   cat <<EOF
-Usage: scripts/nterminalctl <command>
+Usage: nterminal <command>
 
 Commands:
   status         Show process status. Exit 0 when running, 3 when stopped.
   start          Start the built server in the background.
   stop           Stop the managed server with SIGTERM, then SIGKILL after timeout.
   restart        Stop and start the server.
-  build          Build source checkouts. Package installs use bundled dist.
-  deploy         Build source checkouts when needed, then restart.
+  build          No-op for package installs; verifies the bundled runtime exists.
+  deploy         Restart the installed package using the bundled runtime.
   clean --force  Stop server, kill NTerminal tmux sessions, and remove local state/log/pid files.
                  Add --env to also remove .env. Add --keep-tmux to preserve live panes.
+  uninstall --force
+                 Stop server, unload NTerminal launchd agent, remove local runtime files and .env.
+                 Add --keep-tmux to preserve live panes.
   logs [N]       Show the last N log lines. Default: 100.
   logs -f [N]    Follow logs.
   doctor         Check Node/npm/env/runtime/pid/log/port readiness.
@@ -616,9 +656,9 @@ Commands:
 Environment:
   NTERMINAL_APP_DIR                  Override app directory.
   NTERMINAL_ENV_FILE                 Override .env path.
-  NTERMINAL_STATE_PATH               Default .nterminal/state.json.
-  NTERMINAL_PID_PATH                 Default .nterminal/nterminal.pid.
-  NTERMINAL_LOG_PATH                 Default .nterminal/nterminal.log.
+  NTERMINAL_STATE_PATH               Default ~/.nterminal/state.json.
+  NTERMINAL_PID_PATH                 Default ~/.nterminal/nterminal.pid.
+  NTERMINAL_LOG_PATH                 Default ~/.nterminal/nterminal.log.
   NTERMINAL_HEALTH_TIMEOUT_SECONDS   Default 15.
   NTERMINAL_STOP_TIMEOUT_SECONDS     Default 20.
   NTERMINAL_LAUNCHD_LABEL            Default com.nterminal.local. Used when a loaded LaunchAgent controls this app.
@@ -633,6 +673,7 @@ case "$COMMAND" in
   build) cmd_build "$@" ;;
   deploy) cmd_deploy "$@" ;;
   clean|purge) cmd_clean "$@" ;;
+  uninstall|remove) cmd_uninstall "$@" ;;
   logs|log) cmd_logs "$@" ;;
   doctor) cmd_doctor "$@" ;;
   pid) cmd_pid "$@" ;;