@pithy-sh/core 0.1.1 → 0.1.3

package/dist/semver/semver.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+//#region src/semver/semver.ts
+/**
+* Semantic versions: one parse, one format, one order.
+*
+* Anything that has to *rank* versions needs semver §11.4 — order a release feed, decide what sits
+* between installed and latest, sort a prerelease against the stable it precedes. §11.4 is short and
+* every clause of it is a trap: numeric identifiers compare numerically and alphanumerics compare
+* lexically, a numeric identifier ranks *below* an alphanumeric one, a longer identifier set wins when
+* every shared identifier is equal, and a stable outranks every prerelease of the same core. Each of
+* those is one line to get wrong, and getting one wrong shows up as a feed in the wrong order rather
+* than as an error.
+*
+* So it lives here once. The kit's update notifier uses it and ignores the prerelease field, which is
+* the narrowness it wants rather than a second implementation.
+*
+* **The parse is a split, not a string.** A version held as one string compares as text, and text puts
+* `1.10.0` below `1.9.0`. Split into numbers, the core comparison is three integer comparisons — and
+* for an adopter storing versions in SQLite, three integer columns are a row-value predicate
+* (`(major, minor, patch) > (?, ?, ?)`) that the database orders correctly on its own. SQL cannot
+* express prerelease precedence in that predicate, so a query built that way over-selects a stable
+* against a prerelease of the same core and {@link compareSemver} settles it in app code.
+*/
+/** The largest version part that survives a round trip through a number. */
+const MAX_PART = Number.MAX_SAFE_INTEGER;
+/**
+* Semver's grammar, minus what carries no order. Build metadata (`+sha`) is matched so it can be
+* discarded: the spec excludes it from precedence, so keeping it would imply an ordering it does not
+* have. A leading `v` is tolerated because tags and changelogs carry one.
+*/
+const SEMVER_PATTERN = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+const Semver = z.object({
+	major: z.number().int().nonnegative().describe("The major version. A breaking change increments it."),
+	minor: z.number().int().nonnegative().describe("The minor version. A backwards-compatible feature increments it."),
+	patch: z.number().int().nonnegative().describe("The patch version. A backwards-compatible fix increments it."),
+	prerelease: z.string().nullable().describe("The prerelease tag without its leading hyphen (`rc.1`), or null for a stable release. Null sorts above any prerelease of the same core.")
+}).describe("A semantic version split into its parts. Three numbers a database can compare as a row value, plus the prerelease tag that only `compareSemver` can order.");
+/** How far behind a version is, in each place. */
+const SemverGap = z.object({
+	major: z.number().int().nonnegative().describe("How many major versions have been published since."),
+	minor: z.number().int().nonnegative().describe("How many minor versions have accrued within the current major."),
+	patch: z.number().int().nonnegative().describe("How many patch versions have accrued within the current minor.")
+}).describe("How far an installed version is behind the latest one, counted in version places. Three counts and nothing else, so two versions with the same core are zero apart here however their prereleases rank — that difference is precedence, and `compareSemver` is what answers it.");
+/** Parse a version string into its parts. Returns null for anything that is not a version. */
+function parseSemver(value) {
+	const match = SEMVER_PATTERN.exec(value.trim());
+	if (!match) return null;
+	const [, major, minor, patch, prerelease] = match;
+	const parts = [
+		Number(major),
+		Number(minor),
+		Number(patch)
+	];
+	if (parts.some((part) => part > MAX_PART)) return null;
+	return {
+		major: parts[0],
+		minor: parts[1],
+		patch: parts[2],
+		prerelease: prerelease ?? null
+	};
+}
+/** Render a parsed version back to its canonical string. */
+function formatSemver(version) {
+	const core = `${version.major}.${version.minor}.${version.patch}`;
+	return version.prerelease === null ? core : `${core}-${version.prerelease}`;
+}
+/** Compare two dot-separated prerelease identifiers, per semver §11.4. */
+function comparePrereleaseIdentifier(a, b) {
+	const aNumeric = /^\d+$/.test(a);
+	const bNumeric = /^\d+$/.test(b);
+	if (aNumeric && bNumeric) {
+		if (a.length !== b.length) return a.length - b.length;
+		return a < b ? -1 : a > b ? 1 : 0;
+	}
+	if (aNumeric) return -1;
+	if (bNumeric) return 1;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Compare two prerelease tags. A larger set of identifiers wins when every shared one is equal. */
+function comparePrerelease(a, b) {
+	const left = a.split(".");
+	const right = b.split(".");
+	for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+		const l = left[i];
+		const r = right[i];
+		if (l === void 0) return -1;
+		if (r === void 0) return 1;
+		const ordered = comparePrereleaseIdentifier(l, r);
+		if (ordered !== 0) return ordered;
+	}
+	return 0;
+}
+/**
+* Compare two versions by semver precedence. Negative when `a` precedes `b`. Suitable as an
+* `Array.prototype.sort` comparator, so it accepts the nulls {@link parseSemver} returns — an
+* unparseable version sorts below every real one rather than throwing mid-sort.
+*/
+function compareSemver(a, b) {
+	if (a === null || b === null) return a === b ? 0 : a === null ? -1 : 1;
+	if (a.major !== b.major) return a.major - b.major;
+	if (a.minor !== b.minor) return a.minor - b.minor;
+	if (a.patch !== b.patch) return a.patch - b.patch;
+	if (a.prerelease === b.prerelease) return 0;
+	if (a.prerelease === null) return 1;
+	if (b.prerelease === null) return -1;
+	return comparePrerelease(a.prerelease, b.prerelease);
+}
+/**
+* How far `installed` is behind `latest`, per place.
+*
+* Each place counts only what accrued while the places above it stayed put, which is what makes the
+* number mean something: `1.2.3` against `1.6.1` is four minors and one patch behind, not four minors
+* and *negative two* patches. Somebody running something newer than we know about is ahead, not behind,
+* so the gap floors at zero rather than going negative.
+*
+* **A zero gap is not a claim of being current.** Two versions with the same core sit zero places apart
+* whatever their prereleases say, so `1.2.3-rc.1` against `1.2.3` measures zero even though it precedes
+* it. That is the shape being honest about its limits rather than a bug to paper over: counting places
+* cannot express a prerelease, {@link compareSemver} is what ranks them, and inventing a phantom patch
+* here would put a number on screen that no release actually carries.
+*/
+function semverGap(installed, latest) {
+	if (compareSemver(installed, latest) >= 0) return {
+		major: 0,
+		minor: 0,
+		patch: 0
+	};
+	const major = Math.max(0, latest.major - installed.major);
+	const minor = major > 0 ? latest.minor : Math.max(0, latest.minor - installed.minor);
+	return {
+		major,
+		minor,
+		patch: major > 0 || minor > 0 ? latest.patch : Math.max(0, latest.patch - installed.patch)
+	};
+}
+//#endregion
+export { Semver, SemverGap, compareSemver, formatSemver, parseSemver, semverGap };

