@pithy-sh/core 0.1.2 → 0.1.3

package/dist/seed/seed.d.ts

@@ -0,0 +1,264 @@
+import type { z } from "zod";
+import type { KvStoreSpec } from "../kv/namespaces";
+import type { SeededRows } from "./seededRows";
+/**
+ * The seed contract: the pure, schema-bound shapes a capability (or the app) contributes to
+ * `pithy seed`. A capability declares its fixtures as {@link SeedSet}s on `Capability.seeds`;
+ * `composeSeeds` merges every capability's sets library-before-app, and the CLI writes them,
+ * idempotently and non-destructively, into the environment named by `--env`.
+ *
+ * Rows and entries are authored as **app-shape values** (the decoded, `z.output` side). The
+ * write-time `schema.encode(row)` in `seedD1Group` is the single Zod validation boundary — a bad
+ * fixture fails there, before any write. Core defines only the types and the pure write/compose
+ * logic; filesystem work (media bytes, UUID write-back) lives in the CLI.
+ */
+/**
+ * An environment name a set may be seeded into (`dev`, `staging`, `production`, or any custom
+ * environment). A set lists the environments it is allowed into on {@link SeedSet.environments};
+ * `production` is only ever seeded when a set lists it explicitly.
+ */
+export type SeedEnv = string;
+/**
+ * One D1 seed group: a batch of app-shape rows for a single table in a single named database.
+ * `database` and `table` match the names a capability declares in its `databases` map; the row
+ * schema is resolved from the composed databases registry at write time (the fixture never
+ * redeclares it). `rows` are `z.output` (app shape) values — re-encoded and validated on write.
+ */
+export interface D1SeedGroup<Table extends z.ZodType = z.ZodType> {
+    /** The named database this table lives in (matches a `databases` key, e.g. "app", "analytics"). */
+    database: string;
+    /** The table name to seed (the un-prefixed logical name used in query code). */
+    table: string;
+    /** The rows to insert, as app-shape (`z.output`) values — encoded + validated at write time. */
+    rows: readonly z.output<Table>[];
+}
+/**
+ * One KV seed entry: an app-shape key/value (and optional metadata) for a store. The values are
+ * the store's input shapes; {@link TypedKv.put} validates each on write.
+ */
+export interface KvSeedEntry<V extends z.ZodType = z.ZodType, K extends z.ZodObject = z.ZodObject, M extends z.ZodType = z.ZodType> {
+    /** The structured key segments, validated by the store's key schema. */
+    key: z.input<K>;
+    /** The value to store, validated by the store's value schema. */
+    value: z.input<V>;
+    /** Optional metadata, validated by the store's metadata schema. */
+    metadata?: z.input<M>;
+}
+/**
+ * One KV seed group: a batch of entries for a single named store within a named namespace.
+ * `namespace` and `store` match the names a capability declares in its `kvNamespaces` map.
+ */
+export interface KvSeedGroup<V extends z.ZodType = z.ZodType, K extends z.ZodObject = z.ZodObject, M extends z.ZodType = z.ZodType> {
+    /** The named KV namespace this store lives in (matches a `kvNamespaces` key). */
+    namespace: string;
+    /** The store name within the namespace to seed. */
+    store: string;
+    /** The entries to write — each validated by the store on put. */
+    entries: readonly KvSeedEntry<V, K, M>[];
+}
+/**
+ * One R2 object to seed: raw bytes (or a string) under a key in a bound bucket. R2 has no schema
+ * layer, so the payload is opaque; the CLI writes it via the bucket manager for the target env.
+ */
+export interface R2SeedItem {
+    /** The R2 binding name in the Worker env this object lives in. */
+    binding: string;
+    /** The object key. */
+    key: string;
+    /** The object bytes, or a string body. */
+    body: Uint8Array | string;
+    /** The object's content type (e.g. "image/png"). */
+    contentType: string;
+    /** Optional custom metadata stored alongside the object. */
+    metadata?: Record<string, string>;
+}
+/**
+ * One media asset to seed into the shared Cloudflare Images or Stream store. Core defines only the
+ * type — the filesystem read (`file`), the upload, and the UUID write-back (`ref`) run in the CLI.
+ *
+ * `once` (the default) uploads on the first run and records the minted UUID in the `ref` sidecar,
+ * so later runs skip the upload and reference the recorded id. `always` re-uploads every run,
+ * scoped by metadata, and never writes a UUID back.
+ */
+export interface MediaSeedItem {
+    /** Which shared asset store to upload to. */
+    store: "images" | "stream";
+    /** Upload policy: `once` (upload + record the UUID) or `always` (re-upload each run). */
+    mode: "once" | "always";
+    /**
+     * Path to the asset bytes. Resolved against the set's {@link SeedSet.baseDir} (the seed module's own
+     * directory, set with `import.meta.dirname`), or the project root when the set declares none. Read by
+     * the CLI. An absolute path is used as-is.
+     */
+    file: string;
+    /**
+     * Path to the JSON sidecar that records the minted UUID (for `once`). Resolved the same way as
+     * {@link MediaSeedItem.file} — against the set's {@link SeedSet.baseDir} or the project root.
+     * Read/written by the CLI. An absolute path is used as-is.
+     */
+    ref: string;
+    /** Optional custom metadata merged with the standard asset metadata block on upload. */
+    metadata?: Record<string, string>;
+    /**
+     * Optional D1 asset row (in `database`.`table`) that references the minted UUID. Only valid with
+     * `mode: "once"`: the row is keyed by the stable, recorded UUID, so an `always` asset — which mints
+     * a fresh UUID every run — cannot own a stable record. The CLI rejects `always` + `record`.
+     */
+    record?: {
+        /** The named database the asset row lives in. */
+        database: string;
+        /** The table the asset row is written to. */
+        table: string;
+        /** The app-shape row — the CLI fills in the minted UUID before writing it. */
+        row: unknown;
+    };
+}
+/**
+ * A transient file a prepared set asks the CLI to write, under the project's gitignored `logs/`.
+ *
+ * The path is not the author's choice: a set names the file, never the directory, so a fixture can never
+ * put a run artifact somewhere committable. The one artifact that exists today is the dev login
+ * (`DEV_LOGIN_PATH`), which holds a live session cookie — hence both halves of that rule.
+ */
+export interface SeedArtifact {
+    /** The file name within the project's `logs/` directory (no directory separators). */
+    file: string;
+    /** The file's contents, written verbatim after the set's rows land. */
+    contents: string;
+}
+/**
+ * What a run gives {@link SeedSet.prepare} so it can compute the fixtures it cannot state statically.
+ *
+ * Deliberately narrow. `secret` is the only I/O the set performs, and it is the reason the hook exists: a
+ * fixture that must
+ * agree with what the running app will verify — a signed cookie, a derived id — needs the same secret the
+ * app reads, and a static row cannot hold one. Everything else is passed in already-read, so a capability
+ * never touches the filesystem: a capability module is bundled into the Worker, and `node:fs` there is a
+ * build error rather than a possibility. For the same reason `seeded` is the composed plan rather than a
+ * database handle — a prepared set answers "does this row exist" from the run, never from a query.
+ */
+export interface SeedPrepareContext {
+    /** The environment being seeded — the same value the set's `environments` allowed. */
+    env: string;
+    /** The project name (the root `pithy.config.ts` `name`), for messages and per-project lookups. */
+    project: string;
+    /**
+     * Where this Worker answers locally — `http://localhost:8807` and the like. `null` outside `dev`, and
+     * `null` in a checkout that was never allocated a port block.
+     *
+     * The one address a fixture cannot write down. A dev port is *allocated*, not configured: a checkout
+     * reserves a block and pins one port per Worker into `.dev.config.json`, so `http://localhost:8787` is
+     * right in the first checkout on a machine and wrong in every other one. A set that has to register a
+     * self-connection had nothing to ask, so it hard-coded that literal and every second checkout addressed
+     * the first one's Worker. This is the string the run was actually allocated — the same one `pithy dev`
+     * exports to this Worker's siblings as `<STEM>_ORIGIN`, read back verbatim and never recomposed from
+     * the port.
+     *
+     * **An address, not an identity.** It says where to reach this Worker, on this machine, now. Anything a
+     * later check compares against a stored value — an issuer, an audience, a signing scope — must not be
+     * built from it: the same project answers on a different port in every checkout and a different origin
+     * in every environment, so a row minted against one is unverifiable against the next. Reachability
+     * moves. Identity must not.
+     *
+     * **`null` is an answer, never a guess.** A plain clone that has never run `pithy dev`, a Worker added
+     * after the block was pinned, or any environment but `dev` — a deployed environment's address is
+     * declared rather than allocated, and `pithy env` is what answers it. An invented origin would be
+     * indistinguishable from a real one, so a set that cannot work without one refuses and says so.
+     */
+    origin: string | null;
+    /**
+     * Read one of this environment's secrets by name, or `undefined` when it is not set. Local dev resolves
+     * every secret from `.dev.vars`, so this answers there; a deployed environment's secrets are not on the
+     * operator's disk, and a set that needs one must therefore be `dev`-only.
+     */
+    secret: (name: string) => Promise<string | undefined>;
+    /**
+     * The developer's machine-local preferences for this project, read from the Pithy config directory
+     * (`~/.config/pithy/<project>/dev.json`, or `%APPDATA%\pithy\<project>\dev.json` on Windows), parsed but
+     * unvalidated — `undefined` when the file is absent or unreadable. It is a per-machine opt-in, outside
+     * the repo, so two developers on one checkout can differ and neither has to commit anything. The set
+     * validates the shape it expects.
+     */
+    preferences: unknown;
+    /**
+     * The rows this run declares for one `database`.`table`, from every composed set — this one included, and
+     * every other capability's and the app's. It is how a fixture that must reference a row it does not own
+     * (a session for a seeded user) finds that row without hard-coding a roster or opening D1. Statically
+     * declared rows only; see {@link SeededRows}.
+     */
+    seeded: SeededRows;
+}
+/**
+ * What {@link SeedSet.prepare} contributes: more of the same groups a static set declares, plus any
+ * transient artifacts. The groups are appended to the set's static ones and written through the identical
+ * validated path; the artifacts are written afterwards, so a file never claims a row that failed to land.
+ */
+export interface SeedPreparation {
+    /** D1 row groups computed for this run. */
+    d1?: readonly D1SeedGroup[];
+    /** KV entry groups computed for this run. */
+    kv?: readonly KvSeedGroup[];
+    /** Transient files to write under the project's `logs/` once the rows are in. */
+    artifacts?: readonly SeedArtifact[];
+}
+/**
+ * One named, ordered batch of fixtures a capability contributes to `pithy seed`. Sets are composed
+ * library-before-app by `order` (like migrations) and each declares the environments it may be
+ * seeded into — the first layer of the env-safety model. `production` is seeded only when a set
+ * lists it explicitly.
+ */
+export interface SeedSet {
+    /** Stable, unique-per-capability name. Namespaced by capability name when composed. */
+    name: string;
+    /** Sort order across capabilities (libraries low, app high). Ties break on the namespaced key. */
+    order: number;
+    /** The environments this set may be seeded into. A set is skipped for any env it does not list. */
+    environments: readonly SeedEnv[];
+    /**
+     * The directory the set's relative media paths (`MediaSeedItem.file` / `.ref`) resolve against —
+     * the seed module's own directory, so fixture bytes sit next to the module that declares them.
+     * Author it as `baseDir: import.meta.dirname`. When omitted, media paths resolve against the
+     * project root instead (a legacy fallback, rarely what you want once a set ships media).
+     */
+    baseDir?: string;
+    /** Whether this is an example/demo set — composed only when the project enables `includeExamples`. */
+    example?: boolean;
+    /** D1 row groups. */
+    d1?: readonly D1SeedGroup[];
+    /** KV entry groups. */
+    kv?: readonly KvSeedGroup[];
+    /** R2 objects. */
+    r2?: readonly R2SeedItem[];
+    /** Media assets (Images/Stream), uploaded by the CLI. */
+    media?: readonly MediaSeedItem[];
+    /**
+     * Late-bound fixtures: run once per Worker, just before this set's rows are written, to compute what a
+     * static literal cannot hold. Its groups are appended to the static ones and go through the same
+     * `schema.encode` validation; its artifacts are written after.
+     *
+     * A dry run never calls it. A plan touches no backend and needs no credentials, so a prepared set
+     * reports nothing there rather than reading a secret to describe work it is not going to do.
+     */
+    prepare?: (context: SeedPrepareContext) => Promise<SeedPreparation>;
+}
+/**
+ * Author a seed set. A pass-through that anchors the {@link SeedSet} type at the author site (the
+ * peer of `defineCapability`); the real invariant checks (namespacing, ordering, env filtering)
+ * run in `composeSeeds`, and the write-time validation runs in `seedD1Group`. Use {@link d1SeedGroup}
+ * and {@link kvSeedGroup} to bind rows/entries to their schemas at compile time.
+ */
+export declare function defineSeed(input: SeedSet): SeedSet;
+/**
+ * Author a typed D1 seed group. `schema` is a compile-time carrier only — it binds `rows` to the
+ * table's `z.output` (app) shape so a mistyped fixture fails to compile; it is not stored on the
+ * group (the writer resolves the schema from the composed databases registry). Mirrors
+ * `createDatabase`'s type-only `map` argument.
+ */
+export declare function d1SeedGroup<Table extends z.ZodType>(database: string, table: string, schema: Table, rows: readonly z.output<Table>[]): D1SeedGroup<Table>;
+/**
+ * Author a typed KV seed group. `spec` is a compile-time carrier only — it binds each entry's
+ * `key`/`value`/`metadata` to the store's schemas so a mistyped fixture fails to compile; it is not
+ * stored on the group (the writer supplies the live store).
+ */
+export declare function kvSeedGroup<V extends z.ZodType, K extends z.ZodObject, M extends z.ZodType>(namespace: string, store: string, spec: KvStoreSpec<V, K, M>, entries: readonly KvSeedEntry<V, K, M>[]): KvSeedGroup<V, K, M>;
+//# sourceMappingURL=seed.d.ts.map

