@pithy-sh/core 0.1.1 → 0.1.3

package/dist/naming/domains.js

@@ -0,0 +1,156 @@
+import { ENVIRONMENTS } from "./environment.js";
+import { z } from "zod";
+//#region src/naming/domains.ts
+/**
+* Where a Worker answers, declared once per Worker per environment.
+*
+* ## The problem this replaces
+*
+* Nothing in `pithy.config.ts` described a Worker's address, so three commands each reconstructed it
+* differently and none of them reconciled: `pithy env` scraped the first `routes` pattern out of
+* `wrangler.jsonc`, `pithy email provision` and `pithy turnstile` read a hand-set `vars.BASE_URL`, and
+* `pithy deploy` scraped the last URL wrangler happened to print. `email provision` refused to run
+* without `vars.BASE_URL` while `pithy env` cheerfully printed a URL derived from routes, and nothing
+* noticed when the two disagreed. Three answers to one question, in one CLI.
+*
+* So the address is declared, and everything else is generated from it — the `routes` entry with
+* `custom_domain` and `zone_name`, and `vars.BASE_URL`. `BASE_URL` stays a wrangler var because the
+* **Worker reads it at runtime**: `@pithy-sh/email` builds tracking and unsubscribe links against it and
+* Turnstile binds its widget to that domain. What changes is that it is derived rather than hand-set and
+* able to contradict the routes beside it.
+*
+* ## Per Worker, per environment
+*
+* Per Worker because each serves its own hostname. Per environment because `staging.api.example.com` and
+* `api.example.com` are one Worker in two environments, and `env.<name>` stanzas in `wrangler.jsonc`
+* replace rather than merge — so one declaration has to fan out to all of them.
+*
+* ## `dev` carries no domain
+*
+* Deliberately absent from the accepted keys. Local answers on `http://localhost:<port>` from the port
+* the feature's `.dev.config.json` pinned at creation, and a domain there would be a second answer to a
+* question the port allocator already answers. `requireManagedEnvironment` refuses `dev` for the same
+* reason everywhere else.
+*/
+/** A hostname a Worker answers on. No scheme, no path, no port — wrangler's `routes` pattern is a host. */
+const HOSTNAME_PATTERN = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/;
+/** The environments a domain may be declared for — every managed one, never `dev`. */
+const DOMAIN_ENVIRONMENTS = ENVIRONMENTS.filter((environment) => environment !== "dev");
+/** One environment's public address for one Worker. */
+const WorkerDomain = z.object({
+	pattern: z.string().regex(HOSTNAME_PATTERN, "A domain is a bare hostname — no scheme, no path, no port (e.g. `api.example.com`, not `https://api.example.com/`).").describe("The hostname this Worker answers on in this environment, e.g. `api.example.com`. Written into `wrangler.jsonc` as a `routes` entry with `custom_domain: true`, and into `vars.BASE_URL` as `https://<pattern>`. A bare hostname rather than a URL, because that is what wrangler's route matcher takes — a scheme here would be silently wrong."),
+	zone: z.string().regex(HOSTNAME_PATTERN, "A zone is the registrable domain on your Cloudflare account, e.g. `example.com`.").describe("The Cloudflare zone `pattern` sits under — the registrable domain as it appears on your account, e.g. `example.com` for `api.example.com`. Cloudflare needs it to attach a custom domain, and it is not always derivable from the hostname: a zone can be a subdomain, and a public-suffix guess would be wrong for exactly the adopters who are hardest to debug.")
+}).describe("Where one Worker answers in one environment: the hostname, and the Cloudflare zone it sits under.").check((ctx) => {
+	const { pattern, zone } = ctx.value;
+	if (pattern !== zone && !pattern.endsWith(`.${zone}`)) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["pattern"],
+		message: `The domain \`${pattern}\` is not inside the zone \`${zone}\`. A custom domain must sit on the zone it names — set \`zone\` to the registrable domain \`${pattern}\` belongs to.`
+	});
+});
+/**
+* A Worker's domains, keyed by environment.
+*
+* Every key optional: a project with no domain yet is legitimate, and so is one that has staging wired
+* and production not. Adding one later is a config edit plus a deploy, never a rescaffold.
+*/
+const WorkerDomains = z.object({
+	staging: WorkerDomain.optional().describe("Where this Worker answers in `staging`, if it has a domain yet."),
+	prod: WorkerDomain.optional().describe("Where this Worker answers in `prod`, if it has a domain yet.")
+}).describe("Where this Worker answers, per environment. `dev` is absent by design — local runs on `http://localhost:<port>` from the port pinned in `.dev.config.json`. Everything else is generated from this: the `routes` entry with `custom_domain` and `zone_name`, and `vars.BASE_URL`.");
+/**
+* The declared domain for one environment, or null where none is declared (including every `dev`).
+*
+* `environment` may be `undefined`, which is what `compositionEnvironment()` answers when nothing stamped
+* one. That is not a `dev` default — it is "this composition names no environment", and an environment
+* nobody named has declared no domain, so the answer is the same `null` an undeclared one gets.
+*/
+function domainFor(domains, environment) {
+	if (!domains) return null;
+	if (environment === "staging") return domains.staging ?? null;
+	if (environment === "prod") return domains.prod ?? null;
+	return null;
+}
+/** The base URL a declared domain implies. Always `https` — a custom domain on Cloudflare is TLS-terminated. */
+function baseUrlFor(domain) {
+	return `https://${domain.pattern}`;
+}
+/**
+* The origin an environment with no declared domain resolves to.
+*
+* **No port, and that is the whole design.** Local dev's port is assigned per Worker per run from the
+* feature's reserved block, so it is the one address nobody can write down — `@pithy-sh/auth` resolves
+* dev's base URL from the host the request arrived at for exactly that reason, and a config-time value
+* could only ever be a stale guess at it. So this is a *placeholder that fails closed*: a link built
+* against it goes nowhere, which is useless rather than harmful.
+*
+* Compare what it replaces. Every capability that made an adopter write an origin got production's
+* written into staging, and the failure was never "the link is broken" — it was a staging deploy mailing
+* real users magic links **into production**, an unsubscribe from a staging test unsubscribing that
+* person in production, and a Checkout return landing a staging payer in production on an account that
+* had bought nothing. A fallback that goes nowhere is the only one that cannot do any of that.
+*/
+const LOCAL_ORIGIN = "http://localhost";
+/**
+* **Where is this Worker publicly reachable, in this environment?** — asked once, answered once.
+*
+* The two halves already existed ({@link domainFor} and {@link baseUrlFor}) and nothing composed them,
+* so every caller that needed the answer did the two-step for itself and every *adopter* who needed it
+* wrote a URL down. The first adopter's one Worker config carried `https://app.pithy.sh` three times —
+* `auth.baseURL`, `email.baseUrl`, and the Stripe return URLs — each wrong for staging in its own way,
+* each found on a different day. Fixing it inside one capability does not stop the next capability
+* asking the same question, so the question gets one answer that anyone can call.
+*
+* **The fallback never reaches for another environment's origin.** An environment absent from `domains`
+* is one that is not published, so it resolves to {@link LOCAL_ORIGIN} and nothing else. Falling back to
+* production's is what the shape being replaced did, and it is the one behavior here that was actively
+* dangerous rather than merely wrong.
+*
+* **A deployed environment must never *keep* that fallback**, and it is not this function's job to say
+* so — `pithy deploy --env <name>` refuses an environment whose origin its config does not declare
+* (#253), and `pithy doctor` reports it first. One rule in two halves: this one cannot invent another
+* environment's origin, and deploy makes sure the placeholder never ships.
+*
+* **Not every origin should derive from this, and `controlplane.issuer` is the one to name.** That is an
+* **identity**, not an address: a connection stores the issuer it was created with and verification
+* checks that stored value, so a per-environment issuer would make a connection minted in staging
+* unverifiable in production. That may be the better isolation, but it is a decision about trust rather
+* than about reachability, and a helper whose job is "where am I reachable" must not sweep it up.
+*/
+function resolveOrigin(environment, domains) {
+	const domain = domainFor(domains, environment);
+	if (domain) return {
+		origin: baseUrlFor(domain),
+		hostname: domain.pattern,
+		declared: true
+	};
+	return {
+		origin: LOCAL_ORIGIN,
+		hostname: "localhost",
+		declared: false
+	};
+}
+/**
+* The one line an adopter writes: this Worker's public origin for the environment it is running in.
+*
+* ```ts
+* const DOMAINS = { staging: { … }, prod: { … } };
+* const PUBLIC_ORIGIN = originFor(compositionEnvironment(), DOMAINS);
+* ```
+*
+* That is the line `pithy init` scaffolds, so an adopter who never thinks about it gets it right and one
+* who wants a literal can still write one. `compositionEnvironment()` is `string | undefined`, and it is
+* taken as such rather than defaulted to `dev` at the call site: an unstamped composition has declared no
+* domain either way, and a `?? "dev"` in every adopter's config would be a default nobody chose.
+*
+* Named for what it is rather than for who asked. The first adopter's own version was called
+* `AUTH_BASE_URL`, which is part of why `email` and `payments` were missed for days: the constant read
+* as auth's private business when it is the Worker's address, and every capability that needs an origin
+* needs this one.
+*/
+function originFor(environment, domains) {
+	return resolveOrigin(environment, domains).origin;
+}
+//#endregion
+export { DOMAIN_ENVIRONMENTS, LOCAL_ORIGIN, WorkerDomain, WorkerDomains, baseUrlFor, domainFor, originFor, resolveOrigin };