package/dist/text/comments.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `source` with every comment blanked — the one comment stripper this repository's gates share.
+ *
+ * A tripwire that reads source has to walk past prose, because this repository's docblocks quote the
+ * very thing their gate forbids: a paragraph explaining why a config must never read `process.env`, a
+ * header naming `@cloudflare/workers-types` in a sentence. Blanking is what makes the prose invisible
+ * without making the file shorter.
+ *
+ * **Blanked rather than deleted: every character becomes a space and every newline survives**, so the
+ * line number in a failure is the line number in the file, a caller may split on `\n` and index, and a
+ * caller may slice the blanked text at an offset it measured on the original. Deleting is the cheaper
+ * thing to write and it silently joins the code either side of a block comment onto one line, which
+ * costs the position of everything below it.
+ *
+ * **It walks the source rather than matching a pattern, because the pattern has two measured false
+ * negatives.** One `replace` over a comment pattern has no notion of a string, and a string is where a
+ * comment can be forged:
+ *
+ * - `const base = "https://api.cloudflare.com";` opens a line comment at the `//` inside the URL, and
+ *   everything after it on that line is blanked — a `process.env.CLOUDFLARE_API_TOKEN` read beside it,
+ *   a `D1Database` beside it, whatever the caller was looking for.
+ * - `include: ["**\/*.workers.test.ts"]` opens a block comment at the `/*` inside the glob, which runs
+ *   to the next `*\/` anywhere later in the file — the next docblock will do — and blanks every line
+ *   between.
+ *
+ * Both were measured against planted source, and both are silent: the scan reports nothing and passes.
+ * A prohibition that a URL can switch off is worse than no prohibition, because the file it exempts
+ * looks scanned.
+ *
+ * **Strings are stepped over, not blanked.** The job is comments, and preserving a string keeps a real
+ * read inside a template — `` `${process.env.CLOUDFLARE_API_TOKEN}` `` — visible to the caller. A string
+ * that merely *contains* the text is then a false positive, which is the direction a gate should fail in.
+ *
+ * **A regex literal is stepped over too**, because `/^["']|["']$/` is a quote a string state would open
+ * on, and a runaway string swallows every line to the next quote. Told apart from division by the last
+ * significant character: a `/` where a value may begin starts a literal, and one after an operand is a
+ * divide. An unterminated string or regex stops at the newline, so a bad guess costs one line rather
+ * than the rest of the file.
+ *
+ * ## Why it lives in `@pithy-sh/core`, of all places
+ *
+ * It was written in `@pithy-sh/cli`'s `ci/sourceFiles.ts`, beside the walk its first three callers used
+ * (#437). `packages/core/src/worker-safety.test.ts` is the caller that could not follow it there:
+ * it guards which bare specifiers core's shipped source imports, it had the naive pattern, and
+ * `@pithy-sh/core` must never depend on `@pithy-sh/cli` — core is bundled into the adopter's Worker, so
+ * its dependency set is a shipped surface and the arrow runs cli → core only (#439).
+ *
+ * The alternatives were a documented copy and a drift gate over two copies. That pattern is real here —
+ * `envIsolation.workers.test.ts` restates `CLOUDFLARE_ENV_KEYS` under exactly this constraint — and it
+ * holds for two string constants, which a gate can compare for equality. Over a hundred-line walk it
+ * degrades into comparing function text, which changes on a rename and says nothing about behavior.
+ *
+ * So the third home, and core is the only package every caller already imports: the CLI, `email`,
+ * `payments` and `ui-react` all declare it, and `worker-safety.test.ts` reaches it with a relative path.
+ * The cost is honest and small. This is source-text tooling inside the package that ships into a Worker
+ * — but core has no barrel, so a module nothing imports is never reached by an adopter's bundler at all,
+ * and the price is bytes in a tarball rather than bytes in a Worker. And it earns its keep as a Worker
+ * neighbor on its own terms: **it imports nothing and touches no Node builtin**, which is the property
+ * `worker-safety.test.ts` exists to enforce, so the gate now polices the stripper it reads with.
+ */
+export declare function blankComments(source: string): string;
+//# sourceMappingURL=comments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/text/comments.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgCpD"}

package/dist/text/comments.js

@@ -0,0 +1,161 @@
+//#region src/text/comments.ts
+/**
+* `source` with every comment blanked — the one comment stripper this repository's gates share.
+*
+* A tripwire that reads source has to walk past prose, because this repository's docblocks quote the
+* very thing their gate forbids: a paragraph explaining why a config must never read `process.env`, a
+* header naming `@cloudflare/workers-types` in a sentence. Blanking is what makes the prose invisible
+* without making the file shorter.
+*
+* **Blanked rather than deleted: every character becomes a space and every newline survives**, so the
+* line number in a failure is the line number in the file, a caller may split on `\n` and index, and a
+* caller may slice the blanked text at an offset it measured on the original. Deleting is the cheaper
+* thing to write and it silently joins the code either side of a block comment onto one line, which
+* costs the position of everything below it.
+*
+* **It walks the source rather than matching a pattern, because the pattern has two measured false
+* negatives.** One `replace` over a comment pattern has no notion of a string, and a string is where a
+* comment can be forged:
+*
+* - `const base = "https://api.cloudflare.com";` opens a line comment at the `//` inside the URL, and
+*   everything after it on that line is blanked — a `process.env.CLOUDFLARE_API_TOKEN` read beside it,
+*   a `D1Database` beside it, whatever the caller was looking for.
+* - `include: ["**\/*.workers.test.ts"]` opens a block comment at the `/*` inside the glob, which runs
+*   to the next `*\/` anywhere later in the file — the next docblock will do — and blanks every line
+*   between.
+*
+* Both were measured against planted source, and both are silent: the scan reports nothing and passes.
+* A prohibition that a URL can switch off is worse than no prohibition, because the file it exempts
+* looks scanned.
+*
+* **Strings are stepped over, not blanked.** The job is comments, and preserving a string keeps a real
+* read inside a template — `` `${process.env.CLOUDFLARE_API_TOKEN}` `` — visible to the caller. A string
+* that merely *contains* the text is then a false positive, which is the direction a gate should fail in.
+*
+* **A regex literal is stepped over too**, because `/^["']|["']$/` is a quote a string state would open
+* on, and a runaway string swallows every line to the next quote. Told apart from division by the last
+* significant character: a `/` where a value may begin starts a literal, and one after an operand is a
+* divide. An unterminated string or regex stops at the newline, so a bad guess costs one line rather
+* than the rest of the file.
+*
+* ## Why it lives in `@pithy-sh/core`, of all places
+*
+* It was written in `@pithy-sh/cli`'s `ci/sourceFiles.ts`, beside the walk its first three callers used
+* (#437). `packages/core/src/worker-safety.test.ts` is the caller that could not follow it there:
+* it guards which bare specifiers core's shipped source imports, it had the naive pattern, and
+* `@pithy-sh/core` must never depend on `@pithy-sh/cli` — core is bundled into the adopter's Worker, so
+* its dependency set is a shipped surface and the arrow runs cli → core only (#439).
+*
+* The alternatives were a documented copy and a drift gate over two copies. That pattern is real here —
+* `envIsolation.workers.test.ts` restates `CLOUDFLARE_ENV_KEYS` under exactly this constraint — and it
+* holds for two string constants, which a gate can compare for equality. Over a hundred-line walk it
+* degrades into comparing function text, which changes on a rename and says nothing about behavior.
+*
+* So the third home, and core is the only package every caller already imports: the CLI, `email`,
+* `payments` and `ui-react` all declare it, and `worker-safety.test.ts` reaches it with a relative path.
+* The cost is honest and small. This is source-text tooling inside the package that ships into a Worker
+* — but core has no barrel, so a module nothing imports is never reached by an adopter's bundler at all,
+* and the price is bytes in a tarball rather than bytes in a Worker. And it earns its keep as a Worker
+* neighbor on its own terms: **it imports nothing and touches no Node builtin**, which is the property
+* `worker-safety.test.ts` exists to enforce, so the gate now polices the stripper it reads with.
+*/
+function blankComments(source) {
+	let out = "";
+	let previous = "";
+	let index = 0;
+	while (index < source.length) {
+		const char = source[index];
+		const pair = source.slice(index, index + 2);
+		if (pair === "//" || pair === "/*") {
+			const stop = endOfComment(source, index, pair);
+			out += source.slice(index, stop).replace(/[^\n]/g, " ");
+			index = stop;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			const stop = endOfQuoted(source, index, char, char !== "`");
+			out += source.slice(index, stop);
+			index = stop;
+			previous = char;
+			continue;
+		}
+		if (char === "/" && VALUE_POSITION.has(previous)) {
+			const stop = endOfRegex(source, index);
+			out += source.slice(index, stop);
+			index = stop;
+			previous = "/";
+			continue;
+		}
+		out += char;
+		if (!/\s/.test(char)) previous = char;
+		index += 1;
+	}
+	return out;
+}
+/**
+* After one of these, a `/` opens a regex literal; after anything else it divides. The empty string is
+* the start of the file. A wrong guess is bounded — see {@link endOfRegex}.
+*/
+const VALUE_POSITION = /* @__PURE__ */ new Set([
+	"",
+	"(",
+	",",
+	"=",
+	":",
+	"[",
+	"!",
+	"&",
+	"|",
+	"?",
+	"{",
+	"}",
+	";",
+	"+",
+	"-",
+	"*",
+	"%",
+	"^",
+	"~",
+	"<",
+	">"
+]);
+/** Where a comment ends. An unterminated block comment runs to the end of the file, as it does for tsc. */
+function endOfComment(source, start, pair) {
+	if (pair === "//") {
+		const newline = source.indexOf("\n", start);
+		return newline === -1 ? source.length : newline;
+	}
+	const close = source.indexOf("*/", start + 2);
+	return close === -1 ? source.length : close + 2;
+}
+/** Where a quoted run ends: past its closing quote, or at the newline a single-line quote cannot cross. */
+function endOfQuoted(source, start, quote, singleLine) {
+	for (let index = start + 1; index < source.length; index += 1) {
+		const char = source[index];
+		if (char === "\\") {
+			index += 1;
+			continue;
+		}
+		if (char === quote) return index + 1;
+		if (char === "\n" && singleLine) return index;
+	}
+	return source.length;
+}
+/** Where a regex literal ends. A `/` inside a character class does not close it; a newline does. */
+function endOfRegex(source, start) {
+	let inClass = false;
+	for (let index = start + 1; index < source.length; index += 1) {
+		const char = source[index];
+		if (char === "\\") {
+			index += 1;
+			continue;
+		}
+		if (char === "\n") return index;
+		if (char === "[") inClass = true;
+		else if (char === "]") inClass = false;
+		else if (char === "/" && !inClass) return index + 1;
+	}
+	return source.length;
+}
+//#endregion
+export { blankComments };

package/dist/version.generated.d.ts

@@ -0,0 +1,5 @@
+/** This package's npm name — the join key against a release feed. */
+export declare const PACKAGE_NAME = "@pithy-sh/core";
+/** This package's version, stamped from its own package.json at generation time. */
+export declare const PACKAGE_VERSION = "0.1.3";
+//# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/version.generated.js

@@ -0,0 +1,7 @@
+//#region src/version.generated.ts
+/** This package's npm name — the join key against a release feed. */
+const PACKAGE_NAME = "@pithy-sh/core";
+/** This package's version, stamped from its own package.json at generation time. */
+const PACKAGE_VERSION = "0.1.3";
+//#endregion
+export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/worker/health.d.ts

@@ -0,0 +1,39 @@
+/**
+ * **Where every Pithy Worker answers liveness — written once, read by everyone who needs it.**
+ *
+ * `createBackend` mounts this route, the CLI's route allowlist keeps it worker-first, `pithy deploy`
+ * probes it after a release, and the bare home screen a no-auth scaffold ships fetches it. Four sites,
+ * one path, and until #400 each of them wrote it out.
+ *
+ * The failure that earned this module is the quietest one in the front end. `home.bare.tsx` is the
+ * **only** screen a project with no auth composed gets, and its entire content is that one request. A
+ * rename here without a matching edit there renders *"The worker says: unknown."* — a 200, no error, no
+ * failed build, nothing in a log. The adopter's first screen showing a word that is not a status, for a
+ * reason nowhere on the page.
+ *
+ * A gate comparing the copies would have watched that. This removes it instead: the template imports
+ * the constant, so a rename moves the screen with it, and there is no second string left to disagree
+ * with. `docs/CONVENTIONS.md` § *Seeded files* is the general form — **removing the class beats
+ * watching it** — and #377, #366, #393 and #394 are the same move made earlier.
+ *
+ * ## Why a module of its own
+ *
+ * Because a client bundle imports it. Everything else in `@pithy-sh/core` that a route path could sit
+ * beside pulls Hono, the Workers types, or both, and the scaffolded SPA is a browser program that must
+ * import neither. This file declares one string and imports nothing, so the seeded screen can read it
+ * without dragging a server runtime into the client's program.
+ */
+/**
+ * `GET /health` — public, and deliberately so.
+ *
+ * It reads nothing about the caller, so there is no session to send it. That is what makes it the one
+ * request the bare home screen can make with no auth capability in the project, and why
+ * `sameOrigin.test.ts` exempts that screen's `fetch` rather than routing it through a credentialed
+ * primitive.
+ *
+ * The leading slash is part of the value. Hono mounts it, `firstSegment` splits it, and `verifyDeploy`
+ * appends it to a declared origin — all three want the same string, and a bare `health` would make two
+ * of them concatenate wrongly in silence.
+ */
+export declare const HEALTH_PATH = "/health";
+//# sourceMappingURL=health.d.ts.map

package/dist/worker/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/worker/health.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC"}

package/dist/worker/health.js

@@ -0,0 +1,41 @@
+//#region src/worker/health.ts
+/**
+* **Where every Pithy Worker answers liveness — written once, read by everyone who needs it.**
+*
+* `createBackend` mounts this route, the CLI's route allowlist keeps it worker-first, `pithy deploy`
+* probes it after a release, and the bare home screen a no-auth scaffold ships fetches it. Four sites,
+* one path, and until #400 each of them wrote it out.
+*
+* The failure that earned this module is the quietest one in the front end. `home.bare.tsx` is the
+* **only** screen a project with no auth composed gets, and its entire content is that one request. A
+* rename here without a matching edit there renders *"The worker says: unknown."* — a 200, no error, no
+* failed build, nothing in a log. The adopter's first screen showing a word that is not a status, for a
+* reason nowhere on the page.
+*
+* A gate comparing the copies would have watched that. This removes it instead: the template imports
+* the constant, so a rename moves the screen with it, and there is no second string left to disagree
+* with. `docs/CONVENTIONS.md` § *Seeded files* is the general form — **removing the class beats
+* watching it** — and #377, #366, #393 and #394 are the same move made earlier.
+*
+* ## Why a module of its own
+*
+* Because a client bundle imports it. Everything else in `@pithy-sh/core` that a route path could sit
+* beside pulls Hono, the Workers types, or both, and the scaffolded SPA is a browser program that must
+* import neither. This file declares one string and imports nothing, so the seeded screen can read it
+* without dragging a server runtime into the client's program.
+*/
+/**
+* `GET /health` — public, and deliberately so.
+*
+* It reads nothing about the caller, so there is no session to send it. That is what makes it the one
+* request the bare home screen can make with no auth capability in the project, and why
+* `sameOrigin.test.ts` exempts that screen's `fetch` rather than routing it through a credentialed
+* primitive.
+*
+* The leading slash is part of the value. Hono mounts it, `firstSegment` splits it, and `verifyDeploy`
+* appends it to a declared origin — all three want the same string, and a bare `health` would make two
+* of them concatenate wrongly in silence.
+*/
+const HEALTH_PATH = "/health";
+//#endregion
+export { HEALTH_PATH };