@toolpath/tool-scraper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toolpath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @toolpath/tool-scraper
+
+Scrapes cutting-tool and toolholding geometry from vendor catalogs into records.
+
+Node ≥20, ESM, one runtime dependency. One vendor-neutral core plus one adapter per manufacturer
+under `src/vendors/`; two adapters share the core and never each other, which
+`tests/vendor-boundary.test.ts` asserts from the package tree rather than from a list.
+
+**Scraped output is not committed.** A CSV is the vendor's data and a working file, not source —
+and this repository is public, which is a second reason independent of size.
+
+## Install
+
+```sh
+pnpm add @toolpath/tool-scraper
+```
+
+## Vendors
+
+| Vendor             | Transport                                        | What it publishes     |
+| ------------------ | ------------------------------------------------ | --------------------- |
+| Kennametal / WIDIA | AEM variant-table GET, parsed with `htmlparser2` | tools and toolholding |
+| REGO-FIX           | Elasticsearch proxy POST + per-part DIN 4000 XML | toolholding           |
+| Destiny Tool       | Firestore REST, paginated                        | solid end mills       |
+
+## Two entry points
+
+**`@toolpath/tool-scraper` returns records.** Every scrape hands back rows and enough provenance to
+say where they came from; nothing in it touches the filesystem, so a backend can embed it and do
+what it likes with the result.
+
+```ts
+import { createFetcher } from '@toolpath/tool-scraper'
+import { scrapeFamily } from '@toolpath/tool-scraper/vendors/kennametal'
+
+const fetcher = createFetcher() // or your own: retries, proxy, rate limits
+const { header, rows, source } = await scrapeFamily(fetcher, '100003658')
+```
+
+The transport is a parameter, not a module global. Supply your own `Fetcher` and the vendor
+adapters read through it — which is also how every test in this package runs without a network.
+
+**`@toolpath/tool-scraper/node` writes files.** CSV serialization, the provenance sidecar, the
+scrape-root resolution and the bulk CAD mirror all need `fs`, so they are a separate entry point and
+a consumer that only wants records never imports them.
+
+## Command line
+
+Every command prints the resolved scrape root before it does anything, and writes a receipt beside
+what it produces — the source URL, the family code, a timestamp, the row count and the scraper
+version.
+
+```sh
+export TOOLPATH_SCRAPE_ROOT=~/toolpath-scrapes      # default: ./scrape-out, gitignored
+
+toolpath-scrape kennametal 100003658 "$TOOLPATH_SCRAPE_ROOT/kennametal/csv/godrill_3xd_metric.csv"
+toolpath-scrape materials godrill_3xd_metric.csv
+toolpath-scrape regofix holders "$TOOLPATH_SCRAPE_ROOT/regofix/csv/regofix_bt30_pg_holders.csv"
+toolpath-scrape destinytool "$TOOLPATH_SCRAPE_ROOT/destinytool/csv/destinytool_end_mills_inch.csv"
+```
+
+`toolpath-scrape --help` lists the rest.
+
+## The record
+
+Geometry lands in **ISO 13399** codes — `DC`, `OAL`, `LCF`, `RE`, `NOF`, `SIG`, `TP` — the
+machine-tool industry's own interchange dictionary. CAM vendors implement subsets of it, which is
+why these names also appear in Fusion's tool JSON. `records.GEOMETRY_FIELDS` carries each code's
+definition and names the three that are Autodesk's rather than the standard's.
+
+Vendor CSVs keep the **vendor's** own column labels. Nothing reads a vendor's CSV but that vendor's
+adapter, and `conventions.ts` holds the short list of rules that do hold across all of them.
+
+Every per-family constant no vendor table states carries its provenance — whether it was
+vendor-stated, derived or assumed, and by whom on what date. The types enforce it: an assumed fact
+without a note, a date and initials does not compile.
+
+## Documentation
+
+- [`docs/ADDING-A-VENDOR.md`](docs/ADDING-A-VENDOR.md) — the runbook.
+- [`docs/KENNAMETAL_CAD_API.md`](docs/KENNAMETAL_CAD_API.md),
+  [`docs/KENNAMETAL_SPEEDFEED_API.md`](docs/KENNAMETAL_SPEEDFEED_API.md),
+  [`docs/REGOFIX_PRODUCTFINDER_API.md`](docs/REGOFIX_PRODUCTFINDER_API.md) — how each endpoint was
+  found, and the dead ends tried first.
+- [`../../docs/TOOL-SCRAPER-PLAN.md`](../../docs/TOOL-SCRAPER-PLAN.md) — the structure, the evidence
+  behind it, and what has landed.
+
+## Tests
+
+```sh
+pnpm --filter @toolpath/tool-scraper test
+```
+
+Nothing in the suite reaches a vendor: `tests/setup.ts` replaces the global `fetch` with one that
+throws, so a test that forgets its stub fails loudly instead of quietly paging a vendor's catalog.
+
+Tests that read a scraped CSV skip with a named reason where no scrape exists; set
+`TOOLPATH_REQUIRE_CORPUS=1` on a machine that keeps one to turn those skips into failures.

