wire-mesh 1.0.3 → 1.0.4

package/README.md

@@ -28,6 +28,19 @@ pnpm add wire-mesh
 wire-mesh --bind 0.0.0.0:8787
 ```
 
+Every flag the CLI accepts, exactly as `wire-mesh --help` prints it. An unknown flag, a flag missing its value, or a malformed `--bind` address exits non-zero with a message on stderr rather than starting a node; the `--tls-cert`/`--tls-key` pairing is enforced the same way. The parser, this text, and the help output all come from one flag table in `src/cli-options.ts`, and a test fails if this block stops matching it.
+
+```text
+Usage: wire-mesh [options]
+
+Options:
+      --bind <host:port>  Address to listen on. Port 0 asks the OS for a free port. Use 127.0.0.1:8787 to accept local connections only. (default: 0.0.0.0:8787)
+      --tls-cert <path>   PEM certificate file, to serve wss:// and https://. Requires --tls-key.
+      --tls-key <path>    PEM private key file for --tls-cert. Requires --tls-cert.
+  -h, --help              Print this help and exit.
+  -v, --version           Print the version and exit.
+```
+
 **Default bind address is `0.0.0.0:8787`, not loopback.** Unlike a typical dev-server tool, whose loopback-only default assumes only the machine itself needs to reach it, this package's whole purpose is LAN reachability — a phone on the same network, a laptop in the next room. `--bind` overrides the address if you want to restrict it (loopback-only, a specific interface, a different port).
 
 Point a browser at the bound address to reach the console, or check its health directly:

package/dist/server.cjs

@@ -5,6 +5,98 @@ let node_fs = require("node:fs");
 let node_path = require("node:path");
 let node_url = require("node:url");
 let wire_mesh_core_domain_relay_hub = require("wire-mesh-core/domain/relay-hub");
+let node_util = require("node:util");
+//#region src/cli-options.ts
+/** The address the server binds when --bind is not given. */
+const DEFAULT_BIND_ADDRESS = "0.0.0.0:8787";
+const MAX_PORT = 65535;
+/** Every flag the CLI accepts, keyed by its long name (without the leading dashes). */
+const FLAGS = {
+	bind: {
+		type: "string",
+		valueName: "host:port",
+		default: DEFAULT_BIND_ADDRESS,
+		description: "Address to listen on. Port 0 asks the OS for a free port. Use 127.0.0.1:8787 to accept local connections only."
+	},
+	"tls-cert": {
+		type: "string",
+		valueName: "path",
+		description: "PEM certificate file, to serve wss:// and https://. Requires --tls-key."
+	},
+	"tls-key": {
+		type: "string",
+		valueName: "path",
+		description: "PEM private key file for --tls-cert. Requires --tls-cert."
+	},
+	help: {
+		type: "boolean",
+		short: "h",
+		description: "Print this help and exit."
+	},
+	version: {
+		type: "boolean",
+		short: "v",
+		description: "Print the version and exit."
+	}
+};
+/** Thrown for arguments the CLI cannot act on; the message names the offending flag and is fit to print as-is. */
+var CliUsageError = class extends Error {
+	name = "CliUsageError";
+};
+function usageLabelOf(name, definition) {
+	const long = `--${name}${definition.valueName === void 0 ? "" : ` <${definition.valueName}>`}`;
+	return definition.short === void 0 ? `    ${long}` : `-${definition.short}, ${long}`;
+}
+/** The usage text printed for --help, generated from FLAGS. */
+function helpText() {
+	const rows = Object.entries(FLAGS).map(([name, definition]) => ({
+		label: usageLabelOf(name, definition),
+		description: definition.default === void 0 ? definition.description : `${definition.description} (default: ${definition.default})`
+	}));
+	const labelWidth = Math.max(...rows.map((row) => row.label.length));
+	return [
+		"Usage: wire-mesh [options]",
+		"",
+		"Options:",
+		...rows.map((row) => `  ${row.label.padEnd(labelWidth)}  ${row.description}`)
+	].join("\n");
+}
+function validatedBindAddress(address) {
+	const separator = address.lastIndexOf(":");
+	const host = address.slice(0, separator);
+	const port = address.slice(separator + 1);
+	if (separator === -1 || host === "" || !/^\d+$/.test(port) || Number(port) > MAX_PORT) throw new CliUsageError(`--bind expects host:port with a port from 0 to ${String(MAX_PORT)}, got "${address}"`);
+	return address;
+}
+/** Parses the process arguments (without the node and script entries) into the command they ask for. Throws CliUsageError for an unknown flag, a stray positional argument, a flag missing or given an unwanted value, a malformed --bind address, or --tls-cert without --tls-key (or the reverse). */
+function parseCliArguments(argv) {
+	let values;
+	try {
+		({values} = (0, node_util.parseArgs)({
+			args: [...argv],
+			options: FLAGS,
+			strict: true,
+			allowPositionals: false
+		}));
+	} catch (error) {
+		if (error instanceof Error) throw new CliUsageError(error.message, { cause: error });
+		throw error;
+	}
+	if (values.help === true) return { kind: "help" };
+	if (values.version === true) return { kind: "version" };
+	const certPath = values["tls-cert"];
+	const keyPath = values["tls-key"];
+	if (certPath === void 0 !== (keyPath === void 0)) throw new CliUsageError("--tls-cert and --tls-key must be given together");
+	return {
+		kind: "serve",
+		bindAddress: validatedBindAddress(values.bind),
+		tls: certPath === void 0 || keyPath === void 0 ? void 0 : {
+			certPath,
+			keyPath
+		}
+	};
+}
+//#endregion
 //#region src/static-console.ts
 const CONTENT_TYPES = {
 	".css": "text/css; charset=utf-8",
@@ -54,28 +146,18 @@ function healthResponse() {
 		roles: ["relay"]
 	};
 }
-const DEFAULT_BIND_ADDRESS = "0.0.0.0:8787";
 const HTTP_OK = 200;
 const HTTP_NOT_FOUND = 404;
 const HEALTH_PATH = "/health";
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
 const __dirname$1 = (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
 const CONSOLE_DIR = (0, node_path.join)(__dirname$1, "web-console");
-function bindAddressFromArgs(argv) {
-	const flagIndex = argv.indexOf("--bind");
-	return (flagIndex === -1 ? void 0 : argv[flagIndex + 1]) ?? DEFAULT_BIND_ADDRESS;
-}
-/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
-function tlsFromArgs(argv) {
-	const certIndex = argv.indexOf("--tls-cert");
-	const keyIndex = argv.indexOf("--tls-key");
-	const certPath = certIndex === -1 ? void 0 : argv[certIndex + 1];
-	const keyPath = keyIndex === -1 ? void 0 : argv[keyIndex + 1];
-	if (certPath === void 0 && keyPath === void 0) return;
-	if (certPath === void 0 || keyPath === void 0) throw new Error("--tls-cert and --tls-key must be given together");
-	return {
-		certPath,
-		keyPath
-	};
+const PACKAGE_MANIFEST_URL = new URL("../package.json", require("url").pathToFileURL(__filename).href);
+function readPackageVersion() {
+	const manifest = JSON.parse((0, node_fs.readFileSync)(PACKAGE_MANIFEST_URL, "utf-8"));
+	if (typeof manifest !== "object" || manifest === null || !("version" in manifest) || typeof manifest.version !== "string") throw new Error(`no string "version" in ${(0, node_url.fileURLToPath)(PACKAGE_MANIFEST_URL)}`);
+	return manifest.version;
 }
 /** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
 function createHttpRequestHandler(consoleDir) {
@@ -98,29 +180,49 @@ function createHttpRequestHandler(consoleDir) {
 		response.writeHead(HTTP_NOT_FOUND).end();
 	};
 }
-function logStartup(message) {
+function logOutput(message) {
 	console.log(message);
 }
-async function main() {
-	const argv = process.argv.slice(2);
-	const tlsFiles = tlsFromArgs(argv);
-	const tls = tlsFiles ? {
-		certificatePem: (0, node_fs.readFileSync)(tlsFiles.certPath, "utf-8"),
-		privateKeyPem: (0, node_fs.readFileSync)(tlsFiles.keyPath, "utf-8")
+function logError(message) {
+	console.error(message);
+}
+async function main(argv) {
+	const command = parseCliArguments(argv);
+	if (command.kind === "help") {
+		logOutput(helpText());
+		return;
+	}
+	if (command.kind === "version") {
+		logOutput(readPackageVersion());
+		return;
+	}
+	const tls = command.tls ? {
+		certificatePem: (0, node_fs.readFileSync)(command.tls.certPath, "utf-8"),
+		privateKeyPem: (0, node_fs.readFileSync)(command.tls.keyPath, "utf-8")
 	} : void 0;
 	const hub = (0, wire_mesh_core_domain_relay_hub.createRelayHub)();
 	const listener = await require_adapters_node_websocket_transport.createNodeWebSocketTransport({
 		onHttpRequest: createHttpRequestHandler(CONSOLE_DIR),
 		...tls ? { tls } : {}
-	}).listen(bindAddressFromArgs(argv), (connection) => {
+	}).listen(command.bindAddress, (connection) => {
 		hub.handleConnection(connection);
 	});
-	logStartup(`wire-mesh listening on ${tls ? "wss" : "ws"}://${listener.address}`);
+	logOutput(`wire-mesh listening on ${tls ? "wss" : "ws"}://${listener.address}`);
+}
+/** Runs the CLI and turns a failure into a one-line message on stderr and a non-zero exit code, instead of an unhandled rejection's stack trace. */
+async function run(argv) {
+	try {
+		await main(argv);
+	} catch (error) {
+		logError(`wire-mesh: ${error instanceof Error ? error.message : String(error)}`);
+		if (error instanceof CliUsageError) {
+			logError("Run wire-mesh --help for usage.");
+			process.exitCode = EXIT_USAGE;
+		} else process.exitCode = EXIT_FAILURE;
+	}
 }
 const invokedPath = process.argv[1];
