@pithy-sh/vite 0.1.1 → 0.1.3

package/dist/clientEnvDeclaration.d.ts

@@ -0,0 +1,102 @@
+/**
+ * **`client-env.d.ts` is generated from the four declared client projections (#398).**
+ *
+ * `@pithy-sh/ui-react`'s `templates/client-env.d.ts` is the ambient declaration for the four
+ * `virtual:pithy/*` modules, copied into an adopter's Worker by `pithy ui add react`. It used to be
+ * hand-written, three packages away from the `client:` projections that produce the values it
+ * describes, and #392 held the two together with a spawned compiler because there was no faithful
+ * source to generate from: `Capability.client` is typed `(context) => ClientProjection`, so each
+ * capability's real shape existed only as an inferred literal inside a closure.
+ *
+ * #395 removed that. The four capabilities now declare their projection types, and the declaration is
+ * the source of truth rather than a restatement of the literal. So there is exactly one statement of
+ * each shape, and this module copies it — **a gate that watches two things agree is strictly worse
+ * than one thing.**
+ *
+ * ## Why the declared type is copied as text rather than re-printed from a type
+ *
+ * Because the doc comments are half of what the file is worth. A declaration emitted from a resolved
+ * type carries the shape and loses every sentence attached to it, and those sentences are what tell a
+ * screen that `action` must be rendered and never retyped, or that a Paddle client token is
+ * publishable by design. Copying the type node's own source text keeps the unions, the `| null` arms
+ * and the prose exactly as the capability wrote them.
+ *
+ * The one thing that is *not* copied is what is not a shape at all — see {@link PREAMBLE} and
+ * {@link ENABLED_EXPORT}, both of which are policy and are written as fixed text.
+ *
+ * ## Nothing an adopter runs
+ *
+ * The kit generates at its own build time and commits the artifact. `pithy ui add react` still copies
+ * a plain static `.d.ts` into a Worker, and a scaffolded project typechecks with no new step.
+ */
+/** One `virtual:pithy/*` module, and the declared type that is its whole shape. */
+export interface DeclaredModule {
+    /** The capability name — the segment after `virtual:pithy/`. */
+    readonly module: string;
+    /** The specifier the projection is read from. Resolved through the package's own exports map. */
+    readonly specifier: string;
+    /** The exported type alias that declares what a browser receives. */
+    readonly type: string;
+}
+/**
+ * The modules the declaration covers, in the order they are emitted.
+ *
+ * This list is the whole reach of the generated file: a further capability projecting to a browser is
+ * a further entry here, and until it is one, nothing declares it. The specifiers resolve because each
+ * capability is a devDependency of `@pithy-sh/vite` — a build-time dependency, like the compiler. An
+ * adopter installs none of them to use the plugin, and never runs this module.
+ */
+export declare const DECLARED_MODULES: readonly DeclaredModule[];
+/**
+ * The source text of every top-level `export type X = …;` in a module, keyed by name.
+ *
+ * The value is the type node's own text, verbatim: every doc comment, every union arm, every `| null`
+ * exactly as written. It is found by scanning for the `;` that closes the alias at bracket depth zero,
+ * over code characters only.
+ */
+export declare function parseTypeAliases(source: string): Map<string, string>;
+/**
+ * Replace every reference to a sibling type alias with that alias's own text, re-indented to sit where
+ * the reference did.
+ *
+ * `PaymentsClientProduct` is the only one today, and it is named rather than inlined at the source for
+ * a reason #395 recorded — the annotation goes on the `.map` callback, where a fresh literal is still
+ * checked in both directions. The declaration an adopter reads has no such seam to hang a name on, so
+ * the shape is written where it is used.
+ */
+export declare function inlineAliases(text: string, aliases: ReadonlyMap<string, string>, seen?: readonly string[]): string;
+/** One `declare module "virtual:pithy/<module>"` block, fixed text and declared shape together. */
+export declare function renderModule(module: string, declaredType: string): string;
+/**
+ * The whole file, from each module's projection source.
+ *
+ * Pure, and the module list is an argument, so the test can hand it a projection this repository does
+ * not contain and read what came out. A generator asserted only against the real four would pass just
+ * as well if it ignored them and printed a constant.
+ */
+export declare function renderClientEnv(sources: ReadonlyMap<string, string>, modules?: readonly DeclaredModule[]): string;
+/**
+ * Read the four projections' sources through their own packages' exports maps.
+ *
+ * **Resolved, then mirrored back to `src` — Jim, #476.** Until every package shipped a build,
+ * `@pithy-sh/auth/src/client/projection` resolved to the TypeScript itself. It resolves to
+ * `dist/client/projection.js` now, where the types are stripped and `AuthClientProjection` does not
+ * exist, so the resolved path is walked back to the module it was emitted from.
+ *
+ * The declaration beside it, `dist/client/projection.d.ts`, is the other candidate and was tried first.
+ * It is arguably the more truthful input — it is the type an adopter can actually see — but it makes
+ * this generator's build wait on five capability packages' builds, and `@pithy-sh/vite` depends on none
+ * of them. That is five cross-package `dependsOn` edges in `turbo.jsonc` that a sixth capability's
+ * projection would silently need and silently not have: the generator would read a stale declaration,
+ * emit a stale template, and say nothing. Source has no such ordering, `turbo.jsonc` already names
+ * every `packages/<name>/src/client/projection.ts` as this build's input, and the authored text is
+ * what the file's own header promises an adopter is emitted verbatim.
+ *
+ * `dist/x.js` → `src/x.ts` is not a guess about the layout: `tsdown` and `tsc -p tsconfig.build.json`
+ * both mirror `src/` into `dist/`, so the two are the same path under a different root, and
+ * `packaging.test.ts` fails on any published module missing either half.
+ */
+export declare function readProjectionSources(): Promise<Map<string, string>>;
+/** The declaration as it should be on disk. What `bun run generate` writes and the gate compares. */
+export declare function generateClientEnv(): Promise<string>;
+//# sourceMappingURL=clientEnvDeclaration.d.ts.map

