@toolpath/tool-scraper 0.1.0 → 2.0.0

package/dist/vendors/harvey/value.d.ts

@@ -0,0 +1,74 @@
+/**
+ * One display cell -> a number, or an honest reason there is none.
+ *
+ * Harvey publishes values the way a printed catalog does, because the table is
+ * a printed catalog: `.1250 (1/8)` is a decimal with the fraction a machinist
+ * orders by beside it, `1-1/2` is a mixed number, `3 mm` is a metric shank on
+ * an imperial page, and `-` means the column does not apply to that row.
+ *
+ * **One rule covers the whole grammar: the value is the leading token, and
+ * anything in parentheses is Harvey's own equivalent annotation.** Every shape
+ * measured across all 12,799 parts is in `docs/HARVEY_PRODUCT_TABLE.md` §4;
+ * this module is that section as code.
+ *
+ * ## Read `d`, never `v`
+ *
+ * Each cell also carries `v`, which looks pre-parsed and is the wrong field: it
+ * changes unit basis *within a single row*. On the metric ball page, `v` is the
+ * inch equivalent for the cutter diameter and the raw millimetre number for the
+ * length of cut. Anything reading it gets a clean conversion with wrong numbers
+ * in it — the exact failure `conventions.UNIT_SUFFIX` exists to prevent.
+ *
+ * ## A stated unit wins over the column's
+ *
+ * 46 cells across six otherwise-imperial families state a metric value outright
+ * — `3 mm` in a `SHANK DIAMETER` column on an inch page, a metric-shank tool
+ * listed among imperial ones. {@link dimension} converts those into the family's
+ * declared unit and warns, naming the part. It does **not** treat a
+ * parenthesised `(3 mm)` that way: that is an annotation on an inch value, and
+ * converting it would turn `.1181 in` into `3 in`.
+ */
+import type { UnitSystem } from '../../conventions.js';
+import { type Warn } from '../../scrape.js';
+/** What one display cell says. */
+export interface HarveyValue {
+    /** The leading numeric token, in whatever {@link stated} says. */
+    readonly value: number | null;
+    /** The unit the token states outright. Null where it states none. */
+    readonly stated: UnitSystem | null;
+    /** True where the token is an angle in degrees rather than a length. */
+    readonly degrees: boolean;
+    /** Harvey's parenthesised equivalent, verbatim — `1/8`, `3 mm`, `N.P.T.`. */
+    readonly annotation: string | null;
+    /** The multiplier a `(1.5x)` cell states, and nothing else. */
+    readonly ratio: number | null;
+    /** Text with no numeric reading at all: `I`, `II`, `III`, `LONG`. */
+    readonly code: string | null;
+}
+/**
+ * One cell's display text, read.
+ *
+ * An empty cell and a `-` both come back as {@link NOTHING}. They mean slightly
+ * different things to a reader of the catalog — "nothing published" and "does
+ * not apply" — and the same thing to anything building a record, which is that
+ * there is no number here and 0 is not a substitute for one.
+ */
+export declare function parseValue(display: string): HarveyValue;
+/**
+ * One cell as a length in `unit`, or null where it publishes none.
+ *
+ * `measure.asLength` makes both calls — convert-and-warn a cell whose stated
+ * unit disagrees with the family's, refuse an angle in a dimensional column —
+ * because they are the same two calls for every vendor and were a verbatim copy
+ * here and in `vendors/emuge/value.ts` until 2026-09-01. What is Harvey's is
+ * above: that `degrees` is a field of its own rather than a member of
+ * `stated`, and that a parenthesised `(3 mm)` is an annotation on an inch value
+ * and never the value itself.
+ *
+ * The 46 cells this converts are metric-shank tools listed among imperial ones
+ * — real parts somebody can order, which is why they are converted rather than
+ * dropped.
+ */
+export declare function dimension(display: string, unit: UnitSystem, what: string, warn?: Warn): number | null;
+/** One cell as a whole count — a flute or tooth number. Null where blank. */
+export declare function count(display: string): number | null;

package/dist/vendors/harvey/value.js

