@mailwoman/map-tui 9.1.1 → 9.3.0

package/lib/cli-args.ts

@@ -0,0 +1,233 @@
+import { errorMessage } from "@mailwoman/core/errors/schema"
+import { parseArguments } from "@mailwoman/core/scripting/arguments"
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * Argument parsing for the `map-tui` bin.
+ *
+ * `parseCLIArgs` is pure: it takes the argv slice and an environment record, and answers with a discriminated result
+ * (`help` / `version` / `browse`) or throws {@link CLIArgsError}. Reading `process.argv` / `process.env` is the bin's
+ * job (./cli.ts), which keeps every rejection path testable without a subprocess.
+ */
+
+/**
+ * Center longitude when `--lon` is omitted — the world view mapscii opens on.
+ */
+const DEFAULT_LON = 0
+
+/**
+ * Center latitude when `--lat` is omitted.
+ */
+const DEFAULT_LAT = 0
+
+/**
+ * Zoom when `--zoom` is omitted. z2 shows a full hemisphere in a typical terminal, so a planet archive opens on
+ * something recognizable rather than a single ocean tile.
+ */
+const DEFAULT_ZOOM = 2
+
+/**
+ * Widest zoom any tile archive uses.
+ */
+const MIN_ZOOM = 0
+
+/**
+ * Deepest zoom the Web-Mercator tile pyramid is defined for. The archive's own `maxZoom` clamps further at runtime;
+ * this is only the range a flag value must fall inside to be meaningful at all.
+ */
+const MAX_ZOOM = 24
+
+// True geographic bounds, not Web-Mercator's ±85.05113: the flag accepts any real latitude, and the browser clamps
+// the CENTER to the projection's MERCATOR_LATITUDE_LIMIT itself (see ./browser.ts) — rejecting 87 here would refuse a
+// value the viewport handles fine.
+const MIN_LAT = -90
+const MAX_LAT = 90
+const MIN_LON = -180
+const MAX_LON = 180
+
+/**
+ * A view request: an archive to read and where to open it.
+ */
+export interface BrowseArgs {
+	mode: "browse"
+	/**
+	 * Path to the PMTiles archive.
+	 */
+	tiles: string
+	lat: number
+	lon: number
+	/**
+	 * Integer zoom level. The renderer draws whole tile-pyramid levels, so a fractional flag value is rounded here rather
+	 * than carried as a lie through the viewport.
+	 */
+	zoom: number
+}
+
+export type CLIArgs = { mode: "help" } | { mode: "version" } | BrowseArgs
+
+/**
+ * A rejected command line. The message is user-facing: it says what was wrong AND what to pass instead, since the bin
+ * prints it verbatim to stderr.
+ */
+export class CLIArgsError extends Error {
+	override name = "CLIArgsError"
+}
+
+/**
+ * Environment keys the CLI reads. Passed in rather than read here so the parser stays pure.
+ */
+export interface CLIEnvironment {
+	MAILWOMAN_TILES?: string | undefined
+}
+
+/**
+ * `--help` output. It doubles as the package's key reference, so the bindings listed here and the ones ./input.ts
+ * decodes are the same list said twice — a key added there without a line here is a key nobody finds.
+ */
+export const HELP_TEXT = `map-tui — the whole world in your terminal
+
+Usage
+  npx @mailwoman/map-tui --tiles <archive.pmtiles> [options]
+
+Options
+  --tiles <path|url>  PMTiles archive — local path or https:// URL (default: $MAILWOMAN_TILES)
+  --lat <degrees>   Initial center latitude, -90..90 (default: ${DEFAULT_LAT})
+  --lon <degrees>   Initial center longitude, -180..180 (default: ${DEFAULT_LON})
+  --zoom <level>    Initial zoom, ${MIN_ZOOM}..${MAX_ZOOM} (default: ${DEFAULT_ZOOM})
+  -h, --help        Print this help and exit
+  -v, --version     Print the package version and exit
+
+Keys
+  arrows, hjkl      Pan
+  +, =, a           Zoom in
+  -, _, z           Zoom out
+  q, Esc, Ctrl+C    Quit
+
+Mouse
+  Wheel zooms toward the pointer, drag pans, click centers.
+
+Tiles are never bundled with this package. Download a planet or region
+archive from https://protomaps.com/downloads and point --tiles at it.
+`
+
+/**
+ * Reads one numeric flag, rejecting anything `Number` would quietly accept as garbage (empty string, whitespace,
+ * `Infinity`) as well as out-of-range values.
+ */
+function numericFlag(name: string, raw: string | undefined, fallback: number, min: number, max: number): number {
+	if (raw == null) return fallback
+
+	const value = Number(raw.trim())
+
+	if (!Number.isFinite(value) || !raw.trim().length) {
+		throw new CLIArgsError(`--${name} expects a number, got ${JSON.stringify(raw)}`)
+	}
+
+	if (value < min || value > max) {
+		throw new CLIArgsError(`--${name} must be between ${min} and ${max}, got ${value}`)
+	}
+
+	return value
+}
+
+/**
+ * Flags whose value is a number, and may therefore start with a dash.
+ */
+const NUMERIC_FLAGS = new Set(["--lat", "--lon", "--zoom"])
+
+/**
+ * Joins `--lon -122.6` into `--lon=-122.6` before `parseArgs` sees it.
+ *
+ * `node:util`'s parser refuses a separate value that starts with a dash — it cannot tell a negative number from a
+ * mistyped flag, and says so ("argument is ambiguous"). Half the planet has a negative longitude, so the space-form has
+ * to work. The join is conditional on the next token parsing as a finite number, which leaves a genuinely missing value
+ * (`--lon --zoom 3`) to `parseArgs` and its own error.
+ */
+function joinNegativeNumbers(argv: readonly string[]): string[] {
+	const joined: string[] = []
+
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index]!
+		const next = argv[index + 1]
+
+		if (NUMERIC_FLAGS.has(token) && next?.startsWith("-") && Number.isFinite(Number(next))) {
+			joined.push(`${token}=${next}`)
+			index += 1
+
+			continue
+		}
+
+		joined.push(token)
+	}
+
+	return joined
+}
+
+interface ParsedFlags {
+	tiles?: string | undefined
+	lat?: string | undefined
+	lon?: string | undefined
+	zoom?: string | undefined
+	help?: boolean | undefined
+	version?: boolean | undefined
+}
+
+/**
+ * `node:util`'s own rejections (unknown flag, missing value) name the flag but not the remedy, so they're re-thrown as
+ * a {@link CLIArgsError} pointing at `--help`.
+ */
+function readFlags(argv: readonly string[]): ParsedFlags {
+	try {
+		const { values } = parseArguments({
+			args: joinNegativeNumbers(argv),
+			options: {
+				tiles: { type: "string" },
+				lat: { type: "string" },
+				lon: { type: "string" },
+				zoom: { type: "string" },
+				help: { type: "boolean", short: "h" },
+				version: { type: "boolean", short: "v" },
+			},
+			allowPositionals: false,
+			strict: true,
+		})
+
+		return values
+	} catch (error) {
+		throw new CLIArgsError(`${errorMessage(error)}\nRun \`map-tui --help\` for the supported flags.`)
+	}
+}
+
+/**
+ * Parses a `map-tui` command line.
+ *
+ * @throws {CLIArgsError} On an unknown flag, an unparseable or out-of-range number, or a missing archive path.
+ */
+export function parseCLIArgs(argv: readonly string[], environment: CLIEnvironment = {}): CLIArgs {
+	const values = readFlags(argv)
+
+	if (values.help) return { mode: "help" }
+
+	if (values.version) return { mode: "version" }
+
+	const tiles = (values.tiles ?? environment.MAILWOMAN_TILES ?? "").trim()
+
+	if (!tiles.length) {
+		throw new CLIArgsError(
+			"No tile archive: pass --tiles <archive.pmtiles> or set MAILWOMAN_TILES.\n" +
+				"Planet and region archives: https://protomaps.com/downloads"
+		)
+	}
+
+	return {
+		mode: "browse",
+		tiles,
+		lat: numericFlag("lat", values.lat, DEFAULT_LAT, MIN_LAT, MAX_LAT),
+		lon: numericFlag("lon", values.lon, DEFAULT_LON, MIN_LON, MAX_LON),
+		zoom: Math.round(numericFlag("zoom", values.zoom, DEFAULT_ZOOM, MIN_ZOOM, MAX_ZOOM)),
+	}
+}

