@adelie/server 0.0.0-stage → 0.5.0

package/dist/install.sh

@@ -0,0 +1,494 @@
+#!/bin/sh
+# Adelie one-line installer.
+#
+#   curl -fsSL https://github.com/lmliheng/Adelie/releases/latest/download/install.sh | sh
+#
+# Options:
+#   PENGUIN_VERSION=vX.Y.Z    choose a version (same as --version vX.Y.Z); a published Release
+#                              installer defaults to its own version, an unstamped source copy to latest
+#   PENGUIN_INSTALL_DIR=<dir> install dir; default ~/.adelie
+#   PENGUIN_ARCHIVE=<file>    install a local Release archive without network access (same as --archive <file>)
+#   PENGUIN_DOWNLOAD_SOURCE=auto|github choose the online source; default auto (GitHub Releases)
+#   PENGUIN_DOWNLOAD_BASE_URL=<url> exact online asset directory selected by the stable forwarder
+#   PENGUIN_DOWNLOAD_FALLBACK_BASE_URL=<url> fallback for PENGUIN_DOWNLOAD_BASE_URL
+#   --universal               install the universal package (no bundled Node runtime; needs system Node >= 24)
+#   --no-modify-path          do not put `penguin` on PATH (no ~/.local/bin/penguin symlink); for a second
+#                              installation beside the one the command belongs to
+#
+# Each Release attaches exactly one artifact per target: penguin-<target>.tar.gz, a shallow
+# installer bundle holding this script, the program payload (payload.tar.gz) and the payload's
+# checksum. Online installs download that bundle and verify it against its published .sha256;
+# offline installs transfer the same single file, extract it once and run the bundled
+# ./install.sh, which installs the sibling payload with no network access. Both paths verify
+# the payload checksum sealed inside the bundle before anything is staged. Releases up to
+# v0.1.5 shipped the program tree directly (top-level penguin/); such archives are still
+# accepted, from --version pins and --archive files alike.
+#
+# The data dir (~/.adelie/data by default) sits under the install home but is never touched by reinstall/upgrade (which only replace bin/lib/web/node). The launcher exports the root it lives under, so an install made before the rename (at ~/.penguin) keeps reading its own data there.
+#
+# Docs: https://lmliheng.github.io/Adelie/docs/quickstart-cli
+set -eu
+
+REPO="https://github.com/lmliheng/Adelie"
+GITHUB_RELEASE_ROOT="$REPO/releases/download"
+GITHUB_LATEST_BASE="$REPO/releases/latest/download"
+VERSION="${PENGUIN_VERSION:-}"
+INSTALL_DIR="${PENGUIN_INSTALL_DIR:-$HOME/.adelie}"
+BIN_DIR="$HOME/.local/bin"
+MODIFY_PATH=1
+UNIVERSAL=0
+ARCHIVE="${PENGUIN_ARCHIVE:-}"
+SOURCE_MODE="${PENGUIN_DOWNLOAD_SOURCE:-auto}"
+DOWNLOAD_BASE_URL="${PENGUIN_DOWNLOAD_BASE_URL:-}"
+DOWNLOAD_FALLBACK_BASE_URL="${PENGUIN_DOWNLOAD_FALLBACK_BASE_URL:-}"
+PAYLOAD_NAME="payload.tar.gz"
+# The release workflow replaces this token with the immutable tag before publishing both the
+# standalone installer and the copies sealed inside the Linux, macOS and universal bundles.
+EMBEDDED_RELEASE_VERSION="v0.5.0"
+
+fail() {
+  echo "error: $1" >&2
+  exit 1
+}
+
+validate_https_url() {
+  case "$2" in
+    https://*) ;;
+    *) fail "$1 must be an absolute HTTPS URL" ;;
+  esac
+}
+
+is_release_tag() {
+  case "$1" in
+    v[0-9A-Za-z]* ) ;;
+    *) return 1 ;;
+  esac
+  case "$1" in
+    *[!0-9A-Za-z._-]*) return 1 ;;
+  esac
+  return 0
+}
+
+validate_release_tag() {
+  is_release_tag "$1" || fail "invalid release version: $1"
+}
+
+download_source_label() {
+  case "$1" in
+    https://github.com/*) printf '%s\n' "GitHub" ;;
+    *) printf '%s\n' "configured mirror" ;;
+  esac
+}
+
+# --- Parse args (also passable via curl | sh -s -- --universal) ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version)
+      [ $# -ge 2 ] || fail "--version requires a value (e.g. --version v1.0.0)"
+      VERSION="$2"
+      shift 2
+      ;;
+    --universal)
+      UNIVERSAL=1
+      shift
+      ;;
+    --no-modify-path)
+      MODIFY_PATH=0
+      shift
+      ;;
+    --archive)
+      [ $# -ge 2 ] || fail "--archive requires a path to a Release archive"
+      ARCHIVE="$2"
+      shift 2
+      ;;
+    *)
+      fail "unknown option: $1"
+      ;;
+  esac
+done
+
+# --- Detect platform: Linux/Darwin x64/arm64; other platforms should use the universal package ---
+TARGET="universal"
+if [ "$UNIVERSAL" -eq 0 ]; then
+  case "$(uname -s)" in
+    Linux) os="linux" ;;
+    Darwin) os="darwin" ;;
+    *) fail "unsupported OS: $(uname -s). Install Node.js >= 24, then re-run with --universal." ;;
+  esac
+  case "$(uname -m)" in
+    x86_64) arch="x64" ;;
+    aarch64 | arm64) arch="arm64" ;;
+    *) fail "unsupported architecture: $(uname -m). Install Node.js >= 24, then re-run with --universal." ;;
+  esac
+  TARGET="$os-$arch"
+fi
+ASSET="penguin-$TARGET.tar.gz"
+
+if [ -n "$ARCHIVE" ] && [ -n "$VERSION" ]; then
+  fail "--archive/PENGUIN_ARCHIVE cannot be combined with --version/PENGUIN_VERSION"
+fi
+if [ -n "$VERSION" ]; then
+  validate_release_tag "$VERSION"
+fi
+case "$SOURCE_MODE" in
+  auto | github) ;;
+  *) fail "PENGUIN_DOWNLOAD_SOURCE must be auto or github" ;;
+esac
+RESOLVED_RELEASE_VERSION="$VERSION"
+if [ -z "$RESOLVED_RELEASE_VERSION" ] && is_release_tag "$EMBEDDED_RELEASE_VERSION"; then
+  RESOLVED_RELEASE_VERSION="$EMBEDDED_RELEASE_VERSION"
+fi
+if [ -n "$DOWNLOAD_BASE_URL" ]; then
+  DOWNLOAD_BASE_URL="${DOWNLOAD_BASE_URL%/}"
+  validate_https_url PENGUIN_DOWNLOAD_BASE_URL "$DOWNLOAD_BASE_URL"
+  if [ -n "$DOWNLOAD_FALLBACK_BASE_URL" ]; then
+    DOWNLOAD_FALLBACK_BASE_URL="${DOWNLOAD_FALLBACK_BASE_URL%/}"
+    validate_https_url PENGUIN_DOWNLOAD_FALLBACK_BASE_URL "$DOWNLOAD_FALLBACK_BASE_URL"
+  fi
+else
+  DOWNLOAD_FALLBACK_BASE_URL=""
+fi
+
+# --- Universal package precheck: system Node >= 24 (platform packages bundle the runtime, so exempt) ---
+if [ "$UNIVERSAL" -eq 1 ]; then
+  command -v node >/dev/null 2>&1 \
+    || fail "the universal package needs Node.js >= 24 on PATH (none found)."
+  node_version="$(node --version)" # e.g. v24.18.0
+  v="${node_version#v}"
+  major="${v%%.*}"
+  if [ "$major" -lt 24 ]; then
+    fail "the universal package needs Node.js >= 24, found $node_version."
+  fi
+fi
+
+TMP="$(mktemp -d)"
+STAGING=""
+OLD_DIR=""
+SWAP_ACTIVE=0
+MOVED_OLD=""
+MOVED_NEW=""
+
+# Moves one directory to a new location even when the directory inode itself cannot be renamed
+# — a mount point, a process's CWD, or a filesystem that pins in-use directories (overlayfs
+# under Docker reports EBUSY when `penguin update` replaces the very lib/ its own process runs
+# from). Strategies, in order: plain rename; per-entry renames into a fresh or existing
+# destination; per-entry copy with the source entry removed (POSIX keeps an unlinked-but-open
+# file valid for the process using it). A pinned, now-empty source directory is left in place
+# and reused by the incoming move.
+relocate_dir() {
+  rl_src="$1"
+  rl_dst="$2"
+  if [ ! -e "$rl_dst" ] && mv "$rl_src" "$rl_dst" 2>/dev/null; then
+    return 0
+  fi
+  [ -d "$rl_src" ] || return 1
+  mkdir -p "$rl_dst" || return 1
+  rl_failed=0
+  for rl_entry in "$rl_src"/* "$rl_src"/.[!.]* "$rl_src"/..?*; do
+    [ -e "$rl_entry" ] || [ -L "$rl_entry" ] || continue
+    if ! mv "$rl_entry" "$rl_dst/" 2>/dev/null; then
+      cp -Rp "$rl_entry" "$rl_dst/" || rl_failed=1
+      rm -rf "$rl_entry" || rl_failed=1
+    fi
+  done
+  [ "$rl_failed" -eq 0 ] || return 1
+  [ -z "$(ls -A "$rl_src" 2>/dev/null)" ] || return 1
+  rmdir "$rl_src" 2>/dev/null || :
+  return 0
+}
+
+rollback_install() {
+  rollback_failed=0
+  for d in $MOVED_NEW; do
+    # Clearing may leave a pinned-but-empty directory husk; the restore below reuses it.
+    rm -rf "$INSTALL_DIR/$d" 2>/dev/null || :
+    if [ -e "$INSTALL_DIR/$d" ] && [ -n "$(ls -A "$INSTALL_DIR/$d" 2>/dev/null)" ]; then
+      rollback_failed=1
+    fi
+  done
+  for d in $MOVED_OLD; do
+    if [ -e "$OLD_DIR/$d" ]; then
+      relocate_dir "$OLD_DIR/$d" "$INSTALL_DIR/$d" || rollback_failed=1
+    fi
+  done
+  if [ "$rollback_failed" -ne 0 ]; then
+    echo "error: automatic rollback was incomplete; previous files remain in $OLD_DIR" >&2
+    return 1
+  fi
+  echo "Previous Adelie installation restored." >&2
+}
+
+cleanup() {
+  status=$?
+  trap - EXIT HUP INT TERM
+  set +e
+  if [ "$SWAP_ACTIVE" -eq 1 ]; then
+    rollback_install
+  fi
+  rm -rf "$TMP"
+  [ -z "$STAGING" ] || rm -rf "$STAGING"
+  [ -z "$OLD_DIR" ] || rm -rf "$OLD_DIR"
+  exit "$status"
+}
+
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+# Verifies file $1 against the sha256sum-format file $2 ($3 names the layer in messages).
+# Checksums are never optional: every install path either downloads the published .sha256 or
+# reads the one sealed inside the bundle.
+verify_sha256() {
+  vs_expected="$(awk 'NR == 1 { print $1 }' "$2" | tr 'A-F' 'a-f')"
+  [ -n "$vs_expected" ] || fail "checksum file is empty or malformed: $2"
+  if command -v sha256sum >/dev/null 2>&1; then
+    vs_actual="$(sha256sum "$1" | awk '{ print $1 }')"
+  elif command -v shasum >/dev/null 2>&1; then
+    vs_actual="$(shasum -a 256 "$1" | awk '{ print $1 }')"
+  else
+    fail "sha256sum or shasum is required for checksum verification"
+  fi
+  [ "$vs_actual" = "$vs_expected" ] || fail "checksum mismatch for $3."
+  echo "$3 checksum OK."
+}
+
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{ print $1 }'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{ print $1 }'
+  else
+    fail "sha256sum or shasum is required for checksum verification"
+  fi
+}
+
+# Downloads the bundle and its checksum as a pair. Transport failures may try a same-version
+# fallback; checksum failures are handled afterwards and always abort rather than being hidden
+# by a different source.
+download_release_pair() {
+  drp_base="$1"
+  drp_label="$(download_source_label "$drp_base")"
+  echo "Downloading $ASSET from $drp_label ..."
+  rm -f "$ARCHIVE_PATH" "$TMP/$ASSET.sha256"
+  curl -fSL --progress-bar --connect-timeout 5 --speed-limit 65536 --speed-time 20 "$drp_base/$ASSET" -o "$ARCHIVE_PATH" \
+    || return 1
+  curl -fsSL --connect-timeout 5 --speed-limit 1024 --speed-time 20 "$drp_base/$ASSET.sha256" -o "$TMP/$ASSET.sha256" \
+    || return 1
+  return 0
+}
+
+# --- Resolve the program payload. Three entries converge on PAYLOAD_PATH:
+#     (a) bundled offline: this script sits next to payload.tar.gz in an extracted bundle;
+#     (b) --archive <file>: a local installer bundle, or a payload/legacy program archive;
+#     (c) online: download penguin-<target>.tar.gz and verify it, then open it.
+#     A bundle is recognized by containing payload.tar.gz at its top level; anything else is a
+#     program archive (payload.tar.gz itself, or a pre-0.1.6 release archive) whose top level
+#     is penguin/. ---
+LOCAL_ARCHIVE=0
+ARCHIVE_SHAPE=""
+ARCHIVE_PATH=""
+ARCHIVE_NAME=""
+PAYLOAD_PATH=""
+
+# Sibling pickup engages only for a real file actually named install.sh — the name it carries
+# inside a bundle. A forwarder or `curl | sh` run never satisfies that (no file, or a random
+# temp name), so an online installer cannot be steered by archives someone planted next to a
+# temporary script in a shared directory.
+SIBLING_PAYLOAD=""
+if [ -z "$ARCHIVE" ] && [ -f "$0" ] && [ "$(basename "$0")" = "install.sh" ]; then
+  script_dir="$(CDPATH= cd "$(dirname "$0")" && pwd)"
+  if [ -f "$script_dir/$PAYLOAD_NAME" ]; then
+    SIBLING_PAYLOAD="$script_dir/$PAYLOAD_NAME"
+  fi
+fi
+
+if [ -n "$SIBLING_PAYLOAD" ]; then
+  # (a) Extracted bundle: install the sibling payload; no network access at all.
+  [ -z "$VERSION" ] \
+    || fail "--version/PENGUIN_VERSION cannot be combined with the bundled offline installer"
+  echo "Using bundled payload $SIBLING_PAYLOAD ..."
+  [ -f "$SIBLING_PAYLOAD.sha256" ] \
+    || fail "offline checksum file not found: $SIBLING_PAYLOAD.sha256"
+  verify_sha256 "$SIBLING_PAYLOAD" "$SIBLING_PAYLOAD.sha256" "Payload"
+  PAYLOAD_PATH="$SIBLING_PAYLOAD"
+  ARCHIVE_NAME="$PAYLOAD_NAME"
+  LOCAL_ARCHIVE=1
+elif [ -n "$ARCHIVE" ]; then
+  # (b) Explicit local archive; its shape is probed below.
+  [ -f "$ARCHIVE" ] || fail "local archive not found: $ARCHIVE"
+  archive_name="${ARCHIVE##*/}"
+  archive_dir="$(CDPATH= cd "$(dirname "$ARCHIVE")" && pwd)"
+  ARCHIVE_PATH="$archive_dir/$archive_name"
+  ARCHIVE_NAME="$archive_name"
+  LOCAL_ARCHIVE=1
+  echo "Using local archive $ARCHIVE_PATH ..."
+else
+  # (c) Online: an explicit forwarder/configured URL wins. Otherwise a stamped Release installer
+  #     uses its own immutable version; an unstamped source-tree installer falls back to the
+  #     release GitHub currently marks latest.
+  FALLBACK_BASE_URL="$DOWNLOAD_FALLBACK_BASE_URL"
+  if [ -n "$DOWNLOAD_BASE_URL" ]; then
+    BASE_URL="$DOWNLOAD_BASE_URL"
+  elif [ -n "$RESOLVED_RELEASE_VERSION" ]; then
+    BASE_URL="$GITHUB_RELEASE_ROOT/$RESOLVED_RELEASE_VERSION"
+  else
+    BASE_URL="$GITHUB_LATEST_BASE"
+  fi
+  ARCHIVE_PATH="$TMP/$ASSET"
+  ARCHIVE_NAME="$ASSET"
+  if ! download_release_pair "$BASE_URL"; then
+    if [ -n "$FALLBACK_BASE_URL" ] && [ "$FALLBACK_BASE_URL" != "$BASE_URL" ]; then
+      echo "Primary download source unavailable; trying $(download_source_label "$FALLBACK_BASE_URL") ..."
+      download_release_pair "$FALLBACK_BASE_URL" \
+        || fail "download failed from both the primary source and its fallback. Check your network, then retry."
+    else
+      fail "download failed from $(download_source_label "$BASE_URL"). Check the version tag and your network, then retry."
+    fi
+  fi
+  verify_sha256 "$ARCHIVE_PATH" "$TMP/$ASSET.sha256" "Bundle"
+fi
+
+if [ -z "$PAYLOAD_PATH" ]; then
+  if tar -tzf "$ARCHIVE_PATH" 2>/dev/null | head -50 | grep -qE "^(\./)?$PAYLOAD_NAME\$"; then
+    ARCHIVE_SHAPE="bundle"
+  else
+    ARCHIVE_SHAPE="program"
+  fi
+  if [ "$ARCHIVE_SHAPE" = "bundle" ]; then
+    # A local bundle is self-verifying through its sealed payload checksum; when the published
+    # outer .sha256 was transferred alongside it, verify that layer too.
+    if [ "$LOCAL_ARCHIVE" -eq 1 ] && [ -f "$ARCHIVE_PATH.sha256" ]; then
+      verify_sha256 "$ARCHIVE_PATH" "$ARCHIVE_PATH.sha256" "Bundle"
+    fi
+    BUNDLE_DIR="$TMP/bundle"
+    mkdir -p "$BUNDLE_DIR"
+    tar -xzf "$ARCHIVE_PATH" -C "$BUNDLE_DIR"
+    PAYLOAD_PATH="$BUNDLE_DIR/$PAYLOAD_NAME"
+    [ -f "$PAYLOAD_PATH" ] || fail "unexpected bundle layout: $PAYLOAD_NAME missing."
+    [ -f "$PAYLOAD_PATH.sha256" ] || fail "unexpected bundle layout: $PAYLOAD_NAME.sha256 missing."
+    verify_sha256 "$PAYLOAD_PATH" "$PAYLOAD_PATH.sha256" "Payload"
+  else
+    # Program archive (payload.tar.gz, or a pre-0.1.6 release archive). A local file needs an
+    # adjacent checksum — its own, or the canonical asset checksum next to a renamed legacy
+    # file; an online download was already verified against the published .sha256 above.
+    if [ "$LOCAL_ARCHIVE" -eq 1 ]; then
+      SHA_PATH="$ARCHIVE_PATH.sha256"
+      if [ ! -f "$SHA_PATH" ] && [ "$ARCHIVE_NAME" != "$ASSET" ] && [ -f "$archive_dir/$ASSET.sha256" ]; then
+        SHA_PATH="$archive_dir/$ASSET.sha256"
+      fi
+      [ -f "$SHA_PATH" ] || fail "offline checksum file not found: $SHA_PATH"
+      verify_sha256 "$ARCHIVE_PATH" "$SHA_PATH" "Payload"
+    fi
+    PAYLOAD_PATH="$ARCHIVE_PATH"
+  fi
+fi
+
+# --- Extract and validate in staging before touching the current install. The final same-filesystem
+#    swap keeps the previous dirs in .old.$$ until the installed command runs successfully; any
+#    move or launch failure restores them automatically. The data dir is never part of the swap. ---
+tar -xzf "$PAYLOAD_PATH" -C "$TMP"
+[ -d "$TMP/penguin" ] || fail "unexpected archive layout: top-level penguin/ missing."
+MANIFEST_PATH="$TMP/penguin/package-manifest.json"
+if [ -f "$MANIFEST_PATH" ]; then
+  manifest_target="$(sed -n 's/.*"target"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$MANIFEST_PATH" | head -n 1)"
+  [ -n "$manifest_target" ] || fail "package manifest is malformed: target missing."
+  [ "$manifest_target" = "$TARGET" ] \
+    || fail "package target mismatch: expected $TARGET, found $manifest_target."
+elif [ "$LOCAL_ARCHIVE" -eq 1 ] && [ "$ARCHIVE_SHAPE" = "program" ] && [ "$ARCHIVE_NAME" != "$ASSET" ]; then
+  fail "a renamed local archive must contain package-manifest.json; use the original filename for legacy packages."
+fi
+mkdir -p "$INSTALL_DIR"
+STAGING="$INSTALL_DIR/.staging.$$"
+OLD_DIR="$INSTALL_DIR/.old.$$"
+rm -rf "$STAGING"
+rm -rf "$OLD_DIR"
+mkdir -p "$STAGING"
+for d in bin lib web node; do
+  if [ -e "$TMP/penguin/$d" ]; then
+    mv "$TMP/penguin/$d" "$STAGING/$d"
+  fi
+done
+[ -x "$STAGING/bin/penguin" ] || fail "unexpected archive layout: bin/penguin missing."
+
+# The launcher resolves lib/, web/ and node/ relative to itself, so staging is a faithful
+# preflight that catches macOS execution policy and runtime/package failures before replacement.
+if candidate_version="$("$STAGING/bin/penguin" --version)"; then
+  [ -n "$candidate_version" ] || fail "candidate Adelie returned an empty version."
+else
+  candidate_status=$?
+  fail "candidate Adelie failed to run (exit status $candidate_status). See the error above."
+fi
+
+mkdir -p "$OLD_DIR"
+SWAP_ACTIVE=1
+for d in bin lib web node; do
+  if [ -e "$INSTALL_DIR/$d" ]; then
+    if relocate_dir "$INSTALL_DIR/$d" "$OLD_DIR/$d"; then
+      MOVED_OLD="$MOVED_OLD $d"
+    else
+      fail "could not move the existing $d directory aside (stop running penguin processes and retry); the previous installation will be restored."
+    fi
+  fi
+done
+for d in bin lib web node; do
+  if [ -e "$STAGING/$d" ]; then
+    if relocate_dir "$STAGING/$d" "$INSTALL_DIR/$d"; then
+      MOVED_NEW="$MOVED_NEW $d"
+    else
+      fail "could not install the new $d directory; the previous installation will be restored."
+    fi
+  fi
+done
+[ -x "$INSTALL_DIR/bin/penguin" ] || fail "install incomplete: $INSTALL_DIR/bin/penguin missing."
+
+# Verify again from the final path before deleting the backup. Keep stderr visible so platform
+# policy, permission and runtime errors are not disguised as an "unknown" version.
+if installed_version="$("$INSTALL_DIR/bin/penguin" --version)"; then
+  [ -n "$installed_version" ] || fail "installed Adelie returned an empty version."
+else
+  version_status=$?
+  fail "installed Adelie failed to run (exit status $version_status); the previous installation will be restored. See the error above."
+fi
+
+SWAP_ACTIVE=0
+if ! rm -rf "$OLD_DIR"; then
+  echo "warning: could not remove the previous installation backup at $OLD_DIR" >&2
+fi
+OLD_DIR=""
+rm -rf "$STAGING"
+STAGING=""
+
+# --- Symlink into ~/.local/bin and check PATH only after the install is known to work.
+#     --no-modify-path skips both: ~/.local/bin/penguin is one name, and a second
+#     installation that took it would hand its program to whoever types `penguin`. ---
+PATH_MISSING=0
+PENGUIN_COMMAND="penguin"
+if [ "$MODIFY_PATH" -eq 1 ]; then
+  mkdir -p "$BIN_DIR"
+  ln -sf "$INSTALL_DIR/bin/penguin" "$BIN_DIR/penguin"
+  case ":$PATH:" in
+    *":$BIN_DIR:"*) ;;
+    *) PATH_MISSING=1 ;;
+  esac
+else
+  PENGUIN_COMMAND="$INSTALL_DIR/bin/penguin"
+fi
+
+echo ""
+echo "Adelie $installed_version installed to $INSTALL_DIR"
+if [ "$PATH_MISSING" -eq 1 ]; then
+  echo ""
+  echo "note: installation succeeded, but $BIN_DIR is not on your PATH. Add it to your shell profile:"
+  case "${SHELL:-}" in
+    */zsh) echo "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc && source ~/.zshrc" ;;
+    */bash) echo "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc && source ~/.bashrc" ;;
+    */fish) echo "  fish_add_path \$HOME/.local/bin" ;;
+    *) echo "  export PATH=\"\$HOME/.local/bin:\$PATH\"" ;;
+  esac
+fi
+echo ""
+echo "Get started:"
+echo "  $PENGUIN_COMMAND --help    # all commands"
+echo "  $PENGUIN_COMMAND web       # start the Web UI at http://127.0.0.1:4000 (a first-login link is printed on first start)"
+echo "  $PENGUIN_COMMAND server    # headless server (PORT / HOST to override)"

