feat(launcher): install the server from a prebuilt archive (P1.3c)

The launcher is now a self-contained installer with install, run, update,
doctor and uninstall. Install downloads waggle-server-<version>-<target>
.tar.gz, checks its SHA-256, unpacks it into a per-user program directory
and writes a waggle-server command that runs the tool on the archive's own
Node. Nothing is built on the user's machine and the data directory stays
WAGGLE_DATA_DIR or ~/.waggle.

scripts/build-server-archive.mjs packs the staged desktop sidecar payload
with the built web UI and a manifest. The download location waits for the
repository decision; until then install takes --from or
WAGGLE_RELEASE_BASE_URL (ADR-0009).

Removes install.sh, scripts/waggle-server.sh and their CI job, which the
installer replaces, and the bin name clash with @waggle/cli.
This commit is contained in:
shumeiko.it
2026-11-01 01:35:54 +01:00
parent eb2412b687
commit 3a426a5423
22 changed files with 1455 additions and 2206 deletions

View File

@@ -67,7 +67,6 @@ jobs:
npm test --
--exclude=packages/cli/tests/cli-runtime.test.ts
--exclude=packages/marketplace/tests/cli-runtime.test.ts
--exclude=packages/launcher/tests/cli.test.ts
--maxWorkers=2
# These tests each create a temporary project and run npm install. Running
@@ -78,7 +77,6 @@ jobs:
npx vitest run
packages/cli/tests/cli-runtime.test.ts
packages/marketplace/tests/cli-runtime.test.ts
packages/launcher/tests/cli.test.ts
--maxWorkers=1
--no-file-parallelism

View File

@@ -1,115 +0,0 @@
name: Installer Smoke
# Authoritative Linux proof for the one-line self-host installer (steal #5).
# The installer is developed on Windows, where the esbuild-hoist trap and CRLF
# quirks are Windows-only — so a green `bash -n` locally is NOT proof it works
# for the VPS/homelab audience. This job runs install.sh end-to-end from a
# clean ubuntu runner: it actually installs, builds packages, boots the sidecar,
# and asserts /health returns 200, then tears it down and asserts the port frees.
on:
pull_request:
paths:
- install.sh
- scripts/waggle-server.sh
- .github/workflows/installer-smoke.yml
push:
paths:
- install.sh
- scripts/waggle-server.sh
- .github/workflows/installer-smoke.yml
workflow_dispatch:
jobs:
installer-smoke:
runs-on: ubuntu-latest
timeout-minutes: 30
env:
WAGGLE_PORT: "3947"
steps:
- uses: actions/checkout@v4
# The `runner` context is not available in job-level env, so the scratch
# paths (isolated from the checkout to exercise the real "copy + fresh
# install" path) are computed here from $RUNNER_TEMP instead.
- name: Compute scratch paths
run: |
echo "WAGGLE_INSTALL_DIR=$RUNNER_TEMP/waggle" >> "$GITHUB_ENV"
echo "WAGGLE_DATA_DIR=$RUNNER_TEMP/wdata" >> "$GITHUB_ENV"
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
# shellcheck ships pre-installed on ubuntu-latest runners. Findings are
# failures — the installer is user-facing shell that runs unsupervised via
# `curl | bash`, so lint cleanliness is a correctness gate, not a nicety.
- name: shellcheck installer scripts
run: shellcheck install.sh scripts/waggle-server.sh
# The real E2E. --local-source copies THIS checkout (tracked + untracked,
# excluding node_modules/dist) into a scratch dir, then does a from-scratch
# npm install + build:packages there. --no-web keeps it to API/echo mode
# (no vite build); --no-start hands the boot to waggle-server.sh below so we
# test the process manager too.
- name: Install (install.sh --yes, from-scratch)
run: |
./install.sh \
--yes \
--no-web \
--no-start \
--local-source "$GITHUB_WORKSPACE" \
--dir "$WAGGLE_INSTALL_DIR" \
--data-dir "$WAGGLE_DATA_DIR" \
--port "$WAGGLE_PORT"
- name: Start the sidecar (waggle-server.sh start)
run: |
bash "$WAGGLE_INSTALL_DIR/scripts/waggle-server.sh" start \
--port "$WAGGLE_PORT" \
--data-dir "$WAGGLE_DATA_DIR"
# Defensive re-poll. waggle-server.sh already blocks until /health is 200
# (up to 60s; the sidecar spends ~9s on marketplace sync before listening),
# so this normally passes on the first attempt. The wider 90s budget guards
# against a slow cold runner without making the assertion flaky.
- name: Wait for /health (HTTP 200)
run: |
url="http://127.0.0.1:${WAGGLE_PORT}/health"
for i in $(seq 1 90); do
code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 "$url" || echo 000)"
if [ "$code" = "200" ]; then
echo "healthy after ${i}s (HTTP 200)"
exit 0
fi
sleep 1
done
echo "::error::/health did not return 200 within 90s"
echo "--- last sidecar log lines ---"
tail -n 40 "$WAGGLE_DATA_DIR/server.log" 2>/dev/null || true
exit 1
- name: Status
run: |
bash "$WAGGLE_INSTALL_DIR/scripts/waggle-server.sh" status \
--port "$WAGGLE_PORT" \
--data-dir "$WAGGLE_DATA_DIR"
- name: Stop
run: |
bash "$WAGGLE_INSTALL_DIR/scripts/waggle-server.sh" stop \
--port "$WAGGLE_PORT" \
--data-dir "$WAGGLE_DATA_DIR"
- name: Assert port is free after stop
run: |
url="http://127.0.0.1:${WAGGLE_PORT}/health"
if curl -fsS -o /dev/null --max-time 3 "$url"; then
echo "::error::/health still responding on port ${WAGGLE_PORT} after stop"
exit 1
fi
echo "port ${WAGGLE_PORT} is free"
- name: Dump sidecar log on failure
if: failure()
run: tail -n 100 "$WAGGLE_DATA_DIR/server.log" 2>/dev/null || echo "(no log file)"

3
.gitignore vendored
View File

@@ -129,3 +129,6 @@ bun.lock
# Local plaintext API keys — never commit
AI API KEYS.txt
# Server archives built by scripts/build-server-archive.mjs
artifacts/

View File

@@ -64,8 +64,8 @@ describe('auto-update configuration', () => {
describe('Cargo.toml dependencies', () => {
const cargo = readFileSync(resolve(ROOT, 'src-tauri/Cargo.toml'), 'utf-8');
it('includes tauri-plugin-updater dependency', () => {
expect(cargo).toContain('tauri-plugin-updater');
it('does not depend on tauri-plugin-updater while updater config is disabled', () => {
expect(cargo).not.toContain('tauri-plugin-updater');
});
});

View File

@@ -0,0 +1,49 @@
# ADR-0009: The installer delivers a prebuilt server archive
- Status: Accepted
- Date: 2026-11-01
## Context
The scope requires a Node-based install tool without Docker or Python (fixed decision 4), built
on `packages/launcher` (P1.3c). Two install paths existed:
- `npx @waggle-ai/waggle` started the server from npm. npm installed the server dependencies on
the user's Node, so native modules could fall back to node-gyp, and the CUDA and Puppeteer
download skips could not be set (ADR-0005, ADR-0008). The tool did not serve the web UI.
- `install.sh` cloned the repository and built it on the user's machine. It needed git, npm and,
for some prebuild mismatches, a compiler. It ran on Linux and macOS only.
The desktop build already stages a complete sidecar payload: `service.js`, the pinned Node, the
native modules and the production `node_modules` (ADR-0008).
## Decision
1. **The release publishes one server archive per target**: `windows-x64`, `macos-arm64`,
`macos-x64` and `linux-x64`. `scripts/build-server-archive.mjs` packs the staged desktop
payload, the built web UI under `web/` and a `manifest.json` into
`waggle-server-<version>-<target>.tar.gz`, with a `.sha256` next to it.
2. **The installer downloads and unpacks it.** `packages/launcher` is now a self-contained tool
(`waggle-server`) that uses only Node's built-in modules:
- `install` downloads the archive for this system, checks its SHA-256 and unpacks it into a
per-user program directory, then writes a `waggle-server` command;
- `run` (the default) starts the server on the archive's own Node and opens the browser;
- `doctor` checks the runtime, SQLite, the data directory, the port and the command;
- `update` swaps in another version; `uninstall` removes the program and keeps the data.
3. **Nothing is built on the user's machine.** The archive carries its own Node, so the user's
Node (20 or newer) is needed only for the first `npx` call.
4. **The data directory does not change**: `WAGGLE_DATA_DIR` or `~/.waggle`, as for the sidecar.
5. **The download location waits for the repository decision (Q9).** Until then `install` takes
`--from <path or URL>`, and `WAGGLE_RELEASE_BASE_URL` points it at a mirror.
The project owner chose this over publishing the server to npm on 2026-11-01.
## Consequences
- The installed server runs exactly the payload the desktop app ships and the release smoke
tests.
- An archive is about 130 MB (macOS arm64); it is downloaded once per version.
- `install.sh`, `scripts/waggle-server.sh` and their CI job are removed.
- The release workflow must build the archive on each target system (P1.3d).
- Windows cannot replace a running program: `update` and `uninstall` there run through `npx`,
and the server must be stopped first.

View File

@@ -14,6 +14,7 @@ decision, add a new record that supersedes the old one.
| [0006](0006-opt-in-analytics.md) | Analytics are opt-in | Accepted, one open item |
| [0007](0007-memory-contract.md) | The memory contract and how it maps onto mem0 | Accepted |
| [0008](0008-native-modules.md) | Native modules ship with a pinned Node runtime | Accepted |
| [0009](0009-installer-server-archive.md) | The installer delivers a prebuilt server archive | Accepted |
## Pending decisions

View File

@@ -1,383 +0,0 @@
#!/usr/bin/env bash
#
# install.sh — one-line self-host installer for Waggle OS (Linux + macOS).
#
# curl -fsSL https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash
#
# WHY THIS EXISTS (steal #5, installer arc 2026-07-10):
# Waggle had a Tauri desktop binary, a heavy Docker team stack, and a
# "clone + two dev terminals" README — but no one-command headless self-host
# story for the VPS/homelab audience the OSS funnel targets. This installer
# fills that gap: prereqs -> clone -> build -> tiny wizard -> start -> URL.
#
# WHAT IT DOES NOT DO (by design, D2/D3):
# No sudo, ever. No API keys, personas, or channel setup — the web UI's
# OnboardingWizard owns all of that. Missing prerequisites print the exact
# per-OS install command and exit; we never install system packages for you.
#
# FLAGS:
# --yes non-interactive; accept every wizard default
# --dir PATH install directory (default: ~/waggle-os)
# --port N sidecar port (default: 3333)
# --data-dir PATH data directory (default: ~/.waggle)
# --no-web skip building the web UI (API/echo mode only)
# --no-start install but do not start the server
# --branch NAME git branch to clone (default: main)
# --local-source PATH copy an existing checkout instead of git-cloning
# (for CI and local testing; includes uncommitted files)
#
# Idempotent: re-running against an installed directory prints an upgrade hint
# and exits without re-cloning or rebuilding.
set -euo pipefail
# ── Constants ─────────────────────────────────────────────────────────────────
REPO_URL="https://github.com/marolinik/waggle-os.git"
MIN_NODE_MAJOR=20
DEFAULT_PORT=3333
MARKER_NAME=".waggle-installed"
# ── Wizard defaults ───────────────────────────────────────────────────────────
INSTALL_DIR="$HOME/waggle-os"
PORT="$DEFAULT_PORT"
DATA_DIR="$HOME/.waggle"
BUILD_WEB=1
START_NOW=1
BRANCH="main"
ASSUME_YES=0
LOCAL_SOURCE=""
# ── Pretty output (disabled when not a TTY) ───────────────────────────────────
if [ -t 1 ]; then
C_BOLD="$(printf '\033[1m')"; C_DIM="$(printf '\033[2m')"
C_GREEN="$(printf '\033[32m')"; C_YELLOW="$(printf '\033[33m')"
C_RED="$(printf '\033[31m')"; C_RESET="$(printf '\033[0m')"
else
C_BOLD=""; C_DIM=""; C_GREEN=""; C_YELLOW=""; C_RED=""; C_RESET=""
fi
say() { echo "${C_BOLD}==>${C_RESET} $*"; }
info() { echo " $*"; }
warn() { echo "${C_YELLOW}warning:${C_RESET} $*" >&2; }
die() { echo "${C_RED}error:${C_RESET} $*" >&2; exit 1; }
# True when $1 is a decimal integer within the valid TCP port range (1-65535).
valid_port() {
case "$1" in
''|*[!0-9]*) return 1 ;;
esac
[ "$1" -ge 1 ] && [ "$1" -le 65535 ]
}
on_interrupt() {
# Restore sane terminal state if a wizard read was interrupted, then abort.
if [ -e /dev/tty ]; then stty sane </dev/tty >/dev/null 2>&1 || true; fi
echo
die "Aborted by user."
}
trap on_interrupt INT
# ── Arg parsing ───────────────────────────────────────────────────────────────
while [ $# -gt 0 ]; do
case "$1" in
--yes|-y) ASSUME_YES=1; shift ;;
--dir) INSTALL_DIR="${2:?--dir needs a value}"; shift 2 ;;
--dir=*) INSTALL_DIR="${1#*=}"; shift ;;
--port) PORT="${2:?--port needs a value}"; shift 2 ;;
--port=*) PORT="${1#*=}"; shift ;;
--data-dir) DATA_DIR="${2:?--data-dir needs a value}"; shift 2 ;;
--data-dir=*) DATA_DIR="${1#*=}"; shift ;;
--no-web) BUILD_WEB=0; shift ;;
--no-start) START_NOW=0; shift ;;
--branch) BRANCH="${2:?--branch needs a value}"; shift 2 ;;
--branch=*) BRANCH="${1#*=}"; shift ;;
--local-source) LOCAL_SOURCE="${2:?--local-source needs a value}"; shift 2 ;;
--local-source=*) LOCAL_SOURCE="${1#*=}"; shift ;;
-h|--help)
sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'
exit 0 ;;
*) die "Unknown option: $1 (try --help)" ;;
esac
done
valid_port "$PORT" || die "Invalid --port '${PORT}': must be an integer between 1 and 65535."
# ── OS detection (for install hints; not a hard gate) ─────────────────────────
UNAME_S="$(uname -s 2>/dev/null || echo unknown)"
case "$UNAME_S" in
Linux) OS="linux" ;;
Darwin) OS="macos" ;;
*) OS="other" ;;
esac
# Per-OS install command hint for a missing tool.
install_hint() {
local tool="$1"
case "$OS" in
linux) echo "sudo apt install ${tool} # or: sudo dnf install ${tool}" ;;
macos) echo "brew install ${tool}" ;;
*) echo "install ${tool} using your platform's package manager" ;;
esac
}
# ── Preflight ─────────────────────────────────────────────────────────────────
preflight() {
say "Checking prerequisites"
if [ "${BASH_VERSINFO:-0}" -lt 4 ]; then
warn "bash ${BASH_VERSION} is old; this script targets bash >= 4 but avoids 4-only features. Continuing."
fi
if [ "$OS" = "other" ]; then
warn "Unsupported OS '${UNAME_S}'. Official support is Linux and macOS; proceeding best-effort."
fi
command -v git >/dev/null 2>&1 || die "git is required. Install it:
$(install_hint git)"
if ! command -v node >/dev/null 2>&1; then
die "Node.js >= ${MIN_NODE_MAJOR} is required. Install it:
$(install_hint nodejs)
or use nvm: https://github.com/nvm-sh/nvm"
fi
local node_major
node_major="$(node -v 2>/dev/null | sed -E 's/^v([0-9]+).*/\1/')"
if [ -z "$node_major" ] || [ "$node_major" -lt "$MIN_NODE_MAJOR" ]; then
die "Node.js >= ${MIN_NODE_MAJOR} required, found $(node -v 2>/dev/null || echo none).
Upgrade Node (nvm install ${MIN_NODE_MAJOR}) and re-run."
fi
command -v npm >/dev/null 2>&1 || die "npm is required (ships with Node.js). Re-install Node.js:
$(install_hint nodejs)"
# C++ toolchain: better-sqlite3 falls back to compiling from source when no
# prebuilt binary matches. Warn only — a prebuilt often exists.
if ! command -v cc >/dev/null 2>&1 && ! command -v gcc >/dev/null 2>&1 && ! command -v clang >/dev/null 2>&1; then
warn "No C/C++ compiler found. If native modules (better-sqlite3) fail to install, install build tools:
$( [ "$OS" = macos ] && echo 'xcode-select --install' || echo 'sudo apt install build-essential python3' )"
fi
info "git $(git --version | awk '{print $3}') · node $(node -v) · npm $(npm -v)"
}
# ── Acquire the source tree into INSTALL_DIR ──────────────────────────────────
# git ls-files enumerates tracked + untracked-but-not-ignored files, so a
# --local-source copy includes uncommitted work (this installer, the wrapper
# script) yet excludes node_modules/dist/.git the same way a clone would.
acquire_source() {
if [ -n "$LOCAL_SOURCE" ]; then
[ -d "$LOCAL_SOURCE" ] || die "--local-source path does not exist: ${LOCAL_SOURCE}"
say "Copying source from ${LOCAL_SOURCE}"
mkdir -p "$INSTALL_DIR"
if command -v git >/dev/null 2>&1 && git -C "$LOCAL_SOURCE" rev-parse --show-toplevel >/dev/null 2>&1; then
( cd "$LOCAL_SOURCE" && git ls-files -z --cached --others --exclude-standard ) \
| ( cd "$LOCAL_SOURCE" && tar --null -T - -cf - ) \
| ( cd "$INSTALL_DIR" && tar -xf - )
else
# Non-git source: copy everything except the heavy/regenerated dirs.
tar -C "$LOCAL_SOURCE" --exclude=node_modules --exclude=dist --exclude=.git -cf - . \
| tar -C "$INSTALL_DIR" -xf -
fi
else
say "Cloning ${REPO_URL} (branch ${BRANCH})"
git clone --depth 1 --branch "$BRANCH" "$REPO_URL" "$INSTALL_DIR"
fi
}
# ── Wizard (D4) ───────────────────────────────────────────────────────────────
# Reads from /dev/tty so `curl | bash` (stdin = the pipe) can still prompt. When
# non-interactive (--yes, or no controlling terminal), every answer takes its
# default silently.
ask() {
# ask <var-name> <prompt> <default>
local __var="$1" __prompt="$2" __default="$3" __reply=""
if [ "$ASSUME_YES" -eq 1 ] || [ ! -e /dev/tty ]; then
printf -v "$__var" '%s' "$__default"
return
fi
# Relax errexit around the interactive read (EOF/empty must fall to default).
set +e
read -r -p "$(printf '%s [%s]: ' "$__prompt" "$__default")" __reply </dev/tty
set -e
printf -v "$__var" '%s' "${__reply:-$__default}"
}
ask_yesno() {
# ask_yesno <var-name 0|1> <prompt> <default 0|1>
local __var="$1" __prompt="$2" __default="$3" __reply="" __hint
[ "$__default" -eq 1 ] && __hint="Y/n" || __hint="y/N"
if [ "$ASSUME_YES" -eq 1 ] || [ ! -e /dev/tty ]; then
printf -v "$__var" '%s' "$__default"
return
fi
set +e
read -r -p "$(printf '%s [%s]: ' "$__prompt" "$__hint")" __reply </dev/tty
set -e
case "$(printf '%s' "$__reply" | tr '[:upper:]' '[:lower:]')" in
y|yes) printf -v "$__var" '%s' 1 ;;
n|no) printf -v "$__var" '%s' 0 ;;
*) printf -v "$__var" '%s' "$__default" ;;
esac
}
run_wizard() {
if [ "$ASSUME_YES" -eq 1 ] || [ ! -e /dev/tty ]; then
info "Non-interactive: using defaults (dir=${INSTALL_DIR}, port=${PORT}, data=${DATA_DIR}, web=${BUILD_WEB}, start=${START_NOW})"
return
fi
echo
say "Setup (press Enter to accept each default)"
ask INSTALL_DIR "Install directory" "$INSTALL_DIR"
local __port_default="$PORT"
while :; do
ask PORT "Server port" "$__port_default"
valid_port "$PORT" && break
warn "Port must be an integer between 1 and 65535; try again."
done
ask DATA_DIR "Data directory" "$DATA_DIR"
ask_yesno BUILD_WEB "Build the web UI now" "$BUILD_WEB"
ask_yesno START_NOW "Start the server when done" "$START_NOW"
echo
}
# ── Post-install runtime verification (D10) ───────────────────────────────────
# Confirms the native SQLite module actually loads in the installed tree: opens
# an in-memory better-sqlite3 db, as waggle.db and the memory store do. Turns
# the "does the native module load on this platform?" unknown into a visible,
# actionable check.
verify_runtime() {
say "Verifying native SQLite"
local script
script='
const Database = require("better-sqlite3");
const db = new Database(":memory:");
const row = db.prepare("select sqlite_version() as v").get();
db.close();
console.log("SQLite " + row.v);
'
local errfile
errfile="$(mktemp "${TMPDIR:-/tmp}/waggle-verify.XXXXXX")" \
|| die "Could not create a temporary file for the runtime check (is mktemp available?)."
if ( cd "$INSTALL_DIR" && node -e "$script" ) 2>"$errfile"; then
info "$(cat "$errfile" 2>/dev/null || true) — OK"
rm -f "$errfile" 2>/dev/null || true
return 0
fi
local err; err="$(cat "$errfile" 2>/dev/null || true)"
rm -f "$errfile" 2>/dev/null || true
warn "Native SQLite check failed:
${err}
Remedies:
- Ensure a C/C++ toolchain is installed so better-sqlite3 can build:
$( [ "$OS" = macos ] && echo 'xcode-select --install' || echo 'sudo apt install build-essential python3' )
- Re-run: cd ${INSTALL_DIR} && npm install"
return 1
}
# ── Persist the install marker (D5/D6) ────────────────────────────────────────
# Injection-safe: the port/data-dir/branch answers cross into the file only as
# environment variables consumed by node's JSON.stringify — never interpolated
# into shell or file text.
write_marker() {
local marker="$INSTALL_DIR/$MARKER_NAME"
if [ -f "$marker" ]; then
local backup
backup="${marker}.$(date +%Y%m%d%H%M%S).bak"
cp "$marker" "$backup" 2>/dev/null || true
info "Backed up existing marker to ${backup}"
fi
WAGGLE_M_PORT="$PORT" \
WAGGLE_M_DATADIR="$DATA_DIR" \
WAGGLE_M_BRANCH="$BRANCH" \
node -e '
const fs = require("fs");
const out = {
installedAt: new Date().toISOString(),
port: process.env.WAGGLE_M_PORT,
dataDir: process.env.WAGGLE_M_DATADIR,
branch: process.env.WAGGLE_M_BRANCH,
};
fs.writeFileSync(process.argv[1], JSON.stringify(out, null, 2) + "\n");
' "$marker"
}
# ── Success card ──────────────────────────────────────────────────────────────
success_card() {
local mgr="$INSTALL_DIR/scripts/waggle-server.sh"
echo
echo "${C_GREEN}${C_BOLD} Waggle OS is installed.${C_RESET}"
echo
if [ "$START_NOW" -eq 1 ]; then
echo " ${C_BOLD}Open:${C_RESET} http://127.0.0.1:${PORT}"
else
echo " ${C_BOLD}Start:${C_RESET} bash ${mgr} start --port ${PORT} --data-dir ${DATA_DIR}"
echo " ${C_BOLD}Then open:${C_RESET} http://127.0.0.1:${PORT}"
fi
echo
echo " ${C_DIM}Runs in echo mode with zero keys. Add an API key in Settings > API Keys${C_RESET}"
echo " ${C_DIM}to enable real models. Connect Slack/Telegram/WhatsApp/Discord under${C_RESET}"
echo " ${C_DIM}Settings > Channels to reach your agent from anywhere.${C_RESET}"
echo
echo " ${C_BOLD}Manage the server:${C_RESET}"
echo " bash ${mgr} status"
echo " bash ${mgr} logs"
echo " bash ${mgr} stop"
echo
}
# ── Main ──────────────────────────────────────────────────────────────────────
main() {
echo "${C_BOLD}Waggle OS installer${C_RESET}"
preflight
run_wizard
local marker="$INSTALL_DIR/$MARKER_NAME"
# D5 — 3-way idempotent directory branch.
if [ -d "$INSTALL_DIR" ] && [ -f "$marker" ]; then
say "Already installed at ${INSTALL_DIR}"
info "To update: cd ${INSTALL_DIR} && git pull && ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install && npm run build:packages$( [ "$BUILD_WEB" -eq 1 ] && echo ' && npm run build' )"
info "To run: bash ${INSTALL_DIR}/scripts/waggle-server.sh start --port ${PORT} --data-dir ${DATA_DIR}"
info "To reinstall fresh: remove ${marker} (or the whole directory) and re-run."
exit 0
elif [ -d "$INSTALL_DIR" ] && [ -n "$(ls -A "$INSTALL_DIR" 2>/dev/null)" ]; then
say "Resuming a partial install in ${INSTALL_DIR} (directory exists, no marker)"
if [ -n "$LOCAL_SOURCE" ]; then
info "Refreshing files from ${LOCAL_SOURCE}"
acquire_source
else
info "Skipping clone; using existing directory contents."
fi
else
acquire_source
fi
say "Installing dependencies (this can take a few minutes)"
# onnxruntime-node would otherwise download CUDA libraries (hundreds of MB)
# on every Linux x64 install, GPU or not; the in-process models run on CPU.
( cd "$INSTALL_DIR" && ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --no-audit --no-fund )
say "Building packages"
( cd "$INSTALL_DIR" && npm run build:packages )
if [ "$BUILD_WEB" -eq 1 ]; then
say "Building web UI"
( cd "$INSTALL_DIR" && npm run build )
else
info "Skipping web UI build (--no-web); the UI serves in API/echo mode only."
fi
verify_runtime || warn "Continuing despite the SQLite check — the server may still fail to open its database."
write_marker
if [ "$START_NOW" -eq 1 ]; then
say "Starting the server"
bash "$INSTALL_DIR/scripts/waggle-server.sh" start --port "$PORT" --data-dir "$DATA_DIR"
fi
success_card
}
main

