@pithy-sh/core 0.1.2 → 0.1.4

package/dist/naming/limits.d.ts

@@ -0,0 +1,229 @@
+/**
+ * What Cloudflare will actually accept as a name, per namespace — and, where it publishes nothing,
+ * what Pithy chooses instead.
+ *
+ * Pithy used to hold one number, 63, against every namespace it writes into, justified as "R2's
+ * cap". That is true of R2 and of nothing else. It over-truncated a KV title by a factor of eight
+ * and truncated D1 databases, Secrets Store entries, and API token labels against limits that do
+ * not exist — `secrets-encryption-keys` came out of it as `secrets-encryp-91c2e9`, hashed for
+ * nothing. A truncated name is not merely ugly: it is the name teardown must recompute exactly, and
+ * the name a human has to recognize in a dashboard listing that cannot be filtered.
+ *
+ * Every row below carries its source. `cloudflare` means the number is documented (limits page,
+ * OpenAPI schema, or wrangler's own constant, verified 2026-07-31); `pithy` means Cloudflare
+ * publishes no cap and this is our ceiling, chosen and stated as ours.
+ */
+/** Where a limit comes from — Cloudflare's documentation, or Pithy's own judgment. */
+export type LimitSource = "cloudflare" | "pithy";
+/**
+ * What to do with a name that will not fit.
+ *
+ * **`refuse`** where the name is a durable address: a Workflow (renaming orphans every running
+ * instance), a Worker script (renaming orphans the deployment and every `service` binding pointing
+ * at it), a Vectorize index (renaming orphans the vectors — they cannot be re-embedded for free).
+ * A build error naming the limit is strictly better than a silent rename.
+ *
+ * **`truncate`** where Pithy recomputes the name from the same inputs on every command — a D1
+ * database, a KV namespace, a bucket, a secret entry, a token. Truncation is deterministic and
+ * hash-disambiguated, so provision and teardown still agree, and a failed CI run is avoided.
+ */
+export type OverflowPolicy = "refuse" | "truncate";
+/** One namespace's rule: how long a name may be, and what happens when it would be longer. */
+export interface NamespaceLimit {
+    /** How an error message names this namespace, e.g. `an R2 bucket name`. */
+    readonly label: string;
+    /** The longest name the namespace accepts. Pithy composes ASCII only, so characters are bytes. */
+    readonly maxLength: number;
+    /** The shortest name the namespace accepts. Only R2 states one; everywhere else it is 1. */
+    readonly minLength: number;
+    /** What happens to a name that would exceed {@link maxLength}. */
+    readonly policy: OverflowPolicy;
+    /** Whether {@link maxLength} is Cloudflare's number or Pithy's. */
+    readonly source: LimitSource;
+}
+/**
+ * Pithy's ceiling for a namespace Cloudflare does not cap — D1 database names, Secrets Store
+ * entries, API token labels.
+ *
+ * **This is our number, not Cloudflare's.** No published cap is not the same as no cap: a name is
+ * read by humans in unfilterable listings, echoed in CLI output, and pasted into wrangler configs,
+ * so it needs an end. 128 is twice the longest limit Cloudflare does publish (64) and roughly twice
+ * the longest name Pithy can compose today, which leaves room for a capability with a long tail
+ * without ever reaching for the truncator.
+ */
+export declare const MAX_PITHY_NAME = 128;
+/**
+ * The rule per namespace. Read it, do not re-derive it — a limit enforced in two places eventually
+ * disagrees with itself, and the number an error quotes must be the number the check used.
+ */
+export declare const NAMESPACE_LIMITS: {
+    /**
+     * A Workflow name: 64 characters, `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`. Documented on the Workflows
+     * limits page, `maxLength: 64` in the OpenAPI schema, and `MAX_WORKFLOW_NAME_LENGTH` in wrangler.
+     */
+    readonly workflow: {
+        readonly label: "a Workflow name";
+        readonly maxLength: 64;
+        readonly minLength: 1;
+        readonly policy: "refuse";
+        readonly source: "cloudflare";
+    };
+    /**
+     * A Worker script name: 255 in general, **63 once workers.dev is on**, alphanumeric and dashes
+     * with no leading or trailing dash. Pithy holds the 63: it is the only number that stays true
+     * after an adopter enables a workers.dev subdomain, and a script cannot be renamed afterwards.
+     * Deliberately one *less* than the Workflow cap — they are different resources with different
+     * numbers, and collapsing them would loosen this one.
+     */
+    readonly worker: {
+        readonly label: "a Worker script name";
+        readonly maxLength: 63;
+        readonly minLength: 1;
+        readonly policy: "refuse";
+        readonly source: "cloudflare";
+    };
+    /**
+     * An R2 bucket: 3–63 characters, lowercase letters, digits and hyphens, and it must **start and
+     * end alphanumeric**. The one namespace where 63 was always the right answer.
+     */
+    readonly r2: {
+        readonly label: "an R2 bucket name";
+        readonly maxLength: 63;
+        readonly minLength: 3;
+        readonly policy: "truncate";
+        readonly source: "cloudflare";
+    };
+    /**
+     * A Vectorize index: 64 bytes, `^([a-z]+[a-z0-9_-]*[a-z0-9]+)$` — it must start with a letter,
+     * which the project rule already guarantees. Refused rather than truncated because a renamed
+     * index is an empty index until everything is re-embedded.
+     */
+    readonly vectorizeIndex: {
+        readonly label: "a Vectorize index name";
+        readonly maxLength: 64;
+        readonly minLength: 2;
+        readonly policy: "refuse";
+        readonly source: "cloudflare";
+    };
+    /**
+     * A KV namespace title: 512 characters, no pattern at all — spaces and mixed case are accepted
+     * (`workers-kv_namespace_title.maxLength` in the OpenAPI schema). Pithy still composes a kebab
+     * title, for the same reason it composes every other name the same way; what changed is that it
+     * no longer hashes one at 63.
+     */
+    readonly kv: {
+        readonly label: "a KV namespace title";
+        readonly maxLength: 512;
+        readonly minLength: 1;
+        readonly policy: "truncate";
+        readonly source: "cloudflare";
+    };
+    /**
+     * A D1 database name: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` in the OpenAPI schema, and **no documented
+     * length cap** — the limits page has no row for it. So the ceiling here is {@link MAX_PITHY_NAME}.
+     */
+    readonly d1: {
+        readonly label: "a D1 database name";
+        readonly maxLength: 128;
+        readonly minLength: 1;
+        readonly policy: "truncate";
+        readonly source: "pithy";
+    };
+    /**
+     * A Secrets Store entry name: "cannot contain spaces", wrangler enforces `/^[A-z0-9-_]+$/`, and
+     * **no documented length cap**. Ours, therefore — {@link MAX_PITHY_NAME}.
+     */
+    readonly secretEntry: {
+        readonly label: "a Secrets Store entry name";
+        readonly maxLength: 128;
+        readonly minLength: 1;
+        readonly policy: "truncate";
+        readonly source: "pithy";
+    };
+    /**
+     * A Cloudflare API token name: a free-text label with **no documented cap**. Ours —
+     * {@link MAX_PITHY_NAME} — and it matters least of all, since nothing addresses a token by name.
+     */
+    readonly apiToken: {
+        readonly label: "a Cloudflare API token name";
+        readonly maxLength: 128;
+        readonly minLength: 1;
+        readonly policy: "truncate";
+        readonly source: "pithy";
+    };
+};
+/** Every namespace the naming facade can compose into. */
+export type Namespace = keyof typeof NAMESPACE_LIMITS;
+/**
+ * The longest `<capability>-<job>` tail any capability registry declares today. Read off the
+ * registries, not guessed: `media-audio-transcribe` and `media-video-transcribe` are both 22, ahead
+ * of `payments-reconcile` (18), `vector-reprocess` (16), `support-classify` (16), `email-schedule`
+ * (14), `secrets-rotate` (14), `storage-sweep` (13), `testers-daily` (13).
+ *
+ * {@link WORKFLOW_DERIVED_PROJECT_NAME} is derived against it, so the two move together — and
+ * `workflowScriptName` refuses a longer tail rather than letting a new capability silently
+ * invalidate the project-name cap every existing project was accepted under.
+ */
+export declare const MAX_CAPABILITY_JOB: number;
+/**
+ * Digits a feature's issue number may carry. Six — `f999999`, just under a million open issues in one
+ * repository, which nothing this toolkit will serve is going to exhaust.
+ *
+ * The count is not free: every digit reserved here costs one character of **every** adopter's project
+ * name, because {@link FEATURE_DERIVED_PROJECT_NAME} is computed against it and a project name cannot
+ * be changed once anything is provisioned. Seven digits would buy ten million issues nobody asked for
+ * and charge every project a character for them.
+ */
+export declare const MAX_ISSUE_DIGITS = 6;
+/**
+ * The slug length a feature resource name keeps verbatim at the worst legal project name.
+ *
+ * Twelve, because that is where a feature slug stops being readable in a listing: below it,
+ * `fitSegment` has to fall back to a short head plus a six-hex disambiguator, and
+ * `acme-f95-medi-8f21c4-db-d1` tells a human nothing about which branch owns the database.
+ */
+export declare const MIN_LEGIBLE_SLUG = 12;
+/**
+ * The binding length a feature resource name keeps verbatim at the worst legal project name.
+ *
+ * Also twelve — `MEDIA_BUCKET`, `SESSIONS`, `CACHE`, `ASSETS`, `DB`, `ROOMS` all fit. It is
+ * deliberately **not** the longest binding Pithy declares (`EMAIL_SUPPRESSIONS`, 18): reserving
+ * that would cost every adopter six characters of project name to protect a purely cosmetic
+ * property, since a longer binding truncates deterministically and stays unique through its hash,
+ * and teardown recomputes the name rather than matching a prefix.
+ */
+export declare const MIN_VERBATIM_BINDING = 12;
+/** The longest feature resource kind — `d1`, `kv`, `r2` are all two characters. `feature.test.ts` pins it. */
+export declare const MAX_FEATURE_KIND = 2;
+/**
+ * What the longest Workflow name leaves a project.
+ *
+ * ```
+ *     64   a Workflow name (NAMESPACE_LIMITS.workflow)
+ *   -  1   the hyphen before the environment
+ *   -  7   the longest environment, `staging` (MAX_ENVIRONMENT_NAME)
+ *   -  1   the hyphen before the tail
+ *   - 22   the longest <capability>-<job>, `media-audio-transcribe`
+ *   ----
+ *     33
+ * ```
+ */
+export declare const WORKFLOW_DERIVED_PROJECT_NAME: number;
+/**
+ * What the longest feature resource name leaves a project — `<project>-f<issue>-<slug>-<binding>-<kind>`,
+ * against R2's 63 (the strictest of the three kinds a feature provisions, and the same number a
+ * feature Worker script gets).
+ *
+ * ```
+ *     63   an R2 bucket name (NAMESPACE_LIMITS.r2)
+ *   -  2   `-f`
+ *   -  6   the issue number, six digits — `f999999` (MAX_ISSUE_DIGITS)
+ *   - 13   `-` + a legible slug (MIN_LEGIBLE_SLUG)
+ *   - 13   `-` + a binding kept whole (MIN_VERBATIM_BINDING)
+ *   -  3   `-` + the kind, `d1` | `kv` | `r2`
+ *   ----
+ *     26
+ * ```
+ */
+export declare const FEATURE_DERIVED_PROJECT_NAME: number;
+//# sourceMappingURL=limits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/naming/limits.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AAEH,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEnD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;OAGG;;iBACS,KAAK,EAAE,iBAAiB;iBAAE,SAAS,EAAE,EAAE;iBAAE,SAAS,EAAE,CAAC;iBAAE,MAAM,EAAE,QAAQ;iBAAE,MAAM,EAAE,YAAY;;IACzG;;;;;;OAMG;;iBACO,KAAK,EAAE,sBAAsB;iBAAE,SAAS,EAAE,EAAE;iBAAE,SAAS,EAAE,CAAC;iBAAE,MAAM,EAAE,QAAQ;iBAAE,MAAM,EAAE,YAAY;;IAC5G;;;OAGG;;iBACG,KAAK,EAAE,mBAAmB;iBAAE,SAAS,EAAE,EAAE;iBAAE,SAAS,EAAE,CAAC;iBAAE,MAAM,EAAE,UAAU;iBAAE,MAAM,EAAE,YAAY;;IACvG;;;;OAIG;;iBAED,KAAK,EAAE,wBAAwB;iBAC/B,SAAS,EAAE,EAAE;iBACb,SAAS,EAAE,CAAC;iBACZ,MAAM,EAAE,QAAQ;iBAChB,MAAM,EAAE,YAAY;;IAEtB;;;;;OAKG;;iBACG,KAAK,EAAE,sBAAsB;iBAAE,SAAS,EAAE,GAAG;iBAAE,SAAS,EAAE,CAAC;iBAAE,MAAM,EAAE,UAAU;iBAAE,MAAM,EAAE,YAAY;;IAC3G;;;OAGG;;iBACG,KAAK,EAAE,oBAAoB;iBAAE,SAAS;iBAAkB,SAAS,EAAE,CAAC;iBAAE,MAAM,EAAE,UAAU;iBAAE,MAAM,EAAE,OAAO;;IAC/G;;;OAGG;;iBAED,KAAK,EAAE,4BAA4B;iBACnC,SAAS;iBACT,SAAS,EAAE,CAAC;iBACZ,MAAM,EAAE,UAAU;iBAClB,MAAM,EAAE,OAAO;;IAEjB;;;OAGG;;iBAED,KAAK,EAAE,6BAA6B;iBACpC,SAAS;iBACT,SAAS,EAAE,CAAC;iBACZ,MAAM,EAAE,UAAU;iBAClB,MAAM,EAAE,OAAO;;CAEgC,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,QAC+C,CAAC;AAE1F;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,QAMjB,CAAC"}

