mailwoman 8.6.0 → 9.1.0

package/README.md

@@ -170,7 +170,7 @@ Programmatically, build a `WofSqlitePlaceLookup` backend (from
 `@mailwoman/resolver-wof-sqlite`), pass it to `createWOFResolver` (from `@mailwoman/resolver`),
 and hand the resolver to `createRuntimePipeline({ classifier, resolver })`. The resolved
 `result.tree` roots then carry a `wof:id` and coordinate. See
-[Getting started → Adding resolution](https://mailwoman.sister.software/articles/getting-started/)
+[Getting started → Adding resolution](https://mailwoman.sister.software/docs/developers/get-started/install-and-first-parse)
 for the worked example.
 
 ## Architecture
@@ -210,7 +210,7 @@ package is the umbrella that wires them together as a single `npm install`.
 ## Related
 
 - [Documentation & blog](https://mailwoman.sister.software)
-- [What Mailwoman Is](https://mailwoman.sister.software/articles/concepts/what-mailwoman-is/)
+- [What Mailwoman Is](https://mailwoman.sister.software/docs/developers/get-started/what-mailwoman-is)
 - [GitHub](https://github.com/sister-software/mailwoman)
 
 ## License

package/api-engine.ts

@@ -8,7 +8,7 @@
  *   `/api/batch`, `/api/resolve-tree`, `/api/reload` handlers, `AddressRouter`'s retired `/parse`
  *   handler, and `HealthRouter`'s `/health` data block — onto the engine-agnostic `@mailwoman/api`
  *   contract's live routes (`/v1/parse`, `/v1/geocode`, `/v1/batch`, `/v1/resolve`, `/v1/reload`).
- *   `mailwoman/server/` is deleted (Task 2) — this file is its sole successor, a fresh port rather
+ *   `mailwoman/server/` is deleted — this file is its sole successor, a fresh port rather
  *   than a thin wrapper.
  *
  *   `createServeEngine` builds the shared stack ONCE, at boot, instead of express's lazy
@@ -26,14 +26,14 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { createRequire } from "node:module"
-import { join } from "node:path"
+import { fileURLToPath } from "node:url"
 
 import type { BatchRow, GeocodeOutcome, HealthData, MailwomanAPIEngine, ResolveTreeOutcome } from "@mailwoman/api"
 import { recordTimed } from "@mailwoman/api-kit"
 import { decodeAsTuples, decodeAsXML } from "@mailwoman/core"
 import type { AddressTree } from "@mailwoman/core/decoder"
 import { $public } from "@mailwoman/core/env"
+import { tryParsingJSON } from "@mailwoman/core/objects"
 import { deriveInputMode } from "@mailwoman/core/pipeline"
 import { classifyKindSync } from "@mailwoman/kind-classifier"
 import { computeQueryShape } from "@mailwoman/query-shape"
@@ -48,7 +48,13 @@ import {
 	ShardProvider,
 } from "./geocode-core.ts"
 import { INTERP_RADIUS_CALIBRATION, interpCalibrationForRegion } from "./interp-calibration.ts"
-import { createResolverBackend, mailwomanDataRoot, resolveCandidateDBPath, wofShardPaths } from "./resolver-backend.ts"
+import {
+	buildNoGazetteerMessage,
+	createResolverBackend,
+	mailwomanDataRoot,
+	resolveCandidateDBPath,
+	wofShardPaths,
+} from "./resolver-backend.ts"
 
 /**
  * Default per-state shard root + interp calibration — mirrors the express server's defaults (`GeocodeRouter.ts`).
@@ -82,30 +88,13 @@ function wofPaths(): string[] {
 
 /**
  * #1009-style boot preflight message. Same shape as the drop-ins' (`photon/cli.ts`, `nominatim/cli.ts`) — a stranger's
- * first `mailwoman serve` must say exactly what data is missing and the one command that fixes it — adapted to this
- * package's own override (`MAILWOMAN_WOF_DB`, a comma-separated FTS shard list) alongside the shared
- * candidate-gazetteer fast path (`MAILWOMAN_CANDIDATE_DB`).
+ * first `mailwoman serve` must say exactly what data is missing and the one command that fixes it.
  */
 function buildPreflightMessage(): string {
-	const conventionCandidate = join(DATA_ROOT, "wof", "candidate.db")
-
-	return [
-		"✗ no gazetteer data found — `mailwoman serve` needs a WOF SQLite distribution to geocode/resolve.",
-		"",
-		"  Fastest path (worldwide resolution, ~1.4 GB, byte-range friendly):",
-		`    mkdir -p ${join(DATA_ROOT, "wof")}`,
-		`    curl -fSL https://public.sister.software/mailwoman/gazetteer/2026-07-07a/candidate.db \\`,
-		`      -o ${conventionCandidate}`,
-		"",
-		"  Then point `$MAILWOMAN_CANDIDATE_DB` at that file and re-run `serve`:",
-		`    export MAILWOMAN_CANDIDATE_DB=${conventionCandidate}`,
-		"",
-		"  Or point at your own gazetteer:",
-		"    $MAILWOMAN_WOF_DB=<path1,path2,...>    (admin WOF SQLite shard(s) — the FTS backend)",
-		"    $MAILWOMAN_CANDIDATE_DB=<path>         (candidate-table gazetteer — population-first, demo-parity)",
-		"",
-		"  Docs: https://mailwoman.sister.software/docs",
-	].join("\n")
+	return buildNoGazetteerMessage({
+		dataRoot: DATA_ROOT,
+		docsPath: "/docs/developers/get-started/ten-minute-trial",
+	})
 }
 
 /**
@@ -120,7 +109,13 @@ function readModelCard(): Record<string, unknown> | null {
 	}
 
 	try {
-		candidates.push(createRequire(import.meta.url).resolve("@mailwoman/neural-weights-en-us/model-card.json"))
+		// Native ESM resolution of the weights package's card. `@mailwoman/neural-weights-*` packages carry no `exports`
+		// map, so the subpath resolves as a plain file inside the package, and (unlike `node:module`'s
+		// `findPackageJSON`) `import.meta.resolve` realpaths through the workspace symlink — the same string the CJS
+		// `require.resolve` this replaced returned. It does NOT throw for a missing FILE inside a resolvable package,
+		// only for an unresolvable package; the `existsSync` below already gates every candidate, so that is a no-op
+		// here.
+		candidates.push(fileURLToPath(import.meta.resolve("@mailwoman/neural-weights-en-us/model-card.json")))
 	} catch {
 		/* package not resolvable from here — fall through */
 	}
@@ -129,9 +124,13 @@ function readModelCard(): Record<string, unknown> | null {
 
 	for (const p of candidates) {
 		try {
-			if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8")) as Record<string, unknown>
+			if (existsSync(p)) {
+				const card = tryParsingJSON<Record<string, unknown>>(readFileSync(p, "utf8"))
+
+				if (card) return card
+			}
 		} catch {
-			/* unreadable / malformed — try the next candidate */
+			/* unreadable — try the next candidate */
 		}
 	}
 
@@ -325,7 +324,7 @@ export async function createServeEngine(): Promise<ServeEngine> {
 	// `onnxruntime-node`'s `session.run()` blocks the JS thread rather than releasing to the libuv pool,
 	// and `node:sqlite` reads are synchronous. The pool bought nothing but the appearance of tuning, so
 	// it's a plain loop now. To actually parallelize, cross a thread boundary — see
-	// `mailwoman/geocode-stream.ts`. Receipts: `docs/articles/plan/reference/performance.mdx`.
+	// `mailwoman/geocode-stream.ts`. Receipts: `docs/engineering/reference/performance.mdx`.
 	const batch: MailwomanAPIEngine["batch"] = async (addresses, opts) => {
 		// Decision A endpoint default: batch rows are the record register.
 		const inputMode = opts?.inputMode ?? "formatted"

package/cli-kit/dropin.ts

@@ -0,0 +1,195 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The shared skeleton behind the drop-in CLIs — `mailwoman-libpostal`, `mailwoman-nominatim`,
+ *   `mailwoman-photon`. All three are the same program with a different engine bolted in: dispatch
+ *   `serve` / `openapi` off the first positional, boot the neural classifier with a friendly
+ *   failure, (for the two geocoding drop-ins) locate a gazetteer with a friendly failure, then print
+ *   a banner. Those pieces were copied between the three files, and the copies were being kept in
+ *   sync BY HAND — nominatim/cli.ts said so in a comment ("same message shape as
+ *   @mailwoman/photon's pre-flight (kept in lockstep)"). This module is the lockstep.
+ *
+ *   WHY IT LIVES HERE and not in `@mailwoman/api-kit`, which already owns `printOpenAPIDocument` and
+ *   `serveNode` and would otherwise be the obvious home: the preflights need `@mailwoman/neural` and
+ *   this package's `resolver-backend`, and api-kit is engine-agnostic by charter. Splitting the
+ *   skeleton across two packages to preserve that charter costs more than the duplication did. All
+ *   three drop-ins already declare `mailwoman` as a dependency, so landing the whole thing here adds
+ *   no dependency to anyone.
+ *
+ *   WHY IT IS NOT IN `cli-kit/index.ts`: that barrel is the Pastel/Ink toolkit for
+ *   `mailwoman/commands/*` and imports `ink` + `react`. The drop-ins are plain `parseArgs` scripts
+ *   that render no UI, and `npx @mailwoman/libpostal serve` should not pay for a TUI runtime to
+ *   start an HTTP server. Hence a standalone module with its own `mailwoman/cli-kit/dropin`
+ *   subpath, deliberately NOT re-exported through the barrel.
+ */
+
+import { existsSync } from "node:fs"
+import { parseArgs } from "node:util"
+
+import { NeuralAddressClassifier } from "@mailwoman/neural"
+
+import {
+	buildNoGazetteerMessage,
+	mailwomanDataRoot,
+	resolveCandidateDBPath,
+	wofShardPaths,
+} from "../resolver-backend.ts"
+
+/**
+ * The docs page every drop-in's missing-gazetteer message points a stranger at (#1009). One constant so the three
+ * messages cannot drift onto different pages when the docs move.
+ */
+const GAZETTEER_DOCS_PATH = "/docs/developers/get-started/ten-minute-trial"
+
+/**
+ * Print an error and exit non-zero. Typed `never` so callers get definite-assignment narrowing after the call.
+ */
+function fail(message: string): never {
+	console.error(message)
+
+	process.exit(1)
+}
+
+/**
+ * Parse the `openapi` subcommand's flags, validating `--flavor`. Exits 1 with the binary's usage line on a bad flavor.
+ *
+ * Returns the shape `printOpenAPIDocument` takes, so a drop-in's `openapi` command is this call plus building its app
+ * around a stub engine — which is what keeps the command pure route-table introspection that never boots a classifier
+ * or opens a gazetteer.
+ */
+export function parseOpenAPIFlags(binaryName: string): { flavor?: string; out?: string } {
+	const { values } = parseArgs({
+		options: {
+			flavor: { type: "string", default: "3.1" },
+			out: { type: "string" },
+		},
+		allowPositionals: true,
+	})
+
+	if (values.flavor !== "3.1" && values.flavor !== "3.0") {
+		console.error(`✗ --flavor must be "3.1" or "3.0" (got "${values.flavor}")`)
+
+		fail(`Usage: ${binaryName} openapi [--flavor 3.1|3.0] [--out <path>]`)
+	}
+
+	return values
+}
+
+/**
+ * Load the en-US neural classifier, failing FRIENDLY (#1009).
+ *
+ * `resolveWeights` (`neural/weights.ts`) already names the exact fix command; this guard only keeps that message from
+ * being buried under an unhandled-rejection stack trace. Eager, so a missing-weights boot fails at startup rather than
+ * on the first request.
+ */
+export async function loadClassifierOrExit(): Promise<NeuralAddressClassifier> {
+	try {
+		return await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" })
+	} catch (error) {
+		return fail(`✗ ${error instanceof Error ? error.message : String(error)}`)
+	}
+}
+
+/**
+ * Where a geocoding drop-in reads its places from.
+ */
+export interface GazetteerPaths {
+	/**
+	 * The candidate gazetteer (worldwide resolution), when one was found.
+	 */
+	candidateDb: string | undefined
+	/**
+	 * The WOF admin FTS shards that exist on disk.
+	 */
+	wofPaths: string[]
+	/**
+	 * The first shard — the admin DB the reverse geocoder opens. `undefined` when there are no shards.
+	 */
+	adminDBPath: string | undefined
+}
+
+/**
+ * Locate the gazetteer for a geocoding drop-in, with both of the #1009 friendly failures:
+ *
+ * - An EXPLICIT `--candidate-db` that does not exist errors loudly. It must never silently fall back to whatever ambient
+ *   data-root file happens to be present — a typo'd path would otherwise serve the wrong gazetteer without a word.
+ * - No candidate DB AND no shards prints the named-artifact message with the one command that fixes it, instead of
+ *   letting the resolver throw its internal "resolveShards: at least one shard is required".
+ */
+export function resolveGazetteerOrExit(candidateDBFlag: string | undefined): GazetteerPaths {
+	if (candidateDBFlag && !existsSync(candidateDBFlag)) {
+		fail(`✗ --candidate-db not found: ${candidateDBFlag}`)
+	}
+
+	const wofPaths = wofShardPaths().filter(existsSync)
+	// Candidate gazetteer = worldwide resolution (population-first ranking + global coverage + the FTS5-trigram typo
+	// fallback). --candidate-db, else $MAILWOMAN_CANDIDATE_DB, else the `<data-root>/wof/candidate.db` convention
+	// path. Absent → the admin FTS shards.
+	const candidateDb = resolveCandidateDBPath(candidateDBFlag)
+
+	if (!candidateDb && !wofPaths.length) {
+		fail(buildNoGazetteerMessage({ dataRoot: mailwomanDataRoot(), docsPath: GAZETTEER_DOCS_PATH }))
+	}
+
+	return { adminDBPath: wofPaths[0], candidateDb, wofPaths }
+}
+
+/**
+ * The `cors:` line of a drop-in's startup banner.
+ */
+export function corsBannerLine(cors: boolean): string {
+	return `  cors: ${cors ? "enabled (Access-Control-Allow-Origin: *)" : "disabled (--no-cors)"}`
+}
+
+/**
+ * The `wof:` + `resolver:` lines of a geocoding drop-in's startup banner — which gazetteer the process actually opened,
+ * and (when it fell back to admin-only) the flag that widens it.
+ */
+export function gazetteerBannerLines({ adminDBPath, candidateDb }: GazetteerPaths): string[] {
+	return [
+		`  wof: ${adminDBPath ?? "(none found — set MAILWOMAN_WOF_DB)"}`,
+		candidateDb
+			? `  resolver: candidate gazetteer (worldwide) — ${candidateDb}`
+			: `  resolver: admin-only (US-optimized) — point --candidate-db / $MAILWOMAN_CANDIDATE_DB at a candidate gazetteer for worldwide`,
+	]
+}
+
+/**
+ * A drop-in CLI's two subcommands.
+ */
+export interface DropInCLI {
+	/**
+	 * The binary name, for the usage message (e.g. `mailwoman-photon`).
+	 */
+	binaryName: string
+	/**
+	 * Usage lines for the subcommands, without the leading `Usage:` header.
+	 */
+	usage: string[]
+	serve: () => Promise<void>
+	openapi: () => void
+}
+
+/**
+ * Dispatch a drop-in CLI's subcommand off the first positional.
+ *
+ * `strict: false` because the per-command parsers own their own flags — this pass only reads the positional. An unknown
+ * command exits 1; a bare invocation prints usage and exits 0.
+ */
+export async function runDropInCLI({ binaryName, openapi, serve, usage }: DropInCLI): Promise<void> {
+	const command = parseArgs({ strict: false, allowPositionals: true }).positionals[0]
+
+	switch (command) {
+		case "serve":
+			await serve()
+			break
+		case "openapi":
+			openapi()
+			break
+		default:
+			console.error([`Usage: ${binaryName} <command>`, ...usage].join("\n"))
+			process.exit(command ? 1 : 0)
+	}
+}

package/cli-kit/index.ts

@@ -2,130 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The command toolkit for `mailwoman/commands/*` — Pastel/Ink helper types, the one-shot
- *   {@linkcode useCommandTask} runner, and the {@linkcode CheckList} renderer. Lives OUTSIDE
- *   `commands/` (Pastel treats every file there as a command) and OUTSIDE `sdk/` (`sdk/` submodules
- *   mean data acquisition). Built with `createElement`, not JSX, so the module stays plain `.ts` —
- *   importable under node's type stripping (the dev `node →` exports condition).
  */
 
-import { Box, Text } from "ink"
-import { createElement as h, useEffect, useState } from "react"
-import type * as React from "react"
-import type * as zod from "zod"
-
-/**
- * Type-helper to infer the positional arguments of a command.
- */
-export interface PositionalArguments<T extends zod.ZodTypeAny> {
-	args: zod.infer<T>
-}
-
-/**
- * React component for a command with positional arguments.
- */
-export type PositionalCommandComponent<T extends zod.ZodTypeAny> = React.FC<PositionalArguments<T>>
-
-/**
- * Type-helper to infer the options of a command.
- */
-export interface CommandProps<
-	OptionProps extends zod.ZodObject,
-	PositionalProps extends zod.ZodTypeAny | unknown = unknown,
-> {
-	options: zod.infer<OptionProps>
-	args: PositionalProps extends zod.ZodTypeAny ? zod.infer<PositionalProps> : unknown[]
-}
-
-/**
- * React component for a command with options.
- */
-export type CommandComponent<
-	OptionProps extends zod.ZodObject,
-	PositionalProps extends zod.ZodTypeAny | unknown = unknown,
-> = React.FC<CommandProps<OptionProps, PositionalProps>>
-
-/**
- * The lifecycle of a command's one-shot async task.
- */
-export type CommandTaskState<T> =
-	| { status: "running" }
-	| { status: "done"; result: T }
-	| { status: "error"; message: string }
-
-/**
- * Run a command's one-shot async task and own the exit-code discipline: rejection renders the error state and exits 1;
- * resolution exits with `exitCode(result)` (default 0) — always AFTER the final frame committed. Replaces the
- * copy-pasted useEffect/useState/setImmediate dance in every command.
- */
-/* oxlint-disable react-hooks/exhaustive-deps -- One-shot by design: the task/exitCode closures
-   capture their options at mount; tracking them (fresh closure per render) would re-run the task
-   every render. The empty/[state] deps are the point. */
-export function useCommandTask<T>(task: () => Promise<T>, exitCode?: (result: T) => number): CommandTaskState<T> {
-	const [state, setState] = useState<CommandTaskState<T>>({ status: "running" })
-
-	useEffect(() => {
-		void task().then(
-			(result) => setState({ status: "done", result }),
-			(error: unknown) =>
-				setState({ status: "error", message: error instanceof Error ? (error.stack ?? error.message) : String(error) })
-		)
-	}, [])
-
-	useEffect(() => {
-		if (state.status === "running") return
-		const code = state.status === "error" ? 1 : (exitCode?.(state.result) ?? 0)
-		setImmediate(() => process.exit(code))
-	}, [state])
-
-	return state
-}
-
-/* oxlint-enable react-hooks/exhaustive-deps */
-
-/**
- * Build a guidance-grade error whose rendered form is exactly `message` — no stack. {@linkcode useCommandTask} renders
- * `error.stack ?? error.message`, which is right for unexpected failures but turns deliberate user-facing guidance
- * ("Set $MAILWOMAN_WOF_DB…") into a stack dump. Throw `commandError(msg)` for those instead of `new Error(msg)`.
- */
-export function commandError(message: string): Error {
-	const error = new Error(message)
-	error.stack = message
-
-	return error
-}
-
-/**
- * One ✓/✗ line in a {@linkcode CheckList}.
- */
-export interface Check {
-	ok: boolean
-	check: string
-	detail?: string
-}
-
-/**
- * The ✓/✗ check-list + PASS/FAIL renderer (extracted from `gazetteer verify`). Pass `verdict` to append the summary
- * line.
- */
-export function CheckList({ checks, verdict }: { checks: readonly Check[]; verdict?: boolean }): React.ReactElement {
-	const lines = checks.map((c, i) =>
-		h(
-			Text,
-			{ key: i, color: c.ok ? "green" : "red" },
-			`${c.ok ? "✓" : "✗"} ${c.check}${c.detail ? `: ${c.detail}` : ""}`
-		)
-	)
-
-	const summary =
-		verdict === undefined
-			? null
-			: h(
-					Text,
-					{ color: verdict ? "green" : "red" },
-					`${verdict ? "PASS" : "FAIL"} (${checks.filter((c) => c.ok).length}/${checks.length} checks)`
-				)
-
-	return h(Box, { flexDirection: "column" }, ...lines, summary)
-}
+export * from "./shared.ts"

package/cli-kit/shared.ts

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The command toolkit for `mailwoman/commands/*` — Pastel/Ink helper types, the one-shot
+ *   {@linkcode useCommandTask} runner, and the {@linkcode CheckList} renderer. Lives OUTSIDE
+ *   `commands/` (Pastel treats every file there as a command) and OUTSIDE `sdk/` (`sdk/` submodules
+ *   mean data acquisition). Built with `createElement`, not JSX, so the module stays plain `.ts` —
+ *   importable under node's type stripping (the dev `node →` exports condition).
+ */
+
+import { type PlacetypeRole, PlacetypeRoles } from "@mailwoman/core"
+import { Box, Text } from "ink"
+import { createElement as h, useEffect, useState } from "react"
+import type * as React from "react"
+import type * as zod from "zod"
+
+/**
+ * Type-helper to infer the positional arguments of a command.
+ */
+export interface PositionalArguments<T extends zod.ZodTypeAny> {
+	args: zod.infer<T>
+}
+
+/**
+ * React component for a command with positional arguments.
+ */
+export type PositionalCommandComponent<T extends zod.ZodTypeAny> = React.FC<PositionalArguments<T>>
+
+/**
+ * Type-helper to infer the options of a command.
+ */
+export interface CommandProps<
+	OptionProps extends zod.ZodObject,
+	PositionalProps extends zod.ZodTypeAny | unknown = unknown,
+> {
+	options: zod.infer<OptionProps>
+	args: PositionalProps extends zod.ZodTypeAny ? zod.infer<PositionalProps> : unknown[]
+}
+
+/**
+ * React component for a command with options.
+ */
+export type CommandComponent<
+	OptionProps extends zod.ZodObject,
+	PositionalProps extends zod.ZodTypeAny | unknown = unknown,
+> = React.FC<CommandProps<OptionProps, PositionalProps>>
+
+/**
+ * The lifecycle of a command's one-shot async task.
+ */
+export type CommandTaskState<T> =
+	| { status: "running" }
+	| { status: "done"; result: T }
+	| { status: "error"; message: string }
+
+/**
+ * Run a command's one-shot async task and own the exit-code discipline: rejection renders the error state and exits 1;
+ * resolution exits with `exitCode(result)` (default 0) — always AFTER the final frame committed. Replaces the
+ * copy-pasted useEffect/useState/setImmediate dance in every command.
+ */
+/* oxlint-disable react-hooks/exhaustive-deps -- One-shot by design: the task/exitCode closures
+	 capture their options at mount; tracking them (fresh closure per render) would re-run the task
+	 every render. The empty/[state] deps are the point. */
+export function useCommandTask<T>(task: () => Promise<T>, exitCode?: (result: T) => number): CommandTaskState<T> {
+	const [state, setState] = useState<CommandTaskState<T>>({ status: "running" })
+
+	useEffect(() => {
+		void task().then(
+			(result) => setState({ status: "done", result }),
+			(error: unknown) =>
+				setState({ status: "error", message: error instanceof Error ? (error.stack ?? error.message) : String(error) })
+		)
+	}, [])
+
+	useEffect(() => {
+		if (state.status === "running") return
+		const code = state.status === "error" ? 1 : (exitCode?.(state.result) ?? 0)
+		setImmediate(() => process.exit(code))
+	}, [state])
+
+	return state
+}
+
+/* oxlint-enable react-hooks/exhaustive-deps */
+
+/**
+ * Emit a command's final output as raw bytes, bypassing Ink's `<Text>` renderer.
+ *
+ * Ink word-wraps rendered text at the terminal width — and at 80 columns when stdout is piped — which corrupts
+ * machine-readable output: a JSON string value longer than the width gets real newlines inserted mid-string, breaking
+ * the document (observed 2026-08-07: `geocode --format json` on "Toledo Ohio" wrapped `intent_markers[].message` at 80
+ * cols). Machine formats (json/jsonld/xml/tuple, `--json` flags) must never pass through `<Text>`.
+ *
+ * Returns `null` so the caller can `return writeRawStdout(result)` from the done branch. Safe to call from render:
+ * {@linkcode useCommandTask} renders the done frame exactly once before its `process.exit`. Same pattern as
+ * `commands/gazetteer/inspect/graph.tsx`.
+ */
+export function writeRawStdout(text: string): null {
+	process.stdout.write(text + "\n")
+
+	return null
+}
+
+/**
+ * Build a guidance-grade error whose rendered form is exactly `message` — no stack. {@linkcode useCommandTask} renders
+ * `error.stack ?? error.message`, which is right for unexpected failures but turns deliberate user-facing guidance
+ * ("Set $MAILWOMAN_WOF_DB…") into a stack dump. Throw `commandError(msg)` for those instead of `new Error(msg)`.
+ */
+export function commandError(message: string): Error {
+	const error = new Error(message)
+	error.stack = message
+
+	return error
+}
+
+/**
+ * One ✓/✗ line in a {@linkcode CheckList}.
+ */
+export interface Check {
+	ok: boolean
+	check: string
+	detail?: string
+}
+
+/**
+ * The ✓/✗ check-list + PASS/FAIL renderer (extracted from `gazetteer verify`). Pass `verdict` to append the summary
+ * line.
+ */
+export function CheckList({ checks, verdict }: { checks: readonly Check[]; verdict?: boolean }): React.ReactElement {
+	const lines = checks.map((c, i) =>
+		h(
+			Text,
+			{ key: i, color: c.ok ? "green" : "red" },
+			`${c.ok ? "✓" : "✗"} ${c.check}${c.detail ? `: ${c.detail}` : ""}`
+		)
+	)
+
+	const summary =
+		verdict === undefined
+			? null
+			: h(
+					Text,
+					{ color: verdict ? "green" : "red" },
+					`${verdict ? "PASS" : "FAIL"} (${checks.filter((c) => c.ok).length}/${checks.length} checks)`
+				)
+
+	return h(Box, { flexDirection: "column" }, ...lines, summary)
+}
+
+/**
+ * Parse a `--roles a,b,c` flag into validated {@link PlacetypeRole}s, or `undefined` when the flag is absent (which
+ * every caller reads as "all roles").
+ *
+ * Rejects an unknown role with {@link commandError} rather than silently filtering it — a typo in a role name would
+ * otherwise produce an empty, entirely plausible-looking result.
+ */
+export function parseRoles(raw: string | undefined): PlacetypeRole[] | undefined {
+	if (!raw) return undefined
+
+	const valid = new Set<string>(PlacetypeRoles)
+
+	const parsed = raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean)
+
+	for (const role of parsed) {
+		if (!valid.has(role)) {
+			throw commandError(`Unknown placetype role '${role}'. Valid roles: ${PlacetypeRoles.join(", ")}.`)
+		}
+	}
+
+	return parsed as PlacetypeRole[]
+}