package/dist/seed/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../src/seed/seed.ts"],"names":[],"mappings":"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"}

package/dist/seed/seed.js

@@ -0,0 +1,37 @@
+//#region src/seed/seed.ts
+/**
+* Author a seed set. A pass-through that anchors the {@link SeedSet} type at the author site (the
+* peer of `defineCapability`); the real invariant checks (namespacing, ordering, env filtering)
+* run in `composeSeeds`, and the write-time validation runs in `seedD1Group`. Use {@link d1SeedGroup}
+* and {@link kvSeedGroup} to bind rows/entries to their schemas at compile time.
+*/
+function defineSeed(input) {
+	return input;
+}
+/**
+* Author a typed D1 seed group. `schema` is a compile-time carrier only — it binds `rows` to the
+* table's `z.output` (app) shape so a mistyped fixture fails to compile; it is not stored on the
+* group (the writer resolves the schema from the composed databases registry). Mirrors
+* `createDatabase`'s type-only `map` argument.
+*/
+function d1SeedGroup(database, table, schema, rows) {
+	return {
+		database,
+		table,
+		rows
+	};
+}
+/**
+* Author a typed KV seed group. `spec` is a compile-time carrier only — it binds each entry's
+* `key`/`value`/`metadata` to the store's schemas so a mistyped fixture fails to compile; it is not
+* stored on the group (the writer supplies the live store).
+*/
+function kvSeedGroup(namespace, store, spec, entries) {
+	return {
+		namespace,
+		store,
+		entries
+	};
+}
+//#endregion
+export { d1SeedGroup, defineSeed, kvSeedGroup };