249
package-lock.json generated
View File

@@ -19228,34 +19228,10 @@
"name": "@waggle-ai/waggle",
"version": "1.0.0",
"license": "MIT",
"dependencies": {
"@fastify/cors": "^10.0.0",
"@fastify/static": "^10.1.2",
"@fastify/websocket": "^11.0.0",
"@huggingface/transformers": "3.8.1",
"@puppeteer/browsers": "2.13.0",
"adm-zip": "^0.6.0",
"archiver": "^7.0.1",
"better-sqlite3": "^12.6.2",
"cron-parser": "^4.9.0",
"docx": "^9.6.1",
"exceljs": "^4.4.0",
"fastify": "^5.3.0",
"fastify-plugin": "^5.0.0",
"glob": "^13.0.6",
"mammoth": "^1.11.0",
"mem0ai": "3.3.1",
"pdf-parse": "^2.4.5",
"undici": "^6.27.0",
"whatsapp-web.js": "1.34.7",
"ws": "^8.21.0",
"zod": "^3.24.0"
},
"bin": {
"waggle": "dist/cli.js"
"waggle-server": "dist/cli.js"
},
"devDependencies": {
"@waggle/server": "*",
"tsup": "^8.5.1",
"tsx": "^4.21.0"
},
@@ -19263,229 +19239,6 @@
"node": ">=20"
}
},
"packages/launcher/node_modules/@anthropic-ai/sdk": {
"version": "0.40.1",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.40.1.tgz",
"integrity": "sha512-DJMWm8lTEM9Lk/MSFL+V+ugF7jKOn0M2Ujvb5fN8r2nY14aHbGPZ1k6sgjL+tpJ3VuOGJNG+4R83jEpOuYPv8w==",
"license": "MIT",
"optional": true,
"peer": true,
"dependencies": {
"@types/node": "^18.11.18",
"@types/node-fetch": "^2.6.4",
"abort-controller": "^3.0.0",
"agentkeepalive": "^4.2.1",
"form-data-encoder": "1.7.2",
"formdata-node": "^4.3.2",
"node-fetch": "^2.6.7"
}
},
"packages/launcher/node_modules/@types/node": {
"version": "18.19.130",
"resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
"integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
"license": "MIT",
"optional": true,
"peer": true,
"dependencies": {
"undici-types": "~5.26.4"
}
},
"packages/launcher/node_modules/mem0ai": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/mem0ai/-/mem0ai-3.3.1.tgz",
"integrity": "sha512-R+T0rB8WNU4Eh8ClfZnD2BKjk7Q4MDx3XdLZMoUZ+S7dItpkpg3xkcGrKqk0COV0dyRrul/EYzkDWTr2D6YTag==",
"license": "Apache-2.0",
"dependencies": {
"axios": "^1.18.0",
"openai": "^4.93.0",
"uuid": "^11.1.1",
"zod": "^3.24.1"
},
"engines": {
"node": ">=18"
},
"peerDependencies": {
"@anthropic-ai/sdk": "^0.40.1",
"@aws-sdk/client-bedrock-runtime": ">=3.0.0 <3.968.0",
"@aws-sdk/client-neptune-graph": ">=3.0.0 <3.968.0",
"@aws-sdk/client-s3vectors": "3.967.0",
"@azure/identity": "^4.0.0",
"@azure/search-documents": "^12.0.0",
"@cloudflare/workers-types": "^4.20250504.0",
"@databricks/sql": "^1.16.0",
"@elastic/elasticsearch": "^9.0.0",
"@google-cloud/aiplatform": "^6.8.0",
"@google/genai": "^1.40.0",
"@huggingface/transformers": "^3.0.0 || ^4.0.0",
"@langchain/core": "^1.1.47",
"@mistralai/mistralai": "^1.5.2",
"@mochow/mochow-sdk-node": "^2.1.5",
"@opensearch-project/opensearch": "^3.5.1",
"@pinecone-database/pinecone": "^8.0.0",
"@qdrant/js-client-rest": "^1.18.0",
"@supabase/supabase-js": "^2.49.1",
"@turbopuffer/turbopuffer": "^2.0.0",
"@types/pg": "^8.11.0",
"@upstash/vector": "^1.2.3",
"@zilliz/milvus2-sdk-node": "^2.4.0 || ^3.0.0",
"better-sqlite3": "^12.6.2",
"cassandra-driver": "4.8.0",
"chromadb": "^3.5.0",
"cloudflare": "^4.2.0",
"cohere-ai": "^7.17.0 || ^8.0.0",
"compromise": "^14.0.0",
"fastembed": "^2.1.0",
"groq-sdk": "0.3.0",
"iovalkey": "^0.3.3",
"mongodb": "^7.0.0",
"mysql2": "^3.0.0",
"natural": "^8.0.1",
"ollama": "^0.5.14",
"oracledb": "^6.5.0 || ^7.0.0",
"pg": "^8.11.3",
"redis": "^4.6.13",
"weaviate-client": "^3.0.0",
"zeroentropy": "^0.1.0-alpha.10"
},
"peerDependenciesMeta": {
"@anthropic-ai/sdk": {
"optional": true
},
"@aws-sdk/client-bedrock-runtime": {
"optional": true
},
"@aws-sdk/client-neptune-graph": {
"optional": true
},
"@aws-sdk/client-s3vectors": {
"optional": true
},
"@azure/identity": {
"optional": true
},
"@azure/search-documents": {
"optional": true
},
"@databricks/sql": {
"optional": true
},
"@elastic/elasticsearch": {
"optional": true
},
"@google-cloud/aiplatform": {
"optional": true
},
"@google/genai": {
"optional": true
},
"@huggingface/transformers": {
"optional": true
},
"@langchain/core": {
"optional": true
},
"@mistralai/mistralai": {
"optional": true
},
"@mochow/mochow-sdk-node": {
"optional": true
},
"@opensearch-project/opensearch": {
"optional": true
},
"@pinecone-database/pinecone": {
"optional": true
},
"@qdrant/js-client-rest": {
"optional": true
},
"@supabase/supabase-js": {
"optional": true
},
"@turbopuffer/turbopuffer": {
"optional": true
},
"@types/pg": {
"optional": true
},
"@upstash/vector": {
"optional": true
},
"@zilliz/milvus2-sdk-node": {
"optional": true
},
"cassandra-driver": {
"optional": true
},
"chromadb": {
"optional": true
},
"cloudflare": {
"optional": true
},
"cohere-ai": {
"optional": true
},
"fastembed": {
"optional": true
},
"groq-sdk": {
"optional": true
},
"iovalkey": {
"optional": true
},
"mongodb": {
"optional": true
},
"mysql2": {
"optional": true
},
"natural": {
"optional": true
},
"ollama": {
"optional": true
},
"oracledb": {
"optional": true
},
"pg": {
"optional": true
},
"redis": {
"optional": true
},
"weaviate-client": {
"optional": true
},
"zeroentropy": {
"optional": true
}
}
},
"packages/launcher/node_modules/undici-types": {
"version": "5.26.5",
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
"integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
"license": "MIT",
"optional": true,
"peer": true
},
"packages/launcher/node_modules/uuid": {
"version": "11.1.1",
"resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.1.tgz",
"integrity": "sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==",
"funding": [
"https://github.com/sponsors/broofa",
"https://github.com/sponsors/ctavan"
],
"license": "MIT",
"bin": {
"uuid": "dist/esm/bin/uuid"
}
},
"packages/marketplace": {
"name": "@waggle/marketplace",
"version": "0.1.0",

View File

@@ -25,6 +25,7 @@
"lint": "eslint .",
"check:deps": "node scripts/check-workspace-deps.mjs",
"check:licenses": "node scripts/check-licenses.mjs",
"build:server-archive": "node scripts/build-server-archive.mjs",
"lint:no-invalid-snapshots": "node scripts/check-no-invalid-snapshots.mjs",
"ux:contrast": "node scripts/ux-gates/contrast-tokens.mjs",
"ux:color-guard": "node scripts/ux-gates/text-color-guard.mjs",

View File

@@ -1,13 +1,13 @@
{
"name": "@waggle-ai/waggle",
"version": "1.0.0",
"description": "Waggle — Your personal AI agent swarm. Start with `npx @waggle-ai/waggle`.",
"description": "Installs and runs the Waggle server: npx @waggle-ai/waggle install",
"publishConfig": {
"access": "public"
},
"type": "module",
"bin": {
"waggle": "./dist/cli.js"
"waggle-server": "./dist/cli.js"
},
"files": [
"dist",
@@ -18,45 +18,19 @@
},
"scripts": {
"build": "tsup",
"start": "tsx --conditions=source src/cli.ts",
"test": "node ../../node_modules/vitest/vitest.mjs run --root ../.. --config vitest.config.ts packages/launcher/tests/cli.test.ts",
"start": "tsx src/cli.ts",
"test": "node ../../node_modules/vitest/vitest.mjs run --root ../.. --config vitest.config.ts packages/launcher/tests",
"prepublishOnly": "npm run build"
},
"keywords": [
"ai",
"agent",
"swarm",
"memory",
"waggle",
"llm",
"personal-assistant"
],
"license": "MIT",
"dependencies": {
"@fastify/cors": "^10.0.0",
"@fastify/static": "^10.1.2",
"@fastify/websocket": "^11.0.0",
"@huggingface/transformers": "3.8.1",
"@puppeteer/browsers": "2.13.0",
"adm-zip": "^0.6.0",
"archiver": "^7.0.1",
"better-sqlite3": "^12.6.2",
"cron-parser": "^4.9.0",
"docx": "^9.6.1",
"exceljs": "^4.4.0",
"fastify": "^5.3.0",
"fastify-plugin": "^5.0.0",
"glob": "^13.0.6",
"mammoth": "^1.11.0",
"mem0ai": "3.3.1",
"pdf-parse": "^2.4.5",
"undici": "^6.27.0",
"whatsapp-web.js": "1.34.7",
"ws": "^8.21.0",
"zod": "^3.24.0"
},
"devDependencies": {
"@waggle/server": "*",
"tsup": "^8.5.1",
"tsx": "^4.21.0"
}

View File

@@ -0,0 +1,107 @@
import { COMMAND_NAME } from './platform.js';
export type Command = 'install' | 'update' | 'run' | 'doctor' | 'uninstall' | 'help' | 'version';
export interface Options {
/** Archive path or URL; replaces the default download location. */
from?: string;
/** Expected SHA-256 of the archive. */
sha256?: string;
/** Install directory. */
dir?: string;
/** Directory for the command shim. */
binDir?: string;
/** Data directory passed to the server as WAGGLE_DATA_DIR. */
dataDir?: string;
port: number;
open: boolean;
force: boolean;
}
export interface ParsedArgs {
command: Command;
options: Options;
error?: string;
}
export const DEFAULT_PORT = 3333;
const COMMANDS: ReadonlySet<string> = new Set(['install', 'update', 'run', 'doctor', 'uninstall', 'help', 'version']);
const VALUE_FLAGS: Record<string, keyof Options> = {
'--from': 'from',
'--sha256': 'sha256',
'--dir': 'dir',
'--bin-dir': 'binDir',
'--data-dir': 'dataDir',
};
/** `args` is argv without the node and script entries. With no command, `run`. */
export function parseArgs(args: string[]): ParsedArgs {
const options: Options = { port: DEFAULT_PORT, open: true, force: false };
let command: Command | undefined;
const fail = (error: string): ParsedArgs => ({ command: command ?? 'run', options, error });
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '--help' || arg === '-h') {
command = 'help';
} else if (arg === '--version' || arg === '-v') {
command = 'version';
} else if (arg === '--no-open') {
options.open = false;
} else if (arg === '--force') {
options.force = true;
} else if (arg === '--port' || arg === '-p') {
const value = args[++i];
const port = Number(value);
if (value === undefined || !Number.isInteger(port) || port < 1 || port > 65_535) {
return fail(`Invalid port: ${value ?? '(missing)'}. Use a number between 1 and 65535.`);
}
options.port = port;
} else if (arg in VALUE_FLAGS) {
const value = args[++i];
if (value === undefined || value.startsWith('--')) return fail(`Missing value for ${arg}.`);
(options[VALUE_FLAGS[arg]] as string) = value;
} else if (arg.startsWith('-')) {
return fail(`Unknown option: ${arg}`);
} else if (command === undefined && COMMANDS.has(arg)) {
command = arg as Command;
} else {
return fail(`Unknown command: ${arg}`);
}
}
if (options.sha256 !== undefined && !/^[0-9a-fA-F]{64}$/.test(options.sha256)) {
return fail('--sha256 takes the 64-character hex digest of the archive.');
}
return { command: command ?? 'run', options };
}
export function formatHelp(version: string): string {
return `
Waggle server ${version}
Usage:
${COMMAND_NAME} <command> [options]
Commands:
install Download and install the Waggle server for this system
update Replace the installed server with this version (or --from)
run Start the server and open it in the browser (default)
doctor Check the installation and report problems
uninstall Remove the installed server; your data stays
Options:
--from <path|url> Install from this archive instead of the release download
--sha256 <hex> Expected SHA-256 of the archive
--dir <path> Install directory
--bin-dir <path> Where to put the ${COMMAND_NAME} command
--data-dir <path> Data directory (default: $WAGGLE_DATA_DIR or ~/.waggle)
--port, -p <number> Server port (default: ${DEFAULT_PORT})
--no-open Do not open the browser
--force Reinstall even when this version is installed
--help, -h Show this help
--version, -v Show the version
`;
}

