@pablopunk/webr 0.1.1

package/dist/server/virtual_astro_middleware.mjs

@@ -0,0 +1,4 @@
+//#region \0noop-middleware
+var onRequest = (_, next) => next();
+//#endregion
+export { onRequest };

package/drizzle/0000_gateway.sql

@@ -0,0 +1,13 @@
+CREATE TABLE app_threads (id TEXT PRIMARY KEY NOT NULL, machine_id TEXT NOT NULL, session TEXT NOT NULL, alias TEXT, metadata TEXT NOT NULL, anchors TEXT NOT NULL, avatar INTEGER NOT NULL);
+--> statement-breakpoint
+CREATE UNIQUE INDEX native_alias ON app_threads(machine_id, session, alias);
+--> statement-breakpoint
+CREATE TABLE launch_operations (id TEXT PRIMARY KEY NOT NULL, account_id TEXT NOT NULL, key TEXT NOT NULL, hash TEXT NOT NULL, thread_id TEXT NOT NULL, input TEXT NOT NULL, state TEXT NOT NULL, step TEXT NOT NULL, result TEXT NOT NULL);
+--> statement-breakpoint
+CREATE UNIQUE INDEX account_operation_key ON launch_operations(account_id, key);
+--> statement-breakpoint
+CREATE TABLE app_settings (key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL);
+--> statement-breakpoint
+CREATE TABLE machine_profiles (id TEXT PRIMARY KEY NOT NULL, session TEXT NOT NULL, config_version INTEGER NOT NULL, metadata TEXT NOT NULL);
+--> statement-breakpoint
+CREATE TABLE project_locations (id TEXT PRIMARY KEY NOT NULL, machine_id TEXT NOT NULL, project_id TEXT NOT NULL, path TEXT NOT NULL);

package/drizzle/0001_device_sessions.sql

@@ -0,0 +1,9 @@
+CREATE TABLE `device_sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`token_hash` text NOT NULL,
+	`name` text NOT NULL,
+	`created_at` integer NOT NULL,
+	`last_seen_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `device_session_token` ON `device_sessions` (`token_hash`);

package/drizzle/0002_audit_events.sql

@@ -0,0 +1,7 @@
+CREATE TABLE `audit_events` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`at` integer NOT NULL,
+	`kind` text NOT NULL,
+	`source` text,
+	`device_name` text
+);

package/drizzle/meta/_journal.json

@@ -0,0 +1 @@
+{"version":"7","dialect":"sqlite","entries":[{"idx":0,"version":"6","when":1790841600000,"tag":"0000_gateway","breakpoints":true},{"idx":1,"version":"6","when":1790928000000,"tag":"0001_device_sessions","breakpoints":true},{"idx":2,"version":"6","when":1791014400000,"tag":"0002_audit_events","breakpoints":true}]}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@pablopunk/webr",
+  "version": "0.1.1",
+  "description": "Control your Herdr agents from anywhere.",
+  "keywords": [
+    "herdr",
+    "agents",
+    "terminal",
+    "web-ui",
+    "remote",
+    "cli"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "homepage": "https://github.com/pablopunk/webr#readme",
+  "bugs": {
+    "url": "https://github.com/pablopunk/webr/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pablopunk/webr.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "webr": "bin/webr.mjs"
+  },
+  "files": [
+    "bin",
+    "server",
+    "src/server",
+    "src/shared",
+    "src/lib",
+    "drizzle",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.16"
+  },
+  "scripts": {
+    "dev": "tsx scripts/dev.ts",
+    "build": "astro build",
+    "start": "tsx server/start.ts",
+    "check": "astro check && tsc --noEmit",
+    "test": "vitest run",
+    "icons": "tsx scripts/build-icons.ts",
+    "validate:offline": "tsx scripts/validate-protocol.ts",
+    "prepack": "astro build",
+    "smoke:install": "tsx scripts/smoke-install.ts"
+  },
+  "dependencies": {
+    "@astrojs/node": "11.1.6",
+    "@astrojs/react": "7.0.0",
+    "@base-ui/react": "1.8.0",
+    "@fastify/middie": "9.3.4",
+    "@fastify/static": "10.1.5",
+    "@fastify/websocket": "11.3.1",
+    "@tanstack/react-query": "5.104.0",
+    "@xterm/addon-fit": "0.10.0",
+    "@xterm/addon-web-links": "0.11.0",
+    "@xterm/xterm": "5.5.0",
+    "astro": "7.3.5",
+    "bot-avatars": "0.1.2",
+    "drizzle-orm": "0.45.3",
+    "fastify": "5.12.5",
+    "lucide-react": "0.468.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsx": "4.23.15",
+    "uqr": "0.1.3",
+    "zod": "4.6.5",
+    "zustand": "5.0.15"
+  },
+  "devDependencies": {
+    "@astrojs/check": "0.9.10",
+    "@testing-library/react": "16.3.3",
+    "@testing-library/user-event": "14.6.7",
+    "@types/node": "22.20.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@types/ws": "8.18.2",
+    "jsdom": "30.1.1",
+    "typescript": "5.9.3",
+    "vitest": "5.0.3",
+    "ws": "8.22.0"
+  }
+}

