@mohasinac/appkit 4.45.0 → 4.47.0

package/dist/utils/id-generators.d.ts

@@ -118,6 +118,36 @@ export interface GenerateOfferIdInput {
 }
 export declare function generateOfferId(input: GenerateOfferIdInput): string;
 export declare function idExists(getExistingId: () => Promise<unknown>): Promise<boolean>;
+/**
+ * Find the first id a `checkExists` probe says is free, trying
+ * `generateId(0)`, `generateId(1)`, … up to `maxAttempts`.
+ *
+ * 🛑 **The loop starts at 0, and it used to start at 1.** That one-character
+ * difference made the first candidate unreachable, because its only caller
+ * passes:
+ *
+ *     (count) => (count === 0 ? baseSlug : `${baseSlug}-${count}`)
+ *
+ * so `count === 0` — the BARE slug, which is obviously what the author
+ * intended as the first choice — was dead code. Every product created through
+ * the UI got a gratuitous suffix: the first-ever Dragoon G listing became
+ * `product-dragoon-g-1`, not `product-dragoon-g`.
+ *
+ * Verified by simulating the real helper against the real closure: three
+ * creations yielded `-1`, `-2`, `-3` and never the bare slug.
+ *
+ * It stayed invisible because all 70 production products come from the seed,
+ * which hand-writes clean ids and never calls this — so the catalogue looks
+ * right and only a UI-created listing shows the defect. Same shape as Root
+ * Cause #101: a path exercised by no fixture.
+ *
+ * 🛑 A product id is a URL and a `categorySlugs` reference, and the slug is
+ * immutable after creation by convention, so this is not cosmetic — a listing
+ * created today keeps the wrong URL forever.
+ *
+ * `maxAttempts` still bounds the ATTEMPTS, so the loop runs `0..maxAttempts`
+ * and the random-suffix fallback is unchanged.
+ */
 export declare function generateUniqueId(generateId: (count: number) => string, checkExists: (id: string) => Promise<boolean>, maxAttempts?: number): Promise<string>;
 export declare function generateBarcodeFromId(id: string): string;
 export declare function generateQRCodeData(id: string, baseUrl: string): string;

package/dist/utils/id-generators.js

@@ -171,8 +171,38 @@ export async function idExists(getExistingId) {
         return false;
     }
 }
