@pithy-sh/core 0.1.2 → 0.1.3

package/dist/naming/resource.d.ts

@@ -0,0 +1,169 @@
+/**
+ * One naming rule, in one module: **`<project>-<env>-<thing>`**, kebab-case.
+ *
+ * Every Cloudflare namespace Pithy writes into is flat and account-wide — D1, KV, R2, Worker
+ * scripts, Workflows, the single Secrets Store, the API-token list. None of them can be
+ * partitioned, so the *name* is the partition, and the project segment is the only thing keeping
+ * two Pithy projects in one account from adopting or overwriting each other's resources.
+ *
+ * **Project first** because that is the ownership boundary everything turns on: teardown, the
+ * token listing's prefix filter, and the reaper's reservation all key on it. **Environment second**
+ * because these end up in listings nobody can filter — `wrangler d1 list`, the account dashboard,
+ * the Secrets Store — and sorting by name should group a project's resources and then that
+ * project's environments, so everything belonging to prod sits together. Environment last
+ * would scatter prod through the listing, interleaved with staging, which is exactly when
+ * someone acts on the wrong one.
+ *
+ * A `global`-scoped thing puts the literal `global` in the environment slot rather than omitting
+ * it, so the scheme has no exception to remember.
+ *
+ * This module is in `core` because it has no dependencies and every layer needs it — capabilities,
+ * the CLI, and the Workers runtime alike. It therefore uses **no `node:` builtin**: core is bundled
+ * into the adopter's Worker, where `node:crypto` is not free.
+ */
+/**
+ * The default budget of the un-namespaced {@link resourceName} composer: the strictest cap of any
+ * namespace Pithy writes into, which is R2's 63.
+ *
+ * A caller that knows its namespace does **not** use this — it passes that namespace's own limit
+ * from `./limits`, or, better, goes through the facade in `./resourceNames`, which cannot pick the
+ * wrong budget. This number is the conservative answer for a call site that has no namespace at all.
+ */
+export declare const MAX_RESOURCE_NAME: 63;
+/**
+ * The cap on a project name — **derived, not chosen, and derived from two shapes rather than one**.
+ *
+ * A project name has to survive every name it will ever be the head of, so it gets the *smaller* of
+ * the two worst cases (`./limits` carries both derivations with their arithmetic):
+ *
+ * - {@link WORKFLOW_DERIVED_PROJECT_NAME} — `<project>-<env>-<capability>-<job>` against a Workflow's
+ *   64 characters, after the longest environment and the longest `<capability>-<job>`.
+ * - {@link FEATURE_DERIVED_PROJECT_NAME} — `<project>-f<issue>-<slug>-<binding>-<kind>` against R2's
+ *   63, with room for the reserved issue digits, a legible slug, and a binding kept whole.
+ *
+ * Neither number is repeated here. Each is a computed constant with its arithmetic in `./limits`, and a
+ * copy in this sentence is a copy that goes stale the first time a term of the derivation moves.
+ *
+ * The feature shape is the binding one, and it used to be invisible: the cap was derived from the
+ * Workflow alone, so a project inside it could still compose a feature name whose slug was hashed
+ * away to nothing. Taking the minimum is the only version that is true of both.
+ *
+ * **Why the cap belongs on the project name rather than on each composed name:** without it the
+ * refusal lands at the first `pithy <capability> provision`, by which time `pithy add` has created
+ * real R2 buckets and D1 databases under a name that fits *their* budget. The project is
+ * half-provisioned, and the only documented remedy — renaming — orphans everything already made.
+ * Capped here, `pithy init` and `requireProjectName` refuse it before anything is written.
+ */
+export declare const MAX_PROJECT_NAME: number;
+/** Lowercase, collapse any run of non-`[a-z0-9]` to one `-`, and trim leading/trailing `-`. */
+export declare function kebab(input: string): string;
+/**
+ * A stable 6-hex-character digest, FNV-1a. Pure arithmetic rather than `node:crypto` so this module
+ * runs unchanged in a Worker. It is a *disambiguator for truncated names*, never a security
+ * primitive — collision resistance beyond "two different capability names look different" is not
+ * claimed and must not be relied on.
+ */
+export declare function hash6(input: string): string;
+/**
+ * Fit a kebab segment into `budget` characters: verbatim when it fits, otherwise a truncated head
+ * plus a short stable hash so it stays distinct and within budget. Deterministic in `segment`
+ * alone, so two commands computing the same name agree without storing it. The hash shrinks for
+ * tiny budgets, and the result never exceeds `budget` nor trails a hyphen.
+ */
+export declare function fitSegment(segment: string, budget: number): string;
+/** The parts of a provisioned name. Every field is required — an absent segment is a naming bug, not a default. */
+export interface ResourceNameParts {
+    /**
+     * The project name — the root `pithy.config.ts` `name`, resolved by `requireProjectName` and
+     * **never guessed**. This is the ownership boundary; a wrong value here writes into another
+     * project's resources.
+     */
+    project: string;
+    /** The environment (`dev`, `staging`, `prod`), or the literal `global` for a value shared across all of them. */
+    env: string;
+    /** What this resource is — a capability, a binding, a secret, a token profile. The only segment ever truncated. */
+    thing: string;
+}
+/**
+ * Compose `<project>-<env>-<thing>`, kebab-cased and fitted to `budget`.
+ *
+ * **Only `thing` is ever truncated.** The project and environment segments are taken verbatim,
+ * because a hashed project segment would let two long project names share a prefix — and the token
+ * listing filters on exactly that prefix, so a collision there means one project enumerating and
+ * acting on another's credentials. If project and environment alone cannot fit, that is refused
+ * with the limit named rather than quietly hashed into an ambiguous name.
+ *
+ * `budget` defaults to {@link MAX_RESOURCE_NAME}; a namespace with its own limit passes it in.
+ *
+ * The project segment is held to {@link isValidProjectName} — the same rule the Worker and Workflow
+ * namers apply — so a project this accepts is one every namespace accepts. It is a backstop, not the
+ * gate: the real refusal belongs at `pithy init` and `requireProjectName`, before anything is written.
+ */
+export declare function resourceName(parts: ResourceNameParts, budget?: number): string;
+/**
+ * Could every Cloudflare name this project generates be created? The one rule, in one place, so no
+ * namespace re-derives a looser version of it.
+ *
+ * **Read after kebabbing**, for the same reason {@link isReservedProjectName} is: the raw string never
+ * reaches an account, only what the composer made of it. `Acme Corp` is legal (it becomes `acme-corp`);
+ * `2026 Launch` is not, and neither answer can be read off the raw characters.
+ *
+ * **Two dimensions, one answer: charset and length.** Both have the same failure mode and so must have
+ * the same home — {@link NAME_SEGMENT} for the charset, {@link MAX_PROJECT_NAME} for the number. The
+ * charset is the shared segment rule rather than a project-specific one: a project name is the head of
+ * every composed name, so it is held to exactly what every other segment is held to.
+ *
+ * The rule matters at the *source* — `pithy init` and `requireProjectName` — because the namespaces
+ * disagree about it. A digit-leading project composes a legal D1 database name, a legal KV title, and a
+ * legal bucket name, so `pithy add` provisions all three for real; only the first host-worker deploy
+ * refuses it, by which point the documented remedy — rename the project — orphans everything already
+ * created. A 33-character project fails exactly the same way, one deploy later. One rule, enforced
+ * before anything is written, is the only version of this that is safe.
+ */
+export declare function isValidProjectName(name: string): boolean;
+/**
+ * Refuse a project name no Cloudflare namespace could carry, as a **`ValidationError`**: a project name
+ * is something a human typed, so it is a 400 with an action, never an internal 500 blamed on the toolkit.
+ *
+ * Length and charset are one rule with two sentences, because they are two different mistakes: a name
+ * that is merely long is otherwise perfect, and "use lowercase letters" would be no help at all.
+ */
+export declare function assertValidProjectName(name: string): void;
+/**
+ * **`pithy-int-` is reserved for Pithy's own live integration tests, on any account.**
+ *
+ * Every Cloudflare name a live test creates begins with it, no real project's name may, and the
+ * test-debris reaper deletes nothing without it. The reservation is what makes automatic reaping safe
+ * in both directions: without it the reaper is guessing — either it fails to recognize the names a
+ * suite invented, and debris accumulates silently on a real account, or it matches loosely enough to
+ * one day delete a customer's database. With it, membership is decidable from the name alone.
+ *
+ * It lives here, next to the composer, because both halves of the reservation are naming facts.
+ * `<project>-<env>-<thing>` puts the project first and takes it **verbatim**, so the prefix of every
+ * generated name is decided by the project name and nothing else — which is what lets one guard, on
+ * `pithy init`, keep the two sets from ever overlapping. See {@link isReservedProjectName}.
+ *
+ * This is deliberately narrower than the product's own `pithy` prefix. A project may legitimately be
+ * named `pithy-app`, and everything it provisions is real; `pithy-int-…` is debris by definition.
+ */
+export declare const RESERVED_TEST_PREFIX = "pithy-int-";
+/**
+ * Would a project of this name generate resource names inside the reservation? The one rule
+ * `pithy init` enforces, stated once so no call site re-derives it.
+ *
+ * Two traps make the obvious `name.startsWith(RESERVED_TEST_PREFIX)` wrong, and both are reachable
+ * with a name a human would type.
+ *
+ * **Kebabbing.** The composer kebabs the project before using it, so the raw string is not what
+ * Cloudflare sees. `"Pithy Int Ruse"` is not prefixed by `pithy-int-`, and it normalizes straight into
+ * the reservation.
+ *
+ * **The trailing hyphen.** The composer appends one after the project. A project named exactly
+ * `pithy-int` is not prefixed by `pithy-int-` either, and it generates `pithy-int-dev-db` — inside the
+ * namespace the reaper deletes.
+ *
+ * Testing `` `${kebab(name)}-` `` against the prefix closes both: it compares the form the composer
+ * actually uses, including the separator it actually adds.
+ */
+export declare function isReservedProjectName(name: string): boolean;
+//# sourceMappingURL=resource.d.ts.map