package/server/cli.ts

@@ -0,0 +1,93 @@
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { renderUnicode } from 'uqr';
+import { webrHome } from './home';
+import { runServer } from './run';
+import { serverPort } from './port';
+import { defaultDeps, installPlugin, pluginStatus, restartPluginWebr, uninstallWebrPlugin } from './plugin';
+import { checkHerdr } from './herdr-check';
+import { packageInfo } from './package-info';
+import { realUpdateEnvironment, runUpdate } from './update';
+import { refreshLatestVersionCache, updateHint } from './update/hint';
+
+const HELP = `Webr — control your Herdr agents from anywhere.
+
+Usage
+  webr [start] [options]        Run the server in this terminal
+  webr plugin install [options]  Start Webr whenever the Herdr server starts
+  webr plugin uninstall          Remove the Herdr plugin
+  webr plugin status             Show whether the plugin is installed and Webr is running
+  webr invite [--port <port>]    Print a one-time code and QR to connect a device
+  webr update                    Install the latest version and restart the Herdr plugin
+
+Options
+  --port <port>     Port to listen on (default 4321)
+  --lan             Listen on every network interface so devices on your network can connect
+  --host <address>  Listen on a specific address (default 127.0.0.1)
+  --origin <url>    Public URL when served through a proxy, e.g. https://mac.tailnet.ts.net
+  -v, --version     Print the version
+  -h, --help        Print this help
+
+Set WEBR_NO_UPDATE_CHECK=1 to stop Webr from checking for new versions.
+Localhost never needs a token. Any other device asks for access and you approve it in Webr on this computer.
+`;
+
+const options = {
+  port: { type: 'string' }, host: { type: 'string' }, origin: { type: 'string' }, lan: { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+} as const;
+
+function parseCommand(argv: string[]) { return parseArgs({ args: argv, options, allowPositionals: true }); }
+
+function applyServerFlags(values: ReturnType<typeof parseCommand>['values']) {
+  if (values.port) process.env.PORT = String(serverPort(['--port', values.port], {}));
+  if (values.lan) process.env.HOST = '0.0.0.0'; else if (values.host) process.env.HOST = values.host;
+  if (values.origin) process.env.WEBR_ORIGIN = values.origin;
+  process.env.WEBR_DATABASE ??= join(webrHome(), 'gateway.sqlite');
+}
+
+function printUpdateHint() {
+  const hint = updateHint();
+  if (hint) console.error(hint);
+}
+
+async function requireHerdr() {
+  const status = await checkHerdr();
+  if (!status.ok) throw new Error(status.problem);
+  if (status.note) console.log(status.note);
+}
+
+async function invite(port: number) {
+  const origin = `http://localhost:${port}`;
+  const response = await fetch(`${origin}/api/pair/invites`, { method: 'POST', headers: { 'Content-Type': 'application/json', Origin: origin }, body: '{}' }).catch(() => undefined);
+  if (!response?.ok) throw new Error(`Webr is not running on port ${port}. Start Herdr, or run "webr start".`);
+  const { token, urls } = await response.json() as { token: string; urls: string[] };
+  if (urls[0]) console.log(`${renderUnicode(urls[0], { border: 1, invert: true })}\n${urls[0]}\n`);
+  console.log(`Code: ${token}\nExpires in 5 minutes. Works once.`);
+  if (!urls.length) console.log('Webr is only reachable from this computer. Restart it with --lan or --origin to connect other devices.');
+}
+
+const pluginSettings = (values: ReturnType<typeof parseCommand>['values']) => ({
+  ...(values.port ? { port: serverPort(['--port', values.port], {}) } : {}),
+  ...(values.lan ? { host: '0.0.0.0' } : values.host ? { host: values.host } : {}),
+  ...(values.origin ? { origin: values.origin } : {}),
+});
+
+async function pluginCommand(action: string, values: ReturnType<typeof parseCommand>['values']) {
+  const deps = defaultDeps();
+  const lines = action === 'install' ? await installPlugin(pluginSettings(values), deps) : action === 'uninstall' ? await uninstallWebrPlugin(deps) : await pluginStatus(deps);
+  for (const line of lines.filter(Boolean)) console.log(line);
+}
+
+export async function main(argv: string[]) {
+  const { values, positionals } = parseCommand(argv);
+  const [command = 'start', subcommand] = positionals;
+  if (values.help || command === 'help') return void console.log(HELP);
+  if (values.version) { console.log(packageInfo().version); return printUpdateHint(); }
+  if (command === 'start') { applyServerFlags(values); await requireHerdr(); return runServer(); }
+  if (command === 'update') return void (await runUpdate(realUpdateEnvironment(() => restartPluginWebr(defaultDeps())))).forEach((line) => console.log(line));
+  if (command === 'refresh-update-cache') return refreshLatestVersionCache().catch(() => undefined);
+  if (command === 'invite') return invite(serverPort(values.port ? ['--port', values.port] : []));
+  if (command === 'plugin' && ['install', 'uninstall', 'status'].includes(subcommand ?? '')) return pluginCommand(subcommand!, values);
+  throw new Error(`Unknown command: ${positionals.join(' ')}\n\n${HELP}`);
+}

package/server/command.ts

@@ -0,0 +1,9 @@
+import { spawnSync } from 'node:child_process';
+
+export type CommandResult = { ok: boolean; output: string };
+export type RunCommand = (command: string, args: string[], env?: NodeJS.ProcessEnv) => CommandResult;
+
+export const realRun: RunCommand = (command, args, env): CommandResult => {
+  const result = spawnSync(command, args, { encoding: 'utf8', env: env ? { ...process.env, ...env } : undefined });
+  return { ok: result.status === 0, output: `${result.stdout ?? ''}${result.stderr ?? ''}${result.error?.message ?? ''}` };
+};

package/server/entry.ts

@@ -0,0 +1,3 @@
+import { fileURLToPath } from 'node:url';
+
+export const installedEntry = () => fileURLToPath(new URL('../bin/webr.mjs', import.meta.url));

package/server/herdr-check.ts

@@ -0,0 +1,37 @@
+import { SocketApi } from '../src/server/protocol/socket';
+import { discoverLocalSession } from '../src/server/transport/local-session';
+import { localSocket, type TargetProfile } from '../src/server/transport/registry';
+
+const NOT_INSTALLED = 'Herdr was not found. Install Herdr and make sure the "herdr" command is on your PATH, then try again.';
+const NOT_RUNNING = 'Herdr is not running yet. Webr will start its default session when it connects.';
+
+const UNRESPONSIVE = 'A Herdr session exists but does not answer. Quit Herdr, then start it again.';
+
+const problems: [match: string, advice: string][] = [
+  ['ENOENT', NOT_INSTALLED],
+  ['multiple_herdr_sessions', 'More than one Herdr session is running. Start Webr from the session you want, or set HERDR_SESSION to its name.'],
+  ['herdr_session_unreachable', UNRESPONSIVE],
+  ['rpc_timeout', UNRESPONSIVE],
+  ['missing_default_session', 'Herdr has no default session. Start Herdr once, then try again.'],
+];
+
+export const describeHerdrProblem = (error: unknown) => {
+  const text = `${(error as NodeJS.ErrnoException).code ?? ''} ${error instanceof Error ? error.message : String(error)}`;
+  return problems.find(([match]) => text.includes(match))?.[1] ?? `Webr could not reach Herdr: ${text.trim()}`;
+};
+
+async function answers(profile: TargetProfile) {
+  const api = new SocketApi(localSocket(profile));
+  try { await api.request('ping'); return true; }
+  catch (error) { if (['ENOENT', 'ECONNREFUSED'].includes((error as NodeJS.ErrnoException).code ?? '')) return false; throw error; }
+  finally { api.close(); }
+}
+
+export type HerdrStatus = { ok: true; note?: string } | { ok: false; problem: string };
+
+export async function checkHerdr(discover: () => Promise<TargetProfile> = () => discoverLocalSession(), ping: (profile: TargetProfile) => Promise<boolean> = answers): Promise<HerdrStatus> {
+  try {
+    const profile = await discover();
+    return profile.transport !== 'local' || await ping(profile) ? { ok: true } : { ok: true, note: NOT_RUNNING };
+  } catch (error) { return { ok: false, problem: describeHerdrProblem(error) }; }
+}

package/server/home.ts

@@ -0,0 +1,4 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const webrHome = (env: NodeJS.ProcessEnv = process.env) => env.WEBR_HOME ?? join(homedir(), '.webr');

package/server/log-file.ts

@@ -0,0 +1,52 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const MAX_BYTES = 5 * 1024 * 1024;
+const KEPT_BACKUPS = 3;
+
+type Chunk = string | Uint8Array;
+type OutputStream = { write: (chunk: Chunk, ...rest: never[]) => boolean };
+type LogOptions = { maxBytes?: number; keep?: number };
+
+const sizeOf = (path: string) => existsSync(path) ? statSync(path).size : 0;
+const backupPath = (path: string, index: number) => `${path}.${index}`;
+
+export class RotatingLog {
+  private size: number;
+  private readonly maxBytes: number;
+  private readonly keep: number;
+
+  constructor(private readonly path: string, { maxBytes = MAX_BYTES, keep = KEPT_BACKUPS }: LogOptions = {}) {
+    this.maxBytes = maxBytes;
+    this.keep = keep;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    this.size = sizeOf(path);
+  }
+
+  write(chunk: Chunk) {
+    const length = Buffer.byteLength(chunk);
+    if (this.size > 0 && this.size + length > this.maxBytes) this.rotate();
+    appendFileSync(this.path, chunk, { mode: 0o600 });
+    this.size += length;
+  }
+
+  private rotate() {
+    rmSync(backupPath(this.path, this.keep), { force: true });
+    for (let index = this.keep - 1; index >= 1; index--) if (existsSync(backupPath(this.path, index))) renameSync(backupPath(this.path, index), backupPath(this.path, index + 1));
+    renameSync(this.path, backupPath(this.path, 1));
+    this.size = 0;
+  }
+}
+
+export function redirectOutputToLogFile(path: string | undefined = process.env.WEBR_LOG_FILE, streams: OutputStream[] = [process.stdout, process.stderr], processEvents: Pick<NodeJS.Process, 'on' | 'exit'> = process) {
+  if (!path) return;
+  const log = new RotatingLog(path);
+  const append = (chunk: Chunk) => { try { log.write(chunk); } catch { return; } };
+  for (const stream of streams) stream.write = ((chunk: Chunk, ...rest: unknown[]) => {
+    append(chunk);
+    const done = rest.find((argument) => typeof argument === 'function') as (() => void) | undefined;
+    done?.();
+    return true;
+  }) as OutputStream['write'];
+  processEvents.on('uncaughtException', (error) => { append(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`); processEvents.exit(1); });
+}

package/server/package-info.ts

@@ -0,0 +1,6 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export type PackageInfo = { name: string; version: string };
+
+export const packageInfo = (): PackageInfo => JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));

package/server/plugin/config.ts

@@ -0,0 +1,14 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONFIG_FILE } from './files';
+
+export type PluginConfig = { port?: number; host?: string; origin?: string };
+
+export function writePluginConfig(configDir: string, config: PluginConfig) {
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(join(configDir, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function readPluginConfig(configDir: string): PluginConfig {
+  try { return JSON.parse(readFileSync(join(configDir, CONFIG_FILE), 'utf8')) as PluginConfig; } catch { return {}; }
+}

package/server/plugin/dev.ts

@@ -0,0 +1,27 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { realRun } from '../command';
+import type { RunCommand } from '../command';
+import { DEV_FILE, pluginStateDir } from './files';
+import { installFromGithub, installedPlugin, linkLocalPlugin } from './herdr';
+
+type Restore = () => void;
+const nothingToRestore: Restore = () => {};
+
+function restorePrevious(previous: ReturnType<typeof installedPlugin>, run: RunCommand) {
+  if (previous?.kind === 'github') return installFromGithub(run);
+  if (previous) return linkLocalPlugin(run, previous.root);
+}
+
+export function enterPluginDevMode(checkout: string, run: RunCommand = realRun, stateDir = pluginStateDir()): Restore {
+  const previous = installedPlugin(run);
+  if (!previous) return nothingToRestore;
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, DEV_FILE), JSON.stringify({ checkout }));
+  linkLocalPlugin(run, join(checkout, 'plugin'));
+  console.log('Webr plugin linked to this checkout. It is restored when dev stops.');
+  return () => {
+    rmSync(join(stateDir, DEV_FILE), { force: true });
+    restorePrevious(previous, run);
+  };
+}

package/server/plugin/files.ts

@@ -0,0 +1,10 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { PLUGIN_ID } from './herdr';
+
+export const CONFIG_FILE = 'config.json';
+export const DEV_FILE = 'dev.json';
+export const PID_FILE = 'webr.pid';
+export const LOG_FILE = 'webr.log';
+
+export const pluginStateDir = (env: NodeJS.ProcessEnv = process.env) => join(env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'herdr', 'plugins', PLUGIN_ID);

package/server/plugin/herdr.ts

@@ -0,0 +1,33 @@
+import type { CommandResult, RunCommand } from '../command';
+
+export const PLUGIN_ID = 'pablopunk.webr';
+export const PLUGIN_SOURCE = 'pablopunk/webr/plugin';
+
+export type InstalledPlugin = { root: string; kind: 'github' | 'local' };
+
+const succeeded = (result: CommandResult, action: string) => {
+  if (!result.ok) throw new Error(`herdr could not ${action}: ${result.output.trim()}`);
+  return result.output;
+};
+
+export function installedPlugin(run: RunCommand): InstalledPlugin | undefined {
+  const result = run('herdr', ['plugin', 'list', '--json']);
+  if (!result.ok) return undefined;
+  const plugins = (JSON.parse(result.output) as { result: { plugins: { plugin_id: string; plugin_root: string; source: { kind: InstalledPlugin['kind'] } }[] } }).result.plugins;
+  const found = plugins.find((plugin) => plugin.plugin_id === PLUGIN_ID);
+  return found && { root: found.plugin_root, kind: found.source.kind };
+}
+
+export const requireHerdr = (run: RunCommand) => {
+  if (!run('herdr', ['--version']).ok) throw new Error('Herdr is not installed or not on your PATH. Install it from https://herdr.dev first.');
+};
+
+export const requireGit = (run: RunCommand) => {
+  if (!run('git', ['--version']).ok) throw new Error('Git is not installed or not on your PATH. Herdr needs it to install plugins from GitHub.');
+};
+
+export const pluginConfigDir = (run: RunCommand) => succeeded(run('herdr', ['plugin', 'config-dir', PLUGIN_ID]), 'find the plugin config folder').trim();
+export const installFromGithub = (run: RunCommand) => succeeded(run('herdr', ['plugin', 'install', PLUGIN_SOURCE, '--yes']), 'install the plugin');
+export const uninstallPlugin = (run: RunCommand) => succeeded(run('herdr', ['plugin', 'uninstall', PLUGIN_ID]), 'uninstall the plugin');
+export const linkLocalPlugin = (run: RunCommand, directory: string) => succeeded(run('herdr', ['plugin', 'link', directory]), 'link the plugin');
+export const unlinkLocalPlugin = (run: RunCommand) => succeeded(run('herdr', ['plugin', 'unlink', PLUGIN_ID]), 'unlink the plugin');

package/server/plugin/index.ts

@@ -0,0 +1,68 @@
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { realRun, type RunCommand } from '../command';
+import { readPluginConfig, writePluginConfig, type PluginConfig } from './config';
+import { pluginStateDir } from './files';
+import { isPortOpen, probeAddress } from './probe';
+import { stopPluginWebr } from './stop';
+import { installFromGithub, installedPlugin, pluginConfigDir, requireGit, requireHerdr, uninstallPlugin, unlinkLocalPlugin } from './herdr';
+
+export type PluginDeps = {
+  run: RunCommand;
+  stateDir: string;
+};
+
+export const defaultDeps = (): PluginDeps => ({ run: realRun, stateDir: pluginStateDir() });
+
+const startNow = (root: string, configDir: string, deps: PluginDeps) =>
+  deps.run(process.execPath, [join(root, 'launch.mjs')], { HERDR_PLUGIN_CONFIG_DIR: configDir, HERDR_PLUGIN_STATE_DIR: deps.stateDir }).output.trim();
+
+export async function installPlugin(config: PluginConfig, deps: PluginDeps) {
+  requireHerdr(deps.run);
+  requireGit(deps.run);
+  const configDir = pluginConfigDir(deps.run);
+  writePluginConfig(configDir, config);
+  installFromGithub(deps.run);
+  const plugin = installedPlugin(deps.run);
+  if (!plugin) throw new Error('Herdr did not register the Webr plugin.');
+  return [
+    'Installed the Webr plugin. It starts Webr whenever the Herdr server starts.',
+    startNow(plugin.root, configDir, deps),
+  ];
+}
+
+export async function uninstallWebrPlugin(deps: PluginDeps) {
+  requireHerdr(deps.run);
+  const plugin = installedPlugin(deps.run);
+  if (!plugin) return ['The Webr plugin is not installed.'];
+  const configDir = pluginConfigDir(deps.run);
+  const stopped = await stopPluginWebr(deps.stateDir, probeAddress(readPluginConfig(configDir)));
+  if (plugin.kind === 'github') uninstallPlugin(deps.run); else unlinkLocalPlugin(deps.run);
+  rmSync(configDir, { recursive: true, force: true });
+  rmSync(deps.stateDir, { recursive: true, force: true });
+  return ['Removed the Webr plugin.', ...(stopped ? ['Stopped the running Webr.'] : [])];
+}
+
+export async function restartPluginWebr(deps: PluginDeps) {
+  if (!deps.run('herdr', ['--version']).ok) return undefined;
+  const plugin = installedPlugin(deps.run);
+  if (!plugin) return undefined;
+  const configDir = pluginConfigDir(deps.run);
+  const address = probeAddress(readPluginConfig(configDir));
+  if ((await isPortOpen(address)) && !(await stopPluginWebr(deps.stateDir, address))) return [`Webr is running on port ${address.port} but the plugin did not start it. Stop it and run "webr plugin install" to use the new version.`];
+  return [startNow(plugin.root, configDir, deps)];
+}
+
+export async function pluginStatus(deps: PluginDeps) {
+  requireHerdr(deps.run);
+  const plugin = installedPlugin(deps.run);
+  if (!plugin) return ['The Webr plugin is not installed. Install it with "webr plugin install".'];
+  const config = readPluginConfig(pluginConfigDir(deps.run));
+  const address = probeAddress(config);
+  return [
+    `Installed (${plugin.kind === 'github' ? 'from GitHub' : `linked to ${plugin.root}`}).`,
+    `Webr is ${await isPortOpen(address) ? 'running' : 'not running'} on port ${address.port}.`,
+    `Settings: ${JSON.stringify(config)}`,
+    `Logs and state: ${deps.stateDir}`,
+  ];
+}

package/server/plugin/probe.ts

@@ -0,0 +1,17 @@
+import { createConnection } from 'node:net';
+import type { PluginConfig } from './config';
+
+const DEFAULT_PORT = 4321;
+const WILDCARD_HOSTS = ['0.0.0.0', '::'];
+
+export const probeAddress = ({ port, host }: PluginConfig) => ({
+  port: port ?? DEFAULT_PORT,
+  host: !host || WILDCARD_HOSTS.includes(host) ? '127.0.0.1' : host,
+});
+
+export const isPortOpen = ({ host, port }: { host: string; port: number }) => new Promise<boolean>((done) => {
+  const socket = createConnection({ host, port });
+  socket.once('connect', () => { socket.destroy(); done(true); });
+  socket.once('error', () => done(false));
+  socket.setTimeout(1000, () => { socket.destroy(); done(false); });
+});

package/server/plugin/stop.ts

@@ -0,0 +1,39 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { PID_FILE } from './files';
+import { isPortOpen } from './probe';
+
+type Address = Parameters<typeof isPortOpen>[0];
+
+const STOP_ATTEMPTS = 50;
+const STOP_POLL_MS = 100;
+
+const pidPath = (stateDir: string) => join(stateDir, PID_FILE);
+const sleep = (ms: number) => new Promise((done) => setTimeout(done, ms));
+
+function recordedPid(stateDir: string) {
+  try {
+    const pid = Number(readFileSync(pidPath(stateDir), 'utf8').trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+  } catch { return undefined; }
+}
+
+function isAlive(pid: number) {
+  try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM'; }
+}
+
+async function waitUntilClosed(address: Address) {
+  for (let attempt = 0; attempt < STOP_ATTEMPTS; attempt++) {
+    if (!(await isPortOpen(address))) return true;
+    await sleep(STOP_POLL_MS);
+  }
+  return false;
+}
+
+export async function stopPluginWebr(stateDir: string, address: Address) {
+  const pid = recordedPid(stateDir);
+  rmSync(pidPath(stateDir), { force: true });
+  if (!pid || !isAlive(pid) || !(await isPortOpen(address))) return false;
+  process.kill(pid, 'SIGTERM');
+  return waitUntilClosed(address);
+}

package/server/port.ts

@@ -0,0 +1,8 @@
+const DEFAULT_PORT = 4321;
+const portArgument = (args: string[]) => { const index = args.indexOf('--port'); return index >= 0 ? args[index + 1] : args.find((arg) => arg.startsWith('--port='))?.slice('--port='.length); };
+
+export function serverPort(args = process.argv.slice(2), env = process.env) {
+  const port = Number(portArgument(args) ?? env.PORT ?? DEFAULT_PORT);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('The port must be a number from 1 to 65535.');
+  return port;
+}

package/server/run.ts

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { MetadataDatabase } from '../src/server/storage/database';
+import { RuntimeManager } from '../src/server/runtime/manager';
+import { loadRegistry } from '../src/server/transport/registry';
+import { HerdrTarget } from '../src/server/transport/herdr-target';
+import { createHost } from '../src/server/host';
+import { publicUrls } from '../src/server/public-urls';
+import { detectTailscaleHost } from '../src/server/tailscale-host';
+import { isLoopbackHost } from '../src/server/auth/access';
+import { serverPort } from './port';
+import { builtSsr, devSsr } from './ssr';
+
+const WILDCARD_HOSTS = ['0.0.0.0', '::'];
+
+export async function runServer() {
+  const host = process.env.HOST ?? '127.0.0.1';
+  const port = serverPort();
+  const tlsEnabled = !!(process.env.WEBR_TLS_CERT && process.env.WEBR_TLS_KEY);
+  const origin = process.env.WEBR_ORIGIN ?? `${tlsEnabled ? 'https' : 'http'}://${WILDCARD_HOSTS.includes(host) ? 'localhost' : host}:${port}`;
+  if (new URL(origin).origin !== origin || new URL(origin).username || new URL(origin).password) throw new Error('WEBR_ORIGIN must be a normalized HTTP or HTTPS origin without credentials or a path');
+  if (!['http:', 'https:'].includes(new URL(origin).protocol)) throw new Error('WEBR_ORIGIN must use HTTP or HTTPS');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid port');
+  const database = new MetadataDatabase(process.env.WEBR_DATABASE ?? '.data/gateway.sqlite');
+  const profiles = await loadRegistry(process.env.WEBR_TARGETS);
+  const manager = new RuntimeManager(database, profiles.map((profile) => new HerdrTarget(profile)));
+  const ssr = process.env.WEBR_DEV === '1' ? await devSsr(port, host) : await builtSsr();
+  const tls = tlsEnabled ? { cert: await readFile(process.env.WEBR_TLS_CERT!), key: await readFile(process.env.WEBR_TLS_KEY!) } : undefined;
+  const urls = publicUrls(origin, host, port, undefined, await detectTailscaleHost());
+  const app = await createHost(manager, origin, ssr.handler, tls, undefined, { publicUrls: urls });
+  await app.listen({ host, port });
+  manager.start();
+  console.log(`Webr listening at ${origin}`);
+  if (!isLoopbackHost(host) || urls.length) console.log(`Other devices connect at:\n${(urls.length ? urls : [origin]).map((url) => `  ${url}`).join('\n')}\nThey ask for access and you approve them in Webr on this computer.`);
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => { void Promise.all([app.close(), ssr.stop()]).finally(() => { database.close(); process.exit(0); }); });
+}

package/server/ssr.ts

@@ -0,0 +1,23 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { distRoot } from '../src/server/dist';
+
+type Locals = Record<string, unknown>;
+export type Ssr = { handler: (request: object, response: unknown, next: unknown, locals: Locals) => void; stop: () => Promise<void> };
+
+const astroLocalsSymbol = Symbol.for('astro.locals');
+
+export async function builtSsr(): Promise<Ssr> {
+  const { handler } = await import(pathToFileURL(resolve(distRoot(), 'server/entry.mjs')).href);
+  return { handler, stop: async () => {} };
+}
+
+export async function devSsr(port: number, host = '127.0.0.1'): Promise<Ssr> {
+  const { dev } = await import('astro');
+  const astro = await dev({ server: { port: port + 2, host }, vite: { server: { allowedHosts: true, hmr: { port: port + 1 } } } });
+  const handler: Ssr['handler'] = (request, response, _next, locals) => {
+    Reflect.set(request, astroLocalsSymbol, locals);
+    astro.handle(request as never, response as never);
+  };
+  return { handler, stop: () => astro.stop() };
+}

package/server/start.ts

@@ -0,0 +1,5 @@
+import { redirectOutputToLogFile } from './log-file';
+import { runServer } from './run';
+
+redirectOutputToLogFile();
+await runServer();