@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/us/tools/fetch/hrsa.ts

@@ -6,8 +6,8 @@
  *   Re-fetch the HRSA Health Center Service Delivery Sites CSV. Source for the `usgov-hrsa-fqhc`
  *   adapter. US Public Domain.
  *
- *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum, and
- *   writes the same sibling `MANIFEST.json` (origin URL + fetch timestamp + byte count + sha256) so
+ *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum. It
+ *   writes the same sibling `manifest.json` (origin URL + fetch timestamp + byte count + sha256) so
  *   downstream adapters can verify provenance.
  *
  *   Invoke via `mailwoman corpus fetch hrsa --out-root <path>`.
@@ -15,10 +15,9 @@
 
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download/index"
-import { downloadToFile, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, writeManifest } from "#tools/fetch/download"
 
 const SLUG = "usgov-hrsa-fqhc"
 const FILENAME = "Health_Center_Service_Delivery_and_LookAlike_Sites.csv"
@@ -27,9 +26,9 @@ const SOURCE_URL = `https://data.hrsa.gov/DataDownload/DD_Files/${FILENAME}`
 export type FetchHRSAOptions = BaseFetchOptions
 
 export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: string) => void): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
-	const dest = join(destDir, FILENAME)
+	const dest = destDir(FILENAME)
 
 	report?.(`=== ${SLUG} / ${FILENAME}`)
 
@@ -51,7 +50,7 @@ export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: strin
 		bytes,
 	}
 
