pixelremotecontrol 0.0.0-stage → 0.1.0

package/DISCLOSURE

@@ -0,0 +1,5 @@
+# Authorized remote device control
+
+This package mirrors and controls an Android device that its owner has deliberately paired for ADB Wireless debugging and connected to a trusted SSH relay. It can wake, lock, and restart that device. The phone holder starts sharing from Termux and can stop the session at any time. A viewer must authenticate to the relay and have access through its private network.
+
+The commands are intended for development, support, and access to devices owned by the operator or used with the owner's permission. They do not bypass Android's lock screen, ADB pairing, SSH authentication, or Tailscale authorization. The package does not collect credentials or device data.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# pixelremotecontrol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command line launcher for a paired Pixel 8 and a private SSH relay. Use it only
+with a device you own or are authorized to control.
+
+On a Windows viewer PC:
+
+```powershell
+npm.cmd install -g pixelremotecontrol
+pixelremotecontrol setup --host YOUR_RELAY_TAILSCALE_IP --user YOUR_SSH_USERNAME
+pixelremotecontrol control local pixel8
+```
+
+`setup` saves the relay address for this viewer and downloads the official
+scrcpy Windows bundle (including `adb`). A later `control` run downloads it if
+needed. Windows OpenSSH Client and Tailscale access to the relay are required.
+SSH authentication is interactive; no password is stored by this package.
+Use `npm.cmd` in PowerShell because Windows execution policy may block
+`npm.ps1`. The `pixelremotecontrol` command uses a `.cmd` launcher and works
+under a Restricted PowerShell execution policy.
+If an older manual installation is still on `PATH`, check which launcher wins
+with `Get-Command pixelremotecontrol -All`. Move the old launcher out of `PATH`
+so the npm `.cmd` is selected.
+
+In Termux on the configured Pixel:
+
+```sh
+pkg install nodejs npm
+npm install -g pixelremotecontrol
+pixelremotecontrol setup
+pixelremotecontrol startservice pixel8 asml
+```
+
+If an older standalone `pixelremotecontrol` launcher is already in Termux's
+`$PREFIX/bin`, save it before installing the npm package:
+
+```sh
+mv "$PREFIX/bin/pixelremotecontrol" "$PREFIX/bin/pixelremotecontrol.pre-npm"
+npm install -g pixelremotecontrol
+```
+
+The command installs missing Termux `openssh`, `coreutils`, and `procps`
+packages. It
+uses the phone's existing relay config at `~/.config/pixel-connect/config`
+and key at `~/.ssh/central_tunnel`; it never writes or replaces them. Android
+Wireless debugging and relay ADB pairing must already be enabled. The command
+prompts for the Android connection port when Termux cannot discover it.
+The central machine must already have `pixelctl.cmd` provisioned, its ADB
+service paired with the Pixel, and a restricted SSH tunnel account that the
+phone's key can use. This package cannot complete Tailscale sign-in or
+Android's first-time ADB pairing for you.
+
+`pixelremotecontrol wake local pixel8`, `lock`, `restart`, and `status` work on
+the Windows viewer. `control asml pixel8` opens a window on the ASML desktop
+when run there. The current relay scripts support one configured Pixel 8.

package/assets/phone/pixel-connect

