@monotykamary/dsh-web-app 0.1.0-rc.10

package/lib/index.js

@@ -0,0 +1,432 @@
+import { createRequire } from "node:module";
+import { execFile, spawn } from "node:child_process";
+import { networkInterfaces } from "node:os";
+import { fileURLToPath } from "node:url";
+import z from "@monotykamary/schemastery";
+import { addHarnessSourceSection } from "@monotykamary/dsh-app-boot";
+import * as FrontendStatic from "@monotykamary/dsh-host-frontend-static";
+import { launchEnvironmentOf } from "@monotykamary/dsh-launch-environment";
+import { scrubbedParentEnv } from "@monotykamary/dsh-subprocess";
+import { createConnection } from "node:net";
+import { promisify } from "node:util";
+//#region lib/types/surfaces.js
+/**
+* Deployment-surface resolution for `dsh web`: derives the tailnet and
+* portless serving authorities from the machine's installed tooling for the
+* /api browser-trust fence and the URL line. Every probe is best-effort
+* environment detection, not configuration validation: an absent binary, an
+* unmatched route, or a dead proxy yields a warning and no surface, never a
+* failed boot. Resolution never rejects; unexpected probe failures surface
+* as warnings too, so a hanging or broken tool cannot take the URL line
+* (a supervisor readiness signal) down with it.
+* @module @monotykamary/dsh-web-app/surfaces
+*/
+const execFileAsync = promisify(execFile);
+/** Milliseconds one tailscale or portless binary invocation may run before the probe gives up. */
+const BINARY_PROBE_TIMEOUT_MS = 3e3;
+/** Milliseconds one TCP connect probe may wait for the portless proxy. */
+const PROXY_PROBE_TIMEOUT_MS = 1e3;
+/** The portless proxy's loopback HTTPS port (the fixed port its alias service owns). */
+const PORTLESS_PROXY_PORT = 443;
+/** The portless alias naming this app's HTTPS surface: the `dsh.localhost` host. */
+const PORTLESS_ALIAS_NAME = "dsh";
+/** Tailscale's canonical HTTPS port for `tailscale serve --https`. */
+const TAILSCALE_HTTPS_PORT = 443;
+function isEnoent(error) {
+	return error instanceof Error && error.code === "ENOENT";
+}
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function parseJson(stdout) {
+	const trimmed = stdout.trim();
+	if (trimmed === "") return null;
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		return null;
+	}
+}
+const stripTrailingDot = (dnsName) => dnsName.replace(/\.+$/, "");
+const defaultExec = (file, args) => execFileAsync(file, args, { timeout: BINARY_PROBE_TIMEOUT_MS });
+const defaultProbe = (host, port) => new Promise((resolve) => {
+	const socket = createConnection({
+		host,
+		port
+	});
+	const timer = setTimeout(() => {
+		socket.destroy();
+		resolve(false);
+	}, PROXY_PROBE_TIMEOUT_MS);
+	socket.once("connect", () => {
+		clearTimeout(timer);
+		socket.destroy();
+		resolve(true);
+	});
+	socket.once("error", () => {
+		clearTimeout(timer);
+		socket.destroy();
+		resolve(false);
+	});
+});
+/**
+* Resolve the tailnet surface: the tailscale node DNS name when
+* `tailscale serve` fronts the bound port with HTTPS (canonical port 443
+* Web handler or a TCP HTTPS listener), else a warning naming the mismatch.
+* @param port - the webserver's bound port (the serve target).
+* @param exec - the binary seam.
+* @returns the surface or one warning.
+*/
+async function resolveTailnetSurface(port, exec) {
+	let serveStdout;
+	try {
+		serveStdout = (await exec("tailscale", [
+			"serve",
+			"status",
+			"--json"
+		])).stdout;
+	} catch (error) {
+		if (isEnoent(error)) return { warning: "tailscale not installed — install from https://tailscale.com/download" };
+		return { warning: `tailscale serve status failed: ${errorText(error)}` };
+	}
+	let selfStdout;
+	try {
+		selfStdout = (await exec("tailscale", ["status", "--json"])).stdout;
+	} catch (error) {
+		if (isEnoent(error)) return { warning: "tailscale not installed — install from https://tailscale.com/download" };
+		return { warning: `tailscale status failed: ${errorText(error)}` };
+	}
+	const self = parseJson(selfStdout)?.Self;
+	if (self?.Online === false) return { warning: "tailscale offline — run `tailscale up` before using the tailnet surface" };
+	const dnsName = stripTrailingDot(self?.DNSName ?? "");
+	if (dnsName === "") return { warning: "tailscale node has no DNS name — run `tailscale up` before using the tailnet surface" };
+	const serveStatus = parseJson(serveStdout);
+	const webProxy = serveStatus?.Web?.[`${dnsName}:${TAILSCALE_HTTPS_PORT}`]?.Handlers?.["/"]?.Proxy;
+	if (webProxy === `http://localhost:${port}` || webProxy === `http://127.0.0.1:${port}`) return { surface: {
+		url: `https://${dnsName}`,
+		authority: dnsName
+	} };
+	const httpsTcpPorts = [];
+	for (const [hostPort, entry] of Object.entries(serveStatus?.TCP ?? {})) {
+		if (entry.HTTPS !== true) continue;
+		const match = /^(.*):(\d+)$/u.exec(hostPort);
+		if (match === null) continue;
+		if (match[1] !== dnsName && match[1] !== "localhost" && match[1] !== "127.0.0.1") continue;
+		httpsTcpPorts.push(Number(match[2]));
+	}
+	if (httpsTcpPorts.length > 0) return { surface: {
+		url: `https://${dnsName}:${httpsTcpPorts.includes(port) ? port : Math.min(...httpsTcpPorts)}`,
+		authority: dnsName
+	} };
+	return { warning: `tailscale serve does not front port ${port} — run \`tailscale serve --bg --https ${port} localhost:${port}\` to expose the tailnet surface` };
+}
+/**
+* Resolve the portless surface: register the \`dsh\` alias for the bound port
+* and confirm the proxy serves loopback :443 (IPv4 or IPv6 — observed setups
+* answer on only one), else a warning naming the missing piece.
+* @param port - the webserver's bound port (the alias target).
+* @param exec - the binary seam.
+* @param probe - the TCP probe seam.
+* @returns the surface or one warning.
+*/
+async function resolvePortlessSurface(port, exec, probe) {
+	try {
+		await exec("portless", [
+			"alias",
+			PORTLESS_ALIAS_NAME,
+			String(port),
+			"--force"
+		]);
+	} catch (error) {
+		if (isEnoent(error)) return { warning: "portless not installed — install from https://www.npmjs.com/package/portless for named localhost URLs" };
+		return { warning: `portless alias registration failed: ${errorText(error)}` };
+	}
+	if (!(await Promise.all([probe("127.0.0.1", PORTLESS_PROXY_PORT), probe("::1", PORTLESS_PROXY_PORT)])).some(Boolean)) return { warning: "portless proxy not running on :443 — run `portless service install` for named localhost URLs" };
+	return { surface: {
+		url: `https://${PORTLESS_ALIAS_NAME}.localhost`,
+		authority: `${PORTLESS_ALIAS_NAME}.localhost`
+	} };
+}
+const settleUnexpected = (label) => (error) => ({ warning: `${label} surface resolution failed: ${errorText(error)}` });
+/**
+* Resolve the enabled remote surfaces for the bound port. Disabled flags run
+* no probe and settle at once; enabled probes run in parallel and every
+* failure, expected or not, lands in `warnings`.
+* @param port - the webserver's bound port.
+* @param tailnet - whether the tailscale serve surface is enabled.
+* @param portless - whether the portless HTTPS surface is enabled.
+* @param options - binary and probe seams (tests).
+* @returns the resolved surfaces and their warnings; never rejects.
+*/
+async function resolveRemoteSurfaces(port, tailnet, portless, options = {}) {
+	if (!tailnet && !portless) return { warnings: [] };
+	const exec = options.exec ?? defaultExec;
+	const probe = options.probe ?? defaultProbe;
+	const [tailnetSettlement, portlessSettlement] = await Promise.all([tailnet ? resolveTailnetSurface(port, exec).catch(settleUnexpected("tailnet")) : Promise.resolve({}), portless ? resolvePortlessSurface(port, exec, probe).catch(settleUnexpected("portless")) : Promise.resolve({})]);
+	const resolution = { warnings: [] };
+	if (tailnetSettlement.surface !== void 0) resolution.tailnet = tailnetSettlement.surface;
+	if (tailnetSettlement.warning !== void 0) resolution.warnings.push(tailnetSettlement.warning);
+	if (portlessSettlement.surface !== void 0) resolution.portless = portlessSettlement.surface;
+	if (portlessSettlement.warning !== void 0) resolution.warnings.push(portlessSettlement.warning);
+	return resolution;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* @monotykamary/dsh-web-app — the browser-surface bundle's runtime glue plugin
+* plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
+* manifest field). The plugin owns the browser-surface glue: it resolves
+* the built frontend dist (workspace knowledge of this bundle, never user
+* config), mounts the `frontend-static` fallback owner over it, registers the
+* harness-source and web-surface prompt sections, the bash-visible web runtime
+* variable, the URL line, and the default-browser handoff. App command-line
+* values arrive through the `webStartup` service expressions in the bundle
+* patch.
+* @module @monotykamary/dsh-web-app
+*/
+/** Stable Cordis plugin name. */
+const name = "web-app";
+/** This dsh installation's root, from either this package's source or built entry. */
+const SOURCE_ROOT = fileURLToPath(new URL("../../../..", import.meta.url));
+/** Runtime service that releases Web rows after bind-dependent values resolve. */
+const WEB_RUNTIME_SERVICE = "webRuntime";
+/** Services required before the web runtime can mount. */
+const inject = ["webServer"];
+const Config = z.object({
+	openBrowser: z.boolean().default(true),
+	printUrl: z.boolean().default(true),
+	surfaceContext: z.boolean().default(true),
+	trustedHosts: z.array(String).default([]),
+	tailnet: z.boolean().default(false),
+	portless: z.boolean().default(false)
+});
+/** Environment variable naming the canonical local URL of this Web GUI. */
+const DSH_WEB_URL = "DSH_WEB_URL";
+const LOOPBACK_HOST = "127.0.0.1";
+/** The webserver schema's all-interfaces bind literal. */
+const ALL_INTERFACES_HOST = "0.0.0.0";
+/** Whether this process was launched through SSH, including a forwarded-port session. */
+function launchedThroughSsh(ctx) {
+	const environment = launchEnvironmentOf(ctx);
+	return ["SSH_CONNECTION", "SSH_TTY"].some((name) => {
+		const value = environment.getFrom(name, ["process"])?.value;
+		return value !== void 0 && value !== "";
+	});
+}
+const BROWSER_OPENER_MODULE = import.meta.resolve("open");
+const BROWSER_OPENER_PROGRAM = `
+try {
+  const { default: open } = await import(${JSON.stringify(BROWSER_OPENER_MODULE)})
+  const launcher = await open(process.argv[1])
+  if (process.platform === 'win32') {
+    // open resolves at PowerShell spawn; keep it referenced until that launcher hands the URL to Windows.
+    const code = launcher.exitCode ?? await new Promise((resolve, reject) => {
+      function onError(error) {
+        launcher.off('close', onClose)
+        reject(error)
+      }
+      function onClose(code) {
+        launcher.off('error', onError)
+        resolve(code)
+      }
+      launcher.ref()
+      launcher.once('error', onError)
+      launcher.once('close', onClose)
+    })
+    if (code !== 0) throw new Error('browser operating-system launcher exited with code ' + String(code))
+  }
+  process.exitCode = 0
+} catch (error) {
+  // The parent turns this exit into the manual-URL warning.
+  console.error(error)
+  process.exitCode = 1
+}
+`;
+/**
+* Resolve one LAN-trust snapshot from the active server bind.
+*
+* Derived entries are port-less IP literals: DNS rebinding needs an
+* attacker-controlled name, while an IP-literal Host is safe on any port and
+* an OS-assigned port is unknowable before bind.
+* @param bindHost - the active webserver bind host.
+* @param extra - explicit `--trusted-host` values, in argument order.
+* @returns the LAN display addresses and invocation-derived fence authorities.
+*/
+function resolveLanTrust(bindHost, extra) {
+	const lanAddresses = bindHost === ALL_INTERFACES_HOST ? Object.values(networkInterfaces()).flat().filter((iface) => iface !== void 0 && iface.family === "IPv4" && !iface.internal).map((iface) => iface.address) : [];
+	return {
+		lanAddresses,
+		trustedHosts: [...lanAddresses, ...extra]
+	};
+}
+/** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
+function webSurfacePrompt(webUrl) {
+	return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while \`pnpm run dev:web\` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background job and verify its exact URL.`;
+}
+/** Resolve the canonical loopback URL from the active Web server. */
+function localWebUrl(ctx) {
+	const port = ctx.get("webServer")?.port;
+	if (port === void 0) throw new Error("web-app: webServer service missing while resolving Web runtime");
+	return `http://${LOOPBACK_HOST}:${String(port)}`;
+}
+/** Dist location is workspace knowledge of this bundle: resolved through the frontend package exports, not configured. */
+function resolveDistIndex() {
+	const require = createRequire(import.meta.url);
+	try {
+		return require.resolve("@monotykamary/dsh-web-frontend/dist/index.html");
+	} catch {
+		/* v8 ignore next 2 -- reachable only on a checkout without a built dist; the test tree builds it */
+		throw new Error("web-app: frontend dist not built; run pnpm run build from the repository root first");
+	}
+}
+/** Start the maintained platform opener without forwarding Harness credentials. */
+function spawnBrowserLauncher(url) {
+	return spawn(process.execPath, [
+		"--input-type=module",
+		"--eval",
+		BROWSER_OPENER_PROGRAM,
+		"--",
+		url
+	], {
+		env: scrubbedParentEnv(),
+		stdio: [
+			"ignore",
+			"inherit",
+			"pipe"
+		]
+	});
+}
+/** Hand one URL to the operating system's default browser. */
+async function openBrowser(url) {
+	const launcher = spawnBrowserLauncher(url);
+	let launcherStderr = "";
+	launcher.stderr?.setEncoding("utf8");
+	launcher.stderr?.on("data", (chunk) => {
+		launcherStderr += chunk;
+	});
+	await new Promise((resolve, reject) => {
+		function onError(error) {
+			launcher.off("close", onClose);
+			reject(error);
+		}
+		function onClose(code) {
+			launcher.off("error", onError);
+			if (code !== 0) {
+				const firstLine = launcherStderr.trim().split(/\r?\n/u)[0];
+				const reason = firstLine === void 0 || firstLine === "" ? `browser launcher exited with code ${String(code)}` : firstLine.replace(/^(?:[A-Za-z]*Error):\s*/u, "");
+				reject(new Error(reason));
+				return;
+			}
+			if (launcherStderr !== "") process.stderr.write(launcherStderr);
+			resolve();
+		}
+		launcher.once("error", onError);
+		launcher.once("close", onClose);
+	});
+}
+/** Test hooks for the built dist and native browser handoff; production never mutates them. */
+/**
+* Test hooks: hosts with no built frontend dist substitute the dist resolver;
+* surface tests substitute the prober. Production never touches these.
+*/
+/**
+* Test hooks: hosts with no built frontend dist substitute the dist resolver;
+* surface tests substitute the prober. Production never touches these.
+*/
+const internals = {
+	resolveDistIndex,
+	resolveSurfaces: resolveRemoteSurfaces,
+	openBrowser
+};
+/**
+* Resolve the enabled remote surfaces once per boot and publish their
+* authorities into the /api fence. The add runs only after resolution
+* commits, and a derived authority failing canonical validation is dropped
+* from the announcement with a warning instead of silently widening trust.
+* @param ctx - plugin context carrying the bound webServer and the connection fence owner.
+* @param config - validated plugin config.
+* @returns the settled surface snapshot the URL line announces.
+*/
+async function settleSurfaces(ctx, config) {
+	const resolved = await internals.resolveSurfaces(ctx.webServer.port, config.tailnet, config.portless);
+	const connection = ctx.get("connection");
+	const resolution = { warnings: [...resolved.warnings] };
+	for (const key of ["tailnet", "portless"]) {
+		const surface = resolved[key];
+		if (surface === void 0) continue;
+		if (connection !== void 0) try {
+			connection.addTrustedAuthority(surface.authority);
+		} catch (error) {
+			resolution.warnings.push(`derived ${key} surface authority ${JSON.stringify(surface.authority)} refused: ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		resolution[key] = surface;
+	}
+	return resolution;
+}
+/**
+* Print the readiness URL line: the loopback URL first (supervisors parse
+* it), then the LAN snapshot and the derived remote surfaces.
+* @param ctx - plugin context carrying the bound webServer.
+* @param runtime - the bind-dependent LAN snapshot.
+* @param resolution - the settled surface snapshot.
+*/
+function printUrl(ctx, runtime, resolution) {
+	const port = ctx.webServer.port;
+	const entries = [];
+	const lanCandidate = runtime.lanAddresses[0];
+	if (lanCandidate !== void 0) entries.push(`LAN: http://${lanCandidate}:${String(port)}`);
+	if (resolution.tailnet !== void 0) entries.push(`tailnet: ${resolution.tailnet.url}`);
+	if (resolution.portless !== void 0) entries.push(`portless: ${resolution.portless.url}`);
+	console.log(`dsh web: ${localWebUrl(ctx)}${entries.length === 0 ? "" : ` (${entries.join(", ")})`}`);
+}
+/**
+* Mount the Web runtime: dist serving, surface prompt, the bash runtime
+* variable, the URL line, and the default-browser handoff.
+* @param ctx - plugin context carrying the webServer service.
+* @param config - validated {@link Config}.
+*/
+function apply(ctx, config) {
+	const runtime = resolveLanTrust(ctx.webServer.host, config.trustedHosts);
+	const handoffBrowser = config.openBrowser && !launchedThroughSsh(ctx);
+	ctx.provide(WEB_RUNTIME_SERVICE, runtime);
+	ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() });
+	if (config.surfaceContext) {
+		ctx.inject(["systemPrompt"], (promptCtx) => {
+			addHarnessSourceSection(promptCtx, SOURCE_ROOT);
+			promptCtx.systemPrompt.section({
+				name: "app:web-surface",
+				order: -98,
+				text: () => webSurfacePrompt(localWebUrl(promptCtx))
+			});
+		});
+		ctx.inject(["shellEnv"], (runtimeCtx) => {
+			runtimeCtx.shellEnv.register({
+				name: "web-runtime",
+				variables: { [DSH_WEB_URL]: { description: "Canonical local URL of the DeepSeek Harness Web GUI serving this session." } },
+				resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx) })
+			});
+		});
+	}
+	if (config.printUrl || handoffBrowser || config.tailnet || config.portless) {
+		const settled = ctx.get("loader")?.await();
+		const afterSettlement = async () => {
+			if (ctx.get("webServer") === void 0) return;
+			const webUrl = localWebUrl(ctx);
+			const resolution = await settleSurfaces(ctx, config);
+			for (const warning of resolution.warnings) ctx.logger.warn(warning);
+			if (config.printUrl) printUrl(ctx, runtime, resolution);
+			if (handoffBrowser) {
+				console.log("dsh web: opening the default browser; pass --no-open to disable");
+				internals.openBrowser(webUrl).catch((error) => {
+					const reason = error instanceof Error ? error.message : String(error);
+					console.error(`web-app: could not open the default browser because ${reason}; visit ${webUrl} manually`);
+				});
+			}
+		};
+		if (settled === void 0) afterSettlement();
+		else settled.then(afterSettlement, () => {});
+	}
+}
+//#endregion
+export { Config, apply, inject, internals, name, resolveLanTrust };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-web-app`.
+* @module @monotykamary/dsh-web-app/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-web-app";
+/** Cordis companion plugin name. */
+const name = "web-app-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: every contribution (frontend-static child plugin,
+* prompt section, bashEnv registration) is registry-disposed with the fiber,
+* and each owning registry's package carries that relation's invariant; the
+* package holds no mutable state of its own to audit.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/startup.js

@@ -0,0 +1,68 @@
+import { Command } from "commander";
+import { parseCmdline } from "@monotykamary/dsh-cmdline";
+//#region lib/types/startup.js
+/**
+* The web app's command-line provider: it parses the `dsh --profile web` flag
+* family (`--host`, `--port`, `--trusted-host`, `--tailnet`,
+* `--portless`, `--no-open`) and its `--help` text, then provides the
+* immutable values as {@link WEB_STARTUP_SERVICE}. Ordinary rows inject that
+* service before reading it from lazy config.
+* @module @monotykamary/dsh-web-app/startup
+*/
+/** Stable Cordis plugin name. */
+const name = "web-startup";
+/** Services required before the flags can be resolved. */
+const inject = ["cmdlineArgs"];
+/** Service provided by this ordinary plugin and injected by flag-configured rows. */
+const WEB_STARTUP_SERVICE = "webStartup";
+/**
+* This app's command: its flags, its description, and its help text.
+* @returns a fresh program, so one process can parse more than once (tests).
+*/
+function webCommand() {
+	return new Command().name("dsh --profile web").description("Serve the DeepSeek Harness browser UI.").helpOption("-h, --help", "show this help").option("--host <host>", "bind host").option("--no-open", "do not open the Web UI in the default browser").option("--port <port>", "listen port; pass 0 to let the OS pick a free one").option("--trusted-host <authority...>", "extra authority the /api browser-trust fence accepts (host or host:port; repeatable)").option("--tailnet", "resolve the tailscale serve surface: trust its DNS name and announce its URL").option("--portless", "resolve the portless HTTPS surface: register the dsh alias, trust dsh.localhost, and announce it").option("--identity <provider>", "identity provider: header (trust a reverse proxy) or passkey (WebAuthn)").option("--identity-header <name>", "identity header the trusted proxy sets (default x-forwarded-user)").option("--identity-trusted-proxy <spec>", "source allowlist for the identity header: loopback (default), private, a CIDR, or an address").option("--identity-registration <policy>", "passkey registration: open (default) or closed").option("--identity-rp-name <name>", "passkey relying-party display name (default dsh)").addHelpText("after", `
+Examples:
+  dsh --profile web                          serve on the composed host and port
+  dsh --profile web --no-open                serve without opening a browser
+  dsh --profile web --port 8080              serve on another port
+  dsh --profile web --tailnet                announce and trust https://<node>.ts.net
+  dsh --profile web --identity header        partition sessions by a proxy-set x-forwarded-user
+  dsh --profile web --identity passkey       self-contained WebAuthn login (prints an operator token)
+`);
+}
+/**
+* Parse and provide the Web invocation as an ordinary Cordis service. The
+* command's action publishes the flags this invocation named; `--host 0.0.0.0`
+* or a non-numeric `--port` is a usage error, so on rejection (and on `--help`)
+* nothing is provided.
+* @param ctx - plugin context carrying the command line.
+*/
+function apply(ctx) {
+	const program = webCommand();
+	program.action(() => {
+		const options = program.opts();
+		if (options.host === "0.0.0.0") program.error("error: --host 0.0.0.0 is intentionally not supported yet for safety: it would expose remote code execution to the network; use 127.0.0.1 instead");
+		if (options.port !== void 0 && !/^\d+$/.test(options.port)) program.error(`error: --port must be a number, got ${JSON.stringify(options.port)}`);
+		const identity = options.identity === "header" ? {
+			provider: "header",
+			...options.identityHeader !== void 0 && { header: options.identityHeader },
+			...options.identityTrustedProxy !== void 0 && { trustedProxy: options.identityTrustedProxy }
+		} : options.identity === "passkey" ? {
+			provider: "passkey",
+			...options.identityRegistration !== void 0 && { registration: options.identityRegistration },
+			...options.identityRpName !== void 0 && { rpName: options.identityRpName }
+		} : void 0;
+		ctx.provide(WEB_STARTUP_SERVICE, {
+			openBrowser: options.open,
+			...options.host !== void 0 && { host: options.host },
+			...options.port !== void 0 && { port: Number(options.port) },
+			trustedHosts: options.trustedHost ?? [],
+			tailnet: options.tailnet ?? false,
+			portless: options.portless ?? false,
+			...identity === void 0 ? {} : { identity }
+		});
+	});
+	parseCmdline(ctx, program);
+}
+//#endregion
+export { WEB_STARTUP_SERVICE, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @monotykamary/dsh-web-app — the browser-surface bundle's runtime glue plugin
+ * plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field). The plugin owns the browser-surface glue: it resolves
+ * the built frontend dist (workspace knowledge of this bundle, never user
+ * config), mounts the `frontend-static` fallback owner over it, registers the
+ * harness-source and web-surface prompt sections, the bash-visible web runtime
+ * variable, the URL line, and the default-browser handoff. App command-line
+ * values arrive through the `webStartup` service expressions in the bundle
+ * patch.
+ * @module @monotykamary/dsh-web-app
+ */
+import type { Context } from '@monotykamary/cordis';
+import z from '@monotykamary/schemastery';
+import { type SurfaceResolution } from './surfaces.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "web-app";
+/** Services required before the web runtime can mount. */
+export declare const inject: string[];
+/** Plugin config: composed deployment settings plus per-invocation command-line values. */
+export interface Config {
+    /** Permit default-browser handoff after the Loader tree settles; an SSH launch suppresses it. */
+    openBrowser: boolean;
+    /** Print the URL line on activation; a non-interactive layer can turn it off. */
+    printUrl: boolean;
+    /**
+     * Register the model-visible surface context (the `app:web-surface` prompt
+     * section and the `DSH_WEB_URL` bash variable). A one-shot non-interactive
+     * layer can turn it off when its user is not in the GUI, so the
+     * orientation text would be false.
+     */
+    surfaceContext: boolean;
+    /** Explicit `--trusted-host` authorities from this invocation. */
+    trustedHosts: string[];
+    /** `--tailnet`: resolve the tailscale serve surface, trust its DNS name, and announce its URL. */
+    tailnet: boolean;
+    /** `--portless`: resolve the portless HTTPS surface, trust its alias host, and announce it. */
+    portless: boolean;
+}
+export declare const Config: z<Config>;
+/** Bind-dependent Web values shared by the trust fence and URL display. */
+export interface WebRuntimeValues {
+    /** LAN IPv4 literals sampled once when the server binds all interfaces. */
+    lanAddresses: string[];
+    /** LAN literals followed by explicit invocation authorities. */
+    trustedHosts: string[];
+}
+/**
+ * Resolve one LAN-trust snapshot from the active server bind.
+ *
+ * Derived entries are port-less IP literals: DNS rebinding needs an
+ * attacker-controlled name, while an IP-literal Host is safe on any port and
+ * an OS-assigned port is unknowable before bind.
+ * @param bindHost - the active webserver bind host.
+ * @param extra - explicit `--trusted-host` values, in argument order.
+ * @returns the LAN display addresses and invocation-derived fence authorities.
+ */
+export declare function resolveLanTrust(bindHost: string, extra: readonly string[]): WebRuntimeValues;
+/** Test hooks for the built dist and native browser handoff; production never mutates them. */
+/**
+ * Test hooks: hosts with no built frontend dist substitute the dist resolver;
+ * surface tests substitute the prober. Production never touches these.
+ */
+/**
+ * Test hooks: hosts with no built frontend dist substitute the dist resolver;
+ * surface tests substitute the prober. Production never touches these.
+ */
+export declare const internals: {
+    resolveDistIndex: () => string;
+    resolveSurfaces: (port: number, tailnet: boolean, portless: boolean) => Promise<SurfaceResolution>;
+    openBrowser: (url: string) => Promise<void>;
+};
+/**
+ * Mount the Web runtime: dist serving, surface prompt, the bash runtime
+ * variable, the URL line, and the default-browser handoff.
+ * @param ctx - plugin context carrying the webServer service.
+ * @param config - validated {@link Config}.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-web-app`.
+ * @module @monotykamary/dsh-web-app/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-app-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/startup.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The web app's command-line provider: it parses the `dsh --profile web` flag
+ * family (`--host`, `--port`, `--trusted-host`, `--tailnet`,
+ * `--portless`, `--no-open`) and its `--help` text, then provides the
+ * immutable values as {@link WEB_STARTUP_SERVICE}. Ordinary rows inject that
+ * service before reading it from lazy config.
+ * @module @monotykamary/dsh-web-app/startup
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "web-startup";
+/** Services required before the flags can be resolved. */
+export declare const inject: string[];
+/** Service provided by this ordinary plugin and injected by flag-configured rows. */
+export declare const WEB_STARTUP_SERVICE = "webStartup";
+/** What the web rows read from {@link WEB_STARTUP_SERVICE}. */
+export interface WebStartupValues {
+    /** Whether this invocation opens the default browser after startup. */
+    openBrowser: boolean;
+    /** `--host`, absent when the invocation did not name one. */
+    host?: string;
+    /** `--port`, absent when the invocation did not name one. */
+    port?: number;
+    /** Explicit `--trusted-host` authorities, in argument order. */
+    trustedHosts: string[];
+    /** `--tailnet`: resolve and trust the tailscale serve surface. */
+    tailnet: boolean;
+    /** `--portless`: resolve and trust the portless HTTPS surface. */
+    portless: boolean;
+    /** The identity provider config `--identity` assembled, absent when off. */
+    identity?: {
+        provider: 'header';
+        header?: string;
+        trustedProxy?: string;
+    } | {
+        provider: 'passkey';
+        rpName?: string;
+        registration?: 'open' | 'closed';
+    };
+}
+/**
+ * Parse and provide the Web invocation as an ordinary Cordis service. The
+ * command's action publishes the flags this invocation named; `--host 0.0.0.0`
+ * or a non-numeric `--port` is a usage error, so on rejection (and on `--help`)
+ * nothing is provided.
+ * @param ctx - plugin context carrying the command line.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=startup.d.ts.map