@pithy-sh/core 0.6.1 → 0.7.0

package/src/naming/provisionScope.ts

@@ -1,8 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import { InternalError } from "../error/pithyError";
-import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE } from "./environment";
+import { InternalError, ValidationError } from "../error/pithyError";
+import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE, isFeatureMarker } from "./environment";
 import {
   type FeatureIdentity,
   type FeatureResourceKind,
@@ -10,6 +10,7 @@ import {
   featureSecretEntryName,
   featureWorkerName,
 } from "./feature";
+import { kebab } from "./resource";
 import { resourceNames } from "./resourceNames";
 
 /**
@@ -89,6 +90,28 @@ export interface ProjectGlobalNaming extends BindingNaming {
   readonly scope: "global";
 }
 
+/**
+ * The two names one Worker answers to before a scope has named it — **and why a scope is handed both.**
+ *
+ * `pithy init replay --worker board` writes `apps/board/wrangler.jsonc` with `"name": "replay-board"`.
+ * So the Worker's directory says `board` and its deploy name says `replay-board`, and the two scopes need
+ * different ones. A declared environment's fallback is wrangler's own `<script>-<env>`, which is built on
+ * the deploy name. A feature's name is `<project>-f<issue>-<slug>-<app>`, which already leads with the
+ * project, so it is built on the directory.
+ *
+ * This was one string until #587, and the string was the deploy name, so every feature Worker carried the
+ * project twice: `replay-f69-demo-replay-board`. That was not only untidy. The name is held to the Worker
+ * cap of 63, and the doubled segment spent that budget where the truncation lands on the part that says
+ * *which* Worker. Carrying both names is what lets each scope take the one its shape is built from, and
+ * lets neither caller choose on the scope's behalf.
+ */
+export interface ProvisionWorkerNames {
+  /** The Worker's `apps/<app>` directory basename — the name a sibling's `service` binding targets it by. */
+  readonly app: string;
+  /** The Worker's deploy name — the top-level `name` of its `wrangler.jsonc`, e.g. `replay-board`. */
+  readonly script: string;
+}
+
 /** 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. */
@@ -133,8 +156,18 @@ export interface ProvisionScope {
    * is created, judged to be the project's, kept out of the teardown record, and orphaned.
    */
   readonly honorsGlobal: boolean;
-  /** The script name a Worker deploys under in this scope. */
-  worker(worker: string): string;
+  /**
+   * The script name a Worker deploys under in this scope.
+   *
+   * `worker` carries **both** of the Worker's names, because the two scopes compose from different ones:
+   * a declared environment falls back to wrangler's `<script>-<env>`, and a feature composes
+   * `<project>-f<issue>-<slug>-<app>`. See {@link ProvisionWorkerNames}.
+   *
+   * `declared` is the name that scope's stanza already carries, when it carries one. A scope may honor it
+   * or compose its own; see {@link environmentScope} and {@link featureScope}, which answer differently
+   * and say why. Passing it is how a caller asks the scope rather than deciding for itself.
+   */
+  worker(worker: ProvisionWorkerNames, declared?: string): string;
   /**
    * This scope's CF Secrets Store entry name for a declared secret.
    *
@@ -221,6 +254,28 @@ export function bindingResourceName(
   return scoped(thing);
 }
 
+/**
+ * **Is this name inside a feature's namespace** — `<project>-f<issue>-…`, the project and then a feature's
+ * marker, with something after it?
+ *
+ * The namespace, not one feature's names, because that is what has to stay disjoint: `pithy feature destroy`
+ * deletes by exact name, and a feature Worker's name has no kind suffix, so a declared environment's name
+ * that lands anywhere in here is one some branch's teardown can delete (#587). Every name {@link featureScope}
+ * composes is inside; {@link environmentScope} refuses to name a Worker inside, and `isValidEnvironment`
+ * refuses every environment whose composed names could be.
+ *
+ * **What it does not see.** It is stated for one project. A second project on the same account whose name is
+ * this one's plus `-f<issue>` — `acme-f1` beside `acme` — composes names inside `acme`'s namespace from an
+ * ordinary environment, and nothing here can tell, because a project name carries no boundary a later hyphen
+ * cannot fake. That is the hyphen ambiguity every composed name carries, one segment further left.
+ */
+export function isFeatureName(project: string, name: string): boolean {
+  const head = `${kebab(project)}-`;
+  if (!name.startsWith(head)) return false;
+  const [marker, ...rest] = name.slice(head.length).split("-");
+  return isFeatureMarker(marker ?? "") && rest.length > 0;
+}
+
 /**
  * A declared environment's scope — `staging`, `prod`, or whatever the root `pithy.config.ts` lists.
  *
@@ -228,13 +283,25 @@ export function bindingResourceName(
  * 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.
+ * **A declared name wins; the fallback is wrangler's own, `<script>-<env>`.**
+ *
+ * This reverses the rule that stood here until #580, and the reversal is worth reading rather than
+ * assuming. The old rule *recomputed* `<script>-<env>` on every provision and wrote it over whatever the
+ * stanza said, on the argument that wrangler has always appended the environment to the top-level `name`,
+ * so every project that ever deployed is already at that address.
+ *
+ * That argument is still true about the **fallback**, and the fallback is unchanged: a stanza that names
+ * nothing gets `<script>-<env>` and every existing adopter deploys exactly where they always did. What was
+ * wrong was recomputing over a name somebody wrote down. Since #580 the starter template writes one —
+ * `<project>-<env>-<worker>`, the shape every other resource here takes — so recompute would have made the
+ * template's stamp pointless, and worse: it would have silently renamed the Worker of every project that
+ * had taken the new shape, on their next `pithy provision`. A Worker script is a `refuse`-policy namespace
+ * precisely because renaming one orphans the deployment, its routes, and every `service` binding pointing
+ * at it. Doing that as a side effect of provisioning is the failure the old rule was written to prevent,
+ * arriving from the other direction.
+ *
+ * So the name is read, not composed, when the file already holds one — and written out when it does not,
+ * so a service binding and a deploy still agree on one string that is in the file.
  */
 export function environmentScope(project: string, environment: string): ProvisionScope {
   assertValidEnvironment(environment);
@@ -247,7 +314,21 @@ export function environmentScope(project: string, environment: string): Provisio
     honorsGlobal: true,
     resource: (binding, kind, naming) =>
       bindingResourceName(project, binding, kind, naming, (thing) => names[KIND_NAMER[kind]](thing)),
-    worker: (worker) => `${worker}-${environment}`,
+    worker: ({ script }, declared) => {
+      const name = declared ?? `${script}-${environment}`;
+      // The environment rule already keeps every name composed from the environment out of a feature's
+      // namespace. A declared name and wrangler's fallback are not composed from it — the stanza says one,
+      // the deploy name leads the other — so either can still sit there, and a branch's teardown would
+      // delete the Worker (#587). Refused here, where the name is chosen, rather than spared at teardown.
+      if (isFeatureName(project, name)) {
+        throw new ValidationError({
+          message: `The ${environment} Worker "${name}" is named the way a feature's Worker is.`,
+          action: `Rename it in env.${environment}.name, or the Worker's top-level name, so it does not follow ${kebab(project)}- with f and a number.`,
+          detail: `${declared === undefined ? "Composed by wrangler from the deploy name" : `Declared in env.${environment}.name`}. A feature's Worker is <project>-f<issue>-<slug>-<app>, and \`pithy feature destroy\` deletes it by that exact name.`,
+        });
+      }
+      return name;
+    },
     secretEntry: (secret, secretScope) =>
       secretEntryName(project, secret, secretScope, () => names.secretEntry(secret)),
   };
@@ -272,6 +353,12 @@ export function environmentScope(project: string, environment: string): Provisio
  * `resource` is ignored for the same reason it is moot: a feature's `<thing>` segment is the binding plus
  * the kind, and the whole name is recomputed on teardown rather than looked up, so nothing outside the
  * feature reads the string.
+ *
+ * **And a declared Worker name is ignored here too — the other half of the #580 asymmetry.** A declared
+ * environment's script name is the adopter's, written in a tracked file, and provisioning reads it. A
+ * feature's is the kit's: it is composed from the branch, written into a generated config nobody commits,
+ * and **recomputed on teardown**. Honoring a declared one would leave `pithy feature destroy` computing a
+ * name the deployment does not answer to, which is a Worker nothing deletes.
  */
 export function featureScope(identity: FeatureIdentity): ProvisionScope {
   return {
@@ -282,8 +369,38 @@ export function featureScope(identity: FeatureIdentity): ProvisionScope {
     // part company here.
     honorsGlobal: false,
     resource: (binding, kind) => featureResourceName(identity, binding, kind),
-    worker: (worker) => featureWorkerName(identity, worker),
+    // The directory, not the deploy name: the head already carries the project, and the deploy name
+    // usually leads with it too, which composed `<project>-f<issue>-<slug>-<project>-<app>` (#587).
+    worker: ({ app }) => featureWorkerName(identity, app),
     secretEntry: (secret, secretScope) =>
       secretEntryName(identity.project, secret, secretScope, () => featureSecretEntryName(identity, secret)),
   };
 }
+
+/**
+ * **Every script name one Worker can be deployed under in a feature — what teardown looks for (#592).**
+ *
+ * The first is the name {@link featureScope} composes today, taken from the scope rather than composed a
+ * second time, so provisioning and teardown cannot disagree about it. The second is the one it composed
+ * until #587, from the deploy name: `<project>-f<issue>-<slug>-<project>-<app>`. A feature provisioned and
+ * deployed before that upgrade is still running under it, and after its next deploy it runs under both —
+ * so teardown looks for both. One entry when the two coincide, as they do for a Worker whose deploy name
+ * is its directory.
+ *
+ * **Exact names, never a prefix.** A prefix scan of `<project>-f<issue>-<slug>-` reaches a sibling whose
+ * slug extends this one's. The exact names can still meet a sibling in one shape: the doubled name for
+ * slug `demo` and deploy name `acme-api` is the current name for slug `demo-acme` and directory `api`, on
+ * the same issue number. That is the same hyphen ambiguity every feature name here carries.
+ *
+ * **They cannot meet a declared environment's Worker**, which has no suffix either and is `<project>-<env>-<app>`
+ * since #580: every name either shape yields is inside {@link isFeatureName}'s namespace, no environment may
+ * start with a feature's marker, and {@link environmentScope} refuses a declared or fallback Worker name inside
+ * it. What that does not reach is a name nothing in the kit chose — a stanza written by hand and deployed
+ * without `pithy provision --env` ever reading it, or another project on the account, as {@link isFeatureName}
+ * says.
+ */
+export function featureWorkerScriptNames(identity: FeatureIdentity, worker: ProvisionWorkerNames): string[] {
+  const current = featureScope(identity).worker(worker);
+  const beforeSingleProject = featureWorkerName(identity, worker.script);
+  return current === beforeSingleProject ? [current] : [current, beforeSingleProject];
+}

package/src/naming/resourceNames.ts

@@ -69,8 +69,11 @@ export interface ScopedNames {
 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;
+  /**
+   * A feature's Worker script — `<project>-f<issue>-<slug>-<app>`, from the `apps/<app>` directory and
+   * never the deploy name, which already leads with the project (#587).
+   */
+  worker(app: string): string;
 }
 
 /** Everything a project can be asked to name. Created once, from the project, by {@link resourceNames}. */
@@ -167,7 +170,7 @@ export function resourceNames(project: string): ProjectNames {
       const full: FeatureIdentity = { ...identity, project: normalized };
       return {
         resource: (binding, kind) => featureResourceName(full, binding, kind),
-        worker: (worker) => featureWorkerName(full, worker),
+        worker: (app) => featureWorkerName(full, app),
       };
     },
   };

package/src/text/comments.ts

@@ -62,6 +62,28 @@
  * `worker-safety.test.ts` exists to enforce, so the gate now polices the stripper it reads with.
  */
 export function blankComments(source: string): string {
+  return blank(source, false);
+}
+
+/**
+ * `source` with every comment **and every string's contents** blanked — for a gate asking whether a name is
+ * *called*, where {@link blankComments}' own rule points the wrong way.
+ *
+ * `blankComments` keeps strings because its callers look for a forbidden read, and a string that merely contains
+ * one is a false positive, the safe direction. A gate looking for a *required* call inverts that: a validator named
+ * only inside an error message — `"requireEnvironment(args.env)"` — is a call that never runs, and counting it
+ * passes the file. So this blanks the contents too, delimiters kept, character for character.
+ *
+ * **A template literal goes whole, `${}` included.** A call written only inside an interpolation is not seen. For
+ * a presence check that is the safe direction again — the file is flagged, never passed — and a scan for a read
+ * belongs on {@link blankComments}, where the interpolation stays.
+ */
+export function blankCommentsAndStrings(source: string): string {
+  return blank(source, true);
+}
+
+/** The one walk behind both: comments always blanked, a quoted run kept or blanked inside its delimiters. */
+function blank(source: string, strings: boolean): string {
   let out = "";
   let previous = "";
   let index = 0;
@@ -76,7 +98,8 @@ export function blankComments(source: string): string {
     }
     if (char === '"' || char === "'" || char === "`") {
       const stop = endOfQuoted(source, index, char, char !== "`");
-      out += source.slice(index, stop);
+      const run = source.slice(index, stop);
+      out += strings ? blankInside(run, char) : run;
       index = stop;
       previous = char;
       continue;
@@ -95,6 +118,13 @@ export function blankComments(source: string): string {
   return out;
 }
 
+/** A quoted run with everything between its delimiters blanked, newlines kept. An unterminated run has no closer. */
+function blankInside(run: string, quote: string): string {
+  const closed = run.length > 1 && run.endsWith(quote);
+  const body = run.slice(1, closed ? -1 : undefined).replace(/[^\n]/g, " ");
+  return `${quote}${body}${closed ? quote : ""}`;
+}
+
 /**
  * After one of these, a `/` opens a regex literal; after anything else it divides. The empty string is
  * the start of the file. A wrong guess is bounded — see {@link endOfRegex}.

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.6.1";
+export const PACKAGE_VERSION = "0.7.0";

package/src/workflow/host.ts

@@ -139,6 +139,14 @@ export interface WorkflowHostParams {
    * not depend on `@pithy-sh/secrets`, which owns that naming.
    */
   masterKeySecretName?: string;
+  /**
+   * Secrets Store binding name → the entry it resolves to in this environment, for every store secret the
+   * host reads besides the master key. Filled **only** for the bindings listed, like
+   * {@link databaseNames}; the names come from the capability, which composes them with the same namer
+   * provisioning created the entries with. Core composes none of them itself, for the reason
+   * {@link masterKeySecretName} gives.
+   */
+  secretNames?: Record<string, string>;
   /** Vars merged over the template's, e.g. the capability's config serialized as one JSON blob. */
   vars?: Record<string, string>;
   /**
@@ -241,13 +249,15 @@ export function resolveWorkflowHost(template: WorkflowHostTemplate, params: Work
 
   if (resolved.secrets_store_secrets && params.secretsStoreId !== undefined) {
     const storeId = params.secretsStoreId;
-    const masterKey = params.masterKeySecretName;
+    const names: Record<string, string> = {
+      ...(params.masterKeySecretName !== undefined ? { SECRETS_ENCRYPTION_KEYS: params.masterKeySecretName } : {}),
+      ...params.secretNames,
+    };
     resolved.secrets_store_secrets = resolved.secrets_store_secrets.map((entry) => ({
       ...entry,
       store_id: storeId,
-      // Only the master key is environment-scoped; every other entry keeps its declared name.
-      secret_name:
-        masterKey !== undefined && entry.binding === "SECRETS_ENCRYPTION_KEYS" ? masterKey : entry.secret_name,
+      // A named binding takes the entry its capability composed; an unnamed one keeps its declared name.
+      secret_name: Object.hasOwn(names, entry.binding) ? (names[entry.binding] as string) : entry.secret_name,
     }));
   }
 

package/src/workflow/hostEnv.ts

@@ -45,7 +45,7 @@ export type HostEnvProviderKind = z.infer<typeof HostEnvProviderKind>;
 /**
  * What provides one field. The whole point of the declaration: a report that says `BASE_URL is
  * missing` sends a developer looking, and a report that says `Var BASE_URL in the host's
- * wrangler.jsonc. Run pithy email provision --env dev.` ends the search.
+ * wrangler.jsonc. Run pithy email provision.` ends the search.
  */
 export const HostEnvProvider = z
   .object({