@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/seed/seed-purpose.d.ts

@@ -1,299 +0,0 @@
-/**
- * ── Seed provenance: may a purge delete this row? ───────────────────────────
- *
- * Every document written by `appkit-seed` carries a `seedPurpose`, and it is
- * the ONE declaration of whether a row is real content or clearable test data.
- * The purge reads it; nothing else decides.
- *
- * ## The rule this exists to enforce
- *
- * 🛑 **Content comes from a seed FILE, never from a direct database write.**
- * Not a one-off script, not a console paste, not a `node -e`. A row that exists
- * only in Firestore cannot be reviewed in a diff, cannot be recreated after a
- * purge, and cannot be found by anyone who did not watch it being written —
- * and when it references other rows, nothing updates it when those move.
- *
- * `seedPurpose` makes that rule *checkable*: a document with no `seedPurpose`
- * was not written by the seeder, so the purge will not touch it.
- *
- * ## 🛑 THE DEFAULT IS `test`, AND THE OPPOSITE WAS THIS FILE'S FIRST BUG
- *
- * The first version of this file defaulted every collection to `permanent`,
- * reasoning that the dangerous direction is deleting something unrecoverable.
- * **That reasoning was wrong here, and it made the purge a no-op.**
- *
- * This site has never gone live. There are no real customers, no real orders
- * and no real payouts — every user, store, listing, auction, order, bid and
- * review in the seed was added TO EXERCISE THE PLATFORM. Classifying them
- * `permanent` means "cannot be cleared", which is precisely the opposite of
- * why the field was asked for.
- *
- * So the default is `test`, and `permanent` is the **narrow** exception: the
- * handful of collections that are genuinely content rather than scaffolding.
- *
- * ## 🛑 AND `isTestData` IS NOT DERIVED FROM THIS — that was the second bug
- *
- * The first version wrote `isTestData: true` for every `test` row. That would
- * have **hidden the entire demo catalogue from the public**, because
- * `hidePublicTestData` filters on exactly that field — 70 products, 416
- * categories and every store would have vanished from every public page while
- * the summary line read `created 2513, errors 0`.
- *
- * The two concerns are orthogonal and must stay separate:
- *
- * | Question | Field |
- * |---|---|
- * | May a purge delete this row? | **`seedPurpose`** (here) |
- * | Should the public be able to SEE this row? | **`isTestData`** + `testDataExpiresAt` |
- *
- * A demo product is `test` (clearable) **and visible**. A tester-sandbox
- * cross-store fixture is `test` **and hidden**. Those are different rows with
- * different needs, and one field cannot answer both.
- *
- * `isTestData` therefore stays an explicit per-row opt-in, authored via
- * `testDataExpiresAt()` in `./test-data-ttl.ts`, and this file never writes it.
- *
- * ## What it replaces
- *
- * Measured 2026-10-12, before this file existed: **47** seed data files, of
- * which **one** carried any permanence marker; `isTestData` declared on **5**
- * schemas; and `TEST_DATA_COLLECTIONS` listing **`offers`**, whose schema does
- * not declare the field at all, so that entry could only ever match zero rows.
- * `users`, `orders`, `faqs`, `reviews`, `bids`, `payouts` and `carts` had no
- * marker and no purge path — and users and orders are the two that were named.
- */
-/**
- * Why a seeded row exists — i.e. what a purge is allowed to do with it.
- *
- * 🛑 Not a severity scale. Three different answers to one question: never,
- * on request, and only on an explicit full purge.
- */
-export type SeedPurpose = 
-/**
- * Clearable test data. **The default**, and what almost everything is.
- *
- * Users, stores, listings, auctions, orders, bids, reviews, offers, carts,
- * payouts — everything seeded to exercise a path rather than to be read as
- * content. `appkit-seed purge` removes these and nothing else.
- *
- * 🛑 `test` says nothing about PUBLIC VISIBILITY. A demo product is `test`
- * and fully visible; that is what makes the demo a demo. Hiding a row from
- * the public is `isTestData`, which is a separate decision (see the header).
- */
-"test"
-/**
- * Real content. **A purge must NEVER remove it**, because re-creating it is
- * not a re-seed, it is authoring.
- *
- * The test to apply: *if clearing this means somebody has to WRITE it again
- * rather than re-run a loader, it is permanent.*
- *
- * That is why the **tester checklist cases** are in here and not in some
- * harness tier — they are the real catalogue of issues the testers test
- * against and keep updating, which is authored content that happens to be
- * about testing. Its 1,162 cases are no more disposable than the 85 FAQs.
- */
- | "permanent";
-/**
- * `Record<SeedPurpose, true>`, so a third value is a compile error in every map
- * keyed on the union rather than a silent gap (Root Cause #61).
- */
-export declare const SEED_PURPOSE_VALUES: Record<SeedPurpose, true>;
-export declare const ALL_SEED_PURPOSES: SeedPurpose[];
-export declare function isSeedPurpose(value: unknown): value is SeedPurpose;
-/**
- * 🛑 There is deliberately NO third `fixture` tier.
- *
- * An earlier draft had one, meaning "clearable but only by an explicit full
- * purge", intended for the tester checklist. Once the cases were correctly
- * classified as permanent content it had **nothing in it** — and a union member
- * with no members is the dead-enum-value shape this codebase keeps paying for:
- * a filter chip whose value no row carries returns zero rows forever and reads
- * as a working control (Root Cause #33), and nine section types that exist in a
- * dropdown and have never rendered (F1 #20).
- *
- * Two values answer the question that was actually asked. If a genuine third
- * case appears, add it then — with a row that needs it.
- */
-export declare const PURGEABLE: Record<SeedPurpose, boolean>;
-/**
- * The per-collection default, keyed on `COLLECTION_MAP`'s keys in
- * `appkit/scripts/seed-cli.mjs`.
- *
- * 🛑 Typed `Record<string, SeedPurpose>` rather than a closed union of
- * collection names, and that is a deliberate trade: the collection list lives
- * in a `.mjs` script that cannot be imported for its types, so a closed union
- * here would be a fifth hand-written copy of it — the thing this file exists to
- * stop. `audit-seed-purpose` cross-checks the two sets instead, which catches
- * both a missing entry and a dead one.
- *
- * **Anything absent defaults to `test`**, so a collection added later is
- * clearable rather than quietly permanent. That is the right fail direction on
- * a site with no real data: the cost of clearing something re-seedable is one
- * command, and the cost of being unable to clear it is the state this replaced.
- */
-export declare const SEED_COLLECTION_PURPOSE: Record<string, SeedPurpose>;
-/**
- * Individual rows that differ from their collection's default, by document id.
- *
- * 🛑 This is the "clear all out EXCEPT our admin creds and the original single
- * store" instruction, made declarative. Both collections default to `test` —
- * every persona and every other store is disposable — and exactly two rows are
- * not.
- *
- * ✅ The precedent already existed and this replaces it: `cmdDelete` has
- * carried `PROTECTED_USER_UIDS = new Set(["user-admin-letitrip"])` for a long
- * time, skipping that uid on a wholesale delete. One mechanism is better than a
- * list the purge path happens to know about privately.
- *
- * 🛑 Keyed **`"<collection>:<id>"`**, and the collection half is load-bearing.
- *
- * It was a bare id, and a live read-back caught the consequence: `carts`,
- * `wishlists` and `history` are all keyed on the USER id (CLAUDE.md: "Doc id =
- * userId"), so `"user-admin-letitrip"` matched the admin's **cart** as well as
- * the admin's user row — making a disposable cart permanently unpurgeable.
- * Subtle, silent, and it would have left a stale cart surviving every purge
- * forever.
- *
- * The id half is the DOCUMENT id, which for `users` is the Auth uid (`uid` on
- * the seed row) and for everything else is `id`. `resolveSeedPurpose` checks
- * both, because a seeded user row carries `uid` and no `id`.
- */
-export declare const SEED_ROW_PURPOSE: Record<string, SeedPurpose>;
-/**
- * Collections whose purpose FOLLOWS a referenced row rather than being declared.
- *
- * 🛑 This exists to hold one invariant: **a `permanent` row may not reference a
- * `test` row**, because the purge would leave it behind as a dangling FK that
- * still looks like real config.
- *
- * Measured in `store-extensions-seed-data.ts`: **14** rows reference
- * `store-beyblade-arena` (test) and **9** reference `store-letitrip-official`
- * (permanent). So marking `shippingConfigs` / `analyticsCards` permanent at the
- * COLLECTION level — which the user's list implies and an earlier draft of the
- * plan did — would strand 14 rows pointing at a store the purge deletes.
- *
- * Deriving is better than 23 hand-maintained per-row overrides for the usual
- * reason: a hand-kept mirror drifts the moment a store is added (Root Cause
- * #42), and a derivation is correct for stores that do not exist yet.
- */
-export declare const SEED_PURPOSE_DERIVED_FROM: Record<string, {
-    readonly field: SeedReferenceField;
-    readonly collection: string;
-}>;
-/** A seeded row may override its collection's default inline. */
-export interface WithSeedPurpose {
-    seedPurpose?: SeedPurpose;
-}
-/**
- * The fields `resolveSeedPurpose` reads off a row — all optional, because it is
- * handed rows from 47 differently-shaped collections.
- *
- * 🛑 Declared explicitly rather than as `Record<string, unknown>`, which
- * `audit-unknown-leakage` blocks and which is worse anyway: an index signature
- * accepts ANY field name, so a typo in `SEED_PURPOSE_DERIVED_FROM.field` would
- * read `undefined` and fall through to `test` silently — the exact mistake
- * already made once, where `analyticsCards` was declared to derive from
- * `storeId` and the rows carry `ownerId`.
- *
- * `SeedReferenceField` then constrains that `field` to one of these, so the
- * same typo becomes a compile error.
- */
-export interface SeedRowIdentity extends WithSeedPurpose {
-    /** Document id, on every collection except `users`. */
-    id?: string;
-    /** `users` seed rows carry the Auth uid and no `id`. */
-    uid?: string;
-    storeId?: string;
-    ownerId?: string;
-    userId?: string;
-    sellerId?: string;
-}
-/** The reference fields a derived collection may follow. */
-export type SeedReferenceField = "storeId" | "ownerId" | "userId" | "sellerId";
-/**
- * Resolution order, most specific first:
- *
- *   1. the row's own inline `seedPurpose`
- *   2. a per-row override in `SEED_ROW_PURPOSE`, by `id` or `uid`
- *   3. for a DERIVED collection, the purpose of the row it references
- *   4. the collection default
- *   5. `test`
- *
- * 🛑 Step 3 is what holds the referential invariant. A `shippingConfig` for
- * `store-letitrip-official` resolves `permanent`; one for
- * `store-beyblade-arena` resolves `test` and is purged alongside the store it
- * configures, rather than outliving it.
- */
-export declare function resolveSeedPurpose(collection: string, row?: SeedRowIdentity | null, 
-/**
- * The document id, when the caller has it and the row does not.
- *
- * 🛑 Required by `loadGeneric`, which does `let { id, ...data } = docData`
- * and therefore hands this function a row with **no `id` at all**. Without
- * this parameter the per-row overrides silently did not apply: measured,
- * `store-letitrip-official` loaded as `test` — i.e. the platform's own store
- * would have been purged, which is exactly the row the keep-list exists to
- * protect. `loadUsers` was unaffected because `{ ...u }` keeps `uid`, which
- * is why the admin override worked and the store one did not.
- */
-docId?: string | null): SeedPurpose;
-export interface SeedPurposeFields {
-    seedPurpose: SeedPurpose;
-}
-/**
- * The fields to write for a purpose — exactly one.
- *
- * 🛑 It does **not** touch `isTestData` or `testDataExpiresAt`, and that
- * restraint is the whole correction described in the header: deriving
- * `isTestData` from `test` would have hidden every seeded product, category and
- * store from the public site while reporting a clean load.
- *
- * Kept as a function rather than inlined so there is one place to look when
- * someone asks "what does a purpose actually write?", and so the next field
- * (if one is ever justified) lands in one place.
- */
-export declare function seedPurposeFields(purpose: SeedPurpose): SeedPurposeFields;
-/**
- * Stamp a row for writing. The one function every loader calls, so the CLI and
- * `runSeed` cannot disagree about what a purpose means — Root Cause #75's shape
- * on the seed axis (a rule reachable by copy-paste gets copied, and the copy
- * made before a branch was added never learns about it).
- *
- * Returns a NEW object; the seed arrays are module-level constants re-imported
- * on every CLI invocation and must not be mutated.
- */
-export declare function stampSeedPurpose<T extends WithSeedPurpose>(collection: string, row: T, 
-/** Pass this whenever the caller holds the id and the row does not — see
- *  `resolveSeedPurpose`'s `docId` for why `loadGeneric` must. */
-docId?: string | null): T & SeedPurposeFields;
-/**
- * Mark a whole array as something other than its collection default — the
- * readable way to say "this file is permanent" (or "this file is fixtures")
- * without repeating the field on every row.
- *
- * Sets the row-level override, so it beats the collection default and is
- * visible at the call site.
- */
-export declare function asSeedPurpose<T>(purpose: SeedPurpose, rows: readonly T[]): Array<T & WithSeedPurpose>;
-/**
- * How long a `test` row survives before a purge may take it.
- *
- * 🛑 STOP-GAP, added 2026-10-12 to unbreak the build — NOT a design decision,
- * and whoever owns `seedPurpose` should replace it with the real declaration.
- *
- * This file arrived with `src/seed/index.ts:247` and `src/index.ts:1935` ALREADY
- * re-exporting `SEED_TEST_TTL_DAYS` from here while nothing declared it, so
- * `tsc` failed with TS2305 and appkit did not compile at all — the half-finished
- * public-surface rename of Root Cause #20, where the barrel landed without the
- * definition. (The same commit also carried `sxdexport const` on line 149,
- * i.e. stray keystrokes, which is the likelier reading of what happened here.)
- *
- * Aliased to the EXISTING value rather than given a fresh number: a retention
- * window is a product decision and inventing one would have been worse than the
- * compile error. `TEST_DATA_TTL_DAYS` is 7 and is what `testDataExpiresAt()`
- * already stamps on every test row, so this is behaviour-preserving by
- * construction — and when the two names are reconciled, there is exactly one
- * number to change.
- */
-export { TEST_DATA_TTL_DAYS as SEED_TEST_TTL_DAYS } from "./test-data-ttl";