package/dist/clientEnvDeclaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientEnvDeclaration.d.ts","sourceRoot":"","sources":["../src/clientEnvDeclaration.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAMrD,CAAC;AAuGF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBpE;AAQD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,IAAI,GAAE,SAAS,MAAM,EAAO,GAC3B,MAAM,CAiBR;AA2CD,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAUzE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,OAAO,GAAE,SAAS,cAAc,EAAqB,GACpD,MAAM,CAYR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAS1E;AAED,qGAAqG;AACrG,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEzD"}

package/dist/clientEnvDeclaration.js

@@ -0,0 +1,299 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region src/clientEnvDeclaration.ts
+/**
+* The modules the declaration covers, in the order they are emitted.
+*
+* This list is the whole reach of the generated file: a further capability projecting to a browser is
+* a further entry here, and until it is one, nothing declares it. The specifiers resolve because each
+* capability is a devDependency of `@pithy-sh/vite` — a build-time dependency, like the compiler. An
+* adopter installs none of them to use the plugin, and never runs this module.
+*/
+const DECLARED_MODULES = [
+	{
+		module: "auth",
+		specifier: "@pithy-sh/auth/src/client/projection",
+		type: "AuthClientProjection"
+	},
+	{
+		module: "i18n",
+		specifier: "@pithy-sh/i18n/src/client/projection",
+		type: "I18nClientProjection"
+	},
+	{
+		module: "payments",
+		specifier: "@pithy-sh/payments/src/client/projection",
+		type: "PaymentsClientProjection"
+	},
+	{
+		module: "support",
+		specifier: "@pithy-sh/support/src/client/projection",
+		type: "SupportClientProjection"
+	},
+	{
+		module: "turnstile",
+		specifier: "@pithy-sh/turnstile/src/client/projection",
+		type: "TurnstileClientProjection"
+	}
+];
+/**
+* **Fixed text, item one: the preamble.**
+*
+* The `vite/client` reference and the paragraph explaining why the default export is a union are
+* policy about how the modules are consumed, not a projection of anything, so there is nothing to
+* derive them from. They are written here.
+*/
+const PREAMBLE = `/// <reference types="vite/client" />
+
+// The client-safe projection of this worker's composed capabilities, served by @pithy-sh/vite.
+//
+// Each module is a DEFAULT export whose type is a union discriminated on \`enabled\`. That shape is
+// deliberate. A capability that is not composed projects \`{ enabled: false }\` and nothing else, so a
+// NAMED import of any other key would be a missing export and the build would fail — on exactly the
+// case this mechanism exists to make survivable. Importing the default and narrowing cannot fail:
+//
+//   import turnstile from "virtual:pithy/turnstile";
+//   if (!turnstile.enabled) return null;   // narrowed: sitekey, mode and token exist below this line
+//
+// The \`virtual:pithy/*\` modules are never written to disk. These declarations describe modules the
+// Vite plugin serves, built from the Worker's own pithy.config.ts.
+//
+// **Generated, and copied here as it was emitted (#398).** Each declaration below is a capability's
+// declared client projection — \`src/client/projection.ts\` in @pithy-sh/auth, @pithy-sh/payments,
+// @pithy-sh/support and @pithy-sh/turnstile — written out by @pithy-sh/vite's
+// \`src/clientEnvDeclaration.ts\` at kit build time. In the kit that is one statement of each shape and
+// nothing to keep in step: a field a projection stops emitting is a compile error where it is
+// projected, and this file moves in the same commit.
+//
+// In your repository it is yours, like every other seeded file. Editing it changes what your compiler
+// believes and nothing about what the plugin serves.
+`;
+/**
+* **Fixed text, item two: the one named export.**
+*
+* `enabled` is declared alone on purpose, and the refusal is the feature. A capability nobody composed
+* serves `{ enabled: false }` and nothing else, so `import { sitekey } from "virtual:pithy/turnstile"`
+* has to fail the build — on exactly the case the union exists to make survivable. Deriving the named
+* exports from the projection's keys would declare every one of them and take that refusal away.
+*/
+const ENABLED_EXPORT = `  /**
+   * Whether this capability is composed and serving on this worker. Also the union's discriminant.
+   *
+   * The only named export, deliberately. Every other key is reached through the default export and a
+   * narrowing — see the note at the top of this file.
+   */
+  export const enabled: boolean;
+`;
+/**
+* Which characters of a TypeScript source are code — everything outside a comment or a string.
+*
+* Both passes below need it, and for the same reason: a brace in `` `POST {basePath}/feedback` `` and
+* a type name in an `{@link …}` tag are text, and counting or rewriting them would be a silent wrong
+* answer rather than an error. Template literals with `${}` substitutions are not handled, because a
+* type position cannot hold one — `parseTypeAliases` refuses anything it cannot finish instead.
+*/
+function codeMask(source) {
+	const mask = new Array(source.length).fill(true);
+	let index = 0;
+	while (index < source.length) {
+		if (source.startsWith("//", index)) {
+			while (index < source.length && source[index] !== "\n") mask[index++] = false;
+			continue;
+		}
+		if (source.startsWith("/*", index)) {
+			const close = source.indexOf("*/", index + 2);
+			const stop = close === -1 ? source.length : close + 2;
+			while (index < stop) mask[index++] = false;
+			continue;
+		}
+		const quote = source[index];
+		if (quote === "\"" || quote === "'" || quote === "`") {
+			mask[index++] = false;
+			while (index < source.length) {
+				const char = source[index];
+				mask[index++] = false;
+				if (char === "\\") {
+					if (index < source.length) mask[index++] = false;
+					continue;
+				}
+				if (char === quote) break;
+			}
+			continue;
+		}
+		index += 1;
+	}
+	return mask;
+}
+/**
+* An identifier, wherever one may start, and the head of a top-level exported type alias.
+*
+* Both are built per call rather than shared. A `g` flag carries `lastIndex` between uses, and
+* {@link inlineAliases} recurses — one shared instance would have an inner call move the outer's
+* cursor, which reads as a reference the generator simply skipped.
+*/
+const identifierPattern = () => /[A-Za-z_$][A-Za-z0-9_$]*/g;
+const typeAliasPattern = () => /^export type ([A-Za-z_$][A-Za-z0-9_$]*)\s*=/gm;
+/**
+* The source text of every top-level `export type X = …;` in a module, keyed by name.
+*
+* The value is the type node's own text, verbatim: every doc comment, every union arm, every `| null`
+* exactly as written. It is found by scanning for the `;` that closes the alias at bracket depth zero,
+* over code characters only.
+*/
+function parseTypeAliases(source) {
+	const mask = codeMask(source);
+	const aliases = /* @__PURE__ */ new Map();
+	const pattern = typeAliasPattern();
+	for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+		const [head, name] = match;
+		const start = match.index;
+		if (!mask[start] || !name) continue;
+		const from = start + head.length;
+		let depth = 0;
+		let end = -1;
+		for (let index = from; index < source.length; index += 1) {
+			if (!mask[index]) continue;
+			const char = source[index];
+			if (char === "{" || char === "(" || char === "[") depth += 1;
+			else if (char === "}" || char === ")" || char === "]") depth -= 1;
+			else if (char === ";" && depth === 0) {
+				end = index;
+				break;
+			}
+		}
+		if (end === -1) throw new Error(`\`export type ${name}\` is never closed by a \`;\` at depth zero.`);
+		aliases.set(name, source.slice(from, end));
+	}
+	return aliases;
+}
+/** The leading spaces of the line `index` falls on. What an inlined alias has to be pushed out by. */
+function indentAt(text, index) {
+	const lineStart = text.lastIndexOf("\n", index - 1) + 1;
+	return /^[ ]*/.exec(text.slice(lineStart, index))?.[0] ?? "";
+}
+/**
+* Replace every reference to a sibling type alias with that alias's own text, re-indented to sit where
+* the reference did.
+*
+* `PaymentsClientProduct` is the only one today, and it is named rather than inlined at the source for
+* a reason #395 recorded — the annotation goes on the `.map` callback, where a fresh literal is still
+* checked in both directions. The declaration an adopter reads has no such seam to hang a name on, so
+* the shape is written where it is used.
+*/
+function inlineAliases(text, aliases, seen = []) {
+	const mask = codeMask(text);
+	const parts = [];
+	let cursor = 0;
+	const pattern = identifierPattern();
+	for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+		const name = match[0];
+		const body = aliases.get(name);
+		if (body === void 0 || !mask[match.index]) continue;
+		if (seen.includes(name)) throw new Error(`\`${name}\` refers to itself through ${seen.join(" → ")}.`);
+		const indent = indentAt(text, match.index);
+		const inlined = inlineAliases(body, aliases, [...seen, name]);
+		parts.push(text.slice(cursor, match.index), reindent(inlined.trim(), indent));
+		cursor = match.index + name.length;
+	}
+	parts.push(text.slice(cursor));
+	return parts.join("");
+}
+/** Push every line but the first out by `indent`. The first is already sitting where it was written. */
+function reindent(text, indent) {
+	return text.split("\n").map((line, position) => position === 0 || line === "" ? line : `${indent}${line}`).join("\n");
+}
+/**
+* Move a block from the column it was written at to the one it is emitted at.
+*
+* The alias text arrives at whatever depth its file put it — `tsc` prints a union's arms at zero and
+* their members at four — and inside a `declare module` block those want four and eight. So the block
+* is dedented to column zero and then pushed out uniformly, which keeps every relative depth, including
+* the ` *` continuation of a doc comment.
+*
+* **The first line is trimmed rather than measured, and the rest are dedented by their common indent.**
+* A type alias's body begins on the `=` line, so its first line arrives as `{` behind a single space
+* that says nothing about the block's depth. Taking that space as the base — which is what this did
+* until #476 changed the input from source to emitted declaration — shifted every following line one
+* column left of where it belonged, and the misalignment was invisible in the old input only because a
+* hand-written union happened to start on a line of its own.
+*/
+function shift(text, indent) {
+	const lines = text.split("\n");
+	while (lines.length > 0 && (lines[0] ?? "").trim() === "") lines.shift();
+	while (lines.length > 0 && (lines.at(-1) ?? "").trim() === "") lines.pop();
+	const base = lines.slice(1).filter((line) => line.trim() !== "").reduce((width, line) => Math.min(width, (/^[ ]*/.exec(line)?.[0] ?? "").length), Infinity);
+	const dedent = Number.isFinite(base) ? base : 0;
+	return lines.map((line, position) => {
+		if (line.trim() === "") return "";
+		return `${indent}${position === 0 ? line.trim() : line.slice(dedent)}`;
+	}).join("\n");
+}
+/** One `declare module "virtual:pithy/<module>"` block, fixed text and declared shape together. */
+function renderModule(module, declaredType) {
+	return [
+		`declare module "virtual:pithy/${module}" {`,
+		ENABLED_EXPORT,
+		"  const config:",
+		`${shift(declaredType, "    ")};`,
+		"  export default config;",
+		"}",
+		""
+	].join("\n");
+}
+/**
+* The whole file, from each module's projection source.
+*
+* Pure, and the module list is an argument, so the test can hand it a projection this repository does
+* not contain and read what came out. A generator asserted only against the real four would pass just
+* as well if it ignored them and printed a constant.
+*/
+function renderClientEnv(sources, modules = DECLARED_MODULES) {
+	const blocks = [];
+	for (const declared of modules) {
+		const source = sources.get(declared.module);
+		if (source === void 0) throw new Error(`No projection source for virtual:pithy/${declared.module}.`);
+		const aliases = parseTypeAliases(source);
+		const body = aliases.get(declared.type);
+		if (body === void 0) throw new Error(`${declared.specifier} exports no type \`${declared.type}\`.`);
+		aliases.delete(declared.type);
+		blocks.push(renderModule(declared.module, inlineAliases(body, aliases)));
+	}
+	return `${PREAMBLE}\n${blocks.join("\n")}`;
+}
+/**
+* Read the four projections' sources through their own packages' exports maps.
+*
+* **Resolved, then mirrored back to `src` — Jim, #476.** Until every package shipped a build,
+* `@pithy-sh/auth/src/client/projection` resolved to the TypeScript itself. It resolves to
+* `dist/client/projection.js` now, where the types are stripped and `AuthClientProjection` does not
+* exist, so the resolved path is walked back to the module it was emitted from.
+*
+* The declaration beside it, `dist/client/projection.d.ts`, is the other candidate and was tried first.
+* It is arguably the more truthful input — it is the type an adopter can actually see — but it makes
+* this generator's build wait on five capability packages' builds, and `@pithy-sh/vite` depends on none
+* of them. That is five cross-package `dependsOn` edges in `turbo.jsonc` that a sixth capability's
+* projection would silently need and silently not have: the generator would read a stale declaration,
+* emit a stale template, and say nothing. Source has no such ordering, `turbo.jsonc` already names
+* every `packages/<name>/src/client/projection.ts` as this build's input, and the authored text is
+* what the file's own header promises an adopter is emitted verbatim.
+*
+* `dist/x.js` → `src/x.ts` is not a guess about the layout: `tsdown` and `tsc -p tsconfig.build.json`
+* both mirror `src/` into `dist/`, so the two are the same path under a different root, and
+* `packaging.test.ts` fails on any published module missing either half.
+*/
+async function readProjectionSources() {
+	const sources = /* @__PURE__ */ new Map();
+	for (const declared of DECLARED_MODULES) {
+		const built = fileURLToPath(import.meta.resolve(declared.specifier));
+		const source = built.replace(/([\\/])dist\1(.+)\.js$/, "$1src$1$2.ts");
+		if (source === built) throw new Error(`${declared.specifier} did not resolve into a build: ${built}`);
+		sources.set(declared.module, await readFile(source, "utf8"));
+	}
+	return sources;
+}
+/** The declaration as it should be on disk. What `bun run generate` writes and the gate compares. */
+async function generateClientEnv() {
+	return renderClientEnv(await readProjectionSources());
+}
+//#endregion
+export { DECLARED_MODULES, generateClientEnv, inlineAliases, parseTypeAliases, readProjectionSources, renderClientEnv, renderModule };