package/dist/seed/seededRows.d.ts

@@ -0,0 +1,26 @@
+import type { SeedSet } from "./seed";
+/**
+ * The run's own inventory: which rows a seed run declares, per table, before it writes any of them.
+ *
+ * It exists for the one class of fixture that has to agree with a row another set owns — a dev session for a
+ * seeded user, say. Such a set cannot hard-code the roster (the users may be an adopter's, not a library's)
+ * and must not read the database (a capability module is bundled into the Worker, where D1 is a binding it
+ * has no business opening during a seed). So the CLI hands it the composed registry it already holds in
+ * memory. It is a *plan*, not a query: no I/O, no credentials, and the same answer in a dry run.
+ */
+/**
+ * Read the app-shape rows this run declares for one `database`.`table`, across every composed set. Empty
+ * when nothing seeds that table. Values are `unknown` on purpose — they cross into a capability that does
+ * not own the table, so the reader validates them with the schema it expects.
+ */
+export type SeededRows = (database: string, table: string) => readonly unknown[];
+/**
+ * Index every set's statically declared D1 rows into one lookup, in composed order.
+ *
+ * Statically declared, and only that. A prepared set's rows do not exist until its own `prepare` runs, and a
+ * media record's row has no id until the CLI mints one — reporting either would promise a row that may never
+ * land. A set that needs to be *seen* must therefore declare its rows as literals, which every user fixture
+ * does.
+ */
+export declare function collectSeededRows(sets: readonly SeedSet[]): SeededRows;
+//# sourceMappingURL=seededRows.d.ts.map

