diff --git a/README.md b/README.md index d222305..78a21b8 100644 --- a/README.md +++ b/README.md @@ -280,6 +280,38 @@ redirect. | `--workspace ` | `mcp setup` | Toolstile Cloud workspace the agents use (default: the last one, or personal) | | `--device-name ` | `mcp setup` | Name for this machine in the dashboard (default: its hostname) | +## Run Toolstile on your machine + +Toolstile's open-source server runs as one executable with its own embedded +database: no Docker, database server or Node.js setup. The CLI downloads it, +checks it against its published SHA-256 checksum and starts it: + +```sh +npx toolstile server start +``` + +On a new instance it runs the server at `http://127.0.0.1:4310` until you press +Ctrl-C and prints a one-time setup link (it works once and expires after 15 +minutes; each start prints a new one until an account exists). Open it, create +your account and follow the guided setup. Connect Claude Code to your own +server with: + +```sh +claude mcp add --transport http toolstile http://127.0.0.1:4310/mcp +``` + +| Command | What it does | +| --- | --- | +| `server start [--email ]` | Installs on first use and initializes a new instance, then runs the server. `--email` prints an invitation link for that address instead, for instances other people reach over the network | +| `server install [--release ] [--from ]` | Installs the latest release, a named one or a file you built | +| `server upgrade` | Refuses while the server runs; backs up the instance, then installs the latest release and keeps the previous executable | +| `server uninstall` | Removes the executable; your data and backups stay | +| `server bootstrap`, `operator`, `backup`, `restore`, `version` | Run the server's own commands | + +Builds exist for macOS on Apple silicon and Linux (x64 and arm64). The executable +lives in `~/.local/share/toolstile-server` (`$TOOLSTILE_SERVER_HOME`), its data in +`~/.local/share/toolstile` (`--data-dir` or `$TOOLSTILE_DATA_DIR`). + ## Use it from code ```ts diff --git a/src/cli.ts b/src/cli.ts index bae361e..393437d 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -6,6 +6,7 @@ import { createApi } from "./api.js"; import { renderCard, shareText, shareUrl } from "./card.js"; import { type Context, login, logout, proxy, setup, status, UserError, whoami } from "./commands.js"; import { runFix } from "./fix.js"; +import { install, passthrough, ServerError, split, start, uninstall, upgrade, type ServerContext } from "./server.js"; import { audit } from "./index.js"; import { redact, renderJson, renderReport, style } from "./report.js"; import type { Severity } from "./types.js"; @@ -20,6 +21,7 @@ Usage npx toolstile auth status List the servers this machine is signed in to npx toolstile whoami Show the account on the current server npx toolstile mcp setup Choose which agents here use Toolstile + npx toolstile server start Run your own Toolstile on this machine The auth, whoami and mcp commands work with Toolstile Cloud (the default), a self-hosted server (--server ) or the server on this machine (--local). @@ -136,6 +138,40 @@ Agents: claude-code, claude-desktop, cursor, codex, vscode, windsurf, devin, gem grok, opencode, kiro, antigravity `; +const SERVER_HELP = `toolstile server: run your own Toolstile on this machine + +Usage + npx toolstile server start [--email ] [options] + npx toolstile server install [--release ] [--from ] + npx toolstile server upgrade [--release ] [--from ] + npx toolstile server uninstall + npx toolstile server ... + +start downloads toolstile-server, a single executable with its own database, +on first use, then runs the server until you press Ctrl-C. A new instance on +this machine (an http:// origin on localhost, 127.0.0.0/8 or [::1]; the +default is http://127.0.0.1:4310) prints a one-time setup link: open it, +create your account and follow the guided setup. For a new instance with any +other origin, or to invite a specific account, pass --email: start then +prints an invitation link for it. + +upgrade refuses while the server is running, backs up the instance first and +keeps the executable it replaces. uninstall keeps your data. Other commands +run toolstile-server directly; see its local operation guide: +https://github.com/toolstile/toolstile/blob/main/docs/local-operation.md + +Options for start + --email
Print an invitation link for this account before starting + --data-dir Instance folder (default ~/.local/share/toolstile, or TOOLSTILE_DATA_DIR) + --origin New instance only: its address (default http://127.0.0.1:4310) + --listen
New instance only: interface to listen on (default 127.0.0.1) + --port New instance only: port (default 4310) + +Options for install and upgrade + --release A specific release (default: the latest) + --from Install a toolstile-server you built or downloaded yourself +`; + function version(): string { const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }; return pkg.version; @@ -326,10 +362,53 @@ async function command(argv: string[]): Promise { } } +async function server(argv: string[]): Promise { + const [action, ...rest] = argv; + if (!action || action === "-h" || action === "--help" || action === "help") { + process.stdout.write(SERVER_HELP); + return action ? 0 : 2; + } + if (rest.includes("-h") || rest.includes("--help")) { + if (["start", "install", "upgrade", "uninstall"].includes(action)) { + process.stdout.write(SERVER_HELP); + return 0; + } + } + const ctx: ServerContext = { + home: homedir(), + env: process.env, + platform: process.platform, + arch: process.arch, + fetch: (...args) => fetch(...args), + stdout: process.stdout, + stderr: process.stderr, + style: style(process.stderr.isTTY === true && !process.env.NO_COLOR), + }; + try { + if (action === "start") return await start(ctx, rest); + if (action === "install") { + const { own, rest: unknown } = split(rest, ["--release", "--from"]); + if (unknown.length) throw new ServerError(`Unknown option: ${unknown[0]}`); + await install(ctx, { release: own["--release"], from: own["--from"] }); + return 0; + } + if (action === "upgrade") return await upgrade(ctx, rest); + if (action === "uninstall") return uninstall(ctx); + return await passthrough(ctx, argv); + } catch (error) { + if (error instanceof ServerError) { + process.stderr.write(`toolstile: ${error.message}\n`); + return 1; + } + throw error; + } +} + async function main(): Promise { const argv = process.argv.slice(2); if (argv[0] === "whoami") return command(["auth", ...argv]); if (argv[0] === "auth" || argv[0] === "mcp") return command(argv); + if (argv[0] === "server") return server(argv.slice(1)); const help = argv[0] === "audit" ? AUDIT_HELP : HELP; let args: ReturnType; try { diff --git a/src/server.ts b/src/server.ts new file mode 100644 index 0000000..dda0748 --- /dev/null +++ b/src/server.ts @@ -0,0 +1,361 @@ +import { spawn } from "node:child_process"; +import { createHash } from "node:crypto"; +import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs"; +import { homedir } from "node:os"; +import { join, resolve } from "node:path"; +import { Readable, Transform } from "node:stream"; +import { pipeline } from "node:stream/promises"; +import { createBrotliDecompress } from "node:zlib"; +import type { Style } from "./report.js"; +import { isLoopback } from "./servers.js"; + +/** Where release executables are published; `TOOLSTILE_SERVER_DOWNLOAD_URL` replaces it. */ +export const RELEASES = "https://github.com/toolstile/toolstile/releases"; +/** Platforms with a published `toolstile-server` build. */ +export const PLATFORMS = ["darwin-arm64", "linux-arm64", "linux-x64"]; +const NAME = "toolstile-server"; + +export interface ServerContext { + home: string; + env: Record; + platform: NodeJS.Platform; + arch: string; + fetch: typeof fetch; + stdout: NodeJS.WritableStream & { isTTY?: boolean }; + stderr: NodeJS.WritableStream & { isTTY?: boolean }; + style: Style; + /** Runs the executable with inherited stdio and resolves to its exit code. */ + run?: (file: string, args: string[]) => Promise; +} + +/** A failure explained to the user; exits 1 without a stack trace. */ +export class ServerError extends Error {} + +/** `TOOLSTILE_SERVER_HOME`, else `toolstile-server` in the per-user data folder. */ +export function serverHome({ home, env }: Pick): string { + if (env.TOOLSTILE_SERVER_HOME) return resolve(env.TOOLSTILE_SERVER_HOME); + return join(env.XDG_DATA_HOME ?? join(home, ".local", "share"), NAME); +} +export const executablePath = (ctx: Pick) => join(serverHome(ctx), NAME); + +/** The instance folder `toolstile-server` uses: `--data-dir`, `TOOLSTILE_DATA_DIR` or its default. */ +export function dataDir(ctx: Pick, args: string[]): string { + const i = args.findIndex((a) => a === "--data-dir" || a.startsWith("--data-dir=")); + const given = i === -1 ? undefined : args[i]!.includes("=") ? args[i]!.slice(args[i]!.indexOf("=") + 1) : args[i + 1]; + return resolve(given ?? ctx.env.TOOLSTILE_DATA_DIR ?? join(ctx.home, ".local", "share", "toolstile")); +} + +function target(ctx: Pick): string { + const id = `${ctx.platform}-${ctx.arch}`; + if (!PLATFORMS.includes(id)) + throw new ServerError( + `There is no toolstile-server build for ${id} yet (available: ${PLATFORMS.join(", ")}). Run it from source instead: https://github.com/toolstile/toolstile/blob/main/docs/local-operation.md`, + ); + return `${NAME}-${id}`; +} + +/** Release download folder for `release` (`latest` or a tag). */ +export function downloadBase(ctx: Pick, release = "latest"): string { + const custom = ctx.env.TOOLSTILE_SERVER_DOWNLOAD_URL; + if (custom) { + const url = new URL(custom); + if (!allowed(url)) + throw new ServerError("TOOLSTILE_SERVER_DOWNLOAD_URL must use https://"); + return url.href.replace(/\/$/, ""); + } + return release === "latest" ? `${RELEASES}/latest/download` : `${RELEASES}/download/${encodeURIComponent(release)}`; +} + +const say = (ctx: ServerContext, text = "") => ctx.stderr.write(`${text}\n`); + +function runner(ctx: ServerContext) { + return ( + ctx.run ?? + ((file: string, args: string[]) => + new Promise((done, fail) => { + // In its own process group, Ctrl-C reaches only this process, which passes each + // signal on once: the server treats a second SIGINT as "stop without draining". + const child = spawn(file, args, { stdio: "inherit", detached: true }); + const signals = ["SIGINT", "SIGTERM", "SIGHUP"] as const; + // npx also passes Ctrl-C on to this process, so one keypress can arrive twice; + // a deliberate second Ctrl-C a moment later still forces the stop. + let interrupted = 0; + const forward = (signal: NodeJS.Signals) => { + if (signal === "SIGINT") { + if (Date.now() - interrupted < 1000) return; + interrupted = Date.now(); + } + child.kill(signal); + }; + for (const signal of signals) process.on(signal, forward); + child.once("error", fail); + child.once("exit", (code, signal) => { + for (const s of signals) process.off(s, forward); + done(code ?? (signal ? 1 : 0)); + }); + })) + ); +} + +/** Output of a short command, for `version`. */ +function capture(file: string, args: string[]): Promise { + return new Promise((done, fail) => { + const child = spawn(file, args, { stdio: ["ignore", "pipe", "pipe"] }); + let out = ""; + child.stdout.on("data", (chunk) => (out += chunk)); + child.once("error", fail); + child.once("exit", (code) => (code === 0 ? done(out.trim()) : fail(new Error(`exited with ${code}`)))); + }); +} + +/** HTTPS, or HTTP to a loopback host for a local test release. */ +function allowed(url: URL) { + return url.protocol === "https:" || (url.protocol === "http:" && /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(url.hostname)); +} + +async function get(ctx: ServerContext, url: string): Promise { + // Follow redirects here, so every hop (GitHub sends release files to its storage host) + // meets the same transport rule as the first. + let current = new URL(url); + for (let hop = 0; hop < 6; hop++) { + if (!allowed(current)) throw new ServerError(`Refusing to download from ${current.origin}: it is not HTTPS`); + let response: Response; + try { + response = await ctx.fetch(current.href, { redirect: "manual" }); + } catch (error) { + throw new ServerError(`Could not download ${url}: ${(error as Error).message}`); + } + const location = response.headers.get("location"); + if (response.status >= 300 && response.status < 400 && location) { + await response.body?.cancel(); + current = new URL(location, current); + continue; + } + if (response.status === 404) + throw new ServerError(`${url} was not found. Check the release name, or that this release has a build for your platform.`); + if (!response.ok || !response.body) throw new ServerError(`Downloading ${url} failed (HTTP ${response.status})`); + return response; + } + throw new ServerError(`Downloading ${url} redirected too many times`); +} + +/** Counts bytes through the stream and redraws a progress line on a terminal. */ +function progress(ctx: ServerContext, total: number) { + let seen = 0; + let shown = -1; + return new Transform({ + transform(chunk: Buffer, _encoding, next) { + seen += chunk.length; + // Redraw each percent, or each megabyte when the size is unknown. + const step = total ? Math.floor((seen / total) * 100) : Math.floor(seen / 1048576); + if (ctx.stderr.isTTY && step !== shown) { + shown = step; + const mb = (seen / 1048576).toFixed(1); + ctx.stderr.write(`\r ${total ? `${step}% ` : ""}${mb} MB`); + } + next(null, chunk); + }, + flush(done) { + if (ctx.stderr.isTTY) ctx.stderr.write("\r\x1b[2K"); + done(); + }, + }); +} + +/** + * Download (or copy `from`), verify and install the executable, keeping the one it replaces + * as `toolstile-server.previous`. Returns the installed version. + */ +export async function install(ctx: ServerContext, options: { release?: string; from?: string } = {}): Promise { + const destination = executablePath(ctx); + mkdirSync(serverHome(ctx), { recursive: true, mode: 0o700 }); + const temporary = `${destination}.download-${process.pid}`; + try { + if (options.from) { + const source = resolve(options.from); + if (!existsSync(source)) throw new ServerError(`${source} does not exist`); + say(ctx, `Installing ${source}`); + const output = createWriteStream(temporary, { mode: 0o755 }); + if (source.endsWith(".br")) await pipeline(createReadStream(source), createBrotliDecompress(), output); + else await pipeline(createReadStream(source), output); + } else { + const name = target(ctx); + const base = downloadBase(ctx, options.release); + const sums = await (await get(ctx, `${base}/${name}.sha256`)).text(); + const expected = sums.trim().split(/\s+/)[0] ?? ""; + if (!/^[a-f0-9]{64}$/.test(expected)) throw new ServerError(`${base}/${name}.sha256 is not a SHA-256 checksum`); + const response = await get(ctx, `${base}/${name}.br`); + say(ctx, `Downloading ${name} (${options.release ?? "latest"})`); + const hash = createHash("sha256"); + await pipeline( + Readable.fromWeb(response.body as import("node:stream/web").ReadableStream), + progress(ctx, Number(response.headers.get("content-length")) || 0), + createBrotliDecompress(), + new Transform({ + transform(chunk: Buffer, _encoding, next) { + hash.update(chunk); + next(null, chunk); + }, + }), + createWriteStream(temporary, { mode: 0o755 }), + ); + if (hash.digest("hex") !== expected) + throw new ServerError("The download does not match its published checksum, so it was not installed. Try again."); + } + let version: string; + try { + version = await capture(temporary, ["version"]); + } catch (error) { + throw new ServerError(`The downloaded executable does not run on this machine (${(error as Error).message})`); + } + if (existsSync(destination)) renameSync(destination, `${destination}.previous`); + renameSync(temporary, destination); + say(ctx, `Installed toolstile-server ${version} at ${destination}`); + return version; + } finally { + rmSync(temporary, { force: true }); + } +} + +/** Whether a process still owns the instance's database, as the server records it. */ +export function running(directory: string): number | undefined { + try { + const pid = Number(readFileSync(join(directory, "pglite.owner"), "utf8")); + if (!Number.isSafeInteger(pid) || pid < 1) return undefined; + process.kill(pid, 0); + return pid; + } catch { + return undefined; + } +} + +/** Options only `init` reads; `start` passes them on when it creates the instance. */ +const INIT_OPTIONS = ["--origin", "--listen", "--port"]; + +/** Separate `names` (each taking a value) from the other arguments. */ +export function split(args: string[], names: string[]) { + const own: Record = {}; + const rest: string[] = []; + const forward: string[] = []; + for (let i = 0; i < args.length; i++) { + const a = args[i]!; + const eq = a.indexOf("="); + const name = eq === -1 ? a : a.slice(0, eq); + if (names.includes(name)) { + const value = eq === -1 ? args[++i] : a.slice(eq + 1); + if (!value || value.startsWith("-")) throw new ServerError(`${name} needs a value`); + own[name] = value; + forward.push(name, value); + } else rest.push(a); + } + return { own, rest, forward }; +} + +/** + * `toolstile server start`: install on first use, initialize and invite the first account on + * a new instance, then run the server in the foreground. + */ +export async function start(ctx: ServerContext, args: string[]): Promise { + const { own, rest: other } = split(args, ["--email", "--data-dir"]); + const { forward: initArgs, rest } = split(other, INIT_OPTIONS); + const run = runner(ctx); + const executable = executablePath(ctx); + if (!existsSync(executable)) await install(ctx); + const directory = dataDir(ctx, own["--data-dir"] ? ["--data-dir", own["--data-dir"]] : []); + const pid = running(directory); + if (pid) throw new ServerError(`The instance in ${directory} is already running (process ${pid})`); + const data = ["--data-dir", directory]; + const email = own["--email"]; + const fresh = !existsSync(join(directory, "instance.json")); + if (fresh) { + if ((await run(executable, ["init", ...initArgs, ...data])) !== 0) return 1; + } else if (initArgs.length) + throw new ServerError(`${directory} is already initialized; --origin, --listen and --port apply only to a new instance.`); + const origin = instanceOrigin(directory); + const loopback = origin !== undefined && isLoopbackOrigin(origin); + if (email) { + if ((await run(executable, ["bootstrap", email, ...data])) !== 0) return 1; + say(ctx, ctx.style.dim("Open the invitation link once the server is listening, then create your account.")); + } else if (fresh && !loopback) { + // A loopback instance prints its own one-time setup link when it starts with no accounts. + // bootstrap needs the database the running server holds, so it has to run before start. + const dir = own["--data-dir"] ? ` --data-dir ${shellQuote(directory)}` : ""; + say(ctx, `No account exists yet. Stop the server (Ctrl-C), then run: npx toolstile server start --email you@example.com${dir}`); + } + // On a new loopback instance the server prints this line with its setup link. + if (origin && !(fresh && loopback)) + say(ctx, `Connect Claude Code: claude mcp add --transport http toolstile ${origin}/mcp`); + return run(executable, ["start", ...rest, ...data]); +} + +/** Quotes a path for a POSIX shell (the server runs on macOS and Linux only). */ +export const shellQuote = (value: string) => + /^[\w./~-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`; + +/** True for `http://` origins on 127.0.0.0/8, `localhost` or `[::1]`. */ +export function isLoopbackOrigin(origin: string): boolean { + try { + const url = new URL(origin); + return url.protocol === "http:" && isLoopback(url.hostname); + } catch { + return false; + } +} + +function instanceOrigin(directory: string): string | undefined { + try { + const origin = JSON.parse(readFileSync(join(directory, "instance.json"), "utf8")).origin; + return typeof origin === "string" ? origin : undefined; + } catch { + return undefined; + } +} + +/** Install a newer executable after backing up a stopped instance. */ +export async function upgrade(ctx: ServerContext, args: string[]): Promise { + const { own, rest } = split(args, ["--release", "--from", "--data-dir"]); + if (rest.length) throw new ServerError(`Unknown option: ${rest[0]}`); + const directory = dataDir(ctx, own["--data-dir"] ? ["--data-dir", own["--data-dir"]] : []); + const pid = running(directory); + if (pid) throw new ServerError(`Stop the server first (process ${pid}), then upgrade.`); + const executable = executablePath(ctx); + const initialized = existsSync(join(directory, "instance.json")); + if (!existsSync(executable)) { + // Without the executable that wrote the instance there is nothing to back it up with. + if (initialized) + throw new ServerError(`toolstile-server is not installed here, so ${directory} cannot be backed up first. Back it up with the executable that runs it, then use: npx toolstile server install`); + await install(ctx, { release: own["--release"], from: own["--from"] }); + return 0; + } + const current = await capture(executable, ["version"]).catch(() => "unknown"); + if (initialized) { + const backup = join(serverHome(ctx), "backups", `${new Date().toISOString().replace(/[:.]/g, "-")}-${current.replace(/[^\w.-]/g, "_")}`); + mkdirSync(join(serverHome(ctx), "backups"), { recursive: true, mode: 0o700 }); + if ((await runner(ctx)(executable, ["backup", backup, "--data-dir", directory])) !== 0) + throw new ServerError("The backup failed, so nothing was upgraded."); + say(ctx, `Backed up the instance to ${backup}`); + } + const next = await install(ctx, { release: own["--release"], from: own["--from"] }); + say(ctx, `Upgraded ${current} → ${next}. The previous executable is ${executable}.previous; start the server to apply migrations.`); + return 0; +} + +/** Remove the executables; the instance and its backups stay. */ +export function uninstall(ctx: ServerContext): number { + const executable = executablePath(ctx); + if (!existsSync(executable)) { + say(ctx, "toolstile-server is not installed."); + return 0; + } + rmSync(executable, { force: true }); + rmSync(`${executable}.previous`, { force: true }); + say(ctx, `Removed ${executable}. Instance data and backups were kept.`); + return 0; +} + +/** Run an installed `toolstile-server` command. */ +export async function passthrough(ctx: ServerContext, args: string[]): Promise { + const executable = executablePath(ctx); + if (!existsSync(executable)) throw new ServerError("toolstile-server is not installed. Run: npx toolstile server install"); + return runner(ctx)(executable, args); +} diff --git a/test/server.test.ts b/test/server.test.ts new file mode 100644 index 0000000..4fc303e --- /dev/null +++ b/test/server.test.ts @@ -0,0 +1,252 @@ +import { createHash } from "node:crypto"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { PassThrough } from "node:stream"; +import { brotliCompressSync } from "node:zlib"; +import { afterEach, beforeEach, describe, expect, it } from "vite-plus/test"; +import { style } from "../src/report.js"; +import { + dataDir, + downloadBase, + executablePath, + install, + isLoopbackOrigin, + shellQuote, + type ServerContext, + ServerError, + serverHome, + start, + uninstall, + upgrade, +} from "../src/server.js"; + +let home: string; +beforeEach(() => { + home = mkdtempSync(join(tmpdir(), "toolstile-server-")); +}); +afterEach(() => rmSync(home, { recursive: true, force: true })); + +/** A stand-in for toolstile-server: a script that prints its version. */ +const script = (version: string) => Buffer.from(`#!/bin/sh\necho ${version}\n`); +const sha256 = (data: Buffer) => createHash("sha256").update(data).digest("hex"); + +function context(files: Record = {}, overrides: Partial = {}) { + const requests: string[] = []; + const calls: string[][] = []; + const stderr = new PassThrough(); + let err = ""; + stderr.on("data", (chunk) => (err += chunk)); + const ctx: ServerContext = { + home, + env: { TOOLSTILE_SERVER_DOWNLOAD_URL: "https://releases.test/v1" }, + platform: "linux", + arch: "x64", + fetch: (async (url: string) => { + requests.push(url); + const file = files[url.replace("https://releases.test/v1/", "")]; + return file === undefined ? new Response("missing", { status: 404 }) : new Response(typeof file === "string" ? file : new Uint8Array(file)); + }) as typeof fetch, + stdout: new PassThrough(), + stderr, + style: style(false), + run: async (file, args) => { + calls.push([file, ...args]); + return 0; + }, + ...overrides, + }; + return { ctx, requests, calls, stderr: () => err }; +} + +function release(version: string, checksum?: string) { + const executable = script(version); + return { + "toolstile-server-linux-x64.br": brotliCompressSync(executable), + "toolstile-server-linux-x64.sha256": `${checksum ?? sha256(executable)} toolstile-server-linux-x64\n`, + }; +} + +describe.skipIf(process.platform === "win32")("toolstile server", () => { + it("keeps the executable apart from the instance it serves", () => { + const { ctx } = context(); + expect(serverHome(ctx)).toBe(join(home, ".local", "share", "toolstile-server")); + expect(serverHome({ home, env: { XDG_DATA_HOME: join(home, "xdg") } })).toBe(join(home, "xdg", "toolstile-server")); + expect(dataDir(ctx, [])).toBe(join(home, ".local", "share", "toolstile")); + expect(dataDir({ home, env: { TOOLSTILE_DATA_DIR: "/srv/a" } }, [])).toBe("/srv/a"); + expect(dataDir(ctx, ["start", "--data-dir", "/srv/b"])).toBe("/srv/b"); + expect(dataDir(ctx, ["--data-dir=/srv/c"])).toBe("/srv/c"); + }); + + it("downloads the latest release or a named one, and only over HTTPS", () => { + expect(downloadBase({ env: {} })).toBe("https://github.com/toolstile/toolstile/releases/latest/download"); + expect(downloadBase({ env: {} }, "v1.2.0")).toBe("https://github.com/toolstile/toolstile/releases/download/v1.2.0"); + expect(downloadBase({ env: { TOOLSTILE_SERVER_DOWNLOAD_URL: "http://127.0.0.1:9000/" } })).toBe("http://127.0.0.1:9000"); + expect(() => downloadBase({ env: { TOOLSTILE_SERVER_DOWNLOAD_URL: "http://example.com" } })).toThrow(ServerError); + }); + + it("installs a verified download and keeps the executable it replaces", async () => { + const first = context(release("1.0.0")); + expect(await install(first.ctx)).toBe("1.0.0"); + expect(first.requests).toEqual([ + "https://releases.test/v1/toolstile-server-linux-x64.sha256", + "https://releases.test/v1/toolstile-server-linux-x64.br", + ]); + const path = executablePath(first.ctx); + expect(readFileSync(path)).toEqual(script("1.0.0")); + expect(await install(context(release("1.1.0")).ctx)).toBe("1.1.0"); + expect(readFileSync(path)).toEqual(script("1.1.0")); + expect(readFileSync(`${path}.previous`)).toEqual(script("1.0.0")); + }); + + it("refuses a download that does not match its checksum and leaves nothing behind", async () => { + const { ctx } = context(release("1.0.0", "0".repeat(64))); + await expect(install(ctx)).rejects.toThrow(/does not match its published checksum/); + expect(readdirSync(serverHome(ctx))).toEqual([]); + }); + + it("follows redirects only to HTTPS", async () => { + const files = release("1.0.0"); + const fetchVia = (target: string) => + (async (url: string) => { + if (url.startsWith("https://releases.test/")) + return new Response(null, { status: 302, headers: { location: `${target}/${url.split("/").at(-1)}` } }); + const file = files[url.split("/").at(-1) as keyof typeof files]; + return new Response(typeof file === "string" ? file : new Uint8Array(file)); + }) as typeof fetch; + expect(await install(context({}, { fetch: fetchVia("https://storage.test") }).ctx)).toBe("1.0.0"); + await expect(install(context({}, { fetch: fetchVia("http://storage.test") }).ctx)).rejects.toThrow(/not HTTPS/); + }); + + it("explains a missing release and an unsupported platform", async () => { + await expect(install(context().ctx)).rejects.toThrow(/was not found/); + await expect(install(context(release("1.0.0"), { platform: "win32" }).ctx)).rejects.toThrow(/no toolstile-server build for win32-x64/); + }); + + it("installs a local build, compressed or not", async () => { + const { ctx } = context(); + const raw = join(home, "toolstile-server"); + writeFileSync(raw, script("2.0.0")); + expect(await install(ctx, { from: raw })).toBe("2.0.0"); + writeFileSync(`${raw}.br`, brotliCompressSync(script("2.1.0"))); + expect(await install(ctx, { from: `${raw}.br` })).toBe("2.1.0"); + }); + + it("initializes and invites on first start, then serves the same folder", async () => { + const { ctx, calls } = context(release("1.0.0")); + const data = join(home, "instance"); + const code = await start(ctx, ["--data-dir", data, "--email", "you@example.com", "--port", "4500"]); + expect(code).toBe(0); + const exe = executablePath(ctx); + expect(calls).toEqual([ + [exe, "init", "--port", "4500", "--data-dir", data], + [exe, "bootstrap", "you@example.com", "--data-dir", data], + [exe, "start", "--data-dir", data], + ]); + }); + + it("leaves the first account to the server's setup link on a new loopback instance", async () => { + const { ctx, calls, stderr } = context(release("1.0.0")); + const data = join(home, "instance"); + const run = ctx.run; + ctx.run = async (file, args) => { + if (args[0] === "init") { + mkdirSync(data, { recursive: true }); + writeFileSync(join(data, "instance.json"), JSON.stringify({ origin: "http://127.0.0.1:4310" })); + } + return run!(file, args); + }; + expect(await start(ctx, ["--data-dir", data])).toBe(0); + expect(calls.map((c) => c[1])).toEqual(["init", "start"]); + expect(stderr()).not.toMatch(/bootstrap|Connect Claude Code/); + }); + + it("points a new non-loopback instance at start --email with a quoted folder", async () => { + const { ctx, stderr } = context(release("1.0.0")); + const data = join(home, "Toolstile Data"); + const run = ctx.run; + ctx.run = async (file, args) => { + if (args[0] === "init") { + mkdirSync(data, { recursive: true }); + writeFileSync(join(data, "instance.json"), JSON.stringify({ origin: "https://tools.example.com" })); + } + return run!(file, args); + }; + expect(await start(ctx, ["--data-dir", data])).toBe(0); + expect(stderr()).toContain(`npx toolstile server start --email you@example.com --data-dir '${data}'`); + expect(stderr()).toMatch(/Connect Claude Code: .*https:\/\/tools.example.com\/mcp/); + }); + + it("quotes paths for the shell", () => { + expect(shellQuote("/tmp/toolstile-data")).toBe("/tmp/toolstile-data"); + expect(shellQuote("/tmp/Toolstile Data")).toBe("'/tmp/Toolstile Data'"); + expect(shellQuote("/tmp/it's")).toBe("'/tmp/it'\\''s'"); + }); + + it("recognizes loopback origins", () => { + expect(isLoopbackOrigin("http://127.0.0.1:4310")).toBe(true); + expect(isLoopbackOrigin("http://localhost:4310")).toBe(true); + expect(isLoopbackOrigin("http://[::1]:4310")).toBe(true); + expect(isLoopbackOrigin("https://127.0.0.1:4310")).toBe(false); + expect(isLoopbackOrigin("http://192.168.1.2:4310")).toBe(false); + }); + + it("starts an existing instance without initializing it again", async () => { + const { ctx, calls } = context(release("1.0.0")); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), JSON.stringify({ origin: "http://127.0.0.1:4310" })); + await start(ctx, ["--data-dir", data]); + expect(calls.map((c) => c[1])).toEqual(["start"]); + await expect(start(ctx, ["--data-dir", data, "--port", "1"])).rejects.toThrow(/already initialized/); + }); + + it("refuses to start or upgrade an instance that is running", async () => { + const { ctx } = context(release("1.0.0")); + await install(ctx); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), "{}"); + writeFileSync(join(data, "pglite.owner"), String(process.pid)); + await expect(start(ctx, ["--data-dir", data])).rejects.toThrow(/already running/); + await expect(upgrade(ctx, ["--data-dir", data])).rejects.toThrow(/Stop the server first/); + }); + + it("upgrades only an instance it can back up, with the options it knows", async () => { + const { ctx } = context(release("1.0.0")); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), "{}"); + await expect(upgrade(ctx, ["--data-dir", data])).rejects.toThrow(/cannot be backed up first/); + expect(existsSync(executablePath(ctx))).toBe(false); + await install(ctx); + await expect(upgrade(ctx, ["--data-di", data])).rejects.toThrow(/Unknown option: --data-di/); + await expect(upgrade(ctx, ["--data-dir="])).rejects.toThrow(/--data-dir needs a value/); + await expect(upgrade(ctx, ["--from="])).rejects.toThrow(/--from needs a value/); + }); + + it("backs up a stopped instance before upgrading", async () => { + const { ctx, calls } = context(release("1.0.0")); + await install(ctx); + const data = join(home, "instance"); + mkdirSync(data); + writeFileSync(join(data, "instance.json"), "{}"); + expect(await upgrade(ctx, ["--data-dir", data])).toBe(0); + expect(calls).toHaveLength(1); + expect(calls[0]!.slice(1, 2)).toEqual(["backup"]); + expect(calls[0]![2]).toContain(join(serverHome(ctx), "backups")); + expect(calls[0]!.slice(3)).toEqual(["--data-dir", data]); + expect(existsSync(`${executablePath(ctx)}.previous`)).toBe(true); + }); + + it("uninstalls the executables and keeps the instance", async () => { + const { ctx } = context(release("1.0.0")); + await install(ctx); + const data = join(home, ".local", "share", "toolstile"); + mkdirSync(data, { recursive: true }); + writeFileSync(join(data, "instance.json"), "{}"); + expect(uninstall(ctx)).toBe(0); + expect(existsSync(executablePath(ctx))).toBe(false); + expect(existsSync(join(data, "instance.json"))).toBe(true); + }); +});