package/lib/cli.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * The `map-tui` bin — `npx @mailwoman/map-tui` opens a PMTiles archive as a full-screen terminal map.
+ *
+ * This file owns everything process-shaped so the rest of the package stays testable without one: argv and the
+ * environment (parsed by ./cli-args.ts), the archive handle, signal handlers, and the exit code. `MapBrowser` takes
+ * streams rather than reaching for `process` itself, which is what lets the PTY smoke test drive the real bin and a
+ * unit test drive the parser with neither.
+ *
+ * Signal handling is not optional here. This is a raw-mode app on the alternate screen with mouse reporting on, and
+ * there is no framework underneath to put any of that back — a process killed between `start` and `restore` leaves the
+ * user with an unusable shell. So `restore` is wired to SIGINT, SIGTERM and `exit`, and it is idempotent for exactly
+ * that reason.
+ */
+
+import { errorMessage } from "@mailwoman/core/errors/schema"
+import { createRequire } from "@mailwoman/core/module/resolvers"
+
+import { MapBrowser } from "#browser"
+import { type CLIArgs, CLIArgsError, HELP_TEXT, parseCLIArgs } from "#cli-args"
+import { TileSource } from "#tile-source"
+
+/**
+ * Exit code for a command line that could not be parsed.
+ */
+const EXIT_USAGE = 1
+
+/**
+ * Reads the package's own version.
+ *
+ * Self-reference (`@mailwoman/map-tui/...`, which the package's `exports` publishes) rather than a path relative to
+ * this file: the bin runs from `out/` when installed and from the workspace root in development, and only the package
+ * graph knows which. `createRequire` parses the JSON itself, so no reader here has to.
+ */
+function readVersion(): string {
+	const require = createRequire(import.meta.url)
+	const manifest = require("@mailwoman/map-tui/package.json") as { version?: string }
+
+	return manifest.version ?? "0.0.0"
+}
+
+/**
+ * Opens the archive, translating the filesystem's error into something that names the flag that was wrong.
+ */
+async function openTiles(path: string): Promise<TileSource> {
+	try {
+		return await TileSource.open(path)
+	} catch (error) {
+		throw new CLIArgsError(
+			`Could not open the tile archive at ${path}: ${errorMessage(error)}\n` +
+				"Pass --tiles <archive.pmtiles>, or download one from https://protomaps.com/downloads"
+		)
+	}
+}
+
+/**
+ * Runs the interactive browser against an already-open archive, resolving with its exit code.
+ */
+async function browse(source: TileSource, args: { lat: number; lon: number; zoom: number }): Promise<number> {
+	const browser = new MapBrowser({
+		source,
+		input: process.stdin,
+		output: process.stdout,
+		lat: args.lat,
+		lon: args.lon,
+		zoom: args.zoom,
+	})
+
+	const onSignal = (): void => browser.requestExit(130)
+	const onExit = (): void => browser.restore()
+
+	process.on("SIGINT", onSignal)
+	process.on("SIGTERM", onSignal)
+	process.on("exit", onExit)
+
+	try {
+		return await browser.run()
+	} finally {
+		browser.restore()
+		process.off("SIGINT", onSignal)
+		process.off("SIGTERM", onSignal)
+		process.off("exit", onExit)
+	}
+}
+
+async function main(): Promise<number> {
+	let args: CLIArgs
+
+	try {
+		/**
+		 * `parseCLIArgs` keeps argv and the environment read on this one line, and nowhere else in the package —
+		 * `@mailwoman/core/env`'s typed readers would pull core's data-backed environment schema behind a CLI whose whole
+		 * premise is `npx`, so the bin passes the raw records to the pure parser instead.
+		 */
+		// oxlint-disable-next-line sister-software/no-process-globals -- see above.
+		args = parseCLIArgs(process.argv.slice(2), process.env)
+	} catch (error) {
+		if (!(error instanceof CLIArgsError)) throw error
+
+		process.stderr.write(`${error.message}\n`)
+
+		return EXIT_USAGE
+	}
+
+	if (args.mode === "help") {
+		process.stdout.write(HELP_TEXT)
+
+		return 0
+	}
+
+	if (args.mode === "version") {
+		process.stdout.write(`${readVersion()}\n`)
+
+		return 0
+	}
+
+	let opened: TileSource
+
+	// A bad `--tiles` path is a usage error, not a crash — the guard stays around the open, and ownership passes to the
+	// `using` declaration only once the open succeeded.
+	try {
+		opened = await openTiles(args.tiles)
+	} catch (error) {
+		process.stderr.write(`${errorMessage(error)}\n`)
+
+		return EXIT_USAGE
+	}
+
+	await using source = opened
+
+	return await browse(source, args)
+}
+
+process.exitCode = await main()