package/dist/seed/seededRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seededRows.d.ts","sourceRoot":"","sources":["../../src/seed/seededRows.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,OAAO,EAAE,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,UAAU,CAUtE"}

package/dist/seed/seededRows.js

@@ -0,0 +1,20 @@
+//#region src/seed/seededRows.ts
+/**
+* Index every set's statically declared D1 rows into one lookup, in composed order.
+*
+* Statically declared, and only that. A prepared set's rows do not exist until its own `prepare` runs, and a
+* media record's row has no id until the CLI mints one — reporting either would promise a row that may never
+* land. A set that needs to be *seen* must therefore declare its rows as literals, which every user fixture
+* does.
+*/
+function collectSeededRows(sets) {
+	const index = /* @__PURE__ */ new Map();
+	for (const set of sets) for (const group of set.d1 ?? []) {
+		const tables = index.get(group.database) ?? /* @__PURE__ */ new Map();
+		index.set(group.database, tables);
+		tables.set(group.table, [...tables.get(group.table) ?? [], ...group.rows]);
+	}
+	return (database, table) => index.get(database)?.get(table) ?? [];
+}
+//#endregion
+export { collectSeededRows };

package/dist/seed/writeD1.d.ts

@@ -0,0 +1,43 @@
+import type { Kysely } from "kysely";
+import { z } from "zod";
+import type { D1SeedGroup } from "./seed";
+/** Options for {@link seedD1Group}. */
+export interface SeedD1Options {
+    /** Validate + count only; perform no write. */
+    dryRun?: boolean;
+}
+/** The outcome of seeding one D1 group. */
+export interface SeedD1Result {
+    /** The table seeded. */
+    table: string;
+    /** The number of rows validated (and, unless `dryRun`, written). */
+    rows: number;
+}
+/**
+ * Seed one D1 group, idempotently and non-destructively.
+ *
+ * Every row is `schema.encode(row)`d first — this IS the write-time Zod validation boundary. An
+ * invalid fixture throws a `ValidationError` (a `ZodError` mapped via `fromZodError`) **before any
+ * write for this group**, so a partial group never lands. The insert is `INSERT OR IGNORE`
+ * (`orIgnore`), so re-running seeds writes no duplicate rows and never overwrites existing data. The
+ * table's row schema is resolved by the caller from the composed databases registry and passed in —
+ * the fixture never redeclares it.
+ *
+ * **The group is written in chunks sized against D1's bound-parameter ceiling, and that belongs here
+ * rather than at any call site.** An insert binds one parameter per column per row, so a group's real
+ * limit is `100 / columns` — around fifteen rows for a seven-column table — and it moves with the
+ * table. Every fixture the kit ships is 2–6 rows, which is why the single unbatched insert survived: it
+ * only breaks on a fixture big enough to do the job fixtures exist for, and `DEFAULT_PAGE_SIZE` is 25,
+ * so anything proving a paged list crosses the limit by construction. `pithy-sh/dashboard` hit it on
+ * its first realistic seed and worked around it by splitting fourteen tables into twenty-nine groups by
+ * hand. A rule that every adopter re-derives after a confusing `too many SQL variables` is a rule in
+ * the wrong place; the size is derived from the row's own column count, never guessed.
+ *
+ * Chunks are written in sequence, and a group is deliberately not atomic across them. `INSERT OR
+ * IGNORE` makes a partial run safe to re-run — the landed chunks collide and are ignored — which is the
+ * same property that makes seeding re-runnable at all.
+ *
+ * `dryRun` validates and counts but writes nothing.
+ */
+export declare function seedD1Group(db: Kysely<any>, group: D1SeedGroup, schema: z.ZodType, options?: SeedD1Options): Promise<SeedD1Result>;
+//# sourceMappingURL=writeD1.d.ts.map

