@toolpath/tool-scraper 0.1.0

package/dist/fetch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The polite GET every transport here was copying.
+ *
+ * Three vendors, three unrelated transports — an AEM variant-table GET, a
+ * Firestore REST walk, an Elasticsearch proxy POST — and all three arrived at
+ * the same four lines: build a request, set a browser `User-Agent`, send it
+ * with a timeout, decode. Four copies of four lines is not expensive; four
+ * copies of the *decisions* in them is, because the decisions are the part
+ * that has to be consistent. A vendor whose transport needs something else — a
+ * session, a retry policy, a browser — keeps it in its own module rather than
+ * widening this one.
+ *
+ * **The `User-Agent` is not evasion.** These are unauthenticated, publicly
+ * served endpoints; a default agent gets a 403 from ordinary CDN rules on two
+ * of the three hosts, and the request is otherwise exactly what a browser on
+ * the vendor's own page makes.
+ *
+ * ## Why this is an interface and not four exported functions
+ *
+ * A Node backend embedding this has its own opinions about retries,
+ * connection pools, proxies and rate limits, and patching a module global is
+ * not how it expresses them.
+ *
+ * So every scrape takes a {@link Fetcher}. The default is the four lines
+ * below; a caller that wants otherwise passes its own, and a test passes a
+ * stub with no network behind it. `tests/setup.ts` additionally replaces the
+ * global `fetch` with one that throws, so a test that forgets to pass a stub
+ * fails loudly instead of quietly paging a vendor's whole catalog.
+ */
+/** What every request from the default fetcher identifies as. */
+export declare const USER_AGENT = "Mozilla/5.0";
+/**
+ * Milliseconds. Long, because a vendor's variant table for a 259-row family is
+ * a slow render on their side and a timeout would read as a scrape failure.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+/**
+ * The transport a scrape reads through.
+ *
+ * Four methods because the four vendors between them need exactly four
+ * behaviours, and the differences are deliberate — see {@link createFetcher}.
+ */
+export interface Fetcher {
+    /** One GET, verbatim. For anything that is not text — a STEP model. */
+    bytes(url: string): Promise<Uint8Array>;
+    /** One GET, decoded as UTF-8, replacing undecodable bytes. */
+    text(url: string): Promise<string>;
+    /** One GET, parsed as JSON. */
+    json<T = unknown>(url: string): Promise<T>;
+    /** One POST of a JSON body, parsed as JSON. */
+    postJson<T = unknown>(url: string, payload: unknown): Promise<T>;
+}
+/** Options the default fetcher accepts. */
+export interface FetcherOptions {
+    /** Milliseconds before a request is abandoned. */
+    timeoutMs?: number;
+    /** What to identify as. */
+    userAgent?: string;
+    /**
+     * The underlying `fetch`. Injectable so a consumer can supply an
+     * instrumented or proxied one without reimplementing the decoding rules
+     * below, which are the part that has to stay consistent.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * A response that is not a 2xx, named so the URL is in the message.
+ *
+ * Carries the status because one caller needs to tell 404 from everything
+ * else: REGO-FIX publishes no DIN 4000 document for two of its BT+ 30 holders,
+ * and "the vendor has none" is a real state a scrape skips past, where any
+ * other status is a failed request that has to stop the run.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(url: string, status: number);
+}
+/**
+ * The HTTP status behind an error, or null when it carries none.
+ *
+ * Duck-typed rather than an `instanceof HttpError` check, so a consumer that
+ * supplies its own {@link Fetcher} — with its own error type carrying its own
+ * `status` — still gets the 404 handling the vendor adapters depend on.
+ */
+export declare function statusOf(error: unknown): number | null;
+/**
+ * The default transport: one request, a browser `User-Agent`, and a timeout.
+ *
+ * The two decoders differ on purpose. `text` replaces an undecodable byte,
+ * because these are vendor HTML and XML documents that occasionally carry a
+ * stray byte in a description, and refusing the whole 257-row table over one
+ * of them would lose the 256 good rows to no purpose. `json` is strict,
+ * because a JSON document with an undecodable byte in it is a broken response
+ * and replacing the byte would hand the parser a document the server never
+ * sent.
+ */
+export declare function createFetcher(options?: FetcherOptions): Fetcher;

package/dist/fetch.js

@@ -0,0 +1,116 @@
+/**
+ * The polite GET every transport here was copying.
+ *
+ * Three vendors, three unrelated transports — an AEM variant-table GET, a
+ * Firestore REST walk, an Elasticsearch proxy POST — and all three arrived at
+ * the same four lines: build a request, set a browser `User-Agent`, send it
+ * with a timeout, decode. Four copies of four lines is not expensive; four
+ * copies of the *decisions* in them is, because the decisions are the part
+ * that has to be consistent. A vendor whose transport needs something else — a
+ * session, a retry policy, a browser — keeps it in its own module rather than
+ * widening this one.
+ *
+ * **The `User-Agent` is not evasion.** These are unauthenticated, publicly
+ * served endpoints; a default agent gets a 403 from ordinary CDN rules on two
+ * of the three hosts, and the request is otherwise exactly what a browser on
+ * the vendor's own page makes.
+ *
+ * ## Why this is an interface and not four exported functions
+ *
+ * A Node backend embedding this has its own opinions about retries,
+ * connection pools, proxies and rate limits, and patching a module global is
+ * not how it expresses them.
+ *
+ * So every scrape takes a {@link Fetcher}. The default is the four lines
+ * below; a caller that wants otherwise passes its own, and a test passes a
+ * stub with no network behind it. `tests/setup.ts` additionally replaces the
+ * global `fetch` with one that throws, so a test that forgets to pass a stub
+ * fails loudly instead of quietly paging a vendor's whole catalog.
+ */
+/** What every request from the default fetcher identifies as. */
+export const USER_AGENT = 'Mozilla/5.0';
+/**
+ * Milliseconds. Long, because a vendor's variant table for a 259-row family is
+ * a slow render on their side and a timeout would read as a scrape failure.
+ */
+export const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * A response that is not a 2xx, named so the URL is in the message.
+ *
+ * Carries the status because one caller needs to tell 404 from everything
+ * else: REGO-FIX publishes no DIN 4000 document for two of its BT+ 30 holders,
+ * and "the vendor has none" is a real state a scrape skips past, where any
+ * other status is a failed request that has to stop the run.
+ */
+export class HttpError extends Error {
+    status;
+    url;
+    constructor(url, status) {
+        super(`${url}: the vendor answered ${status}`);
+        this.status = status;
+        this.url = url;
+        Object.setPrototypeOf(this, HttpError.prototype);
+        this.name = 'HttpError';
+    }
+}
+/**
+ * The HTTP status behind an error, or null when it carries none.
+ *
+ * Duck-typed rather than an `instanceof HttpError` check, so a consumer that
+ * supplies its own {@link Fetcher} — with its own error type carrying its own
+ * `status` — still gets the 404 handling the vendor adapters depend on.
+ */
+export function statusOf(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? status : null;
+}
+function checkOk(url, response) {
+    if (!response.ok)
+        throw new HttpError(url, response.status);
+}
+/**
+ * The default transport: one request, a browser `User-Agent`, and a timeout.
+ *
+ * The two decoders differ on purpose. `text` replaces an undecodable byte,
+ * because these are vendor HTML and XML documents that occasionally carry a
+ * stray byte in a description, and refusing the whole 257-row table over one
+ * of them would lose the 256 good rows to no purpose. `json` is strict,
+ * because a JSON document with an undecodable byte in it is a broken response
+ * and replacing the byte would hand the parser a document the server never
+ * sent.
+ */
+export function createFetcher(options = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, userAgent = USER_AGENT, fetch: send = globalThis.fetch, } = options;
+    async function request(url, init) {
+        const response = await send(url, {
+            ...init,
+            headers: { 'User-Agent': userAgent, ...init?.headers },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        checkOk(url, response);
+        return response;
+    }
+    return {
+        async bytes(url) {
+            return new Uint8Array(await (await request(url)).arrayBuffer());
+        },
+        async text(url) {
+            const buffer = await (await request(url)).arrayBuffer();
+            return new TextDecoder('utf-8').decode(buffer);
+        },
+        async json(url) {
+            const buffer = await (await request(url)).arrayBuffer();
+            const body = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+            return JSON.parse(body);
+        },
+        async postJson(url, payload) {
+            const response = await request(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+            });
+            const body = new TextDecoder('utf-8', { fatal: true }).decode(await response.arrayBuffer());
+            return JSON.parse(body);
+        },
+    };
+}

package/dist/identity.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Vendor identity: which brands this package knows, and how records are named.
+ *
+ * Kept apart from the adapters because every one of them needs it — a scraper
+ * resolves a brand to a host and, on the two AEM brands, to a component node;
+ * record identity resolves the same brand to a `vendor` string, a product URL
+ * and the UUID namespace its records are minted under.
+ *
+ * **Every record's guid is minted in its own brand's namespace.** That is what
+ * makes a guid collision across brands structurally impossible rather than
+ * merely unlikely: a material number is a vendor-local integer, and nothing
+ * reserves `100003658` to Kennametal. One namespace for every brand is
+ * harmless only while two brands share a number space by accident.
+ *
+ * The preset namespace is deliberately absent. Presets are the conversion
+ * half, which stays out of this package (see `docs/TOOL-SCRAPER-PLAN.md`,
+ * decision 1), and a constant nothing here reads would be a pinned value with
+ * nothing pinning it.
+ */
+/** What this package knows about one manufacturer. */
+export interface Brand {
+    /** The bare hostname, for a transport that builds its own URLs. */
+    host: string;
+    /**
+     * The brand's home page, and therefore its guid namespace seed.
+     *
+     * **Stated rather than derived.** `https://www.{host}` is right for the two
+     * AEM brands and wrong for a host carrying its own subdomain — it would mint
+     * REGO-FIX under the nonsense URL `https://www.us.rego-fix.com`.
+     */
+    home: string;
+    /** What the `vendor` field of a record from this brand says. */
+    vendor: string;
+    /** The vendor's own page for one part, with a `{material}` hole. */
+    productLink: string;
+    /**
+     * The AEM component node that serves a family's variant table.
+     *
+     * **AEM-specific and therefore optional** (2026-08-07). It is a fact about
+     * Kennametal's platform and not about vendors in general — REGO-FIX is a
+     * Drupal site with an Elasticsearch proxy and has no such node. Read it off
+     * a family page's `data-path` attribute when a new brand turns up.
+     */
+    node?: string;
+}
+/**
+ * The brands this package can scrape, by their internal key.
+ *
+ * WIDIA is Kennametal's sister brand on the same AEM/Hybris platform; only the
+ * host, the AEM component node and the vendor string differ. Families default
+ * to `kennametal` unless their config names a brand.
+ */
+export declare const BRANDS: {
+    readonly kennametal: {
+        readonly host: "kennametal.com";
+        readonly home: "https://www.kennametal.com";
+        readonly node: "product_variants";
+        readonly vendor: "Kennametal";
+        readonly productLink: "https://www.kennametal.com/us/en/products/p.{material}.html";
+    };
+    readonly widia: {
+        readonly host: "widia.com";
+        readonly home: "https://www.widia.com";
+        readonly node: "product_variants_cop";
+        readonly vendor: "WIDIA";
+        readonly productLink: "https://www.widia.com/us/en/products/p.{material}.html";
+    };
+    readonly regofix: {
+        readonly host: "us.rego-fix.com";
+        readonly home: "https://us.rego-fix.com";
+        readonly vendor: "REGO-FIX";
+        readonly productLink: "https://us.rego-fix.com/en/productfinder?q={material}";
+    };
+    readonly destinytool: {
+        readonly host: "destinytool.com";
+        readonly home: "https://destinytool.com";
+        readonly vendor: "Destiny Tool";
+        readonly productLink: "https://destinytool.com/products?search={material}";
+    };
+};
+/**
+ * The brands this package knows, as a type.
+ *
+ * Derived from {@link BRANDS} rather than listed, so the two cannot disagree,
+ * a new brand needs no second edit, and a typo is a compile error rather than
+ * a missing key at run time.
+ */
+export type BrandName = keyof typeof BRANDS;
+/**
+ * The two brands on Kennametal's AEM platform.
+ *
+ * A named type because it is a real constraint rather than a convenience: the
+ * Kennametal transport reads {@link Brand.node}, and a brand without one
+ * simply cannot be passed to it — the scraper's signature says so, and
+ * REGO-FIX cannot reach it.
+ *
+ * The value exists alongside the type because the CLI has to check a *string*
+ * off argv against this set — a type cannot do that, and checking against
+ * {@link BRANDS} instead let `--brand regofix` through to a URL with
+ * `undefined` in its path.
+ */
+export declare const AEM_BRANDS: readonly ["kennametal", "widia"];
+export type AemBrandName = (typeof AEM_BRANDS)[number];
+/**
+ * The UUID namespace records of `brand` are minted under.
+ *
+ * Seeded from the brand's own home page, so a new brand gets a distinct
+ * namespace for free. Deterministic across machines and runs, which is the
+ * whole point: tool guids are the join key for every downstream consumer of a
+ * scrape.
+ *
+ * Kennametal's value is unchanged from the single namespace this package used
+ * before 2026-08-07 — the migration therefore churned WIDIA's six tools and
+ * nothing else.
+ */
+export declare function vendorNamespace(brand: BrandName): string;
+/**
+ * The vendor's own page for one orderable part.
+ *
+ * Per-brand rather than one template, because the shape is not shared: the two
+ * AEM brands serve a product page per material number, REGO-FIX serves none at
+ * all and is linked into its ProductFinder instead. A single format string
+ * with a `{host}` hole encoded the AEM path as though it were universal.
+ */
+export declare function productLink(brand: BrandName, material: string): string;
+/**
+ * The stable guid for one orderable part, from its vendor material number.
+ *
+ * One function because tools and toolholding must mint identically: a holder
+ * and a tool are different kinds of record but they share a guid space, and a
+ * consumer that builds a catalog from both refuses a collision between them.
+ */
+export declare function recordGuid(brand: BrandName, material: string): string;

package/dist/identity.js

@@ -0,0 +1,118 @@
+/**
+ * Vendor identity: which brands this package knows, and how records are named.
+ *
+ * Kept apart from the adapters because every one of them needs it — a scraper
+ * resolves a brand to a host and, on the two AEM brands, to a component node;
+ * record identity resolves the same brand to a `vendor` string, a product URL
+ * and the UUID namespace its records are minted under.
+ *
+ * **Every record's guid is minted in its own brand's namespace.** That is what
+ * makes a guid collision across brands structurally impossible rather than
+ * merely unlikely: a material number is a vendor-local integer, and nothing
+ * reserves `100003658` to Kennametal. One namespace for every brand is
+ * harmless only while two brands share a number space by accident.
+ *
+ * The preset namespace is deliberately absent. Presets are the conversion
+ * half, which stays out of this package (see `docs/TOOL-SCRAPER-PLAN.md`,
+ * decision 1), and a constant nothing here reads would be a pinned value with
+ * nothing pinning it.
+ */
+import { uuid5, NAMESPACE_URL } from './uuid5.js';
+/**
+ * The brands this package can scrape, by their internal key.
+ *
+ * WIDIA is Kennametal's sister brand on the same AEM/Hybris platform; only the
+ * host, the AEM component node and the vendor string differ. Families default
+ * to `kennametal` unless their config names a brand.
+ */
+export const BRANDS = {
+    kennametal: {
+        host: 'kennametal.com',
+        home: 'https://www.kennametal.com',
+        node: 'product_variants',
+        vendor: 'Kennametal',
+        productLink: 'https://www.kennametal.com/us/en/products/p.{material}.html',
+    },
+    widia: {
+        host: 'widia.com',
+        home: 'https://www.widia.com',
+        node: 'product_variants_cop',
+        vendor: 'WIDIA',
+        productLink: 'https://www.widia.com/us/en/products/p.{material}.html',
+    },
+    // REGO-FIX publishes no per-part page: the Drupal node behind a part
+    // redirects to `/products`, and the only place a single part is addressable
+    // is the ProductFinder, whose Searchkit `SearchBox` has the default accessor
+    // id `q` and queries `field_sku_fulltext` among others (read off
+    // `searchkit-starter-app/build/static/js/main.d1ba5577.js`, JG 2026-08-07).
+    // So the link is a search for the part number rather than a page about it,
+    // which is what the vendor actually offers.
+    regofix: {
+        host: 'us.rego-fix.com',
+        home: 'https://us.rego-fix.com',
+        vendor: 'REGO-FIX',
+        productLink: 'https://us.rego-fix.com/en/productfinder?q={material}',
+    },
+    // Destiny Tool is a Next.js SPA with no product data in the HTML at all — it
+    // reads live from a Firestore database. Like REGO-FIX there is no per-part
+    // page to link to, only a client-rendered products list; unlike REGO-FIX's
+    // ProductFinder, nothing here has confirmed a search query parameter the SPA
+    // actually reads, so this is a best-effort link to the listing page rather
+    // than a verified deep link (JG 2026-08-19).
+    destinytool: {
+        host: 'destinytool.com',
+        home: 'https://destinytool.com',
+        vendor: 'Destiny Tool',
+        productLink: 'https://destinytool.com/products?search={material}',
+    },
+};
+/**
+ * The two brands on Kennametal's AEM platform.
+ *
+ * A named type because it is a real constraint rather than a convenience: the
+ * Kennametal transport reads {@link Brand.node}, and a brand without one
+ * simply cannot be passed to it — the scraper's signature says so, and
+ * REGO-FIX cannot reach it.
+ *
+ * The value exists alongside the type because the CLI has to check a *string*
+ * off argv against this set — a type cannot do that, and checking against
+ * {@link BRANDS} instead let `--brand regofix` through to a URL with
+ * `undefined` in its path.
+ */
+export const AEM_BRANDS = ['kennametal', 'widia'];
+/**
+ * The UUID namespace records of `brand` are minted under.
+ *
+ * Seeded from the brand's own home page, so a new brand gets a distinct
+ * namespace for free. Deterministic across machines and runs, which is the
+ * whole point: tool guids are the join key for every downstream consumer of a
+ * scrape.
+ *
+ * Kennametal's value is unchanged from the single namespace this package used
+ * before 2026-08-07 — the migration therefore churned WIDIA's six tools and
+ * nothing else.
+ */
+export function vendorNamespace(brand) {
+    return uuid5(NAMESPACE_URL, BRANDS[brand].home);
+}
+/**
+ * The vendor's own page for one orderable part.
+ *
+ * Per-brand rather than one template, because the shape is not shared: the two
+ * AEM brands serve a product page per material number, REGO-FIX serves none at
+ * all and is linked into its ProductFinder instead. A single format string
+ * with a `{host}` hole encoded the AEM path as though it were universal.
+ */
+export function productLink(brand, material) {
+    return BRANDS[brand].productLink.replace('{material}', material);
+}
+/**
+ * The stable guid for one orderable part, from its vendor material number.
+ *
+ * One function because tools and toolholding must mint identically: a holder
+ * and a tool are different kinds of record but they share a guid space, and a
+ * consumer that builds a catalog from both refuses a collision between them.
+ */
+export function recordGuid(brand, material) {
+    return uuid5(vendorNamespace(brand), material);
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Scrape cutting-tool geometry from vendor catalogs into records.
+ *
+ * A small vendor-neutral core plus one adapter per manufacturer under
+ * `vendors/`. The line between them is **what a fact is about**: a module
+ * under `vendors/` knows one manufacturer's transport, its column vocabulary
+ * or its own dimension codes, and a module beside this one knows the domain —
+ * what a tool record is, how a guid is minted, what the ISO workpiece groups
+ * are.
+ *
+ * Two adapters share no code with each other, and
+ * `tests/vendor-boundary.test.ts` asserts it from the package tree rather than
+ * from a list. What they share is the core, and that sharing is the point: it
+ * is what makes two vendors' catalogs comparable.
+ *
+ * ## This entry point is records, not files
+ *
+ * Every scrape returns rows. Writing them to a CSV, and the provenance sidecar
+ * that goes beside one, is `@toolpath/tool-scraper/node` — a separate entry
+ * point, because a backend embedding this wants the data and a maintainer
+ * running the CLI wants the file, and only one of those two needs `fs`.
+ */
+export * from './conventions.js';
+export * from './errors.js';
+export * from './family.js';
+export * from './fetch.js';
+export * from './identity.js';
+export * from './provenance.js';
+export * from './records.js';
+export * from './scrape.js';
+export * from './thread.js';

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * Scrape cutting-tool geometry from vendor catalogs into records.
+ *
+ * A small vendor-neutral core plus one adapter per manufacturer under
+ * `vendors/`. The line between them is **what a fact is about**: a module
+ * under `vendors/` knows one manufacturer's transport, its column vocabulary
+ * or its own dimension codes, and a module beside this one knows the domain —
+ * what a tool record is, how a guid is minted, what the ISO workpiece groups
+ * are.
+ *
+ * Two adapters share no code with each other, and
+ * `tests/vendor-boundary.test.ts` asserts it from the package tree rather than
+ * from a list. What they share is the core, and that sharing is the point: it
+ * is what makes two vendors' catalogs comparable.
+ *
+ * ## This entry point is records, not files
+ *
+ * Every scrape returns rows. Writing them to a CSV, and the provenance sidecar
+ * that goes beside one, is `@toolpath/tool-scraper/node` — a separate entry
+ * point, because a backend embedding this wants the data and a maintainer
+ * running the CLI wants the file, and only one of those two needs `fs`.
+ */
+export * from './conventions.js';
+export * from './errors.js';
+export * from './family.js';
+export * from './fetch.js';
+export * from './identity.js';
+export * from './provenance.js';
+export * from './records.js';
+export * from './scrape.js';
+export * from './thread.js';

package/dist/node/cad-mirror.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The bulk STEP mirror — a maintainer's tool, not part of the library.
+ *
+ * A vendor's CAD step resolves each part's permanent URL and writes it into
+ * `conventions.CAD_COLUMN`. This reads that column back and downloads every
+ * file — and it is vendor-neutral for the same reason the column is: two
+ * adapters write it and neither owns it.
+ *
+ * **It is here rather than beside the lookup, and that is a decision.** Three
+ * things make it a poor fit for a package a Node backend imports:
+ *
+ * 1. It is filesystem-bound by nature. There is no sensible "return the data
+ *    instead" version — a family is roughly a megabyte of STEP, and more at
+ *    scale.
+ * 2. It is a batch job with rate-limit pauses, not a request-scoped call.
+ *    Eight-plus seconds of serial fetch-and-sleep inside a request handler is
+ *    the wrong shape; putting it in a worker is the consumer's decision, not
+ *    this package's.
+ * 3. These are the vendor's CAD binaries. The stance is that they are mirrored
+ *    locally for measuring a holder and never redistributed, and a public
+ *    module offering a one-call bulk downloader is a different exposure than a
+ *    command a maintainer runs.
+ *
+ * What a consumer wants is the URL — to link to, or to fetch one of on demand
+ * — which is what the annotate step already gives it. The seam was there
+ * before this split: the column exists precisely so downloading is a separate,
+ * later, optional step.
+ */
+import type { Fetcher } from '../fetch.js';
+import { type ScrapedRow, type Warn } from '../scrape.js';
+/** One STEP file onto disk. Returns the bytes written. */
+export declare function downloadStep(fetcher: Fetcher, url: string, dest: string): Promise<number>;
+/** One mirrored file. */
+export interface MirroredStep {
+    catalogNumber: string;
+    bytes: number;
+}
+/**
+ * Every STEP model a holder scrape names, into `outDir`, one file per row.
+ *
+ * Named for the catalog number rather than the material number, because the
+ * filename is what a human reads and `BT30ER16060M` says what the part is
+ * where `1258023` does not.
+ *
+ * **`outDir` is a required argument and never inferred.** These files are a
+ * local working copy, they are gitignored, and a default that pointed into a
+ * tracked directory would be the one mistake that silently commits ~3 MB of
+ * vendor binaries.
+ *
+ * A row with no CAD URL is skipped rather than failed — that is
+ * `lightweightStepUrl`'s documented null case arriving here — and a skipped
+ * row spends no delay, because the count that matters is downloads and a
+ * family that is mostly blank should not sleep its way through the gaps.
+ */
+export declare function mirrorFamilySteps(fetcher: Fetcher, rows: readonly ScrapedRow[], outDir: string, delayMs?: number, warn?: Warn): Promise<MirroredStep[]>;

package/dist/node/cad-mirror.js

@@ -0,0 +1,89 @@
+/**
+ * The bulk STEP mirror — a maintainer's tool, not part of the library.
+ *
+ * A vendor's CAD step resolves each part's permanent URL and writes it into
+ * `conventions.CAD_COLUMN`. This reads that column back and downloads every
+ * file — and it is vendor-neutral for the same reason the column is: two
+ * adapters write it and neither owns it.
+ *
+ * **It is here rather than beside the lookup, and that is a decision.** Three
+ * things make it a poor fit for a package a Node backend imports:
+ *
+ * 1. It is filesystem-bound by nature. There is no sensible "return the data
+ *    instead" version — a family is roughly a megabyte of STEP, and more at
+ *    scale.
+ * 2. It is a batch job with rate-limit pauses, not a request-scoped call.
+ *    Eight-plus seconds of serial fetch-and-sleep inside a request handler is
+ *    the wrong shape; putting it in a worker is the consumer's decision, not
+ *    this package's.
+ * 3. These are the vendor's CAD binaries. The stance is that they are mirrored
+ *    locally for measuring a holder and never redistributed, and a public
+ *    module offering a one-call bulk downloader is a different exposure than a
+ *    command a maintainer runs.
+ *
+ * What a consumer wants is the URL — to link to, or to fetch one of on demand
+ * — which is what the annotate step already gives it. The seam was there
+ * before this split: the column exists precisely so downloading is a separate,
+ * later, optional step.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CAD_COLUMN } from '../conventions.js';
+import { REQUEST_DELAY_MS, consoleWarn, pause } from '../scrape.js';
+/**
+ * A catalog number as one path segment.
+ *
+ * REGO-FIX's catalog number is the vendor's own title — `BT 30 / PG 25 x 075`
+ * — and a separator in it was being honoured as one: `downloadStep` creates
+ * the parent directory, so the file landed in a `BT 30 ` subdirectory instead
+ * of flat in `outDir`, against what this module promises. The number stays
+ * readable, which is the whole reason the file is named for it.
+ */
+function fileName(catalogNumber) {
+    return catalogNumber.replaceAll(/[/\\]/g, '-');
+}
+/** One STEP file onto disk. Returns the bytes written. */
+export async function downloadStep(fetcher, url, dest) {
+    // Straight to `dest` rather than through a temp file: these are ~54 KB
+    // static CDN objects, and a half-written one is caught by whatever tries to
+    // import it, not by anything here.
+    const data = await fetcher.bytes(url);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, data);
+    return data.byteLength;
+}
+/**
+ * Every STEP model a holder scrape names, into `outDir`, one file per row.
+ *
+ * Named for the catalog number rather than the material number, because the
+ * filename is what a human reads and `BT30ER16060M` says what the part is
+ * where `1258023` does not.
+ *
+ * **`outDir` is a required argument and never inferred.** These files are a
+ * local working copy, they are gitignored, and a default that pointed into a
+ * tracked directory would be the one mistake that silently commits ~3 MB of
+ * vendor binaries.
+ *
+ * A row with no CAD URL is skipped rather than failed — that is
+ * `lightweightStepUrl`'s documented null case arriving here — and a skipped
+ * row spends no delay, because the count that matters is downloads and a
+ * family that is mostly blank should not sleep its way through the gaps.
+ */
+export async function mirrorFamilySteps(fetcher, rows, outDir, delayMs = REQUEST_DELAY_MS, warn = consoleWarn) {
+    const written = [];
+    for (const row of rows) {
+        const url = (row[CAD_COLUMN] ?? '').trim();
+        if (!url)
+            continue;
+        const catalogNumber = row['ISO Catalog Number'] ?? '';
+        if (!catalogNumber) {
+            warn(`  SKIPPED a row with a CAD URL and no catalog number to name it`);
+            continue;
+        }
+        if (written.length > 0)
+            await pause(delayMs);
+        const bytes = await downloadStep(fetcher, url, join(outDir, `${fileName(catalogNumber)}.stp`));
+        written.push({ catalogNumber, bytes });
+    }
+    return written;
+}