package/dist/lock.d.ts

@@ -0,0 +1,26 @@
+interface ServerLock {
+    pid: number;
+    port: number;
+    startedAt: string;
+}
+declare function serverLockPath(root: string): string;
+/**
+ * The lock's text, parsed; anything that is not one reads as "no lock".
+ *
+ * Exported because a lock is also read where the file is not: a controller looking at
+ * ANOTHER machine gets this same text back from an ssh `cat` (machines/server-state.ts). The
+ * shape is defined once here so the two readers cannot drift apart.
+ */
+declare function parseServerLock(raw: string): ServerLock | null;
+/** Reads the lock file; a missing or malformed file reads as "no lock". */
+declare function readServerLock(root: string): ServerLock | null;
+/** True when the lock's process is alive AND its port accepts connections. */
+declare function isServerLockAlive(lock: ServerLock): Promise<boolean>;
+/** Convenience for pre-checks: the live lock on this root, or null (absent or stale). */
+declare function liveServerLock(root: string): Promise<ServerLock | null>;
+/** Writes the lock atomically (tmp + rename; the parent directory must already exist). */
+declare function acquireServerLock(root: string, lock: ServerLock): void;
+/** Removes the lock if it is still ours (best-effort; never throws on shutdown paths). */
+declare function releaseServerLock(root: string): void;
+
+export { type ServerLock, acquireServerLock, isServerLockAlive, liveServerLock, parseServerLock, readServerLock, releaseServerLock, serverLockPath };