package/dist/seed/writeD1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeD1.d.ts","sourceRoot":"","sources":["../../src/seed/writeD1.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;CACd;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,WAAW,CAE/B,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,EACf,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA4BvB"}

package/dist/seed/writeD1.js

@@ -0,0 +1,73 @@
+import { fromZodError } from "../error/pithyError.js";
+import { chunkRowsByBoundParameters } from "../data/boundParameters.js";
+import { z } from "zod";
+//#region src/seed/writeD1.ts
+/**
+* How many parameters one encoded row will bind.
+*
+* The **union** of every row's keys, not the first row's count: Kysely builds one column list for a
+* multi-row insert from every object it was given, so a group whose rows differ binds against the wider
+* list. Over-counting only makes the chunks smaller, which is always safe; under-counting is the bug.
+*
+* A row that is not an object cannot be an insert record at all, and Kysely will say so far more
+* usefully than an arithmetic helper would — so it is counted as one parameter and left to fail there.
+*/
+function columnsPerRow(encoded) {
+	const columns = /* @__PURE__ */ new Set();
+	for (const row of encoded) {
+		if (typeof row !== "object" || row === null) return 1;
+		for (const key of Object.keys(row)) columns.add(key);
+	}
+	return Math.max(columns.size, 1);
+}
+/**
+* Seed one D1 group, idempotently and non-destructively.
+*
+* Every row is `schema.encode(row)`d first — this IS the write-time Zod validation boundary. An
+* invalid fixture throws a `ValidationError` (a `ZodError` mapped via `fromZodError`) **before any
+* write for this group**, so a partial group never lands. The insert is `INSERT OR IGNORE`
+* (`orIgnore`), so re-running seeds writes no duplicate rows and never overwrites existing data. The
+* table's row schema is resolved by the caller from the composed databases registry and passed in —
+* the fixture never redeclares it.
+*
+* **The group is written in chunks sized against D1's bound-parameter ceiling, and that belongs here
+* rather than at any call site.** An insert binds one parameter per column per row, so a group's real
+* limit is `100 / columns` — around fifteen rows for a seven-column table — and it moves with the
+* table. Every fixture the kit ships is 2–6 rows, which is why the single unbatched insert survived: it
+* only breaks on a fixture big enough to do the job fixtures exist for, and `DEFAULT_PAGE_SIZE` is 25,
+* so anything proving a paged list crosses the limit by construction. `pithy-sh/dashboard` hit it on
+* its first realistic seed and worked around it by splitting fourteen tables into twenty-nine groups by
+* hand. A rule that every adopter re-derives after a confusing `too many SQL variables` is a rule in
+* the wrong place; the size is derived from the row's own column count, never guessed.
+*
+* Chunks are written in sequence, and a group is deliberately not atomic across them. `INSERT OR
+* IGNORE` makes a partial run safe to re-run — the landed chunks collide and are ignored — which is the
+* same property that makes seeding re-runnable at all.
+*
+* `dryRun` validates and counts but writes nothing.
+*/
+async function seedD1Group(db, group, schema, options = {}) {
+	const encoded = group.rows.map((row, index) => {
+		try {
+			return schema.encode(row);
+		} catch (error) {
+			if (error instanceof z.ZodError) throw fromZodError(error, {
+				message: `Invalid seed row for table "${group.table}".`,
+				action: "Fix the fixture so every field matches the table schema.",
+				detail: `Row ${index} for database "${group.database}" table "${group.table}" failed encode validation.`
+			});
+			throw error;
+		}
+	});
+	if (options.dryRun || encoded.length === 0) return {
+		table: group.table,
+		rows: encoded.length
+	};
+	for (const chunk of chunkRowsByBoundParameters(encoded, columnsPerRow(encoded))) await db.insertInto(group.table).orIgnore().values(chunk).execute();
+	return {
+		table: group.table,
+		rows: encoded.length
+	};
+}
+//#endregion
+export { seedD1Group };

