@pithy-sh/core 0.9.0 → 0.11.0

package/src/naming/limits.ts

@@ -107,6 +107,35 @@ export const NAMESPACE_LIMITS = {
    * no longer hashes one at 63.
    */
   kv: { label: "a KV namespace title", maxLength: 512, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * A Queue name: **1 to 63 characters**, lowercase letters, digits and dashes, starting and ending with a letter
+   * or number ([Queues · Get started](https://developers.cloudflare.com/queues/get-started/), verified
+   * 2026-10-18). Truncated rather than refused: Pithy recomputes a queue's name from its binding on every run,
+   * as it does a bucket's, so a deterministic hash is safe (#662). The same 63 as R2, so a feature's queue fits
+   * the shape {@link FEATURE_DERIVED_PROJECT_NAME} is derived against and moves no budget.
+   */
+  queue: { label: "a Queue name", maxLength: 63, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * An Artifacts namespace: **2 to 63 characters**, starting with a letter or digit, the rest letters, digits, `.`,
+   * `_` and `-` ([Artifacts · Limits](https://developers.cloudflare.com/artifacts/platform/limits/), verified
+   * 2026-10-18). Truncated rather than refused: the kit derives it from the project and the environment on every
+   * run, like an R2 bucket name, and the longest project and environment compose 34 characters, so it never is (#673).
+   */
+  artifactsNamespace: {
+    label: "an Artifacts namespace name",
+    maxLength: 63,
+    minLength: 2,
+    policy: "truncate",
+    source: "cloudflare",
+  },
+  /**
+   * An Artifacts repo name. **The charset is Cloudflare's** — a letter or digit, then letters, digits, `.`, `_` and
+   * `-` ([Artifacts · Limits](https://developers.cloudflare.com/artifacts/platform/limits/), verified 2026-10-18) —
+   * and **the length is ours**: that page states one for a namespace and none for a repo, so 2 to 63 mirrors the
+   * namespace rather than inventing a second number. Refused, never truncated: a repo name is either a UUID or a
+   * name somebody chose, and a name somebody chose is never silently shortened (#673).
+   */
+  artifactsRepo: { label: "an Artifacts repo name", maxLength: 63, minLength: 2, policy: "refuse", source: "pithy" },
   /**
    * 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}.
@@ -196,7 +225,10 @@ export const FEATURE_TAIL_SEPARATOR = "--";
  */
 export const MIN_VERBATIM_BINDING = 12;
 
-/** The longest feature resource kind — `d1`, `kv`, `r2` are all two characters. `feature.test.ts` pins it. */
+/**
+ * The longest feature resource kind segment — `d1`, `kv`, `r2`, and a queue's `q` (#662). `feature.test.ts` pins
+ * every kind's `FEATURE_KIND_SEGMENT` to it, so a longer segment fails rather than shrinking every project's budget.
+ */
 export const MAX_FEATURE_KIND = 2;
 
 /**
@@ -217,7 +249,7 @@ export const WORKFLOW_DERIVED_PROJECT_NAME =
 
 /**
  * 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
+ * against R2's 63 (the strictest of the kinds a feature provisions, a queue's number too, and the same number a
  * feature Worker script gets).
  *
  * ```
@@ -226,7 +258,7 @@ export const WORKFLOW_DERIVED_PROJECT_NAME =
  *   -  6   the issue number, six digits — `f999999` (MAX_ISSUE_DIGITS)
  *   - 12   `-` + a legible slug (MIN_LEGIBLE_SLUG)
  *   - 14   `--` + a binding kept whole (FEATURE_TAIL_SEPARATOR, MIN_VERBATIM_BINDING)
- *   -  3   `-` + the kind, `d1` | `kv` | `r2`
+ *   -  3   `-` + the kind, `d1` | `kv` | `r2` | `q`
  *   ----
  *     26
  * ```

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,12 +1,14 @@
 // 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";
 import {
   type FeatureIdentity,
   type FeatureResourceKind,
+  featureArtifactsNamespace,
   featureResourceName,
   featureSecretEntryName,
   featureWorkerName,
@@ -188,10 +190,21 @@ export interface ProvisionScope {
    * `<project>-feature-email-send` would be one Workflow every open branch deployed over every other's.
    */
   readonly workflowHost: Omit<WorkflowHostNameParts, "capability">;
+  /**
+   * The Artifacts namespace an `artifacts` binding names in this scope (#673): `<project>-<env>` in a declared
+   * environment, `<project>-f<issue>-<slug>--artifacts` in a feature. On the scope for the reason every other name
+   * is: the stanza a run writes and the namespace it writes into it are one decision.
+   */
+  readonly artifactsNamespace: string;
 }
 
 /** The wrangler binding array a resource kind's name is composed for. */
-const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2"> = { d1: "d1", kv: "kv", r2: "r2" };
+const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2" | "queue"> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  queue: "queue",
+};
 
 /**
  * The one branch every scope shares: a `global` secret resolves to the project's single
@@ -336,7 +349,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;
@@ -344,6 +357,7 @@ export function environmentScope(project: string, environment: string): Provisio
     secretEntry: (secret, secretScope) =>
       secretEntryName(project, secret, secretScope, () => names.secretEntry(secret)),
     workflowHost: { project, env: environment },
+    artifactsNamespace: names.artifactsNamespace(),
   };
 }
 
@@ -391,6 +405,11 @@ export function featureScope(identity: FeatureIdentity): ProvisionScope {
     secretEntry: (secret) => featureSecretEntryName(identity, secret),
     // `env` is the stanza — what the host's `ENVIRONMENT` var says — and `feature` is what its names take.
     workflowHost: { project: identity.project, env: FEATURE_ENVIRONMENT, feature: identity },
+    // The feature's own, read back as its own by `isFeatureOwnedName`, so teardown reaps no sibling's repos. A
+    // getter, so a slug too long for it refuses where the namespace is asked for, never where the scope is made.
+    get artifactsNamespace() {
+      return featureArtifactsNamespace(identity);
+    },
   };
 }
 

package/src/naming/resourceNames.ts

@@ -4,7 +4,13 @@
 import { InternalError, ValidationError } from "../error/pithyError";
 import { workflowHostName, workflowScriptName } from "../workflow/naming";
 import { assertValidEnvironment, GLOBAL_SCOPE } from "./environment";
-import { type FeatureIdentity, type FeatureResourceKind, featureResourceName, featureWorkerName } from "./feature";
+import {
+  type FeatureIdentity,
+  type FeatureResourceKind,
+  featureArtifactsNamespace,
+  featureResourceName,
+  featureWorkerName,
+} from "./feature";
 import { NAMESPACE_LIMITS, type NamespaceLimit } from "./limits";
 import { assertValidProjectName, kebab, resourceName } from "./resource";
 
@@ -57,6 +63,8 @@ export interface ScopedNames {
   kv(binding: string): string;
   /** An R2 bucket. Cloudflare's 63 — the one namespace where that number was always right. */
   r2(binding: string): string;
+  /** A Queue. Cloudflare's 63, truncated with a stable hash like a bucket (#662). */
+  queue(binding: string): string;
   /** A Vectorize index. 64 bytes, refused rather than truncated: a renamed index has no vectors. */
   vectorizeIndex(index: string): string;
   /** A Secrets Store entry. No Cloudflare cap; Pithy's ceiling. */
@@ -65,15 +73,33 @@ export interface ScopedNames {
   apiToken(profile: string): string;
 }
 
+/**
+ * The names in one declared environment: everything a scope has, and the one name that exists per environment
+ * and never at `global`.
+ */
+export interface EnvironmentNames extends ScopedNames {
+  /**
+   * The Artifacts namespace — `<project>-<env>`, with no `<thing>` (#673). One per environment, so a feature's
+   * repos never sit beside production's and the per-namespace rate limit splits per environment. There is no
+   * global one, because a namespace shared across environments is exactly that mix.
+   */
+  artifactsNamespace(): string;
+}
+
 /** The names a feature environment provisions under, with the project already bound. */
 export interface FeatureNames {
-  /** A feature's D1, KV, or R2 resource — `<project>-f<issue>-<slug>-<binding>-<kind>`. */
+  /** A feature's D1, KV, R2 or Queue resource — `<project>-f<issue>-<slug>--<binding>-<kind>`. */
   resource(binding: string, kind: FeatureResourceKind): 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;
+  /**
+   * A feature's Artifacts namespace — `<project>-f<issue>-<slug>--artifacts` (#673). The tail is what makes it a
+   * feature name `isFeatureOwnedName` reads back, so teardown reaps this feature's repos and no sibling's.
+   */
+  artifactsNamespace(): string;
 }
 
 /** Everything a project can be asked to name. Created once, from the project, by {@link resourceNames}. */
@@ -81,7 +107,7 @@ export interface ProjectNames {
   /** The kebabbed project name every name below leads with. */
   readonly project: string;
   /** The names in one environment. Throws if the environment is not one this scheme accepts. */
-  env(environment: string): ScopedNames;
+  env(environment: string): EnvironmentNames;
   /** The names shared by every environment — the `global` scope, without typing the word. */
   readonly global: ScopedNames;
   /** The names a feature environment provisions under. */
@@ -134,6 +160,22 @@ function scopedName(project: string, scope: string, thing: string, limit: Namesp
   return name;
 }
 
+/**
+ * `<project>-<env>`, under the Artifacts namespace rule. The project and environment are both validated by now, and
+ * the longest of each compose 34 characters, so the cap is a check rather than a truncation that ever happens.
+ */
+function artifactsNamespaceName(project: string, environment: string): string {
+  const limit = NAMESPACE_LIMITS.artifactsNamespace;
+  const name = `${project}-${environment}`;
+  if (name.length > limit.maxLength || name.length < limit.minLength) {
+    throw new InternalError({
+      message: `"${name}" does not fit ${limit.label}, which takes ${limit.minLength} to ${limit.maxLength} characters.`,
+      action: "Shorten the project or environment name.",
+    });
+  }
+  return name;
+}
+
 /** The getters for one scope. `global` and every environment share this, so nothing special-cases either. */
 function scopedNames(project: string, scope: string): ScopedNames {
   return {
@@ -142,6 +184,7 @@ function scopedNames(project: string, scope: string): ScopedNames {
     d1: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.d1),
     kv: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.kv),
     r2: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.r2),
+    queue: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.queue),
     vectorizeIndex: (index) => scopedName(project, scope, index, NAMESPACE_LIMITS.vectorizeIndex),
     secretEntry: (secret) => scopedName(project, scope, secret, NAMESPACE_LIMITS.secretEntry),
     apiToken: (profile) => scopedName(project, scope, profile, NAMESPACE_LIMITS.apiToken),
@@ -161,9 +204,12 @@ export function resourceNames(project: string): ProjectNames {
 
   return {
     project: normalized,
-    env(environment: string): ScopedNames {
+    env(environment: string): EnvironmentNames {
       assertValidEnvironment(environment);
-      return scopedNames(normalized, environment);
+      return {
+        ...scopedNames(normalized, environment),
+        artifactsNamespace: () => artifactsNamespaceName(normalized, environment),
+      };
     },
     global: scopedNames(normalized, GLOBAL_SCOPE),
     feature(identity): FeatureNames {
@@ -171,6 +217,7 @@ export function resourceNames(project: string): ProjectNames {
       return {
         resource: (binding, kind) => featureResourceName(full, binding, kind),
         worker: (app) => featureWorkerName(full, app),
+        artifactsNamespace: () => featureArtifactsNamespace(full),
       };
     },
   };