package/dist/devOrigin.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The slice of `@cloudflare/vite-plugin`'s worker config this touches.
+ *
+ * Structural rather than imported. `@pithy-sh/vite` does not depend on that plugin — an adopter picks
+ * its own version — and naming one field is enough to be checked against it at the call site, where the
+ * real type applies.
+ */
+export interface WorkerVars {
+    /** The Worker's plain environment variables, as `wrangler.jsonc` declared them. */
+    vars?: Record<string, WorkerVarValue>;
+}
+/**
+ * What a wrangler `vars` entry may hold — wrangler's own `Json`, restated.
+ *
+ * Restated rather than imported for the reason {@link WorkerVars} is structural, and it has to be this
+ * exact shape rather than `unknown`: the customizer's return type is checked against
+ * `Partial<WorkerConfig>` at the call site, and `Record<string, unknown>` is not assignable to
+ * `Record<string, Json>` — an index signature is invariant. A looser type here compiles in this package
+ * and fails in every adopter's, which is the worst place to find out.
+ */
+export type WorkerVarValue = string | number | boolean | null | WorkerVarValue[] | {
+    [key: string]: WorkerVarValue;
+};
+/**
+ * Give the Worker the origin `pithy dev` allocated this checkout, as `BASE_URL`.
+ *
+ * Spread into `@cloudflare/vite-plugin`'s `config` customizer:
+ *
+ * ```ts
+ * cloudflare({ config: devWorkerConfig() })
+ * ```
+ *
+ * **Why an adopter writes a line at all.** A Worker launched through `wrangler dev` is handed its own
+ * origin on the argv, by `pithy dev`, with nothing to configure. A Worker launched through a custom
+ * `dev.command` is a Vite dev server, and there is no argv to append a `--var` to: `@cloudflare/vite-plugin`
+ * takes the Worker's `vars` from `wrangler.jsonc`, and the only documented way in is this customizer,
+ * which lives in the adopter's `vite.config.ts`. `pithy init` scaffolds it; an existing project adds
+ * the line once and `pithy doctor` says so until it does.
+ *
+ * **Why it has to be given rather than written down.** A dev port is *allocated* — every checkout
+ * reserves its own block — so a `vars.BASE_URL` in `wrangler.jsonc` is right in the first checkout on a
+ * machine and wrong in every other one. That is not cosmetic: `BASE_URL` is the `iss` on every
+ * control-plane token a Worker signs and the origin its callback links are built against, so a second
+ * checkout signed tokens as the first one and its own seam denied every call, 401, with every stored
+ * value agreeing (#462, `pithy-sh/dashboard#95`).
+ *
+ * **Outside `pithy dev` it does nothing at all.** A plain `vite dev`, a build, or CI has no
+ * {@link WORKER_ORIGIN_VAR} in its environment, and the Worker keeps whatever `wrangler.jsonc` says —
+ * which for a deployed environment is the value `applyDomains` generated from `domains`, and is
+ * correct. This never invents an origin; it only passes on one that was allocated.
+ */
+export declare function devWorkerConfig(env?: NodeJS.ProcessEnv): (config: WorkerVars) => WorkerVars;
+//# sourceMappingURL=devOrigin.d.ts.map