package/dist/naming/environment.d.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+/**
+ * What an environment may be called, in one module.
+ *
+ * An environment name is not decoration: it sits in the middle of every Cloudflare name a project
+ * composes (`<project>-<env>-<thing>`), so its length is subtracted from every other segment's
+ * budget, and its characters have to be legal in every namespace Pithy writes into. Until this
+ * module existed, `--env` was a bare string that nothing checked — a fourteen-character environment
+ * quietly ate the room a project name had already been accepted against.
+ */
+/**
+ * The three first-class environments: local `dev`, `staging` for test users, `prod` for paid ones.
+ *
+ * **`prod`, not `production`.** The long form cost three characters of every project name, in a
+ * budget where thirty-three was the ceiling, and bought nothing a four-letter word does not say.
+ */
+export declare const ENVIRONMENTS: readonly ["dev", "staging", "prod"];
+/** One of Pithy's first-class environments. A custom environment is a `string`, and still validated. */
+export type Environment = (typeof ENVIRONMENTS)[number];
+/**
+ * The scope that sits beside the environments: one value shared by all of them.
+ *
+ * It occupies the same slot as an environment in a composed name, which is exactly why an
+ * environment may not be *called* `global` — a project would then have one set of names for two
+ * different scopes, and teardown could not tell them apart.
+ */
+export declare const GLOBAL_SCOPE = "global";
+/**
+ * The environment one branch gets — the `env.feature` stanza a feature's provisioning run writes into.
+ *
+ * **A legal environment name, and never a declared one.** Legal because it is a real wrangler stanza
+ * key, so every rule that governs a key governs it: seven characters, which is
+ * {@link MAX_ENVIRONMENT_NAME} exactly. Never declared because the two kinds of environment write to
+ * different files — a declared environment's ids are source, in the tracked `wrangler.jsonc`; a
+ * feature's are a build artifact under `.wrangler/`. A project that declared this name would own two
+ * files claiming one stanza, and the resolver that picks between them answers "generated" for this
+ * name — so a migrate would read bytes no provisioning run wrote.
+ *
+ * It lives here rather than beside the scope that uses it because it is first an environment name, and
+ * because {@link DeclaredEnvironments} has to refuse it: a constant defined downstream of the schema
+ * that rejects it would be a cycle.
+ */
+export declare const FEATURE_ENVIRONMENT = "feature";
+/**
+ * The longest an environment name may be — **the longest canonical one, `staging`**.
+ *
+ * This is a derivation input, not a preference: `WORKFLOW_DERIVED_PROJECT_NAME` and
+ * `FEATURE_DERIVED_PROJECT_NAME` are both computed against it, so every project name Pithy has ever
+ * accepted was accepted on the assumption that no environment exceeds it. Letting a custom
+ * environment run longer would retroactively shrink that cap — and a provisioned project cannot be
+ * renamed. So a longer environment is refused here, at the one place that can still say no.
+ *
+ * Read off {@link ENVIRONMENTS} rather than typed, so adding an environment cannot leave the two
+ * disagreeing.
+ */
+export declare const MAX_ENVIRONMENT_NAME: number;
+/**
+ * Is this a name an environment may carry?
+ *
+ * **Read raw, never kebabbed** — and that is the difference between this rule and the project rule.
+ * A project name is prose an adopter types once into `pithy.config.ts`, so `Acme Corp` is politely
+ * composed into `acme-corp`. An environment is an identifier repeated in `--env`, in
+ * `.dev.vars.<environment>`, and in a wrangler environment key; normalizing `Prod` to `prod` would
+ * make two spellings name one environment in some places and two in others.
+ */
+export declare function isValidEnvironment(name: string): boolean;
+/**
+ * Refuse a name no environment may carry, as a `ValidationError` — an environment comes from a flag
+ * or a config file, so it is a 400 with an action, never an internal fault.
+ *
+ * Three different mistakes get three different sentences, because "invalid environment" helps with
+ * none of them: `production` is the old spelling and gets the new one, a long name gets the number,
+ * and anything else gets the charset.
+ */
+export declare function assertValidEnvironment(name: string): void;
+/**
+ * The environments a project has when it declares nothing: `staging` for test users, `prod` for paid ones.
+ *
+ * The same two {@link ENVIRONMENTS} names minus `dev`, and the same two the starter scaffolded from a
+ * hardcoded template before anything could say otherwise — so a project that never opens this setting
+ * gets exactly what it got before.
+ */
+export declare const DEFAULT_ENVIRONMENTS: readonly ["staging", "prod"];
+/**
+ * The local environment. Never declared: it is the top-level wrangler stanza, and it always exists.
+ *
+ * Exported because "always exists and is never declared" is a fact other code has to act on, not only a
+ * rule this schema enforces. Anything deriving something over *every* environment a project has must add
+ * this one itself — {@link DeclaredEnvironments} will never hand it over — and a caller spelling `"dev"`
+ * inline is a caller that can spell it differently.
+ */
+export declare const LOCAL_ENVIRONMENT = "dev";
+/**
+ * **The set of deployed environments a project has**, declared once in the root `pithy.config.ts`.
+ *
+ * Until this existed a project never said. The set lived only as `env.<name>` stanzas in each Worker's
+ * `wrangler.jsonc` — per Worker, so two Workers in one project could disagree and nothing reconciled them
+ * — while `ManagedEnvironment` held a closed enum of two and `seed.productionEnvironments` invited a
+ * project to name a third. An adopter adding `env.live` got `pithy migrate --env live` working and
+ * `pithy secrets provision` skipping it in silence, because the three answers were never the same answer.
+ *
+ * **Ordered, and the order is meaningful.** It is the order provisioning walks — least-production first,
+ * so a mistake is made in staging before it is made in prod — and the last entry is the one a
+ * `global` account-level secret is written through (see `@pithy-sh/secrets`'s `resolveWriteTargets`).
+ * `["staging", "prod"]` therefore behaves exactly as the hardcoded pair did.
+ *
+ * **`dev` is not declarable.** It is local, it is the top-level wrangler stanza rather than an `env.dev`,
+ * and it resolves from Miniflare rather than an account — so a project always has it and provisioning
+ * never has it. Declaring it would ask a deploy to happen for an environment that never deploys.
+ *
+ * **Nothing is renamed by editing this.** `<project>-<env>-<thing>` is computed from the declaration and
+ * never stored, so changing a name here orphans everything already provisioned under the old one, exactly
+ * as renaming `name` does. `pithy doctor` reports the change rather than applying it.
+ */
+export declare const DeclaredEnvironments: z.ZodArray<z.ZodString>;
+/** Every deployed environment a project has. Same name as its schema, as every Zod object here is. */
+export type DeclaredEnvironments = z.output<typeof DeclaredEnvironments>;
+//# sourceMappingURL=environment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/naming/environment.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAI,KAAK,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAEhE,wGAAwG;AACxG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,QAAqE,CAAC;AAEvG;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CA4BzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,YAAI,SAAS,EAAE,MAAM,CAAU,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,yBA2D9B,CAAC;AAEJ,sGAAsG;AACtG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/naming/environment.js