package/dist/conventions.d.ts

@@ -0,0 +1,124 @@
+/**
+ * What every vendor's CSV agrees on, written down so it can be checked.
+ *
+ * A scraped CSV keeps **that vendor's own column labels**. Relabelling them
+ * into a shared vocabulary on the way into the file would put a lie in the
+ * file whose whole job is to record what the vendor published, and the labels
+ * really do not line up: Kennametal's `D1_mm` and Destiny Tool's `cutDia_in`
+ * are the same measurement under names neither vendor would recognise in the
+ * other's table. Nothing reads a vendor's CSV but that vendor's own adapter.
+ *
+ * So this is not a schema. It is the short list of conventions that hold
+ * *across* the CSVs anyway, and the reason to make them explicit is that
+ * vendor #3 already drifted from one:
+ *
+ * | Convention                                        | Held by                   |
+ * | ------------------------------------------------- | ------------------------- |
+ * | `_mm`/`_in` carries the unit on a dimension       | all three                 |
+ * | Multi-value cells are space-separated             | all three                 |
+ * | One row per orderable part                        | all three                 |
+ * | `CAD_STEP_URL` names a CAD model where one exists | Kennametal, REGO-FIX      |
+ * | Unmapped vendor codes keep a `DIN_` prefix        | REGO-FIX; rule is general |
+ * | The identity columns                              | **broken** — see below    |
+ *
+ * Identity and units are the two worth enforcing; the rest are advisory, and
+ * are here so that "advisory" is a decision on the page rather than an
+ * omission.
+ *
+ * **A vendor's column label can collide with a real ISO 13399 code and mean
+ * something else.** The standard defines `D1` as fixing hole diameter and `L`
+ * as cutting edge length; Kennametal's tables use `D1` for the cutting
+ * diameter and `L` for the overall length. The two vocabularies overlap on
+ * `D1`, `L`, `B`, `H`, `RE`, `SIG` and `TP` among others, so anything that
+ * reads a vendor CSV without going through that vendor's adapter can be
+ * confidently wrong rather than obviously broken. See `records.GEOMETRY_FIELDS`
+ * for the canonical side of that line.
+ */
+import type { BrandName } from './identity.js';
+/** Which unit system a family's dimensional columns are published in. */
+export type UnitSystem = 'millimeters' | 'inches';
+/**
+ * The suffix a dimensional column carries, per unit system.
+ *
+ * **This is the whole of the unit rule, in one place, on purpose.** A vendor
+ * adapter declares a bare label — `'D1'`, never `'D1_mm'` — and the core
+ * appends the suffix from the family's declared unit. Choosing the suffix
+ * inside an adapter is exactly the mistake a declared `unit` exists to
+ * prevent, and a silent unit assumption is the likeliest way this data shows
+ * someone a wrong number: a family tagged metric that publishes both columns
+ * converts cleanly and reports 9.525 mm where a machinist ordered 3/8.
+ */
+export declare const UNIT_SUFFIX: Record<UnitSystem, string>;
+/**
+ * The CSV column holding a part's downloadable STEP model, for every vendor.
+ *
+ * Named for what it holds rather than for how one vendor names the format. It
+ * was `CAD_STP_LWM` until 2026-08-08: `LWM` is CDS Visual's key for
+ * Kennametal's lightweight model, and REGO-FIX publishes no such thing, so the
+ * moment a second vendor wrote into this column the name became a claim about
+ * the data that was false. That fact is still recorded in the Kennametal CAD
+ * module, where it is true.
+ *
+ * It sits here rather than with either vendor because two of them write it and
+ * neither owns it — the leak the vendor-boundary test exists to catch.
+ */
+export declare const CAD_COLUMN = "CAD_STEP_URL";
+/**
+ * The prefix an unmapped vendor code keeps, so it cannot read as a dimension.
+ *
+ * REGO-FIX's per-part DIN 4000 XML publishes codes — `A2`, `B1`, `B2` — whose
+ * meaning is not stated anywhere this package has been able to check. The
+ * standing rule is to leave such a code unlabelled rather than guess at what
+ * it measures, and a bare `A2` beside `L1_mm` reads as a labelled dimension.
+ * `DIN_A2` reads as what it is: a vendor code, pending a source.
+ */
+export declare const DIN_PREFIX = "DIN_";
+/**
+ * The columns that name one orderable part: its vendor-local number, and the
+ * catalog designation a human orders by.
+ *
+ * `Material Number` is the guid seed — see `identity.recordGuid` — so this is
+ * the one convention whose erosion is not cosmetic.
+ */
+export declare const IDENTITY_COLUMNS: readonly ["Material Number", "ISO Catalog Number"];
+/**
+ * Where a vendor's CSV does not use {@link IDENTITY_COLUMNS}, and what it uses
+ * instead.
+ *
+ * **One entry, and it is a record of drift rather than a licence.** REGO-FIX
+ * adopted Kennametal's identity labels; Destiny Tool passes Firestore's own
+ * `itemNumber` straight through and publishes no catalog designation at all —
+ * the convention was real but informal, and it eroded the first time a vendor
+ * did not resemble the first two. Writing the deviation down is what makes the
+ * fourth vendor's drift a decision somebody made rather than a thing that
+ * happened.
+ */
+export declare const IDENTITY_DEVIATIONS: Partial<Record<BrandName, readonly string[]>>;
+/**
+ * A vendor's bare column label, suffixed for `unit`.
+ *
+ * Throws rather than defaulting on an unknown unit system: the two callers
+ * that could pass one are a family config and a CLI flag, and a typo that
+ * silently picked millimetres would produce a clean conversion with the wrong
+ * numbers in it. `unit` is typed as a plain string for the CLI's sake — the
+ * flag arrives as one, and the check is the only thing between it and a
+ * mis-suffixed column.
+ */
+export declare function dimensionalColumn(label: string, unit: string): string;
+/**
+ * The columns that identify a part in `brand`'s CSV.
+ *
+ * {@link IDENTITY_COLUMNS} unless the brand is listed as a deviation, which is
+ * a lookup rather than a guess: a caller cannot resolve this by inspecting a
+ * header, because a header that is missing `Material Number` is
+ * indistinguishable from a scrape that lost it.
+ */
+export declare function identityColumns(brand: BrandName): readonly string[];
+/**
+ * Every identity column `brand` claims is really in the CSV header.
+ *
+ * The failure this prevents: a re-scrape whose part-number column moved or was
+ * renamed produces a CSV that still parses, still has the right number of
+ * rows, and mints every guid off an empty string.
+ */
+export declare function checkIdentityColumns(brand: BrandName, header: Iterable<string>): void;

