@pithy-sh/core 0.9.0 → 0.10.0

package/dist/openapi/document.js

@@ -0,0 +1,314 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { CONTROL_PLANE_HEADER } from "../controlPlane/wire.js";
+import { routeSpecOf } from "../http/routeSpec.js";
+import { requestContractOf } from "../http/validation.js";
+import { ErrorBody } from "../error/wire.js";
+import { pathParams } from "../http/routeContract.js";
+import { z } from "zod";
+//#region src/openapi/document.ts
+/**
+* **The OpenAPI contract, read off a composed app.**
+*
+* Nothing here is written by hand. A route's request schemas come from its `validate` middleware, its
+* summary, verification and responses from its `describeRoute`, and both are found by walking
+* `app.routes` — the same table Hono dispatches from. So the document describes exactly what the Worker
+* serves, the adopter's own routes included, and a schema edit reaches it with no second step.
+*
+* Zod is already the source of truth for every request and response, and every field carries a
+* `.describe()` (CLAUDE.md §Zod). `z.toJSONSchema` keeps those descriptions, which is what lets a client
+* generated in Swift or Kotlin carry the same documentation as the TypeScript one.
+*
+* OpenAPI 3.1, whose schema dialect is JSON Schema 2020-12 — the dialect `z.toJSONSchema` writes — so
+* every schema crosses unchanged.
+*/
+/** The OpenAPI version this module writes. */
+const OPENAPI_VERSION = "3.1.0";
+/** How each verification strategy is presented on the wire. `signed-webhook` and `public` have no scheme. */
+const SECURITY_SCHEMES = {
+	bearer: {
+		type: "http",
+		scheme: "bearer",
+		description: "A short-lived access token from `@pithy-sh/auth`, sent as `Authorization: Bearer <token>`."
+	},
+	session: {
+		type: "apiKey",
+		in: "cookie",
+		name: "better-auth.session_token",
+		description: "A browser session cookie from `@pithy-sh/auth`, named `__Secure-better-auth.session_token` over HTTPS. A state-changing request also needs its `Origin` to be one the Worker trusts."
+	},
+	controlPlane: {
+		type: "apiKey",
+		in: "header",
+		name: CONTROL_PLANE_HEADER,
+		description: "A customer-issued, scoped control-plane credential. Default-denied."
+	}
+};
+/** The `security` requirement for each strategy that has one. */
+const REQUIREMENT = {
+	bearer: { bearer: [] },
+	session: { session: [] },
+	"control-plane": { controlPlane: [] },
+	public: {}
+};
+const ERROR_RESPONSE = "Error";
+/** Hono's `/a/:id{[0-9]+}/*` as OpenAPI's `/a/{id}/{path}`. */
+function openApiPath(path) {
+	return path.replace(/:([A-Za-z0-9_]+)(\{[^}]*\})?\??/g, "{$1}").replace(/\/\*$/, "/{path}").replace(/\*/g, "{path}");
+}
+/**
+* `get` + `/leaderboard/{board}/top` → `getLeaderboardByBoardTop`. A parameter reads as `By<Name>`, so
+* `/items/{id}` and `/items/id` do not meet. Stable, but not unique on its own — `/a-b` and `/a/b` still
+* share one — so {@link openApiDocument} numbers a repeat rather than writing an invalid document.
+*/
+function operationId(method, path) {
+	const words = path.split("/").flatMap((segment) => {
+		const param = /^\{(.+)\}$/.exec(segment);
+		return param ? ["by", ...(param[1] ?? "").split(/[^A-Za-z0-9]+/)] : segment.split(/[^A-Za-z0-9]+/);
+	}).filter((word) => word.length > 0).map((word) => `${word[0]?.toUpperCase()}${word.slice(1)}`);
+	return `${method.toLowerCase()}${words.join("")}`;
+}
+/** A Zod schema as JSON Schema, without the `$schema` key OpenAPI does not want inside a document. */
+function jsonSchema(schema, io) {
+	const { $schema: _dialect, ...rest } = z.toJSONSchema(schema, {
+		io,
+		unrepresentable: "any"
+	});
+	return rest;
+}
+function operationsOf(routes) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = `${route.method} ${route.path}`;
+		const entry = byKey.get(key) ?? {
+			method: route.method,
+			path: route.path,
+			handlers: []
+		};
+		entry.handlers.push(route.handler);
+		byKey.set(key, entry);
+	}
+	return [...byKey.values()];
+}
+/**
+* An `ALL` entry with no spec is `app.use` — middleware, not a route — because Hono records both as
+* `ALL`. An `app.all` route that forgot its `describeRoute` is therefore invisible to the coverage
+* check, which is the one blind spot here; the kit has one such route and it is described.
+*/
+function isMiddlewareOnly(operation) {
+	return operation.method === "ALL" && !operation.handlers.some((handler) => routeSpecOf(handler));
+}
+/** Every route in these groups that registered no `describeRoute`. Empty is the contract being met. */
+function undescribedRoutes(groups) {
+	return groups.flatMap((group) => operationsOf(group.routes).filter((operation) => !isMiddlewareOnly(operation)).filter((operation) => !operation.handlers.some((handler) => routeSpecOf(handler))).map(({ method, path }) => ({
+		method,
+		path
+	})));
+}
+/** The parameters one validator contributes: one per property of its object schema. */
+function parametersOf(contract) {
+	const location = {
+		param: "path",
+		query: "query",
+		header: "header",
+		cookie: "cookie"
+	}[contract.target];
+	if (location === void 0) return [];
+	const schema = jsonSchema(contract.schema, "input");
+	const properties = schema.properties ?? {};
+	const required = new Set(schema.required ?? []);
+	return Object.entries(properties).map(([name, property]) => {
+		const { description, ...rest } = property;
+		return {
+			name,
+			in: location,
+			required: location === "path" || required.has(name),
+			...typeof description === "string" ? { description } : {},
+			schema: rest
+		};
+	});
+}
+/** The request body one validator contributes, if it reads the body. */
+function requestBodyOf(contract) {
+	const media = {
+		json: "application/json",
+		form: "multipart/form-data"
+	}[contract.target];
+	if (media === void 0) return void 0;
+	const schema = jsonSchema(contract.schema, "input");
+	return {
+		required: !contract.schema.safeParse(void 0).success,
+		...typeof schema.description === "string" ? { description: schema.description } : {},
+		content: { [media]: { schema } }
+	};
+}
+function isZodSchema(value) {
+	return value instanceof z.ZodType;
+}
+/** One `responses` entry. A bare schema is a JSON body; a {@link RouteResponse} says what it is. */
+function responseOf(declared) {
+	if (isZodSchema(declared)) {
+		const schema = jsonSchema(declared, "input");
+		return {
+			description: typeof schema.description === "string" ? schema.description : "Success.",
+			content: { "application/json": { schema } }
+		};
+	}
+	const media = declared.contentType ?? (declared.schema ? "application/json" : void 0);
+	return {
+		description: declared.description,
+		...media === void 0 ? {} : { content: { [media]: { schema: declared.schema ? jsonSchema(declared.schema, "input") : {} } } }
+	};
+}
+function strategiesOf(spec) {
+	return typeof spec.verification === "string" ? [spec.verification] : spec.verification;
+}
+/** One OpenAPI operation for a described route. */
+function operationOf(tag, method, operation, spec) {
+	const contracts = operation.handlers.flatMap((handler) => {
+		const contract = requestContractOf(handler);
+		return contract ? [contract] : [];
+	});
+	const parameters = contracts.flatMap(parametersOf);
+	for (const name of pathParams(operation.path)) if (!parameters.some((parameter) => parameter.in === "path" && parameter.name === name)) parameters.push({
+		name,
+		in: "path",
+		required: true,
+		schema: { type: "string" }
+	});
+	if (/\*/.test(operation.path)) parameters.push({
+		name: "path",
+		in: "path",
+		required: true,
+		description: "The rest of the path, passed through to the handler.",
+		schema: { type: "string" }
+	});
+	const body = contracts.map(requestBodyOf).find((candidate) => candidate !== void 0);
+	const strategies = strategiesOf(spec);
+	const security = strategies.flatMap((strategy) => {
+		const requirement = REQUIREMENT[strategy];
+		return requirement === void 0 ? [] : [requirement];
+	});
+	const responses = {};
+	for (const [status, declared] of Object.entries(spec.responses)) responses[status] = responseOf(declared);
+	responses.default = { $ref: `#/components/responses/${ERROR_RESPONSE}` };
+	return {
+		tags: [tag],
+		operationId: operationId(method, openApiPath(operation.path)),
+		summary: spec.summary,
+		...spec.description === void 0 ? {} : { description: spec.description },
+		...parameters.length === 0 ? {} : { parameters },
+		...body === void 0 ? {} : { requestBody: body },
+		responses,
+		...strategies.length === 0 ? {} : {
+			security,
+			"x-pithy-verification": strategies
+		},
+		...spec.scopes === void 0 || spec.scopes.length === 0 ? {} : { "x-pithy-scopes": spec.scopes }
+	};
+}
+/** The methods an operation is documented under: its own, or for `app.all` the ones its spec names. */
+function methodsOf(operation, spec) {
+	if (operation.method !== "ALL") return [operation.method.toLowerCase()];
+	return spec.methods ?? ["get", "post"];
+}
+/** The spec an undescribed route is written with under `undescribed: "include"`. It claims nothing. */
+const UNDESCRIBED = {
+	summary: "Not described. Add describeRoute to this route.",
+	verification: [],
+	responses: {}
+};
+/**
+* The OpenAPI document for these route groups. Undescribed routes are left out rather than guessed at,
+* unless {@link DocumentOptions.undescribed} says otherwise; {@link undescribedRoutes} is the check that
+* keeps that set empty.
+*/
+function openApiDocument(info, groups, options = {}) {
+	const paths = {};
+	const tags = [];
+	const ids = /* @__PURE__ */ new Map();
+	/** An operation id no earlier operation took: the derived one, or it with the next free number. */
+	const unique = (id) => {
+		const seen = ids.get(id) ?? 0;
+		ids.set(id, seen + 1);
+		return seen === 0 ? id : `${id}${seen + 1}`;
+	};
+	for (const group of groups) {
+		let documented = false;
+		for (const operation of operationsOf(group.routes)) {
+			if (isMiddlewareOnly(operation)) continue;
+			const declared = operation.handlers.map(routeSpecOf).find((candidate) => candidate !== void 0);
+			if (declared === void 0 && options.undescribed !== "include") continue;
+			const spec = declared ?? UNDESCRIBED;
+			documented = true;
+			const path = openApiPath(operation.path);
+			const item = paths[path] ?? {};
+			for (const method of methodsOf(operation, spec)) {
+				const derived = operationOf(group.tag, method, operation, spec);
+				const written = {
+					...derived,
+					operationId: unique(String(derived.operationId))
+				};
+				item[method] = declared === void 0 ? {
+					...written,
+					"x-pithy-undescribed": true
+				} : written;
+			}
+			paths[path] = item;
+		}
+		if (documented) tags.push({
+			name: group.tag,
+			...group.description ? { description: group.description } : {}
+		});
+	}
+	return {
+		openapi: OPENAPI_VERSION,
+		info,
+		tags,
+		paths,
+		components: {
+			schemas: { [ERROR_RESPONSE]: jsonSchema(ErrorBody, "input") },
+			responses: { [ERROR_RESPONSE]: {
+				description: "Any failure. The status is the error's own; the body is always this shape.",
+				content: { "application/json": { schema: { $ref: `#/components/schemas/${ERROR_RESPONSE}` } } }
+			} },
+			securitySchemes: SECURITY_SCHEMES
+		}
+	};
+}
+const escapePointer = (segment) => segment.replaceAll("~", "~0").replaceAll("/", "~1");
+/**
+* Every object property and every parameter in the document without a description. The kit holds every
+* Zod field to `.describe()`, and this is how that rule is checked on the wire shape a client actually
+* generates from, rather than on the source it came from.
+*/
+function undescribedFields(document) {
+	return undescribedFieldsIn(document.paths, "/paths");
+}
+/**
+* The same sweep over any part of a contract document, from a JSON pointer: every object property and every
+* OpenAPI parameter below `node` without a description. The AsyncAPI document runs it over its messages.
+*/
+function undescribedFieldsIn(node, at) {
+	const found = [];
+	const visit = (node, pointer) => {
+		if (Array.isArray(node)) {
+			node.forEach((child, index) => {
+				visit(child, `${pointer}/${index}`);
+			});
+			return;
+		}
+		if (node === null || typeof node !== "object") return;
+		const record = node;
+		if (typeof record.in === "string" && typeof record.name === "string" && typeof record.description !== "string") found.push({ pointer });
+		const properties = record.properties;
+		if (properties !== null && typeof properties === "object" && !Array.isArray(properties)) {
+			for (const [name, property] of Object.entries(properties)) if (!(property !== null && typeof property === "object" && typeof property.description === "string")) found.push({ pointer: `${pointer}/properties/${escapePointer(name)}` });
+		}
+		for (const [key, child] of Object.entries(record)) visit(child, `${pointer}/${escapePointer(key)}`);
+	};
+	visit(node, at);
+	return found;
+}
+//#endregion
+export { OPENAPI_VERSION, jsonSchema, openApiDocument, openApiPath, operationId, undescribedFields, undescribedFieldsIn, undescribedRoutes };