+/**
+ * Find the first id a `checkExists` probe says is free, trying
+ * `generateId(0)`, `generateId(1)`, … up to `maxAttempts`.
+ *
+ * 🛑 **The loop starts at 0, and it used to start at 1.** That one-character
+ * difference made the first candidate unreachable, because its only caller
+ * passes:
+ *
+ *     (count) => (count === 0 ? baseSlug : `${baseSlug}-${count}`)
+ *
+ * so `count === 0` — the BARE slug, which is obviously what the author
+ * intended as the first choice — was dead code. Every product created through
+ * the UI got a gratuitous suffix: the first-ever Dragoon G listing became
+ * `product-dragoon-g-1`, not `product-dragoon-g`.
+ *
+ * Verified by simulating the real helper against the real closure: three
+ * creations yielded `-1`, `-2`, `-3` and never the bare slug.
+ *
+ * It stayed invisible because all 70 production products come from the seed,
+ * which hand-writes clean ids and never calls this — so the catalogue looks
+ * right and only a UI-created listing shows the defect. Same shape as Root
+ * Cause #101: a path exercised by no fixture.
+ *
+ * 🛑 A product id is a URL and a `categorySlugs` reference, and the slug is
+ * immutable after creation by convention, so this is not cosmetic — a listing
+ * created today keeps the wrong URL forever.
+ *
+ * `maxAttempts` still bounds the ATTEMPTS, so the loop runs `0..maxAttempts`
+ * and the random-suffix fallback is unchanged.
+ */
 export async function generateUniqueId(generateId, checkExists, maxAttempts = 100) {
-    for (let count = 1; count <= maxAttempts; count++) {
+    for (let count = 0; count <= maxAttempts; count++) {
         const id = generateId(count);
         if (!(await checkExists(id)))
             return id;

package/dist/utils/search-txt-builders.js

@@ -29,6 +29,7 @@
  */
 import { buildSearchTxt } from "./search-txt.js";
 import { aliasVariantsForName } from "../_internal/shared/search/alias-variants.js";
+import { partAliasTokens } from "../_internal/shared/search/part-aliases.js";
 import { physicalLocationTokens } from "./physical-location.js";
 const stripHtml = (s) => (s ?? "").replace(/<[^>]+>/g, " ");
 /** products — title, description, brand, taxonomy, condition, card/grading, specs. */
@@ -46,6 +47,27 @@ export function buildProductSearchTxt(p) {
         p.card?.cardNumber,
         p.grading?.service,
         p.specifications?.map((s) => `${s.name} ${s.value}`),
+        /*
+         * D2 Fix 3 — the PART CODE ⇄ NAME bridge, so "rubber flat" finds a listing
+         * titled "Storm Pegasus 105RF" and `RF` finds one titled "… Rubber Flat".
+         *
+         * Firestore cannot fuzzy-match, but nothing stops us indexing MORE tokens
+         * per document — which is the whole mechanism, and it costs nothing at
+         * query time because `searchTxt` is already `array-contains`-indexed.
+         *
+         * 🛑 Fed the TITLE and the specs only, not `description`. A 300-word body
+         * mentioning a dozen parts would add a dozen aliases and push real tokens
+         * off the 600 cap — the same reasoning the misspelling generator records
+         * for itself, and the cap TRUNCATES SILENTLY.
+         *
+         * Emitted BEFORE the misspelling variants: a glossary alias is evidence
+         * from the corpus, a generated misspelling is a guess, so the guess is what
+         * should be dropped first if anything is.
+         */
+        partAliasTokens([
+            p.title ?? "",
+            ...(p.specifications ?? []).map((sp) => `${sp.name} ${sp.value}`),
+        ].join(" ")),
         /*
          * The warehouse location — C4, and this one line is what makes the hard
          * direction work.

package/dist/utils/search-txt.d.ts

@@ -28,6 +28,28 @@
  *   a `searchTxt` for a person's name IS that name, re-encoded. Encrypted fields
  *   stay searchable only through their HMAC blind index (exact match).
  */
+/**
+ * Ceiling on tokens per document. Firestore allows 40k index entries per doc and
+ * each array element costs one per index containing the field, so a long body
+ * left unbounded is a real limit to hit.
+ */
+/**
+ * The field every MIGRATED collection stores its tokens in.
+ *
+ * 🛑 ONE shared constant because `searchTxt` is a CROSS-COLLECTION convention,
+ * not a per-feature field: 12 collections carry it (products, categories,
+ * stores, blogPosts, events, faqs, reviews, coupons, offers, orders,
+ * scammerProfiles, supportTickets) and the name is identical in all of them by
+ * design.
+ *
+ * `field-names.ts` declares `SEARCH_TXT: "searchTxt"` FOUR separate times —
+ * once each in the product, order, FAQ and category blocks — which is the very
+ * duplication `audit-registry-constants` exists to stop, one level up. A module
+ * that queries SIX collections cannot honestly borrow any single feature's
+ * copy: `PRODUCT_FIELDS.SEARCH_TXT` naming the field on a `faqs` query is a
+ * true string and a false statement.
+ */
+export declare const SEARCH_TXT_FIELD = "searchTxt";
 export interface SearchTxtOptions {
     /**
      * Emit prefixes for these sources. Use for short, high-signal text (title,

package/dist/utils/search-txt.js

@@ -37,6 +37,23 @@ const MIN_PREFIX_LENGTH = 1;
  * each array element costs one per index containing the field, so a long body
  * left unbounded is a real limit to hit.
  */
+/**
+ * The field every MIGRATED collection stores its tokens in.
+ *
+ * 🛑 ONE shared constant because `searchTxt` is a CROSS-COLLECTION convention,
+ * not a per-feature field: 12 collections carry it (products, categories,
+ * stores, blogPosts, events, faqs, reviews, coupons, offers, orders,
+ * scammerProfiles, supportTickets) and the name is identical in all of them by
+ * design.
+ *
+ * `field-names.ts` declares `SEARCH_TXT: "searchTxt"` FOUR separate times —
+ * once each in the product, order, FAQ and category blocks — which is the very
+ * duplication `audit-registry-constants` exists to stop, one level up. A module
+ * that queries SIX collections cannot honestly borrow any single feature's
+ * copy: `PRODUCT_FIELDS.SEARCH_TXT` naming the field on a `faqs` query is a
+ * true string and a false statement.
+ */
+export const SEARCH_TXT_FIELD = "searchTxt";
 const MAX_TOKENS = 600;
 /** Words longer than this contribute whole-word only — no prefix expansion. */
 const LONG_WORD_LIMIT = 24;

package/dist/values/success-messages.d.ts

@@ -216,10 +216,6 @@ export declare const SUCCESS_MESSAGES: {
         readonly ROOM_CREATED: "Chat opened";
         readonly ROOM_DELETED: "Chat deleted";
     };
-    readonly COPILOT: {
-        readonly RESPONSE_OK: "Response generated";
-        readonly FEEDBACK_SAVED: "Feedback saved";
-    };
 };
 export declare const INFO_MESSAGES: {
     readonly EMAIL: {

package/dist/values/success-messages.js

@@ -245,11 +245,6 @@ export const SUCCESS_MESSAGES = {
         ROOM_CREATED: "Chat opened",
         ROOM_DELETED: "Chat deleted",
     },
-    // AI Copilot
-    COPILOT: {
-        RESPONSE_OK: "Response generated",
-        FEEDBACK_SAVED: "Feedback saved",
-    },
 };
 export const INFO_MESSAGES = {
     EMAIL: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.45.0",
+  "version": "4.47.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/scripts/seed-cli.mjs

@@ -56,12 +56,19 @@ const BIN_ACTION_MAP = {
   "appkit-seed-status": "status",
 };
 const ACTION = BIN_ACTION_MAP[binName] ?? POSITIONAL[0];
-if (!["load", "delete", "status"].includes(ACTION)) {
+if (!["load", "delete", "status", "purge"].includes(ACTION)) {
   console.error("usage:");
-  console.error("  appkit-seed <load|delete|status> [flags]");
+  console.error("  appkit-seed <load|delete|status|purge> [flags]");
   console.error("  appkit-seed-add     [flags]   # alias for `appkit-seed load`");
   console.error("  appkit-seed-remove  [flags]   # alias for `appkit-seed delete`");
   console.error("");
+  console.error("  purge   delete every document whose seedPurpose is \"test\", and NOTHING else.");
+  console.error("          Unlike `delete`, which empties whole collections, this keeps real");
+  console.error("          content (faqs, categories, taxCodes, productFeatures, blogPosts,");
+  console.error("          carousels, homepageSections, siteSettings, the tester checklist) and");
+  console.error("          keeps the two keep-list rows: the admin account and store-letitrip-official.");
+  console.error("          Organic rows carry no seedPurpose at all and are unreachable by it.");
+  console.error("");
   console.error("flags: --collections a,b   --dry-run   --yes   --verbose   --service-account <path>");
   process.exit(2);
 }
@@ -196,6 +203,7 @@ const {
   wishlistsSeedData, historySeedData,
   groupedListingsSeedData,
   scammersSeedData, productFeaturesSeedData, taxCodesSeedData,
+  partGlossarySeedData, modelCompositionSeedData,
   testerChecklistSeedData, testerResponsesSeedData,
   supportTicketsSeedData, catalogueSeedData,
   shipmentsSeedData, shipmentLotsSeedData, shipmentItemsSeedData,
@@ -211,6 +219,8 @@ const {
   GROUPED_LISTINGS_COLLECTION, SCAMMER_COLLECTION,
   WISHLIST_COLLECTION, HISTORY_COLLECTION, PRODUCT_FEATURES_COLLECTION,
   TAX_CODES_COLLECTION,
+  PART_GLOSSARY_COLLECTION,
+  MODEL_COMPOSITION_COLLECTION,
   TESTER_CHECKLIST_ITEM_COLLECTION,
   TESTER_CHECKLIST_RESPONSE_COLLECTION,
   // PII field/index constants (plain data, still in the main barrel — the
@@ -297,6 +307,9 @@ const COLLECTION_MAP = {
   scammerProfiles: SCAMMER_COLLECTION,
   productFeatures: PRODUCT_FEATURES_COLLECTION,
   taxCodes: TAX_CODES_COLLECTION,
+  // E4/D12 — extracted from the local corpus, generated into the seed.
+  partGlossary: PART_GLOSSARY_COLLECTION,
+  modelComposition: MODEL_COMPOSITION_COLLECTION,
   testerChecklistItems: TESTER_CHECKLIST_ITEM_COLLECTION,
   /*
    * Tester submissions. DERIVED tier in the tester's own map (wiped at setup so
@@ -311,6 +324,109 @@ const COLLECTION_MAP = {
   testerChecklistResponses: TESTER_CHECKLIST_RESPONSE_COLLECTION,
 };
 
+/*
+ * B6 — stamp `gstRate` + `hsnCode` onto every seeded product.
+ *
+ * 🛑 WITHOUT THIS, EVERY SEEDED PRODUCT IS TAXED AT ZERO, and the Tax row can
+ * never render no matter what the GSTIN says.
+ *
+ * The resolution order C0c settled lives in `ProductRepository.deriveTaxonomy`
+ * — product rate, else the CATEGORY's via `taxCodeId`, else a warned floor —
+ * and it runs on a repository write. **The seed writes through
+ * `set(..., { merge: true })` and never touches the repository**, so no seeded
+ * row has ever carried a rate: measured 2026-10-12, `gstRate` was absent on
+ * all 70 live products. At checkout `sumGroupGst` reads `product.gstRate`
+ * directly with a `?? 0`, so the whole catalogue would have computed GST = 0
+ * with a valid GSTIN and `gstSettings.enabled: true`.
+ *
+ * That is the same class as Root Cause #101 (a schema that strips a field plus
+ * a read-side backfill equals a field no query can see) — here it is a
+ * write-side derivation the seed path does not run.
+ *
+ * 🛑 This is NOT a second implementation of the resolution. The product seed
+ * already hand-writes the FULL `categorySlugs` chain, so there is no walk to
+ * re-derive: take the chain, find the first element whose category declares a
+ * `taxCodeId`, and read the rate off the `taxCodes` seed. Nearest-first, which
+ * is the order `resolveCategoryDefaults` uses, so a more specific category
+ * still wins.
+ *
+ * 🛑 An explicit rate on a product WINS and is never overwritten — including
+ * `gstRate: 0`, which is a deliberate exemption and not an absence
+ * (`ProductDocument.gstRate`'s own JSDoc: "undefined and 0 MEAN DIFFERENT
+ * THINGS"). The test is `== null`, never falsy.
+ *
+ * 🛑 And it REFUSES rather than defaulting. A product whose chain resolves no
+ * tax code throws at load time: C0c defines reaching the floor as a triage
+ * signal, so a silent 5% here would hide exactly what it is meant to surface —
+ * and a wrong rate on a real invoice is worse than a failed load.
+ */
+function withDerivedCategoryFields(products) {
+  const catById = new Map((categoriesSeedData || []).map((c) => [String(c.id), c]));
+  const taxById = new Map((taxCodesSeedData || []).map((t) => [String(t.id), t]));
+  const unresolved = [];
+  const out = products.map((p) => {
+    // 🛑 Must NOT early-exit on tax alone now that authenticity rides along —
+    // a product with a hand-written rate would silently keep no authenticity.
+    if (p.gstRate != null && p.hsnCode && p.authenticity) return p;
+    const chain = Array.isArray(p.categorySlugs) && p.categorySlugs.length
+      ? p.categorySlugs
+      : (p.category ? [p.category] : []);
+    let code = null;
+    for (const id of chain) {
+      const c = catById.get(String(id));
+      const t = c?.productDefaults?.taxCodeId;
+      if (t) { code = t; break; }
+    }
+    const tax = code ? taxById.get(String(code)) : null;
+    if (!tax) { unresolved.push(`${p.id} (leaf ${chain[0] ?? "none"})`); return p; }
+
+    /*
+     * 🛑 AUTHENTICITY, the same gap one field over — and it was making a HERO
+     * CLAIM false.
+     *
+     * `productDefaults.defaultAuthenticity` is declared on 122 categories and
+     * `authenticity` was absent on **all 71 live products**, because it derives
+     * on a repository write and the seed does not make one. The homepage
+     * authenticity slide says "the seller has to pick one before it can go
+     * live" — which was untrue in two ways at once: the write schema has it
+     * `.optional()`, and not one product carried a value.
+     *
+     * `unverified` is the floor, never `original`: `ProductAuthenticity`'s own
+     * docstring says that without it "an honest seller who does not know would
+     * have to pick 'original', and silence would be indistinguishable from a
+     * genuine claim." The platform must not make an authenticity claim nobody
+     * checked.
+     *
+     * An explicit product value always wins, so the 6 categories that declare
+     * `original` still reach their products.
+     */
+    let authenticity = null;
+    for (const id of chain) {
+      const c = catById.get(String(id));
+      const a = c?.productDefaults?.defaultAuthenticity;
+      if (a) { authenticity = a; break; }
+    }
+
+    return {
+      ...p,
+      gstRate: p.gstRate != null ? p.gstRate : tax.gstRate,
+      // An exempt code has no HSN, and `hsnCode: ""` would read as a declared
+      // empty code rather than as an inapplicable one.
+      ...(p.hsnCode || !tax.hsnCode ? {} : { hsnCode: tax.hsnCode }),
+      ...(p.authenticity || !authenticity ? {} : { authenticity }),
+    };
+  });
+  if (unresolved.length) {
+    const detail = unresolved.slice(0, 10).join(", ");
+    throw new Error(
+      `seed: ${unresolved.length} product(s) resolve NO taxCodeId from their category chain, ` +
+        "so they would be taxed at zero. Give the category a taxCodeId " +
+        `(the roots carry a floor - see ROOT_TAX_DEFAULTS): ${detail}`,
+    );
+  }
+  return out;
+}
+
 const SEED_DATA_MAP = {
   users: usersSeedData,
   /*
@@ -336,7 +452,7 @@ const SEED_DATA_MAP = {
   // standalone brands collection/seed exists anymore.
   categories: categoriesSeedData,
   stores: storesSeedData,
-  products: [
+  products: withDerivedCategoryFields([
     ...(productsStandardSeedData || []), ...(productsAuctionsSeedData || []), ...(productsPreordersSeedData || []),
     ...(productsPrizeDrawsSeedData || []), ...(productsClassifiedsSeedData || []), ...(productsDigitalCodesSeedData || []), ...(productsLiveItemsSeedData || []),
     // art + stickers were written, exported from the seed barrel, and then never
@@ -344,7 +460,7 @@ const SEED_DATA_MAP = {
     // /stickers were permanently empty, and listingType=art|stickers returned 0.
     // Root Cause #58's family one layer down: added everywhere except the runner.
     ...(productsArtSeedData || []), ...(productsStickersSeedData || []),
-  ],
+  ]),
   orders: ordersSeedData,
   reviews: reviewsSeedData,
   bids: bidsSeedData,
@@ -383,6 +499,8 @@ const SEED_DATA_MAP = {
   scammerProfiles: scammersSeedData,
   productFeatures: productFeaturesSeedData,
   taxCodes: taxCodesSeedData,
+  partGlossary: partGlossarySeedData,
+  modelComposition: modelCompositionSeedData,
   testerChecklistItems: testerChecklistSeedData,
   testerChecklistResponses: testerResponsesSeedData,
 };
@@ -603,7 +721,7 @@ async function loadUsers(seed, stats) {
        * hashed from plaintext and the encryption must not see a hashed value,
        * so nothing may be added to `docData` after that pair runs.
        */
-      const plain = stripUndefined(stampSeedPurpose("users", { ...u }, LOAD_STARTED_AT));
+      const plain = stripUndefined(stampSeedPurpose("users", { ...u }));
       let docData = {
         ...encryptPiiFields(plain, [...USER_PII_FIELDS]),
         ...piiIndicesFor(plain, USER_PII_INDEX_MAP),
@@ -635,7 +753,7 @@ async function loadSubcollection(seed, parentColl, parentKey, subColl, idKey, pi
        * conflating the two would make a parent's classification silently
        * govern children it knows nothing about.
        */
-      const stamped = stripUndefined(stampSeedPurpose(subColl, data, LOAD_STARTED_AT));
+      const stamped = stripUndefined(stampSeedPurpose(subColl, data));
       const payload = piiFields ? encryptPiiFields(stamped, [...piiFields]) : stamped;
       await docRef.set(payload, { merge: true });
       stats.created++;
@@ -661,11 +779,11 @@ async function loadOneDocPerUser(seed, coll, stats) {
        */
       await db.collection(coll).doc(id).set(
         stripUndefined(
-          stampSeedPurpose(
-            coll,
-            { userId, items: items ?? [], updatedAt: updatedAt ?? new Date() },
-            LOAD_STARTED_AT,
-          ),
+          stampSeedPurpose(coll, {
+            userId,
+            items: items ?? [],
+            updatedAt: updatedAt ?? new Date(),
+          }),
         ),
         { merge: false },
       );
@@ -709,7 +827,14 @@ async function loadGeneric(colName, seed, firestoreCollection, stats) {
        * a heuristic, and `users`/`orders` are reachable by it for the first
        * time.
        */
-      data: encryptSeedPii(colName, stripUndefined(stampSeedPurpose(colName, data, LOAD_STARTED_AT))),
+      /*
+       * 🛑 `docId` is passed EXPLICITLY because this loader destructures `id`
+       * out (`let { id, ...data } = docData`), so the row it hands over has no
+       * id for the per-row overrides to match on. Measured without it:
+       * `store-letitrip-official` loaded as `test` — the platform's own store,
+       * which is one of exactly two rows the keep-list exists to protect.
+       */
+      data: encryptSeedPii(colName, stripUndefined(stampSeedPurpose(colName, data, docId))),
     });
   }
   /*
@@ -846,7 +971,10 @@ async function cmdLoad() {
           try {
             const { id, ownerType, ownerId, ...data } = d;
             if (!id || !ownerType || !ownerId) { stats.errors++; continue; }
-            const payload = encryptPiiFields(stripUndefined({ ownerType, ownerId, ...data }), [...ADDRESS_PII_FIELDS]);
+            const payload = encryptPiiFields(
+              stripUndefined(stampSeedPurpose("addresses", { ownerType, ownerId, ...data }, id)),
+              [...ADDRESS_PII_FIELDS],
+            );
             await db.collection("addresses").doc(id).set(payload, { merge: true });
             stats.created++;
           } catch (err) { console.error(`    ✗ ${err.message}`); stats.errors++; }
@@ -860,8 +988,17 @@ async function cmdLoad() {
           try {
             const { id, storeSlug, ...data } = d;
             if (!id || !storeSlug) { stats.errors++; continue; }
+            /*
+             * Stamped under the SEED KEY `storeAddresses`, not the target
+             * collection `addresses`. Both resolve `test`, so nothing differs
+             * today — but the purpose table is keyed on the seed key, and
+             * stamping under the write target would make the two disagree the
+             * day one of them changes.
+             */
             const payload = encryptPiiFields(
-              stripUndefined({ ownerType: "store", ownerId: storeSlug, ...data }),
+              stripUndefined(
+                stampSeedPurpose("storeAddresses", { ownerType: "store", ownerId: storeSlug, ...data }, id),
+              ),
               [...ADDRESS_PII_FIELDS],
             );
             await db.collection("addresses").doc(id).set(payload, { merge: true });
@@ -875,7 +1012,10 @@ async function cmdLoad() {
             const { userId, couponId, ...data } = d;
             if (!userId || !couponId) { stats.errors++; continue; }
             await db.collection(USER_COLLECTION).doc(userId).collection("couponUsage").doc(couponId)
-              .set(stripUndefined({ couponId, ...data }), { merge: true });
+              .set(
+                stripUndefined(stampSeedPurpose("couponUsage", { couponId, ...data }, couponId)),
+                { merge: true },
+              );
             stats.created++;
           } catch (err) { console.error(`    ✗ ${err.message}`); stats.errors++; }
         }
@@ -886,7 +1026,8 @@ async function cmdLoad() {
       } else if (colName === "siteSettings") {
         const settings = seed[0];
         if (settings) {
-          await db.collection(SITE_SETTINGS_COLLECTION).doc("global").set(stripUndefined(settings), { merge: true });
+          await db.collection(SITE_SETTINGS_COLLECTION).doc("global").set(
+          stripUndefined(stampSeedPurpose("siteSettings", settings, "global")), { merge: true });
           stats.created++;
         }
       } else {
@@ -982,11 +1123,146 @@ async function cmdDryRun(intendedAction) {
 
 // ---------------------------------------------------------------------------
 // Main
+/**
+ * `appkit-seed purge` — delete every `seedPurpose: "test"` document and NOTHING
+ * else.
+ *
+ * ## Why this is not `delete`
+ *
+ * `delete` empties whole COLLECTIONS. That is the right tool for a full reset
+ * and the wrong one for "clear the test data": it would take the 85 authored
+ * FAQs, the 416-node taxonomy every product's `categorySlugs` chain points
+ * into, the real HSN tax codes, the 1,337 tester cases and the AES-encrypted
+ * site credentials with it.
+ *
+ * This is a QUERY over a declaration — `where("seedPurpose","==","test")` —
+ * which gives four properties no heuristic can:
+ *
+ *   1. **A row the seeder never wrote is unreachable.** Organic documents (a
+ *      real buyer's cart, a runtime notification, a real signup) carry no
+ *      `seedPurpose` at all, so an equality on it cannot match them. Measured
+ *      live: 64 of 84 users are organic. That is the single most important
+ *      safety property here, and it comes from the field's ABSENCE rather than
+ *      from a list someone has to maintain.
+ *   2. **The keep-list is data, not code.** `store-letitrip-official` and
+ *      `user-admin-letitrip` resolve `permanent`, so the same query skips them.
+ *      This replaces `cmdDelete`'s private `PROTECTED_USER_UIDS` set.
+ *   3. **No composite index.** A single-field equality is served by Firestore's
+ *      automatic index, so this adds nothing to `firestore.indexes.json` — the
+ *      gap that left `priceIndex` queryless.
+ *   4. **The cascade is mostly automatic.** Orders, bids, reviews, offers,
+ *      carts, payouts and notifications are all `test`, so a purged product's
+ *      dependents go in the same pass rather than needing a reference walk.
+ *
+ * 🛑 **Auth is a SECOND delete and `delete`/`purge` are the only places that
+ * know it.** A Firestore user row and its Firebase Auth record are two objects;
+ * removing the row and leaving the login is the worst of the three outcomes,
+ * because the account then looks absent and can still authenticate.
+ *
+ * 🛑 **What it deliberately does NOT do**: delete organic rows that reference a
+ * purged one. An organic notification pointing at a purged test order becomes a
+ * dangling reference — and it is a real person's record, so it is REPORTED
+ * rather than removed. Guessing in the destructive direction on someone's own
+ * data is not a trade this command gets to make.
+ */
+async function cmdPurge() {
+  const targets = collectionsToProcess;
+
+  /* Subcollections are not reachable by a top-level query, so they are walked
+   * explicitly. `couponUsage` lives at `users/{uid}/couponUsage`. */
+  const SUBCOLLECTIONS = [{ key: "couponUsage", parent: USER_COLLECTION, name: "couponUsage" }];
+
+  const plan = [];
+  for (const colName of targets) {
+    const path = COLLECTION_MAP[colName];
+    if (!path) continue;
+    const sub = SUBCOLLECTIONS.find((s) => s.key === colName);
+    try {
+      if (sub) {
+        /* A collection-group query reaches every parent at once. */
+        const snap = await db.collectionGroup(sub.name).where("seedPurpose", "==", "test").get();
+        if (snap.size > 0) plan.push({ colName, docs: snap.docs, isSub: true });
+      } else {
+        const snap = await db.collection(path).where("seedPurpose", "==", "test").get();
+        if (snap.size > 0) plan.push({ colName, docs: snap.docs, isSub: false });
+      }
+    } catch (err) {
+      console.error(`✗ ${colName}: ${err.message}`);
+    }
+  }
+
+  const total = plan.reduce((n, p) => n + p.docs.length, 0);
+  console.log(`\n${"collection".padEnd(26)} ${"purge".padStart(6)}`);
+  console.log("─".repeat(36));
+  for (const p of plan) {
+    console.log(`  ${p.colName.padEnd(24)} ${String(p.docs.length).padStart(6)}`);
+  }
+  console.log("─".repeat(36));
+  console.log(`  ${"TOTAL".padEnd(24)} ${String(total).padStart(6)}\n`);
+
+  if (total === 0) {
+    console.log("Nothing to purge — no document carries seedPurpose \"test\".");
+    return;
+  }
+
+  if (DRY_RUN) {
+    console.log("--dry-run — nothing was deleted.");
+    return;
+  }
+
+  if (
+    !(await confirm(
+      `Delete ${total} test document(s) in project '${process.env.FIREBASE_ADMIN_PROJECT_ID}'? Permanent content and organic rows are untouched.`,
+    ))
+  ) {
+    console.log("Aborted.");
+    process.exit(0);
+  }
+
+  const stats = { deleted: 0, auth: 0, errors: 0 };
+  for (const p of plan) {
+    /*
+     * 🛑 `users` first deletes the AUTH record, then the Firestore row — in that
+     * order, because the reverse can leave an authenticating account whose
+     * profile is gone, and this loop is the only thing that knows both exist.
+     */
+    if (p.colName === "users") {
+      for (const d of p.docs) {
+        try {
+          await auth.deleteUser(d.id);
+          stats.auth++;
+        } catch (e) {
+          if (e?.code !== "auth/user-not-found") console.error(`    auth ${d.id}: ${e.message}`);
+        }
+      }
+    }
+    for (let i = 0; i < p.docs.length; i += 450) {
+      const chunk = p.docs.slice(i, i + 450);
+      const batch = db.batch();
+      for (const d of chunk) batch.delete(d.ref);
+      try {
+        await batch.commit();
+        stats.deleted += chunk.length;
+        if (VERBOSE) for (const d of chunk) console.log(`    - ${p.colName}/${d.id}`);
+      } catch (err) {
+        console.error(`✗ ${p.colName}: ${err.message}`);
+        stats.errors++;
+      }
+    }
+  }
+
+  console.log(
+    `\n${stats.errors === 0 ? "✓" : "✗"} Purge complete — deleted ${stats.deleted}, auth records ${stats.auth}, errors ${stats.errors}`,
+  );
+  if (stats.errors > 0) process.exit(1);
+}
+
 // ---------------------------------------------------------------------------
 try {
   if (ACTION === "status") await cmdStatus();
   else if (ACTION === "load") await cmdLoad();
   else if (ACTION === "delete") await cmdDelete();
+  else if (ACTION === "purge") await cmdPurge();
   process.exit(0);
 } catch (err) {
   console.error("✗ Fatal:", err.message);