@@ -0,0 +1,119 @@
+/**
+ * One display cell -> a number, or an honest reason there is none.
+ *
+ * Harvey publishes values the way a printed catalog does, because the table is
+ * a printed catalog: `.1250 (1/8)` is a decimal with the fraction a machinist
+ * orders by beside it, `1-1/2` is a mixed number, `3 mm` is a metric shank on
+ * an imperial page, and `-` means the column does not apply to that row.
+ *
+ * **One rule covers the whole grammar: the value is the leading token, and
+ * anything in parentheses is Harvey's own equivalent annotation.** Every shape
+ * measured across all 12,799 parts is in `docs/HARVEY_PRODUCT_TABLE.md` §4;
+ * this module is that section as code.
+ *
+ * ## Read `d`, never `v`
+ *
+ * Each cell also carries `v`, which looks pre-parsed and is the wrong field: it
+ * changes unit basis *within a single row*. On the metric ball page, `v` is the
+ * inch equivalent for the cutter diameter and the raw millimetre number for the
+ * length of cut. Anything reading it gets a clean conversion with wrong numbers
+ * in it — the exact failure `conventions.UNIT_SUFFIX` exists to prevent.
+ *
+ * ## A stated unit wins over the column's
+ *
+ * 46 cells across six otherwise-imperial families state a metric value outright
+ * — `3 mm` in a `SHANK DIAMETER` column on an inch page, a metric-shank tool
+ * listed among imperial ones. {@link dimension} converts those into the family's
+ * declared unit and warns, naming the part. It does **not** treat a
+ * parenthesised `(3 mm)` that way: that is an annotation on an inch value, and
+ * converting it would turn `.1181 in` into `3 in`.
+ */
+import { asCount, asLength, fractionValue } from '../../measure.js';
+import { consoleWarn } from '../../scrape.js';
+/**
+ * Footnote references Harvey appends to a value or a tool number. 62 cells
+ * carry one; each points at a note printed under the table, and none of them is
+ * part of the number.
+ */
+const FOOTNOTE = /[*!†]+$/;
+/** Harvey's own equivalent, in parentheses at the end: `(1/8)`, `(3 mm)`. */
+const ANNOTATION = /\s*\(([^)]*)\)\s*$/;
+/** `(1.5x)`, `(30x)` — the vendor's reach- or length-to-diameter ratio. */
+const RATIO = /^(\d*\.?\d+)x$/;
+/**
+ * A mixed number, a simple fraction or a decimal, with an optional unit.
+ *
+ * The alternation is ordered longest-first on purpose: `\d*\.?\d+` alone
+ * matches the `3` of `3-3/4` and would leave the rest unread, which parses a
+ * 3.75-inch tool as a 3-inch one.
+ */
+const NUMBER = /^(\d+-\d+\/\d+|\d*\.?\d+\/\d+|\d*\.?\d+)\s*(mm|°)?$/;
+const NOTHING = {
+    value: null,
+    stated: null,
+    degrees: false,
+    annotation: null,
+    ratio: null,
+    code: null,
+};
+/**
+ * One cell's display text, read.
+ *
+ * An empty cell and a `-` both come back as {@link NOTHING}. They mean slightly
+ * different things to a reader of the catalog — "nothing published" and "does
+ * not apply" — and the same thing to anything building a record, which is that
+ * there is no number here and 0 is not a substitute for one.
+ */
+export function parseValue(display) {
+    const text = display.trim().replace(FOOTNOTE, '').trim();
+    if (text === '' || text === '-')
+        return NOTHING;
+    const annotated = ANNOTATION.exec(text);
+    const annotation = annotated?.[1]?.trim() ?? null;
+    const head = annotated ? text.slice(0, annotated.index).trim() : text;
+    if (head === '') {
+        const ratio = annotation === null ? null : RATIO.exec(annotation);
+        if (ratio)
+            return { ...NOTHING, ratio: Number(ratio[1]) };
+        return { ...NOTHING, annotation };
+    }
+    const number = NUMBER.exec(head);
+    // `measure.fractionValue` is stricter than {@link NUMBER} in one place — it
+    // refuses a division by zero — so a token that matched here can still have no
+    // reading, and that is a code cell rather than a number.
+    const value = number === null ? null : fractionValue(number[1]);
+    if (number === null || value === null)
+        return { ...NOTHING, annotation, code: head };
+    const unit = number[2];
+    return {
+        value,
+        stated: unit === 'mm' ? 'millimeters' : null,
+        degrees: unit === '°',
+        annotation,
+        ratio: null,
+        code: null,
+    };
+}
+/**
+ * One cell as a length in `unit`, or null where it publishes none.
+ *
+ * `measure.asLength` makes both calls — convert-and-warn a cell whose stated
+ * unit disagrees with the family's, refuse an angle in a dimensional column —
+ * because they are the same two calls for every vendor and were a verbatim copy
+ * here and in `vendors/emuge/value.ts` until 2026-09-01. What is Harvey's is
+ * above: that `degrees` is a field of its own rather than a member of
+ * `stated`, and that a parenthesised `(3 mm)` is an annotation on an inch value
+ * and never the value itself.
+ *
+ * The 46 cells this converts are metric-shank tools listed among imperial ones
+ * — real parts somebody can order, which is why they are converted rather than
+ * dropped.
+ */
+export function dimension(display, unit, what, warn = consoleWarn) {
+    const { value, stated, degrees } = parseValue(display);
+    return asLength({ value, stated: degrees ? 'degrees' : stated }, display, unit, what, warn);
+}
+/** One cell as a whole count — a flute or tooth number. Null where blank. */
+export function count(display) {
+    return asCount(parseValue(display));
+}

