@pithy-sh/core 0.1.1 → 0.1.3

package/dist/schema/describedness.js

@@ -0,0 +1,180 @@
+import { InternalError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/schema/describedness.ts
+/** The kind tag Zod puts on a schema's definition. */
+function kindOf(schema) {
+	return schema.def.type;
+}
+/**
+* Kinds with no schema inside them. **Listed, so that anything not listed is a hole rather than a
+* leaf** — that is the whole difference between a walk that can report and one that quietly cannot.
+*/
+const LEAVES = /* @__PURE__ */ new Set([
+	"string",
+	"number",
+	"int",
+	"bigint",
+	"boolean",
+	"date",
+	"symbol",
+	"undefined",
+	"null",
+	"void",
+	"any",
+	"unknown",
+	"never",
+	"nan",
+	"literal",
+	"enum",
+	"file",
+	"template_literal",
+	"custom",
+	"transform",
+	"function",
+	"promise",
+	"lazy"
+]);
+/**
+* Wrappers that describe **the same documented thing** as what they wrap.
+*
+* `TenantFilter.optional().describe("…")` and `TenantFilter.describe("…").optional()` are one described
+* field written two ways, and Zod's `.description` sits on whichever came last. A walk that demanded a
+* description at both depths would report a field that is documented, which is how a gate gets deleted
+* rather than obeyed — so a description is carried *inward* by {@link collectMissing} and looked for
+* *outward* by {@link describedInChain}, and both directions are asserted.
+*
+* An `array` is deliberately not on this list: describing a list says nothing about the shape of its
+* elements, and an undescribed object inside an array is the gap this walk was deepened to find.
+*/
+const TRANSPARENT = /* @__PURE__ */ new Set([
+	"optional",
+	"nullable",
+	"default",
+	"prefault",
+	"readonly",
+	"catch",
+	"nonoptional"
+]);
+/**
+* The children of one schema, by kind. **Throws for a kind this walk has never been taught** — a
+* walker whose unknown case is silently empty cannot report the thing it exists to report.
+*
+* A `pipe` is stepped through; a **codec** is not. This gate reads the schema tree, so wrapping an
+* object in a guard — `refusesVanishingKey`, and anything else that pipes into a schema — would turn
+* an export it checks into an export it silently skips, and losing coverage as a side effect of adding
+* a guard is the wrong direction. A codec is the §Zod exemption spelled as a type rather than as an
+* accident: `z.codec` builds a `ZodCodec`, so the exemption names codec helpers and nothing else.
+* Measured in #326 — stepping through codecs too reports seven fields whose union sides carry no
+* description, every one of them a `SQLiteDate` or a `sqliteJson`.
+*/
+function childSchemas(schema, path) {
+	const def = schema.def;
+	switch (def.type) {
+		case "object": return Object.values(schema.shape);
+		case "array": return [def.element];
+		case "optional":
+		case "nullable":
+		case "default":
+		case "prefault":
+		case "readonly":
+		case "catch":
+		case "nonoptional":
+		case "success": return [def.innerType];
+		case "union": return def.options ?? [];
+		case "intersection": return [def.left, def.right];
+		case "tuple": return [...def.items ?? [], ...def.rest ? [def.rest] : []];
+		case "record":
+		case "map": return [def.keyType, def.valueType].filter(Boolean);
+		case "set": return [def.valueType];
+		case "pipe":
+			if (schema instanceof z.ZodCodec) return [];
+			return [schema.in, schema.out];
+		default:
+			if (LEAVES.has(def.type)) return [];
+			throw new InternalError({
+				message: "A schema kind this walk has never been taught was reached.",
+				action: `Add "${def.type}" to the switch in @pithy-sh/core/src/schema/describedness, or to its LEAVES.`,
+				detail: `${path}: unknown Zod kind "${def.type}". A kind silently treated as a leaf is a schema nothing is holding to CLAUDE.md §Zod.`
+			});
+	}
+}
+/**
+* Whether a description sits anywhere in a field's transparent-wrapper chain.
+*
+* `.describe("…").optional()` puts it on the inner type and `.optional().describe("…")` puts it on the
+* wrapper. Both are one described field. Only {@link TRANSPARENT} wrappers are followed — an `array`
+* or a `pipe` describes something other than what it holds.
+*/
+function describedInChain(schema) {
+	let current = schema;
+	const seen = /* @__PURE__ */ new Set();
+	while (current && !seen.has(current)) {
+		if (current.description) return true;
+		if (!TRANSPARENT.has(kindOf(current))) return false;
+		seen.add(current);
+		current = current.def?.innerType;
+	}
+	return false;
+}
+/**
+* Record any object/enum/union missing a `.describe()` — on the schema itself or on any of its
+* fields — following every container Zod has. Codec-helper primitives are exempt (CLAUDE.md §Zod) and
+* are not objects/enums/unions, so they are skipped.
+*
+* `described` carries a transparent wrapper's own description inward; see {@link TRANSPARENT}.
+*/
+function collectMissing(schema, path, walk, seen, described = false) {
+	if (seen.has(schema)) return;
+	seen.add(schema);
+	const kind = kindOf(schema);
+	const documented = described || describedInChain(schema);
+	if (kind === "object") {
+		if (!documented) walk.missing.push(`${path} — object has no .describe()`);
+		for (const [key, field] of Object.entries(schema.shape)) {
+			const fieldSchema = field;
+			walk.fields += 1;
+			if (!describedInChain(fieldSchema)) walk.missing.push(`${path}.${key} — field has no .describe()`);
+			collectMissing(fieldSchema, `${path}.${key}`, walk, seen);
+		}
+		return;
+	}
+	if ((kind === "union" || kind === "enum") && !documented) walk.missing.push(`${path} — enum/union has no .describe()`);
+	const inherited = TRANSPARENT.has(kind) && documented;
+	for (const [index, child] of childSchemas(schema, path).entries()) collectMissing(child, `${path}[${kind}:${index}]`, walk, seen, inherited);
+}
+/** One schema, walked. The entry point a unit test reaches for. */
+function undescribed(schema, path = "schema") {
+	const walk = {
+		missing: [],
+		fields: 0
+	};
+	collectMissing(schema, path, walk, /* @__PURE__ */ new Set());
+	return walk;
+}
+/**
+* Every exported Zod schema in a package, walked.
+*
+* Takes the result of `import.meta.glob([...], { eager: true })`. The counts come back with the
+* findings **because a sweep that found nothing and a sweep that looked at nothing are the same green
+* run otherwise** — the caller pins all three against literals of its own.
+*/
+function undescribedExports(modules) {
+	const walk = {
+		missing: [],
+		fields: 0
+	};
+	const seen = /* @__PURE__ */ new Set();
+	let schemas = 0;
+	for (const [file, mod] of Object.entries(modules)) for (const [name, value] of Object.entries(mod)) {
+		if (!(value instanceof z.ZodType)) continue;
+		schemas += 1;
+		collectMissing(value, `${file}:${name}`, walk, seen);
+	}
+	return {
+		...walk,
+		modules: Object.keys(modules).length,
+		schemas
+	};
+}
+//#endregion
+export { childSchemas, collectMissing, describedInChain, undescribed, undescribedExports };

package/dist/seed/compose.d.ts

@@ -0,0 +1,41 @@
+import type { Capability } from "../capability/capability";
+import type { SeedSet } from "./seed";
+/** Maximum per-set `order`, derived from the prefix width so the two never drift. */
+export declare const MAX_SEED_ORDER: number;
+/** Options controlling how `composeSeeds` filters and resolves the registry. */
+export interface ComposeSeedsOptions {
+    /** The environment being seeded. A set is included only if its `environments` lists this value. */
+    env: string;
+    /** Whether `example` sets are composed in (the project's `seed.includeExamples`; default off). */
+    includeExamples: boolean;
+}
+/** One capability's seed set, resolved into a stably-keyed, ready-to-run entry. */
+export interface ResolvedSeedSet {
+    /** The namespaced, order-prefixed key: `NNNN_<capability>_<name>` — the stable sort/identity key. */
+    key: string;
+    /** The capability that contributed this set (the namespace). */
+    capability: string;
+    /** The original set. */
+    set: SeedSet;
+}
+/** The result of composing every capability's seed sets for one environment. */
+export interface ComposedSeeds {
+    /** The runnable sets, ordered library-before-app (`order`, then the namespaced key). */
+    sets: ResolvedSeedSet[];
+    /**
+     * The namespaced keys of sets present in the registry but not allowed in the requested env (their
+     * `environments` did not list it). Surfaced so the CLI can refuse a set explicitly targeted for a
+     * disallowed env, rather than silently doing nothing.
+     */
+    skippedByEnv: string[];
+}
+/**
+ * Merge every capability's `seeds` into one ordered registry for `env`, mirroring the migration
+ * composer. Each set's key is `NNNN_<capability>_<name>` (NNNN = zero-padded `order`), so the sort
+ * is dependency-correct (libraries before app) and stable across releases. `example` sets are
+ * dropped unless `includeExamples`; sets whose `environments` does not list `env` are dropped from
+ * the runnable list but reported in `skippedByEnv` (the env-allowlist safety layer). A set name used
+ * twice within one capability throws an `InternalError` attributed to that capability.
+ */
+export declare function composeSeeds(capabilities: readonly Capability[], options: ComposeSeedsOptions): ComposedSeeds;
+//# sourceMappingURL=compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/seed/compose.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKtC,qFAAqF;AACrF,eAAO,MAAM,cAAc,QAAyB,CAAC;AAErD,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,mGAAmG;IACnG,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,qGAAqG;IACrG,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAWD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAiC7G"}

package/dist/seed/compose.js

@@ -0,0 +1,51 @@
+import { InternalError } from "../error/pithyError.js";
+//#region src/seed/compose.ts
+/** Width of the zero-padded `order` prefix in a composed key — the stable sort anchor. */
+const ORDER_DIGITS = 4;
+/** Maximum per-set `order`, derived from the prefix width so the two never drift. */
+const MAX_SEED_ORDER = 10 ** ORDER_DIGITS - 1;
+/** A bad `order` is a capability-author mistake — surfaced at compose (build), so the value rides along. */
+function assertValidOrder(order, capability, name) {
+	if (!Number.isInteger(order) || order < 0 || order > 9999) throw new InternalError({ message: `seed order ${order} (set "${name}" in capability "${capability}") must be an integer in 0..${MAX_SEED_ORDER}.` });
+}
+/**
+* Merge every capability's `seeds` into one ordered registry for `env`, mirroring the migration
+* composer. Each set's key is `NNNN_<capability>_<name>` (NNNN = zero-padded `order`), so the sort
+* is dependency-correct (libraries before app) and stable across releases. `example` sets are
+* dropped unless `includeExamples`; sets whose `environments` does not list `env` are dropped from
+* the runnable list but reported in `skippedByEnv` (the env-allowlist safety layer). A set name used
+* twice within one capability throws an `InternalError` attributed to that capability.
+*/
+function composeSeeds(capabilities, options) {
+	const sets = [];
+	const skippedByEnv = [];
+	for (const cap of capabilities) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const set of cap.seeds ?? []) {
+			if (seen.has(set.name)) throw new InternalError({
+				message: `Duplicate seed set "${set.name}" in capability "${cap.name}".`,
+				action: "Give every seed set within a capability a unique name."
+			});
+			seen.add(set.name);
+			assertValidOrder(set.order, cap.name, set.name);
+			if (set.example && !options.includeExamples) continue;
+			const key = `${String(set.order).padStart(ORDER_DIGITS, "0")}_${cap.name}_${set.name}`;
+			if (!set.environments.includes(options.env)) {
+				skippedByEnv.push(key);
+				continue;
+			}
+			sets.push({
+				key,
+				capability: cap.name,
+				set
+			});
+		}
+	}
+	sets.sort((a, b) => a.set.order - b.set.order || a.key.localeCompare(b.key));
+	return {
+		sets,
+		skippedByEnv
+	};
+}
+//#endregion
+export { MAX_SEED_ORDER, composeSeeds };