package/dist/naming/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/naming/resource.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,IAAgC,CAAC;AAK/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB,QAAwE,CAAC;AAEtG,+FAA+F;AAC/F,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED,mHAAmH;AACnH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,iHAAiH;IACjH,GAAG,EAAE,MAAM,CAAC;IACZ,mHAAmH;IACnH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,GAAE,MAA0B,GAAG,MAAM,CAgCjG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAezD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D"}

package/dist/naming/resource.js

@@ -0,0 +1,220 @@
+import { NAME_SEGMENT } from "./segment.js";
+import { InternalError, ValidationError } from "../error/pithyError.js";
+import { MAX_ENVIRONMENT_NAME } from "./environment.js";
+import { FEATURE_DERIVED_PROJECT_NAME, NAMESPACE_LIMITS, WORKFLOW_DERIVED_PROJECT_NAME } from "./limits.js";
+//#region src/naming/resource.ts
+/**
+* One naming rule, in one module: **`<project>-<env>-<thing>`**, kebab-case.
+*
+* Every Cloudflare namespace Pithy writes into is flat and account-wide — D1, KV, R2, Worker
+* scripts, Workflows, the single Secrets Store, the API-token list. None of them can be
+* partitioned, so the *name* is the partition, and the project segment is the only thing keeping
+* two Pithy projects in one account from adopting or overwriting each other's resources.
+*
+* **Project first** because that is the ownership boundary everything turns on: teardown, the
+* token listing's prefix filter, and the reaper's reservation all key on it. **Environment second**
+* because these end up in listings nobody can filter — `wrangler d1 list`, the account dashboard,
+* the Secrets Store — and sorting by name should group a project's resources and then that
+* project's environments, so everything belonging to prod sits together. Environment last
+* would scatter prod through the listing, interleaved with staging, which is exactly when
+* someone acts on the wrong one.
+*
+* A `global`-scoped thing puts the literal `global` in the environment slot rather than omitting
+* it, so the scheme has no exception to remember.
+*
+* This module is in `core` because it has no dependencies and every layer needs it — capabilities,
+* the CLI, and the Workers runtime alike. It therefore uses **no `node:` builtin**: core is bundled
+* into the adopter's Worker, where `node:crypto` is not free.
+*/
+/**
+* The default budget of the un-namespaced {@link resourceName} composer: the strictest cap of any
+* namespace Pithy writes into, which is R2's 63.
+*
+* A caller that knows its namespace does **not** use this — it passes that namespace's own limit
+* from `./limits`, or, better, goes through the facade in `./resourceNames`, which cannot pick the
+* wrong budget. This number is the conservative answer for a call site that has no namespace at all.
+*/
+const MAX_RESOURCE_NAME = NAMESPACE_LIMITS.r2.maxLength;
+/** Below this the trailing segment is not worth keeping legible, so a name this tight is refused instead. */
+const MIN_THING_BUDGET = 1;
+/**
+* The cap on a project name — **derived, not chosen, and derived from two shapes rather than one**.
+*
+* A project name has to survive every name it will ever be the head of, so it gets the *smaller* of
+* the two worst cases (`./limits` carries both derivations with their arithmetic):
+*
+* - {@link WORKFLOW_DERIVED_PROJECT_NAME} — `<project>-<env>-<capability>-<job>` against a Workflow's
+*   64 characters, after the longest environment and the longest `<capability>-<job>`.
+* - {@link FEATURE_DERIVED_PROJECT_NAME} — `<project>-f<issue>-<slug>-<binding>-<kind>` against R2's
+*   63, with room for the reserved issue digits, a legible slug, and a binding kept whole.
+*
+* Neither number is repeated here. Each is a computed constant with its arithmetic in `./limits`, and a
+* copy in this sentence is a copy that goes stale the first time a term of the derivation moves.
+*
+* The feature shape is the binding one, and it used to be invisible: the cap was derived from the
+* Workflow alone, so a project inside it could still compose a feature name whose slug was hashed
+* away to nothing. Taking the minimum is the only version that is true of both.
+*
+* **Why the cap belongs on the project name rather than on each composed name:** without it the
+* refusal lands at the first `pithy <capability> provision`, by which time `pithy add` has created
+* real R2 buckets and D1 databases under a name that fits *their* budget. The project is
+* half-provisioned, and the only documented remedy — renaming — orphans everything already made.
+* Capped here, `pithy init` and `requireProjectName` refuse it before anything is written.
+*/
+const MAX_PROJECT_NAME = Math.min(WORKFLOW_DERIVED_PROJECT_NAME, FEATURE_DERIVED_PROJECT_NAME);
+/** Lowercase, collapse any run of non-`[a-z0-9]` to one `-`, and trim leading/trailing `-`. */
+function kebab(input) {
+	return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/**
+* A stable 6-hex-character digest, FNV-1a. Pure arithmetic rather than `node:crypto` so this module
+* runs unchanged in a Worker. It is a *disambiguator for truncated names*, never a security
+* primitive — collision resistance beyond "two different capability names look different" is not
+* claimed and must not be relied on.
+*/
+function hash6(input) {
+	let h = 2166136261;
+	for (let i = 0; i < input.length; i += 1) {
+		h ^= input.charCodeAt(i);
+		h = Math.imul(h, 16777619) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0").slice(0, 6);
+}
+/**
+* Fit a kebab segment into `budget` characters: verbatim when it fits, otherwise a truncated head
+* plus a short stable hash so it stays distinct and within budget. Deterministic in `segment`
+* alone, so two commands computing the same name agree without storing it. The hash shrinks for
+* tiny budgets, and the result never exceeds `budget` nor trails a hyphen.
+*/
+function fitSegment(segment, budget) {
+	if (budget <= 0) return "";
+	if (segment.length <= budget) return segment;
+	if (budget < 4) return hash6(segment).slice(0, budget);
+	const hashLen = Math.min(6, Math.max(2, budget - 2));
+	const headLen = Math.max(1, budget - hashLen - 1);
+	return `${segment.slice(0, headLen).replace(/-+$/, "")}-${hash6(segment).slice(0, hashLen)}`;
+}
+/**
+* Compose `<project>-<env>-<thing>`, kebab-cased and fitted to `budget`.
+*
+* **Only `thing` is ever truncated.** The project and environment segments are taken verbatim,
+* because a hashed project segment would let two long project names share a prefix — and the token
+* listing filters on exactly that prefix, so a collision there means one project enumerating and
+* acting on another's credentials. If project and environment alone cannot fit, that is refused
+* with the limit named rather than quietly hashed into an ambiguous name.
+*
+* `budget` defaults to {@link MAX_RESOURCE_NAME}; a namespace with its own limit passes it in.
+*
+* The project segment is held to {@link isValidProjectName} — the same rule the Worker and Workflow
+* namers apply — so a project this accepts is one every namespace accepts. It is a backstop, not the
+* gate: the real refusal belongs at `pithy init` and `requireProjectName`, before anything is written.
+*/
+function resourceName(parts, budget = MAX_RESOURCE_NAME) {
+	const project = kebab(parts.project);
+	const env = kebab(parts.env);
+	const thing = kebab(parts.thing);
+	for (const [role, value] of [
+		["project", project],
+		["environment", env],
+		["thing", thing]
+	]) if (!value) throw new ValidationError({
+		message: `A resource name needs a ${role}.`,
+		action: role === "project" ? "Set `name` in pithy.config.ts." : void 0,
+		detail: `resourceName received an empty ${role} segment (raw: ${JSON.stringify(parts)})`
+	});
+	assertValidProjectName(parts.project);
+	const head = `${project}-${env}`;
+	const thingBudget = budget - head.length - 1;
+	if (thingBudget < MIN_THING_BUDGET) throw new InternalError({
+		message: `The project and environment names alone exceed the ${budget}-character limit for this resource.`,
+		action: "Shorten `name` in pithy.config.ts.",
+		detail: `"${head}" leaves ${thingBudget} characters for "${thing}"`
+	});
+	return `${head}-${fitSegment(thing, thingBudget)}`;
+}
+/**
+* Could every Cloudflare name this project generates be created? The one rule, in one place, so no
+* namespace re-derives a looser version of it.
+*
+* **Read after kebabbing**, for the same reason {@link isReservedProjectName} is: the raw string never
+* reaches an account, only what the composer made of it. `Acme Corp` is legal (it becomes `acme-corp`);
+* `2026 Launch` is not, and neither answer can be read off the raw characters.
+*
+* **Two dimensions, one answer: charset and length.** Both have the same failure mode and so must have
+* the same home — {@link NAME_SEGMENT} for the charset, {@link MAX_PROJECT_NAME} for the number. The
+* charset is the shared segment rule rather than a project-specific one: a project name is the head of
+* every composed name, so it is held to exactly what every other segment is held to.
+*
+* The rule matters at the *source* — `pithy init` and `requireProjectName` — because the namespaces
+* disagree about it. A digit-leading project composes a legal D1 database name, a legal KV title, and a
+* legal bucket name, so `pithy add` provisions all three for real; only the first host-worker deploy
+* refuses it, by which point the documented remedy — rename the project — orphans everything already
+* created. A 33-character project fails exactly the same way, one deploy later. One rule, enforced
+* before anything is written, is the only version of this that is safe.
+*/
+function isValidProjectName(name) {
+	const normalized = kebab(name);
+	return normalized.length <= MAX_PROJECT_NAME && NAME_SEGMENT.test(normalized);
+}
+/**
+* Refuse a project name no Cloudflare namespace could carry, as a **`ValidationError`**: a project name
+* is something a human typed, so it is a 400 with an action, never an internal 500 blamed on the toolkit.
+*
+* Length and charset are one rule with two sentences, because they are two different mistakes: a name
+* that is merely long is otherwise perfect, and "use lowercase letters" would be no help at all.
+*/
+function assertValidProjectName(name) {
+	if (isValidProjectName(name)) return;
+	const normalized = kebab(name);
+	if (normalized.length > MAX_PROJECT_NAME && NAME_SEGMENT.test(normalized)) throw new ValidationError({
+		message: `"${name}" is ${normalized.length} characters. A project name stops at ${MAX_PROJECT_NAME}.`,
+		action: `Shorten \`name\` in pithy.config.ts to ${MAX_PROJECT_NAME} characters or fewer.`,
+		detail: `${MAX_PROJECT_NAME} is the smaller of what a 64-character Workflow name leaves after a ${MAX_ENVIRONMENT_NAME}-character environment and a 22-character <capability>-<job> (${WORKFLOW_DERIVED_PROJECT_NAME}), and what a 63-character feature resource name leaves after a six-digit issue, a legible slug, and a binding (${FEATURE_DERIVED_PROJECT_NAME}).`
+	});
+	throw new ValidationError({
+		message: `"${name}" can't be a project name.`,
+		action: "Use lowercase letters, digits, and single hyphens, starting with a letter.",
+		detail: `"${name}" kebabs to "${normalized}", which does not match ${NAME_SEGMENT.source}.`
+	});
+}
+/**
+* **`pithy-int-` is reserved for Pithy's own live integration tests, on any account.**
+*
+* Every Cloudflare name a live test creates begins with it, no real project's name may, and the
+* test-debris reaper deletes nothing without it. The reservation is what makes automatic reaping safe
+* in both directions: without it the reaper is guessing — either it fails to recognize the names a
+* suite invented, and debris accumulates silently on a real account, or it matches loosely enough to
+* one day delete a customer's database. With it, membership is decidable from the name alone.
+*
+* It lives here, next to the composer, because both halves of the reservation are naming facts.
+* `<project>-<env>-<thing>` puts the project first and takes it **verbatim**, so the prefix of every
+* generated name is decided by the project name and nothing else — which is what lets one guard, on
+* `pithy init`, keep the two sets from ever overlapping. See {@link isReservedProjectName}.
+*
+* This is deliberately narrower than the product's own `pithy` prefix. A project may legitimately be
+* named `pithy-app`, and everything it provisions is real; `pithy-int-…` is debris by definition.
+*/
+const RESERVED_TEST_PREFIX = "pithy-int-";
+/**
+* Would a project of this name generate resource names inside the reservation? The one rule
+* `pithy init` enforces, stated once so no call site re-derives it.
+*
+* Two traps make the obvious `name.startsWith(RESERVED_TEST_PREFIX)` wrong, and both are reachable
+* with a name a human would type.
+*
+* **Kebabbing.** The composer kebabs the project before using it, so the raw string is not what
+* Cloudflare sees. `"Pithy Int Ruse"` is not prefixed by `pithy-int-`, and it normalizes straight into
+* the reservation.
+*
+* **The trailing hyphen.** The composer appends one after the project. A project named exactly
+* `pithy-int` is not prefixed by `pithy-int-` either, and it generates `pithy-int-dev-db` — inside the
+* namespace the reaper deletes.
+*
+* Testing `` `${kebab(name)}-` `` against the prefix closes both: it compares the form the composer
+* actually uses, including the separator it actually adds.
+*/
+function isReservedProjectName(name) {
+	return `${kebab(name)}-`.startsWith(RESERVED_TEST_PREFIX);
+}
+//#endregion
+export { MAX_PROJECT_NAME, MAX_RESOURCE_NAME, RESERVED_TEST_PREFIX, assertValidProjectName, fitSegment, hash6, isReservedProjectName, isValidProjectName, kebab, resourceName };

package/dist/naming/resourceNames.d.ts

@@ -0,0 +1,83 @@
+import { type FeatureIdentity, type FeatureResourceKind } from "./feature";
+/**
+ * Every Cloudflare name a project composes, behind one object — **the facade**.
+ *
+ * The free functions underneath are correct and stay exported, but they share one flaw: each takes a
+ * budget, so every call site decides for itself which limit applies. That is how one number, 63, ended
+ * up standing in for eight different namespaces. Here the budget is not an argument at all. You pick a
+ * *kind of thing* — a bucket, a KV namespace, a Workflow — and the kind carries its own cap and its own
+ * refuse-or-truncate policy from `./limits`. There is no wrong budget to pass, because there is no
+ * budget to pass.
+ *
+ * **Shape: project, then scope, then kind.**
+ *
+ * ```ts
+ * const names = resourceNames(config.name);   // the project, validated once
+ * const prod = names.env("prod");             // the environment, validated once
+ * prod.d1("DB");                              // acme-prod-db
+ * prod.workflow("email", "send");             // acme-prod-email-send
+ * names.global.secretEntry("secrets-manager-cf-api-token");
+ * names.feature({ issue, slug }).resource("DB", "d1");
+ * ```
+ *
+ * Three reasons for that order rather than a flat `worker(capability, env)`:
+ *
+ * 1. **Each thing is validated once, at the point it is named.** A bad project fails at
+ *    `resourceNames`, before a single name exists; a bad environment fails at `env`, not on the fourth
+ *    getter that happened to use it.
+ * 2. **The environment is threaded once, not through every call.** Commands are environment-scoped —
+ *    `pithy deploy --env prod` names a dozen resources in one environment — so binding it once removes a
+ *    dozen chances to pass the wrong one.
+ * 3. **`global` becomes a property, not a magic string.** It is the same interface as an environment
+ *    (`names.global.secretEntry(…)`), so no call site special-cases the literal, and no call site can
+ *    typo it into a real environment named `globl`.
+ *
+ * The feature shape hangs off the same object for the same reason it exists at all: it is the *other*
+ * scope a project's resources live in, and it shares the project segment with everything above.
+ */
+/** The names available within one scope — an environment, or the global scope beside them. */
+export interface ScopedNames {
+    /** A capability's Worker script — `<project>-<env>-<capability>`. Refused, not truncated, past 63. */
+    worker(capability: string): string;
+    /** One durable job's Workflow — `<project>-<env>-<capability>-<job>`. Refused, not truncated, past 64. */
+    workflow(capability: string, job: string): string;
+    /** A D1 database. No Cloudflare cap; Pithy's ceiling, truncated with a stable hash. */
+    d1(binding: string): string;
+    /** A KV namespace title. Cloudflare's 512, not the 63 this used to be held to. */
+    kv(binding: string): string;
+    /** An R2 bucket. Cloudflare's 63 — the one namespace where that number was always right. */
+    r2(binding: string): string;
+    /** A Vectorize index. 64 bytes, refused rather than truncated: a renamed index has no vectors. */
+    vectorizeIndex(index: string): string;
+    /** A Secrets Store entry. No Cloudflare cap; Pithy's ceiling. */
+    secretEntry(secret: string): string;
+    /** A Cloudflare API token label. No Cloudflare cap; Pithy's ceiling. */
+    apiToken(profile: string): string;
+}
+/** The names a feature environment provisions under, with the project already bound. */
+export interface FeatureNames {
+    /** A feature's D1, KV, or R2 resource — `<project>-f<issue>-<slug>-<binding>-<kind>`. */
+    resource(binding: string, kind: FeatureResourceKind): string;
+    /** A feature's Worker script — `<project>-f<issue>-<slug>-<worker>`. */
+    worker(worker: string): string;
+}
+/** Everything a project can be asked to name. Created once, from the project, by {@link resourceNames}. */
+export interface ProjectNames {
+    /** The kebabbed project name every name below leads with. */
+    readonly project: string;
+    /** The names in one environment. Throws if the environment is not one this scheme accepts. */
+    env(environment: string): ScopedNames;
+    /** The names shared by every environment — the `global` scope, without typing the word. */
+    readonly global: ScopedNames;
+    /** The names a feature environment provisions under. */
+    feature(identity: Omit<FeatureIdentity, "project">): FeatureNames;
+}
+/**
+ * Bind a project to every name it can compose.
+ *
+ * The project is validated here — charset *and* length, the one project rule — so a project that cannot
+ * carry every namespace fails before it has provisioned any of them. That is the whole reason the
+ * project is supplied once instead of per call.
+ */
+export declare function resourceNames(project: string): ProjectNames;
+//# sourceMappingURL=resourceNames.d.ts.map

package/dist/naming/resourceNames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceNames.d.ts","sourceRoot":"","sources":["../../src/naming/resourceNames.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAA0C,MAAM,WAAW,CAAC;AAInH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC1B,sGAAsG;IACtG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAClD,uFAAuF;IACvF,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,kFAAkF;IAClF,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,4FAA4F;IAC5F,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,kGAAkG;IAClG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,iEAAiE;IACjE,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAC7D,wEAAwE;IACxE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,2GAA2G;AAC3G,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAAC;IACtC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,wDAAwD;IACxD,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,YAAY,CAAC;CACnE;AA8DD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAmB3D"}

package/dist/naming/resourceNames.js

@@ -0,0 +1,102 @@
+import { InternalError, ValidationError } from "../error/pithyError.js";
+import { GLOBAL_SCOPE, assertValidEnvironment } from "./environment.js";
+import { NAMESPACE_LIMITS } from "./limits.js";
+import { assertValidProjectName, kebab, resourceName } from "./resource.js";
+import { workflowHostName, workflowScriptName } from "../workflow/naming.js";
+import { featureResourceName, featureWorkerName } from "./feature.js";
+//#region src/naming/resourceNames.ts
+/**
+* Compose `<project>-<scope>-<thing>` under one namespace's rule.
+*
+* A `truncate` namespace hands off to {@link resourceName} with that namespace's cap, so there is still
+* exactly one truncation rule. A `refuse` namespace composes verbatim and throws with the limit named —
+* as an `InternalError`, because by this point the project and scope have both been validated, so an
+* over-long name means author-controlled code asked for one.
+*
+* **The refuse branch here is deliberately not `../workflow/naming`'s**, though both compose
+* `<project>-<scope>-<thing>` and both refuse rather than truncate. They answer different questions: a
+* Workflow or Worker name is assembled from author-controlled capability and job identifiers, so that
+* module *asserts* each segment against `NAME_SEGMENT` and measures the result in **bytes**, the
+* unit Cloudflare states those two limits in. The kinds routed through here are named after a binding
+* or a secret, which is an adopter's string, so it is kebabbed into shape instead. Merging the two would
+* either start mangling a capability name or stop normalizing a binding.
+*/
+function scopedName(project, scope, thing, limit) {
+	if (limit.policy === "truncate") {
+		const name = resourceName({
+			project,
+			env: scope,
+			thing
+		}, limit.maxLength);
+		if (name.length < limit.minLength) throw new InternalError({
+			message: `"${name}" is too short for ${limit.label}.`,
+			action: `Use a longer project, environment, or resource name — ${limit.label} needs ${limit.minLength} characters.`
+		});
+		return name;
+	}
+	const segment = kebab(thing);
+	if (!segment) throw new ValidationError({
+		message: `A name needs something to name.`,
+		detail: `${limit.label} was asked for with an empty segment (raw: ${JSON.stringify(thing)}).`
+	});
+	const name = `${kebab(project)}-${scope}-${segment}`;
+	if (name.length > limit.maxLength) throw new InternalError({
+		message: `"${name}" is ${name.length} characters. ${limit.label[0]?.toUpperCase()}${limit.label.slice(1)} stops at ${limit.maxLength}.`,
+		action: "Shorten the project, environment, or resource name.",
+		detail: `${limit.label} is refused rather than truncated — renaming it after a deploy orphans what it addresses.`
+	});
+	return name;
+}
+/** The getters for one scope. `global` and every environment share this, so nothing special-cases either. */
+function scopedNames(project, scope) {
+	return {
+		worker: (capability) => workflowHostName({
+			project,
+			capability,
+			env: scope
+		}),
+		workflow: (capability, job) => workflowScriptName({
+			project,
+			capability,
+			job,
+			env: scope
+		}),
+		d1: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.d1),
+		kv: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.kv),
+		r2: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.r2),
+		vectorizeIndex: (index) => scopedName(project, scope, index, NAMESPACE_LIMITS.vectorizeIndex),
+		secretEntry: (secret) => scopedName(project, scope, secret, NAMESPACE_LIMITS.secretEntry),
+		apiToken: (profile) => scopedName(project, scope, profile, NAMESPACE_LIMITS.apiToken)
+	};
+}
+/**
+* Bind a project to every name it can compose.
+*
+* The project is validated here — charset *and* length, the one project rule — so a project that cannot
+* carry every namespace fails before it has provisioned any of them. That is the whole reason the
+* project is supplied once instead of per call.
+*/
+function resourceNames(project) {
+	assertValidProjectName(project);
+	const normalized = kebab(project);
+	return {
+		project: normalized,
+		env(environment) {
+			assertValidEnvironment(environment);
+			return scopedNames(normalized, environment);
+		},
+		global: scopedNames(normalized, GLOBAL_SCOPE),
+		feature(identity) {
+			const full = {
+				...identity,
+				project: normalized
+			};
+			return {
+				resource: (binding, kind) => featureResourceName(full, binding, kind),
+				worker: (worker) => featureWorkerName(full, worker)
+			};
+		}
+	};
+}
+//#endregion
+export { resourceNames };