package/dist/vendors/kennametal/records.d.ts

@@ -15,10 +15,11 @@
  *   Number` are Kennametal's header text — the labels
  *   `conventions.IDENTITY_COLUMNS` took as the convention because this vendor
  *   was first, and which Destiny Tool then did not follow.
- * - **Which column is the grade.** A drill and an end mill carry a carbide
- *   `Grade`; a tap has no carbide grade and carries `Coating`, the surface
- *   treatment, in the record's `grade` field. That is Kennametal's table
- *   shape, not a rule about taps everywhere.
+ * - **Which column is the coating.** `Coating` on every table that publishes
+ *   one, which is every tap table and some of the others. The carbide `Grade`
+ *   a drill and an end mill table also carry reaches no record: it is what the
+ *   tool is made of in Kennametal's own vocabulary, nothing downstream reads
+ *   it, and `substrate` already carries the cutting material as a fact.
  * - **That a tap's unit system is per row.** `Thread System` is a constant tag
  *   column this package appends at scrape time, and a metric and an inch tap
  *   can sit in one family — so a tap's `unit` is read per row where a drill's
@@ -43,6 +44,14 @@ import type { ScrapedRow } from '../../scrape.js';
  */
 export declare const MATERIAL_NUMBER = "Material Number";
 export declare const CATALOG_NUMBER = "ISO Catalog Number";
+/**
+ * The surface-treatment column, on the tables that publish one.
+ *
+ * Every tap table does; a drill or an end mill table may not, which is why the
+ * mappers read it with a `?? ''` rather than through a required column — an
+ * absent coating column is a table that states no coating, not a scrape fault.
+ */
+export declare const COATING = "Coating";
 /**
  * A drill, in the family's native unit system per its `unit` fact.
  *

package/dist/vendors/kennametal/records.js

@@ -15,10 +15,11 @@
  *   Number` are Kennametal's header text — the labels
  *   `conventions.IDENTITY_COLUMNS` took as the convention because this vendor
  *   was first, and which Destiny Tool then did not follow.
- * - **Which column is the grade.** A drill and an end mill carry a carbide
- *   `Grade`; a tap has no carbide grade and carries `Coating`, the surface
- *   treatment, in the record's `grade` field. That is Kennametal's table
- *   shape, not a rule about taps everywhere.
+ * - **Which column is the coating.** `Coating` on every table that publishes
+ *   one, which is every tap table and some of the others. The carbide `Grade`
+ *   a drill and an end mill table also carry reaches no record: it is what the
+ *   tool is made of in Kennametal's own vocabulary, nothing downstream reads
+ *   it, and `substrate` already carries the cutting material as a fact.
  * - **That a tap's unit system is per row.** `Thread System` is a constant tag
  *   column this package appends at scrape time, and a metric and an inch tap
  *   can sit in one family — so a tap's `unit` is read per row where a drill's
@@ -34,10 +35,10 @@
  * nose, `LB` and `assemblyGaugeLength` being `OAL` on a bare tool, and every
  * cutting preset. Those are true of a tool, not of a table.
  */
