@pithy-sh/core 0.1.0

package/src/schema/describedness.ts

@@ -0,0 +1,250 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { InternalError } from "../error/pithyError";
+
+/**
+ * **CLAUDE.md §Zod, made executable: the schemas are the documentation.**
+ *
+ * Every object, enum and union carries a `.describe()`, and so does every field of every object. The
+ * rule is stated once in `CLAUDE.md` and enforced nineteen times — once per package that declares a
+ * schema — and until #351 each of those nineteen enforcements was a private copy of the walk. They
+ * drifted, as copies do: three demanded a description on the field exactly as written, fifteen walked
+ * the wrapper chain to find one, one stepped through a `pipe` and eighteen did not, and exactly one
+ * (`@pithy-sh/audit`, #326) descended into an `array` — the shape that hides an undescribed object.
+ * A package's coverage was decided by which copy it inherited.
+ *
+ * This is that walk, once, in the package every other one already depends on. It is deliberately not
+ * test-only code: an adopter declaring capability config of their own is held to the same rule by the
+ * same CLI surfaces that read these descriptions, so the check belongs where they can reach it.
+ *
+ * ## This folder
+ *
+ * `src/schema/` reasons *about* Zod schemas. It is not a drawer to declare them in — §"group by
+ * concern, not by artifact kind" forbids that, and a schema belongs beside the thing it describes.
+ */
+
+/** A Zod schema's internal definition, as much of it as this walk reads. */
+interface Def {
+  type: string;
+  element?: unknown;
+  innerType?: unknown;
+  options?: unknown[];
+  valueType?: unknown;
+  keyType?: unknown;
+  items?: unknown[];
+  rest?: unknown;
+  left?: unknown;
+  right?: unknown;
+}
+
+/** The kind tag Zod puts on a schema's definition. */
+function kindOf(schema: z.ZodType): string {
+  return (schema as unknown as { def: Def }).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: ReadonlySet<string> = 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",
+  // Cyclic by construction. Following the getter is how a walk over a recursive schema never returns.
+  "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: ReadonlySet<string> = 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`.
+ */
+export function childSchemas(schema: z.ZodType, path: string): z.ZodType[] {
+  const def = (schema as unknown as { def: Def }).def;
+  switch (def.type) {
+    case "object":
+      return Object.values((schema as unknown as z.ZodObject).shape) as z.ZodType[];
+    case "array":
+      return [def.element as z.ZodType];
+    case "optional":
+    case "nullable":
+    case "default":
+    case "prefault":
+    case "readonly":
+    case "catch":
+    case "nonoptional":
+    case "success":
+      return [def.innerType as z.ZodType];
+    case "union":
+      return (def.options ?? []) as z.ZodType[];
+    case "intersection":
+      return [def.left as z.ZodType, def.right as z.ZodType];
+    case "tuple":
+      return [...((def.items ?? []) as z.ZodType[]), ...(def.rest ? [def.rest as z.ZodType] : [])];
+    case "record":
+    case "map":
+      return [def.keyType as z.ZodType, def.valueType as z.ZodType].filter(Boolean);
+    case "set":
+      return [def.valueType as z.ZodType];
+    case "pipe":
+      if (schema instanceof z.ZodCodec) return [];
+      return [(schema as unknown as { in: z.ZodType }).in, (schema as unknown as { out: z.ZodType }).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.
+ */
+export function describedInChain(schema: z.ZodType): boolean {
+  let current: z.ZodType | undefined = schema;
+  const seen = new Set<z.ZodType>();
+  while (current && !seen.has(current)) {
+    if (current.description) return true;
+    if (!TRANSPARENT.has(kindOf(current))) return false;
+    seen.add(current);
+    current = (current as unknown as { def?: { innerType?: z.ZodType } }).def?.innerType;
+  }
+  return false;
+}
+
+/** What one walk found: the complaints, and how much it actually looked at. */
+export interface SchemaWalk {
+  /** One line per object, enum, union or field with no `.describe()` anywhere that documents it. */
+  missing: string[];
+  /** Every field of every object reached, so an empty walk is visible as an empty walk. */
+  fields: number;
+}
+
+/**
+ * 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}.
+ */
+export function collectMissing(
+  schema: z.ZodType,
+  path: string,
+  walk: SchemaWalk,
+  seen: Set<z.ZodType>,
+  described = false,
+): void {
+  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 as unknown as z.ZodObject).shape)) {
+      const fieldSchema = field as z.ZodType;
+      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. */
+export function undescribed(schema: z.ZodType, path = "schema"): SchemaWalk {
+  const walk: SchemaWalk = { missing: [], fields: 0 };
+  collectMissing(schema, path, walk, new Set());
+  return walk;
+}
+
+/** What a package-wide sweep found, including the size of the population it swept. */
+export interface ExportWalk extends SchemaWalk {
+  /** Modules the glob handed over. Zero is a broken pattern, not a clean package. */
+  modules: number;
+  /** Exports that resolved to a Zod schema. */
+  schemas: number;
+}
+
+/**
+ * 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.
+ */
+export function undescribedExports(modules: Record<string, Record<string, unknown>>): ExportWalk {
+  const walk: SchemaWalk = { missing: [], fields: 0 };
+  const seen = new Set<z.ZodType>();
+  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 };
+}

package/src/seed/compose.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import { InternalError } from "../error/pithyError";
+import type { SeedSet } from "./seed";
+
+/** 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. */
+export const MAX_SEED_ORDER = 10 ** ORDER_DIGITS - 1;
+
+/** 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[];
+}
+
+/** A bad `order` is a capability-author mistake — surfaced at compose (build), so the value rides along. */
+function assertValidOrder(order: number, capability: string, name: string): void {
+  if (!Number.isInteger(order) || order < 0 || order > MAX_SEED_ORDER) {
+    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.
+ */
+export function composeSeeds(capabilities: readonly Capability[], options: ComposeSeedsOptions): ComposedSeeds {
+  const sets: ResolvedSeedSet[] = [];
+  const skippedByEnv: string[] = [];
+
+  for (const cap of capabilities) {
+    const seen = new Set<string>();
+    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);
+
+      // Example sets are config-gated: absent entirely unless the project opted in. This is not an
+      // env skip, so it is never reported — it is simply not part of the registry.
+      if (set.example && !options.includeExamples) continue;
+
+      const prefix = String(set.order).padStart(ORDER_DIGITS, "0");
+      const key = `${prefix}_${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 };
+}

package/src/seed/devLogin.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { JsonDate } from "../data/codecs";
+
+/**
+ * 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 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 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 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.
+ */
+export 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 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`.");
+export type DevLogin = z.output<typeof DevLogin>;

package/src/seed/exampleIdentities.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * 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 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" },
+] as const satisfies readonly ExampleIdentity[];
+
+/** The three canonical identities by name, for readable references in fixtures (`EXAMPLE_ADA.id`). */
+export const [EXAMPLE_ADA, EXAMPLE_GRACE, EXAMPLE_ALAN] = EXAMPLE_IDENTITIES;

package/src/seed/metadata.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * 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 const PITHY_ENV_METADATA_KEY = "pithyEnv";
+
+/** The metadata keys Pithy sets on every shared-asset write. Kept stable and documented. */
+export const STANDARD_ASSET_METADATA_KEYS: readonly string[] = [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.
+ */
+export function buildAssetMetadata(env: string, extra?: Record<string, string>): Record<string, string> {
+  return { ...extra, [PITHY_ENV_METADATA_KEY]: env };
+}