View File

@@ -1,126 +0,0 @@
export interface LauncherArgs {
port: number;
skipLiteLLM: boolean;
noBrowser: boolean;
help: boolean;
error?: string;
}
export interface StartupSuccessOptions {
url: string;
llmProvider: string;
llmHealth: string;
dataDir: string;
noBrowser: boolean;
}
const DEFAULT_PORT = 3333;
const MAX_PORT = 65535;
export function parseArgs(argv: string[]): LauncherArgs {
const args = argv.slice(2);
const result: LauncherArgs = {
port: DEFAULT_PORT,
skipLiteLLM: false,
noBrowser: false,
help: false,
};
for (let i = 0; i < args.length; i++) {
const arg = args[i];
if (arg === '--port' || arg === '-p') {
const value = args[++i];
if (value === undefined) {
result.error = 'Missing value for --port. Use a number between 1 and 65535.';
return result;
}
const port = Number(value);
if (!Number.isInteger(port) || port < 1 || port > MAX_PORT) {
result.error = `Invalid port: ${value}. Use a number between 1 and 65535.`;
return result;
}
result.port = port;
} else if (arg === '--skip-litellm') {
result.skipLiteLLM = true;
} else if (arg === '--no-open') {
result.noBrowser = true;
} else if (arg === '--help' || arg === '-h') {
result.help = true;
} else if (arg.startsWith('-')) {
result.error = `Unknown option: ${arg}`;
return result;
} else {
result.error = `Unknown argument: ${arg}`;
return result;
}
}
return result;
}
export function formatHelp(): string {
return `
Waggle - Your personal AI agent swarm
Usage:
npx waggle [options]
Options:
--port, -p <number> Server port (default: 3333)
--skip-litellm Use built-in Anthropic proxy instead of LiteLLM
--no-open Do not open browser automatically
--help, -h Show this help message
Data directory: ~/.waggle/
Config: ~/.waggle/config.json
`;
}
export function formatStartupFailure(message: string, port: number): string {
const firstLine = message.split(/\r?\n/)[0] || message;
const lines = [
'',
` Failed to start Waggle: ${firstLine}`,
'',
];
if (/port\s+\d+\s+is already in use/i.test(firstLine)) {
lines.push(
` Another app is already using port ${port}.`,
` Try: npx waggle --port ${port + 1}`,
' Or close the other Waggle instance and run the command again.',
'',
);
} else {
lines.push(
' Check the message above, fix the startup problem, and run the command again.',
'',
);
}
return lines.join('\n');
}
export function formatStartupSuccess(options: StartupSuccessOptions): string {
const lines = [
'',
` Server: ${options.url}`,
` LLM: ${options.llmProvider} (${options.llmHealth})`,
` Data: ${options.dataDir}`,
];
if (options.noBrowser) {
lines.push(
' Browser: not opened (--no-open)',
` Open manually: ${options.url}`,
);
} else {
lines.push(' Browser: opening default browser');
}
lines.push('', ' Press Ctrl+C to stop', '');
return lines.join('\n');
}

View File

