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

@@ -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',
],
});