package/dist/devOrigin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devOrigin.d.ts","sourceRoot":"","sources":["../src/devOrigin.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,cAAc,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;CAAE,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,CAuBxG"}

package/dist/devOrigin.js

@@ -0,0 +1,45 @@
+import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
+import { ENVIRONMENT_VAR, WORKER_ORIGIN_VAR } from "@pithy-sh/core/src/worker/identity";
+//#region src/devOrigin.ts
+/**
+* Give the Worker the origin `pithy dev` allocated this checkout, as `BASE_URL`.
+*
+* Spread into `@cloudflare/vite-plugin`'s `config` customizer:
+*
+* ```ts
+* cloudflare({ config: devWorkerConfig() })
+* ```
+*
+* **Why an adopter writes a line at all.** A Worker launched through `wrangler dev` is handed its own
+* origin on the argv, by `pithy dev`, with nothing to configure. A Worker launched through a custom
+* `dev.command` is a Vite dev server, and there is no argv to append a `--var` to: `@cloudflare/vite-plugin`
+* takes the Worker's `vars` from `wrangler.jsonc`, and the only documented way in is this customizer,
+* which lives in the adopter's `vite.config.ts`. `pithy init` scaffolds it; an existing project adds
+* the line once and `pithy doctor` says so until it does.
+*
+* **Why it has to be given rather than written down.** A dev port is *allocated* — every checkout
+* reserves its own block — so a `vars.BASE_URL` in `wrangler.jsonc` is right in the first checkout on a
+* machine and wrong in every other one. That is not cosmetic: `BASE_URL` is the `iss` on every
+* control-plane token a Worker signs and the origin its callback links are built against, so a second
+* checkout signed tokens as the first one and its own seam denied every call, 401, with every stored
+* value agreeing (#462, `pithy-sh/dashboard#95`).
+*
+* **Outside `pithy dev` it does nothing at all.** A plain `vite dev`, a build, or CI has no
+* {@link WORKER_ORIGIN_VAR} in its environment, and the Worker keeps whatever `wrangler.jsonc` says —
+* which for a deployed environment is the value `applyDomains` generated from `domains`, and is
+* correct. This never invents an origin; it only passes on one that was allocated.
+*/
+function devWorkerConfig(env = process.env) {
+	return (config) => {
+		const origin = env[WORKER_ORIGIN_VAR];
+		if (origin === void 0 || origin.trim() === "") return {};
+		const environment = config.vars?.[ENVIRONMENT_VAR];
+		if (typeof environment === "string" && environment !== LOCAL_ENVIRONMENT) return {};
+		return { vars: {
+			...config.vars,
+			BASE_URL: origin
+		} };
+	};
+}
+//#endregion
+export { devWorkerConfig };

