@pithy-sh/core 0.1.0

package/src/capability/client.ts

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { fromZodError } from "../error/pithyError";
+import type { Capability } from "./capability";
+import { refusesVanishingKey } from "./vanishingKey";
+
+/**
+ * Who has to go and fix a projection that states a key which vanishes. The guard names them, and for a
+ * projection that is the capability author, not the adopter.
+ */
+const SUBJECT = "A capability's client projection";
+
+/**
+ * A JSON value — the only thing that may cross into a browser bundle. Recursive, so an object or
+ * array of JSON values is one too. Declared as a type first because a Zod schema cannot infer its
+ * own recursion (CLAUDE.md §Zod: the const and the type share one name).
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Whether a value is a plain record — `{}` or `Object.create(null)`, never a `Date`, `Map`, or class. */
+function isPlainRecord(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * The JSON value space, as a schema. `z.lazy` carries the recursion. The record branch is guarded by
+ * a plain-object check first: `z.record` alone accepts a `Date` (it has no own enumerable keys) and
+ * would quietly project it as `{}`. A non-finite number is rejected for the same reason — `JSON.stringify`
+ * turns `NaN` into `null`, which is a silent value change, not a projection.
+ *
+ * `refusesVanishingKey` is the third check of the same kind, and the one this schema was missing: a
+ * `__proto__` key written by a capability is dropped by `z.record` with no issue raised, so it never
+ * reaches the bundle and nothing says it was written. See `vanishingKey.ts`.
+ *
+ * It wraps the **whole value**, outside the union, and both halves of that matter. Whole value, because
+ * this is the recursion: every string, array and object in a projection is a `JsonValue`, so guarding it
+ * once covers a space nobody can enumerate, at a depth nobody has to predict. Non-objects pass the check
+ * by definition, so the cost is a `typeof` per node. Outside the union, because a refusal raised by one
+ * branch of a union is reported as the union's own — measured, the message for a key one level down was
+ * `Invalid input`, and out here it is the guard's own sentence at the key's own path.
+ *
+ * Below an array it is `Invalid union` again, with the guard's sentence nested in `issue.errors`. That is
+ * how this union reports every rejection it makes — a `Date` at the same depth reads the same way today —
+ * so it is the union's shape to fix, not this guard's, and it is written here so the next reader knows it
+ * was seen rather than missed.
+ */
+export const JsonValue: z.ZodType<JsonValue> = refusesVanishingKey(
+  z.lazy(() =>
+    z.union([
+      z.string(),
+      z.number().refine((value) => Number.isFinite(value), { error: "Expected a finite number." }),
+      z.boolean(),
+      z.null(),
+      z.array(JsonValue),
+      z
+        .custom<Record<string, unknown>>(isPlainRecord, { error: "Expected a plain JSON object." })
+        .pipe(z.record(z.string(), JsonValue)),
+    ]),
+  ),
+  SUBJECT,
+).describe("Any JSON value — string, finite number, boolean, null, array, or plain object.");
+
+/**
+ * What a capability's client projection is resolved against. A projection is per build, not per
+ * request: the plugin inlines the result into the bundle, so the only axis it varies on is the
+ * environment being built for (a Turnstile sitekey differs between staging and production).
+ */
+export const ClientProjectionContext = z
+  .object({
+    environment: z
+      .string()
+      .min(1)
+      .describe(
+        "The environment this bundle is built for — `dev`, `staging`, `production`, or an adopter's own name. Per-environment config (a Turnstile sitekey) resolves against it.",
+      ),
+  })
+  .describe("The build-time context a capability's client projection is resolved against.");
+export type ClientProjectionContext = z.output<typeof ClientProjectionContext>;
+
+/**
+ * One capability's client-safe projection — the **only** values of its config that may reach a
+ * browser bundle. `enabled` is always present so a screen can branch (`false` means the capability is
+ * absent, or configured in a way this environment cannot render); everything else is the capability's
+ * own JSON, validated by the catchall. This validation is the security boundary of `virtual:pithy/*`:
+ * a capability cannot smuggle a function, a `Date`, or an unserializable value into the bundle, and a
+ * new config field never ships to browsers unless its capability adds it here on purpose.
+ *
+ * Guarded a second time, and this is the one place in the file where that is not redundant. `JsonValue`
+ * covers every object *inside* a projection; the projection's own top level is this object, parsed by the
+ * object branch rather than the record one, and Zod drops `__proto__` there too. So the recursion closes
+ * everything below the root and the root closes itself. Two sites, and the walk in `vanishingKey.test.ts`
+ * is what says they are the only two.
+ */
+const PROJECTION_DESCRIPTION =
+  "A capability's client-safe projection — the only config values that reach a browser bundle.";
+export const ClientProjection = refusesVanishingKey(
+  z
+    .object({
+      enabled: z
+        .boolean()
+        .describe(
+          "Whether the capability is composed and usable in this environment. `false` means a screen must branch, not render.",
+        ),
+    })
+    .catchall(JsonValue)
+    .describe(PROJECTION_DESCRIPTION),
+  SUBJECT,
+).describe(PROJECTION_DESCRIPTION);
+export type ClientProjection = z.output<typeof ClientProjection>;
+
+/**
+ * Resolve one capability's client projection, validated. An absent capability, or one that declares no
+ * projection, is `{ enabled: false }` — never an error, because a front end is written against the
+ * capabilities it may have, not the ones it does. A declared projection is parsed through
+ * {@link ClientProjection}, so a non-JSON value is a build failure rather than a broken bundle.
+ */
+export function resolveClientProjection(
+  capability: Capability | undefined,
+  context: ClientProjectionContext,
+): ClientProjection {
+  if (!capability?.client) return { enabled: false };
+  const resolvedContext = ClientProjectionContext.parse(context);
+  const projected = ClientProjection.safeParse(capability.client(resolvedContext));
+  if (!projected.success) {
+    throw fromZodError(projected.error, {
+      message: `The ${capability.name} capability's client projection is not JSON.`,
+      action: `Return only JSON values from the ${capability.name} capability's \`client\` projection — no functions, dates, or undefined.`,
+      detail: `environment=${resolvedContext.environment}`,
+    });
+  }
+  return projected.data;
+}

package/src/capability/compose.ts

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "../error/pithyError";
+import type { Capability } from "./capability";
+
+/** A logical group bound to one CF binding, holding named items — D1 tables, or KV stores. */
+export interface BindingGroup<Item> {
+  /** The CF binding this group lives in (a D1 or KV binding name in the Worker env). */
+  binding: string;
+  /** The named items in this group: table name → schema, or store name → spec. */
+  items: Record<string, Item>;
+}
+
+/**
+ * Adapt a capability's domain map (`databases`, `kvNamespaces`, …) — each entry a `{ binding, … }`
+ * spec — into the neutral {@link BindingGroup} shape `composeBindingGroups` consumes, projecting the
+ * domain item field (`tables`, `stores`) to `items`. One place to add the next binding type.
+ */
+export function bindingGroupsFrom<Spec extends { binding: string }, Item>(
+  map: Record<string, Spec> | undefined,
+  items: (spec: Spec) => Record<string, Item>,
+): Record<string, BindingGroup<Item>> | undefined {
+  if (!map) return undefined;
+  return Object.fromEntries(
+    Object.entries(map).map(([name, spec]) => [name, { binding: spec.binding, items: items(spec) }]),
+  );
+}
+
+/**
+ * Merge a binding-backed group that capabilities contribute to — D1 `databases` (items are tables)
+ * or KV `kvNamespaces` (items are stores). Capabilities targeting the same group name merge their
+ * items (the project-wide contents, per group); a binding mismatch for one name, or an item name
+ * claimed twice in one group, is an author conflict caught here at assembly (internal — names are
+ * not secret). `groupLabel`/`itemLabel` make the error read in the caller's vocabulary.
+ */
+export function composeBindingGroups<Item>(
+  capabilities: Capability[],
+  select: (cap: Capability) => Record<string, BindingGroup<Item>> | undefined,
+  groupLabel: string,
+  itemLabel: string,
+): Record<string, BindingGroup<Item>> {
+  const merged: Record<string, BindingGroup<Item>> = {};
+  const groupOwner: Record<string, string> = {};
+  const itemOwners = new Map<string, Record<string, string>>();
+
+  for (const cap of capabilities) {
+    for (const [name, group] of Object.entries(select(cap) ?? {})) {
+      let target = merged[name];
+      let owners = itemOwners.get(name);
+      if (!target || !owners) {
+        target = { binding: group.binding, items: {} };
+        owners = {};
+        merged[name] = target;
+        itemOwners.set(name, owners);
+        groupOwner[name] = cap.name;
+      } else if (target.binding !== group.binding) {
+        throw new InternalError({
+          message: `${groupLabel} "${name}" is bound to "${target.binding}" by capability "${groupOwner[name]}" but to "${group.binding}" by "${cap.name}".`,
+          action: `Use one binding per ${groupLabel} name across capabilities.`,
+        });
+      }
+      for (const [item, value] of Object.entries(group.items)) {
+        if (item in target.items) {
+          throw new InternalError({
+            message: `Duplicate ${itemLabel} "${item}" in ${groupLabel} "${name}": declared by capabilities "${owners[item]}" and "${cap.name}".`,
+            action: `Rename one ${itemLabel} — every ${itemLabel} name within a ${groupLabel} must be unique.`,
+          });
+        }
+        target.items[item] = value;
+        owners[item] = cap.name;
+      }
+    }
+  }
+  return merged;
+}

package/src/capability/composition.ts

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "../error/pithyError";
+import type { Capability } from "./capability";
+
+/**
+ * The composed set, reachable from module scope — **so a Workflow can find it** (pithy-sh/pithy#356).
+ *
+ * ## The gap this closes
+ *
+ * A capability's `compose` hook receives every other composed capability, so a route can hold
+ * `@pithy-sh/email`'s bound `enqueue` and call it. `@pithy-sh/auth` does exactly that for magic links,
+ * and an adopter copies the pattern for its own mail.
+ *
+ * **A Workflow class cannot.** The runtime constructs it with the worker `env` and nothing else. `env`
+ * carries `DB`, `EMAIL_SENDER` and every other binding, but a composed seam is a closure `compose`
+ * handed out, not a binding — and there was no way back from a durable step to the composed set. The
+ * two ways past it were both wrong and both the adopter's to take: rebuild the seam from `env` plus a
+ * restated identity (the same sending address in a second place, free to drift from `pithy.config.ts`),
+ * or pass the closure through Workflow params (which are serialized, and a closure is not). So a durable
+ * job could never send mail, and `pithy-sh/dashboard`'s monthly key-rotation notice was written, tested,
+ * and reachable by nothing.
+ *
+ * ## Why module scope is the right place, and what it costs
+ *
+ * `createBackend` runs at module load, and Cloudflare requires a Workflow class to be exported from the
+ * same worker entrypoint that exports the `fetch` handler — so the composition has already happened, in
+ * this isolate, by the time any step body runs. That is the same reasoning
+ * `@pithy-sh/secrets`' shared accessor is built on, and it is worth being explicit that it is a
+ * *reasoned* singleton rather than a convenient global: one worker assembles one backend.
+ *
+ * The cost is that a second `createBackend` in one isolate replaces the first. In a deployed Worker that
+ * cannot happen; in a test file it can, so {@link recordComposition} replaces wholesale rather than
+ * merging — a half-remembered composition would be worse than none — and {@link forgetComposition}
+ * exists so a suite can return to the un-composed state and assert what happens there.
+ *
+ * **Nothing here is a service locator for application code.** A route has `c.var`, and a capability has
+ * its `compose` hook; both are better, both are typed, and both stay the way to reach a seam. This is
+ * for the one caller that has neither.
+ */
+
+/** The composed set, or null before any backend has been assembled in this isolate. */
+let composed: readonly Capability[] | null = null;
+
+/**
+ * Record the composed set. Called once by `createBackend`, after every `compose` hook has run — so a
+ * capability found here is one whose own wiring is already complete, not one mid-assembly.
+ */
+export function recordComposition(capabilities: readonly Capability[]): void {
+  composed = [...capabilities];
+}
+
+/** Forget it. For a test that needs the un-composed state back; a deployed Worker never calls this. */
+export function forgetComposition(): void {
+  composed = null;
+}
+
+/**
+ * The composed capabilities, or a raised wiring fault.
+ *
+ * Empty is not an answer. A caller asking this has already decided it needs a composed seam, and an
+ * empty array would send it down a "the capability is not composed" path that is indistinguishable from
+ * "no backend was assembled" — two very different things to tell somebody reading a log at 3am.
+ */
+export function composedCapabilities(): readonly Capability[] {
+  if (composed === null) {
+    throw new InternalError({
+      message: "This job could not reach the application's capabilities.",
+      action: "Export the Workflow class from the same worker entrypoint that calls createBackend.",
+      detail: "composedCapabilities() was called before any createBackend ran in this isolate.",
+    });
+  }
+  return composed;
+}
+
+/**
+ * One composed capability by name, narrowed by its own type guard, or a raised wiring fault naming it.
+ *
+ * The guard is the capability's own (`isEmailCapability`, and its peers), so the narrowing is the
+ * capability's declaration rather than a cast here — a capability composed under the right name but
+ * without its seams attached is caught as the wiring failure it is, not returned as something whose
+ * methods are missing at the call site.
+ */
+export function composedCapability<T extends Capability>(name: string, is: (capability: Capability) => boolean): T {
+  const found = composedCapabilities().find((capability) => capability.name === name && is(capability));
+  if (!found) {
+    throw new InternalError({
+      // The capability's name is in the client-safe half deliberately, exactly as `createBackend`'s
+      // missing-peer check names it: a capability name is a published part of this framework, and a
+      // wiring fault that will not say which wire is a fault nobody can act on.
+      message: `The "${name}" capability is not composed, so this job could not run.`,
+      action: `Add ${name}(...) to createBackend's capabilities (run \`pithy add ${name}\`).`,
+      detail: `no composed capability named "${name}" carrying its seams was found.`,
+    });
+  }
+  return found as T;
+}

package/src/capability/config.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { Capability } from "./capability";
+
+/** Compose each capability's config schema into one object keyed by capability name. */
+export function composeConfig(capabilities: Capability[]): z.ZodObject<Record<string, z.ZodType>> {
+  const shape: Record<string, z.ZodType> = {};
+  for (const cap of capabilities) {
+    if (cap.config) shape[cap.name] = cap.config;
+  }
+  return z.object(shape);
+}
+
+/** Validate raw config input against the composed schema; throws on mismatch. */
+export function loadConfig(capabilities: Capability[], input: unknown): Record<string, Record<string, unknown>> {
+  return composeConfig(capabilities).parse(input) as Record<string, Record<string, unknown>>;
+}

package/src/capability/devSecret.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * A secret whose value is **arbitrary**, and can therefore be minted for local dev.
+ *
+ * The rule, stated once and here: a secret is generatable when nothing outside the project has to
+ * agree with its value. A session signing key is; an OAuth client secret registered with a provider,
+ * or a Stripe key, is not — a generated value there authenticates against nothing, and hides a real
+ * gap behind one that looks filled in.
+ *
+ * It lives in core, and in its own module, because both ends need it and neither can import the
+ * other: the owning capability declares it on its `@pithy-sh/secrets` registry entry, and the CLI
+ * reads the same declaration off `pithy.manifest.json` — which it must, since `pithy add` wires a
+ * capability without ever executing it.
+ */
+
+export const DevSecretValue = z
+  .enum(["random"])
+  .describe("How `pithy add` mints a secret's dev value. `random` is a random string and nothing else.");
+export type DevSecretValue = z.infer<typeof DevSecretValue>;
+
+/**
+ * One declared dev secret, as a manifest carries it: the registry name, and how its value is minted.
+ *
+ * The manifest's projection of the registry entry's `devValue`. Each capability's own tests assert the
+ * two agree, the way `requiredBindings` and `peerCapabilities` already mirror the runtime capability.
+ */
+export const DevSecret = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .describe(
+        "The registry name the secret is declared under — also the `.dev.vars` key, since local dev resolves every secret from its injected string.",
+      ),
+    devValue: DevSecretValue.describe("How the dev value is minted. Must match the registry entry's `devValue`."),
+  })
+  .describe("A secret whose dev value `pithy add` mints, because its value is arbitrary.");
+export type DevSecret = z.infer<typeof DevSecret>;