mailwoman 9.4.0 → 10.0.0

package/lib/api-engine.ts

@@ -36,7 +36,7 @@ import type {
 import { recordTimed } from "@mailwoman/api-kit"
 import { decodeAsTuples, decodeAsXML } from "@mailwoman/core"
 import { walkNodes, type AddressTree } from "@mailwoman/core/decoder"
-import { pathExists, readDirectory, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { pathExists, readLocalTextFile } from "@mailwoman/core/fs/readers"
 import { tryParsingJSON } from "@mailwoman/core/json"
 import { resolveModulePath } from "@mailwoman/core/module/resolvers"
 import { deriveInputMode } from "@mailwoman/core/pipeline"
@@ -45,6 +45,7 @@ import { mailwomanDataRoot } from "@mailwoman/core/utils"
 import { classifyKindSync } from "@mailwoman/kind-classifier"
 import { computeQueryShape } from "@mailwoman/query-shape"
 import { createWOFResolver } from "@mailwoman/resolver"
+import { Globerator } from "spliterator/node/fs"
 
 import { readReleaseManifest } from "#data/release"
 import { $public } from "#env"
@@ -150,7 +151,9 @@ async function countDatabases(subdir: string, prefix: string): Promise<number> {
 	try {
 		const re = new RegExp(`^${prefix}-us-[a-z]{2}\\.db$`)
 
-		return (await readDirectory(`${DATA_ROOT}/${subdir}`)).filter((f) => re.test(f)).length
+		return await Globerator.from("*.db", { cwd: `${DATA_ROOT}/${subdir}`, absolute: false })
+			.filter((file) => re.test(file))
+			.reduce((count) => count + 1, 0)
 	} catch {
 		return 0
 	}

package/lib/authoritative.ts

@@ -16,13 +16,13 @@
  *   measurement-boundary lie this repository keeps finding.
  */
 
+import type { ComponentTag } from "@mailwoman/codex/component"
 import type {
 	AuthoritativeMatch,
 	AuthoritativeProvider,
 	AuthoritativeQuery,
 	AuthoritativeQueryComponent,
 } from "@mailwoman/core/resolver"
-import type { ComponentTag } from "@mailwoman/core/types"
 
 /**
  * One provider match on the wire — the snake_case projection of {@link AuthoritativeMatch}, field for field. Absent

package/lib/cli/index.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The CLI's bin entry. It runs the process-wide preamble before selecting and importing one command.
+ *
+ *   The split is required. ESM evaluates every static import before a module's own body runs, so a preamble
+ *   written in a statically imported command graph would execute after that graph had already initialized. Only
+ *   `node:module` is imported statically here; command code arrives through dynamic imports after this body.
+ *
+ *   So keep this file at one static import: anything added to the top of it is compiled before the cache exists and,
+ *   if it reaches React, pins the development build.
+ */
+
+import { enableCompileCache } from "@mailwoman/core/module/runtime"
+import { parseArguments } from "@mailwoman/core/scripting/arguments"
+
+// The CLI compiles ~16 MB of source per invocation, and the loader/compiler/GC are ~85% of a `--help` run. V8's
+// on-disk code cache removes most of it: `--help` 1.34 s → 0.99 s, `parse` 2.95 s → 2.63 s. The cache is
+// content-addressed and self-invalidating, so a stale entry is not a failure mode; an unwritable cache directory is,
+// and a CLI that cannot cache its compilation is a slow CLI rather than a broken one.
+try {
+	enableCompileCache()
+} catch {}
+
+// React's CJS entry picks its development or production build from `NODE_ENV` at import time, and the development
+// build is 23.5% of the render work in `geocode --debug`'s interactive session: 12.35 ms → 4.25 ms of synchronous
+// main-thread work per keystroke at 120×36. Nothing in the CLI reads React's dev warnings, so production is the right
+// default — `??=` and not `=`, because vitest sets `NODE_ENV=test`.
+// oxlint-disable-next-line sister-software/no-process-globals -- See above
+process.env.NODE_ENV ??= "production"
+
+// The geocode command's --timing report needs a clock that starts before command dependencies are imported.
+// Keeping the stamp here lets it attribute the otherwise invisible CLI import graph without putting a
+// profiling dependency in this deliberately tiny launcher.
+globalThis.__mailwomanCLIStartedAt = performance.now()
+
+// `strict: false` is required, not a relaxation: the launcher cannot enumerate the union of every command's flags, and
+// a strict parse rejects the first one it has not heard of — `--json`, `--locale`, `--debug` — before dispatch, which
+// is the whole CLI rather than one command. Unknown options stay in the vector for the command router to interpret.
+const { values, positionals } = parseArguments({
+	options: {
+		help: { type: "boolean", short: "h" },
+		timing: { type: "boolean", short: "t" },
+		version: { type: "boolean", short: "v" },
+	},
+	strict: false,
+	allowPositionals: true,
+})
+
+// A ROOT version request, which is why the positional count is required: `--version` reached from anywhere in the
+// vector would make the launcher answer `mw geocode --version` itself, swallowing a flag that belongs to the command.
+const rootVersionRequest = values.version === true && !positionals.length
+
+// Give an interactive geocode invocation feedback before its model and resolver graph loads.
+const interactiveGeocode =
+	process.stderr.isTTY === true && positionals[0] === "geocode" && !values.help && !values.timing
+
+if (interactiveGeocode) {
+	console.error("[geocode] Loading command…")
+}
+
+async function printVersion(): Promise<number> {
+	const { readMailwomanVersion } = await import("#cli/kit/metadata")
+
+	process.stdout.write(`${await readMailwomanVersion()}\n`)
+
+	return 0
+}
+
+function dispatchCommand(): Promise<number> {
+	const runnerModule = import("@mailwoman/core/scripting/command")
+	const routerModule = import("#cli/native/router")
+	const commandRouterModule = import("#cli/native/command/router")
+	const argumentsModule = import("@mailwoman/core/scripting/arguments")
+
+	return Promise.all([runnerModule, routerModule, commandRouterModule, argumentsModule]).then(
+		([
+			{ runCLICommand },
+			{ dispatchNativeCommand },
+			{ dispatchCommand: dispatchFilesystemCommand },
+			{ cliArguments },
+		]) => {
+			const launchArguments = cliArguments()
+
+			return runCLICommand(() =>
+				dispatchNativeCommand(launchArguments).then((exitCode) => {
+					return exitCode ?? dispatchFilesystemCommand(launchArguments)
+				})
+			).then((exitCode) => exitCode ?? 0)
+		}
+	)
+}
+
+const exitCode = await (rootVersionRequest ? printVersion() : dispatchCommand())
+
+// The notice is the last thing written, for every command and every exit code, and it never changes the exit code: a
+// failure to build it is reported on stderr and the command's own result stands. Only the cluster primary prints it —
+// `mailwoman serve` forks workers that run this same file, and one notice per process would be one per CPU. A builtin
+// reached through `process.getBuiltinModule` keeps this file at its one static import.
+if (process.getBuiltinModule("node:cluster").isPrimary) {
+	try {
+		const { printLicenseNotice, resolveEngineStamp } = await import("#cli/kit/engine-stamp")
+
+		printLicenseNotice(await resolveEngineStamp())
+	} catch (error) {
+		const { errorMessage } = await import("@mailwoman/core/errors")
+
+		console.error(`[license] posture unavailable: ${errorMessage(error)}`)
+	}
+}
+
+process.exitCode = exitCode

package/lib/cli/kit/dropin.ts

@@ -0,0 +1,254 @@
+/**
+ * @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 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 { printOpenAPIDocument } from "@mailwoman/api-kit"
+import { pathExists } from "@mailwoman/core/fs/readers"
+import { parseArguments } from "@mailwoman/core/scripting/arguments"
+import { failScript } from "@mailwoman/core/scripting/utils"
+import { mailwomanDataRoot } from "@mailwoman/core/utils"
+import { NeuralAddressClassifier } from "@mailwoman/neural"
+
+import { printLicenseNotice, resolveEngineStamp, type ResolvedEngineStamp } from "#cli/kit/engine-stamp"
+import { type FreshnessArtifact, type FreshnessReport, readFreshness } from "#freshness"
+import { buildNoGazetteerMessage, existingWOFDatabasePaths, resolveCandidateDBPath } from "#resolver-backend"
+/**
+ * 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 {
+	return failScript(message)
+}
+
+/**
+ * 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 } = parseArguments({
+		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
+}
+
+/**
+ * A drop-in's `openapi` subcommand: print (or `--out`-write) the OpenAPI document for its surface.
+ *
+ * `createApp` receives a STUB engine, so the command is pure route-table introspection that never boots a classifier or
+ * opens a gazetteer and stays fast whatever the data-root holds. `--flavor 3.0` prints the 3.0.3 diet instead of the
+ * default 3.1.0.
+ */
+export function openAPICommand<Engine>(
+	binaryName: string,
+	createApp: (engine: Engine) => Parameters<typeof printOpenAPIDocument>[0],
+	docInfo: Parameters<typeof printOpenAPIDocument>[1],
+	stubEngine: Engine
+): () => Promise<void> {
+	return async () => {
+		await printOpenAPIDocument(createApp(stubEngine), docInfo, parseOpenAPIFlags(binaryName))
+	}
+}
+
+/**
+ * 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 databases that exist on disk.
+	 */
+	wofPaths: string[]
+	/**
+	 * The first database — the admin DB the reverse geocoder opens. `undefined` when there are no databases.
+	 */
+	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 databases prints the named-artifact message with the one command that fixes it, instead of
+ *   letting the resolver throw its internal "resolveExtracts: at least one database is required".
+ */
+export async function resolveGazetteerOrExit(candidateDBFlag: string | undefined): Promise<GazetteerPaths> {
+	if (candidateDBFlag && !(await pathExists(candidateDBFlag))) {
+		fail(`✗ --candidate-db not found: ${candidateDBFlag}`)
+	}
+
+	const wofPaths = await existingWOFDatabasePaths()
+
+	// 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 databases.
+	const candidateDB = await 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`,
+	]
+}
+
+/**
+ * The provenance of the gazetteer artifacts a drop-in actually OPENED, for its `/status` surface (#997).
+ *
+ * The set is derived from the same {@link GazetteerPaths} the banner prints, and it follows the backend selection rather
+ * than the search order: `createResolverBackend` opens the candidate gazetteer ALONE when one is resolved, so listing
+ * the admin databases beside it would name databases this process never read. The reverse geocoder is the exception —
+ * it opens the first admin database whatever the forward path chose, which can be a different build, so it is reported
+ * separately unless it is already in the list.
+ *
+ * Call once at boot: a server holds its handles for its whole life, so the artifact it serves from is the one it opened
+ * at start, whatever a later symlink swap points at.
+ */
+export async function gazetteerFreshness({
+	adminDBPath,
+	candidateDB,
+	wofPaths,
+}: GazetteerPaths): Promise<FreshnessReport> {
+	const artifacts: FreshnessArtifact[] = []
+
+	if (candidateDB) {
+		artifacts.push({ name: "gazetteer", path: candidateDB })
+	} else {
+		for (const [index, path] of wofPaths.entries()) {
+			artifacts.push({ name: `gazetteer-database-${index}`, path })
+		}
+	}
+
+	if (adminDBPath && !artifacts.some((artifact) => artifact.path === adminDBPath)) {
+		artifacts.push({ name: "reverse-admin", path: adminDBPath })
+	}
+
+	return await readFreshness(artifacts)
+}
+
+/**
+ * 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[]
+	/**
+	 * Boot the listener and resolve once it is bound; the engine stamp is the process's, resolved here so every drop-in
+	 * carries it the same way and the license notice prints after the listening banner.
+	 */
+	serve: (engineStamp: ResolvedEngineStamp) => Promise<void>
+	openapi: () => void | Promise<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 = parseArguments({ strict: false, allowPositionals: true }).positionals[0]
+
+	switch (command) {
+		case "serve": {
+			const engineStamp = await resolveEngineStamp()
+
+			await serve(engineStamp)
+
+			printLicenseNotice(engineStamp)
+
+			break
+		}
+		case "openapi":
+			await openapi()
+			break
+		default:
+			console.error([`Usage: ${binaryName} <command>`, ...usage].join("\n"))
+			process.exit(command ? 1 : 0)
+	}
+}

package/lib/cli/kit/engine-stamp.ts

@@ -0,0 +1,58 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The process's engine stamp, resolved once. The `mailwoman` package is the one place that can read its own manifest
+ *   AND the configured key, and an HTTP surface's app factory must not import it (its bin may), so this module builds the
+ *   stamp and each bin hands it to its app as an option value.
+ */
+
+import {
+	buildEngineStamp,
+	type EngineStamp,
+	type LicenseKeyVerification,
+	licenseNoticeLines,
+	verifyConfiguredLicenseKey,
+} from "@mailwoman/core/license"
+
+import { readMailwomanManifest } from "#cli/kit/metadata"
+
+export interface ResolvedEngineStamp {
+	stamp: EngineStamp
+	/**
+	 * The offline verification the stamp was built from, so the notice can name an expiry date.
+	 */
+	key?: LicenseKeyVerification
+}
+
+let resolved: Promise<ResolvedEngineStamp> | undefined
+
+/**
+ * Resolve the stamp for this process. Memoized: the manifest and the configured key do not change while a process runs,
+ * and every stamped output must agree.
+ */
+export function resolveEngineStamp(): Promise<ResolvedEngineStamp> {
+	resolved ??= (async () => {
+		const [manifest, key] = await Promise.all([readMailwomanManifest(), verifyConfiguredLicenseKey()])
+		const stamp = buildEngineStamp({ version: manifest.version, expression: manifest.license, key })
+
+		return { stamp, key }
+	})()
+
+	return resolved
+}
+
+/**
+ * Write the two-line notice to stderr, or nothing when the commercial branch applies. stderr, so stdout stays
+ * machine-readable for every `--json` consumer.
+ */
+export function printLicenseNotice(resolvedStamp: ResolvedEngineStamp): void {
+	const lines = licenseNoticeLines(resolvedStamp.stamp, resolvedStamp.key)
+
+	if (!lines) return
+
+	for (const line of lines) {
+		console.error(line)
+	}
+}

package/lib/cli/kit/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export * from "#cli/kit/shared"
+export * from "#cli/kit/engine-stamp"
+export * from "#cli/kit/metadata"
+export * from "#cli/native/spec"

package/lib/cli/kit/metadata.ts

@@ -0,0 +1,103 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export interface CommandArgumentMetadata {
+	name: string
+	description?: string
+	default?: string
+}
+
+/**
+ * Attach CLI presentation metadata to a positional-argument schema.
+ *
+ * The encoded description remains readable by the transitional schema adapter. Native commands express positionals
+ * directly in `CommandSpec` and do not need this helper.
+ */
+export function argument(config: CommandArgumentMetadata): string {
+	return `__mailwoman_argument_config__${JSON.stringify(config)}`
+}
+
+/**
+ * The version of the `mailwoman` package this process ships in — read from the package's own manifest via
+ * `resolvePackagePath`, so dev checkouts, `out/` trees, and published installs all answer the same file.
+ *
+ * @throws {TypeError} When the manifest carries no string version — a broken install, not a formatting choice.
+ */
+/**
+ * The fields of mailwoman's own `package.json` that the CLI reports about itself: the version (`--version`), the Node
+ * engines floor (the doctor), and the license expression (the doctor's posture line).
+ */
+export interface MailwomanManifest {
+	version: string
+	engines?: { node?: string }
+	license: string
+	bin?: Record<string, string>
+}
+
+/**
+ * The compiled CLI's entry point, taken from the manifest's own `bin` rather than assembled from segments.
+ *
+ * Nineteen call sites spelled `workspacePath("mailwoman", "out", "cli.js")`, and every one of them named a file that
+ * had moved — a path built from pieces matches no sweep and is checked by nothing until the process fails to start. The
+ * manifest already states where the binary is, and that statement is what `npm` installs against.
+ */
+export async function mailwomanCLIPath(): Promise<string> {
+	const { resolvePackagePath } = await import("@mailwoman/core/module/resolvers")
+	const { bin } = await readMailwomanManifest()
+	const entry = bin?.mailwoman
+
+	if (!entry) throw new TypeError("mailwoman's manifest declares no `bin.mailwoman`.")
+
+	return String(resolvePackagePath("mailwoman", entry))
+}
+
+let manifest: Promise<MailwomanManifest> | undefined
+
+/**
+ * Read mailwoman's own manifest by package self-reference, so the same file answers from the source tree, `out/`, and a
+ * published tarball. The one place this read happens, and it happens once per process: the version line, the license
+ * notice, the doctor and the license command all read the same file.
+ *
+ * @throws {TypeError} When the manifest carries no string `version` or `license` — a broken install, not a choice.
+ */
+export function readMailwomanManifest(): Promise<MailwomanManifest> {
+	manifest ??= readManifestFile()
+
+	return manifest
+}
+
+async function readManifestFile(): Promise<MailwomanManifest> {
+	const { resolvePackagePath } = await import("@mailwoman/core/module/resolvers")
+	const { readLocalJSONFile } = await import("@mailwoman/core/fs/readers")
+
+	const manifestPath = resolvePackagePath("mailwoman", "package.json")
+
+	const raw = await readLocalJSONFile<{
+		version?: unknown
+		engines?: { node?: string }
+		license?: unknown
+		bin?: Record<string, string>
+	}>(manifestPath)
+
+	if (typeof raw.version !== "string") {
+		throw new TypeError(`Missing string version in ${manifestPath}`)
+	}
+
+	if (typeof raw.license !== "string") {
+		throw new TypeError(`Missing string license in ${manifestPath}`)
+	}
+
+	return {
+		version: raw.version,
+		license: raw.license,
+		...(raw.engines ? { engines: raw.engines } : {}),
+		...(raw.bin ? { bin: raw.bin } : {}),
+	}
+}
+
+export async function readMailwomanVersion(): Promise<string> {
+	return (await readMailwomanManifest()).version
+}