package/{frame.ts → lib/frame.ts}

@@ -11,15 +11,13 @@
  * per cell. The braille dither/luminance work is asciify's — `FrameRasterizer` subclasses `AsciifyTerminal` with a
  * no-op sink purely to reach its protected `_computeBrailleCells`, `_cellChars`, `_cellColors`, so this module never
  * re-implements the dot math. `frameToANSILines` and `overlayText` then work on the plain `MapFrame` value, with no
- * further asciify dependency.
+ * further asciify dependency; `blitFrame` is the path back the other way, for callers driving a live terminal.
  */
 
-import { AsciifyTerminal } from "@sister.software/asciify/tui"
+import { AsciifyTerminal, SGR_RESET } from "@sister.software/asciify/tui"
 
-import type { RGBAGrid } from "./raster.ts"
-import type { RGB } from "./style.ts"
-
-const SGR_RESET = "\u001B[0m"
+import type { RGBAGrid } from "#raster"
+import type { RGB } from "#style"
 
 /**
  * A rendered braille frame: one codepoint and one packed color per cell, row-major.
@@ -168,3 +166,32 @@ export function overlayText(
 export function rgbToPacked(color: RGB): number {
 	return (color[0] << 16) | (color[1] << 8) | color[2]
 }
+
+/**
+ * Codepoint written for a cell the frame left empty. `MapFrame` stores 0 there; `AsciifyTerminal` expects a real
+ * character, and normalizes a space to the inkless color itself.
+ */
+const SPACE_CODEPOINT = 0x20
+
+/**
+ * Writes a frame's cells into an `AsciifyTerminal`'s current frame. Call `flush()` afterwards to emit the damage.
+ *
+ * The frame's packed color is the exact representation asciify canonicalizes truecolor to, so this is a copy and not a
+ * conversion — the channels are unpacked here only because {@linkcode AsciifyTerminal.setCell} takes them apart. Cells
+ * beyond the terminal's own grid are dropped by `setCell`, so a frame larger than the pane clips rather than throws.
+ */
+export function blitFrame(terminal: AsciifyTerminal, frame: MapFrame): void {
+	for (let row = 0; row < frame.rows; row++) {
+		for (let column = 0; column < frame.columns; column++) {
+			const cellIndex = row * frame.columns + column
+			const char = frame.chars[cellIndex]!
+			const color = frame.colors[cellIndex]!
+
+			terminal.setCell(column, row, char === 0 ? SPACE_CODEPOINT : char, [
+				(color >> 16) & 0xff,
+				(color >> 8) & 0xff,
+				color & 0xff,
+			])
+		}
+	}
+}

package/lib/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#frame"
+export * from "#mercator"
+export * from "#mvt"
+export * from "#raster"
+export * from "#renderer"
+export * from "#style"
+export * from "#tile-source"