package/dist/seed/writeKv.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { TypedKv } from "../kv/kv";
+import type { KvStoreSpec } from "../kv/namespaces";
+import type { KvSeedGroup } from "./seed";
+/** Options for {@link seedKvGroup}. */
+export interface SeedKvOptions {
+    /** Count only; perform no write. */
+    dryRun?: boolean;
+}
+/** The outcome of seeding one KV group. */
+export interface SeedKvResult {
+    /** The store seeded. */
+    store: string;
+    /** The number of entries validated (and, unless `dryRun`, considered for writing). */
+    entries: number;
+}
+/**
+ * Seed one KV group, idempotently and non-destructively.
+ *
+ * **Every entry is validated against the store spec before any write** — mirroring `seedD1Group`, an
+ * invalid fixture throws a `ValidationError` (a `ZodError` mapped via `fromZodError`) before the first
+ * `put`, so a partial group never lands. The write itself is non-destructive: an existing key is left
+ * untouched (KV's analog of D1's `INSERT OR IGNORE`), so re-running a seed never overwrites real data
+ * that happens to share a key, and re-establishes only the keys it owns.
+ *
+ * `dryRun` validates and counts but writes nothing.
+ */
+export declare function seedKvGroup<V extends z.ZodType, K extends z.ZodObject, M extends z.ZodType>(store: TypedKv<V, K, M>, group: KvSeedGroup<V, K, M>, spec: KvStoreSpec<V, K, M>, options?: SeedKvOptions): Promise<SeedKvResult>;
+//# sourceMappingURL=writeKv.d.ts.map

