canopycms 0.0.67-int.90 → 0.0.67

package/dist/http/types.d.ts

@@ -1,53 +1,32 @@
-/**
- * Framework-agnostic HTTP request interface.
- * Minimal surface area - only what CanopyCMS actually needs.
- */
+/** Framework-agnostic HTTP request: only what CanopyCMS actually needs. */
 export interface CanopyRequest {
-    /** HTTP method (GET, POST, PUT, DELETE, etc.) */
     readonly method: string;
-    /** Full request URL as string */
     readonly url: string;
-    /**
-     * Get request header value (case-insensitive).
-     * Returns null if header not present.
-     */
+    /** Case-insensitive; null when the header is absent. */
     header(name: string): string | null;
-    /**
-     * Parse request body as JSON.
-     * Returns undefined for GET requests or empty bodies.
-     */
+    /** Undefined for GET requests and empty bodies. */
     json(): Promise<unknown>;
     /**
-     * Read the raw request body as bytes, bypassing JSON parsing.
-     * Optional: only wired by adapters that need to support non-JSON bodies
-     * (e.g. proxied binary/multipart uploads). Bare CanopyRequest mocks/test
-     * harnesses that omit this keep compiling.
+     * The raw body bytes, bypassing JSON parsing. Optional, so that adapters
+     * without non-JSON bodies (and bare test mocks) still compile.
      *
-     * Like the underlying platform Request, the body stream can only be
-     * consumed once - callers must not also call `json()`/`formData()` on the
-     * same request.
+     * As with the platform Request, the body stream is consumed ONCE: a caller
+     * using this must not also call `json()` or `formData()`.
      */
     rawBody?(): Promise<Uint8Array>;
-    /**
-     * Parse the request body as multipart/form-data.
-     * Optional for the same reason as `rawBody` above.
-     */
+    /** Optional, and single-use, for the same reasons as `rawBody`. */
     formData?(): Promise<FormData>;
 }
-/**
- * Framework-agnostic HTTP response.
- * Represents the response data to be sent back.
- */
+/** Framework-agnostic HTTP response. */
 export interface CanopyResponse<T = unknown> {
     readonly status: number;
     readonly body: T;
     readonly headers?: Record<string, string>;
 }
 /**
- * Framework-agnostic binary HTTP response (e.g. serving image/PDF bytes).
- * Distinct from `CanopyResponse` via the `kind` discriminant so adapters can
- * dispatch on response shape without a cast: `body` is arbitrary bytes
- * (or a stream of them), not a JSON-serializable value.
+ * A binary response (image/PDF bytes). The `kind` discriminant lets adapters
+ * dispatch without a cast: `body` here is arbitrary bytes or a stream of them,
+ * not a JSON-serializable value.
  */
 export interface CanopyBinaryResponse {
     readonly kind: 'binary';
@@ -60,14 +39,10 @@ export interface CanopyBinaryResponse {
         etag?: string;
     };
 }
-/**
- * Create a JSON response with the given body and status code.
- */
 export declare function jsonResponse<T>(body: T, status?: number, headers?: Record<string, string>): CanopyResponse<T>;
 /**
- * Type guard distinguishing `CanopyBinaryResponse` from any other route
- * result (`ApiResponse`/`CanopyResponse`, neither of which declare `kind`).
- * Framework adapters and the core handler use this to decide whether to
- * pass a route result through untouched or wrap it via `jsonResponse`.
+ * Distinguishes `CanopyBinaryResponse` from any other route result (neither
+ * `ApiResponse` nor `CanopyResponse` declares `kind`), which is how adapters
+ * and the core handler decide to pass a result through or wrap it in JSON.
  */
 export declare function isCanopyBinaryResponse(value: unknown): value is CanopyBinaryResponse;

package/dist/http/types.js