package/dist/lock.js

@@ -0,0 +1,20 @@
+import {
+  acquireServerLock,
+  isServerLockAlive,
+  liveServerLock,
+  parseServerLock,
+  readServerLock,
+  releaseServerLock,
+  serverLockPath
+} from "./chunk-BQZC56BR.js";
+import "./chunk-B5IP37ZQ.js";
+export {
+  acquireServerLock,
+  isServerLockAlive,
+  liveServerLock,
+  parseServerLock,
+  readServerLock,
+  releaseServerLock,
+  serverLockPath
+};
+//# sourceMappingURL=lock.js.map

package/dist/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/machine-status.d.ts

@@ -0,0 +1,18 @@
+/** What `penguin server status` prints, as one line of JSON. */
+interface MachineStatus {
+    /** A server owns this root right now: its pid is alive and its port answers. */
+    running: boolean;
+    /** The live server's port and pid; null when nothing is running. */
+    port: number | null;
+    pid: number | null;
+    /**
+     * This machine's own id, or null when it has none yet — the id is minted the first time a
+     * server boots here, so an installed-but-never-run machine legitimately has none, and
+     * saying null is better than minting one to answer a question.
+     */
+    machineId: string | null;
+}
+/** `dbPath` may be elsewhere (ADELIE_WEB_DB, or its pre-rename PENGUIN_WEB_DB), as everywhere else that reads this database. */
+declare function readMachineStatus(root: string, dbPath?: string): Promise<MachineStatus>;
+
+export { type MachineStatus, readMachineStatus };