package/dist/seed/writeKv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeKv.d.ts","sourceRoot":"","sources":["../../src/seed/writeKv.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;CACjB;AA4CD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,EAC/F,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACvB,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC3B,IAAI,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAiBvB"}

package/dist/seed/writeKv.js

@@ -0,0 +1,63 @@
+import { fromZodError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/seed/writeKv.ts
+/**
+* Validate one entry's key, value, and (present) metadata against the store spec, mapping a
+* `ZodError` into an actionable `ValidationError`. Pure — never writes.
+*/
+function validateEntry(spec, group, entry, index) {
+	try {
+		spec.key.parse(entry.key);
+		spec.value.parse(entry.value);
+		if (entry.metadata !== void 0 && spec.metadata !== void 0) spec.metadata.parse(entry.metadata);
+	} catch (error) {
+		if (error instanceof z.ZodError) throw fromZodError(error, {
+			message: `Invalid seed entry for KV store "${group.store}".`,
+			action: "Fix the fixture so every entry matches the store's key, value, and metadata schemas.",
+			detail: `Entry ${index} for namespace "${group.namespace}" store "${group.store}" failed validation.`
+		});
+		throw error;
+	}
+}
+/**
+* Whether `key` already holds a value — used to make the write non-destructive. A value that exists but
+* no longer parses against the store schema (foreign or older data at a colliding key) still counts as
+* present: existence, not readability, is what the "never overwrite" guarantee turns on.
+*/
+async function keyExists(store, key) {
+	try {
+		return await store.get(key) !== null;
+	} catch {
+		return true;
+	}
+}
+/**
+* Seed one KV group, idempotently and non-destructively.
+*
+* **Every entry is validated against the store spec before any write** — mirroring `seedD1Group`, an
+* invalid fixture throws a `ValidationError` (a `ZodError` mapped via `fromZodError`) before the first
+* `put`, so a partial group never lands. The write itself is non-destructive: an existing key is left
+* untouched (KV's analog of D1's `INSERT OR IGNORE`), so re-running a seed never overwrites real data
+* that happens to share a key, and re-establishes only the keys it owns.
+*
+* `dryRun` validates and counts but writes nothing.
+*/
+async function seedKvGroup(store, group, spec, options = {}) {
+	group.entries.forEach((entry, index) => {
+		validateEntry(spec, group, entry, index);
+	});
+	if (options.dryRun) return {
+		store: group.store,
+		entries: group.entries.length
+	};
+	for (const entry of group.entries) {
+		if (await keyExists(store, entry.key)) continue;
+		await store.put(entry.key, entry.value, entry.metadata !== void 0 ? { metadata: entry.metadata } : {});
+	}
+	return {
+		store: group.store,
+		entries: group.entries.length
+	};
+}
+//#endregion
+export { seedKvGroup };

package/dist/semver/semver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Semantic versions: one parse, one format, one order.
+ *
+ * Anything that has to *rank* versions needs semver §11.4 — order a release feed, decide what sits
+ * between installed and latest, sort a prerelease against the stable it precedes. §11.4 is short and
+ * every clause of it is a trap: numeric identifiers compare numerically and alphanumerics compare
+ * lexically, a numeric identifier ranks *below* an alphanumeric one, a longer identifier set wins when
+ * every shared identifier is equal, and a stable outranks every prerelease of the same core. Each of
+ * those is one line to get wrong, and getting one wrong shows up as a feed in the wrong order rather
+ * than as an error.
+ *
+ * So it lives here once. The kit's update notifier uses it and ignores the prerelease field, which is
+ * the narrowness it wants rather than a second implementation.
+ *
+ * **The parse is a split, not a string.** A version held as one string compares as text, and text puts
+ * `1.10.0` below `1.9.0`. Split into numbers, the core comparison is three integer comparisons — and
+ * for an adopter storing versions in SQLite, three integer columns are a row-value predicate
+ * (`(major, minor, patch) > (?, ?, ?)`) that the database orders correctly on its own. SQL cannot
+ * express prerelease precedence in that predicate, so a query built that way over-selects a stable
+ * against a prerelease of the same core and {@link compareSemver} settles it in app code.
+ */
+import { z } from "zod";
+export declare const Semver: z.ZodObject<{
+    major: z.ZodNumber;
+    minor: z.ZodNumber;
+    patch: z.ZodNumber;
+    prerelease: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Semver = z.output<typeof Semver>;
+/** How far behind a version is, in each place. */
+export declare const SemverGap: z.ZodObject<{
+    major: z.ZodNumber;
+    minor: z.ZodNumber;
+    patch: z.ZodNumber;
+}, z.core.$strip>;
+export type SemverGap = z.output<typeof SemverGap>;
+/** Parse a version string into its parts. Returns null for anything that is not a version. */
+export declare function parseSemver(value: string): Semver | null;
+/** Render a parsed version back to its canonical string. */
+export declare function formatSemver(version: Semver): string;
+/**
+ * Compare two versions by semver precedence. Negative when `a` precedes `b`. Suitable as an
+ * `Array.prototype.sort` comparator, so it accepts the nulls {@link parseSemver} returns — an
+ * unparseable version sorts below every real one rather than throwing mid-sort.
+ */
+export declare function compareSemver(a: Semver | null, b: Semver | null): number;
+/**
+ * How far `installed` is behind `latest`, per place.
+ *
+ * Each place counts only what accrued while the places above it stayed put, which is what makes the
+ * number mean something: `1.2.3` against `1.6.1` is four minors and one patch behind, not four minors
+ * and *negative two* patches. Somebody running something newer than we know about is ahead, not behind,
+ * so the gap floors at zero rather than going negative.
+ *
+ * **A zero gap is not a claim of being current.** Two versions with the same core sit zero places apart
+ * whatever their prereleases say, so `1.2.3-rc.1` against `1.2.3` measures zero even though it precedes
+ * it. That is the shape being honest about its limits rather than a bug to paper over: counting places
+ * cannot express a prerelease, {@link compareSemver} is what ranks them, and inventing a phantom patch
+ * here would put a number on screen that no release actually carries.
+ */
+export declare function semverGap(installed: Semver, latest: Semver): SemverGap;
+//# sourceMappingURL=semver.d.ts.map

package/dist/semver/semver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../../src/semver/semver.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,MAAM;;;;;iBAchB,CAAC;AACJ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC;AAE7C,kDAAkD;AAClD,eAAO,MAAM,SAAS;;;;iBAQnB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpD;AAmCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAUxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAMtE"}