@@ -0,0 +1,190 @@
+import { NAME_SEGMENT } from "./segment.js";
+import { PithyError, ValidationError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/naming/environment.ts
+/**
+* What an environment may be called, in one module.
+*
+* An environment name is not decoration: it sits in the middle of every Cloudflare name a project
+* composes (`<project>-<env>-<thing>`), so its length is subtracted from every other segment's
+* budget, and its characters have to be legal in every namespace Pithy writes into. Until this
+* module existed, `--env` was a bare string that nothing checked — a fourteen-character environment
+* quietly ate the room a project name had already been accepted against.
+*/
+/**
+* The three first-class environments: local `dev`, `staging` for test users, `prod` for paid ones.
+*
+* **`prod`, not `production`.** The long form cost three characters of every project name, in a
+* budget where thirty-three was the ceiling, and bought nothing a four-letter word does not say.
+*/
+const ENVIRONMENTS = [
+	"dev",
+	"staging",
+	"prod"
+];
+/**
+* The scope that sits beside the environments: one value shared by all of them.
+*
+* It occupies the same slot as an environment in a composed name, which is exactly why an
+* environment may not be *called* `global` — a project would then have one set of names for two
+* different scopes, and teardown could not tell them apart.
+*/
+const GLOBAL_SCOPE = "global";
+/**
+* The environment one branch gets — the `env.feature` stanza a feature's provisioning run writes into.
+*
+* **A legal environment name, and never a declared one.** Legal because it is a real wrangler stanza
+* key, so every rule that governs a key governs it: seven characters, which is
+* {@link MAX_ENVIRONMENT_NAME} exactly. Never declared because the two kinds of environment write to
+* different files — a declared environment's ids are source, in the tracked `wrangler.jsonc`; a
+* feature's are a build artifact under `.wrangler/`. A project that declared this name would own two
+* files claiming one stanza, and the resolver that picks between them answers "generated" for this
+* name — so a migrate would read bytes no provisioning run wrote.
+*
+* It lives here rather than beside the scope that uses it because it is first an environment name, and
+* because {@link DeclaredEnvironments} has to refuse it: a constant defined downstream of the schema
+* that rejects it would be a cycle.
+*/
+const FEATURE_ENVIRONMENT = "feature";
+/**
+* The longest an environment name may be — **the longest canonical one, `staging`**.
+*
+* This is a derivation input, not a preference: `WORKFLOW_DERIVED_PROJECT_NAME` and
+* `FEATURE_DERIVED_PROJECT_NAME` are both computed against it, so every project name Pithy has ever
+* accepted was accepted on the assumption that no environment exceeds it. Letting a custom
+* environment run longer would retroactively shrink that cap — and a provisioned project cannot be
+* renamed. So a longer environment is refused here, at the one place that can still say no.
+*
+* Read off {@link ENVIRONMENTS} rather than typed, so adding an environment cannot leave the two
+* disagreeing.
+*/
+const MAX_ENVIRONMENT_NAME = Math.max(...ENVIRONMENTS.map((environment) => environment.length));
+/**
+* Is this a name an environment may carry?
+*
+* **Read raw, never kebabbed** — and that is the difference between this rule and the project rule.
+* A project name is prose an adopter types once into `pithy.config.ts`, so `Acme Corp` is politely
+* composed into `acme-corp`. An environment is an identifier repeated in `--env`, in
+* `.dev.vars.<environment>`, and in a wrangler environment key; normalizing `Prod` to `prod` would
+* make two spellings name one environment in some places and two in others.
+*/
+function isValidEnvironment(name) {
+	if (name === "global") return false;
+	return name.length <= MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name);
+}
+/**
+* Refuse a name no environment may carry, as a `ValidationError` — an environment comes from a flag
+* or a config file, so it is a 400 with an action, never an internal fault.
+*
+* Three different mistakes get three different sentences, because "invalid environment" helps with
+* none of them: `production` is the old spelling and gets the new one, a long name gets the number,
+* and anything else gets the charset.
+*/
+function assertValidEnvironment(name) {
+	if (isValidEnvironment(name)) return;
+	if (name === "production") throw new ValidationError({
+		message: `"production" is not an environment name in Pithy.`,
+		action: "Use `prod`.",
+		detail: `An environment stops at ${MAX_ENVIRONMENT_NAME} characters, the length of the longest of ${ENVIRONMENTS.join(", ")}.`
+	});
+	if (name === "global") throw new ValidationError({
+		message: `"${GLOBAL_SCOPE}" is a scope, not an environment.`,
+		action: `Name the environment one of ${ENVIRONMENTS.join(", ")}.`,
+		detail: `${GLOBAL_SCOPE} occupies the environment slot of a composed name for values shared across every environment.`
+	});
+	if (name.length > MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name)) throw new ValidationError({
+		message: `"${name}" is ${name.length} characters. An environment stops at ${MAX_ENVIRONMENT_NAME}.`,
+		action: `Use one of ${ENVIRONMENTS.join(", ")}, or a shorter name.`,
+		detail: `Every project-name budget is derived against a ${MAX_ENVIRONMENT_NAME}-character environment, and a provisioned project cannot be renamed.`
+	});
+	throw new ValidationError({
+		message: `"${name}" can't be an environment name.`,
+		action: "Use lowercase letters, digits, and single hyphens, starting with a letter.",
+		detail: `An environment is used verbatim in Cloudflare resource names, so it must match ${NAME_SEGMENT.source}.`
+	});
+}
+/**
+* The environments a project has when it declares nothing: `staging` for test users, `prod` for paid ones.
+*
+* The same two {@link ENVIRONMENTS} names minus `dev`, and the same two the starter scaffolded from a
+* hardcoded template before anything could say otherwise — so a project that never opens this setting
+* gets exactly what it got before.
+*/
+const DEFAULT_ENVIRONMENTS = ["staging", "prod"];
+/**
+* The local environment. Never declared: it is the top-level wrangler stanza, and it always exists.
+*
+* Exported because "always exists and is never declared" is a fact other code has to act on, not only a
+* rule this schema enforces. Anything deriving something over *every* environment a project has must add
+* this one itself — {@link DeclaredEnvironments} will never hand it over — and a caller spelling `"dev"`
+* inline is a caller that can spell it differently.
+*/
+const LOCAL_ENVIRONMENT = "dev";
+/**
+* **The set of deployed environments a project has**, declared once in the root `pithy.config.ts`.
+*
+* Until this existed a project never said. The set lived only as `env.<name>` stanzas in each Worker's
+* `wrangler.jsonc` — per Worker, so two Workers in one project could disagree and nothing reconciled them
+* — while `ManagedEnvironment` held a closed enum of two and `seed.productionEnvironments` invited a
+* project to name a third. An adopter adding `env.live` got `pithy migrate --env live` working and
+* `pithy secrets provision` skipping it in silence, because the three answers were never the same answer.
+*
+* **Ordered, and the order is meaningful.** It is the order provisioning walks — least-production first,
+* so a mistake is made in staging before it is made in prod — and the last entry is the one a
+* `global` account-level secret is written through (see `@pithy-sh/secrets`'s `resolveWriteTargets`).
+* `["staging", "prod"]` therefore behaves exactly as the hardcoded pair did.
+*
+* **`dev` is not declarable.** It is local, it is the top-level wrangler stanza rather than an `env.dev`,
+* and it resolves from Miniflare rather than an account — so a project always has it and provisioning
+* never has it. Declaring it would ask a deploy to happen for an environment that never deploys.
+*
+* **Nothing is renamed by editing this.** `<project>-<env>-<thing>` is computed from the declaration and
+* never stored, so changing a name here orphans everything already provisioned under the old one, exactly
+* as renaming `name` does. `pithy doctor` reports the change rather than applying it.
+*/
+const DeclaredEnvironments = z.array(z.string().describe("One deployed environment's name, used verbatim in the middle of every Cloudflare name the project composes and in each Worker's `env.<name>` wrangler stanza.")).check((ctx) => {
+	if (ctx.value.length === 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		message: `Declare at least one environment. A project with none can never deploy — ${DEFAULT_ENVIRONMENTS.join(" and ")} is the default.`
+	});
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of ctx.value) {
+		if (name === "dev") {
+			ctx.issues.push({
+				code: "custom",
+				input: ctx.value,
+				message: `"dev" is local and always present, so it is never declared. List only the environments this project deploys.`
+			});
+			continue;
+		}
+		if (name === "feature") {
+			ctx.issues.push({
+				code: "custom",
+				input: ctx.value,
+				message: `"${FEATURE_ENVIRONMENT}" is the environment a branch gets, and its config is generated rather than committed. Declaring it would give one stanza two owners.`
+			});
+			continue;
+		}
+		if (seen.has(name)) {
+			ctx.issues.push({
+				code: "custom",
+				input: ctx.value,
+				message: `"${name}" is declared twice. One environment is one set of Cloudflare names.`
+			});
+			continue;
+		}
+		seen.add(name);
+		try {
+			assertValidEnvironment(name);
+		} catch (error) {
+			ctx.issues.push({
+				code: "custom",
+				input: ctx.value,
+				message: error instanceof PithyError ? error.payload.message : `"${name}" can't be an environment name.`
+			});
+		}
+	}
+}).describe("Every deployed environment this project has, in the order provisioning walks them — least-production first. Declared once in the root pithy.config.ts, because the set cannot be per-Worker. `dev` is never listed: it is local and always present.");
+//#endregion
+export { DEFAULT_ENVIRONMENTS, DeclaredEnvironments, ENVIRONMENTS, FEATURE_ENVIRONMENT, GLOBAL_SCOPE, LOCAL_ENVIRONMENT, MAX_ENVIRONMENT_NAME, assertValidEnvironment, isValidEnvironment };