-	await writeManifest(join(destDir, "MANIFEST.json"), manifest)
+	await writeManifest(destDir("MANIFEST.json"), manifest)
 
 	report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`)
 

package/lib/us/tools/fetch/imls-pls.ts

@@ -3,43 +3,28 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Re-fetch the IMLS Public Libraries Survey (PLS) outlet-level data. Each US public library branch
- *   (outlet) is one row, ~17K rows with address fields. Source for the `usgov-imls-pls` adapter. US
- *   Public Domain (federal statistical survey).
- *
- *   The FY 2023 release is the most current as of 2026-05. IMLS ships a single ZIP containing CSV,
- *   SAS, and SPSS variants. We extract the outlet-level CSV (pls_fy*_outlet*.csv or similar) and
- *   discard the rest. The administrative-entity (system-level) CSV is intentionally skipped — it has
- *   no per-branch address detail.
- *
- *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum. The
- *   ZIP is unpacked with the `unzip` binary via `node:child_process` (no clean Node equivalent for
- *   member listing + selective extraction).
- *
- *   Invoke via `mailwoman corpus fetch imls-pls --out-root <path>`. Idempotent: if dest CSV exists
- *   and sha matches MANIFEST, skips download.
+ * Re-fetch the IMLS Public Libraries Survey outlet-level data — one row per US public library branch —
+ * for the `usgov-imls-pls` adapter. The source is US Public Domain (a federal statistical survey).
+ * Extracts the outlet-level CSV from IMLS's single ZIP and discards the rest. The system-level CSV is
+ * skipped for having no per-branch address detail.
  */
 
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
-   procedure, not sections of declarations. A region there folds nothing a reader wants folded. */
+   procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
 import { statPath, pathExists } from "@mailwoman/core/fs/readers"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"
-import { basename, join } from "path-ts"
+import { basename } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download/index"
-import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index"
-
-/**
- * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
- * than data.
- */
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 /**
- * The PLS FY 2023 bulk CSV ZIP (most recent as of 2026-05). If IMLS publishes a newer year, update this URL.
+ * The PLS FY 2023 bulk CSV ZIP.
+ * Update this URL if IMLS publishes a newer year.
  */
 const ZIP_URL = "https://www.imls.gov/sites/default/files/2025-08/pls_fy2023_csv.zip"
 const SLUG = "usgov-imls-pls"
@@ -50,11 +35,11 @@ export async function fetchIMLSPLS(
 	options: FetchIMLSPLSOptions,
 	report?: (line: string) => void
 ): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
 
-	const zipDest = join(destDir, basename(ZIP_URL))
-	const manifestPath = join(destDir, "MANIFEST.json")
+	const zipDest = destDir(basename(ZIP_URL))
+	const manifestPath = destDir("MANIFEST.json")
 
 	report?.(`=== ${SLUG}`)
 
@@ -63,7 +48,7 @@ export async function fetchIMLSPLS(
 	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
 
 	if (recorded?.sha256 && recorded.filename) {
-		const recordedPath = join(destDir, recorded.filename)
+		const recordedPath = destDir(recorded.filename)
 
 		if ((await pathExists(recordedPath)) && (await sha256File(recordedPath)) === recorded.sha256) {
 			report?.("  ✓ Already current (sha256 matches MANIFEST) — skipping download.")
@@ -92,15 +77,12 @@ export async function fetchIMLSPLS(
 		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
 	}
 
-	// Discover the outlet-level CSV inside the ZIP.
-	// Outlet files match: pls_fy*outlet*.csv (case-insensitive)
-	// Administrative-entity files match: pls_fy*ae*.csv — we skip those.
+	// Outlet files match `pls_fy*outlet*.csv`; administrative-entity files are skipped.
 	report?.("  Inspecting ZIP contents ...")
 	const entries = (await listZipEntries(zipDest)).map((entry) => entry.name)
 
 	let csvName = entries.find((name) => /pls_fy.*outlet.*\.csv/i.test(name))
 
-	// Fallback: if IMLS renames the file, grab any CSV that is NOT the ae file.
 	if (!csvName) {
 		csvName = entries.find((name) => /\.csv$/i.test(name) && !/system|state|_ae\b|_se\b/i.test(name))
 	}
@@ -119,7 +101,7 @@ export async function fetchIMLSPLS(
 
 	report?.(`  Extracting outlet CSV: ${csvName}`)
 
-	const csvDest = join(destDir, basename(csvName))
+	const csvDest = destDir(basename(csvName))
 
 	await extractZipEntry(zipDest, csvName, csvDest)
 	const csvSize = (await statPath(csvDest)).size
@@ -130,7 +112,7 @@ export async function fetchIMLSPLS(
 	await removePathIfPresent(zipDest)
 	report?.("  Removed ZIP (CSV kept)")
 
-	// MARK: Write MANIFEST
+	// MARK: Write manifest
 
 	const manifest: SourceManifest = {
 		source_url: ZIP_URL,

package/lib/us/tools/fetch/nad.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   Fetch the US DOT National Address Database (NAD) — ~97 million structured US address-point
- *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter (#30).
+ *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter.
  *   US Public Domain (17 U.S.C. § 105).
  *
  *   - Bounded per-chunk page concurrency (4× speedup at safe pressure)
@@ -20,8 +20,8 @@
  *   - **`bulk`** mode requires a pre-signed S3 URL (Akamai blocks scripted curl on the DOT page). Pass
  *       `--nad-url <presigned>` from a browser visit to
  *       [https://www.transportation.gov/gis/national-address-database](https://www.transportation.gov/gis/national-address-database).
- *   - **`featureserver`** mode (default) pages the live FeatureService via OBJECTID ranges, writing
- *       NDJSON chunks into `<outRoot>/usgov-nad/featureserver/`.
+ *   - **`featureserver`** mode (default) pages the live FeatureService via objectid ranges, writing
+ *       ndjson chunks into `<outRoot>/usgov-nad/featureserver/`.
  *
  *   ## Usage
  *
@@ -40,10 +40,11 @@ import { APIClient, pluckResponseData } from "@mailwoman/core/api"
 import { statPath, pathExists } from "@mailwoman/core/fs/readers"
 import { makeDirectories, writeLocalTextFile } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
+import { stringifyJSON } from "@mailwoman/core/json"
+import type { PathBuilderLike } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
-import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 const SLUG = "usgov-nad"
 
@@ -52,7 +53,9 @@ const FEATURE_SERVICE_URL =
 
 export interface FetchNADOptions extends BaseFetchOptions {
 	/**
-	 * Fetch strategy. Default `featureserver`.
+	 * Fetch strategy.
+	 *
+	 * Default `featureserver`.
 	 */
 	mode?: "featureserver" | "bulk"
 	/**
@@ -60,23 +63,33 @@ export interface FetchNADOptions extends BaseFetchOptions {
 	 */
 	nadURL?: string
 	/**
-	 * Records per output file. Default `100000`.
+	 * Records per output file.
+	 *
+	 * Default `100000`.
 	 */
 	chunkSize?: number
 	/**
-	 * Records per HTTP request. Default `5000`.
+	 * Records per http request.
+	 *
+	 * Default `5000`.
 	 */
 	pageSize?: number
 	/**
-	 * Parallel page fetches within a chunk. Default `4`.
+	 * Parallel page fetches within a chunk.
+	 *
+	 * Default `4`.
 	 */
 	concurrency?: number
 	/**
-	 * Start OBJECTID. Default `1`.
+	 * Start objectid.
+	 *
+	 * Default `1`.
 	 */
 	startOID?: number
 	/**
-	 * Stop before this OID. Default = total count.
+	 * Stop before this OID.
+	 *
+	 * Default = total count.
 	 */
 	endOID?: number
 }
@@ -94,9 +107,11 @@ interface ChunkManifest {
 }
 
 /**
- * ArcGIS paged reads. Retry is ON: the loop walks OBJECTID ranges to completion, so one throttled page previously ended
- * a multi-hour national download. No rate budget — pages are requested one at a time and each assembles thousands of
- * records server-side.
+ * ArcGIS paged reads.
+ *
+ * Retry is on: the loop walks objectid ranges to completion, since one throttled
+ * page can otherwise end a multi-hour national download.
+ * No rate budget — pages are requested one at a time and each assembles thousands of records server-side.
  */
 const nadClient = new APIClient({
 	displayName: "nad",
@@ -139,13 +154,16 @@ async function discoverTotalCount(): Promise<number> {
 }
 
 /**
- * Fetch a single chunk by paging through its OID range with bounded concurrency. Returns the count of records written
- * and the count of pages that errored. The caller decides whether to mark the chunk complete based on errors === 0.
+ * Fetch a single chunk by paging through its OID range with bounded concurrency.
+ *
+ * Returns the count of records written and the count of pages that errored.
+ * The caller decides whether to mark the chunk complete based on errors === 0.
  *
- * NOTE(phase1): this is a JSON API pager, not a file download — the shared `downloadToFile` doesn't apply here.
+ * Note(phase1): this is a JSON API pager rather than a file download —
+ * the shared `downloadToFile` doesn't apply here.
  */
 async function fetchChunk(
-	chunkPath: string,
+	chunkPath: PathBuilderLike,
 	chunkStart: number,
 	chunkEnd: number,
 	pageSize: number,
@@ -158,7 +176,7 @@ async function fetchChunk(
 		pageRanges.push([cursor, Math.min(cursor + pageSize - 1, chunkEnd)])
 	}
 
-	// Run bounded-concurrency page fetches. Results indexed by page slot for in-order write.
+	// Results indexed by page slot for in-order write.
 	const pageResults: Array<{ rows: unknown[]; error: Error | null }> = pageRanges.map(() => ({
 		rows: [],
 		error: null,
@@ -184,7 +202,7 @@ async function fetchChunk(
 
 	await Promise.all(workers)
 
-	// Single-writer phase — write all pages in OID order to keep NDJSON deterministic.
+	// Single-writer phase — write all pages in OID order to keep ndjson deterministic.
 	const lines: string[] = []
 	let errors = 0
 
@@ -196,11 +214,11 @@ async function fetchChunk(
 		}
 
 		for (const row of rows) {
-			lines.push(JSON.stringify(row))
+			lines.push(stringifyJSON(row))
 		}
 	}
 
-	await writeLocalTextFile(!lines.length ? "" : lines.join("\n") + "\n", chunkPath)
+	await writeLocalTextFile(lines, chunkPath)
 
 	return { recordCount: lines.length, errors }
 }
@@ -211,7 +229,7 @@ async function featureserverMode(options: FetchNADOptions, report?: (line: strin
 	const concurrency = options.concurrency ?? 4
 	const startOID = options.startOID ?? 1
 
-	const chunkDir = join(options.outRoot, SLUG, "featureserver")
+	const chunkDir = options.outRoot(SLUG, "featureserver")
 	await makeDirectories(chunkDir)
 
 	report?.(`=== ${SLUG} / featureserver`)
@@ -231,11 +249,11 @@ async function featureserverMode(options: FetchNADOptions, report?: (line: strin
 	for (let cursor = startOID; cursor <= endOID; cursor += chunkSize) {
 		const chunkEnd = Math.min(cursor + chunkSize - 1, endOID)
 		const chunkName = `oids_${cursor}-${chunkEnd}`
-		const chunkPath = join(chunkDir, `${chunkName}.ndjson`)
-		const manifestPath = join(chunkDir, `${chunkName}.manifest.json`)
+		const chunkPath = chunkDir(`${chunkName}.ndjson`)
+		const manifestPath = chunkDir(`${chunkName}.manifest.json`)
 
-		// Idempotency: skip a chunk only if it's marked complete (the bash version's bug was
-		// marking complete on partial-failure runs; we now only set complete after a clean fetch).
+		// Idempotency: skip a chunk only when its manifest is marked complete.
+		// Complete is set only after a clean fetch.
 		if (await pathExists(chunkPath)) {
 			const recorded = await readManifest<ChunkManifest>(manifestPath)
 
@@ -288,7 +306,7 @@ async function featureserverMode(options: FetchNADOptions, report?: (line: strin
 	report?.(`page errors:   ${totalErrors}`)
 	report?.(`output:        ${chunkDir}`)
 
-	// `failed` counts page errors (the old exit-1 condition), `failedCodes` names the dirty chunks.
+	// `failed` counts page errors and `failedCodes` records the dirty chunks.
 	return { fetched, skipped, failed: totalErrors, failedCodes }
 }
 
@@ -301,10 +319,10 @@ async function bulkMode(options: FetchNADOptions, report?: (line: string) => voi
 		)
 	}
 
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
 	const filename = new URL(options.nadURL).pathname.split("/").pop() ?? "NAD.zip"
-	const destPath = join(destDir, filename)
+	const destPath = destDir(filename)
 
 	report?.(`=== ${SLUG} / ${filename}`)
 	report?.(`  URL: ${options.nadURL.slice(0, 100)}${options.nadURL.length > 100 ? "…" : ""}`)
@@ -313,7 +331,7 @@ async function bulkMode(options: FetchNADOptions, report?: (line: string) => voi
 
 	const sha = await sha256File(destPath)
 
-	await writeManifest(join(destDir, "MANIFEST.json"), {
+	await writeManifest(destDir("MANIFEST.json"), {
 		source_url: options.nadURL,
 		downloaded_at: new Date().toISOString(),
 		filename,

package/lib/us/tools/fetch/nppes.ts

@@ -3,36 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Re-fetch the NPPES (National Plan and Provider Enumeration System) full monthly data
- *   dissemination file. ~7M provider rows with venue+address data. Source for the `usgov-nppes`
- *   adapter. US Public Domain.
+ * Re-fetch the NPPES (National Plan and Provider Enumeration System) full monthly data dissemination
+ * file for the `usgov-nppes` adapter. The source is US Public Domain. Discovers the current filename
+ * by scraping the NPI_Files.html index, then extracts only the main registry CSV
+ * (`npidata_pfile_*.csv`) and leaves the endpoint/othername/pl files zipped.
  *
- *   The file is published monthly by CMS. This module discovers the current filename by scraping the
- *   NPI_Files.html index, then downloads the ZIP and extracts only the main registry CSV
- *   (npidata_pfile_*.csv). The smaller endpoint/othername/pl files stay zipped — we don't need them.
- *
- *   Uses Node's built-in fetch (gzip/brotli) to parse the HTML index and download the ZIP, and
- *   streaming sha256 instead of sha256sum. The ZIP is unpacked with the `unzip` binary via
- *   `node:child_process` (no clean Node equivalent for member listing + selective extraction). NOTE:
- *   the old bash fetcher used `curl --continue-at -` to resume a partial download; native fetch has
- *   no resume, so a partial run re-downloads from the start.
- *
- *   Invoke via `mailwoman corpus fetch nppes --out-root <path>`. Idempotent: if dest CSV exists and
- *   sha256 matches MANIFEST, skips download.
+ * Native fetch has no resume, so a partial run re-downloads from the start.
  */
 
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
-   procedure, not sections of declarations. A region there folds nothing a reader wants folded. */
+   procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 
 import { APIClient, pluckResponseData } from "@mailwoman/core/api"
 import { statPath, pathExists } from "@mailwoman/core/fs/readers"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"
-import { basename, join } from "path-ts"
+import { basename, type PathBuilderLike } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download/index"
-import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 const INDEX_URL = "https://download.cms.gov/nppes/NPI_Files.html"
 const BASE_URL = "https://download.cms.gov/nppes"
@@ -41,11 +31,11 @@ const SLUG = "usgov-nppes"
 export type FetchNPPESOptions = BaseFetchOptions
 
 /**
- * Scrape the NPI_Files.html index for the latest full monthly ZIP. Full-replacement files match
- * `NPPES_Data_Dissemination_<Month>_<Year>*.zip`; weekly files carry a `MMDDYY_MMDDYY` date range, which we exclude.
+ * Scrape the NPI_Files.html index for the latest full monthly ZIP: full-replacement
+ * files match `NPPES_Data_Dissemination_<Month>_<Year>*.zip`, while weekly files
+ * include a `MMDDYY_MMDDYY` date range and are excluded.
  */
 async function discoverLatestZip(): Promise<string | undefined> {
-	// `responseType: "text"` — the index is HTML, scraped by regex below.
 	const html = await new APIClient({
 		displayName: "nppes-index",
 		retry: true,
@@ -64,19 +54,19 @@ async function discoverLatestZip(): Promise<string | undefined> {
 }
 
 /**
- * The main registry CSV (npidata_pfile_*.csv), which the archive also carries alongside a header file and a per-month
- * change file.
+ * The main registry CSV (`npidata_pfile_*.csv`); the archive also includes a
+ * header file and a per-month change file.
  */
-async function findNpidataCSV(zipPath: string): Promise<string | undefined> {
+async function findNpidataCSV(zipPath: PathBuilderLike): Promise<string | undefined> {
 	const entries = await listZipEntries(zipPath)
 
 	return entries.find((entry) => /npidata_pfile\S+\.csv/i.test(entry.name))?.name
 }
 
 export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: string) => void): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
-	const manifestPath = join(destDir, "MANIFEST.json")
+	const manifestPath = destDir("MANIFEST.json")
 
 	report?.(`=== ${SLUG}`)
 	report?.(`  Discovering latest full-replacement ZIP from ${INDEX_URL} ...`)
@@ -90,15 +80,13 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 	}
 
 	const zipURL = `${BASE_URL}/${zipFilename}`
-	const zipDest = join(destDir, zipFilename)
+	const zipDest = destDir(zipFilename)
 	report?.(`  Latest full file: ${zipFilename}`)
 
-	// Idempotency check: if the main CSV already exists and sha matches,
-	// skip re-download.
 	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
 
 	if (recorded?.sha256 && recorded.filename) {
-		const recordedPath = join(destDir, recorded.filename)
+		const recordedPath = destDir(recorded.filename)
 
 		if ((await pathExists(recordedPath)) && (await sha256File(recordedPath)) === recorded.sha256) {
 			report?.("  ✓ Already current (sha256 matches MANIFEST) — skipping download.")
@@ -107,7 +95,7 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 		}
 	}
 
-	// MARK: Download ZIP (large; 60-minute timeout)
+	// MARK: Download ZIP
 
 	report?.(`  Downloading ${zipURL} ...`)
 
@@ -134,19 +122,19 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 
 	report?.(`  Extracting: ${csvName}`)
 
-	const csvDest = join(destDir, basename(csvName))
+	const csvDest = destDir(basename(csvName))
 
 	await extractZipEntry(zipDest, csvName, csvDest)
 	const csvSize = (await statPath(csvDest)).size
 	const csvSha = await sha256File(csvDest)
 	report?.(`  CSV size: ${(csvSize / 1024 / 1024).toFixed(1)} MB`)
 
-	// MARK: Remove the ZIP to reclaim ~1 GB
+	// MARK: Remove the ZIP
 
 	await removePathIfPresent(zipDest)
 	report?.("  Removed ZIP (CSV kept)")
 
-	// MARK: Write MANIFEST (records the extracted CSV, not the ZIP)
+	// MARK: Write manifest for extracted CSV
 
 	const manifest: SourceManifest = {
 		source_url: zipURL,

package/lib/us/tools/fetch/state/hi-schools.ts

@@ -3,28 +3,28 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Re-fetch the Hawaii State DOE school directory as its original XLSX workbook. The
+ *   Re-fetch the Hawaii State DOE school directory as its original xlsx workbook. The
  *   `state-hi-schools` adapter reads both worksheets directly.
  *
- *   Upstream is a single XLSX (~64 KB) with two sheets — `HIDOE` (~258 district schools) and `PCS`
+ *   Upstream is a single xlsx (~64 KB) with two sheets — `hidoe` (~258 district schools) and `PCS`
  *   (~38 public charter schools). Both sheets are validated against the adapter's required columns
  *   before the workbook is recorded as fetched.
  *
  *   License: Hawaii state government open data (Tier A — state PD-equivalent).
  *
  *   Invoke via `mailwoman corpus fetch state-hi-schools --out-root <path>`. Idempotent: if the dest
- *   workbook exists and its sha matches MANIFEST, skips download.
+ *   workbook exists and its sha matches manifest, skips download.
  */
 
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
 import { statPath, pathExists } from "@mailwoman/core/fs/readers"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
+import type { PathBuilderLike } from "path-ts"
 import { XLSXSpliterator, type XLSXCellValue } from "spliterator"
 
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
-import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 import { STATE_HI_SCHOOL_REQUIRED_COLUMNS, STATE_HI_SCHOOL_SHEETS } from "#us/adapters/state/hi-schools/workbook"
 
 const SOURCE_URL = "https://www.hawaiipublicschools.org/DOE%20Forms/SchoolList.xlsx"
@@ -33,7 +33,10 @@ const XLSX_FILENAME = "HI_Public_Schools_List.xlsx"
 
 export interface FetchStateHISchoolsOptions extends BaseFetchOptions {
 	/**
-	 * Workbook URL. Defaults to the Hawaii DOE source; overridable for an isolated fetch test.
+	 * Workbook URL.
+	 *
+	 * Defaults to the Hawaii DOE source.
+	 * Overridable for an isolated fetch test.
 	 */
 	sourceURL?: string
 }
@@ -47,9 +50,11 @@ interface Manifest {
 	notes: string
 }
 
-async function validateWorkbook(path: string): Promise<void> {
+async function validateWorkbook(path: PathBuilderLike): Promise<void> {
 	for (const sheet of STATE_HI_SCHOOL_SHEETS) {
-		const rows = await XLSXSpliterator.fromAsync<XLSXCellValue[]>(path, {
+		// XLSXSpliterator opens a string, URL, or byte source.
+		// A PathBuilder is none of those.
+		const rows = await XLSXSpliterator.fromAsync<XLSXCellValue[]>(path.toString(), {
 			sheet,
 			header: false,
 			take: 2,
@@ -61,8 +66,9 @@ async function validateWorkbook(path: string): Promise<void> {
 			throw new Error(`sheet ${sheet} must contain a header and at least one school row`)
 		}
 
-		// Exact casing is part of the adapter contract: object mode preserves the workbook's header names, so accepting
-		// `Code` here while the reader asks for `record.code` would validate a workbook whose every row is later skipped.
+		// Exact casing is part of the adapter interface: object mode preserves the workbook's
+		// header names, so accepting `Code` here while the reader asks for `record.code`
+		// would validate a workbook whose every row is later skipped.
 		const columns = new Set(header.map((cell) => String(cell ?? "").trim()))
 
 		const missing = STATE_HI_SCHOOL_REQUIRED_COLUMNS.filter((column) => !columns.has(column))
@@ -77,11 +83,11 @@ export async function fetchStateHISchools(
 	options: FetchStateHISchoolsOptions,
 	report?: (line: string) => void
 ): Promise<FetchSummary> {
-	const destDir = join(options.outRoot, SLUG)
+	const destDir = options.outRoot(SLUG)
 	await makeDirectories(destDir)
 
-	const xlsxDest = join(destDir, XLSX_FILENAME)
-	const manifestPath = join(destDir, "MANIFEST.json")
+	const xlsxDest = destDir(XLSX_FILENAME)
+	const manifestPath = destDir("MANIFEST.json")
 	const sourceURL = options.sourceURL ?? SOURCE_URL
 
 	report?.(`=== ${SLUG}`)
@@ -101,7 +107,7 @@ export async function fetchStateHISchools(
 		}
 	}
 
-	// Download XLSX.
+	// Download xlsx.
 	report?.(`  Downloading ${sourceURL} ...`)
 
 	try {
@@ -139,7 +145,7 @@ export async function fetchStateHISchools(
 
 	const xlsxSha = await sha256File(xlsxDest)
 
-	// Write MANIFEST.
+	// Write manifest.
 	const manifest: Manifest = {
 		source_url: sourceURL,
 		downloaded_at: new Date().toISOString(),

package/lib/us/tools/fetch/state/sources.ts

@@ -3,14 +3,14 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Re-fetch the state-level open-data sources (NY/TX/DE/OR notaries, IA contractors, WA health
+ *   Re-fetch the state-level open-data sources (NY/TX/DE/or notaries, IA contractors, WA health
  *   providers, HI lobbyists). Reproducible recovery if `$MAILWOMAN_DATA_ROOT` is lost.
  *
- *   HI public schools is fetched separately by `mailwoman corpus fetch state-hi-schools` — its
- *   upstream is an XLSX workbook that requires an openpyxl-driven sheet-concatenation pre-step
+ *   HI public schools is fetched separately by `mailwoman corpus fetch state-hi-schools`. Its
+ *   upstream is an xlsx workbook that requires an openpyxl-driven sheet-concatenation pre-step
  *   before the adapter can consume it.
  *
- *   Each source lands in its own subdirectory of `<outRoot>/<slug>/` along with a `MANIFEST.json`
+ *   Each source lands in its own subdirectory of `<outRoot>/<slug>/` along with a `manifest.json`
  *   recording origin URL + download timestamp + sha256 so downstream adapters can verify provenance.
  *
  *   Invoke via `mailwoman corpus fetch state-sources --out-root <path>`. Uses Node's built-in fetch
@@ -20,14 +20,14 @@
 import { BYTES_PER_KIB } from "@mailwoman/core/fs/formatters"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
 
-import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download/index"
-import { downloadToFile, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, writeManifest } from "#tools/fetch/download"
 
 /**
- * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
- * than data.
+ * Bytes per KiB — the divisor for human-readable sizes.
+ *
+ * It is the floor below which a "download" is an error page rather than data.
  */
 
 export type FetchStateSourcesOptions = BaseFetchOptions
@@ -87,9 +87,9 @@ export async function fetchStateSources(
 	const failedCodes: string[] = []
 
 	for (const { slug, filename, url } of SOURCES) {
-		const destDir = join(options.outRoot, slug)
+		const destDir = options.outRoot(slug)
 		await makeDirectories(destDir)
-		const dest = join(destDir, filename)
+		const dest = destDir(filename)
 
 		report?.(`=== ${slug} / ${filename}`)
 
@@ -131,7 +131,7 @@ export async function fetchStateSources(
 			bytes,
 		}
 
-		await writeManifest(join(destDir, "MANIFEST.json"), manifest)
+		await writeManifest(destDir("MANIFEST.json"), manifest)
 
 		report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`)