-if (invokedPath !== void 0 && (0, node_fs.realpathSync)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)) === (0, node_fs.realpathSync)(invokedPath)) main();
+if (invokedPath !== void 0 && (0, node_fs.realpathSync)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)) === (0, node_fs.realpathSync)(invokedPath)) run(process.argv.slice(2));
 //#endregion
-exports.bindAddressFromArgs = bindAddressFromArgs;
 exports.createHttpRequestHandler = createHttpRequestHandler;
 exports.healthResponse = healthResponse;
-exports.tlsFromArgs = tlsFromArgs;

package/dist/server.d.cts

@@ -5,13 +5,6 @@ export declare function healthResponse(): {
   node: string;
   roles: string[];
 };
-export declare function bindAddressFromArgs(argv: readonly string[]): string;
-export interface TlsFilePaths {
-  certPath: string;
-  keyPath: string;
-}
-/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
-export declare function tlsFromArgs(argv: readonly string[]): TlsFilePaths | undefined;
 /** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
 export declare function createHttpRequestHandler(consoleDir: string): (request: IncomingMessage, response: ServerResponse) => void;
 //#endregion

package/dist/server.d.mts

@@ -5,13 +5,6 @@ export declare function healthResponse(): {
   node: string;
   roles: string[];
 };
-export declare function bindAddressFromArgs(argv: readonly string[]): string;
-export interface TlsFilePaths {
-  certPath: string;
-  keyPath: string;
-}
-/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
-export declare function tlsFromArgs(argv: readonly string[]): TlsFilePaths | undefined;
 /** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
 export declare function createHttpRequestHandler(consoleDir: string): (request: IncomingMessage, response: ServerResponse) => void;
 //#endregion

package/dist/server.mjs

@@ -4,6 +4,98 @@ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, extname, join, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRelayHub } from "wire-mesh-core/domain/relay-hub";
+import { parseArgs } from "node:util";
+//#region src/cli-options.ts
+/** The address the server binds when --bind is not given. */
+const DEFAULT_BIND_ADDRESS = "0.0.0.0:8787";
+const MAX_PORT = 65535;
+/** Every flag the CLI accepts, keyed by its long name (without the leading dashes). */
+const FLAGS = {
+	bind: {
+		type: "string",
+		valueName: "host:port",
+		default: DEFAULT_BIND_ADDRESS,
+		description: "Address to listen on. Port 0 asks the OS for a free port. Use 127.0.0.1:8787 to accept local connections only."
+	},
+	"tls-cert": {
+		type: "string",
+		valueName: "path",
+		description: "PEM certificate file, to serve wss:// and https://. Requires --tls-key."
+	},
+	"tls-key": {
+		type: "string",
+		valueName: "path",
+		description: "PEM private key file for --tls-cert. Requires --tls-cert."
+	},
+	help: {
+		type: "boolean",
+		short: "h",
+		description: "Print this help and exit."
+	},
+	version: {
+		type: "boolean",
+		short: "v",
+		description: "Print the version and exit."
+	}
+};
+/** Thrown for arguments the CLI cannot act on; the message names the offending flag and is fit to print as-is. */
+var CliUsageError = class extends Error {
+	name = "CliUsageError";
+};
+function usageLabelOf(name, definition) {
+	const long = `--${name}${definition.valueName === void 0 ? "" : ` <${definition.valueName}>`}`;
+	return definition.short === void 0 ? `    ${long}` : `-${definition.short}, ${long}`;
+}
+/** The usage text printed for --help, generated from FLAGS. */
+function helpText() {
+	const rows = Object.entries(FLAGS).map(([name, definition]) => ({
+		label: usageLabelOf(name, definition),
+		description: definition.default === void 0 ? definition.description : `${definition.description} (default: ${definition.default})`
+	}));
+	const labelWidth = Math.max(...rows.map((row) => row.label.length));
+	return [
+		"Usage: wire-mesh [options]",
+		"",
+		"Options:",
+		...rows.map((row) => `  ${row.label.padEnd(labelWidth)}  ${row.description}`)
+	].join("\n");
+}
+function validatedBindAddress(address) {
+	const separator = address.lastIndexOf(":");
+	const host = address.slice(0, separator);
+	const port = address.slice(separator + 1);
+	if (separator === -1 || host === "" || !/^\d+$/.test(port) || Number(port) > MAX_PORT) throw new CliUsageError(`--bind expects host:port with a port from 0 to ${String(MAX_PORT)}, got "${address}"`);
+	return address;
+}
+/** Parses the process arguments (without the node and script entries) into the command they ask for. Throws CliUsageError for an unknown flag, a stray positional argument, a flag missing or given an unwanted value, a malformed --bind address, or --tls-cert without --tls-key (or the reverse). */
+function parseCliArguments(argv) {
+	let values;
+	try {
+		({values} = parseArgs({
+			args: [...argv],
+			options: FLAGS,
+			strict: true,
+			allowPositionals: false
+		}));
+	} catch (error) {
+		if (error instanceof Error) throw new CliUsageError(error.message, { cause: error });
+		throw error;
+	}
+	if (values.help === true) return { kind: "help" };
+	if (values.version === true) return { kind: "version" };
+	const certPath = values["tls-cert"];
+	const keyPath = values["tls-key"];
+	if (certPath === void 0 !== (keyPath === void 0)) throw new CliUsageError("--tls-cert and --tls-key must be given together");
+	return {
+		kind: "serve",
+		bindAddress: validatedBindAddress(values.bind),
+		tls: certPath === void 0 || keyPath === void 0 ? void 0 : {
+			certPath,
+			keyPath
+		}
+	};
+}
+//#endregion
 //#region src/static-console.ts
 const CONTENT_TYPES = {
 	".css": "text/css; charset=utf-8",
@@ -53,28 +145,18 @@ function healthResponse() {
 		roles: ["relay"]
 	};
 }