@@ -1,117 +1,84 @@
/**
* Waggle CLI Launcher - `npx waggle`
* Waggle server installer and launcher.
*
* Starts the Waggle server and opens the frontend in the default browser.
* npx <package> install download the server for this system and install it
* waggle-server start it and open the browser (same as `run`)
* waggle-server doctor check the installation
* waggle-server update install this tool's version over the installed one
* waggle-server uninstall remove the program; the data directory stays
*
* Usage:
* npx waggle # Start on default port 3333
* npx waggle --port 4000 # Start on custom port
* npx waggle --skip-litellm # Skip LiteLLM proxy
* npx waggle --no-open # Do not open browser automatically
* The tool is one self-contained script. Install copies it next to the
* payload, and the shim runs that copy with the payload's own Node.
*/
import fs from 'node:fs';
import { fileURLToPath } from 'node:url';
import { formatHelp, parseArgs } from './args.js';
import { UserError, doctor, install, run, uninstall, type Context } from './commands.js';
import { currentHost } from './platform.js';
import { execFile } from 'node:child_process';
import os from 'node:os';
import {
formatHelp,
formatStartupFailure,
formatStartupSuccess,
parseArgs,
} from './cli-core.js';
declare const __WAGGLE_SERVER_VERSION__: string | undefined;
function openBrowser(url: string): void {
const platform = os.platform();
const onOpenError = (err: Error | null): void => {
if (err) console.log(` Open manually: ${url}`);
};
const VERSION: string = typeof __WAGGLE_SERVER_VERSION__ === 'string'
? __WAGGLE_SERVER_VERSION__
: (JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version;
if (platform === 'win32') {
execFile('cmd', ['/c', 'start', '', url], onOpenError);
} else if (platform === 'darwin') {
execFile('open', [url], onOpenError);
} else {
execFile('xdg-open', [url], onOpenError);
}
const MIN_NODE_MAJOR = 20;
/** The bundled script can be copied into an install; a TypeScript source cannot run on its own. */
function launcherSource(): string | null {
const self = fileURLToPath(import.meta.url);
return /\.m?js$/.test(self) ? self : null;
}
function checkNodeVersion(): boolean {
const [major] = process.versions.node.split('.').map(Number);
if (major < 18) {
console.error(`\n Waggle requires Node.js >= 18. You have ${process.versions.node}.`);
console.error(' Install a newer version: https://nodejs.org\n');
return false;
}
return true;
}
async function main() {
const { port, skipLiteLLM, noBrowser, help, error } = parseArgs(process.argv);
if (help) {
console.log(formatHelp());
process.exit(0);
async function main(): Promise<number> {
const major = Number(process.versions.node.split('.')[0]);
if (major < MIN_NODE_MAJOR) {
console.error(`\n Waggle needs Node.js ${MIN_NODE_MAJOR} or newer to install. This is ${process.versions.node}.\n`);
return 1;
}
const { command, options, error } = parseArgs(process.argv.slice(2));
if (error) {
console.error();
console.error(` ${error}`);
console.error(formatHelp());
process.exit(1);
console.error(`\n ${error}`);
console.error(formatHelp(VERSION));
return 1;
}
if (!checkNodeVersion()) {
process.exit(1);
}
console.log();
console.log(' Waggle - AI Agent Swarm');
console.log(' ------------------------');
const { startService, isFirstRun } = await import('@waggle/server/local/service');
const dataDir = process.env.WAGGLE_DATA_DIR || undefined;
const displayDataDir = dataDir ?? `${os.homedir()}/.waggle`;
const firstRun = isFirstRun(displayDataDir);
if (firstRun) {
console.log(' Welcome! Setting up for the first time...');
console.log();
}
try {
const { server } = await startService({
port,
skipLiteLLM,
dataDir,
onProgress: (event) => {
const pct = Math.round(event.progress * 100);
process.stdout.write(`\r [${pct.toString().padStart(3)}%] ${event.message}`);
if (event.phase === 'ready') {
process.stdout.write('\n');
}
},
});
const addr = server.server.address();
const actualPort = typeof addr === 'object' && addr ? addr.port : port;
const url = `http://localhost:${actualPort}`;
const llm = server.agentState.llmProvider;
console.log(formatStartupSuccess({
url,
llmProvider: llm.provider,
llmHealth: llm.health,
dataDir: displayDataDir,
noBrowser,
}));
if (!noBrowser) {
openBrowser(url);
}
} catch (err: unknown) {
const message = err instanceof Error ? err.message : String(err);
console.error(formatStartupFailure(message, port));
process.exit(1);
const ctx: Context = {
host: currentHost(),
version: VERSION,
launcherSource: launcherSource(),
out: (line) => console.log(line),
};
switch (command) {
case 'help':
console.log(formatHelp(VERSION));
return 0;
case 'version':
console.log(VERSION);
return 0;
case 'install':
await install(ctx, options);
return 0;
case 'update':
await install(ctx, options, 'update');
return 0;
case 'doctor':
return doctor(ctx, options);
case 'uninstall':
return uninstall(ctx, options);
case 'run':
return run(ctx, options);
}
}
main();
main().then(
(code) => {
process.exitCode = code;
},
(error: unknown) => {
console.error(`\n ${error instanceof Error ? error.message : String(error)}\n`);
if (!(error instanceof UserError) && error instanceof Error && error.stack) console.error(error.stack);
process.exitCode = 1;
},
);

View File

@@ -0,0 +1,502 @@
/**
* install, update, run, doctor and uninstall.
*
* Errors the user can act on are UserError: the CLI prints their message
* without a stack trace.
*/
import { execFile, spawn, spawnSync } from 'node:child_process';
import fs from 'node:fs';
import net from 'node:net';
import type { Options } from './args.js';
import {
COMMAND_NAME,
assetName,
defaultBinDir,
defaultDataDir,
defaultInstallDir,
isOnPath,
pathApi,
releaseTarget,
type Host,
} from './platform.js';
import {
downloadFile,
extractArchive,
fetchText,
isUrl,
layoutFor,
missingPayloadFiles,
nodeBinary,
parseChecksum,
readManifest,
readRecord,
serviceEnvironment,
sha256File,
shimContent,
shimFile,
writeRecord,
type Layout,
} from './payload.js';
/**
* Where releases are downloaded from, as `<base>/v<version>/<asset>`; for a
* GitHub repository that is https://github.com/<owner>/<repo>/releases/download.
* Empty until the public repository location is decided (Q9).
* WAGGLE_RELEASE_BASE_URL overrides it.
*/
export const DEFAULT_RELEASE_BASE_URL = '';
/** How long `run` waits for the first health answer before it stops reporting. */
const STARTUP_REPORT_TIMEOUT_MS = 300_000;
export interface Context {
host: Host;
/** Version of this tool, which is also the server version it installs. */
version: string;
/** This tool's bundled script, copied into the install for the shim. Null when running from source. */
launcherSource: string | null;
out: (line: string) => void;
}
export class UserError extends Error {}
function message(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
/** --dir, else the install this copy of the tool lives in, else the default. */
function installDir(ctx: Context, opts: Options): string {
const p = pathApi(ctx.host.platform);
if (opts.dir) return p.resolve(opts.dir);
if (ctx.launcherSource) {
const ownDir = p.dirname(ctx.launcherSource);
if (fs.existsSync(p.join(ownDir, 'install.json'))) return ownDir;
}
return defaultInstallDir(ctx.host);
}
function binDir(ctx: Context, opts: Options, layout: Layout): string {
return opts.binDir ? pathApi(ctx.host.platform).resolve(opts.binDir) : defaultBinDir(ctx.host, layout.root);
}
/** --bin-dir, else the shim install recorded, else the default location. */
function installedShim(ctx: Context, opts: Options, layout: Layout): string {
const recorded = opts.binDir ? null : readRecord(layout)?.shim;
return recorded ?? shimFile(binDir(ctx, opts, layout), COMMAND_NAME, ctx.host.platform);
}
/** Windows cannot replace or delete the program that is running this tool. */
function assertNotRunningFromInstall(ctx: Context, layout: Layout, action: string): void {
if (ctx.host.platform !== 'win32') return;
const p = pathApi('win32');
const relative = p.relative(layout.appDir.toLowerCase(), p.resolve(process.execPath).toLowerCase());
if (!relative.startsWith('..') && !p.isAbsolute(relative)) {
throw new UserError(`Windows cannot ${action} the program it is running. Run it through npx instead: npx <package> ${action}`);
}
}
function isOurShim(file: string): boolean {
try {
return fs.readFileSync(file, 'utf8').includes('launcher.mjs');
} catch {
return false;
}
}
// ── install / update ─────────────────────────────────────────────────────────
interface Archive {
file: string;
source: string;
expected: string | null;
downloaded: boolean;
}
function progressPrinter(ctx: Context): (received: number, total: number | null) => void {
let reported = -1;
return (received, total) => {
if (!total) return;
const step = Math.floor((received / total) * 10);
if (step > reported) {
reported = step;
ctx.out(` ${step * 10}% of ${(total / 1024 / 1024).toFixed(0)} MB`);
}
};
}
async function obtainArchive(ctx: Context, layout: Layout, opts: Options, target: string): Promise<Archive> {
const p = pathApi(ctx.host.platform);
const flagChecksum = opts.sha256?.toLowerCase() ?? null;
let source = opts.from;
if (!source) {
const base = (ctx.host.env.WAGGLE_RELEASE_BASE_URL || DEFAULT_RELEASE_BASE_URL).replace(/\/+$/, '');
if (!base) {
throw new UserError('This build has no download location yet. Pass --from <archive path or URL>.');
}
source = `${base}/v${ctx.version}/${assetName(ctx.version, target)}`;
}
if (isUrl(source)) {
const expected = flagChecksum ?? parseChecksum((await fetchText(`${source}.sha256`)) ?? '');
if (!expected) {
throw new UserError(`No checksum found at ${source}.sha256. Pass --sha256 <hex> to install anyway.`);
}
fs.mkdirSync(layout.downloadsDir, { recursive: true });
const file = p.join(layout.downloadsDir, p.basename(new URL(source).pathname) || 'waggle-server.tar.gz');
ctx.out(`Downloading ${source}`);
await downloadFile(source, file, progressPrinter(ctx));
return { file, source, expected, downloaded: true };
}
const file = p.resolve(source);
if (!fs.existsSync(file)) throw new UserError(`Archive not found: ${file}`);
const checksumFile = `${file}.sha256`;
const expected = flagChecksum
?? (fs.existsSync(checksumFile) ? parseChecksum(fs.readFileSync(checksumFile, 'utf8')) : null);
return { file, source: file, expected, downloaded: false };
}
/** Swaps the unpacked payload in for the active one. */
function activate(layout: Layout, staging: string, platform: NodeJS.Platform): void {
const previous = pathApi(platform).join(layout.root, 'app.old');
fs.rmSync(previous, { recursive: true, force: true });
try {
if (fs.existsSync(layout.appDir)) fs.renameSync(layout.appDir, previous);
} catch (error) {
fs.rmSync(staging, { recursive: true, force: true });
throw new UserError(`Could not replace ${layout.appDir}. Stop the running Waggle server and try again. (${message(error)})`);
}
fs.renameSync(staging, layout.appDir);
fs.rmSync(previous, { recursive: true, force: true });
}
export async function install(ctx: Context, opts: Options, mode: 'install' | 'update' = 'install'): Promise<void> {
const { host } = ctx;
const p = pathApi(host.platform);
const target = releaseTarget(host);
if (!target) {
throw new UserError(
`There is no Waggle server build for ${host.platform}-${host.arch}. `
+ 'Builds exist for Windows x64, macOS (Apple and Intel) and Linux x64.',
);
}
const layout = layoutFor(installDir(ctx, opts), host.platform);
const record = readRecord(layout);
if (mode === 'update' && !record) {
throw new UserError(`The Waggle server is not installed in ${layout.root}. Run: ${COMMAND_NAME} install`);
}
if (record && !opts.from && !opts.force && record.version === ctx.version) {
ctx.out(mode === 'update'
? `Waggle server ${record.version} is up to date.`
: `Waggle server ${record.version} is already installed in ${layout.root}. Use --force to reinstall.`);
return;
}
if (record) assertNotRunningFromInstall(ctx, layout, mode);
fs.mkdirSync(layout.root, { recursive: true });
const archive = await obtainArchive(ctx, layout, opts, target);
const staging = p.join(layout.root, 'app.new');
try {
ctx.out('Checking the archive...');
const actual = await sha256File(archive.file);
if (archive.expected && archive.expected !== actual) {
throw new UserError(`The archive checksum does not match: expected ${archive.expected}, got ${actual}. Download it again.`);
}
if (!archive.expected) ctx.out(' No checksum was given for this archive, so it was not compared.');
ctx.out('Unpacking...');
fs.rmSync(staging, { recursive: true, force: true });
extractArchive(host, archive.file, staging);
const manifest = readManifest(staging, host.platform);
if (manifest.target !== target) {
throw new UserError(`This archive is for ${manifest.target}; this system needs ${target}.`);
}
const missing = missingPayloadFiles(staging, host.platform);
if (missing.length > 0) {
throw new UserError(`The archive is incomplete. Missing: ${missing.map((file) => p.relative(staging, file)).join(', ')}`);
}
activate(layout, staging, host.platform);
let shim: string | null = null;
if (ctx.launcherSource) {
fs.copyFileSync(ctx.launcherSource, layout.launcherFile);
const dir = binDir(ctx, opts, layout);
const candidate = shimFile(dir, COMMAND_NAME, host.platform);
if (fs.existsSync(candidate) && !isOurShim(candidate)) {
ctx.out(` ${candidate} exists and is not a Waggle command, so it was left alone.`);
} else {
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(candidate, shimContent(layout, host.platform), { mode: 0o755 });
if (host.platform !== 'win32') fs.chmodSync(candidate, 0o755);
shim = candidate;
}
}
writeRecord(layout, {
version: manifest.version,
target,
installedAt: new Date().toISOString(),
source: archive.source,
sha256: actual,
shim,
});
ctx.out('');
ctx.out(`Installed Waggle server ${manifest.version} in ${layout.root}`);
if (shim && isOnPath(host, p.dirname(shim))) {
ctx.out(`Start it with: ${COMMAND_NAME}`);
} else if (shim) {
ctx.out(`Start it with: ${shim}`);
ctx.out(`To type just ${COMMAND_NAME}, add ${p.dirname(shim)} to your PATH.`);
} else {
ctx.out(`Start it with: ${COMMAND_NAME} run --dir "${layout.root}"`);
}
} finally {
fs.rmSync(staging, { recursive: true, force: true });
if (archive.downloaded) fs.rmSync(archive.file, { force: true });
}
}
// ── run ──────────────────────────────────────────────────────────────────────
interface Health {
mode: string;
port: number;
}
export async function probeHealth(port: number): Promise<Health | null> {
try {
const response = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(1500) });
if (!response.ok) return null;
const body = (await response.json()) as Partial<Health>;
return body.mode === 'local' && typeof body.port === 'number' ? (body as Health) : null;
} catch {
return null;
}
}
export function portIsFree(port: number): Promise<boolean> {
return new Promise((resolve) => {
const server = net.createServer();
server.once('error', () => resolve(false));
server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
});
}
function openBrowser(host: Host, url: string, ctx: Context): void {
const onError = (error: Error | null) => {
if (error) ctx.out(`Open ${url} in your browser.`);
};
if (host.platform === 'win32') execFile('cmd', ['/c', 'start', '', url], { windowsHide: true }, onError);
else if (host.platform === 'darwin') execFile('open', [url], onError);
else execFile('xdg-open', [url], onError);
}
function requireInstall(ctx: Context, layout: Layout): NonNullable<ReturnType<typeof readRecord>> {
const record = readRecord(layout);
if (!record || missingPayloadFiles(layout.appDir, ctx.host.platform).length > 0) {
throw new UserError(`The Waggle server is not installed in ${layout.root}. Run: ${COMMAND_NAME} install`);
}
return record;
}
function dataDirFor(ctx: Context, opts: Options): string {
return opts.dataDir ? pathApi(ctx.host.platform).resolve(opts.dataDir) : defaultDataDir(ctx.host);
}
export async function run(ctx: Context, opts: Options): Promise<number> {
const { host } = ctx;
const p = pathApi(host.platform);
const layout = layoutFor(installDir(ctx, opts), host.platform);
const record = requireInstall(ctx, layout);
const url = `http://localhost:${opts.port}`;
if (await probeHealth(opts.port)) {
ctx.out(`Waggle is already running at ${url}`);
if (opts.open) openBrowser(host, url, ctx);
return 0;
}
if (!(await portIsFree(opts.port))) {
throw new UserError(`Port ${opts.port} is used by another program. Try: ${COMMAND_NAME} run --port ${opts.port + 1}`);
}
const dataDir = dataDirFor(ctx, opts);
const env = serviceEnvironment({
appDir: layout.appDir,
dataDir,
port: opts.port,
platform: host.platform,
baseEnv: host.env,
explicitDataDir: Boolean(opts.dataDir),
});
fs.mkdirSync(env.NPM_CONFIG_PREFIX as string, { recursive: true });
fs.mkdirSync(env.NPM_CONFIG_CACHE as string, { recursive: true });
ctx.out(`Starting Waggle server ${record.version}...`);
const child = spawn(nodeBinary(layout.appDir, host.platform), [p.join(layout.appDir, 'service.js')], {
cwd: layout.appDir,
env,
stdio: 'inherit',
windowsHide: true,
});
const forward = (signal: NodeJS.Signals) => {
if (child.exitCode === null) child.kill(signal);
};
process.on('SIGINT', forward);
process.on('SIGTERM', forward);
let exited = false;
const exit = new Promise<number>((resolve) => {
child.once('error', (error) => {
exited = true;
ctx.out(`Could not start the server: ${error.message}`);
resolve(1);
});
child.once('exit', (code, signal) => {
exited = true;
resolve(code ?? (signal ? 0 : 1));
});
});
void (async () => {
const deadline = Date.now() + STARTUP_REPORT_TIMEOUT_MS;
while (!exited && Date.now() < deadline) {
if (await probeHealth(opts.port)) {
ctx.out('');
ctx.out(` Waggle is running at ${url}`);
ctx.out(` Data: ${dataDir}`);
ctx.out(' Press Ctrl+C to stop.');
ctx.out('');
if (opts.open) openBrowser(host, url, ctx);
return;
}
await new Promise((resolve) => setTimeout(resolve, 500));
}
if (!exited) ctx.out(`The server is still starting. Open ${url} when it is ready.`);
})();
const code = await exit;
process.off('SIGINT', forward);
process.off('SIGTERM', forward);
return code;
}
// ── doctor ───────────────────────────────────────────────────────────────────
type Level = 'ok' | 'warn' | 'fail';
const LEVEL_LABEL: Record<Level, string> = { ok: 'ok ', warn: 'warn', fail: 'FAIL' };
/**
* Loads better-sqlite3 from the payload the way waggle.db and the memory
* store do. The module name is passed as an argument: it is the payload's
* dependency, not this tool's.
*/
const NATIVE_CHECK = ['-e', "const D = require(process.argv[1]); new D(':memory:').prepare('select 1').get();", 'better-sqlite3'];
export async function doctor(ctx: Context, opts: Options): Promise<number> {
const { host } = ctx;
const p = pathApi(host.platform);
let failures = 0;
const report = (level: Level, name: string, detail: string) => {
if (level === 'fail') failures++;
ctx.out(` ${LEVEL_LABEL[level]} ${name}: ${detail}`);
};
ctx.out(`Waggle server doctor (tool ${ctx.version})`);
const target = releaseTarget(host);
report(target ? 'ok' : 'fail', 'System', target ?? `${host.platform}-${host.arch} has no Waggle server build`);
const layout = layoutFor(installDir(ctx, opts), host.platform);
const record = readRecord(layout);
if (!record) {
report('fail', 'Install', `nothing installed in ${layout.root}. Run: ${COMMAND_NAME} install`);
return 1;
}
report('ok', 'Install', `version ${record.version} in ${layout.root}`);
const missing = missingPayloadFiles(layout.appDir, host.platform);
report(
missing.length === 0 ? 'ok' : 'fail',
'Files',
missing.length === 0 ? 'server, runtime and web UI present' : `missing ${missing.map((file) => p.relative(layout.appDir, file)).join(', ')}`,
);
const dataDir = dataDirFor(ctx, opts);
const env = serviceEnvironment({
appDir: layout.appDir,
dataDir,
port: opts.port,
platform: host.platform,
baseEnv: host.env,
explicitDataDir: Boolean(opts.dataDir),
});
const node = nodeBinary(layout.appDir, host.platform);
if (fs.existsSync(node)) {
let expectedNode: string | null = null;
try {
expectedNode = readManifest(layout.appDir, host.platform).node;
} catch {
expectedNode = null;
}
const version = spawnSync(node, ['-p', 'process.versions.node'], { encoding: 'utf8', windowsHide: true });
const actualNode = version.status === 0 ? version.stdout.trim() : null;
if (!actualNode) report('fail', 'Node runtime', `does not start: ${version.error?.message ?? version.stderr.trim()}`);
else if (expectedNode && actualNode !== expectedNode) report('fail', 'Node runtime', `${actualNode}, but the archive was built for ${expectedNode}`);
else report('ok', 'Node runtime', actualNode);
const native = spawnSync(node, NATIVE_CHECK, { cwd: layout.appDir, env, encoding: 'utf8', windowsHide: true });
report(
native.status === 0 ? 'ok' : 'fail',
'Native modules',
native.status === 0 ? 'SQLite loads' : `SQLite does not load: ${(native.error?.message ?? native.stderr.trim()).split('\n')[0]}`,
);
}
try {
fs.mkdirSync(dataDir, { recursive: true });
const probe = p.join(dataDir, `.doctor-${process.pid}`);
fs.writeFileSync(probe, 'ok');
fs.rmSync(probe, { force: true });
report('ok', 'Data', dataDir);
} catch (error) {
report('fail', 'Data', `${dataDir} is not writable: ${message(error)}`);
}
if (await probeHealth(opts.port)) report('ok', 'Port', `${opts.port}: Waggle is running there`);
else if (await portIsFree(opts.port)) report('ok', 'Port', `${opts.port} is free`);
else report('warn', 'Port', `${opts.port} is used by another program; start with --port`);
const shim = installedShim(ctx, opts, layout);
if (!fs.existsSync(shim)) report('warn', 'Command', `${shim} is missing; reinstall to recreate it`);
else if (!isOnPath(host, p.dirname(shim))) report('warn', 'Command', `${p.dirname(shim)} is not on your PATH`);
else report('ok', 'Command', COMMAND_NAME);
return failures > 0 ? 1 : 0;
}
// ── uninstall ────────────────────────────────────────────────────────────────
export async function uninstall(ctx: Context, opts: Options): Promise<number> {
const { host } = ctx;
const layout = layoutFor(installDir(ctx, opts), host.platform);
if (!fs.existsSync(layout.root)) {
ctx.out(`Nothing to remove: ${layout.root} does not exist.`);
return 0;
}
if (!readRecord(layout)) {
throw new UserError(`${layout.root} is not a Waggle server install (it has no install.json). Nothing was removed.`);
}
assertNotRunningFromInstall(ctx, layout, 'uninstall');
const shim = installedShim(ctx, opts, layout);
if (isOurShim(shim)) fs.rmSync(shim, { force: true });
try {
fs.rmSync(layout.root, { recursive: true, force: true });
} catch (error) {
throw new UserError(`Could not remove ${layout.root}. Stop the running Waggle server and try again. (${message(error)})`);
}
ctx.out(`Removed the Waggle server from ${layout.root}.`);
ctx.out(`Your data stays in ${dataDirFor(ctx, opts)}. Delete that folder yourself if you no longer need it.`);
return 0;
}

View File

@@ -0,0 +1,233 @@
/**
* The release payload and its place on disk.
*
* A payload is the sidecar the desktop app ships (service.js, a pinned Node,
* native modules, staged node_modules) plus the built web UI, packed as one
* tar.gz per release target with a manifest.json at its root. It runs on its
* own Node, so native modules always match their ABI and nothing is compiled
* on the user's machine.
*
* Install directory:
* app/ the active payload
* launcher.mjs a copy of this tool, run by the shim with app/'s Node
* install.json what is installed and where it came from
* downloads/ archives being fetched
*/
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import fs from 'node:fs';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
import type { Host } from './platform.js';
import { pathApi } from './platform.js';
export interface Layout {
root: string;
appDir: string;
launcherFile: string;
recordFile: string;
downloadsDir: string;
}
export function layoutFor(root: string, platform: NodeJS.Platform): Layout {
const p = pathApi(platform);
return {
root,
appDir: p.join(root, 'app'),
launcherFile: p.join(root, 'launcher.mjs'),
recordFile: p.join(root, 'install.json'),
downloadsDir: p.join(root, 'downloads'),
};
}
export interface InstallRecord {
version: string;
target: string;
/** ISO 8601. */
installedAt: string;
/** The path or URL the archive came from. */
source: string;
sha256: string | null;
/** The command shim install wrote, if any. */
shim: string | null;
}
export interface PayloadManifest {
name: 'waggle-server';
version: string;
target: string;
/** Version of the bundled Node, without the leading v. */
node: string;
}
export function readRecord(layout: Layout): InstallRecord | null {
try {
return JSON.parse(fs.readFileSync(layout.recordFile, 'utf8')) as InstallRecord;
} catch {
return null;
}
}
export function writeRecord(layout: Layout, record: InstallRecord): void {
fs.writeFileSync(layout.recordFile, `${JSON.stringify(record, null, 2)}\n`);
}
export function readManifest(payloadDir: string, platform: NodeJS.Platform): PayloadManifest {
const file = pathApi(platform).join(payloadDir, 'manifest.json');
let manifest: Partial<PayloadManifest>;
try {
manifest = JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<PayloadManifest>;
} catch {
throw new Error('The archive has no readable manifest.json; it is not a Waggle server archive.');
}
if (manifest.name !== 'waggle-server' || !manifest.version || !manifest.target || !manifest.node) {
throw new Error('The archive manifest is not a Waggle server manifest.');
}
return manifest as PayloadManifest;
}
export function nodeBinary(appDir: string, platform: NodeJS.Platform): string {
return pathApi(platform).join(appDir, platform === 'win32' ? 'node.exe' : 'node');
}
/** Files the sidecar cannot start without. */
export function missingPayloadFiles(appDir: string, platform: NodeJS.Platform): string[] {
const p = pathApi(platform);
return [
nodeBinary(appDir, platform),
p.join(appDir, 'service.js'),
p.join(appDir, 'node_modules'),
p.join(appDir, 'web', 'index.html'),
].filter((file) => !fs.existsSync(file));
}
// ── Checksums ────────────────────────────────────────────────────────────────
export async function sha256File(file: string): Promise<string> {
const hash = createHash('sha256');
await pipeline(fs.createReadStream(file), hash);
return hash.digest('hex');
}
/** Reads `<hex> <name>` (sha256sum format) or a bare hex digest. */
export function parseChecksum(text: string): string | null {
const match = /^\s*([0-9a-fA-F]{64})(?:\s|$)/.exec(text);
return match ? match[1].toLowerCase() : null;
}
// ── Archives ─────────────────────────────────────────────────────────────────
/** bsdtar ships with Windows 10 1803 and later; macOS and Linux always have tar. */
export function tarCommand(host: Pick<Host, 'platform' | 'env'>): string {
if (host.platform !== 'win32') return 'tar';
const systemRoot = host.env.SystemRoot || host.env.WINDIR || 'C:\\Windows';
return pathApi('win32').join(systemRoot, 'System32', 'tar.exe');
}
export function extractArchive(host: Host, archive: string, destination: string): void {
fs.mkdirSync(destination, { recursive: true });
const result = spawnSync(tarCommand(host), ['-xzf', archive, '-C', destination], {
encoding: 'utf8',
windowsHide: true,
});
if (result.error || result.status !== 0) {
const detail = result.error?.message ?? result.stderr.trim();
throw new Error(`Could not unpack ${archive}: ${detail}`);
}
}
// ── Downloads ────────────────────────────────────────────────────────────────
export function isUrl(source: string): boolean {
return /^https?:\/\//i.test(source);
}
export async function fetchText(url: string): Promise<string | null> {
const response = await fetch(url, { redirect: 'follow' });
if (response.status === 404) return null;
if (!response.ok) throw new Error(`GET ${url} failed: HTTP ${response.status}`);
return response.text();
}
export async function downloadFile(
url: string,
destination: string,
onProgress?: (received: number, total: number | null) => void,
): Promise<void> {
const response = await fetch(url, { redirect: 'follow' });
if (!response.ok || !response.body) {
throw new Error(`Download of ${url} failed: HTTP ${response.status}`);
}
const total = Number(response.headers.get('content-length')) || null;
let received = 0;
const body = Readable.fromWeb(response.body as import('node:stream/web').ReadableStream<Uint8Array>);
body.on('data', (chunk: Buffer) => {
received += chunk.length;
onProgress?.(received, total);
});
const partial = `${destination}.partial`;
try {
await pipeline(body, fs.createWriteStream(partial));
fs.renameSync(partial, destination);
} finally {
fs.rmSync(partial, { force: true });
}
}
// ── Running the payload ──────────────────────────────────────────────────────
export interface ServiceEnvOptions {
appDir: string;
dataDir: string;
port: number;
platform: NodeJS.Platform;
baseEnv: NodeJS.ProcessEnv;
/** Pass WAGGLE_DATA_DIR only when the user chose a directory. */
explicitDataDir: boolean;
}
/**
* The environment the desktop shell gives its bundled sidecar
* (app/src-tauri/src/service.rs, build_service_command), plus the web UI
* directory, since here the sidecar serves the UI itself.
*/
export function serviceEnvironment(options: ServiceEnvOptions): NodeJS.ProcessEnv {
const p = pathApi(options.platform);
const runtimeDir = p.join(options.appDir, 'node_modules', 'waggle-node-runtime');
const nativeDir = p.join(options.appDir, 'native');
const env: NodeJS.ProcessEnv = {
...options.baseEnv,
WAGGLE_SKIP_LITELLM: '1',
WAGGLE_PORT: String(options.port),
WAGGLE_FRONTEND_DIR: p.join(options.appDir, 'web'),
NODE_PATH: [p.join(options.appDir, 'node_modules'), nativeDir].join(p.delimiter),
ONNXRUNTIME_NODE_BINDING_PATH: p.join(nativeDir, 'onnxruntime'),
PATH: [p.join(runtimeDir, 'bin'), options.appDir, options.baseEnv.PATH ?? options.baseEnv.Path]
.filter(Boolean)
.join(p.delimiter),
NPM_EXECPATH: p.join(runtimeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
NPM_CONFIG_PREFIX: p.join(options.dataDir, 'npm', 'prefix'),
NPM_CONFIG_CACHE: p.join(options.dataDir, 'npm', 'cache'),
};
// Windows keeps both spellings in process.env; a stale Path would shadow PATH.
if (options.platform === 'win32') delete env.Path;
if (options.explicitDataDir) env.WAGGLE_DATA_DIR = options.dataDir;
else delete env.WAGGLE_DATA_DIR;
return env;
}
// ── Command shim ─────────────────────────────────────────────────────────────
export function shimFile(binDir: string, commandName: string, platform: NodeJS.Platform): string {
return pathApi(platform).join(binDir, platform === 'win32' ? `${commandName}.cmd` : commandName);
}
/** Runs this tool with the payload's own Node, so the user's Node is not needed after install. */
export function shimContent(layout: Layout, platform: NodeJS.Platform): string {
const node = nodeBinary(layout.appDir, platform);
if (platform === 'win32') {
return `@echo off\r\n"${node}" "${layout.launcherFile}" %*\r\n`;
}
const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
return `#!/bin/sh\nexec ${quote(node)} ${quote(layout.launcherFile)} "$@"\n`;
}

View File

@@ -0,0 +1,79 @@
/**
* Where things live on each system: the release target of this machine, the
* install directory, the directory for the command shim and the data
* directory the sidecar uses.
*/
import os from 'node:os';
import path from 'node:path';
/** The command the installer puts on the PATH. A working name until the product name is decided. */
export const COMMAND_NAME = 'waggle-server';
export interface Host {
platform: NodeJS.Platform;
arch: string;
homedir: string;
env: NodeJS.ProcessEnv;
}
export function currentHost(): Host {
return { platform: process.platform, arch: process.arch, homedir: os.homedir(), env: process.env };
}
/** Release targets of v1: Windows x64, macOS on Apple and Intel, Linux x64. */
const TARGETS: Record<string, string> = {
'win32-x64': 'windows-x64',
'darwin-arm64': 'macos-arm64',
'darwin-x64': 'macos-x64',
'linux-x64': 'linux-x64',
};
export function releaseTarget(host: Pick<Host, 'platform' | 'arch'>): string | null {
return TARGETS[`${host.platform}-${host.arch}`] ?? null;
}
export function assetName(version: string, target: string): string {
return `waggle-server-${version}-${target}.tar.gz`;
}
export function pathApi(platform: NodeJS.Platform): path.PlatformPath {
return platform === 'win32' ? path.win32 : path.posix;
}
/** Program files, not user data: uninstall removes this directory whole. */
export function defaultInstallDir(host: Host): string {
const p = pathApi(host.platform);
if (host.platform === 'win32') {
const localAppData = host.env.LOCALAPPDATA || p.join(host.homedir, 'AppData', 'Local');
return p.join(localAppData, 'Waggle', 'server');
}
if (host.platform === 'darwin') {
return p.join(host.homedir, 'Library', 'Application Support', 'Waggle', 'server');
}
const dataHome = host.env.XDG_DATA_HOME || p.join(host.homedir, '.local', 'share');
return p.join(dataHome, 'waggle', 'server');
}
/**
* Where the command shim goes. On Windows it stays inside the install
* directory: the installer never edits the user's PATH, it prints how to.
*/
export function defaultBinDir(host: Host, installDir: string): string {
const p = pathApi(host.platform);
return host.platform === 'win32' ? p.join(installDir, 'bin') : p.join(host.homedir, '.local', 'bin');
}
/** Same rule as the sidecar's resolveDataDir: WAGGLE_DATA_DIR, else ~/.waggle. */
export function defaultDataDir(host: Host): string {
return host.env.WAGGLE_DATA_DIR || pathApi(host.platform).join(host.homedir, '.waggle');
}
export function isOnPath(host: Host, dir: string): boolean {
const p = pathApi(host.platform);
const entries = (host.env.PATH ?? host.env.Path ?? '').split(p.delimiter).filter(Boolean);
const normalize = (value: string) => {
const resolved = p.resolve(value);
return host.platform === 'win32' ? resolved.toLowerCase() : resolved;
};
return entries.some((entry) => normalize(entry) === normalize(dir));
}

View File

@@ -1,858 +0,0 @@
/**
* 9D-3: npx waggle CLI Launcher — tests.
*
* Tests argument parsing, version checking, launcher configuration, and the
* packed/installed CLI startup path a user gets from npm.
*/
import { spawn, spawnSync } from 'node:child_process';
import type { ChildProcessWithoutNullStreams } from 'node:child_process';
import fs from 'node:fs';
import http from 'node:http';
import os from 'node:os';
import path from 'node:path';
import { describe, it, expect } from 'vitest';
import {
formatStartupFailure,
formatStartupSuccess,
parseArgs,
} from '../src/cli-core.js';
const ROOT = path.resolve(import.meta.dirname, '..', '..', '..');
const LAUNCHER_DIR = path.join(ROOT, 'packages', 'launcher');
interface CommandResult {
status: number | null;
stdout: string;
stderr: string;
error?: Error;
}
function bin(name: string): string {
return process.platform === 'win32' ? `${name}.cmd` : name;
}
function makeHome(): string {
return fs.mkdtempSync(path.join(os.tmpdir(), 'waggle-launcher-cli-'));
}
function run(
command: string,
args: string[],
home: string,
extraEnv: NodeJS.ProcessEnv = {},
): Promise<CommandResult> {
return runInCwd(command, args, ROOT, home, extraEnv);
}
function runInCwd(
command: string,
args: string[],
cwd: string,
home: string,
extraEnv: NodeJS.ProcessEnv = {},
): Promise<CommandResult> {
return new Promise((resolve) => {
const child = spawn(command, args, {
cwd,
env: {
...process.env,
HOME: home,
USERPROFILE: home,
...extraEnv,
},
stdio: ['ignore', 'pipe', 'pipe'],
shell: process.platform === 'win32' && command.endsWith('.cmd'),
});
let stdout = '';
let stderr = '';
child.stdout.setEncoding('utf8');
child.stderr.setEncoding('utf8');
child.stdout.on('data', (chunk) => { stdout += chunk; });
child.stderr.on('data', (chunk) => { stderr += chunk; });
child.once('error', (error) => resolve({ status: null, stdout, stderr, error }));
child.once('close', (status) => resolve({ status, stdout, stderr }));
});
}
function spawnInCwd(
command: string,
args: string[],
cwd: string,
home: string,
extraEnv: NodeJS.ProcessEnv = {},
): ChildProcessWithoutNullStreams {
return spawn(command, args, {
cwd,
env: {
...process.env,
HOME: home,
USERPROFILE: home,
...extraEnv,
},
stdio: ['ignore', 'pipe', 'pipe'],
shell: process.platform === 'win32' && command.endsWith('.cmd'),
// POSIX: a process group of its own, so stopProcess can stop npx together
// with the waggle process it starts.
detached: process.platform !== 'win32',
});
}
async function occupyPort(): Promise<{
server: http.Server;
port: number;
requestCount: () => number;
bearerRequestCount: () => number;
}> {
let requests = 0;
let bearerRequests = 0;
const server = http.createServer((request, response) => {
requests += 1;
if (request.headers.authorization?.startsWith('Bearer ')) bearerRequests += 1;
response.writeHead(503, { 'content-type': 'application/json' });
response.end('{}');
});
const port = await new Promise<number>((resolve) => {
server.listen(0, '127.0.0.1', () => {
const addr = server.address();
resolve(typeof addr === 'object' && addr ? addr.port : 0);
});
});
return {
server,
port,
requestCount: () => requests,
bearerRequestCount: () => bearerRequests,
};
}
async function freePort(): Promise<number> {
const { server, port } = await occupyPort();
await new Promise<void>((resolve) => server.close(() => resolve()));
return port;
}
async function extractTarball(file: string, cwd: string): Promise<void> {
const tar = await import('tar');
await tar.x({ file, cwd });
}
async function waitFor(
predicate: () => boolean | Promise<boolean>,
timeoutMs: number,
): Promise<void> {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
if (await predicate()) return;
await new Promise((resolve) => setTimeout(resolve, 100));
}
throw new Error(`Timed out after ${timeoutMs}ms`);
}
async function waitForReadyFile(
child: ChildProcessWithoutNullStreams,
readyFile: string,
output: () => { stdout: string; stderr: string },
timeoutMs: number,
): Promise<void> {
try {
await waitFor(
() => fs.existsSync(readyFile) || child.exitCode !== null || child.signalCode !== null,
timeoutMs,
);
} catch (error) {
const { stdout, stderr } = output();
throw new Error(
`${error instanceof Error ? error.message : String(error)} waiting for ${readyFile}`
+ `\nexit=${String(child.exitCode)} signal=${String(child.signalCode)}`
+ `\nstdout:\n${stdout}\nstderr:\n${stderr}`,
);
}
if (!fs.existsSync(readyFile)) {
const { stdout, stderr } = output();
throw new Error(
`Launcher exited before writing ${readyFile}`
+ `\nexit=${String(child.exitCode)} signal=${String(child.signalCode)}`
+ `\nstdout:\n${stdout}\nstderr:\n${stderr}`,
);
}
}
async function waitForHealth(url: string, timeoutMs: number): Promise<Record<string, unknown>> {
let lastError = '';
await waitFor(async () => {
try {
const res = await fetch(url, { signal: AbortSignal.timeout(750) });
if (!res.ok) {
lastError = `HTTP ${res.status}`;
return false;
}
const body = await res.json() as Record<string, unknown>;
if (body.status === 'ok' || body.status === 'degraded') return true;
lastError = `unexpected status ${String(body.status)}`;
return false;
} catch (err) {
lastError = err instanceof Error ? err.message : String(err);
return false;
}
}, timeoutMs).catch((err) => {
throw new Error(`${err instanceof Error ? err.message : String(err)} waiting for ${url}: ${lastError}`);
});
const res = await fetch(url);
return await res.json() as Record<string, unknown>;
}
function processGroupAlive(pid: number): boolean {
try {
process.kill(-pid, 0);
return true;
} catch {
return false;
}
}
async function stopProcess(child: ChildProcessWithoutNullStreams): Promise<void> {
if (!child.pid) return;
if (process.platform === 'win32') {
if (child.exitCode !== null || child.signalCode !== null) return;
spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
await Promise.race([
new Promise<void>((resolve) => child.once('exit', () => resolve())),
new Promise<void>((resolve) => setTimeout(resolve, 5_000)),
]);
return;
}
// npx can exit before the waggle process it started, so signal and wait for
// the whole group rather than the direct child alone.
const group = child.pid;
const signalGroup = (signal: NodeJS.Signals): void => {
try { process.kill(-group, signal); } catch { /* the group is already gone */ }
};
if (!processGroupAlive(group)) return;
signalGroup('SIGTERM');
try {
await waitFor(() => !processGroupAlive(group), 10_000);
} catch {
signalGroup('SIGKILL');
await waitFor(() => !processGroupAlive(group), 5_000);
}
}
async function providerFreeEnv(): Promise<NodeJS.ProcessEnv> {
return {
EMBEDDING_PROVIDER: 'mock',
ANTHROPIC_API_KEY: '',
OPENAI_API_KEY: '',
GEMINI_API_KEY: '',
GOOGLE_API_KEY: '',
XAI_API_KEY: '',
DEEPSEEK_API_KEY: '',
MISTRAL_API_KEY: '',
DASHSCOPE_API_KEY: '',
MINIMAX_API_KEY: '',
ZHIPU_API_KEY: '',
MOONSHOT_API_KEY: '',
PERPLEXITY_API_KEY: '',
OPENROUTER_API_KEY: '',
OLLAMA_HOST: `http://127.0.0.1:${await freePort()}`,
VLLM_HOST: `http://127.0.0.1:${await freePort()}`,
};
}
describe('Waggle CLI Launcher', () => {
describe('argument parsing', () => {
it('uses default port 3333 when no arguments', () => {
const result = parseArgs(['node', 'waggle']);
expect(result.port).toBe(3333);
expect(result.skipLiteLLM).toBe(false);
expect(result.noBrowser).toBe(false);
expect(result.help).toBe(false);
});
it('parses --port flag', () => {
const result = parseArgs(['node', 'waggle', '--port', '4000']);
expect(result.port).toBe(4000);
});
it('parses -p shorthand', () => {
const result = parseArgs(['node', 'waggle', '-p', '8080']);
expect(result.port).toBe(8080);
});
it('rejects invalid port values', () => {
const result = parseArgs(['node', 'waggle', '--port', 'abc']);
expect(result.port).toBe(3333); // default
expect(result.error).toContain('Invalid port');
});
it('rejects out-of-range ports', () => {
const neg = parseArgs(['node', 'waggle', '--port', '-1']);
expect(neg.port).toBe(3333);
expect(neg.error).toContain('Invalid port');
const big = parseArgs(['node', 'waggle', '--port', '99999']);
expect(big.port).toBe(3333);
expect(big.error).toContain('Invalid port');
});
it('rejects missing port values', () => {
const result = parseArgs(['node', 'waggle', '--port']);
expect(result.port).toBe(3333);
expect(result.error).toContain('Missing value');
});
it('rejects unknown options before startup', () => {
const result = parseArgs(['node', 'waggle', '--wat']);
expect(result.error).toContain('Unknown option');
});
it('parses --skip-litellm flag', () => {
const result = parseArgs(['node', 'waggle', '--skip-litellm']);
expect(result.skipLiteLLM).toBe(true);
});
it('parses --no-open flag', () => {
const result = parseArgs(['node', 'waggle', '--no-open']);
expect(result.noBrowser).toBe(true);
});
it('parses --help flag', () => {
const result = parseArgs(['node', 'waggle', '--help']);
expect(result.help).toBe(true);
});
it('parses -h shorthand', () => {
const result = parseArgs(['node', 'waggle', '-h']);
expect(result.help).toBe(true);
});
it('handles multiple flags together', () => {
const result = parseArgs(['node', 'waggle', '--port', '5000', '--skip-litellm', '--no-open']);
expect(result.port).toBe(5000);
expect(result.skipLiteLLM).toBe(true);
expect(result.noBrowser).toBe(true);
});
});
describe('Node.js version check', () => {
it('current Node version meets minimum requirement (>=18)', () => {
const [major] = process.versions.node.split('.').map(Number);
expect(major).toBeGreaterThanOrEqual(18);
});
});
describe('package configuration', () => {
it('package.json has correct bin entry', async () => {
const { readFileSync } = await import('node:fs');
const { resolve } = await import('node:path');
const pkg = JSON.parse(
readFileSync(resolve(import.meta.dirname, '..', 'package.json'), 'utf-8')
);
expect(pkg.name).toBe('@waggle-ai/waggle');
expect(pkg.bin).toBeDefined();
expect(pkg.bin.waggle).toContain('cli');
});
});
describe('startup copy', () => {
it('turns port conflicts into actionable CLI guidance', () => {
const message = formatStartupFailure(
'Port 3333 is already in use. Another Waggle instance may be running.',
3333,
);
expect(message).toContain('Failed to start Waggle');
expect(message).toContain('Port 3333 is already in use');
expect(message).toContain('npx waggle --port 3334');
});
it('explains --no-open success without implying a browser opened', () => {
const message = formatStartupSuccess({
url: 'http://localhost:3333',
llmProvider: 'anthropic-proxy',
llmHealth: 'degraded',
dataDir: 'C:/tmp/waggle',
noBrowser: true,
});
expect(message).toContain('Server: http://localhost:3333');
expect(message).toContain('Browser: not opened (--no-open)');
expect(message).toContain('Open manually: http://localhost:3333');
});
});
describe('runtime help', () => {
it('runs built help without starting service setup', async () => {
const home = makeHome();
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
const result = await run(process.execPath, [path.join(LAUNCHER_DIR, 'dist', 'cli.js'), '--help'], home);
expect(result.status).toBe(0);
expect(result.stdout).toContain('Usage:');
expect(result.stdout).not.toContain('[waggle:service]');
expect(result.stderr).toBe('');
expect(fs.existsSync(path.join(home, '.waggle'))).toBe(false);
} finally {
fs.rmSync(home, { recursive: true, force: true });
}
});
it('runs built invalid-port validation before starting service setup', async () => {
const home = makeHome();
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
const result = await run(process.execPath, [path.join(LAUNCHER_DIR, 'dist', 'cli.js'), '--port', 'abc'], home);
expect(result.status).toBe(1);
expect(result.stderr).toContain('Invalid port: abc');
expect(result.stderr).not.toContain('[waggle:service]');
expect(fs.existsSync(path.join(home, '.waggle'))).toBe(false);
} finally {
fs.rmSync(home, { recursive: true, force: true });
}
});
it('reports occupied ports with a working --port recovery command', async () => {
const home = makeHome();
const { server: blocker, port, requestCount, bearerRequestCount } = await occupyPort();
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
const result = await run(
process.execPath,
[
path.join(LAUNCHER_DIR, 'dist', 'cli.js'),
'--port',
String(port),
'--skip-litellm',
'--no-open',
],
home,
{ WAGGLE_DATA_DIR: path.join(home, 'data') },
);
expect(result.status).toBe(1);
expect(result.stderr).toContain(`Port ${port} is already in use`);
expect(result.stderr).toContain(`npx waggle --port ${port + 1}`);
expect(bearerRequestCount()).toBe(0);
expect(requestCount()).toBe(0);
} finally {
await new Promise<void>((resolve) => blocker.close(() => resolve()));
fs.rmSync(home, { recursive: true, force: true });
}
});
// Windows has no SIGTERM: Node terminates the process outright there.
it.skipIf(process.platform === 'win32')('exits on its own after SIGTERM once the service is ready (UF-041)', async () => {
const home = makeHome();
let child: ChildProcessWithoutNullStreams | undefined;
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
let output = '';
child = spawnInCwd(
process.execPath,
[path.join(LAUNCHER_DIR, 'dist', 'cli.js'), '--port', String(await freePort()), '--skip-litellm', '--no-open'],
ROOT,
home,
{ WAGGLE_DATA_DIR: path.join(home, 'data'), ...await providerFreeEnv() },
);
child.stdout.setEncoding('utf8');
child.stderr.setEncoding('utf8');
child.stdout.on('data', (chunk) => { output += chunk; });
child.stderr.on('data', (chunk) => { output += chunk; });
const exited = new Promise<void>((resolve) => child!.once('exit', () => resolve()));
await waitFor(() => output.includes('Press Ctrl+C to stop') || child!.exitCode !== null, 90_000);
expect(output).toContain('Press Ctrl+C to stop');
child.kill('SIGTERM');
await Promise.race([exited, new Promise<void>((resolve) => setTimeout(resolve, 10_000))]);
expect({ exitCode: child.exitCode, signalCode: child.signalCode }).toEqual({ exitCode: 0, signalCode: null });
} finally {
if (child) await stopProcess(child);
fs.rmSync(home, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
}
}, 120_000);
it('packs a tarball with a runnable first command', async () => {
const home = makeHome();
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
const pack = await run(
bin('npm'),
['pack', '--workspace', '@waggle-ai/waggle', '--pack-destination', home, '--json'],
home,
);
expect(pack.status).toBe(0);
const [packResult] = JSON.parse(pack.stdout) as Array<{ filename: string }>;
const tarball = path.join(home, packResult.filename);
const extractDir = path.join(home, 'packed');
fs.mkdirSync(extractDir, { recursive: true });
await extractTarball(tarball, extractDir);
const pkg = JSON.parse(
fs.readFileSync(path.join(extractDir, 'package', 'package.json'), 'utf8'),
);
const distFiles = fs.readdirSync(path.join(extractDir, 'package', 'dist'));
const result = await run(
process.execPath,
[path.join(extractDir, 'package', 'dist', 'cli.js'), '--help'],
home,
);
expect(pkg.bin.waggle).toBe('./dist/cli.js');
expect({
transformersDependency: pkg.dependencies?.['@huggingface/transformers'],
bundledNativeBindings: distFiles.filter((file) => /^onnxruntime_binding-.*\.node$/.test(file)),
bundledTransformersRuntime: distFiles.filter((file) => /^transformers\.node-.*\.js$/.test(file)),
}).toEqual({
transformersDependency: '3.8.1',
bundledNativeBindings: [],
bundledTransformersRuntime: [],
});
expect(result.status).toBe(0);
expect(result.stdout).toContain('Usage:');
expect(result.stdout).not.toContain('[waggle:service]');
expect(result.stderr).toBe('');
expect(fs.existsSync(path.join(home, '.waggle'))).toBe(false);
} finally {
fs.rmSync(home, { recursive: true, force: true });
}
}, 120_000);
it('installs the packed launcher and runs npx help plus startup recovery', async () => {
const home = makeHome();
const { server: blocker, port, requestCount, bearerRequestCount } = await occupyPort();
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
const pack = await run(
bin('npm'),
['pack', '--workspace', '@waggle-ai/waggle', '--pack-destination', home, '--json'],
home,
);
expect(pack.status).toBe(0);
const [packResult] = JSON.parse(pack.stdout) as Array<{ filename: string }>;
const projectDir = path.join(home, 'project');
fs.mkdirSync(projectDir, { recursive: true });
fs.writeFileSync(
path.join(projectDir, 'package.json'),
JSON.stringify({ private: true, type: 'module' }, null, 2),
);
const install = await runInCwd(
bin('npm'),
[
'install',
path.join(home, packResult.filename),
'--no-audit',
'--no-fund',
'--prefer-offline',
],
projectDir,
home,
);
expect(install.status).toBe(0);
const nativeEmbeddingRuntime = await runInCwd(
process.execPath,
[
'--input-type=module',
'--eval',
"const runtime = await import('@huggingface/transformers'); if (typeof runtime.pipeline !== 'function') throw new Error('Transformers pipeline API is unavailable');",
],
projectDir,
home,
);
expect(nativeEmbeddingRuntime.status).toBe(0);
expect(nativeEmbeddingRuntime.stderr).toBe('');
const help = await runInCwd(bin('npx'), ['waggle', '--help'], projectDir, home);
expect(help.status).toBe(0);
expect(help.stdout).toContain('Usage:');
expect(help.stdout).not.toContain('[waggle:service]');
expect(help.stderr).toBe('');
expect(fs.existsSync(path.join(home, '.waggle'))).toBe(false);
const startup = await runInCwd(
bin('npx'),
['waggle', '--port', String(port), '--skip-litellm', '--no-open'],
projectDir,
home,
{ WAGGLE_DATA_DIR: path.join(home, 'data') },
);
expect(startup.status).toBe(1);
expect(startup.stderr).toContain(`Port ${port} is already in use`);
expect(startup.stderr).toContain(`npx waggle --port ${port + 1}`);
expect(fs.existsSync(path.join(home, '.waggle'))).toBe(false);
expect(bearerRequestCount()).toBe(0);
expect(requestCount()).toBe(0);
} finally {
await new Promise<void>((resolve) => blocker.close(() => resolve()));
fs.rmSync(home, { recursive: true, force: true });
}
}, 240_000);
it('starts the installed launcher, isolates concurrent histories, and reloads them after restart', async () => {
const home = makeHome();
const {
server: blocker,
port: preferredPort,
requestCount,
bearerRequestCount,
} = await occupyPort();
let child: ChildProcessWithoutNullStreams | undefined;
try {
const build = await run(bin('npm'), ['run', 'build', '--workspace', '@waggle-ai/waggle'], home);
expect(build.status).toBe(0);
const pack = await run(
bin('npm'),
['pack', '--workspace', '@waggle-ai/waggle', '--pack-destination', home, '--json'],
home,
);
expect(pack.status).toBe(0);
const [packResult] = JSON.parse(pack.stdout) as Array<{ filename: string }>;
const projectDir = path.join(home, 'project');
fs.mkdirSync(projectDir, { recursive: true });
fs.writeFileSync(
path.join(projectDir, 'package.json'),
JSON.stringify({ private: true, type: 'module' }, null, 2),
);
const install = await runInCwd(
bin('npm'),
[
'install',
path.join(home, packResult.filename),
'--no-audit',
'--no-fund',
'--prefer-offline',
],
projectDir,
home,
);
expect(install.status).toBe(0);
const dataDir = path.join(home, 'data');
const readyFile = path.join(home, 'desktop-ready.json');
const restartReadyFile = path.join(home, 'desktop-ready-restart.json');
const desktopBootstrapToken = 'launcher-desktop-bootstrap-token-1234567890';
const providerEnv = await providerFreeEnv();
let stdout = '';
let stderr = '';
child = spawnInCwd(
bin('npx'),
['waggle', '--port', String(preferredPort), '--skip-litellm', '--no-open'],
projectDir,
home,
{
WAGGLE_DATA_DIR: dataDir,
WAGGLE_DESKTOP_PORT_FALLBACK: '1',
WAGGLE_INSTANCE_ID: 'launcher-fallback-health',
WAGGLE_DESKTOP_BOOTSTRAP_TOKEN: desktopBootstrapToken,
WAGGLE_READY_FILE: readyFile,
...providerEnv,
},
);
child.stdout.setEncoding('utf8');
child.stderr.setEncoding('utf8');
child.stdout.on('data', (chunk) => { stdout += chunk; });
child.stderr.on('data', (chunk) => { stderr += chunk; });
await waitForReadyFile(child, readyFile, () => ({ stdout, stderr }), 90_000);
const ready = JSON.parse(fs.readFileSync(readyFile, 'utf8')) as {
preferredPort: number;
port: number;
};
expect(ready.preferredPort).toBe(preferredPort);
expect(ready.port).not.toBe(preferredPort);
const baseUrl = `http://127.0.0.1:${ready.port}`;
const health = await waitForHealth(`${baseUrl}/health`, 30_000);
await waitFor(() => stdout.includes('Press Ctrl+C to stop'), 10_000);
expect(health.database).toMatchObject({ healthy: true });
expect(stdout).toContain(`Server: http://localhost:${ready.port}`);
expect(stdout).toContain('Browser: not opened (--no-open)');
expect(stdout).toContain(`Open manually: http://localhost:${ready.port}`);
expect(stderr).not.toContain('Failed to start Waggle');
expect(fs.existsSync(path.join(dataDir, 'waggle.db'))).toBe(true);
expect(fs.existsSync(path.join(dataDir, 'memory'))).toBe(true);
expect(fs.existsSync(path.join(dataDir, 'personal.mind'))).toBe(false);
expect(bearerRequestCount()).toBe(0);
expect(requestCount()).toBe(0);
const tokenResponse = await fetch(`${baseUrl}/api/auth/session-token`, {
headers: { 'x-waggle-desktop-bootstrap': desktopBootstrapToken },
});
expect(tokenResponse.status).toBe(200);
const token = (await tokenResponse.json() as { token?: string }).token;
if (!token) throw new Error('Installed launcher returned no session token');
const headers = {
authorization: `Bearer ${token}`,
'content-type': 'application/json',
};
const workspaceResponse = await fetch(`${baseUrl}/api/workspaces`, {
method: 'POST',
headers,
body: JSON.stringify({ name: 'Packed launcher concurrent history', group: 'Test' }),
});
expect(workspaceResponse.status).toBe(201);
const workspaceId = (await workspaceResponse.json() as { id?: string }).id;
if (!workspaceId) throw new Error('Installed launcher returned no workspace id');
const sessionA = 'packed-concurrent-a';
const sessionB = 'packed-concurrent-b';
const markerA = 'PACKED_CONCURRENT_SESSION_A';
const markerB = 'PACKED_CONCURRENT_SESSION_B';
const [chatA, chatB] = await Promise.all([
fetch(`${baseUrl}/api/chat`, {
method: 'POST',
headers,
body: JSON.stringify({ message: markerA, workspace: workspaceId, session: sessionA }),
}),
fetch(`${baseUrl}/api/chat`, {
method: 'POST',
headers,
body: JSON.stringify({ message: markerB, workspace: workspaceId, session: sessionB }),
}),
]);
const [chatBodyA, chatBodyB] = await Promise.all([chatA.text(), chatB.text()]);
for (const [response, body] of [[chatA, chatBodyA], [chatB, chatBodyB]] as const) {
expect(response.status).toBe(200);
expect(response.headers.get('content-type')).toMatch(/^text\/event-stream/);
expect(body.match(/^event:\s*done\s*$/gm)).toHaveLength(1);
expect(body.match(/^event:\s*error\s*$/gm) ?? []).toHaveLength(0);
expect(body).toContain('No AI model is ready');
}
for (const sessionId of [sessionA, sessionB]) {
expect(fs.existsSync(path.join(
dataDir,
'workspaces',
workspaceId,
'sessions',
`${sessionId}.jsonl`,
))).toBe(true);
}
await stopProcess(child);
child = undefined;
let restartStdout = '';
let restartStderr = '';
child = spawnInCwd(
bin('npx'),
['waggle', '--port', String(preferredPort), '--skip-litellm', '--no-open'],
projectDir,
home,
{
WAGGLE_DATA_DIR: dataDir,
WAGGLE_DESKTOP_PORT_FALLBACK: '1',
WAGGLE_INSTANCE_ID: 'launcher-fallback-history-restart',
WAGGLE_DESKTOP_BOOTSTRAP_TOKEN: desktopBootstrapToken,
WAGGLE_READY_FILE: restartReadyFile,
...providerEnv,
},
);
child.stdout.setEncoding('utf8');
child.stderr.setEncoding('utf8');
child.stdout.on('data', (chunk) => { restartStdout += chunk; });
child.stderr.on('data', (chunk) => { restartStderr += chunk; });
await waitForReadyFile(
child,
restartReadyFile,
() => ({ stdout: restartStdout, stderr: restartStderr }),
90_000,
);
const restartReady = JSON.parse(fs.readFileSync(restartReadyFile, 'utf8')) as {
preferredPort: number;
port: number;
};
expect(restartReady.preferredPort).toBe(preferredPort);
expect(restartReady.port).not.toBe(preferredPort);
const restartBaseUrl = `http://127.0.0.1:${restartReady.port}`;
const restartHealth = await waitForHealth(`${restartBaseUrl}/health`, 30_000);
await waitFor(() => restartStdout.includes('Press Ctrl+C to stop'), 10_000);
expect(restartHealth.database).toMatchObject({ healthy: true });
expect(restartStderr).not.toContain('Failed to start Waggle');
const restartTokenResponse = await fetch(`${restartBaseUrl}/api/auth/session-token`, {
headers: { 'x-waggle-desktop-bootstrap': desktopBootstrapToken },
});
expect(restartTokenResponse.status).toBe(200);
const restartToken = (await restartTokenResponse.json() as { token?: string }).token;
if (!restartToken) throw new Error('Restarted launcher returned no session token');
const restartHeaders = { authorization: `Bearer ${restartToken}` };
const [historyResponseA, historyResponseB] = await Promise.all([
fetch(
`${restartBaseUrl}/api/history?workspace=${encodeURIComponent(workspaceId)}&session=${encodeURIComponent(sessionA)}`,
{ headers: restartHeaders },
),
fetch(
`${restartBaseUrl}/api/history?workspace=${encodeURIComponent(workspaceId)}&session=${encodeURIComponent(sessionB)}`,
{ headers: restartHeaders },
),
]);
expect(historyResponseA.status).toBe(200);
expect(historyResponseB.status).toBe(200);
const [historyA, historyB] = await Promise.all([
historyResponseA.json(),
historyResponseB.json(),
]) as Array<{
sessionId: string;
count: number;
messages: Array<{ role: string; content: string }>;
}>;
expect(historyA.sessionId).toBe(sessionA);
expect(historyB.sessionId).toBe(sessionB);
expect(historyA.count).toBe(2);
expect(historyB.count).toBe(2);
expect(historyA.messages).toEqual([
expect.objectContaining({ role: 'user', content: markerA }),
expect.objectContaining({ role: 'assistant', content: expect.stringContaining('No AI model is ready') }),
]);
expect(historyB.messages).toEqual([
expect.objectContaining({ role: 'user', content: markerB }),
expect.objectContaining({ role: 'assistant', content: expect.stringContaining('No AI model is ready') }),
]);
expect(historyA.messages.some(({ content }) => content.includes(markerB))).toBe(false);
expect(historyB.messages.some(({ content }) => content.includes(markerA))).toBe(false);
expect(bearerRequestCount()).toBe(0);
expect(requestCount()).toBe(0);
} finally {
if (child) await stopProcess(child);
await new Promise<void>((resolve) => blocker.close(() => resolve()));
// Windows can release SQLite WAL/SHM handles a few milliseconds after
// taskkill reports success; retry the isolated temp-home cleanup.
fs.rmSync(home, {
recursive: true,
force: true,
maxRetries: 10,
retryDelay: 100,
});
}
}, 360_000);
});
});

