@pithy-sh/core 0.9.0 → 0.10.0

package/src/migrations/runner.ts

@@ -4,10 +4,12 @@
 import type { D1Database } from "@cloudflare/workers-types";
 import { type Kysely, sql } from "kysely";
 import { type MigrationProvider, type MigrationResult, Migrator, NO_MIGRATIONS } from "kysely/migration";
+import { pithyCommand } from "../cli/command";
 import { causeMessage } from "../error/cause";
-import { InternalError } from "../error/pithyError";
+import { InternalError, ValidationError } from "../error/pithyError";
 import { batchedProvider } from "./batch";
-import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping";
+import { appliedMigrationChain, MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping";
+import { forgetMigrationGroups, generatedMigrationGroup, readGroupPosition, recordMigrationGroup } from "./groups";
 import { guardRetained, isDownRefusal, RetainedBudget } from "./retained";
 
 /**
@@ -33,6 +35,12 @@ import { guardRetained, isDownRefusal, RetainedBudget } from "./retained";
  * are argued.** The short version: a migration is now all-or-nothing where it used to be able to
  * half-apply, and nothing across a migration boundary changed, because the ledger names migrations
  * and a partial chain has to stay representable in it.
+ *
+ * **Every run belongs to a group, and a reversal names one — see `./groups` (#694).** A forward run
+ * records the group it applied each migration under, in a table beside the ledger;
+ * {@link reverseMigrationGroup} reverses one group's portion of one database, in reverse chain order and
+ * nothing outside it. {@link rollbackMigration} is still the single step underneath, for a caller holding
+ * one migration rather than a release — it is not what `pithy migrate --rollback` runs any more.
  */
 
 /**
@@ -105,13 +113,63 @@ function guardOptions(
   return { binding: target?.binding ?? "this database", budget: consent?.budget ?? new RetainedBudget(undefined) };
 }
 
-/** Run every pending migration to latest. An empty provider resolves to `[]`. */
+/**
+ * What a forward run records about itself (#694) — see `./groups`.
+ *
+ * Optional, and absent still records: a run with no group named is a group of its own, stamped with the
+ * moment it ran. There is always a group, so a rollback never has to fall back to counting migrations.
+ */
+export interface RunGroupOptions {
+  /**
+   * The group every migration this run applies is recorded under. Absent, a generated ISO-8601 timestamp
+   * is used — per run, by construction. A caller spanning several databases passes **one** value to all
+   * of them, so one run is one group however many databases it touches.
+   */
+  group?: string;
+}
+
+/**
+ * Run every pending migration to latest, recording the run's group against each one. An empty provider
+ * resolves to `[]` and records nothing.
+ *
+ * **The group is written from what Kysely hands back, and before the failure is raised.** A run that
+ * half-applies is retried with the key it already has, so the migrations that stuck have to be in the
+ * group — otherwise the retry's group would sit on top of an ungrouped migration, and reversing the
+ * retry would leave half a release applied with nothing recording it.
+ */
 export async function runMigrations(
   database: D1Database,
   provider: MigrationProvider,
   target?: MigrationTarget,
+  options?: RunGroupOptions,
 ): Promise<MigrationResult[]> {
   const { error, results } = await migrator(database, provider, target, undefined).migrateToLatest();
+  const applied = (results ?? [])
+    .filter((result) => result.direction === "Up" && result.status === "Success")
+    .map((result) => result.migrationName);
+  try {
+    await recordMigrationGroup(database, {
+      group: options?.group ?? generatedMigrationGroup(),
+      migrations: applied,
+    });
+  } catch (cause) {
+    // A migration failure is the operator's first problem and wins the throw; `settle` raises it below.
+    // With the run otherwise clean, a ledger that records a migration no group claims is its own fault.
+    if (error === undefined) {
+      throw new InternalError(
+        {
+          message: `Applied ${applied.length === 1 ? "a migration" : `${applied.length} migrations`}${on(target)}, then couldn't record the group.`,
+          detail: `${where(target)} ${reasonOf(cause)}`,
+          // Never "run pithy migrate again to record the group": the second run has nothing pending, so it
+          // records nothing and prints `Nothing to migrate.` while the group stays lost. The honest fact is
+          // what these migrations can no longer be — the group they were applied under is gone (#694).
+          action:
+            "Check the database is writable. A second run records nothing for them, so they cannot be reversed by group.",
+        },
+        { cause },
+      );
+    }
+  }
   return settle("run", error, results, target);
 }
 
@@ -153,9 +211,17 @@ export async function readMigrationLedger(database: D1Database, provider: Migrat
 }
 
 /**
- * Step this database's latest applied migration back — one step, per database. `pithy migrate --rollback`
- * calls it once for **every** database in its fan-out. Refused while a retained table here holds rows the
- * caller has not counted in `consent` (#588).
+ * Step this database's latest applied migration back — **one** step, in **one** database.
+ *
+ * It is no longer what `pithy migrate --rollback` runs: a rollback names a group and reverses that
+ * group's portion of each database ({@link reverseMigrationGroup}, #694). What this is, is the single
+ * step underneath — the primitive every capability's "its `down` is the inverse of its `up`" suite
+ * reverses one migration with, and the honest answer for a caller holding one migration rather than a
+ * release.
+ *
+ * It forgets the reversed migration's group row, so the group bookkeeping follows the ledger whichever
+ * way a migration came down. Refused while a retained table here holds rows the caller has not counted in
+ * `consent` (#588).
  */
 export async function rollbackMigration(
   database: D1Database,
@@ -164,9 +230,115 @@ export async function rollbackMigration(
   consent?: RetainedConsent,
 ): Promise<MigrationResult[]> {
   const { error, results } = await migrator(database, provider, target, consent).migrateDown();
+  await forgetReversed(database, results);
   return settle("rollback", error, results, target);
 }
 
+/** What one database reverses of a group: the group, and its migrations newest first. */
+export interface MigrationGroupStep {
+  /** The group being reversed — what the caller passed to `--group`. */
+  group: string;
+  /**
+   * This database's portion of it, in the order it comes down: newest first. The caller reads it from
+   * `readGroupPosition`, which is also what proves the group is the top of this database's chain. It says
+   * **whether** there is anything to reverse here; what comes down is read from the ledger again below, so
+   * a step that named a migration from the group underneath could not reverse it on the caller's word.
+   */
+  migrations: readonly string[];
+}
+
+/**
+ * **Reverse one group's portion of one database — the operation behind `pithy migrate --rollback
+ * --group` (#694).**
+ *
+ * Kysely steps down from the tip, so this is `migrateDown()` once per migration in the group, in reverse
+ * chain order, and **nothing outside it**. Both halves of that are read from the ledger here, not taken on
+ * the caller's word: the group has to be the ledger's own tail before the first `down`, and what each step
+ * brings down has to be one of the migrations that read said the group holds — anything else is an
+ * internal fault and throws rather than carrying on. **And a migration with no `down` stops the group**:
+ * Kysely reports one as `NotExecuted` and leaves it applied, so counting it as reversed is how a group
+ * reported itself fully rolled back with half of it still in the database. The caller's pre-flight is what
+ * makes a group reverse completely or not at all across databases; this is the floor under it.
+ *
+ * **One migrator for the whole group**, so the retained guard clears once and the caller's budget is spent
+ * once across every `down` it covers (#588). Each migration's group row is forgotten as it comes down —
+ * before the step's failure is raised — so a group reversal that dies partway can be re-run under the
+ * same group and reverses what is left.
+ */
+export async function reverseMigrationGroup(
+  database: D1Database,
+  provider: MigrationProvider,
+  step: MigrationGroupStep,
+  target?: MigrationTarget,
+  consent?: RetainedConsent,
+): Promise<MigrationResult[]> {
+  if (step.migrations.length === 0) return [];
+  // Asked of the ledger before the first `down`, so the ordinary ways to get this wrong — another group
+  // applied over this one, or a migration applied under no group at all — are refused rather than
+  // diagnosed afterwards, from under a `down` that has already run.
+  const position = await readGroupPosition(database, step.group);
+  if (position.state !== "top") {
+    throw new InternalError({
+      message: `Group "${step.group}" is not the top of ${target?.binding ?? "this database"}'s chain.`,
+      detail: `${where(target)} ${position.state === "absent" ? "It records nothing under that group." : `Applied over it: ${overIt(position.above, position.ungrouped)}.`}`,
+      action: `Run ${pithyCommand("doctor")} to see where each database stands.`,
+    });
+  }
+  // What comes down is what the ledger says this group holds, never the caller's list: a step naming a
+  // migration the group does not hold would otherwise be reversed on the caller's word.
+  const remaining = new Set(position.migrations);
+  const runner = migrator(database, provider, target, consent);
+  const reversed: MigrationResult[] = [];
+  while (remaining.size > 0) {
+    const { error, results } = await runner.migrateDown();
+    await forgetReversed(database, results);
+    const settled = settle("rollback", error, results, target);
+    if (settled.length === 0) break;
+    for (const result of settled) {
+      // **A migration with no `down` is a refusal, not a reversal.** Kysely's `#migrateDown` runs the body
+      // and deletes the ledger row only `if (migration.down)`, so one without it comes back `NotExecuted`
+      // — no error, row intact — and `./batch` preserves that shape deliberately. Counted as reversed, the
+      // group reported itself fully rolled back while part of it was still applied and still carried its
+      // group rows; and when the `down`-less migration was the group's newest, the next pass got the same
+      // tip back and the throw below blamed the chain's order for a missing `down`. So it stops here, in
+      // the one wording that names the cause, before the rest of the group comes down around it.
+      if (result.status !== "Success") {
+        throw new ValidationError({
+          message: `Migration "${result.migrationName}" has no down, so group "${step.group}" cannot be reversed${on(target)}.`,
+          action: `Give ${result.migrationName} a down, then reverse the group again.`,
+          // What already came down stays down, and the operator needs it by name to know where they are —
+          // the same fact `settle` reports for a forward run that failed partway.
+          detail: [
+            where(target),
+            reversed.length === 0
+              ? "Nothing was reversed. A group reverses completely or not at all."
+              : `Reversed before the refusal: ${reversed.map((entry) => `"${entry.migrationName}"`).join(", ")}. The rest of the group is still applied.`,
+          ]
+            .filter(Boolean)
+            .join(" "),
+        });
+      }
+      if (!remaining.delete(result.migrationName)) {
+        throw new InternalError({
+          message: `Reversing group "${step.group}"${on(target)} would have reversed "${result.migrationName}", which is not in it.`,
+          detail: `${where(target)} The group was not the top of this database's chain. Kysely steps down from the tip, so only the newest group can be reversed.`,
+          action: `Run ${pithyCommand("doctor")} to see where each database stands.`,
+        });
+      }
+      reversed.push(result);
+    }
+  }
+  return reversed;
+}
+
+/** Forget the group rows of whatever actually came down, whether or not the step then failed. */
+async function forgetReversed(database: D1Database, results: MigrationResult[] | undefined): Promise<void> {
+  const names = (results ?? [])
+    .filter((result) => result.direction === "Down" && result.status === "Success")
+    .map((result) => result.migrationName);
+  await forgetMigrationGroups(database, names);
+}
+
 /**
  * Fully reset one database's schema: every applied migration's `down` runs, in one pass, in reverse
  * chronological order — Kysely's `NO_MIGRATIONS` target, not just the latest — then every migration's
@@ -175,6 +347,16 @@ export async function rollbackMigration(
  * skip-if-exists) simply work afterward — there is no per-row identity problem to solve. An empty
  * ledger rolls back nothing; an empty provider reapplies nothing. Refused, before the first `down`, while a
  * retained table here holds rows the caller has not counted in `consent` (#588).
+ *
+ * **It leaves the group bookkeeping exactly as it was (#694).** The table is not a migration, so the `down`
+ * pass cannot remove it, and rewriting the rows would restamp somebody's release as having happened during
+ * a `seed --redo`. Every group row still describes a migration this reset reapplied.
+ *
+ * **What it does not do is record a group for the rest.** A reset reapplies everything *declared*, which
+ * includes migrations that were pending when it started, and those come back applied under no group — this
+ * takes no group and invents none. Such a migration sits over the groups below it, so a `--rollback
+ * --group` of one of them is refused by name (`./groups`, `readGroupPosition`) rather than reversing a
+ * migration nobody recorded.
  */
 export async function resetMigrations(
   database: D1Database,
@@ -191,17 +373,12 @@ export async function resetMigrations(
 }
 
 /**
- * The applied migration names recorded in the ledger — empty when the ledger table doesn't exist yet.
- * Existence is checked against `sqlite_master` (a plain select D1 permits) rather than by catching the
- * read's error, so a genuine read failure surfaces instead of being silently treated as "none applied".
+ * The applied migration names recorded in the ledger — empty when the ledger table doesn't exist yet. The
+ * set half of `appliedMigrationChain`, which is the one read of the ledger: order matters to a group
+ * rollback and not at all to a membership test, and two reads of one table would drift.
  */
 async function appliedMigrationNames(db: Kysely<unknown>): Promise<Set<string>> {
-  const present = await sql<{
-    name: string;
-  }>`select name from sqlite_master where type = 'table' and name = ${MIGRATION_TABLE}`.execute(db);
-  if (present.rows.length === 0) return new Set();
-  const { rows } = await sql<{ name: string }>`select name from ${sql.table(MIGRATION_TABLE)}`.execute(db);
-  return new Set(rows.map((row) => row.name));
+  return new Set(await appliedMigrationChain(db));
 }
 
 /**
@@ -264,6 +441,9 @@ export async function dropMigrations(
     try {
       await down(db);
       await sql`delete from ${sql.table(MIGRATION_TABLE)} where name = ${name}`.execute(db);
+      // The group bookkeeping follows the ledger row it describes: a dropped migration is not applied,
+      // so nothing may go on recording which run applied it.
+      await forgetMigrationGroups(database, [name]);
       results.push({ migrationName: name, direction: "Down", status: "Success" });
     } catch (error) {
       // A refusal is not a failed drop: nothing is broken, and "fix the migration's down" would be a lie.
@@ -273,7 +453,7 @@ export async function dropMigrations(
         {
           message: `Couldn't drop "${name}"${on(target)}. ${reasonOf(error)}`,
           detail: `${where(target)}${dropped.length ? ` Dropped before the failure: ${dropped.join(", ")}.` : ""}`,
-          action: "Fix the migration's down, or drop its table by hand. Run pithy remove --drop again.",
+          action: "Fix the migration's down, or drop its table by hand. Then run this again.",
         },
         { cause: error },
       );
@@ -287,27 +467,39 @@ const VOICE = {
   run: {
     failed: (key: string) => `Couldn't apply "${key}"`,
     fallback: "The migration run failed",
-    action: "Fix the migration. Run pithy migrate again.",
+    action: "Fix the migration, then run this again.",
   },
   rollback: {
     failed: (key: string) => `Couldn't roll back "${key}"`,
     fallback: "The rollback failed",
-    // Never "run --rollback again": a rollback steps back every database, so a second one after a partial
-    // failure reverses a second migration in each database that already moved (#588).
-    action: "Fix the migration's down. Run pithy doctor to see where each database stands.",
+    // Still not a bare "run --rollback again" — that command reverses nothing now, and before #694 it
+    // stepped a second migration back in every database that had already moved (#588). Re-running the
+    // *same group* is the safe retry: each migration's group row is forgotten as it comes down, so a
+    // second pass reverses what is left and nothing else. The group is on the command, not here.
+    action: `Fix the migration's down. Run ${pithyCommand("doctor")} to see where each database stands.`,
   },
   resetDown: {
     failed: (key: string) => `Couldn't roll back "${key}" during reset`,
     fallback: "The schema reset failed while rolling back",
-    action: "Fix the migration. Run pithy seed --redo again.",
+    action: "Fix the migration, then run this again.",
   },
   resetUp: {
     failed: (key: string) => `Couldn't reapply "${key}" during reset`,
     fallback: "The schema reset failed while reapplying",
-    action: "Fix the migration. Run pithy seed --redo again.",
+    action: "Fix the migration, then run this again.",
   },
 } as const;
 
+/**
+ * What sits over a buried group, groups and ungrouped migrations alike, newest first.
+ *
+ * An ungrouped migration is named with its state, because the two are different problems: another group is
+ * something to reverse first, while a migration no group claims cannot be reversed by group at all.
+ */
+function overIt(above: readonly string[], ungrouped: readonly string[]): string {
+  return [...above, ...ungrouped.map((name) => `${name} (ungrouped)`)].join(", ");
+}
+
 /** ` on DB`, or nothing at all — every problem line here ends with this and then a period. */
 function on(target: MigrationTarget | undefined): string {
   return target ? ` on ${target.binding}` : "";

package/src/naming/domains.ts

@@ -72,7 +72,73 @@ const PUNYCODE_LABEL = /(^|\.)xn--/;
  * them rather than a side effect of a parser version.
  */
 export function isPublicHostname(hostname: string): boolean {
-  return hostname.length <= 253 && HOSTNAME_PATTERN.test(hostname) && !PUNYCODE_LABEL.test(hostname);
+  return publicHostnameProblem(hostname) === null;
+}
+
+/** The DNS limit on a whole name, and the only length any caller measures. */
+const MAX_HOSTNAME_LENGTH = 253;
+
+/**
+ * Why a string is not a hostname a Worker can answer on — the reason, not a boolean.
+ *
+ * **It exists so a refusal can say which rule it broke.** {@link isPublicHostname} is the answer when the
+ * caller only needs yes or no; `WorkerDomain` needs the reason, because the three are not interchangeable
+ * to the adopter reading the message. A name over the limit is a typo. A name with a scheme on it is a
+ * misunderstanding. An internationalized name is neither — it is a thing this kit cannot do, for a reason
+ * that is not this kit's, and a message about bare hostnames would send that adopter looking for a typo
+ * they do not have (#665).
+ *
+ * Ordered by how specific the answer is. The length check is first because a name that long is over the
+ * limit whatever else is wrong with it, and `punycode` last because it is only reachable for a string that
+ * is otherwise a well-formed hostname.
+ */
+export function publicHostnameProblem(hostname: string): HostnameProblem | null {
+  if (hostname.length > MAX_HOSTNAME_LENGTH) return "too-long";
+  if (!HOSTNAME_PATTERN.test(hostname)) return "shape";
+  if (PUNYCODE_LABEL.test(hostname)) return "punycode";
+  return null;
+}
+
+/** The three ways a string fails {@link publicHostnameProblem}, each with its own sentence to say. */
+export type HostnameProblem = "too-long" | "shape" | "punycode";
+
+/**
+ * What an adopter is told, per reason, for a hostname this kit refuses.
+ *
+ * `shape` is the caller's to say, because what a bare hostname is differs between a `pattern` and a
+ * `zone` and each already had a sentence worth keeping. The other two are the same wherever they are hit.
+ *
+ * **The internationalized-domain sentence names Cloudflare**, and that is deliberate: the limit is not
+ * ours. `pithy-sh/pithy#691` tested it against a real zone — adding `tëst.pithy-sh.com` as a Worker
+ * Custom Domain returns *Internationalized Domain Names not supported* — so the kit refuses what the
+ * platform will not route rather than inventing a rule of its own. `docs/ACCEPTED-LIMITS.md` carries the
+ * evidence and the condition that would lift it.
+ */
+const HOSTNAME_PROBLEM_MESSAGES: Readonly<Record<Exclude<HostnameProblem, "shape">, string>> = {
+  "too-long": `A hostname is at most ${MAX_HOSTNAME_LENGTH} characters — the DNS limit on a whole name.`,
+  punycode:
+    "Internationalized domains are not supported: Cloudflare Workers will not route one, so a Worker could never answer on it. Use an ASCII hostname.",
+};
+
+/**
+ * One `pattern` or `zone` field, held to the one hostname rule.
+ *
+ * **Through {@link publicHostnameProblem}, never `HOSTNAME_PATTERN` directly.** A configured domain was
+ * the third caller of that rule and the only one that did not go through the function — it handed the
+ * pattern to `.regex()`, so it took a punycode A-label and a 267-character name that `pithy seed --host`
+ * refused for the same string. Two answers to one question, forty lines apart (#665). A rule added to the
+ * function now reaches a configured domain without anyone remembering to.
+ */
+function hostnameField(shapeMessage: string): z.ZodString {
+  return z.string().check((ctx) => {
+    const problem = publicHostnameProblem(ctx.value);
+    if (problem === null) return;
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      message: problem === "shape" ? shapeMessage : HOSTNAME_PROBLEM_MESSAGES[problem],
+    });
+  });
 }
 
 /** The environments a domain may be declared for — every managed one, never `dev`. */
@@ -81,21 +147,14 @@ export const DOMAIN_ENVIRONMENTS = ENVIRONMENTS.filter((environment) => environm
 /** One environment's public address for one Worker. */
 export 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.",
-      ),
+    pattern: hostnameField(
+      "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: hostnameField("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) => {

package/src/naming/environment.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { commandName } from "../cli/command";
 import { PithyError, ValidationError } from "../error/pithyError";
 import { NAME_SEGMENT } from "./segment";
 
@@ -144,7 +145,7 @@ export function assertValidEnvironment(name: string): void {
     throw new ValidationError({
       message: `"${name}" starts the way a feature's name does.`,
       action: "Start the environment with something other than f and a number.",
-      detail: `A feature takes the environment's slot with f<issue>, so <project>-${name}-<worker> can be a feature's Worker name exactly, and \`pithy feature destroy\` deletes that Worker.`,
+      detail: `A feature takes the environment's slot with f<issue>, so <project>-${name}-<worker> can be a feature's Worker name exactly, and \`${commandName("feature destroy")}\` deletes that Worker.`,
     });
   }
   if (name.length > MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name)) {

package/src/naming/packageName.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package a bare specifier names: `@pithy-sh/payments` from `@pithy-sh/payments/src/capability`, and
+ * `stripe` from `stripe/lib/x` — **scope-aware, and the only copy in the kit (#709)**.
+ *
+ * There were five. Three took the first segment or two depending on a leading `@`; two took the first two
+ * segments whatever they were, which is right for every `@pithy-sh/*` name they were written against and
+ * wrong for the first unscoped dependency anyone passed them. A rule that small drifts precisely because
+ * nobody thinks it needs a home, so it has one. That it is the only copy is a gate, not a claim: `packages/cli/src/ci/packageOfCopies.test.ts` fails on any source that writes the rule out by hand, because the first migration left three behind and said it had not.
+ *
+ * Total, and deliberately unopinionated about what it is handed: a caller with a relative path, a `#`
+ * import or a URL gets the first segment back. Deciding whether a specifier is a package at all is the
+ * unresolved-import classifier's job (`error/unresolved.ts`), not this function's.
+ */
+export function packageOf(specifier: string): string {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? specifier);
+}

package/src/naming/provisionScope.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { commandName } from "../cli/command";
 import { InternalError, ValidationError } from "../error/pithyError";
 import type { WorkflowHostNameParts } from "../workflow/naming";
 import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE, isFeatureMarker } from "./environment";
@@ -336,7 +337,7 @@ export function environmentScope(project: string, environment: string): Provisio
         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.`,
+          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 \`${commandName("feature destroy")}\` deletes it by that exact name.`,
         });
       }
       return name;