-import { ScraperConfigError, VendorResponseError } from '../../errors.js';
-import { familyBrand } from '../../family.js';
+import { VendorResponseError } from '../../errors.js';
+import { fact, familyBrand } from '../../family.js';
 import { BRANDS } from '../../identity.js';
-import { toolRecord } from '../../records.js';
+import { toolRecord, UNSPECIFIED, } from '../../records.js';
 import { threadMajorDiameter } from '../../thread.js';
 import { MATERIALS_COLUMN, materialClasses } from './materials.js';
 /**
@@ -46,6 +47,14 @@ import { MATERIALS_COLUMN, materialClasses } from './materials.js';
  */
 export const MATERIAL_NUMBER = 'Material Number';
 export const CATALOG_NUMBER = 'ISO Catalog Number';
+/**
+ * The surface-treatment column, on the tables that publish one.
+ *
+ * Every tap table does; a drill or an end mill table may not, which is why the
+ * mappers read it with a `?? ''` rather than through a required column — an
+ * absent coating column is a table that states no coating, not a scrape fault.
+ */
+export const COATING = 'Coating';
 /**
  * One canonical dimension, or null when this family maps or publishes none.
  *
@@ -79,12 +88,30 @@ function require_(row, columns, canonical, unit, what) {
     }
     return value;
 }
-/** A per-family constant a mapper cannot proceed without. */
-function fact(family, key, value) {
-    if (value === undefined) {
-        throw new ScraperConfigError(family.id, `a ${family.kind} family must state ${key} as a fact`);
-    }
-    return value;
+/**
+ * The workpiece-material groups, and how they were arrived at.
+ *
+ * **The distinction the column cannot make on its own is present versus
+ * blank.** The material groups are not scraped with the variant table: they
+ * come from a second CLI step (`toolpath-scrape materials`) that sweeps the
+ * `workpieceMaterialDetail` facet and writes {@link MATERIALS_COLUMN} into the
+ * CSV. A family that step never ran over has **no such column**, and
+ * `node/csv.parseCsv` fills `''` only for cells under a column that is in the
+ * header — so the cell is `undefined` on an unswept CSV and `''` on a swept
+ * one whose part the vendor rates for nothing.
+ *
+ * Those are different claims and the record now keeps them apart: an
+ * `unspecified` label says this package has no evidence, `[]` says the vendor's
+ * own index has none. All
+ * 129 taps land on the second after a sweep — Kennametal indexes no tap by
+ * workpiece material at all — and reading that as "unconstrained" would put
+ * every tap under every material.
+ */
+function materialGroups(row) {
+    const cell = row[MATERIALS_COLUMN];
+    if (cell === undefined)
+        return { materialGroups: null, materialGroupsSource: UNSPECIFIED };
+    return { materialGroups: materialClasses(cell), materialGroupsSource: 'vendor-stated' };
 }
 /**
  * The `Thread System` tag, refusing anything that is not one of the two.
@@ -129,15 +156,19 @@ export function drillRecord(row, family, columns) {
     const unit = fact(family, 'unit', family.unit);
     const what = row[MATERIAL_NUMBER] ?? '';
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
-        description: row[CATALOG_NUMBER] ?? '',
+        // Kennametal publishes no description column on any table. The catalog
+        // number is already on the record, and repeating it here said nothing —
+        // see `records.ToolRecord.description`.
+        description: '',
         kind: 'drill',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
-        grade: row['Grade'] ?? '',
-        materialGroups: materialClasses(row[MATERIALS_COLUMN]),
+        coating: row[COATING] ?? '',
+        ...materialGroups(row),
         coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         nonFerrous: fact(family, 'nonFerrous', family.nonFerrous),
         geometry: {
@@ -170,19 +201,21 @@ export function tapRecord(row, family, columns) {
     const tdz = row['D1-TDZ'] ?? '';
     const what = row[MATERIAL_NUMBER] ?? '';
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
-        // The designation is part of what a tap *is*, and the catalog number alone
-        // does not carry the size.
-        description: `${row[CATALOG_NUMBER] ?? ''} ${tdz}`,
+        // The one Kennametal table that publishes per-part text: the thread
+        // designation is part of what a tap *is*, and the catalog number does not
+        // carry the size. The catalog number no longer leads it — it is already on
+        // the record, and a description that restates one is not a description.
+        description: tdz,
         kind: 'tap',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
-        // A tap has no carbide grade; the record's grade carries the coating.
-        grade: row['Coating'] ?? '',
-        materialGroups: materialClasses(row[MATERIALS_COLUMN]),
-        coolantThrough: false,
+        coating: row[COATING] ?? '',
+        ...materialGroups(row),
+        coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         geometry: {
             DC: threadMajorDiameter(tdz, system),
             TP: require_(row, columns, 'TP', unit, what),
@@ -212,15 +245,17 @@ export function endmillRecord(row, family, columns) {
     const dc = require_(row, columns, 'DC', unit, what);
     const fluteLength = require_(row, columns, 'LCF', unit, what);
     return toolRecord({
+        brand: familyBrand(family),
         vendor: BRANDS[familyBrand(family)].vendor,
         materialNumber: what,
         catalogNumber: row[CATALOG_NUMBER] ?? '',
-        description: row[CATALOG_NUMBER] ?? '',
+        // No description column here either. See the drill mapper.
+        description: '',
         kind: 'endmill',
         unit,
         substrate: fact(family, 'bmc', family.bmc),
-        grade: row['Grade'] ?? '',
-        materialGroups: materialClasses(row[MATERIALS_COLUMN]),
+        coating: row[COATING] ?? '',
+        ...materialGroups(row),
         coolantThrough: fact(family, 'coolantThrough', family.coolantThrough),
         geometry: {
             DC: dc,

package/dist/vendors/maritool/catalog.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The category tree -> the leaves under it.
+ *
+ * MariTool publishes no sitemap: `/sitemap.xml` answers with a meta-refresh
+ * shell rather than a document, and there is no flat index anywhere on the
+ * site. Walking the category tree is the only way to find out what exists —
+ * see `docs/MARITOOL_CATALOG.md` §2.
+ *
+ * **Nothing in a scrape needs this.** `families/maritool.ts` names all 41 leaf
+ * cPaths in scope, and a scrape fetches exactly those; re-deriving them at
+ * scrape time would put a 199-page crawl in front of every run to rediscover
+ * a list that is already written down. It is here for the maintenance question
+ * that table cannot answer — *has MariTool added or moved a leaf?* — and the
+ * CLI exposes it as `maritool --catalog` for that purpose. It is how the table
+ * was built and how it gets rechecked.
+ *
+ * ## The tree is deeper than it looks
+ *
+ * Two to four levels, and **no root carries products itself**. `Dual Contact
+ * CAT40` (`c23_25_432`) and each of the nine HSK sizes are intermediate nodes
+ * with children, so a walk that stopped at depth 2 would find zero HSK holders
+ * and zero dual-contact parts — 187 of the 529 in scope. That is why this
+ * recurses on the child links rather than reading one level of the sidebar.
+ *
+ * A category page carries its children as links whose cPath extends its own by
+ * exactly one segment, and the sidebar renders unrelated branches beside them,
+ * so the prefix test is what separates a child from a sibling of an ancestor.
+ */
+import type { Fetcher } from '../../fetch.js';
+import { type Warn } from '../../scrape.js';
+/**
+ * The five taper trees this adapter covers.
+ *
+ * MariTool's catalog is larger — `c23` holds twenty more roots, and the store
+ * sells cutting tools besides. These are the trees asked for, and adding one
+ * is a decision rather than a widening of a pattern; see the package's rule on
+ * not adding vendor scope without being asked.
+ *
+ * **There is no CAT30.** MariTool's 30-taper is BT30 and ISO30, confirmed
+ * against the full sidebar rather than against a landing page. ISO30 (`c23_54`)
+ * is absent for a different reason: its three ER parts publish no spec table,
+ * so the family would be a receipt of nothing.
+ */
+export declare const CATEGORY_ROOTS: readonly string[];
+/** One node of the tree, as the walk found it. */
+export interface Category {
+    /** MariTool's own category path, e.g. `23_25_42`. */
+    readonly cPath: string;
+    /** The vendor's own name for it, off the page title. */
+    readonly name: string;
+    /** Child cPaths, sorted. Empty on a leaf. */
+    readonly children: readonly string[];
+    /** What `(of N products)` said, or 0 where the page states no count. */
+    readonly products: number;
+}
+/** The category name a page states, stripped of the store's boilerplate. */
+export declare function categoryName(html: string): string;
+/**
+ * One category page: its children, its name and its own product count.
+ *
+ * A child is a link whose cPath extends this one by exactly one segment. The
+ * page also links every sibling of every ancestor — the sidebar renders the
+ * whole open branch — so taking every `cPath` link would walk the catalog from
+ * any starting point and take the twenty out-of-scope roots with it.
+ */
+export declare function parseCategory(html: string, cPath: string): Category;
+/**
+ * Every category reachable from `roots`, breadth first and paced.
+ *
+ * Sequential and paced by the package's shared politeness delay. The five
+ * roots in scope reach 199 categories, which is a three-minute walk and is run
+ * by hand rather than by a scrape.
+ */
+export declare function discoverCategories(fetcher: Fetcher, roots?: readonly string[], options?: {
+    warn?: Warn;
+    delayMs?: number;
+}): Promise<Category[]>;
+/** The leaves of a walk: the categories that carry products themselves. */
+export declare function leavesOf(categories: readonly Category[]): Category[];
+/** One line per category, for a human reading a `--catalog` run. */
+export declare function describe(category: Category): string;

package/dist/vendors/maritool/catalog.js

@@ -0,0 +1,132 @@
+/**
+ * The category tree -> the leaves under it.
+ *
+ * MariTool publishes no sitemap: `/sitemap.xml` answers with a meta-refresh
+ * shell rather than a document, and there is no flat index anywhere on the
+ * site. Walking the category tree is the only way to find out what exists —
+ * see `docs/MARITOOL_CATALOG.md` §2.
+ *
+ * **Nothing in a scrape needs this.** `families/maritool.ts` names all 41 leaf
+ * cPaths in scope, and a scrape fetches exactly those; re-deriving them at
+ * scrape time would put a 199-page crawl in front of every run to rediscover
+ * a list that is already written down. It is here for the maintenance question
+ * that table cannot answer — *has MariTool added or moved a leaf?* — and the
+ * CLI exposes it as `maritool --catalog` for that purpose. It is how the table
+ * was built and how it gets rechecked.
+ *
+ * ## The tree is deeper than it looks
+ *
+ * Two to four levels, and **no root carries products itself**. `Dual Contact
+ * CAT40` (`c23_25_432`) and each of the nine HSK sizes are intermediate nodes
+ * with children, so a walk that stopped at depth 2 would find zero HSK holders
+ * and zero dual-contact parts — 187 of the 529 in scope. That is why this
+ * recurses on the child links rather than reading one level of the sidebar.
+ *
+ * A category page carries its children as links whose cPath extends its own by
+ * exactly one segment, and the sidebar renders unrelated branches beside them,
+ * so the prefix test is what separates a child from a sibling of an ancestor.
+ */
+import { Parser } from 'htmlparser2';
+import { compare } from '../../order.js';
+import { consoleWarn, pause, REQUEST_DELAY_MS } from '../../scrape.js';
+import { BASE, categoryUrl } from './scrape.js';
+/**
+ * The five taper trees this adapter covers.
+ *
+ * MariTool's catalog is larger — `c23` holds twenty more roots, and the store
+ * sells cutting tools besides. These are the trees asked for, and adding one
+ * is a decision rather than a widening of a pattern; see the package's rule on
+ * not adding vendor scope without being asked.
+ *
+ * **There is no CAT30.** MariTool's 30-taper is BT30 and ISO30, confirmed
+ * against the full sidebar rather than against a landing page. ISO30 (`c23_54`)
+ * is absent for a different reason: its three ER parts publish no spec table,
+ * so the family would be a receipt of nothing.
+ */
+export const CATEGORY_ROOTS = [
+    '23_25', // CAT40
+    '23_24', // CAT50
+    '23_33', // BT30
+    '23_26', // BT40
+    '23_46', // HSK
+];
+/** `.../c23_25_42/index.html` and `index.php?cPath=23_25_42` both give `23_25_42`. */
+const CATEGORY_HREF = /(?:\/c|[?&]cPath=)(\d+(?:_\d+)*)(?:\/index\.html)?(?:[&#]|$)/;
+/** `<title>… Accessories ER Collet Chucks - MariTool</title>` -> the middle. */
+const TITLE = /<title>([^<]*)<\/title>/i;
+/** The vendor's own boilerplate around every category name. */
+const TITLE_NOISE = [/^Tool Holders, Collets and Machine Accessories\s*/i, /\s*-\s*MariTool$/i];
+/** `(of 51 products)`, or 0 — an empty category renders no count at all. */
+const PRODUCT_COUNT = /\(of\s*<b>\s*(\d+)\s*<\/b>\s*products\)/i;
+/** The category name a page states, stripped of the store's boilerplate. */
+export function categoryName(html) {
+    let name = TITLE.exec(html)?.[1] ?? '';
+    for (const noise of TITLE_NOISE)
+        name = name.replace(noise, '');
+    return name.replace(/\s+/g, ' ').trim();
+}
+/**
+ * One category page: its children, its name and its own product count.
+ *
+ * A child is a link whose cPath extends this one by exactly one segment. The
+ * page also links every sibling of every ancestor — the sidebar renders the
+ * whole open branch — so taking every `cPath` link would walk the catalog from
+ * any starting point and take the twenty out-of-scope roots with it.
+ */
+export function parseCategory(html, cPath) {
+    const children = new Set();
+    const parser = new Parser({
+        onopentag: (tag, attribs) => {
+            if (tag !== 'a')
+                return;
+            const found = CATEGORY_HREF.exec(attribs['href'] ?? '')?.[1];
+            if (found === undefined)
+                return;
+            if (found.startsWith(`${cPath}_`) &&
+                found.split('_').length === cPath.split('_').length + 1)
+                children.add(found);
+        },
+    }, { decodeEntities: true });
+    parser.write(html);
+    parser.end();
+    return {
+        cPath,
+        name: categoryName(html),
+        children: [...children].sort(compare),
+        products: Number(PRODUCT_COUNT.exec(html)?.[1] ?? 0),
+    };
+}
+/**
+ * Every category reachable from `roots`, breadth first and paced.
+ *
+ * Sequential and paced by the package's shared politeness delay. The five
+ * roots in scope reach 199 categories, which is a three-minute walk and is run
+ * by hand rather than by a scrape.
+ */
+export async function discoverCategories(fetcher, roots = CATEGORY_ROOTS, options = {}) {
+    const { warn = consoleWarn, delayMs = REQUEST_DELAY_MS } = options;
+    const found = new Map();
+    const queue = [...roots];
+    while (queue.length > 0) {
+        const cPath = queue.shift();
+        if (found.has(cPath))
+            continue;
+        const category = parseCategory(await fetcher.text(categoryUrl(cPath)), cPath);
+        found.set(cPath, category);
+        if (category.children.length === 0 && category.products === 0) {
+            warn(`  WARNING: c${cPath} (${category.name}) holds neither a subcategory nor a product`);
+        }
+        queue.push(...category.children);
+        await pause(delayMs);
+    }
+    return [...found.values()].sort((a, b) => compare(a.cPath, b.cPath));
+}
+/** The leaves of a walk: the categories that carry products themselves. */
+export function leavesOf(categories) {
+    return categories.filter((category) => category.children.length === 0);
+}
+/** One line per category, for a human reading a `--catalog` run. */
+export function describe(category) {
+    const shape = category.children.length > 0 ? `${category.children.length} subcategories` : 'leaf';
+    return `${BASE}/index.php?cPath=${category.cPath}\t${category.products}\t${shape}\t${category.name}`;
+}

package/dist/vendors/maritool/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MariTool — toolholding only, and the one vendor here with no transport to
+ * discover.
+ *
+ * An osCommerce-family storefront: server-rendered HTML, a paced `GET`, and a
+ * roster on the category page with the geometry one request further on. See
+ * `docs/MARITOOL_CATALOG.md`.
+ */
+export * from './catalog.js';
+export * from './scrape.js';

package/dist/vendors/maritool/index.js

@@ -0,0 +1,10 @@
+/**
+ * MariTool — toolholding only, and the one vendor here with no transport to
+ * discover.
+ *
+ * An osCommerce-family storefront: server-rendered HTML, a paced `GET`, and a
+ * roster on the category page with the geometry one request further on. See
+ * `docs/MARITOOL_CATALOG.md`.
+ */
+export * from './catalog.js';
+export * from './scrape.js';