View File

@@ -0,0 +1,269 @@
/**
* The installer: argument parsing, per-system paths, the server environment,
* and install / update / uninstall against an archive packed by
* scripts/build-server-archive.mjs.
*/
import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterEach, describe, expect, it } from 'vitest';
import { DEFAULT_PORT, parseArgs } from '../src/args.js';
import { UserError, doctor, install, uninstall, type Context } from '../src/commands.js';
import {
assetName,
currentHost,
defaultBinDir,
defaultDataDir,
defaultInstallDir,
isOnPath,
releaseTarget,
type Host,
} from '../src/platform.js';
import { layoutFor, parseChecksum, readRecord, serviceEnvironment, shimContent, shimFile } from '../src/payload.js';
const ROOT = path.resolve(import.meta.dirname, '..', '..', '..');
const VERSION = (JSON.parse(fs.readFileSync(path.join(ROOT, 'packages', 'launcher', 'package.json'), 'utf8')) as {
version: string;
}).version;
const temps: string[] = [];
function tempDir(prefix: string): string {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
temps.push(dir);
return dir;
}
afterEach(() => {
for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
});
function host(platform: NodeJS.Platform, env: NodeJS.ProcessEnv = {}): Host {
return { platform, arch: 'x64', homedir: platform === 'win32' ? 'C:\\Users\\ana' : '/home/ana', env };
}
describe('parseArgs', () => {
it('runs the server when no command is given', () => {
expect(parseArgs([])).toEqual({ command: 'run', options: { port: DEFAULT_PORT, open: true, force: false } });
});
it('reads a command and its options', () => {
const parsed = parseArgs(['install', '--from', 'a.tar.gz', '--dir', '/opt/w', '--port', '4000', '--no-open', '--force']);
expect(parsed.error).toBeUndefined();
expect(parsed.command).toBe('install');
expect(parsed.options).toMatchObject({ from: 'a.tar.gz', dir: '/opt/w', port: 4000, open: false, force: true });
});
it('rejects bad ports, unknown words and malformed checksums', () => {
expect(parseArgs(['--port', '70000']).error).toMatch(/Invalid port/);
expect(parseArgs(['--port']).error).toMatch(/Invalid port/);
expect(parseArgs(['instal']).error).toMatch(/Unknown command/);
expect(parseArgs(['--fast']).error).toMatch(/Unknown option/);
expect(parseArgs(['install', '--from']).error).toMatch(/Missing value/);
expect(parseArgs(['install', '--sha256', 'abc']).error).toMatch(/64-character/);
});
it('treats --help and --version as commands', () => {
expect(parseArgs(['--help']).command).toBe('help');
expect(parseArgs(['-v']).command).toBe('version');
});
});
describe('platform paths', () => {
it('maps v1 systems to release targets and names the asset', () => {
expect(releaseTarget({ platform: 'win32', arch: 'x64' })).toBe('windows-x64');
expect(releaseTarget({ platform: 'darwin', arch: 'arm64' })).toBe('macos-arm64');
expect(releaseTarget({ platform: 'darwin', arch: 'x64' })).toBe('macos-x64');
expect(releaseTarget({ platform: 'linux', arch: 'x64' })).toBe('linux-x64');
expect(releaseTarget({ platform: 'linux', arch: 'arm64' })).toBeNull();
expect(assetName('1.2.3', 'linux-x64')).toBe('waggle-server-1.2.3-linux-x64.tar.gz');
});
it('installs into the per-user program directory of each system', () => {
expect(defaultInstallDir(host('win32', { LOCALAPPDATA: 'C:\\Users\\ana\\AppData\\Local' })))
.toBe('C:\\Users\\ana\\AppData\\Local\\Waggle\\server');
expect(defaultInstallDir(host('darwin'))).toBe('/home/ana/Library/Application Support/Waggle/server');
expect(defaultInstallDir(host('linux'))).toBe('/home/ana/.local/share/waggle/server');
expect(defaultInstallDir(host('linux', { XDG_DATA_HOME: '/data' }))).toBe('/data/waggle/server');
});
it('keeps the Windows shim inside the install and uses ~/.local/bin elsewhere', () => {
expect(defaultBinDir(host('win32'), 'C:\\W\\server')).toBe('C:\\W\\server\\bin');
expect(defaultBinDir(host('linux'), '/x')).toBe('/home/ana/.local/bin');
});
it('follows the sidecar data directory rule', () => {
expect(defaultDataDir(host('linux'))).toBe('/home/ana/.waggle');
expect(defaultDataDir(host('linux', { WAGGLE_DATA_DIR: '/srv/waggle' }))).toBe('/srv/waggle');
});
it('finds a directory on PATH, ignoring case on Windows', () => {
expect(isOnPath(host('linux', { PATH: '/usr/bin:/home/ana/.local/bin' }), '/home/ana/.local/bin')).toBe(true);
expect(isOnPath(host('linux', { PATH: '/usr/bin' }), '/home/ana/.local/bin')).toBe(false);
expect(isOnPath(host('win32', { Path: 'C:\\Windows;c:\\w\\BIN' }), 'C:\\W\\bin')).toBe(true);
});
});
describe('payload helpers', () => {
it('gives the server the environment the desktop shell gives it', () => {
const env = serviceEnvironment({
appDir: '/opt/w/app',
dataDir: '/home/ana/.waggle',
port: 4000,
platform: 'linux',
baseEnv: { PATH: '/usr/bin', WAGGLE_DATA_DIR: '/stale' },
explicitDataDir: false,
});
expect(env).toMatchObject({
WAGGLE_SKIP_LITELLM: '1',
WAGGLE_PORT: '4000',
WAGGLE_FRONTEND_DIR: '/opt/w/app/web',
NODE_PATH: '/opt/w/app/node_modules:/opt/w/app/native',
PATH: '/opt/w/app/node_modules/waggle-node-runtime/bin:/opt/w/app:/usr/bin',
NPM_CONFIG_PREFIX: '/home/ana/.waggle/npm/prefix',
NPM_CONFIG_CACHE: '/home/ana/.waggle/npm/cache',
});
expect(env.WAGGLE_DATA_DIR).toBeUndefined();
const windows = serviceEnvironment({
appDir: 'C:\\W\\app',
dataDir: 'D:\\data',
port: 3333,
platform: 'win32',
baseEnv: { Path: 'C:\\Windows' },
explicitDataDir: true,
});
expect(windows.Path).toBeUndefined();
expect(windows.PATH).toBe('C:\\W\\app\\node_modules\\waggle-node-runtime\\bin;C:\\W\\app;C:\\Windows');
expect(windows.WAGGLE_DATA_DIR).toBe('D:\\data');
});
it('writes shims that run the copied tool with the payload Node', () => {
const unix = layoutFor("/home/ana/it's/server", 'linux');
expect(shimContent(unix, 'linux')).toBe(
"#!/bin/sh\nexec '/home/ana/it'\\''s/server/app/node' '/home/ana/it'\\''s/server/launcher.mjs' \"$@\"\n",
);
const windows = layoutFor('C:\\W\\server', 'win32');
expect(shimContent(windows, 'win32')).toBe('@echo off\r\n"C:\\W\\server\\app\\node.exe" "C:\\W\\server\\launcher.mjs" %*\r\n');
expect(shimFile('C:\\W\\bin', 'waggle-server', 'win32')).toBe('C:\\W\\bin\\waggle-server.cmd');
});
it('reads sha256sum lines and bare digests', () => {
const digest = 'A'.repeat(64);
expect(parseChecksum(`${digest} waggle.tar.gz\n`)).toBe('a'.repeat(64));
expect(parseChecksum(digest)).toBe('a'.repeat(64));
expect(parseChecksum('not a digest')).toBeNull();
});
});
const target = releaseTarget(currentHost());
describe.skipIf(!target)('install, update and uninstall from a packed archive', () => {
function packArchive(): string {
const work = tempDir('waggle-archive-');
const resources = path.join(work, 'resources');
const web = path.join(work, 'web');
fs.mkdirSync(path.join(resources, 'node_modules', 'better-sqlite3'), { recursive: true });
fs.mkdirSync(path.join(resources, 'native'), { recursive: true });
fs.mkdirSync(web, { recursive: true });
fs.writeFileSync(path.join(resources, process.platform === 'win32' ? 'node.exe' : 'node'), 'not a real runtime');
fs.writeFileSync(path.join(resources, 'service.js'), 'console.log("service");\n');
fs.writeFileSync(path.join(resources, 'service.js.map'), '{}');
fs.writeFileSync(path.join(web, 'index.html'), '<!doctype html>');
const out = path.join(work, 'out');
const result = spawnSync(
process.execPath,
[
path.join(ROOT, 'scripts', 'build-server-archive.mjs'),
'--resources', resources, '--web', web, '--out', out, '--node-version', '22.0.0',
],
{ encoding: 'utf8' },
);
expect(result.status, result.stderr).toBe(0);
return path.join(out, assetName(VERSION, target!));
}
function context(lines: string[]): Context {
const launcher = path.join(tempDir('waggle-tool-'), 'cli.js');
fs.writeFileSync(launcher, '// bundled tool\n');
return { host: currentHost(), version: VERSION, launcherSource: launcher, out: (line) => lines.push(line) };
}
it('installs, reinstalls on request and removes the program but not the data', async () => {
const archive = packArchive();
const dir = path.join(tempDir('waggle-install-'), 'server');
const binDir = tempDir('waggle-bin-');
const dataDir = tempDir('waggle-data-');
fs.writeFileSync(path.join(dataDir, 'waggle.db'), 'user data');
const lines: string[] = [];
const ctx = context(lines);
const opts = { ...parseArgs([]).options, from: archive, dir, binDir, dataDir };
await install(ctx, opts);
const layout = layoutFor(dir, process.platform);
expect(fs.readFileSync(path.join(layout.appDir, 'service.js'), 'utf8')).toContain('service');
expect(fs.existsSync(path.join(layout.appDir, 'web', 'index.html'))).toBe(true);
expect(fs.existsSync(path.join(layout.appDir, 'service.js.map'))).toBe(false);
expect(fs.readFileSync(layout.launcherFile, 'utf8')).toBe('// bundled tool\n');
const record = readRecord(layout);
expect(record).toMatchObject({ version: VERSION, target, source: archive });
expect(record?.sha256).toBe(parseChecksum(fs.readFileSync(`${archive}.sha256`, 'utf8')));
const shim = shimFile(binDir, 'waggle-server', process.platform);
expect(fs.readFileSync(shim, 'utf8')).toContain(layout.launcherFile);
expect(record?.shim).toBe(shim);
lines.length = 0;
await install(ctx, { ...opts, from: undefined });
expect(lines.join('\n')).toMatch(/already installed/);
await install(ctx, { ...opts, force: true });
expect(fs.existsSync(path.join(dir, 'app.old'))).toBe(false);
expect(fs.existsSync(path.join(dir, 'app.new'))).toBe(false);
// The recorded shim is found without --bin-dir.
expect(await uninstall(ctx, { ...opts, binDir: undefined })).toBe(0);
expect(fs.existsSync(dir)).toBe(false);
expect(fs.existsSync(shim)).toBe(false);
expect(fs.readFileSync(path.join(dataDir, 'waggle.db'), 'utf8')).toBe('user data');
});
it('refuses an archive whose checksum does not match and keeps the installed one', async () => {
const archive = packArchive();
const dir = path.join(tempDir('waggle-install-'), 'server');
const ctx = context([]);
const opts = { ...parseArgs([]).options, from: archive, dir, binDir: tempDir('waggle-bin-') };
await install(ctx, opts);
await expect(install(ctx, { ...opts, force: true, sha256: 'b'.repeat(64) })).rejects.toThrow(UserError);
expect(fs.existsSync(path.join(dir, 'app', 'service.js'))).toBe(true);
expect(fs.existsSync(path.join(dir, 'app.new'))).toBe(false);
});
it('reports a runtime that does not start', async () => {
const archive = packArchive();
const dir = path.join(tempDir('waggle-install-'), 'server');
const lines: string[] = [];
const ctx = context(lines);
const opts = {
...parseArgs([]).options,
from: archive,
dir,
binDir: tempDir('waggle-bin-'),
dataDir: tempDir('waggle-data-'),
port: 1,
};
await install(ctx, opts);
lines.length = 0;
expect(await doctor(ctx, opts)).toBe(1);
const report = lines.join('\n');
expect(report).toMatch(/ok +Install: version/);
expect(report).toMatch(/FAIL +Node runtime: does not start/);
});
it('removes nothing from a directory that is not an install', async () => {
const dir = tempDir('waggle-not-install-');
fs.writeFileSync(path.join(dir, 'keep.txt'), 'mine');
await expect(uninstall(context([]), { ...parseArgs([]).options, dir })).rejects.toThrow(/not a Waggle server install/);
expect(fs.readFileSync(path.join(dir, 'keep.txt'), 'utf8')).toBe('mine');
});
});