package/dist/naming/limits.js

@@ -0,0 +1,187 @@
+import { MAX_ENVIRONMENT_NAME } from "./environment.js";
+//#region src/naming/limits.ts
+/**
+* Pithy's ceiling for a namespace Cloudflare does not cap — D1 database names, Secrets Store
+* entries, API token labels.
+*
+* **This is our number, not Cloudflare's.** No published cap is not the same as no cap: a name is
+* read by humans in unfilterable listings, echoed in CLI output, and pasted into wrangler configs,
+* so it needs an end. 128 is twice the longest limit Cloudflare does publish (64) and roughly twice
+* the longest name Pithy can compose today, which leaves room for a capability with a long tail
+* without ever reaching for the truncator.
+*/
+const MAX_PITHY_NAME = 128;
+/**
+* The rule per namespace. Read it, do not re-derive it — a limit enforced in two places eventually
+* disagrees with itself, and the number an error quotes must be the number the check used.
+*/
+const NAMESPACE_LIMITS = {
+	/**
+	* A Workflow name: 64 characters, `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`. Documented on the Workflows
+	* limits page, `maxLength: 64` in the OpenAPI schema, and `MAX_WORKFLOW_NAME_LENGTH` in wrangler.
+	*/
+	workflow: {
+		label: "a Workflow name",
+		maxLength: 64,
+		minLength: 1,
+		policy: "refuse",
+		source: "cloudflare"
+	},
+	/**
+	* A Worker script name: 255 in general, **63 once workers.dev is on**, alphanumeric and dashes
+	* with no leading or trailing dash. Pithy holds the 63: it is the only number that stays true
+	* after an adopter enables a workers.dev subdomain, and a script cannot be renamed afterwards.
+	* Deliberately one *less* than the Workflow cap — they are different resources with different
+	* numbers, and collapsing them would loosen this one.
+	*/
+	worker: {
+		label: "a Worker script name",
+		maxLength: 63,
+		minLength: 1,
+		policy: "refuse",
+		source: "cloudflare"
+	},
+	/**
+	* An R2 bucket: 3–63 characters, lowercase letters, digits and hyphens, and it must **start and
+	* end alphanumeric**. The one namespace where 63 was always the right answer.
+	*/
+	r2: {
+		label: "an R2 bucket name",
+		maxLength: 63,
+		minLength: 3,
+		policy: "truncate",
+		source: "cloudflare"
+	},
+	/**
+	* A Vectorize index: 64 bytes, `^([a-z]+[a-z0-9_-]*[a-z0-9]+)$` — it must start with a letter,
+	* which the project rule already guarantees. Refused rather than truncated because a renamed
+	* index is an empty index until everything is re-embedded.
+	*/
+	vectorizeIndex: {
+		label: "a Vectorize index name",
+		maxLength: 64,
+		minLength: 2,
+		policy: "refuse",
+		source: "cloudflare"
+	},
+	/**
+	* A KV namespace title: 512 characters, no pattern at all — spaces and mixed case are accepted
+	* (`workers-kv_namespace_title.maxLength` in the OpenAPI schema). Pithy still composes a kebab
+	* title, for the same reason it composes every other name the same way; what changed is that it
+	* no longer hashes one at 63.
+	*/
+	kv: {
+		label: "a KV namespace title",
+		maxLength: 512,
+		minLength: 1,
+		policy: "truncate",
+		source: "cloudflare"
+	},
+	/**
+	* A D1 database name: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` in the OpenAPI schema, and **no documented
+	* length cap** — the limits page has no row for it. So the ceiling here is {@link MAX_PITHY_NAME}.
+	*/
+	d1: {
+		label: "a D1 database name",
+		maxLength: 128,
+		minLength: 1,
+		policy: "truncate",
+		source: "pithy"
+	},
+	/**
+	* A Secrets Store entry name: "cannot contain spaces", wrangler enforces `/^[A-z0-9-_]+$/`, and
+	* **no documented length cap**. Ours, therefore — {@link MAX_PITHY_NAME}.
+	*/
+	secretEntry: {
+		label: "a Secrets Store entry name",
+		maxLength: 128,
+		minLength: 1,
+		policy: "truncate",
+		source: "pithy"
+	},
+	/**
+	* A Cloudflare API token name: a free-text label with **no documented cap**. Ours —
+	* {@link MAX_PITHY_NAME} — and it matters least of all, since nothing addresses a token by name.
+	*/
+	apiToken: {
+		label: "a Cloudflare API token name",
+		maxLength: 128,
+		minLength: 1,
+		policy: "truncate",
+		source: "pithy"
+	}
+};
+/**
+* The longest `<capability>-<job>` tail any capability registry declares today. Read off the
+* registries, not guessed: `media-audio-transcribe` and `media-video-transcribe` are both 22, ahead
+* of `payments-reconcile` (18), `vector-reprocess` (16), `support-classify` (16), `email-schedule`
+* (14), `secrets-rotate` (14), `storage-sweep` (13), `testers-daily` (13).
+*
+* {@link WORKFLOW_DERIVED_PROJECT_NAME} is derived against it, so the two move together — and
+* `workflowScriptName` refuses a longer tail rather than letting a new capability silently
+* invalidate the project-name cap every existing project was accepted under.
+*/
+const MAX_CAPABILITY_JOB = 22;
+/**
+* Digits a feature's issue number may carry. Six — `f999999`, just under a million open issues in one
+* repository, which nothing this toolkit will serve is going to exhaust.
+*
+* The count is not free: every digit reserved here costs one character of **every** adopter's project
+* name, because {@link FEATURE_DERIVED_PROJECT_NAME} is computed against it and a project name cannot
+* be changed once anything is provisioned. Seven digits would buy ten million issues nobody asked for
+* and charge every project a character for them.
+*/
+const MAX_ISSUE_DIGITS = 6;
+/**
+* The slug length a feature resource name keeps verbatim at the worst legal project name.
+*
+* Twelve, because that is where a feature slug stops being readable in a listing: below it,
+* `fitSegment` has to fall back to a short head plus a six-hex disambiguator, and
+* `acme-f95-medi-8f21c4-db-d1` tells a human nothing about which branch owns the database.
+*/
+const MIN_LEGIBLE_SLUG = 12;
+/**
+* The binding length a feature resource name keeps verbatim at the worst legal project name.
+*
+* Also twelve — `MEDIA_BUCKET`, `SESSIONS`, `CACHE`, `ASSETS`, `DB`, `ROOMS` all fit. It is
+* deliberately **not** the longest binding Pithy declares (`EMAIL_SUPPRESSIONS`, 18): reserving
+* that would cost every adopter six characters of project name to protect a purely cosmetic
+* property, since a longer binding truncates deterministically and stays unique through its hash,
+* and teardown recomputes the name rather than matching a prefix.
+*/
+const MIN_VERBATIM_BINDING = 12;
+/** The longest feature resource kind — `d1`, `kv`, `r2` are all two characters. `feature.test.ts` pins it. */
+const MAX_FEATURE_KIND = 2;
+/**
+* What the longest Workflow name leaves a project.
+*
+* ```
+*     64   a Workflow name (NAMESPACE_LIMITS.workflow)
+*   -  1   the hyphen before the environment
+*   -  7   the longest environment, `staging` (MAX_ENVIRONMENT_NAME)
+*   -  1   the hyphen before the tail
+*   - 22   the longest <capability>-<job>, `media-audio-transcribe`
+*   ----
+*     33
+* ```
+*/
+const WORKFLOW_DERIVED_PROJECT_NAME = NAMESPACE_LIMITS.workflow.maxLength - 1 - MAX_ENVIRONMENT_NAME - 1 - 22;
+/**
+* What the longest feature resource name leaves a project — `<project>-f<issue>-<slug>-<binding>-<kind>`,
+* against R2's 63 (the strictest of the three kinds a feature provisions, and the same number a
+* feature Worker script gets).
+*
+* ```
+*     63   an R2 bucket name (NAMESPACE_LIMITS.r2)
+*   -  2   `-f`
+*   -  6   the issue number, six digits — `f999999` (MAX_ISSUE_DIGITS)
+*   - 13   `-` + a legible slug (MIN_LEGIBLE_SLUG)
+*   - 13   `-` + a binding kept whole (MIN_VERBATIM_BINDING)
+*   -  3   `-` + the kind, `d1` | `kv` | `r2`
+*   ----
+*     26
+* ```
+*/
+const FEATURE_DERIVED_PROJECT_NAME = NAMESPACE_LIMITS.r2.maxLength - 2 - 6 - 13 - 13 - 3;
+//#endregion
+export { FEATURE_DERIVED_PROJECT_NAME, MAX_CAPABILITY_JOB, MAX_FEATURE_KIND, MAX_ISSUE_DIGITS, MAX_PITHY_NAME, MIN_LEGIBLE_SLUG, MIN_VERBATIM_BINDING, NAMESPACE_LIMITS, WORKFLOW_DERIVED_PROJECT_NAME };