@@ -1,14 +1,10 @@
-/**
- * Create a JSON response with the given body and status code.
- */
 export function jsonResponse(body, status = 200, headers) {
     return { status, body, headers };
 }
 /**
- * Type guard distinguishing `CanopyBinaryResponse` from any other route
- * result (`ApiResponse`/`CanopyResponse`, neither of which declare `kind`).
- * Framework adapters and the core handler use this to decide whether to
- * pass a route result through untouched or wrap it via `jsonResponse`.
+ * Distinguishes `CanopyBinaryResponse` from any other route result (neither
+ * `ApiResponse` nor `CanopyResponse` declares `kind`), which is how adapters
+ * and the core handler decide to pass a result through or wrap it in JSON.
  */
 export function isCanopyBinaryResponse(value) {
     return (typeof value === 'object' && value !== null && value.kind === 'binary');

package/dist/id.d.ts

@@ -1,16 +1,10 @@
 import type { ContentId } from './paths/types.js';
 import { isValidContentId } from './paths/validation.js';
 /**
- * Generate a new 12-character content ID.
- * Uses Base58-encoded UUID, truncated for shorter filenames.
- *
- * Collision probability with 12 chars:
- * - ~58^12 = 2.6 × 10^21 possible IDs
- * - With 10,000 entries: collision chance ~0.000000002%
+ * Generate a 12-character content ID: a Base58-encoded UUID truncated for
+ * shorter filenames. ~58^12 = 2.6 × 10^21 IDs, so 10,000 entries carry a
+ * ~0.000000002% collision chance.
  */
 export declare function generateId(): ContentId;
-/**
- * Validate that a string is a valid content ID format.
- * Standard format: 12 characters using Base58 alphabet (no ambiguous characters: 0, O, I, l).
- */
+/** Is a string a valid content ID? 12 Base58 characters (no ambiguous 0, O, I, l). */
 export declare const isValidId: typeof isValidContentId;

package/dist/id.js

@@ -1,19 +1,13 @@
 import { generate } from 'short-uuid';
 import { isValidContentId } from './paths/validation.js';
 /**
- * Generate a new 12-character content ID.
- * Uses Base58-encoded UUID, truncated for shorter filenames.
- *
- * Collision probability with 12 chars:
- * - ~58^12 = 2.6 × 10^21 possible IDs
- * - With 10,000 entries: collision chance ~0.000000002%
+ * Generate a 12-character content ID: a Base58-encoded UUID truncated for
+ * shorter filenames. ~58^12 = 2.6 × 10^21 IDs, so 10,000 entries carry a
+ * ~0.000000002% collision chance.
  */
 export function generateId() {
     const full = generate(); // 22 chars
     return full.substring(0, 12); // Truncate to 12 chars
 }
-/**
- * Validate that a string is a valid content ID format.
- * Standard format: 12 characters using Base58 alphabet (no ambiguous characters: 0, O, I, l).
- */
+/** Is a string a valid content ID? 12 Base58 characters (no ambiguous 0, O, I, l). */
 export const isValidId = isValidContentId;

package/dist/index.js

@@ -3,18 +3,15 @@ export * from './config/index.js';
 export * from './entry-schema.js';
 export * from './types.js';
 export * from './user.js';
-// Title-derivation fallback chain (schema isTitle field -> data.title/name ->
-// entry-type label -> humanized slug -> "Untitled"). Client-safe (its only
-// import is `FieldConfig`/`InlineGroupFieldConfig` types, erased at compile
-// time, so no runtime dependency at all) — re-exported here as well as from
-// 'canopycms/server' so client-side list/preview UI can compute the same
-// display title as build scripts without a second implementation.
+// Title-derivation fallback chain (schema isTitle field -> data.title/name -> entry-type label ->
+// humanized slug -> "Untitled"). Client-safe: its only imports are types, erased at compile time.
+// Exported from 'canopycms/server' too, so client list/preview UI and build scripts derive the
+// same display title from one implementation.
 export { resolveEntryTitle } from './utils/title-field.js';
 // AI content config helper — client-safe (no node: imports).
 // Server-only AI features (handler, generator) are in 'canopycms/ai'.
 export { defineAIContentConfig } from './ai/types.js';
 export { isCanopyRequest, isHeadersLike, extractHeaders, validateAuthContext, } from './auth/context-helpers.js';
-// Asset URL helpers — client-safe (no node: imports). Build/adjust transform
-// URLs for <img>/srcset from stored asset refs without pulling in the
-// server-only transform engine (canopycms's assets/transform.ts, sharp).
+// Asset URL helpers — client-safe (no node: imports). Build/adjust transform URLs for <img>/srcset
+// from stored asset refs without the server-only transform engine (assets/transform.ts, sharp).
 export { assetUrl, assetSrcSet } from './assets/asset-url.js';

package/dist/operating-mode/client-safe-strategy.d.ts

@@ -1,10 +1,7 @@
 /**
- * Client-Safe Operating Mode Strategies
- *
- * Base strategy classes that are safe to import in 'use client' React components.
- * NO Node.js imports (fs, path, process, etc.) - only pure logic and simple data.
- *
- * These classes are extended by client-unsafe strategies to add Node.js functionality.
+ * Base strategy classes, safe in 'use client' React components: pure logic and
+ * simple data, NO Node.js imports. client-unsafe-strategy.ts extends these to
+ * add the Node.js surface.
  */
 import type { OperatingMode, ClientSafeStrategy } from './types.js';
 export declare class ProdClientSafeStrategy implements ClientSafeStrategy {
@@ -30,16 +27,12 @@ export declare class DevClientSafeStrategy implements ClientSafeStrategy {
     shouldPush(): boolean;
 }
 /**
- * Get the client-safe strategy for an operating mode.
- *
- * Strategies are memoized - one instance per mode for the entire process lifetime.
- * Safe to call inline: clientOperatingStrategy(mode).supportsBranching()
- *
- * @param mode - The operating mode
- * @returns Client-safe strategy instance
+ * Memoized: one instance per mode for the process lifetime, so this is safe to
+ * call inline — `clientOperatingStrategy(mode).supportsBranching()`.
  */
 export declare function clientOperatingStrategy(mode: OperatingMode): ClientSafeStrategy;
 /**
- * Clear the client strategy cache (mainly for testing)
+ * Mainly for testing.
+ * @internal Exported for tests.
  */
 export declare function clearClientStrategyCache(): void;

package/dist/operating-mode/client-safe-strategy.js

@@ -1,19 +1,12 @@
 /**
- * Client-Safe Operating Mode Strategies
- *
- * Base strategy classes that are safe to import in 'use client' React components.
- * NO Node.js imports (fs, path, process, etc.) - only pure logic and simple data.
- *
- * These classes are extended by client-unsafe strategies to add Node.js functionality.
+ * Base strategy classes, safe in 'use client' React components: pure logic and
+ * simple data, NO Node.js imports. client-unsafe-strategy.ts extends these to
+ * add the Node.js surface.
  */
-// ============================================================================
-// Production Mode - Client-Safe Strategy
-// ============================================================================
 export class ProdClientSafeStrategy {
     constructor() {
         this.mode = 'prod';
     }
-    // UI Feature Flags
     supportsBranching() {
         return true;
     }
@@ -26,7 +19,6 @@ export class ProdClientSafeStrategy {
     supportsPullRequests() {
         return true;
     }
-    // Simple Data
     getPermissionsFileName() {
         return 'permissions.json';
     }
@@ -40,14 +32,10 @@ export class ProdClientSafeStrategy {
         return true;
     }
 }
-// ============================================================================
-// Dev Mode - Client-Safe Strategy
-// ============================================================================
 export class DevClientSafeStrategy {
     constructor() {
         this.mode = 'dev';
     }
-    // UI Feature Flags
     supportsBranching() {
         return true;
     }
@@ -60,7 +48,6 @@ export class DevClientSafeStrategy {
     supportsPullRequests() {
         return false; // No real GitHub in local dev mode
     }
-    // Simple Data
     getPermissionsFileName() {
         return 'permissions.json';
     }
@@ -74,18 +61,10 @@ export class DevClientSafeStrategy {
         return true;
     }
 }
-// ============================================================================
-// Factory with Memoization
-// ============================================================================
 const clientStrategyCache = new Map();
 /**
- * Get the client-safe strategy for an operating mode.
- *
- * Strategies are memoized - one instance per mode for the entire process lifetime.
- * Safe to call inline: clientOperatingStrategy(mode).supportsBranching()
- *
- * @param mode - The operating mode
- * @returns Client-safe strategy instance
+ * Memoized: one instance per mode for the process lifetime, so this is safe to
+ * call inline — `clientOperatingStrategy(mode).supportsBranching()`.
  */
 export function clientOperatingStrategy(mode) {
     const cached = clientStrategyCache.get(mode);
@@ -100,7 +79,7 @@ export function clientOperatingStrategy(mode) {
             strategy = new DevClientSafeStrategy();
             break;
         default: {
-            // Exhaustiveness check - TypeScript will error if a mode is not handled
+            // Exhaustiveness check: adding a mode without a case fails to compile.
             const _exhaustive = mode;
             throw new Error(`Unknown operating mode: ${_exhaustive}`);
         }
@@ -109,7 +88,8 @@ export function clientOperatingStrategy(mode) {
     return strategy;
 }
 /**
- * Clear the client strategy cache (mainly for testing)
+ * Mainly for testing.
+ * @internal Exported for tests.
  */
 export function clearClientStrategyCache() {
     clientStrategyCache.clear();

package/dist/operating-mode/client-unsafe-strategy.d.ts

@@ -1,25 +1,15 @@
 /**
- * Client-Unsafe Operating Mode Strategies
- *
- * Full strategy implementations that extend client-safe base classes.
- * INCLUDES Node.js imports (fs, path, process) - can only be imported server-side.
- *
- * These classes inherit all client-safe methods and add client-unsafe functionality.
+ * Full strategies: the client-safe base classes plus the methods that need
+ * Node.js (fs, path, process). Server-side imports only.
  */
 import type { OperatingMode, ClientUnsafeStrategy } from './types.js';
 /**
- * Get the full strategy (client-unsafe) for an operating mode.
- *
- * Strategies are memoized - one instance per mode for the entire process lifetime.
- * Safe to call inline: operatingStrategy(mode).getBaseRoot()
- *
- * Includes all client-safe methods (inherited) plus client-unsafe methods (Node.js APIs).
- *
- * @param mode - The operating mode
- * @returns Full strategy instance with client-unsafe methods
+ * Memoized: one instance per mode for the process lifetime, so this is safe to
+ * call inline — `operatingStrategy(mode).getWorkspaceRoot()`.
  */
 export declare function operatingStrategy(mode: OperatingMode): ClientUnsafeStrategy;
 /**
- * Clear the strategy cache (mainly for testing)
+ * Mainly for testing.
+ * @internal Exported for tests.
  */
 export declare function clearStrategyCache(): void;

package/dist/operating-mode/client-unsafe-strategy.js

@@ -1,30 +1,18 @@
 /**
- * Client-Unsafe Operating Mode Strategies
- *
- * Full strategy implementations that extend client-safe base classes.
- * INCLUDES Node.js imports (fs, path, process) - can only be imported server-side.
- *
- * These classes inherit all client-safe methods and add client-unsafe functionality.
+ * Full strategies: the client-safe base classes plus the methods that need
+ * Node.js (fs, path, process). Server-side imports only.
  */
 import path from 'node:path';
 import { ProdClientSafeStrategy, DevClientSafeStrategy } from './client-safe-strategy.js';
 import { resolveDeploymentName } from './deployment-name.js';
 import { DEFAULT_PROD_WORKSPACE } from '../config/index.js';
-// ============================================================================
-// Production Mode - Full Strategy
-// ============================================================================
 class ProdStrategy extends ProdClientSafeStrategy {
-    // All client-safe methods inherited automatically from ProdClientSafeStrategy:
-    // - mode, supportsBranching(), supportsStatusBadge(), supportsComments()
-    // - supportsPullRequests(), getPermissionsFileName(), getGroupsFileName()
-    // - shouldCommit(), shouldPush()
-    // Add client-unsafe methods (use Node.js APIs)
     getWorkspaceRoot(_sourceRoot) {
         return path.resolve(process.env.CANOPYCMS_WORKSPACE_ROOT ?? DEFAULT_PROD_WORKSPACE);
     }
     getContentRoot(contentRoot, sourceRoot) {
-        // In prod, content is at workspace root (not project root)
-        // This is called with sourceRoot = workspace path
+        // In prod the caller passes sourceRoot = the workspace path, because
+        // content sits at the workspace root rather than a project root.
         return path.resolve(sourceRoot ?? process.cwd(), contentRoot);
     }
     getContentBranchesRoot(sourceRoot) {
@@ -73,11 +61,7 @@ class ProdStrategy extends ProdClientSafeStrategy {
         return config.autoCreateSettingsPR ?? true;
     }
 }
-// ============================================================================
-// Dev Mode - Full Strategy
-// ============================================================================
 class DevStrategy extends DevClientSafeStrategy {
-    // Inherits client-safe methods from DevClientSafeStrategy
     getWorkspaceRoot(sourceRoot) {
         return path.resolve(sourceRoot ?? process.cwd(), '.canopy-dev');
     }
@@ -127,20 +111,10 @@ class DevStrategy extends DevClientSafeStrategy {
         return false; // No real GitHub in local dev mode
     }
 }
-// ============================================================================
-// Factory with Memoization
-// ============================================================================
 const strategyCache = new Map();
 /**
- * Get the full strategy (client-unsafe) for an operating mode.
- *
- * Strategies are memoized - one instance per mode for the entire process lifetime.
- * Safe to call inline: operatingStrategy(mode).getBaseRoot()
- *
- * Includes all client-safe methods (inherited) plus client-unsafe methods (Node.js APIs).
- *
- * @param mode - The operating mode
- * @returns Full strategy instance with client-unsafe methods
+ * Memoized: one instance per mode for the process lifetime, so this is safe to
+ * call inline — `operatingStrategy(mode).getWorkspaceRoot()`.
  */
 export function operatingStrategy(mode) {
     const cached = strategyCache.get(mode);
@@ -155,7 +129,7 @@ export function operatingStrategy(mode) {
             strategy = new DevStrategy();
             break;
         default: {
-            // Exhaustiveness check - TypeScript will error if a mode is not handled
+            // Exhaustiveness check: adding a mode without a case fails to compile.
             const _exhaustive = mode;
             throw new Error(`Unknown operating mode: ${_exhaustive}`);
         }
@@ -164,7 +138,8 @@ export function operatingStrategy(mode) {
     return strategy;
 }
 /**
- * Clear the strategy cache (mainly for testing)
+ * Mainly for testing.
+ * @internal Exported for tests.
  */
 export function clearStrategyCache() {
     strategyCache.clear();

package/dist/operating-mode/client.d.ts

@@ -1,12 +1,5 @@
 /**
- * Client-Safe Operating Mode Strategy - Client Bundle Entry Point
- *
- * This module ONLY exports client-safe functionality with NO Node.js imports.
- * Safe to import in 'use client' React components.
- *
- * Usage in client components:
- *   import { clientOperatingStrategy } from '@/operating-mode/client'
+ * Client-bundle entry point: exports ONLY client-safe functionality, with no
+ * Node.js imports, so it is safe in 'use client' React components.
  */
-export { clientOperatingStrategy, clearClientStrategyCache } from './client-safe-strategy.js';
-export type { ClientSafeStrategy } from './types.js';
-export type { OperatingMode } from './types.js';
+export { clientOperatingStrategy } from './client-safe-strategy.js';

package/dist/operating-mode/client.js

@@ -1,10 +1,5 @@
 /**
- * Client-Safe Operating Mode Strategy - Client Bundle Entry Point
- *
- * This module ONLY exports client-safe functionality with NO Node.js imports.
- * Safe to import in 'use client' React components.
- *
- * Usage in client components:
- *   import { clientOperatingStrategy } from '@/operating-mode/client'
+ * Client-bundle entry point: exports ONLY client-safe functionality, with no
+ * Node.js imports, so it is safe in 'use client' React components.
  */
-export { clientOperatingStrategy, clearClientStrategyCache } from './client-safe-strategy.js';
+export { clientOperatingStrategy } from './client-safe-strategy.js';

package/dist/operating-mode/deployment-name-fixtures.d.ts

@@ -1,30 +1,26 @@
 /**
  * Shared deployment-name test fixture.
  *
- * The rule that decides whether a `deploymentName` is usable exists TWICE, by
- * necessity: once at runtime (`deployment-name.ts`'s `isValidDeploymentName`)
- * and once at synth time (`canopycms-cdk`'s `constructs/cms-service.ts`).
- * The construct deliberately does not import the real thing — see
- * `isValidDeploymentName`'s doc comment in cms-service.ts for why (not, as
- * this comment used to say, that the published construct lacks a runtime
- * dependency on `canopycms` — it doesn't).
+ * The rule deciding whether a `deploymentName` is usable exists TWICE by
+ * necessity: at runtime (`deployment-name.ts`'s `isValidDeploymentName`) and at
+ * synth time (`canopycms-cdk`'s `constructs/cms-service.ts`, which deliberately
+ * does not import the real thing — see its own doc comment for why).
  *
  * The dangerous drift is asymmetric: a rule TIGHTENED at runtime but not at
- * synth produces a stack that synths clean and then crash-loops the Lambda at
- * boot — precisely what the synth guard exists to prevent. So both packages'
- * suites assert against this one list, and `canopycms-cdk`'s suite additionally
- * asserts that the construct's verdict matches this package's predicate for
- * every name here. Add a case here when you change either copy of the rule.
+ * synth synths clean and then crash-loops the Lambda at boot, precisely what the
+ * synth guard exists to prevent. So both packages' suites assert against this
+ * one list, and `canopycms-cdk`'s also asserts that the construct's verdict
+ * matches this package's predicate for every name here. Add a case when you
+ * change either copy of the rule.
  *
- * Deliberately dependency-free (plain arrays, no vitest import) so the CDK
- * suite can import it across the package boundary without dragging anything
- * along.
+ * Dependency-free (plain arrays, no vitest import) so the CDK suite can import
+ * it across the package boundary.
  */
 /** Names both copies of the rule must ACCEPT. */
 export declare const VALID_DEPLOYMENT_NAMES: readonly ["prod", "staging", "acme-prod_2.1", "a", "9lives", "team.prod", "PROD", "x.locked"];
 /**
- * Names both copies of the rule must REJECT, each with the reason it exists —
- * every entry is a value git itself would refuse as a ref component, or one
- * that would corrupt the worker's `.env` heredoc.
+ * Names both copies of the rule must REJECT: each is either a value git itself
+ * refuses as a ref component, or one that would corrupt the worker's `.env`
+ * heredoc.
  */
 export declare const INVALID_DEPLOYMENT_NAMES: readonly [readonly ["a slash (would add a ref hierarchy level)", "team/prod"], readonly ["whitespace", "my prod"], readonly ["a leading dash (parses as a git option)", "-prod"], readonly ["a git-forbidden character", "prod:1"], readonly ["dot-dot", "a..b"], readonly ["a leading dot", ".prod"], readonly ["a trailing dot", "prod."], readonly ["a .lock suffix", "prod.lock"], readonly ["a tilde", "prod~1"], readonly ["a caret", "prod^1"], readonly ["a question mark", "prod?"], readonly ["an asterisk", "prod*"], readonly ["an open bracket", "prod["], readonly ["a backslash", "prod\\1"], readonly ["the empty string", ""], readonly ["a newline (would inject a line into the worker .env)", "prod\nEVIL=1"]];

package/dist/operating-mode/deployment-name-fixtures.js

@@ -1,24 +1,20 @@
 /**
  * Shared deployment-name test fixture.
  *
- * The rule that decides whether a `deploymentName` is usable exists TWICE, by
- * necessity: once at runtime (`deployment-name.ts`'s `isValidDeploymentName`)
- * and once at synth time (`canopycms-cdk`'s `constructs/cms-service.ts`).
- * The construct deliberately does not import the real thing — see
- * `isValidDeploymentName`'s doc comment in cms-service.ts for why (not, as
- * this comment used to say, that the published construct lacks a runtime
- * dependency on `canopycms` — it doesn't).
+ * The rule deciding whether a `deploymentName` is usable exists TWICE by
+ * necessity: at runtime (`deployment-name.ts`'s `isValidDeploymentName`) and at
+ * synth time (`canopycms-cdk`'s `constructs/cms-service.ts`, which deliberately
+ * does not import the real thing — see its own doc comment for why).
  *
  * The dangerous drift is asymmetric: a rule TIGHTENED at runtime but not at
- * synth produces a stack that synths clean and then crash-loops the Lambda at
- * boot — precisely what the synth guard exists to prevent. So both packages'
- * suites assert against this one list, and `canopycms-cdk`'s suite additionally
- * asserts that the construct's verdict matches this package's predicate for
- * every name here. Add a case here when you change either copy of the rule.
+ * synth synths clean and then crash-loops the Lambda at boot, precisely what the
+ * synth guard exists to prevent. So both packages' suites assert against this
+ * one list, and `canopycms-cdk`'s also asserts that the construct's verdict
+ * matches this package's predicate for every name here. Add a case when you
+ * change either copy of the rule.
  *
- * Deliberately dependency-free (plain arrays, no vitest import) so the CDK
- * suite can import it across the package boundary without dragging anything
- * along.
+ * Dependency-free (plain arrays, no vitest import) so the CDK suite can import
+ * it across the package boundary.
  */
 /** Names both copies of the rule must ACCEPT. */
 export const VALID_DEPLOYMENT_NAMES = [
@@ -32,9 +28,9 @@ export const VALID_DEPLOYMENT_NAMES = [
     'x.locked',
 ];
 /**
- * Names both copies of the rule must REJECT, each with the reason it exists —
- * every entry is a value git itself would refuse as a ref component, or one
- * that would corrupt the worker's `.env` heredoc.
+ * Names both copies of the rule must REJECT: each is either a value git itself
+ * refuses as a ref component, or one that would corrupt the worker's `.env`
+ * heredoc.
  */
 export const INVALID_DEPLOYMENT_NAMES = [
     ['a slash (would add a ref hierarchy level)', 'team/prod'],

package/dist/operating-mode/deployment-name.d.ts

@@ -1,37 +1,27 @@
 /**
- * Single resolution point for `deploymentName`.
+ * Single resolution point for `deploymentName`, which namespaces the settings
+ * branch (`canopycms-settings-{deploymentName}`) so two CanopyCMS deployments
+ * can share one GitHub repo without fighting over the same orphan branch.
  *
- * `deploymentName` namespaces the settings branch
- * (`canopycms-settings-{deploymentName}`) so two CanopyCMS deployments can
- * share one GitHub repo without both resolving to `canopycms-settings-prod`
- * and fighting over the same orphan branch.
+ * Precedence: `process.env.CANOPYCMS_DEPLOYMENT_NAME` (trimmed, empty ignored),
+ * then `config.deploymentName`, then `modeDefault` (the caller's mode-specific
+ * fallback, e.g. 'prod'/'local').
  *
- * Precedence (highest wins):
- *   1. `process.env.CANOPYCMS_DEPLOYMENT_NAME` (trimmed; empty string ignored)
- *   2. `config.deploymentName`
- *   3. `modeDefault` (the caller's mode-specific fallback, e.g. 'prod'/'local')
- *
- * Env wins over config DELIBERATELY. The env var is stamped per-stack by
- * infrastructure (CDK's `CanopyCmsServiceProps.deploymentName` ->
- * `CANOPYCMS_DEPLOYMENT_NAME`), so it is the value GUARANTEED TO DIFFER
- * between two deployments sharing a repo. `config.deploymentName` lives in
- * the shared repo's `canopycms.config.ts`, so it is the value GUARANTEED TO
- * BE IDENTICAL across both deployments (both Lambdas run the same checked-out
- * config). If config won instead, an adopter who already wrote
- * `deploymentName` into their shared config would find the CDK
- * `deploymentName` prop silently doing nothing — exactly the two-stacks-one-repo
- * case this feature exists to fix.
+ * Env wins over config DELIBERATELY. Infrastructure stamps the env var
+ * per-stack (CDK's `CanopyCmsServiceProps.deploymentName`), so it is the value
+ * GUARANTEED TO DIFFER between two deployments sharing a repo, while
+ * `config.deploymentName` lives in the shared repo's `canopycms.config.ts` and
+ * is GUARANTEED TO BE IDENTICAL across both. If config won, an adopter who had
+ * already written `deploymentName` into their shared config would find the CDK
+ * prop silently doing nothing — the two-stacks-one-repo case this exists to fix.
  */
 /**
- * Exported so `canopycms-cdk`'s suite can assert that its own synth-time copy
- * of this rule (constructs/cms-service.ts) still agrees with this one. The
- * construct deliberately does not import this directly — see
- * `isValidDeploymentName`'s doc comment in cms-service.ts for the real reason
- * (not, as this comment used to say, that the published construct lacks a
- * runtime dependency on `canopycms` — it doesn't: `canopycms` is a
- * non-optional peerDependency there, and the package's own main entry already
- * imports it at runtime). The drift check is therefore test-only — see
- * `deployment-name-fixtures.ts`.
+ * Exported so `canopycms-cdk`'s suite can assert that its own synth-time copy of
+ * this rule (constructs/cms-service.ts) still agrees with this one. The
+ * construct deliberately does not import this directly — see its own
+ * `isValidDeploymentName` doc comment. The drift check is therefore test-only,
+ * over `deployment-name-fixtures.ts`.
+ * @internal Exported for tests.
  */
 export declare const isValidDeploymentName: (name: string) => boolean;
 export declare function resolveDeploymentName(config: {