package/dist/openapi/routeGroups.d.ts

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { RouteGroup } from "./document";
+/** Note the route groups of an assembled app. Called by `createBackend` and nothing else. */
+export declare function recordRouteGroups(app: object, groups: readonly RouteGroup[]): void;
+/** The route groups `createBackend` recorded for this app, or `undefined` for an app it did not assemble. */
+export declare function routeGroupsOf(app: object): readonly RouteGroup[] | undefined;
+//# sourceMappingURL=routeGroups.d.ts.map

package/dist/openapi/routeGroups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeGroups.d.ts","sourceRoot":"","sources":["../../src/openapi/routeGroups.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAa7C,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAElF;AAED,6GAA6G;AAC7G,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,CAE5E"}

package/dist/openapi/routeGroups.js

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/openapi/routeGroups.ts
+/**
+* Which capability registered which routes, recorded by `createBackend` as it mounts them.
+*
+* Every capability registers onto the one shared app with absolute paths, so the finished route table
+* says nothing about who owns a route. `createBackend` is the one place that knows — it calls each
+* `routes` hook in turn — so it notes the slice of `app.routes` each hook added, and the contract tags
+* each operation with the capability that owns it. Held beside the app rather than on it, so the app a
+* Worker exports is the plain Hono instance it always was.
+*/
+const recorded = /* @__PURE__ */ new WeakMap();
+/** Note the route groups of an assembled app. Called by `createBackend` and nothing else. */
+function recordRouteGroups(app, groups) {
+	recorded.set(app, groups);
+}
+/** The route groups `createBackend` recorded for this app, or `undefined` for an app it did not assemble. */
+function routeGroupsOf(app) {
+	return recorded.get(app);
+}
+//#endregion
+export { recordRouteGroups, routeGroupsOf };