package/dist/naming/provisionScope.d.ts

@@ -0,0 +1,91 @@
+import { type FeatureIdentity, type FeatureResourceKind } from "./feature";
+/**
+ * **What a provisioning run names its resources, and which `env.<name>` stanza it writes them into —
+ * as one object, never two arguments.**
+ *
+ * Provisioning was specified for ephemeral feature environments and parameterized by `--env` before it
+ * was generalized to named ones. That left the namer and the target stanza as independent inputs, and
+ * A feature's namer with a declared environment beside it was the reachable consequence: it composed
+ * `<project>-f<issue>-<slug>-db` and wrote it in as `staging`'s `DB`. Nothing refused it, the ids went
+ * into a checked-in `wrangler.jsonc`, and a remote migrate ran against them.
+ *
+ * A guard against that combination would be a list of forbidden pairs. This is the invariant instead:
+ * **a scope is chosen once, and it carries both halves.** There is no call path that takes an
+ * environment name and a naming scheme separately, so there is no pair left to get wrong.
+ *
+ * Two scopes exist, and they are the two kinds of environment a project has:
+ *
+ * - {@link environmentScope} — a **declared** environment (`staging`, `prod`, whatever the root
+ *   `pithy.config.ts` lists). Names are `<project>-<env>-<thing>`, the rule every other namer in the
+ *   kit follows, so the environment segment of a name is always the stanza the name lives in.
+ * - {@link featureScope} — one branch's **ephemeral** environment. Names are
+ *   `<project>-f<issue>-<slug>-<thing>`, with no environment segment because a feature *is* an
+ *   environment, and the `f<issue>` marker is what teardown recomputes and what keeps a feature's
+ *   database from ever being mistaken for a deployed one's.
+ */
+/**
+ * Whether a secret's value differs per environment or is one value every environment binds.
+ *
+ * The same two words `@pithy-sh/secrets`' `SecretScope` uses, restated here as a literal union rather
+ * than imported: core carries the secret-registry *seam* and not the package, for the same reason
+ * `SecretRegistryEntrySeam` types `backend` as a `string`.
+ */
+export type SecretNameScope = "environment" | "global";
+/** Where a provisioning run's resources are named, and where their ids are written. */
+export interface ProvisionScope {
+    /** The `env.<stanza>` key in each Worker's config that this scope's ids are written into. */
+    readonly stanza: string;
+    /**
+     * **Are this scope's ids source, or a build artifact?**
+     *
+     * The same provisioning step produces both, and the difference is not cosmetic. A declared
+     * environment's ids are long-lived facts about the repository: they belong in the tracked
+     * `wrangler.jsonc`, under review, in a pull request a human reads. A feature's are facts about one
+     * job — the branch is deleted, the resources are destroyed, and the ids name nothing afterwards.
+     *
+     * Writing a feature's into the tracked file was correct as designed *in CI*, where the checkout is
+     * throwaway, and an expectation everywhere else: a developer's worktree carried a modified tracked
+     * file they never edited, with no note saying it must not be committed, and `git add -A` put ids for
+     * deleted resources onto `main`. So a build artifact goes somewhere untracked instead, and the
+     * question "which is this?" is answered here, once, by the same object that answers "what is it
+     * called?" and "which stanza does it go in?" — because those three answers have to agree.
+     */
+    readonly source: boolean;
+    /** This scope's Cloudflare name for a provisionable binding. */
+    resource(binding: string, kind: FeatureResourceKind): string;
+    /** The script name a Worker deploys under in this scope. */
+    worker(worker: string): string;
+    /**
+     * This scope's CF Secrets Store entry name for a declared secret.
+     *
+     * A `global` secret is the one name that does **not** take the scope's segment: it is a single
+     * account-level value every environment binds, so every scope resolves it to the project's
+     * `<project>-global-<secret>`. Scoping it would mint a second copy of a value defined as one.
+     */
+    secretEntry(secret: string, secretScope: SecretNameScope): string;
+}
+/**
+ * A declared environment's scope — `staging`, `prod`, or whatever the root `pithy.config.ts` lists.
+ *
+ * The environment is validated here, once, before a single name exists: it is the middle segment of
+ * every name below, so an illegal one must fail before anything is created rather than at the fourth
+ * getter that happened to use it.
+ *
+ * **A Worker's script name is wrangler's own, `<script>-<env>`, deliberately.** It is the one name here
+ * that is not `<project>-<env>-<thing>`, because `wrangler deploy --env staging` has always appended the
+ * environment to the top-level `name` — so every project that ever deployed is already at that address.
+ * A Worker script is a `refuse`-policy namespace precisely because renaming one orphans the deployment
+ * and every `service` binding pointing at it; composing a "more correct" name here would do exactly
+ * that, silently, on the next deploy. The name is written out rather than left implicit so a service
+ * binding and a deploy agree on one string that is in the file.
+ */
+export declare function environmentScope(project: string, environment: string): ProvisionScope;
+/**
+ * One feature's scope — the ephemeral environment a branch gets, named from the branch rather than from
+ * an environment.
+ *
+ * Its stanza is {@link FEATURE_ENVIRONMENT} and nothing else, which is what makes a feature's resources
+ * in a declared environment's stanza unexpressible rather than merely discouraged.
+ */
+export declare function featureScope(identity: FeatureIdentity): ProvisionScope;
+//# sourceMappingURL=provisionScope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provisionScope.d.ts","sourceRoot":"","sources":["../../src/naming/provisionScope.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAIzB,MAAM,WAAW,CAAC;AAGnB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEvD,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAC7D,4DAA4D;IAC5D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAAC;CACnE;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAYrF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAUtE"}