@@ -0,0 +1,68 @@
+#!/data/data/com.termux/files/usr/bin/bash
+set -euo pipefail
+
+config="${PIXEL_CONNECT_CONFIG:-$HOME/.config/pixel-connect/config}"
+if [[ ! -r "$config" ]]; then
+  printf 'Missing %s. Copy config.example there and set CENTRAL_HOST and CENTRAL_USER.\n' "$config" >&2
+  exit 2
+fi
+# The config is owned and edited by the phone's Termux user.
+# shellcheck source=/dev/null
+source "$config"
+
+CENTRAL_HOST="${CENTRAL_HOST:-}"
+CENTRAL_USER="${CENTRAL_USER:-}"
+CENTRAL_SSH_PORT="${CENTRAL_SSH_PORT:-22}"
+CENTRAL_ADB_PORT="${CENTRAL_ADB_PORT:-15555}"
+CENTRAL_PAIR_PORT="${CENTRAL_PAIR_PORT:-15556}"
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: pixel-connect CONNECT_PORT [PAIR_PORT]
+
+Read CONNECT_PORT from Android Settings > Developer options > Wireless debugging
+("IP address & Port"). For first-time pairing, also open "Pair device with
+pairing code" and pass that separate PAIR_PORT. Press Ctrl+C to disconnect.
+USAGE
+  exit 2
+}
+
+valid_port() {
+  [[ "$1" =~ ^[0-9]{1,5}$ ]] && (( 10#$1 >= 1 && 10#$1 <= 65535 ))
+}
+
+[[ $# -ge 1 && $# -le 2 ]] || usage
+connect_port="$1"
+valid_port "$connect_port" || usage
+if [[ $# -eq 2 ]]; then
+  pair_port="$2"
+  valid_port "$pair_port" || usage
+fi
+if [[ -z "$CENTRAL_HOST" || -z "$CENTRAL_USER" ]]; then
+  printf 'Set CENTRAL_HOST and CENTRAL_USER in %s.\n' "$config" >&2
+  exit 2
+fi
+for port in "$CENTRAL_SSH_PORT" "$CENTRAL_ADB_PORT" "$CENTRAL_PAIR_PORT"; do
+  valid_port "$port" || { printf 'Invalid port in %s.\n' "$config" >&2; exit 2; }
+done
+
+key="$HOME/.ssh/central_tunnel"
+[[ -r "$key" ]] || { printf 'Missing SSH key: %s\n' "$key" >&2; exit 2; }
+
+ssh_args=(
+  -N -T -i "$key" -p "$CENTRAL_SSH_PORT"
+  -o BatchMode=yes
+  -o ExitOnForwardFailure=yes
+  -o ServerAliveInterval=20
+  -o ServerAliveCountMax=3
+  -o StrictHostKeyChecking=yes
+  -R "127.0.0.1:${CENTRAL_ADB_PORT}:127.0.0.1:${connect_port}"
+)
+if [[ -n "${pair_port:-}" ]]; then
+  ssh_args+=( -R "127.0.0.1:${CENTRAL_PAIR_PORT}:127.0.0.1:${pair_port}" )
+fi
+
+printf 'Connecting Pixel ADB to %s:%s (central loopback port %s).\n' \
+  "$CENTRAL_HOST" "$CENTRAL_SSH_PORT" "$CENTRAL_ADB_PORT"
+printf 'Keep this Termux session open. Press Ctrl+C or run pixel-disconnect to stop sharing.\n'
+exec ssh "${ssh_args[@]}" "${CENTRAL_USER}@${CENTRAL_HOST}"

package/assets/phone/pixelremotecontrol

@@ -0,0 +1,143 @@
+#!/data/data/com.termux/files/usr/bin/bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: pixelremotecontrol startservice <mobiledevice> <destination> [CONNECT_PORT]
+
+  mobiledevice: pixel8, pixel, thisdevice, or thismachine
+  destination:  asml (or the host configured for pixel-connect)
+
+Run this in Termux on the Pixel. Wireless debugging must be enabled. If its
+connection port cannot be found automatically, this command asks for the
+"IP address & Port" shown in Android's Wireless debugging settings.
+USAGE
+  exit 2
+}
+
+valid_port() {
+  [[ "$1" =~ ^[0-9]{1,5}$ ]] && (( 10#$1 >= 1 && 10#$1 <= 65535 ))
+}
+
+port_open() {
+  # The reverse tunnel connects to the phone's own loopback ADB listener.
+  # A two-second limit avoids hanging if the listener is unavailable.
+  timeout 2 bash -c 'exec 3<>"/dev/tcp/127.0.0.1/$1"' _ "$1" >/dev/null 2>&1
+}
+
+[[ $# -ge 3 && $# -le 4 && "$1" == startservice ]] || usage
+device="${2,,}"
+destination="${3,,}"
+case "$device" in
+  pixel8|pixel|thisdevice|thismachine) ;;
+  *) printf 'Unknown mobile device: %s\n' "$2" >&2; usage ;;
+esac
+
+config="${PIXEL_CONNECT_CONFIG:-$HOME/.config/pixel-connect/config}"
+cache="$(dirname "$config")/last-connect-port"
+if [[ ! -r "$config" ]]; then
+  printf 'Missing pixel-connect configuration: %s\n' "$config" >&2
+  exit 2
+fi
+# The config is owned and edited by the phone's Termux user.
+# shellcheck source=/dev/null
+source "$config"
+CENTRAL_HOST="${CENTRAL_HOST:-}"
+CENTRAL_USER="${CENTRAL_USER:-}"
+CENTRAL_ADB_PORT="${CENTRAL_ADB_PORT:-15555}"
+if [[ -z "$CENTRAL_HOST" || -z "$CENTRAL_USER" ]] || ! valid_port "$CENTRAL_ADB_PORT"; then
+  printf 'Set a valid CENTRAL_HOST, CENTRAL_USER, and CENTRAL_ADB_PORT in %s.\n' "$config" >&2
+  exit 2
+fi
+case "$destination" in
+  asml|"${CENTRAL_HOST,,}"|"${CENTRAL_USER,,}@${CENTRAL_HOST,,}") ;;
+  *) printf 'Destination %s does not match the configured central machine (%s).\n' "$3" "$CENTRAL_HOST" >&2; exit 2 ;;
+esac
+command -v pixel-connect >/dev/null 2>&1 || {
+  printf 'pixel-connect is not installed in Termux. Install the Pixel phone tools first.\n' >&2
+  exit 2
+}
+command -v timeout >/dev/null 2>&1 || {
+  printf 'The Termux coreutils package is required (pkg install coreutils).\n' >&2
+  exit 2
+}
+
+# Find only this phone's existing reverse tunnel to the configured machine.
+pattern="^ssh -N -T -i .*/central_tunnel .* -R 127\\.0\\.0\\.1:${CENTRAL_ADB_PORT}:"
+mapfile -t tunnel_pids < <(pgrep -f "$pattern" || true)
+active_port=''
+if ((${#tunnel_pids[@]})); then
+  for pid in "${tunnel_pids[@]}"; do
+    [[ -r "/proc/$pid/cmdline" ]] || continue
+    cmdline="$(tr '\0' ' ' < "/proc/$pid/cmdline")"
+    [[ "$cmdline" == *" ${CENTRAL_USER}@${CENTRAL_HOST} "* ]] || continue
+    if [[ "$cmdline" =~ 127\.0\.0\.1:${CENTRAL_ADB_PORT}:127\.0\.0\.1:([0-9]+) ]]; then
+      active_port="${BASH_REMATCH[1]}"
+      active_pid="$pid"
+      break
+    fi
+  done
+fi
+
+connect_port=''
+if [[ $# -eq 4 ]]; then
+  connect_port="$4"
+elif [[ -n "${PIXEL_CONNECT_PORT:-}" ]]; then
+  connect_port="$PIXEL_CONNECT_PORT"
+else
+  # This Android system property may be hidden from Termux on some builds.
+  if command -v getprop >/dev/null 2>&1; then
+    property_port="$(getprop service.adb.tls.port 2>/dev/null || true)"
+    if valid_port "$property_port" && port_open "$property_port"; then
+      connect_port="$property_port"
+    fi
+  fi
+  if [[ -z "$connect_port" && -n "$active_port" ]] && port_open "$active_port"; then
+    connect_port="$active_port"
+  fi
+  if [[ -z "$connect_port" && -r "$cache" ]]; then
+    IFS= read -r cached_port < "$cache" || true
+    if valid_port "${cached_port:-}" && port_open "$cached_port"; then
+      connect_port="$cached_port"
+    fi
+  fi
+fi
+
+if [[ -z "$connect_port" ]]; then
+  if [[ ! -t 0 ]]; then
+    printf 'Wireless debugging port unknown. Run interactively or pass CONNECT_PORT from Settings > System > Developer options > Wireless debugging > IP address & Port.\n' >&2
+    exit 2
+  fi
+  printf 'Open Settings > System > Developer options > Wireless debugging.\n'
+  printf 'Enable Wireless debugging and read the port under "IP address & Port".\n'
+  while :; do
+    printf 'Connection port: '
+    IFS= read -r connect_port || exit 2
+    if valid_port "$connect_port" && port_open "$connect_port"; then
+      break
+    fi
+    printf 'That port is invalid or not listening on this phone. Check Wireless debugging and try again.\n' >&2
+  done
+elif ! valid_port "$connect_port" || ! port_open "$connect_port"; then
+  printf 'Wireless debugging is not listening on port %s. Check its "IP address & Port" in Android Settings.\n' "$connect_port" >&2
+  exit 2
+fi
+
+if [[ -n "$active_port" ]]; then
+  if [[ "$active_port" == "$connect_port" ]]; then
+    printf 'Pixel service is already connected to %s using wireless debugging port %s.\n' "$CENTRAL_HOST" "$connect_port"
+    exit 0
+  fi
+  printf 'Replacing the stale Pixel tunnel (port %s) with port %s.\n' "$active_port" "$connect_port"
+  kill "$active_pid" 2>/dev/null || true
+  # Give sshd time to release the existing reverse-forwarded port.
+  for ((attempt=0; attempt<20; attempt++)); do
+    kill -0 "$active_pid" 2>/dev/null || break
+    sleep 0.1
+  done
+fi
+
+mkdir -p "$(dirname "$cache")"
+umask 077
+printf '%s\n' "$connect_port" > "$cache"
+exec pixel-connect "$connect_port"

package/assets/viewer/pixelremotecontrol-core.ps1

@@ -0,0 +1,207 @@
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)]
+    [string]$Action = 'control',
+    [Parameter(Position = 1)]
+    [string]$Display = 'local',
+    [Parameter(Position = 2)]
+    [string]$DeviceId = 'pixel8',
+    [string]$CentralHost = '',
+    [string]$CentralUser = '',
+    [ValidateRange(1, 65535)]
+    [int]$SshPort = 22,
+    [ValidateRange(1024, 65535)]
+    [int]$AdbForwardPort = 5038,
+    [ValidateRange(1024, 65535)]
+    [int]$VideoPort = 27183,
+    [string]$ScrcpyPath = '',
+    [string]$AdbPath = '',
+    [ValidateRange(0, 86400)]
+    [int]$TimeLimitSeconds = 0,
+    [switch]$Help
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Show-Usage {
+    Write-Host 'Usage: pixelremotecontrol control <local|asml> <pixel8|Pixel_8> [options]'
+    Write-Host '       pixelremotecontrol <wake|lock|restart|status> <local|asml> <pixel8|Pixel_8>'
+    Write-Host 'Options: -CentralHost HOST -CentralUser USER -SshPort PORT -ScrcpyPath PATH -AdbPath PATH'
+    Write-Host 'Run "control local" on a Windows viewer to see and control the Pixel here.'
+    Write-Host 'Run "control asml" only in an interactive desktop session on ASML.'
+}
+
+function Resolve-Program {
+    param([string]$Name, [string]$ExplicitPath, [string]$SiblingPath)
+    if ($ExplicitPath) {
+        if (-not (Test-Path -LiteralPath $ExplicitPath -PathType Leaf)) {
+            throw "$Name was not found at '$ExplicitPath'."
+        }
+        return (Resolve-Path -LiteralPath $ExplicitPath).Path
+    }
+    if ($SiblingPath -and (Test-Path -LiteralPath $SiblingPath -PathType Leaf)) {
+        return (Resolve-Path -LiteralPath $SiblingPath).Path
+    }
+    $besideScript = Join-Path $PSScriptRoot $Name
+    if (Test-Path -LiteralPath $besideScript -PathType Leaf) {
+        return (Resolve-Path -LiteralPath $besideScript).Path
+    }
+    $command = Get-Command $Name -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($command) { return $command.Source }
+    if ($env:LOCALAPPDATA) {
+        $packages = Join-Path $env:LOCALAPPDATA 'Microsoft\WinGet\Packages'
+        if (Test-Path -LiteralPath $packages -PathType Container) {
+            $found = Get-ChildItem -LiteralPath $packages -Directory -Filter 'Genymobile.scrcpy*' -ErrorAction SilentlyContinue |
+                ForEach-Object { Get-ChildItem -LiteralPath $_.FullName -Directory -Filter 'scrcpy-win64-*' -ErrorAction SilentlyContinue } |
+                Sort-Object Name -Descending |
+                ForEach-Object { Join-Path $_.FullName $Name } |
+                Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } |
+                Select-Object -First 1
+            if ($found) { return $found }
+        }
+    }
+    throw "$Name was not found. Extract the scrcpy Windows ZIP or pass the corresponding path option."
+}
+
+function Test-PortFree {
+    param([int]$Port)
+    $listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Loopback, $Port)
+    try { $listener.Start() }
+    catch { throw "Local port $Port is already in use. Close the other viewer or choose another forward port." }
+    finally { $listener.Stop() }
+}
+
+function Test-PortOpen {
+    param([int]$Port)
+    $client = New-Object System.Net.Sockets.TcpClient
+    try {
+        $pending = $client.BeginConnect('127.0.0.1', $Port, $null, $null)
+        if (-not $pending.AsyncWaitHandle.WaitOne(200)) { return $false }
+        $client.EndConnect($pending)
+        return $true
+    } catch { return $false }
+    finally { $client.Dispose() }
+}
+
+function Invoke-Adb {
+    param([string]$Program, [string[]]$Arguments)
+    # Windows PowerShell 5.1 may turn a native stderr line into a terminating
+    # NativeCommandError when ErrorActionPreference is Stop.
+    $oldPreference = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = @(& $Program @Arguments 2>&1 | ForEach-Object { $_.ToString() })
+        $exitCode = $LASTEXITCODE
+        return [pscustomobject]@{ Output = $output; ExitCode = $exitCode }
+    } finally { $ErrorActionPreference = $oldPreference }
+}
+
+try {
+    if ($Help -or $Action -in @('help', '--help', '-help', '/?')) { Show-Usage; exit 0 }
+
+    if ($Display -eq 'thismachine') { $Display = 'local' }
+    if ($Action -notin @('control', 'wake', 'lock', 'restart', 'status')) {
+        throw "Unknown action '$Action'. Run pixelremotecontrol --help."
+    }
+    if ($Display -notin @('local', 'asml')) {
+        throw "Unknown display '$Display'. Use local or asml."
+    }
+    if ($DeviceId -notin @('pixel8', 'pixel_8', 'pixel-8', '127.0.0.1:15555')) {
+        throw "Unknown device '$DeviceId'. This relay currently has one registered device: pixel8 (Pixel_8)."
+    }
+    if ($CentralUser -notmatch '^[A-Za-z0-9._-]+$') { throw 'CentralUser contains invalid SSH username characters.' }
+    if ($CentralHost -notmatch '^[A-Za-z0-9.:-]+$') { throw 'CentralHost contains invalid SSH host characters.' }
+    if ($AdbForwardPort -eq $VideoPort) { throw 'AdbForwardPort and VideoPort must differ.' }
+
+    $ssh = (Get-Command ssh.exe -CommandType Application -ErrorAction Stop | Select-Object -First 1).Source
+    $destination = "$CentralUser@$CentralHost"
+
+    if ($Action -ne 'control') {
+        $remoteArgs = @('-T', '-p', [string]$SshPort, $destination, "pixelctl.cmd $Action")
+        $remote = Start-Process -FilePath $ssh -ArgumentList $remoteArgs -NoNewWindow -PassThru -Wait
+        exit $remote.ExitCode
+    }
+
+    if ($Display -eq 'asml') {
+        if ($env:COMPUTERNAME -ine 'ASML' -or -not [Environment]::UserInteractive) {
+            throw 'ASML screen mode needs an interactive desktop login on ASML. Use "control local pixel8" here, or open an ASML desktop through Remote Desktop.'
+        }
+        $pixelctl = Join-Path $env:USERPROFILE 'pixelctl.cmd'
+        if (-not (Test-Path -LiteralPath $pixelctl -PathType Leaf)) {
+            throw "pixelctl.cmd was not found in $env:USERPROFILE."
+        }
+        & $pixelctl view
+        exit $LASTEXITCODE
+    }
+
+    $scrcpy = Resolve-Program -Name 'scrcpy.exe' -ExplicitPath $ScrcpyPath
+    $adb = Resolve-Program -Name 'adb.exe' -ExplicitPath $AdbPath -SiblingPath (Join-Path (Split-Path -Parent $scrcpy) 'adb.exe')
+    Test-PortFree -Port $AdbForwardPort
+    Test-PortFree -Port $VideoPort
+
+    $previousAdbSocket = $env:ADB_SERVER_SOCKET
+    $previousAdb = $env:ADB
+    $sshProcess = $null
+    try {
+        $sshArgs = @(
+            '-T', '-o', 'ExitOnForwardFailure=yes', '-o', 'ServerAliveInterval=15',
+            '-o', 'ServerAliveCountMax=3', '-p', [string]$SshPort,
+            '-L', "127.0.0.1:${AdbForwardPort}:127.0.0.1:5039",
+            '-L', "127.0.0.1:${VideoPort}:127.0.0.1:${VideoPort}",
+            $destination, 'pixelctl.cmd serve'
+        )
+        Write-Host "Opening SSH to $destination. Complete any host key or password prompt in this window."
+        $sshProcess = Start-Process -FilePath $ssh -ArgumentList $sshArgs -NoNewWindow -PassThru
+
+        $tunnelReady = $false
+        for ($attempt = 0; $attempt -lt 600; $attempt++) {
+            if ($sshProcess.HasExited) { throw "SSH exited with code $($sshProcess.ExitCode). Check the address, login, host key, and password." }
+            if (Test-PortOpen -Port $AdbForwardPort) { $tunnelReady = $true; break }
+            Start-Sleep -Milliseconds 200
+        }
+        if (-not $tunnelReady) { throw 'SSH forwarding did not open within two minutes.' }
+
+        $env:ADB_SERVER_SOCKET = "tcp:127.0.0.1:$AdbForwardPort"
+        $env:ADB = $adb
+        $serial = '127.0.0.1:15555'
+        $deviceReady = $false
+        $lastMessage = ''
+        for ($attempt = 0; $attempt -lt 60; $attempt++) {
+            if ($sshProcess.HasExited) { throw "SSH ended while waiting for the Pixel (exit $($sshProcess.ExitCode))." }
+            $connect = Invoke-Adb -Program $adb -Arguments @('connect', $serial)
+            $lastMessage = ($connect.Output -join ' ')
+            if ($connect.ExitCode -eq 0) {
+                $devices = Invoke-Adb -Program $adb -Arguments @('devices', '-l')
+                if ($devices.ExitCode -eq 0 -and (($devices.Output -join "`n") -match '(?m)^127\.0\.0\.1:15555\s+device\b')) {
+                    $deviceReady = $true
+                    break
+                }
+                $lastMessage = ($devices.Output -join ' ')
+            }
+            Start-Sleep -Seconds 1
+        }
+        if (-not $deviceReady) {
+            throw "The Pixel did not become available through ASML. Ask the holder to run 'pixelremotecontrol startservice pixel8 asml' in Termux. $lastMessage"
+        }
+
+        Write-Host 'Pixel connected. Opening screen control; close the scrcpy window to end this session.'
+        $scrcpyArgs = @('--force-adb-forward', "--port=$VideoPort", '--serial', $serial)
+        if ($TimeLimitSeconds -gt 0) { $scrcpyArgs += "--time-limit=$TimeLimitSeconds" }
+        $oldPreference = $ErrorActionPreference
+        $ErrorActionPreference = 'Continue'
+        try {
+            & $scrcpy @scrcpyArgs
+            $scrcpyExit = $LASTEXITCODE
+        } finally { $ErrorActionPreference = $oldPreference }
+        if ($scrcpyExit -ne 0) { throw "scrcpy exited with code $scrcpyExit." }
+    } finally {
+        $env:ADB_SERVER_SOCKET = $previousAdbSocket
+        $env:ADB = $previousAdb
+        if ($sshProcess -and -not $sshProcess.HasExited) {
+            Stop-Process -Id $sshProcess.Id -Force -ErrorAction SilentlyContinue
+        }
+    }
+} catch {
+    [Console]::Error.WriteLine("pixelremotecontrol: $($_.Exception.Message)")
+    exit 1
+}

package/bin/pixelremotecontrol.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const readline = require('node:readline/promises');
+const { version } = require('../package.json');
+
+const packageRoot = path.resolve(__dirname, '..');
+const assets = path.join(packageRoot, 'assets');
+const actions = new Set(['control', 'wake', 'lock', 'restart', 'status']);
+
+function isTermux() {
+  return process.platform === 'android' ||
+    (process.env.PREFIX || '').startsWith('/data/data/com.termux/files/usr');
+}
+
+function usage() {
+  process.stdout.write(
+    'Usage:\n' +
+    '  pixelremotecontrol setup [--host RELAY_HOST --user SSH_USER]\n' +
+    '  pixelremotecontrol startservice pixel8 asml [CONNECT_PORT]   (Termux on Pixel)\n' +
+    '  pixelremotecontrol control local pixel8 [options]         (Windows viewer)\n' +
+    '  pixelremotecontrol control asml pixel8                     (ASML desktop)\n' +
+    '  pixelremotecontrol <wake|lock|restart|status> local pixel8\n' +
+    '\nRun setup once on each Windows viewer to save its relay address.\n'
+  );
+}
+
+function viewerConfigPath() {
+  const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+  return path.join(localAppData, 'PixelRemoteControl', 'config.json');
+}
+
+function validHost(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9.:-]*$/.test(value);
+}
+
+function validUser(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_][A-Za-z0-9._-]*$/.test(value);
+}
+
+function readViewerConfig() {
+  const file = viewerConfigPath();
+  if (!fs.existsSync(file)) return null;
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Error(`Cannot read ${file}: ${error.message}`);
+  }
+  if (!validHost(config.host) || !validUser(config.user)) {
+    throw new Error(`Invalid relay address or SSH username in ${file}. Run setup again.`);
+  }
+  return config;
+}
+
+function saveViewerConfig(config) {
+  if (!validHost(config.host) || !validUser(config.user)) {
+    throw new Error('Relay host or SSH username contains invalid characters.');
+  }
+  const file = viewerConfigPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  process.stdout.write(`Saved relay settings to ${file}\n`);
+}
+
+function setupOptions(args) {
+  const result = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const option = args[index];
+    const value = args[index + 1];
+    if (!value || !['--host', '--user'].includes(option)) {
+      throw new Error('Usage: pixelremotecontrol setup --host RELAY_HOST --user SSH_USER');
+    }
+    result[option === '--host' ? 'host' : 'user'] = value;
+  }
+  return result;
+}
+
+async function setupViewerConfig(args) {
+  const options = setupOptions(args);
+  const existing = readViewerConfig();
+  const config = { ...existing, ...options };
+  if ((!config.host || !config.user) && !process.stdin.isTTY) {
+    throw new Error('Run setup --host RELAY_HOST --user SSH_USER in an interactive terminal.');
+  }
+  if (!config.host || !config.user) {
+    const interface_ = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      if (!config.host) config.host = (await interface_.question('Relay Tailscale host or IP: ')).trim();
+      if (!config.user) config.user = (await interface_.question('Relay SSH username: ')).trim();
+    } finally {
+      interface_.close();
+    }
+  }
+  saveViewerConfig(config);
+}
+
+function hasCoreOption(args, name) {
+  return args.some((value) => value.toLowerCase() === name.toLowerCase());
+}
+
+function coreOptionValue(args, name) {
+  let result = null;
+  for (let index = 0; index < args.length; index++) {
+    if (args[index].toLowerCase() !== name.toLowerCase()) continue;
+    if (result !== null) throw new Error(`Specify ${name} only once.`);
+    result = args[index + 1];
+  }
+  return result;
+}
+
+function viewerRelayArgs(args) {
+  const explicitHost = coreOptionValue(args, '-CentralHost');
+  const explicitUser = coreOptionValue(args, '-CentralUser');
+  if (explicitHost !== null && !validHost(explicitHost)) {
+    throw new Error('Invalid -CentralHost value.');
+  }
+  if (explicitUser !== null && !validUser(explicitUser)) {
+    throw new Error('Invalid -CentralUser value.');
+  }
+  if (explicitHost && explicitUser) return [];
+  const config = readViewerConfig();
+  if (!config) {
+    throw new Error('Viewer relay is not configured. Run pixelremotecontrol setup --host RELAY_HOST --user SSH_USER.');
+  }
+  const result = [];
+  if (!hasCoreOption(args, '-CentralHost')) result.push('-CentralHost', config.host);
+  if (!hasCoreOption(args, '-CentralUser')) result.push('-CentralUser', config.user);
+  return result;
+}
+
+function run(program, args, options = {}) {
+  const result = spawnSync(program, args, {
+    stdio: 'inherit',
+    windowsHide: false,
+    ...options,
+  });
+  if (result.error) throw result.error;
+  return result.status === null ? 1 : result.status;
+}
+
+function commandExists(name) {
+  const result = spawnSync(name, ['--version'], { stdio: 'ignore' });
+  return !result.error || result.error.code !== 'ENOENT';
+}
+
+function ensureTermuxPackages() {
+  const missing = [];
+  if (!commandExists('ssh')) missing.push('openssh');
+  if (!commandExists('timeout')) missing.push('coreutils');
+  if (!commandExists('pgrep')) missing.push('procps');
+  if (missing.length === 0) return;
+  if (!commandExists('pkg')) {
+    throw new Error(`Install Termux packages: pkg install ${missing.join(' ')}`);
+  }
+  process.stdout.write(`Installing Termux packages: ${missing.join(', ')}\n`);
+  const code = run('pkg', ['install', '-y', ...missing]);
+  if (code !== 0) throw new Error(`Termux package installation exited with code ${code}`);
+}
+
+function ensureTermuxRuntime() {
+  const bin = path.join(os.homedir(), '.config', 'pixelremotecontrol', 'bin');
+  const source = path.join(assets, 'phone', 'pixel-connect');
+  const target = path.join(bin, 'pixel-connect');
+  fs.mkdirSync(bin, { recursive: true, mode: 0o700 });
+  // Keep the packaged helper available even when npm's global package directory
+  // is not executable from Termux's shell PATH.
+  fs.copyFileSync(source, target);
+  fs.chmodSync(target, 0o700);
+  return bin;
+}
+
+function ensureTermuxSetup() {
+  ensureTermuxPackages();
+  const runtimeBin = ensureTermuxRuntime();
+  const config = process.env.PIXEL_CONNECT_CONFIG ||
+    path.join(os.homedir(), '.config', 'pixel-connect', 'config');
+  const key = path.join(os.homedir(), '.ssh', 'central_tunnel');
+  if (!fs.existsSync(config) || !fs.existsSync(key)) {
+    throw new Error(
+      `The Pixel relay needs its configuration and SSH key: ${config}, ${key}. ` +
+      'Provision the central relay and pair ADB before starting the service.'
+    );
+  }
+  return runtimeBin;
+}
+
+async function ensureViewerTools() {
+  // The dependency module downloads and verifies the official Windows scrcpy
+  // bundle when a suitable local copy is not already present.
+  const { ensureWindowsScrcpy } = require('../lib/dependencies.js');
+  return ensureWindowsScrcpy();
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  if (!action || ['help', '--help', '-h', '/?'].includes(action)) {
+    usage();
+    return action ? 0 : 2;
+  }
+  if (action === '--version' || action === '-v') {
+    process.stdout.write(`${version}\n`);
+    return 0;
+  }
+
+  if (action === 'setup') {
+    if (isTermux()) {
+      ensureTermuxSetup();
+      process.stdout.write('Termux command dependencies are ready.\n');
+      return 0;
+    }
+    if (process.platform === 'win32') {
+      await setupViewerConfig(args.slice(1));
+      if (!commandExists('ssh.exe')) {
+        throw new Error('Windows OpenSSH Client is required. Enable it in Windows Optional Features.');
+      }
+      const tools = await ensureViewerTools();
+      process.stdout.write(`Viewer tools ready: ${tools.scrcpyPath}\n`);
+      return 0;
+    }
+    throw new Error('This package currently supports Windows viewers and Termux on Android.');
+  }
+
+  if (action === 'startservice') {
+    if (!isTermux()) throw new Error('Run startservice in Termux on the Pixel.');
+    const runtimeBin = ensureTermuxSetup();
+    const script = path.join(assets, 'phone', 'pixelremotecontrol');
+    const env = { ...process.env, PATH: `${runtimeBin}:${process.env.PATH || ''}` };
+    return run('bash', [script, ...args], { env });
+  }
+
+  if (actions.has(action)) {
+    if (process.platform !== 'win32') {
+      throw new Error('Run screen control on a Windows viewer or ASML desktop.');
+    }
+    const script = path.join(assets, 'viewer', 'pixelremotecontrol-core.ps1');
+    const powershellArgs = [
+      '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, ...args,
+      ...viewerRelayArgs(args),
+    ];
+    if (action === 'control' && (args[1] || 'local') !== 'asml' &&
+        !args.some((arg) => /^-ScrcpyPath$/i.test(arg))) {
+      const tools = await ensureViewerTools();
+      powershellArgs.push('-ScrcpyPath', tools.scrcpyPath, '-AdbPath', tools.adbPath);
+    }
+    return run('powershell.exe', powershellArgs);
+  }
+
+  throw new Error(`Unknown action '${action}'. Run pixelremotecontrol --help.`);
+}
+
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  process.stderr.write(`pixelremotecontrol: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/lib/dependencies.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const fs = require('node:fs');
+const fsp = fs.promises;
+const path = require('node:path');
+const os = require('node:os');
+const https = require('node:https');
+const crypto = require('node:crypto');
+const { Transform } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+const { spawnSync } = require('node:child_process');
+
+const VERSION = '5.0.1';
+const ARCHIVES = {
+  x64: {
+    name: `scrcpy-win64-v${VERSION}`,
+    sha256: 'b12a2c4ee8be317422451fc7dcf8ee20a71b5ea7ef9ad73ddd825a25316227a5',
+  },
+  ia32: {
+    name: `scrcpy-win32-v${VERSION}`,
+    sha256: '0cb65ebf1bce892fa4d1502d699af0c7a1a7f24d7febcb9ef72894e3f23fc2ad',
+  },
+  arm64: {
+    name: `scrcpy-winarm64-v${VERSION}`,
+    sha256: '16c3fc2068df64946f670e3504b4752073ebae47a416a45b46e79a5ab19c689b',
+  },
+};
+const MAX_DOWNLOAD_BYTES = 250 * 1024 * 1024;
+
+function cacheRoot() {
+  if (process.env.PIXELREMOTECONTROL_CACHE_DIR) {
+    return path.resolve(process.env.PIXELREMOTECONTROL_CACHE_DIR);
+  }
+  const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+  return path.join(localAppData, 'PixelRemoteControl', 'tools');
+}
+
+function containedChild(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to modify a path outside the PixelRemoteControl cache: ${target}`);
+  }
+  return target;
+}
+
+async function existingBundle(dir) {
+  const scrcpyPath = path.join(dir, 'scrcpy.exe');
+  const adbPath = path.join(dir, 'adb.exe');
+  try {
+    const [scrcpy, adb] = await Promise.all([fsp.stat(scrcpyPath), fsp.stat(adbPath)]);
+    if (scrcpy.isFile() && adb.isFile()) return { scrcpyPath, adbPath };
+  } catch (_) {
+    // An incomplete cache entry is not a usable installation.
+  }
+  return null;
+}
+
+function findOnPath(name) {
+  const directories = (process.env.PATH || '').split(path.delimiter);
+  for (const directory of directories) {
+    if (!directory) continue;
+    const file = path.join(directory, name);
+    try {
+      if (fs.statSync(file).isFile()) return file;
+    } catch (_) {
+      // Keep searching.
+    }
+  }
+  return null;
+}
+
+function openRelease(url, redirects = 0) {
+  if (redirects > 6) return Promise.reject(new Error('Too many redirects downloading scrcpy.'));
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:') return Promise.reject(new Error('scrcpy download must use HTTPS.'));
+  return new Promise((resolve, reject) => {
+    const request = https.get(parsed, {
+      headers: { 'User-Agent': 'pixelremotecontrol/npm', Accept: 'application/octet-stream' },
+      timeout: 30000,
+    }, response => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        const location = response.headers.location;
+        response.resume();
+        if (!location) return reject(new Error('scrcpy download redirected without a location.'));
+        return resolve(openRelease(new URL(location, parsed).toString(), redirects + 1));
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        return reject(new Error(`scrcpy download returned HTTP ${response.statusCode}.`));
+      }
+      resolve(response);
+    });
+    request.on('timeout', () => request.destroy(new Error('scrcpy download timed out.')));
+    request.on('error', reject);
+  });
+}
+
+async function downloadVerified(url, destination, expectedSha256) {
+  const response = await openRelease(url);
+  const digest = crypto.createHash('sha256');
+  let bytes = 0;
+  const inspector = new Transform({
+    transform(chunk, _encoding, callback) {
+      bytes += chunk.length;
+      if (bytes > MAX_DOWNLOAD_BYTES) {
+        callback(new Error('scrcpy download exceeded the size limit.'));
+      } else {
+        digest.update(chunk);
+        callback(null, chunk);
+      }
+    },
+  });
+  await pipeline(response, inspector, fs.createWriteStream(destination, { flags: 'wx' }));
+  const actual = digest.digest('hex');
+  if (actual !== expectedSha256) {
+    throw new Error(`scrcpy archive SHA256 mismatch (received ${actual}).`);
+  }
+}
+
+async function ensureWindowsScrcpy() {
+  if (process.platform !== 'win32') throw new Error('The Windows scrcpy bundle is only available on Windows.');
+  const archive = ARCHIVES[process.arch];
+  if (!archive) throw new Error(`Automatic scrcpy installation does not yet support Windows ${process.arch}.`);
+
+  if (process.env.PIXELREMOTECONTROL_FORCE_DOWNLOAD !== '1') {
+    const explicit = process.env.PIXELREMOTECONTROL_SCRCPY;
+    if (explicit) {
+      const bundle = await existingBundle(path.dirname(path.resolve(explicit)));
+      if (bundle && path.resolve(bundle.scrcpyPath).toLowerCase() === path.resolve(explicit).toLowerCase()) return bundle;
+      throw new Error('PIXELREMOTECONTROL_SCRCPY must point to scrcpy.exe beside adb.exe.');
+    }
+    const onPath = findOnPath('scrcpy.exe');
+    if (onPath) {
+      const bundle = await existingBundle(path.dirname(onPath));
+      if (bundle) return bundle;
+    }
+  }
+
+  const root = cacheRoot();
+  const finalDir = containedChild(root, path.join(root, archive.name));
+  const cached = await existingBundle(finalDir);
+  if (cached) return cached;
+
+  await fsp.mkdir(root, { recursive: true });
+  const stage = containedChild(root, await fsp.mkdtemp(path.join(root, '.scrcpy-download-')));
+  try {
+    const zipPath = containedChild(stage, path.join(stage, `${archive.name}.zip`));
+    const extractDir = containedChild(stage, path.join(stage, 'extracted'));
+    await fsp.mkdir(extractDir);
+    const url = `https://github.com/Genymobile/scrcpy/releases/download/v${VERSION}/${archive.name}.zip`;
+    process.stderr.write(`Downloading scrcpy ${VERSION} from the official release...\n`);
+    await downloadVerified(url, zipPath, archive.sha256);
+    const tar = spawnSync('tar.exe', ['-xf', zipPath, '-C', extractDir], { stdio: 'pipe', encoding: 'utf8' });
+    if (tar.error || tar.status !== 0) {
+      throw new Error(`Could not extract scrcpy: ${tar.error?.message || tar.stderr?.trim() || `tar exited ${tar.status}`}`);
+    }
+    const extractedBundle = containedChild(extractDir, path.join(extractDir, archive.name));
+    const bundle = await existingBundle(extractedBundle);
+    if (!bundle) throw new Error('The verified scrcpy archive did not contain scrcpy.exe and adb.exe.');
+    try {
+      await fsp.rename(extractedBundle, finalDir);
+    } catch (error) {
+      // A concurrent install may have populated the cache while this one downloaded.
+      const winner = await existingBundle(finalDir);
+      if (winner) return winner;
+      throw error;
+    }
+    process.stderr.write(`Installed scrcpy at ${finalDir}\n`);
+    return { scrcpyPath: path.join(finalDir, 'scrcpy.exe'), adbPath: path.join(finalDir, 'adb.exe') };
+  } finally {
+    containedChild(root, stage);
+    await fsp.rm(stage, { recursive: true, force: true });
+  }
+}
+
+module.exports = { ensureWindowsScrcpy };

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "pixelremotecontrol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Control a paired Pixel through a private ASML SSH relay",
+  "license": "UNLICENSED",
+  "private": false,
+  "contentPolicy": {
+    "class": "dual-use"
+  },
+  "bin": {
+    "pixelremotecontrol": "bin/pixelremotecontrol.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "assets/",
+    "scripts/postinstall.js",
+    "DISCLOSURE",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node scripts/build-assets.js",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// npm writes both .cmd and .ps1 launchers for a Windows bin entry. A bare
+// command in PowerShell resolves the .ps1 first, which is blocked on systems
+// with Restricted execution policy. Keep npm's .cmd and remove only this
+// package's generated .ps1 shim after a global install.
+if (process.platform !== 'win32' || process.env.npm_config_global !== 'true') {
+  process.exit(0);
+}
+
+const fs = require('node:fs');
+const path = require('node:path');
+const packageRoot = path.resolve(__dirname, '..');
+if (path.basename(packageRoot).toLowerCase() !== 'pixelremotecontrol' ||
+    path.basename(path.dirname(packageRoot)).toLowerCase() !== 'node_modules') {
+  process.exit(0);
+}
+
+const prefix = path.resolve(packageRoot, '..', '..');
+const shim = path.join(prefix, 'pixelremotecontrol.ps1');
+if (!fs.existsSync(shim)) process.exit(0);
+
+const content = fs.readFileSync(shim, 'utf8');
+if (!content.toLowerCase().includes('node_modules/pixelremotecontrol/') &&
+    !content.toLowerCase().includes('node_modules\\pixelremotecontrol\\')) {
+  process.stderr.write(`Leaving unexpected PowerShell file untouched: ${shim}\n`);
+  process.exit(0);
+}
+
+fs.unlinkSync(shim);
+process.stdout.write('Removed npm PowerShell shim; pixelremotecontrol uses its .cmd launcher.\n');