package/dist/naming/segment.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What a single segment of a composed name may look like — one pattern, one home.
+ *
+ * `<project>-<env>-<thing>` is built out of segments, and every one of them answers to the same
+ * shape: a project, an environment, a capability, a job. The pattern lived in three modules,
+ * character for character, which is the arrangement where a rule stops being one rule — an edit to
+ * the environment copy would silently leave the Workflow copy behind, and the two would disagree
+ * about a name the other had already accepted.
+ *
+ * A capability that genuinely needs a different rule should declare its own pattern beside this one
+ * with a comment saying what it allows that this does not, and why. Divergence is a decision, not a
+ * stale copy. `scaffoldProject`'s `WORKER_NAME` is the standing example: a Worker *directory* under
+ * `apps/` may lead with a digit, because it is a package name rather than a Cloudflare name.
+ */
+/**
+ * A lowercase letter, then letters, digits, and single inner hyphens — no leading digit, no
+ * doubled or trailing hyphen, no underscore, no uppercase.
+ *
+ * This is the **strictest** rule of any namespace a name reaches, and therefore the rule for all of
+ * them. Cloudflare Worker script names, Workflow names, and Vectorize indexes must start with a
+ * letter; D1, KV, and R2 would take `1password-clone-dev-db` happily. The loose namespaces are the
+ * ones a project touches first, so holding everything to the strict rule is what keeps a name that
+ * provisions from being a name that cannot deploy.
+ *
+ * Not `/g`: `.test()` on a global regex advances `lastIndex`, and one shared instance would answer
+ * differently on alternate calls. `segment.test.ts` pins that.
+ */
+export declare const NAME_SEGMENT: RegExp;
+//# sourceMappingURL=segment.d.ts.map