package/dist/naming/provisionScope.js

@@ -0,0 +1,65 @@
+import { FEATURE_ENVIRONMENT, assertValidEnvironment } from "./environment.js";
+import { featureResourceName, featureSecretEntryName, featureWorkerName } from "./feature.js";
+import { resourceNames } from "./resourceNames.js";
+//#region src/naming/provisionScope.ts
+/** The wrangler binding array a resource kind's name is composed for. */
+const KIND_NAMER = {
+	d1: "d1",
+	kv: "kv",
+	r2: "r2"
+};
+/**
+* The one branch every scope shares: a `global` secret resolves to the project's single
+* `<project>-global-<secret>` entry, and everything else to the scope's own name for it.
+*
+* Written once here rather than in each scope, because "global is not scoped" is a property of the
+* secret and not of the environment asking — and two copies of it is how one of them would drift.
+*/
+function secretEntryName(project, secret, secretScope, scoped) {
+	if (secretScope === "global") return resourceNames(project).global.secretEntry(secret);
+	return scoped();
+}
+/**
+* A declared environment's scope — `staging`, `prod`, or whatever the root `pithy.config.ts` lists.
+*
+* The environment is validated here, once, before a single name exists: it is the middle segment of
+* every name below, so an illegal one must fail before anything is created rather than at the fourth
+* getter that happened to use it.
+*
+* **A Worker's script name is wrangler's own, `<script>-<env>`, deliberately.** It is the one name here
+* that is not `<project>-<env>-<thing>`, because `wrangler deploy --env staging` has always appended the
+* environment to the top-level `name` — so every project that ever deployed is already at that address.
+* A Worker script is a `refuse`-policy namespace precisely because renaming one orphans the deployment
+* and every `service` binding pointing at it; composing a "more correct" name here would do exactly
+* that, silently, on the next deploy. The name is written out rather than left implicit so a service
+* binding and a deploy agree on one string that is in the file.
+*/
+function environmentScope(project, environment) {
+	assertValidEnvironment(environment);
+	const names = resourceNames(project).env(environment);
+	return {
+		stanza: environment,
+		source: true,
+		resource: (binding, kind) => names[KIND_NAMER[kind]](binding),
+		worker: (worker) => `${worker}-${environment}`,
+		secretEntry: (secret, secretScope) => secretEntryName(project, secret, secretScope, () => names.secretEntry(secret))
+	};
+}
+/**
+* One feature's scope — the ephemeral environment a branch gets, named from the branch rather than from
+* an environment.
+*
+* Its stanza is {@link FEATURE_ENVIRONMENT} and nothing else, which is what makes a feature's resources
+* in a declared environment's stanza unexpressible rather than merely discouraged.
+*/
+function featureScope(identity) {
+	return {
+		stanza: FEATURE_ENVIRONMENT,
+		source: false,
+		resource: (binding, kind) => featureResourceName(identity, binding, kind),
+		worker: (worker) => featureWorkerName(identity, worker),
+		secretEntry: (secret, secretScope) => secretEntryName(identity.project, secret, secretScope, () => featureSecretEntryName(identity, secret))
+	};
+}
+//#endregion
+export { environmentScope, featureScope };