-const DEFAULT_BIND_ADDRESS = "0.0.0.0:8787";
 const HTTP_OK = 200;
 const HTTP_NOT_FOUND = 404;
 const HEALTH_PATH = "/health";
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONSOLE_DIR = join(__dirname, "web-console");
-function bindAddressFromArgs(argv) {
-	const flagIndex = argv.indexOf("--bind");
-	return (flagIndex === -1 ? void 0 : argv[flagIndex + 1]) ?? DEFAULT_BIND_ADDRESS;
-}
-/** Reads --tls-cert/--tls-key from argv, required together — a self-hosted node answering wss:// (wire-mesh#184, so an https://-served PWA can reach it without mixed-content blocking) needs an operator-supplied certificate; this package generates none of its own, matching the README's security note. Returns undefined when neither flag is given, the existing plain-ws:// default. */
-function tlsFromArgs(argv) {
-	const certIndex = argv.indexOf("--tls-cert");
-	const keyIndex = argv.indexOf("--tls-key");
-	const certPath = certIndex === -1 ? void 0 : argv[certIndex + 1];
-	const keyPath = keyIndex === -1 ? void 0 : argv[keyIndex + 1];
-	if (certPath === void 0 && keyPath === void 0) return;
-	if (certPath === void 0 || keyPath === void 0) throw new Error("--tls-cert and --tls-key must be given together");
-	return {
-		certPath,
-		keyPath
-	};
+const PACKAGE_MANIFEST_URL = new URL("../package.json", import.meta.url);
+function readPackageVersion() {
+	const manifest = JSON.parse(readFileSync(PACKAGE_MANIFEST_URL, "utf-8"));
+	if (typeof manifest !== "object" || manifest === null || !("version" in manifest) || typeof manifest.version !== "string") throw new Error(`no string "version" in ${fileURLToPath(PACKAGE_MANIFEST_URL)}`);
+	return manifest.version;
 }
 /** Builds the listener's onHttpRequest handler: /health answers the same JSON shape healthResponse() returns, everything else resolves against consoleDir via resolveConsoleFile. Takes consoleDir as a parameter, not a module-level constant, so a test can point it at a temp fixture instead of the real build-time CONSOLE_DIR. */
 function createHttpRequestHandler(consoleDir) {
@@ -97,26 +179,48 @@ function createHttpRequestHandler(consoleDir) {
 		response.writeHead(HTTP_NOT_FOUND).end();
 	};
 }
-function logStartup(message) {
+function logOutput(message) {
 	console.log(message);
 }
-async function main() {
-	const argv = process.argv.slice(2);
-	const tlsFiles = tlsFromArgs(argv);
-	const tls = tlsFiles ? {
-		certificatePem: readFileSync(tlsFiles.certPath, "utf-8"),
-		privateKeyPem: readFileSync(tlsFiles.keyPath, "utf-8")
+function logError(message) {
+	console.error(message);
+}
+async function main(argv) {
+	const command = parseCliArguments(argv);
+	if (command.kind === "help") {
+		logOutput(helpText());
+		return;
+	}
+	if (command.kind === "version") {
+		logOutput(readPackageVersion());
+		return;
+	}
+	const tls = command.tls ? {
+		certificatePem: readFileSync(command.tls.certPath, "utf-8"),
+		privateKeyPem: readFileSync(command.tls.keyPath, "utf-8")
 	} : void 0;
 	const hub = createRelayHub();
 	const listener = await createNodeWebSocketTransport({
 		onHttpRequest: createHttpRequestHandler(CONSOLE_DIR),
 		...tls ? { tls } : {}
-	}).listen(bindAddressFromArgs(argv), (connection) => {
+	}).listen(command.bindAddress, (connection) => {
 		hub.handleConnection(connection);
 	});
-	logStartup(`wire-mesh listening on ${tls ? "wss" : "ws"}://${listener.address}`);
+	logOutput(`wire-mesh listening on ${tls ? "wss" : "ws"}://${listener.address}`);
+}
+/** Runs the CLI and turns a failure into a one-line message on stderr and a non-zero exit code, instead of an unhandled rejection's stack trace. */
+async function run(argv) {
+	try {
+		await main(argv);
+	} catch (error) {
+		logError(`wire-mesh: ${error instanceof Error ? error.message : String(error)}`);
+		if (error instanceof CliUsageError) {
+			logError("Run wire-mesh --help for usage.");
+			process.exitCode = EXIT_USAGE;
+		} else process.exitCode = EXIT_FAILURE;
+	}
 }
 const invokedPath = process.argv[1];
-if (invokedPath !== void 0 && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(invokedPath)) main();
+if (invokedPath !== void 0 && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(invokedPath)) run(process.argv.slice(2));
 //#endregion
-export { bindAddressFromArgs, createHttpRequestHandler, healthResponse, tlsFromArgs };
+export { createHttpRequestHandler, healthResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "bin": {
     "wire-mesh": "./dist/server.mjs"
   },