@task-handoff/server 0.0.3-alpha.3

package/README.md

@@ -0,0 +1,3 @@
+# @task-handoff/server
+
+Complete TaskHandoff server package. Installing it installs the control plane, node agent, and controlled instance runtimes at the same version. Run `task-handoff-install-server` as root to create and start the systemd services.

package/bin/task-handoff-install-server

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+function resolvePackageRoot(packageName) {
+  const manifest = require.resolve(`${packageName}/package.json`, { paths: [__dirname] });
+  return path.dirname(manifest);
+}
+
+function packageBin(packageName, binName) {
+  const packageRoot = resolvePackageRoot(packageName);
+  const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  const relativeBin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[binName];
+  if (!relativeBin) {
+    throw new Error(`${packageName} does not provide the ${binName} executable.`);
+  }
+  return path.join(packageRoot, relativeBin);
+}
+
+let controlPlane;
+let nodeAgent;
+let controlledInstance;
+try {
+  controlPlane = packageBin("@task-handoff/control-plane", "task-handoff-control-plane");
+  nodeAgent = packageBin("@task-handoff/node-agent", "task-handoff-node-agent");
+  controlledInstance = packageBin("@task-handoff/controlled-instance", "task-handoff-controlled-instance");
+} catch (error) {
+  console.error(`TaskHandoff server package is incomplete: ${error.message}`);
+  process.exit(1);
+}
+
+const result = spawnSync(
+  path.join(__dirname, "task-handoff-install-server-services"),
+  [
+    "--control-plane-bin",
+    controlPlane,
+    "--node-agent-bin",
+    nodeAgent,
+    "--controlled-instance-bin",
+    controlledInstance,
+    ...process.argv.slice(2),
+  ],
+  { stdio: "inherit" },
+);
+
+if (result.error) {
+  console.error(`Failed to start the TaskHandoff service installer: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/bin/task-handoff-install-server-services

@@ -0,0 +1,250 @@
+#!/bin/sh
+set -eu
+
+INSTALLER_BIN_DIR="$(CDPATH= cd -- "$(dirname "$0")" && pwd)"
+REPO_DIR="$(CDPATH= cd -- "$INSTALLER_BIN_DIR/.." && pwd)"
+TASK_HANDOFF_BIN=""
+TASK_HANDOFF_COMMAND=""
+CONTROL_PLANE_BIN=""
+NODE_AGENT_BIN=""
+CONTROLLED_INSTANCE_BIN=""
+CONTROL_PLANE_COMMAND=""
+NODE_AGENT_COMMAND=""
+CONTROLLED_INSTANCE_COMMAND=""
+SERVICE_USER="root"
+ENV_DIR="/etc/task-handoff"
+CONTROL_PLANE_DATA_DIR="/var/lib/task-handoff/control-plane"
+NODE_AGENT_DATA_DIR="/var/lib/task-handoff/node-agent"
+CONTROL_PLANE_HOST="0.0.0.0"
+CONTROL_PLANE_PORT="8081"
+NODE_AGENT_HOST="127.0.0.1"
+NODE_AGENT_PORT="8091"
+NODE_AGENT_IPC_PATH="/run/task-handoff/node-agent.sock"
+AUTH_MODE="password"
+STATIC_DIR=""
+
+usage() {
+  cat <<'USAGE'
+Usage: scripts/install-server-services.sh [options]
+
+Installs server-side TaskHandoff services on a systemd host:
+  task-handoff-node-agent.service
+  task-handoff-control-plane.service
+
+Options:
+  --repo-dir <path>                 Repository or unpacked release directory
+  --task-handoff-bin <path>         Legacy combined task-handoff executable
+  --control-plane-bin <path>        Control-plane executable
+  --node-agent-bin <path>           Node-agent executable
+  --controlled-instance-bin <path>  Controlled-instance executable for local runtimes
+  --service-user <user>             systemd service user, default root
+  --control-plane-data-dir <path>   Control-plane data directory
+  --node-agent-data-dir <path>      Node-agent data directory
+  --control-plane-host <host>       Control-plane bind host, default 0.0.0.0
+  --control-plane-port <port>       Control-plane port, default 8081
+  --node-agent-host <host>          Local node-agent bind host, default 127.0.0.1
+  --node-agent-port <port>          Local node-agent port, default 8091
+  --node-agent-ipc-path <path>      Local control socket, default /run/task-handoff/node-agent.sock
+  --auth-mode <mode>                Control-plane auth mode: password or disabled
+  --static-dir <path>               Built control-plane UI directory
+USAGE
+}
+
+need_root() {
+  if [ "$(id -u)" != "0" ]; then
+    echo "This installer must run as root. Re-run with sudo." >&2
+    exit 1
+  fi
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --repo-dir) REPO_DIR="${2:-}"; shift 2 ;;
+    --task-handoff-bin) TASK_HANDOFF_BIN="${2:-}"; shift 2 ;;
+    --control-plane-bin) CONTROL_PLANE_BIN="${2:-}"; shift 2 ;;
+    --node-agent-bin) NODE_AGENT_BIN="${2:-}"; shift 2 ;;
+    --controlled-instance-bin) CONTROLLED_INSTANCE_BIN="${2:-}"; shift 2 ;;
+    --service-user) SERVICE_USER="${2:-}"; shift 2 ;;
+    --control-plane-data-dir) CONTROL_PLANE_DATA_DIR="${2:-}"; shift 2 ;;
+    --node-agent-data-dir) NODE_AGENT_DATA_DIR="${2:-}"; shift 2 ;;
+    --control-plane-host) CONTROL_PLANE_HOST="${2:-}"; shift 2 ;;
+    --control-plane-port) CONTROL_PLANE_PORT="${2:-}"; shift 2 ;;
+    --node-agent-host) NODE_AGENT_HOST="${2:-}"; shift 2 ;;
+    --node-agent-port) NODE_AGENT_PORT="${2:-}"; shift 2 ;;
+    --node-agent-ipc-path) NODE_AGENT_IPC_PATH="${2:-}"; shift 2 ;;
+    --auth-mode) AUTH_MODE="${2:-}"; shift 2 ;;
+    --static-dir) STATIC_DIR="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+need_root
+
+if [ "$AUTH_MODE" != "password" ] && [ "$AUTH_MODE" != "disabled" ]; then
+  echo "--auth-mode must be password or disabled." >&2
+  exit 1
+fi
+
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "systemd is required for this installer." >&2
+  exit 1
+fi
+if ! command -v node >/dev/null 2>&1; then
+  echo "node is required for this installer." >&2
+  exit 1
+fi
+
+resolve_command() {
+  candidate="$1"
+  if [ -f "$candidate" ]; then
+    if [ -x "$candidate" ]; then
+      printf '%s\n' "$candidate"
+    else
+      if ! command -v node >/dev/null 2>&1; then
+        echo "node is required to run $candidate." >&2
+        exit 1
+      fi
+      printf '%s %s\n' "$(command -v node)" "$candidate"
+    fi
+  elif command -v "$candidate" >/dev/null 2>&1; then
+    command -v "$candidate"
+  else
+    echo "TaskHandoff executable was not found: $candidate" >&2
+    exit 1
+  fi
+}
+
+if [ -n "$TASK_HANDOFF_BIN" ]; then
+  TASK_HANDOFF_COMMAND="$(resolve_command "$TASK_HANDOFF_BIN")"
+elif [ -z "$CONTROL_PLANE_BIN" ] && [ -z "$NODE_AGENT_BIN" ] && [ -z "$CONTROLLED_INSTANCE_BIN" ] && [ -f "$REPO_DIR/bin/task-handoff.js" ]; then
+  TASK_HANDOFF_COMMAND="$(resolve_command "$REPO_DIR/bin/task-handoff.js")"
+fi
+
+if [ -n "$TASK_HANDOFF_COMMAND" ]; then
+  CONTROL_PLANE_COMMAND="$TASK_HANDOFF_COMMAND control-plane"
+  NODE_AGENT_COMMAND="$TASK_HANDOFF_COMMAND node-agent"
+  CONTROLLED_INSTANCE_COMMAND="$TASK_HANDOFF_COMMAND web"
+  if [ -z "$STATIC_DIR" ]; then
+    STATIC_DIR="$REPO_DIR/packages/control-plane-ui/dist"
+  fi
+else
+  if [ -z "$CONTROL_PLANE_BIN" ] && [ -f "$INSTALLER_BIN_DIR/task-handoff-control-plane" ]; then
+    CONTROL_PLANE_BIN="$INSTALLER_BIN_DIR/task-handoff-control-plane"
+  fi
+  if [ -z "$NODE_AGENT_BIN" ] && [ -f "$INSTALLER_BIN_DIR/task-handoff-node-agent" ]; then
+    NODE_AGENT_BIN="$INSTALLER_BIN_DIR/task-handoff-node-agent"
+  fi
+  if [ -z "$CONTROLLED_INSTANCE_BIN" ] && [ -f "$INSTALLER_BIN_DIR/task-handoff-controlled-instance" ]; then
+    CONTROLLED_INSTANCE_BIN="$INSTALLER_BIN_DIR/task-handoff-controlled-instance"
+  fi
+  CONTROL_PLANE_COMMAND="$(resolve_command "${CONTROL_PLANE_BIN:-task-handoff-control-plane}")"
+  NODE_AGENT_COMMAND="$(resolve_command "${NODE_AGENT_BIN:-task-handoff-node-agent}")"
+  CONTROLLED_INSTANCE_COMMAND="$(resolve_command "${CONTROLLED_INSTANCE_BIN:-task-handoff-controlled-instance}") web"
+fi
+
+CONTROL_PLANE_STATIC_OPTION=""
+if [ -n "$STATIC_DIR" ]; then
+  CONTROL_PLANE_STATIC_OPTION="--static-dir $STATIC_DIR"
+fi
+
+NODE_AGENT_IPC_ENDPOINT="$(node -e 'process.stdout.write(`ipc://${encodeURIComponent(process.argv[1])}`)' "$NODE_AGENT_IPC_PATH")"
+
+if [ "$SERVICE_USER" != "root" ] && ! id "$SERVICE_USER" >/dev/null 2>&1; then
+  useradd --system --create-home --home-dir /var/lib/task-handoff --shell /usr/sbin/nologin "$SERVICE_USER"
+fi
+if [ "$SERVICE_USER" != "root" ] && getent group docker >/dev/null 2>&1; then
+  usermod -aG docker "$SERVICE_USER" || true
+fi
+
+assert_service_command_accessible() {
+  command_value="$1"
+  command_label="$2"
+  executable="${command_value%% *}"
+  if [ "$SERVICE_USER" != "root" ] && command -v runuser >/dev/null 2>&1 && ! runuser -u "$SERVICE_USER" -- test -x "$executable"; then
+    echo "$command_label is not executable by service user $SERVICE_USER: $executable" >&2
+    echo "Install Node.js and TaskHandoff under a system-wide prefix such as /usr/local, not a root-only NVM directory." >&2
+    exit 1
+  fi
+}
+
+assert_service_command_accessible "$CONTROL_PLANE_COMMAND" "Control-plane command"
+assert_service_command_accessible "$NODE_AGENT_COMMAND" "Node-agent command"
+assert_service_command_accessible "$CONTROLLED_INSTANCE_COMMAND" "Controlled-instance command"
+
+mkdir -p "$ENV_DIR" "$CONTROL_PLANE_DATA_DIR" "$NODE_AGENT_DATA_DIR"
+chown -R "$SERVICE_USER":"$SERVICE_USER" "$CONTROL_PLANE_DATA_DIR" "$NODE_AGENT_DATA_DIR" 2>/dev/null || true
+
+cat > "$ENV_DIR/node-agent.env" <<EOF
+TASK_HANDOFF_NODE_AGENT_HOST=$NODE_AGENT_HOST
+TASK_HANDOFF_NODE_AGENT_PORT=$NODE_AGENT_PORT
+TASK_HANDOFF_NODE_AGENT_DATA_DIR=$NODE_AGENT_DATA_DIR
+TASK_HANDOFF_NODE_AGENT_CONNECTION_MODE=local-ipc
+TASK_HANDOFF_NODE_AGENT_IPC_PATH=$NODE_AGENT_IPC_PATH
+TASK_HANDOFF_NODE_AGENT_CONTAINER_URL=http://host.docker.internal:$NODE_AGENT_PORT
+TASK_HANDOFF_LOCAL_CONTROLLED_COMMAND=$CONTROLLED_INSTANCE_COMMAND
+EOF
+chmod 0640 "$ENV_DIR/node-agent.env"
+
+cat > "$ENV_DIR/control-plane.env" <<EOF
+TASK_HANDOFF_CONTROL_PLANE_HOST=$CONTROL_PLANE_HOST
+TASK_HANDOFF_CONTROL_PLANE_PORT=$CONTROL_PLANE_PORT
+TASK_HANDOFF_CONTROL_PLANE_DATA_DIR=$CONTROL_PLANE_DATA_DIR
+TASK_HANDOFF_CONTROL_PLANE_STATIC_DIR=$STATIC_DIR
+TASK_HANDOFF_CONTROL_PLANE_AUTH_MODE=$AUTH_MODE
+TASK_HANDOFF_NODE_AGENT_ENDPOINT=http://$NODE_AGENT_HOST:$NODE_AGENT_PORT
+TASK_HANDOFF_NODE_AGENT_CONTROL_ENDPOINT=$NODE_AGENT_IPC_ENDPOINT
+TASK_HANDOFF_NODE_AGENT_CONTAINER_URL=http://host.docker.internal:$NODE_AGENT_PORT
+EOF
+chmod 0640 "$ENV_DIR/control-plane.env"
+
+cat > /etc/systemd/system/task-handoff-node-agent.service <<EOF
+[Unit]
+Description=TaskHandoff Local Node Agent
+After=network-online.target docker.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=$SERVICE_USER
+WorkingDirectory=$NODE_AGENT_DATA_DIR
+RuntimeDirectory=task-handoff
+RuntimeDirectoryMode=0700
+EnvironmentFile=-$ENV_DIR/node-agent.env
+ExecStart=$NODE_AGENT_COMMAND --host $NODE_AGENT_HOST --port $NODE_AGENT_PORT --data-dir $NODE_AGENT_DATA_DIR --connection-mode local-ipc --ipc-path $NODE_AGENT_IPC_PATH
+Restart=always
+RestartSec=3
+KillSignal=SIGTERM
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+cat > /etc/systemd/system/task-handoff-control-plane.service <<EOF
+[Unit]
+Description=TaskHandoff Control Plane
+After=network-online.target task-handoff-node-agent.service
+Wants=network-online.target task-handoff-node-agent.service
+
+[Service]
+Type=simple
+User=$SERVICE_USER
+WorkingDirectory=$CONTROL_PLANE_DATA_DIR
+EnvironmentFile=-$ENV_DIR/control-plane.env
+ExecStartPre=/bin/sh -c 'for i in \$(seq 1 30); do [ -S "$NODE_AGENT_IPC_PATH" ] && exit 0; sleep 1; done; exit 1'
+ExecStart=$CONTROL_PLANE_COMMAND --host $CONTROL_PLANE_HOST --port $CONTROL_PLANE_PORT --data-dir $CONTROL_PLANE_DATA_DIR $CONTROL_PLANE_STATIC_OPTION --auth-mode $AUTH_MODE
+Restart=always
+RestartSec=3
+KillSignal=SIGTERM
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable --now task-handoff-node-agent.service
+systemctl enable --now task-handoff-control-plane.service
+
+echo "TaskHandoff server services are installed."
+echo "Control plane: task-handoff-control-plane.service on $CONTROL_PLANE_HOST:$CONTROL_PLANE_PORT"
+echo "Local node-agent: task-handoff-node-agent.service on $NODE_AGENT_HOST:$NODE_AGENT_PORT"

package/bin/task-handoff-server

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const http = require("node:http");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+
+function usage() {
+  console.log(`Usage: task-handoff-server <command> [options]
+
+Commands:
+  status                      Show installed version and service state
+  check [options]             Check npm for an available version
+  update [options]            Update from npm and restart services safely
+
+Update options:
+  --channel <channel>         npm channel: stable, beta, or alpha (default: stable)
+  --to <version>              Install an exact version instead of a channel
+  --registry <url>            Use a specific npm registry
+  --force                     Reinstall even when the resolved version is unchanged
+`);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", ...options });
+  if (result.status !== 0) {
+    const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    throw new Error(`${command} ${args.join(" ")} failed${output ? `:\n${output}` : ""}`);
+  }
+  return String(result.stdout || "").trim();
+}
+
+function findGlobalPrefix() {
+  let current = packageRoot;
+  while (current !== path.dirname(current)) {
+    if (path.basename(current) === "node_modules" && path.basename(path.dirname(current)) === "lib") {
+      return path.dirname(path.dirname(current));
+    }
+    current = path.dirname(current);
+  }
+  throw new Error(`Cannot determine the npm global prefix from ${packageRoot}.`);
+}
+
+function parseEnvFile(file) {
+  const values = {};
+  if (!fs.existsSync(file)) return values;
+  for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+    if (!line || line.startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator <= 0) continue;
+    values[line.slice(0, separator)] = line.slice(separator + 1);
+  }
+  return values;
+}
+
+function serviceUser() {
+  const unit = "/etc/systemd/system/task-handoff-node-agent.service";
+  if (!fs.existsSync(unit)) return "root";
+  const match = fs.readFileSync(unit, "utf8").match(/^User=(.+)$/m);
+  return match?.[1] || "root";
+}
+
+function currentInstallOptions() {
+  const controlPlane = parseEnvFile("/etc/task-handoff/control-plane.env");
+  const nodeAgent = parseEnvFile("/etc/task-handoff/node-agent.env");
+  return [
+    "--service-user", serviceUser(),
+    "--control-plane-data-dir", controlPlane.TASK_HANDOFF_CONTROL_PLANE_DATA_DIR || "/var/lib/task-handoff/control-plane",
+    "--node-agent-data-dir", nodeAgent.TASK_HANDOFF_NODE_AGENT_DATA_DIR || "/var/lib/task-handoff/node-agent",
+    "--control-plane-host", controlPlane.TASK_HANDOFF_CONTROL_PLANE_HOST || "0.0.0.0",
+    "--control-plane-port", controlPlane.TASK_HANDOFF_CONTROL_PLANE_PORT || "8081",
+    "--node-agent-host", nodeAgent.TASK_HANDOFF_NODE_AGENT_HOST || "127.0.0.1",
+    "--node-agent-port", nodeAgent.TASK_HANDOFF_NODE_AGENT_PORT || "8091",
+    "--node-agent-ipc-path", nodeAgent.TASK_HANDOFF_NODE_AGENT_IPC_PATH || "/run/task-handoff/node-agent.sock",
+    "--auth-mode", controlPlane.TASK_HANDOFF_CONTROL_PLANE_AUTH_MODE || "password",
+  ];
+}
+
+function systemctlState(service) {
+  const result = spawnSync("systemctl", ["is-active", service], { encoding: "utf8" });
+  return String(result.stdout || "unknown").trim() || "unknown";
+}
+
+function npmVersion(target, registry) {
+  const args = ["view", `@task-handoff/server@${target}`, "version", "--json"];
+  if (registry) args.push("--registry", registry);
+  const value = JSON.parse(run("npm", args));
+  if (typeof value !== "string") throw new Error(`npm target ${target} did not resolve to one version.`);
+  return value;
+}
+
+function npmTagForChannel(channel) {
+  return channel === "stable" ? "latest" : channel;
+}
+
+function waitForSocket(socketPath, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      if (fs.statSync(socketPath).isSocket()) return;
+    } catch {}
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+  }
+  throw new Error(`Node agent socket was not ready after ${timeoutMs}ms: ${socketPath}`);
+}
+
+function waitForHttp(port, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const attempt = () => {
+      const request = http.get({ host: "127.0.0.1", port, path: "/api/health", timeout: 1000 }, (response) => {
+        response.resume();
+        if (response.statusCode === 200) return resolve();
+        retry();
+      });
+      request.on("timeout", () => request.destroy());
+      request.on("error", retry);
+    };
+    const retry = () => {
+      if (Date.now() >= deadline) return reject(new Error(`Control plane was not healthy on port ${port} after ${timeoutMs}ms.`));
+      setTimeout(attempt, 250);
+    };
+    attempt();
+  });
+}
+
+function acquireLock() {
+  const lock = "/run/task-handoff-server-update.lock";
+  try {
+    fs.mkdirSync(lock);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error("Another TaskHandoff server update is already running.");
+    throw error;
+  }
+  return () => fs.rmSync(lock, { recursive: true, force: true });
+}
+
+function parseOptions(args, allowExactVersion) {
+  let channel = "stable";
+  let channelExplicit = false;
+  let exactVersion = "";
+  let registry = "";
+  let force = false;
+  while (args.length) {
+    const option = args.shift();
+    if (option === "--channel") {
+      channel = args.shift() || "";
+      channelExplicit = true;
+    }
+    else if (option === "--to" && allowExactVersion) exactVersion = args.shift() || "";
+    else if (option === "--registry") registry = args.shift() || "";
+    else if (option === "--force" && allowExactVersion) force = true;
+    else throw new Error(`Unknown option: ${option}`);
+  }
+  if (!new Set(["stable", "beta", "alpha"]).has(channel)) {
+    throw new Error("--channel must be stable, beta, or alpha.");
+  }
+  if (channelExplicit && exactVersion) throw new Error("Use either --channel or --to, not both.");
+  if (allowExactVersion && exactVersion && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(exactVersion)) {
+    throw new Error("--to must be an exact semantic version.");
+  }
+  return { target: exactVersion || npmTagForChannel(channel), channel, registry, force };
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    usage();
+    return;
+  }
+  if (command === "status") {
+    console.log(`Package: @task-handoff/server ${manifest.version}`);
+    console.log(`Node agent: ${systemctlState("task-handoff-node-agent.service")}`);
+    console.log(`Control plane: ${systemctlState("task-handoff-control-plane.service")}`);
+    return;
+  }
+  if (command === "check") {
+    const { target, channel, registry } = parseOptions(process.argv.slice(3), false);
+    const available = npmVersion(target, registry);
+    console.log(`Installed: ${manifest.version}`);
+    console.log(`Available (${channel} channel, npm ${target}): ${available}`);
+    console.log(available === manifest.version ? "Up to date." : `Update available: task-handoff-server update --to ${available}`);
+    return;
+  }
+  if (command !== "update") throw new Error(`Unknown command: ${command}`);
+  if (typeof process.getuid === "function" && process.getuid() !== 0) {
+    throw new Error("Run updates as root so npm and systemd can be updated.");
+  }
+  const { target, registry, force } = parseOptions(process.argv.slice(3), true);
+  const targetVersion = target === manifest.version ? manifest.version : npmVersion(target, registry);
+  if (targetVersion === manifest.version && !force) {
+    console.log(`@task-handoff/server ${manifest.version} is already installed.`);
+    return;
+  }
+  const releaseLock = acquireLock();
+  try {
+    const prefix = findGlobalPrefix();
+    const installOptions = currentInstallOptions();
+    const nodeSocket = installOptions[installOptions.indexOf("--node-agent-ipc-path") + 1];
+    const controlPlanePort = Number(installOptions[installOptions.indexOf("--control-plane-port") + 1]);
+    console.log(`Updating @task-handoff/server ${manifest.version} -> ${targetVersion}`);
+    const npmArgs = ["install", "--global", "--prefix", prefix, `@task-handoff/server@${targetVersion}`];
+    if (registry) npmArgs.push("--registry", registry);
+    run("npm", npmArgs, { stdio: "inherit" });
+    run(path.join(prefix, "bin", "task-handoff-install-server"), installOptions, { stdio: "inherit" });
+    run("systemctl", ["restart", "task-handoff-node-agent.service"]);
+    waitForSocket(nodeSocket);
+    run("systemctl", ["restart", "task-handoff-control-plane.service"]);
+    await waitForHttp(controlPlanePort);
+    console.log(`Updated TaskHandoff server to ${targetVersion}.`);
+  } catch (error) {
+    console.error(`Update failed. To reinstall the previous version, run: npm install -g @task-handoff/server@${manifest.version}`);
+    throw error;
+  } finally {
+    releaseLock();
+  }
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@task-handoff/server",
+  "version": "0.0.3-alpha.3",
+  "description": "Complete TaskHandoff server package.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "task-handoff-install-server": "bin/task-handoff-install-server",
+    "task-handoff-server-install": "bin/task-handoff-install-server",
+    "task-handoff-server": "bin/task-handoff-server"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "dependencies": {
+    "@task-handoff/control-plane": "0.0.3-alpha.3",
+    "@task-handoff/node-agent": "0.0.3-alpha.3",
+    "@task-handoff/controlled-instance": "0.0.3-alpha.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}