package/dist/text/comments.js

@@ -82,9 +82,18 @@ function blankCommentsAndStrings(source) {
 }
 /** The one walk behind both: comments always blanked, a quoted run kept or blanked inside its delimiters. */
 function blank(source, strings) {
+	return walkCode(source, 0, strings, false).out;
+}
+/**
+* Walk code from `start`. Inside an interpolation (`nested`), the `}` that closes it ends the walk, and is
+* included. A template is walked by {@link walkTemplate}, which walks each of its interpolations as code in turn
+* — so a comment inside `${…}` is blanked like any other, and a template inside one closes nothing (#711).
+*/
+function walkCode(source, start, strings, nested) {
 	let out = "";
 	let previous = "";
-	let index = 0;
+	let depth = 0;
+	let index = start;
 	while (index < source.length) {
 		const char = source[index];
 		const pair = source.slice(index, index + 2);
@@ -94,8 +103,15 @@ function blank(source, strings) {
 			index = stop;
 			continue;
 		}
-		if (char === "\"" || char === "'" || char === "`") {
-			const stop = endOfQuoted(source, index, char, char !== "`");
+		if (char === "`") {
+			const walked = walkTemplate(source, index, strings);
+			out += walked.out;
+			index = walked.end;
+			previous = char;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			const stop = endOfQuoted(source, index, char, true);
 			const run = source.slice(index, stop);
 			out += strings ? blankInside(run, char) : run;
 			index = stop;
@@ -109,11 +125,57 @@ function blank(source, strings) {
 			previous = "/";
 			continue;
 		}
+		if (char === "{") depth += 1;
+		if (char === "}") {
+			if (nested && depth === 0) return {
+				out: `${out}}`,
+				end: index + 1
+			};
+			depth -= 1;
+		}
 		out += char;
 		if (!/\s/.test(char)) previous = char;
 		index += 1;
 	}
-	return out;
+	return {
+		out,
+		end: index
+	};
+}
+/**
+* Walk one template literal from its opening backtick. Its text is kept, or blanked whole — `${}` included — when
+* `strings` asks; each interpolation is walked as code, so its comments are blanked and its own templates close
+* nothing. Returns the text and the index past the closing backtick.
+*/
+function walkTemplate(source, start, strings) {
+	let out = "`";
+	let index = start + 1;
+	while (index < source.length) {
+		const char = source[index];
+		if (char === "\\") {
+			const escaped = source.slice(index, index + 2);
+			out += strings ? escaped.replace(/[^\n]/g, " ") : escaped;
+			index += 2;
+			continue;
+		}
+		if (char === "`") return {
+			out: `${out}\``,
+			end: index + 1
+		};
+		if (char === "$" && source[index + 1] === "{") {
+			const walked = walkCode(source, index + 2, strings, true);
+			const text = `\${${walked.out}`;
+			out += strings ? text.replace(/[^\n]/g, " ") : text;
+			index = walked.end;
+			continue;
+		}
+		out += strings && char !== "\n" ? " " : char;
+		index += 1;
+	}
+	return {
+		out,
+		end: index
+	};
 }
 /** A quoted run with everything between its delimiters blanked, newlines kept. An unterminated run has no closer. */
 function blankInside(run, quote) {

package/dist/text/literals.d.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * **Every string a source file writes, as it reads at run time near enough to scan (#711)** — each quoted or
+ * template literal's text, quotes off, escapes resolved to the character they stand for, and every `${…}` blanked
+ * to `<x>`.
+ *
+ * Gates that read what the code *says* — `packages/cli/src/ci/runnableCommands.test.ts` reads every `pithy …` a
+ * line names — used one regular expression for "a string or template literal", and it has a measured false
+ * reading: a template whose interpolation holds a template of its own, `` `${path}${detail ? ` — ${detail}` :
+ * ""}` ``, closed at the inner backtick, and everything after it was read as a literal that opened there. The
+ * scan then reported text the file does not contain, and missed the text it does. So this walks the source and
+ * keeps a stack: a `${` opens an expression, whose own literals are read as literals in their turn, and its
+ * matching `}` resumes the template it interrupted.
+ *
+ * Comments must be blanked first (`./comments`), as every caller here already does. A regex literal is stepped
+ * over by the same rule `./comments` uses — a `/` where a value may begin opens one — so a quote inside a pattern
+ * does not open a string.
+ */
+export declare function literalTexts(source: string, options?: LiteralOptions): string[];
+/** How a source is read. */
+export interface LiteralOptions {
+    /**
+     * The source is a `.tsx` file: an element's text and its attribute strings are read as literals too, and a
+     * `<` where a value may begin opens an element rather than comparing. A JSX text run is read with its
+     * whitespace collapsed, as React renders it; a `{…}` child is `<x>`.
+     */
+    readonly jsx?: boolean;
+}
+/** One literal: its text as {@link literalTexts} reads it, and the source range it spans, delimiters included. */
+export interface LiteralSpan {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+    /** A template's interpolations, each the range of the code between `${` and `}`. Absent for any other literal. */
+    readonly holes?: readonly (readonly [number, number])[];
+}
+/**
+ * {@link literalTexts}, with where each one sits — so a gate can read what is around a literal: a `+` beside it, or
+ * the array it is an element of being joined.
+ */
+export declare function literalSpans(source: string, options?: LiteralOptions): LiteralSpan[];
+//# sourceMappingURL=literals.d.ts.map

package/dist/text/literals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literals.d.ts","sourceRoot":"","sources":["../../src/text/literals.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,EAAE,CAEnF;AAED,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,kHAAkH;AAClH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kHAAkH;IAClH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CACzD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,WAAW,EAAE,CAIxF"}