package/dist/seed/devLogin.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * The dev-login artifact: the one file a seed run writes so `pithy dev` can say how to sign in.
+ *
+ * It lives in core because it has two ends in two packages that must not depend on each other — the
+ * auth capability mints it inside its seed set, and the CLI reads it to print the ready banner. Core is
+ * the seam they already share, so the shape is stated once instead of being duplicated (and drifting) at
+ * both ends.
+ *
+ * **The file holds a live credential.** A signed session cookie for a local database is a way in for
+ * anyone who can read it, which is why it is written under `logs/` — gitignored by the starter template,
+ * so it can never be committed — and why nothing here is ever put in a `PithyError` (the payload reaches
+ * logs verbatim).
+ */
+/** The directory seed artifacts are written to, relative to the project root. Gitignored, so transient. */
+export declare const SEED_ARTIFACT_DIR = "logs";
+/** The dev-login file's name within {@link SEED_ARTIFACT_DIR}. The `pithy dev` banner reads it by this name. */
+export declare const DEV_LOGIN_FILE = "dev-login.json";
+/** The dev-login file's path relative to the project root — what the banner and the docs both name. */
+export declare const DEV_LOGIN_PATH = "logs/dev-login.json";
+/**
+ * The dev-login **route**: where a `dev` composition serves the seeded session as a `Set-Cookie` and a
+ * redirect, so signing in is a URL rather than a value pasted into a browser console.
+ *
+ * It is stated here, beside the file, because the two ends are the same two packages the file already
+ * had to reconcile — the auth capability registers it, and `pithy dev` opens it — and neither may
+ * import the other. A second spelling in one of them is a `l` that opens a 404.
+ *
+ * **`__pithy/` is the namespace, and the reservation is the point.** An adopter's own routes are theirs;
+ * anything the kit serves that is not part of a capability's public surface lives under this prefix, so
+ * a route added here can never collide with an application path someone already shipped.
+ *
+ * Registered **only** in a `dev` composition, and never under CI. It mints an authenticated session with
+ * no credential presented, which is the whole risk of the feature and the reason its gates live at
+ * registration rather than inside the handler.
+ */
+export declare const DEV_LOGIN_ROUTE = "/__pithy/dev-login";
+/**
+ * A seeded dev login — everything a browser needs to be signed in as a seeded user, and nothing else.
+ * `z.input` is the JSON on disk (dates as ISO-8601 strings); `z.output` is the app shape.
+ */
+export declare const DevLogin: z.ZodObject<{
+    email: z.ZodString;
+    userId: z.ZodString;
+    cookieName: z.ZodString;
+    cookieValue: z.ZodString;
+    expiresAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type DevLogin = z.output<typeof DevLogin>;
+//# sourceMappingURL=devLogin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"devLogin.d.ts","sourceRoot":"","sources":["../../src/seed/devLogin.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;GAYG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAExC,gHAAgH;AAChH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,uGAAuG;AACvG,eAAO,MAAM,cAAc,wBAA2C,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;iBAc8F,CAAC;AACpH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC"}

package/dist/seed/devLogin.js

@@ -0,0 +1,52 @@
+import { JsonDate } from "../data/codecs.js";
+import { z } from "zod";
+//#region src/seed/devLogin.ts
+/**
+* The dev-login artifact: the one file a seed run writes so `pithy dev` can say how to sign in.
+*
+* It lives in core because it has two ends in two packages that must not depend on each other — the
+* auth capability mints it inside its seed set, and the CLI reads it to print the ready banner. Core is
+* the seam they already share, so the shape is stated once instead of being duplicated (and drifting) at
+* both ends.
+*
+* **The file holds a live credential.** A signed session cookie for a local database is a way in for
+* anyone who can read it, which is why it is written under `logs/` — gitignored by the starter template,
+* so it can never be committed — and why nothing here is ever put in a `PithyError` (the payload reaches
+* logs verbatim).
+*/
+/** The directory seed artifacts are written to, relative to the project root. Gitignored, so transient. */
+const SEED_ARTIFACT_DIR = "logs";
+/** The dev-login file's name within {@link SEED_ARTIFACT_DIR}. The `pithy dev` banner reads it by this name. */
+const DEV_LOGIN_FILE = "dev-login.json";
+/** The dev-login file's path relative to the project root — what the banner and the docs both name. */
+const DEV_LOGIN_PATH = `${SEED_ARTIFACT_DIR}/${DEV_LOGIN_FILE}`;
+/**
+* The dev-login **route**: where a `dev` composition serves the seeded session as a `Set-Cookie` and a
+* redirect, so signing in is a URL rather than a value pasted into a browser console.
+*
+* It is stated here, beside the file, because the two ends are the same two packages the file already
+* had to reconcile — the auth capability registers it, and `pithy dev` opens it — and neither may
+* import the other. A second spelling in one of them is a `l` that opens a 404.
+*
+* **`__pithy/` is the namespace, and the reservation is the point.** An adopter's own routes are theirs;
+* anything the kit serves that is not part of a capability's public surface lives under this prefix, so
+* a route added here can never collide with an application path someone already shipped.
+*
+* Registered **only** in a `dev` composition, and never under CI. It mints an authenticated session with
+* no credential presented, which is the whole risk of the feature and the reason its gates live at
+* registration rather than inside the handler.
+*/
+const DEV_LOGIN_ROUTE = "/__pithy/dev-login";
+/**
+* A seeded dev login — everything a browser needs to be signed in as a seeded user, and nothing else.
+* `z.input` is the JSON on disk (dates as ISO-8601 strings); `z.output` is the app shape.
+*/
+const DevLogin = z.object({
+	email: z.string().describe("The seeded user this cookie signs in as. Shown on the `pithy dev` ready banner."),
+	userId: z.string().describe("The seeded user's id, so a tool can correlate the cookie with the seeded rows."),
+	cookieName: z.string().describe("The cookie name the auth capability's session is read from, e.g. `better-auth.session_token`."),
+	cookieValue: z.string().describe("The signed, URI-encoded cookie value. A live credential for the local database — never logged, never committed, never in an error payload."),
+	expiresAt: JsonDate.describe("When the seeded session expires. ISO-8601 text on disk; a `Date` in app code.")
+}).describe("A seeded dev login: the signed session cookie for one seeded user, written to `logs/dev-login.json`.");
+//#endregion
+export { DEV_LOGIN_FILE, DEV_LOGIN_PATH, DEV_LOGIN_ROUTE, DevLogin, SEED_ARTIFACT_DIR };

package/dist/seed/exampleIdentities.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The canonical example identities — a small, fixed cast of demo users that every capability's
+ * example seed set references. It is what makes `pithy seed` (with `seed.includeExamples`) fill a
+ * fresh backend with *connected* data instead of isolated rows: the same three users own the seeded
+ * auth records, leaderboard scores, ledger balances, and multiplayer results, so a new project can
+ * see the whole stack working together in `dev` without authoring a fixture first.
+ *
+ * This is the shared vocabulary that lets each capability seed user-linked rows without depending on
+ * `@pithy-sh/auth` — or on each other. Every module reads these ids from `@pithy-sh/core`, the one
+ * seam they all share (capabilities depend on core seams, never each other's internals). It is a
+ * seeding *convention*, the peer of the standard asset-metadata block: a handful of stable
+ * constants, never a data set.
+ *
+ * The ids are stable and human-legible (`example-<name>`) so seeded rows are obvious in a dev
+ * database. Emails use the reserved `example.com` domain (RFC 2606) so a seeded user can never
+ * collide with, or be mistaken for, a real address.
+ */
+/** One canonical demo user — the shared identity a capability's example seed hangs its rows off. */
+export interface ExampleIdentity {
+    /** The stable demo user id — used as the `userId`/owner across every capability's example seed. */
+    id: string;
+    /** The user's display name. */
+    name: string;
+    /** The user's unique email, on the reserved `example.com` domain. */
+    email: string;
+}
+/**
+ * The canonical demo cast, in a stable order. Referenced by every capability's example seed set so
+ * the seeded data is connected across tables. Keep it tiny — this is a demonstration, not a dataset.
+ */
+export declare const EXAMPLE_IDENTITIES: readonly [{
+    readonly id: "example-ada";
+    readonly name: "Ada Lovelace";
+    readonly email: "ada@example.com";
+}, {
+    readonly id: "example-grace";
+    readonly name: "Grace Hopper";
+    readonly email: "grace@example.com";
+}, {
+    readonly id: "example-alan";
+    readonly name: "Alan Turing";
+    readonly email: "alan@example.com";
+}];
+/** The three canonical identities by name, for readable references in fixtures (`EXAMPLE_ADA.id`). */
+export declare const EXAMPLE_ADA: {
+    readonly id: "example-ada";
+    readonly name: "Ada Lovelace";
+    readonly email: "ada@example.com";
+}, EXAMPLE_GRACE: {
+    readonly id: "example-grace";
+    readonly name: "Grace Hopper";
+    readonly email: "grace@example.com";
+}, EXAMPLE_ALAN: {
+    readonly id: "example-alan";
+    readonly name: "Alan Turing";
+    readonly email: "alan@example.com";
+};
+//# sourceMappingURL=exampleIdentities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exampleIdentities.d.ts","sourceRoot":"","sources":["../../src/seed/exampleIdentities.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB;iBACvB,aAAa;mBAAQ,cAAc;oBAAS,iBAAiB;;iBAC7D,eAAe;mBAAQ,cAAc;oBAAS,mBAAmB;;iBACjE,cAAc;mBAAQ,aAAa;oBAAS,kBAAkB;EACvB,CAAC;AAEhD,sGAAsG;AACtG,eAAO,MAAO,WAAW;iBANjB,aAAa;mBAAQ,cAAc;oBAAS,iBAAiB;GAM1C,aAAa;iBALhC,eAAe;mBAAQ,cAAc;oBAAS,mBAAmB;GAK/B,YAAY;iBAJ9C,cAAc;mBAAQ,aAAa;oBAAS,kBAAkB;CAIM,CAAC"}

package/dist/seed/exampleIdentities.js

@@ -0,0 +1,26 @@
+//#region src/seed/exampleIdentities.ts
+/**
+* The canonical demo cast, in a stable order. Referenced by every capability's example seed set so
+* the seeded data is connected across tables. Keep it tiny — this is a demonstration, not a dataset.
+*/
+const EXAMPLE_IDENTITIES = [
+	{
+		id: "example-ada",
+		name: "Ada Lovelace",
+		email: "ada@example.com"
+	},
+	{
+		id: "example-grace",
+		name: "Grace Hopper",
+		email: "grace@example.com"
+	},
+	{
+		id: "example-alan",
+		name: "Alan Turing",
+		email: "alan@example.com"
+	}
+];
+/** The three canonical identities by name, for readable references in fixtures (`EXAMPLE_ADA.id`). */
+const [EXAMPLE_ADA, EXAMPLE_GRACE, EXAMPLE_ALAN] = EXAMPLE_IDENTITIES;
+//#endregion
+export { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE, EXAMPLE_IDENTITIES };

package/dist/seed/metadata.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The standard Cloudflare-asset metadata convention.
+ *
+ * Every write to a shared Images/Stream store (seeded assets are the first consumer, but the
+ * convention is account-wide) stamps a small, stable metadata block so an asset can be attributed
+ * and scoped without a separate lookup — most importantly to the environment that created it, so a
+ * staging teardown never touches a production asset. App-defined fields (e.g. `userId`) merge on
+ * top; the standard keys always win, so a caller's `extra` can never overwrite `pithyEnv`.
+ */
+/** The metadata key carrying the environment an asset was created in — the scoping anchor. */
+export declare const PITHY_ENV_METADATA_KEY = "pithyEnv";
+/** The metadata keys Pithy sets on every shared-asset write. Kept stable and documented. */
+export declare const STANDARD_ASSET_METADATA_KEYS: readonly string[];
+/**
+ * Build the metadata block for a shared-asset upload: the standard keys (at minimum
+ * `{ pithyEnv: env }`) merged over any app-defined `extra`. The standard keys are applied last, so
+ * they always win — `extra` can add fields but never override the scoping anchor.
+ */
+export declare function buildAssetMetadata(env: string, extra?: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/seed/metadata.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,8FAA8F;AAC9F,eAAO,MAAM,sBAAsB,aAAa,CAAC;AAEjD,4FAA4F;AAC5F,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAA6B,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEtG"}

package/dist/seed/metadata.js

@@ -0,0 +1,27 @@
+//#region src/seed/metadata.ts
+/**
+* The standard Cloudflare-asset metadata convention.
+*
+* Every write to a shared Images/Stream store (seeded assets are the first consumer, but the
+* convention is account-wide) stamps a small, stable metadata block so an asset can be attributed
+* and scoped without a separate lookup — most importantly to the environment that created it, so a
+* staging teardown never touches a production asset. App-defined fields (e.g. `userId`) merge on
+* top; the standard keys always win, so a caller's `extra` can never overwrite `pithyEnv`.
+*/
+/** The metadata key carrying the environment an asset was created in — the scoping anchor. */
+const PITHY_ENV_METADATA_KEY = "pithyEnv";
+/** The metadata keys Pithy sets on every shared-asset write. Kept stable and documented. */
+const STANDARD_ASSET_METADATA_KEYS = [PITHY_ENV_METADATA_KEY];
+/**
+* Build the metadata block for a shared-asset upload: the standard keys (at minimum
+* `{ pithyEnv: env }`) merged over any app-defined `extra`. The standard keys are applied last, so
+* they always win — `extra` can add fields but never override the scoping anchor.
+*/
+function buildAssetMetadata(env, extra) {
+	return {
+		...extra,
+		[PITHY_ENV_METADATA_KEY]: env
+	};
+}
+//#endregion
+export { PITHY_ENV_METADATA_KEY, STANDARD_ASSET_METADATA_KEYS, buildAssetMetadata };