package/dist/naming/feature.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The names a feature environment provisions under: `<project>-f<issue>-<slug>-<binding>-<kind>` for a
+ * resource, `<project>-f<issue>-<slug>-<worker>` for a Worker script.
+ *
+ * **No environment segment, and no Worker segment.** A feature *is* an environment, and two Workers that
+ * declare the same binding are meant to share one resource — so the binding name, not the topology, is
+ * where sharing is expressed.
+ *
+ * Every name here is **derived and recomputed**, never stored: `provision` and `destroy` both compute the
+ * same string from `(identity, binding, kind)`, which is what lets teardown reconcile exactly rather than
+ * scan a prefix a hyphenated sibling slug could ambiguously match. That is also why these names
+ * **truncate** where a capability's Workflow refuses: a feature name addresses nothing that outlives the
+ * feature, and failing a CI run because a branch slug was long would be the worse failure.
+ *
+ * It lives in `core`, beside the rest of the naming rule, so the CLI and the facade compose one
+ * implementation rather than two that drift.
+ */
+/** A Cloudflare resource kind a feature can provision. All two characters — `MAX_FEATURE_KIND` in `./limits`. */
+export type FeatureResourceKind = "d1" | "kv" | "r2";
+/** Every feature resource kind, for tests and for callers that enumerate. */
+export declare const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[];
+/** The identity of a feature — everything a feature name is derived from. */
+export interface FeatureIdentity {
+    /** The project name, from the root `pithy.config.ts` (e.g. `acme`). */
+    project: string;
+    /** The issue number as a string (e.g. `69`). Digits only, up to {@link MAX_ISSUE_DIGITS}. */
+    issue: string;
+    /** The kebab-case feature slug, from the branch (e.g. `media-cli`). */
+    slug: string;
+}
+/**
+ * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>-<binding>-<kind>`.
+ *
+ * Held to **R2's 63**, the strictest of the three kinds a feature provisions, so one shape is legal for
+ * all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
+ * feature that provisions a bucket and a database wants them recognizably the same name.
+ */
+export declare function featureResourceName(identity: FeatureIdentity, binding: string, kind: FeatureResourceKind): string;
+/**
+ * The CF Secrets Store entry name holding one of a feature's **environment-scoped** secrets —
+ * `<project>-f<issue>-<slug>-<secret>`.
+ *
+ * A Cloudflare account has one Secrets Store, flat and unpartitionable, so the entry name is the only
+ * partition there is. A feature therefore needs its own names for the same reason it needs its own
+ * database: without them a branch would adopt staging's master key, and its teardown would delete it.
+ *
+ * Held to the **Secrets Store** limit rather than R2's 63, like every other entry name — an entry has
+ * no documented Cloudflare cap, and holding it to the strictest kind's would hash
+ * `secrets-encryption-keys` down to nothing for no reason.
+ *
+ * A `global` secret is not named here at all: it is one account-level value every environment binds,
+ * so a feature binds the project's `<project>-global-<secret>` rather than minting a second copy.
+ */
+export declare function featureSecretEntryName(identity: FeatureIdentity, secret: string): string;
+/**
+ * The Worker **script name** for one of a feature's workers — `<project>-f<issue>-<slug>-<worker>`.
+ *
+ * This is the name the feature's Workers deploy under, and therefore the name a sibling's `service`
+ * binding must target, so RPC inside a feature environment reaches that feature's deployment rather than
+ * production's.
+ *
+ * Held to the **Worker rule** ({@link NAMESPACE_LIMITS.worker}), which is the bug this used to have: it
+ * floored the slug at one character and never touched the worker segment, so it ran unbounded — 69
+ * characters for a worker called `collaboration-realtime-gateway`, 109 for a 70-character one. `apps/<name>`
+ * has a charset rule and no length rule, so nothing upstream was going to stop it either.
+ */
+export declare function featureWorkerName(identity: FeatureIdentity, worker: string): string;
+//# sourceMappingURL=feature.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feature.d.ts","sourceRoot":"","sources":["../../src/naming/feature.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AAEH,iHAAiH;AACjH,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAAuB,CAAC;AAEzF,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACd;AAkED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAQjH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnF"}