package/dist/naming/segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment.d.ts","sourceRoot":"","sources":["../../src/naming/segment.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,QAAkC,CAAC"}

package/dist/naming/segment.js

@@ -0,0 +1,31 @@
+//#region src/naming/segment.ts
+/**
+* What a single segment of a composed name may look like — one pattern, one home.
+*
+* `<project>-<env>-<thing>` is built out of segments, and every one of them answers to the same
+* shape: a project, an environment, a capability, a job. The pattern lived in three modules,
+* character for character, which is the arrangement where a rule stops being one rule — an edit to
+* the environment copy would silently leave the Workflow copy behind, and the two would disagree
+* about a name the other had already accepted.
+*
+* A capability that genuinely needs a different rule should declare its own pattern beside this one
+* with a comment saying what it allows that this does not, and why. Divergence is a decision, not a
+* stale copy. `scaffoldProject`'s `WORKER_NAME` is the standing example: a Worker *directory* under
+* `apps/` may lead with a digit, because it is a package name rather than a Cloudflare name.
+*/
+/**
+* A lowercase letter, then letters, digits, and single inner hyphens — no leading digit, no
+* doubled or trailing hyphen, no underscore, no uppercase.
+*
+* This is the **strictest** rule of any namespace a name reaches, and therefore the rule for all of
+* them. Cloudflare Worker script names, Workflow names, and Vectorize indexes must start with a
+* letter; D1, KV, and R2 would take `1password-clone-dev-db` happily. The loose namespaces are the
+* ones a project touches first, so holding everything to the strict rule is what keeps a name that
+* provisions from being a name that cannot deploy.
+*
+* Not `/g`: `.test()` on a global regex advances `lastIndex`, and one shared instance would answer
+* differently on alternate calls. `segment.test.ts` pins that.
+*/
+const NAME_SEGMENT = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+//#endregion
+export { NAME_SEGMENT };