@pithy-sh/core 0.1.2 → 0.1.4

package/dist/capability/client.js

@@ -0,0 +1,86 @@
+import { fromZodError } from "../error/pithyError.js";
+import { refusesVanishingKey } from "./vanishingKey.js";
+import { z } from "zod";
+//#region src/capability/client.ts
+/**
+* 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";
+/** Whether a value is a plain record — `{}` or `Object.create(null)`, never a `Date`, `Map`, or class. */
+function isPlainRecord(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	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.
+*/
+const 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(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).
+*/
+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.");
+/**
+* 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.";
+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);
+/**
+* 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.
+*/
+function resolveClientProjection(capability, context) {
+	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;
+}
+//#endregion
+export { ClientProjection, ClientProjectionContext, JsonValue, resolveClientProjection };

package/dist/capability/compose.d.ts

@@ -0,0 +1,25 @@
+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 declare function bindingGroupsFrom<Spec extends {
+    binding: string;
+}, Item>(map: Record<string, Spec> | undefined, items: (spec: Spec) => Record<string, Item>): Record<string, BindingGroup<Item>> | undefined;
+/**
+ * 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 declare function composeBindingGroups<Item>(capabilities: Capability[], select: (cap: Capability) => Record<string, BindingGroup<Item>> | undefined, groupLabel: string, itemLabel: string): Record<string, BindingGroup<Item>>;
+//# sourceMappingURL=compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/capability/compose.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,8FAA8F;AAC9F,MAAM,WAAW,YAAY,CAAC,IAAI;IAChC,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EACtE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,SAAS,EACrC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAKhD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EACvC,YAAY,EAAE,UAAU,EAAE,EAC1B,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EAC3E,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAkCpC"}

package/dist/capability/compose.js

@@ -0,0 +1,54 @@
+import { InternalError } from "../error/pithyError.js";
+//#region src/capability/compose.ts
+/**
+* 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.
+*/
+function bindingGroupsFrom(map, items) {
+	if (!map) return void 0;
+	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.
+*/
+function composeBindingGroups(capabilities, select, groupLabel, itemLabel) {
+	const merged = {};
+	const groupOwner = {};
+	const itemOwners = /* @__PURE__ */ new Map();
+	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;
+}
+//#endregion
+export { bindingGroupsFrom, composeBindingGroups };

package/dist/capability/composition.d.ts

@@ -0,0 +1,26 @@
+import type { Capability } from "./capability";
+/**
+ * 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 declare function recordComposition(capabilities: readonly Capability[]): void;
+/** Forget it. For a test that needs the un-composed state back; a deployed Worker never calls this. */
+export declare function forgetComposition(): void;
+/**
+ * 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 declare function composedCapabilities(): readonly Capability[];
+/**
+ * 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 declare function composedCapability<T extends Capability>(name: string, is: (capability: Capability) => boolean): T;
+//# sourceMappingURL=composition.d.ts.map

package/dist/capability/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/capability/composition.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAyC/C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAE3E;AAED,uGAAuG;AACvG,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,SAAS,UAAU,EAAE,CAS5D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,GAAG,CAAC,CAajH"}

package/dist/capability/composition.js

@@ -0,0 +1,84 @@
+import { InternalError } from "../error/pithyError.js";
+//#region src/capability/composition.ts
+/**
+* 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 = 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.
+*/
+function recordComposition(capabilities) {
+	composed = [...capabilities];
+}
+/** Forget it. For a test that needs the un-composed state back; a deployed Worker never calls this. */
+function forgetComposition() {
+	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.
+*/
+function composedCapabilities() {
+	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.
+*/
+function composedCapability(name, is) {
+	const found = composedCapabilities().find((capability) => capability.name === name && is(capability));
+	if (!found) throw new InternalError({
+		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;
+}
+//#endregion
+export { composedCapabilities, composedCapability, forgetComposition, recordComposition };

package/dist/capability/config.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import type { Capability } from "./capability";
+/** Compose each capability's config schema into one object keyed by capability name. */
+export declare function composeConfig(capabilities: Capability[]): z.ZodObject<Record<string, z.ZodType>>;
+/** Validate raw config input against the composed schema; throws on mismatch. */
+export declare function loadConfig(capabilities: Capability[], input: unknown): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=config.d.ts.map

package/dist/capability/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/capability/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAMhG;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,YAAY,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE9G"}

package/dist/capability/config.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+//#region src/capability/config.ts
+/** Compose each capability's config schema into one object keyed by capability name. */
+function composeConfig(capabilities) {
+	const shape = {};
+	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. */
+function loadConfig(capabilities, input) {
+	return composeConfig(capabilities).parse(input);
+}
+//#endregion
+export { composeConfig, loadConfig };

package/dist/capability/devSecret.d.ts

@@ -0,0 +1,32 @@
+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 declare const DevSecretValue: z.ZodEnum<{
+    random: "random";
+}>;
+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 declare const DevSecret: z.ZodObject<{
+    name: z.ZodString;
+    devValue: z.ZodEnum<{
+        random: "random";
+    }>;
+}, z.core.$strip>;
+export type DevSecret = z.infer<typeof DevSecret>;
+//# sourceMappingURL=devSecret.d.ts.map

package/dist/capability/devSecret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devSecret.d.ts","sourceRoot":"","sources":["../../src/capability/devSecret.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,cAAc;;EAE6E,CAAC;AACzG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;iBAUoE,CAAC;AAC3F,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/capability/devSecret.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+//#region src/capability/devSecret.ts
+/**
+* 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.
+*/
+const DevSecretValue = z.enum(["random"]).describe("How `pithy add` mints a secret's dev value. `random` is a random string and nothing else.");
+/**
+* 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.
+*/
+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.");
+//#endregion
+export { DevSecret, DevSecretValue };