View File

@@ -1,30 +1,22 @@
import fs from 'node:fs';
import { defineConfig } from 'tsup';
const { version } = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')) as {
version: string;
};
export default defineConfig({
entry: ['src/cli.ts'],
format: ['esm'],
target: 'node18',
target: 'node20',
clean: true,
shims: true,
// One self-contained file: install copies it next to the payload, where no
// node_modules exist. The tool only uses Node's built-in modules.
noExternal: [/.*/],
define: {
__WAGGLE_SERVER_VERSION__: JSON.stringify(version),
},
banner: {
js: '#!/usr/bin/env node',
},
// Inline all @waggle/* workspace packages into the bundle.
// Third-party npm packages stay external (installed as dependencies).
noExternal: [/^@waggle\//],
// Build the workspace packages from their source export, not a stale dist/.
esbuildOptions(options) {
options.conditions = ['source'];
},
// Runtime packages that cannot be bundled safely.
external: [
'@huggingface/transformers',
'onnxruntime-node',
'adm-zip',
'playwright-core',
'chromium-bidi',
// mem0 loads a client for each provider it supports on demand; those are
// optional peers Waggle does not install (see scripts/build-sidecar.mjs).
'mem0ai',
],
});

View File

@@ -809,7 +809,9 @@ describe('Tauri Production Configuration', () => {
sharp: '0.35.3',
});
const fastifyStaticRanges = ['launcher', 'server'].map((workspace) => {
// The installer (packages/launcher) ships no server dependencies: it
// downloads the staged sidecar payload instead.
const fastifyStaticRanges = ['server'].map((workspace) => {
const workspaceManifest = JSON.parse(fs.readFileSync(
path.join(ROOT, 'packages', workspace, 'package.json'),
'utf-8',
@@ -820,7 +822,6 @@ describe('Tauri Production Configuration', () => {
const betterSqliteRanges = [
'core',
'launcher',
'marketplace',
'server',
].map((workspace) => {

View File

@@ -0,0 +1,122 @@
#!/usr/bin/env node
/**
* Pack the server archive that the installer (packages/launcher) downloads.
*
* The archive holds the same sidecar payload the desktop app ships, staged by
* bundle-node, build-sidecar, bundle-native-deps and stage-sidecar-deps into
* app/src-tauri/resources, plus the built web UI under web/ and a
* manifest.json. Run it after those steps and the web build, on the system
* the archive is for.
*
* Usage:
* node scripts/build-server-archive.mjs [--resources DIR] [--web DIR] [--out DIR]
* [--target TARGET] [--node-version X.Y.Z]
*
* Writes <out>/waggle-server-<version>-<target>.tar.gz and a .sha256 next to it.
* The version is the installer's (packages/launcher/package.json): the
* installer of version X downloads the archive of version X.
*/
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
// Keep in step with releaseTarget() and assetName() in packages/launcher/src/platform.ts.
const TARGETS = {
'win32-x64': 'windows-x64',
'darwin-arm64': 'macos-arm64',
'darwin-x64': 'macos-x64',
'linux-x64': 'linux-x64',
};
function parseArgs(argv) {
const options = {
resources: path.join(root, 'app', 'src-tauri', 'resources'),
web: path.join(root, 'apps', 'web', 'dist'),
out: path.join(root, 'artifacts'),
target: TARGETS[`${process.platform}-${process.env.TARGET_ARCH || process.arch}`],
nodeVersion: null,
};
const flags = { '--resources': 'resources', '--web': 'web', '--out': 'out', '--target': 'target', '--node-version': 'nodeVersion' };
for (let i = 0; i < argv.length; i++) {
const key = flags[argv[i]];
if (!key || argv[i + 1] === undefined) throw new Error(`Unknown or incomplete option: ${argv[i]}`);
options[key] = key === 'target' || key === 'nodeVersion' ? argv[++i] : path.resolve(argv[++i]);
}
if (!options.target || !Object.values(TARGETS).includes(options.target)) {
throw new Error(`No release target for ${process.platform}-${process.env.TARGET_ARCH || process.arch}; pass --target`);
}
return options;
}
function requireFile(file, hint) {
if (!fs.existsSync(file)) throw new Error(`${path.relative(root, file) || file} is missing. ${hint}`);
}
function sha256(file) {
const hash = createHash('sha256');
const fd = fs.openSync(file, 'r');
try {
const buffer = Buffer.alloc(1024 * 1024);
let read;
while ((read = fs.readSync(fd, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, read));
} finally {
fs.closeSync(fd);
}
return hash.digest('hex');
}
try {
const options = parseArgs(process.argv.slice(2));
const { version } = JSON.parse(fs.readFileSync(path.join(root, 'packages', 'launcher', 'package.json'), 'utf8'));
const nodeName = options.target.startsWith('windows-') ? 'node.exe' : 'node';
const stageHint = 'Run the desktop staging steps first (see the tauri:build scripts in app/package.json).';
requireFile(path.join(options.resources, nodeName), stageHint);
requireFile(path.join(options.resources, 'service.js'), stageHint);
requireFile(path.join(options.resources, 'node_modules'), stageHint);
requireFile(path.join(options.web, 'index.html'), 'Build the web UI first: cd apps/web && npx vite build');
let nodeVersion = options.nodeVersion;
if (!nodeVersion) {
const probe = spawnSync(path.join(options.resources, nodeName), ['-p', 'process.versions.node'], { encoding: 'utf8' });
if (probe.status !== 0) throw new Error(`Could not run the bundled Node to read its version; pass --node-version`);
nodeVersion = probe.stdout.trim();
}
const name = `waggle-server-${version}-${options.target}`;
const stage = fs.mkdtempSync(path.join(os.tmpdir(), `${name}-`));
try {
console.log(`[server-archive] Staging ${name}`);
fs.cpSync(options.resources, stage, {
recursive: true,
verbatimSymlinks: true,
filter: (source) => !source.endsWith('.map'),
});
fs.cpSync(options.web, path.join(stage, 'web'), { recursive: true, verbatimSymlinks: true });
fs.writeFileSync(
path.join(stage, 'manifest.json'),
`${JSON.stringify({ name: 'waggle-server', version, target: options.target, node: nodeVersion }, null, 2)}\n`,
);
fs.mkdirSync(options.out, { recursive: true });
const archive = path.join(options.out, `${name}.tar.gz`);
fs.rmSync(archive, { force: true });
console.log(`[server-archive] Packing ${path.relative(root, archive) || archive}`);
const tar = spawnSync('tar', ['-czf', archive, '-C', stage, '.'], { stdio: 'inherit' });
if (tar.status !== 0) throw new Error(`tar failed with exit code ${tar.status}`);
const digest = sha256(archive);
fs.writeFileSync(`${archive}.sha256`, `${digest} ${path.basename(archive)}\n`);
const sizeMB = (fs.statSync(archive).size / 1024 / 1024).toFixed(1);
console.log(`[server-archive] Done: ${sizeMB} MB, sha256 ${digest}`);
} finally {
fs.rmSync(stage, { recursive: true, force: true });
}
} catch (error) {
console.error(`[server-archive] ${error instanceof Error ? error.message : String(error)}`);
process.exit(1);
}

View File

@@ -1,320 +0,0 @@
#!/usr/bin/env bash
#
# waggle-server.sh — process manager for the Waggle OS solo sidecar.
#
# WHY THIS EXISTS (steal #5, installer arc 2026-07-10):
# The one-line installer (install.sh) needs a small, dependency-free way to
# start/stop/inspect the headless sidecar on a VPS or homelab box. The sidecar
# is packages/server/src/local/start.ts — it defaults to port 3333, binds
# loopback, serves /health, and writes its own PID to <dataDir>/server.pid.
# This wrapper drives it with nohup + that PID file. No ps|grep, no systemd.
#
# COMMANDS:
# start launch the sidecar in the background, wait for /health, print URL
# stop TERM the recorded PID, 3s grace, then KILL; confirm via /health
# status report running/stopped + the /health provider line
# logs follow the sidecar log (Ctrl-C to exit)
#
# FLAGS:
# --port N listen port (default: $WAGGLE_PORT or 3333)
# --data-dir P data directory (default: $WAGGLE_DATA_DIR or ~/.waggle)
#
# The sidecar runs with WAGGLE_SKIP_LITELLM=1 (no optional Python LiteLLM
# subprocess) and, when a built web UI exists at <repo>/dist, WAGGLE_FRONTEND_DIR
# pointed at it. Zero API keys required — the built-in echo provider keeps the UI
# functional until a key is added in Settings.
set -euo pipefail
# ── Locate the installed tree (this script lives at <repo>/scripts/) ──────────
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
DEFAULT_PORT=3333
# ── Defaults (env first, flags override below) ────────────────────────────────
PORT="${WAGGLE_PORT:-$DEFAULT_PORT}"
DATA_DIR="${WAGGLE_DATA_DIR:-$HOME/.waggle}"
usage() {
cat <<EOF
Usage: waggle-server.sh <start|stop|status|logs> [--port N] [--data-dir P]
start Start the sidecar in the background and wait for it to become healthy.
stop Stop the running sidecar (TERM, then KILL after 3s).
status Show whether the sidecar is running and its LLM provider health.
logs Follow the sidecar log file.
Defaults: --port ${DEFAULT_PORT} --data-dir ~/.waggle
Env: WAGGLE_PORT, WAGGLE_DATA_DIR
EOF
}
# ── Arg parsing ───────────────────────────────────────────────────────────────
# True when $1 is a decimal integer within the valid TCP port range (1-65535).
valid_port() {
case "$1" in
''|*[!0-9]*) return 1 ;;
esac
[ "$1" -ge 1 ] && [ "$1" -le 65535 ]
}
CMD="${1:-}"
shift || true
while [ $# -gt 0 ]; do
case "$1" in
--port) PORT="${2:?--port needs a value}"; shift 2 ;;
--port=*) PORT="${1#*=}"; shift ;;
--data-dir) DATA_DIR="${2:?--data-dir needs a value}"; shift 2 ;;
--data-dir=*) DATA_DIR="${1#*=}"; shift ;;
-h|--help) usage; exit 0 ;;
*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
esac
done
valid_port "$PORT" || { echo "Error: invalid --port '${PORT}': must be an integer between 1 and 65535." >&2; exit 2; }
PIDFILE="$DATA_DIR/server.pid"
LOGFILE="$DATA_DIR/server.log"
HEALTH_URL="http://127.0.0.1:${PORT}/health"
# ── Helpers ───────────────────────────────────────────────────────────────────
#
# Liveness model: /health is the OS-agnostic source of truth for "is the server
# up?". The recorded PID is only needed to *signal* the process on stop. We
# never delete a pidfile just because a liveness probe said "no" — a POSIX
# `kill -0` returns false for a native Windows PID under msys/Git Bash even
# while the process is very much alive, and treating that false negative as
# "stale" would orphan a running server. So pid_alive falls back to tasklist,
# and stop falls back to taskkill, where POSIX signalling can't see the PID.
# Pure-bash HTTP/1.0 GET over /dev/tcp: succeed only on a 2xx status line.
# Fallback for minimal images that ship neither curl nor wget, so a healthy
# sidecar is never reported as "did not become healthy" for lack of an HTTP
# client. Plaintext + loopback only (no TLS, no redirects) — exactly what the
# /health endpoint this script polls needs. Degrades to "return 2" (the same
# no-client error as before) if this bash was built without /dev/tcp support.
http_ok_devtcp() {
local url="$1" rest host port path line
rest="${url#http://}"
path="/${rest#*/}"; [ "$path" = "/${rest}" ] && path="/"
host="${rest%%/*}"
port="${host##*:}"; host="${host%%:*}"
[ "$port" = "$host" ] && port=80
exec 3<>"/dev/tcp/${host}/${port}" 2>/dev/null || return 2
printf 'GET %s HTTP/1.0\r\nHost: %s\r\nConnection: close\r\n\r\n' "$path" "$host" >&3
if ! IFS= read -r -t 3 line <&3; then exec 3<&- 3>&-; return 1; fi
exec 3<&- 3>&-
case "$line" in
HTTP/*" 2"[0-9][0-9]*) return 0 ;;
*) return 1 ;;
esac
}
# GET a URL, succeed only on a 2xx response. curl > wget > pure-bash /dev/tcp.
http_ok() {
local url="$1"
if command -v curl >/dev/null 2>&1; then
curl -fsS -o /dev/null --max-time 3 "$url" 2>/dev/null
elif command -v wget >/dev/null 2>&1; then
wget -q -T 3 -O /dev/null "$url" 2>/dev/null
else
http_ok_devtcp "$url"
fi
}
# Fetch a URL body to stdout (best-effort; empty on failure).
http_body() {
local url="$1"
if command -v curl >/dev/null 2>&1; then
curl -fsS --max-time 3 "$url" 2>/dev/null || true
elif command -v wget >/dev/null 2>&1; then
wget -q -T 3 -O - "$url" 2>/dev/null || true
fi
}
# Is the server actually accepting requests? The real readiness signal.
server_up() { http_ok "$HEALTH_URL"; }
# Read the recorded PID from the pidfile (digits only), or empty. Never mutates.
read_pid() {
[ -f "$PIDFILE" ] || return 0
tr -dc '0-9' <"$PIDFILE" 2>/dev/null || true
}
# Is a PID alive? POSIX kill -0, with a Windows/msys tasklist fallback for the
# native-PID case where kill -0 gives a false negative.
pid_alive() {
local pid="$1"
[ -n "$pid" ] || return 1
if kill -0 "$pid" 2>/dev/null; then return 0; fi
if command -v tasklist >/dev/null 2>&1; then
tasklist //FI "PID eq ${pid}" //NH 2>/dev/null | grep -q "${pid}" && return 0
fi
return 1
}
# Send a signal (TERM|KILL) to a PID. Falls back to taskkill when POSIX kill
# cannot reach a native Windows PID (msys/Git Bash).
signal_pid() {
local sig="$1" pid="$2"
if kill -"$sig" "$pid" 2>/dev/null; then return 0; fi
if command -v taskkill >/dev/null 2>&1; then
if [ "$sig" = "KILL" ]; then
taskkill //PID "$pid" //F >/dev/null 2>&1 && return 0
else
taskkill //PID "$pid" >/dev/null 2>&1 && return 0
fi
fi
return 1
}
# Poll $HEALTH_URL until healthy or timeout (seconds). Pure-bash 1s cadence.
wait_for_health() {
local timeout="${1:-45}" i=0
while [ "$i" -lt "$timeout" ]; do
if server_up; then return 0; fi
sleep 1
i=$((i + 1))
done
return 1
}
# Resolve the tsx runner from the installed tree; never hit the network.
resolve_tsx() {
local bin="$REPO_ROOT/node_modules/.bin/tsx"
if [ -x "$bin" ]; then
echo "$bin"
return 0
fi
bin="$(command -v tsx 2>/dev/null || true)"
if [ -n "$bin" ]; then
echo "$bin"
return 0
fi
return 1
}
# ── Commands ──────────────────────────────────────────────────────────────────
cmd_start() {
local existing
existing="$(read_pid)"
if server_up || pid_alive "$existing"; then
echo "Waggle is already running${existing:+ (pid ${existing})} at http://127.0.0.1:${PORT}"
return 0
fi
local tsx_bin
if ! tsx_bin="$(resolve_tsx)"; then
echo "Error: tsx not found under ${REPO_ROOT}/node_modules. Run 'npm install' first." >&2
exit 1
fi
mkdir -p "$DATA_DIR"
# Environment for the sidecar. Skip the optional LiteLLM Python subprocess;
# point at the built web UI only when one exists (the server auto-probes
# <repo>/dist otherwise, but being explicit survives a different cwd).
export WAGGLE_SKIP_LITELLM=1
export WAGGLE_PORT="$PORT"
export WAGGLE_DATA_DIR="$DATA_DIR"
if [ -f "$REPO_ROOT/dist/index.html" ]; then
export WAGGLE_FRONTEND_DIR="$REPO_ROOT/dist"
fi
echo "Starting Waggle sidecar on port ${PORT} (data: ${DATA_DIR})..."
(
cd "$REPO_ROOT/packages/server"
nohup "$tsx_bin" src/local/start.ts >>"$LOGFILE" 2>&1 &
)
# The sidecar writes server.pid itself once it is listening; /health is the
# real readiness signal we wait on.
if wait_for_health 60; then
local pid
pid="$(read_pid)"
echo "Waggle is running${pid:+ (pid ${pid})} at http://127.0.0.1:${PORT}"
return 0
fi
echo "Error: Waggle did not become healthy within 60s. Last log lines:" >&2
tail -n 20 "$LOGFILE" 2>/dev/null >&2 || true
exit 1
}
cmd_stop() {
local pid
pid="$(read_pid)"
if ! server_up && ! pid_alive "$pid"; then
echo "Waggle is not running."
rm -f "$PIDFILE" 2>/dev/null || true
return 0
fi
if [ -z "$pid" ]; then
echo "Waggle appears to be running on port ${PORT} but no pid file was found at ${PIDFILE}." >&2
echo "Cannot signal it safely; stop the process listening on ${PORT} manually." >&2
exit 1
fi
echo "Stopping Waggle (pid ${pid})..."
signal_pid TERM "$pid" || true
local i=0
while [ "$i" -lt 3 ]; do
if ! server_up && ! pid_alive "$pid"; then break; fi
sleep 1
i=$((i + 1))
done
if server_up || pid_alive "$pid"; then
echo "Process did not exit after TERM; sending KILL."
signal_pid KILL "$pid" || true
sleep 1
fi
rm -f "$PIDFILE" 2>/dev/null || true
if server_up; then
echo "Warning: /health still responding on port ${PORT} after stop." >&2
exit 1
fi
echo "Waggle stopped."
}
cmd_status() {
local pid
pid="$(read_pid)"
if server_up; then
echo "Waggle: running${pid:+ (pid ${pid})} at http://127.0.0.1:${PORT}"
echo "Health: OK"
local body
body="$(http_body "$HEALTH_URL")"
[ -n "$body" ] && echo " $body"
elif pid_alive "$pid"; then
echo "Waggle: process ${pid} alive but /health not responding on port ${PORT}"
else
echo "Waggle: stopped"
rm -f "$PIDFILE" 2>/dev/null || true
fi
}
cmd_logs() {
if [ ! -f "$LOGFILE" ]; then
echo "No log file yet at ${LOGFILE}. Start Waggle first." >&2
exit 1
fi
echo "Tailing ${LOGFILE} (Ctrl-C to stop)..."
tail -n 100 -f "$LOGFILE"
}
case "$CMD" in
start) cmd_start ;;
stop) cmd_stop ;;
status) cmd_status ;;
logs) cmd_logs ;;
""|-h|--help) usage ;;
*) echo "Unknown command: ${CMD}" >&2; usage >&2; exit 2 ;;
esac