package/dist/plugin.d.ts

@@ -0,0 +1,105 @@
+/**
+ * What {@link pithy} hands back: a Vite plugin, described without naming a Vite type.
+ *
+ * **The return type used to be Vite's own `Plugin`, and that made the peer range a lie — Jim,
+ * 2026-08-21 (#414).** `package.json` declares `vite: ^6.1.0 || ^7.0.0 || ^8.0.0`, but a `Plugin` in
+ * the signature is a `Plugin` out of *this package's* `node_modules`. An adopter who resolved any
+ * other copy — which is every adopter developing against a symlinked kit, and every adopter whose
+ * install did not deduplicate — had to prove the kit's copy assignable to theirs, field by field,
+ * before `plugins: [pithy()]` would compile. Across majors that comparison fails outright: `hotUpdate`
+ * does not carry the same `this` in 6 as in 8, so this plugin was not a Vite 6 plugin however identical
+ * the hook body is. Within a major it does not even finish — `Plugin` is deep and recursive enough to
+ * exhaust tsc's depth budget, which is the `TS2321: Excessive stack depth` that stopped
+ * `pithy-sh/dashboard` typechecking the `vite.config.ts` `pithy init` had just written for it. A peer
+ * dependency that only compiles when the install deduplicates is not a peer dependency.
+ *
+ * So the signature promises the two things every Vite in that range agrees on and an adopter's
+ * checker can settle in two comparisons: the plugin has a name, and it runs early. No recursion, no
+ * hook signatures, nothing that can differ between two copies of the same library.
+ *
+ * **What is still checked.** The object below is written `satisfies Plugin` against the Vite this
+ * package develops against, so every hook keeps its parameter types, its `this`, and its return type.
+ * A hook that reads the wrong field off `config`, returns the wrong shape, or is spelled with a name
+ * Vite does not call is still a red build — here, where the kit is compiled, and in
+ * `tooling/vite-adopter`, which compiles this file too.
+ *
+ * **What is not.** The adopter's checker no longer re-derives any of that against their copy. It sees
+ * two properties and takes the hooks on trust. Four things pay for that trust and none of them is a
+ * type an adopter has to compare: `tooling/vite-adopter` compiles the return against every major in
+ * the peer range and runs a real `vite build` through the plugin at each of them, {@link
+ * PITHY_PLUGIN_HOOKS} holds every hook name to something all three call, `plugin.test.ts` drives each
+ * hook by hand, and it runs a real `vite build` and reads the bundle.
+ *
+ * **One gap, named rather than papered over — Jim, 2026-08-21.** The hook *signatures* are checked
+ * against one Vite, and there is no arrangement in which they could be checked against three. Vite 8
+ * is rolldown-based and Vite 6 and 7 are rollup-based, so `hotUpdate`'s `this` is
+ * `MinimalPluginContext & { environment: DevEnvironment }` out of two different bundlers — `meta`
+ * carries `rolldownVersion` in one and not the other. A single object cannot be written `satisfies
+ * Plugin` against both; restoring `pithy(): Plugin` reports exactly that at 6.1.6 and 7.0.0, and it is
+ * a fact about the two Vites rather than about this plugin. What is checked across the range is the
+ * hook *set* and the hook *behavior*: a name Vite 6 never calls is a red build, and a build that does
+ * not inline the projection at 6.1.6 is a red test. What is taken on trust across the range is that a
+ * hook Vite 6 calls with an argument of its own shape reaches the same field.
+ *
+ * **Why the floor is `^6.1.0` is not recorded here, because the reason first written down was wrong —
+ * Jim, 2026-08-21.** It said `hotUpdate` arrived in 6.1 and that below it this plugin would be silently
+ * inert. It did not: `npm pack vite@6.0.0` carries `hotUpdate?: ObjectHook<…>` in `index.d.ts`, and its
+ * `HotUpdatePluginContext` is byte-identical to 6.1.6's. The floor may still be right for a reason
+ * nobody has written down, and `6.0.0` is not pinned in `tooling/vite-adopter`, so nothing here has ever
+ * compiled against it.
+ *
+ * Two honest next steps, neither taken in this change: pin `6.0.0` in the fixture and find out, or drop
+ * the floor to `^6.0.0` and let the fixture say whether that holds. **An invented reason is worse than
+ * an absent one**, because the next person reads it instead of measuring.
+ */
+export interface PithyPlugin {
+    /** `"pithy"`. The plugin's identity in Vite's plugin list, and in any error raised from a hook. */
+    name: string;
+    /**
+     * `"pre"`, always. `virtual:pithy/*` is claimed before any other plugin can, so the order of an
+     * adopter's `plugins` array never decides whether the front end can read its own backend.
+     */
+    enforce: "pre";
+}
+/**
+ * Every hook {@link pithy} defines, by name.
+ *
+ * **The one thing about the hooks an adopter's checker can be given for free.** {@link PithyPlugin}
+ * deliberately names no Vite type, so nothing in the return says which hooks exist — and a hook Vite
+ * never calls is dead code that looks like a feature. A name is not a Vite type: `tooling/vite-adopter`
+ * asserts each of these is a `keyof Plugin` in 6, 7 and 8, which costs an adopter nothing and catches
+ * the regression that matters here. Adding a `buildApp` hook, which Vite 7 introduced and Vite 6 has no
+ * name for, reddens the fixture rather than shipping under a range that claims 6.
+ *
+ * `plugin.test.ts` holds this list to the object itself, both directions, at runtime — a hook added
+ * without listing it is a failure there, and a name listed that no longer exists is one too. A list
+ * that can drift from what it lists is a worse gate than none.
+ */
+export declare const PITHY_PLUGIN_HOOKS: readonly ["configResolved", "configureServer", "resolveId", "load", "hotUpdate"];
+/** One of the names {@link PITHY_PLUGIN_HOOKS} lists. */
+export type PithyPluginHook = (typeof PITHY_PLUGIN_HOOKS)[number];
+/** Options for {@link pithy}. Every one has a working default; `pithy()` is the usual call. */
+export interface PithyPluginOptions {
+    /**
+     * The Worker's `pithy.config.ts`. Relative paths resolve against the Vite root, which for a Pithy
+     * Worker is `apps/<name>/` — so the default, `pithy.config.ts`, is already the right file.
+     */
+    configFile?: string;
+    /**
+     * The environment this bundle is built for. Defaults to `ENVIRONMENT` in the process env, then
+     * `dev`. `pithy deploy --env <name>` is what threads a real value in, so a production bundle sees
+     * production's projection and a dev bundle sees dev's.
+     */
+    environment?: string;
+}
+/**
+ * Serve one `virtual:pithy/<capability>` module per capability, projected from the Worker's own
+ * `pithy.config.ts`.
+ *
+ * A screen imports what it needs — `import auth from "virtual:pithy/auth"` — and gets that
+ * capability's client-safe projection inlined at build time. A capability the Worker does not compose
+ * resolves to `{ enabled: false }` rather than failing the import, including a name nobody has ever
+ * heard of: a screen branches on `enabled`, it does not guard on whether the module exists.
+ */
+export declare function pithy(options?: PithyPluginOptions): PithyPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,WAAW,WAAW;IAC1B,mGAAmG;IACnG,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,OAAO,EAAE,KAAK,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,YAAI,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,CAAU,CAAC;AAEnH,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA4FnE"}