package/dist/naming/feature.js

@@ -0,0 +1,106 @@
+import { ValidationError } from "../error/pithyError.js";
+import { NAMESPACE_LIMITS } from "./limits.js";
+import { assertValidProjectName, fitSegment, kebab } from "./resource.js";
+//#region src/naming/feature.ts
+/** Every feature resource kind, for tests and for callers that enumerate. */
+const FEATURE_RESOURCE_KINDS = [
+	"d1",
+	"kv",
+	"r2"
+];
+/** Below this the slug segment isn't worth keeping legible; the trailing segment is truncated to give it room. */
+const MIN_SLUG_BUDGET = 3;
+/**
+* Refuse an issue number the budgets were not derived against.
+*
+* `MAX_ISSUE_DIGITS` is a term in {@link FEATURE_DERIVED_PROJECT_NAME}, so an eight-digit issue would
+* quietly spend a character every project name was already accepted against. It is also the cheapest
+* possible check that the value is an issue number at all — `featureResourceName` used to interpolate
+* whatever string it was handed straight into a Cloudflare name.
+*/
+function assertIssue(issue) {
+	if (new RegExp(`^[0-9]{1,6}$`).test(issue)) return;
+	throw new ValidationError({
+		message: `"${issue}" is not an issue number.`,
+		action: `Use the issue's digits, up to 6 of them.`,
+		detail: `Feature resource names reserve 6 digits, and every project-name budget is derived against that.`
+	});
+}
+/** The `<project>-f<issue>` head both feature shapes share, with the project held to the one project rule. */
+function head(identity) {
+	assertValidProjectName(identity.project);
+	assertIssue(identity.issue);
+	return `${kebab(identity.project)}-f${identity.issue}`;
+}
+/**
+* Fit `<head>-<slug>-<tail><fixed>` into `budget`, truncating the slug first and the tail only if the
+* tail is what is eating the name. `fixed` is never touched — it carries the kind suffix, which is the
+* only thing telling a `DB` bucket from a `DB` database.
+*
+* Deterministic in its inputs and hash-disambiguated on both variable segments, so two long inputs
+* sharing a prefix still produce two different names.
+*/
+function composeFeatureName(headSegment, slug, tail, fixed, budget) {
+	for (const [role, value] of [["slug", slug], ["binding or worker", tail]]) {
+		if (value) continue;
+		throw new ValidationError({
+			message: `A feature resource name needs a ${role}.`,
+			action: "Use letters, digits, and hyphens — something that survives kebabbing.",
+			detail: `composeFeatureName received an empty ${role} segment for "${headSegment}".`
+		});
+	}
+	const inner = budget - fixed.length;
+	let tailSegment = tail;
+	let slugBudget = inner - headSegment.length - 1 - (1 + tailSegment.length);
+	if (slugBudget < MIN_SLUG_BUDGET) {
+		const tailBudget = inner - headSegment.length - 1 - MIN_SLUG_BUDGET - 1;
+		tailSegment = fitSegment(tailSegment, Math.max(1, tailBudget));
+		slugBudget = inner - headSegment.length - 1 - (1 + tailSegment.length);
+	}
+	return `${headSegment}-${fitSegment(slug, Math.max(1, slugBudget))}-${tailSegment}${fixed}`;
+}
+/**
+* The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>-<binding>-<kind>`.
+*
+* Held to **R2's 63**, the strictest of the three kinds a feature provisions, so one shape is legal for
+* all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
+* feature that provisions a bucket and a database wants them recognizably the same name.
+*/
+function featureResourceName(identity, binding, kind) {
+	return composeFeatureName(head(identity), kebab(identity.slug), kebab(binding), `-${kind}`, NAMESPACE_LIMITS.r2.maxLength);
+}
+/**
+* The CF Secrets Store entry name holding one of a feature's **environment-scoped** secrets —
+* `<project>-f<issue>-<slug>-<secret>`.
+*
+* A Cloudflare account has one Secrets Store, flat and unpartitionable, so the entry name is the only
+* partition there is. A feature therefore needs its own names for the same reason it needs its own
+* database: without them a branch would adopt staging's master key, and its teardown would delete it.
+*
+* Held to the **Secrets Store** limit rather than R2's 63, like every other entry name — an entry has
+* no documented Cloudflare cap, and holding it to the strictest kind's would hash
+* `secrets-encryption-keys` down to nothing for no reason.
+*
+* A `global` secret is not named here at all: it is one account-level value every environment binds,
+* so a feature binds the project's `<project>-global-<secret>` rather than minting a second copy.
+*/
+function featureSecretEntryName(identity, secret) {
+	return composeFeatureName(head(identity), kebab(identity.slug), kebab(secret), "", NAMESPACE_LIMITS.secretEntry.maxLength);
+}
+/**
+* The Worker **script name** for one of a feature's workers — `<project>-f<issue>-<slug>-<worker>`.
+*
+* This is the name the feature's Workers deploy under, and therefore the name a sibling's `service`
+* binding must target, so RPC inside a feature environment reaches that feature's deployment rather than
+* production's.
+*
+* Held to the **Worker rule** ({@link NAMESPACE_LIMITS.worker}), which is the bug this used to have: it
+* floored the slug at one character and never touched the worker segment, so it ran unbounded — 69
+* characters for a worker called `collaboration-realtime-gateway`, 109 for a 70-character one. `apps/<name>`
+* has a charset rule and no length rule, so nothing upstream was going to stop it either.
+*/
+function featureWorkerName(identity, worker) {
+	return composeFeatureName(head(identity), kebab(identity.slug), kebab(worker), "", NAMESPACE_LIMITS.worker.maxLength);
+}
+//#endregion
+export { FEATURE_RESOURCE_KINDS, featureResourceName, featureSecretEntryName, featureWorkerName };