package/dist/conventions.js

@@ -0,0 +1,143 @@
+/**
+ * What every vendor's CSV agrees on, written down so it can be checked.
+ *
+ * A scraped CSV keeps **that vendor's own column labels**. Relabelling them
+ * into a shared vocabulary on the way into the file would put a lie in the
+ * file whose whole job is to record what the vendor published, and the labels
+ * really do not line up: Kennametal's `D1_mm` and Destiny Tool's `cutDia_in`
+ * are the same measurement under names neither vendor would recognise in the
+ * other's table. Nothing reads a vendor's CSV but that vendor's own adapter.
+ *
+ * So this is not a schema. It is the short list of conventions that hold
+ * *across* the CSVs anyway, and the reason to make them explicit is that
+ * vendor #3 already drifted from one:
+ *
+ * | Convention                                        | Held by                   |
+ * | ------------------------------------------------- | ------------------------- |
+ * | `_mm`/`_in` carries the unit on a dimension       | all three                 |
+ * | Multi-value cells are space-separated             | all three                 |
+ * | One row per orderable part                        | all three                 |
+ * | `CAD_STEP_URL` names a CAD model where one exists | Kennametal, REGO-FIX      |
+ * | Unmapped vendor codes keep a `DIN_` prefix        | REGO-FIX; rule is general |
+ * | The identity columns                              | **broken** — see below    |
+ *
+ * Identity and units are the two worth enforcing; the rest are advisory, and
+ * are here so that "advisory" is a decision on the page rather than an
+ * omission.
+ *
+ * **A vendor's column label can collide with a real ISO 13399 code and mean
+ * something else.** The standard defines `D1` as fixing hole diameter and `L`
+ * as cutting edge length; Kennametal's tables use `D1` for the cutting
+ * diameter and `L` for the overall length. The two vocabularies overlap on
+ * `D1`, `L`, `B`, `H`, `RE`, `SIG` and `TP` among others, so anything that
+ * reads a vendor CSV without going through that vendor's adapter can be
+ * confidently wrong rather than obviously broken. See `records.GEOMETRY_FIELDS`
+ * for the canonical side of that line.
+ */
+import { ScraperConfigError } from './errors.js';
+/**
+ * The suffix a dimensional column carries, per unit system.
+ *
+ * **This is the whole of the unit rule, in one place, on purpose.** A vendor
+ * adapter declares a bare label — `'D1'`, never `'D1_mm'` — and the core
+ * appends the suffix from the family's declared unit. Choosing the suffix
+ * inside an adapter is exactly the mistake a declared `unit` exists to
+ * prevent, and a silent unit assumption is the likeliest way this data shows
+ * someone a wrong number: a family tagged metric that publishes both columns
+ * converts cleanly and reports 9.525 mm where a machinist ordered 3/8.
+ */
+export const UNIT_SUFFIX = {
+    millimeters: '_mm',
+    inches: '_in',
+};
+/**
+ * The CSV column holding a part's downloadable STEP model, for every vendor.
+ *
+ * Named for what it holds rather than for how one vendor names the format. It
+ * was `CAD_STP_LWM` until 2026-08-08: `LWM` is CDS Visual's key for
+ * Kennametal's lightweight model, and REGO-FIX publishes no such thing, so the
+ * moment a second vendor wrote into this column the name became a claim about
+ * the data that was false. That fact is still recorded in the Kennametal CAD
+ * module, where it is true.
+ *
+ * It sits here rather than with either vendor because two of them write it and
+ * neither owns it — the leak the vendor-boundary test exists to catch.
+ */
+export const CAD_COLUMN = 'CAD_STEP_URL';
+/**
+ * The prefix an unmapped vendor code keeps, so it cannot read as a dimension.
+ *
+ * REGO-FIX's per-part DIN 4000 XML publishes codes — `A2`, `B1`, `B2` — whose
+ * meaning is not stated anywhere this package has been able to check. The
+ * standing rule is to leave such a code unlabelled rather than guess at what
+ * it measures, and a bare `A2` beside `L1_mm` reads as a labelled dimension.
+ * `DIN_A2` reads as what it is: a vendor code, pending a source.
+ */
+export const DIN_PREFIX = 'DIN_';
+/**
+ * The columns that name one orderable part: its vendor-local number, and the
+ * catalog designation a human orders by.
+ *
+ * `Material Number` is the guid seed — see `identity.recordGuid` — so this is
+ * the one convention whose erosion is not cosmetic.
+ */
+export const IDENTITY_COLUMNS = ['Material Number', 'ISO Catalog Number'];
+/**
+ * Where a vendor's CSV does not use {@link IDENTITY_COLUMNS}, and what it uses
+ * instead.
+ *
+ * **One entry, and it is a record of drift rather than a licence.** REGO-FIX
+ * adopted Kennametal's identity labels; Destiny Tool passes Firestore's own
+ * `itemNumber` straight through and publishes no catalog designation at all —
+ * the convention was real but informal, and it eroded the first time a vendor
+ * did not resemble the first two. Writing the deviation down is what makes the
+ * fourth vendor's drift a decision somebody made rather than a thing that
+ * happened.
+ */
+export const IDENTITY_DEVIATIONS = {
+    destinytool: ['itemNumber'],
+};
+/**
+ * A vendor's bare column label, suffixed for `unit`.
+ *
+ * Throws rather than defaulting on an unknown unit system: the two callers
+ * that could pass one are a family config and a CLI flag, and a typo that
+ * silently picked millimetres would produce a clean conversion with the wrong
+ * numbers in it. `unit` is typed as a plain string for the CLI's sake — the
+ * flag arrives as one, and the check is the only thing between it and a
+ * mis-suffixed column.
+ */
+export function dimensionalColumn(label, unit) {
+    if (!Object.hasOwn(UNIT_SUFFIX, unit)) {
+        throw new ScraperConfigError(label, `unknown unit system ${JSON.stringify(unit)} ` +
+            `(known: ${Object.keys(UNIT_SUFFIX).sort().join(', ')})`);
+    }
+    return label + UNIT_SUFFIX[unit];
+}
+/**
+ * The columns that identify a part in `brand`'s CSV.
+ *
+ * {@link IDENTITY_COLUMNS} unless the brand is listed as a deviation, which is
+ * a lookup rather than a guess: a caller cannot resolve this by inspecting a
+ * header, because a header that is missing `Material Number` is
+ * indistinguishable from a scrape that lost it.
+ */
+export function identityColumns(brand) {
+    return IDENTITY_DEVIATIONS[brand] ?? IDENTITY_COLUMNS;
+}
+/**
+ * Every identity column `brand` claims is really in the CSV header.
+ *
+ * The failure this prevents: a re-scrape whose part-number column moved or was
+ * renamed produces a CSV that still parses, still has the right number of
+ * rows, and mints every guid off an empty string.
+ */
+export function checkIdentityColumns(brand, header) {
+    const present = new Set(header);
+    const missing = identityColumns(brand)
+        .filter((column) => !present.has(column))
+        .sort();
+    if (missing.length > 0) {
+        throw new ScraperConfigError(brand, `identity column(s) absent from the CSV: ${missing.join(', ')}`);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The two ways this package refuses, split by who has to fix it.
+ *
+ * - {@link ScraperConfigError} — **this package's own catalog is wrong.** A
+ *   family maps a canonical field that does not exist, a fact is missing the
+ *   note its source kind requires, two vendors claim one CSV name. Nothing a
+ *   retry or a different vendor response can fix; it is a bug here, and it is
+ *   raised before any network call.
+ * - {@link VendorResponseError} — **the vendor sent something this package
+ *   cannot read.** The variants endpoint changed shape, a scrape's row count
+ *   disagrees with the declared one, a DIN 4000 code that should be pinned is
+ *   absent. The catalog is fine; the world moved.
+ *
+ * They throw rather than exiting the process: a Node backend imports this, and
+ * a mapped column that moved must not take down somebody's request handler.
+ * Both carry a `subject` — the family, brand or part the failure is about — so
+ * a caller that catches one does not parse it back out of a sentence.
+ */
+/** Common shape: a message that already names its subject, plus the subject. */
+declare abstract class ScraperError extends Error {
+    /** The family, brand or part number this is about, and `message` leads with it. */
+    readonly subject: string;
+    constructor(subject: string, message: string);
+}
+/**
+ * This package's own catalog or column map is wrong.
+ *
+ * Thrown at config-validation time, which is before a scrape reaches the
+ * network — the whole point of validating a family's map up front is that a
+ * typo fails naming the family instead of as a missing-key fault on row 1 of a
+ * scrape that already ran.
+ */
+export declare class ScraperConfigError extends ScraperError {
+}
+/**
+ * A vendor's response was not the shape this package requires.
+ *
+ * Distinct from "the vendor returned nothing", which is often an ordinary
+ * answer — a facet query for a group a family is not rated for matches no
+ * rows, and that is data, not a fault. This is for the case where the reply
+ * cannot be read at all, because reporting zero rows there would look exactly
+ * like a family being discontinued.
+ */
+export declare class VendorResponseError extends ScraperError {
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,53 @@
+/**
+ * The two ways this package refuses, split by who has to fix it.
+ *
+ * - {@link ScraperConfigError} — **this package's own catalog is wrong.** A
+ *   family maps a canonical field that does not exist, a fact is missing the
+ *   note its source kind requires, two vendors claim one CSV name. Nothing a
+ *   retry or a different vendor response can fix; it is a bug here, and it is
+ *   raised before any network call.
+ * - {@link VendorResponseError} — **the vendor sent something this package
+ *   cannot read.** The variants endpoint changed shape, a scrape's row count
+ *   disagrees with the declared one, a DIN 4000 code that should be pinned is
+ *   absent. The catalog is fine; the world moved.
+ *
+ * They throw rather than exiting the process: a Node backend imports this, and
+ * a mapped column that moved must not take down somebody's request handler.
+ * Both carry a `subject` — the family, brand or part the failure is about — so
+ * a caller that catches one does not parse it back out of a sentence.
+ */
+/** Common shape: a message that already names its subject, plus the subject. */
+class ScraperError extends Error {
+    /** The family, brand or part number this is about, and `message` leads with it. */
+    subject;
+    constructor(subject, message) {
+        super(`${subject}: ${message}`);
+        this.subject = subject;
+        // `Error` is a built-in, so the prototype has to be restored by hand for
+        // `instanceof` to survive the ES2022 downlevel. Cheap, and the alternative
+        // is a catch block that silently never matches.
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = new.target.name;
+    }
+}
+/**
+ * This package's own catalog or column map is wrong.
+ *
+ * Thrown at config-validation time, which is before a scrape reaches the
+ * network — the whole point of validating a family's map up front is that a
+ * typo fails naming the family instead of as a missing-key fault on row 1 of a
+ * scrape that already ran.
+ */
+export class ScraperConfigError extends ScraperError {
+}
+/**
+ * A vendor's response was not the shape this package requires.
+ *
+ * Distinct from "the vendor returned nothing", which is often an ordinary
+ * answer — a facet query for a group a family is not rated for matches no
+ * rows, and that is data, not a fault. This is for the case where the reply
+ * cannot be read at all, because reporting zero rows there would look exactly
+ * like a family being discontinued.
+ */
+export class VendorResponseError extends ScraperError {
+}

package/dist/families/destinytool.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Destiny Tool's families.
+ *
+ * One today, and the vendor's whole catalog is one Firestore collection rather
+ * than a set of family pages — so there is no `familyCode` here to name a scrape
+ * target with. `vendors/destinytool/scrape.ts` fetches the collection and narrows
+ * to `type == 'End Mill'` after decoding, because `documents.list` supports no
+ * server-side filter.
+ *
+ * The 3,898 End Mills are 4,309 products minus 411 the package has no `ToolKind`
+ * for — Chamfer Mill, Thread Mill, Dovetail, Corner Rounder, Spot Drill, Drill
+ * Mill, Countersink, Chamfer End Mill. Those are deferred rather than dropped.
+ */
+export declare const FAMILIES: {
+    readonly 'destinytool_end_mills_inch.csv': {
+        readonly id: "end-mills-inch";
+        readonly brand: "destinytool";
+        readonly kind: "endmill";
+        readonly rows: 3898;
+        readonly columns: {
+            readonly DC: "cutDia";
+            readonly SFDM: "cutDia";
+            readonly OAL: "oal";
+            readonly LCF: "loc";
+            readonly RE: "rad";
+        };
+        readonly facts: {
+            readonly unit: {
+                readonly value: "inches";
+                readonly source: "vendor-stated";
+                readonly cite: "Destiny Tool product API (Firestore project studio-6030841929-4a1a2, collection 'products'), full scrape 2026-08-19 — every dimension on every one of the 3,898 End Mill documents is a US-customary fractional-inch string; no metric row exists";
+            };
+            readonly bmc: {
+                readonly value: "carbide";
+                readonly source: "assumed";
+                readonly note: "'material' is blank on 1,223 of 3,898 End Mills (31.4%); 'Carbide' (one row spells it 'CARBIDE') is the only non-blank value across the whole collection, and solid-carbide is standard for this class of vendor";
+                readonly checked: "2026-08-19";
+                readonly by: "JG";
+            };
+            readonly coolantThrough: {
+                readonly value: false;
+                readonly source: "assumed";
+                readonly note: "no coolant field published anywhere in the Firestore document schema";
+                readonly checked: "2026-08-19";
+                readonly by: "JG";
+            };
+        };
+    };
+};

package/dist/families/destinytool.js

@@ -0,0 +1,55 @@
+/**
+ * Destiny Tool's families.
+ *
+ * One today, and the vendor's whole catalog is one Firestore collection rather
+ * than a set of family pages — so there is no `familyCode` here to name a scrape
+ * target with. `vendors/destinytool/scrape.ts` fetches the collection and narrows
+ * to `type == 'End Mill'` after decoding, because `documents.list` supports no
+ * server-side filter.
+ *
+ * The 3,898 End Mills are 4,309 products minus 411 the package has no `ToolKind`
+ * for — Chamfer Mill, Thread Mill, Dovetail, Corner Rounder, Spot Drill, Drill
+ * Mill, Countersink, Chamfer End Mill. Those are deferred rather than dropped.
+ */
+export const FAMILIES = {
+    'destinytool_end_mills_inch.csv': {
+        id: 'end-mills-inch',
+        brand: 'destinytool',
+        kind: 'endmill',
+        rows: 3898,
+        // `SFDM` maps to the **same** label as `DC` on purpose: Destiny Tool
+        // publishes no structured shank column at all, and `endmillRecord`
+        // reads a shank diameter out of the description's own "SHK" text when
+        // the tool is necked, falling back to that shared column — i.e. to DC —
+        // otherwise. Two more per-record derivations the map cannot express are
+        // in `vendors/destinytool/records.ts`, with the evidence beside them.
+        columns: {
+            DC: 'cutDia',
+            SFDM: 'cutDia',
+            OAL: 'oal',
+            LCF: 'loc',
+            RE: 'rad',
+        },
+        facts: {
+            unit: {
+                value: 'inches',
+                source: 'vendor-stated',
+                cite: "Destiny Tool product API (Firestore project studio-6030841929-4a1a2, collection 'products'), full scrape 2026-08-19 — every dimension on every one of the 3,898 End Mill documents is a US-customary fractional-inch string; no metric row exists",
+            },
+            bmc: {
+                value: 'carbide',
+                source: 'assumed',
+                note: "'material' is blank on 1,223 of 3,898 End Mills (31.4%); 'Carbide' (one row spells it 'CARBIDE') is the only non-blank value across the whole collection, and solid-carbide is standard for this class of vendor",
+                checked: '2026-08-19',
+                by: 'JG',
+            },
+            coolantThrough: {
+                value: false,
+                source: 'assumed',
+                note: 'no coolant field published anywhere in the Firestore document schema',
+                checked: '2026-08-19',
+                by: 'JG',
+            },
+        },
+    },
+};

package/dist/families/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-family scrape config: what to fetch, and how its columns are labelled.
+ *
+ * One module per vendor, merged here. The split is the point: a REGO-FIX
+ * family is named whatever REGO-FIX calls it without anybody checking
+ * Kennametal's list first, and adding a vendor is a new file rather than an
+ * edit to a table three other vendors depend on.
+ *
+ * **Config, not code.** Nothing here imports an adapter — `registry` is the
+ * one module that knows both, and `tests/vendor-boundary.test.ts` refuses the
+ * alternative. In the source package this table briefly did the binding
+ * itself, which made the config import a manufacturer; the table is read by
+ * every test, and none of them should drag a vendor's scraper in behind it.
+ *
+ * Three kinds of key, and they are worth telling apart:
+ *
+ * - **Scrape targets** — `familyCode`, and whatever else names the thing to
+ *   fetch. This is what makes a scrape re-runnable without going back to the
+ *   browser to find the family page again.
+ * - **`columns`** — the vendor's own column labels, keyed by canonical ISO
+ *   13399 name, *without* a unit suffix. `registry.bindFamilies` runs each
+ *   through `records.checkColumnMap`, so a typo fails when the registry binds,
+ *   naming the family.
+ * - **`facts`** — the per-family constants no vendor table states, each
+ *   carrying its provenance. The registry checks and projects them, so readers
+ *   say `family.unit` and never learn about provenance.
+ *
+ * **Where a scrape lands is not here.** Resolving a data root needs `fs` and
+ * `process.env`, which would make this table unimportable in anything that
+ * never writes a file. It is `node/paths.ts`.
+ */
+import type { FamilyDefinition, ToolholdingDefinition } from '../family.js';
+/** Every cutting-tool family, keyed by the CSV it is scraped into. */
+export declare const FAMILIES: Record<string, FamilyDefinition>;
+/**
+ * Every toolholding family — holders, and the collets that go in them.
+ *
+ * Separate tables rather than a `kind` on one, because a holder and a collet
+ * are not variants of a thing: they carry different discriminants (a holder
+ * states a taper and a clamping mode; a collet states a series and a capacity
+ * band) and a scrape of one is not a scrape of the other.
+ */
+export declare const HOLDER_FAMILIES: Record<string, ToolholdingDefinition>;
+export declare const COLLET_FAMILIES: Record<string, ToolholdingDefinition>;
+/**
+ * Every family this package knows, by CSV name — tools and toolholding alike.
+ *
+ * Built once rather than searched per call, so a lookup can refuse an unknown
+ * name by listing what it does know.
+ *
+ * Through {@link merge} and not a spread, for the reason {@link merge} exists:
+ * a spread here would let a name claimed by two of the three tables resolve
+ * silently to whichever was spread last, and this is the table `familyConfig`
+ * — and therefore `familyBrand`, and therefore where a CSV is written — reads.
+ */
+export declare const ALL_FAMILIES: Record<string, FamilyDefinition | ToolholdingDefinition>;
+/** One family's config by CSV name, refusing a name nothing declares. */
+export declare function familyConfig(name: string): FamilyDefinition | ToolholdingDefinition;
+export { familyBrand, familyId } from '../family.js';