package/dist/machine-status.js

@@ -0,0 +1,38 @@
+import {
+  MachinesRepo
+} from "./chunk-HMTT2PX4.js";
+import {
+  liveServerLock
+} from "./chunk-BQZC56BR.js";
+import {
+  openDatabaseReadOnly
+} from "./chunk-ZZUQGQD6.js";
+import "./chunk-B5IP37ZQ.js";
+
+// src/machine-status.ts
+import fs from "fs";
+import path from "path";
+async function readMachineStatus(root, dbPath = path.join(root, "web.db")) {
+  const lock = await liveServerLock(root);
+  return {
+    running: lock !== null,
+    port: lock?.port ?? null,
+    pid: lock?.pid ?? null,
+    machineId: readMachineId(dbPath)
+  };
+}
+function readMachineId(dbPath) {
+  if (!fs.existsSync(dbPath)) return null;
+  const db = openDatabaseReadOnly(dbPath);
+  try {
+    return new MachinesRepo(db).peekOwnId();
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+export {
+  readMachineStatus
+};
+//# sourceMappingURL=machine-status.js.map

package/dist/machine-status.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/machine-status.ts"],"sourcesContent":["/**\n * \"Is a server running on this data root, and which machine is this?\" — answered from the\n * root itself, by whoever can read it, with no server needed and safely while one runs (the\n * same terms as `penguin auth token`, which writes to this database live).\n *\n * Exported as `@adelie/server/machine-status` for `penguin server status`, which\n * is how a CONTROLLER asks: it runs that one command over ssh and reads back JSON. The\n * question used to be asked in shell — `cat` the lock, `sed` the pid out of it, `kill -0`,\n * `cat` a second file for the id — which meant a parser on this side for a format with no\n * definition, and no answer at all from a Windows remote, `kill -0` having no cmd.exe\n * equivalent. Asking the machine's own CLI moves both problems to the side that has Node.\n *\n * Liveness is the local lock's own test (pid alive AND the port accepting), which the shell\n * version could not do: it only had `kill -0`, and a recycled pid reads as a live server.\n */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { openDatabaseReadOnly } from \"./db/database.js\";\nimport { MachinesRepo } from \"./db/repos/machines.js\";\nimport { liveServerLock } from \"./lock.js\";\n\n/** What `penguin server status` prints, as one line of JSON. */\nexport interface MachineStatus {\n  /** A server owns this root right now: its pid is alive and its port answers. */\n  running: boolean;\n  /** The live server's port and pid; null when nothing is running. */\n  port: number | null;\n  pid: number | null;\n  /**\n   * This machine's own id, or null when it has none yet — the id is minted the first time a\n   * server boots here, so an installed-but-never-run machine legitimately has none, and\n   * saying null is better than minting one to answer a question.\n   */\n  machineId: string | null;\n}\n\n/** `dbPath` may be elsewhere (ADELIE_WEB_DB, or its pre-rename PENGUIN_WEB_DB), as everywhere else that reads this database. */\nexport async function readMachineStatus(\n  root: string,\n  dbPath: string = path.join(root, \"web.db\"),\n): Promise<MachineStatus> {\n  const lock = await liveServerLock(root);\n  return {\n    running: lock !== null,\n    port: lock?.port ?? null,\n    pid: lock?.pid ?? null,\n    machineId: readMachineId(dbPath),\n  };\n}\n\n/**\n * Reads the id and changes nothing — and cannot: the connection is read-only.\n *\n * `openDatabaseReadOnly`, never `openDatabase`: the latter is the SCHEMA path — CREATE TABLE,\n * the ensureColumn list, an ALTER with a backfill, and the migrations. A controller asking a\n * machine what it is would then reshape that machine's database under the prepared statements\n * of the server running there, on a build that may be older than this question. A read-only\n * open makes that impossible rather than merely not done.\n *\n * Existence-checked first, because opening would create the file (and its directory) on a\n * root no server has ever used — a probe must not leave a data root behind it. A machine\n * whose database predates the `machine` table answers with no id rather than an error: it is\n * one that has never run a build that mints one, which is the truth about it.\n */\nfunction readMachineId(dbPath: string): string | null {\n  if (!fs.existsSync(dbPath)) return null;\n  const db = openDatabaseReadOnly(dbPath);\n  try {\n    return new MachinesRepo(db).peekOwnId();\n  } catch {\n    return null;\n  } finally {\n    db.close();\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAeA,OAAO,QAAQ;AACf,OAAO,UAAU;AAqBjB,eAAsB,kBACpB,MACA,SAAiB,KAAK,KAAK,MAAM,QAAQ,GACjB;AACxB,QAAM,OAAO,MAAM,eAAe,IAAI;AACtC,SAAO;AAAA,IACL,SAAS,SAAS;AAAA,IAClB,MAAM,MAAM,QAAQ;AAAA,IACpB,KAAK,MAAM,OAAO;AAAA,IAClB,WAAW,cAAc,MAAM;AAAA,EACjC;AACF;AAgBA,SAAS,cAAc,QAA+B;AACpD,MAAI,CAAC,GAAG,WAAW,MAAM,EAAG,QAAO;AACnC,QAAM,KAAK,qBAAqB,MAAM;AACtC,MAAI;AACF,WAAO,IAAI,aAAa,EAAE,EAAE,UAAU;AAAA,EACxC,QAAQ;AACN,WAAO;AAAA,EACT,UAAE;AACA,OAAG,MAAM;AAAA,EACX;AACF;","names":[]}