canopycms 0.0.68-int.98 → 0.1.0

package/dist/github-service.d.ts

@@ -31,7 +31,7 @@ export declare const shouldRetrySecondaryRateLimit: (retryAfter: number, retryCo
  *
  * A deployment using an App constructs the strategy and passes it through here
  * — see `packages/canopycms-cdk/worker/github-app-auth.ts` and
- * `docs/adopter-migration.md` for a hand-written entrypoint.
+ * `CHANGELOG.md` for a hand-written entrypoint.
  */
 export interface OctokitAuthStrategyOptions {
     /**
@@ -57,7 +57,23 @@ export type CanopyOctokitAuthOptions = {
  * for the safety net this doesn't cover: exhausted plugin retries and
  * errors the plugin never sees, like non-403 network failures).
  */
-export declare function createCanopyOctokit(options: CanopyOctokitAuthOptions): Octokit;
+export declare function createCanopyOctokit(options: CanopyOctokitAuthOptions, 
+/**
+ * Where Octokit's own log and the throttle's warnings go: the GitHub gateway passes its own,
+ * which scrubs and escapes. Without one, Octokit logs to the console as it does by default.
+ */
+logger?: {
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}, 
+/**
+ * Told of every request's `authorization` header just before it is sent, which is the only
+ * place the FINAL header is visible: a token an auth strategy minted or rotated shows up here
+ * before anything has logged or thrown it. The GitHub gateway registers it for scrubbing.
+ */
+observe?: {
+    onAuthorization: (authorization: string) => void;
+}): Octokit;
 export interface GitHubServiceOptions {
     token: string;
     owner: string;
@@ -95,6 +111,8 @@ export interface CreateOrUpdatePullRequestParams {
     mergeSectionIntoBody?: boolean;
     /** Forwarded to all GitHub requests (worker task-timeout abort). */
     signal?: AbortSignal;
+    /** Where its warnings go (default `canopyLogWarn`): the GitHub gateway passes its own. */
+    warn?: (...args: unknown[]) => void;
 }
 /**
  * Create or update a pull request, idempotently: an open PR from head to base
@@ -112,6 +130,25 @@ export declare function createOrUpdatePullRequest(params: CreateOrUpdatePullRequ
     url: string;
     created: boolean;
 }>;
+/**
+ * Whether a `git.deleteRef` failure means the branch is already gone from GitHub, so the delete
+ * has nothing left to do. A missing ref is a 422 "Reference does not exist"; the message check
+ * matters because a 422 also refuses deleting the default branch. A 404 counts too, though it
+ * can also mean the repo is not visible to the credential.
+ */
+export declare function isRefAlreadyGoneError(err: unknown): boolean;
+/**
+ * Whether a PR create failed because the head branch has no commits its base lacks. GitHub
+ * answers 422 "Validation Failed" with the reason in `response.data.errors[].message`, which
+ * Octokit also folds into `err.message`. Other 422s (a duplicate PR, an unknown base) never match.
+ */
+export declare function isNoCommitsBetweenError(err: unknown): boolean;
+/**
+ * The `authorization` header of a request's headers: a plain object (lower-case keys, as Octokit
+ * sends them), a `Headers`, or a list of pairs.
+ * @internal Exported for tests.
+ */
+export declare function authorizationOf(headers: HeadersInit | undefined): string | undefined;
 export declare class GitHubService {
     private octokit;
     private owner;

package/dist/github-service.js

@@ -8,6 +8,7 @@ import { getErrorMessage } from './utils/error.js';
 // is plain console. See utils/logger.ts.
 import { canopyLogWarn } from './utils/logger.js';
 import { mergePrSection } from './submission-attribution.js';
+import { baseBranchOf } from './utils/base-branch.js';
 const ThrottledOctokit = Octokit.plugin(throttling);
 /**
  * Retry primary rate limits at most twice and only for short waits; beyond
@@ -30,25 +31,64 @@ export const shouldRetrySecondaryRateLimit = (retryAfter, retryCount) => retryCo
  * for the safety net this doesn't cover: exhausted plugin retries and
  * errors the plugin never sees, like non-403 network failures).
  */
-export function createCanopyOctokit(options) {
+export function createCanopyOctokit(options, 
+/**
+ * Where Octokit's own log and the throttle's warnings go: the GitHub gateway passes its own,
+ * which scrubs and escapes. Without one, Octokit logs to the console as it does by default.
+ */
+logger, 
+/**
+ * Told of every request's `authorization` header just before it is sent, which is the only
+ * place the FINAL header is visible: a token an auth strategy minted or rotated shows up here
+ * before anything has logged or thrown it. The GitHub gateway registers it for scrubbing.
+ */
+observe) {
+    const warn = logger?.warn ?? canopyLogWarn;
     // Pick the two auth fields out EXPLICITLY, never spread: `baseUrl`,
     // `request`, `log` and `userAgent` are all live `OctokitOptions`, and a
     // non-literal argument slips past TypeScript's excess-property check. The
     // contract is "our Octokit, authenticated the way you say", not "configured
-    // however you like".
+    // however you like". The one `request` we set is `observe`'s fetch: an auth
+    // strategy's hook is the innermost `request` wrap, so a hook added after
+    // construction runs before it sets the header. `@octokit/auth-app`'s hook
+    // mints through the `request` it wraps (`request.defaults`), so the JWT of a
+    // mint an Octokit request triggers passes the fetch too; a mint outside one
+    // (`mintInstallationToken`) uses auth-app's own `request`, and does not.
     const auth = 'authStrategy' in options
         ? { authStrategy: options.authStrategy, auth: options.auth }
         : { auth: options.auth };
     return new ThrottledOctokit({
         ...auth,
+        ...(observe === undefined
+            ? {}
+            : {
+                request: {
+                    fetch: (url, init) => {
+                        const authorization = authorizationOf(init?.headers);
+                        if (authorization !== undefined)
+                            observe.onAuthorization(authorization);
+                        return globalThis.fetch(url, init);
+                    },
+                },
+            }),
+        ...(logger === undefined
+            ? {}
+            : {
+                log: {
+                    debug: () => undefined,
+                    info: () => undefined,
+                    warn: logger.warn,
+                    error: logger.error,
+                },
+            }),
         throttle: {
             onRateLimit: (retryAfter, requestOptions, _octokit, retryCount) => {
-                canopyLogWarn(`CanopyCMS: GitHub primary rate limit hit for ${requestOptions.method} ${requestOptions.url} ` +
+                warn(`CanopyCMS: GitHub primary rate limit hit for ${requestOptions.method} ${requestOptions.url} ` +
                     `(retryAfter=${retryAfter}s, retryCount=${retryCount})`);
                 return shouldRetryRateLimit(retryAfter, retryCount);
             },
             onSecondaryRateLimit: (retryAfter, requestOptions, _octokit, retryCount) => {
-                canopyLogWarn(`CanopyCMS: GitHub secondary rate limit hit for ${requestOptions.method} ${requestOptions.url} ` +
+                warn(`CanopyCMS: GitHub secondary rate limit hit for ${requestOptions.method} ${requestOptions.url} ` +
                     `(retryAfter=${retryAfter}s, retryCount=${retryCount})`);
                 return shouldRetrySecondaryRateLimit(retryAfter, retryCount);
             },
@@ -68,6 +108,7 @@ export function createCanopyOctokit(options) {
  */
 export async function createOrUpdatePullRequest(params) {
     const { octokit, owner, repo, head, base, title, body, markReadyIfDraft, signal } = params;
+    const warn = params.warn ?? canopyLogWarn;
     const mergeSection = params.mergeSectionIntoBody === true;
     // CONDITIONAL spread: with no signal, the request objects below carry no
     // `request` key at all (github-service.test.ts asserts on their exact shape).
@@ -87,7 +128,7 @@ export async function createOrUpdatePullRequest(params) {
         let existing = existingPRs.data[0];
         if (existingPRs.data.length > 1) {
             existing = [...existingPRs.data].sort((a, b) => new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime())[0];
-            canopyLogWarn(`CanopyCMS: Found ${existingPRs.data.length} open PRs for ${head} -> ${base}; updating the most recently updated (#${existing.number})`);
+            warn(`CanopyCMS: Found ${existingPRs.data.length} open PRs for ${head} -> ${base}; updating the most recently updated (#${existing.number})`);
         }
         await octokit.pulls.update({
             owner,
@@ -126,7 +167,7 @@ export async function createOrUpdatePullRequest(params) {
                 });
             }
             catch (err) {
-                canopyLogWarn(`CanopyCMS: Failed to convert PR #${existing.number} to ready for review (the PR update itself succeeded; continuing):`, getErrorMessage(err));
+                warn(`CanopyCMS: Failed to convert PR #${existing.number} to ready for review (the PR update itself succeeded; continuing):`, getErrorMessage(err));
             }
         }
         return { number: existing.number, url: existing.html_url, created: false };
@@ -142,6 +183,59 @@ export async function createOrUpdatePullRequest(params) {
     });
     return { number: pr.data.number, url: pr.data.html_url, created: true };
 }
+/**
+ * Whether a `git.deleteRef` failure means the branch is already gone from GitHub, so the delete
+ * has nothing left to do. A missing ref is a 422 "Reference does not exist"; the message check
+ * matters because a 422 also refuses deleting the default branch. A 404 counts too, though it
+ * can also mean the repo is not visible to the credential.
+ */
+export function isRefAlreadyGoneError(err) {
+    if (!(err instanceof Error) || !('status' in err))
+        return false;
+    const { status } = err;
+    if (status === 404)
+        return true;
+    return status === 422 && /reference does not exist/i.test(err.message);
+}
+const NO_COMMITS_BETWEEN = /^No commits between /;
+/**
+ * Whether a PR create failed because the head branch has no commits its base lacks. GitHub
+ * answers 422 "Validation Failed" with the reason in `response.data.errors[].message`, which
+ * Octokit also folds into `err.message`. Other 422s (a duplicate PR, an unknown base) never match.
+ */
+export function isNoCommitsBetweenError(err) {
+    if (!(err instanceof Error) || !('status' in err) || err.status !== 422)
+        return false;
+    const data = 'response' in err ? err.response?.data : null;
+    const errors = typeof data === 'object' && data !== null && 'errors' in data ? data.errors : undefined;
+    if (Array.isArray(errors)) {
+        return errors.some((e) => typeof e === 'object' &&
+            e !== null &&
+            'message' in e &&
+            typeof e.message === 'string' &&
+            NO_COMMITS_BETWEEN.test(e.message));
+    }
+    return /"message":"No commits between /.test(err.message);
+}
+/**
+ * The `authorization` header of a request's headers: a plain object (lower-case keys, as Octokit
+ * sends them), a `Headers`, or a list of pairs.
+ * @internal Exported for tests.
+ */
+export function authorizationOf(headers) {
+    if (headers === undefined)
+        return undefined;
+    if (headers instanceof Headers)
+        return headers.get('authorization') ?? undefined;
+    if (Array.isArray(headers)) {
+        return headers.find(([name]) => name.toLowerCase() === 'authorization')?.[1];
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === 'authorization' && typeof value === 'string')
+            return value;
+    }
+    return undefined;
+}
 export class GitHubService {
     constructor(options) {
         this.octokit = createCanopyOctokit({ auth: options.token });
@@ -311,7 +405,7 @@ export const createGitHubService = (config, remoteUrl) => {
             token,
             owner,
             repo,
-            baseBranch: config.defaultBaseBranch ?? 'main',
+            baseBranch: baseBranchOf(config),
         });
     }
     catch (err) {

package/dist/http/handler.js

@@ -1,10 +1,14 @@
 import { jsonResponse, isCanopyBinaryResponse } from './types.js';
 import { workerNotReadyResponse } from './worker-not-ready.js';
+import { SchemaUnavailableError } from '../schema/schema-unavailable-error.js';
 import { createCanopyRouter } from './router.js';
 import { assertAuthPluginAllowedForMode } from '../auth/plugin.js';
 import { createCanopyServices } from '../services.js';
+import { recordConfiguredSparseCone } from '../branch-sparse.js';
+import { recordServedSchemaRegistry } from '../schema-registry-record.js';
 import { loadBranchContext, BranchWorkspaceManager } from '../branch-workspace.js';
 import { BranchMetadataCorruptError } from '../branch-metadata.js';
+import { BRANCH_METADATA_CORRUPT_MESSAGE } from '../branch-metadata-error.js';
 import { resolveCanopyUser } from '../resolve-canopy-user.js';
 import { authResultToCanopyUser } from '../user.js';
 import { isAdmin } from '../authorization/index.js';
@@ -14,13 +18,18 @@ import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../uti
 // canopyLogError, not console.error: this is shared code and not guaranteed to
 // stay out of the worker's runtime import closure, so new log lines here go
 // through the indirection (utils/logger.ts).
-import { canopyLogError } from '../utils/logger.js';
+import { canopyLogError, canopyLogWarn } from '../utils/logger.js';
+import { EDITOR_MODE_HEADER, EDITOR_MODE_MISMATCH_STATUS, editorModeMismatchMessage, parseEditorModeHeader, } from '../operating-mode/editor-mode-check.js';
 import { runWithRequestTiming, setRequestTimingRoute, timeRequestPhase, } from '../utils/request-timing.js';
+import { baseBranchOf } from '../utils/base-branch.js';
+import { SYSTEM_USER_ID } from '../system-users.js';
 const buildContext = async (options) => {
     const services = options.services ?? (options.config ? await createCanopyServices(options.config) : undefined);
     if (!services) {
         throw new Error('CanopyCMS: config or services is required');
     }
+    await recordConfiguredSparseCone(services.config);
+    await recordServedSchemaRegistry(services.config, services.entrySchemaRegistry);
     const operatingMode = services.config.mode;
     // Derived from the strategy, which resolves deploymentName; a literal here
     // would miss a deployment-namespaced settings branch (say canopycms-settings-acme).
@@ -41,7 +50,7 @@ const buildContext = async (options) => {
             }
             // Read from services.config per-request, not a captured variable, so a
             // refreshActiveBranch() update takes effect immediately.
-            const baseBranch = services.config.defaultBaseBranch ?? 'main';
+            const baseBranch = baseBranchOf(services.config);
             const activeBranch = services.config.defaultActiveBranch ?? baseBranch;
             const shouldAutoCreate = clientOperatingStrategy(operatingMode).supportsBranching() &&
                 (branch === baseBranch || branch === activeBranch);
@@ -50,7 +59,7 @@ const buildContext = async (options) => {
                 const context = await manager.openOrCreateBranch({
                     branchName: branch,
                     mode: operatingMode,
-                    createdBy: 'canopycms-system',
+                    createdBy: SYSTEM_USER_ID,
                 });
                 if (opts?.loadSchema && context) {
                     const contentRootName = services.config.contentRoot || 'content';
@@ -84,6 +93,11 @@ const parseQueryParams = (url) => {
         return {};
     }
 };
+/**
+ * The answer to a request with no accepted session. The body's `status: 401` is what the client
+ * detects sign-out from, so it stays 401 whatever HTTP status `unauthenticatedStatus` picks.
+ */
+const unauthenticatedResponse = (config, error) => jsonResponse({ ok: false, status: 401, error: error ?? 'Unauthorized' }, config.unauthenticatedStatus ?? 401);
 /**
  * The core handler behind every Canopy API request. A framework adapter
  * (Next.js, Express, Hono) converts its request to a CanopyRequest, extracts
@@ -95,6 +109,26 @@ export function createCanopyRequestHandler(options) {
     const mode = options.services?.config.mode ?? options.config?.mode;
     assertAuthPluginAllowedForMode(options.authPlugin, mode);
     const router = createCanopyRouter();
+    // Before auth, because a dev bundle against a prod server cannot authenticate: see
+    // editor-mode-check.ts.
+    let modeMismatchLogged = false;
+    const editorModeMismatchResponse = (req) => {
+        const editorMode = parseEditorModeHeader(req.header(EDITOR_MODE_HEADER));
+        if (!mode || !editorMode || editorMode === mode)
+            return null;
+        if (!modeMismatchLogged) {
+            modeMismatchLogged = true;
+            canopyLogWarn(`CanopyCMS: an editor built with NEXT_PUBLIC_CANOPY_MODE="${editorMode}" called this server, ` +
+                `which runs in "${mode}" mode. Its requests are refused with ${EDITOR_MODE_MISMATCH_STATUS} ` +
+                `until the editor is rebuilt with NEXT_PUBLIC_CANOPY_MODE=${mode}. Logged once per request handler.`);
+        }
+        return jsonResponse({
+            ok: false,
+            status: EDITOR_MODE_MISMATCH_STATUS,
+            code: 'EDITOR_MODE_MISMATCH',
+            error: editorModeMismatchMessage(editorMode),
+        }, EDITOR_MODE_MISMATCH_STATUS);
+    };
     // Built once and reused across requests in the same warm container. On
     // rejection (transient cold start, EFS not yet mounted) the cache is cleared
     // (API-H3) so the NEXT request retries instead of replaying the rejection.
@@ -119,6 +153,9 @@ export function createCanopyRequestHandler(options) {
             return jsonResponse({ ok: false, status: 404, error: 'Not found' }, 404);
         }
         setRequestTimingRoute(match.pattern.join('/') || '(malformed path)');
+        const modeMismatch = editorModeMismatchResponse(req);
+        if (modeMismatch)
+            return modeMismatch;
         const apiCtx = await timeRequestPhase('context', getContext);
         // In dev mode, re-check if the developer switched git branches
         await timeRequestPhase('refreshBranch', () => apiCtx.services.refreshActiveBranch());
@@ -127,13 +164,30 @@ export function createCanopyRequestHandler(options) {
         // any workspace provisioning below, so they can neither trigger expensive
         // git operations nor read provisioning error details.
         if (!authResult.success || !authResult.user) {
-            return jsonResponse({ ok: false, status: 401, error: authResult.error ?? 'Unauthorized' }, 401);
+            return unauthenticatedResponse(apiCtx.services.config, authResult.error);
+        }
+        // Whether a worker's recorded failure may be named in a not-ready 503: admins only, as in
+        // System health. With no remote there are no internal groups, so this is the bootstrap
+        // admins, and /admin is behind the same 503, so this answer is where they read it.
+        const mayReadWorkerFailure = () => isAdmin(authResultToCanopyUser(authResult, apiCtx.services.bootstrapAdminIds).groups);
+        // A prod base branch still pending since creation resolves here, once the
+        // worker has created the remote; until then this answers the not-ready 503.
+        try {
+            await timeRequestPhase('baseBranch', () => apiCtx.services.resolvePendingBaseBranch());
+        }
+        catch (err) {
+            const notReady = workerNotReadyResponse(err, {
+                workerFailureDetail: mayReadWorkerFailure(),
+            });
+            if (notReady)
+                return notReady;
+            throw err;
         }
         // Provision the base/active branch workspace on first request, so the many
         // endpoints that assume it exists (registry reads and the like) don't return
         // confusing empty results on a cold start. A real provisioning error fails
         // loudly here rather than surprising a later handler.
-        const baseBranch = apiCtx.services.config.defaultBaseBranch ?? 'main';
+        const baseBranch = baseBranchOf(apiCtx.services.config);
         try {
             await apiCtx.getBranchContext(baseBranch);
         }
@@ -151,7 +205,9 @@ export function createCanopyRequestHandler(options) {
                 // (authenticated) client. Credentials, which git errors can embed, are
                 // redacted even from the server logs.
                 console.error(`CanopyCMS: Failed to provision workspace for base branch '${baseBranch}': ${redactCredentials(message)}`);
-                const notReady = workerNotReadyResponse(err);
+                const notReady = workerNotReadyResponse(err, {
+                    workerFailureDetail: mayReadWorkerFailure(),
+                });
                 if (notReady)
                     return notReady;
                 return jsonResponse({
@@ -182,7 +238,9 @@ export function createCanopyRequestHandler(options) {
             // No remote means no settings workspace, so /admin cannot load either:
             // the worker has not created the remote yet, so every caller gets the
             // not-ready 503, bootstrap admins included.
-            const notReady = workerNotReadyResponse(err);
+            const notReady = workerNotReadyResponse(err, {
+                workerFailureDetail: mayReadWorkerFailure(),
+            });
             if (notReady)
                 return notReady;
             // Same trade as the base-branch degradation above: /admin is the recovery
@@ -220,7 +278,7 @@ export function createCanopyRequestHandler(options) {
             }
         }
         if (user.type === 'anonymous') {
-            return jsonResponse({ ok: false, status: 401, error: authResult.error ?? 'Unauthorized' }, 401);
+            return unauthenticatedResponse(apiCtx.services.config, authResult.error);
         }
         const queryParams = parseQueryParams(req.url);
         const mergedParams = { ...queryParams, ...match.params };
@@ -274,10 +332,17 @@ export function createCanopyRequestHandler(options) {
         catch (err) {
             // Last-resort boundary (API-C1): see handleRequest's doc comment above.
             const message = getErrorMessage(err);
-            console.error('CanopyCMS: Unhandled error in API request handler:', message);
+            // Not per refused request: branch-schema-cache.ts logs each missing schema once per process.
+            if (!(err instanceof SchemaUnavailableError)) {
+                console.error('CanopyCMS: Unhandled error in API request handler:', message);
+            }
             const notReady = workerNotReadyResponse(err);
             if (notReady)
                 return notReady;
+            // Its message is a path and a parse error, neither of which helps an editor.
+            if (err instanceof BranchMetadataCorruptError) {
+                return jsonResponse({ ok: false, status: 500, error: BRANCH_METADATA_CORRUPT_MESSAGE }, 500);
+            }
             return jsonResponse({ ok: false, status: 500, error: sanitizeErrorMessage(message) }, 500);
         }
     };

package/dist/http/types.d.ts

@@ -37,6 +37,8 @@ export interface CanopyBinaryResponse {
         contentDisposition?: string;
         cacheControl?: string;
         etag?: string;
+        /** Redirect target, for a 3xx `status`; `body` is then empty. */
+        location?: string;
     };
 }
 export declare function jsonResponse<T>(body: T, status?: number, headers?: Record<string, string>): CanopyResponse<T>;

package/dist/http/worker-not-ready.d.ts

@@ -2,8 +2,13 @@ import type { ApiResponse } from '../api/types.js';
 import { type CanopyResponse } from './types.js';
 export declare const WORKER_NOT_READY_MESSAGE = "CMS worker not ready \u2014 it may still be starting. Try again in a minute; if this persists, ask an admin to check the CMS worker.";
 /**
- * The 503 for a request that hit {@link RemoteNotReadyError}, or `undefined`
- * for any other error. The single mapping point for the core handler, the AI route and
- * every framework adapter's backstop, so the message and `Retry-After` cannot diverge.
+ * The 503 for a request that hit {@link RemoteNotReadyError},
+ * {@link BranchProvisioningBusyError} or {@link SchemaUnavailableError}, or `undefined` for any
+ * other error. Retriable (with `Retry-After`) unless the worker recorded that its latest start
+ * failed; `workerFailureDetail` names that failure, for an authenticated admin only. The single
+ * mapping point for the core handler, the AI route and every framework adapter's backstop, so
+ * the message and `Retry-After` cannot diverge.
  */
-export declare function workerNotReadyResponse(err: unknown): CanopyResponse<ApiResponse> | undefined;
+export declare function workerNotReadyResponse(err: unknown, options?: {
+    workerFailureDetail?: boolean;
+}): CanopyResponse<ApiResponse> | undefined;

package/dist/http/worker-not-ready.js

@@ -1,17 +1,70 @@
+import { BranchProvisioningBusyError } from '../branch-provisioning.js';
 import { RemoteNotReadyError } from '../git-manager.js';
+import { sanitizeErrorMessage } from '../utils/error.js';
+import { SchemaUnavailableError } from '../schema/schema-unavailable-error.js';
 import { jsonResponse } from './types.js';
 /** Seconds a client should wait before retrying while the worker boots. */
 const RETRY_AFTER_SECONDS = '30';
+/**
+ * Seconds before retrying an unavailable entry type. The editor's client never resends a 503
+ * (api/client.ts resends only a 429), so this informs other clients; the editor tells authors to
+ * reload.
+ */
+const SCHEMA_RETRY_AFTER_SECONDS = '60';
 export const WORKER_NOT_READY_MESSAGE = 'CMS worker not ready — it may still be starting. Try again in a minute; if this persists, ask an admin to check the CMS worker.';
 /**
- * The 503 for a request that hit {@link RemoteNotReadyError}, or `undefined`
- * for any other error. The single mapping point for the core handler, the AI route and
- * every framework adapter's backstop, so the message and `Retry-After` cannot diverge.
+ * An AWS account id, as twelve digits or the console's dddd-dddd-dddd. A secret's ARN in a
+ * worker error carries one; the region and names around it are what an admin needs.
+ */
+const ACCOUNT_ID = /(?<![0-9A-Za-z-])[0-9]{4}-[0-9]{4}-[0-9]{4}(?![0-9A-Za-z-])|(?<![0-9A-Za-z])[0-9]{12}(?![0-9A-Za-z])/g;
+/**
+ * The 503 for a worker that recorded a startup failure. The worker's message, sanitized and with
+ * account ids masked, is included only with `detail`: it names secrets, paths and the repository,
+ * so it is for an admin the handler has authenticated, never anyone else.
+ */
+function workerFailureResponse(failure, detail) {
+    const named = detail
+        ? ` (${failure.at}): ${sanitizeErrorMessage(failure.message).replace(ACCOUNT_ID, (id) => id.replace(/[0-9]/g, '*'))}`
+        : '.';
+    if (failure.current) {
+        return jsonResponse({
+            ok: false,
+            status: 503,
+            error: `The CMS worker failed to start${named} An admin needs to fix the worker; retrying will not help until then.`,
+            code: 'WORKER_FAILED',
+        }, 503);
+    }
+    return jsonResponse({
+        ok: false,
+        status: 503,
+        error: detail
+            ? `CMS worker not ready — it is starting again after a failure${named} Try again in a minute; if this persists, ask an admin to check the CMS worker.`
+            : WORKER_NOT_READY_MESSAGE,
+    }, 503, { 'Retry-After': RETRY_AFTER_SECONDS });
+}
+/**
+ * The 503 for a request that hit {@link RemoteNotReadyError},
+ * {@link BranchProvisioningBusyError} or {@link SchemaUnavailableError}, or `undefined` for any
+ * other error. Retriable (with `Retry-After`) unless the worker recorded that its latest start
+ * failed; `workerFailureDetail` names that failure, for an authenticated admin only. The single
+ * mapping point for the core handler, the AI route and every framework adapter's backstop, so
+ * the message and `Retry-After` cannot diverge.
  */
-export function workerNotReadyResponse(err) {
-    if (!(err instanceof RemoteNotReadyError))
+export function workerNotReadyResponse(err, options = {}) {
+    if (err instanceof SchemaUnavailableError) {
+        return jsonResponse({ ok: false, status: 503, error: err.message, code: 'SCHEMA_UNAVAILABLE' }, 503, { 'Retry-After': SCHEMA_RETRY_AFTER_SECONDS });
+    }
+    if (err instanceof RemoteNotReadyError && err.workerStartupFailure) {
+        return workerFailureResponse(err.workerStartupFailure, options.workerFailureDetail === true);
+    }
+    const message = err instanceof RemoteNotReadyError
+        ? WORKER_NOT_READY_MESSAGE
+        : err instanceof BranchProvisioningBusyError
+            ? err.message
+            : undefined;
+    if (message === undefined)
         return undefined;
-    return jsonResponse({ ok: false, status: 503, error: WORKER_NOT_READY_MESSAGE }, 503, {
+    return jsonResponse({ ok: false, status: 503, error: message }, 503, {
         'Retry-After': RETRY_AFTER_SECONDS,
     });
 }

package/dist/index.d.ts

@@ -15,3 +15,5 @@ export type { ListEntriesItem, ListEntriesOptions } from './content-listing.js';
 export { assetUrl, assetSrcSet } from './assets/asset-url.js';
 export type { AssetRef, AssetUrlOptions } from './assets/asset-url.js';
 export type { OutputFormat, CropRect, TransformDirectives } from './assets/transform-directives.js';
+export { fieldAttrs, scopeFieldProps } from './editor/field-props.js';
+export type { FieldAttrs, FieldProps } from './editor/field-props.js';

package/dist/index.js

@@ -15,3 +15,6 @@ export { isCanopyRequest, isHeadersLike, extractHeaders, validateAuthContext, }
 // 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';
+// Preview field marks — pure, so server components call them too (`canopycms/preview` is
+// 'use client'); see editor/field-props.ts.
+export { fieldAttrs, scopeFieldProps } from './editor/field-props.js';

package/dist/item-keys.d.ts

@@ -0,0 +1,46 @@
+import type { BlockFieldConfig, FieldConfig, ObjectFieldConfig } from './config/index.js';
+/**
+ * The key each object-list item and block carries in content, naming that item among its list's
+ * items for as long as it exists: a move or an edit keeps it, a copy gets a new one. Field comment
+ * threads name the items on their path by it (`CommentThread.itemKeys`). Beside `template` on a
+ * block, never inside its `value`; a schema may not define a field of this name.
+ *
+ * Dependency-free: the editor and the server both use this module.
+ */
+export declare const ITEM_KEY = "_key";
+/** A usable item key: 1-64 letters, digits, `_` or `-`, starting with a letter or digit. */
+export declare const isItemKey: (value: unknown) => value is string;
+/** A new random item key: 12 Base58 characters. */
+export declare function mintItemKey(): string;
+/**
+ * How `withItemKeys` keys an item that lacks a usable key, or repeats one an earlier item of its
+ * list holds:
+ * - `content`: from a hash of the item, so every reader and writer of the same file names it
+ *   alike before a save writes the key down, and an item added to the file later never inherits
+ *   a key a removed one held unless it is the same content;
+ * - `random`: a fresh key;
+ * - `fresh`: a fresh key for EVERY item, keyed or not, as a copy needs.
+ */
+export type ItemKeyFill = 'content' | 'random' | 'fresh';
+type ListField = ObjectFieldConfig | BlockFieldConfig;
+/**
+ * `data` with every object-list item and block keyed, each unique in its list, nested lists
+ * included; the same object when nothing needed a key. A usable key is kept unless `fill` is
+ * `fresh`.
+ */
+export declare function withItemKeys(fields: readonly FieldConfig[], data: Record<string, unknown>, fill: ItemKeyFill): Record<string, unknown>;
+/** `item`, a copy about to join `field`'s list, with fresh keys for it and every item inside it. */
+export declare function withFreshItemKeys<T>(field: ListField, item: T): T;
+/**
+ * The keys of the list items on `canopyPath` in `value`, outermost first: what a new field thread
+ * stores to name them. Undefined when an item on the path has no usable key or the path isn't
+ * there.
+ */
+export declare function itemKeysOnPath(fields: readonly FieldConfig[], value: Record<string, unknown>, canopyPath: string): string[] | undefined;
+/**
+ * Where a field thread made at `canopyPath` on the items named by `itemKeys` is in `value` now:
+ * its path with each index replaced by that item's current one, or `null` when one of the items
+ * is gone. A path with no keys (one through no list) is returned as it is.
+ */
+export declare function resolveThreadPath(fields: readonly FieldConfig[], value: Record<string, unknown>, canopyPath: string, itemKeys: readonly string[] | undefined): string | null;
+export {};